update text and figures

latex/NEMO/main/introduction.tex

@@ -19,7 +19,7 @@ This model has been used for a wide range of applications, both regional or glob
 as a forced ocean model and as a model coupled with the sea-ice and/or the atmosphere.
 
 This manual provides information about the physics represented by the ocean component of \NEMO\ and
-the rationale for the choice of numerical schemes and model design. There are also README files spread throughout the source code to advise users on the modelling framework.
+the rationale for the choice of numerical schemes and model design. Advice for users of the modelling framework is provided in the \href{https://sites.nemo-ocean.io/user-guide/}{NEMO User Guide}.
 
 %% =================================================================================================
 \section*{Manual outline}
@@ -41,7 +41,7 @@ Momentum equations are formulated in vector invariant or flux form.
 Dimensional units in the meter, kilogram, second (MKS) international system are used throughout.
 The following chapters deal with the discrete equations.
 \item [\nameref{chap:TD}] presents the model time stepping environment.
-it is a three level scheme in which the tendency terms of the equations are evaluated either
+It is a three level scheme in which the tendency terms of the equations are evaluated either
 centered in time, or forward, or backward depending of the nature of the term.
 \item [\nameref{chap:DOM}] presents the model \textbf{DOM}ain.
 It is discretised on a staggered grid (Arakawa C grid) with masking of land areas.

latex/NEMO/subfiles/chap_model_basics.tex

@@ -210,26 +210,12 @@ The hydrostatic pressure is then given by:
   % \label{eq:MB_pressure}
   p_h (i,j,z,t) = \int_{\varsigma = z}^{\varsigma = 0} g \; \rho (T,S,\varsigma) \; d \varsigma
 \]
-Two strategies can be considered for the surface pressure term:
-\begin{enumerate*}[label=(\textit{\alph*})]
-\item introduce of a new variable $\eta$, the free-surface elevation,
-for which a prognostic equation can be established and solved;
-\item assume that the ocean surface is a rigid lid,
-on which the pressure (or its horizontal gradient) can be diagnosed.
-\end{enumerate*}
-When the former strategy is used, one solution of the free-surface elevation consists of
-the excitation of external gravity waves.
+
+The surface pressure term is introduced via a new variable $\eta$, the free surface elevation,
+for which a prognostic equation can be established and solved. One solution of the free surface elevation consists of the excitation of external gravity waves.
 The flow is barotropic and the surface moves up and down with gravity as the restoring force.
 The phase speed of such waves is high (some hundreds of metres per second) so that
 the time step has to be very short when they are present in the model.
-The latter strategy filters out these waves since the rigid lid approximation implies $\eta = 0$,
-\ie\ the sea surface is the surface $z = 0$.
-This well known approximation increases the surface wave speed to infinity and
-modifies certain other longwave dynamics (\eg\ barotropic Rossby or planetary waves).
-The rigid-lid hypothesis is an obsolescent feature in modern OGCMs.
-It has been available until the release 3.1 of \NEMO,
-and it has been removed in release 3.2 and followings.
-Only the free surface formulation is now described in this document (see the next sub-section).
 
 %% =================================================================================================
 \subsection{Free surface formulation}
@@ -314,8 +300,8 @@ their survey of the conservation laws of fluid dynamics.
 
 Let $(i,j,k)$ be a set of orthogonal curvilinear coordinates on
 the sphere associated with the positively oriented orthogonal set of unit vectors
-$(i,j,k)$ linked to the earth such that
-$k$ is the local upward vector and $(i,j)$ are two vectors orthogonal to $k$,
+$(I,J,K)$ linked to the earth such that
+$K$ is the local upward vector and $(I,J)$ are two vectors orthogonal to $K$,
 \ie\ along geopotential surfaces (\autoref{fig:MB_referential}).
 Let $(\lambda,\varphi,z)$ be the geographical coordinate system in which a position is defined by
 the latitude $\varphi(i,j)$, the longitude $\lambda(i,j)$ and
@@ -350,7 +336,7 @@ invariant in any orthogonal horizontal curvilinear coordinate system transformat
     \label{eq:MB_grad}
     \nabla q &=   \frac{1}{e_1} \pd[q]{i} \; \vect i + \frac{1}{e_2} \pd[q]{j} \; \vect j + \frac{1}{e_3} \pd[q]{k} \; \vect k \\
     \label{eq:MB_div}
