Unstructured Open Boundary Conditions (key_ bdy) (BDY)

!-----------------------------------------------------------------------
&nambdy        !  unstructured open boundaries                          ("key_bdy")
!-----------------------------------------------------------------------
    nb_bdy         = 0                    !  number of open boundary sets
    ln_coords_file = .true.               !  =T : read bdy coordinates from file
    cn_coords_file = 'coordinates.bdy.nc' !  bdy coordinates files
    ln_mask_file   = .false.              !  =T : read mask from file
    cn_mask_file   = ''                   !  name of mask file (if ln_mask_file=.TRUE.)
    cn_dyn2d       = 'none'               !
    nn_dyn2d_dta   =  0                   !  = 0, bdy data are equal to the initial state
                                          !  = 1, bdy data are read in 'bdydata   .nc' files
                                          !  = 2, use tidal harmonic forcing data from files
                                          !  = 3, use external data AND tidal harmonic forcing
    cn_dyn3d      =  'none'               !
    nn_dyn3d_dta  =  0                    !  = 0, bdy data are equal to the initial state
                                          !  = 1, bdy data are read in 'bdydata   .nc' files
    cn_tra        =  'none'               !
    nn_tra_dta    =  0                    !  = 0, bdy data are equal to the initial state
                                          !  = 1, bdy data are read in 'bdydata   .nc' files
    cn_ice_lim      =  'none'             !
    nn_ice_lim_dta  =  0                  !  = 0, bdy data are equal to the initial state
                                          !  = 1, bdy data are read in 'bdydata   .nc' files
    rn_ice_tem      = 270.                !  lim3 only: arbitrary temperature of incoming sea ice
    rn_ice_sal      = 10.                 !  lim3 only:      --   salinity           --
    rn_ice_age      = 30.                 !  lim3 only:      --   age                --

    ln_tra_dmp    =.false.                !  open boudaries conditions for tracers
    ln_dyn3d_dmp  =.false.                !  open boundary condition for baroclinic velocities
    rn_time_dmp   =  1.                   ! Damping time scale in days
    rn_time_dmp_out =  1.                 ! Outflow damping time scale
    nn_rimwidth   = 10                    !  width of the relaxation zone
    ln_vol        = .false.               !  total volume correction (see nn_volctl parameter)
    nn_volctl     = 1                     !  = 0, the total water flux across open boundaries is zero
/

/home/ntm/Workspace/NEMO/nemo_v3_6_STABLE/DOC/Namelists/nambdy_index

!-----------------------------------------------------------------------
&nambdy_dta      !  open boundaries - external data           ("key_bdy")
!-----------------------------------------------------------------------
!              !  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      !
   bn_ssh =     'amm12_bdyT_u2d' ,         24        , 'sossheig' ,     .true.     , .false. ,  'daily'  ,    ''    ,   ''     , ''
   bn_u2d =     'amm12_bdyU_u2d' ,         24        , 'vobtcrtx' ,     .true.     , .false. ,  'daily'  ,    ''    ,   ''     , ''
   bn_v2d =     'amm12_bdyV_u2d' ,         24        , 'vobtcrty' ,     .true.     , .false. ,  'daily'  ,    ''    ,   ''     , ''
   bn_u3d  =    'amm12_bdyU_u3d' ,         24        , 'vozocrtx' ,     .true.     , .false. ,  'daily'  ,    ''    ,   ''     , ''
   bn_v3d  =    'amm12_bdyV_u3d' ,         24        , 'vomecrty' ,     .true.     , .false. ,  'daily'  ,    ''    ,   ''     , ''
   bn_tem  =    'amm12_bdyT_tra' ,         24        , 'votemper' ,     .true.     , .false. ,  'daily'  ,    ''    ,   ''     , ''
   bn_sal  =    'amm12_bdyT_tra' ,         24        , 'vosaline' ,     .true.     , .false. ,  'daily'  ,    ''    ,   ''     , ''
! for lim2
!   bn_frld  =    'amm12_bdyT_ice' ,         24        , 'ileadfra' ,     .true.     , .false. ,  'daily'  ,    ''    ,   ''     , ''
!   bn_hicif =    'amm12_bdyT_ice' ,         24        , 'iicethic' ,     .true.     , .false. ,  'daily'  ,    ''    ,   ''     , ''
!   bn_hsnif =    'amm12_bdyT_ice' ,         24        , 'isnowthi' ,     .true.     , .false. ,  'daily'  ,    ''    ,   ''     , ''
! for lim3
!   bn_a_i  =    'amm12_bdyT_ice' ,         24        , 'ileadfra' ,     .true.     , .false. ,  'daily'  ,    ''    ,   ''     , ''
!   bn_ht_i =    'amm12_bdyT_ice' ,         24        , 'iicethic' ,     .true.     , .false. ,  'daily'  ,    ''    ,   ''     , ''
!   bn_ht_s =    'amm12_bdyT_ice' ,         24        , 'isnowthi' ,     .true.     , .false. ,  'daily'  ,    ''    ,   ''     , ''
   cn_dir  =    'bdydta/'
   ln_full_vel = .false.
/

