Changeset 11512

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/main/definitions.tex

-                      r11263
+                      r11512
 %% Engine (folder name)
+%% Engine (subfolder name)
 \def \engine{NEMO}
+%% Title (variable name already use by 'titling' pkg)
+%% Title and cover page settings
+\def \spacetop{  \vspace*{1.85cm} }
 \def \heading{NEMO ocean engine}
+\def \subheading{}
+\def \spacedown{ \vspace*{0.75cm } }
+\def \authorswidth{ 0.3\linewidth}
+\def \rulelenght{270pt}
+\def \abstractwidth{0.6\linewidth}
+%% Authors (thanks will apply to the second author)
+\def \firstauthor{Gurvan Madec~}
+\def \secondauthor{NEMO System Team}
+%% Color for document (frontpage banner, links  and chapter boxes)
+\def \setcolor{ \definecolor{manualcolor}{cmyk}{1, .60, 0, .40} }
 %% IPSL publication number

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/main/foreword.tex

-                      r11263
+                      r11512
+% ================================================================
+% Foreword
+% ================================================================
+\chapter*{Foreword}
+%% ================================================================
+%% Abstract
+%% ================================================================
+The ocean engine of NEMO (Nucleus for European Modelling of the Ocean) is a primitive equation model adapted to
+regional and global ocean circulation problems.
+It is intended to be a flexible tool for studying the ocean and its interactions with the others components of
+the earth climate system over a wide range of space and time scales.
+%% Common part between NEMO-SI3-TOP
+\NEMO\ (``Nucleus for European Modelling of the Ocean'') is a framework of ocean-related engines.
+It is intended to be a flexible tool for studying the ocean dynamics and thermodynamics (``blue ocean''),
+as well as its interactions with the components of the Earth climate system over
+a wide range of space and time scales.
+Within \NEMO, the ocean engine is interfaced with a sea-ice model (\SIcube\ or
+\href{http://github.com/CICE-Consortium/CICE}{CICE}),
+passive tracers and biogeochemical models (\TOP) and,
+via the \href{http://portal.enes.org/oasis}{OASIS} coupler,
+with several atmospheric general circulation models.
+It also supports two-way grid embedding by means of the \href{http://agrif.imag.fr}{AGRIF} software.
+%% Specific part
+The primitive equation model is adapted to regional and global ocean circulation problems down to
+kilometric scale.
 Prognostic variables are the three-dimensional velocity field, a non-linear sea surface height,
 the \textit{Conservative} Temperature and the \textit{Absolute} Salinity.
+In the horizontal direction, the model uses a curvilinear orthogonal grid and in the vertical direction,
+a full or partial step $z$-coordinate, or $s$-coordinate, or a mixture of the two.
+In the horizontal direction, the model uses a curvilinear orthogonal grid and
+in the vertical direction, a full or partial step $z$-coordinate, or $s$-coordinate, or
+a mixture of the two.
 The distribution of variables is a three-dimensional Arakawa C-type grid.
+Various physical choices are available to describe ocean physics, including TKE, and GLS vertical physics.
+Within NEMO, the ocean is interfaced with a sea-ice model (SI$^3$)
+ %or \href{https://github.com/CICE-Consortium/CICE}{CICE}),
+passive tracer and biogeochemical models (TOP-PISCES) and,
+via the \href{https://portal.enes.org/oasis}{OASIS} coupler, with several atmospheric general circulation models.
+It also support two-way grid embedding via the \href{http://agrif.imag.fr}{AGRIF} software.
+Various physical choices are available to describe ocean physics,
+so as various HPC functionalities to improve performances.

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/main/thanks.tex

-                      r11263
+                      r11512
+J\'{e}r\^{o}me Chanut,
+Silvia Mocavero
+%Romain Bourdall\'{e}-Badie
+%\orcid{0000-0002-8742-3289} \\
+%Mike Bell                   \\
+%J\'{e}r\^{o}me Chanut       \\
+%Emanuela Clementi
+%\orcid{0000-0002-5752-1849} \\
+%Andrew Coward
+%\orcid{0000-0002-0456-129X} \\
+%Massimiliano Drudi
+%\orcid{0000-0002-9951-740X} \\
+%Christian \'{E}th\'{e}      \\
+%Doroteaciro Iovino
+%\orcid{0000-0001-5132-7255} \\
+%Dan Lea                     \\
+%Claire L\'{e}vy
+%\orcid{0000-0003-2518-6692} \\
+%Gurvan Madec
+%\orcid{0000-0002-6447-4198} \\
+%Nicolas Martin              \\
+%S\'{e}bastien Masson
+%\orcid{0000-0002-1694-8117} \\
+%Pierre Mathiot              \\
+%Silvia Mocavero
+%\orcid{0000-0002-6309-8282} \\
+%Simon M\"{u}ller            \\
+%George Nurser               \\
+%Guillaume Samson
+%\orcid{0000-0001-7481-6369} \\
+%Dave Storkey
+\orcid{0000-0002-8742-3289} Romain Bourdall\'{e}-Badie  \\
+                            Mike Bell                   \\
+                            J\'{e}r\^{o}me Chanut       \\
+\orcid{0000-0002-5752-1849} Emanuela Clementi           \\
+\orcid{0000-0002-0456-129X} Andrew Coward               \\
+\orcid{0000-0002-9951-740X} Massimiliano Drudi          \\
+                            Christian \'{E}th\'{e}      \\
+\orcid{0000-0001-5132-7255} Doroteaciro Iovino          \\
+                            Dan Lea                     \\
+\orcid{0000-0003-2518-6692} Claire L\'{e}vy             \\
+\orcid{0000-0002-6447-4198} Gurvan Madec                \\
+                            Nicolas Martin              \\
+\orcid{0000-0002-1694-8117} S\'{e}bastien Masson        \\
+                            Pierre Mathiot              \\
+\orcid{0000-0002-6309-8282} Silvia Mocavero             \\
+                            Simon M\"{u}ller            \\
+                            George Nurser               \\
+\orcid{0000-0001-7481-6369} Guillaume Samson            \\
+                            Dave Storkey

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/annex_A.tex

-                      r11353
+                      r11512
 \label{apdx:A}
 \minitoc
+\chaptertoc
 \vfill
 …
 In order to establish the set of Primitive Equation in curvilinear $s$-coordinates
 (\ie an orthogonal curvilinear coordinate in the horizontal and
+(\ie\ an orthogonal curvilinear coordinate in the horizontal and
 an Arbitrary Lagrangian Eulerian (ALE) coordinate in the vertical),
 we start from the set of equations established in \autoref{subsec:PE_zco_Eq} for
 …
 \]
 This leads to the $s-$coordinate formulation of the total $z-$coordinate time derivative,
 \ie the total $s-$coordinate time derivative :
+\ie\ the total $s-$coordinate time derivative :
 \begin{align}
   \label{apdx:A_sco_Dt_vect}
 …
+%
 Introducing the vertical scale factor inside the horizontal derivative of the first two terms
 (\ie the horizontal divergence), it becomes :
+(\ie\ the horizontal divergence), it becomes :
 \begin{align*}
+  {
 …
 \end{align*}
 which leads to the $s-$coordinate flux formulation of the total $s-$coordinate time derivative,
 \ie the total $s-$coordinate time derivative in flux form:
+\ie\ the total $s-$coordinate time derivative in flux form:
 \begin{flalign}
   \label{apdx:A_sco_Dt_flux}
 …
 in particular the pressure gradient.
 By contrast, $\omega$ is not $w$, the third component of the velocity, but the dia-surface velocity component,
 \ie the volume flux across the moving $s$-surfaces per unit horizontal area.
+\ie\ the volume flux across the moving $s$-surfaces per unit horizontal area.

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/annex_B.tex

r11353	r11512
8	8	\label{apdx:B}
9	9
10		\~~mini~~toc
	10	\chaptertoc
11	11
12	12	\newpage

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/annex_C.tex

-                      r10442
+                      r11512
 \label{apdx:C}
 \minitoc
+\chaptertoc
 %%%  Appendix put in gmcomment as it has not been updated for \zstar and s coordinate
 …
 $dv=e_1\,e_2\,e_3 \,di\,dj\,dk$  is the volume element, with only $e_3$ that depends on time.
 $D$ and $S$ are the ocean domain volume and surface, respectively.
 No wetting/drying is allow (\ie $\frac{\partial S}{\partial t} = 0$).
+No wetting/drying is allow (\ie\ $\frac{\partial S}{\partial t} = 0$).
 Let $k_s$ and $k_b$ be the ocean surface and bottom, resp.
 (\ie $s(k_s) = \eta$ and $s(k_b)=-H$, where $H$ is the bottom depth).
+(\ie\ $s(k_s) = \eta$ and $s(k_b)=-H$, where $H$ is the bottom depth).
 \begin{flalign*}
   z(k) = \eta - \int\limits_{\tilde{k}=k}^{\tilde{k}=k_s}  e_3(\tilde{k}) \;d\tilde{k}
 …
 \label{sec:C.1}
 The discretization of pimitive equation in $s$-coordinate (\ie time and space varying vertical coordinate)
 must be chosen so that the discrete equation of the model satisfy integral constrains on energy and enstrophy.
+The discretization of pimitive equation in $s$-coordinate (\ie\ time and space varying vertical coordinate)
+must be chosen so that the discrete equation of the model satisfy integral constrains on energy and enstrophy.
 Let us first establish those constraint in the continuous world.
 The total energy (\ie kinetic plus potential energies) is conserved:
+The total energy (\ie\ kinetic plus potential energies) is conserved:
 \begin{flalign}
   \label{eq:Tot_Energy}
 …
 \end{flalign}
 under the following assumptions: no dissipation, no forcing (wind, buoyancy flux, atmospheric pressure variations),
 mass conservation, and closed domain.
+mass conservation, and closed domain.
 This equation can be transformed to obtain several sub-equalities.
 …
 \end{subequations}
 \autoref{eq:E_tot_pg_3} is the balance between the conversion KE to PE and PE to KE.
+\autoref{eq:E_tot_pg_3} is the balance between the conversion KE to PE and PE to KE.
 Indeed the left hand side of \autoref{eq:E_tot_pg_3} can be transformed as follows:
 \begin{flalign*}
 …
   &=+  \int\limits_D g\, \rho \; w \; dv   &&&\\
 \end{flalign*}
 where the last equality is obtained by noting that the brackets is exactly the expression of $w$,
 the vertical velocity referenced to the fixe $z$-coordinate system (see \autoref{apdx:A_w_s}).
+where the last equality is obtained by noting that the brackets is exactly the expression of $w$,
+the vertical velocity referenced to the fixe $z$-coordinate system (see \autoref{apdx:A_w_s}).
 The left hand side of \autoref{eq:E_tot_pg_3} can be transformed as follows:
 \begin{flalign*}
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsubsection{Vorticity term with ENE scheme (\protect\np{ln\_dynvor\_ene}\forcode{ = .true.})}
 \label{subsec:C_vorENE}
+\label{subsec:C_vorENE}
 For the ENE scheme, the two components of the vorticity term are given by:
 …
         - \overline{ U }^{\,j+1/2}\; \overline{ V }^{\,i+1/2}         \biggr\}  \quad  \equiv 0
     \end{array}
+  }
+  }
 \end{flalign*}
 In other words, the domain averaged kinetic energy does not change due to the vorticity term.
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsubsection{Vorticity term with EEN scheme (\protect\np{ln\_dynvor\_een}\forcode{ = .true.})}
 \label{subsec:C_vorEEN_vect}
 With the EEN scheme, the vorticity terms are represented as:
+\label{subsec:C_vorEEN_vect}
+With the EEN scheme, the vorticity terms are represented as:
 \begin{equation}
   \tag{\ref{eq:dynvor_een}}
 …
       \end{aligned}
     } \right.
 \end{equation}
+\end{equation}
 where the indices $i_p$ and $j_p$ take the following value: $i_p = -1/2$ or $1/2$ and $j_p = -1/2$ or $1/2$,
 and the vorticity triads, ${^i_j}\mathbb{Q}^{i_p}_{j_p}$, defined at $T$-point, are given by:
+and the vorticity triads, ${^i_j}\mathbb{Q}^{i_p}_{j_p}$, defined at $T$-point, are given by:
 \begin{equation}
   \tag{\ref{eq:Q_triads}}
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsubsection{Gradient of kinetic energy / Vertical advection}
 \label{subsec:C_zad}
+\label{subsec:C_zad}
 The change of Kinetic Energy (KE) due to the vertical advection is exactly balanced by the change of KE due to the horizontal gradient of KE~:
 …
   +   \frac{1}{2} \int_D {  \frac{{\textbf{U}_h}^2}{e_3} \partial_t ( e_3) \;dv }
 \]
 Indeed, using successively \autoref{eq:DOM_di_adj} (\ie the skew symmetry property of the $\delta$ operator)
+Indeed, using successively \autoref{eq:DOM_di_adj} (\ie\ the skew symmetry property of the $\delta$ operator)
 and the continuity equation, then \autoref{eq:DOM_di_adj} again,
 then the commutativity of operators $\overline {\,\cdot \,}$ and $\delta$, and finally \autoref{eq:DOM_mi_adj}
 (\ie the symmetry property of the $\overline {\,\cdot \,}$ operator)
+(\ie\ the symmetry property of the $\overline {\,\cdot \,}$ operator)
 applied in the horizontal and vertical directions, it becomes:
 \begin{flalign*}
 …
       } } \right)
 \]
 a formulation that requires an additional horizontal mean in contrast with the one used in NEMO.
+a formulation that requires an additional horizontal mean in contrast with the one used in \NEMO.
 Nine velocity points have to be used instead of 3.
 This is the reason why it has not been chosen.
 …
   A pressure gradient has no contribution to the evolution of the vorticity as the curl of a gradient is zero.
   In the $z$-coordinate, this property is satisfied locally on a C-grid with 2nd order finite differences
   (property \autoref{eq:DOM_curl_grad}).
+  (property \autoref{eq:DOM_curl_grad}).
+}
 When the equation of state is linear
 (\ie when an advection-diffusion equation for density can be derived from those of temperature and salinity)
+(\ie\ when an advection-diffusion equation for density can be derived from those of temperature and salinity)
 the change of KE due to the work of pressure forces is balanced by
 the change of potential energy due to buoyancy forces:
+the change of potential energy due to buoyancy forces:
 \[
   - \int_D  \left. \nabla p \right|_z \cdot \textbf{U}_h \;dv
 …
+  %
   \allowdisplaybreaks
   \intertext{Using successively \autoref{eq:DOM_di_adj}, \ie the skew symmetry property of
+  \intertext{Using successively \autoref{eq:DOM_di_adj}, \ie\ the skew symmetry property of
     the $\delta$ operator, \autoref{eq:wzv}, the continuity equation, \autoref{eq:dynhpg_sco},
     the hydrostatic equation in the $s$-coordinate, and $\delta_{k+1/2} \left[ z_t \right] \equiv e_{3w} $,
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsubsection{Coriolis plus ``metric'' term}
 \label{subsec:C.3.3}
+\label{subsec:C.3.3}
 In flux from the vorticity term reduces to a Coriolis term in which
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsubsection{Flux form advection}
 \label{subsec:C.3.4}
+\label{subsec:C.3.4}
 The flux form operator of the momentum advection is evaluated using
 …
 Let us first consider the first term of the scalar product
 (\ie just the the terms associated with the i-component of the advection):
+(\ie\ just the the terms associated with the i-component of the advection):
 \begin{flalign*}
   &  - \int_D u \cdot \nabla \cdot \left(   \textbf{U}\,u   \right) \; dv   \\
 …
 When the UBS scheme is used to evaluate the flux form momentum advection,
 the discrete operator does not contribute to the global budget of linear momentum (flux form).
 The horizontal kinetic energy is not conserved, but forced to decay (\ie the scheme is diffusive).
+The horizontal kinetic energy is not conserved, but forced to decay (\ie\ the scheme is diffusive).
 % ================================================================
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsubsection{Vorticity term with ENS scheme  (\protect\np{ln\_dynvor\_ens}\forcode{ = .true.})}
 \label{subsec:C_vorENS}
+\label{subsec:C_vorENS}
 In the ENS scheme, the vorticity term is descretized as follows:
 …
     \end{aligned}
   \right.
 \end{equation}
+\end{equation}
 The scheme does not allow but the conservation of the total kinetic energy but the conservation of $q^2$,
 the potential enstrophy for a horizontally non-divergent flow (\ie when $\chi$=$0$).
+the potential enstrophy for a horizontally non-divergent flow (\ie\ when $\chi$=$0$).
 Indeed, using the symmetry or skew symmetry properties of the operators
 ( \autoref{eq:DOM_mi_adj} and \autoref{eq:DOM_di_adj}),
 …
+  }
 \end{flalign*}
 The later equality is obtain only when the flow is horizontally non-divergent, \ie $\chi$=$0$.
+The later equality is obtain only when the flow is horizontally non-divergent, \ie\ $\chi$=$0$.
 % -------------------------------------------------------------------------------------------------------------
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsubsection{Vorticity Term with EEN scheme (\protect\np{ln\_dynvor\_een}\forcode{ = .true.})}
 \label{subsec:C_vorEEN}
 With the EEN scheme, the vorticity terms are represented as:
+\label{subsec:C_vorEEN}
+With the EEN scheme, the vorticity terms are represented as:
 \begin{equation}
   \tag{\ref{eq:dynvor_een}}
 …
       \end{aligned}
     } \right.
 \end{equation}
 where the indices $i_p$ and $k_p$ take the following values:
+\end{equation}
+where the indices $i_p$ and $k_p$ take the following values:
 $i_p = -1/2$ or $1/2$ and $j_p = -1/2$ or $1/2$,
 and the vorticity triads, ${^i_j}\mathbb{Q}^{i_p}_{j_p}$, defined at $T$-point, are given by:
+and the vorticity triads, ${^i_j}\mathbb{Q}^{i_p}_{j_p}$, defined at $T$-point, are given by:
 \begin{equation}
   \tag{\ref{eq:Q_triads}}
 …
 \end{equation}
 This formulation does conserve the potential enstrophy for a horizontally non-divergent flow (\ie $\chi=0$).
+This formulation does conserve the potential enstrophy for a horizontally non-divergent flow (\ie\ $\chi=0$).
 Let consider one of the vorticity triad, for example ${^{i}_j}\mathbb{Q}^{+1/2}_{+1/2} $,
 …
 \label{sec:C.5}
 All the numerical schemes used in NEMO are written such that the tracer content is conserved by
+All the numerical schemes used in \NEMO\ are written such that the tracer content is conserved by
 the internal dynamics and physics (equations in flux form).
 For advection,
 only the CEN2 scheme (\ie $2^{nd}$ order finite different scheme) conserves the global variance of tracer.
+only the CEN2 scheme (\ie\ $2^{nd}$ order finite different scheme) conserves the global variance of tracer.
 Nevertheless the other schemes ensure that the global variance decreases
 (\ie they are at least slightly diffusive).
+(\ie\ they are at least slightly diffusive).
 For diffusion, all the schemes ensure the decrease of the total tracer variance, except the iso-neutral operator.
 There is generally no strict conservation of mass,
 as the equation of state is non linear with respect to $T$ and $S$.
 In practice, the mass is conserved to a very high accuracy.
+In practice, the mass is conserved to a very high accuracy.
 % -------------------------------------------------------------------------------------------------------------
 %       Advection Term
 …
 Indeed, let $T$ be the tracer and its $\tau_u$, $\tau_v$, and $\tau_w$ interpolated values at velocity point
 (whatever the interpolation is),
 the conservation of the tracer content due to the advection tendency is obtained as follows:
+the conservation of the tracer content due to the advection tendency is obtained as follows:
 \begin{flalign*}
   &\int_D { \frac{1}{e_3}\frac{\partial \left( e_3 \, T \right)}{\partial t} \;dv } = - \int_D \nabla \cdot \left( T \textbf{U} \right)\;dv    &&&\\
 …
 The conservation of the variance of tracer due to the advection tendency can be achieved only with the CEN2 scheme,
 \ie when $\tau_u= \overline T^{\,i+1/2}$, $\tau_v= \overline T^{\,j+1/2}$, and $\tau_w= \overline T^{\,k+1/2}$.
+\ie\ when $\tau_u= \overline T^{\,i+1/2}$, $\tau_v= \overline T^{\,j+1/2}$, and $\tau_w= \overline T^{\,k+1/2}$.
 It can be demonstarted as follows:
 \begin{flalign*}
 …
 the conservation of potential vorticity and the horizontal divergence,
 and the dissipation of the square of these quantities
 (\ie enstrophy and the variance of the horizontal divergence) as well as
+(\ie\ enstrophy and the variance of the horizontal divergence) as well as
 the dissipation of the horizontal kinetic energy.
 In particular, when the eddy coefficients are horizontally uniform,
 it ensures a complete separation of vorticity and horizontal divergence fields,
 so that diffusion (dissipation) of vorticity (enstrophy) does not generate horizontal divergence
 (variance of the horizontal divergence) and \textit{vice versa}.
+(variance of the horizontal divergence) and \textit{vice versa}.
 These properties of the horizontal diffusion operator are a direct consequence of
 properties \autoref{eq:DOM_curl_grad} and \autoref{eq:DOM_div_curl}.
 When the vertical curl of the horizontal diffusion of momentum (discrete sense) is taken,
 the term associated with the horizontal gradient of the divergence is locally zero.
+the term associated with the horizontal gradient of the divergence is locally zero.
 % -------------------------------------------------------------------------------------------------------------
 …
 When the horizontal divergence of the horizontal diffusion of momentum (discrete sense) is taken,
 the term associated with the vertical curl of the vorticity is zero locally, due to \autoref{eq:DOM_div_curl}.
+the term associated with the vertical curl of the vorticity is zero locally, due to \autoref{eq:DOM_div_curl}.
 The resulting term conserves the $\chi$ and dissipates $\chi^2$ when the eddy coefficients are horizontally uniform.
 \begin{flalign*}
 …
     \left( \frac{A^{\,vm}} {e_3 }\; \frac{\partial \textbf{U}_h } {\partial k} \right) \right)\; dv = 0    &&&
 \end{flalign*}
 and the square of the horizontal divergence decreases (\ie the horizontal divergence is dissipated) if
+and the square of the horizontal divergence decreases (\ie\ the horizontal divergence is dissipated) if
 the vertical diffusion coefficient is uniform over the whole domain:
 …
 the heat and salt contents are conserved (equations in flux form).
 Since a flux form is used to compute the temperature and salinity,
 the quadratic form of these quantities (\ie their variance) globally tends to diminish.
 As for the advection term, there is conservation of mass only if the Equation Of Seawater is linear.
+the quadratic form of these quantities (\ie\ their variance) globally tends to diminish.
+As for the advection term, there is conservation of mass only if the Equation Of Seawater is linear.
 % -------------------------------------------------------------------------------------------------------------
 …
 \end{flalign*}
 In fact, this property simply results from the flux form of the operator.
+In fact, this property simply results from the flux form of the operator.
 % -------------------------------------------------------------------------------------------------------------

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/annex_DOMAINcfg.tex

-                      r11353
+                      r11512
 \label{apdx:DOMAINcfg}
 \minitoc
+\chaptertoc
 \vfill
 \begin{figure}[b]
 …
 This tool will evolve into an independent utility with its own documentation but its
 current manifestation is mostly a wrapper for \NEMO \forcode{DOM} modules more aligned to
 those in the previous versions of NEMO. These versions allowed the user to define some
+current manifestation is mostly a wrapper for \NEMO\ \forcode{DOM} modules more aligned to
+those in the previous versions of \NEMO. These versions allowed the user to define some
 horizontal and vertical grids through additional namelist parameters. Explanations of
 these parameters are retained here for reference pending better documentation for
 …
 those read by \forcode{DOMAINcfg} via its own \forcode{namelist_ref} and
 \forcode{namelist_cfg} files. Although, due to their origins, these namelists share names
 with those used by NEMO, they are not interchangeable and should be considered independent
+with those used by \NEMO, they are not interchangeable and should be considered independent
 of those described elsewhere in this manual.
 …
 %--------------------------------------------namdom-------------------------------------------------------
 \nlst{namdom_domcfg}
+\nlst{namdom_domcfg}
 %--------------------------------------------------------------------------------------------------------------
 The user has three options available in defining a horizontal grid, which involve the
 namelist variable \np{jphgr\_mesh} of the \ngn{namdom} (\forcode{DOMAINcfg} variant only)
+namelist variable \np{jphgr\_mesh} of the \nam{dom} (\texttt{DOMAINcfg} variant only)
 namelist.
 …
   The coordinates and their first derivatives with respect to $i$ and $j$ are provided
   in a input file (\ifile{coordinates}), read in \rou{hgr\_read} subroutine of the domhgr module.
   This is now the only option available within \NEMO itself from v4.0 onwards.
 \item[\np{jphgr\_mesh}=1 to 5] A few simple analytical grids are provided (see below).
   For other analytical grids, the \textit{domhgr.f90} module (\forcode{DOMAINcfg} variant) must be
   modified by the user. In most cases, modifying the \mdl{usrdef\_hgr} module of \NEMO is
   a better alternative since this is designed to allow simple analytical domains to be
+  This is now the only option available within \NEMO\ itself from v4.0 onwards.
+\item[\np{jphgr\_mesh}=1 to 5] A few simple analytical grids are provided (see below).
+  For other analytical grids, the \mdl{domhgr} module (\texttt{DOMAINcfg} variant) must be
+  modified by the user. In most cases, modifying the \mdl{usrdef\_hgr} module of \NEMO\ is
+  a better alternative since this is designed to allow simple analytical domains to be
   configured and used without the need for external data files.
 \end{description}
 There are two simple cases of geographical grids on the sphere. With
 \np{jphgr\_mesh}=1, the grid (expressed in degrees) is regular in space,
 with grid sizes specified by parameters \np{ppe1\_deg} and \np{ppe2\_deg},
 respectively. Such a geographical grid can be very anisotropic at high latitudes
 because of the convergence of meridians (the zonal scale factors $e_1$
 become much smaller than the meridional scale factors $e_2$). The Mercator
 grid (\np{jphgr\_mesh}=4) avoids this anisotropy by refining the meridional scale
 factors in the same way as the zonal ones. In this case, meridional scale factors
 and latitudes are calculated analytically using the formulae appropriate for
 a Mercator projection, based on \np{ppe1\_deg} which is a reference grid spacing
 at the equator (this applies even when the geographical equator is situated outside
 the model domain).
 In these two cases (\np{jphgr\_mesh}=1 or 4), the grid position is defined by the
 longitude and latitude of the south-westernmost point (\np{ppglamt0}
 and \np{ppgphi0}). Note that for the Mercator grid the user need only provide
 an approximate starting latitude: the real latitude will be recalculated analytically,
 in order to ensure that the equator corresponds to line passing through $t$-
 and $u$-points.
 Rectangular grids ignoring the spherical geometry are defined with
 \np{jphgr\_mesh} = 2, 3, 5. The domain is either an $f$-plane (\np{jphgr\_mesh} = 2,
 Coriolis factor is constant) or a beta-plane (\np{jphgr\_mesh} = 3, the Coriolis factor
 is linear in the $j$-direction). The grid size is uniform in meter in each direction,
 and given by the parameters \np{ppe1\_m} and \np{ppe2\_m} respectively.
 The zonal grid coordinate (\textit{glam} arrays) is in kilometers, starting at zero
 with the first $t$-point. The meridional coordinate (gphi. arrays) is in kilometers,
 and the second $t$-point corresponds to coordinate $gphit=0$. The input
 variable \np{ppglam0} is ignored. \np{ppgphi0} is used to set the reference
 latitude for computation of the Coriolis parameter. In the case of the beta plane,
 \np{ppgphi0} corresponds to the center of the domain. Finally, the special case
 \np{jphgr\_mesh}=5 corresponds to a beta plane in a rotated domain for the
 GYRE configuration, representing a classical mid-latitude double gyre system.
 The rotation allows us to maximize the jet length relative to the gyre areas
 (and the number of grid points).
