macroprocessor.tex 17.5 KB
Newer Older
1 2 3 4
\documentclass{beamer}
\usepackage[utf8]{inputenc}
\usepackage{amsmath}

5
\usetheme{Boadilla}
6 7

\title{The Dynare Macro-processor}
8
\subtitle{Dynare Summer School 2013}
9
\author{Sébastien Villemot}
10
\institute{CEPREMAP}
11
\date{June 28, 2013}
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36

\AtBeginSection[]
{
  \begin{frame}
    \frametitle{Outline}
    \tableofcontents[currentsection]
  \end{frame}
}

\begin{document}

\begin{frame}
  \titlepage
\end{frame}

\begin{frame}
  \frametitle{Outline}
  \tableofcontents
\end{frame}

\section{Overview}

\begin{frame}
  \frametitle{Motivation}
  \begin{itemize}
37 38
  \item The \textbf{Dynare language} (used in MOD files) is well suited for many economic models
  \item However, as such, it lacks some useful features, such as:
39 40 41
    \begin{itemize}
    \item a loop mechanism for automatically repeating similar blocks of equations (such as in multi-country models)
    \item an operator for indexed sums or products inside equations
42
    \item a mechanism for splitting large MOD files in smaller modular files
43 44 45 46 47 48 49 50 51 52
    \item the possibility of conditionally including some equations or some runtime commands
  \end{itemize}
  \item The \textbf{Dynare Macro-language} was specifically designed to address these issues
  \item Being flexible and fairly general, it can also be helpful in other situations
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{Design of the macro-language}
  \begin{itemize}
53
  \item The Dynare Macro-language provides a new set of \textbf{macro-commands} which can be inserted inside MOD files
54 55 56
  \item Language features include:
    \begin{itemize}
    \item file inclusion
57
    \item loops (\textit{for} structure)
58
    \item conditional inclusion (\textit{if/else} structures)
59 60
    \item expression substitution
    \end{itemize}
61
  \item Implemented in Dynare starting from version 4.0
62 63 64 65 66 67
  \item The macro-processor transforms a MOD file with macro-commands into a MOD file without macro-commands (doing text expansions/inclusions) and then feeds it to the Dynare parser
  \item The key point to understand is that the macro-processor only does \textbf{text substitution} (like the C preprocessor or the PHP language)
  \end{itemize}
\end{frame}

\begin{frame}
68
  \frametitle{Design of Dynare}
69 70 71 72 73 74 75 76
  \includegraphics[width=0.95\linewidth]{new-design.pdf}
\end{frame}

\section{Syntax}

\begin{frame}[fragile=singleslide]
  \frametitle{Macro Directives}
  \begin{itemize}
