[10460] | 1 | *************** |
---|
| 2 | Oceanic tracers |
---|
| 3 | *************** |
---|
[10201] | 4 | |
---|
| 5 | .. contents:: |
---|
| 6 | :local: |
---|
| 7 | |
---|
| 8 | TOP (Tracers in the Ocean Paradigm) is the NEMO hardwired interface toward biogeochemical models and |
---|
| 9 | provide the physical constraints/boundaries for oceanic tracers. |
---|
| 10 | It consists of a modular framework to handle multiple ocean tracers, including also a variety of built-in modules. |
---|
| 11 | |
---|
| 12 | This component of the NEMO framework allows one to exploit available modules (see below) and |
---|
| 13 | further develop a range of applications, spanning from the implementation of a dye passive tracer to |
---|
| 14 | evaluate dispersion processes (by means of MY_TRC), track water masses age (AGE module), |
---|
| 15 | assess the ocean interior penetration of persistent chemical compounds (e.g., gases like CFC or even PCBs), |
---|
| 16 | up to the full set of equations involving marine biogeochemical cycles. |
---|
| 17 | |
---|
| 18 | Structure |
---|
[10279] | 19 | ========= |
---|
[10201] | 20 | |
---|
| 21 | TOP interface has the following location in the source code ``./src/MBG/`` and |
---|
| 22 | the following modules are available: |
---|
| 23 | |
---|
| 24 | ``TRP`` |
---|
| 25 | Interface to NEMO physical core for computing tracers transport |
---|
| 26 | |
---|
| 27 | ``CFC`` |
---|
[10549] | 28 | Inert carbon tracers (CFC11,CFC12,SF6) |
---|
[10201] | 29 | |
---|
| 30 | ``C14`` |
---|
| 31 | Radiocarbon passive tracer |
---|
| 32 | |
---|
| 33 | ``AGE`` |
---|
| 34 | Water age tracking |
---|
| 35 | |
---|
| 36 | ``MY_TRC`` |
---|
| 37 | Template for creation of new modules and external BGC models coupling |
---|
| 38 | |
---|
| 39 | ``PISCES`` |
---|
| 40 | Built in BGC model. |
---|
| 41 | See [https://www.geosci-model-dev.net/8/2465/2015/gmd-8-2465-2015-discussion.html Aumont et al. (2015)] for |
---|
| 42 | a throughout description. | |
---|
| 43 | |
---|
| 44 | The usage of TOP is activated i) by including in the configuration definition the component ``MBG`` and |
---|
| 45 | ii) by adding the macro ``key_top`` in the configuration CPP file |
---|
| 46 | (see for more details [http://forge.ipsl.jussieu.fr/nemo/wiki/Users "Learn more about the model"]). |
---|
| 47 | |
---|
| 48 | As an example, the user can refer to already available configurations in the code, |
---|
| 49 | ``GYRE_PISCES`` being the NEMO biogeochemical demonstrator and |
---|
| 50 | ``GYRE_BFM`` to see the required configuration elements to couple with an external biogeochemical model |
---|
| 51 | (see also Section 4) . |
---|
| 52 | |
---|
| 53 | Note that, since version 4.0, TOP interface core functionalities are activated by means of logical keys and |
---|
| 54 | all submodules preprocessing macros from previous versions were removed. |
---|
| 55 | |
---|
| 56 | Here below the list of preprocessing keys that applies to the TOP interface (beside ``key_top``): |
---|
| 57 | |
---|
| 58 | ``key_iomput`` |
---|
| 59 | use XIOS I/O |
---|
| 60 | |
---|
| 61 | ``key_agrif`` |
---|
| 62 | enable AGRIF coupling |
---|
| 63 | |
---|
| 64 | ``key_trdtrc`` & ``key_trdmxl_trc`` |
---|
| 65 | trend computation for tracers |
---|
| 66 | |
---|
| 67 | Synthetic Workflow |
---|
[10279] | 68 | ================== |
---|
[10201] | 69 | |
---|
| 70 | A synthetic description of the TOP interface workflow is given below to summarize the steps involved in |
---|
| 71 | the computation of biogeochemical and physical trends and their time integration and outputs, |
---|
| 72 | by reporting also the principal Fortran subroutine herein involved. |
---|
| 73 | |
---|
| 74 | **Model initialization (OPA_SRC/nemogcm.F90)** |
---|
| 75 | |
---|
| 76 | call to trc_init (trcini.F90) |
---|
| 77 | |
---|
| 78 | ↳ call trc_nam (trcnam.F90) to initialize TOP tracers and run setting |
---|
| 79 | |
---|
| 80 | ↳ call trc_ini_sms, to initialize each submodule |
---|
| 81 | |
---|
| 82 | ↳ call trc_ini_trp, to initialize transport for tracers |
---|
| 83 | |
---|
| 84 | ↳ call trc_ice_ini, to initialize tracers in seaice |
---|
| 85 | |
---|
| 86 | ↳ call trc_ini_state, read passive tracers from a restart or input data |
---|
| 87 | |
---|
| 88 | ↳ call trc_sub_ini, setup substepping if {{{nn_dttrc /= 1}}} |
---|
| 89 | |
---|
| 90 | **Time marching procedure (OPA_SRC/stp.F90)** |
---|
| 91 | |
---|
| 92 | call to trc_stp.F90 (trcstp.F90) |
---|
| 93 | |
---|
| 94 | ↳ call trc_sub_stp, averaging physical variables for sub-stepping |
---|
| 95 | |
---|
| 96 | ↳ call trc_wri, call XIOS for output of data |
---|
| 97 | |
---|
| 98 | ↳ call trc_sms, compute BGC trends for each submodule |
---|
| 99 | |
---|
| 100 | ↳ call trc_sms_my_trc, includes also surface and coastal BCs trends |
---|
| 101 | |
---|
| 102 | ↳ call trc_trp (TRP/trctrp.F90), compute physical trends |
---|
| 103 | |
---|
| 104 | ↳ call trc_sbc, get trend due to surface concentration/dilution |
---|
| 105 | |
---|
| 106 | ↳ call trc_adv, compute tracers advection |
---|
| 107 | |
---|
| 108 | ↳ call to trc_ldf, compute tracers lateral diffusion |
---|
| 109 | |
---|
| 110 | ↳ call to trc_zdf, vertical mixing and after tracer fields |
---|
| 111 | |
---|
| 112 | ↳ call to trc_nxt, tracer fields at next time step. Lateral Boundary Conditions are solved in here. |
---|
| 113 | |
---|
| 114 | ↳ call to trc_rad, Correct artificial negative concentrations |
---|
| 115 | |
---|
| 116 | ↳ call trc_rst_wri, output tracers restart files |
---|
| 117 | |
---|
| 118 | Namelists walkthrough |
---|
[10279] | 119 | ===================== |
---|
[10201] | 120 | |
---|
| 121 | namelist_top |
---|
| 122 | ------------ |
---|
| 123 | |
---|
| 124 | Here below are listed the features/options of the TOP interface accessible through the namelist_top_ref and |
---|
| 125 | modifiable by means of namelist_top_cfg (as for NEMO physical ones). |
---|
| 126 | |
---|
| 127 | Note that ## is used to refer to a number in an array field. |
---|
| 128 | |
---|
| 129 | .. literalinclude:: ../../namelists/namtrc_run |
---|
| 130 | |
---|
| 131 | .. literalinclude:: ../../namelists/namtrc |
---|
| 132 | |
---|
| 133 | .. literalinclude:: ../../namelists/namtrc_dta |
---|
| 134 | |
---|
| 135 | .. literalinclude:: ../../namelists/namtrc_adv |
---|
| 136 | |
---|
| 137 | .. literalinclude:: ../../namelists/namtrc_ldf |
---|
| 138 | |
---|
| 139 | .. literalinclude:: ../../namelists/namtrc_rad |
---|
| 140 | |
---|
[10549] | 141 | .. literalinclude:: ../../namelists/namtrc_snk |
---|
| 142 | |
---|
[10201] | 143 | .. literalinclude:: ../../namelists/namtrc_dmp |
---|
| 144 | |
---|
| 145 | .. literalinclude:: ../../namelists/namtrc_ice |
---|
| 146 | |
---|
| 147 | .. literalinclude:: ../../namelists/namtrc_trd |
---|
| 148 | |
---|
| 149 | .. literalinclude:: ../../namelists/namtrc_bc |
---|
| 150 | |
---|
| 151 | .. literalinclude:: ../../namelists/namtrc_bdy |
---|
| 152 | |
---|
| 153 | .. literalinclude:: ../../namelists/namage |
---|
| 154 | |
---|
| 155 | Two main types of data structure are used within TOP interface to initialize tracer properties (1) and |
---|
| 156 | to provide related initial and boundary conditions (2). |
---|
| 157 | |
---|
| 158 | **1. TOP tracers initialization**: sn_tracer (namtrc) |
---|
| 159 | |
---|
| 160 | Beside providing name and metadata for tracers, |
---|
| 161 | here are also defined the use of initial ({{{sn_tracer%llinit}}}) and |
---|
| 162 | boundary ({{{sn_tracer%llsbc, sn_tracer%llcbc, sn_tracer%llobc}}}) conditions. |
---|
| 163 | |
---|
| 164 | In the following, an example of the full structure definition is given for two idealized tracers both with |
---|
| 165 | initial conditions given, while the first has only surface boundary forcing and |
---|
| 166 | the second both surface and coastal forcings: |
---|
| 167 | |
---|
| 168 | .. code-block:: fortran |
---|
| 169 | |
---|
| 170 | ! ! name ! title of the field ! units ! initial data ! sbc ! cbc ! obc ! |
---|
| 171 | sn_tracer(1) = 'TRC1' , 'Tracer 1 Concentration ', ' - ' , .true. , .true., .false., .true. |
---|
| 172 | sn_tracer(2) = 'TRC2 ' , 'Tracer 2 Concentration ', ' - ' , .true. , .true., .true. , .false. |
---|
| 173 | |
---|
| 174 | As tracers in BGC models are increasingly growing, |
---|
| 175 | the same structure can be written also in a more compact and readable way: |
---|
| 176 | |
---|
| 177 | .. code-block:: fortran |
---|
| 178 | |
---|
| 179 | ! ! name ! title of the field ! units ! initial data ! |
---|
| 180 | sn_tracer(1) = 'TRC1' , 'Tracer 1 Concentration ', ' - ' , .true. |
---|
| 181 | sn_tracer(2) = 'TRC2 ' , 'Tracer 2 Concentration ', ' - ' , .true. |
---|
| 182 | ! sbc |
---|
| 183 | sn_tracer(1)%llsbc = .true. |
---|
| 184 | sn_tracer(2)%llsbc = .true. |
---|
| 185 | ! cbc |
---|
| 186 | sn_tracer(2)%llcbc = .true. |
---|
| 187 | |
---|
| 188 | The data structure is internally initialized by code with dummy names and |
---|
| 189 | all initialization/forcing logical fields set to .false. . |
---|
| 190 | |
---|
| 191 | **2. Structures to read input initial and boundary conditions**: namtrc_dta (sn_trcdta), namtrc_bc (sn_trcsbc/sn_trccbc/sn_trcobc) |
---|
| 192 | |
---|
| 193 | The overall data structure (Fortran type) is based on the general one defined for NEMO core in the SBC component |
---|
| 194 | (see details in User Manual SBC Chapter on Input Data specification). |
---|
| 195 | |
---|
| 196 | Input fields are prescribed within namtrc_dta (with sn_trcdta structure), |
---|
| 197 | while Boundary Conditions are applied to the model by means of namtrc_bc, |
---|
| 198 | with dedicated structure fields for surface (sn_trcsbc), riverine (sn_trccbc), and |
---|
| 199 | lateral open (sn_trcobc) boundaries. |
---|
| 200 | |
---|
| 201 | The following example illustrates the data structure in the case of initial condition for |
---|
| 202 | a single tracer contained in the file named tracer_1_data.nc (.nc is implicitly assumed in namelist filename), |
---|
| 203 | with a doubled initial value, and located in the usr/work/model/inputdata/ folder: |
---|
| 204 | |
---|
| 205 | .. code-block:: fortran |
---|
| 206 | |
---|
| 207 | ! ! file name ! frequency (hours) ! variable ! time interp. ! clim ! 'yearly'/ ! weights ! rotation ! land/sea mask ! |
---|
| 208 | ! ! ! (if <0 months) ! name ! (logical) ! (T/F) ! 'monthly' ! filename ! pairing ! filename ! |
---|
| 209 | sn_trcdta(1) = 'tracer_1_data' , -12 , 'TRC1' , .false. , .true. , 'yearly' , '' , '' , '' |
---|
| 210 | rf_trfac(1) = 2.0 |
---|
[14453] | 211 | cn_dir = 'usr/work/model/inputdata/' |
---|
[10201] | 212 | |
---|
| 213 | Note that, the Lateral Open Boundaries conditions are applied on the segments defined for the physical core of NEMO |
---|
| 214 | (see BDY description in the User Manual). |
---|
| 215 | |
---|
| 216 | namelist_trc |
---|
| 217 | ------------ |
---|
| 218 | |
---|
| 219 | Here below the description of namelist_trc_ref used to handle Carbon tracers modules, namely CFC and C14. |
---|
| 220 | |
---|
| 221 | |||| &'''namcfc''' ! CFC || |
---|
| 222 | |
---|
| 223 | |||| &'''namc14_typ''' ! C14 - type of C14 tracer, default values of C14/C and pco2 || |
---|
| 224 | |
---|
| 225 | |||| &'''namc14_sbc''' ! C14 - surface BC || |
---|
| 226 | |
---|
| 227 | |||| &'''namc14_fcg''' ! files & dates || |
---|
| 228 | |
---|
| 229 | ``MY_TRC`` interface for coupling external BGC models |
---|
[10279] | 230 | ===================================================== |
---|
[10201] | 231 | |
---|
| 232 | The generalized interface is pivoted on MY_TRC module that contains template files to build the coupling between |
---|
| 233 | NEMO and any external BGC model. |
---|
| 234 | |
---|
| 235 | The call to MY_TRC is activated by setting ``ln_my_trc = .true.`` (in namtrc) |
---|
| 236 | |
---|
| 237 | The following 6 fortran files are available in MY_TRC with the specific purposes here described. |
---|
| 238 | |
---|
| 239 | ``par_my_trc.F90`` |
---|
| 240 | This module allows to define additional arrays and public variables to be used within the MY_TRC interface |
---|
| 241 | |
---|
| 242 | ``trcini_my_trc.F90`` |
---|
| 243 | Here are initialized user defined namelists and the call to the external BGC model initialization procedures to |
---|
| 244 | populate general tracer array (trn and trb). Here are also likely to be defined suport arrays related to |
---|
| 245 | system metrics that could be needed by the BGC model. |
---|
| 246 | |
---|
| 247 | ``trcnam_my_trc.F90`` |
---|
| 248 | This routine is called at the beginning of trcini_my_trc and should contain the initialization of |
---|
| 249 | additional namelists for the BGC model or user-defined code. |
---|
| 250 | |
---|
| 251 | ``trcsms_my_trc.F90`` |
---|
| 252 | The routine performs the call to Boundary Conditions and its main purpose is to |
---|
| 253 | contain the Source-Minus-Sinks terms due to the biogeochemical processes of the external model. |
---|
| 254 | Be aware that lateral boundary conditions are applied in trcnxt routine. |
---|
| 255 | IMPORTANT: the routines to compute the light penetration along the water column and |
---|
| 256 | the tracer vertical sinking should be defined/called in here, as generalized modules are still missing in |
---|
| 257 | the code. |
---|
| 258 | |
---|
| 259 | ``trcice_my_trc.F90`` |
---|
| 260 | Here it is possible to prescribe the tracers concentrations in the seaice that will be used as |
---|
| 261 | boundary conditions when ice melting occurs (nn_ice_tr =1 in namtrc_ice). |
---|
| 262 | See e.g. the correspondent PISCES subroutine. |
---|
| 263 | |
---|
| 264 | ``trcwri_my_trc.F90`` |
---|
| 265 | This routine performs the output of the model tracers (only those defined in namtrc) using IOM module |
---|
| 266 | (see Manual Chapter “Output and Diagnostics”). |
---|
| 267 | It is possible to place here the output of additional variables produced by the model, |
---|
| 268 | if not done elsewhere in the code, using the call to iom_put. |
---|
| 269 | |
---|
| 270 | Coupling an external BGC model using NEMO framework |
---|
[10279] | 271 | =================================================== |
---|
[10201] | 272 | |
---|
| 273 | The coupling with an external BGC model through the NEMO compilation framework can be achieved in |
---|
| 274 | different ways according to the degree of coding complexity of the Biogeochemical model, like e.g., |
---|
| 275 | the whole code is made only by one file or it has multiple modules and interfaces spread across several subfolders. |
---|
| 276 | |
---|
| 277 | Beside the 6 core files of MY_TRC module, let’s assume an external BGC model named *MYBGC* and constituted by |
---|
| 278 | a rather essential coding structure, likely few Fortran files. |
---|
| 279 | The new coupled configuration name is *NEMO_MYBGC*. |
---|
| 280 | |
---|
| 281 | The best solution is to have all files (the modified ``MY_TRC`` routines and the BGC model ones) placed in |
---|
| 282 | a unique folder with root ``MYBGCPATH`` and to use the makenemo external readdressing of ``MY_SRC`` folder. |
---|
| 283 | |
---|
| 284 | The coupled configuration listed in ``work_cfgs.txt`` will look like |
---|
| 285 | |
---|
| 286 | :: |
---|
| 287 | |
---|
| 288 | NEMO_MYBGC OPA_SRC TOP_SRC |
---|
| 289 | |
---|
| 290 | and the related ``cpp_MYBGC.fcm`` content will be |
---|
| 291 | |
---|
| 292 | .. code-block:: perl |
---|
| 293 | |
---|
[10549] | 294 | bld::tool::fppkeys key_iomput key_mpp_mpi key_top |
---|
[10201] | 295 | |
---|
| 296 | the compilation with ``makenemo`` will be executed through the following syntax |
---|
| 297 | |
---|
| 298 | .. code-block:: console |
---|
| 299 | |
---|
| 300 | $ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>' |
---|
| 301 | |
---|
| 302 | The makenemo feature “-e” was introduced to readdress at compilation time the standard MY_SRC folder |
---|
| 303 | (usually found in NEMO configurations) with a user defined external one. |
---|
| 304 | |
---|
| 305 | The compilation of more articulated BGC model code & infrastructure, like in the case of BFM |
---|
| 306 | ([http://www.bfm-community.eu/publications/bfmnemomanual_r1.0_201508.pdf BFM-NEMO coupling manual]), |
---|
| 307 | requires some additional features. |
---|
| 308 | |
---|
| 309 | As before, let’s assume a coupled configuration name *NEMO_MYBGC*, |
---|
| 310 | but in this case MYBGC model root becomes ``<MYBGCPATH>`` that contains 4 different subfolders for |
---|
| 311 | biogeochemistry, named ``initialization``, ``pelagic``, and ``benthic``, and |
---|
| 312 | a separate one named ``nemo_coupling`` including the modified ``MY_SRC`` routines. |
---|
| 313 | The latter folder containing the modified NEMO coupling interface will be still linked using |
---|
| 314 | the makenemo “-e” option. |
---|
| 315 | |
---|
| 316 | In order to include the BGC model subfolders in the compilation of NEMO code, |
---|
| 317 | it will be necessary to extend the configuration ``cpp_NEMO_MYBGC.fcm`` file to include the specific paths of |
---|
| 318 | ``MYBGC`` folders, as in the following example |
---|
| 319 | |
---|
| 320 | .. code-block:: perl |
---|
| 321 | |
---|
[10549] | 322 | bld::tool::fppkeys key_iomput key_mpp_mpi key_top |
---|
[10201] | 323 | |
---|
| 324 | src::MYBGC::initialization <MYBGCPATH>/initialization |
---|
| 325 | src::MYBGC::pelagic <MYBGCPATH>/pelagic |
---|
| 326 | src::MYBGC::benthic <MYBGCPATH>/benthic |
---|
| 327 | |
---|
| 328 | bld::pp::MYBGC 1 |
---|
| 329 | bld::tool::fppflags::MYBGC %FPPFLAGS |
---|
| 330 | bld::tool::fppkeys %bld::tool::fppkeys MYBGC_MACROS |
---|
| 331 | |
---|
| 332 | where *MYBGC_MACROS* is the space delimited list of macros used in *MYBGC* model for |
---|
| 333 | selecting/excluding specific parts of the code. |
---|
| 334 | The BGC model code will be preprocessed in the configuration ``BLD`` folder as for NEMO, |
---|
| 335 | but with an independent path, like ``NEMO_MYBGC/BLD/MYBGC/<subforlders>``. |
---|
| 336 | |
---|
| 337 | The compilation will be performed similarly to in the previous case with the following |
---|
| 338 | |
---|
| 339 | .. code-block:: console |
---|
| 340 | |
---|
| 341 | $ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>/nemo_coupling' |
---|
| 342 | |
---|
| 343 | Note that, the additional lines specific for the BGC model source and build paths can be written into |
---|
| 344 | a separate file, e.g. named ``MYBGC.fcm``, and then simply included in the ``cpp_NEMO_MYBGC.fcm`` as follow |
---|
| 345 | |
---|
| 346 | .. code-block:: perl |
---|
| 347 | |
---|
| 348 | bld::tool::fppkeys key_zdftke key_dynspg_ts key_iomput key_mpp_mpi key_top |
---|
| 349 | inc <MYBGCPATH>/MYBGC.fcm |
---|
| 350 | |
---|
| 351 | This will enable a more portable compilation structure for all MYBGC related configurations. |
---|
| 352 | |
---|
| 353 | **Important**: the coupling interface contained in nemo_coupling cannot be added using the FCM syntax, |
---|
| 354 | as the same files already exists in NEMO and they are overridden only with the readdressing of MY_SRC contents to |
---|
| 355 | avoid compilation conflicts due to duplicate routines. |
---|
| 356 | |
---|
| 357 | All modifications illustrated above, can be easily implemented using shell or python scripting to |
---|
| 358 | edit the NEMO configuration CPP.fcm file and to create the BGC model specific FCM compilation file with code paths. |
---|