verification/global_oce_latlon/README.md

f1b47febb7 Jean*0001 # Global Ocean Simulation at 4 degree Resolution, including Adjoint Set-Up
7fe51dd492 Jean*0002 First configuration to use OpenAD, started on 2005-08-19
                0003  by heimbach@mit.edu, utke@mcs.anl.gov, cnh@mit.edu
                0004 ***Note*** this experiment was previously named "OpenAD".
                0005
                0006 ### Overview:
f1b47febb7 Jean*0007 This experiment is derived from `tutorial_global_oce_latlon` (see also `global_ocean.90x40x15`)
                0008 with surface forcing provided by specific pkgs, either
                0009 `pkg/exf` or `pkg/ebm`, instead of relying on the main model surface forcing capability.
                0010 It contains 3 forward set-up, all using the same executable built from `code`
                0011 config but with specific input files from `input/` (primary test) and,
                0012 as secondary tests, from `input.yearly/` and `input.ebm/`.
                0013
                0014 It provides also adjoint settings for 3 AD compilers, OpenAD, TAF and Tapenade, with primary
7fe51dd492 Jean*0015 test input files in `input_oad/`, `input_ad/` and `input_tap/` respectively, but also
                0016 several secondary test setting with each of the AD compilers.
                0017
f1b47febb7 Jean*0018 ## Part 0, Forward only tests:
                0019
                0020 The **primary** forward test, using input files from `input/`,
                0021 uses prescribed monthly-mean air-sea surface fluxes from `pkg/exf`.<br>
                0022
                0023 The **secondary** test, using input files from `input.yearly/`,
                0024 is very similar except for the specification of yearly input fields to`pkg/exf`.<br>
                0025
                0026 **Note:**
                0027
                0028 1.  These 2 set-up have been moved (in PR #830) from `verification/global_with_exf/`
                0029     where a "README" still provides some details related to `pkg/exf` specific
                0030     features used here.
                0031 2.  The ability, using `pkg/exf`, to compute surface fluxes from near surface
                0032     atmospheric state and downward radiation as shown, e.g., in experiment
                0033     `global_ocean.cs32x15` (secondary test `input.seaice` or `input.icedyn` or `input.in_p`)
                0034     is not used here (`#undef ALLOW_BULKFORMULAE`).
                0035
                0036 The **secondary** test, using input files from `input.ebm/`,
                0037 relies on the Energy-Balance Model package (`pkg/ebm`) to compute oceanic surface forcing.<br>
                0038
                0039 **Note:**
                0040
                0041 This secondary test set-up has been moved (in PR #944) from `verification/global_ocean_ebm/`
                0042 and a "README" there still provides some details related to `pkg/ebm` specific
                0043 features used here.
                0044
7fe51dd492 Jean*0045 ## Part 1, using OpenAD Adjoint Compiler:
                0046
                0047 The built process needed to be modified, and some routines
                0048 needed changes. Most changes were commited to default routines,
                0049 the remaining changes are kept in `code_oad/` for now.
                0050
                0051 ### Instructions:
                0052 Configure and compile the code:
f1b47febb7 Jean*0053
7fe51dd492 Jean*0054 ```
                0055   cd build
                0056   ../../../tools/genmake2 -mods ../code_oad [-of my_platform_optionFile]
                0057  [make Clean]
                0058   make adAll
                0059   cd ..
                0060 ```
                0061
                0062 ***Note:*** might want to split the full single step above (make adAll) in
                0063 several intermediate steps such as:
f1b47febb7 Jean*0064
7fe51dd492 Jean*0065 ```
                0066   make cb2m
                0067   make makefile
                0068   make small_f
                0069   make allmods
                0070   make adAll
                0071 ```
f1b47febb7 Jean*0072 where the first step (`cb2m`) invokes a script to convert `COMMON` block headers
                0073 (e.g. `FILE.h`) to `MODULE` headers (`FILE_mod.h`) and create new module files
                0074 (`FILE_mod.F90`); the second step (`makefile`) re-generates the makefile to take
                0075 into account newly created files `FILE_mod.h`, `FILE_mod.F90` ; the third step
                0076 (`small_f`) generates `.f` and `.f90` files. The fourth step (`allmods`)
                0077 compiles all module files `.f90` ; and the fifth and last step compliles all f90
7fe51dd492 Jean*0078 src files.
                0079
                0080 To run primary test:
f1b47febb7 Jean*0081
7fe51dd492 Jean*0082 ```
                0083   cd run
                0084   ln -s ../input_oad/* .
15ec4b1e94 Jean*0085   ./prepare_run
7fe51dd492 Jean*0086   ../build/mitgcmuv_ad > output_oadm.txt
                0087   cd ..
                0088 ```
                0089
                0090 There is comparison output in the directory:
                0091   `results/output_oadm.txt`
                0092
                0093 To run any of secondary `$st` test (`$st` in: `ggl90`, `kpp`):
f1b47febb7 Jean*0094
7fe51dd492 Jean*0095 ```
                0096   cd run
                0097   rm *
                0098   ln -s ../input_oad.$st/* .
                0099   ln -s ../input_oad/* .
                0100   ./prepare_run
                0101   ../build/mitgcmuv_ad > output_oadm.txt
                0102 ```
                0103
                0104 There is comparison output in the directory:
                0105   `results/output_oadm.$st.txt`
                0106
                0107 ## Part 2, using TAF Adjoint Compiler:
                0108 similar to above but using set-up specific code from `code_ad/` and input files from `input_ad/`
                0109
                0110 ### Instructions:
                0111 Configure and compile the code:
f1b47febb7 Jean*0112
7fe51dd492 Jean*0113 ```
                0114   cd build
                0115   ../../../tools/genmake2 -mods ../code_ad [-of my_platform_optionFile]
                0116  [make Clean]
                0117   make depend
                0118   make adall
                0119   cd ..
                0120 ```
                0121
                0122 To run primary test:
f1b47febb7 Jean*0123
7fe51dd492 Jean*0124 ```
                0125   cd run
                0126   ln -s ../input_ad/* .
15ec4b1e94 Jean*0127   ./prepare_run
7fe51dd492 Jean*0128   ../build/mitgcmuv_ad > output_adm.txt
                0129   cd ..
                0130 ```
                0131
                0132 There is comparison output in the directory:
                0133   `results/output_adm.txt`
                0134
f1b47febb7 Jean*0135 To run any of secondary `$st` test (`$st` in: `ggl90`, `w_exf`, `ebm`):
                0136
7fe51dd492 Jean*0137 ```
                0138   cd run
                0139   rm *
                0140   ln -s ../input_ad.$st/* .
                0141   ln -s ../input_ad/* .
                0142   ./prepare_run
                0143   ../build/mitgcmuv_ad > output_adm.txt
                0144 ```
                0145
                0146 There is comparison output in the directory:
                0147   `results/output_adm.$st.txt`
                0148
f1b47febb7 Jean*0149 **Note:**
                0150
                0151 1.  `input_ad.w_exf` set-up has been moved (in PR #830)
                0152     from `verification/global_with_exf/input_ad`
                0153 2.  `input_ad.ebm` set-up has been moved (in PR #944)
                0154     from `verification/global_ocean_ebm/input_ad`
7fe51dd492 Jean*0155
                0156 ## Part 3, using Tapenade Adjoint Compiler:
                0157 similar to above but using set-up specific code from `code_tap/` and input files from `input_tap/`