Version 12 (modified by lovato, 3 years ago) (diff)

TOP interface User Quick Guide (NEMO 4.0+)

TOP interface structure

TOP (Tracers in the Ocean Paradigm) is the NEMO hardwired interface toward biogeochemical models and provide the physical constraints/boundaries for oceanic tracers. It consists of a modular framework to handle multiple ocean tracers, including also a variety of built-in modules. TOP interfaces has the following location in the code repository


and the following modules are available:

TRP Interface to NEMO physical core for computing tracers transport
CFC Inert carbon tracers (CFC11,CFC12, SF6)
C14 Radiocarbon passive tracer
AGE Water age tracking
MY_TRC Template for creation of new modules and external BGC models coupling
PISCES Built in BGC model

The usage of TOP is activated by i) including in the configuration definition the component “TOP_SRC” and ii) adding the macro key_top in the configuration cpp file.

As an example, the user can refer to simplest configurations already available in the code GYRE_BFM or GYRE_PISCES.

Note that, since version 4.0, TOP interface core functionalities are activated by means of logical keys and all submodules preprocessing macros from previous versions were removed.

Here below the list of preprocessing keys that applies to the TOP interface (beside key_top):

key_iomput : use XIOS I/O

key_zdfddm & key_zdftke & key_zdfgls: vertical schemes (need to be updated after Merge2017 finalization)

key_trabbl : bottom boundary layer parameterization

key_agrif : enable AGRIF coupling

key_trdtrc & key_trdmxl_trc : trend computation for tracers

TOP synthetic Workflow

A synthetic description of the TOP interface workflow is given below to summarize the steps involved in the computation of biogeochemical and physical trends and their time integration and outputs, by reporting also the principal Fortran subroutine herein involved.

Model initialization (OPA_SRC/nemogcm.F90)

call to trc_init (trcini.F90)

↳ call trc_nam (trcnam.F90) to initialize TOP tracers and run setting

↳ call trc_ini_sms, to initialize each submodule

↳ call trc_ini_trp, to initialize transport for tracers

↳ call trc_ice_ini, to initialize tracers in seaice

↳ call trc_ini_state, read passive tracers from a restart or input data

↳ call trc_sub_ini, setup substepping if nn_dttrc /= 1

Time marching procedure (OPA_SRC/stp.F90)

call to trc_stp.F90 (trcstp.F90)

↳ call trc_sub_stp, averaging physical variables for sub-stepping

↳ call trc_wri, call XIOS for output of data

↳ call trc_sms, compute BGC trends for each submodule

↳ call trc_sms_my_trc, includes also surface and coastal BCs trends

↳ call trc_trp (TRP/trctrp.F90), compute physical trends

↳ call trc_sbc, get trend due to surface concentration/dilution

↳ call trc_adv, compute tracers advection

↳ call to trc_ldf, compute tracers lateral diffusion

↳ call to trc_zdf, vertical mixing and after tracer fields

↳ call to trc_nxt, tracer fields at next time step

↳ call to trc_rad, Correct artificial negative concentrations

↳ call trc_rst_wri, output tracers restart files

TOP namelist Walkthrough


Here below are listed the features/options of the TOP interface accessible through the namelist_top_ref and modifiable by means of namelist_top_cfg (as for NEMO physical ones). 

Note that ## is used to refer to a number in an array field.

&namtrc_run      !   run information
nn_dttrc Time step frequency for TOP computation
ln_top_euler Use Euler Forward integration instead of leap-frog
ln_rsttr Start from a restart file (T) or not (F)
nn_rsttr Restart control.

0 : initial time step is not compared to the restart file value.

1 : do not use the value in the restart file.

2 : calendar parameters read in the restart file.
cn_trcrst_in cn_trcrst_indir Suffix of tracers INPUT restart file

Root directory for the location of INPUT restart files

suffix of tracers OUTPUT restart file

Root directory for the location of OUTPUT restart files
&namtrc          !   tracers definition
jp_bgc Number of passive tracers of the BGC model
ln_pisces / ln_my_trc Run PISCES or MY_TRC BGC modules. There cannot be run at the same time since they both rely on jp_bgc
ln_age, ln_cfc11, ln_cfc12, ln_sf6, ln_c14 Activate sub-modules: tracers are automatically defined within each module. These can run along with main BGC modules.
ln_trcdta Initialisation from data input file (T) or not (F)
ln_trcdmp, ln_trcdmp_clo Add a damping term (T) or not (F)

