9. Usage of classic adimat

The classic adimat binary is still in use on the transformation server and will be available to those users who obtain a standalone version.

The options and flags of the adimat program as they are listed below can be specified using transformation parameters. Basically, fields of the corresponding names can be found in the parameters sub struct of admOptions (see Transformation parameters). Parameters can also be given in the command line to adimat-client. In general, an option like --gradprefix=GG_ should be specified to adimat-client as -s gradprefix=GG_. A flag --tmpclear should be specified to adimat-client as -s tmpclear=1 or just -s tmpclear. You can also use a prefix no to negate a flag. That is, -s tmpclear=0, -s notmpclear, -s notmpclear=1, and even -s nonotmpclear=0, are all equivalent.

The usage of adimat is:

adimat [options] inputfilename

9.1 adimat Options

-h, -?, --help

Prints a help message and exits the application.

--version

Print the current version of ADiMat.

-v<N>, --verblevel=<N>

Set the verbositylevel to <N>(<N>=6) ADiMat's output routines know a level based system for issuing messages depending on how much the user wants to know. The availabe level range from 0 -> no output at all upto 12 -> output every single step. The table below gives a summary of the available outputlevels:

0

no output at all

1

output only critical errors (like no memory,...)

2

errors which can be recovered by stepping over the erroneous instruction, but this may cause more errors.

4

write warnings for everything that is not clear to ADiMat or may result in unexpected programbehaviour

6

(the default) print a small version information at programstart and some statistics at programmtermination

8

print every major program step

10

print every minor program step

12

prints most information. This will print a real lot of lines. Do not blame me, if it clutters your screen.

The higher numbers include the lesser ones. All output is written to standard error.

-p<OUTPUTDIR>, --outputpath=<OUTPUTDIR>, [AD_OUTPUT_DIR="<OUTPUTDIR>"]

The path where ADiMat puts the augmented files. (<OUTPUTDIR>='.') ADiMats default is the local directory, but it is not really clever to use it, because ADiMat will produce a huge number of files. It may overwrite some existing files, too. Using a subdir is highly encouraged. The subdir has to exist, it will not be created.

-d<DVARLIST>, [AD_DVARS=<DVARLIST>]

Specify the list of dependent variables. This flag is only read if the inputfilename specifies a file containing a function. The flag can be used to select some or all of the variables of the result list of the function to be dependent variables. If the flag is not specified and the inputfilename specifies a function, then all results are treated to be dependent variables. The command line switch overrides the directive AD_DVARS!!!

-i<IVARLIST>, [AD_IVARS=<IVARLIST>]

Like -d but for the independent variables. All parameters are selected to be independent, if the inputfilename is a function and the flag is not given. The command line switch overrides the directive AD_IVARS!!!

-I<PATH>

Add the directories given in <PATH>to the path, where ADiMat looks for matlab m-files. The option -I<PATH> may occur more than once. The valid paths of each occurrence of -I<PATH> will be appended to the list of directories scanned for missing functions. Invalid paths will be discarded. Environments variables are valid and will be expanded. The special tag '@BUILTINS' may be inserted anywhere, but it is not allowed to habe more than one occurrence of it in the list. <PATH> may contain multiple directories seperated by colons ':'. (<PATH>='.:@BUILTINS')

--noforwardvarresolv, [GLOBAL NOFORWARDVARRESOLVE]

This options prevents that ADiMat looks forward in the code to learn, if an unknown identifier is a variable. For example in: 'b=a; a=5;' the 'a' in 'b=a' is bound to the same 'a' as in 'a=5'. This, of course, is an error in this case, because 'a' was not defined before use. The flag exists for the rare situations, where a function has the same name, like a variable and the variable is defined later on. Consider this bad programming style.

--writescopefile, [GLOBAL WRITESCOPEFILE]>

Write the file '<OUTPUTDIR>/adimat.dbg' which contains information about the scopes and the identifiers bound in them. The file contains a history of the identifier resolution process. This file is for debugging purpose only, it is not needed by the differentiated program. If this option is available your version of ADiMat was compiled with the DEBUG-symbol set.

--nobuiltins, [GLOBAL NOBUILTINS]

Skip any builtin-files. Even if there is a different builtinfilelist given, the builtin-files and '%ADiMat B*'-directives in the code are ignored. Use this option with great care. The builtin-files define many Matlab-functions that are used often (see section builtins for further information).

--builtinspath=<BUILDINSPATH>

This path is scanned for the builtins-declaration file 'ADiMat.amb'. Specifing a new path discards the old one. Look at builtins for a more detailed description. (<BUILTINSPATH>='${ADIMAT_HOME}/share/adimat:~/. adimat:.').

--exportctvcg=<FNAME>

