Home Contact Us Site Map  
 
       
    next up previous contents
Next: 3.19.3 Compiling the model Up: 3.19 Sensitivity of Air-Sea Previous: 3.19.1 Overview of the   Contents

Subsections

3.19.2 Code configuration

The model configuration for this experiment resides under the directory verification/carbon/. The code customization routines are in verification/carbon/code/:

  • .genmakerc
  • COST_CPPOPTIONS.h
  • CPP_EEOPTIONS.h
  • CPP_OPTIONS.h
  • CTRL_OPTIONS.h
  • ECCO_OPTIONS.h
  • SIZE.h
  • adcommon.h
  • tamc.h
The runtime flag and parameters settings are contained in verification/carbon/input/, together with the forcing fields and and restart files:
  • data
  • data.cost
  • data.ctrl
  • data.gmredi
  • data.grdchk
  • data.optim
  • data.pkg
  • eedata
  • topog.bin
  • windx.bin, windy.bin
  • salt.bin, theta.bin
  • SSS.bin, SST.bin
  • pickup*
Finally, the file to generate the adjoint code resides in $ adjoint/ $ :
  • makefile

Below we describe the customizations of this files which are specific to this experiment.

3.19.2.1 File .genmakerc

This file overwrites default settings of genmake. In the present example it is used to switch on the following packages which are related to automatic differentiation and are disabled by default:
set ENABLE=( autodiff cost ctrl ecco gmredi grdchk kpp )
Other packages which are not needed are switched off:
set DISABLE=( aim obcs zonal_filt shap_filt cal exf )

3.19.2.2 File COST_CPPOPTIONS.h, CTRL_OPTIONS.h

These files used to contain package-specific CPP-options (see Section ref:ask-the-author). For technical reasons those options have been grouped together in the file ECCO_OPTIONS.h. To retain the modularity, the files have been kept and contain the standard include of the CPP_OPTIONS.h file.

3.19.2.3 File CPP_EEOPTIONS.h

This file contains 'wrapper'-specific CPP options. It only needs to be changed if the code is to be run in a parallel environment (see Section ref:ask-the-author).

3.19.2.4 File CPP_OPTIONS.h

This file contains model-specific CPP options (see Section ref:ask-the-author). Most options are related to the forward model setup. They are identical to the global steady circulation setup of verification/global_ocean.90x40x15/. The three options specific to this experiment are
#define ALLOW_PASSIVE_TRACER
This flag enables the code to carry through the advection/diffusion of a passive tracer along the model integration.
#define ALLOW_MIT_ADJOINT_RUN
This flag enables the inclusion of some AD-related fields concerning initialization, link between control variables and forward model variables, and the call to the top-level forward/adjoint subroutine adthe_main_loop instead of the_main_loop.
#define ALLOW_GRADIENT_CHECK
This flag enables the gradient check package. After computing the unperturbed cost function and its gradient, a series of computations are performed for which
$ \bullet$ an element of the control vector is perturbed
$ \bullet$ the cost function w.r.t. the perturbed element is computed
$ \bullet$ the difference between the perturbed and unperturbed cost function is computed to compute the finite difference gradient
$ \bullet$ the finite difference gradient is compared with the adjoint-generated gradient. The gradient check package is further described in Section ???.

3.19.2.5 File ECCO_OPTIONS.h

