Parameters and Options Module¶

This module houses classes for the macro_model’s parameters and options attributes.

class PyMacroFin.parameters.options¶

This simple container class houses configurable model options. See the notes below the attribute definitions for more detailed descriptions of the loops referenced in the attribute descriptions.

Notes

The HJB update loop, or dynamic loop, is the iteration involving the PDE system. The HJB or dynamic loop iterates backward in time using the equation found on this page and a monotone finite difference scheme.
The inner static loop is the first level of iteration in solving the endogenous system of equations. The inner static loop is run separately for each grid point, solving for the endogenous equations to equal zero. The outer static loop calculates derivatives across the grid using a monotone finite difference scheme after all grid points have completed the inner static loop. This outer static loop continues, running the inner static loop and derivative re-calculation, until the endogenous system of equations is solved at all grid points with consistency with derivatives between grid points.

Attributes:

Attributes:	loop: bool Whether or not to enable the second loop stage of the outer loop. If `True`, after the minimum number of iterations and the tolerance is satisfied on the outer loop, a second loop stage is activated. If enabled, this allows for two stages with varying levels of error tolerance. Defaults to `False`. min_iter_inner_static: int Minimum iterations for the inner static loop. Defaults to 2. max_iter_inner_static: int Maximum iterations for the inner static loop. Defaults to 10,000. tol_inner_static: numeric Error tolerance for the inner static loop. Defaults to 1.0e-6. min_iter_outer_static: int Minimum iterations for the outer static loop. Defaults to 2. max_iter_outer_static: int Maximum iterations for the outer static loop. Defaults to 100. tol_outer_static: numeric Error tolerance for outer static loop. Defaults to 1.0e-4 damp1: numeric Initial dampening factor for the static loop. Defaults to 0.1. damp1_adjustment: numeric Dampening adjustment factor. This number should be between zero and one. The dampening factor is multiplied by this adjustment each loop to speed up convergence. Defaults to 1. min_damp1: numeric Minimum dampening factor. Defaults to 0. damp2: numeric Initial dampening factor for the static loop (second stage). Defaults to 0.1. damp2_adjustment: numeric Dampening adjustment factor (second stage). This number should be between zero and one. The dampening factor is multiplied by this adjustment each loop to speed up convergence. Defaults to 1. min_damp2: numeric Minimum dampening factor for the second stage. Defaults to 0. min_hjb1: int Minimum iterations for the outer HJB update loop (dynamic loop). Defaults to 100. min_hjb2: int Minimum iterations for the outer HJB update loop (second stage). Defaults to 10. max_hjb: int Maximum iterations for the outer HJB update loop (dynamic loop). Defaults to 10000. tol_hjb: numeric Error tolerance for the outer HJB update loop (dynamic loop). Defaults to 0.01. dt: numeric Time step for the HJB update loop (dynamic loop). Defaults to 0.1. dt2: numeric Time step for the HJB update loop (second stage). Defaults to 0.1. tol_d: numeric Error tolerance for the stencil decomposition algorithm. Defaults to 1.0e-4. max_p: int Maximum stencil size for decomposition algorithm. n0: int Number of points to use in the finite difference grid in the dimension associated with the first element of the model `state` attribute. Defaults to 50. n1: int Number of points to use in the finite difference grid in the dimension associated with the second element of the model `state` attribute. Defaults to 50. start0: numeric First point use in the finite difference grid in the dimension associated with the first element of the model `state` attribute. Defaults to 0.01. start1: numeric First point use in the finite difference grid in the dimension associated with the second element of the model `state` attribute. Defaults to 0.01. end0: numeric Last point use in the finite difference grid in the dimension associated with the first element of the model `state` attribute. Defaults to 0.99. end1: numeric Last point use in the finite difference grid in the dimension associated with the second element of the model `state` attribute. Defaults to 0.99. quiet: bool Whether or not to suppress update output. Defaults to `False`. import_guess: bool Whether or not to import an initial guess to work from. Defaults to `False`. guess_function: False or function Possibility to provide a function to calculate initial guesses from state variable values. If not `False`, initial guesses for endogenous and value variables will be calculated from the provided function. The function should return a vector in the order of endogenous variables first, then value variables, such that the length of the vector returned by the function should be equal to the lengths of `macro_model.endog` and `macro_model.value` summed. The function provided should accept two arguments, corresponding to the two state variables in `macro_model.state`. Defaults to `False` import_guess_location: str File path to the csv file where the guess file is located. Defaults to `None` and is not used unnless `import_guess` is set to `True`. The guess file should be a comma-separated values file with columns labeled and completed for all value, state, and endogenous variables. Note that the grid specified by options `start0`, `start1`, `end0`, `end1`, `n0`, above and `n1` must be consistent with the grid implied by the guess file. It is useful to run a simple dummy model without a guess file with the same grid specification, then modify the file saved down by the dummy model without changing the ordering or specification of state variables to create a guess file. inner_plot: bool Whether or not to plot after each outer static loop iteration. Defaults to `False`. outer_plot: bool Whether or not to plot after each HJB loop iteration. Defaults to `False`. final_plot: bool Whether to plot after convergence. Defaults to `True`. derivative_plotting: list(tuple(str)) List of tuples to indicate derivatives to be plotted in addition to endogenous variables and selected secondary variables. Tuples should be of the same form as the input to equations. For example, for the second derivative of a price `q` to state variable `x` will have the tuple `('q','x','x')`. parallel: bool Whether or not to run the static loop in parallel. Defaults to `True`. client: str Must either be `'local'` or `'user-provided'`. When set to `'local'`, PyMacroFin will create a dask client that will parallelize locally on your machine. If set to `'user-provided'`, PyMacroFin will assume there is a dask client already running that the user has defined outside of PyMacroFin, and an error will be thrown if a client is not found. This option is useful when the user would like to define a cluster specific to a high-performance computing environment or a cloud computing service; however, using this option requires familiarity with dask and your computing environment architectural details. Defaults to `'local'`. dask_timeout: int Number of seconds for the dask scheduler to wait for workers before timing out. Defaults to 100 seconds. Only used if parallelization is used. dash_debug: bool Whether or not to run the visualization Dash application in debug mode. Defaults to `False`. dash_port: int Local port on which to run the Dash visualization application. Defaults to `8050`. dash_port_stationary: int Local port on which to run a second Dash visualization application for calculation of a stationary distribution. Defaults to `8000`. ignore_HJB_loop: bool An option to ignore the HJB loop and return after running one iteration of the outer static loop. This is suitable for problems that do not require iteration through the dynamic HJB loop. Defaults to `False`. inner_solver: str Solver to use for the inner static loop. Defaults to `'newton-raphson'`. Other options include `'least_squares'` and `'fsolve'`. `'fsolve'` is currently in alpha stages and is unstable. suppress_warnings: bool Option to suppress warnings associated with solving the endogenous equations. These warnings are typically harmless and occur due to functions compiled by SymPy. Defaults to `True`. It is only recommended to set this option to `False` if you are debugging issues in the endogenous equations and want to see output of exact equations being solved. return_solution: bool Whether or not to return the solution in the form of a Pandas DataFrame from the `macro_model.run` method. Defaults to `False`. save_solution: bool Whether or not to save the solution down to a file after convergence. Defaults to `True`. price_derivative_method: str Price derivative method. Options include `'central'`, `'forward'`, and `'backward'`. Defaults to `'central'`.

