Changeset 3227 for trunk/DOC/TexFiles/Chapters/Chap_LBC.tex

Timestamp:

2011-12-20T11:28:43+01:00 (12 years ago)

Author:

davestorkey

Message:

Update BDY documentation.

File:

• trunk/DOC/TexFiles/Chapters/Chap_LBC.tex (modified) (9 diffs)

trunk/DOC/TexFiles/Chapters/Chap_LBC.tex

@@ -742 +742 @@
 
 %-----------------------------------------nambdy--------------------------------------------
-%-    cn_mask    =  ''                        !  name of mask file (if ln_bdy_mask=.TRUE.)
-%-    cn_dta_frs_T  = 'bdydata_grid_T.nc'     !  name of data file (T-points)
-%-    cn_dta_frs_U  = 'bdydata_grid_U.nc'     !  name of data file (U-points)
-%-    cn_dta_frs_V  = 'bdydata_grid_V.nc'     !  name of data file (V-points)
-%-    cn_dta_fla_T  = 'bdydata_bt_grid_T.nc'  !  name of data file for Flather condition (T-points)
-%-    cn_dta_fla_U  = 'bdydata_bt_grid_U.nc'  !  name of data file for Flather condition (U-points)
-%-    cn_dta_fla_V  = 'bdydata_bt_grid_V.nc'  !  name of data file for Flather condition (V-points)
-%-    ln_clim    = .false.                    !  contain 1 (T) or 12 (F) time dumps and be cyclic
-%-    ln_vol     = .true.                     !  total volume correction (see volbdy parameter)
-%-    ln_mask    = .false.                    !  boundary mask from filbdy_mask (T) or boundaries are on edges of domain (F)
-%-    ln_tides   = .true.                     !  Apply tidal harmonic forcing with Flather condition
-%-    ln_dyn_fla = .true.                     !  Apply Flather condition to velocities
-%-    ln_tra_frs = .false.                    !  Apply FRS condition to temperature and salinity
-%-    ln_dyn_frs = .false.                    !  Apply FRS condition to velocities
-%-    nn_rimwidth    =  9                     !  width of the relaxation zone
-%-    nn_dtactl      =  1                     !  = 0, bdy data are equal to the initial state
-%-                                            !  = 1, bdy data are read in 'bdydata   .nc' files
-%-    nn_volctl      =  0                     !  = 0, the total water flux across open boundaries is zero
-%-                                            !  = 1, the total volume of the system is conserved
 \namdisplay{nambdy} 
+%-----------------------------------------------------------------------------------------------
+%-----------------------------------------nambdy_index--------------------------------------------
+\namdisplay{nambdy_index} 
+%-----------------------------------------------------------------------------------------------
+%-----------------------------------------nambdy_dta--------------------------------------------
+\namdisplay{nambdy_dta} 
+%-----------------------------------------------------------------------------------------------
+%-----------------------------------------nambdy_dta--------------------------------------------
+\namdisplay{nambdy_dta2} 
 %-----------------------------------------------------------------------------------------------
 
@@ -774 +764 @@
 The BDY module was modelled on the OBC module and shares many features
 and a similar coding structure \citep{Chanut2005}.