/home/ntm/Workspace/NEMO/nemo_v3_6_STABLE/DOC/Namelists/nambdy_dta2

Options are defined through the nambdy nambdy_index nambdy_dta nambdy_dta2 namelist variables. The BDY module is an alternative implementation of open boundary conditions for regional configurations. It implements the Flow Relaxation Scheme algorithm for temperature, salinity, velocities and ice fields, and the Flather radiation condition for the depth-mean transports. The specification of the location of the open boundary is completely flexible and allows for example the open boundary to follow an isobath or other irregular contour.

The BDY module was modelled on the OBC module and shares many features and a similar coding structure [Chanut, 2005].

The BDY module is completely rewritten at NEMO 3.4 and there is a new set of namelists. Boundary data files used with earlier versions of NEMO may need to be re-ordered to work with this version. See the section on the Input Boundary Data Files for details.

The namelists

It is possible to define more than one boundary “set” and apply different boundary conditions to each set. The number of boundary sets is defined by nb_bdy. Each boundary set may be defined as a set of straight line segments in a namelist (ln_coords_file=.false.) or read in from a file (ln_coords_file=.true.). If the set is defined in a namelist, then the namelists nambdy_index must be included separately, one for each set. If the set is defined by a file, then a “coordinates.bdy.nc” file must be provided. The coordinates.bdy file is analagous to the usual NEMO “coordinates.nc” file. In the example above, there are two boundary sets, the first of which is defined via a file and the second is defined in a namelist. For more details of the definition of the boundary geometry see section 8.4.4.

For each boundary set a boundary condition has to be chosen for the barotropic solution (“u2d”: sea-surface height and barotropic velocities), for the baroclinic velocities (“u3d”), and for the active tracers^8.1(“tra”). For each set of variables there is a choice of algorithm and a choice for the data, eg. for the active tracers the algorithm is set by nn_tra and the choice of data is set by nn_tra_dta.

The choice of algorithm is currently as follows:

0.

No boundary condition applied. So the solution will “see” the land points around the edge of the edge of the domain.

1.

Flow Relaxation Scheme (FRS) available for all variables.

2.

Flather radiation scheme for the barotropic variables. The Flather scheme is not compatible with the filtered free surface (dynspg_ts).

The main choice for the boundary data is to use initial conditions as boundary data (nn_tra_dta=0) or to use external data from a file (nn_tra_dta=1). For the barotropic solution there is also the option to use tidal harmonic forcing either by itself or in addition to other external data.

If external boundary data is required then the nambdy_dta namelist must be defined. One nambdy_dta namelist is required for each boundary set in the order in which the boundary sets are defined in nambdy. In the example given, two boundary sets have been defined and so there are two nambdy_dta namelists. The boundary data is read in using the fldread module, so the nambdy_dta namelist is in the format required for fldread. For each variable required, the filename, the frequency of the files and the frequency of the data in the files is given. Also whether or not time-interpolation is required and whether the data is climatological (time-cyclic) data. Note that on-the-fly spatial interpolation of boundary data is not available at this version.

In the example namelists given, two boundary sets are defined. The first set is defined via a file and applies FRS conditions to temperature and salinity and Flather conditions to the barotropic variables. External data is provided in daily files (from a large-scale model). Tidal harmonic forcing is also used. The second set is defined in a namelist. FRS conditions are applied on temperature and salinity and climatological data is read from external files.

The Flow Relaxation Scheme

The Flow Relaxation Scheme (FRS) [Engerdahl, 1995, Davies, 1976], applies a simple relaxation of the model fields to externally-specified values over a zone next to the edge of the model domain. Given a model prognostic variable $\Phi$

$$\Phi(d) = \alpha(d)\Phi_{e}(d) + (1-\alpha(d))\Phi_{m}(d)\;\;\;\;\; d=1,N$$ (8.5)

where $\Phi_{m}$ is the model solution and $\Phi_{e}$ is the specified external field, $d$ gives the discrete distance from the model boundary and $\alpha$ is a parameter that varies from $1$ at $d=1$ to a small value at $d=N$. It can be shown that this scheme is equivalent to adding a relaxation term to the prognostic equation for $\Phi$ of the form:

$$-\frac{1}{\tau}\left(\Phi - \Phi_{e}\right)$$ (8.6)

where the relaxation time scale $\tau$ is given by a function of $\alpha$ and the model time step $\Delta t$:

$$\tau = \frac{1-\alpha}{\alpha} \rdt$$ (8.7)

Thus the model solution is completely prescribed by the external conditions at the edge of the model domain and is relaxed towards the external conditions over the rest of the FRS zone. The application of a relaxation zone helps to prevent spurious reflection of outgoing signals from the model boundary.

The function $\alpha$ is specified as a $\tanh$ function:

$$\alpha(d) = 1 - \tanh\left(\frac{d-1}{2}\right), \quad d=1,N$$ (8.8)

The width of the FRS zone is specified in the namelist as nn_rimwidth. This is typically set to a value between 8 and 10.

The Flather radiation scheme

The Flather [1994] scheme is a radiation condition on the normal, depth-mean transport across the open boundary. It takes the form

