gcubed.runners.advanced_runner
This module contains the AdvancedRunner class, for running
experiments using G-Cubed.
Overview
* This runner is still experimental. *
The AdvancedRunner class runs a simulation experiment with G-Cubed that incorporates relinearisation in chosen years while allowing for strict or non-strict choice of points to linearise around and supporting simulation experiments using or not using relinearisation in their event years.
- The model is loaded and used to generate baseline projections.
- The experiment design is loaded, setting out each of the events being simulated as a separate simulation layer.
- The simulation layers are loaded and applied to the model to generate projection updates.
Projections based on any of the simulation layers can be compared to projections from the baseline or from other simulation layers associated with the experiment.
Note: Determine behaviour with regard to neutral real interest rates
by setting the AdvancedRunner.linearise_around_the_neutral_real_interest_rate and
the AdvancedRunner.start_projections_from_the_neutral_real_interest_rate and the
AdvancedRunner.relinearise_around_the_neutral_real_interest_rate properties
before triggering the model run by calling AdvancedRunner.run. The default
behaviour is to:
- use neutral real interest rates for linearisation
- start the projections from the neutral real interest rate and
- relinearise around the neutral real interest rate.
Overview
When the constructor is called, the runner loads the configuration and the model, ready for running. Call the run method when you are ready to start model linearisation etc. after having set properties for the runner to determine its behaviour, for example, how linearisation is done in relation to the neutral real interest rate.
The relinearisation of the model is done for each event year associated with a simulation layer and for each year nominated for relinearisation.
Arguments
working_directory: The directory where the results
and logs are to be stored.
configuration_file: The location of the configuration
file, as an absolute path or a path that is relative to the
working directory. The configuration file is the CSV file that
contains the model configuration. It must be in the model directory,
which is the root directory of the model folder structure.
relinearisation_years: The list of years where a
relinearisation is required. This list can be empty
in which case the model is not relinearised. To generate a
list of years, from 2018 to say, 2030, you can supply the
following as as this parameter value:
list(range(2018, 2031)). (Note that the upper bound is not
included in the range.) Defaults to the empty list.
experiment_design_file: The optional location of the
experiment design CSV file. This must be a relative path directory
to the experiment design file from the simulations directory
within the model directory (the model directory contains
the configuration file). Defaults to None.
Exceptions
Raises exceptions if the working directory is not specified correctly.
Raises exceptions if the configuration file is not specified correctly.
Raises exceptions if the relinearisation years are not specified correctly.
Raises exceptions if the experiment design file is not specified correctly.
True if the baseline linearisation is around neutral real interest rates
and False if they are around database values.
Defaults to True.
True if the baseline linearisation is around the neutral real interest rate
and False if it is around database values.
True if relinearisations are around the neutral real interest rate
and False if they are around previous projection values
in the relinearisation year.
True if the runner is to relinearise the model in all event years
as well as the years specified and False if the runner is to relinearise the model only
in the years specified.
Defaults to False.
If necessary, modify this setting once the running is instantiated but before the experiment is run.
The (possibly empty) list of relinearisation years (all in YYYY format).
A list of all projections generated by the runner or an empty list if no projections have been generated by the runner when this property is requested. The first projections are the baseline projections and then the following projections are the projections generated due to simulation layers or relinearisations etc. added to the list as they are generated.
This method will return the empty list if the runner has not started. If the runner is partway through the run, then the projections that have been produced will be available.
The first baseline projections that are produced.
Note that some runners will create multiple baselines: one per linearisation of the model.
The projections most recently generated in the run.
The final projections which can be the baseline projections if there was no simulation experiment to do.
The simulation layer definitions documented in the experiment design.
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 to the value specified in the supplied
model configuration file but it can be overridden. The default value
for configurations is False, resulting in the standard approach to linearisation.
True if the relinearisation starts with neutral real interest rates
and False otherwise.
Defaults to False.
True if the runner has completed all projections successfully and False otherwise.
Overview
Reset the runner so that it has no generated projections.
The successful completion flag is reset to False
and the list of projections generated by the runner is set
to an empty list.
Once reset, the runner can be rerun. This is useful if you want to run the same runner but with alternative experiments.
Overview
Do the actual work of running the model and performing the experiment.
Call this method after creating a Runner instance.
Once the experiment has run, you can retrieve projections from the simulation layer(s) of interest and the baseline for comparison and analysis purposes.
Overview
Save the projections to the specified directory.
Arguments
results_directory: The directory where the projections are to be saved.
publishable_projections: True if the publishable projections are to be saved. Defaults to True.
database_projections: True if the database projections are to be saved. Defaults to False.