+There are two simple cases of geographical grids on the sphere. With
+\np{jphgr\_mesh}=1, the grid (expressed in degrees) is regular in space,
+with grid sizes specified by parameters \np{ppe1\_deg} and \np{ppe2\_deg},
+respectively. Such a geographical grid can be very anisotropic at high latitudes
+because of the convergence of meridians (the zonal scale factors $e_1$
+become much smaller than the meridional scale factors $e_2$). The Mercator
+grid (\np{jphgr\_mesh}=4) avoids this anisotropy by refining the meridional scale
+factors in the same way as the zonal ones. In this case, meridional scale factors
+and latitudes are calculated analytically using the formulae appropriate for
+a Mercator projection, based on \np{ppe1\_deg} which is a reference grid spacing
+at the equator (this applies even when the geographical equator is situated outside
+the model domain).
+In these two cases (\np{jphgr\_mesh}=1 or 4), the grid position is defined by the
+longitude and latitude of the south-westernmost point (\np{ppglamt0}
+and \np{ppgphi0}). Note that for the Mercator grid the user need only provide
+an approximate starting latitude: the real latitude will be recalculated analytically,
+in order to ensure that the equator corresponds to line passing through $t$-
+and $u$-points.
+Rectangular grids ignoring the spherical geometry are defined with
+\np{jphgr\_mesh} = 2, 3, 5. The domain is either an $f$-plane (\np{jphgr\_mesh} = 2,
+Coriolis factor is constant) or a beta-plane (\np{jphgr\_mesh} = 3, the Coriolis factor
+is linear in the $j$-direction). The grid size is uniform in meter in each direction,
+and given by the parameters \np{ppe1\_m} and \np{ppe2\_m} respectively.
+The zonal grid coordinate (\textit{glam} arrays) is in kilometers, starting at zero
+with the first $t$-point. The meridional coordinate (gphi. arrays) is in kilometers,
+and the second $t$-point corresponds to coordinate $gphit=0$. The input
+variable \np{ppglam0} is ignored. \np{ppgphi0} is used to set the reference
+latitude for computation of the Coriolis parameter. In the case of the beta plane,
+\np{ppgphi0} corresponds to the center of the domain. Finally, the special case
+\np{jphgr\_mesh}=5 corresponds to a beta plane in a rotated domain for the
+GYRE configuration, representing a classical mid-latitude double gyre system.
+The rotation allows us to maximize the jet length relative to the gyre areas
+(and the number of grid points).
 % -------------------------------------------------------------------------------------------------------------
 …
 the vertical scale factors.  The user must provide the analytical expression of both $z_0$
 and its first derivative with respect to $k$.  This is done in routine \mdl{domzgr}
 through statement functions, using parameters provided in the \ngn{namdom} namelist
 (\forcode{DOMAINcfg} variant).
+through statement functions, using parameters provided in the \nam{dom} namelist
+(\texttt{DOMAINcfg} variant).
 It is possible to define a simple regular vertical grid by giving zero stretching
 …
     \begin{split}
     z_0  (k) = h_{sur} - h_0 \; k &- \; h_1 \; \log  \big[ \cosh ((k - h_{th}) / h_{cr}) \big] \\
                              \;   &- \; h2_1 \; \log  \big[ \cosh ((k - h2_{th}) / h2_{cr}) \big]
+                             \;   &- \; h2_1 \; \log  \big[ \cosh ((k - h2_{th}) / h2_{cr}) \big]
     \end{split}
 \end{gather}
 …
 \end{equation}
 This formulation decreases the self-generated circulation into the ice shelf cavity
+This formulation decreases the self-generated circulation into the ice shelf cavity
 (which can, in extreme case, leads to numerical instability). This is now the recommended formulation for all configurations using v4.0 onwards. The analytical derivation of thicknesses is maintained for backwards compatibility.
 …
 The resulting depths and scale factors as a function of the model levels are shown in
 \autoref{fig:DOMCFG_zgr} and given in \autoref{tab:DOMCFG_orca_zgr}.
 Those values correspond to the parameters \np{ppsur}, \np{ppa0}, \np{ppa1}, \np{ppkth} in \ngn{namcfg} namelist.
+Those values correspond to the parameters \np{ppsur}, \np{ppa0}, \np{ppa1}, \np{ppkth} in \nam{cfg} namelist.
 Rather than entering parameters $h_{sur}$, $h_0$, and $h_1$ directly, it is possible to
 recalculate them.  In that case the user sets \np{ppsur}~$=$~\np{ppa0}~$=$~\np{ppa1}~$=
 $., in \ngn{namcfg} namelist, and specifies instead the four following parameters:
+$., in \nam{cfg} namelist, and specifies instead the four following parameters:
 \begin{itemize}
 \item
 …
 Three options are possible for defining the bathymetry, according to the namelist variable
 \np{nn\_bathy} (found in \ngn{namdom} namelist (\forcode{DOMAINCFG} variant) ):
+\np{nn\_bathy} (found in \nam{dom} namelist (\texttt{DOMAINCFG} variant) ):
 \begin{description}
 \item[\np{nn\_bathy}\forcode{ = 0}]:
 …
   The \ifile{bathy\_meter} file (Netcdf format) provides the ocean depth (positive, in meters) at
   each grid point of the model grid.
   The bathymetry is usually built by interpolating a standard bathymetry product (\eg ETOPO2) onto
+  The bathymetry is usually built by interpolating a standard bathymetry product (\eg\ ETOPO2) onto
   the horizontal ocean mesh.
   Defining the bathymetry also defines the coastline: where the bathymetry is zero,
 …
 \end{description}
 %%%
 % -------------------------------------------------------------------------------------------------------------
 %        z-coordinate with constant thickness
 …
 thickness than $e_{3t}(jpk)$: the maximum thickness allowed is $2*e_{3t}(jpk - 1)$.
 This has to be kept in mind when specifying values in \ngn{namdom} namelist
 (\forcode{DOMMAINCFG} variant), such as the maximum depth \np{pphmax} in partial steps.
+This has to be kept in mind when specifying values in \nam{dom} namelist
+(\texttt{DOMAINCFG} variant), such as the maximum depth \np{pphmax} in partial steps.
 For example, with \np{pphmax}~$= 5750~m$ for the DRAKKAR 45 layer grid, the maximum ocean
 …
 %------------------------------------------nam_zgr_sco---------------------------------------------------
+%
 \nlst{namzgr_sco_domcfg}
+\nlst{namzgr_sco_domcfg}
 %--------------------------------------------------------------------------------------------------------------
 Options are defined in \ngn{namzgr\_sco} (\forcode{DOMAINcfg} only).
+Options are defined in \nam{zgr\_sco} (\texttt{DOMAINcfg} only).
 In $s$-coordinate (\np{ln\_sco}\forcode{ = .true.}), the depth and thickness of the model levels are defined from
 the product of a depth field and either a stretching function or its derivative, respectively:
 …
 but care must be taken to ensure that the vertical stretch used is appropriate for the application.
 The original default NEMO s-coordinate stretching is available if neither of the other options are specified as true
+The original default \NEMO\ s-coordinate stretching is available if neither of the other options are specified as true
 (\np{ln\_s\_SH94}\forcode{ = .false.} and \np{ln\_s\_SF12}\forcode{ = .false.}).
 This uses a depth independent $\tanh$ function for the stretching \citep{madec.delecluse.ea_JPO96}:
 …
 \label{subsec:DOMCFG_zgr_star}
 This option is described in the Report by Levier \textit{et al.} (2007), available on the \NEMO web site.
+This option is described in the Report by Levier \textit{et al.} (2007), available on the \NEMO\ web site.
 \biblio

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/annex_E.tex

-                      r11263
+                      r11512
 \label{apdx:E}
 \minitoc
+\chaptertoc
 \newpage
 …
 $\tau "_i =\frac{e_{1T}}{e_{2T}\,e_{3T}}\delta_i \left[ \frac{e_{2u} e_{3u} }{e_{1u} }\delta_{i+1/2}[\tau] \right]$.
 This results in a dissipatively dominant (\ie hyper-diffusive) truncation error
+This results in a dissipatively dominant (\ie\ hyper-diffusive) truncation error
 \citep{shchepetkin.mcwilliams_OM05}.
 The overall performance of the advection scheme is similar to that reported in \cite{farrow.stevens_JPO95}.
 …
 \end{equation}
 with ${A_u^{lT}}^2 = \frac{1}{12} {e_{1u}}^3\ |u|$,
 \ie $A_u^{lT} = \frac{1}{\sqrt{12}} \,e_{1u}\ \sqrt{ e_{1u}\,|u|\,}$
+\ie\ $A_u^{lT} = \frac{1}{\sqrt{12}} \,e_{1u}\ \sqrt{ e_{1u}\,|u|\,}$
 it comes:
 \begin{equation}
 …
   \end{split}
 \end{equation}
 if the velocity is uniform (\ie $|u|=cst$) then the diffusive flux is
+if the velocity is uniform (\ie\ $|u|=cst$) then the diffusive flux is
 \begin{equation}
   \label{eq:tra_ldf_lap}
 …
   \end{split}
 \end{equation}
 if the velocity is uniform (\ie $|u|=cst$) and
+if the velocity is uniform (\ie\ $|u|=cst$) and
 choosing $\tau "_i =\frac{e_{1T}}{e_{2T}\,e_{3T}}\delta_i \left[ \frac{e_{2u} e_{3u} }{e_{1u} } \delta_{i+1/2}[\tau] \right]$
 …
 not $2\rdt$ as it can be found sometimes in literature.
 The leap-Frog time stepping is a second order centered scheme.
 As such it respects the quadratic invariant in integral forms, \ie the following continuous property,
+As such it respects the quadratic invariant in integral forms, \ie\ the following continuous property,
 \[
   % \label{eq:Energy}
 …
 Let try to define a scheme that get its inspiration from the \citet{griffies.gnanadesikan.ea_JPO98} scheme,
 but is formulated within the \NEMO framework
 (\ie using scale factors rather than grid-size and having a position of $T$-points that
+but is formulated within the \NEMO\ framework
+(\ie\ using scale factors rather than grid-size and having a position of $T$-points that
 is not necessary in the middle of vertical velocity points, see \autoref{fig:zgr_e3}).
 …
 (see \autoref{chap:LDF}).
 Nevertheless, this technique works fine for $T$ and $S$ as they are active tracers
 (\ie they enter the computation of density), but it does not work for a passive tracer.
+(\ie\ they enter the computation of density), but it does not work for a passive tracer.
 \citep{griffies.gnanadesikan.ea_JPO98} introduce a different way to discretise the off-diagonal terms that
 nicely solve the problem.
 …
 \item[$\bullet$ implicit treatment in the vertical]
   In the diagonal term associated with the vertical divergence of the iso-neutral fluxes
   \ie the term associated with a second order vertical derivative)
+  \ie\ the term associated with a second order vertical derivative)
   appears only tracer values associated with a single water column.
   This is of paramount importance since it means that
 …
 It is a key property for a diffusion term.
 It means that the operator is also a dissipation term,
 \ie it is a sink term for the square of the quantity on which it is applied.
+\ie\ it is a sink term for the square of the quantity on which it is applied.
 It therfore ensures that, when the diffusivity coefficient is large enough,
 the field on which it is applied become free of grid-point noise.
 …
 the formulation of which depends on the slopes of iso-neutral surfaces.
 Contrary to the case of iso-neutral mixing, the slopes used here are referenced to the geopotential surfaces,
 \ie \autoref{eq:ldfslp_geo} is used in $z$-coordinate,
+\ie\ \autoref{eq:ldfslp_geo} is used in $z$-coordinate,
 and the sum \autoref{eq:ldfslp_geo} + \autoref{eq:ldfslp_iso} in $z^*$ or $s$-coordinates.
 …
 Nevertheless this property can be used to choose a discret form of \autoref{eq:eiv_skew_continuous} which
 is consistent with the iso-neutral operator \autoref{eq:Gf_operator}.
 Using the slopes \autoref{eq:Gf_slopes} and defining $A_e$ at $T$-point(\ie as $A$,
+Using the slopes \autoref{eq:Gf_slopes} and defining $A_e$ at $T$-point(\ie\ as $A$,
 the eddy diffusivity coefficient), the resulting discret form is given by:
 \begin{equation}
 …
 it uses the same definition for the slopes.
 It also ensures the conservation of the tracer variance (see Appendix \autoref{apdx:eiv_skew}),
 \ie it does not include a diffusive component but is a "pure" advection term.
+\ie\ it does not include a diffusive component but is a "pure" advection term.
 $\ $\newpage      %force an empty line
 …
 Exactly the same thing occurs for the triad ${_i^k \mathbb{R}_{-1/2}^{+1/2}}$ in the $i$ direction.
 Therefore the sum over the domain is zero,
 \ie the variance of the tracer is preserved by the discretisation of the skew fluxes.
+\ie\ the variance of the tracer is preserved by the discretisation of the skew fluxes.
 \biblio

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/annex_iso.tex

-                      r11263
+                      r11512
 \label{apdx:triad}
 \minitoc
+\chaptertoc
 \newpage
+\section{Choice of \protect\ngn{namtra\_ldf} namelist parameters}
+\section[Choice of \texttt{namtra\_ldf} namelist parameters]
+{Choice of \protect\nam{tra\_ldf} namelist parameters}
 %-----------------------------------------nam_traldf------------------------------------------------------
 …
 Two scheme are available to perform the iso-neutral diffusion.
 If the namelist logical \np{ln\_traldf\_triad} is set true,
 \NEMO updates both active and passive tracers using the Griffies triad representation of iso-neutral diffusion and
+\NEMO\ updates both active and passive tracers using the Griffies triad representation of iso-neutral diffusion and
 the eddy-induced advective skew (GM) fluxes.
 If the namelist logical \np{ln\_traldf\_iso} is set true,
 …
 Values of iso-neutral diffusivity and GM coefficient are set as described in \autoref{sec:LDF_coef}.
 Note that when GM fluxes are used, the eddy-advective (GM) velocities are output for diagnostic purposes using xIOS,
+Note that when GM fluxes are used, the eddy-advective (GM) velocities are output for diagnostic purposes using XIOS,
 even though the eddy advection is accomplished by means of the skew fluxes.
 …
 \label{sec:iso}
 We have implemented into \NEMO a scheme inspired by \citet{griffies.gnanadesikan.ea_JPO98},
 but formulated within the \NEMO framework, using scale factors rather than grid-sizes.
+We have implemented into \NEMO\ a scheme inspired by \citet{griffies.gnanadesikan.ea_JPO98},
+but formulated within the \NEMO\ framework, using scale factors rather than grid-sizes.
 \subsection{Iso-neutral diffusion operator}
 …
 To correct this, we introduced a smoothing of the slopes of the iso-neutral surfaces (see \autoref{chap:LDF}).
 This technique works for $T$ and $S$ in so far as they are active tracers
 (\ie they enter the computation of density), but it does not work for a passive tracer.
+(\ie\ they enter the computation of density), but it does not work for a passive tracer.
 \subsection{Expression of the skew-flux in terms of triad slopes}
 …
 the intersection of the $i,k$ $T$-cell, the $i+i_p,k$ $u$-cell and the $i,k+k_p$ $w$-cell.
 Expressing the slopes $s_i$ and $s'_i$ in \autoref{eq:i13} and \autoref{eq:i31} in this notation,
 we have \eg \ $s_1=s'_1={\:}_i^k \mathbb{R}_{1/2}^{1/2}$.
+we have \eg\ \ $s_1=s'_1={\:}_i^k \mathbb{R}_{1/2}^{1/2}$.
 Each triad slope $_i^k\mathbb{R}_{i_p}^{k_p}$ is used once (as an $s$) to
 calculate the lateral flux along its $u$-arm, at $(i+i_p,k)$,
 …
 and we notate these areas, similarly to the triad slopes,
 as $_i^k{\mathbb{A}_u}_{i_p}^{k_p}$, $_i^k{\mathbb{A}_w}_{i_p}^{k_p}$,
 where \eg in \autoref{eq:i13} $a_{1}={\:}_i^k{\mathbb{A}_u}_{1/2}^{1/2}$,
+where \eg\ in \autoref{eq:i13} $a_{1}={\:}_i^k{\mathbb{A}_u}_{1/2}^{1/2}$,
 and in \autoref{eq:i31} $a'_{1}={\:}_i^k{\mathbb{A}_w}_{1/2}^{1/2}$.
 …
 defined in terms of the distances between $T$, $u$,$f$ and $w$-points.
 This is the natural discretization of \autoref{eq:cts-var}.
 The \NEMO model, however, operates with scale factors instead of grid sizes,
+The \NEMO\ model, however, operates with scale factors instead of grid sizes,
 and scale factors for the quarter cells are not defined.
 Instead, therefore we simply choose
 …
   It is a key property for a diffusion term.
   It means that it is also a dissipation term,
   \ie it dissipates the square of the quantity on which it is applied.
+  \ie\ it dissipates the square of the quantity on which it is applied.
   It therefore ensures that, when the diffusivity coefficient is large enough,
   the field on which it is applied becomes free of grid-point noise.
 …
 Similar comments apply to triads that would intersect the ocean floor (\autoref{fig:bdry_triads}b).
 Note that both near bottom triad slopes \triad{i}{k}{R}{1/2}{1/2} and \triad{i+1}{k}{R}{-1/2}{1/2} are masked when
 either of the $i,k+1$ or $i+1,k+1$ tracer points is masked, \ie the $i,k+1$ $u$-point is masked.
+either of the $i,k+1$ or $i+1,k+1$ tracer points is masked, \ie\ the $i,k+1$ $u$-point is masked.
 The associated lateral fluxes (grey-black dashed line) are masked if \np{ln\_botmix\_triad}\forcode{ = .false.},
 but left unmasked, giving bottom mixing, if \np{ln\_botmix\_triad}\forcode{ = .true.}.
 The default option \np{ln\_botmix\_triad}\forcode{ = .false.} is suitable when the bbl mixing option is enabled
 (\key{trabbl}, with \np{nn\_bbl\_ldf}\forcode{ = 1}), or for simple idealized problems.
+(\np{ln\_trabbl}\forcode{ = .true.}, with \np{nn\_bbl\_ldf}\forcode{ = 1}), or for simple idealized problems.
 For setups with topography without bbl mixing, \np{ln\_botmix\_triad}\forcode{ = .true.} may be necessary.
 % >>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
       (b) Both near bottom triad slopes \triad{i}{k}{R}{1/2}{1/2} and
       \triad{i+1}{k}{R}{-1/2}{1/2} are masked when either of the $i,k+1$ or $i+1,k+1$ tracer points is masked,
       \ie the $i,k+1$ $u$-point is masked.
+      \ie\ the $i,k+1$ $u$-point is masked.
       The associated lateral fluxes (grey-black dashed line) are masked if
       \protect\np{botmix\_triad}\forcode{ = .false.}, but left unmasked,
       giving bottom mixing, if \protect\np{botmix\_triad}\forcode{ = .true.}
+      \protect\np{ln\_botmix\_triad}\forcode{ = .false.}, but left unmasked,
+      giving bottom mixing, if \protect\np{ln\_botmix\_triad}\forcode{ = .true.}
+    }
   \end{center}
 …
 iso-neutral slopes relative to geopotentials must be bounded everywhere,
 both for consistency with the small-slope approximation and for numerical stability \citep{cox_OM87, griffies_bk04}.
 The bound chosen in \NEMO is applied to each component of the slope separately and
+The bound chosen in \NEMO\ is applied to each component of the slope separately and
 has a value of $1/100$ in the ocean interior.
 %, ramping linearly down above 70~m depth to zero at the surface
 …
   where $i,k_{10}$ is the tracer gridbox within which the depth reaches 10~m.
   See the left side of \autoref{fig:MLB_triad}.
   We use the $k_{10}$-gridbox instead of the surface gridbox to avoid problems \eg with thin daytime mixed-layers.
+  We use the $k_{10}$-gridbox instead of the surface gridbox to avoid problems \eg\ with thin daytime mixed-layers.
   Currently we use the same $\Delta\rho_c=0.01\;\mathrm{kg\:m^{-3}}$ for ML triad tapering as is used to
   output the diagnosed mixed-layer depth $h_{\mathrm{ML}}=|z_{W}|_{k_{\mathrm{ML}}+1/2}$,
 …
                                                        % \label{eq:Rbase}
     \\
     \intertext{with \eg the green triad}
+    \intertext{with \eg\ the green triad}
     {\:}_i{\mathbb{R}_{\mathrm{base}}}_{1/2}^{-1/2}&=
                                                      {\:}^{k_{\mathrm{ML}}}_i{\mathbb{R}_{\mathrm{base}}}_{\,1/2}^{-1/2}.
 …
     ${\:}_i{\mathbb{R}_{\mathrm{base}}}_{\,i_p}^{k_p}$.
     Triads with different $i_p,k_p$, denoted by different colours,
     (\eg the green triad $i_p=1/2,k_p=-1/2$) are tapered to the appropriate basal triad.}
+    (\eg\ the green triad $i_p=1/2,k_p=-1/2$) are tapered to the appropriate basal triad.}
   % }
   \includegraphics[width=\textwidth]{Fig_GRIFF_MLB_triads}
 …
 the formulation of which depends on the slopes of iso-neutral surfaces.
 Contrary to the case of iso-neutral mixing, the slopes used here are referenced to the geopotential surfaces,
 \ie \autoref{eq:ldfslp_geo} is used in $z$-coordinate,
+\ie\ \autoref{eq:ldfslp_geo} is used in $z$-coordinate,
 and the sum \autoref{eq:ldfslp_geo} + \autoref{eq:ldfslp_iso} in $z^*$ or $s$-coordinates.
 …
 The traditional way to implement this additional advection is to add it to the Eulerian velocity prior to
 computing the tracer advection.
 This is implemented if \key{traldf\_eiv} is set in the default implementation,
+This is implemented if \texttt{traldf\_eiv?} is set in the default implementation,
 where \np{ln\_traldf\_triad} is set false.
 This allows us to take advantage of all the advection schemes offered for the tracers
 …
 However, when \np{ln\_traldf\_triad} is set true,
 \NEMO instead implements eddy induced advection according to the so-called skew form \citep{griffies_JPO98}.
+\NEMO\ instead implements eddy induced advection according to the so-called skew form \citep{griffies_JPO98}.
 It is based on a transformation of the advective fluxes using the non-divergent nature of the eddy induced velocity.
 For example in the (\textbf{i},\textbf{k}) plane,
 …
 \subsubsection{No change in tracer variance}
 The discretization conserves tracer variance, \ie it does not include a diffusive component but is a `pure' advection term.
+The discretization conserves tracer variance, \ie\ it does not include a diffusive component but is a `pure' advection term.
 This can be seen %either from Appendix \autoref{apdx:eiv_skew} or
 by considering the fluxes associated with a given triad slope $_i^k{\mathbb{R}}_{i_p}^{k_p} (T)$.
 …
 Thus surface layer triads $\triadt{i}{1}{R}{1/2}{-1/2}$ and $\triadt{i+1}{1}{R}{-1/2}{-1/2}$ are masked,
 and both near bottom triad slopes $\triadt{i}{k}{R}{1/2}{1/2}$ and $\triadt{i+1}{k}{R}{-1/2}{1/2}$ are masked when
 either of the $i,k+1$ or $i+1,k+1$ tracer points is masked, \ie the $i,k+1$ $u$-point is masked.
+either of the $i,k+1$ or $i+1,k+1$ tracer points is masked, \ie\ the $i,k+1$ $u$-point is masked.
 The namelist parameter \np{ln\_botmix\_triad} has no effect on the eddy-induced skew-fluxes.

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_ASM.tex

-                      r11353
+                      r11512
 \label{chap:ASM}
 \minitoc
+\chaptertoc
 \vfill
 …
 \begin{tabular}{l||l|m{0.65\linewidth}}
     Release   & Author        & Modifications \\
     {\em 4.0} & {\em D. J. Lea} & {\em \NEMO 4.0 updates}  \\
+    {\em 4.0} & {\em D. J. Lea} & {\em \NEMO\ 4.0 updates}  \\
     {\em 3.4} & {\em D. J. Lea, M. Martin, K. Mogensen, A. Weaver} & {\em Initial version}  \\
 \end{tabular}
 …
 These are read into the model from a NetCDF file which may be produced by separate data assimilation code.
 The code can also output model background fields which are used as an input to data assimilation code.
 This is all controlled by the namelist \textit{\ngn{nam\_asminc} }.
+This is all controlled by the namelist \nam{\_asminc}.
 There is a brief description of all the namelist options provided.
 To build the ASM code \key{asminc} must be set.
 …
 It is quite challenging for data assimilation systems to provide non-divergent velocity increments.
 Applying divergent velocity increments will likely cause spurious vertical velocities in the model. This section describes a method to take velocity increments provided to \NEMO ($u^0_I$ and $v^0_I$) and adjust them by the iterative application of a divergence damping operator. The method is also described in \citet{dobricic.pinardi.ea_OS07}.
+Applying divergent velocity increments will likely cause spurious vertical velocities in the model. This section describes a method to take velocity increments provided to \NEMO\ ($u^0_I$ and $v^0_I$) and adjust them by the iterative application of a divergence damping operator. The method is also described in \citet{dobricic.pinardi.ea_OS07}.
 In iteration step $n$ (starting at $n=1$) new estimates of velocity increments $u^{n}_I$ and $v^{n}_I$ are updated by:
 …
 \citep{talagrand_JAS72, dobricic.pinardi.ea_OS07}.
 Diffusion coefficients are defined as $A_D = \alpha e_{1t} e_{2t}$, where $\alpha = 0.2$.
 The divergence damping is activated by assigning to \np{nn\_divdmp} in the \textit{nam\_asminc} namelist
+The divergence damping is activated by assigning to \np{nn\_divdmp} in the \nam{\_asminc} namelist
 a value greater than zero.
 This specifies the number of iterations of the divergence damping. Setting a value of the order of 100 will result in a significant reduction in the vertical velocity induced by the increments.
 …
 \label{sec:ASM_details}
 Here we show an example \ngn{nam\_asminc} namelist and the header of an example assimilation increments file on
+Here we show an example \nam{\_asminc} namelist and the header of an example assimilation increments file on
 the ORCA2 grid.

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_CONFIG.tex

-                      r11263
+                      r11512
 \label{chap:CFG}
 \minitoc
+\chaptertoc
 \newpage
 …
 \label{sec:CFG_intro}
 The purpose of this part of the manual is to introduce the NEMO reference configurations.
+The purpose of this part of the manual is to introduce the \NEMO\ reference configurations.
 These configurations are offered as means to explore various numerical and physical options,
 thus allowing the user to verify that the code is performing in a manner consistent with that we are running.
 …
 The reference configurations also provide a sense for some of the options available in the code,
 though by no means are all options exercised in the reference configurations.
 Configuration is defined manually through the \textit{namcfg} namelist variables.
+Configuration is defined manually through the \nam{cfg} namelist variables.
 %------------------------------------------namcfg----------------------------------------------------
 …
 \label{sec:CFG_c1d}
 The 1D model option simulates a stand alone water column within the 3D NEMO system.
+The 1D model option simulates a stand alone water column within the 3D \NEMO\ system.
 It can be applied to the ocean alone or to the ocean-ice system and can include passive tracers or a biogeochemical model.
 It is set up by defining the position of the 1D water column in the grid
 (see \textit{cfgs/SHARED/namelist\_ref}).
+(see \path{./cfgs/SHARED/namelist\_ref}).
 The 1D model is a very useful tool
 \textit{(a)} to learn about the physics and numerical treatment of vertical mixing processes;
 …
 The 1D model has some specifies. First, all the horizontal derivatives are assumed to be zero,
 and second, the two components of the velocity are moved on a $T$-point.
 Therefore, defining \key{c1d} changes some things in the code behaviour:
+and second, the two components of the velocity are moved on a $T$-point.
+Therefore, defining \key{c1d} changes some things in the code behaviour:
 \begin{description}
 \item[(1)]
 …
 \end{description}
 All the relevant \textit{\_c1d} modules can be found in the src/OCE/C1D directory of
 the NEMO distribution.
