Version 14 (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

<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. .

  1. 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).