Frequently Asked Questions on TAPENADE

Last modified: Wed Feb 8 11:09:03 CET 2012
by the developers of Tapenade

• Syst: ff (No such file or directory)
  Syst: Fortran Parser: ff No such file or directory: Interrupted analysis :
  Some required file was not found. Typically an include file was not given.
• Tool: Unknown suffix file ff
  Tool: No parser for ff. File skipped :
  TAPENADE tries to guess the language of the file from its suffix. Then it looks for a parser for this language. Either step may fail.
• File: Fortran Parser: Lexical error at line nn in file ff, ... : There is some character or word at this line nn which is not understood in the current file's programming language (e.g. Fortran).
• File: Fortran Parser: Syntax error at line nn in file ff :
  At this line is some syntax construction which is not permitted by the current file's programming language (e.g. Fortran).
• Syst: Unexpected source operator: op (xx): Interrupted analysis
  Syst: Unexpected source list: ops (xx): Interrupted analysis :
  This internal error says that one operator of the current file's programming language was forgotten in a preliminary stage of the tool. Please send us this error message so that we can fix it quickly.
• Syst: Not a tree operator: text :
  The parser has failed, and sent an incorrect tree to the differentiator. This is probably an internal error, because the normal message should be the well known "Syntax error" above.
• File: The file does not contain a top procedure : strangely enough, this message may appear as a result from a syntax error. Syntactically correct files must declare subroutines or functions. If, for any reason, no routine can be found, differentiation cannot start.
• File: Fortran Parser: Lexical error at line 1 in program.f, Unknown character 'm' in column 1 to 5 : If your program uses the free format style and the file's suffix is .f or .F, you must select fortran95 as input language with the -inputlanguage fortran95 option in order to parse it without syntax error.

• .f or .F for Fortran,
• .f90, .F90, .f95, or .F95 for Fortran90 or Fortran95,
• .c or .C for C

• In Fortran 77 :

  C $AD NOCHECKPOINT

  The C must be in column zero. There can be any number of white space (or none) before the $. Case is insignificant.


• In Fortran 90-95 :

  ! $AD NOCHECKPOINT

  The ! can be in any column. There can be any number of white space (or none) before the $. Case is insignificant.


• In "not really ANSI-" C :

  // $AD NOCHECKPOINT

  The first / can be in any column. There can be any number of white space (or none) before the $. Case is insignificant but we suggest you use upper case for a better visibility.


• In C :

  /* $AD NOCHECKPOINT */

  The initial / can be in any column. There can be any number of white space (or none) before the $. Case is insignificant but we suggest you use upper case for a better visibility.

• $AD NOCHECKPOINT, described here
• $AD II-LOOP, described here
• $AD BINOMIAL-CKP, described here
• $AD CHECKPOINT-START, described here
• $AD CHECKPOINT-END, described here

• Fortran 95 free source form : our Fortran95 handles it. Be careful with comments delimitor in the free format style: comments must start with a "!"
• modules, BLOCKDATA : accepted and differentiated.
• overloading : accepted and differentiated.
• keyword arguments and optional arguments : accepted and differentiated.
• derived types, structured types : accepted and differentiated
• SWITCH/CASE statements : accepted and differentiated
• pointers : accepted, analyzed and differentiated except in some cases in reverse mode
• dynamic allocation, malloc's, free's : accepted and differentiated in tangent mode. In reverse mode, there are some limitations (that we must document some day) e.g. corresponding allocations and frees must live in the same procedure. In any case, we believe these constructs should preferably be kept out of the computational kernel, which should contain the fragment to differentiate.
• namelist : accepted and differentiated.
• vector notation, WHERE and FORALL constructs, mask's, SUM's and FORALL's : accepted and differentiated.
• argument passing call-by-value, call-by-value-result, call-by-reference : accepted and differentiated.
• interleaving declarations and instructions, declarations with initializations : accepted and differentiated. The attached comments are approximatively re-placed at their correct positions.
• C if-expressions, e.g. x = 1 + (y<0?-y:y); : parsed but incorrectly differentiated, especially in reverse mode.
• array constructors e.g. A(:) = (/X(2)-X(1),Y(2)-Y(1)/) : arrayConstructor are parsed but incorrectly differentiated in reverse mode.

• The types and the number of arguments are deduced from the actual usages. If these usages don't match, there will be an error message.
• By default, a black-box routine is supposed to communicate with the calling code only through the calling arguments: TAPENADE supposes that the black-box routine doesn't use arguments through COMMON's and other globals. Warning: this assumption is not conservative: if the black-box routine actually refers to a global and nothing is done to tell TAPENADE about that, TAPENADE may produce wrong code!
• All actual arguments are supposed to be possibly read inside the black-box routine, except of course the returned result of a function.
• All actual variable-reference arguments are supposed to be possibly overwritten inside the black-box routine if it is an external or an intrinsic procedure. If it is an intrinsic function, we suppose no argument is overwritten.
• Any variable argument of a differentiable type is assumed to return an output value that depends (in a differentiable way) on the input value of every argument of a differentiable type.
• The differentiated routine is supposed to have the same name and shape as what would have been created by TAPENADE, i.e. BBOX_D or BBOX_B.

SPECIFYING BLACK-BOX ROUTINES IN *Lib FILES:

    tapenade -ext MyDirectory/MyAppliGeneralLib ...

TYPE ::= ident NAME
(NAME belonging to {real, complex, integer, character, boolean},
 for primitive types)

TYPE ::= modifiedTypeName(modifiers(MODIFIERS), TYPE)
(MODIFIERS being a list of mostly ident and intCst such as double or 16
 for primitive type size modifiers)

TYPE ::= arrayType(TYPE, dimColons(DIMS))
(for arrays with a fixed number of dimensions)

DIMS ::= DIM
DIMS ::= DIM , DIMS

DIM ::= dimColon(BOUND, BOUND)
BOUND ::= none()
(for an unspecified dimension lower or upper bound)
BOUND ::= intCst N

TYPE ::= arrayType(TYPE, dimColons())
(for arrays with any number of dimensions)

TYPE ::= pointerType(TYPE)
(for a pointer to another type (available in near future))