+the \NEMO\ distribution.
 % to be added:  a test case on the yearlong Ocean Weather Station (OWS) Papa dataset of Martin (1985)
 …
 The ORCA family is a series of global ocean configurations that are run together with
 the SI3 model (ORCA-ICE) and possibly with PISCES biogeochemical model (ORCA-ICE-PISCES).
 An appropriate namelist is available in \path{cfgs/ORCA2_ICE_PISCES/EXPREF/namelist_cfg} for ORCA2.
+An appropriate namelist is available in \path{./cfgs/ORCA2_ICE_PISCES/EXPREF/namelist_cfg} for ORCA2.
 The domain of ORCA2 configuration is defined in \ifile{ORCA\_R2\_zps\_domcfg} file,
 this file is available in tar file on the NEMO community zenodo platform: \\
+this file is available in tar file on the \NEMO\ community zenodo platform: \\
 https://doi.org/10.5281/zenodo.2640723
 In this namelist\_cfg the name of domain input file is set in \ngn{namcfg} block of namelist.
+In this namelist\_cfg the name of domain input file is set in \nam{cfg} block of namelist.
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 (\autoref{fig:MISC_ORCA_msh}).
 The resulting mesh presents no loss of continuity in either the mesh lines or the scale factors,
 or even the scale factor derivatives over the whole ocean domain, as the mesh is not a composite mesh.
+or even the scale factor derivatives over the whole ocean domain, as the mesh is not a composite mesh.
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!tbp]
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 The method is applied to Mercator grid (\ie same zonal and meridional grid spacing) poleward of 20\deg{N},
+The method is applied to Mercator grid (\ie\ same zonal and meridional grid spacing) poleward of 20\deg{N},
 so that the Equator is a mesh line, which provides a better numerical solution for equatorial dynamics.
 The choice of the series of embedded ellipses (position of the foci and variation of the ellipses)
 …
 a half a degree grid (ORCA\_R05).
 The smallest ocean scale factor is found in along Antarctica,
 while the ratio of anisotropy remains close to one except near the Victoria Island in the Canadian Archipelago.
+while the ratio of anisotropy remains close to one except near the Victoria Island in the Canadian Archipelago.
 % -------------------------------------------------------------------------------------------------------------
 …
 \label{subsec:CFG_orca_resolution}
 The NEMO system is provided with five built-in ORCA configurations which differ in the horizontal resolution.
+The \NEMO\ system is provided with five built-in ORCA configurations which differ in the horizontal resolution.
 The value of the resolution is given by the resolution at the Equator expressed in degrees.
 Each of configuration is set through the \textit{domain\_cfg} domain configuration file,
 which sets the grid size and configuration name parameters.
 The NEMO System Team provides only ORCA2 domain input file "\ifile{ORCA\_R2\_zps\_domcfg}" file
 (Tab. \autoref{tab:ORCA}).
+The \NEMO\ System Team provides only ORCA2 domain input file "\ifile{ORCA\_R2\_zps\_domcfg}" file
+(\autoref{tab:ORCA}).
 %--------------------------------------------------TABLE--------------------------------------------------
 …
   \begin{center}
     \begin{tabular}{p{4cm} c c c c}
+      Horizontal Grid                         & \np{ORCA\_index} &  \np{jpiglo} & \np{jpjglo} &       \\
+      \hline
+      \hline
+      \~4\deg     &        4         &         92     &      76      &       \\
+      \~2\deg        &        2         &       182     &    149      &        \\
+      \~1\deg        &        1         &       362     &     292     &        \\
+      \~0.5\deg     &        05       &       722     &     511     &        \\
+      \~0.25\deg   &        025     &      1442    &   1021     &        \\
+      % \key{orca\_r8}       &        8         &      2882    &   2042     &        \\
+      % \key{orca\_r12}     &      12         &      4322    &   3062      &       \\
+      \hline
+      \hline
+      Horizontal Grid & \jp{ORCA\_index} & \jp{jpiglo} & \jp{jpjglo} \\
+      \hline \hline
+%             4   \deg &              4   &          92 &          76 \\
+   \deg &              2   &         182 &         149 \\
+   \deg &              1   &         362 &         292 \\
+.5 \deg &              05  &         722 &         511 \\
+.25\deg &              025 &        1442 &        1021 \\
+      \hline \hline
     \end{tabular}
     \caption{
 …
 Note that the tropical mesh refinements in ORCA\_R2 and R1 strongly increases the mesh anisotropy there.
 The ORCA\_R05 and higher global configurations do not incorporate any regional refinements.
+The ORCA\_R05 and higher global configurations do not incorporate any regional refinements.
 For ORCA\_R1 and R025, setting the configuration key to 75 allows to use 75 vertical levels, otherwise 46 are used.
 …
 (see \autoref{tab:orca_zgr}). %\sfcomment{HERE I need to put new table for ORCA2 values} and \autoref{fig:zgr}).
 Only the ORCA\_R2 is provided with all its input files in the NEMO distribution.
+Only the ORCA\_R2 is provided with all its input files in the \NEMO\ distribution.
 %It is very similar to that used as part of the climate model developed at IPSL for the 4th IPCC assessment of
 %climate change (Marti et al., 2009).
 %It is also the basis for the \NEMO contribution to the Coordinate Ocean-ice Reference Experiments (COREs)
 %documented in \citet{griffies.biastoch.ea_OM09}.
+%It is also the basis for the \NEMO\ contribution to the Coordinate Ocean-ice Reference Experiments (COREs)
+%documented in \citet{griffies.biastoch.ea_OM09}.
 This version of ORCA\_R2 has 31 levels in the vertical, with the highest resolution (10m) in the upper 150m
 (see \autoref{tab:orca_zgr} and \autoref{fig:zgr}).
 The bottom topography and the coastlines are derived from the global atlas of Smith and Sandwell (1997).
 The default forcing uses the boundary forcing from \citet{large.yeager_rpt04} (see \autoref{subsec:SBC_blk_core}),
+(see \autoref{tab:orca_zgr} and \autoref{fig:zgr}).
+The bottom topography and the coastlines are derived from the global atlas of Smith and Sandwell (1997).
+The default forcing uses the boundary forcing from \citet{large.yeager_rpt04} (see \autoref{subsec:SBC_blk_core}),
 which was developed for the purpose of running global coupled ocean-ice simulations without
 an interactive atmosphere.
 This \citet{large.yeager_rpt04} dataset is available through
 the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/CORE.html}{GFDL web site}.
+The "normal year" of \citet{large.yeager_rpt04} has been chosen of the NEMO distribution since release v3.3.
+ORCA\_R2 pre-defined configuration can also be run with multiply online nested zooms (\ie with AGRIF, \key{agrif} defined). This is available as the AGRIF\_DEMO configuration that can be found in the \path{cfgs/AGRIF_DEMO/} directory.
+The "normal year" of \citet{large.yeager_rpt04} has been chosen of the \NEMO\ distribution since release v3.3.
+ORCA\_R2 pre-defined configuration can also be run with multiply online nested zooms (\ie\ with AGRIF, \key{agrif} defined).
+This is available as the AGRIF\_DEMO configuration that can be found in the \path{./cfgs/AGRIF_DEMO/} directory.
 A regional Arctic or peri-Antarctic configuration is extracted from an ORCA\_R2 or R05 configurations using
 sponge layers at open boundaries.
+sponge layers at open boundaries.
 % -------------------------------------------------------------------------------------------------------------
 …
 \citet{hazeleger.drijfhout_JPO98, hazeleger.drijfhout_JPO99, hazeleger.drijfhout_JGR00, hazeleger.drijfhout_JPO00},
 over which an analytical seasonal forcing is applied.
 This allows to investigate the spontaneous generation of a large number of interacting, transient mesoscale eddies
 and their contribution to the large scale circulation.
+This allows to investigate the spontaneous generation of a large number of interacting, transient mesoscale eddies
+and their contribution to the large scale circulation.
 The GYRE configuration run together with the PISCES biogeochemical model (GYRE-PISCES).
 …
 The configuration is meant to represent an idealized North Atlantic or North Pacific basin.
 The circulation is forced by analytical profiles of wind and buoyancy fluxes.
 The applied forcings vary seasonally in a sinusoidal manner between winter and summer extrema \citep{levy.klein.ea_OM10}.
+The applied forcings vary seasonally in a sinusoidal manner between winter and summer extrema \citep{levy.klein.ea_OM10}.
 The wind stress is zonal and its curl changes sign at 22\deg{N} and 36\deg{N}.
 It forces a subpolar gyre in the north, a subtropical gyre in the wider part of the domain and
 …
 The GYRE configuration is set like an analytical configuration.
 Through \np{ln\_read\_cfg}\forcode{ = .false.} in \textit{namcfg} namelist defined in
 the reference configuration \path{cfgs/GYRE_PISCES/EXPREF/namelist_cfg}
+Through \np{ln\_read\_cfg}\forcode{ = .false.} in \nam{cfg} namelist defined in
+the reference configuration \path{./cfgs/GYRE_PISCES/EXPREF/namelist_cfg}
 analytical definition of grid in GYRE is done in usrdef\_hrg, usrdef\_zgr routines.
 Its horizontal resolution (and thus the size of the domain) is determined by
 setting \np{nn\_GYRE} in \ngn{namusr\_def}: \\
 \np{jpiglo} $= 30 \times$ \np{nn\_GYRE} + 2   \\
 \np{jpjglo} $= 20 \times$ \np{nn\_GYRE} + 2   \\
+setting \np{nn\_GYRE} in \nam{usr\_def}: \\
+\jp{jpiglo} $= 30 \times$ \np{nn\_GYRE} + 2   \\
+\jp{jpjglo} $= 20 \times$ \np{nn\_GYRE} + 2   \\
 Obviously, the namelist parameters have to be adjusted to the chosen resolution,
 see the Configurations pages on the NEMO web site (NEMO Configurations).
+see the Configurations pages on the \NEMO\ web site (\NEMO\ Configurations).
 In the vertical, GYRE uses the default 30 ocean levels (\jp{jpk}\forcode{ = 31}) (\autoref{fig:zgr}).
 …
 For example, keeping a same model size on each processor while increasing the number of processor used is very easy,
 even though the physical integrity of the solution can be compromised.
 Benchmark is activate via \np{ln\_bench}\forcode{ = .true.} in \ngn{namusr\_def} in
 namelist \path{cfgs/GYRE_PISCES/EXPREF/namelist_cfg}.
+Benchmark is activate via \np{ln\_bench}\forcode{ = .true.} in \nam{usr\_def} in
+namelist \path{./cfgs/GYRE_PISCES/EXPREF/namelist_cfg}.
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 The AMM, Atlantic Margins Model, is a regional model covering the Northwest European Shelf domain on
 a regular lat-lon grid at approximately 12km horizontal resolution.
 The appropriate \textit{\&namcfg} namelist  is available in \textit{cfgs/AMM12/EXPREF/namelist\_cfg}.
+The appropriate \textit{\&namcfg} namelist  is available in \path{./cfgs/AMM12/EXPREF/namelist\_cfg}.
 It is used to build the correct dimensions of the AMM domain.
 This configuration tests several features of NEMO functionality specific to the shelf seas.
+This configuration tests several features of \NEMO\ functionality specific to the shelf seas.
 In particular, the AMM uses $s$-coordinates in the vertical rather than $z$-coordinates and
 is forced with tidal lateral boundary conditions using a Flather boundary condition from the BDY module.

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_DIA.tex

-                      r11366
+                      r11512
 \label{chap:DIA}
 \minitoc
+\chaptertoc
 \vfill
 …
     {\em }      & {\em Dorotea Iovino, Nicolas Martin} & {\em }  \\
     {\em 3.6} & {\em Gurvan Madec, Sebastien Masson } & {\em }  \\
     {\em 3.4} & {\em Gurvan Madec, Rachid Benshila, Andrew Coward } & {\em }  \\
     {\em }      & {\em Christian Ethe, Sebastien Masson } & {\em }  \\
+    {\em 3.4} & {\em Gurvan Madec, Rachid Benshila, Andrew Coward } & {\em }  \\
+    {\em }      & {\em Christian Ethe, Sebastien Masson } & {\em }  \\
 \end{tabular}
 \end{figure}
+\end{figure}
 \newpage
 % ================================================================
 %       Old Model Output
+%       Old Model Output
 % ================================================================
 \section{Model output}
 …
 The output listing and file(s) are predefined but should be checked and eventually adapted to the user's needs.
 The output listing is stored in the $ocean.output$ file.
 The information is printed from within the code on the logical unit $numout$.
+The output listing is stored in the \textit{ocean.output} file.
+The information is printed from within the code on the logical unit \texttt{numout}.
 To locate these prints, use the UNIX command "\textit{grep -i numout}" in the source code directory.
 …
 \label{sec:DIA_iom}
 Since version 3.2, iomput is the NEMO output interface of choice.
+Since version 3.2, iomput is the \NEMO\ output interface of choice.
 It has been designed to be simple to use, flexible and efficient.
 The two main purposes of iomput are:
+The two main purposes of iomput are:
 \begin{enumerate}
 …
 \end{enumerate}
 The first functionality allows the user to specify, without code changes or recompilation,
+The first functionality allows the user to specify, without code changes or recompilation,
 aspects of the diagnostic output stream, such as:
 …
 in a very easy way.
 All details of iomput functionalities are listed in the following subsections.
 Examples of the XML files that control the outputs can be found in:
+Examples of the XML files that control the outputs can be found in:
 \path{cfgs/ORCA2_ICE_PISCES/EXPREF/iodef.xml},
 \path{cfgs/SHARED/field_def_nemo-oce.xml},
 …
 The second functionality targets output performance when running in parallel (\key{mpp\_mpi}).
 Iomput provides the possibility to specify N dedicated I/O processes (in addition to the NEMO processes)
+Iomput provides the possibility to specify N dedicated I/O processes (in addition to the \NEMO\ processes)
 to collect and write the outputs.
 With an appropriate choice of N by the user, the bottleneck associated with the writing of
 the output files can be greatly reduced.
 In version 3.6, the iom\_put interface depends on
 an external code called \href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/branchs/xios-2.5}{XIOS-2.5}
 (use of revision 618 or higher is required).
+In version 3.6, the \rou{iom\_put} interface depends on
+an external code called \href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/branchs/xios-2.5}{XIOS-2.5}
+%(use of revision 618 or higher is required).
 This new IO server can take advantage of the parallel I/O functionality of NetCDF4 to
 create a single output file and therefore to bypass the rebuilding phase.
 Note that writing in parallel into the same NetCDF files requires that your NetCDF4 library is linked to
 an HDF5 library that has been correctly compiled (\ie with the configure option $--$enable-parallel).
+an HDF5 library that has been correctly compiled (\ie\ with the configure option $--$enable-parallel).
 Note that the files created by iomput through XIOS are incompatible with NetCDF3.
 All post-processsing and visualization tools must therefore be compatible with NetCDF4 and not only NetCDF3.
 Even if not using the parallel I/O functionality of NetCDF4, using N dedicated I/O servers,
 where N is typically much less than the number of NEMO processors, will reduce the number of output files created.
 This can greatly reduce the post-processing burden usually associated with using large numbers of NEMO processors.
+where N is typically much less than the number of \NEMO\ processors, will reduce the number of output files created.
+This can greatly reduce the post-processing burden usually associated with using large numbers of \NEMO\ processors.
 Note that for smaller configurations, the rebuilding phase can be avoided,
 even without a parallel-enabled NetCDF4 library, simply by employing only one dedicated I/O server.
 …
 \subsection{XIOS: Reading and writing restart file}
 XIOS may be used to read single file restart produced by NEMO. Currently only the variables written to
+XIOS may be used to read single file restart produced by \NEMO. Currently only the variables written to
 file \forcode{numror} can be handled by XIOS. To activate restart reading using XIOS, set \np{ln\_xios\_read}\forcode{ = .true. }
 in \textit{namelist\_cfg}. This setting will be ignored when multiple restart files are present, and default NEMO
 functionality will be used for reading. There is no need to change iodef.xml file to use XIOS to read
 restart, all definitions are done within the NEMO code. For high resolution configuration, however,
+in \textit{namelist\_cfg}. This setting will be ignored when multiple restart files are present, and default \NEMO
+functionality will be used for reading. There is no need to change iodef.xml file to use XIOS to read
+restart, all definitions are done within the \NEMO\ code. For high resolution configuration, however,
 there may be a need to add the following line in iodef.xml (xios context):
 …
 \end{xmllines}
 This variable sets timeout for reading.
 If XIOS is to be used to read restart from file generated with an earlier NEMO version (3.6 for instance),
+This variable sets timeout for reading.
+If XIOS is to be used to read restart from file generated with an earlier \NEMO\ version (3.6 for instance),
 dimension \forcode{z} defined in restart file must be renamed to \forcode{nav_lev}.\\
 XIOS can also be used to write NEMO restart. A namelist parameter \np{nn\_wxios} is used to determine the
 type of restart NEMO will write. If it is set to 0, default NEMO functionality will be used - each
 processor writes its own restart file; if it is set to 1 XIOS will write restart into a single file;
 for \np{nn\_wxios = 2} the restart will be written by XIOS into multiple files, one for each XIOS server.
 Note, however, that \textbf{NEMO will not read restart generated by XIOS when \np{nn\_wxios = 2}}. The restart will
 have to be rebuild before continuing the run. This option aims to reduce number of restart files generated by NEMO only,
 and may be useful when there is a need to change number of processors used to run simulation.
+XIOS can also be used to write \NEMO\ restart. A namelist parameter \np{nn\_wxios} is used to determine the
+type of restart \NEMO\ will write. If it is set to 0, default \NEMO\ functionality will be used - each
+processor writes its own restart file; if it is set to 1 XIOS will write restart into a single file;
+for \np{nn\_wxios}\forcode{ = 2} the restart will be written by XIOS into multiple files, one for each XIOS server.
+Note, however, that \textbf{\NEMO\ will not read restart generated by XIOS when \np{nn\_wxios}\forcode{ = 2}}. The restart will
+have to be rebuild before continuing the run. This option aims to reduce number of restart files generated by \NEMO\ only,
+and may be useful when there is a need to change number of processors used to run simulation.
 If an additional variable must be written to a restart file, the following steps are needed:
 \begin{description}
    \item[step 1:] add variable name to a list of restart variables (in subroutine \rou{iom\_set\_rst\_vars,} \mdl{iom}) and
 define correct grid for the variable (\forcode{grid_N_3D} - 3D variable, \forcode{grid_N} - 2D variable, \forcode{grid_vector} -
+   \item[step 1:] add variable name to a list of restart variables (in subroutine \rou{iom\_set\_rst\_vars,} \mdl{iom}) and
+define correct grid for the variable (\forcode{grid_N_3D} - 3D variable, \forcode{grid_N} - 2D variable, \forcode{grid_vector} -
 D variable, \forcode{grid_scalar} - scalar),
    \item[step 2:] add variable to the list of fields written by restart.  This can be done either in subroutine
 \rou{iom\_set\_rstw\_core} (\mdl{iom}) or by calling  \rou{iom\_set\_rstw\_active} (\mdl{iom}) with the name of a variable
 as an argument. This convention follows approach for writing restart using iom, where variables are
+   \item[step 2:] add variable to the list of fields written by restart.  This can be done either in subroutine
+\rou{iom\_set\_rstw\_core} (\mdl{iom}) or by calling  \rou{iom\_set\_rstw\_active} (\mdl{iom}) with the name of a variable
+as an argument. This convention follows approach for writing restart using iom, where variables are
 written either by \rou{rst\_write} or by calling \rou{iom\_rstput} from individual routines.
 \end{description}
 …
 In \textit{attached mode} and if the type of file is ''multiple\_file'',
 then each NEMO process will also act as an IO server and produce its own set of output files.
+then each \NEMO\ process will also act as an IO server and produce its own set of output files.
 Superficially, this emulates the standard behaviour in previous versions.
 However, the subdomain written out by each process does not correspond to
 …
 write to its own set of output files.
 If the ''one\_file'' option is chosen then all XIOS processes will collect their longitudinal strips and
 write (in parallel) to a single output file.
+write (in parallel) to a single output file.
 Note running in detached mode requires launching a Multiple Process Multiple Data (MPMD) parallel job.
 The following subsection provides a typical example but the syntax will vary in different MPP environments.
 …
 The number of cores used by the XIOS is specified when launching the model.
 The number of cores dedicated to XIOS should be from \texttildelow1/10 to \texttildelow1/50 of the number of
 cores dedicated to NEMO.
+The number of cores dedicated to XIOS should be from \texttildelow1/10 to \texttildelow1/50 of the number of
+cores dedicated to \NEMO.
 Some manufacturers suggest using O($\sqrt{N}$) dedicated IO processors for N processors but
 this is a general recommendation and not specific to NEMO.
+this is a general recommendation and not specific to \NEMO.
 It is difficult to provide precise recommendations because the optimal choice will depend on
 the particular hardware properties of the target system
+the particular hardware properties of the target system
 (parallel filesystem performance, available memory, memory bandwidth etc.)
 and the volume and frequency of data to be created.
 …
 \subsubsection{Control of XIOS: the context in iodef.xml}
+As well as the {\ttfamily using\_server} flag, other controls on the use of XIOS are set in the XIOS context in iodef.xml.
+As well as the \texttt{using\_server} flag, other controls on the use of XIOS are set in
+the XIOS context in \textit{iodef.xml}.
 See the XML basics section below for more details on XML syntax and rules.
 …
     \hline
     buffer\_size                                                            &
     buffer size used by XIOS to send data from NEMO to XIOS.
+    buffer size used by XIOS to send data from \NEMO\ to XIOS.
     Larger is more efficient.
     Note that needed/used buffer sizes are summarized at the end of the job &
 …
     \hline
     buffer\_server\_factor\_size                                            &
     ratio between NEMO and XIOS buffer size.
+    ratio between \NEMO\ and XIOS buffer size.
     Should be 2.                                                            &
         \\
 …
     \hline
     oasis\_codes\_id                                                        &
     when using oasis, define the identifier of NEMO in the namcouple.
+    when using oasis, define the identifier of \NEMO\ in the namcouple.
     Note that the identifier of XIOS is xios.x                              &
     oceanx   \\
 …
 \subsubsection{Installation}
 As mentioned, XIOS is supported separately and must be downloaded and compiled before it can be used with NEMO.
+As mentioned, XIOS is supported separately and must be downloaded and compiled before it can be used with \NEMO.
 See the installation guide on the \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS} wiki for help and guidance.
 NEMO will need to link to the compiled XIOS library.