77 78 79 80 81 82
  \item Directives begin with an at-sign followed by a pound sign (\verb+@#+)
  \item A directive produces no output, but gives instructions to the macro-processor
  \item Main directives are:
    \begin{itemize}
    \item file inclusion: \verb+@#include+
    \item definition a variable of the macro-processor: \verb+@#define+
83
    \item conditional statements (\verb+@#if/@#ifdef/@#ifndef/@#else/@#endif+)
84 85 86
    \item loop statements (\verb+@#for/@#endfor+)
    \end{itemize}
  \item In most cases, directives occupy exactly one line of text. In case of need, two anti-slashes (\verb+\\+) at the end of the line indicates that the directive is continued on the next line.
87 88 89 90 91
  \end{itemize}
\end{frame}

\begin{frame}[fragile=singleslide]
  \frametitle{Inclusion directive}
92 93 94 95 96 97
  \begin{itemize}
  \item This directive simply includes the content of another file at the place where it is inserted.
    \begin{block}{Syntax}
      \verb+@#include "+\textit{filename}\verb+"+
    \end{block}
    \begin{block}{Example}
98 99 100
\begin{verbatim}
@#include "modelcomponent.mod"
\end{verbatim}
101 102 103 104
    \end{block}
  \item Exactly equivalent to a copy/paste of the content of the included file
  \item Note that it is possible to nest includes (\textit{i.e.} to include a file from an included file)
  \end{itemize}
105 106 107 108 109
\end{frame}

\begin{frame}
\frametitle{Variables}
\begin{itemize}
110 111
\item The macro processor maintains its own list of variables (distinct of model variables and of MATLAB variables)
\item Macro-variables can be of four types:
112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130
  \begin{itemize}
  \item integer
  \item character string (declared between \textit{double} quotes)
  \item array of integers
  \item array of strings
  \end{itemize}
\item No boolean type:
  \begin{itemize}
  \item false is represented by integer zero
  \item true is any non-null integer
  \end{itemize}
\end{itemize}
\end{frame}

\begin{frame}[fragile=singleslide]
  \frametitle{Macro-expressions (1/2)}
  It is possible to construct macro-expressions, using standard operators.
  \begin{block}{Operators on integers}
    \begin{itemize}
131 132 133
    \item arithmetic operators: \texttt{+ - * /}
    \item comparison operators: \texttt{< > <= >= == !=}
    \item logical operators: \verb+&& || !+
134 135 136 137 138 139
    \item integer ranges: \texttt{1:4} is equivalent to integer array \texttt{[1,2,3,4]}
    \end{itemize}
  \end{block}

  \begin{block}{Operators on character strings}
    \begin{itemize}
140
    \item comparison operators: \texttt{== !=}
141 142 143 144 145 146 147 148 149 150 151 152 153 154
    \item concatenation: \texttt{+}
    \item extraction of substrings: if \texttt{s} is a string, then one can write \texttt{s[3]} or \texttt{s[4:6]}
    \end{itemize}
  \end{block}
\end{frame}

\begin{frame}[fragile=singleslide]
  \frametitle{Macro-expressions (2/2)}
  \begin{block}{Operators on arrays}
    \begin{itemize}
    \item dereferencing: if \texttt{v} is an array, then \texttt{v[2]} is its $2^{\textrm{nd}}$ element
    \item concatenation: \texttt{+}
    \item difference \texttt{-}: returns the first operand from which the elements of the second operand have been removed
    \item extraction of sub-arrays: \textit{e.g.} \texttt{v[4:6]}
155 156
    \item testing membership of an array: \texttt{in} operator \\ (example:
      \texttt{"b" in ["a", "b", "c"]} returns \texttt{1})
157 158 159 160 161 162
    \end{itemize}
  \end{block}

  Macro-expressions can be used at two places:
  \begin{itemize}
  \item inside macro directives, directly
163
  \item in the body of the MOD file, between an at-sign and curly braces (like \verb+@{expr}+): the macro processor will substitute the expression with its value
164 165 166 167 168 169 170 171 172 173 174 175 176 177
  \end{itemize}
\end{frame}

\begin{frame}[fragile=singleslide]
  \frametitle{Define directive}

  The value of a macro-variable can be defined with the \verb+@#define+ directive.

  \begin{block}{Syntax}
    \verb+@#define +\textit{variable\_name}\verb+ = +\textit{expression}
  \end{block}

  \begin{block}{Examples}
\begin{verbatim}
178 179 180 181 182 183
@#define x = 5              // Integer
@#define y = "US"           // String
@#define v = [ 1, 2, 4 ]    // Integer array
@#define w = [ "US", "EA" ] // String array
@#define z = 3 + v[2]       // Equals 5
@#define t = ("US" in w)    // Equals 1 (true)
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
\end{verbatim}
  \end{block}
\end{frame}

\begin{frame}[fragile=singleslide]
  \frametitle{Expression substitution}
  \framesubtitle{Dummy example}
  \begin{block}{Before macro-processing}
\begin{verbatim}
@#define x = [ "B", "C" ]
@#define i = 2

model;
  A = @{x[i]};
end;
\end{verbatim}
  \end{block}
  \begin{block}{After macro-processing}
\begin{verbatim}
model;
  A = C;
end;
\end{verbatim}
  \end{block}
\end{frame}

\begin{frame}[fragile=singleslide]
  \frametitle{Loop directive}
  \begin{block}{Syntax}
\verb+@#for +\textit{variable\_name}\verb+ in +\textit{array\_expr} \\
\verb+   +\textit{loop\_body} \\
\verb+@#endfor+
  \end{block}
  \begin{block}{Example: before macro-processing}
    \small
\begin{verbatim}
model;
@#for country in [ "home", "foreign" ]
222
  GDP_@{country} = A * K_@{country}^a * L_@{country}^(1-a);
223 224 225 226 227 228 229 230 231 232
@#endfor
end;
\end{verbatim}
    \normalsize
  \end{block}

  \begin{block}{Example: after macro-processing}
    \small
\begin{verbatim}
model;
233 234
  GDP_home = A * K_home^a * L_home^(1-a);
  GDP_foreign = A * K_foreign^a * L_foreign^(1-a);
235 236 237 238 239 240 241
end;
\end{verbatim}
    \normalsize
  \end{block}
\end{frame}

\begin{frame}[fragile=singleslide]
242
  \frametitle{Conditional inclusion directives (1/2)}
243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264

  \begin{columns}[T]
    \column{0.47\linewidth}
    \begin{block}{Syntax 1}
\verb+@#if +\textit{integer\_expr} \\
\verb+   +\textit{body included if expr != 0} \\
\verb+@#endif+
    \end{block}

    \column{0.47\linewidth}
    \begin{block}{Syntax 2}
\verb+@#if +\textit{integer\_expr} \\
\verb+   +\textit{body included if expr != 0} \\
\verb+@#else+ \\
\verb+   +\textit{body included if expr == 0} \\
\verb+@#endif+
    \end{block}
  \end{columns}

  \begin{block}{Example: alternative monetary policy rules}
    \scriptsize
\begin{verbatim}
265
@#define linear_mon_pol = 0 // or 1
266 267 268
...
model;
@#if linear_mon_pol
269
  i = w*i(-1) + (1-w)*i_ss + w2*(pie-piestar);
270
@#else
271
  i = i(-1)^w * i_ss^(1-w) * (pie/piestar)^w2;
272 273 274 275 276 277 278 279
@#endif
...
end;
\end{verbatim}
    \scriptsize
  \end{block}
\end{frame}

280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299
\begin{frame}[fragile=singleslide]
  \frametitle{Conditional inclusion directives (2/2)}

  \begin{columns}[T]
    \column{0.47\linewidth}
    \begin{block}{Syntax 1}
\verb+@#ifdef +\textit{variable\_name} \\
\verb+   +\textit{body included if variable defined} \\
\verb+@#endif+
    \end{block}

    \column{0.47\linewidth}
    \begin{block}{Syntax 2}
\verb+@#ifdef +\textit{variable\_name} \\
\verb+   +\textit{body included if variable defined} \\
\verb+@#else+ \\
\verb+   +\textit{body included if variable not defined} \\
\verb+@#endif+
    \end{block}
  \end{columns}
300 301 302 303 304

\bigskip

There is also \verb+@#ifndef+, which is the opposite of \verb+@#ifdef+
(\textit{i.e.} it tests whether a variable is \emph{not} defined).
305 306
\end{frame}

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
\begin{frame}[fragile=singleslide]
  \frametitle{Echo and error directives}

  \begin{itemize}
  \item The echo directive will simply display a message on standard output
  \item The error directive will display the message and make Dynare stop (only makes sense inside a conditional inclusion directive)
  \end{itemize}

  \begin{block}{Syntax}
\verb+@#echo +\textit{string\_expr} \\
\verb+@#error +\textit{string\_expr}
  \end{block}

  \begin{block}{Examples}
\begin{verbatim}
@#echo "Information message."
@#error "Error message!"
\end{verbatim}
  \end{block}
\end{frame}

\begin{frame}
  \frametitle{Saving the macro-expanded MOD file}
  \begin{itemize}
  \item For \textbf{debugging or learning} purposes, it is possible to save the output of the macro-processor
332
  \item This output is a valid MOD file, obtained after processing the macro-commands of the original MOD file
333
%  \item Useful to understand how the macro-processor works
334
  \item Just add the \texttt{savemacro} option on the Dynare command line (after the name of your MOD file)
335
  \item If MOD file is \texttt{filename.mod}, then the macro-expanded version will be saved in \texttt{filename-macroexp.mod}
336
  \item You can specify the filename for the macro-expanded version with the syntax \texttt{savemacro=mymacroexp.mod}
337 338 339 340 341 342 343 344 345 346 347 348
  \end{itemize}
\end{frame}

% \begin{frame}
%   \frametitle{Note on error messages}
% \end{frame}

\section{Typical usages}

\begin{frame}[fragile=singleslide]
  \frametitle{Modularization}
  \begin{itemize}
349
  \item The \verb+@#include+ directive can be used to split MOD files into several modular components
350
  \item Example setup:
351 352
    \begin{description}
    \item[\texttt{modeldesc.mod}:] contains variable declarations, model equations and shocks declarations
353
    \item[\texttt{simulate.mod}:] includes \texttt{modeldesc.mod}, calibrates parameters and runs stochastic simulations
354 355
    \item[\texttt{estim.mod}:] includes \texttt{modeldesc.mod}, declares priors on parameters and runs bayesian estimation
    \end{description}
356
  \item Dynare can be called on \texttt{simulate.mod} and \texttt{estim.mod}
357 358
  \item But it makes no sense to run it on \texttt{modeldesc.mod}
  \item Advantage: no need to manually copy/paste the whole model (at the beginning) or changes to the model (during development)
359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406
  \end{itemize}
\end{frame}

\begin{frame}[fragile=singleslide]
  \frametitle{Indexed sums or products}
  \framesubtitle{Example: moving average}
  \begin{columns}[T]
    \column{0.47\linewidth}
    \begin{block}{Before macro-processing}
\begin{verbatim}
@#define window = 2

var x MA_x;
...
model;
...
MA_x = 1/@{2*window+1}*(
@#for i in -window:window
        +x(@{i})
@#endfor
       );
...
end;
\end{verbatim}
    \end{block}
    \column{0.47\linewidth}
    \begin{block}{After macro-processing}
\begin{verbatim}
var x MA_x;
...
model;
...
MA_x = 1/5*(
        +x(-2)
        +x(-1)
        +x(0)
        +x(1)
        +x(2)
       );
...
end;
\end{verbatim}
    \end{block}
  \end{columns}
\end{frame}

\begin{frame}[fragile=singleslide]
  \frametitle{Multi-country models}
407
  \framesubtitle{MOD file skeleton example}
408 409
  \scriptsize
\begin{verbatim}
410
@#define countries = [ "US", "EA", "AS", "JP", "RC" ]
411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434
@#define nth_co = "US"

@#for co in countries
var Y_@{co} K_@{co} L_@{co} i_@{co} E_@{co} ...;
parameters a_@{co} ...;
varexo ...;
@#endfor

model;
@#for co in countries
 Y_@{co} = K_@{co}^a_@{co} * L_@{co}^(1-a_@{co});
...
@# if co != nth_co
 (1+i_@{co}) = (1+i_@{nth_co}) * E_@{co}(+1) / E_@{co}; // UIP relation
@# else
 E_@{co} = 1;
@# endif
@#endfor
end;
\end{verbatim}
  \normalsize
\end{frame}

\begin{frame}
435
  \frametitle{Endogeneizing parameters (1/4)}
436 437 438 439 440 441 442
  \begin{itemize}
  \item When doing the steady-state calibration of the model, it may be useful to consider a parameter as an endogenous (and vice-versa)
  \item Example:
    \begin{gather*}
      y = \left(\alpha^{\frac{1}{\xi}} \ell^{1-\frac{1}{\xi}} + (1-\alpha)^{\frac{1}{\xi}}k^{1-\frac{1}{\xi}}\right)^{\frac{\xi}{\xi - 1}} \\
      lab\_rat = \frac{w \ell}{p y}
    \end{gather*}
443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462
  \item In the model, $\alpha$ is a (share) parameter, and $lab\_rat$ is an endogenous variable
  \item We observe that:
    \begin{itemize}
    \item calibrating $\alpha$ is not straigthforward!
    \item on the contrary, we have real world data for $lab\_rat$
    \item it is clear that these two variables are economically linked
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}[fragile=singleslide]
  \frametitle{Endogeneizing parameters (2/4)}
  \begin{itemize}
  \item Therefore, when computing the steady state:
    \begin{itemize}
    \item we make $\alpha$ an endogenous variable and $lab\_rat$ a parameter
    \item we impose an economically relevant value for $lab\_rat$
    \item the solution algorithm deduces the implied value for $\alpha$
    \end{itemize}
  \item We call this method ``variable flipping''
463 464 465 466
  \end{itemize}
\end{frame}

\begin{frame}[fragile=singleslide]
467 468
  \frametitle{Endogeneizing parameters (3/4)}
  \framesubtitle{Example implementation}
469
  \begin{itemize}
470 471 472 473
  \item File \texttt{modeqs.mod}:
    \begin{itemize}
    \item contains variable declarations and model equations
    \item For declaration of \texttt{alpha} and \texttt{lab\_rat}:
474 475 476 477 478 479 480 481 482 483 484 485
    \footnotesize
\begin{verbatim}
@#if steady
 var alpha;
 parameter lab_rat;
@#else
 parameter alpha;
 var lab_rat;
@#endif
\end{verbatim}
    \normalsize
    \end{itemize}
486

487 488 489 490
  \end{itemize}
\end{frame}

\begin{frame}[fragile=singleslide]
491 492
  \frametitle{Endogeneizing parameters (4/4)}
  \framesubtitle{Example implementation}
493
  \begin{itemize}
494
  \item File \texttt{steadystate.mod}:
495 496 497 498 499
    \begin{itemize}
    \item begins with \verb+@#define steady = 1+
    \item then with \verb+@#include "modeqs.mod"+
    \item initializes parameters (including \texttt{lab\_rat}, excluding \texttt{alpha})
    \item computes steady state (using guess values for endogenous, including \texttt{alpha})
500
    \item saves values of parameters and endogenous at steady-state in a file, using the \texttt{save\_params\_and\_steady\_state} command
501
    \end{itemize}
502
  \item File \texttt{simulate.mod}:
503 504 505
    \begin{itemize}
    \item begins with \verb+@#define steady = 0+
    \item then with \verb+@#include "modeqs.mod"+
506
    \item loads values of parameters and endogenous at steady-state from file, using the \texttt{load\_params\_and\_steady\_state} command
507 508 509 510 511
    \item computes simulations
    \end{itemize}
  \end{itemize}
\end{frame}

512 513 514 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 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567
\begin{frame}[fragile=singleslide]
  \frametitle{MATLAB loops vs macro-processor loops (1/3)}
  Suppose you have a model with a parameter $\rho$, and you want to make
  simulations for three values: $\rho = 0.8, 0.9, 1$. There are
  several ways of doing this:
  \begin{block}{With a MATLAB loop}
\begin{verbatim}
rhos = [ 0.8, 0.9, 1];
for i = 1:length(rhos)
  rho = rhos(i);
  stoch_simul(order=1);
end
\end{verbatim}
  \end{block}
  \begin{itemize}
  \item The loop is not unrolled
  \item MATLAB manages the iterations
  \item Interesting when there are a lot of iterations
  \end{itemize}
\end{frame}

\begin{frame}[fragile=singleslide]
  \frametitle{MATLAB loops vs macro-processor loops (2/3)}
  \begin{block}{With a macro-processor loop (case 1)}
\begin{verbatim}
rhos = [ 0.8, 0.9, 1];
@#for i in 1:3
  rho = rhos(@{i});
  stoch_simul(order=1);
@#endfor
\end{verbatim}
  \end{block}
  \begin{itemize}
  \item Very similar to previous example
  \item Loop is unrolled
  \item Dynare macro-processor manages the loop index but not the data array (\texttt{rhos})
  \end{itemize}
\end{frame}

\begin{frame}[fragile=singleslide]
  \frametitle{MATLAB loops vs macro-processor loops (3/3)}
  \begin{block}{With a macro-processor loop (case 2)}
\begin{verbatim}
@#for rho_val in [ "0.8", "0.9", "1"]
  rho = @{rho_val};
  stoch_simul(order=1);
@#endfor
\end{verbatim}
  \end{block}
  \begin{itemize}
  \item Advantage: shorter syntax, since list of values directly given in the loop construct
  \item Note that values are given as character strings (the macro-processor does not
    know floating point values)
  \item Inconvenient: can not reuse an array stored in a MATLAB variable
  \end{itemize}
\end{frame}
568

569 570 571 572 573 574 575 576 577 578 579
% \begin{frame}[fragile=singleslide]
%   \frametitle{Possible future developments}
%   \begin{itemize}
%   \item Find a nicer syntax for indexed sums/products
%   \item Implement other control structures: \texttt{elsif}, \texttt{switch/case}, \texttt{while/until} loops
%   \item Implement macro-functions (or templates), with a syntax like:
%     \small
%     \verb+@#define QUADRATIC_COST(x, x_ss, phi) = phi/2*(x/x_ss-1)^2+
%     \normalsize
%   \end{itemize}
% \end{frame}
580 581

\end{document}