TYPE ::= void()
(void type, mostly means you don't want to care about it)

TYPE ::= metavar NAME

• It may happen that after activity analysis, TAPENADE finds out that the differentiated program does not actually need to differentiate the black-box. In other words, no argument of the black-box is active. Then you're very lucky, there is nothing you need to do!
• If the routine really has active arguments, then it may happen that it is actually a function, and a simple one so that you can define the partial derivatives of its output with respect to each input, as a simple cheap expression. This can include calls to another intrinsic. TAPENADE can use those partial derivatives both in tangent and reverse mode. Think for example of COS(X). There's only one partial derivative you need to specify which is the partial derivative of the result wrt the first (and only) argument, and this derivative is -SIN(X). To specify this, the "derivative:" entry in the "*GeneralLib" file gives a pattern that must match the original call, and patterns that defines each partial derivative. Here again, the syntax is ugly because we didn't find the time to clean it yet. Sorry again! Let's recall what we wrote for the function fbbox above:

  function fbbox
    derivative: binary(call(ident fbbox, expressions(metavar X, metavar Y)),
                       mul(realCst 2.0, metavar X),
                       expressions(binary(metavar X, none(), add(intCst 5, metavar Y)),
                                   binary(metavar Y, none(), div(realCst 1.0, metavar Y))))
  

  The parts in green are completely meaningless, but must be respected because TAPENADE expects to find them there.
  In this example, one can find, in order, the pattern that must match the actual call, therefore instantiating the metavariables X and Y, then an expression which is a common factor to all partial derivatives (which can be "none()" if there is no common factor), then the list of each partial derivative of the function's result with respect to each metavariable: for each metavariable key, there is an expression that defines the corresponding partial derivative expression, which has to be multiplied by the common factor if present. For instance in the above example, we have expressed that the partial derivative of FBBOX(X,Y) with respect to X is the expression 2.0*X(Y+5) and its partial derivative with respect to Y is the expression 2.0*X/Y. Notice that we didn't give a "deps:" entry, because the default for an intrinsic function is just what we want! More examples can be found in the F77GeneralLib file, for instance the specification of the partial derivatives of COS mentioned above.
• If there is no way to define the partial derivatives explicitly, then you must write and provide the derivative code of the black-box routine for the current differentiation mode (e.g. tangent, adjoint,...). Follow the message issued by TAPENADE to know which inputs (resp. outputs) of the black-box must be considered active. Follow the syntax that TAPENADE has chosen when generating the calls to this differentiated black-box in the differentiated code. Then simply write these differentiated external routines by hand in a separate file, using your preferred method/algorithm. When everything else fails, you may even use divided differences, always at the cost of some accuracy. Finally link the resulting code with the rest at the end of compilation time.

SPECIFYING BLACK-BOX ROUTINES WITH DUMMY ROUTINES:

z = x*y

• There could be a special purpose differentiation mode, propagating a partial Jacobian throughout the execution of the original program. This was implemented once into Odyssee, and the results were interesting, though slightly disappointing. This mode was not maintained in the next version of Odyssee (1.7). However there is a potential source of optimization coming from array analysis in regular loops, as explored in TadjoudineEyssetteFaure98
• One can compute it column by column, by repeated executions of the forward mode, one execution for each direction in the origin space. i.e. for each element of the Cartesian basis of the input space. Actually fewer directions are required when the Jacobian matrix can be shown to be sparse enough (see the litterature, e.g. the Griewank-Walther 2008 book [GrieWalt08]). This can be improved by computing the derivatives for many directions in the same run. This is the so-called vector mode or multi-directional mode, first found in ADIFOR and available in Tapenade. Multi-directional mode can exhibit some parallelism, as shown in BuckerLangMeyBischof01. As compared to ADIFOR, Tapenade brings the novelty that differentiated instructions, which are now loops, are gathered using a special data-dependency analysis. This reduces the overhead due to the numerous one-instruction loops.
• One can compute it line by line, by repeated executions of the reverse mode. Due to the intrinsic difficulties of the reverse mode, this is recommended only when the number of inputs is larger than the number of outputs, but on the other hand this can benefit from specific improvements of the reverse mode such as a bettter detection of common sub=expressions in derivatives. At the present time, Tapenade doesn't provide a multi-directional mode for the adjoint mode, but this could change if more applications would use it.

real*8 var
var = 1.0d0

validation of the differentiated programs

subroutine F(real a, real b) {
  a = 3*b
}

subroutine F_B(real a, real ab, real b, real bb) {
  bb = bb + 3*ab
  ab = 0.0
}

    cc = DCMPLX(rr,ii)

   (rr ii cc.r cc.i)

   (1 0 0 0)
   (0 1 0 0)
   (1 0 0 0)
   (0 1 0 0)

   (rrd   )   (1 0 0 0)   (rrd   )
   (iid   )   (0 1 0 0)   (iid   )
   (ccd.r ) = (1 0 0 0) * (ccd.r )
   (ccd.i )   (0 1 0 0)   (ccd.i )

      function DCMPLX_D(rr, rrd, ii, iid, cc)
      DOUBLE PRECISION rr,rrd,ii,iid
      DOUBLE COMPLEX cc, DCMPLX_D
      DCMPLX_D = DCMPLX(rrd,iid)
      cc = DCMPLX(rr,ii)
      end

   (rrb   )   (1 0 1 0)   (rrb   )
   (iib   )   (0 1 0 1)   (iib   )
   (ccb.r ) = (0 0 0 0) * (ccb.r )
   (ccb.i )   (0 0 0 0)   (ccb.i )

      subroutine DCMPLX_B(rr, rrb, ii, iib, ccb)
      IMPLICIT NONE
      DOUBLE PRECISION rr,rrb,ii,iib
      DOUBLE COMPLEX ccb
      rrb = rrb +  DBLE(ccb)
      iib = iib + DIMAG(ccb)
      ccb = DCMPLX(0.d0)
      end

    a = SQRT(b)

    ad = bd/(2.0*SQRT(b))

    ad = 0.0

      subroutine TOP(x,y)
      real x,y
      real BAD(2)
      call SUB(BAD,x)
      y = BAD(1)
      end

      subroutine SUB(BAD,x)
      real x, BAD(2)
      BAD(1) = x*x
      BAD(2) = BAD(2)*x
      end

• The activity analysis, a static analysis that finds the variables that need not be differentiated, is now bi-directional. It detects the variables that do not depend on the independents, and the variables that do not influence on the dependents. This leads to fewer differentiated variables.
• We included the TBR analysis, a static analysis for the reverse mode. It finds variables which, although they are overwritten during the forward sweep, need not be saved because they will not be used during the reverse sweep.
• We implemented a new storage strategy for the reverse mode, named the global trajectory. This stores intermediate values on an external stack rather than on static arrays that thad to be dimensioned by hand by the user of Odyssée
• Snapshots in the reverse mode are smaller, because they use In-Out analysis to find out variables that are really necessary for duplicate execution of the checkpointed piece of code.
• The inversion of the control, in the reverse mode, is done on the Flow Graph. This gives a better, more readable transformed source, that the compiler can compile better.
• TAPENADE now provides a multi-directional forward mode, similar to the ADIFOR's vector mode. It computes the directional derivatives in many directions simultaneously. Derivative loops are gathered using data-dependency analysis.
• Data-Flow analysis is used to optimize the transformed source, at the level of each Basic Block.

1. First thing is to decide which is the part of the code that defines the function you want to differentiate. It is certainly not your complete program! It must be a connex piece of code (call it the inside) with a unique beginning (call it the entry) and a unique end (call it the exit). This piece of code can very well contain calls to other procedures. Every run of your code that goes through the entry must then reach the exit. In particular, there must be no control jumps from outside to the inside, except to the entry. Similarly, there must be no control jumps from the inside to the outside, except from the exit. Make this "inside" piece of code a subroutine or function (in FORTRAN) or a procedure (in C). You original code is therefore modified: you have created a new procedure, and now there is a call to this procedure in place of the original piece of code to differentiate. It now looks like (FORTRAN style):

   
             ... whatever code is before ... 
   C Beginning of the function I want to differentiate
          CALL MYFUNC(x1, x2,..., y1, y2,...)
   C End of the function I want to differentiate
             ... whatever code comes after ... 
   

2. It goes without saying, but make sure you use some mechanism to make necessary variables travel to and from the new procedure. You may use parameter passing, or FORTRAN common, or globals... as you wish. We shall call these variables the "parameters" of the procedure (even if they are indeed globals). It is very useful that you know these variables well, what they mean, what they are needed too, are they just used or just written and returned, or both, etc... Now you see why this preparation work must be done by someone who knows the code!
3. Apply Tapenade in the "no-differentiation" mode, which is command-line option "-p". This will trigger several analysis but will generate a source code that should be equivalent to the original code, without any differentiation. The interest is to check that Tapenade is able to parse your source files correctly. Another interest is to see the warning messages issued by Tapenade. Some of these messages may indicate situations where things can go wrong. Therefore, we advise you to type something along the lines of:

   
      $> tapenade -p -o nodifferentiated  "source files but no include files"
   

   
   This will read all your source files (do not provide the include files in the command line because Tapenade will read them automatically when needed). Your source code will be parsed and analyzed, and this will result in a file nodifferentiated_p.msg. It contains a (verbous) list of all warning and error messages, that you should browse through, with the help of the documentation on messages. The explanations in the reference manual will help you find which messages can be discarded (e.g., very often, the implicit conversions between REAL*8 and DOUBLE PRECISION), and which ones can't. Tapenade should have generated by now a new source file nodifferentiated_p.[f/f90/c], that contains a duplicate of your original source, with "_P" appended to procedure names. You may look at it to check that it is identical to your source, and you may call it instead of the original code and check you get the same results. Your code could now look like:

   
             ... whatever code is before ... 
   C Beginning of the function I want to differentiate
          CALL MYFUNC_P(x1, x2,..., y1, y2,...)
   C End of the function I want to differentiate
             ... whatever code comes after ... 
   

1. Write a procedure that saves all these "parameters" of MYFUNC into some storage (can be static arrays), and a procedure that restores the saved values into these parameters. You may test them inside your modified code, just to make sure! Your code could now look like:

   
             ... whatever code is before ... 
          CALL SAVE_NECESSARY_PARAMS(x1, x2,..., y1, y2,...)
          CALL RESTORE_NECESSARY_PARAMS(x1, x2,..., y1, y2,...)
   C Beginning of the function I want to differentiate
          CALL MYFUNC(x1, x2,..., y1, y2,...)
   C End of the function I want to differentiate
             ... whatever code comes after ... 
   

2. Call the new procedure twice in a row, inside the same execution. check you obtain the same results. So you will be sure that there is no unwanted side-effect or undefined-variable-used in your code to be differentiated. Your code could now look like:

   
          ... whatever code is before ... 
   C Save what is necessary in the current state
          CALL SAVE_NECESSARY_PARAMS(x1, x2,..., y1, y2,...)
   C Beginning of the function I want to differentiate
          CALL MYFUNC(x1, x2,..., y1, y2,...)
          res1_y1 = y1
          res1_y2 = y2
          ... 
   C Prepare for the second run
          CALL RESTORE_NECESSARY_PARAMS(x1, x2,..., y1, y2,...)
   C Call MYFUNC again
          CALL MYFUNC(x1, x2,..., y1, y2,...)
          res2_y1 = y1
          res2_y2 = y2
          ... 
          make sure all res1_yyy == res2_yyy 
   C End of the function I want to differentiate
          ... whatever code comes after ... 
   

3. Now choose which ones among the above "parameters" you want to differentiate (the "dependents"), with respect to which ones (the "independents"). Beware these must all be elements of the set of "parameters". We do not differentiate a procedure with respect to its local variables, constants, or with respect to variables that the procedure does not see. In particular, it happens that some of these parameters are dynamically allocated (resp. freed). Then it is essential that the allocation (resp. free) is outside of the procedure to be differentiated. Although this is not as essential, it is also good politics to avoid dynamic allocation/freeing anywhere inside the procedures to be differentiated. This may cause hard problems especially with the reverse mode.
4. Why not try and compute a (approached) derivative by divided differences then? It's maybe a little early but you will need to do it anyway for the old validation step. Define a differentiated variable for each of the dependent and independent. Initialize them all to 1.0. Modify each independent inputs by "epsilon" times its derivative variable. Run the procedure once and keep the result. Reset the inputs, this time without the "epsilon" modification, and run again. Then evaluate the difference of outputs, divided by "epsilon". It is the sum of all columns of the Jacobian. For instance, if you want all inputs to be independent and all outputs to be dependent, and setting "ddeps" the epsilon, your code could now look like:

   
          ... whatever code is before ... 
   C Initialize the derivatives of the independent and dependent parameters
   C (don't forget to declare these variables !):
          x1d = 1.0
          x2d = 1.0
          ... 
          y1d = 0.0
          y2d = 0.0
          ... 
   C Save what is necessary in the current state
          CALL SAVE_NECESSARY_PARAMS(x1, x2,..., y1, y2,...)
   C Modify the current state:
          ddeps = 1.d-5
          x1 = x1 + ddeps*x1d
          x2 = x2 + ddeps*x2d
          ... 
   C Call F(X + epsilon*Xd)
          CALL MYFUNC(x1, x2,..., y1, y2,...)
          res1_y1 = y1
          res1_y2 = y2
          ... 
   C Prepare for the second run
          CALL RESTORE_NECESSARY_PARAMS(x1, x2,..., y1, y2,...)
   C Call F(X)
          CALL MYFUNC(x1, x2,..., y1, y2,...)
          res2_y1 = y1
          res2_y2 = y2
          ... 
   C Compute approx_Yd = (F(X+epsilon*Xd) - F(X))/epsilon
          approx_y1d = (res1_y1 - res2_y1)/ddeps
          ... 
          make sure these derivatives make sense! 
   C End of the function I want to differentiate
          ... whatever code comes after ... 
   

 U(in:a,out:b); F(in:b,out:c); D(in:b,in:c,out:d);

 U(in:a,out:b); loop {F(in:b,out:c);} D(in:c,out:d);

      subroutine F(u2,v1,v3,w2)
      real u1,u2,u3,v1,v2,v3,w1,w2,w3
      common /cc/u1,u3,v2,w1,w3
c
      u3 = u3+v1*u1
      u3 = u3-u2*v2
      u2 = 3.0*u1*v1
      u3 = u3+G(u2)
c
      v3 = v3+2.0*v1
      v3 = v3-v2
      v2 = 3.0*v1
      v3 = v3+G(v2)
c
      w3 = w3+v1*v2
      w3 = w3-w2*u1
      w2 = 3.0*w1
      w3 = w3+G(w2)
      end

      real function G(x)
      real x
      G = x*x
      end

    -head "F(v1 v2 v3 w1 w2 w3)>(u1 u2 u3 w1 w2 w3)"

C  Differentiation of f in forward (tangent) mode:
C   variations   of useful results: u3 v2 w3 w2 u2
C   with respect to varying inputs: v2 w1 w3 v1 w2
C   RW status of diff variables: u3:out v2:in-out
C           w1:in w3:in-out v1:in w2:in-out u2:out
      SUBROUTINE F_D(u2, u2d, v1, v1d, v3, w2, w2d)
      IMPLICIT NONE
C
      REAL u1, u2, u3, v1, v2, v3, w1, w2, w3
      REAL u2d, u3d, v1d, v2d, w1d, w2d, w3d
      COMMON /cc/ u1, u3, v2, w1, w3
      REAL G
      REAL G_D
      REAL result1
      REAL result1d
      COMMON /cc_d/ u3d, v2d, w1d, w3d
C
      u3d = u1*v1d
      u3 = u3 + v1*u1
      u3d = u3d - u2*v2d
      u3 = u3 - u2*v2
      u2d = 3.0*u1*v1d
      u2 = 3.0*u1*v1
      result1d = G_D(u2, u2d, result1)
      u3d = u3d + result1d
      u3 = u3 + result1
C
      v3 = v3 + 2.0*v1
      v3 = v3 - v2
      v2d = 3.0*v1d
      v2 = 3.0*v1
      result1 = G(v2)
      v3 = v3 + result1
C
      w3d = w3d + v1d*v2 + v1*v2d
      w3 = w3 + v1*v2
      w3d = w3d - u1*w2d
      w3 = w3 - w2*u1
      w2d = 3.0*w1d
      w2 = 3.0*w1
      result1d = G_D(w2, w2d, result1)
      w3d = w3d + result1d
      w3 = w3 + result1
      END

C  Differentiation of f in reverse (adjoint) mode:
C   gradient     of useful results: u3 w1 w3 w2 u2
C   with respect to varying inputs: u3 v2 w1 w3 v1
C      w2 u2
C   RW status of diff variables: u3:in-out v2:out
C      w1:incr w3:in-out v1:out w2:in-out u2:in-out
      SUBROUTINE F_B(u2, u2b, v1, v1b, v3, w2, w2b)
      IMPLICIT NONE
C
      REAL u1, u2, u3, v1, v2, v3, w1, w2, w3
      REAL u2b, u3b, v1b, v2b, w1b, w2b, w3b
      COMMON /cc/ u1, u3, v2, w1, w3
      REAL G
      REAL result1
      REAL result1b
      COMMON /cc_b/ u3b, v2b, w1b, w3b
      CALL PUSHREAL4(u2)
C
      u2 = 3.0*u1*v1
      CALL PUSHREAL4(v2)
C
      v2 = 3.0*v1
C
      w2 = 3.0*w1
      result1b = w3b
      CALL G_B(w2, w2b, result1b)
      w1b = w1b + 3.0*w2b
      w2b = -(u1*w3b)
      v1b = v2*w3b
      v2b = v1*w3b
      CALL POPREAL4(v2)
      result1b = u3b
      CALL G_B(u2, u2b, result1b)
      v1b = v1b + u1*3.0*u2b + u1*u3b + 3.0*v2b
      CALL POPREAL4(u2)
      u2b = -(v2*u3b)
      v2b = -(u2*u3b)
      END

      "entiere lines between double quotes and drawn in the pattern color"

CHECK THE SIZES OF PRIMITIVE TYPES:

• 1) adapt the compilation commands $(FC) and $(CC) in the Makefile
• 2) make testMemSize
• 3) execute testMemSize
• 4) look at the sizes printed.

