• 5.2.3.1 The list AD_FILES and .list files
• 5.2.3.2 The list AD_FLOW_FILES and .flow files
• 5.2.3.3 Store directives for 3-level checkpointing
• 5.2.3.4 Changing the default AD tool flags: ad_options files
• 5.2.3.5 Hand-written adjoint code

5.2.3 The AD build process in detail

The make <MODE>all target consists of the following procedures:

1. A header file AD_CONFIG.h is generated which contains a CPP option on which code ought to be generated. Depending on the make target, the contents is
   • #define ALLOW_ADJOINT_RUN
   • #define ALLOW_TANGENTLINEAR_RUN
   • #define ALLOW_ECCO_OPTIMIZATION
2. A single file <MODE>_input_code.f is concatenated consisting of all .f files that are part of the list AD_FILES and all .flow files that are part of the list AD_FLOW_FILES.
3. The AD tool is invoked with the <MODE>_<TOOL>_FLAGS. The default AD tool flags in genmake2 can be overrwritten by an adjoint_options file (similar to the platform-specific build_options, see Section ???. The AD tool writes the resulting AD code into the file <MODE>_input_code_ad.f
4. A short sed script adjoint_sed is applied to <MODE>_input_code_ad.f to reinstate myThid into the CALL argument list of active file I/O. The result is written to file <MODE>_<TOOL>_output.f.
5. All routines are compiled and an executable is generated (see Table ???).

5.2.3.1 The list AD_FILES and .list files

Not all routines are presented to the AD tool. Routines typically hidden are diagnostics routines which do not influence the cost function, but may create artificial flow dependencies such as I/O of active variables.

genmake2 generates a list (or variable) AD_FILES which contains all routines that are shown to the AD tool. This list is put together from all files with suffix .list that genmake2 finds in its search directories. The list file for the core MITgcm routines is in model/src/ is called model_ad_diff.list. Note that no wrapper routine is shown to TAF. These are either not visible at all to the AD code, or hand-written AD code is available (see next section).

Each package directory contains its package-specific list file <PKG>_ad_diff.list. For example, pkg/ptracers/ contains the file ptracers_ad_diff.list. Thus, enabling a package will automatically extend the AD_FILES list of genmake2 to incorporate the package-specific routines. Note that you will need to regenerate the Makefile if you enable a package (e.g. by adding it to packages.conf) and a Makefile already exists.

5.2.3.2 The list AD_FLOW_FILES and .flow files

TAMC and TAF can evaluate user-specified directives that start with a specific syntax (CADJ, C$TAF, !$TAF). The main categories of directives are STORE directives and FLOW directives. Here, we are concerned with flow directives, store directives are treated elsewhere.

Flow directives enable the AD tool to evaluate how it should treat routines that are 'hidden' by the user, i.e. routines which are not contained in the AD_FILES list (see previous section), but which are called in part of the code that the AD tool does see. The flow directive tell the AD tool

• which subroutine arguments are input/output
• which subroutine arguments are active
• which subroutine arguments are required to compute the cost
• which subroutine arguments are dependent

genmake2 generates a list (or variable) AD_FLOW_FILES which contains all files with suffix.flow that it finds in its search directories. The flow directives for the core MITgcm routines of eesupp/src/ and model/src/ reside in pkg/autodiff/. This directory also contains hand-written adjoint code for the MITgcm WRAPPER (see Section ???).

Flow directives for package-specific routines are contained in the corresponding package directories in the file <PKG>_ad.flow, e.g. ptracers-specific directives are in ptracers_ad.flow.

5.2.3.3 Store directives for 3-level checkpointing

The storing that is required at each period of the 3-level checkpointing is controled by three top-level headers.

do ilev_3 = 1, nchklev_3
#  include ``checkpoint_lev3.h''
   do ilev_2 = 1, nchklev_2
#     include ``checkpoint_lev2.h''
      do ilev_1 = 1, nchklev_1
#        include ``checkpoint_lev1.h''

...

      end do
   end do
end do

All files checkpoint_lev?.h are contained in directory pkg/autodiff/.

5.2.3.4 Changing the default AD tool flags: ad_options files

5.2.3.5 Hand-written adjoint code

Copyright © 2002 Massachusetts Institute of Technology