10. Directives

ADiMat uses command line options or directives within the parsed sources to configure its behavior. In section Usage options are described in greater detail.

10.1 adimat Directives

Directives are Matlab-comments starting with the keyword 'ADiMat'. A directive is used to manipulate the behaviour of ADiMat during its run. Nearly all directives may appear anywhere in the code. The expections from this rule are the directives starting with the prefix 'AD_'. They have to appear in the first input file given to ADiMat. An occurrence in any additional file is not forbidden, but does not make any sense. Directives used to switch a specific feature on or off are named together, seperating them using a commata. Some features of ADiMat may be selected using a command line option or a directive. The directive overrides the command line option in every case. The corresponding command line option is named with its directive, respectively. The directives available are:

AD_TOP=<FUNCNAME>

The name of the function to differentiate. The function has to be called in the current file using the variables defined as independent or dependent ones using the AD_IVARS- and AD_DVARS-directives, respectively.

AD_IVARS=<IVARLIST>

Specifies the list of independent variables. The variables with which a function is differentiated with respect to are called independent variables. Multiple variables may be named here using a commata ',' to seperate them.

AD_IVAR=<IVAR>

A synonym for the above directive which can be used in the case of a single variable being specified. ADiMat will also accept a list though, it does not engange in english grammar checking.

AD_INDEPENDENT=<IVARLIST>

A synonym for the two above directives.

AD_DVARS=<DVARLIST>

Specifies the list of output variables of the top-level function for which derivatives are sought. More than one variable may be named by seperating each using a commata ','.

AD_DVAR=<DVAR>

A synonym for the above directive which can be used in the case of a single variable being specified. ADiMat will also accept a list though, it does not engange in english grammar checking.

AD_DEPENDENT=<DVARLIST>

A synonym for the two above directives.

AD_OUTPUT_DIR="<OUTPUTDIR>"

All files that are written by ADiMat will be created in the directory given by <OUTPUTDIR>. Please note the double quotes around the <OUTPUTDIR>. These are mandatory, because without them a slash within the directory would be considered to be the division-operator. The directive is only usefull in the first file of the current project to differentiate. It is optional, but overrides the '-p' or '--outputdir' flag of the commandline.

GLOBAL FORWARDMODE, GLOBAL FORWARD-MODE

Select the forward mode of automatic differentiation. Currently this flag has a global scope, that is, specifying it anywhere will switch the mode of differentitation of the current project to forward mode. Until now no alternative modes are implemented, the directive may be obmitted therefore. But it is considered good style to specify it, if a project is to be differentiated using forward mode anytime. The command line switches overriden by this directive are: '-f', '--forward-mode', '-r', '--reverse-mode', '-m' and '--hybrid-mode'.

GLOBAL REVERSEMODE, GLOBAL REVERSE-MODE

This directive is non-functional currently. The reverse mode of automatic differentiation is not implemented yet. Specifying this flag, yields a warning, but ADiMat continues to differentiate the current project using the forward mode.The command line switches overriden by this directive are: '-f', '--forward-mode', '-r', '--reverse-mode', '-m' and '--hybrid-mode'.

GLOBAL HYBRIDMODE, GLOBAL HYBRID-MODE

Same like reverse mode. Not implemented yet. Specifying it, results in a warning. The command line switches overriden by this directive are: '-f', '--forward-mode', '-r', '--reverse-mode', '-m' and '--hybrid-mode'.

GLOBAL NOFORWARDVARRESOLVE, GLOBAL FORWARDVARRESOLVE

This directive is implemented for highly sophisticated code (also called bad style code). In Matlab it is possible to use an identifier as a function and later on to denote a variable. This is considered bad style, but supported by ADiMat. The standard behaviour of ADiMat is to look forward in the parsed code to find a defining occurrence of an identifier (that is, a left-hand side occurrence of a variable). That is, in the example 'b=a; a=3;' ADiMat will treat the first 'a' like the second one, allthough 'a' was not defined before first use. A warning will be issued. Note, it may not be an error that a variable occurs in a using context before it is defined, think about an 'if then else'- construct, where the variable is defined in the else part and used only in the then part. For common codes the directive 'GLOBAL FORWARDVARRESOLVE' is suitable, which is the default. If a code fails to be parsed, because of problems during the identification of the identifiers, try this directive. This directive overrides the command line option '--noforwardvarresolve'.

