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

sierra_research-1.3.11.data/data/share/man/man7/sierra-exec-envs.7

@@ -1,331 +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-EXEC-ENVS" "7" "Sep 23, 2024" "1.3.11" "SIERRA"
-.SH NAME
-sierra-exec-envs \- The execution environments SIERRA supports.
-.SH HPC EXECUTION ENVIRONMENT PLUGINS
-.sp
-SIERRA is capable of adapting its runtime infrastructure to a number of
-different HPC environments so that experiments can be run efficiently on
-whatever computational resources a researcher has access to. Supported
-environments that come with SIERRA are listed on this page.
-.sp
-These plugins tested with the following platforms (they may work on other
-platforms out of the box too):
-.INDENT 0.0
-.IP \(bu 2
-\fI\%ARGoS Platform\fP
-.IP \(bu 2
-\fI\%ROS1+Gazebo Platform\fP
-.UNINDENT
-.sp
-SIERRA makes the following assumptions about the HPC environments corresponding
-to the plugins listed on this page:
-.SH HPC ENVIRONMENT ASSUMPTIONS
-.TS
-center;
-|l|l|.
-_
-T{
-Assumption
-T}	T{
-Rationale
-T}
-_
-T{
-All nodes allocated to SIERRA have the same # of cores (can be less than
-the total # available on each compute node). Note that this may be \fIless\fP
-than the actual number of cores available on each node, if the HPC
-environment allows node sharing, and the job SIERRA runs in is allocated
-less than the total # cores on a given node.
-T}	T{
-Simplicity: If allocated nodes had different core counts, SIERRA would
-have to do more of the work of an HPC scheduler, and match jobs to
-nodes. May be an avenue for future improvement.
-T}
-_
-T{
-All nodes have a shared filesystem.
-T}	T{
-Standard feature on HPC environments. If for some reason this is not
-true, stage 2 outputs will have to be manually placed such that it is as
-if everything ran on a common filesystem prior to running any later
-stages.
-T}
-_
-.TE
-.SS Local HPC Plugin
-.sp
-This HPC environment can be selected via \fB\-\-exec\-env=hpc.local\fP\&.
-.sp
-This is the default HPC environment in which SIERRA will run all experiments on
-the same computer from which it was launched using GNU parallel.  The #
-simultaneous simulations will be determined by:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# cores on machine / # threads per experimental run
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-If more simulations are requested than can be run in parallel, SIERRA will start
-additional simulations as currently running simulations finish.
-.sp
-No additional configuration/environment variables are needed with this HPC
-environment for use with SIERRA.
-.SS ARGoS Considerations
-.sp
-The # threads per \fI\%experimental run\fP is defined with
-\fB\-\-physics\-n\-engines\fP, and that option is required for this HPC environment
-during stage 1.
-.SS PBS HPC Plugin
-.sp
-This HPC environment can be selected via \fB\-\-exec\-env=hpc.pbs\fP\&.
-.sp
-In this HPC environment, SIERRA will run experiments spread across multiple
-allocated nodes by a PBS compatible scheduler such as Moab.  The following table
-describes the PBS\-SIERRA interface. Some PBS environment variables are used by
-SIERRA to configure experiments during stage 1,2 (see TOQUE\-PBS docs for
-meaning); if they are not defined SIERRA will throw an error.
-.SS PBS\-SIERRA interface
-.TS
-center;
-|l|l|.
-_
-T{
-PBS environment variable
-T}	T{
-SIERRA context
-T}
-_
-T{
-PBS_NUM_PPN
-T}	T{
-Used to calculate # threads per experimental run for each allocated
-compute node via:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-floor(PBS_NUM_PPN / \-\-exec\-jobs\-per\-node)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-That is, \fB\-\-exec\-jobs\-per\-node\fP is required for PBS HPC environments.
-T}
-_
-T{
-PBS_NODEFILE
-T}	T{
-Obtaining the list of nodes allocated to a job which SIERRA can direct
-GNU parallel to use for experiments.
-T}
-_
-T{
-PBS_JOBID
-T}	T{
-Creating the UUID nodelist file passed to GNU parallel, guaranteeing
-no collisions (i.e., simultaneous SIERRA invocations sharing allocated
-nodes) if multiple jobs are started from the same directory.
-T}
-_
-.TE
-.sp
-The following environmental variables are used in the PBS HPC environment:
-.TS
-center;
-|l|l|.
-_
-T{
-Environment variable
-T}	T{
-Use
-T}
-_
-T{
-\fI\%SIERRA_ARCH\fP
-T}	T{
-Used to enable architecture/OS specific builds of simulators for maximum
-speed at runtime on clusters.
-T}
-_
-T{
-\fI\%PARALLEL\fP
-T}	T{
-Used to transfer environment variables into the GNU parallel
-environment. This must be always done because PBS doesn\(aqt transfer
-variables automatically, and because GNU parallel starts another level of
-child shells.
-T}
-_
-.TE
-.SS SLURM HPC Plugin
-.sp
-\fI\%https://slurm.schedmd.com/documentation.html\fP
-.sp
-This HPC environment can be selected via \fB\-\-exec\-env=hpc.slurm\fP\&.
-.sp
-In this HPC environment, SIERRA will run experiments spread across multiple
-allocated nodes by the SLURM scheduler. The following table describes the
-SLURM\-SIERRA interface. Some SLURM environment variables are used by SIERRA to
-configure experiments during stage 1,2 (see SLURM docs for meaning); if they are
-not defined SIERRA will throw an error.
-.SS SLURM\-SIERRA interface
-.TS
-center;
-|l|l|l|.
-_
-T{
-SLURM environment variable
-T}	T{
-SIERRA context
-T}	T{
-Command line override
-T}
-_
-T{
-SLURM_CPUS_PER_TASK
-T}	T{
-Used to set # threads per experimental node for each allocated compute
-node.
-T}	T{
-N/A
-T}
-_
-T{
-SLURM_TASKS_PER_NODE
-T}	T{
-Used to set # parallel jobs per allocated compute node.
-T}	T{
-\fB\-\-exec\-jobs\-per\-node\fP
-T}
-_
-T{
-SLURM_JOB_NODELIST
-T}	T{
-Obtaining the list of nodes allocated to a job which SIERRA can direct
-GNU parallel to use for experiments.
-T}	T{
-N/A
-T}
-_
-T{
-SLURM_JOB_ID
-T}	T{
-Creating the UUID nodelist file passed to GNU parallel, guaranteeing no
-collisions (i.e., simultaneous SIERRA invocations sharing allocated nodes
-if multiple jobs are started from the same directory).
-T}	T{
-N/A
-T}
-_
-.TE
-.sp
-The following environmental variables are used in the SLURM HPC environment:
-.TS
-center;
-|l|l|.
-_
-T{
-Environment variable
-T}	T{
-Use
-T}
-_
-T{
-\fI\%SIERRA_ARCH\fP
-T}	T{
-Used to enable architecture/OS specific builds of simulators for maximum
-speed at runtime on clusters.
-T}
-_
-T{
-\fI\%PARALLEL\fP
-T}	T{
-Used to transfer environment variables into the GNU parallel
-environment. This must be done even though SLURM can transfer variables
-automatically, because GNU parallel starts another level of child
-shells.
-T}
-_
-.TE
-.SS Adhoc HPC Plugin
-.sp
-This HPC environment can be selected via \fB\-\-exec\-env=hpc.adhoc\fP\&.
-.sp
-In this HPC environment, SIERRA will run experiments spread across an ad\-hoc
-network of compute nodes. SIERRA makes the following assumptions about the
-compute nodes it is allocated each invocation:
-.INDENT 0.0
-.IP \(bu 2
-All nodes have a shared filesystem.
-.UNINDENT
-.sp
-The following environmental variables are used in the Adhoc HPC environment:
-.TS
-center;
-|l|l|l|l|.
-_
-T{
-Environment variable
-T}	T{
-SIERRA context
-T}	T{
-Command line override
-T}	T{
-Notes
-T}
-_
-T{
-\fI\%SIERRA_NODEFILE\fP
-T}	T{
-Contains hostnames/IP address of all compute nodes SIERRA can use. Same
-format as GNU parallel \fB\-\-sshloginfile\fP\&.
-T}	T{
-\fB\-\-nodefile\fP
-T}	T{
-\fI\%SIERRA_NODEFILE\fP must be defined or \fB\-\-nodefile\fP passed. If
-neither is true, SIERRA will throw an error.
-T}
-_
-.TE
-.SH AUTHOR
-John Harwell
-.SH COPYRIGHT
-2022, John Harwell
-.\" Generated by docutils manpage writer.
-.

sierra_research-1.3.11.data/data/share/man/man7/sierra-glossary.7

@@ -1,285 +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-GLOSSARY" "7" "Sep 23, 2024" "1.3.11" "SIERRA"
-.SH NAME
-sierra-glossary \- Glossary of SIERRA terminology.
-.SH GLOSSARY
-.sp
-SIERRA uses a number of common research\-related terms, perhaps in different ways
-than you are used to. They are defined here to help demystify \fIwhy\fP SIERRA
-works/is designed the way it is, and to help you find your way around.
-.INDENT 0.0
-.TP
-.B ARGoS
-A state\-of\-the\-art multi\-physics engine robotics simulator which SIERRA
-supports as a \fI\%Platform\fP\&. The ARGoS website is at
-\fI\%https://www.argos\-sim.info/index.php\fP\&.
-.TP
-.B Gazebo
-A state\-of\-the\-art robotics simulator with many features including .urdf
-robot models, realistic 3D rendering, and more. The Gazebo website is at
-\fI\%https://gazebosim.org\fP\&.
-.TP
-.B ROS1
-You know it. You either love it or hate it, but you can\(aqt escape it. The
-ROS website is at \fI\%https://wiki.ros.org\fP\&.
-.TP
-.B ROS1+Gazebo
-A \fI\%Platform\fP supported by SIERRA to use \fI\%ROS1\fP with the
-\fI\%Gazebo\fP simulator.
-.TP
-.B ROS1+Robot
-A \fI\%Platform\fP supported by SIERRA using \fI\%ROS1\fP and any robot
-which supports ROS.
-.TP
-.B Project
-The SIERRA plugin allowing you to use your code on the platform of your
-choice within the SIERRA framework. A project is mainly a set of \fB\&.yaml\fP
-configuration files, project\-specific \fI\%Batch Criteria\fP, and some
-utility classes which allow SIERRA to translate the \fB\-\-scenario\fP
-argument passed on the cmdline to sets of XML changes as part of
-\fI\%Experiment\fP definition.
-.sp
-\fBIMPORTANT:\fP
-.INDENT 7.0
-.INDENT 3.5
-The parent directories of all SIERRA project plugins must
-be on \fI\%SIERRA_PLUGIN_PATH\fP, or SIERRA won\(aqt be able
-to find them.
-.UNINDENT
-.UNINDENT
-.sp
-\fBIMPORTANT:\fP
-.INDENT 7.0
-.INDENT 3.5
-You can\(aqt share projects across \fI\%Platforms\fP, so if you want to be able to use your project
-on ROS and ARGoS (for example), you will need to create 2
-separate projects with shared python code imported into
-each as needed.
-.UNINDENT
-.UNINDENT
-.sp
-Specified via \fB\-\-project\fP on the cmdline. See \fI\%Command Line Interface\fP for
-documentation.
-.TP
-.B Tick
-A timestep. In SIERRA, physics engines will perform some number of
-iterations per tick, and after that the controllers for all agents will be
-run.
-.TP
-.B Batch Criteria
-A \fIvariable\fP you wish to use with SIERRA to measure its effect on system
-behavior. A batch criteria can has a single axis (such as
-\fI\%Population Size\fP), in which case it is
-called \fIunivariate\fP, or have two axes (such as
-\fI\%Population Size\fP and another batch
-criteria such as one defining sensor and actuator noise to apply to the
-robots), in which case it is called \fIbivariate\fP\&.
-.sp
-Univariate batch criteria have one dimension, and so the graphs produced
-by them are (usually) linegraphs with a numerical representation of the
-range for the variable on the X axis, and some other quantity of interest
-on the Y.
-.sp
-Bivariate batch criteria have two dimensions, and so the graphs produced
-by them are (usually) heatmaps with the first variable in the criteria on
-the X axis, the second on the Y, and the quantity of interest on
-the Z. Bivariate batch criteria are always built using univariate batch
-criteria as building blocks.
-.sp
-The axis/axes you select as part of the batch criteria you will use to
-define for \fI\%Batch Experiment\fP define the \fIsearch space\fP for your
-experiment: either a 1D or 2D array of \fI\%Experiments\fP\&.
-.sp
-Batch criteria define a \fIrange\fP of sets changes for one or more elements
-in a template \fB\&.xml\fP file (passed to SIERRA with
-\fB\-\-template\-input\-file\fP). For each element in the range, the changes are
-applied to the template \fB\&.xml\fP file to define
-\fI\%Experiments\fP\&. The set of defined experiments is called
-a \fI\%Batch Experiment\fP\&.
-.sp
-The batch criteria you can use depends on:
-.INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
-.IP \(bu 2
-The \fI\%Project\fP you have loaded, as each project can define their
-own batch criteria (see ln\-sierra\-tutorials\-project\-new\-bc).
-.IP \(bu 2
-The \fI\%Platform\fP you have selected, as each platform defines some
-basic batch criteria that any project/experiment can use.
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.sp
-SIERRA itself does not define any batch criteria.
-.TP
-.B Batch Experiment
-A set of \fI\%Experiments\fP each defined by XML changes
-generated by the selected \fI\%Batch Criteria\fP to a template \fB\&.argos\fP
-file passed to SIERRA during stage 1 via \fB\-\-template\-input\-file\fP\&.
-.sp
-For example, for the \fI\%Population Size\fP
-batch criteria, each experiment is defined by a single XML change to the
-provided \fB\&.argos\fP file: the number of robots in the swarm. Depending on
-the specifics you set for the \fIrange\fP of sizes you are interested in,
-several experiments will be generated from the template \fB\&.argos\fP file,
-each differing from the template in the configured swarm size.
-.TP
-.B Experiment
-A single datapoint within a \fI\%Batch Experiment\fP;
-that is a single value of the \fIthing\fP that you are interested in varying
-across some range of experiments to see what happens (or doesn\(aqt happen).
-.TP
-.B Experimental Run
-Meaning is \fI\%Platform\fP dependent.
-.sp
-For \fB\-\-platform=platform.argos\fP it is an \fI\%ARGoS\fP simulation that
-runs as part of an experiment. For \fB\-\-platform=platform.ros1gazebo\fP it
-is a \fI\%Gazebo\fP simulation that runs as part of an experiment.
-.sp
-The number of simulations which will be run by SIERRA in stage 2 and
-averaged together by SIERRA in stage 3 is controlled by \fB\-\-n\-runs\fP\&.
-.sp
-All runs in within an \fI\%Experiment\fP are identical, with the exception
-of:
-.INDENT 7.0
-.IP \(bu 2
-Different values for the XML changes resulting from the different
-experiments they are part of, as defined by the batch criteria
-generating the batch experiment.
-.IP \(bu 2
-Different random seeds
-.UNINDENT
-.TP
-.B Output .csv
-A CSV file generated as an output from a single \fI\%Experimental
-Run\fP\&. It will (probably) contain a set of columns of representing outputs
-of interest, with rows corresponding to values captured throughout the
-run.
-.TP
-.B Averaged .csv
-A CSV file generated as from averaging files from multiple
-\fI\%Experimental Runs\fP\&. It will (probably) contain a
-set of columns of representing outputs of interest, with rows
-corresponding to values captured throughout the run (i.e., a time
-series).
-.TP
-.B Collated .csv
-A CSV file created by SIERRA during stage 4 (if inter\-experiment
-graph generation is to be run). Collated CSV files contain a set
-columns, one per \fI\%Experiment\fP in the \fI\%Batch Experiment\fP\&. Each
-column is the captured value of a \fIsingle\fP column within an \fI\%Output
-\&.csv\fP\&. This is to capture a specific aspect of the behavior of the swarm
-within a batch experiment, for use in graph generation.
-.TP
-.B Summary .csv
-A CSV file created by SIERRA during stage 4 (if inter\-experiment
-graph generation is to be run). A summary CSV file created from a
-\fI\%Collated .csv\fP file by taking the last row; this usually
-corresponds to steady\-state behavior, which is what you are
-after. However, you can also capture transient behaviors by creating
-\fI\%Collated .csv\fP and \fI\%Summary .csv\fP files from captured
-\fI\%Experimental Run\fP outputs over short stretches of time\-\-SIERRA does
-not know the difference.
-.TP
-.B Inter\-Batch .csv
-A CSV file created by SIERRA during stage 5. An inter\-batch CSV
-is created by \(dqcollating\(dq columns from a \fI\%Summary .csv\fP present in
-multiple \fI\%Batch Experiments\fP into a single
-CSV. Used during stage 5.
-.TP
-.B Imagizing
-The process of turning a text file of some kind (e.g., CSV, \fB\&.gml\fP)
-into an image.
-.TP
-.B Platform
-The \fIcontext\fP in which experiments are run: either via a simulator of some
-kind, or a run\-time framework for deploying code to one or more real
-robots.
-.sp
-\fBIMPORTANT:\fP
-.INDENT 7.0
-.INDENT 3.5
-In SIERRA terminology, platform != OS. A given OS such has
-linux might support multiple platforms like ARGoS, ROS,
-etc, while a different OS like OSX might support only
-ARGoS.
-.UNINDENT
-.UNINDENT
-.TP
-.B Graph Category
-A semantic label attached to a set of graphs which are similar. For
-example, if you want to generate graphs about the different ways that
-robots allocate tasks, you might create a \fBLN_task_alloc\fP label, so that
-you can enable/disable all task allocation related graphs for one or more
-controllers easily when configuring your project.
-.TP
-.B Controller Category
-A semantic label attached to a set of controllers which are similar in
-some way. For example, if you have two controllers which use the same type
-of memory (say it\(aqs a \(dqlast N objects seen\(dq memory), you could create a
-\fBLastN\fP category, and then define controllers within it, e.g.,
-\fBLastN.Ring\fP and \fBLastN.DecayRing\fP for two controllers which have a
-ringbuffer of remembered objects and a decaying ringbuffer of remembered
-objects (i.e., an object is forgotten after some period of time even if it
-is not forced out of the ringbuffer by seeing a new object). See
-configuring your project.
-.TP
-.B Model
-A python implementation of a theoretical model of some kind. Can use
-empirical data from simulations/real robot experiments, or not, as
-needed. Intended to generate predictions of \fIsomething\fP which can then be
-plotted against empirical results for comparison.
-.TP
-.B Plugin
-A python package/module living in a directory on
-\fI\%SIERRA_PLUGIN_PATH\fP which contains functionality to extend SIERRA
-without modifying its core (i.e., customization of different parts of the
-pipeline). Plugins come in several flavors, all of which are handled
-equivalently by SIERRA:
-.INDENT 7.0
-.IP \(bu 2
-Pipeline plugins \- Plugins which provide different ways of executing
-core parts of the SIERRA pipeline (e.g., how to run experiments).
-.IP \(bu 2
-Platform plugins \- Plugins which correspond to different
-\fI\%Platforms\fP\&.
-.IP \(bu 2
-Project  plugins \- Plugins which correspond to different
-\fI\%Projects\fP\&.
-.UNINDENT
-.UNINDENT
-.SH AUTHOR
-John Harwell
-.SH COPYRIGHT
-2022, John Harwell
-.\" Generated by docutils manpage writer.
-.