The CPP options of several AD-related packages are grouped in this file:

  • Overall ECCO-related execution modus:
    These determine whether a pure forward run, a sensitivity run or an iteration of optimization is performed. These options are not needed in the present context.
  • Adjoint support package: pkg/autodiff/
    This package contains hand-written adjoint code such as active file handling, flow directives for files which must not be differentiated, and TAMC-specific header files.
    #define ALLOW_AUTODIFF_TAMC
    defines TAMC-related features in the code.
    #define ALLOW_TAMC_CHECKPOINTING
    enables the checkpointing feature of TAMC (see Section ref:ask-the-author). In the present example a 3-level checkpointing is implemented. The code contains the relevant store directives, common block and tape initializations, storing key computation, and loop index handling. The checkpointing length at each level is defined in file tamc.h, cf. below. The out and intermediate loop directivs are contained in the files checkpoint_lev3_directives.h, checkpoint_lev2_directives.h (package pkg/autodiff).
    #define ALLOW_AUTODIFF_MONITOOR
    enables the monitoring of intermediate adjoint variables (see Section ref:ask-the-author).
    #define ALLOW_DIVIDED_ADJOINT
    enables adjoint dump and restart (see Section ref:ask-the-author).
  • Cost function package: pkg/cost/
    This package contains all relevant routines for initializing, accumulating and finalizing the cost function (see Section ref:ask-the-author).
    #define ALLOW_COST
    enables all general aspects of the cost function handling, in particular the hooks in the forward code for initializing, accumulating and finalizing the cost function.
    #define ALLOW_COST_TRACER
    includes the call to the cost function for this particular experiment, eqn. (3.95).
  • Control variable package: pkg/ctrl/
    This package contains all relevant routines for the handling of the control vector. Each control variable can be enabled/disabled with its own flag:
    #define ALLOW_THETA0_CONTROL initial temperature
    #define ALLOW_SALT0_CONTROL initial salinity
    #define ALLOW_TR0_CONTROL initial passive tracer concentration
    #define ALLOW_TAUU0_CONTROL zonal wind stress
    #define ALLOW_TAUV0_CONTROL meridional wind stress
    #define ALLOW_SFLUX0_CONTROL freshwater flux
    #define ALLOW_HFLUX0_CONTROL heat flux
    #define ALLOW_DIFFKR_CONTROL diapycnal diffusivity
    #undef ALLOW_KAPPAGM_CONTROL isopycnal diffusivity

3.19.2.6 File SIZE.h

The file contains the grid point dimensions of the forward model. It is identical to the verification/exp2/:
sNx = 90
sNy = 40
Nr = 20
It corresponds to a single-tile/single-processor setup: nSx = nSy = 1, nPx = nPy = 1, with standard overlap dimensioning OLx = OLy = 3.

3.19.2.7 File adcommon.h

This file contains common blocks of some adjoint variables that are generated by TAMC. The common blocks are used by the adjoint support routine addummy_in_stepping which needs to access those variables:

common /addynvars_r/ is related to DYNVARS.h
common /addynvars_cd/ is related to DYNVARS.h
common /addynvars_diffkr/ is related to DYNVARS.h
common /addynvars_kapgm/ is related to DYNVARS.h
common /adtr1_r/ is related to TR1.h
common /adffields/ is related to FFIELDS.h

Note that if the structure of the common block changes in the above header files of the forward code, the structure of the adjoint common blocks will change accordingly. Thus, it has to be made sure that the structure of the adjoint common block in the hand-written file adcommon.h complies with the automatically generated adjoint common blocks in adjoint_model.F. The header file is enabled via the CPP-option ALLOW_AUTODIFF_MONITOR.

3.19.2.8 File tamc.h

This routine contains the dimensions for TAMC checkpointing and some indices relevant for storing ky computations.

  • #ifdef ALLOW_TAMC_CHECKPOINTING
    3-level checkpointing is enabled, i.e. the timestepping is divided into three different levels (see Section ref:ask-the-author). The model state of the outermost (nchklev_3) and the intermediate (nchklev_2) timestepping loop are stored to file (handled in the_main_loop). The innermost loop (nchklev_1) avoids I/O by storing all required variables to common blocks. This storing may also be necessary if no checkpointing is chosen (nonlinear functions, if-statements, iterative loops, ...). In the present example the dimensions are chosen as follows:
    nchklev_1 = 36
    nchklev_2 = 30
    nchklev_3 = 60
    To guarantee that the checkpointing intervals span the entire integration period the following relation must be satisfied:
    nchklev_1*nchklev_2*nchklev_3 $ \ge $ nTimeSteps
    where nTimeSteps is either specified in data or computed via
    nTimeSteps = (endTime-startTime)/deltaTClock .
  • #undef ALLOW_TAMC_CHECKPOINTING
    No checkpointing is enabled. In this case the relevant counter is nchklev_0. Similar to above, the following relation has to be satisfied
    nchklev_0 $ \ge $ nTimeSteps.

