Warning, /doc/examples/tracer_adjsens/tracer_adjsens.rst is written in an unsupported language. File is not indexed.
view on githubraw file Latest commit 0bad585a on 2022-02-16 18:55:09 UTC
1c8cebb321 Jeff*0001 .. _sec_tracer_adj_sens:
0002
0003 Adjoint Sensitivity Analysis for Tracer Injection
0004 =================================================
d67096e55c Jeff*0005
0006 (in directory: :filelink:`verification/tutorial_tracer_adjsens/`)
0007
0008 MITgcm has been adapted to enable AD using TAMC or TAF. The present
0009 description is specific to the use of TAMC or TAF as AD
0010 tool. The following sections describe the steps which are necessary to
0011 generate a tangent linear or adjoint model of MITgcm. We take as an
0012 example the sensitivity of carbon sequestration in the ocean. The
0013 AD-relevant hooks in the code are outlined in :numref:`sec_ad_tlm_and_adm`
0014 and :numref:`sec_ad_finalize_contribtuions`.
0015
0016 Overview of the experiment
0017 --------------------------
0018
0019 We describe an adjoint sensitivity analysis of out-gassing from the
0020 ocean into the atmosphere of a carbon-like tracer injected into the
0021 ocean interior (see Hill et al. 2004 :cite:`hill:04`).
0022
0023 Passive tracer equation
0024 ~~~~~~~~~~~~~~~~~~~~~~~
0025
0026 For this work, MITgcm was augmented with a thermodynamically inactive
0027 tracer, :math:`C`. Tracer residing in the ocean model surface layer is
0028 out-gassed according to a relaxation time scale, :math:`\mu`. Within the
0029 ocean interior, the tracer is passively advected by the ocean model
0030 currents. The full equation for the time evolution
0031
0032 .. math::
0033 \frac{\partial C}{\partial t} \, = \,
0bad585a21 Navi*0034 -\mathbf{U} \cdot \nabla C \, - \, \mu C \, + \, \Gamma(C) \,+ \, S
d67096e55c Jeff*0035 :label: carbon_ddt
0036
0037 also includes a source term :math:`S`. This term represents interior
0038 sources of :math:`C` such as would arise due to direct injection. The
0bad585a21 Navi*0039 velocity term, :math:`\mathbf{U}`, is the sum of the model Eulerian circulation
d67096e55c Jeff*0040 and an eddy-induced velocity, the latter parameterized according to
0041 Gent/McWilliams (Gent and McWilliams 1990 :cite:`gen-mcw:90`; Gent et al. (1995) :cite:`gen-eta:95`). The
0042 convection function, :math:`\Gamma`, mixes :math:`C` vertically wherever
0043 the fluid is locally statically unstable.
0044
0045 The out-gassing time scale, :math:`\mu`, in :eq:`carbon_ddt` is set
0046 so that :math:`1/\mu \sim 1` year for the surface ocean and
0047 :math:`\mu=0` elsewhere. With this value, :eq:`carbon_ddt` is valid
0048 as a prognostic equation for small perturbations in oceanic carbon
0049 concentrations. This configuration provides a powerful tool for
0050 examining the impact of large-scale ocean circulation on CO\ :sub:`2`
0051 out-gassing due to interior injections. As source we choose a constant
0052 in time injection of :math:`S = 1` mol s\ :sup:`-1`.
0053
0054 Model configuration
0055 ~~~~~~~~~~~~~~~~~~~
0056
0057 The model configuration employed has a constant
0058 :math:`4^\circ \times 4^\circ` resolution horizontal grid and realistic
0059 geography and bathymetry. Twenty vertical layers are used with vertical
0060 spacing ranging from 50 m near the surface to 815 m at depth. Driven to
0061 steady-state by climatological wind-stress, heat and fresh-water forcing,
0062 the model reproduces well known large-scale features of the ocean
0063 general circulation.
0064
0065 Out-gassing cost function
0066 ~~~~~~~~~~~~~~~~~~~~~~~~~
0067
0068 To quantify and understand out-gassing due to injections of :math:`C` in
0069 :eq:`carbon_ddt`, we define a cost function :math:`{\cal J}` that
0070 measures the total amount of tracer out-gassed at each timestep:
0071
0072 .. math::
0073 {\cal J}(t=T)=\int_{t=0}^{t=T}\int_{A} \mu C \, dA \, dt
0074 :label: cost_tracer
0075
0076 :eq:`cost_tracer` integrates the out-gassing term,
0077 :math:`\mu C`, from :eq:`carbon_ddt` over the entire ocean surface area,
0078 :math:`A`, and accumulates it up to time :math:`T`. Physically,
0079 :math:`{\cal J}` can be thought of as representing the amount of
0080 CO\ :sub:`2` that our model predicts would be out-gassed following an
0081 injection at rate :math:`S`. The sensitivity of :math:`{\cal J}` to the
0082 spatial location of :math:`S`,
0083 :math:`\frac{\partial {\cal J}}{\partial S}`, can be used to identify
0084 regions from which circulation would cause CO\ :sub:`2` to rapidly
0085 out-gas following injection and regions in which CO\ :sub:`2` injections
0086 would remain effectively sequestered within the ocean.
0087
0088 Code configuration
0089 ------------------
0090
0091 The code customization routines are in
0092 :filelink:`verification/tutorial_tracer_adjsens/code_ad`:
0093
0094 - :filelink:`verification/tutorial_tracer_adjsens/code_ad/COST_OPTIONS.h`
0095
0096 - :filelink:`verification/tutorial_tracer_adjsens/code_ad/CTRL_OPTIONS.h`
0097
0098 - :filelink:`verification/tutorial_tracer_adjsens/code_ad/CPP_OPTIONS.h`
0099
0100 - :filelink:`verification/tutorial_tracer_adjsens/code_ad/AUTODIFF_OPTIONS.h`
0101
0102 - :filelink:`verification/tutorial_tracer_adjsens/code_ad/CTRL_SIZE.h`
0103
0104 - :filelink:`verification/tutorial_tracer_adjsens/code_ad/GAD_OPTIONS.h`
0105
0106 - :filelink:`verification/tutorial_tracer_adjsens/code_ad/GMREDI_OPTIONS.h`
0107
0108 - :filelink:`verification/tutorial_tracer_adjsens/code_ad/SIZE.h`
0109
0110 - :filelink:`verification/tutorial_tracer_adjsens/code_ad/tamc.h`
0111
0112 - :filelink:`verification/tutorial_tracer_adjsens/code_ad/ctrl_map_ini_genarr.F`
0113
0114 - :filelink:`verification/tutorial_tracer_adjsens/code_ad/ptracers_forcing_surf.F`
0115
0116 - :filelink:`verification/tutorial_tracer_adjsens/code_ad/packages.conf`
0117
0118 The runtime flag and parameters settings are contained in :filelink:`verification/tutorial_tracer_adjsens/input/`
0119 and :filelink:`verification/tutorial_tracer_adjsens/input_ad/`, together with the forcing fields and and
0120 restart files:
0121
0122 - :filelink:`verification/tutorial_tracer_adjsens/input_ad/data`
0123
0124 - :filelink:`verification/tutorial_tracer_adjsens/input_ad/data.cost`
0125
0126 - :filelink:`verification/tutorial_tracer_adjsens/input_ad/data.ctrl`
0127
0128 - :filelink:`verification/tutorial_tracer_adjsens/input_ad/data.gmredi`
0129
0130 - :filelink:`verification/tutorial_tracer_adjsens/input_ad/data.grdchk`
0131
0132 - :filelink:`verification/tutorial_tracer_adjsens/input_ad/data.optim`
0133
0134 - :filelink:`verification/tutorial_tracer_adjsens/input_ad/data.pkg`
0135
0136 - :filelink:`verification/tutorial_tracer_adjsens/input_ad/data.ptracers`
0137
0138 - :filelink:`verification/tutorial_tracer_adjsens/input_ad/eedata`
0139
0140 - ``verification/tutorial_tracer_adjsens/input/topog.bin``
0141
0142 - ``verification/tutorial_tracer_adjsens/input/windx.bin``, ``verification/tutorial_tracer_adjsens/inputwindy.bin``
0143
0144 - ``verification/tutorial_tracer_adjsens/input/salt.bin``, ``verification/tutorial_tracer_adjsens/input/theta.bin``
0145
0146 - ``verification/tutorial_tracer_adjsens/input/SSS.bin``, ``verification/tutorial_tracer_adjsens/input/SST.bin``
0147
0148 Below we describe the customizations of this files which are specific to
0149 this experiment.
0150
0151 File :filelink:`code_ad/COST_OPTIONS.h /<verification/tutorial_tracer_adjsens/code_ad/COST_OPTIONS.h>`
0152 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0153
0154 This file contains package-specific CPP-options (see :numref:`pkg_cost_description`).
0155
0156 File :filelink:`code_ad/CTRL_OPTIONS.h /<verification/tutorial_tracer_adjsens/code_ad/CTRL_OPTIONS.h>`
0157 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0158
0159 This file contains package-specific CPP-options (see :numref:`sec:pkg:ctrl`).
0160
0161 File :filelink:`code_ad/CPP_OPTIONS.h /<verification/tutorial_tracer_adjsens/code_ad/CPP_OPTIONS.h>`
0162 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0163
0164 This file contains model-specific CPP options (see :numref:`customize_compilation`).
0165 Most options are related to the forward model
0166 setup. They are identical to the global steady circulation setup of
0167 :filelink:`verification/global_ocean.90x40x15/`. The three options specific to
0168 this experiment are as follows.
0169 ``#define ALLOW_PASSIVE_TRACER`` enables the code to carry through the advection/diffusion of
0170 a passive tracer along the model integration.
0171 ``#define ALLOW_MIT_ADJOINT_RUN`` enables the inclusion of some AD-related fields concerning
0172 initialization, link between control variables and forward model
0173 variables, and the call to the top-level forward/adjoint subroutine
0174 ``adthe_main_loop.F`` instead of :filelink:`model/src/the_main_loop.F`.
0175 ``#define ALLOW_GRADIENT_CHECK`` enables the gradient check package. After computing the
0176 unperturbed cost function and its gradient, a series of computations
0177 are performed for which:
0178
0179 - an element of the control vector is perturbed
0180 - the cost function w.r.t. the perturbed element is computed
0181 - the difference between the perturbed and unperturbed
0182 cost function is computed to compute the finite difference gradient
0183 - the finite difference gradient is compared with the
0184 adjoint-generated gradient.
0185
0186 The gradient check package is further
0187 described in :numref:`ad_gradient_check`.
0188
0189 File ``ECCO_OPTIONS.h``
0190 ~~~~~~~~~~~~~~~~~~~~~~~
0191
0192 The CPP options of several AD-related packages are grouped in this file:
0193
0194 - | Overall ECCO-related execution modus:
0195 | These determine whether a pure forward run, a sensitivity run or an
0196 iteration of optimization is performed. These options are not
0197 needed in the present context.
0198
0199 - | Adjoint support package: :filelink:`pkg/autodiff/`
0200 | This package contains hand-written adjoint code such as active file
0201 handling, flow directives for files which must not be
0202 differentiated, and TAMC-specific header files. ``#define`` :varlink:`ALLOW_AUTODIFF_TAMC`
0203 defines TAMC-related features in the code. ``#define`` :varlink:`ALLOW_TAMC_CHECKPOINTING`
0204 enables the checkpointing feature of TAMC (see :numref:`sec_autodiff_storage_v_recompute`).
0205 In the present example a 3-level checkpointing
0206 is implemented. The code contains the relevant store directives,
0207 common block and tape initializations, storing key computation, and
0208 loop index handling. The checkpointing length at each level is
0209 defined in file :filelink:`code_ad/tamc.h <verification/tutorial_tracer_adjsens/code_ad/tamc.h>`,
0210 see :ref:`below <tut_tracer_adjsens_tamc>`. The out and intermediate loop
0211 directives are contained in the files
0212 :filelink:`pkg/autodiff/checkpoint_lev3_directives.h`, :filelink:`pkg/autodiff/checkpoint_lev2_directives.h`.
0213 ``#define`` :varlink:`ALLOW_AUTODIFF_MONITOR` enables the monitoring of intermediate adjoint variables (see :numref:`sec_autodiff_output_adj_vars`).
0214 ``#define`` :varlink:`ALLOW_DIVIDED_ADJOINT` enables adjoint dump and restart (see :numref:`sec_autodiff_diva`).
0215
0216 - | Cost function package: :filelink:`pkg/cost/`
0217 | This package contains all relevant routines for initializing,
0218 accumulating and finalizing the cost function (see :numref:`pkg_cost_description`).
0219 ``#define`` :varlink:`ALLOW_COST` enables all general aspects of the cost function handling, in
0220 particular the hooks in the forward code for initializing,
0221 accumulating and finalizing the cost function.
0222 ``#define`` :varlink:`ALLOW_COST_TRACER` includes the call to the cost function for this particular
0223 experiment, eqn. :eq:`cost_tracer`.
0224
0225 - | Control variable package: :filelink:`pkg/ctrl/`
0226 | This package contains all relevant routines for the handling of the
0227 control vector. Each control variable can be enabled/disabled with
0228 its own flag:
0229
0230 +-----------------------------------------------+----------------------------------------+
0231 | ``#define`` :varlink:`ALLOW_THETA0_CONTROL` | initial temperature |
0232 +-----------------------------------------------+----------------------------------------+
0233 | ``#define`` :varlink:`ALLOW_SALT0_CONTROL` | initial salinity |
0234 +-----------------------------------------------+----------------------------------------+
0235 | ``#define`` :varlink:`ALLOW_TR10_CONTROL` | initial passive tracer concentration |
0236 +-----------------------------------------------+----------------------------------------+
0237 | ``#define`` :varlink:`ALLOW_TAUU0_CONTROL` | zonal wind stress |
0238 +-----------------------------------------------+----------------------------------------+
0239 | ``#define`` :varlink:`ALLOW_TAUV0_CONTROL` | meridional wind stress |
0240 +-----------------------------------------------+----------------------------------------+
0241 | ``#define`` :varlink:`ALLOW_SFLUX0_CONTROL` | freshwater flux |
0242 +-----------------------------------------------+----------------------------------------+
0243 | ``#define`` :varlink:`ALLOW_HFLUX0_CONTROL` | heat flux |
0244 +-----------------------------------------------+----------------------------------------+
0245 | ``#define`` :varlink:`ALLOW_DIFFKR_CONTROL` | diapycnal diffusivity |
0246 +-----------------------------------------------+----------------------------------------+
0247 | ``#undef`` :varlink:`ALLOW_KAPGM_CONTROL` | isopycnal diffusivity |
0248 +-----------------------------------------------+----------------------------------------+
0249
0250 File :filelink:`SIZE.h <verification/tutorial_tracer_adjsens/code_ad/SIZE.h>`
0251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0252
0253 .. literalinclude:: ../../../verification/tutorial_tracer_adjsens/code_ad/SIZE.h
0254 :linenos:
0255 :caption: verification/tutorial_global_oce_latlon/code/SIZE.h
0256
0257 The file contains the grid point dimensions of the forward model. It
0258 is identical to the :filelink:`verification/exp2/`.
0259
0260 File :filelink:`/pkg/autodiff/adcommon.h`
0261 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0262
0263 This file contains common blocks of some adjoint variables that are
0264 generated by TAMC. The common blocks are used by the adjoint support
0265 routine :filelink:`/pkg/autodiff/addummy_in_stepping.F` which needs to access those variables:
0266
0267 +-------------------------------------------+-------------------------------------------------+
0268 | common /\ :varlink:`addynvars_r`\ / | is related to :filelink:`model/inc/DYNVARS.h` |
0269 +-------------------------------------------+-------------------------------------------------+
0270 | common /\ :varlink:`addynvars_cd`\ / | is related to :filelink:`model/inc/DYNVARS.h` |
0271 +-------------------------------------------+-------------------------------------------------+
0272 | common /\ :varlink:`addynvars_diffkr`\ / | is related to :filelink:`model/inc/DYNVARS.h` |
0273 +-------------------------------------------+-------------------------------------------------+
0274 | common /\ :varlink:`addynvars_kapgm`\ / | is related to :filelink:`model/inc/DYNVARS.h` |
0275 +-------------------------------------------+-------------------------------------------------+
0276 | common /\ :varlink:`adtr1_r`\ / | is related to ``TR1.h`` |
0277 +-------------------------------------------+-------------------------------------------------+
0278 | common /\ :varlink:`adffields`\ / | is related to :filelink:`model/inc/FFIELDS.h` |
0279 +-------------------------------------------+-------------------------------------------------+
0280
0281 Note that if the structure of the common block changes in the above
0282 header files of the forward code, the structure of the adjoint common
0283 blocks will change accordingly. Thus, one must make sure that the
0284 structure of the adjoint common block in the hand-written file
0285 :filelink:`/pkg/autodiff/adcommon.h` complies with the automatically generated adjoint common
0286 blocks in ``adjoint_model.F``. The header file is enabled via the
0287 CPP-option :varlink:`ALLOW_AUTODIFF_MONITOR`.
0288
0289 .. _tut_tracer_adjsens_tamc:
0290
0291 File :filelink:`code_ad/tamc.h <verification/tutorial_tracer_adjsens/code_ad/tamc.h>`
0292 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0293
0294 This routine contains the dimensions for TAMC checkpointing and some
0295 indices relevant for storing ky computations.
0296
0297 - | ``#ifdef`` :varlink:`ALLOW_TAMC_CHECKPOINTING`
0298 | 3-level checkpointing is enabled, i.e., the timestepping is divided
0299 into three different levels (see :numref:`sec_autodiff_storage_v_recompute`). The
0300 model state of the outermost (:varlink:`nchklev_3`) and the intermediate
0301 (:varlink:`nchklev_2`) timestepping loop are stored to file (handled in
0302 :filelink:`model/src/the_main_loop.F`). The innermost loop (:varlink:`nchklev_1`) avoids I/O by
0303 storing all required variables to common blocks. This storing may
0304 also be necessary if no checkpointing is chosen (nonlinear
0305 functions, if-statements, iterative loops, ...). In the present
0306 example the dimensions are chosen as follows:
0307
0308 ::
0309
0310 nchklev_1 = 36
0311 nchklev_2 = 30
0312 nchklev_3 = 60
0313
0314 | To guarantee that the checkpointing intervals span the entire
0315 integration period the following relation must be satisfied:
0316
0317 | :varlink:`nchklev_1` * :varlink:`nchklev_2` * :varlink:`nchklev_3` :math:`\ge` :varlink:`nTimeSteps`
0318
0319 | where :varlink:`nTimeSteps` is either specified in :filelink:`input_ad/data <verification/tutorial_tracer_adjsens/input_ad/data>`
0320 or computed via:
0321
0322 | :varlink:`nTimeSteps` = (:varlink:`endTime` - :varlink:`startTime` )/ :varlink:`deltaTClock`.
0323
0324 - | ``#undef`` :varlink:`ALLOW_TAMC_CHECKPOINTING`
0325 | No checkpointing is enabled. In this case the relevant counter is
0326 :varlink:`nchklev_0`. Similar to above, the following relation has to be
0327 satisfied:
0328
0329 | :varlink:`nchklev_0` :math:`\ge` :varlink:`nTimeSteps`
0330
0331 The following parameters may be worth describing: :varlink:`isbyte`, :varlink:`maxpass`.
0332
0333 File ``makefile``
0334 ~~~~~~~~~~~~~~~~~
0335
0336 This file contains all relevant parameter flags and lists to run TAMC or
0337 TAF. It is assumed that TAMC is available to you, either locally, being
0338 installed on your network, or remotely through the ’TAMC Utility’. TAMC
0339 is called with the command ``tamc`` followed by a number of options. They
0340 are described in detail in the TAMC manual (Giering 1999 :cite:`giering:99`).
0341 Here we briefly discuss the main flags used in the ``makefile``. The
0342 standard output for TAF is written to file ``taf.log``.
0343
0344 TAMC:
0345
0346 ::
0347
0348 -input «variable names» -output «variable name» -i4 -r4 ...
0349 -toplevel «S/R name» -reverse «file names»
0350
0351 TAF:
0352
0353 ::
0354
0355 -input «variable names» -output «variable name» -i4 -r4 ...
0356 -toplevel «S/R name» -reverse «file names»
0357 -flow taf_flow.log -nonew_arg
0358
0359 - ``-toplevel «S/R name»``
0360
0361 Name of the toplevel routine, with respect to which the control
0362 flow analysis is performed.
0363
0364 - ``input «variable names»``
0365
0366 List of independent variables :math:`u` with respect to which the
0367 dependent variable :math:`J` is differentiated.
0368
0369 - ``-output «variable name»``
0370
0371 Dependent variable :math:`J` which is to be differentiated.
0372
0373 - ``-reverse «file names»``
0374
0375 Adjoint code is generated to compute the sensitivity of an
0376 independent variable w.r.t. many dependent variables. In the
0377 discussion of :numref:`chap_autodiff` the generated adjoint top-level routine
0378 computes the product of the transposed Jacobian matrix
0379 :math:`M^T` times the gradient vector :math:`\nabla_v J`.
0380 «file names» refers to the list of files ``.f`` which are to be analyzed by TAMC.
0381 This list is generally smaller than the full list of code to be
0382 compiled. The files not contained are either above the top-level
0383 routine (some initializations), or are deliberately hidden from
0384 TAMC, either because hand-written adjoint routines exist, or the
0385 routines must not (or don’t have to) be differentiated. For each
0386 routine which is part of the flow tree of the top-level routine,
0387 but deliberately hidden from TAMC (or for each package which
0388 contains such routines), a corresponding file ``.flow`` exists
0389 containing flow directives for TAMC.
0390
0391 - ``-i4 -r4``
0392
0393
0394 - ``-flow taf_flow.log``
0395
0396 Will cause TAF to produce a flow listing file named ``taf_flow.log``
0397 in which the set of active and passive variables are identified for
0398 each subroutine.
0399
0400 - ``-nonew_arg``
0401
0402 The default in the order of the parameter list of adjoint routines
0403 has changed. Before TAF 1.3 the default was compatible with the
0404 TAMC-generated list. As of TAF 1.3 the order of adjoint routine
0405 parameter lists is no longer compatible with TAMC. To restore
0406 compatibility when using TAF 1.3 and higher, this argument is
0407 needed. It is currently crucial to use since all hand-written
0408 adjoint routines refer to the TAMC default.
0409
0410 File ``input/topog.bin``
0411 ^^^^^^^^^^^^^^^^^^^^^^^^
0412
0413 Contains 2-D bathymetry information.
0414
0415 Files ``input/windx.bin``, ``input/windy.bin``, ``input/salt.bin``, ``input/theta.bin``, ``input/SSS.bin``, ``input/SST.bin``
0416 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0417
0418 These contain the initial values of salnity and potential temperature (``salt.bin``, ``theta.bin``), surface boundary values (surface wind stresses
0419 ``windx.bin``, ``windy.bin``), and surface restoring fields (``SSS.bin``, ``SST.bin``).
0420
0421 Compiling the model and its adjoint
0422 -----------------------------------
0423
0424 The build process of the adjoint model is slightly more complex than
0425 that of compiling the forward code. The main reason is that the adjoint
0426 code generation requires a specific list of routines that are to be
0427 differentiated (as opposed to the automatic generation of a list of
0428 files to be compiled by :filelink:`genmake2 <tools/genmake2>`). This list excludes routines that don’t
0429 have to be or must not be differentiated. For some of the latter
0430 routines flow directives may be necessary, a list of which has to be
0431 given as well. For this reason, a separate ``makefile`` is currently
0432 maintained in the directory adjoint/. This makefile is responsible for
0433 the adjoint code generation.
0434
0435 In the following we describe the build process step by step, assuming
0436 you are in the directory bin/. A summary of steps to follow is given at
0437 the end.
0438
0439 Adjoint code generation and compilation – step by step
0440 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0441
0442 1. | ``ln -s ../verification/???/code/.genmakerc .``
0443 | ``ln -s ../verification/???/code/*.[Fh] .``
0444 | Link your customized genmake options, header files, and modified
0445 code to the compile directory.
0446
0447 2. | ``../tools/genmake -makefile``
0448 | Generate your Makefile (see :numref:`genmake2_desc`).
0449
0450 3. | ``make depend``
0451 | Dependency analysis for the CPP pre-compiler (see :numref:`building_quickstart`).
0452
0453 4. | ``cd ../adjoint``
0454 | ``make adtaf`` or ``make adtamc``
0455 | Depending on whether you have TAF or TAMC at your disposal, you’ll
0456 choose adtaf or adtamc as your make target for the ``makefile`` in
0457 the directory adjoint/. Several things happen at this stage.
0458
0459 - | ``make adrestore``
0460 | ``make ftlrestore``
0461 | The initial template files ``adjoint_model.F`` and
0462 ``tangentlinear_model.F`` in :filelink:`pkg/autodiff` which are part of the
0463 compiling list created by :filelink:`genmake2 <tools/genmake2>` are restored.
0464
0465 - | ``make depend, make small_f``
0466 | The bin/ directory is brought up to date, i.e., for recent
0467 changes in header or source code ``.[Fh]``, corresponding ``.f``
0468 routines are generated or re-generated. Note that here, only CPP
0469 pre-compiling is performed; no object code ``.o`` is generated as
0470 yet. Pre-compiling is necessary for TAMC to see the full code.
0471
0472 - | ``make allcode``
0473 | All Fortran routines .f in bin/ are concatenated into a single
0474 file called ``tamc_code.f``.
0475
0476 - | ``make admodeltaf/admodeltamc``
0477 | Adjoint code is generated by TAMC or TAF. The adjoint code is
0478 written to the file ``tamc_code_ad.f``. It contains all adjoint
0479 routines of the forward routines concatenated in ``tamc_code.f``.
0480 For a given forward routine subroutine routinename the adjoint
0481 routine is named adsubroutine routinename by default (that
0482 default can be changed via the flag ``-admark «markname»``).
0483 Furthermore, it may contain modified code which incorporates the
0484 translation of adjoint store directives into specific Fortran
0485 code. For a given forward routines subroutine routinename the
0486 modified routine is named mdsubroutine routinename. TAMC or TAF
0487 info is written to file ``tamc_code.prot`` or ``taf.log``,
0488 respectively.
0489
0490 - | ``make adchange``
0491 | The multi-threading capability of MITgcm requires a slight
0492 change in the parameter list of some routines that are related
0493 to to active file handling. This post-processing invokes the sed
0494 script :filelink:`tools/adjoint_sed` to insert the threading counter
0495 :varlink:`myThId` into the parameter list of those subroutines. The
0496 resulting code is written to file ``tamc_code_sed_ad.f`` and
0497 appended to the file ``adjoint_model.F``. This concludes the
0498 adjoint code generation.
0499
0500 5. | ``cd ../bin``
0501 | ``make``
0502 | The file ``adjoint_model.F`` cnow contains the full adjoint code. All
0503 routines are now compiled.
0504
0505 N.B.: The targets ``make adtaf/adtamc`` now comprise a series of targets
0506 that in previous versions had to be invoked separately. This was
0507 probably preferable at a more experimental stage, but has now been
0508 dropped in favor of a more straightforward build process.
0509
0510 Adjoint code generation and compilation – summary
0511 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0512
0513 ::
0514
0515 cd bin
0516 ln -s ../verification/my_experiment/code/.genmakerc .
0517 ln -s ../verification/my_experiment/code/*.[Fh] .
0518 ../tools/genmake -makefile
0519 make depend
0520 cd ../adjoint
0521 make adtaf <OR: make adtamc>
0522 contains the targets:
0523 adrestore small_f allcode admodeltaf/admodeltamc adchange
0524 cd ../bin
08815fc806 Jeff*0525 make
