The TAPENADE Tutorial

TAPENADE is an Automatic Differentiation Engine developed at INRIA Sophia-Antipolis by the Tropics then Ecuador teams. TAPENADE can be utilized as a server (JAVA servlet), which runs at INRIA Sophia-Antipolis. The current address of this TAPENADE server is The Tapenade server. TAPENADE can also be downloaded and installed locally as a set of JAVA classes (JAR archive). In that case it is run by a simple command line, which can be included into a Makefile. It also provides you with a user-interface to visualize the results in a XHTML browser.

Decide on the sub-program to differentiate Jump there
Specify the differentiation request Jump there
Actual Differentiation Jump there
Alternative invocation from the command line Jump there
Examine the differentiated program Jump there
Download the differentiated program Jump there
Modify the differentiation request Jump there
Examine the result of the Reverse Mode Jump there
A more complex example of the Reverse Mode Jump there
Diagnostics pages after failure Jump there
Want to install TAPENADE locally on your system? Jump there

Decide on the sub-program to differentiate: Jump to top

TAPENADE takes as input a computer source program, plus a request for differentiation. TAPENADE builds and returns the differentiated source program, that evaluates the required derivatives.

The first step in using TAPENADE is to identify and load the input source program. In normal use, you know which routine (i.e. a subroutine or function) implements the mathematical function that you want to differentiate. Let us call it the top differentiation routine. Notice that it is probably not the main program. In order to get an efficient differentiated program, the top differentiation routine, plus all the routines that can be recursively called through it, must all be given to TAPENADE. If some source routine cannot be given to the tool, ("black box" routine, for example an external or library routine), TAPENADE will make some conservative assumptions about it, which may degrade the execution time and memory consumption of the differentiated program. Of course this is a problem only if the top differentiation routine (recursively) calls this black box routine (TAPENADE provides a way to treat these "black box" routines correctly and efficiently). On the other hand, you may also give TAPENADE some routines that are not called through the top differentiation routine. TAPENADE will analyze them and maybe will issue some diagnostics about them, but they will not be differentiated. Notice also that if you do not specify the name of the top differentiation routine, TAPENADE will select one for you. It will select any one of the topmost routines in the call graph defined by the files you have given. Except in very simple cases, this might not be the choice you want, so use this default mechanism with caution.

The input source program must be written in Fortran77, Fortran95, or C. The differentiated source program will be returned using the same language as the input. Some advanced features of Fortran95, and some features of C, are not properly differentiated yet. TAPENADE will issue a warning message if one such feature is met. We are currently working to accept the missing features. More info in the FAQ. In TAPENADE, the internal representation of programs is largely independent from the actual program's language. This should make it easier for us to adapt to a new language later.

Specify the differentiation request: Jump to top

The next step is now to fill in the request for differentiation. The request for differentiation essentially composes of 4 parts: Notice that the present version of TAPENADE requires that the function you want to differentiate corresponds exactly to a program routine. Otherwise, if you want to differentiate only the function defined by a routine fragment, you must first split this routine, so that this fragment becomes a new separate routine, which will be your top differentiation routine.

Now we must select the names of the dependent output variables and the independent input variables, i.e. specify which derivatives are wanted, of which results with respect to which entries. Notice that, for TAPENADE, these two sets of variables must belong to the visible parameters of the top differentiation routine. This means either formal parameters, or declared globals such as variables in Fortran COMMON blocks. In contrast, local variables or constants are not visible parameters.

Moreover, visible parameters must all belong to a type for which differentiation is defined, i.e. REAL, DOUBLE PRECISION, or COMPLEX in FORTRAN. Leaving blank the "dependent output" field selects all visible outputs. Similarly, leaving blank the "independent input" field selects all visible inputs.

Finally, notice that if there is no dependency between the selected dependent and independent variables, the derivatives are certainly all zero. TAPENADE detects this degenerate situation statically, and this results in an empty differentiated program. This may happen for example when dependent variables depend on inputs that are all absent from the independent list. Refer to the FAQ for a more complete discussion on this. In particular, if the derivative of a variable is really required after the differentiated procedure, then add it into the dependent list, even if it is not actually modified by the procedure.

The last step is to choose between the proposed differentiation modes. To put it shortly, the "tangent mode" will build a program that, given some small variations of the independent variables, computes the resulting (1st order) variations of the dependent variables. In other words, if we call "J" the Jacobian matrix of the partial derivatives of each dependent "Yj" with respect to each independent variable "Xi", the tangent mode gives a program that computes "dY=J.dX" for each given "dX".
tangent mode

The "tangent multidirectional mode" also computes the variations of the output variables, but simultaneously for several directions in the input space. For n directions, it is therefore equivalent to running the tangent mode n times, but this is done in a single call, and is therefore more efficient because the original function is evaluated only once.

Conversely, the "reverse mode" gives a program that computes the transposed Jacobian product "J*.dY" for each given "dY". In other words, given a weighting of the dependent output variables "dY", the generated program computes the gradient of the original program.
reverse mode

You may refer to section "what is A.D." for further details.

Actual Differentiation: Jump to top

Clicking on one of the buttons "Tangent Mode", "Tangent Multidirectional Mode" and "Reverse Mode" triggers actual analysis and differentiation of the uploaded files. For large files, this may take some time before our server builds the differentiated files. Times vary with the program, but for example, it takes 1 minute and 40 seconds for a 67 thousand lines FORTRAN file, and a dozen of seconds for a 10 thousand lines. However, to protect our server, we have limited the size of the files you may differentiate with the TAPENADE server, to 100 thousand characters. There is no such limitation in the case of TAPENADE installed locally on your system.

If all goes well, a new page appears in your browser, displaying differentiation result. If something went wrong, you get a special diagnostics page, which is discussed later.

Alternative invocation from the command line: Jump to top

In the above sections of this tutorial, the illustrative example is differentiated with the TAPENADE web server. You can also use a TAPENADE installed locally on your system. In that case, differentiation is called from the command line instead of through a Web interface. This gives you access to the full set of differentiation options. In the case of an invocation from the command line, the discussion of the above sections is still valid. Only the illustration example must be executed differently.

The command name is "tapenade", followed by options and arguments. Of course your "PATH" variable must refer to the place where tapenade is installed, which is the subdirectory "bin" of the TAPENADE installation root. Environment variables TAPENADE_HOME and JAVA_HOME must be properly set. Please follow the installation indications provided in the README.html file that you got at the end of the license process.

You may type "tapenade -help" to get the complete list of options. The most important options are: The command line must also contain the names of the files that contain the original program. Order of options and file names should not matter...

Old command-line options -vars and -outvars are deprecated. They might still work, but one should rather use the current, refined, -head option. This option lets you specify one or several differentiation heads at the same time. If pi are procedures, xi are independent inputs and yi are dependent outputs of their respective procedures, then you may type e.g.:
-head "p1(x1 x3)\(y2 y5) p2(x7)\(y8 y9 y10) p4(x2 x7)\()"
or with equivalently, with slashes in the other direction
-head "p1(y2 y5)/(x1 x3) p2(y8 y9 y10)/(x7) p4()/(x2 x7)"
As can be expected, an empty list of variables means all possible dependent or independent arguments of the current procedure. A simplified syntax such as
-head "p1 p2 p4(x2 x7)\()"
means that p1 and p2 will take all inputs as independent and all outputs as dependent. One property (advantage?) of this sort of complex call is that deep procedures, called by several of the pi head procedures, will be differentiated only once, in a context which is the "envelope" of all possible individual calls. Check the FAQ for further detail.

Notice that if you just type "tapenade" with no options, you get a graphical input interface very much like the web server input interface, that lets you specify progressively your differentiation request.

Examine the differentiated program: Jump to top

The page that displays the result of differentiation is composed of several frames. The meaning of these frames is the following: Let us use this interface to examine the differentiated program (tangent mode). You may refer to section "Direct differentiation model" for a more complete description of the tangent mode of differentiation.

