Toolbox API Reference

Toolbox Script (hmod) File

Important

All statements need to be closed by a semicolon.

parameters var1 var2 ...;

Declare parameters that are used in the vfi block.

“parameters” should include those which (1) enter the vfi block explicitly; or (2) enter the definition of var_pre_vfi and will change with var_agg.

var_shock var1 var2 ...;

Declare individual exogenous state variables. They need to be Markov chains with discretized values specified.

Their joint transition matrix needs to be specified in varaible shock_trans.

Example:

 1var_shock e z;
 2e_grid = [1.0, 2.0];
 3e_trans = [0.4 0.6;0.6 0.4];
 4z_grid = [2.0,3.0,4.0];
 5z_trans = [0.6 0.2 0.2;0.2 0.6 0.2; 0.2 0.2 0.6];
 6% form tensor product
 7[e,z] = ndgrid(e,z);
 8e = e(:)';
 9z = z(:)';
10shock_trans = kron(z_trans, e_trans);
var_state var1 var2 ...;

Declare individual endogenous state variables. They need to be continuous varialbes.

The grid for each endogenous state variable needs to be specified. Value and policy functions will be approximated over these grids with linear interpolation or cubic splines.

var_pre_vfi var1 var2 ...;

Declare variables that are simple functions of var_shock and/or var_state, which can be evaluated before the vfi block.

A var_pre_vfi can be used in defining the initial values of var_policy or direclty used in the vfi block. This avoids unnecessary repetitive evaluations of these varaibles in solving the optimization problem.

Example:

 1parameters beta r w;
 2...
 3
 4var_shock e;
 5...
 6
 7var_state a;
 8...
 9
10var_pre_vfi budget;
11budget = (1+r)*a + w*e;
12
13var_policy ap;
14...
15
16vfi;
17    c = budget - ap;
18    Tv = u(c) + beta*EXPECT(v(ap));
19    ap >= 0.0;
20end;
var_policy var1 var2 ...;

Declare individual policy variables, i.e., variables to be optimized with. Their initial values need to be specified, which can be dependent on state values or var_pre_vfi.

Example:

 1parameters beta r w;
 2...
 3
 4var_shock e;
 5...
 6
 7var_state a;
 8...
 9
10var_pre_vfi budget;
11budget = (1+r)*a + w*e;
12
13var_policy c ap;
14initial ap 0.0;
15initial c budget;
16
17vfi;
18    Tv = u(c) + beta*EXPECT(v(ap));
19    ap >= 0.0;
20    c + ap == budget;
21end;
var_aux var1 var2 ...;

Declare auxilliary variables which can be evaluated as simple functions of var_shock, var_state, and/or var_policy.

They need to be defined in the vfi block and will be returned.

Example:

 1parameters beta r w;
 2...
 3
 4var_shock e;
 5...
 6
 7var_state a;
 8...
 9
10var_pre_vfi budget;
11budget = (1+r)*a + w*e;
12
13var_policy c ap;
14initial ap 0.0;
15initial c budget;
16
17var_aux inc;
18
19vfi;
20    Tv = u(c) + beta*EXPECT(v(ap));
21    ap >= 0.0;
22    c + ap == budget;
23    inc = a*r + w*e;
24end;
vfi; ... end;

Define the vfi block. The block is executed line by line from top to bottom. In the block,

  • The updated value after each iteration needs to be assigned to “Tv”

  • The objective of the optimization needs to be assigned to “objective”. If variable “objective” is not found, “Tv” will be used as the objective.

  • Future value function (i.e., value function from the last iteration) can be evaluated by calling v(var_state_1_future, var_state_2_future,…). If calling is warpped by EXPECT(), then the expected value will be calculated using the transition matrix conditional on current value of exogenous states.

  • Equality or inequality constraints can be specified with “==”, “<=” or “>=”.

  • All var_aux need to be defined.

  • The state transition is inferred from the arguments when evaluating future value functions. One can also specify the state transition explicity by the line: var_state(+1) = {state_value_1, state_value_2, …} {prob_1, prob_2, }, where state_value_1, state_value_2, … are values of states, and prob_1, prob_2 are the associated probabilities (for stochastic transitions).

Example:

 1parameters beta r w;
 2...
 3
 4var_shock e;
 5...
 6
 7var_state a;
 8...
 9
