New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
Changeset 11435 for NEMO/trunk/doc/latex/NEMO/subfiles/chap_DOM.tex – NEMO

Ignore:
Timestamp:
2019-08-14T14:45:08+02:00 (5 years ago)
Author:
nicolasmartin
Message:

Various corrections on chapters

Cleaning the indexes by fixing/removing wrong entries (or appending a ? to unknown items) and
improve the classification with new index definitions for CPP keys and namelist blocks:

  • from \key{...} cmd, key_ prefix no longer precedes the index entry
  • namelist block declaration moves from \ngn{nam...} to \nam{...} (i.e. \ngn{namtra\_ldf} -> \nam{tra\_ldf}) The expected prefix nam is added to the printed word but not the index entry.

Now we have indexes with a better sorting instead of all CPP keys under 'K' and namelists blocks under 'N'.

Fix missing space issues with alias commands by adding a trailing backslash (\NEMO\, \ie\, \eg\, ...).
There is no perfect solution for this, and I prefer not using a particular package to solve it.

Review the initial LaTeX code snippet for the historic changes in chapters

Finally, for readability and future diff visualisations, please avoid writing paragraphs with continuous lines.
Break the lines around 80 to 100 characters long

File:
1 edited

Legend:

Unmodified
Added
Removed

  • NEMO/trunk/doc/latex/NEMO/subfiles/chap_DOM.tex

    r11330 r11435  
    88\label{chap:DOM} 
    99 
    10 \minitoc 
     10%\chaptertoc 
    1111 
    1212% Missing things: 
    1313%  - istate: description of the initial state   ==> this has to be put elsewhere.. 
    14 %                  perhaps in MISC ?  By the way the initialisation of T S and dynamics  
     14%                  perhaps in MISC ?  By the way the initialisation of T S and dynamics 
    1515%                  should be put outside of DOM routine (better with TRC staff and off-line 
    1616%                  tracers) 
    … …  
    1919 
    2020\vfill 
    21 \begin{figure}[b] 
    22 \subsubsection*{Changes record} 
    23 \begin{tabular}{m{0.08\linewidth}||m{0.32\linewidth}|m{0.6\linewidth}} 
    24     Release   & Author(s)     & Modifications \\ 
    25 \hline 
    26     {\em 4.0} & {\em Simon M{\"u}ller \& Andrew Coward} & {\em Compatibility changes for v4.0. Major simplication has moved many of the options to external domain configuration tools. For now this information has been retained in \autoref{apdx:DOMAINcfg} }  \\ 
    27     {\em 3.x} & {\em Sebastien Masson, Gurvan Madec \& Rashid Benshila } & {\em }  \\ 
    28 \end{tabular} 
    29 \end{figure} 
     21 
     22\begin{table}[b] 
     23  \footnotesize 
     24  \caption*{Changes record} 
     25  \begin{tabularx}{\textwidth}{l||X|X} 
     26    Release & Author(s) & Modifications                                                          \\ 
     27    \hline 
     28    {\em 4.0} & {\em Simon M\"{u}ller \& Andrew Coward} & 
     29    {\em 
     30      Compatibility changes Major simplification has moved many of the options to external domain configuration tools. 
     31      (see \autoref{apdx:DOMAINcfg}) 
     32    }                                                                                            \\ 
     33    {\em 3.x} & {\em Rachid Benshila, Gurvan Madec \& S\'{e}bastien Masson} & 
     34    {\em First version}                                                                          \\ 
     35  \end{tabularx} 
     36\end{table} 
    3037 
    3138\newpage 
    3239 
    33 Having defined the continuous equations in \autoref{chap:PE} and chosen a time discretization \autoref{chap:STP}, 
    34 we need to choose a grid for spatial discretization and related numerical algorithms. 
     40Having defined the continuous equations in \autoref{chap:PE} and chosen a time discretisation \autoref{chap:STP}, 
     41we need to choose a grid for spatial discretisation and related numerical algorithms. 
    3542In the present chapter, we provide a general description of the staggered grid used in \NEMO, 
    36 and other relevant information about the DOM (DOMain) source-code modules . 
     43and other relevant information about the DOM (DOMain) source code modules. 
    3744 
    3845% ================================================================ 
    … …  
    4350 
    4451% ------------------------------------------------------------------------------------------------------------- 
    45 %        Arrangement of Variables  
     52%        Arrangement of Variables 
    4653% ------------------------------------------------------------------------------------------------------------- 
    4754\subsection{Arrangement of variables} 
    … …  
    7582the barotropic stream function $\psi$ is defined at horizontal points overlying the $\zeta$ and $f$-points. 
    7683 
    77 The ocean mesh (\ie the position of all the scalar and vector points) is defined by the transformation that 
     84The ocean mesh (\ie\ the position of all the scalar and vector points) is defined by the transformation that 
    7885gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 
    7986The grid-points are located at integer or integer and a half value of $(i,j,k)$ as indicated on \autoref{tab:cell}. 
    … …  
    127134 
    128135Note that the definition of the scale factors 
    129 (\ie as the analytical first derivative of the transformation that 
     136(\ie\ as the analytical first derivative of the transformation that 
    130137results in $(\lambda,\varphi,z)$ as a function of $(i,j,k)$) 
    131 is specific to the \NEMO model \citep{marti.madec.ea_JGR92}. 
     138is specific to the \NEMO\ model \citep{marti.madec.ea_JGR92}. 
    132139As an example, a scale factor in the $i$ direction is defined locally at a $t$-point, 
    133140whereas many other models on a C grid choose to define such a scale factor as 
    … …  
    159166 
    160167% ------------------------------------------------------------------------------------------------------------- 
    161 %        Vector Invariant Formulation  
     168%        Vector Invariant Formulation 
    162169% ------------------------------------------------------------------------------------------------------------- 
    163170\subsection{Discrete operators} 
    … …  
    173180 
    174181Similar operators are defined with respect to $i + 1/2$, $j$, $j + 1/2$, $k$, and $k + 1/2$. 
    175 Following \autoref{eq:PE_grad} and \autoref{eq:PE_lap}, the gradient of a variable $q$ defined at 
    176 a $t$-point has its three components defined at $u$-, $v$- and $w$-points while 
    177 its Laplacian is defined at the $t$-point. 
     182Following \autoref{eq:PE_grad} and \autoref{eq:PE_lap}, the gradient of a variable $q$ defined at a $t$-point has 
     183its three components defined at $u$-, $v$- and $w$-points while its Laplacian is defined at the $t$-point. 
    178184These operators have the following discrete forms in the curvilinear $s$-coordinates system: 
    179185\[ 
    … …  
    215221 
    216222The vertical average over the whole water column is denoted by an overbar and is for 
    217 a masked field $q$ (\ie a quantity that is equal to zero inside solid areas): 
     223a masked field $q$ (\ie\ a quantity that is equal to zero inside solid areas): 
    218224\begin{equation} 
    219225  \label{eq:DOM_bar} 
    … …  
    247253\end{alignat} 
    248254 
    249 In other words, the adjoint of the differencing and averaging operators are $\delta_i^* = \delta_{i + 1/2}$ and  
     255In other words, the adjoint of the differencing and averaging operators are $\delta_i^* = \delta_{i + 1/2}$ and 
    250256$(\overline{\cdots}^{\, i})^* = \overline{\cdots}^{\, i + 1/2}$, respectively. 
    251257These two properties will be used extensively in the \autoref{apdx:C} to 
    … …  
    253259 
    254260% ------------------------------------------------------------------------------------------------------------- 
    255 %        Numerical Indexing  
     261%        Numerical Indexing 
    256262% ------------------------------------------------------------------------------------------------------------- 
    257263\subsection{Numerical indexing} 
    … …  
    275281integer values for $t$-points only while all the other points involve integer and a half values. 
    276282Therefore, a specific integer indexing has been defined for points other than $t$-points 
    277 (\ie velocity and vorticity grid-points). 
     283(\ie\ velocity and vorticity grid-points). 
    278284Furthermore, the direction of the vertical indexing has been reversed and the surface level set at $k = 1$. 
    279285 
    280286% ----------------------------------- 
    281 %        Horizontal Indexing  
     287%        Horizontal Indexing 
    282288% ----------------------------------- 
    283289\subsubsection{Horizontal indexing} 
    … …  
    288294the $t$-point and the eastward $u$-point (northward $v$-point) have the same index 
    289295(see the dashed area in \autoref{fig:index_hor}). 
    290 A $t$-point and its nearest northeast $f$-point have the same $i$-and $j$-indices. 
     296A $t$-point and its nearest north-east $f$-point have the same $i$-and $j$-indices. 
    291297 
    292298% ----------------------------------- 
    293 %        Vertical indexing  
     299%        Vertical indexing 
    294300% ----------------------------------- 
    295301\subsubsection{Vertical indexing} 
    … …  
    303309The last $w$-level ($k = jpk$) either corresponds to or is below the ocean floor while 
    304310the last $t$-level is always outside the ocean domain (\autoref{fig:index_vert}). 
    305 Note that a $w$-point and the directly underlaying $t$-point have a common $k$ index (\ie $t$-points and their 
    306 nearest $w$-point neighbour in negative index direction), in contrast to the indexing on the horizontal plane where 
    307 the $t$-point has the same index as the nearest velocity points in the positive direction of the respective horizontal axis index 
     311Note that a $w$-point and the directly underlaying $t$-point have a common $k$ index 
     312(\ie\ $t$-points and their nearest $w$-point neighbour in negative index direction), 
     313in contrast to the indexing on the horizontal plane where the $t$-point has the same index as 
     314the nearest velocity points in the positive direction of the respective horizontal axis index 
    308315(compare the dashed area in \autoref{fig:index_hor} and \autoref{fig:index_vert}). 
    309316Since the scale factors are chosen to be strictly positive, 
    310 a \textit{minus sign} is included in the \fortran implementations of \textit{all the vertical derivatives} of 
    311 the discrete equations given in this manual in order to accommodate the opposing vertical index directions in implementation and documentation. 
     317a \textit{minus sign} is included in the \fortran implementations of 
     318\textit{all the vertical derivatives} of the discrete equations given in this manual in order to 
     319accommodate the opposing vertical index directions in implementation and documentation. 
    312320 
    313321%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    … …  
    333341\nlst{namcfg} 
    334342 
    335 Two typical methods are available to specify the spatial domain 
    336 configuration; they can be selected using parameter \np{ln\_read\_cfg} 
    337 parameter in namelist \ngn{namcfg}.  
    338  
    339 If \np{ln\_read\_cfg} is set to \forcode{.true.}, the domain-specific parameters 
    340 and fields are read from a netCDF input file, whose name (without its .nc 
    341 suffix) can be specified as the value of the \np{cn\_domcfg} parameter in 
    342 namelist \ngn{namcfg}. 
    343  
    344 If \np{ln\_read\_cfg} is set to \forcode{.false.}, the domain-specific 
    345 parameters and fields can be provided (\eg analytically computed) by subroutines 
    346 \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}. These subroutines can be supplied in 
    347 the \path{MY_SRC} directory of the configuration, and default versions that 
    348 configure the spatial domain for the GYRE reference configuration are present in 
    349 the \path{src/OCE/USR} directory. 
    350  
    351 In version 4.0 there are no longer any options for reading complex bathmetries and  
    352 performing a vertical discretization at run-time. Whilst it is occasionally convenient 
    353 to have a common bathymetry file and, for example, to run similar models with and 
    354 without partial bottom boxes and/or sigma-coordinates, supporting such choices leads to 
    355 overly complex code. Worse still is the difficulty of ensuring the model configurations  
    356 intended to be identical are indeed so when the model domain itself can be altered by runtime 
    357 selections. The code previously used to perform vertical discretization has be incorporated  
    358 into an external tool (\path{tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMAINcfg}. 
    359  
    360 The next subsections summarise the parameter and fields related to the 
    361 configuration of the whole model domain. These represent the minimum information 
    362 that must be provided either via the \np{cn\_domcfg} file or set by code 
    363 inserted into user-supplied versions of the \mdl{usrdef\_*} subroutines. The 
    364 requirements are presented in three sections: the domain size 
    365 (\autoref{subsec:DOM_size}), the horizontal mesh 
    366 (\autoref{subsec:DOM_hgr}), and the vertical grid 
    367 (\autoref{subsec:DOM_zgr}). 
     343Two typical methods are available to specify the spatial domain configuration; 
     344they can be selected using parameter \np{ln\_read\_cfg} parameter in namelist \nam{cfg}. 
     345 
     346If \np{ln\_read\_cfg} is set to \forcode{.true.}, 
     347the domain-specific parameters and fields are read from a netCDF input file, 
     348whose name (without its .nc suffix) can be specified as the value of the \np{cn\_domcfg} parameter in namelist \nam{cfg}. 
     349 
     350If \np{ln\_read\_cfg} is set to \forcode{.false.}, 
     351the domain-specific parameters and fields can be provided (\eg\ analytically computed) by 
     352subroutines \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}. 
     353These subroutines can be supplied in the \path{MY_SRC} directory of the configuration, 
     354and default versions that configure the spatial domain for the GYRE reference configuration are present in 
     355the \path{./src/OCE/USR} directory. 
     356 
     357In version 4.0 there are no longer any options for reading complex bathymetries and 
     358performing a vertical discretisation at run-time. 
     359Whilst it is occasionally convenient to have a common bathymetry file and, for example, 
     360to run similar models with and without partial bottom boxes and/or sigma-coordinates, 
     361supporting such choices leads to overly complex code. 
     362Worse still is the difficulty of ensuring the model configurations intended to be identical are indeed so when 
     363the model domain itself can be altered by runtime selections. 
     364The code previously used to perform vertical discretisation has been incorporated into an external tool 
     365(\path{./tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMAINcfg}. 
     366 
     367The next subsections summarise the parameter and fields related to the configuration of the whole model domain. 
     368These represent the minimum information that must be provided either via the \np{cn\_domcfg} file or set by code 
     369inserted into user-supplied versions of the \texttt{usrdef\_*} subroutines. 
     370The requirements are presented in three sections: 
     371the domain size (\autoref{subsec:DOM_size}), the horizontal mesh (\autoref{subsec:DOM_hgr}), 
     372and the vertical grid (\autoref{subsec:DOM_zgr}). 
    368373 
    369374% ----------------------------------- 
    … …  
    373378\label{subsec:DOM_size} 
    374379 
    375 The total size of the computational domain is set by the parameters 
    376 \np{jpiglo}, \np{jpjglo} and \np{jpkglo} for the $i$, $j$ and $k$ 
    377 directions, respectively. Note, that the variables \forcode{jpi} and \forcode{jpj} 
    378 refer to the size of each processor subdomain when the code is run in 
    379 parallel using domain decomposition (\key{mpp\_mpi} defined, see 
    380 \autoref{sec:LBC_mpp}). 
     380The total size of the computational domain is set by the parameters \jp{jpiglo}, \jp{jpjglo} and \jp{jpkglo} for 
     381the $i$, $j$ and $k$ directions, respectively. 
     382Note, that the variables \texttt{jpi} and \texttt{jpj} refer to the size of each processor subdomain when 
     383the code is run in parallel using domain decomposition (\key{mpp\_mpi} defined, 
     384see \autoref{sec:LBC_mpp}). 
    381385 
    382386The name of the configuration is set through parameter \np{cn\_cfg}, 
    383 and the nominal resolution through parameter \np{nn\_cfg} (unless in 
    384 the input file both of variables \forcode{ORCA} and \forcode{ORCA_index} 
    385 are present, in which case \np{cn\_cfg} and \np{nn\_cfg} are set from these 
    386 values accordingly). 
    387  
    388 The global lateral boundary condition type is selected from 8 options 
    389 using parameter \np{jperio}. See \autoref{sec:LBC_jperio} for 
    390 details on the available options and the corresponding values for 
    391 \np{jperio}. 
    392  
    393 % ================================================================ 
    394 % Domain: Horizontal Grid (mesh)  
     387and the nominal resolution through parameter \np{nn\_cfg} 
     388(unless in the input file both of variables \texttt{ORCA} and \texttt{ORCA\_index} are present, 
     389in which case \np{cn\_cfg} and \np{nn\_cfg} are set from these values accordingly). 
     390 
     391The global lateral boundary condition type is selected from 8 options using parameter \jp{jperio}. 
     392See \autoref{sec:LBC_jperio} for details on the available options and the corresponding values for \jp{jperio}. 
     393 
     394% ================================================================ 
     395% Domain: Horizontal Grid (mesh) 
    395396% ================================================================ 
    396397\subsection{Horizontal grid mesh (\protect\mdl{domhgr})} 
    … …  
    402403\subsubsection{Required fields} 
    403404\label{sec:DOM_hgr_fields} 
    404 The explicit specification of a range of mesh-related fields are required for the definition of a configuration. These include: 
    405  
    406 \begin{Verbatim}[fontsize=\tiny] 
     405 
     406The explicit specification of a range of mesh-related fields are required for the definition of a configuration. 
     407These include: 
     408 
     409\begin{clines} 
    407410int    jpiglo, jpjglo, jpkglo            /* global domain sizes                                          */ 
    408411int    jperio                            /* lateral global domain b.c.                                   */ 
    … …  
    411414double e1t, e1u, e1v, e1f                /* horizontal scale factors                                     */ 
    412415double e2t, e2u, e2v, e2f                /* horizontal scale factors                                     */ 
    413 \end{Verbatim} 
    414  
    415 The values of the geographic longitude and latitude arrays at indices $i,j$ correspond to the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$, evaluated at the values as specified in Table \autoref{tab:cell} for the respective grid-point position. The calculation of the values of the horizontal scale factor arrays in general additionally involves partial derivatives of $\lambda$ and $\varphi$ with respect to $i$ and $j$, evaluated for the same arguments as $\lambda$ and $\varphi$. 
     416\end{clines} 
     417 
     418The values of the geographic longitude and latitude arrays at indices $i,j$ correspond to 
     419the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$, 
     420evaluated at the values as specified in \autoref{tab:cell} for the respective grid-point position. 
     421The calculation of the values of the horizontal scale factor arrays in general additionally involves 
     422partial derivatives of $\lambda$ and $\varphi$ with respect to $i$ and $j$, 
     423evaluated for the same arguments as $\lambda$ and $\varphi$. 
    416424 
    417425\subsubsection{Optional fields} 
    418 \begin{Verbatim}[fontsize=\tiny] 
     426 
     427\begin{clines} 
    419428                                         /* Optional:                                                    */ 
    420429int    ORCA, ORCA_index                  /* configuration name, configuration resolution                 */ 
    421430double e1e2u, e1e2v                      /* U and V surfaces (if grid size reduction in some straits)    */ 
    422431double ff_f, ff_t                        /* Coriolis parameter (if not on the sphere)                    */ 
    423 \end{Verbatim} 
    424  
    425 NEMO can support the local reduction of key strait widths by altering individual values of 
    426 e2u or e1v at the appropriate locations. This is particularly useful for locations such as 
    427 Gibraltar or Indonesian Throughflow pinch-points (see \autoref{sec:MISC_strait} for 
    428 illustrated examples). The key is to reduce the faces of $T$-cell (\ie change the value of 
    429 the horizontal scale factors at $u$- or $v$-point) but not the volume of the cells. Doing 
    430 otherwise can lead to numerical instability issues.  In normal operation the surface areas 
    431 are computed from $\texttt{e1u} * \texttt{e2u}$ and $\texttt{e1v} * \texttt{e2v}$ but in 
    432 cases where a gridsize reduction is required, the unaltered surface areas at $u$ and $v$ 
    433 grid points (\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or pre-computed 
    434 in \mdl{usrdef\_hgr}. If these arrays are present in the \np{cn\_domcfg} file they are 
    435 read and the internal computation is suppressed. Versions of \mdl{usrdef\_hgr} which set 
    436 their own values of \texttt{e1e2u} and \texttt{e1e2v} should set the surface-area 
    437 computation flag: \texttt{ie1e2u\_v} to a non-zero value to suppress their re-computation. 
     432\end{clines} 
     433 
     434\NEMO\ can support the local reduction of key strait widths by 
     435altering individual values of e2u or e1v at the appropriate locations. 
     436This is particularly useful for locations such as Gibraltar or Indonesian Throughflow pinch-points 
     437(see \autoref{sec:MISC_strait} for illustrated examples). 
     438The key is to reduce the faces of $T$-cell (\ie\ change the value of the horizontal scale factors at $u$- or $v$-point) but 
     439not the volume of the cells. 
     440Doing otherwise can lead to numerical instability issues. 
     441In normal operation the surface areas are computed from $e1u * e2u$ and $e1v * e2v$ but 
     442in cases where a gridsize reduction is required, 
     443the unaltered surface areas at $u$ and $v$ grid points (\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or 
     444pre-computed in \mdl{usrdef\_hgr}. 
     445If these arrays are present in the \np{cn\_domcfg} file they are read and the internal computation is suppressed. 
     446Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{e1e2u} and \texttt{e1e2v} should set 
     447the surface-area computation flag: 
     448\texttt{ie1e2u\_v} to a non-zero value to suppress their re-computation. 
    438449 
    439450\smallskip 
    440 Similar logic applies to the other optional fields: \texttt{ff\_f} and \texttt{ff\_t} 
    441 which can be used to provide the Coriolis parameter at F- and T-points respectively if the 
    442 mesh is not on a sphere. If present these fields will be read and used and the normal 
    443 calculation ($2*\Omega*\sin(\varphi)$) suppressed. Versions of \mdl{usrdef\_hgr} which set 
    444 their own values of \texttt{ff\_f} and \texttt{ff\_t} should set the Coriolis computation 
    445 flag: \texttt{iff} to a non-zero value to suppress their re-computation. 
    446  
    447 Note that longitudes, latitudes, and scale factors at $w$ points are exactly 
    448 equal to those of $t$ points, thus no specific arrays are defined at $w$ points. 
     451Similar logic applies to the other optional fields: 
     452\texttt{ff\_f} and \texttt{ff\_t} which can be used to provide the Coriolis parameter at F- and T-points respectively if 
     453the mesh is not on a sphere. 
     454If present these fields will be read and used and the normal calculation ($2 * \Omega * \sin(\varphi)$) suppressed. 
     455Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{ff\_f} and \texttt{ff\_t} should set 
     456the Coriolis computation flag: 
     457\texttt{iff} to a non-zero value to suppress their re-computation. 
     458 
     459Note that longitudes, latitudes, and scale factors at $w$ points are exactly equal to those of $t$ points, 
     460thus no specific arrays are defined at $w$ points. 
    449461 
    450462 
    … …  
    459471%------------------------------------------------------------------------------------------------------------- 
    460472 
    461 In the vertical, the model mesh is determined by four things:  
     473In the vertical, the model mesh is determined by four things: 
    462474\begin{enumerate} 
    463   \item the bathymetry given in meters;  
    464   \item the number of levels of the model (\jp{jpk});  
     475  \item the bathymetry given in meters; 
     476  \item the number of levels of the model (\jp{jpk}); 
    465477  \item the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and 
    466   \item the masking system, \ie the number of wet model levels at each  
     478  \item the masking system, \ie\ the number of wet model levels at each 
    467479$(i,j)$ location of the horizontal grid. 
    468480\end{enumerate} 
    … …  
    488500 
    489501The choice of a vertical coordinate is made when setting up the configuration; 
    490 it is not intended to be an option which can be changed in the middle of an 
    491 experiment. The one exception to this statement being the choice of linear or 
    492 non-linear free surface. In v4.0 the linear free surface option is implemented 
    493 as a special case of the non-linear free surface. This is computationally 
    494 wasteful since it uses the structures for time-varying 3D metrics for fields 
    495 that (in the linear free surface case) are fixed. However, the linear 
    496 free-surface is rarely used and implementing it this way means a single configuration 
    497 file can support both options. 
    498  
    499 By default a non-linear free surface is used (\np{ln\_linssh} set to \forcode{ = 
    500 .false.} in \ngn{namdom}): the coordinate follow the time-variation of the free 
    501 surface so that the transformation is time dependent: $z(i,j,k,t)$ 
    502 (\eg \autoref{fig:z_zps_s_sps}f).  When a linear free surface is assumed 
    503 (\np{ln\_linssh} set to \forcode{ = .true.} in \ngn{namdom}), the vertical 
    504 coordinates are fixed in time, but the seawater can move up and down across the 
    505 $z_0$ surface (in other words, the top of the ocean in not a rigid lid). 
    506  
    507 Note that settings: \np{ln\_zco}, \np{ln\_zps}, \np{ln\_sco} and \np{ln\_isfcav} mentioned 
    508 in the following sections appear to be namelist options but they are no longer truly 
    509 namelist options for NEMO. Their value is written to and read from the domain configuration file 
    510 and they should be treated as fixed parameters for a particular configuration. They are 
    511 namelist options for the \forcode{DOMAINcfg} tool that can be used to build the 
    512 configuration file and serve both to provide a record of the choices made whilst building the 
    513 configuration and to trigger appropriate code blocks within NEMO. 
     502it is not intended to be an option which can be changed in the middle of an experiment. 
     503The one exception to this statement being the choice of linear or non-linear free surface. 
     504In v4.0 the linear free surface option is implemented as a special case of the non-linear free surface. 
     505This is computationally wasteful since it uses the structures for time-varying 3D metrics 
     506for fields that (in the linear free surface case) are fixed. 
     507However, the linear free-surface is rarely used and implementing it this way means 
     508a single configuration file can support both options. 
     509 
     510By default a non-linear free surface is used (\np{ln\_linssh} set to \forcode{ = .false.} in \nam{dom}): 
     511the coordinate follow the time-variation of the free surface so that the transformation is time dependent: 
     512$z(i,j,k,t)$ (\eg\ \autoref{fig:z_zps_s_sps}f). 
     513When a linear free surface is assumed (\np{ln\_linssh} set to \forcode{ = .true.} in \nam{dom}), 
     514the vertical coordinates are fixed in time, but the seawater can move up and down across the $z_0$ surface 
     515(in other words, the top of the ocean in not a rigid lid). 
     516 
     517Note that settings: 
     518\np{ln\_zco}, \np{ln\_zps}, \np{ln\_sco} and \np{ln\_isfcav} mentioned in the following sections 
     519appear to be namelist options but they are no longer truly namelist options for \NEMO. 
     520Their value is written to and read from the domain configuration file and 
     521they should be treated as fixed parameters for a particular configuration. 
     522They are namelist options for the \texttt{DOMAINcfg} tool that can be used to build the configuration file and 
     523serve both to provide a record of the choices made whilst building the configuration and 
     524to trigger appropriate code blocks within \NEMO. 
    514525These values should not be altered in the \np{cn\_domcfg} file. 
    515526 
    … …  
    527538$s-z$ or $s-zps$ coordinate (\autoref{fig:z_zps_s_sps}d and \autoref{fig:z_zps_s_sps}e). 
    528539 
    529 A further choice related to vertical coordinate concerns the presence (or not) of ocean 
    530 cavities beneath ice shelves within the model domain.  A setting of \np{ln\_isfcav} as 
    531 \forcode{.true.} indicates that the domain contains  ocean cavities, otherwise the top, 
    532 wet layer of the ocean will always be at the ocean surface.  This option is currently only 
    533 available for $z$- or $zps$-coordinates. In the latter case, partial steps are also applied 
    534 at the ocean/ice shelf interface. 
    535  
    536 Within the model, the arrays describing the grid point depths and vertical scale factors 
    537 are three set of three dimensional arrays $(i,j,k)$ defined at \textit{before}, 
    538 \textit{now} and \textit{after} time step.  The time at which they are defined is 
    539 indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively.  They are updated at each 
    540 model time step. The initial fixed reference coordinate system is held in variable names 
    541 with a $\_0$ suffix.  When the linear free surface option is used 
    542 (\np{ln\_linssh}\forcode{ = .true.}), \textit{before}, \textit{now} and \textit{after} 
    543 arrays are initially set to their reference counterpart and remain fixed. 
     540A further choice related to vertical coordinate concerns 
     541the presence (or not) of ocean cavities beneath ice shelves within the model domain. 
     542A setting of \np{ln\_isfcav} as \forcode{.true.} indicates that the domain contains ocean cavities, 
     543otherwise the top, wet layer of the ocean will always be at the ocean surface. 
     544This option is currently only available for $z$- or $zps$-coordinates. 
     545In the latter case, partial steps are also applied at the ocean/ice shelf interface. 
     546 
     547Within the model, the arrays describing the grid point depths and vertical scale factors are three set of 
     548three dimensional arrays $(i,j,k)$ defined at \textit{before}, \textit{now} and \textit{after} time step. 
     549The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively. 
     550They are updated at each model time step. 
     551The initial fixed reference coordinate system is held in variable names with a $\_0$ suffix. 
     552When the linear free surface option is used (\np{ln\_linssh}\forcode{ = .true.}), 
     553\textit{before}, \textit{now} and \textit{after} arrays are initially set to 
     554their reference counterpart and remain fixed. 
    544555 
    545556\subsubsection{Required fields} 
    546557\label{sec:DOM_zgr_fields} 
    547 The explicit specification of a range of fields related to the vertical grid are required for the definition of a configuration. These include: 
    548  
    549 \begin{Verbatim}[fontsize=\tiny] 
     558 
     559The explicit specification of a range of fields related to the vertical grid are required for 
     560the definition of a configuration. 
     561These include: 
     562 
     563\begin{clines} 
    550564int    ln_zco, ln_zps, ln_sco            /* flags for z-coord, z-coord with partial steps and s-coord    */ 
    551565int    ln_isfcav                         /* flag  for ice shelf cavities                                 */ 
    … …  
    556570                                         /* For reference:                                               */ 
    557571float  bathy_metry                       /* bathymetry used in setting top and bottom levels             */ 
    558 \end{Verbatim} 
    559  
    560 This set of vertical metrics is sufficient to describe the initial depth and thickness of 
    561 every gridcell in the model regardless of the choice of vertical coordinate. With constant 
    562 z-levels, e3 metrics will be uniform across each horizontal level. In the partial step 
    563 case each e3 at the \np{bottom\_level} (and, possibly, \np{top\_level} if ice cavities are 
    564 present) may vary from its horizontal neighbours. And, in s-coordinates, variations can 
    565 occur throughout the water column. With the non-linear free-surface, all the coordinates 
    566 behave more like the s-coordinate in that variations occurr throughout the water column 
    567 with displacements related to the sea surface height. These variations are typically much 
    568 smaller than those arising from bottom fitted coordinates. The values for vertical metrics 
    569 supplied in the domain configuration file can be considered as those arising from a flat 
    570 sea surface with zero elevation. 
    571  
    572 The \np{bottom\_level} and \np{top\_level} 2D arrays define the \np{bottom\_level} and top 
    573 wet levels in each grid column. Without ice cavities, \np{top\_level} is essentially a land 
    574 mask (0 on land; 1 everywhere else). With ice cavities, \np{top\_level} determines the 
    575 first wet point below the overlying ice shelf. 
    576  
    577  
    578  
    579 % ------------------------------------------------------------------------------------------------------------- 
    580 %        level bathymetry and mask  
     572\end{clines} 
     573 
     574This set of vertical metrics is sufficient to describe the initial depth and thickness of every gridcell in 
     575the model regardless of the choice of vertical coordinate. 
     576With constant z-levels, e3 metrics will be uniform across each horizontal level. 
     577In the partial step case each e3 at the \jp{bottom\_level} 
     578(and, possibly, \jp{top\_level} if ice cavities are present) 
     579may vary from its horizontal neighbours. 
     580And, in s-coordinates, variations can occur throughout the water column. 
     581With the non-linear free-surface, all the coordinates behave more like the s-coordinate in 
     582that variations occur throughout the water column with displacements related to the sea surface height. 
     583These variations are typically much smaller than those arising from bottom fitted coordinates. 
     584The values for vertical metrics supplied in the domain configuration file can be considered as 
     585those arising from a flat sea surface with zero elevation. 
     586 
     587The \jp{bottom\_level} and \jp{top\_level} 2D arrays define the \jp{bottom\_level} and top wet levels in each grid column. 
     588Without ice cavities, \jp{top\_level} is essentially a land mask (0 on land; 1 everywhere else). 
     589With ice cavities, \jp{top\_level} determines the first wet point below the overlying ice shelf. 
     590 
     591 
     592% ------------------------------------------------------------------------------------------------------------- 
     593%        level bathymetry and mask 
    581594% ------------------------------------------------------------------------------------------------------------- 
    582595\subsubsection{Level bathymetry and mask} 
    … …  
    584597 
    585598 
    586 From \np{top\_level} and \np{bottom\_level} fields, the mask fields are defined as follows: 
     599From \jp{top\_level} and \jp{bottom\_level} fields, the mask fields are defined as follows: 
    587600\begin{alignat*}{2} 
    588601  tmask(i,j,k) &= &  & 
    … …  
    603616Note that, without ice shelves cavities, 
    604617masks at $t-$ and $w-$points are identical with the numerical indexing used (\autoref{subsec:DOM_Num_Index}). 
    605 Nevertheless, $wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface)  
     618Nevertheless, $wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface) 
    606619exactly in the same way as for the bottom boundary. 
    607620 
    … …  
    614627 
    615628%------------------------------------------------------------------------------------------------- 
    616 %        Closed seas  
     629%        Closed seas 
    617630%------------------------------------------------------------------------------------------------- 
    618 \subsection{Closed seas} \label{subsec:DOM_closea}  
    619  
    620 When a global ocean is coupled to an atmospheric model it is better to represent all large 
    621 water bodies (\eg great lakes, Caspian sea...) even if the model resolution does not allow 
    622 their communication with the rest of the ocean.  This is unnecessary when the ocean is 
    623 forced by fixed atmospheric conditions, so these seas can be removed from the ocean 
    624 domain.  The user has the option to set the bathymetry in closed seas to zero (see 
    625 \autoref{sec:MISC_closea}) and to optionally decide on the fate of any freshwater 
    626 imbalance over the area. The options are explained in \autoref{sec:MISC_closea} but it 
    627 should be noted here that a successful use of these options requires appropriate mask 
    628 fields to be present in the domain configuration file. Among the possibilities are: 
    629  
    630 \begin{Verbatim}[fontsize=\tiny] 
     631\subsection{Closed seas} \label{subsec:DOM_closea} 
     632 
     633When a global ocean is coupled to an atmospheric model it is better to represent all large water bodies 
     634(\eg\ Great Lakes, Caspian sea \dots) even if the model resolution does not allow their communication with 
     635the rest of the ocean. 
     636This is unnecessary when the ocean is forced by fixed atmospheric conditions, 
     637so these seas can be removed from the ocean domain. 
     638The user has the option to set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}) and 
     639to optionally decide on the fate of any freshwater imbalance over the area. 
     640The options are explained in \autoref{sec:MISC_closea} but it should be noted here that 
     641a successful use of these options requires appropriate mask fields to be present in the domain configuration file. 
     642Among the possibilities are: 
     643 
     644\begin{clines} 
    631645int    closea_mask          /* non-zero values in closed sea areas for optional masking                  */ 
    632646int    closea_mask_rnf      /* non-zero values in closed sea areas with runoff locations (precip only)   */ 
    633647int    closea_mask_emp      /* non-zero values in closed sea areas with runoff locations (total emp)     */ 
    634 \end{Verbatim} 
     648\end{clines} 
    635649 
    636650% ------------------------------------------------------------------------------------------------------------- 
    … …  
    642656\nlst{namcfg} 
    643657 
    644 Most of the arrays relating to a particular ocean model configuration dicussed in this 
    645 chapter (grid-point position, scale factors) can be saved in a file if namelist parameter 
    646 \np{ln\_write\_cfg} (namelist \ngn{namcfg}) is set to \forcode{.true.}; the output 
    647 filename is set thorugh parameter \np{cn\_domcfg\_out}. This is only really useful 
    648 if the fields are computed in subroutines \mdl{usrdef\_hgr} or \mdl{usrdef\_zgr} and 
     658Most of the arrays relating to a particular ocean model configuration discussed in this chapter 
     659(grid-point position, scale factors) 
     660can be saved in a file if 
     661namelist parameter \np{ln\_write\_cfg} (namelist \nam{cfg}) is set to \forcode{.true.}; 
     662the output filename is set through parameter \np{cn\_domcfg\_out}. 
     663This is only really useful if 
     664the fields are computed in subroutines \mdl{usrdef\_hgr} or \mdl{usrdef\_zgr} and 
    649665checking or confirmation is required. 
    650666 
    … …  
    652668 
    653669Alternatively, all the arrays relating to a particular ocean model configuration 
    654 (grid-point position, scale factors, depths and masks) can be saved in a file called 
    655 \texttt{mesh\_mask} if namelist parameter \np{ln\_meshmask} (namelist \ngn{namdom}) is set 
    656 to \forcode{.true.}. This file contains additional fields that can be useful for 
    657 post-processing applications 
     670(grid-point position, scale factors, depths and masks) 
     671can be saved in a file called \texttt{mesh\_mask} if 
     672namelist parameter \np{ln\_meshmask} (namelist \nam{dom}) is set to \forcode{.true.}. 
     673This file contains additional fields that can be useful for post-processing applications. 
    658674 
    659675% ================================================================ 
    … …  
    664680\label{sec:DTA_tsd} 
    665681%-----------------------------------------namtsd------------------------------------------- 
    666 \nlst{namtsd}  
     682\nlst{namtsd} 
    667683%------------------------------------------------------------------------------------------ 
    668684 
    669 Basic initial state options are defined in \ngn{namtsd}.  By default, the ocean starts 
    670 from rest (the velocity field is set to zero) and the initialization of temperature and 
    671 salinity fields is controlled through the \np{ln\_tsd\_init} namelist parameter. 
     685Basic initial state options are defined in \nam{tsd}. 
     686By default, the ocean starts from rest (the velocity field is set to zero) and 
     687the initialization of temperature and salinity fields is controlled through the \np{ln\_tsd\_init} namelist parameter. 
    672688 
    673689\begin{description} 
    674690\item[\np{ln\_tsd\_init}\forcode{= .true.}] 
    675   Use T and S input files that can be given on the model grid itself or on their native 
    676   input data grids.  In the latter case, the data will be interpolated on-the-fly both in 
    677   the horizontal and the vertical to the model grid (see \autoref{subsec:SBC_iof}).  The 
    678   information relating to the input files are specified in the \np{sn\_tem} and 
    679   \np{sn\_sal} structures.  The computation is done in the \mdl{dtatsd} module. 
     691  Use T and S input files that can be given on the model grid itself or on their native input data grids. 
     692  In the latter case, the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid 
     693  (see \autoref{subsec:SBC_iof}). 
     694  The information relating to the input files are specified in the \np{sn\_tem} and \np{sn\_sal} structures. 
     695  The computation is done in the \mdl{dtatsd} module. 
    680696\item[\np{ln\_tsd\_init}\forcode{= .false.}] 
    681   Initial values for T and S are set via a user supplied \rou{usr\_def\_istate} routine 
    682   contained in \mdl{userdef\_istate}. The default version sets horizontally uniform T and 
    683   profiles as used in the  GYRE configuration (see \autoref{sec:CFG_gyre}). 
     697  Initial values for T and S are set via a user supplied \rou{usr\_def\_istate} routine contained in \mdl{userdef\_istate}. 
     698  The default version sets horizontally uniform T and profiles as used in the GYRE configuration 
     699  (see \autoref{sec:CFG_gyre}). 
    684700\end{description} 
    685701 
Note: See TracChangeset for help on using the changeset viewer.