The following parameters may be worth describing:
isbyte
maxpass
 

3.19.2.9 File makefile

This file contains all relevant parameter flags and lists to run TAMC or TAF. It is assumed that TAMC is available to you, either locally, being installed on your network, or remotely through the 'TAMC Utility'. TAMC is called with the command tamc followed by a number of options. They are described in detail in the TAMC manual Giering [1999]. Here we briefly discuss the main flags used in the makefile. The standard output for TAF is written to file taf.log.

tamc
-input <variable names> -output <variable name> -i4 -r4 ...
-toplevel <S/R name> -reverse <file names>
taf
-input <variable names> -output <variable name> -i4 -r4 ...
-toplevel <S/R name> -reverse <file names>
-flow taf_flow.log -nonew_arg
  • -toplevel <S/R name>
    Name of the toplevel routine, with respect to which the control flow analysis is performed.
  • -input <variable names>
    List of independent variables $ u$ with respect to which the dependent variable $ J$ is differentiated.
  • -output <variable name>
    Dependent variable $ J$ which is to be differentiated.
  • -reverse <file names>
    Adjoint code is generated to compute the sensitivity of an independent variable w.r.t. many dependent variables. In the discussion of Section ??? the generated adjoint top-level routine computes the product of the transposed Jacobian matrix $ M^T $ times the gradient vector $ \nabla_v J $ .
    <file names> refers to the list of files .f which are to be analyzed by TAMC. This list is generally smaller than the full list of code to be compiled. The files not contained are either above the top-level routine (some initializations), or are deliberately hidden from TAMC, either because hand-written adjoint routines exist, or the routines must not (or don't have to) be differentiated. For each routine which is part of the flow tree of the top-level routine, but deliberately hidden from TAMC (or for each package which contains such routines), a corresponding file .flow exists containing flow directives for TAMC.
  • -i4 -r4
     
  • -flow taf_flow.log
    Will cause TAF to produce a flow listing file named taf_flow.log in which the set of active and passive variables are identified for each subroutine.
  • -nonew_arg
    The default in the order of the parameter list of adjoint routines has changed. Before TAF 1.3 the default was compatible with the TAMC-generated list. As of TAF 1.3 the order of adjoint routine parameter lists is no longer copatible with TAMC. To restore compatibility when using TAF 1.3 and higher, this argument is needed. It is currently crucial to use since all hand-written adjoint routines refer to the TAMC default.

3.19.2.10 The input parameter files

3.19.2.10.1 File data

3.19.2.10.2 File data.cost

3.19.2.10.3 File data.ctrl

3.19.2.10.4 File data.gmredi

3.19.2.10.5 File data.grdchk

3.19.2.10.6 File data.optim

3.19.2.10.7 File data.pkg

3.19.2.10.8 File eedata

3.19.2.10.9 File topog.bin

 
Contains two-dimendional bathymetry information

3.19.2.10.10 File windx.bin, windy.bin, salt.bin, theta.bin, SSS.bin, SST.bin

 
These contain the initial values (salinity, temperature, salt.bin, theta.bin), surface boundary values (surface wind stresses, (windx.bin, windy.bin), and surface restoring fields (SSS.bin, SST.bin).

3.19.2.10.11 File pickup*

 
Contains model state after model spinup.

next up previous contents
Next: 3.19.3 Compiling the model Up: 3.19 Sensitivity of Air-Sea Previous: 3.19.1 Overview of the   Contents
mitgcm-support@mitgcm.org
Copyright © 2006 Massachusetts Institute of Technology Last update 2018-01-23