Model Module

The model module houses the main model class. The model class is built to accept and process the inputs required to run the solution procedure found here and described briefly here.

class PyMacroFin.model.macro_model(name='')

Model class to assign equations, variables, parameters, options, constraints, etc. Once the model is defined by the user, upon calling the run method, the jacobians are computed and the model is run to convergence.

Parameters:

name: str

Name of the model. This will be used in file names when saving down solution files (the file name will consist of the time, date, and model name). This is also used for the visualization application.

Attributes:

options: PyMacroFin.parameters.options

An options class with highly configurable options (documentation here. When a macro_model object is instantiated, this attribute is created with default values that can be modified by the user.

parameters: PyMacroFin.parameters.parameters

An attribute to house model parameters. An empty parameters object is created upon macro_model instantiation. See documentation here.

Methods

boundary_condition(boundary, condition)	Add a boundary condition for endogenous variable values to the model.
constraint(endog_var, constraint_type, bound)	Add constraint to an endogenous variable.
endog_equation(eq)	Add an equation to the core system to solve for endogenous variable values.
equation(eq[, plot, latex])	Define a new intermediate variable with an equation.
hjb_equation(hjbvar, linkvar, eq)	Define variables to be used in the dynamic iteration of the equation shown in this section.
run()	Runs the specified model to convergence according to the process described here.
set_endog(endog[, init, latex])	Define endogenous variables and (optionally) provide associated initialization values and latex strings.
set_state(state[, latex])	Define state variables and (optionally) provide associated latex strings.
set_value(value[, init, latex])	Define value variables and (optionally) provide associated initialization values and latex strings.

set_state(state, latex=None)

Define state variables and (optionally) provide associated latex strings.

Parameters:

endog: list(str)

List of strings that define endogenous variables.

latex: list(str)

List of raw strings

Notes

1. The values of the state variables are defined by the options in this section.
2. In the current release, due to issues in packages used for the visualization, the state variables are rendered simply as x and y in plots regardless of the inputs for the latex argument.

set_endog(endog, init='default', latex=None)

Define endogenous variables and (optionally) provide associated initialization values and latex strings.

Parameters:

endog: list(str)

List of strings that define endogenous variables.

init: str or list(numeric)

List of values to initialize the endogenous variables with, or 'default' (default value). If 'default' then each endogenous variable is initialized at zero.

latex: list(str)

List of raw strings

Notes

1. The number of endogenous variables must be equal to the number of endogenous equations specified.
2. Rather than using initialization with constant values as supported in this method, you can also specify a file or function from which to initialize each variable value at each individual grid point. This can be done in the options class.
3. See the documentation in this section for more detail on which variables to define with this method.

set_value(value, init='default', latex=None)

Define value variables and (optionally) provide associated initialization values and latex strings. See the value variable section for more detail on value variables.

Parameters:

value: list(str)

List of strings that define value variables.

init: str or list(numeric)

List of values to initialize the endogenous variables with, or 'default' (default value). If 'default' then each endogenous variable is initialized at zero.

latex: list(str)

List of raw strings

Notes

1. Rather than using initialization with constant values as supported in this method, you can also specify a file from which to initialize each variable value at each individual grid point. This can be done in the options class.

equation(eq, plot=False, latex=None)

Define a new intermediate variable with an equation.

Parameters:

eq: str

This string should be of the form newvar = f(<previously defined variables>). For example, if b and c are already defined as parameters, endogenous variables, value variables, or defined in previous equations, then eq='a = b + c' is acceptable.

plot: bool

Whether or not to include the defined variable in the visualization application.

latex: str

Latex to be used for plot labels. Unused if plot=False. Defaults to None.

Notes

1. See the derivatives section for using derivatives in equations.

endog_equation(eq)

Add an equation to the core system to solve for endogenous variable values. This equation will be solved to be equal to zero to find the values of the endogenous variables at each grid point.

Parameters:

eq: str

This string should be of the form f(<previously defined variables>). For example, if b and c are already defined as parameters, endogenous variables, value variables, or defined in previous equations, then eq='b + c' is acceptable. At equilibrium, the expression given by eq should be equal to zero.

Notes

1. See the derivatives section for using derivatives in equations.

hjb_equation(hjbvar, linkvar, eq)

Define variables to be used in the dynamic iteration of the equation shown in this section. You must specify the drift and volatilty of each state variable’s law of motion and you must specify the \(u\) and \(r\) values for each value variable (for each \(F(X,t)\)).

Parameters:

hjbvar: str

This is the type of variable you are specifying. This should either be 'mu', 'sig', 'u', or 'r'.

linkvar: str

This is the variable you are associating the hjbvar with. For example, if hjbvar = 'mu' and linkvar = 'a', then you are assigning the equation to the drift of the state variable a.

eq: str

This string should be of the form f(<previously defined variables>). For example, if b and c are already defined as parameters, endogenous variables, value variables, or defined in previous equations, then eq='b + c' is acceptable. The expression given by eq should be the variable described in the descriptions of hjbvar and linkvar.

Notes

1. See the derivatives section for using derivatives in equations.

constraint(endog_var, constraint_type, bound, label='')

Add constraint to an endogenous variable. Constraint behavior depends on the solver selected by the macro_model.options.inner_solver option. For details on constraint behavior with different solvers and usage of constraints with equation systems, see this section.

Parameters:

endog_var: str

The endogenous variable to be constrainted.

constraint_type: str

This must be '<' or '>'. The reading is that if m.constraint('a','<',10) is specified than the constraint written is a < 10.

bound: numeric

The constraint bound value.

label: str

A label to use when referencing this constraint in endogenous equation systems. Defaults to an empty string, meaning the constraint cannot be referenced in a system.

Notes

1. Any variable to be constrained, whether traditionally considered to be “endogenous” or not, must be defined by the set_endog method. See details here.

boundary_condition(boundary, condition)

Add a boundary condition for endogenous variable values to the model.

Parameters:

boundary_: dict

This boundary must be of the following form: {'state':'bound_type'} where ‘state’ is the name of the state variable as a string and ‘bound_type’ is either 'min' or 'max'. For example, if my state variables were 'e' and 'z' and I would like to create a boundary condition for the grid boundary where 'e' takes its minimum value, I would set this argument equal to {'e':'min'}. You can specify boundaries at corners by giving the dictionary two entries as follows: {'e':'min','z':'max'}.

condition: function

A function that accepts a dictionary as an input with state variable and parameter names as keys (and appropriate values as dictionary values). This function should return a vector of endogenous variable values (with the same order as input with macro_model.set_endog).

Notes

1. While the function should accept a dictionary as an argument, the function is not required to use any entries in the dictionary. A boundary unrelated to parameters and state variable values may be defined.
2. Allowing boundaries to be specified by user-defined functions allows for high flexibility in defining boundary conditions as opposed to using the equation definition format.

run()

Runs the specified model to convergence according to the process described here.

Parameters:

None

Notes

1. It can be helpful to run the visualization application along with the model to see live updates of 3D surfaces of any chosen variable from the model (or derivative). The plots are shown in a browser and are fully interactive. Documentation for the visualization application can be found here.
2. Although there are no direct inputs to this method, the behavior of the model is highly configurable by specifying options in the macro_model.options attribute (see here for documentation on model options).

Endogenous Variables

It is important to note here that a variable defined by macro_model.set_endog need not be strictly an “endogenous” variable in economic terminology. Any variable whose value needs to (1) be constrained or (2) be solved with a system of equations rather than by simple definition in terms of other variables can be set by macro_model.set_endog. For example, if a choice variable x for an agent needs to be constrained, it should be defined in macro_model.set_endog. If it has a definition in terms of other variables (i.e. f(vars)) when the constraint is nonbinding, in the core system of endogenous equations you may specify macro_model.endog_equation('x - f(vars)'). Then, when constrained you may specify another solution in a constraint system or simply remove an equation and set the constrained variable equal to the bound (see documentation here).

Value Variables

A “value” variable is a variable that takes the form of \(F(X,t)\) in the following equation form:

\[r(X)F(X,t) = u(X)+\sum^m_{i=1} \mu_i(X) \frac{\partial F(X,t)}{\partial x_i} + \sum_{i=1}^m \sum_{j=1}^m \frac{\sigma_i(X)\sigma_j(X)}{2} \frac{\partial^2 F(X,t)}{\partial x_i \partial x_j} + \frac{\partial F(X,t)}{\partial t}\]

Often, this is a wealth multiplier to link wealth and utility such as \(\xi\) in an equation such as the following:

\[U(n_t,\xi_t) = \frac{\left( n_t \right)^{1-\gamma}\xi_t}{1-\gamma}\]

where \(U(n_t,\xi_t)\) is utility, \(n_t\) is wealth, and \(\gamma\) is risk aversion.

Derivatives

Derivatives of price and value variables with respect to state variables may be used in all forms of equation inputs [1]. To specify a derivative of price q with respect to state a then you would write d(q,a) in your equation. To specify a second order derivative, write d(q,a,a) or d(q,a,b) for a cross derivative for states a and b. Derivatives of order higher than two are not supported.

Footnotes

[1]	To take derivatives of other variables, you may simply add these variables to the macro_model.prices attribute.