the-model-file.rst

The model file

Conventions

A model file contains a list of commands and of blocks. Each command and each element of a block is terminated by a semicolon (;). Blocks are terminated by end;.

If Dynare encounters an unknown expression at the beginning of a line or after a semicolon, it will parse the rest of that line as native MATLAB code, even if there are more statements separated by semicolons present. To prevent cryptic error messages, it is strongly recommended to always only put one statement/command into each line and start a new line after each semicolon. [1]

Lines of codes can be commented out line by line or as a block. Single-line comments begin with // and stop at the end of the line. Multiline comments are introduced by /* and terminated by */.

Examples

// This is a single line comment

var x; // This is a comment about x

/* This is another inline comment about alpha */  alpha = 0.3;

/*
 This comment is spanning
 two lines.
*/

Note that these comment marks should not be used in native MATLAB code regions where the % should be preferred instead to introduce a comment. In a verbatim block, see :ref:`verbatim`, this would result in a crash since // is not a valid MATLAB statement).

Most Dynare commands have arguments and several accept options, indicated in parentheses after the command keyword. Several options are separated by commas.

In the description of Dynare commands, the following conventions are observed:

• Optional arguments or options are indicated between square brackets: ‘[]’;
• Repeated arguments are indicated by ellipses: “...”;
• Mutually exclusive arguments are separated by vertical bars: ‘|’;
• INTEGER indicates an integer number;
• INTEGER_VECTOR indicates a vector of integer numbers separated by spaces, enclosed by square brackets;
• DOUBLE indicates a double precision number. The following syntaxes are valid: 1.1e3, 1.1E3, 1.1d3, 1.1D3. In some places, infinite Values Inf and -Inf are also allowed;
• NUMERICAL_VECTOR indicates a vector of numbers separated by spaces, enclosed by square brackets;
• EXPRESSION indicates a mathematical expression valid outside the model description (see :ref:`expr`);
• MODEL_EXPRESSION (sometimes MODEL_EXP) indicates a mathematical expression valid in the model description (see :ref:`expr` and :ref:`model-decl`);
• MACRO_EXPRESSION designates an expression of the macro processor (see :ref:`macro-exp`);
• VARIABLE_NAME (sometimes VAR_NAME) indicates a variable name starting with an alphabetical character and can’t contain: ()+-\*/^=!;:@#. or accentuated characters;
• PARAMETER_NAME (sometimes PARAM_NAME) indicates a parameter name starting with an alphabetical character and can’t contain: ()+-\*/^=!;:@#. or accentuated characters;
• LATEX_NAME (sometimes TEX_NAME) indicates a valid LaTeX expression in math mode (not including the dollar signs);
• FUNCTION_NAME indicates a valid MATLAB function name;
• FILENAME indicates a filename valid in the underlying operating system; it is necessary to put it between quotes when specifying the extension or if the filename contains a non-alphanumeric character;
• QUOTED_STRING indicates an arbitrary string enclosed between (single) quotes;
• DATE indicates a time period which can be either a year (e.g. 2024Y or 2024A), a half-year (2024S1 or 2024H1), a quarter (2024Q2) or a month (2024M3) (see :ref:`dates in a mod file`). Optionally, the time period can be followed by a plus sign and a number of periods, in which case the date is shifted accordingly (e.g. 2023Q1+6 is accepted and is equivalent to 2024Q3).

Variable declarations

While Dynare allows the user to choose their own variable names, there are some restrictions to be kept in mind. First, variables and parameters must not have the same name as Dynare commands or built-in functions. In this respect, Dynare is not case-sensitive. For example, do not use Ln or shocks to name your variable. Not conforming to this rule might yield hard-to-debug error messages or crashes. Second, when employing user-defined steady state files it is recommended to avoid using the name of MATLAB functions as this may cause conflicts. In particular, when working with user-defined steady state files, do not use correctly-spelled greek names like alpha, because there are MATLAB functions of the same name. Rather go for alppha or alph. Lastly, please do not name a variable or parameter i. This may interfere with the imaginary number i and the index in many loops. Rather, name investment invest. Using inv is also not recommended as it already denotes the inverse operator. Commands for declaring variables and parameters are described below.

