running-dynare.rst

Running Dynare

In order to give instructions to Dynare, the user has to write a model file whose filename extension must be .mod or .dyn. This file contains the description of the model and the computing tasks required by the user. Its contents are described in :ref:`model-file`.

Dynare invocation

Once the model file is written, Dynare is invoked using the dynare command at the MATLAB or Octave prompt (with the filename of the .mod given as argument).

In practice, the handling of the model file is done in two steps: in the first one, the model and the processing instructions written by the user in a model file are interpreted and the proper MATLAB or Octave instructions are generated; in the second step, the program actually runs the computations. Both steps are triggered automatically by the dynare command.

This command launches Dynare and executes the instructions included in FILENAME.mod. This user-supplied file contains the model and the processing instructions, as described in :ref:`model-file`. The options, listed below, can be passed on the command line, following the name of the .mod file or in the first line of the .mod file itself (see below).

dynare begins by launching the preprocessor on the .mod file. By default (unless the :opt:`use_dll` option has been given to model), the preprocessor creates three intermediary files:

• +FILENAME/driver.m

  Contains variable declarations, and computing tasks.

• +FILENAME/dynamic.m

  Contains the dynamic model equations. Note that Dynare might introduce auxiliary equations and variables (see :ref:`aux-variables`). Outputs are the residuals of the dynamic model equations in the order the equations were declared and the Jacobian of the dynamic model equations. For higher order approximations also the Hessian and the third-order derivatives are provided. When computing the Jacobian of the dynamic model, the order of the endogenous variables in the columns is stored in M_.lead_lag_incidence. The rows of this matrix represent time periods: the first row denotes a lagged (time t-1) variable, the second row a contemporaneous (time t) variable, and the third row a leaded (time t+1) variable. The columns of the matrix represent the endogenous variables in their order of declaration. A zero in the matrix means that this endogenous does not appear in the model in this time period. The value in the M_.lead_lag_incidence matrix corresponds to the column of that variable in the Jacobian of the dynamic model. Example: Let the second declared variable be c and the (3,2) entry of M_.lead_lag_incidence be 15. Then the 15th column of the Jacobian is the derivative with respect to c(+1).

• +FILENAME/static.m

  Contains the long run static model equations. Note that Dynare might introduce auxiliary equations and variables (see :ref:`aux-variables`). Outputs are the residuals of the static model equations in the order the equations were declared and the Jacobian of the static equations. Entry (i,j) of the Jacobian represents the derivative of the ith static model equation with respect to the jth model variable in declaration order.

These files may be looked at to understand errors reported at the simulation stage.

dynare will then run the computing tasks by executing +FILENAME/driver.m. If a user needs to rerun the computing tasks without calling the preprocessor (or without calling the :mcomm:`dynare` command), for instance because he has modified the script, he just have to type the following on the command line:

>> FILENAME.driver

A few words of warning are warranted here: under Octave the filename of the .mod file should be chosen in such a way that the generated .m files described above do not conflict with .m files provided by Octave or by Dynare. Not respecting this rule could cause crashes or unexpected behaviour. In particular, it means that the .mod file cannot be given the name of an Octave or Dynare command. For instance, under Octave, it also means that the .mod file cannot be named test.mod or example.mod.

Note

Note on Quotes

When passing command line options that contains a space (or, under Octave, a double quote), you must surround the entire option (keyword and argument) with single quotes, as in the following example.

Example

Call Dynare with options containing spaces

>> dynare <<modfile.mod>> '-DA=[ i in [1,2,3] when i > 1 ]' 'conffile=C:\User\My Documents\config.txt'

Options

These options can be passed to the preprocessor by listing them after the name of the .mod file. They can alternatively be defined in the first line of the .mod file, this avoids typing them on the command line each time a .mod file is to be run. This line must be a Dynare one-line comment (i.e. must begin with //) and the options must be whitespace separated between --+ options: and +--. Note that any text after the +-- will be discarded. As in the command line, if an option admits a value the equal symbol must not be surrounded by spaces. For instance json = compute is not correct, and should be written json=compute. The nopathchange option cannot be specified in this way, it must be passed on the command-line.

Output

Depending on the computing tasks requested in the .mod file, executing the dynare command will leave variables containing results in the workspace available for further processing. More details are given under the relevant computing tasks. The M_,``oo_``, and options_ structures are saved in a file called FILENAME_results.mat. If they exist, estim_params_, bayestopt_, dataset_, oo_recursive_ and estimation_info are saved in the same file. Note that Matlab by default only allows .mat-files up to 2GB. You can lift this restriction by enabling the save -v7.3-option in Preferences -> General -> MAT-Files.

Example

Call dynare from the MATLAB or Octave prompt, without or with options:

>> dynare ramst
>> dynare ramst.mod savemacro

Alternatively the options can be passed in the first line of ramst.mod:

// --+ options: savemacro, json=compute +--

and then dynare called without passing options on the command line:

>> dynare ramst

Dynare hooks

It is possible to call pre and post Dynare preprocessor hooks written as MATLAB scripts. The script MODFILENAME/hooks/priorprocessing.m is executed before the call to Dynare’s preprocessor, and can be used to programmatically transform the mod file that will be read by the preprocessor. The script MODFILENAME/hooks/postprocessing.m is gexecuted just after the call to Dynare’s preprocessor, and can be used to programmatically transform the files generated by Dynare’s preprocessor before actual computations start. The pre and/or post dynare preprocessor hooks are executed if and only if the aforementioned scripts are detected in the same folder as the the model file, FILENAME.mod.

Understanding Preprocessor Error Messages

If the preprocessor runs into an error while processing your .mod file, it will issue an error. Due to the way that a parser works, sometimes these errors can be misleading. Here, we aim to demystify these error messages.

The preprocessor issues error messages of the form:

1. ERROR: <<file.mod>>: line A, col B: <<error message>>
2. ERROR: <<file.mod>>: line A, cols B-C: <<error message>>
3. ERROR: <<file.mod>>: line A, col B - line C, col D: <<error message>>

The first two errors occur on a single line, with error two spanning multiple columns. Error three spans multiple rows.

Often, the line and column numbers are precise, leading you directly to the offending syntax. Infrequently however, because of the way the parser works, this is not the case. The most common example of misleading line and column numbers (and error message for that matter) is the case of a missing semicolon, as seen in the following example:

varexo a, b
parameters c, ...;

In this case, the parser doesn’t know a semicolon is missing at the end of the varexo command until it begins parsing the second line and bumps into the parameters command. This is because we allow commands to span multiple lines and, hence, the parser cannot know that the second line will not have a semicolon on it until it gets there. Once the parser begins parsing the second line, it realizes that it has encountered a keyword, parameters, which it did not expect. Hence, it throws an error of the form: ERROR: <<file.mod>>: line 2, cols 0-9: syntax error, unexpected PARAMETERS. In this case, you would simply place a semicolon at the end of line one and the parser would continue processing.

It is also helpful to keep in mind that any piece of code that does not violate Dynare syntax, but at the same time is not recognized by the parser, is interpreted as native MATLAB code. This code will be directly passed to the driver script. Investigating driver.m file then helps with debugging. Such problems most often occur when defined variable or parameter names have been misspelled so that Dynare's parser is unable to recognize them.