source: NEMO/branches/2018/dev_r10164_HPC09_ESIWACE_PREP_MERGE/src/TOP/README.rst @ 10372

Last change on this file since 10372 was 10345, checked in by smasson, 2 years ago

dev_r10164_HPC09_ESIWACE_PREP_MERGE: merge with trunk@10344, see #2133

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