Changes between Version 12 and Version 13 of Working Groups/TOP/TOP-User Quick Guide


Ignore:
Timestamp:
2018-01-17T11:52:45+01:00 (3 years ago)
Author:
lovato
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • Working Groups/TOP/TOP-User Quick Guide

    v12 v13  
    8383== TOP namelist Walkthrough == 
    8484=== namelist_top === 
    85 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).  
     85Here 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). 
    8686 
    8787Note that ## is used to refer to a number in an array field. 
    8888 
    89 |||| &namtrc_run      !   run information || 
    90 || nn_dttrc || Time step frequency for TOP computation || 
     89|||| &'''namtrc_run'''      !   run information || 
     90|| nn_dttrc || Time step frequency for TOP computation (if >1 substepping is used) || 
    9191|| ln_top_euler || Use Euler Forward integration instead of leap-frog || 
    9292|| ln_rsttr || Start from a restart file (T) or not (F) || 
    93 || 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. || 
    94 || cn_trcrst_in cn_trcrst_indir || Suffix of tracers INPUT restart file[[BR]][[BR]]Root directory for the location of INPUT restart files || 
    95 || 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 || 
    96 |||| &namtrc          !   tracers definition || 
     93|| nn_rsttr || Restart control.[[BR]]0 : initial time step is not compared to the restart file value.[[BR]]1 : do not use the value in the restart file.[[BR]]2 : calendar parameters read in the restart file. || 
     94|| cn_trcrst_in [[BR]]cn_trcrst_indir || Suffix of tracers INPUT restart file[[BR]]Root directory for the location of INPUT restart files || 
     95|| cn_trcrst_out[[BR]]cn_trcrst_outdir || suffix of tracers OUTPUT restart file[[BR]]Root directory for the location of OUTPUT restart files || 
     96|||| &'''namtrc'''          !   tracers definition || 
    9797|| jp_bgc || Number of passive tracers of the BGC model || 
    98 || 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 || 
     98|| 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 || 
    9999|| 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. || 
    100100|| ln_trcdta || Initialisation from data input file (T) or not (F) || 
    101 || 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 || 
     101|| ln_trcdmp[[BR]]ln_trcdmp_clo || Add a damping term (T) or not (F)[[BR]]Add a damping term (T) or not (F) for closed seas || 
    102102|| jp_dia3d, jp_dia2d || Number of 3D/2D diagnostic variables to populate dedicated array beside the direct usage of iom_put calls. || 
    103103|| 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. || 
    104 |||| &namtrc_dta      !    Initialisation from data input file || 
     104|||| &'''namtrc_dta'''      !    Initialisation from data input file || 
    105105|| sn_trcdta(##) || Data structure to read tracers Initial conditions according to sn_tracer%llinit option. See structure description after this table. || 
    106106|| rf_trfac(''##'') || Multiplicative factor for initialized tracer. If omitted default is 1.0. || 
    107107|| cn_dir || Root directory for the location of INPUT data files || 
    108 |||| &namtrc_adv      !   advection scheme for passive tracer || 
    109 || 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 || 
    110 || 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 || 
    111 || ln_trcadv_mus[[BR]][[BR]]ln_mus_ups || MUSCL scheme[[BR]][[BR]]use (T) or not (F) upstream scheme near river mouths || 
    112 || ln_trcadv_ubs[[BR]][[BR]]nn_ubs_v || UBS scheme[[BR]][[BR]]= 2 , vertical 2nd order FCT || 
     108|||| &'''namtrc_adv'''      !   advection scheme for passive tracer || 
     109|| ln_trcadv_cen[[BR]]nn_cen_h[[BR]]nn_cen_v || 2nd order centered scheme[[BR]]=2 or 4, horizontal 2nd / 4th order[[BR]]=2 or 4, vertical 2nd / 4th order || 
     110|| ln_trcadv_fct[[BR]]nn_fct_h[[BR]]nn_fct_v[[BR]]nn_fct_zts || FCT scheme[[BR]]=2 or 4, horizontal 2nd / 4th order[[BR]]=2 or 4, vertical 2nd / 4th order[[BR]]>=1,  number of sub-timestep for 2nd order vertical scheme || 
     111|| ln_trcadv_mus[[BR]]ln_mus_ups || MUSCL scheme[[BR]]use (T) or not (F) upstream scheme near river mouths || 
     112|| ln_trcadv_ubs[[BR]]nn_ubs_v || UBS scheme[[BR]]= 2 , vertical 2nd order FCT || 
    113113|| ln_trcadv_qck || QUICKEST scheme || 
    114 |||| &namtrc_ldf      !   lateral diffusion scheme for passive tracer || 
    115 || ln_trcldf_lap[[BR]][[BR]]rn_ahtrc_0 || Laplacian operator (use .T. or not .F.)[[BR]][[BR]]Lateral eddy diffusivity coefficient [m2/s] || 
    116 || ln_trcldf_bilap[[BR]][[BR]]rn_bhtrc_0 || Bilaplacian operator (use .T. or not .F.)[[BR]][[BR]]Lateral eddy diffusivity coefficient [m2/s] || 
    117 || 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.) || 
     114|||| &'''namtrc_ldf'''      !   lateral diffusion scheme for passive tracer || 
     115|| ln_trcldf_lap[[BR]]rn_ahtrc_0 || Laplacian operator (use .T. or not .F.)[[BR]]Lateral eddy diffusivity coefficient [m2/s] || 
     116|| ln_trcldf_bilap[[BR]]rn_bhtrc_0 || Bilaplacian operator (use .T. or not .F.)[[BR]]Lateral eddy diffusivity coefficient [m2/s] || 
     117|| ln_trcldf_lev[[BR]]ln_trcldf_hor[[BR]]ln_trcldf_iso[[BR]]ln_trcldf_triad || Iso-level direction (use .T. or not .F.)[[BR]]Horizontal (geopotential) direction (use .T. or not .F.)[[BR]]Iso-neutral (standard operator) direction (use .T. or not .F.)[[BR]]Iso-neutral (triad operator) direction (use .T. or not .F.) || 
    118118|| rn_fact_lap || Multiplicative factor to enhance zonal eddy diffusivity. || 
    119 |||| &namtrc_zdf      !   vertical physics || 
     119|||| &'''namtrc_zdf'''      !   vertical physics || 
    120120|| ln_trczdf_exp || Split explicit (T) or implicit (F) time stepping || 
    121121|| nn_trczdf_exp || Number of sub-timestep for ln_trczdfexp=T || 
    122 |||| &namtrc_rad      !  treatment of negative concentrations || 
     122|||| &'''namtrc_rad'''      !  treatment of negative concentrations || 
    123123|| ln_trcrad || Artificially correct negative concentrations (T) or not (F) || 
    124 |||| &namtrc_dmp      !   passive tracer newtonian damping || 
    125 || 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) || 
     124|||| &'''namtrc_dmp'''      !   passive tracer newtonian damping || 
     125|| nn_zdmp_tr || Vertical shape of damping term[[BR]]0 : damping throughout the water column[[BR]]1 : no damping in the mixing layer (kz  criteria)[[BR]]2 : no damping in the mixed layer (rho crieria) || 
    126126|| cn_resto_tr || NetCDF filename with input damping coefficients || 
    127 |||| &namtrc_ice      !    Representation of sea ice growth & melt effects || 
     127|||| &namtrc_ice      !    Representation of sea ice growth & melt effects || 
    128128|| 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) || 
    129 |||| &namtrc_trd      !   diagnostics on tracer trends                       ('key_trdtrc') || 
     129|||| &'''namtrc_trd'''      !   diagnostics on tracer trends                       ('key_trdtrc') || 
    130130|| nn_trd_trc || Time step frequency and tracers trends || 
    131131|| nn_ctls_trc || Control surface type in mixed-layer trends (0,1 or n<jpk) || 
     
    134134|| ln_trdmld_trc_instant || Diagnose trends of instantaneous (T) or mean (F) ML T/S || 
    135135|| ln_trdtrc(##) || Compute trend for nth tracer. Array of logical values. || 
    136 |||| &namtrc_bc       !   Forcing data for boundary conditions || 
     136|||| &'''namtrc_bc'''       !   Forcing data for boundary conditions || 
    137137|| 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. || 
    138138|| rn_trsfac(''##''), rn_trcfac(##), rn_trofac(##) || Multiplicative factor for SURFACE (sbc), COASTAL (cbc), and LATERAL (obc) forcing data files || 
     
    140140|| ln_rnf_ctl || Remove runoff dilution on tracers with absent river load (only without VVL) || 
    141141|| rn_bc_time || Time scaling factor for SBC and CBC data (seconds in a day) || 
    142 |||| &namtrc_bdy      !   Setup of tracer boundary conditions || 
     142|||| &'''namtrc_bdy'''      !   Setup of tracer boundary conditions || 
    143143|| cn_trc_dflt || Open Boundary Condition applied by default to all tracers || 
    144144|| cn_trc || Boundary conditions used for tracers with data files (selected in namtrc using sn_tracer%llobc) || 
    145 || 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 || 
    146 |||| &namage         !   Water Age module || 
     145|| nn_trcdmp_bdy || Use damping timescales defined in nambdy of namelist[[BR]]0 : NO damping of tracers at open boundaries[[BR]]1 : Only for tracers forced with external data[[BR]]2 : Damping applied to all tracers || 
     146|||| &'''namage'''         !   Water Age module || 
    147147|| rn_age_depth || Depth over which age tracer reset to zero || 
    148148|| rn_age_kill_rate || Relaxation timescale (s) for age tracer shallower than age depth || 
     149 
     150 
     151 
     152Two main types of data structure are used within TOP interface to initialize tracer properties (1) and to provide related initial and boundary conditions (2). 
     153 
     154 1. TOP tracers initialization : sn_tracer (namtrc) 
     155 
     156 
     157 
     158Beside 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. 
     159 
     160In 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: 
     161 
     162!                          !    name   !           title of the field            !   units    ! initial data ! sbc ! cbc ! obc !  
     163 
     164sn_tracer(1)  = 'TRC1' , 'Tracer  1 Concentration                 ',   ' - '    ,  .true., .true., .false., .true. 
     165 
     166sn_tracer(2)  = 'TRC2 ' , 'Tracer 2  Concentration                 ',   ' - '    ,  .true., .true., .true., .false. 
     167 
     168As tracers in BGC models are increasingly growing, the same structure can be written also in a more compact and readable way: 
     169 
     170!                          !    name   !           title of the field            !   units    ! initial data !  
     171 
     172sn_tracer(1)  = 'TRC1' , 'Tracer  1 Concentration                 ',   ' - '    ,   .true. 
     173 
     174sn_tracer(2)  = 'TRC2 ' , 'Tracer 2  Concentration                 ',   ' - '    ,   .true. 
     175 
     176! sbc 
     177 
     178sn_tracer(1)%llsbc = .true. 
     179 
     180sn_tracer(2)%llsbc = .true. 
     181 
     182! cbc 
     183 
     184sn_tracer(2)%llcbc = .true. 
     185 
     186The data structure is internally initialized by code with dummy names and all initialization/forcing logical fields set to .false. . 
     187 
     188 2. SBC structure to read input fields : sn_trcdta (namtrc_dta), sn_trcsbc sn_trccbc sn_trcobc (namtrc_bc) 
     189 
     190 
     191 
     192This 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). 
     193 
     194The 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: 
     195 
     196!          !  file name  ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask ! 
     197 
     198!          !             !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      ! 
     199 
     200   sn_trcdta(1)  = !''tracer_1_data'        ,        -12        ,  'TRC1'     ,    .false.   , .true. , 'yearly'  , !''       , !''   , !'' 
     201 
     202rf_trfac(1) = 2.0 
     203 
     204cn_dir = “usr/work/model/inputdata/” 
     205 
     206The Lateral Open Boundaries conditions are applied to the segments defined for the physical core of NEMO (see BDY description in the User Manual).