sierra.core.experiment.bindings

• IParsedCmdlineConfigurer: Modify arguments as needed for the platform or execution environment.

• IExpRunShellCmdsGenerator: Interface for generating the shell cmds to run for an Experimental Run.

• IExpShellCmdsGenerator: Interface for generating the shell cmds to run for an Experiment.

• IExpConfigurer: Perform addition configuration after creating experiments.

• IExecEnvChecker: Perform sanity checks for stage 2 execution environment.

• ICmdlineParserGenerator: Return the argparse object containing ALL options relevant to the platform.

class sierra.core.experiment.bindings.IParsedCmdlineConfigurer(exec_env: str)

Modify arguments as needed for the platform or execution environment.

Inheritance

__call__(args: Namespace) → None

Call self as a function.

__doc__ = '\n    Modify arguments as needed for the platform or execution environment.\n    '

__init__(exec_env: str) → None

__module__ = 'sierra.core.experiment.bindings'

class sierra.core.experiment.bindings.IExpRunShellCmdsGenerator(cmdopts: Dict[str, Any], criteria: BatchCriteria, n_robots: int, exp_num: int)

Interface for generating the shell cmds to run for an Experimental Run.

This includes:

• The cmds to run the prior to the run.

• The cmds to executed the experimental run.

• Any post-run cleanup cmds before the next run is executed.

Depending on your environment, you may want to use SIERRA_ARCH (either in this function or your dispatch) to chose a version of your simulator compiled for a given architecture for maximum performance.

Parameters:

• cmdopts – Dictionary of parsed cmdline options.

• n_robots – The configured # of robots for the experimental run.

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

Inheritance

__doc__ = 'Interface for generating the shell cmds to run for an :term:`Experimental Run`.\n\n    This includes:\n\n    - The cmds to run the prior to the run.\n\n    - The cmds to executed the experimental run.\n\n    - Any post-run cleanup cmds before the next run is executed.\n\n    Depending on your environment, you may want to use :envvar:`SIERRA_ARCH`\n    (either in this function or your dispatch) to chose a version of your\n    simulator compiled for a given architecture for maximum performance.\n\n    Arguments:\n\n        cmdopts: Dictionary of parsed cmdline options.\n\n        n_robots: The configured # of robots for the experimental run.\n\n        exp_num: The 0-based index of the experiment in the batch.\n\n    '

__init__(cmdopts: Dict[str, Any], criteria: BatchCriteria, n_robots: int, exp_num: int) → None

__module__ = 'sierra.core.experiment.bindings'

exec_run_cmds(host: str, input_fpath: Path, run_num: int) → List[ShellCmdSpec]

Generate shell commands to execute a single Experimental Run.

This is (usually) a command to launch the simulation environment or start the controller code on a real robot, but it doesn’t have to be. These commands are run during stage 2 after the pre_run_cmds() for each experimental run in the Experiment.

Called during stage 1.

Parameters:

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

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

post_run_cmds(host: str) → List[ShellCmdSpec]

Generate shell commands to run after an experimental run has finished.

These commands are run during stage 2 in the same sub-shell as the pre- and exec-run commands. These commands can include things like cleaning up/stopping background processes, visualization daemons, etc.

Called during stage 1.

pre_run_cmds(host: str, input_fpath: Path, run_num: int) → List[ShellCmdSpec]

Generate shell commands to setup the experimental run environment.

These commands are run in stage 2 prior to each experimental run in the Experiment; that is prior to the exec_run_cmds(). These commands can include setting up things which are unique to/should not be shared between experimental runs within the experiment, such as launching daemons/background processes, setting environment variables, etc.

Called during stage 1.

Parameters:

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

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

class sierra.core.experiment.bindings.IExpShellCmdsGenerator(cmdopts: Dict[str, Any], exp_num: int)

Interface for generating the shell cmds to run for an Experiment.

This includes:

• The cmds to run the prior to the experiment (before any Experimental Runs).

• The cmds to run the experiment.

• Any post-experiment cleanup cmds before the next Experiment is run.

Parameters:

• cmdopts – Dictionary of parsed cmdline options.

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

Inheritance

