[[PageOutline()]]

[[TOC(WorkingGroups/top-dg/*, depth=1)]]

= '''NEMO v3.6 TOP BDY Patch''' =
Last edition: '''[[Wikinfo(changed_ts)]]''' by '''[[Wikinfo(changed_by)]]'''

'''BEFORE USE''' : this patch is meant to provide only the core functionality for TOP BDY under NEMO v3.6 ([raw-attachment:N36_TOP_BDY_patch.tar]). 

__Official support of System Team for tracers BDY will be given only for NEMO v4.0+ versions.__

== Description  ==

This patch enables the core support of BDY for TOP passive tracers with NEMO v3.6 (tested with r10254).
Note that in this patch, routines that provide to initialization/reading of all Boundary conditions (trcbc.f90) were also updated.

__BDY schemes__ included in this version are the following (see trcbdy.F90): 
* '''frs''' : Flow Relaxation Scheme 
* '''specified''' : Specified value
* '''neumann''' : Duplicate the value for tracers (as in NEMO v4.0)
* '''orlanski''' : Orlanski radiation 
* '''orlanski_npo''' : Orlanski radiation with adaptive nudging

Refer to the BDY description of NEMO manual for further details on the different schemes.

In '''namelist_top_ref''' the following changes are necessary (see the patched version contained in the code provided):

{{{
 !-----------------------------------------------------------------------
 &namtrc_bc
 !
   cn_dir_sbc        =  './'      !  root directory for the location of SURFACE data files
   cn_dir_cbc        =  './'      !  root directory for the location of COASTAL data files
   cn_dir_obc        =  './'      !  root directory for the location of OPEN data files
/

!----------------------------------------------------------------------
!namtrc_bdy       !   Setup of tracer boundary conditions
!-----------------------------------------------------------------------
$namtrc_bdy
   cn_trc_dflt     =  'neumann'    !  OBC applied by default to all tracers
   cn_trc          =  'none'       !  Boundary conditions applied to the passive tracers (selected in namtrc)

   nn_trcdmp_bdy   = 0     !  Use damping timescales defined in nambdy of namelist
                           !  = 0 NO damping of tracers at open boudaries
                           !  = 1 Only for tracers forced with external data
                           !  = 2 Damping applied to all tracers
 /
}}}

Details on the usage of these namelists and the setup of a one tracer case are given below.


== Usage walktrough  ==

Code is contained in the attached tarball ([raw-attachment:N36_TOP_BDY_patch.tar]) and it consists of modified files wrapped in the classic "MY_SRC" folder to be added in NEMO configuration.
These files have to be unpacked in the MY_SRC folder of your configuration in order to be used.

__REMINDER__: MY_SRC contains user modified versions of NEMO routines or new pieces of code that are used at compilation time to supersede at original ones.

In the following example the user defined tracer module MY_TRC is used to setup a simple one passive tracer case (need to add ''key_my_trc'' in the configuration cpp file)
and specific modified files are also available in the tarball.

Note that '''namelist_top_ref''' has to be modified by the user in <NEMODIR>/NEMOGCM/CONFIG/SHARED according to the description above (or the sample file provided in the tarball).

All boundary conditions are controlled within the namelist '''namtrc''' in namelist_top_(cfg/ref).
A modified fortran data structure of namtrc was here developed to set the different boundary conditions of passive tracers, as in the following example of namelist_top_cfg for one tracer :

{{{
!-----------------------------------------------------------------------
&namtrc     !   tracers definition
!-----------------------------------------------------------------------
!                !    name   !           title of the field              ! initial data ! initial data !   sbc   !   cbc   !   obc   ! save   !
!                !           !                                           !  units       ! from file    !         !         !         ! or not !
!                !           !                                           !              ! or not       !         !         !         !        !
   sn_tracer(1)   = 'TRACER1  ' , 'Tracer1 for key_my_trc               ',  'unitless'  ,   .true.     , .false. , .true.  , .true.  ,  .true.

...
/
}}}
where the new options relates to the provision of SURFACE (sbc), COASTAL (cbc), or  OPEN lateral Boundaries (obc) data for  sn_tracer(1)  named TRACER1.

In '''namtrc_bc''' are provided the different boundary conditions for passive tracers, see the example below of namelist_top_cfg:

{{{
!----------------------------------------------------------------------
&namtrc_bc        !   data for boundary conditions
!-----------------------------------------------------------------------
!                !  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_trcsbc(1)  = 'TRACER_SBC'        ,        -12        ,  'TRACER_SUR'     ,    .false.   , .true. , 'yearly'  , ''       , ''   , ''
   rn_trsfac(1)  = 1.0
   sn_trccbc(1)  = 'TRACER_CBC'        ,        -12        ,  'TRACER_RIV'     ,    .false.   , .true. , 'yearly'  , ''       , ''   , ''
   rn_trcfac(1)  = 1.0
   sn_trcobc(1)  = 'TRACER_BDY'        ,        -12        ,  'TRACER_BDY'     ,    .false.   , .true. , 'yearly'  , ''       , ''   , ''
   rn_trofac(1)  = 1.0
   !
   cn_dir_sbc        =  './'      !  root directory for the location of SURFACE data files
   cn_dir_cbc        =  './'      !  root directory for the location of COASTAL data files
   cn_dir_obc        =  './'      !  root directory for the location of OPEN data files
/
}}}

Input files are provided using the standard NEMO fldread structure and it follows the convention sn_trcsbc = surface, sn_trccbc = coastal, sn_trcobc = open lateral,
with the corresponding scaling factors rn_trsfac = surface, rn_trcfac = coastal, rn_trofac = open lateral.

BDY schemes are setup in the namelist '''namtrc_bdy'''.  In the following example for 1 tracer, we set the use of orlanski_npo scheme and no tracer damping:

{{{
!----------------------------------------------------------------------
!namtrc_bdy       !   Setup of tracer boundary conditions
!-----------------------------------------------------------------------
$namtrc_bdy
   cn_trc_dflt     =  'neumann'    !  OBC applied by default to all tracers
   cn_trc          =  'orlanski_npo'       !  Boundary conditions applied to the passive tracers (selected in namtrc)

   nn_trcdmp_bdy   = 0     !  Use damping timescales defined in nambdy of namelist
 /
}}}


Here below a summary of available options
|| cn_trc_dflt || Default BDY scheme for all passive tracers ||
|| cn_trc || Specific BDY scheme to be applied for tracers that are forced with external data files, setup via namtrc ||
||nn_trcdmp_bdy || tracer damping, with timescales defined in nambdy of namelist_(ref/cfg) ||
|| || 0 : NO damping of tracers at open boundaries  ||
|| || 1 : Only for tracers forced with external data ||
|| || 2 : Damping applied to all tracers ||