Model configuration

Table of contents

Running a model entails generation of a set of baseline projections. Projections are values for each variable in the model, for each of the years from the start of the projections to the end of the projections, potentially spanning many decades.

A simulation experiment also generates simulation projections that can be compared to the baseline projections.

The baseline projections and the simulation projections will naturally depend in which model is being run.

Different models

G-Cubed supports simulation experiments using a variety of model versions. These versions differ in terms of the regions included in the model, the sectors in each region, and the economic relationships embodied in the equations describing the model version.

Model versions also differ in terms of how the model parameters are calibrated using the available data about each region in the model. The calibration rules are built into G-Cubed and cannot be modified.

However, you can modify the data used to do parameter calibration, you can modify the data used to set up a model simulation, and you can modify the shocks that impact the simulated economy, through the course of the model projections.

All of files that specify the details (including the data) for a model version need to be in a set of files with a specific organisation within directories.

This document sets out how the files must be stored, and how the data files must be formatted.

Model identification

A specific model is identified by the combination of its version and its build. A particular model version can have many different builds.

Model versions

Version codes have two parts, a number and a letter. The number indicates the number of sectors in the version of the model. The letter is used to differentiate versions of the model that have different regions, even if the number of regions is the same. The letter is capitalised.

Thus, model 2R has 2 regions. Model 20J has 10 regions and 20 sectors. Model 20C also has 20 sectors but the regions are different from those in model version 20J.

Model builds

Model versions are improved over time. Each improvement is released as a new build of the model version.

Model builds are also identified by a number and an optional string of other letters amd digits. Examples include 164, 170, and 170logv6.

The prefix number in the model build increases over time. The suffix in the model build differentiates models of the same generation if they differ in material ways.

The files required to run a G-Cubed model

A specific version of a G-Cubed model requires a number of files to run. These files are organised into a root folder with a set of subdirectories. The gcubed package will load these files and produce certain outputs into this root folder.

A link to the ZIP archive containing the files for the teaching model is in the navigation links on the left of this page.

All directories have lower-case names. This must not be changed because G-Cubed is case sensitive.

The file names that include parts like are to be substituted as follows:

  • replace with the version of the model, e.g. `2R`, `20C`, etc.
  • replace with the build of the model, e.g. `169`, `170`, `170log` etc.
  • replace with the build number of the model: e.g. `170` if the build is `17log`.
  • <?> For anything else in <> use whatever text you want, but make sure that it matches the file name details given in the model configuration file, the <MODEL_CONFIGURATION>.csv file that must be in the root folder of the model’s folder structure.

The model version and the model build values used in file naming must match their values in the model configuration file.

<VERSION>
├── <BUILD>
  ├── <MODEL_CONFIGURATION>.csv
  ├── data
  │   │   ├── <DATABASE>.csv
  │   │   ├── <IOTABLES>.csv
  │   │   ├── <USERPARAMETERS>.csv
  │   │   ├── <POPULATION>.csv
  │   │   ├── <PRODUCTIVITY>.csv
  │   │   ├── <AEEINEW>.csv
  ├── sym
  │   │   ├── ggg-<VERSION>-<NUMBER>.sym
  │   │   ├── ggg-sets.sym
  │   │   ├── linear
  │   │   │   ├── ggg-configuration.sym
  │   │   │   ├── ggg-main.sym
  │   │   │   ├── *.sym
  │   │   ├── log
  │   │   │   ├── ggg-configuration.sym
  │   │   │   ├── ggg-main.sym
  │   │   │   ├── *.sym
  │   │   ├── model_<VERSION>_<NUMBER>_eqnmap.sym
  │   │   ├── model_<VERSION>_<NUMBER>_optmap.sym
  │   │   ├── model_<VERSION>_<NUMBER>_varmap.sym
  │   │   ├── model_<VERSION>_<NUMBER>_varinfo.sym
  │   │   ├── model_<VERSION>_<NUMBER>_vars.sym
  │   │   ├── model_<VERSION>_<NUMBER>.lis
  │   │   ├── model_<VERSION>_<NUMBER>.py
  ├── simulations
  │   ├── <EXPERIMENT1>
  │   │   ├── <EXPERIMENT1_DESIGN>.csv
  │   │   ├── <LAYER1_DATA>.csv
  │   │   ├── ...
  │   ├── <EXPERIMENT2>
  │   │   ├── <EXPERIMENT2_DESIGN>.csv
  │   │   ├── <LAYER1_DATA>.csv
  │   │   ├── <LAYER2_DATA>.csv
  │   │   ├── ...
  │   ├── ...
  ├── diagnostics
  │   ├── ...

