Changeset 11422 for NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_misc.tex

Timestamp:

2019-08-08T15:40:47+02:00 (5 years ago)

Author:

jchanut

Message:

#1791, merge with trunk

Location:

NEMO/branches/2019/fix_vvl_ticket1791/doc

Files:

• . (modified) (1 prop)
• latex (modified) (1 prop)
• latex/NEMO (modified) (1 prop)
• latex/NEMO/subfiles/chap_misc.tex (modified) (11 diffs)

NEMO/branches/2019/fix_vvl_ticket1791/doc/latex

@@ -1 @@
-*.aux
-*.bbl
-*.blg
-*.dvi
-*.fdb*
-*.fls
-*.idx
-*.ilg
-*.ind
-*.log
-*.maf
-*.mtc*
-*.out
-*.pdf
-*.toc
-_minted-*
+figures

@@ -1 @@
-*.aux
-*.bbl
-*.blg
-*.dvi
-*.fdb*
-*.fls
-*.idx
-*.ilg
-*.ind
-*.log
-*.maf
-*.mtc*
-*.out
-*.pdf
-*.toc
-_minted-*
+figures

NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_misc.tex

@@ -30 +30 @@
 are much narrow than even a single ocean grid-point.
 
-We describe briefly here the three methods that can be used in \NEMO to handle such improperly resolved straits.
-The first two consist of opening the strait by hand while ensuring that the mass exchanges through
-the strait are not too large by either artificially reducing the surface of the strait grid-cells or,
-locally increasing the lateral friction.
-In the third one, the strait is closed but exchanges of mass, heat and salt across the land are allowed.
-Note that such modifications are so specific to a given configuration that no attempt has been made to
-set them in a generic way.
-However, examples of how they can be set up is given in the ORCA 2\deg and 0.5\deg configurations.
-For example, for details of implementation in ORCA2, search: \texttt{IF( cp\_cfg == "orca" .AND. jp\_cfg == 2 )}
+We describe briefly here the two methods that can be used in \NEMO to handle such
+improperly resolved straits. The methods consist of opening the strait while ensuring
+that the mass exchanges through the strait are not too large by either artificially
+reducing the cross-sectional area of the strait grid-cells or, locally increasing the
+lateral friction.
 
 % -------------------------------------------------------------------------------------------------------------
@@ -46 +42 @@
 \label{subsec:MISC_strait_hand}
 