The interface also shows some warning and error messages, that were detected during the preliminary analyses required by TAPENADE. These messages should be examined, because some of the problems they show might lead to an incorrect differentiation. The end-user can often find out that a warning message can be neglected, but bear in mind that this is not always the case. For example, incompatible array sizes between actual and formal arguments may result in insufficient storage of intermediate values in the reverse mode. Similarly, aliasing problems (see FAQ) can lead to bad differentiation.

Download the differentiated program: Jump to top

This applies only to the web server. When called from the command line, TAPENADE automatically creates the differentiated files.

Using the Web server, if you are satisfied with the differentiated program, and you want to use it, you may cut-and-paste it. However, since this is tedious on large files, you'd better download it using the "Download differentiated file" button in the top right frame. This will download a single gzip'ed file that contains all differentiated routines. You may then include these differentiated routines in your application, feeding it with values for the derivatives of the independent input variables, and using the returned derivatives of the dependent output variables. Notice that, since differentiated routines may call original routines, this differentiated program may require linking to the original routines before running.

Modify the differentiation request: Jump to top

This applies only to the web server. When you use the command line, you just need to type a new "tapenade" command, with different arguments.

Using the Web server, you may go back to the differentiation request page by clicking on the button "Retry with the same files" in the top left frame. In the differentiation request page, you may remove and add uploaded files, and even remove them all with the "Retry with the new files" button. This should be used with caution, because uploading again is tedious. But don't worry: of course, in any case, nothing is erased on your local system!!

You may very well want to modify some of your original files, for example to fix an error or to improve differentiation result. After doing so, don't forget to use the "Remove selected files" button to remove the uploaded copy of the file, then upload the new version as indicated above.

You may also specify a different top routine, or different dependent or independent variables, and also use another mode of differentiation.

Examine the result of the Reverse Mode: Jump to top

The page that displays the differentiated program is identical for the reverse mode and the tangent mode. But of course the differentiated programs differ completely. You may refer to section "Reverse differentiation model" for a more complete description of the reverse mode.

Again, you may download the differentiated subroutines using the "Download differentiated file" button. In the reverse mode, you need to link the differentiated program to a separate library (actually two files, one Fortran: adBuffer.f and one C: adStack.c), that defines all the PUSH... and POP... routines. You need to compile both adBuffer.f and adStack.c and link them both to your final reverse-differentiated executable. You will find these files adBuffer.f and adStack.c in the ADFirstAidKit, which you may download by clicking on the "Download PUSH/POP" button in the differentiation result page, or else
Be careful when linking Fortran and C. This is highly dependent on your local system/architecture. On some systems, like ours (Linux+Gnu compilers or Solaris+Sun compilers), this is rather simple. We compile the Fortran files with:
$> f77 -c fortranfilename.f
$> f77 -c adBuffer.f
We compile the C file with:
$> cc -c adStack.c
And we do the final link by:
$> f77 fortranfilename.o adBuffer.o adStack.o -o execname
On other systems, there may be additional work. For example (thanks! Frode Martinsen, NTNU, Norway) under Windows2000, with VisualStudio and Compaq VisualFortran, you may have to add the following directives into the Fortran files that use C routines. For example if Fortran calls PUSHINTEGER4:
EXTERNAL pushinteger4_
In any case, read the documentation of your compilers, or otherwise ask your system engineer.

A more complex example of the Reverse Mode: Jump to top

Under development ... To be continued ... Under development

Diagnostics pages after failure: Jump to top

Under development ... To be continued ... Under development

Want to install TAPENADE locally on your system? Jump to top

If you are satisifed with the programs returned by the TAPENADE server, you may stick to this manner of differentiating programs. There is no algorithmic difference between the TAPENADE server and a locally installed TAPENADE, and the differentiated programs are the same.

There are some advantages in sticking to the server. First, you don't need to install, and second, you don't need to re-install to get updates of the tool.

However, there are several reasons why you might want to install TAPENADE locally on your system: In that case, download TAPENADE.

Last modified: Wed Oct 14 10:50:21 CEST 2015 by the developers of Tapenade Mail to ...