$$U = U_{e} + \frac{c}{h}\left(\eta - \eta_{e}\right),$$ (8.9)

where $U$ is the depth-mean velocity normal to the boundary and $\eta$ is the sea surface height, both from the model. The subscript $e$ indicates the same fields from external sources. The speed of external gravity waves is given by $c = \sqrt{gh}$, and $h$ is the depth of the water column. The depth-mean normal velocity along the edge of the model domain is set equal to the external depth-mean normal velocity, plus a correction term that allows gravity waves generated internally to exit the model boundary. Note that the sea-surface height gradient in (8.9) is a spatial gradient across the model boundary, so that $\eta_{e}$ is defined on the $T$ points with $nbr=1$ and $\eta$ is defined on the $T$ points with $nbr=2$. $U$ and $U_{e}$ are defined on the $U$ or $V$ points with $nbr=1$, $i.e.$ between the two $T$ grid points.

Boundary geometry

Each open boundary set is defined as a list of points. The information is stored in the arrays $nbi$, $nbj$, and $nbr$ in the $idx\_bdy$ structure. The $nbi$ and $nbj$ arrays define the local $(i,j)$ indices of each point in the boundary zone and the $nbr$ array defines the discrete distance from the boundary with $nbr=1$ meaning that the point is next to the edge of the model domain and $nbr>1$ showing that the point is increasingly further away from the edge of the model domain. A set of $nbi$, $nbj$, and $nbr$ arrays is defined for each of the $T$, $U$ and $V$ grids. Figure 8.7 shows an example of an irregular boundary.

The boundary geometry for each set may be defined in a namelist nambdy_index or by reading in a “coordinates.bdy.nc” file. The nambdy_index namelist defines a series of straight-line segments for north, east, south and west boundaries. For the northern boundary, nbdysegn gives the number of segments, jpjnob gives the $j$ index for each segment and jpindt and jpinft give the start and end $i$ indices for each segment with similar for the other boundaries. These segments define a list of $T$ grid points along the outermost row of the boundary ( $nbr = 1$). The code deduces the $U$ and $V$ points and also the points for $nbr > 1$ if $nn\_rimwidth > 1$.

The boundary geometry may also be defined from a “coordinates.bdy.nc” file. Figure 8.8 gives an example of the header information from such a file. The file should contain the index arrays for each of the $T$, $U$ and $V$ grids. The arrays must be in order of increasing $nbr$. Note that the $nbi$, $nbj$ values in the file are global values and are converted to local values in the code. Typically this file will be used to generate external boundary data via interpolation and so will also contain the latitudes and longitudes of each point as shown. However, this is not necessary to run the model.

For some choices of irregular boundary the model domain may contain areas of ocean which are not part of the computational domain. For example if an open boundary is defined along an isobath, say at the shelf break, then the areas of ocean outside of this boundary will need to be masked out. This can be done by reading a mask file defined as cn_mask_file in the nam_bdy namelist. Only one mask file is used even if multiple boundary sets are defined.

Figure 8.7: Example of geometry of unstructured open boundary

Input boundary data files

The data files contain the data arrays in the order in which the points are defined in the $nbi$ and $nbj$ arrays. The data arrays are dimensioned on: a time dimension; $xb$ which is the index of the boundary data point in the horizontal; and $yb$ which is a degenerate dimension of 1 to enable the file to be read by the standard NEMO I/O routines. The 3D fields also have a depth dimension.

At Version 3.4 there are new restrictions on the order in which the boundary points are defined (and therefore restrictions on the order of the data in the file). In particular:

1. The data points must be in order of increasing $nbr$, ie. all the $nbr=1$ points, then all the $nbr=2$ points etc.
2. All the data for a particular boundary set must be in the same order. (Prior to 3.4 it was possible to define barotropic data in a different order to the data for tracers and baroclinic velocities).

These restrictions mean that data files used with previous versions of the model may not work with version 3.4. A fortran utility bdy_reorder exists in the TOOLS directory which will re-order the data in old BDY data files.

Figure 8.8: Example of the header for a coordinates.bdy.nc file

Volume correction

There is an option to force the total volume in the regional model to be constant, similar to the option in the OBC module. This is controlled by the nn_volctl parameter in the namelist. A value of nn_volctl = 0 indicates that this option is not used. If nn_volctl = 1 then a correction is applied to the normal velocities around the boundary at each timestep to ensure that the integrated volume flow through the boundary is zero. If nn_volctl = 2 then the calculation of the volume change on the timestep includes the change due to the freshwater flux across the surface and the correction velocity corrects for this as well.

If more than one boundary set is used then volume correction is applied to all boundaries at once.

Tidal harmonic forcing

!-----------------------------------------------------------------------
&nambdy_tide     ! tidal forcing at open boundaries
!-----------------------------------------------------------------------
   filtide          = 'bdydta/amm12_bdytide_'         !  file name root of tidal forcing files
   ln_bdytide_2ddta = .false.
   ln_bdytide_conj  = .false.
/

Options are defined through the nambdy_tide namelist variables. To be written....

Footnotes

... tracers^8.1

The BDY module does not deal with passive tracers at this version