CHECK THE TANGENT DERIVATIVES WITH RESPECT TO DIVIDED DIFFERENCES:

X+*Xd

          ... whatever code is before ... 
C Beginning of the procedure to differentiate
       CALL MYFUNC(x1, x2,..., y1, y2,...)
C End of the procedure to differentiate
          ... whatever code comes after ... 

• The first copy, that we will call "codeDD1", compiles into an executable that we will call "exeDD1". Instead of calling MYFUNC, it calls its tangent differentiated version MYFUNC_D, calling a few debugging primitives before and after. The central part of "codeDD1" is thus:

  
            ... whatever code is before ... 
  
            Now initialize the input differentiated variables, to 
            define the chosen differentiation direction, e.g.:
         x1d = 1.5d0
         x2d = (/-1.d0,2.3d0,-0.5d0,.../)
            ...
            Now prepare for the test:
         CALL DEBUG_TGT_INIT1(1.d-8, 1.d-5, .1d0)
         CALL DEBUG_TGT_INITREAL8(x1, x1d)
         CALL DEBUG_TGT_INITREAL8ARRAY(x2, x2d, ns)
            ...
         CALL DEBUG_TGT_CALL('MYFUNC', .true., .false.)
  C Beginning of differentiated part
         CALL MYFUNC_D(x1, x1d, x2, x2d, ..., y1, y1d, y2, y2d, ...)
  C End of differentiated part
            Now terminate the test:
         CALL DEBUG_TGT_EXIT()
         CALL DEBUG_TGT_CONCLUDEREAL8('y1', y1, y1d)
         CALL DEBUG_TGT_CONCLUDEREAL8ARRAY('y2', y2, y2d, 20)
            ...
  
            ... whatever code comes after ... 
  

• The second copy, that we will call "codeDD2", compiles into an executable that we will call "exeDD2". It is strictly identical to "codeDD1" except that it calls DEBUG_TGT_INIT2 instead of DEBUG_TGT_INIT1

• Each copy "codeDD1" and "codeDD2" will be executed independently. Each must use or read from the same data files as the original code, and should behave exactly the same until reaching the central part. You don't need to duplicate every source file to define these copies "codeDD1" and "codeDD2". You probably need only to duplicate the file that contains the "central" part. The rest should be taken care of by the compilation and link commands.
• The code for MYFUNC_D must be built by Tapenade by tangent differentiation of the source code, with the only additional command-line option -debugTGT. The same differentiated code is used by "exeDD1" and "exeDD2".
• Each executable "exeDD1" and "exeDD2" must be linked with the debugging library provided in the "First-Aid Kit". This library consists of file debugAD.f and its include file debugAD.inc
• The calls to DEBUG_TGT_INIT1 or to DEBUG_TGT_INIT2 must have the same arguments. The first is the "epsilon" used for divided differences. The second is called "almost-zero" (see below). The third is the "threshold" (see below) error percentage above which a message is printed.
• In the prepared code above, notice that there is a statement that initializes each input differentiated variable. You are free to choose the values, therefore choosing the direction of your tangent. Naturally, arrays require several values.
• A few lines later, before calling MYFUNC_D, you must insert one initialization call for each input differentiated variable. For arrays, initialization procedure DEBUG_TGT_INITREAL8ARRAY takes an extra argument, which is the size of the array. For single precision REAL's, replace REAL8 by REAL4.
• The same remarks apply to the DEBUG_TGT_CONCLUDE... debug termination calls.
• Don't forget to declare all differentiated variables in the declaration part of your codes "codeDD1" and "codeDD2".

   $> exeDD1 | exeDD2

$> exeDD1 | exeDD2
Starting TGT test, epsilon=0.1E-07, zero=0.1E-04, errmax=10.0%
===========================================================
  AT:entry OF                                 MYFUNC
    AT:entry OF                                POLYPERIM
    AT:middle OF                                POLYPERIM
      AT:entry OF                                 INCRSQRT
      AT:exit OF                                 INCRSQRT
      AT:entry OF                                 INCRSQRT
      AT:exit OF                                 INCRSQRT
    AT:exit OF                                POLYPERIM
    AT:entry OF                                POLYPERIM
    AT:middle OF                                POLYPERIM
         ... lots of lines deleted here ... 
    AT:exit OF                                POLYPERIM
  AT:middle OF                                 MYFUNC
    AT:entry OF                                 POLYSURF
    AT:middle OF                                 POLYSURF
pp:   -0.1000000000000000E+01 (ad) 90.0% DIFF WITH (dd) -0.1000000011686097E+02
      AT:entry OF                                 INCRSQRT
pp:    0.3001997501343353E+01 (ad)150.0% DIFF WITH (dd) -0.5998002627904953E+01
      AT:exit OF                                 INCRSQRT
polysurf:    0.3001997501343353E+01 (ad)150.0% DIFF WITH (dd) -0.5998002627904953E+01
    AT:exit OF                                 POLYSURF
y2:    0.3787447771453199E+13 (ad) 92.3% DIFF WITH (dd) 0.2901041015625000E+12
  AT:exit OF                                 MYFUNC
Final result y2: 0.3787447771453199E+13 (ad) 92.34038% DIFF WITH (dd) 0.2901041015625000E+12
===========================================================

         IF (pp.EQ.0) pp=ns
C$AD DEBUG-HERE CP4 cp.eq.4
         dx = X(cp)-X(pp)

C$AD DEBUG-CALL false
       perim = perim+ i*POLYPERIM(X,Y,ns)

