source: NEMO/trunk/src/TOP/README.rst @ 11723

Last change on this file since 11723 was 11723, checked in by nicolasmartin, 22 months ago

Review of INSTALL.rst

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