dynare.texi 538 KB
Newer Older
1 2 3 4
\input texinfo
@c %**start of header
@setfilename dynare.info
@documentencoding UTF-8
5
@set txicodequoteundirected
6

7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
@settitle Dynare Reference Manual
@afourwide
@dircategory Math
@direntry
* Dynare: (dynare).             A platform for handling a wide class
                                  of economic models.
@end direntry

@include version.texi

@c Define some macros

@macro descriptionhead
@ifnothtml
@sp 1
@end ifnothtml
@emph{Description}
@end macro

@macro optionshead
@iftex
@sp 1
@end iftex
@emph{Options}
@end macro

33 34 35 36 37 38 39
@macro flagshead
@iftex
@sp 1
@end iftex
@emph{Flags}
@end macro

40 41 42 43 44 45 46
@macro examplehead
@iftex
@sp 1
@end iftex
@emph{Example}
@end macro

47 48 49 50 51 52 53
@macro exampleshead
@iftex
@sp 1
@end iftex
@emph{Examples}
@end macro

54 55 56 57 58 59 60
@macro remarkhead
@iftex
@sp 1
@end iftex
@noindent @emph{Remark}
@end macro

61 62 63 64 65 66 67
@macro outputhead
@iftex
@sp 1
@end iftex
@emph{Output}
@end macro

68 69 70 71 72 73 74
@macro algorithmhead
@iftex
@sp 1
@end iftex
@emph{Algorithm}
@end macro

75 76 77 78 79 80 81
@macro algorithmshead
@iftex
@sp 1
@end iftex
@emph{Algorithms}
@end macro

82 83 84 85 86 87 88
@macro customhead{title}
@iftex
@sp 1
@end iftex
@emph{\title\}
@end macro

89 90 91 92
@macro dates
@code{dates }
@end macro

93 94 95 96
@macro dseries
@code{dseries }
@end macro

97 98 99
@c %**end of header

@copying
Houtan Bastani's avatar
Houtan Bastani committed
100
Copyright @copyright{} 1996-2018, Dynare Team.
101 102 103 104 105 106 107 108 109 110 111 112 113 114

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

