the-model-file.rst 420 KB
Newer Older
1 2
.. default-domain:: dynare

3 4 5 6
.. |br| raw:: html

    <br>

7 8 9 10 11 12
.. _model-file:

##############
The model file
##############

13
.. _conv:
14 15 16 17

Conventions
===========

18 19 20
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;``.
21

22 23
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
24
MATLAB code, even if there are more statements separated by semicolons
25 26
present. To prevent cryptic error messages, it is strongly recommended
to always only put one statement/command into each line and start a
27
new line after each semicolon. [#feol]_
28

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

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

36 37
* Optional arguments or options are indicated between square brackets:
  [];
38 39 40
* Repeated arguments are indicated by ellipses: ...;
* Mutually exclusive arguments are separated by vertical bars: |;
* INTEGER indicates an integer number;
41 42 43
* INTEGER_VECTOR indicates a vector of integer numbers separated by
  spaces, enclosed by square brackets;
* DOUBLE indicates a double precision number. The following syntaxes
Stéphane Adjemian's avatar
Stéphane Adjemian committed
44 45
  are valid: ``1.1e3``, ``1.1E3``, ``1.1d3``, ``1.1D3``. In some
  places, infinite Values ``Inf`` and ``-Inf`` are also allowed;
46 47 48 49 50 51 52
* 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`);
53
* MACRO_EXPRESSION designates an expression of the macro processor
54 55 56 57 58 59 60
  (see :ref:`macro-exp`);
* VARIABLE_NAME (sometimes VAR_NAME) indicates a variable name
  starting with an alphabetical character and cant contain:
  ()+-\*/^=!;:@#.’ or accentuated characters;
* PARAMETER_NAME (sometimes PARAM_NAME) indicates a parameter name
  starting with an alphabetical character and cant contain:
  ()+-\*/^=!;:@#.’ or accentuated characters;
61
* LATEX_NAME (sometimes TEX_NAME) indicates a valid
Stéphane Adjemian's avatar
Stéphane Adjemian committed
62
  LaTeX expression in math mode (not including the
63
  dollar signs);
64
* FUNCTION_NAME indicates a valid MATLAB function name;
65 66 67
* 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;
68 69 70 71 72 73 74


.. _var-decl:

Variable declarations
=====================

75 76 77 78 79 80 81 82 83 84 85
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
86
MATLAB functions of the same name. Rather go for ``alppha`` or
87 88 89 90 91
``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.
92 93

.. command:: var VAR_NAME [$TEX_NAME$] [(long_name=QUOTED_STR|NAME=QUOTED_STR)]...;
94 95 96
    var(deflator=MODEL_EXPR) VAR_NAME (... same options apply)
    var(log_deflator=MODEL_EXPR) VAR_NAME (... same options apply)

97 98 99
    |br| This required command declares the endogenous variables in
    the model. See :ref:`conv` for the syntax of *VAR_NAME* and
    *MODEL_EXPR*. Optionally it is possible to give a
Stéphane Adjemian's avatar
Stéphane Adjemian committed
100
    LaTeX name to the variable or, if it is
Sébastien Villemot's avatar
Sébastien Villemot committed
101 102
    nonstationary, provide information regarding its deflator. The variables in
    the list can be separated by spaces or by commas. ``var``
103 104 105 106
    commands can appear several times in the file and Dynare will
    concatenate them. Dynare stores the list of declared parameters,
    in the order of declaration, in a column cell array
    ``M_.endo_names``.
107

108
    *Options*
109

110 111 112 113 114
    If the model is nonstationary and is to be written as such in the
    ``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.
115 116


117
    .. option:: deflator = MODEL_EXPR
118

119 120 121 122 123 124
        The expression used to detrend an endogenous variable. All
        trend variables, endogenous variables and parameters
        referenced in MODEL_EXPR must already have been declared by
        the ``trend_var, log_trend_var, var`` and ``parameters``
        commands. The deflator is assumed to be multiplicative; for an
        additive deflator, use ``log_deflator``.
125

126
    .. option:: log_deflator = MODEL_EXPR
127

128 129 130 131
        Same as ``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).
132

133
    .. _long-name:
134

135
    .. option:: long_name = QUOTED_STR
136

137 138 139 140 141
        This is the long version of the variable name. Its value is
        stored in ``M_.endo_names_long`` (a column cell array, in the
        same order as ``M_.endo_names``). In case multiple
        ``long_name`` options are provided, the last one will be
        used. Default: ``VAR_NAME``.
142

143
    .. _partitioning:
144

145
    .. option:: NAME = QUOTED_STR
146

147 148 149
        This is used to create a partitioning of variables. It results
        in the direct output in the ``.m`` file analogous to:
        ``M_.endo_partitions.NAME = QUOTED_STR``;.
150

151
    *Example (variable partitioning)*
152

153
      ::
154

155 156 157 158
        var c gnp cva (country=`US', state=`VA')
                  cca (country=`US', state=`CA', long_name=`Consumption CA');
        var(deflator=A) i b;
        var c $C$ (long_name=`Consumption');
159 160


161
.. command :: varexo VAR_NAME [$TEX_NAME$] [(long_name=QUOTED_STR|NAME=QUOTED_STR)...];
162

163 164
    |br| This optional command declares the exogenous variables in the
    model. See :ref:`conv` for the syntax of ``VAR_NAME``. Optionally
Stéphane Adjemian's avatar
Stéphane Adjemian committed
165
    it is possible to give a LaTeX name to the
166
    variable. Exogenous variables are required if the user wants to be
Sébastien Villemot's avatar
Sébastien Villemot committed
167 168
    able to apply shocks to her model.  The variables in
    the list can be separated by spaces or by commas. ``varexo`` commands can appear
169
    several times in the file and Dynare will concatenate them.
170

171
    *Options*
172

173
    .. option:: long_name = QUOTED_STRING
174

175
        Like :ref:`long_name <long-name>` but value stored in ``M_.exo_names_long``.
176

177
    .. option:: NAME = QUOTED_STRING
178

179 180
        Like :ref:`partitioning <partitioning>` but QUOTED_STRING
        stored in ``M_.exo_partitions.NAME``.
181

182
    *Example*
183

184
        ::
185

186
            varexo m gov;
187 188


189
    *Remarks*
190

191 192 193 194
    An exogenous variable is an innovation, in the sense
    that this variable cannot be predicted from the knowledge of the
    current state of the economy. For instance, if logged TFP is a first
    order autoregressive process:
195

196
    .. math::
197

198
       a_t  = \rho a_{t-1} + \varepsilon_t
199

200 201 202 203
    then logged TFP :math:`a_t` is an endogenous variable to be
    declared with ``var``, its best prediction is :math:`\rho
    a_{t-1}`, while the innovation :math:`\varepsilon_t` is to be
    declared with ``varexo``.
204 205


206
.. command:: varexo_det VAR_NAME [$TEX_NAME$] [(long_name=QUOTED_STR|NAME=QUOTED_STR)...];
207

208 209
    |br| This optional command declares exogenous deterministic
    variables in a stochastic model. See :ref:`conv` for the syntax of
Stéphane Adjemian's avatar
Stéphane Adjemian committed
210
    VARIABLE_NAME. Optionally it is possible to give a LaTeX
Sébastien Villemot's avatar
Sébastien Villemot committed
211 212
    name to the variable.  The variables in
    the list can be separated by spaces or by commas. ``varexo_det`` commands can appear several
213
    times in the file and Dynare will concatenate them.
214

215 216 217 218 219 220 221
    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 ``stoch_simul`` will
    compute the rational expectation solution adding future
    information to the state space (nothing is shown in the output of
    ``stoch_simul``) and forecast will compute a simulation
    conditional on initial conditions and future information.
222 223


224
    *Options*
225

226
    .. option:: long_name = QUOTED_STRING
227

228 229
       Like :ref:`long_name <long-name>` but value stored in
       ``M_.exo_det_names_long``.
230

231
    .. option:: NAME = QUOTED_STRING
232

233 234
       Like :ref:`partitioning <partitioning>` but QUOTED_STRING stored
       in ``M_.exo_det_partitions.NAME``.
235

236
    *Example*
237

238
        ::
239

240 241
            varexo m gov;
            varexo_det tau;
242 243


244
.. command :: parameters PARAM_NAME [$TEX_NAME$] [(long_name=QUOTED_STR|NAME=QUOTED_STR)...];
245

246 247 248
    |br| This command declares parameters used in the model, in variable
    initialization or in shocks declarations. See :ref:`conv` for the
    syntax of ``PARAM_NAME``. Optionally it is possible to give a
Stéphane Adjemian's avatar
Stéphane Adjemian committed
249
    LaTeX name to the parameter.
250

251
    The parameters must subsequently be assigned values (see :ref:`param-init`).
252

Sébastien Villemot's avatar
Sébastien Villemot committed
253 254 255
    The parameters in the list can be separated by spaces or by commas.
    ``parameters`` commands can appear several times in the file and Dynare
    will concatenate them.
256

257
    *Options*
258

259
    .. option:: long_name = QUOTED_STRING
260

261
        Like :ref:`long_name <long-name>` but value stored in ``M_.param_names_long``.
262

263
    .. option:: NAME = QUOTED_STRING
264

265
        Like :ref:`partitioning <partitioning>` but QUOTED_STRING stored in ``M_.param_partitions.NAME``.
266

267
    *Example*
268

269
        ::
270

271
            parameters alpha, bet;
272 273


274
.. command :: change_type (var|varexo|varexo_det|parameters) VAR_NAME | PARAM_NAME...;
275

276 277 278 279 280 281 282 283
    Changes the types of the specified variables/parameters to another
    type: endogenous, exogenous, exogenous deterministic or
    parameter. It is important to understand that this command has a
    global effect on the ``.mod`` file: the type change is effective
    after, but also before, the ``change_type`` command. This command
    is typically used when flipping some variables for steady state
    calibration: typically a separate model file is used for
    calibration, which includes the list of variable declarations with
284
    the macro processor, and flips some variable.
285

286
    *Example*
287

288
        ::
289

290 291 292 293 294
            var y, w;
            parameters alpha, beta;
            ...
            change_type(var) alpha, beta;
            change_type(parameters) y, w;
295

Stéphane Adjemian's avatar
Stéphane Adjemian committed
296 297
        Here, in the whole model file, ``alpha`` and ``beta`` will be
        endogenous and ``y`` and ``w`` will be parameters.
298 299


300
.. command:: predetermined_variables VAR_NAME...;
301

302 303 304 305 306 307 308 309 310 311 312 313 314 315 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 358 359 360
    |br| In Dynare, the default convention is that the timing of a variable
    reflects when this variable is decided. The typical example is for
    capital stock: since the capital stock used at current period is
    actually decided at the previous period, then the capital stock
    entering the production function is ``k(-1)``, and the law of
    motion of capital must be written::

        k = i + (1-delta)*k(-1)

    Put another way, for stock variables, the default in Dynare is to
    use a stock at the end of the period concept, instead of a
    stock at the beginning of the period convention.

    The ``predetermined_variables`` is used to change that
    convention. The endogenous variables declared as predetermined
    variables are supposed to be decided one period ahead of all other
    endogenous variables. For stock variables, they are supposed to
    follow a stock at the beginning of the period convention.

    Note that Dynare internally always uses the stock at the end of
    the period concept, even when the model has been entered using
    the ``predetermined_variables`` command. Thus, when plotting,
    computing or simulating variables, Dynare will follow the
    convention to use variables that are decided in the current
    period. For example, when generating impulse response functions
    for capital, Dynare will plot ``k``, which is the capital stock
    decided upon by investment today (and which will be used in
    tomorrows production function). This is the reason that capital
    is shown to be moving on impact, because it is ``k`` and not the
    predetermined ``k(-1)`` that is displayed. It is important to
    remember that this also affects simulated time series and output
    from smoother routines for predetermined variables. Compared to
    non-predetermined variables they might otherwise appear to be
    falsely shifted to the future by one period.

    *Example*

        The following two program snippets are strictly equivalent.

        Using default Dynare timing convention::

            var y, k, i;
            ...
            model;
            y = k(-1)^alpha;
            k = i + (1-delta)*k(-1);
            ...
            end;

        Using the alternative timing convention::

            var y, k, i;
            predetermined_variables k;
            ...
            model;
            y = k^alpha;
            k(+1) = i + (1-delta)*k;
            ...
            end;
361 362 363 364


.. command:: trend_var (growth_factor = MODEL_EXPR) VAR_NAME [$LATEX_NAME$]...;

365 366
    |br| This optional command declares the trend variables in the
    model. See ref:`conv` for the syntax of MODEL_EXPR and
Stéphane Adjemian's avatar
Stéphane Adjemian committed
367
    VAR_NAME. Optionally it is possible to give a
Stéphane Adjemian's avatar
Stéphane Adjemian committed
368
    LaTeX name to the variable.
369

370 371
    The variable is assumed to have a multiplicative growth trend. For
    an additive growth trend, use ``log_trend_var`` instead.
372

373 374 375 376
    Trend variables are required if the user wants to be able to write
    a nonstationary model in the ``model`` block. The ``trend_var``
    command must appear before the var command that references the
    trend variable.
377

378 379
    ``trend_var`` commands can appear several times in the file and
    Dynare will concatenate them.
380

381 382 383 384 385 386 387
    If the model is nonstationary and is to be written as such in the
    ``model`` block, Dynare will need the growth factor of every trend
    variable in order to stationarize the model. The growth factor
    must be provided within the declaration of the trend variable,
    using the ``growth_factor`` keyword. All endogenous variables and
    parameters referenced in MODEL_EXPR must already have been
    declared by the var and parameters commands.
388

389
    *Example*
390

391 392
        ::

393
            trend_var (growth_factor=gA) A;
394 395 396 397


.. command :: log_trend_var (log_growth_factor = MODEL_EXPR) VAR_NAME [$LATEX_NAME$]...;

398 399 400
    |br| Same as ``trend_var``, except that the variable is supposed to
    have an additive trend (or, to put it otherwise, to be equal to
    the log of a variable with a multiplicative trend).
401 402


403 404
.. command::  model_local_variable VARIABLE_NAME [LATEX_NAME]... ;

Stéphane Adjemian's avatar
Stéphane Adjemian committed
405
    |br| This optional command declares a model local variable. See
406 407 408 409 410 411 412 413 414 415 416 417
    :ref:`conv` for the syntax of VARIABLE_NAME. As you can create
    model local variables on the fly in the model block (see
    :ref:`model-decl`), the interest of this command is primarily to
    assign a LATEX_NAME to the model local variable.

    *Example*

        ::

            model_local_variable GDP_US $GDPUS$;


418 419 420 421 422 423
.. _on-the-fly-declaration:

On-the-fly Model Variable Declaration
-------------------------------------

Endogenous variables, exogenous variables, and parameters can also be declared
424 425 426 427 428 429 430 431 432
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']``.

Sébastien Villemot's avatar
Sébastien Villemot committed
433
To perform on-the-fly variable declaration in an equation, simply follow the
434 435 436 437 438
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
439
on-the-fly variable declarations must be made on contemporaneous variables.
440 441 442

On-the-fly variable declarations do not have to appear in the first place where
this variable is encountered.
443 444 445 446 447 448 449 450

*Example*

    The following two snippets are equivalent:

        ::

            model;
451
              [endogenous='k',name='law of motion of capital']
452
              k(+1) = i|e + (1-delta|p)*k;
453
              y|e = k^alpha|p;
454 455 456 457 458 459 460 461 462 463 464 465 466
              ...
            end;
            delta = 0.025;
            alpha = 0.36;

        ::

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

473 474 475 476 477
.. _expr:

Expressions
===========

Stéphane Adjemian's avatar
Stéphane Adjemian committed
478 479 480 481 482 483
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.
484

Stéphane Adjemian's avatar
Stéphane Adjemian committed
485 486
Unlike MATLAB or Octave expressions, Dynare expressions are
necessarily scalar ones: they cannot contain matrices or evaluate to
487
matrices. [#f1]_
488

Stéphane Adjemian's avatar
Stéphane Adjemian committed
489 490 491
Expressions can be constructed using integers (INTEGER), floating
point numbers (DOUBLE), parameter names (PARAMETER_NAME), variable
names (VARIABLE_NAME), operators and functions.
492 493 494 495 496

The following special constants are also accepted in some contexts:

.. constant:: inf

497
    Represents infinity.
498 499 500 501 502 503 504 505 506

.. constant:: nan

    Not a number: represents an undefined or unrepresentable value.


Parameters and variables
------------------------

Stéphane Adjemian's avatar
Stéphane Adjemian committed
507 508 509
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.
510 511 512 513 514


Inside the model
^^^^^^^^^^^^^^^^

Stéphane Adjemian's avatar
Stéphane Adjemian committed
515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539
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).
540 541 542 543 544


Outside the model
^^^^^^^^^^^^^^^^^

Stéphane Adjemian's avatar
Stéphane Adjemian committed
545 546 547 548 549 550
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.
551 552 553 554 555


Operators
---------

Stéphane Adjemian's avatar
Stéphane Adjemian committed
556 557
The following operators are allowed in both MODEL_EXPRESSION and
EXPRESSION:
558

Stéphane Adjemian's avatar
Stéphane Adjemian committed
559 560 561 562
* Binary arithmetic operators: ``+``, ``-``, ``*``, ``/``, ``^``
* Unary arithmetic operators: ``+``, ``-``
* Binary comparison operators (which evaluate to either 0 or 1): ``<``,
  ``>``, ``<=``, ``>=``, ``==``, ``!=``
563

Stéphane Adjemian's avatar
Stéphane Adjemian committed
564 565 566 567 568 569
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).
570

Stéphane Adjemian's avatar
Stéphane Adjemian committed
571 572
The following special operators are accepted in MODEL_EXPRESSION (but
not in EXPRESSION):
573 574 575

.. operator:: STEADY_STATE (MODEL_EXPRESSION)

Stéphane Adjemian's avatar
Stéphane Adjemian committed
576 577 578 579
    This operator is used to take the value of the enclosed expression
    at the steady state. A typical usage is in the Taylor rule, where
    you may want to use the value of GDP at steady state to compute
    the output gap.
580

Sébastien Villemot's avatar
Sébastien Villemot committed
581 582 583
    Exogenous and exogenous deterministic variables may not appear in
    MODEL_EXPRESSION.

584 585
.. operator:: EXPECTATION (INTEGER) (MODEL_EXPRESSION)

Stéphane Adjemian's avatar
Stéphane Adjemian committed
586 587 588 589 590 591 592
    This operator is used to take the expectation of some expression
    using a different information set than the information available
    at current period. For example, ``EXPECTATION(-1)(x(+1))`` is
    equal to the expected value of variable x at next period, using
    the information set available at the previous period. See
    :ref:`aux-variables` for an explanation of how this operator is
    handled internally and how this affects the output.
593 594 595 596 597 598 599 600


Functions
---------

Built-in functions
^^^^^^^^^^^^^^^^^^

Stéphane Adjemian's avatar
Stéphane Adjemian committed
601 602
The following standard functions are supported internally for both
MODEL_EXPRESSION and EXPRESSION:
603 604 605

.. function:: exp(x)

606
    Natural exponential.
607 608 609 610

.. function:: log(x)
.. function:: ln(x)

611
    Natural logarithm.
612 613 614

.. function:: log10(x)

615
    Base 10 logarithm.
616 617 618

.. function:: sqrt(x)

619
    Square root.
620

621 622
.. function:: cbrt(x)

Houtan Bastani's avatar
Houtan Bastani committed
623
    Cube root.
624

Stéphane Adjemian's avatar
Stéphane Adjemian committed
625
.. function:: sign(x)
626

Stéphane Adjemian's avatar
Stéphane Adjemian committed
627
    Signum function, defined as:
628

Stéphane Adjemian's avatar
Stéphane Adjemian committed
629
        .. math::
630

Stéphane Adjemian's avatar
Stéphane Adjemian committed
631 632 633 634 635 636
           \textrm{sign}(x) =
                  \begin{cases}
                  -1 &\quad\text{if }x<0\\
                  0 &\quad\text{if }x=0\\
                  1 &\quad\text{if }x>0
                  \end{cases}
637 638


Stéphane Adjemian's avatar
Stéphane Adjemian committed
639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659
    Note that this function is not continuous, hence not  differentiable, at
    :math:`x=0`. However, for facilitating convergence of Newton-type
    methods, Dynare assumes that the derivative at :math:`x=0` is
    equal to :math:`0`. This assumption comes from the observation
    that both the right- and left-derivatives at this point exist and
    are equal to :math:`0`, so we can remove the singularity by
    postulating that the derivative at :math:`x=0` is :math:`0`.

.. function:: abs(x)

    Absolute value.

    Note that this continuous function is not differentiable at
    :math:`x=0`. However, for facilitating convergence of Newton-type
    methods, Dynare assumes that the derivative at :math:`x=0` is
    equal to :math:`0` (even if the derivative does not exist). The
    rational for this mathematically unfounded definition, rely on the
    observation that the derivative of :math:`\mathrm{abs}(x)` is equal to
    :math:`\mathrm{sign}(x)` for any :math:`x\neq 0` in :math:`\mathbb R` and
    from the convention for the value of :math:`\mathrm{sign}(x)` at
    :math:`x=0`).
660 661 662 663 664 665 666 667

.. function:: sin(x)
.. function:: cos(x)
.. function:: tan(x)
.. function:: asin(x)
.. function:: acos(x)
.. function:: atan(x)

668
    Trigonometric functions.
669 670 671 672 673 674

.. function:: max(a, b)
.. function:: min(a, b)

    Maximum and minimum of two reals.

Stéphane Adjemian's avatar
Stéphane Adjemian committed
675 676 677 678 679 680 681 682 683
    Note that these functions are differentiable everywhere except on
    a line of the 2-dimensional real plane defined by
    :math:`a=b`. However for facilitating convergence of Newton-type
    methods, Dynare assumes that, at the points of
    non-differentiability, the partial derivative of these functions
    with respect to the first (resp. the second) argument is equal to
    :math:`1` (resp. to :math:`0`) (i.e. the derivatives at the kink
    are equal to the derivatives observed on the half-plane where the
    function is equal to its first argument).
684 685

.. function:: normcdf(x)
686
              normcdf(x, mu, sigma)
687

Stéphane Adjemian's avatar
Stéphane Adjemian committed
688 689 690
    Gaussian cumulative density function, with mean *mu* and standard
    deviation *sigma*. Note that ``normcdf(x)`` is equivalent to
    ``normcdf(x,0,1)``.
691 692

.. function:: normpdf(x)
693
              normpdf(x, mu, sigma)
694

Stéphane Adjemian's avatar
Stéphane Adjemian committed
695 696 697
    Gaussian probability density function, with mean *mu* and standard
    deviation *sigma*. Note that ``normpdf(x)`` is equivalent to
    ``normpdf(x,0,1)``.
698 699 700

.. function:: erf(x)

701
    Gauss error function.
702 703 704 705 706


External functions
^^^^^^^^^^^^^^^^^^

Stéphane Adjemian's avatar
Stéphane Adjemian committed
707 708 709
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.
710

Stéphane Adjemian's avatar
Stéphane Adjemian committed
711 712 713 714
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.
715 716 717

.. command:: external_function (OPTIONS...);

Stéphane Adjemian's avatar
Stéphane Adjemian committed
718 719 720
    This command declares the external functions used in the model
    block. It is required for every unique function used in the model
    block.
721

Stéphane Adjemian's avatar
Stéphane Adjemian committed
722 723
    ``external_function`` commands can appear several times in the
    file and must come before the model block.
724 725 726 727 728

    *Options*

    .. option:: name = NAME

Stéphane Adjemian's avatar
Stéphane Adjemian committed
729 730
        The name of the function, which must also be the name of the
        M-/MEX file implementing it. This option is mandatory.
731

732 733
    .. option:: nargs = INTEGER

Stéphane Adjemian's avatar
Stéphane Adjemian committed
734 735
        The number of arguments of the function. If this option is not
        provided, Dynare assumes ``nargs = 1``.
736

737 738
    .. option:: first_deriv_provided [= NAME]

Stéphane Adjemian's avatar
Stéphane Adjemian committed
739 740 741 742 743
        If NAME is provided, this tells Dynare that the Jacobian is
        provided as the only output of the M-/MEX file given as the
        option argument. If NAME is not provided, this tells Dynare
        that the M-/MEX file specified by the argument passed to NAME
        returns the Jacobian as its second output argument.
744

745 746
    .. option:: second_deriv_provided [= NAME]

Stéphane Adjemian's avatar
Stéphane Adjemian committed
747 748 749 750 751 752 753
        If NAME is provided, this tells Dynare that the Hessian is
        provided as the only output of the M-/MEX file given as the
        option argument. If NAME is not provided, this tells Dynare
        that the M-/MEX file specified by the argument passed to NAME
        returns the Hessian as its third output argument. NB: This
        option can only be used if the ``first_deriv_provided`` option
        is used in the same ``external_function`` command.
754

Stéphane Adjemian's avatar
Stéphane Adjemian committed
755
    *Example*
756

757
        ::
758

Stéphane Adjemian's avatar
Stéphane Adjemian committed
759 760 761
           external_function(name = funcname);
           external_function(name = otherfuncname, nargs = 2, first_deriv_provided, second_deriv_provided);
           external_function(name = yetotherfuncname, nargs = 3, first_deriv_provided = funcname_deriv);
762 763 764 765 766


A few words of warning in stochastic context
--------------------------------------------

Stéphane Adjemian's avatar
Stéphane Adjemian committed
767 768 769
The use of the following functions and operators is strongly
discouraged in a stochastic context: ``max``, ``min``, ``abs``,
``sign``, ``<``, ``>``, ``<=``, ``>=``, ``==``, ``!=``.
770

Stéphane Adjemian's avatar
Stéphane Adjemian committed
771 772 773 774 775 776 777
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).
778

Stéphane Adjemian's avatar
Stéphane Adjemian committed
779 780
Note that ``extended_path`` is not affected by this problem, because
it does not rely on a local approximation of the mode.
781 782 783 784 785 786 787


.. _param-init:

Parameter initialization
========================

788 789 790
When using Dynare for computing simulations, it is necessary to
calibrate the parameters of the model. This is done through parameter
initialization.
791 792 793

The syntax is the following::

794
    PARAMETER_NAME = EXPRESSION;
795 796 797

Here is an example of calibration::

798
    parameters alpha, beta;
799

800 801 802
    beta = 0.99;
    alpha = 0.36;
    A = 1-alpha*beta;
803 804 805 806 807

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

.. matvar:: M_.params

808
    Contains the values of model parameters. The parameters are in the
Sébastien Villemot's avatar
Sébastien Villemot committed
809
    order that was used in the ``parameters`` command, hence ordered as
810
    in ``M_.param_names``.
811

812 813 814 815 816
The parameter names are stored in ``M_.param_names``:

.. matvar:: M_.param_names

    Cell array containing the names of the model parameters.
817 818 819 820 821 822 823 824 825

.. _model-decl:

Model declaration
=================

The model is declared inside a ``model`` block:

.. block:: model ;
826
   model (OPTIONS...);
827

828 829
    |br| The equations of the model are written in a block delimited by
    ``model`` and ``end`` keywords.
830

831 832 833 834
    There must be as many equations as there are endogenous variables
    in the model, except when computing the unconstrained optimal
    policy with ``ramsey_model``, ``ramsey_policy`` or
    ``discretionary_policy``.
835

836 837 838 839
    The syntax of equations must follow the conventions for
    MODEL_EXPRESSION as described in :ref:`expr`. Each equation
    must be terminated by a semicolon (;). A normal equation looks
    like:
840

841
        MODEL_EXPRESSION = MODEL_EXPRESSION;
842

843 844 845
    |br| When the equations are written in homogenous form, it is possible
    to omit the =0 part and write only the left hand side of the
    equation. A homogenous equation looks like:
846

847
        MODEL_EXPRESSION;
848

849 850 851 852 853 854 855
    |br| Inside the model block, Dynare allows the creation of
    *model-local variables*, which constitute a simple way to share a
    common expression between several equations. The syntax consists
    of a pound sign (#) followed by the name of the new model local
    variable (which must **not** be declared as in :ref:`var-decl`,
    but may have been declared by :comm:`model_local_variable`), an
    equal sign, and the expression for which this new variable will
856 857 858
    stand. Later on, every time this variable appears in the model,
    Dynare will substitute it by the expression assigned to the
    variable. Note that the scope of this variable is restricted to
859 860 861 862
    the model block; it cannot be used outside. To assign a LaTeX name
    to the model local variable, use the declaration syntax outlined
    by :comm:`model_local_variable`. A model local variable declaration
    looks like:
863

864
        #VARIABLE_NAME = MODEL_EXPRESSION;
865

866 867 868 869 870
    |br| It is possible to tag equations written in the model block. A tag
    can serve different purposes by allowing the user to attach
    arbitrary informations to each equation and to recover them at
    runtime. For instance, it is possible to name the equations with a
    ``name``-tag, using a syntax like::
871

872
        model;
873

874 875
        [name = 'Budget constraint'];
        c + k = k^theta*A;
876

877
        end;
878

879 880 881 882 883 884
    Here, ``name`` is the keyword indicating that the tag names the
    equation. If an equation of the model is tagged with a name, the
    ``resid`` command will display the name of the equations (which
    may be more informative than the equation numbers) in addition to
    the equation number. Several tags for one equation can be
    separated using a comma::
885

886
        model;
887

888 889
        [name='Taylor rule',mcp = 'r > -1.94478']
        r = rho*r(-1) + (1-rho)*(gpi*Infl+gy*YGap) + e;
890

891
        end;
892

893
    More information on tags is available on the `Dynare wiki`_.
894

895
    *Options*
896

897
    .. option:: linear
898

899 900 901 902 903
        Declares the model as being linear. It spares oneself from
        having to declare initial values for computing the steady
        state of a stationary linear model. This option cant be used
        with non-linear models, it will NOT trigger linearization of
        the model.
904

905
    .. option:: use_dll
906

907 908 909 910 911 912 913 914 915
        Instructs the preprocessor to create dynamic loadable
        libraries (DLL) containing the model equations and
        derivatives, instead of writing those in M-files. You need a
        working compilation environment, i.e. a working ``mex``
        command (see :ref:`compil-install` for more details). On
        MATLAB for Windows, you will need to also pass the compiler
        name at the command line. Using this option can result in
        faster simulations or estimations, at the expense of some
        initial compilation time. [#f2]_
916

917
    .. option:: block
918

919 920 921 922 923
        Perform the block decomposition of the model, and exploit it
        in computations (steady-state, deterministic simulation,
        stochastic simulation with first order approximation and
        estimation). See `Dynare wiki`_ for details on the algorithms
        used in deterministic simulation and steady-state computation.
924

925
    .. option:: bytecode
926

927 928 929
        Instead of M-files, use a bytecode representation of the
        model, i.e. a binary file containing a compact representation
        of all the equations.
930

931
    .. option:: cutoff = DOUBLE
932

933 934 935
        Threshold under which a jacobian element is considered as null
        during the model normalization. Only available with option
        ``block``. Default: ``1e-15``
936

937
    .. option:: mfs = INTEGER
938

939 940 941
        Controls the handling of minimum feedback set of endogenous
        variables. Only available with option ``block``. Possible
        values:
942

943
        ``0``
944

945 946
            All the endogenous variables are considered as feedback
            variables (Default).
947

948
        ``1``
949

950 951 952 953 954
            The endogenous variables assigned to equation naturally
            normalized (i.e. of the form :math:`x=f(Y)` where
            :math:`x` does not appear in :math:`Y`) are potentially
            recursive variables. All the other variables are forced to
            belong to the set of feedback variables.
955

956
        ``2``
957

958 959 960 961 962
            In addition of variables with ``mfs = 1`` the endogenous
            variables related to linear equations which could be
            normalized are potential recursive variables. All the
            other variables are forced to belong to the set of
            feedback variables.
963

964 965
        ``3``

966 967 968 969 970
            In addition of variables with ``mfs = 2`` the endogenous
            variables related to non-linear equations which could be
            normalized are potential recursive variables. All the
            other variables are forced to belong to the set of
            feedback variables.
971 972 973

    .. option:: no_static

974 975 976
        Dont create the static model file. This can be useful for
        models which dont have a steady state.

Houtan Bastani's avatar
Houtan Bastani committed
977 978
    .. option:: differentiate_forward_vars
                differentiate_forward_vars = ( VARIABLE_NAME [VARIABLE_NAME ...] )
979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000

        Tells Dynare to create a new auxiliary variable for each
        endogenous variable that appears with a lead, such that the
        new variable is the time differentiate of the original
        one. More precisely, if the model contains ``x(+1)``, then a
        variable ``AUX_DIFF_VAR`` will be created such that
        ``AUX_DIFF_VAR=x-x(-1)``, and ``x(+1)`` will be replaced with
        ``x+AUX_DIFF_VAR(+1)``.

        The transformation is applied to all endogenous variables with
        a lead if the option is given without a list of variables. If
        there is a list, the transformation is restricted to
        endogenous with a lead that also appear in the list.

        This option can useful for some deterministic simulations
        where convergence is hard to obtain. Bad values for terminal
        conditions in the case of very persistent dynamics or
        permanent shocks can hinder correct solutions or any
        convergence. The new differentiated variables have obvious
        zero terminal conditions (if the terminal condition is a
        steady state) and this in many cases helps convergence of
        simulations.
1001

1002
    .. option:: parallel_local_files = ( FILENAME [, FILENAME]... )