GLOBAL WRITESCOPEFILE

Write the file '<OUTPUTDIR>/adimat.dbg' which contains debuging information about the binding of identifiers. This directive is for debugging use only.

GLOBAL NOBUILTINS

Switch off the builtin system. This is no good idea! Specifying this option hinders ADiMat's use of derivative information stored in the database. None of the hunderts of builtin Matlab-functions will get differentiated, nor is it possible to specify BMFUNC ... directives.

GLOBAL NOLOCALMFILES, GLOBAL LOCALMFILES

Matlab allows two sorts of files. Files containing a function and files containing statements only. The former kind is not affected by this directive, but the later. A statement file (called m-file here) causes a problem, when called from more than one function. Different sets of variables may be active. If the directive 'LOCALMFILES' is used, which is the default, each m-file will be duplicated each time it is called from a function and the name of the calling function is concatenated to the m-file name. This localises the m-file and enables correct identification of the identifiers within the file. This techinque is in alpha-state and therefore not applicable every time. If ADiMat complains about missing identifiers and the project contains an m-file, then the directive 'GLOBAL NOLOCALMFILES' may solve the problem. This directive overrides the command line option '--nolocalmfiles'.

GLOBAL ENVOUTPUT

Each identifier in the whole program is augmented with information of its state within ADiMat. The output-files produced by ADiMat are no longer valid Matlab-files. The directive is for debuging purpose only.

GLOBAL NOOPEROPTIM, GLOBAL OPEROPTIM

These directives disable/ enable the use of an optimisation, if a binary operator is used more than once successively to compute a derivative. Assume the expression a* b* c is to be differentiated with respect to all three variables. If the flag NOOPEROPTIM is set, then the derivative looks like this: g_a* b* c+ a* g_b* c+ a* b *g_c. This code is not very efficient, because each multiplication of a derivative object g_? with any over object executes a loop for each operator. That is, for the example above 7 loops are executed (the product of a* b contains no derivative object and no loop therefore). Using the flag OPEROPTIM the above derivative expression will be replaced with a function call and the number of loops executed will be decreased significantly (currently five loops are executed, but in future versions only one loop may be executed). The default is to use OPEROPTIM, the ability to switch of the optimization of operator differentiation is merely a tool for performance-meassurement. This directive overrides the command line option '--nooperoptim'.

GLOBAL NOLOCALCSE, GLOBAL LOCALCSE

Dis-/Enables local common subexpression elimination (cse). The transformation is applied to all files if this statement is encountered anywhere. During the canonicalisation step ADiMat may encounter that one subexpression is evaluated several times. The code is transformed in a way that the subexpression is evaluated only once and stored in a temporary variable. The temporary variable is inserted into the code where a reevaluation of the subexpression would have occurred. This directive switches off/on the optimization strategy. This may be needed, if one of the subexpressions contained a function with sideeffects. This directive implies setting the GLOBAL NOGLOBALCSE directive. The directive overrides '--nolocalcse', '--localcse' and partially '--globalcse'. The latter one is only partially overriden, because switching off local cse switches off global cse, too.

GLOBAL NOGLOBALCSE, GLOBAL GLOBALCSE

Switches off/on global common subexpression elimination. ADiMat applies a common subexpression elimination algorithm to the whole code after the canonicalization step. This directive may be of use, if the code contains functions with side effects. The resulting code may be incorrect. Try this directive or the commandline option --noglobalcse to check if the cse caused the problem. This directive overrides '--noglobalcse', '--globalcse' and partially '--localcse'. The latter one is overriden partially, because global cse needs local cse.

