gcubed.model_configuration

Constructor

Initialises the model details from a modified version of the CSV files used by G-cubed. The information in the file is a subset of the information in the modeldetails.csv file and a subset of the information that is stored in the baseinfo.csv file.

Arguments

configuration_file: the relative path, from Python's current working directory, to the model configuration file.

The root directory of the model, where the configuration CSV file is located.

The data directory of the model, where the model's data files are stored.

The sym directory of the model, where the model's sym files are stored and where the Python script and other SYM processor outputs are stored after the SYM processor has been run.

This directory is where all simulation experiment definitions are stored. Each experiment has its own root directory that is a subdirectory of the simulations directory.

The diagnostics directory is where all model execution diagnostics are saved.

This directory is where all chartpacks are saved.

This directory is where all python scripts to run model experiments are saved.

The unique string identifying the version of the model. This influences the way that the model parameters are calibrated.

This configuration property must be specified.

Conventionally the model version is a number plus single letter string, where number represents the number of sectors, and the letter relates to specific regions in the model. For example:

2R is the 2 region/2 sector model

20R is the 2 region/20 sector model

20C is the 10 region/20 sector model used for carbon emissions modelling.

The name for this property in the configuration file is Version.

The string identifying the build of the model. This influences the way that the model parameters are calibrated.

This configuration property must be specified.

The model build must start with a positive integer (e.g. 20) but it can also include a suffix that consists of digits and letters (e.g. 123logv13).

The name for this property in the configuration file is Build.

The integer indicating which build of the model is being used. A given model version can have many different builds.

This configuration property is inferred from the Build value in the model configuration file. See ModelConfiguration.build for details of the Build configuration setting.

The absolute path and name of the root SYM file to process with the sym processor to produce the sym details (lists of variables and Python implementation of the model equations etc.) for the model and the Python implementation of the model equations.

Note that the SYM definition of a model can be split among several files with the root file including the others to form the complete model definition. Only the name of the root SYM file is returned.

This configuration property must be specified.

The name for this property in the configuration file is "SymInputFile".

The equations Python module that is imported by the Lineariser.

The fully qualified module name required to import the SYM generated Python equations module.

The name of the file that is the Python equations module for this model.

The prefix used for all files output by the SYM processor.

The absolute path to the SYM processor generated varmap file.

The absolute path to the SYM processor generated eqnmap file.

The file containing a listing of left and right hand side variables in the model equations. the LHS variable comes first, as a name of the vector (column 1), and the index in that vector (column 2). Then each RHS variable appears, again as the vector name in column 2 and the index in that vector in column 2.

This information is used to populate a dictionary with keys being the vector and index tuple for each RHS variable and the value being a list of of vector name, vector index tuples, one for each equation that the RHS variable occurs in. That dictionary then drives the equation evaluations used in model linearisation.

The absolute path to the SYM processor generated varinfo file.

The absolute path to the SYM processor generated vars file.

The absolute path to the SYM processor generated lis file.

This is not used by the Python implementation.

The absolute path to the model's database CSV file.

The database file contains the historical data for all of the variables in the model.

Defaults to database.csv.

The absolute path to the model's input-output tables CSV file.

This file contains the tables for all regions in the model.

An example value is IOTABLESvR2011.csv.

The name for this property in the configuration file is IOTables.

Defaults to iotables.csv.

This configuration setting is the name of the CSV file containing the information about the advancement rates for technology in each sector, through all projection years. Values are expressed as a percentage so a value of 2.0 means that the technology will advance by 2% in the associated year.

It is an optional configuration setting. The default value is technology_advancement_rates.csv.

The name for this property in the configuration file is TechnologyAdvancementRatesFile.

The absolute path to the CSV file containing the values of the parameters that are set by the user rather than by calibration using database and IO table information.

The name for this property in the configuration file is UserParameters.

Returns

The absolute path to the user parameters file.

This configuration setting is the the name of the CSV file containing the information about the advancement rates for technology in each sector, through all projection years. Values are expressed as a percentage so a value of 2.0 means that the technology will advance by 2% in the associated year.

It is an optional configuration setting. The default value is technology_advancement_rates.csv.

The name for this property in the configuration file is TechnologyAdvancementRatesFile.

Returns

The absolute path to the technology advancement rates file.

This configuration setting is the the name of the CSV file containing the information about the technology gaps in each region for each sector, expressed as a percentage. Thus, a value of 50 means the region has a sector that is 50% as efficient as is possible in the first projection year.

It is an optional configuration setting. The default value is technology_gaps.csv.

The name for this property in the configuration file is TechnologyGapsFile.

Returns

The absolute path to the technology gaps file.

This configuration setting is the the name of the CSV file containing the information about the catchup rates for technology in each sector, through all projection years. Values are expressed as a percentage so a value of 2.0 means that the technology gap will close by 2% in the associated year.