CHECK THE REVERSE DERIVATIVES USING THE DOT-PRODUCT TEST:

          ... whatever code is before ... 
C Beginning of the procedure to differentiate
       CALL MYFUNC(x1, x2,..., y1, y2,...)
C End of the procedure to differentiate
          ... whatever code comes after ... 

• The first copy, that we will call "codeBB1", compiles into an executable that we will call "exeBB1". Instead of calling MYFUNC, it calls its reverse differentiated version MYFUNC_B, calling a few debugging primitives before and after. The central part of "codeBB1" is thus:

  
            ... whatever code is before ... 
  
            Now initialize the REVERSE differentiated variables, e.g.:
            (this step is NOT absolutely necessary for debug !)
         x1b = 0.d0
         DO i=1,ns
           x2b(i) = 0.d0
         ENDDO
         y1b = 1.d0
         DO i=1,20
           y2b(i) = 1.d0
         ENDDO
            ...
            Now prepare for the test:
         CALL DEBUG_BWD_INIT(1.d-5, 0.1d0, 0.87d0)
         CALL DEBUG_BWD_CALL('MYFUNC', .true.)
  C Beginning of differentiated part
         CALL MYFUNC_B(x1, x1b, x2, x2b, ..., y1, y1b, y2, y2b, ...)
  C End of differentiated part
            Now terminate the test:
         CALL DEBUG_BWD_EXIT()
         CALL DEBUG_BWD_CONCLUDE()
  
            ... whatever code comes after ... 
  

• The second copy, that we will call "codeBB2", compiles into an executable that we will call "exeBB2". Again, only its central part is modified into the following code:

  
            ... whatever code is before ... 
  
            Now initialize the TANGENT differentiated variables, e.g.:
            (this step is NOT absolutely necessary for debug !)
         x1d = 1.d0
         DO i=1,ns
           x2d(i) = 1.d0
         ENDDO
         y1d = 0.d0
         DO i=1,20
           y2d(i) = 0.d0
         ENDDO
            ...
            Now prepare for the test:
         CALL DEBUG_FWD_INIT(1.d-5, 0.1d0, 0.87d0)
         CALL DEBUG_FWD_CALL('MYFUNC')
  C Beginning of differentiated part
         call MYFUNC_D(x1, x1d, x2, x2d, ..., y1, y1d, y2, y2d, ...)
  C End of differentiated part
            Now terminate the test:
         CALL DEBUG_FWD_EXIT()
         CALL DEBUG_FWD_CONCLUDE()
  
            ... whatever code comes after ... 
  

• Each copy "codeBB1" and "codeBB2" will be executed independently. Each must use or read from the same data files as the original code, and should behave exactly the same until reaching the central part. You don't need to duplicate every source file to define these copies "codeBB1" and "codeBB2". You probably need only to duplicate the file that contains the "central" part. The rest should be taken care of by the compilation and link commands.
• Note that "codeBB1" makes use of the reverse-differentiated code MYFUNC_B and of the associated differentiated variables x1b etc. The code for MYFUNC_B must be built by Tapenade by reverse differentiation of the source code, with the only additional command-line option -debugADJ.
• Conversely, "codeBB2" makes use of the tangent-differentiated code MYFUNC_D and of the associated differentiated variables x1d etc. The code for MYFUNC_D must be built by Tapenade by tangent differentiation of the source code, with the only additional command-line option -debugADJ.
• Each executable "exeDD1" and "exeDD2" must be linked with the debugging library provided in the "First-Aid Kit". This library consists of file debugAD.f and its include file debugAD.inc
• The calls to DEBUG_BWD_INIT or to DEBUG_FWD_INIT must have the same arguments. The first is called "almost-zero" (see below). The second is the "threshold" (see below) error percentage above which a message is printed. The third is the "seed" that influences the random choice of vectors Xd and Yb during testing.
• In the prepared code above, notice that debug statements do not concern individual differentiated variables. This is because, unlike the divided-differences test, this dot-product test is global and cannot be applied to a single variable.
• Don't forget to declare all differentiated variables in the declaration part of your codes "codeBB1" and "codeBB2".

   $> exeBB1 | exeBB2

$> exeBB1 | exeBB2
Starting ADJ test, zero=0.1E-04, errmax=10.0%, random_incr=0.87E+00
===========================================================
  AT:entry OF                                 MYFUNC
    AT:entry OF                                POLYPERIM
    AT:middle OF                                POLYPERIM
         ... lots of lines deleted here ... 
    AT:exit OF                                POLYPERIM
  AT:middle OF                                 MYFUNC
    AT:entry OF                                 POLYSURF
    AT:middle OF                                 POLYSURF
49.0% DIFFERENCE!!  fwd: 0.1156790000000001E+02  bwd: 0.2268820000000001E+02
      AT:entry OF                                 INCRSQRT
      AT:exit OF                                 INCRSQRT
    AT:exit OF                                 POLYSURF
  AT:exit OF                                 MYFUNC
End of ADJ test. 1 error(s) found. WARNING: testing alters derivatives!
===========================================================

• To turn off/on testing inside the call tree below a particular call to procedure FOO, find this call to FOO_B, move up the debugging if-then-else before it, to reach the call to CALL DEBUG_BWD_CALL('FOO', "boolean-expression") you may change the boolean second argument at will.
• To turn off/on a debug point named "mypoint", find the test: IF ("boolean-expression" .AND. DEBUG_BWD_HERE('mypoint')) THEN and change the boolean before AND at will. Debug points named "entry", "exit", "beforeCall", and "afterCall" can not and must not be turned off individually.

PROBLEMATIC INTERACTION WITH INDEPENDENT AND DEPENDENT PARAMETER SETS:

• This may cause problems in the tangent validation ("divided differences") because it affects the way derivatives are initialized.
• This will certainly cause problems in the adjoint validation ("dot product") if the tangent and adjoint codes are built with (in)dependent paramaters that don't match

• either add the command-line option -fixinterface and the Independent and Dependent parameters will not be modified,
• or modify by hand your Independent and Dependent parameter sets, according to the variables indicated by the above messages. Then the sets will be coherent again between the tangent and the adjoint codes.

• Open "Preferences", then click either on "File Helpers" if visible, or on "Receiving Files/File Helpers" sub-menu. You should get something like this.
• Click the "Add..." button.
• Enter a description, e.g. "Fortran files", and an extension, e.g. .f or .f90.
• Enter a MIME type application/octet-stream.
• Enter a File type. Four characters exactly are required here. Type e.g. FORT .
• Enter a File creator (as for "File type" above).
• Make sure the "Plain text" radio button is selected.
• Tick "Use for incoming" and "Use for outgoing" check-boxes.
• This should look like this. Then click "OK".

www.autodiff.org

• Adifor differentiates Fortran77 codes in tangent (direct) mode. Adifor once was extended towards the adjoint (reverse) mode (Adjfor), but we believe this know-how has now been reinjected into the OpenAD framework.
• Adic can be seen as the C equivalent of Adifor. However it is based on a completely different architecture, from the OpenAD framework. This framework, very similar to Tapenade's architecture, claims that only front-end and back-end should depend on the particular language, whereas the analysis and differentiation part should work on a language-independent program representation. Adic differentiates ANSI C programs in tangent mode, with the possibility to obtain second derivatives.
• OpenAD/F differentiates Fortran codes in tangent and adjoint modes. Its strategy to restore intermediate values in reverse AD is extremely close to Tapenade's. OpenAD/F is made of Adifor and Adjfor components integrated into the OpenAD framework.
• TAMC, and its commercial offspring TAF differentiate Fortran files. Taf also differentiates Fortran95 files, under certain restrictions. TAF is commercialized by the FastOpt company in Hamburg, Germany. TAF differentiates in tangent and reverse mode, with the recompute-all approach to restore intermediate values in reverse AD. Checkpointing and an algorithm to avoid useless recomputations (ERA) are used to avoid explosion of run-time. TAF also provides a mode that efficiently computes the sparsity pattern of Jacobian matrices, using bitsets.
• TAC++ is the C version of TAF. It is also developped by FastOpt. Presently, TAC++ only handles a large subset of C, and it is still in its development phase, although making significant progress. Like TAF, it will provide tangent and adjoint modes, with the same strategies, e.g. the recompute-all approach with checkpointing for the reverse mode.

tapenade ... -parserfileseparator "\" ...

tapenade ... -parserfileseparator "/" ...

• Subroutine name
• Dependent outputs
• Independent inputs

  tapenade foo.f bar.f toto.f ... -head "f1(y1 y3)/(x2) f2(b2 b4)/(a1 a2 a3)"

  -head "f1(x2)>(y1 y3)"

  -head "m5%f1(y1 y3 m2%v2%c4)/(x2)"

  -head "m5.f1(y1 y3 m2.v2)/(x2 x4)"

• You can place a directive in the source just before a particular procedure call. For example:

  
  C$AD NOCHECKPOINT
        w = toto(x, y, z)
  

  tells Tapenade not to place a checkpoint around this particular call to function toto.
• You can place a directive in the source just before the definition of a procedure. For example:

  
  C$AD NOCHECKPOINT
         subroutine titi(a,b)
  

  tells Tapenade not to place a checkpoint around any call to subroutine titi.
• You can use the command-line argument -nocheckpoint that takes the list of procedures that must never be checkpointed. For example:

  
     $> tapenade -b -nocheckpoint "toto titi" program.f
  

  will checkpoint no call to subroutines toto and titi.

C$AD II-LOOP
        DO i=1,N,2
          A(i) = 2.0*z
          A(i+1) = 3.0*z
          tmp1 = B(T(i))
          tmp2 = B(K(i))
          vv = SQRT(tmp1*tmp2)
          C(i) = C(i)+vv
        ENDDO

        DO i=3,N-2
          A(i) = A(i-2)
          B(i) = B(i+2)
          prod = prod*C(i)
        ENDDO

• There is a loop-carried flow dependence of distance 2 on A
  
