Simulation experiments

Table of contents

• The simulations directory and its contents
  • The experiment design file
    • The event year
    • The simulation layer data
  • The simulation layer data file
• Experiment design

The simulations directory and its contents

The simulations directory must be a child directory of the directory that contains the model configuration file.

<ROOT_DIRECTORY_FOR_MODEL>
├── <MODEL_CONFIGURATION>.csv
├── data
│   │   ├── ...
├── sym
│   │   ├── ...
├── simulations
│   ├── <EXPERIMENT1>
│   │   ├── <EXPERIMENT1_DESIGN>.csv
│   │   ├── <LAYER1_DATA>.csv
│   │   ├── ...
│   ├── <EXPERIMENT2>
│   │   ├── <EXPERIMENT2_DESIGN>.csv
│   │   ├── <LAYER1_DATA>.csv
│   │   ├── <LAYER2_DATA>.csv
│   │   ├── ...
│   ├── ...

The simulations directory contains one directory for each simulation experiment being done using the model.

The experiment directory names are user-determined.

The experiment design file

Each experiment directory contains a CSV experiment design file that configures the experiment, documenting the layers of adjustments to variables that are to be applied in specific years through the projections.

The experiment design file for the teaching model provides a useful template to adapt for your own experiments.

The experiment design file is comma delimited and the values in the file must not contain commas.

The first row of the design file contains column labels. They are, in order:

1. name
2. data
3. event_year
4. description

Each of the following rows in the design file sets out the definition of a single simulation layer. When running simulations, the details of the simulation layer are loaded into a simulation layer definition.

That simulation layer definition is used to create the simulation projections associated with the layer. The simulation projections are generated by the simulation layer.

The name and the description of a simulation layer are used for experiment documentation purposes. The effect of the simulation layer is determined by the event_year and the data values.

The event year

Each simulation has an event year. That is the year that the agents in the model become aware of the changes to their circumstances associated with the simulation layer. For example, if agents become aware, in 2025, that the new target inflation rate is 5% instead of 2.5% then the simulation layer that describes the changes to the new target inflation rate would have an event year of 2025. This is the case, even if the change in the target inflation rate only takes effect in a year after 2025.

The event year for each simulation layer must be contained in the event_year column of the experiment design file.

The event year must be after the first projection year, specified in the model configuration.

The simulation layer data

Each simulation layer involves applying changes to the circumstances of the agents in the model. These take the form of increments that are applied to:

• exogenous variables in the event year or in any year thereafter; and
• state variables in the event year itself

The increments to exogenous variables set out in a single CSV file. The name of that CSV file is the value in the data column for the simulation layer in the experiment design file. Note that only the file name is required. The directory location of the file is assumed to be the same as the directory location of the experiment design file.

The increments to exogenous variables are in the same units as the data in the model database.

The simulation layer data file

There must be exactly one data file for each simulation layer.

The data file is a comma-delimited CSV file. The first column contains the full variable names for the exogenous or state variables that change.

The following columns are for the changes to the variables in each year from the event year of the simulation layer through to the last projection year.

The rows for the variables can be in any order.

The data file for a simulation has column headings in the first row:

1. name for the full name of the variable
2. 2025 if the event year is 2025
3. 2026
4. …
5. 2100 if the last projection year is 2100.

The simulation layer data file for the teaching model provides a useful example.

The simulation layer data file can, pathologically contain just the column headings, in which case, the simulation layer should not alter projections at all because it implies no changes to the circumstances of the agents in the model.

More typical data files involve changes to several exogenous or state variables.

Because the simulation layer applies changes for:

• exogenous variables in the event year or in any year thereafter; and
• state variables in the event year itself

any changes to state variables after the event year are ignored.

Also, the simulation layer data file must not include changes to variables that are not exogenous variables or state variables.

Experiment design

Experiments can involve applying more than one simulation layer. More than one simulation layer can be applied with the same event year.

The simulation layers are ordered by their event years when they are applied.

The application of multiple simulation layers with the same event year is done in the row order of the simulation layers in the experiment design file.