The files in the data folder

For details, review the documentation of the model data files.

The files in the sym folder

For details, review the documentation of the SYM files used to define models.

The diagnostics folder

When the model runs, it will create the diagnostics folder if it does not already exist. This folder will contain a large number of CSV files that give insights into the model’s operation. These files are useful for debugging the model, and for understanding the model’s operation. For example, it gives access to all of the calibrated parameter values used in the model.

The configuration file

The <CONFIGURATION>.csv model configuration file contains all of the information needed to load a specific model. It must be in the root folder.

The configuration file sets up all of the details of the model that is to be used. This includes:

  • the files where parameter calibration and initial variable state data are stored
  • settings affecting parameter calibration
  • settings affecting model linearisation
  • settings for how the model is ‘solved’
  • settings affecting the baseline projections

Model details

setting explanation required? accessor
Version The model version expressed as a positive integer followed by a capital letter e.g. 2R required ModelConfiguration.version
Build The model build expressed as a positive integer followed by one or more underscores or required ModelConfiguration.version
SymInputFile The root file for the SYM model definition required ModelConfiguration.sym_input_file

Important years

setting explanation required? accessor
Version The model version expressed as a positive integer followed by a capital letter e.g. 2R required ModelConfiguration.version
Build The model build expressed as a positive integer followed by one or more underscores or required ModelConfiguration.version
SymInputFile The root file for the SYM model definition required ModelConfiguration.sym_input_file
BaseYear The base year for indices in the model database required ModelConfiguration.base_year
CalibrationYear The year used to calibrate the model parameters except for the carbon coefficients required ModelConfiguration.calibration_year
CalibrationOfCarbonCoefficientsYear The year used to calibrate the carbon coefficients required ModelConfiguration.calibration_of_carbon_coefficients_year
LinearisationYear The year used to linearise the model for baseline projections required ModelConfiguration.linearisation_year
FirstProjectionYear The first projection year for the baseline projections required ModelConfiguration.first_projection_year
LastProjectionYear The last projection year required ModelConfiguration.last_projection_year
LastPublishableProjectionYear The optional last year for which publishable projection data will be made available (defaults to 70 years before last projection year) optional ModelConfiguration.last_publishable_projection_year

Data files

setting explanation required? accessor
Database The optional name of the file that contains the model database (defaults to database.csv) optional ModelConfiguration.database_file
IOTables The optional name of the file that contains the Input/Output tables for each region (defaults to iotables.csv) optional ModelConfiguration.io_table_file

Baseline exogenous adjustment settings

setting explanation required? accessor
LabourForceGrowthRatesFile The optional name of the file that contains the data about labor force growth rate projections for each region (defaults to labor_force_growth_rates.csv) optional ModelConfiguration.labor_force_growth_rates_file
AutonomousEnergyEfficiencyImprovementsFile The optional name of the file that contains the data about autonomous energy efficiency improvments over the projection years (defaults to autonomous_energy_efficiency_improvements.csv ) optional ModelConfiguration.aeei_file
TechnologyAdvancementRatesFile The optional name of the file that contains the technology advancement rates (defaults to technology_advancement_rates.csv) optional ModelConfiguration.technology_advancement_rates_file
TechnologyGapsFile The optional name of the file that contains the technology gaps (defaults to technology_gaps.csv) optional ModelConfiguration.technology_gaps_file
TechnologyCatchupRatesFile The optional name of the file that contains the technology catchup rates (defaults to technology_catchup_rates.csv) optional ModelConfiguration.technology_catchup_rates_file
LaborAugmentingTechnicalChangeFile The optional name of the derived file that contains the projections for labor augmenting technical change, based on the content of the technology files (defaults to labor_augmenting_technical_change.csv) optional ModelConfiguration.labor_augmenting_technical_change_file
ExogenousGrowthAndEfficiencyAdjustmentsFile The optional name of the derived file that contains the exogenous growth and energy efficiency projections (defaults to baseline_exogenous_projections.csv) optional ModelConfiguration.exogenous_growth_and_efficiency_adjustments_file
BaselineDesignFile The optional name of the file that contains the design of the baseline exogenous adjustments (defaults to baseline_design.csv) optional ModelConfiguration.baseline_design_file

