sierra-research 1.3.6__py3-none-any.whl → 1.5.0__py3-none-any.whl

sierra_research-1.3.6.data/data/share/man/man7/sierra-usage.7

@@ -1,725 +0,0 @@
-.\" Man page generated from reStructuredText.
-.
-.
-.nr rst2man-indent-level 0
-.
-.de1 rstReportMargin
-\\$1 \\n[an-margin]
-level \\n[rst2man-indent-level]
-level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
--
-\\n[rst2man-indent0]
-\\n[rst2man-indent1]
-\\n[rst2man-indent2]
-..
-.de1 INDENT
-.\" .rstReportMargin pre:
-. RS \\$1
-. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
-. nr rst2man-indent-level +1
-.\" .rstReportMargin post:
-..
-.de UNINDENT
-. RE
-.\" indent \\n[an-margin]
-.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
-.nr rst2man-indent-level -1
-.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
-.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
-..
-.TH "SIERRA-USAGE" "7" "Apr 01, 2024" "1.3.6" "SIERRA"
-.SH NAME
-sierra-usage \- How to use SIERRA. This covers all non-command line interface aspects.
-.sp
-This covers everything which is (mostly) \fI\%Platform\fP independent and is not
-the command line interface.
-.SH SIERRA PIPELINE
-.sp
-When invoked SIERRA will run one or more stages of its execution path, as
-specified via \fB\-\-pipeline\fP on the cmdline. Only the first 4 pipeline stages
-will run by default. The pipeline stages are:
-.SS Stage 1: Experiment Generation
-.sp
-Experiments using the scientific method have an independent variable whose
-impact on results are measured through a series of trials. SIERRA allows you to
-express this as a research query on the command line, and then parses your query
-to make changes to a template input file to generate launch commands and
-experimental inputs to operationalize it. Switching from targeting platform A
-(e.g., ARGoS) to platform B (e.g., ROS1+Gazebo) is as easy as changing a single
-command line argument. SIERRA handles the \(dqbackend\(dq aspects of defining
-experimental inputs allowing you to focus on their \fIcontent\fP, rather than the
-mechanics of how to turn the content into something that can be executed. See
-also:
-.INDENT 0.0
-.IP \(bu 2
-\fI\%SIERRA Support Matrix\fP
-.IP \(bu 2
-\fI\%Command Line Interface\fP
-.UNINDENT
-.sp
-Part of default pipeline.
-.SS Stage 2: Experiment Execution
-.sp
-SIERRA runs a previously generated \fI\%Batch Experiment\fP\&. Exactly which batch
-experiment SIERRA runs is determined by:
-.INDENT 0.0
-.IP \(bu 2
-\fB\-\-controller\fP
-.IP \(bu 2
-\fB\-\-scenario\fP
-.IP \(bu 2
-\fB\-\-sierra\-root\fP
-.IP \(bu 2
-\fB\-\-template\-input\-file\fP
-.IP \(bu 2
-\fB\-\-batch\-criteria\fP
-.UNINDENT
-.sp
-SIERRA currently supports two types of execution environments: simulators and
-real robots, which are handled seamlessly. For simulators, SIERRA will run
-multiple experimental runs from each experiment in parallel if possible. Similar
-to stage 1, switching between execution environments is as easy as changing a
-single command line argument. See also:
-.INDENT 0.0
-.IP \(bu 2
-\fI\%Execution Environment Plugins\fP
-.IP \(bu 2
-\fI\%Platform Plugins\fP
-.IP \(bu 2
-\fI\%SIERRA Support Matrix\fP
-.UNINDENT
-.sp
-Part of default pipeline.
-.SS Stage 3: Experiment Post\-Processing
-.sp
-SIERRA supports a number of data formats which simulations/real robot
-experiments can output their data, e.g., the number of robots engaged in a given
-task over time for processing.  SIERRA post\-processes experimental results after
-running the batch experiment; some parts of this can be done in parallel. This
-includes one or more of:
-.INDENT 0.0
-.IP \(bu 2
-Computing statistics over/about experimental data for stage 4 for use in graph
-generation in stage 4. See \fI\%Command Line Interface\fP documentation for
-\fB\-\-dist\-stats\fP for details.
-.IP \(bu 2
-Creating images from project CSV files for rendering in stage 4. See
-\fI\%Project Rendering\fP for details.
-.UNINDENT
-.sp
-Part of default pipeline.
-.SS Stage 4: Deliverable Generation
-.sp
-SIERRA can generate many deliverables from the processed experimental results
-automatically (independent of the platform/execution environment!), thus greatly
-simplifying reproduction of previous results if you need to tweak a given graph
-(for example). SIERRA currently supports generating the following deliverables:
-.INDENT 0.0
-.IP \(bu 2
-Camera\-ready linegraphs, heatmaps, 3D surfaces, and scatterplots directly from
-averaged/statistically processed experimental data using matplotlib.
-.IP \(bu 2
-Videos built from frames captured during simulation or real robot operation.
-.IP \(bu 2
-Videos built from captured experimental output .csv files.
-.UNINDENT
-.sp
-SIERRA also has a rich model framework allowing you to run arbitrary models,
-generate data, and plot it on the same figure as empirical results,
-automatically. See ln\-sierra\-tutorials\-project\-models for details.
-.sp
-For some examples, see the \(dqGenerating Deliverables\(dq section of
-\fI\%2022 AAMAS Demo\fP <\fBhttps://www-users.cse.umn.edu/~harwe006/showcase/aamas-2022-demo\fP>\&. See \fI\%Rendering\fP for details about
-rendering capabilities.
-.sp
-Part of default pipeline.
-.SS Stage 5: Graph Generation for Controller/Scenario Comparison
-.sp
-SIERRA can perform additional graph generation \fIAFTER\fP graph generation for
-batch experiments has been run. This is extremely useful for generating graphs
-which can be dropped immediately into academic papers without modification. This
-can be used to compare:
-.INDENT 0.0
-.IP \(bu 2
-Different agent control algorithms which have all been run in the same
-\fB\-\-scenario\fP\&. See \fI\%Intra\-Scenario Comparison\fP for details.
-.IP \(bu 2
-A single \fB\-\-controller\fP across multiple scenarios. See
-\fI\%Inter\-Scenario Comparison\fP for details.
-.UNINDENT
-.sp
-Not part of default pipeline.
-.SH PIPELINE STAGE 5
-.sp
-The main idea of this pipeline stage is to \(dqcollate\(dq the results of one or more
-\fI\%Summary .csv\fP files present in different \fI\%Batch Experiments\fP into a \fI\%Inter\-Batch .csv\fP file, and then use that file to
-generate graphs. Any \fI\%Summary .csv\fP that is present in multiple
-\fI\%Batch Experiments\fP can be used during stage 5!  This
-gives this pipeline stage tremendous flexibility as a camera\-ready graph
-generation tool.
-.sp
-In general, stage 5 is always run separate from stages 1\-4 (i.e., a separate
-SIERRA invocation), because the options are quite different, but you don\(aqt
-\fIhave\fP to do this.
-.sp
-\fBIMPORTANT:\fP
-.INDENT 0.0
-.INDENT 3.5
-You \fIcannot\fP use this stage before successfully running stage 4
-for each of the \fI\%Batch Experiments\fP you
-want to include on the final graph.
-.UNINDENT
-.UNINDENT
-.sp
-\fBWARNING:\fP
-.INDENT 0.0
-.INDENT 3.5
-Because SIERRA never deletes stuff for you, running stage 5 is
-\fINOT\fP idempotent. Running the same stage 5 invocation comparing 3
-controllers in a single scenario (for example) could result in
-linegraphs containing 3,6,9,..., lines with duplicated data. In
-general, you want to delete the directories generated by stage 5
-between successive runs. See
-\fI\%SIERRA Runtime Directory Tree\fP for details on what
-directories are generated.
-.UNINDENT
-.UNINDENT
-.SS Intra\-Scenario Comparison
-.sp
-Intra\-scenario comparison compares the of experiments using one or more
-controllers on the same \fB\-\-scenario\fP\&. To use it, you need to pass the
-following options to SIERRA (see \fI\%Command Line Interface\fP for documentation):
-.INDENT 0.0
-.IP \(bu 2
-\fB\-\-scenario\-comparison\fP
-.IP \(bu 2
-\fB\-\-bc\-univar\fP or \fB\-\-bc\-bivar\fP
-.IP \(bu 2
-\fB\-\-dist\-stats\fP (to get statistics generated during stage 3 to show up on the
-final graph).
-.UNINDENT
-.sp
-Other \fB\-\-plot\-*\fP options providing for fine\-grained control of the generated
-graphs may also be of interest.
-.sp
-For YAML configuration, see
-ln\-sierra\-tutorials\-project\-stage5\-config\-intra\&.
-.SS Inter\-Scenario Comparison
-.sp
-Inter\-scenario comparison compares the same \fB\-\-controller\fP across multiple
-\fB\-\-scenarios\fP\&. To use it, you need to pass the following options to SIERRA
-when running stage 5 (see \fI\%Command Line Interface\fP for documentation):
-.INDENT 0.0
-.IP \(bu 2
-\fB\-\-controller\-comparison\fP
-.IP \(bu 2
-\fB\-\-bc\-univar\fP or \fB\-\-bc\-bivar\fP
-.IP \(bu 2
-\fB\-\-dist\-stats\fP (to get statistics generated during stage 3 to show up on the
-final graph).
-.UNINDENT
-.sp
-Other \fB\-\-plot\-*\fP options providing for fine\-grained control of the generated
-graphs may also be of interest.
-.sp
-For YAML configuration, see
-ln\-sierra\-tutorials\-project\-stage5\-config\-inter\&.
-.SH SIERRA RUNTIME DIRECTORY TREE
-.sp
-\fBIMPORTANT:\fP
-.INDENT 0.0
-.INDENT 3.5
-SIERRA \fBNEVER\fP deletes directories for you.
-.sp
-Subsequent experiments using the same values for the following cmdline
-arguments \fBWILL\fP result in the same calculated root directory for
-experimental inputs and outputs, even if other parameters change (or if you
-change the contents of the template input file):
-.INDENT 0.0
-.IP \(bu 2
-\fB\-\-controller\fP
-.IP \(bu 2
-\fB\-\-scenario\fP
-.IP \(bu 2
-\fB\-\-sierra\-root\fP
-.IP \(bu 2
-\fB\-\-template\-input\-file\fP
-.IP \(bu 2
-\fB\-\-batch\-criteria\fP
-.UNINDENT
-.sp
-SIERRA will abort stage {1,2} processing when this occurs in order to
-preserve data integrity; this behavior can be overwridden with
-\fB\-\-exp\-overwrite\fP, in which case the use assumes full responsibility for
-ensuring the integrity of the experiment.
-.sp
-Always better to check the arguments before hitting ENTER. Measure twice, cut
-once, as the saying goes.
-.UNINDENT
-.UNINDENT
-.SS Default Pipeline Directory Tree (Stages 1\-4)
-.sp
-When SIERRA runs stages 1\-4, it creates a directory structure under whatever was
-passed as \fB\-\-sierra\-root\fP\&. For the purposes of explanation, I will use the
-following partial SIERRA option set to explain the experiment tree:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-\-\-sierra\-root=$HOME/exp\e
-\-\-controller=CATEGORY.my_controller\e
-\-\-scenario=SS.12x6\e
-\-\-platform=platform.argos\e
-\-\-batch\-criteria=population_size.Log8\e
-\-\-n\-runs=4\e
-\-\-template\-input\-file=~/my\-template.argos\e
-\-\-project=fordyca
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This invocation will cause SIERRA to create the following directory structure as
-it runs:
-.INDENT 0.0
-.IP \(bu 2
-\fB$HOME/exp\fP \- This is the root of the directory structure (\fB\-\-sierra\-root\fP),
-and is \fBNOT\fP deleted on subsequent runs.
-.INDENT 2.0
-.IP \(bu 2
-\fBfordyca\fP \- Each project gets their own directory, so you can disambiguate
-otherwise identical SIERRA invocations and don\(aqt overwrite the directories
-for a previously used project on subsequent runs.
-.INDENT 2.0
-.IP \(bu 2
-\fBCATEGORY.my_controller\fP \- Each controller gets their own directory in the
-project root, which is \fBNOT\fP deleted on subsequent runs.
-.INDENT 2.0
-.IP \(bu 2
-\fBmytemplate\-SS.12x6\fP \- The directory for the \fI\%Batch Experiment\fP
-is named from a combination of the template input file used
-(\fB\-\-template\-input\-file\fP) and the scenario (\fB\-\-scenario\fP).
-.INDENT 2.0
-.IP \(bu 2
-\fBexp\-inputs\fP \- Root directory for \fI\%Experimental\fP
-inputs; each experiment in the batch gets their own directory in here.
-.INDENT 2.0
-.IP \(bu 2
-\fBexp0\fP \- Within the input directory for each experiment in the
-batch (there are 4 such directories in this example), there will be
-an input file for each \fI\%Experimental Run\fP in the experiment,
-as well as a \fBcommands.txt\fP used by GNU parallel to run them all
-in parallel. The leaf of the \fB\-\-template\-input\-file\fP, sans
-extension, has the experimental run # appended to it
-(e.g. \fBmy\-template_0.argos\fP is the input file for simulation 0).
-.INDENT 2.0
-.INDENT 3.5
-.INDENT 0.0
-.IP \(bu 2
-\fBcommands.txt\fP
-.IP \(bu 2
-\fBmy\-template_0.argos\fP
-.IP \(bu 2
-\fBmy\-template_1.argos\fP
-.IP \(bu 2
-\fBmy\-template_2.argos\fP
-.IP \(bu 2
-\fBmy\-template_3.argos\fP
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.IP \(bu 2
-\fBexp1\fP
-.INDENT 2.0
-.IP \(bu 2
-\fBmy\-template_0.argos\fP
-.IP \(bu 2
-\fBmy\-template_1.argos\fP
-.IP \(bu 2
-\fBmy\-template_2.argos\fP
-.IP \(bu 2
-\fBmy\-template_3.argos\fP
-.UNINDENT
-.IP \(bu 2
-\fBexp2\fP
-.INDENT 2.0
-.IP \(bu 2
-\fB\&...\fP
-.UNINDENT
-.UNINDENT
-.IP \(bu 2
-\fBexp\-outputs\fP \- Root directory for experimental outputs; each
-experiment gets their own directory in here (just like for experiment
-inputs). Directory name is controlled by the main YAML configuration.
-.INDENT 2.0
-.IP \(bu 2
-\fBexp0\fP \- Within the output directory for each experiment in the
-batch (there are 3 such directories in this example), there will be
-a \fIdirectory\fP (rather than a file, as was the case for inputs) for
-each experimental run\(aqs output, including metrics, grabbed frames,
-etc., as configured in the XML input file.
-.INDENT 2.0
-.IP \(bu 2
-\fBmy\-template_0_output\fP
-.IP \(bu 2
-\fBmy\-template_1_output\fP
-.IP \(bu 2
-\fBmy\-template_2_output\fP
-.IP \(bu 2
-\fBmy\-template_3_output\fP
-.UNINDENT
-.IP \(bu 2
-\fBexp1\fP
-.INDENT 2.0
-.IP \(bu 2
-\fBmy\-template_0_output\fP
-.IP \(bu 2
-\fBmy\-template_1_output\fP
-.IP \(bu 2
-\fBmy\-template_2_output\fP
-.IP \(bu 2
-\fBmy\-template_3_output\fP
-.UNINDENT
-.IP \(bu 2
-\fBexp2\fP
-.INDENT 2.0
-.IP \(bu 2
-\fB\&...\fP
-.UNINDENT
-.IP \(bu 2
-\fBstatistics\fP \- Root directory for holding statistics calculated
-during stage3 for use during stage4.
-.INDENT 2.0
-.IP \(bu 2
-\fBexp0\fP \- Contains the results of statistics generation for exp0
-(mean, stddev, etc., as configured).
-.IP \(bu 2
-\fBexp1\fP
-.IP \(bu 2
-\fBexp2\fP
-.IP \(bu 2
-\fB\&...\fP
-.IP \(bu 2
-\fBcollated\fP \- Contains \fI\%Collated .csv\fP files. During
-stage4, SIERRA will draw specific columns from .csv files under
-\fBstatistics\fP according to configuration, and collate them under
-here for graph generation of \fIinter\fP\-experiment graphs.
-.IP \(bu 2
-\fBexec\fP \- Statistics about SIERRA runtime. Useful for capturing
-runtime of specific experiments to better plan/schedule time on
-HPC clusters.
-.UNINDENT
-.UNINDENT
-.IP \(bu 2
-\fBimagize\fP \- Root directory for holding imagized files (averaged run
-outputs which have been converted to graphs) which can be patched
-together in stage 4 to generated videos. Each experiment will get its
-own directory under here, with unique sub\-directories for each
-different type of \fI\%Experimental Run\fP data captured for
-imagizing. See \fI\%Project Rendering\fP for more details.
-.IP \(bu 2
-\fBvideos\fP \- Root directory for holding rendered videos generated
-during stage 4 from either captured simulator frames for imagized
-project files. Each experiment will get its own directory under here,
-with See \fI\%Rendering\fP for more details.
-.IP \(bu 2
-\fBmodels\fP \- During stage4, the dataframes generated by all executed
-models are stored under this directory. Each experiment in the batch
-gets their own directory for \fIintra\fP\-experiment models.
-.IP \(bu 2
-\fBgraphs\fP \- During stage4, all generated graphs are output under this
-directory. Each experiment in the batch gets their own directory for
-\fIintra\fP\-experiment graphs.
-.INDENT 2.0
-.IP \(bu 2
-\fBexp0\fP
-.IP \(bu 2
-\fBexp1\fP
-.IP \(bu 2
-\fBexp2\fP
-.IP \(bu 2
-\fBexp3\fP
-.IP \(bu 2
-\fBcollated\fP \- Graphs which are generated across experiments in the
-batch from collated .csv data, rather than from the averaged results
-within each experiment, are output here.
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.SS Stage 5 Directory Tree
-.sp
-When SIERRA runs stage 5, stages 1\-4 must have already been successfully run,
-and therefore the directory tree shown above will exist. For the purposes of
-explanation, I will use the following partial SIERRA option sets to explain the
-additions to the experiment tree for stage 5.
-.sp
-First, the experiment tree for \fIscenario comparison\fP:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-\-\-pipeline 5\e
-\-\-scenario\-comparison\e
-\-\-batch\-criteria population_size.Log8\e
-\-\-scenarios\-list=RN.16x16x2,PL.16x16x2\e
-\-\-sierra\-root=$HOME/exp\(dq
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This invocation will cause SIERRA to create the following directory structure as
-it runs:
-.INDENT 0.0
-.IP \(bu 2
-\fB$HOME/exp\fP
-.INDENT 2.0
-.IP \(bu 2
-\fBRN.16x16x2+PL.16x16x2\-sc\-graphs\fP
-.sp
-This is the directory holding the comparison graphs for all controllers
-which were previously run on the scenarios \fBRN.16x16x2\fP and \fBPL.16x16x2\fP
-(scenario names are arbitrary for the purposes of stage 5 and entirely
-depend on the project). Inside this directory will be all graphs generated
-according to the configuration specified in
-ln\-sierra\-tutorials\-project\-stage5\-config\&.
-.UNINDENT
-.UNINDENT
-.sp
-Second, the experiment tree for \fIcontroller comparison\fP
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-\-\-pipeline 5\e
-\-\-controller\-comparison\e
-\-\-batch\-criteria population_size.Log8\e
-\-\-controllers\-list d0.CRW,d0.DPO\e
-\-\-sierra\-root=$HOME/exp\(dq
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This invocation will cause SIERRA to create the following directory structure as
-it runs:
-.INDENT 0.0
-.IP \(bu 2
-\fB$HOME/exp\fP
-.INDENT 2.0
-.IP \(bu 2
-\fBd0.CRW+d0.DPO\-cc\-graphs\fP
-.sp
-This is the directory holding the comparison graphs for each scenario for
-which \fBd0.CRW\fP and \fBd0.DPO\fP were run (scenarios are computed by
-examining the directory tree for stages 1\-4). Controller names are arbitrary
-for the purposes of stage 5 and entirely depend on the project). Inside this
-directory will be all graphs generated according to the configuration
-specified in ln\-sierra\-tutorials\-project\-stage5\-config\&.
-.UNINDENT
-.UNINDENT
-.SH SIERRA SUBPROGRAMS
-.sp
-These are the shell programs which SIERRA \fImay\fP use internally when running,
-depending on what you are doing.
-.INDENT 0.0
-.IP \(bu 2
-\fBparallel\fP \- GNU parallel. Used during stage 2 when running
-experiments (\fI\%ARGoS\fP, \fI\%ROS1+Gazebo\fP, \fI\%ROS1+Robot\fP platforms).
-.IP \(bu 2
-\fBffmpeg\fP \- Used during stage 3 if imagizing is run. See
-\fI\%Platform Visual Capture\fP\&.
-.IP \(bu 2
-\fBXvfb\fP \- Used during stage 1 when generating simulation inputs, and
-during stage 2 when running experiments for the \fI\%ARGoS\fP
-\fI\%Platform\fP\&. See also \fI\%Platform Visual Capture\fP\&.
-.IP \(bu 2
-\fBparallel\-ssh\fP \- Used during stage 1 when generating experiments
-experiments (\fI\%ROS1+Robot\fP platform).
-.IP \(bu 2
-\fBparallel\-rsync\fP \- Used during stage 1 when generating experiments
-experiments (\fI\%ROS1+Robot\fP platform).
-.UNINDENT
-.SH ENVIRONMENT VARIABLES
-.INDENT 0.0
-.TP
-.B SIERRA_PLUGIN_PATH
-Used for locating \fI\%plugins\fP\&. The directory \fIcontaining\fP a
-plugin directory outside the SIERRA source tree must be on
-\fBSIERRA_PLUGIN_PATH\fP\&. Paths are added to \fBPYTHONPATH\fP as needed to load
-plugins correctly. For example, if you have a different version of the
-\fB\-\-storage\-medium\fP plugin you\(aqd like to use, and you have but the directory
-containing the plugin in \fB$HOME/plugins\fP, then you need to add
-\fB$HOME/plugins\fP to your \fBSIERRA_PLUGIN_PATH\fP to so that SIERRA will find
-it. This variable is used in stages 1\-5.
-.sp
-Used for locating \fI\%projects\fP; all projects specifiable with
-\fB\-\-project\fP are directories found within the directories on this path. For
-example, if you have a project \fB$HOME/git/projects/myproject\fP, then
-\fB$HOME/git\fP must be on \fBSIERRA_PLUGIN_PATH\fP in order for you to be able
-to specify \fB\-\-project=myproject\fP\&. This variable is used in stages 1\-5.
-.sp
-You \fIcannot\fP just put the parent directory of your project on
-\fI\%PYTHONPATH\fP because SIERRA uses this path for other things
-internally (e.g., computing the paths to YAML config files).
-.UNINDENT
-.INDENT 0.0
-.TP
-.B PYTHONPATH
-Used for locating projects per the usual python mechanisms.
-.UNINDENT
-.INDENT 0.0
-.TP
-.B ARGOS_PLUGIN_PATH
-Must be set to contain the library directory where you installed/built ARGoS,
-as well as the library directory for your project \fB\&.so\fP\&. Checked to be
-non\-empty before running stage 2 for all \fB\-\-exec\-env\fP plugins. SIERRA does
-\fInot\fP modify this variable, so it needs to be setup properly prior to
-invoking SIERRA (i.e., the directory containing the \fI\%Project\fP \fB\&.so\fP
-file needs to be on it). SIERRA can\(aqt know, in general, where the location of
-the C++ code corresponding to the loaded \fI\%Project\fP is.
-.UNINDENT
-.INDENT 0.0
-.TP
-.B SIERRA_ARCH
-Can be used to determine the names of executables launch in HPC environment,
-so that in environments with multiple queues/sub\-clusters with different
-architectures simulators can be compiled natively for each for maximum
-performance. Can be any string. If defined, then instead of searching for the
-\fBfoobar\fP executable for some platform on \fBPATH\fP, SIERRA will look for
-\fBfoobar\-$SIERRA_ARCH\fP\&.
-.sp
-\fBIMPORTANT:\fP
-.INDENT 7.0
-.INDENT 3.5
-Not all platforms use this variable\-\-see the docs for your
-platform of interest.
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B SIERRA_NODEFILE
-Points to a file suitable for passing to \fBparallel\fP via
-\fB\-\-sshloginfile\fP\&. See \fBparallel\fP docs for general
-content/formatting requirements.
-.sp
-Used by SIERRA to configure experiments during stage 1,2; if it is not
-defined and \fB\-\-nodefile\fP is not passed SIERRA will throw an error.
-.UNINDENT
-.INDENT 0.0
-.TP
-.B PARALLEL
-When running on some execution environments, such as \fBhpc.slurm,hpc.pbs\fP,
-any and all environment variables needed by your \fI\%Project\fP should be
-exported via the \fBPARALLEL\fP environment variable before invoking SIERRA,
-because GNU parallel does not export the environment of the node it is
-launched from to slave nodes (or even on the local machine). Something like:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-export PARALLEL=\(dq\-\-workdir . \e
-\-\-env PATH \e
-\-\-env LD_LIBRARY_PATH \e
-\-\-env LOADEDMODULES \e
-\-\-env _LMFILES_ \e
-\-\-env MODULE_VERSION \e
-\-\-env MODULEPATH \e
-\-\-env MODULEVERSION_STACK
-\-\-env MODULESHOME \e
-\-\-env OMP_DYNAMICS \e
-\-\-env OMP_MAX_ACTIVE_LEVELS \e
-\-\-env OMP_NESTED \e
-\-\-env OMP_NUM_THREADS \e
-\-\-env OMP_SCHEDULE \e
-\-\-env OMP_STACKSIZE \e
-\-\-env OMP_THREAD_LIMIT \e
-\-\-env OMP_WAIT_POLICY \e
-\-\-env SIERRA_ARCH \e
-\-\-env SIERRA_PLUGIN_PATH\(dq
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Don\(aqt forget to include \fI\%ARGOS_PLUGIN_PATH\fP,
-\fI\%ROS_PACKAGE_PATH\fP, etc., depending on your chosen \fI\%Platform\fP\&.
-.UNINDENT
-.INDENT 0.0
-.TP
-.B PARALLEL_SHELL
-SIERRA sets up the \fI\%Experiment\fP execution environments by running one
-or more shell commands in a subprocess (treated as a \fBshell\fP, which means
-that \fBparallel\fP can\(aqt determine \fBSHELL\fP, and therefore defaults to
-\fB/bin/sh\fP, which is not what users expect. SIERRA explicitly sets
-\fBPARALLEL_SHELL\fP to the result of \fBshutil.which(\(aqbash\(aq)\fP in keeping with
-the Principle Of Least Surprise.
-.UNINDENT
-.INDENT 0.0
-.TP
-.B ROS_PACKAGE_PATH
-The list of directories which defines where ROS will search for
-packages. SIERRA does \fInot\fP modify this variable, so it needs to be setup
-properly prior to invoking SIERRA (i.e., sourcing the proper \fBsetup.bash\fP
-script).
-.UNINDENT
-.SH CONFIGURABLE SIERRA VARIABLES
-.sp
-Non\-\fI\%Batch Criteria\fP variables which you can use to configure
-simulations. All batch criteria are variables, but not all variables are batch
-criteria.
-.INDENT 0.0
-.IP \(bu 2
-\fI\%Experiment Setup\fP
-.UNINDENT
-.SS Experiment Setup
-.sp
-Configure \fI\%Experiment\fP time: length, controller cadence (\fI\%Tick\fP
-duration/timestep), and how many datapoints to capture per \fI\%Experimental
-Run\fP\&.
-.SS Cmdline Syntax
-.sp
-\fBT{duration}[.K{ticks_per_sec}][.N{n_datapoints}\fP
-.INDENT 0.0
-.IP \(bu 2
-\fBduration\fP \- Duration of timesteps in \fIseconds\fP (not timesteps).
-.IP \(bu 2
-\fBticks_per_sec\fP \- How many times each controller will be run per second.
-.IP \(bu 2
-\fBn_datapoints\fP \- # datapoints per \fI\%Experimental Run\fP to be captured;
-the capture interval (if configurable) should be adjusted in
-\fI\%Project\fP\-derived class from the platform \(dqExperiment setup class\(dq
-(e.g., \fBsierra.plugins.platform.argos.variables.exp_setup.ExpSetup\fP for
-\fI\%ARGoS\fP).
-.UNINDENT
-.SS Examples
-.INDENT 0.0
-.IP \(bu 2
-\fBexp_setup.T1000\fP: Experimental run will be 1,000 seconds long and have
-1,000*5=5,000 timesteps, with default (50) # datapoints.
-.IP \(bu 2
-\fBexp_setup.T2000.N100\fP: Experimental run will be 2,000 seconds long and have
-2,000*5=10,000 timesteps, with 100 datapoints (1 every 20 seconds/100
-timesteps).
-.IP \(bu 2
-\fBexp_setup.T10000.K10\fP: Experimental run will be 10,000 seconds long, and
-have 10,000*10=100,000 timesteps with default (50) # datapoints.
-.IP \(bu 2
-\fBexp_setup.T10000.K10.N100\fP: Experimental run will be 10,000 seconds long,
-and have 10,000*10=100,000 timesteps, with 100 datapoints (one every 100
-seconds/1,000 timesteps).
-.UNINDENT
-.SH AUTHOR
-John Harwell
-.SH COPYRIGHT
-2022, John Harwell
-.\" Generated by docutils manpage writer.
-.