On-the-fly Model Variable Declaration

Endogenous variables, exogenous variables, and parameters can also be declared inside the model block. You can do this in two different ways: either via the equation tag (only for endogenous variables) or directly in an equation (for endogenous, exogenous or parameters).

To declare an endogenous variable on-the-fly in an equation tag, simply write endogenous followed by an equal sign and the variable name in single quotes. Hence, to declare a variable c as endogenous in an equation tag, you can type [endogenous='c'].

To perform on-the-fly variable declaration in an equation, simply follow the symbol name with a vertical line (|, pipe character) and either an e (for endogenous), an x (for exogenous), or a p (for parameter). For example, to declare a parameter named alphaa in the model block, you could write alphaa|p directly in an equation where it appears. Similarly, to declare an endogenous variable c in the model block you could write c|e. Note that in-equation on-the-fly variable declarations must be made on contemporaneous variables.

On-the-fly variable declarations do not have to appear in the first place where this variable is encountered.

Example

The following two snippets are equivalent:

model;
  [endogenous='k',name='law of motion of capital']
  k(+1) = i|e + (1-delta|p)*k;
  y|e = k^alpha|p;
  ...
end;
delta = 0.025;
alpha = 0.36;

var k, i, y;
parameters delta, alpha;
delta = 0.025;
alpha = 0.36;
...
model;
  [name='law of motion of capital']
  k(1) = i|e + (1-delta|p)*k;
  y|e = k|e^alpha|p;
  ...
end;

Expressions

Dynare distinguishes between two types of mathematical expressions: those that are used to describe the model, and those that are used outside the model block (e.g. for initializing parameters or variables, or as command options). In this manual, those two types of expressions are respectively denoted by MODEL_EXPRESSION and EXPRESSION.

Unlike MATLAB or Octave expressions, Dynare expressions are necessarily scalar ones: they cannot contain matrices or evaluate to matrices. [2]

Expressions can be constructed using integers (INTEGER), floating point numbers (DOUBLE), parameter names (PARAMETER_NAME), variable names (VARIABLE_NAME), operators and functions.

The following special constants are also accepted in some contexts:

Parameters and variables

Parameters and variables can be introduced in expressions by simply typing their names. The semantics of parameters and variables is quite different whether they are used inside or outside the model block.

Inside the model

Parameters used inside the model refer to the value given through parameter initialization (see :ref:`param-init`) or homotopy_setup when doing a simulation, or are the estimated variables when doing an estimation.

Variables used in a MODEL_EXPRESSION denote current period values when neither a lead or a lag is given. A lead or a lag can be given by enclosing an integer between parenthesis just after the variable name: a positive integer means a lead, a negative one means a lag. Leads or lags of more than one period are allowed. For example, if c is an endogenous variable, then c(+1) is the variable one period ahead, and c(-2) is the variable two periods before.

When specifying the leads and lags of endogenous variables, it is important to respect the following convention: in Dynare, the timing of a variable reflects when that variable is decided. A control variable — which by definition is decided in the current period — must have no lead. A predetermined variable — which by definition has been decided in a previous period — must have a lag. A consequence of this is that all stock variables must use the “stock at the end of the period” convention.

Leads and lags are primarily used for endogenous variables, but can be used for exogenous variables. They have no effect on parameters and are forbidden for local model variables (see Model declaration).

Outside the model

When used in an expression outside the model block, a parameter or a variable simply refers to the last value given to that variable. More precisely, for a parameter it refers to the value given in the corresponding parameter initialization (see :ref:`param-init`); for an endogenous or exogenous variable, it refers to the value given in the most recent initval or endval block.

Operators

The following operators are allowed in both MODEL_EXPRESSION and EXPRESSION:

