Running G-Cubed experiments

Table of contents

These instructions assume that you have a working dev container virtual machine set up in a Github Codespace or similar environment.

The model experiments are contained in the model’s python directory at /workspace/gcubed-2R/python. The model’s configuration files are in the user_data directory at /workspace/user_data/2R/178/python.

Each experiment is a Python file with a run_ filename prefix, for example The experiments run G-Cubed simulations.

Running an experiment

There are two ways to run an experiment.

You can run an experiment by opening the python file for the experiment in your VSCode editor. A small arrow will appear in the top right corner of the open window. The experiment will run if you click on that small arrow. A terminal will open at the bottom of the VSCode window and you will see the logs of the experiment as it runs.

Alternatively you can run an experiment from the commandline e.g.:


Typically, experiments are run using a Runner object. There are a number of Runner classes. They run the experiment and save the results to the results directory. A Runner will run an entire experiment, using a model solution and building on a set of baseline projections by sequentially applying the sequence of simulation layers to those baseline projections.

The projections associated with the application of each simulation layer are preserved as a Projections object. To access the full list of projections produced when running an experiment, access the Runner.all_projections property. Each Projections object provides access to the projections implied by the baseline and the cumulative impact of the simulation layers up to and including its own simulation layer.

In this way, the Runner object provides a way to analyse the marginal and cumulative impacts of each simulation layer. To assess the marginal impact of a simulation layer work with deviations of the simulation layer’s projections from the projections associated with the previous simulation layer. To assess the cumulative impact of all simulation layers up to and including the simulation layer of interest, work with deviations of that simulation layer’s projections from the baseline projections.

Experiment results

Experiments are saved to the results directory in /workspace/user_data/results/2R/178/<experiment script name>. Thus, running, the results will be available in /workspace/user_data/results/2R/178/run_fast_experiment1.

The results directory will contain the run.log file and any CSV projections files (in levels or deviations) that were produced by the experiment.

The projections produced by an experiment can be viewed in the Hypercube application.

Other Python files in the python directory

There are two other Python files in the Python directory: the model constants file,, and the model parameter calibrationi class, The parameter calibration class should not be altered except in exceptional circumstances. The model constants file can be altered to include new experiment design files as new experiments are created.