It is an optional configuration setting. The default value is technology_catchup_rates.csv.

The name for this property in the configuration file is TechnologyCatchupRatesFile.

Returns

The absolute path to the technology catchup rates file.

This configuration setting is the the name of the CSV file containing the information needed to do region labor force growth rate projections. Values as given as percentages so a value of 2 is 2% growth in the associated year.

It is an optional configuration setting. The default value is labor_force_growth_rates.csv.

The name for this property in the configuration file is LaborForceGrowthRatesFile.

Returns

The absolute path to the labor force growth rates file.

This configuration setting is the the name of the CSV file containing the information needed to do projections of region/sector autonomous energy efficiency improvements.

It is an optional configuration setting. The default value is autonomous_energy_efficiency_improvements.csv.

The name for this property in the configuration file is AutonomousEnergyEfficiencyImprovementsFile.

Returns

The absolute path to the autonomous energy efficiency improvements file.

This configuration setting is the the name of the CSV file containing the information needed to do projections of region/sector autonomous energy efficiency improvements.

It is an optional configuration setting. It should only be used in models with a fully articulated electricity generation system. Typically it was relevant to the 20C model version. It has been superceded in later model versions.

If this setting is not specified in the model configuration, then the co2coef emissions coefficients must not feature in the model.

If used, the typical file name has the form co2coef_<VERSION>.csv.

The name for this property in the configuration file is CarbonCoefficientsFile.

Returns

The absolute path to the carbon coefficients file or None if none has been specified.

True if the model has emission intensity parameters and False if the model does not have emission intensity parameters.

The name of the CSV file containing the information about household emission intensity parameters. This file is expected to be in the data directory of the model.

This value is optional. If it not specified, then the model does not use the coefficients.

The name of the CSV file containing the information about government emission intensity parameters. This file is expected to be in the data directory of the model.

This value is optional. If it not specified, then the model does not use the coefficients.

The name of the CSV file containing the information about sector input emission intensity parameters. This file is expected to be in the data directory of the model.

This value is optional. If it not specified, then the model does not use the coefficients.

The name of the CSV file containing the information about sector capital emission intensity parameters. This file is expected to be in the data directory of the model.

This value is optional. If it not specified, then the model does not use the coefficients.

The name of the CSV file containing the information about sector labor emission intensity parameters. This file is expected to be in the data directory of the model.

This value is optional. If it not specified, then the model does not use the coefficients.

The name of the CSV file containing the information about sector output emission intensity parameters. This file is expected to be in the data directory of the model.

This value is optional. If it not specified, then the model does not use the coefficients.

This configuration setting is the name of the CSV file containing the derived information about labor augmenting technical change projections for all sectors in all regions. It is produced when the technology advancement rates, technology gaps, and technology catchup rates are combined.

It is an optional configuration setting. The default value is labor_augmenting_technical_change.csv.

The name for this property in the configuration file is LaborAugmentingTechnicalChangeFile.

Returns

The absolute path to the labor augmenting technical change file.

This configuration setting is the name of the CSV file containing the exogenous variable projections produced when the labor augmenting technical change data and the labor force growth rates data and the autonomous energy efficiency improvements data are combined.

It is an optional configuration setting. The default value is baseline_exogenous_projections.csv.

The name for this property in the configuration file is ExogenousGrowthAndEfficiencyAdjustmentsFile.

Returns

The absolute path to the exogenous growth an efficiency adjustments file.

This configuration setting is the name of the CSV file containing design information about the baseline projections.

The standard value is baseline_design.csv.

It is an optional configuration setting. If omitted, then no adjustments are made to the baseline projections. Exogenous variable projections are simply the values in the database, replicated through the projection years.

The name for this property in the configuration file is BaselineDesignFile.

Returns

The absolute path to the baseline design file or None if no baseline design file has been specified.

True if the model has a baseline design file and False if the model does not have a baseline design file.

This configuration setting is the year to use when selecting the database data for model linearisation purposes (e.g. 2011). It must be a year in which there is data in the database file.

The model can be relinearised in projection years, depending on how the model is run and how simulation experiments are designed. This is still an experimental feature of the model.

The name for this property in the configuration file is LinearisationYear.

This configuration setting is the year to use when selecting the database data for model parameter calibration purposes (e.g. 2011).
It must be a year in which there is data in the database file.

This is used to calibrate the values of all parameters except those set by the user in the ModelConfiguration.parameters_file and the carbon emissions coefficients. The carbon coefficients can be linearised in a different year, specified via ModelConfiguration.calibration_of_carbon_coefficients_year

The name for this property in the configuration file is CalibrationYear.

This configuration setting is the year to use when selecting the database data for model parameter calibration purposes for the carbon emissions related parameters (e.g. 2018). It must be a year in which there is data in the database file.