• Binary arithmetic operators: +, -, *, /, ^
• Unary arithmetic operators: +, -
• Binary comparison operators (which evaluate to either 0 or 1): <, >, <=, >=, ==, !=

Note the binary comparison operators are differentiable everywhere except on a line of the 2-dimensional real plane. However for facilitating convergence of Newton-type methods, Dynare assumes that, at the points of non-differentiability, the partial derivatives of these operators with respect to both arguments is equal to 0 (since this is the value of the partial derivatives everywhere else).

The following special operators are accepted in MODEL_EXPRESSION (but not in EXPRESSION):

Functions

Built-in functions

The following standard functions are supported internally for both MODEL_EXPRESSION and EXPRESSION:

External functions

Any other user-defined (or built-in) MATLAB or Octave function may be used in both a MODEL_EXPRESSION and an EXPRESSION, provided that this function has a scalar argument as a return value.

To use an external function in a MODEL_EXPRESSION, one must declare the function using the external_function statement. This is not required for external functions used in an EXPRESSION outside of a model block or steady_state_model block.

A few words of warning in stochastic context

The use of the following functions and operators is strongly discouraged in a stochastic context: max, min, abs, sign, <, >, <=, >=, ==, !=.

The reason is that the local approximation used by stoch_simul or estimation will by nature ignore the non-linearities introduced by these functions if the steady state is away from the kink. And, if the steady state is exactly at the kink, then the approximation will be bogus because the derivative of these functions at the kink is bogus (as explained in the respective documentations of these functions and operators).

Note that extended_path is not affected by this problem, because it does not rely on a local approximation of the mode.

Parameter initialization

When using Dynare for computing simulations, it is necessary to calibrate the parameters of the model. This is done through parameter initialization.

The syntax is the following:

PARAMETER_NAME = EXPRESSION;

Here is an example of calibration:

parameters alpha, beta;

beta = 0.99;
alpha = 0.36;
A = 1-alpha*beta;

Internally, the parameter values are stored in M_.params:

The parameter names are stored in M_.param_names:

Model declaration

The model is declared inside a model block:

Dynare has the ability to output the original list of model equations to a LaTeX file, using the write_latex_original_model command, the list of transformed model equations using the write_latex_dynamic_model command, and the list of static model equations using the write_latex_static_model command.

Auxiliary variables

The model which is solved internally by Dynare is not exactly the model declared by the user. In some cases, Dynare will introduce auxiliary endogenous variables—along with corresponding auxiliary equations—which will appear in the final output.

The main transformation concerns leads and lags. Dynare will perform a transformation of the model so that there is only one lead and one lag on endogenous variables and no leads/lags on exogenous variables.

This transformation is achieved by the creation of auxiliary variables and corresponding equations. For example, if x(+2) exists in the model, Dynare will create one auxiliary variable AUX_ENDO_LEAD = x(+1), and replace x(+2) by AUX_ENDO_LEAD(+1).

A similar transformation is done for lags greater than 2 on endogenous (auxiliary variables will have a name beginning with AUX_ENDO_LAG), and for exogenous with leads and lags (auxiliary variables will have a name beginning with AUX_EXO_LEAD or AUX_EXO_LAG respectively).

Another transformation is done for the EXPECTATION operator. For each occurrence of this operator, Dynare creates an auxiliary variable defined by a new equation, and replaces the expectation operator by a reference to the new auxiliary variable. For example, the expression EXPECTATION(-1)(x(+1)) is replaced by AUX_EXPECT_LAG_1(-1), and the new auxiliary variable is declared as AUX_EXPECT_LAG_1 = x(+2).

Auxiliary variables are also introduced by the preprocessor for the ramsey_model and ramsey_policy commands. In this case, they are used to represent the Lagrange multipliers when first order conditions of the Ramsey problem are computed. The new variables take the form MULT_i, where i represents the constraint with which the multiplier is associated (counted from the order of declaration in the model block).

Auxiliary variables are also introduced by the differentiate_forward_vars option of the model block. The new variables take the form AUX_DIFF_FWRD_i, and are equal to x-x(-1) for some endogenous variable x.

