garage.experiment.experiment module

Tools for running experiments with Garage.

class ExperimentContext(*, snapshot_dir, snapshot_mode, snapshot_gap)[source]

Bases: object

Context in which an experiment is being run.

Currently, this class implements the same interface as SnapshotConfig, but it will be extended in the future.

Parameters:
  • snapshot_dir (str) – The full directory to put snapshots in.
  • snapshot_mode (str) – Policy for which snapshots to keep (or make at all). Can be either “all” (all iterations will be saved), “last” (only the last iteration will be saved), “gap” (every snapshot_gap iterations are saved), or “none” (do not save snapshots).
  • snapshot_gap (int) – Gap between snapshot iterations. Waits this number of iterations before taking another snapshot.
class ExperimentTemplate(*, function, log_dir, name, prefix, snapshot_mode, snapshot_gap, archive_launch_repo, name_parameters, use_existing_dir)[source]

Bases: object

Creates experiment log directories and runs an experiment.

This class should only be created by calling garage.wrap_experiment. Generally, it’s used as a decorator like this:

@wrap_experiment(snapshot_mode=’all’) def my_experiment(ctxt, seed, lr=0.5):

…

my_experiment(seed=1)

Even though this class could be implemented as a closure in wrap_experiment(), it’s more readable (and easier to pickle) implemented as a class.

Note that the full path that will be created is f’{data}/local/{prefix}/{name}’.

Parameters:
  • function (callable or None) – The experiment function to wrap.
  • log_dir (str or None) – The full log directory to log to. Will be computed from name if omitted.
  • name (str or None) – The name of this experiment template. Will be filled from the wrapped function’s name if omitted.
  • prefix (str) – Directory under data/local in which to place the experiment directory.
  • snapshot_mode (str) – Policy for which snapshots to keep (or make at all). Can be either “all” (all iterations will be saved), “last” (only the last iteration will be saved), “gap” (every snapshot_gap iterations are saved), or “none” (do not save snapshots).
  • snapshot_gap (int) – Gap between snapshot iterations. Waits this number of iterations before taking another snapshot.
  • archive_launch_repo (bool) – Whether to save an archive of the repository containing the launcher script. This is a potentially expensive operation which is useful for ensuring reproducibility.
  • name_parameters (str or None) – Parameters to insert into the experiment name. Should be either None (the default), ‘all’ (all parameters will be used), or ‘passed’ (only passed parameters will be used). The used parameters will be inserted in the order they appear in the function definition.
  • use_existing_dir (bool) – If true, (re)use the directory for this experiment, even if it already contains data.
class LogEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]

Bases: json.encoder.JSONEncoder

Encoder to be used as cls in json.dump.

default(o)[source]

Perform JSON encoding.

Parameters:o (object) – Object to encode.
Returns:Object encoded in JSON.
Return type:str
dump_json(filename, data)[source]

Dump a dictionary to a file in JSON format.

Parameters:
  • filename (str) – Filename for the file.
  • data (dict) – Data to save to file.
get_metadata()[source]

Get metadata about the main script.

The goal of this function is to capture the additional information needed to re-run an experiment, assuming that the launcher script that started the experiment is located in a clean git repository.

Returns:
  • Absolute path to root directory of launcher’s git repo.
  • Directory containing: * githash (str): Hash of the git revision of the repo the
    experiment was started from. “-dirty” will be appended to this string if the repo has uncommitted changes. May not be present if the main script is not in a git repo.
    • launcher (str): Relative path to the main script from the base of
      the repo the experiment was started from. If the main script was not started from a git repo, this will instead be an absolute path to the main script.
Return type:tuple[str, dict[str, str]]
make_launcher_archive(*, git_root_path, log_dir)[source]

Saves an archive of the launcher’s git repo to the log directory.

Parameters:
  • git_root_path (str) – Absolute path to git repo to archive.
  • log_dir (str) – Absolute path to the log directory.
run_experiment(method_call=None, batch_tasks=None, exp_prefix='experiment', exp_name=None, log_dir=None, script='garage.experiment.experiment_wrapper', python_command='python', dry=False, env=None, variant=None, force_cpu=False, pre_commands=None, **kwargs)[source]

Serialize the method call and run the experiment using specified mode.

Parameters:
  • method_call (callable) – A method call.
  • batch_tasks (list[dict]) – A batch of method calls.
  • exp_prefix (str) – Name prefix for the experiment.
  • exp_name (str) – Name of the experiment.
  • log_dir (str) – Log directory for the experiment.
  • script (str) – The name of the entrance point python script.
  • python_command (str) – Python command to run the experiment.
  • dry (bool) – Whether to do a dry-run, which only prints the commands without executing them.
  • env (dict) – Extra environment variables.
  • variant (dict) – If provided, should be a dictionary of parameters.
  • force_cpu (bool) – Whether to set all GPU devices invisible to force use CPU.
  • pre_commands (str) – Pre commands to run the experiment.
  • kwargs (dict) – Additional parameters.
to_local_command(params, python_command='python', script='garage.experiment.experiment_wrapper')[source]
wrap_experiment(function=None, *, log_dir=None, prefix='experiment', name=None, snapshot_mode='last', snapshot_gap=1, archive_launch_repo=True, name_parameters=None, use_existing_dir=False)[source]

Decorate a function to turn it into an ExperimentTemplate.

When invoked, the wrapped function will receive an ExperimentContext, which will contain the log directory into which the experiment should log information.

This decorator can be invoked in two differed ways.

Without arguments, like this:

@wrap_experiment def my_experiment(ctxt, seed, lr=0.5):

…

Or with arguments:

@wrap_experiment(snapshot_mode=’all’) def my_experiment(ctxt, seed, lr=0.5):

…

All arguments must be keyword arguments.

Parameters:
  • function (callable or None) – The experiment function to wrap.
  • log_dir (str or None) – The full log directory to log to. Will be computed from name if omitted.
  • name (str or None) – The name of this experiment template. Will be filled from the wrapped function’s name if omitted.
  • prefix (str) – Directory under data/local in which to place the experiment directory.
  • snapshot_mode (str) – Policy for which snapshots to keep (or make at all). Can be either “all” (all iterations will be saved), “last” (only the last iteration will be saved), “gap” (every snapshot_gap iterations are saved), or “none” (do not save snapshots).
  • snapshot_gap (int) – Gap between snapshot iterations. Waits this number of iterations before taking another snapshot.
  • archive_launch_repo (bool) – Whether to save an archive of the repository containing the launcher script. This is a potentially expensive operation which is useful for ensuring reproducibility.
  • name_parameters (str or None) – Parameters to insert into the experiment name. Should be either None (the default), ‘all’ (all parameters will be used), or ‘passed’ (only passed parameters will be used). The used parameters will be inserted in the order they appear in the function definition.
  • use_existing_dir (bool) – If true, (re)use the directory for this experiment, even if it already contains data.
Returns:

The wrapped function.
Return type:

callable