+
+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.
+
+%----------------------------------------------
+\subsection{The namelists}
+\label{BDY_namelist}
+
+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 \np{nb\_bdy}.  Each boundary set may be defined
+as a set of straight line segments in a namelist
+(\np{ln\_coords\_file}=.false.) or read in from a file
+(\np{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
+\ref{BDY_geometry}.
+
+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\footnote{The BDY
+  module does not deal with passive tracers at this version}
+(``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 \np{nn\_tra} and the choice of data is set by
+\np{nn\_tra\_dta}. 
+
+The choice of algorithm is currently as follows:
+
+\mbox{}
+
+\begin{itemize}
+\item[0.] No boundary condition applied. So the solution will ``see''
+  the land points around the edge of the edge of the domain.
+\item[1.] Flow Relaxation Scheme (FRS) available for all variables. 
+\item[2.] Flather radiation scheme for the barotropic variables. The
+  Flather scheme is not compatible with the filtered free surface
+  ({\it dynspg\_ts}). 
+\end{itemize}
+
+\mbox{}
+
+The main choice for the boundary data is
+to use initial conditions as boundary data (\np{nn\_tra\_dta}=0) or to
+use external data from a file (\np{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. 
 
 %----------------------------------------------
@@ -832 +899 @@
 Note that the sea-surface height gradient in \eqref{Eq_bdy_fla1}
 is a spatial gradient across the model boundary, so that $\eta_{e}$ is
-defined on the $T$ points with $nbrdta=1$ and $\eta$ is defined on the
-$T$ points with $nbrdta=2$. $U$ and $U_{e}$ are defined on the $U$ or
-$V$ points with $nbrdta=1$, $i.e.$ between the two $T$ grid points.
-
-%----------------------------------------------
-\subsection{Choice of schemes}
-\label{BDY_choice_of_schemes}
-
-The Flow Relaxation Scheme may be applied separately to the
-temperature and salinity (\np{ln\_tra\_frs} = true) and
-the velocity fields (\np{ln\_dyn\_frs} = true). Flather
-radiation conditions may be applied using externally defined
-barotropic velocities and sea-surface height (\np{ln\_dyn\_fla} = true) 
-or using tidal harmonics fields (\np{ln\_tides} = true) 
-or both. FRS and Flather conditions may be applied simultaneously. 
-A typical configuration where all possible conditions might be used is a tidal, 
-shelf-seas model, where the barotropic boundary conditions are fixed 
-with the Flather scheme using tidal harmonics and possibly output 
-from a large-scale model, and FRS conditions are applied to the tracers 
-and baroclinic velocity fields, using fields from a large-scale model.
-
-Note that FRS conditions will work with the filtered
-(\key{dynspg\_flt}) or time-split (\key{dynspg\_ts}) solutions for the
-surface pressure gradient. The Flather condition will only work for
-the time-split solution (\key{dynspg\_ts}). FRS conditions are applied
-at the end of the main model time step. Flather conditions are applied
-during the barotropic subcycle in the time-split solution. 
+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.
+
+%% %----------------------------------------------
+%% \subsection{Compatibility of schemes}
+%% \label{BDY_choice_of_schemes}
+%% 
+%% The Flow Relaxation Scheme may be applied separately to the
+%% temperature and salinity (\np{ln\_tra\_frs} = true) and
+%% the velocity fields (\np{ln\_dyn\_frs} = true). Flather
+%% radiation conditions may be applied using externally defined
+%% barotropic velocities and sea-surface height (\np{ln\_dyn\_fla} = true) 
+%% or using tidal harmonics fields (\np{ln\_tides} = true) 
+%% or both. FRS and Flather conditions may be applied simultaneously. 
+%% A typical configuration where all possible conditions might be used is a tidal, 
+%% shelf-seas model, where the barotropic boundary conditions are fixed 
+%% with the Flather scheme using tidal harmonics and possibly output 
+%% from a large-scale model, and FRS conditions are applied to the tracers 
+%% and baroclinic velocity fields, using fields from a large-scale model.
+%% 
+%% Note that FRS conditions will work with the filtered
+%% (\key{dynspg\_flt}) or time-split (\key{dynspg\_ts}) solutions for the
+%% surface pressure gradient. The Flather condition will only work for
+%% the time-split solution (\key{dynspg\_ts}). FRS conditions are applied
+%% at the end of the main model time step. Flather conditions are applied
+%% during the barotropic subcycle in the time-split solution. 
 
 %----------------------------------------------
@@ -864 +931 @@
 \label{BDY_geometry}
 
-The definition of the open boundary is completely flexible. An example
-is shown in Fig.~\ref{Fig_LBC_bdy_geom}. The boundary zone is
-defined by a series of index arrays read in from the input boundary
-data files: $nbidta$, $nbjdta$, and $nbrdta$. The first two of these
-define the global $(i,j)$ indices of each point in the boundary zone
-and the $nbrdta$ array defines the discrete distance from the boundary
-with $nbrdta=1$ meaning that the point is next to the edge of the
-model domain and $nbrdta>1$ showing that the point is increasingly
-further away from the edge of the model domain. These arrays are
-defined separately for each of the $T$, $U$ and $V$ grids, but the
-relationship between the points is assumed to be as in Fig.
-\ref{Fig_LBC_bdy_geom} with the $T$ points forming the outermost row
-of the boundary and the first row of velocities normal to the boundary
-being inside the first row of $T$ points. The order in which the
-points are defined is unimportant. 
+%% The definition of the open boundary is completely flexible. An example
+%% is shown in Fig.~\ref{Fig_LBC_bdy_geom}. The boundary zone is
+%% defined by a series of index arrays read in from the input boundary
+%% data files: $nbidta$, $nbjdta$, and $nbrdta$. The first two of these
+%% define the global $(i,j)$ indices of each point in the boundary zone
+%% and the $nbrdta$ array defines the discrete distance from the boundary
+%% with $nbrdta=1$ meaning that the point is next to the edge of the
+%% model domain and $nbrdta>1$ showing that the point is increasingly
+%% further away from the edge of the model domain. These arrays are
+%% defined separately for each of the $T$, $U$ and $V$ grids, but the
+%% relationship between the points is assumed to be as in Fig.
+%% \ref{Fig_LBC_bdy_geom} with the $T$ points forming the outermost row
+%% of the boundary and the first row of velocities normal to the boundary
+%% being inside the first row of $T$ points. The order in which the
+%% points are defined is unimportant. 
+
+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 \ref{Fig_LBC_bdy_geom} 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,
+\np{nbdysegn} gives the number of segments, \np{jpjnob} gives the $j$
+index for each segment and \np{jpindt} and \np{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 \ref{Fig_LBC_nc_header}
+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 \np{cn\_mask\_file} in the nam\_bdy namelist. Only one mask file is
+used even if multiple boundary sets are defined.
 
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
@@ -892 +1002 @@
 \label{BDY_data}
 
-The input data files for the FRS conditions are defined in the
-namelist as \np{cn\_dta\_frs\_T}, \np{cn\_dta\_frs\_U}, 
-\np{cn\_dta\_frs\_V}. The input data files for the Flather conditions
-are defined in the namelist as \np{cn\_dta\_fla\_T}, 
-\np{cn\_dta\_fla\_U}, \np{cn\_dta\_fla\_V}. 
-
-The netcdf header of a typical input data file is shown in Fig.~\ref{Fig_LBC_nc_header}. 
-The file contains the index arrays which define the boundary geometry 
-as noted above and the data arrays for each field.  
-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.
-
-If \np{ln\_clim} is set to \textit{false}, the model expects the
-units of the time axis to have the form shown in
-Fig.~\ref{Fig_LBC_nc_header}, $i.e.$ {\it ``seconds since yyyy-mm-dd
-hh:mm:ss''} The fields are then linearly interpolated to the model
-time at each timestep. Note that for this option, the time axis of the
-input files must completely span the time period of the model
-integration. If \np{ln\_clim} is set to \textit{true} (climatological
-boundary forcing), the model will expect either a single set of annual
-mean fields (constant boundary forcing) or 12 sets of monthly mean
-fields in the input files.
-
-As in the OBC module there is an option to use initial conditions as
-boundary conditions. This is chosen by setting
-\np{nn\_dtactl}~=~0. However, since the model defines the boundary
-geometry by reading the boundary index arrays from the input files,
-it is still necessary to provide a set of input files in this
-case. They need only contain the boundary index arrays, $nbidta$,
-\textit{nbjdta}, \textit{nbrdta}.
+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:
+
+\mbox{}
+
+\begin{enumerate}
+\item The data points must be in order of increasing $nbr$, ie. all
+  the $nbr=1$ points, then all the $nbr=2$ points etc.
+\item 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). 
+\end{enumerate}
+
+\mbox{}
+
+These restrictions mean that data files used with previous versions of
+the model may not work with version 3.4. A fortran utility
+{\it bdy\_reorder} exists in the TOOLS directory which will re-order the
+data in old BDY data files. 
 
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
@@ -930 +1035 @@
 \includegraphics[width=1.0\textwidth]{./TexFiles/Figures/Fig_LBC_nc_header.pdf}
 \caption {     \label{Fig_LBC_nc_header} 
-Example of header of netcdf input data file for BDY}
+Example of the header for a coordinates.bdy.nc file}
 \end{center}   \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
@@ -940 +1045 @@
 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 \np{nn\_volctl} 
-parameter in the namelist. A value of\np{nn\_volctl}~=~0 indicates that this option is not used. 
+parameter in the namelist. A value of \np{nn\_volctl}~=~0 indicates that this option is not used. 
 If  \np{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 
@@ -947 +1052 @@
 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.
 
 %----------------------------------------------
@@ -952 +1059 @@
 \label{BDY_tides}
 
+%-----------------------------------------nambdy_tide--------------------------------------------
+\namdisplay{nambdy_tide} 
+%-----------------------------------------------------------------------------------------------
+
 To be written....