-    \nabla \cdot \vect A &=   \frac{1}{e_1 \; e_2} \lt[ \pd[(e_2 \; a_1)]{\partial i} + \pd[(e_1 \; a_2)]{j} \rt] + \frac{1}{e_3} \lt[ \pd[a_3]{k} \rt] \\
+    \nabla \cdot \vect A &=   \frac{1}{e_1 \; e_2} \lt[ \pd[(e_2 \; a_1)]{i} + \pd[(e_1 \; a_2)]{j} \rt] + \frac{1}{e_3} \lt[ \pd[a_3]{k} \rt] \\
     \label{eq:MB_curl}
       \nabla \times \vect{A} &=   \lt[ \frac{1}{e_2} \pd[a_3]{j} - \frac{1}{e_3} \pd[a_2]{k}   \rt] \vect i + \lt[ \frac{1}{e_3} \pd[a_1]{k} - \frac{1}{e_1} \pd[a_3]{i}   \rt] \vect j + \frac{1}{e_1 e_2} \lt[ \pd[(e_2 a_2)]{i} - \pd[(e_1 a_1)]{j} \rt] \vect k \\
     \label{eq:MB_lap}
@@ -533,9 +519,9 @@ are discussed in \autoref{chap:SBC}.
 \section{Curvilinear generalised vertical coordinate system}
 \label{sec:MB_gco}
 
-The ocean domain presents a huge diversity of situation in the vertical.
-First the ocean surface is a time dependent surface (moving surface).
-Second the ocean floor depends on the geographical position,
+The ocean domain presents a huge diversity of situations in the vertical.
+First, the ocean surface is a time dependent surface (moving surface).
+Second, the ocean floor depends on the geographical position,
 varying from more than 6,000 meters in abyssal trenches to zero at the coast.
 Last but not least, the ocean stratification exerts a strong barrier to vertical motions and mixing.
 Therefore, in order to represent the ocean with respect to the first point
@@ -548,7 +534,7 @@ and for the third point,
 one will be tempted to use a space and time dependent coordinate that follows the isopycnal surfaces,
 \eg\ an isopycnic coordinate.
 