10var_pre_vfi budget;
11budget = (1+r)*a + w*e;
12
13var_policy c ap;
14initial ap 0.0;
15initial c budget;
16
17var_aux inc;
18
19vfi;
20    % assign updated value to Tv
21    % Tv will also be the objective
22    % state transition is inferred to be "ap"
23    Tv = u(c) + beta*EXPECT(v(ap));
24
25    % can also specify the state transition explicitly
26    a(+1) = {ap} {1};
27
28    % equality and inequality constraints
29    ap >= 0.0;
30    c + ap == budget;
31
32    % var_aux needs to be assigned
33    inc = a*r + w*e;
34end;

Note

Defining the following equilibrium model and required information is optional. The parser can generate standalone codes for solving the value function iteration.

var_agg var1 var2 ...;

Declare unknowns in aggregate equilibirium conditions.

Their initial values need to be specified.

var_agg_shock var1 var2 ...;

Declare exogenous time-varying aggregate variables.

Their steady state values need to be specified.

For var_agg_shock named “var”, its time sequence value can be overwritten by supplying a field named “var_t” in the options passed to the model solving script.

model; ... end;

Define the system of equations that represents the aggregate equilibrium system. In the block,

  • Each equation is defined with a line that contains “==”.

  • Statements are evaluated from top to bottom, which assign values to intermediate variables.

  • All individual parameters that change with var_agg (e.g., wage and interest rates that depend on capital stock) need to be updated before defining the system of equations.

  • var_policy can be used in defining the equation, which represents the aggregates of individual policy functions integrated over the distribution of states.

  • Lags and leads of variables are represented by varname(-l) or varname(+l), where l is the number of lag or lead periods. Only variables declared as var_agg can have lags and leads (i.e., intermediate values assigned cannot be indexed with lags or leads).

  • Pre-determined variables should enter the system as lagged variables.

  • All left hand side assigned variables will be returned after the equations are solved. This facilitates calculating extra equilibrium variables of interests.

Example:

 1parameters beta r w;
 2...
 3
 4
 5var_state a;
 6...
 7
 8var_policy ap;
 9...
10
11vfi;
12	...
13end;
14
15var_agg K;
16K = 30.0;	% initial value for solving the stead state
17var_agg_shock Z;
18Z = 1.0;	% steady state value
19
20model;
21    % update parameters that enter vfi
22    % capital is pre-determined, use the lagged value K(-1)
23    r = alpha * Z * K(-1)^(alpha-1) * L^(1-alpha) - delta;
24    w = (1-alpha) * Z * K(-1)^alpha * L^(-alpha);
25
26    % use "==" to define equations
27    % ap used below is the aggregate of policy ap
28    K == ap; % asset demand = asset supply
29
30    % post evaluation; all assignments will be returned
31    Y = Z*(K(-1)^alpha)*(L^(1-alpha));
32    I = K - (1 - delta)*K(-1);
33    C = Y - I;
34end;
model_modname(var_agg_1, var_agg_2); ... end;

Define an alternative equilibrium system with unknowns overwritten by (var_agg_1, var_agg_2, …).

The parser will generate a “solve_modname.m” script file for each alterantive model_modname block.

This allows multiple different models to share the same vfi block (e.g., the system for calibration is different from the system of solving the equilibrium).

Example:

 1...
 2
 3var_agg K;
 4
 5model;
 6    % this block is used for solving the equilibrium
 7    r = alpha * Z * K(-1)^(alpha-1) * L^(1-alpha) - delta;
 8    w = (1-alpha) * Z * K(-1)^alpha * L^(-alpha);
 9    K == ap; % asset demand = asset supply
10end;
11
12model_cali(K,beta);
13    % this block is used for calibration 
14    r = alpha * Z * K(-1)^(alpha-1) * L^(1-alpha) - delta;
15    w = (1-alpha) * Z * K(-1)^alpha * L^(-alpha);
16    Y = Z*(K(-1)^alpha)*(L^(1-alpha));
17    K == ap; % asset demand = asset supply
18    K/Y == KY_ratio_target;	% for calibration
19end;

MATLAB Interfaces

solve_vfi(options)

Solve the value function iteration.

Parameters:

  • options –

    a structure that can contain fields below

    • interp_order: the order of interpolation and extrapolation in value function approximations. Default: ‘4+3’

      • ‘4’: cubic

      • ‘2’: linear

      • ‘4+2’: cubic interpolation + linear extraplation

      • ‘4+3’: cubic interpolation + quadrait extrapolation

      • ‘pchip’: MATLAB’s pchip (only for single-dimensional endogenous state)

    • algorithm: the algorithm used in solving the optimization problem. Default: ‘dbrent’ for single-dimensional choice with box constraints; ‘donlp2’ otherwise. Allowed values:

      • ‘dbrent’

      • ‘golden’

      • ‘brent’

      • ‘nr3_dbrent’

      • ‘donlp2’

    • vfi_tol_v: tolerance for convergence in value functions. Default: 1e-6

    • vfi_tol_policy: tolerance for convergence in policy functions. Default: 1e-12

    • print_freq: frequencies of printing information. Default: 100

    • solver_tol_x: tolerance for optimality for the optimization problem. Default: 1e-8

    • solver_tol_con: tolerance for feasibility for the optimization problem. Default: 1e-8

    • num_threads: number of threads used in solving the optimization problem across state values. Default: value returned by feature(‘numcores’)

  • options – parameter values contained in the structure will be used to overwrite existing ones.

