The macroprocessor

Before the model parser sees a .mod file, a macroprocessor expands a small set of Dynare-compatible directives. It is a pure text-transformation pass: a directive line is one whose first non-blank characters are @#; everything else is verbatim text.

The macroprocessor preserves source positions so that error messages from the model parser point at the right place in the original file (through any number of expansion frames).

Including other files

@#include "common.mod"

Splices the contents of another file at this point. Paths are resolved relative to the including file (and then against an optional search list set with @#includepath). Circular includes are rejected.

Includes are the primary tool for factoring shared declarations and the model block out of multiple scenarios; the shipped examples under examples/ use this systematically.

@#includepath "../shared"   // add to the include search list
@#include "params.mod"

Definitions

@#define introduces a macro name (a value bound at the macro level — this is not the same thing as a model parameter):

@#define ALPHA = 0.33
@#define COUNTRIES = ["fr", "de", "it"]

With a parameter list, @#define instead binds a macro function — its body is evaluated with the arguments substituted for the parameters:

@#define spread(a, b) = a - b
@#define tagged(xs)   = [ "K_" + string(x) for x in xs ]

The right-hand side is the macro expression language (see below). Inside model text, @{...} interpolates the value of an expression at the place of the braces:

parameters alpha;
alpha = @{ALPHA};

The macro expression language

Macro expressions — in @#define, @{...}, conditions, and @#for iterables — are evaluated by a small language, distinct from the model’s own expressions (Expressions):

• Values: integers and reals, strings, booleans (true / false), lists […] and tuples (…).

• Operators: arithmetic + - * / ^ (^ is power), comparisons == != < <= > >=, membership in, and boolean && / || / !. + also concatenates two strings or two lists, and - between two lists is set-difference (drop the right operand’s elements from the left).

• Ranges: a:b is the inclusive integer range (Dynare-style), so 1:3 is [1, 2, 3].

• Indexing: xs[i] is 1-based, as in Dynare.

• List comprehensions: [ f(x) for x in xs if cond ], with one or more for / if clauses.

• Builtins: maths (exp, ln, log, log10, sqrt, the trigonometric and inverse-trigonometric functions, erf / erfc), numeric helpers (abs, sign, floor, ceil, trunc, round, mod, power, min / max, sum, length, normpdf / normcdf), type predicates (isreal, isinteger, isstring, isboolean, isarray, istuple, isempty), and the casts / constructors string, real, bool, range(lo, hi[, step]).

These fold macro values at expansion time; they are unrelated to the model-level min / max / log that act on model variables at solve time.

Conditionals

@#if SOME_FLAG > 0
  // text included when the condition is true
@#elseif OTHER_FLAG
  // ...
@#else
  // fallback
@#endif

The shorthand @#ifdef NAME / @#ifndef NAME tests whether a macro is defined, regardless of its value:

@#ifdef ZLB
  i = max(0, rho + phipi*pi + phix*x);
@#else
  i = rho + phipi*pi + phix*x;
@#endif

Loops

@#for iterates a name (or a parenthesised tuple of names) over a list (to loop over a filtered subset, filter the list with a comprehension — @#for x in [y for y in LIST if cond]):

@#for c in COUNTRIES
var(state) K_@{c};
var Y_@{c};
@#endfor

@#for (i, j) in [(1, 2), (3, 4)]
  Y_@{i}_@{j} = ...;
@#endfor

The body is expanded once per iteration with the loop variable(s) bound to the current value.

Echo and diagnostics

@#echo and @#error evaluate a message expression at expansion time: @#echo prints it (a build-time note), @#error aborts the expansion with it.

@#echo "building " + string(length(COUNTRIES)) + " countries"
@#if length(COUNTRIES) == 0
@#error "COUNTRIES is empty"
@#endif

@#echomacrovars dumps the current macro environment (every defined name and its value) — a debugging aid.

Error reporting

A macro-time error (unknown identifier, type mismatch, missing @#endif, …) is reported with the source position in the original file. Errors that surface later — at the parser or the IR — also carry the original source position through the line map: a model error that arose inside an expanded @#for body shows the loop’s iteration in the message.