• There is a loop-carried anti dependence of distance 2 on B, and it will become a flow dependence if the iteration order is reversed.
• There is a loop carried dependence on the product prod

C$AD II-LOOP
        DO i=1,N,2
          tmp1 = B(T(i))
          tmp2 = B(K(i))
          vv = SQRT(tmp1*tmp2)
          sum = sum+vv
        ENDDO

• The $AD CHECKPOINT-START must be placed immediately before the first statement that is in P.
• The $AD CHECKPOINT-END must be placed immediately before the first statement out of P, i.e. the first statement that follows the end of P.

      if (x.gt.10.0) then
C$AD CHECKPOINT-START
         x = x*y
         if (x.gt.0.0) x =-x
C$AD CHECKPOINT-START
         y = y - x*x
         y = y*y
C$AD CHECKPOINT-END
         x = x + sin(y)
C$AD CHECKPOINT-END
         continue
         ...
      endif

      IF (x .GT. 10.0) THEN
        CALL PUSHREAL4(x)
        CALL PUSHREAL4(y)
        x = x*y
        IF (x .GT. 0.0) x = -x
        y = y - x*x
        y = y*y
        x = x + SIN(y)
        ...
        CALL PUSHCONTROL1B(1)
      ELSE
        CALL PUSHCONTROL1B(0)
      END IF

      CALL POPCONTROL1B(branch)
      IF (branch .NE. 0) THEN
        ...
        CALL POPREAL4(y)
        CALL POPREAL4(x)
        CALL PUSHREAL4(x)
        x = x*y
        IF (x .GT. 0.0) THEN
          x = -x
          CALL PUSHCONTROL1B(1)
        ELSE
          CALL PUSHCONTROL1B(0)
        END IF
        CALL PUSHREAL4(y)
        y = y - x*x
        y = y*y
        yb = yb + COS(y)*xb
        CALL LOOKREAL4(y)
        y = y - x*x
        yb = 2*y*yb
        xb = xb - 2*x*yb
        CALL POPREAL4(y)
        CALL POPCONTROL1B(branch)
        IF (branch .NE. 0) xb = -xb
        CALL POPREAL4(x)
        yb = yb + x*xb
        xb = y*xb
      END IF

• The maximum number of checkpoint snapshots (i.e. bunches of values required to restart execution from a given iteration) present in memory at the same time grows like log(N). Therefore the maximum memory required is log(N) times the size of one snapshot.
• The maximum number of times a given iteration with be repeatedly executed due to this strategy also grows like log(N). Therefore the time required to compute the adjoint of the N iterations will be (log(N) + Constant) times longer than the time to run the original N iterations.

• The maximum memory required is q times the size of one snapshot. It is independent of N.
• The time required to compute the adjoint of the N iterations will grow like the q-th root of N.

C$AD BINOMIAL-CKP nstp-stp1+2 4 stp1
      do stp=stp1,nstp
         x = x+y
         y = y-x*x
         v3 = 1.0
         do i=3,98
            j = i-stp/10
            v1 = A(j)*B(i)
            v2 = B(j)/A(i+1)+v3
            A(i) = 2*A(i)+sin(C(j))
            B(i-1) = B(i)*B(i+2) - A(i+1)*A(i-1)
            A(i+1) = A(i)+v1*v2
            B(i-1) = B(i)+v2*v3
            v3 = v3+v2-v1
         enddo
         A(j) = A(i)*B(j)
      enddo

• The number of iteration steps, or an expression to compute it just before the loop starts. For optimal results, also count the iteration during which loop exit occurs. This is why we wrote nstp-stp1+2 instead of nstp-stp1+1. If the given number of iterations is wrong, the differentiated code should still work, but will be less efficient in time or memory.
• The maximum number q of allowed snapshots, chosen by the end-user
• The index of the first step in the sequence

• Push Snapshot: Push the current memory state on the stack.
• Look Snapshot: Restore the memory state from the stack, but leave it on the stack.
• Pop Snapshot: Restore the memory state from the stack and remove it from the stack
• Advance: run the next iteration in its original form, without any derivative computed nor value pushed.
• First Turn: Compute the adjoint of the last iteration and of the rest of the code.
• Turn: Compute the adjoint of an ordinary iteration (not the last one)

• TRV_INIT()
• TRV_NEXT_ACTION()
• TRV_RESIZE()

        call SOLVE(A,y,b,n)

        call SOLVE_D(A,Ad,y,yd,b,bd,n)

        subroutine SOLVE_D(A,Ad,y,yd,b,bd,n)
        INTEGER n
        REAL A(n,n), Ad(n,n)
        REAL y(n), yd(n), b(n), bd(n)
        INTEGER i,j
        REAL RHSd(n)

        call SOLVE(A,y,b,n)
        DO i=1,n
          RHSd(i) = bd(i)
          DO j=1,n
            RHSd(i) = RHSd(i) - Ad(i,j)*y(j)
          ENDDO
        ENDDO
        call SOLVE(A,Yd,RHSd,n)
        END

        call SOLVE_B(A,Ab,y,yb,b,bb,n)

        subroutine SOLVE_B(A,Ab,y,yb,b,bb,n)
        INTEGER n
        REAL A(n,n), Ab(n,n)
        REAL y(n), yb(n), b(n), bb(n)
        INTEGER i,j
        REAL AT(n,n), incrbb(n)

        DO i=1,n
          DO j=1,n
            AT(i,j) = A(j,i)
          ENDDO
        ENDDO
        call SOLVE(AT, incrbb, yb, n)
        DO j=1,n
          bb(j) = bb(j) + incrbb(j)
        ENDDO
        call SOLVE(A,y,b,n)
        DO i=1,n
          DO j=1,n
            Ab(i,j) = Ab(i,j) - y(j)*incrbb(i)
          ENDDO
        ENDDO
        END

• first, notice that this code increments Ab and bb instead of just setting them. This is the usual adjoint behavior that comes from the fact that A and b may very well be used elsewhere in the program and therefore may have other influences on the dependent outputs.
• Second, we have been considering in these examples that both A and b are active. If either one is not active, then the codes above may be simplified.

• There are not as many PUSH'es and POP's because the control flow is not inversed well. The symptom is that the crash occurs inside a POP, and the stack is empty. If this occurs to you, it is a Tapenade bug. Please signal it to us.
• If your program passes a FORTRAN PARAMETER (i.e. a constant) as an argument to another procedure, Tapenade tries to PUSH/POP this constant, which results in a segmentation fault at the POP. Until we fix that, don't pass a PARAMETER as an argument.

       real*8 xx

       real*8 xxd(nbdirsmax)

       real*8 aa(100,N)

       real*8 aad(nbdirsmax,100,N)

       a(i1, i2) = 2*b(i1, i2)

       DO nd=1,nbdirs
         ad(nd, i1, i2) = 2*bd(nd, i1, i2)
       ENDDO

       integer nbdirsmax
       parameter (nbdirsmax = 50)

• the same Y = F(X)
• and in addition YD = J*XD, where J is the Jacobian of F at point X.

   $> tapenade -d -head P -vars "x" -outvars "y" p.f 

   $> tapenade -d -head P_D -vars "x" -outvars "yd" p_d.f 

TANGENT-ON-TANGENT APPROACH:

• The first multi-directional differentiation creates a program that includes a new file DIFFSIZES.inc, containing information about array sizes. Precisely, the include file must declare the integer constant nbdirsmax which is the maximum number of differentiation directions that you plan to compute in a single run. nbdirsmax is used in the declarations of the size of the differentiated arrays. You must create this file DIFFSIZES.inc before starting the second differentiation step. For instance, this file may contain

  
         integer nbdirsmax
         parameter (nbdirsmax = 50)
  

  if 50 is the max number of differentiation directions. If what you want is the Hessian, this max number of differentiation directions is the cumulated sizes of all the inputs x.
• The second multi-directional differentiation requires a new maximum size value nbdirsmax0, which is a priori different from nbdirsmax. For the Hessian case, it is probably equal to nbdirsmax. What's more, Tapenade has inlined the 1st level include file, so what you get is a strange looking piece of declarations:

  
        ...
        INCLUDE 'DIFFSIZES.inc'
  C  Hint: nbdirsmax should be the maximum ...
        INTEGER nbdirsmax
        PARAMETER (nbdirsmax=50)
        ...
  

  We suggest you just remove the INCLUDE 'DIFFSIZES.inc' line, and hand-replace each occurrence of nbdirsmax0 by either nbdirsmax or even 50!
• A complete Hessian is in general symmetric. Tapenade was not able to take advantage of this. You may do so by replacing every successive lines of the form

  
        ...
        DO nd=1,nbdirs
          DO nd0=1,nbdirs0
        ...
  

  by

  
        ...
        DO nd=1,nbdirs
          DO nd0=nd,nbdirs0
        ...
  

TANGENT-ON-REVERSE APPROACH:

              4*n*7*P

              4*n*4*n*P

  ... -ext PUSHPOPGeneralLib ...