Returns:

a structure that contains the solved policy functions

solve_ss(options)

Solve the steady state of the equilbrium system defined in the model block.

Parameters:

  • options –

    a structure that can contain fields below

    • ss_solver: the equation solver used for solving the steady state system. Default: ‘Broyden’. Allowed values:

      • ‘Broyden’

      • ‘Newton’

      • ‘lsqnonlin’

      • ‘CoDoSol’

      • ‘fsolve’

    • ss_ftol: tolerance for residuals of equations passed to the equation solver. Default: 1e-4

    • ss_xtol: tolerance for step sizes passed to the equation solver. Default: 1e-6

    • ss_findiffstep: finite difference step for calculating numerical derivatives. Default: 1e-4

    • HANS_x: initial values of unknowns

  • options – can also contain options passed to solving the value function iteration

  • options – can also contain parameter values to be overwritten

Returns:

a structure that contains the solved steady state

solve_trans_linear(ss, options)

Solve the linearized transition path following the Sequence Space Jacobian method. The Jacobian matrix of individual aggregates with respect to parameters is calculated using the fake news algorithm.

Parameters:

  • ss – a structure that conatins the solved steady state (returned by solve_ss) around which the linearization is carried out

  • options –

    a structure that can contain fields below

    • T: number of periods of the transition path. Default: 200

  • options – for a var_agg_shock named “var”, supply the updated time sequence in field “var_t” of the structure

  • options – can also contain options passed to solving the value function iteration

  • options – can also contain parameter values to be overwritten

Returns:

a structure that contains the solved transition path and the Jacobian matrix of individual aggregates with respect to parameters

solve_trans_nonlinear(init_ss, final_ss, options)

Solve the non-linear transition path.

Parameters:

  • init_ss – a structure that conatins the initial steady state that the transition path starts from

  • final_ss – a structure that conatins the final steady state that the transition path converges to

  • options –

    a structure that can contain fields below

    • T: number of periods of the transition path. Default: 200

    • trans_linear_rslt: the solved linearized transition path, which contains the Jacobian matrix of individual aggregates with respect to parameters, that is used to form the initial Jacobian of the nonlinear equation system. Default: empty; will call solve_trans_linear to calculate

    • trans_solver: the equation solver. Default: “Broyden”. Allowed values:

      • “Broyden”

      • “FixedJacobian”

      • “BroydenMod”

      • “Newton”

      • “fsolve”

    • trans_ftol: tolerance for residuals of equations passed to the equation solver. Default: 1e-4

    • trans_xtol: tolerance for step sizes passed to the equation solver. Default: 1e-6

    • HANS_x: initial values of unknowns

  • options – can also contain options passed to solving the value function iteration

  • options – can also contain parameter values to be overwritten

Returns:

a structure that contains the solved nonlinear transition path

solve_*modname*(options)

Solve the steady state of the alternative equilbrium system defined in the model_modname block.

Functions share the same input and output structures as solve_ss.

simulate_stochastic(eq_rslt, options)

Simulate individual random samples with the solved equilibrium.

Parameters:

  • eq_rslt – a structure that contains a steady state equilibrium (returned by solve_ss) or a transition path (returned by solve_nonlinear_trans)

  • options –

    a structure that can contain fields below

    • num_samples: number of individual samples. Default: 1e4

    • num_periods: number of periods. Default: 1e3

    • simulate_initials: a structure that contains the initial state values. Default: empty; will sample state values from the stationary distribution

    • interp_order: the order of interpolation and extrapolation in policy function approximations. Default: ‘2’

      • ‘4’: cubic

      • ‘2’: linear

      • ‘4+2’: cubic interpolation + linear extraplation

      • ‘4+3’: cubic interpolation + quadrait extrapolation

    • simu_print_freq: frequency of printing the summary statsitics along the simulation. Default: 1000

    • num_threads: number of threads used in interpolating policy functions. Default: value returned by feature(‘numcores’)