Creating a New SIERRA Project

  1. Decide what Platform your Project will target. Currently, there is no way to share projects across platforms; any common code will have to be put into common python files and imported as needed.

  2. Create the directory which will hold your Project. The directory your project must be on SIERRA_PLUGIN_PATH or SIERRA won’t be able to find your project. For example, if your project is proj-awesome, and that directory is in projects as /path/to/projects/proj-awesome, then /path/to/projects needs to be on SIERRA_PLUGIN_PATH.

  3. Create the following directory structure within your project directory (or copy and modify the one from an existing project).

    Important

    Once you create the directory structure below you need to INSTALL your project with pip so that not only can SIERRA find it, but so can the python interpreter. If you don’t want to do that, then you need to put your project plugin directory on PYTHONPATH. Otherwise, you won’t be able to use your project plugin with SIERRA.

    • config/ - Plugin YAML configuration root. This directory is required for all projects. Within this directory, the following files are used (not all files are required when running a stage that utilizes them):

      • main.yaml - Main SIERRA configuration file. This file is required for all pipeline stages. See Main Configuration for documentation.

      • controllers.yaml - Configuration for controllers (input file/graph generation). This file is required for all pipeline stages. See Main Configuration for documentation.

      • intra-graphs-line.yaml - Configuration for intra-experiment linegraphs. This file is optional. If it is present, graphs defined in it will be added to those specified in <sierra>/core/config/intra-graphs-line.yaml, and will be generated if stage 4 is run. See Graph Configuration for documentation.

      • intra-graphs-hm.yaml - Configuration for intra-experiment heatmaps. This file is optional. If it is present, graphs defined in it will be added to those specified in <sierra>/core/config/intra-graphs-hm.yaml, and will be generated if stage 4 is run. See Graph Configuration for documentation.

      • inter-graphs.yaml - Configuration for inter-experiment graphs. This file is optional. If it is present, graphs defined in it will be added to those specified in <sierra>/core/config/inter-graphs-line.yaml, and will be generated if stage 4 is run. See Graph Configuration for documentation.

      • stage5.yaml - Configuration for stage5 controller comparisons. This file is required if stage 5 is run, and optional otherwise. See Stage 5 Configuration for documentation.

      • models.yaml - Configuration for intra- and inter-experiment models. This file is optional. If it is present, models defined and enabled in it will be run before stage 4 intra- and/or inter-experiment graph generation, if stage 4 is run. See Adding Models to your SIERRA Project for documentation.

    • generators/ - Classes to enable SIERRA to generate changes to template XML files needed by your project. This directory is required for all SIERRA projects.

      • scenario_generator_parser.py - Contains the parser for parsing the contents of --scenario into a dictionary which can be used to configure experiments. This file is required. See Per-Scenario Configuration for documentation.

      • scenario_generators.py - Specifies classes and functions to enable SIERRA to generate XML file modifications to the --template-input-file based on what is passed as --scenario on the cmdline. This file is required. See Per-Scenario Configuration for documentation.

      • exp_generators.py - Contains extensions to the per-Experiment and per-Experimental Run configuration that SIERRA performs. See Per-Experimental Run Configuration for documentation. This file is optional.

    • variables/ - Additional variables (including batch criteria) defined by the plugin/project that can be directly or indirectly used by the --batch-criteria and --scenario cmdline arguments. This directory is optional.

    • models/ - Theoretical models that you want to run against empirical data from experimental runs (presumably to compare predictions with). This directory is optional. See Adding Models to your SIERRA Project for documentation.

    • cmdline.py - Specifies cmdline extensions specific to the plugin/project. This file is required. See Extending the SIERRA Cmdline for documentation.

#. Configure your project so SIERRA understands how to generate Experimental Run inputs and process outputs correctly by following Main Configuration.

  1. Define graphs to be generated from Experiment outputs by following Graph Configuration. Strictly speaking this is optional, but automated graph generation during stage 4 is one of the most useful parts of SIERRA, so its kind of silly if you don’t do this.

  2. Setup your --template-input-file appropriately by following Template Input Files.

Optional Steps

  1. Define additional batch criteria to investigate variables of interest specific to your project by following Create A New Batch Criteria.

  2. Define one or more Models to run to compare with empirical data.

  3. Add additional per-run configuration such as unique output directory names, random seeds, etc. in various python files referenced by scenario_generators.py and exp_generators.py beyond what is required for --scenario. SIERRA can’t set stuff like this up in a project agnostic way.