loop: bool: Whether or not to enable the second loop stage of the outer loop. If True, after the minimum number of iterations and the tolerance is satisfied on the outer loop, a second loop stage is activated. If enabled, this allows for two stages with varying levels of error tolerance. Defaults to False.
min_iter_inner_static: int: Minimum iterations for the inner static loop. Defaults to 2.
max_iter_inner_static: int: Maximum iterations for the inner static loop. Defaults to 10,000.
tol_inner_static: numeric: Error tolerance for the inner static loop. Defaults to 1.0e-6.
min_iter_outer_static: int: Minimum iterations for the outer static loop. Defaults to 2.
max_iter_outer_static: int: Maximum iterations for the outer static loop. Defaults to 100.
tol_outer_static: numeric: Error tolerance for outer static loop. Defaults to 1.0e-4
damp1: numeric: Initial dampening factor for the static loop. Defaults to 0.1.
damp1_adjustment: numeric: Dampening adjustment factor. This number should be between zero and one. The dampening factor is multiplied by this adjustment each loop to speed up convergence. Defaults to 1.
min_damp1: numeric: Minimum dampening factor. Defaults to 0.
damp2: numeric: Initial dampening factor for the static loop (second stage). Defaults to 0.1.
damp2_adjustment: numeric: Dampening adjustment factor (second stage). This number should be between zero and one. The dampening factor is multiplied by this adjustment each loop to speed up convergence. Defaults to 1.
min_damp2: numeric: Minimum dampening factor for the second stage. Defaults to 0.
min_hjb1: int: Minimum iterations for the outer HJB update loop (dynamic loop). Defaults to 100.
min_hjb2: int: Minimum iterations for the outer HJB update loop (second stage). Defaults to 10.
max_hjb: int: Maximum iterations for the outer HJB update loop (dynamic loop). Defaults to 10000.
tol_hjb: numeric: Error tolerance for the outer HJB update loop (dynamic loop). Defaults to 0.01.
dt: numeric: Time step for the HJB update loop (dynamic loop). Defaults to 0.1.
dt2: numeric: Time step for the HJB update loop (second stage). Defaults to 0.1.
tol_d: numeric: Error tolerance for the stencil decomposition algorithm. Defaults to 1.0e-4.
max_p: int: Maximum stencil size for decomposition algorithm.
n0: int: Number of points to use in the finite difference grid in the dimension associated with the first element of the model state attribute. Defaults to 50.
n1: int: Number of points to use in the finite difference grid in the dimension associated with the second element of the model state attribute. Defaults to 50.
start0: numeric: First point use in the finite difference grid in the dimension associated with the first element of the model state attribute. Defaults to 0.01.
start1: numeric: First point use in the finite difference grid in the dimension associated with the second element of the model state attribute. Defaults to 0.01.
end0: numeric: Last point use in the finite difference grid in the dimension associated with the first element of the model state attribute. Defaults to 0.99.
end1: numeric: Last point use in the finite difference grid in the dimension associated with the second element of the model state attribute. Defaults to 0.99.
quiet: bool: Whether or not to suppress update output. Defaults to False.
import_guess: bool: Whether or not to import an initial guess to work from. Defaults to False.
guess_function: False or function: Possibility to provide a function to calculate initial guesses from state variable values. If not False, initial guesses for endogenous and value variables will be calculated from the provided function. The function should return a vector in the order of endogenous variables first, then value variables, such that the length of the vector returned by the function should be equal to the lengths of macro_model.endog and macro_model.value summed. The function provided should accept two arguments, corresponding to the two state variables in macro_model.state. Defaults to False
import_guess_location: str: File path to the csv file where the guess file is located. Defaults to None and is not used unnless import_guess is set to True. The guess file should be a comma-separated values file with columns labeled and completed for all value, state, and endogenous variables. Note that the grid specified by options start0, start1, end0, end1, n0, above and n1 must be consistent with the grid implied by the guess file. It is useful to run a simple dummy model without a guess file with the same grid specification, then modify the file saved down by the dummy model without changing the ordering or specification of state variables to create a guess file.
inner_plot: bool: Whether or not to plot after each outer static loop iteration. Defaults to False.
outer_plot: bool: Whether or not to plot after each HJB loop iteration. Defaults to False.
final_plot: bool: Whether to plot after convergence. Defaults to True.
derivative_plotting: list(tuple(str)): List of tuples to indicate derivatives to be plotted in addition to endogenous variables and selected secondary variables. Tuples should be of the same form as the input to equations. For example, for the second derivative of a price q to state variable x will have the tuple ('q','x','x').
parallel: bool: Whether or not to run the static loop in parallel. Defaults to True.
client: str: Must either be 'local' or 'user-provided'. When set to 'local', PyMacroFin will create a dask client that will parallelize locally on your machine. If set to 'user-provided', PyMacroFin will assume there is a dask client already running that the user has defined outside of PyMacroFin, and an error will be thrown if a client is not found. This option is useful when the user would like to define a cluster specific to a high-performance computing environment or a cloud computing service; however, using this option requires familiarity with dask and your computing environment architectural details. Defaults to 'local'.
dask_timeout: int: Number of seconds for the dask scheduler to wait for workers before timing out. Defaults to 100 seconds. Only used if parallelization is used.
dash_debug: bool: Whether or not to run the visualization Dash application in debug mode. Defaults to False.
dash_port: int: Local port on which to run the Dash visualization application. Defaults to 8050.
dash_port_stationary: int: Local port on which to run a second Dash visualization application for calculation of a stationary distribution. Defaults to 8000.
ignore_HJB_loop: bool: An option to ignore the HJB loop and return after running one iteration of the outer static loop. This is suitable for problems that do not require iteration through the dynamic HJB loop. Defaults to False.
inner_solver: str: Solver to use for the inner static loop. Defaults to 'newton-raphson'. Other options include 'least_squares' and 'fsolve'. 'fsolve' is currently in alpha stages and is unstable.
suppress_warnings: bool: Option to suppress warnings associated with solving the endogenous equations. These warnings are typically harmless and occur due to functions compiled by SymPy. Defaults to True. It is only recommended to set this option to False if you are debugging issues in the endogenous equations and want to see output of exact equations being solved.
return_solution: bool: Whether or not to return the solution in the form of a Pandas DataFrame from the macro_model.run method. Defaults to False.
save_solution: bool: Whether or not to save the solution down to a file after convergence. Defaults to True.
price_derivative_method: str: Price derivative method. Options include 'central', 'forward', and 'backward'. Defaults to 'central'.

Methods

set_defaults() Reset all options to default values.

set_defaults()¶

Reset all options to default values.

Parameters:	None

Notes

See the documentation for the class for descriptions of options as well as their default values.

class PyMacroFin.parameters.parameters¶

A simple container class for model parameters.

Methods

add_parameter(name, value) Add a constant parameter to be used in model equations.

add_parameter(name, value)¶

Add a constant parameter to be used in model equations.

Parameters:	name: str The name of the parameter. value: numeric The numeric value assigned to the parameter.

Notes

It is typically useful to define all parameters prior to defining equations so that parameters can be used in equations.

Parameters and Options Module

Parameters and Options Module

Table Of Contents

Parameters and Options Module¶