+\NEMO\ will need to link to the compiled XIOS library.
 The \href{https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/guide/html/install.html#extract-and-install-xios}
 {Extract and install XIOS} guide provides an example illustration of how this can be achieved.
 …
 \begin{enumerate}
 \item[1.]
   in NEMO code, add a \forcode{CALL iom_put( 'identifier', array )} where you want to output a 2D or 3D array.
+  in \NEMO\ code, add a \forcode{CALL iom_put( 'identifier', array )} where you want to output a 2D or 3D array.
 \item[2.]
   If necessary, add \forcode{USE iom ! I/O manager library} to the list of used modules in
 …
    <field_group id="grid_T" grid_ref="grid_T_3D"> <!-- T grid -->
    ...
       <field id="identifier" long_name="blabla" ... />
+      <field id="identifier" long_name="blabla" ... />
       ...
 </field_definition>
+</field_definition>
 \end{xmllines}
 …
 \begin{xmllines}
 <file id="file1" .../>
+<file id="file1" .../>
 ...
    <field field_ref="identifier" />
+   <field field_ref="identifier" />
    ...
 </file>
+</file>
 \end{xmllines}
 …
 See \href{http://www.xmlnews.org/docs/xml-basics.html}{here} for more details.
 \subsubsection{Structure of the XML file used in NEMO}
+\subsubsection{Structure of the XML file used in \NEMO}
 The XML file used in XIOS is structured by 7 families of tags:
 …
                                                                                                      \xmlcode{<context id="xios" ... >}   \\
     \hline
     context nemo    &   context containing IO information for NEMO (mother grid when using AGRIF)  &
+    context nemo    &   context containing IO information for \NEMO\ (mother grid when using AGRIF)  &
                                                                                                      \xmlcode{<context id="nemo" ... >}   \\
     \hline
     context 1\_nemo &   context containing IO information for NEMO child grid 1 (when using AGRIF) &
+    context 1\_nemo &   context containing IO information for \NEMO\ child grid 1 (when using AGRIF) &
                                                                                                      \xmlcode{<context id="1_nemo" ... >} \\
     \hline
     context n\_nemo &   context containing IO information for NEMO child grid n (when using AGRIF) &
+    context n\_nemo &   context containing IO information for \NEMO\ child grid n (when using AGRIF) &
                                                                                                      \xmlcode{<context id="n_nemo" ... >} \\
     \hline
 …
 \end{table}
 \noindent Each context tag related to NEMO (mother or child grids) is divided into 5 parts
+\noindent Each context tag related to \NEMO\ (mother or child grids) is divided into 5 parts
 (that can be defined in any order):
 …
 The inclusion of XML files into the main XML file can be done through the attribute src:
 \xmlline|<context src="./nemo_def.xml" />|
 \noindent In NEMO, by default, the field definition is done in 3 separate files (
+\noindent In \NEMO, by default, the field definition is done in 3 separate files (
 \path{cfgs/SHARED/field_def_nemo-oce.xml},
 \path{cfgs/SHARED/field_def_nemo-pisces.xml} and
 …
 are included in the main iodef.xml file through the following commands:
 \begin{xmllines}
 <context id="nemo" src="./context_nemo.xml"/>
+<context id="nemo" src="./context_nemo.xml"/>
 \end{xmllines}
 …
 \begin{xmllines}
 <field_definition operation="average" >
    <field id="sst"                    />   <!-- averaged      sst -->
    <field id="sss" operation="instant"/>   <!-- instantaneous sss -->
 </field_definition>
+   <field id="sst"                    />   <!-- averaged      sst -->
+   <field id="sss" operation="instant"/>   <!-- instantaneous sss -->
+</field_definition>
 \end{xmllines}
 …
 </field_definition>
 <file_definition>
    <file id="myfile" output_freq="1d" />
+   <file id="myfile" output_freq="1d" />
       <field field_ref="sst"                            />  <!-- default def -->
       <field field_ref="sss" long_name="my description" />  <!-- overwrite   -->
    </file>
 </file_definition>
+</file_definition>
 \end{xmllines}
 …
    <field_group group_ref="groupU" />
    <field field_ref="uocetr_eff"   />  <!-- add another field -->
 </file>
+</file>
 \end{xmllines}
 …
 Horizontal subdomains are defined through the attributs zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj of
 the tag family domain.
 It must therefore be done in the domain part of the XML file.
 For example, in \path{cfgs/SHARED/domain_def.xml}, we provide the following example of a definition of
+It must therefore be done in the domain part of the XML file.
+For example, in \path{cfgs/SHARED/domain_def.xml}, we provide the following example of a definition of
 a 5 by 5 box with the bottom left corner at point (10,10).
 …
 \end{xmllines}
 Moorings are seen as an extrem case corresponding to a 1 by 1 subdomain.
+Moorings are seen as an extrem case corresponding to a 1 by 1 subdomain.
 The Equatorial section, the TAO, RAMA and PIRATA moorings are already registered in the code and
 can therefore be outputted without taking care of their (i,j) position in the grid.
 …
 \end{xmllines}
 Note that if the domain decomposition used in XIOS cuts the subdomain in several parts and if
 you use the ''multiple\_file'' type for your output files,
 you will endup with several files you will need to rebuild using unprovided tools (like ncpdq and ncrcat,
+Note that if the domain decomposition used in XIOS cuts the subdomain in several parts and if
+you use the ''multiple\_file'' type for your output files,
+you will endup with several files you will need to rebuild using unprovided tools (like ncpdq and ncrcat,
 \href{http://nco.sourceforge.net/nco.html#Concatenation}{see nco manual}).
 We are therefore advising to use the ''one\_file'' type in this case.
 …
 \begin{xmllines}
 <file_group id="1d" output_freq="1d" name="myfile_1d" >
+<file_group id="1d" output_freq="1d" name="myfile_1d" >
    <file id="myfileA" name_suffix="_AAA" > <!-- will create file "myfile_1d_AAA"  -->
       ...
 …
 \end{table}
 \noindent For example,
+\noindent For example,
 \xmlline|<file id="myfile_hzoom" name="myfile_@expname@_@startdate@_freq@freq@" output_freq="1d" >|
 …
 \noindent will give the following file name radical: \ifile{myfile\_ORCA2\_19891231\_freq1d}
 \subsubsection{Other controls of the XML attributes from NEMO}
 The values of some attributes are defined by subroutine calls within NEMO
+\subsubsection{Other controls of the XML attributes from \NEMO}
+The values of some attributes are defined by subroutine calls within \NEMO
 (calls to iom\_set\_domain\_attr, iom\_set\_axis\_attr and iom\_set\_field\_attr in \mdl{iom}).
 Any definition given in the XML file will be overwritten.
 …
 \end{xmllines}
 Note that, then the code is crashing, writting real4 variables forces a numerical conversion from
+Note that, then the code is crashing, writting real4 variables forces a numerical conversion from
 real8 to real4 which will create an internal error in NetCDF and will avoid the creation of the output files.
 Forcing double precision outputs with prec="8" (for example in the field\_definition) will avoid this problem.
 …
 \begin{xmllines}
 <file_group id="1d" output_freq="1d" output_level="10" enabled=".true."> <!-- 1d files -->
+<file_group id="1d" output_freq="1d" output_level="10" enabled=".true."> <!-- 1d files -->
    <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
       <field field_ref="sst" name="tos" >
 …
       <variable id="my_global_attribute" type="string" > blabla_global </variable>
    </file>
 </file_group>
+</file_group>
 \end{xmllines}
 …
 \begin{xmllines}
 <file_group id="5d" output_freq="5d"  output_level="10" enabled=".true." >  <!-- 5d files -->
+<file_group id="5d" output_freq="5d"  output_level="10" enabled=".true." >  <!-- 5d files -->
    <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
       <field field_ref="toce" operation="instant" freq_op="5d" > @toce_e3t / @e3t </field>
    </file>
 </file_group>
+</file_group>
 \end{xmllines}
 …
 \begin{xmllines}
 <file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files -->
+<file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files -->
    <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
       <field field_ref="ssh" name="sshstd" long_name="sea_surface_temperature_standard_deviation"
+      <field field_ref="ssh" name="sshstd" long_name="sea_surface_temperature_standard_deviation"
       operation="instant" freq_op="1m" >
          sqrt( @ssh2 - @ssh * @ssh )
       </field>
    </file>
 </file_group>
+</file_group>
 \end{xmllines}
 …
 here we use the default, average.
 So, in the above case, @ssh2 will do the monthly mean of ssh*ssh.
 Operation="instant" refers to the temporal operation to be performed on the field ''sqrt( @ssh2 - @ssh * @ssh )'':
+Operation="instant" refers to the temporal operation to be performed on the field ''sqrt( @ssh2 - @ssh * @ssh )'':
 here the temporal average is alreday done by the ``@'' function so we just use instant.
 field\_ref="ssh" means that attributes not explicitely defined, are inherited from ssh field.
 …
 \begin{xmllines}
 <file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files -->
+<file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files -->
    <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
       <field field_ref="sst" name="sstdcy" long_name="amplitude of sst diurnal cycle" operation="average" freq_op="1d" >
 …
       </field>
    </file>
 </file_group>
+</file_group>
 \end{xmllines}
 …
 \subsection{CF metadata standard compliance}
 Output from the XIOS IO server is compliant with
+Output from the XIOS IO server is compliant with
 \href{http://cfconventions.org/Data/cf-conventions/cf-conventions-1.5/build/cf-conventions.html}{version 1.5} of
 the CF metadata standard.
+the CF metadata standard.
 Therefore while a user may wish to add their own metadata to the output files (as demonstrated in example 4 of
 section \autoref{subsec:IOM_xmlref}) the metadata should, for the most part, comply with the CF-1.5 standard.
 Some metadata that may significantly increase the file size (horizontal cell areas and vertices) are controlled by
 the namelist parameter \np{ln\_cfmeta} in the \ngn{namrun} namelist.
+the namelist parameter \np{ln\_cfmeta} in the \nam{run} namelist.
 This must be set to true if these metadata are to be included in the output files.
 …
 Datasets created with chunking and compression are not backwards compatible with NetCDF3 "classic" format but
 most analysis codes can be relinked simply with the new libraries and will then read both NetCDF3 and NetCDF4 files.
 NEMO executables linked with NetCDF4 libraries can be made to produce NetCDF3 files by
 setting the \np{ln\_nc4zip} logical to false in the \textit{namnc4} namelist:
+\NEMO\ executables linked with NetCDF4 libraries can be made to produce NetCDF3 files by
+setting the \np{ln\_nc4zip} logical to false in the \nam{nc4} namelist:
 %------------------------------------------namnc4----------------------------------------------------
 …
 \noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\ttfamily 46x38x1} respectively in
 the mono-processor case (\ie global domain of {\small\ttfamily 182x149x31}).
 An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in
+the mono-processor case (\ie\ global domain of {\small\ttfamily 182x149x31}).
+An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in
 table \autoref{tab:NC4} which compares the results of two short runs of the ORCA2\_LIM reference configuration with
 a 4x2 mpi partitioning.
 …
 When \key{iomput} is activated with \key{netcdf4} chunking and compression parameters for fields produced via
 \np{iom\_put} calls are set via an equivalent and identically named namelist to \textit{namnc4} in
 \np{xmlio\_server.def}.
 Typically this namelist serves the mean files whilst the \ngn{ namnc4} in the main namelist file continues to
+\rou{iom\_put} calls are set via an equivalent and identically named namelist to \nam{nc4} in
+\textit{xmlio\_server.def}.
+Typically this namelist serves the mean files whilst the \nam{nc4} in the main namelist file continues to
 serve the restart files.
 This duplication is unfortunate but appropriate since, if using io\_servers, the domain sizes of
 the individual files produced by the io\_server processes may be different to those produced by
 the invidual processing regions and different chunking choices may be desired.
 % -------------------------------------------------------------------------------------------------------------
 %       Tracer/Dynamics Trends
 % -------------------------------------------------------------------------------------------------------------
 \section[Tracer/Dynamics trends (\texttt{namtrd})]
 {Tracer/Dynamics trends (\protect\ngn{namtrd})}
+{Tracer/Dynamics trends (\protect\nam{trd})}
 \label{sec:DIA_trd}
 %------------------------------------------namtrd----------------------------------------------------
 \nlst{namtrd}
+\nlst{namtrd}
 %-------------------------------------------------------------------------------------------------------------
 Each trend of the dynamics and/or temperature and salinity time evolution equations can be send to
 \mdl{trddyn} and/or \mdl{trdtra} modules (see TRD directory) just after their computation
 (\ie at the end of each $dyn\cdots.F90$ and/or $tra\cdots.F90$ routines).
 This capability is controlled by options offered in \ngn{namtrd} namelist.
+(\ie\ at the end of each \textit{dyn....F90} and/or \textit{tra....F90} routines).
+This capability is controlled by options offered in \nam{trd} namelist.
 Note that the output are done with XIOS, and therefore the \key{iomput} is required.
 What is done depends on the \ngn{namtrd} logical set to \forcode{.true.}:
+What is done depends on the \nam{trd} logical set to \forcode{.true.}:
 \begin{description}
 …
 \end{description}
 Note that the mixed layer tendency diagnostic can also be used on biogeochemical models via
+Note that the mixed layer tendency diagnostic can also be used on biogeochemical models via
 the \key{trdtrc} and \key{trdmxl\_trc} CPP keys.
 \textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested.
 In particular, options associated with \np{ln\_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl} are not working,
 and none of the options have been tested with variable volume (\ie \np{ln\_linssh}\forcode{ = .true.}).
+and none of the options have been tested with variable volume (\ie\ \np{ln\_linssh}\forcode{ = .true.}).
 % -------------------------------------------------------------------------------------------------------------
 …
 %--------------------------------------------namflo-------------------------------------------------------
 \nlst{namflo}
+\nlst{namflo}
 %--------------------------------------------------------------------------------------------------------------
 The on-line computation of floats advected either by the three dimensional velocity field or constraint to
 remain at a given depth ($w = 0$ in the computation) have been introduced in the system during the CLIPPER project.
 Options are defined by \ngn{namflo} namelist variables.
+Options are defined by \nam{flo} namelist variables.
 The algorithm used is based either on the work of \cite{blanke.raynaud_JPO97} (default option),
 or on a $4^th$ Runge-Hutta algorithm (\np{ln\_flork4}\forcode{ = .true.}).
 …
 (IJK coordinates, (\np{ln\_ariane}\forcode{ = .true.}) ) or with longitude and latitude.
 In case of Ariane convention, input filename is \np{init\_float\_ariane}.
+In case of Ariane convention, input filename is \textit{init\_float\_ariane}.
 Its format is: \\
 {\scriptsize \texttt{I J K nisobfl itrash}}
 …
  - I,J,K  : indexes of initial position
  - nisobfl: 0 for an isobar float, 1 for a float following the w velocity
+ - nisobfl: 0 for an isobar float, 1 for a float following the w velocity
  - itrash : set to zero; it is a dummy variable to respect Ariane Tools convention
 …
 This on-line Harmonic analysis is actived with \key{diaharm}.
 Some parameters are available in namelist \ngn{nam\_diaharm}:
+Some parameters are available in namelist \nam{\_diaharm}:
  - \np{nit000\_han} is the first time step used for harmonic analysis
 …
  - \np{nstep\_han}  is the  time step frequency for harmonic analysis
  - \np{nb\_ana}     is the number of harmonics to analyse
+% - \np{nb\_ana}     is the number of harmonics to analyse
  - \np{tname}       is an array with names of tidal constituents to analyse
 …
 The pathways between them are contructed using tools which can be found in \texttt{tools/SECTIONS\_DIADCT}
 and are written in a binary file \texttt{section\_ijglobal.diadct} which is later read in by
 NEMO to compute on-line transports.
+\NEMO\ to compute on-line transports.
 The on-line transports module creates three output ascii files:
 …
 - \texttt{salt\_transport}   for   salt transports (unit: $10^{9}Kg s^{-1}$) \\
 Namelist variables in \ngn{nam_diadct} control how frequently the flows are summed and the time scales over which
+Namelist variables in \nam{\_diadct} control how frequently the flows are summed and the time scales over which
 they are averaged, as well as the level of output for debugging:
 \np{nn\_dct}   : frequency of instantaneous transports computing
 …
  - \texttt{long2 lat2}, coordinates of the second extremity of the section;
  - \texttt{nclass}    the number of bounds of your classes (\eg bounds for 2 classes);
+ - \texttt{nclass}    the number of bounds of your classes (\eg\ bounds for 2 classes);
  - \texttt{okstrpond} to compute    heat and       salt transports, \texttt{nostrpond} if no;
 …
  - \texttt{zsigp} for potential density classes \\
  The script \texttt{job.ksh} computes the pathway for each section and creates a binary file
  \texttt{section\_ijglobal.diadct} which is read by NEMO. \\
+ \texttt{section\_ijglobal.diadct} which is read by \NEMO. \\
  It is possible to use this tools for new configuations: \texttt{job.ksh} has to be updated with
 …
 Let denote
 $\mathcal{M}$ the total mass    of liquid seawater ($\mathcal{M} = \int_D \rho dv$),
 $\mathcal{V}$ the total volume  of        seawater      ($\mathcal{V} = \int_D dv$),
 $\mathcal{A}$ the total surface of       the ocean      ($\mathcal{A} = \int_S ds$),
 $\bar{\rho}$ the global mean  seawater (\textit{in situ}) density
+$\mathcal{M}$ the total mass    of liquid seawater ($\mathcal{M} = \int_D \rho dv$),
+$\mathcal{V}$ the total volume  of        seawater      ($\mathcal{V} = \int_D dv$),
+$\mathcal{A}$ the total surface of       the ocean      ($\mathcal{A} = \int_S ds$),
+$\bar{\rho}$ the global mean  seawater (\textit{in situ}) density
 ($\bar{\rho} = 1/\mathcal{V} \int_D \rho \,dv$), and
 $\bar{\eta}$ the global mean sea level
+$\bar{\eta}$ the global mean sea level
 ($\bar{\eta} = 1/\mathcal{A} \int_S \eta \,ds$).
 …
 where $\rho$ is the \textit{in situ} density, and \textit{emp} the surface mass exchanges with the other media of
 the Earth system (atmosphere, sea-ice, land).
 Its global averaged leads to the total mass change
+Its global averaged leads to the total mass change
 \begin{equation}
 …
 \end{equation}
 The first term in equation \autoref{eq:ssh_nBq} alters sea level by adding or subtracting mass from the ocean.
 The second term arises from temporal changes in the global mean density; \ie from steric effects.
+The first term in equation \autoref{eq:ssh_nBq} alters sea level by adding or subtracting mass from the ocean.
+The second term arises from temporal changes in the global mean density; \ie\ from steric effects.
 In a Boussinesq fluid, $\rho$ is replaced by $\rho_o$ in all the equation except when $\rho$ appears multiplied by
 the gravity (\ie in the hydrostatic balance of the primitive Equations).
+the gravity (\ie\ in the hydrostatic balance of the primitive Equations).
 In particular, the mass conservation equation, \autoref{eq:Co_nBq}, degenerates into the incompressibility equation:
 …
 Nevertheless, following \citep{greatbatch_JGR94}, the steric effect on the volume can be diagnosed by
 considering the mass budget of the ocean.
+considering the mass budget of the ocean.
 The apparent changes in $\mathcal{M}$, mass of the ocean, which are not induced by surface mass flux
 must be compensated by a spatially uniform change in the mean sea level due to expansion/contraction of the ocean
 …
 is converted into a mean change in sea level.
 Introducing the total density anomaly, $\mathcal{D}= \int_D d_a \,dv$,
 where $d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO (cf. \autoref{subsec:TRA_eos})
+where $d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO\ (cf. \autoref{subsec:TRA_eos})
 in \autoref{eq:M_Bq} leads to a very simple form for the steric height:
 …
 The above formulation of the steric height of a Boussinesq ocean requires four remarks.
 First, one can be tempted to define $\rho_o$ as the initial value of $\mathcal{M}/\mathcal{V}$,
 \ie set $\mathcal{D}_{t=0}=0$, so that the initial steric height is zero.
+\ie\ set $\mathcal{D}_{t=0}=0$, so that the initial steric height is zero.
 We do not recommend that.
 Indeed, in this case $\rho_o$ depends on the initial state of the ocean.
 …
 does not change when the sea level is changing as it is the case in all global ocean GCMs
 (wetting and drying of grid point is not allowed).
 Third, the discretisation of \autoref{eq:steric_Bq} depends on the type of free surface which is considered.
 In the non linear free surface case, \ie \np{ln\_linssh}\forcode{ = .true.}, it is given by
+In the non linear free surface case, \ie\ \np{ln\_linssh}\forcode{ = .true.}, it is given by
 \[
 …
 so that there are no associated ocean currents.
 Hence, the dynamically relevant sea level is the effective sea level,
 \ie the sea level as if sea ice (and snow) were converted to liquid seawater \citep{campin.marshall.ea_OM08}.
 However, in the current version of \NEMO the sea-ice is levitating above the ocean without mass exchanges between
+\ie\ the sea level as if sea ice (and snow) were converted to liquid seawater \citep{campin.marshall.ea_OM08}.
+However, in the current version of \NEMO\ the sea-ice is levitating above the ocean without mass exchanges between
 ice and ocean.
 Therefore the model effective sea level is always given by $\eta + \eta_s$, whether or not there is sea ice present.
 …
+    }
   \end{center}
 \end{figure}
+\end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 % -----------------------------------------------------------
 %       CMIP specific diagnostics
+%       CMIP specific diagnostics
 % -----------------------------------------------------------
 \subsection[CMIP specific diagnostics (\textit{diaar5.F90}, \textit{diaptr.F90})]
 …
 In \mdl{diaar5} they correspond to outputs that are required for AR5 simulations (CMIP5)
 (see also \autoref{sec:DIA_steric} for one of them).
+The module \mdl{diaar5} is active when one of the following outputs is required : global total volume (voltot), global mean ssh (sshtot), global total mass (masstot), global mean temperature (temptot), global mean ssh steric (sshsteric), global mean ssh thermosteric (sshthster), global mean salinity (saltot), sea water pressure at sea floor (botpres), dynamic sea surface height (sshdyn).
+In \mdl{diaptr} when \np{ln\_diaptr}\forcode{ = .true.}
+(see the \textit{\ngn{namptr} } namelist below) can be computed on-line the poleward heat and salt transports, their advective and diffusive component, and the meriodional stream function .
+The module \mdl{diaar5} is active when one of the following outputs is required :
+global total volume (voltot), global mean ssh (sshtot), global total mass (masstot), global mean temperature (temptot),
+global mean ssh steric (sshsteric), global mean ssh thermosteric (sshthster), global mean salinity (saltot),
+sea water pressure at sea floor (botpres), dynamic sea surface height (sshdyn).
+In \mdl{diaptr} when \np{ln\_diaptr}\forcode{ = .true.}
+(see the \nam{ptr} namelist below) can be computed on-line the poleward heat and salt transports,
+their advective and diffusive component, and the meriodional stream function .
 When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed for the Atlantic, Indian,
 Pacific and Indo-Pacific Oceans (defined north of 30\deg{S}) as well as for the World Ocean.
 …
 %------------------------------------------namptr-----------------------------------------
 \nlst{namptr}
+\nlst{namptr}
 %-----------------------------------------------------------------------------------------
 % -----------------------------------------------------------
 %       25 hour mean and hourly Surface, Mid and Bed
+%       25 hour mean and hourly Surface, Mid and Bed
 % -----------------------------------------------------------
 \subsection{25 hour mean output for tidal models}
 …
 Values greater than 1 indicate that information is propagated across more than one grid cell in a single time step.
 The variables can be activated by setting the \np{nn\_diacfl} namelist parameter to 1 in the \ngn{namctl} namelist.
+The variables can be activated by setting the \np{nn\_diacfl} namelist parameter to 1 in the \nam{ctl} namelist.
 The diagnostics will be written out to an ascii file named cfl\_diagnostics.ascii.
 In this file the maximum value of $C_u$, $C_v$, and $C_w$ are printed at each timestep along with the coordinates of
 …
 At the end of the model run the maximum value of $C_u$, $C_v$, and $C_w$ for the whole model run is printed along
 with the coordinates of each.
 The maximum values from the run are also copied to the ocean.output file.
+The maximum values from the run are also copied to the ocean.output file.
 % ================================================================

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_DIU.tex

-                      r11263
+                      r11512
 \label{chap:DIU}
 \minitoc
+\chaptertoc
 …
 Code to produce an estimate of the diurnal warming and cooling of the sea surface skin
 temperature (skin SST) is found in the DIU directory.
+temperature (skin SST) is found in the DIU directory.
 The skin temperature can be split into three parts:
 \begin{itemize}
 …
 Models are provided for both the warm layer, \mdl{diurnal\_bulk}, and the cool skin, \mdl{cool\_skin}.
 Foundation SST is not considered as it can be obtained either from the main NEMO model
 (\ie from the temperature of the top few model levels) or from some other source.
+Foundation SST is not considered as it can be obtained either from the main \NEMO\ model
+(\ie\ from the temperature of the top few model levels) or from some other source.
 It must be noted that both the cool skin and warm layer models produce estimates of the change in temperature
 ($\Delta T_{\mathrm{cs}}$ and $\Delta T_{\mathrm{wl}}$) and
 both must be added to a foundation SST to obtain the true skin temperature.
 Both the cool skin and warm layer models are controlled through the namelist \ngn{namdiu}:
+Both the cool skin and warm layer models are controlled through the namelist \nam{diu}:
 \nlst{namdiu}
 …
   A logical switch for turning on/off both the cool skin and warm layer.
 \item[\np{ln\_diurnal\_only}]
   A logical switch which if \forcode{.true.} will run the diurnal model without the other dynamical parts of NEMO.
+  A logical switch which if \forcode{.true.} will run the diurnal model without the other dynamical parts of \NEMO.
   \np{ln\_diurnal\_only} must be \forcode{.false.} if \np{ln\_diurnal} is \forcode{.false.}.
 \end{description}
 …
 Initialisation is through the restart file.
 Specifically the code will expect the presence of the 2-D variable ``Dsst'' to initialise the warm layer.
 The cool skin model, which is determined purely by the instantaneous fluxes, has no initialisation variable.
+The cool skin model, which is determined purely by the instantaneous fluxes, has no initialisation variable.
 %===============================================================
 …
 \end{equation}
 where $\zeta=\frac{D_T}{L}$.  It is clear that the first derivative of (\autoref{eq:stab_func_eqn}),
 and thus of (\autoref{eq:ecmwf1}), is discontinuous at $\zeta=0$ (\ie $Q\rightarrow0$ in
+and thus of (\autoref{eq:ecmwf1}), is discontinuous at $\zeta=0$ (\ie\ $Q\rightarrow0$ in
 equation (\autoref{eq:ecmwf2})).

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_DOM.tex

-                      r11353
+                      r11512
 \label{chap:DOM}
 \minitoc
+%\chaptertoc
 % Missing things:
 %  - istate: description of the initial state   ==> this has to be put elsewhere..
 %                  perhaps in MISC ?  By the way the initialisation of T S and dynamics
+%                  perhaps in MISC ?  By the way the initialisation of T S and dynamics
 %                  should be put outside of DOM routine (better with TRC staff and off-line
 %                  tracers)
 …
 \vfill
+\begin{figure}[b]
+\subsubsection*{Changes record}
+\begin{tabular}{m{0.08\linewidth}||m{0.32\linewidth}|m{0.6\linewidth}}
+    Release   & Author(s)     & Modifications \\
+\hline
+    {\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} }  \\
+    {\em 3.x} & {\em Sebastien Masson, Gurvan Madec \& Rashid Benshila } & {\em }  \\
+\end{tabular}
+\end{figure}
+\begin{table}[b]
+  \footnotesize
+  \caption*{Changes record}
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release & Author(s) & Modifications                                                          \\
+    \hline
+    {\em 4.0} & {\em Simon M\"{u}ller \& Andrew Coward} &
+    {\em
+      Compatibility changes Major simplification has moved many of the options to external domain configuration tools.
+      (see \autoref{apdx:DOMAINcfg})
+    }                                                                                            \\
+    {\em 3.x} & {\em Rachid Benshila, Gurvan Madec \& S\'{e}bastien Masson} &
+    {\em First version}                                                                          \\
+  \end{tabularx}
+\end{table}
 \newpage
 Having defined the continuous equations in \autoref{chap:PE} and chosen a time discretization \autoref{chap:STP},
 we need to choose a grid for spatial discretization and related numerical algorithms.
+Having defined the continuous equations in \autoref{chap:PE} and chosen a time discretisation \autoref{chap:STP},
+we need to choose a grid for spatial discretisation and related numerical algorithms.
 In the present chapter, we provide a general description of the staggered grid used in \NEMO,
 and other relevant information about the DOM (DOMain) source-code modules .
+and other relevant information about the DOM (DOMain) source code modules.
 % ================================================================
 …
 % -------------------------------------------------------------------------------------------------------------
 %        Arrangement of Variables
+%        Arrangement of Variables
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Arrangement of variables}
 …
 the barotropic stream function $\psi$ is defined at horizontal points overlying the $\zeta$ and $f$-points.
 The ocean mesh (\ie the position of all the scalar and vector points) is defined by the transformation that
+The ocean mesh (\ie\ the position of all the scalar and vector points) is defined by the transformation that
 gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$.
 The grid-points are located at integer or integer and a half value of $(i,j,k)$ as indicated on \autoref{tab:cell}.
 …
 Note that the definition of the scale factors
 (\ie as the analytical first derivative of the transformation that
+(\ie\ as the analytical first derivative of the transformation that
 results in $(\lambda,\varphi,z)$ as a function of $(i,j,k)$)
 is specific to the \NEMO model \citep{marti.madec.ea_JGR92}.
+is specific to the \NEMO\ model \citep{marti.madec.ea_JGR92}.
 As an example, a scale factor in the $i$ direction is defined locally at a $t$-point,
 whereas many other models on a C grid choose to define such a scale factor as
 …
 % -------------------------------------------------------------------------------------------------------------
 %        Vector Invariant Formulation
+%        Vector Invariant Formulation
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Discrete operators}
 …
 Similar operators are defined with respect to $i + 1/2$, $j$, $j + 1/2$, $k$, and $k + 1/2$.
+Following \autoref{eq:PE_grad} and \autoref{eq:PE_lap}, the gradient of a variable $q$ defined at
+a $t$-point has its three components defined at $u$-, $v$- and $w$-points while
+its Laplacian is defined at the $t$-point.
+Following \autoref{eq:PE_grad} and \autoref{eq:PE_lap}, the gradient of a variable $q$ defined at a $t$-point has
+its three components defined at $u$-, $v$- and $w$-points while its Laplacian is defined at the $t$-point.
 These operators have the following discrete forms in the curvilinear $s$-coordinates system:
 \[
 …
 The vertical average over the whole water column is denoted by an overbar and is for
 a masked field $q$ (\ie a quantity that is equal to zero inside solid areas):
+a masked field $q$ (\ie\ a quantity that is equal to zero inside solid areas):
 \begin{equation}
   \label{eq:DOM_bar}
 …
 \end{alignat}
 In other words, the adjoint of the differencing and averaging operators are $\delta_i^* = \delta_{i + 1/2}$ and
+In other words, the adjoint of the differencing and averaging operators are $\delta_i^* = \delta_{i + 1/2}$ and
 $(\overline{\cdots}^{\, i})^* = \overline{\cdots}^{\, i + 1/2}$, respectively.
 These two properties will be used extensively in the \autoref{apdx:C} to
 …
 % -------------------------------------------------------------------------------------------------------------
 %        Numerical Indexing
+%        Numerical Indexing
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Numerical indexing}
 …
 integer values for $t$-points only while all the other points involve integer and a half values.
 Therefore, a specific integer indexing has been defined for points other than $t$-points
 (\ie velocity and vorticity grid-points).
+(\ie\ velocity and vorticity grid-points).
 Furthermore, the direction of the vertical indexing has been reversed and the surface level set at $k = 1$.
 % -----------------------------------
 %        Horizontal Indexing
+%        Horizontal Indexing
 % -----------------------------------
 \subsubsection{Horizontal indexing}
 …
 the $t$-point and the eastward $u$-point (northward $v$-point) have the same index
 (see the dashed area in \autoref{fig:index_hor}).
 A $t$-point and its nearest northeast $f$-point have the same $i$-and $j$-indices.
+A $t$-point and its nearest north-east $f$-point have the same $i$-and $j$-indices.
 % -----------------------------------
 %        Vertical indexing
+%        Vertical indexing
 % -----------------------------------
 \subsubsection{Vertical indexing}
 …
 The last $w$-level ($k = jpk$) either corresponds to or is below the ocean floor while
 the last $t$-level is always outside the ocean domain (\autoref{fig:index_vert}).
+Note that a $w$-point and the directly underlaying $t$-point have a common $k$ index (\ie $t$-points and their
+nearest $w$-point neighbour in negative index direction), in contrast to the indexing on the horizontal plane where
+the $t$-point has the same index as the nearest velocity points in the positive direction of the respective horizontal axis index
+Note that a $w$-point and the directly underlaying $t$-point have a common $k$ index
+(\ie\ $t$-points and their nearest $w$-point neighbour in negative index direction),
+in contrast to the indexing on the horizontal plane where the $t$-point has the same index as
+the nearest velocity points in the positive direction of the respective horizontal axis index
 (compare the dashed area in \autoref{fig:index_hor} and \autoref{fig:index_vert}).
 Since the scale factors are chosen to be strictly positive,
+a \textit{minus sign} is included in the \fortran implementations of \textit{all the vertical derivatives} of
+the discrete equations given in this manual in order to accommodate the opposing vertical index directions in implementation and documentation.
+a \textit{minus sign} is included in the \fortran implementations of
+\textit{all the vertical derivatives} of the discrete equations given in this manual in order to
+accommodate the opposing vertical index directions in implementation and documentation.
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 \nlst{namcfg}
+Two typical methods are available to specify the spatial domain
+configuration; they can be selected using parameter \np{ln\_read\_cfg}
+parameter in namelist \ngn{namcfg}.
+If \np{ln\_read\_cfg} is set to \forcode{.true.}, the domain-specific parameters
+and fields are read from a netCDF input file, whose name (without its .nc
+suffix) can be specified as the value of the \np{cn\_domcfg} parameter in
+namelist \ngn{namcfg}.
+If \np{ln\_read\_cfg} is set to \forcode{.false.}, the domain-specific
+parameters and fields can be provided (\eg analytically computed) by subroutines
+\mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}. These subroutines can be supplied in
+the \path{MY_SRC} directory of the configuration, and default versions that
+configure the spatial domain for the GYRE reference configuration are present in
+the \path{src/OCE/USR} directory.
+In version 4.0 there are no longer any options for reading complex bathmetries and
+performing a vertical discretization at run-time. Whilst it is occasionally convenient
+to have a common bathymetry file and, for example, to run similar models with and
+without partial bottom boxes and/or sigma-coordinates, supporting such choices leads to
+overly complex code. Worse still is the difficulty of ensuring the model configurations
+intended to be identical are indeed so when the model domain itself can be altered by runtime
+selections. The code previously used to perform vertical discretization has be incorporated
+into an external tool (\path{tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMAINcfg}.
+The next subsections summarise the parameter and fields related to the
+configuration of the whole model domain. These represent the minimum information
+that must be provided either via the \np{cn\_domcfg} file or set by code
+inserted into user-supplied versions of the \mdl{usrdef\_*} subroutines. The
+requirements are presented in three sections: the domain size
+(\autoref{subsec:DOM_size}), the horizontal mesh
+(\autoref{subsec:DOM_hgr}), and the vertical grid
+(\autoref{subsec:DOM_zgr}).
+Two typical methods are available to specify the spatial domain configuration;
+they can be selected using parameter \np{ln\_read\_cfg} parameter in namelist \nam{cfg}.
+If \np{ln\_read\_cfg} is set to \forcode{.true.},
+the domain-specific parameters and fields are read from a netCDF input file,
+whose name (without its .nc suffix) can be specified as the value of the \np{cn\_domcfg} parameter in namelist \nam{cfg}.
+If \np{ln\_read\_cfg} is set to \forcode{.false.},
+the domain-specific parameters and fields can be provided (\eg\ analytically computed) by
+subroutines \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}.
+These subroutines can be supplied in the \path{MY_SRC} directory of the configuration,
+and default versions that configure the spatial domain for the GYRE reference configuration are present in
+the \path{./src/OCE/USR} directory.
+In version 4.0 there are no longer any options for reading complex bathymetries and
+performing a vertical discretisation at run-time.
+Whilst it is occasionally convenient to have a common bathymetry file and, for example,
+to run similar models with and without partial bottom boxes and/or sigma-coordinates,
+supporting such choices leads to overly complex code.
+Worse still is the difficulty of ensuring the model configurations intended to be identical are indeed so when
+the model domain itself can be altered by runtime selections.
+The code previously used to perform vertical discretisation has been incorporated into an external tool
+(\path{./tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMAINcfg}.
+The next subsections summarise the parameter and fields related to the configuration of the whole model domain.
+These represent the minimum information that must be provided either via the \np{cn\_domcfg} file or set by code
+inserted into user-supplied versions of the \texttt{usrdef\_*} subroutines.
+The requirements are presented in three sections:
+the domain size (\autoref{subsec:DOM_size}), the horizontal mesh (\autoref{subsec:DOM_hgr}),
+and the vertical grid (\autoref{subsec:DOM_zgr}).
 % -----------------------------------
 …
 \label{subsec:DOM_size}
+The total size of the computational domain is set by the parameters
+\np{jpiglo}, \np{jpjglo} and \np{jpkglo} for the $i$, $j$ and $k$
+directions, respectively. Note, that the variables \forcode{jpi} and \forcode{jpj}
+refer to the size of each processor subdomain when the code is run in
+parallel using domain decomposition (\key{mpp\_mpi} defined, see
+\autoref{sec:LBC_mpp}).
+The total size of the computational domain is set by the parameters \jp{jpiglo}, \jp{jpjglo} and \jp{jpkglo} for
+the $i$, $j$ and $k$ directions, respectively.
+Note, that the variables \texttt{jpi} and \texttt{jpj} refer to the size of each processor subdomain when
+the code is run in parallel using domain decomposition (\key{mpp\_mpi} defined,
+see \autoref{sec:LBC_mpp}).
 The name of the configuration is set through parameter \np{cn\_cfg},
+and the nominal resolution through parameter \np{nn\_cfg} (unless in
+the input file both of variables \forcode{ORCA} and \forcode{ORCA_index}
+are present, in which case \np{cn\_cfg} and \np{nn\_cfg} are set from these
+values accordingly).
+The global lateral boundary condition type is selected from 8 options
+using parameter \np{jperio}. See \autoref{sec:LBC_jperio} for
+details on the available options and the corresponding values for
+\np{jperio}.
+% ================================================================
+% Domain: Horizontal Grid (mesh)
+and the nominal resolution through parameter \np{nn\_cfg}
+(unless in the input file both of variables \texttt{ORCA} and \texttt{ORCA\_index} are present,
+in which case \np{cn\_cfg} and \np{nn\_cfg} are set from these values accordingly).
+The global lateral boundary condition type is selected from 8 options using parameter \jp{jperio}.
+See \autoref{sec:LBC_jperio} for details on the available options and the corresponding values for \jp{jperio}.
+% ================================================================
+% Domain: Horizontal Grid (mesh)
 % ================================================================
 \subsection{Horizontal grid mesh (\protect\mdl{domhgr})}
 …
 \subsubsection{Required fields}
 \label{sec:DOM_hgr_fields}
+The explicit specification of a range of mesh-related fields are required for the definition of a configuration. These include:
+\begin{Verbatim}[fontsize=\tiny]
+The explicit specification of a range of mesh-related fields are required for the definition of a configuration.
+These include:
+\begin{clines}
 int    jpiglo, jpjglo, jpkglo            /* global domain sizes                                          */
 int    jperio                            /* lateral global domain b.c.                                   */
 …
 double e1t, e1u, e1v, e1f                /* horizontal scale factors                                     */
 double e2t, e2u, e2v, e2f                /* horizontal scale factors                                     */
+\end{Verbatim}
+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$.
+\end{clines}
+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 \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$.
 \subsubsection{Optional fields}
+\begin{Verbatim}[fontsize=\tiny]
+\begin{clines}
                                          /* Optional:                                                    */
 int    ORCA, ORCA_index                  /* configuration name, configuration resolution                 */
 double e1e2u, e1e2v                      /* U and V surfaces (if grid size reduction in some straits)    */
 double ff_f, ff_t                        /* Coriolis parameter (if not on the sphere)                    */
+\end{Verbatim}
+NEMO can support the local reduction of key strait widths by altering individual values of
+e2u or e1v at the appropriate locations. This is particularly useful for locations such as
+Gibraltar or Indonesian Throughflow pinch-points (see \autoref{sec:MISC_strait} for
+illustrated examples). The key is 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 cells. Doing
+otherwise can lead to numerical instability issues.  In normal operation the surface areas
+are computed from $\texttt{e1u} * \texttt{e2u}$ and $\texttt{e1v} * \texttt{e2v}$ but in
+cases where a gridsize reduction is required, the unaltered surface areas at $u$ and $v$
+grid points (\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or pre-computed
+in \mdl{usrdef\_hgr}. If these arrays are present in the \np{cn\_domcfg} file they are
+read and the internal computation is suppressed. Versions of \mdl{usrdef\_hgr} which set
+their own values of \texttt{e1e2u} and \texttt{e1e2v} should set the surface-area
+computation flag: \texttt{ie1e2u\_v} to a non-zero value to suppress their re-computation.
+\end{clines}
+\NEMO\ can support the local reduction of key strait widths by
+altering individual values of e2u or e1v at the appropriate locations.
+This is particularly useful for locations such as Gibraltar or Indonesian Throughflow pinch-points
+(see \autoref{sec:MISC_strait} for illustrated examples).
+The key is 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 cells.
+Doing otherwise can lead to numerical instability issues.
+In normal operation the surface areas are computed from $e1u * e2u$ and $e1v * e2v$ but
+in cases where a gridsize reduction is required,
+the unaltered surface areas at $u$ and $v$ grid points (\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or
+pre-computed in \mdl{usrdef\_hgr}.
+If these arrays are present in the \np{cn\_domcfg} file they are read and the internal computation is suppressed.
+Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{e1e2u} and \texttt{e1e2v} should set
+the surface-area computation flag:
+\texttt{ie1e2u\_v} to a non-zero value to suppress their re-computation.
 \smallskip
+Similar logic applies to the other optional fields: \texttt{ff\_f} and \texttt{ff\_t}
+which can be used to provide the Coriolis parameter at F- and T-points respectively if the
+mesh is not on a sphere. If present these fields will be read and used and the normal
+calculation ($2*\Omega*\sin(\varphi)$) suppressed. Versions of \mdl{usrdef\_hgr} which set
+their own values of \texttt{ff\_f} and \texttt{ff\_t} should set the Coriolis computation
+flag: \texttt{iff} to a non-zero value to suppress their re-computation.
+Note that longitudes, latitudes, and scale factors at $w$ points are exactly
+equal to those of $t$ points, thus no specific arrays are defined at $w$ points.
+Similar logic applies to the other optional fields:
+\texttt{ff\_f} and \texttt{ff\_t} which can be used to provide the Coriolis parameter at F- and T-points respectively if
+the mesh is not on a sphere.
+If present these fields will be read and used and the normal calculation ($2 * \Omega * \sin(\varphi)$) suppressed.
+Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{ff\_f} and \texttt{ff\_t} should set
+the Coriolis computation flag:
+\texttt{iff} to a non-zero value to suppress their re-computation.
+Note that longitudes, latitudes, and scale factors at $w$ points are exactly equal to those of $t$ points,
+thus no specific arrays are defined at $w$ points.
 …
 %-------------------------------------------------------------------------------------------------------------
 In the vertical, the model mesh is determined by four things:
+In the vertical, the model mesh is determined by four things:
 \begin{enumerate}
   \item the bathymetry given in meters;
   \item the number of levels of the model (\jp{jpk});
+  \item the bathymetry given in meters;
+  \item the number of levels of the model (\jp{jpk});
   \item the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and
   \item the masking system, \ie the number of wet model levels at each
+  \item the masking system, \ie\ the number of wet model levels at each
 $(i,j)$ location of the horizontal grid.
 \end{enumerate}
 …
 The choice of a vertical coordinate is made when setting up the configuration;
+it is not intended to be an option which can be changed in the middle of an
+experiment. The one exception to this statement being the choice of linear or
+non-linear free surface. In v4.0 the linear free surface option is implemented
+as a special case of the non-linear free surface. This is computationally
+wasteful since it uses the structures for time-varying 3D metrics for fields
+that (in the linear free surface case) are fixed. However, the linear
+free-surface is rarely used and implementing it this way means a single configuration
+file can support both options.
+By default a non-linear free surface is used (\np{ln\_linssh} set to \forcode{ =
+.false.} in \ngn{namdom}): the coordinate follow the time-variation of the free
+surface so that the transformation is time dependent: $z(i,j,k,t)$
+(\eg \autoref{fig:z_zps_s_sps}f).  When a linear free surface is assumed
+(\np{ln\_linssh} set to \forcode{ = .true.} in \ngn{namdom}), the vertical
+coordinates are fixed in time, but the seawater can move up and down across the
+$z_0$ surface (in other words, the top of the ocean in not a rigid lid).
+Note that settings: \np{ln\_zco}, \np{ln\_zps}, \np{ln\_sco} and \np{ln\_isfcav} mentioned
+in the following sections appear to be namelist options but they are no longer truly
+namelist options for NEMO. Their value is written to and read from the domain configuration file
+and they should be treated as fixed parameters for a particular configuration. They are
+namelist options for the \forcode{DOMAINcfg} tool that can be used to build the
+configuration file and serve both to provide a record of the choices made whilst building the
+configuration and to trigger appropriate code blocks within NEMO.
+it is not intended to be an option which can be changed in the middle of an experiment.
+The one exception to this statement being the choice of linear or non-linear free surface.
+In v4.0 the linear free surface option is implemented as a special case of the non-linear free surface.
+This is computationally wasteful since it uses the structures for time-varying 3D metrics
+for fields that (in the linear free surface case) are fixed.
+However, the linear free-surface is rarely used and implementing it this way means
+a single configuration file can support both options.
+By default a non-linear free surface is used (\np{ln\_linssh} set to \forcode{ = .false.} in \nam{dom}):
+the coordinate follow the time-variation of the free surface so that the transformation is time dependent:
+$z(i,j,k,t)$ (\eg\ \autoref{fig:z_zps_s_sps}f).
+When a linear free surface is assumed (\np{ln\_linssh} set to \forcode{ = .true.} in \nam{dom}),
+the vertical coordinates are fixed in time, but the seawater can move up and down across the $z_0$ surface
+(in other words, the top of the ocean in not a rigid lid).
+Note that settings:
+\np{ln\_zco}, \np{ln\_zps}, \np{ln\_sco} and \np{ln\_isfcav} mentioned in the following sections
+appear to be namelist options but they are no longer truly namelist options for \NEMO.
+Their value is written to and read from the domain configuration file and
+they should be treated as fixed parameters for a particular configuration.
+They are namelist options for the \texttt{DOMAINcfg} tool that can be used to build the configuration file and
+serve both to provide a record of the choices made whilst building the configuration and
+to trigger appropriate code blocks within \NEMO.
 These values should not be altered in the \np{cn\_domcfg} file.
 …
 $s-z$ or $s-zps$ coordinate (\autoref{fig:z_zps_s_sps}d and \autoref{fig:z_zps_s_sps}e).
 A further choice related to vertical coordinate concerns the presence (or not) of ocean
+cavities beneath ice shelves within the model domain.  A setting of \np{ln\_isfcav} as
 \forcode{.true.} indicates that the domain contains  ocean cavities, otherwise the top,
+wet layer of the ocean will always be at the ocean surface.  This option is currently only
+available for $z$- or $zps$-coordinates. In the latter case, partial steps are also applied
 at the ocean/ice shelf interface.
 Within the model, the arrays describing the grid point depths and vertical scale factors
+are three set of three dimensional arrays $(i,j,k)$ defined at \textit{before},
+\textit{now} and \textit{after} time step.  The time at which they are defined is
+indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively.  They are updated at each
+model time step. The initial fixed reference coordinate system is held in variable names
+with a $\_0$ suffix.  When the linear free surface option is used
+(\np{ln\_linssh}\forcode{ = .true.}), \textit{before}, \textit{now} and \textit{after}
 arrays are initially set to their reference counterpart and remain fixed.
+A further choice related to vertical coordinate concerns
+the presence (or not) of ocean cavities beneath ice shelves within the model domain.
+A setting of \np{ln\_isfcav} as \forcode{.true.} indicates that the domain contains ocean cavities,
+otherwise the top, wet layer of the ocean will always be at the ocean surface.
+This option is currently only available for $z$- or $zps$-coordinates.
+In the latter case, partial steps are also applied at the ocean/ice shelf interface.
+Within the model, the arrays describing the grid point depths and vertical scale factors are three set of
+three dimensional arrays $(i,j,k)$ defined at \textit{before}, \textit{now} and \textit{after} time step.
+The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively.
+They are updated at each model time step.
+The initial fixed reference coordinate system is held in variable names with a $\_0$ suffix.
+When the linear free surface option is used (\np{ln\_linssh}\forcode{ = .true.}),
+\textit{before}, \textit{now} and \textit{after} arrays are initially set to
+their reference counterpart and remain fixed.
 \subsubsection{Required fields}
 \label{sec:DOM_zgr_fields}
+The explicit specification of a range of fields related to the vertical grid are required for the definition of a configuration. These include:
+\begin{Verbatim}[fontsize=\tiny]
+The explicit specification of a range of fields related to the vertical grid are required for
+the definition of a configuration.
+These include:
+\begin{clines}
 int    ln_zco, ln_zps, ln_sco            /* flags for z-coord, z-coord with partial steps and s-coord    */
 int    ln_isfcav                         /* flag  for ice shelf cavities                                 */
 …
                                          /* For reference:                                               */
 float  bathy_metry                       /* bathymetry used in setting top and bottom levels             */
+\end{Verbatim}
+This set of vertical metrics is sufficient to describe the initial depth and thickness of
+every gridcell in the model regardless of the choice of vertical coordinate. With constant
+z-levels, e3 metrics will be uniform across each horizontal level. In the partial step
+case each e3 at the \np{bottom\_level} (and, possibly, \np{top\_level} if ice cavities are
+present) may vary from its horizontal neighbours. And, in s-coordinates, variations can
+occur throughout the water column. With the non-linear free-surface, all the coordinates
+behave more like the s-coordinate in that variations occurr throughout the water column
+with displacements related to the sea surface height. These variations are typically much
+smaller than those arising from bottom fitted coordinates. The values for vertical metrics
+supplied in the domain configuration file can be considered as those arising from a flat
+sea surface with zero elevation.
+The \np{bottom\_level} and \np{top\_level} 2D arrays define the \np{bottom\_level} and top
+wet levels in each grid column. Without ice cavities, \np{top\_level} is essentially a land
+mask (0 on land; 1 everywhere else). With ice cavities, \np{top\_level} determines the
+first wet point below the overlying ice shelf.
+% -------------------------------------------------------------------------------------------------------------
+%        level bathymetry and mask
+\end{clines}
+This set of vertical metrics is sufficient to describe the initial depth and thickness of every gridcell in
+the model regardless of the choice of vertical coordinate.
+With constant z-levels, e3 metrics will be uniform across each horizontal level.
+In the partial step case each e3 at the \jp{bottom\_level}
+(and, possibly, \jp{top\_level} if ice cavities are present)
+may vary from its horizontal neighbours.
+And, in s-coordinates, variations can occur throughout the water column.
+With the non-linear free-surface, all the coordinates behave more like the s-coordinate in
+that variations occur throughout the water column with displacements related to the sea surface height.
+These variations are typically much smaller than those arising from bottom fitted coordinates.
+The values for vertical metrics supplied in the domain configuration file can be considered as
+those arising from a flat sea surface with zero elevation.
+The \jp{bottom\_level} and \jp{top\_level} 2D arrays define the \jp{bottom\_level} and top wet levels in each grid column.
+Without ice cavities, \jp{top\_level} is essentially a land mask (0 on land; 1 everywhere else).
+With ice cavities, \jp{top\_level} determines the first wet point below the overlying ice shelf.
+% -------------------------------------------------------------------------------------------------------------
+%        level bathymetry and mask
 % -------------------------------------------------------------------------------------------------------------
 \subsubsection{Level bathymetry and mask}
 …
 From \np{top\_level} and \np{bottom\_level} fields, the mask fields are defined as follows:
+From \jp{top\_level} and \jp{bottom\_level} fields, the mask fields are defined as follows:
 \begin{alignat*}{2}
   tmask(i,j,k) &= &  &
 …
 Note that, without ice shelves cavities,
 masks at $t-$ and $w-$points are identical with the numerical indexing used (\autoref{subsec:DOM_Num_Index}).
 Nevertheless, $wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface)
+Nevertheless, $wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface)
 exactly in the same way as for the bottom boundary.
 …
 %-------------------------------------------------------------------------------------------------
 %        Closed seas
+%        Closed seas
 %-------------------------------------------------------------------------------------------------
+\subsection{Closed seas} \label{subsec:DOM_closea}
+When a global ocean is coupled to an atmospheric model it is better to represent all large
+water bodies (\eg great lakes, Caspian sea...) even if the model resolution does not allow
+their communication with the rest of the ocean.  This is unnecessary when the ocean is
+forced by fixed atmospheric conditions, so these seas can be removed from the ocean
+domain.  The user has the option to set the bathymetry in closed seas to zero (see
+\autoref{sec:MISC_closea}) and to optionally decide on the fate of any freshwater
+imbalance over the area. The options are explained in \autoref{sec:MISC_closea} but it
+should be noted here that a successful use of these options requires appropriate mask
+fields to be present in the domain configuration file. Among the possibilities are:
+\begin{Verbatim}[fontsize=\tiny]
+\subsection{Closed seas} \label{subsec:DOM_closea}
+When a global ocean is coupled to an atmospheric model it is better to represent all large water bodies
+(\eg\ Great Lakes, Caspian sea \dots) even if the model resolution does not allow their communication with
+the rest of the ocean.
+This is unnecessary when the ocean is forced by fixed atmospheric conditions,
+so these seas can be removed from the ocean domain.
+The user has the option to set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}) and
+to optionally decide on the fate of any freshwater imbalance over the area.
+The options are explained in \autoref{sec:MISC_closea} but it should be noted here that
+a successful use of these options requires appropriate mask fields to be present in the domain configuration file.
+Among the possibilities are:
+\begin{clines}
 int    closea_mask          /* non-zero values in closed sea areas for optional masking                  */
 int    closea_mask_rnf      /* non-zero values in closed sea areas with runoff locations (precip only)   */
 int    closea_mask_emp      /* non-zero values in closed sea areas with runoff locations (total emp)     */
 \end{Verbatim}
+\end{clines}
 % -------------------------------------------------------------------------------------------------------------
 …
 \nlst{namcfg}
+Most of the arrays relating to a particular ocean model configuration dicussed in this
+chapter (grid-point position, scale factors) can be saved in a file if namelist parameter
+\np{ln\_write\_cfg} (namelist \ngn{namcfg}) is set to \forcode{.true.}; the output
+filename is set thorugh parameter \np{cn\_domcfg\_out}. This is only really useful
+if the fields are computed in subroutines \mdl{usrdef\_hgr} or \mdl{usrdef\_zgr} and
+Most of the arrays relating to a particular ocean model configuration discussed in this chapter
+(grid-point position, scale factors)
+can be saved in a file if
+namelist parameter \np{ln\_write\_cfg} (namelist \nam{cfg}) is set to \forcode{.true.};
+the output filename is set through parameter \np{cn\_domcfg\_out}.
+This is only really useful if
+the fields are computed in subroutines \mdl{usrdef\_hgr} or \mdl{usrdef\_zgr} and
 checking or confirmation is required.
 …
 Alternatively, all the arrays relating to a particular ocean model configuration
 (grid-point position, scale factors, depths and masks) can be saved in a file called
+\texttt{mesh\_mask} if namelist parameter \np{ln\_meshmask} (namelist \ngn{namdom}) is set
+to \forcode{.true.}. This file contains additional fields that can be useful for
+post-processing applications
+(grid-point position, scale factors, depths and masks)
+can be saved in a file called \texttt{mesh\_mask} if
+namelist parameter \np{ln\_meshmask} (namelist \nam{dom}) is set to \forcode{.true.}.
+This file contains additional fields that can be useful for post-processing applications.
 % ================================================================
 …
 \label{sec:DTA_tsd}
 %-----------------------------------------namtsd-------------------------------------------
 \nlst{namtsd}
+\nlst{namtsd}
 %------------------------------------------------------------------------------------------
 Basic initial state options are defined in \ngn{namtsd}.  By default, the ocean starts
 from rest (the velocity field is set to zero) and the initialization of temperature and
 salinity fields is controlled through the \np{ln\_tsd\_init} namelist parameter.
+Basic initial state options are defined in \nam{tsd}.
+By default, the ocean starts from rest (the velocity field is set to zero) and
+the initialization of temperature and salinity fields is controlled through the \np{ln\_tsd\_init} namelist parameter.
 \begin{description}
 \item[\np{ln\_tsd\_init}\forcode{= .true.}]
   Use T and S input files that can be given on the model grid itself or on their native
   input data grids.  In the latter case, the data will be interpolated on-the-fly both in
   the horizontal and the vertical to the model grid (see \autoref{subsec:SBC_iof}).  The
   information relating to the input files are specified in the \np{sn\_tem} and
   \np{sn\_sal} structures.  The computation is done in the \mdl{dtatsd} module.
+  Use T and S input files that can be given on the model grid itself or on their native input data grids.
+  In the latter case, the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid
+  (see \autoref{subsec:SBC_iof}).
+  The information relating to the input files are specified in the \np{sn\_tem} and \np{sn\_sal} structures.
+  The computation is done in the \mdl{dtatsd} module.
 \item[\np{ln\_tsd\_init}\forcode{= .false.}]
   Initial values for T and S are set via a user supplied \rou{usr\_def\_istate} routine
   contained in \mdl{userdef\_istate}. The default version sets horizontally uniform T and
   profiles as used in the  GYRE configuration (see \autoref{sec:CFG_gyre}).
+  Initial values for T and S are set via a user supplied \rou{usr\_def\_istate} routine contained in \mdl{userdef\_istate}.
+  The default version sets horizontally uniform T and profiles as used in the GYRE configuration
+  (see \autoref{sec:CFG_gyre}).
 \end{description}

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_DYN.tex

-                      r11263
+                      r11512
 \label{chap:DYN}
 \minitoc
+\chaptertoc
 Using the representation described in \autoref{chap:DOM},
 …
 (surface wind stress calculation using bulk formulae, estimation of mixing coefficients)
 that are carried out in modules SBC, LDF and ZDF and are described in
 \autoref{chap:SBC}, \autoref{chap:LDF} and \autoref{chap:ZDF}, respectively.
+\autoref{chap:SBC}, \autoref{chap:LDF} and \autoref{chap:ZDF}, respectively.
 In the present chapter we also describe the diagnostic equations used to compute the horizontal divergence,
 curl of the velocities (\emph{divcur} module) and the vertical velocity (\emph{wzvmod} module).
 The different options available to the user are managed by namelist variables.
 For term \textit{ttt} in the momentum equations, the logical namelist variables are \textit{ln\_dynttt\_xxx},
+The different options available to the user are managed by namelist variables.
+For term \textit{ttt} in the momentum equations, the logical namelist variables are \textit{ln\_dynttt\_xxx},
 where \textit{xxx} is a 3 or 4 letter acronym corresponding to each optional scheme.
 If a CPP key is used for this term its name is \key{ttt}.
+%If a CPP key is used for this term its name is \key{ttt}.
 The corresponding code can be found in the \textit{dynttt\_xxx} module in the DYN directory,
 and it is usually computed in the \textit{dyn\_ttt\_xxx} subroutine.
 The user has the option of extracting and outputting each tendency term from the 3D momentum equations
 (\key{trddyn} defined), as described in \autoref{chap:MISC}.
 Furthermore, the tendency terms associated with the 2D barotropic vorticity balance (when \key{trdvor} is defined)
+(\texttt{trddyn?} defined), as described in \autoref{chap:MISC}.
+Furthermore, the tendency terms associated with the 2D barotropic vorticity balance (when \texttt{trdvor?} is defined)
 can be derived from the 3D terms.
 %%%
 \gmcomment{STEVEN: not quite sure I've got the sense of the last sentence. does
+\gmcomment{STEVEN: not quite sure I've got the sense of the last sentence. does
 MISC correspond to "extracting tendency terms" or "vorticity balance"?}
 …
 \label{subsec:DYN_divcur}
 The vorticity is defined at an $f$-point (\ie corner point) as follows:
+The vorticity is defined at an $f$-point (\ie\ corner point) as follows:
 \begin{equation}
   \label{eq:divcur_cur}
   \zeta =\frac{1}{e_{1f}\,e_{2f} }\left( {\;\delta_{i+1/2} \left[ {e_{2v}\;v} \right]
       -\delta_{j+1/2} \left[ {e_{1u}\;u} \right]\;} \right)
 \end{equation}
+\end{equation}
 The horizontal divergence is defined at a $T$-point.
 …
 ensure perfect restartability.
 The vorticity and divergence at the \textit{now} time step are used for the computation of
 the nonlinear advection and of the vertical velocity respectively.
+the nonlinear advection and of the vertical velocity respectively.
 %--------------------------------------------------------------------------------------------------------------
 …
   \end{aligned}
 \end{equation}
 where \textit{emp} is the surface freshwater budget (evaporation minus precipitation),
+where \textit{emp} is the surface freshwater budget (evaporation minus precipitation),
 expressed in Kg/m$^2$/s (which is equal to mm/s),
 and $\rho_w$=1,035~Kg/m$^3$ is the reference density of sea water (Boussinesq approximation).
 If river runoff is expressed as a surface freshwater flux (see \autoref{chap:SBC}) then
 \textit{emp} can be written as the evaporation minus precipitation, minus the river runoff.
+\textit{emp} can be written as the evaporation minus precipitation, minus the river runoff.
 The sea-surface height is evaluated using exactly the same time stepping scheme as
 the tracer equation \autoref{eq:tra_nxt}:
 a leapfrog scheme in combination with an Asselin time filter,
 \ie the velocity appearing in \autoref{eq:dynspg_ssh} is centred in time (\textit{now} velocity).
+\ie\ the velocity appearing in \autoref{eq:dynspg_ssh} is centred in time (\textit{now} velocity).
 This is of paramount importance.
 Replacing $T$ by the number $1$ in the tracer equation and summing over the water column must lead to
 …
 \end{equation}
 In the case of a non-linear free surface (\key{vvl}), the top vertical velocity is $-\textit{emp}/\rho_w$,
+In the case of a non-linear free surface (\texttt{vvl?}), the top vertical velocity is $-\textit{emp}/\rho_w$,
 as changes in the divergence of the barotropic transport are absorbed into the change of the level thicknesses,
 re-orientated downward.
 …
 The upper boundary condition applies at a fixed level $z=0$.
 The top vertical velocity is thus equal to the divergence of the barotropic transport
 (\ie the first term in the right-hand-side of \autoref{eq:dynspg_ssh}).
+(\ie\ the first term in the right-hand-side of \autoref{eq:dynspg_ssh}).
 Note also that whereas the vertical velocity has the same discrete expression in $z$- and $s$-coordinates,
 …
 Note also that the $k$-axis is re-orientated downwards in the \fortran code compared to
 the indexing used in the semi-discrete equations such as \autoref{eq:wzv}
 (see \autoref{subsec:DOM_Num_Index_vertical}).
+(see \autoref{subsec:DOM_Num_Index_vertical}).
 …
 %-----------------------------------------nam_dynadv----------------------------------------------------
 \nlst{namdyn_adv}
+\nlst{namdyn_adv}
 %-------------------------------------------------------------------------------------------------------------
 The vector invariant form of the momentum equations is the one most often used in
 applications of the \NEMO ocean model.
+applications of the \NEMO\ ocean model.
 The flux form option (see next section) has been present since version $2$.
 Options are defined through the \ngn{namdyn\_adv} namelist variables Coriolis and
+Options are defined through the \nam{dyn\_adv} namelist variables Coriolis and
 momentum advection terms are evaluated using a leapfrog scheme,
 \ie the velocity appearing in these expressions is centred in time (\textit{now} velocity).
+\ie\ the velocity appearing in these expressions is centred in time (\textit{now} velocity).
 At the lateral boundaries either free slip, no slip or partial slip boundary conditions are applied following
 \autoref{chap:LBC}.
 % -------------------------------------------------------------------------------------------------------------
 %        Vorticity term
+%        Vorticity term
 % -------------------------------------------------------------------------------------------------------------
 \subsection[Vorticity term (\textit{dynvor.F90})]
 …
 %------------------------------------------nam_dynvor----------------------------------------------------
 \nlst{namdyn_vor}
+\nlst{namdyn_vor}
 %-------------------------------------------------------------------------------------------------------------
 Options are defined through the \ngn{namdyn\_vor} namelist variables.
 Four discretisations of the vorticity term (\np{ln\_dynvor\_xxx}\forcode{ = .true.}) are available:
+Options are defined through the \nam{dyn\_vor} namelist variables.
+Four discretisations of the vorticity term (\texttt{ln\_dynvor\_xxx}\forcode{ = .true.}) are available:
 conserving potential enstrophy of horizontally non-divergent flow (ENS scheme);
 conserving horizontal kinetic energy (ENE scheme);
 …
 In the enstrophy conserving case (ENS scheme),
 the discrete formulation of the vorticity term provides a global conservation of the enstrophy
 ($ [ (\zeta +f ) / e_{3f} ]^2 $ in $s$-coordinates) for a horizontally non-divergent flow (\ie $\chi$=$0$),
+($ [ (\zeta +f ) / e_{3f} ]^2 $ in $s$-coordinates) for a horizontally non-divergent flow (\ie\ $\chi$=$0$),
 but does not conserve the total kinetic energy.
 It is given by:
 …
     \end{aligned}
   \right.
 \end{equation}
+\end{equation}
 %-------------------------------------------------------------
 …
     \end{aligned}
   \right.
 \end{equation}
+\end{equation}
 %-------------------------------------------------------------
 …
 the presence of grid point oscillation structures that will be invisible to the operator.
 These structures are \textit{computational modes} that will be at least partly damped by
 the momentum diffusion operator (\ie the subgrid-scale advection), but not by the resolved advection term.
+the momentum diffusion operator (\ie\ the subgrid-scale advection), but not by the resolved advection term.
 The ENS and ENE schemes therefore do not contribute to dump any grid point noise in the horizontal velocity field.
 Such noise would result in more noise in the vertical velocity field, an undesirable feature.
 …
 $u$ and $v$ are located at different grid points,
 a price worth paying to avoid a double averaging in the pressure gradient term as in the $B$-grid.
 \gmcomment{ To circumvent this, Adcroft (ADD REF HERE)
+\gmcomment{ To circumvent this, Adcroft (ADD REF HERE)
 Nevertheless, this technique strongly distort the phase and group velocity of Rossby waves....}
 …
 \citep{griffies.gnanadesikan.ea_JPO98} for the discretization of the iso-neutral diffusion operator (see \autoref{apdx:C}).
 The \citet{arakawa.hsu_MWR90} vorticity advection scheme for a single layer is modified
 for spherical coordinates as described by \citet{arakawa.lamb_MWR81} to obtain the EEN scheme.
 First consider the discrete expression of the potential vorticity, $q$, defined at an $f$-point:
+The \citet{arakawa.hsu_MWR90} vorticity advection scheme for a single layer is modified
+for spherical coordinates as described by \citet{arakawa.lamb_MWR81} to obtain the EEN scheme.
+First consider the discrete expression of the potential vorticity, $q$, defined at an $f$-point:
 \[
   % \label{eq:pot_vor}
 …
 \]
 where the relative vorticity is defined by (\autoref{eq:divcur_cur}),
 the Coriolis parameter is given by $f=2 \,\Omega \;\sin \varphi _f $ and the layer thickness at $f$-points is:
+the Coriolis parameter is given by $f=2 \,\Omega \;\sin \varphi _f $ and the layer thickness at $f$-points is:
 \begin{equation}
   \label{eq:een_e3f}
 …
 % >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 A key point in \autoref{eq:een_e3f} is how the averaging in the \textbf{i}- and \textbf{j}- directions is made.
+A key point in \autoref{eq:een_e3f} is how the averaging in the \textbf{i}- and \textbf{j}- directions is made.
 It uses the sum of masked t-point vertical scale factor divided either by the sum of the four t-point masks
 (\np{nn\_een\_e3f}\forcode{ = 1}), or just by $4$ (\np{nn\_een\_e3f}\forcode{ = .true.}).
 …
 (with a systematic reduction of $e_{3f}$ when a model level intercept the bathymetry)
 that tends to reinforce the topostrophy of the flow
 (\ie the tendency of the flow to follow the isobaths) \citep{penduff.le-sommer.ea_OS07}.
+(\ie\ the tendency of the flow to follow the isobaths) \citep{penduff.le-sommer.ea_OS07}.
 Next, the vorticity triads, $ {^i_j}\mathbb{Q}^{i_p}_{j_p}$ can be defined at a $T$-point as
 the following triad combinations of the neighbouring potential vorticities defined at f-points
 (\autoref{fig:DYN_een_triad}):
+(\autoref{fig:DYN_een_triad}):
 \begin{equation}
   \label{eq:Q_triads}
 …
   = \frac{1}{12} \ \left(   q^{i-i_p}_{j+j_p} + q^{i+j_p}_{j+i_p} + q^{i+i_p}_{j-j_p}  \right)
 \end{equation}
 where the indices $i_p$ and $k_p$ take the values: $i_p = -1/2$ or $1/2$ and $j_p = -1/2$ or $1/2$.
 Finally, the vorticity terms are represented as:
+where the indices $i_p$ and $k_p$ take the values: $i_p = -1/2$ or $1/2$ and $j_p = -1/2$ or $1/2$.
+Finally, the vorticity terms are represented as:
 \begin{equation}
   \label{eq:dynvor_een}
 …
       \end{aligned}
     } \right.
 \end{equation}
+\end{equation}
 This EEN scheme in fact combines the conservation properties of the ENS and ENE schemes.
 It conserves both total energy and potential enstrophy in the limit of horizontally nondivergent flow
 (\ie $\chi$=$0$) (see \autoref{subsec:C_vorEEN}).
+(\ie\ $\chi$=$0$) (see \autoref{subsec:C_vorEEN}).
 Applied to a realistic ocean configuration, it has been shown that it leads to a significant reduction of
 the noise in the vertical velocity field \citep{le-sommer.penduff.ea_OM09}.
 Furthermore, used in combination with a partial steps representation of bottom topography,
 it improves the interaction between current and topography,
 leading to a larger topostrophy of the flow \citep{barnier.madec.ea_OD06, penduff.le-sommer.ea_OS07}.
+leading to a larger topostrophy of the flow \citep{barnier.madec.ea_OD06, penduff.le-sommer.ea_OS07}.
 %--------------------------------------------------------------------------------------------------------------
 …
 When \np{ln\_dynzad\_zts}\forcode{ = .true.},
 a split-explicit time stepping with 5 sub-timesteps is used on the vertical advection term.
 This option can be useful when the value of the timestep is limited by vertical advection \citep{lemarie.debreu.ea_OM15}.
+This option can be useful when the value of the timestep is limited by vertical advection \citep{lemarie.debreu.ea_OM15}.
 Note that in this case,
 a similar split-explicit time stepping should be used on vertical advection of tracer to ensure a better stability,
 …
 %------------------------------------------nam_dynadv----------------------------------------------------
 \nlst{namdyn_adv}
+\nlst{namdyn_adv}
 %-------------------------------------------------------------------------------------------------------------
 Options are defined through the \ngn{namdyn\_adv} namelist variables.
+Options are defined through the \nam{dyn\_adv} namelist variables.
 In the flux form (as in the vector invariant form),
 the Coriolis and momentum advection terms are evaluated using a leapfrog scheme,
 \ie the velocity appearing in their expressions is centred in time (\textit{now} velocity).
+\ie\ the velocity appearing in their expressions is centred in time (\textit{now} velocity).
 At the lateral boundaries either free slip,
 no slip or partial slip boundary conditions are applied following \autoref{chap:LBC}.
 …
 In flux form, the vorticity term reduces to a Coriolis term in which the Coriolis parameter has been modified to account for the "metric" term.
 This altered Coriolis parameter is thus discretised at $f$-points.
 It is given by:
+It is given by:
 \begin{multline*}
   % \label{eq:dyncor_metric}
 …
   \equiv   f + \frac{1}{e_{1f} e_{2f} } \left( { \ \overline v ^{i+1/2}\delta_{i+1/2} \left[ {e_{2u} } \right]
       -  \overline u ^{j+1/2}\delta_{j+1/2} \left[ {e_{1u} } \right]  }  \ \right)
 \end{multline*}
+\end{multline*}
 Any of the (\autoref{eq:dynvor_ens}), (\autoref{eq:dynvor_ene}) and (\autoref{eq:dynvor_een}) schemes can be used to
 compute the product of the Coriolis parameter and the vorticity.
 However, the energy-conserving scheme (\autoref{eq:dynvor_een}) has exclusively been used to date.
 This term is evaluated using a leapfrog scheme, \ie the velocity is centred in time (\textit{now} velocity).
+This term is evaluated using a leapfrog scheme, \ie\ the velocity is centred in time (\textit{now} velocity).
 %--------------------------------------------------------------------------------------------------------------
 …
 or a $3^{rd}$ order upstream biased scheme, UBS.
 The latter is described in \citet{shchepetkin.mcwilliams_OM05}.
 The schemes are selected using the namelist logicals \np{ln\_dynadv\_cen2} and \np{ln\_dynadv\_ubs}.
+The schemes are selected using the namelist logicals \np{ln\_dynadv\_cen2} and \np{ln\_dynadv\_ubs}.
 In flux form, the schemes differ by the choice of a space and time interpolation to define the value of
 $u$ and $v$ at the centre of each face of $u$- and $v$-cells, \ie at the $T$-, $f$-,
 and $uw$-points for $u$ and at the $f$-, $T$- and $vw$-points for $v$.
+$u$ and $v$ at the centre of each face of $u$- and $v$-cells, \ie\ at the $T$-, $f$-,
+and $uw$-points for $u$ and at the $f$-, $T$- and $vw$-points for $v$.
 %-------------------------------------------------------------
 …
     \end{aligned}
   \right.
 \end{equation}
 The scheme is non diffusive (\ie conserves the kinetic energy) but dispersive (\ie it may create false extrema).
+\end{equation}
+The scheme is non diffusive (\ie\ conserves the kinetic energy) but dispersive (\ie\ it may create false extrema).
 It is therefore notoriously noisy and must be used in conjunction with an explicit diffusion operator to
 produce a sensible solution.
 …
 \end{equation}
 where $u"_{i+1/2} =\delta_{i+1/2} \left[ {\delta_i \left[ u \right]} \right]$.
 This results in a dissipatively dominant (\ie hyper-diffusive) truncation error
+This results in a dissipatively dominant (\ie\ hyper-diffusive) truncation error
 \citep{shchepetkin.mcwilliams_OM05}.
 The overall performance of the advection scheme is similar to that reported in \citet{farrow.stevens_JPO95}.
 …
 It is not a \emph{positive} scheme, meaning that false extrema are permitted.
 But the amplitudes of the false extrema are significantly reduced over those in the centred second order method.
 As the scheme already includes a diffusion component, it can be used without explicit lateral diffusion on momentum
 (\ie \np{ln\_dynldf\_lap}\forcode{ = }\np{ln\_dynldf\_bilap}\forcode{ = .false.}),
+As the scheme already includes a diffusion component, it can be used without explicit lateral diffusion on momentum
+(\ie\ \np{ln\_dynldf\_lap}\forcode{ = }\np{ln\_dynldf\_bilap}\forcode{ = .false.}),
 and it is recommended to do so.
 The UBS scheme is not used in all directions.
 In the vertical, the centred $2^{nd}$ order evaluation of the advection is preferred, \ie $u_{uw}^{ubs}$ and
+In the vertical, the centred $2^{nd}$ order evaluation of the advection is preferred, \ie\ $u_{uw}^{ubs}$ and
 $u_{vw}^{ubs}$ in \autoref{eq:dynadv_cen2} are used.
 UBS is diffusive and is associated with vertical mixing of momentum. \gmcomment{ gm  pursue the
+UBS is diffusive and is associated with vertical mixing of momentum. \gmcomment{ gm  pursue the
 sentence:Since vertical mixing of momentum is a source term of the TKE equation...  }
 …
 %------------------------------------------nam_dynhpg---------------------------------------------------
 \nlst{namdyn_hpg}
+\nlst{namdyn_hpg}
 %-------------------------------------------------------------------------------------------------------------
 Options are defined through the \ngn{namdyn\_hpg} namelist variables.
+Options are defined through the \nam{dyn\_hpg} namelist variables.
 The key distinction between the different algorithms used for
 the hydrostatic pressure gradient is the vertical coordinate used,
 since HPG is a \emph{horizontal} pressure gradient, \ie computed along geopotential surfaces.
+since HPG is a \emph{horizontal} pressure gradient, \ie\ computed along geopotential surfaces.
 As a result, any tilt of the surface of the computational levels will require a specific treatment to
 compute the hydrostatic pressure gradient.
 The hydrostatic pressure gradient term is evaluated either using a leapfrog scheme,
 \ie the density appearing in its expression is centred in time (\emph{now} $\rho$),
+\ie\ the density appearing in its expression is centred in time (\emph{now} $\rho$),
 or a semi-implcit scheme.
 At the lateral boundaries either free slip, no slip or partial slip boundary conditions are applied.
 …
     \end{aligned}
   \right.
 \end{equation}
+\end{equation}
 for $1<k<km$ (interior layer)
 …
     \end{aligned}
   \right.
 \end{equation}
+\end{equation}
 Note that the $1/2$ factor in (\autoref{eq:dynhpg_zco_surf}) is adequate because of the definition of $e_{3w}$ as
 the vertical derivative of the scale factor at the surface level ($z=0$).
 Note also that in case of variable volume level (\key{vvl} defined),
+Note also that in case of variable volume level (\texttt{vvl?} defined),
 the surface pressure gradient is included in \autoref{eq:dynhpg_zco_surf} and
 \autoref{eq:dynhpg_zco} through the space and time variations of the vertical scale factor $e_{3w}$.
 …
 Before taking horizontal gradients between these tracer points,
 a linear interpolation is used to approximate the deeper tracer as if
 it actually lived at the depth of the shallower tracer point.
+it actually lived at the depth of the shallower tracer point.
 Apart from this modification,
 …
 Pressure gradient formulations in an $s$-coordinate have been the subject of a vast number of papers
 (\eg, \citet{song_MWR98, shchepetkin.mcwilliams_OM05}).
+(\eg, \citet{song_MWR98, shchepetkin.mcwilliams_OM05}).
 A number of different pressure gradient options are coded but the ROMS-like,
 density Jacobian with cubic polynomial method is currently disabled whilst known bugs are under investigation.
 …
     \end{aligned}
   \right.
 \end{equation}
+\end{equation}
 Where the first term is the pressure gradient along coordinates,
 computed as in \autoref{eq:dynhpg_zco_surf} - \autoref{eq:dynhpg_zco},
 and $z_T$ is the depth of the $T$-point evaluated from the sum of the vertical scale factors at the $w$-point
+and $z_T$ is the depth of the $T$-point evaluated from the sum of the vertical scale factors at the $w$-point
 ($e_{3w}$).
 $\bullet$ Traditional coding with adaptation for ice shelf cavities (\np{ln\_dynhpg\_isf}\forcode{ = .true.}).
 This scheme need the activation of ice shelf cavities (\np{ln\_isfcav}\forcode{ = .true.}).
 …
 $\bullet$ Pressure Jacobian scheme (prj) (a research paper in preparation) (\np{ln\_dynhpg\_prj}\forcode{ = .true.})
 $\bullet$ Density Jacobian with cubic polynomial scheme (DJC) \citep{shchepetkin.mcwilliams_OM05}
+$\bullet$ Density Jacobian with cubic polynomial scheme (DJC) \citep{shchepetkin.mcwilliams_OM05}
 (\np{ln\_dynhpg\_djc}\forcode{ = .true.}) (currently disabled; under development)
 Note that expression \autoref{eq:dynhpg_sco} is commonly used when the variable volume formulation is activated
 (\key{vvl}) because in that case, even with a flat bottom,
+(\texttt{vvl?}) because in that case, even with a flat bottom,
 the coordinate surfaces are not horizontal but follow the free surface \citep{levier.treguier.ea_rpt07}.
 The pressure jacobian scheme (\np{ln\_dynhpg\_prj}\forcode{ = .true.}) is available as
 an improved option to \np{ln\_dynhpg\_sco}\forcode{ = .true.} when \key{vvl} is active.
+an improved option to \np{ln\_dynhpg\_sco}\forcode{ = .true.} when \texttt{vvl?} is active.
 The pressure Jacobian scheme uses a constrained cubic spline to
 reconstruct the density profile across the water column.
 …
 The pressure gradient due to ocean load is computed using the expression \autoref{eq:dynhpg_sco} described in
 \autoref{subsec:DYN_hpg_sco}.
+\autoref{subsec:DYN_hpg_sco}.
 %--------------------------------------------------------------------------------------------------------------
 …
 It involves the evaluation of the hydrostatic pressure gradient as
 an average over the three time levels $t-\rdt$, $t$, and $t+\rdt$
 (\ie \textit{before}, \textit{now} and  \textit{after} time-steps),
 rather than at the central time level $t$ only, as in the standard leapfrog scheme.
+(\ie\ \textit{before}, \textit{now} and  \textit{after} time-steps),
+rather than at the central time level $t$ only, as in the standard leapfrog scheme.
 $\bullet$ leapfrog scheme (\np{ln\_dynhpg\_imp}\forcode{ = .true.}):
 …
 %-----------------------------------------nam_dynspg----------------------------------------------------
 \nlst{namdyn_spg}
+\nlst{namdyn_spg}
 %------------------------------------------------------------------------------------------------------------
 Options are defined through the \ngn{namdyn\_spg} namelist variables.
+Options are defined through the \nam{dyn\_spg} namelist variables.
 The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:PE_hor_pg}).
 The main distinction is between the fixed volume case (linear free surface) and
 the variable volume case (nonlinear free surface, \key{vvl} is defined).
+the variable volume case (nonlinear free surface, \texttt{vvl?} is defined).
 In the linear free surface case (\autoref{subsec:PE_free_surface})
 the vertical scale factors $e_{3}$ are fixed in time,
 while they are time-dependent in the nonlinear case (\autoref{subsec:PE_free_surface}).
 With both linear and nonlinear free surface, external gravity waves are allowed in the equations,
+With both linear and nonlinear free surface, external gravity waves are allowed in the equations,
 which imposes a very small time step when an explicit time stepping is used.
 Two methods are proposed to allow a longer time step for the three-dimensional equations:
 the filtered free surface, which is a modification of the continuous equations (see \autoref{eq:PE_flt?}),
+Two methods are proposed to allow a longer time step for the three-dimensional equations:
+the filtered free surface, which is a modification of the continuous equations (see \autoref{eq:PE_flt?}),
 and the split-explicit free surface described below.
 The extra term introduced in the filtered method is calculated implicitly,
+The extra term introduced in the filtered method is calculated implicitly,
 so that the update of the next velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}.
 …
 an explicit formulation which requires a small time step;
 a filtered free surface formulation which allows a larger time step by
 adding a filtering term into the momentum equation;
+adding a filtering term into the momentum equation;
 and a split-explicit free surface formulation, described below, which also allows a larger time step.
 …
 % Explicit free surface formulation
 %--------------------------------------------------------------------------------------------------------------
 \subsection[Explicit free surface (\texttt{\textbf{key\_dynspg\_exp}})]
 {Explicit free surface (\protect\key{dynspg\_exp})}
+\subsection[Explicit free surface (\texttt{ln\_dynspg\_exp}\forcode{ = .true.})]
+{Explicit free surface (\protect\np{ln\_dynspg\_exp}\forcode{ = .true.})}
 \label{subsec:DYN_spg_exp}
 In the explicit free surface formulation (\key{dynspg\_exp} defined),
+In the explicit free surface formulation (\np{ln\_dynspg\_exp} set to true),
 the model time step is chosen to be small enough to resolve the external gravity waves
 (typically a few tens of seconds).
 The surface pressure gradient, evaluated using a leap-frog scheme (\ie centered in time),
+The surface pressure gradient, evaluated using a leap-frog scheme (\ie\ centered in time),
 is thus simply given by :
 \begin{equation}
 …
     \end{aligned}
   \right.
 \end{equation}
 Note that in the non-linear free surface case (\ie \key{vvl} defined),
+\end{equation}
+Note that in the non-linear free surface case (\ie\ \texttt{vvl?} defined),
 the surface pressure gradient is already included in the momentum tendency through
 the level thickness variation allowed in the computation of the hydrostatic pressure gradient.
 …
 % Split-explict free surface formulation
 %--------------------------------------------------------------------------------------------------------------
 \subsection[Split-explicit free surface (\texttt{\textbf{key\_dynspg\_ts}})]
 {Split-explicit free surface (\protect\key{dynspg\_ts})}
+\subsection[Split-explicit free surface (\texttt{ln\_dynspg\_ts}\forcode{ = .true.})]
+{Split-explicit free surface (\protect\np{ln\_dynspg\_ts}\forcode{ = .true.})}
 \label{subsec:DYN_spg_ts}
 %------------------------------------------namsplit-----------------------------------------------------------
 …
 %-------------------------------------------------------------------------------------------------------------
 The split-explicit free surface formulation used in \NEMO (\key{dynspg\_ts} defined),
+The split-explicit free surface formulation used in \NEMO\ (\np{ln\_dynspg\_ts} set to true),
 also called the time-splitting formulation, follows the one proposed by \citet{shchepetkin.mcwilliams_OM05}.
 The general idea is to solve the free surface equation and the associated barotropic velocity equations with
 …
 Temporal discretization of the system above follows a three-time step Generalized Forward Backward algorithm
 detailed in \citet{shchepetkin.mcwilliams_OM05}.
 AB3-AM4 coefficients used in \NEMO follow the second-order accurate,
+AB3-AM4 coefficients used in \NEMO\ follow the second-order accurate,
 "multi-purpose" stability compromise as defined in \citet{shchepetkin.mcwilliams_ibk09}
 (see their figure 12, lower left).
+(see their figure 12, lower left).
 %>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >
 …
 provide time filtered quantities.
 These are used for the subsequent initialization of the barotropic mode in the following baroclinic step.
 Since external mode equations written at baroclinic time steps finally follow a forward time stepping scheme,
+Since external mode equations written at baroclinic time steps finally follow a forward time stepping scheme,
 asselin filtering is not applied to barotropic quantities.\\
 Alternatively, one can choose to integrate barotropic equations starting from \textit{before} time step
 …
 One can eventually choose to feedback instantaneous values by not using any time filter
 (\np{ln\_bt\_av}\forcode{ = .false.}).
+(\np{ln\_bt\_av}\forcode{ = .false.}).
 In that case, external mode equations are continuous in time,
 \ie they are not re-initialized when starting a new sub-stepping sequence.
+\ie\ they are not re-initialized when starting a new sub-stepping sequence.
 This is the method used so far in the POM model, the stability being maintained by
 refreshing at (almost) each barotropic time step advection and horizontal diffusion terms.
 Since the latter terms have not been added in \NEMO for computational efficiency,
+Since the latter terms have not been added in \NEMO\ for computational efficiency,
 removing time filtering is not recommended except for debugging purposes.
 This may be used for instance to appreciate the damping effect of the standard formulation on
 …
 %>>>>>===============
 \gmcomment{               %%% copy from griffies Book
+\gmcomment{               %%% copy from griffies Book
 \textbf{title: Time stepping the barotropic system }
 …
 Hence, we can update the surface height and vertically integrated velocity with a leap-frog scheme using
 the small barotropic time step $\rdt$.
 We have
+We have
 \[
 …
 and total depth of the ocean $H(\tau)$ are held for the duration of the barotropic time stepping over
 a single cycle.
 This is also the time that sets the barotropic time steps via
+This is also the time that sets the barotropic time steps via
 \[
   % \label{eq:DYN_spg_ts_t}
 …
 \]
 with $n$ an integer.
 The density scaled surface pressure is evaluated via
+The density scaled surface pressure is evaluated via
 \[
   % \label{eq:DYN_spg_ts_ps}
 …
   \end{cases}
 \]
 To get started, we assume the following initial conditions
+To get started, we assume the following initial conditions
 \[
   % \label{eq:DYN_spg_ts_eta}
 …
   \end{split}
 \]
 with
+with
 \[
   % \label{eq:DYN_spg_ts_etaF}
 …
 \]
 the time averaged surface height taken from the previous barotropic cycle.
 Likewise,
+Likewise,
 \[
   % \label{eq:DYN_spg_ts_u}
 …
   \textbf{U}(\tau,t_{n=1}) = \textbf{U}^{(b)}(\tau,t_{n=0}) + \rdt \ \text{RHS}_{n=0}
 \]
 with
+with
 \[
   % \label{eq:DYN_spg_ts_u}
 …
 \]
 the time averaged vertically integrated transport.
 Notably, there is no Robert-Asselin time filter used in the barotropic portion of the integration.
+Notably, there is no Robert-Asselin time filter used in the barotropic portion of the integration.
 Upon reaching $t_{n=N} = \tau + 2\rdt \tau$ ,
 the vertically integrated velocity is time averaged to produce the updated vertically integrated velocity at
 baroclinic time $\tau + \rdt \tau$
+baroclinic time $\tau + \rdt \tau$
 \[
   % \label{eq:DYN_spg_ts_u}
 …
 \]
 The surface height on the new baroclinic time step is then determined via a baroclinic leap-frog using
 the following form
+the following form
 \begin{equation}
   \label{eq:DYN_spg_ts_ssh}
   \eta(\tau+\Delta) - \eta^{F}(\tau-\Delta) = 2\rdt \ \left[ - \nabla \cdot \textbf{U}(\tau) + \text{EMP}_w \right]
+  \eta(\tau+\Delta) - \eta^{F}(\tau-\Delta) = 2\rdt \ \left[ - \nabla \cdot \textbf{U}(\tau) + \text{EMP}_w \right]
 \end{equation}
 The use of this "big-leap-frog" scheme for the surface height ensures compatibility between
 the mass/volume budgets and the tracer budgets.
 More discussion of this point is provided in Chapter 10 (see in particular Section 10.2).
+More discussion of this point is provided in Chapter 10 (see in particular Section 10.2).
 In general, some form of time filter is needed to maintain integrity of the surface height field due to
 the leap-frog splitting mode in equation \autoref{eq:DYN_spg_ts_ssh}.
 …
   \eta^{F}(\tau-\Delta) =  \overline{\eta^{(b)}(\tau)}
 \end{equation}
 Another approach tried was
+Another approach tried was
 \[
 …
 eliminating tracer and surface height time filtering (see ?? for more complete discussion).
 However, in the general case with a non-zero $\alpha$,
 the filter \autoref{eq:DYN_spg_ts_sshf} was found to be more conservative, and so is recommended.
+the filter \autoref{eq:DYN_spg_ts_sshf} was found to be more conservative, and so is recommended.
 }            %%end gm comment (copy of griffies book)
 …
 % Filtered free surface formulation
 %--------------------------------------------------------------------------------------------------------------
 \subsection[Filtered free surface (\texttt{\textbf{key\_dynspg\_flt}})]
 {Filtered free surface (\protect\key{dynspg\_flt})}
+\subsection[Filtered free surface (\texttt{dynspg\_flt?})]
+{Filtered free surface (\protect\texttt{dynspg\_flt?})}
 \label{subsec:DYN_spg_fltp}
 The filtered formulation follows the \citet{roullet.madec_JGR00} implementation.
 The extra term introduced in the equations (see \autoref{subsec:PE_free_surface}) is solved implicitly.
+The filtered formulation follows the \citet{roullet.madec_JGR00} implementation.
+The extra term introduced in the equations (see \autoref{subsec:PE_free_surface}) is solved implicitly.
 The elliptic solvers available in the code are documented in \autoref{chap:MISC}.
 %% gm %%======>>>>   given here the discrete eqs provided to the solver
 \gmcomment{               %%% copy from chap-model basics
+\gmcomment{               %%% copy from chap-model basics
   \[
     % \label{eq:spg_flt}
 …
 }   %end gmcomment
 Note that in the linear free surface formulation (\key{vvl} not defined),
+Note that in the linear free surface formulation (\texttt{vvl?} not defined),
 the ocean depth is time-independent and so is the matrix to be inverted.
 It is computed once and for all and applies to all ocean time steps.
+It is computed once and for all and applies to all ocean time steps.
 % ================================================================
 …
 %------------------------------------------nam_dynldf----------------------------------------------------
 \nlst{namdyn_ldf}
+\nlst{namdyn_ldf}
 %-------------------------------------------------------------------------------------------------------------
 Options are defined through the \ngn{namdyn\_ldf} namelist variables.
+Options are defined through the \nam{dyn\_ldf} namelist variables.
 The options available for lateral diffusion are to use either laplacian (rotated or not) or biharmonic operators.
 The coefficients may be constant or spatially variable;
 the description of the coefficients is found in the chapter on lateral physics (\autoref{chap:LDF}).
 The lateral diffusion of momentum is evaluated using a forward scheme,
 \ie the velocity appearing in its expression is the \textit{before} velocity in time,
+\ie\ the velocity appearing in its expression is the \textit{before} velocity in time,
 except for the pure vertical component that appears when a tensor of rotation is used.
 This latter term is solved implicitly together with the vertical diffusion term (see \autoref{chap:STP}).
 …
   In finite difference methods,
   the biharmonic operator is frequently the method of choice to achieve this scale selective dissipation since
   its damping time (\ie its spin down time) scale like $\lambda^{-4}$ for disturbances of wavelength $\lambda$
+  its damping time (\ie\ its spin down time) scale like $\lambda^{-4}$ for disturbances of wavelength $\lambda$
   (so that short waves damped more rapidelly than long ones),
   whereas the Laplace operator damping time scales only like $\lambda^{-2}$.
 …
 \label{subsec:DYN_ldf_lap}
 For lateral iso-level diffusion, the discrete operator is:
+For lateral iso-level diffusion, the discrete operator is:
 \begin{equation}
   \label{eq:dynldf_lap}
 …
     \begin{aligned}
       D_u^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{1u} }\delta_{i+1/2} \left[ {A_T^{lm}
           \;\chi } \right]-\frac{1}{e_{2u} {\kern 1pt}e_{3u} }\delta_j \left[
+          \;\chi } \right]-\frac{1}{e_{2u} {\kern 1pt}e_{3u} }\delta_j \left[
         {A_f^{lm} \;e_{3f} \zeta } \right] \\ \\
       D_v^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{2v} }\delta_{j+1/2} \left[ {A_T^{lm}
           \;\chi } \right]+\frac{1}{e_{1v} {\kern 1pt}e_{3v} }\delta_i \left[
+          \;\chi } \right]+\frac{1}{e_{1v} {\kern 1pt}e_{3v} }\delta_i \left[
         {A_f^{lm} \;e_{3f} \zeta } \right]
     \end{aligned}
   \right.
 \end{equation}
+\end{equation}
 As explained in \autoref{subsec:PE_ldf},
 this formulation (as the gradient of a divergence and curl of the vorticity) preserves symmetry and
 ensures a complete separation between the vorticity and divergence parts of the momentum diffusion.
+ensures a complete separation between the vorticity and divergence parts of the momentum diffusion.
 %--------------------------------------------------------------------------------------------------------------
 …
                 -e_{2f} \; r_{1f} \,\overline{\overline {\delta_{k+1/2}[v]}}^{\,i+1/2,\,k}}
             \right)} \right]}    \right. \\
     & \qquad +\ \delta_j \left[ {A_T^{lm} \left( {\frac{e_{1t}\,e_{3t} }{e_{2t}
+    & \qquad +\ \delta_j \left[ {A_T^{lm} \left( {\frac{e_{1t}\,e_{3t} }{e_{2t}
             }\,\delta_{j} [v] - e_{1t}\, r_{2t}
             \,\overline{\overline {\delta_{k+1/2} [v]}} ^{\,j,\,k}}
         \right)} \right] \\
     & \qquad +\ \delta_k \left[ {A_{vw}^{lm} \left( {-e_{2v} \, r_{1vw} \,\overline{\overline
+    & \qquad +\ \delta_k \left[ {A_{vw}^{lm} \left( {-e_{2v} \, r_{1vw} \,\overline{\overline
               {\delta_{i+1/2} [v]}}^{\,i+1/2,\,k+1/2} }\right.} \right. \\
     &  \ \qquad \qquad \qquad \quad\
     - e_{1v} \, r_{2vw} \,\overline{\overline {\delta_{j+1/2} [v]}} ^{\,j+1/2,\,k+1/2} \\
     & \left. {\left. { \ \qquad \qquad \qquad \ \ \ \left. {\
+    & \left. {\left. { \ \qquad \qquad \qquad \ \ \ \left. {\
                 +\frac{e_{1v}\, e_{2v} }{e_{3vw} }\,\left( {r_{1vw}^2+r_{2vw}^2}
                 \right)\,\delta_{k+1/2} [v]} \right)} \right]\;\;\;} \right\}
+                \right)\,\delta_{k+1/2} [v]} \right)} \right]\;\;\;} \right\}
   \end{split}
 \end{equation}
 where $r_1$ and $r_2$ are the slopes between the surface along which the diffusion operator acts and
 the surface of computation ($z$- or $s$-surfaces).
+the surface of computation ($z$- or $s$-surfaces).
 The way these slopes are evaluated is given in the lateral physics chapter (\autoref{chap:LDF}).
 …
 %----------------------------------------------namzdf------------------------------------------------------
 \nlst{namzdf}
+\nlst{namzdf}
 %-------------------------------------------------------------------------------------------------------------
 Options are defined through the \ngn{namzdf} namelist variables.
+Options are defined through the \nam{zdf} namelist variables.
 The large vertical diffusion coefficient found in the surface mixed layer together with high vertical resolution implies that in the case of explicit time stepping there would be too restrictive a constraint on the time step.
 Two time stepping schemes can be used for the vertical diffusion term:
 …
 $(b)$ a backward (or implicit) time differencing scheme (\np{ln\_zdfexp}\forcode{ = .false.})
 (see \autoref{chap:STP}).
 Note that namelist variables \np{ln\_zdfexp} and \np{nn\_zdfexp} apply to both tracers and dynamics.
+Note that namelist variables \np{ln\_zdfexp} and \np{nn\_zdfexp} apply to both tracers and dynamics.
 The formulation of the vertical subgrid scale physics is the same whatever the vertical coordinate is.
 …
 where $\left( \tau_u ,\tau_v \right)$ are the two components of the wind stress vector in
 the (\textbf{i},\textbf{j}) coordinate system.
 The high mixing coefficients in the surface mixed layer ensure that the surface wind stress is distributed in
+The high mixing coefficients in the surface mixed layer ensure that the surface wind stress is distributed in
 the vertical over the mixed layer depth.
 If the vertical mixing coefficient is small (when no mixed layer scheme is used)
 …
 Besides the surface and bottom stresses (see the above section)
 which are introduced as boundary conditions on the vertical mixing,
 three other forcings may enter the dynamical equations by affecting the surface pressure gradient.
+three other forcings may enter the dynamical equations by affecting the surface pressure gradient.
 (1) When \np{ln\_apr\_dyn}\forcode{ = .true.} (see \autoref{sec:SBC_apr}),
 …
 (3) When \np{nn\_ice\_embd}\forcode{ = 2} and LIM or CICE is used
 (\ie when the sea-ice is embedded in the ocean),
+(\ie\ when the sea-ice is embedded in the ocean),
 the snow-ice mass is taken into account when computing the surface pressure gradient.
 …
 % ================================================================
 % Wetting and drying
+% Wetting and drying
 % ================================================================
 \section{Wetting and drying }
 …
 The following terminology is used. The depth of the topography (positive downwards)
 at each $(i,j)$ point is the quantity stored in array $\mathrm{ht\_wd}$ in the NEMO code.
+at each $(i,j)$ point is the quantity stored in array $\mathrm{ht\_wd}$ in the \NEMO\ code.
 The height of the free surface (positive upwards) is denoted by $ \mathrm{ssh}$. Given the sign
 conventions used, the water depth, $h$, is the height of the free surface plus the depth of the
 …
 covered by water. They require the topography specified with a model
 configuration to have negative depths at points where the land is higher than the
 topography's reference sea-level. The vertical grid in NEMO is normally computed relative to an
+topography's reference sea-level. The vertical grid in \NEMO\ is normally computed relative to an
 initial state with zero sea surface height elevation.
 The user can choose to compute the vertical grid and heights in the model relative to
 …
 All these configurations have used pure sigma coordinates. It is expected that
 the wetting and drying code will work in domains with more general s-coordinates provided
 the coordinates are pure sigma in the region where wetting and drying actually occurs.
+the coordinates are pure sigma in the region where wetting and drying actually occurs.
 The next sub-section descrbies the directional limiter and the following sub-section the iterative limiter.
 …
 \label{subsec:DYN_wd_directional_limiter}
 The principal idea of the directional limiter is that
 water should not be allowed to flow out of a dry tracer cell (i.e. one whose water depth is less than rn\_wdmin1).
+water should not be allowed to flow out of a dry tracer cell (i.e. one whose water depth is less than \np{rn\_wdmin1}).
 All the changes associated with this option are made to the barotropic solver for the non-linear
 …
 The flux across each $u$-face of a tracer cell is multiplied by a factor zuwdmask (an array which depends on ji and jj).
 If the user sets ln\_wd\_dl\_ramp = .False. then zuwdmask is 1 when the
 flux is from a cell with water depth greater than rn\_wdmin1 and 0 otherwise. If the user sets
 ln\_wd\_dl\_ramp = .True. the flux across the face is ramped down as the water depth decreases
 from 2 * rn\_wdmin1 to rn\_wdmin1. The use of this ramp reduced grid-scale noise in idealised test cases.
+If the user sets \np{ln\_wd\_dl\_ramp}\forcode{ = .false.} then zuwdmask is 1 when the
+flux is from a cell with water depth greater than \np{rn\_wdmin1} and 0 otherwise. If the user sets
+\np{ln\_wd\_dl\_ramp}\forcode{ = .true.} the flux across the face is ramped down as the water depth decreases
+from 2 * \np{rn\_wdmin1} to \np{rn\_wdmin1}. The use of this ramp reduced grid-scale noise in idealised test cases.
 At the point where the flux across a $u$-face is multiplied by zuwdmask , we have chosen
 …
 fields (tracers independent of $x$, $y$ and $z$). Our scheme conserves constant tracers because
 the velocities used at the tracer cell faces on the baroclinic timesteps are carefully calculated by dynspg\_ts
 to equal their mean value during the barotropic steps. If the user sets ln\_wd\_dl\_bc = .True., the
 baroclinic velocities are also multiplied by a suitably weighted average of zuwdmask.
+to equal their mean value during the barotropic steps. If the user sets \np{ln\_wd\_dl\_bc}\forcode{ = .true.}, the
+baroclinic velocities are also multiplied by a suitably weighted average of zuwdmask.
 %-----------------------------------------------------------------------------------------
 …
 \begin{align} \label{dyn_wd_continuity_2}
 \frac{e_1 e_2}{\Delta t} ( h_{i,j}(t_{n+1}) - h_{i,j}(t_e) )
+\frac{e_1 e_2}{\Delta t} ( h_{i,j}(t_{n+1}) - h_{i,j}(t_e) )
 &= - ( \mathrm{flxu}_{i+1,j} - \mathrm{flxu}_{i,j}  + \mathrm{flxv}_{i,j+1} - \mathrm{flxv}_{i,j} ) \\
 &= \mathrm{zzflx}_{i,j} .
 …
 \begin{equation} \label{dyn_wd_zzflx_p_n_1}
 \mathrm{zzflx}_{i,j} = \mathrm{zzflxp}_{i,j} + \mathrm{zzflxn}_{i,j} .
+\mathrm{zzflx}_{i,j} = \mathrm{zzflxp}_{i,j} + \mathrm{zzflxn}_{i,j} .
 \end{equation}
 …
 \begin{equation} \label{dyn_wd_zzflx_initial}
 \mathrm{zzflxp^{(0)}}_{i,j} = \mathrm{zzflxp}_{i,j} , \quad  \mathrm{zzflxn^{(0)}}_{i,j} = \mathrm{zzflxn}_{i,j} .
+\mathrm{zzflxp^{(0)}}_{i,j} = \mathrm{zzflxp}_{i,j} , \quad  \mathrm{zzflxn^{(0)}}_{i,j} = \mathrm{zzflxn}_{i,j} .
 \end{equation}
 …
 \begin{split}
 \mathrm{zcoef}^{(m+1)}_{i,j} = \Big[ (h_{i,j}(t_e) & - \mathrm{rn\_wdmin1} - \mathrm{rn\_wdmin2})  \frac{e_1 e_2}{\Delta t} \phantom{]} \\
 \phantom{[} & -  \mathrm{zzflxn}^{(m)}_{i,j} \Big] \frac{1}{ \mathrm{zzflxp}^{(0)}_{i,j} }
+\phantom{[} & -  \mathrm{zzflxn}^{(m)}_{i,j} \Big] \frac{1}{ \mathrm{zzflxp}^{(0)}_{i,j} }
 \end{split}
 \end{equation}
 …
 % ================================================================
 % Time evolution term
+% Time evolution term
 % ================================================================
 \section[Time evolution term (\textit{dynnxt.F90})]
 …
 %----------------------------------------------namdom----------------------------------------------------
 \nlst{namdom}
+\nlst{namdom}
 %-------------------------------------------------------------------------------------------------------------
 Options are defined through the \ngn{namdom} namelist variables.
+Options are defined through the \nam{dom} namelist variables.
 The general framework for dynamics time stepping is a leap-frog scheme,
 \ie a three level centred time scheme associated with an Asselin time filter (cf. \autoref{chap:STP}).
+\ie\ a three level centred time scheme associated with an Asselin time filter (cf. \autoref{chap:STP}).
 The scheme is applied to the velocity, except when
 using the flux form of momentum advection (cf. \autoref{sec:DYN_adv_cor_flux})
 in the variable volume case (\key{vvl} defined),
 where it has to be applied to the thickness weighted velocity (see \autoref{sec:A_momentum})
+in the variable volume case (\texttt{vvl?} defined),
+where it has to be applied to the thickness weighted velocity (see \autoref{sec:A_momentum})
 $\bullet$ vector invariant form or linear free surface
 (\np{ln\_dynhpg\_vec}\forcode{ = .true.} ; \key{vvl} not defined):
+(\np{ln\_dynhpg\_vec}\forcode{ = .true.} ; \texttt{vvl?} not defined):
 \[
   % \label{eq:dynnxt_vec}
 …
 $\bullet$ flux form and nonlinear free surface
 (\np{ln\_dynhpg\_vec}\forcode{ = .false.} ; \key{vvl} defined):
+(\np{ln\_dynhpg\_vec}\forcode{ = .false.} ; \texttt{vvl?} defined):
 \[
   % \label{eq:dynnxt_flux}

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_LBC.tex

-                      r11263
+                      r11512
 \begin{document}
 % ================================================================
 % Chapter — Lateral Boundary Condition (LBC)
+% Chapter — Lateral Boundary Condition (LBC)
 % ================================================================
 \chapter{Lateral Boundary Condition (LBC)}
 \label{chap:LBC}
 \minitoc
+\chaptertoc
 \newpage
 …
 %--------------------------------------------nam_lbc-------------------------------------------------------
 \nlst{namlbc}
+\nlst{namlbc}
 %--------------------------------------------------------------------------------------------------------------
+%The lateral ocean boundary conditions contiguous to coastlines are Neumann conditions for heat and salt (no flux across boundaries) and Dirichlet conditions for momentum (ranging from free-slip to "strong" no-slip). They are handled automatically by the mask system (see \autoref{subsec:DOM_msk}).
+%OPA allows land and topography grid points in the computational domain due to the presence of continents or islands, and includes the use of a full or partial step representation of bottom topography. The computation is performed over the whole domain, \ie we do not try to restrict the computation to ocean-only points. This choice has two motivations. Firstly, working on ocean only grid points overloads the code and harms the code readability. Secondly, and more importantly, it drastically reduces the vector portion of the computation, leading to a dramatic increase of CPU time requirement on vector computers.  The current section describes how the masking affects the computation of the various terms of the equations with respect to the boundary condition at solid walls. The process of defining which areas are to be masked is described in \autoref{subsec:DOM_msk}.
+Options are defined through the \ngn{namlbc} namelist variables.
+%The lateral ocean boundary conditions contiguous to coastlines are Neumann conditions for heat and salt
+%(no flux across boundaries) and Dirichlet conditions for momentum (ranging from free-slip to "strong" no-slip).
+%They are handled automatically by the mask system (see \autoref{subsec:DOM_msk}).
+%OPA allows land and topography grid points in the computational domain due to the presence of continents or islands,
+%and includes the use of a full or partial step representation of bottom topography.
+%The computation is performed over the whole domain, \ie\ we do not try to restrict the computation to ocean-only points.
+%This choice has two motivations.
+%Firstly, working on ocean only grid points overloads the code and harms the code readability.
+%Secondly, and more importantly, it drastically reduces the vector portion of the computation,
+%leading to a dramatic increase of CPU time requirement on vector computers.
+%The current section describes how the masking affects the computation of the various terms of the equations
+%with respect to the boundary condition at solid walls.
+%The process of defining which areas are to be masked is described in \autoref{subsec:DOM_msk}.
+Options are defined through the \nam{lbc} namelist variables.
 The discrete representation of a domain with complex boundaries (coastlines and bottom topography) leads to
 arrays that include large portions where a computation is not required as the model variables remain at zero.
 …
 Since most of the boundary conditions consist of a zero flux across the solid boundaries,
 they can be simply applied by multiplying variables by the correct mask arrays,
 \ie the mask array of the grid point where the flux is evaluated.
+\ie\ the mask array of the grid point where the flux is evaluated.
 For example, the heat flux in the \textbf{i}-direction is evaluated at $u$-points.
 Evaluating this quantity as,
 …
 (where mask$_{u}$ is the mask array at a $u$-point) ensures that the heat flux is zero inside land and
 at the boundaries, since mask$_{u}$ is zero at solid boundaries which in this case are defined at $u$-points
 (normal velocity $u$ remains zero at the coast) (\autoref{fig:LBC_uv}).
+(normal velocity $u$ remains zero at the coast) (\autoref{fig:LBC_uv}).
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 \item[free-slip boundary condition (\np{rn\_shlat}\forcode{ = 0}):] the tangential velocity at
   the coastline is equal to the offshore velocity,
   \ie the normal derivative of the tangential velocity is zero at the coast,
+  \ie\ the normal derivative of the tangential velocity is zero at the coast,
   so the vorticity: mask$_{f}$ array is set to zero inside the land and just at the coast
   (\autoref{fig:LBC_shlat}-a).
 …
   the closest ocean velocity gridpoint were of the same magnitude but in the opposite direction
   (\autoref{fig:LBC_shlat}-b).
   Therefore, the vorticity along the coastlines is given by:
+  Therefore, the vorticity along the coastlines is given by:
   \[
 …
 \item["partial" free-slip boundary condition (0$<$\np{rn\_shlat}$<$2):] the tangential velocity at
   the coastline is smaller than the offshore velocity, \ie there is a lateral friction but
+  the coastline is smaller than the offshore velocity, \ie\ there is a lateral friction but
   not strong enough to make the tangential velocity at the coast vanish (\autoref{fig:LBC_shlat}-c).
   This can be selected by providing a value of mask$_{f}$ strictly inbetween $0$ and $2$.
 …
 \end{description}
 Note that when the bottom topography is entirely represented by the $s$-coor-dinates (pure $s$-coordinate),
+Note that when the bottom topography is entirely represented by the $s$-coordinates (pure $s$-coordinate),
 the lateral boundary condition on tangential velocity is of much less importance as
 it is only applied next to the coast where the minimum water depth can be quite shallow.
 …
 % ================================================================
 \section[Model domain boundary condition (\texttt{jperio})]
 {Model domain boundary condition (\protect\np{jperio})}
+{Model domain boundary condition (\protect\jp{jperio})}
 \label{sec:LBC_jperio}
 …
 closed, cyclic east-west, cyclic north-south, a north-fold, and combination closed-north fold or
 bi-cyclic east-west and north-fold.
 The north-fold boundary condition is associated with the 3-pole ORCA mesh.
+The north-fold boundary condition is associated with the 3-pole ORCA mesh.
 % -------------------------------------------------------------------------------------------------------------
 %        Closed, cyclic (\np{jperio}\forcode{ = 0..2})
+%        Closed, cyclic (\jp{jperio}\forcode{ = 0..2})
 % -------------------------------------------------------------------------------------------------------------
 \subsection[Closed, cyclic (\forcode{jperio = [0127]})]
 {Closed, cyclic (\protect\np{jperio}\forcode{ = [0127]})}
+{Closed, cyclic (\protect\jp{jperio}\forcode{ = [0127]})}
 \label{subsec:LBC_jperio012}
 The choice of closed or cyclic model domain boundary condition is made by
 setting \np{jperio} to 0, 1, 2 or 7 in namelist \ngn{namcfg}.
+setting \jp{jperio} to 0, 1, 2 or 7 in namelist \nam{cfg}.
 Each time such a boundary condition is needed, it is set by a call to routine \mdl{lbclnk}.
 The computation of momentum and tracer trends proceeds from $i=2$ to $i=jpi-1$ and from $j=2$ to $j=jpj-1$,
 \ie in the model interior.
+\ie\ in the model interior.
 To choose a lateral model boundary condition is to specify the first and last rows and columns of
 the model variables.
+the model variables.
 \begin{description}
 \item[For closed boundary (\np{jperio}\forcode{ = 0})],
+\item[For closed boundary (\jp{jperio}\forcode{ = 0})],
   solid walls are imposed at all model boundaries:
   first and last rows and columns are set to zero.
 \item[For cyclic east-west boundary (\np{jperio}\forcode{ = 1})],
+\item[For cyclic east-west boundary (\jp{jperio}\forcode{ = 1})],
   first and last rows are set to zero (closed) whilst the first column is set to
   the value of the last-but-one column and the last column to the value of the second one
 …
   Whatever flows out of the eastern (western) end of the basin enters the western (eastern) end.
 \item[For cyclic north-south boundary (\np{jperio}\forcode{ = 2})],
+\item[For cyclic north-south boundary (\jp{jperio}\forcode{ = 2})],
   first and last columns are set to zero (closed) whilst the first row is set to
   the value of the last-but-one row and the last row to the value of the second one
 …
   Whatever flows out of the northern (southern) end of the basin enters the southern (northern) end.
 \item[Bi-cyclic east-west and north-south boundary (\np{jperio}\forcode{ = 7})] combines cases 1 and 2.
+\item[Bi-cyclic east-west and north-south boundary (\jp{jperio}\forcode{ = 7})] combines cases 1 and 2.
 \end{description}
 …
 % -------------------------------------------------------------------------------------------------------------
 %        North fold (\textit{jperio = 3 }to $6)$
+%        North fold (\textit{jperio = 3 }to $6)$
 % -------------------------------------------------------------------------------------------------------------
 \subsection[North-fold (\forcode{jperio = [3-6]})]
 {North-fold (\protect\np{jperio}\forcode{ = [3-6]})}
+{North-fold (\protect\jp{jperio}\forcode{ = [3-6]})}
 \label{subsec:LBC_north_fold}
 …
 a three-polar ORCA grid.
 Such a grid has two poles in the northern hemisphere (\autoref{fig:MISC_ORCA_msh},
 and thus requires a specific treatment illustrated in \autoref{fig:North_Fold_T}.
+and thus requires a specific treatment illustrated in \autoref{fig:North_Fold_T}.
 Further information can be found in \mdl{lbcnfd} module which applies the north fold boundary condition.
 …
 % ====================================================================
 % Exchange with neighbouring processors
+% Exchange with neighbouring processors
 % ====================================================================
 \section[Exchange with neighbouring processors (\textit{lbclnk.F90}, \textit{lib\_mpp.F90})]
 …
 After a computation, a communication phase starts:
 each processor sends to its neighbouring processors the update values of the points corresponding to
 the interior overlapping area to its neighbouring sub-domain (\ie the innermost of the two overlapping rows).
+the interior overlapping area to its neighbouring sub-domain (\ie\ the innermost of the two overlapping rows).
 The communication is done through the Message Passing Interface (MPI).
 The data exchanges between processors are required at the very place where
 lateral domain boundary conditions are set in the mono-domain computation:
 the \rou{lbc\_lnk} routine (found in \mdl{lbclnk} module) which manages such conditions is interfaced with
 routines found in \mdl{lib\_mpp} module when running on an MPP computer (\ie when \key{mpp\_mpi} defined).
+routines found in \mdl{lib\_mpp} module when running on an MPP computer (\ie\ when \key{mpp\_mpi} defined).
 It has to be pointed out that when using the MPP version of the model,
 the east-west cyclic boundary condition is done implicitly,
 …
 The i-axis is divided by \jp{jpni} and
 the j-axis by \jp{jpnj} for a number of processors \jp{jpnij} most often equal to $jpni \times jpnj$
 (parameters set in  \ngn{nammpp} namelist).
+(parameters set in  \nam{mpp} namelist).
 Each processor is independent and without message passing or synchronous process,
 programs run alone and access just its own local memory.
 …
 These dimensions include the internal domain and the overlapping rows.
 The number of rows to exchange (known as the halo) is usually set to one (\jp{jpreci}=1, in \mdl{par\_oce}).
 The whole domain dimensions are named \np{jpiglo}, \np{jpjglo} and \jp{jpk}.
+The whole domain dimensions are named \jp{jpiglo}, \jp{jpjglo} and \jp{jpk}.
 The relationship between the whole domain and a sub-domain is:
 \[
 …
 where \jp{jpni}, \jp{jpnj} are the number of processors following the i- and j-axis.
 One also defines variables nldi and nlei which correspond to the internal domain bounds,
 and the variables nimpp and njmpp which are the position of the (1,1) grid-point in the global domain.
+One also defines variables nldi and nlei which correspond to the internal domain bounds,
+and the variables nimpp and njmpp which are the position of the (1,1) grid-point in the global domain.
 An element of $T_{l}$, a local array (subdomain) corresponds to an element of $T_{g}$,
 a global array (whole domain) by the relationship:
+a global array (whole domain) by the relationship:
 \[
   % \label{eq:lbc_nimpp}
 …
 The \NEMO model computes equation terms with the help of mask arrays (0 on land points and 1 on sea points).
+The \NEMO\ model computes equation terms with the help of mask arrays (0 on land points and 1 on sea points).
 It is easily readable and very efficient in the context of a computer with vectorial architecture.
 However, in the case of a scalar processor, computations over the land regions become more expensive in
 terms of CPU time.
+terms of CPU time.
 It is worse when we use a complex configuration with a realistic bathymetry like the global ocean where
 more than 50 \% of points are land points.
 …
 The user then chooses optimal parameters \jp{jpni}, \jp{jpnj} and \jp{jpnij} with $jpnij < jpni \times jpnj$,
 leading to the elimination of $jpni \times jpnj - jpnij$ land processors.
 When those parameters are specified in \ngn{nammpp} namelist,
+When those parameters are specified in \nam{mpp} namelist,
 the algorithm in the \rou{inimpp2} routine sets each processor's parameters (nbound, nono, noea,...) so that
 the land-only processors are not taken into account.
 \gmcomment{Note that the inimpp2 routine is general so that the original inimpp
+\gmcomment{Note that the inimpp2 routine is general so that the original inimpp
 routine should be suppressed from the code.}
 …
 Note that this is a problem for the meshmask file which requires to be defined over the whole domain.
 Therefore, user should not eliminate land processors when creating a meshmask file
 (\ie when setting a non-zero value to \np{nn\_msh}).
+(\ie\ when setting a non-zero value to \np{nn\_msh}).
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 % ====================================================================
 % Unstructured open boundaries BDY
+% Unstructured open boundaries BDY
 % ====================================================================
 \section{Unstructured open boundary conditions (BDY)}
 …
 %-----------------------------------------nambdy--------------------------------------------
 \nlst{nambdy}
+\nlst{nambdy}
 %-----------------------------------------------------------------------------------------------
 %-----------------------------------------nambdy_dta--------------------------------------------
 \nlst{nambdy_dta}
+\nlst{nambdy_dta}
 %-----------------------------------------------------------------------------------------------
 Options are defined through the \ngn{nambdy} \ngn{nambdy\_dta} namelist variables.
 The BDY module is the core implementation of open boundary conditions for regional configurations on
 temperature, salinity, barotropic and baroclinic velocities, as well as ice concentration, ice and snow thicknesses).
 The BDY module was modelled on the OBC module (see NEMO 3.4) and shares many features and
+Options are defined through the \nam{bdy} \nam{bdy\_dta} namelist variables.
+The BDY module is the core implementation of open boundary conditions for regional configurations on
+temperature, salinity, barotropic and baroclinic velocities, as well as ice concentration, ice and snow thicknesses.
+The BDY module was modelled on the OBC module (see \NEMO\ 3.4) and shares many features and
 a similar coding structure \citep{chanut_rpt05}.
 The specification of the location of the open boundary is completely flexible and
 allows for example the open boundary to follow an isobath or other irregular contour.
 Boundary data files used with versions of NEMO prior to Version 3.4 may need to be re-ordered to work with this version.
+allows any type of setup, from regular boundaries to irregular contour (it includes the possibility to set an open boundary able to follow an isobath).
+Boundary data files used with versions of \NEMO\ prior to Version 3.4 may need to be re-ordered to work with this version.
 See the section on the Input Boundary Data Files for details.
 …
 Each boundary set may be defined as a set of straight line segments in a namelist
 (\np{ln\_coords\_file}\forcode{ = .false.}) or read in from a file (\np{ln\_coords\_file}\forcode{ = .true.}).
 If the set is defined in a namelist, then the namelists \ngn{nambdy\_index} must be included separately, one for each set.
+If the set is defined in a namelist, then the namelists \nam{bdy\_index} must be included separately, one for each set.
 If the set is defined by a file, then a ``\ifile{coordinates.bdy}'' file must be provided.
 The coordinates.bdy file is analagous to the usual NEMO ``\ifile{coordinates}'' file.
+The coordinates.bdy file is analagous to the usual \NEMO\ ``\ifile{coordinates}'' 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 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''),
+(``u2d'':sea-surface height and barotropic velocities), for the baroclinic velocities (``u3d''),
 for the active tracers \footnote{The BDY module does not deal with passive tracers at this version} (``tra''), and sea-ice (``ice'').
 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{cn\_tra} and the choice of data is set by \np{nn\_tra\_dta}.\\
+eg. for the active tracers the algorithm is set by \np{cn\_tra} and the choice of data is set by \np{nn\_tra\_dta}.\\
 The choice of algorithm is currently as follows:
 …
 \item[\forcode{'neumann'}:] Value at the boundary are duplicated (No gradient). Only available for baroclinic velocity and tracer variables.
 \item[\forcode{'frs'}:] Flow Relaxation Scheme (FRS) available for all variables.
 \item[\forcode{'Orlanski'}:] Orlanski radiation scheme (fully oblique) for barotropic, baroclinic and tracer variables.
 \item[\forcode{'Orlanski_npo'}:] Orlanski radiation scheme for barotropic, baroclinic and tracer variables.
+\item[\forcode{'Orlanski'}:] Orlanski radiation scheme (fully oblique) for barotropic, baroclinic and tracer variables.
+\item[\forcode{'Orlanski_npo'}:] Orlanski radiation scheme for barotropic, baroclinic and tracer variables.
 \item[\forcode{'flather'}:] Flather radiation scheme for the barotropic variables only.
 \end{description}
 …
 The main choice for the boundary data is to use initial conditions as boundary data
 (\np{nn\_tra\_dta}\forcode{ = 0}) or to use external data from a file (\np{nn\_tra\_dta}\forcode{ = 1}).
 In case the 3d velocity data contain the total velocity (ie, baroclinic and barotropic velocity),
+In case the 3d velocity data contain the total velocity (ie, baroclinic and barotropic velocity),
 the bdy code can derived baroclinic and barotropic velocities by setting \np{ln\_full\_vel}\forcode{ = .true. }
 For the barotropic solution there is also the option to use tidal harmonic forcing either by
 itself (\np{nn\_dyn2d\_dta}\forcode{ = 2}) or in addition to other external data (\np{nn\_dyn2d\_dta}\forcode{ = 3}).\\
+Sea-ice salinity, temperature and age data at the boundary are constant and defined repectively by \np{rn\_ice\_sal}, \np{rn\_ice\_tem} and \np{rn\_ice\_age}.
+If external boundary data is required then the \ngn{nambdy\_dta} namelist must be defined.
+One \ngn{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. The first one is reading data file in the \ngn{nambdy\_dta} namelist shown above
+and the second one is using data from intial condition (no namelist bloc needed).
+Sea-ice salinity, temperature and age data at the boundary are constant and defined repectively by \np{rn\_ice\_sal}, \np{rn\_ice\_tem} and \np{rn\_ice\_age}.
+If external boundary data is required then the \nam{bdy\_dta} namelist must be defined.
+One \nam{bdy\_dta} namelist is required for each boundary set, adopting the same order of indexes in which the boundary sets are defined in nambdy.
+In the example given, two boundary sets have been defined. The first one is reading data file in the \nam{bdy\_dta} namelist shown above
+and the second one is using data from intial condition (no namelist block needed).
 The boundary data is read in using the fldread module,
 so the \ngn{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.
+so the \nam{bdy\_dta} namelist is in the format required for fldread.
+For each required variable, the filename, the frequency of the files and
+the frequency of the data in the files are given.
 Also whether or not time-interpolation is required and whether the data is climatological (time-cyclic) data.\\
 There is currently an option to vertically interpolate the open boundary data onto the native grid at run-time.
 If \np{nn\_bdy\_jpk} $< -1$, it is assumed that the lateral boundary data are already on the native grid.
 However, if \np{nn\_bdy\_jpk} is set to the number of vertical levels present in the boundary data,
 a bilinear interpolation onto the native grid will be triggered at runtime.
 For this to be successful the additional variables: $gdept$, $gdepu$, $gdepv$, $e3t$, $e3u$ and $e3v$, are required to be present in the lateral boundary files.
 These correspond to the depths and scale factors of the input data,
+If \np{nn\_bdy\_jpk} $< -1$, it is assumed that the lateral boundary data are already on the native grid.
+However, if \np{nn\_bdy\_jpk} is set to the number of vertical levels present in the boundary data,
+a bilinear interpolation onto the native grid will be triggered at runtime.
+For this to be successful the additional variables: $gdept$, $gdepu$, $gdepv$, $e3t$, $e3u$ and $e3v$, are required to be present in the lateral boundary files.
+These correspond to the depths and scale factors of the input data,
 the latter used to make any adjustment to the velocity fields due to differences in the total water depths between the two vertical grids.\\
 In the example namelists given, two boundary sets are defined.
+In the example of given namelists, 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. No condition specified for the baroclinic velocity and sea-ice.
 …
 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 initial condition files.
+FRS conditions are applied on temperature and salinity and climatological data is read from initial condition files.
 %----------------------------------------------
 …
 is relaxed towards the external conditions over the rest of the FRS zone.
 The application of a relaxation zone helps to prevent spurious reflection of
 outgoing signals from the model boundary.
+outgoing signals from the model boundary.
 The function $\alpha$ is specified as a $tanh$ function:
 …
 Note that the sea-surface height gradient in \autoref{eq:bdy_fla1} is a spatial gradient across the model boundary,
 so that $\eta_{e}$ is 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$, \ie between the two $T$ grid points.
+$U$ and $U_{e}$ are defined on the $U$ or $V$ points with $nbr=1$, \ie\ between the two $T$ grid points.
 %----------------------------------------------
 …
 \end{equation}
 Generally the relaxation time scale at inward propagation points \np{(rn\_time\_dmp}) is set much shorter than the time scale at outward propagation
+Generally the relaxation time scale at inward propagation points (\np{rn\_time\_dmp}) is set much shorter than the time scale at outward propagation
 points (\np{rn\_time\_dmp\_out}) so that the solution is constrained more strongly by the external data at inward propagation points.
 See \autoref{subsec:BDY_relaxation} for detailed on the spatial shape of the scaling.\\
 The ``normal propagation of oblique radiation'' or NPO approximation (called \forcode{'orlanski_npo'}) involves assuming
+See \autoref{subsec:BDY_relaxation} for detailed on the spatial shape of the scaling.\\
+The ``normal propagation of oblique radiation'' or NPO approximation (called \forcode{'orlanski_npo'}) involves assuming
 that $c_y$ is zero in equation (\autoref{eq:wave_continuous}), but including
 this term in the denominator of equation (\autoref{eq:cx}). Both versions of the scheme are options in BDY. Equations
 …
 \label{subsec:BDY_relaxation}
 In addition to a specific boundary condition specified as \np{cn\_tra} and \np{cn\_dyn3d}, relaxation on baroclinic velocities and tracers variables are available.
+In addition to a specific boundary condition specified as \np{cn\_tra} and \np{cn\_dyn3d}, relaxation on baroclinic velocities and tracers variables are available.
 It is control by the namelist parameter \np{ln\_tra\_dmp} and \np{ln\_dyn3d\_dmp} for each boundary set.
 The relaxation time scale value (\np{rn\_time\_dmp} and \np{rn\_time\_dmp\_out}, $\tau$) are defined at the boundaries itself.
+The relaxation time scale value (\np{rn\_time\_dmp} and \np{rn\_time\_dmp\_out}, $\tau$) are defined at the boundaries itself.
 This time scale ($\alpha$) is weighted by the distance ($d$) from the boundary over \np{nn\_rimwidth} cells ($N$):
 …
 \]
 The same scaling is applied in the Orlanski damping.
+The same scaling is applied in the Orlanski damping.
 %----------------------------------------------
 …
 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.
+The $nbi$ and $nbj$ arrays define the local $(i,j)$ indexes of each point in the boundary zone and
+the $nbr$ array defines the discrete distance from the boundary: $nbr=1$ means that
+the boundary point is next to the edge of the model domain, while $nbr>1$ means that
+the boundary 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 \autoref{fig:LBC_bdy_geom} shows an example of an irregular boundary.
+Figure \autoref{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 ``\ifile{coordinates.bdy}'' file.
 The nambdy\_index namelist defines a series of straight-line segments for north, east, south and west boundaries.
 One nambdy\_index namelist bloc is needed for each boundary condition defined by indexes.
 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.
+One nambdy\_index namelist block is needed for each boundary condition defined by indexes.
+For the northern boundary, \texttt{nbdysegn} gives the number of segments,
+\jp{jpjnob} gives the $j$ index for each segment and \jp{jpindt} and
+\jp{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 \np{nn\_rimwidth}\forcode{ > 1}.
 The boundary geometry may also be defined from a ``\ifile{coordinates.bdy}'' file.
 Figure \autoref{fig:LBC_nc_header} gives an example of the header information from such a file.
+Figure \autoref{fig:LBC_nc_header} gives an example of the header information from such a file, based on the description of geometrical setup given above.
 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$.
 …
 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.
+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,
+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.
 …
 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.
+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.
 From Version 3.4 there are new restrictions on the order in which the boundary points are defined
 …
 \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).
+  the data for tracers and baroclinic velocities).
 \end{enumerate}
 …
 This is controlled  by the \np{ln\_vol} parameter in the namelist.
 A value of \np{ln\_vol}\forcode{ = .false.} indicates that this option is not used.
 Two options to control the volume are available (\np{nn\_volctl}).
+Two options to control the volume are available (\np{nn\_volctl}).
 If \np{nn\_volctl}\forcode{ = 0} then a correction is applied to the normal barotropic velocities around the boundary at
 each timestep to ensure that the integrated volume flow through the boundary is zero.
 …
 %-----------------------------------------nambdy_tide--------------------------------------------
 \nlst{nambdy_tide}
+\nlst{nambdy_tide}
 %-----------------------------------------------------------------------------------------------
 Tidal forcing at open boundaries requires the activation of surface
 tides (i.e., in \ngn{nam\_tide}, \np{ln\_tide} needs to be set to
+tides (i.e., in \nam{\_tide}, \np{ln\_tide} needs to be set to
 \forcode{.true.} and the required constituents need to be activated by
 including their names in the \np{cname} array; see
+including their names in the \np{clname} array; see
 \autoref{sec:SBC_tide}). Specific options related to the reading in of
 the complex harmonic amplitudes of elevation (SSH) and barotropic
 velocity (u,v) at open boundaries are defined through the
 \ngn{nambdy\_tide} namelist parameters.\\
+\nam{bdy\_tide} namelist parameters.\\
 The tidal harmonic data at open boundaries can be specified in two

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_LDF.tex

-                      r11353
+                      r11512
 \label{chap:LDF}
 \minitoc
+\chaptertoc
 \newpage
 …
 (3) the space and time variations of the eddy coefficients.
 These three aspects of the lateral diffusion are set through namelist parameters
 (see the \ngn{nam\_traldf} and \ngn{nam\_dynldf} below).
+(see the \nam{tra\_ldf} and \nam{dyn\_ldf} below).
 Note that this chapter describes the standard implementation of iso-neutral tracer mixing.
 Griffies's implementation, which is used if \np{ln\_traldf\_triad}\forcode{ = .true.},
 …
 {Laplacian mixing (\protect\np{ln\_traldf\_lap}, \protect\np{ln\_dynldf\_lap})}
 Setting \protect\np{ln\_traldf\_lap}\forcode{ = .true.} and/or \protect\np{ln\_dynldf\_lap}\forcode{ = .true.} enables
 a second order diffusion on tracers and momentum respectively. Note that in \NEMO 4, one can not combine
+a second order diffusion on tracers and momentum respectively. Note that in \NEMO\ 4, one can not combine
 Laplacian and Bilaplacian operators for the same variable.
 …
 Setting \protect\np{ln\_traldf\_blp}\forcode{ = .true.} and/or \protect\np{ln\_dynldf\_blp}\forcode{ = .true.} enables
 a fourth order diffusion on tracers and momentum respectively. It is implemented by calling the above Laplacian operator twice.
 We stress again that from \NEMO 4, the simultaneous use Laplacian and Bilaplacian operators is not allowed.
+We stress again that from \NEMO\ 4, the simultaneous use Laplacian and Bilaplacian operators is not allowed.
 % ================================================================
 …
 \subsection{Slopes for tracer geopotential mixing in the $s$-coordinate}
 In $s$-coordinates, geopotential mixing (\ie horizontal mixing) $r_1$ and $r_2$ are the slopes between
+In $s$-coordinates, geopotential mixing (\ie\ horizontal mixing) $r_1$ and $r_2$ are the slopes between
 the geopotential and computational surfaces.
 Their discrete formulation is found by locally solving \autoref{eq:tra_ldf_iso} when
 the diffusive fluxes in the three directions are set to zero and $T$ is assumed to be horizontally uniform,
 \ie a linear function of $z_T$, the depth of a $T$-point.
+\ie\ a linear function of $z_T$, the depth of a $T$-point.
 %gm { Steven : My version is obviously wrong since I'm left with an arbitrary constant which is the local vertical temperature gradient}
 …
 Their formulation does not depend on the vertical coordinate used.
 Their discrete formulation is found using the fact that the diffusive fluxes of
 locally referenced potential density (\ie $in situ$ density) vanish.
+locally referenced potential density (\ie\ $in situ$ density) vanish.
 So, substituting $T$ by $\rho$ in \autoref{eq:tra_ldf_iso} and setting the diffusive fluxes in
 the three directions to zero leads to the following definition for the neutral slopes:
 …
 To overcome this problem, several techniques have been proposed in which the numerical schemes of
 the ocean model are modified \citep{weaver.eby_JPO97, griffies.gnanadesikan.ea_JPO98}.
 Griffies's scheme is now available in \NEMO if \np{ln\_traldf\_triad}=\forcode{= .true.}; see \autoref{apdx:triad}.
+Griffies's scheme is now available in \NEMO\ if \np{ln\_traldf\_triad}\forcode{ = .true.}; see \autoref{apdx:triad}.
 Here, another strategy is presented \citep{lazar_phd97}:
 a local filtering of the iso-neutral slopes (made on 9 grid-points) prevents the development of
 …
       \textit{(a)} in the real ocean the slope is the iso-neutral slope in the ocean interior,
       which has to be adjusted at the surface boundary
       \ie it must tend to zero at the surface since there is no mixing across the air-sea interface:
+      \ie\ it must tend to zero at the surface since there is no mixing across the air-sea interface:
       wall boundary condition).
       Nevertheless, the profile between the surface zero value and the interior iso-neutral one is unknown,
 …
 \textit{vw}- points for the $v$-component.
 They are computed from the slopes used for tracer diffusion,
 \ie \autoref{eq:ldfslp_geo} and \autoref{eq:ldfslp_iso}:
+\ie\ \autoref{eq:ldfslp_geo} and \autoref{eq:ldfslp_iso}:
 \[
 …
 The major issue remaining is in the specification of the boundary conditions.
 The same boundary conditions are chosen as those used for lateral diffusion along model level surfaces,
 \ie using the shear computed along the model levels and with no additional friction at the ocean bottom
+\ie\ using the shear computed along the model levels and with no additional friction at the ocean bottom
 (see \autoref{sec:LBC_coast}).
 …
   A_l = \left\{
     \begin{aligned}
       & \frac{\max(e_1,e_2)}{e_{ref}} A_o^l           & \text{for laplacian operator } \\
       & \frac{\max(e_1,e_2)^{3}}{e_{ref}^{3}} A_o^l          & \text{for bilaplacian operator }
+      & \frac{1}{2} U_{scl}  \max(e_1,e_2)         & \text{for laplacian operator } \\
+      & \frac{1}{12} U_{scl}  \max(e_1,e_2)^{3}             & \text{for bilaplacian operator }
     \end{aligned}
   \right.
 \end{equation}
+where $e_{ref}$ is a reference grid size harcoded to a $1^{\circ}$ grid size (\ie $e_{ref}\approx 111 km$),
+and $A_o^l$ is the user defined mixing coefficient defined according to  \autoref{eq:constantah}.
+where $U_{scl}$ is a user defined velocity scale (\np{rn\_Ud}, \np{rn\_Uv}).
 This variation is intended to reflect the lesser need for subgrid scale eddy mixing where
 the grid size is smaller in the domain.
 …
 The 3D space variation of the mixing coefficient is simply the combination of the 1D and 2D cases above,
 \ie a hyperbolic tangent variation with depth associated with a grid size dependence of
+\ie\ a hyperbolic tangent variation with depth associated with a grid size dependence of
 the magnitude of the coefficient.
 …
 the formulation of which depends on the slopes of iso-neutral surfaces.
 Contrary to the case of iso-neutral mixing, the slopes used here are referenced to the geopotential surfaces,
 \ie \autoref{eq:ldfslp_geo} is used in $z$-coordinates,
+\ie\ \autoref{eq:ldfslp_geo} is used in $z$-coordinates,
 and the sum \autoref{eq:ldfslp_geo} + \autoref{eq:ldfslp_iso} in $s$-coordinates.
 If isopycnal mixing is used in the standard way, \ie \np{ln\_traldf\_triad}\forcode{ = .false.}, the eddy induced velocity is given by:
+If isopycnal mixing is used in the standard way, \ie\ \np{ln\_traldf\_triad}\forcode{ = .false.}, the eddy induced velocity is given by:
 \begin{equation}
   \label{eq:ldfeiv}
 …
   \end{split}
 \end{equation}
 where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{nn\_aei\_ijk\_t} \ngn{namtra\_eiv} namelist parameter.
+where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{nn\_aei\_ijk\_t} \nam{tra\_eiv} namelist parameter.
 The three components of the eddy induced velocity are computed in \rou{ldf\_eiv\_trp} and
 added to the eulerian velocity in \rou{tra\_adv} where tracer advection is performed.
 …
 %--------------------------------------------------------------------------------------------------------------
 If  \np{ln\_mle}\forcode{ = .true.} in \ngn{namtra\_mle} namelist, a parameterization of the mixing due to unresolved mixed layer instabilities is activated (\citet{foxkemper.ferrari_JPO08}). Additional transport is computed in \rou{ldf\_mle\_trp} and added to the eulerian transport in \rou{tra\_adv} as done for eddy induced advection.
+If  \np{ln\_mle}\forcode{ = .true.} in \nam{tra\_mle} namelist, a parameterization of the mixing due to unresolved mixed layer instabilities is activated (\citet{foxkemper.ferrari_JPO08}). Additional transport is computed in \rou{ldf\_mle\_trp} and added to the eulerian transport in \rou{tra\_adv} as done for eddy induced advection.
 \colorbox{yellow}{TBC}

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_OBS.tex

-                      r11353
+                      r11512
 \label{chap:OBS}
 \minitoc
+\chaptertoc
 \vfill
 …
 \begin{tabular}{l||l|m{0.65\linewidth}}
     Release   & Author        & Modifications \\
     {\em 4.0} & {\em D. J. Lea} & {\em \NEMO 4.0 updates}  \\
+    {\em 4.0} & {\em D. J. Lea} & {\em \NEMO\ 4.0 updates}  \\
     {\em 3.6} & {\em M. Martin, A. Ryan} & {\em Add averaging operator, standalone obs oper} \\
     {\em 3.4} & {\em D. J. Lea, M. Martin, ...} & {\em Initial version}  \\
 …
 The OBS code is called from \mdl{nemogcm} for model initialisation and to calculate the model equivalent values for observations on the 0th time step.
 The code is then called again after each time step from \mdl{step}.
 The code is only activated if the \ngn{namobs} namelist logical \np{ln\_diaobs} is set to true.
+The code is only activated if the \nam{obs} namelist logical \np{ln\_diaobs} is set to true.
 For all data types a 2D horizontal interpolator or averager is needed to
 …
 This now works in a generalised vertical coordinate system.
 Some profile observation types (\eg tropical moored buoys) are made available as daily averaged quantities.
+Some profile observation types (\eg\ tropical moored buoys) are made available as daily averaged quantities.
 The observation operator code can be set-up to calculate the equivalent daily average model temperature fields using
 the \np{nn\_profdavtypes} namelist array.
 …
 Otherwise (by default) the model value from the nearest time step to the observation time is used.
 The code is controlled by the namelist \ngn{namobs}.
+The code is controlled by the namelist \nam{obs}.
 See the following sections for more details on setting up the namelist.
 …
 In this section an example of running the observation operator code is described using
 profile observation data which can be freely downloaded.
 It shows how to adapt an existing run and build of \NEMO to run the observation operator. Note also the observation operator and the assimilation increments code are run in the \np{ORCA2\_ICE\_OBS} SETTE test.
+It shows how to adapt an existing run and build of \NEMO\ to run the observation operator. Note also the observation operator and the assimilation increments code are run in the ORCA2\_ICE\_OBS SETTE test.
 \begin{enumerate}
 \item Compile NEMO.
+\item Compile \NEMO.
 \item Download some EN4 data from \href{http://www.metoffice.gov.uk/hadobs}{www.metoffice.gov.uk/hadobs}.
 …
   the observation operator compares the model and observations for a matching date and time.
 \item Compile the OBSTOOLS code in the \np{tools} directory using:
+\item Compile the OBSTOOLS code in the \path{tools} directory using:
 \begin{cmds}
 ./maketools -n OBSTOOLS -m [ARCH]
 \end{cmds}
 replacing \np{[ARCH]} with the build architecture file for your machine. Note the tools are checked out from a separate repository under \np{utils/tools}.
+replacing \texttt{[ARCH]} with the build architecture file for your machine. Note the tools are checked out from a separate location of the repository (under \path{/utils/tools}).
 \item Convert the EN4 data into feedback format:
 …
 \end{cmds}
 \item Include the following in the \NEMO namelist to run the observation operator on this data:
+\item Include the following in the \NEMO\ namelist to run the observation operator on this data:
 \end{enumerate}
 Options are defined through the \ngn{namobs} namelist variables.
+Options are defined through the \nam{obs} namelist variables.
 The options \np{ln\_t3d} and \np{ln\_s3d} switch on the temperature and salinity profile observation operator code.
 The filename or array of filenames are specified using the \np{cn\_profbfiles} variable.
 …

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

Context Navigation

Legend:

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/main/definitions.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/main/foreword.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/main/thanks.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/annex_A.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/annex_B.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/annex_C.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/annex_DOMAINcfg.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/annex_E.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/annex_iso.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_ASM.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_CONFIG.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_DIA.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_DIU.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_DOM.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_DYN.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_LBC.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_LDF.tex

NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_OBS.tex