__doc__ = '\n    Interface for generating the shell cmds to run for an :term:`Experiment`.\n\n    This includes:\n\n    - The cmds to run the prior to the experiment (before any\n      :term:`Experimental Runs <Experimental Run>`).\n\n    - The cmds to run the experiment.\n\n    - Any post-experiment cleanup cmds before the next :term:`Experiment` is\n      run.\n\n    Arguments:\n\n        cmdopts: Dictionary of parsed cmdline options.\n\n        exp_num: The 0-based index of the experiment in the batch.\n    '

__init__(cmdopts: Dict[str, Any], exp_num: int) → None

__module__ = 'sierra.core.experiment.bindings'

exec_exp_cmds(exec_opts: Dict[str, str]) → List[ShellCmdSpec]

Generate shell commands to execute an Experiment.

This is (usually) a single GNU parallel command, but it does not have to be. These commands are run in the same sub-shell as the pre- and post-exp commands during stage 2.

Called during stage 2.

Parameters:

exec_opts –

A dictionary containing:

• jobroot_path - The root directory for the batch experiment.

• exec_resume - Is this a resume of a previously run experiment?

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

• joblog_path - The logfile for output for the experiment run cmd (different than the Project code).

• cmdfile_stem_path - Stem of the file containing the launch cmds to run (one per line), all the way up to but not including the extension.

• cmdfile_ext - Extension of files containing the launch cmds to run.

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

post_exp_cmds() → List[ShellCmdSpec]

Generate shell commands to run after an Experiment has finished.

Commands are run during stage 2 after all Experimental runs <Experimental Run>` for an Experiment have finished, but before the next experiment in the Batch Experiment is launched. These commands are run in the same sub-shell as the pre- and exec-exp commands.

These commands include things like cleaning up/stopping background processes, visualization daemons, etc.

Called during stage 1.

pre_exp_cmds() → List[ShellCmdSpec]

Generate shell commands to setup the environment for an Experiment.

These commands can include setting up things which are common to/should be the same for all experimental runs within the experiment, such as launching daemons/background processes needed by the platform, setting environment variables, etc. These commands are run prior to each experiment in the batch during stage 2, in a new sub-shell which SIERRA uses to run all Experiment Runs within the experiment.

Called during stage 1.

class sierra.core.experiment.bindings.IExpConfigurer(cmdopts: Dict[str, Any])

Perform addition configuration after creating experiments.

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

Parameters:

cmdopts – Dictionary of parsed cmdline options.

Inheritance

__doc__ = 'Perform addition configuration after creating experiments.\n\n    E.g., creating directories store outputs in if they are not created by the\n    simulator/:term:`Project` code.\n\n    Arguments:\n\n        cmdopts: Dictionary of parsed cmdline options.\n\n    '

__init__(cmdopts: Dict[str, Any]) → None

__module__ = 'sierra.core.experiment.bindings'

cmdfile_paradigm() → str

Return the paradigm for the platform, in terms of GNU parallel cmds.

• per-exp - A single GNU parallel cmds file per experiment.

• per-run - A single GNU parallel cmds file per run.

for_exp(exp_input_root: Path) → None

Configure an experiment.

Parameters:

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

for_exp_run(exp_input_root: Path, run_output_root: Path) → None

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.

class sierra.core.experiment.bindings.IExecEnvChecker(cmdopts: Dict[str, Any])

Perform sanity checks for stage 2 execution environment.

This is needed because stage 2 can run separate from stage 1, and we need to guarantee that the execution environment we verified during stage 1 is still valid.

Parameters:

cmdopts – Dictionary of parsed cmdline options.

Inheritance

__call__() → None

Call self as a function.

__doc__ = 'Perform sanity checks for stage 2 execution environment.\n\n    This is needed because stage 2 can run separate from stage 1, and we need to\n    guarantee that the execution environment we verified during stage 1 is still\n    valid.\n\n    Arguments:\n\n        cmdopts: Dictionary of parsed cmdline options.\n\n    '

__init__(cmdopts: Dict[str, Any]) → None

__module__ = 'sierra.core.experiment.bindings'

class sierra.core.experiment.bindings.ICmdlineParserGenerator

Return the argparse object containing ALL options relevant to the platform.

This includes the options for whatever --exec-env are valid for the platform, making use of the parents option for the cmdline.

Inheritance

__call__() → ArgumentParser

Call self as a function.

__doc__ = 'Return the argparse object containing ALL options relevant to the platform.\n\n    This includes the options for whatever ``--exec-env`` are valid for the\n    platform, making use of the ``parents`` option for the cmdline.\n\n    '

__module__ = 'sierra.core.experiment.bindings'