Finally, auxiliary variables will arise in the context of employing the diff operator.

Once created, all auxiliary variables are included in the set of endogenous variables. The output of decision rules (see below) is such that auxiliary variable names are replaced by the original variables they refer to.

The number of endogenous variables before the creation of auxiliary variables is stored in M_.orig_endo_nbr, and the number of endogenous variables after the creation of auxiliary variables is stored in M_.endo_nbr.

See https://git.dynare.org/Dynare/dynare/-/wikis/Auxiliary-variables for more technical details on auxiliary variables.

Initial and terminal conditions

For most simulation exercises, it is necessary to provide initial (and possibly terminal) conditions. It is also necessary to provide initial guess values for non-linear solvers. This section describes the statements used for those purposes.

In many contexts (deterministic or stochastic), it is necessary to compute the steady state of a non-linear model: initval then specifies numerical initial values for the non-linear solver. The command resid can be used to compute the equation residuals for the given initial values.

Used in perfect foresight mode, the types of forward-looking models for which Dynare was designed require both initial and terminal conditions. Most often these initial and terminal conditions are static equilibria, but not necessarily.

One typical application is to consider an economy at the equilibrium at time 0, trigger a shock in first period, and study the trajectory of return to the initial equilibrium. To do that, one needs initval and shocks (see :ref:`shocks-exo`).

Another one is to study how an economy, starting from arbitrary initial conditions at time 0 converges towards equilibrium. In this case models, the command histval permits to specify different historical initial values for variables with lags for the periods before the beginning of the simulation. Due to the design of Dynare, in this case initval is used to specify the terminal conditions.

Shocks on exogenous variables

In a deterministic context, when one wants to study the transition of one equilibrium position to another, it is equivalent to analyze the consequences of a permanent shock and this in done in Dynare through the proper use of initval and endval.

Another typical experiment is to study the effects of a temporary shock after which the system goes back to the original equilibrium (if the model is stable...). A temporary shock is a temporary change of value of one or several exogenous variables in the model. Temporary shocks are specified with the command shocks.

In a stochastic framework, the exogenous variables take random values in each period. In Dynare, these random values follow a normal distribution with zero mean, but it belongs to the user to specify the variability of these shocks. The non-zero elements of the matrix of variance-covariance of the shocks can be entered with the shocks command.

If the variance of an exogenous variable is set to zero, this variable will appear in the report on policy and transition functions, but isn’t used in the computation of moments and of Impulse Response Functions. Setting a variance to zero is an easy way of removing an exogenous shock.

Note that, by default, if there are several shocks or mshocks blocks in the same .mod file, then they are cumulative: all the shocks declared in all the blocks are considered; however, if a shocks or mshocks block is declared with the overwrite option, then it replaces all the previous shocks and mshocks blocks.

Other general declarations

Steady state

There are two ways of computing the steady state (i.e. the static equilibrium) of a model. The first way is to let Dynare compute the steady state using a nonlinear Newton-type solver; this should work for most models, and is relatively simple to use. The second way is to give more guidance to Dynare, using your knowledge of the model, by providing it with a method to compute the steady state, either using a steady_state_model block or writing matlab routine.

Finding the steady state with Dynare nonlinear solver

After computation, the steady state is available in the following variable:

Providing the steady state to Dynare

If you know how to compute the steady state for your model, you can provide a MATLAB/Octave function doing the computation instead of using steady. Again, there are two options for doing that:

• The easiest way is to write a steady_state_model block, which is described below in more details. See also fs2000.mod in the examples directory for an example. The steady state file generated by Dynare will be called +FILENAME/steadystate.m.
• You can write the corresponding MATLAB function by hand. If your .mod file is called FILENAME.mod, the steady state file must be called FILENAME_steadystate.m. See NK_baseline_steadystate.m in the examples directory for an example. This option gives a bit more flexibility (loops and conditional structures can be used), at the expense of a heavier programming burden and a lesser efficiency.