The name for this property in the configuration file is CalibrationOfCarbonCoefficientsYear.

This configuration setting is the year in which key price indices in the database are equal to 100.

Typically, the base year is chosen to be the first projection year, noting that the first year of projections are matched up to observed data in that first year. Note that this configuration setting needs to describe the actual database file. It should not be a specification of the base year that you want to use. Other configuration settings manage how the base year is altered after the data is loaded.

Databases can be rebased to different years after they have been loaded.

The name for this property in the configuration fileis BaseYear.

The original first projection year. This is tracked because, for projections that iterate forward through the projection years, the first projection year will be updated with each iteration.

This property is set equal to the value of the FirstProjectionYear property in the configuration file.

It must not be specified independently of the FirstProjectionYear. .

This configuration setting is the first year that projections are to be generated for. Note that for baseline projections, the projections start in a year where the model's database has data, so the projections can be lined up with the observed data in the database.

The first projection year must be one of the years in the database. It must not be the first or the last year in the database.

The name for this property in the configuration file is FirstProjectionYear.

This configuration setting is the last year for which data will be projected.

The last projection year must be later than the first projection year.

The name for this property in the configuration file is LastProjectionYear.

This configuration setting is the last year for which publishable projection data will be made available.

It defaults to 50 years before the last projection year.

The value must be between the first projection year and the last projection year, inclusive.

This is an optional configuration setting. It defaults to 50 years before the last projection year.

The name for this property in the configuration file is LastPublishableProjectionYear.

The list of integer years from the first projection year to the last projection year.

A list of string representations of the years from the first projection year to the last projection year.

A list of string representations of the years from the original first projection year to the last projection year.

The number of projection years, from the first to the last.

This configuration setting is the maximum size of the change in the stable manifold estimate allowed during the search for the stable manifold.

This value is used to ensure that the search for a stable manifold terminates within a reasonable period of time. Consider making this value larger if the search is not converging.

This is an optional configuration setting. The default value is 1e-10.

Values must be small and positive.

Values should be at least as small as 1e-5.

The name for this property in the configuration file is StableManifoldTolerance.

This configuration setting is the maximum number of iterations allowed when searching for the stable manifold for the model. If this number is reached without convergence of the stable manifold, then the model cannot be used for projection purposes.

This value is used to ensure that the search for a stable manifold terminates within a reasonable period of time.

This is an optional configuration setting. The default value is 1000.

The name for this property in the configuration file is StableManifoldMaximumIterations.

This configuration setting is the tolerance for the unit root test (maximum value that is still treated as not greater than 1, defaults to 1.001).

This value should not be set to a value that is meaningfully greater than 1.0.

This is an optional configuration setting. The default value is 1.001.

The name for this property in the configuration file is UnitRootTolerance.

This experimental configuration setting is a 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 rather than possibly being greater than 1 by the amount allowed by the UnitRootTolerance setting).

This is an optional configuration setting. The default value is False.

The name for this property in the configuration file is ScaleTransitionMatrixToEliminateExplosiveRoots.

This configuration setting is the global neutral real interest rate as a decimal, so a value of 3.6% would be specified in the model configuration as 0.036.

This rate influences model linearisation. Linearisation is done around a set of varible values that that force the interest rates in the model to be equal to this value.

This is an optional configuration setting. The default value is 3.6% (a value of 0.036)

The name for this property in the configuration file is NeutralRealInterestRate.

The name of the Python module that contains the parameters class definition.

This is always parameters_<VERSION>_<BUILD>, where <VERSION> is the model version and <BUILD> is the model build.

The path to the file containing the parameters calibration class.

This is a file called parameters_<VERSION>_<BUILD>.py in the model's Python directory where <VERSION> is the model version and <BUILD> is the model build.

The name of the class to use for calibrating the model parameters.

This is always Parameters<VERSION><BUILD>, where <VERSION> is the model version and <BUILD> is the model build.

This experimental configuration setting is True if the model linearisation is done around a strict model solution and False if the model linearisation is to instead be done around actual data values sourced from the model database or from a previous model projection.

Set this to False for standard linearisation as has been done for G-Cubed for decades. Set this 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.

This property defaults to False unless overridden in the model configuration.

This is an optional configuration setting. The default value is False.

The name for this property in the configuration file is LineariseAroundStrictModelSolution.

This experimental configuration setting is True if the model should enforce GDP and other variable aggregation consistency and False if the model should not enforce aggregate consistency in projections. Aggregates relate to GDP and high-level components and they relate to emissions. Aggregation consistency in projections is not guaranteed because of the way that the model is linearised and solved.

This is an optional configuration setting. The default value is False.

The name for this property in the configuration file is EnforceAggregateConsistency.