= 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 {{{ /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 || || 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.[[BR]][[BR]]0 : initial time step is not compared to the restart file value.[[BR]][[BR]]1 : do not use the value in the restart file.[[BR]][[BR]]2 : calendar parameters read in the restart file. || || cn_trcrst_in cn_trcrst_indir || Suffix of tracers INPUT restart file[[BR]][[BR]]Root directory for the location of INPUT restart files || || cn_trcrst_out[[BR]][[BR]]cn_trcrst_outdir || suffix of tracers OUTPUT restart file[[BR]][[BR]]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)[[BR]][[BR]]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[[BR]][[BR]]nn_cen_h[[BR]][[BR]]nn_cen_v || 2nd order centered scheme[[BR]][[BR]]=2 or 4, horizontal 2nd / 4th order[[BR]][[BR]]=2 or 4, vertical 2nd / 4th order || || ln_trcadv_fct[[BR]][[BR]]nn_fct_h[[BR]][[BR]]nn_fct_v[[BR]][[BR]]nn_fct_zts || FCT scheme[[BR]][[BR]]=2 or 4, horizontal 2nd / 4th order[[BR]][[BR]]=2 or 4, vertical 2nd / 4th order[[BR]][[BR]]>=1,  number of sub-timestep for 2nd order vertical scheme || || ln_trcadv_mus[[BR]][[BR]]ln_mus_ups || MUSCL scheme[[BR]][[BR]]use (T) or not (F) upstream scheme near river mouths || || ln_trcadv_ubs[[BR]][[BR]]nn_ubs_v || UBS scheme[[BR]][[BR]]= 2 , vertical 2nd order FCT || || ln_trcadv_qck || QUICKEST scheme || |||| &namtrc_ldf      !   lateral diffusion scheme for passive tracer || || ln_trcldf_lap[[BR]][[BR]]rn_ahtrc_0 || Laplacian operator (use .T. or not .F.)[[BR]][[BR]]Lateral eddy diffusivity coefficient [m2/s] || || ln_trcldf_bilap[[BR]][[BR]]rn_bhtrc_0 || Bilaplacian operator (use .T. or not .F.)[[BR]][[BR]]Lateral eddy diffusivity coefficient [m2/s] || || ln_trcldf_lev[[BR]][[BR]]ln_trcldf_hor[[BR]][[BR]]ln_trcldf_iso[[BR]][[BR]]ln_trcldf_triad || Iso-level direction (use .T. or not .F.)[[BR]][[BR]]horizontal (geopotential) direction (use .T. or not .F.)[[BR]][[BR]]iso-neutral (standard operator) direction (use .T. or not .F.)[[BR]][[BR]]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[[BR]][[BR]]0 : damping throughout the water column[[BR]][[BR]]1 : no damping in the mixing layer (kz  criteria)[[BR]][[BR]]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[[BR]][[BR]]-1 (no vvl: identical cc in ice and ocean / vvl: cc_ice = 0)[[BR]][[BR]]0 (no vvl: cc_ice = zero / vvl: cc_ice = )[[BR]][[BR]]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 /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[[BR]][[BR]]0 : NO damping of tracers at open boundaries[[BR]][[BR]]1 : Only for tracers forced with external data[[BR]][[BR]]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 ||