diff --git a/doc/autodiff/autodiff.rst b/doc/autodiff/autodiff.rst index 1632e9495d..9166a0fe0c 100644 --- a/doc/autodiff/autodiff.rst +++ b/doc/autodiff/autodiff.rst @@ -709,18 +709,21 @@ be enabled: - :filelink:`pkg/grdchk` The packages are enabled by adding them to your experiment-specific -configuration file ``packages.conf`` (see Section ???). +configuration file ``packages.conf`` (see :numref:`using_packages`). The following AD-specific CPP option files need to be customized: -- :filelink:`ECCO_CPPOPTIONS.h ` - This header file collects CPP options for :filelink:`pkg/autodiff`, - :filelink:`pkg/cost`, :filelink:`pkg/ctrl` as well as AD-unrelated options for the external - forcing package :filelink:`pkg/exf`. (NOTE: These options are not set in their - package-specific headers such as :filelink:`COST_OPTIONS.h `, - but are instead collected in the single header file - :filelink:`ECCO_CPPOPTIONS.h `. - The package-specific header files serve as simple placeholders at this point.) +- :filelink:`AUTODIFF_OPTIONS.h ` This header + file collects CPP options for :filelink:`pkg/autodiff`, :filelink:`pkg/cost`, + :filelink:`pkg/ctrl` as well as AD-unrelated options for the external forcing + package :filelink:`pkg/exf`. + +- :filelink:`COST_OPTIONS.h ` In this header file, + options for different cost functions are set. + +- :filelink:`CTRL_OPTIONS.h ` In this header file the + control variables are enabled and options for writing and reading the control + vector are set - :filelink:`tamc.h ` This header configures the splitting of the time stepping loop @@ -787,7 +790,7 @@ follows: % mkdir build % cd build - % ../../../tools/genmake2 -mods=../code_ad + % ../../../tools/genmake2 -mods=../code_ad [ -nocat4ad ] % make depend % make adall @@ -805,21 +808,25 @@ The ``make «MODE»all`` target consists of the following procedures: - #define :varlink:`ALLOW_TANGENTLINEAR_RUN` - - #define :varlink:`ALLOW_ECCO_OPTIMIZATION` - -#. 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``. +#. If `` -nocat4ad`` is not specified, 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``. #. The AD tool is invoked with the ``«MODE»_«TOOL»_FLAGS``. The default AD tool - flags in :filelink:`genmake2 ` can be overwritten by a :filelink:`tools/adjoint_options` file - (similar to the platform-specific :filelink:`tools/build_options`, see :numref:`genmake2_optfiles`). - The AD tool writes the resulting AD code into the file - ``«MODE»_input_code_ad.f``. + flags in :filelink:`genmake2 ` can be overwritten by a + :filelink:`tools/adjoint_options` file (similar to the platform-specific + :filelink:`tools/build_options`, see :numref:`genmake2_optfiles`). The AD + tool writes the resulting AD code into the file ``«MODE»_input_code_ad.f``. -#. A short sed script :filelink:`tools/adjoint_sed ` is applied to ``«MODE»_input_code_ad.f`` to - reinstate :varlink:`myThid` into the CALL argument list of active file I/O. - The result is written to file ``«MODE»_«TOOL»_output.f``. +#. A short sed script :filelink:`tools/adjoint_sed ` is + applied to ``«MODE»_input_code_ad.f`` to reinstate :varlink:`myThid` into + the CALL argument list of active file I/O. The result is written to file + ``«MODE»_«TOOL»_output.f``. + +#. If the `` -nocat4ad`` option is specified, the concatenation of all ``.f`` + files is skipped and instead all necessary files are sent to TAF and for + each file an AD-file is returned. #. All routines are compiled and an executable is generated. @@ -961,18 +968,19 @@ the package :filelink:`pkg/ctrl` and will be treated in the next section. Enabling the package ~~~~~~~~~~~~~~~~~~~~ -:filelink:`pkg/cost ` is enabled by adding the line ``cost`` to your file ``packages.conf`` (see Section ???). +:filelink:`pkg/cost ` is enabled by adding the line ``cost`` to your +file ``packages.conf`` (see :numref:`using_packages`). -In general the following packages ought to be enabled -simultaneously: :filelink:`pkg/autodiff `, :filelink:`pkg/ctrl `, -and :filelink:`pkg/cost`. The basic CPP option to enable -the cost function is :varlink:`ALLOW_COST`. Each specific cost function -contribution has its own option. For the present example the option is -:varlink:`ALLOW_COST_TRACER`. All cost-specific options are set in -:filelink:`ECCO_CPPOPTIONS.h ` Since the cost function is usually used in +In general the following packages ought to be enabled simultaneously: +:filelink:`pkg/autodiff `, :filelink:`pkg/ctrl `, and +:filelink:`pkg/cost`. The basic CPP option to enable the cost function is +:varlink:`ALLOW_COST`. Each specific cost function contribution has its own +option. For the present example the option is :varlink:`ALLOW_COST_TRACER`. All +cost-specific options are set in :filelink:`COST_OPTIONS.h +`. Since the cost function is usually used in conjunction with automatic differentiation, the CPP option -:varlink:`ALLOW_ADJOINT_RUN` (file :filelink:`CPP_OPTIONS.h `) and -:varlink:`ALLOW_AUTODIFF_TAMC` (file :filelink:`ECCO_CPPOPTIONS.h `) should be defined. +:varlink:`ALLOW_AUTODIFF_TAMC` (file :filelink:`AUTODIFF_OPTIONS.h +`) should be defined. Initialization ~~~~~~~~~~~~~~ @@ -1126,9 +1134,9 @@ initialization, perturbation) are controlled by the package :filelink:`pkg/ctrl` :filelink:`genmake2 ` and CPP options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Package :filelink:`pkg/ctrl` is enabled by adding the line ``ctrl`` to your file ``packages.conf``. -Each control variable is enabled via its own CPP option in -:filelink:`ECCO_CPPOPTIONS.h `. +Package :filelink:`pkg/ctrl` is enabled by adding the line ``ctrl`` to your +file ``packages.conf``. Each control variable is enabled via its own CPP +option in :filelink:`CTRL_OPTIONS.h `. Initialization ~~~~~~~~~~~~~~ @@ -1293,7 +1301,7 @@ Several ways exist to generate output of adjoint fields. :filelink:`addummy_in_stepping.F `. The procedure is enabled using via the CPP-option :varlink:`ALLOW_AUTODIFF_MONITOR` (file - :filelink:`ECCO_CPPOPTIONS.h `). + :filelink:`AUTODIFF_OPTIONS.h `). To be part of the adjoint code, the corresponding S/R :filelink:`dummy_in_stepping.F ` has to be called in the @@ -1379,25 +1387,15 @@ corresponding I/O flow is shown in :numref:`forward-adj_io`: Flow chart showing I/O in the forward/adjoint model. -:filelink:`ctrl_unpack.F ` reads the updated control vector -``vector_ctrl_``. It distributes the -different control variables to 2-D and 3-D files -``xx_«...»``. At the start of the forward -integration the control variables are read from -``xx_«...»`` and added to the field. -Correspondingly, at the end of the adjoint integration the adjoint -fields are written to ``adxx_«...»``, again via -the active file routines. Finally, -:filelink:`ctrl_pack.F ` collects all adjoint -files and writes them to the compressed vector file -``vector_grad_``. - +:filelink:`ctrl_unpack.F ` reads the updated control +vector ``vector_ctrl_``. It distributes the different control variables to +2-D and 3-D files ``xx_«...»``. At the start of the forward integration the +control variables are read from ``xx_«...»`` and added to the field. +Correspondingly, at the end of the adjoint integration the adjoint fields are +written to ``adxx_«...»``, again via the active file routines. Finally, +:filelink:`ctrl_pack.F ` collects all adjoint files and +writes them to the compressed vector file ``vector_grad_``. -NOTE: These options are not set in their package-specific headers -such as :filelink:`COST_OPTIONS.h `, -but are instead collected in the single -header file :filelink:`ECCO_CPPOPTIONS.h `. The package-specific header files -serve as simple placeholders at this point. .. _ad_gradient_check: @@ -1491,15 +1489,13 @@ The relevant runtime flags are set in the files: Adjoint dump & restart – divided adjoint (DIVA) =============================================== -Authors: Patrick Heimbach & Geoffrey Gebbie, 07-Mar-2003* +Authors: Patrick Heimbach & Geoffrey Gebbie, 07-Mar-2003 ***NOTE:THIS SECTION IS SUBJECT TO CHANGE. IT REFERS TO TAF-1.4.26.** -Previous TAF versions are incomplete and have problems with both TAF -options ``-pure`` and ``-mpi``. - -The code which is tuned to the DIVA implementation of this TAF version -is ``checkpoint50`` (MITgcm) and ``ecco_c50_e28`` (ECCO). +Old TAF versions are incomplete and have problems with both TAF options +``-pure`` and ``-mpi``. At the time of the latest update, the current version +of TAF is 6.1.5 Introduction ------------ @@ -1549,7 +1545,8 @@ the current implementation, the forward sweep is immediately followed by the first adjoint leg. Thus, in theory, the following steps are performed (automatically) -- **1st model call:** This is the case if file ``costfinal`` does *not* exist. S/R +- **1st model call:** + This is the case if file ``costfinal`` does *not* exist. S/R ``mdthe_main_loop.f`` (generated by TAF) is called. #. calculate forward trajectory and dump model state after each @@ -1589,111 +1586,69 @@ intermediate adjoint integration interval). compensate for TAF bugs. Since we refer to TAF-1.4.26 onwards, these modifications are not documented here]. -.. _recipe1: - -Recipe 1: single processor --------------------------- +.. _diva_recipe: -#. In :filelink:`ECCO_CPPOPTIONS.h ` set: - - - #define :varlink:`ALLOW_DIVIDED_ADJOINT` - - #undef :varlink:`ALLOW_DIVIDED_ADJOINT_MPI` +Recipe for divided adjoint code generation +------------------------------------------ -#. Generate adjoint code. Using the TAF option ``-pure``, two codes are - generated: - - - ``mdthe_main_loop.f``: - Is responsible for the forward trajectory, storing of outermost - checkpoint levels to file, computation of cost function, and - storing of cost function to file (1st step). - - - ``adthe_main_loop.f``: - Is responsible for computing one adjoint leg, dump adjoint state - to file and write index info to file (2nd and consecutive - steps). +Verification experiment :filelink:`lab_sea ` tests the +divided adjoint and serves as an example of how to configure the code. - for adjoint code generation, e.g., add ``-pure`` to TAF option list +#. define ``USE_DIVA=1``, either as an environment variable (e.g., in bash: + ``export USE_DIVA=1``), in a ``genmake_local`` file in the ``build`` + directory, or in your build options file. This will instruct + :filelink:`genmake2 ` to generate TAF options (``-pure``) + for divided adjoint generation. - :: +#. In a local copy of :filelink:`AUTODIFF_OPTIONS.h + ` set: - make adtaf - - - One modification needs to be made to adjoint codes in S/R - ``adecco_the_main_loop.f`` (generated by TAF): - - There’s a remaining issue with the ``-pure`` option. The ``call - ad...`` between ``call ad...`` and the read of the ``snapshot`` file - should be called only in the first adjoint leg between - :math:`nlev3` and :math:`nlev3-1`. In the ecco-branch, the - following lines should be bracketed by an ``if (idivbeg .GE. - nchklev_3) then``, thus: - - :: - - - ... - xx_psbar_mean_dummy = onetape_xx_psbar_mean_dummy_3h(1) - xx_tbar_mean_dummy = onetape_xx_tbar_mean_dummy_4h(1) - xx_sbar_mean_dummy = onetape_xx_sbar_mean_dummy_5h(1) - call barrier( mythid ) - cAdd( - if (idivbeg .GE. nchklev_3) then - cAdd) - - call adcost_final( mythid ) - call barrier( mythid ) - call adcost_sst( mythid ) - call adcost_ssh( mythid ) - call adcost_hyd( mythid ) - call adcost_averagesfields( mytime,myiter,mythid ) - call barrier( mythid ) - cAdd( - endif - cAdd) - - C---------------------------------------------- - C read snapshot - C---------------------------------------------- - if (idivbeg .lt. nchklev_3) then - open(unit=77,file='snapshot',status='old',form='unformatted', - $iostat=iers) - ... - - For the main code, in all likelihood the block which needs to be - bracketed consists of ``adcost_final.f`` (generated by TAF) only. + - #define :varlink:`ALLOW_DIVIDED_ADJOINT` - - Now the code can be copied as usual to ``adjoint_model.F`` and then - be compiled: + to enable code for divided adjoint. - :: +#. If using MPI, make sure that the paths to mpi-header files, such as + ``mpif.h``, are know to :filelink:`genmake2 ` (as usual, via + the build options file, see also :numref:`diva_mpi`). - make adchange +#. Run the usual sequence for generating the Makefile and the AD-code. - then compile + :: -Recipe 2: multi processor (MPI) -------------------------------- + ${ROOTDIR}/tools/genmake2 -mods=../code_ad -nocat4ad [ other options ] + make depend + make adtaf -#. On the machine where you execute the code (most likely not the - machine where you run TAF) find the includes directory for MPI - containing ``mpif.h``. Either copy ``mpif.h`` to the machine where you - generate the ``.f`` files before TAF-ing, or add the path to the includes - directory to your :filelink:`genmake2 ` platform setup, TAF needs some MPI parameter - settings (essentially ``mpi_comm_world`` and ``mpi_integer``) to - incorporate those in the adjoint code. + the ``-nocat4ad`` option is not necessary, but will generate individual + AD-files for each forward file sent to TAF. The adjoint code now contains + subroutines (in ``the_main_loop_ad.f``): -#. In :filelink:`ECCO_CPPOPTIONS.h ` set + - ``adthe_main_loop_ad``: + Is responsible for the forward trajectory, storing of outermost + checkpoint levels to file, computation of cost function, and + storing of cost function to file (1st step). - - #define :varlink:`ALLOW_DIVIDED_ADJOINT` - - #define :varlink:`ALLOW_DIVIDED_ADJOINT_MPI` + - ``adthe_main_loop``: + Is responsible for computing one adjoint leg, dump adjoint state + to file and write index info to file (2nd and consecutive + steps). - This will include the header file ``mpif.h`` into the top level routine - for TAF. + Then compile with ``make adall`` (the ``make adtaf`` step is not necessary + unless you want to inspect the TAF-generated code before compiling). -#. Add the TAF option ``-mpi`` to the TAF argument list in the makefile. +.. _diva_mpi: -#. Follow the same steps as in :ref:`Recipe 1 `. +Special considerations for multi processor (MPI) runs +----------------------------------------------------- +On the machine where you execute the code (most likely not the machine where +you run TAF) find the includes directory for MPI containing ``mpif.h``. Either +copy ``mpif.h`` to the machine where you preprocess the code (generate the +``.f`` files) before TAF-ing, or add the path to the includes directory to your +:filelink:`genmake2 ` platform setup. TAF needs some MPI +parameter settings (essentially ``mpi_comm_world`` and ``mpi_integer``) to +incorporate those in the adjoint code. The ``-mpi`` will be added to the TAF +argument list automatically. .. _ad_openad: diff --git a/verification/lab_sea/README b/verification/lab_sea/README deleted file mode 100644 index 203e364323..0000000000 --- a/verification/lab_sea/README +++ /dev/null @@ -1,168 +0,0 @@ -Example: Labrador Sea Region with Sea-Ice -========================================= - -This example sets up a small (20x16x23) Labrador Sea experiment -coupled to a dynamic thermodynamic sea-ice model. -A brief description of the sea-ice model is in "seaice.ps". - -The domain of integration spans 280E to 320E and 46N to 78N. -Horizontal grid spacing is 2 degrees. -The 23 vertical levels and the bathymetry file - bathyFile = 'bathy.labsea' -are obtained from the the 2-degree ECCO configuration. - -Integration is initialized from annual-mean Levitus climatology - hydrogThetaFile = 'LevCli_temp.labsea' - hydrogSaltFile = 'LevCli_salt.labsea' - -Surface salinity relaxation is to the monthly mean Levitus climatology - saltClimFile = 'SSS.labsea' - -Forcing files are a 1979-1999 monthly climatology computed from the -NCEP reanalysis (see pkg/seaice/SEAICE_FFIELDS.h for units and signs) - uwindFile = 'u10m.labsea79' # 10-m zonal wind - vwindFile = 'v10m.labsea79' # 10-m meridional wind - atempFile = 'tair.labsea1979' # 2-m air temperature - aqhFile = 'qa.labsea1979' # 2-m specific humidity - lwdownFile = 'flo.labsea1979' # downward longwave radiation - swdownFile = 'fsh.labsea1979' # downward shortwave radiation - precipFile = 'prate.labsea1979' # precipitation - -The experiment uses pkg/gmredi, pkg/kpp, pkg/seaice, and pkg/exf. -The test is a 1-cpu, 10-hour integration. Both the atmospheric -state and the open-water surface fluxes are provided by pkg/exf. - -More pkg/seaice test experiments, configured for low and -high-resolution global cube-sphere domains are described -in MITgcm_contrib/high_res_cube/README_ice. - -Lab Sea adjoint -===================================== -The code_ad directory provides files required to compile the adjoint -version of this verification experiment. This verification -experiment uses the 'divided adjoint'. - -To compile the adjoint, one must use a special AD_OPTFILE, -the location of which is specified in the file 'build/genmake_local'. -To wit, -AD_OPTFILE='../../../tools/adjoint_options/adjoint_diva' - -To compile the adjoint without the divided adjoint, the compile-time -flag ALLOW_DIVIDED_ADJOINT in 'code_ad/ECCO_CPPOPTIONS.h' should -be changed from -#define ALLOW_DIVIDED_ADJOINT -to -#undef ALLOW_DIVIDED_ADJOINT - -Note: testreport builds in the 'lab_sea/build' directory which contains -this 'genmake_local' file and so it knows to use the 'adjoint_diva' -AD_OPTFILE - -Using testscript to test sea-ice code -===================================== - -Running the testscript experiment: - cd MITgcm/verification - ./testreport -t lab_sea [-of my_platform_optionFile] - -Note that fairly large differences in accuracy occur across different -platforms. For example, testscript comparisons between g77 (Linux) -and f77 (SGI) generated output gives: - - T S U V -C D M c m s m s m s m s -n p a R g m m e . m m e . m m e . m m e . -f n k u 2 i a a d i a a d i a a d i a a d -g d e n d n x n . n x n . n x n . n x n . - -Y Y Y Y 8 10 9 11 10 9 11 13 10 9 8 8 9 8 9 8 9 FAIL lab_sea - -Instructions for generating and running a 1-CPU experiment -========================================================== - - cd MITgcm/verification/lab_sea - -Configure and compile the code: - cd build - ../../../tools/genmake2 -mods ../code [-of my_platform_optionFile] - make depend - make - cd .. - -To run: - cd run - ln -s ../input/* . - ln -s ../build/mitgcmuv . - ./mitgcmuv > output.txt - cd .. - -There is comparison output in the directory: - results/output.txt - -Use matlab script lookat_ice.m to compare the output - with that from checkpoint51f sea-ice code: - cd ../../../verification/lab_sea/matlab - matlab - lookat_ice - -Instructions for generating and running a 2-CPU experiment -========================================================== - - cd MITgcm/verification/lab_sea - -Configure and compile the code: - cd build - ../../../tools/genmake2 -mpi -mods ../code [-of my_platform_optionFile] - ln -s ../code/SIZE.h_mpi SIZE.h - make depend - make - cd .. - -To run: - cd run - ln -s ../input/* . - mpirun -np 2 ../build/mitgcmuv - cd .. - -Instructions for testing useExfYearlyFields (Note: might not be up-to-date) -=========================================== - - cd MITgcm/verification/lab_sea/build - \rm * - \cp ../code/* . - sed 's/undef EXF_V/define EXF_V/' \ - ../../../pkg/exf/EXF_OPTIONS.h > EXF_OPTIONS.h - ../../../tools/genmake2 - make depend - make -j - cd ../run - \rm * - \cp ../input/* . - \mv v10m.labsea1979 v10m.labsea_1979 - \mv u10m.labsea1979 u10m.labsea_1979 - \mv flo.labsea1979 flo.labsea_1979 - \mv prate.labsea1979 prate.labsea_1979 - \mv tair.labsea1979 tair.labsea_1979 - \mv fsh.labsea1979 fsh.labsea_1979 - \mv qa.labsea1979 qa.labsea_1979 - \mv SSS_monthly.labsea1979 SSS_monthly.labsea_1979 - \ln -sf v10m.labsea_1979 v10m.labsea_1978 - \ln -sf u10m.labsea_1979 u10m.labsea_1978 - \ln -sf flo.labsea_1979 flo.labsea_1978 - \ln -sf prate.labsea_1979 prate.labsea_1978 - \ln -sf tair.labsea_1979 tair.labsea_1978 - \ln -sf fsh.labsea_1979 fsh.labsea_1978 - \ln -sf qa.labsea_1979 qa.labsea_1978 - \ln -sf SSS_monthly.labsea_1979 SSS_monthly.labsea_1978 - \ln -sf v10m.labsea_1979 v10m.labsea_1980 - \ln -sf u10m.labsea_1979 u10m.labsea_1980 - \ln -sf flo.labsea_1979 flo.labsea_1980 - \ln -sf prate.labsea_1979 prate.labsea_1980 - \ln -sf tair.labsea_1979 tair.labsea_1980 - \ln -sf fsh.labsea_1979 fsh.labsea_1980 - \ln -sf qa.labsea_1979 qa.labsea_1980 - \ln -sf SSS_monthly.labsea_1979 SSS_monthly.labsea_1980 - \mv data.exf_YearlyFields data.exf - \mv data_YearlyFields data - sed 's/tics = .TRUE./tics = .FALSE./' ../input/data.pkg > data.pkg - ../build/mitgcmuv >& output.txt & diff --git a/verification/lab_sea/README.md b/verification/lab_sea/README.md new file mode 100644 index 0000000000..1ceb7e67cd --- /dev/null +++ b/verification/lab_sea/README.md @@ -0,0 +1,224 @@ +Labrador Sea Region with Sea-Ice +========================================= + +### Overview: +This example sets up a small (20x16x23) Labrador Sea experiment +coupled to a dynamic thermodynamic sea-ice model (MITgcm Documentation 8.6.2). + +The domain of integration spans $`[280, 320]^\circ`$E and $`[46, 78]^\circ`$N. +Horizontal grid spacing is 2 degrees. +The 23 vertical levels and the bathymetry file + +``` + bathyFile = 'bathy.labsea1979' +``` +are obtained from the the 2$`^\circ`$ ECCO configuration. + +Integration is initialized from annual-mean Levitus climatology + +``` + hydrogThetaFile = 'LevCli_temp.labsea1979' + hydrogSaltFile = 'LevCli_salt.labsea1979' +``` + +Surface salinity relaxation is to the monthly mean Levitus climatology + +``` + saltClimFile = 'SSS.labsea1979' +``` + +Forcing files are a 1979-1999 monthly climatology computed from the +NCEP reanalysis (see [SEAICE_PARAMS.h](https://github.com/MITgcm/MITgcm/blob/master/pkg/seaice/SEAICE_PARAMS.h) for units and signs) + +``` + uwindFile = 'u10m.labsea1979' # 10-m zonal wind + vwindFile = 'v10m.labsea1979' # 10-m meridional wind + atempFile = 'tair.labsea1979' # 2-m air temperature + aqhFile = 'qa.labsea1979' # 2-m specific humidity + lwdownFile = 'flo.labsea1979' # downward longwave radiation + swdownFile = 'fsh.labsea1979' # downward shortwave radiation + precipFile = 'prate.labsea1979' # precipitation +``` + +The experiment uses `pkg/gmredi`, `pkg/kpp`, `pkg/seaice`, and `pkg/exf`. +The test is a 1-cpu, 10-hour integration. Both the atmospheric +state and the open-water surface fluxes are provided by `pkg/exf`. + +More `pkg/seaice` test experiments, configured for low and +high-resolution global cube-sphere domains are described +in `MITgcm_contrib/high_res_cube/README_ice`. + +## Lab Sea adjoint +The `code_ad` directory provides files required to compile the adjoint +version of this verification experiment. This verification +experiment uses the 'divided adjoint'. + +To compile the adjoint, one must enable the divided adjoint with the +compile-time flag `USE_DIVA`, the location of which is specified in +the file `build/genmake_local`. +To wit, + +``` + USE_DIVA=1 +``` + +To compile the adjoint without the divided adjoint, the compile-time +flag `ALLOW_DIVIDED_ADJOINT` in `code_ad/AUTODIFF_OPTIONS.h` should +be changed from + +``` + #define ALLOW_DIVIDED_ADJOINT +``` +to + +``` + #undef ALLOW_DIVIDED_ADJOINT +``` + +Note: `testreport` builds in the `lab_sea/build` directory which contains +this `genmake_local` file and so it knows to use the divided adjoint. + +## Instructions +Navigate to experiment directory + +``` + cd MITgcm/verification/lab_sea +``` + +### 1-CPU forward experiment +Configure and compile the code: + +``` + cd build + ../../../tools/genmake2 -mods ../code [-of my_platform_optionFile] + make depend + make + cd .. +``` + +To run: + +``` + cd run + ln -s ../input/* . + ln -s ../build/mitgcmuv . + ./mitgcmuv > output.txt + cd .. +``` + +There is comparison output in the directory: + +``` + results/output.txt +``` + +Use matlab script `lookat_ice.m` to compare the output + with that from `checkpoint51f` sea-ice code: + +``` + cd ../../../verification/lab_sea/matlab + matlab + lookat_ice +``` + +### 2-CPU forward experiment +Configure and compile the code: + +``` + cd build + ../../../tools/genmake2 -mpi -mods ../code [-of my_platform_optionFile] + ln -s ../code/SIZE.h_mpi SIZE.h + make depend + make + cd .. +``` + +To run: + +``` + cd run + ln -s ../input/* . + mpirun -np 2 ../build/mitgcmuv + cd .. +``` + +### 1-CPU adjoint experiment +Configure and compile the code: + +``` + cd build + ../../../tools/genmake2 -mods ../code_ad [-of my_platform_optionFile] + make adall + cd .. +``` + +To run: + +``` + cd run + ln -s ../input_ad/* . + ln -s ../input/* . + ln -s ../../isomip/input_ad/ones_64b.bin . + ln -s ../build/mitgcmuv_ad . + ./do_run.sh + cd .. +``` + +**Note:** the overly simple shell script "do_run.sh" just executes four times +(as specified in file "run_ADM_DIVA", `add_DIVA_runs = 4`) `mitgcmuv_ad`, saving +output in intermediate files "output_adm.txt.diva_0,1,2,3", plus a final time: +``` + mitgcmuv_ad > output_adm.txt +``` +where output file `output_adm.txt` can be compared with reference output: + +``` + results/output_adm.txt +``` + +## Test sea-ice code +Run the testscript _forward_ experiments: + +``` + cd MITgcm/verification + ./testreport -t lab_sea [-of my_platform_optionFile] +``` + +Standard testreport output, with all secondary tests: +``` +default 10 ----T----- ----S----- ----U----- ----V----- --PTR 01-- --PTR 02-- --PTR 03-- --PTR 04-- --PTR 05-- +G D M c m s m s m s m s m s m s m s m s m s +e p a R g m m e . m m e . m m e . m m e . m m e . m m e . m m e . m m e . m m e . +n n k u 2 i a a d i a a d i a a d i a a d i a a d i a a d i a a d i a a d i a a d +2 d e n d n x n . n x n . n x n . n x n . n x n . n x n . n x n . n x n . n x n . + +Y Y Y Y>11<16 16 16 16 13 16 16 16 13 16 13 13 16 13 12 13 22 16 16 16 22 16 16 16 pass lab_sea +Y Y Y Y>11<16 16 16 16 13 16 16 16 13 12 13 13 12 13 12 14 22 16 16 16 22 16 16 16 pass lab_sea.fd +Y Y Y Y> 4< 9 10 9 8 16 13 11 8 6 8 4 5 8 8 4 5 22 6 7 7 22 5 7 6 FAIL lab_sea.hb87 +Y Y Y Y>11<16 16 16 16 16 16 16 16 16 13 12 14 16 16 13 14 22 16 16 16 22 16 16 16 pass lab_sea.salt_plume +``` + +**Note:** Some differences in accuracy occur across different platforms as seen +here for secondary test "lab_sea.hb87". + +Run the testscript _adjoint_ experiments: + +``` + cd MITgcm/verification + ./testreport -t lab_sea -ad [-of my_platform_optionFile] +``` + +Standard adjoint testreport output, with all secondary tests: +``` +Adjoint generated by TAF + +default 10 ----T----- ----S----- ----U----- ----V----- +G D M C A F m s m s m s m s +e p a R o d D m m e . m m e . m m e . m m e . +n n k u s G G i a a d i a a d i a a d i a a d +2 d e n t r r n x n . n x n . n x n . n x n . + +Y Y Y Y 16>16<16 16 14 16 16 16 16 16 16 16 16 16 14 14 16 16 16 pass lab_sea (e=0, w=0, lfd=1, dop=1, sm=1) +Y Y Y Y 14>15< 6 16 16 16 13 16 13 13 11 13 13 12 13 11 11 12 12 pass lab_sea.noseaice +Y Y Y Y 16>13<16 16 16 14 16 16 13 13 16 16 16 16 14 14 16 14 16 pass lab_sea.noseaicedyn +```