Currently, Dynare 4 only operates on a small set of mathematical functions in the model description (though it accepts any MATLAB function outside the model, for example in parameter initializations).

This is a regression since Dynare 3 used to be able to operate on any function.

This change was made necessary because Dynare 4 does analytical derivatives, while Dynare 3 did numerical derivatives, hence needing less knowledge about the functions.

The purpose of this page is to describe the way we can fix this regression.

We call external functions the functions which are not part of the small set natively supported by Dynare (log, exp, trigonometry...).

Proposed user syntax

We assume that the user wants to use a function called funcname in its 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.

For giving the derivatives of this function to Dynare, there are three possibilities for the user:

the user does not provide any derivative: then it is up to Dynare to call a numerical derivator
the user provides the first (and possibly second) derivatives in the same M-file than the function itself: the first derivatives will be the second return argument (in a vector), the second derivatives will be the third return argument (in a matrix)
the user provides the first (and possibly second) derivatives in separate M-files

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 (i.e. the jacobian), 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 (i.e. the hessian), 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.

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);

Treatment of Unknown Functions

Functions and their derivatives are declared by user via a keyword
Functions are *.m files or Matlab primitives or the the function is declared by the user but the derivative isn't provided we must call a numerical derivator
1. these functions have an arbitrary number of arguments
2. this can only be implemented for first or second order derivatives
3. it is necessary to know if we are dealing with first or second derivatives to call the right numerical derivator
4. the numerical derivator (jacobian or hessian) returns an array
5. each derivative is function of the derivatives of the arguments and the derivatives of the function
  - Example:
```
    F(y_1,y_2,...,y_k)
    D(F,x_i) = D(F,y_1)*D(y_1,x_i)+D(F,y_2)*D(y_2,x_i)+...D(F,y_k)*D(y_k,x_i)
    D^2(F,x_i,x_j) = D^2(F,y_1,y_1)*D(y_1,x_i)*D(y_1,x_j)+...+D^2(F,y_1,y_k)*D(y_1,x_i)*D(y_k,x_j)+..+D^2(F,y_k,y_k)*D(y_k,x_i)*D(y_k,x_j)
                     +D(F,y_1)*D^2(y_1,x_i,x_j)+...+D(F,y_k)*D^2(y_k,x_i,x_j)
```
6. because the number of arguments and derivatives are arbitrary, it is necessary to introduce some sort of array type in the parser