Model configuration

Table of contents

Contents

• Model configuration
• Different models
  • Model identification
    • Model versions
    • Model builds
• The files required to run a G-Cubed model
  • The files in the data folder
  • The files in the sym folder
  • The diagnostics folder
  • The configuration file
    • Model details
    • Important years
    • Data files
    • Baseline exogenous adjustment settings
    • Parameter settings
    • Parameter settings that impact on the database and technology catchup files
    • Model solution settings

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.

Various model versions are documented online.

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 followed by an optional string of other letters amd digits. Examples include 191 and 173logv2.

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.

The files for the teaching model can be obtained from the Github repository by forking the gcubed.com-model-2R repository on GitHub. Your fork of the teaching model repository allows you to:

• Run your model in GitHub Codespaces or in a local devcontainer
• Easily receive updates when the model is improved
• Save your own changes using Git
• See Getting Started for detailed instructions.

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>
  ├── configuration.csv
  ├── data
  │   │   ├── autonomous_energy_efficiency_improvements.csv
  │   │   ├── baseline_design.csv
  │   │   ├── baseline_exogenous_projections.csv (generated file)
  │   │   ├── database.csv
  │   │   ├── iotables.csv
  │   │   ├── labor_augmenting_technical_change.csv (generated file)
  │   │   ├── labor_force_growth_rates.csv
  │   │   ├── technology_advancement_rates.csv
  │   │   ├── technology_catchup_rates.csv
  │   │   ├── technology_gaps.csv
  │   │   ├── user_parameters.csv
  │   │   ├── ...
  ├── sym
  │   │   ├── ggg-model.sym
  │   │   ├── ggg-sets.sym
  │   │   ├── linear
  │   │   │   ├── ggg-configuration.sym
  │   │   │   ├── ggg-main.sym
  │   │   │   ├── ...
  │   │   ├── log
  │   │   │   ├── ggg-configuration.sym
  │   │   │   ├── ggg-main.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 typically expressed as a positive integer	required	ModelConfiguration.build
SectorCount	The integer number of sectors other than household and raw capital sectors	required	ModelConfiguration.sector_count
SymInputFile	The root file for the SYM model definition. This is the file that is specified when using the SYM processor at the commandline.	optional	ModelConfiguration.sym_input_file
ConstructionIsAllocatedAcrossOtherSectors	A boolean flag indicating whether construction is allocated across other sectors. This is typically the case for models with 6+ sectors and less than 12 sectors.	optional (default: False)	ModelConfiguration.construction_is_allocated_across_other_sectors
HasElectricityDistributionAndGenerationSectors	A boolean flag indicating whether the model has an electricity distribution sector that aggregates the output from electricity generation sectors.	optional (default: False)	ModelConfiguration.has_electricity_distribution_and_generation_sectors
HasMultipleGreenhouseGases	A boolean flag indicating whether the model has multiple greenhouse gases.	optional (default: False)	ModelConfiguration.has_multiple_greenhouse_gases

Important years

setting	explanation	required?	accessor
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	optional (default: base year)	ModelConfiguration.calibration_year
CalibrationOfCarbonCoefficientsYear	The year used to calibrate the carbon coefficients	optional (default: calibration year)	ModelConfiguration.calibration_of_carbon_coefficients_year
LinearisationYear	The year used to linearise the model for baseline projections	optional (default: base year)	ModelConfiguration.linearisation_year
FirstProjectionYear	The first projection year for the baseline projections	optional (default: base year)	ModelConfiguration.first_projection_year
LastProjectionYear	The last projection year	required	ModelConfiguration.last_projection_year
LastPublishableProjectionYear	The last year for which publishable projection data will be made available	optional (default: 70 years before last projection year)	ModelConfiguration.last_publishable_projection_year

Data files

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

Baseline exogenous adjustment settings

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

Parameter settings

setting	explanation	required?	accessor
UserParameters	The name of the file that contains the values for parameters that are set directly by the user	optional (default: user_parameters.csv)	ModelConfiguration.user_parameters_file
ParameterCalibrationClassName	The name of the class that contains the parameter calibration logic	optional (default: CalibratedParameters)	ModelConfiguration.parameter_calibration_class_name
ParameterCalibrationModuleName	The name of the module that contains the parameter calibration class. This implies a file name of calibrated_parameters.py in the model’s python folder.	optional (default: calibrated_parameters)	ModelConfiguration.parameter_calibration_module_name
NeutralRealInterestRate	The global neutral real interest rate, as a decimal rather than a percentage (e.g., 0.036 for 3.6%)	optional (default: 0.036)	ModelConfiguration.neutral_real_interest_rate
RateOfTimePreference	The rate of time preference, as a decimal rather than a percentage (e.g., 0.022 for 2.2%)	optional (default: 0.022)	ModelConfiguration.rate_of_time_preference
MarginalPropensityToConsume	The marginal propensity to consume out of disposable income for constrained households (e.g., 1.0 for 100%)	optional (default: 1.0)	ModelConfiguration.marginal_propensity_to_consume

Parameter settings that impact on the database and technology catchup files

If these parameters are changed, the database and technology catchup files must be updated.

setting	explanation	required?	accessor
EffectiveLaborProductivityGrowthRateInSteadyState	The effective labor productivity growth rate in steady state, as a decimal (e.g., 0.014 for 1.4%)	optional (default: 0.014)	ModelConfiguration.effective_labor_productivity_growth_rate_in_steady_state
BlanchardProbabilityOfDeath	The global Blanchard probability of death, as a decimal (e.g., 0.03 for 3%). Regenerate the database if you change this value.	optional (default: 0.03)	ModelConfiguration.blanchard_probability_of_death
ConstantsDecayRate	An optional constant decay rate used to generate decay factors for intertemporal calculations (e.g., 0.02 for 2%)	optional (default: 0.0)	ModelConfiguration.constants_decay_rate
SymmetricTwoRegionModel	A boolean flag indicating whether the model is a symmetric two-region model with identical values for their data	optional (default: False)	ModelConfiguration.symmetric_two_region_model

Model solution settings

setting	explanation	required?	accessor
StableManifoldTolerance	The tolerance for small changes in the stable manifold that defines convergence to the stable manifold. Values should be at least as small as 1e-5.	optional (default: 1e-7)	ModelConfiguration.stable_manifold_tolerance
StableManifoldMaximumIterations	The maximum number of iterations to perform before failing to find the stable manifold	optional (default: 1000)	ModelConfiguration.stable_manifold_maximum_iterations
UnitRootTolerance	The tolerance for the unit root test (maximum value that is still treated as not greater than 1). This value should not be set to a value that is meaningfully greater than 1.0.	optional (default: 1.001)	ModelConfiguration.unit_root_tolerance
ScaleTransitionMatrixToEliminateExplosiveRoots	An experimental switch to scale the transition matrix to eliminate explosive roots. If True, 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.	optional (default: False)	ModelConfiguration.scale_transition_matrix_to_eliminate_explosive_roots
LineariseAroundStrictModelSolution	An experimental switch governing how model linearisation is done. Set to True if the actual data values are to be adjusted to find similar values that exactly solve all of the equations in the model before then linearising around those similar values. Set to False for standard linearisation as has been done for G-Cubed for decades.	optional (default: False)	ModelConfiguration.linearise_around_strict_model_solution
EnforceAggregateConsistency	An experimental boolean. Set to True to enforce consistency of macroeconomic aggregates (GDP and high-level components, emissions) in the projections.	optional (default: False)	ModelConfiguration.enforce_aggregate_consistency

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