Write the calltree of the functions to the file <FNAME>. The file will be written to the <OUTPUTDIR>. No absolute paths are possible, only paths relative to the <OUTPUTDIR>. The calltree is stored using the vcg format. The file gets the suffix '.vcg'. See section calltree for more information.

--exportctsimp=<FNAME>

Write the information gathered about caller-callees dependencies between function (the calltree) to the file <FNAME> in a simple text fashion. This file is intended for use with other programs, use --exportcttxt for a more human readable format. No suffix is appended to the filename. The file is put into the <OUTPUTDIR>. No absolute paths are allowed here. See section calltree for more information.

--exportcttxt=<FNAME>

Write the calltree to the file '<OUTPUTDIR>/<FNAME>' in a human readable format. No suffix is appended, but '.txt' is proposed here. See section calltree for more information.

--exportdgvcg=<FNAME>

The dependencies between all variables of the current project are written to the file '<OUTPUTDIR>/<FNAME>'. The filename-suffix '.vcg' is ensured. The variable dependency graph is only available in this format, because it is huge most of the time and other formats are not applicable. For documentation of the vcg format see section VCG.

--nolocalmfiles, [GLOBAL NOLOCALMFILES]

Files that contain only statements and no function declarations are normaly copied into the scope they are called from and the file is renamed to meet the pattern: <calling_function_name>_<original_filename>. However, in some circumstances this may not be desired. Using this switch, will prevent the localization of these files. But make sure, that no activ variables are used or altered in the command-file. (The default is to use local files.)

--envoutput, [GLOBAL ENVOUTPUT]

This option writes more information about each identifier into the m-files written by ADiMat. The files are no longer Matlab-complient than. This option is for debuging purpose only. If this option is available your executable was compiled using the DEBUG-flag.

--gradprefix=<PREFIX>

This prefix is added to each active variable. The prefix is used for variables, when ADiMat is in forward mode. (<PREFIX>='g_')

--hessprefix=<PREFIX>

If the second order forward mode flag is set, then this prefix is used to preceed the variables that store Hessians. (<PREFIX>='h_')

--funcprefix=<PREFIX>

The prefix is added to each function that is augemented in forward mode. There is no distinction between functions that are differentiated once or twice. They all get this prefix. (<PREFIX>='g_')

-f, --forward-mode, [GLOBAL FORWARD-MODE]

Differentiate using the forward mode. For the reverse mode you have to use the command admrev.

-r, --reverse-mode, [GLOBAL REVERSE-MODE]

Differentiate the functions using the reverse mode. This mode is not available yet in the adimat binary. For the reverse mode source transformation you have to use the command admrev.

-m, --hybrid-mode, [GLOBAL HYBRID-MODE]

Differentiate the project using forward and reverse mode interchangeably. The decision when to switch modes is not yet defined. This flag is non-functional. It is defined to prevent future misuse. The mode will be forced to forward even if this flag is used.

--outl_comp=<NUM>

Set the limit when a subexpression is truncated to the number given by <NUM>. See section outlining for further information. (<NUM>=1)

--nooperoptim, [GLOBAL NOOPEROPTIM]

During differentiation operations like a*b*c are joined to a single subroutine call times3(a, b, c) if a derivative object is involved. This flag prevents the optimization.

--nolocalcse, [GLOBAL NOLOCALCSE]

ADiMat splits up expressions that consist of more than one operation into many small expressions. Each expression is assigned to a temporary variable. While ADiMat operates on one such big expression it may encounter, that the same small expression is found several times. Instead of recomputing it each time, the expression is evaluated only once and the temporary variable is inserted multiple times into the expression. This switch turns this behaviour off. It may be of use if a function that manipulates a global variable is called multiple times.

--noglobalcse, [GLOBAL NOGLOBALCSE]

Similiar behaviour like --nolocalcse, but this time not only the expressions, which are generated during splitting the bigger expressions are taken into account. ADiMat will look at all expression in the program and replaces expressions which compute the same values with a temporary variable. The value of the temporary variable is then computed only once. This feature is switched off, whenever the flag --nolocalcse or its corresponding directive is used. Use this flag, if you use functions which have sideeffects and you encounter a wrong program behaviour after differentiation. !!! This flag is default currently due to a deficiency in the implementation. !!!

--globalcse, [GLOBAL GLOBALCSE]

Explicitly switch on global common subexpression elimination. Danger!!! The algorithm is buggy. Use at your own risk.

--noloopsaving, [GLOBAL NOLOOPSAVING]

ADiMat uses so called loopsaving operators when invoked without this flag. A loopsaving operator enables faster derivative computation, because several loops are joined togehter into one loop, therefore reducing the number of cycles needed. It is usually not a good idea to switch of the feature, because the differentiated code will perform badly then.

