TAMC man page

       tamc - TAMC Tangent linear and Adjoint Model Compiler


       tamc [OPTIONS] <files>


       TAMC  is a source to source translator for Fortran-77 pro-
       grams.  It constructs code to compute derivatives  in  the
       forward  and  reverse  mode.  The input must correspond to
       the ANSI FORTRAN-77 standard.  Some FORTRAN-90  extensions
       are already implemented (DO ENDDO, WHERE).

       Old  style  Fortran  statements (assigned goto, arithmetic
       if, computed goto) will not be accepted.  The GOTO command
       will  be accepted but a warning will be given if it occurs
       inside an active routine, because in this case the adjoint
       code  cannot be constructed.  Other restriction are due to
       the simple scanner and parser.


       All switches are turned on by the option and turned off by
       the option having a no in front.

       -help  A short description about the options is given.

       -l <file>
              This  option  sets  the  name  of a listing file on
              which TAMC will write flow information  about  each
              routine (default no listing).

       -u     Set all variables undefined by default.

       -i2    Make integers be two bytes by default

       -i4    Make integers be four bytes by default

       -i8    Make integers be eight bytes by default

       -r4    Make reals be four bytes by default

       -r8    Make reals be eight bytes by default

       -e     Accept  extended source lines, up to 132 characters

       -N <col>
              Specifies the line width, in columns.

       -U     Distinguish between upper and lower case letters.

       -V     Print version and date

              Specifies the maximal number of errors being  docu-

       -toplevel <name>
              Define the name of the subroutine to be differenti-
              ated (top level routine).  If the name is MODEL  or
              FUNC  all arguments of it will also be arguments of
              the adjoint subroutine  ADMODEL.   This  ensures  a
              preliminary  known  argument list of MODEL (used by

       -input <names>
              Define the independent variables  (blank  separated
              list  of names, given as a string).  If this option
              is missing all arguments of the top  level  routine
              are assumed to be independent.  The dependent vari-
              ables are differentiated with respect to the  inde-
              pendent variables.

       -output <names>
              Define  the  dependent  variables  (blank separated
              list of names, given as a string).  If this  option
              is  missing  all arguments of the top level routine
              are assumed to  be  dependent.   The  corresponding
              adjoint variables are NOT initialized, because they
              contain the vector,  which  is  multiplied  by  the
              jacobian matrix.

              Contruct code to compute derivatives in the reverse

              This option is a synonym for -reverse.

              Contruct code to  compute  derivatives  in  forward
              mode.   The  code  computes the dependent variables
              and the derivatives of  the  independent  variables
              (tangent linear adn function code).

       -pure  By  default, the adjoint top level routine computes
              the dependent variables and the derivatives.  Using
              this  option, the adjoint code computes derivatives
              only.  If tapes are used, they must be written pre-
              viously  by  a  call of the modified top-level rou-

       -jacobian <int>
              Per default TAMC generates code, which computes the
              product  of  the  Jacobian with one vector from the
              left (-adjoint,  -reverse,  reverse  mode)  or  the
              the  reverse mode is used and this number is set to
              the number of dependent variables the full Jacobian
              will  be computed.  Using the forward mode and sup-
              plying the number  of  independent  variables,  the
              full  Jacobian will be computed.  In both cases the
              derivative variables must be initialized  according
              to the identity matrix.

              Append index of extra dimension instead of prepend-
              ing it.

       -ldg   Add leading dimension arguments.

              If set all arguments of the given toplevel  routine
              will  be arguments of the adjoint toplevel routine.
              Thus, the argument list  does  not  depend  on  the
              required  variables  of  the  adjoint  code.   This
              option is on for toplevel routines MODEL and  FUNC.

       -unit <int>
              Lowest  unit  numbers used for direct access I/O to
              store and restore  variables.   If  -nokeepopen  is
              given this unit number will be used for every file.

              If an tape is implemented by a file, the file  will
              only  be  opened  once  an  closed  onced.  If this
              option is given the  file  will  be  opened  before
              every read/write and closed afterwards.  This saves
              buffer memory, but may be slower.

       -split Expressions are split into unary and binary  opera-
              tions before adjoint code is generated.  Using this
              options common subexpressions are avoided by intro-
              ducing auxiliary variables.

                   A  data  dependence  analysis  is  applied  by
              default.       It detects loop carried data  depen-
              dencies             and   categories   the   loops.
                   Adjoint code is  then  generated  accordingly.
                   Switching  off  this  analysis  will result in
                   unnecessary recomputations.

       -auxmark <mark>
              Whenever auxiliary variables are introduced,  there
              names  consist  of  an  existing name and this mark
              (default 'h').  The mark is always appended to  the

              The  names of adjoint variables, common blocks, and
              routines consist of  the  original  name  and  this
              mark.   The default setting 'ad' means, the adjoint
              variable to the variable x will be adx.

       -modmark <mark>
              The names of modified subroutines  consist  of  the
              original  name  and this mark.  The default setting
              'md' means, the modified subroutine  SUB  will  get
              the name MDSUB.

       -ftlmark <mark>
              The  names  of  tangent  linear  variables,  common
              blocks, and routines consist of the  original  name
              and this mark.  The default setting 'g_' means, the
              tangent linear variable to the variable x  will  be

              The mark of derivative variables leads the original
              name  by  default.   If  set,  the  mark  will   be
              appended. Eg the adjoint variable of x will be xad.

       -f90   Read and write Fortran-90 extensions to Fortran-77.
              This option enables -vector, -doendo, -dowhile, and
              -dynamic.  In addition instead of the BLAS1 subrou-
              tine  SSUM (DSUM) the intrinsic Fortran-90 function
              SUM is used in the adjoint code.

       -hpf   Reads and writes High  Performance  Fortran.   This
              options  also enables Fortran-90 extensions (-f90).
              Right  now  only  INDEPENDENT,  DISTRIBUTION,   and
              SHADOW directives are handled.

       -fixed All  input files are in fixed format independent of
              their extension.

       -free  All input files are in Fortran-90 free format.   By
              default  only files with extension .f90 or .F90 are
              read in free format.  This option also enables For-
              tran-90 extensions (-f90).

              If  the  Fortran  compiler  supports dynamic arrays
              TAMC may  generate  local  arrays  with  dimensions
              given as arguments.

              Generate Fortran-90 array assignments.

              Generate Fortran-90 DO ENDDO statements.
              Generate Fortran-90 DO WHILE ENDDO statements.

       -ivdep Write CDIR$ IVDEP directives (default off).

       -direc Directives  readable  by  TAMC  are  written to the
              specified file.

       -info  If this option is turned off  information  will  no
              longer be given.

              If  this  option is turned of warnings will be sup-

              If an condition depends on  the  independent  vari-
              ables  directly  or  indirectly, the mapping to the
              dependent  variables  may  be  non  differentiable.
              Please  note, intrinsic function ABS, MIN, MAX will
              not be noticed yet.


       Directives may be placed in the  source  code.   They  all
       start with CADJ in the first 4 rows.  Thus a standard For-
       tran compiler will accept them as a comment.

       CADJ SUBROUTINE <name> ADNAME = ident
              Set the name of the corresponding  adjoint  subrou-

       CADJ SUBROUTINE <name> MODNAME = ident
              Set the name of a modified subroutine.

       CADJ SUBROUTINE <name> FTLNAME = ident
              Set  the  name  of the corresponding tangent linear

       CADJ SUBROUTINE <name> INPUT  = <ints>

       CADJ SUBROUTINE <name> OUTPUT = <ints>

       CADJ SUBROUTINE <name> ACTIVE = <ints>

       CADJ SUBROUTINE <name> DEPEND = <ints>
              Set the flow of an subroutine not  given  to  TAMC.
              This  is useful to specify the flow of library rou-
              tines.  The arguments referenced by the routine are
              specified  by the keyword INPUT. Arguments computed
              by the routine are specified by the keyword OUTPUT.
              If  the  routine has an corresponding adjoint, then
              ACTIVE defines  the  active  arguments  and  DEPEND

       CADJ SUBROUTINE <name> COMMON <cname> INPUT  = <ints>

       CADJ SUBROUTINE <name> COMMON <cname> OUTPUT = <ints>

       CADJ SUBROUTINE <name> COMMON <cname> ACTIVE = <ints>

       CADJ SUBROUTINE <name> COMMON <cname> DEPEND = <ints>
              The flow information through common  block  can  be
              specified  by  these  directives.  Their meaning is
              similar to those given above.

       CADJ INIT <tape> = <string>
              Defines a tape on disk. For every  variable  stored
              on  this tape a direct access file will be created.
              Note, the string is used as the first part of  file
              names created.

       CADJ INIT <tape> = MEMORY
              Defines a tape implemented as dynamic memory.

       CADJ INIT <tape> = COMMON, <const_int_expr>
              Defines  a  tape implemented by common blocks.  The
              constant   integer   expression    <const_int_expr>
              defines the maximal number of records for one vari-
              able stored on that tape.  This number is  used  to
              define  the  dimension  of  a common block variable
              holding the stored values.  If  the  number  is  to
              small unpredictable runtime errors might occur.

       CADJ STORE <vars> = <tape> [, KEY = <expr>] [, BYTE =
              This directive defines the place  where  the  vari-
              able(s)  should  be stored during function computa-
              tion.  Code will be generated to store and  restore
              the  variable using the specified tape.  Recomputa-
              tions start at the tape initialization.   The  list
              of variables <vars> must be separated by commas.

              Computing the key of a record may be time consuming
              if a call to the subroutine  getkey  is  generated.
              You  can define your own key algorithm by using the
              KEY keyword, where <expr> is the expression  to  be
              used as key.  Please note, in this case it is up to
              you to guarantee an unambiguous key.

              The BYTE extension can be used to define the preci-
              sion  (4  or  8) to be used for storing.  Currently
              this influences only  variables  stored  on  common

              cuted in parallel, insert the directive in front of
              the loop.  The TAMC  will  construct  adjoint  code
              under  the assumption of non existing dependencies.
              The  generated  adjoint  loop  will  computes   the
              adjoint kernel in the original order.

       CADJ LOOP = ITERATION <vars>
              Alternative  adjoint code will be generated by TAMC
              for loops doing an iteration to solve  an  equation
              for  variables  <vars>  (comma separated list).  By
              inserting the directive, the TAMC assumes the equa-
              tion is solved exactly with respect to machine pre-
              cision.  The generated  adjoint  loop  is  also  an
              iteration,  it  solves  the  corresponding  adjoint
              equations.   The  advantage  of   the   alternative
              adjoint  code is, that no variables must be stored.
              At the moment the code is only correct  for  linear


       if -reverse or -adjoint is given

       <file>_ad.f    adjoint and modified code

       if -forward is given

       <file>_ftl.f   function and tangent linear code


       libtamc.a      TAMC library



       R.  Giering: "TAMC users manual", Max-Planck-Institut fuer
       Meteorologie, Hamburg

       R. Giering, T. Kaminski: "Recipes for  Adjoint  Code  Con-
       struction",  Max-Planck-Institut  fuer  Meteorologie, Ham-
       burg, Report No. 212, 1996.

       R. Giering: "AMC: Ein Werkzeug zum automatischen Differen-
       zieren   von   Fortran  Programmen",  Forschung  und  wis-
       senschaftliches Rechnen, GWDG-Bericht Nr. 42, 1996,  Goet-

       R.  Giering,  T.  Kaminski: "Recipes for Adjoint Code Con-
       struction", ACM transaction on Mathematical Software, Vol-
       ume 24, Number 4, Pages 437-474, 1998


Man(1) output converted with man2html