TAMC man page
tamc - TAMC Tangent linear and Adjoint Model CompilerSYNOPSIS
tamc [OPTIONS] <files>DESCRIPTION
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.OPTIONS
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 long. -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- mented. -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 tamlink). -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. -reverse Contruct code to compute derivatives in the reverse mode. -adjoint This option is a synonym for -reverse. -forward 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- tine. -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 Append index of extra dimension instead of prepend- ing it. -ldg Add leading dimension arguments. -arglist 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. -closetapes 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. -depend 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 name. 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 g_x. -postfix 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). -dynamic If the Fortran compiler supports dynamic arrays TAMC may generate local arrays with dimensions given as arguments. -vector Generate Fortran-90 array assignments. -doendo 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. -warning If this option is turned of warnings will be sup- pressed. -warn_step 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
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- tine. 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 subroutine. 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 = <int>] 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 blocks. CADJ LOOP = PARALLEL 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 equations.FILES
if -reverse or -adjoint is given <file>_ad.f adjoint and modified code if -forward is given <file>_ftl.f function and tangent linear codeLIBRARIES
libtamc.a TAMC librarySEE ALSO
tamlink(1) 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- tingen. R. Giering, T. Kaminski: "Recipes for Adjoint Code Con- struction", ACM transaction on Mathematical Software, Vol- ume 24, Number 4, Pages 437-474, 1998AUTHOR
Man(1) output converted with man2html