Changeset 10530


Ignore:
Timestamp:
2019-01-16T12:18:17+01:00 (15 months ago)
Author:
mathiot
Message:

update BDY doc with contribution from Enda, Dave and James. fix ticket #2205

Location:
NEMO/trunk/doc
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • NEMO/trunk/doc/latex/NEMO/main/NEMO_manual.bib

    r10499 r10530  
    28072807} 
    28082808 
     2809@Article{Mathiot2017, 
     2810  AUTHOR =       {Mathiot, P. and Jenkins, A. and Harris, C. and Madec, G.}, 
     2811  TITLE =        {Explicit representation and parametrised impacts of under ice shelf seas in the ${z}^{\ast}$ coordinate ocean model NEMO 3.6}, 
     2812  JOURNAL =      {Geoscientific Model Development}, 
     2813  VOLUME =       {10}, 
     2814  YEAR =         {2017}, 
     2815  NUMBER =       {7}, 
     2816  PAGES =        {2849--2874}, 
     2817  URL =          {https://www.geosci-model-dev.net/10/2849/2017/}, 
     2818  DOI =          {10.5194/gmd-10-2849-2017} 
     2819} 
     2820 
    28092821@ARTICLE{McDougall1987, 
    28102822  author =       {T. J. McDougall}, 
  • NEMO/trunk/doc/latex/NEMO/subfiles/chap_LBC.tex

    r10481 r10530  
    391391 
    392392Options are defined through the \ngn{nambdy} \ngn{nambdy\_dta} namelist variables. 
    393 The BDY module is the core implementation of open boundary conditions for regional configurations. 
    394 It implements the Flow Relaxation Scheme algorithm for temperature, salinity, velocities and ice fields, and 
    395 the Flather radiation condition for the depth-mean transports. 
     393The BDY module is the core implementation of open boundary conditions for regional configurations on  
     394temperature, salinity, barotropic and baroclinic velocities, as well as ice concentration, ice and snow thicknesses). 
     395 
     396The BDY module was modelled on the OBC module (see NEMO 3.4) and shares many features and 
     397a similar coding structure \citep{Chanut2005}. 
    396398The specification of the location of the open boundary is completely flexible and 
    397399allows for example the open boundary to follow an isobath or other irregular contour.  
    398  
    399 The BDY module was modelled on the OBC module (see NEMO 3.4) and shares many features and 
    400 a similar coding structure \citep{Chanut2005}. 
    401  
    402 Boundary data files used with earlier versions of NEMO may need to be re-ordered to work with this version. 
     400Boundary data files used with versions of NEMO prior to Version 3.4 may need to be re-ordered to work with this version. 
    403401See the section on the Input Boundary Data Files for details. 
    404402 
     
    407405\label{subsec:BDY_namelist} 
    408406 
    409 The BDY module is activated by setting \np{ln\_bdy} to true. 
     407The BDY module is activated by setting \np{ln\_bdy}\forcode{ = .true.} . 
    410408It is possible to define more than one boundary ``set'' and apply different boundary conditions to each set. 
    411409The number of boundary sets is defined by \np{nb\_bdy}. 
    412410Each boundary set may be defined as a set of straight line segments in a namelist 
    413411(\np{ln\_coords\_file}\forcode{ = .false.}) or read in from a file (\np{ln\_coords\_file}\forcode{ = .true.}). 
    414 If the set is defined in a namelist, then the namelists nambdy\_index must be included separately, one for each set. 
     412If the set is defined in a namelist, then the namelists \ngn{nambdy\_index} must be included separately, one for each set. 
    415413If the set is defined by a file, then a ``\ifile{coordinates.bdy}'' file must be provided. 
    416414The coordinates.bdy file is analagous to the usual NEMO ``\ifile{coordinates}'' file. 
     
    420418 
    421419For each boundary set a boundary condition has to be chosen for the barotropic solution 
    422 (``u2d'':sea-surface height and barotropic velocities), for the baroclinic velocities (``u3d''), and 
    423 for the active tracers \footnote{The BDY module does not deal with passive tracers at this version} (``tra''). 
     420(``u2d'':sea-surface height and barotropic velocities), for the baroclinic velocities (``u3d''),  
     421for the active tracers \footnote{The BDY module does not deal with passive tracers at this version} (``tra''), and sea-ice (``ice''). 
    424422For each set of variables there is a choice of algorithm and a choice for the data, 
    425 eg. for the active tracers the algorithm is set by \np{nn\_tra} and the choice of data is set by \np{nn\_tra\_dta}.  
     423eg. for the active tracers the algorithm is set by \np{cn\_tra} and the choice of data is set by \np{nn\_tra\_dta}.\\  
    426424 
    427425The choice of algorithm is currently as follows: 
    428426 
    429 \begin{itemize} 
    430 \item[0.] No boundary condition applied. 
     427\begin{description} 
     428\item[\forcode{'none'}:] No boundary condition applied. 
    431429  So the solution will ``see'' the land points around the edge of the edge of the domain. 
    432 \item[1.] Flow Relaxation Scheme (FRS) available for all variables. 
    433 \item[2.] Flather radiation scheme for the barotropic variables. 
    434   The Flather scheme is not compatible with the filtered free surface 
    435   ({\it dynspg\_ts}).  
    436 \end{itemize} 
     430\item[\forcode{'specified'}:] Specified boundary condition applied (only available for baroclinic velocity and tracer variables). 
     431\item[\forcode{'neumann'}:] Value at the boundary are duplicated (No gradient). Only available for baroclinic velocity and tracer variables. 
     432\item[\forcode{'frs'}:] Flow Relaxation Scheme (FRS) available for all variables. 
     433\item[\forcode{'Orlanski'}:] Orlanski radiation scheme (fully oblique) for barotropic, baroclinic and tracer variables.  
     434\item[\forcode{'Orlanski_npo'}:] Orlanski radiation scheme for barotropic, baroclinic and tracer variables.  
     435\item[\forcode{'flather'}:] Flather radiation scheme for the barotropic variables only. 
     436\end{description} 
    437437 
    438438The main choice for the boundary data is to use initial conditions as boundary data 
    439439(\np{nn\_tra\_dta}\forcode{ = 0}) or to use external data from a file (\np{nn\_tra\_dta}\forcode{ = 1}). 
     440In case the 3d velocity data contain the total velocity (ie, baroclinic and barotropic velocity),  
     441the bdy code can derived baroclinic and barotropic velocities by setting \np{ln\_full\_vel}\forcode{ = .true. } 
    440442For the barotropic solution there is also the option to use tidal harmonic forcing either by 
    441 itself or in addition to other external data.  
    442  
    443 If external boundary data is required then the nambdy\_dta namelist must be defined. 
    444 One nambdy\_dta namelist is required for each boundary set in the order in which 
     443itself (\np{nn\_dyn2d\_dta}\forcode{ = 2}) or in addition to other external data (\np{nn\_dyn2d\_dta}\forcode{ = 3}).\\ 
     444Sea-ice salinity, temperature and age data at the boundary are constant and defined repectively by \np{rn\_ice\_sal}, \np{rn\_ice\_tem} and \np{rn\_ice\_age}.  
     445 
     446If external boundary data is required then the \ngn{nambdy\_dta} namelist must be defined. 
     447One \ngn{nambdy\_dta} namelist is required for each boundary set in the order in which 
    445448the boundary sets are defined in nambdy. 
    446 In the example given, two boundary sets have been defined and so there are two nambdy\_dta namelists. 
     449In the example given, two boundary sets have been defined. The first one is reading data file in the \ngn{nambdy\_dta} namelist shown above  
     450and the second one is using data from intial condition (no namelist bloc needed). 
    447451The boundary data is read in using the fldread module, 
    448 so the nambdy\_dta namelist is in the format required for fldread. 
     452so the \ngn{nambdy\_dta} namelist is in the format required for fldread. 
    449453For each variable required, the filename, the frequency of the files and 
    450454the frequency of the data in the files is given. 
    451 Also whether or not time-interpolation is required and whether the data is climatological (time-cyclic) data. 
    452 Note that on-the-fly spatial interpolation of boundary data is not available at this version.  
     455Also whether or not time-interpolation is required and whether the data is climatological (time-cyclic) data.\\ 
     456 
     457There is currently an option to vertically interpolate the open boundary data onto the native grid at run-time. 
     458If \np{nn\_bdy\_jpk} $< -1$, it is assumed that the lateral boundary data are already on the native grid.  
     459However, if \np{nn\_bdy\_jpk} is set to the number of vertical levels present in the boundary data,  
     460a bilinear interpolation onto the native grid will be triggered at runtime.  
     461For this to be successful the additional variables: $gdept$, $gdepu$, $gdepv$, $e3t$, $e3u$ and $e3v$, are required to be present in the lateral boundary files.  
     462These correspond to the depths and scale factors of the input data,  
     463the latter used to make any adjustment to the velocity fields due to differences in the total water depths between the two vertical grids.\\ 
    453464 
    454465In the example namelists given, two boundary sets are defined. 
    455466The first set is defined via a file and applies FRS conditions to temperature and salinity and 
    456 Flather conditions to the barotropic variables. 
     467Flather conditions to the barotropic variables. No condition specified for the baroclinic velocity and sea-ice. 
    457468External data is provided in daily files (from a large-scale model). 
    458469Tidal harmonic forcing is also used. 
    459470The second set is defined in a namelist. 
    460 FRS conditions are applied on temperature and salinity and climatological data is read from external files.  
     471FRS conditions are applied on temperature and salinity and climatological data is read from initial condition files.  
    461472 
    462473%---------------------------------------------- 
     
    521532 
    522533%---------------------------------------------- 
     534\subsection{Orlanski radiation scheme} 
     535\label{subsec:BDY_orlanski_scheme} 
     536 
     537The Orlanski scheme is based on the algorithm described by \citep{Marchesiello2001}, hereafter MMS. 
     538 
     539The adaptive Orlanski condition solves a wave plus relaxation equation at the boundary: 
     540\begin{equation} 
     541\frac{\partial\phi}{\partial t} + c_x \frac{\partial\phi}{\partial x} + c_y \frac{\partial\phi}{\partial y} = 
     542                                                -\frac{1}{\tau}(\phi - \phi^{ext}) 
     543\label{eq:wave_continuous} 
     544\end{equation} 
     545 
     546where $\phi$ is the model field, $x$ and $y$ refer to the normal and tangential directions to the boundary respectively, and the phase 
     547velocities are diagnosed from the model fields as: 
     548 
     549\begin{equation} \label{eq:cx} 
     550c_x = -\frac{\partial\phi}{\partial t}\frac{\partial\phi / \partial x}{(\partial\phi /\partial x)^2 + (\partial\phi /\partial y)^2} 
     551\end{equation} 
     552\begin{equation} 
     553\label{eq:cy} 
     554c_y = -\frac{\partial\phi}{\partial t}\frac{\partial\phi / \partial y}{(\partial\phi /\partial x)^2 + (\partial\phi /\partial y)^2} 
     555\end{equation} 
     556 
     557(As noted by MMS, this is a circular diagnosis of the phase speeds which only makes sense on a discrete grid). 
     558Equation (\autoref{eq:wave_continuous}) is defined adaptively depending on the sign of the phase velocity normal to the boundary $c_x$. 
     559For $c_x$ outward, we have 
     560 
     561\begin{equation} 
     562\tau = \tau_{out} 
     563\end{equation} 
     564 
     565For $c_x$ inward, the radiation equation is not applied: 
     566 
     567\begin{equation} 
     568\tau = \tau_{in}\,\,\,;\,\,\, c_x = c_y = 0 
     569\label{eq:tau_in} 
     570\end{equation} 
     571 
     572Generally the relaxation time scale at inward propagation points \np{(rn\_time\_dmp}) is set much shorter than the time scale at outward propagation 
     573points (\np{rn\_time\_dmp\_out}) so that the solution is constrained more strongly by the external data at inward propagation points. 
     574See \autoref{subsec:BDY_relaxation} for detailed on the spatial shape of the scaling.\\  
     575The ``normal propagation of oblique radiation'' or NPO approximation (called \forcode{'orlanski_npo'}) involves assuming  
     576that $c_y$ is zero in equation (\autoref{eq:wave_continuous}), but including 
     577this term in the denominator of equation (\autoref{eq:cx}). Both versions of the scheme are options in BDY. Equations 
     578(\autoref{eq:wave_continuous}) - (\autoref{eq:tau_in}) correspond to equations (13) - (15) and (2) - (3) in MMS.\\ 
     579 
     580%---------------------------------------------- 
     581\subsection{Relaxation at the boundary} 
     582\label{subsec:BDY_relaxation} 
     583 
     584In addition to a specific boundary condition specified as \np{cn\_tra} and \np{cn\_dyn3d}, relaxation on baroclinic velocities and tracers variables are available.  
     585It is control by the namelist parameter \np{ln\_tra\_dmp} and \np{ln\_dyn3d\_dmp} for each boundary set. 
     586 
     587The relaxation time scale value (\np{rn\_time\_dmp} and \np{rn\_time\_dmp\_out}, $\tau$) are defined at the boundaries itself.  
     588This time scale ($\alpha$) is weighted by the distance ($d$) from the boundary over \np{nn\_rimwidth} cells ($N$): 
     589 
     590\[ 
     591  \alpha = \frac{1}{\tau}(\frac{N+1-d}{N})^2,       \quad d=1,N 
     592\] 
     593 
     594The same scaling is applied in the Orlanski damping.  
     595 
     596%---------------------------------------------- 
    523597\subsection{Boundary geometry} 
    524598\label{subsec:BDY_geometry} 
     
    536610by reading in a ``\ifile{coordinates.bdy}'' file. 
    537611The nambdy\_index namelist defines a series of straight-line segments for north, east, south and west boundaries. 
     612One nambdy\_index namelist bloc is needed for each boundary condition defined by indexes.  
    538613For the northern boundary, \np{nbdysegn} gives the number of segments, 
    539614\np{jpjnob} gives the $j$ index for each segment and \np{jpindt} and 
    540615\np{jpinft} give the start and end $i$ indices for each segment with similar for the other boundaries. 
    541616These segments define a list of $T$ grid points along the outermost row of the boundary ($nbr\,=\, 1$). 
    542 The code deduces the $U$ and $V$ points and also the points for $nbr\,>\, 1$ if $nn\_rimwidth\,>\,1$. 
     617The code deduces the $U$ and $V$ points and also the points for $nbr\,>\, 1$ if \np{nn\_rimwidth}\forcode{ > 1}. 
    543618 
    544619The boundary geometry may also be defined from a ``\ifile{coordinates.bdy}'' file. 
     
    581656The 3D fields also have a depth dimension.  
    582657 
    583 At Version 3.4 there are new restrictions on the order in which the boundary points are defined 
     658From Version 3.4 there are new restrictions on the order in which the boundary points are defined 
    584659(and therefore restrictions on the order of the data in the file). 
    585660In particular: 
     
    593668\end{enumerate} 
    594669 
    595 These restrictions mean that data files used with previous versions of the model may not work with version 3.4. 
    596 A\fortran utility {\it bdy\_reorder} exists in the TOOLS directory which 
    597 will re-order the data in old BDY data files.  
     670These restrictions mean that data files used with versions of the 
     671model prior to Version 3.4 may not work with Version 3.4 onwards. 
     672A \fortran utility {\it bdy\_reorder} exists in the TOOLS directory which 
     673will re-order the data in old BDY data files. 
    598674 
    599675%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     
    626702applied to all boundaries at once. 
    627703 
    628 \newpage 
    629704%---------------------------------------------- 
    630705\subsection{Tidal harmonic forcing} 
     
    636711%----------------------------------------------------------------------------------------------- 
    637712 
    638 Options are defined through the  \ngn{nambdy\_tide} namelist variables. 
    639  To be written.... 
     713Options are defined through the \ngn{nambdy\_tide} namelist variables  
     714for reading in the complex harmonic amplitudes of elevation (ssh) and barotropic velocity (u,v).  
     715 
     716The tidal harmonic data can be specified in 2 ways.\\ 
     717First it can be specified on a 2D grid covering the entire model domain in which case the user should set \np{ln\_bdytide\_2ddta }\forcode{ = .true.}.  
     718In this case the model assumes that the real and imaginary parts are split. 
     719The variable naming convention is \textit{constituent\_name\_z1} for real SSH and \textit{constituent\_name\_z2} for imaginary SSH.  
     720The available \textit{constituent\_names} in NEMO are defined in \rou{SBC/tide.h90} 
     721Likewise for $u$ and $v$ data. File name is assumed to be \np{filtide}\ifile{\_grid\_T} for the elevation component  
     722and \np{filtide}\ifile{\_grid\_U} for the u barotropic velocity and \np{filtide}\ifile{\_grid\_V} for the v barotropic velocity.\\  
     723Otherwise, the tidal data must be specified along bdy segments.  
     724In this case each constituent has its own file name and the real part is assumed to be z1 and the imaginary part z2 for SSH.  
     725Similarly u1, u2 and v1, v2 for velocities. Input file name convention (for elevation of the M2 tidal component) is \np{filtide}\ifile{M2\_grid\_T}.  
     726Similar logic applies for other components and u and v barotropic velocities.\\ 
     727 
     728The data may also be in complex conjugate form. If that is the case then the user should set \np{ln\_bdytide\_conj}\forcode{ = .true. }  
     729so the model correctly interprets the data. The default case assumes it is not in complex conjugate form.  
     730 
     731Note the barotropic velocities are assumed to be on the model native grid and must be rotated as appropriate from the source grid upon which they are extracted from.  
     732To do so convert to U, V amplitude and phase into tidal ellipses. Add the grid rotation to ellipse inclination and convert back. Be careful about conventions  
     733of direction of rotation, e.g. anticlockwise or clockwise.  
    640734 
    641735\biblio 
  • NEMO/trunk/doc/namelists/nambdy

    r10445 r10530  
    33!----------------------------------------------------------------------- 
    44   ln_bdy         = .false.   !  Use unstructured open boundaries 
    5    nb_bdy         = 0         !  number of open boundary sets 
    6    ln_coords_file = .true.    !  =T : read bdy coordinates from file 
     5   nb_bdy         = 2         !  number of open boundary sets 
     6   ln_coords_file = .true. , .false.    !  =T : read bdy coordinates from file 
    77      cn_coords_file = 'coordinates.bdy.nc'  !  bdy coordinates files 
    88   ln_mask_file   = .false.   !  =T : read mask from file 
    9       cn_mask_file = ''        !  name of mask file (if ln_mask_file=.TRUE.) 
    10    cn_dyn2d    = 'none'       ! 
    11    nn_dyn2d_dta   =  0        !  = 0, bdy data are equal to the initial state 
     9      cn_mask_file = ''       !  name of mask file (if ln_mask_file=.TRUE.) 
     10   cn_dyn2d    = 'flather', 'none'       ! 
     11   nn_dyn2d_dta   =  3 , 0    !  = 0, bdy data are equal to the initial state 
    1212      !                       !  = 1, bdy data are read in 'bdydata   .nc' files 
    1313      !                       !  = 2, use tidal harmonic forcing data from files 
    1414      !                       !  = 3, use external data AND tidal harmonic forcing 
    15    cn_dyn3d      =  'none'    ! 
    16    nn_dyn3d_dta  =  0         !  = 0, bdy data are equal to the initial state 
     15   cn_dyn3d      =  'none' , 'none' 
     16   nn_dyn3d_dta  =  0 , 0     !  = 0, bdy data are equal to the initial state 
    1717   !                          !  = 1, bdy data are read in 'bdydata   .nc' files 
    18    cn_tra        =  'none'    ! 
    19    nn_tra_dta    =  0         !  = 0, bdy data are equal to the initial state 
     18   cn_tra        =  'frs' , 'frs' 
     19   nn_tra_dta    =  1 , 0     !  = 0, bdy data are equal to the initial state 
    2020   !                          !  = 1, bdy data are read in 'bdydata   .nc' files 
    21    cn_ice        =  'none'    ! 
    22    nn_ice_dta    =  0         !  = 0, bdy data are equal to the initial state 
     21   cn_ice        =  'none' , 'none' 
     22   nn_ice_dta    =  0, 0      !  = 0, bdy data are equal to the initial state 
    2323   !                          !  = 1, bdy data are read in 'bdydata   .nc' files 
    24    rn_ice_tem    = 270.      !  si3 only: arbitrary temperature of incoming sea ice 
    25    rn_ice_sal    = 10.       !  si3 only:      --   salinity           -- 
    26    rn_ice_age    = 30.       !  si3 only:      --   age                -- 
     24   rn_ice_tem    = 270., 270. !  si3 only: arbitrary temperature of incoming sea ice 
     25   rn_ice_sal    = 10. ,  10. !  si3 only:      --   salinity           -- 
     26   rn_ice_age    = 30. ,  30. !  si3 only:      --   age                -- 
    2727   ! 
    28    ln_tra_dmp    =.false.     !  open boudaries conditions for tracers 
    29    ln_dyn3d_dmp  =.false.     !  open boundary condition for baroclinic velocities 
    30    rn_time_dmp   =  1.        !  Damping time scale in days 
    31    rn_time_dmp_out = 1.        !  Outflow damping time scale 
    32    nn_rimwidth   = 10         !  width of the relaxation zone 
     28   ln_tra_dmp    =.false., .false.  !  open boudaries conditions for tracers 
     29   ln_dyn3d_dmp  =.false., .false.  !  open boundary condition for baroclinic velocities 
     30   rn_time_dmp   =  1., 1.    !  Damping time scale in days 
     31   rn_time_dmp_out = 1., 1.    !  Outflow damping time scale 
     32   nn_rimwidth   = 10, 5      !  width of the relaxation zone 
    3333   ln_vol        = .false.    !  total volume correction (see nn_volctl parameter) 
    3434   nn_volctl     =  1         !  = 0, the total water flux across open boundaries is zero 
    3535   nb_jpk_bdy    = -1         ! number of levels in the bdy data (set < 0 if consistent with planned run) 
    3636/ 
     37!----------------------------------------------------------------------- 
     38&nambdy_index     ! index definition of bdy 
     39!----------------------------------------------------------------------- 
     40    ctypebdy = 'S' 
     41    nbdyind  =  2 
     42    nbdybeg  = 2 
     43    nbdyend  = 273 
     44/ 
Note: See TracChangeset for help on using the changeset viewer.