A copy of the license can be found at @uref{http://www.gnu.org/licenses/fdl.txt}.
@end quotation
@end copying

@titlepage
@title Dynare
@subtitle Reference Manual, version @value{VERSION}
115
@author Stéphane Adjemian
116 117
@author Houtan Bastani
@author Michel Juillard
118
@author Frédéric Karamé
119 120 121
@author Junior Maih
@author Ferhat Mihoubi
@author George Perendia
122
@author Johannes Pfeifer
123
@author Marco Ratto
124
@author Sébastien Villemot
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Dynare
This is Dynare Reference Manual, version @value{VERSION}.

@insertcopying
@end ifnottex

@menu
141 142 143 144 145 146 147 148
* Introduction::
* Installation and configuration::
* Running Dynare::
* The Model file::
* The Configuration File::
* Time Series::
* Reporting::
* Examples::
149
* Dynare misc commands::
150 151 152
* Bibliography::
* Command and Function Index::
* Variable Index::
153 154 155 156 157 158

@detailmenu
 --- The Detailed Node Listing ---

Introduction

159 160 161
* What is Dynare ?::
* Documentation sources::
* Citing Dynare in your research::
162 163 164

Installation and configuration

165 166
* Software requirements::
* Installation of Dynare::
167
* Compiler installation::
168
* Configuration::
169 170 171

Installation of Dynare

172 173
* On Windows::
* On Debian GNU/Linux and Ubuntu::
Houtan Bastani's avatar
Houtan Bastani committed
174
* On macOS::
175
* For other systems::
176

177 178 179 180
Compiler installation

* Prerequisites on Windows::
* Prerequisites on Debian GNU/Linux and Ubuntu::
Houtan Bastani's avatar
Houtan Bastani committed
181
* Prerequisites on macOS::
182

183 184
Configuration

185 186 187
* For MATLAB::
* For GNU Octave::
* Some words of warning::
188

189 190
Running Dynare

191 192 193
* Dynare invocation::
* Dynare hooks::
* Understanding Preprocessor Error Messages::
194
* Invoking the Dynare Preprocessor from the GNU/Linux or macOS Command Line::
195

196 197
The Model file

198 199 200 201 202 203 204 205 206 207 208 209 210 211
* Conventions::
* Variable declarations::
* Expressions::
* Parameter initialization::
* Model declaration::
* Auxiliary variables::
* Initial and terminal conditions::
* Shocks on exogenous variables::
* Other general declarations::
* Steady state::
* Getting information about the model::
* Deterministic simulation::
* Stochastic solution and simulation::
* Estimation::
212 213 214
* Model Comparison::
* Shock Decomposition::
* Calibrated Smoother::
215 216 217 218 219 220
* Forecasting::
* Optimal policy::
* Sensitivity and identification analysis::
* Markov-switching SBVAR::
* Displaying and saving results::
* Macro-processing language::
221
* Verbatim inclusion::
222
* Misc commands::
223

224 225 226 227
Variable declarations

* On-the-fly Model Variable Declaration::

228 229
Expressions

230 231 232 233
* Parameters and variables::
* Operators::
* Functions::
* A few words of warning in stochastic context::
234 235 236

Parameters and variables

237 238
* Inside the model::
* Outside the model::
239 240 241

Functions

242 243
* Built-in Functions::
* External Functions::
244 245 246

Steady state

247 248 249
* Finding the steady state with Dynare nonlinear solver::
* Using a steady state file::
* Replace some equations during steady state computations::
250 251 252

Stochastic solution and simulation

253 254 255 256 257
* Computing the stochastic solution::
* Typology and ordering of variables::
* First order approximation::
* Second order approximation::
* Third order approximation::
258

259 260
Sensitivity and identification analysis

261
* Performing sensitivity analysis::
262
* IRF/Moment calibration::
263
* Performing identification analysis::
264 265 266
* Types of analysis and output files::

Types of analysis and output files
267

268 269
* Sampling::
* Stability Mapping::
270
* IRF/Moment restrictions::
271 272 273 274
* Reduced Form Mapping::
* RMSE::
* Screening Analysis::
* Identification Analysis::
275

276 277
Macro-processing language

278 279 280 281
* Macro expressions::
* Macro directives::
* Typical usages::
* MATLAB/Octave loops versus macro-processor loops::
282 283 284

Typical usages

285 286 287 288
* Modularization::
* Indexed sums or products::
* Multi-country models::
* Endogeneizing parameters::
289

290 291
The Configuration File

292 293
* Dynare Configuration::
* Parallel Configuration::
294
* Windows Step-by-Step Guide::
295 296 297 298 299 300 301 302 303 304

Time Series

* Dates::
* dseries class::

Dates

* dates in a mod file::
* dates class::
305 306 307 308 309 310 311 312

@end detailmenu
@end menu

@node Introduction
@chapter Introduction

@menu
313 314 315
* What is Dynare ?::
* Documentation sources::
* Citing Dynare in your research::
316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357
@end menu

@node What is Dynare ?
@section What is Dynare ?

Dynare is a software platform for handling a wide class of economic
models, in particular dynamic stochastic general equilibrium (DSGE)
and overlapping generations (OLG) models. The models solved by Dynare
include those relying on the @i{rational expectations} hypothesis, wherein
agents form their expectations about the future in a way consistent
with the model. But Dynare is also able to handle models where
expectations are formed differently: on one extreme, models where
agents perfectly anticipate the future; on the other extreme, models
where agents have limited rationality or imperfect knowledge of the
state of the economy and, hence, form their expectations through a
learning process. In terms of types of agents, models solved by Dynare
can incorporate consumers, productive firms, governments, monetary
authorities, investors and financial intermediaries. Some degree of
heterogeneity can be achieved by including several distinct classes of
agents in each of the aforementioned agent categories.

Dynare offers a user-friendly and intuitive way of describing these
models. It is able to perform simulations of the model given a
calibration of the model parameters and is also able to estimate these
parameters given a dataset. In practice, the user will write a text
file containing the list of model variables, the dynamic equations
linking these variables together, the computing tasks to be performed
and the desired graphical or numerical outputs.

A large panel of applied mathematics and computer science techniques
are internally employed by Dynare: multivariate nonlinear solving and
optimization, matrix factorizations, local functional approximation,
Kalman filters and smoothers, MCMC techniques for Bayesian estimation,
graph algorithms, optimal control, @dots{}

Various public bodies (central banks, ministries of economy and
finance, international organisations) and some private financial
institutions use Dynare for performing policy analysis exercises and
as a support tool for forecasting exercises. In the academic world,
Dynare is used for research and teaching purposes in postgraduate
macroeconomics courses.

Houtan Bastani's avatar
Houtan Bastani committed
358 359 360 361 362 363
Dynare is a free software, which means that it can be downloaded free of
charge, that its source code is freely available, and that it can be used for
both non-profit and for-profit purposes. Most of the source files are covered
by the GNU General Public Licence (GPL) version 3 or later (there are some
exceptions to this, see the file @file{license.txt} in Dynare distribution). It
is available for the Windows, macOS, and Linux platforms and is fully
364
documented in this reference manual. Part of Dynare is
Houtan Bastani's avatar
Houtan Bastani committed
365 366 367 368 369 370 371 372
programmed in C++, while the rest is written using the
@uref{http://www.mathworks.com/products/matlab/, MATLAB} programming language.
The latter implies that commercially-available MATLAB software is required in
order to run Dynare. However, as an alternative to MATLAB, Dynare is also able
to run on top of @uref{http://www.octave.org, GNU Octave} (basically a free
clone of MATLAB): this possibility is particularly interesting for students or
institutions who cannot afford, or do not want to pay for, MATLAB and are
willing to bear the concomitant performance loss.
373 374

The development of Dynare is mainly done at
375
@uref{http://www.cepremap.fr, Cepremap} by a core team of
376 377 378 379
researchers who devote part of their time to software development.
Currently the development team of Dynare is composed of Stéphane
Adjemian (Université du Maine, Gains and Cepremap), Houtan Bastani
(Cepremap), Michel Juillard (Banque de France), Frédéric Karamé
380
(Université du Maine, Gains and Cepremap), Junior Maih (Norges Bank),
Sébastien Villemot's avatar
Sébastien Villemot committed
381
Ferhat Mihoubi (Université Paris-Est Créteil, Epee and Cepremap), George
382
Perendia, Johannes Pfeifer (University of Cologne), Marco Ratto (European Commission, Joint Research Centre - JRC)
Sébastien Villemot's avatar
Sébastien Villemot committed
383
and Sébastien Villemot (Cepremap).
384 385 386 387 388 389 390 391
Increasingly, the developer base is expanding, as tools developed by
researchers outside of Cepremap are integrated into Dynare. Financial
support is provided by Cepremap, Banque de France and DSGE-net (an
international research network for DSGE modeling). The Dynare project
also received funding through the Seventh Framework Programme for
Research (FP7) of the European Commission's Socio-economic Sciences
and Humanities (SSH) Program from October 2008 to September 2011 under
grant agreement SSH-CT-2009-225149.
392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408

Interaction between developers and users of Dynare is central to the
project. A @uref{http://www.dynare.org/phpBB3, web forum} is available
for users who have questions about the usage of Dynare or who want to
report bugs. Training sessions are given through the Dynare Summer
School, which is organized every year and is attended by about 40
people. Finally, priorities in terms of future developments and
features to be added are decided in cooperation with the institutions
providing financial support.

@node Documentation sources
@section Documentation sources

The present document is the reference manual for Dynare. It documents
all commands and features in a systematic fashion.

Other useful sources of information include the
409 410 411 412
@uref{http://www.dynare.org/DynareWiki,old Dynare wiki}, the
@uref{https://github.com/DynareTeam/dynare/wiki,new Dynare wiki}, the documentation
section of the @uref{http://www.dynare.org/documentation-and-support,Dynare
website} and the @uref{https://forum.dynare.org/,Dynare forum}.
413

414 415 416
@node Citing Dynare in your research
@section Citing Dynare in your research

417 418
You should cite Dynare if you use it in your research. The recommended way to
do this is to cite the present manual as:
419 420

@quotation
421 422 423 424
Stéphane Adjemian, Houtan Bastani, Michel Juillard, Frédéric Karamé, Junior
Maih, Ferhat Mihoubi, George Perendia, Johannes Pfeifer, Marco Ratto and
Sébastien Villemot (2011), ``Dynare: Reference Manual, Version 4,'' @i{Dynare
Working Papers}, 1, CEPREMAP
425 426
@end quotation

427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442
@noindent For convenience, you can copy and paste the following into your BibTeX file:

@verbatim
@TechReport{Adjemianetal2011,
  author      = {Adjemian, St\'ephane and Bastani, Houtan and Juillard, Michel and
                 Karam\'e, Fr\'ederic and Maih, Junior and Mihoubi, Ferhat and
                 Perendia, George and Pfeifer, Johannes and Ratto, Marco and
                 Villemot, S\'ebastien},
  title       = {Dynare: Reference Manual Version 4},
  year        = {2011},
  institution = {CEPREMAP},
  type        = {Dynare Working Papers},
  number      = {1},
}
@end verbatim

443
@noindent If you want to give a URL, use the address of the Dynare website:
444 445
@uref{http://www.dynare.org}.

446 447 448 449
@node Installation and configuration
@chapter Installation and configuration

@menu
450 451
* Software requirements::
* Installation of Dynare::
452
* Compiler installation::
453
* Configuration::
454 455 456 457 458
@end menu

@node Software requirements
@section Software requirements

459
Packaged versions of Dynare are available for Windows XP/Vista/7/8/10,
460
@uref{http://www.debian.org,Debian GNU/Linux},
Houtan Bastani's avatar
Houtan Bastani committed
461
@uref{http://www.ubuntu.com/,Ubuntu} and macOS 10.8 or later.  Dynare should
462
work on other systems, but some compilation steps are necessary in that case.
463

464
In order to run Dynare, you need one of the following:
465

466
@itemize
467 468

@item
Houtan Bastani's avatar
Houtan Bastani committed
469
MATLAB version 7.5 (R2007b) or above (MATLAB R2009b 64-bit for macOS);
470 471

@item
472
GNU Octave version 4.2.1 or above.
473 474
@end itemize

Sébastien Villemot's avatar
Sébastien Villemot committed
475 476
Packages of GNU Octave can be downloaded on the
@uref{http://www.dynare.org/download/octave,Dynare website}.
477

478 479 480 481 482 483
The following optional extensions are also useful to benefit from extra
features, but are in no way required:

@itemize

@item
484 485
If under MATLAB: the optimization toolbox, the statistics toolbox, the
control system toolbox;
486 487 488 489

@item
If under GNU Octave, the following
@uref{http://octave.sourceforge.net/,Octave-Forge} packages: optim,
490
io, statistics, control.
491 492 493

@end itemize

494

495 496 497 498 499 500 501 502 503 504 505

@node Installation of Dynare
@section Installation of Dynare

After installation, Dynare can be used in any directory on your
computer. It is best practice to keep your model files in directories
different from the one containing the Dynare toolbox. That way you can
upgrade Dynare and discard the previous version without having to worry
about your own files.

@menu
506 507
* On Windows::
* On Debian GNU/Linux and Ubuntu::
Houtan Bastani's avatar
Houtan Bastani committed
508
* On macOS::
509
* For other systems::
510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535
@end menu

@node On Windows
@subsection On Windows

Execute the automated installer called @file{dynare-4.@var{x}.@var{y}-win.exe}
(where 4.@var{x}.@var{y} is the version number), and follow the instructions. The
default installation directory is @file{c:\dynare\4.@var{x}.@var{y}}.

After installation, this directory will contain several sub-directories,
among which are @file{matlab}, @file{mex} and @file{doc}.

The installer will also add an entry in your Start Menu with a shortcut
to the documentation files and uninstaller.

Note that you can have several versions of Dynare coexisting (for
example in @file{c:\dynare}), as long as you correctly adjust your path
settings (@pxref{Some words of warning}).

@node On Debian GNU/Linux and Ubuntu
@subsection On Debian GNU/Linux and Ubuntu

Please refer to the
@uref{http://www.dynare.org/DynareWiki/InstallOnDebianOrUbuntu,Dynare
Wiki} for detailed instructions.

536 537
Dynare will be installed under @file{/usr/lib/dynare}. Documentation will be
under @file{/usr/share/doc/dynare-doc}.
538

Houtan Bastani's avatar
Houtan Bastani committed
539 540
@node On macOS
@subsection On macOS
541

Houtan Bastani's avatar
Houtan Bastani committed
542 543 544 545
To install Dynare for use with Matlab, execute the automated installer called
@file{dynare-4.@var{x}.@var{y}.pkg} (where 4.@var{x}.@var{y} is the version
number), and follow the instructions. The default installation directory is
@file{/Applications/Dynare/4.@var{x}.@var{y}} (please refer to the
546
@uref{http://www.dynare.org/DynareWiki/InstallOnMacOSX,Dynare Wiki} for
Houtan Bastani's avatar
Houtan Bastani committed
547
detailed instructions).
548 549 550 551

After installation, this directory will contain several sub-directories,
among which are @file{matlab}, @file{mex} and @file{doc}.

Houtan Bastani's avatar
Houtan Bastani committed
552 553 554 555 556 557 558 559 560 561
Note that several versions of Dynare can coexist (by default in
@file{/Applications/Dynare}), as long as you correctly adjust your path
settings (@pxref{Some words of warning}).

To install Dynare for Octave, first install Homebrew following the instructions
on their site: @uref{https://brew.sh/}. Then install Octave, issuing the
command @code{brew install octave} at the Terminal prompt. You can then install
the latest stable version of Dynare by typing @code{brew install dynare} at the
Terminal prompt. You can also pass options to the installation command. These
options can be viewed by typing @code{brew info dynare} at the Terminal prompt.
562 563 564 565 566 567 568 569 570

@node For other systems
@subsection For other systems

You need to download Dynare source code from the
@uref{http://www.dynare.org,Dynare website} and unpack it somewhere.

Then you will need to recompile the pre-processor and the dynamic
loadable libraries. Please refer to
571
@uref{https://github.com/DynareTeam/dynare/blob/master/README.md,README.md}.
572

573 574 575 576 577 578 579 580 581 582 583 584 585 586 587
@node Compiler installation
@section Compiler installation

If you plan to use the @code{use_dll} option of the @code{model}
command, you will need to install the necessary requirements for
compiling MEX files on your machine. 

If you are using MATLAB, please check
@uref{http://www.mathworks.com/support/compilers} for supported compilers for
your MATLAB version on your operating system. After installing your compiler,
select it using @code{mex -setup} in Matlab and clicking on the required compiler.

Octave comes with built-in functionality for compiling mex-files.

@menu
588 589
* Prerequisites on Windows::
* Prerequisites on Debian GNU/Linux and Ubuntu::
Houtan Bastani's avatar
Houtan Bastani committed
590
* Prerequisites on macOS::
591 592
@end menu

593 594
@node Prerequisites on Windows
@subsection Prerequisites on Windows
595 596 597 598 599 600 601 602 603 604 605 606 607 608

If you are using MATLAB under Windows, install a C++ compiler on your machine and configure it with
MATLAB. There are at least two free compilers you can use. First, there is Microsoft's Visual Studio 
Community (@uref{https://www.visualstudio.com/}), which has the largest history of MATLAB support, but 
requires much space on the hard-disk. Second, since MATLAB R2015b, MATLAB supports the MinGW-w64 C/C++ 
Compiler from TDM-GCC. To install this compiler, use the Add-Ons menu of MATLAB. Search for MinGW or 
select it from Features. 

For older version of MATLAB, in particular before R2014a, it may sometimes make sense to use the gcc compiler 
provided by Cygwin. However, integrating it in MATLAB can be quite cumbersome and should be considered as a
legacy option. For details, see
@uref{http://www.dynare.org/DynareWiki/ConfigureMatlabWindowsForMexCompilation,instructions
on the Dynare wiki}. 

609 610
@node Prerequisites on Debian GNU/Linux and Ubuntu
@subsection Prerequisites on Debian GNU/Linux and Ubuntu
611 612 613 614 615 616 617

Users of MATLAB under Linux need to have a working compilation environment installed. If not already present,
it can be installed via @code{apt-get install build-essential}.

Users of Octave under Linux should install the package for MEX file compilation 
(under Debian or Ubuntu, it is called @file{liboctave-dev}).

Houtan Bastani's avatar
Houtan Bastani committed
618 619 620
@node Prerequisites on macOS
@subsection Prerequisites on macOS
If you are using MATLAB under macOS, you should install the latest
621 622 623 624 625
version of XCode: see
@uref{http://www.dynare.org/DynareWiki/InstallOnMacOSX,instructions on
the Dynare wiki}.


626 627 628 629
@node Configuration
@section Configuration

@menu
630 631 632
* For MATLAB::
* For GNU Octave::
* Some words of warning::
633 634 635 636 637 638 639 640
@end menu

@node For MATLAB
@subsection For MATLAB

You need to add the @file{matlab} subdirectory of your Dynare
installation to MATLAB path. You have two options for doing that:

641
@itemize
642 643 644 645 646 647 648 649 650 651 652 653 654 655 656

@item
Using the @code{addpath} command in the MATLAB command window:

Under Windows, assuming that you have installed Dynare in the standard
location, and replacing @code{4.@var{x}.@var{y}} with the correct
version number, type:

@example
addpath c:\dynare\4.@var{x}.@var{y}\matlab
@end example

Under Debian GNU/Linux or Ubuntu, type:

@example
657
addpath /usr/lib/dynare/matlab
658 659
@end example

Houtan Bastani's avatar
Houtan Bastani committed
660
Under macOS, assuming that you have installed Dynare in the standard
661 662 663 664
location, and replacing @code{4.@var{x}.@var{y}} with the correct version
number, type:

@example
Houtan Bastani's avatar
Houtan Bastani committed
665
addpath /Applications/Dynare/4.@var{x}.@var{y}/matlab
666 667 668 669 670 671 672 673 674
@end example

MATLAB will not remember this setting next time you run it, and you
will have to do it again.

@item
Via the menu entries:

Select the ``Set Path'' entry in the ``File'' menu, then click on
Houtan Bastani's avatar
Houtan Bastani committed
675
``Add Folder@dots{}'', and select the @file{matlab} subdirectory of `your
676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698
Dynare installation. Note that you @emph{should not} use ``Add with
Subfolders@dots{}''. Apply the settings by clicking on ``Save''. Note that
MATLAB will remember this setting next time you run it.
@end itemize

@node For GNU Octave
@subsection For GNU Octave

You need to add the @file{matlab} subdirectory of your Dynare
installation to Octave path, using the @code{addpath} at the Octave
command prompt.

Under Windows, assuming that you have installed Dynare in the standard
location, and replacing ``4.@var{x}.@var{y}'' with the correct version
number, type:

@example
addpath c:\dynare\4.@var{x}.@var{y}\matlab
@end example

Under Debian GNU/Linux or Ubuntu, there is no need to use the
@code{addpath} command; the packaging does it for you.

Houtan Bastani's avatar
Houtan Bastani committed
699
Under macOS, assuming that you have installed Dynare and Octave via Homebrew, type:
700 701

@example
Houtan Bastani's avatar
Houtan Bastani committed
702
addpath /usr/local/opt/dynare/lib/dynare/matlab
703 704 705 706
@end example

If you don't want to type this command every time you run Octave, you
can put it in a file called @file{.octaverc} in your home directory
Houtan Bastani's avatar
Houtan Bastani committed
707
(under Windows this will generally be @file{c:\Documents and
Houtan Bastani's avatar
Houtan Bastani committed
708
Settings\USERNAME\} while under macOS it is @file{/Users/USERNAME/}).
709
This file is run by Octave at every startup.
710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725

@node Some words of warning
@subsection Some words of warning

You should be very careful about the content of your MATLAB or Octave
path. You can display its content by simply typing @code{path} in the
command window.

The path should normally contain system directories of MATLAB or Octave,
and some subdirectories of your Dynare installation. You have to
manually add the @file{matlab} subdirectory, and Dynare will
automatically add a few other subdirectories at runtime (depending on
your configuration). You must verify that there is no directory coming
from another version of Dynare than the one you are planning to use.

You have to be aware that adding other directories to your path can
Houtan Bastani's avatar
Houtan Bastani committed
726 727
potentially create problems if any of your M-files have the same name
as a Dynare file. Your file would then override the Dynare file, making
728 729
Dynare unusable.

730 731
@node Running Dynare
@chapter Running Dynare
732 733 734 735

In order to give instructions to Dynare, the user has to write a
@emph{model file} whose filename extension must be @file{.mod}. This
file contains the description of the model and the computing tasks
736
required by the user. Its contents are described in @ref{The Model file}.
737

738
@menu
739 740 741
* Dynare invocation::
* Dynare hooks::
* Understanding Preprocessor Error Messages::
742
* Invoking the Dynare Preprocessor from the GNU/Linux or macOS Command Line::
743 744 745 746 747
@end menu

@node Dynare invocation
@section Dynare invocation

748 749 750 751 752 753 754 755
Once the model file is written, Dynare is invoked using the
@code{dynare} command at the MATLAB or Octave prompt (with the filename
of the @file{.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 @emph{model file} are interpreted and the proper MATLAB or GNU
Octave instructions are generated; in the second step, the program
756
actually runs the computations. Both steps are triggered automatically
757 758 759 760 761 762 763
by the @code{dynare} command.

@deffn {MATLAB/Octave command} dynare @var{FILENAME}[.mod] [@var{OPTIONS}@dots{}]

@descriptionhead

This command launches Dynare and executes the instructions included in
764 765 766 767
@file{@var{FILENAME}.mod}.  This user-supplied file contains the model and the
processing instructions, as described in @ref{The Model file}. The options,
listed below, can be passed on the command line, following the name of the
@file{.mod} file or in the first line of the @file{.mod} file itself (see below).
768 769 770 771 772 773 774

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

@table @file

775
@item +@var{FILENAME}/driver.m
776 777
Contains variable declarations, and computing tasks

778
@item +@var{FILENAME}/dynamic.m
Johannes Pfeifer's avatar
Johannes Pfeifer committed
779
@vindex M_.lead_lag_incidence
Houtan Bastani's avatar
Houtan Bastani committed
780
Contains the dynamic model equations. Note that Dynare might introduce auxiliary equations and variables (@pxref{Auxiliary 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 @code{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 @code{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 @code{c} and the @code{(3,2)} entry of @code{M_.lead_lag_incidence} be @code{15}. Then the @code{15}th column of the Jacobian is the derivative with respect to @code{c(+1)}.
781

782
@item +@var{FILENAME}/static.m
783
Contains the long run static model equations. Note that Dynare might introduce auxiliary equations and variables (@pxref{Auxiliary 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 @code{(i,j)} of the Jacobian represents the derivative of the @code{i}th static model equation with respect to the @code{j}th model variable in declaration order.
784 785 786 787 788
@end table

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

789
@code{dynare} will then run the computing tasks by executing @file{+@var{FILENAME}/driver.m}.
790

791 792 793 794 795 796
@optionshead

@table @code

@item noclearall
By default, @code{dynare} will issue a @code{clear all} command to
797 798 799 800 801 802 803
MATLAB (<R2015b) or Octave, thereby deleting all workspace variables and
functions; this option instructs @code{dynare} not to clear the
workspace. Note that starting with Matlab 2015b @code{dynare} only
deletes the global variables and the functions using persistent
variables, in order to benefit from the JIT (Just In Time)
compilation. In this case the option instructs @code{dynare} not to
clear the globals and functions.
804

805 806
@item onlyclearglobals
By default, @code{dynare} will issue a @code{clear all} command to
807
MATLAB versions before 2015b and to Octave, thereby deleting all workspace variables; this
808 809 810 811 812
option instructs @code{dynare} to clear only the global variables
(@i{i.e.} @code{M_}, @code{options_}, @code{oo_},
@code{estim_params_}, @code{bayestopt_}, and @code{dataset_}), leaving
the other variables in the workspace.

813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835
@item debug
Instructs the preprocessor to write some debugging information about the
scanning and parsing of the @file{.mod} file

@item notmpterms
Instructs the preprocessor to omit temporary terms in the static and
dynamic files; this generally decreases performance, but is used for
debugging purposes since it makes the static and dynamic files more
readable

@item savemacro[=@var{FILENAME}]
Instructs @code{dynare} to save the intermediary file which is obtained
after macro-processing (@pxref{Macro-processing language}); the saved
output will go in the file specified, or if no file is specified in
@file{@var{FILENAME}-macroexp.mod}

@item onlymacro
Instructs the preprocessor to only perform the macro-processing step,
and stop just after. Mainly useful for debugging purposes or for using
the macro-processor independently of the rest of Dynare toolbox.

@item nolinemacro
Instructs the macro-preprocessor to omit line numbering information in
836
the intermediary @file{.mod} file created after the macro-processing
837 838 839 840
step. Useful in conjunction with @code{savemacro} when one wants that to
reuse the intermediary @file{.mod} file, without having it cluttered by
line numbering directives.

841 842 843 844
@item noemptylinemacro
Passing this option removes all empty from the macro expanded mod file created
when the @code{savemacro} option is used.

845 846 847 848
@item nolog
Instructs Dynare to no create a logfile of this run in
@file{@var{FILENAME}.log}. The default is to create the logfile.

849 850 851 852 853 854
@item params_derivs_order=0|1|2
When @ref{identification}, @ref{dynare_sensitivity} (with identification), or
@ref{estimation_cmd} are present, this option is used to limit the order of the
derivatives with respect to the parameters that are calculated by the
preprocessor. @code{0} means no derivatives, @code{1} means first derivatives,
and @code{2} means second derivatives. Default: @code{2}
855

856 857 858
@item nowarn
Suppresses all warnings.

859 860 861
@anchor{json}
@item json=parse|transform|compute
Causes the preprocessor to output a version of the @file{.mod} file in JSON
862
format. If @code{parse} is passed, the output will be written after the parsing
863
of the @file{.mod} file to a file called @file{@var{FILENAME}/model/json/modfile.json}. If
864 865
@code{transform} is passed, the JSON output of the transformed model (maximum
lead of 1, minimum lag of -1, expectation operators substituted, etc.) will be
866 867
written to a file called @file{@var{FILENAME}/model/json/modfile.json} and the original,
untransformed model will be written in @file{@var{FILENAME}/model/json/modfile-original.json}. And
868
if @code{compute} is passed, the output is written after the computing pass. In
869 870 871 872
this case, the transformed model is written to @file{@var{FILENAME}/model/json/modfile.json}, the
original model is written to @file{@var{FILENAME}/model/json/model-original.json}, and the
dynamic and static files are written to @file{@var{FILENAME}/model/json/dynamic.json} and
@file{@var{FILENAME}/model/json/static.json}.
873 874 875 876 877 878 879 880

@item jsonstdout
Instead of writing output requested by @ref{json} to files, write to standard
out.

@item onlyjson
Quit processing once the output requested by @ref{json} has been written.

881
@item jsonderivsimple
882
Print a simplified version (excluding variable name(s) and lag information) of the
883 884
static and dynamic files in @file{@var{FILENAME}/model/json/static.json} and
@file{@var{FILENAME}/model/json/dynamic.json}.
885

886 887 888 889 890 891 892 893 894
@item warn_uninit
Display a warning for each variable or parameter which is not
initialized. @xref{Parameter initialization}, or
@ref{load_params_and_steady_state} for initialization of parameters.
@xref{Initial and terminal conditions}, or
@ref{load_params_and_steady_state} for initialization of endogenous
and exogenous variables.

@item console
895 896 897
Activate console mode. In addition to the behavior of
@code{nodisplay}, Dynare will not use graphical waitbars for long
computations.
898

899
@item nograph
900
Activate the @code{nograph} option (@pxref{nograph}), so that Dynare will not produce any
901 902
graph

903
@item nointeractive
Johannes Pfeifer 's avatar
Johannes Pfeifer committed
904 905
@anchor{nointeractive}
Instructs Dynare to not request user input.
906

907 908 909 910 911 912 913 914 915
@item nopathchange
By default Dynare will change Matlab/Octave's path if
@file{dynare/matlab} directory is not on top and if Dynare's routines
are overriden by routines provided in other toolboxes. If one wishes to
override Dynare's routines, the @code{nopathchange} options can be
used. Alternatively, the path can be temporarly modified by the user at
the top of the @file{*.mod} file (using Matlab/Octave's @code{addpath}
command).

916 917 918 919
@item nopreprocessoroutput
Prevent Dynare from printing the output of the steps leading up to the
preprocessor as well as the preprocessor output itself.

920 921 922 923 924
@item mingw
Tells Dynare that your MATLAB is configured for compiling MEX files with the
MinGW-compiler from TDM-GCC (@pxref{Compiler installation}). This option is
only available under Windows, and is used in conjunction with
@code{use_dll}.
925 926 927

@item msvc
Tells Dynare that your MATLAB is configured for compiling MEX files with
928
Microsoft Visual C++ (@pxref{Compiler installation}). This option is
929 930 931
only available under Windows, and is used in conjunction with
@code{use_dll}.

932 933 934 935 936
@item cygwin
Tells Dynare that your MATLAB is configured for compiling MEX files with
Cygwin (@pxref{Compiler installation}). This option is only available
under Windows, and is used in conjunction with @code{use_dll}.

937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957
@item parallel[=@var{CLUSTER_NAME}]
Tells Dynare to perform computations in parallel. If @var{CLUSTER_NAME}
is passed, Dynare will use the specified cluster to perform parallel
computations. Otherwise, Dynare will use the first cluster specified in
the configuration file. @xref{The Configuration File}, for more
information about the configuration file.

@item conffile=@var{FILENAME}
Specifies the location of the configuration file if it differs from the
default. @xref{The Configuration File}, for more information about the
configuration file and its default location.

@item parallel_slave_open_mode
Instructs Dynare to leave the connection to the slave node open after
computation is complete, closing this connection only when Dynare
finishes processing.

@item parallel_test
Tests the parallel setup specified in the configuration file without
executing the @file{.mod} file. @xref{The Configuration File}, for more
information about the configuration file.
958 959 960 961

@item -D@var{MACRO_VARIABLE}=@var{MACRO_EXPRESSION}
Defines a macro-variable from the command line (the same effect as using
the Macro directive @code{@@#define} in a model file, @pxref{Macro-processing language}).
962

963
@anchor{-I}
964 965 966 967 968
@item -I@var{<<path>>}
Defines a path to search for files to be included by the
macroprocessor (using the @ref{@@#include} command). Multiple
@code{-I} flags can be passed on the command line. The paths will be
searched in the order that the @code{-I} flags are passed and the
969 970
first matching file will be used. The flags passed here take priority
over those passed to @ref{@@#includepath}.
971

972
@item nostrict
973 974 975
Allows Dynare to issue a warning and continue processing when
@enumerate
@item there are more endogenous variables than equations
976
@item an undeclared symbol is assigned in @code{initval} or @code{endval}
977
@item an undeclared symbol is found in the @code{model} block; in this case, it is automatically declared exogenous
978
@item exogenous variables were declared but not used in the @code{model} block
979
@end enumerate
980 981 982 983

@item fast
Only useful with model option @code{use_dll}. Don't recompile the MEX
files when running again the same model file and the lists of variables
984 985 986 987
and the equations haven't changed. We use a 32 bit checksum, stored in
@code{<model filename>/checksum}. There is a very small probability that
the preprocessor misses a change in the model. In case of doubt, re-run
without the @code{fast} option.
988 989 990 991 992 993

@item minimal_workspace
Instructs Dynare not to write parameter assignments to parameter names
in the @file{.m} file produced by the preprocessor. This is
potentially useful when running @code{dynare} on a large @file{.mod}
file that runs into workspace size limitations imposed by MATLAB.
994 995 996 997

@item compute_xrefs
Tells Dynare to compute the equation cross references, writing them to the
output @file{.m} file.
998 999 1000 1001

@item stochastic
Tells Dynare that the model to be solved is stochastic. If no Dynare commands related to stochastic models (@code{stoch_simul}, @code{estimation}@dots{}) are present in the @code{.mod} file, Dynare understands by default that the model to be solved is deterministic.

1002 1003
@end table

1004 1005 1006 1007 1008
These options can be passed to the preprocessor by listing them after the name
of the @code{.mod} file. They can alternatively be defined in the first line of
the @file{.mod} file, this avoids typing them on the command line each time a
@file{.mod} file is to be run. This line must be a Dynare comment (@emph{ie}
must begin with @code{//}) and the options must be comma separated between
1009 1010 1011 1012
@code{--+ options:} and @code{+--}. Note that any text after the @code{+--}
will be discarded. As with the command line, if an option admits a value the
equal symbol must not be surrounded by spaces. For instance @code{json =
compute} is not correct, and should be written @code{json=compute}.
1013

1014 1015 1016
@outputhead

Depending on the computing tasks requested in the @file{.mod} file,
1017 1018 1019
executing the @code{dynare} command will leave variables containing
results in the workspace available for further processing. More
details are given under the relevant computing tasks.
1020

1021 1022
The @code{M_}, @code{oo_}, and @code{options_} structures are saved in
a file called @file{@var{FILENAME}_results.mat}. If they exist,
1023
@code{estim_params_}, @code{bayestopt_}, @code{dataset_}, @code{oo_recursive_} and
1024
@code{estimation_info} are saved in the same file.
1025 1026 1027 1028 1029

@examplehead

@example
dynare ramst
1030
dynare ramst.mod savemacro
1031 1032
@end example

1033 1034 1035 1036 1037 1038 1039
Alternatively the options can be specified in the first line of @file{ramst.mod}:

@example
// --+ options: savemacro, json=compute +--
@end example


1040 1041 1042 1043 1044 1045
@end deffn

The output of Dynare is left into three main variables in the
MATLAB/Octave workspace:

@defvr {MATLAB/Octave variable} M_
1046
Structure containing various information about the model.
1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057
@end defvr

@defvr {MATLAB/Octave variable} options_
Structure contains the values of the various options used by Dynare
during the computation.
@end defvr

@defvr {MATLAB/Octave variable} oo_
Structure containing the various results of the computations.
@end defvr

1058 1059 1060 1061 1062 1063 1064 1065
@defvr {MATLAB/Octave variable} oo_recursive_
@anchor{oo_recursive_}
Cell array containing the @code{oo_} structures obtained when estimating the model 
for the different samples when performing recursive estimation and forecasting. 
The @code{oo_} structure obtained for the sample ranging to the @math{i}th observation 
is saved in the @math{i}th field. The fields for non-estimated endpoints are empty.
@end defvr

1066 1067 1068 1069

@node Dynare hooks
@section Dynare hooks

1070
It is possible to call pre and post Dynare preprocessor hooks written as MATLAB scripts.
1071
The script @file{@var{MODFILENAME}/hooks/priorprocessing.m} is executed before the
1072
call to Dynare's preprocessor, and  can be used to programmatically transform the mod file
1073
that will be read by the preprocessor. The script @file{@var{MODFILENAME}/hooks/postprocessing.m}
1074
is executed just after the call to Dynare's preprocessor, and can be used to programmatically
1075
transform the files generated by Dynare's preprocessor before actual computations start. The
Houtan Bastani's avatar
Houtan Bastani committed
1076
pre and/or post dynare preprocessor hooks are executed if and only if the aforementioned scripts
1077 1078 1079
are detected in the same folder as the the model file, @file{@var{FILENAME}.mod}.


1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117
@node Understanding Preprocessor Error Messages
@section Understanding Preprocessor Error Messages

If the preprocessor runs into an error while processing your
@file{.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:
@enumerate
@item @code{ERROR: <<file.mod>>: line A, col B: <<error message>>}
@item @code{ERROR: <<file.mod>>: line A, cols B-C: <<error message>>}
@item @code{ERROR: <<file.mod>>: line A, col B - line C, col D: <<error message>>}
@end enumerate
@noindent 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:
@example
varexo a, b
parameters c, ...;
@end example
@noindent In this case, the parser doesn't know a semicolon is missing at the
end of the @code{varexo} command until it begins parsing the second
line and bumps into the @code{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, @code{parameters}, which
it did not expect. Hence, it throws an error of the form: @code{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.

1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152
@node Invoking the Dynare Preprocessor from the GNU/Linux or macOS Command Line
@section Invoking the Dynare Preprocessor from the GNU/Linux or macOS Command Line

You can invoke the preprocessor directly from the command line. In this way,
the preprocessor can be called a @file{.mod} file as explained above or on the
text of a @file{.mod} file as explained herein.

In certain circumstances, it may be useful to invoke the preprocessor on the
text of a @file{.mod} file. To do so, simply invoke the preprocessor by passing
it the text of your @file{.mod} file as the first argument. This argument
requires special care. First, any native Matlab statements contained in the
string representing your @file{.mod} file must be followed by a newline
character (@code{\n}). Further, any single-line comments must also be followed
by a newline character. Finally, any apostrophe's must be escaped with a
backslash (@i{i.e.}, @code{\'} instead of @code{'}.

Taking into account the considerations above, the file located in
@code{examples/example1.mod} could be run by executing:
@example
./dynare_m $'/* * Example 1 from F. Collard (2001): "Stochastic simulations
with DYNARE: * A practical guide" (see "guide.pdf" in the documentation
directory). */var y, c, k, a, h, b;varexo e, u;parameters beta, rho, alpha,
delta, theta, psi, tau;alpha = 0.36;rho = 0.95;tau = 0.025;beta = 0.99;delta =
0.025;psi = 0;theta = 2.95;phi = 0.1;\nmodel;c*theta*h^(1+psi)=(1-alpha)*y;k =
beta*(((exp(b)*c)/(exp(b(+1))*c(+1))) *(exp(b(+1))*alpha*y(+1)+(1-delta)*k));y
= exp(a)*(k(-1)^alpha)*(h^(1-alpha));k = exp(b)*(y-c)+(1-delta)*k(-1);a =
rho*a(-1)+tau*b(-1) + e;b = tau*a(-1)+rho*b(-1) + u;end;initval;y =
1.08068253095672;c = 0.80359242014163;h = 0.29175631001732;k =
11.08360443260358;a = 0;b = 0;e = 0;u = 0;end;shocks;var e; stderr 0.009;var u;
stderr 0.009;var e, u = phi*0.009*0.009;end;stoch_simul;'
@end example

This produces the same output as when running dynare on a @file{.mod} file with
the basename of the output files being set to @code{mod_file_passed_as_string_}.

1153 1154 1155 1156
@node The Model file
@chapter The Model file

@menu
1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170
* Conventions::
* Variable declarations::
* Expressions::
* Parameter initialization::
* Model declaration::
* Auxiliary variables::
* Initial and terminal conditions::
* Shocks on exogenous variables::
* Other general declarations::
* Steady state::
* Getting information about the model::
* Deterministic simulation::
* Stochastic solution and simulation::
* Estimation::
1171 1172 1173
* Model Comparison::
* Shock Decomposition::
* Calibrated Smoother::
1174 1175 1176 1177 1178 1179
* Forecasting::
* Optimal policy::
* Sensitivity and identification analysis::
* Markov-switching SBVAR::
* Displaying and saving results::
* Macro-processing language::
1180
* Verbatim inclusion::
1181
* Misc commands::
1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197
@end menu

@node Conventions
@section 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
(@code{;}). Blocks are terminated by @code{end;}.

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:

1198
@itemize
1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212

@item
optional arguments or options are indicated between square brackets:
@samp{[]};

@item
repreated arguments are indicated by ellipses: ``@dots{}'';

@item
mutually exclusive arguments are separated by vertical bars: @samp{|};

@item
@var{INTEGER} indicates an integer number;

1213
@item
1214 1215
@var{INTEGER_VECTOR} indicates a vector of integer numbers separated by spaces,
enclosed by square brackets;
1216

1217 1218
@item
@var{DOUBLE} indicates a double precision number. The following syntaxes
1219 1220
are valid: @code{1.1e3}, @code{1.1E3}, @code{1.1d3}, @code{1.1D3}. In
some places, infinite values @code{Inf} and @code{-Inf} are also allowed;
1221

Houtan Bastani's avatar
Houtan Bastani committed
1222 1223 1224 1225
@item
@var{NUMERICAL_VECTOR} indicates a vector of numbers separated by spaces,
enclosed by square brackets;

1226 1227 1228 1229 1230 1231 1232 1233
@item
@var{EXPRESSION} indicates a mathematical expression valid outside the
model description (@pxref{Expressions});

@item
@var{MODEL_EXPRESSION} indicates a mathematical expression valid in the
model description (@pxref{Expressions} and @ref{Model declaration});

1234 1235 1236 1237
@item
@var{MACRO_EXPRESSION} designates an expression of the macro-processor
(@pxref{Macro expressions});

1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248
@item
@var{VARIABLE_NAME} indicates a variable name starting with an
alphabetical character and can't contain: @samp{()+-*/^=!;:@@#.} or
accentuated characters;

@item
@var{PARAMETER_NAME} indicates a parameter name starting with an
alphabetical character and can't contain: @samp{()+-*/^=!;:@@#.} or
accentuated characters;

@item
1249 1250
@var{LATEX_NAME} indicates a valid @LaTeX{} expression in math mode
(not including the dollar signs);
1251 1252 1253 1254 1255 1256

@item
@var{FUNCTION_NAME} indicates a valid MATLAB function name;

@item
@var{FILENAME} indicates a filename valid in the underlying operating
1257 1258
system; it is necessary to put it between quotes when specifying the
extension or if the filename contains a non-alphanumeric character;
1259 1260 1261 1262 1263 1264

@end itemize

@node Variable declarations
@section Variable declarations

1265 1266 1267 1268 1269 1270 1271
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 @var{Ln}
or @var{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 
Johannes Pfeifer 's avatar
Johannes Pfeifer committed
1272
names like @var{alpha}, because there are Matlab functions of the same name. Rather go for @var{alppha} or @var{alph}.
1273
Lastly, please do not name a variable or parameter @var{i}. This may interfere with the imaginary 
Johannes Pfeifer 's avatar
Johannes Pfeifer committed
1274 1275
number @var{i} and the index in many loops. Rather, name investment @var{invest}. Using @var{inv} is also not recommended
as it alread denotes the inverse operator.
1276

1277 1278
Declarations of variables and parameters are made with the following commands:

1279 1280 1281
@deffn Command var @var{VARIABLE_NAME} [$@var{LATEX_NAME}$] [(long_name=@var{QUOTED_STRING}|NAME=@var{QUOTED_STRING}@dots{})]@dots{};
@deffnx Command var (deflator = @var{MODEL_EXPRESSION}) @var{VARIABLE_NAME} [$@var{LATEX_NAME}$] [(long_name=@var{QUOTED_STRING}|NAME=@var{QUOTED_STRING}@dots{})]@dots{};
@deffnx Command var (log_deflator = @var{MODEL_EXPRESSION}) @var{VARIABLE_NAME} [$@var{LATEX_NAME}$] [(long_name=@var{QUOTED_STRING}|NAME=@var{QUOTED_STRING}@dots{})]@dots{};
1282 1283 1284 1285 1286

@descriptionhead

This required command declares the endogenous variables in the
model. @xref{Conventions}, for the syntax of @var{VARIABLE_NAME} and
1287 1288 1289
@var{MODEL_EXPRESSION}. Optionally it is possible to give a @LaTeX{}
name to the variable or, if it is nonstationary, provide information
regarding its deflator.
1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307

@code{var} commands can appear several times in the file and Dynare will
concatenate them.

@optionshead

If the model is nonstationary and is to be written as such in the
@code{model} block, Dynare will need the trend deflator for the
appropriate endogenous variables in order to stationarize the model. The
trend deflator must be provided alongside the variables that follow this
trend.

@table @code

@item deflator = @var{MODEL_EXPRESSION}
The expression used to detrend an endogenous variable. All trend
variables, endogenous variables and parameters referenced in
@var{MODEL_EXPRESSION} must already have been declared by the
1308 1309 1310 1311 1312 1313 1314 1315 1316
@code{trend_var}, @code{log_trend_var}, @code{var} and
@code{parameters} commands. The deflator is assumed to be
multiplicative; for an additive deflator, use @code{log_deflator}.

@item log_deflator = @var{MODEL_EXPRESSION}
Same as @code{deflator}, except that the deflator is assumed to be
additive instead of multiplicative (or, to put it otherwise, the
declared variable is equal to the log of a variable with a
multiplicative trend).
1317 1318 1319 1320

@anchor{long_name}
@item long_name = @var{QUOTED_STRING}
This is the long version of the variable name. Its value is stored in
1321 1322
@code{M_.endo_names_long}. In case multiple @code{long_name} options are
provided, the last one will be used. Default: @var{VARIABLE_NAME}
1323

1324 1325 1326
@anchor{partitioning}
@item NAME = @var{QUOTED_STRING}
This is used to create a partitioning of variables. It results in the direct
1327 1328
output in the @file{.m} file analogous to:
@code{M_.endo_partitions.}@var{NAME}@code{ = }@var{QUOTED_STRING}@code{;}.
1329 1330 1331 1332 1333
@end table

@examplehead

@example
1334 1335
var c gnp cva (country=`US', state=`VA')
          cca (country=`US', state=`CA', long_name=`Consumption CA');
1336
var(deflator=A) i b;
Houtan Bastani's avatar
Houtan Bastani committed
1337
var c $C$ (long_name=`Consumption');
1338 1339 1340 1341
@end example

@end deffn

1342
@deffn Command varexo @var{VARIABLE_NAME} [$@var{LATEX_NAME}$] [(long_name=@var{QUOTED_STRING}|NAME=@var{QUOTED_STRING}@dots{})]@dots{};
1343 1344 1345 1346 1347

@descriptionhead

This optional command declares the exogenous variables in the model.
@xref{Conventions}, for the syntax of @var{VARIABLE_NAME}. Optionally it
1348
is possible to give a @LaTeX{} name to the variable.
1349 1350 1351 1352 1353 1354 1355

Exogenous variables are required if the user wants to be able to apply
shocks to her model.

@code{varexo} commands can appear several times in the file and Dynare
will concatenate them.

1356 1357 1358 1359
@optionshead
@table @code
@item long_name = @var{QUOTED_STRING}
Like @ref{long_name} but value stored in @code{M_.exo_names_long}.
1360

1361
@item NAME = @var{QUOTED_STRING}
1362 1363
Like @ref{partitioning} but @var{QUOTED_STRING} stored in
@code{M_.exo_partitions.}@var{NAME}.
1364 1365
@end table

1366 1367 1368 1369 1370 1371 1372 1373
@examplehead

@example
varexo m gov;
@end example

@end deffn

1374
@deffn Command varexo_det @var{VARIABLE_NAME} [$@var{LATEX_NAME}$] [(long_name=@var{QUOTED_STRING}|NAME=@var{QUOTED_STRING}@dots{})]@dots{};
1375 1376 1377 1378 1379

@descriptionhead

This optional command declares exogenous deterministic variables in a
stochastic model. See @ref{Conventions}, for the syntax of
1380 1381
@var{VARIABLE_NAME}. Optionally it is possible to give a @LaTeX{} name
to the variable.
1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393

It is possible to mix deterministic and stochastic shocks to build
models where agents know from the start of the simulation about future
exogenous changes. In that case @code{stoch_simul} will compute the
rational expectation solution adding future information to the state
space (nothing is shown in the output of @code{stoch_simul}) and
@code{forecast} will compute a simulation conditional on initial
conditions and future information.

@code{varexo_det} commands can appear several times in the file and
Dynare will concatenate them.

1394 1395 1396 1397
@optionshead
@table @code
@item long_name = @var{QUOTED_STRING}
Like @ref{long_name} but value stored in @code{M_.exo_det_names_long}.
1398

1399
@item NAME = @var{QUOTED_STRING}
1400 1401
Like @ref{partitioning} but @var{QUOTED_STRING} stored in
@code{M_.exo_det_partitions.}@var{NAME}.
1402 1403
@end table

1404 1405 1406 1407