gcubed.linearisation.linear_model
This module contains the LinearModel class.
It is used to linearise the model by producing the partial derivative matrices that embody the model dynamics. at a point satisfying the model equations.
Overview
The algebra embodied in this class follows https://www.msgpl.com.au/Manuals2021/GGGv20JManual/softwaremanual/algorithm.pdf
The notation has been extended to also include equations for expected endogenous variables to include exogenous variables.
This class provides the ability to work with the model equations. It:
- Computes the partial derivatives of the model equations so that an approximation of the model can be expressed as a set of linear equations.
- Constructs the matrices of constants associated with the state-space form of the linearised model. This involves eliminating the endogenous variables from the model via substitution.
To use this class:
- instantiate it with a model.
- run the __compute_partial_derivatives() method.
Once this sequence of steps has been completed without raising an exception, the matrices associated with the state space form will be accessible as properties of the linear model to support solving the model.
Instantiation determines the values for the RHS variable vectors based upon the model's database and the year that has been chosen to determine the variable values that the model will be linearised around.
These RHS variable vector values, and the implied LHS variable vector values are exposed as properties of the linear model. The names of these vector properties are 3 character acronyms:
The linear model supports evaluation of the model equations to obtain values for the LHS and RHS vectors of variables defined in sym_data.
To understanding the naming conventions, the partial
derivatives matrix associated with the partials of
x1l with respect to z1r are stored in a property called x1l_z1r_partials.
The same naming convention is used for all partials matrices:
Arguments
model: The model that is to be linearised with the linearisation
year specified as part of the model configuration.
use_neutral_real_interest_rate: If True, use the neutral real interest rate
for the values around which linearisation is done, otherwise use the real interest rate
from the database (which may be negative). This parameter defaults to True.
The database containing the values that will be utilised to populate variable values for the linearisation.
True if the model has been linearised
successfully and False otherwise (either because linearisation has not
finished or linearisation was not possible for whatever reason).
This property is checked when doing baseline projections to ensure that baseline projections never start from the neutral real interest rate unless the linearisation was done around the neutral real interest rate.
True if the linearisation used the neutral real interest rate
and False otherwise.
The equations subclass instance that implements the functions for each of the nonlinear equations in the model.
The configuration details for the model being linearised.
Overview
This is only a public property to assist with unit testing. Do not use it directly for other purposes.
The map is populated from the SYM processor output and is used to make the calculation of partial derivatives more efficient, only calculating those derivatives that are not zero by definition.
Returns
The map from each RHS variable in the model to the list of LHS variables (equations) that depend on it.
Overview
Use the name of the vector to retrieve its numpy array value. These values have been set using data in the database.
Arguments
vector_name: The name of the LHS or RHS vector.
Returns
The named column vector.
Overview
This function is useful for benchmarking the model's nonlinear equation evaluations.
Use the name of the vector to retrieve its numpy array value. These values have been set by evaluating the model's non-linear equations using the RHS vector values for the base year chosen for the linearisation.
Arguments
lhs_vector_name: The name of the LHS vector, e.g. 'x1l' or 'j1l'.
Returns
The named LHS column vector.
Overview
Use the name of the LHS vector and the RHS vector to retrieve the numpy matrix value for the partial derivatives.
The matrices of partial derivatives are stored in a dictionary indexed by the lhs and rhs vector names.
Arguments
lhs_vector_name: The name of the LHS vector, e.g. 'x1l' or 'j1l'.
rhs_vector_name: The name of the RHS vector, e.g. 'yxr' or 'j1r'.
Returns
The required partial derivatives as a dataframe with variable names as the row and column labels.
Arguments
lhs_vector_name: The name of the LHS vector, e.g. 'x1l' or 'j1l'.
rhs_vector_name: The name of the RHS vector, e.g. 'yxr' or 'j1r'.
Returns
The required partial derivatives as a dataframe with variable names as the row and column labels.
Details about the differences between the LHS and RHS values for all endogenous variables as at the point of linearisation. This is only used for unit testing purposes.
Overview Retrieve the partial derivatives for the specified LHS vector.
Arguments
lhs_vector_name: The name of the LHS vector, e.g. x1l or j1l.
rhs_vector_name: The name of the RHS vector, e.g. yxr or j1r.
lhs_variable_name_prefix: The prefix to use for the LHS variable names, e.g. PRID(USA. Defaults to None
in which case all rows are returned.
rhs_variable_name_prefix: The prefix to use for the RHS variable names, e.g. TCPS(a11,g02,USA. Defaults to None
in which case all columns are returned.
Returns
The dataframe with the matched rows and columns of the chosen partial derivatives matrix.
Overview Retrieve the partial derivatives for the specified LHS variables.
Arguments
lhs_variable_name_prefix: The prefix to use for the LHS variable names, e.g. PRID(USA. Defaults to None
in which case all rows are returned.
Returns
The dataframe with the partial derivatives for the selected LHS variables.