sierra.core.experiment.bindings#

Container module for interfaces for things related to experiments.

Interfaces are implemented by {engines, exec envs}.

Classes#

IBatchShellCmdsGenerator

Shell command generator for per-batch parallelism.

IExpConfigurer

Perform additional configuration after creating experiments in stage 1.

IExpRunShellCmdsGenerator

Shell command generator for per-run parallelism.

IExpShellCmdsGenerator

Shell command generator for per-exp parallelism.

Module Contents#

class sierra.core.experiment.bindings.IBatchShellCmdsGenerator(cmdopts: sierra.core.types.Cmdopts)[source]#

Shell command generator for per-batch parallelism.

See Execution Model for a full explanation of the parallelism paradigms and hook structure.

Parameters:

cmdopts -- Dictionary of parsed cmdline options.

abstract exec_batch_cmds(exec_opts: sierra.core.types.StrDict) → list[sierra.core.types.ShellCmdSpec][source]#

Generate the command to execute the Batch Experiment.

Called during stage 2. Runs in the same sub-shell as the pre- and post-batch commands.

Parameters:

exec_opts --

A dictionary containing:

  • jobroot_path - Root directory for the batch experiment.

  • exec_resume - Whether this resumes a previously started experiment.

  • joblog_path - Logfile for the experiment run command (distinct from Project code output).

  • cmdfile_stem_path - Path to the cmdfile, excluding extension.

  • cmdfile_ext - Extension of the cmdfile.

abstract post_batch_cmds() → list[sierra.core.types.ShellCmdSpec][source]#

Generate cleanup commands for after the Batch Experiment.

Called during stage 1. Commands run after all experiments have finished: stopping background processes, visualization daemons, etc. Runs in the same sub-shell as the pre- and exec-batch commands.

abstract pre_batch_cmds() → list[sierra.core.types.ShellCmdSpec][source]#

Generate setup commands for the Batch Experiment.

Called during stage 1. Commands run before any experimental run is started: launching daemons, background processes, setting environment variables, etc. that should be common to all experiments in the batch.

class sierra.core.experiment.bindings.IExpConfigurer(cmdopts: sierra.core.types.Cmdopts)[source]#

Perform additional configuration after creating experiments in stage 1.

E.g., creating directories to store outputs in if they are not created by the simulator/Project code.

Parameters:

cmdopts -- Dictionary of parsed cmdline options.

abstract for_exp(exp_input_root: pathlib.Path) → None[source]#

Configure an Experiment.

Parameters:

exp_input_root -- Absolute path to the input directory for the experiment.

abstract for_exp_run(exp_input_root: pathlib.Path, run_output_root: pathlib.Path) → None[source]#

Configure an Experimental Run.

Parameters:

  • exp_input_root -- Absolute path to the input directory for the experiment.

  • run_output_root -- Absolute path to the output directory for the experimental run.

abstract parallelism_paradigm() → str[source]#

Return the parallelism paradigm for this engine.

Must return one of per-batch, per-exp, or per-run. See Execution Model for full details and guidance on which to choose.

class sierra.core.experiment.bindings.IExpRunShellCmdsGenerator(cmdopts: sierra.core.types.Cmdopts, criteria: sierra.core.variables.batch_criteria.XVarBatchCriteria, exp_num: int, n_agents: int | None)[source]#

Shell command generator for per-run parallelism.

See Execution Model for a full explanation of the parallelism paradigms and hook structure.

You may want to use SIERRA_ARCH (in this class or your dispatch) to select a version of your simulator compiled for a specific architecture.

Parameters:

  • cmdopts -- Dictionary of parsed cmdline options.

  • criteria -- The batch criteria for the experiment.

  • exp_num -- The 0-based index of the experiment in the batch.

  • n_agents -- The configured number of agents for the run, if known.

abstract exec_run_cmds(host: str, input_fpath: pathlib.Path, run_num: int) → list[sierra.core.types.ShellCmdSpec][source]#

Generate the command to execute a single Experimental Run.

Called during stage 1. Typically the simulator launch command or the robot controller startup command. Runs in stage 2 after pre_run_cmds() for each run.

Parameters:

  • host -- The machine these commands will run on.

  • input_fpath -- Absolute path to the input/launch file for the run.

  • run_num -- The 0-based ID of the experimental run.

abstract post_run_cmds(host: str, run_output_root: pathlib.Path) → list[sierra.core.types.ShellCmdSpec][source]#

Generate cleanup commands for after an Experimental Run.

Called during stage 1. Commands run in stage 2 in the same sub-shell as the pre- and exec-run commands: stopping background processes, collecting remote outputs, etc.

Parameters:

  • host -- The machine these commands will run on.

  • run_output_root -- Absolute path to the output directory for the run.

abstract pre_run_cmds(host: str, input_fpath: pathlib.Path, run_num: int) → list[sierra.core.types.ShellCmdSpec][source]#

Generate setup commands for an Experimental Run.

Called during stage 1. Commands run in stage 2 before each run: launching per-run daemons, background processes, or anything that should not be shared between runs. The host argument identifies which machine these commands will execute on.

Parameters:

  • host -- The machine these commands will run on.

  • input_fpath -- Absolute path to the input/launch file for the run.

  • run_num -- The 0-based ID of the experimental run.

class sierra.core.experiment.bindings.IExpShellCmdsGenerator(cmdopts: sierra.core.types.Cmdopts, exp_num: int)[source]#

Shell command generator for per-exp parallelism.

See Execution Model for a full explanation of the parallelism paradigms and hook structure.

Parameters:

  • cmdopts -- Dictionary of parsed cmdline options.

  • exp_num -- The 0-based index of the experiment in the batch.

abstract exec_exp_cmds(exec_opts: sierra.core.types.StrDict) → list[sierra.core.types.ShellCmdSpec][source]#

Generate the command to execute an Experiment.

Typically a single GNU parallel invocation, but not required to be. Called during stage 2. Runs in the same sub-shell as the pre- and post-exp commands.

Note

The return value of this method is ignored when defined on an engine plugin. Execution environment plugins are always responsible for the actual parallel dispatch.

Parameters:

exec_opts --

A dictionary containing:

  • jobroot_path - Root directory for the batch experiment.

  • exec_resume - Whether this resumes a previously started experiment.

  • n_jobs - How many parallel jobs are allowed per node.

  • joblog_path - Logfile for the experiment run command (distinct from Project code output).

  • cmdfile_stem_path - Path to the cmdfile, excluding extension.

  • cmdfile_ext - Extension of the cmdfile.

  • nodefile - Path to the file containing compute resources for SIERRA to use. See --nodefile and SIERRA_NODEFILE for details.

abstract post_exp_cmds() → list[sierra.core.types.ShellCmdSpec][source]#

Generate cleanup commands for after an Experiment.

Called during stage 1. Commands run after all Experimental Runs in the experiment have finished but before the next experiment starts: stopping background processes, visualization daemons, etc. Runs in the same sub-shell as the pre- and exec-exp commands.

abstract pre_exp_cmds() → list[sierra.core.types.ShellCmdSpec][source]#

Generate setup commands for an Experiment.

Called during stage 1. Commands run before any experimental run in the experiment starts, in a new sub-shell: launching daemons, background processes, setting environment variables, etc. that should be common to all runs within the experiment.