darwin3 |
|
|
|
|||
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 UTC1c8cebb321 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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 339.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 386.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 429.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 440.
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``** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 456.
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** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 511.
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
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated from https://github.com/darwinproject/darwin3 by the 2.3.7-MITgcm-0.1 LXR engine. The LXR team |
|