16. Questions and Answers

What is the order of derivative objects and results or parameters in a function call?

With admDiffFor and admDiffVFor the order of derivate objects and results or parameters in a function is: The derivative object preceeds its corresponding active result or active parameter. For example: Let [y,w]=f(a,b,c) be a function having the parameters a,b, and c and the results y and w. Assume that the parameters a and c and the output y are active. The correct call of this function is: [g_y,y,w]=f(g_a,a,b,g_c,c).

With admDiffRev derivative outputs (adjoints of input parameters) get prepended to the output parameter list and derivative inputs (adjoints of output parameters) get appended to the input parameter list.

Is the derivative assignment put in front of the orginial expression?

admDiffFor: The derivative assignment is put in front of the original assignment usually. The exceptions to this rule are assignments with LHSs with the backslash operator or other builtins with BMFUNC DIFFSTO rules that use the original expression's result ($$). In this case the original expression is assigned to a temporary variable which the derivative expression can use, and after that the temporary expression is assigned to its original variable.

admDiffVFor: Only when an active variable is assigned a constant (non-active) value is the corresponding d_zeros assignment placed after the original assignment, so the RHSs value can be used there.

Which prefix do derivative objects get?

admDiffFor: Derivative objects are prefixed with 'g_' by default. This may be changed using the parameter gradprefix.

admDiffVFor: Derivative objects are prefixed with 'd_' by default. This may be changed using the parameter forward-deriv-variable-prefix.

admDiffRev: Derivative objects are prefixed with 'a_' by default. This may be changed using the parameter rev-prefix.

Which prefix do differentiated functions get?

admDiffFor: A differentiated function gets the prefix 'g_' by default. This may be changed using the parameter option funcprefix.

admDiffVFor: Derivative functions are prefixed with 'd_' by default. This may be changed using the parameter forward-deriv-function-prefix.

admDiffRev: Adjoint functions are prefixed with 'a_' by default. This may be changed using the parameter rev-prefix. Recording (forward-sweep) functions are prefixed with 'rec_' by default, changeable using the parameter rec-prefix. Returning (reverse-sweep) functions are prefixed with 'ret_' by default, changeable using the parameter ret-prefix.

How can I put each generated function into a different file

With admDiffVFor and admDiffRev all generated functions are placed into a single file. You can set the parameter output-mode to split-all to change that. Be careful when using this as this may in certain circumstances overwrite some of your existing files.

How can I avoid having to use use-subsref and use-subsasgn

In some situations, admDiffVFor will only work if the parameters use-subsref and/or use-subsasgn are turned on. Since these options make the AD code much slower, it may be worth the effort to change the code in such a way that they are not necessary any more.

One such situation that may cause trouble is when you have a row vector and in your code index into it using a single index, like this: v(i), or like this: v(1:n). Try to change these expressions to v(1,i) and v(1,1:n), resp.

How can I achieve a better performance

There are several things you can try in order to achieve a better performance:

• First of all: try to write vectorized code.
• When you have a rather small function, then the high-level drivers such as admDiffFor and adnDiffRev may require more time for performing all the useful checks and tests than for the actual derivative computation. Most of these checks can be turned off, using the option nochecks:

    adopts = admOptions();
    adopts.nochecks = true;
  

  This is a shortcut option with the same effect as setting the following options:

    adopts.forceTransform = -1;
    adopts.checkDependencies = false;
    adopts.checkResultSizes = false;
    adopts.checknargs = false;
    adopts.checkoptions = false;
  

  Not however that this will in particular turn off the check whether the differentiated files are up to date. So it may be wise to run a dummy call without option nocheck before turning it on.
• When using admDiffFor, try the different derivative classes (see The derivative classes) to see which one is the fastest for you.
• When you compute a Jacobian, see if it is sparse, so you might be able to apply compression. In exceptional cases, compression with the reverse mode may be an idea, if the Jacobian can be better compressed along the rows. Try admColorSeed with both the pattern and the transposed pattern to see if it makes a difference. Certain Jacobian with peculiar sparsity patterns (e.g. array shape) can be efficiently computed by a combination of the FM and RM, though you would have to do that manually.
• When the NDD is low, but > 1 (for example after applying compression), and you are using admDiffFor or admDiffRev, you may try whether strip mining is faster than vector mode. The reason is that vector mode needs the derivative classes, which are rather slow. The only amortize when there is a certain minimum NDD. There are two ways to do this: Either set the option scalarModeSwitch to some number higher that your NDD or you set the option derivClassName to 'scalar_directderivs'.
• When using admDiffRev, try if in your code you can turn off the use of wrapper functions that deal with scalar expansion and implicit reshapes.

    adopts = admOptions();
    adopts.parameters.allowArrayGrowth = 0;
    adopts.parameters.adjointReductions = 'no';
    adopts.parameters.adjointReshapes = 'no';
    adopts.parameters.avoidVarargFunctions = 1;
  

How can I clean up the files generated by ADiMat

You can use the function admClean (cf. admClean).

How can I check derivatives for correctness

You should always check the AD derivatives that come out of ADiMat for correctness, at least initially and then after major changes to your code. We suggest that you test all three AD drivers and also the FD and complex variable method drivers (see High level user interface) to compute the desired derivative. Then compute the relative error between any two of the resulting Jacobians J1 and J2 like this:

norm(J1 - J2) ./ norm(J1)

The relative error between any of the AD and the complex variable method derivatives should be very small, while the relative error between one of these and the FD derivatives have about the size of sqrt(eps). You can use the functions admAllDiff and admAllDiffMatrix for this. See also our example notebook on this topic.

I am behind a web proxy which blocks me from accessing the transformation server. What can I do?

The ADiMat transformation server has been configured to listen also on the port 10443 for SSL connections in addition to the standard port 443. In some cases using this port allows you to get around the proxy.

You can tell adimat-client to use this alternative port using one of these methods:

• On the command-line, pass the option --server=https://adimat.sc.informatik.tu-darmstadt.de:10443/ to adimat-client.
• Within Matlab, you can add this same option to the flags field of admOptions.
• Or you can set the server URL using the field server of admOptions.

How can I tell ADiMat to ignore unbound identifiers?

You can give the flag -b to adimat-client, which will cause it to not generate errors when it encounters an unbound identifier. Unbound identifiers are most likely toolbox functions that ADiMat does not know. These may also include functions from ADiMat's runtime environment.

I want to send ADiMat generated code to the server again, but I get errors

ADiMat generates code which may contain many calls to various runtime functions. These have often not been added to the function data base yet. Hence you will get errors complaining about unbound identifiers when you try to tranform this code again.

See the previous question on how to suppress these.