-In order to satisfy two or more constraints one can even be tempted to mixed these coordinate systems,
+In order to satisfy two or more constraints one can even be tempted to mix these coordinate systems,
 as in HYCOM (mixture of $z$-coordinate at the surface, isopycnic coordinate in the ocean interior and
 $\sigma$ at the ocean bottom) \citep{chassignet.smith.ea_JPO03} or
 OPA (mixture of $z$-coordinate in vicinity the surface and steep topography areas and
@@ -575,7 +561,7 @@ The coordinate is also sometimes referenced as an adaptive coordinate
 \citep{hofmeister.burchard.ea_OM10}, since the coordinate system is adapted in
 the course of the simulation.
 Its most often used implementation is via an ALE algorithm,
-in which a pure lagrangian step is followed by regridding and remapping steps,
+in which a pure Lagrangian step is followed by regridding and remapping steps,
 the latter step implicitly embedding the vertical advection
 \citep{hirt.amsden.ea_JCP74, chassignet.smith.ea_JPO03, white.adcroft.ea_JCP09}.
 Here we follow the \citep{kasahara_MWR74} strategy:
@@ -594,13 +580,11 @@ That is, horizontal velocity is mathematically the same regardless of the vertic
 be it geopotential, isopycnal, pressure, or terrain following.
 The key motivation for maintaining the same horizontal velocity component is that
 the hydrostatic and geostrophic balances are dominant in the large-scale ocean.
-Use of an alternative quasi -horizontal velocity,
+Use of an alternative quasi-horizontal velocity,
 for example one oriented parallel to the generalized surface,
 would lead to unacceptable numerical errors.
-Correspondingly, the vertical direction is anti -parallel to the gravitational force in
-all of the coordinate systems.
-We do not choose the alternative of a quasi -vertical direction oriented normal to
-the surface of a constant generalized vertical coordinate.
+The vertical direction is a quasi-vertical direction, which is oriented normal to
+a constant level surface in the vertical coordinate system.
 
 It is the method used to measure transport across the generalized vertical coordinate surfaces which
 differs between the vertical coordinate choices.
@@ -695,13 +679,12 @@ and similar expressions are used for mixing and forcing terms.
 
 \begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{MB_z_zstar}
+  \includegraphics[width=0.33\textwidth]{MB_z_zstar}
   \caption[Curvilinear z-coordinate systems (\{non-\}linear free-surface cases and re-scaled \zstar)]{
+    Sea level high, position of the vertical levels and vertical velocities in a barotropic flow. 
     \begin{enumerate*}[label=(\textit{\alph*})]
-    \item $z$-coordinate in linear free-surface case;
-    \item $z$-coordinate in non-linear free surface case;
-    \item re-scaled height coordinate
-      (become popular as the \zstar-coordinate \citep{adcroft.campin_OM04}).
+    \item $z$-coordinate in linear free-surface case: fixed position levels and non-null vertical velocities;
+    \item re-scaled height coordinate (become popular as the \zstar-coordinate \citep{adcroft.campin_OM04}): time-varying position levels and null vertical velocities (if pure barotropic flow).
     \end{enumerate*}
   }
   \label{fig:MB_z_zstar}
@@ -723,7 +706,7 @@ as illustrated by \autoref{fig:MB_z_zstar}.
 Note that with a flat bottom, such as in \autoref{fig:MB_z_zstar},
 the bottom-following $z$ coordinate and \zstar\ are equivalent.
 The definition and modified oceanic equations for the rescaled vertical coordinate \zstar,
-including the treatment of fresh-water flux at the surface, are detailed in Adcroft and Campin (2004).
+including the treatment of fresh-water flux at the surface, are detailed in \citet{adcroft.campin_OM04}.
 The major points are summarized here.
 The position (\zstar) and vertical discretization ($\delta \zstar$) are expressed as:
 \[
@@ -886,9 +869,7 @@ It also offers a completely general transformation, $s=s(i,j,z)$ for the vertica
 \label{subsec:MB_zco_tilde}
 
 The \ztilde-coordinate has been developed by \citet{leclair.madec_OM11}.
-It is available in \NEMO\ since the version 3.4 and is more robust in version 4.0 than previously.
-Nevertheless, it is currently not robust enough to be used in all possible configurations.
-Its use is therefore not recommended.
+Available in \NEMO\ versions 3.4 to 4.2, it was not robust enough to be used in all possible configurations and its use was not recommended. The \ztilde-coordinate was temporary removed from \NEMO\ version 5.0 to be better reintroduced in a future version.
 
 %% =================================================================================================
 \section{Subgrid scale physics}
@@ -1010,10 +991,9 @@ All these parameterisations of subgrid scale physics have advantages and drawbac
 They are not all available in \NEMO.
 For active tracers (temperature and salinity) the main ones are:
 Laplacian and bilaplacian operators acting along geopotential or iso-neutral surfaces,
-\citet{gent.mcwilliams_JPO90} parameterisation, and various slightly diffusive advection schemes.
+\citet{gent.mcwilliams_JPO90} and \citet{fox-kemper.ferrari.ea_JPO08} parameterisations, and various slightly diffusive advection schemes.
 For momentum, the main ones are:
-Laplacian and bilaplacian operators acting along geopotential surfaces,
-and UBS advection schemes when flux form is chosen for the momentum advection.
+Laplacian and bilaplacian operators acting along geopotential surfaces or iso-neutral surfaces for the Laplacian, and the 2nd order centered or the 3rd order upstream-biased advection schemes when flux form is chosen for the momentum advection.
 
 %% =================================================================================================
 \subsubsection{Lateral laplacian tracer diffusive operator}
@@ -1109,6 +1089,7 @@ The lateral bilaplacian tracer diffusive operator is defined by:
 \]
 It is the Laplacian operator given by \autoref{eq:MB_iso_tensor} applied twice with
 the harmonic eddy diffusion coefficient set to the square root of the biharmonic one.
+A rotated version of the bilaplacian tracer diffusive operator is available, following the work of \citet{lemarie.debreu.ea_OM12}.
 
 %% =================================================================================================
 \subsubsection{Lateral Laplacian momentum diffusive operator}