GLOBAL NOLOOPSAVING, GLOBAL LOOPSAVING

Disables/Enables optimized operators in derivative computations. During computation of derivatives loops iterate over the number of derivatives. In the derivative of a product three loops are run. The loopsaving operator, in fact a function, combines these three loops to one single loop minimizing the computational effort. It is highly recommended to use loopsaving operators/functions. The loopsaving functions are denote by the 'ls_'-prefix. This directive overrides the '--noloopsaving' flag.

GLOBAL NOOVERWRITINGCHECK, GLOBAL OVERWRITINGCHECK

Disable/Enable the check for variable updates. A variable update is an assignment to a variable v where the variable occurs on the right- and left-hand side of the assignment. In fact, it is not only checked if an update occured, but it is also prevented that the variable v is overwritten in the same assignment it is used in. The motivation for this check is simply the fact, that within the derivative expression of the assignment, the original value of v before the update may be needed. This directive overrides the option '--nooverwrtchk'.

GLOBAL SECONDORDERFWD, GLOBAL SECONDORDERFWDMD

Compute Hessians along with the gradients. This directive switches on the computation of second-order derivatives.

GLOBAL PARENTCHECK, GLOBAL CANON_PARENTCHECK, GLOBAL POST_PARENTCHECK

Check consistency of the AST. This is a debugging directive. See --parentcheck for more information.

GLOBAL NOSCALARFOLDING, GLOBAL SCALARFOLDING, GLOBAL NOPRESCALARFOLDING, GLOBAL PRESCALARFOLDING, GLOBAL NOPOSTSCALARFOLDING, GLOBAL POSTSCALARFOLDING

Disable/Enable folding of constant real scalar expressions at transformation time. Have a look at the commandline option for more information (see --noscalarfolding). These directives override: '--noscalarfolding', '--noprescalarfolding', and '--nopostscalarfolding'.

GLOBAL NOCONSTFOLDMULT0, GLOBAL CONSTFOLDMULT0

If scalarfolding is enabled, then this directive can be used to switch off and on the folding of products whose one factor is zero. This directive overrides: '--noconstfoldmult0'.

GLOBAL NONARGINMAPPER, GLOBAL NARGINMAPPER

Omit/permit creation of nargin mappers for functions using the Matlab function nargin. See command line option nonargmapper for more information. This option allows a finer control over the created mappers, by permitting creation for nargin only.

GLOBAL NONARGOUTMAPPER, GLOBAL NARGOUTMAPPER

Omit/permit creation of nargout mappers for functions using the Matlab function nargout. See command line option nonargmapper for more information. This option allows a finer control over the created mappers, by permitting creation for nargout only.

GLOBAL NOTMPCLEAR, GLOBAL TMPCLEAR

Omit/Insert statements for clearing temporary variables inserted by ADiMat. See command line option --notmpclear for more information.

GLOBAL NOVISITFWDMD, GLOBAL VISITFWDMD

Use the old way of computing forward mode derivatives. Beware the old way is not capable of treating all Matlab constructs correctly. It is strongly advised not to use these options. The associated command line switch is --visitfwdmd.

GLOBAL NOZEROPOWZEROCHECK, GLOBAL ZEROPOWZEROCHECK

Omit/permit creation of code for computing the correct derivative for 0^0 statements. See --no0pow0check for more information.

GLOBAL NOSIGNATUREENSURE, GLOBAL SIGNATUREENSURE

Prevent/Force ADiMat from/to insert dummy objects for function's parameter/result lists that are incompatibly called from more than two functions and where the transitive closure recommends a certain signature. See --nosigensure for more information.

BMFUNC ..., BJFUNC ..., BCFUNC ..., BCOMMAND ..., BVAR ...

The builtin-declarations may be used like a directive, too. For their description look at the chapter builtins.

FUNCTION_HANDLE=<VARLIST>