Note that both files allow to update parameters in each call of the function. This allows for example to calibrate a model to a labor supply of 0.2 in steady state by setting the labor disutility parameter to a corresponding value (see NK_baseline_steadystate.m in the examples directory). They can also be used in estimation where some parameter may be a function of an estimated parameter and needs to be updated for every parameter draw. For example, one might want to set the capital utilization cost parameter as a function of the discount rate to ensure that capacity utilization is 1 in steady state. Treating both parameters as independent or not updating one as a function of the other would lead to wrong results. But this also means that care is required. Do not accidentally overwrite your parameters with new values as it will lead to wrong results.

Replace some equations during steady state computations

When there is no steady state file, Dynare computes the steady state by solving the static model, i.e. the model from the .mod file from which leads and lags have been removed.

In some specific cases, one may want to have more control over the way this static model is created. Dynare therefore offers the possibility to explicitly give the form of equations that should be in the static model.

More precisely, if an equation is prepended by a [static] tag, then it will appear in the static model used for steady state computation, but that equation will not be used for other computations. For every equation tagged in this way, you must tag another equation with [dynamic]: that equation will not be used for steady state computation, but will be used for other computations.

This functionality can be useful on models with a unit root, where there is an infinity of steady states. An equation (tagged [dynamic]) would give the law of motion of the nonstationary variable (like a random walk). To pin down one specific steady state, an equation tagged [static] would affect a constant value to the nonstationary variable. Another situation where the [static] tag can be useful is when one has only a partial closed form solution for the steady state.

Example

This is a trivial example with two endogenous variables. The second equation takes a different form in the static model:

var c k;
varexo x;
...
model;
c + k - aa*x*k(-1)^alph - (1-delt)*k(-1);
[dynamic] c^(-gam) - (1+bet)^(-1)*(aa*alph*x(+1)*k^(alph-1) + 1 - delt)*c(+1)^(-gam);
[static] k = ((delt+bet)/(x*aa*alph))^(1/(alph-1));
end;

Getting information about the model

Deterministic simulation

Perfect foresight

When the framework is deterministic, Dynare can be used for models with the assumption of perfect foresight. Typically, the system is supposed to be in a state of equilibrium before a period 1 when the news of a contemporaneous or of a future shock is learned by the agents in the model. The purpose of the simulation is to describe the reaction in anticipation of, then in reaction to the shock, until the system returns to the old or to a new state of equilibrium. In most models, this return to equilibrium is only an asymptotic phenomenon, which one must approximate by an horizon of simulation far enough in the future. Another exercise for which Dynare is well suited is to study the transition path to a new equilibrium following a permanent shock. For deterministic simulations, the numerical problem consists of solving a nonlinear system of simultaneous equations in n endogenous variables in T periods. Dynare offers several algorithms for solving this problem, which can be chosen via the stack_solve_algo option. By default (stack_solve_algo=0), Dynare uses a Newton-type method to solve the simultaneous equation system. Because the resulting Jacobian is in the order of n by T and hence will be very large for long simulations with many variables, Dynare makes use of the sparse matrix capacities of MATLAB/Octave. A slower but potentially less memory consuming alternative (stack_solve_algo=1) is based on a Newton-type algorithm first proposed by Laffargue (1990) and Boucekkine (1995), which avoids ever storing the full Jacobian. The details of the algorithm can be found in Juillard (1996). The third type of algorithms makes use of block decomposition techniques (divide-and-conquer methods) that exploit the structure of the model. The principle is to identify recursive and simultaneous blocks in the model structure and use this information to aid the solution process. These solution algorithms can provide a significant speed-up on large models.

Warning

Be careful when employing auxiliary variables in the context of perfect foresight computations. The same model may work for stochastic simulations, but fail for perfect foresight simulations. The issue arises when an equation suddenly only contains variables dated t+1 (or t-1 for that matter). In this case, the derivative in the last (first) period with respect to all variables will be 0, rendering the stacked Jacobian singular.

Example

Consider the following specification of an Euler equation with log utility:

