Changeset 11564 for NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc

Property svn:ignore deleted

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex

Property svn:ignore

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

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/HTML_latex2html.sh

-                      r10146
+                      r11564
 #!/bin/bash
 ./inc/clean.sh
 ./inc/build.sh
+#./inc/clean.sh
+#./inc/build.sh
+cd tex_main
+sed -i -e 's#\\documentclass#%\\documentclass#' -e '/{document}/ s/^/%/' \
+   ../tex_sub/*.tex
+sed -i    's#\\subfile{#\\include{#g' \
+   NEMO_manual.tex
+latex2html -local_icons -no_footnode -split 4 -link 2 -mkdir -dir ../html_LaTeX2HTML   \
+            $*                                                                         \
+   NEMO_manual
+sed -i -e 's#%\\documentclass#\\documentclass#' -e '/{document}/ s/^%//' \
+   ../tex_sub/*.tex
+sed -i    's#\\include{#\\subfile{#g' \
+   NEMO_manual.tex
+sed -i -e 's#utf8#latin1#'                                 \
+       -e 's#\[outputdir=../build\]{minted}#\[\]{minted}#' \
+       -e '/graphicspath/ s#{../#{../../#g'                \
+          global/packages.tex
+cd ./NEMO/main
+sed -i -e 's#\\documentclass#%\\documentclass#' -e '/{document}/ s#^#%#'   ../subfiles/*.tex
+sed -i    's#\\subfile{#\\input{#'                                         chapters.tex appendices.tex
+#latex2html                                   -noimages -local_icons -no_footnode -split 4 -link 2 -dir ../html_LaTeX2HTML $* NEMO_manual
+latex2html -debug -noreuse -init_file ../../l2hconf.pm -local_icons                               -dir ../build/html               NEMO_manual
+sed -i -e 's#%\\documentclass#\\documentclass#' -e '/{document}/ s#^%##'   ../subfiles/*.tex
+sed -i    's#\\input{#\\subfile{#'                                         chapters.tex appendices.tex
 cd -
+sed -i -e 's#latin1#utf8#'                                 \
+       -e 's#\[\]{minted}#\[outputdir=../build\]{minted}#' \
+       -e '/graphicspath/ s#{../../#{../#g'                \
+     global/packages.tex
 exit 0

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO

Property svn:ignore deleted

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/main

Property svn:ignore

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

Property svn:externals set to
^/utils/dev/bibtool.rsc bibtool.rsc

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_ASM.tex

-                      r10442
+                      r11564
 \label{chap:ASM}
+Authors: D. Lea,  M. Martin, K. Mogensen, A. Weaver, ...   % do we keep
+\minitoc
+\chaptertoc
+\vfill
+\begin{figure}[b]
+\subsubsection*{Changes record}
+\begin{tabular}{l||l|m{0.65\linewidth}}
+    Release   & Author        & Modifications \\
+    {\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}
+\end{figure}
 \newpage
 The ASM code adds the functionality to apply increments to the model variables: temperature, salinity,
 sea surface height, velocity and sea ice concentration.
+sea surface height, velocity and sea ice concentration.
 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 may be preferable to introduce the increment gradually into the ocean model in order to
 minimize spurious adjustment processes.
 This technique is referred to as Incremental Analysis Updates (IAU) \citep{Bloom_al_MWR96}.
+This technique is referred to as Incremental Analysis Updates (IAU) \citep{bloom.takacs.ea_MWR96}.
 IAU is a common technique used with 3D assimilation methods such as 3D-Var or OI.
 IAU is used when \np{ln\_asmiau} is set to true.
 With IAU, the model state trajectory ${\bf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$)
+With IAU, the model state trajectory ${\mathbf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$)
 is corrected by adding the analysis increments for temperature, salinity, horizontal velocity and SSH as
 additional tendency terms to the prognostic equations:
 \begin{align*}
   % \label{eq:wa_traj_iau}
   {\bf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\bf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\bf x}^{a}
+  % \label{eq:ASM_wa_traj_iau}
+  {\mathbf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\mathbf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\mathbf x}^{a}
 \end{align*}
 where $F_{i}$ is a weighting function for applying the increments $\delta\tilde{\bf x}^{a}$ defined such that
+where $F_{i}$ is a weighting function for applying the increments $\delta\tilde{\mathbf x}^{a}$ defined such that
 $\sum_{i=1}^{N} F_{i}=1$.
 ${\bf x}^b$ denotes the model initial state and ${\bf x}^a$ is the model state after the increments are applied.
+${\mathbf x}^b$ denotes the model initial state and ${\mathbf x}^a$ is the model state after the increments are applied.
 To control the adjustment time of the model to the increment,
 the increment can be applied over an arbitrary sub-window, $t_{m} \leq t_{i} \leq t_{n}$,
 …
 Typically the increments are spread evenly over the full window.
 In addition, two different weighting functions have been implemented.
 The first function employs constant weights,
+The first function (namelist option \np{niaufn}=0) employs constant weights,
 \begin{align}
   \label{eq:F1_i}
+  \label{eq:ASM_F1_i}
   F^{(1)}_{i}
   =\left\{
   \begin{array}{ll}
      &    {\rm if} \; \; \; t_{i} < t_{m}                \\
 /M &    {\rm if} \; \; \; t_{m} < t_{i} \leq t_{n} \\
      &    {\rm if} \; \; \; t_{i} > t_{n}
+     &    {\mathrm if} \; \; \; t_{i} < t_{m}                \\
+/M &    {\mathrm if} \; \; \; t_{m} < t_{i} \leq t_{n} \\
+     &    {\mathrm if} \; \; \; t_{i} > t_{n}
   \end{array}
             \right.
+            \right.
 \end{align}
 where $M = m-n$.
 The second function employs peaked hat-like weights in order to give maximum weight in the centre of the sub-window,
+The second function (namelist option \np{niaufn}=1) employs peaked hat-like weights in order to give maximum weight in the centre of the sub-window,
 with the weighting reduced linearly to a small value at the window end-points:
 \begin{align}
   \label{eq:F2_i}
+  \label{eq:ASM_F2_i}
   F^{(2)}_{i}
   =\left\{
   \begin{array}{ll}
                            &    {\rm if} \; \; \; t_{i}       <     t_{m}                        \\
     \alpha \, i               &    {\rm if} \; \; \; t_{m}    \leq t_{i}    \leq   t_{M/2}   \\
     \alpha \, (M - i +1) &    {\rm if} \; \; \; t_{M/2}  <    t_{i}    \leq   t_{n}       \\
                             &   {\rm if} \; \; \; t_{i}        >    t_{n}
+                           &    {\mathrm if} \; \; \; t_{i}       <     t_{m}                        \\
+    \alpha \, i               &    {\mathrm if} \; \; \; t_{m}    \leq t_{i}    \leq   t_{M/2}   \\
+    \alpha \, (M - i +1) &    {\mathrm if} \; \; \; t_{M/2}  <    t_{i}    \leq   t_{n}       \\
+                            &   {\mathrm if} \; \; \; t_{i}        >    t_{n}
   \end{array}
                                    \right.
 \end{align}
 where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even.
 The weights described by \autoref{eq:F2_i} provide a smoother transition of the analysis trajectory from
 one assimilation cycle to the next than that described by \autoref{eq:F1_i}.
+where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even.
+The weights described by \autoref{eq:ASM_F2_i} provide a smoother transition of the analysis trajectory from
+one assimilation cycle to the next than that described by \autoref{eq:ASM_F1_i}.
 %==========================================================================
 …
 \label{sec:ASM_div_dmp}
+The velocity increments may be initialized by the iterative application of a divergence damping operator.
+In iteration step $n$ new estimates of velocity increments $u^{n}_I$ and $v^{n}_I$ are updated by:
+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}.
+In iteration step $n$ (starting at $n=1$) new estimates of velocity increments $u^{n}_I$ and $v^{n}_I$ are updated by:
 \begin{equation}
   \label{eq:asm_dmp}
+  \label{eq:ASM_dmp}
   \left\{
     \begin{aligned}
 …
   \right.,
 \end{equation}
+where
+where the divergence is defined as
 \[
   % \label{eq:asm_div}
+  % \label{eq:ASM_div}
   \chi^{n-1}_I = \frac{1}{e_{1t}\,e_{2t}\,e_{3t} }
   \left( {\delta_i \left[ {e_{2u}\,e_{3u}\,u^{n-1}_I} \right]
       +\delta_j \left[ {e_{1v}\,e_{3v}\,v^{n-1}_I} \right]} \right).
 \]
+By the application of \autoref{eq:asm_dmp} and \autoref{eq:asm_dmp} the divergence is filtered in each iteration,
+By the application of \autoref{eq:ASM_dmp} the divergence is filtered in each iteration,
 and the vorticity is left unchanged.
 In the presence of coastal boundaries with zero velocity increments perpendicular to the coast
 …
 This type of the initialisation reduces the vertical velocity magnitude and
 alleviates the problem of the excessive unphysical vertical mixing in the first steps of the model integration
 \citep{Talagrand_JAS72, Dobricic_al_OS07}.
+\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.
+By choosing this value to be of the order of 100 the increments in
+the vertical velocity will be significantly reduced.
+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{namasm} 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.
 %------------------------------------------namasm-----------------------------------------------------
+%------------------------------------------nam_asminc-----------------------------------------------------
+%
+\nlst{nam_asminc}
+\begin{listing}
+  \nlst{nam_asminc}
+  \caption{\texttt{nam\_asminc}}
+  \label{lst:nam_asminc}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_DIA.tex

-                      r10509
+                      r11564
 \label{chap:DIA}
+\minitoc
+\chaptertoc
+\vfill
+\begin{figure}[b]
+\subsubsection*{Changes record}
+\begin{tabular}{l||l|m{0.65\linewidth}}
+    Release   & Author        & Modifications \\
+    {\em 4.0} & {\em Mirek Andrejczuk, Massimiliano Drudi} & {\em }  \\
+    {\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 }  \\
+\end{tabular}
+\end{figure}
 \newpage
 % ================================================================
 %       Old Model Output
+%       Old Model Output
 % ================================================================
 \section{Old model output (default)}
+\section{Model output}
 \label{sec:DIA_io_old}
 …
 the same run performed in one step.
 It should be noted that this requires that the restart file contains two consecutive time steps for
+all the prognostic variables, and that it is saved in the same binary format as the one used by the computer that
+is to read it (in particular, 32 bits binary IEEE format must not be used for this file).
+all the prognostic variables.
 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.
 …
 A complete description of the use of this I/O server is presented in the next section.
-By default, \key{iomput} is not defined,
-NEMO produces NetCDF with the old IOIPSL library which has been kept for compatibility and its easy installation.
-However, the IOIPSL library is quite inefficient on parallel machines and, since version 3.2,
-many diagnostic options have been added presuming the use of \key{iomput}.
-The usefulness of the default IOIPSL-based option is expected to reduce with each new release.
-If \key{iomput} is not defined, output files and content are defined in the \mdl{diawri} module and
-contain mean (or instantaneous if \key{diainstant} is defined) values over a regular period of
-nn\_write time-steps (namelist parameter).
 %\gmcomment{                    % start of gmcomment
 …
 \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: \path{NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef.xml},
+\path{NEMOGCM/CONFIG/SHARED/field_def.xml} and \path{NEMOGCM/CONFIG/SHARED/domain_def.xml}. \\
+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},
+\path{cfgs/SHARED/field_def_nemo-pisces.xml},
+\path{cfgs/SHARED/field_def_nemo-ice.xml} and \path{cfgs/SHARED/domain_def_nemo.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-1.0}{XIOS-1.0}
 (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
 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,
+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,
 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}
 …
 \xmlline|<variable id="using_server" type="bool"></variable>|
+The {\tt using\_server} setting determines whether or not the server will be used in \textit{attached mode}
+(as a library) [{\tt> false <}] or in \textit{detached mode}
+(as an external executable on N additional, dedicated cpus) [{\tt > true <}].
+The \textit{attached mode} is simpler to use but much less efficient for massively parallel applications.
+The \texttt{using\_server} setting determines whether or not the server will be used in
+\textit{attached mode}
+(as a library) [\texttt{> false <}] or in \textit{detached mode}
+(as an external executable on N additional, dedicated cpus) [\texttt{ > true <}].
+The \textit{attached mode} is simpler to use but much less efficient for
+massively parallel applications.
 The type of each file can be either ''multiple\_file'' or ''one\_file''.
 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 {\tt 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.
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|lXl|}
     \hline
 …
     \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.
 The \href{https://forge.ipsl.jussieu.fr/nemo/wiki/Users/ModelInterfacing/InputsOutputs#Inputs-OutputsusingXIOS}
 {XIOS with NEMO} guide provides an example illustration of how this can be achieved.
+\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.
 \subsubsection{Add your own outputs}
 …
 \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:
 …
 \begin{table}
-  \scriptsize
   \begin{tabular*}{\textwidth}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|}
     \hline
 …
 \begin{table}
-  \scriptsize
   \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|}
     \hline
 …
                                                                                                      \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
 …
 \begin{table}
-  \scriptsize
   \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|}
     \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):
 \begin{table}
-  \scriptsize
   \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|}
     \hline
 …
 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 and domain definition is done in 2 separate files:
+\path{NEMOGCM/CONFIG/SHARED/field_def.xml} and \path{NEMOGCM/CONFIG/SHARED/domain_def.xml} that
+\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
+\path{cfgs/SHARED/field_def_nemo-ice.xml} ) and the  domain definition is done in another file ( \path{cfgs/SHARED/domain_def_nemo.xml} )
+that
 are included in the main iodef.xml file through the following commands:
 \begin{xmllines}
+<field_definition src="./field_def.xml" />
+<domain_definition src="./domain_def.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}
 …
 Secondly, the group can be used to replace a list of elements.
+Several examples of groups of fields are proposed at the end of the file \path{CONFIG/SHARED/field_def.xml}.
+Several examples of groups of fields are proposed at the end of the XML field files (
+\path{cfgs/SHARED/field_def_nemo-oce.xml},
+\path{cfgs/SHARED/field_def_nemo-pisces.xml} and
+\path{cfgs/SHARED/field_def_nemo-ice.xml} ) .
 For example, a short list of the usual variables related to the U grid:
 …
 <field_group id="groupU" >
    <field field_ref="uoce"  />
    <field field_ref="suoce" />
+   <field field_ref="ssu" />
    <field field_ref="utau"  />
 </field_group>
 …
    <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{CONFIG/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).
 \begin{xmllines}
 <domain_group id="grid_T">
    <domain id="myzoom" zoom_ibegin="10" zoom_jbegin="10" zoom_ni="5" zoom_nj="5" />
+<domain id="myzoomT" domain_ref="grid_T">
+   <zoom_domain ibegin="10" jbegin="10" ni="5" nj="5" />
 \end{xmllines}
 …
 \begin{xmllines}
 <file id="myfile_vzoom" output_freq="1d" >
    <field field_ref="toce" domain_ref="myzoom"/>
+   <field field_ref="toce" domain_ref="myzoomT"/>
 </file>
 \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.
 …
 \subsubsection{Define vertical zooms}
 Vertical zooms are defined through the attributs zoom\_begin and zoom\_end of the tag family axis.
+Vertical zooms are defined through the attributs zoom\_begin and zoom\_n of the tag family axis.
 It must therefore be done in the axis part of the XML file.
+For example, in \path{NEMOGCM/CONFIG/ORCA2_LIM/iodef_demo.xml}, we provide the following example:
+\begin{xmllines}
+<axis_group id="deptht" long_name="Vertical T levels" unit="m" positive="down" >
+   <axis id="deptht" />
+   <axis id="deptht_myzoom" zoom_begin="1" zoom_end="10" />
+For example, in \path{cfgs/ORCA2_ICE_PISCES/EXPREF/iodef_demo.xml}, we provide the following example:
+\begin{xmllines}
+<axis_definition>
+   <axis id="deptht" long_name="Vertical T levels" unit="m" positive="down" />
+   <axis id="deptht_zoom" azix_ref="deptht" >
+      <zoom_axis zoom_begin="1" zoom_n="10" />
+   </axis>
 \end{xmllines}
 …
 \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"  -->
       ...
 …
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|lX|}
     \hline
 …
 \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.
 …
 \begin{table}
+  \scriptsize
+  \begin{tabularx}{\textwidth}{|X|c|c|c|}
+  \begin{tabular}{|l|c|c|}
     \hline
     tag ids affected by automatic definition of some of their attributes &
     name attribute                                                       &
     attribute value                      \\
+    attribute value                                                      \\
     \hline
     \hline
     field\_definition                                                    &
     freq\_op                                                             &
     \np{rn\_rdt}                         \\
+    \np{rn\_rdt}                                                         \\
     \hline
     SBC                                                                  &
     freq\_op                                                             &
     \np{rn\_rdt} $\times$ \np{nn\_fsbc}  \\
+    \np{rn\_rdt} $\times$ \np{nn\_fsbc}                                  \\
     \hline
     ptrc\_T                                                              &
     freq\_op                                                             &
     \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\
+    \np{rn\_rdt} $\times$ \np{nn\_dttrc}                                 \\
     \hline
     diad\_T                                                              &
     freq\_op                                                             &
     \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\
+    \np{rn\_rdt} $\times$ \np{nn\_dttrc}                                 \\
     \hline
     EqT, EqU, EqW                                                        &
     jbegin, ni,                                                          &
     according to the grid                \\
+    &
+    according to the grid                                                \\
+                                                                         &
     name\_suffix                                                         &
     \\
+                                                                         \\
     \hline
     TAO, RAMA and PIRATA moorings                                        &
     zoom\_ibegin, zoom\_jbegin,                                          &
     according to the grid                \\
+    &
+    according to the grid                                                \\
+                                                                         &
     name\_suffix                                                         &
     \\
     \hline
   \end{tabularx}
+                                                                         \\
+    \hline
+  \end{tabular}
 \end{table}
 …
 \subsection{XML reference tables}
 \label{subsec:IOM_xmlref}
+\label{subsec:DIA_IOM_xmlref}
 \begin{enumerate}
 …
 \end{xmllines}
 Note that, then the code is crashing, writting real4 variables forces a numerical convection 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}
 …
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|l|X|X|l|X|}
     \hline
 …
     \hline
   \end{tabularx}
   \caption{Context tags}
+  \caption{XIOS: context tags}
 \end{table}
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|l|X|X|X|l|}
     \hline
 …
     \hline
   \end{tabularx}
   \caption{Field tags ("\tt{field\_*}")}
+  \caption{XIOS: field tags ("\texttt{field\_*}")}
 \end{table}
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|l|X|X|X|l|}
     \hline
 …
     \hline
   \end{tabularx}
   \caption{File tags ("\tt{file\_*}")}
+  \caption{XIOS: file tags ("\texttt{file\_*}")}
 \end{table}
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|l|X|X|X|X|}
     \hline
 …
     \hline
   \end{tabularx}
   \caption{Axis tags ("\tt{axis\_*}")}
+  \caption{XIOS: axis tags ("\texttt{axis\_*}")}
 \end{table}
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|l|X|X|X|X|}
     \hline
 …
     \hline
   \end{tabularx}
   \caption{Domain tags ("\tt{domain\_*)}"}
+  \caption{XIOS: domain tags ("\texttt{domain\_*)}"}
 \end{table}
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|l|X|X|X|X|}
     \hline
 …
     \hline
   \end{tabularx}
   \caption{Grid tags ("\tt{grid\_*}")}
+  \caption{XIOS: grid tags ("\texttt{grid\_*}")}
 \end{table}
 …
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|l|X|l|l|}
     \hline
 …
     \hline
   \end{tabularx}
   \caption{Reference attributes ("\tt{*\_ref}")}
+  \caption{XIOS: reference attributes ("\texttt{*\_ref}")}
 \end{table}
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|l|X|l|l|}
     \hline
 …
     \hline
   \end{tabularx}
   \caption{Domain attributes ("\tt{zoom\_*}")}
+  \caption{XIOS: domain attributes ("\texttt{zoom\_*}")}
 \end{table}
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|l|X|l|l|}
     \hline
 …
     \hline
   \end{tabularx}
   \caption{File attributes}
+  \caption{XIOS: file attributes}
 \end{table}
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|l|X|l|l|}
     \hline
 …
     \hline
   \end{tabularx}
   \caption{Field attributes}
+  \caption{XIOS: field attributes}
 \end{table}
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|l|X|X|X|}
     \hline
 …
     \hline
   \end{tabularx}
   \caption{Miscellaneous attributes}
+  \caption{XIOS: miscellaneous attributes}
 \end{table}
 \subsection{CF metadata standard compliance}
 Output from the XIOS-1.0 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.
+section \autoref{subsec:DIA_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.
 …
 %       NetCDF4 support
 % ================================================================
+\section{NetCDF4 support (\protect\key{netcdf4})}
+\section[NetCDF4 support (\texttt{\textbf{key\_netcdf4}})]
+{NetCDF4 support (\protect\key{netcdf4})}
 \label{sec:DIA_nc4}
 …
 Chunking and compression can lead to significant reductions in file sizes for a small runtime overhead.
 For a fuller discussion on chunking and other performance issues the reader is referred to
 the NetCDF4 documentation found \href{http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Chunking}{here}.
+the NetCDF4 documentation found \href{https://www.unidata.ucar.edu/software/netcdf/docs/netcdf_perf_chunking.html}{here}.
 The new features are only available when the code has been linked with a NetCDF4 library
 …
 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----------------------------------------------------
+\nlst{namnc4}
+\begin{listing}
+  \nlst{namnc4}
+  \caption{\texttt{namnc4}}
+  \label{lst:namnc4}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 …
 \end{forlines}
 \noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\tt 46x38x1} respectively in
 the mono-processor case (\ie global domain of {\small\tt 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
+\noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\texttt 46x38x1} respectively in
+the mono-processor case (\ie\ global domain of {\small\texttt 182x149x31}).
+An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in
+table \autoref{tab:DIA_NC4} which compares the results of two short runs of the ORCA2\_LIM reference configuration with
 a 4x2 mpi partitioning.
 Note the variation in the compression ratio achieved which reflects chiefly the dry to wet volume ratio of
 …
 %------------------------------------------TABLE----------------------------------------------------
 \begin{table}
-  \scriptsize
   \centering
   \begin{tabular}{lrrr}
 …
     ORCA2\_2d\_grid\_W\_0007.nc & 4416    & 1368     & 70\%      \\
   \end{tabular}
+  \caption{
+    \protect\label{tab:NC4}
+    Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression
+  }
+  \caption{Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression}
+  \label{tab:DIA_NC4}
 \end{table}
 %----------------------------------------------------------------------------------------------------
 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  (\protect\ngn{namtrd})}
+\section[Tracer/Dynamics trends (\texttt{namtrd})]
+{Tracer/Dynamics trends (\protect\nam{trd})}
 \label{sec:DIA_trd}
 %------------------------------------------namtrd----------------------------------------------------
+\nlst{namtrd}
+\begin{listing}
+  \nlst{namtrd}
+  \caption{\texttt{namtrd}}
+  \label{lst:namtrd}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 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.
 Note that the output are done with xIOS, and therefore the \key{IOM} is required.
 What is done depends on the \ngn{namtrd} logical set to \forcode{.true.}:
+(\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 \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
 the \key{trdtrc} and \key{trdmld\_trc} CPP keys.
+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 \key{vvl} defined).
+and none of the options have been tested with variable volume (\ie\ \np{ln\_linssh}\forcode{=.true.}).
 % -------------------------------------------------------------------------------------------------------------
 %       On-line Floats trajectories
 % -------------------------------------------------------------------------------------------------------------
+\section{FLO: On-Line Floats trajectories (\protect\key{floats})}
+\label{sec:FLO}
+\section[FLO: On-Line Floats trajectories (\texttt{\textbf{key\_floats}})]
+{FLO: On-Line Floats trajectories (\protect\key{floats})}
+\label{sec:DIA_FLO}
 %--------------------------------------------namflo-------------------------------------------------------
+\nlst{namflo}
+\begin{listing}
+  \nlst{namflo}
+  \caption{\texttt{namflo}}
+  \label{lst:namflo}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------------
 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} namelis 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.}).
 Note that the \cite{Blanke_Raynaud_JPO97} algorithm have the advantage of providing trajectories which
+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.}).
+Note that the \cite{blanke.raynaud_JPO97} algorithm have the advantage of providing trajectories which
 are consistent with the numeric of the code, so that the trajectories never intercept the bathymetry.
 …
 Initial coordinates can be given with Ariane Tools convention
 (IJK coordinates, (\np{ln\_ariane}\forcode{ = .true.}) ) or with longitude and latitude.
 In case of Ariane convention, input filename is \np{init\_float\_ariane}.
+(IJK coordinates, (\np{ln\_ariane}\forcode{=.true.}) ) or with longitude and latitude.
+In case of Ariane convention, input filename is \textit{init\_float\_ariane}.
 Its format is: \\
 {\scriptsize \texttt{I J K nisobfl itrash itrash}}
+{ \texttt{I J K nisobfl itrash}}
 \noindent with:
 …
  - 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
 …
 \noindent Example: \\
 \noindent
 {\scriptsize
+{
   \texttt{
 .00000  90.00000  -1.50000 1.00000   0.00000   \\
 …
 In the other case (longitude and latitude), input filename is init\_float.
 Its format is: \\
 {\scriptsize \texttt{Long Lat depth nisobfl ngrpfl itrash}}
+{ \texttt{Long Lat depth nisobfl ngrpfl itrash}}
 \noindent with:
 …
 \noindent Example: \\
 \noindent
 {\scriptsize
+{
   \texttt{
 .0 0.0 0.0 0 1 1    \\
 …
 \np{jpnfl} is the total number of floats during the run.
 When initial positions are read in a restart file (\np{ln\_rstflo}\forcode{ = .true.} ),
+When initial positions are read in a restart file (\np{ln\_rstflo}\forcode{=.true.} ),
 \np{jpnflnewflo} can be added in the initialization file.
 …
 creation of the float restart file.
 Output data can be written in ascii files (\np{ln\_flo\_ascii}\forcode{ = .true.}).
+Output data can be written in ascii files (\np{ln\_flo\_ascii}\forcode{=.true.}).
 In that case, output filename is trajec\_float.
+Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}).
+There are 2 possibilities:
+- if (\key{iomput}) is used, outputs are selected in  iodef.xml.
+Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{=.false.}) with
+\key{iomput} and outputs selected in iodef.xml.
 Here it is an example of specification to put in files description section:
 …
 \end{xmllines}
- -  if (\key{iomput}) is not used, a file called \ifile{trajec\_float} will be created by IOIPSL library.
- See also \href{http://stockage.univ-brest.fr/~grima/Ariane/}{here} the web site describing the off-line use of
- this marvellous diagnostic tool.
 % -------------------------------------------------------------------------------------------------------------
 %       Harmonic analysis of tidal constituents
 % -------------------------------------------------------------------------------------------------------------
+\section{Harmonic analysis of tidal constituents (\protect\key{diaharm}) }
+\section[Harmonic analysis of tidal constituents (\texttt{\textbf{key\_diaharm}})]
+{Harmonic analysis of tidal constituents (\protect\key{diaharm})}
 \label{sec:DIA_diag_harm}
 %------------------------------------------namdia_harm----------------------------------------------------
+%------------------------------------------nam_diaharm----------------------------------------------------
+%
+\nlst{nam_diaharm}
+\begin{listing}
+  \nlst{nam_diaharm}
+  \caption{\texttt{nam\_diaharm}}
+  \label{lst:nam_diaharm}
+\end{listing}
 %----------------------------------------------------------------------------------------------------------
 …
 This on-line Harmonic analysis is actived with \key{diaharm}.
 Some parameters are available in namelist \ngn{namdia\_harm}:
+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
 …
 %       Sections transports
 % -------------------------------------------------------------------------------------------------------------
+\section{Transports across sections (\protect\key{diadct}) }
+\section[Transports across sections (\texttt{\textbf{key\_diadct}})]
+{Transports across sections (\protect\key{diadct})}
 \label{sec:DIA_diag_dct}
+%------------------------------------------namdct----------------------------------------------------
+\nlst{namdct}
+%------------------------------------------nam_diadct----------------------------------------------------
+\begin{listing}
+  \nlst{nam_diadct}
+  \caption{\texttt{nam\_diadct}}
+  \label{lst:nam_diadct}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 …
 Each section is defined by the coordinates of its 2 extremities.
 The pathways between them are contructed using tools which can be found in \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT}
 and are written in a binary file \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is later read in by
 NEMO to compute on-line transports.
+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.
 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{namdct} 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
 …
 \subsubsection{Creating a binary file containing the pathway of each section}
 In \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT/run},
+In \texttt{tools/SECTIONS\_DIADCT/run},
 the file \textit{ {list\_sections.ascii\_global}} contains a list of all the sections that are to be computed
 (this list of sections is based on MERSEA project metrics).
 …
 Each section is defined by: \\
 \noindent {\scriptsize \texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name}} \\
+\noindent { \texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name}} \\
 with:
 …
  - \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;
 …
 \noindent If nclass $\neq$ 0, the next lines contain the class type and the nclass bounds: \\
 {\scriptsize
+{
   \texttt{
     long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name \\
 …
  - \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\_ORCA2\_LIM} 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
 …
  and the ATL\_Cuba\_Florida with 4 temperature clases (5 class bounds), are shown: \\
  \noindent
  {\scriptsize
+ {
    \texttt{
      -68.    -54.5   -60.    -64.7  00 okstrpond noice ACC\_Drake\_Passage \\
 …
 The output format is: \\
 {\scriptsize
+{
   \texttt{
     date, time-step number, section number,                \\
 …
 \begin{table}
-  \scriptsize
   \begin{tabular}{|l|l|l|l|l|}
     \hline
 …
 The steric effect is therefore not explicitely represented.
 This approximation does not represent a serious error with respect to the flow field calculated by the model
 \citep{Greatbatch_JGR94}, but extra attention is required when investigating sea level,
+\citep{greatbatch_JGR94}, but extra attention is required when investigating sea level,
 as steric changes are an important contribution to local changes in sea level on seasonal and climatic time scales.
 This is especially true for investigation into sea level rise due to global warming.
 Fortunately, the steric contribution to the sea level consists of a spatially uniform component that
 can be diagnosed by considering the mass budget of the world ocean \citep{Greatbatch_JGR94}.
+can be diagnosed by considering the mass budget of the world ocean \citep{greatbatch_JGR94}.
 In order to better understand how global mean sea level evolves and thus how the steric sea level can be diagnosed,
 we compare, in the following, the non-Boussinesq and Boussinesq cases.
 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$).
 …
     \mathcal{V} &=  \mathcal{A}  \;\bar{\eta}
   \end{split}
   \label{eq:MV_nBq}
+  \label{eq:DIA_MV_nBq}
 \end{equation}
 …
   \frac{1}{e_3} \partial_t ( e_3\,\rho) + \nabla( \rho \, \textbf{U} )
   = \left. \frac{\textit{emp}}{e_3}\right|_\textit{surface}
   \label{eq:Co_nBq}
+  \label{eq:DIA_Co_nBq}
 \end{equation}
 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}
   \partial_t \mathcal{M} = \mathcal{A} \;\overline{\textit{emp}}
   \label{eq:Mass_nBq}
+  \label{eq:DIA_Mass_nBq}
 \end{equation}
 where $\overline{\textit{emp}} = \int_S \textit{emp}\,ds$ is the net mass flux through the ocean surface.
 Bringing \autoref{eq:Mass_nBq} and the time derivative of \autoref{eq:MV_nBq} together leads to
+Bringing \autoref{eq:DIA_Mass_nBq} and the time derivative of \autoref{eq:DIA_MV_nBq} together leads to
 the evolution equation of the mean sea level
 …
   \partial_t \bar{\eta} = \frac{\overline{\textit{emp}}}{ \bar{\rho}}
   - \frac{\mathcal{V}}{\mathcal{A}} \;\frac{\partial_t \bar{\rho} }{\bar{\rho}}
   \label{eq:ssh_nBq}
+  \label{eq:DIA_ssh_nBq}
 \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:DIA_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).
 In particular, the mass conservation equation, \autoref{eq:Co_nBq}, degenerates into the incompressibility equation:
+the gravity (\ie\ in the hydrostatic balance of the primitive Equations).
+In particular, the mass conservation equation, \autoref{eq:DIA_Co_nBq}, degenerates into the incompressibility equation:
 \[
   \frac{1}{e_3} \partial_t ( e_3 ) + \nabla( \textbf{U} ) = \left. \frac{\textit{emp}}{\rho_o \,e_3}\right|_ \textit{surface}
   % \label{eq:Co_Bq}
+  % \label{eq:DIA_Co_Bq}
 \]
 …
 \[
   \partial_t \mathcal{V} = \mathcal{A} \;\frac{\overline{\textit{emp}}}{\rho_o}
   % \label{eq:V_Bq}
+  % \label{eq:DIA_V_Bq}
 \]
 …
 the ocean surface, not by changes in mean mass of the ocean: the steric effect is missing in a Boussinesq fluid.
 Nevertheless, following \citep{Greatbatch_JGR94}, the steric effect on the volume can be diagnosed by
 considering the mass budget of the ocean.
+Nevertheless, following \citep{greatbatch_JGR94}, the steric effect on the volume can be diagnosed by
+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
 \citep{Greatbatch_JGR94}.
+\citep{greatbatch_JGR94}.
 In others words, the Boussinesq mass, $\mathcal{M}_o$, can be related to $\mathcal{M}$,
 the total mass of the ocean seen by the Boussinesq model, via the steric contribution to the sea level,
 …
 \begin{equation}
   \mathcal{M}_o = \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A}
   \label{eq:M_Bq}
+  \label{eq:DIA_M_Bq}
 \end{equation}
 …
 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})
 in \autoref{eq:M_Bq} leads to a very simple form for the steric height:
+where $d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO\ (cf. \autoref{subsec:TRA_eos})
+in \autoref{eq:DIA_M_Bq} leads to a very simple form for the steric height:
 \begin{equation}
   \eta_s = - \frac{1}{\mathcal{A}} \mathcal{D}
   \label{eq:steric_Bq}
+  \label{eq:DIA_steric_Bq}
 \end{equation}
 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.
 …
 This value is a sensible choice for the reference density used in a Boussinesq ocean climate model since,
 with the exception of only a small percentage of the ocean, density in the World Ocean varies by no more than
 $\%$ from this value (\cite{Gill1982}, page 47).
+$\%$ from this value (\cite{gill_bk82}, page 47).
 Second, we have assumed here that the total ocean surface, $\mathcal{A}$,
 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 \key{vvl} defined, it is given by
+Third, the discretisation of \autoref{eq:DIA_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
 \[
   \eta_s = - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t} e_{2t} e_{3t} }{ \sum_{i,\,j,\,k}       e_{1t} e_{2t} e_{3t} }
   % \label{eq:discrete_steric_Bq_nfs}
+  % \label{eq:DIA_discrete_steric_Bq_nfs}
 \]
 …
   \eta_s = - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t}e_{2t}e_{3t} + \sum_{i,\,j} d_a\; e_{1t}e_{2t} \eta }
                   { \sum_{i,\,j,\,k}       e_{1t}e_{2t}e_{3t} + \sum_{i,\,j}       e_{1t}e_{2t} \eta }
   % \label{eq:discrete_steric_Bq_fs}
+  % \label{eq:DIA_discrete_steric_Bq_fs}
 \]
 …
 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_al_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.
 …
 \[
   \eta_s = - \frac{1}{\mathcal{A}} \int_D d_a(T,S_o,p_o) \,dv
   % \label{eq:thermosteric_Bq}
+  % \label{eq:DIA_thermosteric_Bq}
 \]
 where $S_o$ and $p_o$ are the initial salinity and pressure, respectively.
+Both steric and thermosteric sea level are computed in \mdl{diaar5} which needs the \key{diaar5} defined to
+be called.
+Both steric and thermosteric sea level are computed in \mdl{diaar5}.
 % -------------------------------------------------------------------------------------------------------------
 %       Other Diagnostics
 % -------------------------------------------------------------------------------------------------------------
+\section{Other diagnostics (\protect\key{diahth}, \protect\key{diaar5})}
+\section[Other diagnostics]
+{Other diagnostics}
 \label{sec:DIA_diag_others}
 …
 The available ready-to-add diagnostics modules can be found in directory DIA.
+\subsection{Depth of various quantities (\protect\mdl{diahth})}
+\subsection[Depth of various quantities (\textit{diahth.F90})]
+{Depth of various quantities (\protect\mdl{diahth})}
 Among the available diagnostics the following ones are obtained when defining the \key{diahth} CPP key:
 - the mixed layer depth (based on a density criterion \citep{de_Boyer_Montegut_al_JGR04}) (\mdl{diahth})
+- the mixed layer depth (based on a density criterion \citep{de-boyer-montegut.madec.ea_JGR04}) (\mdl{diahth})
 - the turbocline depth (based on a turbulent mixing coefficient criterion) (\mdl{diahth})
 …
 - the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth})
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]
+  \centering
+  \includegraphics[width=\textwidth]{Fig_mask_subasins}
+  \caption[Decomposition of the World Ocean to compute transports as well as
+  the meridional stream-function]{
+    Decomposition of the World Ocean (here ORCA2) into sub-basin used in to
+    compute the heat and salt transports as well as the meridional stream-function:
+    Atlantic basin (red), Pacific basin (green),
+    Indian basin (blue), Indo-Pacific basin (blue+green).
+    Note that semi-enclosed seas (Red, Med and Baltic seas) as well as
+    Hudson Bay are removed from the sub-basins.
+    Note also that the Arctic Ocean has been split into Atlantic and
+    Pacific basins along the North fold line.
+  }
+  \label{fig:DIA_mask_subasins}
+\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 % -----------------------------------------------------------
 %     Poleward heat and salt transports
+%       CMIP specific diagnostics
 % -----------------------------------------------------------
+\subsection{Poleward heat and salt transports (\protect\mdl{diaptr})}
+%------------------------------------------namptr-----------------------------------------
+\nlst{namptr}
+%-----------------------------------------------------------------------------------------
+The poleward heat and salt transports, their advective and diffusive component,
+and the meriodional stream function can be computed on-line in \mdl{diaptr} \np{ln\_diaptr} to true
+(see the \textit{\ngn{namptr} } namelist below).
+When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed for the Atlantic, Indian,
+\subsection[CMIP specific diagnostics (\textit{diaar5.F90}, \textit{diaptr.F90})]
+{CMIP specific diagnostics (\protect\mdl{diaar5})}
+A series of diagnostics has been added in the \mdl{diaar5} and \mdl{diaptr}.
+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 \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.
 The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains three 2D mask arrays,
+the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:mask_subasins}).
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=1.0\textwidth]{Fig_mask_subasins}
+    \caption{
+      \protect\label{fig:mask_subasins}
+      Decomposition of the World Ocean (here ORCA2) into sub-basin used in to
+      compute the heat and salt transports as well as the meridional stream-function:
+      Atlantic basin (red), Pacific basin (green), Indian basin (bleue), Indo-Pacific basin (bleue+green).
+      Note that semi-enclosed seas (Red, Med and Baltic seas) as well as Hudson Bay are removed from the sub-basins.
+      Note also that the Arctic Ocean has been split into Atlantic and Pacific basins along the North fold line.
+    }
+  \end{center}
+\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:DIA_mask_subasins}).
+%------------------------------------------namptr-----------------------------------------
+\begin{listing}
+  \nlst{namptr}
+  \caption{\texttt{namptr}}
+  \label{lst:namptr}
+\end{listing}
+%-----------------------------------------------------------------------------------------
 % -----------------------------------------------------------
+%       CMIP specific diagnostics
+% -----------------------------------------------------------
+\subsection{CMIP specific diagnostics (\protect\mdl{diaar5})}
+A series of diagnostics has been added in the \mdl{diaar5}.
+They corresponds to outputs that are required for AR5 simulations (CMIP5)
+(see also \autoref{sec:DIA_steric} for one of them).
+Activating those outputs requires to define the \key{diaar5} CPP key.
+% -----------------------------------------------------------
+%       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}
 …
 %------------------------------------------nam_dia25h-------------------------------------
+\nlst{nam_dia25h}
+\begin{listing}
+  \nlst{nam_dia25h}
+  \caption{\texttt{nam\_dia25h}}
+  \label{lst:nam_dia25h}
+\end{listing}
 %-----------------------------------------------------------------------------------------
 …
 %------------------------------------------nam_diatmb-----------------------------------------------------
+\nlst{nam_diatmb}
+\begin{listing}
+  \nlst{nam_diatmb}
+  \caption{\texttt{nam\_diatmb}}
+  \label{lst:nam_diatmb}
+\end{listing}
 %----------------------------------------------------------------------------------------------------------
 …
 \[
   C_u = |u|\frac{\rdt}{e_{1u}}, \quad C_v = |v|\frac{\rdt}{e_{2v}}, \quad C_w = |w|\frac{\rdt}{e_{3w}}
   % \label{eq:CFL}
+  % \label{eq:DIA_CFL}
 \]
 …
 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_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_DIU.tex

-                      r10442
+                      r11564
 \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_{\rm{cs}}$ and $\Delta T_{\rm{wl}}$) and
+($\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}
+\begin{listing}
+  \nlst{namdiu}
+  \caption{\texttt{namdiu}}
+  \label{lst:namdiu}
+\end{listing}
 This namelist contains only two variables:
 \begin{description}
 …
   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.
 %===============================================================
 \section{Warm layer model}
 \label{sec:warm_layer_sec}
+\label{sec:DIU_warm_layer_sec}
 %===============================================================
 The warm layer is calculated using the model of \citet{Takaya_al_JGR10} (TAKAYA10 model hereafter).
+The warm layer is calculated using the model of \citet{takaya.bidlot.ea_JGR10} (TAKAYA10 model hereafter).
 This is a simple flux based model that is defined by the equations
 \begin{align}
 \frac{\partial{\Delta T_{\rm{wl}}}}{\partial{t}}&=&\frac{Q(\nu+1)}{D_T\rho_w c_p
+\frac{\partial{\Delta T_{\mathrm{wl}}}}{\partial{t}}&=&\frac{Q(\nu+1)}{D_T\rho_w c_p
 \nu}-\frac{(\nu+1)ku^*_{w}f(L_a)\Delta T}{D_T\Phi\!\left(\frac{D_T}{L}\right)} \mbox{,}
 \label{eq:ecmwf1} \\
 L&=&\frac{\rho_w c_p u^{*^3}_{w}}{\kappa g \alpha_w Q }\mbox{,}\label{eq:ecmwf2}
+\label{eq:DIU_ecmwf1} \\
+L&=&\frac{\rho_w c_p u^{*^3}_{w}}{\kappa g \alpha_w Q }\mbox{,}\label{eq:DIU_ecmwf2}
 \end{align}
 where $\Delta T_{\rm{wl}}$ is the temperature difference between the top of the warm layer and the depth $D_T=3$\,m at which there is assumed to be no diurnal signal.
 In equation (\autoref{eq:ecmwf1}) $\alpha_w=2\times10^{-4}$ is the thermal expansion coefficient of water,
+where $\Delta T_{\mathrm{wl}}$ is the temperature difference between the top of the warm layer and the depth $D_T=3$\,m at which there is assumed to be no diurnal signal.
+In equation (\autoref{eq:DIU_ecmwf1}) $\alpha_w=2\times10^{-4}$ is the thermal expansion coefficient of water,
 $\kappa=0.4$ is von K\'{a}rm\'{a}n's constant, $c_p$ is the heat capacity at constant pressure of sea water,
 $\rho_w$ is the water density, and $L$ is the Monin-Obukhov length.
 The tunable variable $\nu$ is a shape parameter that defines the expected subskin temperature profile via
 $T(z) = T(0) - \left( \frac{z}{D_T} \right)^\nu \Delta T_{\rm{wl}}$,
+$T(z) = T(0) - \left( \frac{z}{D_T} \right)^\nu \Delta T_{\mathrm{wl}}$,
 where $T$ is the absolute temperature and $z\le D_T$ is the depth below the top of the warm layer.
 The influence of wind on TAKAYA10 comes through the magnitude of the friction velocity of the water $u^*_{w}$,
 …
 the relationship $u^*_{w} = u_{10}\sqrt{\frac{C_d\rho_a}{\rho_w}}$, where $C_d$ is the drag coefficient,
 and $\rho_a$ is the density of air.
 The symbol $Q$ in equation (\autoref{eq:ecmwf1}) is the instantaneous total thermal energy flux into
+The symbol $Q$ in equation (\autoref{eq:DIU_ecmwf1}) is the instantaneous total thermal energy flux into
 the diurnal layer, \ie
 \[
   Q = Q_{\rm{sol}} + Q_{\rm{lw}} + Q_{\rm{h}}\mbox{,}
   % \label{eq:e_flux_eqn}
+  Q = Q_{\mathrm{sol}} + Q_{\mathrm{lw}} + Q_{\mathrm{h}}\mbox{,}
+  % \label{eq:DIU_e_flux_eqn}
 \]
 where $Q_{\rm{h}}$ is the sensible and latent heat flux, $Q_{\rm{lw}}$ is the long wave flux,
 and $Q_{\rm{sol}}$ is the solar flux absorbed within the diurnal warm layer.
 For $Q_{\rm{sol}}$ the 9 term representation of \citet{Gentemann_al_JGR09} is used.
 In equation \autoref{eq:ecmwf1} the function $f(L_a)=\max(1,L_a^{\frac{2}{3}})$,
+where $Q_{\mathrm{h}}$ is the sensible and latent heat flux, $Q_{\mathrm{lw}}$ is the long wave flux,
+and $Q_{\mathrm{sol}}$ is the solar flux absorbed within the diurnal warm layer.
+For $Q_{\mathrm{sol}}$ the 9 term representation of \citet{gentemann.minnett.ea_JGR09} is used.
+In equation \autoref{eq:DIU_ecmwf1} the function $f(L_a)=\max(1,L_a^{\frac{2}{3}})$,
 where $L_a=0.3$\footnote{
   This is a global average value, more accurately $L_a$ could be computed as $L_a=(u^*_{w}/u_s)^{\frac{1}{2}}$,
 …
 \zeta^2}{1+3\zeta+0.25\zeta^2} &(\zeta \ge 0) \\
                                     (1 - 16\zeta)^{-\frac{1}{2}} & (\zeta < 0) \mbox{,}
                                     \end{array} \right. \label{eq:stab_func_eqn}
+                                    \end{array} \right. \label{eq:DIU_stab_func_eqn}
 \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
 equation (\autoref{eq:ecmwf2})).
+where $\zeta=\frac{D_T}{L}$.  It is clear that the first derivative of (\autoref{eq:DIU_stab_func_eqn}),
+and thus of (\autoref{eq:DIU_ecmwf1}), is discontinuous at $\zeta=0$ (\ie\ $Q\rightarrow0$ in
+equation (\autoref{eq:DIU_ecmwf2})).
 The two terms on the right hand side of (\autoref{eq:ecmwf1}) represent different processes.
+The two terms on the right hand side of (\autoref{eq:DIU_ecmwf1}) represent different processes.
 The first term is simply the diabatic heating or cooling of the diurnal warm layer due to
 thermal energy fluxes into and out of the layer.
 …
 \section{Cool skin model}
 \label{sec:cool_skin_sec}
+\label{sec:DIU_cool_skin_sec}
 %===============================================================
 The cool skin is modelled using the framework of \citet{Saunders_JAS82} who used a formulation of the near surface temperature difference based upon the heat flux and the friction velocity $u^*_{w}$.
 As the cool skin is so thin (~1\,mm) we ignore the solar flux component to the heat flux and the Saunders equation for the cool skin temperature difference $\Delta T_{\rm{cs}}$ becomes
+The cool skin is modelled using the framework of \citet{saunders_JAS67} who used a formulation of the near surface temperature difference based upon the heat flux and the friction velocity $u^*_{w}$.
+As the cool skin is so thin (~1\,mm) we ignore the solar flux component to the heat flux and the Saunders equation for the cool skin temperature difference $\Delta T_{\mathrm{cs}}$ becomes
 \[
   % \label{eq:sunders_eqn}
   \Delta T_{\rm{cs}}=\frac{Q_{\rm{ns}}\delta}{k_t} \mbox{,}
+  % \label{eq:DIU_sunders_eqn}
+  \Delta T_{\mathrm{cs}}=\frac{Q_{\mathrm{ns}}\delta}{k_t} \mbox{,}
 \]
 where $Q_{\rm{ns}}$ is the, usually negative, non-solar heat flux into the ocean and
+where $Q_{\mathrm{ns}}$ is the, usually negative, non-solar heat flux into the ocean and
 $k_t$ is the thermal conductivity of sea water.
 $\delta$ is the thickness of the skin layer and is given by
 \begin{equation}
 \label{eq:sunders_thick_eqn}
+\label{eq:DIU_sunders_thick_eqn}
 \delta=\frac{\lambda \mu}{u^*_{w}} \mbox{,}
 \end{equation}
 where $\mu$ is the kinematic viscosity of sea water and $\lambda$ is a constant of proportionality which
 \citet{Saunders_JAS82} suggested varied between 5 and 10.
+\citet{saunders_JAS67} suggested varied between 5 and 10.
 The value of $\lambda$ used in equation (\autoref{eq:sunders_thick_eqn}) is that of \citet{Artale_al_JGR02},
 which is shown in \citet{Tu_Tsuang_GRL05} to outperform a number of other parametrisations at
+The value of $\lambda$ used in equation (\autoref{eq:DIU_sunders_thick_eqn}) is that of \citet{artale.iudicone.ea_JGR02},
+which is shown in \citet{tu.tsuang_GRL05} to outperform a number of other parametrisations at
 both low and high wind speeds.
 Specifically,
 \[
   % \label{eq:artale_lambda_eqn}
+  % \label{eq:DIU_artale_lambda_eqn}
   \lambda = \frac{ 8.64\times10^4 u^*_{w} k_t }{ \rho c_p h \mu \gamma }\mbox{,}
 \]
 …
 $\gamma$ is a dimensionless function of wind speed $u$:
 \[
   % \label{eq:artale_gamma_eqn}
+  % \label{eq:DIU_artale_gamma_eqn}
   \gamma =
   \begin{cases}

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_DOM.tex

-                      r10502
+                      r11564
 \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)
 …
 %     - domclo:  closed sea and lakes.... management of closea sea area : specific to global configuration, both forced and coupled
+\vfill
+\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:DOMCFG})
+    }                                                                                            \\
+    {\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 discretization on a grid, and numerical algorithms.
+Having defined the continuous equations in \autoref{chap:MB} and chosen a time discretisation \autoref{chap:TD},
+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 information relevant to the main directory routines as well as the DOM (DOMain) directory.
+and other relevant information about the DOM (DOMain) source code modules.
 % ================================================================
 …
 % -------------------------------------------------------------------------------------------------------------
 %        Arrangement of Variables
+%        Arrangement of Variables
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Arrangement of variables}
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!tb]
+  \begin{center}
+    \includegraphics[]{Fig_cell}
+    \caption{
+      \protect\label{fig:cell}
+      Arrangement of variables.
+      $t$ indicates scalar points where temperature, salinity, density, pressure and
+      horizontal divergence are defined.
+      $(u,v,w)$ indicates vector points, and $f$ indicates vorticity points where both relative and
+      planetary vorticities are defined.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_cell}
+  \caption[Arrangement of variables in the unit cell of space domain]{
+    Arrangement of variables in the unit cell of space domain.
+    $t$ indicates scalar points where
+    temperature, salinity, density, pressure and horizontal divergence are defined.
+    $(u,v,w)$ indicates vector points,
+    and $f$ indicates vorticity points where
+    both relative and planetary vorticities are defined.}
+  \label{fig:DOM_cell}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 The numerical techniques used to solve the Primitive Equations in this model are based on the traditional,
 centred second-order finite difference approximation.
 Special attention has been given to the homogeneity of the solution in the three space directions.
+Special attention has been given to the homogeneity of the solution in the three spatial directions.
 The arrangement of variables is the same in all directions.
 It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with vector points $(u, v, w)$ defined in
 the centre of each face of the cells (\autoref{fig:cell}).
+the centre of each face of the cells (\autoref{fig:DOM_cell}).
 This is the generalisation to three dimensions of the well-known ``C'' grid in Arakawa's classification
 \citep{Mesinger_Arakawa_Bk76}.
+\citep{mesinger.arakawa_bk76}.
 The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge and
 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}.
+The grid-points are located at integer or integer and a half value of $(i,j,k)$ as indicated on \autoref{tab:DOM_cell}.
 In all the following, subscripts $u$, $v$, $w$, $f$, $uw$, $vw$ or $fw$ indicate the position of
 the grid-point where the scale factors are defined.
 Each scale factor is defined as the local analytical value provided by \autoref{eq:scale_factors}.
+Each scale factor is defined as the local analytical value provided by \autoref{eq:MB_scale_factors}.
 As a result, the mesh on which partial derivatives $\pd[]{\lambda}$, $\pd[]{\varphi}$ and
 $\pd[]{z}$ are evaluated in a uniform mesh with a grid size of unity.
+$\pd[]{z}$ are evaluated is a uniform mesh with a grid size of unity.
 Discrete partial derivatives are formulated by the traditional, centred second order finite difference approximation
 while the scale factors are chosen equal to their local analytical value.
 …
 centred finite difference approximation, not from their analytical expression.
 This preserves the symmetry of the discrete set of equations and therefore satisfies many of
 the continuous properties (see \autoref{apdx:C}).
+the continuous properties (see \autoref{apdx:INVARIANTS}).
 A similar, related remark can be made about the domain size:
 when needed, an area, volume, or the total ocean depth must be evaluated as the sum of the relevant scale factors
+when needed, an area, volume, or the total ocean depth must be evaluated as the product or sum of the relevant scale factors
 (see \autoref{eq:DOM_bar} in the next section).
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{table}[!tb]
   \begin{center}
     \begin{tabular}{|p{46pt}|p{56pt}|p{56pt}|p{56pt}|}
       \hline
       T  & $i      $ & $j      $ & $k      $ \\
       \hline
       u  & $i + 1/2$ & $j      $ & $k      $ \\
       \hline
       v  & $i      $ & $j + 1/2$ & $k      $ \\
       \hline
       w  & $i      $ & $j      $ & $k + 1/2$ \\
       \hline
       f  & $i + 1/2$ & $j + 1/2$ & $k      $ \\
       \hline
       uw & $i + 1/2$ & $j      $ & $k + 1/2$ \\
       \hline
       vw & $i      $ & $j + 1/2$ & $k + 1/2$ \\
       \hline
       fw & $i + 1/2$ & $j + 1/2$ & $k + 1/2$ \\
       \hline
     \end{tabular}
     \caption{
       \protect\label{tab:cell}
       Location of grid-points as a function of integer or integer and a half value of the column, line or level.
       This indexing is only used for the writing of the semi -discrete equation.
       In the code, the indexing uses integer values only and has a reverse direction in the vertical
       (see \autoref{subsec:DOM_Num_Index})
+    }
   \end{center}
+  \centering
+  \begin{tabular}{|p{46pt}|p{56pt}|p{56pt}|p{56pt}|}
+    \hline
+    t & $i      $ & $j      $ & $k      $ \\
+    \hline
+    u & $i + 1/2$ & $j      $ & $k      $ \\
+    \hline
+    v & $i      $ & $j + 1/2$ & $k      $ \\
+    \hline
+    w & $i      $ & $j      $ & $k + 1/2$ \\
+    \hline
+    f & $i + 1/2$ & $j + 1/2$ & $k      $ \\
+    \hline
+    uw   & $i + 1/2$ & $j      $ & $k + 1/2$ \\
+    \hline
+    vw   & $i      $ & $j + 1/2$ & $k + 1/2$ \\
+    \hline
+    fw   & $i + 1/2$ & $j + 1/2$ & $k + 1/2$ \\
+    \hline
+  \end{tabular}
+  \caption[Location of grid-points]{
+    Location of grid-points as a function of integer or
+    integer and a half value of the column, line or level.
+    This indexing is only used for the writing of the semi -discrete equations.
+    In the code, the indexing uses integer values only and
+    is positive downwards in the vertical with $k=1$ at the surface.
+    (see \autoref{subsec:DOM_Num_Index})}
+  \label{tab:DOM_cell}
 \end{table}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+% -------------------------------------------------------------------------------------------------------------
+%        Vector Invariant Formulation
+Note that the definition of the scale factors
+(\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}.
+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
+the distance between the $u$-points on each side of the $t$-point.
+Relying on an analytical transformation has two advantages:
+firstly, there is no ambiguity in the scale factors appearing in the discrete equations,
+since they are first introduced in the continuous equations;
+secondly, analytical transformations encourage good practice by the definition of smoothly varying grids
+(rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{treguier.dukowicz.ea_JGR96}.
+An example of the effect of such a choice is shown in \autoref{fig:DOM_zgr_e3}.
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]
+  \centering
+  \includegraphics[width=\textwidth]{Fig_zgr_e3}
+  \caption[Comparison of grid-point position, vertical grid-size and scale factors]{
+    Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical,
+    and (b) analytically derived grid-point position and scale factors.
+    For both grids here, the same $w$-point depth has been chosen but
+    in (a) the $t$-points are set half way between $w$-points while
+    in (b) they are defined from an analytical function:
+    $z(k) = 5 \, (k - 1/2)^3 - 45 \, (k - 1/2)^2 + 140 \, (k - 1/2) - 150$.
+    Note the resulting difference between the value of the grid-size $\Delta_k$ and
+    those of the scale factor $e_k$.}
+  \label{fig:DOM_zgr_e3}
+\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+% -------------------------------------------------------------------------------------------------------------
+%        Vector Invariant Formulation
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Discrete operators}
 …
 the midpoint between them are:
 \begin{alignat*}{2}
   % \label{eq:di_mi}
+  % \label{eq:DOM_di_mi}
   \delta_i [q]      &= &       &q (i + 1/2) - q (i - 1/2) \\
   \overline q^{\, i} &= &\big\{ &q (i + 1/2) + q (i - 1/2) \big\} / 2
 …
 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 $t$-point.
+Following \autoref{eq:MB_grad} and \autoref{eq:MB_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:
 \[
 …
 \end{multline*}
 Following \autoref{eq:PE_curl} and \autoref{eq:PE_div}, a vector $\vect A = (a_1,a_2,a_3)$ defined at
+Following \autoref{eq:MB_curl} and \autoref{eq:MB_div}, a vector $\vect A = (a_1,a_2,a_3)$ defined at
 vector points $(u,v,w)$ has its three curl components defined at $vw$-, $uw$, and $f$-points, and
 its divergence defined at $t$-points:
 …
 \end{equation}
 The vertical average over the whole water column denoted by an overbar becomes for a quantity $q$ which
 is a masked field (i.e. equal to zero inside solid area):
+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):
 \begin{equation}
   \label{eq:DOM_bar}
 …
 \end{equation}
 where $H_q$  is the ocean depth, which is the masked sum of the vertical scale factors at $q$ points,
 $k^b$ and $k^o$ are the bottom and surface $k$-indices, and the symbol $k^o$ refers to a summation over
+$k^b$ and $k^o$ are the bottom and surface $k$-indices, and the symbol $\sum \limits_k$ refers to a summation over
 all grid points of the same type in the direction indicated by the subscript (here $k$).
 …
 vector points $(u,v,w)$.
 Let $a$ and $b$ be two fields defined on the mesh, with value zero inside continental area.
 Using integration by parts it can be shown that the differencing operators ($\delta_i$, $\delta_j$ and $\delta_k$)
+Let $a$ and $b$ be two fields defined on the mesh, with a value of zero inside continental areas.
+It can be shown that the differencing operators ($\delta_i$, $\delta_j$ and $\delta_k$)
 are skew-symmetric linear operators, and further that the averaging operators $\overline{\cdots}^{\, i}$,
 $\overline{\cdots}^{\, j}$ and $\overline{\cdots}^{\, k}$) are symmetric linear operators, \ie
 …
 \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
+These two properties will be used extensively in the \autoref{apdx:INVARIANTS} to
 demonstrate integral conservative properties of the discrete formulation chosen.
 % -------------------------------------------------------------------------------------------------------------
 %        Numerical Indexing
+%        Numerical Indexing
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Numerical indexing}
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!tb]
+  \begin{center}
+    \includegraphics[]{Fig_index_hor}
+    \caption{
+      \protect\label{fig:index_hor}
+      Horizontal integer indexing used in the \fortran code.
+      The dashed area indicates the cell in which variables contained in arrays have the same $i$- and $j$-indices
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_index_hor}
+  \caption[Horizontal integer indexing]{
+    Horizontal integer indexing used in the \fortran\ code.
+    The dashed area indicates the cell in which
+    variables contained in arrays have the same $i$- and $j$-indices}
+  \label{fig:DOM_index_hor}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 The array representation used in the \fortran code requires an integer indexing while
 the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with the use of
 integer values for $t$-points and both integer and integer and a half values for all the other points.
 Therefore a specific integer indexing must be defined for points other than $t$-points
 (\ie velocity and vorticity grid-points).
 Furthermore, the direction of the vertical indexing has been changed so that the surface level is at $k = 1$.
+The array representation used in the \fortran\ code requires an integer indexing.
+However, the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with the use of
+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).
+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}
 \label{subsec:DOM_Num_Index_hor}
 The indexing in the horizontal plane has been chosen as shown in \autoref{fig:index_hor}.
+The indexing in the horizontal plane has been chosen as shown in \autoref{fig:DOM_index_hor}.
 For an increasing $i$ index ($j$ index),
 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.
+(see the dashed area in \autoref{fig:DOM_index_hor}).
+A $t$-point and its nearest north-east $f$-point have the same $i$-and $j$-indices.
 % -----------------------------------
 %        Vertical indexing
+%        Vertical indexing
 % -----------------------------------
 \subsubsection{Vertical indexing}
 \label{subsec:DOM_Num_Index_vertical}
 In the vertical, the chosen indexing requires special attention since the $k$-axis is re-orientated downward in
 the \fortran code compared to the indexing used in the semi -discrete equations and
+In the vertical, the chosen indexing requires special attention since the direction of the $k$-axis in
+the \fortran\ code is the reverse of that used in the semi -discrete equations and
 given in \autoref{subsec:DOM_cell}.
 The sea surface corresponds to the $w$-level $k = 1$ which is the same index as $t$-level just below
 (\autoref{fig:index_vert}).
 The last $w$-level ($k = jpk$) either corresponds to the ocean floor or is inside the bathymetry while
 the last $t$-level is always inside the bathymetry (\autoref{fig:index_vert}).
 Note that for an increasing $k$ index, a $w$-point and the $t$-point just below have the same $k$ index,
+in opposition to what is done in the horizontal plane where
 it is the $t$-point and the nearest velocity points in the direction of the horizontal axis that
 have the same $i$ or $j$ index
 (compare the dashed area in \autoref{fig:index_hor} and \autoref{fig:index_vert}).
+The sea surface corresponds to the $w$-level $k = 1$, which is the same index as the $t$-level just below
+(\autoref{fig:DOM_index_vert}).
+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:DOM_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
+(compare the dashed area in \autoref{fig:DOM_index_hor} and \autoref{fig:DOM_index_vert}).
 Since the scale factors are chosen to be strictly positive,
+a \textit{minus sign} appears in the \fortran code \textit{before all the vertical derivatives} of
+the discrete equations given in this 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.
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!pt]
+  \begin{center}
+    \includegraphics[]{Fig_index_vert}
+    \caption{
+      \protect\label{fig:index_vert}
+      Vertical integer indexing used in the \fortran code.
+      Note that the $k$-axis is orientated downward.
+      The dashed area indicates the cell in which variables contained in arrays have the same $k$-index.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_index_vert}
+  \caption[Vertical integer indexing]{
+    Vertical integer indexing used in the \fortran\ code.
+    Note that the $k$-axis is oriented downward.
+    The dashed area indicates the cell in which
+    variables contained in arrays have a common $k$-index.}
+  \label{fig:DOM_index_vert}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+% -------------------------------------------------------------------------------------------------------------
+%        Domain configuration
+% -------------------------------------------------------------------------------------------------------------
+\section{Spatial domain configuration}
+\label{subsec:DOM_config}
+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:DOMCFG}.
+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}).
 % -----------------------------------
 %        Domain Size
 % -----------------------------------
 \subsubsection{Domain size}
+\subsection{Domain size}
 \label{subsec:DOM_size}
 The total size of the computational domain is set by the parameters \np{jpiglo},
 \np{jpjglo} and \np{jpkglo} in the $i$, $j$ and $k$ directions respectively.
 Parameters $jpi$ and $jpj$ refer to the size of each processor subdomain when
+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}).
+% ================================================================
+% Domain: List of fields needed
+% ================================================================
+\section{Needed fields}
+\label{sec:DOM_fields}
+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 values of as indicated in \autoref{tab:cell}.
+The associated scale factors are defined using the analytical first derivative of the transformation
+\autoref{eq:scale_factors}.
+Necessary fields for configuration definition are:
+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 \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})}
+\label{subsec:DOM_hgr}
+% ================================================================
+% Domain: List of hgr-related fields needed
+% ================================================================
+\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{clines}
+int    jpiglo, jpjglo, jpkglo            /* global domain sizes                                          */
+int    jperio                            /* lateral global domain b.c.                                   */
+double glamt, glamu, glamv, glamf        /* geographic longitude (t,u,v and f points respectively)       */
+double gphit, gphiu, gphiv, gphif        /* geographic latitude                                          */
+double e1t, e1u, e1v, e1f                /* horizontal scale factors                                     */
+double e2t, e2u, e2v, e2f                /* horizontal scale factors                                     */
+\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:DOM_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{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{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.
+% ================================================================
+% Domain: Vertical Grid (domzgr)
+% ================================================================
+\subsection[Vertical grid (\textit{domzgr.F90})]
+{Vertical grid (\protect\mdl{domzgr})}
+\label{subsec:DOM_zgr}
+%-----------------------------------------namdom-------------------------------------------
+\begin{listing}
+  \nlst{namdom}
+  \caption{\texttt{namdom}}
+  \label{lst:namdom}
+\end{listing}
+%-------------------------------------------------------------------------------------------------------------
+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 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
+$(i,j)$ location of the horizontal grid.
+\end{enumerate}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!tb]
+  \centering
+  \includegraphics[width=\textwidth]{Fig_z_zps_s_sps}
+  \caption[Ocean bottom regarding coordinate systems ($z$, $s$ and hybrid $s-z$)]{
+    The ocean bottom as seen by the model:
+    (a) $z$-coordinate with full step,
+    (b) $z$-coordinate with partial step,
+    (c) $s$-coordinate: terrain following representation,
+    (d) hybrid $s-z$ coordinate,
+    (e) hybrid $s-z$ coordinate with partial step, and
+    (f) same as (e) but in the non-linear free surface (\protect\np{ln\_linssh}\forcode{=.false.}).
+    Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e).}
+  \label{fig:DOM_z_zps_s_sps}
+\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+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 \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:DOM_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.
+\medskip
+The decision on these choices must be made when the \np{cn\_domcfg} file is constructed.
+Three main choices are offered (\autoref{fig:DOM_z_zps_s_sps}a-c):
 \begin{itemize}
+\item
+  Geographic position:
+  longitude with \texttt{glamt}, \texttt{glamu}, \texttt{glamv}, \texttt{glamf} and
+  latitude  with \texttt{gphit}, \texttt{gphiu}, \texttt{gphiv}, \texttt{gphif}
+  (all respectively at T, U, V and F point)
+\item
+  Coriolis parameter (if domain not on the sphere): \texttt{ff\_f} and \texttt{ff\_t}
+  (at T and F point)
+\item
+  Scale factors:
+  \texttt{e1t}, \texttt{e1u}, \texttt{e1v} and \texttt{e1f} (on i direction),
+  \texttt{e2t}, \texttt{e2u}, \texttt{e2v} and \texttt{e2f} (on j direction) and
+  \texttt{ie1e2u\_v}, \texttt{e1e2u}, \texttt{e1e2v}. \\
+  \texttt{e1e2u}, \texttt{e1e2v} are u and v surfaces (if gridsize reduction in some straits),
+  \texttt{ie1e2u\_v} is to flag set u and v surfaces are neither read nor computed.
+\item $z$-coordinate with full step bathymetry (\np{ln\_zco}\forcode{=.true.}),
+\item $z$-coordinate with partial step ($zps$) bathymetry (\np{ln\_zps}\forcode{=.true.}),
+\item Generalized, $s$-coordinate (\np{ln\_sco}\forcode{=.true.}).
 \end{itemize}
+These fields can be read in an domain input file which name is setted in \np{cn\_domcfg} parameter specified in
+\ngn{namcfg}.
+\nlst{namcfg}
+Or they can be defined in an analytical way in \path{MY_SRC} directory of the configuration.
+For Reference Configurations of NEMO input domain files are supplied by NEMO System Team.
+For analytical definition of input fields two routines are supplied: \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}.
+They are an example of GYRE configuration parameters, and they are available in \path{src/OCE/USR} directory,
+they provide the horizontal and vertical mesh.
+% -------------------------------------------------------------------------------------------------------------
+%        Needed fields
+% -------------------------------------------------------------------------------------------------------------
+%\subsection{List of needed fields to build DOMAIN}
+%\label{subsec:DOM_fields_list}
+% ================================================================
+% Domain: Horizontal Grid (mesh)
+% ================================================================
+\section{Horizontal grid mesh (\protect\mdl{domhgr})}
+\label{sec:DOM_hgr}
+% -------------------------------------------------------------------------------------------------------------
+%        Coordinates and scale factors
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Coordinates and scale factors}
+\label{subsec:DOM_hgr_coord_e}
+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 values of as indicated in \autoref{tab:cell}.
+The associated scale factors are defined using the analytical first derivative of the transformation
+\autoref{eq:scale_factors}.
+These definitions are done in two modules, \mdl{domhgr} and \mdl{domzgr},
+which provide the horizontal and vertical meshes, respectively.
+This section deals with the horizontal mesh parameters.
+In a horizontal plane, the location of all the model grid points is defined from
+the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$.
+The horizontal scale factors are calculated using \autoref{eq:scale_factors}.
+For example, when the longitude and latitude are function of a single value
+($i$ and $j$, respectively) (geographical configuration of the mesh),
+the horizontal mesh definition reduces to define the wanted $\lambda(i)$, $\varphi(j)$,
+and their derivatives $\lambda'(i) \ \varphi'(j)$ in the \mdl{domhgr} module.
+The model computes the grid-point positions and scale factors in the horizontal plane as follows:
+\begin{align*}
+   \lambda_t &\equiv \text{glamt} =      \lambda (i      )
+  &\varphi_t &\equiv \text{gphit} =      \varphi (j      ) \\
+   \lambda_u &\equiv \text{glamu} =      \lambda (i + 1/2)
+  &\varphi_u &\equiv \text{gphiu} =      \varphi (j      ) \\
+   \lambda_v &\equiv \text{glamv} =      \lambda (i      )
+  &\varphi_v &\equiv \text{gphiv} =      \varphi (j + 1/2) \\
+   \lambda_f &\equiv \text{glamf} =      \lambda (i + 1/2)
+  &\varphi_f &\equiv \text{gphif} =      \varphi (j + 1/2) \\
+   e_{1t}    &\equiv \text{e1t}   = r_a |\lambda'(i      ) \; \cos\varphi(j      ) |
+  &e_{2t}    &\equiv \text{e2t}   = r_a |\varphi'(j      )                         | \\
+   e_{1u}    &\equiv \text{e1t}   = r_a |\lambda'(i + 1/2) \; \cos\varphi(j      ) |
+  &e_{2u}    &\equiv \text{e2t}   = r_a |\varphi'(j      )                         | \\
+   e_{1v}    &\equiv \text{e1t}   = r_a |\lambda'(i      ) \; \cos\varphi(j + 1/2) |
+  &e_{2v}    &\equiv \text{e2t}   = r_a |\varphi'(j + 1/2)                         | \\
+   e_{1f}    &\equiv \text{e1t}   = r_a |\lambda'(i + 1/2) \; \cos\varphi(j + 1/2) |
+  &e_{2f}    &\equiv \text{e2t}   = r_a |\varphi'(j + 1/2)                         |
+\end{align*}
+where the last letter of each computational name indicates the grid point considered and
+$r_a$ is the earth radius (defined in \mdl{phycst} along with all universal constants).
+Note that the horizontal position of and scale factors at $w$-points are exactly equal to those of $t$-points,
+thus no specific arrays are defined at $w$-points.
+Note that the definition of the scale factors
+(\ie as the analytical first derivative of the transformation that
+gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$)
+is specific to the \NEMO model \citep{Marti_al_JGR92}.
+As an example, $e_{1t}$ is defined locally at a $t$-point,
+whereas many other models on a C grid choose to define such a scale factor as
+the distance between the $U$-points on each side of the $t$-point.
+Relying on an analytical transformation has two advantages:
+firstly, there is no ambiguity in the scale factors appearing in the discrete equations,
+since they are first introduced in the continuous equations;
+secondly, analytical transformations encourage good practice by the definition of smoothly varying grids
+(rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{Treguier1996}.
+An example of the effect of such a choice is shown in \autoref{fig:zgr_e3}.
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]
+  \begin{center}
+    \includegraphics[]{Fig_zgr_e3}
+    \caption{
+      \protect\label{fig:zgr_e3}
+      Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical,
+      and (b) analytically derived grid-point position and scale factors.
+      For both grids here, the same $w$-point depth has been chosen but
+      in (a) the $t$-points are set half way between $w$-points while
+      in (b) they are defined from an analytical function:
+      $z(k) = 5 \, (k - 1/2)^3 - 45 \, (k - 1/2)^2 + 140 \, (k - 1/2) - 150$.
+      Note the resulting difference between the value of the grid-size $\Delta_k$ and
+      those of the scale factor $e_k$.
+    }
+  \end{center}
+\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+% -------------------------------------------------------------------------------------------------------------
+%        Choice of horizontal grid
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Choice of horizontal grid}
+\label{subsec:DOM_hgr_msh_choice}
+% -------------------------------------------------------------------------------------------------------------
+%        Grid files
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Output grid files}
+\label{subsec:DOM_hgr_files}
+All the arrays relating to a particular ocean model configuration (grid-point position, scale factors, masks)
+can be saved in files if \np{nn\_msh} $\not = 0$ (namelist variable in \ngn{namdom}).
+This can be particularly useful for plots and off-line diagnostics.
+In some cases, the user may choose to make a local modification of a scale factor in the code.
+This is the case in global configurations when restricting the width of a specific strait
+(usually a one-grid-point strait that happens to be too wide due to insufficient model resolution).
+An example is Gibraltar Strait in the ORCA2 configuration.
+When such modifications are done,
+the output grid written when \np{nn\_msh} $\not = 0$ is no more equal to the input grid.
+% ================================================================
+% Domain: Vertical Grid (domzgr)
+% ================================================================
+\section{Vertical grid (\protect\mdl{domzgr})}
+\label{sec:DOM_zgr}
+%-----------------------------------------nam_zgr & namdom-------------------------------------------
+%
+%\nlst{namzgr}
+\nlst{namdom}
+%-------------------------------------------------------------------------------------------------------------
+Variables are defined through the \ngn{namzgr} and \ngn{namdom} namelists.
+In the vertical, the model mesh is determined by four things:
+(1) the bathymetry given in meters;
+(2) the number of levels of the model (\jp{jpk});
+(3) the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and
+(4) the masking system, \ie the number of wet model levels at each
+$(i,j)$ column of points.
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!tb]
+  \begin{center}
+    \includegraphics[]{Fig_z_zps_s_sps}
+    \caption{
+      \protect\label{fig:z_zps_s_sps}
+      The ocean bottom as seen by the model:
+      (a) $z$-coordinate with full step,
+      (b) $z$-coordinate with partial step,
+      (c) $s$-coordinate: terrain following representation,
+      (d) hybrid $s-z$ coordinate,
+      (e) hybrid $s-z$ coordinate with partial step, and
+      (f) same as (e) but in the non-linear free surface (\protect\np{ln\_linssh}~\forcode{= .false.}).
+      Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e).
+    }
+  \end{center}
+\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+The choice of a vertical coordinate, even if it is made through \ngn{namzgr} namelist parameters,
+must be done once of all at the beginning of an experiment.
+It is not intended as an option which can be enabled or disabled in the middle of an experiment.
+Three main choices are offered (\autoref{fig:z_zps_s_sps}):
+$z$-coordinate with full step bathymetry (\np{ln\_zco}~\forcode{= .true.}),
+$z$-coordinate with partial step bathymetry (\np{ln\_zps}~\forcode{= .true.}),
+or generalized, $s$-coordinate (\np{ln\_sco}~\forcode{= .true.}).
+Hybridation of the three main coordinates are available:
+$s-z$ or $s-zps$ coordinate (\autoref{fig:z_zps_s_sps} and \autoref{fig:z_zps_s_sps}).
+By default a non-linear free surface is used: the coordinate follow the time-variation of the free surface so that
+the transformation is time dependent: $z(i,j,k,t)$ (\autoref{fig:z_zps_s_sps}).
+When a linear free surface is assumed (\np{ln\_linssh}~\forcode{= .true.}),
+the vertical coordinate 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).
+The last choice in terms of vertical coordinate concerns the presence (or not) in
+the model domain of ocean cavities beneath ice shelves.
+Setting \np{ln\_isfcav} to true allows to manage ocean cavities, otherwise they are filled in.
+This option is currently only available in $z$- or $zps$-coordinate,
+and partial step are also applied at the ocean/ice shelf interface.
+Contrary to the horizontal grid, the vertical grid is computed in the code and no provision is made for
+reading it from a file.
+The only input file is the bathymetry (in meters) (\ifile{bathy\_meter})
+\footnote{
+  N.B. in full step $z$-coordinate, a \ifile{bathy\_level} file can replace the \ifile{bathy\_meter} file,
+  so that the computation of the number of wet ocean point in each water column is by-passed}.
+If \np{ln\_isfcav}~\forcode{= .true.}, an extra file input file (\ifile{isf\_draft\_meter}) describing
+the ice shelf draft (in meters) is needed.
+After reading the bathymetry, the algorithm for vertical grid definition differs between the different options:
+\begin{description}
+\item[\textit{zco}]
+  set a reference coordinate transformation $z_0(k)$, and set $z(i,j,k,t) = z_0(k)$.
+\item[\textit{zps}]
+  set a reference coordinate transformation $z_0(k)$, and calculate the thickness of the deepest level at
+  each $(i,j)$ point using the bathymetry, to obtain the final three-dimensional depth and scale factor arrays.
+\item[\textit{sco}]
+  smooth the bathymetry to fulfill the hydrostatic consistency criteria and
+  set the three-dimensional transformation.
+\item[\textit{s-z} and \textit{s-zps}]
+  smooth the bathymetry to fulfill the hydrostatic consistency criteria and
+  set the three-dimensional transformation $z(i,j,k)$,
+  and possibly introduce masking of extra land points to better fit the original bathymetry file.
+\end{description}
+%%%
+\gmcomment{   add the description of the smoothing:  envelop topography...}
+%%%
+Unless a linear free surface is used (\np{ln\_linssh}~\forcode{= .false.}),
+the arrays describing the grid point depths and vertical scale factors are three set of
+Additionally, hybrid combinations of the three main coordinates are available:
+$s-z$ or $s-zps$ coordinate (\autoref{fig:DOM_z_zps_s_sps}d and \autoref{fig:DOM_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 using a fixed reference coordinate system which
+computer names have 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 simply set one for all to their reference counterpart.
+% -------------------------------------------------------------------------------------------------------------
+%        Meter Bathymetry
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Meter bathymetry}
+\label{subsec:DOM_bathy}
+Three options are possible for defining the bathymetry, according to the namelist variable \np{nn\_bathy}
+(found in \ngn{namdom} namelist):
+\begin{description}
+\item[\np{nn\_bathy}~\forcode{= 0}]:
+  a flat-bottom domain is defined.
+  The total depth $z_w (jpk)$ is given by the coordinate transformation.
+  The domain can either be a closed basin or a periodic channel depending on the parameter \np{jperio}.
+\item[\np{nn\_bathy}~\forcode{= -1}]:
+  a domain with a bump of topography one third of the domain width at the central latitude.
+  This is meant for the "EEL-R5" configuration, a periodic or open boundary channel with a seamount.
+\item[\np{nn\_bathy}~\forcode{= 1}]:
+  read a bathymetry and ice shelf draft (if needed).
+  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 horizontal ocean mesh.
+  Defining the bathymetry also defines the coastline: where the bathymetry is zero,
+  no model levels are defined (all levels are masked).
+  The \ifile{isfdraft\_meter} file (Netcdf format) provides the ice shelf draft (positive, in meters) at
+  each grid point of the model grid.
+  This file is only needed if \np{ln\_isfcav}~\forcode{= .true.}.
+  Defining the ice shelf draft will also define the ice shelf edge and the grounding line position.
+\end{description}
+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}),
+but the code has to be adapted to the user's configuration.
+% -------------------------------------------------------------------------------------------------------------
+%        z-coordinate  and reference coordinate transformation
+% -------------------------------------------------------------------------------------------------------------
+\subsection[$Z$-coordinate (\protect\np{ln\_zco}~\forcode{= .true.}) and ref. coordinate]
+            {$Z$-coordinate (\protect\np{ln\_zco}~\forcode{= .true.}) and reference coordinate}
+\label{subsec:DOM_zco}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!tb]
+  \begin{center}
+    \includegraphics[]{Fig_zgr}
+    \caption{
+      \protect\label{fig:zgr}
+      Default vertical mesh for ORCA2: 30 ocean levels (L30).
+      Vertical level functions for (a) T-point depth and (b) the associated scale factor as computed from
+      \autoref{eq:DOM_zgr_ana_1} using \autoref{eq:DOM_zgr_coef} in $z$-coordinate.
+    }
+  \end{center}
+\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+The reference coordinate transformation $z_0(k)$ defines the arrays $gdept_0$ and $gdepw_0$ for $t$- and $w$-points,
+respectively.
+As indicated on \autoref{fig:index_vert} \jp{jpk} is the number of $w$-levels.
+$gdepw_0(1)$ is the ocean surface.
+There are at most \jp{jpk}-1 $t$-points inside the ocean,
+the additional $t$-point at $jk = jpk$ is below the sea floor and is not used.
+The vertical location of $w$- and $t$-levels is defined from the analytic expression of the depth $z_0(k)$ whose
+analytical derivative with respect to $k$ provides 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{namcfg} namelist.
+It is possible to define a simple regular vertical grid by giving zero stretching (\np{ppacr}~\forcode{= 0}).
+In that case, the parameters \jp{jpk} (number of $w$-levels) and
+\np{pphmax} (total ocean depth in meters) fully define the grid.
+For climate-related studies it is often desirable to concentrate the vertical resolution near the ocean surface.
+The following function is proposed as a standard for a $z$-coordinate (with either full or partial steps):
+\begin{gather}
+  \label{eq:DOM_zgr_ana_1}
+    z_0  (k) = h_{sur} - h_0 \; k - \; h_1 \; \log  \big[ \cosh ((k - h_{th}) / h_{cr}) \big] \\
+    e_3^0(k) = \lt|    - h_0      -    h_1 \; \tanh \big[        (k - h_{th}) / h_{cr}  \big] \rt|
+\end{gather}
+where $k = 1$ to \jp{jpk} for $w$-levels and $k = 1$ to $k = 1$ for $T-$levels.
+Such an expression allows us to define a nearly uniform vertical location of levels at the ocean top and bottom with
+a smooth hyperbolic tangent transition in between (\autoref{fig:zgr}).
+If the ice shelf cavities are opened (\np{ln\_isfcav}~\forcode{= .true.}), the definition of $z_0$ is the same.
+However, definition of $e_3^0$ at $t$- and $w$-points is respectively changed to:
+\begin{equation}
+  \label{eq:DOM_zgr_ana_2}
+  \begin{split}
+    e_3^T(k) &= z_W (k + 1) - z_W (k    ) \\
+    e_3^W(k) &= z_T (k    ) - z_T (k - 1)
+  \end{split}
+\end{equation}
+This formulation decrease the self-generated circulation into the ice shelf cavity
+(which can, in extreme case, leads to blow up).\\
+The most used vertical grid for ORCA2 has $10~m$ ($500~m$) resolution in the surface (bottom) layers and
+a depth which varies from 0 at the sea surface to a minimum of $-5000~m$.
+This leads to the following conditions:
+\begin{equation}
+  \label{eq:DOM_zgr_coef}
+  \begin{array}{ll}
+    e_3 (1   + 1/2) =  10. & z(1  ) =     0. \\
+    e_3 (jpk - 1/2) = 500. & z(jpk) = -5000.
+  \end{array}
+\end{equation}
+With the choice of the stretching $h_{cr} = 3$ and the number of levels \jp{jpk}~$= 31$,
+the four coefficients $h_{sur}$, $h_0$, $h_1$, and $h_{th}$ in
+\autoref{eq:DOM_zgr_ana_2} have been determined such that
+\autoref{eq:DOM_zgr_coef} is satisfied, through an optimisation procedure using a bisection method.
+For the first standard ORCA2 vertical grid this led to the following values:
+$h_{sur} = 4762.96$, $h_0 = 255.58, h_1 = 245.5813$, and $h_{th} = 21.43336$.
+The resulting depths and scale factors as a function of the model levels are shown in
+\autoref{fig:zgr} and given in \autoref{tab:orca_zgr}.
+Those values correspond to the parameters \np{ppsur}, \np{ppa0}, \np{ppa1}, \np{ppkth} in \ngn{namcfg} 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}~$= 999999$.,
+in \ngn{namcfg} namelist, and specifies instead the four following parameters:
+\begin{itemize}
+\item
+  \np{ppacr}~$= h_{cr}$: stretching factor (nondimensional).
+  The larger \np{ppacr}, the smaller the stretching.
+  Values from $3$ to $10$ are usual.
+\item
+  \np{ppkth}~$= h_{th}$: is approximately the model level at which maximum stretching occurs
+  (nondimensional, usually of order 1/2 or 2/3 of \jp{jpk})
+\item
+  \np{ppdzmin}: minimum thickness for the top layer (in meters).
+\item
+  \np{pphmax}: total depth of the ocean (meters).
+\end{itemize}
+As an example, for the $45$ layers used in the DRAKKAR configuration those parameters are:
+\jp{jpk}~$= 46$, \np{ppacr}~$= 9$, \np{ppkth}~$= 23.563$, \np{ppdzmin}~$= 6~m$, \np{pphmax}~$= 5750~m$.
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{table}
+  \begin{center}
+    \begin{tabular}{c||r|r|r|r}
+      \hline
+      \textbf{LEVEL} & \textbf{gdept\_1d} & \textbf{gdepw\_1d} & \textbf{e3t\_1d } & \textbf{e3w\_1d} \\
+      \hline
+              & \textbf{     5.00} &               0.00 & \textbf{   10.00} &            10.00 \\
+      \hline
+              & \textbf{    15.00} &              10.00 & \textbf{   10.00} &            10.00 \\
+      \hline
+              & \textbf{    25.00} &              20.00 & \textbf{   10.00} &            10.00 \\
+      \hline
+              & \textbf{    35.01} &              30.00 & \textbf{   10.01} &            10.00 \\
+      \hline
+              & \textbf{    45.01} &              40.01 & \textbf{   10.01} &            10.01 \\
+      \hline
+              & \textbf{    55.03} &              50.02 & \textbf{   10.02} &            10.02 \\
+      \hline
+              & \textbf{    65.06} &              60.04 & \textbf{   10.04} &            10.03 \\
+      \hline
+              & \textbf{    75.13} &              70.09 & \textbf{   10.09} &            10.06 \\
+      \hline
+              & \textbf{    85.25} &              80.18 & \textbf{   10.17} &            10.12 \\
+      \hline
+             & \textbf{    95.49} &              90.35 & \textbf{   10.33} &            10.24 \\
+      \hline
+             & \textbf{   105.97} &             100.69 & \textbf{   10.65} &            10.47 \\
+      \hline
+             & \textbf{   116.90} &             111.36 & \textbf{   11.27} &            10.91 \\
+      \hline
+             & \textbf{   128.70} &             122.65 & \textbf{   12.47} &            11.77 \\
+      \hline
+             & \textbf{   142.20} &             135.16 & \textbf{   14.78} &            13.43 \\
+      \hline
+             & \textbf{   158.96} &             150.03 & \textbf{   19.23} &            16.65 \\
+      \hline
+             & \textbf{   181.96} &             169.42 & \textbf{   27.66} &            22.78 \\
+      \hline
+             & \textbf{   216.65} &             197.37 & \textbf{   43.26} &            34.30 \\
+      \hline
+             & \textbf{   272.48} &             241.13 & \textbf{   70.88} &            55.21 \\
+      \hline
+             & \textbf{   364.30} &             312.74 & \textbf{  116.11} &            90.99 \\
+      \hline
+             & \textbf{   511.53} &             429.72 & \textbf{  181.55} &           146.43 \\
+      \hline
+             & \textbf{   732.20} &             611.89 & \textbf{  261.03} &           220.35 \\
+      \hline
+             & \textbf{  1033.22} &             872.87 & \textbf{  339.39} &           301.42 \\
+      \hline
+             & \textbf{  1405.70} &            1211.59 & \textbf{  402.26} &           373.31 \\
+      \hline
+             & \textbf{  1830.89} &            1612.98 & \textbf{  444.87} &           426.00 \\
+      \hline
+             & \textbf{  2289.77} &            2057.13 & \textbf{  470.55} &           459.47 \\
+      \hline
+             & \textbf{  2768.24} &            2527.22 & \textbf{  484.95} &           478.83 \\
+      \hline
+             & \textbf{  3257.48} &            3011.90 & \textbf{  492.70} &           489.44 \\
+      \hline
+             & \textbf{  3752.44} &            3504.46 & \textbf{  496.78} &           495.07 \\
+      \hline
+             & \textbf{  4250.40} &            4001.16 & \textbf{  498.90} &           498.02 \\
+      \hline
+             & \textbf{  4749.91} &            4500.02 & \textbf{  500.00} &           499.54 \\
+      \hline
+             & \textbf{  5250.23} &            5000.00 & \textbf{  500.56} &           500.33 \\
+      \hline
+    \end{tabular}
+  \end{center}
+  \caption{
+    \protect\label{tab:orca_zgr}
+    Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration as computed from
+    \autoref{eq:DOM_zgr_ana_2} using the coefficients given in \autoref{eq:DOM_zgr_coef}
+  }
+\end{table}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+% -------------------------------------------------------------------------------------------------------------
+%        z-coordinate with partial step
+% -------------------------------------------------------------------------------------------------------------
+\subsection{$Z$-coordinate with partial step (\protect\np{ln\_zps}~\forcode{= .true.})}
+\label{subsec:DOM_zps}
+%--------------------------------------------namdom-------------------------------------------------------
+\nlst{namdom}
+%--------------------------------------------------------------------------------------------------------------
+In $z$-coordinate partial step,
+the depths of the model levels are defined by the reference analytical function $z_0(k)$ as described in
+the previous section, \textit{except} in the bottom layer.
+The thickness of the bottom layer is allowed to vary as a function of geographical location $(\lambda,\varphi)$ to
+allow a better representation of the bathymetry, especially in the case of small slopes
+(where the bathymetry varies by less than one level thickness from one grid point to the next).
+The reference layer thicknesses $e_{3t}^0$ have been defined in the absence of bathymetry.
+With partial steps, layers from 1 to \jp{jpk}-2 can have a thickness smaller than $e_{3t}(jk)$.
+The model deepest layer (\jp{jpk}-1) is allowed to have either a smaller or larger 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,
+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 depth allowed is actually $6000~m$ (the default thickness $e_{3t}(jpk - 1)$ being $250~m$).
+Two variables in the namdom namelist are used to define the partial step vertical grid.
+The mimimum water thickness (in meters) allowed for a cell partially filled with bathymetry at level jk is
+the minimum of \np{rn\_e3zps\_min} (thickness in meters, usually $20~m$) or $e_{3t}(jk)*$\np{rn\_e3zps\_rat}
+(a fraction, usually 10\%, of the default thickness $e_{3t}(jk)$).
+\gmcomment{ \colorbox{yellow}{Add a figure here of pstep especially at last ocean level }  }
+% -------------------------------------------------------------------------------------------------------------
+%        s-coordinate
+% -------------------------------------------------------------------------------------------------------------
+\subsection{$S$-coordinate (\protect\np{ln\_sco}~\forcode{= .true.})}
+\label{subsec:DOM_sco}
+%------------------------------------------nam_zgr_sco---------------------------------------------------
+%
+%\nlst{namzgr_sco}
+%--------------------------------------------------------------------------------------------------------------
+Options are defined in \ngn{namzgr\_sco}.
+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:
+\begin{align*}
+  % \label{eq:DOM_sco_ana}
+  z(k)   &= h(i,j) \; z_0 (k) \\
+  e_3(k) &= h(i,j) \; z_0'(k)
+\end{align*}
+where $h$ is the depth of the last $w$-level ($z_0(k)$) defined at the $t$-point location in the horizontal and
+$z_0(k)$ is a function which varies from $0$ at the sea surface to $1$ at the ocean bottom.
+The depth field $h$ is not necessary the ocean depth,
+since a mixed step-like and bottom-following representation of the topography can be used
+(\autoref{fig:z_zps_s_sps}) or an envelop bathymetry can be defined (\autoref{fig:z_zps_s_sps}).
+The namelist parameter \np{rn\_rmax} determines the slope at which
+the terrain-following coordinate intersects the sea bed and becomes a pseudo z-coordinate.
+The coordinate can also be hybridised by specifying \np{rn\_sbot\_min} and \np{rn\_sbot\_max} as
+the minimum and maximum depths at which the terrain-following vertical coordinate is calculated.
+Options for stretching the coordinate are provided as examples,
+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
+(\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_al_JPO96}:
+\[
+  z = s_{min} + C (s) (H - s_{min})
+  % \label{eq:SH94_1}
+\]
+where $s_{min}$ is the depth at which the $s$-coordinate stretching starts and
+allows a $z$-coordinate to placed on top of the stretched coordinate,
+and $z$ is the depth (negative down from the asea surface).
+\begin{gather*}
+  s = - \frac{k}{n - 1} \quad \text{and} \quad 0 \leq k \leq n - 1
+  % \label{eq:DOM_s}
+ \\
+  % \label{eq:DOM_sco_function}
+  C(s) = \frac{[\tanh(\theta \, (s + b)) - \tanh(\theta \, b)]}{2 \; \sinh(\theta)}
+\end{gather*}
+A stretching function,
+modified from the commonly used \citet{Song_Haidvogel_JCP94} stretching (\np{ln\_s\_SH94}~\forcode{= .true.}),
+is also available and is more commonly used for shelf seas modelling:
+\[
+  C(s) =   (1 - b) \frac{\sinh(\theta s)}{\sinh(\theta)}
+         + b       \frac{\tanh \lt[ \theta \lt(s + \frac{1}{2} \rt) \rt] -   \tanh \lt( \frac{\theta}{2} \rt)}
+                        {                                                  2 \tanh \lt( \frac{\theta}{2} \rt)}
+  % \label{eq:SH94_2}
+\]
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht]
+  \begin{center}
+    \includegraphics[]{Fig_sco_function}
+    \caption{
+      \protect\label{fig:sco_function}
+      Examples of the stretching function applied to a seamount;
+      from left to right: surface, surface and bottom, and bottom intensified resolutions
+    }
+  \end{center}
+\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+where $H_c$ is the critical depth (\np{rn\_hc}) at which the coordinate transitions from pure $\sigma$ to
+the stretched coordinate, and $\theta$ (\np{rn\_theta}) and $b$ (\np{rn\_bb}) are the surface and
+bottom control parameters such that $0 \leqslant \theta \leqslant 20$, and $0 \leqslant b \leqslant 1$.
+$b$ has been designed to allow surface and/or bottom increase of the vertical resolution
+(\autoref{fig:sco_function}).
+Another example has been provided at version 3.5 (\np{ln\_s\_SF12}) that allows a fixed surface resolution in
+an analytical terrain-following stretching \citet{Siddorn_Furner_OM12}.
+In this case the a stretching function $\gamma$ is defined such that:
+\begin{equation}
+  z = - \gamma h \quad \text{with} \quad 0 \leq \gamma \leq 1
+  % \label{eq:z}
+\end{equation}
+The function is defined with respect to $\sigma$, the unstretched terrain-following coordinate:
+\begin{gather*}
+  % \label{eq:DOM_gamma_deriv}
+  \gamma =   A \lt( \sigma   - \frac{1}{2} (\sigma^2     + f (\sigma)) \rt)
+           + B \lt( \sigma^3 - f           (\sigma) \rt) + f (\sigma)       \\
+  \intertext{Where:}
+  % \label{eq:DOM_gamma}
+  f(\sigma) = (\alpha + 2) \sigma^{\alpha + 1} - (\alpha + 1) \sigma^{\alpha + 2}
+  \quad \text{and} \quad \sigma = \frac{k}{n - 1}
+\end{gather*}
+This gives an analytical stretching of $\sigma$ that is solvable in $A$ and $B$ as a function of
+the user prescribed stretching parameter $\alpha$ (\np{rn\_alpha}) that stretches towards
+the surface ($\alpha > 1.0$) or the bottom ($\alpha < 1.0$) and
+user prescribed surface (\np{rn\_zs}) and bottom depths.
+The bottom cell depth in this example is given as a function of water depth:
+\[
+  % \label{eq:DOM_zb}
+  Z_b = h a + b
+\]
+where the namelist parameters \np{rn\_zb\_a} and \np{rn\_zb\_b} are $a$ and $b$ respectively.
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht]
+  \includegraphics[]{Fig_DOM_compare_coordinates_surface}
+  \caption{
+    A comparison of the \citet{Song_Haidvogel_JCP94} $S$-coordinate (solid lines),
+    a 50 level $Z$-coordinate (contoured surfaces) and
+    the \citet{Siddorn_Furner_OM12} $S$-coordinate (dashed lines) in the surface $100~m$ for
+    a idealised bathymetry that goes from $50~m$ to $5500~m$ depth.
+    For clarity every third coordinate surface is shown.
+  }
+  \label{fig:fig_compare_coordinates_surface}
+\end{figure}
+ % >>>>>>>>>>>>>>>>>>>>>>>>>>>>
+This gives a smooth analytical stretching in computational space that is constrained to
+given specified surface and bottom grid cell thicknesses in real space.
+This is not to be confused with the hybrid schemes that
+superimpose geopotential coordinates on terrain following coordinates thus
+creating a non-analytical vertical coordinate that
+therefore may suffer from large gradients in the vertical resolutions.
+This stretching is less straightforward to implement than the \citet{Song_Haidvogel_JCP94} stretching,
+but has the advantage of resolving diurnal processes in deep water and has generally flatter slopes.
+As with the \citet{Song_Haidvogel_JCP94} stretching the stretch is only applied at depths greater than
+the critical depth $h_c$.
+In this example two options are available in depths shallower than $h_c$,
+with pure sigma being applied if the \np{ln\_sigcrit} is true and pure z-coordinates if it is false
+(the z-coordinate being equal to the depths of the stretched coordinate at $h_c$).
+Minimising the horizontal slope of the vertical coordinate is important in terrain-following systems as
+large slopes lead to hydrostatic consistency.
+A hydrostatic consistency parameter diagnostic following \citet{Haney1991} has been implemented,
+and is output as part of the model mesh file at the start of the run.
+% -------------------------------------------------------------------------------------------------------------
+%        z*- or s*-coordinate
+% -------------------------------------------------------------------------------------------------------------
+\subsection{\zstar- or \sstar-coordinate (\protect\np{ln\_linssh}~\forcode{= .false.})}
+\label{subsec:DOM_zgr_star}
+This option is described in the Report by Levier \textit{et al.} (2007), available on the \NEMO web site.
+%gm% key advantage: minimise the diffusion/dispertion associated with advection in response to high frequency surface disturbances
+% -------------------------------------------------------------------------------------------------------------
+%        level bathymetry and mask
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Level bathymetry and mask}
+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{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                                 */
+double e3t_1d, e3w_1d                    /* reference vertical scale factors at T and W points           */
+double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0 /* vertical scale factors 3D coordinate at T,U,V,F and W points */
+double e3uw_0, e3vw_0                    /* vertical scale factors 3D coordinate at UW and VW points     */
+int    bottom_level, top_level           /* last wet T-points, 1st wet T-points (for ice shelf cavities) */
+                                         /* For reference:                                               */
+float  bathy_metry                       /* bathymetry used in setting top and bottom levels             */
+\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}
 \label{subsec:DOM_msk}
+Whatever the vertical coordinate used, the model offers the possibility of representing the bottom topography with
+steps that follow the face of the model cells (step like topography) \citep{Madec_al_JPO96}.
+The distribution of the steps in the horizontal is defined in a 2D integer array, mbathy, which
+gives the number of ocean levels (\ie those that are not masked) at each $t$-point.
+mbathy is computed from the meter bathymetry using the definiton of gdept as the number of $t$-points which
+gdept $\leq$ bathy.
+Modifications of the model bathymetry are performed in the \textit{bat\_ctl} routine (see \mdl{domzgr} module) after
+mbathy is computed.
+Isolated grid points that do not communicate with another ocean point at the same level are eliminated.
+As for the representation of bathymetry, a 2D integer array, misfdep, is created.
+misfdep defines the level of the first wet $t$-point.
+All the cells between $k = 1$ and $misfdep(i,j) - 1$ are masked.
+By default, $misfdep(:,:) = 1$ and no cells are masked.
+In case of ice shelf cavities, modifications of the model bathymetry and ice shelf draft into
+the cavities are performed in the \textit{zgr\_isf} routine.
+The compatibility between ice shelf draft and bathymetry is checked.
+All the locations where the isf cavity is thinnest than \np{rn\_isfhmin} meters are grounded (\ie masked).
+If only one cell on the water column is opened at $t$-, $u$- or $v$-points,
+the bathymetry or the ice shelf draft is dug to fit this constrain.
+If the incompatibility is too strong (need to dig more than 1 cell), the cell is masked.
+From the \textit{mbathy} and \textit{misfdep} array, 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) &= &  &
     \begin{cases}
 &\text{if $                  k  <    misfdep(i,j)$} \\
 &\text{if $misfdep(i,j) \leq k \leq   mbathy(i,j)$} \\
 &\text{if $                  k  >     mbathy(i,j)$}
+&\text{if $                  k  <    top\_level(i,j)$} \\
+&\text{if $bottom\_level(i,j) \leq k \leq   top\_level(i,j)$} \\
+&\text{if $                  k  >     bottom\_level(i,j)$}
     \end{cases}
   \\
 …
 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.
+The specification of closed lateral boundaries requires that at least
+the first and last rows and columns of the \textit{mbathy} array are set to zero.
+In the particular case of an east-west cyclical boundary condition, \textit{mbathy} has its last column equal to
+the second one and its first column equal to the last but one (and so too the mask arrays)
+(see \autoref{fig:LBC_jperio}).
+%% The specification of closed lateral boundaries requires that at least
+%% the first and last rows and columns of the \textit{mbathy} array are set to zero.
+%% In the particular case of an east-west cyclical boundary condition, \textit{mbathy} has its last column equal to
+%% the second one and its first column equal to the last but one (and so too the mask arrays)
+%% (see \autoref{fig:LBC_jperio}).
+%-------------------------------------------------------------------------------------------------
+%        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 \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{clines}
+% -------------------------------------------------------------------------------------------------------------
+%        Grid files
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Output grid files}
+\label{subsec:DOM_meshmask}
+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 \nam{dom}) is set to \forcode{.true.}.
+This file contains additional fields that can be useful for post-processing applications.
 % ================================================================
 % Domain: Initial State (dtatsd & istate)
 % ================================================================
+\section{Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})}
+\label{sec:DTA_tsd}
+\section[Initial state (\textit{istate.F90} and \textit{dtatsd.F90})]
+{Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})}
+\label{sec:DOM_DTA_tsd}
 %-----------------------------------------namtsd-------------------------------------------
+\nlst{namtsd}
+\begin{listing}
+  \nlst{namtsd}
+  \caption{\texttt{namtsd}}
+  \label{lst:namtsd}
+\end{listing}
 %------------------------------------------------------------------------------------------
+Options are defined in \ngn{namtsd}.
+By default, the ocean start from rest (the velocity field is set to zero) and the initialization of temperature and
+salinity fields is controlled through the \np{ln\_tsd\_ini} 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 a T and S input files that can be given on the model grid itself or on their native input data grid.
+  In the latter case,
+  the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid
+\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 relative to the input files are given in the \np{sn\_tem} and \np{sn\_sal} structures.
+  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.}]
+  use constant salinity value of $35.5~psu$ and an analytical profile of temperature
+  (typical of the tropical ocean), see \rou{istate\_t\_s} subroutine called from \mdl{istate} 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:CFGS_gyre}).
 \end{description}

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_DYN.tex

-                      r10499
+                      r11564
 \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"?}
 …
 %           Horizontal divergence and relative vorticity
 %--------------------------------------------------------------------------------------------------------------
 \subsection{Horizontal divergence and relative vorticity (\protect\mdl{divcur})}
+\subsection[Horizontal divergence and relative vorticity (\textit{divcur.F90})]{Horizontal divergence and relative vorticity (\protect\mdl{divcur})}
 \label{subsec:DYN_divcur}
 The vorticity is defined at an $f$-point (\ie corner point) as follows:
 \begin{equation}
   \label{eq:divcur_cur}
+The vorticity is defined at an $f$-point (\ie\ corner point) as follows:
+\begin{equation}
+  \label{eq:DYN_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.
 It is given by:
 \[
   % \label{eq:divcur_div}
+  % \label{eq:DYN_divcur_div}
   \chi =\frac{1}{e_{1t}\,e_{2t}\,e_{3t} }
   \left( {\delta_i \left[ {e_{2u}\,e_{3u}\,u} \right]
 …
 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.
 %--------------------------------------------------------------------------------------------------------------
 %           Sea Surface Height evolution
 %--------------------------------------------------------------------------------------------------------------
 \subsection{Horizontal divergence and relative vorticity (\protect\mdl{sshwzv})}
+\subsection[Horizontal divergence and relative vorticity (\textit{sshwzv.F90})]{Horizontal divergence and relative vorticity (\protect\mdl{sshwzv})}
 \label{subsec:DYN_sshwzv}
 The sea surface height is given by:
 \begin{equation}
   \label{eq:dynspg_ssh}
+  \label{eq:DYN_spg_ssh}
   \begin{aligned}
     \frac{\partial \eta }{\partial t}
 …
   \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}:
+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:DYN_spg_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
 the sea surface height equation otherwise tracer content will not be conserved
 \citep{Griffies_al_MWR01, Leclair_Madec_OM09}.
+\citep{griffies.pacanowski.ea_MWR01, leclair.madec_OM09}.
 The vertical velocity is computed by an upward integration of the horizontal divergence starting at the bottom,
 taking into account the change of the thickness of the levels:
 \begin{equation}
   \label{eq:wzv}
+  \label{eq:DYN_wzv}
   \left\{
     \begin{aligned}
 …
 \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.
 \gmcomment{not sure of this...  to be modified with the change in emp setting}
 In the case of a linear free surface, the time derivative in \autoref{eq:wzv} disappears.
+In the case of a linear free surface, the time derivative in \autoref{eq:DYN_wzv} disappears.
 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:DYN_spg_ssh}).
 Note also that whereas the vertical velocity has the same discrete expression in $z$- and $s$-coordinates,
 its physical meaning is not the same:
 in the second case, $w$ is the velocity normal to the $s$-surfaces.
 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}).
+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:DYN_wzv}
+(see \autoref{subsec:DOM_Num_Index_vertical}).
 …
 %-----------------------------------------nam_dynadv----------------------------------------------------
+\nlst{namdyn_adv}
+\begin{listing}
+  \nlst{namdyn_adv}
+  \caption{\texttt{namdyn\_adv}}
+  \label{lst:namdyn_adv}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 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 (\protect\mdl{dynvor})}
+\subsection[Vorticity term (\textit{dynvor.F90})]{Vorticity term (\protect\mdl{dynvor})}
 \label{subsec:DYN_vor}
 %------------------------------------------nam_dynvor----------------------------------------------------
+\nlst{namdyn_vor}
+\begin{listing}
+  \nlst{namdyn_vor}
+  \caption{\texttt{namdyn\_vor}}
+  \label{lst:namdyn_vor}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 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);
 …
 horizontal kinetic energy for the planetary vorticity term (MIX scheme);
 or conserving both the potential enstrophy of horizontally non-divergent flow and horizontal kinetic energy
 (EEN scheme) (see \autoref{subsec:C_vorEEN}).
+(EEN scheme) (see \autoref{subsec:INVARIANTS_vorEEN}).
 In the case of ENS, ENE or MIX schemes the land sea mask may be slightly modified to ensure the consistency of
 vorticity term with analytical equations (\np{ln\_dynvor\_con}\forcode{ = .true.}).
+vorticity term with analytical equations (\np{ln\_dynvor\_con}\forcode{=.true.}).
 The vorticity terms are all computed in dedicated routines that can be found in the \mdl{dynvor} module.
 …
 %                 enstrophy conserving scheme
 %-------------------------------------------------------------
 \subsubsection{Enstrophy conserving scheme (\protect\np{ln\_dynvor\_ens}\forcode{ = .true.})}
+\subsubsection[Enstrophy conserving scheme (\forcode{ln_dynvor_ens = .true.})]{Enstrophy conserving scheme (\protect\np{ln\_dynvor\_ens}\forcode{ = .true.})}
 \label{subsec:DYN_vor_ens}
 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:
 \begin{equation}
   \label{eq:dynvor_ens}
+  \label{eq:DYN_vor_ens}
   \left\{
     \begin{aligned}
 …
     \end{aligned}
   \right.
 \end{equation}
+\end{equation}
 %-------------------------------------------------------------
 %                 energy conserving scheme
 %-------------------------------------------------------------
 \subsubsection{Energy conserving scheme (\protect\np{ln\_dynvor\_ene}\forcode{ = .true.})}
+\subsubsection[Energy conserving scheme (\forcode{ln_dynvor_ene = .true.})]{Energy conserving scheme (\protect\np{ln\_dynvor\_ene}\forcode{ = .true.})}
 \label{subsec:DYN_vor_ene}
 …
 It is given by:
 \begin{equation}
   \label{eq:dynvor_ene}
+  \label{eq:DYN_vor_ene}
   \left\{
     \begin{aligned}
 …
     \end{aligned}
   \right.
 \end{equation}
+\end{equation}
 %-------------------------------------------------------------
 %                 mix energy/enstrophy conserving scheme
 %-------------------------------------------------------------
 \subsubsection{Mixed energy/enstrophy conserving scheme (\protect\np{ln\_dynvor\_mix}\forcode{ = .true.}) }
+\subsubsection[Mixed energy/enstrophy conserving scheme (\forcode{ln_dynvor_mix = .true.})]{Mixed energy/enstrophy conserving scheme (\protect\np{ln\_dynvor\_mix}\forcode{ = .true.})}
 \label{subsec:DYN_vor_mix}
 For the mixed energy/enstrophy conserving scheme (MIX scheme), a mixture of the two previous schemes is used.
 It consists of the ENS scheme (\autoref{eq:dynvor_ens}) for the relative vorticity term,
 and of the ENE scheme (\autoref{eq:dynvor_ene}) applied to the planetary vorticity term.
 \[
   % \label{eq:dynvor_mix}
+It consists of the ENS scheme (\autoref{eq:DYN_vor_ens}) for the relative vorticity term,
+and of the ENE scheme (\autoref{eq:DYN_vor_ene}) applied to the planetary vorticity term.
+\[
+  % \label{eq:DYN_vor_mix}
   \left\{ {
       \begin{aligned}
 …
 %                 energy and enstrophy conserving scheme
 %-------------------------------------------------------------
 \subsubsection{Energy and enstrophy conserving scheme (\protect\np{ln\_dynvor\_een}\forcode{ = .true.}) }
+\subsubsection[Energy and enstrophy conserving scheme (\forcode{ln_dynvor_een = .true.})]{Energy and enstrophy conserving scheme (\protect\np{ln\_dynvor\_een}\forcode{ = .true.})}
 \label{subsec:DYN_vor_een}
 …
 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....}
 A very nice solution to the problem of double averaging was proposed by \citet{Arakawa_Hsu_MWR90}.
+A very nice solution to the problem of double averaging was proposed by \citet{arakawa.hsu_MWR90}.
 The idea is to get rid of the double averaging by considering triad combinations of vorticity.
 It is noteworthy that this solution is conceptually quite similar to the one proposed by
 \citep{Griffies_al_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:
 \[
   % \label{eq:pot_vor}
+\citep{griffies.gnanadesikan.ea_JPO98} for the discretization of the iso-neutral diffusion operator (see \autoref{apdx:INVARIANTS}).
+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:DYN_pot_vor}
   q  = \frac{\zeta +f} {e_{3f} }
 \]
 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:
 \begin{equation}
   \label{eq:een_e3f}
+where the relative vorticity is defined by (\autoref{eq:DYN_divcur_cur}),
+the Coriolis parameter is given by $f=2 \,\Omega \;\sin \varphi _f $ and the layer thickness at $f$-points is:
+\begin{equation}
+  \label{eq:DYN_een_e3f}
   e_{3f} = \overline{\overline {e_{3t} }} ^{\,i+1/2,j+1/2}
 \end{equation}
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!ht]
+  \begin{center}
+    \includegraphics[width=0.70\textwidth]{Fig_DYN_een_triad}
+    \caption{
+      \protect\label{fig:DYN_een_triad}
+      Triads used in the energy and enstrophy conserving scheme (een) for
+      $u$-component (upper panel) and $v$-component (lower panel).
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_DYN_een_triad}
+  \caption[Triads used in the energy and enstrophy conserving scheme (EEN)]{
+    Triads used in the energy and enstrophy conserving scheme (EEN) for
+    $u$-component (upper panel) and $v$-component (lower panel).}
+  \label{fig:DYN_een_triad}
 \end{figure}
 % >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 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:DYN_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.}).
+(\np{nn\_een\_e3f}\forcode{=1}), or just by $4$ (\np{nn\_een\_e3f}\forcode{=.true.}).
 The latter case preserves the continuity of $e_{3f}$ when one or more of the neighbouring $e_{3t}$ tends to zero and
 extends by continuity the value of $e_{3f}$ into the land areas.
 …
 (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_al_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}):
 \begin{equation}
   \label{eq:Q_triads}
+(\autoref{fig:DYN_een_triad}):
+\begin{equation}
+  \label{eq:DYN_Q_triads}
   _i^j \mathbb{Q}^{i_p}_{j_p}
   = \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:
 \begin{equation}
   \label{eq:dynvor_een}
+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:DYN_vor_een}
   \left\{ {
       \begin{aligned}
 …
       \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:INVARIANTS_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_al_OM09}.
+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_al_OD06, Penduff_al_OS07}.
+leading to a larger topostrophy of the flow \citep{barnier.madec.ea_OD06, penduff.le-sommer.ea_OS07}.
 %--------------------------------------------------------------------------------------------------------------
 %           Kinetic Energy Gradient term
 %--------------------------------------------------------------------------------------------------------------
 \subsection{Kinetic energy gradient term (\protect\mdl{dynkeg})}
+\subsection[Kinetic energy gradient term (\textit{dynkeg.F90})]{Kinetic energy gradient term (\protect\mdl{dynkeg})}
 \label{subsec:DYN_keg}
 As demonstrated in \autoref{apdx:C},
+As demonstrated in \autoref{apdx:INVARIANTS},
 there is a single discrete formulation of the kinetic energy gradient term that,
 together with the formulation chosen for the vertical advection (see below),
 conserves the total kinetic energy:
 \[
   % \label{eq:dynkeg}
+  % \label{eq:DYN_keg}
   \left\{
     \begin{aligned}
 …
 %           Vertical advection term
 %--------------------------------------------------------------------------------------------------------------
 \subsection{Vertical advection term (\protect\mdl{dynzad}) }
+\subsection[Vertical advection term (\textit{dynzad.F90})]{Vertical advection term (\protect\mdl{dynzad})}
 \label{subsec:DYN_zad}
 …
 conserves the total kinetic energy.
 Indeed, the change of KE due to the vertical advection is exactly balanced by
 the change of KE due to the gradient of KE (see \autoref{apdx:C}).
 \[
   % \label{eq:dynzad}
+the change of KE due to the gradient of KE (see \autoref{apdx:INVARIANTS}).
+\[
+  % \label{eq:DYN_zad}
   \left\{
     \begin{aligned}
 …
   \right.
 \]
 When \np{ln\_dynzad\_zts}\forcode{ = .true.},
+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_OM2015}.
+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}
 %-------------------------------------------------------------------------------------------------------------
 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}.
 …
 %           Coriolis plus curvature metric terms
 %--------------------------------------------------------------------------------------------------------------
 \subsection{Coriolis plus curvature metric terms (\protect\mdl{dynvor}) }
+\subsection[Coriolis plus curvature metric terms (\textit{dynvor.F90})]{Coriolis plus curvature metric terms (\protect\mdl{dynvor})}
 \label{subsec:DYN_cor_flux}
 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}
+  % \label{eq:DYN_cor_metric}
   f+\frac{1}{e_1 e_2 }\left( {v\frac{\partial e_2 }{\partial i}  -  u\frac{\partial e_1 }{\partial j}} \right)  \\
   \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*}
 Any of the (\autoref{eq:dynvor_ens}), (\autoref{eq:dynvor_ene}) and (\autoref{eq:dynvor_een}) schemes can be used to
+\end{multline*}
+Any of the (\autoref{eq:DYN_vor_ens}), (\autoref{eq:DYN_vor_ene}) and (\autoref{eq:DYN_vor_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).
+However, the energy-conserving scheme (\autoref{eq:DYN_vor_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).
 %--------------------------------------------------------------------------------------------------------------
 %           Flux form Advection term
 %--------------------------------------------------------------------------------------------------------------
 \subsection{Flux form advection term (\protect\mdl{dynadv}) }
+\subsection[Flux form advection term (\textit{dynadv.F90})]{Flux form advection term (\protect\mdl{dynadv})}
 \label{subsec:DYN_adv_flux}
 The discrete expression of the advection term is given by:
 \[
   % \label{eq:dynadv}
+  % \label{eq:DYN_adv}
   \left\{
     \begin{aligned}
 …
 a $2^{nd}$ order centered finite difference scheme, CEN2,
 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 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}.
 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$.
 %-------------------------------------------------------------
 %                 2nd order centred scheme
 %-------------------------------------------------------------
 \subsubsection{CEN2: $2^{nd}$ order centred scheme (\protect\np{ln\_dynadv\_cen2}\forcode{ = .true.})}
+\subsubsection[CEN2: $2^{nd}$ order centred scheme (\forcode{ln_dynadv_cen2 = .true.})]{CEN2: $2^{nd}$ order centred scheme (\protect\np{ln\_dynadv\_cen2}\forcode{ = .true.})}
 \label{subsec:DYN_adv_cen2}
 In the centered $2^{nd}$ order formulation, the velocity is evaluated as the mean of the two neighbouring points:
 \begin{equation}
   \label{eq:dynadv_cen2}
+  \label{eq:DYN_adv_cen2}
   \left\{
     \begin{aligned}
 …
     \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.
 …
 %                 UBS scheme
 %-------------------------------------------------------------
 \subsubsection{UBS: Upstream Biased Scheme (\protect\np{ln\_dynadv\_ubs}\forcode{ = .true.})}
+\subsubsection[UBS: Upstream Biased Scheme (\forcode{ln_dynadv_ubs = .true.})]{UBS: Upstream Biased Scheme (\protect\np{ln\_dynadv\_ubs}\forcode{ = .true.})}
 \label{subsec:DYN_adv_ubs}
 …
 For example, the evaluation of $u_T^{ubs} $ is done as follows:
 \begin{equation}
   \label{eq:dynadv_ubs}
+  \label{eq:DYN_adv_ubs}
   u_T^{ubs} =\overline u ^i-\;\frac{1}{6}
   \begin{cases}
 …
 \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
 \citep{Shchepetkin_McWilliams_OM05}.
 The overall performance of the advection scheme is similar to that reported in \citet{Farrow1995}.
+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 a relatively good compromise between accuracy and smoothness.
 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
 $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
+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:DYN_adv_cen2} are used.
+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...  }
 For stability reasons, the first term in (\autoref{eq:dynadv_ubs}),
+For stability reasons, the first term in (\autoref{eq:DYN_adv_ubs}),
 which corresponds to a second order centred scheme, is evaluated using the \textit{now} velocity (centred in time),
 while the second term, which is the diffusion part of the scheme,
 is evaluated using the \textit{before} velocity (forward in time).
 This is discussed by \citet{Webb_al_JAOT98} in the context of the Quick advection scheme.
+This is discussed by \citet{webb.de-cuevas.ea_JAOT98} in the context of the Quick advection scheme.
 Note that the UBS and QUICK (Quadratic Upstream Interpolation for Convective Kinematics) schemes only differ by
 one coefficient.
 Replacing $1/6$ by $1/8$ in (\autoref{eq:dynadv_ubs}) leads to the QUICK advection scheme \citep{Webb_al_JAOT98}.
+Replacing $1/6$ by $1/8$ in (\autoref{eq:DYN_adv_ubs}) leads to the QUICK advection scheme \citep{webb.de-cuevas.ea_JAOT98}.
 This option is not available through a namelist parameter, since the $1/6$ coefficient is hard coded.
 Nevertheless it is quite easy to make the substitution in the \mdl{dynadv\_ubs} module and obtain a QUICK scheme.
 …
 %           Hydrostatic pressure gradient term
 % ================================================================
 \section{Hydrostatic pressure gradient (\protect\mdl{dynhpg})}
+\section[Hydrostatic pressure gradient (\textit{dynhpg.F90})]{Hydrostatic pressure gradient (\protect\mdl{dynhpg})}
 \label{sec:DYN_hpg}
 %------------------------------------------nam_dynhpg---------------------------------------------------
+\nlst{namdyn_hpg}
+\begin{listing}
+  \nlst{namdyn_hpg}
+  \caption{\texttt{namdyn\_hpg}}
+  \label{lst:namdyn_hpg}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 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.
 …
 %           z-coordinate with full step
 %--------------------------------------------------------------------------------------------------------------
 \subsection{Full step $Z$-coordinate (\protect\np{ln\_dynhpg\_zco}\forcode{ = .true.})}
+\subsection[Full step $Z$-coordinate (\forcode{ln_dynhpg_zco = .true.})]{Full step $Z$-coordinate (\protect\np{ln\_dynhpg\_zco}\forcode{ = .true.})}
 \label{subsec:DYN_hpg_zco}
 …
 for $k=km$ (surface layer, $jk=1$ in the code)
 \begin{equation}
   \label{eq:dynhpg_zco_surf}
+  \label{eq:DYN_hpg_zco_surf}
   \left\{
     \begin{aligned}
 …
     \end{aligned}
   \right.
 \end{equation}
+\end{equation}
 for $1<k<km$ (interior layer)
 \begin{equation}
   \label{eq:dynhpg_zco}
+  \label{eq:DYN_hpg_zco}
   \left\{
     \begin{aligned}
 …
     \end{aligned}
   \right.
 \end{equation}
 Note that the $1/2$ factor in (\autoref{eq:dynhpg_zco_surf}) is adequate because of the definition of $e_{3w}$ as
+\end{equation}
+Note that the $1/2$ factor in (\autoref{eq:DYN_hpg_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),
 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}$.
+Note also that in case of variable volume level (\texttt{vvl?} defined),
+the surface pressure gradient is included in \autoref{eq:DYN_hpg_zco_surf} and
+\autoref{eq:DYN_hpg_zco} through the space and time variations of the vertical scale factor $e_{3w}$.
 %--------------------------------------------------------------------------------------------------------------
 %           z-coordinate with partial step
 %--------------------------------------------------------------------------------------------------------------
 \subsection{Partial step $Z$-coordinate (\protect\np{ln\_dynhpg\_zps}\forcode{ = .true.})}
+\subsection[Partial step $Z$-coordinate (\forcode{ln_dynhpg_zps = .true.})]{Partial step $Z$-coordinate (\protect\np{ln\_dynhpg\_zps}\forcode{ = .true.})}
 \label{subsec:DYN_hpg_zps}
 …
 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{Song1998, 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.
 $\bullet$ Traditional coding (see for example \citet{Madec_al_JPO96}: (\np{ln\_dynhpg\_sco}\forcode{ = .true.})
 \begin{equation}
   \label{eq:dynhpg_sco}
+$\bullet$ Traditional coding (see for example \citet{madec.delecluse.ea_JPO96}: (\np{ln\_dynhpg\_sco}\forcode{=.true.})
+\begin{equation}
+  \label{eq:DYN_hpg_sco}
   \left\{
     \begin{aligned}
 …
     \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
+computed as in \autoref{eq:DYN_hpg_zco_surf} - \autoref{eq:DYN_hpg_zco},
+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}
 (\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,
 the coordinate surfaces are not horizontal but follow the free surface \citep{Levier2007}.
 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.
+$\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}
+(\np{ln\_dynhpg\_djc}\forcode{=.true.}) (currently disabled; under development)
+Note that expression \autoref{eq:DYN_hpg_sco} is commonly used when the variable volume formulation is activated
+(\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 \texttt{vvl?} is active.
 The pressure Jacobian scheme uses a constrained cubic spline to
 reconstruct the density profile across the water column.
 …
 \subsection{Ice shelf cavity}
 \label{subsec:DYN_hpg_isf}
 Beneath an ice shelf, the total pressure gradient is the sum of the pressure gradient due to the ice shelf load and
 the pressure gradient due to the ocean load (\np{ln\_dynhpg\_isf}\forcode{ = .true.}).\\
+the pressure gradient due to the ocean load (\np{ln\_dynhpg\_isf}\forcode{=.true.}).\\
 The main hypothesis to compute the ice shelf load is that the ice shelf is in an isostatic equilibrium.
 …
 corresponds to the water replaced by the ice shelf.
 This top pressure is constant over time.
 A detailed description of this method is described in \citet{Losch2008}.\\
 The pressure gradient due to ocean load is computed using the expression \autoref{eq:dynhpg_sco} described in
 \autoref{subsec:DYN_hpg_sco}.
+A detailed description of this method is described in \citet{losch_JGR08}.\\
+The pressure gradient due to ocean load is computed using the expression \autoref{eq:DYN_hpg_sco} described in
+\autoref{subsec:DYN_hpg_sco}.
 %--------------------------------------------------------------------------------------------------------------
 %           Time-scheme
 %--------------------------------------------------------------------------------------------------------------
 \subsection{Time-scheme (\protect\np{ln\_dynhpg\_imp}\forcode{ = .true./.false.})}
+\subsection[Time-scheme (\forcode{ln_dynhpg_imp = .{true,false}.})]{Time-scheme (\protect\np{ln\_dynhpg\_imp}\forcode{ = .\{true,false\}}.)}
 \label{subsec:DYN_hpg_imp}
 …
 the physical phenomenon that controls the time-step is internal gravity waves (IGWs).
 A semi-implicit scheme for doubling the stability limit associated with IGWs can be used
 \citep{Brown_Campana_MWR78, Maltrud1998}.
+\citep{brown.campana_MWR78, maltrud.smith.ea_JGR98}.
 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.
 $\bullet$ leapfrog scheme (\np{ln\_dynhpg\_imp}\forcode{ = .true.}):
 \begin{equation}
   \label{eq:dynhpg_lf}
+(\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.}):
+\begin{equation}
+  \label{eq:DYN_hpg_lf}
   \frac{u^{t+\rdt}-u^{t-\rdt}}{2\rdt} = \;\cdots \;
   -\frac{1}{\rho_o \,e_{1u} }\delta_{i+1/2} \left[ {p_h^t } \right]
 \end{equation}
 $\bullet$ semi-implicit scheme (\np{ln\_dynhpg\_imp}\forcode{ = .true.}):
 \begin{equation}
   \label{eq:dynhpg_imp}
+$\bullet$ semi-implicit scheme (\np{ln\_dynhpg\_imp}\forcode{=.true.}):
+\begin{equation}
+  \label{eq:DYN_hpg_imp}
   \frac{u^{t+\rdt}-u^{t-\rdt}}{2\rdt} = \;\cdots \;
   -\frac{1}{4\,\rho_o \,e_{1u} } \delta_{i+1/2} \left[ p_h^{t+\rdt} +2\,p_h^t +p_h^{t-\rdt}  \right]
 \end{equation}
 The semi-implicit time scheme \autoref{eq:dynhpg_imp} is made possible without
+The semi-implicit time scheme \autoref{eq:DYN_hpg_imp} is made possible without
 significant additional computation since the density can be updated to time level $t+\rdt$ before
 computing the horizontal hydrostatic pressure gradient.
 It can be easily shown that the stability limit associated with the hydrostatic pressure gradient doubles using
 \autoref{eq:dynhpg_imp} compared to that using the standard leapfrog scheme \autoref{eq:dynhpg_lf}.
 Note that \autoref{eq:dynhpg_imp} is equivalent to applying a time filter to the pressure gradient to
+\autoref{eq:DYN_hpg_imp} compared to that using the standard leapfrog scheme \autoref{eq:DYN_hpg_lf}.
+Note that \autoref{eq:DYN_hpg_imp} is equivalent to applying a time filter to the pressure gradient to
 eliminate high frequency IGWs.
 Obviously, when using \autoref{eq:dynhpg_imp},
+Obviously, when using \autoref{eq:DYN_hpg_imp},
 the doubling of the time-step is achievable only if no other factors control the time-step,
 such as the stability limits associated with advection or diffusion.
 In practice, the semi-implicit scheme is used when \np{ln\_dynhpg\_imp}\forcode{ = .true.}.
+In practice, the semi-implicit scheme is used when \np{ln\_dynhpg\_imp}\forcode{=.true.}.
 In this case, we choose to apply the time filter to temperature and salinity used in the equation of state,
 instead of applying it to the hydrostatic pressure or to the density,
 …
 The density used to compute the hydrostatic pressure gradient (whatever the formulation) is evaluated as follows:
 \[
   % \label{eq:rho_flt}
+  % \label{eq:DYN_rho_flt}
   \rho^t = \rho( \widetilde{T},\widetilde {S},z_t)
   \quad    \text{with}  \quad
 …
 % Surface Pressure Gradient
 % ================================================================
 \section{Surface pressure gradient (\protect\mdl{dynspg})}
+\section[Surface pressure gradient (\textit{dynspg.F90})]{Surface pressure gradient (\protect\mdl{dynspg})}
 \label{sec:DYN_spg}
 %-----------------------------------------nam_dynspg----------------------------------------------------
+\nlst{namdyn_spg}
+\begin{listing}
+  \nlst{namdyn_spg}
+  \caption{\texttt{namdyn\_spg}}
+  \label{lst:namdyn_spg}
+\end{listing}
 %------------------------------------------------------------------------------------------------------------
 Options are defined through the \ngn{namdyn\_spg} namelist variables.
 The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:PE_hor_pg}).
+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:MB_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).
 In the linear free surface case (\autoref{subsec:PE_free_surface})
+the variable volume case (nonlinear free surface, \texttt{vvl?} is defined).
+In the linear free surface case (\autoref{subsec:MB_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,
+while they are time-dependent in the nonlinear case (\autoref{subsec:MB_free_surface}).
+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:MB_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}.
 The form of the surface pressure gradient term depends on how the user wants to
 handle the fast external gravity waves that are a solution of the analytical equation (\autoref{sec:PE_hor_pg}).
+handle the fast external gravity waves that are a solution of the analytical equation (\autoref{sec:MB_hor_pg}).
 Three formulations are available, all controlled by a CPP key (ln\_dynspg\_xxx):
 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 (\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}
   \label{eq:dynspg_exp}
+  \label{eq:DYN_spg_exp}
   \left\{
     \begin{aligned}
 …
     \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 (\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),
 also called the time-splitting formulation, follows the one proposed by \citet{Shchepetkin_McWilliams_OM05}.
+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
 a smaller time step than $\rdt$, the time step used for the three dimensional prognostic variables
 (\autoref{fig:DYN_dynspg_ts}).
+(\autoref{fig:DYN_spg_ts}).
 The size of the small time step, $\rdt_e$ (the external mode or barotropic time step) is provided through
 the \np{nn\_baro} namelist parameter as: $\rdt_e = \rdt / nn\_baro$.
 This parameter can be optionally defined automatically (\np{ln\_bt\_nn\_auto}\forcode{ = .true.}) considering that
+This parameter can be optionally defined automatically (\np{ln\_bt\_nn\_auto}\forcode{=.true.}) considering that
 the stability of the barotropic system is essentially controled by external waves propagation.
 Maximum Courant number is in that case time independent, and easily computed online from the input bathymetry.
 …
 The barotropic mode solves the following equations:
 % \begin{subequations}
 %  \label{eq:BT}
 \begin{equation}
   \label{eq:BT_dyn}
   \frac{\partial {\rm \overline{{\bf U}}_h} }{\partial t}=
   -f\;{\rm {\bf k}}\times {\rm \overline{{\bf U}}_h}
   -g\nabla _h \eta -\frac{c_b^{\textbf U}}{H+\eta} \rm {\overline{{\bf U}}_h} + \rm {\overline{\bf G}}
 \end{equation}
 \[
   % \label{eq:BT_ssh}
   \frac{\partial \eta }{\partial t}=-\nabla \cdot \left[ {\left( {H+\eta } \right) \; {\rm{\bf \overline{U}}}_h \,} \right]+P-E
+%  \label{eq:DYN_BT}
+\begin{equation}
+  \label{eq:DYN_BT_dyn}
+  \frac{\partial {\mathrm \overline{{\mathbf U}}_h} }{\partial t}=
+  -f\;{\mathrm {\mathbf k}}\times {\mathrm \overline{{\mathbf U}}_h}
+  -g\nabla _h \eta -\frac{c_b^{\textbf U}}{H+\eta} \mathrm {\overline{{\mathbf U}}_h} + \mathrm {\overline{\mathbf G}}
+\end{equation}
+\[
+  % \label{eq:DYN_BT_ssh}
+  \frac{\partial \eta }{\partial t}=-\nabla \cdot \left[ {\left( {H+\eta } \right) \; {\mathrm{\mathbf \overline{U}}}_h \,} \right]+P-E
 \]
 % \end{subequations}
 where $\rm {\overline{\bf G}}$ is a forcing term held constant, containing coupling term between modes,
+where $\mathrm {\overline{\mathbf G}}$ is a forcing term held constant, containing coupling term between modes,
 surface atmospheric forcing as well as slowly varying barotropic terms not explicitly computed to gain efficiency.
 The third term on the right hand side of \autoref{eq:BT_dyn} represents the bottom stress
 (see section \autoref{sec:ZDF_bfr}), explicitly accounted for at each barotropic iteration.
+The third term on the right hand side of \autoref{eq:DYN_BT_dyn} represents the bottom stress
+(see section \autoref{sec:ZDF_drg}), explicitly accounted for at each barotropic iteration.
 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,
 "multi-purpose" stability compromise as defined in \citet{Shchepetkin_McWilliams_Bk08}
 (see their figure 12, lower left).
+detailed in \citet{shchepetkin.mcwilliams_OM05}.
+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).
 %>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=0.7\textwidth]{Fig_DYN_dynspg_ts}
+    \caption{
+      \protect\label{fig:DYN_dynspg_ts}
+      Schematic of the split-explicit time stepping scheme for the external and internal modes.
+      Time increases to the right. In this particular exemple,
+      a boxcar averaging window over $nn\_baro$ barotropic time steps is used ($nn\_bt\_flt=1$) and $nn\_baro=5$.
+      Internal mode time steps (which are also the model time steps) are denoted by $t-\rdt$, $t$ and $t+\rdt$.
+      Variables with $k$ superscript refer to instantaneous barotropic variables,
+      $< >$ and $<< >>$ operator refer to time filtered variables using respectively primary (red vertical bars) and
+      secondary weights (blue vertical bars).
+      The former are used to obtain time filtered quantities at $t+\rdt$ while
+      the latter are used to obtain time averaged transports to advect tracers.
+      a) Forward time integration: \protect\np{ln\_bt\_fw}\forcode{ = .true.},
+      \protect\np{ln\_bt\_av}\forcode{ = .true.}.
+      b) Centred time integration: \protect\np{ln\_bt\_fw}\forcode{ = .false.},
+      \protect\np{ln\_bt\_av}\forcode{ = .true.}.
+      c) Forward time integration with no time filtering (POM-like scheme):
+      \protect\np{ln\_bt\_fw}\forcode{ = .true.}, \protect\np{ln\_bt\_av}\forcode{ = .false.}.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_DYN_dynspg_ts}
+  \caption[Split-explicit time stepping scheme for the external and internal modes]{
+    Schematic of the split-explicit time stepping scheme for the external and internal modes.
+    Time increases to the right.
+    In this particular exemple,
+    a boxcar averaging window over \np{nn\_baro} barotropic time steps is used
+    (\np{nn\_bt\_flt}\forcode{=1}) and \np{nn\_baro}\forcode{=5}.
+    Internal mode time steps (which are also the model time steps) are denoted by
+    $t-\rdt$, $t$ and $t+\rdt$.
+    Variables with $k$ superscript refer to instantaneous barotropic variables,
+    $< >$ and $<< >>$ operator refer to time filtered variables using respectively primary
+    (red vertical bars) and secondary weights (blue vertical bars).
+    The former are used to obtain time filtered quantities at $t+\rdt$ while
+    the latter are used to obtain time averaged transports to advect tracers.
+    a) Forward time integration:
+    \protect\np{ln\_bt\_fw}\forcode{=.true.},  \protect\np{ln\_bt\_av}\forcode{=.true.}.
+    b) Centred time integration:
+    \protect\np{ln\_bt\_fw}\forcode{=.false.}, \protect\np{ln\_bt\_av}\forcode{=.true.}.
+    c) Forward time integration with no time filtering (POM-like scheme):
+    \protect\np{ln\_bt\_fw}\forcode{=.true.},  \protect\np{ln\_bt\_av}\forcode{=.false.}.}
+  \label{fig:DYN_spg_ts}
 \end{figure}
 %>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >
 In the default case (\np{ln\_bt\_fw}\forcode{ = .true.}),
+In the default case (\np{ln\_bt\_fw}\forcode{=.true.}),
 the external mode is integrated between \textit{now} and \textit{after} baroclinic time-steps
 (\autoref{fig:DYN_dynspg_ts}a).
+(\autoref{fig:DYN_spg_ts}a).
 To avoid aliasing of fast barotropic motions into three dimensional equations,
 time filtering is eventually applied on barotropic quantities (\np{ln\_bt\_av}\forcode{ = .true.}).
+time filtering is eventually applied on barotropic quantities (\np{ln\_bt\_av}\forcode{=.true.}).
 In that case, the integration is extended slightly beyond \textit{after} time step to
 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
 (\np{ln\_bt\_fw}\forcode{ = .false.}).
+(\np{ln\_bt\_fw}\forcode{=.false.}).
 Although more computationaly expensive ( \np{nn\_baro} additional iterations are indeed necessary),
 the baroclinic to barotropic forcing term given at \textit{now} time step become centred in
 …
 and time splitting not compatible.
 Advective barotropic velocities are obtained by using a secondary set of filtering weights,
 uniquely defined from the filter coefficients used for the time averaging (\citet{Shchepetkin_McWilliams_OM05}).
+uniquely defined from the filter coefficients used for the time averaging (\citet{shchepetkin.mcwilliams_OM05}).
 Consistency between the time averaged continuity equation and the time stepping of tracers is here the key to
 obtain exact conservation.
 …
 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
 external gravity waves in idealized or weakly non-linear cases.
 Although the damping is lower than for the filtered free surface,
 it is still significant as shown by \citet{Levier2007} in the case of an analytical barotropic Kelvin wave.
+it is still significant as shown by \citet{levier.treguier.ea_rpt07} in the case of an analytical barotropic Kelvin wave.
 %>>>>>===============
 \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}.
 We have tried various forms of such filtering,
 with the following method discussed in \cite{Griffies_al_MWR01} chosen due to
+with the following method discussed in \cite{griffies.pacanowski.ea_MWR01} chosen due to
 its stability and reasonably good maintenance of tracer conservation properties (see ??).
 …
   \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 (\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:MB_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}
     \frac{\partial {\rm {\bf U}}_h }{\partial t}= {\rm {\bf M}}
+    % \label{eq:DYN_spg_flt}
+    \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= {\mathrm {\mathbf M}}
     - g \nabla \left( \tilde{\rho} \ \eta \right)
     - g \ T_c \nabla \left( \widetilde{\rho} \ \partial_t \eta \right)
 …
   where $T_c$, is a parameter with dimensions of time which characterizes the force,
   $\widetilde{\rho} = \rho / \rho_o$ is the dimensionless density,
   and $\rm {\bf M}$ represents the collected contributions of the Coriolis, hydrostatic pressure gradient,
   non-linear and viscous terms in \autoref{eq:PE_dyn}.
+  and $\mathrm {\mathbf M}$ represents the collected contributions of the Coriolis, hydrostatic pressure gradient,
+  non-linear and viscous terms in \autoref{eq:MB_dyn}.
 }   %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.
 % ================================================================
 % Lateral diffusion term
 % ================================================================
 \section{Lateral diffusion term and operators (\protect\mdl{dynldf})}
+\section[Lateral diffusion term and operators (\textit{dynldf.F90})]{Lateral diffusion term and operators (\protect\mdl{dynldf})}
 \label{sec:DYN_ldf}
 %------------------------------------------nam_dynldf----------------------------------------------------
+\nlst{namdyn_ldf}
+\begin{listing}
+  \nlst{namdyn_ldf}
+  \caption{\texttt{namdyn\_ldf}}
+  \label{lst:namdyn_ldf}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 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}).
+This latter term is solved implicitly together with the vertical diffusion term (see \autoref{chap:TD}).
 At the lateral boundaries either free slip,
 …
   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}$.
 …
 % ================================================================
+\subsection[Iso-level laplacian (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})]
+            {Iso-level laplacian operator (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})}
+\subsection[Iso-level laplacian (\forcode{ln_dynldf_lap = .true.})]{Iso-level laplacian operator (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})}
 \label{subsec:DYN_ldf_lap}
 For lateral iso-level diffusion, the discrete operator is:
 \begin{equation}
   \label{eq:dynldf_lap}
+For lateral iso-level diffusion, the discrete operator is:
+\begin{equation}
+  \label{eq:DYN_ldf_lap}
   \left\{
     \begin{aligned}
       D_u^{l{\rm {\bf 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[
+      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[
         {A_f^{lm} \;e_{3f} \zeta } \right] \\ \\
       D_v^{l{\rm {\bf 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[
+      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[
         {A_f^{lm} \;e_{3f} \zeta } \right]
     \end{aligned}
   \right.
 \end{equation}
 As explained in \autoref{subsec:PE_ldf},
+\end{equation}
+As explained in \autoref{subsec:MB_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.
 %--------------------------------------------------------------------------------------------------------------
 %           Rotated laplacian operator
 %--------------------------------------------------------------------------------------------------------------
+\subsection[Rotated laplacian (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})]
+            {Rotated laplacian operator (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})}
+\subsection[Rotated laplacian (\forcode{ln_dynldf_iso = .true.})]{Rotated laplacian operator (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})}
 \label{subsec:DYN_ldf_iso}
 A rotation of the lateral momentum diffusion operator is needed in several cases:
 for iso-neutral diffusion in the $z$-coordinate (\np{ln\_dynldf\_iso}\forcode{ = .true.}) and
 for either iso-neutral (\np{ln\_dynldf\_iso}\forcode{ = .true.}) or
 geopotential (\np{ln\_dynldf\_hor}\forcode{ = .true.}) diffusion in the $s$-coordinate.
+for iso-neutral diffusion in the $z$-coordinate (\np{ln\_dynldf\_iso}\forcode{=.true.}) and
+for either iso-neutral (\np{ln\_dynldf\_iso}\forcode{=.true.}) or
+geopotential (\np{ln\_dynldf\_hor}\forcode{=.true.}) diffusion in the $s$-coordinate.
 In the partial step case, coordinates are horizontal except at the deepest level and
 no rotation is performed when \np{ln\_dynldf\_hor}\forcode{ = .true.}.
+no rotation is performed when \np{ln\_dynldf\_hor}\forcode{=.true.}.
 The diffusion operator is defined simply as the divergence of down gradient momentum fluxes on
 each momentum component.
 …
 The resulting discrete representation is:
 \begin{equation}
   \label{eq:dyn_ldf_iso}
+  \label{eq:DYN_ldf_iso}
   \begin{split}
     D_u^{l\textbf{U}} &= \frac{1}{e_{1u} \, e_{2u} \, e_{3u} } \\
 …
                 -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}).
 …
 %           Iso-level bilaplacian operator
 %--------------------------------------------------------------------------------------------------------------
+\subsection[Iso-level bilaplacian (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})]
+            {Iso-level bilaplacian operator (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})}
+\subsection[Iso-level bilaplacian (\forcode{ln_dynldf_bilap = .true.})]{Iso-level bilaplacian operator (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})}
 \label{subsec:DYN_ldf_bilap}
 The lateral fourth order operator formulation on momentum is obtained by applying \autoref{eq:dynldf_lap} twice.
+The lateral fourth order operator formulation on momentum is obtained by applying \autoref{eq:DYN_ldf_lap} twice.
 It requires an additional assumption on boundary conditions:
 the first derivative term normal to the coast depends on the free or no-slip lateral boundary conditions chosen,
 …
 %           Vertical diffusion term
 % ================================================================
 \section{Vertical diffusion term (\protect\mdl{dynzdf})}
+\section[Vertical diffusion term (\textit{dynzdf.F90})]{Vertical diffusion term (\protect\mdl{dynzdf})}
 \label{sec:DYN_zdf}
 %----------------------------------------------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:
 $(a)$ a forward time differencing scheme
 (\np{ln\_zdfexp}\forcode{ = .true.}) using a time splitting technique (\np{nn\_zdfexp} $>$ 1) or
 $(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.
+(\np{ln\_zdfexp}\forcode{=.true.}) using a time splitting technique (\np{nn\_zdfexp} $>$ 1) or
+$(b)$ a backward (or implicit) time differencing scheme (\np{ln\_zdfexp}\forcode{=.false.})
+(see \autoref{chap:TD}).
+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.
 The vertical diffusion operators given by \autoref{eq:PE_zdf} take the following semi-discrete space form:
 \[
   % \label{eq:dynzdf}
+The vertical diffusion operators given by \autoref{eq:MB_zdf} take the following semi-discrete space form:
+\[
+  % \label{eq:DYN_zdf}
   \left\{
     \begin{aligned}
 …
 the vertical turbulent momentum fluxes,
 \begin{equation}
   \label{eq:dynzdf_sbc}
+  \label{eq:DYN_zdf_sbc}
   \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{z=1}
   = \frac{1}{\rho_o} \binom{\tau_u}{\tau_v }
 …
 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)
 …
 The turbulent flux of momentum at the bottom of the ocean is specified through a bottom friction parameterisation
 (see \autoref{sec:ZDF_bfr})
+(see \autoref{sec:ZDF_drg})
 % ================================================================
 …
 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.
 (1) When \np{ln\_apr\_dyn}\forcode{ = .true.} (see \autoref{sec:SBC_apr}),
+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}),
 the atmospheric pressure is taken into account when computing the surface pressure gradient.
 (2) When \np{ln\_tide\_pot}\forcode{ = .true.} and \np{ln\_tide}\forcode{ = .true.} (see \autoref{sec:SBC_tide}),
+(2) When \np{ln\_tide\_pot}\forcode{=.true.} and \np{ln\_tide}\forcode{=.true.} (see \autoref{sec:SBC_tide}),
 the tidal potential is taken into account when computing the surface pressure gradient.
 (3) When \np{nn\_ice\_embd}\forcode{ = 2} and LIM or CICE is used
 (\ie when the sea-ice is embedded in the ocean),
+(3) When \np{nn\_ice\_embd}\forcode{=2} and LIM or CICE is used
+(\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 }
 \label{sec:DYN_wetdry}
 There are two main options for wetting and drying code (wd):
 (a) an iterative limiter (il) and (b) a directional limiter (dl).
 The directional limiter is based on the scheme developed by \cite{WarnerEtal13} for RO
+The directional limiter is based on the scheme developed by \cite{warner.defne.ea_CG13} for RO
 MS
 which was in turn based on ideas developed for POM by \cite{Oey06}. The iterative
+which was in turn based on ideas developed for POM by \cite{oey_OM06}. The iterative
 limiter is a new scheme.  The iterative limiter is activated by setting $\mathrm{ln\_wd\_il} = \mathrm{.true.}$
 and $\mathrm{ln\_wd\_dl} = \mathrm{.false.}$. The directional limiter is activated
 by setting $\mathrm{ln\_wd\_dl} = \mathrm{.true.}$ and $\mathrm{ln\_wd\_il} = \mathrm{.false.}$.
+\nlst{namwad}
+\begin{listing}
+  \nlst{namwad}
+  \caption{\texttt{namwad}}
+  \label{lst:namwad}
+\end{listing}
 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.
 …
 %   Iterative limiters
 %-----------------------------------------------------------------------------------------
+\subsection   [Directional limiter (\textit{wet\_dry})]
+         {Directional limiter (\mdl{wet\_dry})}
+\subsection[Directional limiter (\textit{wet\_dry.F90})]{Directional limiter (\mdl{wet\_dry})}
 \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
 …
 \cite{WarnerEtal13} state that in their scheme the velocity masks at the cell faces for the baroclinic
+\cite{warner.defne.ea_CG13} state that in their scheme the velocity masks at the cell faces for the baroclinic
 timesteps are set to 0 or 1 depending on whether the average of the masks over the barotropic sub-steps is respectively less than
 or greater than 0.5. That scheme does not conserve tracers in integrations started from constant tracer
 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.
 %-----------------------------------------------------------------------------------------
 …
 %-----------------------------------------------------------------------------------------
+\subsection   [Iterative limiter (\textit{wet\_dry})]
+         {Iterative limiter (\mdl{wet\_dry})}
+\subsection[Iterative limiter (\textit{wet\_dry.F90})]{Iterative limiter (\mdl{wet\_dry})}
 \label{subsec:DYN_wd_iterative_limiter}
+\subsubsection [Iterative flux limiter (\textit{wet\_dry})]
+         {Iterative flux limiter (\mdl{wet\_dry})}
+\label{subsubsec:DYN_wd_il_spg_limiter}
+\subsubsection[Iterative flux limiter (\textit{wet\_dry.F90})]{Iterative flux limiter (\mdl{wet\_dry})}
+\label{subsec:DYN_wd_il_spg_limiter}
 The iterative limiter modifies the fluxes across the faces of cells that are either already ``dry''
 …
 The continuity equation for the total water depth in a column
+\begin{equation} \label{dyn_wd_continuity}
+ \frac{\partial h}{\partial t} + \mathbf{\nabla.}(h\mathbf{u}) = 0 .
+\begin{equation}
+  \label{eq:DYN_wd_continuity}
+  \frac{\partial h}{\partial t} + \mathbf{\nabla.}(h\mathbf{u}) = 0 .
 \end{equation}
 can be written in discrete form  as
+\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) )
+&= - ( \mathrm{flxu}_{i+1,j} - \mathrm{flxu}_{i,j}  + \mathrm{flxv}_{i,j+1} - \mathrm{flxv}_{i,j} ) \\
+&= \mathrm{zzflx}_{i,j} .
+\begin{align}
+  \label{eq:DYN_wd_continuity_2}
+  \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} .
 \end{align}
 …
 (zzflxp) and fluxes that are into the cell (zzflxn).  Clearly
+\begin{equation} \label{dyn_wd_zzflx_p_n_1}
+\mathrm{zzflx}_{i,j} = \mathrm{zzflxp}_{i,j} + \mathrm{zzflxn}_{i,j} .
+\begin{equation}
+  \label{eq:DYN_wd_zzflx_p_n_1}
+  \mathrm{zzflx}_{i,j} = \mathrm{zzflxp}_{i,j} + \mathrm{zzflxn}_{i,j} .
 \end{equation}
 …
 $\mathrm{zcoef}_{i,j}^{(m)}$ such that:
+\begin{equation} \label{dyn_wd_continuity_coef}
+\begin{split}
+\mathrm{zzflxp}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxp}^{(0)}_{i,j} \\
+\mathrm{zzflxn}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxn}^{(0)}_{i,j}
+\end{split}
+\begin{equation}
+  \label{eq:DYN_wd_continuity_coef}
+  \begin{split}
+    \mathrm{zzflxp}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxp}^{(0)}_{i,j} \\
+    \mathrm{zzflxn}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxn}^{(0)}_{i,j}
+  \end{split}
 \end{equation}
 …
 The iteration is initialised by setting
+\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} .
+\begin{equation}
+  \label{eq:DYN_wd_zzflx_initial}
+  \mathrm{zzflxp^{(0)}}_{i,j} = \mathrm{zzflxp}_{i,j} , \quad  \mathrm{zzflxn^{(0)}}_{i,j} = \mathrm{zzflxn}_{i,j} .
 \end{equation}
 The fluxes out of cell $(i,j)$ are updated at the $m+1$th iteration if the depth of the
 cell on timestep $t_e$, namely $h_{i,j}(t_e)$, is less than the total flux out of the cell
 times the timestep divided by the cell area. Using (\ref{dyn_wd_continuity_2}) this
+times the timestep divided by the cell area. Using (\autoref{eq:DYN_wd_continuity_2}) this
 condition is
+\begin{equation} \label{dyn_wd_continuity_if}
+h_{i,j}(t_e)  - \mathrm{rn\_wdmin1} <  \frac{\Delta t}{e_1 e_2} ( \mathrm{zzflxp}^{(m)}_{i,j} + \mathrm{zzflxn}^{(m)}_{i,j} ) .
+\end{equation}
+Rearranging (\ref{dyn_wd_continuity_if}) we can obtain an expression for the maximum
+\begin{equation}
+  \label{eq:DYN_wd_continuity_if}
+  h_{i,j}(t_e)  - \mathrm{rn\_wdmin1} <  \frac{\Delta t}{e_1 e_2} ( \mathrm{zzflxp}^{(m)}_{i,j} + \mathrm{zzflxn}^{(m)}_{i,j} ) .
+\end{equation}
+Rearranging (\autoref{eq:DYN_wd_continuity_if}) we can obtain an expression for the maximum
 outward flux that can be allowed and still maintain the minimum wet depth:
+\begin{equation} \label{dyn_wd_max_flux}
+\begin{split}
+\mathrm{zzflxp}^{(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]
+\end{split}
+\end{equation}
+Note a small tolerance ($\mathrm{rn\_wdmin2}$) has been introduced here {\it [Q: Why is
+this necessary/desirable?]}. Substituting from (\ref{dyn_wd_continuity_coef}) gives an
+\begin{equation}
+  \label{eq:DYN_wd_max_flux}
+  \begin{split}
+    \mathrm{zzflxp}^{(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]
+  \end{split}
+\end{equation}
+Note a small tolerance ($\mathrm{rn\_wdmin2}$) has been introduced here {\itshape [Q: Why is
+this necessary/desirable?]}. Substituting from (\autoref{eq:DYN_wd_continuity_coef}) gives an
 expression for the coefficient needed to multiply the outward flux at this cell in order
 to avoid drying.
+\begin{equation} \label{dyn_wd_continuity_nxtcoef}
+\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} }
+\end{split}
+\begin{equation}
+  \label{eq:DYN_wd_continuity_nxtcoef}
+  \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} }
+  \end{split}
 \end{equation}
 …
 %      Surface pressure gradients
 %----------------------------------------------------------------------------------------
+\subsubsection   [Modification of surface pressure gradients (\textit{dynhpg})]
+         {Modification of surface pressure gradients (\mdl{dynhpg})}
+\label{subsubsec:DYN_wd_il_spg}
+\subsubsection[Modification of surface pressure gradients (\textit{dynhpg.F90})]{Modification of surface pressure gradients (\mdl{dynhpg})}
+\label{subsec:DYN_wd_il_spg}
 At ``dry'' points the water depth is usually close to $\mathrm{rn\_wdmin1}$. If the
 …
 neighbouring $(i+1,j)$ and $(i,j)$ tracer points.  zcpx is calculated using two logicals
 variables, $\mathrm{ll\_tmp1}$ and $\mathrm{ll\_tmp2}$ which are evaluated for each grid
 column.  The three possible combinations are illustrated in figure \ref{Fig_WAD_dynhpg}.
+column.  The three possible combinations are illustrated in \autoref{fig:DYN_WAD_dynhpg}.
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht] \begin{center}
+\includegraphics[width=0.8\textwidth]{Fig_WAD_dynhpg}
+\caption{ \label{Fig_WAD_dynhpg}
+Illustrations of the three possible combinations of the logical variables controlling the
+limiting of the horizontal pressure gradient in wetting and drying regimes}
+\end{center}\end{figure}
+\begin{figure}[!ht]
+  \centering
+  \includegraphics[width=\textwidth]{Fig_WAD_dynhpg}
+  \caption[Combinations controlling the limiting of the horizontal pressure gradient in
+  wetting and drying regimes]{
+    Three possible combinations of the logical variables controlling the
+    limiting of the horizontal pressure gradient in wetting and drying regimes}
+  \label{fig:DYN_WAD_dynhpg}
+\end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 of the topography at the two points:
+\begin{equation} \label{dyn_ll_tmp1}
+\begin{split}
+\mathrm{ll\_tmp1}  = & \mathrm{MIN(sshn(ji,jj), sshn(ji+1,jj))} > \\
+\begin{equation}
+  \label{eq:DYN_ll_tmp1}
+  \begin{split}
+    \mathrm{ll\_tmp1}  = & \mathrm{MIN(sshn(ji,jj), sshn(ji+1,jj))} > \\
                      & \quad \mathrm{MAX(-ht\_wd(ji,jj), -ht\_wd(ji+1,jj))\  .and.} \\
 & \mathrm{MAX(sshn(ji,jj) + ht\_wd(ji,jj),} \\
 & \mathrm{\phantom{MAX(}sshn(ji+1,jj) + ht\_wd(ji+1,jj))} >\\
 & \quad\quad\mathrm{rn\_wdmin1 + rn\_wdmin2 }
 \end{split}
+                     & \mathrm{MAX(sshn(ji,jj) + ht\_wd(ji,jj),} \\
+                     & \mathrm{\phantom{MAX(}sshn(ji+1,jj) + ht\_wd(ji+1,jj))} >\\
+                     & \quad\quad\mathrm{rn\_wdmin1 + rn\_wdmin2 }
+  \end{split}
 \end{equation}
 …
 at the two points plus $\mathrm{rn\_wdmin1} + \mathrm{rn\_wdmin2}$
+\begin{equation} \label{dyn_ll_tmp2}
+\begin{split}
+\mathrm{ ll\_tmp2 } = & \mathrm{( ABS( sshn(ji,jj) - sshn(ji+1,jj) ) > 1.E-12 )\ .AND.}\\
+& \mathrm{( MAX(sshn(ji,jj), sshn(ji+1,jj)) > } \\
+& \mathrm{\phantom{(} MAX(-ht\_wd(ji,jj), -ht\_wd(ji+1,jj)) + rn\_wdmin1 + rn\_wdmin2}) .
+\end{split}
+\begin{equation}
+  \label{eq:DYN_ll_tmp2}
+  \begin{split}
+    \mathrm{ ll\_tmp2 } = & \mathrm{( ABS( sshn(ji,jj) - sshn(ji+1,jj) ) > 1.E-12 )\ .AND.}\\
+    & \mathrm{( MAX(sshn(ji,jj), sshn(ji+1,jj)) > } \\
+    & \mathrm{\phantom{(} MAX(-ht\_wd(ji,jj), -ht\_wd(ji+1,jj)) + rn\_wdmin1 + rn\_wdmin2}) .
+  \end{split}
 \end{equation}
 …
 conditions.
+\subsubsection   [Additional considerations (\textit{usrdef\_zgr})]
+         {Additional considerations (\mdl{usrdef\_zgr})}
+\label{subsubsec:WAD_additional}
+\subsubsection[Additional considerations (\textit{usrdef\_zgr.F90})]{Additional considerations (\mdl{usrdef\_zgr})}
+\label{subsec:DYN_WAD_additional}
 In the very shallow water where wetting and drying occurs the parametrisation of
 …
 %      The WAD test cases
 %----------------------------------------------------------------------------------------
+\subsection   [The WAD test cases (\textit{usrdef\_zgr})]
+         {The WAD test cases (\mdl{usrdef\_zgr})}
+\label{WAD_test_cases}
+\subsection[The WAD test cases (\textit{usrdef\_zgr.F90})]{The WAD test cases (\mdl{usrdef\_zgr})}
+\label{subsec:DYN_WAD_test_cases}
 See the WAD tests MY\_DOC documention for details of the WAD test cases.
 …
 % ================================================================
 % Time evolution term
 % ================================================================
 \section{Time evolution term (\protect\mdl{dynnxt})}
+% Time evolution term
+% ================================================================
+\section[Time evolution term (\textit{dynnxt.F90})]{Time evolution term (\protect\mdl{dynnxt})}
 \label{sec:DYN_nxt}
 %----------------------------------------------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:TD}).
 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:SCOORD_momentum})
 $\bullet$ vector invariant form or linear free surface
 (\np{ln\_dynhpg\_vec}\forcode{ = .true.} ; \key{vvl} not defined):
 \[
   % \label{eq:dynnxt_vec}
+(\np{ln\_dynhpg\_vec}\forcode{=.true.} ; \texttt{vvl?} not defined):
+\[
+  % \label{eq:DYN_nxt_vec}
   \left\{
     \begin{aligned}
 …
 $\bullet$ flux form and nonlinear free surface
 (\np{ln\_dynhpg\_vec}\forcode{ = .false.} ; \key{vvl} defined):
 \[
   % \label{eq:dynnxt_flux}
+(\np{ln\_dynhpg\_vec}\forcode{=.false.} ; \texttt{vvl?} defined):
+\[
+  % \label{eq:DYN_nxt_flux}
   \left\{
     \begin{aligned}
 …
 the subscript $f$ denotes filtered values and $\gamma$ is the Asselin coefficient.
 $\gamma$ is initialized as \np{nn\_atfp} (namelist parameter).
 Its default value is \np{nn\_atfp}\forcode{ = 10.e-3}.
+Its default value is \np{nn\_atfp}\forcode{=10.e-3}.
 In both cases, the modified Asselin filter is not applied since perfect conservation is not an issue for
 the momentum equations.

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_LBC.tex

-                      r10614
+                      r11564
 \begin{document}
 % ================================================================
 % Chapter — Lateral Boundary Condition (LBC)
+% Chapter — Lateral Boundary Condition (LBC)
 % ================================================================
 \chapter{Lateral Boundary Condition (LBC)}
 \label{chap:LBC}
 \minitoc
+\chaptertoc
 \newpage
 …
 % Boundary Condition at the Coast
 % ================================================================
+\section{Boundary condition at the coast (\protect\np{rn\_shlat})}
+\section[Boundary condition at the coast (\texttt{rn\_shlat})]
+{Boundary condition at the coast (\protect\np{rn\_shlat})}
 \label{sec:LBC_coast}
+%--------------------------------------------nam_lbc-------------------------------------------------------
+\nlst{namlbc}
+%--------------------------------------------namlbc-------------------------------------------------------
+\begin{listing}
+  \nlst{namlbc}
+  \caption{\texttt{namlbc}}
+  \label{lst:namlbc}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------------
+%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,
 \[
   % \label{eq:lbc_aaaa}
+  % \label{eq:LBC_aaaa}
   \frac{A^{lT} }{e_1 }\frac{\partial T}{\partial i}\equiv \frac{A_u^{lT}
   }{e_{1u} } \; \delta_{i+1 / 2} \left[ T \right]\;\;mask_u
 …
 (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}).
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=0.90\textwidth]{Fig_LBC_uv}
+    \caption{
+      \protect\label{fig:LBC_uv}
+      Lateral boundary (thick line) at T-level.
+      The velocity normal to the boundary is set to zero.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_LBC_uv}
+  \caption[Lateral boundary at $T$-level]{
+    Lateral boundary (thick line) at T-level.
+    The velocity normal to the boundary is set to zero.}
+  \label{fig:LBC_uv}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!p]
+  \begin{center}
+    \includegraphics[width=0.90\textwidth]{Fig_LBC_shlat}
+    \caption{
+      \protect\label{fig:LBC_shlat}
+      lateral boundary condition
+      (a) free-slip ($rn\_shlat=0$);
+      (b) no-slip ($rn\_shlat=2$);
+      (c) "partial" free-slip ($0<rn\_shlat<2$) and
+      (d) "strong" no-slip ($2<rn\_shlat$).
+      Implied "ghost" velocity inside land area is display in grey.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_LBC_shlat}
+  \caption[Lateral boundary conditions]{
+    Lateral boundary conditions
+    (a) free-slip                       (\protect\np{rn\_shlat}\forcode{=0});
+    (b) no-slip                         (\protect\np{rn\_shlat}\forcode{=2});
+    (c) "partial" free-slip (\forcode{0<}\protect\np{rn\_shlat}\forcode{<2}) and
+    (d) "strong" no-slip    (\forcode{2<}\protect\np{rn\_shlat}).
+    Implied "ghost" velocity inside land area is display in grey.}
+  \label{fig:LBC_shlat}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 \begin{description}
 \item[free-slip boundary condition (\np{rn\_shlat}\forcode{ = 0}):] the tangential velocity at
+\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).
 \item[no-slip boundary condition (\np{rn\_shlat}\forcode{ = 2}):] the tangential velocity vanishes at the coastline.
+\item[no-slip boundary condition (\np{rn\_shlat}\forcode{=2}):] the tangential velocity vanishes at the coastline.
   Assuming that the tangential velocity decreases linearly from
   the closest ocean velocity grid point to the coastline,
 …
   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:
   \[
 …
   the no-slip boundary condition, simply by multiplying it by the mask$_{f}$ :
   \[
     % \label{eq:lbc_bbbb}
+    % \label{eq:LBC_bbbb}
     \zeta \equiv \frac{1}{e_{1f} {\kern 1pt}e_{2f} }\left( {\delta_{i+1/2}
         \left[ {e_{2v} \,v} \right]-\delta_{j+1/2} \left[ {e_{1u} \,u} \right]}
 …
 \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.
 …
 % Boundary Condition around the Model Domain
 % ================================================================
+\section{Model domain boundary condition (\protect\np{jperio})}
+\section[Model domain boundary condition (\texttt{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 (\protect\np{jperio}\forcode{= [0127]})}
+\subsection[Closed, cyclic (\forcode{jperio=[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}
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=1.0\textwidth]{Fig_LBC_jperio}
+    \caption{
+      \protect\label{fig:LBC_jperio}
+      setting of (a) east-west cyclic  (b) symmetric across the equator boundary conditions.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_LBC_jperio}
+  \caption[Setting of east-west cyclic and symmetric across the Equator boundary conditions]{
+    Setting of (a) east-west cyclic (b) symmetric across the Equator boundary conditions}
+  \label{fig:LBC_jperio}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 % -------------------------------------------------------------------------------------------------------------
 %        North fold (\textit{jperio = 3 }to $6)$
+%        North fold (\textit{jperio = 3 }to $6)$
 % -------------------------------------------------------------------------------------------------------------
+\subsection{North-fold (\protect\np{jperio}\forcode{ = 3..6})}
+\subsection[North-fold (\forcode{jperio=[3-6]})]
+{North-fold (\protect\jp{jperio}\forcode{=[3-6]})}
 \label{subsec:LBC_north_fold}
 The north fold boundary condition has been introduced in order to handle the north boundary of
 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}.
+Such a grid has two poles in the northern hemisphere (\autoref{fig:CFGS_ORCA_msh},
+and thus requires a specific treatment illustrated in \autoref{fig:LBC_North_Fold_T}.
 Further information can be found in \mdl{lbcnfd} module which applies the north fold boundary condition.
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=0.90\textwidth]{Fig_North_Fold_T}
+    \caption{
+      \protect\label{fig:North_Fold_T}
+      North fold boundary with a $T$-point pivot and cyclic east-west boundary condition ($jperio=4$),
+      as used in ORCA 2, 1/4, and 1/12.
+      Pink shaded area corresponds to the inner domain mask (see text).
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_North_Fold_T}
+  \caption[North fold boundary in ORCA 2\deg, 1/4\deg and 1/12\deg]{
+    North fold boundary with a $T$-point pivot and cyclic east-west boundary condition ($jperio=4$),
+    as used in ORCA 2\deg, 1/4\deg and 1/12\deg.
+    Pink shaded area corresponds to the inner domain mask (see text).}
+  \label{fig:LBC_North_Fold_T}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 % ====================================================================
 % Exchange with neighbouring processors
+% Exchange with neighbouring processors
 % ====================================================================
+\section{Exchange with neighbouring processors (\protect\mdl{lbclnk}, \protect\mdl{lib\_mpp})}
+\section[Exchange with neighbouring processors (\textit{lbclnk.F90}, \textit{lib\_mpp.F90})]
+{Exchange with neighbouring processors (\protect\mdl{lbclnk}, \protect\mdl{lib\_mpp})}
 \label{sec:LBC_mpp}
+%-----------------------------------------nammpp--------------------------------------------
+\begin{listing}
+  \nlst{nammpp}
+  \caption{\texttt{nammpp}}
+  \label{lst:nammpp}
+\end{listing}
+%-----------------------------------------------------------------------------------------------
 For massively parallel processing (mpp), a domain decomposition method is used.
 The basic idea of the method is to split the large computation domain of a numerical experiment into
 several smaller domains and solve the set of equations by addressing independent local problems.
+The basic idea of the method is to split the large computation domain of a numerical experiment into several smaller domains and
+solve the set of equations by addressing independent local problems.
 Each processor has its own local memory and computes the model equation over a subdomain of the whole model domain.
+The subdomain boundary conditions are specified through communications between processors which
+are organized by explicit statements (message passing method).
+A big advantage is that the method does not need many modifications of the initial \fortran code.
+From the modeller's point of view, each sub domain running on a processor is identical to the "mono-domain" code.
+In addition, the programmer manages the communications between subdomains,
+and the code is faster when the number of processors is increased.
+The porting of OPA code on an iPSC860 was achieved during Guyon's PhD [Guyon et al. 1994, 1995]
+in collaboration with CETIIS and ONERA.
+The implementation in the operational context and the studies of performance on
+a T3D and T3E Cray computers have been made in collaboration with IDRIS and CNRS.
+The subdomain boundary conditions are specified through communications between processors which are organized by
+explicit statements (message passing method).
 The present implementation is largely inspired by Guyon's work [Guyon 1995].
 …
 depend at the very most on one neighbouring point.
 The only non-local computations concern the vertical physics
+(implicit diffusion, turbulent closure scheme, ...) (delocalization over the whole water column),
+and the solving of the elliptic equation associated with the surface pressure gradient computation
+(delocalization over the whole horizontal domain).
+(implicit diffusion, turbulent closure scheme, ...).
 Therefore, a pencil strategy is used for the data sub-structuration:
 the 3D initial domain is laid out on local processor memories following a 2D horizontal topological splitting.
 …
 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 communication is done through the Message Passing Interface (MPI).
+the interior overlapping area to its neighbouring sub-domain (\ie\ the innermost of the two overlapping rows).
+Communications are first done according to the east-west direction and next according to the north-south direction.
+There is no specific communications for the corners.
+The communication is done through the Message Passing Interface (MPI) and requires \key{mpp\_mpi}.
+Use also \key{mpi2} if MPI3 is not available on your computer.
 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).
+It has to be pointed out that when using the MPP version of the model,
+the east-west cyclic boundary condition is done implicitly,
+whilst the south-symmetric boundary condition option is not available.
+routines found in \mdl{lib\_mpp} module.
+The output file \textit{communication\_report.txt} provides the list of which routines do how
+many communications during 1 time step of the model.\\
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=0.90\textwidth]{Fig_mpp}
+    \caption{
+      \protect\label{fig:mpp}
+      Positioning of a sub-domain when massively parallel processing is used.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_mpp}
+  \caption{Positioning of a sub-domain when massively parallel processing is used}
+  \label{fig:LBC_mpp}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+In the standard version of \NEMO, the splitting is regular and arithmetic.
+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).
+Each processor is independent and without message passing or synchronous process,
+programs run alone and access just its own local memory.
+For this reason, the main model dimensions are now the local dimensions of the subdomain (pencil) that
+are named \jp{jpi}, \jp{jpj}, \jp{jpk}.
+In \NEMO, the splitting is regular and arithmetic.
+The total number of subdomains corresponds to the number of MPI processes allocated to \NEMO\ when the model is launched
+(\ie\ mpirun -np x ./nemo will automatically give x subdomains).
+The i-axis is divided by \np{jpni} and the j-axis by \np{jpnj}.
+These parameters are defined in \nam{mpp} namelist.
+If \np{jpni} and \np{jpnj} are < 1, they will be automatically redefined in the code to give the best domain decomposition
+(see bellow).
+Each processor is independent and without message passing or synchronous process, programs run alone and access just its own local memory.
+For this reason,
+the main model dimensions are now the local dimensions of the subdomain (pencil) that are named \jp{jpi}, \jp{jpj}, \jp{jpk}.
 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 number of rows to exchange (known as the halo) is usually set to one (nn\_hls=1, in \mdl{par\_oce},
+and must be kept to one until further notice).
+The whole domain dimensions are named \jp{jpiglo}, \jp{jpjglo} and \jp{jpk}.
 The relationship between the whole domain and a sub-domain is:
+\begin{gather*}
+  jpi = ( jpiglo-2\times nn\_hls + (jpni-1) ) / jpni + 2\times nn\_hls \\
+  jpj = ( jpjglo-2\times nn\_hls + (jpnj-1) ) / jpnj + 2\times nn\_hls
+\end{gather*}
+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 (\autoref{fig:LBC_mpp}). Note that since the version 4, there is no more extra-halo area as defined in \autoref{fig:LBC_mpp} so \jp{jpi} is now always equal to nlci and \jp{jpj} equal to nlcj.
+An element of $T_{l}$, a local array (subdomain) corresponds to an element of $T_{g}$,
+a global array (whole domain) by the relationship:
 \[
+  jpi = ( jpiglo-2*jpreci + (jpni-1) ) / jpni + 2*jpreci
+  jpj = ( jpjglo-2*jprecj + (jpnj-1) ) / jpnj + 2*jprecj
+\]
+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.
+An element of $T_{l}$, a local array (subdomain) corresponds to an element of $T_{g}$,
+a global array (whole domain) by the relationship:
+\[
+  % \label{eq:lbc_nimpp}
+  % \label{eq:LBC_nimpp}
   T_{g} (i+nimpp-1,j+njmpp-1,k) = T_{l} (i,j,k),
 \]
+with  $1 \leq i \leq jpi$, $1  \leq j \leq jpj $ , and  $1  \leq k \leq jpk$.
+Processors are numbered from 0 to $jpnij-1$, the number is saved in the variable nproc.
+In the standard version, a processor has no more than
+four neighbouring processors named nono (for north), noea (east), noso (south) and nowe (west) and
+two variables, nbondi and nbondj, indicate the relative position of the processor:
+\begin{itemize}
+\item       nbondi = -1    an east neighbour, no west processor,
+\item       nbondi =  0 an east neighbour, a west neighbour,
+\item       nbondi =  1    no east processor, a west neighbour,
+\item       nbondi =  2    no splitting following the i-axis.
+\end{itemize}
+During the simulation, processors exchange data with their neighbours.
+If there is effectively a neighbour, the processor receives variables from this processor on its overlapping row,
+and sends the data issued from internal domain corresponding to the overlapping row of the other processor.
+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.
+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.
+For this reason, a pre-processing tool can be used to choose the mpp domain decomposition with a maximum number of
+only land points processors, which can then be eliminated (\autoref{fig:mppini2})
+(For example, the mpp\_optimiz tools, available from the DRAKKAR web site).
+This optimisation is dependent on the specific bathymetry employed.
+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,
+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
+routine should be suppressed from the code.}
+When land processors are eliminated,
+the value corresponding to these locations in the model output files is undefined.
+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}).
+with $1 \leq i \leq jpi$, $1  \leq j \leq jpj $ , and  $1  \leq k \leq jpk$.
+The 1-d arrays $mig(1:\jp{jpi})$ and $mjg(1:\jp{jpj})$, defined in \rou{dom\_glo} routine (\mdl{domain} module), should be used to get global domain indices from local domain indices. The 1-d arrays, $mi0(1:\jp{jpiglo})$, $mi1(1:\jp{jpiglo})$ and $mj0(1:\jp{jpjglo})$, $mj1(1:\jp{jpjglo})$ have the reverse purpose and should be used to define loop indices expressed in global domain indices (see examples in \mdl{dtastd} module).\\
+The \NEMO\ model computes equation terms with the help of mask arrays (0 on land points and 1 on sea points). It is therefore possible that an MPI subdomain contains only land points. To save ressources, we try to supress from the computational domain as much land subdomains as possible. For example if $N_{mpi}$ processes are allocated to NEMO, the domain decomposition will be given by the following equation:
+\[
+  N_{mpi} = jpni \times jpnj - N_{land} + N_{useless}
+\]
+$N_{land}$ is the total number of land subdomains in the domain decomposition defined by \np{jpni} and \np{jpnj}. $N_{useless}$ is the number of land subdomains that are kept in the compuational domain in order to make sure that $N_{mpi}$ MPI processes are indeed allocated to a given subdomain. The values of $N_{mpi}$, \np{jpni}, \np{jpnj},  $N_{land}$ and $N_{useless}$ are printed in the output file \texttt{ocean.output}. $N_{useless}$ must, of course, be as small as possible to limit the waste of ressources. A warning is issued in  \texttt{ocean.output} if $N_{useless}$ is not zero. Note that non-zero value of $N_{useless}$ is uselly required when using AGRIF as, up to now, the parent grid and each of the child grids must use all the $N_{mpi}$ processes.
+If the domain decomposition is automatically defined (when \np{jpni} and \np{jpnj} are < 1), the decomposition chosen by the model will minimise the sub-domain size (defined as $max_{all domains}(jpi \times jpj)$) and maximize the number of eliminated land subdomains. This means that no other domain decomposition (a set of \np{jpni} and \np{jpnj} values) will use less processes than $(jpni  \times  jpnj - N_{land})$ and get a smaller subdomain size.
+In order to specify $N_{mpi}$ properly (minimize $N_{useless}$), you must run the model once with \np{ln\_list} activated. In this case, the model will start the initialisation phase, print the list of optimum decompositions ($N_{mpi}$, \np{jpni} and \np{jpnj}) in \texttt{ocean.output} and directly abort. The maximum value of $N_{mpi}$ tested in this list is given by $max(N_{MPI\_tasks}, jpni \times jpnj)$. For example, run the model on 40 nodes with ln\_list activated and $jpni = 10000$ and $jpnj = 1$, will print the list of optimum domains decomposition from 1 to about 10000.
+Processors are numbered from 0 to $N_{mpi} - 1$. Subdomains containning some ocean points are numbered first from 0 to $jpni * jpnj - N_{land} -1$. The remaining $N_{useless}$ land subdomains are numbered next, which means that, for a given (\np{jpni}, \np{jpnj}), the numbers attributed to he ocean subdomains do not vary with $N_{useless}$.
+When land processors are eliminated, the value corresponding to these locations in the model output files is undefined. \np{ln\_mskland} must be activated in order avoid Not a Number values in output files. Note that it is better to not eliminate land processors when creating a meshmask file (\ie\ when setting a non-zero value to \np{nn\_msh}).
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!ht]
+  \begin{center}
+    \includegraphics[width=0.90\textwidth]{Fig_mppini2}
+    \caption {
+      \protect\label{fig:mppini2}
+      Example of Atlantic domain defined for the CLIPPER projet.
+      Initial grid is composed of 773 x 1236 horizontal points.
+      (a) the domain is split onto 9 \time 20 subdomains (jpni=9, jpnj=20).
+subdomains are land areas.
+      (b) 52 subdomains are eliminated (white rectangles) and
+      the resulting number of processors really used during the computation is jpnij=128.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_mppini2}
+  \caption[Atlantic domain defined for the CLIPPER projet]{
+    Example of Atlantic domain defined for the CLIPPER projet.
+    Initial grid is composed of 773 x 1236 horizontal points.
+    (a) the domain is split onto 9 $times$ 20 subdomains (jpni=9, jpnj=20).
+subdomains are land areas.
+    (b) 52 subdomains are eliminated (white rectangles) and
+    the resulting number of processors really used during the computation is jpnij=128.}
+  \label{fig:LBC_mppini2}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 % ====================================================================
 % Unstructured open boundaries BDY
+% Unstructured open boundaries BDY
 % ====================================================================
 \section{Unstructured open boundary conditions (BDY)}
 …
 %-----------------------------------------nambdy--------------------------------------------
+\nlst{nambdy}
+\begin{listing}
+  \nlst{nambdy}
+  \caption{\texttt{nambdy}}
+  \label{lst:nambdy}
+\end{listing}
 %-----------------------------------------------------------------------------------------------
 %-----------------------------------------nambdy_dta--------------------------------------------
+\nlst{nambdy_dta}
+\begin{listing}
+  \nlst{nambdy_dta}
+  \caption{\texttt{nambdy\_dta}}
+  \label{lst:nambdy_dta}
+\end{listing}
 %-----------------------------------------------------------------------------------------------
 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
 a similar coding structure \citep{Chanut2005}.
+Options are defined through the \nam{bdy} and \nam{bdy\_dta} namelist variables.
+The BDY module is the core implementation of open boundary conditions for regional configurations on
+ocean temperature, salinity, barotropic-baroclinic velocities, ice-snow concentration, thicknesses, temperatures, salinity and melt ponds concentration and thickness.
+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.
 %----------------------------------------------
 \subsection{Namelists}
 \label{subsec:BDY_namelist}
 The BDY module is activated by setting \np{ln\_bdy}\forcode{ = .true.} .
+\label{subsec:LBC_bdy_namelist}
+The BDY module is activated by setting \np{ln\_bdy}\forcode{=.true.} .
 It is possible to define more than one boundary ``set'' and apply different boundary conditions to each set.
 The number of boundary sets is defined by \np{nb\_bdy}.
+Each boundary set may be defined as a set of straight line segments in a namelist
+(\np{ln\_coords\_file}\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 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.
+Each boundary set can be either defined as a series of straight line segments directly in the namelist
+(\np{ln\_coords\_file}\forcode{=.false.}, and a namelist block \nam{bdy\_index} must be included for each set) or read in from a file (\np{ln\_coords\_file}\forcode{=.true.}, and a ``\ifile{coordinates.bdy}'' file must be provided).
+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 more details of the definition of the boundary geometry see section \autoref{subsec:BDY_geometry}.
+the second is defined in the namelist.
+For more details of the definition of the boundary geometry see section \autoref{subsec:LBC_bdy_geometry}.
 For each boundary set a boundary condition has to be chosen for the barotropic solution
+(``u2d'':sea-surface height and barotropic velocities), for the baroclinic velocities (``u3d''),
+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}.\\
+(``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 for sea-ice (``ice'').
+For each set of variables one has to choose an algorithm and the boundary data (set resp. by \np{cn\_tra} and \np{nn\_tra\_dta} for tracers).\\
 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),
 the bdy code can derived baroclinic and barotropic velocities by setting \np{ln\_full\_vel}\forcode{ = .true. }
+The boundary data is either set to initial conditions
+(\np{nn\_tra\_dta}\forcode{=0}) or forced with 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),
+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).
+itself (\np{nn\_dyn2d\_dta}\forcode{=2}) or in addition to other external data (\np{nn\_dyn2d\_dta}\forcode{=3}).\\
+If not set to initial conditions, sea-ice salinity, temperatures and melt ponds data at the boundary can either be read in a file or defined as constant (by \np{rn\_ice\_sal}, \np{rn\_ice\_tem}, \np{rn\_ice\_apnd}, \np{rn\_ice\_hpnd}). Ice age is constant and defined by \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.
+Also whether or not time-interpolation is required and whether the data is climatological (time-cyclic) data.\\
+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.
+For sea-ice salinity, temperatures and melt ponds, reading the files are skipped and constant values are used if filenames are defined as {'NOT USED'}.\\
 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.
 %----------------------------------------------
 \subsection{Flow relaxation scheme}
 \label{subsec:BDY_FRS_scheme}
 The Flow Relaxation Scheme (FRS) \citep{Davies_QJRMS76,Engerdahl_Tel95},
+\label{subsec:LBC_bdy_FRS_scheme}
+The Flow Relaxation Scheme (FRS) \citep{davies_QJRMS76,engedahl_T95},
 applies a simple relaxation of the model fields to externally-specified values over
 a zone next to the edge of the model domain.
 Given a model prognostic variable $\Phi$
 \[
   % \label{eq:bdy_frs1}
+  % \label{eq:LBC_bdy_frs1}
   \Phi(d) = \alpha(d)\Phi_{e}(d) + (1-\alpha(d))\Phi_{m}(d)\;\;\;\;\; d=1,N
 \]
 …
 the prognostic equation for $\Phi$ of the form:
 \[
   % \label{eq:bdy_frs2}
+  % \label{eq:LBC_bdy_frs2}
   -\frac{1}{\tau}\left(\Phi - \Phi_{e}\right)
 \]
 where the relaxation time scale $\tau$ is given by a function of $\alpha$ and the model time step $\Delta t$:
 \[
   % \label{eq:bdy_frs3}
+  % \label{eq:LBC_bdy_frs3}
   \tau = \frac{1-\alpha}{\alpha}  \,\rdt
 \]
 …
 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:
 \[
   % \label{eq:bdy_frs4}
+  % \label{eq:LBC_bdy_frs4}
   \alpha(d) = 1 - \tanh\left(\frac{d-1}{2}\right),       \quad d=1,N
 \]
 …
 %----------------------------------------------
 \subsection{Flather radiation scheme}
 \label{subsec:BDY_flather_scheme}
 The \citet{Flather_JPO94} scheme is a radiation condition on the normal,
+\label{subsec:LBC_bdy_flather_scheme}
+The \citet{flather_JPO94} scheme is a radiation condition on the normal,
 depth-mean transport across the open boundary.
 It takes the form
+\begin{equation}  \label{eq:bdy_fla1}
+U = U_{e} + \frac{c}{h}\left(\eta - \eta_{e}\right),
+\begin{equation}
+  \label{eq:LBC_bdy_fla1}
+  U = U_{e} + \frac{c}{h}\left(\eta - \eta_{e}\right),
 \end{equation}
 where $U$ is the depth-mean velocity normal to the boundary and $\eta$ is the sea surface height,
 …
 the external depth-mean normal velocity,
 plus a correction term that allows gravity waves generated internally to exit the model boundary.
 Note that the sea-surface height gradient in \autoref{eq:bdy_fla1} is a spatial gradient across the model boundary,
+Note that the sea-surface height gradient in \autoref{eq:LBC_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.
 %----------------------------------------------
 \subsection{Orlanski radiation scheme}
 \label{subsec:BDY_orlanski_scheme}
 The Orlanski scheme is based on the algorithm described by \citep{Marchesiello2001}, hereafter MMS.
+\label{subsec:LBC_bdy_orlanski_scheme}
+The Orlanski scheme is based on the algorithm described by \citep{marchesiello.mcwilliams.ea_OM01}, hereafter MMS.
 The adaptive Orlanski condition solves a wave plus relaxation equation at the boundary:
 \begin{equation}
+\frac{\partial\phi}{\partial t} + c_x \frac{\partial\phi}{\partial x} + c_y \frac{\partial\phi}{\partial y} =
                                                 -\frac{1}{\tau}(\phi - \phi^{ext})
+\label{eq:wave_continuous}
+  \label{eq:LBC_wave_continuous}
+  \frac{\partial\phi}{\partial t} + c_x \frac{\partial\phi}{\partial x} + c_y \frac{\partial\phi}{\partial y} =
+  -\frac{1}{\tau}(\phi - \phi^{ext})
 \end{equation}
 …
 velocities are diagnosed from the model fields as:
+\begin{equation} \label{eq:cx}
+c_x = -\frac{\partial\phi}{\partial t}\frac{\partial\phi / \partial x}{(\partial\phi /\partial x)^2 + (\partial\phi /\partial y)^2}
+\begin{equation}
+  \label{eq:LBC_cx}
+  c_x = -\frac{\partial\phi}{\partial t}\frac{\partial\phi / \partial x}{(\partial\phi /\partial x)^2 + (\partial\phi /\partial y)^2}
 \end{equation}
 \begin{equation}
 \label{eq:cy}
 c_y = -\frac{\partial\phi}{\partial t}\frac{\partial\phi / \partial y}{(\partial\phi /\partial x)^2 + (\partial\phi /\partial y)^2}
+  \label{eq:LBC_cy}
+  c_y = -\frac{\partial\phi}{\partial t}\frac{\partial\phi / \partial y}{(\partial\phi /\partial x)^2 + (\partial\phi /\partial y)^2}
 \end{equation}
 (As noted by MMS, this is a circular diagnosis of the phase speeds which only makes sense on a discrete grid).
 Equation (\autoref{eq:wave_continuous}) is defined adaptively depending on the sign of the phase velocity normal to the boundary $c_x$.
+Equation (\autoref{eq:LBC_wave_continuous}) is defined adaptively depending on the sign of the phase velocity normal to the boundary $c_x$.
 For $c_x$ outward, we have
 …
 \begin{equation}
+\tau = \tau_{in}\,\,\,;\,\,\, c_x = c_y = 0
+\label{eq:tau_in}
+  \label{eq:LBC_tau_in}
+  \tau = \tau_{in}\,\,\,;\,\,\, c_x = c_y = 0
 \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
 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
 (\autoref{eq:wave_continuous}) - (\autoref{eq:tau_in}) correspond to equations (13) - (15) and (2) - (3) in MMS.\\
+See \autoref{subsec:LBC_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:LBC_wave_continuous}), but including
+this term in the denominator of equation (\autoref{eq:LBC_cx}). Both versions of the scheme are options in BDY. Equations
+(\autoref{eq:LBC_wave_continuous}) - (\autoref{eq:LBC_tau_in}) correspond to equations (13) - (15) and (2) - (3) in MMS.\\
 %----------------------------------------------
 \subsection{Relaxation at the boundary}
 \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.
+\label{subsec:LBC_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.
 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.
 %----------------------------------------------
 \subsection{Boundary geometry}
 \label{subsec:BDY_geometry}
+\label{subsec:LBC_bdy_geometry}
 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.
+\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 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.
+\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.
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=1.0\textwidth]{Fig_LBC_bdy_geom}
+    \caption {
+      \protect\label{fig:LBC_bdy_geom}
+      Example of geometry of unstructured open boundary
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_LBC_bdy_geom}
+  \caption[Geometry of unstructured open boundary]{Example of geometry of unstructured open boundary}
+  \label{fig:LBC_bdy_geom}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 %----------------------------------------------
 \subsection{Input boundary data files}
 \label{subsec:BDY_data}
+\label{subsec:LBC_bdy_data}
 The data files contain the data arrays in the order in which the points are defined in the $nbi$ and $nbj$ arrays.
 …
 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}
 These restrictions mean that data files used with versions of the
 model prior to Version 3.4 may not work with Version 3.4 onwards.
 A \fortran utility {\it bdy\_reorder} exists in the TOOLS directory which
+A \fortran\ utility {\itshape bdy\_reorder} exists in the TOOLS directory which
 will re-order the data in old BDY data files.
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=1.0\textwidth]{Fig_LBC_nc_header}
+    \caption {
+      \protect\label{fig:LBC_nc_header}
+      Example of the header for a \protect\ifile{coordinates.bdy} file
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_LBC_nc_header}
+  \caption[Header for a \protect\ifile{coordinates.bdy} file]{
+    Example of the header for a \protect\ifile{coordinates.bdy} file}
+  \label{fig:LBC_nc_header}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 %----------------------------------------------
 \subsection{Volume correction}
 \label{subsec:BDY_vol_corr}
+\label{subsec:LBC_bdy_vol_corr}
 There is an option to force the total volume in the regional model to be constant.
 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}).
 If \np{nn\_volctl}\forcode{ = 0} then a correction is applied to the normal barotropic velocities around the boundary at
+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}).
+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.
 If \np{nn\_volctl}\forcode{ = 1} then the calculation of the volume change on
+If \np{nn\_volctl}\forcode{=1} then the calculation of the volume change on
 the timestep includes the change due to the freshwater flux across the surface and
 the correction velocity corrects for this as well.
 …
 %----------------------------------------------
 \subsection{Tidal harmonic forcing}
 \label{subsec:BDY_tides}
+\label{subsec:LBC_bdy_tides}
 %-----------------------------------------nambdy_tide--------------------------------------------
+\nlst{nambdy_tide}
+\begin{listing}
+  \nlst{nambdy_tide}
+  \caption{\texttt{nambdy\_tide}}
+  \label{lst:nambdy_tide}
+\end{listing}
 %-----------------------------------------------------------------------------------------------
 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_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_LDF.tex

-                      r10442
+                      r11564
 \label{chap:LDF}
 \minitoc
+\chaptertoc
 \newpage
 The lateral physics terms in the momentum and tracer equations have been described in \autoref{eq:PE_zdf} and
+The lateral physics terms in the momentum and tracer equations have been described in \autoref{eq:MB_zdf} and
 their discrete formulation in \autoref{sec:TRA_ldf} and \autoref{sec:DYN_ldf}).
 In this section we further discuss each lateral physics option.
 …
 (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).
+Note that this chapter describes the standard implementation of iso-neutral tracer mixing,
+and Griffies's implementation, which is used if \np{traldf\_grif}\forcode{ = .true.},
+is described in Appdx\autoref{apdx:triad}
+%-----------------------------------nam_traldf - nam_dynldf--------------------------------------------
+\nlst{namtra_ldf}
+\nlst{namdyn_ldf}
+(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.},
+is described in \autoref{apdx:TRIADS}
+%-----------------------------------namtra_ldf - namdyn_ldf--------------------------------------------
 %--------------------------------------------------------------------------------------------------------------
+% ================================================================
+% Lateral Mixing Operator
+% ================================================================
+\section[Lateral mixing operators]
+{Lateral mixing operators}
+\label{sec:LDF_op}
+We remind here the different lateral mixing operators that can be used. Further details can be found in \autoref{subsec:TRA_ldf_op} and  \autoref{sec:DYN_ldf}.
+\subsection[No lateral mixing (\forcode{ln_traldf_OFF}, \forcode{ln_dynldf_OFF})]
+{No lateral mixing (\protect\np{ln\_traldf\_OFF}, \protect\np{ln\_dynldf\_OFF})}
+It is possible to run without explicit lateral diffusion on tracers (\protect\np{ln\_traldf\_OFF}\forcode{=.true.}) and/or
+momentum (\protect\np{ln\_dynldf\_OFF}\forcode{=.true.}). The latter option is even recommended if using the
+UBS advection scheme on momentum (\np{ln\_dynadv\_ubs}\forcode{=.true.},
+see \autoref{subsec:DYN_adv_ubs}) and can be useful for testing purposes.
+\subsection[Laplacian mixing (\forcode{ln_traldf_lap}, \forcode{ln_dynldf_lap})]
+{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
+Laplacian and Bilaplacian operators for the same variable.
+\subsection[Bilaplacian mixing (\forcode{ln_traldf_blp}, \forcode{ln_dynldf_blp})]
+{Bilaplacian mixing (\protect\np{ln\_traldf\_blp}, \protect\np{ln\_dynldf\_blp})}
+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.
 % ================================================================
 % Direction of lateral Mixing
 % ================================================================
+\section{Direction of lateral mixing (\protect\mdl{ldfslp})}
+\section[Direction of lateral mixing (\textit{ldfslp.F90})]
+{Direction of lateral mixing (\protect\mdl{ldfslp})}
 \label{sec:LDF_slp}
 …
 \gmcomment{
   we should emphasize here that the implementation is a rather old one.
   Better work can be achieved by using \citet{Griffies_al_JPO98, Griffies_Bk04} iso-neutral scheme.
+  Better work can be achieved by using \citet{griffies.gnanadesikan.ea_JPO98, griffies_bk04} iso-neutral scheme.
+}
 …
 the cell of the quantity to be diffused.
 For a tracer, this leads to the following four slopes:
 $r_{1u}$, $r_{1w}$, $r_{2v}$, $r_{2w}$ (see \autoref{eq:tra_ldf_iso}),
+$r_{1u}$, $r_{1w}$, $r_{2v}$, $r_{2w}$ (see \autoref{eq:TRA_ldf_iso}),
 while for momentum the slopes are  $r_{1t}$, $r_{1uw}$, $r_{2f}$, $r_{2uw}$ for $u$ and
 $r_{1f}$, $r_{1vw}$, $r_{2t}$, $r_{2vw}$ for $v$.
+$r_{1f}$, $r_{1vw}$, $r_{2t}$, $r_{2vw}$ for $v$.
 %gm% add here afigure of the slope in i-direction
 …
 \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
+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}
 \begin{equation}
   \label{eq:ldfslp_geo}
+  \label{eq:LDF_slp_geo}
   \begin{aligned}
     r_{1u} &= \frac{e_{3u}}{ \left( e_{1u}\;\overline{\overline{e_{3w}}}^{\,i+1/2,\,k} \right)}
 …
 \end{equation}
 %gm%  caution I'm not sure the simplification was a good idea!
 These slopes are computed once in \rou{ldfslp\_init} when \np{ln\_sco}\forcode{ = .true.}rue,
 and either \np{ln\_traldf\_hor}\forcode{ = .true.} or \np{ln\_dynldf\_hor}\forcode{ = .true.}.
+%gm%  caution I'm not sure the simplification was a good idea!
+These slopes are computed once in \rou{ldf\_slp\_init} when \np{ln\_sco}\forcode{=.true.},
+and either \np{ln\_traldf\_hor}\forcode{=.true.} or \np{ln\_dynldf\_hor}\forcode{=.true.}.
 \subsection{Slopes for tracer iso-neutral mixing}
 …
 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.
 So, substituting $T$ by $\rho$ in \autoref{eq:tra_ldf_iso} and setting the diffusive fluxes in
+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:
 \begin{equation}
   \label{eq:ldfslp_iso}
+  \label{eq:LDF_slp_iso}
   \begin{split}
     r_{1u} &= \frac{e_{3u}}{e_{1u}}\; \frac{\delta_{i+1/2}[\rho]}
 …
 %gm% rewrite this as the explanation is not very clear !!!
 %In practice, \autoref{eq:ldfslp_iso} is of little help in evaluating the neutral surface slopes. Indeed, for an unsimplified equation of state, the density has a strong dependancy on pressure (here approximated as the depth), therefore applying \autoref{eq:ldfslp_iso} using the $in situ$ density, $\rho$, computed at T-points leads to a flattening of slopes as the depth increases. This is due to the strong increase of the $in situ$ density with depth.
 %By definition, neutral surfaces are tangent to the local $in situ$ density \citep{McDougall1987}, therefore in \autoref{eq:ldfslp_iso}, all the derivatives have to be evaluated at the same local pressure (which in decibars is approximated by the depth in meters).
 %In the $z$-coordinate, the derivative of the  \autoref{eq:ldfslp_iso} numerator is evaluated at the same depth \nocite{as what?} ($T$-level, which is the same as the $u$- and $v$-levels), so  the $in situ$ density can be used for its evaluation.
 As the mixing is performed along neutral surfaces, the gradient of $\rho$ in \autoref{eq:ldfslp_iso} has to
+%In practice, \autoref{eq:LDF_slp_iso} is of little help in evaluating the neutral surface slopes. Indeed, for an unsimplified equation of state, the density has a strong dependancy on pressure (here approximated as the depth), therefore applying \autoref{eq:LDF_slp_iso} using the $in situ$ density, $\rho$, computed at T-points leads to a flattening of slopes as the depth increases. This is due to the strong increase of the $in situ$ density with depth.
+%By definition, neutral surfaces are tangent to the local $in situ$ density \citep{mcdougall_JPO87}, therefore in \autoref{eq:LDF_slp_iso}, all the derivatives have to be evaluated at the same local pressure (which in decibars is approximated by the depth in meters).
+%In the $z$-coordinate, the derivative of the  \autoref{eq:LDF_slp_iso} numerator is evaluated at the same depth \nocite{as what?} ($T$-level, which is the same as the $u$- and $v$-levels), so  the $in situ$ density can be used for its evaluation.
+As the mixing is performed along neutral surfaces, the gradient of $\rho$ in \autoref{eq:LDF_slp_iso} has to
 be evaluated at the same local pressure
 (which, in decibars, is approximated by the depth in meters in the model).
 Therefore \autoref{eq:ldfslp_iso} cannot be used as such,
+Therefore \autoref{eq:LDF_slp_iso} cannot be used as such,
 but further transformation is needed depending on the vertical coordinate used:
 …
 \item[$z$-coordinate with full step: ]
   in \autoref{eq:ldfslp_iso} the densities appearing in the $i$ and $j$ derivatives  are taken at the same depth,
+  in \autoref{eq:LDF_slp_iso} the densities appearing in the $i$ and $j$ derivatives  are taken at the same depth,
   thus the $in situ$ density can be used.
   This is not the case for the vertical derivatives: $\delta_{k+1/2}[\rho]$ is replaced by $-\rho N^2/g$,
   where $N^2$ is the local Brunt-Vais\"{a}l\"{a} frequency evaluated following \citet{McDougall1987}
   (see \autoref{subsec:TRA_bn2}).
+  where $N^2$ is the local Brunt-Vais\"{a}l\"{a} frequency evaluated following \citet{mcdougall_JPO87}
+  (see \autoref{subsec:TRA_bn2}).
 \item[$z$-coordinate with partial step: ]
 …
 \item[$s$- or hybrid $s$-$z$- coordinate: ]
   in the current release of \NEMO, iso-neutral mixing is only employed for $s$-coordinates if
   the Griffies scheme is used (\np{traldf\_grif}\forcode{ = .true.};
   see Appdx \autoref{apdx:triad}).
+  the Griffies scheme is used (\np{ln\_traldf\_triad}\forcode{=.true.};
+  see \autoref{apdx:TRIADS}).
   In other words, iso-neutral mixing will only be accurately represented with a linear equation of state
   (\np{nn\_eos}\forcode{ = 1..2}).
   In the case of a "true" equation of state, the evaluation of $i$ and $j$ derivatives in \autoref{eq:ldfslp_iso}
+  (\np{ln\_seos}\forcode{=.true.}).
+  In the case of a "true" equation of state, the evaluation of $i$ and $j$ derivatives in \autoref{eq:LDF_slp_iso}
   will include a pressure dependent part, leading to the wrong evaluation of the neutral slopes.
 %gm%
+%gm%
   Note: The solution for $s$-coordinate passes trough the use of different (and better) expression for
   the constraint on iso-neutral fluxes.
   Following \citet{Griffies_Bk04}, instead of specifying directly that there is a zero neutral diffusive flux of
+  Following \citet{griffies_bk04}, instead of specifying directly that there is a zero neutral diffusive flux of
   locally referenced potential density, we stay in the $T$-$S$ plane and consider the balance between
   the neutral direction diffusive fluxes of potential temperature and salinity:
 …
 \[
   % \label{eq:ldfslp_iso2}
+  % \label{eq:LDF_slp_iso2}
   \begin{split}
     r_{1u} &= \frac{e_{3u}}{e_{1u}}\; \frac
 …
 This implementation is a rather old one.
 It is similar to the one proposed by Cox [1987], except for the background horizontal diffusion.
 Indeed, the Cox implementation of isopycnal diffusion in GFDL-type models requires
+It is similar to the one proposed by \citet{cox_OM87}, except for the background horizontal diffusion.
+Indeed, the \citet{cox_OM87} implementation of isopycnal diffusion in GFDL-type models requires
 a minimum background horizontal diffusion for numerical stability reasons.
 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_al_JPO98}.
 Griffies's scheme is now available in \NEMO if \np{traldf\_grif\_iso} is set true; see Appdx \autoref{apdx:triad}.
 Here, another strategy is presented \citep{Lazar_PhD97}:
+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:TRIADS}.
+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
 grid point noise generated by the iso-neutral diffusion operator (\autoref{fig:LDF_ZDF1}).
 …
 Nevertheless, this iso-neutral operator does not ensure that variance cannot increase,
 contrary to the \citet{Griffies_al_JPO98} operator which has that property.
+contrary to the \citet{griffies.gnanadesikan.ea_JPO98} operator which has that property.
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!ht]
+  \begin{center}
+    \includegraphics[width=0.70\textwidth]{Fig_LDF_ZDF1}
+    \caption {
+      \protect\label{fig:LDF_ZDF1}
+      averaging procedure for isopycnal slope computation.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_LDF_ZDF1}
+  \caption{Averaging procedure for isopycnal slope computation}
+  \label{fig:LDF_ZDF1}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 %There are three additional questions about the slope calculation.
 %First the expression for the rotation tensor has been obtain assuming the "small slope" approximation, so a bound has to be imposed on slopes.
 %Second, numerical stability issues also require a bound on slopes.
+%There are three additional questions about the slope calculation.
+%First the expression for the rotation tensor has been obtain assuming the "small slope" approximation, so a bound has to be imposed on slopes.
+%Second, numerical stability issues also require a bound on slopes.
 %Third, the question of boundary condition specified on slopes...
 …
 % In addition and also for numerical stability reasons \citep{Cox1987, Griffies_Bk04},
 % the slopes are bounded by $1/100$ everywhere. This limit is decreasing linearly
 % to zero fom $70$ meters depth and the surface (the fact that the eddies "feel" the
+% In addition and also for numerical stability reasons \citep{cox_OM87, griffies_bk04},
+% the slopes are bounded by $1/100$ everywhere. This limit is decreasing linearly
+% to zero fom $70$ meters depth and the surface (the fact that the eddies "feel" the
 % surface motivates this flattening of isopycnals near the surface).
 For numerical stability reasons \citep{Cox1987, Griffies_Bk04}, the slopes must also be bounded by
 $1/100$ everywhere.
+For numerical stability reasons \citep{cox_OM87, griffies_bk04}, the slopes must also be bounded by
+the namelist scalar \np{rn\_slpmax} (usually $1/100$) everywhere.
 This constraint is applied in a piecewise linear fashion, increasing from zero at the surface to
 $1/100$ at $70$ metres and thereafter decreasing to zero at the bottom of the ocean
 (the fact that the eddies "feel" the surface motivates this flattening of isopycnals near the surface).
+\colorbox{yellow}{The way slopes are tapered has be checked. Not sure that this is still what is actually done.}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!ht]
+  \begin{center}
+    \includegraphics[width=0.70\textwidth]{Fig_eiv_slp}
+    \caption{
+      \protect\label{fig:eiv_slp}
+      Vertical profile of the slope used for lateral mixing in the mixed layer:
+      \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:
+      wall boundary condition).
+      Nevertheless, the profile between the surface zero value and the interior iso-neutral one is unknown,
+      and especially the value at the base of the mixed layer;
+      \textit{(b)} profile of slope using a linear tapering of the slope near the surface and
+      imposing a maximum slope of 1/100;
+      \textit{(c)} profile of slope actually used in \NEMO: a linear decrease of the slope from
+      zero at the surface to its ocean interior value computed just below the mixed layer.
+      Note the huge change in the slope at the base of the mixed layer between \textit{(b)} and \textit{(c)}.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_eiv_slp}
+  \caption[Vertical profile of the slope used for lateral mixing in the mixed layer]{
+    Vertical profile of the slope used for lateral mixing in the mixed layer:
+    \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:
+    wall boundary condition).
+    Nevertheless,
+    the profile between the surface zero value and the interior iso-neutral one is unknown,
+    and especially the value at the base of the mixed layer;
+    \textit{(b)} profile of slope using a linear tapering of the slope near the surface and
+    imposing a maximum slope of 1/100;
+    \textit{(c)} profile of slope actually used in \NEMO:
+    a linear decrease of the slope from zero at the surface to
+    its ocean interior value computed just below the mixed layer.
+    Note the huge change in the slope at the base of the mixed layer between
+    \textit{(b)} and \textit{(c)}.}
+  \label{fig:LDF_eiv_slp}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 The iso-neutral diffusion operator on momentum is the same as the one used on tracers but
 applied to each component of the velocity separately
 (see \autoref{eq:dyn_ldf_iso} in section~\autoref{subsec:DYN_ldf_iso}).
+(see \autoref{eq:DYN_ldf_iso} in section~\autoref{subsec:DYN_ldf_iso}).
 The slopes between the surface along which the diffusion operator acts and the surface of computation
 ($z$- or $s$-surfaces) are defined at $T$-, $f$-, and \textit{uw}- points for the $u$-component, and $T$-, $f$- and
 \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:LDF_slp_geo} and \autoref{eq:LDF_slp_iso}:
 \[
   % \label{eq:ldfslp_dyn}
+  % \label{eq:LDF_slp_dyn}
   \begin{aligned}
     &r_{1t}\ \ = \overline{r_{1u}}^{\,i}       &&&    r_{1f}\ \ &= \overline{r_{1u}}^{\,i+1/2} \\
 …
 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}).
 % ================================================================
-% Lateral Mixing Operator
-% ================================================================
-\section{Lateral mixing operators (\protect\mdl{traldf}, \protect\mdl{traldf}) }
-\label{sec:LDF_op}
-% ================================================================
 % Lateral Mixing Coefficients
 % ================================================================
+\section{Lateral mixing coefficient (\protect\mdl{ldftra}, \protect\mdl{ldfdyn}) }
+\section[Lateral mixing coefficient (\forcode{nn_aht_ijk_t}, \forcode{nn_ahm_ijk_t})]
+{Lateral mixing coefficient (\protect\np{nn\_aht\_ijk\_t}, \protect\np{nn\_ahm\_ijk\_t})}
 \label{sec:LDF_coef}
+Introducing a space variation in the lateral eddy mixing coefficients changes the model core memory requirement,
+adding up to four extra three-dimensional arrays for the geopotential or isopycnal second order operator applied to
+momentum.
+Six CPP keys control the space variation of eddy coefficients: three for momentum and three for tracer.
+The three choices allow:
+a space variation in the three space directions (\key{traldf\_c3d},  \key{dynldf\_c3d}),
+in the horizontal plane (\key{traldf\_c2d},  \key{dynldf\_c2d}),
+or in the vertical only (\key{traldf\_c1d},  \key{dynldf\_c1d}).
+The default option is a constant value over the whole ocean on both momentum and tracers.
+The number of additional arrays that have to be defined and the gridpoint position at which
+they are defined depend on both the space variation chosen and the type of operator used.
+The resulting eddy viscosity and diffusivity coefficients can be a function of more than one variable.
+Changes in the computer code when switching from one option to another have been minimized by
+introducing the eddy coefficients as statement functions
+(include file \textit{ldftra\_substitute.h90} and \textit{ldfdyn\_substitute.h90}).
+The functions are replaced by their actual meaning during the preprocessing step (CPP).
+The specification of the space variation of the coefficient is made in \mdl{ldftra} and \mdl{ldfdyn},
+or more precisely in include files \textit{traldf\_cNd.h90} and \textit{dynldf\_cNd.h90}, with N=1, 2 or 3.
+The user can modify these include files as he/she wishes.
+The way the mixing coefficient are set in the reference version can be briefly described as follows:
+\subsubsection{Constant mixing coefficients (default option)}
+When none of the \key{dynldf\_...} and \key{traldf\_...} keys are defined,
+a constant value is used over the whole ocean for momentum and tracers,
+which is specified through the \np{rn\_ahm0} and \np{rn\_aht0} namelist parameters.
+\subsubsection{Vertically varying mixing coefficients (\protect\key{traldf\_c1d} and \key{dynldf\_c1d})}
+The 1D option is only available when using the $z$-coordinate with full step.
+Indeed in all the other types of vertical coordinate,
+the depth is a 3D function of (\textbf{i},\textbf{j},\textbf{k}) and therefore,
+introducing depth-dependent mixing coefficients will require 3D arrays.
+In the 1D option, a hyperbolic variation of the lateral mixing coefficient is introduced in which
+the surface value is \np{rn\_aht0} (\np{rn\_ahm0}), the bottom value is 1/4 of the surface value,
+and the transition takes place around z=300~m with a width of 300~m
+(\ie both the depth and the width of the inflection point are set to 300~m).
+This profile is hard coded in file \textit{traldf\_c1d.h90}, but can be easily modified by users.
+\subsubsection{Horizontally varying mixing coefficients (\protect\key{traldf\_c2d} and \protect\key{dynldf\_c2d})}
+By default the horizontal variation of the eddy coefficient depends on the local mesh size and
+The specification of the space variation of the coefficient is made in modules \mdl{ldftra} and \mdl{ldfdyn}.
+The way the mixing coefficients are set in the reference version can be described as follows:
+\subsection[Mixing coefficients read from file (\forcode{nn_aht_ijk_t=-20, -30}, \forcode{nn_ahm_ijk_t=-20,-30})]
+{ Mixing coefficients read from file (\protect\np{nn\_aht\_ijk\_t}\forcode{=-20, -30}, \protect\np{nn\_ahm\_ijk\_t}\forcode{=-20, -30})}
+Mixing coefficients can be read from file if a particular geographical variation is needed. For example, in the ORCA2 global ocean model,
+the laplacian viscosity operator uses $A^l$~= 4.10$^4$ m$^2$/s poleward of 20$^{\circ}$ north and south and
+decreases linearly to $A^l$~= 2.10$^3$ m$^2$/s at the equator \citep{madec.delecluse.ea_JPO96, delecluse.madec_icol99}.
+Similar modified horizontal variations can be found with the Antarctic or Arctic sub-domain options of ORCA2 and ORCA05.
+The provided fields can either be 2d (\np{nn\_aht\_ijk\_t}\forcode{=-20}, \np{nn\_ahm\_ijk\_t}\forcode{=-20}) or 3d (\np{nn\_aht\_ijk\_t}\forcode{=-30},  \np{nn\_ahm\_ijk\_t}\forcode{=-30}). They must be given at U, V points for tracers and T, F points for momentum (see \autoref{tab:LDF_files}).
+%-------------------------------------------------TABLE---------------------------------------------------
+\begin{table}[htb]
+  \centering
+  \begin{tabular}{|l|l|l|l|}
+    \hline
+    Namelist parameter                       & Input filename                               & dimensions & variable names                      \\  \hline
+    \np{nn\_ahm\_ijk\_t}\forcode{=-20}     & \forcode{eddy_viscosity_2D.nc }            &     $(i,j)$         & \forcode{ahmt_2d, ahmf_2d}  \\  \hline
+    \np{nn\_aht\_ijk\_t}\forcode{=-20}           & \forcode{eddy_diffusivity_2D.nc }           &     $(i,j)$           & \forcode{ahtu_2d, ahtv_2d}    \\   \hline
+    \np{nn\_ahm\_ijk\_t}\forcode{=-30}        & \forcode{eddy_viscosity_3D.nc }            &     $(i,j,k)$          & \forcode{ahmt_3d, ahmf_3d}  \\  \hline
+    \np{nn\_aht\_ijk\_t}\forcode{=-30}     & \forcode{eddy_diffusivity_3D.nc }           &     $(i,j,k)$         & \forcode{ahtu_3d, ahtv_3d}    \\   \hline
+  \end{tabular}
+  \caption{Description of expected input files if mixing coefficients are read from NetCDF files}
+  \label{tab:LDF_files}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+\subsection[Constant mixing coefficients (\forcode{nn_aht_ijk_t=0}, \forcode{nn_ahm_ijk_t=0})]
+{ Constant mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{=0}, \protect\np{nn\_ahm\_ijk\_t}\forcode{=0})}
+If constant, mixing coefficients are set thanks to a velocity and a length scales ($U_{scl}$, $L_{scl}$) such that:
+\begin{equation}
+  \label{eq:LDF_constantah}
+  A_o^l = \left\{
+    \begin{aligned}
+      & \frac{1}{2} U_{scl} L_{scl}            & \text{for laplacian operator } \\
+      & \frac{1}{12} U_{scl} L_{scl}^3                    & \text{for bilaplacian operator }
+    \end{aligned}
+  \right.
+\end{equation}
+ $U_{scl}$ and $L_{scl}$ are given by the namelist parameters \np{rn\_Ud}, \np{rn\_Uv}, \np{rn\_Ld} and \np{rn\_Lv}.
+\subsection[Vertically varying mixing coefficients (\forcode{nn_aht_ijk_t=10}, \forcode{nn_ahm_ijk_t=10})]
+{Vertically varying mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{=10}, \protect\np{nn\_ahm\_ijk\_t}\forcode{=10})}
+In the vertically varying case, a hyperbolic variation of the lateral mixing coefficient is introduced in which
+the surface value is given by \autoref{eq:LDF_constantah}, the bottom value is 1/4 of the surface value,
+and the transition takes place around z=500~m with a width of 200~m.
+This profile is hard coded in module \mdl{ldfc1d\_c2d}, but can be easily modified by users.
+\subsection[Mesh size dependent mixing coefficients (\forcode{nn_aht_ijk_t=20}, \forcode{nn_ahm_ijk_t=20})]
+{Mesh size dependent mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{=20}, \protect\np{nn\_ahm\_ijk\_t}\forcode{=20})}
+In that case, the horizontal variation of the eddy coefficient depends on the local mesh size and
 the type of operator used:
 \begin{equation}
   \label{eq:title}
+  \label{eq:LDF_title}
   A_l = \left\{
     \begin{aligned}
       & \frac{\max(e_1,e_2)}{e_{max}} A_o^l           & \text{for laplacian operator } \\
       & \frac{\max(e_1,e_2)^{3}}{e_{max}^{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_{max}$ is the maximum of $e_1$ and $e_2$ taken over the whole masked ocean domain,
+and $A_o^l$ is the \np{rn\_ahm0} (momentum) or \np{rn\_aht0} (tracer) namelist parameter.
+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.
 It was introduced in the context of the DYNAMO modelling project \citep{Willebrand_al_PO01}.
 Note that such a grid scale dependance of mixing coefficients significantly increase the range of stability of
 model configurations presenting large changes in grid pacing such as global ocean models.
+It was introduced in the context of the DYNAMO modelling project \citep{willebrand.barnier.ea_PO01}.
+Note that such a grid scale dependance of mixing coefficients significantly increases the range of stability of
+model configurations presenting large changes in grid spacing such as global ocean models.
 Indeed, in such a case, a constant mixing coefficient can lead to a blow up of the model due to
 large coefficient compare to the smallest grid size (see \autoref{sec:STP_forward_imp}),
+large coefficient compare to the smallest grid size (see \autoref{sec:TD_forward_imp}),
 especially when using a bilaplacian operator.
+Other formulations can be introduced by the user for a given configuration.
+For example, in the ORCA2 global ocean model (see Configurations),
+the laplacian viscosity operator uses \np{rn\_ahm0}~= 4.10$^4$ m$^2$/s poleward of 20$^{\circ}$ north and south and
+decreases linearly to \np{rn\_aht0}~= 2.10$^3$ m$^2$/s at the equator \citep{Madec_al_JPO96, Delecluse_Madec_Bk00}.
+This modification can be found in routine \rou{ldf\_dyn\_c2d\_orca} defined in \mdl{ldfdyn\_c2d}.
+Similar modified horizontal variations can be found with the Antarctic or Arctic sub-domain options of
+ORCA2 and ORCA05 (see \&namcfg namelist).
+\subsubsection{Space varying mixing coefficients (\protect\key{traldf\_c3d} and \key{dynldf\_c3d})}
+The 3D space variation of the mixing coefficient is simply the combination of the 1D and 2D cases,
+\ie a hyperbolic tangent variation with depth associated with a grid size dependence of
+the magnitude of the coefficient.
+\subsubsection{Space and time varying mixing coefficients}
+There is no default specification of space and time varying mixing coefficient.
+The only case available is specific to the ORCA2 and ORCA05 global ocean configurations.
+It provides only a tracer mixing coefficient for eddy induced velocity (ORCA2) or both iso-neutral and
+eddy induced velocity (ORCA05) that depends on the local growth rate of baroclinic instability.
+This specification is actually used when an ORCA key and both \key{traldf\_eiv} and \key{traldf\_c2d} are defined.
+\colorbox{yellow}{CASE \np{nn\_aht\_ijk\_t} = 21 to be added}
+\subsection[Mesh size and depth dependent mixing coefficients (\forcode{nn_aht_ijk_t=30}, \forcode{nn_ahm_ijk_t=30})]
+{Mesh size and depth dependent mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{=30}, \protect\np{nn\_ahm\_ijk\_t}\forcode{=30})}
+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
+the magnitude of the coefficient.
+\subsection[Velocity dependent mixing coefficients (\forcode{nn_aht_ijk_t=31}, \forcode{nn_ahm_ijk_t=31})]
+{Flow dependent mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{=31}, \protect\np{nn\_ahm\_ijk\_t}\forcode{=31})}
+In that case, the eddy coefficient is proportional to the local velocity magnitude so that the Reynolds number $Re =  \lvert U \rvert  e / A_l$ is constant (and here hardcoded to $12$):
+\colorbox{yellow}{JC comment: The Reynolds is effectively set to 12 in the code for both operators but shouldn't it be 2 for Laplacian ?}
+\begin{equation}
+  \label{eq:LDF_flowah}
+  A_l = \left\{
+    \begin{aligned}
+      & \frac{1}{12} \lvert U \rvert e          & \text{for laplacian operator } \\
+      & \frac{1}{12} \lvert U \rvert e^3             & \text{for bilaplacian operator }
+    \end{aligned}
+  \right.
+\end{equation}
+\subsection[Deformation rate dependent viscosities (\forcode{nn_ahm_ijk_t=32})]
+{Deformation rate dependent viscosities (\protect\np{nn\_ahm\_ijk\_t}\forcode{=32})}
+This option refers to the \citep{smagorinsky_MW63} scheme which is here implemented for momentum only. Smagorinsky chose as a
+characteristic time scale $T_{smag}$ the deformation rate and for the lengthscale $L_{smag}$ the maximum wavenumber possible on the horizontal grid, e.g.:
+\begin{equation}
+  \label{eq:LDF_smag1}
+  \begin{split}
+    T_{smag}^{-1} & = \sqrt{\left( \partial_x u - \partial_y v\right)^2 + \left( \partial_y u + \partial_x v\right)^2  } \\
+    L_{smag} & = \frac{1}{\pi}\frac{e_1 e_2}{e_1 + e_2}
+  \end{split}
+\end{equation}
+Introducing a user defined constant $C$ (given in the namelist as \np{rn\_csmc}), one can deduce the mixing coefficients as follows:
+\begin{equation}
+  \label{eq:LDF_smag2}
+  A_{smag} = \left\{
+    \begin{aligned}
+      & C^2  T_{smag}^{-1}  L_{smag}^2       & \text{for laplacian operator } \\
+      & \frac{C^2}{8} T_{smag}^{-1} L_{smag}^4        & \text{for bilaplacian operator }
+    \end{aligned}
+  \right.
+\end{equation}
+For stability reasons, upper and lower limits are applied on the resulting coefficient (see \autoref{sec:TD_forward_imp}) so that:
+\begin{equation}
+  \label{eq:LDF_smag3}
+    \begin{aligned}
+      & C_{min} \frac{1}{2}   \lvert U \rvert  e    < A_{smag} < C_{max} \frac{e^2}{   8\rdt}                 & \text{for laplacian operator } \\
+      & C_{min} \frac{1}{12} \lvert U \rvert  e^3 < A_{smag} < C_{max} \frac{e^4}{64 \rdt}                 & \text{for bilaplacian operator }
+    \end{aligned}
+\end{equation}
+where $C_{min}$ and $C_{max}$ are adimensional namelist parameters given by \np{rn\_minfac} and \np{rn\_maxfac} respectively.
+\subsection{About space and time varying mixing coefficients}
 The following points are relevant when the eddy coefficient varies spatially:
 (1) the momentum diffusion operator acting along model level surfaces is written in terms of curl and
 divergent components of the horizontal current (see \autoref{subsec:PE_ldf}).
+divergent components of the horizontal current (see \autoref{subsec:MB_ldf}).
 Although the eddy coefficient could be set to different values in these two terms,
 this option is not currently available.
+this option is not currently available.
 (2) with an horizontally varying viscosity, the quadratic integral constraints on enstrophy and on the square of
 the horizontal divergence for operators acting along model-surfaces are no longer satisfied
+(\autoref{sec:dynldf_properties}).
+(3) for isopycnal diffusion on momentum or tracers, an additional purely horizontal background diffusion with
+uniform coefficient can be added by setting a non zero value of \np{rn\_ahmb0} or \np{rn\_ahtb0},
+a background horizontal eddy viscosity or diffusivity coefficient
+(namelist parameters whose default values are $0$).
+However, the technique used to compute the isopycnal slopes is intended to get rid of such a background diffusion,
+since it introduces spurious diapycnal diffusion (see \autoref{sec:LDF_slp}).
+(4) when an eddy induced advection term is used (\key{traldf\_eiv}),
+$A^{eiv}$, the eddy induced coefficient has to be defined.
+Its space variations are controlled by the same CPP variable as for the eddy diffusivity coefficient
+(\ie \key{traldf\_cNd}).
+(5) the eddy coefficient associated with a biharmonic operator must be set to a \emph{negative} value.
+(6) it is possible to use both the laplacian and biharmonic operators concurrently.
+(7) it is possible to run without explicit lateral diffusion on momentum
+(\np{ln\_dynldf\_lap}\forcode{ = .?.}\np{ln\_dynldf\_bilap}\forcode{ = .false.}).
+This is recommended when using the UBS advection scheme on momentum (\np{ln\_dynadv\_ubs}\forcode{ = .true.},
+see \autoref{subsec:DYN_adv_ubs}) and can be useful for testing purposes.
+(\autoref{sec:INVARIANTS_dynldf_properties}).
 % ================================================================
 % Eddy Induced Mixing
 % ================================================================
+\section{Eddy induced velocity (\protect\mdl{traadv\_eiv}, \protect\mdl{ldfeiv})}
+\section[Eddy induced velocity (\forcode{ln_ldfeiv=.true.})]
+{Eddy induced velocity (\protect\np{ln\_ldfeiv}\forcode{=.true.})}
 \label{sec:LDF_eiv}
+%--------------------------------------------namtra_eiv---------------------------------------------------
+\begin{listing}
+  \nlst{namtra_eiv}
+  \caption{\texttt{namtra\_eiv}}
+  \label{lst:namtra_eiv}
+\end{listing}
+%--------------------------------------------------------------------------------------------------------------
 %%gm  from Triad appendix  : to be incorporated....
 …
+}
 When Gent and McWilliams [1990] diffusion is used (\key{traldf\_eiv} defined),
+When  \citet{gent.mcwilliams_JPO90} diffusion is used (\np{ln\_ldfeiv}\forcode{=.true.}),
 an eddy induced tracer advection term is added,
 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,
+and the sum \autoref{eq:ldfslp_geo} + \autoref{eq:ldfslp_iso} in $s$-coordinates.
+The eddy induced velocity is given by:
+\begin{equation}
+  \label{eq:ldfeiv}
+\ie\ \autoref{eq:LDF_slp_geo} is used in $z$-coordinates,
+and the sum \autoref{eq:LDF_slp_geo} + \autoref{eq:LDF_slp_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:
+\begin{equation}
+  \label{eq:LDF_eiv}
   \begin{split}
     u^* & = \frac{1}{e_{2u}e_{3u}}\; \delta_k \left[e_{2u} \, A_{uw}^{eiv} \; \overline{r_{1w}}^{\,i+1/2} \right]\\
 …
   \end{split}
 \end{equation}
+where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{rn\_aeiv},
+a \textit{nam\_traldf} namelist parameter.
+The three components of the eddy induced velocity are computed and
+add to the eulerian velocity in \mdl{traadv\_eiv}.
+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.
 This has been preferred to a separate computation of the advective trends associated with the eiv velocity,
 since it allows us to take advantage of all the advection schemes offered for the tracers
 (see \autoref{sec:TRA_adv}) and not just the $2^{nd}$ order advection scheme as in
 previous releases of OPA \citep{Madec1998}.
+previous releases of OPA \citep{madec.delecluse.ea_NPM98}.
 This is particularly useful for passive tracers where \emph{positivity} of the advection scheme is of
 paramount importance.
+paramount importance.
 At the surface, lateral and bottom boundaries, the eddy induced velocity,
+and thus the advective eddy fluxes of heat and salt, are set to zero.
+and thus the advective eddy fluxes of heat and salt, are set to zero.
+The value of the eddy induced mixing coefficient and its space variation is controlled in a similar way as for lateral mixing coefficient described in the preceding subsection (\np{nn\_aei\_ijk\_t}, \np{rn\_Ue}, \np{rn\_Le} namelist parameters).
+\colorbox{yellow}{CASE \np{nn\_aei\_ijk\_t} = 21 to be added}
+In case of setting \np{ln\_traldf\_triad}\forcode{ = .true.}, a skew form of the eddy induced advective fluxes is used, which is described in \autoref{apdx:TRIADS}.
+% ================================================================
+% Mixed layer eddies
+% ================================================================
+\section[Mixed layer eddies (\forcode{ln_mle=.true.})]
+{Mixed layer eddies (\protect\np{ln\_mle}\forcode{=.true.})}
+\label{sec:LDF_mle}
+%--------------------------------------------namtra_eiv---------------------------------------------------
+\begin{listing}
+  \nlst{namtra_mle}
+  \caption{\texttt{namtra\_mle}}
+  \label{lst:namtra_mle}
+\end{listing}
+%--------------------------------------------------------------------------------------------------------------
+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}
 \biblio

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_OBS.tex

-                      r10442
+                      r11564
 \label{chap:OBS}
+Authors: D. Lea, M. Martin, K. Mogensen, A. Vidard, A. Weaver, A. Ryan, ...   % do we keep that ?
+\minitoc
+\chaptertoc
+\vfill
+\begin{figure}[b]
+\subsubsection*{Changes record}
+\begin{tabular}{l||l|m{0.65\linewidth}}
+    Release   & Author        & Modifications \\
+    {\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}  \\
+    {\em --\texttt{"}--} & {\em ... K. Mogensen, A. Vidard, A. Weaver} & {\em ---\texttt{"}---}  \\
+\end{tabular}
+\end{figure}
 \newpage
 The observation and model comparison code (OBS) reads in observation files
 (profile temperature and salinity, sea surface temperature, sea level anomaly, sea ice concentration, and velocity) and calculates an interpolated model equivalent value at the observation location and nearest model timestep.
+The observation and model comparison code, the observation operator (OBS), reads in observation files
+(profile temperature and salinity, sea surface temperature, sea level anomaly, sea ice concentration, and velocity) and calculates an interpolated model equivalent value at the observation location and nearest model time step.
 The resulting data are saved in a ``feedback'' file (or files).
 The code was originally developed for use with the NEMOVAR data assimilation code,
 but can be used for validation or verification of the model or with any other data assimilation system.
 The OBS code is called from \mdl{nemogcm} for model initialisation and to calculate the model equivalent values for observations on the 0th timestep.
 The code is then called again after each timestep from \mdl{step}.
 The code is only activated if the namelist logical \np{ln\_diaobs} is set to true.
+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 \nam{obs} namelist logical \np{ln\_diaobs} is set to true.
 For all data types a 2D horizontal interpolator or averager is needed to
 …
 For {\em in situ} profiles, a 1D vertical interpolator is needed in addition to
 provide model fields at the observation depths.
 This now works in a generalised vertical coordinate system.
 Some profile observation types (\eg tropical moored buoys) are made available as daily averaged quantities.
+This now works in a generalised vertical coordinate system.
+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.
 …
 the observation operator code can calculate equivalent night-time average model SST fields by
 setting the namelist value \np{ln\_sstnight} to true.
 Otherwise the model value from the nearest timestep to the observation time is used.
 The code is controlled by the namelist \textit{namobs}.
+Otherwise (by default) the model value from the nearest time step to the observation time is used.
+The code is controlled by the namelist \nam{obs}.
 See the following sections for more details on setting up the namelist.
 \autoref{sec:OBS_example} introduces a test example of the observation operator code including
+In \autoref{sec:OBS_example} a test example of the observation operator code is introduced, including
 where to obtain data and how to setup the namelist.
+\autoref{sec:OBS_details} introduces some more technical details of the different observation types used and
 also shows a more complete namelist.
 \autoref{sec:OBS_theory} introduces some of the theoretical aspects of the observation operator including
+In \autoref{sec:OBS_details} some more technical details of the different observation types used are introduced, and we
+also show a more complete namelist.
+In \autoref{sec:OBS_theory} some of the theoretical aspects of the observation operator are described including
 interpolation methods and running on multiple processors.
 \autoref{sec:OBS_ooo} describes the offline observation operator code.
 \autoref{sec:OBS_obsutils} introduces some utilities to help working with the files produced by the OBS code.
+In \autoref{sec:OBS_sao} the standalone observation operator code is described.
+In \autoref{sec:OBS_obsutils} we describe some utilities to help work with the files produced by the OBS code.
 % ================================================================
 …
 \label{sec:OBS_example}
 This section describes an example of running the observation operator code using
 profile data which can be freely downloaded.
 It shows how to adapt an existing run and build of NEMO to run the observation operator.
+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 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}.
   Choose observations which are valid for the period of your test run because
   the observation operator compares the model and observations for a matching date and time.
 \item Compile the OBSTOOLS code using:
+  the observation operator compares the model and observations for a matching date and time.
+\item Compile the OBSTOOLS code in the \path{tools} directory using:
 \begin{cmds}
 ./maketools -n OBSTOOLS -m [ARCH].
+./maketools -n OBSTOOLS -m [ARCH]
 \end{cmds}
+\item Convert the EN4 data into feedback format:
+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:
 \begin{cmds}
 enact2fb.exe profiles_01.nc EN.4.1.1.f.profiles.g10.YYYYMM.nc
 \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.
 …
 This can be expensive, particularly for large numbers of observations,
 setting \np{ln\_grid\_search\_lookup} allows the use of a lookup table which
 is saved into an ``xypos`` file (or files).
+is saved into an \np{cn\_gridsearch} file (or files).
 This will need to be generated the first time if it does not exist in the run directory.
 However, once produced it will significantly speed up future grid searches.
 Setting \np{ln\_grid\_global} means that the code distributes the observations evenly between processors.
 Alternatively each processor will work with observations located within the model subdomain
 (see section~\autoref{subsec:OBS_parallel}).
+(see \autoref{subsec:OBS_parallel}).
 A number of utilities are now provided to plot the feedback files, convert and recombine the files.
 These are explained in more detail in section~\autoref{sec:OBS_obsutils}.
 Utilites to convert other input data formats into the feedback format are also described in
 section~\autoref{sec:OBS_obsutils}.
+These are explained in more detail in \autoref{sec:OBS_obsutils}.
+Utilities to convert other input data formats into the feedback format are also described in
+\autoref{sec:OBS_obsutils}.
 \section{Technical details (feedback type observation file headers)}
 \label{sec:OBS_details}
 Here we show a more complete example namelist \ngn{namobs} and also show the NetCDF headers of
+Here we show a more complete example namelist \nam{obs} and also show the NetCDF headers of
 the observation files that may be used with the observation operator.
 %------------------------------------------namobs--------------------------------------------------------
+\nlst{namobs}
+\begin{listing}
+  \nlst{namobs}
+  \caption{\texttt{namobs}}
+  \label{lst:namobs}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 The observation operator code uses the "feedback" observation file format for all data types.
+The observation operator code uses the feedback observation file format for all data types.
 All the observation files must be in NetCDF format.
 Some example headers (produced using \mbox{\textit{ncdump~-h}}) for profile data, sea level anomaly and
 sea surface temperature are in the following subsections.
 \subsection{Profile feedback}
+\subsection{Profile feedback file}
 \begin{clines}
 …
 \end{clines}
 \subsection{Sea level anomaly feedback}
+\subsection{Sea level anomaly feedback file}
 \begin{clines}
 …
 \end{clines}
 The mean dynamic topography (MDT) must be provided in a separate file defined on
+To use Sea Level Anomaly (SLA) data the mean dynamic topography (MDT) must be provided in a separate file defined on
 the model grid called \ifile{slaReferenceLevel}.
 The MDT is required in order to produce the model equivalent sea level anomaly from the model sea surface height.
 …
 \end{clines}
 \subsection{Sea surface temperature feedback}
+\subsection{Sea surface temperature feedback file}
 \begin{clines}
 …
 the model equivalent of the observation is calculated by interpolating from
 the four surrounding grid points to the observation location.
 Some satellite observations (\eg microwave satellite SST data, or satellite SSS data) have a footprint which
+Some satellite observations (\eg\ microwave satellite SST data, or satellite SSS data) have a footprint which
 is similar in size or larger than the model grid size (particularly when the grid size is small).
 In those cases the model counterpart should be calculated by averaging the model grid points over
 the same size as the footprint.
 NEMO therefore has the capability to specify either an interpolation or an averaging
 (for surface observation types only).
+\NEMO\ therefore has the capability to specify either an interpolation or an averaging
+(for surface observation types only).
 The main namelist option associated with the interpolation/averaging is \np{nn\_2dint}.
 …
 \item \np{nn\_2dint}\forcode{ = 4}: Polynomial interpolation
 \item \np{nn\_2dint}\forcode{ = 5}: Radial footprint averaging with diameter specified in the namelist as
   \np{rn\_???\_avglamscl} in degrees or metres (set using \np{ln\_???\_fp\_indegs})
+  \texttt{rn\_[var]\_avglamscl} in degrees or metres (set using \texttt{ln\_[var]\_fp\_indegs})
 \item \np{nn\_2dint}\forcode{ = 6}: Rectangular footprint averaging with E/W and N/S size specified in
   the namelist as \np{rn\_???\_avglamscl} and \np{rn\_???\_avgphiscl} in degrees or metres
   (set using \np{ln\_???\_fp\_indegs})
+  the namelist as \texttt{rn\_[var]\_avglamscl} and \texttt{rn\_[var]\_avgphiscl} in degrees or metres
+  (set using \texttt{ln\_[var]\_fp\_indegs})
 \end{itemize}
 The ??? in the last two options indicate these options should be specified for each observation type for
+Replace \texttt{[var]} in the last two options with the observation type (sla, sst, sss or sic) for
 which the averaging is to be performed (see namelist example above).
 The \np{nn\_2dint} default option can be overridden for surface observation types using
 namelist values \np{nn\_2dint\_???} where ??? is one of sla,sst,sss,sic.
 Below is some more detail on the various options for interpolation and averaging available in NEMO.
+namelist values \texttt{nn\_2dint\_[var]} where \texttt{[var]} is the observation type.
+Below is some more detail on the various options for interpolation and averaging available in \NEMO.
 \subsubsection{Horizontal interpolation}
+Consider an observation point ${\rm P}$ with with longitude and latitude $({\lambda_{}}_{\rm P}, \phi_{\rm P})$ and
+the four nearest neighbouring model grid points ${\rm A}$, ${\rm B}$, ${\rm C}$ and ${\rm D}$ with
+longitude and latitude ($\lambda_{\rm A}$, $\phi_{\rm A}$),($\lambda_{\rm B}$, $\phi_{\rm B}$) etc.
+All horizontal interpolation methods implemented in NEMO estimate the value of a model variable $x$ at point $P$ as
+a weighted linear combination of the values of the model variables at the grid points ${\rm A}$, ${\rm B}$ etc.:
+Consider an observation point ${\mathrm P}$ with longitude and latitude (${\lambda_{}}_{\mathrm P}$, $\phi_{\mathrm P}$) and
+the four nearest neighbouring model grid points ${\mathrm A}$, ${\mathrm B}$, ${\mathrm C}$ and ${\mathrm D}$ with
+longitude and latitude ($\lambda_{\mathrm A}$, $\phi_{\mathrm A}$),($\lambda_{\mathrm B}$, $\phi_{\mathrm B}$) etc.
+All horizontal interpolation methods implemented in \NEMO\ estimate the value of a model variable $x$ at point $P$ as
+a weighted linear combination of the values of the model variables at the grid points ${\mathrm A}$, ${\mathrm B}$ etc.:
 \begin{align*}
   {x_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} &
                                                    \frac{1}{w} \left( {w_{}}_{\rm A} {x_{}}_{\rm A} +
                                                    {w_{}}_{\rm B} {x_{}}_{\rm B} +
                                                    {w_{}}_{\rm C} {x_{}}_{\rm C} +
                                                    {w_{}}_{\rm D} {x_{}}_{\rm D} \right)
+  {x_{}}_{\mathrm P} =
+\frac{1}{w} \left( {w_{}}_{\mathrm A} {x_{}}_{\mathrm A} +
+{w_{}}_{\mathrm B} {x_{}}_{\mathrm B} +
+{w_{}}_{\mathrm C} {x_{}}_{\mathrm C} +
+{w_{}}_{\mathrm D} {x_{}}_{\mathrm D} \right)
 \end{align*}
+where ${w_{}}_{\rm A}$, ${w_{}}_{\rm B}$ etc. are the respective weights for the model field at
+points ${\rm A}$, ${\rm B}$ etc., and $w = {w_{}}_{\rm A} + {w_{}}_{\rm B} + {w_{}}_{\rm C} + {w_{}}_{\rm D}$.
+where ${w_{}}_{\mathrm A}$, ${w_{}}_{\mathrm B}$ etc. are the respective weights for the model field at
+points ${\mathrm A}$, ${\mathrm B}$ etc., and $w = {w_{}}_{\mathrm A} + {w_{}}_{\mathrm B} + {w_{}}_{\mathrm C} + {w_{}}_{\mathrm D}$.
 Four different possibilities are available for computing the weights.
 …
 \begin{enumerate}
 \item[1.] {\bf Great-Circle distance-weighted interpolation.}
+\item[1.] {\bfseries Great-Circle distance-weighted interpolation.}
   The weights are computed as a function of the great-circle distance $s(P, \cdot)$ between $P$ and
   the model grid points $A$, $B$ etc.
+  For example, the weight given to the field ${x_{}}_{\rm A}$ is specified as the product of the distances
+  from ${\rm P}$ to the other points:
+  \begin{align*}
+    {w_{}}_{\rm A} = s({\rm P}, {\rm B}) \, s({\rm P}, {\rm C}) \, s({\rm P}, {\rm D})
+  \end{align*}
+  where
+  \begin{align*}
+    s\left ({\rm P}, {\rm M} \right )
+     & \hspace{-2mm} = \hspace{-2mm} &
+      \cos^{-1} \! \left\{
+               \sin {\phi_{}}_{\rm P} \sin {\phi_{}}_{\rm M}
+             + \cos {\phi_{}}_{\rm P} \cos {\phi_{}}_{\rm M}
+               \cos ({\lambda_{}}_{\rm M} - {\lambda_{}}_{\rm P})
+  For example, the weight given to the field ${x_{}}_{\mathrm A}$ is specified as the product of the distances
+  from ${\mathrm P}$ to the other points:
+  \begin{alignat*}{2}
+    {w_{}}_{\mathrm A} = s({\mathrm P}, {\mathrm B}) \, s({\mathrm P}, {\mathrm C}) \, s({\mathrm P}, {\mathrm D})
+  \end{alignat*}
+  where
+  \begin{alignat*}{2}
+    s\left({\mathrm P}, {\mathrm M} \right) & = & \hspace{0.25em} \cos^{-1} \! \left\{
+               \sin {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm M}
+             + \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm M}
+               \cos ({\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P})
                    \right\}
+   \end{align*}
+   \end{alignat*}
    and $M$ corresponds to $B$, $C$ or $D$.
    A more stable form of the great-circle distance formula for small distances ($x$ near 1)
+   involves the arcsine function (\eg see p.~101 of \citet{Daley_Barker_Bk01}:
+   \begin{align*}
+     s\left( {\rm P}, {\rm M} \right) & \hspace{-2mm} = \hspace{-2mm} & \sin^{-1} \! \left\{ \sqrt{ 1 - x^2 } \right\}
+   \end{align*}
+   involves the arcsine function (\eg\ see p.~101 of \citet{daley.barker_bk01}:
+   \begin{alignat*}{2}
+     s\left( {\mathrm P}, {\mathrm M} \right) = \sin^{-1} \! \left\{ \sqrt{ 1 - x^2 } \right\}
+   \end{alignat*}
    where
+   \begin{align*}
+     x & \hspace{-2mm} = \hspace{-2mm} &
+                                         {a_{}}_{\rm M} {a_{}}_{\rm P} + {b_{}}_{\rm M} {b_{}}_{\rm P} + {c_{}}_{\rm M} {c_{}}_{\rm P}
+   \end{align*}
+   and
+   \begin{align*}
+      {a_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\rm M}, \\
+      {a_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\rm P}, \\
+      {b_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm M} \cos {\phi_{}}_{\rm M}, \\
+      {b_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm P} \cos {\phi_{}}_{\rm P}, \\
+      {c_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm M} \sin {\phi_{}}_{\rm M}, \\
+      {c_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm P} \sin {\phi_{}}_{\rm P}.
+  \end{align*}
+\item[2.] {\bf Great-Circle distance-weighted interpolation with small angle approximation.}
+   \begin{alignat*}{2}
+     x = {a_{}}_{\mathrm M} {a_{}}_{\mathrm P} + {b_{}}_{\mathrm M} {b_{}}_{\mathrm P} + {c_{}}_{\mathrm M} {c_{}}_{\mathrm P}
+   \end{alignat*}
+   and
+   \begin{alignat*}{3}
+   & {a_{}}_{\mathrm M} & = && \quad \sin {\phi_{}}_{\mathrm M}, \\
+   & {a_{}}_{\mathrm P} & = && \quad \sin {\phi_{}}_{\mathrm P}, \\
+   & {b_{}}_{\mathrm M} & = && \quad \cos {\phi_{}}_{\mathrm M} \cos {\phi_{}}_{\mathrm M}, \\
+   & {b_{}}_{\mathrm P} & = && \quad \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm P}, \\
+   & {c_{}}_{\mathrm M} & = && \quad \cos {\phi_{}}_{\mathrm M} \sin {\phi_{}}_{\mathrm M}, \\
+   & {c_{}}_{\mathrm P} & = && \quad \cos {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm P}.
+   \end{alignat*}
+\item[2.] {\bfseries Great-Circle distance-weighted interpolation with small angle approximation.}
   Similar to the previous interpolation but with the distance $s$ computed as
+  \begin{align*}
+    s\left( {\rm P}, {\rm M} \right)
+    & \hspace{-2mm} = \hspace{-2mm} &
+                                      \sqrt{ \left( {\phi_{}}_{\rm M} - {\phi_{}}_{\rm P} \right)^{2}
+                                      + \left( {\lambda_{}}_{\rm M} - {\lambda_{}}_{\rm P} \right)^{2}
+                                      \cos^{2} {\phi_{}}_{\rm M} }
+  \end{align*}
+  \begin{alignat*}{2}
+    s\left( {\mathrm P}, {\mathrm M} \right)
+    & = & \sqrt{ \left( {\phi_{}}_{\mathrm M} - {\phi_{}}_{\mathrm P} \right)^{2}
+                                      + \left( {\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P} \right)^{2}
+                                      \cos^{2} {\phi_{}}_{\mathrm M} }
+  \end{alignat*}
   where $M$ corresponds to $A$, $B$, $C$ or $D$.
 \item[3.] {\bf Bilinear interpolation for a regular spaced grid.}
+\item[3.] {\bfseries Bilinear interpolation for a regular spaced grid.}
   The interpolation is split into two 1D interpolations in the longitude and latitude directions, respectively.
 \item[4.] {\bf Bilinear remapping interpolation for a general grid.}
+\item[4.] {\bfseries Bilinear remapping interpolation for a general grid.}
   An iterative scheme that involves first mapping a quadrilateral cell into
   a cell with coordinates (0,0), (1,0), (0,1) and (1,1).
   This method is based on the SCRIP interpolation package \citep{Jones_1998}.
+  This method is based on the \href{https://github.com/SCRIP-Project/SCRIP}{SCRIP interpolation package}.
 \end{enumerate}
 …
 \item The standard grid-searching code is used to find the nearest model grid point to the observation location
   (see next subsection).
+\item The maximum number of grid points is calculated in the local grid domain for which
+  the averaging is likely need to cover.
+\item The lats/longs of the grid points surrounding the nearest model grid box are extracted using
+  existing mpi routines.
+\item The maximum number of grid points required for that observation in each local grid domain is calculated. Some of these points may later turn out to have zero weight depending on the shape of the footprint.
+\item The longitudes and latitudes of the grid points surrounding the nearest model grid box are extracted using
+  existing MPI routines.
 \item The weights for each grid point associated with each observation are calculated,
   either for radial or rectangular footprints.
 …
 Examples of the weights calculated for an observation with rectangular and radial footprints are shown in
 Figs.~\autoref{fig:obsavgrec} and~\autoref{fig:obsavgrad}.
+\autoref{fig:OBS_avgrec} and~\autoref{fig:OBS_avgrad}.
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}
+  \begin{center}
+    \includegraphics[width=0.90\textwidth]{Fig_OBS_avg_rec}
+    \caption{
+      \protect\label{fig:obsavgrec}
+      Weights associated with each model grid box (blue lines and numbers)
+      for an observation at -170.5\deg{E}, 56.0\deg{N} with a rectangular footprint of 1\deg x 1\deg.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_OBS_avg_rec}
+  \caption[Observational weights with a rectangular footprint]{
+    Weights associated with each model grid box (blue lines and numbers)
+    for an observation at -170.5\deg{E}, 56.0\deg{N} with a rectangular footprint of 1\deg\ x 1\deg.}
+  \label{fig:OBS_avgrec}
+\end{figure}
+% >>>>>>>>>>>>>>>>>>>>>>>>>>>>
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_OBS_avg_rad}
+  \caption[Observational weights with a radial footprint]{
+    Weights associated with each model grid box (blue lines and numbers)
+    for an observation at -170.5\deg{E}, 56.0\deg{N} with a radial footprint with diameter 1\deg.}
+  \label{fig:OBS_avgrad}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-\begin{figure}
-  \begin{center}
-    \includegraphics[width=0.90\textwidth]{Fig_OBS_avg_rad}
-    \caption{
-      \protect\label{fig:obsavgrad}
-      Weights associated with each model grid box (blue lines and numbers)
-      for an observation at -170.5\deg{E}, 56.0\deg{N} with a radial footprint with diameter 1\deg.
+    }
-  \end{center}
-\end{figure}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \subsection{Grid search}
 For many grids used by the NEMO model, such as the ORCA family, the horizontal grid coordinates $i$ and $j$ are not simple functions of latitude and longitude.
+For many grids used by the \NEMO\ model, such as the ORCA family, the horizontal grid coordinates $i$ and $j$ are not simple functions of latitude and longitude.
 Therefore, it is not always straightforward to determine the grid points surrounding any given observational position.
 Before the interpolation can be performed, a search algorithm is then required to determine the corner points of
+Before the interpolation can be performed, a search algorithm is then required to determine the corner points of
 the quadrilateral cell in which the observation is located.
 This is the most difficult and time consuming part of the 2D interpolation procedure.
+This is the most difficult and time consuming part of the 2D interpolation procedure.
 A robust test for determining if an observation falls within a given quadrilateral cell is as follows.
 Let ${\rm P}({\lambda_{}}_{\rm P} ,{\phi_{}}_{\rm P} )$ denote the observation point,
 and let ${\rm A}({\lambda_{}}_{\rm A} ,{\phi_{}}_{\rm A} )$, ${\rm B}({\lambda_{}}_{\rm B} ,{\phi_{}}_{\rm B} )$,
 ${\rm C}({\lambda_{}}_{\rm C} ,{\phi_{}}_{\rm C} )$ and ${\rm D}({\lambda_{}}_{\rm D} ,{\phi_{}}_{\rm D} )$
 denote the bottom left, bottom right, top left and top right corner points of the cell, respectively.
 To determine if P is inside the cell, we verify that the cross-products
+Let ${\mathrm P}({\lambda_{}}_{\mathrm P} ,{\phi_{}}_{\mathrm P} )$ denote the observation point,
+and let ${\mathrm A}({\lambda_{}}_{\mathrm A} ,{\phi_{}}_{\mathrm A} )$, ${\mathrm B}({\lambda_{}}_{\mathrm B} ,{\phi_{}}_{\mathrm B} )$,
+${\mathrm C}({\lambda_{}}_{\mathrm C} ,{\phi_{}}_{\mathrm C} )$ and ${\mathrm D}({\lambda_{}}_{\mathrm D} ,{\phi_{}}_{\mathrm D} )$
+denote the bottom left, bottom right, top left and top right corner points of the cell, respectively.
+To determine if P is inside the cell, we verify that the cross-products
 \begin{align*}
   \begin{array}{lllll}
     {{\bf r}_{}}_{\rm PA} \times {{\bf r}_{}}_{\rm PC}
     & = & [({\lambda_{}}_{\rm A}\; -\; {\lambda_{}}_{\rm P} )
           ({\phi_{}}_{\rm C}   \; -\; {\phi_{}}_{\rm P} )
           - ({\lambda_{}}_{\rm C}\; -\; {\lambda_{}}_{\rm P} )
           ({\phi_{}}_{\rm A}   \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\
     {{\bf r}_{}}_{\rm PB} \times {{\bf r}_{}}_{\rm PA}
     & = & [({\lambda_{}}_{\rm B}\; -\; {\lambda_{}}_{\rm P} )
           ({\phi_{}}_{\rm A}   \; -\; {\phi_{}}_{\rm P} )
           - ({\lambda_{}}_{\rm A}\; -\; {\lambda_{}}_{\rm P} )
           ({\phi_{}}_{\rm B}   \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\
     {{\bf r}_{}}_{\rm PC} \times {{\bf r}_{}}_{\rm PD}
     & = & [({\lambda_{}}_{\rm C}\; -\; {\lambda_{}}_{\rm P} )
           ({\phi_{}}_{\rm D}   \; -\; {\phi_{}}_{\rm P} )
           - ({\lambda_{}}_{\rm D}\; -\; {\lambda_{}}_{\rm P} )
           ({\phi_{}}_{\rm C}   \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\
     {{\bf r}_{}}_{\rm PD} \times {{\bf r}_{}}_{\rm PB}
     & = & [({\lambda_{}}_{\rm D}\; -\; {\lambda_{}}_{\rm P} )
           ({\phi_{}}_{\rm B}   \; -\; {\phi_{}}_{\rm P} )
           - ({\lambda_{}}_{\rm B}\; -\; {\lambda_{}}_{\rm P} )
           ({\phi_{}}_{\rm D}  \;  - \; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\
+    {{\mathbf r}_{}}_{\mathrm PA} \times {{\mathbf r}_{}}_{\mathrm PC}
+    & = & [({\lambda_{}}_{\mathrm A}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm C}   \; -\; {\phi_{}}_{\mathrm P} )
+          - ({\lambda_{}}_{\mathrm C}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm A}   \; -\; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\
+    {{\mathbf r}_{}}_{\mathrm PB} \times {{\mathbf r}_{}}_{\mathrm PA}
+    & = & [({\lambda_{}}_{\mathrm B}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm A}   \; -\; {\phi_{}}_{\mathrm P} )
+          - ({\lambda_{}}_{\mathrm A}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm B}   \; -\; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\
+    {{\mathbf r}_{}}_{\mathrm PC} \times {{\mathbf r}_{}}_{\mathrm PD}
+    & = & [({\lambda_{}}_{\mathrm C}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm D}   \; -\; {\phi_{}}_{\mathrm P} )
+          - ({\lambda_{}}_{\mathrm D}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm C}   \; -\; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\
+    {{\mathbf r}_{}}_{\mathrm PD} \times {{\mathbf r}_{}}_{\mathrm PB}
+    & = & [({\lambda_{}}_{\mathrm D}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm B}   \; -\; {\phi_{}}_{\mathrm P} )
+          - ({\lambda_{}}_{\mathrm B}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm D}  \;  - \; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\
   \end{array}
   % \label{eq:cross}
+  % \label{eq:OBS_cross}
 \end{align*}
 point in the opposite direction to the unit normal $\widehat{\bf k}$
 (\ie that the coefficients of $\widehat{\bf k}$ are negative),
 where ${{\bf r}_{}}_{\rm PA}$, ${{\bf r}_{}}_{\rm PB}$, etc. correspond to
+point in the opposite direction to the unit normal $\widehat{\mathbf k}$
+(\ie\ that the coefficients of $\widehat{\mathbf k}$ are negative),
+where ${{\mathbf r}_{}}_{\mathrm PA}$, ${{\mathbf r}_{}}_{\mathrm PB}$, etc. correspond to
 the vectors between points P and A, P and B, etc..
 The method used is similar to the method used in the SCRIP interpolation package \citep{Jones_1998}.
+The method used is similar to the method used in the \href{https://github.com/SCRIP-Project/SCRIP}{SCRIP interpolation package}.
 In order to speed up the grid search, there is the possibility to construct a lookup table for a user specified resolution.
 …
 be searched for on a regular grid.
 For each observation position, the closest point on the regular grid of this position is computed and
 the $i$ and $j$ ranges of this point searched to determine the precise four points surrounding the observation.
+the $i$ and $j$ ranges of this point searched to determine the precise four points surrounding the observation.
 \subsection{Parallel aspects of horizontal interpolation}
 …
 For horizontal interpolation, there is the basic problem that
 the observations are unevenly distributed on the globe.
 In numerical models, it is common to divide the model grid into subgrids (or domains) where
+In \NEMO\ the model grid is divided into subgrids (or domains) where
 each subgrid is executed on a single processing element with explicit message passing for
 exchange of information along the domain boundaries when running on a massively parallel processor (MPP) system.
+This approach is used by \NEMO.
+For observations there is no natural distribution since the observations are not equally distributed on the globe.
+For observations there is no natural distribution since the observations are not equally distributed on the globe.
 Two options have been made available:
 ) geographical distribution;
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}
+  \begin{center}
+    \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_ASM_obsdist_local}
+    \caption{
+      \protect\label{fig:obslocal}
+      Example of the distribution of observations with the geographical distribution of observational data.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_ASM_obsdist_local}
+  \caption[Observations with the geographical distribution]{
+    Example of the distribution of observations with
+    the geographical distribution of observational data}
+  \label{fig:OBS_local}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 This is the simplest option in which the observations are distributed according to
 the domain of the grid-point parallelization.
 \autoref{fig:obslocal} shows an example of the distribution of the {\em in situ} data on processors with
 a different colour for each observation on a given processor for a 4 $\times$ 2 decomposition with ORCA2.
+\autoref{fig:OBS_local} shows an example of the distribution of the {\em in situ} data on processors with
+a different colour for each observation on a given processor for a 4 $\times$ 2 decomposition with ORCA2.
 The grid-point domain decomposition is clearly visible on the plot.
 The advantage of this approach is that all information needed for horizontal interpolation is available without
 any MPP communication.
 Of course, this is under the assumption that we are only using a $2 \times 2$ grid-point stencil for
 the interpolation (\eg bilinear interpolation).
+This is under the assumption that we are dealing with point observations and only using a $2 \times 2$ grid-point stencil for
+the interpolation (\eg\ bilinear interpolation).
 For higher order interpolation schemes this is no longer valid.
 A disadvantage with the above scheme is that the number of observations on each processor can be very different.
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}
+  \begin{center}
+    \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_ASM_obsdist_global}
+    \caption{
+      \protect\label{fig:obsglobal}
+      Example of the distribution of observations with the round-robin distribution of observational data.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_ASM_obsdist_global}
+  \caption[Observations with the round-robin distribution]{
+    Example of the distribution of observations with
+    the round-robin distribution of observational data.}
+  \label{fig:OBS_global}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 use message passing in order to retrieve the stencil for interpolation.
 The simplest distribution of the observations is to distribute them using a round-robin scheme.
 \autoref{fig:obsglobal} shows the distribution of the {\em in situ} data on processors for
+\autoref{fig:OBS_global} shows the distribution of the {\em in situ} data on processors for
 the round-robin distribution of observations with a different colour for each observation on a given processor for
 a 4 $\times$ 2 decomposition with ORCA2 for the same input data as in \autoref{fig:obslocal}.
+a 4 $\times$ 2 decomposition with ORCA2 for the same input data as in \autoref{fig:OBS_local}.
 The observations are now clearly randomly distributed on the globe.
 In order to be able to perform horizontal interpolation in this case,
 …
 At the bottom boundary, this is done using the land-ocean mask.
+For profile observation types we do both vertical and horizontal interpolation. \NEMO\ has a generalised vertical coordinate system this means the vertical level depths can vary with location. Therefore, it is necessary first to perform vertical interpolation of the model value to the observation depths for each of the four surrounding grid points. After this the model values, at these points, at the observation depth, are horizontally interpolated to the observation location.
 \newpage
 % ================================================================
 % Offline observation operator documentation
+% Standalone observation operator documentation
 % ================================================================
 %\usepackage{framed}
 \section{Offline observation operator}
 \label{sec:OBS_ooo}
+\section{Standalone observation operator}
+\label{sec:OBS_sao}
 \subsection{Concept}
+The obs oper maps model variables to observation space.
+It is possible to apply this mapping without running the model.
+The software which performs this functionality is known as the \textbf{offline obs oper}.
+The obs oper is divided into three stages.
+An initialisation phase, an interpolation phase and an output phase.
+The implementation of which is outlined in the previous sections.
+During the interpolation phase the offline obs oper populates the model arrays by
+reading saved model fields from disk.
+There are two ways of exploiting this offline capacity.
+The observation operator maps model variables to observation space. This is normally done while the model is running, i.e. online, it is possible to apply this mapping offline without running the model with the \textbf{standalone observation operator} (SAO). The process is divided into an initialisation phase, an interpolation phase and an output phase.
+During the interpolation phase the SAO populates the model arrays by
+reading saved model fields from disk. The interpolation and the output phases use the same OBS code described in the preceding sections.
+There are two ways of exploiting the standalone capacity.
 The first is to mimic the behaviour of the online system by supplying model fields at
 regular intervals between the start and the end of the run.
 This approach results in a single model counterpart per observation.
 This kind of usage produces feedback files the same file format as the online obs oper.
 The second is to take advantage of the offline setting in which
 multiple model counterparts can be calculated per observation.
+This kind of usage produces feedback files the same file format as the online observation operator.
+The second is to take advantage of the ability to run offline by calculating
+multiple model counterparts for each observation.
 In this case it is possible to consider all forecasts verifying at the same time.
+By forecast, I mean any method which produces an estimate of physical reality which is not an observed value.
+In the case of class 4 files this means forecasts, analyses, persisted analyses and
+climatological values verifying at the same time.
+Although the class 4 file format doesn't account for multiple ensemble members or
+multiple experiments per observation, it is possible to include these components in the same or multiple files.
+By forecast, we mean any method which produces an estimate of physical reality which is not an observed value.
 %--------------------------------------------------------------------------------------------------------
 % offline_oper.exe
+% sao.exe
 %--------------------------------------------------------------------------------------------------------
 \subsection{Using the offline observation operator}
+\subsection{Using the standalone observation operator}
 \subsubsection{Building}
 In addition to \emph{OPA\_SRC} the offline obs oper requires the inclusion of the \emph{OOO\_SRC} directory.
 \emph{OOO\_SRC} contains a replacement \mdl{nemo} and \mdl{nemogcm} which
+In addition to \emph{OPA\_SRC} the SAO requires the inclusion of the \emph{SAO\_SRC} directory.
+\emph{SAO\_SRC} contains a replacement \mdl{nemo} and \mdl{nemogcm} which
 overwrites the resultant \textbf{nemo.exe}.
 This is the approach taken by \emph{SAS\_SRC} and \emph{OFF\_SRC}.
+Note this a similar approach to that taken by the standalone surface scheme \emph{SAS\_SRC} and the offline TOP model \emph{OFF\_SRC}.
 %--------------------------------------------------------------------------------------------------------
 % Running
+% Running
 %--------------------------------------------------------------------------------------------------------
 \subsubsection{Running}
+The simplest way to use the executable is to edit and append the \textbf{ooo.nml} namelist to
+a full NEMO namelist and then to run the executable as if it were nemo.exe.
+\subsubsection{Quick script}
+A useful Python utility to control the namelist options can be found in \textbf{OBSTOOLS/OOO}.
+The functions which locate model fields and observation files can be manually specified.
+The package can be installed by appropriate use of the included setup.py script.
+Documentation can be auto-generated by Sphinx by running \emph{make html} in the \textbf{doc} directory.
+The simplest way to use the executable is to edit and append the \textbf{sao.nml} namelist to
+a full \NEMO\ namelist and then to run the executable as if it were nemo.exe.
 %--------------------------------------------------------------------------------------------------------
 % Configuration section
 %--------------------------------------------------------------------------------------------------------
+\subsection{Configuring the offline observation operator}
+The observation files and settings understood by \textbf{namobs} have been outlined in the online obs oper section.
+In addition there are two further namelists wich control the operation of the offline obs oper.
+\textbf{namooo} which controls the input model fields and \textbf{namcl4} which
+controls the production of class 4 files.
+\subsection{Configuring the standalone observation operator}
+The observation files and settings understood by \nam{obs} have been outlined in the online observation operator section.
+In addition is a further namelist \nam{sao} which used to set the input model fields for the SAO
 \subsubsection{Single field}
 In offline mode model arrays are populated at appropriate time steps via input files.
 At present, \textbf{tsn} and \textbf{sshn} are populated by the default read routines.
+In the SAO the model arrays are populated at appropriate time steps via input files.
+At present, \textbf{tsn} and \textbf{sshn} are populated by the default read routines.
 These routines will be expanded upon in future versions to allow the specification of any model variable.
 As such, input files must be global versions of the model domain with
 \textbf{votemper}, \textbf{vosaline} and optionally \textbf{sshn} present.
 For each field read there must be an entry in the \textbf{namooo} namelist specifying
+For each field read there must be an entry in the \nam{sao} namelist specifying
 the name of the file to read and the index along the \emph{time\_counter}.
 For example, to read the second time counter from a single file the namelist would be.
 …
 \begin{forlines}
 !----------------------------------------------------------------------
 !       namooo Offline obs_oper namelist
+!       namsao Standalone obs_oper namelist
 !----------------------------------------------------------------------
 !   ooo_files    specifies the files containing the model counterpart
 !   nn_ooo_idx   specifies the time_counter index within the model file
 &namooo
    ooo_files = "foo.nc"
    nn_ooo_idx = 2
+!   sao_files    specifies the files containing the model counterpart
+!   nn_sao_idx   specifies the time_counter index within the model file
+&namsao
+   sao_files = "foo.nc"
+   nn_sao_idx = 2
+/
 \end{forlines}
 …
 \subsubsection{Multiple fields per run}
 Model field iteration is controlled via \textbf{nn\_ooo\_freq} which
+Model field iteration is controlled via \textbf{nn\_sao\_freq} which
 specifies the number of model steps at which the next field gets read.
 For example, if 12 hourly fields are to be interpolated in a setup where 288 steps equals 24 hours.
 …
 \begin{forlines}
 !----------------------------------------------------------------------
 !       namooo Offline obs_oper namelist
+!       namsao Standalone obs_oper namelist
 !----------------------------------------------------------------------
 !   ooo_files    specifies the files containing the model counterpart
 !   nn_ooo_idx   specifies the time_counter index within the model file
 !   nn_ooo_freq  specifies number of time steps between read operations
 &namooo
    ooo_files = "foo.nc" "foo.nc"
    nn_ooo_idx = 1 2
    nn_ooo_freq = 144
+!   sao_files    specifies the files containing the model counterpart
+!   nn_sao_idx   specifies the time_counter index within the model file
+!   nn_sao_freq  specifies number of time steps between read operations
+&namsao
+   sao_files = "foo.nc" "foo.nc"
+   nn_sao_idx = 1 2
+   nn_sao_freq = 144
+/
 \end{forlines}
 …
 %\end{framed}
 It is easy to see how a collection of fields taken fron a number of files at different indices can be combined at
+A collection of fields taken from a number of files at different indices can be combined at
 a particular frequency in time to generate a pseudo model evolution.
+As long as all that is needed is a single model counterpart at a regular interval then
+namooo is all that needs to be edited.
+However, a far more interesting approach can be taken in which multiple forecasts, analyses, persisted analyses and
+climatologies are considered against the same set of observations.
+For this a slightly more complicated approach is needed.
+It is referred to as \emph{Class 4} since it is the fourth metric defined by the GODAE intercomparison project.
+%--------------------------------------------------------------------------------------------------------
+% Class 4 file section
+%--------------------------------------------------------------------------------------------------------
+\subsubsection{Multiple model counterparts per observation a.k.a Class 4}
+A generalisation of feedback files to allow multiple model components per observation.
+For a single observation, as well as previous forecasts verifying at the same time
+there are also analyses, persisted analyses and climatologies.
+The above namelist performs two basic functions.
+It organises the fields given in \textbf{namooo} into groups so that observations can be matched up multiple times.
+It also controls the metadata and the output variable of the class 4 file when a write routine is called.
+%\begin{framed}
+\textbf{Note: ln\_cl4} must be set to \forcode{.true.} in \textbf{namobs} to use class 4 outputs.
+%\end{framed}
+\subsubsection{Class 4 naming convention}
+The standard class 4 file naming convention is as follows.
+\noindent
+\linebreak
+\textbf{\$\{prefix\}\_\$\{yyyymmdd\}\_\$\{sys\}\_\$\{cfg\}\_\$\{vn\}\_\$\{kind\}\_\$\{nproc\}}.nc
+\noindent
+\linebreak
+Much of the namelist is devoted to specifying this convention.
+The following namelist settings control the elements of the output file names.
+Each should be specified as a single string of character data.
+\begin{description}
+\item[cl4\_prefix]
+  Prefix for class 4 files \eg class4
+\item[cl4\_date]
+  YYYYMMDD validity date
+\item[cl4\_sys]
+  The name of the class 4 model system \eg FOAM
+\item[cl4\_cfg]
+  The name of the class 4 model configuration \eg orca025
+\item[cl4\_vn]
+  The name of the class 4 model version \eg 12.0
+\end{description}
+\noindent
+The kind is specified by the observation type internally to the obs oper.
+The processor number is specified internally in NEMO.
+\subsubsection{Class 4 file global attributes}
+Global attributes necessary to fulfill the class 4 file definition.
+These are also useful pieces of information when collaborating with external partners.
+\begin{description}
+\item[cl4\_contact]
+  Contact email for class 4 files.
+\item[cl4\_inst]
+  The name of the producers institution.
+\item[cl4\_cfg]
+  The name of the class 4 model configuration \eg orca025
+\item[cl4\_vn]
+  The name of the class 4 model version \eg 12.0
+\end{description}
+\noindent
+The obs\_type, creation date and validity time are specified internally to the obs oper.
+\subsubsection{Class 4 model counterpart configuration}
+As seen previously it is possible to perform a single sweep of the obs oper and
+specify a collection of model fields equally spaced along that sweep.
+In the class 4 case the single sweep is replaced with multiple sweeps and
+a certain ammount of book keeping is needed to ensure each model counterpart makes its way to
+the correct piece of memory in the output files.
+\noindent
+\linebreak
+In terms of book keeping, the offline obs oper needs to know how many full sweeps need to be performed.
+This is specified via the \textbf{cl4\_match\_len} variable and
+is the total number of model counterparts per observation.
+For example, a 3 forecasts plus 3 persistence fields plus an analysis field would be 7 counterparts per observation.
+\begin{forlines}
+   cl4_match_len = 7
+\end{forlines}
+Then to correctly allocate a class 4 file the forecast axis must be defined.
+This is controlled via \textbf{cl4\_fcst\_len}, which in out above example would be 3.
+\begin{forlines}
+   cl4_fcst_len = 3
+\end{forlines}
+Then for each model field it is necessary to designate what class 4 variable and index along
+the forecast dimension the model counterpart should be stored in the output file.
+As well as a value for that lead time in hours, this will be useful when interpreting the data afterwards.
+\begin{forlines}
+   cl4_vars = "forecast" "forecast" "forecast" "persistence" "persistence"
+              "persistence" "best_estimate"
+   cl4_fcst_idx = 1 2 3 1 2 3 1
+   cl4_leadtime = 12 36 60
+\end{forlines}
+In terms of files and indices of fields inside each file the class 4 approach makes use of
+the \textbf{namooo} namelist.
+If our fields are in separate files with a single field per file our example inputs will be specified.
+\begin{forlines}
+   ooo_files = "F.1.nc" "F.2.nc" "F.3.nc" "P.1.nc" "P.2.nc" "P.3.nc" "A.1.nc"
+   nn_ooo_idx = 1 1 1 1 1 1 1
+\end{forlines}
+When we combine all of the naming conventions, global attributes and i/o instructions the class 4 namelist becomes.
+\begin{forlines}
+!----------------------------------------------------------------------
+!       namooo Offline obs_oper namelist
+!----------------------------------------------------------------------
+!   ooo_files    specifies the files containing the model counterpart
+!   nn_ooo_idx   specifies the time_counter index within the model file
+!   nn_ooo_freq  specifies number of time steps between read operations
+&namooo
+   ooo_files = "F.1.nc" "F.2.nc" "F.3.nc" "P.1.nc" "P.2.nc" "P.3.nc" "A.1.nc"
+   nn_ooo_idx = 1 1 1 1 1 1 1
+/
+!----------------------------------------------------------------------
+!       namcl4 Offline obs_oper class 4 namelist
+!----------------------------------------------------------------------
+!
+!  Naming convention
+!  -----------------
+!  cl4_prefix    specifies the output file prefix
+!  cl4_date      specifies the output file validity date
+!  cl4_sys       specifies the model counterpart system
+!  cl4_cfg       specifies the model counterpart configuration
+!  cl4_vn        specifies the model counterpart version
+!  cl4_inst      specifies the model counterpart institute
+!  cl4_contact   specifies the file producers contact details
+!
+!  I/O specification
+!  -----------------
+!  cl4_vars      specifies the names of the output file netcdf variable
+!  cl4_fcst_idx  specifies output file forecast index
+!  cl4_fcst_len  specifies forecast axis length
+!  cl4_match_len specifies number of unique matches per observation
+!  cl4_leadtime  specifies the forecast axis lead time
+!
+&namcl4
+   cl4_match_len = 7
+   cl4_fcst_len = 3
+   cl4_fcst_idx = 1 2 3 1 2 3 1
+   cl4_vars = "forecast" "forecast" "forecast" "persistence" "persistence"
+              "persistence" "best_estimate"
+   cl4_leadtime = 12 36 60
+   cl4_prefix = "class4"
+   cl4_date = "20130101"
+   cl4_vn = "12.0"
+   cl4_sys = "FOAM"
+   cl4_cfg = "AMM7"
+   cl4_contact = "example@example.com"
+   cl4_inst = "UK Met Office"
+/
+\end{forlines}
+\subsubsection{Climatology interpolation}
+The climatological counterpart is generated at the start of the run by
+restarting the model from climatology through appropriate use of \textbf{namtsd}.
+To override the offline observation operator read routine and to take advantage of the restart settings,
+specify the first entry in \textbf{cl4\_vars} as "climatology".
+This will then pipe the restart from climatology into the output class 4 file.
+As in every other class 4 matchup the input file, input index and output index must be specified.
+These can be replaced with dummy data since they are not used but
+they must be present to cycle through the matchups correctly.
+\subsection{Advanced usage}
+In certain cases it may be desirable to include both multiple model fields per observation window with
+multiple match ups per observation.
+This can be achieved by specifying \textbf{nn\_ooo\_freq} as well as the class 4 settings.
+Care must be taken in generating the ooo\_files list such that the files are arranged into
+consecutive blocks of single match ups.
+For example, 2 forecast fields of 12 hourly data would result in 4 separate read operations but
+only 2 write operations, 1 per forecast.
+\begin{forlines}
+   ooo_files = "F1.nc" "F1.nc" "F2.nc" "F2.nc"
+...
+   cl4_fcst_idx = 1 2
+\end{forlines}
+The above notation reveals the internal split between match up iterators and file iterators.
+This technique has not been used before so experimentation is needed before results can be trusted.
+If all that is needed is a single model counterpart at a regular interval then
+the standard SAO is all that is required.
+However, just to note, it is possible to extend this approach by comparing multiple forecasts, analyses, persisted analyses and
+climatologies with the same set of observations.
+This approach is referred to as \emph{Class 4} since it is the fourth metric defined by the GODAE intercomparison project. This requires multiple runs of the SAO and running an additional utility (not currently in the \NEMO\ repository) to combine the feedback files into one class 4 file.
 \newpage
 …
 \label{sec:OBS_obsutils}
 Some tools for viewing and processing of observation and feedback files are provided in
 the NEMO repository for convenience.
 These include OBSTOOLS which are a collection of \fortran programs which are helpful to deal with feedback files.
+For convenience some tools for viewing and processing of observation and feedback files are provided in
+the \NEMO\ repository.
+These tools include OBSTOOLS which are a collection of \fortran\ programs which are helpful to deal with feedback files.
 They do such tasks as observation file conversion, printing of file contents,
 some basic statistical analysis of feedback files.
 The other tool is an IDL program called dataplot which uses a graphical interface to
+The other main tool is an IDL program called dataplot which uses a graphical interface to
 visualise observations and feedback files.
 OBSTOOLS and dataplot are described in more detail below.
 …
 \subsection{Obstools}
+A series of \fortran utilities is provided with NEMO called OBSTOOLS.
+This are helpful in handling observation files and the feedback file output from the NEMO observation operator.
+The utilities are as follows
+\subsubsection{c4comb}
+The program c4comb combines multiple class 4 files produced by individual processors in
+an MPI run of NEMO offline obs\_oper into a single class 4 file.
+The program is called in the following way:
+\footnotesize
+\begin{cmds}
+c4comb.exe outputfile inputfile1 inputfile2 ...
+\end{cmds}
+A series of \fortran\ utilities is provided with \NEMO\ called OBSTOOLS.
+This are helpful in handling observation files and the feedback file output from the observation operator. A brief description of some of the utilities follows
 \subsubsection{corio2fb}
 The program corio2fb converts profile observation files from the Coriolis format to the standard feedback format.
+The program is called in the following way:
+\footnotesize
+It is called in the following way:
 \begin{cmds}
 corio2fb.exe outputfile inputfile1 inputfile2 ...
 …
 The program enact2fb converts profile observation files from the ENACT format to the standard feedback format.
+The program is called in the following way:
+\footnotesize
+It is called in the following way:
 \begin{cmds}
 enact2fb.exe outputfile inputfile1 inputfile2 ...
 …
 The program fbcomb combines multiple feedback files produced by individual processors in
+an MPI run of NEMO into a single feedback file.
+The program is called in the following way:
+\footnotesize
+an MPI run of \NEMO\ into a single feedback file.
+It is called in the following way:
 \begin{cmds}
 fbcomb.exe outputfile inputfile1 inputfile2 ...
 …
 The program fbmatchup will match observations from two feedback files.
+The program is called in the following way:
+\footnotesize
+It is called in the following way:
 \begin{cmds}
 fbmatchup.exe outputfile inputfile1 varname1 inputfile2 varname2 ...
 …
 The program fbprint will print the contents of a feedback file or files to standard output.
 Selected information can be output using optional arguments.
+The program is called in the following way:
+\footnotesize
+It is called in the following way:
 \begin{cmds}
 fbprint.exe [options] inputfile
 …
      -B            Select observations based on QC flags
      -u            unsorted
      -s ID         select station ID
+     -s ID         select station ID
      -t TYPE       select observation type
      -v NUM1-NUM2  select variable range to print by number
+     -v NUM1-NUM2  select variable range to print by number
                       (default all)
      -a NUM1-NUM2  select additional variable range to print by number
+     -a NUM1-NUM2  select additional variable range to print by number
                       (default all)
      -e NUM1-NUM2  select extra variable range to print by number
+     -e NUM1-NUM2  select extra variable range to print by number
                       (default all)
      -d            output date range
 …
 The program fbsel will select or subsample observations.
+The program is called in the following way:
+\footnotesize
+It is called in the following way:
 \begin{cmds}
 fbsel.exe <input filename> <output filename>
 …
 The program fbstat will output summary statistics in different global areas into a number of files.
+The program is called in the following way:
+\footnotesize
+It is called in the following way:
 \begin{cmds}
 fbstat.exe [-nmlev] <filenames>
 …
 The program fbthin will thin the data to 1 degree resolution.
 The code could easily be modified to thin to a different resolution.
+The program is called in the following way:
+\footnotesize
+It is called in the following way:
 \begin{cmds}
 fbthin.exe inputfile outputfile
 …
 The program sla2fb will convert an AVISO SLA format file to feedback format.
+The program is called in the following way:
+\footnotesize
+It is called in the following way:
 \begin{cmds}
 sla2fb.exe [-s type] outputfile inputfile1 inputfile2 ...
 …
 The program vel2fb will convert TAO/PIRATA/RAMA currents files to feedback format.
+The program is called in the following way:
+\footnotesize
+It is called in the following way:
 \begin{cmds}
 vel2fb.exe outputfile inputfile1 inputfile2 ...
 …
 An IDL program called dataplot is included which uses a graphical interface to
+visualise observations and feedback files.
+visualise observations and feedback files. Note a similar package has recently developed in python (also called dataplot) which does some of the same things that the IDL dataplot does. Please contact the authors of the this chapter if you are interested in this.
 It is possible to zoom in, plot individual profiles and calculate some basic statistics.
 To plot some data run IDL and then:
+\footnotesize
 \begin{minted}{idl}
 IDL> dataplot, "filename"
 …
 for example multiple feedback files from different processors or from different days,
 the easiest method is to use the spawn command to generate a list of files which can then be passed to dataplot.
+\footnotesize
 \begin{minted}{idl}
 IDL> spawn, 'ls profb*.nc', files
 …
 \end{minted}
 \autoref{fig:obsdataplotmain} shows the main window which is launched when dataplot starts.
+\autoref{fig:OBS_dataplotmain} shows the main window which is launched when dataplot starts.
 This is split into three parts.
 At the top there is a menu bar which contains a variety of drop down menus.
 …
 The plotting colour range can be changed by clicking on the colour bar.
 The title of the plot gives some basic information about the date range and depth range shown,
 the extreme values, and the mean and rms values.
+the extreme values, and the mean and RMS values.
 It is possible to zoom in using a drag-box.
 You may also zoom in or out using the mouse wheel.
 …
 observation minus background value.
 The next group of radio buttons selects the map projection.
 This can either be regular latitude longitude grid, or north or south polar stereographic.
+This can either be regular longitude latitude grid, or north or south polar stereographic.
 The next group of radio buttons will plot bad observations, switch to salinity and
 plot density for profile observations.
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}
+  \begin{center}
+    % \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_OBS_dataplot_main}
+    \includegraphics[width=9cm,angle=-90.]{Fig_OBS_dataplot_main}
+    \caption{
+      \protect\label{fig:obsdataplotmain}
+      Main window of dataplot.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_OBS_dataplot_main}
+  \caption{Main window of dataplot}
+  \label{fig:OBS_dataplotmain}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 If a profile point is clicked with the mouse button a plot of the observation and background values as
 a function of depth (\autoref{fig:obsdataplotprofile}).
+a function of depth (\autoref{fig:OBS_dataplotprofile}).
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}
+  \begin{center}
+    % \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_OBS_dataplot_prof}
+    \includegraphics[width=7cm,angle=-90.]{Fig_OBS_dataplot_prof}
+    \caption{
+      \protect\label{fig:obsdataplotprofile}
+      Profile plot from dataplot produced by right clicking on a point in the main window.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_OBS_dataplot_prof}
+  \caption[Profile plot from dataplot]{
+    Profile plot from dataplot produced by right clicking on a point in the main window}
+  \label{fig:OBS_dataplotprofile}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_SBC.tex

-                      r10614
+                      r11564
 \begin{document}
+% ================================================================
+% Chapter —— Surface Boundary Condition (SBC, ISF, ICB)
+% ================================================================
+\chapter{Surface Boundary Condition (SBC, ISF, ICB) }
+% ================================================================
+% Chapter —— Surface Boundary Condition (SBC, SAS, ISF, ICB)
+% ================================================================
+\chapter{Surface Boundary Condition (SBC, SAS, ISF, ICB)}
 \label{chap:SBC}
 \minitoc
+\chaptertoc
 \newpage
 …
 %---------------------------------------namsbc--------------------------------------------------
+\nlst{namsbc}
+\begin{listing}
+  \nlst{namsbc}
+  \caption{\texttt{namsbc}}
+  \label{lst:namsbc}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------------
+The ocean needs six fields as surface boundary condition:
+The ocean needs seven fields as surface boundary condition:
 \begin{itemize}
 \item
 …
 \item
   the surface salt flux associated with freezing/melting of seawater $\left( {\textit{sfx}} \right)$
+\item
+  the atmospheric pressure at the ocean surface $\left( p_a \right)$
 \end{itemize}
+plus an optional field:
+Four different ways are available to provide the seven fields to the ocean. They are controlled by
+namelist \nam{sbc} variables:
 \begin{itemize}
+   \item the atmospheric pressure at the ocean surface $\left( p_a \right)$
+\item
+  a bulk formulation (\np{ln\_blk}\forcode{=.true.} with four possible bulk algorithms),
+\item
+  a flux formulation (\np{ln\_flx}\forcode{=.true.}),
+\item
+  a coupled or mixed forced/coupled formulation (exchanges with a atmospheric model via the OASIS coupler),
+(\np{ln\_cpl} or \np{ln\_mixcpl}\forcode{=.true.}),
+\item
+  a user defined formulation (\np{ln\_usr}\forcode{=.true.}).
 \end{itemize}
-Four different ways to provide the first six fields to the ocean are available which are controlled by
-namelist \ngn{namsbc} variables:
-an analytical formulation (\np{ln\_ana}\forcode{ = .true.}),
-a flux formulation (\np{ln\_flx}\forcode{ = .true.}),
-a bulk formulae formulation (CORE (\np{ln\_blk\_core}\forcode{ = .true.}),
-CLIO (\np{ln\_blk\_clio}\forcode{ = .true.}) bulk formulae) and
-a coupled or mixed forced/coupled formulation (exchanges with a atmospheric model via the OASIS coupler)
-(\np{ln\_cpl} or \np{ln\_mixcpl}\forcode{ = .true.}).
-When used (\ie \np{ln\_apr\_dyn}\forcode{ = .true.}),
-the atmospheric pressure forces both ocean and ice dynamics.
 The frequency at which the forcing fields have to be updated is given by the \np{nn\_fsbc} namelist parameter.
+When the fields are supplied from data files (flux and bulk formulations),
+the input fields need not be supplied on the model grid.
+Instead a file of coordinates and weights can be supplied which maps the data from the supplied grid to
+When the fields are supplied from data files (bulk, flux and mixed formulations),
+the input fields do not need to be supplied on the model grid.
+Instead, a file of coordinates and weights can be supplied to map the data from the input fields grid to
 the model points (so called "Interpolation on the Fly", see \autoref{subsec:SBC_iof}).
 If the Interpolation on the Fly option is used, input data belonging to land points (in the native grid),
 can be masked to avoid spurious results in proximity of the coasts as
+If the "Interpolation on the Fly" option is used, input data belonging to land points (in the native grid)
+should be masked or filled to avoid spurious results in proximity of the coasts, as
 large sea-land gradients characterize most of the atmospheric variables.
 In addition, the resulting fields can be further modified using several namelist options.
+These options control
+These options control:
 \begin{itemize}
 \item
   the rotation of vector components supplied relative to an east-north coordinate system onto
+  the local grid directions in the model;
+\item
+  the addition of a surface restoring term to observed SST and/or SSS (\np{ln\_ssr}\forcode{ = .true.});
+\item
+  the modification of fluxes below ice-covered areas (using observed ice-cover or a sea-ice model)
+  (\np{nn\_ice}\forcode{ = 0..3});
+\item
+  the addition of river runoffs as surface freshwater fluxes or lateral inflow (\np{ln\_rnf}\forcode{ = .true.});
+\item
+  the addition of isf melting as lateral inflow (parameterisation) or
+  as fluxes applied at the land-ice ocean interface (\np{ln\_isf}) ;
+  the local grid directions in the model,
+\item
+  the use of a land/sea mask for input fields (\np{nn\_lsm}\forcode{=.true.}),
+\item
+  the addition of a surface restoring term to observed SST and/or SSS (\np{ln\_ssr}\forcode{=.true.}),
+\item
+  the modification of fluxes below ice-covered areas (using climatological ice-cover or a sea-ice model)
+  (\np{nn\_ice}\forcode{=0..3}),
+\item
+  the addition of river runoffs as surface freshwater fluxes or lateral inflow (\np{ln\_rnf}\forcode{=.true.}),
+\item
+  the addition of ice-shelf melting as lateral inflow (parameterisation) or
+  as fluxes applied at the land-ice ocean interface (\np{ln\_isf}\forcode{=.true.}),
 \item
   the addition of a freshwater flux adjustment in order to avoid a mean sea-level drift
+  (\np{nn\_fwb}\forcode{ = 0..2});
+\item
+  the transformation of the solar radiation (if provided as daily mean) into a diurnal cycle
+  (\np{ln\_dm2dc}\forcode{ = .true.});
+\item
+  a neutral drag coefficient can be read from an external wave model (\np{ln\_cdgw}\forcode{ = .true.});
+\item
+  the Stokes drift rom an external wave model can be accounted (\np{ln\_sdw}\forcode{ = .true.});
+\item
+  the Stokes-Coriolis term can be included (\np{ln\_stcor}\forcode{ = .true.});
+\item
+  the surface stress felt by the ocean can be modified by surface waves (\np{ln\_tauwoc}\forcode{ = .true.}).
+  (\np{nn\_fwb}\forcode{=0..2}),
+\item
+  the transformation of the solar radiation (if provided as daily mean) into an analytical diurnal cycle
+  (\np{ln\_dm2dc}\forcode{=.true.}),
+\item
+  the activation of wave effects from an external wave model  (\np{ln\_wave}\forcode{=.true.}),
+\item
+  a neutral drag coefficient is read from an external wave model (\np{ln\_cdgw}\forcode{=.true.}),
+\item
+  the Stokes drift from an external wave model is accounted for (\np{ln\_sdw}\forcode{=.true.}),
+\item
+  the choice of the Stokes drift profile parameterization (\np{nn\_sdrift}\forcode{=0..2}),
+\item
+  the surface stress given to the ocean is modified by surface waves (\np{ln\_tauwoc}\forcode{=.true.}),
+\item
+  the surface stress given to the ocean is read from an external wave model (\np{ln\_tauw}\forcode{=.true.}),
+\item
+  the Stokes-Coriolis term is included (\np{ln\_stcor}\forcode{=.true.}),
+\item
+  the light penetration in the ocean (\np{ln\_traqsr}\forcode{=.true.} with namelist \nam{tra\_qsr}),
+\item
+  the atmospheric surface pressure gradient effect on ocean and ice dynamics (\np{ln\_apr\_dyn}\forcode{=.true.} with namelist \nam{sbc\_apr}),
+\item
+  the effect of sea-ice pressure on the ocean (\np{ln\_ice\_embd}\forcode{=.true.}).
 \end{itemize}
 In this chapter, we first discuss where the surface boundary condition appears in the model equations.
 Then we present the five ways of providing the surface boundary condition,
 followed by the description of the atmospheric pressure and the river runoff.
 Next the scheme for interpolation on the fly is described.
+In this chapter, we first discuss where the surface boundary conditions appear in the model equations.
+Then we present the three ways of providing the surface boundary conditions,
+followed by the description of the atmospheric pressure and the river runoff.
+Next, the scheme for interpolation on the fly is described.
 Finally, the different options that further modify the fluxes applied to the ocean are discussed.
 One of these is modification by icebergs (see \autoref{sec:ICB_icebergs}),
+One of these is modification by icebergs (see \autoref{sec:SBC_ICB_icebergs}),
 which act as drifting sources of fresh water.
 Another example of modification is that due to the ice shelf melting/freezing (see \autoref{sec:SBC_isf}),
+Another example of modification is that due to the ice shelf melting/freezing (see \autoref{sec:SBC_isf}),
 which provides additional sources of fresh water.
 % ================================================================
 % Surface boundary condition for the ocean
 % ================================================================
 \section{Surface boundary condition for the ocean}
 \label{sec:SBC_general}
+\label{sec:SBC_ocean}
 The surface ocean stress is the stress exerted by the wind and the sea-ice on the ocean.
 It is applied in \mdl{dynzdf} module as a surface boundary condition of the computation of
 the momentum vertical mixing trend (see \autoref{eq:dynzdf_sbc} in \autoref{sec:DYN_zdf}).
+the momentum vertical mixing trend (see \autoref{eq:DYN_zdf_sbc} in \autoref{sec:DYN_zdf}).
 As such, it has to be provided as a 2D vector interpolated onto the horizontal velocity ocean mesh,
 \ie resolved onto the model (\textbf{i},\textbf{j}) direction at $u$- and $v$-points.
+\ie\ resolved onto the model (\textbf{i},\textbf{j}) direction at $u$- and $v$-points.
 The surface heat flux is decomposed into two parts, a non solar and a solar heat flux,
 $Q_{ns}$ and $Q_{sr}$, respectively.
 The former is the non penetrative part of the heat flux
 (\ie the sum of sensible, latent and long wave heat fluxes plus
 the heat content of the mass exchange with the atmosphere and sea-ice).
+(\ie\ the sum of sensible, latent and long wave heat fluxes plus
+the heat content of the mass exchange between the ocean and sea-ice).
 It is applied in \mdl{trasbc} module as a surface boundary condition trend of
 the first level temperature time evolution equation
 (see \autoref{eq:tra_sbc} and \autoref{eq:tra_sbc_lin} in \autoref{subsec:TRA_sbc}).
+(see \autoref{eq:TRA_sbc} and \autoref{eq:TRA_sbc_lin} in \autoref{subsec:TRA_sbc}).
 The latter is the penetrative part of the heat flux.
 It is applied as a 3D trends of the temperature equation (\mdl{traqsr} module) when
 \np{ln\_traqsr}\forcode{ = .true.}.
+It is applied as a 3D trend of the temperature equation (\mdl{traqsr} module) when
+\np{ln\_traqsr}\forcode{=.true.}.
 The way the light penetrates inside the water column is generally a sum of decreasing exponentials
 (see \autoref{subsec:TRA_qsr}).
+(see \autoref{subsec:TRA_qsr}).
 The surface freshwater budget is provided by the \textit{emp} field.
 It represents the mass flux exchanged with the atmosphere (evaporation minus precipitation) and
 possibly with the sea-ice and ice shelves (freezing minus melting of ice).
 It affects both the ocean in two different ways:
 $(i)$  it changes the volume of the ocean and therefore appears in the sea surface height equation as
 a volume flux, and
+It affects the ocean in two different ways:
+$(i)$  it changes the volume of the ocean, and therefore appears in the sea surface height equation as      %GS: autoref ssh equation to be added
+a volume flux, and
 $(ii)$ it changes the surface temperature and salinity through the heat and salt contents of
 the mass exchanged with the atmosphere, the sea-ice and the ice shelves.
+the mass exchanged with atmosphere, sea-ice and ice shelves.
 %\colorbox{yellow}{Miss: }
+%
 %A extensive description of all namsbc namelist (parameter that have to be
+%A extensive description of all namsbc namelist (parameter that have to be
 %created!)
+%
 %Especially the \np{nn\_fsbc}, the \mdl{sbc\_oce} module (fluxes + mean sst sss ssu
 %ssv) \ie information required by flux computation or sea-ice
+%Especially the \np{nn\_fsbc}, the \mdl{sbc\_oce} module (fluxes + mean sst sss ssu
+%ssv) \ie\ information required by flux computation or sea-ice
+%
 %\mdl{sbc\_oce} containt the definition in memory of the 7 fields (6+runoff), add
+%\mdl{sbc\_oce} containt the definition in memory of the 7 fields (6+runoff), add
 %a word on runoff: included in surface bc or add as lateral obc{\ldots}.
+%
 %Sbcmod manage the ``providing'' (fourniture) to the ocean the 7 fields
+%
 %Fluxes update only each nf{\_}sbc time step (namsbc) explain relation
 %between nf{\_}sbc and nf{\_}ice, do we define nf{\_}blk??? ? only one
 %nf{\_}sbc
+%Fluxes update only each nf\_sbc time step (namsbc) explain relation
+%between nf\_sbc and nf\_ice, do we define nf\_blk??? ? only one
+%nf\_sbc
+%
 %Explain here all the namlist namsbc variable{\ldots}.
+%
+%
 % explain : use or not of surface currents
+%
 …
 The ocean model provides, at each time step, to the surface module (\mdl{sbcmod})
 the surface currents, temperature and salinity.
 These variables are averaged over \np{nn\_fsbc} time-step (\autoref{tab:ssm}), and
 it is these averaged fields which are used to computes the surface fluxes at a frequency of \np{nn\_fsbc} time-step.
+the surface currents, temperature and salinity.
+These variables are averaged over \np{nn\_fsbc} time-step (\autoref{tab:SBC_ssm}), and
+these averaged fields are used to compute the surface fluxes at the frequency of \np{nn\_fsbc} time-steps.
 %-------------------------------------------------TABLE---------------------------------------------------
 \begin{table}[tb]
+  \begin{center}
+    \begin{tabular}{|l|l|l|l|}
+      \hline
+      Variable description             & Model variable  & Units  & point \\  \hline
+      i-component of the surface current  & ssu\_m & $m.s^{-1}$   & U \\   \hline
+      j-component of the surface current  & ssv\_m & $m.s^{-1}$   & V \\   \hline
+      Sea surface temperature          & sst\_m & \r{}$K$      & T \\   \hline
+      Sea surface salinty              & sss\_m & $psu$        & T \\   \hline
+    \end{tabular}
+    \caption{
+      \protect\label{tab:ssm}
+      Ocean variables provided by the ocean to the surface module (SBC).
+      The variable are averaged over nn{\_}fsbc time step,
+      \ie the frequency of computation of surface fluxes.
+    }
+  \end{center}
+  \centering
+  \begin{tabular}{|l|l|l|l|}
+    \hline
+    Variable description                           & Model variable  & Units  & point                 \\
+    \hline
+    i-component of the surface current & ssu\_m               & $m.s^{-1}$     & U     \\
+    \hline
+    j-component of the surface current & ssv\_m               & $m.s^{-1}$     & V     \\
+    \hline
+    Sea surface temperature                  & sst\_m               & \r{}$K$              & T     \\\hline
+    Sea surface salinty                         & sss\_m               & $psu$              & T     \\   \hline
+  \end{tabular}
+  \caption[Ocean variables provided to the surface module)]{
+    Ocean variables provided to the surface module (\texttt{SBC}).
+    The variable are averaged over \protect\np{nn\_fsbc} time-step,
+    \ie\ the frequency of computation of surface fluxes.}
+  \label{tab:SBC_ssm}
 \end{table}
 %--------------------------------------------------------------------------------------------------------------
+%\colorbox{yellow}{Penser a} mettre dans le restant l'info nn{\_}fsbc ET nn{\_}fsbc*rdt de sorte de reinitialiser la moyenne si on change la frequence ou le pdt
+% ================================================================
+%       Input Data
+%\colorbox{yellow}{Penser a} mettre dans le restant l'info nn\_fsbc ET nn\_fsbc*rdt de sorte de reinitialiser la moyenne si on change la frequence ou le pdt
+% ================================================================
+%       Input Data
 % ================================================================
 \section{Input data generic interface}
 …
 A generic interface has been introduced to manage the way input data
 (2D or 3D fields, like surface forcing or ocean T and S) are specify in \NEMO.
 This task is archieved by \mdl{fldread}.
 The module was design with four main objectives in mind:
+(2D or 3D fields, like surface forcing or ocean T and S) are specified in \NEMO.
+This task is achieved by \mdl{fldread}.
+The module is designed with four main objectives in mind:
 \begin{enumerate}
 \item
   optionally provide a time interpolation of the input data at model time-step, whatever their input frequency is,
+  optionally provide a time interpolation of the input data every specified model time-step, whatever their input frequency is,
   and according to the different calendars available in the model.
 \item
 …
 \item
   provide a simple user interface and a rather simple developer interface by
   limiting the number of prerequisite information.
 \end{enumerate}
 As a results the user have only to fill in for each variable a structure in the namelist file to
+  limiting the number of prerequisite informations.
+\end{enumerate}
+As a result, the user has only to fill in for each variable a structure in the namelist file to
 define the input data file and variable names, the frequency of the data (in hours or months),
 whether its is climatological data or not, the period covered by the input file (one year, month, week or day),
 and three additional parameters for on-the-fly interpolation.
+and three additional parameters for the on-the-fly interpolation.
 When adding a new input variable, the developer has to add the associated structure in the namelist,
 read this information by mirroring the namelist read in \rou{sbc\_blk\_init} for example,
 and simply call \rou{fld\_read} to obtain the desired input field at the model time-step and grid points.
 The only constraints are that the input file is a NetCDF file, the file name follows a nomenclature
+The only constraints are that the input file is a NetCDF file, the file name follows a nomenclature
 (see \autoref{subsec:SBC_fldread}), the period it cover is one year, month, week or day, and,
 if on-the-fly interpolation is used, a file of weights must be supplied (see \autoref{subsec:SBC_iof}).
 Note that when an input data is archived on a disc which is accessible directly from the workspace where
+the code is executed, then the use can set the \np{cn\_dir} to the pathway leading to the data.
+By default, the data are assumed to have been copied so that cn\_dir='./'.
+the code is executed, then the user can set the \np{cn\_dir} to the pathway leading to the data.
+By default, the data are assumed to be in the same directory as the executable, so that cn\_dir='./'.
 % -------------------------------------------------------------------------------------------------------------
 % Input Data specification (\mdl{fldread})
 % -------------------------------------------------------------------------------------------------------------
+\subsection{Input data specification (\protect\mdl{fldread})}
+\subsection[Input data specification (\textit{fldread.F90})]
+{Input data specification (\protect\mdl{fldread})}
 \label{subsec:SBC_fldread}
 The structure associated with an input variable contains the following information:
 \begin{forlines}
 !  file name  ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
+!  file name  ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
 !             !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
 \end{forlines}
 where
 \begin{description}
+where
+\begin{description}
 \item[File name]:
   the stem name of the NetCDF file to be open.
+  the stem name of the NetCDF file to be opened.
   This stem will be completed automatically by the model, with the addition of a '.nc' at its end and
   by date information and possibly a prefix (when using AGRIF).
   Tab.\autoref{tab:fldread} provides the resulting file name in all possible cases according to
+  \autoref{tab:SBC_fldread} provides the resulting file name in all possible cases according to
   whether it is a climatological file or not, and to the open/close frequency (see below for definition).
 %--------------------------------------------------TABLE--------------------------------------------------
   \begin{table}[htbp]
+    \begin{center}
+      \begin{tabular}{|l|c|c|c|}
+        \hline
+        & daily or weekLLL         & monthly                   &   yearly          \\   \hline
+        \np{clim}\forcode{ = .false.}  & fn\_yYYYYmMMdDD.nc  &   fn\_yYYYYmMM.nc   &   fn\_yYYYY.nc  \\   \hline
+        \np{clim}\forcode{ = .true.}         & not possible                  &  fn\_m??.nc             &   fn                \\   \hline
+      \end{tabular}
+    \end{center}
+    \caption{
+      \protect\label{tab:fldread}
+      naming nomenclature for climatological or interannual input file, as a function of the Open/close frequency.
+    \centering
+    \begin{tabular}{|l|c|c|c|}
+      \hline
+                                  &  daily or weekLL     &  monthly           &  yearly        \\
+      \hline
+      \np{clim}\forcode{=.false.} &  fn\_yYYYYmMMdDD.nc  &  fn\_yYYYYmMM.nc   &  fn\_yYYYY.nc  \\
+      \hline
+      \np{clim}\forcode{=.true.}  &  not possible        &  fn\_m??.nc        &  fn            \\
+      \hline
+    \end{tabular}
+    \caption[Naming nomenclature for climatological or interannual input file]{
+      Naming nomenclature for climatological or interannual input file,
+      as a function of the open/close frequency.
       The stem name is assumed to be 'fn'.
       For weekly files, the 'LLL' corresponds to the first three letters of the first day of the week
+      (\ie 'sun','sat','fri','thu','wed','tue','mon').
+      The 'YYYY', 'MM' and 'DD' should be replaced by the actual year/month/day, always coded with 4 or 2 digits.
+      Note that (1) in mpp, if the file is split over each subdomain, the suffix '.nc' is replaced by '\_PPPP.nc',
+      (\ie\ 'sun','sat','fri','thu','wed','tue','mon').
+      The 'YYYY', 'MM' and 'DD' should be replaced by the actual year/month/day,
+      always coded with 4 or 2 digits.
+      Note that (1) in mpp, if the file is split over each subdomain,
+      the suffix '.nc' is replaced by '\_PPPP.nc',
       where 'PPPP' is the process number coded with 4 digits;
       (2) when using AGRIF, the prefix '\_N' is added to files, where 'N'  is the child grid number.
+      (2) when using AGRIF, the prefix '\_N' is added to files, where 'N' is the child grid number.
+    }
+    \label{tab:SBC_fldread}
   \end{table}
 %--------------------------------------------------------------------------------------------------------------
 \item[Record frequency]:
 …
   Its unit is in hours if it is positive (for example 24 for daily forcing) or in months if negative
   (for example -1 for monthly forcing or -12 for annual forcing).
   Note that this frequency must really be an integer and not a real.
   On some computers, seting it to '24.' can be interpreted as 240!
+  Note that this frequency must REALLY be an integer and not a real.
+  On some computers, setting it to '24.' can be interpreted as 240!
 \item[Variable name]:
 …
 h00'00'' to 23h59'59".
   If set to 'true', the forcing will have a broken line shape.
   Records are assumed to be dated the middle of the forcing period.
+  Records are assumed to be dated at the middle of the forcing period.
   For example, when using a daily forcing with time interpolation,
   linear interpolation will be performed between mid-day of two consecutive days.
+  linear interpolation will be performed between mid-day of two consecutive days.
 \item[Climatological forcing]:
   a logical to specify if a input file contains climatological forcing which can be cycle in time,
   or an interannual forcing which will requires additional files if
   the period covered by the simulation exceed the one of the file.
   See the above the file naming strategy which impacts the expected name of the file to be opened.
+  the period covered by the simulation exceeds the one of the file.
+  See the above file naming strategy which impacts the expected name of the file to be opened.
 \item[Open/close frequency]:
 …
   Files are assumed to contain data from the beginning of the open/close period.
   For example, the first record of a yearly file containing daily data is Jan 1st even if
   the experiment is not starting at the beginning of the year.
+  the experiment is not starting at the beginning of the year.
 \item[Others]:
 …
 The only tricky point is therefore to specify the date at which we need to do the interpolation and
 the date of the records read in the input files.
 Following \citet{Leclair_Madec_OM09}, the date of a time step is set at the middle of the time step.
 For example, for an experiment starting at 0h00'00" with a one hour time-step,
+Following \citet{leclair.madec_OM09}, the date of a time step is set at the middle of the time step.
+For example, for an experiment starting at 0h00'00" with a one-hour time-step,
 a time interpolation will be performed at the following time: 0h30'00", 1h30'00", 2h30'00", etc.
 However, for forcing data related to the surface module,
 values are not needed at every time-step but at every \np{nn\_fsbc} time-step.
 For example with \np{nn\_fsbc}\forcode{ = 3}, the surface module will be called at time-steps 1, 4, 7, etc.
 The date used for the time interpolation is thus redefined to be at the middle of \np{nn\_fsbc} time-step period.
 In the previous example, this leads to: 1h30'00", 4h30'00", 7h30'00", etc. \\
+For example with \np{nn\_fsbc}\forcode{=3}, the surface module will be called at time-steps 1, 4, 7, etc.
+The date used for the time interpolation is thus redefined to the middle of \np{nn\_fsbc} time-step period.
+In the previous example, this leads to: 1h30'00", 4h30'00", 7h30'00", etc. \\
 (2) For code readablility and maintenance issues, we don't take into account the NetCDF input file calendar.
 The calendar associated with the forcing field is build according to the information provided by
 user in the record frequency, the open/close frequency and the type of temporal interpolation.
 For example, the first record of a yearly file containing daily data that will be interpolated in time is assumed to
 be start Jan 1st at 12h00'00" and end Dec 31st at 12h00'00". \\
+start Jan 1st at 12h00'00" and end Dec 31st at 12h00'00". \\
 (3) If a time interpolation is requested, the code will pick up the needed data in the previous (next) file when
 interpolating data with the first (last) record of the open/close period.
 For example, if the input file specifications are ''yearly, containing daily data to be interpolated in time'',
+For example, if the input file specifications are ''yearly, containing daily data to be interpolated in time'',
 the values given by the code between 00h00'00" and 11h59'59" on Jan 1st will be interpolated values between
 Dec 31st 12h00'00" and Jan 1st 12h00'00".
 If the forcing is climatological, Dec and Jan will be keep-up from the same year.
 However, if the forcing is not climatological, at the end of
 the open/close period the code will automatically close the current file and open the next one.
+the open/close period, the code will automatically close the current file and open the next one.
 Note that, if the experiment is starting (ending) at the beginning (end) of
 an open/close period we do accept that the previous (next) file is not existing.
+an open/close period, we do accept that the previous (next) file is not existing.
 In this case, the time interpolation will be performed between two identical values.
 For example, when starting an experiment on Jan 1st of year Y with yearly files and daily data to be interpolated,
 we do accept that the file related to year Y-1 is not existing.
 The value of Jan 1st will be used as the missing one for Dec 31st of year Y-1.
 If the file of year Y-1 exists, the code will read its last record.
+If the file of year Y-1 exists, the code will read its last record.
 Therefore, this file can contain only one record corresponding to Dec 31st,
 a useful feature for user considering that it is too heavy to manipulate the complete file for year Y-1.
 …
 Interpolation on the Fly allows the user to supply input files required for the surface forcing on
 grids other than the model grid.
 To do this he or she must supply, in addition to the source data file, a file of weights to be used to
+To do this, he or she must supply, in addition to the source data file(s), a file of weights to be used to
 interpolate from the data grid to the model grid.
 The original development of this code used the SCRIP package
 (freely available \href{http://climate.lanl.gov/Software/SCRIP}{here} under a copyright agreement).
 In principle, any package can be used to generate the weights, but the variables in
+In principle, any package such as CDO can be used to generate the weights, but the variables in
 the input weights file must have the same names and meanings as assumed by the model.
 Two methods are currently available: bilinear and bicubic interpolation.
+Two methods are currently available: bilinear and bicubic interpolations.
 Prior to the interpolation, providing a land/sea mask file, the user can decide to remove land points from
 the input file and substitute the corresponding values with the average of the 8 neighbouring points in
 …
 Only "sea points" are considered for the averaging.
 The land/sea mask file must be provided in the structure associated with the input variable.
+The netcdf land/sea mask variable name must be 'LSM' it must have the same horizontal and vertical dimensions of
+the associated variable and should be equal to 1 over land and 0 elsewhere.
+The procedure can be recursively applied setting nn\_lsm > 1 in namsbc namelist.
+Note that nn\_lsm=0 forces the code to not apply the procedure even if a file for land/sea mask is supplied.
+The netcdf land/sea mask variable name must be 'LSM' and must have the same horizontal and vertical dimensions as
+the associated variables and should be equal to 1 over land and 0 elsewhere.
+The procedure can be recursively applied by setting nn\_lsm > 1 in namsbc namelist.
+Note that nn\_lsm=0 forces the code to not apply the procedure, even if a land/sea mask file is supplied.
+% -------------------------------------------------------------------------------------------------------------
+% Bilinear interpolation
+% -------------------------------------------------------------------------------------------------------------
 \subsubsection{Bilinear interpolation}
 \label{subsec:SBC_iof_bilinear}
 …
 The input weights file in this case has two sets of variables:
 src01, src02, src03, src04 and wgt01, wgt02, wgt03, wgt04.
 The "src" variables correspond to the point in the input grid to which the weight "wgt" is to be applied.
+The "src" variables correspond to the point in the input grid to which the weight "wgt" is applied.
 Each src value is an integer corresponding to the index of a point in the input grid when
 written as a one dimensional array.
 …
 and wgt(1) corresponds to variable "wgt01" for example.
+% -------------------------------------------------------------------------------------------------------------
+% Bicubic interpolation
+% -------------------------------------------------------------------------------------------------------------
 \subsubsection{Bicubic interpolation}
 \label{subsec:SBC_iof_bicubic}
 Again there are two sets of variables: "src" and "wgt".
 But in this case there are 16 of each.
+Again, there are two sets of variables: "src" and "wgt".
+But in this case, there are 16 of each.
 The symbolic algorithm used to calculate values on the model grid is now:
 …
   \begin{split}
     f_{m}(i,j) =  f_{m}(i,j) +& \sum_{k=1}^{4} {wgt(k)f(idx(src(k)))}
     +   \sum_{k=5}^{8} {wgt(k)\left.\frac{\partial f}{\partial i}\right| _{idx(src(k))} }    \\
     +& \sum_{k=9}^{12} {wgt(k)\left.\frac{\partial f}{\partial j}\right| _{idx(src(k))} }
     +   \sum_{k=13}^{16} {wgt(k)\left.\frac{\partial ^2 f}{\partial i \partial j}\right| _{idx(src(k))} }
+    +  \sum_{k=5 }^{8 } {wgt(k)\left.\frac{\partial f}{\partial i}\right| _{idx(src(k))} }    \\
+    +& \sum_{k=9 }^{12} {wgt(k)\left.\frac{\partial f}{\partial j}\right| _{idx(src(k))} }
+    +  \sum_{k=13}^{16} {wgt(k)\left.\frac{\partial ^2 f}{\partial i \partial j}\right| _{idx(src(k))} }
   \end{split}
 \]
 The gradients here are taken with respect to the horizontal indices and not distances since
+the spatial dependency has been absorbed into the weights.
+the spatial dependency has been included into the weights.
+% -------------------------------------------------------------------------------------------------------------
+% Implementation
+% -------------------------------------------------------------------------------------------------------------
 \subsubsection{Implementation}
 \label{subsec:SBC_iof_imp}
 …
 inspecting a global attribute stored in the weights input file.
 This attribute must be called "ew\_wrap" and be of integer type.
 If it is negative, the input non-model grid is assumed not to be cyclic.
+If it is negative, the input non-model grid is assumed to be not cyclic.
 If zero or greater, then the value represents the number of columns that overlap.
 $E.g.$ if the input grid has columns at longitudes 0, 1, 2, .... , 359, then ew\_wrap should be set to 0;
 if longitudes are 0.5, 2.5, .... , 358.5, 360.5, 362.5, ew\_wrap should be 2.
 If the model does not find attribute ew\_wrap, then a value of -999 is assumed.
 In this case the \rou{fld\_read} routine defaults ew\_wrap to value 0 and
+In this case, the \rou{fld\_read} routine defaults ew\_wrap to value 0 and
 therefore the grid is assumed to be cyclic with no overlapping columns.
 (In fact this only matters when bicubic interpolation is required.)
+(In fact, this only matters when bicubic interpolation is required.)
 Note that no testing is done to check the validity in the model,
 since there is no way of knowing the name used for the longitude variable,
 …
 or is a copy of one from the first few columns on the opposite side of the grid (cyclical case).
+% -------------------------------------------------------------------------------------------------------------
+% Limitations
+% -------------------------------------------------------------------------------------------------------------
 \subsubsection{Limitations}
 \label{subsec:SBC_iof_lim}
 \begin{enumerate}
 \item
   The case where input data grids are not logically rectangular has not been tested.
+\begin{enumerate}
+\item
+  The case where input data grids are not logically rectangular (irregular grid case) has not been tested.
 \item
   This code is not guaranteed to produce positive definite answers from positive definite inputs when
 …
 (see the directory NEMOGCM/TOOLS/WEIGHTS).
 % -------------------------------------------------------------------------------------------------------------
 % Standalone Surface Boundary Condition Scheme
 % -------------------------------------------------------------------------------------------------------------
+\subsection{Standalone surface boundary condition scheme}
+\label{subsec:SAS_iof}
+%---------------------------------------namsbc_ana--------------------------------------------------
+\nlst{namsbc_sas}
+\subsection{Standalone surface boundary condition scheme (SAS)}
+\label{subsec:SBC_SAS}
+%---------------------------------------namsbc_sas--------------------------------------------------
+\begin{listing}
+  \nlst{namsbc_sas}
+  \caption{\texttt{namsbc\_sas}}
+  \label{lst:namsbc_sas}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------------
 In some circumstances it may be useful to avoid calculating the 3D temperature,
 salinity and velocity fields and simply read them in from a previous run or receive them from OASIS.
+In some circumstances, it may be useful to avoid calculating the 3D temperature,
+salinity and velocity fields and simply read them in from a previous run or receive them from OASIS.
 For example:
 …
   Spinup of the iceberg floats
 \item
   Ocean/sea-ice simulation with both media running in parallel (\np{ln\_mixcpl}\forcode{ = .true.})
+  Ocean/sea-ice simulation with both models running in parallel (\np{ln\_mixcpl}\forcode{=.true.})
 \end{itemize}
 The StandAlone Surface scheme provides this utility.
 Its options are defined through the \ngn{namsbc\_sas} namelist variables.
+The Standalone Surface scheme provides this capacity.
+Its options are defined through the \nam{sbc\_sas} namelist variables.
 A new copy of the model has to be compiled with a configuration based on ORCA2\_SAS\_LIM.
 However no namelist parameters need be changed from the settings of the previous run (except perhaps nn{\_}date0).
+However, no namelist parameters need be changed from the settings of the previous run (except perhaps nn\_date0).
 In this configuration, a few routines in the standard model are overriden by new versions.
 Routines replaced are:
 …
   This has been cut down and now only calculates surface forcing and the ice model required.
   New surface modules that can function when only the surface level of the ocean state is defined can also be added
   (\eg icebergs).
+  (\eg\ icebergs).
 \item
   \mdl{daymod}:
 …
   so calls to restart functions have been removed.
   This also means that the calendar cannot be controlled by time in a restart file,
   so the user must make sure that nn{\_}date0 in the model namelist is correct for his or her purposes.
+  so the user must check that nn\_date0 in the model namelist is correct for his or her purposes.
 \item
   \mdl{stpctl}:
 …
   This module initialises the input files needed for reading temperature, salinity and
   velocity arrays at the surface.
   These filenames are supplied in namelist namsbc{\_}sas.
   Unfortunately because of limitations with the \mdl{iom} module,
+  These filenames are supplied in namelist namsbc\_sas.
+  Unfortunately, because of limitations with the \mdl{iom} module,
   the full 3D fields from the mean files have to be read in and interpolated in time,
   before using just the top level.
 …
+% Missing the description of the 2 following variables:
+%   ln_3d_uve   = .true.    !  specify whether we are supplying a 3D u,v and e3 field
+%   ln_read_frq = .false.    !  specify whether we must read frq or not
+% ================================================================
+% Analytical formulation (sbcana module)
+% ================================================================
+\section{Analytical formulation (\protect\mdl{sbcana})}
+\label{sec:SBC_ana}
+%---------------------------------------namsbc_ana--------------------------------------------------
+%
+%\nlst{namsbc_ana}
+%--------------------------------------------------------------------------------------------------------------
+The analytical formulation of the surface boundary condition is the default scheme.
+In this case, all the six fluxes needed by the ocean are assumed to be uniform in space.
+They take constant values given in the namelist \ngn{namsbc{\_}ana} by
+the variables \np{rn\_utau0}, \np{rn\_vtau0}, \np{rn\_qns0}, \np{rn\_qsr0}, and \np{rn\_emp0}
+($\textit{emp}=\textit{emp}_S$).
+The runoff is set to zero.
+In addition, the wind is allowed to reach its nominal value within a given number of time steps (\np{nn\_tau000}).
+If a user wants to apply a different analytical forcing,
+the \mdl{sbcana} module can be modified to use another scheme.
+As an example, the \mdl{sbc\_ana\_gyre} routine provides the analytical forcing for the GYRE configuration
+(see GYRE configuration manual, in preparation).
+% ================================================================
+% Flux formulation
+% ================================================================
+\section{Flux formulation (\protect\mdl{sbcflx})}
+The user can also choose in the \nam{sbc\_sas} namelist to read the mean (nn\_fsbc time-step) fraction of solar net radiation absorbed in the 1st T level using
+ (\np{ln\_flx}\forcode{=.true.}) and to provide 3D oceanic velocities instead of 2D ones (\np{ln\_flx}\forcode{=.true.}). In that last case, only the 1st level will be read in.
+% ================================================================
+% Flux formulation
+% ================================================================
+\section[Flux formulation (\textit{sbcflx.F90})]
+{Flux formulation (\protect\mdl{sbcflx})}
 \label{sec:SBC_flx}
 %------------------------------------------namsbc_flx----------------------------------------------------
+\nlst{namsbc_flx}
+\begin{listing}
+  \nlst{namsbc_flx}
+  \caption{\texttt{namsbc\_flx}}
+  \label{lst:namsbc_flx}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 In the flux formulation (\np{ln\_flx}\forcode{ = .true.}),
+In the flux formulation (\np{ln\_flx}\forcode{=.true.}),
 the surface boundary condition fields are directly read from input files.
 The user has to define in the namelist \ngn{namsbc{\_}flx} the name of the file,
+The user has to define in the namelist \nam{sbc\_flx} the name of the file,
 the name of the variable read in the file, the time frequency at which it is given (in hours),
 and a logical setting whether a time interpolation to the model time step is required for this field.
 …
 % ================================================================
 % Bulk formulation
 % ================================================================
 \section[Bulk formulation {(\textit{sbcblk\{\_core,\_clio\}.F90})}]
                         {Bulk formulation {(\protect\mdl{sbcblk\_core}, \protect\mdl{sbcblk\_clio})}}
+\section[Bulk formulation (\textit{sbcblk.F90})]
+{Bulk formulation (\protect\mdl{sbcblk})}
 \label{sec:SBC_blk}
+In the bulk formulation, the surface boundary condition fields are computed using bulk formulae and atmospheric fields and ocean (and ice) variables.
+%---------------------------------------namsbc_blk--------------------------------------------------
+\begin{listing}
+  \nlst{namsbc_blk}
+  \caption{\texttt{namsbc\_blk}}
+  \label{lst:namsbc_blk}
+\end{listing}
+%--------------------------------------------------------------------------------------------------------------
+In the bulk formulation, the surface boundary condition fields are computed with bulk formulae using atmospheric fields
+and ocean (and sea-ice) variables averaged over \np{nn\_fsbc} time-step.
 The atmospheric fields used depend on the bulk formulae used.
+Two bulk formulations are available:
+the CORE and the CLIO bulk formulea.
+In forced mode, when a sea-ice model is used, a specific bulk formulation is used.
+Therefore, different bulk formulae are used for the turbulent fluxes computation
+over the ocean and over sea-ice surface.
+For the ocean, four bulk formulations are available thanks to the \href{https://brodeau.github.io/aerobulk/}{Aerobulk} package (\citet{brodeau.barnier.ea_JPO16}):
+the NCAR (formerly named CORE), COARE 3.0, COARE 3.5 and ECMWF bulk formulae.
 The choice is made by setting to true one of the following namelist variable:
+\np{ln\_core} or \np{ln\_clio}.
+Note:
+in forced mode, when a sea-ice model is used, a bulk formulation (CLIO or CORE) have to be used.
+Therefore the two bulk (CLIO and CORE) formulea include the computation of the fluxes over
+both an ocean and an ice surface.
+% -------------------------------------------------------------------------------------------------------------
+%        CORE Bulk formulea
+% -------------------------------------------------------------------------------------------------------------
+\subsection{CORE formulea (\protect\mdl{sbcblk\_core}, \protect\np{ln\_core}\forcode{ = .true.})}
+\label{subsec:SBC_blk_core}
+%------------------------------------------namsbc_core----------------------------------------------------
+%
+%\nlst{namsbc_core}
+%-------------------------------------------------------------------------------------------------------------
+The CORE bulk formulae have been developed by \citet{Large_Yeager_Rep04}.
+They have been designed to handle the CORE forcing, a mixture of NCEP reanalysis and satellite data.
+They use an inertial dissipative method to compute the turbulent transfer coefficients
+(momentum, sensible heat and evaporation) from the 10 metre wind speed, air temperature and specific humidity.
+This \citet{Large_Yeager_Rep04} dataset is available through
+the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/CORE.html}{GFDL web site}.
+Note that substituting ERA40 to NCEP reanalysis fields does not require changes in the bulk formulea themself.
+This is the so-called DRAKKAR Forcing Set (DFS) \citep{Brodeau_al_OM09}.
+Options are defined through the  \ngn{namsbc\_core} namelist variables.
+The required 8 input fields are:
+ \np{ln\_NCAR}, \np{ln\_COARE\_3p0},  \np{ln\_COARE\_3p5} and  \np{ln\_ECMWF}.
+For sea-ice, three possibilities can be selected:
+a constant transfer coefficient (1.4e-3; default value), \citet{lupkes.gryanik.ea_JGR12} (\np{ln\_Cd\_L12}), and \citet{lupkes.gryanik_JGR15} (\np{ln\_Cd\_L15}) parameterizations
+Common options are defined through the \nam{sbc\_blk} namelist variables.
+The required 9 input fields are:
 %--------------------------------------------------TABLE--------------------------------------------------
 \begin{table}[htbp]
+  \label{tab:CORE}
+  \begin{center}
+    \begin{tabular}{|l|c|c|c|}
+      \hline
+      Variable desciption              & Model variable  & Units   & point \\    \hline
+      i-component of the 10m air velocity & utau      & $m.s^{-1}$         & T  \\  \hline
+      j-component of the 10m air velocity & vtau      & $m.s^{-1}$         & T  \\  \hline
+m air temperature              & tair      & \r{}$K$            & T   \\ \hline
+      Specific humidity             & humi      & \%              & T \\      \hline
+      Incoming long wave radiation     & qlw    & $W.m^{-2}$         & T \\      \hline
+      Incoming short wave radiation    & qsr    & $W.m^{-2}$         & T \\      \hline
+      Total precipitation (liquid + solid)   & precip & $Kg.m^{-2}.s^{-1}$ & T \\   \hline
+      Solid precipitation              & snow      & $Kg.m^{-2}.s^{-1}$ & T \\   \hline
+  \centering
+  \begin{tabular}{|l|c|c|c|}
+    \hline
+    Variable description                 & Model variable & Units              & point \\
+    \hline
+    i-component of the 10m air velocity  & utau           & $m.s^{-1}$         & T     \\
+    \hline
+    j-component of the 10m air velocity  & vtau           & $m.s^{-1}$         & T     \\
+    \hline
+m air temperature                  & tair           & \r{}$K$            & T     \\
+    \hline
+    Specific humidity                    & humi           & \%                 & T     \\
+    \hline
+    Incoming long wave radiation         & qlw            & $W.m^{-2}$         & T     \\
+    \hline
+    Incoming short wave radiation        & qsr            & $W.m^{-2}$         & T     \\
+    \hline
+    Total precipitation (liquid + solid) & precip         & $Kg.m^{-2}.s^{-1}$ & T     \\
+    \hline
+    Solid precipitation                  & snow           & $Kg.m^{-2}.s^{-1}$ & T     \\
+    \hline
+    Mean sea-level pressure              & slp            & $hPa$              & T     \\
+    \hline
     \end{tabular}
   \end{center}
+  \label{tab:SBC_BULK}
 \end{table}
 %--------------------------------------------------------------------------------------------------------------
 …
 The \np{sn\_wndi}, \np{sn\_wndj}, \np{sn\_qsr}, \np{sn\_qlw}, \np{sn\_tair}, \np{sn\_humi}, \np{sn\_prec},
 \np{sn\_snow}, \np{sn\_tdif} parameters describe the fields and the way they have to be used
 (spatial and temporal interpolations).
+(spatial and temporal interpolations).
 \np{cn\_dir} is the directory of location of bulk files
 …
 \np{rn\_zu}: is the height of wind measurements (m)
 Three multiplicative factors are availables:
 \np{rn\_pfac} and \np{rn\_efac} allows to adjust (if necessary) the global freshwater budget by
+Three multiplicative factors are available:
+\np{rn\_pfac} and \np{rn\_efac} allow to adjust (if necessary) the global freshwater budget by
 increasing/reducing the precipitations (total and snow) and or evaporation, respectively.
 The third one,\np{rn\_vfac}, control to which extend the ice/ocean velocities are taken into account in
 the calculation of surface wind stress.
+Its range should be between zero and one, and it is recommended to set it to 0.
+% -------------------------------------------------------------------------------------------------------------
+%        CLIO Bulk formulea
+% -------------------------------------------------------------------------------------------------------------
+\subsection{CLIO formulea (\protect\mdl{sbcblk\_clio}, \protect\np{ln\_clio}\forcode{ = .true.})}
+\label{subsec:SBC_blk_clio}
+%------------------------------------------namsbc_clio----------------------------------------------------
+%
+%\nlst{namsbc_clio}
+%-------------------------------------------------------------------------------------------------------------
+The CLIO bulk formulae were developed several years ago for the Louvain-la-neuve coupled ice-ocean model
+(CLIO, \cite{Goosse_al_JGR99}).
+They are simpler bulk formulae.
+They assume the stress to be known and compute the radiative fluxes from a climatological cloud cover.
+Options are defined through the  \ngn{namsbc\_clio} namelist variables.
+The required 7 input fields are:
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[htbp]
+  \label{tab:CLIO}
+  \begin{center}
+    \begin{tabular}{|l|l|l|l|}
+      \hline
+      Variable desciption           & Model variable  & Units           & point \\  \hline
+      i-component of the ocean stress     & utau         & $N.m^{-2}$         & U \\   \hline
+      j-component of the ocean stress     & vtau         & $N.m^{-2}$         & V \\   \hline
+      Wind speed module             & vatm         & $m.s^{-1}$         & T \\   \hline
+m air temperature              & tair         & \r{}$K$            & T \\   \hline
+      Specific humidity                & humi         & \%              & T \\   \hline
+      Cloud cover                   &           & \%              & T \\   \hline
+      Total precipitation (liquid + solid)   & precip    & $Kg.m^{-2}.s^{-1}$ & T \\   \hline
+      Solid precipitation              & snow         & $Kg.m^{-2}.s^{-1}$ & T \\   \hline
+    \end{tabular}
+  \end{center}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+Its range must be between zero and one, and it is recommended to set it to 0 at low-resolution (ORCA2 configuration).
 As for the flux formulation, information about the input data required by the model is provided in
+the namsbc\_blk\_core or namsbc\_blk\_clio namelist (see \autoref{subsec:SBC_fldread}).
+the namsbc\_blk namelist (see \autoref{subsec:SBC_fldread}).
+% -------------------------------------------------------------------------------------------------------------
+%        Ocean-Atmosphere Bulk formulae
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Ocean-Atmosphere Bulk formulae (\textit{sbcblk\_algo\_coare.F90, sbcblk\_algo\_coare3p5.F90,
+sbcblk\_algo\_ecmwf.F90, sbcblk\_algo\_ncar.F90})]
+{Ocean-Atmosphere Bulk formulae (\mdl{sbcblk\_algo\_coare}, \mdl{sbcblk\_algo\_coare3p5},
+\mdl{sbcblk\_algo\_ecmwf}, \mdl{sbcblk\_algo\_ncar})}
+\label{subsec:SBC_blk_ocean}
+Four different bulk algorithms are available to compute surface turbulent momentum and heat fluxes over the ocean.
+COARE 3.0, COARE 3.5 and ECMWF schemes mainly differ by their roughness lenghts computation and consequently
+their neutral transfer coefficients relationships with neutral wind.
+\begin{itemize}
+\item
+  NCAR (\np{ln\_NCAR}\forcode{=.true.}):
+  The NCAR bulk formulae have been developed by \citet{large.yeager_rpt04}.
+  They have been designed to handle the NCAR forcing, a mixture of NCEP reanalysis and satellite data.
+  They use an inertial dissipative method to compute the turbulent transfer coefficients
+  (momentum, sensible heat and evaporation) from the 10m wind speed, air temperature and specific humidity.
+  This \citet{large.yeager_rpt04} dataset is available through
+  the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/NCAR.html}{GFDL web site}.
+  Note that substituting ERA40 to NCEP reanalysis fields does not require changes in the bulk formulea themself.
+  This is the so-called DRAKKAR Forcing Set (DFS) \citep{brodeau.barnier.ea_OM10}.
+\item
+  COARE 3.0 (\np{ln\_COARE\_3p0}\forcode{=.true.}):
+  See \citet{fairall.bradley.ea_JC03} for more details
+\item
+  COARE 3.5 (\np{ln\_COARE\_3p5}\forcode{=.true.}):
+  See \citet{edson.jampana.ea_JPO13} for more details
+\item
+  ECMWF (\np{ln\_ECMWF}\forcode{=.true.}):
+  Based on \href{https://www.ecmwf.int/node/9221}{IFS (Cy31)} implementation and documentation.
+  Surface roughness lengths needed for the Obukhov length are computed following \citet{beljaars_QJRMS95}.
+\end{itemize}
+% -------------------------------------------------------------------------------------------------------------
+%        Ice-Atmosphere Bulk formulae
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Ice-Atmosphere Bulk formulae}
+\label{subsec:SBC_blk_ice}
+Surface turbulent fluxes between sea-ice and the atmosphere can be computed in three different ways:
+\begin{itemize}
+\item
+  Constant value (\np{constant\ value}\forcode{ Cd_ice = 1.4e-3 }):
+  default constant value used for momentum and heat neutral transfer coefficients
+\item
+  \citet{lupkes.gryanik.ea_JGR12} (\np{ln\_Cd\_L12}\forcode{=.true.}):
+  This scheme adds a dependency on edges at leads, melt ponds and flows
+  of the constant neutral air-ice drag. After some approximations,
+  this can be resumed to a dependency on ice concentration (A).
+  This drag coefficient has a parabolic shape (as a function of ice concentration)
+  starting at 1.5e-3 for A=0, reaching 1.97e-3 for A=0.5 and going down 1.4e-3 for A=1.
+  It is theoretically applicable to all ice conditions (not only MIZ).
+\item
+  \citet{lupkes.gryanik_JGR15} (\np{ln\_Cd\_L15}\forcode{=.true.}):
+  Alternative turbulent transfer coefficients formulation between sea-ice
+  and atmosphere with distinct momentum and heat coefficients depending
+  on sea-ice concentration and atmospheric stability (no melt-ponds effect for now).
+  The parameterization is adapted from ECHAM6 atmospheric model.
+  Compared to Lupkes2012 scheme, it considers specific skin and form drags
+  to compute neutral transfer coefficients for both heat and momentum fluxes.
+  Atmospheric stability effect on transfer coefficient is also taken into account.
+\end{itemize}
 % ================================================================
 % Coupled formulation
 % ================================================================
+\section{Coupled formulation (\protect\mdl{sbccpl})}
+\section[Coupled formulation (\textit{sbccpl.F90})]
+{Coupled formulation (\protect\mdl{sbccpl})}
 \label{sec:SBC_cpl}
 %------------------------------------------namsbc_cpl----------------------------------------------------
+\nlst{namsbc_cpl}
+\begin{listing}
+  \nlst{namsbc_cpl}
+  \caption{\texttt{namsbc\_cpl}}
+  \label{lst:namsbc_cpl}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 In the coupled formulation of the surface boundary condition,
 the fluxes are provided by the OASIS coupler at a frequency which is defined in the OASIS coupler,
+the fluxes are provided by the OASIS coupler at a frequency which is defined in the OASIS coupler namelist,
 while sea and ice surface temperature, ocean and ice albedo, and ocean currents are sent to
 the atmospheric component.
 A generalised coupled interface has been developed.
+It is currently interfaced with OASIS-3-MCT (\key{oasis3}).
+It has been successfully used to interface \NEMO to most of the European atmospheric GCM
+It is currently interfaced with OASIS-3-MCT versions 1 to 4 (\key{oasis3}).
+An additional specific CPP key (\key{oa3mct\_v1v2}) is needed for OASIS-3-MCT versions 1 and 2.
+It has been successfully used to interface \NEMO\ to most of the European atmospheric GCM
 (ARPEGE, ECHAM, ECMWF, HadAM, HadGAM, LMDz), as well as to \href{http://wrf-model.org/}{WRF}
 (Weather Research and Forecasting Model).
+Note that in addition to the setting of \np{ln\_cpl} to true, the \key{coupled} have to be defined.
+The CPP key is mainly used in sea-ice to ensure that the atmospheric fluxes are actually received by
+the ice-ocean system (no calculation of ice sublimation in coupled mode).
+When PISCES biogeochemical model (\key{top} and \key{pisces}) is also used in the coupled system,
+the whole carbon cycle is computed by defining \key{cpl\_carbon\_cycle}.
+When PISCES biogeochemical model (\key{top}) is also used in the coupled system,
+the whole carbon cycle is computed.
 In this case, CO$_2$ fluxes will be exchanged between the atmosphere and the ice-ocean system
 (and need to be activated in \ngn{namsbc{\_}cpl} ).
+(and need to be activated in \nam{sbc\_cpl} ).
 The namelist above allows control of various aspects of the coupling fields (particularly for vectors) and
 now allows for any coupling fields to have multiple sea ice categories (as required by LIM3 and CICE).
 When indicating a multi-category coupling field in namsbc{\_}cpl the number of categories will be determined by
+When indicating a multi-category coupling field in \nam{sbc\_cpl}, the number of categories will be determined by
 the number used in the sea ice model.
 In some limited cases it may be possible to specify single category coupling fields even when
+In some limited cases, it may be possible to specify single category coupling fields even when
 the sea ice model is running with multiple categories -
+in this case the user should examine the code to be sure the assumptions made are satisfactory.
+In cases where this is definitely not possible the model should abort with an error message.
+The new code has been tested using ECHAM with LIM2, and HadGAM3 with CICE but
+although it will compile with \key{lim3} additional minor code changes may be required to run using LIM3.
+in this case, the user should examine the code to be sure the assumptions made are satisfactory.
+In cases where this is definitely not possible, the model should abort with an error message.
 …
 %        Atmospheric pressure
 % ================================================================
+\section{Atmospheric pressure (\protect\mdl{sbcapr})}
+\section[Atmospheric pressure (\textit{sbcapr.F90})]
+{Atmospheric pressure (\protect\mdl{sbcapr})}
 \label{sec:SBC_apr}
 %------------------------------------------namsbc_apr----------------------------------------------------
+\nlst{namsbc_apr}
+\begin{listing}
+  \nlst{namsbc_apr}
+  \caption{\texttt{namsbc\_apr}}
+  \label{lst:namsbc_apr}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 The optional atmospheric pressure can be used to force ocean and ice dynamics
 (\np{ln\_apr\_dyn}\forcode{ = .true.}, \textit{\ngn{namsbc}} namelist).
 The input atmospheric forcing defined via \np{sn\_apr} structure (\textit{namsbc\_apr} namelist)
+(\np{ln\_apr\_dyn}\forcode{=.true.}, \nam{sbc} namelist).
+The input atmospheric forcing defined via \np{sn\_apr} structure (\nam{sbc\_apr} namelist)
 can be interpolated in time to the model time step, and even in space when the interpolation on-the-fly is used.
 When used to force the dynamics, the atmospheric pressure is further transformed into
 …
 where $P_{atm}$ is the atmospheric pressure and $P_o$ a reference atmospheric pressure.
 A value of $101,000~N/m^2$ is used unless \np{ln\_ref\_apr} is set to true.
 In this case $P_o$ is set to the value of $P_{atm}$ averaged over the ocean domain,
 \ie the mean value of $\eta_{ib}$ is kept to zero at all time step.
+In this case, $P_o$ is set to the value of $P_{atm}$ averaged over the ocean domain,
+\ie\ the mean value of $\eta_{ib}$ is kept to zero at all time steps.
 The gradient of $\eta_{ib}$ is added to the RHS of the ocean momentum equation (see \mdl{dynspg} for the ocean).
 For sea-ice, the sea surface height, $\eta_m$, which is provided to the sea ice model is set to $\eta - \eta_{ib}$
 (see \mdl{sbcssr} module).
 $\eta_{ib}$ can be set in the output.
+$\eta_{ib}$ can be written in the output.
 This can simplify altimetry data and model comparison as
 inverse barometer sea surface height is usually removed from these date prior to their distribution.
 When using time-splitting and BDY package for open boundaries conditions,
 the equivalent inverse barometer sea surface height $\eta_{ib}$ can be added to BDY ssh data:
+the equivalent inverse barometer sea surface height $\eta_{ib}$ can be added to BDY ssh data:
 \np{ln\_apr\_obc}  might be set to true.
 % ================================================================
 %        Surface Tides Forcing
 % ================================================================
+\section{Surface tides (\protect\mdl{sbctide})}
+\section[Surface tides (\textit{sbctide.F90})]
+{Surface tides (\protect\mdl{sbctide})}
 \label{sec:SBC_tide}
 %------------------------------------------nam_tide---------------------------------------
+\nlst{nam_tide}
+\begin{listing}
+  \nlst{nam_tide}
+  \caption{\texttt{nam\_tide}}
+  \label{lst:nam_tide}
+\end{listing}
 %-----------------------------------------------------------------------------------------
 The tidal forcing, generated by the gravity forces of the Earth-Moon and Earth-Sun sytems,
 is activated if \np{ln\_tide} and \np{ln\_tide\_pot} are both set to \forcode{.true.} in \ngn{nam\_tide}.
 This translates as an additional barotropic force in the momentum equations \ref{eq:PE_dyn} such that:
+is activated if \np{ln\_tide} and \np{ln\_tide\_pot} are both set to \forcode{.true.} in \nam{\_tide}.
+This translates as an additional barotropic force in the momentum \autoref{eq:MB_PE_dyn} such that:
 \[
   % \label{eq:PE_dyn_tides}
   \frac{\partial {\rm {\bf U}}_h }{\partial t}= ...
+  % \label{eq:SBC_PE_dyn_tides}
+  \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= ...
   +g\nabla (\Pi_{eq} + \Pi_{sal})
 \]
 where $\Pi_{eq}$ stands for the equilibrium tidal forcing and
 $\Pi_{sal}$ is a self-attraction and loading term (SAL).
 The equilibrium tidal forcing is expressed as a sum over a subset of
 constituents chosen from the set of available tidal constituents
 defined in file \rou{SBC/tide.h90} (this comprises the tidal
+defined in file \hf{SBC/tide} (this comprises the tidal
 constituents \textit{M2, N2, 2N2, S2, K2, K1, O1, Q1, P1, M4, Mf, Mm,
   Msqm, Mtm, S1, MU2, NU2, L2}, and \textit{T2}). Individual
 constituents are selected by including their names in the array
 \np{clname} in \ngn{nam\_tide} (e.g., \np{clname(1) = 'M2',
   clname(2)='S2'} to select solely the tidal consituents \textit{M2}
+\np{clname} in \nam{\_tide} (e.g., \np{clname}\forcode{(1)='M2', }
+\np{clname}\forcode{(2)='S2'} to select solely the tidal consituents \textit{M2}
 and \textit{S2}). Optionally, when \np{ln\_tide\_ramp} is set to
 \forcode{.true.}, the equilibrium tidal forcing can be ramped up
 …
 The SAL term should in principle be computed online as it depends on
 the model tidal prediction itself (see \citet{Arbic2004} for a
+the model tidal prediction itself (see \citet{arbic.garner.ea_DSR04} for a
 discussion about the practical implementation of this term).
 Nevertheless, the complex calculations involved would make this
 computationally too expensive.  Here, two options are available:
+computationally too expensive. Here, two options are available:
 $\Pi_{sal}$ generated by an external model can be read in
 (\np{ln\_read\_load=.true.}), or a ``scalar approximation'' can be
 used (\np{ln\_scal\_load=.true.}). In the latter case
+(\np{ln\_read\_load}\forcode{ =.true.}), or a ``scalar approximation'' can be
+used (\np{ln\_scal\_load}\forcode{ =.true.}). In the latter case
 \[
   \Pi_{sal} = \beta \eta,
 …
 \forcode{.false.} removes the SAL contribution.
 % ================================================================
 %        River runoffs
 % ================================================================
 \section{River runoffs (\protect\mdl{sbcrnf})}
+\section[River runoffs (\textit{sbcrnf.F90})]{River runoffs (\protect\mdl{sbcrnf})}
 \label{sec:SBC_rnf}
 %------------------------------------------namsbc_rnf----------------------------------------------------
+\nlst{namsbc_rnf}
+\begin{listing}
+  \nlst{namsbc_rnf}
+  \caption{\texttt{namsbc\_rnf}}
+  \label{lst:namsbc_rnf}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 %River runoff generally enters the ocean at a nonzero depth rather than through the surface.
+%River runoff generally enters the ocean at a nonzero depth rather than through the surface.
 %Many models, however, have traditionally inserted river runoff to the top model cell.
 %This was the case in \NEMO prior to the version 3.3. The switch toward a input of runoff
 %throughout a nonzero depth has been motivated by the numerical and physical problems
 %that arise when the top grid cells are of the order of one meter. This situation is common in
 %coastal modelling and becomes more and more often open ocean and climate modelling
+%This was the case in \NEMO\ prior to the version 3.3. The switch toward a input of runoff
+%throughout a nonzero depth has been motivated by the numerical and physical problems
+%that arise when the top grid cells are of the order of one meter. This situation is common in
+%coastal modelling and becomes more and more often open ocean and climate modelling
 %\footnote{At least a top cells thickness of 1~meter and a 3 hours forcing frequency are
 %required to properly represent the diurnal cycle \citep{Bernie_al_JC05}. see also \autoref{fig:SBC_dcy}.}.
 %To do this we need to treat evaporation/precipitation fluxes and river runoff differently in the
 %\mdl{tra\_sbc} module.  We decided to separate them throughout the code, so that the variable
 %\textit{emp} represented solely evaporation minus precipitation fluxes, and a new 2d variable
 %rnf was added which represents the volume flux of river runoff (in kg/m2s to remain consistent with
 %emp).  This meant many uses of emp and emps needed to be changed, a list of all modules which use
+%required to properly represent the diurnal cycle \citep{bernie.woolnough.ea_JC05}. see also \autoref{fig:SBC_dcy}.}.
+%To do this we need to treat evaporation/precipitation fluxes and river runoff differently in the
+%\mdl{tra\_sbc} module.  We decided to separate them throughout the code, so that the variable
+%\textit{emp} represented solely evaporation minus precipitation fluxes, and a new 2d variable
+%rnf was added which represents the volume flux of river runoff (in kg/m2s to remain consistent with
+%emp).  This meant many uses of emp and emps needed to be changed, a list of all modules which use
 %emp or emps and the changes made are below:
 …
 River runoff generally enters the ocean at a nonzero depth rather than through the surface.
 Many models, however, have traditionally inserted river runoff to the top model cell.
 This was the case in \NEMO prior to the version 3.3,
+This was the case in \NEMO\ prior to the version 3.3,
 and was combined with an option to increase vertical mixing near the river mouth.
 However, with this method numerical and physical problems arise when the top grid cells are of the order of one meter.
 This situation is common in coastal modelling and is becoming more common in open ocean and climate modelling
+This situation is common in coastal modelling and is becoming more common in open ocean and climate modelling
 \footnote{
   At least a top cells thickness of 1~meter and a 3 hours forcing frequency are required to
   properly represent the diurnal cycle \citep{Bernie_al_JC05}.
+  properly represent the diurnal cycle \citep{bernie.woolnough.ea_JC05}.
   see also \autoref{fig:SBC_dcy}.}.
 …
 along with the depth (in metres) which the river should be added to.
 Namelist variables in \ngn{namsbc\_rnf}, \np{ln\_rnf\_depth}, \np{ln\_rnf\_sal} and
+Namelist variables in \nam{sbc\_rnf}, \np{ln\_rnf\_depth}, \np{ln\_rnf\_sal} and
 \np{ln\_rnf\_temp} control whether the river attributes (depth, salinity and temperature) are read in and used.
 If these are set as false the river is added to the surface box only, assumed to be fresh (0~psu),
 and/or taken as surface temperature respectively.
 The runoff value and attributes are read in in sbcrnf.
+The runoff value and attributes are read in in sbcrnf.
 For temperature -999 is taken as missing data and the river temperature is taken to
 be the surface temperatue at the river point.
 For the depth parameter a value of -1 means the river is added to the surface box only,
 and a value of -999 means the river is added through the entire water column.
+For the depth parameter a value of -1 means the river is added to the surface box only,
+and a value of -999 means the river is added through the entire water column.
 After being read in the temperature and salinity variables are multiplied by the amount of runoff
 (converted into m/s) to give the heat and salt content of the river runoff.
 …
 The variable \textit{h\_dep} is then calculated to be the depth (in metres) of
 the bottom of the lowest box the river water is being added to
 (\ie the total depth that river water is being added to in the model).
+(\ie\ the total depth that river water is being added to in the model).
 The mass/volume addition due to the river runoff is, at each relevant depth level, added to
 …
 This increases the diffusion term in the vicinity of the river, thereby simulating a momentum flux.
 The sea surface height is calculated using the sum of the horizontal divergence terms,
 and so the river runoff indirectly forces an increase in sea surface height.
+and so the river runoff indirectly forces an increase in sea surface height.
 The \textit{hdivn} terms are used in the tracer advection modules to force vertical velocities.
 …
 As such the volume of water does not change, but the water is diluted.
 For the non-linear free surface case (\key{vvl}), no flux is allowed through the surface.
+For the non-linear free surface case, no flux is allowed through the surface.
 Instead in the surface box (as well as water moving up from the boxes below) a volume of runoff water is added with
 no corresponding heat and salt addition and so as happens in the lower boxes there is a dilution effect.
 …
 This is done in the same way for both vvl and non-vvl.
 The temperature and salinity are increased through the specified depth according to
 the heat and salt content of the river.
+the heat and salt content of the river.
 In the non-linear free surface case (vvl),
 …
 It is also possible for runnoff to be specified as a negative value for modelling flow through straits,
 \ie modelling the Baltic flow in and out of the North Sea.
+\ie\ modelling the Baltic flow in and out of the North Sea.
 When the flow is out of the domain there is no change in temperature and salinity,
 regardless of the namelist options used,
 as the ocean water leaving the domain removes heat and salt (at the same concentration) with it.
 %\colorbox{yellow}{Nevertheless, Pb of vertical resolution and 3D input : increase vertical mixing near river mouths to mimic a 3D river
+as the ocean water leaving the domain removes heat and salt (at the same concentration) with it.
+%\colorbox{yellow}{Nevertheless, Pb of vertical resolution and 3D input : increase vertical mixing near river mouths to mimic a 3D river
 %All river runoff and emp fluxes are assumed to be fresh water (zero salinity) and at the same temperature as the sea surface.}
 …
 %\gmcomment{  word doc of runoffs:
+%
 %In the current \NEMO setup river runoff is added to emp fluxes, these are then applied at just the sea surface as a volume change (in the variable volume case this is a literal volume change, and in the linear free surface case the free surface is moved) and a salt flux due to the concentration/dilution effect.  There is also an option to increase vertical mixing near river mouths; this gives the effect of having a 3d river.  All river runoff and emp fluxes are assumed to be fresh water (zero salinity) and at the same temperature as the sea surface.
 %Our aim was to code the option to specify the temperature and salinity of river runoff, (as well as the amount), along with the depth that the river water will affect.  This would make it possible to model low salinity outflow, such as the Baltic, and would allow the ocean temperature to be affected by river runoff.
+%In the current \NEMO\ setup river runoff is added to emp fluxes, these are then applied at just the sea surface as a volume change (in the variable volume case this is a literal volume change, and in the linear free surface case the free surface is moved) and a salt flux due to the concentration/dilution effect.  There is also an option to increase vertical mixing near river mouths; this gives the effect of having a 3d river.  All river runoff and emp fluxes are assumed to be fresh water (zero salinity) and at the same temperature as the sea surface.
+%Our aim was to code the option to specify the temperature and salinity of river runoff, (as well as the amount), along with the depth that the river water will affect.  This would make it possible to model low salinity outflow, such as the Baltic, and would allow the ocean temperature to be affected by river runoff.
 %The depth option makes it possible to have the river water affecting just the surface layer, throughout depth, or some specified point in between.
 …
 %To do this we need to treat evaporation/precipitation fluxes and river runoff differently in the tra_sbc module.  We decided to separate them throughout the code, so that the variable emp represented solely evaporation minus precipitation fluxes, and a new 2d variable rnf was added which represents the volume flux of river runoff (in kg/m2s to remain consistent with emp).  This meant many uses of emp and emps needed to be changed, a list of all modules which use emp or emps and the changes made are below:
+%}
 % ================================================================
 %        Ice shelf melting
 % ================================================================
 \section{Ice shelf melting (\protect\mdl{sbcisf})}
+\section[Ice shelf melting (\textit{sbcisf.F90})]{Ice shelf melting (\protect\mdl{sbcisf})}
 \label{sec:SBC_isf}
 %------------------------------------------namsbc_isf----------------------------------------------------
+\nlst{namsbc_isf}
+\begin{listing}
+  \nlst{namsbc_isf}
+  \caption{\texttt{namsbc\_isf}}
+  \label{lst:namsbc_isf}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------
+The namelist variable in \ngn{namsbc}, \np{nn\_isf}, controls the ice shelf representation.
+Description and result of sensitivity test to \np{nn\_isf} are presented in \citet{Mathiot2017}.
+The namelist variable in \nam{sbc}, \np{nn\_isf}, controls the ice shelf representation.
+Description and result of sensitivity test to \np{nn\_isf} are presented in \citet{mathiot.jenkins.ea_GMD17}.
 The different options are illustrated in \autoref{fig:SBC_isf}.
 \begin{description}
+\item[\np{nn\_isf}\forcode{ = 1}]:
+  The ice shelf cavity is represented (\np{ln\_isfcav}\forcode{ = .true.} needed).
+  \item[\np{nn\_isf}\forcode{=1}]:
+  The ice shelf cavity is represented (\np{ln\_isfcav}\forcode{=.true.} needed).
   The fwf and heat flux are depending of the local water properties.
   Two different bulk formulae are available:
    \begin{description}
    \item[\np{nn\_isfblk}\forcode{ = 1}]:
+   \item[\np{nn\_isfblk}\forcode{=1}]:
      The melt rate is based on a balance between the upward ocean heat flux and
      the latent heat flux at the ice shelf base. A complete description is available in \citet{Hunter2006}.
    \item[\np{nn\_isfblk}\forcode{ = 2}]:
+     the latent heat flux at the ice shelf base. A complete description is available in \citet{hunter_rpt06}.
+   \item[\np{nn\_isfblk}\forcode{=2}]:
      The melt rate and the heat flux are based on a 3 equations formulation
      (a heat flux budget at the ice base, a salt flux budget at the ice base and a linearised freezing point temperature equation).
      A complete description is available in \citet{Jenkins1991}.
+     (a heat flux budget at the ice base, a salt flux budget at the ice base and a linearised freezing point temperature equation).
+     A complete description is available in \citet{jenkins_JGR91}.
    \end{description}
      Temperature and salinity used to compute the melt are the average temperature in the top boundary layer \citet{Losch2008}.
+     Temperature and salinity used to compute the melt are the average temperature in the top boundary layer \citet{losch_JGR08}.
      Its thickness is defined by \np{rn\_hisf\_tbl}.
      The fluxes and friction velocity are computed using the mean temperature, salinity and velocity in the the first \np{rn\_hisf\_tbl} m.
 …
      If \np{rn\_hisf\_tbl} smaller than top $e_{3}t$, the top boundary layer thickness is set to the top cell thickness.\\
      Each melt bulk formula depends on a exchange coeficient ($\Gamma^{T,S}$) between the ocean and the ice.
+     Each melt bulk formula depends on a exchange coeficient ($\Gamma^{T,S}$) between the ocean and the ice.
      There are 3 different ways to compute the exchange coeficient:
    \begin{description}
+        \item[\np{nn\_gammablk}\forcode{ = 0}]:
+     The salt and heat exchange coefficients are constant and defined by \np{rn\_gammas0} and \np{rn\_gammat0}.
+\[
+  % \label{eq:sbc_isf_gamma_iso}
+\gamma^{T} = \np{rn\_gammat0}
+\]
+\[
+\gamma^{S} = \np{rn\_gammas0}
+\]
+        \item[\np{nn\_gammablk}\forcode{=0}]:
+     The salt and heat exchange coefficients are constant and defined by \np{rn\_gammas0} and \np{rn\_gammat0}.
+     \begin{gather*}
+       % \label{eq:SBC_isf_gamma_iso}
+       \gamma^{T} = rn\_gammat0 \\
+       \gamma^{S} = rn\_gammas0
+     \end{gather*}
      This is the recommended formulation for ISOMIP.
    \item[\np{nn\_gammablk}\forcode{ = 1}]:
+   \item[\np{nn\_gammablk}\forcode{=1}]:
      The salt and heat exchange coefficients are velocity dependent and defined as
+\[
+\gamma^{T} = \np{rn\_gammat0} \times u_{*}
+\]
+\[
+\gamma^{S} = \np{rn\_gammas0} \times u_{*}
+\]
+     \begin{gather*}
+       \gamma^{T} = rn\_gammat0 \times u_{*} \\
+       \gamma^{S} = rn\_gammas0 \times u_{*}
+     \end{gather*}
      where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters).
      See \citet{Jenkins2010} for all the details on this formulation. It is the recommended formulation for realistic application.
    \item[\np{nn\_gammablk}\forcode{ = 2}]:
+     See \citet{jenkins.nicholls.ea_JPO10} for all the details on this formulation. It is the recommended formulation for realistic application.
+   \item[\np{nn\_gammablk}\forcode{=2}]:
      The salt and heat exchange coefficients are velocity and stability dependent and defined as:
 \[
 \gamma^{T,S} = \frac{u_{*}}{\Gamma_{Turb} + \Gamma^{T,S}_{Mole}}
+\gamma^{T,S} = \frac{u_{*}}{\Gamma_{Turb} + \Gamma^{T,S}_{Mole}}
 \]
      where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters),
      $\Gamma_{Turb}$ the contribution of the ocean stability and
      $\Gamma^{T,S}_{Mole}$ the contribution of the molecular diffusion.
      See \citet{Holland1999} for all the details on this formulation.
      This formulation has not been extensively tested in NEMO (not recommended).
+     See \citet{holland.jenkins_JPO99} for all the details on this formulation.
+     This formulation has not been extensively tested in \NEMO\ (not recommended).
    \end{description}
  \item[\np{nn\_isf}\forcode{ = 2}]:
+  \item[\np{nn\_isf}\forcode{=2}]:
    The ice shelf cavity is not represented.
    The fwf and heat flux are computed using the \citet{Beckmann2003} parameterisation of isf melting.
+   The fwf and heat flux are computed using the \citet{beckmann.goosse_OM03} parameterisation of isf melting.
    The fluxes are distributed along the ice shelf edge between the depth of the average grounding line (GL)
    (\np{sn\_depmax\_isf}) and the base of the ice shelf along the calving front
    (\np{sn\_depmin\_isf}) as in (\np{nn\_isf}\forcode{ = 3}).
+   (\np{sn\_depmin\_isf}) as in (\np{nn\_isf}\forcode{=3}).
    The effective melting length (\np{sn\_Leff\_isf}) is read from a file.
  \item[\np{nn\_isf}\forcode{ = 3}]:
+  \item[\np{nn\_isf}\forcode{=3}]:
    The ice shelf cavity is not represented.
    The fwf (\np{sn\_rnfisf}) is prescribed and distributed along the ice shelf edge between
 …
    the base of the ice shelf along the calving front (\np{sn\_depmin\_isf}).
    The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$.
  \item[\np{nn\_isf}\forcode{ = 4}]:
    The ice shelf cavity is opened (\np{ln\_isfcav}\forcode{ = .true.} needed).
+  \item[\np{nn\_isf}\forcode{=4}]:
+   The ice shelf cavity is opened (\np{ln\_isfcav}\forcode{=.true.} needed).
    However, the fwf is not computed but specified from file \np{sn\_fwfisf}).
    The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$.
    As in \np{nn\_isf}\forcode{ = 1}, the fluxes are spread over the top boundary layer thickness (\np{rn\_hisf\_tbl})\\
+   As in \np{nn\_isf}\forcode{=1}, the fluxes are spread over the top boundary layer thickness (\np{rn\_hisf\_tbl})\\
 \end{description}
 $\bullet$ \np{nn\_isf}\forcode{ = 1} and \np{nn\_isf}\forcode{ = 2} compute a melt rate based on
+$\bullet$ \np{nn\_isf}\forcode{=1} and \np{nn\_isf}\forcode{=2} compute a melt rate based on
 the water mass properties, ocean velocities and depth.
 This flux is thus highly dependent of the model resolution (horizontal and vertical),
 realism of the water masses onto the shelf ...\\
 $\bullet$ \np{nn\_isf}\forcode{ = 3} and \np{nn\_isf}\forcode{ = 4} read the melt rate from a file.
+$\bullet$ \np{nn\_isf}\forcode{=3} and \np{nn\_isf}\forcode{=4} read the melt rate from a file.
 You have total control of the fwf forcing.
 This can be useful if the water masses on the shelf are not realistic or
 the resolution (horizontal/vertical) are too coarse to have realistic melting or
 for studies where you need to control your heat and fw input.\\
+for studies where you need to control your heat and fw input.\\
 The ice shelf melt is implemented as a volume flux as for the runoff.
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=0.8\textwidth]{Fig_SBC_isf}
+    \caption{
+      \protect\label{fig:SBC_isf}
+      Illustration the location where the fwf is injected and whether or not the fwf is interactif or not depending of \np{nn\_isf}.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_SBC_isf}
+  \caption[Ice shelf location and fresh water flux definition]{
+    Illustration of the location where the fwf is injected and
+    whether or not the fwf is interactif or not depending of \protect\np{nn\_isf}.}
+  \label{fig:SBC_isf}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+% ================================================================
+%        Ice sheet coupling
+% ================================================================
 \section{Ice sheet coupling}
 \label{sec:SBC_iscpl}
 %------------------------------------------namsbc_iscpl----------------------------------------------------
+\nlst{namsbc_iscpl}
+\begin{listing}
+  \nlst{namsbc_iscpl}
+  \caption{\texttt{namsbc\_iscpl}}
+  \label{lst:namsbc_iscpl}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------
 Ice sheet/ocean coupling is done through file exchange at the restart step.
 At each restart step:
 \begin{description}
 \item[Step 1]: the ice sheet model send a new bathymetry and ice shelf draft netcdf file.
 \item[Step 2]: a new domcfg.nc file is built using the DOMAINcfg tools.
 \item[Step 3]: NEMO run for a specific period and output the average melt rate over the period.
+\item[Step 3]: \NEMO\ run for a specific period and output the average melt rate over the period.
 \item[Step 4]: the ice sheet model run using the melt rate outputed in step 4.
 \item[Step 5]: go back to 1.
 \end{description}
 If \np{ln\_iscpl}\forcode{ = .true.}, the isf draft is assume to be different at each restart step with
+If \np{ln\_iscpl}\forcode{=.true.}, the isf draft is assume to be different at each restart step with
 potentially some new wet/dry cells due to the ice sheet dynamics/thermodynamics.
 The wetting and drying scheme applied on the restart is very simple and described below for the 6 different possible cases:
 \begin{description}
 \item[Thin a cell down]:
 …
   mask, T/S, U/V and ssh are set to 0.
   Furthermore, U/V into the water column are modified to satisfy ($bt_b=bt_n$).
 \item[Wet a cell]:
+\item[Wet a cell]:
   mask is set to 1, T/S is extrapolated from neighbours, $ssh_n = ssh_b$ and U/V set to 0.
   If no neighbours, T/S is extrapolated from old top cell value.
+  If no neighbours, T/S is extrapolated from old top cell value.
   If no neighbours along i,j and k (both previous test failed), T/S/U/V/ssh and mask are set to 0.
 \item[Dry a column]:
 …
 The default number is set up for the MISOMIP idealised experiments.
 This coupling procedure is able to take into account grounding line and calving front migration.
 However, it is a non-conservative processe.
+However, it is a non-conservative processe.
 This could lead to a trend in heat/salt content and volume.\\
 In order to remove the trend and keep the conservation level as close to 0 as possible,
 a simple conservation scheme is available with \np{ln\_hsb}\forcode{ = .true.}.
+a simple conservation scheme is available with \np{ln\_hsb}\forcode{=.true.}.
 The heat/salt/vol. gain/loss is diagnosed, as well as the location.
 A correction increment is computed and apply each time step during the next \np{rn\_fiscpl} time steps.
+A correction increment is computed and apply each time step during the next \np{rn\_fiscpl} time steps.
 For safety, it is advised to set \np{rn\_fiscpl} equal to the coupling period (smallest increment possible).
 The corrective increment is apply into the cell itself (if it is a wet cell), the neigbouring cells or the closest wet cell (if the cell is now dry).
+%
 % ================================================================
 %        Handling of icebergs
 % ================================================================
 \section{Handling of icebergs (ICB)}
 \label{sec:ICB_icebergs}
+\label{sec:SBC_ICB_icebergs}
 %------------------------------------------namberg----------------------------------------------------
+\nlst{namberg}
+\begin{listing}
+  \nlst{namberg}
+  \caption{\texttt{namberg}}
+  \label{lst:namberg}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 Icebergs are modelled as lagrangian particles in NEMO \citep{Marsh_GMD2015}.
 Their physical behaviour is controlled by equations as described in \citet{Martin_Adcroft_OM10} ).
 (Note that the authors kindly provided a copy of their code to act as a basis for implementation in NEMO).
+Icebergs are modelled as lagrangian particles in \NEMO\ \citep{marsh.ivchenko.ea_GMD15}.
+Their physical behaviour is controlled by equations as described in \citet{martin.adcroft_OM10} ).
+(Note that the authors kindly provided a copy of their code to act as a basis for implementation in \NEMO).
 Icebergs are initially spawned into one of ten classes which have specific mass and thickness as
 described in the \ngn{namberg} namelist: \np{rn\_initial\_mass} and \np{rn\_initial\_thickness}.
+described in the \nam{berg} namelist: \np{rn\_initial\_mass} and \np{rn\_initial\_thickness}.
 Each class has an associated scaling (\np{rn\_mass\_scaling}),
 which is an integer representing how many icebergs of this class are being described as one lagrangian point
 (this reduces the numerical problem of tracking every single iceberg).
 They are enabled by setting \np{ln\_icebergs}\forcode{ = .true.}.
+They are enabled by setting \np{ln\_icebergs}\forcode{=.true.}.
 Two initialisation schemes are possible.
 …
   \np{nn\_test\_icebergs} is defined by four numbers in \np{nn\_test\_box} representing the corners of
   the geographical box: lonmin,lonmax,latmin,latmax
 \item[\np{nn\_test\_icebergs}\forcode{ = -1}]
   In this scheme the model reads a calving file supplied in the \np{sn\_icb} parameter.
+\item[\np{nn\_test\_icebergs}\forcode{=-1}]
+  In this scheme, the model reads a calving file supplied in the \np{sn\_icb} parameter.
   This should be a file with a field on the configuration grid (typically ORCA)
   representing ice accumulation rate at each model point.
 …
   At each time step, a test is performed to see if there is enough ice mass to
   calve an iceberg of each class in order (1 to 10).
   Note that this is the initial mass multiplied by the number each particle represents (\ie the scaling).
+  Note that this is the initial mass multiplied by the number each particle represents (\ie\ the scaling).
   If there is enough ice, a new iceberg is spawned and the total available ice reduced accordingly.
 \end{description}
 …
 or (if \np{rn\_bits\_erosion\_fraction}~$>$~0) into melt and additionally small ice bits
 which are assumed to propagate with their larger parent and thus delay fluxing into the ocean.
 Melt water (and other variables on the configuration grid) are written into the main NEMO model output files.
+Melt water (and other variables on the configuration grid) are written into the main \NEMO\ model output files.
 Extensive diagnostics can be produced.
 …
 since its trajectory data may be spread across multiple files.
+% -------------------------------------------------------------------------------------------------------------
+% =============================================================================================================
 %        Interactions with waves (sbcwave.F90, ln_wave)
 % -------------------------------------------------------------------------------------------------------------
 \section{Interactions with waves (\protect\mdl{sbcwave}, \protect\np{ln\_wave})}
+% =============================================================================================================
+\section[Interactions with waves (\textit{sbcwave.F90}, \texttt{ln\_wave})]{Interactions with waves (\protect\mdl{sbcwave}, \protect\np{ln\_wave})}
 \label{sec:SBC_wave}
 %------------------------------------------namsbc_wave--------------------------------------------------------
+\nlst{namsbc_wave}
+\begin{listing}
+  \nlst{namsbc_wave}
+  \caption{\texttt{namsbc\_wave}}
+  \label{lst:namsbc_wave}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 Ocean waves represent the interface between the ocean and the atmosphere, so NEMO is extended to incorporate
 physical processes related to ocean surface waves, namely the surface stress modified by growth and
 dissipation of the oceanic wave field, the Stokes-Coriolis force and the Stokes drift impact on mass and
 tracer advection; moreover the neutral surface drag coefficient from a wave model can be used to evaluate
+Ocean waves represent the interface between the ocean and the atmosphere, so \NEMO\ is extended to incorporate
+physical processes related to ocean surface waves, namely the surface stress modified by growth and
+dissipation of the oceanic wave field, the Stokes-Coriolis force and the Stokes drift impact on mass and
+tracer advection; moreover the neutral surface drag coefficient from a wave model can be used to evaluate
 the wind stress.
 Physical processes related to ocean surface waves can be accounted by setting the logical variable
 \np{ln\_wave}\forcode{= .true.} in \ngn{namsbc} namelist. In addition, specific flags accounting for
 different porcesses should be activated as explained in the following sections.
+Physical processes related to ocean surface waves can be accounted by setting the logical variable
+\np{ln\_wave}\forcode{=.true.} in \nam{sbc} namelist. In addition, specific flags accounting for
+different processes should be activated as explained in the following sections.
 Wave fields can be provided either in forced or coupled mode:
 \begin{description}
 \item[forced mode]: wave fields should be defined through the \ngn{namsbc\_wave} namelist
 for external data names, locations, frequency, interpolation and all the miscellanous options allowed by
 Input Data generic Interface (see \autoref{sec:SBC_input}).
 \item[coupled mode]: NEMO and an external wave model can be coupled by setting \np{ln\_cpl} \forcode{= .true.}
 in \ngn{namsbc} namelist and filling the \ngn{namsbc\_cpl} namelist.
+\item[forced mode]: wave fields should be defined through the \nam{sbc\_wave} namelist
+for external data names, locations, frequency, interpolation and all the miscellanous options allowed by
+Input Data generic Interface (see \autoref{sec:SBC_input}).
+\item[coupled mode]: \NEMO\ and an external wave model can be coupled by setting \np{ln\_cpl} \forcode{= .true.}
+in \nam{sbc} namelist and filling the \nam{sbc\_cpl} namelist.
 \end{description}
 % ================================================================
+% ----------------------------------------------------------------
 % Neutral drag coefficient from wave model (ln_cdgw)
 % ================================================================
 \subsection{Neutral drag coefficient from wave model (\protect\np{ln\_cdgw})}
+% ----------------------------------------------------------------
+\subsection[Neutral drag coefficient from wave model (\texttt{ln\_cdgw})]{Neutral drag coefficient from wave model (\protect\np{ln\_cdgw})}
 \label{subsec:SBC_wave_cdgw}
 The neutral surface drag coefficient provided from an external data source (\ie a wave model),
 can be used by setting the logical variable \np{ln\_cdgw} \forcode{= .true.} in \ngn{namsbc} namelist.
 Then using the routine \rou{turb\_ncar} and starting from the neutral drag coefficent provided,
 the drag coefficient is computed according to the stable/unstable conditions of the
 air-sea interface following \citet{Large_Yeager_Rep04}.
 % ================================================================
+The neutral surface drag coefficient provided from an external data source (\ie\ a wave model),
+can be used by setting the logical variable \np{ln\_cdgw} \forcode{= .true.} in \nam{sbc} namelist.
+Then using the routine \rou{sbcblk\_algo\_ncar} and starting from the neutral drag coefficent provided,
+the drag coefficient is computed according to the stable/unstable conditions of the
+air-sea interface following \citet{large.yeager_rpt04}.
+% ----------------------------------------------------------------
 % 3D Stokes Drift (ln_sdw, nn_sdrift)
 % ================================================================
 \subsection{3D Stokes Drift (\protect\np{ln\_sdw, nn\_sdrift})}
+% ----------------------------------------------------------------
+\subsection[3D Stokes Drift (\texttt{ln\_sdw}, \texttt{nn\_sdrift})]{3D Stokes Drift (\protect\np{ln\_sdw, nn\_sdrift})}
 \label{subsec:SBC_wave_sdw}
 The Stokes drift is a wave driven mechanism of mass and momentum transport \citep{Stokes_1847}.
 It is defined as the difference between the average velocity of a fluid parcel (Lagrangian velocity)
 and the current measured at a fixed point (Eulerian velocity).
 As waves travel, the water particles that make up the waves travel in orbital motions but
 without a closed path. Their movement is enhanced at the top of the orbit and slowed slightly
 at the bottom so the result is a net forward motion of water particles, referred to as the Stokes drift.
 An accurate evaluation of the Stokes drift and the inclusion of related processes may lead to improved
 representation of surface physics in ocean general circulation models.
 The Stokes drift velocity $\mathbf{U}_{st}$ in deep water can be computed from the wave spectrum and may be written as:
+The Stokes drift is a wave driven mechanism of mass and momentum transport \citep{stokes_ibk09}.
+It is defined as the difference between the average velocity of a fluid parcel (Lagrangian velocity)
+and the current measured at a fixed point (Eulerian velocity).
+As waves travel, the water particles that make up the waves travel in orbital motions but
+without a closed path. Their movement is enhanced at the top of the orbit and slowed slightly
+at the bottom, so the result is a net forward motion of water particles, referred to as the Stokes drift.
+An accurate evaluation of the Stokes drift and the inclusion of related processes may lead to improved
+representation of surface physics in ocean general circulation models. %GS: reference needed
+The Stokes drift velocity $\mathbf{U}_{st}$ in deep water can be computed from the wave spectrum and may be written as:
 \[
   % \label{eq:sbc_wave_sdw}
+  % \label{eq:SBC_wave_sdw}
   \mathbf{U}_{st} = \frac{16{\pi^3}} {g}
   \int_0^\infty \int_{-\pi}^{\pi} (cos{\theta},sin{\theta}) {f^3}
 …
 \]
 where: ${\theta}$ is the wave direction, $f$ is the wave intrinsic frequency,
 $\mathrm{S}($f$,\theta)$ is the 2D frequency-direction spectrum,
 $k$ is the mean wavenumber defined as:
+where: ${\theta}$ is the wave direction, $f$ is the wave intrinsic frequency,
+$\mathrm{S}($f$,\theta)$ is the 2D frequency-direction spectrum,
+$k$ is the mean wavenumber defined as:
 $k=\frac{2\pi}{\lambda}$ (being $\lambda$ the wavelength). \\
 In order to evaluate the Stokes drift in a realistic ocean wave field the wave spectral shape is required
 and its computation quickly becomes expensive as the 2D spectrum must be integrated for each vertical level.
+In order to evaluate the Stokes drift in a realistic ocean wave field, the wave spectral shape is required
+and its computation quickly becomes expensive as the 2D spectrum must be integrated for each vertical level.
 To simplify, it is customary to use approximations to the full Stokes profile.
 Three possible parameterizations for the calculation for the approximate Stokes drift velocity profile
 are included in the code through the \np{nn\_sdrift} parameter once provided the surface Stokes drift
 $\mathbf{U}_{st |_{z=0}}$ which is evaluated by an external wave model that accurately reproduces the wave spectra
 and makes possible the estimation of the surface Stokes drift for random directional waves in
+Three possible parameterizations for the calculation for the approximate Stokes drift velocity profile
+are included in the code through the \np{nn\_sdrift} parameter once provided the surface Stokes drift
+$\mathbf{U}_{st |_{z=0}}$ which is evaluated by an external wave model that accurately reproduces the wave spectra
+and makes possible the estimation of the surface Stokes drift for random directional waves in
 realistic wave conditions:
 \begin{description}
 \item[\np{nn\_sdrift} = 0]: exponential integral profile parameterization proposed by
 \citet{Breivik_al_JPO2014}:
+\item[\np{nn\_sdrift} = 0]: exponential integral profile parameterization proposed by
+\citet{breivik.janssen.ea_JPO14}:
 \[
   % \label{eq:sbc_wave_sdw_0a}
   \mathbf{U}_{st} \cong \mathbf{U}_{st |_{z=0}} \frac{\mathrm{e}^{-2k_ez}} {1-8k_ez}
+  % \label{eq:SBC_wave_sdw_0a}
+  \mathbf{U}_{st} \cong \mathbf{U}_{st |_{z=0}} \frac{\mathrm{e}^{-2k_ez}} {1-8k_ez}
 \]
 …
 \[
   % \label{eq:sbc_wave_sdw_0b}
+  % \label{eq:SBC_wave_sdw_0b}
   k_e = \frac{|\mathbf{U}_{\left.st\right|_{z=0}}|} {|T_{st}|}
   \quad \text{and }\
   T_{st} = \frac{1}{16} \bar{\omega} H_s^2
+  T_{st} = \frac{1}{16} \bar{\omega} H_s^2
 \]
 where $H_s$ is the significant wave height and $\omega$ is the wave frequency.
 \item[\np{nn\_sdrift} = 1]: velocity profile based on the Phillips spectrum which is considered to be a
 reasonable estimate of the part of the spectrum most contributing to the Stokes drift velocity near the surface
 \citep{Breivik_al_OM2016}:
+\item[\np{nn\_sdrift} = 1]: velocity profile based on the Phillips spectrum which is considered to be a
+reasonable estimate of the part of the spectrum mostly contributing to the Stokes drift velocity near the surface
+\citep{breivik.bidlot.ea_OM16}:
 \[
   % \label{eq:sbc_wave_sdw_1}
+  % \label{eq:SBC_wave_sdw_1}
   \mathbf{U}_{st} \cong \mathbf{U}_{st |_{z=0}} \Big[exp(2k_pz)-\beta \sqrt{-2 \pi k_pz}
   \textit{ erf } \Big(\sqrt{-2 k_pz}\Big)\Big]
 …
 where $erf$ is the complementary error function and $k_p$ is the peak wavenumber.
 \item[\np{nn\_sdrift} = 2]: velocity profile based on the Phillips spectrum as for \np{nn\_sdrift} = 1
+\item[\np{nn\_sdrift} = 2]: velocity profile based on the Phillips spectrum as for \np{nn\_sdrift} = 1
 but using the wave frequency from a wave model.
 \end{description}
 The Stokes drift enters the wave-averaged momentum equation, as well as the tracer advection equations
 and its effect on the evolution of the sea-surface height ${\eta}$ is considered as follows:
+The Stokes drift enters the wave-averaged momentum equation, as well as the tracer advection equations
+and its effect on the evolution of the sea-surface height ${\eta}$ is considered as follows:
 \[
   % \label{eq:sbc_wave_eta_sdw}
+  % \label{eq:SBC_wave_eta_sdw}
   \frac{\partial{\eta}}{\partial{t}} =
   -\nabla_h \int_{-H}^{\eta} (\mathbf{U} + \mathbf{U}_{st}) dz
 \]
 The tracer advection equation is also modified in order for Eulerian ocean models to properly account
 for unresolved wave effect. The divergence of the wave tracer flux equals the mean tracer advection
 that is induced by the three-dimensional Stokes velocity.
 The advective equation for a tracer $c$ combining the effects of the mean current and sea surface waves
 can be formulated as follows:
+The tracer advection equation is also modified in order for Eulerian ocean models to properly account
+for unresolved wave effect. The divergence of the wave tracer flux equals the mean tracer advection
+that is induced by the three-dimensional Stokes velocity.
+The advective equation for a tracer $c$ combining the effects of the mean current and sea surface waves
+can be formulated as follows:
 \[
   % \label{eq:sbc_wave_tra_sdw}
+  % \label{eq:SBC_wave_tra_sdw}
   \frac{\partial{c}}{\partial{t}} =
   - (\mathbf{U} + \mathbf{U}_{st}) \cdot \nabla{c}
 …
 % ================================================================
+% ----------------------------------------------------------------
 % Stokes-Coriolis term (ln_stcor)
 % ================================================================
 \subsection{Stokes-Coriolis term (\protect\np{ln\_stcor})}
+% ----------------------------------------------------------------
+\subsection[Stokes-Coriolis term (\texttt{ln\_stcor})]{Stokes-Coriolis term (\protect\np{ln\_stcor})}
 \label{subsec:SBC_wave_stcor}
 In a rotating ocean, waves exert a wave-induced stress on the mean ocean circulation which results
 in a force equal to $\mathbf{U}_{st}$×$f$, where $f$ is the Coriolis parameter.
 This additional force may have impact on the Ekman turning of the surface current.
 In order to include this term, once evaluated the Stokes drift (using one of the 3 possible
 approximations described in \autoref{subsec:SBC_wave_sdw}),
 \np{ln\_stcor}\forcode{ = .true.} has to be set.
 % ================================================================
+In a rotating ocean, waves exert a wave-induced stress on the mean ocean circulation which results
+in a force equal to $\mathbf{U}_{st}$×$f$, where $f$ is the Coriolis parameter.
+This additional force may have impact on the Ekman turning of the surface current.
+In order to include this term, once evaluated the Stokes drift (using one of the 3 possible
+approximations described in \autoref{subsec:SBC_wave_sdw}),
+\np{ln\_stcor}\forcode{=.true.} has to be set.
+% ----------------------------------------------------------------
 % Waves modified stress (ln_tauwoc, ln_tauw)
 % ================================================================
 \subsection{Wave modified sress (\protect\np{ln\_tauwoc, ln\_tauw})}
+% ----------------------------------------------------------------
+\subsection[Wave modified stress (\texttt{ln\_tauwoc}, \texttt{ln\_tauw})]{Wave modified sress (\protect\np{ln\_tauwoc, ln\_tauw})}
 \label{subsec:SBC_wave_tauw}
 The surface stress felt by the ocean is the atmospheric stress minus the net stress going
 into the waves \citep{Janssen_al_TM13}. Therefore, when waves are growing, momentum and energy is spent and is not
 available for forcing the mean circulation, while in the opposite case of a decaying sea
 state more momentum is available for forcing the ocean.
 Only when the sea state is in equilibrium the ocean is forced by the atmospheric stress,
 but in practice an equilibrium sea state is a fairly rare event.
 So the atmospheric stress felt by the ocean circulation $\tau_{oc,a}$ can be expressed as:
+The surface stress felt by the ocean is the atmospheric stress minus the net stress going
+into the waves \citep{janssen.breivik.ea_rpt13}. Therefore, when waves are growing, momentum and energy is spent and is not
+available for forcing the mean circulation, while in the opposite case of a decaying sea
+state, more momentum is available for forcing the ocean.
+Only when the sea state is in equilibrium, the ocean is forced by the atmospheric stress,
+but in practice, an equilibrium sea state is a fairly rare event.
+So the atmospheric stress felt by the ocean circulation $\tau_{oc,a}$ can be expressed as:
 \[
   % \label{eq:sbc_wave_tauoc}
+  % \label{eq:SBC_wave_tauoc}
   \tau_{oc,a} = \tau_a - \tau_w
 \]
 …
 \[
   % \label{eq:sbc_wave_tauw}
+  % \label{eq:SBC_wave_tauw}
   \tau_w = \rho g \int {\frac{dk}{c_p} (S_{in}+S_{nl}+S_{diss})}
 \]
 where: $c_p$ is the phase speed of the gravity waves,
 $S_{in}$, $S_{nl}$ and $S_{diss}$ are three source terms that represent
 the physics of ocean waves. The first one, $S_{in}$, describes the generation
 of ocean waves by wind and therefore represents the momentum and energy transfer
 from air to ocean waves; the second term $S_{nl}$ denotes
 the nonlinear transfer by resonant four-wave interactions; while the third term $S_{diss}$
 describes the dissipation of waves by processes such as white-capping, large scale breaking
+$S_{in}$, $S_{nl}$ and $S_{diss}$ are three source terms that represent
+the physics of ocean waves. The first one, $S_{in}$, describes the generation
+of ocean waves by wind and therefore represents the momentum and energy transfer
+from air to ocean waves; the second term $S_{nl}$ denotes
+the nonlinear transfer by resonant four-wave interactions; while the third term $S_{diss}$
+describes the dissipation of waves by processes such as white-capping, large scale breaking
 eddy-induced damping.
+The wave stress derived from an external wave model can be provided either through the normalized
+wave stress into the ocean by setting \np{ln\_tauwoc}\forcode{ = .true.}, or through the zonal and
+meridional stress components by setting \np{ln\_tauw}\forcode{ = .true.}.
+The wave stress derived from an external wave model can be provided either through the normalized
+wave stress into the ocean by setting \np{ln\_tauwoc}\forcode{=.true.}, or through the zonal and
+meridional stress components by setting \np{ln\_tauw}\forcode{=.true.}.
 …
 \label{sec:SBC_misc}
 % -------------------------------------------------------------------------------------------------------------
 %        Diurnal cycle
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Diurnal cycle (\protect\mdl{sbcdcy})}
+\subsection[Diurnal cycle (\textit{sbcdcy.F90})]{Diurnal cycle (\protect\mdl{sbcdcy})}
 \label{subsec:SBC_dcy}
 %------------------------------------------namsbc_rnf----------------------------------------------------
+%------------------------------------------namsbc-------------------------------------------------------------
+%
+\nlst{namsbc}
 %-------------------------------------------------------------------------------------------------------------
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=0.8\textwidth]{Fig_SBC_diurnal}
+    \caption{
+      \protect\label{fig:SBC_diurnal}
+      Example of recontruction of the diurnal cycle variation of short wave flux from daily mean values.
+      The reconstructed diurnal cycle (black line) is chosen as
+      the mean value of the analytical cycle (blue line) over a time step,
+      not as the mid time step value of the analytically cycle (red square).
+      From \citet{Bernie_al_CD07}.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_SBC_diurnal}
+  \caption[Reconstruction of the diurnal cycle variation of short wave flux]{
+    Example of reconstruction of the diurnal cycle variation of short wave flux from
+    daily mean values.
+    The reconstructed diurnal cycle (black line) is chosen as
+    the mean value of the analytical cycle (blue line) over a time step,
+    not as the mid time step value of the analytically cycle (red square).
+    From \citet{bernie.guilyardi.ea_CD07}.}
+  \label{fig:SBC_diurnal}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\cite{Bernie_al_JC05} have shown that to capture 90$\%$ of the diurnal variability of SST requires a vertical resolution in upper ocean of 1~m or better and a temporal resolution of the surface fluxes of 3~h or less.
+Unfortunately high frequency forcing fields are rare, not to say inexistent.
+Nevertheless, it is possible to obtain a reasonable diurnal cycle of the SST knowning only short wave flux (SWF) at
+high frequency \citep{Bernie_al_CD07}.
+\cite{bernie.woolnough.ea_JC05} have shown that to capture 90$\%$ of the diurnal variability of SST requires a vertical resolution in upper ocean of 1~m or better and a temporal resolution of the surface fluxes of 3~h or less.
+%Unfortunately high frequency forcing fields are rare, not to say inexistent. GS: not true anymore !
+Nevertheless, it is possible to obtain a reasonable diurnal cycle of the SST knowning only short wave flux (SWF) at high frequency \citep{bernie.guilyardi.ea_CD07}.
 Furthermore, only the knowledge of daily mean value of SWF is needed,
 as higher frequency variations can be reconstructed from them,
 assuming that the diurnal cycle of SWF is a scaling of the top of the atmosphere diurnal cycle of incident SWF.
 The \cite{Bernie_al_CD07} reconstruction algorithm is available in \NEMO by
 setting \np{ln\_dm2dc}\forcode{ = .true.} (a \textit{\ngn{namsbc}} namelist variable) when
 using CORE bulk formulea (\np{ln\_blk\_core}\forcode{ = .true.}) or
 the flux formulation (\np{ln\_flx}\forcode{ = .true.}).
+The \cite{bernie.guilyardi.ea_CD07} reconstruction algorithm is available in \NEMO\ by
+setting \np{ln\_dm2dc}\forcode{=.true.} (a \textit{\nam{sbc}} namelist variable) when
+using a bulk formulation (\np{ln\_blk}\forcode{=.true.}) or
+the flux formulation (\np{ln\_flx}\forcode{=.true.}).
 The reconstruction is performed in the \mdl{sbcdcy} module.
 The detail of the algoritm used can be found in the appendix~A of \cite{Bernie_al_CD07}.
 The algorithm preserve the daily mean incoming SWF as the reconstructed SWF at
+The detail of the algoritm used can be found in the appendix~A of \cite{bernie.guilyardi.ea_CD07}.
+The algorithm preserves the daily mean incoming SWF as the reconstructed SWF at
 a given time step is the mean value of the analytical cycle over this time step (\autoref{fig:SBC_diurnal}).
 The use of diurnal cycle reconstruction requires the input SWF to be daily
 (\ie a frequency of 24 and a time interpolation set to true in \np{sn\_qsr} namelist parameter).
 Furthermore, it is recommended to have a least 8 surface module time step per day,
+(\ie\ a frequency of 24 hours and a time interpolation set to true in \np{sn\_qsr} namelist parameter).
+Furthermore, it is recommended to have a least 8 surface module time steps per day,
 that is  $\rdt \ nn\_fsbc < 10,800~s = 3~h$.
 An example of recontructed SWF is given in \autoref{fig:SBC_dcy} for a 12 reconstructed diurnal cycle,
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=0.7\textwidth]{Fig_SBC_dcy}
+    \caption{
+      \protect\label{fig:SBC_dcy}
+      Example of recontruction of the diurnal cycle variation of short wave flux from
+      daily mean values on an ORCA2 grid with a time sampling of 2~hours (from 1am to 11pm).
+      The display is on (i,j) plane.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_SBC_dcy}
+  \caption[Reconstruction of the diurnal cycle variation of short wave flux on an ORCA2 grid]{
+    Example of reconstruction of the diurnal cycle variation of short wave flux from
+    daily mean values on an ORCA2 grid with a time sampling of 2~hours (from 1am to 11pm).
+    The display is on (i,j) plane.}
+  \label{fig:SBC_dcy}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 an inconsistency between the scale of the vertical resolution and the forcing acting on that scale.
 % -------------------------------------------------------------------------------------------------------------
 %        Rotation of vector pairs onto the model grid directions
 …
 \label{subsec:SBC_rotation}
+When using a flux (\np{ln\_flx}\forcode{ = .true.}) or
+bulk (\np{ln\_clio}\forcode{ = .true.} or \np{ln\_core}\forcode{ = .true.}) formulation,
+When using a flux (\np{ln\_flx}\forcode{=.true.}) or bulk (\np{ln\_blk}\forcode{=.true.}) formulation,
 pairs of vector components can be rotated from east-north directions onto the local grid directions.
 This is particularly useful when interpolation on the fly is used since here any vectors are likely to
 be defined relative to a rectilinear grid.
 To activate this option a non-empty string is supplied in the rotation pair column of the relevant namelist.
 The eastward component must start with "U" and the northward component with "V".
+To activate this option, a non-empty string is supplied in the rotation pair column of the relevant namelist.
+The eastward component must start with "U" and the northward component with "V".
 The remaining characters in the strings are used to identify which pair of components go together.
 So for example, strings "U1" and "V1" next to "utau" and "vtau" would pair the wind stress components together and
 …
 The rot\_rep routine from the \mdl{geo2ocean} module is used to perform the rotation.
 % -------------------------------------------------------------------------------------------------------------
 %        Surface restoring to observed SST and/or SSS
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Surface restoring to observed SST and/or SSS (\protect\mdl{sbcssr})}
+\subsection[Surface restoring to observed SST and/or SSS (\textit{sbcssr.F90})]{Surface restoring to observed SST and/or SSS (\protect\mdl{sbcssr})}
 \label{subsec:SBC_ssr}
 %------------------------------------------namsbc_ssr----------------------------------------------------
+\nlst{namsbc_ssr}
+\begin{listing}
+  \nlst{namsbc_ssr}
+  \caption{\texttt{namsbc\_ssr}}
+  \label{lst:namsbc_ssr}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 IOptions are defined through the \ngn{namsbc\_ssr} namelist variables.
 On forced mode using a flux formulation (\np{ln\_flx}\forcode{ = .true.}),
+Options are defined through the \nam{sbc\_ssr} namelist variables.
+On forced mode using a flux formulation (\np{ln\_flx}\forcode{=.true.}),
 a feedback term \emph{must} be added to the surface heat flux $Q_{ns}^o$:
 \[
   % \label{eq:sbc_dmp_q}
+  % \label{eq:SBC_dmp_q}
   Q_{ns} = Q_{ns}^o + \frac{dQ}{dT} \left( \left. T \right|_{k=1} - SST_{Obs} \right)
 \]
 …
 $T$ is the model surface layer temperature and
 $\frac{dQ}{dT}$ is a negative feedback coefficient usually taken equal to $-40~W/m^2/K$.
 For a $50~m$ mixed-layer depth, this value corresponds to a relaxation time scale of two months.
 This term ensures that if $T$ perfectly matches the supplied SST, then $Q$ is equal to $Q_o$.
+For a $50~m$ mixed-layer depth, this value corresponds to a relaxation time scale of two months.
+This term ensures that if $T$ perfectly matches the supplied SST, then $Q$ is equal to $Q_o$.
 In the fresh water budget, a feedback term can also be added.
 …
 \begin{equation}
   \label{eq:sbc_dmp_emp}
+  \label{eq:SBC_dmp_emp}
   \textit{emp} = \textit{emp}_o + \gamma_s^{-1} e_{3t}  \frac{  \left(\left.S\right|_{k=1}-SSS_{Obs}\right)}
   {\left.S\right|_{k=1}}
 …
 (observed, climatological or an atmospheric model product),
 \textit{SSS}$_{Obs}$ is a sea surface salinity
 (usually a time interpolation of the monthly mean Polar Hydrographic Climatology \citep{Steele2001}),
+(usually a time interpolation of the monthly mean Polar Hydrographic Climatology \citep{steele.morley.ea_JC01}),
 $\left.S\right|_{k=1}$ is the model surface layer salinity and
 $\gamma_s$ is a negative feedback coefficient which is provided as a namelist parameter.
 Unlike heat flux, there is no physical justification for the feedback term in \autoref{eq:sbc_dmp_emp} as
 the atmosphere does not care about ocean surface salinity \citep{Madec1997}.
+Unlike heat flux, there is no physical justification for the feedback term in \autoref{eq:SBC_dmp_emp} as
+the atmosphere does not care about ocean surface salinity \citep{madec.delecluse_IWN97}.
 The SSS restoring term should be viewed as a flux correction on freshwater fluxes to
 reduce the uncertainties we have on the observed freshwater budget.
 % -------------------------------------------------------------------------------------------------------------
 %        Handling of ice-covered area
 …
 The presence at the sea surface of an ice covered area modifies all the fluxes transmitted to the ocean.
 There are several way to handle sea-ice in the system depending on
 the value of the \np{nn\_ice} namelist parameter found in \ngn{namsbc} namelist.
+the value of the \np{nn\_ice} namelist parameter found in \nam{sbc} namelist.
 \begin{description}
 \item[nn{\_}ice = 0]
+\item[nn\_ice = 0]
   there will never be sea-ice in the computational domain.
   This is a typical namelist value used for tropical ocean domain.
   The surface fluxes are simply specified for an ice-free ocean.
   No specific things is done for sea-ice.
 \item[nn{\_}ice = 1]
+\item[nn\_ice = 1]
   sea-ice can exist in the computational domain, but no sea-ice model is used.
   An observed ice covered area is read in a file.
 …
   This prevents deep convection to occur when trying to reach the freezing point
   (and so ice covered area condition) while the SSS is too large.
   This manner of managing sea-ice area, just by using si IF case,
+  This manner of managing sea-ice area, just by using a IF case,
   is usually referred as the \textit{ice-if} model.
   It can be found in the \mdl{sbcice{\_}if} module.
 \item[nn{\_}ice = 2 or more]
+  It can be found in the \mdl{sbcice\_if} module.
+\item[nn\_ice = 2 or more]
   A full sea ice model is used.
   This model computes the ice-ocean fluxes,
   that are combined with the air-sea fluxes using the ice fraction of each model cell to
   provide the surface ocean fluxes.
   Note that the activation of a sea-ice model is is done by defining a CPP key (\key{lim3} or \key{cice}).
   The activation automatically overwrites the read value of nn{\_}ice to its appropriate value
   (\ie $2$ for LIM-3 or $3$ for CICE).
+  provide the surface averaged ocean fluxes.
+  Note that the activation of a sea-ice model is done by defining a CPP key (\key{si3} or \key{cice}).
+  The activation automatically overwrites the read value of nn\_ice to its appropriate value
+  (\ie\ $2$ for SI3 or $3$ for CICE).
 \end{description}
 % {Description of Ice-ocean interface to be added here or in LIM 2 and 3 doc ?}
+\subsection{Interface to CICE (\protect\mdl{sbcice\_cice})}
+%GS: ocean-ice (SI3) interface is not located in SBC directory anymore, so it should be included in SI3 doc
+% -------------------------------------------------------------------------------------------------------------
+%        CICE-ocean Interface
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Interface to CICE (\textit{sbcice\_cice.F90})]{Interface to CICE (\protect\mdl{sbcice\_cice})}
 \label{subsec:SBC_cice}
 It is now possible to couple a regional or global NEMO configuration (without AGRIF)
+It is possible to couple a regional or global \NEMO\ configuration (without AGRIF)
 to the CICE sea-ice model by using \key{cice}.
 The CICE code can be obtained from \href{http://oceans11.lanl.gov/trac/CICE/}{LANL} and
 the additional 'hadgem3' drivers will be required, even with the latest code release.
 Input grid files consistent with those used in NEMO will also be needed,
+Input grid files consistent with those used in \NEMO\ will also be needed,
 and CICE CPP keys \textbf{ORCA\_GRID}, \textbf{CICE\_IN\_NEMO} and \textbf{coupled} should be used
 (seek advice from UKMO if necessary).
 Currently the code is only designed to work when using the CORE forcing option for NEMO
 (with \textit{calc\_strair}\forcode{ = .true.} and \textit{calc\_Tsfc}\forcode{ = .true.} in the CICE name-list),
 or alternatively when NEMO is coupled to the HadGAM3 atmosphere model
 (with \textit{calc\_strair}\forcode{ = .false.} and \textit{calc\_Tsfc}\forcode{ = false}).
+Currently, the code is only designed to work when using the NCAR forcing option for \NEMO\ %GS: still true ?
+(with \textit{calc\_strair}\forcode{=.true.} and \textit{calc\_Tsfc}\forcode{=.true.} in the CICE name-list),
+or alternatively when \NEMO\ is coupled to the HadGAM3 atmosphere model
+(with \textit{calc\_strair}\forcode{=.false.} and \textit{calc\_Tsfc}\forcode{=false}).
 The code is intended to be used with \np{nn\_fsbc} set to 1
 (although coupling ocean and ice less frequently should work,
 …
 the user should check that results are not significantly different to the standard case).
 There are two options for the technical coupling between NEMO and CICE.
+There are two options for the technical coupling between \NEMO\ and CICE.
 The standard version allows complete flexibility for the domain decompositions in the individual models,
 but this is at the expense of global gather and scatter operations in the coupling which
 become very expensive on larger numbers of processors.
 The alternative option (using \key{nemocice\_decomp} for both NEMO and CICE) ensures that
+The alternative option (using \key{nemocice\_decomp} for both \NEMO\ and CICE) ensures that
 the domain decomposition is identical in both models (provided domain parameters are set appropriately,
 and \textit{processor\_shape~=~square-ice} and \textit{distribution\_wght~=~block} in the CICE name-list) and
 …
 there is no sea ice.
+% -------------------------------------------------------------------------------------------------------------
+%        Freshwater budget control
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Freshwater budget control (\protect\mdl{sbcfwb})}
+% -------------------------------------------------------------------------------------------------------------
+%        Freshwater budget control
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Freshwater budget control (\textit{sbcfwb.F90})]{Freshwater budget control (\protect\mdl{sbcfwb})}
 \label{subsec:SBC_fwb}
 For global ocean simulation it can be useful to introduce a control of the mean sea level in order to
+For global ocean simulation, it can be useful to introduce a control of the mean sea level in order to
 prevent unrealistic drift of the sea surface height due to inaccuracy in the freshwater fluxes.
+In \NEMO, two way of controlling the the freshwater budget.
+In \NEMO, two way of controlling the freshwater budget are proposed:
 \begin{description}
 \item[\np{nn\_fwb}\forcode{ = 0}]
+\item[\np{nn\_fwb}\forcode{=0}]
   no control at all.
   The mean sea level is free to drift, and will certainly do so.
+\item[\np{nn\_fwb}\forcode{ = 1}]
+  global mean \textit{emp} set to zero at each model time step.
+%Note that with a sea-ice model, this technique only control the mean sea level with linear free surface (\key{vvl} not defined) and no mass flux between ocean and ice (as it is implemented in the current ice-ocean coupling).
+\item[\np{nn\_fwb}\forcode{ = 2}]
+\item[\np{nn\_fwb}\forcode{=1}]
+  global mean \textit{emp} set to zero at each model time step.
+  %GS: comment below still relevant ?
+  %Note that with a sea-ice model, this technique only controls the mean sea level with linear free surface and no mass flux between ocean and ice (as it is implemented in the current ice-ocean coupling).
+\item[\np{nn\_fwb}\forcode{=2}]
   freshwater budget is adjusted from the previous year annual mean budget which
   is read in the \textit{EMPave\_old.dat} file.
   As the model uses the Boussinesq approximation, the annual mean fresh water budget is simply evaluated from
   the change in the mean sea level at January the first and saved in the \textit{EMPav.dat} file.
+  the change in the mean sea level at January the first and saved in the \textit{EMPav.dat} file.
 \end{description}
 % Griffies doc:
+% When running ocean-ice simulations, we are not explicitly representing land processes,
+% such as rivers, catchment areas, snow accumulation, etc. However, to reduce model drift,
+% it is important to balance the hydrological cycle in ocean-ice models.
+% We thus need to prescribe some form of global normalization to the precipitation minus evaporation plus river runoff.
+% The result of the normalization should be a global integrated zero net water input to the ocean-ice system over
+% a chosen time scale.
+%How often the normalization is done is a matter of choice. In mom4p1, we choose to do so at each model time step,
+% so that there is always a zero net input of water to the ocean-ice system.
+% Others choose to normalize over an annual cycle, in which case the net imbalance over an annual cycle is used
+% to alter the subsequent year�s water budget in an attempt to damp the annual water imbalance.
+% Note that the annual budget approach may be inappropriate with interannually varying precipitation forcing.
+% When running ocean-ice coupled models, it is incorrect to include the water transport between the ocean
+% and ice models when aiming to balance the hydrological cycle.
+% The reason is that it is the sum of the water in the ocean plus ice that should be balanced when running ocean-ice models,
+% not the water in any one sub-component. As an extreme example to illustrate the issue,
+% consider an ocean-ice model with zero initial sea ice. As the ocean-ice model spins up,
+% there should be a net accumulation of water in the growing sea ice, and thus a net loss of water from the ocean.
+% The total water contained in the ocean plus ice system is constant, but there is an exchange of water between
+% the subcomponents. This exchange should not be part of the normalization used to balance the hydrological cycle
+% in ocean-ice models.
+% When running ocean-ice simulations, we are not explicitly representing land processes,
+% such as rivers, catchment areas, snow accumulation, etc. However, to reduce model drift,
+% it is important to balance the hydrological cycle in ocean-ice models.
+% We thus need to prescribe some form of global normalization to the precipitation minus evaporation plus river runoff.
+% The result of the normalization should be a global integrated zero net water input to the ocean-ice system over
+% a chosen time scale.
+% How often the normalization is done is a matter of choice. In mom4p1, we choose to do so at each model time step,
+% so that there is always a zero net input of water to the ocean-ice system.
+% Others choose to normalize over an annual cycle, in which case the net imbalance over an annual cycle is used
+% to alter the subsequent year�s water budget in an attempt to damp the annual water imbalance.
+% Note that the annual budget approach may be inappropriate with interannually varying precipitation forcing.
+% When running ocean-ice coupled models, it is incorrect to include the water transport between the ocean
+% and ice models when aiming to balance the hydrological cycle.
+% The reason is that it is the sum of the water in the ocean plus ice that should be balanced when running ocean-ice models,
+% not the water in any one sub-component. As an extreme example to illustrate the issue,
+% consider an ocean-ice model with zero initial sea ice. As the ocean-ice model spins up,
+% there should be a net accumulation of water in the growing sea ice, and thus a net loss of water from the ocean.
+% The total water contained in the ocean plus ice system is constant, but there is an exchange of water between
+% the subcomponents. This exchange should not be part of the normalization used to balance the hydrological cycle
+% in ocean-ice models.
 \biblio

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_STO.tex

-                      r10442
+                      r11564
 \label{chap:STO}
+Authors: P.-A. Bouttier
+\minitoc
+\chaptertoc
+% \vfill
+% \begin{figure}[b]
+% \subsubsection*{Changes record}
+% \begin{tabular}{l||l|m{0.65\linewidth}}
+%    Release   & Author        & Modifications \\
+%    {\em 4.0.1} & {\em C. Levy} & {\em 4.0.1 update}  \\
+%    {\em 3.6} & {\em P.-A. Bouttier} & {\em initial version}  \\
+% \end{tabular}
+% \end{figure}
+Authors: \\
+C. Levy release 4.0.1 update \\
+P.-A. Bouttier release 3.6 inital version
 \newpage
+The stochastic parametrization module aims to explicitly simulate uncertainties in the model.
+More particularly, \cite{Brankart_OM2013} has shown that,
+because of the nonlinearity of the seawater equation of state, unresolved scales represent a major source of
+uncertainties in the computation of the large scale horizontal density gradient (from T/S large scale fields),
+and that the impact of these uncertainties can be simulated by
+random processes representing unresolved T/S fluctuations.
+The stochastic formulation of the equation of state can be written as:
+As a result of the nonlinearity of the seawater equation of state, unresolved scales represent a major source of uncertainties in the computation of the large-scale horizontal density gradient from the large-scale temperature and salinity fields. Following  \cite{brankart_OM13}, the impact of these uncertainties can be simulated by random processes representing unresolved T/S fluctuations. The Stochastic Parametrization of EOS (STO) module implements this parametrization.
+As detailed in \cite{brankart_OM13}, the stochastic formulation of the equation of state can be written as:
 \begin{equation}
   \label{eq:eos_sto}
+  \label{eq:STO_eos_sto}
   \rho = \frac{1}{2} \sum_{i=1}^m\{ \rho[T+\Delta T_i,S+\Delta S_i,p_o(z)] + \rho[T-\Delta T_i,S-\Delta S_i,p_o(z)] \}
 \end{equation}
 where $p_o(z)$ is the reference pressure depending on the depth and,
 $\Delta T_i$ and $\Delta S_i$ are a set of T/S perturbations defined as
+$\Delta T_i$ and $\Delta S_i$ (i=1,m) is a set of T/S perturbations defined as
 the scalar product of the respective local T/S gradients with random walks $\mathbf{\xi}$:
 \begin{equation}
   \label{eq:sto_pert}
+  \label{eq:STO_sto_pert}
   \Delta T_i = \mathbf{\xi}_i \cdot \nabla T \qquad \hbox{and} \qquad \Delta S_i = \mathbf{\xi}_i \cdot \nabla S
 \end{equation}
 $\mathbf{\xi}_i$ are produced by a first-order autoregressive processes (AR-1) with
+$\mathbf{\xi}_i$ are produced by a first-order autoregressive process (AR-1) with
 a parametrized decorrelation time scale, and horizontal and vertical standard deviations $\sigma_s$.
 $\mathbf{\xi}$ are uncorrelated over the horizontal and fully correlated along the vertical.
 …
 \label{sec:STO_the_details}
+The starting point of our implementation of stochastic parameterizations in NEMO is to observe that
+many existing parameterizations are based on autoregressive processes,
+There are many existing parameterizations based on autoregressive processes,
 which are used as a basic source of randomness to transform a deterministic model into a probabilistic model.
 A generic approach is thus to add one single new module in NEMO,
 generating processes with appropriate statistics to simulate each kind of uncertainty in the model
 (see \cite{Brankart_al_GMD2015} for more details).
 In practice, at every model grid point,
+The generic approach here is to a new STO module,
+generating processes features with appropriate statistics to simulate these uncertainties in the model
+(see \cite{brankart.candille.ea_GMD15} for more details).
+In practice, at each model grid point,
 independent Gaussian autoregressive processes~$\xi^{(i)},\,i=1,\ldots,m$ are first generated using
 the same basic equation:
 \begin{equation}
   \label{eq:autoreg}
+  \label{eq:STO_autoreg}
   \xi^{(i)}_{k+1} = a^{(i)} \xi^{(i)}_k + b^{(i)} w^{(i)} + c^{(i)}
 \end{equation}
 …
   \[
     % \label{eq:ord1}
+    % \label{eq:STO_ord1}
     \left\{
       \begin{array}{l}
 …
   \begin{equation}
     \label{eq:ord2}
+    \label{eq:STO_ord2}
     \left\{
       \begin{array}{l}
 …
 \noindent
 In this way, higher order processes can be easily generated recursively using the same piece of code implementing
 (\autoref{eq:autoreg}), and using succesively processes from order $0$ to~$n-1$ as~$w^{(i)}$.
 The parameters in (\autoref{eq:ord2}) are computed so that this recursive application of
 (\autoref{eq:autoreg}) leads to processes with the required standard deviation and correlation timescale,
+\autoref{eq:STO_autoreg}, and using successive processes from order $0$ to~$n-1$ as~$w^{(i)}$.
+The parameters in \autoref{eq:STO_ord2} are computed so that this recursive application of
+\autoref{eq:STO_autoreg} leads to processes with the required standard deviation and correlation timescale,
 with the additional condition that the $n-1$ first derivatives of the autocorrelation function are equal to
 zero at~$t=0$, so that the resulting processes become smoother and smoother as $n$ is increased.
+zero at~$t=0$, so that the resulting processes become smoother and smoother as $n$ increases.
 Overall, this method provides quite a simple and generic way of generating a wide class of stochastic processes.
 However, this also means that new model parameters are needed to specify each of these stochastic processes.
 As in any parameterization of lacking physics, a very important issues then to tune these new parameters using
+As in any parameterization, the main issue is to tune the parameters using
 either first principles, model simulations, or real-world observations.
+The parameters are set by default as described in \cite{brankart_OM13}, which has been shown in the paper
+to give good results for a global low resolution (2°) \NEMO\ configuration. where this parametrization produces a major effect on the average large-scale circulation, especilally in regions of intense mesoscale activity.
+The set of parameters will need further investigation to find appropriate values
+for any other configuration or resolution of the model.
 \section{Implementation details}
 \label{sec:STO_thech_details}
+%---------------------------------------namsbc--------------------------------------------------
+\nlst{namsto}
+%--------------------------------------------------------------------------------------------------------------
+The computer code implementing stochastic parametrisations can be found in the STO directory.
+It involves three modules :
+\begin{description}
+\item[\mdl{stopar}:]
+  define the Stochastic parameters and their time evolution.
+\item[\mdl{storng}:]
+  a random number generator based on (and includes) the 64-bit KISS (Keep It Simple Stupid) random number generator
+  distributed by George Marsaglia
+  (see \href{https://groups.google.com/forum/#!searchin/comp.lang.fortran/64-bit$20KISS$20RNGs}{here})
+\item[\mdl{stopts}:]
+  stochastic parametrisation associated with the non-linearity of the equation of seawater,
+  implementing \autoref{eq:sto_pert} and specific piece of code in
+  the equation of state implementing \autoref{eq:eos_sto}.
+\end{description}
+The \mdl{stopar} module has 3 public routines to be called by the model (in our case, NEMO):
+The first routine (\rou{sto\_par}) is a direct implementation of (\autoref{eq:autoreg}),
+The code implementing stochastic parametrisation is located in the src/OCE/STO directory.
+It contains three modules :
+% \begin{description}
+\mdl{stopar} : define the Stochastic parameters and their time evolution
+\mdl{storng} : random number generator based on and including the 64-bit KISS (Keep It Simple Stupid) random number generator distributed by George Marsaglia
+\mdl{stopts} : stochastic parametrisation associated with the non-linearity of the equation of
+ seawater, implementing \autoref{eq:STO_sto_pert} so as specifics in the equation of state
+ implementing \autoref{eq:STO_eos_sto}.
+% \end{description}
+The \mdl{stopar} module includes three public routines called in the model:
+(\rou{sto\_par}) is a direct implementation of \autoref{eq:STO_autoreg},
 applied at each model grid point (in 2D or 3D), and called at each model time step ($k$) to
 update every autoregressive process ($i=1,\ldots,m$).
 …
 to introduce a spatial correlation between the stochastic processes.
+The second routine (\rou{sto\_par\_init}) is an initialization routine mainly dedicated to
 the computation of parameters $a^{(i)}, b^{(i)}, c^{(i)}$ for each autoregressive process,
+(\rou{sto\_par\_init}) is the initialization routine computing
+the values $a^{(i)}, b^{(i)}, c^{(i)}$ for each autoregressive process,
 as a function of the statistical properties required by the model user
+(mean, standard deviation, time correlation, order of the process,\ldots).
+Parameters for the processes can be specified through the following \ngn{namsto} namelist parameters:
+(mean, standard deviation, time correlation, order of the process,\ldots).
+This routine also includes the initialization (seeding) of the random number generator.
+(\rou{sto\_rst\_write}) writes a restart file
+(which suffix name is given by \np{cn\_storst\_out} namelist parameter) containing the current value of
+all autoregressive processes to allow creating the file needed for a restart.
+This restart file also contains the current state of the random number generator.
+When \np{ln\_rststo} is set to \forcode{.true.}),
+the restart file (which suffix name is given by \np{cn\_storst\_in} namelist parameter) is read by
+the initialization routine (\rou{sto\_par\_init}).
+The simulation will continue exactly as if it was not interrupted only
+when \np{ln\_rstseed} is set to \forcode{.true.},
+\ie\ when the state of the random number generator is read in the restart file.\\
+The implementation includes the basics for a few possible stochastic parametrisations including equation of state,
+lateral diffusion, horizontal pressure gradient, ice strength, trend, tracers dynamics.
+As for this release, only the stochastic parametrisation of equation of state is fully available and tested. \\
+Options and parameters \\
+The \np{ln\_sto\_eos} namelist variable activates stochastic parametrisation of equation of state.
+By default it set to \forcode{.false.}) and not active.
+The set of parameters is available in \nam{sto} namelist
+(only the subset for equation of state stochastic parametrisation is listed below):
+%---------------------------------------namsto--------------------------------------------------
+\begin{listing}
+  \nlst{namsto}
+  \caption{\texttt{namsto}}
+  \label{lst:namsto}
+\end{listing}
+%--------------------------------------------------------------------------------------------------------------
+The variables of stochastic paramtetrisation itself (based on the global 2° experiments as in \cite{brankart_OM13} are:
 \begin{description}
 \item[\np{nn\_sto\_eos}:]   number of independent random walks
 \item[\np{rn\_eos\_stdxy}:] random walk horz. standard deviation (in grid points)
 \item[\np{rn\_eos\_stdz}:]  random walk vert. standard deviation (in grid points)
+\item[\np{rn\_eos\_stdxy}:] random walk horizontal standard deviation (in grid points)
+\item[\np{rn\_eos\_stdz}:]  random walk vertical standard deviation (in grid points)
 \item[\np{rn\_eos\_tcor}:]  random walk time correlation (in timesteps)
 \item[\np{nn\_eos\_ord}:]   order of autoregressive processes
 …
 \item[\np{rn\_eos\_lim}:]   limitation factor (default = 3.0)
 \end{description}
+This routine also includes the initialization (seeding) of the random number generator.
+The third routine (\rou{sto\_rst\_write}) writes a restart file
+(which suffix name is given by \np{cn\_storst\_out} namelist parameter) containing the current value of
+all autoregressive processes to allow restarting a simulation from where it has been interrupted.
+This file also contains the current state of the random number generator.
+When \np{ln\_rststo} is set to \forcode{.true.}),
+the restart file (which suffix name is given by \np{cn\_storst\_in} namelist parameter) is read by
+the initialization routine (\rou{sto\_par\_init}).
+The simulation will continue exactly as if it was not interrupted only
+when \np{ln\_rstseed} is set to \forcode{.true.},
+\ie when the state of the random number generator is read in the restart file.
+The first four parameters define the stochastic part of equation of state.
 \biblio

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_TRA.tex

-                      r10544
+                      r11564
 \label{chap:TRA}
 \minitoc
 % missing/update
+\chaptertoc
+% missing/update
 % traqsr: need to coordinate with SBC module
+%STEVEN :  is the use of the word "positive" to describe a scheme enough, or should it be "positive definite"? I added a comment to this effect on some instances of this below
+%STEVEN :  is the use of the word "positive" to describe a scheme enough, or should it be "positive definite"?
+%I added a comment to this effect on some instances of this below
 Using the representation described in \autoref{chap:DOM}, several semi -discrete space forms of
 …
 The terms QSR, BBC, BBL and DMP are optional.
 The external forcings and parameterisations require complex inputs and complex calculations
 (\eg bulk formulae, estimation of mixing coefficients) that are carried out in the SBC,
+(\eg\ bulk formulae, estimation of mixing coefficients) that are carried out in the SBC,
 LDF and ZDF modules and described in \autoref{chap:SBC}, \autoref{chap:LDF} and
 \autoref{chap:ZDF}, respectively.
 …
 associated modules \mdl{eosbn2} and \mdl{phycst}).
 The different options available to the user are managed by namelist logicals or CPP keys.
+The different options available to the user are managed by namelist logicals.
 For each equation term \textit{TTT}, the namelist logicals are \textit{ln\_traTTT\_xxx},
 where \textit{xxx} is a 3 or 4 letter acronym corresponding to each optional scheme.
-The CPP key (when it exists) is \key{traTTT}.
 The equivalent code can be found in the \textit{traTTT} or \textit{traTTT\_xxx} module,
 in the \path{./src/OCE/TRA} directory.
 The user has the option of extracting each tendency term on the RHS of the tracer equation for output
 (\np{ln\_tra\_trd} or \np{ln\_tra\_mxl}~\forcode{= .true.}), as described in \autoref{chap:DIA}.
+(\np{ln\_tra\_trd} or \np{ln\_tra\_mxl}\forcode{=.true.}), as described in \autoref{chap:DIA}.
 % ================================================================
 % Tracer Advection
 % ================================================================
+\section{Tracer advection (\protect\mdl{traadv})}
+\section[Tracer advection (\textit{traadv.F90})]
+{Tracer advection (\protect\mdl{traadv})}
 \label{sec:TRA_adv}
 %------------------------------------------namtra_adv-----------------------------------------------------
+\nlst{namtra_adv}
+\begin{listing}
+  \nlst{namtra_adv}
+  \caption{\texttt{namtra\_adv}}
+  \label{lst:namtra_adv}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 When considered (\ie when \np{ln\_traadv\_NONE} is not set to \forcode{.true.}),
+When considered (\ie\ when \np{ln\_traadv\_OFF} is not set to \forcode{.true.}),
 the advection tendency of a tracer is expressed in flux form,
 \ie as the divergence of the advective fluxes.
+\ie\ as the divergence of the advective fluxes.
 Its discrete expression is given by :
 \begin{equation}
   \label{eq:tra_adv}
+  \label{eq:TRA_adv}
   ADV_\tau = - \frac{1}{b_t} \Big(   \delta_i [ e_{2u} \, e_{3u} \; u \; \tau_u]
                                    + \delta_j [ e_{1v} \, e_{3v} \; v \; \tau_v] \Big)
 …
 \end{equation}
 where $\tau$ is either T or S, and $b_t = e_{1t} \, e_{2t} \, e_{3t}$ is the volume of $T$-cells.
 The flux form in \autoref{eq:tra_adv} implicitly requires the use of the continuity equation.
+The flux form in \autoref{eq:TRA_adv} implicitly requires the use of the continuity equation.
 Indeed, it is obtained by using the following equality: $\nabla \cdot (\vect U \, T) = \vect U \cdot \nabla T$ which
 results from the use of the continuity equation, $\partial_t e_3 + e_3 \; \nabla \cdot \vect U = 0$
 (which reduces to $\nabla \cdot \vect U = 0$ in linear free surface, \ie \np{ln\_linssh}~\forcode{= .true.}).
+(which reduces to $\nabla \cdot \vect U = 0$ in linear free surface, \ie\ \np{ln\_linssh}\forcode{=.true.}).
 Therefore it is of paramount importance to design the discrete analogue of the advection tendency so that
 it is consistent with the continuity equation in order to enforce the conservation properties of
 the continuous equations.
 In other words, by setting $\tau = 1$ in (\autoref{eq:tra_adv}) we recover the discrete form of
+In other words, by setting $\tau = 1$ in (\autoref{eq:TRA_adv}) we recover the discrete form of
 the continuity equation which is used to calculate the vertical velocity.
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[]{Fig_adv_scheme}
+    \caption{
+      \protect\label{fig:adv_scheme}
+      Schematic representation of some ways used to evaluate the tracer value at $u$-point and
+      the amount of tracer exchanged between two neighbouring grid points.
+      Upsteam biased scheme (ups):
+      the upstream value is used and the black area is exchanged.
+      Piecewise parabolic method (ppm):
+      a parabolic interpolation is used and the black and dark grey areas are exchanged.
+      Monotonic upstream scheme for conservative laws (muscl):
+      a parabolic interpolation is used and black, dark grey and grey areas are exchanged.
+      Second order scheme (cen2):
+      the mean value is used and black, dark grey, grey and light grey areas are exchanged.
+      Note that this illustration does not include the flux limiter used in ppm and muscl schemes.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_adv_scheme}
+  \caption[Ways to evaluate the tracer value and the amount of tracer exchanged]{
+    Schematic representation of some ways used to evaluate the tracer value at $u$-point and
+    the amount of tracer exchanged between two neighbouring grid points.
+    Upsteam biased scheme (ups):
+    the upstream value is used and the black area is exchanged.
+    Piecewise parabolic method (ppm):
+    a parabolic interpolation is used and the black and dark grey areas are exchanged.
+    Monotonic upstream scheme for conservative laws (muscl):
+    a parabolic interpolation is used and black, dark grey and grey areas are exchanged.
+    Second order scheme (cen2):
+    the mean value is used and black, dark grey, grey and light grey areas are exchanged.
+    Note that this illustration does not include the flux limiter used in ppm and muscl schemes.}
+  \label{fig:TRA_adv_scheme}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 The key difference between the advection schemes available in \NEMO is the choice made in space and
+The key difference between the advection schemes available in \NEMO\ is the choice made in space and
 time interpolation to define the value of the tracer at the velocity points
 (\autoref{fig:adv_scheme}).
+(\autoref{fig:TRA_adv_scheme}).
 Along solid lateral and bottom boundaries a zero tracer flux is automatically specified,
 …
 \begin{description}
 \item[linear free surface:]
   (\np{ln\_linssh}~\forcode{= .true.})
+  (\np{ln\_linssh}\forcode{=.true.})
   the first level thickness is constant in time:
   the vertical boundary condition is applied at the fixed surface $z = 0$ rather than on
   the moving surface $z = \eta$.
   There is a non-zero advective flux which is set for all advection schemes as
   $\tau_w|_{k = 1/2} = T_{k = 1}$, \ie the product of surface velocity (at $z = 0$) by
+  $\tau_w|_{k = 1/2} = T_{k = 1}$, \ie\ the product of surface velocity (at $z = 0$) by
   the first level tracer value.
 \item[non-linear free surface:]
   (\np{ln\_linssh}~\forcode{= .false.})
+  (\np{ln\_linssh}\forcode{=.false.})
   convergence/divergence in the first ocean level moves the free surface up/down.
   There is no tracer advection through it so that the advective fluxes through the surface are also zero.
 …
 Nevertheless, in the latter case, it is achieved to a good approximation since
 the non-conservative term is the product of the time derivative of the tracer and the free surface height,
 two quantities that are not correlated \citep{Roullet_Madec_JGR00, Griffies_al_MWR01, Campin2004}.
 The velocity field that appears in (\autoref{eq:tra_adv} and \autoref{eq:tra_adv_zco}) is
 the centred (\textit{now}) \textit{effective} ocean velocity, \ie the \textit{eulerian} velocity
+two quantities that are not correlated \citep{roullet.madec_JGR00, griffies.pacanowski.ea_MWR01, campin.adcroft.ea_OM04}.
+The velocity field that appears in (\autoref{eq:TRA_adv} is
+the centred (\textit{now}) \textit{effective} ocean velocity, \ie\ the \textit{eulerian} velocity
 (see \autoref{chap:DYN}) plus the eddy induced velocity (\textit{eiv}) and/or
 the mixed layer eddy induced velocity (\textit{eiv}) when those parameterisations are used
 …
 Conservative Laws scheme (MUSCL), a $3^{rd}$ Upstream Biased Scheme (UBS, also often called UP3),
 and a Quadratic Upstream Interpolation for Convective Kinematics with Estimated Streaming Terms scheme (QUICKEST).
 The choice is made in the \ngn{namtra\_adv} namelist, by setting to \forcode{.true.} one of
+The choice is made in the \nam{tra\_adv} namelist, by setting to \forcode{.true.} one of
 the logicals \textit{ln\_traadv\_xxx}.
 The corresponding code can be found in the \textit{traadv\_xxx.F90} module, where
 \textit{xxx} is a 3 or 4 letter acronym corresponding to each scheme.
 By default (\ie in the reference namelist, \textit{namelist\_ref}), all the logicals are set to \forcode{.false.}.
+By default (\ie\ in the reference namelist, \textit{namelist\_ref}), all the logicals are set to \forcode{.false.}.
 If the user does not select an advection scheme in the configuration namelist (\textit{namelist\_cfg}),
 the tracers will \textit{not} be advected!
 …
 %        2nd and 4th order centred schemes
 % -------------------------------------------------------------------------------------------------------------
+\subsection{CEN: Centred scheme (\protect\np{ln\_traadv\_cen}~\forcode{= .true.})}
+\subsection[CEN: Centred scheme (\forcode{ln_traadv_cen=.true.})]
+{CEN: Centred scheme (\protect\np{ln\_traadv\_cen}\forcode{=.true.})}
 \label{subsec:TRA_adv_cen}
 %        2nd order centred scheme
 The centred advection scheme (CEN) is used when \np{ln\_traadv\_cen}~\forcode{= .true.}.
+%        2nd order centred scheme
+The centred advection scheme (CEN) is used when \np{ln\_traadv\_cen}\forcode{=.true.}.
 Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) and vertical direction by
 setting \np{nn\_cen\_h} and \np{nn\_cen\_v} to $2$ or $4$.
 …
 For example, in the $i$-direction :
 \begin{equation}
   \label{eq:tra_adv_cen2}
+  \label{eq:TRA_adv_cen2}
   \tau_u^{cen2} = \overline T ^{i + 1/2}
 \end{equation}
 CEN2 is non diffusive (\ie it conserves the tracer variance, $\tau^2$) but dispersive
 (\ie it may create false extrema).
+CEN2 is non diffusive (\ie\ it conserves the tracer variance, $\tau^2$) 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.
 The associated time-stepping is performed using a leapfrog scheme in conjunction with an Asselin time-filter,
 so $T$ in (\autoref{eq:tra_adv_cen2}) is the \textit{now} tracer value.
+so $T$ in (\autoref{eq:TRA_adv_cen2}) is the \textit{now} tracer value.
 Note that using the CEN2, the overall tracer advection is of second order accuracy since
 both (\autoref{eq:tra_adv}) and (\autoref{eq:tra_adv_cen2}) have this order of accuracy.
 %        4nd order centred scheme
+both (\autoref{eq:TRA_adv}) and (\autoref{eq:TRA_adv_cen2}) have this order of accuracy.
+%        4nd order centred scheme
 In the $4^{th}$ order formulation (CEN4), tracer values are evaluated at u- and v-points as
 …
 For example, in the $i$-direction:
 \begin{equation}
   \label{eq:tra_adv_cen4}
+  \label{eq:TRA_adv_cen4}
   \tau_u^{cen4} = \overline{T - \frac{1}{6} \, \delta_i \Big[ \delta_{i + 1/2}[T] \, \Big]}^{\,i + 1/2}
 \end{equation}
 In the vertical direction (\np{nn\_cen\_v}~\forcode{= 4}),
 a $4^{th}$ COMPACT interpolation has been prefered \citep{Demange_PhD2014}.
+In the vertical direction (\np{nn\_cen\_v}\forcode{=4}),
+a $4^{th}$ COMPACT interpolation has been prefered \citep{demange_phd14}.
 In the COMPACT scheme, both the field and its derivative are interpolated, which leads, after a matrix inversion,
 spectral characteristics similar to schemes of higher order \citep{Lele_JCP1992}.
+spectral characteristics similar to schemes of higher order \citep{lele_JCP92}.
 Strictly speaking, the CEN4 scheme is not a $4^{th}$ order advection scheme but
 a $4^{th}$ order evaluation of advective fluxes,
 since the divergence of advective fluxes \autoref{eq:tra_adv} is kept at $2^{nd}$ order.
+since the divergence of advective fluxes \autoref{eq:TRA_adv} is kept at $2^{nd}$ order.
 The expression \textit{$4^{th}$ order scheme} used in oceanographic literature is usually associated with
 the scheme presented here.
 …
 A direct consequence of the pseudo-fourth order nature of the scheme is that it is not non-diffusive,
 \ie the global variance of a tracer is not preserved using CEN4.
+\ie\ the global variance of a tracer is not preserved using CEN4.
 Furthermore, it must be used in conjunction with an explicit diffusion operator to produce a sensible solution.
 As in CEN2 case, the time-stepping is performed using a leapfrog scheme in conjunction with an Asselin time-filter,
 so $T$ in (\autoref{eq:tra_adv_cen4}) is the \textit{now} tracer.
+so $T$ in (\autoref{eq:TRA_adv_cen4}) is the \textit{now} tracer.
 At a $T$-grid cell adjacent to a boundary (coastline, bottom and surface),
 …
 % -------------------------------------------------------------------------------------------------------------
+%        FCT scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection{FCT: Flux Corrected Transport scheme (\protect\np{ln\_traadv\_fct}~\forcode{= .true.})}
+%        FCT scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection[FCT: Flux Corrected Transport scheme (\forcode{ln_traadv_fct=.true.})]
+{FCT: Flux Corrected Transport scheme (\protect\np{ln\_traadv\_fct}\forcode{=.true.})}
 \label{subsec:TRA_adv_tvd}
 The Flux Corrected Transport schemes (FCT) is used when \np{ln\_traadv\_fct}~\forcode{= .true.}.
+The Flux Corrected Transport schemes (FCT) is used when \np{ln\_traadv\_fct}\forcode{=.true.}.
 Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) and vertical direction by
 setting \np{nn\_fct\_h} and \np{nn\_fct\_v} to $2$ or $4$.
 …
 For example, in the $i$-direction :
 \begin{equation}
   \label{eq:tra_adv_fct}
+  \label{eq:TRA_adv_fct}
   \begin{split}
     \tau_u^{ups} &=
 …
 where $c_u$ is a flux limiter function taking values between 0 and 1.
 The FCT order is the one of the centred scheme used
 (\ie it depends on the setting of \np{nn\_fct\_h} and \np{nn\_fct\_v}).
+(\ie\ it depends on the setting of \np{nn\_fct\_h} and \np{nn\_fct\_v}).
 There exist many ways to define $c_u$, each corresponding to a different FCT scheme.
 The one chosen in \NEMO is described in \citet{Zalesak_JCP79}.
+The one chosen in \NEMO\ is described in \citet{zalesak_JCP79}.
 $c_u$ only departs from $1$ when the advective term produces a local extremum in the tracer field.
 The resulting scheme is quite expensive but \textit{positive}.
 It can be used on both active and passive tracers.
+A comparison of FCT-2 with MUSCL and a MPDATA scheme can be found in \citet{Levy_al_GRL01}.
+An additional option has been added controlled by \np{nn\_fct\_zts}.
+By setting this integer to a value larger than zero,
+a $2^{nd}$ order FCT scheme is used on both horizontal and vertical direction, but on the latter,
+a split-explicit time stepping is used, with a number of sub-timestep equals to \np{nn\_fct\_zts}.
+This option can be useful when the size of the timestep is limited by vertical advection \citep{Lemarie_OM2015}.
+Note that in this case, a similar split-explicit time stepping should be used on vertical advection of momentum to
+insure a better stability (see \autoref{subsec:DYN_zad}).
+For stability reasons (see \autoref{chap:STP}),
+$\tau_u^{cen}$ is evaluated in (\autoref{eq:tra_adv_fct}) using the \textit{now} tracer while
+A comparison of FCT-2 with MUSCL and a MPDATA scheme can be found in \citet{levy.estublier.ea_GRL01}.
+For stability reasons (see \autoref{chap:TD}),
+$\tau_u^{cen}$ is evaluated in (\autoref{eq:TRA_adv_fct}) using the \textit{now} tracer while
 $\tau_u^{ups}$ is evaluated using the \textit{before} tracer.
 In other words, the advective part of the scheme is time stepped with a leap-frog scheme
 …
 % -------------------------------------------------------------------------------------------------------------
+%        MUSCL scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection{MUSCL: Monotone Upstream Scheme for Conservative Laws (\protect\np{ln\_traadv\_mus}~\forcode{= .true.})}
+%        MUSCL scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection[MUSCL: Monotone Upstream Scheme for Conservative Laws (\forcode{ln_traadv_mus=.true.})]
+{MUSCL: Monotone Upstream Scheme for Conservative Laws (\protect\np{ln\_traadv\_mus}\forcode{=.true.})}
 \label{subsec:TRA_adv_mus}
 The Monotone Upstream Scheme for Conservative Laws (MUSCL) is used when \np{ln\_traadv\_mus}~\forcode{= .true.}.
+The Monotone Upstream Scheme for Conservative Laws (MUSCL) is used when \np{ln\_traadv\_mus}\forcode{=.true.}.
 MUSCL implementation can be found in the \mdl{traadv\_mus} module.
 MUSCL has been first implemented in \NEMO by \citet{Levy_al_GRL01}.
+MUSCL has been first implemented in \NEMO\ by \citet{levy.estublier.ea_GRL01}.
 In its formulation, the tracer at velocity points is evaluated assuming a linear tracer variation between
 two $T$-points (\autoref{fig:adv_scheme}).
+two $T$-points (\autoref{fig:TRA_adv_scheme}).
 For example, in the $i$-direction :
 \begin{equation}
   % \label{eq:tra_adv_mus}
+  % \label{eq:TRA_adv_mus}
   \tau_u^{mus} = \lt\{
   \begin{split}
 …
 This choice ensure the \textit{positive} character of the scheme.
 In addition, fluxes round a grid-point where a runoff is applied can optionally be computed using upstream fluxes
+(\np{ln\_mus\_ups}~\forcode{= .true.}).
+% -------------------------------------------------------------------------------------------------------------
+%        UBS scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection{UBS a.k.a. UP3: Upstream-Biased Scheme (\protect\np{ln\_traadv\_ubs}~\forcode{= .true.})}
+(\np{ln\_mus\_ups}\forcode{=.true.}).
+% -------------------------------------------------------------------------------------------------------------
+%        UBS scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection[UBS a.k.a. UP3: Upstream-Biased Scheme (\forcode{ln_traadv_ubs=.true.})]
+{UBS a.k.a. UP3: Upstream-Biased Scheme (\protect\np{ln\_traadv\_ubs}\forcode{=.true.})}
 \label{subsec:TRA_adv_ubs}
 The Upstream-Biased Scheme (UBS) is used when \np{ln\_traadv\_ubs}~\forcode{= .true.}.
+The Upstream-Biased Scheme (UBS) is used when \np{ln\_traadv\_ubs}\forcode{=.true.}.
 UBS implementation can be found in the \mdl{traadv\_mus} module.
 …
 For example, in the $i$-direction:
 \begin{equation}
   \label{eq:tra_adv_ubs}
+  \label{eq:TRA_adv_ubs}
   \tau_u^{ubs} = \overline T ^{i + 1/2} - \frac{1}{6}
     \begin{cases}
 …
 This results in a dissipatively dominant (i.e. hyper-diffusive) truncation error
 \citep{Shchepetkin_McWilliams_OM05}.
 The overall performance of the advection scheme is similar to that reported in \cite{Farrow1995}.
+\citep{shchepetkin.mcwilliams_OM05}.
+The overall performance of the advection scheme is similar to that reported in \cite{farrow.stevens_JPO95}.
 It is a relatively good compromise between accuracy and smoothness.
 Nevertheless the scheme is not \textit{positive}, meaning that false extrema are permitted,
 …
 The intrinsic diffusion of UBS makes its use risky in the vertical direction where
 the control of artificial diapycnal fluxes is of paramount importance
 \citep{Shchepetkin_McWilliams_OM05, Demange_PhD2014}.
+\citep{shchepetkin.mcwilliams_OM05, demange_phd14}.
 Therefore the vertical flux is evaluated using either a $2^nd$ order FCT scheme or a $4^th$ order COMPACT scheme
 (\np{nn\_cen\_v}~\forcode{= 2 or 4}).
 For stability reasons (see \autoref{chap:STP}), the first term  in \autoref{eq:tra_adv_ubs}
+(\np{nn\_ubs\_v}\forcode{=2 or 4}).
+For stability reasons (see \autoref{chap:TD}), the first term  in \autoref{eq:TRA_adv_ubs}
 (which corresponds to a second order centred scheme)
 is evaluated using the \textit{now} tracer (centred in time) while the second term
 (which is the diffusive part of the scheme),
 is evaluated using the \textit{before} tracer (forward in time).
 This choice is discussed by \citet{Webb_al_JAOT98} in the context of the QUICK advection scheme.
+This choice is discussed by \citet{webb.de-cuevas.ea_JAOT98} in the context of the QUICK advection scheme.
 UBS and QUICK schemes only differ by one coefficient.
 Replacing 1/6 with 1/8 in \autoref{eq:tra_adv_ubs} leads to the QUICK advection scheme \citep{Webb_al_JAOT98}.
+Replacing 1/6 with 1/8 in \autoref{eq:TRA_adv_ubs} leads to the QUICK advection scheme \citep{webb.de-cuevas.ea_JAOT98}.
 This option is not available through a namelist parameter, since the 1/6 coefficient is hard coded.
 Nevertheless it is quite easy to make the substitution in the \mdl{traadv\_ubs} module and obtain a QUICK scheme.
 Note that it is straightforward to rewrite \autoref{eq:tra_adv_ubs} as follows:
+Note that it is straightforward to rewrite \autoref{eq:TRA_adv_ubs} as follows:
 \begin{gather}
   \label{eq:traadv_ubs2}
+  \label{eq:TRA_adv_ubs2}
   \tau_u^{ubs} = \tau_u^{cen4} + \frac{1}{12}
     \begin{cases}
 …
     \end{cases}
   \intertext{or equivalently}
   % \label{eq:traadv_ubs2b}
+  % \label{eq:TRA_adv_ubs2b}
   u_{i + 1/2} \ \tau_u^{ubs} = u_{i + 1/2} \, \overline{T - \frac{1}{6} \, \delta_i \Big[ \delta_{i + 1/2}[T] \Big]}^{\,i + 1/2}
                              - \frac{1}{2} |u|_{i + 1/2} \, \frac{1}{6} \, \delta_{i + 1/2} [\tau"_i] \nonumber
 \end{gather}
 \autoref{eq:traadv_ubs2} has several advantages.
+\autoref{eq:TRA_adv_ubs2} has several advantages.
 Firstly, it clearly reveals that the UBS scheme is based on the fourth order scheme to which
 an upstream-biased diffusion term is added.
 Secondly, this emphasises that the $4^{th}$ order part (as well as the $2^{nd}$ order part as stated above) has to
 be evaluated at the \textit{now} time step using \autoref{eq:tra_adv_ubs}.
+be evaluated at the \textit{now} time step using \autoref{eq:TRA_adv_ubs}.
 Thirdly, the diffusion term is in fact a biharmonic operator with an eddy coefficient which
 is simply proportional to the velocity: $A_u^{lm} = \frac{1}{12} \, {e_{1u}}^3 \, |u|$.
+Note the current version of NEMO uses the computationally more efficient formulation \autoref{eq:tra_adv_ubs}.
+% -------------------------------------------------------------------------------------------------------------
+%        QCK scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection{QCK: QuiCKest scheme (\protect\np{ln\_traadv\_qck}~\forcode{= .true.})}
+Note the current version of \NEMO\ uses the computationally more efficient formulation \autoref{eq:TRA_adv_ubs}.
+% -------------------------------------------------------------------------------------------------------------
+%        QCK scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection[QCK: QuiCKest scheme (\forcode{ln_traadv_qck=.true.})]
+{QCK: QuiCKest scheme (\protect\np{ln\_traadv\_qck}\forcode{=.true.})}
 \label{subsec:TRA_adv_qck}
 The Quadratic Upstream Interpolation for Convective Kinematics with Estimated Streaming Terms (QUICKEST) scheme
 proposed by \citet{Leonard1979} is used when \np{ln\_traadv\_qck}~\forcode{= .true.}.
+proposed by \citet{leonard_CMAME79} is used when \np{ln\_traadv\_qck}\forcode{=.true.}.
 QUICKEST implementation can be found in the \mdl{traadv\_qck} module.
 QUICKEST is the third order Godunov scheme which is associated with the ULTIMATE QUICKEST limiter
 \citep{Leonard1991}.
 It has been implemented in NEMO by G. Reffray (MERCATOR-ocean) and can be found in the \mdl{traadv\_qck} module.
+\citep{leonard_CMAME91}.
+It has been implemented in \NEMO\ by G. Reffray (MERCATOR-ocean) and can be found in the \mdl{traadv\_qck} module.
 The resulting scheme is quite expensive but \textit{positive}.
 It can be used on both active and passive tracers.
 …
 % Tracer Lateral Diffusion
 % ================================================================
+\section{Tracer lateral diffusion (\protect\mdl{traldf})}
+\section[Tracer lateral diffusion (\textit{traldf.F90})]
+{Tracer lateral diffusion (\protect\mdl{traldf})}
 \label{sec:TRA_ldf}
 %-----------------------------------------nam_traldf------------------------------------------------------
+\nlst{namtra_ldf}
+\begin{listing}
+  \nlst{namtra_ldf}
+  \caption{\texttt{namtra\_ldf}}
+  \label{lst:namtra_ldf}
+\end{listing}
 %-------------------------------------------------------------------------------------------------------------
 Options are defined through the \ngn{namtra\_ldf} namelist variables.
 They are regrouped in four items, allowing to specify
+Options are defined through the \nam{tra\_ldf} namelist variables.
+They are regrouped in four items, allowing to specify
 $(i)$   the type of operator used (none, laplacian, bilaplacian),
 $(ii)$  the direction along which the operator acts (iso-level, horizontal, iso-neutral),
 $(iii)$ some specific options related to the rotated operators (\ie non-iso-level operator), and
+$(iii)$ some specific options related to the rotated operators (\ie\ non-iso-level operator), and
 $(iv)$  the specification of eddy diffusivity coefficient (either constant or variable in space and time).
 Item $(iv)$ will be described in \autoref{chap:LDF}.
 …
 The lateral diffusion of tracers is evaluated using a forward scheme,
 \ie the tracers appearing in its expression are the \textit{before} tracers in time,
+\ie\ the tracers appearing in its expression are the \textit{before} tracers in time,
 except for the pure vertical component that appears when a rotation tensor is used.
 This latter component is solved implicitly together with the vertical diffusion term (see \autoref{chap:STP}).
 When \np{ln\_traldf\_msc}~\forcode{= .true.}, a Method of Stabilizing Correction is used in which
 the pure vertical component is split into an explicit and an implicit part \citep{Lemarie_OM2012}.
+This latter component is solved implicitly together with the vertical diffusion term (see \autoref{chap:TD}).
+When \np{ln\_traldf\_msc}\forcode{=.true.}, a Method of Stabilizing Correction is used in which
+the pure vertical component is split into an explicit and an implicit part \citep{lemarie.debreu.ea_OM12}.
 % -------------------------------------------------------------------------------------------------------------
 %        Type of operator
 % -------------------------------------------------------------------------------------------------------------
+\subsection[Type of operator (\protect\np{ln\_traldf}\{\_NONE,\_lap,\_blp\}\})]{Type of operator (\protect\np{ln\_traldf\_NONE}, \protect\np{ln\_traldf\_lap}, or \protect\np{ln\_traldf\_blp}) }
+\subsection[Type of operator (\texttt{ln\_traldf}\{\texttt{\_OFF,\_lap,\_blp}\})]
+{Type of operator (\protect\np{ln\_traldf\_OFF}, \protect\np{ln\_traldf\_lap}, or \protect\np{ln\_traldf\_blp}) }
 \label{subsec:TRA_ldf_op}
 …
 \begin{description}
 \item[\np{ln\_traldf\_NONE}~\forcode{= .true.}:]
+\item[\np{ln\_traldf\_OFF}\forcode{=.true.}:]
   no operator selected, the lateral diffusive tendency will not be applied to the tracer equation.
   This option can be used when the selected advection scheme is diffusive enough (MUSCL scheme for example).
 \item[\np{ln\_traldf\_lap}~\forcode{= .true.}:]
+\item[\np{ln\_traldf\_lap}\forcode{=.true.}:]
   a laplacian operator is selected.
   This harmonic operator takes the following expression:  $\mathpzc{L}(T) = \nabla \cdot A_{ht} \; \nabla T $,
+  This harmonic operator takes the following expression:  $\mathcal{L}(T) = \nabla \cdot A_{ht} \; \nabla T $,
   where the gradient operates along the selected direction (see \autoref{subsec:TRA_ldf_dir}),
   and $A_{ht}$ is the eddy diffusivity coefficient expressed in $m^2/s$ (see \autoref{chap:LDF}).
 \item[\np{ln\_traldf\_blp}~\forcode{= .true.}]:
+\item[\np{ln\_traldf\_blp}\forcode{=.true.}]:
   a bilaplacian operator is selected.
   This biharmonic operator takes the following expression:
   $\mathpzc{B} = - \mathpzc{L}(\mathpzc{L}(T)) = - \nabla \cdot b \nabla (\nabla \cdot b \nabla T)$
+  $\mathcal{B} = - \mathcal{L}(\mathcal{L}(T)) = - \nabla \cdot b \nabla (\nabla \cdot b \nabla T)$
   where the gradient operats along the selected direction,
   and $b^2 = B_{ht}$ is the eddy diffusivity coefficient expressed in $m^4/s$ (see \autoref{chap:LDF}).
 …
 minimizing the impact on the larger scale features.
 The main difference between the two operators is the scale selectiveness.
 The bilaplacian damping time (\ie its spin down time) scales like $\lambda^{-4}$ for
+The bilaplacian damping time (\ie\ its spin down time) scales like $\lambda^{-4}$ for
 disturbances of wavelength $\lambda$ (so that short waves damped more rapidelly than long ones),
 whereas the laplacian damping time scales only like $\lambda^{-2}$.
 …
 %        Direction of action
 % -------------------------------------------------------------------------------------------------------------
+\subsection[Action direction (\protect\np{ln\_traldf}\{\_lev,\_hor,\_iso,\_triad\})]{Direction of action (\protect\np{ln\_traldf\_lev}, \protect\np{ln\_traldf\_hor}, \protect\np{ln\_traldf\_iso}, or \protect\np{ln\_traldf\_triad}) }
+\subsection[Action direction (\texttt{ln\_traldf}\{\texttt{\_lev,\_hor,\_iso,\_triad}\})]
+{Direction of action (\protect\np{ln\_traldf\_lev}, \protect\np{ln\_traldf\_hor}, \protect\np{ln\_traldf\_iso}, or \protect\np{ln\_traldf\_triad}) }
 \label{subsec:TRA_ldf_dir}
 The choice of a direction of action determines the form of operator used.
 The operator is a simple (re-entrant) laplacian acting in the (\textbf{i},\textbf{j}) plane when
 iso-level option is used (\np{ln\_traldf\_lev}~\forcode{= .true.}) or
 when a horizontal (\ie geopotential) operator is demanded in \textit{z}-coordinate
 (\np{ln\_traldf\_hor} and \np{ln\_zco} equal \forcode{.true.}).
+iso-level option is used (\np{ln\_traldf\_lev}\forcode{=.true.}) or
+when a horizontal (\ie\ geopotential) operator is demanded in \textit{z}-coordinate
+(\np{ln\_traldf\_hor} and \np{ln\_zco}\forcode{=.true.}).
 The associated code can be found in the \mdl{traldf\_lap\_blp} module.
 The operator is a rotated (re-entrant) laplacian when
 the direction along which it acts does not coincide with the iso-level surfaces,
 that is when standard or triad iso-neutral option is used
 (\np{ln\_traldf\_iso} or \np{ln\_traldf\_triad} equals \forcode{.true.},
+(\np{ln\_traldf\_iso} or \np{ln\_traldf\_triad} = \forcode{.true.},
 see \mdl{traldf\_iso} or \mdl{traldf\_triad} module, resp.), or
 when a horizontal (\ie geopotential) operator is demanded in \textit{s}-coordinate
 (\np{ln\_traldf\_hor} and \np{ln\_sco} equal \forcode{.true.})
+when a horizontal (\ie\ geopotential) operator is demanded in \textit{s}-coordinate
+(\np{ln\_traldf\_hor} and \np{ln\_sco} = \forcode{.true.})
 \footnote{In this case, the standard iso-neutral operator will be automatically selected}.
 In that case, a rotation is applied to the gradient(s) that appears in the operator so that
 …
 %       iso-level operator
 % -------------------------------------------------------------------------------------------------------------
+\subsection{Iso-level (bi -)laplacian operator ( \protect\np{ln\_traldf\_iso}) }
+\subsection[Iso-level (bi-)laplacian operator (\texttt{ln\_traldf\_iso})]
+{Iso-level (bi-)laplacian operator ( \protect\np{ln\_traldf\_iso})}
 \label{subsec:TRA_ldf_lev}
 The laplacian diffusion operator acting along the model (\textit{i,j})-surfaces is given by:
 \begin{equation}
   \label{eq:tra_ldf_lap}
+The laplacian diffusion operator acting along the model (\textit{i,j})-surfaces is given by:
+\begin{equation}
+  \label{eq:TRA_ldf_lap}
   D_t^{lT} = \frac{1}{b_t} \Bigg(   \delta_{i} \lt[ A_u^{lT} \; \frac{e_{2u} \, e_{3u}}{e_{1u}} \; \delta_{i + 1/2} [T] \rt]
                                   + \delta_{j} \lt[ A_v^{lT} \; \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [T] \rt] \Bigg)
 …
 where zero diffusive fluxes is assumed across solid boundaries,
 first (and third in bilaplacian case) horizontal tracer derivative are masked.
 It is implemented in the \rou{traldf\_lap} subroutine found in the \mdl{traldf\_lap} module.
 The module also contains \rou{traldf\_blp}, the subroutine calling twice \rou{traldf\_lap} in order to
+It is implemented in the \rou{tra\_ldf\_lap} subroutine found in the \mdl{traldf\_lap\_blp} module.
+The module also contains \rou{tra\_ldf\_blp}, the subroutine calling twice \rou{tra\_ldf\_lap} in order to
 compute the iso-level bilaplacian operator.
 It is a \textit{horizontal} operator (\ie acting along geopotential surfaces) in
 the $z$-coordinate with or without partial steps, but is simply an iso-level operator in the $s$-coordinate.
 It is thus used when, in addition to \np{ln\_traldf\_lap} or \np{ln\_traldf\_blp}~\forcode{= .true.},
 we have \np{ln\_traldf\_lev}~\forcode{= .true.} or \np{ln\_traldf\_hor}~=~\np{ln\_zco}~\forcode{= .true.}.
+It is thus used when, in addition to \np{ln\_traldf\_lap} or \np{ln\_traldf\_blp}\forcode{=.true.},
+we have \np{ln\_traldf\_lev}\forcode{=.true.} or \np{ln\_traldf\_hor}~=~\np{ln\_zco}\forcode{=.true.}.
 In both cases, it significantly contributes to diapycnal mixing.
 It is therefore never recommended, even when using it in the bilaplacian case.
 Note that in the partial step $z$-coordinate (\np{ln\_zps}~\forcode{= .true.}),
+Note that in the partial step $z$-coordinate (\np{ln\_zps}\forcode{=.true.}),
 tracers in horizontally adjacent cells are located at different depths in the vicinity of the bottom.
 In this case, horizontal derivatives in (\autoref{eq:tra_ldf_lap}) at the bottom level require a specific treatment.
+In this case, horizontal derivatives in (\autoref{eq:TRA_ldf_lap}) at the bottom level require a specific treatment.
 They are calculated in the \mdl{zpshde} module, described in \autoref{sec:TRA_zpshde}.
 …
 %         Rotated laplacian operator
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Standard and triad (bi -)laplacian operator}
+\subsection{Standard and triad (bi-)laplacian operator}
 \label{subsec:TRA_ldf_iso_triad}
 %&&    Standard rotated (bi -)laplacian operator
+%&&    Standard rotated (bi-)laplacian operator
 %&& ----------------------------------------------
+\subsubsection{Standard rotated (bi -)laplacian operator (\protect\mdl{traldf\_iso})}
+\subsubsection[Standard rotated (bi-)laplacian operator (\textit{traldf\_iso.F90})]
+{Standard rotated (bi-)laplacian operator (\protect\mdl{traldf\_iso})}
 \label{subsec:TRA_ldf_iso}
 The general form of the second order lateral tracer subgrid scale physics (\autoref{eq:PE_zdf})
+The general form of the second order lateral tracer subgrid scale physics (\autoref{eq:MB_zdf})
 takes the following semi -discrete space form in $z$- and $s$-coordinates:
 \begin{equation}
   \label{eq:tra_ldf_iso}
+  \label{eq:TRA_ldf_iso}
   \begin{split}
     D_T^{lT} = \frac{1}{b_t} \Bigg[ \quad &\delta_i A_u^{lT} \lt( \frac{e_{2u} e_{3u}}{e_{1u}}                      \, \delta_{i + 1/2} [T]
 …
 where $b_t = e_{1t} \, e_{2t} \, e_{3t}$  is the volume of $T$-cells,
 $r_1$ and $r_2$ are the slopes between the surface of computation ($z$- or $s$-surfaces) and
 the surface along which the diffusion operator acts (\ie horizontal or iso-neutral surfaces).
 It is thus used when, in addition to \np{ln\_traldf\_lap}~\forcode{= .true.},
 we have \np{ln\_traldf\_iso}~\forcode{= .true.},
 or both \np{ln\_traldf\_hor}~\forcode{= .true.} and \np{ln\_zco}~\forcode{= .true.}.
+the surface along which the diffusion operator acts (\ie\ horizontal or iso-neutral surfaces).
+It is thus used when, in addition to \np{ln\_traldf\_lap}\forcode{=.true.},
+we have \np{ln\_traldf\_iso}\forcode{=.true.},
+or both \np{ln\_traldf\_hor}\forcode{=.true.} and \np{ln\_zco}\forcode{=.true.}.
 The way these slopes are evaluated is given in \autoref{sec:LDF_slp}.
 At the surface, bottom and lateral boundaries, the turbulent fluxes of heat and salt are set to zero using
 the mask technique (see \autoref{sec:LBC_coast}).
 The operator in \autoref{eq:tra_ldf_iso} involves both lateral and vertical derivatives.
+The operator in \autoref{eq:TRA_ldf_iso} involves both lateral and vertical derivatives.
 For numerical stability, the vertical second derivative must be solved using the same implicit time scheme as that
 used in the vertical physics (see \autoref{sec:TRA_zdf}).
 …
 This formulation conserves the tracer but does not ensure the decrease of the tracer variance.
 Nevertheless the treatment performed on the slopes (see \autoref{chap:LDF}) allows the model to run safely without
 any additional background horizontal diffusion \citep{Guilyardi_al_CD01}.
 Note that in the partial step $z$-coordinate (\np{ln\_zps}~\forcode{= .true.}),
 the horizontal derivatives at the bottom level in \autoref{eq:tra_ldf_iso} require a specific treatment.
+any additional background horizontal diffusion \citep{guilyardi.madec.ea_CD01}.
+Note that in the partial step $z$-coordinate (\np{ln\_zps}\forcode{=.true.}),
+the horizontal derivatives at the bottom level in \autoref{eq:TRA_ldf_iso} require a specific treatment.
 They are calculated in module zpshde, described in \autoref{sec:TRA_zpshde}.
 %&&     Triad rotated (bi -)laplacian operator
+%&&     Triad rotated (bi-)laplacian operator
 %&&  -------------------------------------------
+\subsubsection{Triad rotated (bi -)laplacian operator (\protect\np{ln\_traldf\_triad})}
+\subsubsection[Triad rotated (bi-)laplacian operator (\textit{ln\_traldf\_triad})]
+{Triad rotated (bi-)laplacian operator (\protect\np{ln\_traldf\_triad})}
 \label{subsec:TRA_ldf_triad}
+If the Griffies triad scheme is employed (\np{ln\_traldf\_triad}~\forcode{= .true.}; see \autoref{apdx:triad})
+An alternative scheme developed by \cite{Griffies_al_JPO98} which ensures tracer variance decreases
+is also available in \NEMO (\np{ln\_traldf\_grif}~\forcode{= .true.}).
+A complete description of the algorithm is given in \autoref{apdx:triad}.
+The lateral fourth order bilaplacian operator on tracers is obtained by applying (\autoref{eq:tra_ldf_lap}) twice.
+An alternative scheme developed by \cite{griffies.gnanadesikan.ea_JPO98} which ensures tracer variance decreases
+is also available in \NEMO\ (\np{ln\_traldf\_triad}\forcode{=.true.}).
+A complete description of the algorithm is given in \autoref{apdx:TRIADS}.
+The lateral fourth order bilaplacian operator on tracers is obtained by applying (\autoref{eq:TRA_ldf_lap}) twice.
 The operator requires an additional assumption on boundary conditions:
 both first and third derivative terms normal to the coast are set to zero.
 The lateral fourth order operator formulation on tracers is obtained by applying (\autoref{eq:tra_ldf_iso}) twice.
+The lateral fourth order operator formulation on tracers is obtained by applying (\autoref{eq:TRA_ldf_iso}) twice.
 It requires an additional assumption on boundary conditions:
 first and third derivative terms normal to the coast,
 …
 \item \np{rn\_slpmax} = slope limit (both operators)
 \item \np{ln\_triad\_iso} = pure horizontal mixing in ML (triad only)
 \item \np{rn\_sw\_triad} $= 1$ switching triad; $= 0$ all 4 triads used (triad only)
+\item \np{rn\_sw\_triad} $= 1$ switching triad; $= 0$ all 4 triads used (triad only)
 \item \np{ln\_botmix\_triad} = lateral mixing on bottom (triad only)
 \end{itemize}
 …
 % Tracer Vertical Diffusion
 % ================================================================
+\section{Tracer vertical diffusion (\protect\mdl{trazdf})}
+\section[Tracer vertical diffusion (\textit{trazdf.F90})]
+{Tracer vertical diffusion (\protect\mdl{trazdf})}
 \label{sec:TRA_zdf}
 %--------------------------------------------namzdf---------------------------------------------------------
-\nlst{namzdf}
 %--------------------------------------------------------------------------------------------------------------
 Options are defined through the \ngn{namzdf} namelist variables.
+Options are defined through the \nam{zdf} namelist variables.
 The formulation of the vertical subgrid scale tracer physics is the same for all the vertical coordinates,
 and is based on a laplacian operator.
 The vertical diffusion operator given by (\autoref{eq:PE_zdf}) takes the following semi -discrete space form:
+The vertical diffusion operator given by (\autoref{eq:MB_zdf}) takes the following semi -discrete space form:
 \begin{gather*}
   % \label{eq:tra_zdf}
+  % \label{eq:TRA_zdf}
     D^{vT}_T = \frac{1}{e_{3t}} \, \delta_k \lt[ \, \frac{A^{vT}_w}{e_{3w}} \delta_{k + 1/2}[T] \, \rt] \\
     D^{vS}_T = \frac{1}{e_{3t}} \; \delta_k \lt[ \, \frac{A^{vS}_w}{e_{3w}} \delta_{k + 1/2}[S] \, \rt]
 …
 respectively.
 Generally, $A_w^{vT} = A_w^{vS}$ except when double diffusive mixing is parameterised
 (\ie \key{zdfddm} is defined).
+(\ie\ \np{ln\_zdfddm}\forcode{=.true.},).
 The way these coefficients are evaluated is given in \autoref{chap:ZDF} (ZDF).
 Furthermore, when iso-neutral mixing is used, both mixing coefficients are increased by
 $\frac{e_{1w} e_{2w}}{e_{3w} }({r_{1w}^2 + r_{2w}^2})$ to account for the vertical second derivative of
 \autoref{eq:tra_ldf_iso}.
+\autoref{eq:TRA_ldf_iso}.
 At the surface and bottom boundaries, the turbulent fluxes of heat and salt must be specified.
 …
 The large eddy coefficient found in the mixed layer together with high vertical resolution implies that
+in the case of explicit time stepping (\np{ln\_zdfexp}~\forcode{= .true.})
+there would be too restrictive a constraint on the time step.
+Therefore, the default implicit time stepping is preferred for the vertical diffusion since
+there would be too restrictive constraint on the time step if we use explicit time stepping.
+Therefore an implicit time stepping is preferred for the vertical diffusion since
 it overcomes the stability constraint.
-A forward time differencing scheme (\np{ln\_zdfexp}~\forcode{= .true.}) using
-a time splitting technique (\np{nn\_zdfexp} $> 1$) is provided as an alternative.
-Namelist variables \np{ln\_zdfexp} and \np{nn\_zdfexp} apply to both tracers and dynamics.
 % ================================================================
 …
 %        surface boundary condition
 % -------------------------------------------------------------------------------------------------------------
+\subsection{Surface boundary condition (\protect\mdl{trasbc})}
+\subsection[Surface boundary condition (\textit{trasbc.F90})]
+{Surface boundary condition (\protect\mdl{trasbc})}
 \label{subsec:TRA_sbc}
 …
 Due to interactions and mass exchange of water ($F_{mass}$) with other Earth system components
 (\ie atmosphere, sea-ice, land), the change in the heat and salt content of the surface layer of the ocean is due
+(\ie\ atmosphere, sea-ice, land), the change in the heat and salt content of the surface layer of the ocean is due
 both to the heat and salt fluxes crossing the sea surface (not linked with $F_{mass}$) and
 to the heat and salt content of the mass exchange.
 …
 \item
   $Q_{ns}$, the non-solar part of the net surface heat flux that crosses the sea surface
   (\ie the difference between the total surface heat flux and the fraction of the short wave flux that
+  (\ie\ the difference between the total surface heat flux and the fraction of the short wave flux that
   penetrates into the water column, see \autoref{subsec:TRA_qsr})
   plus the heat content associated with of the mass exchange with the atmosphere and lands.
 …
 The surface boundary condition on temperature and salinity is applied as follows:
 \begin{equation}
   \label{eq:tra_sbc}
+  \label{eq:TRA_sbc}
   \begin{alignedat}{2}
     F^T &= \frac{1}{C_p} &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} &\overline{Q_{ns}      }^t \\
 …
 where $\overline x^t$ means that $x$ is averaged over two consecutive time steps
 ($t - \rdt / 2$ and $t + \rdt / 2$).
 Such time averaging prevents the divergence of odd and even time step (see \autoref{chap:STP}).
 In the linear free surface case (\np{ln\_linssh}~\forcode{= .true.}), an additional term has to be added on
+Such time averaging prevents the divergence of odd and even time step (see \autoref{chap:TD}).
+In the linear free surface case (\np{ln\_linssh}\forcode{=.true.}), an additional term has to be added on
 both temperature and salinity.
 On temperature, this term remove the heat content associated with mass exchange that has been added to $Q_{ns}$.
 …
 The resulting surface boundary condition is applied as follows:
 \begin{equation}
   \label{eq:tra_sbc_lin}
+  \label{eq:TRA_sbc_lin}
   \begin{alignedat}{2}
     F^T &= \frac{1}{C_p} &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}}
 …
           &\overline{(\textit{sfx} -        \textit{emp} \lt. S \rt|_{k = 1})}^t
   \end{alignedat}
 \end{equation}
+\end{equation}
 Note that an exact conservation of heat and salt content is only achieved with non-linear free surface.
 In the linear free surface case, there is a small imbalance.
+The imbalance is larger than the imbalance associated with the Asselin time filter \citep{Leclair_Madec_OM09}.
+This is the reason why the modified filter is not applied in the linear free surface case (see \autoref{chap:STP}).
+% -------------------------------------------------------------------------------------------------------------
+%        Solar Radiation Penetration
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Solar radiation penetration (\protect\mdl{traqsr})}
+The imbalance is larger than the imbalance associated with the Asselin time filter \citep{leclair.madec_OM09}.
+This is the reason why the modified filter is not applied in the linear free surface case (see \autoref{chap:TD}).
+% -------------------------------------------------------------------------------------------------------------
+%        Solar Radiation Penetration
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Solar radiation penetration (\textit{traqsr.F90})]
+{Solar radiation penetration (\protect\mdl{traqsr})}
 \label{subsec:TRA_qsr}
 %--------------------------------------------namqsr--------------------------------------------------------
+\nlst{namtra_qsr}
+\begin{listing}
+  \nlst{namtra_qsr}
+  \caption{\texttt{namtra\_qsr}}
+  \label{lst:namtra_qsr}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------------
 Options are defined through the \ngn{namtra\_qsr} namelist variables.
 When the penetrative solar radiation option is used (\np{ln\_flxqsr}~\forcode{= .true.}),
+Options are defined through the \nam{tra\_qsr} namelist variables.
+When the penetrative solar radiation option is used (\np{ln\_traqsr}\forcode{=.true.}),
 the solar radiation penetrates the top few tens of meters of the ocean.
 If it is not used (\np{ln\_flxqsr}~\forcode{= .false.}) all the heat flux is absorbed in the first ocean level.
 Thus, in the former case a term is added to the time evolution equation of temperature \autoref{eq:PE_tra_T} and
 the surface boundary condition is modified to take into account only the non-penetrative part of the surface
+If it is not used (\np{ln\_traqsr}\forcode{=.false.}) all the heat flux is absorbed in the first ocean level.
+Thus, in the former case a term is added to the time evolution equation of temperature \autoref{eq:MB_PE_tra_T} and
+the surface boundary condition is modified to take into account only the non-penetrative part of the surface
 heat flux:
 \begin{equation}
   \label{eq:PE_qsr}
+  \label{eq:TRA_PE_qsr}
   \begin{gathered}
     \pd[T]{t} = \ldots + \frac{1}{\rho_o \, C_p \, e_3} \; \pd[I]{k} \\
 …
   \end{gathered}
 \end{equation}
 where $Q_{sr}$ is the penetrative part of the surface heat flux (\ie the shortwave radiation) and
+where $Q_{sr}$ is the penetrative part of the surface heat flux (\ie\ the shortwave radiation) and
 $I$ is the downward irradiance ($\lt. I \rt|_{z = \eta} = Q_{sr}$).
 The additional term in \autoref{eq:PE_qsr} is discretized as follows:
 \begin{equation}
   \label{eq:tra_qsr}
+The additional term in \autoref{eq:TRA_PE_qsr} is discretized as follows:
+\begin{equation}
+  \label{eq:TRA_qsr}
   \frac{1}{\rho_o \, C_p \, e_3} \, \pd[I]{k} \equiv \frac{1}{\rho_o \, C_p \, e_{3t}} \delta_k [I_w]
 \end{equation}
 …
 (specified through namelist parameter \np{rn\_abs}).
 It is assumed to penetrate the ocean with a decreasing exponential profile, with an e-folding depth scale, $\xi_0$,
 of a few tens of centimetres (typically $\xi_0 = 0.35~m$ set as \np{rn\_si0} in the \ngn{namtra\_qsr} namelist).
+of a few tens of centimetres (typically $\xi_0 = 0.35~m$ set as \np{rn\_si0} in the \nam{tra\_qsr} namelist).
 For shorter wavelengths (400-700~nm), the ocean is more transparent, and solar energy propagates to
 larger depths where it contributes to local heating.
 The way this second part of the solar energy penetrates into the ocean depends on which formulation is chosen.
 In the simple 2-waveband light penetration scheme (\np{ln\_qsr\_2bd}~\forcode{= .true.})
+In the simple 2-waveband light penetration scheme (\np{ln\_qsr\_2bd}\forcode{=.true.})
 a chlorophyll-independent monochromatic formulation is chosen for the shorter wavelengths,
 leading to the following expression \citep{Paulson1977}:
+leading to the following expression \citep{paulson.simpson_JPO77}:
 \[
   % \label{eq:traqsr_iradiance}
+  % \label{eq:TRA_qsr_iradiance}
   I(z) = Q_{sr} \lt[ Re^{- z / \xi_0} + (1 - R) e^{- z / \xi_1} \rt]
 \]
 …
 Such assumptions have been shown to provide a very crude and simplistic representation of
 observed light penetration profiles (\cite{Morel_JGR88}, see also \autoref{fig:traqsr_irradiance}).
+observed light penetration profiles (\cite{morel_JGR88}, see also \autoref{fig:TRA_qsr_irradiance}).
 Light absorption in the ocean depends on particle concentration and is spectrally selective.
 \cite{Morel_JGR88} has shown that an accurate representation of light penetration can be provided by
+\cite{morel_JGR88} has shown that an accurate representation of light penetration can be provided by
 a 61 waveband formulation.
 Unfortunately, such a model is very computationally expensive.
 Thus, \cite{Lengaigne_al_CD07} have constructed a simplified version of this formulation in which
+Thus, \cite{lengaigne.menkes.ea_CD07} have constructed a simplified version of this formulation in which
 visible light is split into three wavebands: blue (400-500 nm), green (500-600 nm) and red (600-700nm).
 For each wave-band, the chlorophyll-dependent attenuation coefficient is fitted to the coefficients computed from
 the full spectral model of \cite{Morel_JGR88} (as modified by \cite{Morel_Maritorena_JGR01}),
+the full spectral model of \cite{morel_JGR88} (as modified by \cite{morel.maritorena_JGR01}),
 assuming the same power-law relationship.
 As shown in \autoref{fig:traqsr_irradiance}, this formulation, called RGB (Red-Green-Blue),
+As shown in \autoref{fig:TRA_qsr_irradiance}, this formulation, called RGB (Red-Green-Blue),
 reproduces quite closely the light penetration profiles predicted by the full spectal model,
 but with much greater computational efficiency.
 The 2-bands formulation does not reproduce the full model very well.
 The RGB formulation is used when \np{ln\_qsr\_rgb}~\forcode{= .true.}.
 The RGB attenuation coefficients (\ie the inverses of the extinction length scales) are tabulated over
+The RGB formulation is used when \np{ln\_qsr\_rgb}\forcode{=.true.}.
+The RGB attenuation coefficients (\ie\ the inverses of the extinction length scales) are tabulated over
 nonuniform chlorophyll classes ranging from 0.01 to 10 g.Chl/L
 (see the routine \rou{trc\_oce\_rgb} in \mdl{trc\_oce} module).
 …
 \begin{description}
 \item[\np{nn\_chdta}~\forcode{= 0}]
   a constant 0.05 g.Chl/L value everywhere ;
 \item[\np{nn\_chdta}~\forcode{= 1}]
+\item[\np{nn\_chldta}\forcode{=0}]
+  a constant 0.05 g.Chl/L value everywhere ;
+\item[\np{nn\_chldta}\forcode{=1}]
   an observed time varying chlorophyll deduced from satellite surface ocean color measurement spread uniformly in
   the vertical direction;
 \item[\np{nn\_chdta}~\forcode{= 2}]
+\item[\np{nn\_chldta}\forcode{=2}]
   same as previous case except that a vertical profile of chlorophyl is used.
   Following \cite{Morel_Berthon_LO89}, the profile is computed from the local surface chlorophyll value;
 \item[\np{ln\_qsr\_bio}~\forcode{= .true.}]
+  Following \cite{morel.berthon_LO89}, the profile is computed from the local surface chlorophyll value;
+\item[\np{ln\_qsr\_bio}\forcode{=.true.}]
   simulated time varying chlorophyll by TOP biogeochemical model.
   In this case, the RGB formulation is used to calculate both the phytoplankton light limitation in
   PISCES or LOBSTER and the oceanic heating rate.
 \end{description}
 The trend in \autoref{eq:tra_qsr} associated with the penetration of the solar radiation is added to
+  PISCES and the oceanic heating rate.
+\end{description}
+The trend in \autoref{eq:TRA_qsr} associated with the penetration of the solar radiation is added to
 the temperature trend, and the surface heat flux is modified in routine \mdl{traqsr}.
 …
 the depth of $w-$levels does not significantly vary with location.
 The level at which the light has been totally absorbed
 (\ie it is less than the computer precision) is computed once,
+(\ie\ it is less than the computer precision) is computed once,
 and the trend associated with the penetration of the solar radiation is only added down to that level.
 Finally, note that when the ocean is shallow ($<$ 200~m), part of the solar radiation can reach the ocean floor.
 In this case, we have chosen that all remaining radiation is absorbed in the last ocean level
 (\ie $I$ is masked).
+(\ie\ $I$ is masked).
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[]{Fig_TRA_Irradiance}
+    \caption{
+      \protect\label{fig:traqsr_irradiance}
+      Penetration profile of the downward solar irradiance calculated by four models.
+      Two waveband chlorophyll-independent formulation (blue),
+      a chlorophyll-dependent monochromatic formulation (green),
+waveband RGB formulation (red),
+waveband Morel (1988) formulation (black) for a chlorophyll concentration of
+      (a) Chl=0.05 mg/m$^3$ and (b) Chl=0.5 mg/m$^3$.
+      From \citet{Lengaigne_al_CD07}.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_TRA_Irradiance}
+  \caption[Penetration profile of the downward solar irradiance calculated by four models]{
+    Penetration profile of the downward solar irradiance calculated by four models.
+    Two waveband chlorophyll-independent formulation (blue),
+    a chlorophyll-dependent monochromatic formulation (green),
+waveband RGB formulation (red),
+waveband Morel (1988) formulation (black) for a chlorophyll concentration of
+    (a) Chl=0.05 mg/m$^3$ and (b) Chl=0.5 mg/m$^3$.
+    From \citet{lengaigne.menkes.ea_CD07}.}
+  \label{fig:TRA_qsr_irradiance}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 %        Bottom Boundary Condition
 % -------------------------------------------------------------------------------------------------------------
+\subsection{Bottom boundary condition (\protect\mdl{trabbc})}
+\subsection[Bottom boundary condition (\textit{trabbc.F90}) - \forcode{ln_trabbc=.true.})]
+{Bottom boundary condition (\protect\mdl{trabbc})}
 \label{subsec:TRA_bbc}
 %--------------------------------------------nambbc--------------------------------------------------------
+\nlst{nambbc}
+\begin{listing}
+  \nlst{nambbc}
+  \caption{\texttt{nambbc}}
+  \label{lst:nambbc}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------------
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[]{Fig_TRA_geoth}
+    \caption{
+      \protect\label{fig:geothermal}
+      Geothermal Heat flux (in $mW.m^{-2}$) used by \cite{Emile-Geay_Madec_OS09}.
+      It is inferred from the age of the sea floor and the formulae of \citet{Stein_Stein_Nat92}.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_TRA_geoth}
+  \caption[Geothermal heat flux]{
+    Geothermal Heat flux (in $mW.m^{-2}$) used by \cite{emile-geay.madec_OS09}.
+    It is inferred from the age of the sea floor and the formulae of \citet{stein.stein_N92}.}
+  \label{fig:TRA_geothermal}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 Usually it is assumed that there is no exchange of heat or salt through the ocean bottom,
 \ie a no flux boundary condition is applied on active tracers at the bottom.
+\ie\ a no flux boundary condition is applied on active tracers at the bottom.
 This is the default option in \NEMO, and it is implemented using the masking technique.
 However, there is a non-zero heat flux across the seafloor that is associated with solid earth cooling.
 This flux is weak compared to surface fluxes (a mean global value of $\sim 0.1 \, W/m^2$ \citep{Stein_Stein_Nat92}),
+This flux is weak compared to surface fluxes (a mean global value of $\sim 0.1 \, W/m^2$ \citep{stein.stein_N92}),
 but it warms systematically the ocean and acts on the densest water masses.
 Taking this flux into account in a global ocean model increases the deepest overturning cell
 (\ie the one associated with the Antarctic Bottom Water) by a few Sverdrups \citep{Emile-Geay_Madec_OS09}.
 Options are defined through the  \ngn{namtra\_bbc} namelist variables.
+(\ie\ the one associated with the Antarctic Bottom Water) by a few Sverdrups \citep{emile-geay.madec_OS09}.
+Options are defined through the \nam{bbc} namelist variables.
 The presence of geothermal heating is controlled by setting the namelist parameter \np{ln\_trabbc} to true.
 Then, when \np{nn\_geoflx} is set to 1, a constant geothermal heating is introduced whose value is given by
 the \np{nn\_geoflx\_cst}, which is also a namelist parameter.
+the \np{rn\_geoflx\_cst}, which is also a namelist parameter.
 When \np{nn\_geoflx} is set to 2, a spatially varying geothermal heat flux is introduced which is provided in
 the \ifile{geothermal\_heating} NetCDF file (\autoref{fig:geothermal}) \citep{Emile-Geay_Madec_OS09}.
+the \ifile{geothermal\_heating} NetCDF file (\autoref{fig:TRA_geothermal}) \citep{emile-geay.madec_OS09}.
 % ================================================================
 % Bottom Boundary Layer
 % ================================================================
+\section{Bottom boundary layer (\protect\mdl{trabbl} - \protect\key{trabbl})}
+\section[Bottom boundary layer (\textit{trabbl.F90} - \forcode{ln_trabbl=.true.})]
+{Bottom boundary layer (\protect\mdl{trabbl} - \protect\np{ln\_trabbl}\forcode{=.true.})}
 \label{sec:TRA_bbl}
 %--------------------------------------------nambbl---------------------------------------------------------
+\nlst{nambbl}
+\begin{listing}
+  \nlst{nambbl}
+  \caption{\texttt{nambbl}}
+  \label{lst:nambbl}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------------
 Options are defined through the \ngn{nambbl} namelist variables.
+Options are defined through the \nam{bbl} namelist variables.
 In a $z$-coordinate configuration, the bottom topography is represented by a series of discrete steps.
 This is not adequate to represent gravity driven downslope flows.
 …
 sometimes over a thickness much larger than the thickness of the observed gravity plume.
 A similar problem occurs in the $s$-coordinate when the thickness of the bottom level varies rapidly downstream of
 a sill \citep{Willebrand_al_PO01}, and the thickness of the plume is not resolved.
 The idea of the bottom boundary layer (BBL) parameterisation, first introduced by \citet{Beckmann_Doscher1997},
+a sill \citep{willebrand.barnier.ea_PO01}, and the thickness of the plume is not resolved.
+The idea of the bottom boundary layer (BBL) parameterisation, first introduced by \citet{beckmann.doscher_JPO97},
 is to allow a direct communication between two adjacent bottom cells at different levels,
 whenever the densest water is located above the less dense water.
 …
 In the current implementation of the BBL, only the tracers are modified, not the velocities.
 Furthermore, it only connects ocean bottom cells, and therefore does not include all the improvements introduced by
 \citet{Campin_Goosse_Tel99}.
+\citet{campin.goosse_T99}.
 % -------------------------------------------------------------------------------------------------------------
 %        Diffusive BBL
 % -------------------------------------------------------------------------------------------------------------
+\subsection{Diffusive bottom boundary layer (\protect\np{nn\_bbl\_ldf}~\forcode{= 1})}
+\subsection[Diffusive bottom boundary layer (\forcode{nn_bbl_ldf=1})]
+{Diffusive bottom boundary layer (\protect\np{nn\_bbl\_ldf}\forcode{=1})}
 \label{subsec:TRA_bbl_diff}
 When applying sigma-diffusion (\key{trabbl} defined and \np{nn\_bbl\_ldf} set to 1),
 the diffusive flux between two adjacent cells at the ocean floor is given by
+When applying sigma-diffusion (\np{ln\_trabbl}\forcode{=.true.} and \np{nn\_bbl\_ldf} set to 1),
+the diffusive flux between two adjacent cells at the ocean floor is given by
 \[
   % \label{eq:tra_bbl_diff}
+  % \label{eq:TRA_bbl_diff}
   \vect F_\sigma = A_l^\sigma \, \nabla_\sigma T
 \]
 with $\nabla_\sigma$ the lateral gradient operator taken between bottom cells, and
 $A_l^\sigma$ the lateral diffusivity in the BBL.
 Following \citet{Beckmann_Doscher1997}, the latter is prescribed with a spatial dependence,
 \ie in the conditional form
 \begin{equation}
   \label{eq:tra_bbl_coef}
+Following \citet{beckmann.doscher_JPO97}, the latter is prescribed with a spatial dependence,
+\ie\ in the conditional form
+\begin{equation}
+  \label{eq:TRA_bbl_coef}
   A_l^\sigma (i,j,t) =
       \begin{cases}
 …
 where $A_{bbl}$ is the BBL diffusivity coefficient, given by the namelist parameter \np{rn\_ahtbbl} and
 usually set to a value much larger than the one used for lateral mixing in the open ocean.
 The constraint in \autoref{eq:tra_bbl_coef} implies that sigma-like diffusion only occurs when
+The constraint in \autoref{eq:TRA_bbl_coef} implies that sigma-like diffusion only occurs when
 the density above the sea floor, at the top of the slope, is larger than in the deeper ocean
 (see green arrow in \autoref{fig:bbl}).
+(see green arrow in \autoref{fig:TRA_bbl}).
 In practice, this constraint is applied separately in the two horizontal directions,
 and the density gradient in \autoref{eq:tra_bbl_coef} is evaluated with the log gradient formulation:
+and the density gradient in \autoref{eq:TRA_bbl_coef} is evaluated with the log gradient formulation:
 \[
   % \label{eq:tra_bbl_Drho}
+  % \label{eq:TRA_bbl_Drho}
   \nabla_\sigma \rho / \rho = \alpha \, \nabla_\sigma T + \beta \, \nabla_\sigma S
 \]
 …
 %        Advective BBL
 % -------------------------------------------------------------------------------------------------------------
+\subsection{Advective bottom boundary layer  (\protect\np{nn\_bbl\_adv}~\forcode{= 1..2})}
+\subsection[Advective bottom boundary layer (\forcode{nn_bbl_adv=[12]})]
+{Advective bottom boundary layer (\protect\np{nn\_bbl\_adv}\forcode{=[12]})}
 \label{subsec:TRA_bbl_adv}
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
   \begin{center}
     \includegraphics[]{Fig_BBL_adv}
     \caption{
       \protect\label{fig:bbl}
       Advective/diffusive Bottom Boundary Layer.
       The BBL parameterisation is activated when $\rho^i_{kup}$ is larger than $\rho^{i + 1}_{kdnw}$.
       Red arrows indicate the additional overturning circulation due to the advective BBL.
       The transport of the downslope flow is defined either as the transport of the bottom ocean cell (black arrow),
       or as a function of the along slope density gradient.
       The green arrow indicates the diffusive BBL flux directly connecting $kup$ and $kdwn$ ocean bottom cells.
+    }
   \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_BBL_adv}
+  \caption[Advective/diffusive bottom boundary layer]{
+    Advective/diffusive Bottom Boundary Layer.
+    The BBL parameterisation is activated when $\rho^i_{kup}$ is larger than $\rho^{i + 1}_{kdnw}$.
+    Red arrows indicate the additional overturning circulation due to the advective BBL.
+    The transport of the downslope flow is defined either
+    as the transport of the bottom ocean cell (black arrow),
+    or as a function of the along slope density gradient.
+    The green arrow indicates the diffusive BBL flux directly connecting
+    $kup$ and $kdwn$ ocean bottom cells.}
+  \label{fig:TRA_bbl}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 %%%gmcomment   :  this section has to be really written
 When applying an advective BBL (\np{nn\_bbl\_adv}~\forcode{= 1..2}), an overturning circulation is added which
+When applying an advective BBL (\np{nn\_bbl\_adv}\forcode{=1..2}), an overturning circulation is added which
 connects two adjacent bottom grid-points only if dense water overlies less dense water on the slope.
 The density difference causes dense water to move down the slope.
 \np{nn\_bbl\_adv}~\forcode{= 1}:
+\np{nn\_bbl\_adv}\forcode{=1}:
 the downslope velocity is chosen to be the Eulerian ocean velocity just above the topographic step
 (see black arrow in \autoref{fig:bbl}) \citep{Beckmann_Doscher1997}.
+(see black arrow in \autoref{fig:TRA_bbl}) \citep{beckmann.doscher_JPO97}.
 It is a \textit{conditional advection}, that is, advection is allowed only
 if dense water overlies less dense water on the slope (\ie $\nabla_\sigma \rho \cdot \nabla H < 0$) and
 if the velocity is directed towards greater depth (\ie $\vect U \cdot \nabla H > 0$).
 \np{nn\_bbl\_adv}~\forcode{= 2}:
+if dense water overlies less dense water on the slope (\ie\ $\nabla_\sigma \rho \cdot \nabla H < 0$) and
+if the velocity is directed towards greater depth (\ie\ $\vect U \cdot \nabla H > 0$).
+\np{nn\_bbl\_adv}\forcode{=2}:
 the downslope velocity is chosen to be proportional to $\Delta \rho$,
 the density difference between the higher cell and lower cell densities \citep{Campin_Goosse_Tel99}.
+the density difference between the higher cell and lower cell densities \citep{campin.goosse_T99}.
 The advection is allowed only  if dense water overlies less dense water on the slope
 (\ie $\nabla_\sigma \rho \cdot \nabla H < 0$).
 For example, the resulting transport of the downslope flow, here in the $i$-direction (\autoref{fig:bbl}),
+(\ie\ $\nabla_\sigma \rho \cdot \nabla H < 0$).
+For example, the resulting transport of the downslope flow, here in the $i$-direction (\autoref{fig:TRA_bbl}),
 is simply given by the following expression:
 \[
   % \label{eq:bbl_Utr}
+  % \label{eq:TRA_bbl_Utr}
   u^{tr}_{bbl} = \gamma g \frac{\Delta \rho}{\rho_o} e_{1u} \, min ({e_{3u}}_{kup},{e_{3u}}_{kdwn})
 \]
 …
 The parameter $\gamma$ should take a different value for each bathymetric step, but for simplicity,
 and because no direct estimation of this parameter is available, a uniform value has been assumed.
 The possible values for $\gamma$ range between 1 and $10~s$ \citep{Campin_Goosse_Tel99}.
+The possible values for $\gamma$ range between 1 and $10~s$ \citep{campin.goosse_T99}.
 Scalar properties are advected by this additional transport $(u^{tr}_{bbl},v^{tr}_{bbl})$ using the upwind scheme.
 …
 the surrounding water at intermediate depths.
 The entrainment is replaced by the vertical mixing implicit in the advection scheme.
 Let us consider as an example the case displayed in \autoref{fig:bbl} where
+Let us consider as an example the case displayed in \autoref{fig:TRA_bbl} where
 the density at level $(i,kup)$ is larger than the one at level $(i,kdwn)$.
 The advective BBL scheme modifies the tracer time tendency of the ocean cells near the topographic step by
 the downslope flow \autoref{eq:bbl_dw}, the horizontal \autoref{eq:bbl_hor} and
 the upward \autoref{eq:bbl_up} return flows as follows:
+the downslope flow \autoref{eq:TRA_bbl_dw}, the horizontal \autoref{eq:TRA_bbl_hor} and
+the upward \autoref{eq:TRA_bbl_up} return flows as follows:
 \begin{alignat}{3}
   \label{eq:bbl_dw}
+  \label{eq:TRA_bbl_dw}
   \partial_t T^{do}_{kdw} &\equiv \partial_t T^{do}_{kdw}
                                 &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{kdw}} &&\lt( T^{sh}_{kup} - T^{do}_{kdw} \rt) \\
   \label{eq:bbl_hor}
+  \label{eq:TRA_bbl_hor}
   \partial_t T^{sh}_{kup} &\equiv \partial_t T^{sh}_{kup}
                                 &&+ \frac{u^{tr}_{bbl}}{{b_t}^{sh}_{kup}} &&\lt( T^{do}_{kup} - T^{sh}_{kup} \rt) \\
 …
   \intertext{and for $k =kdw-1,\;..., \; kup$ :}
+  %
   \label{eq:bbl_up}
+  \label{eq:TRA_bbl_up}
   \partial_t T^{do}_{k} &\equiv \partial_t S^{do}_{k}
                                 &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{k}}   &&\lt( T^{do}_{k +1} - T^{sh}_{k}   \rt)
 …
 % Tracer damping
 % ================================================================
+\section{Tracer damping (\protect\mdl{tradmp})}
+\section[Tracer damping (\textit{tradmp.F90})]
+{Tracer damping (\protect\mdl{tradmp})}
 \label{sec:TRA_dmp}
 %--------------------------------------------namtra_dmp-------------------------------------------------
+\nlst{namtra_dmp}
+\begin{listing}
+  \nlst{namtra_dmp}
+  \caption{\texttt{namtra\_dmp}}
+  \label{lst:namtra_dmp}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------------
 In some applications it can be useful to add a Newtonian damping term into the temperature and salinity equations:
 \begin{equation}
   \label{eq:tra_dmp}
+  \label{eq:TRA_dmp}
   \begin{gathered}
     \pd[T]{t} = \cdots - \gamma (T - T_o) \\
     \pd[S]{t} = \cdots - \gamma (S - S_o)
   \end{gathered}
 \end{equation}
+\end{equation}
 where $\gamma$ is the inverse of a time scale, and $T_o$ and $S_o$ are given temperature and salinity fields
 (usually a climatology).
 Options are defined through the  \ngn{namtra\_dmp} namelist variables.
+Options are defined through the  \nam{tra\_dmp} namelist variables.
 The restoring term is added when the namelist parameter \np{ln\_tradmp} is set to true.
 It also requires that both \np{ln\_tsd\_init} and \np{ln\_tsd\_tradmp} are set to true in
 \ngn{namtsd} namelist as well as \np{sn\_tem} and \np{sn\_sal} structures are correctly set
 (\ie that $T_o$ and $S_o$ are provided in input files and read using \mdl{fldread},
+It also requires that both \np{ln\_tsd\_init} and \np{ln\_tsd\_dmp} are set to true in
+\nam{tsd} namelist as well as \np{sn\_tem} and \np{sn\_sal} structures are correctly set
+(\ie\ that $T_o$ and $S_o$ are provided in input files and read using \mdl{fldread},
 see \autoref{subsec:SBC_fldread}).
 The restoring coefficient $\gamma$ is a three-dimensional array read in during the \rou{tra\_dmp\_init} routine.
 …
 The DMP\_TOOLS tool is provided to allow users to generate the netcdf file.
 The two main cases in which \autoref{eq:tra_dmp} is used are
+The two main cases in which \autoref{eq:TRA_dmp} is used are
 \textit{(a)} the specification of the boundary conditions along artificial walls of a limited domain basin and
 \textit{(b)} the computation of the velocity field associated with a given $T$-$S$ field
 …
 In the vicinity of these walls, $\gamma$ takes large values (equivalent to a time scale of a few days) whereas
 it is zero in the interior of the model domain.
 The second case corresponds to the use of the robust diagnostic method \citep{Sarmiento1982}.
+The second case corresponds to the use of the robust diagnostic method \citep{sarmiento.bryan_JGR82}.
 It allows us to find the velocity field consistent with the model dynamics whilst
 having a $T$, $S$ field close to a given climatological field ($T_o$, $S_o$).
 …
 only below the mixed layer (defined either on a density or $S_o$ criterion).
 It is common to set the damping to zero in the mixed layer as the adjustment time scale is short here
 \citep{Madec_al_JPO96}.
+\citep{madec.delecluse.ea_JPO96}.
 For generating \ifile{resto}, see the documentation for the DMP tool provided with the source code under
 …
 % Tracer time evolution
 % ================================================================
+\section{Tracer time evolution (\protect\mdl{tranxt})}
+\section[Tracer time evolution (\textit{tranxt.F90})]
+{Tracer time evolution (\protect\mdl{tranxt})}
 \label{sec:TRA_nxt}
 %--------------------------------------------namdom-----------------------------------------------------
-\nlst{namdom}
 %--------------------------------------------------------------------------------------------------------------
 Options are defined through the \ngn{namdom} namelist variables.
 The general framework for tracer time stepping is a modified leap-frog scheme \citep{Leclair_Madec_OM09},
 \ie a three level centred time scheme associated with a Asselin time filter (cf. \autoref{sec:STP_mLF}):
 \begin{equation}
   \label{eq:tra_nxt}
+Options are defined through the \nam{dom} namelist variables.
+The general framework for tracer time stepping is a modified leap-frog scheme \citep{leclair.madec_OM09},
+\ie\ a three level centred time scheme associated with a Asselin time filter (cf. \autoref{sec:TD_mLF}):
+\begin{equation}
+  \label{eq:TRA_nxt}
   \begin{alignedat}{3}
     &(e_{3t}T)^{t + \rdt} &&= (e_{3t}T)_f^{t - \rdt} &&+ 2 \, \rdt \,e_{3t}^t \ \text{RHS}^t \\
     &(e_{3t}T)_f^t        &&= (e_{3t}T)^t            &&+ \, \gamma \, \lt[ (e_{3t}T)_f^{t - \rdt} - 2(e_{3t}T)^t + (e_{3t}T)^{t + \rdt} \rt] \\
     &                     &&                         &&- \, \gamma \, \rdt \, \lt[ Q^{t + \rdt/2} - Q^{t - \rdt/2} \rt]
+    &                     &&                         &&- \, \gamma \, \rdt \, \lt[ Q^{t + \rdt/2} - Q^{t - \rdt/2} \rt]
   \end{alignedat}
 \end{equation}
+\end{equation}
 where RHS is the right hand side of the temperature equation, the subscript $f$ denotes filtered values,
 $\gamma$ is the Asselin coefficient, and $S$ is the total forcing applied on $T$
 (\ie fluxes plus content in mass exchanges).
+(\ie\ fluxes plus content in mass exchanges).
 $\gamma$ is initialized as \np{rn\_atfp} (\textbf{namelist} parameter).
 Its default value is \np{rn\_atfp}~\forcode{= 10.e-3}.
+Its default value is \np{rn\_atfp}\forcode{=10.e-3}.
 Note that the forcing correction term in the filter is not applied in linear free surface
 (\jp{lk\_vvl}~\forcode{= .false.}) (see \autoref{subsec:TRA_sbc}).
+(\jp{ln\_linssh}\forcode{=.true.}) (see \autoref{subsec:TRA_sbc}).
 Not also that in constant volume case, the time stepping is performed on $T$, not on its content, $e_{3t}T$.
 …
 % ================================================================
+% Equation of State (eosbn2)
+% ================================================================
+\section{Equation of state (\protect\mdl{eosbn2}) }
+% Equation of State (eosbn2)
+% ================================================================
+\section[Equation of state (\textit{eosbn2.F90})]
+{Equation of state (\protect\mdl{eosbn2})}
 \label{sec:TRA_eosbn2}
 %--------------------------------------------nameos-----------------------------------------------------
+\nlst{nameos}
+\begin{listing}
+  \nlst{nameos}
+  \caption{\texttt{nameos}}
+  \label{lst:nameos}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------------
 …
 %        Equation of State
 % -------------------------------------------------------------------------------------------------------------
+\subsection{Equation of seawater (\protect\np{nn\_eos}~\forcode{= -1..1})}
+\subsection[Equation of seawater (\texttt{ln}\{\texttt{\_teso10,\_eos80,\_seos}\})]
+{Equation of seawater (\protect\np{ln\_teos10}, \protect\np{ln\_teos80}, or \protect\np{ln\_seos}) }
 \label{subsec:TRA_eos}
 The Equation Of Seawater (EOS) is an empirical nonlinear thermodynamic relationship linking seawater density,
 …
 Nonlinearities of the EOS are of major importance, in particular influencing the circulation through
 determination of the static stability below the mixed layer,
 thus controlling rates of exchange between the atmosphere and the ocean interior \citep{Roquet_JPO2015}.
 Therefore an accurate EOS based on either the 1980 equation of state (EOS-80, \cite{UNESCO1983}) or
 TEOS-10 \citep{TEOS10} standards should be used anytime a simulation of the real ocean circulation is attempted
 \citep{Roquet_JPO2015}.
+thus controlling rates of exchange between the atmosphere and the ocean interior \citep{roquet.madec.ea_JPO15}.
+Therefore an accurate EOS based on either the 1980 equation of state (EOS-80, \cite{fofonoff.millard_bk83}) or
+TEOS-10 \citep{ioc.iapso_bk10} standards should be used anytime a simulation of the real ocean circulation is attempted
+\citep{roquet.madec.ea_JPO15}.
 The use of TEOS-10 is highly recommended because
 \textit{(i)}   it is the new official EOS,
 \textit{(ii)}  it is more accurate, being based on an updated database of laboratory measurements, and
 \textit{(iii)} it uses Conservative Temperature and Absolute Salinity (instead of potential temperature and
 practical salinity for EOS-980, both variables being more suitable for use as model variables
 \citep{TEOS10, Graham_McDougall_JPO13}.
 EOS-80 is an obsolescent feature of the NEMO system, kept only for backward compatibility.
+practical salinity for EOS-80, both variables being more suitable for use as model variables
+\citep{ioc.iapso_bk10, graham.mcdougall_JPO13}.
+EOS-80 is an obsolescent feature of the \NEMO\ system, kept only for backward compatibility.
 For process studies, it is often convenient to use an approximation of the EOS.
 To that purposed, a simplified EOS (S-EOS) inspired by \citet{Vallis06} is also available.
+To that purposed, a simplified EOS (S-EOS) inspired by \citet{vallis_bk06} is also available.
 In the computer code, a density anomaly, $d_a = \rho / \rho_o - 1$, is computed, with $\rho_o$ a reference density.
 …
 This is a sensible choice for the reference density used in a Boussinesq ocean climate model, as,
 with the exception of only a small percentage of the ocean,
+density in the World Ocean varies by no more than 2$\%$ from that value \citep{Gill1982}.
+Options are defined through the \ngn{nameos} namelist variables, and in particular \np{nn\_eos} which
+controls the EOS used (\forcode{= -1} for TEOS10 ; \forcode{= 0} for EOS-80 ; \forcode{= 1} for S-EOS).
+density in the World Ocean varies by no more than 2$\%$ from that value \citep{gill_bk82}.
+Options which control the EOS used are defined through the \nam{eos} namelist variables.
 \begin{description}
 \item[\np{nn\_eos}~\forcode{= -1}]
   the polyTEOS10-bsq equation of seawater \citep{Roquet_OM2015} is used.
+\item[\np{ln\_teos10}\forcode{=.true.}]
+  the polyTEOS10-bsq equation of seawater \citep{roquet.madec.ea_OM15} is used.
   The accuracy of this approximation is comparable to the TEOS-10 rational function approximation,
   but it is optimized for a boussinesq fluid and the polynomial expressions have simpler and
 …
   use in ocean models.
   Note that a slightly higher precision polynomial form is now used replacement of
   the TEOS-10 rational function approximation for hydrographic data analysis \citep{TEOS10}.
+  the TEOS-10 rational function approximation for hydrographic data analysis \citep{ioc.iapso_bk10}.
   A key point is that conservative state variables are used:
   Absolute Salinity (unit: g/kg, notation: $S_A$) and Conservative Temperature (unit: \deg{C}, notation: $\Theta$).
   The pressure in decibars is approximated by the depth in meters.
   With TEOS10, the specific heat capacity of sea water, $C_p$, is a constant.
   It is set to $C_p = 3991.86795711963~J\,Kg^{-1}\,^{\circ}K^{-1}$, according to \citet{TEOS10}.
+  It is set to $C_p = 3991.86795711963~J\,Kg^{-1}\,^{\circ}K^{-1}$, according to \citet{ioc.iapso_bk10}.
   Choosing polyTEOS10-bsq implies that the state variables used by the model are $\Theta$ and $S_A$.
   In particular, the initial state deined by the user have to be given as \textit{Conservative} Temperature and
   \textit{Absolute} Salinity.
   In addition, setting \np{ln\_useCT} to \forcode{.true.} convert the Conservative SST to potential SST prior to
+  In addition, when using TEOS10, the Conservative SST is converted to potential SST prior to
   either computing the air-sea and ice-sea fluxes (forced mode) or
   sending the SST field to the atmosphere (coupled mode).
 \item[\np{nn\_eos}~\forcode{= 0}]
+\item[\np{ln\_eos80}\forcode{=.true.}]
   the polyEOS80-bsq equation of seawater is used.
   It takes the same polynomial form as the polyTEOS10, but the coefficients have been optimized to
 …
   The pressure in decibars is approximated by the depth in meters.
   With thsi EOS, the specific heat capacity of sea water, $C_p$, is a function of temperature, salinity and
   pressure \citep{UNESCO1983}.
+  pressure \citep{fofonoff.millard_bk83}.
   Nevertheless, a severe assumption is made in order to have a heat content ($C_p T_p$) which
   is conserved by the model: $C_p$ is set to a constant value, the TEOS10 value.
 \item[\np{nn\_eos}~\forcode{= 1}]
   a simplified EOS (S-EOS) inspired by \citet{Vallis06} is chosen,
+\item[\np{ln\_seos}\forcode{=.true.}]
+  a simplified EOS (S-EOS) inspired by \citet{vallis_bk06} is chosen,
   the coefficients of which has been optimized to fit the behavior of TEOS10
   (Roquet, personal comm.) (see also \citet{Roquet_JPO2015}).
+  (Roquet, personal comm.) (see also \citet{roquet.madec.ea_JPO15}).
   It provides a simplistic linear representation of both cabbeling and thermobaricity effects which
   is enough for a proper treatment of the EOS in theoretical studies \citep{Roquet_JPO2015}.
+  is enough for a proper treatment of the EOS in theoretical studies \citep{roquet.madec.ea_JPO15}.
   With such an equation of state there is no longer a distinction between
   \textit{conservative} and \textit{potential} temperature,
   as well as between \textit{absolute} and \textit{practical} salinity.
   S-EOS takes the following expression:
   \begin{gather*}
     % \label{eq:tra_S-EOS}
+    % \label{eq:TRA_S-EOS}
     \begin{alignedat}{2}
     &d_a(T,S,z) = \frac{1}{\rho_o} \big[ &- a_0 \; ( 1 + 0.5 \; \lambda_1 \; T_a + \mu_1 \; z ) * &T_a \big. \\
     &                                    &+ b_0 \; ( 1 - 0.5 \; \lambda_2 \; S_a - \mu_2 \; z ) * &S_a       \\
+    &                                    &+ b_0 \; ( 1 - 0.5 \; \lambda_2 \; S_a - \mu_2 \; z ) * &S_a       \\
     &                              \big. &- \nu \;                           T_a                  &S_a \big] \\
     \end{alignedat}
 …
     \text{with~} T_a = T - 10 \, ; \, S_a = S - 35 \, ; \, \rho_o = 1026~Kg/m^3
   \end{gather*}
   where the computer name of the coefficients as well as their standard value are given in \autoref{tab:SEOS}.
+  where the computer name of the coefficients as well as their standard value are given in \autoref{tab:TRA_SEOS}.
   In fact, when choosing S-EOS, various approximation of EOS can be specified simply by
   changing the associated coefficients.
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{table}[!tb]
+  \begin{center}
+    \begin{tabular}{|l|l|l|l|}
+      \hline
+      coeff.      & computer name   & S-EOS           & description                      \\
+      \hline
+      $a_0$       & \np{rn\_a0}     & $1.6550~10^{-1}$ & linear thermal expansion coeff. \\
+      \hline
+      $b_0$       & \np{rn\_b0}     & $7.6554~10^{-1}$ & linear haline  expansion coeff. \\
+      \hline
+      $\lambda_1$ & \np{rn\_lambda1}& $5.9520~10^{-2}$ & cabbeling coeff. in $T^2$       \\
+      \hline
+      $\lambda_2$ & \np{rn\_lambda2}& $5.4914~10^{-4}$ & cabbeling coeff. in $S^2$       \\
+      \hline
+      $\nu$       & \np{rn\_nu}     & $2.4341~10^{-3}$ & cabbeling coeff. in $T \, S$    \\
+      \hline
+      $\mu_1$     & \np{rn\_mu1}    & $1.4970~10^{-4}$ & thermobaric coeff. in T         \\
+      \hline
+      $\mu_2$     & \np{rn\_mu2}    & $1.1090~10^{-5}$ & thermobaric coeff. in S         \\
+      \hline
+    \end{tabular}
+    \caption{
+      \protect\label{tab:SEOS}
+      Standard value of S-EOS coefficients.
+    }
+\end{center}
+  \centering
+  \begin{tabular}{|l|l|l|l|}
+    \hline
+    coeff.     & computer name   & S-EOS           & description                      \\
+    \hline
+    $a_0$       & \np{rn\_a0}     & $1.6550~10^{-1}$ & linear thermal expansion coeff. \\
+    \hline
+    $b_0$         & \np{rn\_b0}     & $7.6554~10^{-1}$ & linear haline  expansion coeff. \\
+    \hline
+    $\lambda_1$   & \np{rn\_lambda1}& $5.9520~10^{-2}$ & cabbeling coeff. in $T^2$       \\
+    \hline
+    $\lambda_2$   & \np{rn\_lambda2}& $5.4914~10^{-4}$ & cabbeling coeff. in $S^2$       \\
+    \hline
+    $\nu$       & \np{rn\_nu}     & $2.4341~10^{-3}$ & cabbeling coeff. in $T \, S$      \\
+    \hline
+    $\mu_1$     & \np{rn\_mu1}   & $1.4970~10^{-4}$ & thermobaric coeff. in T         \\
+    \hline
+    $\mu_2$     & \np{rn\_mu2}   & $1.1090~10^{-5}$ & thermobaric coeff. in S         \\
+    \hline
+  \end{tabular}
+  \caption{Standard value of S-EOS coefficients}
+  \label{tab:TRA_SEOS}
 \end{table}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 %        Brunt-V\"{a}is\"{a}l\"{a} Frequency
 % -------------------------------------------------------------------------------------------------------------
+\subsection{Brunt-V\"{a}is\"{a}l\"{a} frequency (\protect\np{nn\_eos}~\forcode{= 0..2})}
+\subsection[Brunt-V\"{a}is\"{a}l\"{a} frequency]
+{Brunt-V\"{a}is\"{a}l\"{a} frequency}
 \label{subsec:TRA_bn2}
 …
 In particular, $N^2$ has to be computed at the local pressure
 (pressure in decibar being approximated by the depth in meters).
 The expression for $N^2$  is given by:
+The expression for $N^2$  is given by:
 \[
   % \label{eq:tra_bn2}
+  % \label{eq:TRA_bn2}
   N^2 = \frac{g}{e_{3w}} \lt( \beta \; \delta_{k + 1/2}[S] - \alpha \; \delta_{k + 1/2}[T] \rt)
 \]
 …
 The coefficients are a polynomial function of temperature, salinity and depth which expression depends on
 the chosen EOS.
 They are computed through \textit{eos\_rab}, a \fortran function that can be found in \mdl{eosbn2}.
+They are computed through \textit{eos\_rab}, a \fortran\ function that can be found in \mdl{eosbn2}.
 % -------------------------------------------------------------------------------------------------------------
 …
 \label{subsec:TRA_fzp}
 The freezing point of seawater is a function of salinity and pressure \citep{UNESCO1983}:
 \begin{equation}
   \label{eq:tra_eos_fzp}
+The freezing point of seawater is a function of salinity and pressure \citep{fofonoff.millard_bk83}:
+\begin{equation}
+  \label{eq:TRA_eos_fzp}
   \begin{split}
     &T_f (S,p) = \lt( a + b \, \sqrt{S} + c \, S \rt) \, S + d \, p \\
     &\text{where~} a = -0.0575, \, b = 1.710523~10^{-3}, \, c = -2.154996~10^{-4} \\
+    &\text{where~} a = -0.0575, \, b = 1.710523~10^{-3}, \, c = -2.154996~10^{-4} \\
     &\text{and~} d = -7.53~10^{-3}
     \end{split}
 \end{equation}
 \autoref{eq:tra_eos_fzp} is only used to compute the potential freezing point of sea water
 (\ie referenced to the surface $p = 0$),
 thus the pressure dependent terms in \autoref{eq:tra_eos_fzp} (last term) have been dropped.
+\autoref{eq:TRA_eos_fzp} is only used to compute the potential freezing point of sea water
+(\ie\ referenced to the surface $p = 0$),
+thus the pressure dependent terms in \autoref{eq:TRA_eos_fzp} (last term) have been dropped.
 The freezing point is computed through \textit{eos\_fzp},
 a \fortran function that can be found in \mdl{eosbn2}.
 % -------------------------------------------------------------------------------------------------------------
 %        Potential Energy
+a \fortran\ function that can be found in \mdl{eosbn2}.
+% -------------------------------------------------------------------------------------------------------------
+%        Potential Energy
 % -------------------------------------------------------------------------------------------------------------
 %\subsection{Potential Energy anomalies}
 …
 % ================================================================
+% Horizontal Derivative in zps-coordinate
+% ================================================================
+\section{Horizontal derivative in \textit{zps}-coordinate (\protect\mdl{zpshde})}
+% Horizontal Derivative in zps-coordinate
+% ================================================================
+\section[Horizontal derivative in \textit{zps}-coordinate (\textit{zpshde.F90})]
+{Horizontal derivative in \textit{zps}-coordinate (\protect\mdl{zpshde})}
 \label{sec:TRA_zpshde}
 \gmcomment{STEVEN: to be consistent with earlier discussion of differencing and averaging operators,
+\gmcomment{STEVEN: to be consistent with earlier discussion of differencing and averaging operators,
 I've changed "derivative" to "difference" and "mean" to "average"}
 With partial cells (\np{ln\_zps}~\forcode{= .true.}) at bottom and top (\np{ln\_isfcav}~\forcode{= .true.}),
+With partial cells (\np{ln\_zps}\forcode{=.true.}) at bottom and top (\np{ln\_isfcav}\forcode{=.true.}),
 in general, tracers in horizontally adjacent cells live at different depths.
 Horizontal gradients of tracers are needed for horizontal diffusion (\mdl{traldf} module) and
 the hydrostatic pressure gradient calculations (\mdl{dynhpg} module).
 The partial cell properties at the top (\np{ln\_isfcav}~\forcode{= .true.}) are computed in the same way as
+The partial cell properties at the top (\np{ln\_isfcav}\forcode{=.true.}) are computed in the same way as
 for the bottom.
 So, only the bottom interpolation is explained below.
 …
 Before taking horizontal gradients between the tracers next to the bottom,
 a linear interpolation in the vertical is used to approximate the deeper tracer as if
 it actually lived at the depth of the shallower tracer point (\autoref{fig:Partial_step_scheme}).
+it actually lived at the depth of the shallower tracer point (\autoref{fig:TRA_Partial_step_scheme}).
 For example, for temperature in the $i$-direction the needed interpolated temperature, $\widetilde T$, is:
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!p]
+  \begin{center}
+    \includegraphics[]{Fig_partial_step_scheme}
+    \caption{
+      \protect\label{fig:Partial_step_scheme}
+      Discretisation of the horizontal difference and average of tracers in the $z$-partial step coordinate
+      (\protect\np{ln\_zps}~\forcode{= .true.}) in the case $(e3w_k^{i + 1} - e3w_k^i) > 0$.
+      A linear interpolation is used to estimate $\widetilde T_k^{i + 1}$,
+      the tracer value at the depth of the shallower tracer point of the two adjacent bottom $T$-points.
+      The horizontal difference is then given by: $\delta_{i + 1/2} T_k = \widetilde T_k^{\, i + 1} -T_k^{\, i}$ and
+      the average by: $\overline T_k^{\, i + 1/2} = (\widetilde T_k^{\, i + 1/2} - T_k^{\, i}) / 2$.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_partial_step_scheme}
+  \caption[Discretisation of the horizontal difference and average of tracers in
+  the $z$-partial step coordinate]{
+    Discretisation of the horizontal difference and average of tracers in
+    the $z$-partial step coordinate (\protect\np{ln\_zps}\forcode{=.true.}) in
+    the case $(e3w_k^{i + 1} - e3w_k^i) > 0$.
+    A linear interpolation is used to estimate $\widetilde T_k^{i + 1}$,
+    the tracer value at the depth of the shallower tracer point of
+    the two adjacent bottom $T$-points.
+    The horizontal difference is then given by:
+    $\delta_{i + 1/2} T_k = \widetilde T_k^{\, i + 1} -T_k^{\, i}$ and
+    the average by:
+    $\overline T_k^{\, i + 1/2} = (\widetilde T_k^{\, i + 1/2} - T_k^{\, i}) / 2$.}
+  \label{fig:TRA_Partial_step_scheme}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
   \rt.
 \]
 and the resulting forms for the horizontal difference and the horizontal average value of $T$ at a $U$-point are:
 \begin{equation}
   \label{eq:zps_hde}
+and the resulting forms for the horizontal difference and the horizontal average value of $T$ at a $U$-point are:
+\begin{equation}
+  \label{eq:TRA_zps_hde}
   \begin{split}
     \delta_{i + 1/2} T       &=
 …
 Instead of forming a linear approximation of density, we compute $\widetilde \rho$ from the interpolated values of
 $T$ and $S$, and the pressure at a $u$-point
 (in the equation of state pressure is approximated by depth, see \autoref{subsec:TRA_eos}):
+(in the equation of state pressure is approximated by depth, see \autoref{subsec:TRA_eos}):
 \[
   % \label{eq:zps_hde_rho}
+  % \label{eq:TRA_zps_hde_rho}
   \widetilde \rho = \rho (\widetilde T,\widetilde S,z_u) \quad \text{where~} z_u = \min \lt( z_T^{i + 1},z_T^i \rt)
 \]
 …
 Note that in almost all the advection schemes presented in this Chapter,
 both averaging and differencing operators appear.
 Yet \autoref{eq:zps_hde} has not been used in these schemes:
+Yet \autoref{eq:TRA_zps_hde} has not been used in these schemes:
 in contrast to diffusion and pressure gradient computations,
 no correction for partial steps is applied for advection.

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_ZDF.tex

-                      r10442
+                      r11564
 \documentclass[../main/NEMO_manual]{subfiles}
+%% Custom aliases
+\newcommand{\cf}{\ensuremath{C\kern-0.14em f}}
 \begin{document}
 …
 \label{chap:ZDF}
 \minitoc
+\chaptertoc
 %gm% Add here a small introduction to ZDF and naming of the different physics (similar to what have been written for TRA and DYN.
 …
 % ================================================================
 \section{Vertical mixing}
 \label{sec:ZDF_zdf}
+\label{sec:ZDF}
 The discrete form of the ocean subgrid scale physics has been presented in
 …
 At the surface they are prescribed from the surface forcing (see \autoref{chap:SBC}),
 while at the bottom they are set to zero for heat and salt,
 unless a geothermal flux forcing is prescribed as a bottom boundary condition (\ie \key{trabbl} defined,
+unless a geothermal flux forcing is prescribed as a bottom boundary condition (\ie\ \np{ln\_trabbc} defined,
 see \autoref{subsec:TRA_bbc}), and specified through a bottom friction parameterisation for momentum
 (see \autoref{sec:ZDF_bfr}).
+(see \autoref{sec:ZDF_drg}).
 In this section we briefly discuss the various choices offered to compute the vertical eddy viscosity and
 …
 respectively (see \autoref{sec:TRA_zdf} and \autoref{sec:DYN_zdf}).
 These coefficients can be assumed to be either constant, or a function of the local Richardson number,
 or computed from a turbulent closure model (either TKE or GLS formulation).
 The computation of these coefficients is initialized in the \mdl{zdfini} module and performed in
 the \mdl{zdfric}, \mdl{zdftke} or \mdl{zdfgls} modules.
+or computed from a turbulent closure model (either TKE or GLS or OSMOSIS formulation).
+The computation of these coefficients is initialized in the \mdl{zdfphy} module and performed in
+the \mdl{zdfric}, \mdl{zdftke} or \mdl{zdfgls} or \mdl{zdfosm} modules.
 The trends due to the vertical momentum and tracer diffusion, including the surface forcing,
+are computed and added to the general trend in the \mdl{dynzdf} and \mdl{trazdf} modules, respectively.
+These trends can be computed using either a forward time stepping scheme
+(namelist parameter \np{ln\_zdfexp}\forcode{ = .true.}) or a backward time stepping scheme
+(\np{ln\_zdfexp}\forcode{ = .false.}) depending on the magnitude of the mixing coefficients,
+and thus of the formulation used (see \autoref{chap:STP}).
+% -------------------------------------------------------------------------------------------------------------
+%        Constant
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Constant (\protect\key{zdfcst})}
+are computed and added to the general trend in the \mdl{dynzdf} and \mdl{trazdf} modules, respectively.
+%These trends can be computed using either a forward time stepping scheme
+%(namelist parameter \np{ln\_zdfexp}\forcode{=.true.}) or a backward time stepping scheme
+%(\np{ln\_zdfexp}\forcode{=.false.}) depending on the magnitude of the mixing coefficients,
+%and thus of the formulation used (see \autoref{chap:TD}).
+%--------------------------------------------namzdf--------------------------------------------------------
+\begin{listing}
+  \nlst{namzdf}
+  \caption{\texttt{namzdf}}
+  \label{lst:namzdf}
+\end{listing}
+%--------------------------------------------------------------------------------------------------------------
+% -------------------------------------------------------------------------------------------------------------
+%        Constant
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Constant (\forcode{ln_zdfcst=.true.})]
+{Constant (\protect\np{ln\_zdfcst}\forcode{=.true.})}
 \label{subsec:ZDF_cst}
+%--------------------------------------------namzdf---------------------------------------------------------
+\nlst{namzdf}
+%--------------------------------------------------------------------------------------------------------------
+Options are defined through the \ngn{namzdf} namelist variables.
+When \key{zdfcst} is defined, the momentum and tracer vertical eddy coefficients are set to
+Options are defined through the \nam{zdf} namelist variables.
+When \np{ln\_zdfcst} is defined, the momentum and tracer vertical eddy coefficients are set to
 constant values over the whole ocean.
 This is the crudest way to define the vertical ocean physics.
 It is recommended that this option is only used in process studies, not in basin scale simulations.
+It is recommended to use this option only in process studies, not in basin scale simulations.
 Typical values used in this case are:
 \begin{align*}
 …
 \end{align*}
 These values are set through the \np{rn\_avm0} and \np{rn\_avt0} namelist parameters.
+These values are set through the \np{rn\_avm0} and \np{rn\_avt0} namelist parameters.
 In all cases, do not use values smaller that those associated with the molecular viscosity and diffusivity,
 that is $\sim10^{-6}~m^2.s^{-1}$ for momentum, $\sim10^{-7}~m^2.s^{-1}$ for temperature and
 …
 %        Richardson Number Dependent
 % -------------------------------------------------------------------------------------------------------------
+\subsection{Richardson number dependent (\protect\key{zdfric})}
+\subsection[Richardson number dependent (\forcode{ln_zdfric=.true.})]
+{Richardson number dependent (\protect\np{ln\_zdfric}\forcode{=.true.})}
 \label{subsec:ZDF_ric}
 %--------------------------------------------namric---------------------------------------------------------
+\nlst{namzdf_ric}
+\begin{listing}
+  \nlst{namzdf_ric}
+  \caption{\texttt{namzdf\_ric}}
+  \label{lst:namzdf_ric}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------------
 When \key{zdfric} is defined, a local Richardson number dependent formulation for the vertical momentum and
 tracer eddy coefficients is set through the \ngn{namzdf\_ric} namelist variables.
 The vertical mixing coefficients are diagnosed from the large scale variables computed by the model.
+When \np{ln\_zdfric}\forcode{=.true.}, a local Richardson number dependent formulation for the vertical momentum and
+tracer eddy coefficients is set through the \nam{zdf\_ric} namelist variables.
+The vertical mixing coefficients are diagnosed from the large scale variables computed by the model.
 \textit{In situ} measurements have been used to link vertical turbulent activity to large scale ocean structures.
 The hypothesis of a mixing mainly maintained by the growth of Kelvin-Helmholtz like instabilities leads to
 a dependency between the vertical eddy coefficients and the local Richardson number
 (\ie the ratio of stratification to vertical shear).
 Following \citet{Pacanowski_Philander_JPO81}, the following formulation has been implemented:
 \[
   % \label{eq:zdfric}
+(\ie\ the ratio of stratification to vertical shear).
+Following \citet{pacanowski.philander_JPO81}, the following formulation has been implemented:
+\[
+  % \label{eq:ZDF_ric}
   \left\{
     \begin{aligned}
 …
 \]
 where $Ri = N^2 / \left(\partial_z \textbf{U}_h \right)^2$ is the local Richardson number,
 $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}),
+$N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}),
 $A_b^{vT} $ and $A_b^{vm}$ are the constant background values set as in the constant case
 (see \autoref{subsec:ZDF_cst}), and $A_{ric}^{vT} = 10^{-4}~m^2.s^{-1}$ is the maximum value that
 …
 A simple mixing-layer model to transfer and dissipate the atmospheric forcings
 (wind-stress and buoyancy fluxes) can be activated setting the \np{ln\_mldw}\forcode{ = .true.} in the namelist.
+(wind-stress and buoyancy fluxes) can be activated setting the \np{ln\_mldw}\forcode{=.true.} in the namelist.
 In this case, the local depth of turbulent wind-mixing or "Ekman depth" $h_{e}(x,y,t)$ is evaluated and
 …
 The final $h_{e}$ is further constrained by the adjustable bounds \np{rn\_mldmin} and \np{rn\_mldmax}.
 Once $h_{e}$ is computed, the vertical eddy coefficients within $h_{e}$ are set to
+the empirical values \np{rn\_wtmix} and \np{rn\_wvmix} \citep{Lermusiaux2001}.
+% -------------------------------------------------------------------------------------------------------------
+%        TKE Turbulent Closure Scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection{TKE turbulent closure scheme (\protect\key{zdftke})}
+the empirical values \np{rn\_wtmix} and \np{rn\_wvmix} \citep{lermusiaux_JMS01}.
+% -------------------------------------------------------------------------------------------------------------
+%        TKE Turbulent Closure Scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection[TKE turbulent closure scheme (\forcode{ln_zdftke=.true.})]
+{TKE turbulent closure scheme (\protect\np{ln\_zdftke}\forcode{=.true.})}
 \label{subsec:ZDF_tke}
 %--------------------------------------------namzdf_tke--------------------------------------------------
+\nlst{namzdf_tke}
+\begin{listing}
+  \nlst{namzdf_tke}
+  \caption{\texttt{namzdf\_tke}}
+  \label{lst:namzdf_tke}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------------
 …
 a prognostic equation for $\bar{e}$, the turbulent kinetic energy,
 and a closure assumption for the turbulent length scales.
 This turbulent closure model has been developed by \citet{Bougeault1989} in the atmospheric case,
 adapted by \citet{Gaspar1990} for the oceanic case, and embedded in OPA, the ancestor of NEMO,
 by \citet{Blanke1993} for equatorial Atlantic simulations.
 Since then, significant modifications have been introduced by \citet{Madec1998} in both the implementation and
+This turbulent closure model has been developed by \citet{bougeault.lacarrere_MWR89} in the atmospheric case,
+adapted by \citet{gaspar.gregoris.ea_JGR90} for the oceanic case, and embedded in OPA, the ancestor of \NEMO,
+by \citet{blanke.delecluse_JPO93} for equatorial Atlantic simulations.
+Since then, significant modifications have been introduced by \citet{madec.delecluse.ea_NPM98} in both the implementation and
 the formulation of the mixing length scale.
 The time evolution of $\bar{e}$ is the result of the production of $\bar{e}$ through vertical shear,
 its destruction through stratification, its vertical diffusion, and its dissipation of \citet{Kolmogorov1942} type:
+its destruction through stratification, its vertical diffusion, and its dissipation of \citet{kolmogorov_IANS42} type:
 \begin{equation}
   \label{eq:zdftke_e}
+  \label{eq:ZDF_tke_e}
   \frac{\partial \bar{e}}{\partial t} =
   \frac{K_m}{{e_3}^2 }\;\left[ {\left( {\frac{\partial u}{\partial k}} \right)^2
 …
 \end{equation}
 \[
   % \label{eq:zdftke_kz}
+  % \label{eq:ZDF_tke_kz}
   \begin{split}
     K_m &= C_k\  l_k\  \sqrt {\bar{e}\; }    \\
 …
   \end{split}
 \]
 where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}),
 $l_{\epsilon }$ and $l_{\kappa }$ are the dissipation and mixing length scales,
+where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}),
+$l_{\epsilon }$ and $l_{\kappa }$ are the dissipation and mixing length scales,
 $P_{rt}$ is the Prandtl number, $K_m$ and $K_\rho$ are the vertical eddy viscosity and diffusivity coefficients.
 The constants $C_k =  0.1$ and $C_\epsilon = \sqrt {2} /2$ $\approx 0.7$ are designed to deal with
 vertical mixing at any depth \citep{Gaspar1990}.
+vertical mixing at any depth \citep{gaspar.gregoris.ea_JGR90}.
 They are set through namelist parameters \np{nn\_ediff} and \np{nn\_ediss}.
 $P_{rt}$ can be set to unity or, following \citet{Blanke1993}, be a function of the local Richardson number, $R_i$:
+$P_{rt}$ can be set to unity or, following \citet{blanke.delecluse_JPO93}, be a function of the local Richardson number, $R_i$:
 \begin{align*}
   % \label{eq:prt}
+  % \label{eq:ZDF_prt}
   P_{rt} =
   \begin{cases}
 …
   \end{cases}
 \end{align*}
-Options are defined through the  \ngn{namzdfy\_tke} namelist variables.
 The choice of $P_{rt}$ is controlled by the \np{nn\_pdl} namelist variable.
 At the sea surface, the value of $\bar{e}$ is prescribed from the wind stress field as
 $\bar{e}_o = e_{bb} |\tau| / \rho_o$, with $e_{bb}$ the \np{rn\_ebb} namelist parameter.
 The default value of $e_{bb}$ is 3.75. \citep{Gaspar1990}), however a much larger value can be used when
+The default value of $e_{bb}$ is 3.75. \citep{gaspar.gregoris.ea_JGR90}), however a much larger value can be used when
 taking into account the surface wave breaking (see below Eq. \autoref{eq:ZDF_Esbc}).
 The bottom value of TKE is assumed to be equal to the value of the level just above.
 …
 the numerical scheme does not ensure its positivity.
 To overcome this problem, a cut-off in the minimum value of $\bar{e}$ is used (\np{rn\_emin} namelist parameter).
 Following \citet{Gaspar1990}, the cut-off value is set to $\sqrt{2}/2~10^{-6}~m^2.s^{-2}$.
 This allows the subsequent formulations to match that of \citet{Gargett1984} for the diffusion in
+Following \citet{gaspar.gregoris.ea_JGR90}, the cut-off value is set to $\sqrt{2}/2~10^{-6}~m^2.s^{-2}$.
+This allows the subsequent formulations to match that of \citet{gargett_JMR84} for the diffusion in
 the thermocline and deep ocean :  $K_\rho = 10^{-3} / N$.
 In addition, a cut-off is applied on $K_m$ and $K_\rho$ to avoid numerical instabilities associated with
 too weak vertical diffusion.
 They must be specified at least larger than the molecular values, and are set through \np{rn\_avm0} and
 \np{rn\_avt0} (namzdf namelist, see \autoref{subsec:ZDF_cst}).
+\np{rn\_avt0} (\nam{zdf} namelist, see \autoref{subsec:ZDF_cst}).
 \subsubsection{Turbulent length scale}
 For computational efficiency, the original formulation of the turbulent length scales proposed by
 \citet{Gaspar1990} has been simplified.
+\citet{gaspar.gregoris.ea_JGR90} has been simplified.
 Four formulations are proposed, the choice of which is controlled by the \np{nn\_mxl} namelist parameter.
 The first two are based on the following first order approximation \citep{Blanke1993}:
+The first two are based on the following first order approximation \citep{blanke.delecluse_JPO93}:
 \begin{equation}
   \label{eq:tke_mxl0_1}
+  \label{eq:ZDF_tke_mxl0_1}
   l_k = l_\epsilon = \sqrt {2 \bar{e}\; } / N
 \end{equation}
 which is valid in a stable stratified region with constant values of the Brunt-Vais\"{a}l\"{a} frequency.
 The resulting length scale is bounded by the distance to the surface or to the bottom
 (\np{nn\_mxl}\forcode{ = 0}) or by the local vertical scale factor (\np{nn\_mxl}\forcode{ = 1}).
 \citet{Blanke1993} notice that this simplification has two major drawbacks:
+(\np{nn\_mxl}\forcode{=0}) or by the local vertical scale factor (\np{nn\_mxl}\forcode{=1}).
+\citet{blanke.delecluse_JPO93} notice that this simplification has two major drawbacks:
 it makes no sense for locally unstable stratification and the computation no longer uses all
 the information contained in the vertical density profile.
 To overcome these drawbacks, \citet{Madec1998} introduces the \np{nn\_mxl}\forcode{ = 2..3} cases,
+To overcome these drawbacks, \citet{madec.delecluse.ea_NPM98} introduces the \np{nn\_mxl}\forcode{=2, 3} cases,
 which add an extra assumption concerning the vertical gradient of the computed length scale.
 So, the length scales are first evaluated as in \autoref{eq:tke_mxl0_1} and then bounded such that:
+So, the length scales are first evaluated as in \autoref{eq:ZDF_tke_mxl0_1} and then bounded such that:
 \begin{equation}
   \label{eq:tke_mxl_constraint}
+  \label{eq:ZDF_tke_mxl_constraint}
   \frac{1}{e_3 }\left| {\frac{\partial l}{\partial k}} \right| \leq 1
   \qquad \text{with }\  l =  l_k = l_\epsilon
 \end{equation}
 \autoref{eq:tke_mxl_constraint} means that the vertical variations of the length scale cannot be larger than
+\autoref{eq:ZDF_tke_mxl_constraint} means that the vertical variations of the length scale cannot be larger than
 the variations of depth.
 It provides a better approximation of the \citet{Gaspar1990} formulation while being much less
+It provides a better approximation of the \citet{gaspar.gregoris.ea_JGR90} formulation while being much less
 time consuming.
 In particular, it allows the length scale to be limited not only by the distance to the surface or
 to the ocean bottom but also by the distance to a strongly stratified portion of the water column such as
 the thermocline (\autoref{fig:mixing_length}).
 In order to impose the \autoref{eq:tke_mxl_constraint} constraint, we introduce two additional length scales:
+the thermocline (\autoref{fig:ZDF_mixing_length}).
+In order to impose the \autoref{eq:ZDF_tke_mxl_constraint} constraint, we introduce two additional length scales:
 $l_{up}$ and $l_{dwn}$, the upward and downward length scales, and
 evaluate the dissipation and mixing length scales as
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=1.00\textwidth]{Fig_mixing_length}
+    \caption{
+      \protect\label{fig:mixing_length}
+      Illustration of the mixing length computation.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_mixing_length}
+  \caption[Mixing length computation]{Illustration of the mixing length computation}
+  \label{fig:ZDF_mixing_length}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \[
   % \label{eq:tke_mxl2}
+  % \label{eq:ZDF_tke_mxl2}
   \begin{aligned}
     l_{up\ \ }^{(k)} &= \min \left(  l^{(k)} \ , \ l_{up}^{(k+1)} + e_{3t}^{(k)}\ \ \ \;  \right)
 …
   \end{aligned}
 \]
 where $l^{(k)}$ is computed using \autoref{eq:tke_mxl0_1}, \ie $l^{(k)} = \sqrt {2 {\bar e}^{(k)} / {N^2}^{(k)} }$.
 In the \np{nn\_mxl}\forcode{ = 2} case, the dissipation and mixing length scales take the same value:
 $ l_k=  l_\epsilon = \min \left(\ l_{up} \;,\;  l_{dwn}\ \right)$, while in the \np{nn\_mxl}\forcode{ = 3} case,
 the dissipation and mixing turbulent length scales are give as in \citet{Gaspar1990}:
 \[
   % \label{eq:tke_mxl_gaspar}
+where $l^{(k)}$ is computed using \autoref{eq:ZDF_tke_mxl0_1}, \ie\ $l^{(k)} = \sqrt {2 {\bar e}^{(k)} / {N^2}^{(k)} }$.
+In the \np{nn\_mxl}\forcode{=2} case, the dissipation and mixing length scales take the same value:
+$ l_k=  l_\epsilon = \min \left(\ l_{up} \;,\;  l_{dwn}\ \right)$, while in the \np{nn\_mxl}\forcode{=3} case,
+the dissipation and mixing turbulent length scales are give as in \citet{gaspar.gregoris.ea_JGR90}:
+\[
+  % \label{eq:ZDF_tke_mxl_gaspar}
   \begin{aligned}
     & l_k          = \sqrt{\  l_{up} \ \ l_{dwn}\ }   \\
 …
 Usually the surface scale is given by $l_o = \kappa \,z_o$ where $\kappa = 0.4$ is von Karman's constant and
 $z_o$ the roughness parameter of the surface.
 Assuming $z_o=0.1$~m \citep{Craig_Banner_JPO94} leads to a 0.04~m, the default value of \np{rn\_mxl0}.
+Assuming $z_o=0.1$~m \citep{craig.banner_JPO94} leads to a 0.04~m, the default value of \np{rn\_mxl0}.
 In the ocean interior a minimum length scale is set to recover the molecular viscosity when
 $\bar{e}$ reach its minimum value ($1.10^{-6}= C_k\, l_{min} \,\sqrt{\bar{e}_{min}}$ ).
 …
 %-----------------------------------------------------------------------%
 Following \citet{Mellor_Blumberg_JPO04}, the TKE turbulence closure model has been modified to
+Following \citet{mellor.blumberg_JPO04}, the TKE turbulence closure model has been modified to
 include the effect of surface wave breaking energetics.
 This results in a reduction of summertime surface temperature when the mixed layer is relatively shallow.
 The \citet{Mellor_Blumberg_JPO04} modifications acts on surface length scale and TKE values and
 air-sea drag coefficient.
 The latter concerns the bulk formulea and is not discussed here.
 Following \citet{Craig_Banner_JPO94}, the boundary condition on surface TKE value is :
+The \citet{mellor.blumberg_JPO04} modifications acts on surface length scale and TKE values and
+air-sea drag coefficient.
+The latter concerns the bulk formulae and is not discussed here.
+Following \citet{craig.banner_JPO94}, the boundary condition on surface TKE value is :
 \begin{equation}
   \label{eq:ZDF_Esbc}
   \bar{e}_o = \frac{1}{2}\,\left(  15.8\,\alpha_{CB} \right)^{2/3} \,\frac{|\tau|}{\rho_o}
 \end{equation}
 where $\alpha_{CB}$ is the \citet{Craig_Banner_JPO94} constant of proportionality which depends on the ''wave age'',
 ranging from 57 for mature waves to 146 for younger waves \citep{Mellor_Blumberg_JPO04}.
+where $\alpha_{CB}$ is the \citet{craig.banner_JPO94} constant of proportionality which depends on the ''wave age'',
+ranging from 57 for mature waves to 146 for younger waves \citep{mellor.blumberg_JPO04}.
 The boundary condition on the turbulent length scale follows the Charnock's relation:
 \begin{equation}
 …
 \end{equation}
 where $\kappa=0.40$ is the von Karman constant, and $\beta$ is the Charnock's constant.
 \citet{Mellor_Blumberg_JPO04} suggest $\beta = 2.10^{5}$ the value chosen by
 \citet{Stacey_JPO99} citing observation evidence, and
+\citet{mellor.blumberg_JPO04} suggest $\beta = 2.10^{5}$ the value chosen by
+\citet{stacey_JPO99} citing observation evidence, and
 $\alpha_{CB} = 100$ the Craig and Banner's value.
 As the surface boundary condition on TKE is prescribed through $\bar{e}_o = e_{bb} |\tau| / \rho_o$,
 with $e_{bb}$ the \np{rn\_ebb} namelist parameter, setting \np{rn\_ebb}\forcode{ = 67.83} corresponds
+with $e_{bb}$ the \np{rn\_ebb} namelist parameter, setting \np{rn\_ebb}\forcode{ = 67.83} corresponds
 to $\alpha_{CB} = 100$.
 Further setting  \np{ln\_mxl0} to true applies \autoref{eq:ZDF_Lsbc} as surface boundary condition on length scale,
+Further setting  \np{ln\_mxl0}\forcode{ =.true.},  applies \autoref{eq:ZDF_Lsbc} as the surface boundary condition on the length scale,
 with $\beta$ hard coded to the Stacey's value.
 Note that a minimal threshold of \np{rn\_emin0}$=10^{-4}~m^2.s^{-2}$ (namelist parameters) is applied on
+Note that a minimal threshold of \np{rn\_emin0}$=10^{-4}~m^2.s^{-2}$ (namelist parameters) is applied on the
 surface $\bar{e}$ value.
 …
 Although LC have nothing to do with convection, the circulation pattern is rather similar to
 so-called convective rolls in the atmospheric boundary layer.
 The detailed physics behind LC is described in, for example, \citet{Craik_Leibovich_JFM76}.
+The detailed physics behind LC is described in, for example, \citet{craik.leibovich_JFM76}.
 The prevailing explanation is that LC arise from a nonlinear interaction between the Stokes drift and
 wind drift currents.
+wind drift currents.
 Here we introduced in the TKE turbulent closure the simple parameterization of Langmuir circulations proposed by
 \citep{Axell_JGR02} for a $k-\epsilon$ turbulent closure.
+\citep{axell_JGR02} for a $k-\epsilon$ turbulent closure.
 The parameterization, tuned against large-eddy simulation, includes the whole effect of LC in
 an extra source terms of TKE, $P_{LC}$.
 The presence of $P_{LC}$ in \autoref{eq:zdftke_e}, the TKE equation, is controlled by setting \np{ln\_lc} to
 \forcode{.true.} in the namtke namelist.
 By making an analogy with the characteristic convective velocity scale (\eg, \citet{D'Alessio_al_JPO98}),
 $P_{LC}$ is assumed to be :
+an extra source term of TKE, $P_{LC}$.
+The presence of $P_{LC}$ in \autoref{eq:ZDF_tke_e}, the TKE equation, is controlled by setting \np{ln\_lc} to
+\forcode{.true.} in the \nam{zdf\_tke} namelist.
+By making an analogy with the characteristic convective velocity scale (\eg, \citet{dalessio.abdella.ea_JPO98}),
+$P_{LC}$ is assumed to be :
 \[
 P_{LC}(z) = \frac{w_{LC}^3(z)}{H_{LC}}
 \]
 where $w_{LC}(z)$ is the vertical velocity profile of LC, and $H_{LC}$ is the LC depth.
 With no information about the wave field, $w_{LC}$ is assumed to be proportional to
 the Stokes drift $u_s = 0.377\,\,|\tau|^{1/2}$, where $|\tau|$ is the surface wind stress module
 \footnote{Following \citet{Li_Garrett_JMR93}, the surface Stoke drift velocity may be expressed as
+With no information about the wave field, $w_{LC}$ is assumed to be proportional to
+the Stokes drift $u_s = 0.377\,\,|\tau|^{1/2}$, where $|\tau|$ is the surface wind stress module
+\footnote{Following \citet{li.garrett_JMR93}, the surface Stoke drift velocity may be expressed as
   $u_s =  0.016 \,|U_{10m}|$.
   Assuming an air density of $\rho_a=1.22 \,Kg/m^3$ and a drag coefficient of
 …
 For the vertical variation, $w_{LC}$ is assumed to be zero at the surface as well as at
 a finite depth $H_{LC}$ (which is often close to the mixed layer depth),
 and simply varies as a sine function in between (a first-order profile for the Langmuir cell structures).
+and simply varies as a sine function in between (a first-order profile for the Langmuir cell structures).
 The resulting expression for $w_{LC}$ is :
 \[
 …
   \end{cases}
 \]
 where $c_{LC} = 0.15$ has been chosen by \citep{Axell_JGR02} as a good compromise to fit LES data.
+where $c_{LC} = 0.15$ has been chosen by \citep{axell_JGR02} as a good compromise to fit LES data.
 The chosen value yields maximum vertical velocities $w_{LC}$ of the order of a few centimeters per second.
 The value of $c_{LC}$ is set through the \np{rn\_lc} namelist parameter,
 having in mind that it should stay between 0.15 and 0.54 \citep{Axell_JGR02}.
+having in mind that it should stay between 0.15 and 0.54 \citep{axell_JGR02}.
 The $H_{LC}$ is estimated in a similar way as the turbulent length scale of TKE equations:
 $H_{LC}$ is depth to which a water parcel with kinetic energy due to Stoke drift can reach on its own by
 converting its kinetic energy to potential energy, according to
+$H_{LC}$ is the depth to which a water parcel with kinetic energy due to Stoke drift can reach on its own by
+converting its kinetic energy to potential energy, according to
 \[
 - \int_{-H_{LC}}^0 { N^2\;z  \;dz} = \frac{1}{2} u_s^2
 …
 produce mixed-layer depths that are too shallow during summer months and windy conditions.
 This bias is particularly acute over the Southern Ocean.
 To overcome this systematic bias, an ad hoc parameterization is introduced into the TKE scheme \cite{Rodgers_2014}.
 The parameterization is an empirical one, \ie not derived from theoretical considerations,
 but rather is meant to account for observed processes that affect the density structure of
 the ocean’s planetary boundary layer that are not explicitly captured by default in the TKE scheme
 (\ie near-inertial oscillations and ocean swells and waves).
 When using this parameterization (\ie when \np{nn\_etau}\forcode{ = 1}),
+To overcome this systematic bias, an ad hoc parameterization is introduced into the TKE scheme \cite{rodgers.aumont.ea_B14}.
+The parameterization is an empirical one, \ie\ not derived from theoretical considerations,
+but rather is meant to account for observed processes that affect the density structure of
+the ocean’s planetary boundary layer that are not explicitly captured by default in the TKE scheme
+(\ie\ near-inertial oscillations and ocean swells and waves).
+When using this parameterization (\ie\ when \np{nn\_etau}\forcode{=1}),
 the TKE input to the ocean ($S$) imposed by the winds in the form of near-inertial oscillations,
 swell and waves is parameterized by \autoref{eq:ZDF_Esbc} the standard TKE surface boundary condition,
 …
 \end{equation}
 where $z$ is the depth, $e_s$ is TKE surface boundary condition, $f_r$ is the fraction of the surface TKE that
 penetrate in the ocean, $h_\tau$ is a vertical mixing length scale that controls exponential shape of
+penetrates in the ocean, $h_\tau$ is a vertical mixing length scale that controls exponential shape of
 the penetration, and $f_i$ is the ice concentration
 (no penetration if $f_i=1$, that is if the ocean is entirely covered by sea-ice).
+(no penetration if $f_i=1$, \ie\ if the ocean is entirely covered by sea-ice).
 The value of $f_r$, usually a few percents, is specified through \np{rn\_efr} namelist parameter.
 The vertical mixing length scale, $h_\tau$, can be set as a 10~m uniform value (\np{nn\_etau}\forcode{ = 0}) or
+The vertical mixing length scale, $h_\tau$, can be set as a 10~m uniform value (\np{nn\_etau}\forcode{=0}) or
 a latitude dependent value (varying from 0.5~m at the Equator to a maximum value of 30~m at high latitudes
 (\np{nn\_etau}\forcode{ = 1}).
 Note that two other option existe, \np{nn\_etau}\forcode{ = 2..3}.
+(\np{nn\_etau}\forcode{=1}).
+Note that two other option exist, \np{nn\_etau}\forcode{=2, 3}.
 They correspond to applying \autoref{eq:ZDF_Ehtau} only at the base of the mixed layer,
 or to using the high frequency part of the stress to evaluate the fraction of TKE that penetrate the ocean.
+or to using the high frequency part of the stress to evaluate the fraction of TKE that penetrates the ocean.
 Those two options are obsolescent features introduced for test purposes.
+They will be removed in the next release.
+% from Burchard et al OM 2008 :
+% the most critical process not reproduced by statistical turbulence models is the activity of
+% internal waves and their interaction with turbulence. After the Reynolds decomposition,
+% internal waves are in principle included in the RANS equations, but later partially
+% excluded by the hydrostatic assumption and the model resolution.
+% Thus far, the representation of internal wave mixing in ocean models has been relatively crude
+% (\eg Mellor, 1989; Large et al., 1994; Meier, 2001; Axell, 2002; St. Laurent and Garrett, 2002).
+% -------------------------------------------------------------------------------------------------------------
+%        TKE discretization considerations
+% -------------------------------------------------------------------------------------------------------------
+\subsection{TKE discretization considerations (\protect\key{zdftke})}
+They will be removed in the next release.
+% This should be explain better below what this rn_eice parameter is meant for:
+In presence of Sea Ice, the value of this mixing can be modulated by the \np{rn\_eice} namelist parameter.
+This parameter varies from \forcode{0} for no effect to \forcode{4} to suppress the TKE input into the ocean when Sea Ice concentration
+is greater than 25\%.
+% from Burchard et al OM 2008 :
+% the most critical process not reproduced by statistical turbulence models is the activity of
+% internal waves and their interaction with turbulence. After the Reynolds decomposition,
+% internal waves are in principle included in the RANS equations, but later partially
+% excluded by the hydrostatic assumption and the model resolution.
+% Thus far, the representation of internal wave mixing in ocean models has been relatively crude
+% (\eg\ Mellor, 1989; Large et al., 1994; Meier, 2001; Axell, 2002; St. Laurent and Garrett, 2002).
+% -------------------------------------------------------------------------------------------------------------
+%        GLS Generic Length Scale Scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection[GLS: Generic Length Scale (\forcode{ln_zdfgls=.true.})]
+{GLS: Generic Length Scale (\protect\np{ln\_zdfgls}\forcode{=.true.})}
+\label{subsec:ZDF_gls}
+%--------------------------------------------namzdf_gls---------------------------------------------------------
+\begin{listing}
+  \nlst{namzdf_gls}
+  \caption{\texttt{namzdf\_gls}}
+  \label{lst:namzdf_gls}
+\end{listing}
+%--------------------------------------------------------------------------------------------------------------
+The Generic Length Scale (GLS) scheme is a turbulent closure scheme based on two prognostic equations:
+one for the turbulent kinetic energy $\bar {e}$, and another for the generic length scale,
+$\psi$ \citep{umlauf.burchard_JMR03, umlauf.burchard_CSR05}.
+This later variable is defined as: $\psi = {C_{0\mu}}^{p} \ {\bar{e}}^{m} \ l^{n}$,
+where the triplet $(p, m, n)$ value given in Tab.\autoref{tab:ZDF_GLS} allows to recover a number of
+well-known turbulent closures ($k$-$kl$ \citep{mellor.yamada_RG82}, $k$-$\epsilon$ \citep{rodi_JGR87},
+$k$-$\omega$ \citep{wilcox_AJ88} among others \citep{umlauf.burchard_JMR03,kantha.carniel_JMR03}).
+The GLS scheme is given by the following set of equations:
+\begin{equation}
+  \label{eq:ZDF_gls_e}
+  \frac{\partial \bar{e}}{\partial t} =
+  \frac{K_m}{\sigma_e e_3 }\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2
+      +\left( \frac{\partial v}{\partial k} \right)^2} \right]
+  -K_\rho \,N^2
+  +\frac{1}{e_3}\,\frac{\partial}{\partial k} \left[ \frac{K_m}{e_3}\,\frac{\partial \bar{e}}{\partial k} \right]
+  - \epsilon
+\end{equation}
+\[
+  % \label{eq:ZDF_gls_psi}
+  \begin{split}
+    \frac{\partial \psi}{\partial t} =& \frac{\psi}{\bar{e}} \left\{
+      \frac{C_1\,K_m}{\sigma_{\psi} {e_3}}\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2
+          +\left( \frac{\partial v}{\partial k} \right)^2} \right]
+      - C_3 \,K_\rho\,N^2   - C_2 \,\epsilon \,Fw   \right\}             \\
+    &+\frac{1}{e_3}  \;\frac{\partial }{\partial k}\left[ {\frac{K_m}{e_3 }
+        \;\frac{\partial \psi}{\partial k}} \right]\;
+  \end{split}
+\]
+\[
+  % \label{eq:ZDF_gls_kz}
+  \begin{split}
+    K_m    &= C_{\mu} \ \sqrt {\bar{e}} \ l         \\
+    K_\rho &= C_{\mu'}\ \sqrt {\bar{e}} \ l
+  \end{split}
+\]
+\[
+  % \label{eq:ZDF_gls_eps}
+  {\epsilon} = C_{0\mu} \,\frac{\bar {e}^{3/2}}{l} \;
+\]
+where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}) and
+$\epsilon$ the dissipation rate.
+The constants $C_1$, $C_2$, $C_3$, ${\sigma_e}$, ${\sigma_{\psi}}$ and the wall function ($Fw$) depends of
+the choice of the turbulence model.
+Four different turbulent models are pre-defined (\autoref{tab:ZDF_GLS}).
+They are made available through the \np{nn\_clo} namelist parameter.
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[htbp]
+  \centering
+  % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}c}
+  \begin{tabular}{ccccc}
+    &   $k-kl$   & $k-\epsilon$ & $k-\omega$ &   generic   \\
+    % & \citep{mellor.yamada_RG82} &  \citep{rodi_JGR87}       & \citep{wilcox_AJ88} &                 \\
+    \hline
+    \hline
+    \np{nn\_clo}     & \textbf{0} &   \textbf{1}  &   \textbf{2}   &    \textbf{3}   \\
+    \hline
+    $( p , n , m )$         &   ( 0 , 1 , 1 )   & ( 3 , 1.5 , -1 )   & ( -1 , 0.5 , -1 )    &  ( 2 , 1 , -0.67 )  \\
+    $\sigma_k$      &    2.44         &     1.              &      2.                &      0.8          \\
+    $\sigma_\psi$  &    2.44         &     1.3            &      2.                 &       1.07       \\
+    $C_1$              &      0.9         &     1.44          &      0.555          &       1.           \\
+    $C_2$              &      0.5         &     1.92          &      0.833          &       1.22       \\
+    $C_3$              &      1.           &     1.              &      1.                &       1.           \\
+    $F_{wall}$        &      Yes        &       --             &     --                  &      --          \\
+    \hline
+    \hline
+  \end{tabular}
+  \caption[Set of predefined GLS parameters or equivalently predefined turbulence models available]{
+    Set of predefined GLS parameters, or equivalently predefined turbulence models available with
+    \protect\np{ln\_zdfgls}\forcode{=.true.} and controlled by
+    the \protect\np{nn\_clos} namelist variable in \protect\nam{zdf\_gls}.}
+  \label{tab:ZDF_GLS}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+In the Mellor-Yamada model, the negativity of $n$ allows to use a wall function to force the convergence of
+the mixing length towards $\kappa z_b$ ($\kappa$ is the Von Karman constant and $z_b$ the rugosity length scale) value near physical boundaries
+(logarithmic boundary layer law).
+$C_{\mu}$ and $C_{\mu'}$ are calculated from stability function proposed by \citet{galperin.kantha.ea_JAS88},
+or by \citet{kantha.clayson_JGR94} or one of the two functions suggested by \citet{canuto.howard.ea_JPO01}
+(\np{nn\_stab\_func}\forcode{=0, 3}, resp.).
+The value of $C_{0\mu}$ depends on the choice of the stability function.
+The surface and bottom boundary condition on both $\bar{e}$ and $\psi$ can be calculated thanks to Dirichlet or
+Neumann condition through \np{nn\_bc\_surf} and \np{nn\_bc\_bot}, resp.
+As for TKE closure, the wave effect on the mixing is considered when
+\np{rn\_crban}\forcode{ > 0.} \citep{craig.banner_JPO94, mellor.blumberg_JPO04}.
+The \np{rn\_crban} namelist parameter is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and
+\np{rn\_charn} provides the value of $\beta$ in \autoref{eq:ZDF_Lsbc}.
+The $\psi$ equation is known to fail in stably stratified flows, and for this reason
+almost all authors apply a clipping of the length scale as an \textit{ad hoc} remedy.
+With this clipping, the maximum permissible length scale is determined by $l_{max} = c_{lim} \sqrt{2\bar{e}}/ N$.
+A value of $c_{lim} = 0.53$ is often used \citep{galperin.kantha.ea_JAS88}.
+\cite{umlauf.burchard_CSR05} show that the value of the clipping factor is of crucial importance for
+the entrainment depth predicted in stably stratified situations,
+and that its value has to be chosen in accordance with the algebraic model for the turbulent fluxes.
+The clipping is only activated if \np{ln\_length\_lim}\forcode{=.true.},
+and the $c_{lim}$ is set to the \np{rn\_clim\_galp} value.
+The time and space discretization of the GLS equations follows the same energetic consideration as for
+the TKE case described in \autoref{subsec:ZDF_tke_ene} \citep{burchard_OM02}.
+Evaluation of the 4 GLS turbulent closure schemes can be found in \citet{warner.sherwood.ea_OM05} in ROMS model and
+ in \citet{reffray.guillaume.ea_GMD15} for the \NEMO\ model.
+% -------------------------------------------------------------------------------------------------------------
+%        OSM OSMOSIS BL Scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection[OSM: OSMosis boundary layer scheme (\forcode{ln_zdfosm=.true.})]
+{OSM: OSMosis boundary layer scheme (\protect\np{ln\_zdfosm}\forcode{=.true.})}
+\label{subsec:ZDF_osm}
+%--------------------------------------------namzdf_osm---------------------------------------------------------
+\begin{listing}
+  \nlst{namzdf_osm}
+  \caption{\texttt{namzdf\_osm}}
+  \label{lst:namzdf_osm}
+\end{listing}
+%--------------------------------------------------------------------------------------------------------------
+The OSMOSIS turbulent closure scheme is based on......   TBC
+% -------------------------------------------------------------------------------------------------------------
+%        TKE and GLS discretization considerations
+% -------------------------------------------------------------------------------------------------------------
+\subsection[ Discrete energy conservation for TKE and GLS schemes]
+{Discrete energy conservation for TKE and GLS schemes}
 \label{subsec:ZDF_tke_ene}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=1.00\textwidth]{Fig_ZDF_TKE_time_scheme}
+    \caption{
+      \protect\label{fig:TKE_time_scheme}
+      Illustration of the TKE time integration and its links to the momentum and tracer time integration.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_ZDF_TKE_time_scheme}
+  \caption[Subgrid kinetic energy integration in GLS and TKE schemes]{
+    Illustration of the subgrid kinetic energy integration in GLS and TKE schemes and
+    its links to the momentum and tracer time integration.}
+  \label{fig:ZDF_TKE_time_scheme}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 The production of turbulence by vertical shear (the first term of the right hand side of
 \autoref{eq:zdftke_e}) should balance the loss of kinetic energy associated with the vertical momentum diffusion
 (first line in \autoref{eq:PE_zdf}).
 To do so a special care have to be taken for both the time and space discretization of
 the TKE equation \citep{Burchard_OM02,Marsaleix_al_OM08}.
 Let us first address the time stepping issue. \autoref{fig:TKE_time_scheme} shows how
+\autoref{eq:ZDF_tke_e}) and  \autoref{eq:ZDF_gls_e}) should balance the loss of kinetic energy associated with the vertical momentum diffusion
+(first line in \autoref{eq:MB_zdf}).
+To do so a special care has to be taken for both the time and space discretization of
+the kinetic energy equation \citep{burchard_OM02,marsaleix.auclair.ea_OM08}.
+Let us first address the time stepping issue. \autoref{fig:ZDF_TKE_time_scheme} shows how
 the two-level Leap-Frog time stepping of the momentum and tracer equations interplays with
 the one-level forward time stepping of TKE equation.
+the one-level forward time stepping of the equation for $\bar{e}$.
 With this framework, the total loss of kinetic energy (in 1D for the demonstration) due to
 the vertical momentum diffusion is obtained by multiplying this quantity by $u^t$ and
 summing the result vertically:
+summing the result vertically:
 \begin{equation}
   \label{eq:energ1}
+  \label{eq:ZDF_energ1}
   \begin{split}
     \int_{-H}^{\eta}  u^t \,\partial_z &\left( {K_m}^t \,(\partial_z u)^{t+\rdt}  \right) \,dz   \\
 …
 \end{equation}
 Here, the vertical diffusion of momentum is discretized backward in time with a coefficient, $K_m$,
 known at time $t$ (\autoref{fig:TKE_time_scheme}), as it is required when using the TKE scheme
 (see \autoref{sec:STP_forward_imp}).
 The first term of the right hand side of \autoref{eq:energ1} represents the kinetic energy transfer at
+known at time $t$ (\autoref{fig:ZDF_TKE_time_scheme}), as it is required when using the TKE scheme
+(see \autoref{sec:TD_forward_imp}).
+The first term of the right hand side of \autoref{eq:ZDF_energ1} represents the kinetic energy transfer at
 the surface (atmospheric forcing) and at the bottom (friction effect).
 The second term is always negative.
 It is the dissipation rate of kinetic energy, and thus minus the shear production rate of $\bar{e}$.
 \autoref{eq:energ1} implies that, to be energetically consistent,
+\autoref{eq:ZDF_energ1} implies that, to be energetically consistent,
 the production rate of $\bar{e}$ used to compute $(\bar{e})^t$ (and thus ${K_m}^t$) should be expressed as
 ${K_m}^{t-\rdt}\,(\partial_z u)^{t-\rdt} \,(\partial_z u)^t$
 …
 A similar consideration applies on the destruction rate of $\bar{e}$ due to stratification
 (second term of the right hand side of \autoref{eq:zdftke_e}).
+(second term of the right hand side of \autoref{eq:ZDF_tke_e} and \autoref{eq:ZDF_gls_e}).
 This term must balance the input of potential energy resulting from vertical mixing.
 The rate of change of potential energy (in 1D for the demonstration) due vertical mixing is obtained by
 multiplying vertical density diffusion tendency by $g\,z$ and and summing the result vertically:
+The rate of change of potential energy (in 1D for the demonstration) due to vertical mixing is obtained by
+multiplying the vertical density diffusion tendency by $g\,z$ and and summing the result vertically:
 \begin{equation}
   \label{eq:energ2}
+  \label{eq:ZDF_energ2}
   \begin{split}
     \int_{-H}^{\eta} g\,z\,\partial_z &\left( {K_\rho}^t \,(\partial_k \rho)^{t+\rdt}   \right) \,dz    \\
 …
   \end{split}
 \end{equation}
 where we use $N^2 = -g \,\partial_k \rho / (e_3 \rho)$.
 The first term of the right hand side of \autoref{eq:energ2} is always zero because
+where we use $N^2 = -g \,\partial_k \rho / (e_3 \rho)$.
+The first term of the right hand side of \autoref{eq:ZDF_energ2} is always zero because
 there is no diffusive flux through the ocean surface and bottom).
 The second term is minus the destruction rate of  $\bar{e}$ due to stratification.
 Therefore \autoref{eq:energ1} implies that, to be energetically consistent,
 the product ${K_\rho}^{t-\rdt}\,(N^2)^t$ should be used in \autoref{eq:zdftke_e}, the TKE equation.
+Therefore \autoref{eq:ZDF_energ1} implies that, to be energetically consistent,
+the product ${K_\rho}^{t-\rdt}\,(N^2)^t$ should be used in \autoref{eq:ZDF_tke_e} and  \autoref{eq:ZDF_gls_e}.
 Let us now address the space discretization issue.
 The vertical eddy coefficients are defined at $w$-point whereas the horizontal velocity components are in
 the centre of the side faces of a $t$-box in staggered C-grid (\autoref{fig:cell}).
+the centre of the side faces of a $t$-box in staggered C-grid (\autoref{fig:DOM_cell}).
 A space averaging is thus required to obtain the shear TKE production term.
 By redoing the \autoref{eq:energ1} in the 3D case, it can be shown that the product of eddy coefficient by
+By redoing the \autoref{eq:ZDF_energ1} in the 3D case, it can be shown that the product of eddy coefficient by
 the shear at $t$ and $t-\rdt$ must be performed prior to the averaging.
 Furthermore, the possible time variation of $e_3$ (\key{vvl} case) have to be taken into account.
+Furthermore, the time variation of $e_3$ has be taken into account.
 The above energetic considerations leads to the following final discrete form for the TKE equation:
 \begin{equation}
   \label{eq:zdftke_ene}
+  \label{eq:ZDF_tke_ene}
   \begin{split}
     \frac { (\bar{e})^t - (\bar{e})^{t-\rdt} } {\rdt}  \equiv
 …
   \end{split}
 \end{equation}
 where the last two terms in \autoref{eq:zdftke_ene} (vertical diffusion and Kolmogorov dissipation)
 are time stepped using a backward scheme (see\autoref{sec:STP_forward_imp}).
+where the last two terms in \autoref{eq:ZDF_tke_ene} (vertical diffusion and Kolmogorov dissipation)
+are time stepped using a backward scheme (see\autoref{sec:TD_forward_imp}).
 Note that the Kolmogorov term has been linearized in time in order to render the implicit computation possible.
+The restart of the TKE scheme requires the storage of $\bar {e}$, $K_m$, $K_\rho$ and $l_\epsilon$ as
+they all appear in the right hand side of \autoref{eq:zdftke_ene}.
+For the latter, it is in fact the ratio $\sqrt{\bar{e}}/l_\epsilon$ which is stored.
+% -------------------------------------------------------------------------------------------------------------
+%        GLS Generic Length Scale Scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection{GLS: Generic Length Scale (\protect\key{zdfgls})}
+\label{subsec:ZDF_gls}
+%--------------------------------------------namzdf_gls---------------------------------------------------------
+\nlst{namzdf_gls}
+%--------------------------------------------------------------------------------------------------------------
+The Generic Length Scale (GLS) scheme is a turbulent closure scheme based on two prognostic equations:
+one for the turbulent kinetic energy $\bar {e}$, and another for the generic length scale,
+$\psi$ \citep{Umlauf_Burchard_JMS03, Umlauf_Burchard_CSR05}.
+This later variable is defined as: $\psi = {C_{0\mu}}^{p} \ {\bar{e}}^{m} \ l^{n}$,
+where the triplet $(p, m, n)$ value given in Tab.\autoref{tab:GLS} allows to recover a number of
+well-known turbulent closures ($k$-$kl$ \citep{Mellor_Yamada_1982}, $k$-$\epsilon$ \citep{Rodi_1987},
+$k$-$\omega$ \citep{Wilcox_1988} among others \citep{Umlauf_Burchard_JMS03,Kantha_Carniel_CSR05}).
+The GLS scheme is given by the following set of equations:
+\begin{equation}
+  \label{eq:zdfgls_e}
+  \frac{\partial \bar{e}}{\partial t} =
+  \frac{K_m}{\sigma_e e_3 }\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2
+      +\left( \frac{\partial v}{\partial k} \right)^2} \right]
+  -K_\rho \,N^2
+  +\frac{1}{e_3}\,\frac{\partial}{\partial k} \left[ \frac{K_m}{e_3}\,\frac{\partial \bar{e}}{\partial k} \right]
+  - \epsilon
+\end{equation}
+\[
+  % \label{eq:zdfgls_psi}
+  \begin{split}
+    \frac{\partial \psi}{\partial t} =& \frac{\psi}{\bar{e}} \left\{
+      \frac{C_1\,K_m}{\sigma_{\psi} {e_3}}\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2
+          +\left( \frac{\partial v}{\partial k} \right)^2} \right]
+      - C_3 \,K_\rho\,N^2   - C_2 \,\epsilon \,Fw   \right\}             \\
+    &+\frac{1}{e_3}  \;\frac{\partial }{\partial k}\left[ {\frac{K_m}{e_3 }
+        \;\frac{\partial \psi}{\partial k}} \right]\;
+  \end{split}
+\]
+\[
+  % \label{eq:zdfgls_kz}
+  \begin{split}
+    K_m    &= C_{\mu} \ \sqrt {\bar{e}} \ l         \\
+    K_\rho &= C_{\mu'}\ \sqrt {\bar{e}} \ l
+  \end{split}
+\]
+\[
+  % \label{eq:zdfgls_eps}
+  {\epsilon} = C_{0\mu} \,\frac{\bar {e}^{3/2}}{l} \;
+\]
+where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}) and
+$\epsilon$ the dissipation rate.
+The constants $C_1$, $C_2$, $C_3$, ${\sigma_e}$, ${\sigma_{\psi}}$ and the wall function ($Fw$) depends of
+the choice of the turbulence model.
+Four different turbulent models are pre-defined (Tab.\autoref{tab:GLS}).
+They are made available through the \np{nn\_clo} namelist parameter.
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[htbp]
+  \begin{center}
+    % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}c}
+    \begin{tabular}{ccccc}
+      &   $k-kl$   & $k-\epsilon$ & $k-\omega$ &   generic   \\
+      % & \citep{Mellor_Yamada_1982} &  \citep{Rodi_1987}       & \citep{Wilcox_1988} &                 \\
+      \hline
+      \hline
+      \np{nn\_clo}     & \textbf{0} &   \textbf{1}  &   \textbf{2}   &    \textbf{3}   \\
+      \hline
+      $( p , n , m )$          &   ( 0 , 1 , 1 )   & ( 3 , 1.5 , -1 )   & ( -1 , 0.5 , -1 )    &  ( 2 , 1 , -0.67 )  \\
+      $\sigma_k$      &    2.44         &     1.              &      2.                &      0.8          \\
+      $\sigma_\psi$  &    2.44         &     1.3            &      2.                 &       1.07       \\
+      $C_1$              &      0.9         &     1.44          &      0.555          &       1.           \\
+      $C_2$              &      0.5         &     1.92          &      0.833          &       1.22       \\
+      $C_3$              &      1.           &     1.              &      1.                &       1.           \\
+      $F_{wall}$        &      Yes        &       --             &     --                  &      --          \\
+      \hline
+      \hline
+    \end{tabular}
+    \caption{
+      \protect\label{tab:GLS}
+      Set of predefined GLS parameters, or equivalently predefined turbulence models available with
+      \protect\key{zdfgls} and controlled by the \protect\np{nn\_clos} namelist variable in \protect\ngn{namzdf\_gls}.
+    }
+  \end{center}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+In the Mellor-Yamada model, the negativity of $n$ allows to use a wall function to force the convergence of
+the mixing length towards $K z_b$ ($K$: Kappa and $z_b$: rugosity length) value near physical boundaries
+(logarithmic boundary layer law).
+$C_{\mu}$ and $C_{\mu'}$ are calculated from stability function proposed by \citet{Galperin_al_JAS88},
+or by \citet{Kantha_Clayson_1994} or one of the two functions suggested by \citet{Canuto_2001}
+(\np{nn\_stab\_func}\forcode{ = 0..3}, resp.).
+The value of $C_{0\mu}$ depends of the choice of the stability function.
+The surface and bottom boundary condition on both $\bar{e}$ and $\psi$ can be calculated thanks to Dirichlet or
+Neumann condition through \np{nn\_tkebc\_surf} and \np{nn\_tkebc\_bot}, resp.
+As for TKE closure, the wave effect on the mixing is considered when
+\np{ln\_crban}\forcode{ = .true.} \citep{Craig_Banner_JPO94, Mellor_Blumberg_JPO04}.
+The \np{rn\_crban} namelist parameter is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and
+\np{rn\_charn} provides the value of $\beta$ in \autoref{eq:ZDF_Lsbc}.
+The $\psi$ equation is known to fail in stably stratified flows, and for this reason
+almost all authors apply a clipping of the length scale as an \textit{ad hoc} remedy.
+With this clipping, the maximum permissible length scale is determined by $l_{max} = c_{lim} \sqrt{2\bar{e}}/ N$.
+A value of $c_{lim} = 0.53$ is often used \citep{Galperin_al_JAS88}.
+\cite{Umlauf_Burchard_CSR05} show that the value of the clipping factor is of crucial importance for
+the entrainment depth predicted in stably stratified situations,
+and that its value has to be chosen in accordance with the algebraic model for the turbulent fluxes.
+The clipping is only activated if \np{ln\_length\_lim}\forcode{ = .true.},
+and the $c_{lim}$ is set to the \np{rn\_clim\_galp} value.
+The time and space discretization of the GLS equations follows the same energetic consideration as for
+the TKE case described in \autoref{subsec:ZDF_tke_ene} \citep{Burchard_OM02}.
+Examples of performance of the 4 turbulent closure scheme can be found in \citet{Warner_al_OM05}.
+% -------------------------------------------------------------------------------------------------------------
+%        OSM OSMOSIS BL Scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection{OSM: OSMOSIS boundary layer scheme (\protect\key{zdfosm})}
+\label{subsec:ZDF_osm}
+%--------------------------------------------namzdf_osm---------------------------------------------------------
+\nlst{namzdf_osm}
+%--------------------------------------------------------------------------------------------------------------
+The OSMOSIS turbulent closure scheme is based on......   TBC
+%The restart of the TKE scheme requires the storage of $\bar {e}$, $K_m$, $K_\rho$ and $l_\epsilon$ as
+%they all appear in the right hand side of \autoref{eq:ZDF_tke_ene}.
+%For the latter, it is in fact the ratio $\sqrt{\bar{e}}/l_\epsilon$ which is stored.
 % ================================================================
 …
 \label{sec:ZDF_conv}
+%--------------------------------------------namzdf--------------------------------------------------------
+\nlst{namzdf}
+%--------------------------------------------------------------------------------------------------------------
+Static instabilities (\ie light potential densities under heavy ones) may occur at particular ocean grid points.
+Static instabilities (\ie\ light potential densities under heavy ones) may occur at particular ocean grid points.
 In nature, convective processes quickly re-establish the static stability of the water column.
 These processes have been removed from the model via the hydrostatic assumption so they must be parameterized.
 …
 % -------------------------------------------------------------------------------------------------------------
 %       Non-Penetrative Convective Adjustment
 % -------------------------------------------------------------------------------------------------------------
 \subsection[Non-penetrative convective adjmt (\protect\np{ln\_tranpc}\forcode{ = .true.})]
             {Non-penetrative convective adjustment (\protect\np{ln\_tranpc}\forcode{ = .true.})}
+%       Non-Penetrative Convective Adjustment
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Non-penetrative convective adjustment (\forcode{ln_tranpc=.true.})]
+{Non-penetrative convective adjustment (\protect\np{ln\_tranpc}\forcode{=.true.})}
 \label{subsec:ZDF_npc}
-%--------------------------------------------namzdf--------------------------------------------------------
-\nlst{namzdf}
-%--------------------------------------------------------------------------------------------------------------
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!htb]
+  \begin{center}
+    \includegraphics[width=0.90\textwidth]{Fig_npc}
+    \caption{
+      \protect\label{fig:npc}
+      Example of an unstable density profile treated by the non penetrative convective adjustment algorithm.
+      $1^{st}$ step: the initial profile is checked from the surface to the bottom.
+      It is found to be unstable between levels 3 and 4.
+      They are mixed.
+      The resulting $\rho$ is still larger than $\rho$(5): levels 3 to 5 are mixed.
+      The resulting $\rho$ is still larger than $\rho$(6): levels 3 to 6 are mixed.
+      The $1^{st}$ step ends since the density profile is then stable below the level 3.
+      $2^{nd}$ step: the new $\rho$ profile is checked following the same procedure as in $1^{st}$ step:
+      levels 2 to 5 are mixed.
+      The new density profile is checked.
+      It is found stable: end of algorithm.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_npc}
+  \caption[Unstable density profile treated by the non penetrative convective adjustment algorithm]{
+    Example of an unstable density profile treated by
+    the non penetrative convective adjustment algorithm.
+    $1^{st}$ step: the initial profile is checked from the surface to the bottom.
+    It is found to be unstable between levels 3 and 4.
+    They are mixed.
+    The resulting $\rho$ is still larger than $\rho$(5): levels 3 to 5 are mixed.
+    The resulting $\rho$ is still larger than $\rho$(6): levels 3 to 6 are mixed.
+    The $1^{st}$ step ends since the density profile is then stable below the level 3.
+    $2^{nd}$ step: the new $\rho$ profile is checked following the same procedure as in $1^{st}$ step:
+    levels 2 to 5 are mixed.
+    The new density profile is checked.
+    It is found stable: end of algorithm.}
+  \label{fig:ZDF_npc}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 Options are defined through the \ngn{namzdf} namelist variables.
 The non-penetrative convective adjustment is used when \np{ln\_zdfnpc}\forcode{ = .true.}.
+Options are defined through the \nam{zdf} namelist variables.
+The non-penetrative convective adjustment is used when \np{ln\_zdfnpc}\forcode{=.true.}.
 It is applied at each \np{nn\_npc} time step and mixes downwards instantaneously the statically unstable portion of
 the water column, but only until the density structure becomes neutrally stable
 (\ie until the mixed portion of the water column has \textit{exactly} the density of the water just below)
 \citep{Madec_al_JPO91}.
 The associated algorithm is an iterative process used in the following way (\autoref{fig:npc}):
+(\ie\ until the mixed portion of the water column has \textit{exactly} the density of the water just below)
+\citep{madec.delecluse.ea_JPO91}.
+The associated algorithm is an iterative process used in the following way (\autoref{fig:ZDF_npc}):
 starting from the top of the ocean, the first instability is found.
 Assume in the following that the instability is located between levels $k$ and $k+1$.
 …
 This algorithm is significantly different from mixing statically unstable levels two by two.
 The latter procedure cannot converge with a finite number of iterations for some vertical profiles while
 the algorithm used in \NEMO converges for any profile in a number of iterations which is less than
+the algorithm used in \NEMO\ converges for any profile in a number of iterations which is less than
 the number of vertical levels.
 This property is of paramount importance as pointed out by \citet{Killworth1989}:
+This property is of paramount importance as pointed out by \citet{killworth_iprc89}:
 it avoids the existence of permanent and unrealistic static instabilities at the sea surface.
 This non-penetrative convective algorithm has been proved successful in studies of the deep water formation in
 the north-western Mediterranean Sea \citep{Madec_al_JPO91, Madec_al_DAO91, Madec_Crepon_Bk91}.
+the north-western Mediterranean Sea \citep{madec.delecluse.ea_JPO91, madec.chartier.ea_DAO91, madec.crepon_iprc91}.
 The current implementation has been modified in order to deal with any non linear equation of seawater
 (L. Brodeau, personnal communication).
 Two main differences have been introduced compared to the original algorithm:
 $(i)$ the stability is now checked using the Brunt-V\"{a}is\"{a}l\"{a} frequency
 (not the the difference in potential density);
+$(i)$ the stability is now checked using the Brunt-V\"{a}is\"{a}l\"{a} frequency
+(not the difference in potential density);
 $(ii)$ when two levels are found unstable, their thermal and haline expansion coefficients are vertically mixed in
 the same way their temperature and salinity has been mixed.
 …
 % -------------------------------------------------------------------------------------------------------------
+%       Enhanced Vertical Diffusion
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Enhanced vertical diffusion (\protect\np{ln\_zdfevd}\forcode{ = .true.})}
+%       Enhanced Vertical Diffusion
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Enhanced vertical diffusion (\forcode{ln_zdfevd=.true.})]
+{Enhanced vertical diffusion (\protect\np{ln\_zdfevd}\forcode{=.true.})}
 \label{subsec:ZDF_evd}
+%--------------------------------------------namzdf--------------------------------------------------------
+\nlst{namzdf}
+%--------------------------------------------------------------------------------------------------------------
+Options are defined through the  \ngn{namzdf} namelist variables.
+The enhanced vertical diffusion parameterisation is used when \np{ln\_zdfevd}\forcode{ = .true.}.
+Options are defined through the  \nam{zdf} namelist variables.
+The enhanced vertical diffusion parameterisation is used when \np{ln\_zdfevd}\forcode{=.true.}.
 In this case, the vertical eddy mixing coefficients are assigned very large values
 (a typical value is $10\;m^2s^{-1})$ in regions where the stratification is unstable
 (\ie when $N^2$ the Brunt-Vais\"{a}l\"{a} frequency is negative) \citep{Lazar_PhD97, Lazar_al_JPO99}.
 This is done either on tracers only (\np{nn\_evdm}\forcode{ = 0}) or
 on both momentum and tracers (\np{nn\_evdm}\forcode{ = 1}).
 In practice, where $N^2\leq 10^{-12}$, $A_T^{vT}$ and $A_T^{vS}$, and if \np{nn\_evdm}\forcode{ = 1},
+in regions where the stratification is unstable
+(\ie\ when $N^2$ the Brunt-Vais\"{a}l\"{a} frequency is negative) \citep{lazar_phd97, lazar.madec.ea_JPO99}.
+This is done either on tracers only (\np{nn\_evdm}\forcode{=0}) or
+on both momentum and tracers (\np{nn\_evdm}\forcode{=1}).
+In practice, where $N^2\leq 10^{-12}$, $A_T^{vT}$ and $A_T^{vS}$, and if \np{nn\_evdm}\forcode{=1},
 the four neighbouring $A_u^{vm} \;\mbox{and}\;A_v^{vm}$ values also, are set equal to
 the namelist parameter \np{rn\_avevd}.
 …
 the convective adjustment algorithm presented above when mixing both tracers and
 momentum in the case of static instabilities.
-It requires the use of an implicit time stepping on vertical diffusion terms
-(\ie np{ln\_zdfexp}\forcode{ = .false.}).
 Note that the stability test is performed on both \textit{before} and \textit{now} values of $N^2$.
 This removes a potential source of divergence of odd and even time step in
 a leapfrog environment \citep{Leclair_PhD2010} (see \autoref{sec:STP_mLF}).
 % -------------------------------------------------------------------------------------------------------------
 %       Turbulent Closure Scheme
 % -------------------------------------------------------------------------------------------------------------
 \subsection[Turbulent closure scheme (\protect\key{zdf}\{tke,gls,osm\})]{Turbulent Closure Scheme (\protect\key{zdftke}, \protect\key{zdfgls} or \protect\key{zdfosm})}
+a leapfrog environment \citep{leclair_phd10} (see \autoref{sec:TD_mLF}).
+% -------------------------------------------------------------------------------------------------------------
+%       Turbulent Closure Scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Handling convection with turbulent closure schemes (\forcode{ln_zdf{tke,gls,osm}=.true.})}
 \label{subsec:ZDF_tcs}
+The turbulent closure scheme presented in \autoref{subsec:ZDF_tke} and \autoref{subsec:ZDF_gls}
+(\key{zdftke} or \key{zdftke} is defined) in theory solves the problem of statically unstable density profiles.
+The turbulent closure schemes presented in \autoref{subsec:ZDF_tke}, \autoref{subsec:ZDF_gls} and
+\autoref{subsec:ZDF_osm} (\ie\ \np{ln\_zdftke} or \np{ln\_zdfgls} or \np{ln\_zdfosm} defined) deal, in theory,
+with statically unstable density profiles.
 In such a case, the term corresponding to the destruction of turbulent kinetic energy through stratification in
 \autoref{eq:zdftke_e} or \autoref{eq:zdfgls_e} becomes a source term, since $N^2$ is negative.
 It results in large values of $A_T^{vT}$ and  $A_T^{vT}$, and also the four neighbouring $A_u^{vm} {and}\;A_v^{vm}$
 (up to $1\;m^2s^{-1}$).
+\autoref{eq:ZDF_tke_e} or \autoref{eq:ZDF_gls_e} becomes a source term, since $N^2$ is negative.
+It results in large values of $A_T^{vT}$ and  $A_T^{vT}$, and also of the four neighboring values at
+velocity points $A_u^{vm} {and}\;A_v^{vm}$ (up to $1\;m^2s^{-1}$).
 These large values restore the static stability of the water column in a way similar to that of
 the enhanced vertical diffusion parameterisation (\autoref{subsec:ZDF_evd}).
 …
 because the mixing length scale is bounded by the distance to the sea surface.
 It can thus be useful to combine the enhanced vertical diffusion with the turbulent closure scheme,
 \ie setting the \np{ln\_zdfnpc} namelist parameter to true and
 defining the turbulent closure CPP key all together.
 The KPP turbulent closure scheme already includes enhanced vertical diffusion in the case of convection,
 as governed by the variables $bvsqcon$ and $difcon$ found in \mdl{zdfkpp},
 therefore \np{ln\_zdfevd}\forcode{ = .false.} should be used with the KPP scheme.
+\ie\ setting the \np{ln\_zdfnpc} namelist parameter to true and
+defining the turbulent closure (\np{ln\_zdftke} or \np{ln\_zdfgls} = \forcode{.true.}) all together.
+The OSMOSIS turbulent closure scheme already includes enhanced vertical diffusion in the case of convection,
+%as governed by the variables $bvsqcon$ and $difcon$ found in \mdl{zdfkpp},
+therefore \np{ln\_zdfevd}\forcode{=.false.} should be used with the OSMOSIS scheme.
 % gm%  + one word on non local flux with KPP scheme trakpp.F90 module...
 …
 % Double Diffusion Mixing
 % ================================================================
+\section{Double diffusion mixing (\protect\key{zdfddm})}
+\label{sec:ZDF_ddm}
+\section[Double diffusion mixing (\forcode{ln_zdfddm=.true.})]
+{Double diffusion mixing (\protect\np{ln\_zdfddm}\forcode{=.true.})}
+\label{subsec:ZDF_ddm}
 %-------------------------------------------namzdf_ddm-------------------------------------------------
 …
 %--------------------------------------------------------------------------------------------------------------
+Options are defined through the  \ngn{namzdf\_ddm} namelist variables.
+This parameterisation has been introduced in \mdl{zdfddm} module and is controlled by the namelist parameter
+\np{ln\_zdfddm} in \nam{zdf}.
 Double diffusion occurs when relatively warm, salty water overlies cooler, fresher water, or vice versa.
 The former condition leads to salt fingering and the latter to diffusive convection.
 Double-diffusive phenomena contribute to diapycnal mixing in extensive regions of the ocean.
 \citet{Merryfield1999} include a parameterisation of such phenomena in a global ocean model and show that
+\citet{merryfield.holloway.ea_JPO99} include a parameterisation of such phenomena in a global ocean model and show that
 it leads to relatively minor changes in circulation but exerts significant regional influences on
 temperature and salinity.
+This parameterisation has been introduced in \mdl{zdfddm} module and is controlled by the \key{zdfddm} CPP key.
 Diapycnal mixing of S and T are described by diapycnal diffusion coefficients
+Diapycnal mixing of S and T are described by diapycnal diffusion coefficients
 \begin{align*}
   % \label{eq:zdfddm_Kz}
+  % \label{eq:ZDF_ddm_Kz}
   &A^{vT} = A_o^{vT}+A_f^{vT}+A_d^{vT} \\
   &A^{vS} = A_o^{vS}+A_f^{vS}+A_d^{vS}
 …
 (1981):
 \begin{align}
   \label{eq:zdfddm_f}
+  \label{eq:ZDF_ddm_f}
   A_f^{vS} &=
              \begin{cases}
 …
                               &\text{otherwise}
              \end{cases}
   \\         \label{eq:zdfddm_f_T}
   A_f^{vT} &= 0.7 \ A_f^{vS} / R_\rho
+  \\         \label{eq:ZDF_ddm_f_T}
+  A_f^{vT} &= 0.7 \ A_f^{vS} / R_\rho
 \end{align}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=0.99\textwidth]{Fig_zdfddm}
+    \caption{
+      \protect\label{fig:zdfddm}
+      From \citet{Merryfield1999} :
+      (a) Diapycnal diffusivities $A_f^{vT}$ and $A_f^{vS}$ for temperature and salt in regions of salt fingering.
+      Heavy curves denote $A^{\ast v} = 10^{-3}~m^2.s^{-1}$ and thin curves $A^{\ast v} = 10^{-4}~m^2.s^{-1}$;
+      (b) diapycnal diffusivities $A_d^{vT}$ and $A_d^{vS}$ for temperature and salt in regions of
+      diffusive convection.
+      Heavy curves denote the Federov parameterisation and thin curves the Kelley parameterisation.
+      The latter is not implemented in \NEMO.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_zdfddm}
+  \caption[Diapycnal diffusivities for temperature and salt in regions of salt fingering and
+  diffusive convection]{
+    From \citet{merryfield.holloway.ea_JPO99}:
+    (a) Diapycnal diffusivities $A_f^{vT}$ and $A_f^{vS}$ for temperature and salt in
+    regions of salt fingering.
+    Heavy curves denote $A^{\ast v} = 10^{-3}~m^2.s^{-1}$ and
+    thin curves $A^{\ast v} = 10^{-4}~m^2.s^{-1}$;
+    (b) diapycnal diffusivities $A_d^{vT}$ and $A_d^{vS}$ for temperature and salt in
+    regions of diffusive convection.
+    Heavy curves denote the Federov parameterisation and thin curves the Kelley parameterisation.
+    The latter is not implemented in \NEMO.}
+  \label{fig:ZDF_ddm}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 The factor 0.7 in \autoref{eq:zdfddm_f_T} reflects the measured ratio $\alpha F_T /\beta F_S \approx  0.7$ of
 buoyancy flux of heat to buoyancy flux of salt (\eg, \citet{McDougall_Taylor_JMR84}).
 Following  \citet{Merryfield1999}, we adopt $R_c = 1.6$, $n = 6$, and $A^{\ast v} = 10^{-4}~m^2.s^{-1}$.
+The factor 0.7 in \autoref{eq:ZDF_ddm_f_T} reflects the measured ratio $\alpha F_T /\beta F_S \approx  0.7$ of
+buoyancy flux of heat to buoyancy flux of salt (\eg, \citet{mcdougall.taylor_JMR84}).
+Following  \citet{merryfield.holloway.ea_JPO99}, we adopt $R_c = 1.6$, $n = 6$, and $A^{\ast v} = 10^{-4}~m^2.s^{-1}$.
 To represent mixing of S and T by diffusive layering,  the diapycnal diffusivities suggested by
 Federov (1988) is used:
+Federov (1988) is used:
 \begin{align}
   % \label{eq:zdfddm_d}
+  % \label{eq:ZDF_ddm_d}
   A_d^{vT} &=
              \begin{cases}
 …
              \end{cases}
                                        \nonumber \\
   \label{eq:zdfddm_d_S}
+  \label{eq:ZDF_ddm_d_S}
   A_d^{vS} &=
              \begin{cases}
 …
 \end{align}
 The dependencies of \autoref{eq:zdfddm_f} to \autoref{eq:zdfddm_d_S} on $R_\rho$ are illustrated in
 \autoref{fig:zdfddm}.
+The dependencies of \autoref{eq:ZDF_ddm_f} to \autoref{eq:ZDF_ddm_d_S} on $R_\rho$ are illustrated in
+\autoref{fig:ZDF_ddm}.
 Implementing this requires computing $R_\rho$ at each grid point on every time step.
 This is done in \mdl{eosbn2} at the same time as $N^2$ is computed.
 …
 % Bottom Friction
 % ================================================================
+\section{Bottom and top friction (\protect\mdl{zdfbfr})}
+\label{sec:ZDF_bfr}
+%--------------------------------------------nambfr--------------------------------------------------------
+ \section[Bottom and top friction (\textit{zdfdrg.F90})]
+ {Bottom and top friction (\protect\mdl{zdfdrg})}
+ \label{sec:ZDF_drg}
+%--------------------------------------------namdrg--------------------------------------------------------
+%
+%\nlst{nambfr}
+\begin{listing}
+  \nlst{namdrg}
+  \caption{\texttt{namdrg}}
+  \label{lst:namdrg}
+\end{listing}
+\begin{listing}
+  \nlst{namdrg_top}
+  \caption{\texttt{namdrg\_top}}
+  \label{lst:namdrg_top}
+\end{listing}
+\begin{listing}
+  \nlst{namdrg_bot}
+  \caption{\texttt{namdrg\_bot}}
+  \label{lst:namdrg_bot}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------------
 Options to define the top and bottom friction are defined through the \ngn{nambfr} namelist variables.
+Options to define the top and bottom friction are defined through the \nam{drg} namelist variables.
 The bottom friction represents the friction generated by the bathymetry.
 The top friction represents the friction generated by the ice shelf/ocean interface.
 As the friction processes at the top and bottom are treated in similar way,
 only the bottom friction is described in detail below.
+As the friction processes at the top and the bottom are treated in and identical way,
+the description below considers mostly the bottom friction case, if not stated otherwise.
 …
 a condition on the vertical diffusive flux.
 For the bottom boundary layer, one has:
 \[
   % \label{eq:zdfbfr_flux}
   A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U}
 \]
+ \[
+   % \label{eq:ZDF_bfr_flux}
+   A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U}
+ \]
 where ${\cal F}_h^{\textbf U}$ is represents the downward flux of horizontal momentum outside
 the logarithmic turbulent boundary layer (thickness of the order of 1~m in the ocean).
 …
 one needs a vertical diffusion coefficient $A^{vm} = 0.125$~m$^2$s$^{-1}$
 (for a Coriolis frequency $f = 10^{-4}$~m$^2$s$^{-1}$).
 With a background diffusion coefficient $A^{vm} = 10^{-4}$~m$^2$s$^{-1}$, the Ekman layer depth is only 1.4~m.
+With a background diffusion coefficient $A^{vm} = 10^{-4}$~m$^2$s$^{-1}$, the Ekman layer depth is only 1.4~m.
 When the vertical mixing coefficient is this small, using a flux condition is equivalent to
 entering the viscous forces (either wind stress or bottom friction) as a body force over the depth of the top or
 …
 To illustrate this, consider the equation for $u$ at $k$, the last ocean level:
 \begin{equation}
   \label{eq:zdfbfr_flux2}
+  \label{eq:ZDF_drg_flux2}
   \frac{\partial u_k}{\partial t} = \frac{1}{e_{3u}} \left[ \frac{A_{uw}^{vm}}{e_{3uw}} \delta_{k+1/2}\;[u] - {\cal F}^u_h \right] \approx - \frac{{\cal F}^u_{h}}{e_{3u}}
 \end{equation}
 …
 In the code, the bottom friction is imposed by adding the trend due to the bottom friction to
 the general momentum trend in \mdl{dynbfr}.
+ the general momentum trend in \mdl{dynzdf}.
 For the time-split surface pressure gradient algorithm, the momentum trend due to
 the barotropic component needs to be handled separately.
 For this purpose it is convenient to compute and store coefficients which can be simply combined with
 bottom velocities and geometric values to provide the momentum trend due to bottom friction.
 These coefficients are computed in \mdl{zdfbfr} and generally take the form $c_b^{\textbf U}$ where:
+ These coefficients are computed in \mdl{zdfdrg} and generally take the form $c_b^{\textbf U}$ where:
 \begin{equation}
   \label{eq:zdfbfr_bdef}
+  \label{eq:ZDF_bfr_bdef}
   \frac{\partial {\textbf U_h}}{\partial t} =
   - \frac{{\cal F}^{\textbf U}_{h}}{e_{3u}} = \frac{c_b^{\textbf U}}{e_{3u}} \;{\textbf U}_h^b
 \end{equation}
 where $\textbf{U}_h^b = (u_b\;,\;v_b)$ is the near-bottom, horizontal, ocean velocity.
+Note than from \NEMO\ 4.0, drag coefficients are only computed at cell centers (\ie\ at T-points) and refer to as $c_b^T$ in the following. These are then linearly interpolated in space to get $c_b^\textbf{U}$ at velocity points.
 % -------------------------------------------------------------------------------------------------------------
 %       Linear Bottom Friction
 % -------------------------------------------------------------------------------------------------------------
+\subsection{Linear bottom friction (\protect\np{nn\_botfr}\forcode{ = 0..1})}
+\label{subsec:ZDF_bfr_linear}
+The linear bottom friction parameterisation (including the special case of a free-slip condition) assumes that
+the bottom friction is proportional to the interior velocity (\ie the velocity of the last model level):
+\[
+  % \label{eq:zdfbfr_linear}
+ \subsection[Linear top/bottom friction (\forcode{ln_lin=.true.})]
+ {Linear top/bottom friction (\protect\np{ln\_lin}\forcode{=.true.)}}
+ \label{subsec:ZDF_drg_linear}
+The linear friction parameterisation (including the special case of a free-slip condition) assumes that
+the friction is proportional to the interior velocity (\ie\ the velocity of the first/last model level):
+\[
+  % \label{eq:ZDF_bfr_linear}
   {\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3} \; \frac{\partial \textbf{U}_h}{\partial k} = r \; \textbf{U}_h^b
 \]
 where $r$ is a friction coefficient expressed in ms$^{-1}$.
 This coefficient is generally estimated by setting a typical decay time $\tau$ in the deep ocean,
+where $r$ is a friction coefficient expressed in $m s^{-1}$.
+This coefficient is generally estimated by setting a typical decay time $\tau$ in the deep ocean,
 and setting $r = H / \tau$, where $H$ is the ocean depth.
 Commonly accepted values of $\tau$ are of the order of 100 to 200 days \citep{Weatherly_JMR84}.
+Commonly accepted values of $\tau$ are of the order of 100 to 200 days \citep{weatherly_JMR84}.
 A value $\tau^{-1} = 10^{-7}$~s$^{-1}$ equivalent to 115 days, is usually used in quasi-geostrophic models.
 One may consider the linear friction as an approximation of quadratic friction, $r \approx 2\;C_D\;U_{av}$
 (\citet{Gill1982}, Eq. 9.6.6).
+(\citet{gill_bk82}, Eq. 9.6.6).
 For example, with a drag coefficient $C_D = 0.002$, a typical speed of tidal currents of $U_{av} =0.1$~m\;s$^{-1}$,
 and assuming an ocean depth $H = 4000$~m, the resulting friction coefficient is $r = 4\;10^{-4}$~m\;s$^{-1}$.
 This is the default value used in \NEMO. It corresponds to a decay time scale of 115~days.
+It can be changed by specifying \np{rn\_bfri1} (namelist parameter).
+For the linear friction case the coefficients defined in the general expression \autoref{eq:zdfbfr_bdef} are:
+\[
+  % \label{eq:zdfbfr_linbfr_b}
+  \begin{split}
+    c_b^u &= - r\\
+    c_b^v &= - r\\
+  \end{split}
+\]
+When \np{nn\_botfr}\forcode{ = 1}, the value of $r$ used is \np{rn\_bfri1}.
+Setting \np{nn\_botfr}\forcode{ = 0} is equivalent to setting $r=0$ and
+leads to a free-slip bottom boundary condition.
+These values are assigned in \mdl{zdfbfr}.
+From v3.2 onwards there is support for local enhancement of these values via an externally defined 2D mask array
+(\np{ln\_bfr2d}\forcode{ = .true.}) given in the \ifile{bfr\_coef} input NetCDF file.
+It can be changed by specifying \np{rn\_Uc0} (namelist parameter).
+ For the linear friction case the drag coefficient used in the general expression \autoref{eq:ZDF_bfr_bdef} is:
+\[
+  % \label{eq:ZDF_bfr_linbfr_b}
+    c_b^T = - r
+\]
+When \np{ln\_lin} \forcode{= .true.}, the value of $r$ used is \np{rn\_Uc0}*\np{rn\_Cd0}.
+Setting \np{ln\_OFF} \forcode{= .true.} (and \forcode{ln_lin=.true.}) is equivalent to setting $r=0$ and leads to a free-slip boundary condition.
+These values are assigned in \mdl{zdfdrg}.
+Note that there is support for local enhancement of these values via an externally defined 2D mask array
+(\np{ln\_boost}\forcode{=.true.}) given in the \ifile{bfr\_coef} input NetCDF file.
 The mask values should vary from 0 to 1.
 Locations with a non-zero mask value will have the friction coefficient increased by
 $mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri1}.
+$mask\_value$ * \np{rn\_boost} * \np{rn\_Cd0}.
 % -------------------------------------------------------------------------------------------------------------
 %       Non-Linear Bottom Friction
 % -------------------------------------------------------------------------------------------------------------
+\subsection{Non-linear bottom friction (\protect\np{nn\_botfr}\forcode{ = 2})}
+\label{subsec:ZDF_bfr_nonlinear}
+The non-linear bottom friction parameterisation assumes that the bottom friction is quadratic:
+\[
+  % \label{eq:zdfbfr_nonlinear}
+ \subsection[Non-linear top/bottom friction (\forcode{ln_non_lin=.true.})]
+ {Non-linear top/bottom friction (\protect\np{ln\_non\_lin}\forcode{=.true.})}
+ \label{subsec:ZDF_drg_nonlinear}
+The non-linear bottom friction parameterisation assumes that the top/bottom friction is quadratic:
+\[
+  % \label{eq:ZDF_drg_nonlinear}
   {\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3 }\frac{\partial \textbf {U}_h
   }{\partial k}=C_D \;\sqrt {u_b ^2+v_b ^2+e_b } \;\; \textbf {U}_h^b
 \]
 where $C_D$ is a drag coefficient, and $e_b $ a bottom turbulent kinetic energy due to tides,
+where $C_D$ is a drag coefficient, and $e_b $ a top/bottom turbulent kinetic energy due to tides,
 internal waves breaking and other short time scale currents.
 A typical value of the drag coefficient is $C_D = 10^{-3} $.
 As an example, the CME experiment \citep{Treguier_JGR92} uses $C_D = 10^{-3}$ and
 $e_b = 2.5\;10^{-3}$m$^2$\;s$^{-2}$, while the FRAM experiment \citep{Killworth1992} uses $C_D = 1.4\;10^{-3}$ and
+As an example, the CME experiment \citep{treguier_JGR92} uses $C_D = 10^{-3}$ and
+$e_b = 2.5\;10^{-3}$m$^2$\;s$^{-2}$, while the FRAM experiment \citep{killworth_JPO92} uses $C_D = 1.4\;10^{-3}$ and
 $e_b =2.5\;\;10^{-3}$m$^2$\;s$^{-2}$.
+The CME choices have been set as default values (\np{rn\_bfri2} and \np{rn\_bfeb2} namelist parameters).
+As for the linear case, the bottom friction is imposed in the code by adding the trend due to
+the bottom friction to the general momentum trend in \mdl{dynbfr}.
+For the non-linear friction case the terms computed in \mdl{zdfbfr} are:
+\[
+  % \label{eq:zdfbfr_nonlinbfr}
+  \begin{split}
+    c_b^u &= - \; C_D\;\left[ u^2 + \left(\bar{\bar{v}}^{i+1,j}\right)^2 + e_b \right]^{1/2}\\
+    c_b^v &= - \; C_D\;\left[  \left(\bar{\bar{u}}^{i,j+1}\right)^2 + v^2 + e_b \right]^{1/2}\\
+  \end{split}
+\]
+The coefficients that control the strength of the non-linear bottom friction are initialised as namelist parameters:
+$C_D$= \np{rn\_bfri2}, and $e_b$ =\np{rn\_bfeb2}.
+Note for applications which treat tides explicitly a low or even zero value of \np{rn\_bfeb2} is recommended.
+From v3.2 onwards a local enhancement of $C_D$ is possible via an externally defined 2D mask array
+(\np{ln\_bfr2d}\forcode{ = .true.}).
+This works in the same way as for the linear bottom friction case with non-zero masked locations increased by
+$mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri2}.
+The CME choices have been set as default values (\np{rn\_Cd0} and \np{rn\_ke0} namelist parameters).
+As for the linear case, the friction is imposed in the code by adding the trend due to
+the friction to the general momentum trend in \mdl{dynzdf}.
+For the non-linear friction case the term computed in \mdl{zdfdrg} is:
+\[
+  % \label{eq:ZDF_drg_nonlinbfr}
+    c_b^T = - \; C_D\;\left[ \left(\bar{u_b}^{i}\right)^2 + \left(\bar{v_b}^{j}\right)^2 + e_b \right]^{1/2}
+\]
+The coefficients that control the strength of the non-linear friction are initialised as namelist parameters:
+$C_D$= \np{rn\_Cd0}, and $e_b$ =\np{rn\_bfeb2}.
+Note that for applications which consider tides explicitly, a low or even zero value of \np{rn\_bfeb2} is recommended. A local enhancement of $C_D$ is again possible via an externally defined 2D mask array
+(\np{ln\_boost}\forcode{=.true.}).
+This works in the same way as for the linear friction case with non-zero masked locations increased by
+$mask\_value$ * \np{rn\_boost} * \np{rn\_Cd0}.
 % -------------------------------------------------------------------------------------------------------------
 %       Bottom Friction Log-layer
 % -------------------------------------------------------------------------------------------------------------
+\subsection[Log-layer btm frict enhncmnt (\protect\np{nn\_botfr}\forcode{ = 2}, \protect\np{ln\_loglayer}\forcode{ = .true.})]
+            {Log-layer bottom friction enhancement (\protect\np{nn\_botfr}\forcode{ = 2}, \protect\np{ln\_loglayer}\forcode{ = .true.})}
+\label{subsec:ZDF_bfr_loglayer}
+In the non-linear bottom friction case, the drag coefficient, $C_D$, can be optionally enhanced using
+a "law of the wall" scaling.
+If  \np{ln\_loglayer} = .true., $C_D$ is no longer constant but is related to the thickness of
+the last wet layer in each column by:
+\[
+  C_D = \left ( {\kappa \over {\rm log}\left ( 0.5e_{3t}/rn\_bfrz0 \right ) } \right )^2
+\]
+\noindent where $\kappa$ is the von-Karman constant and \np{rn\_bfrz0} is a roughness length provided via
+the namelist.
+For stability, the drag coefficient is bounded such that it is kept greater or equal to
+the base \np{rn\_bfri2} value and it is not allowed to exceed the value of an additional namelist parameter:
+\np{rn\_bfri2\_max}, \ie
+\[
+  rn\_bfri2 \leq C_D \leq rn\_bfri2\_max
+\]
+\noindent Note also that a log-layer enhancement can also be applied to the top boundary friction if
+under ice-shelf cavities are in use (\np{ln\_isfcav}\forcode{ = .true.}).
+In this case, the relevant namelist parameters are \np{rn\_tfrz0}, \np{rn\_tfri2} and \np{rn\_tfri2\_max}.
+% -------------------------------------------------------------------------------------------------------------
+%       Bottom Friction stability
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Bottom friction stability considerations}
+\label{subsec:ZDF_bfr_stability}
+Some care needs to exercised over the choice of parameters to ensure that the implementation of
+bottom friction does not induce numerical instability.
+For the purposes of stability analysis, an approximation to \autoref{eq:zdfbfr_flux2} is:
+ \subsection[Log-layer top/bottom friction (\forcode{ln_loglayer=.true.})]
+ {Log-layer top/bottom friction (\protect\np{ln\_loglayer}\forcode{=.true.})}
+ \label{subsec:ZDF_drg_loglayer}
+In the non-linear friction case, the drag coefficient, $C_D$, can be optionally enhanced using
+a "law of the wall" scaling. This assumes that the model vertical resolution can capture the logarithmic layer which typically occur for layers thinner than 1 m or so.
+If  \np{ln\_loglayer} \forcode{= .true.}, $C_D$ is no longer constant but is related to the distance to the wall (or equivalently to the half of the top/bottom layer thickness):
+\[
+  C_D = \left ( {\kappa \over {\mathrm log}\left ( 0.5 \; e_{3b} / rn\_{z0} \right ) } \right )^2
+\]
+\noindent where $\kappa$ is the von-Karman constant and \np{rn\_z0} is a roughness length provided via the namelist.
+The drag coefficient is bounded such that it is kept greater or equal to
+the base \np{rn\_Cd0} value which occurs where layer thicknesses become large and presumably logarithmic layers are not resolved at all. For stability reason, it is also not allowed to exceed the value of an additional namelist parameter:
+\np{rn\_Cdmax}, \ie
+\[
+  rn\_Cd0 \leq C_D \leq rn\_Cdmax
+\]
+\noindent The log-layer enhancement can also be applied to the top boundary friction if
+under ice-shelf cavities are activated (\np{ln\_isfcav}\forcode{=.true.}).
+%In this case, the relevant namelist parameters are \np{rn\_tfrz0}, \np{rn\_tfri2} and \np{rn\_tfri2\_max}.
+% -------------------------------------------------------------------------------------------------------------
+%       Explicit bottom Friction
+% -------------------------------------------------------------------------------------------------------------
+ \subsection{Explicit top/bottom friction (\forcode{ln_drgimp=.false.})}
+ \label{subsec:ZDF_drg_stability}
+Setting \np{ln\_drgimp} \forcode{= .false.} means that bottom friction is treated explicitly in time, which has the advantage of simplifying the interaction with the split-explicit free surface (see \autoref{subsec:ZDF_drg_ts}). The latter does indeed require the knowledge of bottom stresses in the course of the barotropic sub-iteration, which becomes less straightforward in the implicit case. In the explicit case, top/bottom stresses can be computed using \textit{before} velocities and inserted in the overall momentum tendency budget. This reads:
+At the top (below an ice shelf cavity):
+\[
+  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{t}
+  = c_{t}^{\textbf{U}}\textbf{u}^{n-1}_{t}
+\]
+At the bottom (above the sea floor):
+\[
+  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{b}
+  = c_{b}^{\textbf{U}}\textbf{u}^{n-1}_{b}
+\]
+Since this is conditionally stable, some care needs to exercised over the choice of parameters to ensure that the implementation of explicit top/bottom friction does not induce numerical instability.
+For the purposes of stability analysis, an approximation to \autoref{eq:ZDF_drg_flux2} is:
 \begin{equation}
   \label{eq:Eqn_bfrstab}
+  \label{eq:ZDF_Eqn_drgstab}
   \begin{split}
     \Delta u &= -\frac{{{\cal F}_h}^u}{e_{3u}}\;2 \rdt    \\
 …
   \end{split}
 \end{equation}
 \noindent where linear bottom friction and a leapfrog timestep have been assumed.
 To ensure that the bottom friction cannot reverse the direction of flow it is necessary to have:
 \[
   |\Delta u| < \;|u|
 \]
 \noindent which, using \autoref{eq:Eqn_bfrstab}, gives:
+\noindent where linear friction and a leapfrog timestep have been assumed.
+To ensure that the friction cannot reverse the direction of flow it is necessary to have:
+\[
+  |\Delta u| < \;|u|
+\]
+\noindent which, using \autoref{eq:ZDF_Eqn_drgstab}, gives:
 \[
   r\frac{2\rdt}{e_{3u}} < 1 \qquad  \Rightarrow \qquad r < \frac{e_{3u}}{2\rdt}\\
 …
 For example, if $|u| = 1$ m.s$^{-1}$, $rdt = 1800$ s, $r = 10^{-3}$ then $e_{3u}$ should be greater than 3.6 m.
 For most applications, with physically sensible parameters these restrictions should not be of concern.
 But caution may be necessary if attempts are made to locally enhance the bottom friction parameters.
 To ensure stability limits are imposed on the bottom friction coefficients both
+But caution may be necessary if attempts are made to locally enhance the bottom friction parameters.
+To ensure stability limits are imposed on the top/bottom friction coefficients both
 during initialisation and at each time step.
 Checks at initialisation are made in \mdl{zdfbfr} (assuming a 1 m.s$^{-1}$ velocity in the non-linear case).
+Checks at initialisation are made in \mdl{zdfdrg} (assuming a 1 m.s$^{-1}$ velocity in the non-linear case).
 The number of breaches of the stability criterion are reported as well as
 the minimum and maximum values that have been set.
 The criterion is also checked at each time step, using the actual velocity, in \mdl{dynbfr}.
 Values of the bottom friction coefficient are reduced as necessary to ensure stability;
+The criterion is also checked at each time step, using the actual velocity, in \mdl{dynzdf}.
+Values of the friction coefficient are reduced as necessary to ensure stability;
 these changes are not reported.
 Limits on the bottom friction coefficient are not imposed if the user has elected to
 handle the bottom friction implicitly (see \autoref{subsec:ZDF_bfr_imp}).
+Limits on the top/bottom friction coefficient are not imposed if the user has elected to
+handle the friction implicitly (see \autoref{subsec:ZDF_drg_imp}).
 The number of potential breaches of the explicit stability criterion are still reported for information purposes.
 …
 %       Implicit Bottom Friction
 % -------------------------------------------------------------------------------------------------------------
+\subsection{Implicit bottom friction (\protect\np{ln\_bfrimp}\forcode{ = .true.})}
+\label{subsec:ZDF_bfr_imp}
+ \subsection[Implicit top/bottom friction (\forcode{ln_drgimp=.true.})]
+ {Implicit top/bottom friction (\protect\np{ln\_drgimp}\forcode{=.true.})}
+ \label{subsec:ZDF_drg_imp}
 An optional implicit form of bottom friction has been implemented to improve model stability.
+We recommend this option for shelf sea and coastal ocean applications, especially for split-explicit time splitting.
+This option can be invoked by setting \np{ln\_bfrimp} to \forcode{.true.} in the \textit{nambfr} namelist.
+This option requires \np{ln\_zdfexp} to be \forcode{.false.} in the \textit{namzdf} namelist.
+This implementation is realised in \mdl{dynzdf\_imp} and \mdl{dynspg\_ts}. In \mdl{dynzdf\_imp},
+the bottom boundary condition is implemented implicitly.
+\[
+  % \label{eq:dynzdf_bfr}
+  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{mbk}
+  = \binom{c_{b}^{u}u^{n+1}_{mbk}}{c_{b}^{v}v^{n+1}_{mbk}}
+\]
+where $mbk$ is the layer number of the bottom wet layer.
+Superscript $n+1$ means the velocity used in the friction formula is to be calculated, so, it is implicit.
+If split-explicit time splitting is used, care must be taken to avoid the double counting of the bottom friction in
+the 2-D barotropic momentum equations.
+As NEMO only updates the barotropic pressure gradient and Coriolis' forcing terms in the 2-D barotropic calculation,
+we need to remove the bottom friction induced by these two terms which has been included in the 3-D momentum trend
+and update it with the latest value.
+On the other hand, the bottom friction contributed by the other terms
+(\eg the advection term, viscosity term) has been included in the 3-D momentum equations and
+should not be added in the 2-D barotropic mode.
+The implementation of the implicit bottom friction in \mdl{dynspg\_ts} is done in two steps as the following:
+\[
+  % \label{eq:dynspg_ts_bfr1}
+  \frac{\textbf{U}_{med}-\textbf{U}^{m-1}}{2\Delta t}=-g\nabla\eta-f\textbf{k}\times\textbf{U}^{m}+c_{b}
+  \left(\textbf{U}_{med}-\textbf{U}^{m-1}\right)
+\]
+\[
+  \frac{\textbf{U}^{m+1}-\textbf{U}_{med}}{2\Delta t}=\textbf{T}+
+  \left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{U}^{'}\right)-
+\Delta t_{bc}c_{b}\left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{u}_{b}\right)
+\]
+where $\textbf{T}$ is the vertical integrated 3-D momentum trend.
+We assume the leap-frog time-stepping is used here.
+$\Delta t$ is the barotropic mode time step and $\Delta t_{bc}$ is the baroclinic mode time step.
+$c_{b}$ is the friction coefficient.
+$\eta$ is the sea surface level calculated in the barotropic loops while $\eta^{'}$ is the sea surface level used in
+the 3-D baroclinic mode.
+$\textbf{u}_{b}$ is the bottom layer horizontal velocity.
+% -------------------------------------------------------------------------------------------------------------
+%       Bottom Friction with split-explicit time splitting
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Bottom friction w/ split-explicit time splitting (\protect\np{ln\_bfrimp})]
+            {Bottom friction with split-explicit time splitting (\protect\np{ln\_bfrimp})}
+\label{subsec:ZDF_bfr_ts}
+When calculating the momentum trend due to bottom friction in \mdl{dynbfr},
+the bottom velocity at the before time step is used.
+This velocity includes both the baroclinic and barotropic components which is appropriate when
+using either the explicit or filtered surface pressure gradient algorithms
+(\key{dynspg\_exp} or \key{dynspg\_flt}).
+Extra attention is required, however, when using split-explicit time stepping (\key{dynspg\_ts}).
+In this case the free surface equation is solved with a small time step \np{rn\_rdt}/\np{nn\_baro},
+while the three dimensional prognostic variables are solved with the longer time step of \np{rn\_rdt} seconds.
+The trend in the barotropic momentum due to bottom friction appropriate to this method is that given by
+the selected parameterisation (\ie linear or non-linear bottom friction) computed with
+the evolving velocities at each barotropic timestep.
+In the case of non-linear bottom friction, we have elected to partially linearise the problem by
+keeping the coefficients fixed throughout the barotropic time-stepping to those computed in
+\mdl{zdfbfr} using the now timestep.
+This decision allows an efficient use of the $c_b^{\vect{U}}$ coefficients to:
+We recommend this option for shelf sea and coastal ocean applications. %, especially for split-explicit time splitting.
+This option can be invoked by setting \np{ln\_drgimp} to \forcode{.true.} in the \nam{drg} namelist.
+%This option requires \np{ln\_zdfexp} to be \forcode{.false.} in the \nam{zdf} namelist.
+This implementation is performed in \mdl{dynzdf} where the following boundary conditions are set while solving the fully implicit diffusion step:
+At the top (below an ice shelf cavity):
+\[
+  % \label{eq:ZDF_dynZDF__drg_top}
+  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{t}
+  = c_{t}^{\textbf{U}}\textbf{u}^{n+1}_{t}
+\]
+At the bottom (above the sea floor):
+\[
+  % \label{eq:ZDF_dynZDF__drg_bot}
+  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{b}
+  = c_{b}^{\textbf{U}}\textbf{u}^{n+1}_{b}
+\]
+where $t$ and $b$ refers to top and bottom layers respectively.
+Superscript $n+1$ means the velocity used in the friction formula is to be calculated, so it is implicit.
+% -------------------------------------------------------------------------------------------------------------
+%       Bottom Friction with split-explicit free surface
+% -------------------------------------------------------------------------------------------------------------
+ \subsection[Bottom friction with split-explicit free surface]
+ {Bottom friction with split-explicit free surface}
+ \label{subsec:ZDF_drg_ts}
+With split-explicit free surface, the sub-stepping of barotropic equations needs the knowledge of top/bottom stresses. An obvious way to satisfy this is to take them as constant over the course of the barotropic integration and equal to the value used to update the baroclinic momentum trend. Provided \np{ln\_drgimp}\forcode{= .false.} and a centred or \textit{leap-frog} like integration of barotropic equations is used (\ie\ \forcode{ln_bt_fw=.false.}, cf \autoref{subsec:DYN_spg_ts}), this does ensure that barotropic and baroclinic dynamics feel the same stresses during one leapfrog time step. However, if \np{ln\_drgimp}\forcode{= .true.},  stresses depend on the \textit{after} value of the velocities which themselves depend on the barotropic iteration result. This cyclic dependency makes difficult obtaining consistent stresses in 2d and 3d dynamics. Part of this mismatch is then removed when setting the final barotropic component of 3d velocities to the time splitting estimate. This last step can be seen as a necessary evil but should be minimized since it interferes with the adjustment to the boundary conditions.
+The strategy to handle top/bottom stresses with split-explicit free surface in \NEMO\ is as follows:
 \begin{enumerate}
+\item On entry to \rou{dyn\_spg\_ts}, remove the contribution of the before barotropic velocity to
+  the bottom friction component of the vertically integrated momentum trend.
+  Note the same stability check that is carried out on the bottom friction coefficient in \mdl{dynbfr} has to
+  be applied here to ensure that the trend removed matches that which was added in \mdl{dynbfr}.
+\item At each barotropic step, compute the contribution of the current barotropic velocity to
+  the trend due to bottom friction.
+  Add this contribution to the vertically integrated momentum trend.
+  This contribution is handled implicitly which eliminates the need to impose a stability criteria on
+  the values of the bottom friction coefficient within the barotropic loop.
+\item To extend the stability of the barotropic sub-stepping, bottom stresses are refreshed at each sub-iteration. The baroclinic part of the flow entering the stresses is frozen at the initial time of the barotropic iteration. In case of non-linear friction, the drag coefficient is also constant.
+\item In case of an implicit drag, specific computations are performed in \mdl{dynzdf} which renders the overall scheme mixed explicit/implicit: the barotropic components of 3d velocities are removed before seeking for the implicit vertical diffusion result. Top/bottom stresses due to the barotropic components are explicitly accounted for thanks to the updated values of barotropic velocities. Then the implicit solution of 3d velocities is obtained. Lastly, the residual barotropic component is replaced by the time split estimate.
 \end{enumerate}
+Note that the use of an implicit formulation within the barotropic loop for the bottom friction trend means that
+any limiting of the bottom friction coefficient in \mdl{dynbfr} does not adversely affect the solution when
+using split-explicit time splitting.
+This is because the major contribution to bottom friction is likely to come from the barotropic component which
+uses the unrestricted value of the coefficient.
+However, if the limiting is thought to be having a major effect
+(a more likely prospect in coastal and shelf seas applications) then
+the fully implicit form of the bottom friction should be used (see \autoref{subsec:ZDF_bfr_imp})
+which can be selected by setting \np{ln\_bfrimp} $=$ \forcode{.true.}.
+Otherwise, the implicit formulation takes the form:
+\[
+  % \label{eq:zdfbfr_implicitts}
+  \bar{U}^{t+ \rdt} = \; \left [ \bar{U}^{t-\rdt}\; + 2 \rdt\;RHS \right ] / \left [ 1 - 2 \rdt \;c_b^{u} / H_e \right ]
+\]
+where $\bar U$ is the barotropic velocity, $H_e$ is the full depth (including sea surface height),
+$c_b^u$ is the bottom friction coefficient as calculated in \rou{zdf\_bfr} and
+$RHS$ represents all the components to the vertically integrated momentum trend except for
+that due to bottom friction.
+% ================================================================
+% Tidal Mixing
+% ================================================================
+\section{Tidal mixing (\protect\key{zdftmx})}
+\label{sec:ZDF_tmx}
+%--------------------------------------------namzdf_tmx--------------------------------------------------
+Note that other strategies are possible, like considering vertical diffusion step in advance, \ie\ prior barotropic integration.
+% ================================================================
+% Internal wave-driven mixing
+% ================================================================
+\section[Internal wave-driven mixing (\forcode{ln_zdfiwm=.true.})]
+{Internal wave-driven mixing (\protect\np{ln\_zdfiwm}\forcode{=.true.})}
+\label{subsec:ZDF_tmx_new}
+%--------------------------------------------namzdf_iwm------------------------------------------
+%
+%\nlst{namzdf_tmx}
+\begin{listing}
+  \nlst{namzdf_iwm}
+  \caption{\texttt{namzdf\_iwm}}
+  \label{lst:namzdf_iwm}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------------
-% -------------------------------------------------------------------------------------------------------------
-%        Bottom intensified tidal mixing
-% -------------------------------------------------------------------------------------------------------------
-\subsection{Bottom intensified tidal mixing}
-\label{subsec:ZDF_tmx_bottom}
-Options are defined through the  \ngn{namzdf\_tmx} namelist variables.
-The parameterization of tidal mixing follows the general formulation for the vertical eddy diffusivity proposed by
-\citet{St_Laurent_al_GRL02} and first introduced in an OGCM by \citep{Simmons_al_OM04}.
-In this formulation an additional vertical diffusivity resulting from internal tide breaking,
-$A^{vT}_{tides}$ is expressed as a function of $E(x,y)$,
-the energy transfer from barotropic tides to baroclinic tides:
-\begin{equation}
-  \label{eq:Ktides}
-  A^{vT}_{tides} =  q \,\Gamma \,\frac{ E(x,y) \, F(z) }{ \rho \, N^2 }
-\end{equation}
-where $\Gamma$ is the mixing efficiency, $N$ the Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}),
-$\rho$ the density, $q$ the tidal dissipation efficiency, and $F(z)$ the vertical structure function.
-The mixing efficiency of turbulence is set by $\Gamma$ (\np{rn\_me} namelist parameter) and
-is usually taken to be the canonical value of $\Gamma = 0.2$ (Osborn 1980).
-The tidal dissipation efficiency is given by the parameter $q$ (\np{rn\_tfe} namelist parameter)
-represents the part of the internal wave energy flux $E(x, y)$ that is dissipated locally,
-with the remaining $1-q$ radiating away as low mode internal waves and
-contributing to the background internal wave field.
-A value of $q=1/3$ is typically used \citet{St_Laurent_al_GRL02}.
-The vertical structure function $F(z)$ models the distribution of the turbulent mixing in the vertical.
-It is implemented as a simple exponential decaying upward away from the bottom,
-with a vertical scale of $h_o$ (\np{rn\_htmx} namelist parameter,
-with a typical value of $500\,m$) \citep{St_Laurent_Nash_DSR04},
-\[
-  % \label{eq:Fz}
-  F(i,j,k) = \frac{ e^{ -\frac{H+z}{h_o} } }{ h_o \left( 1- e^{ -\frac{H}{h_o} } \right) }
-\]
-and is normalized so that vertical integral over the water column is unity.
-The associated vertical viscosity is calculated from the vertical diffusivity assuming a Prandtl number of 1,
-\ie $A^{vm}_{tides}=A^{vT}_{tides}$.
-In the limit of $N \rightarrow 0$ (or becoming negative), the vertical diffusivity is capped at $300\,cm^2/s$ and
-impose a lower limit on $N^2$ of \np{rn\_n2min} usually set to $10^{-8} s^{-2}$.
-These bounds are usually rarely encountered.
-The internal wave energy map, $E(x, y)$ in \autoref{eq:Ktides}, is derived from a barotropic model of
-the tides utilizing a parameterization of the conversion of barotropic tidal energy into internal waves.
-The essential goal of the parameterization is to represent the momentum exchange between the barotropic tides and
-the unrepresented internal waves induced by the tidal flow over rough topography in a stratified ocean.
-In the current version of \NEMO, the map is built from the output of
-the barotropic global ocean tide model MOG2D-G \citep{Carrere_Lyard_GRL03}.
-This model provides the dissipation associated with internal wave energy for the M2 and K1 tides component
-(\autoref{fig:ZDF_M2_K1_tmx}).
-The S2 dissipation is simply approximated as being $1/4$ of the M2 one.
-The internal wave energy is thus : $E(x, y) = 1.25 E_{M2} + E_{K1}$.
-Its global mean value is $1.1$ TW,
-in agreement with independent estimates \citep{Egbert_Ray_Nat00, Egbert_Ray_JGR01}.
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-\begin{figure}[!t]
-  \begin{center}
-    \includegraphics[width=0.90\textwidth]{Fig_ZDF_M2_K1_tmx}
-    \caption{
-      \protect\label{fig:ZDF_M2_K1_tmx}
-      (a) M2 and (b) K1 internal wave drag energy from \citet{Carrere_Lyard_GRL03} ($W/m^2$).
+    }
-  \end{center}
-\end{figure}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-% -------------------------------------------------------------------------------------------------------------
-%        Indonesian area specific treatment
-% -------------------------------------------------------------------------------------------------------------
-\subsection{Indonesian area specific treatment (\protect\np{ln\_zdftmx\_itf})}
-\label{subsec:ZDF_tmx_itf}
-When the Indonesian Through Flow (ITF) area is included in the model domain,
-a specific treatment of tidal induced mixing in this area can be used.
-It is activated through the namelist logical \np{ln\_tmx\_itf}, and the user must provide an input NetCDF file,
-\ifile{mask\_itf}, which contains a mask array defining the ITF area where the specific treatment is applied.
-When \np{ln\_tmx\_itf}\forcode{ = .true.}, the two key parameters $q$ and $F(z)$ are adjusted following
-the parameterisation developed by \citet{Koch-Larrouy_al_GRL07}:
-First, the Indonesian archipelago is a complex geographic region with a series of
-large, deep, semi-enclosed basins connected via numerous narrow straits.
-Once generated, internal tides remain confined within this semi-enclosed area and hardly radiate away.
-Therefore all the internal tides energy is consumed within this area.
-So it is assumed that $q = 1$, \ie all the energy generated is available for mixing.
-Note that for test purposed, the ITF tidal dissipation efficiency is a namelist parameter (\np{rn\_tfe\_itf}).
-A value of $1$ or close to is this recommended for this parameter.
-Second, the vertical structure function, $F(z)$, is no more associated with a bottom intensification of the mixing,
-but with a maximum of energy available within the thermocline.
-\citet{Koch-Larrouy_al_GRL07} have suggested that the vertical distribution of
-the energy dissipation proportional to $N^2$ below the core of the thermocline and to $N$ above.
-The resulting $F(z)$ is:
-\[
-  % \label{eq:Fz_itf}
-  F(i,j,k) \sim     \left\{
-    \begin{aligned}
-      \frac{q\,\Gamma E(i,j) } {\rho N \, \int N     dz}    \qquad \text{when $\partial_z N < 0$} \\
-      \frac{q\,\Gamma E(i,j) } {\rho     \, \int N^2 dz}    \qquad \text{when $\partial_z N > 0$}
-    \end{aligned}
-  \right.
-\]
-Averaged over the ITF area, the resulting tidal mixing coefficient is $1.5\,cm^2/s$,
-which agrees with the independent estimates inferred from observations.
-Introduced in a regional OGCM, the parameterization improves the water mass characteristics in
-the different Indonesian seas, suggesting that the horizontal and vertical distributions of
-the mixing are adequately prescribed \citep{Koch-Larrouy_al_GRL07, Koch-Larrouy_al_OD08a, Koch-Larrouy_al_OD08b}.
-Note also that such a parameterisation has a significant impact on the behaviour of
-global coupled GCMs \citep{Koch-Larrouy_al_CD10}.
-% ================================================================
-% Internal wave-driven mixing
-% ================================================================
-\section{Internal wave-driven mixing (\protect\key{zdftmx\_new})}
-\label{sec:ZDF_tmx_new}
-%--------------------------------------------namzdf_tmx_new------------------------------------------
+%
-%\nlst{namzdf_tmx_new}
-%--------------------------------------------------------------------------------------------------------------
 The parameterization of mixing induced by breaking internal waves is a generalization of
 the approach originally proposed by \citet{St_Laurent_al_GRL02}.
+the approach originally proposed by \citet{st-laurent.simmons.ea_GRL02}.
 A three-dimensional field of internal wave energy dissipation $\epsilon(x,y,z)$ is first constructed,
 and the resulting diffusivity is obtained as
 \[
   % \label{eq:Kwave}
+and the resulting diffusivity is obtained as
+\[
+  % \label{eq:ZDF_Kwave}
   A^{vT}_{wave} =  R_f \,\frac{ \epsilon }{ \rho \, N^2 }
 \]
 where $R_f$ is the mixing efficiency and $\epsilon$ is a specified three dimensional distribution of
 the energy available for mixing.
 If the \np{ln\_mevar} namelist parameter is set to false, the mixing efficiency is taken as constant and
 equal to 1/6 \citep{Osborn_JPO80}.
+If the \np{ln\_mevar} namelist parameter is set to \forcode{.false.}, the mixing efficiency is taken as constant and
+equal to 1/6 \citep{osborn_JPO80}.
 In the opposite (recommended) case, $R_f$ is instead a function of
 the turbulence intensity parameter $Re_b = \frac{ \epsilon}{\nu \, N^2}$,
 with $\nu$ the molecular viscosity of seawater, following the model of \cite{Bouffard_Boegman_DAO2013} and
 the implementation of \cite{de_lavergne_JPO2016_efficiency}.
+with $\nu$ the molecular viscosity of seawater, following the model of \cite{bouffard.boegman_DAO13} and
+the implementation of \cite{de-lavergne.madec.ea_JPO16}.
 Note that $A^{vT}_{wave}$ is bounded by $10^{-2}\,m^2/s$, a limit that is often reached when
 the mixing efficiency is constant.
 In addition to the mixing efficiency, the ratio of salt to heat diffusivities can chosen to vary
 as a function of $Re_b$ by setting the \np{ln\_tsdiff} parameter to true, a recommended choice.
 This parameterization of differential mixing, due to \cite{Jackson_Rehmann_JPO2014},
 is implemented as in \cite{de_lavergne_JPO2016_efficiency}.
+In addition to the mixing efficiency, the ratio of salt to heat diffusivities can chosen to vary
+as a function of $Re_b$ by setting the \np{ln\_tsdiff} parameter to \forcode{.true.}, a recommended choice.
+This parameterization of differential mixing, due to \cite{jackson.rehmann_JPO14},
+is implemented as in \cite{de-lavergne.madec.ea_JPO16}.
 The three-dimensional distribution of the energy available for mixing, $\epsilon(i,j,k)$,
 is constructed from three static maps of column-integrated internal wave energy dissipation,
 $E_{cri}(i,j)$, $E_{pyc}(i,j)$, and $E_{bot}(i,j)$, combined to three corresponding vertical structures
+(de Lavergne et al., in prep):
+$E_{cri}(i,j)$, $E_{pyc}(i,j)$, and $E_{bot}(i,j)$, combined to three corresponding vertical structures:
 \begin{align*}
   F_{cri}(i,j,k) &\propto e^{-h_{ab} / h_{cri} }\\
   F_{pyc}(i,j,k) &\propto N^{n\_p}\\
+  F_{pyc}(i,j,k) &\propto N^{n_p}\\
   F_{bot}(i,j,k) &\propto N^2 \, e^{- h_{wkb} / h_{bot} }
 \end{align*}
+\end{align*}
 In the above formula, $h_{ab}$ denotes the height above bottom,
 $h_{wkb}$ denotes the WKB-stretched height above bottom, defined by
 …
   h_{wkb} = H \, \frac{ \int_{-H}^{z} N \, dz' } { \int_{-H}^{\eta} N \, dz'  } \; ,
 \]
 The $n_p$ parameter (given by \np{nn\_zpyc} in \ngn{namzdf\_tmx\_new} namelist)
+The $n_p$ parameter (given by \np{nn\_zpyc} in \nam{zdf\_iwm} namelist)
 controls the stratification-dependence of the pycnocline-intensified dissipation.
 It can take values of 1 (recommended) or 2.
+It can take values of $1$ (recommended) or $2$.
 Finally, the vertical structures $F_{cri}$ and $F_{bot}$ require the specification of
 the decay scales $h_{cri}(i,j)$ and $h_{bot}(i,j)$, which are defined by two additional input maps.
 $h_{cri}$ is related to the large-scale topography of the ocean (etopo2) and
 $h_{bot}$ is a function of the energy flux $E_{bot}$, the characteristic horizontal scale of
+the abyssal hill topography \citep{Goff_JGR2010} and the latitude.
+the abyssal hill topography \citep{goff_JGR10} and the latitude.
+%
+% Jc: input files names ?
+% ================================================================
+% surface wave-induced mixing
+% ================================================================
+\section[Surface wave-induced mixing (\forcode{ln_zdfswm=.true.})]
+{Surface wave-induced mixing (\protect\np{ln\_zdfswm}\forcode{=.true.})}
+\label{subsec:ZDF_swm}
+Surface waves produce an enhanced mixing through wave-turbulence interaction.
+In addition to breaking waves induced turbulence (\autoref{subsec:ZDF_tke}),
+the influence of non-breaking waves can be accounted introducing
+wave-induced viscosity and diffusivity as a function of the wave number spectrum.
+Following \citet{qiao.yuan.ea_OD10}, a formulation of wave-induced mixing coefficient
+is provided  as a function of wave amplitude, Stokes Drift and wave-number:
+\begin{equation}
+  \label{eq:ZDF_Bv}
+  B_{v} = \alpha {A} {U}_{st} {exp(3kz)}
+\end{equation}
+Where $B_{v}$ is the wave-induced mixing coefficient, $A$ is the wave amplitude,
+${U}_{st}$ is the Stokes Drift velocity, $k$ is the wave number and $\alpha$
+is a constant which should be determined by observations or
+numerical experiments and is set to be 1.
+The coefficient $B_{v}$ is then directly added to the vertical viscosity
+and diffusivity coefficients.
+In order to account for this contribution set: \forcode{ln_zdfswm=.true.},
+then wave interaction has to be activated through \forcode{ln_wave=.true.},
+the Stokes Drift can be evaluated by setting \forcode{ln_sdw=.true.}
+(see \autoref{subsec:SBC_wave_sdw})
+and the needed wave fields can be provided either in forcing or coupled mode
+(for more information on wave parameters and settings see \autoref{sec:SBC_wave})
+% ================================================================
+% Adaptive-implicit vertical advection
+% ================================================================
+\section[Adaptive-implicit vertical advection (\forcode{ln_zad_Aimp=.true.})]
+{Adaptive-implicit vertical advection(\protect\np{ln\_zad\_Aimp}\forcode{=.true.})}
+\label{subsec:ZDF_aimp}
+The adaptive-implicit vertical advection option in NEMO is based on the work of
+\citep{shchepetkin_OM15}.  In common with most ocean models, the timestep used with NEMO
+needs to satisfy multiple criteria associated with different physical processes in order
+to maintain numerical stability. \citep{shchepetkin_OM15} pointed out that the vertical
+CFL criterion is commonly the most limiting. \citep{lemarie.debreu.ea_OM15} examined the
+constraints for a range of time and space discretizations and provide the CFL stability
+criteria for a range of advection schemes. The values for the Leap-Frog with Robert
+asselin filter time-stepping (as used in NEMO) are reproduced in
+\autoref{tab:ZDF_zad_Aimp_CFLcrit}. Treating the vertical advection implicitly can avoid these
+restrictions but at the cost of large dispersive errors and, possibly, large numerical
+viscosity. The adaptive-implicit vertical advection option provides a targetted use of the
+implicit scheme only when and where potential breaches of the vertical CFL condition
+occur. In many practical applications these events may occur remote from the main area of
+interest or due to short-lived conditions such that the extra numerical diffusion or
+viscosity does not greatly affect the overall solution. With such applications, setting:
+\forcode{ln_zad_Aimp=.true.} should allow much longer model timesteps to be used whilst
+retaining the accuracy of the high order explicit schemes over most of the domain.
+\begin{table}[htbp]
+  \centering
+  % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}}
+  \begin{tabular}{r|ccc}
+    \hline
+    spatial discretization  & 2$^nd$ order centered & 3$^rd$ order upwind & 4$^th$ order compact \\
+    advective CFL criterion &                 0.904 &              0.472  &                0.522 \\
+    \hline
+  \end{tabular}
+  \caption[Advective CFL criteria for the leapfrog with Robert Asselin filter time-stepping]{
+    The advective CFL criteria for a range of spatial discretizations for
+    the leapfrog with Robert Asselin filter time-stepping
+    ($\nu=0.1$) as given in \citep{lemarie.debreu.ea_OM15}.}
+  \label{tab:ZDF_zad_Aimp_CFLcrit}
+\end{table}
+In particular, the advection scheme remains explicit everywhere except where and when
+local vertical velocities exceed a threshold set just below the explicit stability limit.
+Once the threshold is reached a tapered transition towards an implicit scheme is used by
+partitioning the vertical velocity into a part that can be treated explicitly and any
+excess that must be treated implicitly. The partitioning is achieved via a Courant-number
+dependent weighting algorithm as described in \citep{shchepetkin_OM15}.
+The local cell Courant number ($Cu$) used for this partitioning is:
+\begin{equation}
+  \label{eq:ZDF_Eqn_zad_Aimp_Courant}
+  \begin{split}
+    Cu &= {2 \rdt \over e^n_{3t_{ijk}}} \bigg (\big [ \texttt{Max}(w^n_{ijk},0.0) - \texttt{Min}(w^n_{ijk+1},0.0) \big ]    \\
+       &\phantom{=} +\big [ \texttt{Max}(e_{{2_u}ij}e^n_{{3_{u}}ijk}u^n_{ijk},0.0) - \texttt{Min}(e_{{2_u}i-1j}e^n_{{3_{u}}i-1jk}u^n_{i-1jk},0.0) \big ]
+                     \big / e_{{1_t}ij}e_{{2_t}ij}            \\
+       &\phantom{=} +\big [ \texttt{Max}(e_{{1_v}ij}e^n_{{3_{v}}ijk}v^n_{ijk},0.0) - \texttt{Min}(e_{{1_v}ij-1}e^n_{{3_{v}}ij-1k}v^n_{ij-1k},0.0) \big ]
+                     \big / e_{{1_t}ij}e_{{2_t}ij} \bigg )    \\
+  \end{split}
+\end{equation}
+\noindent and the tapering algorithm follows \citep{shchepetkin_OM15} as:
+\begin{align}
+  \label{eq:ZDF_Eqn_zad_Aimp_partition}
+Cu_{min} &= 0.15 \nonumber \\
+Cu_{max} &= 0.3  \nonumber \\
+Cu_{cut} &= 2Cu_{max} - Cu_{min} \nonumber \\
+Fcu    &= 4Cu_{max}*(Cu_{max}-Cu_{min}) \nonumber \\
+\cf &=
+     \begin{cases}
+.0                                                        &\text{if $Cu \leq Cu_{min}$} \\
+        (Cu - Cu_{min})^2 / (Fcu +  (Cu - Cu_{min})^2)             &\text{else if $Cu < Cu_{cut}$} \\
+        (Cu - Cu_{max}) / Cu                                       &\text{else}
+     \end{cases}
+\end{align}
+\begin{figure}[!t]
+  \centering
+  \includegraphics[width=\textwidth]{Fig_ZDF_zad_Aimp_coeff}
+  \caption[Partitioning coefficient used to partition vertical velocities into parts]{
+    The value of the partitioning coefficient (\cf) used to partition vertical velocities into
+    parts to be treated implicitly and explicitly for a range of typical Courant numbers
+    (\forcode{ln_zad_Aimp=.true.}).}
+  \label{fig:ZDF_zad_Aimp_coeff}
+\end{figure}
+\noindent The partitioning coefficient is used to determine the part of the vertical
+velocity that must be handled implicitly ($w_i$) and to subtract this from the total
+vertical velocity ($w_n$) to leave that which can continue to be handled explicitly:
+\begin{align}
+  \label{eq:ZDF_Eqn_zad_Aimp_partition2}
+    w_{i_{ijk}} &= \cf_{ijk} w_{n_{ijk}}     \nonumber \\
+    w_{n_{ijk}} &= (1-\cf_{ijk}) w_{n_{ijk}}
+\end{align}
+\noindent Note that the coefficient is such that the treatment is never fully implicit;
+the three cases from \autoref{eq:ZDF_Eqn_zad_Aimp_partition} can be considered as:
+fully-explicit; mixed explicit/implicit and mostly-implicit.  With the settings shown the
+coefficient (\cf) varies as shown in \autoref{fig:ZDF_zad_Aimp_coeff}. Note with these values
+the $Cu_{cut}$ boundary between the mixed implicit-explicit treatment and 'mostly
+implicit' is 0.45 which is just below the stability limited given in
+\autoref{tab:ZDF_zad_Aimp_CFLcrit}  for a 3rd order scheme.
+The $w_i$ component is added to the implicit solvers for the vertical mixing in
+\mdl{dynzdf} and \mdl{trazdf} in a similar way to \citep{shchepetkin_OM15}.  This is
+sufficient for the flux-limited advection scheme (\forcode{ln_traadv_mus}) but further
+intervention is required when using the flux-corrected scheme (\forcode{ln_traadv_fct}).
+For these schemes the implicit upstream fluxes must be added to both the monotonic guess
+and to the higher order solution when calculating the antidiffusive fluxes. The implicit
+vertical fluxes are then removed since they are added by the implicit solver later on.
+The adaptive-implicit vertical advection option is new to NEMO at v4.0 and has yet to be
+used in a wide range of simulations. The following test simulation, however, does illustrate
+the potential benefits and will hopefully encourage further testing and feedback from users:
+\begin{figure}[!t]
+  \centering
+  \includegraphics[width=\textwidth]{Fig_ZDF_zad_Aimp_overflow_frames}
+  \caption[OVERFLOW: time-series of temperature vertical cross-sections]{
+    A time-series of temperature vertical cross-sections for the OVERFLOW test case.
+    These results are for the default settings with \forcode{nn_rdt=10.0} and
+    without adaptive implicit vertical advection (\forcode{ln_zad_Aimp=.false.}).}
+  \label{fig:ZDF_zad_Aimp_overflow_frames}
+\end{figure}
+\subsection{Adaptive-implicit vertical advection in the OVERFLOW test-case}
+The \href{https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/guide/html/test\_cases.html\#overflow}{OVERFLOW test case}
+provides a simple illustration of the adaptive-implicit advection in action. The example here differs from the basic test case
+by only a few extra physics choices namely:
+\begin{verbatim}
+     ln_dynldf_OFF = .false.
+     ln_dynldf_lap = .true.
+     ln_dynldf_hor = .true.
+     ln_zdfnpc     = .true.
+     ln_traadv_fct = .true.
+        nn_fct_h   =  2
+        nn_fct_v   =  2
+\end{verbatim}
+\noindent which were chosen to provide a slightly more stable and less noisy solution. The
+result when using the default value of \forcode{nn_rdt=10.} without adaptive-implicit
+vertical velocity is illustrated in \autoref{fig:ZDF_zad_Aimp_overflow_frames}. The mass of
+cold water, initially sitting on the shelf, moves down the slope and forms a
+bottom-trapped, dense plume. Even with these extra physics choices the model is close to
+stability limits and attempts with \forcode{nn_rdt=30.} will fail after about 5.5 hours
+with excessively high horizontal velocities. This time-scale corresponds with the time the
+plume reaches the steepest part of the topography and, although detected as a horizontal
+CFL breach, the instability originates from a breach of the vertical CFL limit. This is a good
+candidate, therefore, for use of the adaptive-implicit vertical advection scheme.
+The results with \forcode{ln_zad_Aimp=.true.} and a variety of model timesteps
+are shown in \autoref{fig:ZDF_zad_Aimp_overflow_all_rdt} (together with the equivalent
+frames from the base run).  In this simple example the use of the adaptive-implicit
+vertcal advection scheme has enabled a 12x increase in the model timestep without
+significantly altering the solution (although at this extreme the plume is more diffuse
+and has not travelled so far).  Notably, the solution with and without the scheme is
+slightly different even with \forcode{nn_rdt=10.}; suggesting that the base run was
+close enough to instability to trigger the scheme despite completing successfully.
+To assist in diagnosing how active the scheme is, in both location and time, the 3D
+implicit and explicit components of the vertical velocity are available via XIOS as
+\texttt{wimp} and \texttt{wexp} respectively.  Likewise, the partitioning coefficient
+(\cf) is also available as \texttt{wi\_cff}. For a quick oversight of
+the schemes activity the global maximum values of the absolute implicit component
+of the vertical velocity and the partitioning coefficient are written to the netCDF
+version of the run statistics file (\texttt{run.stat.nc}) if this is active (see
+\autoref{sec:MISC_opt} for activation details).
+\autoref{fig:ZDF_zad_Aimp_maxCf} shows examples of the maximum partitioning coefficient for
+the various overflow tests.  Note that the adaptive-implicit vertical advection scheme is
+active even in the base run with \forcode{nn_rdt=10.0s} adding to the evidence that the
+test case is close to stability limits even with this value. At the larger timesteps, the
+vertical velocity is treated mostly implicitly at some location throughout the run. The
+oscillatory nature of this measure appears to be linked to the progress of the plume front
+as each cusp is associated with the location of the maximum shifting to the adjacent cell.
+This is illustrated in \autoref{fig:ZDF_zad_Aimp_maxCf_loc} where the i- and k- locations of the
+maximum have been overlaid for the base run case.
+\medskip
+\noindent Only limited tests have been performed in more realistic configurations. In the
+ORCA2\_ICE\_PISCES reference configuration the scheme does activate and passes
+restartability and reproducibility tests but it is unable to improve the model's stability
+enough to allow an increase in the model time-step. A view of the time-series of maximum
+partitioning coefficient (not shown here)  suggests that the default time-step of 5400s is
+already pushing at stability limits, especially in the initial start-up phase. The
+time-series does not, however, exhibit any of the 'cuspiness' found with the overflow
+tests.
+\medskip
+\noindent A short test with an eORCA1 configuration promises more since a test using a
+time-step of 3600s remains stable with \forcode{ln_zad_Aimp=.true.} whereas the
+time-step is limited to 2700s without.
+\begin{figure}[!t]
+  \centering
+  \includegraphics[width=\textwidth]{Fig_ZDF_zad_Aimp_overflow_all_rdt}
+  \caption[OVERFLOW: sample temperature vertical cross-sections from mid- and end-run]{
+    Sample temperature vertical cross-sections from mid- and end-run using
+    different values for \forcode{nn_rdt} and with or without adaptive implicit vertical advection.
+    Without the adaptive implicit vertical advection
+    only the run with the shortest timestep is able to run to completion.
+    Note also that the colour-scale has been chosen to confirm that
+    temperatures remain within the original range of 10$^o$ to 20$^o$.}
+  \label{fig:ZDF_zad_Aimp_overflow_all_rdt}
+\end{figure}
+\begin{figure}[!t]
+  \centering
+  \includegraphics[width=\textwidth]{Fig_ZDF_zad_Aimp_maxCf}
+  \caption[OVERFLOW: maximum partitioning coefficient during a series of test runs]{
+    The maximum partitioning coefficient during a series of test runs with
+    increasing model timestep length.
+    At the larger timesteps,
+    the vertical velocity is treated mostly implicitly at some location throughout the run.}
+  \label{fig:ZDF_zad_Aimp_maxCf}
+\end{figure}
+\begin{figure}[!t]
+  \centering
+  \includegraphics[width=\textwidth]{Fig_ZDF_zad_Aimp_maxCf_loc}
+  \caption[OVERFLOW: maximum partitioning coefficient for the case overlaid]{
+    The maximum partitioning coefficient for the \forcode{nn_rdt=10.0} case overlaid with
+    information on the gridcell i- and k-locations of the maximum value.}
+  \label{fig:ZDF_zad_Aimp_maxCf_loc}
+\end{figure}
 % ================================================================

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_conservation.tex

-                      r10442
+                      r11564
 % ================================================================
 \chapter{Invariants of the Primitive Equations}
+\label{chap:Invariant}
+\minitoc
+\label{chap:CONS}
+\chaptertoc
 The continuous equations of motion have many analytic properties.
 …
 horizontal kinetic energy and/or potential enstrophy of horizontally non-divergent flow,
 and variance of temperature and salinity will be conserved in the absence of dissipative effects and forcing.
 \citet{Arakawa1966} has first pointed out the advantage of this approach.
+\citet{arakawa_JCP66} has first pointed out the advantage of this approach.
 He showed that if integral constraints on energy are maintained,
 the computation will be free of the troublesome "non linear" instability originally pointed out by
 \citet{Phillips1959}.
+\citet{phillips_TAMS59}.
 A consistent formulation of the energetic properties is also extremely important in carrying out
 long-term numerical simulations for an oceanographic model.
 Such a formulation avoids systematic errors that accumulate with time \citep{Bryan1997}.
+Such a formulation avoids systematic errors that accumulate with time \citep{bryan_JCP97}.
 The general philosophy of OPA which has led to the discrete formulation presented in {\S}II.2 and II.3 is to
 …
 The alternative is to use diffusive schemes such as upstream or flux corrected schemes.
 This last option was rejected because we prefer a complete handling of the model diffusion,
 \ie of the model physics rather than letting the advective scheme produces its own implicit diffusion without
+\ie\ of the model physics rather than letting the advective scheme produces its own implicit diffusion without
 controlling the space and time structure of this implicit diffusion.
 Note that in some very specific cases as passive tracer studies, the positivity of the advective scheme is required.
 In that case, and in that case only, the advective scheme used for passive tracer is a flux correction scheme
 \citep{Marti1992, Levy1996, Levy1998}.
+\citep{Marti1992?, Levy1996?, Levy1998?}.
 % -------------------------------------------------------------------------------------------------------------
 …
 % -------------------------------------------------------------------------------------------------------------
 \section{Conservation properties on ocean dynamics}
 \label{sec:Invariant_dyn}
+\label{sec:CONS_Invariant_dyn}
 The non linear term of the momentum equations has been split into a vorticity term,
 …
 The continuous formulation of the vorticity term satisfies following integral constraints:
 \[
   % \label{eq:vor_vorticity}
+  % \label{eq:CONS_vor_vorticity}
   \int_D {{\textbf {k}}\cdot \frac{1}{e_3 }\nabla \times \left( {\varsigma
         \;{\rm {\bf k}}\times {\textbf {U}}_h } \right)\;dv} =0
 \]
 \[
   % \label{eq:vor_enstrophy}
+        \;{\mathrm {\mathbf k}}\times {\textbf {U}}_h } \right)\;dv} =0
+\]
+\[
+  % \label{eq:CONS_vor_enstrophy}
   if\quad \chi =0\quad \quad \int\limits_D {\varsigma \;{\textbf{k}}\cdot
     \frac{1}{e_3 }\nabla \times \left( {\varsigma {\textbf{k}}\times {\textbf{U}}_h } \right)\;dv} =-\int\limits_D {\frac{1}{2}\varsigma ^2\,\chi \;dv}
 …
 \[
   % \label{eq:vor_energy}
+  % \label{eq:CONS_vor_energy}
   \int_D {{\textbf{U}}_h \times \left( {\varsigma \;{\textbf{k}}\times {\textbf{U}}_h } \right)\;dv} =0
 \]
 …
 Using the symmetry or anti-symmetry properties of the operators (Eqs II.1.10 and 11),
 it can be shown that the scheme (II.2.11) satisfies (II.4.1b) but not (II.4.1c),
 while scheme (II.2.12) satisfies (II.4.1c) but not (II.4.1b) (see appendix C).
+while scheme (II.2.12) satisfies (II.4.1c) but not (II.4.1b) (see appendix C).
 Note that the enstrophy conserving scheme on total vorticity has been chosen as the standard discrete form of
 the vorticity term.
 …
 the horizontal gradient of horizontal kinetic energy:
 \begin{equation} \label{eq:keg_zad}
 \int_D {{\textbf{U}}_h \cdot \nabla _h \left( {1/2\;{\textbf{U}}_h ^2} \right)\;dv} =-\int_D {{\textbf{U}}_h \cdot \frac{w}{e_3 }\;\frac{\partial
+\begin{equation} \label{eq:CONS_keg_zad}
+\int_D {{\textbf{U}}_h \cdot \nabla _h \left( {1/2\;{\textbf{U}}_h ^2} \right)\;dv} =-\int_D {{\textbf{U}}_h \cdot \frac{w}{e_3 }\;\frac{\partial
 {\textbf{U}}_h }{\partial k}\;dv}
 \end{equation}
 Using the discrete form given in {\S}II.2-a and the symmetry or anti-symmetry properties of
 the mean and difference operators, \autoref{eq:keg_zad} is demonstrated in the Appendix C.
 The main point here is that satisfying \autoref{eq:keg_zad} links the choice of the discrete forms of
+the mean and difference operators, \autoref{eq:CONS_keg_zad} is demonstrated in the Appendix C.
+The main point here is that satisfying \autoref{eq:CONS_keg_zad} links the choice of the discrete forms of
 the vertical advection and of the horizontal gradient of horizontal kinetic energy.
 Choosing one imposes the other.
 …
 This properties is satisfied locally with the choice of discretization we have made (property (II.1.9)~).
 In addition, when the equation of state is linear
 (\ie when an advective-diffusive equation for density can be derived from those of temperature and salinity)
+(\ie\ when an advective-diffusive equation for density can be derived from those of temperature and salinity)
 the change of horizontal kinetic energy due to the work of pressure forces is balanced by the change of
 potential energy due to buoyancy forces:
 \[
   % \label{eq:hpg_pe}
+  % \label{eq:CONS_hpg_pe}
   \int_D {-\frac{1}{\rho_o }\left. {\nabla p^h} \right|_z \cdot {\textbf {U}}_h \;dv} \;=\;\int_D {\nabla .\left( {\rho \,{\textbf{U}}} \right)\;g\;z\;\;dv}
 \]
 …
 Using the discrete form given in {\S}~II.2-a and the symmetry or anti-symmetry properties of
 the mean and difference operators, (II.4.3) is demonstrated in the Appendix C.
 The main point here is that satisfying (II.4.3) strongly constraints the discrete expression of the depth of
+The main point here is that satisfying (II.4.3) strongly constraints the discrete expression of the depth of
 $T$-points and of the term added to the pressure gradient in $s-$coordinates: the depth of a $T$-point, $z_T$,
 is defined as the sum the vertical scale factors at $w$-points starting from the surface.
 …
 Nevertheless, the $\psi$-equation is solved numerically by an iterative solver (see {\S}~III.5),
 thus the property is only satisfied with the accuracy required on the solver.
 In addition, with the rigid-lid approximation, the change of horizontal kinetic energy due to the work of
+In addition, with the rigid-lid approximation, the change of horizontal kinetic energy due to the work of
 surface pressure forces is exactly zero:
 \[
   % \label{eq:spg}
+  % \label{eq:CONS_spg}
   \int_D {-\frac{1}{\rho_o }\nabla _h } \left( {p_s } \right)\cdot {\textbf{U}}_h \;dv=0
 \]
 …
 % -------------------------------------------------------------------------------------------------------------
 \section{Conservation properties on ocean thermodynamics}
 \label{sec:Invariant_tra}
+\label{sec:CONS_Invariant_tra}
 In continuous formulation, the advective terms of the tracer equations conserve the tracer content and
 the quadratic form of the tracer, \ie
 \[
   % \label{eq:tra_tra2}
+  % \label{eq:CONS_tra_tra2}
   \int_D {\nabla .\left( {T\;{\textbf{U}}} \right)\;dv} =0
   \;\text{and}
 …
 Note that in both continuous and discrete formulations, there is generally no strict conservation of mass,
 since the equation of state is non linear with respect to $T$ and $S$.
 In practice, the mass is conserved with a very good accuracy.
+In practice, the mass is conserved with a very good accuracy.
 % -------------------------------------------------------------------------------------------------------------
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Conservation properties on momentum physics}
 \label{subsec:Invariant_dyn_physics}
+\label{subsec:CONS_Invariant_dyn_physics}
 \textbf{* lateral momentum diffusion term}
 …
 The continuous formulation of the horizontal diffusion of momentum satisfies the following integral constraints~:
 \[
   % \label{eq:dynldf_dyn}
   \int\limits_D {\frac{1}{e_3 }{\rm {\bf k}}\cdot \nabla \times \left[ {\nabla
+  % \label{eq:CONS_dynldf_dyn}
+  \int\limits_D {\frac{1}{e_3 }{\mathrm {\mathbf k}}\cdot \nabla \times \left[ {\nabla
         _h \left( {A^{lm}\;\chi } \right)-\nabla _h \times \left( {A^{lm}\;\zeta
             \;{\rm {\bf k}}} \right)} \right]\;dv} =0
 \]
 \[
   % \label{eq:dynldf_div}
+            \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} =0
+\]
+\[
+  % \label{eq:CONS_dynldf_div}
   \int\limits_D {\nabla _h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi }
         \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)}
+        \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)}
     \right]\;dv} =0
 \]
 \[
   % \label{eq:dynldf_curl}
   \int_D {{\rm {\bf U}}_h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi }
         \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)}
+  % \label{eq:CONS_dynldf_curl}
+  \int_D {{\mathrm {\mathbf U}}_h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi }
+        \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)}
     \right]\;dv} \leqslant 0
 \]
 \[
   % \label{eq:dynldf_curl2}
   \mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\zeta \;{\rm {\bf k}}\cdot
+  % \label{eq:CONS_dynldf_curl2}
+  \mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\zeta \;{\mathrm {\mathbf k}}\cdot
     \nabla \times \left[ {\nabla _h \left( {A^{lm}\;\chi } \right)-\nabla _h
         \times \left( {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} \right]\;dv}
+        \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} \right]\;dv}
   \leqslant 0
 \]
 \[
   % \label{eq:dynldf_div2}
+  % \label{eq:CONS_dynldf_div2}
   \mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\chi \;\nabla _h \cdot \left[
       {\nabla _h \left( {A^{lm}\;\chi } \right)-\nabla _h \times \left(
           {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} \right]\;dv} \leqslant 0
+          {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} \leqslant 0
 \]
 …
 \[
   % \label{eq:dynzdf_dyn}
+  % \label{eq:CONS_dynzdf_dyn}
   \begin{aligned}
     & \int_D {\frac{1}{e_3 }}  \frac{\partial }{\partial k}\left( \frac{A^{vm}}{e_3 }\frac{\partial {\textbf{U}}_h }{\partial k} \right) \;dv = \overrightarrow{\textbf{0}} \\
 …
 conservation of vorticity, dissipation of enstrophy
 \[
   % \label{eq:dynzdf_vor}
   \begin{aligned}
     & \int_D {\frac{1}{e_3 }{\rm {\bf k}}\cdot \nabla \times \left( {\frac{1}{e_3
           }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm
                   {\bf U}}_h }{\partial k}} \right)} \right)\;dv} =0 \\
     & \int_D {\zeta \,{\rm {\bf k}}\cdot \nabla \times \left( {\frac{1}{e_3
           }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm
                   {\bf U}}_h }{\partial k}} \right)} \right)\;dv} \leq 0 \\
+  % \label{eq:CONS_dynzdf_vor}
+  \begin{aligned}
+    & \int_D {\frac{1}{e_3 }{\mathrm {\mathbf k}}\cdot \nabla \times \left( {\frac{1}{e_3
+          }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm
+                  {\mathbf U}}_h }{\partial k}} \right)} \right)\;dv} =0 \\
+    & \int_D {\zeta \,{\mathrm {\mathbf k}}\cdot \nabla \times \left( {\frac{1}{e_3
+          }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm
+                  {\mathbf U}}_h }{\partial k}} \right)} \right)\;dv} \leq 0 \\
   \end{aligned}
 \]
 conservation of horizontal divergence, dissipation of square of the horizontal divergence
 \[
   % \label{eq:dynzdf_div}
+  % \label{eq:CONS_dynzdf_div}
   \begin{aligned}
     &\int_D {\nabla \cdot \left( {\frac{1}{e_3 }\frac{\partial }{\partial
             k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm {\bf U}}_h }{\partial k}}
+            k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm {\mathbf U}}_h }{\partial k}}
           \right)} \right)\;dv} =0 \\
     & \int_D {\chi \;\nabla \cdot \left( {\frac{1}{e_3 }\frac{\partial }{\partial
             k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm {\bf U}}_h }{\partial k}}
+            k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm {\mathbf U}}_h }{\partial k}}
           \right)} \right)\;dv} \leq 0 \\
   \end{aligned}
 …
 In discrete form, all these properties are satisfied in $z$-coordinate (see Appendix C).
 In $s$-coordinates, only first order properties can be demonstrated,
 \ie the vertical momentum physics conserve momentum, potential vorticity, and horizontal divergence.
+\ie\ the vertical momentum physics conserve momentum, potential vorticity, and horizontal divergence.
 % -------------------------------------------------------------------------------------------------------------
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Conservation properties on tracer physics}
 \label{subsec:Invariant_tra_physics}
+\label{subsec:CONS_Invariant_tra_physics}
 The numerical schemes used for tracer subgridscale physics are written in such a way that
 the heat and salt contents are conserved (equations in flux form, second order centred finite differences).
 As a form flux is used to compute the temperature and salinity,
 the quadratic form of these quantities (\ie their variance) globally tends to diminish.
+the quadratic form of these quantities (\ie\ their variance) globally tends to diminish.
 As for the advective term, there is generally no strict conservation of mass even if,
 in practice, the mass is conserved with a very good accuracy.
 \textbf{* lateral physics: }conservation of tracer, dissipation of tracer
+in practice, the mass is conserved with a very good accuracy.
+\textbf{* lateral physics: }conservation of tracer, dissipation of tracer
 variance, i.e.
 \[
   % \label{eq:traldf_t_t2}
+  % \label{eq:CONS_traldf_t_t2}
   \begin{aligned}
     &\int_D \nabla\, \cdot\, \left( A^{lT} \,\Re \,\nabla \,T \right)\;dv = 0 \\
 …
 \[
   % \label{eq:trazdf_t_t2}
+  % \label{eq:CONS_trazdf_t_t2}
   \begin{aligned}
     & \int_D \frac{1}{e_3 } \frac{\partial }{\partial k}\left( \frac{A^{vT}}{e_3 }  \frac{\partial T}{\partial k}  \right)\;dv = 0 \\

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_misc.tex

-                      r10601
+                      r11564
 \label{chap:MISC}
 \minitoc
+\chaptertoc
 \newpage
 …
 balance the net evaporation occurring over the Mediterranean region.
 This problem occurs even in eddy permitting simulations.
 For example, in ORCA 1/4\deg several straits of the Indonesian archipelago (Ombai, Lombok...)
+For example, in ORCA 1/4\deg\ several straits of the Indonesian archipelago (Ombai, Lombok...)
 are much narrow than even a single ocean grid-point.
+We describe briefly here the three methods that can be used in \NEMO to handle such improperly resolved straits.
+The first two consist of opening the strait by hand while ensuring that the mass exchanges through
+the strait are not too large by either artificially reducing the surface of the strait grid-cells or,
+locally increasing the lateral friction.
+In the third one, the strait is closed but exchanges of mass, heat and salt across the land are allowed.
+Note that such modifications are so specific to a given configuration that no attempt has been made to
+set them in a generic way.
+However, examples of how they can be set up is given in the ORCA 2\deg and 0.5\deg configurations.
+For example, for details of implementation in ORCA2, search: \texttt{IF( cp\_cfg == "orca" .AND. jp\_cfg == 2 )}
+We describe briefly here the two methods that can be used in \NEMO\ to handle such
+improperly resolved straits. The methods consist of opening the strait while ensuring
+that the mass exchanges through the strait are not too large by either artificially
+reducing the cross-sectional area of the strait grid-cells or, locally increasing the
+lateral friction.
 % -------------------------------------------------------------------------------------------------------------
 …
 \label{subsec:MISC_strait_hand}
+$\bullet$ reduced scale factor in the cross-strait direction to a value in better agreement with
+the true mean width of the strait (\autoref{fig:MISC_strait_hand}).
+This technique is sometime called "partially open face" or "partially closed cells".
+The key issue here is only to reduce the faces of $T$-cell
+(\ie change the value of the horizontal scale factors at $u$- or $v$-point) but not the volume of the $T$-cell.
+Indeed, reducing the volume of strait $T$-cell can easily produce a numerical instability at
+that grid point that would require a reduction of the model time step.
+The changes associated with strait management are done in \mdl{domhgr},
+just after the definition or reading of the horizontal scale factors.
+$\bullet$ increase of the viscous boundary layer thickness by local increase of the fmask value at the coast
+(\autoref{fig:MISC_strait_hand}).
+This is done in \mdl{dommsk} together with the setting of the coastal value of fmask (see  \autoref{sec:LBC_coast}).
+The first method involves reducing the scale factor in the cross-strait direction to a
+value in better agreement with the true mean width of the strait
+(\autoref{fig:MISC_strait_hand}).  This technique is sometime called "partially open face"
+or "partially closed cells".  The key issue here is only to reduce the faces of $T$-cell
+(\ie\ change the value of the horizontal scale factors at $u$- or $v$-point) but not the
+volume of the $T$-cell.  Indeed, reducing the volume of strait $T$-cell can easily produce
+a numerical instability at that grid point which would require a reduction of the model
+time step.  Thus to instigate a local change in the width of a Strait requires two steps:
+\begin{itemize}
+\item Add \texttt{e1e2u} and \texttt{e1e2v} arrays to the \np{cn\_domcfg} file. These 2D
+arrays should contain the products of the unaltered values of: $\texttt{e1u}*\texttt{e2u}$
+and $\texttt{e1u}*\texttt{e2v}$ respectively. That is the original surface areas of $u$-
+and $v$- cells respectively.  These areas are usually defined by the corresponding product
+within the \NEMO\ code but the presence of \texttt{e1e2u} and \texttt{e1e2v} in the
+\np{cn\_domcfg} file will suppress this calculation and use the supplied fields instead.
+If the model domain is provided by user-supplied code in \mdl{usrdef\_hgr}, then this
+routine should also return \texttt{e1e2u} and \texttt{e1e2v} and set the integer return
+argument \texttt{ie1e2u\_v} to a non-zero value. Values other than 0 for this argument
+will suppress the calculation of the areas.
+\item Change values of \texttt{e2u} or \texttt{e1v} (either in the \np{cn\_domcfg} file or
+via code in  \mdl{usrdef\_hgr}), whereever a Strait reduction is required. The choice of
+whether to alter \texttt{e2u} or \texttt{e1v} depends. respectively,  on whether the
+Strait in question is North-South orientated (\eg\ Gibraltar) or East-West orientated (\eg
+Lombok).
+\end{itemize}
+The second method is to increase the viscous boundary layer thickness by a local increase
+of the fmask value at the coast. This method can also be effective in wider passages.  The
+concept is illustarted in the second part of  \autoref{fig:MISC_strait_hand} and changes
+to specific locations can be coded in \mdl{usrdef\_fmask}. The \forcode{usr_def_fmask}
+routine is always called after \texttt{fmask} has been defined according to the choice of
+lateral boundary condition as discussed in \autoref{sec:LBC_coast}. The default version of
+\mdl{usrdef\_fmask} contains settings specific to ORCA2 and ORCA1 configurations. These are
+meant as examples only; it is up to the user to verify settings and provide alternatives
+for their own configurations. The default \forcode{usr_def_fmask} makes no changes to
+\texttt{fmask} for any other configuration.
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!tbp]
+  \begin{center}
+    \includegraphics[width=0.80\textwidth]{Fig_Gibraltar}
+    \includegraphics[width=0.80\textwidth]{Fig_Gibraltar2}
+    \caption{
+      \protect\label{fig:MISC_strait_hand}
+      Example of the Gibraltar strait defined in a $1^{\circ} \times 1^{\circ}$ mesh.
+      \textit{Top}: using partially open cells.
+      The meridional scale factor at $v$-point is reduced on both sides of the strait to account for
+      the real width of the strait (about 20 km).
+      Note that the scale factors of the strait $T$-point remains unchanged.
+      \textit{Bottom}: using viscous boundary layers.
+      The four fmask parameters along the strait coastlines are set to a value larger than 4,
+      \ie "strong" no-slip case (see \autoref{fig:LBC_shlat}) creating a large viscous boundary layer that
+      allows a reduced transport through the strait.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_Gibraltar}
+  \includegraphics[width=\textwidth]{Fig_Gibraltar2}
+  \caption[Two methods to defined the Gibraltar strait]{
+    Example of the Gibraltar strait defined in a 1\deg\ $\times$ 1\deg\ mesh.
+    \textit{Top}: using partially open cells.
+    The meridional scale factor at $v$-point is reduced on both sides of the strait to
+    account for the real width of the strait (about 20 km).
+    Note that the scale factors of the strait $T$-point remains unchanged.
+    \textit{Bottom}: using viscous boundary layers.
+    The four fmask parameters along the strait coastlines are set to a value larger than 4,
+    \ie\ "strong" no-slip case (see \autoref{fig:LBC_shlat}) creating a large viscous boundary layer
+    that allows a reduced transport through the strait.}
+  \label{fig:MISC_strait_hand}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!tbp]
+  \begin{center}
+    \includegraphics[width=1.0\textwidth]{Fig_closea_mask_example}
+    \caption{
+      \protect\label{fig:closea_mask_example}
+      Example of mask fields for the closea module. \textit{Left}: a
+      closea\_mask field; \textit{Right}: a closea\_mask\_rnf
+      field. In this example, if ln\_closea is set to .true., the mean
+      freshwater flux over each of the American Great Lakes will be
+      set to zero, and the total residual for all the lakes, if
+      negative, will be put into the St Laurence Seaway in the area
+      shown.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_closea_mask_example}
+  \caption[Mask fields for the \protect\mdl{closea} module]{
+    Example of mask fields for the \protect\mdl{closea} module.
+    \textit{Left}: a closea\_mask field;
+    \textit{Right}: a closea\_mask\_rnf field.
+    In this example, if \protect\np{ln\_closea} is set to \forcode{.true.},
+    the mean freshwater flux over each of the American Great Lakes will be set to zero,
+    and the total residual for all the lakes, if negative, will be put into
+    the St Laurence Seaway in the area shown.}
+  \label{fig:MISC_closea_mask_example}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 % Closed seas
 % ================================================================
+\section{Closed seas (\protect\mdl{closea})}
+\section[Closed seas (\textit{closea.F90})]
+{Closed seas (\protect\mdl{closea})}
 \label{sec:MISC_closea}
 …
 to zero and put the residual flux into the ocean.
 Prior to NEMO 4 the locations of inland seas and lakes was set via
 hardcoded indices for various ORCA configurations. From NEMO 4 onwards
+Prior to \NEMO\ 4 the locations of inland seas and lakes was set via
+hardcoded indices for various ORCA configurations. From \NEMO\ 4 onwards
 the inland seas and lakes are defined using mask fields in the
 domain configuration file. The options are as follows.
 \begin{enumerate}
 \item{{\bf No ``closea\_mask'' field is included in domain configuration
+\item{{\bfseries No ``closea\_mask'' field is included in domain configuration
   file.} In this case the closea module does nothing.}
 \item{{\bf A field called closea\_mask is included in the domain
+\item{{\bfseries A field called closea\_mask is included in the domain
 configuration file and ln\_closea=.false. in namelist namcfg.} In this
 case the inland seas defined by the closea\_mask field are filled in
 …
 closea\_mask that is nonzero is set to be a land point.}
 \item{{\bf A field called closea\_mask is included in the domain
+\item{{\bfseries A field called closea\_mask is included in the domain
 configuration file and ln\_closea=.true. in namelist namcfg.} Each
 inland sea or group of inland seas is set to a positive integer value
 in the closea\_mask field (see Figure \ref{fig:closea_mask_example}
+in the closea\_mask field (see \autoref{fig:MISC_closea_mask_example}
 for an example). The net surface flux over each inland sea or group of
 inland seas is set to zero each timestep and the residual flux is
 …
 closea\_mask is zero).}
 \item{{\bf Fields called closea\_mask and closea\_mask\_rnf are
+\item{{\bfseries Fields called closea\_mask and closea\_mask\_rnf are
 included in the domain configuration file and ln\_closea=.true. in
 namelist namcfg.} This option works as for option 3, except that if
 …
 by the closea\_mask\_rnf field. Each mapping is defined by a positive
 integer value for the inland sea(s) and the corresponding runoff
 points. An example is given in Figure
 \ref{fig:closea_mask_example}. If no mapping is provided for a
+points. An example is given in
+\autoref{fig:MISC_closea_mask_example}. If no mapping is provided for a
 particular inland sea then the residual is spread over the global
 ocean.}
 \item{{\bf Fields called closea\_mask and closea\_mask\_emp are
+\item{{\bfseries Fields called closea\_mask and closea\_mask\_emp are
 included in the domain configuration file and ln\_closea=.true. in
 namelist namcfg.} This option works the same as option 4 except that
 …
 There is a python routine to create the closea\_mask fields and append
 them to the domain configuration file in the utils/tools/DOMAINcfg directory.
 % ================================================================
 % Sub-Domain Functionality
+them to the domain configuration file in the utils/tools/DOMAINcfg directory.
+% ================================================================
+% Sub-Domain Functionality
 % ================================================================
 \section{Sub-domain functionality}
 …
 \subsection{Simple subsetting of input files via NetCDF attributes}
+The extended grids for use with the under-shelf ice cavities will result in redundant rows around Antarctica if
+the ice cavities are not active.
+A simple mechanism for subsetting input files associated with the extended domains has been implemented to
+avoid the need to maintain different sets of input fields for use with or without active ice cavities.
+The existing 'zoom' options are overly complex for this task and marked for deletion anyway.
+This alternative subsetting operates for the j-direction only and works by optionally looking for and
+using a global file attribute (named: \np{open\_ocean\_jstart}) to determine the starting j-row for input.
+The use of this option is best explained with an example:
+consider an ORCA1 configuration using the extended grid bathymetry and coordinate files:
+\vspace{-10pt}
+\ifile{eORCA1\_bathymetry\_v2}
+\ifile{eORCA1\_coordinates}
+\noindent These files define a horizontal domain of 362x332.
+Assuming the first row with open ocean wet points in the non-isf bathymetry for this set is row 42
+(\fortran indexing) then the formally correct setting for \np{open\_ocean\_jstart} is 41.
+Using this value as the first row to be read will result in a 362x292 domain which is the same size as
+the original ORCA1 domain.
+Thus the extended coordinates and bathymetry files can be used with all the original input files for ORCA1 if
+the ice cavities are not active (\np{ln\_isfcav = .false.}).
+Full instructions for achieving this are:
+\noindent Add the new attribute to any input files requiring a j-row offset, i.e:
+\vspace{-10pt}
+The extended grids for use with the under-shelf ice cavities will result in redundant rows
+around Antarctica if the ice cavities are not active.  A simple mechanism for subsetting
+input files associated with the extended domains has been implemented to avoid the need to
+maintain different sets of input fields for use with or without active ice cavities.  This
+subsetting operates for the j-direction only and works by optionally looking for and using
+a global file attribute (named: \np{open\_ocean\_jstart}) to determine the starting j-row
+for input.  The use of this option is best explained with an example:
+\medskip
+\noindent Consider an ORCA1
+configuration using the extended grid domain configuration file: \ifile{eORCA1\_domcfg.nc}
+This file define a horizontal domain of 362x332.  The first row with
+open ocean wet points in the non-isf bathymetry for this set is row 42 (\fortran\ indexing)
+then the formally correct setting for \np{open\_ocean\_jstart} is 41.  Using this value as
+the first row to be read will result in a 362x292 domain which is the same size as the
+original ORCA1 domain.  Thus the extended domain configuration file can be used with all
+the original input files for ORCA1 if the ice cavities are not active (\np{ln\_isfcav =
+.false.}).  Full instructions for achieving this are:
+\begin{itemize}
+\item  Add the new attribute to any input files requiring a j-row offset, i.e:
 \begin{cmds}
+ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_coordinates.nc
+ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_bathymetry_v2.nc
+ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_domcfg.nc
 \end{cmds}
+\noindent Add the logical switch to \ngn{namcfg} in the configuration namelist and set true:
+%--------------------------------------------namcfg--------------------------------------------------------
+\nlst{namcfg}
+%--------------------------------------------------------------------------------------------------------------
+\noindent Note the j-size of the global domain is the (extended j-size minus \np{open\_ocean\_jstart} + 1 ) and
+this must match the size of all datasets other than bathymetry and coordinates currently.
+However the option can be extended to any global, 2D and 3D, netcdf, input field by adding the:
+\vspace{-10pt}
+\item Add the logical switch \np{ln\_use\_jattr} to \nam{cfg} in the configuration
+namelist (if it is not already there) and set \np{.true.}
+\end{itemize}
+\noindent Note that with this option, the j-size of the global domain is (extended
+j-size minus \np{open\_ocean\_jstart} + 1 ) and this must match the \texttt{jpjglo} value
+for the configuration. This means an alternative version of \ifile{eORCA1\_domcfg.nc} must
+be created for when \np{ln\_use\_jattr} is active. The \texttt{ncap2} tool provides a
+convenient way of achieving this:
+\begin{cmds}
+ncap2 -s 'jpjglo=292' eORCA1_domcfg.nc nORCA1_domcfg.nc
+\end{cmds}
+The domain configuration file is unique in this respect since it also contains the value of \jp{jpjglo}
+that is read and used by the model.
+Any other global, 2D and 3D, netcdf, input field can be prepared for use in a reduced domain by adding the
+\texttt{open\_ocean\_jstart} attribute to the file's global attributes.
+In particular this is true for any field that is read by \NEMO\ using the following optional argument to
+the appropriate call to \np{iom\_get}.
 \begin{forlines}
 lrowattr=ln_use_jattr
 \end{forlines}
+optional argument to the appropriate \np{iom\_get} call and the \np{open\_ocean\_jstart} attribute to
+the corresponding input files.
+It remains the users responsibility to set \np{jpjdta} and \np{jpjglo} values in
+the \np{namelist\_cfg} file according to their needs.
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht]
+  \begin{center}
+    \includegraphics[width=0.90\textwidth]{Fig_LBC_zoom}
+    \caption{
+      \protect\label{fig:LBC_zoom}
+      Position of a model domain compared to the data input domain when the zoom functionality is used.
+    }
+  \end{center}
+\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+Currently, only the domain configuration variables make use of this optional argument so
+this facility is of little practical use except for tests where no other external input
+files are needed or you wish to use an extended domain configuration with inputs from
+earlier, non-extended configurations. Alternatively, it should be possible to exclude
+empty rows for extended domain, forced ocean runs using interpolation on the fly, by
+adding the optional argument to \texttt{iom\_get} calls for the weights and initial
+conditions. Experimenting with this remains an exercise for the user.
 % ================================================================
 % Accuracy and Reproducibility
 % ================================================================
+\section{Accuracy and reproducibility (\protect\mdl{lib\_fortran})}
+\section[Accuracy and reproducibility (\textit{lib\_fortran.F90})]
+{Accuracy and reproducibility (\protect\mdl{lib\_fortran})}
 \label{sec:MISC_fortran}
+\subsection{Issues with intrinsinc SIGN function (\protect\key{nosignedzero})}
+\subsection[Issues with intrinsinc SIGN function (\texttt{\textbf{key\_nosignedzero}})]
+{Issues with intrinsinc SIGN function (\protect\key{nosignedzero})}
 \label{subsec:MISC_sign}
 The SIGN(A, B) is the \fortran intrinsic function delivers the magnitude of A with the sign of B.
+The SIGN(A, B) is the \fortran\ intrinsic function delivers the magnitude of A with the sign of B.
 For example, SIGN(-3.0,2.0) has the value 3.0.
 The problematic case is when the second argument is zero, because, on platforms that support IEEE arithmetic,
 …
 and the processor is capable of distinguishing between positive and negative zero,
 and B is negative real zero.
 Then SIGN delivers a negative result where, under \fninety rules, it used to return a positive result.
+Then SIGN delivers a negative result where, under \fninety\ rules, it used to return a positive result.
 This change may be especially sensitive for the ice model,
 so we overwrite the intrinsinc function with our own function simply performing :   \\
 …
 The numerical reproducibility of simulations on distributed memory parallel computers is a critical issue.
 In particular, within NEMO global summation of distributed arrays is most susceptible to rounding errors,
+In particular, within \NEMO\ global summation of distributed arrays is most susceptible to rounding errors,
 and their propagation and accumulation cause uncertainty in final simulation reproducibility on
 different numbers of processors.
 To avoid so, based on \citet{He_Ding_JSC01} review of different technics,
+To avoid so, based on \citet{he.ding_JS01} review of different technics,
 we use a so called self-compensated summation method.
 The idea is to estimate the roundoff error, store it in a buffer, and then add it back in the next addition.
+The idea is to estimate the roundoff error, store it in a buffer, and then add it back in the next addition.
 Suppose we need to calculate $b = a_1 + a_2 + a_3$.
 …
 The self-compensated summation method should be used in all summation in i- and/or j-direction.
 See \mdl{closea} module for an example.
 Note also that this implementation may be sensitive to the optimization level.
+Note also that this implementation may be sensitive to the optimization level.
 \subsection{MPP scalability}
 …
 This alternative method should give identical results to the default \textsc{ALLGATHER} method and
 is recommended for large values of \np{jpni}.
 The new method is activated by setting \np{ln\_nnogather} to be true ({\bf nammpp}).
+The new method is activated by setting \np{ln\_nnogather} to be true (\nam{mpp}).
 The reproducibility of results using the two methods should be confirmed for each new,
 non-reference configuration.
 …
 %--------------------------------------------namctl-------------------------------------------------------
+\nlst{namctl}
+\begin{listing}
+  \nlst{namctl}
+  \caption{\texttt{namctl}}
+  \label{lst:namctl}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------------
 Options are defined through the  \ngn{namctl} namelist variables.
+Options are defined through the  \nam{ctl} namelist variables.
 \subsection{Vector optimisation}
 …
 This is very a very efficient way to increase the length of vector calculations and thus
 to speed up the model on vector computers.
 % Add here also one word on NPROMA technique that has been found useless, since compiler have made significant progress during the last decade.
 % Add also one word on NEC specific optimisation (Novercheck option for example)
 \subsection{Control print}
 …
 at a suitably long interval. For example:
 \begin{verbatim}
+\begin{verbatim}
        sn_cfctl%ptimincr  = 25
 \end{verbatim}
 will carry out the global communications and write the information every 25 timesteps. This
+will carry out the global communications and write the information every 25 timesteps. This
 increment also applies to the time.step file which is otherwise updated every timestep.

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_model_basics.tex

-                      r10544
+                      r11564
 \documentclass[../main/NEMO_manual]{subfiles}
 …
 % ================================================================
 \chapter{Model Basics}
+\label{chap:PE}
+\minitoc
+\label{chap:MB}
+\chaptertoc
 \newpage
 …
 % ================================================================
 \section{Primitive equations}
 \label{sec:PE_PE}
 % -------------------------------------------------------------------------------------------------------------
 %        Vector Invariant Formulation
+\label{sec:MB_PE}
+% -------------------------------------------------------------------------------------------------------------
+%        Vector Invariant Formulation
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Vector invariant formulation}
 \label{subsec:PE_Vector}
+\label{subsec:MB_PE_vector}
 The ocean is a fluid that can be described to a good approximation by the primitive equations,
 \ie the Navier-Stokes equations along with a nonlinear equation of state which
+\ie\ the Navier-Stokes equations along with a nonlinear equation of state which
 couples the two active tracers (temperature and salinity) to the fluid velocity,
 plus the following additional assumptions made from scale considerations:
 …
 \begin{enumerate}
 \item
+  \textit{spherical earth approximation}: the geopotential surfaces are assumed to be spheres so that
+  gravity (local vertical) is parallel to the earth's radius
+  \textit{spherical Earth approximation}: the geopotential surfaces are assumed to be oblate spheriods
+  that follow the Earth's bulge; these spheroids are approximated by spheres with
+  gravity locally vertical (parallel to the Earth's radius) and independent of latitude
+  \citep[][section 2]{white.hoskins.ea_QJRMS05}.
 \item
   \textit{thin-shell approximation}: the ocean depth is neglected compared to the earth's radius
 …
   the buoyancy force
   \begin{equation}
     \label{eq:PE_eos}
+    \label{eq:MB_PE_eos}
     \rho = \rho \ (T,S,p)
   \end{equation}
 …
   convective processes must be parameterized instead)
   \begin{equation}
     \label{eq:PE_hydrostatic}
+    \label{eq:MB_PE_hydrostatic}
     \pd[p]{z} = - \rho \ g
   \end{equation}
 …
   is assumed to be zero.
   \begin{equation}
     \label{eq:PE_continuity}
+    \label{eq:MB_PE_continuity}
     \nabla \cdot \vect U = 0
   \end{equation}
+ \item
+  \textit{Neglect of additional Coriolis terms}: the Coriolis terms that vary with the cosine of latitude are neglected.
+  These terms may be non-negligible where the Brunt-Vaisala frequency $N$ is small, either in the deep ocean or
+  in the sub-mesoscale motions of the mixed layer, or near the equator \citep[][section 1]{white.hoskins.ea_QJRMS05}.
+  They can be consistently included as part of the ocean dynamics \citep[][section 3(d)]{white.hoskins.ea_QJRMS05} and are
+  retained in the MIT ocean model.
 \end{enumerate}
 Because the gravitational force is so dominant in the equations of large-scale motions,
 it is useful to choose an orthogonal set of unit vectors $(i,j,k)$ linked to the earth such that
+it is useful to choose an orthogonal set of unit vectors $(i,j,k)$ linked to the Earth such that
 $k$ is the local upward vector and $(i,j)$ are two vectors orthogonal to $k$,
 \ie tangent to the geopotential surfaces.
+\ie\ tangent to the geopotential surfaces.
 Let us define the following variables: $\vect U$ the vector velocity, $\vect U = \vect U_h + w \, \vect k$
 (the subscript $h$ denotes the local horizontal vector, \ie over the $(i,j)$ plane),
+(the subscript $h$ denotes the local horizontal vector, \ie\ over the $(i,j)$ plane),
 $T$ the potential temperature, $S$ the salinity, $\rho$ the \textit{in situ} density.
 The vector invariant form of the primitive equations in the $(i,j,k)$ vector system provides
 the following equations:
 \begin{subequations}
   \label{eq:PE}
+  \label{eq:MB_PE}
   \begin{gather}
     \intertext{$-$ the momentum balance}
     \label{eq:PE_dyn}
+    \label{eq:MB_PE_dyn}
     \pd[\vect U_h]{t} = - \lt[ (\nabla \times \vect U) \times \vect U + \frac{1}{2} \nabla \lt( \vect U^2 \rt) \rt]_h
                         - f \; k \times \vect U_h - \frac{1}{\rho_o} \nabla_h p
                         + \vect D^{\vect U} + \vect F^{\vect U} \\
     \intertext{$-$ the heat and salt conservation equations}
     \label{eq:PE_tra_T}
+    \label{eq:MB_PE_tra_T}
     \pd[T]{t} = - \nabla \cdot (T \ \vect U) + D^T + F^T \\
     \label{eq:PE_tra_S}
+    \label{eq:MB_PE_tra_S}
     \pd[S]{t} = - \nabla \cdot (S \ \vect U) + D^S + F^S
   \end{gather}
 …
 where $\nabla$ is the generalised derivative vector operator in $(i,j,k)$ directions, $t$ is the time,
 $z$ is the vertical coordinate, $\rho$ is the \textit{in situ} density given by the equation of state
 (\autoref{eq:PE_eos}), $\rho_o$ is a reference density, $p$ the pressure,
+(\autoref{eq:MB_PE_eos}), $\rho_o$ is a reference density, $p$ the pressure,
 $f = 2 \vect \Omega \cdot k$ is the Coriolis acceleration
 (where $\vect \Omega$ is the Earth's angular velocity vector), and $g$ is the gravitational acceleration.
 $\vect D^{\vect U}$, $D^T$ and $D^S$ are the parameterisations of small-scale physics for momentum,
 temperature and salinity, and $\vect F^{\vect U}$, $F^T$ and $F^S$ surface forcing terms.
 Their nature and formulation are discussed in \autoref{sec:PE_zdf_ldf} and \autoref{subsec:PE_boundary_condition}.
+Their nature and formulation are discussed in \autoref{sec:MB_zdf_ldf} and \autoref{subsec:MB_boundary_condition}.
 % -------------------------------------------------------------------------------------------------------------
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Boundary conditions}
 \label{subsec:PE_boundary_condition}
+\label{subsec:MB_boundary_condition}
 An ocean is bounded by complex coastlines, bottom topography at its base and
 an air-sea or ice-sea interface at its top.
 These boundaries can be defined by two surfaces, $z = - H(i,j)$ and $z = \eta(i,j,k,t)$,
+where $H$ is the depth of the ocean bottom and $\eta$ is the height of the sea surface.
+Both $H$ and $\eta$ are usually referenced to a given surface, $z = 0$, chosen as a mean sea surface
+(\autoref{fig:ocean_bc}).
+where $H$ is the depth of the ocean bottom and $\eta$ is the height of the sea surface
+(discretisation can introduce additional artificial ``side-wall'' boundaries).
+Both $H$ and $\eta$ are referenced to a surface of constant geopotential (\ie\ a mean sea surface height) on which $z = 0$.
+(\autoref{fig:MB_ocean_bc}).
 Through these two boundaries, the ocean can exchange fluxes of heat, fresh water, salt, and momentum with
 the solid earth, the continental margins, the sea ice and the atmosphere.
 …
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!ht]
+  \begin{center}
+    \includegraphics[]{Fig_I_ocean_bc}
+    \caption{
+      \protect\label{fig:ocean_bc}
+      The ocean is bounded by two surfaces, $z = - H(i,j)$ and $z = \eta(i,j,t)$,
+      where $H$ is the depth of the sea floor and $\eta$ the height of the sea surface.
+      Both $H$ and $\eta$ are referenced to $z = 0$.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_I_ocean_bc}
+  \caption[Ocean boundary conditions]{
+    The ocean is bounded by two surfaces, $z = - H(i,j)$ and $z = \eta(i,j,t)$,
+    where $H$ is the depth of the sea floor and $\eta$ the height of the sea surface.
+    Both $H$ and $\eta$ are referenced to $z = 0$.}
+  \label{fig:MB_ocean_bc}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
   \footnote{
     In fact, it has been shown that the heat flux associated with the solid Earth cooling
     (\ie the geothermal heating) is not negligible for the thermohaline circulation of the world ocean
+    (\ie\ the geothermal heating) is not negligible for the thermohaline circulation of the world ocean
     (see \autoref{subsec:TRA_bbc}).
   }.
   The boundary condition is thus set to no flux of heat and salt across solid boundaries.
   For momentum, the situation is different. There is no flow across solid boundaries,
   \ie the velocity normal to the ocean bottom and coastlines is zero (in other words,
+  \ie\ the velocity normal to the ocean bottom and coastlines is zero (in other words,
   the bottom velocity is parallel to solid boundaries). This kinematic boundary condition
   can be expressed as:
   \begin{equation}
     \label{eq:PE_w_bbc}
+    \label{eq:MB_w_bbc}
     w = - \vect U_h \cdot \nabla_h (H)
   \end{equation}
 …
   It must be parameterized in terms of turbulent fluxes using bottom and/or lateral boundary conditions.
   Its specification depends on the nature of the physical parameterisation used for
   $\vect D^{\vect U}$ in \autoref{eq:PE_dyn}.
   It is discussed in \autoref{eq:PE_zdf}.% and Chap. III.6 to 9.
+  $\vect D^{\vect U}$ in \autoref{eq:MB_PE_dyn}.
+  It is discussed in \autoref{eq:MB_zdf}.% and Chap. III.6 to 9.
 \item[Atmosphere - ocean interface:]
   the kinematic surface condition plus the mass flux of fresh water PE (the precipitation minus evaporation budget)
   leads to:
   \[
     % \label{eq:PE_w_sbc}
+    % \label{eq:MB_w_sbc}
     w = \pd[\eta]{t} + \lt. \vect U_h \rt|_{z = \eta} \cdot \nabla_h (\eta) + P - E
   \]
 …
 % ================================================================
 \section{Horizontal pressure gradient}
 \label{sec:PE_hor_pg}
+\label{sec:MB_hor_pg}
 % -------------------------------------------------------------------------------------------------------------
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Pressure formulation}
 \label{subsec:PE_p_formulation}
+\label{subsec:MB_p_formulation}
 The total pressure at a given depth $z$ is composed of a surface pressure $p_s$ at
 a reference geopotential surface ($z = 0$) and a hydrostatic pressure $p_h$ such that:
 $p(i,j,k,t) = p_s(i,j,t) + p_h(i,j,k,t)$.
 The latter is computed by integrating (\autoref{eq:PE_hydrostatic}),
 assuming that pressure in decibars can be approximated by depth in meters in (\autoref{eq:PE_eos}).
+The latter is computed by integrating (\autoref{eq:MB_PE_hydrostatic}),
+assuming that pressure in decibars can be approximated by depth in meters in (\autoref{eq:MB_PE_eos}).
 The hydrostatic pressure is then given by:
 \[
   % \label{eq:PE_pressure}
+  % \label{eq:MB_pressure}
   p_h (i,j,z,t) = \int_{\varsigma = z}^{\varsigma = 0} g \; \rho (T,S,\varsigma) \; d \varsigma
 \]
 …
 The flow is barotropic and the surface moves up and down with gravity as the restoring force.
 The phase speed of such waves is high (some hundreds of metres per second) so that
 the time step would have to be very short if they were present in the model.
+the time step has to be very short when they are present in the model.
 The latter strategy filters out these waves since the rigid lid approximation implies $\eta = 0$,
 \ie the sea surface is the surface $z = 0$.
+\ie\ the sea surface is the surface $z = 0$.
 This well known approximation increases the surface wave speed to infinity and
 modifies certain other longwave dynamics (\eg barotropic Rossby or planetary waves).
+modifies certain other longwave dynamics (\eg\ barotropic Rossby or planetary waves).
 The rigid-lid hypothesis is an obsolescent feature in modern OGCMs.
 It has been available until the release 3.1 of \NEMO, and it has been removed in release 3.2 and followings.
 Only the free surface formulation is now described in the this document (see the next sub-section).
+Only the free surface formulation is now described in this document (see the next sub-section).
 % -------------------------------------------------------------------------------------------------------------
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Free surface formulation}
 \label{subsec:PE_free_surface}
+\label{subsec:MB_free_surface}
 In the free surface formulation, a variable $\eta$, the sea-surface height,
 is introduced which describes the shape of the air-sea interface.
 This variable is solution of a prognostic equation which is established by forming the vertical average of
 the kinematic surface condition (\autoref{eq:PE_w_bbc}):
+the kinematic surface condition (\autoref{eq:MB_w_bbc}):
 \begin{equation}
   \label{eq:PE_ssh}
+  \label{eq:MB_ssh}
   \pd[\eta]{t} = - D + P - E \quad \text{where} \quad D = \nabla \cdot \lt[ (H + \eta) \; \overline{U}_h \, \rt]
 \end{equation}
 and using (\autoref{eq:PE_hydrostatic}) the surface pressure is given by: $p_s = \rho \, g \, \eta$.
+and using (\autoref{eq:MB_PE_hydrostatic}) the surface pressure is given by: $p_s = \rho \, g \, \eta$.
 Allowing the air-sea interface to move introduces the external gravity waves (EGWs) as
 a class of solution of the primitive equations.
 These waves are barotropic because of hydrostatic assumption, and their phase speed is quite high.
+These waves are barotropic (\ie\ nearly independent of depth) and their phase speed is quite high.
 Their time scale is short with respect to the other processes described by the primitive equations.
 …
 the baroclinic structure of the ocean (internal waves) possibly in shallow seas,
 then a non linear free surface is the most appropriate.
 This means that no approximation is made in \autoref{eq:PE_ssh} and that
+This means that no approximation is made in \autoref{eq:MB_ssh} and that
 the variation of the ocean volume is fully taken into account.
 Note that in order to study the fast time scales associated with EGWs it is necessary to
 …
 not altering the slow barotropic Rossby waves.
 If further, an approximative conservation of heat and salt contents is sufficient for the problem solved,
 then it is sufficient to solve a linearized version of \autoref{eq:PE_ssh},
 which still allows to take into account freshwater fluxes applied at the ocean surface \citep{Roullet_Madec_JGR00}.
+then it is sufficient to solve a linearized version of \autoref{eq:MB_ssh},
+which still allows to take into account freshwater fluxes applied at the ocean surface \citep{roullet.madec_JGR00}.
 Nevertheless, with the linearization, an exact conservation of heat and salt contents is lost.
 The filtering of EGWs in models with a free surface is usually a matter of discretisation of
 the temporal derivatives,
 using a split-explicit method \citep{Killworth_al_JPO91, Zhang_Endoh_JGR92} or
 the implicit scheme \citep{Dukowicz1994} or
 the addition of a filtering force in the momentum equation \citep{Roullet_Madec_JGR00}.
 With the present release, \NEMO offers the choice between
+using a split-explicit method \citep{killworth.webb.ea_JPO91, zhang.endoh_JGR92} or
+the implicit scheme \citep{dukowicz.smith_JGR94} or
+the addition of a filtering force in the momentum equation \citep{roullet.madec_JGR00}.
+With the present release, \NEMO\  offers the choice between
 an explicit free surface (see \autoref{subsec:DYN_spg_exp}) or
 a split-explicit scheme strongly inspired the one proposed by \citet{Shchepetkin_McWilliams_OM05}
+a split-explicit scheme strongly inspired the one proposed by \citet{shchepetkin.mcwilliams_OM05}
 (see \autoref{subsec:DYN_spg_ts}).
 …
 % ================================================================
 \section{Curvilinear \textit{z-}coordinate system}
 \label{sec:PE_zco}
+\label{sec:MB_zco}
 % -------------------------------------------------------------------------------------------------------------
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Tensorial formalism}
 \label{subsec:PE_tensorial}
+\label{subsec:MB_tensorial}
 In many ocean circulation problems, the flow field has regions of enhanced dynamics
 (\ie surface layers, western boundary currents, equatorial currents, or ocean fronts).
+(\ie\ surface layers, western boundary currents, equatorial currents, or ocean fronts).
 The representation of such dynamical processes can be improved by
 specifically increasing the model resolution in these regions.
 …
 cannot be easily treated in a global model without filtering.
 A solution consists of introducing an appropriate coordinate transformation that
 shifts the singular point onto land \citep{Madec_Imbard_CD96, Murray_JCP96}.
+shifts the singular point onto land \citep{madec.imbard_CD96, murray_JCP96}.
 As a consequence, it is important to solve the primitive equations in various curvilinear coordinate systems.
 An efficient way of introducing an appropriate coordinate transform can be found when using a tensorial formalism.
 …
 Ocean modellers mainly use three-dimensional orthogonal grids on the sphere (spherical earth approximation),
 with preservation of the local vertical. Here we give the simplified equations for this particular case.
 The general case is detailed by \citet{Eiseman1980} in their survey of the conservation laws of fluid dynamics.
+The general case is detailed by \citet{eiseman.stone_SR80} in their survey of the conservation laws of fluid dynamics.
 Let $(i,j,k)$ be a set of orthogonal curvilinear coordinates on
 …
 $(i,j,k)$ linked to the earth such that
 $k$ is the local upward vector and $(i,j)$ are two vectors orthogonal to $k$,
 \ie along geopotential surfaces (\autoref{fig:referential}).
+\ie\ along geopotential surfaces (\autoref{fig:MB_referential}).
 Let $(\lambda,\varphi,z)$ be the geographical coordinate system in which a position is defined by
 the latitude $\varphi(i,j)$, the longitude $\lambda(i,j)$ and
 the distance from the centre of the earth $a + z(k)$ where $a$ is the earth's radius and
 $z$ the altitude above a reference sea level (\autoref{fig:referential}).
+$z$ the altitude above a reference sea level (\autoref{fig:MB_referential}).
 The local deformation of the curvilinear coordinate system is given by $e_1$, $e_2$ and $e_3$,
 the three scale factors:
 \begin{equation}
   \label{eq:scale_factors}
+  \label{eq:MB_scale_factors}
   \begin{aligned}
     e_1 &= (a + z) \lt[ \lt( \pd[\lambda]{i} \cos \varphi \rt)^2 + \lt( \pd[\varphi]{i} \rt)^2 \rt]^{1/2} \\
 …
 % >>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!tb]
+  \begin{center}
+    \includegraphics[]{Fig_I_earth_referential}
+    \caption{
+      \protect\label{fig:referential}
+      the geographical coordinate system $(\lambda,\varphi,z)$ and the curvilinear
+      coordinate system $(i,j,k)$.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_I_earth_referential}
+  \caption[Geographical and curvilinear coordinate systems]{
+    the geographical coordinate system $(\lambda,\varphi,z)$ and the curvilinear
+    coordinate system $(i,j,k)$.}
+  \label{fig:MB_referential}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 Since the ocean depth is far smaller than the earth's radius, $a + z$, can be replaced by $a$ in
 (\autoref{eq:scale_factors}) (thin-shell approximation).
+(\autoref{eq:MB_scale_factors}) (thin-shell approximation).
 The resulting horizontal scale factors $e_1$, $e_2$  are independent of $k$ while
 the vertical scale factor is a single function of $k$ as $k$ is parallel to $z$.
 The scalar and vector operators that appear in the primitive equations
 (\autoref{eq:PE_dyn} to \autoref{eq:PE_eos}) can be written in the tensorial form,
+(\autoref{eq:MB_PE_dyn} to \autoref{eq:MB_PE_eos}) can then be written in the tensorial form,
 invariant in any orthogonal horizontal curvilinear coordinate system transformation:
 \begin{subequations}
   % \label{eq:PE_discrete_operators}
+  % \label{eq:MB_discrete_operators}
   \begin{gather}
     \label{eq:PE_grad}
+    \label{eq:MB_grad}
     \nabla q =   \frac{1}{e_1} \pd[q]{i} \; \vect i
                + \frac{1}{e_2} \pd[q]{j} \; \vect j
                + \frac{1}{e_3} \pd[q]{k} \; \vect k \\
     \label{eq:PE_div}
+    \label{eq:MB_div}
     \nabla \cdot \vect A =   \frac{1}{e_1 \; e_2} \lt[ \pd[(e_2 \; a_1)]{\partial i} + \pd[(e_1 \; a_2)]{j} \rt]
                            + \frac{1}{e_3} \lt[ \pd[a_3]{k} \rt]
   \end{gather}
   \begin{multline}
     \label{eq:PE_curl}
+    \label{eq:MB_curl}
       \nabla \times \vect{A} =   \lt[ \frac{1}{e_2} \pd[a_3]{j} - \frac{1}{e_3} \pd[a_2]{k}   \rt] \vect i \\
                                + \lt[ \frac{1}{e_3} \pd[a_1]{k} - \frac{1}{e_1} \pd[a_3]{i}   \rt] \vect j \\
 …
   \end{multline}
   \begin{gather}
     \label{eq:PE_lap}
+    \label{eq:MB_lap}
     \Delta q = \nabla \cdot (\nabla q) \\
     \label{eq:PE_lap_vector}
+    \label{eq:MB_lap_vector}
     \Delta \vect A = \nabla (\nabla \cdot \vect A) - \nabla \times (\nabla \times \vect A)
   \end{gather}
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Continuous model equations}
 \label{subsec:PE_zco_Eq}
+\label{subsec:MB_zco_Eq}
 In order to express the Primitive Equations in tensorial formalism,
 it is necessary to compute the horizontal component of the non-linear and viscous terms of the equation using
 \autoref{eq:PE_grad}) to \autoref{eq:PE_lap_vector}.
+\autoref{eq:MB_grad}) to \autoref{eq:MB_lap_vector}.
 Let us set $\vect U = (u,v,w) = \vect U_h + w \; \vect k $, the velocity in the $(i,j,k)$ coordinates system and
 define the relative vorticity $\zeta$ and the divergence of the horizontal velocity field $\chi$, by:
 \begin{gather}
   \label{eq:PE_curl_Uh}
+  \label{eq:MB_curl_Uh}
   \zeta = \frac{1}{e_1 e_2} \lt[ \pd[(e_2 \, v)]{i} - \pd[(e_1 \, u)]{j} \rt] \\
   \label{eq:PE_div_Uh}
+  \label{eq:MB_div_Uh}
   \chi  = \frac{1}{e_1 e_2} \lt[ \pd[(e_2 \, u)]{i} + \pd[(e_1 \, v)]{j} \rt]
 \end{gather}
 Using the fact that the horizontal scale factors $e_1$ and $e_2$ are independent of $k$ and that
+Using again the fact that the horizontal scale factors $e_1$ and $e_2$ are independent of $k$ and that
 $e_3$  is a function of the single variable $k$,
 $NLT$ the nonlinear term of \autoref{eq:PE_dyn} can be transformed as follows:
+$NLT$ the nonlinear term of \autoref{eq:MB_PE_dyn} can be transformed as follows:
 \begin{alignat*}{2}
   &NLT &=   &\lt[ (\nabla \times {\vect U}) \times {\vect U} + \frac{1}{2} \nabla \lt( {\vect U}^2 \rt) \rt]_h \\
 …
 \end{alignat*}
 The last term of the right hand side is obviously zero, and thus the nonlinear term of
 \autoref{eq:PE_dyn} is written in the $(i,j,k)$ coordinate system:
+\autoref{eq:MB_PE_dyn} is written in the $(i,j,k)$ coordinate system:
 \begin{equation}
   \label{eq:PE_vector_form}
+  \label{eq:MB_vector_form}
   NLT =   \zeta \; \vect k \times \vect U_h + \frac{1}{2} \nabla_h \lt( \vect U_h^2 \rt)
         + \frac{1}{e_3} w \pd[\vect U_h]{k}
 …
 This is the so-called \textit{vector invariant form} of the momentum advection term.
 For some purposes, it can be advantageous to write this term in the so-called flux form,
 \ie to write it as the divergence of fluxes.
 For example, the first component of \autoref{eq:PE_vector_form} (the $i$-component) is transformed as follows:
+\ie\ to write it as the divergence of fluxes.
+For example, the first component of \autoref{eq:MB_vector_form} (the $i$-component) is transformed as follows:
 \begin{alignat*}{2}
   &NLT_i &= &- \zeta \; v + \frac{1}{2 \; e_1} \pd[ (u^2 + v^2) ]{i} + \frac{1}{e_3} w \ \pd[u]{k} \\
 …
   &      &= &\nabla \cdot (\vect U \, u) - (\nabla \cdot \vect U) \ u
             + \frac{1}{e_1 e_2} \lt( -v^2 \pd[e_2]{i} + u v \, \pd[e_1]{j} \rt) \\
   \intertext{as $\nabla \cdot {\vect U} \; = 0$ (incompressibility) it comes:}
+  \intertext{as $\nabla \cdot {\vect U} \; = 0$ (incompressibility) it becomes:}
   &      &= &\, \nabla \cdot (\vect U \, u) + \frac{1}{e_1 e_2} \lt( v \; \pd[e_2]{i} - u \; \pd[e_1]{j} \rt) (-v)
 \end{alignat*}
 …
 The flux form of the momentum advection term is therefore given by:
 \begin{equation}
   \label{eq:PE_flux_form}
+  \label{eq:MB_flux_form}
   NLT =   \nabla \cdot \lt(
     \begin{array}{*{20}c}
 …
 the first one is expressed as the divergence of momentum fluxes (hence the flux form name given to this formulation)
 and the second one is due to the curvilinear nature of the coordinate system used.
 The latter is called the \textit{metric} term and can be viewed as a modification of the Coriolis parameter:
+The latter is called the \textit{metric} term and can be viewed as a modification of the Coriolis parameter:
 \[
   % \label{eq:PE_cor+metric}
+  % \label{eq:MB_cor+metric}
   f \to f + \frac{1}{e_1 e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt)
 \]
 Note that in the case of geographical coordinate,
 \ie when $(i,j) \to (\lambda,\varphi)$ and $(e_1,e_2) \to (a \, \cos \varphi,a)$,
+\ie\ when $(i,j) \to (\lambda,\varphi)$ and $(e_1,e_2) \to (a \, \cos \varphi,a)$,
 we recover the commonly used modification of the Coriolis parameter $f \to f + (u / a) \tan \varphi$.
 …
   \textbf{Vector invariant form of the momentum equations}:
   \begin{equation}
     \label{eq:PE_dyn_vect}
+    \label{eq:MB_dyn_vect}
     \begin{split}
     % \label{eq:PE_dyn_vect_u}
+    % \label{eq:MB_dyn_vect_u}
       \pd[u]{t} = &+ (\zeta + f) \, v - \frac{1}{2 e_1} \pd[]{i} (u^2 + v^2)
                    - \frac{1}{e_3} w \pd[u]{k} - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) \\
                   &+ D_u^{\vect U} + F_u^{\vect U} \\
       \pd[v]{t} = &- (\zeta + f) \, u - \frac{1}{2 e_2} \pd[]{j} (u^2 + v^2)
                    - \frac{1}{e_3} w \pd[v]{k} - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) \\
+                   - \frac{1}{e_3} w \pd[v]{k} - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) \\
                   &+ D_v^{\vect U} + F_v^{\vect U}
     \end{split}
 …
 \item
   \textbf{flux form of the momentum equations}:
   % \label{eq:PE_dyn_flux}
+  % \label{eq:MB_dyn_flux}
   \begin{multline*}
     % \label{eq:PE_dyn_flux_u}
+    % \label{eq:MB_dyn_flux_u}
     \pd[u]{t} = + \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, v \\
                 - \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, u)]{i} + \pd[(e_1 \, v \, u)]{j} \rt) \\
 …
   \end{multline*}
   \begin{multline*}
     % \label{eq:PE_dyn_flux_v}
+    % \label{eq:MB_dyn_flux_v}
     \pd[v]{t} = - \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, u \\
                 + \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, v)]{i} + \pd[(e_1 \, v \, v)]{j} \rt) \\
+                - \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, v)]{i} + \pd[(e_1 \, v \, v)]{j} \rt) \\
                 - \frac{1}{e_3} \pd[(w \, v)]{k} - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt)
                 + D_v^{\vect U} + F_v^{\vect U}
   \end{multline*}
   where $\zeta$, the relative vorticity, is given by \autoref{eq:PE_curl_Uh} and $p_s$, the surface pressure,
+  where $\zeta$, the relative vorticity, is given by \autoref{eq:MB_curl_Uh} and $p_s$, the surface pressure,
   is given by:
   \[
   % \label{eq:PE_spg}
+  % \label{eq:MB_spg}
     p_s = \rho \,g \, \eta
   \]
   with $\eta$ is solution of \autoref{eq:PE_ssh}.
+  and $\eta$ is the solution of \autoref{eq:MB_ssh}.
   The vertical velocity and the hydrostatic pressure are diagnosed from the following equations:
   \[
   % \label{eq:w_diag}
     \pd[w]{k} = - \chi \; e_3 \qquad
   % \label{eq:hp_diag}
+  % \label{eq:MB_w_diag}
+    \pd[w]{k} = - \chi \; e_3 \qquad
+  % \label{eq:MB_hp_diag}
     \pd[p_h]{k} = - \rho \; g \; e_3
   \]
+  where the divergence of the horizontal velocity, $\chi$ is given by \autoref{eq:PE_div_Uh}.
+\item \textit{tracer equations}:
+  \[
+    %\label{eq:S}
+    \pd[T]{t} = - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 T \, u)]{i} + \pd[(e_1 T \, v)]{j} \rt]
+  where the divergence of the horizontal velocity, $\chi$ is given by \autoref{eq:MB_div_Uh}.
+\item
+  \textbf{tracer equations}:
+  \begin{equation}
+  \begin{split}
+    \pd[T]{t} = & - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 T \, u)]{i} + \pd[(e_1 T \, v)]{j} \rt]
                 - \frac{1}{e_3} \pd[(T \, w)]{k} + D^T + F^T \\
+    %\label{eq:T}
+    \pd[S]{t} = - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 S \, u)]{i} + \pd[(e_1 S \, v)]{j} \rt]
+                - \frac{1}{e_3} \pd[(S \, w)]{k} + D^S + F^S
+    %\label{eq:rho}
+    \rho = \rho \big( T,S,z(k) \big)
+  \]
+    \pd[S]{t} = & - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 S \, u)]{i} + \pd[(e_1 S \, v)]{j} \rt]
+                - \frac{1}{e_3} \pd[(S \, w)]{k} + D^S + F^S \\
+    \rho = & \rho \big( T,S,z(k) \big)
+  \end{split}
+  \end{equation}
 \end{itemize}
 The expression of $\vect D^{U}$, $D^{S}$ and $D^{T}$ depends on the subgrid scale parameterisation used.
 It will be defined in \autoref{eq:PE_zdf}.
+It will be defined in \autoref{eq:MB_zdf}.
 The nature and formulation of $\vect F^{\vect U}$, $F^T$ and $F^S$, the surface forcing terms,
 are discussed in \autoref{chap:SBC}.
 …
 % ================================================================
 \section{Curvilinear generalised vertical coordinate system}
 \label{sec:PE_gco}
+\label{sec:MB_gco}
 The ocean domain presents a huge diversity of situation in the vertical.
 …
 Therefore, in order to represent the ocean with respect to
 the first point a space and time dependent vertical coordinate that follows the variation of the sea surface height
 \eg an \zstar-coordinate;
+\eg\ an \zstar-coordinate;
 for the second point, a space variation to fit the change of bottom topography
 \eg a terrain-following or $\sigma$-coordinate;
+\eg\ a terrain-following or $\sigma$-coordinate;
 and for the third point, one will be tempted to use a space and time dependent coordinate that
 follows the isopycnal surfaces, \eg an isopycnic coordinate.
 In order to satisfy two or more constrains one can even be tempted to mixed these coordinate systems, as in
+follows the isopycnal surfaces, \eg\ an isopycnic coordinate.
+In order to satisfy two or more constraints one can even be tempted to mixed these coordinate systems, as in
 HYCOM (mixture of $z$-coordinate at the surface, isopycnic coordinate in the ocean interior and $\sigma$ at
 the ocean bottom) \citep{Chassignet_al_JPO03} or
+the ocean bottom) \citep{chassignet.smith.ea_JPO03} or
 OPA (mixture of $z$-coordinate in vicinity the surface and steep topography areas and $\sigma$-coordinate elsewhere)
 \citep{Madec_al_JPO96} among others.
+\citep{madec.delecluse.ea_JPO96} among others.
 In fact one is totally free to choose any space and time vertical coordinate by
 introducing an arbitrary vertical coordinate :
 \begin{equation}
   \label{eq:PE_s}
+  \label{eq:MB_s}
   s = s(i,j,k,t)
 \end{equation}
 with the restriction that the above equation gives a single-valued monotonic relationship between $s$ and $k$,
 when $i$, $j$ and $t$ are held fixed.
 \autoref{eq:PE_s} is a transformation from the $(i,j,k,t)$ coordinate system with independent variables into
+\autoref{eq:MB_s} is a transformation from the $(i,j,k,t)$ coordinate system with independent variables into
 the $(i,j,s,t)$ generalised coordinate system with $s$ depending on the other three variables through
 \autoref{eq:PE_s}.
 This so-called \textit{generalised vertical coordinate} \citep{Kasahara_MWR74} is in fact
+\autoref{eq:MB_s}.
+This so-called \textit{generalised vertical coordinate} \citep{kasahara_MWR74} is in fact
 an Arbitrary Lagrangian--Eulerian (ALE) coordinate.
 Indeed, choosing an expression for $s$ is an arbitrary choice that determines
+Indeed, one has a great deal of freedom in the choice of expression for $s$. The choice determines
 which part of the vertical velocity (defined from a fixed referential) will cross the levels (Eulerian part) and
 which part will be used to move them (Lagrangian part).
 The coordinate is also sometime referenced as an adaptive coordinate \citep{Hofmeister_al_OM09},
+The coordinate is also sometime referenced as an adaptive coordinate \citep{hofmeister.burchard.ea_OM10},
 since the coordinate system is adapted in the course of the simulation.
 Its most often used implementation is via an ALE algorithm,
 in which a pure lagrangian step is followed by regridding and remapping steps,
 the later step implicitly embedding the vertical advection
 \citep{Hirt_al_JCP74, Chassignet_al_JPO03, White_al_JCP09}.
 Here we follow the \citep{Kasahara_MWR74} strategy:
 a regridding step (an update of the vertical coordinate) followed by an eulerian step with
+the latter step implicitly embedding the vertical advection
+\citep{hirt.amsden.ea_JCP74, chassignet.smith.ea_JPO03, white.adcroft.ea_JCP09}.
+Here we follow the \citep{kasahara_MWR74} strategy:
+a regridding step (an update of the vertical coordinate) followed by an Eulerian step with
 an explicit computation of vertical advection relative to the moving s-surfaces.
 %\gmcomment{
 %A key point here is that the $s$-coordinate depends on $(i,j)$ ==> horizontal pressure gradient...
 the generalized vertical coordinates used in ocean modelling are not orthogonal,
+The generalized vertical coordinates used in ocean modelling are not orthogonal,
 which contrasts with many other applications in mathematical physics.
 Hence, it is useful to keep in mind the following properties that may seem odd on initial encounter.
 …
 The horizontal velocity in ocean models measures motions in the horizontal plane,
 perpendicular to the local gravitational field.
 That is, horizontal velocity is mathematically the same regardless the vertical coordinate, be it geopotential,
+That is, horizontal velocity is mathematically the same regardless of the vertical coordinate, be it geopotential,
 isopycnal, pressure, or terrain following.
 The key motivation for maintaining the same horizontal velocity component is that
 …
 \subsection{\textit{S}-coordinate formulation}
 Starting from the set of equations established in \autoref{sec:PE_zco} for the special case $k = z$ and
+Starting from the set of equations established in \autoref{sec:MB_zco} for the special case $k = z$ and
 thus $e_3 = 1$, we introduce an arbitrary vertical coordinate $s = s(i,j,k,t)$,
 which includes $z$-, \zstar- and $\sigma$-coordinates as special cases
 ($s = z$, $s = \zstar$, and $s = \sigma = z / H$ or $ = z / \lt( H + \eta \rt)$, resp.).
 A formal derivation of the transformed equations is given in \autoref{apdx:A}.
+A formal derivation of the transformed equations is given in \autoref{apdx:SCOORD}.
 Let us define the vertical scale factor by $e_3 = \partial_s z$  ($e_3$ is now a function of $(i,j,k,t)$ ),
 and the slopes in the $(i,j)$ directions between $s$- and $z$-surfaces by:
 \begin{equation}
   \label{eq:PE_sco_slope}
+  \label{eq:MB_sco_slope}
   \sigma_1 = \frac{1}{e_1} \; \lt. \pd[z]{i} \rt|_s \quad \text{and} \quad
   \sigma_2 = \frac{1}{e_2} \; \lt. \pd[z]{j} \rt|_s
 \end{equation}
 We also introduce $\omega$, a dia-surface velocity component, defined as the velocity
+We also introduce $\omega$, a dia-surface velocity component, defined as the velocity
 relative to the moving $s$-surfaces and normal to them:
 \[
   % \label{eq:PE_sco_w}
   \omega = w - e_3 \, \pd[s]{t} - \sigma_1 \, u - \sigma_2 \, v
+  % \label{eq:MB_sco_w}
+  \omega = w -  \, \lt. \pd[z]{t} \rt|_s - \sigma_1 \, u - \sigma_2 \, v
 \]
 The equations solved by the ocean model \autoref{eq:PE} in $s$-coordinate can be written as follows
 (see \autoref{sec:A_momentum}):
+The equations solved by the ocean model \autoref{eq:MB_PE} in $s$-coordinate can be written as follows
+(see \autoref{sec:SCOORD_momentum}):
 \begin{itemize}
 \item \textbf{Vector invariant form of the momentum equation}:
   \begin{multline*}
   % \label{eq:PE_sco_u_vector}
+  % \label{eq:MB_sco_u_vector}
     \pd[u]{t} = + (\zeta + f) \, v - \frac{1}{2 \, e_1} \pd[]{i} (u^2 + v^2) - \frac{1}{e_3} \omega \pd[u]{k} \\
                 - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) + g \frac{\rho}{\rho_o} \sigma_1
+                - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) - g \frac{\rho}{\rho_o} \sigma_1
                 + D_u^{\vect U} + F_u^{\vect U}
   \end{multline*}
   \begin{multline*}
   % \label{eq:PE_sco_v_vector}
+  % \label{eq:MB_sco_v_vector}
     \pd[v]{t} = - (\zeta + f) \, u - \frac{1}{2 \, e_2} \pd[]{j}(u^2 + v^2) - \frac{1}{e_3} \omega \pd[v]{k} \\
                 - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) + g \frac{\rho}{\rho_o} \sigma_2
+                - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) - g \frac{\rho}{\rho_o} \sigma_2
                 + D_v^{\vect U} + F_v^{\vect U}
   \end{multline*}
 \item \textbf{Flux form of the momentum equation}:
   \begin{multline*}
   % \label{eq:PE_sco_u_flux}
+  % \label{eq:MB_sco_u_flux}
     \frac{1}{e_3} \pd[(e_3 \, u)]{t} = + \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, v \\
                                        - \frac{1}{e_1 \; e_2 \; e_3} \lt( \pd[(e_2 \, e_3 \, u \, u)]{i} + \pd[(e_1 \, e_3 \, v \, u)]{j} \rt) \\
                                        - \frac{1}{e_3} \pd[(\omega \, u)]{k}
                                        - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt)
                                        + g \frac{\rho}{\rho_o} \sigma_1 + D_u^{\vect U} + F_u^{\vect U}
+                                       - g \frac{\rho}{\rho_o} \sigma_1 + D_u^{\vect U} + F_u^{\vect U}
   \end{multline*}
   \begin{multline*}
   % \label{eq:PE_sco_v_flux}
+  % \label{eq:MB_sco_v_flux}
     \frac{1}{e_3} \pd[(e_3 \, v)]{t} = - \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, u \\
                                        - \frac{1}{e_1 \; e_2 \; e_3} \lt( \pd[( e_2 \; e_3 \, u \, v)]{i} + \pd[(e_1 \; e_3 \, v \, v)]{j} \rt) \\
                                        - \frac{1}{e_3} \pd[(\omega \, v)]{k}
                                        - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt)
                                        + g \frac{\rho}{\rho_o}\sigma_2 + D_v^{\vect U} + F_v^{\vect U}
+                                       - g \frac{\rho}{\rho_o}\sigma_2 + D_v^{\vect U} + F_v^{\vect U}
   \end{multline*}
   where the relative vorticity, $\zeta$, the surface pressure gradient,
   and the hydrostatic pressure have the same expressions as in $z$-coordinates although
   they do not represent exactly the same quantities.
   $\omega$ is provided by the continuity equation (see \autoref{apdx:A}):
+  $\omega$ is provided by the continuity equation (see \autoref{apdx:SCOORD}):
   \[
   % \label{eq:PE_sco_continuity}
+  % \label{eq:MB_sco_continuity}
     \pd[e_3]{t} + e_3 \; \chi + \pd[\omega]{s} = 0 \quad \text{with} \quad
     \chi = \frac{1}{e_1 e_2 e_3} \lt( \pd[(e_2 e_3 \, u)]{i} + \pd[(e_1 e_3 \, v)]{j} \rt)
 …
 \item \textit{tracer equations}:
   \begin{multline*}
   % \label{eq:PE_sco_t}
+  % \label{eq:MB_sco_t}
     \frac{1}{e_3} \pd[(e_3 \, T)]{t} = - \frac{1}{e_1 e_2 e_3} \lt(   \pd[(e_2 e_3 \, u \, T)]{i}
                                                                     + \pd[(e_1 e_3 \, v \, T)]{j} \rt) \\
 …
   \end{multline*}
   \begin{multline}
   % \label{eq:PE_sco_s}
+  % \label{eq:MB_sco_s}
     \frac{1}{e_3} \pd[(e_3 \, S)]{t} = - \frac{1}{e_1 e_2 e_3} \lt(   \pd[(e_2 e_3 \, u \, S)]{i}
                                                                     + \pd[(e_1 e_3 \, v \, S)]{j} \rt) \\
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Curvilinear \zstar-coordinate system}
 \label{subsec:PE_zco_star}
+\label{subsec:MB_zco_star}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!b]
+  \begin{center}
+    \includegraphics[]{Fig_z_zstar}
+    \caption{
+      \protect\label{fig:z_zstar}
+      (a) $z$-coordinate in linear free-surface case ;
+      (b) $z$-coordinate in non-linear free surface case ;
+      (c) re-scaled height coordinate
+      (become popular as the \zstar-coordinate \citep{Adcroft_Campin_OM04}).
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_z_zstar}
+  \caption[Curvilinear z-coordinate systems (\{non-\}linear free-surface cases and re-scaled \zstar)]{
+    (a) $z$-coordinate in linear free-surface case ;
+    (b) $z$-coordinate in non-linear free surface case ;
+    (c) re-scaled height coordinate
+    (become popular as the \zstar-coordinate \citep{adcroft.campin_OM04}).}
+  \label{fig:MB_z_zstar}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 In that case, the free surface equation is nonlinear, and the variations of volume are fully taken into account.
 These coordinates systems is presented in a report \citep{Levier2007} available on the \NEMO web site.
+In this case, the free surface equation is nonlinear, and the variations of volume are fully taken into account.
+These coordinates systems is presented in a report \citep{levier.treguier.ea_rpt07} available on the \NEMO\ web site.
 The \zstar coordinate approach is an unapproximated, non-linear free surface implementation which allows one to
 deal with large amplitude free-surface variations relative to the vertical resolution \citep{Adcroft_Campin_OM04}.
+deal with large amplitude free-surface variations relative to the vertical resolution \citep{adcroft.campin_OM04}.
 In the \zstar formulation,
 the variation of the column thickness due to sea-surface undulations is not concentrated in the surface level,
 as in the $z$-coordinate formulation, but is equally distributed over the full water column.
 Thus vertical levels naturally follow sea-surface variations, with a linear attenuation with depth,
 as illustrated by \autoref{fig:z_zstar}.
 Note that with a flat bottom, such as in \autoref{fig:z_zstar}, the bottom-following $z$ coordinate and \zstar are equivalent.
+as illustrated by \autoref{fig:MB_z_zstar}.
+Note that with a flat bottom, such as in \autoref{fig:MB_z_zstar}, the bottom-following $z$ coordinate and \zstar are equivalent.
 The definition and modified oceanic equations for the rescaled vertical coordinate \zstar,
 including the treatment of fresh-water flux at the surface, are detailed in Adcroft and Campin (2004).
 …
 The position (\zstar) and vertical discretization (\zstar) are expressed as:
 \[
   % \label{eq:z-star}
+  % \label{eq:MB_z-star}
   H + \zstar = (H + z)  / r \quad \text{and}  \quad \delta \zstar
               = \delta z / r \quad \text{with} \quad r
+              = \frac{H + \eta}{H}
+              = \frac{H + \eta}{H} .
+\]
+Simple re-organisation of the above expressions gives
+\[
+  % \label{eq:MB_zstar_2}
+  \zstar = H \lt( \frac{z - \eta}{H + \eta} \rt) .
 \]
 Since the vertical displacement of the free surface is incorporated in the vertical coordinate \zstar,
 …
 Also the divergence of the flow field is no longer zero as shown by the continuity equation:
 \[
   \pd[r]{t} = \nabla_{\zstar} \cdot \lt( r \; \vect U_h \rt) (r \; w *) = 0
+  \pd[r]{t} = \nabla_{\zstar} \cdot \lt( r \; \vect U_h \rt) + \pd[r \; w^*]{\zstar} = 0 .
 \]
+% from MOM4p1 documentation
+To overcome problems with vanishing surface and/or bottom cells, we consider the zstar coordinate
+\[
+  % \label{eq:PE_}
+  \zstar = H \lt( \frac{z - \eta}{H + \eta} \rt)
+\]
+This coordinate is closely related to the "eta" coordinate used in many atmospheric models
+This \zstar coordinate is closely related to the "eta" coordinate used in many atmospheric models
 (see Black (1994) for a review of eta coordinate atmospheric models).
 It was originally used in ocean models by Stacey et al. (1995) for studies of tides next to shelves,
 …
 it is clear that surfaces constant \zstar are very similar to the depth surfaces.
 These properties greatly reduce difficulties of computing the horizontal pressure gradient relative to
 terrain following sigma models discussed in \autoref{subsec:PE_sco}.
 Additionally, since \zstar when $\eta = 0$,
+terrain following sigma models discussed in \autoref{subsec:MB_sco}.
+Additionally, since $\zstar = z$ when $\eta = 0$,
 no flow is spontaneously generated in an unforced ocean starting from rest, regardless the bottom topography.
 This behaviour is in contrast to the case with "s"-models, where pressure gradient errors in the presence of
 …
 depending on the sophistication of the pressure gradient solver.
 The quasi -horizontal nature of the coordinate surfaces also facilitates the implementation of
 neutral physics parameterizations in \zstar models using the same techniques as in $z$-models
 (see Chapters 13-16 of \cite{Griffies_Bk04}) for a discussion of neutral physics in $z$-models,
+neutral physics parameterizations in \zstar  models using the same techniques as in $z$-models
+(see Chapters 13-16 of \cite{griffies_bk04}) for a discussion of neutral physics in $z$-models,
 as well as \autoref{sec:LDF_slp} in this document for treatment in \NEMO).
 The range over which \zstar varies is time independent $-H \leq \zstar \leq 0$.
 Hence, all cells remain nonvanishing, so long as the surface height maintains $\eta > ?H$.
+The range over which \zstar  varies is time independent $-H \leq \zstar \leq 0$.
+Hence, all cells remain nonvanishing, so long as the surface height maintains $\eta > -H$.
 This is a minor constraint relative to that encountered on the surface height when using $s = z$ or $s = z - \eta$.
 Because \zstar has a time independent range, all grid cells have static increments ds,
 and the sum of the ver tical increments yields the time independent ocean depth. %k ds = H.
+Because \zstar  has a time independent range, all grid cells have static increments ds,
+and the sum of the vertical increments yields the time independent ocean depth. %k ds = H.
 The \zstar coordinate is therefore invisible to undulations of the free surface,
 since it moves along with the free surface.
 This proper ty means that no spurious vertical transport is induced across surfaces of constant \zstar by
+This property means that no spurious vertical transport is induced across surfaces of constant \zstar  by
 the motion of external gravity waves.
 Such spurious transpor t can be a problem in z-models, especially those with tidal forcing.
 Quite generally, the time independent range for the \zstar coordinate is a very convenient property that
 allows for a nearly arbitrary ver tical resolution even in the presence of large amplitude fluctuations of
+Such spurious transport can be a problem in z-models, especially those with tidal forcing.
+Quite generally, the time independent range for the \zstar  coordinate is a very convenient property that
+allows for a nearly arbitrary vertical resolution even in the presence of large amplitude fluctuations of
 the surface height, again so long as $\eta > -H$.
 %end MOM doc %%%
 \newpage
+\newpage
 % -------------------------------------------------------------------------------------------------------------
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Curvilinear terrain-following \textit{s}--coordinate}
 \label{subsec:PE_sco}
+\label{subsec:MB_sco}
 % -------------------------------------------------------------------------------------------------------------
 …
 For example, the topographic $\beta$-effect is usually larger than the planetary one along continental slopes.
 Topographic Rossby waves can be excited and can interact with the mean current.
 In the $z$-coordinate system presented in the previous section (\autoref{sec:PE_zco}),
+In the $z$-coordinate system presented in the previous section (\autoref{sec:MB_zco}),
 $z$-surfaces are geopotential surfaces.
 The bottom topography is discretised by steps.
 …
 The response to such a velocity field often leads to numerical dispersion effects.
 One solution to strongly reduce this error is to use a partial step representation of bottom topography instead of
 a full step one \cite{Pacanowski_Gnanadesikan_MWR98}.
+a full step one \cite{pacanowski.gnanadesikan_MWR98}.
 Another solution is to introduce a terrain-following coordinate system (hereafter $s$-coordinate).
 …
 The main two problems come from the truncation error in the horizontal pressure gradient and
 a possibly increased diapycnal diffusion.
 The horizontal pressure force in $s$-coordinate consists of two terms (see \autoref{apdx:A}),
+The horizontal pressure force in $s$-coordinate consists of two terms (see \autoref{apdx:SCOORD}),
 \begin{equation}
   \label{eq:PE_p_sco}
   \nabla p |_z = \nabla p |_s - \pd[p]{s} \nabla z |_s
+  \label{eq:MB_p_sco}
+  \nabla p |_z = \nabla p |_s - \frac{1}{e_3} \pd[p]{s} \nabla z |_s
 \end{equation}
 The second term in \autoref{eq:PE_p_sco} depends on the tilt of the coordinate surface and
 introduces a truncation error that is not present in a $z$-model.
+The second term in \autoref{eq:MB_p_sco} depends on the tilt of the coordinate surface and
+leads to a truncation error that is not present in a $z$-model.
 In the special case of a $\sigma$-coordinate (i.e. a depth-normalised coordinate system $\sigma = z/H$),
 \citet{Haney1991} and \citet{Beckmann1993} have given estimates of the magnitude of this truncation error.
+\citet{haney_JPO91} and \citet{beckmann.haidvogel_JPO93} have given estimates of the magnitude of this truncation error.
 It depends on topographic slope, stratification, horizontal and vertical resolution, the equation of state,
 and the finite difference scheme.
 …
 The large-scale slopes require high horizontal resolution, and the computational cost becomes prohibitive.
 This problem can be at least partially overcome by mixing $s$-coordinate and
 step-like representation of bottom topography \citep{Gerdes1993a,Gerdes1993b,Madec_al_JPO96}.
+step-like representation of bottom topography \citep{gerdes_JGR93*a,gerdes_JGR93*b,madec.delecluse.ea_JPO96}.
 However, the definition of the model domain vertical coordinate becomes then a non-trivial thing for
 a realistic bottom topography:
 a envelope topography is defined in $s$-coordinate on which a full or
+an envelope topography is defined in $s$-coordinate on which a full or
 partial step bottom topography is then applied in order to adjust the model depth to the observed one
 (see \autoref{sec:DOM_zgr}.
+(see \autoref{subsec:DOM_zgr}.
 For numerical reasons a minimum of diffusion is required along the coordinate surfaces of
 …
 In contrast, the ocean will stay at rest in a $z$-model.
 As for the truncation error, the problem can be reduced by introducing the terrain-following coordinate below
 the strongly stratified portion of the water column (\ie the main thermocline) \citep{Madec_al_JPO96}.
+the strongly stratified portion of the water column (\ie\ the main thermocline) \citep{madec.delecluse.ea_JPO96}.
 An alternate solution consists of rotating the lateral diffusive tensor to geopotential or to isoneutral surfaces
 (see \autoref{subsec:PE_ldf}).
+(see \autoref{subsec:MB_ldf}).
 Unfortunately, the slope of isoneutral surfaces relative to the $s$-surfaces can very large,
 strongly exceeding the stability limit of such a operator when it is discretized (see \autoref{chap:LDF}).
 The $s$-coordinates introduced here \citep{Lott_al_OM90,Madec_al_JPO96} differ mainly in two aspects from
+The $s$-coordinates introduced here \citep{lott.madec.ea_OM90,madec.delecluse.ea_JPO96} differ mainly in two aspects from
 similar models:
 it allows a representation of bottom topography with mixed full or partial step-like/terrain following topography;
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsection{\texorpdfstring{Curvilinear \ztilde-coordinate}{}}
 \label{subsec:PE_zco_tilde}
 The \ztilde -coordinate has been developed by \citet{Leclair_Madec_OM11}.
 It is available in \NEMO since the version 3.4.
+\label{subsec:MB_zco_tilde}
+The \ztilde -coordinate has been developed by \citet{leclair.madec_OM11}.
+It is available in \NEMO\ since the version 3.4 and is more robust in version 4.0 than previously.
 Nevertheless, it is currently not robust enough to be used in all possible configurations.
 Its use is therefore not recommended.
 \newpage
+\newpage
 % ================================================================
 …
 % ================================================================
 \section{Subgrid scale physics}
 \label{sec:PE_zdf_ldf}
 The primitive equations describe the behaviour of a geophysical fluid at space and time scales larger than
+\label{sec:MB_zdf_ldf}
+The hydrostatic primitive equations describe the behaviour of a geophysical fluid at space and time scales larger than
 a few kilometres in the horizontal, a few meters in the vertical and a few minutes.
 They are usually solved at larger scales: the specified grid spacing and time step of the numerical model.
 …
 must be represented entirely in terms of large-scale patterns to close the equations.
 These effects appear in the equations as the divergence of turbulent fluxes
 (\ie fluxes associated with the mean correlation of small scale perturbations).
+(\ie\ fluxes associated with the mean correlation of small scale perturbations).
 Assuming a turbulent closure hypothesis is equivalent to choose a formulation for these fluxes.
 It is usually called the subgrid scale physics.
 …
 The control exerted by gravity on the flow induces a strong anisotropy between the lateral and vertical motions.
 Therefore subgrid-scale physics \textbf{D}$^{\vect U}$, $D^{S}$ and $D^{T}$  in
 \autoref{eq:PE_dyn}, \autoref{eq:PE_tra_T} and \autoref{eq:PE_tra_S} are divided into
+\autoref{eq:MB_PE_dyn}, \autoref{eq:MB_PE_tra_T} and \autoref{eq:MB_PE_tra_S} are divided into
 a lateral part \textbf{D}$^{l \vect U}$, $D^{l S}$ and $D^{l T}$ and
 a vertical part \textbf{D}$^{v \vect U}$, $D^{v S}$ and $D^{v T}$.
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Vertical subgrid scale physics}
 \label{subsec:PE_zdf}
+\label{subsec:MB_zdf}
 The model resolution is always larger than the scale at which the major sources of vertical turbulence occur
 …
 The resulting vertical momentum and tracer diffusive operators are of second order:
 \begin{equation}
   \label{eq:PE_zdf}
+  \label{eq:MB_zdf}
   \begin{gathered}
     \vect D^{v \vect U} = \pd[]{z} \lt( A^{vm} \pd[\vect U_h]{z} \rt) \ , \\
 …
 All the vertical physics is embedded in the specification of the eddy coefficients.
 They can be assumed to be either constant, or function of the local fluid properties
 (\eg Richardson number, Brunt-Vais\"{a}l\"{a} frequency...),
+(\eg\ Richardson number, Brunt-Vais\"{a}l\"{a} frequency, distance from the boundary ...),
 or computed from a turbulent closure model.
 The choices available in \NEMO are discussed in \autoref{chap:ZDF}).
+The choices available in \NEMO\ are discussed in \autoref{chap:ZDF}).
 % -------------------------------------------------------------------------------------------------------------
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Formulation of the lateral diffusive and viscous operators}
 \label{subsec:PE_ldf}
+\label{subsec:MB_ldf}
 Lateral turbulence can be roughly divided into a mesoscale turbulence associated with eddies
 …
 and a sub mesoscale turbulence which is never explicitly solved even partially, but always parameterized.
 The formulation of lateral eddy fluxes depends on whether the mesoscale is below or above the grid-spacing
 (\ie the model is eddy-resolving or not).
+(\ie\ the model is eddy-resolving or not).
 In non-eddy-resolving configurations, the closure is similar to that used for the vertical physics.
 …
 The resulting lateral diffusive and dissipative operators are of second order.
 Observations show that lateral mixing induced by mesoscale turbulence tends to be along isopycnal surfaces
 (or more precisely neutral surfaces \cite{McDougall1987}) rather than across them.
+(or more precisely neutral surfaces \cite{mcdougall_JPO87}) rather than across them.
 As the slope of neutral surfaces is small in the ocean, a common approximation is to assume that
 the `lateral' direction is the horizontal, \ie the lateral mixing is performed along geopotential surfaces.
+the `lateral' direction is the horizontal, \ie\ the lateral mixing is performed along geopotential surfaces.
 This leads to a geopotential second order operator for lateral subgrid scale physics.
 This assumption can be relaxed: the eddy-induced turbulent fluxes can be better approached by assuming that
 …
 it has components in the three space directions.
 However,
 both horizontal and isoneutral operators have no effect on mean (\ie large scale) potential energy whereas
+both horizontal and isoneutral operators have no effect on mean (\ie\ large scale) potential energy whereas
 potential energy is a main source of turbulence (through baroclinic instabilities).
 \citet{Gent1990} have proposed a parameterisation of mesoscale eddy-induced turbulence which
+\citet{gent.mcwilliams_JPO90} proposed a parameterisation of mesoscale eddy-induced turbulence which
 associates an eddy-induced velocity to the isoneutral diffusion.
 Its mean effect is to reduce the mean potential energy of the ocean.
 …
 Another approach is becoming more and more popular:
 instead of specifying explicitly a sub-grid scale term in the momentum and tracer time evolution equations,
 one uses a advective scheme which is diffusive enough to maintain the model stability.
+one uses an advective scheme which is diffusive enough to maintain the model stability.
 It must be emphasised that then, all the sub-grid scale physics is included in the formulation of
 the advection scheme.
 All these parameterisations of subgrid scale physics have advantages and drawbacks.
 There are not all available in \NEMO. For active tracers (temperature and salinity) the main ones are:
+They are not all available in \NEMO. For active tracers (temperature and salinity) the main ones are:
 Laplacian and bilaplacian operators acting along geopotential or iso-neutral surfaces,
 \citet{Gent1990} parameterisation, and various slightly diffusive advection schemes.
+\citet{gent.mcwilliams_JPO90} parameterisation, and various slightly diffusive advection schemes.
 For momentum, the main ones are: Laplacian and bilaplacian operators acting along geopotential surfaces,
 and UBS advection schemes when flux form is chosen for the momentum advection.
 …
 \subsubsection{Lateral laplacian tracer diffusive operator}
 The lateral Laplacian tracer diffusive operator is defined by (see \autoref{apdx:B}):
+The lateral Laplacian tracer diffusive operator is defined by (see \autoref{apdx:DIFFOPERS}):
 \begin{equation}
   \label{eq:PE_iso_tensor}
+  \label{eq:MB_iso_tensor}
   D^{lT} = \nabla \vect . \lt( A^{lT} \; \Re \; \nabla T \rt) \quad \text{with} \quad
   \Re =
 …
 \end{equation}
 where $r_1$ and $r_2$ are the slopes between the surface along which the diffusive operator acts and
 the model level (\eg $z$- or $s$-surfaces).
 Note that the formulation \autoref{eq:PE_iso_tensor} is exact for
+the model level (\eg\ $z$- or $s$-surfaces).
+Note that the formulation \autoref{eq:MB_iso_tensor} is exact for
 the rotation between geopotential and $s$-surfaces,
 while it is only an approximation for the rotation between isoneutral and $z$- or $s$-surfaces.
 Indeed, in the latter case, two assumptions are made to simplify \autoref{eq:PE_iso_tensor} \citep{Cox1987}.
+Indeed, in the latter case, two assumptions are made to simplify \autoref{eq:MB_iso_tensor} \citep{cox_OM87}.
 First, the horizontal contribution of the dianeutral mixing is neglected since the ratio between iso and
 dia-neutral diffusive coefficients is known to be several orders of magnitude smaller than unity.
 Second, the two isoneutral directions of diffusion are assumed to be independent since
 the slopes are generally less than $10^{-2}$ in the ocean (see \autoref{apdx:B}).
+the slopes are generally less than $10^{-2}$ in the ocean (see \autoref{apdx:DIFFOPERS}).
 For \textit{iso-level} diffusion, $r_1$ and $r_2 $ are zero.
 …
 For \textit{geopotential} diffusion,
 $r_1$ and $r_2 $ are the slopes between the geopotential and computational surfaces:
 they are equal to $\sigma_1$ and $\sigma_2$, respectively (see \autoref{eq:PE_sco_slope}).
+they are equal to $\sigma_1$ and $\sigma_2$, respectively (see \autoref{eq:MB_sco_slope}).
 For \textit{isoneutral} diffusion $r_1$ and $r_2$ are the slopes between the isoneutral and computational surfaces.
 …
 In $z$-coordinates:
 \begin{equation}
   \label{eq:PE_iso_slopes}
+  \label{eq:MB_iso_slopes}
   r_1 = \frac{e_3}{e_1} \lt( \pd[\rho]{i} \rt) \lt( \pd[\rho]{k} \rt)^{-1} \quad
   r_2 = \frac{e_3}{e_2} \lt( \pd[\rho]{j} \rt) \lt( \pd[\rho]{k} \rt)^{-1}
 …
 \subsubsection{Eddy induced velocity}
 When the \textit{eddy induced velocity} parametrisation (eiv) \citep{Gent1990} is used,
+When the \textit{eddy induced velocity} parametrisation (eiv) \citep{gent.mcwilliams_JPO90} is used,
 an additional tracer advection is introduced in combination with the isoneutral diffusion of tracers:
 \[
   % \label{eq:PE_iso+eiv}
+  % \label{eq:MB_iso+eiv}
   D^{lT} = \nabla \cdot \lt( A^{lT} \; \Re \; \nabla T \rt) + \nabla \cdot \lt( \vect U^\ast \, T \rt)
 \]
 …
 eddy-induced transport velocity. This velocity field is defined by:
 \begin{gather}
   % \label{eq:PE_eiv}
+  % \label{eq:MB_eiv}
   u^\ast =   \frac{1}{e_3}            \pd[]{k} \lt( A^{eiv} \;        \tilde{r}_1 \rt) \\
   v^\ast =   \frac{1}{e_3}            \pd[]{k} \lt( A^{eiv} \;        \tilde{r}_2 \rt) \\
 …
 (or equivalently the isoneutral thickness diffusivity coefficient),
 and $\tilde r_1$ and $\tilde r_2$ are the slopes between isoneutral and \textit{geopotential} surfaces.
 Their values are thus independent of the vertical coordinate, but their expression depends on the coordinate:
+Their values are thus independent of the vertical coordinate, but their expression depends on the coordinate:
 \begin{align}
   \label{eq:PE_slopes_eiv}
+  \label{eq:MB_slopes_eiv}
   \tilde{r}_n =
     \begin{cases}
 …
 This can be achieved in a model by tapering either the eddy coefficient or the slopes to zero in the vicinity of
 the boundaries.
 The latter strategy is used in \NEMO (cf. \autoref{chap:LDF}).
+The latter strategy is used in \NEMO\ (cf. \autoref{chap:LDF}).
 \subsubsection{Lateral bilaplacian tracer diffusive operator}
 …
 The lateral bilaplacian tracer diffusive operator is defined by:
 \[
   % \label{eq:PE_bilapT}
+  % \label{eq:MB_bilapT}
   D^{lT}= - \Delta \; (\Delta T) \quad \text{where} \quad
   \Delta \bullet = \nabla \lt( \sqrt{B^{lT}} \; \Re \; \nabla \bullet \rt)
 \]
 It is the Laplacian operator given by \autoref{eq:PE_iso_tensor} applied twice with
+It is the Laplacian operator given by \autoref{eq:MB_iso_tensor} applied twice with
 the harmonic eddy diffusion coefficient set to the square root of the biharmonic one.
 …
 The Laplacian momentum diffusive operator along $z$- or $s$-surfaces is found by
 applying \autoref{eq:PE_lap_vector} to the horizontal velocity vector (see \autoref{apdx:B}):
+applying \autoref{eq:MB_lap_vector} to the horizontal velocity vector (see \autoref{apdx:DIFFOPERS}):
 \begin{align*}
   % \label{eq:PE_lapU}
+  % \label{eq:MB_lapU}
   \vect D^{l \vect U} &=   \nabla_h        \big( A^{lm}    \chi             \big)
                          - \nabla_h \times \big( A^{lm} \, \zeta \; \vect k \big) \\
                       &= \lt(   \frac{1}{e_1}     \pd[ \lt( A^{lm}    \chi      \rt) ]{i} \rt.
                               - \frac{1}{e_2 e_3} \pd[ \lt( A^{lm} \; e_3 \zeta \rt) ]{j}
+                              - \frac{1}{e_2 e_3} \pd[ \lt( A^{lm} \; e_3 \zeta \rt) ]{j} ,
                                 \frac{1}{e_2}     \pd[ \lt( A^{lm}    \chi      \rt) ]{j}
                          \lt. + \frac{1}{e_1 e_3} \pd[ \lt( A^{lm} \; e_3 \zeta \rt) ]{i} \rt)
 …
 Such a formulation ensures a complete separation between the vorticity and horizontal divergence fields
 (see \autoref{apdx:C}).
+(see \autoref{apdx:INVARIANTS}).
 Unfortunately, it is only available in \textit{iso-level} direction.
 When a rotation is required
 (\ie geopotential diffusion in $s$-coordinates or isoneutral diffusion in both $z$- and $s$-coordinates),
+(\ie\ geopotential diffusion in $s$-coordinates or isoneutral diffusion in both $z$- and $s$-coordinates),
 the $u$ and $v$-fields are considered as independent scalar fields, so that the diffusive operator is given by:
 \begin{gather*}
   % \label{eq:PE_lapU_iso}
+  % \label{eq:MB_lapU_iso}
     D_u^{l \vect U} = \nabla . \lt( A^{lm} \; \Re \; \nabla u \rt) \\
     D_v^{l \vect U} = \nabla . \lt( A^{lm} \; \Re \; \nabla v \rt)
 \end{gather*}
 where $\Re$ is given by \autoref{eq:PE_iso_tensor}.
+where $\Re$ is given by \autoref{eq:MB_iso_tensor}.
 It is the same expression as those used for diffusive operator on tracers.
 It must be emphasised that such a formulation is only exact in a Cartesian coordinate system,
 \ie on a $f$- or $\beta$-plane, not on the sphere.
+\ie\ on a $f$- or $\beta$-plane, not on the sphere.
 It is also a very good approximation in vicinity of the Equator in
 a geographical coordinate system \citep{Lengaigne_al_JGR03}.
 \subsubsection{lateral bilaplacian momentum diffusive operator}
+a geographical coordinate system \citep{lengaigne.madec.ea_JGR03}.
+\subsubsection{Lateral bilaplacian momentum diffusive operator}
 As for tracers, the bilaplacian order momentum diffusive operator is a re-entering Laplacian operator with

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex

-                      r10544
+                      r11564
 In that case, the free surface equation is nonlinear, and the variations of volume are fully taken into account.
 These coordinates systems is presented in a report \citep{Levier2007} available on the \NEMO web site.
+These coordinates systems is presented in a report \citep{levier.treguier.ea_rpt07} available on the \NEMO\ web site.
 \colorbox{yellow}{  end of to be updated}
 …
 % from MOM4p1 documentation
 To overcome problems with vanishing surface and/or bottom cells, we consider the zstar coordinate
 \[
   % \label{eq:PE_}
+To overcome problems with vanishing surface and/or bottom cells, we consider the zstar coordinate
+\[
+  % \label{eq:MBZ_PE_}
   z^\star = H \left( \frac{z-\eta}{H+\eta} \right)
 \]
 …
 the surface height, it is clear that surfaces constant $z^\star$ are very similar to the depth surfaces.
 These properties greatly reduce difficulties of computing the horizontal pressure gradient relative to
 terrain following sigma models discussed in \autoref{subsec:PE_sco}.
+terrain following sigma models discussed in \autoref{subsec:MB_sco}.
 Additionally, since $z^\star$ when $\eta = 0$, no flow is spontaneously generated in
 an unforced ocean starting from rest, regardless the bottom topography.
 …
 neutral physics parameterizations in $z^\star$ models using the same techniques as in $z$-models
 (see Chapters 13-16 of Griffies (2004) for a discussion of neutral physics in $z$-models,
 as well as  \autoref{sec:LDF_slp} in this document for treatment in \NEMO).
+as well as  \autoref{sec:LDF_slp} in this document for treatment in \NEMO).
 The range over which $z^\star$ varies is time independent $-H \leq z^\star \leq 0$.
 Hence, all cells remain nonvanishing, so long as the surface height maintains $\eta > ?H$.
 This is a minor constraint relative to that encountered on the surface height when using $s = z$ or $s = z - \eta$.
+This is a minor constraint relative to that encountered on the surface height when using $s = z$ or $s = z - \eta$.
 Because $z^\star$ has a time independent range, all grid cells have static increments ds,
 and the sum of the ver tical increments yields the time independent ocean depth %�k ds = H.
+and the sum of the ver tical increments yields the time independent ocean depth %�k ds = H.
 The $z^\star$ coordinate is therefore invisible to undulations of the free surface,
 since it moves along with the free surface.
 …
 Quite generally, the time independent range for the $z^\star$ coordinate is a very convenient property that
 allows for a nearly arbitrary vertical resolution even in the presence of large amplitude fluctuations of
 the surface height, again so long as $\eta > -H$.
+the surface height, again so long as $\eta > -H$.
 %%%
 …
 % Surface Pressure Gradient and Sea Surface Height
 % ================================================================
+\section{Surface pressure gradient and sea surface heigth (\protect\mdl{dynspg})}
+\label{sec:DYN_hpg_spg}
+\section[Surface pressure gradient and sea surface heigth (\textit{dynspg.F90})]
+{Surface pressure gradient and sea surface heigth (\protect\mdl{dynspg})}
+\label{sec:MBZ_dyn_hpg_spg}
 %-----------------------------------------nam_dynspg----------------------------------------------------
 %\nlst{nam_dynspg}
+%\nlst{nam_dynspg}
 %------------------------------------------------------------------------------------------------------------
 Options are defined through the \ngn{nam\_dynspg} namelist variables.
 The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:PE_hor_pg}).
+Options are defined through the \nam{\_dynspg} namelist variables.
+The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:MB_hor_pg}).
 The main distinction is between the fixed volume case (linear free surface or rigid lid) and
 the variable volume case (nonlinear free surface, \key{vvl} is active).
 In the linear free surface case (\autoref{subsec:PE_free_surface}) and rigid lid (\autoref{PE_rigid_lid}),
+In the linear free surface case (\autoref{subsec:MB_free_surface}) and rigid lid (\autoref{PE_rigid_lid}),
 the vertical scale factors $e_{3}$ are fixed in time,
 while in the nonlinear case (\autoref{subsec:PE_free_surface}) they are time-dependent.
+while in the nonlinear case (\autoref{subsec:MB_free_surface}) they are time-dependent.
 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}),
+the filtered free surface, which is a modification of the continuous equations %(see \autoref{eq:MB_flt?}),
 and the split-explicit free surface described below.
 The extra term introduced in the filtered method is calculated implicitly,
 …
 % Explicit
 %-------------------------------------------------------------
+\subsubsection{Explicit (\protect\key{dynspg\_exp})}
+\label{subsec:DYN_spg_exp}
+\subsubsection[Explicit (\texttt{\textbf{key\_dynspg\_exp}})]
+{Explicit (\protect\key{dynspg\_exp})}
+\label{subsec:MBZ_dyn_spg_exp}
 In the explicit free surface formulation, the model time step is chosen small enough to
 …
 The sea surface height is given by:
 \begin{equation}
   \label{eq:dynspg_ssh}
+  \label{eq:MBZ_dynspg_ssh}
   \frac{\partial \eta }{\partial t}\equiv \frac{\text{EMP}}{\rho_w }+\frac{1}{e_{1T}
     e_{2T} }\sum\limits_k {\left( {\delta_i \left[ {e_{2u} e_{3u} u}
 …
 and $\rho_w =1,000\,Kg.m^{-3}$ is the volumic mass of pure water.
 The sea-surface height is evaluated using 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:DYN_spg_ssh}) is centred in time (\textit{now} velocity).
 The surface pressure gradient, also evaluated using a leap-frog scheme, is then simply given by:
 \begin{equation}
   \label{eq:dynspg_exp}
+  \label{eq:MBZ_dynspg_exp}
   \left\{
     \begin{aligned}
 …
     \end{aligned}
   \right.
 \end{equation}
+\end{equation}
 Consistent with the linearization, a $\left. \rho \right|_{k=1} / \rho_o$ factor is omitted in
 (\autoref{eq:dynspg_exp}).
+(\autoref{eq:DYN_spg_exp}).
 %-------------------------------------------------------------
 % Split-explicit time-stepping
 %-------------------------------------------------------------
+\subsubsection{Split-explicit time-stepping (\protect\key{dynspg\_ts})}
+\label{subsec:DYN_spg_ts}
+\subsubsection[Split-explicit time-stepping (\texttt{\textbf{key\_dynspg\_ts}})]
+{Split-explicit time-stepping (\protect\key{dynspg\_ts})}
+\label{subsec:MBZ_dyn_spg_ts}
 %--------------------------------------------namdom----------------------------------------------------
-\nlst{namdom}
 %--------------------------------------------------------------------------------------------------------------
 The split-explicit free surface formulation used in OPA follows the one proposed by \citet{Griffies2004}.
+The split-explicit free surface formulation used in OPA follows the one proposed by \citet{Griffies2004?}.
 The general idea is to solve the free surface equation with a small time step,
 while the three dimensional prognostic variables are solved with a longer time step that
 is a multiple of \np{rdtbt} in the \ngn{namdom} namelist (Figure III.3).
+is a multiple of \np{rdtbt} in the \nam{dom} namelist (Figure III.3).
 %>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >
 \begin{figure}[!t]
   \begin{center}
     \includegraphics[width=0.90\textwidth]{Fig_DYN_dynspg_ts}
     \caption{
       \protect\label{fig:DYN_dynspg_ts}
       Schematic of the split-explicit time stepping scheme for the barotropic and baroclinic modes,
       after \citet{Griffies2004}.
       Time increases to the right.
       Baroclinic time steps are denoted by $t-\Delta t$, $t, t+\Delta t$, and $t+2\Delta t$.
       The curved line represents a leap-frog time step,
       and the smaller barotropic time steps $N \Delta t=2\Delta t$ are denoted by the zig-zag line.
       The vertically integrated forcing \textbf{M}(t) computed at
       baroclinic time step t represents the interaction between the barotropic and baroclinic motions.
       While keeping the total depth, tracer, and freshwater forcing fields fixed,
       a leap-frog integration carries the surface height and vertically integrated velocity from
       t to $t+2 \Delta t$ using N barotropic time steps of length $\Delta t$.
       Time averaging the barotropic fields over the N+1 time steps (endpoints included)
       centers the vertically integrated velocity at the baroclinic timestep $t+\Delta t$.
       A baroclinic leap-frog time step carries the surface height to $t+\Delta t$ using the convergence of
       the time averaged vertically integrated velocity taken from baroclinic time step t.
+    }
   \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_DYN_dynspg_ts}
+  \caption[Schematic of the split-explicit time stepping scheme for
+  the barotropic and baroclinic modes, after \citet{Griffies2004?}]{
+    Schematic of the split-explicit time stepping scheme for the barotropic and baroclinic modes,
+    after \citet{Griffies2004?}.
+    Time increases to the right.
+    Baroclinic time steps are denoted by $t-\Delta t$, $t, t+\Delta t$, and $t+2\Delta t$.
+    The curved line represents a leap-frog time step,
+    and the smaller barotropic time steps $N \Delta t=2\Delta t$ are denoted by the zig-zag line.
+    The vertically integrated forcing \textbf{M}(t) computed at
+    baroclinic time step t represents the interaction between the barotropic and baroclinic motions.
+    While keeping the total depth, tracer, and freshwater forcing fields fixed,
+    a leap-frog integration carries the surface height and vertically integrated velocity from
+    t to $t+2 \Delta t$ using N barotropic time steps of length $\Delta t$.
+    Time averaging the barotropic fields over the N+1 time steps (endpoints included)
+    centers the vertically integrated velocity at the baroclinic timestep $t+\Delta t$.
+    A baroclinic leap-frog time step carries the surface height to $t+\Delta t$ using
+    the convergence of the time averaged vertically integrated velocity taken from
+    baroclinic time step t.}
+  \label{fig:MBZ_dyn_dynspg_ts}
 \end{figure}
 %>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >
 The split-explicit formulation has a damping effect on external gravity waves,
 which is weaker than the filtered free surface but still significant as shown by \citet{Levier2007} in
 the case of an analytical barotropic Kelvin wave.
+which is weaker than the filtered free surface but still significant as shown by \citet{levier.treguier.ea_rpt07} in
+the case of an analytical barotropic Kelvin wave.
 %from griffies book: .....   copy past !
 …
 We have
 \[
   % \label{eq:DYN_spg_ts_eta}
+  % \label{eq:MBZ_dyn_spg_ts_eta}
   \eta^{(b)}(\tau,t_{n+1}) - \eta^{(b)}(\tau,t_{n+1}) (\tau,t_{n-1})
   = 2 \Delta t \left[-\nabla \cdot \textbf{U}^{(b)}(\tau,t_n) + \text{EMP}_w(\tau) \right]
+  = 2 \Delta t \left[-\nabla \cdot \textbf{U}^{(b)}(\tau,t_n) + \text{EMP}_w(\tau) \right]
 \]
 \begin{multline*}
   % \label{eq:DYN_spg_ts_u}
+  % \label{eq:MBZ_dyn_spg_ts_u}
   \textbf{U}^{(b)}(\tau,t_{n+1}) - \textbf{U}^{(b)}(\tau,t_{n-1})  \\
   = 2\Delta t \left[ - f \textbf{k} \times \textbf{U}^{(b)}(\tau,t_{n})
 …
 the freshwater flux $\text{EMP}_w(\tau)$, 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
 \[
   % \label{eq:DYN_spg_ts_t}
   t_n=\tau+n\Delta t
+This is also the time that sets the barotropic time steps via
+\[
+  % \label{eq:MBZ_dyn_spg_ts_t}
+  t_n=\tau+n\Delta t
 \]
 with $n$ an integer.
 The density scaled surface pressure is evaluated via
 \[
   % \label{eq:DYN_spg_ts_ps}
+The density scaled surface pressure is evaluated via
+\[
+  % \label{eq:MBZ_dyn_spg_ts_ps}
   p_s^{(b)}(\tau,t_{n}) =
   \begin{cases}
 …
   \end{cases}
 \]
 To get started, we assume the following initial conditions
 \[
   % \label{eq:DYN_spg_ts_eta}
+To get started, we assume the following initial conditions
+\[
+  % \label{eq:MBZ_dyn_spg_ts_eta}
   \begin{split}
     \eta^{(b)}(\tau,t_{n=0}) &= \overline{\eta^{(b)}(\tau)} \\
 …
   \end{split}
 \]
 with
 \[
   % \label{eq:DYN_spg_ts_etaF}
+with
+\[
+  % \label{eq:MBZ_dyn_spg_ts_etaF}
   \overline{\eta^{(b)}(\tau)} = \frac{1}{N+1} \sum\limits_{n=0}^N \eta^{(b)}(\tau-\Delta t,t_{n})
 \]
 …
 Likewise,
 \[
   % \label{eq:DYN_spg_ts_u}
+  % \label{eq:MBZ_dyn_spg_ts_u}
   \textbf{U}^{(b)}(\tau,t_{n=0}) = \overline{\textbf{U}^{(b)}(\tau)} \\ \\
   \textbf{U}(\tau,t_{n=1}) = \textbf{U}^{(b)}(\tau,t_{n=0}) + \Delta t \ \text{RHS}_{n=0}
 \]
 with
 \[
   % \label{eq:DYN_spg_ts_u}
+with
+\[
+  % \label{eq:MBZ_dyn_spg_ts_u}
   \overline{\textbf{U}^{(b)}(\tau)} = \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau-\Delta t,t_{n})
 \]
 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\Delta \tau$ , the vertically integrated velocity is time averaged to
 produce the updated vertically integrated velocity at baroclinic time $\tau + \Delta \tau$
 \[
   % \label{eq:DYN_spg_ts_u}
+produce the updated vertically integrated velocity at baroclinic time $\tau + \Delta \tau$
+\[
+  % \label{eq:MBZ_dyn_spg_ts_u}
   \textbf{U}(\tau+\Delta t) = \overline{\textbf{U}^{(b)}(\tau+\Delta t)}
   = \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau,t_{n})
 \]
 The surface height on the new baroclinic time step is then determined via
 a baroclinic leap-frog using the following form
+a baroclinic leap-frog using the following form
 \begin{equation}
   \label{eq:DYN_spg_ts_ssh}
+  \label{eq:MBZ_dyn_spg_ts_ssh}
   \eta(\tau+\Delta) - \eta^{F}(\tau-\Delta) = 2\Delta t \ \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}.
+the leap-frog splitting mode in equation \autoref{eq:MBZ_dyn_spg_ts_ssh}.
 We have tried various forms of such filtering,
 with the following method discussed in Griffies et al. (2001) chosen due to its stability and
 reasonably good maintenance of tracer conservation properties (see ??)
+reasonably good maintenance of tracer conservation properties (see ??)
 \begin{equation}
   \label{eq:DYN_spg_ts_sshf}
+  \label{eq:MBZ_dyn_spg_ts_sshf}
   \eta^{F}(\tau-\Delta) =  \overline{\eta^{(b)}(\tau)}
 \end{equation}
 Another approach tried was
 \[
   % \label{eq:DYN_spg_ts_sshf2}
+Another approach tried was
+\[
+  % \label{eq:MBZ_dyn_spg_ts_sshf2}
   \eta^{F}(\tau-\Delta) = \eta(\tau)
   + (\alpha/2) \left[\overline{\eta^{(b)}}(\tau+\Delta t)
 …
 This isolation allows for an easy check that tracer conservation is exact when 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.
+%-------------------------------------------------------------
+% Filtered formulation
+%-------------------------------------------------------------
+\subsubsection{Filtered formulation (\protect\key{dynspg\_flt})}
+\label{subsec:DYN_spg_flt}
+The filtered formulation follows the \citet{Roullet2000} implementation.
+However, in the general case with a non-zero $\alpha$, the filter \autoref{eq:MBZ_dyn_spg_ts_sshf} was found to
+be more conservative, and so is recommended.
+%-------------------------------------------------------------
+% Filtered formulation
+%-------------------------------------------------------------
+\subsubsection[Filtered formulation (\texttt{\textbf{key\_dynspg\_flt}})]
+{Filtered formulation (\protect\key{dynspg\_flt})}
+\label{subsec:MBZ_dyn_spg_flt}
+The filtered formulation follows the \citet{Roullet2000?} implementation.
 The extra term introduced in the equations (see {\S}I.2.2) is solved implicitly.
 The elliptic solvers available in the code are documented in \autoref{chap:MISC}.
 The amplitude of the extra term is given by the namelist variable \np{rnu}.
+The default value is 1, as recommended by \citet{Roullet2000}
+\colorbox{red}{\np{rnu}\forcode{ = 1} to be suppressed from namelist !}
+%-------------------------------------------------------------
+% Non-linear free surface formulation
+%-------------------------------------------------------------
+\subsection{Non-linear free surface formulation (\protect\key{vvl})}
+\label{subsec:DYN_spg_vvl}
+The default value is 1, as recommended by \citet{Roullet2000?}
+\colorbox{red}{\np{rnu}\forcode{=1} to be suppressed from namelist !}
+%-------------------------------------------------------------
+% Non-linear free surface formulation
+%-------------------------------------------------------------
+\subsection[Non-linear free surface formulation (\texttt{\textbf{key\_vvl}})]
+{Non-linear free surface formulation (\protect\key{vvl})}
+\label{subsec:MBZ_dyn_spg_vvl}
 In the non-linear free surface formulation, the variations of volume are fully taken into account.
 This option is presented in a report \citep{Levier2007} available on the NEMO web site.
+This option is presented in a report \citep{levier.treguier.ea_rpt07} available on the \NEMO\ web site.
 The three time-stepping methods (explicit, split-explicit and filtered) are the same as in
 \autoref{DYN_spg_linear} except that the ocean depth is now time-dependent.
+\autoref{?:DYN_spg_linear?} except that the ocean depth is now time-dependent.
 In particular, this means that in filtered case, the matrix to be inverted has to be recomputed at each time-step.

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_time_domain.tex

-                      r10501
+                      r11564
 % Chapter 2 ——— Time Domain (step.F90)
 % ================================================================
 \chapter{Time Domain (STP)}
 \label{chap:STP}
 \minitoc
+\chapter{Time Domain}
+\label{chap:TD}
+\chaptertoc
 % Missing things:
 %  - daymod: definition of the time domain (nit000, nitend andd the calendar)
+%  - daymod: definition of the time domain (nit000, nitend and the calendar)
 \gmcomment{STEVEN :maybe a picture of the directory structure in the introduction which could be referred to here,
 …
 \newpage
 Having defined the continuous equations in \autoref{chap:PE}, we need now to choose a time discretization,
+Having defined the continuous equations in \autoref{chap:MB}, we need now to choose a time discretization,
 a key feature of an ocean model as it exerts a strong influence on the structure of the computer code
 (\ie on its flowchart).
 In the present chapter, we provide a general description of the \NEMO time stepping strategy and
+(\ie\ on its flowchart).
+In the present chapter, we provide a general description of the \NEMO\  time stepping strategy and
 the consequences for the order in which the equations are solved.
 …
 % ================================================================
 \section{Time stepping environment}
 \label{sec:STP_environment}
 The time stepping used in \NEMO is a three level scheme that can be represented as follows:
 \begin{equation}
   \label{eq:STP}
+\label{sec:TD_environment}
+The time stepping used in \NEMO\ is a three level scheme that can be represented as follows:
+\begin{equation}
+  \label{eq:TD}
   x^{t + \rdt} = x^{t - \rdt} + 2 \, \rdt \ \text{RHS}_x^{t - \rdt, \, t, \, t + \rdt}
 \end{equation}
+\end{equation}
 where $x$ stands for $u$, $v$, $T$ or $S$;
 RHS is the Right-Hand-Side of the corresponding time evolution equation;
 $\rdt$ is the time step;
 and the superscripts indicate the time at which a quantity is evaluated.
 Each term of the RHS is evaluated at a specific time step depending on the physics with which it is associated.
 The choice of the time step used for this evaluation is discussed below as well as
+Each term of the RHS is evaluated at a specific time stepping depending on the physics with which it is associated.
+The choice of the time stepping used for this evaluation is discussed below as well as
 the implications for starting or restarting a model simulation.
 Note that the time stepping calculation is generally performed in a single operation.
 …
 The third array, although referred to as $x_a$ (after) in the code,
 is usually not the variable at the after time step;
+but rather it is used to store the time derivative (RHS in \autoref{eq:STP}) prior to time-stepping the equation.
+Generally, the time stepping is performed once at each time step in the \mdl{tranxt} and \mdl{dynnxt} modules,
+except when using implicit vertical diffusion or calculating sea surface height in which
+case time-splitting options are used.
+but rather it is used to store the time derivative (RHS in \autoref{eq:TD}) prior to time-stepping the equation.
+The time stepping itself is performed once at each time step where implicit vertical diffusion is computed, \ie\ in the \mdl{trazdf} and \mdl{dynzdf} modules.
 % -------------------------------------------------------------------------------------------------------------
 …
 % -------------------------------------------------------------------------------------------------------------
 \section{Non-diffusive part --- Leapfrog scheme}
 \label{sec:STP_leap_frog}
+\label{sec:TD_leap_frog}
 The time stepping used for processes other than diffusion is the well-known leapfrog scheme
 \citep{Mesinger_Arakawa_Bk76}.
+\citep{mesinger.arakawa_bk76}.
 This scheme is widely used for advection processes in low-viscosity fluids.
 It is a time centred scheme, \ie the RHS in \autoref{eq:STP} is evaluated at time step $t$, the now time step.
+It is a time centred scheme, \ie\ the RHS in \autoref{eq:TD} is evaluated at time step $t$, the now time step.
 It may be used for momentum and tracer advection, pressure gradient, and Coriolis terms,
 but not for diffusion terms.
 …
 To prevent it, the leapfrog scheme is often used in association with a Robert-Asselin time filter
 (hereafter the LF-RA scheme).
 This filter, first designed by \citet{Robert_JMSJ66} and more comprehensively studied by \citet{Asselin_MWR72},
+This filter, first designed by \citet{robert_JMSJ66} and more comprehensively studied by \citet{asselin_MWR72},
 is a kind of laplacian diffusion in time that mixes odd and even time steps:
 \begin{equation}
   \label{eq:STP_asselin}
+  \label{eq:TD_asselin}
   x_F^t = x^t + \gamma \, \lt[ x_F^{t - \rdt} - 2 x^t + x^{t + \rdt} \rt]
 \end{equation}
 where the subscript $F$ denotes filtered values and $\gamma$ is the Asselin coefficient.
 $\gamma$ is initialized as \np{rn\_atfp} (namelist parameter).
 Its default value is \np{rn\_atfp}~\forcode{= 10.e-3} (see \autoref{sec:STP_mLF}),
 causing only a weak dissipation of high frequency motions (\citep{Farge1987}).
+Its default value is \np{rn\_atfp}\forcode{ = 10.e-3} (see \autoref{sec:TD_mLF}),
+causing only a weak dissipation of high frequency motions (\citep{farge-coulombier_phd87}).
 The addition of a time filter degrades the accuracy of the calculation from second to first order.
 However, the second order truncation error is proportional to $\gamma$, which is small compared to 1.
 …
 When used with the 2nd order space centred discretisation of the advection terms in
 the momentum and tracer equations, LF-RA avoids implicit numerical diffusion:
 diffusion is set explicitly by the user through the Robert-Asselin
+diffusion is set explicitly by the user through the Robert-Asselin
 filter parameter and the viscosity and diffusion coefficients.
 …
 % -------------------------------------------------------------------------------------------------------------
 \section{Diffusive part --- Forward or backward scheme}
 \label{sec:STP_forward_imp}
+\label{sec:TD_forward_imp}
 The leapfrog differencing scheme is unsuitable for the representation of diffusion and damping processes.
 For a tendancy $D_x$, representing a diffusion term or a restoring term to a tracer climatology
+For a tendency $D_x$, representing a diffusion term or a restoring term to a tracer climatology
 (when present, see \autoref{sec:TRA_dmp}), a forward time differencing scheme is used :
 \[
   %\label{eq:STP_euler}
+  %\label{eq:TD_euler}
   x^{t + \rdt} = x^{t - \rdt} + 2 \, \rdt \ D_x^{t - \rdt}
 \]
 This is diffusive in time and conditionally stable.
 The conditions for stability of second and fourth order horizontal diffusion schemes are \citep{Griffies_Bk04}:
 \begin{equation}
   \label{eq:STP_euler_stability}
+The conditions for stability of second and fourth order horizontal diffusion schemes are \citep{griffies_bk04}:
+\begin{equation}
+  \label{eq:TD_euler_stability}
   A^h <
   \begin{cases}
 …
 \end{equation}
 where $e$ is the smallest grid size in the two horizontal directions and $A^h$ is the mixing coefficient.
 The linear constraint \autoref{eq:STP_euler_stability} is a necessary condition, but not sufficient.
+The linear constraint \autoref{eq:TD_euler_stability} is a necessary condition, but not sufficient.
 If it is not satisfied, even mildly, then the model soon becomes wildly unstable.
 The instability can be removed by either reducing the length of the time steps or reducing the mixing coefficient.
 For the vertical diffusion terms, a forward time differencing scheme can be used,
+but usually the numerical stability condition imposes a strong constraint on the time step.
+Two solutions are available in \NEMO to overcome the stability constraint:
+$(a)$ a forward time differencing scheme using a time splitting technique (\np{ln\_zdfexp}~\forcode{= .true.}) or
+$(b)$ a backward (or implicit) time differencing scheme                   (\np{ln\_zdfexp}~\forcode{= .false.}).
+In $(a)$, the master time step $\Delta$t is cut into $N$ fractional time steps so that
+the stability criterion is reduced by a factor of $N$.
+The computation is performed as follows:
+\begin{alignat*}{2}
+  % \label{eq:STP_ts}
+  &x_\ast^{t - \rdt}                      &= &x^{t - \rdt} \\
+  &x_\ast^{t - \rdt + L \frac{2 \rdt}{N}} &=   &x_\ast ^{t - \rdt + (L - 1) \frac{2 \rdt}{N}}
+                                             + \frac{2 \rdt}{N} \; DF^{t - \rdt + (L - 1) \frac{2 \rdt}{N}}
+  \quad \text{for $L = 1$ to $N$} \\
+  &x^{t + \rdt}                           &= &x_\ast^{t + \rdt}
+\end{alignat*}
+with DF a vertical diffusion term.
+The number of fractional time steps, $N$, is given by setting \np{nn\_zdfexp}, (namelist parameter).
+The scheme $(b)$ is unconditionally stable but diffusive. It can be written as follows:
+\begin{equation}
+  \label{eq:STP_imp}
+but usually the numerical stability condition imposes a strong constraint on the time step. To overcome the stability constraint, a
+backward (or implicit) time differencing scheme is used. This scheme is unconditionally stable but diffusive and can be written as follows:
+\begin{equation}
+  \label{eq:TD_imp}
   x^{t + \rdt} = x^{t - \rdt} + 2 \, \rdt \ \text{RHS}_x^{t + \rdt}
 \end{equation}
 …
 %%gm
+This scheme is rather time consuming since it requires a matrix inversion,
+but it becomes attractive since a value of 3 or more is needed for N in the forward time differencing scheme.
+For example, the finite difference approximation of the temperature equation is:
+This scheme is rather time consuming since it requires a matrix inversion. For example, the finite difference approximation of the temperature equation is:
 \[
   % \label{eq:STP_imp_zdf}
+  % \label{eq:TD_imp_zdf}
   \frac{T(k)^{t + 1} - T(k)^{t - 1}}{2 \; \rdt}
   \equiv
 …
 \]
 where RHS is the right hand side of the equation except for the vertical diffusion term.
 We rewrite \autoref{eq:STP_imp} as:
 \begin{equation}
   \label{eq:STP_imp_mat}
+We rewrite \autoref{eq:TD_imp} as:
+\begin{equation}
+  \label{eq:TD_imp_mat}
   -c(k + 1) \; T^{t + 1}(k + 1) + d(k) \; T^{t + 1}(k) - \; c(k) \; T^{t + 1}(k - 1) \equiv b(k)
 \end{equation}
 where
 \begin{align*}
+where
+\begin{align*}
   c(k) &= A_w^{vT} (k) \, / \, e_{3w} (k)     \\
   d(k) &= e_{3t}   (k)       \, / \, (2 \rdt) + c_k + c_{k + 1}    \\
 …
 \end{align*}
 \autoref{eq:STP_imp_mat} is a linear system of equations with an associated matrix which is tridiagonal.
+\autoref{eq:TD_imp_mat} is a linear system of equations with an associated matrix which is tridiagonal.
 Moreover,
 $c(k)$ and $d(k)$ are positive and the diagonal term is greater than the sum of the two extra-diagonal terms,
 therefore a special adaptation of the Gauss elimination procedure is used to find the solution
 (see for example \citet{Richtmyer1967}).
+(see for example \citet{richtmyer.morton_bk67}).
 % -------------------------------------------------------------------------------------------------------------
 …
 % -------------------------------------------------------------------------------------------------------------
 \section{Surface pressure gradient}
+\label{sec:STP_spg_ts}
+===>>>>  TO BE written....  :-)
+%\gmcomment{
+\label{sec:TD_spg_ts}
+The leapfrog environment supports a centred in time computation of the surface pressure, \ie\ evaluated
+at \textit{now} time step. This refers to as the explicit free surface case in the code (\np{ln\_dynspg\_exp}\forcode{=.true.}).
+This choice however imposes a strong constraint on the time step which should be small enough to resolve the propagation
+of external gravity waves. As a matter of fact, one rather use in a realistic setup, a split-explicit free surface
+(\np{ln\_dynspg\_ts}\forcode{=.true.}) in which barotropic and baroclinic dynamical equations are solved separately with ad-hoc
+time steps. The use of the time-splitting (in combination with non-linear free surface) imposes some constraints on the design of
+the overall flowchart, in particular to ensure exact tracer conservation (see \autoref{fig:TD_TimeStep_flowchart}).
+Compared to the former use of the filtered free surface in \NEMO\ v3.6 (\citet{roullet.madec_JGR00}), the use of a split-explicit free surface is advantageous
+on massively parallel computers. Indeed, no global computations are anymore required by the elliptic solver which saves a substantial amount of communication
+time. Fast barotropic motions (such as tides) are also simulated with a better accuracy.
+%\gmcomment{
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[]{Fig_TimeStepping_flowchart}
+    \caption{
+      \protect\label{fig:TimeStep_flowchart}
+      Sketch of the leapfrog time stepping sequence in \NEMO from \citet{Leclair_Madec_OM09}.
+      The use of a semi -implicit computation of the hydrostatic pressure gradient requires the tracer equation to
+      be stepped forward prior to the momentum equation.
+      The need for knowledge of the vertical scale factor (here denoted as $h$) requires the sea surface height and
+      the continuity equation to be stepped forward prior to the computation of the tracer equation.
+      Note that the method for the evaluation of the surface pressure gradient $\nabla p_s$ is not presented here
+      (see \autoref{sec:DYN_spg}).
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_TimeStepping_flowchart_v4}
+  \caption[Leapfrog time stepping sequence with split-explicit free surface]{
+    Sketch of the leapfrog time stepping sequence in \NEMO\ with split-explicit free surface.
+    The latter combined with non-linear free surface requires the dynamical tendency being
+    updated prior tracers tendency to ensure conservation.
+    Note the use of time integrated fluxes issued from the barotropic loop in
+    subsequent calculations of tracer advection and in the continuity equation.
+    Details about the time-splitting scheme can be found in \autoref{subsec:DYN_spg_ts}.}
+  \label{fig:TD_TimeStep_flowchart}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 % -------------------------------------------------------------------------------------------------------------
 \section{Modified Leapfrog -- Asselin filter scheme}
 \label{sec:STP_mLF}
 Significant changes have been introduced by \cite{Leclair_Madec_OM09} in the LF-RA scheme in order to
+\label{sec:TD_mLF}
+Significant changes have been introduced by \cite{leclair.madec_OM09} in the LF-RA scheme in order to
 ensure tracer conservation and to allow the use of a much smaller value of the Asselin filter parameter.
 The modifications affect both the forcing and filtering treatments in the LF-RA scheme.
 In a classical LF-RA environment, the forcing term is centred in time,
 \ie it is time-stepped over a $2 \rdt$ period:
+\ie\ it is time-stepped over a $2 \rdt$ period:
 $x^t = x^t + 2 \rdt Q^t$ where $Q$ is the forcing applied to $x$,
 and the time filter is given by \autoref{eq:STP_asselin} so that $Q$ is redistributed over several time step.
+and the time filter is given by \autoref{eq:TD_asselin} so that $Q$ is redistributed over several time step.
 In the modified LF-RA environment, these two formulations have been replaced by:
 \begin{gather}
   \label{eq:STP_forcing}
+  \label{eq:TD_forcing}
   x^{t + \rdt} = x^{t - \rdt} + \rdt \lt( Q^{t - \rdt / 2} + Q^{t + \rdt / 2} \rt)  \\
   \label{eq:STP_RA}
+  \label{eq:TD_RA}
   x_F^t       = x^t + \gamma \, \lt( x_F^{t - \rdt} - 2 x^t + x^{t + \rdt} \rt)
                     - \gamma \, \rdt \, \lt( Q^{t + \rdt / 2} - Q^{t - \rdt / 2} \rt)
 \end{gather}
 The change in the forcing formulation given by \autoref{eq:STP_forcing} (see \autoref{fig:MLF_forcing})
+The change in the forcing formulation given by \autoref{eq:TD_forcing} (see \autoref{fig:TD_MLF_forcing})
 has a significant effect:
 the forcing term no longer excites the divergence of odd and even time steps \citep{Leclair_Madec_OM09}.
+the forcing term no longer excites the divergence of odd and even time steps \citep{leclair.madec_OM09}.
 % forcing seen by the model....
 This property improves the LF-RA scheme in two respects.
+This property improves the LF-RA scheme in two aspects.
 First, the LF-RA can now ensure the local and global conservation of tracers.
 Indeed, time filtering is no longer required on the forcing part.
 The influence of the Asselin filter on the forcing is be removed by adding a new term in the filter
 (last term in \autoref{eq:STP_RA} compared to \autoref{eq:STP_asselin}).
+The influence of the Asselin filter on the forcing is explicitly removed by adding a new term in the filter
+(last term in \autoref{eq:TD_RA} compared to \autoref{eq:TD_asselin}).
 Since the filtering of the forcing was the source of non-conservation in the classical LF-RA scheme,
 the modified formulation becomes conservative \citep{Leclair_Madec_OM09}.
+the modified formulation becomes conservative \citep{leclair.madec_OM09}.
 Second, the LF-RA becomes a truly quasi -second order scheme.
 Indeed, \autoref{eq:STP_forcing} used in combination with a careful treatment of static instability
 (\autoref{subsec:ZDF_evd}) and of the TKE physics (\autoref{subsec:ZDF_tke_ene}),
 the two other main sources of time step divergence,
+Indeed, \autoref{eq:TD_forcing} used in combination with a careful treatment of static instability
+(\autoref{subsec:ZDF_evd}) and of the TKE physics (\autoref{subsec:ZDF_tke_ene})
+(the two other main sources of time step divergence),
 allows a reduction by two orders of magnitude of the Asselin filter parameter.
 Note that the forcing is now provided at the middle of a time step:
 $Q^{t + \rdt / 2}$ is the forcing applied over the $[t,t + \rdt]$ time interval.
 This and the change in the time filter, \autoref{eq:STP_RA},
 allows an exact evaluation of the contribution due to the forcing term between any two time steps,
+This and the change in the time filter, \autoref{eq:TD_RA},
+allows for an exact evaluation of the contribution due to the forcing term between any two time steps,
 even if separated by only $\rdt$ since the time filter is no longer applied to the forcing term.
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
   \begin{center}
     \includegraphics[]{Fig_MLF_forcing}
     \caption{
       \protect\label{fig:MLF_forcing}
       Illustration of forcing integration methods.
       (top) ''Traditional'' formulation:
       the forcing is defined at the same time as the variable to which it is applied
       (integer value of the time step index) and it is applied over a $2 \rdt$ period.
       (bottom)  modified formulation:
       the forcing is defined in the middle of the time (integer and a half value of the time step index) and
       the mean of two successive forcing values ($n - 1 / 2$, $n + 1 / 2$) is applied over a $2 \rdt$ period.
+    }
   \end{center}
+  \centering
+  \includegraphics[width=\textwidth]{Fig_MLF_forcing}
+  \caption[Forcing integration methods for modified leapfrog (top and bottom)]{
+    Illustration of forcing integration methods.
+    (top) ''Traditional'' formulation:
+    the forcing is defined at the same time as the variable to which it is applied
+    (integer value of the time step index) and it is applied over a $2 \rdt$ period.
+    (bottom)  modified formulation:
+    the forcing is defined in the middle of the time
+    (integer and a half value of the time step index) and
+    the mean of two successive forcing values ($n - 1 / 2$, $n + 1 / 2$) is applied over
+    a $2 \rdt$ period.}
+  \label{fig:TD_MLF_forcing}
 \end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 …
 % -------------------------------------------------------------------------------------------------------------
 \section{Start/Restart strategy}
 \label{sec:STP_rst}
+\label{sec:TD_rst}
 %--------------------------------------------namrun-------------------------------------------
+\nlst{namrun}
+\begin{listing}
+  \nlst{namrun}
+  \caption{\texttt{namrun}}
+  \label{lst:namrun}
+\end{listing}
 %--------------------------------------------------------------------------------------------------------------
 …
 (Euler time integration):
 \[
   % \label{eq:DOM_euler}
+  % \label{eq:TD_DOM_euler}
   x^1 = x^0 + \rdt \ \text{RHS}^0
 \]
 This is done simply by keeping the leapfrog environment (\ie the \autoref{eq:STP} three level time stepping) but
+This is done simply by keeping the leapfrog environment (\ie\ the \autoref{eq:TD} three level time stepping) but
 setting all $x^0$ (\textit{before}) and $x^1$ (\textit{now}) fields equal at the first time step and
 using half the value of $\rdt$.
+using half the value of a leapfrog time step ($2 \rdt$).
 It is also possible to restart from a previous computation, by using a restart file.
 …
 This requires saving two time levels and many auxiliary data in the restart files in machine precision.
+Note that when a semi -implicit scheme is used to evaluate the hydrostatic pressure gradient
+(see \autoref{subsec:DYN_hpg_imp}), an extra three-dimensional field has to
+be added to the restart file to ensure an exact restartability.
+This is done optionally via the  \np{nn\_dynhpg\_rst} namelist parameter,
+so that the size of the restart file can be reduced when restartability is not a key issue
+(operational oceanography or in ensemble simulations for seasonal forecasting).
+Note the size of the time step used, $\rdt$, is also saved in the restart file.
+When restarting, if the the time step has been changed, a restart using an Euler time stepping scheme is imposed.
+Options are defined through the  \ngn{namrun} namelist variables.
+Note that the time step $\rdt$, is also saved in the restart file.
+When restarting, if the time step has been changed, or one of the prognostic variables at \textit{before} time step
+is missing, an Euler time stepping scheme is imposed. A forward initial step can still be enforced by the user by setting
+the namelist variable \np{nn\_euler}\forcode{=0}. Other options to control the time integration of the model
+are defined through the  \nam{run} namelist variables.
 %%%
 \gmcomment{
 …
 add also the idea of writing several restart for seasonal forecast : how is it done ?
 verify that all namelist pararmeters are truly described
+verify that all namelist pararmeters are truly described
 a word on the check of restart  .....
 …
 %%%
 \gmcomment{       % add a subsection here
+\gmcomment{       % add a subsection here
 %-------------------------------------------------------------------------------------------------------------
 …
 % -------------------------------------------------------------------------------------------------------------
 \subsection{Time domain}
 \label{subsec:STP_time}
+\label{subsec:TD_time}
 %--------------------------------------------namrun-------------------------------------------
-\nlst{namdom}
 %--------------------------------------------------------------------------------------------------------------
 Options are defined through the  \ngn{namdom} namelist variables.
+Options are defined through the  \nam{dom} namelist variables.
  \colorbox{yellow}{add here a few word on nit000 and nitend}
 …
 %%
 \gmcomment{       % add implicit in vvl case  and Crant-Nicholson scheme
+\gmcomment{       % add implicit in vvl case  and Crant-Nicholson scheme
 Implicit time stepping in case of variable volume thickness.

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/SI3

Property svn:ignore deleted

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/SI3/namelists

Property svn:ignore deleted

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/SI3/namelists/namdyn_adv

Property svn:mime-type set to text/x-fortran

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/TOP

Property svn:ignore deleted

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

Context Navigation

Legend:

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/HTML_latex2html.sh

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/main

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_ASM.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_DIA.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_DIU.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_DOM.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_DYN.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_LBC.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_LDF.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_OBS.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_SBC.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_STO.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_TRA.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_ZDF.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_conservation.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_misc.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_model_basics.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/NEMO/subfiles/chap_time_domain.tex

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/SI3

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/SI3/namelists

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/SI3/namelists/namdyn_adv

NEMO/branches/2019/dev_r10973_AGRIF-01_jchanut_small_jpi_jpj/doc/latex/TOP

Download in other formats: