Running experiments

These instructions assume that you have a working G-Cubed deployment.

Build 199 separates artefact generation from execution. setup.yaml describes standard files to generate. A maintained run_*.py script selects those files and runs the experiment.

Related YAML documentation: setup YAML, generated simulation layers, shock projections, design YAML and chartpack YAML.

Typical experiment directory

simulations/<experiment>/
├── setup.py
├── setup.yaml
├── run_experiment.py
├── design.yaml
├── chartpack.yaml
└── [simulation-layer CSV files]

The setup and run scripts have different responsibilities.

File	Responsibility
setup.yaml	Declares generated layers, targets, designs and chartpacks
setup.py	Calls the standard setup generator
layer CSV	Contains projected shock values for model variables
design.yaml	Orders the simulation layers and records event years
chartpack.yaml	Selects charts and projection series
run_experiment.py	Selects runtime resources and runs the experiment

What an experiment does

Solving a model produces a reusable, expectations-consistent model solution. The baseline applies that solution to the baseline exogenous projections and starting values. An experiment then applies one or more cumulative simulation layers to that baseline.

Each layer produces another set of projections. Comparing a layer with the baseline shows its cumulative effect. Comparing it with the preceding layer shows that layer’s marginal effect. The final projections include every layer in the design.

Solving is the computationally expensive step, particularly for larger models. Maintained run scripts can reuse a compatible solved-model file across baseline and experiment runs. Set the script’s force-resolve option when the model equations or data have changed.

1. Define or maintain simulation layers

For standard projections, declare generated layers in setup. Choose from permanent, temporary, explicit, constant-tail, phase-in and piecewise-linear shock projections.

For an optimisation or custom calculation, declare a maintained layer that the run script owns.

2. Declare design and chartpack outputs

The setup design lists layer IDs in their intended order. The setup chartpack selects reporting variables. See generate designs and generate chartpacks.

3. Generate declared artefacts

From the experiment directory, run:

python setup.py

Setup preflights the entire declaration, then atomically replaces only its declared generated outputs. There is no overwrite prompt. Inspect the generated CSV and YAML files before running the experiment.

4. Configure and run the maintained script

Open run_experiment.py and review the clearly marked client-configuration settings near the top. From the experiment directory, run:

python run_experiment.py

The run script reads the generated or maintained artefacts directly. It does not read setup.yaml and continues to work if the setup files are removed.

Other run types

• run_baseline.py produces the baseline projections.
• run_optimisation.py adjusts controls to fit declared targets.
• run_fixed_point.py manages an external fixed-point calculation.
• A report-only run can reuse existing projections without solving again.

Start from the corresponding maintained build 199 example. Keep algorithm, cache, result-path and fixed-point settings in the run script, not setup YAML.

See setting up baselines and experiments for the complete authoring sequence.

Results

Run scripts write results beneath results/<VERSION>/<BUILD>/<experiment name>/. A normal run includes:

• run.log, which records progress and errors;
• HTML reports in html_reports/; and
• the CSV data underlying the reports in projections_data/.

Open an HTML report in a browser to review its charts and tables. In a Codespace, find the file in the VS Code Explorer, right-click it and select Download to save a copy to your computer. The Getting started recipe shows the exact folders for the public 2R baseline and example experiment. See Reporting for how G-Cubed creates the CSV and HTML outputs, including charts and optional derived variables.