ARGoS Engine#

https://www.argos-sim.info/index.php. Requires ARGoS >= 3.0.0-beta59.

This engine can be selected via --engine=engine.argos.

This is the default engine on which SIERRA will run experiments, and uses the ARGoS simulator. It cannot be used to run experiments on real robots.

Requirements#

  1. All swarms are homogeneous (i.e., only contain 1 type of robot) if the size of the swarm changes across experiments (e.g., 1 robot in exp0, 2 in exp1, etc.). While SIERRA does not currently support multiple types of robots with varying swarm sizes, adding support for doing so would not be difficult. As a result, SIERRA assumes that the type of the robots you want to use is already set in the template input file (e.g., <entity/foot-bot>) when using SIERRA to change the swarm size.

  2. The distribution method via <distribute> in the .argos file is the same for all robots, and therefore only one such tag exists (not checked).

#. The <XXX_controller> tag representing the configuration for the --controller you want to use does not exist verbatim in the --expdef-template. Instead, a placeholder __CONTROLLER__ is used so that SIERRA can unambiguously set the "library" attribute of the controller; the __CONTROLLER__ tag will replaced with the ARGoS name of the controller you selected via --controller specified in the controllers.yaml configuration file by SIERRA. You should have something like this in your template input file:

<argos-configuration>
   ...
   <controllers>
      ...
      <__CONTROLLER__>
         <param_set1>
            ...
         </param_set1>
         ...
      <__CONTROLLER__/>
      ...
   </controllers>
   ...
</argos-configuration>

See also Project YAML Configuration.

  1. --project matches the name of the C++ library for the project (i.e. --project.so), unless library_name is present in sierra.main.run YAML config. See Project YAML Configuration for details. For example if you pass --project=project-awesome, then SIERRA will tell ARGoS to search in project-awesome.so for both loop function and controller definitions via XML changes, unless you specify otherwise in project configuration. You cannot put the loop function/controller definitions in different libraries.

  2. ARGOS_PLUGIN_PATH is set up properly prior to invoking SIERRA.

OS Packages#

apt-get install xvfb # only needed for --engine-vc

brew install --cask xquartz # Only needed for --engine-vc

Note that you also need to install ARGoS.

Usage#

Batch Criteria#

The following batch criteria are defined which can be used with any ARGoS-based Project.

Cmdline Interface#

sierra - CLI interface#

sierra [--exp-setup EXP_SETUP] [--physics-engine-type2D {dynamics2d}]
       [--physics-engine-type3D {dynamics3d}] [--physics-n-engines {1,2,4,6,8,12,16,24}]
       [--physics-iter-per-tick PHYSICS_ITER_PER_TICK] [--physics-spatial-hash2D]
       [--camera-config {overhead,sw,sw+interp}] [--with-robot-rab] [--with-robot-leds]
       [--with-robot-battery] [--n-agents N_AGENTS]
sierra Stage 1 options#

