iode.Simulation
- class iode.Simulation
Class for simulate models.
Models
IN IODE, a model is simply a list of equations. No other construction is necessary: in this way, to modify a model, the only thing to do is to modify the list that defines it. For example, if a model is logically divided into 5 blocks, 5 lists of equations will be defined:
BLOC1 : A, B, C, D BLOC2 : X, Y BLOC3 : C1, C2, C3, C4 BLOC4 : X_A1, X_A2, X_A3 BLOC5 : R1, R2, R3, S_12 MODSIM : $BLOC1, $BLOC2, $BLOC3, $BLOC4, $BLOC5
To simulate a model, all equations of the model must have been loaded or created. In addition, all the variables and scalars used in the model equations must have been loaded or created. Values of exogenous variables and of scalar cannot be \(NA\) (Not Available) over the simulation periods.
Exchange Endo-Exo
It is possible to set endogenous-exogenous pairs for
goal seeking. For each pair, the status of the variables is exchanged: endogenous becomes exogenous and vice versa. This enables the model to be run through known endogenous values and to deduce the necessary values for the associated exogenous variables. The exogenous variables take on the value calculated over the entire workspace period. See the methodSimulation.model_exchange().Newton-Raphson Algorithm
When an equation is not explicitly defined in terms of its endogen, or when the endogen appears several times in the equation, the simulation algorithm tries to solve the equation using a Newton method. If this method fails, a secant method is used to find a solution to the equation. However, there is no guarantee that a solution will be found in every case. Non-continuous functions (singularities) such as:
may be impossible to solve around their singular point. For this type of problem, the only solution is to modify the form of the equation:
Warning
As the endogenous variable of an equation carries the name of the equation, it is not possible to place in a model two equations with the same endogenous variable.
The order in which equations are introduced in the lists can influence the behavior of the simulation algorithm. As this is a Gauss-Seidel algorithm, the information calculated is used directly in the rest of the calculation. If X depends on Y, it’s better to place Y before X in the list of equations.
Examples
>>> from iode import SAMPLE_DATA_DIR, equations, scalars, variables >>> from iode import Simulation >>> equations.load(f"{SAMPLE_DATA_DIR}/fun.eqs") >>> scalars.load(f"{SAMPLE_DATA_DIR}/fun.scl") >>> variables.load(f"{SAMPLE_DATA_DIR}/fun.var")
>>> simu = Simulation() >>> simu.convergence_threshold 0.001 >>> simu.relax 1.0 >>> simu.max_nb_iterations 100 >>> simu.sort_algorithm 'BOTH (Connex compon. + Triangulation)' >>> simu.initialization_method 'TM1 (Y := Y[-1], if Y null or NA)' >>> simu.debug False >>> simu.nb_passes 5 >>> simu.debug_newton False
- Attributes:
- convergence_threshold: float
Convergence threshold below which the simulation results are considered enough close to the true solution for the current period. Default to 0.001.
- relax: float
Relaxation parameter (“damping”). Its value must be in the range [0.1, 1.0]. Default to 1.0
- max_nb_iterations: int
Maximum number of iterations to reach a solution. If, after the specified maximum number of iterations, the model has not converged, the process stops with an error message. This parameter prevents the process from looping indefinitely. Default to 100.
- sort_algorithm: SimulationSort
Sorting algorithm used to reorganized the list of equations before the simulation is performed. This reorganization can be usefully to to speed up the simulation. Possible values are:
NONE: do not use any sorting algorithm
CONNEX: use the Strongly Connected Component (SCC) method only
BOTH: use both the SCC and the Pseudo-triangulation methods
Default to BOTH.
- initialization_method: SimulationInitialization
At the start of each period to be simulated, a starting value must be chosen for each endogenous variable. Possible values are:
TM1: \(Y := Y[-1], if Y null or NA\)
TM1_A: \(Y := Y[-1], always\)
EXTRA: \(Y := extrapolation, if Y null or NA\)
EXTRA_A: \(Y := extrapolation, always\)
ASIS: \(Y unchanged\)
TM1_NA: \(Y := Y[-1], if Y = NA\)
EXTRA_NA: \(Y := extrapolation, if Y = NA\)
Default to TM1.
- debug: bool
Option to automatically generates IODE lists containing pre- and post-recursive equations: _PRE, _INTER and _POST. Default to False.
- nb_passes: int
Number of passes to make when the pseudo-triangulation sorting algorithm is used. Default to 5.
- debug_newton: bool
Save a trace of the sub-iterations when the Newton-Raphson alogrithm is used. Default to False.
Methods
model_calculate_SCC(self, nb_iterations[, ...])Decompose the model into Strongly Connex Components (SCC) and reorder it.
model_compile(self[, list_eqs])Recompiles a list of equations, or all equations if no list is specified.
model_exchange(self[, list_exo])Set a list of endogenous-exogenous pairs for
goal seeking.model_simulate(self, from_period, to_period)Run the simulation of a model for a given sample.
model_simulate_SCC(self, from_period, to_period)Simulates a model previously decomposed into Strongly Connex Components (SCC) and reordered.
- __init__(*args, **kwargs)
Methods
__init__(*args, **kwargs)model_calculate_SCC(self, nb_iterations[, ...])Decompose the model into Strongly Connex Components (SCC) and reorder it.
model_compile(self[, list_eqs])Recompiles a list of equations, or all equations if no list is specified.
model_exchange(self[, list_exo])Set a list of endogenous-exogenous pairs for
goal seeking.model_simulate(self, from_period, to_period)Run the simulation of a model for a given sample.
model_simulate_SCC(self, from_period, to_period)Simulates a model previously decomposed into Strongly Connex Components (SCC) and reordered.
Attributes
convergence_threshold: float
debug: bool
debug_newton: bool
initialization_method: str
max_nb_iterations: int
max_nb_iterations_newton: int
nb_passes: int
relax: float
sort_algorithm: str