This page documents the implementation of external functions in Dynare 4. We call external functions those functions that are not part of the small set of functions natively supported by Dynare (e.g., log, exp, etc).

Essentially, this feature allows Dynare 4 to operate on any user-defined (or built-in Matlab) function.

User Syntax

We assume that the user wants to use a function called funcname in his model. The function is supposed to be implemented through a M-file or a MEX file, located in MATLAB path (this definition includes built-in MATLAB functions).

From the mathematical point of view, this function is supposed to be of type $\mathbb{R}^n \rightarrow \mathbb{R}$ . In other words, it can accept any number of real arguments, but returns only one real argument.

The user has three options with regards to providing the derivative of the function to Dynare:

Provide no derivative. In this case, Dynare will calculate the numerical derivatives using finite differences;
Provide the first (and possibly second) derivatives in the same M-file as the function itself. The first derivative will be the second return argument (the Jacobian, in a vector) and the second derivative will be the third return argument (the Hessian, in a matrix).
Provide the first (and possibly second) derivatives in separate M-files. In this case, the only return argument to these functions will be a vector in the case of the Jacobian and a matrix in the case of the Hessian.

The keyword external_function will be used for the declaration of external functions. It accepts the following options:

name = STRING: the name of the function, which must also be the name of the M-file (or MEX file) implementing it
nargs = INTEGER: the number of arguments of the function. Defaults to 1
first_deriv_provided: tells Dynare that the M-file also returns the first derivatives, as the second output
first_deriv_provided = STRING: tells Dynare that the first derivatives of the function are provided by the M-file given as option argument
second_deriv_provided: tells Dynare that the M-file also returns the second derivatives, as the second output
second_deriv_provided = STRING: tells Dynare that the second derivatives of the function are provided by the M-file given as option argument

This keyword would be used in the first part of the MOD file (where variable declarations are), possibly several times if several external functions are used.

Since external functions are already accepted outside the MOD file without any specific declaration, we should keep the following convention: if during the parsing (inside or outside the model block), the parser encounters an unknown function name, then it should behave as if a external function declaration had been made for that function, with the number of arguments used in the construct, and without any provided derivative. Put otherwise, if the parser encounters something like funcname(x, y, z) and there is no explicit external function declaration, then it should generate an implicit external function declaration like the following:

external_function(name = funcname, nargs = 3);

Syntax examples

Declare an external function with name funcname, accepting only one argument, and whose derivatives must be computed numerically by Dynare:

external_function(name = funcname);

Declare an external function with two arguments, whose derivatives are returned as second and third output argument of the implementation:

external_function(name = funcname, nargs = 2, first_deriv_provided, second_deriv_provided);

Declare an external function with three arguments, whose first derivative is provided by M-file funcname_deriv, and whose second derivative must be computed numerically by Dynare:

external_function(name = funcname, nargs = 3, first_deriv_provided = funcname_deriv);