Lambda = beta*C(-1)/C;
Lambda(+1)*R(+1)= 1;

Clearly, the derivative of the second equation with respect to all endogenous variables at time t is zero, causing perfect_foresight_solver to generally fail. This is due to the use of the Lagrange multiplier Lambda as an auxiliary variable. Instead, employing the identical

beta*C/C(+1)*R(+1)= 1;

will work.

Perfect foresight with expectation errors

The solution under perfect foresight that was presented in the previous section makes the assumption that agents learn the complete path of future shocks in period 1, without making any expectation errors.

One may however want to study a scenario where it turns out that agents make expectation errors, in the sense that the path they had anticipated in period 1 does not realize exactly. More precisely, in some simulation periods, they may receive new information that makes them revise their anticipation for the path of future shocks. Also, under this scenario, it is assumed that agents behave as under perfect foresight, i.e. they take their decisions as if there was no uncertainty and they knew exactly the path of future shocks; the new information that they may receive comes as a total surprise to them.

Such a scenario can be solved by Dynare using the perfect_foresight_with_expectation_errors_setup and perfect_foresight_with_expectation_errors_solver commands, alongside shocks and endval blocks which are given a special learnt_in option.

Controlling the path of endogenous variables

In the usual perfect foresight problem, the user controls the path of exogenous variables for the simulation periods and the initial and terminal conditions for endogenous variables, while Dynare solves for the path of endogenous variables for the simulation periods.

However, Dynare offers the possibility of controlling the value of some endogenous variables for some simulation periods (in which case some exogenous variables must be left free and are thus solved for by Dynare, to avoid over-determination of the problem). This exercise is called “conditional forecasting” in some contexts (even though one may argue that this is not really forecasting, since perfect foresight by the agents is assumed; for the stochastic case, see the :comm:`conditional_forecast` command).

The description of controlled endogenous variables is done using the perfect_foresight_controlled_paths block. The information given therein is then processed by the :comm:`perfect_foresight_setup` (or :comm:`perfect_foresight_with_expectation_errors_setup`) command, so that the next :comm:`perfect_foresight_solver` (or :comm:`perfect_foresight_with_expectation_errors_solver`) command computes the simulation with controlled paths. In particular, :mvar:`oo_.exo_simul` will contain the computed value of exogenous variables that have been left free.

Stochastic solution and simulation

In a stochastic context, Dynare computes one or several simulations corresponding to a random draw of the shocks.

The main algorithm for solving stochastic models relies on a Taylor approximation, up to third order, of the expectation functions (see Judd (1996), Collard and Juillard (2001a, 2001b), and Schmitt-Grohé and Uríbe (2004)). The details of the Dynare implementation of the first order solution are given in Villemot (2011). Such a solution is computed using the stoch_simul command.

As an alternative, it is possible to compute a simulation to a stochastic model using the extended path method presented by Fair and Taylor (1983). This method is especially useful when there are strong nonlinearities or binding constraints. Such a solution is computed using the extended_path command.

Computing the stochastic solution

The approximated solution of a model takes the form of a set of decision rules or transition equations expressing the current value of the endogenous variables of the model as function of the previous state of the model and shocks observed at the beginning of the period. The decision rules are stored in the structure oo_.dr which is described below.

Typology and ordering of variables

Dynare distinguishes four types of endogenous variables:

Purely backward (or purely predetermined) variables

Those that appear only at current and past period in the model, but not at future period (i.e. at t and t-1 but not t+1). The number of such variables is equal to M_.npred.

Purely forward variables

Those that appear only at current and future period in the model, but not at past period (i.e. at t and t+1 but not t-1). The number of such variables is stored in M_.nfwrd.

Mixed variables

Those that appear at current, past and future period in the model (i.e. at t, t+1 and t-1). The number of such variables is stored in M_.nboth.

Static variables

Those that appear only at current, not past and future period in the model (i.e. only at t, not at t+1 or t-1). The number of such variables is stored in M_.nstatic.