-$\bullet$ reduced scale factor in the cross-strait direction to a value in better agreement with
-the true mean width of the strait (\autoref{fig:MISC_strait_hand}).
-This technique is sometime called "partially open face" or "partially closed cells".
-The key issue here is only to reduce the faces of $T$-cell
-(\ie change the value of the horizontal scale factors at $u$- or $v$-point) but not the volume of the $T$-cell.
-Indeed, reducing the volume of strait $T$-cell can easily produce a numerical instability at
-that grid point that would require a reduction of the model time step.
-The changes associated with strait management are done in \mdl{domhgr},
-just after the definition or reading of the horizontal scale factors. 
-
-$\bullet$ increase of the viscous boundary layer thickness by local increase of the fmask value at the coast
-(\autoref{fig:MISC_strait_hand}).
-This is done in \mdl{dommsk} together with the setting of the coastal value of fmask (see  \autoref{sec:LBC_coast}).
+The first method involves reducing the scale factor in the cross-strait direction to a
+value in better agreement with the true mean width of the strait
+(\autoref{fig:MISC_strait_hand}).  This technique is sometime called "partially open face"
+or "partially closed cells".  The key issue here is only to reduce the faces of $T$-cell
+(\ie change the value of the horizontal scale factors at $u$- or $v$-point) but not the
+volume of the $T$-cell.  Indeed, reducing the volume of strait $T$-cell can easily produce
+a numerical instability at that grid point which would require a reduction of the model
+time step.  Thus to instigate a local change in the width of a Strait requires two steps:
+
+\begin{itemize}
+
+\item Add \texttt{e1e2u} and \texttt{e1e2v} arrays to the \np{cn\_domcfg} file. These 2D
+arrays should contain the products of the unaltered values of: $\texttt{e1u}*\texttt{e2u}$
+and $\texttt{e1u}*\texttt{e2v}$ respectively. That is the original surface areas of $u$-
+and $v$- cells respectively.  These areas are usually defined by the corresponding product
+within the \NEMO code but the presence of \texttt{e1e2u} and \texttt{e1e2v} in the
+\np{cn\_domcfg} file will suppress this calculation and use the supplied fields instead.
+If the model domain is provided by user-supplied code in \mdl{usrdef\_hgr}, then this
+routine should also return \texttt{e1e2u} and \texttt{e1e2v} and set the integer return
+argument \texttt{ie1e2u\_v} to a non-zero value. Values other than 0 for this argument
+will suppress the calculation of the areas.
+
+\item Change values of \texttt{e2u} or \texttt{e1v} (either in the \np{cn\_domcfg} file or
+via code in  \mdl{usrdef\_hgr}), whereever a Strait reduction is required. The choice of
+whether to alter \texttt{e2u} or \texttt{e1v} depends. respectively,  on whether the
+Strait in question is North-South orientated (\eg Gibraltar) or East-West orientated (\eg
+Lombok).
+
+\end{itemize}
+
+
+The second method is to increase the viscous boundary layer thickness by a local increase
+of the fmask value at the coast. This method can also be effective in wider passages.  The
+concept is illustarted in the second part of  \autoref{fig:MISC_strait_hand} and changes
+to specific locations can be coded in \mdl{usrdef\_fmask}. The \forcode{usr_def_fmask}
+routine is always called after \texttt{fmask} has been defined according to the choice of
+lateral boundary condition as discussed in \autoref{sec:LBC_coast}. The default version of
+\mdl{usrdef\_fmask} contains settings specific to ORCA2 and ORCA1 configurations. These are
+meant as examples only; it is up to the user to verify settings and provide alternatives
+for their own configurations. The default \forcode{usr_def_fmask} makes no changes to
+\texttt{fmask} for any other configuration.
 
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!tbp]
   \begin{center}
