Run Utils


Spinning Up ships with a tool called ExperimentGrid for making hyperparameter ablations easier.This is based on (but simpler than)the rllab toolcalled VariantGenerator.

class spinup.utils.run_utils. ExperimentGrid ( name='' ) [source]

Tool for running many experiments given hyperparameter ranges.

add ( key, vals, shorthand=None, in_name=False ) [source]

Add a parameter (key) to the grid config,with potential values (vals).

By default,if a shorthand isn't given,one is automatically generatedfrom the key using the first three letters of each colon-separatedterm.To disable this behavior,changeDEFAULT_SHORTHANDin thespinup/user_config.pyfile toFalse.

  • key(string) – Name of parameter.
  • vals(valueorlist of values) – Allowed values of parameter.
  • shorthand(string) – Optional,shortened name of parameter.Forexample,maybe the parametersteps_per_epochis shortenedtosteps.
  • in_name(bool) – When constructing variant names,force theinclusion of this parameter into the name.
print ( ) [source]

Print a helpful report about the experiment grid.

run ( thunk, num_cpu=1, data_dir=None, datestamp=False ) [source]

Run each variant in the grid with function ‘thunk'.

Note: ‘thunk' must be either a callable function,or a string.If it isa string,it must be the name of a parameter whose values are allcallable functions.

Usescall_experimentto actually launch each experiment,and giveseach variant a name usingself.variant_name().

Maintenance note: the args for should track closelyto the args for call_experiment.However,seedis omitted becausewe presume the user may add it as a parameter in the grid.

variant_name ( variant ) [source]

Given a variant (dict of valid param/value pairs),make an exp_name.

A variant's name is constructed as the grid name (if you've given itone),plus param names (or shorthands if available) and valuesseparated by underscores.

Note: ifseedis a parameter,it is not included in the name.

variants ( ) [source]

Makes a list of dicts,where each dict is a valid config in the grid.

There is special handling for variant parameters whose names takethe form


The colons are taken to indicate that these parameters shouldhave a nested dict,if there are two params,

Key Val
'base:param:a' 1
'base:param:b' 2

the variant dict will have the structure

variant = {
    base: {
        param : {
            a : 1,
            b : 2

Calling Experiments

spinup.utils.run_utils. call_experiment ( exp_name, thunk, seed=0, num_cpu=1, data_dir=None, datestamp=False, **kwargs ) [source]

Run a function (thunk) with hyperparameters (kwargs),plus configuration.

This wraps a few pieces of functionality which are useful when you wantto run many experiments in sequence,including logger configuration andsplitting into multiple processes for MPI.

There's also a SpinningUp-specific convenience added into executing thethunk: ifenv_nameis one of the kwargs passed to call_experiment,it'sassumed that the thunk accepts an argument calledenv_fn,and thattheenv_fnshould make a gym environment with the givenenv_name.

The way the experiment is actually executed is slightly complicated: thefunction is serialized to a string,and thenrun_entrypoint.pyisexecuted in a subprocess call with the serialized string as an argument.run_entrypoint.pyunserializes the function call and executes it.We choose to do it this way—instead of just calling the functiondirectly here—to avoid leaking state between successive experiments.

  • exp_name(string) – Name for experiment.
  • thunk(callable) – A python function.
  • seed(int) – Seed for random number generators.
  • num_cpu(int) – Number of MPI processes to split into.Also accepts‘auto',which will set up as many procs as there are cpus onthe machine.
  • data_dir(string) – Used in configuring the logger,to decide whereto store experiment results.Note: if left as None,data_dir willdefault toDEFAULT_DATA_DIRfromspinup/
  • **kwargs– All kwargs to pass to thunk.
spinup.utils.run_utils. setup_logger_kwargs ( exp_name, seed=None, data_dir=None, datestamp=False ) [source]

Sets up the output_dir for a logger and returns a dict for logger kwargs.

If no seed is given and datestamp is false,

output_dir = data_dir/exp_name

If a seed is given and datestamp is false,

output_dir = data_dir/exp_name/exp_name_s[seed]

If datestamp is true,amend to

output_dir = data_dir/YY-MM-DD_exp_name/YY-MM-DD_HH-MM-SS_exp_name_s[seed]

You can force datestamp=True by settingFORCE_DATESTAMP=Trueinspinup/

  • exp_name(string) – Name for experiment.
  • seed(int) – Seed for random number generators used by experiment.
  • data_dir(string) – Path to folder where results should be saved.Default is theDEFAULT_DATA_DIRinspinup/
  • datestamp(bool) – Whether to include a date and timestamp in thename of the save directory.

logger_kwargs,a dict containing output_dir and exp_name.