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-examples.7

@@ -1,508 +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-EXAMPLES" "7" "Sep 23, 2024" "1.3.11" "SIERRA"
-.SH NAME
-sierra-examples \- Examples of SIERRA usage. These examples all assume that you have successfully set up SIERRA with a project of your choice.
-.sp
-This page contains reference examples of SIERRA usage to help you craft your own
-SIERRA invocation.  These examples use the SIERRA project plugins from the
-SIERRA sample project repo: \fI\%https://github.com/jharwell/sierra\-sample\-project.git\fP\&. See
-\fI\%Trying Out SIERRA\fP or \fI\%Getting Started With SIERRA\fP for setting up the
-sample project repository.
-.sp
-In all examples:
-.INDENT 0.0
-.IP \(bu 2
-\fB$HOME/git/mycode\fP contains the ARGoS C++ library
-.IP \(bu 2
-\fB$HOME/git/sierra\-sample\-project/projects\fP contains the SIERRA project
-plugin
-.IP \(bu 2
-\fB$HOME/git/sierra\-sample\-project/projects\fP is on
-\fI\%SIERRA_PLUGIN_PATH\fP\&.
-.UNINDENT
-.sp
-If your setup is different, adjust paths in the commands below as needed.
-.sp
-\fBIMPORTANT:\fP
-.INDENT 0.0
-.INDENT 3.5
-The examples are grouped by platform, so they can be pasted into
-the terminal and executed directly. However, parts of many
-commands use common functionality in the SIERRA core; just
-because you don\(aqt see stage5 examples for the ROS1+Gazebo
-platform doesn\(aqt mean you can\(aqt run stage5 with that
-platform. Non\-uniformities in which commands are below are more a
-limitation of the sample project than SIERRA itself.
-.UNINDENT
-.UNINDENT
-.SH ARGOS EXAMPLES
-.SS Basic Example
-.sp
-This example illustrates the simplest way to use ARGoS with SIERRA to run
-experiments.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-sierra\-cli \e
-\-\-sierra\-root=$HOME/exp \e
-\-\-template\-input\-file=exp/your\-experiment.argos \e
-\-\-n\-runs=3 \e
-\-\-platform=platform.argos\e
-\-\-project=argos_project \e
-\-\-exec\-env=hpc.local \e
-\-\-physics\-n\-engines=1 \e
-\-\-exp\-setup=exp_setup.T10000 \e
-\-\-controller=foraging.footbot_foraging\e
-\-\-scenario=LowBlockCount.10x10x2 \e
-\-\-batch\-criteria population_size.Log64
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This will run a batch of 7 experiments using a correlated random walk robot
-controller (CRW), across which the swarm size will be varied from 1..64, by
-powers of 2. Experiments will all be run in the same scenario: \fBLowBlockCount\fP
-in a 10x10x2 arena; the meaning of \fBLowBlockCount\fP is entirely up to the
-project. In this case, we can infer it has to do with the # of blocks available
-for robots to forage for. In fact, whatever is passed to \fB\-\-scenario\fP is
-totally arbitrary from SIERRA\(aqs point of view.
-.sp
-Within each experiment, 3 copies of each simulation will be run (each with
-different random seeds), for a total of 21 ARGoS simulations. On a reasonable
-machine it should take about 10 minutes or so to run. After it finishes, you can
-go to \fB$HOME/exp\fP and find all the simulation outputs. For an explanation of
-SIERRA\(aqs runtime directory tree, see \fI\%SIERRA Runtime Directory Tree\fP\&.
-.SS HPC Example
-.sp
-In order to run on a SLURM managed cluster, you need to invoke SIERRA within a
-script submitted with \fBsbatch\fP, or via \fBsrun\fP with the correspond cmdline
-options set.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-#!/bin/bash \-l
-#SBATCH \-\-time=01:00:00
-#SBATCH \-\-nodes 10
-#SBATCH \-\-tasks\-per\-node=6
-#SBATCH \-\-cpus\-per\-task=4
-#SBATCH \-\-mem\-per\-cpu=2G
-#SBATCH \-\-output=R\-%x.%j.out
-#SBATCH \-\-error=R\-%x.%j.err
-#SBATCH \-J argos\-slurm\-example
-
-# setup environment
-export ARGOS_INSTALL_PREFIX=/$HOME/.local
-export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ARGOS_INSTALL_PREFIX/lib/argos3
-export ARGOS_PLUGIN_PATH=$ARGOS_INSTALL_PREFIX/lib/argos3:$HOME/git/mycode
-export SIERRA_PLUGIN_PATH=$HOME/git/sierra\-projects
-export PARALLEL=\(dq\-\-env ARGOS_PLUGIN_PATH \-\-env LD_LIBRARY_PATH\(dq
-
-sierra\-cli \e
-\-\-sierra\-root=$HOME/exp \e
-\-\-template\-input\-file=exp/your\-experiment.argos \e
-\-\-n\-runs=96 \e
-\-\-platform=platform.argos\e
-\-\-project=argos_project \e
-\-\-exec\-env=hpc.slurm \e
-\-\-exp\-setup=exp_setup.T10000 \e
-\-\-controller=foraging.footbot_foraging \e
-\-\-scenario=LowBlockCount.10x10x2 \e
-\-\-batch\-criteria population_size.Log64
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-In this example, the user requests 10 nodes with 24 cores each, and wants to run
-ARGoS with 4 physics engines ( 4 * 6 = 24), with 8GB memory per core. Note that
-we don\(aqt pass \fB\-\-physics\-n\-engines\fP \-\- SIERRA computes this from the SLURM
-parameters. SIERRA will run each of the 96 simulations per experiment in
-parallel, 6 at a time on each allocated node.  Each simulation will be 10,000
-seconds long and use \fBLowBlockCount\fP scenario in a 10x10x2 arena, as in the
-previous example.
-.sp
-\fBIMPORTANT:\fP
-.INDENT 0.0
-.INDENT 3.5
-You need to export \fI\%PARALLEL\fP containing all necessary
-environment variables your code uses in addition to those needed
-by SIERRA before invoking it, otherwise some of them might not be
-transferred to the SLURM job and/or the new shell GNU parallel
-starts each simulation in.
-.UNINDENT
-.UNINDENT
-.sp
-Note that if you compile ARGoS for different architectures within the same HPC
-environment, you can use a combination of conditionally setting
-\fI\%ARGOS_PLUGIN_PATH\fP with setting \fI\%SIERRA_ARCH\fP to some string to
-tell SIERRA to use a given version of ARGoS, depending on where you request
-resources from. For example, you could set \fBSIERRA_ARCH=x86\fP or
-\fBSIERRA_ARCH=arm\fP to link to an \fBargos3\-x86\fP or \fBargos3\-arm\fP executable
-and libraries, respectively.
-.SS Rendering Example
-.sp
-This example shows how to use ARGoS image capturing ability to create nice
-videos of simulations.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-sierra\-cli \e
-\-\-sierra\-root=$HOME/exp \e
-\-\-template\-input\-file=exp/your\-experiment.argos \e
-\-\-platform=platform.argos\e
-\-\-project=argos_project \e
-\-\-controller=foraging.footbot_foraging \e
-\-\-scenario=LowBlockCount.10x10x2 \e
-\-\-exec\-env=hpc.local \e
-\-\-n\-runs=3 \e
-\-\-platform\-vc \e
-\-\-exp\-graphs=none \e
-\-\-physics\-n\-engines=1 \e
-\-\-batch\-criteria population_size.Log8
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The runs 3 simulations in parallel with 1 physics engine each, and runs ARGoS
-under \fBXvfb\fP to get it to render headless images. During stage 4, these
-images are stitched together using \fBffmpeg\fP to create videos (see
-\fI\%SIERRA Runtime Directory Tree\fP for where the videos will appear). No
-graphs are generated during stage 4 in this example.
-.sp
-You may also be interested in the \fB\-\-camera\-config\fP option, which allows you
-to specify different static/dynamic camera arrangements (e.g., do a nice
-circular pan around the arena during simulation).
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-Because LOTS of images can be captured by ARGoS to create videos,
-depending on simulation length, you usually want to have a very small
-\fB\-\-n\-runs\fP to avoid filling up the filesystem.
-.UNINDENT
-.UNINDENT
-.SS Bivariate Batch Criteria Example
-.sp
-This example shows how to use ARGoS with a bivariate batch criteria (i.e., with
-TWO variables/things you want to vary jointly):
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-sierra\-cli \e
-\-\-sierra\-root=$HOME/exp \e
-\-\-template\-input\-file=exp/your\-experiment.argos \e
-\-\-platform=platform.argos\e
-\-\-project=argos_project \e
-\-\-controller=foraging.footbot_foraging \e
-\-\-scenario=LowBlockCount.10x10x2 \e
-\-\-exec\-env=hpc.local \e
-\-\-n\-runs=3 \e
-\-\-platform\-vc \e
-\-\-exp\-graphs=none \e
-\-\-physics\-n\-engines=1 \e
-\-\-batch\-criteria population_size.Log8 max_speed.1.9.C5
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The \fBmax_speed.1.9.C5\fP is a batch criteria defined in the sample project, and
-corresponds to setting the maximum robot speed from 1...9 to make 5 experiments;
-i.e., 1,3,5,7,9. It can also be used on its own\-\-just remove the first
-\fBpopulation_size\fP batch criteria from the command to get a univariate example.
-.sp
-The generated experiments form a grid: population size on the X axis and max
-speed on the Y, for a total of 3 * 5 = 15 experiments. If the order of the batch
-criteria is switched, then so is which criteria/variable is on the X/Y
-axis. Experiments are run in sequence just as with univariate batch
-criteria. During stage 3/4, by default SIERRA generates discrete a set of
-heatmaps, one per capture interval of simulated time, because the experiment
-space is 2D instead of 1D, and you can\(aqt easily represent time AND two
-variables + time on a plot. This can take a loooonnnggg time, and can be
-disabled with \fB\-\-project\-no\-HM\fP\&.
-.sp
-The generated sequence of heatmaps can be turned into a video\-\-pass
-\fB\-\-bc\-rendering\fP during stage 4 to do so.
-.SS Stage 5 Scenario Comparison Example
-.sp
-This example shows how to run stage 5 to compare a single controller across
-different scenarios, assuming that stages 1\-4 have been run successfully. Note
-that this stage does not require you to input the \fB\-\-scenario\fP, or the
-\fB\-\-batch\-criteria\fP; SIERRA figures these out for you from the \fB\-\-controller\fP
-and \fB\-\-sierra\-root\fP\&.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-sierra\-cli \e
-\-\-sierra\-root=$HOME/exp \e
-\-\-project=argos_project \e
-\-\-pipeline 5 \e
-\-\-scenario\-comparison \e
-\-\-dist\-stats=conf95 \e
-\-\-bc\-univar \e
-\-\-controller=foraging.footbot_foraging \e
-\-\-sierra\-root=$HOME/exp
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This will compare all scenarios that the
-\fBforaging.footbot_foraging\fP controller has been run on according to
-the configuration defined in \fBstage5.yaml\fP\&. SIERRA will plot the 95%
-confidence intervals on all generated graphs for the univariate batch criteria
-(whatever it was). If multiple batch criterias were used with this controller in
-the same scenario, SIERRA will process all of them and generate unique graphs
-for each scenario+criteria combination that the
-\fBforaging.footbot_foraging\fP controller was run on.
-.SS Stage 5 Controller Comparison Example
-.sp
-This example shows how to run stage 5 to compare multiple controllers in a
-single scenario, assuming that stages 1\-4 have been run successfully. Note that
-this stage does not require you to input \fB\-\-batch\-criteria\fP; SIERRA figures
-these out for you from the \fB\-\-controller\-list\fP and \fB\-\-sierra\-root\fP\&.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-sierra\-cli \e
-\-\-sierra\-root=$HOME/exp \e
-\-\-project=argos_project \e
-\-\-pipeline 5 \e
-\-\-controller\-comparison \e
-\-\-dist\-stats=conf95 \e
-\-\-bc\-univar \e
-\-\-controllers\-list=foraging.footbot_foraging,foraging.footbot_foraging\-slow \e
-\-\-sierra\-root=$HOME/exp
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-SIERRA will compute the list of scenarios that the \fBforaging.footbot_foraging\fP
-and the \fBforaging.footbot_foraging_slow\fP controllers have \fIall\fP been
-run. Comparison graphs for each scenario with the
-\fBforaging.footbot_foraging,foraging.footbot_foraging_slow\fP controllers will be
-generated according to the configuration defined in \fBstage5.yaml\fP\&. SIERRA will
-plot the 95% confidence intervals on all generated graphs for the univariate
-batch criteria (whatever it was). If multiple batch criterias were used with
-each controller in the same scenario, SIERRA will process all of them and
-generate unique graphs for each scenario+criteria combination both controllers
-were run on.
-.SH ROS1+GAZEBO EXAMPLES
-.SS Basic Example
-.sp
-This examples shows the simplest way to use SIERRA with the ROS1+gazebo platform
-plugin:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-sierra\-cli \e
-\-\-platform=platform.ros1gazebo \e
-\-\-project=ros1gazebo_project \e
-\-\-n\-runs=4 \e
-\-\-exec\-env=hpc.local \e
-\-\-template\-input\-file=exp/your\-experiment.launch \e
-\-\-scenario=HouseWorld.10x10x1 \e
-\-\-sierra\-root=$HOME/exp/test \e
-\-\-batch\-criteria population_size.Log8 \e
-\-\-controller=turtlebot3_sim.wander \e
-\-\-exp\-overwrite \e
-\-\-exp\-setup=exp_setup.T10 \e
-\-\-robot turtlebot3
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This will run a batch of 4 experiments using a correlated random walk controller
-(CRW) on the turtlebot3. Population size will be varied from 1..8, by powers
-of 2. Within each experiment, 4 copies of each simulation will be run (each with
-different random seeds), for a total of 16 Gazebo simulations. Each experimental
-run will be will be 10 seconds of simulated time. On a reasonable machine it
-should take about 10 minutes or so to run. After it finishes, you can go to
-\fB$HOME/exp\fP and find all the simulation outputs. For an explanation of
-SIERRA\(aqs runtime directory tree, see \fI\%SIERRA Runtime Directory Tree\fP\&.
-.SS HPC Example
-.sp
-In order to run on a SLURM managed cluster, you need to invoke SIERRA within a
-script submitted with \fBsbatch\fP, or via \fBsrun\fP with the correspond cmdline
-options set.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-#!/bin/bash \-l
-#SBATCH \-\-time=01:00:00
-#SBATCH \-\-nodes 4
-#SBATCH \-\-tasks\-per\-node=6
-#SBATCH \-\-cpus\-per\-task=4
-#SBATCH \-\-mem\-per\-cpu=2G
-#SBATCH \-\-output=R\-%x.%j.out
-#SBATCH \-\-error=R\-%x.%j.err
-#SBATCH \-J ros1gazebo\-slurm\-example
-
-# setup environment
-export SIERRA_PLUGIN_PATH=$HOME/git/sierra\-projects
-
-sierra\-cli \e
-\-\-platform=platform.ros1gazebo \e
-\-\-project=ros1gazebo_project \e
-\-\-n\-runs=96 \e
-\-\-exec\-env=hpc.slurm \e
-\-\-template\-input\-file=exp/your\-experiment.launch \e
-\-\-scenario=HouseWorld.10x10x1 \e
-\-\-sierra\-root=$HOME/exp/test \e
-\-\-batch\-criteria population_size.Log8 \e
-\-\-controller=turtlebot3_sim.wander \e
-\-\-exp\-overwrite \e
-\-\-exp\-setup=exp_setup.T10000 \e
-\-\-robot turtlebot3
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-In this example, the user requests 10 nodes with 24 cores each. SIERRA will run
-each of the 96 runs in parallel, 24 at a time on each allocated node.  Each
-simulation will be 1,000 seconds long and use same scenario as before.
-.sp
-\fBIMPORTANT:\fP
-.INDENT 0.0
-.INDENT 3.5
-You need to export \fI\%PARALLEL\fP containing all necessary
-environment variables your code uses in addition to those needed
-by SIERRA before invoking it, otherwise some of them might not be
-transferred to the SLURM job and/or the new shell GNU parallel
-starts each simulation in.
-.UNINDENT
-.UNINDENT
-.SS Bivariate Batch Criteria Example
-.sp
-This example shows how to use ROS1+gazebo with a bivariate batch criteria (i.e.,
-with TWO variables/things you want to vary jointly):
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-sierra\-cli \e
-\-\-sierra\-root=$HOME/exp \e
-\-\-template\-input\-file=exp/your\-experiment.argos \e
-\-\-platform=platform.ros1gazebo\e
-\-\-project=ros1gazebo_project \e
-\-\-controller=turtlebot3_sim.wander \e
-\-\-scenario=HouseWorld.10x10x2 \e
-\-\-exec\-env=hpc.local \e
-\-\-n\-runs=3 \e
-\-\-exp\-graphs=none \e
-\-\-batch\-criteria population_size.Log8 max_speed.1.9.C5
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The \fBmax_speed.1.9.C5\fP is a batch criteria defined in the sample project, and
-corresponds to setting the maximum robot speed from 1...9 to make 5 experiments;
-i.e., 1,3,5,7,9. It can also be used on its own\-\-just remove the first
-\fBpopulation_size\fP batch criteria from the command to get a univariate example.
-.sp
-The generated experiments form a grid: population size on the X axis and max
-speed on the Y, for a total of 3 * 5 = 15 experiments. If the order of the batch
-criteria is switched, then so is which criteria/variable is on the X/Y
-axis. Experiments are run in sequence just as with univariate batch
-criteria. During stage 3/4, by default SIERRA generates discrete heatmaps of
-results instead of linegraphs, because the experiment space is 2D instead of 1D.
-.SH ROS1+ROBOT EXAMPLES
-.SS Basic Example
-.sp
-This examples shows the simplest way to use SIERRA with the ROS1+robot platform
-plugin:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-sierra\-cli \e
-\-\-platform=platform.ros1robot \e
-\-\-project=ros1robot_project \e
-\-\-n\-runs=4 \e
-\-\-template\-input\-file=exp/your\-experiment.launch \e
-\-\-scenario=OutdoorWorld.16x16x2 \e
-\-\-sierra\-root=$HOME/exp/test \e
-\-\-batch\-criteria population_size.Linear6.C6 \e
-\-\-controller=turtlebot3.wander \e
-\-\-robot turtlebot3 \e
-\-\-exp\-setup=exp_setup.T100 \e
-\-\-exec\-env=robot.turtlebot3 \e
-\-\-nodefile=turtlebots.txt
-\-\-exec\-inter\-run\-pause=60 \e
-\-\-no\-master\-node \e
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This will run a batch of 4 experiments using a correlated random walk controller
-(CRW) on the turtlebot3. Population size will be varied from 1,2,3,4,5,6. Within
-each experiment, 4 experimental runs will be conducted with each swarm
-size. SIERRA will pause for 60 seconds between runs so you can reset the robot\(aqs
-positions and environment before continuing with the next
-run. \fBturtlebots3.txt\fP contains the IP addresses of all 6 robots in the swarm
-(SIERRA may use different combinations of these if the swarm size is < 6).  You
-could also omit \fB\-\-nodefile\fP and set \fI\%SIERRA_NODEFILE\fP instead.
-.sp
-For these experiments, no master node is needed, so it is disabled. After all
-runs have completed and SIERRA finishes stages 3 and 4, you can go to
-\fB$HOME/exp\fP and find all the simulation outputs. For an explanation of
-SIERRA\(aqs runtime directory tree, see \fI\%SIERRA Runtime Directory Tree\fP\&.
-.SH AUTHOR
-John Harwell
-.SH COPYRIGHT
-2022, John Harwell
-.\" Generated by docutils manpage writer.
-.