-    \includegraphics[width=0.80\textwidth]{Fig_Gibraltar}
-    \includegraphics[width=0.80\textwidth]{Fig_Gibraltar2}
+    \includegraphics[width=\textwidth]{Fig_Gibraltar}
+    \includegraphics[width=\textwidth]{Fig_Gibraltar2}
     \caption{
       \protect\label{fig:MISC_strait_hand}
@@ -84 +108 @@
 \begin{figure}[!tbp]
   \begin{center}
-    \includegraphics[width=1.0\textwidth]{Fig_closea_mask_example}
+    \includegraphics[width=\textwidth]{Fig_closea_mask_example}
     \caption{
       \protect\label{fig:closea_mask_example}
@@ -102 +126 @@
 % Closed seas
 % ================================================================
-\section{Closed seas (\protect\mdl{closea})}
+\section[Closed seas (\textit{closea.F90})]
+{Closed seas (\protect\mdl{closea})}
 \label{sec:MISC_closea}
 
@@ -122 +147 @@
 
 \begin{enumerate}
-\item{{\bf No ``closea\_mask'' field is included in domain configuration
+\item{{\bfseries No ``closea\_mask'' field is included in domain configuration
   file.} In this case the closea module does nothing.}
 
-\item{{\bf A field called closea\_mask is included in the domain
+\item{{\bfseries A field called closea\_mask is included in the domain
 configuration file and ln\_closea=.false. in namelist namcfg.} In this
 case the inland seas defined by the closea\_mask field are filled in
@@ -131 +156 @@
 closea\_mask that is nonzero is set to be a land point.}
 
-\item{{\bf A field called closea\_mask is included in the domain
+\item{{\bfseries A field called closea\_mask is included in the domain
 configuration file and ln\_closea=.true. in namelist namcfg.} Each
 inland sea or group of inland seas is set to a positive integer value
@@ -140 +165 @@
 closea\_mask is zero).}
 
-\item{{\bf Fields called closea\_mask and closea\_mask\_rnf are
+\item{{\bfseries Fields called closea\_mask and closea\_mask\_rnf are
 included in the domain configuration file and ln\_closea=.true. in
 namelist namcfg.} This option works as for option 3, except that if
@@ -154 +179 @@
 ocean.}
 
-\item{{\bf Fields called closea\_mask and closea\_mask\_emp are
+\item{{\bfseries Fields called closea\_mask and closea\_mask\_emp are
 included in the domain configuration file and ln\_closea=.true. in
 namelist namcfg.} This option works the same as option 4 except that
@@ -174 +199 @@
 \subsection{Simple subsetting of input files via NetCDF attributes}
 
-The extended grids for use with the under-shelf ice cavities will result in redundant rows around Antarctica if
-the ice cavities are not active.
-A simple mechanism for subsetting input files associated with the extended domains has been implemented to
-avoid the need to maintain different sets of input fields for use with or without active ice cavities.
-The existing 'zoom' options are overly complex for this task and marked for deletion anyway.
-This alternative subsetting operates for the j-direction only and works by optionally looking for and
-using a global file attribute (named: \np{open\_ocean\_jstart}) to determine the starting j-row for input.
-The use of this option is best explained with an example:
-consider an ORCA1 configuration using the extended grid bathymetry and coordinate files:
-\vspace{-10pt}
-\ifile{eORCA1\_bathymetry\_v2}
-\ifile{eORCA1\_coordinates}
-\noindent These files define a horizontal domain of 362x332.
-Assuming the first row with open ocean wet points in the non-isf bathymetry for this set is row 42
-(\fortran indexing) then the formally correct setting for \np{open\_ocean\_jstart} is 41.
-Using this value as the first row to be read will result in a 362x292 domain which is the same size as
-the original ORCA1 domain.
-Thus the extended coordinates and bathymetry files can be used with all the original input files for ORCA1 if
-the ice cavities are not active (\np{ln\_isfcav = .false.}).
-Full instructions for achieving this are:
-
-\noindent Add the new attribute to any input files requiring a j-row offset, i.e:
-\vspace{-10pt}
+The extended grids for use with the under-shelf ice cavities will result in redundant rows
+around Antarctica if the ice cavities are not active.  A simple mechanism for subsetting
+input files associated with the extended domains has been implemented to avoid the need to
+maintain different sets of input fields for use with or without active ice cavities.  This
+subsetting operates for the j-direction only and works by optionally looking for and using
+a global file attribute (named: \np{open\_ocean\_jstart}) to determine the starting j-row
+for input.  The use of this option is best explained with an example: 
+\medskip
+
+\noindent Consider an ORCA1
+configuration using the extended grid domain configuration file: \ifile{eORCA1\_domcfg.nc}
+This file define a horizontal domain of 362x332.  The first row with
+open ocean wet points in the non-isf bathymetry for this set is row 42 (\fortran indexing)
+then the formally correct setting for \np{open\_ocean\_jstart} is 41.  Using this value as
+the first row to be read will result in a 362x292 domain which is the same size as the
+original ORCA1 domain.  Thus the extended domain configuration file can be used with all
+the original input files for ORCA1 if the ice cavities are not active (\np{ln\_isfcav =
+.false.}).  Full instructions for achieving this are:
+
+\begin{itemize}
+\item  Add the new attribute to any input files requiring a j-row offset, i.e:
+\begin{cmds} 
+ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_domcfg.nc 
+\end{cmds}
+
+\item Add the logical switch \np{ln\_use\_jattr} to \ngn{namcfg} in the configuration
+namelist (if it is not already there) and set \np{.true.}
+\end{itemize}
+
+\noindent Note that with this option, the j-size of the global domain is (extended
+j-size minus \np{open\_ocean\_jstart} + 1 ) and this must match the \texttt{jpjglo} value
+for the configuration. This means an alternative version of \ifile{eORCA1\_domcfg.nc} must
+be created for when \np{ln\_use\_jattr} is active. The \texttt{ncap2} tool provides a
+convenient way of achieving this:
+
 \begin{cmds}
-ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_coordinates.nc 
-ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_bathymetry_v2.nc
+ncap2 -s 'jpjglo=292' eORCA1_domcfg.nc nORCA1_domcfg.nc
 \end{cmds}
- 
-\noindent Add the logical switch to \ngn{namcfg} in the configuration namelist and set true:
-%--------------------------------------------namcfg--------------------------------------------------------
-
-\nlst{namcfg}
-%--------------------------------------------------------------------------------------------------------------
-
-\noindent Note the j-size of the global domain is the (extended j-size minus \np{open\_ocean\_jstart} + 1 ) and
-this must match the size of all datasets other than bathymetry and coordinates currently.
-However the option can be extended to any global, 2D and 3D, netcdf, input field by adding the:
-\vspace{-10pt}
+
+The domain configuration file is unique in this respect since it also contains the value
+of \texttt{jpjglo} that is read and used by the model. Any other global, 2D and 3D,
+netcdf, input field can be prepared for use in a reduced domain by adding the
+\texttt{open\_ocean\_jstart} attribute to the file's  global attributes. In particular
+this is true for any field that is read by \NEMO using the following optional argument to
+the appropriate call to \np{iom\_get}.
 \begin{forlines}
 lrowattr=ln_use_jattr
 \end{forlines}
-optional argument to the appropriate \np{iom\_get} call and the \np{open\_ocean\_jstart} attribute to
-the corresponding input files.
-It remains the users responsibility to set \np{jpjdta} and \np{jpjglo} values in
-the \np{namelist\_cfg} file according to their needs.
-
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-\begin{figure}[!ht]
-  \begin{center}
-    \includegraphics[width=0.90\textwidth]{Fig_LBC_zoom}
-    \caption{
-      \protect\label{fig:LBC_zoom}
-      Position of a model domain compared to the data input domain when the zoom functionality is used.
-    }
-  \end{center}
-\end{figure}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-
+
+Currently, only the domain configuration variables make use of this optional argument so
+this facility is of little practical use except for tests where no other external input
+files are needed or you wish to use an extended domain configuration with inputs from
+earlier, non-extended configurations. Alternatively, it should be possible to exclude
+empty rows for extended domain, forced ocean runs using interpolation on the fly, by
+adding the optional argument to \texttt{iom\_get} calls for the weights and initial
+conditions. Experimenting with this remains an exercise for the user.
 
 % ================================================================
 % Accuracy and Reproducibility
 % ================================================================
-\section{Accuracy and reproducibility (\protect\mdl{lib\_fortran})}
+\section[Accuracy and reproducibility (\textit{lib\_fortran.F90})]
+{Accuracy and reproducibility (\protect\mdl{lib\_fortran})}
 \label{sec:MISC_fortran}
 
-\subsection{Issues with intrinsinc SIGN function (\protect\key{nosignedzero})}
+\subsection[Issues with intrinsinc SIGN function (\texttt{\textbf{key\_nosignedzero}})]
+{Issues with intrinsinc SIGN function (\protect\key{nosignedzero})}
 \label{subsec:MISC_sign}
 
@@ -272 +297 @@
 and their propagation and accumulation cause uncertainty in final simulation reproducibility on
 different numbers of processors.
-To avoid so, based on \citet{He_Ding_JSC01} review of different technics,
+To avoid so, based on \citet{he.ding_JS01} review of different technics,
 we use a so called self-compensated summation method.
 The idea is to estimate the roundoff error, store it in a buffer, and then add it back in the next addition. 
@@ -314 +339 @@
 This alternative method should give identical results to the default \textsc{ALLGATHER} method and
 is recommended for large values of \np{jpni}.
-The new method is activated by setting \np{ln\_nnogather} to be true ({\bf nammpp}).
+The new method is activated by setting \np{ln\_nnogather} to be true (\ngn{nammpp}).
 The reproducibility of results using the two methods should be confirmed for each new,
 non-reference configuration.

@@ -1 @@
-*.aux
-*.bbl
-*.blg
-*.dvi
-*.fdb*
-*.fls
-*.idx
-*.ilg
-*.ind
-*.log
-*.maf
-*.mtc*
-*.out
-*.pdf
-*.toc
-_minted-*
+figures