Specifies a list of variables that have class function_handle in the current scope. ADiMat needs this declaration to distinguish between array indexing and calls of function handles, as both are syntactically equal. ADiMat will treat the calls to declared function handles similarly as calls to user defined functions. This means that for any function handle foo, function handles g_foo (FM), rec_foo, and ret_foo (RM) must also be available. If a function parameter is declared to be of type function_handle, ADiMat will automatically augment the signature to contain these names as well. Consider the function signature

function r = someFunc(a,b,f_ptr)

Inside the function body the directive FUNCTION_HANDLE must be used:

%ADiMat FUNCTION_HANDLE=f_ptr

If all parameters are active, in FM the signature will be augmented as follows

function [g_r, r] = g_someFunc(g_a,a, g_b,b, g_f_ptr,f_ptr)

In a driver routine, g_someFunc should be called something like that

[g_a g_b] = createFullGradients(a,b);
[g_r r] = g_someFunc(g_a,a, g_b,b, @g_otherFunc,@otherFunc)

In RM the signature will be augmented as follows

function [a_a, a_b, nr_r] = a_someFunc(a,b,f_ptr,rec_ptr,ret_ptr)

In a driver routine, a_someFunc should be called something like that

r = someFunc(a,b,@otherFunc)
[a_r] = createFullGradients(r);
[a_a a_b r] = a_someFunc(a, b, @otherFunc, @rec_otherFunc, @ret_otherFunc)

The top level derivative functions must by called with additional arguments representing function handles to the differentiated versions of function otherfunc. The function otherfunc should be differentiated with ADiMat in a separate step. There are some limitations of this directive:

• Function handles must be declared separately in each function where they occur in.
• The function the handle refers to will not be differentiated automatically.
• All arguments of calls to functions handles will be differentiated.
• The activity analysis can usually detect whether a function handle variable is active and will not differentiate it if that is not necessary. However, when a function handle is not used inside a function f, but only passed on to a subfunction g, then it may be necessary to declare the function handle variable as active using AD_ACTIVE=f_ptr to produce the correct calls to g and the augmented signature in f.

AD_ACTIVE=<VARLIST>

Specifies a list of variables that ADiMat should treat as being active in the current scope (i.e. where the directive occures). Normally any variable on a path from a independent to a dependent variable is active and this will be detected by ADiMat's activiy analysis. This directive only serves as an escape hatch should that fail somehow. There are currently two possible scenarios where this directive is useful:

• Handling function handles that are not called in a certain function but passed on as arguments to subfunction calls.
• Forcing ADiMat to produce derivative parameters for some parameters that are not active. This can be used to force ADiMat to produce a certain function signature.

% First the mandatory data
%ADiMat AD_DVARS= z
%ADiMat AD_IVARS= b
%ADiMat AD_TOP= f
% This is optional
%ADiMat AD_OUTPUT_DIR="ad_out/"
b=0.1:0.1:100;
z=f(b);

10.2 admproc Directives

As with adimat, admrev directives are Matlab-comments starting with the keyword 'ADiMat'. The remainder of the line must be a well-formed XML subtree, however.

function foo = bar(x,y,z)
%
%ADiMat <nargin>3</nargin>
  foo = x*y+z;

<parallel/>

Declare that the for loop in which the directive occurs is parallelizable. This is the case if the order of execution of the loop body does not matter. The loop iterations in the forward sweep will not be recorded, instead the loop is differentiated by performing little forward and return sweeps on the loop body during the function's return sweep.

<nargin>number</nargin>

Declare that the function in which the directive occurs will always be called with at least number arguments. This helps ADiMat to decide which of the functions arguments are to be saved for the return sweep.

<recompute>name</recompute>

Declare that the call(s) to function name in the following statement is to be recomputed in the reverse sweep. This has the effect that function name is called in the storage sweep and function a_name in the reverse sweep. The normal strategy is to save the computattions of the storage sweep, calling rec_name in the storage and ret_name in the reverse sweep.