.. _reference/glossary: ======== 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. .. glossary:: :sorted: ARGoS A state-of-the-art multi-physics engine robotics simulator which SIERRA supports as an :term:`Engine`. 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 :term:`Engine` supported by SIERRA to use :term:`ROS1` with the :term:`Gazebo` simulator. ROS1+Robot A :term:`Engine` supported by SIERRA using :term:`ROS1` and any robot which supports ROS. Prefect Python-based scheduling framework for defining and executing workflows. The website is at ``_. Project The SIERRA plugin allowing you to use your code on the engine of your choice within the SIERRA framework. A project is mainly a set of ``.yaml`` configuration files, project-specific :term:`Batch Criteria`, and some utility classes which allow SIERRA to translate the ``--scenario`` argument passed on the cmdline to sets of expdef changes as part of :term:`Experiment` definition. .. IMPORTANT:: You can't share projects across :term:`Engines `, 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 :ref:`--project` on the cmdline. 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 See :ref:`concepts/batch-criteria` for a thorough explanation of batch criteria, but the short version is that they are the core of SIERRA--how to get it to DO stuff for you as you create and define an experiment which investigates a *variable* (or multiple variables) across a *range* of values, which when instantiated gives you a *batch* of experiments to run. Batch Experiment A set of :term:`Experiments` each defined by expdef changes generated by the selected :term:`Batch Criteria` to a template ``.argos`` file passed to SIERRA during stage 1 via :ref:`--expdef-template`. For example, for the :ref:`plugins/engine/argos/bc/population-size` batch criteria, each experiment is defined by a single expdef 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 :term:`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 :term:`Engine` dependent. For simulator-based engines, such as :term:`ARGoS`, each run is a simulation run. For real-world engines such as :term:`ROS1+Robot`, it is a run with physical robots. The number of runs which will be run by SIERRA in stage 2 and averaged together by SIERRA in stage 3 is controlled by :ref:`--n-runs`. All runs in within an :term:`Experiment` are identical, with the exception of: - Different values for the expdef changes resulting from the different experiments they are part of, as defined by the batch criteria generating the batch experiment. - Different random seeds Raw Output Data A csv/arrow/etc file generated as an output from a single :term:`Experimental Run`. It will (probably) contain a set of columns of representing outputs of interest, with rows corresponding to values captured throughout the run. Processed Output Data A csv/arrow/etc file generated as from averaging files from multiple :term:`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). Data Collation The process of taking a set of user-specified columns from a set of files and putting them into a single file. Comes in three flavors: - Taking one column per :term:`Experiment` in the :term:`Batch Experiment`. This is *inter-experiment* collation, and happens during stage 4. See :ref:`plugins/prod` for more info. - Taking one column per :term:`Experimental Run` in an :term:`Experiment`. This is *intra-experiment* collation, and happens during stage 3. See :ref:`plugins/proc/collate`. - Taking one column per :term:`Batch Experiment` during stage 5. This is *inter-batch* collation. See :ref:`plugins/compare` for more info. This can be visualized as follows: .. figure:: /figures/data-collation.png For use in product generation and running models. See :ref:`plugins/proc/collate` for more information. Collated Output Data A csv/arrow/etc file created by SIERRA during stage 3/4 via :term:`Data Collation`. See :ref:`plugins/proc/collate`. Batch Summary Data A csv/arrow/etc file created by SIERRA during stage 4 (if inter-experiment graph generation is to be run). Created from a :term:`Collated Output Data` file by taking the last row; this usually corresponds to things like: - Steady-state behavior - Cumulative counts of something These flavor of measures are usually what you are after. However, if you want something different you can specify it in a per-graph manner; see :ref:`plugins/prod/graphs` for more info. You can also capture transient behaviors by creating :term:`Collated Output Data` files and thus :term:`Batch Summary Data` files from captured :term:`Experimental Run` outputs over short stretches of time--SIERRA does not know the difference. Inter-Batch Data A CSV file created by SIERRA during stage 5. An inter-batch CSV is created by "collating" columns from a :term:`Batch Summary Data` present in multiple :term:`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. Engine The executor for experiments: 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, engine != OS. A given OS such has linux might support multiple engines 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 :ref:`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 :ref:`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. Imagize The process of taking a :term:`Raw Output Data` or :term:`Processed Output Data` file and turning it into a PNG/JPG file. Product Something which is of interest/value generated duration stage 4. Probably a file of some kind, like a graphical image or video. Plugin A python package/module living in a directory on :envvar:`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: - Engine plugins - Plugins which correspond to different :term:`Engines `. - Storage plugins - Plugins which correspond to different experiment output formats, and are used in translating said formats into the internal representation used by SIERRA. - Execution environment plugins - Plugins which correspond to different run-time environments in which experiments are executed. - Experiment definition plugins - Plugins which correspond to different file input formats which are used by SIERRA to create runnable experiments from a template input file. - Data processing plugins - Plugins which correspond to different ways to process :term:`Raw Output Data` files. - Project plugins - Plugins which correspond to different :term:`Projects `. - Comparator plugins - Plugins which correspond to different way to compare generated :term:`Products ` during stage 5.