|
Size: 1189
Comment:
|
Size: 3905
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| = Treatment of Unknown Functions = | 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). |
| Line 3: | Line 3: |
| I. Functions and their derivatives are declared by user via a keyword I. 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 a. these functions have an arbitrary number of arguments a. this can only be implemented for first or second order derivatives a. it is necessary to know if we are dealing with first or second derivatives to call the right numerical derivator a. the numerical derivator (jacobian or hessian) returns an array a. 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) }}} a. because the number of arguments and derivatives are arbitrary, it is necessary to introduce some sort of array type in the parser |
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 <<latex(\usepackage{amsfonts} % $\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 (the jacobian, in a vector), the second derivatives will be the third return argument (the hessian, 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, 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); }}} |
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 
. 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 (the jacobian, in a vector), the second derivatives will be the third return argument (the hessian, 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, 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);