--nooverwrtchk, [GLOBAL NOOVERWRITINGCHECK]

Prevents "update" of variables. An expression v=v*...; is called an update of v. This is a bad idea, because v is most likely used in the derivative computation of g_v=.... The outcome of the expression will be assigned to a temporary variable. The temporary will be assigned to v in a successive statement. This switch turns off the check for variable updates. Again, be carefull if you use this switch.

--2ndorderfwd, [GLOBAL SECONDORDERFWDMD]

Insert statements to compute second order derivative using forward mode. In fact, the routines to compute first order derivatives are simply repeated once more.

--parentcheck, [GLOBAL PARENTCHECK]

Switch on parent checking in AST. This is flag is available only, if ADiMat was compiled with DEBUG-support. The check is done directly after all files are read.

--canonparentcheck, [GLOBAL CANON_PARENTCHECK]

Check that the AST is correctly linked. The check is applied after code canonicalization. Debugging.

--postparentcheck, [GLOBAL POST_PARENTCHECK]

Check correct linking of the AST after augmentation and shortly before output. Debugging.

--allparentchecks

Use all of the above checks. This flag is available only, if ADiMat was compiled in DEBUG mode.

--noscalarfolding, [GLOBAL NOSCALARFOLDING]

Suppress folding of constant real scalar expressions. Scalarfolding examines expressions and computes the result of constant expressions, like 3+4. This option disables all folding of scalar values.

--noprescalarfolding, [GLOBAL NOPRESCALARFOLDING]

Suppress scalar folding before the augmentation step.

--nopostscalarfolding, [GLOBAL NOPOSTSCALARFOLDING]

Suppress scalar folding after the augmentation step. It is not advisable to switch of scalarfolding, because ADiMat will generate some constant expressions, e.g. 2*x^(2-1)*g_x for the derivative of x^2, where a constant term could be eliminated. Use this switch if you believe, that ADiMat does incorrect folding.

--noconstfoldmult0, [GLOBAL NOCONSTFOLDMULT0]

Suppress folding of expressions with one factor being zero. ADiMat usually folds products of the kind bar= foo*0 to bar= 0. In some special, and seldom cases this may be undesireable. E.g. if foo is a function call having side effects.

--nonargsupport, [GLOBAL NONARGINMAPPER], [GLOBAL NONARGOUTMAPPER]

Suppress the generation of mapping arrays for nargin and nargout identifiers. In Matlab a function can check how many arguments are set by the calling context by checking the nargin identifier. During augmentation the parameter list is changed. The mapping arrays take care about mapping the number of arguments correctly to the number of arguments the code expects without the derivative objects in the parameter list. Usually there is no need to deactivate generation of narg-mapper.

--notmpclear, [GLOBAL NOTMPCLEAR]

ADiMat generates clear instructions for temporary variables, that are inserted by ADiMat itself. This conserves memory and speeds up computation, because Matlab's workspace size is smaller. It is usually a bad idea to switch off the generation of these clear commands, but it may be necessary, if temporary variables are cleared, that ought to exist longer. Normally this occurs only, if some tricky programming is used. Note, these clear commands only free memory of temporary variables introduced by ADiMat.

--visitfwdmd, [GLOBAL VISITFWDMD]

This is a new implementation of the forward mode differentation approach of AD. It is currently in beta state, but enables the use of more complex source code analysis and application of replace actions for toolbox-functions. This is the default. The flag is present for backward compatibilty and will be deleted in future versions.

--novisitfwdmd, [GLOBAL NOVISITFWDMD]

Switch back to old AST-driven differentiation of AD. Beware, this mode is not able to different every Matlab-program. It is not advised to switch off visitfwdmd. If you do not know what we are talking about, then do not use this flag.

--no0pow0check, [GLOBAL NOZEROPOWZEROCHECK]

If Matlab has to compute x^y where x and y are zero, then the result is set to 1. This behaviour is choosen by Matlab. To mimick this behaviour correctly, ADiMat has to check if 0^0 operations occur and set the derivative at these entries to 0.0. This flag prevents ADiMat from inserting the code executing these checks. If you know, that your code never computes 0^0, then you may switch off generation of this code. But note, that the derivative code may possibly compute incorrect derivatives (NaN values!). If you get NaN's and have used this flag, then try again without the flag.

--nosigensure, [GLOBAL NOSIGNATUREENSURE]

If functions are called by distinct functions using varying parameter lists, then ADiMat computes the transitive closure of all variables that need derivative objects associated to it. For most functions the sets of variables that need derivative objects are equal, but in some cases the sets differ and dummy derivative objects and results have to be inserted to call the function correctly. This switch prevents ADiMat from inserting these dummy derivative objects and the dummy results.