Parameter settings

setting explanation required? accessor
BaselineDesignFile The optional name of the file that contains the design of the baseline exogenous adjustments (defaults to baseline_design.csv) optional ModelConfiguration.baseline_design_file
UserParameters The optional name of the file that contains the values for parameters that are set directly by the user (defaults to user_parameters.csv) optional ModelConfiguration.user_parameters_file
NeutralRealInterestRate The optional global neutral real interest rate, as a decimal rather than a percentage optional ModelConfiguration.neutral_real_interest_rate
CarbonCoefficientsFile The optional name of the file that contains the carbon coefficients. If not specified, the coefficients are not loaded. optional ModelConfiguration.carbon_coefficients_file
EmissionIntensityParameterFileSuffix The optional suffix of the names of the files that contain the emission intensity coefficients. If not specified then the coefficients are not loaded. optional ModelConfiguration.emissions_coefficient_file_suffix

The EmissionIntensityParameterFileSuffix will eventually replace the carbon coefficients. If provided, then the suffix is appended to a set of standard prefixes to form the full file names of the various emission intensity parameter files. The standard prefixes are household, government, sector_input, sector_capital, sector_labor, and sector_output.

Model solution settings

setting explanation required? accessor
BaselineDesignFile The optional name of the file that contains the design of the baseline exogenous adjustments (defaults to baseline_design.csv) optional ModelConfiguration.baseline_design_file
UserParameters The optional name of the file that contains the values for parameters that are set directly by the user (defaults to user_parameters.csv) optional ModelConfiguration.user_parameters_file
NeutralRealInterestRate The optional global neutral real interest rate, as a decimal rather than a percentage optional ModelConfiguration.neutral_real_interest_rate
CarbonCoefficientsFile The optional name of the file that contains the carbon coefficients. If not specified, the coefficients are not loaded. optional ModelConfiguration.carbon_coefficients_file
EmissionIntensityParameterFileSuffix The optional suffix of the names of the files that contain the emission intensity coefficients. If not specified then the coefficients are not loaded. optional ModelConfiguration.emissions_coefficient_file_suffix
StableManifoldTolerance The tolerance for small changes in the stable manifold that defines convergence to the stable manifold (defaults to 1e-10) optional ModelConfiguration.stable_manifold_tolerance
StableManifoldMaximumIterations The maximum number of iterations to perform before failing to find the stable manifold (defaults to 1000) optional ModelConfiguration.stable_manifold_maximum_iterations
UnitRootTolerance The tolerance for the unit root test (maximum value that is still treated as not greater than 1, defaults to 1.001) optional ModelConfiguration.unit_root_tolerance
ScaleTransitionMatrixToEliminateExplosiveRoots An experimental switch to scale the transition matrix to eliminate explosive roots (If 1, then the state transition matrix is divided by the maximum modulus of its roots to ensure all roots are less than or exactly equal to 1 rather than possibly being greater than 1 by the amount allowed by the UnitRootTolerance setting) optional ModelConfiguration.scale_transition_matrix_to_eliminate_explosive_roots
LineariseAroundStrictModelSolution Optional switch governing how model linearisation is done. Defaults to True optional ModelConfiguration.linearise_around_strict_model_solution
EnforceAggregateConsistency An experimental boolean. Set to True to enforce consistency of macroeconomic aggregates in the projections. The default value is False. optional ModelConfiguration.enforce_aggregate_consistency

All of these settings are also detailed in the documentation of the Model Configuration API.