iode.Simulation

class iode.Simulation(convergence_threshold: float = 0.001, relax: float = 1.0, max_nb_iterations: int = 100, sort_algorithm: SimulationSort | str = SimulationSort.BOTH, initialization_method: SimulationInitialization | str = SimulationInitialization.TM1, debug: bool = False, nb_passes: int = 5, debug_newton: bool = False)[source]

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 method Simulation.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:

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 algorithm is used. Default to False.

Methods

`model_calculate_SCC`(nb_iterations[, ...])	Decompose the model into Strongly Connex Components (SCC) and reorder it.
`model_compile`([list_eqs, quiet])	Recompiles a list of equations, or all equations if no list is specified.
`model_exchange`([list_exo])	Set a list of endogenous-exogenous pairs for `goal seeking`.
`model_simulate`(from_period, to_period[, ...])	Run the simulation of a model for a given sample.
`model_simulate_SCC`(from_period, to_period[, ...])	Simulates a model previously decomposed into Strongly Connex Components (SCC) and reordered.
`nb_iterations`(period)	Number of iterations to converge in the last simulation for the period period.
`norm`(period)	Get the norm value of the last simulation for the period period.
`save_nb_iterations`(var_name)	Save the number of iterations needed to complete each simulated period in a new variable named var_name.
`save_norms`(var_name)	Save the lowest norm value reached to complete each simulated period in a new variable named var_name.

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")
Loading .../fun.eqs
274 objects loaded 
>>> scalars.load(f"{SAMPLE_DATA_DIR}/fun.scl")
Loading .../fun.scl
161 objects loaded 
>>> variables.load(f"{SAMPLE_DATA_DIR}/fun.var")
Loading .../fun.var
394 objects loaded

>>> simu = Simulation()
>>> simu
Simulation(convergence_threshold = 0.001, relax = 1.0, max_nb_iterations = 100,
           sort_algorithm = 'BOTH', initialization_method = 'TM1', debug =
           False, nb_passes = 5, debug_newton = False)

__init__(convergence_threshold: float = 0.001, relax: float = 1.0, max_nb_iterations: int = 100, sort_algorithm: SimulationSort | str = SimulationSort.BOTH, initialization_method: SimulationInitialization | str = SimulationInitialization.TM1, debug: bool = False, nb_passes: int = 5, debug_newton: bool = False)[source]

Methods

`__init__`([convergence_threshold, relax, ...])
`model_calculate_SCC`(nb_iterations[, ...])	Decompose the model into Strongly Connex Components (SCC) and reorder it.
`model_compile`([list_eqs, quiet])	Recompiles a list of equations, or all equations if no list is specified.
`model_exchange`([list_exo])	Set a list of endogenous-exogenous pairs for `goal seeking`.
`model_simulate`(from_period, to_period[, ...])	Run the simulation of a model for a given sample.
`model_simulate_SCC`(from_period, to_period[, ...])	Simulates a model previously decomposed into Strongly Connex Components (SCC) and reordered.
`nb_iterations`(period)	Number of iterations to converge in the last simulation for the period period.
`norm`(period)	Get the norm value of the last simulation for the period period.
`save_nb_iterations`(var_name)	Save the number of iterations needed to complete each simulated period in a new variable named var_name.
`save_norms`(var_name)	Save the lowest norm value reached to complete each simulated period in a new variable named var_name.

Attributes

`convergence_threshold`	Indicates the convergence threshold below which the simulation ends positively for the current period.
`debug`	Option to automatically generates IODE lists containing pre-recursive, interdependent and post-recursive equations: _PRE, _INTER and _POST.
`debug_newton`	Save a trace of the sub-iterations when the Newton-Raphson alogrithm is used.
`initialization_method`	At the start of each period to be simulated, a starting value must be chosen for each endogenous variable. This value can be : - \(Y := Y[-1], if Y null or NA\) (TM1) : each null or NA endogen at the start takes the value of the previous period, - \(Y := Y[-1], always\) (TM1_A) : each endogen takes the value of the previous period at the start, - \(Y := extrapolation, if Y null or NA\) (EXTRA) : each null or NA endogen takes as value a linear extrapolation of the two previous periods, - \(Y := extrapolation, always\) (EXTRA_A) : each endogen takes as its value a linear extrapolation of the two preceding periods, whether or not it is zero at the start, - \(Y unchanged\) (ASIS): endogenous values are not initialized. They retain their value whether or not they are zero, - \(Y := Y[-1], if Y = NA\) (TM1_NA): each NA value takes the value of the previous period, - \(Y := extrapolation, if Y = NA\) (EXTRA_NA): each NA value takes the value of a linear extrapolation of the two previous periods.
`initialization_method_long`	At the start of each period to be simulated, a starting value must be chosen for each endogenous variable.
`max_nb_iterations`	Maximum number of iterations to reach a solution.
`max_nb_iterations_newton`	Maximum number of iterations when the Newton-Raphson algorithm is used.
`nb_passes`	Number of passes to make when the pseudo-triangulation sorting algorithm is used.
`relax`	Relaxation parameter.
`sort_algorithm`	Sorting algorithm used to reorganized the list of equations before the simulation is performed.
`sort_algorithm_long`	Sorting algorithm used to reorganized the list of equations before the simulation is performed.