the-model-file.rst 441 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
        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
743
744
745
        returns the Jacobian as its second output argument. When this option is
        not provided, Dynare will use finite difference approximations for
        computing the derivatives of the function, whenever needed.
746

747
748
    .. option:: second_deriv_provided [= NAME]

Stéphane Adjemian's avatar
Stéphane Adjemian committed
749
750
751
752
753
754
        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
755
756
757
        is used in the same ``external_function`` command. When this option is
        not provided, Dynare will use finite difference approximations for
        computing the Hessian derivatives of the function, whenever needed.
758

Stéphane Adjemian's avatar
Stéphane Adjemian committed
759
    *Example*
760

761
        ::
762

Stéphane Adjemian's avatar
Stéphane Adjemian committed
763
764
765
           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);
766
767
768
769
770


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

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

Stéphane Adjemian's avatar
Stéphane Adjemian committed
775
776
777
778
779
780
781
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).
782

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


.. _param-init:

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

792
793
794
When using Dynare for computing simulations, it is necessary to
calibrate the parameters of the model. This is done through parameter
initialization.
795
796
797

The syntax is the following::

798
    PARAMETER_NAME = EXPRESSION;
799
800
801

Here is an example of calibration::

802
    parameters alpha, beta;
803

804
805
806
    beta = 0.99;
    alpha = 0.36;
    A = 1-alpha*beta;
807
808
809
810
811

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

.. matvar:: M_.params

812
    Contains the values of model parameters. The parameters are in the
Sébastien Villemot's avatar
Sébastien Villemot committed
813
    order that was used in the ``parameters`` command, hence ordered as
814
    in ``M_.param_names``.
815

816
817
818
819
820
The parameter names are stored in ``M_.param_names``:

.. matvar:: M_.param_names

    Cell array containing the names of the model parameters.
821

822
823
824
825
826
827
828
829
830
831
832
833
834
.. matcomm:: get_param_by_name ('PARAMETER_NAME');

   Given the name of a parameter, returns its calibrated value as it is
   stored in ``M_.params``.

.. matcomm:: set_param_value ('PARAMETER_NAME', MATLAB_EXPRESSION);

   Sets the calibrated value of a parameter to the provided expression.
   This does essentially the same as the parameter initialization syntax
   described above, except that it accepts arbitrary MATLAB/Octave expressions,
   and that it works from MATLAB/Octave scripts.


835
836
837
838
839
840
841
842
.. _model-decl:

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

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

.. block:: model ;
843
   model (OPTIONS...);
844

845
846
    |br| The equations of the model are written in a block delimited by
    ``model`` and ``end`` keywords.
847

848
849
850
851
    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``.
852

853
854
855
856
    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:
857

858
        MODEL_EXPRESSION = MODEL_EXPRESSION;
859

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

864
        MODEL_EXPRESSION;
865

866
867
868
869
870
871
872
    |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
873
874
875
    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
876
877
878
879
    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:
880

881
        #VARIABLE_NAME = MODEL_EXPRESSION;
882

883
884
885
886
887
    |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::
888

889
        model;
890

891
892
        [name = 'Budget constraint'];
        c + k = k^theta*A;
893

894
        end;
895

896
897
898
899
900
901
    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::
902

903
        model;
904

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

908
        end;
909

910
    More information on tags is available on the `Dynare wiki`_.
911

912
    *Options*
913

914
    .. option:: linear
915

916
917
918
919
920
        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.
921

922
    .. option:: use_dll
923

924
925
926
927
        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``
928
929
        command (see :ref:`compil-install` for more details).
        Using this option can result in
930
        faster simulations or estimations, at the expense of some
931
932
        initial compilation time. Alternatively, this option can be
        given to the ``dynare`` command (see :ref:`dyn-invoc`). [#f2]_
933

934
    .. option:: block
935

936
937
938
939
940
        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.
941

942
    .. option:: bytecode
943

944
945
946
        Instead of M-files, use a bytecode representation of the
        model, i.e. a binary file containing a compact representation
        of all the equations.
947

948
    .. option:: cutoff = DOUBLE
949

950
951
952
        Threshold under which a jacobian element is considered as null
        during the model normalization. Only available with option
        ``block``. Default: ``1e-15``
953

954
    .. option:: mfs = INTEGER
955

956
957
958
        Controls the handling of minimum feedback set of endogenous
        variables. Only available with option ``block``. Possible
        values:
959

960
        ``0``
961

962
963
            All the endogenous variables are considered as feedback
            variables (Default).
964

965
        ``1``
966

967
968
969
970
971
            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.
972

973
        ``2``
974

975
976
977
978
979
            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.
980

981
982
        ``3``

983
984
985
986
987
            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.
988
989
990

    .. option:: no_static

991
992
993
        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
994
995
    .. option:: differentiate_forward_vars
                differentiate_forward_vars = ( VARIABLE_NAME [VARIABLE_NAME ...] )
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017

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

1019
    .. option