Setting Up Your Own Project#

This page walks you through connecting SIERRA to your own code. By the end you will have a working sierra invocation against your own simulator or algorithm.

Note

Complete Installing SIERRA and (optionally) the Trying Out SIERRA before starting here. The trial is the fastest way to build intuition for the workflow before applying it to your own project.

Browsing the Glossary first is also worth the few minutes it takes — SIERRA uses several terms precisely, and recognising them will make the steps below easier to follow.

Step 1: Check Requirements#

Before writing any plugin code, verify your setup meets SIERRA's requirements for experimental design and output format:

If your setup doesn't meet a requirement, the requirements page explains which plugin to write to accommodate it.

Step 2: Create a Project Plugin#

A Project plugin is the bridge between your code and SIERRA. It tells SIERRA how to translate command-line arguments into experiment configuration, where to find your controller, and how to interpret --scenario.

Follow Creating a New SIERRA Project to create your project plugin. The sample projects at jharwell/sierra-sample-project.git provide working examples for every built-in engine and are a useful reference alongside that tutorial.

Note

Projects are not portable across Engines. If you want to run the same code on both ARGoS and ROS1+Gazebo, you will need two project plugins — but they can share Python code via imports.

Step 3: Invoke SIERRA#

Once your project plugin exists, you are ready to run SIERRA. Every invocation needs at least four things:

Argument

Purpose

--engine

The simulation or robot execution engine to use. See Engine (--engine) for available options.

--execenv

Where and how to run experiments (local, SLURM, AWS Batch, etc.). See Execution Environment (--execenv) for available plugins.

--batch-criteria

The independent variable you want to vary across the batch. See Create A New Batch Criteria if you need to define a new one.

--project

The project plugin to load (the one you created in Step 2).

The remaining required arguments fill in the specifics:

Argument

Purpose

--expdef-template

The template input file for your experiment. See Experiment Definition (--expdef) for supported formats and requirements.

--n-runs

How many independent runs to execute per experiment. Used to average over stochasticity; set to 1 for deterministic simulations.

--controller

The controller or algorithm to run. Project-dependent; see Project YAML Configuration for how this drives experiment generation declaratively.

--scenario

Arena size, environment type, and other contextual settings. Project-dependent; can also be derived from the batch criteria.

--sierra-root

Root directory where all SIERRA outputs will be written.
Environment variables to set before invoking

Configure the shell you will run sierra from:

  • PYTHONPATH — set this if Python cannot find the SIERRA package or your project plugin after installation.

  • SIERRA_PLUGIN_PATH — set this to the directory containing your project plugin so SIERRA can find it at runtime.

Engine-specific variables (e.g., ARGOS_PLUGIN_PATH, ROS_PACKAGE_PATH) are documented on each engine's plugin page. See Engine (--engine).

If you pass an obviously incorrect combination of arguments, SIERRA will refuse to start. For subtler errors it will abort via an assertion before doing anything substantial.

See Usage By Example for annotated invocation examples, and FAQ if you get stuck.

Step 4: Understand the Output#

SIERRA creates a sizeable directory structure under --sierra-root during a run. Read Running Experiments before your first real invocation — understanding the structure upfront will save a lot of filesystem spelunking later.

The key principle: SIERRA never deletes your data. If a directory that SIERRA needs to create already exists, it will abort during stages 1–2 rather than risk overwriting experimental results. Pass --exp-overwrite to override this when you deliberately want to rerun. See Design Philosophy for the reasoning behind this behaviour.

Next Steps#

  • Explore what you can vary — Batch Criteria explains the batch criteria system in depth.

  • Re-run individual stages — Pipeline explains how to run only stages {3,4} to regenerate graphs without re-running experiments.

  • Add more batch criteria — Create A New Batch Criteria shows how to define new variables to sweep over.

  • Scale to HPC or cloud — Execution Environment (--execenv) covers SLURM, PBS, AWS Batch, and ad-hoc cluster configurations.