From 9451c56d3d26fc90267ba07ea3c7528eaba25bd8 Mon Sep 17 00:00:00 2001 From: Houtan Bastani Date: Tue, 9 Mar 2010 14:13:26 +0100 Subject: [PATCH] Modified manual for external functions --- doc/manual.xml | 78 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 74 insertions(+), 4 deletions(-) diff --git a/doc/manual.xml b/doc/manual.xml index 87f767f6f..f60d15025 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -746,7 +746,8 @@ end; Functions -The following standard functions are allowed in both MODEL_EXPRESSION and EXPRESSION: +Internal +The following standard functions are supported internally for both MODEL_EXPRESSION and EXPRESSION: exponential: exp(x) natural logarithm: log(x) (or equivalently ln(x)) @@ -757,10 +758,79 @@ end; gaussian cumulative distribution function: normcdf(x, μ, σ) (note that normcdf(x) is equivalent to normcdf(x, 0, 1)) -In a MODEL_EXPRESSION, no other function is allowed.This is due to the fact that the Dynare preprocessor performs a symbolical derivation of all model equations, and therefore needs to know the analytical derivatives of all the equations in the model equations. In the future, we should add support for other usual functions, and implement an interface to let the user define custom functions, for which he would provide the analytical derivatives. -In an EXPRESSION, it is possible to use any arbitrary MATLAB or Octave function, provided that this function has scalar arguments and return value. - + +External +Any other user-defined (or built-in) MATLAB or Octave function may be used in both a MODEL_EXPRESSION and an EXPRESSION, provided that this function has a scalar argument as a return value. +To use an external function in a MODEL_EXPRESSION, one must declare the function using the statement. This is not necessary for external functions used in an EXPRESSION. + + + external_function + + + + external_function + declares external functions + + + + + external_function + ( + = NAME + , + OPTION = INTEGER + + , + OPTION = NAME + + ); + + + + Options + + + = NAME + The name of the function, which must also be the name of the M-/MEX file implementing it. + + + = INTEGER + The number of arguments of the function. If this option is not provided, Dynare assumes = 1. + + + [= NAME] + If NAME is provided, this tells Dynare that the Jacobian is provided as the only output of the M-/MEX file given as the option argument. If NAME is not provided, this tells Dynare that the M-/MEX file specified by the argument passed to returns the Jacobian as its second output argument. + + + [= NAME] + If NAME is provided, this tells Dynare that the Hessian is provided as the only output of the M-/MEX file given as the option argument. If NAME is not provided, this tells Dynare that the M-/MEX file specified by the argument passed to returns the Hessian as its third output argument. NB: This option can only be used if the option is used in the same external_function command. + + + + + Description + + This command declares the external functions used in the model block. It is required for every unique function used in the model block. + + external_function commands can appear several times in the file and must come before the model block. + + + Example + + + + external_function(name = funcname); + external_function(name = funcname, nargs = 2, first_deriv_provided, second_deriv_provided); + external_function(name = funcname, nargs = 3, first_deriv_provided = funcname_deriv); + + + + + + + + Parameter initialization