Add a damping term (T) or not (F) for closed seas
jp_dia3d, jp_dia2d Number of 3D/2D diagnostic variables to populate dedicated array beside the direct usage of iom_put calls.
sn_tracer(##) Data structure to specify tracer name and metadata for the chosen BGC module. Here set initialization and Boundary conditions. See structure description after this table.
&namtrc_dta      !    Initialisation from data input file
sn_trcdta(##) Data structure to read tracers Initial conditions according to sn_tracer%llinit option. See structure description after this table.
rf_trfac(##) Multiplicative factor for initialized tracer. If omitted default is 1.0.
cn_dir Root directory for the location of INPUT data files
&namtrc_adv      !   advection scheme for passive tracer


2nd order centered scheme

=2 or 4, horizontal 2nd / 4th order

=2 or 4, vertical 2nd / 4th order



FCT scheme

=2 or 4, horizontal 2nd / 4th order

=2 or 4, vertical 2nd / 4th order

≥1,  number of sub-timestep for 2nd order vertical scheme

MUSCL scheme

use (T) or not (F) upstream scheme near river mouths

UBS scheme

= 2 , vertical 2nd order FCT
ln_trcadv_qck QUICKEST scheme
&namtrc_ldf      !   lateral diffusion scheme for passive tracer

Laplacian operator (use .T. or not .F.)

Lateral eddy diffusivity coefficient [m2/s]

Bilaplacian operator (use .T. or not .F.)

Lateral eddy diffusivity coefficient [m2/s]



Iso-level direction (use .T. or not .F.)

horizontal (geopotential) direction (use .T. or not .F.)

iso-neutral (standard operator) direction (use .T. or not .F.)

iso-neutral (triad operator) direction (use .T. or not .F.)
rn_fact_lap Multiplicative factor to enhance zonal eddy diffusivity.
&namtrc_zdf      !   vertical physics
ln_trczdf_exp Split explicit (T) or implicit (F) time stepping
nn_trczdf_exp Number of sub-timestep for ln_trczdfexp=T
&namtrc_rad      !  treatment of negative concentrations
ln_trcrad Artificially correct negative concentrations (T) or not (F)
&namtrc_dmp      !   passive tracer newtonian damping
nn_zdmp_tr Vertical shape of damping term

0 : damping throughout the water column

1 : no damping in the mixing layer (kz  criteria)

2 : no damping in the mixed layer (rho crieria)
cn_resto_tr NetCDF filename with input damping coefficients
&namtrc_ice      !    Representation of sea ice growth & melt effects
nn_ice_tr Tracer concentration in sea ice. Available options

-1 (no vvl: identical cc in ice and ocean / vvl: cc_ice = 0)

0 (no vvl: cc_ice = zero / vvl: cc_ice = )

1 prescribed to a namelist value (implemented in pisces or through user definition in trcice_my_trc)
&namtrc_trd      !   diagnostics on tracer trends                       ('key_trdtrc')
nn_trd_trc Time step frequency and tracers trends
nn_ctls_trc Control surface type in mixed-layer trends (0,1 or n<jpk)
rn_ucf_trc Unit conversion factor (=1 → /seconds ; =86400. → /day)
ln_trdmld_trc_restart Use restart (T) or not (F) for ML diagnostics
ln_trdmld_trc_instant Diagnose trends of instantaneous (T) or mean (F) ML T/S
ln_trdtrc(##) Compute trend for nth tracer. Array of logical values.
&namtrc_bc       !   Forcing data for boundary conditions
sn_trcsbc(##), sn_trccbc(##), sn_trcobc(##) Data structure to read tracers boundary conditions according to sn_tracer%llsbc,sn_tracer%llcbc, sn_tracer%llobc options. See structure description after this table.
rn_trsfac(##), rn_trcfac(##), rn_trofac(##) Multiplicative factor for SURFACE (sbc), COASTAL (cbc), and LATERAL (obc) forcing data files
cn_dir_sbc, cn_dir_cbc, cn_dir_obc Root directory for the location of SURFACE (sbc), COASTAL (cbc), and LATERAL (obc) forcing data files
ln_rnf_ctl Remove runoff dilution on tracers with absent river load (only without VVL)
rn_bc_time Time scaling factor for SBC and CBC data (seconds in a day)
&namtrc_bdy      !   Setup of tracer boundary conditions
cn_trc_dflt Open Boundary Condition applied by default to all tracers
cn_trc Boundary conditions used for tracers with data files (selected in namtrc using sn_tracer%llobc)
nn_trcdmp_bdy Use damping timescales defined in nambdy of namelist

0 : NO damping of tracers at open boundaries

1 : Only for tracers forced with external data

2 : Damping applied to all tracers
&namage         !   Water Age module
rn_age_depth Depth over which age tracer reset to zero
rn_age_kill_rate Relaxation timescale (s) for age tracer shallower than age depth