Options for generating experiments

  • --exp-setup EXP_SETUP -

    Defines experiment run length, Ticks per second for the experiment (<experiment> tag). See Experiment Setup for a full description.

    (default: exp_setup.T5000.K5)

  • --physics-engine-type2D PHYSICS_ENGINE_TYPE2D -

    The type of 2D physics engine to use for managing spatial extents within the arena, choosing one of the types that ARGoS supports. The precise 2D areas (if any) within the arena which will be controlled by 2D physics engines is defined on a per --project basis.

    (default: dynamics2d)

  • --physics-engine-type3D PHYSICS_ENGINE_TYPE3D -

    The type of 3D physics engine to use for managing 3D volumetric extents within the arena, choosing one of the types that ARGoS supports. The precise 3D volumes (if any) within the arena which will be controlled by 3D physics engines is defined on a per --project basis.

    (default: dynamics3d)

  • --physics-n-engines PHYSICS_N_ENGINES -

    # of physics engines to use during simulation (yay ARGoS!). If N > 1, the engines will be tiled in a uniform grid within the arena (X and Y spacing may not be the same depending on dimensions and how many engines are chosen, however), extending upward in Z to the height specified by --scenario (i.e., forming a set of "silos" rather that equal volumetric extents).

    If 2D and 3D physics engines are mixed, then half of the specified # of engines will be allocated among all arena extents cumulatively managed by each type of engine. For example, if 4 engines are used, with 1/3 of the arena managed by 2D engines and 2/3 by 3D, then 2 2D engines will manage 1/3 of the arena, and 2 3D engines will manage the other 2/3 of the arena.

    If --execenv is something other than hpc.local then the # physics engines will be computed from the HPC environment, and the cmdline value (if any) will be ignored.

    Important

    When using multiple physics engines, always make sure that # engines / arena dimension (X AND Y dimensions) is always a rational number. That is,

    • 24 engines in a 12x12 arena will be fine, because 12/24=0.5, which can be represented reasonably well in floating point.

    • 24 engines in a 16x16 arena will not be fine, because 16/24=0.666667, which will very likely result in rounding errors and ARGoS being unable to initialize the space because it can't place arena walls.

    This is enforced by SIERRA.

    (default: None)

  • --physics-iter-per-tick PHYSICS_ITER_PER_TICK -

    The # of iterations all physics engines should perform per Tick each time the controller loops are run (the # of ticks per second for controller control loops is set via --exp-setup).

    (default: 10)

  • --physics-spatial-hash2D -

    Specify that each 2D physics engine should use a spatial hash (only applies to dynamics2d engine type).

  • --camera-config CAMERA_CONFIG -

    Select the camera configuration for simulation. Ignored unless --engine-vc is passed. Valid values are:

    • overhead - Use a single overhead camera at the center of the aren looking straight down at an appropriate height to see the whole arena.

    • sw - Use the ARGoS camera configuration (12 cameras), cycling through them periodically throughout simulation without interpolation.

    • sw+interp - Same as sw, but with interpolation between cameras.

    (default: overhead)

  • --with-robot-rab -

    If passed, do not remove the Range and Bearing (RAB) sensor, actuator, and medium XML definitions from --expdef-template before generating experimental inputs. Otherwise, the following XML tags are removed if they exist:

    • .//media/range_and_bearing

    • .//actuators/range_and_bearing

    • .//sensors/range_and_bearing

  • --with-robot-leds -

    If passed, do not remove the robot LED actuator XML definitions from the --expdef-template before generating experimental inputs. Otherwise, the following XML tags are removed if they exist:

    • .//actuators/leds

    • .//medium/leds

    • .//sensors/colored_blob_omnidirectional_camera

  • --with-robot-battery -

    If passed, do not remove the robot battery sensor XML definitions from --expdef-template before generating experimental inputs. Otherwise, the following XML tags are removed if they exist:

    • .//entity/*/battery

    • .//sensors/battery

  • --n-agents N_AGENTS -

    The # agents (robots) that should be used in the simulation. Can be used to override batch criteria, or to supplement experiments that do not set it so that manual modification of input file is unneccesary.

    (default: None)

Environment Variables#

This engine respects SIERRA_ARCH.

Execution Environments#

The # threads per experimental run is defined with --physics-n-engines, and that option is required for the --execenv=hpc.local environment during stage 1. This engine supports:

Others may work but are untested.

Random Seeding For Reproducibility#

ARGoS provides its own random seed mechanism under <experiment> which SIERRA uses to seed each experiment. Project code should use this mechanism or a similar random seed generator manager seeded by the same value so that experiments can be reproduced exactly. By default SIERRA does not overwrite its generated random seeds for each experiment once generated; you can override with --no-preserve-seeds.

Visual Capture and Rendering#

This engine can render it's simulation environment offscreen into a virtual buffer using Xvfb, and output captured frames as PNG images during stage 2, which can then be rendered into per-run videos during stage 4 (see Rendering for more details).

Important

During stage 1 --engine-vc causes the ARGoS Qt/OpenGL <visualization> subtree to be added to the --expdef-template when generating experimental inputs; it is removed otherwise. If <visualization> already exists, it is removed and re-created.

To use:

  • Install Xvfb so that it can installed/can be found by the shell during stage 2.

  • Pass --engine-vc during stage 2. This will slow ARGoS down a LOT, so if you use it, --n-runs should probably be low, unless you have gobs of computing power available. ARGoS will output captured frames to frames/ in each experimental run output directory.

  • Pass --engine-vc during stage 4, which causes frames captured during stage 2 to be stitched together into a unique video file using ffmpeg (precise command configurable via --render-cmd-opts), and output under <batch_root>/videos/<exp>.