sierra.core.engine

Terminal interface for pltaform plugins.

Classes for generating the commands to run experiments on multiple engines using multiple execution methods.

Classes

ExpRunShellCmdsGenerator	Dispatcher for shell cmd generation for an Experimental Run.
ExpShellCmdsGenerator	Dispatcher for shell cmd generation for an Experiment.

Functions

cmdline_postparse_configure(→ argparse.Namespace)

Dispatcher for configuring the cmdopts dictionary.

Module Contents

class sierra.core.engine.ExpRunShellCmdsGenerator(cmdopts: sierra.core.types.Cmdopts, criteria: sierra.core.variables.batch_criteria.XVarBatchCriteria, exp_num: int, n_agents: int | None)

Dispatcher for shell cmd generation for an Experimental Run.

Dispatches generation to the selected engine. Called during stage 1 to add shell commands which should be run immediately before and after the shell command to actually execute a single Experimental Run to the commands file to be fed to whatever the tool a given execution environment environment uses to run cmds (e.g., GNU parallel).

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

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.

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

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.

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

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.engine.ExpShellCmdsGenerator(cmdopts: sierra.core.types.Cmdopts, exp_num: int)

Dispatcher for shell cmd generation for an Experiment.

Dispatches generation to the selected engine. Called during stage 2 to run shell commands immediately before running a given Experiment, to run shell commands to actually run the experiment, and to run shell commands immediately after the experiment finishes.

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

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.

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

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.

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

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.

sierra.core.engine.cmdline_postparse_configure(engine: str, execenv: str, args: argparse.Namespace) → argparse.Namespace

Dispatcher for configuring the cmdopts dictionary.

Dispatches configuring to the selected --engine and --execenv. Called before the pipeline starts to add modify existing cmdline arguments after initial parsing. engine and execenv are needed as arguments as they are not present in args; they are "bootstrap" cmdline args needed to be parsed first to build the parser for the set of cmdline arguments accepted.