Glossary

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 why SIERRA works/is designed the way it is, and to help you find your way around.

ARGoS

A state-of-the-art multi-physics engine robotics simulator which SIERRA supports as a Platform. The ARGoS website is at https://www.argos-sim.info/index.php.

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 https://gazebosim.org.

ROS1

You know it. You either love it or hate it, but you can’t escape it. The ROS website is at https://wiki.ros.org.

ROS1+Gazebo

A Platform supported by SIERRA to use ROS1 with the Gazebo simulator.

ROS1+Robot

A Platform supported by SIERRA using ROS1 and any robot which supports ROS.

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 .yaml configuration files, project-specific Batch Criteria, and some utility classes which allow SIERRA to translate the --scenario argument passed on the cmdline to sets of XML changes as part of Experiment definition.

Important

The parent directories of all SIERRA project plugins must be on SIERRA_PLUGIN_PATH, or SIERRA won’t be able to find them.

Important

You can’t share projects across Platforms, 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.

Specified via --project on the cmdline. See Command Line Interface for documentation.

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.

Batch Criteria

A variable you wish to use with SIERRA to measure its effect on system behavior. A batch criteria can has a single axis (such as Population Size), in which case it is called univariate, or have two axes (such as Population Size and another batch criteria such as one defining sensor and actuator noise to apply to the robots), in which case it is called bivariate.

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.

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.

The axis/axes you select as part of the batch criteria you will use to define for Batch Experiment define the search space for your experiment: either a 1D or 2D array of Experiments.

Batch criteria define a range of sets changes for one or more elements in a template .xml file (passed to SIERRA with --template-input-file). For each element in the range, the changes are applied to the template .xml file to define Experiments. The set of defined experiments is called a Batch Experiment.

The batch criteria you can use depends on:

• The Project you have loaded, as each project can define their own batch criteria (see Create A New Batch Criteria).

• The Platform you have selected, as each platform defines some basic batch criteria that any project/experiment can use.

SIERRA itself does not define any batch criteria.

Batch Experiment

A set of Experiments each defined by XML changes generated by the selected Batch Criteria to a template .argos file passed to SIERRA during stage 1 via --template-input-file.

For example, for the Population Size batch criteria, each experiment is defined by a single XML change to the provided .argos file: the number of robots in the swarm. Depending on the specifics you set for the range of sizes you are interested in, several experiments will be generated from the template .argos file, each differing from the template in the configured swarm size.

Experiment

A single datapoint within a Batch Experiment; that is a single value of the thing that you are interested in varying across some range of experiments to see what happens (or doesn’t happen).

Experimental Run

Meaning is Platform dependent.

For --platform=platform.argos it is an ARGoS simulation that runs as part of an experiment. For --platform=platform.ros1gazebo it is a Gazebo simulation that runs as part of an experiment.

The number of simulations which will be run by SIERRA in stage 2 and averaged together by SIERRA in stage 3 is controlled by --n-runs.

All runs in within an Experiment are identical, with the exception of:

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

• Different random seeds

Output .csv

A CSV file generated as an output from a single Experimental Run. It will (probably) contain a set of columns of representing outputs of interest, with rows corresponding to values captured throughout the run.

Averaged .csv

A CSV file generated as from averaging files from multiple Experimental Runs. 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).

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 Experiment in the Batch Experiment. Each column is the captured value of a single column within an Output .csv. This is to capture a specific aspect of the behavior of the swarm within a batch experiment, for use in graph generation.

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 Collated .csv 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 Collated .csv and Summary .csv files from captured Experimental Run outputs over short stretches of time–SIERRA does not know the difference.

Inter-Batch .csv

A CSV file created by SIERRA during stage 5. An inter-batch CSV is created by “collating” columns from a Summary .csv present in multiple Batch Experiments into a single CSV. Used during stage 5.

Imagizing

The process of turning a text file of some kind (e.g., CSV, .gml) into an image.

Platform

The context 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.

Important

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.

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 LN_task_alloc label, so that you can enable/disable all task allocation related graphs for one or more controllers easily when configuring your project.

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’s a “last N objects seen” memory), you could create a LastN category, and then define controllers within it, e.g., LastN.Ring and LastN.DecayRing 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.

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 something which can then be plotted against empirical results for comparison.

Plugin

A python package/module living in a directory on SIERRA_PLUGIN_PATH 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:

• Pipeline plugins - Plugins which provide different ways of executing core parts of the SIERRA pipeline (e.g., how to run experiments).

• Platform plugins - Plugins which correspond to different Platforms.

• Project plugins - Plugins which correspond to different Projects.