source: NEMO/branches/2020/dev_r12563_ASINTER-06_ABL_improvement/src/TOP/README.rst @ 12808

Last change on this file since 12808 was 11734, checked in by nicolasmartin, 14 months ago

Review README for reference confgiurations

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