Builtin-declarations are 'equations' that define a function of Matlab and its differentiated function or code. Matlab has a set of builtin-, intrinsic- or toolbox-supplied-functions (for simplicity these functions are called toolbox-functions from now on), that are not defined in a .m-file (allthough one may exists!), but are known to the MatLab-executable. The code of these functions can not be differentiated by ADiMat, because the .m-file of these functions only contains a description (some comments) and no code. Furthermore the differentiation of such a function is done by replacing the function call using a different function (e.g. The derivative of sin(x) is cos(x)). Another way had to be choosen to specify the derivative of these functions: builtin-declarations.
A builtin-declaration specifies the signature of a function, (e.g. the
signature of the sinus is: $$=sin($1)) and the
corresponding actions of ADiMat when differentiating this function. Possible
actions are 'DIFFTO' (may also be written 'DIFFSTO'),
'REPLACE' (also 'REPL'), 'IGNORE', 'NODIFF',
'ERROR', 'WARNING', and 'SPECIAL' (also
'SPEC'). With these actions it is possible to specify the
differentiated code of a function, replace a function call to compute its
original result and derivative, ignore the function when differentiating
it, do not differentiate this function, print an error-message, add a warning
message where ever the specified function occurs, and do something not yet known
to ADiMat in the current version, respectively. The last modifier
is reserved for extensions in future versions of ADiMat. The following
sections briefly discuss the structure of the file where the
builtin-declarations are specified in and the builtin-declarations
themselves.
Starting with version 0.5 ADiMat no longer uses the .amb-files directly, but uses a preprocessed form of the builtin-declarations stored in an SQL-database. Nevertheless the .amb-files are used to build the database using the tool dbbuild. The builtin-declarations known to ADiMat prior to version 0.5 may also be used as directives in Matlab-files to differentiate (see directivebuiltindeclaration ).
The postfix '.amb' is the short form of ADiMatBuiltins. A .amb-file may contain zero (does not really make sense) or more builtin-declarations. It also may contain empty lines and comments, which will be ignored. A comment starts with a '%' and runs to the end of the line. !!! A comment starting with '%ADiMat' is not ignored, it is treated as a regular builtin-declaration and has to conform to the specification of a builtin-declaration. Whenever an error is encountred while parsing a .amb-file a message displayed and the line is ignored. The parsing of the file continues at the next line. The dbbuild tool's default is to look for the .amb-file 'ADiMat.amb' in the following path (in this order):
This section describes the syntax and keywords of builtin-declarations. First some explanations of the language used to define the syntax: Keywords and literals are written in single quotes and have to appear in the declaration without the quotes. Variable- and function-names are written: <name> and have to conform with the MatLab-identifier rules. They may begin with a character (upper- and lower-case) or an underscore followed by one or more (upper- or lower-case) characters, underscores and numbers in any order. Unquoted lowercase words represent rules that will be expanded to their contents. <NUM> represents a non-fractional number starting with one.
Describe the signature of a function.
<funcname>
<funcname>'('')'
<funcname>'('parameters')'
'$$''='<funcname>
'$$''='<funcname>'('')'
'$$''='<funcname>'('parameters')'
'['returns']='<funcname>
'['returns']='<funcname>'('')'
'['returns']='<funcname>'('parameters')'
A function signature specifies the name of the function and the number of its return arguments and parameters. Optionally a type may be specified with each return argument and parameter. A function name may be followed by an optional parameterlist. This list may be non-existent, that is no parentheses are specified at all, an empty list may be specified, that is empty parentheses are following the function name, or parameters are specified between the parentheses. A parameter is specified using a '$'-sign followed by a non-fractional number. The counting starts with one and has to be specified. A function using one parameter has to specify the parameter '$1'. If more than one parameter is used, the parameters have to be numbered consecutively. The symbol '<NUM>' in the syntax diagram below denotes the highest number of the parameters. The symbol '$#' denotes a variable number of arguments. Any number of arguments may be assigned to this symbol including zero. The last two lines of the syntax diagram below denote the way of specifying a number of arguments that have to be specified for this particular function.
$1
$1, ..., $<NUM>
$#
$1, $#
$1, ..., $<NUM>, $#
These are valid function-signatures:
$$= g($1, $2:real)
f1
[$$1:string, $$2]=
example($1:matrix)
[$$#]=varargout_function($1)
printf($1:string, $#)
Define what code to insert when differentiating the corresponding function.
The code in a actionstring has to be valid Matlab-code. Expressions
starting with a '$' are replaced. The following table gives the
'$'-expressions and what is substituted for them.
| '$'-expression | substitute |
| $<NUM> | Is substituted by the <NUM>'s argument of the function. |
| $@<NUM> | Is substituted by the derivative of the argument $<NUM>. |
| $$<NUM> | Is substituted by the <NUM>'s result of the original expression. |
| $$@<NUM> | Is substituted by the identifier of the derivative of the <NUM>'s result (only applicable with REPLACE action, error else). |
| $TMP<NUM> | Is substituted by a temporary variable that is unique for the difftostring of the current expression. Allthough not forced, this symbol make sense in REPLACE actions only. |
| $@TMP<NUM> | Is substituted by the derivative of the <NUM>'s temporary variable. An association by name is done to the <NUM> temporary variable. It is recommended that derivatives of temporary variables are referred to by this symbol. Allthough not forced, this symbol make sense in REPLACE actions only. |
| $# | Is substituted by the arguments, that are associated to the varargin. |
| $@# | Is substituted by the list of derivatives of the arguments, that are associated to the varargin. E.g.: g_x, g_y if x, y is bound to $#. |
| $@m# | Is substituted by the list of derivatives followed by their original result. E.g.: g_x, x, g_y, y if x, y is bound to $#. |
| $$# | Is substituted by the list of results, that are associated to the varargout. |
| $$@# | Is substituted by the list of derivatives of the results, that are associated to the varargout. E.g. g_r, g_y if r, y is associated to $$# |
actionstring is not really a string. No doublequotes are allowed
around it. A doublequote within it will start a string, that has to end with
another doublequote in the same difftostring.
Look at BMFUNC examples for some applications.
The names of all available types and their meaning.
'real'
'complex'
'scalar'
'matrix'
'generic'
'string'
'boolean'
'function'
These identifiers represent simple types. 'real' and 'complex' type a parameter as a scaler real or complex number. The type 'scalar' is an alias for 'complex', because every real number also is a complex number. 'scalar' was introduced to let the user express his intention to specify one single number more precisely. 'matrix' types a real or complex matrix. There is no distinction between these two kinds, not yet. 'generic' types everything that is not explicitly typed. A generic parameter accepts every kind of data. 'real', 'complex', 'scalar', 'matrix', 'boolean', 'function' and 'string' are all accepted by a generic-typed parameter. 'string' is a number of characters in single-quotes. A 'boolean' only knows the two boolean-values true and false. A 'function'-typed parameter accepts a functionreference (the @-operator applied on a functionname).
Look at funcsig examples for some applications.
Declare a variable.
'BVAR' <varname>
'BVAR' <varname>':'type
Declare a variable. If the type is omitted 'generic' is used. This directive is used seldom. It is used however to spefify some constants like 'pi' or 'NaN' to be introduce them to ADiMat in a quick way.
BVAR test
BVAR name:string
BVAR pi:real
Declare a builtin MatLab function and its behaviour on differentiation.
'BMFUNC' funcsig 'DIFFTO' actionstring
'BMFUNC' funcsig 'DIFFSTO' actionstring
'BMFUNC' funcsig 'REPLACE' actionstring
'BMFUNC' funcsig 'REPL' actionstring
'BMFUNC' funcsig 'IGNORE'
'BMFUNC' funcsig 'NODIFF'
'BMFUNC' funcsig 'ERROR' errormsg
'BMFUNC' funcsig 'WARNING' warningmsg
'BMFUNC' funcsig 'WARN' warningmsg
'BMFUNC' funcsig 'SPEC' eol
The BMFUNC-directive declares a function specified by funcsig to be
built into Matlab. (look at
funcsig
for more information about specifying function-signatures).
A 'BMFUNC'-directive has two parts:
funcsig is to be differentiated.
The possible actions are:
The Matlab-expression
specified by the actionstring is inserted into the code where the
derivative of the function specified by funcsig is needed. Look at
'actionstring' for the specification of an
actionstring.
The call to the function
specified by funcsig is deleted from the statement-list during
differentiation and substituted by the actionstring. For correct
program behaviour the actionstring has to contain a semantically
identical expression. That is, the original results have to contain the same
values as in the undifferentiated program. This action is used to make use of
functions, that compute additional information needed for the differentiation,
but that is not yet required by the code. A REPLACE action may consist of more
than one line of code, where a single \ at the end of a line acts as a
line-continuation marker. The REPLACE action is available since ADiMat version
0.5 and in the dbbuild tool only. I.e. it can not be used as a directive!
The function declared by funcsig is not
differentiated. It will occur in the differentiated code the same way like in
the undifferentiated code (e.g. 'BMFUNC $$=real($1) IGNORE'
corresponds to 'BMFUNC $$=real($1) DIFFTO real($1)').
The function declared by funcsig is not differentiable. When trying to differentiated it, ADiMat will stop with an error. The function declared by funcsig may be safely used in code-fragment that are not differentiated.
Similar behaviour like 'NODIFF', but 'errormsg' is printed instead. 'errormsg' is a doublequoted string that may contain some special tokens:
the function-name,
the filename,
the pathname,
the linenumber where the function occured,
the character where the function occured.
The message given by
warningmsg is printed during augmentation time and inserted into the
output source code as comment. A WARNING action may be added to every other
action including itself to issue the message given. A WARNING acition is added
to another action by specifying a builtin-declaration with exactly the same
funcsig and giving the WARNING message as action before the
builtin-declaration the WARNING message it to be added. It is
not possible to generally add a WARNING message to every occurrence of
a function by specifying a more general signature or the most general signature
[$$#]= somefunc($#).
The warningmsg may contain the same $-tokens like the
errormsg.
Is ignored currently. The spec-action is for future enhancements of ADiMat. All builtin-declarations that use this action produce a warning and are treated as if 'IGNORE' is specified instead. The line is read until its end and the contents is discarded.
BMFUNC $$:real=sin($1:real) DIFFSTO cos($@1)
BMFUNC $$:real=real($1:scalar) IGNORE
BMFUNC $$=abs($1) NODIFF
BMFUNC nonlinear($1) ERROR "Function: $n used in file $f line $l: \n Function: is nonlinear -> not differentiable."
BMFUNC $$=max($1) REPLACE {$$1, $TMP1}= max($1);\
if (isvector($1)) ;\
$$@1= $@1($TMP1);\
else \
$TMP2= size($1);\
$$@= $@1((0:($TMP2(2)-1))*$TMP2( 1)+$TMP1);\
end
Declare a function that is implemented in C-code.
'BCFUNC' funcsig 'DIFFTO' actionstring
'BCFUNC' funcsig 'DIFFSTO' actionstring
'BCFUNC' funcsig 'IGNORE'
'BCFUNC' funcsig 'NODIFF'
'BCFUNC' funcsig 'ERROR' errormsg
'BCFUNC' funcsig 'SPEC' eol
Internally this directive is handle the same like BMFUNC. Except that a warning message is displayed at time, when this builtin-declaration is read. This directive exists for future-enhancment. There may be more support for C-code in future. With this version of ADiMat the user has to specify the differentiated expression for this function AND provide it. (ADiC is a tool to differentiate C-code. It is planned to automatically call ADiC whenever a differentiated C-function is needed).
(see 'BMFUNC example')
Declare a function that is implemented in Java-code.
'BJFUNC' funcsig 'DIFFTO' actionstring
'BJFUNC' funcsig 'DIFFSTO' actionstring
'BJFUNC' funcsig 'IGNORE'
'BJFUNC' funcsig 'NODIFF'
'BJFUNC' funcsig 'ERROR' string
'BJFUNC' funcsig 'SPEC' eol
Internally this directiv is handle the same as BMFUNC. Except that a warning message is displayed when the builtin-delcaration is read. This directive exists for future-enhancment. There may be more support for Java-code in future (if an ADiJava is existent then). Nowadays the user has to specify the differentiated expression for this function AND provide it.
(see 'BMFUNC example')