the-model-file.rst 408 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 24 25 26 27 28
If Dynare encounters an unknown expression at the beginning of a line
or after a semicolon, it will parse the rest of that line as native
Matlab code, even if there are more statements separated by semicolons
present. To prevent cryptic error messages, it is strongly recommended
to always only put one statement/command into each line and start a
new line after each semicolon.

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 can’t contain:
  ‘()+-\*/^=!;:@#.’ or accentuated characters;
* PARAMETER_NAME (sometimes PARAM_NAME) indicates a parameter name
  starting with an alphabetical character and can’t contain:
  ‘()+-\*/^=!;:@#.’ or accentuated characters;
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 86 87 88 89 90 91
While Dynare allows the user to choose their own variable names, there
are some restrictions to be kept in mind. First, variables and
parameters must not have the same name as Dynare commands or built-in
functions. In this respect, Dynare is not case-sensitive. For example,
do not use ``Ln`` or ``Sigma_e`` to name your variable. Not conforming
to this rule might yield hard-to-debug error messages or
crashes. Second, to minimize interference with MATLAB or Octave
functions that may be called by Dynare or user-defined steady state
files, it is recommended to avoid using the name of MATLAB
functions. In particular when working with steady state files, do not
use correctly-spelled greek names like `alpha`, because there are
Matlab functions of the same name. Rather go for ``alppha`` or
``alph``. Lastly, please do not name a variable or parameter
``i``. This may interfere with the imaginary number i and the index in
many loops. Rather, name investment ``invest``. Using ``inv`` is also
not recommended as it already denotes the inverse operator. Commands
for declaring variables and parameters are described below.
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
    tomorrow’s 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 433 434 435 436 437 438
inside the model block. You can do this in two different ways: either via the
equation tag or directly in an equation.

To declare a variable on-the-fly in an equation tag, simply state the type of
variable to be declared (``endogenous``, ``exogenous``, or
``parameter`` followed by an equal sign and the variable name in single
quotes. Hence, to declare a variable ``c`` as endogenous in an equation tag,
you can type ``[endogenous='c']``.

To perform on-the-fly variable declaration in an equtaion, simply follow the
symbol name with a vertical line (``|``, pipe character) and either an ``e``, an
``x``, or a ``p``. For example, to declare a parameter named
``alphaa`` in the model block, you could write ``alphaa|p`` directly in
an equation where it appears. Similarly, to declare an endogenous variable
``c`` in the model block you could write ``c|e``. Note that in-equation
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 487
Unlike MATLAB or Octave expressions, Dynare expressions are
necessarily scalar ones: they cannot contain matrices or evaluate to
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 581 582

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

Stéphane Adjemian's avatar
Stéphane Adjemian committed
583 584 585 586 587 588 589
    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.
590 591 592 593 594 595 596 597


Functions
---------

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

Stéphane Adjemian's avatar
Stéphane Adjemian committed
598 599
The following standard functions are supported internally for both
MODEL_EXPRESSION and EXPRESSION:
600 601 602

.. function:: exp(x)

603
    Natural exponential.
604 605 606 607

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

608
    Natural logarithm.
609 610 611

.. function:: log10(x)

612
    Base 10 logarithm.
613 614 615

.. function:: sqrt(x)

616
    Square root.
617

618 619 620 621
.. function:: cbrt(x)

    Cubic root.

Stéphane Adjemian's avatar
Stéphane Adjemian committed
622
.. function:: sign(x)
623

Stéphane Adjemian's avatar
Stéphane Adjemian committed
624
    Signum function, defined as:
625

Stéphane Adjemian's avatar
Stéphane Adjemian committed
626
        .. math::
627

Stéphane Adjemian's avatar
Stéphane Adjemian committed
628 629 630 631 632 633
           \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}
634 635


