sierra.plugins.engine.argos.plugin

The plugin for the ARGoS Engine.

Classes

ExpConfigurer	Perform additional configuration after creating experiments in stage 1.
ExpRunShellCmdsGenerator	Shell command generator for per-run parallelism.
ExpShellCmdsGenerator	Shell command generator for per-exp parallelism.

Functions

cmdline_postparse_configure(→ argparse.Namespace)	Configure cmdline args after parsing for the ARGoS engine.
execenv_check(→ None)	Perform stage2 execution environment checks for the ARgoS engine.
robot_type_from_def(→ Optional[str])	Get the entity type of the robots managed by ARGoS.

Module Contents

class sierra.plugins.engine.argos.plugin.ExpConfigurer(cmdopts: sierra.core.types.Cmdopts)

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.

for_exp(exp_input_root: pathlib.Path) → None

Configure an Experiment.

Parameters:

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

for_exp_run(exp_input_root: pathlib.Path, run_output_root: pathlib.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.

parallelism_paradigm() → str

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.plugins.engine.argos.plugin.ExpRunShellCmdsGenerator(cmdopts: sierra.core.types.Cmdopts, criteria: sierra.core.variables.batch_criteria.XVarBatchCriteria, exp_num: int, n_agents: int | None)

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.

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

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.

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.plugins.engine.argos.plugin.cmdline_postparse_configure(env: str, args: argparse.Namespace) → argparse.Namespace

Configure cmdline args after parsing for the ARGoS engine.

This sets arguments appropriately depending on what HPC environment is selected with --execenv.

• hpc.local

• hpc.adhoc

• hpc.slurm

• hpc.pbs

sierra.plugins.engine.argos.plugin.execenv_check(cmdopts: sierra.core.types.Cmdopts) → None

Perform stage2 execution environment checks for the ARgoS engine.

Checks:

• ARGoS can be found

• ARGoS version supported

• ARGOS_PLUGIN_PATH is set

• for Xvfb if --engine-vc was passed.

sierra.plugins.engine.argos.plugin.robot_type_from_def(exp_def: sierra.core.experiment.definition.BaseExpDef) → str | None

Get the entity type of the robots managed by ARGoS.

Note

Assumes homgeneous systems.