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

<repository>/NEMOGCM/NEMO/TOP_SRC/

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

namelist_top

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 (if >1 substepping is used)
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
cn_trcrst_out cn_trcrst_outdir	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. These modules 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
ln_trcadv_cen nn_cen_h nn_cen_v	2nd order centered scheme =2 or 4, horizontal 2nd / 4th order =2 or 4, vertical 2nd / 4th order
ln_trcadv_fct nn_fct_h nn_fct_v nn_fct_zts	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
ln_trcadv_mus ln_mus_ups	MUSCL scheme use (T) or not (F) upstream scheme near river mouths
ln_trcadv_ubs nn_ubs_v	UBS scheme = 2 , vertical 2nd order FCT
ln_trcadv_qck	QUICKEST scheme
&namtrc_ldf ! lateral diffusion scheme for passive tracer
ln_trcldf_lap rn_ahtrc_0	Laplacian operator (use .T. or not .F.) Lateral eddy diffusivity coefficient [m2/s]
ln_trcldf_bilap rn_bhtrc_0	Bilaplacian operator (use .T. or not .F.) Lateral eddy diffusivity coefficient [m2/s]
ln_trcldf_lev ln_trcldf_hor ln_trcldf_iso ln_trcldf_triad	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

Two main types of data structure are used within TOP interface to initialize tracer properties (1) and to provide related initial and boundary conditions (2).

1. TOP tracers initialization : sn_tracer (namtrc)

Beside providing name and metadata for tracers, here are also defined the use of initial (sn_tracer%llinit) and boundary (sn_tracer%llsbc,sn_tracer%llcbc, sn_tracer%llobc) conditions.

In the following, an example of the full structure definition is given for two idealized tracer both with initial conditions given and the first with surface boundary forcing prescribes, while the second has surface and coastal forcing:

!                          !    name   !           title of the field            !   units    ! initial data ! sbc ! cbc ! obc !

sn_tracer(1)  = 'TRC1' , 'Tracer  1 Concentration                 ',   ' - '    ,  .true., .true., .false., .true.

sn_tracer(2)  = 'TRC2 ' , 'Tracer 2  Concentration                 ',   ' - '    ,  .true., .true., .true., .false.

As tracers in BGC models are increasingly growing, the same structure can be written also in a more compact and readable way:

!                          !    name   !           title of the field            !   units    ! initial data !

sn_tracer(1)  = 'TRC1' , 'Tracer  1 Concentration                 ',   ' - '    ,   .true.

sn_tracer(2)  = 'TRC2 ' , 'Tracer 2  Concentration                 ',   ' - '    ,   .true.

! sbc

sn_tracer(1)%llsbc = .true.

sn_tracer(2)%llsbc = .true.

! cbc

sn_tracer(2)%llcbc = .true.

The data structure is internally initialized by code with dummy names and all initialization/forcing logical fields set to .false. .

2. SBC structure to read input fields : sn_trcdta (namtrc_dta), sn_trcsbc sn_trccbc sn_trcobc (namtrc_bc)

This data structure is based on the general one defined for NEMO core in the SBC component (see details in User Manual SBC Chapter on Input Data specification).

The following example show the data structure in the case of a single tracer with initial conditions contained in the file named tracer_1_data.nc (.nc is implicitly assumed), with a doublef intial value, and located in the usr/work/model/inputdata/ folder:

!          !  file name  ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !

!          !             !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !

sn_trcdta(1)  = ''tracer_1_data'        ,        -12        ,  'TRC1'     ,    .false.   , .true. , 'yearly'  , ''       , ''   , ''

rf_trfac(1) = 2.0

cn_dir = “usr/work/model/inputdata/”

The Lateral Open Boundaries conditions are applied to the segments defined for the physical core of NEMO (see BDY description in the User Manual).