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

Last change on this file since 10227 was 10201, checked in by nicolasmartin, 2 years ago

Various modifications related to the setting of a NEMO Quick Start Guide

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