• PUSHPOPGeneralLib declares the inputs and outputs of the PUSH and POP procedures. For example the lines

  
  subroutine popreal8:
    external:
    shape:(param 1,
           common /adstack/[0,*[)
    type:(modifiedTypeName(modifiers(intCst 8), ident real),
          arrayType(modifiedTypeName(modifiers(intCst 8), ident real),
                    dimColons(dimColon(none(),none()))))
    R : (0, 1)
    W : (1, 1)
  

  mean that POPREAL8 has indeed two arguments. One is the formal parameter, which is a REAL*8, and the other is the stack, whose type is an array of REAL*8 values. The formal parameter is not read but overwritten, the stack is read and overwritten i.e. modified. You may want to add new such declarations if your code uses other PUSH and POP's, such as PUSHREAL4. PUSHPOPGeneralLib also declares the dependencies through the PUSH and POP procedures. For example the lines concerning POPREAL8

  
    deps: (0, 1,
           0, 1)
  

  mean that POPREAL8 outputs a value in its first argument that only depends on the given value of the stack, and also sets a new value for the stack that only depends on the given value of the stack. You may need to add new such declarations if your code uses other PUSH and POP's, such as PUSHREAL4.
• PUSHPOPDiff.f defines the differentiated procedures for the PUSH and POP procedures, in plain tangent mode as well as in multi-directional tangent mode. These differentiated routines exist only for the PUSH and POP of active variables. In particular there are no such differentiated routines for PUSHINTEGER nor POPINTEGER. The trick is to push and pop the original variable and the differentiated variable, and since we use a stack, the order of the PUSH'es and POP's is reversed. You may need to add new such definitions if your code uses other PUSH and POP's, such as PUSHREAL4.

subscribe

allocatable :: a(:,:)
pointer :: son
target :: a, y(10)

MODULE M
  ...
END MODULE M

SUBROUTINE S
USE M
...
END SUBROUTINE S

MODULE M_B
  ...
END MODULE M_B

SUBROUTINE S_B
USE M_B
...
END SUBROUTINE S_B

SUBROUTINE S_CB
USE M_B
...
END SUBROUTINE S_CB

• "S", the original "S" that works with the original "M", and
• "S_CB", the copy of "S" for the reverse mode, which works with the same module "M_B" as the differentiated "S_B". (the _CB suffix is built by adding _C in front of the suffix for differentiated variables.)

PROGRAM MAIN
  USE MMA
  USE MMB
  REAL, DIMENSION(:), ALLOCATABLE :: x
  INTEGER :: i
  REAL :: cva(2)
  COMMON /cc1/ cva
  EXTERNAL GETFLAG
  CALL GETFLAG(flag)
  ALLOCATE(x(30))
  CALL INITA()
  DO i=1,20
    aa(i) = 100.0/i
    x(i) = 3.3*i
  END DO
  cva(1) = 1.8
  cva(2) = 8.1
  CALL ROOT(x)
  PRINT*, 'zz=', zz
  DEALLOCATE(aa)
  DEALLOCATE(x)
END PROGRAM MAIN

MODULE MMA
  REAL, DIMENSION(20), ALLOCATABLE :: aa

CONTAINS
  SUBROUTINE INITA()
    ALLOCATE(aa)
  END SUBROUTINE INITA
END MODULE MMA

MODULE MMB
  INTEGER :: flag
  REAL :: zz
END MODULE MMB

SUBROUTINE ROOT(x)
  USE MMA
  USE MMB
  REAL, DIMENSION(*) :: x
  REAL :: v
  REAL :: cv1, cv2
  COMMON /cc1/ cv1, cv2
  zz = cv1*cv2
  v = SUM(aa)
  IF (flag .GT. 2) zz = zz*v
  zz = zz + SUM(x)
END SUBROUTINE ROOT

!  Diff. of root in tangent mode:
!   variations of useful results: zz
!   with respect to varying inputs:
!    *aa cv1 cv2 x
!   RW status of diff variables:
!    zz:out *aa:in cv1:in cv2:in x:in
SUBROUTINE ROOT_D(x, xd)
  USE MMB_D
  USE MMA_D
  IMPLICIT NONE
  REAL, DIMENSION(*) :: x
  REAL, DIMENSION(*) :: xd
  REAL :: v
  REAL :: vd
  REAL :: cv1, cv2
  REAL :: cv1d, cv2d
  COMMON /cc1/ cv1, cv2
  INTRINSIC SUM
  COMMON /cc1_d/ cv1d, cv2d
  zzd = cv1d*cv2 + cv1*cv2d
  zz = cv1*cv2
  vd = SUM(aad)
  v = SUM(aa)
  IF (flag .GT. 2) THEN
    zzd = zzd*v + zz*vd
    zz = zz*v
  END IF
  zzd = zzd + SUM(xd)
  zz = zz + SUM(x)
END SUBROUTINE ROOT_D

MODULE MMA_D
  IMPLICIT NONE
  REAL, DIMENSION(:), ALLOCATABLE :: aa
  REAL, DIMENSION(:), ALLOCATABLE :: aad

CONTAINS
  SUBROUTINE INITA()
    IMPLICIT NONE
    ALLOCATE(aad(20))
    ALLOCATE(aa(20))
  END SUBROUTINE INITA
END MODULE MMA_D

MODULE MMB_D
  IMPLICIT NONE
  INTEGER :: flag
  REAL :: zz
  REAL :: zzd
END MODULE MMB_D

PROGRAM MAIN_CD
  USE MMB_D
  USE MMA_D
  REAL, DIMENSION(:), ALLOCATABLE :: x
  REAL, DIMENSION(:), ALLOCATABLE :: xd
  INTEGER :: i
  REAL :: cvad(2)
  COMMON /cc1_d/ cvad
  REAL :: cva(2)
  COMMON /cc1/ cva
  EXTERNAL GETFLAG
  CALL GETFLAG(flag)
  ALLOCATE(xd(30))
  ALLOCATE(x(30))
  CALL INITA()
  initialize aad,xd,cvad,zzd
  DO i=1,20
    aa(i) = 100.0/i
    x(i) = 3.3*i
  END DO
  cva(1) = 1.8
  cva(2) = 8.1
  CALL ROOT_D(x, xd)
  PRINT*, 'zz=', zz, 'and zzd=', zzd
  DEALLOCATE(aad)
  DEALLOCATE(aa)
  DEALLOCATE(xd)
  DEALLOCATE(x)
END PROGRAM MAIN_CD

• the context must call the differentiated root, hence the call to ROOT_D.
• the context must provide ROOT_D with all the derivatives of its arguments, whether formal parameters or globals. Hence xd, but also aad, /cc1_d/, zzd.
• These new xd, aad, /cc1_d/, zzd must be declared, allocated if their original variable is, and initialized with the derivatives you want.
• After return from ROOT_D, the derivatives in these variables can be used, and the variables must be deallocated if their original variable is.
• One must make sure that these variables are effectively the same in the context and in ROOT_D, which means that when they are globals from modules, the same modules must be used on both sides. Hence the USE MMA_D and USE MMB_D. This also ensures that the "good" INIT_A() is called.
• All these operations need not be done only in MAIN_CD. If MAIN_CD calls utility procedures, you may choose to modify these procedures instead. Make sure to keep all these modified procedures separated from their original definition, and link with the original code only when it was not modified. This also applies to MAIN_CD itself.
• To make sure you don't mix the original context procedures and the new context procedures adapted to ROOT_D, why not give them the same procedure name? This way, the compiler should complain if you mix them. Here MAIN_CD could just remain MAIN. The same could be said for module names MMA_D and MMB_D but that's another story as currently Tapenade systematically appends a _D to them.

• first read our downloading policy, and register either for academic usage or for evaluation usage. You will get a link to a README.html file.
• Looking at the README.html, going to the section about Windows, download the tapenade zip archive into your chosen installation directory "install_dir"
• Go to your chosen installation directory "install_dir", and uncompress TAPENADE.
  
• Copy "install_dir"\bin\tapenade.bat and update the installation parameters: JAVA_HOME, TAPENADE_HOME, and BROWSER.

You have multiple copies of cygwin1.dll on your system.
Search for cygwin1.dll using ...
and delete all but the most recent version. The most recent version *should*
reside in x:\cygwin\bin, where 'x' is the drive on which you have
installed the cygwin distribution.
System: Parsing error 

CHECK THE TANGENT DERIVATIVES WITH RESPECT TO DIVIDED DIFFERENCES:

      "entiere lines between double quotes and drawn in the pattern color"

X+*Xd

       DD"TYPE""SHAPE"("(STRING) variable name",
                 "(FORTRAN TYPE) original variable",
                 "(SAME FORTRAN TYPE) differentiated variable"
                 [,"(INTEGER) array length"])

• "TYPE" is one of real4, real8, etc
• "SHAPE" is ARRAY for an array, and nothing for a scalar.
• The first argument is any string (no white space please!) in principle, you should put the name of the variable you are testing. This name is only used to be printed!
• The second argument is the original variable that you want to test.
• The third argument is its corresponding differentiated variable.
• For arrays, an extra argument gives the total size of the array, i.e. the product of the sizes of all dimensions.

       CALL DDREAL8("x", x, xd)

       CALL DDREAL4ARRAY("T", t, td, 30)

       CALL DDREAL4("T_3_2", t(3,2), td(3,2))

       CALL DDREAL4ARRAY("somepartofT", t(3,1), td(3,1), 5)

       "set all inputs x1, x2, ... to their initial values"
       "set the differentiation tangent direction in x1d, x2d,..."
       CALL F_D(x1, x1d, x2, x2d,..., y1, y1d, y2, y2d,...)
       "use the resulting derivatives y1d, y2d, ..."

       real*8 ddeps, epszero
       integer ddphase, ddfile
       common /DDTESTCOMMON/ ddphase, ddfile, ddeps, epszero

       "set the inputs x1, x2, ... to their initial values"
       "take a snapshot "S" of the initial values of x1, x2,..."
       "set the differentiation tangent direction in variables x1d, x2d,..."
       "take a snapshot "SD" of this initial direction x1d, x2d,..."
       ddeps = 1.d-5
       "set the inputs x1, x2, ... to a value "plus ""
       x1 = x1 + ddeps*x1d
       ...
       epszero = 0.00000001
       ddphase = 1
       ddfile = 37
       OPEN(37, FILE='epsvalues')
       CALL F_D(x1, x1d, x2, x2d,..., y1, y1d, y2, y2d,...)
       CLOSE(37)
       "reset the inputs x1, x2, ... to their initial values, using "S""
       "reset the differentiation tangent direction in x1d, x2d,...using "SD""
       ddphase = 2
       OPEN(37, FILE='epsvalues')
       CALL F_D(x1, x1d, x2, x2d,..., y1, y1d, y2, y2d,...)
       CLOSE(37)

   $> tapenade -d -traceactivevars "units" ...

   $> tapenade -d -traceactivevars %all% ...

CHECK THE REVERSE DERIVATIVES USING THE DOT-PRODUCT TEST:

      "entiere lines between double quotes and drawn in the pattern color"

   $> tapenade -d -head F -dptest "F" ...
   $> tapenade -b -head F -dptest "F" ...

       INTEGER dpunitcallcount,dptriggercount
       COMMON /DPCALLCOUNT/dpunitcallcount,dptriggercount

       "set the inputs x1, x2, ... to their initial values"
       "take a snapshot "S" of the initial values of x1, x2,..."
       "set the differentiation tangent direction in x1d, x2d,..."
       dptriggercount = 1
       CALL F_D(x1, x1d, x2, x2d,..., y1, y1d, y2, y2d,...)
       "reset the inputs x1, x2, ... to their initial values, using "S""
       "assign the y1d, y2d, ... into y1b, y2b,..."
       CALL F_B(x1, x1b, x2, x2b,..., y1, y1b, y2, y2b,...)
       CALL DPPRINTSUMMARY()

   $> tapenade -d -head F -dptest "G" ...
   $> tapenade -b -head F -dptest "G" ...

       dptriggercount = 1

       dptriggercount = 12

• Declarations messages
  DD01,DD02,DD03,DD04,DD05,DD06, DD07,DD08,DD09,DD10,DD11,DD12, DD13
• Type messages
  TC01,TC02,TC03,TC04, TC05,TC06,TC07,TC08,TC09, TC10,TC11,TC12,TC13,TC14, TC15,TC16,TC17,TC18,TC19, TC20,TC21,TC22,TC23,TC24, TC25,TC26,TC27,TC28,TC29, TC30,TC31,TC32,TC33,TC34, TC35,TC36,TC37,TC38, TC40,TC41,TC42, TC50,TC51,TC52
• Control flow messages
  CF01,CF02,CF03,CF04,CF05
• Data flow messages
  DF01,DF02,DF03,DF04
• Automatic Differentiation messages
  AD01,AD02,AD03,AD04,AD05,AD06, AD07,AD08,AD09, AD10

• Declarations problems:
  

  (DD01)	Cannot combine successive declarations of variable var: Type1 and Type2 (ignored new)
  (DD02)	Cannot combine successive declarations of character array: Type1 and Type2 (ignored new)
  (DD03)	Cannot combine successive declarations of constant const type: Type1 and Type2 (ignored new)
  (DD04)	Double definition of function Func (ignored new)
  (DD05)	Cannot combine successive declarations of function Func (ignored new)
  (DD06)	Cannot combine successive declarations of function Func return type: Type1 and Type2 (overwritten previous)
  (DD07)	Cannot combine successive declarations of function Func kind: kind1 and kind2 (ignored new)
  (DD08)	Double declaration of external function Func
  (DD09)	Double declaration of intrinsic function Func
  (DD10)	Double declaration of the main program: Func1 and Func2 (overwritten previous)
  (DD11)	Double declaration of function Func in library file LibraryFile
  (DD12)	Cannot combine successive declarations of type Type (ignored new)
  (DD13)	Double definition of label label (ignored new)

  
  There are two successive definitions or partial declarations of some symbol, as a variable, constant, type, label or function name. These successive declarations occur in the same scope and do not combine into a coherent declaration for the symbol. TAPENADE therefore chooses either to ignore the new piece of declaration, or to overwrite the previous piece of declaration, as indicated by the message. For DD08 and DD09, the two choices are equivalent.
  
  Why should you care? TAPENADE chooses to ignore the indicated declaration or part of your original program. Therefore the types considered by TAPENADE may not be the ones you expect, or the program actually differentiated may differ from the program you think. In particular when types are concerned, remember that differentiation occurs only on REAL (or COMPLEX) typed variables. Therefore some variable may have no derivative whereas you think it should have one. Also for DD13 or DD10, the flow of control may be different from what you think, or from what your local compiler used to build. Also for DD11, some information that you give about an external function may be ignored and replaced by another one.
  
  What can you do? Remove the declaration or definition in excess, or modify conflicting declarations so that they combine well into the type that you expect. For DD11, clean up the library file by merging the data about a given function into one single entry.
  


• Type problems:
  

  (TC01)	Expression is expected to be numeric, and is here Type
  (TC02)	Expression is expected to be boolean, and is here Type
  (TC03)	Expression is expected to be a record, and is here Type
  (TC04)	Expression is expected to be a pointer, and is here Type
  (TC05)	Expression var is expected to be an array, and is here Type
  (TC06)	Loop index is expected to be integer, and is here Type
  (TC07)	Loop bound is expected to be integer, and is here Type
  (TC08)	Loop times expression is expected to be integer, and is here Type
  (TC09)	Real part of complex constructor is expected to be numeric, and is here Type
  (TC10)	Imaginary part of complex constructor is expected to be numeric, and is here Type
  (TC11)	Argument of arithmetic operator is expected to be numeric, and is here Type
  (TC12)	Array index is expected to be numeric, and is here Type
  (TC13)	Triplet element is expected to be numeric, and is here Type
  (TC14)	Substring index is expected to be numeric, and is here Type
  (TC15)	Argument of logical operator is expected to be boolean, and is here Type

  
  The indicated expression is used in a context which requires some type. Using the available declarations, the type-checker found that this expression actually has a different type, indicated in the message.
  
  Why should you care? This may be the sign of an error in the program. Even if this original program actually compiles and runs well, remember that differentiation occurs only on REAL (or COMPLEX) typed variables. If some sub-expression becomes of another type, there will be no derivative associated, even if you think there should be one. Remember also that these problems make the program non-portable.
  
  What can you do? Check the types. You may also use the appropriate conversion functions. Be aware that when you convert a REAL into an INTEGER, the differentials are reset to zero.
  
  

  (TC16)	Type mismatch in assignment: Type1 receives Type2
  (TC17)	Type mismatch in case: Type1 compared to Type2
  (TC18)	Type mismatch in comparison: Type1 compared to Type2

  
  The two terms in the assignment or comparison, or the switch and case expressions, must have compatible types. Otherwise, the meaning of the instruction is not well defined, and not portable.
  
  Why should you care? This can be the indication for a standard type error and, like above, this can lose derivatives.
  
  What can you do? Check the types. Use conversion functions when appropriate.
  
  

  (TC19)

  Equality test on reals is not reliable

  
  Equality and non-equality are not well defined between REAL's, because they are defined only up to a given "machine precision". Equality test can yield different results on different machines.
  
  Why should you care? As far as AD is concerned, equality tests on REAL's are sometimes used as the stopping criterion for some iterative process. Then it relates to a well-known problem: do the derivatives converge when the function does, and if yes, do they converge at the same speed?
  
  What can you do? Check that this does not impact differentiation. Take care to perform the usual validation tests on the computed derivatives.
  
  

  (TC20)	Variable var is not declared
  (TC21)	No implicit rule available to complete the declaration of variable var
  (TC22)	Variable var, declared implicitly as Type1, is used as Type2
  (TC23)	Symbol var, formerly used as a variable, now used for another object
  (TC24)	Wrong number of dimensions for array Array: n2 expected, and n1 given
  (TC25)	Dimensions mismatch in vector expression, Type1 combined with Type2
  (TC26)	Incorrect equivalence
  (TC27)	End of common /COMMON/ reached before variable var
  (TC28)	Variable var cannot be added to common /COMMON1/ because it is already in common /COMMON2/
  (TC29)	Common /COMMON1/ declared with two different sizes: s1 vs s2
  (TC30)	Type mismatch in argument Arg of function Func, expects Type1, receives Type2
  (TC31)	Type mismatch in argument Arg of function Func, declared Type1, previously given Type2
  (TC32)	Wrong number of arguments calling Func: n2 expected, and n1 given

  
  These messages indicate conflicts between declaration and usage of some variable. Message TC25 occurs in the context of vectorized programs. Messages TC26 to TC29 indicate a problem in EQUIVALENCE's and COMMON's. Recall that variables in a COMMON are stored contiguously, so that their relative order cannot be changed, and extra variables cannot be inserted occasionaly. Also a variable cannot be in two different COMMON's, and one cannot set an EQUIVALENCE between two variables that already have their own, different, memory space allocated. Messages TC30 to TC32 indicate a mismatch between the formal and actual parameters of a function. Recall that the standards require that formal and actual parameters match in number and size.
  
  Why should you care? In general, if you let the system choose the type of a variable, you run the risk that it becomes REAL while you don't want, or the other way round. And this in turn impacts differentiation. Messages TC24, and TC26 to TC32 are even more serious: They can indicate that the code relies on FORTRAN weak typing to perform hidden equivalence's between two arrays, or to resize, reshape, or split an array into pieces. Since TAPENADE cannot possibly understand what is intended, it might not propagate differentiability and derivatives from the old array shape to the new array shape.
  
  What can you do? Declare variables explicitly. Try to avoid the "implicit" declaration facility. Declare arrays with their actual size (not "1"). Never resize, reshape, or split arrays implicitly through parameter passing, and avoid to do so across COMMON's
  
  

  (TC33)	Intrinsic function Func is not declared
  (TC34)	External function Func is not declared

  
  These messages indicate that you did not provide TAPENADE with the sources of the indicated procedures.
  
  Why should you care? If TAPENADE doesn't see the source of a called procedure, it is obliged to make several worst-case assumptions about it. Moreover, it this procedure must be differentiated, TAPENADE can't do it. You will have to do it yourself. In some cases this can be profitable because an expert user can do a better job than TAPENADE.
  
  What can you do? If you just forgot the procedure's source file, add it to the list of source files. If the procedure is missing for a good reason, first give TAPENADE type and data-flow information about the missing procedures, using either a dummy source procedure, or using our library mechanism. This can only make things better, as the conservative worst-case assumptions often have a negative impact. Then think about these missing procedures: if it turns out they will have a derivative, you will have to provide this derivative: message AD09 will remind you of that later. In the best situation, you are able to write an analytic differentiated code yourself. In the worst situation, you may use divided differences for the derivative of this unknown procedure, but this will loose some accuracy!
  
  

  (TC35)	Subroutine Func used as a function
  (TC36)	Type function Func used as a subroutine
  (TC37)	Return type of Func set by implicit rule to Type

  
  These messages indicate conflicts between declaration and usage of some function. Programs with messages TC35 and TC36 should not compile.
  
  Why should you care? In general, if you let the system choose the return type of a function, you run the risk that it becomes REAL while you don't want, or the other way round. And this in turn impacts differentiation.
  
  What can you do? Insert the correct declaration.
  
  

  (TC38)

  Recursivity: Func1-->Func2-->...-->FuncN

  
  Recursivity is when a subroutine Func1 calls a subroutine Func2, which itself calls a subroutine Func3, and so on, and when this eventually leads to calling Func1 again. In other words this is a cycle in the call graph. Basically, this is not an error, although FORTRAN77 used to forbid recursive programs.
  
  Why should you care? It is just a matter of time. Recursive programs are harder to analyze. We are progressively updating TAPENADE analyses so that they cope with recursivity.
  
  What can you do? In the meantime, check that the resulting derivatives are correct, using the classical tests.
  
  

  (TC40)	No field named name in Type
  (TC41)	Recursive type definition

  
  These are illegal uses of types. TC40 says the program looks for a field name which does not exist, and TC41 that some types directly contains a field of the same type, thus yielding an infinite size!
  
  Why should you care? It is surprising is the original program actually compiles! Differentiation is undefined.
  
  What can you do? Rewrite the definitions of these types.
  
  

  (TC42)

  Definition of type Type comes a little too late

  
  The definition of the type came after it was used. This is just a warning, because TAPENADE will do as if the definition was done in due time. But you should better fix this.
  
  

  (TC50)	Label label is not defined
  (TC51)	Label variable var must be written by an ASSIGN-TO construct
  (TC52)	Variable var used in assigned-GOTO is not a label variable

  
  These are illegal uses of labels, or label variables.
  
  Why should you care? If labels are misunderstood, the final flow of control that TAPENADE understands and regenerates might not be the one you expect. Therefore TAPENADE does not differentiate the program you expect.
  
  What can you do? Define the labels you use. Use the correct constructs to manipulate label variables.
  
  


• Control flow problems:
  

  (CF01)	Irreducible entry into loop
  (CF02)	Computed-GOTO without legal destinations list
  (CF03)	This assigned-GOTO to var goes nowhere
  (CF04)	This assigned-GOTO to var only goes to label label
  (CF05)	This assigned-GOTO to var is possibly undefined

  
  These messages indicate problems in the flow of control of the program. Message CF01 comes from jumps that go from outside to inside a loop, without going through the loop control header. The meaning of this is not well defined and is probably implementation dependent.
  
  Why should you care? Of course a bad control of a program yields a bad control of its differentiated programs.
  
  What can you do? Avoid irreducible loops. Avoid jumps into loops and into branches of a conditional structure. Try to use structured programming instead. If an assigned-GOTO goes to only one place, at least replace it by a GOTO.
  


• Data flow problems:
  

  (DF01)	Illegal non-reference value for output argument Arg of function Func
  (DF02)	Potential aliasing in calling function Func, between arguments arguments
  (DF03)	Variable var is used before initialized
  (DF04)	Variable var may be used before initialized

  
  These problems are detected through the built-in interprocedural data-flow analysis of TAPENADE.
  
  Why should you care? Programs with DF01 usually provoke segmentation faults. Aliasing (DF02) is a major source of errors for DIfferentiation in the reverse mode, as described in more detail in the "Aliasing" section. Uninitialized variables lead to uninitialized derivatives.
  
  What can you do? Output formal arguments of a subroutine must be passed reference (i.e. writable) actual arguments. It is better to avoid aliasing. When aliasing is really a problem, one can easily avoid it by introducing temporary variables, so that memory locations of the parameters do not overlap. Variables should be initialized before they are used.
  


• Automatic Differentiation problems:
  

  (AD01)	Actual argument Arg of Func is active while formal argument is non-differentiable
  (AD02)	Actual output Arg of Func is useful while formal result is non-differentiable

  
  These two messages are usually associated. They indicate the following situation: Some programs implicitly convert REAL's to INTEGER's during a function call, then these INTEGERS follow their way through the code, and finally are converted back into REAL's during another function call.
  
  Why should you care? If the original REAL's are active, i.e. depend on the independent input variables, and the final REAL's are useful, i.e. influence the dependent output variables, then this temprary conversion into INTEGER's has lost differentiability and derivatives. Differentiability is lost, derivatives are wrong!
  
  What can you do? REAL's must remain REAL's. If absolutely necessary, there is a "secret" option in TAPENADE to actually differentiate these strange REAL-INTEGER's...
  
  

  (AD03)	Active variable var written by I-O to file file
  (AD04)	Useful variable var read by I-O from file file

  
  This is comparable to the above AD01 and AD02. These two messages are usually associated or, to put it differently, if the two messages occur for the same differentiation session, then there is a risk. The risk occurs in the following situation: Some programs write intermediate REAL values into a file and later on, read back these REAL values from this file. This process looses differentiability.
  
  Why should you care? If the written value is active, i.e. depends on the independent input variables, and the corresponding (equal) value read is useful, i.e. influences the dependent output variables, then this temporary storage into a file has lost differentiability and derivatives. Differentiability is lost, derivatives are wrong!
  For instance if the code looks like:

  
        subroutine TOP(x,y,fileno)
        real x,y,tmp
        integer fileno
        write(fileno,*) x
        ...
        read(fileno,*) tmp
        y = 2.0*x + tmp
        end
  

  Tapenade cannot find the dependency path that goes from the input x through de file "fileno" and finally to the output y. if xd is 1.0 yd will be 2.0, whereas the correct answer should be 3.0.
  
  What can you do? Do not use files as temporary storage. Use arrays instead. You may also use TAPENADE "Black-box" mechanism to disconnect differentiation on the calling subroutines, and differentiate them by hand, with an ad-hoc mechanism to propagate derivatives.
  
  

  (AD05)

  Active variable var overwritten by I-O

  
  This reminds you that a variable that was active has been overwritten by an I-O operation
  
  Why should you care? The derivative is of course reset to zero. Maybe this is not what you expected?
  
  What can you do? Check that it is OK. Otherwise try to put all I-O operations outside the part of the program you are actually differentiating.
  
  

  (AD06)	Differentiate of function Func needs to save undeclared side-effect variables: variables
  (AD07)	This call needs to save undeclared side-effect variable: extern-var
  (AD10)	call to Proc2 in differentiation of procedure Proc1 need to save and restore the I-O state

  
  These messages all indicate that the checkpointing mechanism is not certain that it can do a correct job. These messages point at (a collection) of procedure calls in the program, e.g. all calls to Func, or one particular call, or procedure (i.e. subroutine or function) Proc1 calling another procedure (i.e. subroutine or function) Proc2.
  
  In reverse mode, the standard strategy of Tapenade is to checkpoint all procedure calls (cf a quick description of checkpointing, or Tapenade User's guide for something more technical). Checkpointing a call to Proc2 inside Proc1 means that the reverse differentiated subroutine of Proc1 is going to call Proc2 twice, or more precisely the original Proc2 once and then the differentiated Proc2. Roughly speking, these two calls must be made with the same inputs, so that the 2nd call is an exact duplication of the 1st call. To do this, a minimal "environment" needs to be stored just before the 1st call to Proc2 and restored just before the 2nd call. We know how to save and restore most variables, e.g. the formal parameters of Proc2, but also the globals known by Proc1 and Proc2. On the other hand, we don't know how to save and restore hidden SAVE variables, or private global variables of a module, or a COMMON which is not declared at the calling subroutine level, or the position of the read/write pointer inside an opened file which is being read/written, or the very open/close status of a file, and several other things... These messages just signal such (possibly) nasty situations.
  
  Why should you care? Checkpointing cannot restore the environment before the second call to Proc2. Therefore the differentiated program might be wrong.
  
  What can you do? Either make absolutely sure that this is not a problem in the present case, because you know that the second call to Proc2 will behave just like the 1st one, at least as far as differentiation is concerned. You need to know the code for that because errors will be hard to track down. For instance, one favorable situation is when the (AD10) message corresponds only to prints of messages on the screen. The messages will appear twice, but derivatives should be correct.
  Or modify your code so that the problem disappears, for instance insert the COMMON declaration at the level of the calling subroutine. or transform the SAVE variables into elements of a COMMON that everyone can see, or take the file I/O or dynamic memory allocation or deallocation outside the code to differentiate,
  Or (more high-tech!) tell Tapenade not to checkpoint the calls that raise the problem using the "nocheckpoint" directive.
  
  

  (AD08)

  Don't know the size of dimension n of array array, which must be saved

  
  In some cases, for example in reverse-mode AD, the differentiated function must save some variables, to restore them later. If one such variable is an array, and the size of this array is dynamic, TAPENADE must know this size to actually do the save.
  
  Why should you care? If you don't give this size, the differentiated program will not compile.
  
  What can you do? Define the value of the PARAMETERS that TAPENADE requests, in a special include file. You may also explicitly give this size in the original file, so that the message does not show up!
  
  

  (AD09)

  Please provide a differential of function Func for arguments arguments

  
  You must provide the differentiated program with a new function, differentiated from Func with respect to the input and output parameters of Func specified in the arguments. Probably Func is an external function, for which TAPENADE has no source, and therefore it couldn't differentiate it.
  
  Why should you care? If you don't give this new function, the differentiated program will probably not compile.
  
  What can you do? Define this new function. You have the choice of the method. Maybe you know explicitly the derivative mathematical function, which can be implemented efficiently. Maybe you have the source and you may use AD again, with TAPENADE or with another tool. Maybe you just want to run a local "divided differences" method, knowing that this might slightly degrade the precision of the derivatives. In any case, make sure that you provide a differentiated function in the correct mode (tangent, reverse...), and which adheres to the conventions of TAPENADE about the name of the function and the order of its parameters.