Stéphane Adjemian's avatar
Stéphane Adjemian committed
636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656
    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`).
657 658 659 660 661 662 663 664

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

665
    Trigonometric functions.
666 667 668 669 670 671

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

    Maximum and minimum of two reals.

Stéphane Adjemian's avatar
Stéphane Adjemian committed
672 673 674 675 676 677 678 679 680
    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).
681 682

.. function:: normcdf(x)
683
              normcdf(x, mu, sigma)
684

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

.. function:: normpdf(x)
690
              normpdf(x, mu, sigma)
691

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

.. function:: erf(x)

698
    Gauss error function.
699 700 701 702 703


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

Stéphane Adjemian's avatar
Stéphane Adjemian committed
704 705 706
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.
707

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

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

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

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

    *Options*

    .. option:: name = NAME

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

729 730
    .. option:: nargs = INTEGER

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

734 735
    .. option:: first_deriv_provided [= NAME]

Stéphane Adjemian's avatar
Stéphane Adjemian committed
736 737 738 739 740
        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.
741

742 743
    .. option:: second_deriv_provided [= NAME]

Stéphane Adjemian's avatar
Stéphane Adjemian committed
744 745 746 747 748 749 750
        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.
751

Stéphane Adjemian's avatar
Stéphane Adjemian committed
752
    *Example*
753

754
        ::
755

Stéphane Adjemian's avatar
Stéphane Adjemian committed
756 757 758
           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);
759 760 761 762 763


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

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

Stéphane Adjemian's avatar
Stéphane Adjemian committed
768 769 770 771 772 773 774
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).
775

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


.. _param-init:

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

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

The syntax is the following::

791
    PARAMETER_NAME = EXPRESSION;
792 793 794

Here is an example of calibration::

795
    parameters alpha, beta;
796

797 798 799
    beta = 0.99;
    alpha = 0.36;
    A = 1-alpha*beta;
800 801 802 803 804

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

.. matvar:: M_.params

805
    Contains the values of model parameters. The parameters are in the
Sébastien Villemot's avatar
Sébastien Villemot committed
806
    order that was used in the ``parameters`` command, hence ordered as
807
    in ``M_.param_names``.
808 809 810 811 812 813 814 815 816 817


.. _model-decl:

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

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

.. block:: model ;
818
   model (OPTIONS...);
819

820 821
    |br| The equations of the model are written in a block delimited by
    ``model`` and ``end`` keywords.
822

823 824 825 826
    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``.
827

828 829 830 831
    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:
832

833
        MODEL_EXPRESSION = MODEL_EXPRESSION;
834

835 836 837
    |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:
838

839
        MODEL_EXPRESSION;
840

841 842 843 844 845 846 847
    |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
848 849 850
    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
851 852 853 854
    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:
855

856
        #VARIABLE_NAME = MODEL_EXPRESSION;
857

858 859 860 861 862
    |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::
863

864
        model;
865

866 867
        [name = 'Budget constraint'];
        c + k = k^theta*A;
868

869
        end;
870

871 872 873 874 875 876
    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::
877

878
        model;
879

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

883
        end;
884

885
    More information on tags is available on the `Dynare wiki`_.
886

887
    *Options*
888

889
    .. option:: linear
890

891 892 893 894 895
        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 can’t be used
        with non-linear models, it will NOT trigger linearization of
        the model.
896

897
    .. option:: use_dll
898

899 900 901 902 903 904 905 906 907
        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]_
908

909
    .. option:: block
910

911 912 913 914 915
        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.
916

917
    .. option:: bytecode
918

919 920 921
        Instead of M-files, use a bytecode representation of the
        model, i.e. a binary file containing a compact representation
        of all the equations.
922

923
    .. option:: cutoff = DOUBLE
924

925 926 927
        Threshold under which a jacobian element is considered as null
        during the model normalization. Only available with option
        ``block``. Default: ``1e-15``
928

929
    .. option:: mfs = INTEGER
930

931 932 933
        Controls the handling of minimum feedback set of endogenous
        variables. Only available with option ``block``. Possible
        values:
934

935
        ``0``
936

937 938
            All the endogenous variables are considered as feedback
            variables (Default).
939

940
        ``1``
941

942 943 944 945 946
            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.
947

948
        ``2``
949

950 951 952 953 954
            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.
955

956 957
        ``3``

958 959 960 961 962
            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.
963 964 965

    .. option:: no_static

966 967 968
        Don’t create the static model file. This can be useful for
        models which don’t have a steady state.

Houtan Bastani's avatar
Houtan Bastani committed
969 970
    .. option:: differentiate_forward_vars
                differentiate_forward_vars = ( VARIABLE_NAME [VARIABLE_NAME ...] )
971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992

        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.
993

994
    .. option:: parallel_local_files = ( FILENAME [, FILENAME]... )
995

996 997 998
        Declares a list of extra files that should be transferred to
        slave nodes when doing a parallel computation (see
        :ref:`paral-conf`).
999

1000
    *Example* (Elementary RBC model)
1001

1002
        ::
1003

1004 1005 1006
            var c k;
            varexo x;
            parameters aa alph bet delt gam;
1007

1008 1009 1010 1011
            model;
            c =  - k + aa*x*k(-1)^alph + (1-delt)*k(-1);
            c^(-gam) = (aa*alph*x(+1)*k^(alph-1) + 1 - delt)*c(+1)^(-gam)/(1+bet);
            end;
1012

1013
    *Example* (Use of model local variables)
1014

1015
        The following program::
1016

1017 1018 1019 1020 1021
            model;
            # gamma = 1 - 1/sigma;
            u1 = c1^gamma/gamma;
            u2 = c2^gamma/gamma;
            end;
1022

1023
        ...is formally equivalent to::
1024

1025 1026 1027 1028 1029
            model;
            u1 = c1^(1-1/sigma)/(1-1/sigma);
            u2 = c2^(1-1/sigma)/(1-1/sigma);
            end;

1030
    *Example* (A linear model)
1031 1032 1033 1034 1035 1036 1037

        ::

         model(linear);
         x = a*x(-1)+b*y(+1)+e_x;
         y = d*y(-1)+e_y;
         end;
1038 1039


1040
Dynare has the ability to output the original list of model equations
Stéphane Adjemian's avatar
Stéphane Adjemian committed
1041
to a LaTeX file, using the ``write_latex_original_model``
1042 1043 1044
command, the list of transformed model equations using the
``write_latex_dynamic_model command``, and the list of static model
equations using the ``write_latex_static_model`` command.
1045

1046
.. command:: write_latex_original_model (OPTIONS);
1047

Stéphane Adjemian's avatar
Stéphane Adjemian committed
1048
    |br| This command creates two LaTeX files: one
1049
    containing the model as defined in the model block and one
Stéphane Adjemian's avatar
Stéphane Adjemian committed
1050
    containing the LaTeX document header information.
1051

1052
    If your ``.mod`` file is ``FILENAME.mod``, then Dynare will create
1053 1054
    a file called ``FILENAME/latex/original.tex``, which includes a file
    called ``FILENAME/latex/original_content.tex`` (also created by Dynare)
1055
    containing the list of all the original model equations.
1056

Stéphane Adjemian's avatar
Stéphane Adjemian committed
1057
    If LaTeX names were given for variables and parameters
1058 1059
    (see :ref:`var-decl`), then those will be used; otherwise, the
    plain text names will be used.
1060

1061
    Time subscripts (``t``, ``t+1``, ``t-1``, ...) will be appended to
Stéphane Adjemian's avatar
Stéphane Adjemian committed
1062
    the variable names, as LaTeX subscripts.
1063

Stéphane Adjemian's avatar
Stéphane Adjemian committed
1064
    Compiling the TeX file requires the following LaTeX
1065
    packages: ``geometry, fullpage, breqn``.
1066

1067 1068 1069 1070 1071 1072 1073
    *Options*

    .. option:: write_equation_tags

        Write the equation tags in the LaTeX output. The
        equation tags will be interpreted with LaTeX markups.

1074
.. command:: write_latex_dynamic_model ;
1075
             write_latex_dynamic_model (OPTIONS);
1076

Stéphane Adjemian's avatar
Stéphane Adjemian committed
1077 1078
    |br| This command creates two LaTeX files: one containing
    the dynamic model and one containing the LaTeX document
1079 1080 1081
    header information.

    If your ``.mod`` file is ``FILENAME.mod``, then Dynare will create