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. For the remainder of this wiki, we assume that the user wants to use a function called funcname in her model.

The External Function

The function can be implemented through a M-file or a MEX file (hereafter, M-/MEX file) located on the MATLAB path. NB: This 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.

There are two ways in which the user can provide the derivative of funcname to Dynare:

Provide the first (and possibly second) derivatives in the same M-/MEX 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-/MEX 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.

Further, the user has the option to provide neither the first nor the second derivative of funcname. In this case (and in the case when the first derivative is provided but the second is not), Dynare will calculate the missing derivatives numerically using finite differences methods (central differences for the Jacobian and eqs. 25.3.24 and 25.3.27 from Abramowitz and Stegun (1965), pg 884 for the Hessian);

Example

1. The case when one M-/MEX file contains the function output, its Jacobian and Hessian:

function [y df d2f]=funcname(a,b)
y=a*(b^2);

da=b^2;
db=2*a*b;
df=[da db];

d2f=[0 2*b; 2*b 2*a];
end

2. The case when there is a separate M-/MEX file for funcname and its derivative, funcname_deriv:

function y=funcname(a,b)
y=a*(b^2);
end

function df=funcname_deriv(a,b)
da=b^2;
db=2*a*b;
df=[da db];
end

User Syntax in the .mod file

The keyword external_function is reserved 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-/MEX file implementing it.
nargs = INTEGER: the number of arguments of the function. If this option is not provided, Dynare assumes nargs = 1.
first_deriv_provided: tells Dynare that the M-/MEX file specified by the argument passed to name returns the Jacobian as its second output argument.
first_deriv_provided = STRING: tells Dynare that the Jacobian is provided as the only output of the M-/MEX file given as the option argument.
second_deriv_provided: tells Dynare that the M-/MEX file specified by the argument passed to name returns the Hessian as its third output argument.
second_deriv_provided = STRING: tells Dynare that the Hessian is provided as the only output of the M-/MEX file given as the option argument.

An external_function statement must be used once for every external function referenced in the model_block. Further, the statement must be issued somewhere before the model_block. The user does not need to include an external_function statement for external functions referenced outside of the model_block.

Examples

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

external_function(name = funcname);

2. Declare an external function with name funcname, accepting two arguments, whose derivatives are returned as the second and third output arguments of the M-/MEX file funcname:

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

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

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