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]

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;

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 Sigma_e to name your variable. Not conforming to this rule might yield hard-to-debug error messages or crashes. Second, to minimize interference with MATLAB or Octave functions that may be called by Dynare or user-defined steady state files, it is recommended to avoid using the name of MATLAB functions. In particular when working with 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 or directly in an equation.

To declare a variable on-the-fly in an equation tag, simply state the type of variable to be declared (endogenous, exogenous, or parameter 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, an x, or a p. 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.