1 | *************** |
---|
2 | Oceanic tracers |
---|
3 | *************** |
---|
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 |
---|
19 | ========= |
---|
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`` |
---|
28 | Inert carbon tracers (CFC11,CFC12,SF6) |
---|
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 |
---|
68 | ================== |
---|
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 |
---|
119 | ===================== |
---|
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 | |
---|
141 | .. literalinclude:: ../../namelists/namtrc_snk |
---|
142 | |
---|
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 |
---|
211 | cn_dir = 'usr/work/model/inputdata/' |
---|
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 |
---|
230 | ===================================================== |
---|
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 |
---|
271 | =================================================== |
---|
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 | |
---|
294 | bld::tool::fppkeys key_iomput key_mpp_mpi key_top |
---|
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 | |
---|
322 | bld::tool::fppkeys key_iomput key_mpp_mpi key_top |
---|
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. |
---|