Changeset 11799 for NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc

Property svn:externals set to
^/utils/badges badges
^/utils/logos logos

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex

Property svn:ignore deleted

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO

Property svn:externals set to
^/utils/figures/NEMO figures

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/build

Property svn:ignore

old	new
14	14	*.pdf
15	15	*.toc
	16	*.xdv
16	17	_minted-*

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/main/appendices.tex

-                      r11330
+                      r11799
 \subfile{../subfiles/annex_A}             %% Generalised vertical coordinate
 \subfile{../subfiles/annex_B}             %% Diffusive operator
 \subfile{../subfiles/annex_C}             %% Discrete invariants of the eqs.
 \subfile{../subfiles/annex_iso}            %% Isoneutral diffusion using triads
 \subfile{../subfiles/annex_DOMAINcfg}     %% Brief notes on DOMAINcfg
+\subfile{../subfiles/apdx_s_coord}      %% A. Generalised vertical coordinate
+\subfile{../subfiles/apdx_diff_opers}   %% B. Diffusive operators
+\subfile{../subfiles/apdx_invariants}   %% C. Discrete invariants of the eqs.
+\subfile{../subfiles/apdx_triads}       %% D. Isoneutral diffusion using triads
+\subfile{../subfiles/apdx_DOMAINcfg}    %% E. Brief notes on DOMAINcfg
 %% Not included
 …
 %\subfile{../subfiles/chap_DIU}
 %\subfile{../subfiles/chap_conservation}
+%\subfile{../subfiles/annex_E}            %% Notes on some on going staff
+%\subfile{../subfiles/apdx_algos}   %% Notes on some on going staff

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/main/bibliography.bib

-                      r11336
+                      r11799
+}
+@article{         kraus.turner_tellus67,
+  author = {Kraus, E.B. and Turner, J.},
+  journal = {Tellus},
+  pages = {98--106},
+  title = {A one dimensional model of the seasonal thermocline {II}. {T}he general theory and its consequences},
+  volume = {19},
+  year = {1967}
+}
+@article{        large.ea_RG97,
+  author        = "Large, W. G. and McWilliams, J. C. and Doney, S. C.",
+  doi           = "10.1029/94RG01872",
+  journal       = "Reviews of Geophysics",
+  number        = {4},
+  pages         = {363--403},
+  publisher     = {AGU},
+  title         = "Oceanic vertical mixing: {A} review and a model with a nonlocal boundary layer parameterization",
+  year          = "1994"
+}
 @techreport{      large.yeager_rpt04,
   title         = "Diurnal to decadal global forcing for ocean and sea-ice
 …
+}
+@article{mcwilliams.ea_JFM97,
+   author = {McWilliams, James C. and Sullivan, Peter P. and Moeng, Chin-Hoh},
+   doi = {10.1017/S0022112096004375},
+   journal = {Journal of Fluid Mechanics},
+   pages = {1--30},
+   title = {Langmuir turbulence in the ocean},
+   volume = {334},
+   year = {1997},
+}
 @article{         mellor.blumberg_JPO04,
   title         = "Wave Breaking and Ocean Surface Layer Thermal Response",

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/main/chapters.tex

-                      r11170
+                      r11799
+\subfile{../subfiles/introduction}        %% Introduction
+\subfile{../subfiles/chap_model_basics}
+\subfile{../subfiles/chap_time_domain}    %% Time discretisation (time stepping strategy)
+\subfile{../subfiles/chap_DOM}            %% Space discretisation
+\subfile{../subfiles/chap_TRA}            %% Tracer advection/diffusion equation
+\subfile{../subfiles/chap_DYN}            %% Dynamics : momentum equation
+\subfile{../subfiles/chap_SBC}            %% Surface Boundary Conditions
+\subfile{../subfiles/chap_LBC}            %% Lateral Boundary Conditions
+\subfile{../subfiles/chap_LDF}            %% Lateral diffusion
+\subfile{../subfiles/chap_ZDF}            %% Vertical diffusion
+\subfile{../subfiles/chap_DIA}            %% Outputs and Diagnostics
+\subfile{../subfiles/chap_OBS}            %% Observation operator
+\subfile{../subfiles/chap_ASM}            %% Assimilation increments
+\subfile{../subfiles/chap_STO}            %% Stochastic param.
+\subfile{../subfiles/chap_misc}           %% Miscellaneous topics
+\subfile{../subfiles/chap_CONFIG}         %% Predefined configurations
+\subfile{../subfiles/chap_model_basics}   %% 1.
+\subfile{../subfiles/chap_time_domain}    %% 2.  Time discretisation (time stepping strategy)
+\subfile{../subfiles/chap_DOM}            %% 3.  Space discretisation
+\subfile{../subfiles/chap_TRA}            %% 4.  Tracer advection/diffusion equation
+\subfile{../subfiles/chap_DYN}            %% 5.  Dynamics : momentum equation
+\subfile{../subfiles/chap_SBC}            %% 6.  Surface Boundary Conditions
+\subfile{../subfiles/chap_LBC}            %% 7.  Lateral Boundary Conditions
+\subfile{../subfiles/chap_LDF}            %% 8.  Lateral diffusion
+\subfile{../subfiles/chap_ZDF}            %% 9.  Vertical diffusion
+\subfile{../subfiles/chap_DIA}            %% 10. Outputs and Diagnostics
+\subfile{../subfiles/chap_OBS}            %% 11. Observation operator
+\subfile{../subfiles/chap_ASM}            %% 12. Assimilation increments
+\subfile{../subfiles/chap_STO}            %% 13. Stochastic param.
+\subfile{../subfiles/chap_misc}           %% 14. Miscellaneous topics
+\subfile{../subfiles/chap_cfgs}           %% 15. Predefined configurations
+%% Not included
+%\subfile{../subfiles/chap_model_basics_zstar}
+%\subfile{../subfiles/chap_DIU}
+%\subfile{../subfiles/chap_conservation}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles

Property svn:ignore

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

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_ASM.tex

-                      r11435
+                      r11799
 \begin{document}
+% ================================================================
+% Chapter Assimilation increments (ASM)
+% ================================================================
 \chapter{Apply Assimilation Increments (ASM)}
 \label{chap:ASM}
+%    {\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}  \\
+\thispagestyle{plain}
 \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}
+\paragraph{Changes record} ~\\
+\newpage
+{\footnotesize
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release & Author(s) & Modifications \\
+    \hline
+    {\em   4.0} & {\em ...} & {\em ...} \\
+    {\em   3.6} & {\em ...} & {\em ...} \\
+    {\em   3.4} & {\em ...} & {\em ...} \\
+    {\em <=3.4} & {\em ...} & {\em ...}
+  \end{tabularx}
+}
+\clearpage
 The ASM code adds the functionality to apply increments to the model variables: temperature, salinity,
 …
 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 \nam{\_asminc}.
+This is all controlled by the namelist \nam{_asminc}{\_asminc}.
 There is a brief description of all the namelist options provided.
 To build the ASM code \key{asminc} must be set.
+%===============================================================
+%% =================================================================================================
 \section{Direct initialization}
 \label{sec:ASM_DI}
 …
 Direct initialization (DI) refers to the instantaneous correction of the model background state using
 the analysis increment.
 DI is used when \np{ln\_asmdin} is set to true.
+DI is used when \np{ln_asmdin}{ln\_asmdin} is set to true.
+%% =================================================================================================
 \section{Incremental analysis updates}
 \label{sec:ASM_IAU}
 …
 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.
+IAU is used when \np{ln_asmiau}{ln\_asmiau} is set to true.
 With IAU, the model state trajectory ${\mathbf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$)
 …
 additional tendency terms to the prognostic equations:
 \begin{align*}
   % \label{eq:wa_traj_iau}
+  % \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*}
 …
 Typically the increments are spread evenly over the full window.
 In addition, two different weighting functions have been implemented.
 The first function (namelist option \np{niaufn} = 0) employs constant weights,
+The first function (namelist option \np{niaufn}{niaufn}=0) employs constant weights,
 \begin{align}
   \label{eq:F1_i}
+  \label{eq:ASM_F1_i}
   F^{(1)}_{i}
   =\left\{
 …
 \end{align}
 where $M = m-n$.
 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,
+The second function (namelist option \np{niaufn}{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\{
 …
 \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}.
+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}.
+%==========================================================================
+% Divergence damping description %%%
+%% =================================================================================================
 \section{Divergence damping initialisation}
 \label{sec:ASM_div_dmp}
 …
 \begin{equation}
   \label{eq:asm_dmp}
+  \label{eq:ASM_dmp}
   \left\{
     \begin{aligned}
 …
 \[
   % \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]
 …
 \]
 By the application of \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
 …
 \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 \nam{\_asminc} namelist
+The divergence damping is activated by assigning to \np{nn_divdmp}{nn\_divdmp} in the \nam{_asminc}{\_asminc} namelist
 a value greater than zero.
 This specifies the number of iterations of the divergence damping. Setting a value of the order of 100 will result in a significant reduction in the vertical velocity induced by the increments.
+%==========================================================================
+%% =================================================================================================
 \section{Implementation details}
 \label{sec:ASM_details}
 Here we show an example \nam{\_asminc} namelist and the header of an example assimilation increments file on
+Here we show an example \nam{_asminc}{\_asminc} namelist and the header of an example assimilation increments file on
 the ORCA2 grid.
+%------------------------------------------nam_asminc-----------------------------------------------------
+%
+\nlst{nam_asminc}
+%-------------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{nam_asminc}
+  \caption{\forcode{&nam_asminc}}
+  \label{lst:nam_asminc}
+\end{listing}
 The header of an assimilation increments file produced using the NetCDF tool
 …
 \end{clines}
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_DIA.tex

-                      r11435
+                      r11799
 \begin{document}
+% ================================================================
+% Chapter I/O & Diagnostics
+% ================================================================
 \chapter{Output and Diagnostics (IOM, DIA, TRD, FLO)}
 \label{chap:DIA}
+%    {\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 }  \\
+\thispagestyle{plain}
 \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
+% ================================================================
+\paragraph{Changes record} ~\\
+{\footnotesize
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release & Author(s) & Modifications \\
+    \hline
+    {\em   4.0} & {\em ...} & {\em ...} \\
+    {\em   3.6} & {\em ...} & {\em ...} \\
+    {\em   3.4} & {\em ...} & {\em ...} \\
+    {\em <=3.4} & {\em ...} & {\em ...}
+  \end{tabularx}
+}
+\clearpage
+%% =================================================================================================
 \section{Model output}
 \label{sec:DIA_io_old}
 …
 %\gmcomment{                    % start of gmcomment
+% ================================================================
+% Diagnostics
+% ================================================================
+%% =================================================================================================
 \section{Standard model output (IOM)}
 \label{sec:DIA_iom}
 …
 \begin{enumerate}
+\item
+  The complete and flexible control of the output files through external XML files adapted by
+\item The complete and flexible control of the output files through external XML files adapted by
   the user from standard templates.
+\item
+  To achieve high performance and scalable output through the optional distribution of
+\item To achieve high performance and scalable output through the optional distribution of
   all diagnostic output related tasks to dedicated processes.
 \end{enumerate}
 …
 \begin{itemize}
+\item
+  The choice of output frequencies that can be different for each file (including real months and years).
+\item
+  The choice of file contents; includes complete flexibility over which data are written in which files
+\item The choice of output frequencies that can be different for each file (including real months and years).
+\item The choice of file contents; includes complete flexibility over which data are written in which files
   (the same data can be written in different files).
+\item
+  The possibility to split output files at a chosen frequency.
+\item
+  The possibility to extract a vertical or an horizontal subdomain.
+\item
+  The choice of the temporal operation to perform, \eg: average, accumulate, instantaneous, min, max and once.
+\item
+  Control over metadata via a large XML "database" of possible output fields.
+\item The possibility to split output files at a chosen frequency.
+\item The possibility to extract a vertical or an horizontal subdomain.
+\item The choice of the temporal operation to perform, \eg: average, accumulate, instantaneous, min, max and once.
+\item Control over metadata via a large XML "database" of possible output fields.
 \end{itemize}
 …
 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. }
+file \forcode{numror} can be handled by XIOS. To activate restart reading using XIOS, set \np[=.true. ]{ln_xios_read}{ln\_xios\_read}
 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
 …
 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
+XIOS can also be used to write \NEMO\ restart. A namelist parameter \np{nn_wxios}{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
+for \np[=2]{nn_wxios}{nn\_wxios} 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[=2]{nn_wxios}{nn\_wxios}}. 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
+\begin{enumerate}
+\item 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
+\item 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}
+\end{enumerate}
 An older versions of XIOS do not support reading functionality. It's recommended to use at least XIOS2@1451.
+%% =================================================================================================
 \subsection{XIOS: XML Inputs-Outputs Server}
+%% =================================================================================================
 \subsubsection{Attached or detached mode?}
 …
 \xmlline|<variable id="using_server" type="bool"></variable>|
+The {\ttfamily using\_server} setting determines whether or not the server will be used in \textit{attached mode}
+(as a library) [{\ttfamily> false <}] or in \textit{detached mode}
+(as an external executable on N additional, dedicated cpus) [{\ttfamily > 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''.
 …
 The following subsection provides a typical example but the syntax will vary in different MPP environments.
+%% =================================================================================================
 \subsubsection{Number of cpu used by XIOS in detached mode}
 …
 \cmd|mpirun -np 62 ./nemo.exe : -np 2 ./xios_server.exe|
+%% =================================================================================================
 \subsubsection{Control of XIOS: the context in iodef.xml}
 …
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|lXl|}
     \hline
 …
 \end{table}
+%% =================================================================================================
 \subsection{Practical issues}
+%% =================================================================================================
 \subsubsection{Installation}
 …
 {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.
+\item[2.]
+  If necessary, add \forcode{USE iom ! I/O manager library} to the list of used modules in
+\item in \NEMO\ code, add a \forcode{CALL iom_put( 'identifier', array )} where you want to output a 2D or 3D array.
+\item If necessary, add \forcode{USE iom ! I/O manager library} to the list of used modules in
   the upper part of your module.
+\item[3.]
+  in the field\_def.xml file, add the definition of your variable using the same identifier you used in the f90 code
+\item in the field\_def.xml file, add the definition of your variable using the same identifier you used in the f90 code
   (see subsequent sections for a details of the XML syntax and rules).
   For example:
 \begin{xmllines}
 <field_definition>
 …
 </field_definition>
 \end{xmllines}
 Note your definition must be added to the field\_group whose reference grid is consistent with the size of
 the array passed to iomput.
 …
 (iom\_set\_domain\_attr and iom\_set\_axis\_attr in \mdl{iom}) or defined in the domain\_def.xml file.
 \eg:
 \begin{xmllines}
 <grid id="grid_T_3D" domain_ref="grid_T" axis_ref="deptht"/>
 \end{xmllines}
+Note, if your array is computed within the surface module each \np{nn\_fsbc} time\_step,
+Note, if your array is computed within the surface module each \np{nn_fsbc}{nn\_fsbc} time\_step,
 add the field definition within the field\_group defined with the id "SBC":
 \xmlcode{<field_group id="SBC" ...>} which has been defined with the correct frequency of operations
 (iom\_set\_field\_attr in \mdl{iom})
+\item[4.]
+  add your field in one of the output files defined in iodef.xml
+\item add your field in one of the output files defined in iodef.xml
   (again see subsequent sections for syntax and rules)
 \begin{xmllines}
 <file id="file1" .../>
 …
 </file>
 \end{xmllines}
 \end{enumerate}
+%% =================================================================================================
 \subsection{XML fundamentals}
+%% =================================================================================================
 \subsubsection{ XML basic rules}
 …
 See \href{http://www.xmlnews.org/docs/xml-basics.html}{here} for more details.
+%% =================================================================================================
 \subsubsection{Structure of the XML file used in \NEMO}
 …
 \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
 …
 \begin{table}
-  \scriptsize
   \begin{tabular}{|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
 …
 \end{table}
+%% =================================================================================================
 \subsubsection{Nesting XML files}
 …
 \end{xmllines}
+%% =================================================================================================
 \subsubsection{Use of inheritance}
 …
 Inherit (and overwrite, if needed) the attributes of a tag you are refering to.
+%% =================================================================================================
 \subsubsection{Use of groups}
 …
 \end{xmllines}
+%% =================================================================================================
 \subsection{Detailed functionalities}
 …
 the new functionalities offered by the XML interface of XIOS.
+%% =================================================================================================
 \subsubsection{Define horizontal subdomains}
 …
 We are therefore advising to use the ''one\_file'' type in this case.
+%% =================================================================================================
 \subsubsection{Define vertical zooms}
 …
 \end{xmllines}
+%% =================================================================================================
 \subsubsection{Control of the output file names}
 …
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|lX|}
     \hline
 …
 \noindent will give the following file name radical: \ifile{myfile\_ORCA2\_19891231\_freq1d}
+%% =================================================================================================
 \subsubsection{Other controls of the XML attributes from \NEMO}
 …
 \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}{rn\_rdt}                                                         \\
     \hline
     SBC                                                                  &
     freq\_op                                                             &
     \np{rn\_rdt} $\times$ \np{nn\_fsbc}  \\
+    \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_fsbc}{nn\_fsbc}                                  \\
     \hline
     ptrc\_T                                                              &
     freq\_op                                                             &
     \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\
+    \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_dttrc}{nn\_dttrc}                                 \\
     \hline
     diad\_T                                                              &
     freq\_op                                                             &
     \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\
+    \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_dttrc}{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}
+%% =================================================================================================
 \subsubsection{Advanced use of XIOS functionalities}
+%% =================================================================================================
 \subsection{XML reference tables}
 \label{subsec:IOM_xmlref}
+\label{subsec:DIA_IOM_xmlref}
 \begin{enumerate}
+\item
+  Simple computation: directly define the computation when refering to the variable in the file definition.
+\item Simple computation: directly define the computation when refering to the variable in the file definition.
 \begin{xmllines}
 …
 \end{xmllines}
+\item
+  Simple computation: define a new variable and use it in the file definition.
+\item Simple computation: define a new variable and use it in the file definition.
 in field\_definition:
 …
 sst2 won't be evaluated.
+\item
+  Change of variable precision:
+\item Change of variable precision:
 \begin{xmllines}
 …
 Forcing double precision outputs with prec="8" (for example in the field\_definition) will avoid this problem.
+\item
+  add user defined attributes:
+\item add user defined attributes:
 \begin{xmllines}
 …
 \end{xmllines}
+\item
+  use of the ``@'' function: example 1, weighted temporal average
+\item use of the ``@'' function: example 1, weighted temporal average
  - define a new variable in field\_definition
 …
 Note that in this case, freq\_op must be equal to the file output\_freq.
+\item
+  use of the ``@'' function: example 2, monthly SSH standard deviation
+\item use of the ``@'' function: example 2, monthly SSH standard deviation
  - define a new variable in field\_definition
 …
 Note that in this case, freq\_op must be equal to the file output\_freq.
+\item
+  use of the ``@'' function: example 3, monthly average of SST diurnal cycle
+\item use of the ``@'' function: example 3, monthly average of SST diurnal cycle
  - define 2 new variables in field\_definition
 …
 field\_ref="sst" means that attributes not explicitely defined, are inherited from sst field.
+%% =================================================================================================
 \subsubsection{Tag list per family}
 \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 ("\ttfamily{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 ("\ttfamily{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 ("\ttfamily{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 ("\ttfamily{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 ("\ttfamily{grid\_*}")}
+  \caption{XIOS: grid tags ("\texttt{grid\_*}")}
 \end{table}
+%% =================================================================================================
 \subsubsection{Attributes list per family}
 \begin{table}
-  \scriptsize
   \begin{tabularx}{\textwidth}{|l|X|l|l|}
     \hline
 …
     \hline
   \end{tabularx}
   \caption{Reference attributes ("\ttfamily{*\_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 ("\ttfamily{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}
 …
 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 \nam{run} namelist.
+the namelist parameter \np{ln_cfmeta}{ln\_cfmeta} in the \nam{run}{run} namelist.
 This must be set to true if these metadata are to be included in the output files.
+% ================================================================
+%       NetCDF4 support
+% ================================================================
+\section[NetCDF4 support (\texttt{\textbf{key\_netcdf4}})]
+{NetCDF4 support (\protect\key{netcdf4})}
+%% =================================================================================================
+\section[NetCDF4 support (\texttt{\textbf{key\_netcdf4}})]{NetCDF4 support (\protect\key{netcdf4})}
 \label{sec:DIA_nc4}
 …
 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 \nam{nc4} namelist:
+%------------------------------------------namnc4----------------------------------------------------
+\nlst{namnc4}
+%-------------------------------------------------------------------------------------------------------------
+setting the \np{ln_nc4zip}{ln\_nc4zip} logical to false in the \nam{nc4}{nc4} namelist:
+\begin{listing}
+  \nlst{namnc4}
+  \caption{\forcode{&namnc4}}
+  \label{lst:namnc4}
+\end{listing}
 If \key{netcdf4} has not been defined, these namelist parameters are not read.
 In this case, \np{ln\_nc4zip} is set false and dummy routines for a few NetCDF4-specific functions are defined.
+In this case, \np{ln_nc4zip}{ln\_nc4zip} is set false and dummy routines for a few NetCDF4-specific functions are defined.
 These functions will not be used but need to be included so that compilation is possible with NetCDF3 libraries.
 …
 \end{forlines}
 \noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\ttfamily 46x38x1} respectively in
 the mono-processor case (\ie\ global domain of {\small\ttfamily 182x149x31}).
+\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:NC4} which compares the results of two short runs of the ORCA2\_LIM reference configuration with
+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
 each processing region.
-%------------------------------------------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
 \rou{iom\_put} calls are set via an equivalent and identically named namelist to \nam{nc4} in
+\rou{iom\_put} calls are set via an equivalent and identically named namelist to \nam{nc4}{nc4} in
 \textit{xmlio\_server.def}.
 Typically this namelist serves the mean files whilst the \nam{nc4} in the main namelist file continues to
+Typically this namelist serves the mean files whilst the \nam{nc4}{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 invidual processing regions and different chunking choices may be desired.
+% -------------------------------------------------------------------------------------------------------------
+%       Tracer/Dynamics Trends
+% -------------------------------------------------------------------------------------------------------------
+\section[Tracer/Dynamics trends (\texttt{namtrd})]
+{Tracer/Dynamics trends (\protect\nam{trd})}
+%% =================================================================================================
+\section[Tracer/Dynamics trends (\forcode{&namtrd})]{Tracer/Dynamics trends (\protect\nam{trd}{trd})}
 \label{sec:DIA_trd}
+%------------------------------------------namtrd----------------------------------------------------
+\nlst{namtrd}
+%-------------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{namtrd}
+  \caption{\forcode{&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 \textit{dyn....F90} and/or \textit{tra....F90} routines).
 This capability is controlled by options offered in \nam{trd} namelist.
+This capability is controlled by options offered in \nam{trd}{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.}:
+What is done depends on the \nam{trd}{trd} logical set to \forcode{.true.}:
 \begin{description}
+\item[\np{ln\_glo\_trd}]:
+  at each \np{nn\_trd} time-step a check of the basin averaged properties of
+\item [{\np{ln_glo_trd}{ln\_glo\_trd}}]: at each \np{nn_trd}{nn\_trd} time-step a check of the basin averaged properties of
   the momentum and tracer equations is performed.
   This also includes a check of $T^2$, $S^2$, $\tfrac{1}{2} (u^2+v2)$,
   and potential energy time evolution equations properties;
+\item[\np{ln\_dyn\_trd}]:
+  each 3D trend of the evolution of the two momentum components is output;
+\item[\np{ln\_dyn\_mxl}]:
+  each 3D trend of the evolution of the two momentum components averaged over the mixed layer is output;
+\item[\np{ln\_vor\_trd}]:
+  a vertical summation of the moment tendencies is performed,
+\item [{\np{ln_dyn_trd}{ln\_dyn\_trd}}]: each 3D trend of the evolution of the two momentum components is output;
+\item [{\np{ln_dyn_mxl}{ln\_dyn\_mxl}}]: each 3D trend of the evolution of the two momentum components averaged over the mixed layer is output;
+\item [{\np{ln_vor_trd}{ln\_vor\_trd}}]: a vertical summation of the moment tendencies is performed,
   then the curl is computed to obtain the barotropic vorticity tendencies which are output;
+\item[\np{ln\_KE\_trd}] :
+  each 3D trend of the Kinetic Energy equation is output;
+\item[\np{ln\_tra\_trd}]:
+  each 3D trend of the evolution of temperature and salinity is output;
+\item[\np{ln\_tra\_mxl}]:
+  each 2D trend of the evolution of temperature and salinity averaged over the mixed layer is output;
+\item [{\np{ln_KE_trd}{ln\_KE\_trd}}]  : each 3D trend of the Kinetic Energy equation is output;
+\item [{\np{ln_tra_trd}{ln\_tra\_trd}}]: each 3D trend of the evolution of temperature and salinity is output;
+\item [{\np{ln_tra_mxl}{ln\_tra\_mxl}}]: each 2D trend of the evolution of temperature and salinity averaged over the mixed layer is output;
 \end{description}
 …
 \textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested.
+In particular, options associated with \np{ln\_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl} are not working,
+and none of the options have been tested with variable volume (\ie\ \np{ln\_linssh}\forcode{ = .true.}).
+% -------------------------------------------------------------------------------------------------------------
+%       On-line Floats trajectories
+% -------------------------------------------------------------------------------------------------------------
+\section[FLO: On-Line Floats trajectories (\texttt{\textbf{key\_floats}})]
+{FLO: On-Line Floats trajectories (\protect\key{floats})}
+\label{sec:FLO}
+%--------------------------------------------namflo-------------------------------------------------------
+\nlst{namflo}
+%--------------------------------------------------------------------------------------------------------------
+In particular, options associated with \np{ln_dyn_mxl}{ln\_dyn\_mxl}, \np{ln_vor_trd}{ln\_vor\_trd}, and \np{ln_tra_mxl}{ln\_tra\_mxl} are not working,
+and none of the options have been tested with variable volume (\ie\ \np[=.true.]{ln_linssh}{ln\_linssh}).
+%% =================================================================================================
+\section[FLO: On-Line Floats trajectories (\texttt{\textbf{key\_floats}})]{FLO: On-Line Floats trajectories (\protect\key{floats})}
+\label{sec:DIA_FLO}
+\begin{listing}
+  \nlst{namflo}
+  \caption{\forcode{&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 \nam{flo} namelist variables.
+Options are defined by \nam{flo}{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.}).
+or on a $4^th$ Runge-Hutta algorithm (\np[=.true.]{ln_flork4}{ln\_flork4}).
 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.
+%% =================================================================================================
 \subsubsection{Input data: initial coordinates}
 Initial coordinates can be given with Ariane Tools convention
 (IJK coordinates, (\np{ln\_ariane}\forcode{ = .true.}) ) or with longitude and latitude.
+(IJK coordinates, (\np[=.true.]{ln_ariane}{ln\_ariane}) ) 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}}
+{ \texttt{I J K nisobfl itrash}}
 \noindent with:
 …
 \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.} ),
+\np{jpnflnewflo} can be added in the initialization file.
+\np{jpnfl}{jpnfl} is the total number of floats during the run.
+When initial positions are read in a restart file (\np[=.true.]{ln_rstflo}{ln\_rstflo} ),
+\np{jpnflnewflo}{jpnflnewflo} can be added in the initialization file.
+%% =================================================================================================
 \subsubsection{Output data}
 \np{nn\_writefl} is the frequency of writing in float output file and \np{nn\_stockfl} is the frequency of
+\np{nn_writefl}{nn\_writefl} is the frequency of writing in float output file and \np{nn_stockfl}{nn\_stockfl} is the frequency of
 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[=.true.]{ln_flo_ascii}{ln\_flo\_ascii}).
 In that case, output filename is trajec\_float.
 Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}) with
+Another possiblity of writing format is Netcdf (\np[=.false.]{ln_flo_ascii}{ln\_flo\_ascii}) with
 \key{iomput} and outputs selected in iodef.xml.
 Here it is an example of specification to put in files description section:
 …
 \end{xmllines}
+% -------------------------------------------------------------------------------------------------------------
+%       Harmonic analysis of tidal constituents
+% -------------------------------------------------------------------------------------------------------------
+\section[Harmonic analysis of tidal constituents (\texttt{\textbf{key\_diaharm}})]
+{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}
+%------------------------------------------nam_diaharm----------------------------------------------------
+%
+\nlst{nam_diaharm}
+%----------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{nam_diaharm}
+  \caption{\forcode{&nam_diaharm}}
+  \label{lst:nam_diaharm}
+\end{listing}
 A module is available to compute the amplitude and phase of tidal waves.
 This on-line Harmonic analysis is actived with \key{diaharm}.
 Some parameters are available in namelist \nam{\_diaharm}:
  - \np{nit000\_han} is the first time step used for harmonic analysis
  - \np{nitend\_han} is the  last 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{tname}       is an array with names of tidal constituents to analyse
  \np{nit000\_han} and \np{nitend\_han} must be between \np{nit000} and \np{nitend} of the simulation.
+Some parameters are available in namelist \nam{_diaharm}{\_diaharm}:
+ - \np{nit000_han}{nit000\_han} is the first time step used for harmonic analysis
+ - \np{nitend_han}{nitend\_han} is the  last time step used for harmonic analysis
+ - \np{nstep_han}{nstep\_han}  is the  time step frequency for harmonic analysis
+% - \np{nb_ana}{nb\_ana}     is the number of harmonics to analyse
+ - \np{tname}{tname}       is an array with names of tidal constituents to analyse
+ \np{nit000_han}{nit000\_han} and \np{nitend_han}{nitend\_han} must be between \np{nit000}{nit000} and \np{nitend}{nitend} of the simulation.
  The restart capability is not implemented.
 …
 We obtain in output $C_{j}$ and $S_{j}$ for each tidal wave.
+% -------------------------------------------------------------------------------------------------------------
+%       Sections transports
+% -------------------------------------------------------------------------------------------------------------
+\section[Transports across sections (\texttt{\textbf{key\_diadct}})]
+{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}
+%-------------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{nam_diadct}
+  \caption{\forcode{&nam_diadct}}
+  \label{lst:nam_diadct}
+\end{listing}
 A module is available to compute the transport of volume, heat and salt through sections.
 …
 - \texttt{salt\_transport}   for   salt transports (unit: $10^{9}Kg s^{-1}$) \\
 Namelist variables in \nam{dct} control how frequently the flows are summed and the time scales over which
+Namelist variables in \nam{_diadct}{\_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
+\np{nn\_dctwri}: frequency of writing ( mean of instantaneous transports )
+\np{nn\_debug} : debugging of the section
+\np{nn_dct}{nn\_dct}   : frequency of instantaneous transports computing
+\np{nn_dctwri}{nn\_dctwri}: frequency of writing ( mean of instantaneous transports )
+\np{nn_debug}{nn\_debug} : debugging of the section
+%% =================================================================================================
 \subsubsection{Creating a binary file containing the pathway of each section}
 …
 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:
 …
 \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 \\
 …
  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 \\
 …
+ }
+%% =================================================================================================
 \subsubsection{To read the output files}
 The output format is: \\
 {\scriptsize
+{
   \texttt{
     date, time-step number, section number,                \\
 …
 \begin{table}
-  \scriptsize
   \begin{tabular}{|l|l|l|l|l|}
     \hline
 …
 \end{table}
+% ================================================================
+% Steric effect in sea surface height
+% ================================================================
+%% =================================================================================================
 \section{Diagnosing the steric effect in sea surface height}
 \label{sec:DIA_steric}
 Changes in steric sea level are caused when changes in the density of the water column imply an expansion or
 …
     \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}
 …
 \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 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:
+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}
 \]
 …
 \begin{equation}
   \mathcal{M}_o = \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A}
   \label{eq:M_Bq}
+  \label{eq:DIA_M_Bq}
 \end{equation}
 …
 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:
+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}
 …
 (wetting and drying of grid point is not allowed).
 Third, the discretisation of \autoref{eq:steric_Bq} depends on the type of free surface which is considered.
 In the non linear free surface case, \ie\ \np{ln\_linssh}\forcode{ = .true.}, it is given by
+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[=.true.]{ln_linssh}{ln\_linssh}, 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}
 \]
 …
 \[
   \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}
 \]
 …
 Both steric and thermosteric sea level are computed in \mdl{diaar5}.
+% -------------------------------------------------------------------------------------------------------------
+%       Other Diagnostics
+% -------------------------------------------------------------------------------------------------------------
+\section[Other diagnostics]
+{Other diagnostics}
+%% =================================================================================================
+\section{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 (\textit{diahth.F90})]
 {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 depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth})
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=\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}
+  \centering
+  \includegraphics[width=0.66\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}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+% -----------------------------------------------------------
+%       CMIP specific diagnostics
+% -----------------------------------------------------------
+\subsection[CMIP specific diagnostics (\textit{diaar5.F90}, \textit{diaptr.F90})]
+{CMIP specific diagnostics (\protect\mdl{diaar5})}
+%% =================================================================================================
+\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}.
 …
 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,
+In \mdl{diaptr} when \np[=.true.]{ln_diaptr}{ln\_diaptr}
+(see the \nam{ptr}{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,
+When \np[=.true.]{ln_subbas}{ln\_subbas}, 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}).
+%------------------------------------------namptr-----------------------------------------
+\nlst{namptr}
+%-----------------------------------------------------------------------------------------
+% -----------------------------------------------------------
+%       25 hour mean and hourly Surface, Mid and Bed
+% -----------------------------------------------------------
+the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:DIA_mask_subasins}).
+\begin{listing}
+  \nlst{namptr}
+  \caption{\forcode{&namptr}}
+  \label{lst:namptr}
+\end{listing}
+%% =================================================================================================
 \subsection{25 hour mean output for tidal models}
+%------------------------------------------nam_dia25h-------------------------------------
+\nlst{nam_dia25h}
+%-----------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{nam_dia25h}
+  \caption{\forcode{&nam_dia25h}}
+  \label{lst:nam_dia25h}
+\end{listing}
 A module is available to compute a crudely detided M2 signal by obtaining a 25 hour mean.
 …
 This diagnostic is actived with the logical $ln\_dia25h$.
+% -----------------------------------------------------------
+%     Top Middle and Bed hourly output
+% -----------------------------------------------------------
+%% =================================================================================================
 \subsection{Top middle and bed hourly output}
+%------------------------------------------nam_diatmb-----------------------------------------------------
+\nlst{nam_diatmb}
+%----------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{nam_diatmb}
+  \caption{\forcode{&nam_diatmb}}
+  \label{lst:nam_diatmb}
+\end{listing}
 A module is available to output the surface (top), mid water and bed diagnostics of a set of standard variables.
 …
 This diagnostic is actived with the logical $ln\_diatmb$.
+% -----------------------------------------------------------
+%     Courant numbers
+% -----------------------------------------------------------
+%% =================================================================================================
 \subsection{Courant numbers}
 …
 \[
   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 \nam{ctl} namelist.
+The variables can be activated by setting the \np{nn_diacfl}{nn\_diacfl} namelist parameter to 1 in the \nam{ctl}{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
 …
 The maximum values from the run are also copied to the ocean.output file.
+% ================================================================
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_DIU.tex

-                      r11435
+                      r11799
 \begin{document}
+% ================================================================
+% Diurnal SST models (DIU)
+% Edited by James While
+% ================================================================
 \chapter{Diurnal SST Models (DIU)}
 \label{chap:DIU}
+\thispagestyle{plain}
 \chaptertoc
+\paragraph{Changes record} ~\\
+\newpage
+$\ $\newline % force a new line
+{\footnotesize
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release & Author(s) & Modifications \\
+    \hline
+    {\em   4.0} & {\em ...} & {\em ...} \\
+    {\em   3.6} & {\em ...} & {\em ...} \\
+    {\em   3.4} & {\em ...} & {\em ...} \\
+    {\em <=3.4} & {\em ...} & {\em ...}
+  \end{tabularx}
+}
+\clearpage
 Code to produce an estimate of the diurnal warming and cooling of the sea surface skin
 …
 The skin temperature can be split into three parts:
 \begin{itemize}
+\item
+  A foundation SST which is free from diurnal warming.
+\item
+  A warm layer, typically ~3\,m thick,
+\item A foundation SST which is free from diurnal warming.
+\item A warm layer, typically ~3\,m thick,
   where heating from solar radiation can cause a warm stably stratified layer during the daytime
+\item
+  A cool skin, a thin layer, approximately ~1\, mm thick,
+\item A cool skin, a thin layer, approximately ~1\, mm thick,
   where long wave cooling is dominant and cools the immediate ocean surface.
 \end{itemize}
 …
 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 \nam{diu}:
+Both the cool skin and warm layer models are controlled through the namelist \nam{diu}{diu}:
+\nlst{namdiu}
+\begin{listing}
+  \nlst{namdiu}
+  \caption{\forcode{&namdiu}}
+  \label{lst:namdiu}
+\end{listing}
 This namelist contains only two variables:
 \begin{description}
+\item[\np{ln\_diurnal}]
+  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.
+  \np{ln\_diurnal\_only} must be \forcode{.false.} if \np{ln\_diurnal} is \forcode{.false.}.
+\item [{\np{ln_diurnal}{ln\_diurnal}}] A logical switch for turning on/off both the cool skin and warm layer.
+\item [{\np{ln_diurnal_only}{ln\_diurnal\_only}}] A logical switch which if \forcode{.true.} will run the diurnal model without the other dynamical parts of \NEMO.
+  \np{ln_diurnal_only}{ln\_diurnal\_only} must be \forcode{.false.} if \np{ln_diurnal}{ln\_diurnal} is \forcode{.false.}.
 \end{description}
 …
 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.bidlot.ea_JGR10} (TAKAYA10 model hereafter).
 …
 \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_{\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:ecmwf1}) $\alpha_w=2\times10^{-4}$ is the thermal expansion coefficient of water,
+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 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_{\mathrm{sol}} + Q_{\mathrm{lw}} + Q_{\mathrm{h}}\mbox{,}
   % \label{eq:e_flux_eqn}
+  % \label{eq:DIU_e_flux_eqn}
 \]
 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:ecmwf1} the function $f(L_a)=\max(1,L_a^{\frac{2}{3}})$,
+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.
 …
 In practice the second term acts as a relaxation on the temperature.
+%===============================================================
+%% =================================================================================================
 \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_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}
+  % \label{eq:DIU_sunders_eqn}
   \Delta T_{\mathrm{cs}}=\frac{Q_{\mathrm{ns}}\delta}{k_t} \mbox{,}
 \]
 …
 $\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}
 …
 \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.iudicone.ea_JGR02},
+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}
 …
 \]
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_DOM.tex

-                      r11435
+                      r11799
 \begin{document}
+% ================================================================
+% Chapter 2 ——— Space and Time Domain (DOM)
+% ================================================================
 \chapter{Space Domain (DOM)}
 \label{chap:DOM}
+%\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
+%                  should be put outside of DOM routine (better with TRC staff and off-line
+%                  tracers)
+%  -geo2ocean:  how to switch from geographic to mesh coordinate
+%     - 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:DOMAINcfg})
+    }                                                                                            \\
+    {\em 3.x} & {\em Rachid Benshila, Gurvan Madec \& S\'{e}bastien Masson} &
+    {\em First version}                                                                          \\
+% 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
+%              should be put outside of DOM routine (better with TRC staff and off-line
+%              tracers)
+% - geo2ocean: how to switch from geographic to mesh coordinate
+% -    domclo: closed sea and lakes....
+%              management of closea sea area: specific to global cfg, both forced and coupled
+\thispagestyle{plain}
+\chaptertoc
+\paragraph{Changes record} ~\\
+{\footnotesize
+  \begin{tabularx}{0.8\textwidth}{l||X|X}
+    Release                                                                                 &
+    Author(s)                                                                               &
+    Modifications                                                                           \\
+    \hline
+    {\em 4.0                                                                              } &
+    {\em Simon M\"{u}ller \& Andrew Coward \newline \newline
+      Simona Flavoni and Tim Graham                                                       } &
+    {\em Compatibility changes: many options moved to external domain configuration tools
+      (see \autoref{apdx:DOMCFG}). \newline
+      Updates                                                                             } \\
+    {\em 3.6                                                                              } &
+    {\em Rachid Benshila, Christian \'{E}th\'{e}, Pierre Mathiot and Gurvan Madec         } &
+    {\em Updates                                                                          } \\
+    {\em $\leq$ 3.4                                                                       } &
+    {\em Gurvan Madec and 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 discretisation \autoref{chap:STP},
+}
+\clearpage
+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 relevant information about the DOM (DOMain) source code modules.
+% ================================================================
+% Fundamentals of the Discretisation
+% ================================================================
+%% =================================================================================================
 \section{Fundamentals of the discretisation}
 \label{sec:DOM_basics}
+% -------------------------------------------------------------------------------------------------------------
+%        Arrangement of Variables
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsection{Arrangement of variables}
 \label{subsec:DOM_cell}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!tb]
+  \begin{center}
+    \includegraphics[width=\textwidth]{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}
+\begin{figure}
+  \centering
+  \includegraphics[width=0.33\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.
+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 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}).
+This is the generalisation to three dimensions of the well-known ``C'' grid in Arakawa's classification
+\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
+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}.
+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}.
+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:DOM_cell}).
+This is the generalisation to three dimensions of the well-known ``C'' grid in
+Arakawa's classification \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 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: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:MB_scale_factors}.
 As a result, the mesh on which partial derivatives $\pd[]{\lambda}$, $\pd[]{\varphi}$ and
 $\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.
+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.
 An important point here is that the partial derivative of the scale factors must be evaluated by
 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}).
+This preserves the symmetry of the discrete set of equations and
+therefore satisfies many of 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 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 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})
+    }
+  \end{center}
+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}
+  \centering
+  \begin{tabular}{|l|l|l|l|}
+    \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}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 Note that the definition of the scale factors
 …
 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:zgr_e3}.
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=\textwidth]{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}
+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}
+  \centering
+  \includegraphics[width=0.5\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}
 \label{subsec:DOM_operators}
 Given the values of a variable $q$ at adjacent points, the differencing and averaging operators at
 the midpoint between them are:
+Given the values of a variable $q$ at adjacent points,
+the differencing and averaging operators at 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 the $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:
 \[
+\begin{gather*}
   % \label{eq:DOM_grad}
   \nabla q \equiv   \frac{1}{e_{1u}} \delta_{i + 1/2} [q] \; \, \vect i
                   + \frac{1}{e_{2v}} \delta_{j + 1/2} [q] \; \, \vect j
+                  + \frac{1}{e_{3w}} \delta_{k + 1/2} [q] \; \, \vect k
+\]
+\begin{multline*}
+                  + \frac{1}{e_{3w}} \delta_{k + 1/2} [q] \; \, \vect k \\
   % \label{eq:DOM_lap}
   \Delta q \equiv   \frac{1}{e_{1t} \, e_{2t} \, e_{3t}}
                     \; \lt[   \delta_i \lt( \frac{e_{2u} \, e_{3u}}{e_{1u}} \; \delta_{i + 1/2} [q] \rt)
                             + \delta_j \lt( \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [q] \rt) \; \rt] \\
+                            + \delta_j \lt( \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [q] \rt) \; \rt]
                   + \frac{1}{e_{3t}}
                               \delta_k \lt[ \frac{1              }{e_{3w}} \; \delta_{k + 1/2} [q] \rt]
+\end{multline*}
+Following \autoref{eq:PE_curl} and \autoref{eq:PE_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
+\end{gather*}
+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:
 \begin{multline}
+\begin{multline*}
 % \label{eq:DOM_curl}
   \nabla \times \vect A \equiv   \frac{1}{e_{2v} \, e_{3vw}}
 …
                                  \Big[   \delta_{i + 1/2} (e_{2v} \, a_2)
                                        - \delta_{j + 1/2} (e_{1u} \, a_1) \Big] \vect k
 \end{multline}
 \begin{equation}
+\end{multline*}
+\[
 % \label{eq:DOM_div}
   \nabla \cdot \vect A \equiv   \frac{1}{e_{1t} \, e_{2t} \, e_{3t}}
                                 \Big[ \delta_i (e_{2u} \, e_{3u} \, a_1) + \delta_j (e_{1v} \, e_{3v} \, a_2) \Big]
                               + \frac{1}{e_{3t}} \delta_k (a_3)
 \end{equation}
 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):
+\]
+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 $\sum \limits_k$ refers to a summation over
+all grid points of the same type in the direction indicated by the subscript (here $k$).
+$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$).
 In continuous form, the following properties are satisfied:
 …
 \end{gather}
 It is straightforward to demonstrate that these properties are verified locally in discrete form as soon as
 the scalar $q$ is taken at $t$-points and the vector $\vect A$ has its components defined at
+It is straightforward to demonstrate that these properties are verified locally in discrete form as
+soon as the scalar $q$ is taken at $t$-points and the vector $\vect A$ has its components defined at
 vector points $(u,v,w)$.
 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
+\begin{alignat}{4}
+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
+\begin{alignat}{5}
   \label{eq:DOM_di_adj}
   &\sum \limits_i a_i \; \delta_i [b]      &\equiv &- &&\sum \limits_i \delta      _{   i + 1/2} [a] &b_{i + 1/2} \\
 …
 \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
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsection{Numerical indexing}
 \label{subsec:DOM_Num_Index}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!tb]
+  \begin{center}
+    \includegraphics[width=\textwidth]{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}
+\begin{figure}
+  \centering
+  \includegraphics[width=0.33\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.
+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.
+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
+% -----------------------------------
+Furthermore, the direction of the vertical indexing has been reversed and
+the surface level set at $k = 1$.
+%% =================================================================================================
 \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}).
+(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
+% -----------------------------------
+%% =================================================================================================
 \subsubsection{Vertical indexing}
 \label{subsec:DOM_Num_Index_vertical}
 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 the $t$-level just below
 (\autoref{fig:index_vert}).
+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 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:index_vert}).
+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:index_hor} and \autoref{fig:index_vert}).
+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} is included in the \fortran implementations of
+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[width=\textwidth]{Fig_index_vert}
+    \caption{
+      \protect\label{fig:index_vert}
+      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.
+    }
+  \end{center}
+\begin{figure}
+  \centering
+  \includegraphics[width=0.33\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}
-\nlst{namcfg}
 Two typical methods are available to specify the spatial domain configuration;
+they can be selected using parameter \np{ln\_read\_cfg} parameter in namelist \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.},
+they can be selected using parameter \np{ln_read_cfg}{ln\_read\_cfg} parameter in
+namelist \nam{cfg}{cfg}.
+If \np{ln_read_cfg}{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}{cn\_domcfg} parameter in namelist \nam{cfg}{cfg}.
+If \np{ln_read_cfg}{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.
+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
 …
 to run similar models with and without partial bottom boxes and/or sigma-coordinates,
 supporting such choices leads to overly complex code.
+Worse still is the difficulty of ensuring the model configurations intended to be identical are indeed so when
+the model domain itself can be altered by runtime selections.
+The code previously used to perform vertical discretisation has been incorporated into an external tool
+(\path{./tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMAINcfg}.
+The next subsections summarise the parameter and fields related to the configuration of the whole model domain.
+These represent the minimum information that must be provided either via the \np{cn\_domcfg} file or set by code
+inserted into user-supplied versions of the \texttt{usrdef\_*} subroutines.
+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}{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
+% -----------------------------------
+%% =================================================================================================
 \subsection{Domain size}
 \label{subsec:DOM_size}
 The total size of the computational domain is set by the parameters \jp{jpiglo}, \jp{jpjglo} and \jp{jpkglo} for
 the $i$, $j$ and $k$ directions, respectively.
 Note, that the variables \texttt{jpi} and \texttt{jpj} refer to the size of each processor subdomain when
 the code is run in parallel using domain decomposition (\key{mpp\_mpi} defined,
 see \autoref{sec:LBC_mpp}).
 The name of the configuration is set through parameter \np{cn\_cfg},
 and the nominal resolution through parameter \np{nn\_cfg}
+The total size of the computational domain is set by the parameters \jp{jpiglo}, \jp{jpjglo} and
+\jp{jpkglo} for the $i$, $j$ and $k$ directions, respectively.
+Note, that the variables \texttt{jpi} and \texttt{jpj} refer to
+the size of each processor subdomain when the code is run in parallel using domain decomposition
+(\key{mpp\_mpi} defined, see \autoref{sec:LBC_mpp}).
+The name of the configuration is set through parameter \np{cn_cfg}{cn\_cfg},
+and the nominal resolution through parameter \np{nn_cfg}{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).
+in which case \np{cn_cfg}{cn\_cfg} and \np{nn_cfg}{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})}
+See \autoref{sec:LBC_jperio} for details on the available options and
+the corresponding values for \jp{jperio}.
+%% =================================================================================================
+\subsection[Horizontal grid mesh (\textit{domhgr.F90}]{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.
+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                                     */
+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:cell} for the respective grid-point position.
+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)                    */
+                        /* 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}
 …
 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
+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:
+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}{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{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})}
+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.
+%% =================================================================================================
+\subsection[Vertical grid (\textit{domzgr.F90})]{Vertical grid (\protect\mdl{domzgr})}
 \label{subsec:DOM_zgr}
+%-----------------------------------------namdom-------------------------------------------
+\nlst{namdom}
+%-------------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{namdom}
+  \caption{\forcode{&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.
+\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]
   \begin{center}
     \includegraphics[width=\textwidth]{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}
+\begin{figure}
+  \centering
+  \includegraphics[width=0.5\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:
+    \begin{enumerate*}[label=(\textit{\alph*})]
+    \item $z$-coordinate with full step,
+    \item $z$-coordinate with partial step,
+    \item $s$-coordinate: terrain following representation,
+    \item hybrid $s-z$ coordinate,
+    \item hybrid $s-z$ coordinate with partial step, and
+    \item same as (e) but in the non-linear free surface
+      (\protect\np[=.false.]{ln_linssh}{ln\_linssh}).
+  \end{enumerate*}
+  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.
+In v4.0 the linear free surface option is implemented as
+a special case of the non-linear free surface.
 This is computationally wasteful since it uses the structures for time-varying 3D metrics
 for fields that (in the linear free surface case) are fixed.
+However, the linear free-surface is rarely used and implementing it this way means
+a single configuration file can support both options.
+By default a non-linear free surface is used (\np{ln\_linssh} set to \forcode{ = .false.} in \nam{dom}):
+the coordinate follow the time-variation of the free surface so that the transformation is time dependent:
+$z(i,j,k,t)$ (\eg\ \autoref{fig:z_zps_s_sps}f).
+When a linear free surface is assumed (\np{ln\_linssh} set to \forcode{ = .true.} in \nam{dom}),
+the vertical coordinates are fixed in time, but the seawater can move up and down across the $z_0$ surface
+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}{ln\_linssh} set to \forcode{=.false.} in \nam{dom}{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}{ln\_linssh} set to \forcode{=.true.} in \nam{dom}{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.
+\np{ln_zco}{ln\_zco}, \np{ln_zps}{ln\_zps}, \np{ln_sco}{ln\_sco} and \np{ln_isfcav}{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.
+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}{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:z_zps_s_sps}a-c):
+The decision on these choices must be made when the \np{cn_domcfg}{cn\_domcfg} file is constructed.
+Three main choices are offered (\autoref{fig:DOM_z_zps_s_sps}a-c):
 \begin{itemize}
 \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.}).
+\item $z$-coordinate with full step bathymetry (\np[=.true.]{ln_zco}{ln\_zco}),
+\item $z$-coordinate with partial step ($zps$) bathymetry (\np[=.true.]{ln_zps}{ln\_zps}),
+\item Generalized, $s$-coordinate (\np[=.true.]{ln_sco}{ln\_sco}).
 \end{itemize}
 Additionally, hybrid combinations of the three main coordinates are available:
 $s-z$ or $s-zps$ coordinate (\autoref{fig:z_zps_s_sps}d and \autoref{fig:z_zps_s_sps}e).
+$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,
+A setting of \np{ln_isfcav}{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.
+Within the model,
+the arrays describing the grid point depths and vertical scale factors are
+three set of three dimensional arrays $(i,j,k)$ defined at
+\textit{before}, \textit{now} and \textit{after} time step.
 The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively.
 They are updated at each model time step.
 The initial fixed reference coordinate system is held in variable names with a $\_0$ suffix.
 When the linear free surface option is used (\np{ln\_linssh}\forcode{ = .true.}),
+When the linear free surface option is used (\np[=.true.]{ln_linssh}{ln\_linssh}),
 \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}
 …
 \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.
+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}
 …
 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.
+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.
+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}
 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  <    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}
+  \\
+  umask(i,j,k) &= &  &tmask(i,j,k) * tmask(i + 1,j,    k) \\
+  vmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i    ,j + 1,k) \\
+  fmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i + 1,j,    k) \\
+               &  &* &tmask(i,j,k) * tmask(i + 1,j,    k) \\
+  wmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i    ,j,k - 1) \\
+  \text{with~} wmask(i,j,1) &= & &tmask(i,j,1)
+\end{alignat*}
+\begin{align*}
+  tmask(i,j,k) &=
+  \begin{cases}
+&\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} \\
+  umask(i,j,k) &= tmask(i,j,k) * tmask(i + 1,j,    k) \\
+  vmask(i,j,k) &= tmask(i,j,k) * tmask(i    ,j + 1,k) \\
+  fmask(i,j,k) &= tmask(i,j,k) * tmask(i + 1,j,    k) * tmask(i,j,k) * tmask(i + 1,j,    k) \\
+  wmask(i,j,k) &= tmask(i,j,k) * tmask(i    ,j,k - 1) \\
+  \text{with~} wmask(i,j,1) &= tmask(i,j,1)
+\end{align*}
 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)
+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)
 exactly in the same way as for the bottom boundary.
 …
 %% (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.
+%% =================================================================================================
+\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.
+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)     */
+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}
-\nlst{namcfg}
 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}.
+(grid-point position, scale factors) can be saved in a file if
+namelist parameter \np{ln_write_cfg}{ln\_write\_cfg} (namelist \nam{cfg}{cfg}) is set to
+\forcode{.true.};
+the output filename is set through parameter \np{cn_domcfg_out}{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.
-\nlst{namdom}
 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.}.
+(grid-point position, scale factors, depths and masks) can be saved in
+a file called \texttt{mesh\_mask} if
+namelist parameter \np{ln_meshmask}{ln\_meshmask} (namelist \nam{dom}{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 (\textit{istate.F90} and \textit{dtatsd.F90})]
 {Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})}
 \label{sec:DTA_tsd}
+%-----------------------------------------namtsd-------------------------------------------
 \nlst{namtsd}
+%------------------------------------------------------------------------------------------
 Basic initial state options are defined in \nam{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}
+\begin{listing}
+  \nlst{namtsd}
+  \caption{\forcode{&namtsd}}
+  \label{lst:namtsd}
+\end{listing}
+Basic initial state options are defined in \nam{tsd}{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.
+the initialization of temperature and salinity fields is controlled through the \np{ln_tsd_init}{ln\_tsd\_init} namelist parameter.
 \begin{description}
+\item[\np{ln\_tsd\_init}\forcode{= .true.}]
+  Use T and S input files that can be given on the model grid itself or on their native input data grids.
+  In the latter case, the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid
+\item [{\np[=.true.]{ln_tsd_init}{ln\_tsd\_init}}] Use T and S input files that can be given on
+  the model grid itself or on their native input data grids.
+  In the latter case,
+  the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid
   (see \autoref{subsec:SBC_iof}).
+  The information relating to the input files are specified in the \np{sn\_tem} and \np{sn\_sal} structures.
+  The information relating to the input files are specified in
+  the \np{sn_tem}{sn\_tem} and \np{sn_sal}{sn\_sal} structures.
   The computation is done in the \mdl{dtatsd} module.
 \item[\np{ln\_tsd\_init}\forcode{= .false.}]
   Initial values for T and S are set via a user supplied \rou{usr\_def\_istate} routine contained in \mdl{userdef\_istate}.
+\item [{\np[=.false.]{ln_tsd_init}{ln\_tsd\_init}}] Initial values for T and S are set via
+  a user supplied \rou{usr\_def\_istate} routine contained in \mdl{userdef\_istate}.
   The default version sets horizontally uniform T and profiles as used in the GYRE configuration
   (see \autoref{sec:CFG_gyre}).
+  (see \autoref{sec:CFGS_gyre}).
 \end{description}
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_DYN.tex

-                      r11435
+                      r11799
 \begin{document}
+% ================================================================
+% Chapter ——— Ocean Dynamics (DYN)
+% ================================================================
 \chapter{Ocean Dynamics (DYN)}
 \label{chap:DYN}
+\thispagestyle{plain}
 \chaptertoc
+\paragraph{Changes record} ~\\
+{\footnotesize
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release & Author(s) & Modifications \\
+    \hline
+    {\em   4.0} & {\em ...} & {\em ...} \\
+    {\em   3.6} & {\em ...} & {\em ...} \\
+    {\em   3.4} & {\em ...} & {\em ...} \\
+    {\em <=3.4} & {\em ...} & {\em ...}
+  \end{tabularx}
+}
+\clearpage
 Using the representation described in \autoref{chap:DOM},
 …
 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
 MISC correspond to "extracting tendency terms" or "vorticity balance"?}
+% ================================================================
+% Sea Surface Height evolution & Diagnostics variables
+% ================================================================
+%% =================================================================================================
 \section{Sea surface height and diagnostic variables ($\eta$, $\zeta$, $\chi$, $w$)}
 \label{sec:DYN_divcur_wzv}
+%--------------------------------------------------------------------------------------------------------------
+%           Horizontal divergence and relative vorticity
+%--------------------------------------------------------------------------------------------------------------
+\subsection[Horizontal divergence and relative vorticity (\textit{divcur.F90})]
+{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}
+  \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)
 …
 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]
 …
 the nonlinear advection and of the vertical velocity respectively.
+%--------------------------------------------------------------------------------------------------------------
+%           Sea Surface Height evolution
+%--------------------------------------------------------------------------------------------------------------
+\subsection[Horizontal divergence and relative vorticity (\textit{sshwzv.F90})]
+{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}
 …
 \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
 …
 taking into account the change of the thickness of the levels:
 \begin{equation}
   \label{eq:wzv}
+  \label{eq:DYN_wzv}
   \left\{
     \begin{aligned}
 …
 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}
+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}).
+% ================================================================
+% Coriolis and Advection terms: vector invariant form
+% ================================================================
+%% =================================================================================================
 \section{Coriolis and advection: vector invariant form}
 \label{sec:DYN_adv_cor_vect}
+%-----------------------------------------nam_dynadv----------------------------------------------------
+\nlst{namdyn_adv}
+%-------------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{namdyn_adv}
+  \caption{\forcode{&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.
 The flux form option (see next section) has been present since version $2$.
 Options are defined through the \nam{dyn\_adv} namelist variables Coriolis and
+Options are defined through the \nam{dyn_adv}{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).
 …
 \autoref{chap:LBC}.
+% -------------------------------------------------------------------------------------------------------------
+%        Vorticity term
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Vorticity term (\textit{dynvor.F90})]
+{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}
+%-------------------------------------------------------------------------------------------------------------
+Options are defined through the \nam{dyn\_vor} namelist variables.
+Four discretisations of the vorticity term (\texttt{ln\_dynvor\_xxx}\forcode{ = .true.}) are available:
+\begin{listing}
+  \nlst{namdyn_vor}
+  \caption{\forcode{&namdyn_vor}}
+  \label{lst:namdyn_vor}
+\end{listing}
+Options are defined through the \nam{dyn_vor}{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[=.true.]{ln_dynvor_con}{ln\_dynvor\_con}).
 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 (\forcode{ln_dynvor_ens = .true.})]
+{Enstrophy conserving scheme (\protect\np{ln\_dynvor\_ens}\forcode{ = .true.})}
+%% =================================================================================================
+\subsubsection[Enstrophy conserving scheme (\forcode{ln_dynvor_ens})]{Enstrophy conserving scheme (\protect\np{ln_dynvor_ens}{ln\_dynvor\_ens})}
 \label{subsec:DYN_vor_ens}
 …
 It is given by:
 \begin{equation}
   \label{eq:dynvor_ens}
+  \label{eq:DYN_vor_ens}
   \left\{
     \begin{aligned}
 …
 \end{equation}
-%-------------------------------------------------------------
 %                 energy conserving scheme
+%-------------------------------------------------------------
+\subsubsection[Energy conserving scheme (\forcode{ln_dynvor_ene = .true.})]
+{Energy conserving scheme (\protect\np{ln\_dynvor\_ene}\forcode{ = .true.})}
+%% =================================================================================================
+\subsubsection[Energy conserving scheme (\forcode{ln_dynvor_ene})]{Energy conserving scheme (\protect\np{ln_dynvor_ene}{ln\_dynvor\_ene})}
 \label{subsec:DYN_vor_ene}
 …
 It is given by:
 \begin{equation}
   \label{eq:dynvor_ene}
+  \label{eq:DYN_vor_ene}
   \left\{
     \begin{aligned}
 …
 \end{equation}
-%-------------------------------------------------------------
 %                 mix energy/enstrophy conserving scheme
+%-------------------------------------------------------------
+\subsubsection[Mixed energy/enstrophy conserving scheme (\forcode{ln_dynvor_mix = .true.})]
+{Mixed energy/enstrophy conserving scheme (\protect\np{ln\_dynvor\_mix}\forcode{ = .true.})}
+%% =================================================================================================
+\subsubsection[Mixed energy/enstrophy conserving scheme (\forcode{ln_dynvor_mix})]{Mixed energy/enstrophy conserving scheme (\protect\np{ln_dynvor_mix}{ln\_dynvor\_mix})}
 \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 (\forcode{ln_dynvor_een = .true.})]
+{Energy and enstrophy conserving scheme (\protect\np{ln\_dynvor\_een}\forcode{ = .true.})}
+%% =================================================================================================
+\subsubsection[Energy and enstrophy conserving scheme (\forcode{ln_dynvor_een})]{Energy and enstrophy conserving scheme (\protect\np{ln_dynvor_een}{ln\_dynvor\_een})}
 \label{subsec:DYN_vor_een}
 …
 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.gnanadesikan.ea_JPO98} for the discretization of the iso-neutral diffusion operator (see \autoref{apdx:C}).
+\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
 …
 First consider the discrete expression of the potential vorticity, $q$, defined at an $f$-point:
 \[
   % \label{eq:pot_vor}
+  % \label{eq:DYN_pot_vor}
   q  = \frac{\zeta +f} {e_{3f} }
 \]
 where the relative vorticity is defined by (\autoref{eq:divcur_cur}),
+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:een_e3f}
+  \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=\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=0.66\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[=1]{nn_een_e3f}{nn\_een\_e3f}), or just by $4$ (\np[=.true.]{nn_een_e3f}{nn\_een\_e3f}).
 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.
 …
 (\autoref{fig:DYN_een_triad}):
 \begin{equation}
   \label{eq:Q_triads}
+  \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)
 …
 Finally, the vorticity terms are represented as:
 \begin{equation}
   \label{eq:dynvor_een}
+  \label{eq:DYN_vor_een}
   \left\{ {
       \begin{aligned}
 …
 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.penduff.ea_OM09}.
 …
 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 (\textit{dynkeg.F90})]
+{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 (\textit{dynzad.F90})]
+{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[=.true.]{ln_dynzad_zts}{ln\_dynzad\_zts},
 a split-explicit time stepping with 5 sub-timesteps is used on the vertical advection term.
 This option can be useful when the value of the timestep is limited by vertical advection \citep{lemarie.debreu.ea_OM15}.
 Note that in this case,
 a similar split-explicit time stepping should be used on vertical advection of tracer to ensure a better stability,
+an option which is only available with a TVD scheme (see \np{ln\_traadv\_tvd\_zts} in \autoref{subsec:TRA_adv_tvd}).
+% ================================================================
+% Coriolis and Advection : flux form
+% ================================================================
+an option which is only available with a TVD scheme (see \np{ln_traadv_tvd_zts}{ln\_traadv\_tvd\_zts} in \autoref{subsec:TRA_adv_tvd}).
+%% =================================================================================================
 \section{Coriolis and advection: flux form}
 \label{sec:DYN_adv_cor_flux}
+%------------------------------------------nam_dynadv----------------------------------------------------
+\nlst{namdyn_adv}
+%-------------------------------------------------------------------------------------------------------------
+Options are defined through the \nam{dyn\_adv} namelist variables.
+Options are defined through the \nam{dyn_adv}{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,
 …
 no slip or partial slip boundary conditions are applied following \autoref{chap:LBC}.
+%--------------------------------------------------------------------------------------------------------------
+%           Coriolis plus curvature metric terms
+%--------------------------------------------------------------------------------------------------------------
+\subsection[Coriolis plus curvature metric terms (\textit{dynvor.F90})]
+{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}
 …
 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]
 …
 \end{multline*}
 Any of the (\autoref{eq:dynvor_ens}), (\autoref{eq:dynvor_ene}) and (\autoref{eq:dynvor_een}) schemes can be used to
+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.
+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 (\textit{dynadv.F90})]
+{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}
 …
 or a $3^{rd}$ order upstream biased scheme, UBS.
 The latter is described in \citet{shchepetkin.mcwilliams_OM05}.
 The schemes are selected using the namelist logicals \np{ln\_dynadv\_cen2} and \np{ln\_dynadv\_ubs}.
+The schemes are selected using the namelist logicals \np{ln_dynadv_cen2}{ln\_dynadv\_cen2} and \np{ln_dynadv_ubs}{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$.
-%-------------------------------------------------------------
 %                 2nd order centred scheme
+%-------------------------------------------------------------
+\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.})}
+%% =================================================================================================
+\subsubsection[CEN2: $2^{nd}$ order centred scheme (\forcode{ln_dynadv_cen2})]{CEN2: $2^{nd}$ order centred scheme (\protect\np{ln_dynadv_cen2}{ln\_dynadv\_cen2})}
 \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}
 …
 so $u$ and $v$ are the \emph{now} velocities.
-%-------------------------------------------------------------
 %                 UBS scheme
+%-------------------------------------------------------------
+\subsubsection[UBS: Upstream Biased Scheme (\forcode{ln_dynadv_ubs = .true.})]
+{UBS: Upstream Biased Scheme (\protect\np{ln\_dynadv\_ubs}\forcode{ = .true.})}
+%% =================================================================================================
+\subsubsection[UBS: Upstream Biased Scheme (\forcode{ln_dynadv_ubs})]{UBS: Upstream Biased Scheme (\protect\np{ln_dynadv_ubs}{ln\_dynadv\_ubs})}
 \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}
 …
 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.}),
+(\ie\ \np[=]{ln_dynldf_lap}{ln\_dynldf\_lap}\np[=.false.]{ln_dynldf_bilap}{ln\_dynldf\_bilap}),
 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.
+$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,
 …
 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.de-cuevas.ea_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.
 …
 there is also the possibility of using a $4^{th}$ order evaluation of the advective velocity as in ROMS.
 This is an error and should be suppressed soon.
-%%%
 \gmcomment{action :  this have to be done}
+%%%
+% ================================================================
+%           Hydrostatic pressure gradient term
+% ================================================================
+\section[Hydrostatic pressure gradient (\textit{dynhpg.F90})]
+{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}
+%-------------------------------------------------------------------------------------------------------------
+Options are defined through the \nam{dyn\_hpg} namelist variables.
+\begin{listing}
+  \nlst{namdyn_hpg}
+  \caption{\forcode{&namdyn_hpg}}
+  \label{lst:namdyn_hpg}
+\end{listing}
+Options are defined through the \nam{dyn_hpg}{dyn\_hpg} namelist variables.
 The key distinction between the different algorithms used for
 the hydrostatic pressure gradient is the vertical coordinate used,
 …
 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 (\forcode{ln_dynhpg_zco = .true.})]
+{Full step $Z$-coordinate (\protect\np{ln\_dynhpg\_zco}\forcode{ = .true.})}
+%% =================================================================================================
+\subsection[Full step $Z$-coordinate (\forcode{ln_dynhpg_zco})]{Full step $Z$-coordinate (\protect\np{ln_dynhpg_zco}{ln\_dynhpg\_zco})}
 \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}
 …
 for $1<k<km$ (interior layer)
 \begin{equation}
   \label{eq:dynhpg_zco}
+  \label{eq:DYN_hpg_zco}
   \left\{
     \begin{aligned}
 …
 \end{equation}
 Note that the $1/2$ factor in (\autoref{eq:dynhpg_zco_surf}) is adequate because of the definition of $e_{3w}$ as
+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 (\texttt{vvl?} defined),
+the surface pressure gradient is included in \autoref{eq:dynhpg_zco_surf} and
+\autoref{eq:dynhpg_zco} through the space and time variations of the vertical scale factor $e_{3w}$.
+%--------------------------------------------------------------------------------------------------------------
+%           z-coordinate with partial step
+%--------------------------------------------------------------------------------------------------------------
+\subsection[Partial step $Z$-coordinate (\forcode{ln_dynhpg_zps = .true.})]
+{Partial step $Z$-coordinate (\protect\np{ln\_dynhpg\_zps}\forcode{ = .true.})}
+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}$.
+%% =================================================================================================
+\subsection[Partial step $Z$-coordinate (\forcode{ln_dynhpg_zps})]{Partial step $Z$-coordinate (\protect\np{ln_dynhpg_zps}{ln\_dynhpg\_zps})}
 \label{subsec:DYN_hpg_zps}
 …
 module \mdl{zpsdhe} located in the TRA directory and described in \autoref{sec:TRA_zpshde}.
+%--------------------------------------------------------------------------------------------------------------
+%           s- and s-z-coordinates
+%--------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsection{$S$- and $Z$-$S$-coordinates}
 \label{subsec:DYN_hpg_sco}
 …
 density Jacobian with cubic polynomial method is currently disabled whilst known bugs are under investigation.
 $\bullet$ Traditional coding (see for example \citet{madec.delecluse.ea_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[=.true.]{ln_dynhpg_sco}{ln\_dynhpg\_sco})
+\begin{equation}
+  \label{eq:DYN_hpg_sco}
   \left\{
     \begin{aligned}
 …
 Where the first term is the pressure gradient along coordinates,
 computed as in \autoref{eq:dynhpg_zco_surf} - \autoref{eq:dynhpg_zco},
+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$ Traditional coding with adaptation for ice shelf cavities (\np[=.true.]{ln_dynhpg_isf}{ln\_dynhpg\_isf}).
+This scheme need the activation of ice shelf cavities (\np[=.true.]{ln_isfcav}{ln\_isfcav}).
+$\bullet$ Pressure Jacobian scheme (prj) (a research paper in preparation) (\np[=.true.]{ln_dynhpg_prj}{ln\_dynhpg\_prj})
 $\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
+(\np[=.true.]{ln_dynhpg_djc}{ln\_dynhpg\_djc}) (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 (\np[=.true.]{ln_dynhpg_prj}{ln\_dynhpg\_prj}) is available as
+an improved option to \np[=.true.]{ln_dynhpg_sco}{ln\_dynhpg\_sco} when \texttt{vvl?} is active.
 The pressure Jacobian scheme uses a constrained cubic spline to
 reconstruct the density profile across the water column.
 …
 This method can provide a more accurate calculation of the horizontal pressure gradient than the standard scheme.
+%% =================================================================================================
 \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[=.true.]{ln_dynhpg_isf}{ln\_dynhpg\_isf}).\\
 The main hypothesis to compute the ice shelf load is that the ice shelf is in an isostatic equilibrium.
 …
 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:dynhpg_sco} described in
+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 (\forcode{ln_dynhpg_imp = .{true,false}.})]
+{Time-scheme (\protect\np{ln\_dynhpg\_imp}\forcode{ = .\{true,false\}}.)}
+%% =================================================================================================
+\subsection[Time-scheme (\forcode{ln_dynhpg_imp})]{Time-scheme (\protect\np{ln_dynhpg_imp}{ln\_dynhpg\_imp})}
 \label{subsec:DYN_hpg_imp}
 …
 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}
+$\bullet$ leapfrog scheme (\np[=.true.]{ln_dynhpg_imp}{ln\_dynhpg\_imp}):
+\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[=.true.]{ln_dynhpg_imp}{ln\_dynhpg\_imp}):
+\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[=.true.]{ln_dynhpg_imp}{ln\_dynhpg\_imp}.
 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
 …
 Note that in the semi-implicit case, it is necessary to save the filtered density,
 an extra three-dimensional field, in the restart file to restart the model with exact reproducibility.
+This option is controlled by  \np{nn\_dynhpg\_rst}, a namelist parameter.
+% ================================================================
+% Surface Pressure Gradient
+% ================================================================
+\section[Surface pressure gradient (\textit{dynspg.F90})]
+{Surface pressure gradient (\protect\mdl{dynspg})}
+This option is controlled by  \np{nn_dynhpg_rst}{nn\_dynhpg\_rst}, a namelist parameter.
+%% =================================================================================================
+\section[Surface pressure gradient (\textit{dynspg.F90})]{Surface pressure gradient (\protect\mdl{dynspg})}
 \label{sec:DYN_spg}
+%-----------------------------------------nam_dynspg----------------------------------------------------
+\nlst{namdyn_spg}
+%------------------------------------------------------------------------------------------------------------
+Options are defined through the \nam{dyn\_spg} namelist variables.
+The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:PE_hor_pg}).
+\begin{listing}
+  \nlst{namdyn_spg}
+  \caption{\forcode{&namdyn_spg}}
+  \label{lst:namdyn_spg}
+\end{listing}
+Options are defined through the \nam{dyn_spg}{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, \texttt{vvl?} is defined).
 In the linear free surface case (\autoref{subsec:PE_free_surface})
+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}).
+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?}),
+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,
 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;
 …
 As a consequence the update of the $next$ velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}.
+%--------------------------------------------------------------------------------------------------------------
+% Explicit free surface formulation
+%--------------------------------------------------------------------------------------------------------------
+\subsection[Explicit free surface (\texttt{ln\_dynspg\_exp}\forcode{ = .true.})]
+{Explicit free surface (\protect\np{ln\_dynspg\_exp}\forcode{ = .true.})}
+%% =================================================================================================
+\subsection[Explicit free surface (\forcode{ln_dynspg_exp})]{Explicit free surface (\protect\np{ln_dynspg_exp}{ln\_dynspg\_exp})}
 \label{subsec:DYN_spg_exp}
 In the explicit free surface formulation (\np{ln\_dynspg\_exp} set to true),
+In the explicit free surface formulation (\np{ln_dynspg_exp}{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).
 …
 is thus simply given by :
 \begin{equation}
   \label{eq:dynspg_exp}
+  \label{eq:DYN_spg_exp}
   \left\{
     \begin{aligned}
 …
 Thus, nothing is done in the \mdl{dynspg\_exp} module.
+%--------------------------------------------------------------------------------------------------------------
+% Split-explict free surface formulation
+%--------------------------------------------------------------------------------------------------------------
+\subsection[Split-explicit free surface (\texttt{ln\_dynspg\_ts}\forcode{ = .true.})]
+{Split-explicit free surface (\protect\np{ln\_dynspg\_ts}\forcode{ = .true.})}
+%% =================================================================================================
+\subsection[Split-explicit free surface (\forcode{ln_dynspg_ts})]{Split-explicit free surface (\protect\np{ln_dynspg_ts}{ln\_dynspg\_ts})}
 \label{subsec:DYN_spg_ts}
-%------------------------------------------namsplit-----------------------------------------------------------
+%
 %\nlst{namsplit}
+%-------------------------------------------------------------------------------------------------------------
+The split-explicit free surface formulation used in \NEMO\ (\np{ln\_dynspg\_ts} set to true),
+The split-explicit free surface formulation used in \NEMO\ (\np{ln_dynspg_ts}{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
+the \np{nn_baro}{nn\_baro} namelist parameter as: $\rdt_e = \rdt / nn\_baro$.
+This parameter can be optionally defined automatically (\np[=.true.]{ln_bt_nn_auto}{ln\_bt\_nn\_auto}) 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.
+Therefore, $\rdt_e$ is adjusted so that the Maximum allowed Courant number is smaller than \np{rn\_bt\_cmax}.
+%%%
+Therefore, $\rdt_e$ is adjusted so that the Maximum allowed Courant number is smaller than \np{rn_bt_cmax}{rn\_bt\_cmax}.
 The barotropic mode solves the following equations:
 % \begin{subequations}
 %  \label{eq:BT}
 \begin{equation}
   \label{eq:BT_dyn}
+%  \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}
 …
 \end{equation}
 \[
   % \label{eq:BT_ssh}
+  % \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
 \]
 …
 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}.
 …
 (see their figure 12, lower left).
-%>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=\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=0.66\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}{nn\_baro} barotropic time steps is used
+    (\np[=1]{nn_bt_flt}{nn\_bt\_flt}) and \np[=5]{nn_baro}{nn\_baro}.
+    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[=.true.]{ln_bt_fw}{ln\_bt\_fw},  \protect\np[=.true.]{ln_bt_av}{ln\_bt\_av}.
+    b) Centred time integration:
+    \protect\np[=.false.]{ln_bt_fw}{ln\_bt\_fw}, \protect\np[=.true.]{ln_bt_av}{ln\_bt\_av}.
+    c) Forward time integration with no time filtering (POM-like scheme):
+    \protect\np[=.true.]{ln_bt_fw}{ln\_bt\_fw},  \protect\np[=.false.]{ln_bt_av}{ln\_bt\_av}.}
+  \label{fig:DYN_spg_ts}
 \end{figure}
+%>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >
+In the default case (\np{ln\_bt\_fw}\forcode{ = .true.}),
+In the default case (\np[=.true.]{ln_bt_fw}{ln\_bt\_fw}),
 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[=.true.]{ln_bt_av}{ln\_bt\_av}).
 In that case, the integration is extended slightly beyond \textit{after} time step to
 provide time filtered quantities.
 …
 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.}).
 Although more computationaly expensive ( \np{nn\_baro} additional iterations are indeed necessary),
+(\np[=.false.]{ln_bt_fw}{ln\_bt\_fw}).
+Although more computationaly expensive ( \np{nn_baro}{nn\_baro} additional iterations are indeed necessary),
 the baroclinic to barotropic forcing term given at \textit{now} time step become centred in
 the middle of the integration window.
 …
 %references to Patrick Marsaleix' work here. Also work done by SHOM group.
-%%%
 As far as tracer conservation is concerned,
 …
 obtain exact conservation.
-%%%
 One can eventually choose to feedback instantaneous values by not using any time filter
 (\np{ln\_bt\_av}\forcode{ = .false.}).
+(\np[=.false.]{ln_bt_av}{ln\_bt\_av}).
 In that case, external mode equations are continuous in time,
 \ie\ they are not re-initialized when starting a new sub-stepping sequence.
 …
 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
 …
 }            %%end gm comment (copy of griffies book)
+%>>>>>===============
+%--------------------------------------------------------------------------------------------------------------
+% Filtered free surface formulation
+%--------------------------------------------------------------------------------------------------------------
+\subsection[Filtered free surface (\texttt{dynspg\_flt?})]
+{Filtered free surface (\protect\texttt{dynspg\_flt?})}
+%% =================================================================================================
+\subsection{Filtered free surface (\forcode{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 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}.
 …
 \gmcomment{               %%% copy from chap-model basics
   \[
     % \label{eq:spg_flt}
+    % \label{eq:DYN_spg_flt}
     \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= {\mathrm {\mathbf M}}
     - g \nabla \left( \tilde{\rho} \ \eta \right)
 …
   $\widetilde{\rho} = \rho / \rho_o$ is the dimensionless density,
   and $\mathrm {\mathbf M}$ represents the collected contributions of the Coriolis, hydrostatic pressure gradient,
   non-linear and viscous terms in \autoref{eq:PE_dyn}.
+  non-linear and viscous terms in \autoref{eq:MB_dyn}.
 }   %end gmcomment
 …
 It is computed once and for all and applies to all ocean time steps.
+% ================================================================
+% Lateral diffusion term
+% ================================================================
+\section[Lateral diffusion term and operators (\textit{dynldf.F90})]
+{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}
+%-------------------------------------------------------------------------------------------------------------
+Options are defined through the \nam{dyn\_ldf} namelist variables.
+\begin{listing}
+  \nlst{namdyn_ldf}
+  \caption{\forcode{&namdyn_ldf}}
+  \label{lst:namdyn_ldf}
+\end{listing}
+Options are defined through the \nam{dyn_ldf}{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;
 …
 \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,
 …
+}
+% ================================================================
+\subsection[Iso-level laplacian (\forcode{ln_dynldf_lap = .true.})]
+{Iso-level laplacian operator (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})}
+%% =================================================================================================
+\subsection[Iso-level laplacian (\forcode{ln_dynldf_lap})]{Iso-level laplacian operator (\protect\np{ln_dynldf_lap}{ln\_dynldf\_lap})}
 \label{subsec:DYN_ldf_lap}
 For lateral iso-level diffusion, the discrete operator is:
 \begin{equation}
   \label{eq:dynldf_lap}
+  \label{eq:DYN_ldf_lap}
   \left\{
     \begin{aligned}
 …
 \end{equation}
 As explained in \autoref{subsec:PE_ldf},
+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.
+%--------------------------------------------------------------------------------------------------------------
+%           Rotated laplacian operator
+%--------------------------------------------------------------------------------------------------------------
+\subsection[Rotated laplacian (\forcode{ln_dynldf_iso = .true.})]
+{Rotated laplacian operator (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})}
+%% =================================================================================================
+\subsection[Rotated laplacian (\forcode{ln_dynldf_iso})]{Rotated laplacian operator (\protect\np{ln_dynldf_iso}{ln\_dynldf\_iso})}
 \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[=.true.]{ln_dynldf_iso}{ln\_dynldf\_iso}) and
+for either iso-neutral (\np[=.true.]{ln_dynldf_iso}{ln\_dynldf\_iso}) or
+geopotential (\np[=.true.]{ln_dynldf_hor}{ln\_dynldf\_hor}) 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[=.true.]{ln_dynldf_hor}{ln\_dynldf\_hor}.
 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} } \\
 …
 The way these slopes are evaluated is given in the lateral physics chapter (\autoref{chap:LDF}).
+%--------------------------------------------------------------------------------------------------------------
+%           Iso-level bilaplacian operator
+%--------------------------------------------------------------------------------------------------------------
+\subsection[Iso-level bilaplacian (\forcode{ln_dynldf_bilap = .true.})]
+{Iso-level bilaplacian operator (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})}
+%% =================================================================================================
+\subsection[Iso-level bilaplacian (\forcode{ln_dynldf_bilap})]{Iso-level bilaplacian operator (\protect\np{ln_dynldf_bilap}{ln\_dynldf\_bilap})}
 \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,
 while the third derivative terms normal to the coast are set to zero (see \autoref{chap:LBC}).
-%%%
 \gmcomment{add a remark on the the change in the position of the coefficient}
+%%%
+% ================================================================
+%           Vertical diffusion term
+% ================================================================
+\section[Vertical diffusion term (\textit{dynzdf.F90})]
+{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 \nam{zdf} namelist variables.
+Options are defined through the \nam{zdf}{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[=.true.]{ln_zdfexp}{ln\_zdfexp}) using a time splitting technique (\np{nn_zdfexp}{nn\_zdfexp} $>$ 1) or
+$(b)$ a backward (or implicit) time differencing scheme (\np[=.false.]{ln_zdfexp}{ln\_zdfexp})
+(see \autoref{chap:TD}).
+Note that namelist variables \np{ln_zdfexp}{ln\_zdfexp} and \np{nn_zdfexp}{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 }
 …
 The turbulent flux of momentum at the bottom of the ocean is specified through a bottom friction parameterisation
+(see \autoref{sec:ZDF_bfr})
+% ================================================================
+% External Forcing
+% ================================================================
+(see \autoref{sec:ZDF_drg})
+%% =================================================================================================
 \section{External forcings}
 \label{sec:DYN_forcing}
 …
 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}),
+(1) When \np[=.true.]{ln_apr_dyn}{ln\_apr\_dyn} (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[=.true.]{ln_tide_pot}{ln\_tide\_pot} and \np[=.true.]{ln_tide}{ln\_tide} (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
+(3) When \np[=2]{nn_ice_embd}{nn\_ice\_embd} 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.
 \gmcomment{ missing : the lateral boundary condition !!!   another external forcing
+ }
+% ================================================================
+% 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).
 …
 by setting $\mathrm{ln\_wd\_dl} = \mathrm{.true.}$ and $\mathrm{ln\_wd\_il} = \mathrm{.false.}$.
+\nlst{namwad}
+\begin{listing}
+  \nlst{namwad}
+  \caption{\forcode{&namwad}}
+  \label{lst:namwad}
+\end{listing}
 The following terminology is used. The depth of the topography (positive downwards)
 …
 The final sub-section covers some additional considerations that are relevant to both schemes.
-%-----------------------------------------------------------------------------------------
 %   Iterative limiters
+%-----------------------------------------------------------------------------------------
+\subsection[Directional limiter (\textit{wet\_dry.F90})]
+{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 \np{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}{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 \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.
+If the user sets \np[=.false.]{ln_wd_dl_ramp}{ln\_wd\_dl\_ramp} then zuwdmask is 1 when the
+flux is from a cell with water depth greater than \np{rn_wdmin1}{rn\_wdmin1} and 0 otherwise. If the user sets
+\np[=.true.]{ln_wd_dl_ramp}{ln\_wd\_dl\_ramp} the flux across the face is ramped down as the water depth decreases
+from 2 * \np{rn_wdmin1}{rn\_wdmin1} to \np{rn_wdmin1}{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
 …
 treatment in the calculation of the flux of mass across the cell face.
 \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
 …
 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 \np{ln\_wd\_dl\_bc}\forcode{ = .true.}, the
+to equal their mean value during the barotropic steps. If the user sets \np[=.true.]{ln_wd_dl_bc}{ln\_wd\_dl\_bc}, the
 baroclinic velocities are also multiplied by a suitably weighted average of zuwdmask.
-%-----------------------------------------------------------------------------------------
 %   Iterative limiters
+%-----------------------------------------------------------------------------------------
+\subsection[Iterative limiter (\textit{wet\_dry.F90})]
+{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.F90})]
 {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}
+\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 (\ref{dyn_wd_continuity_coef}) gives an
+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}
 …
 directional limiter does.
-%----------------------------------------------------------------------------------------
 %      Surface pressure gradients
+%----------------------------------------------------------------------------------------
+\subsubsection[Modification of surface pressure gradients (\textit{dynhpg.F90})]
+{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}.
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht] \begin{center}
+\includegraphics[width=\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}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+column.  The three possible combinations are illustrated in \autoref{fig:DYN_WAD_dynhpg}.
+\begin{figure}[!ht]
+  \centering
+  \includegraphics[width=0.66\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}
 The first logical, $\mathrm{ll\_tmp1}$, is set to true if and only if the water depth at
 …
 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.F90})]
 {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
 …
 in uncoupled integrations the net surface heat fluxes need to be appropriately limited.
-%----------------------------------------------------------------------------------------
 %      The WAD test cases
+%----------------------------------------------------------------------------------------
+\subsection[The WAD test cases (\textit{usrdef\_zgr.F90})]
+{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 (\textit{dynnxt.F90})]
+{Time evolution term (\protect\mdl{dynnxt})}
+%% =================================================================================================
+\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 \nam{dom} namelist variables.
+Options are defined through the \nam{dom}{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 (\texttt{vvl?} defined),
 where it has to be applied to the thickness weighted velocity (see \autoref{sec:A_momentum})
+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.} ; \texttt{vvl?} not defined):
 \[
   % \label{eq:dynnxt_vec}
+(\np[=.true.]{ln_dynhpg_vec}{ln\_dynhpg\_vec} ; \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.} ; \texttt{vvl?} defined):
 \[
   % \label{eq:dynnxt_flux}
+(\np[=.false.]{ln_dynhpg_vec}{ln\_dynhpg\_vec} ; \texttt{vvl?} defined):
+\[
+  % \label{eq:DYN_nxt_flux}
   \left\{
     \begin{aligned}
 …
 where RHS is the right hand side of the momentum equation,
 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}.
+$\gamma$ is initialized as \np{nn_atfp}{nn\_atfp} (namelist parameter).
+Its default value is \np[=10.e-3]{nn_atfp}{nn\_atfp}.
 In both cases, the modified Asselin filter is not applied since perfect conservation is not an issue for
 the momentum equations.
 …
 and only array swapping and Asselin filtering is done in \mdl{dynnxt}.
+% ================================================================
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_LBC.tex

-                      r11445
+                      r11799
 \begin{document}
+% ================================================================
+% Chapter — Lateral Boundary Condition (LBC)
+% ================================================================
 \chapter{Lateral Boundary Condition (LBC)}
 \label{chap:LBC}
+\thispagestyle{plain}
 \chaptertoc
+\newpage
+\paragraph{Changes record} ~\\
+{\footnotesize
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release & Author(s) & Modifications \\
+    \hline
+    {\em   4.0} & {\em ...} & {\em ...} \\
+    {\em   3.6} & {\em ...} & {\em ...} \\
+    {\em   3.4} & {\em ...} & {\em ...} \\
+    {\em <=3.4} & {\em ...} & {\em ...}
+  \end{tabularx}
+}
+\clearpage
 %gm% add here introduction to this chapter
+% ================================================================
+% Boundary Condition at the Coast
+% ================================================================
+\section[Boundary condition at the coast (\texttt{rn\_shlat})]
+{Boundary condition at the coast (\protect\np{rn\_shlat})}
+%% =================================================================================================
+\section[Boundary condition at the coast (\forcode{rn_shlat})]{Boundary condition at the coast (\protect\np{rn_shlat}{rn\_shlat})}
 \label{sec:LBC_coast}
+%--------------------------------------------nam_lbc-------------------------------------------------------
+\nlst{namlbc}
+%--------------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{namlbc}
+  \caption{\forcode{&namlbc}}
+  \label{lst:namlbc}
+\end{listing}
 %The lateral ocean boundary conditions contiguous to coastlines are Neumann conditions for heat and salt
 …
 %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.
+Options are defined through the \nam{lbc}{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.
 …
 \[
   % \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
 …
 (normal velocity $u$ remains zero at the coast) (\autoref{fig:LBC_uv}).
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=\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=0.66\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}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 For momentum the situation is a bit more complex as two boundary conditions must be provided along the coast
 …
 and is required in order to compute the vorticity at the coast.
 Four different types of lateral boundary condition are available,
 controlled by the value of the \np{rn\_shlat} namelist parameter
+controlled by the value of the \np{rn_shlat}{rn\_shlat} namelist parameter
 (The value of the mask$_{f}$ array along the coastline is set equal to this parameter).
 These are:
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!p]
+  \begin{center}
+    \includegraphics[width=\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=0.66\textwidth]{Fig_LBC_shlat}
+  \caption[Lateral boundary conditions]{
+    Lateral boundary conditions
+    (a) free-slip                       (\protect\np[=0]{rn_shlat}{rn\_shlat});
+    (b) no-slip                         (\protect\np[=2]{rn_shlat}{rn\_shlat});
+    (c) "partial" free-slip (\forcode{0<}\protect\np[<2]{rn_shlat}{rn\_shlat}) and
+    (d) "strong" no-slip    (\forcode{2<}\protect\np{rn_shlat}{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[=0]{rn_shlat}{rn\_shlat}})] 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,
 …
   (\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[=2]{rn_shlat}{rn\_shlat}})] 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 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
+\item ["partial" free-slip boundary condition (0$<$\np{rn_shlat}{rn\_shlat}$<$2)] the tangential velocity at
   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$.
 \item["strong" no-slip boundary condition (2$<$\np{rn\_shlat}):] the viscous boundary layer is assumed to
+\item ["strong" no-slip boundary condition (2$<$\np{rn_shlat}{rn\_shlat})] the viscous boundary layer is assumed to
   be smaller than half the grid size (\autoref{fig:LBC_shlat}-d).
   The friction is thus larger than in the no-slip case.
 …
 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 (\texttt{jperio})]
+{Model domain boundary condition (\protect\jp{jperio})}
+%% =================================================================================================
+\section[Model domain boundary condition (\forcode{jperio})]{Model domain boundary condition (\protect\jp{jperio})}
 \label{sec:LBC_jperio}
 …
 The north-fold boundary condition is associated with the 3-pole ORCA mesh.
+% -------------------------------------------------------------------------------------------------------------
+%        Closed, cyclic (\jp{jperio}\forcode{ = 0..2})
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Closed, cyclic (\forcode{jperio = [0127]})]
+{Closed, cyclic (\protect\jp{jperio}\forcode{ = [0127]})}
+%% =================================================================================================
+\subsection[Closed, cyclic (\forcode{=0,1,2,7})]{Closed, cyclic (\protect\jp{jperio}\forcode{=0,1,2,7})}
 \label{subsec:LBC_jperio012}
 The choice of closed or cyclic model domain boundary condition is made by
 setting \jp{jperio} to 0, 1, 2 or 7 in namelist \nam{cfg}.
+setting \jp{jperio} to 0, 1, 2 or 7 in namelist \nam{cfg}{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$,
 …
 \begin{description}
+\item[For closed boundary (\jp{jperio}\forcode{ = 0})],
+  solid walls are imposed at all model boundaries:
+\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 (\jp{jperio}\forcode{ = 1})],
+  first and last rows are set to zero (closed) whilst the first column is set to
+\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
   (\autoref{fig:LBC_jperio}-a).
   Whatever flows out of the eastern (western) end of the basin enters the western (eastern) end.
+\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
+\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
   (\autoref{fig:LBC_jperio}-a).
   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 (\jp{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=\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=0.66\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)$
+% -------------------------------------------------------------------------------------------------------------
+\subsection[North-fold (\forcode{jperio = [3-6]})]
+{North-fold (\protect\jp{jperio}\forcode{ = [3-6]})}
+%% =================================================================================================
+\subsection[North-fold (\forcode{=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=\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=0.66\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
+% ====================================================================
+\section[Exchange with neighbouring processors (\textit{lbclnk.F90}, \textit{lib\_mpp.F90})]
+{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}
+\begin{listing}
+  \nlst{nammpp}
+  \caption{\forcode{&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.
 …
 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).
+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=\textwidth]{Fig_mpp}
+    \caption{
+      \protect\label{fig:mpp}
+      Positioning of a sub-domain when massively parallel processing is used.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=0.66\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  \nam{mpp} 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}{jpni} and the j-axis by \np{jpnj}{jpnj}.
+These parameters are defined in \nam{mpp}{mpp} namelist.
+If \np{jpni}{jpni} and \np{jpnj}{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 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:
+\[
+  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.
+\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:
 \[
   % \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 \nam{mpp} namelist,
+the algorithm in the \rou{inimpp2} routine sets each processor's parameters (nbound, nono, noea,...) so that
+the land-only processors are not taken into account.
+\gmcomment{Note that the inimpp2 routine is general so that the original inimpp
+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}{jpni} and \np{jpnj}{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}{jpni}, \np{jpnj}{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}{jpni} and \np{jpnj}{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}{jpni} and \np{jpnj}{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}{ln\_list} activated. In this case, the model will start the initialisation phase, print the list of optimum decompositions ($N_{mpi}$, \np{jpni}{jpni} and \np{jpnj}{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}{jpni}, \np{jpnj}{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}{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}{nn\_msh}).
 \begin{figure}[!ht]
+  \begin{center}
+    \includegraphics[width=\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=0.66\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
+% ====================================================================
+%% =================================================================================================
 \section{Unstructured open boundary conditions (BDY)}
 \label{sec:LBC_bdy}
+%-----------------------------------------nambdy--------------------------------------------
+\nlst{nambdy}
+%-----------------------------------------------------------------------------------------------
+%-----------------------------------------nambdy_dta--------------------------------------------
+\nlst{nambdy_dta}
+%-----------------------------------------------------------------------------------------------
+Options are defined through the \nam{bdy} \nam{bdy\_dta} namelist variables.
+\begin{listing}
+  \nlst{nambdy}
+  \caption{\forcode{&nambdy}}
+  \label{lst:nambdy}
+\end{listing}
+\begin{listing}
+  \nlst{nambdy_dta}
+  \caption{\forcode{&nambdy_dta}}
+  \label{lst:nambdy_dta}
+\end{listing}
+Options are defined through the \nam{bdy}{bdy} and \nam{bdy_dta}{bdy\_dta} namelist variables.
 The BDY module is the core implementation of open boundary conditions for regional configurations on
 temperature, salinity, barotropic and baroclinic velocities, as well as ice concentration, ice and snow thicknesses.
+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
 …
 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[=.true.]{ln_bdy}{ln\_bdy} .
 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 \nam{bdy\_index} must be included separately, one for each set.
+If the set is defined by a file, then a ``\ifile{coordinates.bdy}'' file must be provided.
+The number of boundary sets is defined by \np{nb_bdy}{nb\_bdy}.
+Each boundary set can be either defined as a series of straight line segments directly in the namelist
+(\np[=.false.]{ln_coords_file}{ln\_coords\_file}, and a namelist block \nam{bdy_index}{bdy\_index} must be included for each set) or read in from a file (\np[=.true.]{ln_coords_file}{ln\_coords\_file}, 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}.\\
+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}{cn\_tra} and \np{nn_tra_dta}{nn\_tra\_dta} for tracers).\\
 The choice of algorithm is currently as follows:
 \begin{description}
 \item[\forcode{'none'}:] No boundary condition applied.
+\item [\forcode{'none'}:] No boundary condition applied.
   So the solution will ``see'' the land points around the edge of the edge of the domain.
 \item[\forcode{'specified'}:] Specified boundary condition applied (only available for baroclinic velocity and tracer variables).
 \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{'flather'}:] Flather radiation scheme for the barotropic variables only.
+\item [\forcode{'specified'}:] Specified boundary condition applied (only available for baroclinic velocity and tracer variables).
+\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{'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}).
+The boundary data is either set to initial conditions
+(\np[=0]{nn_tra_dta}{nn\_tra\_dta}) or forced with external data from a file (\np[=1]{nn_tra_dta}{nn\_tra\_dta}).
 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 bdy code can derived baroclinic and barotropic velocities by setting \np[=.true.]{ln_full_vel}{ln\_full\_vel}
 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 \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
+itself (\np[=2]{nn_dyn2d_dta}{nn\_dyn2d\_dta}) or in addition to other external data (\np[=3]{nn_dyn2d_dta}{nn\_dyn2d\_dta}).\\
+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}{rn\_ice\_sal}, \np{rn_ice_tem}{rn\_ice\_tem}, \np{rn_ice_apnd}{rn\_ice\_apnd}, \np{rn_ice_hpnd}{rn\_ice\_hpnd}). Ice age is constant and defined by \np{rn_ice_age}{rn\_ice\_age}.
+If external boundary data is required then the \nam{bdy_dta}{bdy\_dta} namelist must be defined.
+One \nam{bdy_dta}{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}{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 \nam{bdy\_dta} namelist is in the format required for fldread.
+so the \nam{bdy_dta}{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.\\
+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,
+If \np{nn_bdy_jpk}{nn\_bdy\_jpk}$<-1$, it is assumed that the lateral boundary data are already on the native grid.
+However, if \np{nn_bdy_jpk}{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.
 …
 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}
+\label{subsec:LBC_bdy_FRS_scheme}
 The Flow Relaxation Scheme (FRS) \citep{davies_QJRMS76,engedahl_T95},
 …
 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
 \]
 …
 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
 \]
 The width of the FRS zone is specified in the namelist as \np{nn\_rimwidth}.
+The width of the FRS zone is specified in the namelist as \np{nn_rimwidth}{nn\_rimwidth}.
 This is typically set to a value between 8 and 10.
 %----------------------------------------------
+%% =================================================================================================
 \subsection{Flather radiation scheme}
 \label{subsec:BDY_flather_scheme}
+\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.
 %----------------------------------------------
+%% =================================================================================================
 \subsection{Orlanski radiation scheme}
 \label{subsec:BDY_orlanski_scheme}
+\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
 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.\\
+Generally the relaxation time scale at inward propagation points (\np{rn_time_dmp}{rn\_time\_dmp}) is set much shorter than the time scale at outward propagation
+points (\np{rn_time_dmp_out}{rn\_time\_dmp\_out}) so that the solution is constrained more strongly by the external data at inward propagation points.
+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: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.\\
 %----------------------------------------------
+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.
 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.
 This time scale ($\alpha$) is weighted by the distance ($d$) from the boundary over \np{nn\_rimwidth} cells ($N$):
+\label{subsec:LBC_bdy_relaxation}
+In addition to a specific boundary condition specified as \np{cn_tra}{cn\_tra} and \np{cn_dyn3d}{cn\_dyn3d}, relaxation on baroclinic velocities and tracers variables are available.
+It is control by the namelist parameter \np{ln_tra_dmp}{ln\_tra\_dmp} and \np{ln_dyn3d_dmp}{ln\_dyn3d\_dmp} for each boundary set.
+The relaxation time scale value (\np{rn_time_dmp}{rn\_time\_dmp} and \np{rn_time_dmp_out}{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}{nn\_rimwidth} cells ($N$):
 \[
 …
 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 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
 …
 \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[>1]{nn_rimwidth}{nn\_rimwidth}.
 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, based on the description of geometrical setup given above.
+\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$.
 …
 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.
+This can be done by reading a mask file defined as \np{cn_mask_file}{cn\_mask\_file} in the nam\_bdy namelist.
 Only one mask file is used even if multiple boundary sets are defined.
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=\textwidth]{Fig_LBC_bdy_geom}
+    \caption {
+      \protect\label{fig:LBC_bdy_geom}
+      Example of geometry of unstructured open boundary
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=0.66\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.
 …
 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 {\itshape 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=\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=0.66\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
+This is controlled  by the \np{ln_vol}{ln\_vol} parameter in the namelist.
+A value of \np[=.false.]{ln_vol}{ln\_vol} indicates that this option is not used.
+Two options to control the volume are available (\np{nn_volctl}{nn\_volctl}).
+If \np[=0]{nn_volctl}{nn\_volctl} 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[=1]{nn_volctl}{nn\_volctl} 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.
 …
 applied to all boundaries at once.
 %----------------------------------------------
+%% =================================================================================================
 \subsection{Tidal harmonic forcing}
+\label{subsec:BDY_tides}
+%-----------------------------------------nambdy_tide--------------------------------------------
+\nlst{nambdy_tide}
+%-----------------------------------------------------------------------------------------------
+\label{subsec:LBC_bdy_tides}
+\begin{listing}
+  \nlst{nambdy_tide}
+  \caption{\forcode{&nambdy_tide}}
+  \label{lst:nambdy_tide}
+\end{listing}
 Tidal forcing at open boundaries requires the activation of surface
 tides (i.e., in \nam{\_tide}, \np{ln\_tide} needs to be set to
+tides (i.e., in \nam{_tide}{\_tide}, \np{ln_tide}{ln\_tide} needs to be set to
 \forcode{.true.} and the required constituents need to be activated by
 including their names in the \np{clname} array; see
+including their names in the \np{clname}{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
 \nam{bdy\_tide} namelist parameters.\\
+\nam{bdy_tide}{bdy\_tide} namelist parameters.\\
 The tidal harmonic data at open boundaries can be specified in two
 different ways, either on a two-dimensional grid covering the entire
 model domain or along open boundary segments; these two variants can
 be selected by setting \np{ln\_bdytide\_2ddta } to \forcode{.true.} or
+be selected by setting \np{ln_bdytide_2ddta }{ln\_bdytide\_2ddta } to \forcode{.true.} or
 \forcode{.false.}, respectively. In either case, the real and
 imaginary parts of SSH and the two barotropic velocity components for
 …
 separately: when two-dimensional data is used, variables
 \textit{tcname\_z1} and \textit{tcname\_z2} for real and imaginary SSH,
 respectively, are expected in input file \np{filtide} with suffix
+respectively, are expected in input file \np{filtide}{filtide} with suffix
 \ifile{\_grid\_T}, variables \textit{tcname\_u1} and
 \textit{tcname\_u2} for real and imaginary u, respectively, are
 expected in input file \np{filtide} with suffix \ifile{\_grid\_U}, and
+expected in input file \np{filtide}{filtide} with suffix \ifile{\_grid\_U}, and
 \textit{tcname\_v1} and \textit{tcname\_v2} for real and imaginary v,
 respectively, are expected in input file \np{filtide} with suffix
+respectively, are expected in input file \np{filtide}{filtide} with suffix
 \ifile{\_grid\_V}; when data along open boundary segments is used,
 variables \textit{z1} and \textit{z2} (real and imaginary part of SSH)
 are expected to be available from file \np{filtide} with suffix
+are expected to be available from file \np{filtide}{filtide} with suffix
 \ifile{tcname\_grid\_T}, variables \textit{u1} and \textit{u2} (real
 and imaginary part of u) are expected to be available from file
 \np{filtide} with suffix \ifile{tcname\_grid\_U}, and variables
+\np{filtide}{filtide} with suffix \ifile{tcname\_grid\_U}, and variables
 \textit{v1} and \textit{v2} (real and imaginary part of v) are
 expected to be available from file \np{filtide} with suffix
 \ifile{tcname\_grid\_V}. If \np{ln\_bdytide\_conj} is set to
+expected to be available from file \np{filtide}{filtide} with suffix
+\ifile{tcname\_grid\_V}. If \np{ln_bdytide_conj}{ln\_bdytide\_conj} is set to
 \forcode{.true.}, the data is expected to be in complex conjugate
 form.
 …
 direction of rotation). %, e.g. anticlockwise or clockwise.
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_LDF.tex

-                      r11435
+                      r11799
 \begin{document}
-% ================================================================
-% Chapter Lateral Ocean Physics (LDF)
-% ================================================================
 \chapter{Lateral Ocean Physics (LDF)}
 \label{chap:LDF}
+\thispagestyle{plain}
 \chaptertoc
+\newpage
+The lateral physics terms in the momentum and tracer equations have been described in \autoref{eq:PE_zdf} and
+\paragraph{Changes record} ~\\
+{\footnotesize
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release & Author(s) & Modifications \\
+    \hline
+    {\em   4.0} & {\em ...} & {\em ...} \\
+    {\em   3.6} & {\em ...} & {\em ...} \\
+    {\em   3.4} & {\em ...} & {\em ...} \\
+    {\em <=3.4} & {\em ...} & {\em ...}
+  \end{tabularx}
+}
+\clearpage
+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 \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:triad}
+%-----------------------------------namtra_ldf - namdyn_ldf--------------------------------------------
+\nlst{namtra_ldf}
+\nlst{namdyn_ldf}
+%--------------------------------------------------------------------------------------------------------------
+% ================================================================
+% Lateral Mixing Operator
+% ================================================================
+\section[Lateral mixing operators]
+{Lateral mixing operators}
+(see the \nam{tra_ldf}{tra\_ldf} and \nam{dyn_ldf}{dyn\_ldf} below).
+Note that this chapter describes the standard implementation of iso-neutral tracer mixing.
+Griffies's implementation, which is used if \np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad},
+is described in \autoref{apdx:TRIADS}
+%% =================================================================================================
+\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.},
+%% =================================================================================================
+\subsection[No lateral mixing (\forcode{ln_traldf_OFF} \& \forcode{ln_dynldf_OFF})]{No lateral mixing (\protect\np{ln_traldf_OFF}{ln\_traldf\_OFF} \& \protect\np{ln_dynldf_OFF}{ln\_dynldf\_OFF})}
+It is possible to run without explicit lateral diffusion on tracers (\protect\np[=.true.]{ln_traldf_OFF}{ln\_traldf\_OFF}) and/or
+momentum (\protect\np[=.true.]{ln_dynldf_OFF}{ln\_dynldf\_OFF}). The latter option is even recommended if using the
+UBS advection scheme on momentum (\np[=.true.]{ln_dynadv_ubs}{ln\_dynadv\_ubs},
 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
+%% =================================================================================================
+\subsection[Laplacian mixing (\forcode{ln_traldf_lap} \& \forcode{ln_dynldf_lap})]{Laplacian mixing (\protect\np{ln_traldf_lap}{ln\_traldf\_lap} \& \protect\np{ln_dynldf_lap}{ln\_dynldf\_lap})}
+Setting \protect\np[=.true.]{ln_traldf_lap}{ln\_traldf\_lap} and/or \protect\np[=.true.]{ln_dynldf_lap}{ln\_dynldf\_lap} 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.
+%% =================================================================================================
+\subsection[Bilaplacian mixing (\forcode{ln_traldf_blp} \& \forcode{ln_dynldf_blp})]{Bilaplacian mixing (\protect\np{ln_traldf_blp}{ln\_traldf\_blp} \& \protect\np{ln_dynldf_blp}{ln\_dynldf\_blp})}
+Setting \protect\np[=.true.]{ln_traldf_blp}{ln\_traldf\_blp} and/or \protect\np[=.true.]{ln_dynldf_blp}{ln\_dynldf\_blp} 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 (\textit{ldfslp.F90})]
+{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.
 …
 A direction for lateral mixing has to be defined when the desired operator does not act along the model levels.
 This occurs when $(a)$ horizontal mixing is required on tracer or momentum
 (\np{ln\_traldf\_hor} or \np{ln\_dynldf\_hor}) in $s$- or mixed $s$-$z$- coordinates,
+(\np{ln_traldf_hor}{ln\_traldf\_hor} or \np{ln_dynldf_hor}{ln\_dynldf\_hor}) in $s$- or mixed $s$-$z$- coordinates,
 and $(b)$ isoneutral mixing is required whatever the vertical coordinate is.
 This direction of mixing is defined by its slopes in the \textbf{i}- and \textbf{j}-directions at the face of
 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
 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{ldf\_slp\_init} when \np{ln\_sco}\forcode{ = .true.},
+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[=.true.]{ln_sco}{ln\_sco},
+and either \np[=.true.]{ln_traldf_hor}{ln\_traldf\_hor} or \np[=.true.]{ln_dynldf_hor}{ln\_dynldf\_hor}.
+%% =================================================================================================
 \subsection{Slopes for tracer iso-neutral mixing}
 \label{subsec:LDF_slp_iso}
 …
 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
+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{mcdougall_JPO87}, 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:
 \begin{description}
+\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,
+\item [$z$-coordinate with full step:] 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{mcdougall_JPO87}
+  (see \autoref{subsec:TRA_bn2}).
+\item[$z$-coordinate with partial step: ]
+  this case is identical to the full step case except that at partial step level,
+  (see \autoref{subsec:TRA_bn2}).
+\item [$z$-coordinate with partial step:] this case is identical to the full step case except that at partial step level,
   the \emph{horizontal} density gradient is evaluated as described in \autoref{sec:TRA_zpshde}.
+\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{ln\_traldf\_triad}\forcode{ = .true.};
+  see \autoref{apdx:triad}).
+\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[=.true.]{ln_traldf_triad}{ln\_traldf\_triad};
+  see \autoref{apdx:TRIADS}).
   In other words, iso-neutral mixing will only be accurately represented with a linear equation of state
   (\np{ln\_seos}\forcode{ = .true.}).
   In the case of a "true" equation of state, the evaluation of $i$ and $j$ derivatives in \autoref{eq:ldfslp_iso}
+  (\np[=.true.]{ln_seos}{ln\_seos}).
+  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.
 …
 \[
   % \label{eq:ldfslp_iso2}
+  % \label{eq:LDF_slp_iso2}
   \begin{split}
     r_{1u} &= \frac{e_{3u}}{e_{1u}}\; \frac
 …
 Note that such a formulation could be also used in the $z$-coordinate and $z$-coordinate with partial steps cases.
 \end{description}
 …
 To overcome this problem, several techniques have been proposed in which the numerical schemes of
 the ocean model are modified \citep{weaver.eby_JPO97, griffies.gnanadesikan.ea_JPO98}.
 Griffies's scheme is now available in \NEMO\ if \np{ln\_traldf\_triad}\forcode{ = .true.}; see \autoref{apdx:triad}.
+Griffies's scheme is now available in \NEMO\ if \np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}; 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
 …
 Nevertheless, this iso-neutral operator does not ensure that variance cannot increase,
+contrary to the \citet{griffies.gnanadesikan.ea_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=\textwidth]{Fig_LDF_ZDF1}
+    \caption {
+      \protect\label{fig:LDF_ZDF1}
+      averaging procedure for isopycnal slope computation.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=0.66\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...
 %from griffies: chapter 13.1....
+% 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
+% 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{cox_OM87, griffies_bk04}, the slopes must also be bounded by
 the namelist scalar \np{rn\_slpmax} (usually $1/100$) everywhere.
+the namelist scalar \np{rn_slpmax}{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
 …
 \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=\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=0.66\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}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \colorbox{yellow}{add here a discussion about the flattening of the slopes, vs tapering the coefficient.}
+%% =================================================================================================
 \subsection{Slopes for momentum iso-neutral mixing}
 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} \\
 …
 (see \autoref{sec:LBC_coast}).
+% ================================================================
+% Lateral Mixing Coefficients
+% ================================================================
+\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})}
+%% =================================================================================================
+\section[Lateral mixing coefficient (\forcode{nn_aht_ijk_t} \& \forcode{nn_ahm_ijk_t})]{Lateral mixing coefficient (\protect\np{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})}
 \label{sec:LDF_coef}
 The specification of the space variation of the coefficient is made in modules \mdl{ldftra} and \mdl{ldfdyn}.
+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,
+%% =================================================================================================
+\subsection[Mixing coefficients read from file (\forcode{=-20, -30})]{ Mixing coefficients read from file (\protect\np[=-20, -30]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=-20, -30]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})}
+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---------------------------------------------------
+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[=-20]{nn_aht_ijk_t}{nn\_aht\_ijk\_t}, \np[=-20]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t}) or 3d (\np[=-30]{nn_aht_ijk_t}{nn\_aht\_ijk\_t},  \np[=-30]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t}). They must be given at U, V points for tracers and T, F points for momentum (see \autoref{tab:LDF_files}).
 \begin{table}[htb]
+  \begin{center}
+    \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{
+      \protect\label{tab:LDF_files}
+      Description of expected input files if mixing coefficients are read from NetCDF files.
+    }
+  \end{center}
+  \centering
+  \begin{tabular}{|l|l|l|l|}
+    \hline
+    Namelist parameter                       & Input filename                               & dimensions & variable names                      \\  \hline
+    \np[=-20]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t}     & \forcode{eddy_viscosity_2D.nc }            &     $(i,j)$         & \forcode{ahmt_2d, ahmf_2d}  \\  \hline
+    \np[=-20]{nn_aht_ijk_t}{nn\_aht\_ijk\_t}           & \forcode{eddy_diffusivity_2D.nc }           &     $(i,j)$           & \forcode{ahtu_2d, ahtv_2d}    \\   \hline
+    \np[=-30]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t}        & \forcode{eddy_viscosity_3D.nc }            &     $(i,j,k)$          & \forcode{ahmt_3d, ahmf_3d}  \\  \hline
+    \np[=-30]{nn_aht_ijk_t}{nn\_aht\_ijk\_t}     & \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})}
+%% =================================================================================================
+\subsection[Constant mixing coefficients (\forcode{=0})]{ Constant mixing coefficients (\protect\np[=0]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=0]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})}
 If constant, mixing coefficients are set thanks to a velocity and a length scales ($U_{scl}$, $L_{scl}$) such that:
 \begin{equation}
   \label{eq:constantah}
+  \label{eq:LDF_constantah}
   A_o^l = \left\{
     \begin{aligned}
 …
 \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})}
+ $U_{scl}$ and $L_{scl}$ are given by the namelist parameters \np{rn_Ud}{rn\_Ud}, \np{rn_Uv}{rn\_Uv}, \np{rn_Ld}{rn\_Ld} and \np{rn_Lv}{rn\_Lv}.
+%% =================================================================================================
+\subsection[Vertically varying mixing coefficients (\forcode{=10})]{Vertically varying mixing coefficients (\protect\np[=10]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=10]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})}
 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:constantah}, the bottom value is 1/4 of the surface value,
+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})}
+%% =================================================================================================
+\subsection[Mesh size dependent mixing coefficients (\forcode{=20})]{Mesh size dependent mixing coefficients (\protect\np[=20]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=20]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})}
 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}
 …
   \right.
 \end{equation}
 where $U_{scl}$ is a user defined velocity scale (\np{rn\_Ud}, \np{rn\_Uv}).
+where $U_{scl}$ is a user defined velocity scale (\np{rn_Ud}{rn\_Ud}, \np{rn_Uv}{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.
 …
 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.
 \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})}
+\colorbox{yellow}{CASE \np{nn_aht_ijk_t}{nn\_aht\_ijk\_t} = 21 to be added}
+%% =================================================================================================
+\subsection[Mesh size and depth dependent mixing coefficients (\forcode{=30})]{Mesh size and depth dependent mixing coefficients (\protect\np[=30]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=30]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})}
 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})}
+the magnitude of the coefficient.
+%% =================================================================================================
+\subsection[Velocity dependent mixing coefficients (\forcode{=31})]{Flow dependent mixing coefficients (\protect\np[=31]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=31]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})}
 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:flowah}
+  \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 }
+      & \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
+%% =================================================================================================
+\subsection[Deformation rate dependent viscosities (\forcode{nn_ahm_ijk_t=32})]{Deformation rate dependent viscosities (\protect\np[=32]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})}
+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:smag1}
+  \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  } \\
 …
 \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:smag2}
+Introducing a user defined constant $C$ (given in the namelist as \np{rn_csmc}{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 }
+      & \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:STP_forward_imp}) so that:
 \begin{equation}
   \label{eq:smag3}
+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 }
+      & 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.
+where $C_{min}$ and $C_{max}$ are adimensional namelist parameters given by \np{rn_minfac}{rn\_minfac} and \np{rn_maxfac}{rn\_maxfac} respectively.
+%% =================================================================================================
 \subsection{About space and time varying mixing coefficients}
 …
 (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}).
+% ================================================================
+% Eddy Induced Mixing
+% ================================================================
+\section[Eddy induced velocity (\forcode{ln_ldfeiv = .true.})]
+{Eddy induced velocity (\protect\np{ln\_ldfeiv}\forcode{ = .true.})}
+(\autoref{sec:INVARIANTS_dynldf_properties}).
+%% =================================================================================================
+\section[Eddy induced velocity (\forcode{ln_ldfeiv})]{Eddy induced velocity (\protect\np{ln_ldfeiv}{ln\_ldfeiv})}
 \label{sec:LDF_eiv}
+%--------------------------------------------namtra_eiv---------------------------------------------------
+\nlst{namtra_eiv}
+%--------------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{namtra_eiv}
+  \caption{\forcode{&namtra_eiv}}
+  \label{lst:namtra_eiv}
+\end{listing}
 %%gm  from Triad appendix  : to be incorporated....
 …
   Values of iso-neutral diffusivity and GM coefficient are set as described in \autoref{sec:LDF_coef}.
   If none of the keys \key{traldf\_cNd}, N=1,2,3 is set (the default), spatially constant iso-neutral $A_l$ and
   GM diffusivity $A_e$ are directly set by \np{rn\_aeih\_0} and \np{rn\_aeiv\_0}.
+  GM diffusivity $A_e$ are directly set by \np{rn_aeih_0}{rn\_aeih\_0} and \np{rn_aeiv_0}{rn\_aeiv\_0}.
   If 2D-varying coefficients are set with \key{traldf\_c2d} then $A_l$ is reduced in proportion with horizontal
   scale factor according to \autoref{eq:title}
 …
     In this case, $A_e$ at low latitudes $|\theta|<20^{\circ}$ is further reduced by a factor $|f/f_{20}|$,
     where $f_{20}$ is the value of $f$ at $20^{\circ}$~N
   } (\mdl{ldfeiv}) and \np{rn\_aeiv\_0} is ignored unless it is zero.
+  } (\mdl{ldfeiv}) and \np{rn_aeiv_0}{rn\_aeiv\_0} is ignored unless it is zero.
+}
 When  \citet{gent.mcwilliams_JPO90} diffusion is used (\np{ln\_ldfeiv}\forcode{ = .true.}),
+When  \citet{gent.mcwilliams_JPO90} diffusion is used (\np[=.true.]{ln_ldfeiv}{ln\_ldfeiv}),
 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.
 If isopycnal mixing is used in the standard way, \ie\ \np{ln\_traldf\_triad}\forcode{ = .false.}, the eddy induced velocity is given by:
 \begin{equation}
   \label{eq:ldfeiv}
+\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[=.false.]{ln_traldf_triad}{ln\_traldf\_triad}, 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{nn\_aei\_ijk\_t} \nam{tra\_eiv} namelist parameter.
+where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{nn_aei_ijk_t}{nn\_aei\_ijk\_t} \nam{tra_eiv}{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.
 …
 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.
+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:triad}.
+% ================================================================
+% Mixed layer eddies
+% ================================================================
+\section[Mixed layer eddies (\forcode{ln_mle = .true.})]
+{Mixed layer eddies (\protect\np{ln\_mle}\forcode{ = .true.})}
+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}{nn\_aei\_ijk\_t}, \np{rn_Ue}{rn\_Ue}, \np{rn_Le}{rn\_Le} namelist parameters).
+\colorbox{yellow}{CASE \np{nn_aei_ijk_t}{nn\_aei\_ijk\_t} = 21 to be added}
+In case of setting \np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}, a skew form of the eddy induced advective fluxes is used, which is described in \autoref{apdx:TRIADS}.
+%% =================================================================================================
+\section[Mixed layer eddies (\forcode{ln_mle})]{Mixed layer eddies (\protect\np{ln_mle}{ln\_mle})}
 \label{sec:LDF_mle}
+%--------------------------------------------namtra_eiv---------------------------------------------------
 \nlst{namtra_mle}
+%--------------------------------------------------------------------------------------------------------------
 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.
+\begin{listing}
+  \nlst{namtra_mle}
+  \caption{\forcode{&namtra_mle}}
+  \label{lst:namtra_mle}
+\end{listing}
+If  \np[=.true.]{ln_mle}{ln\_mle} in \nam{tra_mle}{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
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_OBS.tex

-                      r11435
+                      r11799
 \begin{document}
+% ================================================================
+% Chapter observation operator (OBS)
+% ================================================================
 \chapter{Observation and Model Comparison (OBS)}
 \label{chap:OBS}
+%\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}
+\thispagestyle{plain}
 \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
+\paragraph{Changes record} ~\\
+{\footnotesize
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release & Author(s) & Modifications \\
+    \hline
+    {\em   4.0} & {\em ...} & {\em ...} \\
+    {\em   3.6} & {\em ...} & {\em ...} \\
+    {\em   3.4} & {\em ...} & {\em ...} \\
+    {\em <=3.4} & {\em ...} & {\em ...}
+  \end{tabularx}
+}
+\clearpage
 The observation and model comparison code, the observation operator (OBS), reads in observation files
 …
 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.
+The code is only activated if the \nam{obs}{obs} namelist logical \np{ln_diaobs}{ln\_diaobs} is set to true.
 For all data types a 2D horizontal interpolator or averager is needed to
 …
 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 \np{nn_profdavtypes}{nn\_profdavtypes} namelist array.
 Some SST observations are equivalent to a night-time average value and
 the observation operator code can calculate equivalent night-time average model SST fields by
 setting the namelist value \np{ln\_sstnight} to true.
+setting the namelist value \np{ln_sstnight}{ln\_sstnight} to true.
 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}.
+The code is controlled by the namelist \nam{obs}{obs}.
 See the following sections for more details on setting up the namelist.
 …
 In \autoref{sec:OBS_obsutils} we describe some utilities to help work with the files produced by the OBS code.
+% ================================================================
+% Example
+% ================================================================
+%% =================================================================================================
 \section{Running the observation operator code example}
 \label{sec:OBS_example}
 …
 \end{enumerate}
 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.
+Options are defined through the \nam{obs}{obs} namelist variables.
+The options \np{ln_t3d}{ln\_t3d} and \np{ln_s3d}{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}{cn\_profbfiles} variable.
 The model grid points for a particular observation latitude and longitude are found using
 the grid searching part of the code.
 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 \np{cn\_gridsearch} file (or files).
+setting \np{ln_grid_search_lookup}{ln\_grid\_search\_lookup} allows the use of a lookup table which
+is saved into an \np{cn_gridsearch}{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.
+Setting \np{ln_grid_global}{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 \autoref{subsec:OBS_parallel}).
 …
 \autoref{sec:OBS_obsutils}.
+%% =================================================================================================
 \section{Technical details (feedback type observation file headers)}
 \label{sec:OBS_details}
 Here we show a more complete example namelist \nam{obs} and also show the NetCDF headers of
+Here we show a more complete example namelist \nam{obs}{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{\forcode{&namobs}}
+  \label{lst:namobs}
+\end{listing}
 The observation operator code uses the feedback observation file format for all data types.
 …
 sea surface temperature are in the following subsections.
+%% =================================================================================================
 \subsection{Profile feedback file}
 …
 \end{clines}
+%% =================================================================================================
 \subsection{Sea level anomaly feedback file}
 …
 \end{clines}
+%% =================================================================================================
 \subsection{Sea surface temperature feedback file}
 …
 \end{clines}
+%% =================================================================================================
 \section{Theoretical details}
 \label{sec:OBS_theory}
+%% =================================================================================================
 \subsection{Horizontal interpolation and averaging methods}
 …
 (for surface observation types only).
 The main namelist option associated with the interpolation/averaging is \np{nn\_2dint}.
+The main namelist option associated with the interpolation/averaging is \np{nn_2dint}{nn\_2dint}.
 This default option can be set to values from 0 to 6.
 Values between 0 to 4 are associated with interpolation while values 5 or 6 are associated with averaging.
 \begin{itemize}
 \item \np{nn\_2dint}\forcode{ = 0}: Distance-weighted interpolation
 \item \np{nn\_2dint}\forcode{ = 1}: Distance-weighted interpolation (small angle)
 \item \np{nn\_2dint}\forcode{ = 2}: Bilinear interpolation (geographical grid)
 \item \np{nn\_2dint}\forcode{ = 3}: Bilinear remapping interpolation (general grid)
 \item \np{nn\_2dint}\forcode{ = 4}: Polynomial interpolation
 \item \np{nn\_2dint}\forcode{ = 5}: Radial footprint averaging with diameter specified in the namelist as
+\item \np[=0]{nn_2dint}{nn\_2dint}: Distance-weighted interpolation
+\item \np[=1]{nn_2dint}{nn\_2dint}: Distance-weighted interpolation (small angle)
+\item \np[=2]{nn_2dint}{nn\_2dint}: Bilinear interpolation (geographical grid)
+\item \np[=3]{nn_2dint}{nn\_2dint}: Bilinear remapping interpolation (general grid)
+\item \np[=4]{nn_2dint}{nn\_2dint}: Polynomial interpolation
+\item \np[=5]{nn_2dint}{nn\_2dint}: Radial footprint averaging with diameter specified in the namelist as
   \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
+\item \np[=6]{nn_2dint}{nn\_2dint}: Rectangular footprint averaging with E/W and N/S size specified in
   the namelist as \texttt{rn\_[var]\_avglamscl} and \texttt{rn\_[var]\_avgphiscl} in degrees or metres
   (set using \texttt{ln\_[var]\_fp\_indegs})
 …
 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
+The \np{nn_2dint}{nn\_2dint} default option can be overridden for surface observation types using
 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}
 …
 \begin{enumerate}
+\item[1.] {\bfseries Great-Circle distance-weighted interpolation.}
+\item {\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.
 …
    \end{alignat*}
 \item[2.] {\bfseries Great-Circle distance-weighted interpolation with small angle approximation.}
+\item {\bfseries Great-Circle distance-weighted interpolation with small angle approximation.}
   Similar to the previous interpolation but with the distance $s$ computed as
   \begin{alignat*}{2}
 …
   where $M$ corresponds to $A$, $B$, $C$ or $D$.
 \item[3.] {\bfseries Bilinear interpolation for a regular spaced grid.}
+\item {\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.] {\bfseries Bilinear remapping interpolation for a general grid.}
+\item {\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).
 …
 \end{enumerate}
+%% =================================================================================================
 \subsubsection{Horizontal averaging}
 …
 Examples of the weights calculated for an observation with rectangular and radial footprints are shown in
+\autoref{fig:obsavgrec} and~\autoref{fig:obsavgrad}.
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\autoref{fig:OBS_avgrec} and~\autoref{fig:OBS_avgrad}.
 \begin{figure}
+  \begin{center}
+    \includegraphics[width=\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=0.66\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}
+  \begin{center}
+    \includegraphics[width=\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}
+  \centering
+  \includegraphics[width=0.66\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}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+%% =================================================================================================
 \subsection{Grid search}
 …
           ({\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{\mathbf k}$
 …
 the $i$ and $j$ ranges of this point searched to determine the precise four points surrounding the observation.
+%% =================================================================================================
 \subsection{Parallel aspects of horizontal interpolation}
 \label{subsec:OBS_parallel}
 …
 and 2) round-robin.
+%% =================================================================================================
 \subsubsection{Geographical distribution of observations among processors}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}
+  \begin{center}
+    \includegraphics[width=\textwidth]{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=0.66\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
+\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.
 …
 this could lead to load imbalance.
+%% =================================================================================================
 \subsubsection{Round-robin distribution of observations among processors}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}
+  \begin{center}
+    \includegraphics[width=\textwidth]{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=0.66\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}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 An alternative approach is to distribute the observations equally among processors and
 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,
 a subroutine has been developed that retrieves any grid points in the global space.
+%% =================================================================================================
 \subsection{Vertical interpolation operator}
 …
 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
-% ================================================================
-% Standalone observation operator documentation
-% ================================================================
 %\usepackage{framed}
+%% =================================================================================================
 \section{Standalone observation operator}
 \label{sec:OBS_sao}
+%% =================================================================================================
 \subsection{Concept}
 …
 By forecast, we mean any method which produces an estimate of physical reality which is not an observed value.
-%--------------------------------------------------------------------------------------------------------
 % sao.exe
+%--------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsection{Using the standalone observation operator}
+%% =================================================================================================
 \subsubsection{Building}
 …
 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
 %--------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsubsection{Running}
 …
 a full \NEMO\ namelist and then to run the executable as if it were nemo.exe.
-%--------------------------------------------------------------------------------------------------------
 % Configuration section
 %--------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \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
+The observation files and settings understood by \nam{obs}{obs} have been outlined in the online observation operator section.
+In addition is a further namelist \nam{sao}{sao} which used to set the input model fields for the SAO
+%% =================================================================================================
 \subsubsection{Single field}
 …
 \textbf{votemper}, \textbf{vosaline} and optionally \textbf{sshn} present.
 For each field read there must be an entry in the \nam{sao} namelist specifying
+For each field read there must be an entry in the \nam{sao}{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.
 …
 \end{forlines}
+%% =================================================================================================
 \subsubsection{Multiple fields per run}
 …
 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
+%% =================================================================================================
 \section{Observation utilities}
 \label{sec:OBS_obsutils}
 …
 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.
+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.
 …
 OBSTOOLS and dataplot are described in more detail below.
+%% =================================================================================================
 \subsection{Obstools}
 A series of \fortran utilities is provided with \NEMO\ called 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 observation operator. A brief description of some of the utilities follows
+%% =================================================================================================
 \subsubsection{corio2fb}
 …
 \end{cmds}
+%% =================================================================================================
 \subsubsection{enact2fb}
 …
 \end{cmds}
+%% =================================================================================================
 \subsubsection{fbcomb}
 …
 \end{cmds}
+%% =================================================================================================
 \subsubsection{fbmatchup}
 …
 \end{cmds}
+%% =================================================================================================
 \subsubsection{fbprint}
 …
 \end{cmds}
+%% =================================================================================================
 \subsubsection{fbsel}
 …
 \end{cmds}
+%% =================================================================================================
 \subsubsection{fbstat}
 …
 \end{cmds}
+%% =================================================================================================
 \subsubsection{fbthin}
 …
 \end{cmds}
+%% =================================================================================================
 \subsubsection{sla2fb}
 …
 \end{cmds}
+%% =================================================================================================
 \subsubsection{vel2fb}
 …
 \end{cmds}
+%% =================================================================================================
 \subsection{Building the obstools}
 To build the obstools use in the tools directory use ./maketools -n OBSTOOLS -m [ARCH].
+%% =================================================================================================
 \subsection{Dataplot}
 …
 \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 rightmost group of buttons will print the plot window as a postscript, save it as png, or exit from dataplot.
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}
+  \begin{center}
+    % \includegraphics[width=\textwidth]{Fig_OBS_dataplot_main}
+    \includegraphics[width=\textwidth]{Fig_OBS_dataplot_main}
+    \caption{
+      \protect\label{fig:obsdataplotmain}
+      Main window of dataplot.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=0.66\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=\textwidth]{Fig_OBS_dataplot_prof}
+    \includegraphics[width=\textwidth]{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=0.66\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}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_SBC.tex

-                      r11435
+                      r11799
 \begin{document}
-% ================================================================
-% Chapter —— Surface Boundary Condition (SBC, SAS, ISF, ICB)
-% ================================================================
 \chapter{Surface Boundary Condition (SBC, SAS, ISF, ICB)}
 \label{chap:SBC}
+\thispagestyle{plain}
 \chaptertoc
+\newpage
+%---------------------------------------namsbc--------------------------------------------------
+\nlst{namsbc}
+%--------------------------------------------------------------------------------------------------------------
+\paragraph{Changes record} ~\\
+{\footnotesize
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release & Author(s) & Modifications \\
+    \hline
+    {\em   4.0} & {\em ...} & {\em ...} \\
+    {\em   3.6} & {\em ...} & {\em ...} \\
+    {\em   3.4} & {\em ...} & {\em ...} \\
+    {\em <=3.4} & {\em ...} & {\em ...}
+  \end{tabularx}
+}
+\clearpage
+\begin{listing}
+  \nlst{namsbc}
+  \caption{\forcode{&namsbc}}
+  \label{lst:namsbc}
+\end{listing}
 The ocean needs seven fields as surface boundary condition:
 \begin{itemize}
+\item
+  the two components of the surface ocean stress $\left( {\tau_u \;,\;\tau_v} \right)$
+\item
+  the incoming solar and non solar heat fluxes $\left( {Q_{ns} \;,\;Q_{sr} } \right)$
+\item
+  the surface freshwater budget $\left( {\textit{emp}} \right)$
+\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)$
+\item the two components of the surface ocean stress $\left( {\tau_u \;,\;\tau_v} \right)$
+\item the incoming solar and non solar heat fluxes $\left( {Q_{ns} \;,\;Q_{sr} } \right)$
+\item the surface freshwater budget $\left( {\textit{emp}} \right)$
+\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}
 Four different ways are available to provide the seven fields to the ocean. They are controlled by
 namelist \nam{sbc} variables:
+namelist \nam{sbc}{sbc} variables:
 \begin{itemize}
+\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.}).
+\item a bulk formulation (\np[=.true.]{ln_blk}{ln\_blk} with four possible bulk algorithms),
+\item a flux formulation (\np[=.true.]{ln_flx}{ln\_flx}),
+\item a coupled or mixed forced/coupled formulation (exchanges with a atmospheric model via the OASIS coupler),
+(\np{ln_cpl}{ln\_cpl} or \np[=.true.]{ln_mixcpl}{ln\_mixcpl}),
+\item a user defined formulation (\np[=.true.]{ln_usr}{ln\_usr}).
 \end{itemize}
 The frequency at which the forcing fields have to be updated is given by the \np{nn\_fsbc} namelist parameter.
+The frequency at which the forcing fields have to be updated is given by the \np{nn_fsbc}{nn\_fsbc} namelist parameter.
 When the fields are supplied from data files (bulk, flux and mixed formulations),
 …
 \begin{itemize}
+\item
+  the rotation of vector components supplied relative to an east-north coordinate system onto
+\item the rotation of vector components supplied relative to an east-north coordinate system onto
   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 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.}).
+\item the use of a land/sea mask for input fields (\np[=.true.]{nn_lsm}{nn\_lsm}),
+\item the addition of a surface restoring term to observed SST and/or SSS (\np[=.true.]{ln_ssr}{ln\_ssr}),
+\item the modification of fluxes below ice-covered areas (using climatological ice-cover or a sea-ice model)
+  (\np[=0..3]{nn_ice}{nn\_ice}),
+\item the addition of river runoffs as surface freshwater fluxes or lateral inflow (\np[=.true.]{ln_rnf}{ln\_rnf}),
+\item the addition of ice-shelf melting as lateral inflow (parameterisation) or
+  as fluxes applied at the land-ice ocean interface (\np[=.true.]{ln_isf}{ln\_isf}),
+\item the addition of a freshwater flux adjustment in order to avoid a mean sea-level drift
+  (\np[=0..2]{nn_fwb}{nn\_fwb}),
+\item the transformation of the solar radiation (if provided as daily mean) into an analytical diurnal cycle
+  (\np[=.true.]{ln_dm2dc}{ln\_dm2dc}),
+\item the activation of wave effects from an external wave model  (\np[=.true.]{ln_wave}{ln\_wave}),
+\item a neutral drag coefficient is read from an external wave model (\np[=.true.]{ln_cdgw}{ln\_cdgw}),
+\item the Stokes drift from an external wave model is accounted for (\np[=.true.]{ln_sdw}{ln\_sdw}),
+\item the choice of the Stokes drift profile parameterization (\np[=0..2]{nn_sdrift}{nn\_sdrift}),
+\item the surface stress given to the ocean is modified by surface waves (\np[=.true.]{ln_tauwoc}{ln\_tauwoc}),
+\item the surface stress given to the ocean is read from an external wave model (\np[=.true.]{ln_tauw}{ln\_tauw}),
+\item the Stokes-Coriolis term is included (\np[=.true.]{ln_stcor}{ln\_stcor}),
+\item the light penetration in the ocean (\np[=.true.]{ln_traqsr}{ln\_traqsr} with namelist \nam{tra_qsr}{tra\_qsr}),
+\item the atmospheric surface pressure gradient effect on ocean and ice dynamics (\np[=.true.]{ln_apr_dyn}{ln\_apr\_dyn} with namelist \nam{sbc_apr}{sbc\_apr}),
+\item the effect of sea-ice pressure on the ocean (\np[=.true.]{ln_ice_embd}{ln\_ice\_embd}).
 \end{itemize}
 …
 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}),
 which provides additional sources of fresh water.
+% ================================================================
+% Surface boundary condition for the ocean
+% ================================================================
+%% =================================================================================================
 \section{Surface boundary condition for the ocean}
 \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.
 …
 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 trend of the temperature equation (\mdl{traqsr} module) when
 \np{ln\_traqsr}\forcode{ = .true.}.
+\np[=.true.]{ln_traqsr}{ln\_traqsr}.
 The way the light penetrates inside the water column is generally a sum of decreasing exponentials
 (see \autoref{subsec:TRA_qsr}).
 …
 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
 %created!)
+%
+%Especially the \np{nn\_fsbc}, the \mdl{sbc\_oce} module (fluxes + mean sst sss ssu
+%Especially the \np{nn_fsbc}{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
 %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
+%
 %Explain here all the namlist namsbc variable{\ldots}.
+%
 % explain : use or not of surface currents
+%
 %\colorbox{yellow}{End Miss }
 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
+these averaged fields are used to compute the surface fluxes at the frequency of \np{nn\_fsbc} time-steps.
+%-------------------------------------------------TABLE---------------------------------------------------
+These variables are averaged over \np{nn_fsbc}{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}{nn\_fsbc} time-steps.
 \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 \np{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}{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
+% ================================================================
+%% =================================================================================================
 \section{Input data generic interface}
 \label{sec:SBC_input}
 …
 The module is designed with four main objectives in mind:
 \begin{enumerate}
+\item
+  optionally provide a time interpolation of the input data every specified model time-step, whatever their input frequency is,
+\item 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
+  optionally provide an on-the-fly space interpolation from the native input data grid to the model grid.
+\item
+  make the run duration independent from the period cover by the input files.
+\item
+  provide a simple user interface and a rather simple developer interface by
+\item optionally provide an on-the-fly space interpolation from the native input data grid to the model grid.
+\item make the run duration independent from the period cover by the input files.
+\item provide a simple user interface and a rather simple developer interface by
   limiting the number of prerequisite informations.
 \end{enumerate}
 …
 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 user can set the \np{cn\_dir} to the pathway leading to the data.
+the code is executed, then the user can set the \np{cn_dir}{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 (\textit{fldread.F90})]
+{Input data specification (\protect\mdl{fldread})}
+%% =================================================================================================
+\subsection[Input data specification (\textit{fldread.F90})]{Input data specification (\protect\mdl{fldread})}
 \label{subsec:SBC_fldread}
 …
 where
 \begin{description}
+\item[File name]:
+  the stem name of the NetCDF file to be opened.
+\item [File name]: 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).
   \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 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}
+    \end{center}
+    \caption{
+      \protect\label{tab:fldread}
+      naming nomenclature for climatological or interannual input file(s), as a function of the open/close frequency.
+    \centering
+    \begin{tabular}{|l|c|c|c|}
+      \hline
+                                  &  daily or weekLL     &  monthly           &  yearly        \\
+      \hline
+      \np[=.false.]{clim}{clim} &  fn\_yYYYYmMMdDD.nc  &  fn\_yYYYYmMM.nc   &  fn\_yYYYY.nc  \\
+      \hline
+      \np[=.true.]{clim}{clim}  &  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',
+      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.
+    }
+    \label{tab:SBC_fldread}
   \end{table}
+%--------------------------------------------------------------------------------------------------------------
+\item[Record frequency]:
+  the frequency of the records contained in the input file.
+\item [Record frequency]: the frequency of the records contained in the input file.
   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, setting it to '24.' can be interpreted as 240!
+\item[Variable name]:
+  the name of the variable to be read in the input NetCDF file.
+\item[Time interpolation]:
+  a logical to activate, or not, the time interpolation.
+\item [Variable name]: the name of the variable to be read in the input NetCDF file.
+\item [Time interpolation]: a logical to activate, or not, the time interpolation.
   If set to 'false', the forcing will have a steplike shape remaining constant during each forcing period.
   For example, when using a daily forcing without time interpolation, the forcing remaining constant from
 …
   For example, when using a daily forcing with time interpolation,
   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,
+\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 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]:
+  the frequency at which forcing files must be opened/closed.
+\item [Open/close frequency]: the frequency at which forcing files must be opened/closed.
   Four cases are coded:
   'daily', 'weekLLL' (with 'LLL' the first 3 letters of the first day of the week), 'monthly' and 'yearly' which
 …
   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.
+\item[Others]:
+  'weights filename', 'pairing rotation' and 'land/sea mask' are associated with
+\item [Others]:  'weights filename', 'pairing rotation' and 'land/sea mask' are associated with
   on-the-fly interpolation which is described in \autoref{subsec:SBC_iof}.
 \end{description}
 …
 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 the middle of \np{nn\_fsbc} time-step period.
+values are not needed at every time-step but at every \np{nn_fsbc}{nn\_fsbc} time-step.
+For example with \np[=3]{nn_fsbc}{nn\_fsbc}, 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}{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.
 …
 a useful feature for user considering that it is too heavy to manipulate the complete file for year Y-1.
+% -------------------------------------------------------------------------------------------------------------
+% Interpolation on the Fly
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsection{Interpolation on-the-fly}
 \label{subsec:SBC_iof}
 …
 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}
 …
 and wgt(1) corresponds to variable "wgt01" for example.
+% -------------------------------------------------------------------------------------------------------------
+% Bicubic interpolation
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsubsection{Bicubic interpolation}
 \label{subsec:SBC_iof_bicubic}
 …
 the spatial dependency has been included into the weights.
+% -------------------------------------------------------------------------------------------------------------
+% Implementation
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsubsection{Implementation}
 \label{subsec:SBC_iof_imp}
 …
 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 (irregular grid case) has not been tested.
+\item
+  This code is not guaranteed to produce positive definite answers from positive definite inputs when
+\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
   a bicubic interpolation method is used.
+\item
+  The cyclic condition is only applied on left and right columns, and not to top and bottom rows.
+\item
+  The gradients across the ends of a cyclical grid assume that the grid spacing between
+\item The cyclic condition is only applied on left and right columns, and not to top and bottom rows.
+\item The gradients across the ends of a cyclical grid assume that the grid spacing between
   the two columns involved are consistent with the weights used.
+\item
+  Neither interpolation scheme is conservative. (There is a conservative scheme available in SCRIP,
+\item Neither interpolation scheme is conservative. (There is a conservative scheme available in SCRIP,
   but this has not been implemented.)
 \end{enumerate}
+%% =================================================================================================
 \subsubsection{Utilities}
 \label{subsec:SBC_iof_util}
 …
 (see the directory NEMOGCM/TOOLS/WEIGHTS).
+% -------------------------------------------------------------------------------------------------------------
+% Standalone Surface Boundary Condition Scheme
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsection{Standalone surface boundary condition scheme (SAS)}
+\label{subsec:SAS}
+%---------------------------------------namsbc_sas--------------------------------------------------
+\nlst{namsbc_sas}
+%--------------------------------------------------------------------------------------------------------------
+\label{subsec:SBC_SAS}
+\begin{listing}
+  \nlst{namsbc_sas}
+  \caption{\forcode{&namsbc_sas}}
+  \label{lst:namsbc_sas}
+\end{listing}
 In some circumstances, it may be useful to avoid calculating the 3D temperature,
 …
 \begin{itemize}
+\item
+  Multiple runs of the model are required in code development to
+\item Multiple runs of the model are required in code development to
   see the effect of different algorithms in the bulk formulae.
+\item
+  The effect of different parameter sets in the ice model is to be examined.
+\item
+  Development of sea-ice algorithms or parameterizations.
+\item
+  Spinup of the iceberg floats
+\item
+  Ocean/sea-ice simulation with both models running in parallel (\np{ln\_mixcpl}\forcode{ = .true.})
+\item The effect of different parameter sets in the ice model is to be examined.
+\item Development of sea-ice algorithms or parameterizations.
+\item Spinup of the iceberg floats
+\item Ocean/sea-ice simulation with both models running in parallel (\np[=.true.]{ln_mixcpl}{ln\_mixcpl})
 \end{itemize}
 The Standalone Surface scheme provides this capacity.
 Its options are defined through the \nam{sbc\_sas} namelist variables.
+Its options are defined through the \nam{sbc_sas}{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).
 …
 \begin{itemize}
+\item
+  \mdl{nemogcm}:
+  This routine initialises the rest of the model and repeatedly calls the stp time stepping routine (\mdl{step}).
+\item \mdl{nemogcm}: This routine initialises the rest of the model and repeatedly calls the stp time stepping routine (\mdl{step}).
   Since the ocean state is not calculated all associated initialisations have been removed.
+\item
+  \mdl{step}:
+  The main time stepping routine now only needs to call the sbc routine (and a few utility functions).
+\item
+  \mdl{sbcmod}:
+  This has been cut down and now only calculates surface forcing and the ice model required.
+\item \mdl{step}: The main time stepping routine now only needs to call the sbc routine (and a few utility functions).
+\item \mdl{sbcmod}: 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).
+\item
+  \mdl{daymod}:
+  No ocean restarts are read or written (though the ice model restarts are retained),
+\item \mdl{daymod}: No ocean restarts are read or written (though the ice model restarts are retained),
   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 check that nn\_date0 in the model namelist is correct for his or her purposes.
+\item
+  \mdl{stpctl}:
+  Since there is no free surface solver, references to it have been removed from \rou{stp\_ctl} module.
+\item
+  \mdl{diawri}:
+  All 3D data have been removed from the output.
+\item \mdl{stpctl}: Since there is no free surface solver, references to it have been removed from \rou{stp\_ctl} module.
+\item \mdl{diawri}: All 3D data have been removed from the output.
   The surface temperature, salinity and velocity components (which have been read in) are written along with
   relevant forcing and ice data.
 …
 \begin{itemize}
+\item
+  \mdl{sbcsas}:
+  This module initialises the input files needed for reading temperature, salinity and
+\item \mdl{sbcsas}: 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.
 …
 \end{itemize}
+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})}
+The user can also choose in the \nam{sbc_sas}{sbc\_sas} namelist to read the mean (nn\_fsbc time-step) fraction of solar net radiation absorbed in the 1st T level using
+ (\np[=.true.]{ln_flx}{ln\_flx}) and to provide 3D oceanic velocities instead of 2D ones (\np{ln_flx}{ln\_flx}\forcode{=.true.}). In that last case, only the 1st level will be read in.
+%% =================================================================================================
+\section[Flux formulation (\textit{sbcflx.F90})]{Flux formulation (\protect\mdl{sbcflx})}
 \label{sec:SBC_flx}
+%------------------------------------------namsbc_flx----------------------------------------------------
+\nlst{namsbc_flx}
+%-------------------------------------------------------------------------------------------------------------
+In the flux formulation (\np{ln\_flx}\forcode{ = .true.}),
+\begin{listing}
+  \nlst{namsbc_flx}
+  \caption{\forcode{&namsbc_flx}}
+  \label{lst:namsbc_flx}
+\end{listing}
+In the flux formulation (\np[=.true.]{ln_flx}{ln\_flx}),
 the surface boundary condition fields are directly read from input files.
 The user has to define in the namelist \nam{sbc\_flx} the name of the file,
+The user has to define in the namelist \nam{sbc_flx}{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.
 …
 See \autoref{subsec:SBC_ssr} for its specification.
+% ================================================================
+% Bulk formulation
+% ================================================================
+\section[Bulk formulation (\textit{sbcblk.F90})]
+{Bulk formulation (\protect\mdl{sbcblk})}
+%% =================================================================================================
+\section[Bulk formulation (\textit{sbcblk.F90})]{Bulk formulation (\protect\mdl{sbcblk})}
 \label{sec:SBC_blk}
+%---------------------------------------namsbc_blk--------------------------------------------------
+\nlst{namsbc_blk}
+%--------------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{namsbc_blk}
+  \caption{\forcode{&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.
+and ocean (and sea-ice) variables averaged over \np{nn_fsbc}{nn\_fsbc} time-step.
 The atmospheric fields used depend on the bulk formulae used.
 …
 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\_NCAR}, \np{ln\_COARE\_3p0},  \np{ln\_COARE\_3p5} and  \np{ln\_ECMWF}.
+ \np{ln_NCAR}{ln\_NCAR}, \np{ln_COARE_3p0}{ln\_COARE\_3p0},  \np{ln_COARE_3p5}{ln\_COARE\_3p5} and  \np{ln_ECMWF}{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.
+a constant transfer coefficient (1.4e-3; default value), \citet{lupkes.gryanik.ea_JGR12} (\np{ln_Cd_L12}{ln\_Cd\_L12}), and \citet{lupkes.gryanik_JGR15} (\np{ln_Cd_L15}{ln\_Cd\_L15}) parameterizations
+Common options are defined through the \nam{sbc_blk}{sbc\_blk} namelist variables.
 The required 9 input fields are:
-%--------------------------------------------------TABLE--------------------------------------------------
 \begin{table}[htbp]
+  \label{tab:BULK}
+  \begin{center}
+    \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
+  \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}
-%--------------------------------------------------------------------------------------------------------------
 Note that the air velocity is provided at a tracer ocean point, not at a velocity ocean point ($u$- and $v$-points).
 …
 the ocean grid size is the same or larger than the one of the input atmospheric fields.
 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
+The \np{sn_wndi}{sn\_wndi}, \np{sn_wndj}{sn\_wndj}, \np{sn_qsr}{sn\_qsr}, \np{sn_qlw}{sn\_qlw}, \np{sn_tair}{sn\_tair}, \np{sn_humi}{sn\_humi}, \np{sn_prec}{sn\_prec},
+\np{sn_snow}{sn\_snow}, \np{sn_tdif}{sn\_tdif} parameters describe the fields and the way they have to be used
 (spatial and temporal interpolations).
 \np{cn\_dir} is the directory of location of bulk files
 \np{ln\_taudif} is the flag to specify if we use Hight Frequency (HF) tau information (.true.) or not (.false.)
 \np{rn\_zqt}: is the height of humidity and temperature measurements (m)
 \np{rn\_zu}: is the height of wind measurements (m)
+\np{cn_dir}{cn\_dir} is the directory of location of bulk files
+\np{ln_taudif}{ln\_taudif} is the flag to specify if we use Hight Frequency (HF) tau information (.true.) or not (.false.)
+\np{rn_zqt}{rn\_zqt}: is the height of humidity and temperature measurements (m)
+\np{rn_zu}{rn\_zu}: is the height of wind measurements (m)
 Three multiplicative factors are available:
 \np{rn\_pfac} and \np{rn\_efac} allow to adjust (if necessary) the global freshwater budget by
+\np{rn_pfac}{rn\_pfac} and \np{rn_efac}{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 third one,\np{rn_vfac}{rn\_vfac}, control to which extend the ice/ocean velocities are taken into account in
 the calculation of surface wind stress.
 Its range must be between zero and one, and it is recommended to set it to 0 at low-resolution (ORCA2 configuration).
 …
 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})}
+%% =================================================================================================
+\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}
 …
 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}.
+\item NCAR (\np[=.true.]{ln_NCAR}{ln\_NCAR}): 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
 …
   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.
+\item COARE 3.0 (\np[=.true.]{ln_COARE_3p0}{ln\_COARE\_3p0}): See \citet{fairall.bradley.ea_JC03} for more details
+\item COARE 3.5 (\np[=.true.]{ln_COARE_3p5}{ln\_COARE\_3p5}): See \citet{edson.jampana.ea_JPO13} for more details
+\item ECMWF (\np[=.true.]{ln_ECMWF}{ln\_ECMWF}): 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}
 …
 \begin{itemize}
+\item
+  Constant value (\np{constant\ value}\forcode{ Cd_ice = 1.4e-3 }):
+\item Constant value (\np[ Cd_ice=1.4e-3 ]{constant value}{constant\ value}):
   default constant value used for momentum and heat neutral transfer coefficients
+\item
+  \citet{lupkes.gryanik.ea_JGR12} (\np{ln\_Cd\_L12}\forcode{ = .true.}):
+\item \citet{lupkes.gryanik.ea_JGR12} (\np[=.true.]{ln_Cd_L12}{ln\_Cd\_L12}):
   This scheme adds a dependency on edges at leads, melt ponds and flows
   of the constant neutral air-ice drag. After some approximations,
 …
   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.}):
+\item \citet{lupkes.gryanik_JGR15} (\np[=.true.]{ln_Cd_L15}{ln\_Cd\_L15}):
   Alternative turbulent transfer coefficients formulation between sea-ice
   and atmosphere with distinct momentum and heat coefficients depending
 …
 \end{itemize}
+% ================================================================
+% Coupled formulation
+% ================================================================
+\section[Coupled formulation (\textit{sbccpl.F90})]
+{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{\forcode{&namsbc_cpl}}
+  \label{lst:namsbc_cpl}
+\end{listing}
 In the coupled formulation of the surface boundary condition,
 …
 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 \nam{sbc\_cpl} ).
+(and need to be activated in \nam{sbc_cpl}{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 \nam{sbc\_cpl}, the number of categories will be determined by
+When indicating a multi-category coupling field in \nam{sbc_cpl}{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 cases where this is definitely not possible, the model should abort with an error message.
+% ================================================================
+%        Atmospheric pressure
+% ================================================================
+\section[Atmospheric pressure (\textit{sbcapr.F90})]
+{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{\forcode{&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.}, \nam{sbc} namelist).
 The input atmospheric forcing defined via \np{sn\_apr} structure (\nam{sbc\_apr} namelist)
+(\np[=.true.]{ln_apr_dyn}{ln\_apr\_dyn}, \nam{sbc}{sbc} namelist).
+The input atmospheric forcing defined via \np{sn_apr}{sn\_apr} structure (\nam{sbc_apr}{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.
+A value of $101,000~N/m^2$ is used unless \np{ln_ref_apr}{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 steps.
 …
 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:
+\np{ln\_apr\_obc}  might be set to true.
+% ================================================================
+%        Surface Tides Forcing
+% ================================================================
+\section[Surface tides (\textit{sbctide.F90})]
+{Surface tides (\protect\mdl{sbctide})}
+\np{ln_apr_obc}{ln\_apr\_obc}  might be set to true.
+%% =================================================================================================
+\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{\forcode{&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 \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}{ln\_tide} and \np{ln_tide_pot}{ln\_tide\_pot} are both set to \forcode{.true.} in \nam{_tide}{\_tide}.
+This translates as an additional barotropic force in the momentum \autoref{eq:MB_PE_dyn} such that:
 \[
   % \label{eq:PE_dyn_tides}
+  % \label{eq:SBC_PE_dyn_tides}
   \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= ...
   +g\nabla (\Pi_{eq} + \Pi_{sal})
 …
   Msqm, Mtm, S1, MU2, NU2, L2}, and \textit{T2}). Individual
 constituents are selected by including their names in the array
 \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
+\np{clname}{clname} in \nam{_tide}{\_tide} (e.g., \np{clname}{clname}\forcode{(1)='M2', }
+\np{clname}{clname}\forcode{(2)='S2'} to select solely the tidal consituents \textit{M2}
+and \textit{S2}). Optionally, when \np{ln_tide_ramp}{ln\_tide\_ramp} is set to
 \forcode{.true.}, the equilibrium tidal forcing can be ramped up
 linearly from zero during the initial \np{rdttideramp} days of the
+linearly from zero during the initial \np{rdttideramp}{rdttideramp} days of the
 model run.
 …
 computationally too expensive. Here, two options are available:
 $\Pi_{sal}$ generated by an external model can be read in
 (\np{ln\_read\_load}\forcode{ =.true.}), or a ``scalar approximation'' can be
 used (\np{ln\_scal\_load}\forcode{ =.true.}). In the latter case
+(\np[=.true.]{ln_read_load}{ln\_read\_load}), or a ``scalar approximation'' can be
+used (\np[=.true.]{ln_scal_load}{ln\_scal\_load}). In the latter case
 \[
   \Pi_{sal} = \beta \eta,
 \]
 where $\beta$ (\np{rn\_scal\_load} with a default value of 0.094) is a
+where $\beta$ (\np{rn_scal_load}{rn\_scal\_load} with a default value of 0.094) is a
 spatially constant scalar, often chosen to minimize tidal prediction
 errors. Setting both \np{ln\_read\_load} and \np{ln\_scal\_load} to
+errors. Setting both \np{ln_read_load}{ln\_read\_load} and \np{ln_scal_load}{ln\_scal\_load} to
 \forcode{.false.} removes the SAL contribution.
+% ================================================================
+%        River runoffs
+% ================================================================
+\section[River runoffs (\textit{sbcrnf.F90})]
+{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{\forcode{&namsbc_rnf}}
+  \label{lst:namsbc_rnf}
+\end{listing}
 %River runoff generally enters the ocean at a nonzero depth rather than through the surface.
 …
 %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
 …
 %emp or emps and the changes made are below:
 %Rachel:
 River runoff generally enters the ocean at a nonzero depth rather than through the surface.
 …
 along with the depth (in metres) which the river should be added to.
 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.
+Namelist variables in \nam{sbc_rnf}{sbc\_rnf}, \np{ln_rnf_depth}{ln\_rnf\_depth}, \np{ln_rnf_sal}{ln\_rnf\_sal} and
+\np{ln_rnf_temp}{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.
 …
 (converted into m/s) to give the heat and salt content of the river runoff.
 After the user specified depth is read ini,
 the number of grid boxes this corresponds to is calculated and stored in the variable \np{nz\_rnf}.
+the number of grid boxes this corresponds to is calculated and stored in the variable \np{nz_rnf}{nz\_rnf}.
 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
 …
 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
 …
 %\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.
 …
 %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 (\textit{sbcisf.F90})]
+{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}
+%--------------------------------------------------------------------------------------------------------
+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}.
+\begin{listing}
+  \nlst{namsbc_isf}
+  \caption{\forcode{&namsbc_isf}}
+  \label{lst:namsbc_isf}
+\end{listing}
+The namelist variable in \nam{sbc}{sbc}, \np{nn_isf}{nn\_isf}, controls the ice shelf representation.
+Description and result of sensitivity test to \np{nn_isf}{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[=1]{nn_isf}{nn\_isf}}]: The ice shelf cavity is represented (\np[=.true.]{ln_isfcav}{ln\_isfcav} needed).
   The fwf and heat flux are depending of the local water properties.
 …
    \begin{description}
+   \item[\np{nn\_isfblk}\forcode{ = 1}]:
+     The melt rate is based on a balance between the upward ocean heat flux and
+   \item [{\np[=1]{nn_isfblk}{nn\_isfblk}}]: 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{hunter_rpt06}.
+   \item[\np{nn\_isfblk}\forcode{ = 2}]:
+     The melt rate and the heat flux are based on a 3 equations formulation
+   \item [{\np[=2]{nn_isfblk}{nn\_isfblk}}]: 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{jenkins_JGR91}.
 …
      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.
+     Its thickness is defined by \np{rn_hisf_tbl}{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}{rn\_hisf\_tbl} m.
      Then, the fluxes are spread over the same thickness (ie over one or several cells).
      If \np{rn\_hisf\_tbl} larger than top $e_{3}t$, there is no more feedback between the freezing point at the interface and the the top cell temperature.
+     If \np{rn_hisf_tbl}{rn\_hisf\_tbl} larger than top $e_{3}t$, there is no more feedback between the freezing point at the interface and the the top cell temperature.
      This can lead to super-cool temperature in the top cell under melting condition.
      If \np{rn\_hisf\_tbl} smaller than top $e_{3}t$, the top boundary layer thickness is set to the top cell thickness.\\
+     If \np{rn_hisf_tbl}{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.
      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[=0]{nn_gammablk}{nn\_gammablk}}]: The salt and heat exchange coefficients are constant and defined by \np{rn_gammas0}{rn\_gammas0} and \np{rn_gammat0}{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}]:
+     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_{*}
+\]
+     where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters).
+   \item [{\np[=1]{nn_gammablk}{nn\_gammablk}}]: The salt and heat exchange coefficients are velocity dependent and defined as
+     \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}{rn\_hisf\_tbl} meters).
      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:
+   \item [{\np[=2]{nn_gammablk}{nn\_gammablk}}]: 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}}
 \]
      where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters),
+     where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn_hisf_tbl}{rn\_hisf\_tbl} meters),
      $\Gamma_{Turb}$ the contribution of the ocean stability and
      $\Gamma^{T,S}_{Mole}$ the contribution of the molecular diffusion.
 …
      This formulation has not been extensively tested in \NEMO\ (not recommended).
    \end{description}
+  \item[\np{nn\_isf}\forcode{ = 2}]:
+   The ice shelf cavity is not represented.
+  \item [{\np[=2]{nn_isf}{nn\_isf}}]: The ice shelf cavity is not represented.
    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}).
+   The effective melting length (\np{sn\_Leff\_isf}) is read from a file.
+  \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 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}).
+   (\np{sn_depmax_isf}{sn\_depmax\_isf}) and the base of the ice shelf along the calving front
+   (\np{sn_depmin_isf}{sn\_depmin\_isf}) as in (\np[=3]{nn_isf}{nn\_isf}).
+   The effective melting length (\np{sn_Leff_isf}{sn\_Leff\_isf}) is read from a file.
+  \item [{\np[=3]{nn_isf}{nn\_isf}}]: The ice shelf cavity is not represented.
+   The fwf (\np{sn_rnfisf}{sn\_rnfisf}) is prescribed and distributed along the ice shelf edge between
+   the depth of the average grounding line (GL) (\np{sn_depmax_isf}{sn\_depmax\_isf}) and
+   the base of the ice shelf along the calving front (\np{sn_depmin_isf}{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).
+   However, the fwf is not computed but specified from file \np{sn\_fwfisf}).
+  \item [{\np[=4]{nn_isf}{nn\_isf}}]: The ice shelf cavity is opened (\np[=.true.]{ln_isfcav}{ln\_isfcav} needed).
+   However, the fwf is not computed but specified from file \np{sn_fwfisf}{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[=1]{nn_isf}{nn\_isf}, the fluxes are spread over the top boundary layer thickness (\np{rn_hisf_tbl}{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[=1]{nn_isf}{nn\_isf} and \np[=2]{nn_isf}{nn\_isf} 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[=3]{nn_isf}{nn\_isf} and \np[=4]{nn_isf}{nn\_isf} 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
 …
 See the runoff section \autoref{sec:SBC_rnf} for all the details about the divergence correction.\\
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=\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=0.66\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}{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{\forcode{&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 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
+\begin{enumerate}
+\item the ice sheet model send a new bathymetry and ice shelf draft netcdf file.
+\item a new domcfg.nc file is built using the DOMAINcfg tools.
+\item \NEMO\ run for a specific period and output the average melt rate over the period.
+\item the ice sheet model run using the melt rate outputed in step 4.
+\item go back to 1.
+\end{enumerate}
+If \np[=.true.]{ln_iscpl}{ln\_iscpl}, 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]:
+  T/S/ssh are unchanged and U/V in the top cell are corrected to keep the barotropic transport (bt) constant
+\item [Thin a cell down]: T/S/ssh are unchanged and U/V in the top cell are corrected to keep the barotropic transport (bt) constant
   ($bt_b=bt_n$).
+\item[Enlarge  a cell]:
+  See case "Thin a cell down"
+\item[Dry a cell]:
+  mask, T/S, U/V and ssh are set to 0.
+\item [Enlarge  a cell]: See case "Thin a cell down"
+\item [Dry a cell]: 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]:
+  mask is set to 1, T/S is extrapolated from neighbours, $ssh_n = ssh_b$ and U/V set to 0.
+\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 along i,j and k (both previous test failed), T/S/U/V/ssh and mask are set to 0.
+\item[Dry a column]:
+   mask, T/S, U/V are set to 0 everywhere in the column and ssh set to 0.
+\item[Wet a column]:
+  set mask to 1, T/S is extrapolated from neighbours, ssh is extrapolated from neighbours and U/V set to 0.
+\item [Dry a column]: mask, T/S, U/V are set to 0 everywhere in the column and ssh set to 0.
+\item [Wet a column]: set mask to 1, T/S is extrapolated from neighbours, ssh is extrapolated from neighbours and U/V set to 0.
   If no neighbour, T/S/U/V and mask set to 0.
 \end{description}
 …
 the restart time step is prescribed to be an euler time step instead of a leap frog and $fields_b = fields_n$.\\
 The horizontal extrapolation to fill new cell with realistic value is called \np{nn\_drown} times.
 It means that if the grounding line retreat by more than \np{nn\_drown} cells between 2 coupling steps,
+The horizontal extrapolation to fill new cell with realistic value is called \np{nn_drown}{nn\_drown} times.
+It means that if the grounding line retreat by more than \np{nn_drown}{nn\_drown} cells between 2 coupling steps,
 the code will be unable to fill all the new wet cells properly.
 The default number is set up for the MISOMIP idealised experiments.
 …
 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[=.true.]{ln_hsb}{ln\_hsb}.
 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.
 For safety, it is advised to set \np{rn\_fiscpl} equal to the coupling period (smallest increment possible).
+A correction increment is computed and apply each time step during the next \np{rn_fiscpl}{rn\_fiscpl} time steps.
+For safety, it is advised to set \np{rn_fiscpl}{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}
+%------------------------------------------namberg----------------------------------------------------
+\nlst{namberg}
+%-------------------------------------------------------------------------------------------------------------
+\label{sec:SBC_ICB_icebergs}
+\begin{listing}
+  \nlst{namberg}
+  \caption{\forcode{&namberg}}
+  \label{lst:namberg}
+\end{listing}
 Icebergs are modelled as lagrangian particles in \NEMO\ \citep{marsh.ivchenko.ea_GMD15}.
 …
 (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 \nam{berg} namelist: \np{rn\_initial\_mass} and \np{rn\_initial\_thickness}.
 Each class has an associated scaling (\np{rn\_mass\_scaling}),
+described in the \nam{berg}{berg} namelist: \np{rn_initial_mass}{rn\_initial\_mass} and \np{rn_initial_thickness}{rn\_initial\_thickness}.
+Each class has an associated scaling (\np{rn_mass_scaling}{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[=.true.]{ln_icebergs}{ln\_icebergs}.
 Two initialisation schemes are possible.
 \begin{description}
+\item[\np{nn\_test\_icebergs}~$>$~0]
+  In this scheme, the value of \np{nn\_test\_icebergs} represents the class of iceberg to generate
+  (so between 1 and 10), and \np{nn\_test\_icebergs} provides a lon/lat box in the domain at each grid point of
+\item [{\np{nn_test_icebergs}{nn\_test\_icebergs}~$>$~0}] In this scheme, the value of \np{nn_test_icebergs}{nn\_test\_icebergs} represents the class of iceberg to generate
+  (so between 1 and 10), and \np{nn_test_icebergs}{nn\_test\_icebergs} provides a lon/lat box in the domain at each grid point of
   which an iceberg is generated at the beginning of the run.
   (Note that this happens each time the timestep equals \np{nn\_nit000}.)
   \np{nn\_test\_icebergs} is defined by four numbers in \np{nn\_test\_box} representing the corners of
+  (Note that this happens each time the timestep equals \np{nn_nit000}{nn\_nit000}.)
+  \np{nn_test_icebergs}{nn\_test\_icebergs} is defined by four numbers in \np{nn_test_box}{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[=-1]{nn_test_icebergs}{nn\_test\_icebergs}}] In this scheme, the model reads a calving file supplied in the \np{sn_icb}{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.
 …
 The latter act to disintegrate the iceberg.
 This is either all melted freshwater,
 or (if \np{rn\_bits\_erosion\_fraction}~$>$~0) into melt and additionally small ice bits
+or (if \np{rn_bits_erosion_fraction}{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.
 …
 Extensive diagnostics can be produced.
 Separate output files are maintained for human-readable iceberg information.
 A separate file is produced for each processor (independent of \np{ln\_ctl}).
+A separate file is produced for each processor (independent of \np{ln_ctl}{ln\_ctl}).
 The amount of information is controlled by two integer parameters:
 \begin{description}
 \item[\np{nn\_verbose\_level}] takes a value between one and four and
+\item [{\np{nn_verbose_level}{nn\_verbose\_level}}] takes a value between one and four and
   represents an increasing number of points in the code at which variables are written,
   and an increasing level of obscurity.
 \item[\np{nn\_verbose\_write}] is the number of timesteps between writes
+\item [{\np{nn_verbose_write}{nn\_verbose\_write}}] is the number of timesteps between writes
 \end{description}
 Iceberg trajectories can also be written out and this is enabled by setting \np{nn\_sample\_rate}~$>$~0.
+Iceberg trajectories can also be written out and this is enabled by setting \np{nn_sample_rate}{nn\_sample\_rate}~$>$~0.
 A non-zero value represents how many timesteps between writes of information into the output file.
 These output files are in NETCDF format.
 …
 since its trajectory data may be spread across multiple files.
+% =============================================================================================================
+%        Interactions with waves (sbcwave.F90, ln_wave)
+% =============================================================================================================
+\section[Interactions with waves (\textit{sbcwave.F90}, \texttt{ln\_wave})]
+{Interactions with waves (\protect\mdl{sbcwave}, \protect\np{ln\_wave})}
+%% =================================================================================================
+\section[Interactions with waves (\textit{sbcwave.F90}, \forcode{ln_wave})]{Interactions with waves (\protect\mdl{sbcwave}, \protect\np{ln_wave}{ln\_wave})}
 \label{sec:SBC_wave}
+%------------------------------------------namsbc_wave--------------------------------------------------------
+\nlst{namsbc_wave}
+%-------------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{namsbc_wave}
+  \caption{\forcode{&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 can be accounted by setting the logical variable
 \np{ln\_wave}\forcode{ = .true.} in \nam{sbc} namelist. In addition, specific flags accounting for
+\np[=.true.]{ln_wave}{ln\_wave} in \nam{sbc}{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 \nam{sbc\_wave} namelist
+\item [forced mode]: wave fields should be defined through the \nam{sbc_wave}{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.
+\item [coupled mode]: \NEMO\ and an external wave model can be coupled by setting \np[=.true.]{ln_cpl}{ln\_cpl}
+in \nam{sbc}{sbc} namelist and filling the \nam{sbc_cpl}{sbc\_cpl} namelist.
 \end{description}
+% ----------------------------------------------------------------
+% Neutral drag coefficient from wave model (ln_cdgw)
+% ----------------------------------------------------------------
+\subsection[Neutral drag coefficient from wave model (\texttt{ln\_cdgw})]
+{Neutral drag coefficient from wave model (\protect\np{ln\_cdgw})}
+%% =================================================================================================
+\subsection[Neutral drag coefficient from wave model (\forcode{ln_cdgw})]{Neutral drag coefficient from wave model (\protect\np{ln_cdgw}{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 \nam{sbc} namelist.
+can be used by setting the logical variable \np[=.true.]{ln_cdgw}{ln\_cdgw} in \nam{sbc}{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 (\texttt{ln\_sdw}, \texttt{nn\_sdrift})]
+{3D Stokes Drift (\protect\np{ln\_sdw, nn\_sdrift})}
+%% =================================================================================================
+\subsection[3D Stokes Drift (\forcode{ln_sdw} \& \forcode{nn_sdrift})]{3D Stokes Drift (\protect\np{ln_sdw}{ln\_sdw} \& \np{nn_sdrift}{nn\_sdrift})}
 \label{subsec:SBC_wave_sdw}
 …
 \[
   % \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}
 …
 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
+are included in the code through the \np{nn_sdrift}{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
 …
 \begin{description}
 \item[\np{nn\_sdrift} = 0]: exponential integral profile parameterization proposed by
+\item [{\np{nn_sdrift}{nn\_sdrift} = 0}]: exponential integral profile parameterization proposed by
 \citet{breivik.janssen.ea_JPO14}:
 \[
   % \label{eq:sbc_wave_sdw_0a}
+  % \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 }\
 …
 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
+\item [{\np{nn_sdrift}{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}{nn\_sdrift} = 2}]: velocity profile based on the Phillips spectrum as for \np{nn_sdrift}{nn\_sdrift} = 1
 but using the wave frequency from a wave model.
 …
 \[
   % \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
 …
 \[
   % \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 (\texttt{ln\_stcor})]
+{Stokes-Coriolis term (\protect\np{ln\_stcor})}
+%% =================================================================================================
+\subsection[Stokes-Coriolis term (\forcode{ln_stcor})]{Stokes-Coriolis term (\protect\np{ln_stcor}{ln\_stcor})}
 \label{subsec:SBC_wave_stcor}
 …
 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 stress (\texttt{ln\_tauwoc}, \texttt{ln\_tauw})]
+{Wave modified sress (\protect\np{ln\_tauwoc, ln\_tauw})}
+\np[=.true.]{ln_stcor}{ln\_stcor} has to be set.
+%% =================================================================================================
+\subsection[Wave modified stress (\forcode{ln_tauwoc} \& \forcode{ln_tauw})]{Wave modified sress (\protect\np{ln_tauwoc}{ln\_tauwoc} \& \np{ln_tauw}{ln\_tauw})}
 \label{subsec:SBC_wave_tauw}
 …
 \[
   % \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})}
 \]
 …
 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.}.
+% ================================================================
+% Miscellanea options
+% ================================================================
+wave stress into the ocean by setting \np[=.true.]{ln_tauwoc}{ln\_tauwoc}, or through the zonal and
+meridional stress components by setting \np[=.true.]{ln_tauw}{ln\_tauw}.
+%% =================================================================================================
 \section{Miscellaneous options}
 \label{sec:SBC_misc}
+% -------------------------------------------------------------------------------------------------------------
+%        Diurnal cycle
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Diurnal cycle (\textit{sbcdcy.F90})]
+{Diurnal cycle (\protect\mdl{sbcdcy})}
+%% =================================================================================================
+\subsection[Diurnal cycle (\textit{sbcdcy.F90})]{Diurnal cycle (\protect\mdl{sbcdcy})}
 \label{subsec:SBC_dcy}
+%------------------------------------------namsbc-------------------------------------------------------------
+%
+\nlst{namsbc}
+%-------------------------------------------------------------------------------------------------------------
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=\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.guilyardi.ea_CD07}.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=0.66\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.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.
 …
 assuming that the diurnal cycle of SWF is a scaling of the top of the atmosphere diurnal cycle of incident SWF.
 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.}).
+setting \np[=.true.]{ln_dm2dc}{ln\_dm2dc} (a \textit{\nam{sbc}{sbc}} namelist variable) when
+using a bulk formulation (\np[=.true.]{ln_blk}{ln\_blk}) or
+the flux formulation (\np[=.true.]{ln_flx}{ln\_flx}).
 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.guilyardi.ea_CD07}.
 …
 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 hours and a time interpolation set to true in \np{sn\_qsr} namelist parameter).
+(\ie\ a frequency of 24 hours and a time interpolation set to true in \np{sn_qsr}{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$.
 …
 one every 2~hours (from 1am to 11pm).
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=\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=0.66\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}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 Note also that the setting a diurnal cycle in SWF is highly recommended when
 …
 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
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsection{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\_blk}\forcode{ = .true.}) formulation,
+When using a flux (\np[=.true.]{ln_flx}{ln\_flx}) or bulk (\np[=.true.]{ln_blk}{ln\_blk}) 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
 …
 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 (\textit{sbcssr.F90})]
+{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}
+%-------------------------------------------------------------------------------------------------------------
+Options are defined through the \nam{sbc\_ssr} namelist variables.
+On forced mode using a flux formulation (\np{ln\_flx}\forcode{ = .true.}),
+\begin{listing}
+  \nlst{namsbc_ssr}
+  \caption{\forcode{&namsbc_ssr}}
+  \label{lst:namsbc_ssr}
+\end{listing}
+Options are defined through the \nam{sbc_ssr}{sbc\_ssr} namelist variables.
+On forced mode using a flux formulation (\np[=.true.]{ln_flx}{ln\_flx}),
 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)
 \]
 …
 \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}}
 …
 $\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
+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
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsection{Handling of ice-covered area  (\textit{sbcice\_...})}
 \label{subsec:SBC_ice-cover}
 …
 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 \nam{sbc} namelist.
+the value of the \np{nn_ice}{nn\_ice} namelist parameter found in \nam{sbc}{sbc} namelist.
 \begin{description}
+\item[nn\_ice = 0]
+  there will never be sea-ice in the computational domain.
+\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]
+  sea-ice can exist in the computational domain, but no sea-ice model is used.
+\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.
   Below this area, the SST is restored to the freezing point and
 …
   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]
+  A full sea ice model is used.
+\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
 …
 %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})}
+%% =================================================================================================
+\subsection[Interface to CICE (\textit{sbcice\_cice.F90})]{Interface to CICE (\protect\mdl{sbcice\_cice})}
 \label{subsec:SBC_cice}
 …
 (seek advice from UKMO if necessary).
 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),
+(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
+(with \textit{calc\_strair}\forcode{=.false.} and \textit{calc\_Tsfc}\forcode{=false}).
+The code is intended to be used with \np{nn_fsbc}{nn\_fsbc} set to 1
 (although coupling ocean and ice less frequently should work,
 it is possible the calculation of some of the ocean-ice fluxes needs to be modified slightly -
 …
 there is no sea ice.
+% -------------------------------------------------------------------------------------------------------------
+%        Freshwater budget control
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Freshwater budget control (\textit{sbcfwb.F90})]
+{Freshwater budget control (\protect\mdl{sbcfwb})}
+%% =================================================================================================
+\subsection[Freshwater budget control (\textit{sbcfwb.F90})]{Freshwater budget control (\protect\mdl{sbcfwb})}
 \label{subsec:SBC_fwb}
 …
 \begin{description}
+\item[\np{nn\_fwb}\forcode{ = 0}]
+  no control at all.
+\item [{\np[=0]{nn_fwb}{nn\_fwb}}] 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.
+\item [{\np[=1]{nn_fwb}{nn\_fwb}}] 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
+\item [{\np[=2]{nn_fwb}{nn\_fwb}}] 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
 …
 % in ocean-ice models.
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_STO.tex

-                      r11435
+                      r11799
 \begin{document}
+% ================================================================
+% Chapter stochastic parametrization of EOS (STO)
+% ================================================================
 \chapter{Stochastic Parametrization of EOS (STO)}
 \label{chap:STO}
+\thispagestyle{plain}
 \chaptertoc
+\paragraph{Changes record} ~\\
+{\footnotesize
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release & Author(s) & Modifications \\
+    \hline
+    {\em   4.0} & {\em ...} & {\em ...} \\
+    {\em   3.6} & {\em ...} & {\em ...} \\
+    {\em   3.4} & {\em ...} & {\em ...} \\
+    {\em <=3.4} & {\em ...} & {\em ...}
+  \end{tabularx}
+}
 % \vfill
 % \begin{figure}[b]
+%% =================================================================================================
 % \subsubsection*{Changes record}
 % \begin{tabular}{l||l|m{0.65\linewidth}}
 …
 % \end{figure}
+Authors: \\
+C. Levy release 4.0.1 update \\
+P.-A. Bouttier release 3.6 inital version
+\newpage
+\clearpage
 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}
 …
 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}$ are uncorrelated over the horizontal and fully correlated along the vertical.
+%% =================================================================================================
 \section{Stochastic processes}
 \label{sec:STO_the_details}
 …
 \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}
 …
 \begin{itemize}
+\item
+  for order~1 processes, $w^{(i)}$ is a Gaussian white noise, with zero mean and standard deviation equal to~1,
+\item for order~1 processes, $w^{(i)}$ is a Gaussian white noise, with zero mean and standard deviation equal to~1,
   and the parameters $a^{(i)}$, $b^{(i)}$, $c^{(i)}$ are given by:
   \[
     % \label{eq:ord1}
+    % \label{eq:STO_ord1}
     \left\{
       \begin{array}{l}
 …
   \]
+\item
+  for order~$n>1$ processes, $w^{(i)}$ is an order~$n-1$ autoregressive process, with zero mean,
+\item for order~$n>1$ processes, $w^{(i)}$ is an order~$n-1$ autoregressive process, with zero mean,
   standard deviation equal to~$\sigma^{(i)}$;
   correlation timescale equal to~$\tau^{(i)}$;
 …
   \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 successive 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$ increases.
 …
 for any other configuration or resolution of the model.
+%% =================================================================================================
 \section{Implementation details}
 \label{sec:STO_thech_details}
 The code implementing stochastic parametrisation is located in the src/OCE/STO directory.
 …
 \mdl{stopts} : stochastic parametrisation associated with the non-linearity of the equation of
  seawater, implementing \autoref{eq:sto_pert} so as specifics in the equation of state
  implementing \autoref{eq:eos_sto}.
+ 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:autoreg},
+(\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$).
 …
 (\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
+(which suffix name is given by \np{cn_storst_out}{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
+When \np{ln_rststo}{ln\_rststo} is set to \forcode{.true.}),
+the restart file (which suffix name is given by \np{cn_storst_in}{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.},
+when \np{ln_rstseed}{ln\_rstseed} is set to \forcode{.true.},
 \ie\ when the state of the random number generator is read in the restart file.\\
 …
 Options and parameters \\
 The \np{ln\_sto\_eos} namelist variable activates stochastic parametrisation of equation of state.
+The \np{ln_sto_eos}{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
+The set of parameters is available in \nam{sto}{sto} namelist
 (only the subset for equation of state stochastic parametrisation is listed below):
+%---------------------------------------namsto--------------------------------------------------
+\nlst{namsto}
+%--------------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{namsto}
+  \caption{\forcode{&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 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{nn\_eos\_flt}:]   passes of Laplacian filter
+\item[\np{rn\_eos\_lim}:]   limitation factor (default = 3.0)
+\item [{\np{nn_sto_eos}{nn\_sto\_eos}:}]     number of independent random walks
+\item [{\np{rn_eos_stdxy}{rn\_eos\_stdxy}:}] random walk horizontal standard deviation
+  (in grid points)
+\item [{\np{rn_eos_stdz}{rn\_eos\_stdz}:}]   random walk vertical standard deviation
+  (in grid points)
+\item [{\np{rn_eos_tcor}{rn\_eos\_tcor}:}]   random walk time correlation (in timesteps)
+\item [{\np{nn_eos_ord}{nn\_eos\_ord}:}]     order of autoregressive processes
+\item [{\np{nn_eos_flt}{nn\_eos\_flt}:}]     passes of Laplacian filter
+\item [{\np{rn_eos_lim}{rn\_eos\_lim}:}]     limitation factor (default = 3.0)
 \end{description}
 The first four parameters define the stochastic part of equation of state.
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_TRA.tex

-                      r11459
+                      r11799
 \begin{document}
+% ================================================================
+% Chapter 1 ——— Ocean Tracers (TRA)
+% ================================================================
 \chapter{Ocean Tracers (TRA)}
 \label{chap:TRA}
+\thispagestyle{plain}
 \chaptertoc
+\paragraph{Changes record} ~\\
+{\footnotesize
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release          & Author(s)                                   & Modifications       \\
+    \hline
+    {\em        4.0} & {\em Christian \'{E}th\'{e}               } & {\em Review       } \\
+    {\em        3.6} & {\em Gurvan Madec                         } & {\em Update       } \\
+    {\em $\leq$ 3.4} & {\em Gurvan Madec and S\'{e}bastien Masson} & {\em First version} \\
+  \end{tabularx}
+}
+\clearpage
 % missing/update
 …
 the tracer equations are available depending on the vertical coordinate used and on the physics used.
 In all the equations presented here, the masking has been omitted for simplicity.
 One must be aware that all the quantities are masked fields and that each time a mean or
 difference operator is used, the resulting field is multiplied by a mask.
+One must be aware that all the quantities are masked fields and that
+each time a mean or difference operator is used, the resulting field is multiplied by a mask.
 The two active tracers are potential temperature and salinity.
 …
 NXT stands for next, referring to the time-stepping.
 From left to right, the terms on the rhs of the tracer equations are the advection (ADV),
+the lateral diffusion (LDF), the vertical diffusion (ZDF), the contributions from the external forcings
+(SBC: Surface Boundary Condition, QSR: penetrative Solar Radiation, and BBC: Bottom Boundary Condition),
+the contribution from the bottom boundary Layer (BBL) parametrisation, and an internal damping (DMP) term.
+the lateral diffusion (LDF), the vertical diffusion (ZDF),
+the contributions from the external forcings (SBC: Surface Boundary Condition,
+QSR: penetrative Solar Radiation, and BBC: Bottom Boundary Condition),
+the contribution from the bottom boundary Layer (BBL) parametrisation,
+and an internal damping (DMP) term.
 The terms QSR, BBC, BBL and DMP are optional.
 The external forcings and parameterisations require complex inputs and complex calculations
 …
 LDF and ZDF modules and described in \autoref{chap:SBC}, \autoref{chap:LDF} and
 \autoref{chap:ZDF}, respectively.
 Note that \mdl{tranpc}, the non-penetrative convection module, although located in
 the \path{./src/OCE/TRA} directory as it directly modifies the tracer fields,
+Note that \mdl{tranpc}, the non-penetrative convection module,
+although located in the \path{./src/OCE/TRA} directory as it directly modifies the tracer fields,
 is described with the model vertical physics (ZDF) together with
 other available parameterization of convection.
 In the present chapter we also describe the diagnostic equations used to compute the sea-water properties
+(density, Brunt-V\"{a}is\"{a}l\"{a} frequency, specific heat and freezing point with
 associated modules \mdl{eosbn2} and \mdl{phycst}).
+In the present chapter we also describe the diagnostic equations used to
+compute the sea-water properties (density, Brunt-V\"{a}is\"{a}l\"{a} frequency, specific heat and
+freezing point with associated modules \mdl{eosbn2} and \mdl{phycst}).
 The different options available to the user are managed by namelist logicals.
 …
 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}.
+% ================================================================
+% Tracer Advection
+% ================================================================
+\section[Tracer advection (\textit{traadv.F90})]
+{Tracer advection (\protect\mdl{traadv})}
+(\np{ln_tra_trd}{ln\_tra\_trd} or \np[=.true.]{ln_tra_mxl}{ln\_tra\_mxl}),
+as described in \autoref{chap:DIA}.
+%% =================================================================================================
+\section[Tracer advection (\textit{traadv.F90})]{Tracer advection (\protect\mdl{traadv})}
 \label{sec:TRA_adv}
+%------------------------------------------namtra_adv-----------------------------------------------------
+\nlst{namtra_adv}
+%-------------------------------------------------------------------------------------------------------------
+When considered (\ie\ when \np{ln\_traadv\_OFF} is not set to \forcode{.true.}),
+\begin{listing}
+  \nlst{namtra_adv}
+  \caption{\forcode{&namtra_adv}}
+  \label{lst:namtra_adv}
+\end{listing}
+When considered (\ie\ when \np{ln_traadv_OFF}{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.
 Its discrete expression is given by :
 \begin{equation}
   \label{eq:tra_adv}
+Its discrete expression is given by:
+\begin{equation}
+  \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.
+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.}).
+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
+the continuity equation which is used to calculate the vertical velocity.
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=\textwidth]{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}
+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[=.true.]{ln_linssh}{ln\_linssh}).
+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 the continuity equation which is used to calculate the vertical velocity.
+\begin{figure}
+  \centering
+  \includegraphics[width=0.66\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
+time interpolation to define the value of the tracer at the velocity points
+(\autoref{fig:adv_scheme}).
+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: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.})
+\item [linear free surface] (\np[=.true.]{ln_linssh}{ln\_linssh})
   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
+  the first level tracer value.
+\item[non-linear free surface:]
+  (\np{ln\_linssh}\forcode{ = .false.})
+  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 the first level tracer value.
+\item [non-linear free surface] (\np[=.false.]{ln_linssh}{ln\_linssh})
   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.
+  There is no tracer advection through it so that
+  the advective fluxes through the surface are also zero.
 \end{description}
 In all cases, this boundary condition retains local conservation of tracer.
+Global conservation is obtained in non-linear free surface case, but \textit{not} in the linear free surface case.
+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.pacanowski.ea_MWR01, campin.adcroft.ea_OM04}.
+The velocity field that appears in (\autoref{eq:tra_adv} is
+Global conservation is obtained in non-linear free surface case,
+but \textit{not} in the linear free surface case.
+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.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
 …
 (see \autoref{chap:LDF}).
+Several tracer advection scheme are proposed, namely a $2^{nd}$ or $4^{th}$ order centred schemes (CEN),
+a $2^{nd}$ or $4^{th}$ order Flux Corrected Transport scheme (FCT), a Monotone Upstream Scheme for
+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 \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.}.
+If the user does not select an advection scheme in the configuration namelist (\textit{namelist\_cfg}),
+the tracers will \textit{not} be advected!
+Several tracer advection scheme are proposed,
+namely a $2^{nd}$ or $4^{th}$ order \textbf{CEN}tred schemes (CEN),
+a $2^{nd}$ or $4^{th}$ order \textbf{F}lux \textbf{C}orrected \textbf{T}ransport scheme (FCT),
+a \textbf{M}onotone \textbf{U}pstream \textbf{S}cheme for
+\textbf{C}onservative \textbf{L}aws scheme (MUSCL),
+a $3^{rd}$ \textbf{U}pstream \textbf{B}iased \textbf{S}cheme (UBS, also often called UP3),
+and a \textbf{Q}uadratic \textbf{U}pstream \textbf{I}nterpolation for
+\textbf{C}onvective \textbf{K}inematics with
+\textbf{E}stimated \textbf{S}treaming \textbf{T}erms scheme (QUICKEST).
+The choice is made in the \nam{tra_adv}{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.}.
+If the user does not select an advection scheme in the configuration namelist
+(\textit{namelist\_cfg}), the tracers will \textit{not} be advected!
 Details of the advection schemes are given below.
+The choosing an advection scheme is a complex matter which depends on the model physics, model resolution,
+type of tracer, as well as the issue of numerical cost. In particular, we note that
+The choosing an advection scheme is a complex matter which depends on the
+model physics, model resolution, type of tracer, as well as the issue of numerical cost.
+In particular, we note that
 \begin{enumerate}
+\item
+  CEN and FCT schemes require an explicit diffusion operator while the other schemes are diffusive enough so that
+  they do not necessarily need additional diffusion;
+\item
+  CEN and UBS are not \textit{positive} schemes
+  \footnote{negative values can appear in an initially strictly positive tracer field which is advected},
+\item CEN and FCT schemes require an explicit diffusion operator while
+  the other schemes are diffusive enough so that they do not necessarily need additional diffusion;
+\item CEN and UBS are not \textit{positive} schemes \footnote{negative values can appear in
+    an initially strictly positive tracer field which is advected},
   implying that false extrema are permitted.
   Their use is not recommended on passive tracers;
 \item
   It is recommended that the same advection-diffusion scheme is used on both active and passive tracers.
+\item It is recommended that the same advection-diffusion scheme is used on
+  both active and passive tracers.
 \end{enumerate}
+Indeed, if a source or sink of a passive tracer depends on an active one, the difference of treatment of active and
+passive tracers can create very nice-looking frontal structures that are pure numerical artefacts.
+Indeed, if a source or sink of a passive tracer depends on an active one,
+the difference of treatment of active and passive tracers can create
+very nice-looking frontal structures that are pure numerical artefacts.
 Nevertheless, most of our users set a different treatment on passive and active tracers,
 that's the reason why this possibility is offered.
+We strongly suggest them to perform a sensitivity experiment using a same treatment to assess the robustness of
+their results.
+% -------------------------------------------------------------------------------------------------------------
+%        2nd and 4th order centred schemes
+% -------------------------------------------------------------------------------------------------------------
+\subsection[CEN: Centred scheme (\forcode{ln_traadv_cen = .true.})]
+{CEN: Centred scheme (\protect\np{ln\_traadv\_cen}\forcode{ = .true.})}
+We strongly suggest them to perform a sensitivity experiment using a same treatment to
+assess the robustness of their results.
+%% =================================================================================================
+\subsection[CEN: Centred scheme (\forcode{ln_traadv_cen})]{CEN: Centred scheme (\protect\np{ln_traadv_cen}{ln\_traadv\_cen})}
 \label{subsec:TRA_adv_cen}
 %        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$.
+The \textbf{CEN}tred advection scheme (CEN) is used when \np[=.true.]{ln_traadv_cen}{ln\_traadv\_cen}.
+Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on
+horizontal (iso-level) and vertical direction by
+setting \np{nn_cen_h}{nn\_cen\_h} and \np{nn_cen_v}{nn\_cen\_v} to $2$ or $4$.
 CEN implementation can be found in the \mdl{traadv\_cen} module.
 In the $2^{nd}$ order centred formulation (CEN2), the tracer at velocity points is evaluated as the mean of
 the two neighbouring $T$-point values.
+In the $2^{nd}$ order centred formulation (CEN2), the tracer at velocity points is evaluated as
+the mean of the two neighbouring $T$-point values.
 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).
+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.
+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.
 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.
+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
+a $4^{th}$ order interpolation, and thus depend on the four neighbouring $T$-points.
+In the $4^{th}$ order formulation (CEN4),
+tracer values are evaluated at u- and v-points as a $4^{th}$ order interpolation,
+and thus depend on the four neighbouring $T$-points.
 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}),
+In the vertical direction (\np[=4]{nn_cen_v}{nn\_cen\_v}),
 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_JCP92}.
+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_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.
 The expression \textit{$4^{th}$ order scheme} used in oceanographic literature is usually associated with
 the scheme presented here.
 Introducing a \forcode{.true.} $4^{th}$ order advection scheme is feasible but, for consistency reasons,
 it requires changes in the discretisation of the tracer advection together with changes in the continuity equation,
 and the momentum advection and pressure terms.
+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.
+Introducing a ``true'' $4^{th}$ order advection scheme is feasible but, for consistency reasons,
+it requires changes in the discretisation of the tracer advection together with
+changes in the continuity equation, and the momentum advection and pressure terms.
 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.
+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.
+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.
 At a $T$-grid cell adjacent to a boundary (coastline, bottom and surface),
 …
 This hypothesis usually reduces the order of the scheme.
 Here we choose to set the gradient of $T$ across the boundary to zero.
+Alternative conditions can be specified, such as a reduction to a second order scheme for
+these near boundary grid points.
+% -------------------------------------------------------------------------------------------------------------
+%        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.})}
+Alternative conditions can be specified,
+such as a reduction to a second order scheme for these near boundary grid points.
+%% =================================================================================================
+\subsection[FCT: Flux Corrected Transport scheme (\forcode{ln_traadv_fct})]{FCT: Flux Corrected Transport scheme (\protect\np{ln_traadv_fct}{ln\_traadv\_fct})}
 \label{subsec:TRA_adv_tvd}
+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$.
+The \textbf{F}lux \textbf{C}orrected \textbf{T}ransport schemes (FCT) is used when
+\np[=.true.]{ln_traadv_fct}{ln\_traadv\_fct}.
+Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on
+horizontal (iso-level) and vertical direction by
+setting \np{nn_fct_h}{nn\_fct\_h} and \np{nn_fct_v}{nn\_fct\_v} to $2$ or $4$.
 FCT implementation can be found in the \mdl{traadv\_fct} module.
 In FCT formulation, the tracer at velocity points is evaluated using a combination of an upstream and
 a centred scheme.
+In FCT formulation, the tracer at velocity points is evaluated using
+a combination of an upstream and a centred scheme.
 For example, in the $i$-direction :
 \begin{equation}
   \label{eq:tra_adv_fct}
+  \label{eq:TRA_adv_fct}
   \begin{split}
     \tau_u^{ups} &=
 …
                      T_{i + 1} & \text{if~} u_{i + 1/2} <    0 \\
                      T_i       & \text{if~} u_{i + 1/2} \geq 0 \\
+    \end{cases}
+    \\
+    \end{cases} \\
     \tau_u^{fct} &= \tau_u^{ups} + c_u \, \big( \tau_u^{cen} - \tau_u^{ups} \big)
   \end{split}
 …
 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}{nn\_fct\_h} and \np{nn_fct_v}{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}.
 …
 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:STP}),
+$\tau_u^{cen}$ is evaluated in (\autoref{eq:tra_adv_fct}) using the \textit{now} tracer while
+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
+while a forward scheme is used for the diffusive part.
+% -------------------------------------------------------------------------------------------------------------
+%        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.})}
+In other words, the advective part of the scheme is time stepped with a leap-frog scheme while
+a forward scheme is used for the diffusive part.
+%% =================================================================================================
+\subsection[MUSCL: Monotone Upstream Scheme for Conservative Laws (\forcode{ln_traadv_mus})]{MUSCL: Monotone Upstream Scheme for Conservative Laws (\protect\np{ln_traadv_mus}{ln\_traadv\_mus})}
 \label{subsec:TRA_adv_mus}
+The Monotone Upstream Scheme for Conservative Laws (MUSCL) is used when \np{ln\_traadv\_mus}\forcode{ = .true.}.
+The \textbf{M}onotone \textbf{U}pstream \textbf{S}cheme for \textbf{C}onservative \textbf{L}aws
+(MUSCL) is used when \np[=.true.]{ln_traadv_mus}{ln\_traadv\_mus}.
 MUSCL implementation can be found in the \mdl{traadv\_mus} module.
 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}).
+In its formulation, the tracer at velocity points is evaluated assuming
+a linear tracer variation between 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}
                        \tau_i         &+ \frac{1}{2} \lt( 1 - \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt)
                        \widetilde{\partial_i         \tau} & \text{if~} u_{i + 1/2} \geqslant 0 \\
                        \tau_{i + 1/2} &+ \frac{1}{2} \lt( 1 + \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt)
                        \widetilde{\partial_{i + 1/2} \tau} & \text{if~} u_{i + 1/2} <         0
+    \tau_i        &+ \frac{1}{2} \lt( 1 - \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt)
+    \widetilde{\partial_i        \tau} & \text{if~} u_{i + 1/2} \geqslant 0 \\
+    \tau_{i + 1/2} &+ \frac{1}{2} \lt( 1 + \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt)
+    \widetilde{\partial_{i + 1/2} \tau} & \text{if~} u_{i + 1/2} <         0
   \end{split}
                                                                                                       \rt.
 \end{equation}
 where $\widetilde{\partial_i \tau}$ is the slope of the tracer on which a limitation is imposed to
 ensure the \textit{positive} character of the scheme.
 The time stepping is performed using a forward scheme, that is the \textit{before} tracer field is used to
 evaluate $\tau_u^{mus}$.
+\]
+where $\widetilde{\partial_i \tau}$ is the slope of the tracer on which
+a limitation is imposed to ensure the \textit{positive} character of the scheme.
+The time stepping is performed using a forward scheme,
+that is the \textit{before} tracer field is used to evaluate $\tau_u^{mus}$.
 For an ocean grid point adjacent to land and where the ocean velocity is directed toward land,
 an upstream flux is used.
 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 (\forcode{ln_traadv_ubs = .true.})]
+{UBS a.k.a. UP3: Upstream-Biased Scheme (\protect\np{ln\_traadv\_ubs}\forcode{ = .true.})}
+In addition, fluxes round a grid-point where a runoff is applied can optionally be computed using
+upstream fluxes (\np[=.true.]{ln_mus_ups}{ln\_mus\_ups}).
+%% =================================================================================================
+\subsection[UBS a.k.a. UP3: Upstream-Biased Scheme (\forcode{ln_traadv_ubs})]{UBS a.k.a. UP3: Upstream-Biased Scheme (\protect\np{ln_traadv_ubs}{ln\_traadv\_ubs})}
 \label{subsec:TRA_adv_ubs}
+The Upstream-Biased Scheme (UBS) is used when \np{ln\_traadv\_ubs}\forcode{ = .true.}.
+The \textbf{U}pstream-\textbf{B}iased \textbf{S}cheme (UBS) is used when
+\np[=.true.]{ln_traadv_ubs}{ln\_traadv\_ubs}.
 UBS implementation can be found in the \mdl{traadv\_mus} module.
 The UBS scheme, often called UP3, is also known as the Cell Averaged QUICK scheme
+(Quadratic Upstream Interpolation for Convective Kinematics).
+(\textbf{Q}uadratic \textbf{U}pstream \textbf{I}nterpolation for
+\textbf{C}onvective \textbf{K}inematics).
 It is an upstream-biased third order scheme based on an upstream-biased parabolic interpolation.
 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}
                                                       \tau"_i       & \text{if~} u_{i + 1/2} \geqslant 0 \\
                                                       \tau"_{i + 1} & \text{if~} u_{i + 1/2} <         0
+      \tau"_i       & \text{if~} u_{i + 1/2} \geqslant 0 \\
+      \tau"_{i + 1} & \text{if~} u_{i + 1/2} <         0
     \end{cases}
+  \quad
+  \text{where~} \tau"_i = \delta_i \lt[ \delta_{i + 1/2} [\tau] \rt]
+  \quad \text{where~} \tau"_i = \delta_i \lt[ \delta_{i + 1/2} [\tau] \rt]
 \end{equation}
 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{farrow.stevens_JPO95}.
+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,
 but the amplitude of such are significantly reduced over the centred second or fourth order method.
+Therefore it is not recommended that it should be applied to a passive tracer that requires positivity.
+Therefore it is not recommended that it should be applied to
+a passive tracer that requires positivity.
 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_phd14}.
 Therefore the vertical flux is evaluated using either a $2^nd$ order FCT scheme or a $4^th$ order COMPACT scheme
 (\np{nn\_ubs\_v}\forcode{ = 2 or 4}).
 For stability reasons (see \autoref{chap:STP}), 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),
+Therefore the vertical flux is evaluated using either a $2^nd$ order FCT scheme or
+a $4^th$ order COMPACT scheme (\np[=2 or 4]{nn_ubs_v}{nn\_ubs\_v}).
+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.de-cuevas.ea_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.de-cuevas.ea_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:
+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:
 \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}.
+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 (\forcode{ln_traadv_qck = .true.})]
+{QCK: QuiCKest scheme (\protect\np{ln\_traadv\_qck}\forcode{ = .true.})}
+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}.
+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}.
+%% =================================================================================================
+\subsection[QCK: QuiCKest scheme (\forcode{ln_traadv_qck})]{QCK: QuiCKest scheme (\protect\np{ln_traadv_qck}{ln\_traadv\_qck})}
 \label{subsec:TRA_adv_qck}
+The Quadratic Upstream Interpolation for Convective Kinematics with Estimated Streaming Terms (QUICKEST) scheme
+proposed by \citet{leonard_CMAME79} is used when \np{ln\_traadv\_qck}\forcode{ = .true.}.
+The \textbf{Q}uadratic \textbf{U}pstream \textbf{I}nterpolation for
+\textbf{C}onvective \textbf{K}inematics with \textbf{E}stimated \textbf{S}treaming \textbf{T}erms
+(QUICKEST) scheme proposed by \citet{leonard_CMAME79} is used when
+\np[=.true.]{ln_traadv_qck}{ln\_traadv\_qck}.
 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{leonard_CMAME91}.
+It has been implemented in \NEMO\ by G. Reffray (MERCATOR-ocean) and can be found in the \mdl{traadv\_qck} module.
+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.
 …
 Therefore the vertical flux is evaluated using the CEN2 scheme.
 This no longer guarantees the positivity of the scheme.
+The use of FCT in the vertical direction (as for the UBS case) should be implemented to restore this property.
+The use of FCT in the vertical direction (as for the UBS case) should be implemented to
+restore this property.
 %%%gmcomment   :  Cross term are missing in the current implementation....
+% ================================================================
+% Tracer Lateral Diffusion
+% ================================================================
+\section[Tracer lateral diffusion (\textit{traldf.F90})]
+{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}
+%-------------------------------------------------------------------------------------------------------------
+Options are defined through the \nam{tra\_ldf} namelist variables.
+\begin{listing}
+  \nlst{namtra_ldf}
+  \caption{\forcode{&namtra_ldf}}
+  \label{lst:namtra_ldf}
+\end{listing}
+Options are defined through the \nam{tra_ldf}{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
+$(iv)$  the specification of eddy diffusivity coefficient (either constant or variable in space and time).
+Item $(iv)$ will be described in \autoref{chap:LDF}.
+\begin{enumerate*}[label=(\textit{\roman*})]
+\item the type of operator used (none, laplacian, bilaplacian),
+\item the direction along which the operator acts (iso-level, horizontal, iso-neutral),
+\item some specific options related to the rotated operators (\ie\ non-iso-level operator), and
+\item the specification of eddy diffusivity coefficient
+  (either constant or variable in space and time).
+\end{enumerate*}
+Item (iv) will be described in \autoref{chap:LDF}.
 The direction along which the operators act is defined through the slope between
 this direction and the iso-level surfaces.
 …
 \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.debreu.ea_OM12}.
+% -------------------------------------------------------------------------------------------------------------
+%        Type of operator
+% -------------------------------------------------------------------------------------------------------------
+\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}) }
+This latter component is solved implicitly together with the vertical diffusion term
+(see \autoref{chap:TD}).
+When \np[=.true.]{ln_traldf_msc}{ln\_traldf\_msc},
+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}.
+%% =================================================================================================
+\subsection[Type of operator (\forcode{ln_traldf_}\{\forcode{OFF,lap,blp}\})]{Type of operator (\protect\np{ln_traldf_OFF}{ln\_traldf\_OFF}, \protect\np{ln_traldf_lap}{ln\_traldf\_lap}, or \protect\np{ln_traldf_blp}{ln\_traldf\_blp})}
 \label{subsec:TRA_ldf_op}
 …
 \begin{description}
+\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.}:]
+  a laplacian operator is selected.
+  This harmonic operator takes the following expression:  $\mathpzc{L}(T) = \nabla \cdot A_{ht} \; \nabla T $,
+\item [{\np[=.true.]{ln_traldf_OFF}{ln\_traldf\_OFF}}] 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[=.true.]{ln_traldf_lap}{ln\_traldf\_lap}}] a laplacian operator is selected.
+  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.}]:
+  a bilaplacian operator is selected.
+\item [{\np[=.true.]{ln_traldf_blp}{ln\_traldf\_blp}}] 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}).
+  and $b^2 = B_{ht}$ is the eddy diffusivity coefficient expressed in $m^4/s$
+  (see \autoref{chap:LDF}).
   In the code, the bilaplacian operator is obtained by calling the laplacian twice.
 \end{description}
 …
 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
+disturbances of wavelength $\lambda$ (so that short waves damped more rapidelly than long ones),
+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 (\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}) }
+%% =================================================================================================
+\subsection[Action direction (\forcode{ln_traldf_}\{\forcode{lev,hor,iso,triad}\})]{Direction of action (\protect\np{ln_traldf_lev}{ln\_traldf\_lev}, \protect\np{ln_traldf_hor}{ln\_traldf\_hor}, \protect\np{ln_traldf_iso}{ln\_traldf\_iso}, or \protect\np{ln_traldf_triad}{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[=.true.]{ln_traldf_lev}{ln\_traldf\_lev}) or when
+a horizontal (\ie\ geopotential) operator is demanded in \textit{z}-coordinate
+(\np{ln_traldf_hor}{ln\_traldf\_hor} and \np[=.true.]{ln_zco}{ln\_zco}).
 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}{ln\_traldf\_iso} or \np{ln_traldf_triad}{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.})
 \footnote{In this case, the standard iso-neutral operator will be automatically selected}.
+(\np{ln_traldf_hor}{ln\_traldf\_hor} and \np{ln_sco}{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
 diffusive fluxes acts on the three spatial direction.
 …
 the next two sub-sections.
+% -------------------------------------------------------------------------------------------------------------
+%       iso-level operator
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Iso-level (bi-)laplacian operator (\texttt{ln\_traldf\_iso})]
+{Iso-level (bi-)laplacian operator ( \protect\np{ln\_traldf\_iso})}
+%% =================================================================================================
+\subsection[Iso-level (bi-)laplacian operator (\forcode{ln_traldf_iso})]{Iso-level (bi-)laplacian operator ( \protect\np{ln_traldf_iso}{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}
+  \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{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
+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.}.
+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}{ln\_traldf\_lap} or \np[=.true.]{ln_traldf_blp}{ln\_traldf\_blp},
+we have \np[=.true.]{ln_traldf_lev}{ln\_traldf\_lev} or
+\np[=]{ln_traldf_hor}{ln\_traldf\_hor}\np[=.true.]{ln_zco}{ln\_zco}.
 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[=.true.]{ln_zps}{ln\_zps}),
 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}
 \label{subsec:TRA_ldf_iso_triad}
+%&&    Standard rotated (bi-)laplacian operator
+%&& ----------------------------------------------
+\subsubsection[Standard rotated (bi-)laplacian operator (\textit{traldf\_iso.F90})]
+{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})
+takes the following semi -discrete space form in $z$- and $s$-coordinates:
+\begin{equation}
+  \label{eq:tra_ldf_iso}
+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}
   \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]
 …
 $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.}.
+It is thus used when, in addition to \np[=.true.]{ln_traldf_lap}{ln\_traldf\_lap},
+we have \np[=.true.]{ln_traldf_iso}{ln\_traldf\_iso},
+or both \np[=.true.]{ln_traldf_hor}{ln\_traldf\_hor} and \np[=.true.]{ln_zco}{ln\_zco}.
 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.
+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}).
+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.
+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}).
 For computer efficiency reasons, this term is not computed in the \mdl{traldf\_iso} module,
 but in the \mdl{trazdf} module where, if iso-neutral mixing is used,
+the vertical mixing coefficient is simply increased by $\frac{e_{1w} e_{2w}}{e_{3w}}(r_{1w}^2 + r_{2w}^2)$.
+the vertical mixing coefficient is simply increased by
+$\frac{e_{1w} e_{2w}}{e_{3w}}(r_{1w}^2 + r_{2w}^2)$.
 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.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.
+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.madec.ea_CD01}.
+Note that in the partial step $z$-coordinate (\np[=.true.]{ln_zps}{ln\_zps}),
+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
+%&&  -------------------------------------------
+\subsubsection[Triad rotated (bi-)laplacian operator (\textit{ln\_traldf\_triad})]
+{Triad rotated (bi-)laplacian operator (\protect\np{ln\_traldf\_triad})}
+%% =================================================================================================
+\subsubsection[Triad rotated (bi-)laplacian operator (\forcode{ln_traldf_triad})]{Triad rotated (bi-)laplacian operator (\protect\np{ln_traldf_triad}{ln\_traldf\_triad})}
 \label{subsec:TRA_ldf_triad}
+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: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[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}).
+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,
 normal to the bottom and normal to the surface are set to zero.
+%&&    Option for the rotated operators
+%&& ----------------------------------------------
+%% =================================================================================================
 \subsubsection{Option for the rotated operators}
 \label{subsec:TRA_ldf_options}
+\begin{itemize}
+\item \np{ln\_traldf\_msc} = Method of Stabilizing Correction (both operators)
+\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{ln\_botmix\_triad} = lateral mixing on bottom (triad only)
+\end{itemize}
+% ================================================================
+% Tracer Vertical Diffusion
+% ================================================================
+\section[Tracer vertical diffusion (\textit{trazdf.F90})]
+{Tracer vertical diffusion (\protect\mdl{trazdf})}
+\begin{labeling}{{\np{ln_botmix_triad}{ln\_botmix\_triad}}}
+\item [{\np{ln_traldf_msc}{ln\_traldf\_msc}    }] Method of Stabilizing Correction (both operators)
+\item [{\np{rn_slpmax}{rn\_slpmax}             }] Slope limit (both operators)
+\item [{\np{ln_triad_iso}{ln\_triad\_iso}      }] Pure horizontal mixing in ML (triad only)
+\item [{\np{rn_sw_triad}{rn\_sw\_triad}        }] \forcode{=1} switching triad;
+  \forcode{= 0} all 4 triads used (triad only)
+\item [{\np{ln_botmix_triad}{ln\_botmix\_triad}}] Lateral mixing on bottom (triad only)
+\end{labeling}
+%% =================================================================================================
+\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 \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:
+\begin{gather*}
+  % \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]
+\end{gather*}
+where $A_w^{vT}$ and $A_w^{vS}$ are the vertical eddy diffusivity coefficients on temperature and salinity,
+respectively.
+Options are defined through the \nam{zdf}{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:MB_zdf}) takes
+the following semi-discrete space form:
+\[
+  % \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] \quad
+  D^{vS}_T = \frac{1}{e_{3t}} \; \delta_k \lt[ \, \frac{A^{vS}_w}{e_{3w}} \delta_{k + 1/2}[S] \, \rt]
+\]
+where $A_w^{vT}$ and $A_w^{vS}$ are the vertical eddy diffusivity coefficients on
+temperature and salinity, respectively.
 Generally, $A_w^{vT} = A_w^{vS}$ except when double diffusive mixing is parameterised
 (\ie\ \np{ln\_zdfddm} equals \forcode{.true.},).
+(\ie\ \np[=.true.]{ln_zdfddm}{ln\_zdfddm},).
 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}.
+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}.
 At the surface and bottom boundaries, the turbulent fluxes of heat and salt must be specified.
 …
 a geothermal flux forcing is prescribed as a bottom boundary condition (see \autoref{subsec:TRA_bbc}).
 The large eddy coefficient found in the mixed layer together with high vertical resolution implies that
 there would be too restrictive constraint on the time step if we use explicit time stepping.
+The large eddy coefficient found in the mixed layer together with high vertical resolution implies
+that 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.
+% ================================================================
+% External Forcing
+% ================================================================
+%% =================================================================================================
 \section{External forcing}
 \label{sec:TRA_sbc_qsr_bbc}
+% -------------------------------------------------------------------------------------------------------------
+%        surface boundary condition
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Surface boundary condition (\textit{trasbc.F90})]
+{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
+both to the heat and salt fluxes crossing the sea surface (not linked with $F_{mass}$) and
+(\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.
 They are both included directly in $Q_{ns}$, the surface heat flux,
 and $F_{salt}$, the surface salt flux (see \autoref{chap:SBC} for further details).
+By doing this, the forcing formulation is the same for any tracer (including temperature and salinity).
+The surface module (\mdl{sbcmod}, see \autoref{chap:SBC}) provides the following forcing fields (used on tracers):
+\begin{itemize}
+\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
+  penetrates into the water column, see \autoref{subsec:TRA_qsr})
+By doing this, the forcing formulation is the same for any tracer
+(including temperature and salinity).
+The surface module (\mdl{sbcmod}, see \autoref{chap:SBC}) provides the following forcing fields
+(used on tracers):
+\begin{labeling}{\textit{fwfisf}}
+\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 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.
+\item
+  $\textit{sfx}$, the salt flux resulting from ice-ocean mass exchange (freezing, melting, ridging...)
+\item
+  \textit{emp}, the mass flux exchanged with the atmosphere (evaporation minus precipitation) and
+\item [\textit{sfx}] The salt flux resulting from ice-ocean mass exchange
+  (freezing, melting, ridging...)
+\item [\textit{emp}] The mass flux exchanged with the atmosphere (evaporation minus precipitation) and
   possibly with the sea-ice and ice-shelves.
+\item
+  \textit{rnf}, the mass flux associated with runoff
+\item [\textit{rnf}] The mass flux associated with runoff
   (see \autoref{sec:SBC_rnf} for further detail of how it acts on temperature and salinity tendencies)
+\item
+  \textit{fwfisf}, the mass flux associated with ice shelf melt,
+\item [\textit{fwfisf}] The mass flux associated with ice shelf melt,
   (see \autoref{sec:SBC_isf} for further details on how the ice shelf melt is computed and applied).
 \end{itemize}
+\end{labeling}
 The surface boundary condition on temperature and salinity is applied as follows:
 \begin{equation}
+  \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 \\
+    F^S &=               &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} &\overline{\textit{sfx}}^t
+  \end{alignedat}
+  \label{eq:TRA_sbc}
+    F^T = \frac{1}{C_p} \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} \overline{Q_{ns}      }^t \qquad
+    F^S =               \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} \overline{\textit{sfx}}^t
 \end{equation}
 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
+both temperature and salinity.
+On temperature, this term remove the heat content associated with mass exchange that has been added to $Q_{ns}$.
+On salinity, this term mimics the concentration/dilution effect that would have resulted from a change in
+the volume of the first level.
+Such time averaging prevents the divergence of odd and even time step (see \autoref{chap:TD}).
+In the linear free surface case (\np[=.true.]{ln_linssh}{ln\_linssh}),
+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}$.
+On salinity, this term mimics the concentration/dilution effect that would have resulted from
+a change in the volume of the first level.
 The resulting surface boundary condition is applied as follows:
 \begin{equation}
+  \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{(Q_{ns}       - C_p \, \textit{emp} \lt. T \rt|_{k = 1})}^t \\
+    F^S &=               &\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}
+Note that an exact conservation of heat and salt content is only achieved with non-linear free surface.
+  \label{eq:TRA_sbc_lin}
+    F^T = \frac{1}{C_p} \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}}
+          \overline{(Q_{ns}       - C_p \, \textit{emp} \lt. T \rt|_{k = 1})}^t \qquad
+    F^S =               \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}}
+          \overline{(\textit{sfx} -        \textit{emp} \lt. S \rt|_{k = 1})}^t
+\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 (\textit{traqsr.F90})]
+{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}).
+%% =================================================================================================
+\subsection[Solar radiation penetration (\textit{traqsr.F90})]{Solar radiation penetration (\protect\mdl{traqsr})}
 \label{subsec:TRA_qsr}
+%--------------------------------------------namqsr--------------------------------------------------------
+\nlst{namtra_qsr}
+%--------------------------------------------------------------------------------------------------------------
+Options are defined through the \nam{tra\_qsr} namelist variables.
+When the penetrative solar radiation option is used (\np{ln\_traqsr}\forcode{ = .true.}),
+\begin{listing}
+  \nlst{namtra_qsr}
+  \caption{\forcode{&namtra_qsr}}
+  \label{lst:namtra_qsr}
+\end{listing}
+Options are defined through the \nam{tra_qsr}{tra\_qsr} namelist variables.
+When the penetrative solar radiation option is used (\np[=.true.]{ln_traqsr}{ln\_traqsr}),
 the solar radiation penetrates the top few tens of meters of the ocean.
+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: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}
+If it is not used (\np[=.false.]{ln_traqsr}{ln\_traqsr}) 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:TRA_PE_qsr}
   \begin{gathered}
     \pd[T]{t} = \ldots + \frac{1}{\rho_o \, C_p \, e_3} \; \pd[I]{k} \\
 …
 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}
 The shortwave radiation, $Q_{sr}$, consists of energy distributed across a wide spectral range.
+The ocean is strongly absorbing for wavelengths longer than 700~nm and these wavelengths contribute to
+heating the upper few tens of centimetres.
+The fraction of $Q_{sr}$ that resides in these almost non-penetrative wavebands, $R$, is $\sim 58\%$
+(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 \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.})
+The ocean is strongly absorbing for wavelengths longer than 700 $nm$ and
+these wavelengths contribute to heat the upper few tens of centimetres.
+The fraction of $Q_{sr}$ that resides in these almost non-penetrative wavebands, $R$, is $\sim$ 58\%
+(specified through namelist parameter \np{rn_abs}{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}{rn\_si0} in the \nam{tra_qsr}{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[=.true.]{ln_qsr_2bd}{ln\_qsr\_2bd})
 a chlorophyll-independent monochromatic formulation is chosen for the shorter wavelengths,
 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]
 \]
 where $\xi_1$ is the second extinction length scale associated with the shorter wavelengths.
 It is usually chosen to be 23~m by setting the \np{rn\_si0} namelist parameter.
 The set of default values ($\xi_0, \xi_1, R$) corresponds to a Type I water in Jerlov's (1968) classification
 (oligotrophic waters).
+It is usually chosen to be 23~m by setting the \np{rn_si0}{rn\_si0} namelist parameter.
+The set of default values ($\xi_0, \xi_1, R$) corresponds to
+a Type I water in Jerlov's (1968) classification (oligotrophic waters).
 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
 a 61 waveband formulation.
 Unfortunately, such a model is very computationally expensive.
+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}),
+assuming the same power-law relationship.
+As shown in \autoref{fig:traqsr_irradiance}, this formulation, called RGB (Red-Green-Blue),
+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-700 $nm$).
+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}), assuming the same power-law relationship.
+As shown in \autoref{fig:TRA_qsr_irradiance}, this formulation,
+called RGB (\textbf{R}ed-\textbf{G}reen-\textbf{B}lue),
 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
+nonuniform chlorophyll classes ranging from 0.01 to 10 g.Chl/L
+The RGB formulation is used when \np[=.true.]{ln_qsr_rgb}{ln\_qsr\_rgb}.
+The RGB attenuation coefficients (\ie\ the inverses of the extinction length scales) are
+tabulated over 61 nonuniform chlorophyll classes ranging from 0.01 to 10 $g.Chl/L$
 (see the routine \rou{trc\_oce\_rgb} in \mdl{trc\_oce} module).
 Four types of chlorophyll can be chosen in the RGB formulation:
 \begin{description}
+\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\_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.}]
+  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 and the oceanic heating rate.
+\item [{\np[=0]{nn_chldta}{nn\_chldta}}] a constant 0.05 $g.Chl/L$ value everywhere;
+\item [{\np[=1]{nn_chldta}{nn\_chldta}}] an observed time varying chlorophyll deduced from
+  satellite surface ocean color measurement spread uniformly in the vertical direction;
+\item [{\np[=2]{nn_chldta}{nn\_chldta}}] 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[=.true.]{ln_qsr_bio}{ln\_qsr\_bio}}] 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\ 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 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}.
 …
 (\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.
+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).
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=\textwidth]{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.menkes.ea_CD07}.
+    }
+  \end{center}
+\begin{figure}
+  \centering
+  \includegraphics[width=0.66\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 (\textit{trabbc.F90}) - \forcode{ln_trabbc = .true.})]
+{Bottom boundary condition (\protect\mdl{trabbc})}
+%% =================================================================================================
+\subsection[Bottom boundary condition (\textit{trabbc.F90}) - \forcode{ln_trabbc})]{Bottom boundary condition (\protect\mdl{trabbc} - \protect\np{ln_trabbc}{ln\_trabbc})}
 \label{subsec:TRA_bbc}
+%--------------------------------------------nambbc--------------------------------------------------------
 \nlst{nambbc}
+%--------------------------------------------------------------------------------------------------------------
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
     \includegraphics[width=\textwidth]{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_N92}.
+    }
   \end{center}
+\begin{listing}
+  \nlst{nambbc}
+  \caption{\forcode{&nambbc}}
+  \label{lst:nambbc}
+\end{listing}
+\begin{figure}
+  \centering
+  \includegraphics[width=0.66\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.
 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_N92}),
+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_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 \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{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}.
+% ================================================================
+% Bottom Boundary Layer
+% ================================================================
+\section[Bottom boundary layer (\textit{trabbl.F90} - \forcode{ln_trabbl = .true.})]
+{Bottom boundary layer (\protect\mdl{trabbl} - \protect\np{ln\_trabbl}\forcode{ = .true.})}
+(\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}{bbc} namelist variables.
+The presence of geothermal heating is controlled by
+setting the namelist parameter \np{ln_trabbc}{ln\_trabbc} to true.
+Then, when \np{nn_geoflx}{nn\_geoflx} is set to 1, a constant geothermal heating is introduced whose
+value is given by the \np{rn_geoflx_cst}{rn\_geoflx\_cst}, which is also a namelist parameter.
+When \np{nn_geoflx}{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:TRA_geothermal}) \citep{emile-geay.madec_OS09}.
+%% =================================================================================================
+\section[Bottom boundary layer (\textit{trabbl.F90} - \forcode{ln_trabbl})]{Bottom boundary layer (\protect\mdl{trabbl} - \protect\np{ln_trabbl}{ln\_trabbl})}
 \label{sec:TRA_bbl}
+%--------------------------------------------nambbl---------------------------------------------------------
+\nlst{nambbl}
+%--------------------------------------------------------------------------------------------------------------
+Options are defined through the \nam{bbl} namelist variables.
+\begin{listing}
+  \nlst{nambbl}
+  \caption{\forcode{&nambbl}}
+  \label{lst:nambbl}
+\end{listing}
+Options are defined through the \nam{bbl}{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.
 …
 where dense water formed in marginal seas flows into a basin filled with less dense water,
 or along the continental slope when dense water masses are formed on a continental shelf.
+The amount of entrainment that occurs in these gravity plumes is critical in determining the density and
+volume flux of the densest waters of the ocean, such as Antarctic Bottom Water, or North Atlantic Deep Water.
+The amount of entrainment that occurs in these gravity plumes is critical in
+determining the density and volume flux of the densest waters of the ocean,
+such as Antarctic Bottom Water, or North Atlantic Deep Water.
 $z$-coordinate models tend to overestimate the entrainment,
+because the gravity flow is mixed vertically by convection as it goes ''downstairs'' following the step topography,
+because the gravity flow is mixed vertically by convection as
+it goes ''downstairs'' following the step topography,
 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.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},
+A similar problem occurs in the $s$-coordinate when
+the thickness of the bottom level varies rapidly downstream of 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.
+The communication can be by a diffusive flux (diffusive BBL), an advective flux (advective BBL), or both.
+The communication can be by a diffusive flux (diffusive BBL),
+an advective flux (advective BBL), or both.
 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_T99}.
+% -------------------------------------------------------------------------------------------------------------
+%        Diffusive BBL
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Diffusive bottom boundary layer (\forcode{nn_bbl_ldf = 1})]
+{Diffusive bottom boundary layer (\protect\np{nn\_bbl\_ldf}\forcode{ = 1})}
+Furthermore, it only connects ocean bottom cells,
+and therefore does not include all the improvements introduced by \citet{campin.goosse_T99}.
+%% =================================================================================================
+\subsection[Diffusive bottom boundary layer (\forcode{nn_bbl_ldf=1})]{Diffusive bottom boundary layer (\protect\np[=1]{nn_bbl_ldf}{nn\_bbl\_ldf})}
 \label{subsec:TRA_bbl_diff}
+When applying sigma-diffusion (\np{ln\_trabbl}\forcode{ = .true.} and \np{nn\_bbl\_ldf} set to 1),
+When applying sigma-diffusion
+(\np[=.true.]{ln_trabbl}{ln\_trabbl} and \np{nn_bbl_ldf}{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.
+with $\nabla_\sigma$ the lateral gradient operator taken between bottom cells,
+and $A_l^\sigma$ the lateral diffusivity in the BBL.
 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}
+  \label{eq:TRA_bbl_coef}
   A_l^\sigma (i,j,t) =
       \begin{cases}
         A_{bbl} & \text{if~} \nabla_\sigma \rho \cdot \nabla H < 0 \\
+        \\
+      & \text{otherwise} \\
+      & \text{otherwise}
       \end{cases}
 \end{equation}
+where $A_{bbl}$ is the BBL diffusivity coefficient, given by the namelist parameter \np{rn\_ahtbbl} and
+where $A_{bbl}$ is the BBL diffusivity coefficient,
+given by the namelist parameter \np{rn_ahtbbl}{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
 \]
+where $\rho$, $\alpha$ and $\beta$ are functions of $\overline T^\sigma$, $\overline S^\sigma$ and
+$\overline H^\sigma$, the along bottom mean temperature, salinity and depth, respectively.
+% -------------------------------------------------------------------------------------------------------------
+%        Advective BBL
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Advective bottom boundary layer (\forcode{nn_bbl_adv = [12]})]
+{Advective bottom boundary layer (\protect\np{nn\_bbl\_adv}\forcode{ = [12]})}
+where $\rho$, $\alpha$ and $\beta$ are functions of
+$\overline T^\sigma$, $\overline S^\sigma$ and $\overline H^\sigma$,
+the along bottom mean temperature, salinity and depth, respectively.
+%% =================================================================================================
+\subsection[Advective bottom boundary layer (\forcode{nn_bbl_adv=1,2})]{Advective bottom boundary layer (\protect\np[=1,2]{nn_bbl_adv}{nn\_bbl\_adv})}
 \label{subsec:TRA_bbl_adv}
 …
 %}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=\textwidth]{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}
+\begin{figure}
+  \centering
+  \includegraphics[width=0.33\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}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 %!!      nn_bbl_adv = 1   use of the ocean velocity as bbl velocity
 …
 %%%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
+connects two adjacent bottom grid-points only if dense water overlies less dense water on the slope.
+When applying an advective BBL (\np[=1..2]{nn_bbl_adv}{nn\_bbl\_adv}),
+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}:
+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.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}:
+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_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}),
+is simply given by the following expression:
+\[
+  % \label{eq:bbl_Utr}
+  u^{tr}_{bbl} = \gamma g \frac{\Delta \rho}{\rho_o} e_{1u} \, min ({e_{3u}}_{kup},{e_{3u}}_{kdwn})
+\]
+where $\gamma$, expressed in seconds, is the coefficient of proportionality provided as \np{rn\_gambbl},
+a namelist parameter, and \textit{kup} and \textit{kdwn} are the vertical index of the higher and lower cells,
+respectively.
+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_T99}.
+Scalar properties are advected by this additional transport $(u^{tr}_{bbl},v^{tr}_{bbl})$ using the upwind scheme.
+Such a diffusive advective scheme has been chosen to mimic the entrainment between the downslope plume and
+the surrounding water at intermediate depths.
+\begin{description}
+\item [{\np[=1]{nn_bbl_adv}{nn\_bbl\_adv}}] the downslope velocity is chosen to
+  be the Eulerian ocean velocity just above the topographic step
+  (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$).
+\item [{\np[=2]{nn_bbl_adv}{nn\_bbl\_adv}}] 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_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:TRA_bbl}), is simply given by the following expression:
+  \[
+    % \label{eq:TRA_bbl_Utr}
+    u^{tr}_{bbl} = \gamma g \frac{\Delta \rho}{\rho_o} e_{1u} \, min ({e_{3u}}_{kup},{e_{3u}}_{kdwn})
+  \]
+  where $\gamma$, expressed in seconds, is the coefficient of proportionality provided as
+  \np{rn_gambbl}{rn\_gambbl}, a namelist parameter, and
+  \textit{kup} and \textit{kdwn} are the vertical index of the higher and lower cells, respectively.
+  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_T99}.
+\end{description}
+Scalar properties are advected by this additional transport $(u^{tr}_{bbl},v^{tr}_{bbl})$ using
+the upwind scheme.
+Such a diffusive advective scheme has been chosen to mimic the entrainment between
+the downslope plume and 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:
+\begin{alignat}{3}
+  \label{eq: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}
+  \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}
+  \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)
+The advective BBL scheme modifies the tracer time tendency of
+the ocean cells near the topographic step by 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}{5}
+  \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: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) \\
+  \shortintertext{and for $k =kdw-1,\;..., \; kup$ :}
+  \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)
 \end{alignat}
 where $b_t$ is the $T$-cell volume.
 …
 It has to be used to compute the effective velocity as well as the effective overturning circulation.
+% ================================================================
+% Tracer damping
+% ================================================================
+\section[Tracer damping (\textit{tradmp.F90})]
+{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}
+%--------------------------------------------------------------------------------------------------------------
+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}
+  \begin{gathered}
+    \pd[T]{t} = \cdots - \gamma (T - T_o) \\
+    \pd[S]{t} = \cdots - \gamma (S - S_o)
+  \end{gathered}
+\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  \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\_dmp} are set to true in
+\nam{tsd} namelist as well as \np{sn\_tem} and \np{sn\_sal} structures are correctly set
+\begin{listing}
+  \nlst{namtra_dmp}
+  \caption{\forcode{&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}
+    \pd[T]{t} = \cdots - \gamma (T - T_o) \qquad \pd[S]{t} = \cdots - \gamma (S - S_o)
+\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 \nam{tra_dmp}{tra\_dmp} namelist variables.
+The restoring term is added when the namelist parameter \np{ln_tradmp}{ln\_tradmp} is set to true.
+It also requires that both \np{ln_tsd_init}{ln\_tsd\_init} and
+\np{ln_tsd_dmp}{ln\_tsd\_dmp} are set to true in \nam{tsd}{tsd} namelist as well as
+\np{sn_tem}{sn\_tem} and \np{sn_sal}{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 file name is specified by the namelist variable \np{cn\_resto}.
+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
+\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
+(for example to build the initial state of a prognostic simulation,
+or to use the resulting velocity field for a passive tracer study).
+The restoring coefficient $\gamma$ is a three-dimensional array read in during
+the \rou{tra\_dmp\_init} routine.
+The file name is specified by the namelist variable \np{cn_resto}{cn\_resto}.
+The \texttt{DMP\_TOOLS} are provided to allow users to generate the netcdf file.
+The two main cases in which \autoref{eq:TRA_dmp} is used are
+\begin{enumerate*}[label=(\textit{\alph*})]
+\item the specification of the boundary conditions along
+  artificial walls of a limited domain basin and
+\item the computation of the velocity field associated with a given $T$-$S$ field
+  (for example to build the initial state of a prognostic simulation,
+  or to use the resulting velocity field for a passive tracer study).
+\end{enumerate*}
 The first case applies to regional models that have artificial walls instead of open boundaries.
 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.
+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{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$).
 The robust diagnostic method is very efficient in preventing temperature drift in intermediate waters but
 it produces artificial sources of heat and salt within the ocean.
+The robust diagnostic method is very efficient in preventing temperature drift in
+intermediate waters but it produces artificial sources of heat and salt within the ocean.
 It also has undesirable effects on the ocean convection.
+It tends to prevent deep convection and subsequent deep-water formation, by stabilising the water column too much.
+The namelist parameter \np{nn\_zdmp} sets whether the damping should be applied in the whole water column or
+only below the mixed layer (defined either on a density or $S_o$ criterion).
+It tends to prevent deep convection and subsequent deep-water formation,
+by stabilising the water column too much.
+The namelist parameter \np{nn_zdmp}{nn\_zdmp} sets whether the damping should be applied in
+the whole water column or 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.delecluse.ea_JPO96}.
+For generating \ifile{resto}, see the documentation for the DMP tool provided with the source code under
+\path{./tools/DMP_TOOLS}.
+% ================================================================
+% Tracer time evolution
+% ================================================================
+\section[Tracer time evolution (\textit{tranxt.F90})]
+{Tracer time evolution (\protect\mdl{tranxt})}
+For generating \ifile{resto},
+see the documentation for the DMP tools provided with the source code under \path{./tools/DMP_TOOLS}.
+%% =================================================================================================
+\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 \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:STP_mLF}):
+\begin{equation}
+  \label{eq:tra_nxt}
+  \begin{alignedat}{3}
+Options are defined through the \nam{dom}{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}{5}
     &(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] \\
 …
   \end{alignedat}
 \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).
+$\gamma$ is initialized as \np{rn\_atfp} (\textbf{namelist} parameter).
+Its default value is \np{rn\_atfp}\forcode{ = 10.e-3}.
+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).
+$\gamma$ is initialized as \np{rn_atfp}{rn\_atfp}, its default value is \forcode{10.e-3}.
 Note that the forcing correction term in the filter is not applied in linear free surface
+(\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$.
+When the vertical mixing is solved implicitly, the update of the \textit{next} tracer fields is done in
+\mdl{trazdf} module.
+(\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$.
+When the vertical mixing is solved implicitly,
+the update of the \textit{next} tracer fields is done in \mdl{trazdf} module.
 In this case only the swapping of arrays and the Asselin filtering is done in the \mdl{tranxt} module.
+In order to prepare for the computation of the \textit{next} time step, a swap of tracer arrays is performed:
+$T^{t - \rdt} = T^t$ and $T^t = T_f$.
+% ================================================================
+% Equation of State (eosbn2)
+% ================================================================
+\section[Equation of state (\textit{eosbn2.F90})]
+{Equation of state (\protect\mdl{eosbn2})}
+In order to prepare for the computation of the \textit{next} time step,
+a swap of tracer arrays is performed: $T^{t - \rdt} = T^t$ and $T^t = T_f$.
+%% =================================================================================================
+\section[Equation of state (\textit{eosbn2.F90})]{Equation of state (\protect\mdl{eosbn2})}
 \label{sec:TRA_eosbn2}
+%--------------------------------------------nameos-----------------------------------------------------
+\nlst{nameos}
+%--------------------------------------------------------------------------------------------------------------
+% -------------------------------------------------------------------------------------------------------------
+%        Equation of State
+% -------------------------------------------------------------------------------------------------------------
+\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}) }
+\begin{listing}
+  \nlst{nameos}
+  \caption{\forcode{&nameos}}
+  \label{lst:nameos}
+\end{listing}
+%% =================================================================================================
+\subsection[Equation of seawater (\forcode{ln_}\{\forcode{teos10,eos80,seos}\})]{Equation of seawater (\protect\np{ln_teos10}{ln\_teos10}, \protect\np{ln_teos80}{ln\_teos80}, or \protect\np{ln_seos}{ln\_seos})}
 \label{subsec:TRA_eos}
+The Equation Of Seawater (EOS) is an empirical nonlinear thermodynamic relationship linking seawater density,
+$\rho$, to a number of state variables, most typically temperature, salinity and pressure.
+The \textbf{E}quation \textbf{O}f \textbf{S}eawater (EOS) is
+an empirical nonlinear thermodynamic relationship linking
+seawater density, $\rho$, to a number of state variables,
+most typically temperature, salinity and pressure.
 Because density gradients control the pressure gradient force through the hydrostatic balance,
 the equation of state provides a fundamental bridge between the distribution of active tracers and
 the fluid dynamics.
+the equation of state provides a fundamental bridge between
+the distribution of active tracers and the fluid dynamics.
 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.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
+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-80, both variables being more suitable for use as model variables
+\citep{ioc.iapso_bk10, graham.mcdougall_JPO13}.
+\begin{enumerate*}[label=(\textit{\roman*})]
+\item it is the new official EOS,
+\item it is more accurate, being based on an updated database of laboratory measurements, and
+\item it uses Conservative Temperature and Absolute Salinity
+  (instead of potential temperature and practical salinity for EOS-80),
+  both variables being more suitable for use as model variables
+  \citep{ioc.iapso_bk10, graham.mcdougall_JPO13}.
+\end{enumerate*}
 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{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.
+Called \textit{rau0} in the code, $\rho_o$ is set in \mdl{phycst} to a value of $1,026~Kg/m^3$.
+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{gill_bk82}.
+Options which control the EOS used are defined through the \ngn{nameos} namelist variables.
+In the computer code, a density anomaly, $d_a = \rho / \rho_o - 1$, is computed,
+with $\rho_o$ a reference density.
+Called \textit{rau0} in the code,
+$\rho_o$ is set in \mdl{phycst} to a value of \texttt{1,026} $Kg/m^3$.
+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{gill_bk82}.
+Options which control the EOS used are defined through the \nam{eos}{eos} namelist variables.
 \begin{description}
 \item[\np{ln\_teos10}\forcode{ = .true.}]
   the polyTEOS10-bsq equation of seawater \citep{roquet.madec.ea_OM15} is used.
+\item [{\np[=.true.]{ln_teos10}{ln\_teos10}}] 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
+  more computationally efficient expressions for their derived quantities which make them more adapted for
+  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{ioc.iapso_bk10}.
+  but it is optimized for a Boussinesq fluid and
+  the polynomial expressions have simpler and more computationally efficient expressions for
+  their derived quantities which make them more adapted for 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{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$).
+  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{ioc.iapso_bk10}.
+  It is set to $C_p$ = 3991.86795711963 $J.Kg^{-1}.\deg{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 particular, the initial state defined by the user have to be given as
+  \textit{Conservative} Temperature and \textit{Absolute} Salinity.
   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{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
+  accurately fit EOS80 (Roquet, personal comm.).
+\item [{\np[=.true.]{ln_eos80}{ln\_eos80}}] the polyEOS80-bsq equation of seawater is used.
+  It takes the same polynomial form as the polyTEOS10,
+  but the coefficients have been optimized to accurately fit EOS80 (Roquet, personal comm.).
   The state variables used in both the EOS80 and the ocean model are:
   the Practical Salinity ((unit: psu, notation: $S_p$)) and
   Potential Temperature (unit: $^{\circ}C$, notation: $\theta$).
+  the Practical Salinity (unit: $psu$, notation: $S_p$) and
+  Potential Temperature (unit: $\deg{C}$, notation: $\theta$).
   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{fofonoff.millard_bk83}.
+  With EOS, the specific heat capacity of sea water, $C_p$, is a function of
+  temperature, salinity and 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{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.madec.ea_JPO15}).
+\item [{\np[=.true.]{ln_seos}{ln\_seos}}] 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.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.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.
+  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}
+    \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       \\
+    &                              \big. &- \nu \;                           T_a                  &S_a \big] \\
+    \end{alignedat}
+    \\
+    % \label{eq:TRA_S-EOS}
+    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
+                                  \big. - \nu \;                           T_a                  S_a \big] \\
     \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.
+  Setting to zero the two thermobaric coefficients $(\mu_1,\mu_2)$ remove thermobaric effect from S-EOS.
+  setting to zero the three cabbeling coefficients $(\lambda_1,\lambda_2,\nu)$ remove cabbeling effect from
+  S-EOS.
+  Setting to zero the two thermobaric coefficients $(\mu_1,\mu_2)$
+  remove thermobaric effect from S-EOS.
+  Setting to zero the three cabbeling coefficients $(\lambda_1,\lambda_2,\nu)$
+  remove   cabbeling effect from S-EOS.
   Keeping non-zero value to $a_0$ and $b_0$ provide a linear EOS function of T and S.
 \end{description}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\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}
+\begin{table}
+  \centering
+  \begin{tabular}{|l|l|l|l|}
+    \hline
+    coeff.      & computer name                & S-EOS            & description                     \\
+    \hline
+    $a_0      $ & \np{rn_a0}{rn\_a0}           & $1.6550~10^{-1}$ & linear thermal expansion coeff. \\
+    \hline
+    $b_0      $ & \np{rn_b0}{rn\_b0}           & $7.6554~10^{-1}$ & linear haline  expansion coeff. \\
+    \hline
+    $\lambda_1$ & \np{rn_lambda1}{rn\_lambda1} & $5.9520~10^{-2}$ & cabbeling coeff. in $T^2$       \\
+    \hline
+    $\lambda_2$ & \np{rn_lambda2}{rn\_lambda2} & $5.4914~10^{-4}$ & cabbeling coeff. in $S^2$       \\
+    \hline
+    $\nu      $ & \np{rn_nu}{rn\_nu}           & $2.4341~10^{-3}$ & cabbeling coeff. in $T \, S$    \\
+    \hline
+    $\mu_1    $ & \np{rn_mu1}{rn\_mu1}         & $1.4970~10^{-4}$ & thermobaric coeff. in T         \\
+    \hline
+    $\mu_2    $ & \np{rn_mu2}{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]
+{Brunt-V\"{a}is\"{a}l\"{a} frequency}
+%% =================================================================================================
+\subsection[Brunt-V\"{a}is\"{a}l\"{a} frequency]{Brunt-V\"{a}is\"{a}l\"{a} frequency}
 \label{subsec:TRA_bn2}
 An accurate computation of the ocean stability (i.e. of $N$, the brunt-V\"{a}is\"{a}l\"{a} frequency) is of
 paramount importance as determine the ocean stratification and is used in several ocean parameterisations
+An accurate computation of the ocean stability (i.e. of $N$, the Brunt-V\"{a}is\"{a}l\"{a} frequency) is of paramount importance as determine the ocean stratification and
+is used in several ocean parameterisations
 (namely TKE, GLS, Richardson number dependent vertical diffusion, enhanced vertical diffusion,
 non-penetrative convection, tidal mixing  parameterisation, iso-neutral diffusion).
 …
 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)
 \]
 where $(T,S) = (\Theta,S_A)$ for TEOS10, $(\theta,S_p)$ for TEOS-80, or $(T,S)$ for S-EOS, and,
 $\alpha$ and $\beta$ are the thermal and haline expansion coefficients.
+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}.
+% -------------------------------------------------------------------------------------------------------------
+%        Freezing Point of Seawater
+% -------------------------------------------------------------------------------------------------------------
+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}.
+%% =================================================================================================
 \subsection{Freezing point of seawater}
 \label{subsec:TRA_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{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
+  \label{eq:TRA_eos_fzp}
+  \begin{gathered}
+    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{and~} d = -7.53~10^{-3}
+    \end{gathered}
+\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.
+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}.
+%% =================================================================================================
 %\subsection{Potential Energy anomalies}
 %\label{subsec:TRA_bn2}
 %    =====>>>>> TO BE written
+%
+% ================================================================
+% Horizontal Derivative in zps-coordinate
+% ================================================================
+\section[Horizontal derivative in \textit{zps}-coordinate (\textit{zpshde.F90})]
+{Horizontal derivative in \textit{zps}-coordinate (\protect\mdl{zpshde})}
+%% =================================================================================================
+\section[Horizontal derivative in \textit{zps}-coordinate (\textit{zpshde.F90})]{Horizontal derivative in \textit{zps}-coordinate (\protect\mdl{zpshde})}
 \label{sec:TRA_zpshde}
 …
 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[=.true.]{ln_zps}{ln\_zps}) at bottom and top
+(\np[=.true.]{ln_isfcav}{ln\_isfcav}),
 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
 for the bottom.
+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[=.true.]{ln_isfcav}{ln\_isfcav}) 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}).
+For example, for temperature in the $i$-direction the needed interpolated temperature, $\widetilde T$, is:
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!p]
+  \begin{center}
+    \includegraphics[width=\textwidth]{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}
+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}
+  \centering
+  \includegraphics[width=0.33\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[=.true.]{ln_zps}{ln\_zps}) 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}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \[
   \widetilde T = \lt\{
     \begin{alignedat}{2}
       &T^{\, i + 1} &-\frac{ \lt( e_{3w}^{i + 1} -e_{3w}^i \rt) }{ e_{3w}^{i + 1} } \; \delta_k T^{i + 1}
       & \quad \text{if $e_{3w}^{i + 1} \geq e_{3w}^i$} \\ \\
+      & \quad \text{if $e_{3w}^{i + 1} \geq e_{3w}^i$} \\
       &T^{\, i}     &+\frac{ \lt( e_{3w}^{i + 1} -e_{3w}^i \rt )}{e_{3w}^i       } \; \delta_k T^{i + 1}
       & \quad \text{if $e_{3w}^{i + 1} <    e_{3w}^i$}
 …
   \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       &=
     \begin{cases}
+                                \widetilde T - T^i          & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\
+                                \\
+                                T^{\, i + 1} - \widetilde T & \text{if~} e_{3w}^{i + 1} <    e_{3w}^i
+    \end{cases}
+    \\
+      \widetilde T - T^i          & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\
+      T^{\, i + 1} - \widetilde T & \text{if~} e_{3w}^{i + 1} <    e_{3w}^i
+    \end{cases} \\
     \overline T^{\, i + 1/2} &=
     \begin{cases}
+                                (\widetilde T - T^{\, i}   ) / 2 & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\
+                                \\
+                                (T^{\, i + 1} - \widetilde T) / 2 & \text{if~} e_{3w}^{i + 1} <   e_{3w}^i
+      (\widetilde T - T^{\, i}    ) / 2 & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\
+      (T^{\, i + 1} - \widetilde T) / 2 & \text{if~} e_{3w}^{i + 1} <   e_{3w}^i
     \end{cases}
   \end{split}
 …
 The computation of horizontal derivative of tracers as well as of density is performed once for all at
 each time step in \mdl{zpshde} module and stored in shared arrays to be used when needed.
+It has to be emphasized that the procedure used to compute the interpolated density, $\widetilde \rho$,
+is not the same as that used for $T$ and $S$.
+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
+It has to be emphasized that the procedure used to compute the interpolated density,
+$\widetilde \rho$, is not the same as that used for $T$ and $S$.
+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}):
 \[
   % \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)
 \]
 This is a much better approximation as the variation of $\rho$ with depth (and thus pressure)
+is highly non-linear with a true equation of state and thus is badly approximated with a linear interpolation.
+This approximation is used to compute both the horizontal pressure gradient (\autoref{sec:DYN_hpg}) and
+the slopes of neutral surfaces (\autoref{sec:LDF_slp}).
+Note that in almost all the advection schemes presented in this Chapter,
+is highly non-linear with a true equation of state and thus is badly approximated with
+a linear interpolation.
+This approximation is used to compute both the horizontal pressure gradient (\autoref{sec:DYN_hpg})
+and the slopes of neutral surfaces (\autoref{sec:LDF_slp}).
+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.
 The main motivation is to preserve the domain averaged mean variance of the advected field when
 using the $2^{nd}$ order centred scheme.
+Sensitivity of the advection schemes to the way horizontal averages are performed in the vicinity of
+partial cells should be further investigated in the near future.
+%%%
+Sensitivity of the advection schemes to the way horizontal averages are performed in
+the vicinity of partial cells should be further investigated in the near future.
 \gmcomment{gm :   this last remark has to be done}
+%%%
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_ZDF.tex

-                      r11435
+                      r11799
 \documentclass[../main/NEMO_manual]{subfiles}
+%% Custom aliases
+\newcommand{\cf}{\ensuremath{C\kern-0.14em f}}
 \begin{document}
+% ================================================================
+% Chapter  Vertical Ocean Physics (ZDF)
+% ================================================================
 \chapter{Vertical Ocean Physics (ZDF)}
 \label{chap:ZDF}
+\thispagestyle{plain}
 \chaptertoc
+\paragraph{Changes record} ~\\
+{\footnotesize
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release & Author(s) & Modifications \\
+    \hline
+    {\em   4.0} & {\em ...} & {\em ...} \\
+    {\em   3.6} & {\em ...} & {\em ...} \\
+    {\em   3.4} & {\em ...} & {\em ...} \\
+    {\em <=3.4} & {\em ...} & {\em ...}
+  \end{tabularx}
+}
+\clearpage
 %gm% Add here a small introduction to ZDF and naming of the different physics (similar to what have been written for TRA and DYN.
+\newpage
+% ================================================================
+% Vertical Mixing
+% ================================================================
+%% =================================================================================================
 \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\ \np{ln\_trabbc} defined,
+unless a geothermal flux forcing is prescribed as a bottom boundary condition (\ie\ \np{ln_trabbc}{ln\_trabbc} defined,
 see \autoref{subsec:TRA_bbc}), and specified through a bottom friction parameterisation for momentum
 (see \autoref{sec:ZDF_drg}).
 …
 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}).
+%--------------------------------------------namzdf--------------------------------------------------------
+\nlst{namzdf}
+%--------------------------------------------------------------------------------------------------------------
+% -------------------------------------------------------------------------------------------------------------
+%        Constant
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Constant (\forcode{ln_zdfcst = .true.})]
+{Constant (\protect\np{ln\_zdfcst}\forcode{ = .true.})}
+%(namelist parameter \np[=.true.]{ln_zdfexp}{ln\_zdfexp}) or a backward time stepping scheme
+%(\np[=.false.]{ln_zdfexp}{ln\_zdfexp}) depending on the magnitude of the mixing coefficients,
+%and thus of the formulation used (see \autoref{chap:TD}).
+\begin{listing}
+  \nlst{namzdf}
+  \caption{\forcode{&namzdf}}
+  \label{lst:namzdf}
+\end{listing}
+%% =================================================================================================
+\subsection[Constant (\forcode{ln_zdfcst})]{Constant (\protect\np{ln_zdfcst}{ln\_zdfcst})}
 \label{subsec:ZDF_cst}
 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
+Options are defined through the \nam{zdf}{zdf} namelist variables.
+When \np{ln_zdfcst}{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.
 …
 \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}{rn\_avm0} and \np{rn_avt0}{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
 $\sim10^{-9}~m^2.s^{-1}$ for salinity.
+% -------------------------------------------------------------------------------------------------------------
+%        Richardson Number Dependent
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Richardson number dependent (\forcode{ln_zdfric = .true.})]
+{Richardson number dependent (\protect\np{ln\_zdfric}\forcode{ = .true.})}
+%% =================================================================================================
+\subsection[Richardson number dependent (\forcode{ln_zdfric})]{Richardson number dependent (\protect\np{ln_zdfric}{ln\_zdfric})}
 \label{subsec:ZDF_ric}
+%--------------------------------------------namric---------------------------------------------------------
+\nlst{namzdf_ric}
+%--------------------------------------------------------------------------------------------------------------
+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.
+\begin{listing}
+  \nlst{namzdf_ric}
+  \caption{\forcode{&namzdf_ric}}
+  \label{lst:namzdf_ric}
+\end{listing}
+When \np[=.true.]{ln_zdfric}{ln\_zdfric}, a local Richardson number dependent formulation for the vertical momentum and
+tracer eddy coefficients is set through the \nam{zdf_ric}{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.
 …
 Following \citet{pacanowski.philander_JPO81}, the following formulation has been implemented:
 \[
   % \label{eq:zdfric}
+  % \label{eq:ZDF_ric}
   \left\{
     \begin{aligned}
 …
 (see \autoref{subsec:ZDF_cst}), and $A_{ric}^{vT} = 10^{-4}~m^2.s^{-1}$ is the maximum value that
 can be reached by the coefficient when $Ri\leq 0$, $a=5$ and $n=2$.
 The last three values can be modified by setting the \np{rn\_avmri}, \np{rn\_alp} and
 \np{nn\_ric} namelist parameters, respectively.
+The last three values can be modified by setting the \np{rn_avmri}{rn\_avmri}, \np{rn_alp}{rn\_alp} and
+\np{nn_ric}{nn\_ric} namelist parameters, respectively.
 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[=.true.]{ln_mldw}{ln\_mldw} in the namelist.
 In this case, the local depth of turbulent wind-mixing or "Ekman depth" $h_{e}(x,y,t)$ is evaluated and
 …
 \]
 is computed from the wind stress vector $|\tau|$ and the reference density $ \rho_o$.
 The final $h_{e}$ is further constrained by the adjustable bounds \np{rn\_mldmin} and \np{rn\_mldmax}.
+The final $h_{e}$ is further constrained by the adjustable bounds \np{rn_mldmin}{rn\_mldmin} and \np{rn_mldmax}{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{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.})}
+the empirical values \np{rn_wtmix}{rn\_wtmix} and \np{rn_wvmix}{rn\_wvmix} \citep{lermusiaux_JMS01}.
+%% =================================================================================================
+\subsection[TKE turbulent closure scheme (\forcode{ln_zdftke})]{TKE turbulent closure scheme (\protect\np{ln_zdftke}{ln\_zdftke})}
 \label{subsec:ZDF_tke}
+%--------------------------------------------namzdf_tke--------------------------------------------------
+\nlst{namzdf_tke}
+%--------------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{namzdf_tke}
+  \caption{\forcode{&namzdf_tke}}
+  \label{lst:namzdf_tke}
+\end{listing}
 The vertical eddy viscosity and diffusivity coefficients are computed from a TKE turbulent closure model based on
 …
 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}\; }    \\
 …
 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{gaspar.gregoris.ea_JGR90}.
 They are set through namelist parameters \np{nn\_ediff} and \np{nn\_ediss}.
+They are set through namelist parameters \np{nn_ediff}{nn\_ediff} and \np{nn_ediss}{nn\_ediss}.
 $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*}
 The choice of $P_{rt}$ is controlled by the \np{nn\_pdl} namelist variable.
+The choice of $P_{rt}$ is controlled by the \np{nn_pdl}{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.
+$\bar{e}_o = e_{bb} |\tau| / \rho_o$, with $e_{bb}$ the \np{rn_ebb}{rn\_ebb} namelist parameter.
 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 time integration of the $\bar{e}$ equation may formally lead to negative values because
 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).
+To overcome this problem, a cut-off in the minimum value of $\bar{e}$ is used (\np{rn_emin}{rn\_emin} namelist parameter).
 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
 …
 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} (\nam{zdf} namelist, see \autoref{subsec:ZDF_cst}).
+They must be specified at least larger than the molecular values, and are set through \np{rn_avm0}{rn\_avm0} and
+\np{rn_avt0}{rn\_avt0} (\nam{zdf}{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{gaspar.gregoris.ea_JGR90} has been simplified.
 Four formulations are proposed, the choice of which is controlled by the \np{nn\_mxl} namelist parameter.
+Four formulations are proposed, the choice of which is controlled by the \np{nn_mxl}{nn\_mxl} namelist parameter.
 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}).
+(\np[=0]{nn_mxl}{nn\_mxl}) or by the local vertical scale factor (\np[=1]{nn_mxl}{nn\_mxl}).
 \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{madec.delecluse.ea_NPM98} introduces the \np{nn\_mxl}\forcode{ = 2, 3} cases,
+To overcome these drawbacks, \citet{madec.delecluse.ea_NPM98} introduces the \np[=2, 3]{nn_mxl}{nn\_mxl} 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{gaspar.gregoris.ea_JGR90} formulation while being much less
 …
 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
 (and note that here we use numerical indexing):
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=\textwidth]{Fig_mixing_length}
+    \caption{
+      \protect\label{fig:mixing_length}
+      Illustration of the mixing length computation.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=0.66\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,
+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[=2]{nn_mxl}{nn\_mxl} 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[=3]{nn_mxl}{nn\_mxl} case,
 the dissipation and mixing turbulent length scales are give as in \citet{gaspar.gregoris.ea_JGR90}:
 \[
   % \label{eq:tke_mxl_gaspar}
+  % \label{eq:ZDF_tke_mxl_gaspar}
   \begin{aligned}
     & l_k          = \sqrt{\  l_{up} \ \ l_{dwn}\ }   \\
 …
 \]
 At the ocean surface, a non zero length scale is set through the  \np{rn\_mxl0} namelist parameter.
+At the ocean surface, a non zero length scale is set through the  \np{rn_mxl0}{rn\_mxl0} namelist parameter.
 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}{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}}$ ).
+%% =================================================================================================
 \subsubsection{Surface wave breaking parameterization}
-%-----------------------------------------------------------------------%
 Following \citet{mellor.blumberg_JPO04}, the TKE turbulence closure model has been modified to
 …
 $\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}{rn\_ebb} namelist parameter, setting \np[=67.83]{rn_ebb}{rn\_ebb} corresponds
 to $\alpha_{CB} = 100$.
 Further setting  \np{ln\_mxl0}\forcode{ =.true.},  applies \autoref{eq:ZDF_Lsbc} as the surface boundary condition on the length scale,
+Further setting  \np[=.true.]{ln_mxl0}{ln\_mxl0},  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 the
+Note that a minimal threshold of \np{rn_emin0}{rn\_emin0}$=10^{-4}~m^2.s^{-2}$ (namelist parameters) is applied on the
 surface $\bar{e}$ value.
+%% =================================================================================================
 \subsubsection{Langmuir cells}
-%--------------------------------------%
 Langmuir circulations (LC) can be described as ordered large-scale vertical motions in
 …
 The parameterization, tuned against large-eddy simulation, includes the whole effect of LC in
 an extra source term 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 \nam{zdf\_tke} namelist.
+The presence of $P_{LC}$ in \autoref{eq:ZDF_tke_e}, the TKE equation, is controlled by setting \np{ln_lc}{ln\_lc} to
+\forcode{.true.} in the \nam{zdf_tke}{zdf\_tke} namelist.
 By making an analogy with the characteristic convective velocity scale (\eg, \citet{dalessio.abdella.ea_JPO98}),
 …
 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,
+The value of $c_{LC}$ is set through the \np{rn_lc}{rn\_lc} namelist parameter,
 having in mind that it should stay between 0.15 and 0.54 \citep{axell_JGR02}.
 …
 \]
+%% =================================================================================================
 \subsubsection{Mixing just below the mixed layer}
-%--------------------------------------------------------------%
 Vertical mixing parameterizations commonly used in ocean general circulation models tend to
 …
 (\ie\ near-inertial oscillations and ocean swells and waves).
 When using this parameterization (\ie\ when \np{nn\_etau}\forcode{ = 1}),
+When using this parameterization (\ie\ when \np[=1]{nn_etau}{nn\_etau}),
 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,
 …
 the penetration, and $f_i$ is the ice concentration
 (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 value of $f_r$, usually a few percents, is specified through \np{rn_efr}{rn\_efr} namelist parameter.
+The vertical mixing length scale, $h_\tau$, can be set as a 10~m uniform value (\np[=0]{nn_etau}{nn\_etau}) 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 exist, \np{nn\_etau}\forcode{ = 2, 3}.
+(\np[=1]{nn_etau}{nn\_etau}).
+Note that two other option exist, \np[=2, 3]{nn_etau}{nn\_etau}.
 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 penetrates the ocean.
 …
 % 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.
+In presence of Sea Ice, the value of this mixing can be modulated by the \np{rn_eice}{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\%.
 …
 % (\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.})}
+%% =================================================================================================
+\subsection[GLS: Generic Length Scale (\forcode{ln_zdfgls})]{GLS: Generic Length Scale (\protect\np{ln_zdfgls}{ln\_zdfgls})}
 \label{subsec:ZDF_gls}
+%--------------------------------------------namzdf_gls---------------------------------------------------------
+\nlst{namzdf_gls}
+%--------------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{namzdf_gls}
+  \caption{\forcode{&namzdf_gls}}
+  \label{lst:namzdf_gls}
+\end{listing}
 The Generic Length Scale (GLS) scheme is a turbulent closure scheme based on two prognostic equations:
 …
 $\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:GLS} allows to recover a number of
+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:zdfgls_e}
+  \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
 …
 \[
   % \label{eq:zdfgls_psi}
+  % \label{eq:ZDF_gls_psi}
   \begin{split}
     \frac{\partial \psi}{\partial t} =& \frac{\psi}{\bar{e}} \left\{
 …
 \[
   % \label{eq:zdfgls_kz}
+  % \label{eq:ZDF_gls_kz}
   \begin{split}
     K_m    &= C_{\mu} \ \sqrt {\bar{e}} \ l         \\
 …
 \[
   % \label{eq:zdfgls_eps}
+  % \label{eq:ZDF_gls_eps}
   {\epsilon} = C_{0\mu} \,\frac{\bar {e}^{3/2}}{l} \;
 \]
 …
 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:GLS}).
+They are made available through the \np{nn\_clo} namelist parameter.
+%--------------------------------------------------TABLE--------------------------------------------------
+Four different turbulent models are pre-defined (\autoref{tab:ZDF_GLS}).
+They are made available through the \np{nn_clo}{nn\_clo} namelist parameter.
 \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_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{
+      \protect\label{tab:GLS}
+      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}.
+    }
+  \end{center}
+  \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}{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[=.true.]{ln_zdfgls}{ln\_zdfgls} and controlled by
+    the \protect\np{nn_clos}{nn\_clos} namelist variable in \protect\nam{zdf_gls}{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
 …
 $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.).
+(\np[=0, 3]{nn_stab_func}{nn\_stab\_func}, 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.
+Neumann condition through \np{nn_bc_surf}{nn\_bc\_surf} and \np{nn_bc_bot}{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}.
+\np[ > 0.]{rn_crban}{rn\_crban} \citep{craig.banner_JPO94, mellor.blumberg_JPO04}.
+The \np{rn_crban}{rn\_crban} namelist parameter is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and
+\np{rn_charn}{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
 …
 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 clipping is only activated if \np[=.true.]{ln_length_lim}{ln\_length\_lim},
+and the $c_{lim}$ is set to the \np{rn_clim_galp}{rn\_clim\_galp} value.
 The time and space discretization of the GLS equations follows the same energetic consideration as for
 …
  in \citet{reffray.guillaume.ea_GMD15} for the \NEMO\ model.
 % -------------------------------------------------------------------------------------------------------------
 %        OSM OSMOSIS BL Scheme
+%        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.})}
+\subsection[OSM: OSMOSIS boundary layer scheme (\forcode{ln_zdfosm = .true.})]
+{OSM: OSMOSIS boundary layer scheme (\protect\np{ln_zdfosm}{ln\_zdfosm})}
 \label{subsec:ZDF_osm}
+%--------------------------------------------namzdf_osm---------------------------------------------------------
+\nlst{namzdf_osm}
+\begin{listing}
+  \nlst{namzdf_osm}
+  \caption{\forcode{&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}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\paragraph{Namelist choices}
+Most of the namelist options refer to how to specify the Stokes
+surface drift and penetration depth. There are three options:
+\begin{description}
+  \item \protect\np[=0]{nn_osm_wave}{nn\_osm\_wave} Default value in \texttt{namelist\_ref}. In this case the Stokes drift is
+      assumed to be parallel to the surface wind stress, with
+      magnitude consistent with a constant turbulent Langmuir number
+    $\mathrm{La}_t=$ \protect\np{rn_m_la} {rn\_m\_la} i.e.\
+    $u_{s0}=\tau/(\mathrm{La}_t^2\rho_0)$.  Default value of
+    \protect\np{rn_m_la}{rn\_m\_la} is 0.3. The Stokes penetration
+      depth $\delta = $ \protect\np{rn_osm_dstokes}{rn\_osm\_dstokes}; this has default value
+      of 5~m.
+  \item \protect\np[=1]{nn_osm_wave}{nn\_osm\_wave} In this case the Stokes drift is
+      assumed to be parallel to the surface wind stress, with
+      magnitude as in the classical Pierson-Moskowitz wind-sea
+      spectrum.  Significant wave height and
+      wave-mean period taken from this spectrum are used to calculate the Stokes penetration
+      depth, following the approach set out in  \citet{breivik.janssen.ea_JPO14}.
+    \item \protect\np[=2]{nn_osm_wave}{nn\_osm\_wave} In this case the Stokes drift is
+      taken from  ECMWF wave model output, though only the component parallel
+      to the wind stress is retained. Significant wave height and
+      wave-mean period from ECMWF wave model output are used to calculate the Stokes penetration
+      depth, again following \citet{breivik.janssen.ea_JPO14}.
+    \end{description}
+    Others refer to the treatment of diffusion and viscosity beneath
+    the surface boundary layer:
+\begin{description}
+   \item \protect\np{ln_kpprimix} {ln\_kpprimix}  Default is \np{.true.}. Switches on KPP-style Ri \#-dependent
+     mixing below the surface boundary layer. If this is set
+     \texttt{.true.}  the following variable settings are honoured:
+    \item \protect\np{rn_riinfty}{rn\_riinfty} Critical value of local Ri \# below which
+      shear instability increases vertical mixing from background value.
+    \item \protect\np{rn_difri} {rn\_difri} Maximum value of Ri \#-dependent mixing at $\mathrm{Ri}=0$.
+    \item \protect\np{ln_convmix}{ln\_convmix} If \texttt{.true.} then, where water column is unstable, specify
+       diffusivity equal to \protect\np{rn_dif_conv}{rn\_dif\_conv} (default value is 1 m~s$^{-2}$).
+ \end{description}
+ Diagnostic output is controlled by:
+  \begin{description}
+    \item \protect\np{ln_dia_osm}{ln\_dia\_osm} Default is \np{.false.}; allows XIOS output of OSMOSIS internal fields.
+  \end{description}
+Obsolete namelist parameters include:
+\begin{description}
+   \item \protect\np{ln_use_osm_la}\np{ln\_use\_osm\_la} With \protect\np[=0]{nn_osm_wave}{nn\_osm\_wave},
+      \protect\np{rn_osm_dstokes} {rn\_osm\_dstokes} is always used to specify the Stokes
+      penetration depth.
+   \item \protect\np{nn_ave} {nn\_ave} Choice of averaging method for KPP-style Ri \#
+      mixing. Not taken account of.
+   \item \protect\np{rn_osm_hbl0} {rn\_osm\_hbl0} Depth of initial boundary layer is now set
+     by a density criterion similar to that used in calculating \emph{hmlp} (output as \texttt{mldr10\_1}) in \mdl{zdfmxl}.
+\end{description}
+\subsubsection{Summary}
+Much of the time the turbulent motions in the ocean surface boundary
+layer (OSBL) are not given by
+classical shear turbulence. Instead they are in a regime known as
+`Langmuir turbulence',  dominated by an
+interaction between the currents and the Stokes drift of the surface waves \citep[e.g.][]{mcwilliams.ea_JFM97}.
+This regime is characterised by strong vertical turbulent motion, and appears when the surface Stokes drift $u_{s0}$ is much greater than the friction velocity $u_{\ast}$. More specifically Langmuir turbulence is thought to be crucial where the turbulent Langmuir number $\mathrm{La}_{t}=(u_{\ast}/u_{s0}) > 0.4$.
+The OSMOSIS model is fundamentally based on results of Large Eddy
+Simulations (LES) of Langmuir turbulence and aims to fully describe
+this Langmuir regime. The description in this section is of necessity incomplete and further details are available in Grant. A (2019); in prep.
+The OSMOSIS turbulent closure scheme is a similarity-scale scheme in
+the same spirit as the K-profile
+parameterization (KPP) scheme of \citet{large.ea_RG97}.
+A specified shape of diffusivity, scaled by the (OSBL) depth
+$h_{\mathrm{BL}}$ and a turbulent velocity scale, is imposed throughout the
+boundary layer
+$-h_{\mathrm{BL}}<z<\eta$. The turbulent closure model
+also includes fluxes of tracers and momentum that are``non-local'' (independent of the local property gradient).
+Rather than the OSBL
+depth being diagnosed in terms of a bulk Richardson number criterion,
+as in KPP, it is set by a prognostic equation that is informed by
+energy budget considerations reminiscent of the classical mixed layer
+models of \citet{kraus.turner_tellus67}.
+The model also includes an explicit parametrization of the structure
+of the pycnocline (the stratified region at the bottom of the OSBL).
+Presently, mixing below the OSBL is handled by the Richardson
+number-dependent mixing scheme used in \citet{large.ea_RG97}.
+Convective parameterizations such as described in \ref{sec:ZDF_conv}
+below should not be used with the OSMOSIS-OBL model: instabilities
+within the OSBL are part of the model, while instabilities below the
+ML are handled by the Ri \# dependent scheme.
+\subsubsection{Depth and velocity scales}
+The model supposes a boundary layer of thickness $h_{\mathrm{bl}}$ enclosing a well-mixed layer of thickness $h_{\mathrm{ml}}$ and a relatively thin pycnocline at the base of thickness $\Delta h$; Fig.~\ref{fig: OSBL_structure} shows typical (a) buoyancy structure and (b) turbulent buoyancy flux profile for the unstable boundary layer (losing buoyancy at the surface; e.g.\ cooling).
 \begin{figure}[!t]
   \begin{center}
     \includegraphics[width=\textwidth]{Fig_ZDF_TKE_time_scheme}
+    \includegraphics[width=0.7\textwidth]{Fig_ZDF_OSM_structure_of_OSBL}
     \caption{
       \protect\label{fig:TKE_time_scheme}
       Illustration of the subgrid kinetic energy integration in GLS and TKE schemes and its links to the momentum and tracer time integration.
+      \protect\label{fig: OSBL_structure}
+     The structure of the entraining  boundary layer. (a) Mean buoyancy profile. (b) Profile of the buoyancy flux.
+    }
   \end{center}
 \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+The pycnocline in the OSMOSIS scheme is assumed to have a finite thickness, and may include a number of model levels. This means that the OSMOSIS scheme must parametrize both the thickness of the pycnocline, and the turbulent fluxes within the pycnocline.
+Consideration of the power input by wind acting on the Stokes drift suggests that the Langmuir turbulence has velocity scale:
+\begin{equation}\label{eq:w_La}
+w_{*L}= \left(u_*^2 u_{s\,0}\right)^{1/3};
+\end{equation}
+but at times the Stokes drift may be weak due to e.g.\ ice cover, short fetch, misalignment with the surface stress, etc.\ so  a composite velocity scale is assumed for the stable (warming) boundary layer:
+\begin{equation}\label{eq:composite-nu}
+  \nu_{\ast}= \left\{ u_*^3 \left[1-\exp(-.5 \mathrm{La}_t^2)\right]+w_{*L}^3\right\}^{1/3}.
+\end{equation}
+For the unstable boundary layer this is merged with the standard convective velocity scale $w_{*C}=\left(\overline{w^\prime b^\prime}_0 \,h_\mathrm{ml}\right)^{1/3}$, where $\overline{w^\prime b^\prime}_0$ is the upwards surface buoyancy flux, to give:
+\begin{equation}\label{eq:vel-scale-unstable}
+\omega_* = \left(\nu_*^3 + 0.5 w_{*C}^3\right)^{1/3}.
+\end{equation}
+\subsubsection{The flux gradient model}
+The flux-gradient relationships used in the OSMOSIS scheme take the form:
+%
+\begin{equation}\label{eq:flux-grad-gen}
+\overline{w^\prime\chi^\prime}=-K\frac{\partial\overline{\chi}}{\partial z} + N_{\chi,s} +N_{\chi,b} +N_{\chi,t},
+\end{equation}
+%
+where $\chi$ is a general variable and $N_{\chi,s}, N_{\chi,b} \mathrm{and} N_{\chi,t}$  are the non-gradient terms, and represent the effects of the different terms in the turbulent flux-budget on the transport of $\chi$. $N_{\chi,s}$ represents the effects that the Stokes shear has on the transport of $\chi$, $N_{\chi,b}$  the effect of buoyancy, and $N_{\chi,t}$ the effect of the turbulent transport.  The same general form for the flux-gradient relationship is used to parametrize the transports of momentum, heat and salinity.
+In terms of the non-dimensionalized depth variables
+%
+\begin{equation}\label{eq:sigma}
+\sigma_{\mathrm{ml}}= -z/h_{\mathrm{ml}}; \;\sigma_{\mathrm{bl}}= -z/h_{\mathrm{bl}},
+\end{equation}
+%
+in unstable conditions the eddy diffusivity ($K_d$) and eddy viscosity ($K_\nu$) profiles are parametrized as:
+%
+\begin{align}\label{eq:diff-unstable}
+K_d=&0.8\, \omega_*\, h_{\mathrm{ml}} \, \sigma_{\mathrm{ml}} \left(1-\beta_d \sigma_{\mathrm{ml}}\right)^{3/2}
+\\\label{eq:visc-unstable}
+K_\nu =& 0.3\, \omega_* \,h_{\mathrm{ml}}\, \sigma_{\mathrm{ml}} \left(1-\beta_\nu \sigma_{\mathrm{ml}}\right)\left(1-\tfrac{1}{2}\sigma_{\mathrm{ml}}^2\right)
+\end{align}
+%
+where $\beta_d$ and $\beta_\nu$ are parameters that are determined by matching Eqs \ref{eq:diff-unstable} and \ref{eq:visc-unstable} to the eddy diffusivity and viscosity at the base of the well-mixed layer, given by
+%
+\begin{equation}\label{eq:diff-wml-base}
+K_{d,\mathrm{ml}}=K_{\nu,\mathrm{ml}}=\,0.16\,\omega_* \Delta h.
+\end{equation}
+%
+For stable conditions the eddy diffusivity/viscosity profiles are given by:
+%
+\begin{align}\label{diff-stable}
+K_d= & 0.75\,\, \nu_*\, h_{\mathrm{ml}}\,\,  \exp\left[-2.8 \left(h_{\mathrm{bl}}/L_L\right)^2\right]\sigma_{\mathrm{ml}} \left(1-\sigma_{\mathrm{ml}}\right)^{3/2} \\\label{eq:visc-stable}
+K_\nu = & 0.375\,\,  \nu_*\, h_{\mathrm{ml}} \,\, \exp\left[-2.8 \left(h_{\mathrm{bl}}/L_L\right)^2\right] \sigma_{\mathrm{ml}} \left(1-\sigma_{\mathrm{ml}}\right)\left(1-\tfrac{1}{2}\sigma_{\mathrm{ml}}^2\right).
+\end{align}
+%
+The shape of the eddy viscosity and diffusivity profiles is the same as the shape in the unstable OSBL. The eddy diffusivity/viscosity depends on the stability parameter $h_{\mathrm{bl}}/{L_L}$ where $ L_L$ is analogous to the Obukhov length, but for Langmuir turbulence:
+\begin{equation}\label{eq:L_L}
+  L_L=-w_{*L}^3/\left<\overline{w^\prime b^\prime}\right>_L,
+\end{equation}
+with the mean turbulent buoyancy flux averaged over the boundary layer given in terms of its surface value $\overline{w^\prime b^\prime}_0$ and (downwards) )solar irradiance $I(z)$ by
+\begin{equation} \label{eq:stable-av-buoy-flux}
+\left<\overline{w^\prime b^\prime}\right>_L = \tfrac{1}{2} {\overline{w^\prime b^\prime}}_0-g\alpha_E\left[\tfrac{1}{2}(I(0)+I(-h))-\left<I\right>\right].
+\end{equation}
+%
+In unstable conditions the eddy diffusivity and viscosity depend on stability through the velocity scale $\omega_*$, which depends on the two velocity scales $\nu_*$ and $w_{*C}$.
+Details of the non-gradient terms in \eqref{eq:flux-grad-gen} and of the fluxes within the pycnocline $-h_{\mathrm{bl}}<z<h_{\mathrm{ml}}$ can be found in Grant (2019).
+\subsubsection{Evolution of the boundary layer depth}
+The prognostic equation for the depth of the neutral/unstable boundary layer is given by \citep{grant+etal18},
+\begin{equation} \label{eq:dhdt-unstable}
+%\frac{\partial h_\mathrm{bl}}{\partial t} + \mathbf{U}_b\cdot\nabla h_\mathrm{bl}= W_b - \frac{{\overline{w^\prime b^\prime}}_\mathrm{ent}}{\Delta B_\mathrm{bl}}
+\frac{\partial h_\mathrm{bl}}{\partial t} = W_b - \frac{{\overline{w^\prime b^\prime}}_\mathrm{ent}}{\Delta B_\mathrm{bl}}
+\end{equation}
+where $h_\mathrm{bl}$ is the horizontally-varying depth of the OSBL,
+$\mathbf{U}_b$ and $W_b$ are the mean horizontal and vertical
+velocities at the base of the OSBL, ${\overline{w^\prime
+    b^\prime}}_\mathrm{ent}$ is the buoyancy flux due to entrainment
+and $\Delta B_\mathrm{bl}$ is the difference between the buoyancy
+averaged over the depth of the OSBL (i.e.\ including the ML and
+pycnocline) and the buoyancy just below the base of the OSBL. This
+equation for the case when the pycnocline has a finite thickness,
+based on the potential energy budget of the OSBL, is the leading term
+\citep{grant+etal18} of a generalization of that used in mixed-layer
+models e.g.\ \citet{kraus.turner_tellus67}, in which the thickness of the pycnocline is taken to be zero.
+The entrainment flux for the combination of convective and Langmuir turbulence is given by
+\begin{equation} \label{eq:entrain-flux}
+  {\overline{w^\prime b^\prime}}_\mathrm{ent} = -\alpha_{\mathrm{B}} {\overline{w^\prime b^\prime}}_0 - \alpha_{\mathrm{S}} \frac{u_*^3}{h_{\mathrm{ml}}}
+  + G\left(\delta/h_{\mathrm{ml}} \right)\left[\alpha_{\mathrm{S}}e^{-1.5\, \mathrm{La}_t}-\alpha_{\mathrm{L}} \frac{w_{\mathrm{*L}}^3}{h_{\mathrm{ml}}}\right]
+\end{equation}
+where the factor $G\equiv 1 - \mathrm{e}^ {-25\delta/h_{\mathrm{bl}}}(1-4\delta/h_{\mathrm{bl}})$ models the lesser efficiency of Langmuir mixing when the boundary-layer depth is much greater than the Stokes depth, and $\alpha_{\mathrm{B}}$, $\alpha_{S}$  and $\alpha_{\mathrm{L}}$ depend on the ratio of the appropriate eddy turnover time to the inertial timescale $f^{-1}$. Results from the LES suggest $\alpha_{\mathrm{B}}=0.18 F(fh_{\mathrm{bl}}/w_{*C})$, $\alpha_{S}=0.15 F(fh_{\mathrm{bl}}/u_*$  and $\alpha_{\mathrm{L}}=0.035 F(fh_{\mathrm{bl}}/u_{*L})$, where $F(x)\equiv\tanh(x^{-1})^{0.69}$.
+For the stable boundary layer, the equation for the depth of the OSBL is:
+\begin{equation}\label{eq:dhdt-stable}
+\max\left(\Delta B_{bl},\frac{w_{*L}^2}{h_\mathrm{bl}}\right)\frac{\partial h_\mathrm{bl}}{\partial t} = \left(0.06 + 0.52\,\frac{ h_\mathrm{bl}}{L_L}\right) \frac{w_{*L}^3}{h_\mathrm{bl}} +\left<\overline{w^\prime b^\prime}\right>_L.
+\end{equation}
+Equation. \ref{eq:dhdt-unstable} always leads to the depth of the entraining OSBL increasing (ignoring the effect of the mean vertical motion), but the change in the thickness of the stable OSBL given by Eq. \ref{eq:dhdt-stable} can be positive or negative, depending on the magnitudes of $\left<\overline{w^\prime b^\prime}\right>_L$ and $h_\mathrm{bl}/L_L$. The rate at which the depth of the OSBL can decrease is limited by choosing an effective buoyancy $w_{*L}^2/h_\mathrm{bl}$, in place of $\Delta B_{bl}$ which will be $\approx 0$ for the collapsing OSBL.
+%% =================================================================================================
+\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]
+  \centering
+  \includegraphics[width=0.66\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}) and  \autoref{eq:zdfgls_e}) should balance the loss of kinetic energy associated with the vertical momentum diffusion
 (first line in \autoref{eq:PE_zdf}).
+\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:TKE_time_scheme} shows how
+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 the equation for $\bar{e}$.
 …
 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} and \autoref{eq:zdfgls_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 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{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
+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} and  \autoref{eq:zdfgls_e}.
+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 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}.
+%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.
+% ================================================================
+% Convection
+% ================================================================
+%% =================================================================================================
 \section{Convection}
 \label{sec:ZDF_conv}
 …
 or/and the use of a turbulent closure scheme.
+% -------------------------------------------------------------------------------------------------------------
+%       Non-Penetrative Convective Adjustment
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Non-penetrative convective adjustment (\forcode{ln_tranpc = .true.})]
+{Non-penetrative convective adjustment (\protect\np{ln\_tranpc}\forcode{ = .true.})}
+%% =================================================================================================
+\subsection[Non-penetrative convective adjustment (\forcode{ln_tranpc})]{Non-penetrative convective adjustment (\protect\np{ln_tranpc}{ln\_tranpc})}
 \label{subsec:ZDF_npc}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!htb]
+  \begin{center}
+    \includegraphics[width=\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=0.66\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 \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
+Options are defined through the \nam{zdf}{zdf} namelist variables.
+The non-penetrative convective adjustment is used when \np[=.true.]{ln_zdfnpc}{ln\_zdfnpc}.
+It is applied at each \np{nn_npc}{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.delecluse.ea_JPO91}.
 The associated algorithm is an iterative process used in the following way (\autoref{fig:npc}):
+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$.
 …
 having to recompute the expansion coefficients at each mixing iteration.
+% -------------------------------------------------------------------------------------------------------------
+%       Enhanced Vertical Diffusion
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Enhanced vertical diffusion (\forcode{ln_zdfevd = .true.})]
+{Enhanced vertical diffusion (\protect\np{ln\_zdfevd}\forcode{ = .true.})}
+%% =================================================================================================
+\subsection[Enhanced vertical diffusion (\forcode{ln_zdfevd})]{Enhanced vertical diffusion (\protect\np{ln_zdfevd}{ln\_zdfevd})}
 \label{subsec:ZDF_evd}
 Options are defined through the  \nam{zdf} namelist variables.
 The enhanced vertical diffusion parameterisation is used when \np{ln\_zdfevd}\forcode{ = .true.}.
+Options are defined through the  \nam{zdf}{zdf} namelist variables.
+The enhanced vertical diffusion parameterisation is used when \np[=.true.]{ln_zdfevd}{ln\_zdfevd}.
 In this case, the vertical eddy mixing coefficients are assigned very large values
 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},
+This is done either on tracers only (\np[=0]{nn_evdm}{nn\_evdm}) or
+on both momentum and tracers (\np[=1]{nn_evdm}{nn\_evdm}).
+In practice, where $N^2\leq 10^{-12}$, $A_T^{vT}$ and $A_T^{vS}$, and if \np[=1]{nn_evdm}{nn\_evdm},
 the four neighbouring $A_u^{vm} \;\mbox{and}\;A_v^{vm}$ values also, are set equal to
 the namelist parameter \np{rn\_avevd}.
+the namelist parameter \np{rn_avevd}{rn\_avevd}.
 A typical value for $rn\_avevd$ is between 1 and $100~m^2.s^{-1}$.
 This parameterisation of convective processes is less time consuming than
 …
 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_phd10} (see \autoref{sec:STP_mLF}).
+% -------------------------------------------------------------------------------------------------------------
+%       Turbulent Closure Scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Handling convection with turbulent closure schemes (\forcode{ln_zdf\{tke,gls,osm\} = .true.})}
+a leapfrog environment \citep{leclair_phd10} (see \autoref{sec:TD_mLF}).
+%% =================================================================================================
+\subsection[Handling convection with turbulent closure schemes (\forcode{ln_zdf_}\{\forcode{tke,gls,osm}\})]{Handling convection with turbulent closure schemes (\forcode{ln_zdf{tke,gls,osm}})}
 \label{subsec:ZDF_tcs}
 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,
+\autoref{subsec:ZDF_osm} (\ie\ \np{ln_zdftke}{ln\_zdftke} or \np{ln_zdfgls}{ln\_zdfgls} or \np{ln_zdfosm}{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.
+\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}$).
 …
 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 (\np{ln\_zdftke} or \np{ln\_zdfgls} = \forcode{.true.}) all together.
+\ie\ setting the \np{ln_zdfnpc}{ln\_zdfnpc} namelist parameter to true and
+defining the turbulent closure (\np{ln_zdftke}{ln\_zdftke} or \np{ln_zdfgls}{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.
+therefore \np[=.false.]{ln_zdfevd}{ln\_zdfevd} 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 (\forcode{ln_zdfddm = .true.})]
+{Double diffusion mixing (\protect\np{ln\_zdfddm}\forcode{ = .true.})}
+%% =================================================================================================
+\section[Double diffusion mixing (\forcode{ln_zdfddm})]{Double diffusion mixing (\protect\np{ln_zdfddm}{ln\_zdfddm})}
 \label{subsec:ZDF_ddm}
-%-------------------------------------------namzdf_ddm-------------------------------------------------
+%
 %\nlst{namzdf_ddm}
-%--------------------------------------------------------------------------------------------------------------
 This parameterisation has been introduced in \mdl{zdfddm} module and is controlled by the namelist parameter
 \np{ln\_zdfddm} in \nam{zdf}.
+\np{ln_zdfddm}{ln\_zdfddm} in \nam{zdf}{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.
 …
 temperature and salinity.
 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}
+  \\         \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=\textwidth]{Fig_zdfddm}
+    \caption{
+      \protect\label{fig:zdfddm}
+      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.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=0.66\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
+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}$.
 …
 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.
 This avoids duplication in the computation of $\alpha$ and $\beta$ (which is usually quite expensive).
+% ================================================================
+% Bottom Friction
+% ================================================================
+ \section[Bottom and top friction (\textit{zdfdrg.F90})]
+ {Bottom and top friction (\protect\mdl{zdfdrg})}
+ \label{sec:ZDF_drg}
+%--------------------------------------------nambfr--------------------------------------------------------
+%
+\nlst{namdrg}
+\nlst{namdrg_top}
+\nlst{namdrg_bot}
+%--------------------------------------------------------------------------------------------------------------
+Options to define the top and bottom friction are defined through the \nam{drg} namelist variables.
+%% =================================================================================================
+\section[Bottom and top friction (\textit{zdfdrg.F90})]{Bottom and top friction (\protect\mdl{zdfdrg})}
+\label{sec:ZDF_drg}
+\begin{listing}
+  \nlst{namdrg}
+  \caption{\forcode{&namdrg}}
+  \label{lst:namdrg}
+\end{listing}
+\begin{listing}
+  \nlst{namdrg_top}
+  \caption{\forcode{&namdrg_top}}
+  \label{lst:namdrg_top}
+\end{listing}
+\begin{listing}
+  \nlst{namdrg_bot}
+  \caption{\forcode{&namdrg_bot}}
+  \label{lst:namdrg_bot}
+\end{listing}
+Options to define the top and bottom friction are defined through the \nam{drg}{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.
 …
 the description below considers mostly the bottom friction case, if not stated otherwise.
 Both the surface momentum flux (wind stress) and the bottom momentum flux (bottom friction) enter the equations as
 a condition on the vertical diffusive flux.
 For the bottom boundary layer, one has:
  \[
    % \label{eq:zdfbfr_flux}
+   % \label{eq:ZDF_bfr_flux}
    A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U}
  \]
 …
 To illustrate this, consider the equation for $u$ at $k$, the last ocean level:
 \begin{equation}
   \label{eq:zdfdrg_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}
 …
  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
 …
 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 top/bottom friction (\forcode{ln_lin = .true.})]
+ {Linear top/bottom friction (\protect\np{ln\_lin}\forcode{ = .true.)}}
+ \label{subsec:ZDF_drg_linear}
+%% =================================================================================================
+\subsection[Linear top/bottom friction (\forcode{ln_lin})]{Linear top/bottom friction (\protect\np{ln_lin}{ln\_lin})}
+\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:zdfbfr_linear}
+  % \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
 \]
 …
 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\_Uc0} (namelist parameter).
  For the linear friction case the drag coefficient used in the general expression \autoref{eq:zdfbfr_bdef} is:
 \[
   % \label{eq:zdfbfr_linbfr_b}
+It can be changed by specifying \np{rn_Uc0}{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.
+When \np[=.true.]{ln_lin}{ln\_lin}, the value of $r$ used is \np{rn_Uc0}{rn\_Uc0}*\np{rn_Cd0}{rn\_Cd0}.
+Setting \np[=.true.]{ln_OFF}{ln\_OFF} (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.
+(\np[=.true.]{ln_boost}{ln\_boost}) 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\_boost} * \np{rn\_Cd0}.
+% -------------------------------------------------------------------------------------------------------------
+%       Non-Linear Bottom Friction
+% -------------------------------------------------------------------------------------------------------------
+ \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}
+$mask\_value$ * \np{rn_boost}{rn\_boost} * \np{rn_Cd0}{rn\_Cd0}.
+%% =================================================================================================
+\subsection[Non-linear top/bottom friction (\forcode{ln_non_lin})]{Non-linear top/bottom friction (\protect\np{ln_non_lin}{ln\_non\_lin})}
+\label{subsec:ZDF_drg_nonlinear}
 The non-linear bottom friction parameterisation assumes that the top/bottom friction is quadratic:
 \[
   % \label{eq:zdfdrg_nonlinear}
+  % \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
 …
 $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\_Cd0} and \np{rn\_ke0} namelist parameters).
+The CME choices have been set as default values (\np{rn_Cd0}{rn\_Cd0} and \np{rn_ke0}{rn\_ke0} namelist parameters).
 As for the linear case, the friction is imposed in the code by adding the trend due to
 …
 For the non-linear friction case the term computed in \mdl{zdfdrg} is:
 \[
   % \label{eq:zdfdrg_nonlinbfr}
+  % \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.}).
+$C_D$= \np{rn_Cd0}{rn\_Cd0}, and $e_b$ =\np{rn_bfeb2}{rn\_bfeb2}.
+Note that for applications which consider tides explicitly, a low or even zero value of \np{rn_bfeb2}{rn\_bfeb2} is recommended. A local enhancement of $C_D$ is again possible via an externally defined 2D mask array
+(\np[=.true.]{ln_boost}{ln\_boost}).
 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 top/bottom friction (\forcode{ln_loglayer = .true.})]
+ {Log-layer top/bottom friction (\protect\np{ln\_loglayer}\forcode{ = .true.})}
+ \label{subsec:ZDF_drg_loglayer}
+$mask\_value$ * \np{rn_boost}{rn\_boost} * \np{rn_Cd0}{rn\_Cd0}.
+%% =================================================================================================
+\subsection[Log-layer top/bottom friction (\forcode{ln_loglayer})]{Log-layer top/bottom friction (\protect\np{ln_loglayer}{ln\_loglayer})}
+\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):
+If  \np[=.true.]{ln_loglayer}{ln\_loglayer}, $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.
+\noindent where $\kappa$ is the von-Karman constant and \np{rn_z0}{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
+the base \np{rn_Cd0}{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}{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:
+under ice-shelf cavities are activated (\np[=.true.]{ln_isfcav}{ln\_isfcav}).
+%In this case, the relevant namelist parameters are \np{rn_tfrz0}{rn\_tfrz0}, \np{rn_tfri2}{rn\_tfri2} and \np{rn_tfri2_max}{rn\_tfri2\_max}.
+%% =================================================================================================
+\subsection[Explicit top/bottom friction (\forcode{ln_drgimp=.false.})]{Explicit top/bottom friction (\protect\np[=.false.]{ln_drgimp}{ln\_drgimp})}
+\label{subsec:ZDF_drg_stability}
+Setting \np[=.false.]{ln_drgimp}{ln\_drgimp} 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):
 …
 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:zdfdrg_flux2} is:
+For the purposes of stability analysis, an approximation to \autoref{eq:ZDF_drg_flux2} is:
 \begin{equation}
   \label{eq:Eqn_drgstab}
+  \label{eq:ZDF_Eqn_drgstab}
   \begin{split}
     \Delta u &= -\frac{{{\cal F}_h}^u}{e_{3u}}\;2 \rdt    \\
 …
   |\Delta u| < \;|u|
 \]
 \noindent which, using \autoref{eq:Eqn_drgstab}, gives:
+\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}\\
 …
 The number of potential breaches of the explicit stability criterion are still reported for information purposes.
+% -------------------------------------------------------------------------------------------------------------
+%       Implicit Bottom Friction
+% -------------------------------------------------------------------------------------------------------------
+ \subsection[Implicit top/bottom friction (\forcode{ln_drgimp = .true.})]
+ {Implicit top/bottom friction (\protect\np{ln\_drgimp}\forcode{ = .true.})}
+ \label{subsec:ZDF_drg_imp}
+%% =================================================================================================
+\subsection[Implicit top/bottom friction (\forcode{ln_drgimp=.true.})]{Implicit top/bottom friction (\protect\np[=.true.]{ln_drgimp}{ln\_drgimp})}
+\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\_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 option can be invoked by setting \np{ln_drgimp}{ln\_drgimp} to \forcode{.true.} in the \nam{drg}{drg} namelist.
+%This option requires \np{ln_zdfexp}{ln\_zdfexp} to be \forcode{.false.} in the \nam{zdf}{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:dynzdf_drg_top}
+  % \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:dynzdf_drg_bot}
+  % \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}
 …
 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.
+%% =================================================================================================
+\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[=.false.]{ln_drgimp}{ln\_drgimp} 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[=.true.]{ln_drgimp}{ln\_drgimp},  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:
 …
 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.})}
+%% =================================================================================================
+\section[Internal wave-driven mixing (\forcode{ln_zdfiwm})]{Internal wave-driven mixing (\protect\np{ln_zdfiwm}{ln\_zdfiwm})}
 \label{subsec:ZDF_tmx_new}
+%--------------------------------------------namzdf_iwm------------------------------------------
+%
+\nlst{namzdf_iwm}
+%--------------------------------------------------------------------------------------------------------------
+\begin{listing}
+  \nlst{namzdf_iwm}
+  \caption{\forcode{&namzdf_iwm}}
+  \label{lst:namzdf_iwm}
+\end{listing}
 The parameterization of mixing induced by breaking internal waves is a generalization of
 …
 and the resulting diffusivity is obtained as
 \[
   % \label{eq:Kwave}
+  % \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 \forcode{.false.}, the mixing efficiency is taken as constant and
+If the \np{ln_mevar}{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
 …
 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.
+as a function of $Re_b$ by setting the \np{ln_tsdiff}{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}.
 …
   h_{wkb} = H \, \frac{ \int_{-H}^{z} N \, dz' } { \int_{-H}^{\eta} N \, dz'  } \; ,
 \]
 The $n_p$ parameter (given by \np{nn\_zpyc} in \nam{zdf\_iwm} namelist)
+The $n_p$ parameter (given by \np{nn_zpyc}{nn\_zpyc} in \nam{zdf_iwm}{zdf\_iwm} namelist)
 controls the stratification-dependence of the pycnocline-intensified dissipation.
 It can take values of $1$ (recommended) or $2$.
 …
 $h_{bot}$ is a function of the energy flux $E_{bot}$, the characteristic horizontal scale of
 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.})}
+%% =================================================================================================
+\section[Surface wave-induced mixing (\forcode{ln_zdfswm})]{Surface wave-induced mixing (\protect\np{ln_zdfswm}{ln\_zdfswm})}
 \label{subsec:ZDF_swm}
 …
 \begin{equation}
   \label{eq:Bv}
+  \label{eq:ZDF_Bv}
   B_{v} = \alpha {A} {U}_{st} {exp(3kz)}
 \end{equation}
 …
 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.}
+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.})}
+%% =================================================================================================
+\section[Adaptive-implicit vertical advection (\forcode{ln_zad_Aimp})]{Adaptive-implicit vertical advection(\protect\np{ln_zad_Aimp}{ln\_zad\_Aimp})}
 \label{subsec:ZDF_aimp}
 …
 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:zad_Aimp_CFLcrit}. Treating the vertical advection implicitly can avoid these
+\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
 …
 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
+\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]
+  \begin{center}
+    % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}}
+    \begin{tabular}{r|ccc}
+      \hline
+      spatial discretization &   2nd order centered   & 3rd order upwind & 4th order compact  \\
+      advective CFL criterion     & 0.904 &   0.472  &   0.522    \\
+      \hline
+    \end{tabular}
+    \caption{
+      \protect\label{tab:zad_Aimp_CFLcrit}
+      The advective CFL criteria for a range of spatial discretizations for the Leap-Frog with Robert Asselin filter time-stepping
+      ($\nu=0.1$) as given in \citep{lemarie.debreu.ea_OM15}.
+    }
+  \end{center}
+  \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}
 …
 \begin{equation}
   \label{eq:Eqn_zad_Aimp_Courant}
+  \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 ]    \\
 …
 \begin{align}
   \label{eq:Eqn_zad_Aimp_partition}
+  \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 \\
 C\kern-0.14em f &=
+\cf &=
      \begin{cases}
 .0                                                        &\text{if $Cu \leq Cu_{min}$} \\
 …
 \begin{figure}[!t]
+  \begin{center}
+    \includegraphics[width=\textwidth]{Fig_ZDF_zad_Aimp_coeff}
+    \caption{
+      \protect\label{fig:zad_Aimp_coeff}
+      The value of the partitioning coefficient ($C\kern-0.14em f$) 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.})
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=0.66\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}
 …
 \begin{align}
   \label{eq:Eqn_zad_Aimp_partition2}
     w_{i_{ijk}} &= C\kern-0.14em f_{ijk} w_{n_{ijk}}     \nonumber \\
     w_{n_{ijk}} &= (1-C\kern-0.14em f_{ijk}) w_{n_{ijk}}
+  \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:Eqn_zad_Aimp_partition} can be considered as:
+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 ($C\kern-0.14em f$) varies as shown in \autoref{fig:zad_Aimp_coeff}. Note with these values
+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:zad_Aimp_CFLcrit}  for a 3rd order scheme.
+\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
 …
 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
+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]
+  \begin{center}
+    \includegraphics[width=\textwidth]{Fig_ZDF_zad_Aimp_overflow_frames}
+    \caption{
+      \protect\label{fig:zad_Aimp_overflow_frames}
+      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.}).
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=0.66\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
 …
 \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:zad_Aimp_overflow_frames}. The mass of
+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
+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
 …
 The results with \forcode{ln_zad_Aimp=.true.} and a variety of model timesteps
 are shown in \autoref{fig:zad_Aimp_overflow_all_rdt} (together with the equivalent
+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
+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
 ($C\kern-0.14em f$) is also available as \texttt{wi\_cff}. For a quick oversight of
+(\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
 …
 \autoref{sec:MISC_opt} for activation details).
 \autoref{fig:zad_Aimp_maxCf} shows examples of the maximum partitioning coefficient for
+\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
 …
 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:zad_Aimp_maxCf_loc} where the i- and k- locations of the
+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.
 …
 \begin{figure}[!t]
   \begin{center}
     \includegraphics[width=\textwidth]{Fig_ZDF_zad_Aimp_overflow_all_rdt}
     \caption{
       \protect\label{fig:zad_Aimp_overflow_all_rdt}
       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$.
+    }
   \end{center}
+  \centering
+  \includegraphics[width=0.66\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]
+  \begin{center}
+    \includegraphics[width=\textwidth]{Fig_ZDF_zad_Aimp_maxCf}
+    \caption{
+      \protect\label{fig:zad_Aimp_maxCf}
+      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.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=0.66\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]
+  \begin{center}
+    \includegraphics[width=\textwidth]{Fig_ZDF_zad_Aimp_maxCf_loc}
+    \caption{
+      \protect\label{fig:zad_Aimp_maxCf_loc}
+      The maximum partitioning coefficient for the  \forcode{nn_rdt=10.0s} case overlaid with  information on the gridcell i- and k-
+      locations of the maximum value.
+    }
+  \end{center}
+  \centering
+  \includegraphics[width=0.66\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}
+% ================================================================
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_conservation.tex

-                      r11435
+                      r11799
 \begin{document}
-% ================================================================
-% Invariant of the Equations
-% ================================================================
 \chapter{Invariants of the Primitive Equations}
+\label{chap:Invariant}
+\label{chap:CONS}
+\thispagestyle{plain}
 \chaptertoc
+\paragraph{Changes record} ~\\
+{\footnotesize
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release & Author(s) & Modifications \\
+    \hline
+    {\em   4.0} & {\em ...} & {\em ...} \\
+    {\em   3.6} & {\em ...} & {\em ...} \\
+    {\em   3.4} & {\em ...} & {\em ...} \\
+    {\em <=3.4} & {\em ...} & {\em ...}
+  \end{tabularx}
+}
+\clearpage
 The continuous equations of motion have many analytic properties.
 …
 \citep{Marti1992?, Levy1996?, Levy1998?}.
+% -------------------------------------------------------------------------------------------------------------
+%       Conservation Properties on Ocean Dynamics
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \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
         \;{\mathrm {\mathbf k}}\times {\textbf {U}}_h } \right)\;dv} =0
 …
 \[
   % \label{eq:vor_enstrophy}
+  % \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.
 …
 \[
   % \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
 \]
 …
 otherwise there is no guarantee that the surface pressure force work vanishes.
+% -------------------------------------------------------------------------------------------------------------
+%       Conservation Properties on Ocean Thermodynamics
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \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.
+% -------------------------------------------------------------------------------------------------------------
+%       Conservation Properties on Momentum Physics
+% -------------------------------------------------------------------------------------------------------------
+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}
+  % \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
 …
 \[
   % \label{eq:dynldf_div}
+  % \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 \;{\mathrm {\mathbf k}}} \right)}
 …
 \[
   % \label{eq:dynldf_curl}
+  % \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)}
 …
 \[
   % \label{eq:dynldf_curl2}
+  % \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
 …
 \[
   % \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 \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} \leqslant 0
 \]
 (II.4.6a) and (II.4.6b) means that the horizontal diffusion of momentum conserve both the potential vorticity and
 …
 \[
   % \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}
+  % \label{eq:CONS_dynzdf_vor}
   \begin{aligned}
     & \int_D {\frac{1}{e_3 }{\mathrm {\mathbf k}}\cdot \nabla \times \left( {\frac{1}{e_3
 …
 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
 …
 \ie\ the vertical momentum physics conserve momentum, potential vorticity, and horizontal divergence.
+% -------------------------------------------------------------------------------------------------------------
+%       Conservation Properties on Tracer Physics
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \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 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 \\
 …
 It has not been implemented.
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

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

-                      r11435
+                      r11799
 \begin{document}
+% ================================================================
+% Chapter --- Miscellaneous Topics
+% ================================================================
 \chapter{Miscellaneous Topics}
 \label{chap:MISC}
+\thispagestyle{plain}
 \chaptertoc
+\newpage
+% ================================================================
+% Representation of Unresolved Straits
+% ================================================================
+\paragraph{Changes record} ~\\
+{\footnotesize
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release & Author(s) & Modifications \\
+    \hline
+    {\em   4.0} & {\em ...} & {\em ...} \\
+    {\em   3.6} & {\em ...} & {\em ...} \\
+    {\em   3.4} & {\em ...} & {\em ...} \\
+    {\em <=3.4} & {\em ...} & {\em ...}
+  \end{tabularx}
+}
+\clearpage
+%% =================================================================================================
 \section{Representation of unresolved straits}
 \label{sec:MISC_strait}
 …
 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.
 …
 lateral friction.
+% -------------------------------------------------------------------------------------------------------------
+%       Hand made geometry changes
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsection{Hand made geometry changes}
 \label{subsec:MISC_strait_hand}
 …
 \begin{itemize}
 \item Add \texttt{e1e2u} and \texttt{e1e2v} arrays to the \np{cn\_domcfg} file. These 2D
+\item Add \texttt{e1e2u} and \texttt{e1e2v} arrays to the \np{cn_domcfg}{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.
+\np{cn_domcfg}{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
 …
 will suppress the calculation of the areas.
 \item Change values of \texttt{e2u} or \texttt{e1v} (either in the \np{cn\_domcfg} file or
+\item Change values of \texttt{e2u} or \texttt{e1v} (either in the \np{cn_domcfg}{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
 …
 \end{itemize}
 The second method is to increase the viscous boundary layer thickness by a local increase
 …
 \texttt{fmask} for any other configuration.
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!tbp]
+  \begin{center}
+    \includegraphics[width=\textwidth]{Fig_Gibraltar}
+    \includegraphics[width=\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=0.66\textwidth]{Fig_Gibraltar}
+  \includegraphics[width=0.66\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=\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=0.66\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}{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 (\textit{closea.F90})]
+{Closed seas (\protect\mdl{closea})}
+%% =================================================================================================
+\section[Closed seas (\textit{closea.F90})]{Closed seas (\protect\mdl{closea})}
 \label{sec:MISC_closea}
 …
 \begin{enumerate}
 \item{{\bfseries 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{{\bfseries 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{{\bfseries 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{{\bfseries 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{{\bfseries 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
 …
 them to the domain configuration file in the utils/tools/DOMAINcfg directory.
+% ================================================================
+% Sub-Domain Functionality
+% ================================================================
+%% =================================================================================================
 \section{Sub-domain functionality}
 \label{sec:MISC_zoom}
+%% =================================================================================================
 \subsection{Simple subsetting of input files via NetCDF attributes}
 …
 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
+a global file attribute (named: \np{open_ocean_jstart}{open\_ocean\_jstart}) to determine the starting j-row
 for input.  The use of this option is best explained with an example:
 \medskip
 …
 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
+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}{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
 …
 \begin{itemize}
 \item  Add the new attribute to any input files requiring a j-row offset, i.e:
+\item Add the new attribute to any input files requiring a j-row offset, i.e:
 \begin{cmds}
 ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_domcfg.nc
 \end{cmds}
 \item Add the logical switch \np{ln\_use\_jattr} to \nam{cfg} in the configuration
 namelist (if it is not already there) and set \np{.true.}
+\item Add the logical switch \np{ln_use_jattr}{ln\_use\_jattr} to \nam{cfg}{cfg} in the configuration
+namelist (if it is not already there) and set \forcode{.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
+j-size minus \np{open_ocean_jstart}{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
+be created for when \np{ln_use_jattr}{ln\_use\_jattr} is active. The \texttt{ncap2} tool provides a
 convenient way of achieving this:
 …
 \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}.
+the appropriate call to \np{iom_get}{iom\_get}.
 \begin{forlines}
 …
 conditions. Experimenting with this remains an exercise for the user.
+% ================================================================
+% Accuracy and Reproducibility
+% ================================================================
+\section[Accuracy and reproducibility (\textit{lib\_fortran.F90})]
+{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 (\texttt{\textbf{key\_nosignedzero}})]
 {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 :   \\
 …
 some computers/compilers.
+%% =================================================================================================
 \subsection{MPP reproducibility}
 \label{subsec:MISC_glosum}
 …
 Note also that this implementation may be sensitive to the optimization level.
+%% =================================================================================================
 \subsection{MPP scalability}
 \label{subsec:MISC_mppsca}
 …
 be set at all the locations actually required by each individual for the fold operation.
 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 (\nam{mpp}).
+is recommended for large values of \np{jpni}{jpni}.
+The new method is activated by setting \np{ln_nnogather}{ln\_nnogather} to be true (\nam{mpp}{mpp}).
 The reproducibility of results using the two methods should be confirmed for each new,
 non-reference configuration.
+% ================================================================
+% Model optimisation, Control Print and Benchmark
+% ================================================================
+%% =================================================================================================
 \section{Model optimisation, control print and benchmark}
 \label{sec:MISC_opt}
+%--------------------------------------------namctl-------------------------------------------------------
+\nlst{namctl}
+%--------------------------------------------------------------------------------------------------------------
+Options are defined through the  \nam{ctl} namelist variables.
+\begin{listing}
+  \nlst{namctl}
+  \caption{\forcode{&namctl}}
+  \label{lst:namctl}
+\end{listing}
+Options are defined through the  \nam{ctl}{ctl} namelist variables.
+%% =================================================================================================
 \subsection{Vector optimisation}
 …
 % Add also one word on NEC specific optimisation (Novercheck option for example)
+%% =================================================================================================
 \subsection{Control print}
 The \np{ln\_ctl} switch was originally used as a debugging option in two modes:
+The \np{ln_ctl}{ln\_ctl} switch was originally used as a debugging option in two modes:
 \begin{enumerate}
 \item{\np{ln\_ctl}: compute and print the trends averaged over the interior domain in all TRA, DYN, LDF and
+\item {\np{ln_ctl}{ln\_ctl}: compute and print the trends averaged over the interior domain in all TRA, DYN, LDF and
 ZDF modules.
 This option is very helpful when diagnosing the origin of an undesired change in model results. }
 \item{also \np{ln\_ctl} but using the nictl and njctl namelist parameters to check the source of differences between
+\item {also \np{ln_ctl}{ln\_ctl} but using the nictl and njctl namelist parameters to check the source of differences between
 mono and multi processor runs.}
 \end{enumerate}
 However, in recent versions it has also been used to force all processors to assume the
 reporting role. Thus when \np{ln\_ctl} is true all processors produce their own versions
+reporting role. Thus when \np{ln_ctl}{ln\_ctl} is true all processors produce their own versions
 of files such as: ocean.output, layout.dat, etc.  All such files, beyond the the normal
 reporting processor (narea == 1), are named with a \_XXXX extension to their name, where
 …
 such as run.stat (and its netCDF counterpart: run.stat.nc) and tracer.stat contain global
 information and are only ever produced by the reporting master (narea == 1). For version
 .0 a start has been made to return \np{ln\_ctl} to its original function by introducing
+.0 a start has been made to return \np{ln_ctl}{ln\_ctl} to its original function by introducing
 a new control structure which allows finer control over which files are produced. This
 feature is still evolving but it does already allow the user to: select individually the
 …
 increment also applies to the time.step file which is otherwise updated every timestep.
+% ================================================================
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_model_basics.tex

-                      r11435
+                      r11799
 \documentclass[../main/NEMO_manual]{subfiles}
 \begin{document}
-% ================================================================
-% Chapter 1  Model Basics
-% ================================================================
 \chapter{Model Basics}
+\label{chap:PE}
+\label{chap:MB}
+\thispagestyle{plain}
 \chaptertoc
+\newpage
+% ================================================================
+% Primitive Equations
+% ================================================================
+\paragraph{Changes record} ~\\
+{\footnotesize
+  \begin{tabular}{l||l|l}
+    Release          & Author(s)                                   & Modifications       \\
+    \hline
+    {\em        4.0} & {\em Mike Bell                            } & {\em Review       } \\
+    {\em        3.6} & {\em Tim Graham and Gurvan Madec          } & {\em Updates      } \\
+    {\em $\leq$ 3.4} & {\em Gurvan Madec and S\'{e}bastien Masson} & {\em First version} \\
+  \end{tabular}
+}
+\clearpage
+%% =================================================================================================
 \section{Primitive equations}
+\label{sec:PE_PE}
+% -------------------------------------------------------------------------------------------------------------
+%        Vector Invariant Formulation
+% -------------------------------------------------------------------------------------------------------------
+\label{sec:MB_PE}
+%% =================================================================================================
 \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,
 …
 plus the following additional assumptions made from scale considerations:
 \begin{enumerate}
 \item
   \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
+\begin{labeling}{Neglect of additional Coriolis terms}
+\item [\textit{Spherical Earth approximation}] The geopotential surfaces are assumed to
+  be oblate spheroids 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
+\item
+  \textit{turbulent closure hypothesis}: the turbulent fluxes
+\item [\textit{Thin-shell approximation}] The ocean depth is neglected compared to the earth's radius
+\item [\textit{Turbulent closure hypothesis}] The turbulent fluxes
   (which represent the effect of small scale processes on the large-scale)
   are expressed in terms of large-scale features
+\item
+  \textit{Boussinesq hypothesis}: density variations are neglected except in their contribution to
+  the buoyancy force
+\item [\textit{Boussinesq hypothesis}] Density variations are neglected except in
+  their contribution to the buoyancy force
   \begin{equation}
     \label{eq:PE_eos}
+    \label{eq:MB_PE_eos}
     \rho = \rho \ (T,S,p)
   \end{equation}
+\item
+  \textit{Hydrostatic hypothesis}: the vertical momentum equation is reduced to a balance between
+  the vertical pressure gradient and the buoyancy force
+\item [\textit{Hydrostatic hypothesis}] The vertical momentum equation is reduced to
+  a balance between the vertical pressure gradient and the buoyancy force
   (this removes convective processes from the initial Navier-Stokes equations and so
   convective processes must be parameterized instead)
   \begin{equation}
     \label{eq:PE_hydrostatic}
+    \label{eq:MB_PE_hydrostatic}
     \pd[p]{z} = - \rho \ g
   \end{equation}
+\item
+  \textit{Incompressibility hypothesis}: the three dimensional divergence of the velocity vector $\vect U$
+  is assumed to be zero.
+\item [\textit{Incompressibility hypothesis}] The three dimensional divergence of
+  the velocity vector $\vect U$ 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}
+\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-V\"{a}is\"{a}l\"{a} 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{labeling}
 Because the gravitational force is so dominant in the equations of large-scale motions,
 …
 $k$ is the local upward vector and $(i,j)$ are two vectors orthogonal to $k$,
 \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$
+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),
 $T$ the potential temperature, $S$ the salinity, $\rho$ the \textit{in situ} density.
 …
 the following equations:
 \begin{subequations}
   \label{eq:PE}
+  \label{eq:MB_PE}
   \begin{gather}
+    \intertext{$-$ the momentum balance}
+    \label{eq: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}
+    \shortintertext{$-$ the momentum balance}
+    \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}
+    \shortintertext{$-$ the heat and salt conservation equations}
+    \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.
+(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}.
+% -------------------------------------------------------------------------------------------------------------
+% 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
 …
 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: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.
 However, some of these fluxes are so weak that even on climatic time scales of thousands of years
 they can be neglected.
+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.
+However, some of these fluxes are so weak that
+even on climatic time scales of thousands of years they can be neglected.
 In the following, we briefly review the fluxes exchanged at the interfaces between the ocean and
 the other components of the earth system.
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht]
+  \begin{center}
+    \includegraphics[width=\textwidth]{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}
+\begin{figure}
+  \centering
+  \includegraphics[width=0.66\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}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{description}
 \item[Land - ocean interface:]
   the major flux between continental margins and the ocean is a mass exchange of fresh water through river runoff.
+\item [Land - ocean] The major flux between continental margins and the ocean is a mass exchange of
+  fresh water through river runoff.
   Such an exchange modifies the sea surface salinity especially in the vicinity of major river mouths.
+  It can be neglected for short range integrations but has to be taken into account for long term integrations as
+  It can be neglected for short range integrations but
+  has to be taken into account for long term integrations as
   it influences the characteristics of water masses formed (especially at high latitudes).
   It is required in order to close the water cycle of the climate system.
   It is usually specified as a fresh water flux at the air-sea interface in the vicinity of river mouths.
+\item[Solid earth - ocean interface:]
+  heat and salt fluxes through the sea floor are small, except in special areas of little extent.
   They are usually neglected in the model
   \footnote{
+  It is usually specified as a fresh water flux at the air-sea interface in
+  the vicinity of river mouths.
+\item [Solid earth - ocean] Heat and salt fluxes through the sea floor are small,
+  except in special areas of little extent.
+  They are usually neglected in the model \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
     (see \autoref{subsec:TRA_bbc}).
+    (\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,
+  the bottom velocity is parallel to solid boundaries). This kinematic boundary condition
+  can be expressed as:
+  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, 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}
   In addition, the ocean exchanges momentum with the earth through frictional processes.
   Such momentum transfer occurs at small scales in a boundary layer.
+  It must be parameterized in terms of turbulent fluxes using bottom and/or lateral boundary conditions.
+  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.
+\item[Atmosphere - ocean interface:]
+  the kinematic surface condition plus the mass flux of fresh water PE (the precipitation minus evaporation budget)
+  leads to:
+  $\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] 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
   \]
+  The dynamic boundary condition, neglecting the surface tension (which removes capillary waves from the system)
+  leads to the continuity of pressure across the interface $z = \eta$.
+  The dynamic boundary condition, neglecting the surface tension
+  (which removes capillary waves from the system) leads to
+  the continuity of pressure across the interface $z = \eta$.
   The atmosphere and ocean also exchange horizontal momentum (wind stress), and heat.
+\item[Sea ice - ocean interface:]
+  the ocean and sea ice exchange heat, salt, fresh water and momentum.
+\item [Sea ice - ocean] The ocean and sea ice exchange heat, salt, fresh water and momentum.
   The sea surface temperature is constrained to be at the freezing point at the interface.
   Sea ice salinity is very low ($\sim4-6 \, psu$) compared to those of the ocean ($\sim34 \, psu$).
+  The cycle of freezing/melting is associated with fresh water and salt fluxes that cannot be neglected.
+  The cycle of freezing/melting is associated with fresh water and salt fluxes that
+  cannot be neglected.
 \end{description}
+% ================================================================
+% The Horizontal Pressure Gradient
+% ================================================================
+%% =================================================================================================
 \section{Horizontal pressure gradient}
+\label{sec:PE_hor_pg}
+% -------------------------------------------------------------------------------------------------------------
+% Pressure Formulation
+% -------------------------------------------------------------------------------------------------------------
+\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
 \]
 Two strategies can be considered for the surface pressure term:
+$(a)$ introduce of a  new variable $\eta$, the free-surface elevation,
+\begin{enumerate*}[label=(\textit{\alph*})]
+\item introduce of a new variable $\eta$, the free-surface elevation,
 for which a prognostic equation can be established and solved;
 $(b)$ assume that the ocean surface is a rigid lid,
+\item assume that the ocean surface is a rigid lid,
 on which the pressure (or its horizontal gradient) can be diagnosed.
+\end{enumerate*}
 When the former strategy is used, one solution of the free-surface elevation consists of
 the excitation of external gravity waves.
 …
 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.
+It has been available until the release 3.1 of \NEMO,
+and it has been removed in release 3.2 and followings.
 Only the free surface formulation is now described in this document (see the next sub-section).
+% -------------------------------------------------------------------------------------------------------------
+% Free Surface Formulation
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \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}):
+This variable is solution of a prognostic equation which is established by
+forming the vertical average of 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$.
+Allowing the air-sea interface to move introduces the external gravity waves (EGWs) as
+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 \textbf{E}xternal \textbf{G}ravity \textbf{W}aves (EGWs) as
 a class of solution of the primitive equations.
 These waves are barotropic (\ie\ nearly independent of depth) and their phase speed is quite high.
 …
 Two choices can be made regarding the implementation of the free surface in the model,
 depending on the physical processes of interest.
+$\bullet$ If one is interested in EGWs, in particular the tides and their interaction with
+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
+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
+minimize time filtering effects
+(use an explicit time scheme with very small time step, or a split-explicit scheme with reasonably small time step,
+see \autoref{subsec:DYN_spg_exp} or \autoref{subsec:DYN_spg_ts}).
+$\bullet$ If one is not interested in EGW but rather sees them as high frequency noise,
+it is possible to apply an explicit filter to slow down the fastest waves while
+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}.
+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,
+\begin{itemize}
+\item If one is interested in EGWs, in particular the tides and their interaction with
+  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: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
+  minimize time filtering effects
+  (use an explicit time scheme with very small time step,
+  or a split-explicit scheme with reasonably small time step,
+  see \autoref{subsec:DYN_spg_exp} or \autoref{subsec:DYN_spg_ts}).
+\item If one is not interested in EGWs but rather sees them as high frequency noise,
+  it is possible to apply an explicit filter to slow down the fastest waves while
+  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: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.
+\end{itemize}
+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.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}
+(see \autoref{subsec:DYN_spg_ts}).
+% ================================================================
+% Curvilinear z-coordinate System
+% ================================================================
+\section{Curvilinear \textit{z-}coordinate system}
+\label{sec:PE_zco}
+% -------------------------------------------------------------------------------------------------------------
+% Tensorial Formalism
+% -------------------------------------------------------------------------------------------------------------
+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} (see \autoref{subsec:DYN_spg_ts}).
+%% =================================================================================================
+\section{Curvilinear \textit{z}-coordinate system}
+\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
 …
 A solution consists of introducing an appropriate coordinate transformation that
 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.
+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.
 This formalism is suited to any multidimensional curvilinear coordinate system.
+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{eiseman.stone_SR80} in their survey of the conservation laws of fluid dynamics.
+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{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}
+  \begin{aligned}
+    e_1 &= (a + z) \lt[ \lt( \pd[\lambda]{i} \cos \varphi \rt)^2 + \lt( \pd[\varphi]{i} \rt)^2 \rt]^{1/2} \\
+    e_2 &= (a + z) \lt[ \lt( \pd[\lambda]{j} \cos \varphi \rt)^2 + \lt( \pd[\varphi]{j} \rt)^2 \rt]^{1/2} \\
+    e_3 &= \lt( \pd[z]{k} \rt)
+  \end{aligned}
+  \label{eq:MB_scale_factors}
+    e_1 = (a + z) \lt[ \lt( \pd[\lambda]{i} \cos \varphi \rt)^2 + \lt( \pd[\varphi]{i} \rt)^2 \rt]^{1/2} \quad e_2 = (a + z) \lt[ \lt( \pd[\lambda]{j} \cos \varphi \rt)^2 + \lt( \pd[\varphi]{j} \rt)^2 \rt]^{1/2} \quad e_3 = \lt( \pd[z]{k} \rt)
 \end{equation}
+% >>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!tb]
+  \begin{center}
+    \includegraphics[width=\textwidth]{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}
+\begin{figure}
+  \centering
+  \includegraphics[width=0.33\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 then 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}
+  \begin{gather}
+    \label{eq:PE_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}
+    \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}
+      \nabla \times \vect{A} =   \lt[ \frac{1}{e_2} \pd[a_3]{j} - \frac{1}{e_3} \pd[a_2]{k}   \rt] \vect i \\
+                               + \lt[ \frac{1}{e_3} \pd[a_1]{k} - \frac{1}{e_1} \pd[a_3]{i}   \rt] \vect j \\
+                               + \frac{1}{e_1 e_2} \lt[ \pd[(e_2 a_2)]{i} - \pd[(e_1 a_1)]{j} \rt] \vect k
+  \end{multline}
+  \begin{gather}
+    \label{eq:PE_lap}
+    \Delta q = \nabla \cdot (\nabla q) \\
+    \label{eq:PE_lap_vector}
+    \Delta \vect A = \nabla (\nabla \cdot \vect A) - \nabla \times (\nabla \times \vect A)
+  \end{gather}
+  % \label{eq:MB_discrete_operators}
+  \begin{align}
+    \label{eq:MB_grad}
+    \nabla q &=   \frac{1}{e_1} \pd[q]{i} \; \vect i + \frac{1}{e_2} \pd[q]{j} \; \vect j + \frac{1}{e_3} \pd[q]{k} \; \vect k \\
+    \label{eq:MB_div}
+    \nabla \cdot \vect A &=   \frac{1}{e_1 \; e_2} \lt[ \pd[(e_2 \; a_1)]{\partial i} + \pd[(e_1 \; a_2)]{j} \rt] + \frac{1}{e_3} \lt[ \pd[a_3]{k} \rt] \\
+    \label{eq:MB_curl}
+      \nabla \times \vect{A} &=   \lt[ \frac{1}{e_2} \pd[a_3]{j} - \frac{1}{e_3} \pd[a_2]{k}   \rt] \vect i + \lt[ \frac{1}{e_3} \pd[a_1]{k} - \frac{1}{e_1} \pd[a_3]{i}   \rt] \vect j + \frac{1}{e_1 e_2} \lt[ \pd[(e_2 a_2)]{i} - \pd[(e_1 a_1)]{j} \rt] \vect k \\
+    \label{eq:MB_lap}
+    \Delta q &= \nabla \cdot (\nabla q) \\
+    \label{eq:MB_lap_vector}
+    \Delta \vect A &= \nabla (\nabla \cdot \vect A) - \nabla \times (\nabla \times \vect A)
+  \end{align}
 \end{subequations}
+where $q$ is a scalar quantity and $\vect A = (a_1,a_2,a_3)$ a vector in the $(i,j,k)$ coordinates system.
+% -------------------------------------------------------------------------------------------------------------
+% Continuous Model Equations
+% -------------------------------------------------------------------------------------------------------------
+where $q$ is a scalar quantity and
+$\vect A = (a_1,a_2,a_3)$ a vector in the $(i,j,k)$ coordinates system.
+%% =================================================================================================
 \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}.
+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:
+it is necessary to compute the horizontal component of the non-linear and viscous terms of
+the equation using \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 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:
+\begin{alignat*}{2}
+  &NLT &=   &\lt[ (\nabla \times {\vect U}) \times {\vect U} + \frac{1}{2} \nabla \lt( {\vect U}^2 \rt) \rt]_h \\
+  &    &=   &\lt(
+    \begin{array}{*{20}c}
+                \lt[ \frac{1}{e_3} \pd[u]{k} - \frac{1}{e_1} \pd[w]{i} \rt] w - \zeta \; v   \\
+                \zeta \; u - \lt[ \frac{1}{e_2} \pd[w]{j} - \frac{1}{e_3} \pd[v]{k} \rt] \ w
+    \end{array}
+                                                                                             \rt)
+          + \frac{1}{2} \lt(
+    \begin{array}{*{20}c}
+                             \frac{1}{e_1} \pd[(u^2 + v^2 + w^2)]{i} \\
+                             \frac{1}{e_2} \pd[(u^2 + v^2 + w^2)]{j}
+    \end{array}
+                                                                     \rt) \\
+  &    &=   &\lt(
+    \begin{array}{*{20}c}
+                  -\zeta \; v \\
+                   \zeta \; u
+    \end{array}
+                              \rt)
+          + \frac{1}{2} \lt(
+    \begin{array}{*{20}c}
+                             \frac{1}{e_1} \pd[(u^2 + v^2)]{i} \\
+                             \frac{1}{e_2} \pd[(u^2 + v^2)]{j}
+    \end{array}
+                                                               \rt) \\
+  &    &  &+ \frac{1}{e_3} \lt(
+    \begin{array}{*{20}c}
+                                w \; \pd[u]{k} \\
+                                w \; \pd[v]{k}
+    \end{array}
+                                               \rt)
+           - \lt(
+    \begin{array}{*{20}c}
+                  \frac{w}{e_1} \pd[w]{i} - \frac{1}{2 e_1} \pd[w^2]{i} \\
+                  \frac{w}{e_2} \pd[w]{j} - \frac{1}{2 e_2} \pd[w^2]{j}
+    \end{array}
+                                                                        \rt)
+\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:
+$NLT$ the nonlinear term of \autoref{eq:MB_PE_dyn} can be transformed as follows:
+\begin{align*}
+  NLT &= \lt[ (\nabla \times {\vect U}) \times {\vect U} + \frac{1}{2} \nabla \lt( {\vect U}^2 \rt) \rt]_h \\
+      &= \lt(
+        \begin{array}{*{20}c}
+          \lt[ \frac{1}{e_3} \pd[u]{k} - \frac{1}{e_1} \pd[w]{i} \rt] w - \zeta \; v   \\
+          \zeta \; u - \lt[ \frac{1}{e_2} \pd[w]{j} - \frac{1}{e_3} \pd[v]{k} \rt] \ w
+        \end{array}
+  \rt)
+  + \frac{1}{2} \lt(
+  \begin{array}{*{20}c}
+    \frac{1}{e_1} \pd[(u^2 + v^2 + w^2)]{i} \\
+    \frac{1}{e_2} \pd[(u^2 + v^2 + w^2)]{j}
+  \end{array}
+  \rt) \\
+      &= \lt(
+        \begin{array}{*{20}c}
+          -\zeta \; v \\
+          \zeta \; u
+        \end{array}
+  \rt)
+  + \frac{1}{2} \lt(
+  \begin{array}{*{20}c}
+    \frac{1}{e_1} \pd[(u^2 + v^2)]{i} \\
+    \frac{1}{e_2} \pd[(u^2 + v^2)]{j}
+  \end{array}
+  \rt)
+  + \frac{1}{e_3} \lt(
+  \begin{array}{*{20}c}
+    w \; \pd[u]{k} \\
+    w \; \pd[v]{k}
+  \end{array}
+  \rt)
+  - \lt(
+  \begin{array}{*{20}c}
+    \frac{w}{e_1} \pd[w]{i} - \frac{1}{2 e_1} \pd[w^2]{i} \\
+    \frac{w}{e_2} \pd[w]{j} - \frac{1}{2 e_2} \pd[w^2]{j}
+  \end{array}
+  \rt)
+\end{align*}
+The last term of the right hand side is obviously zero,
+and thus the \textbf{N}on\textbf{L}inear \textbf{T}erm ($NLT$) of \autoref{eq:MB_PE_dyn} is written in
+the $(i,j,k)$ coordinate system:
 \begin{equation}
+  \label{eq:PE_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}
+  \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}
 \end{equation}
 …
 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:
+\begin{alignat*}{2}
+For example,
+the first component of \autoref{eq:MB_vector_form} (the $i$-component) is transformed as follows:
+\begin{alignat*}{3}
   &NLT_i &= &- \zeta \; v + \frac{1}{2 \; e_1} \pd[ (u^2 + v^2) ]{i} + \frac{1}{e_3} w \ \pd[u]{k} \\
+  &      &=  &\frac{1}{e_1 \; e_2} \lt( -v \pd[(e_2 \, v)]{i} + v \pd[(e_1 \, u)]{j} \rt)
+            + \frac{1}{e_1 e_2} \lt( e_2 \; u \pd[u]{i} + e_2 \; v \pd[v]{i} \rt) \\
+  &      & &+ \frac{1}{e_3} \lt( w \; \pd[u]{k} \rt) \\
+  &      &=  &\frac{1}{e_1 \; e_2} \lt[ - \lt( v^2 \pd[e_2]{i} + e_2 \, v \pd[v]{i} \rt)
+                                     + \lt( \pd[ \lt( e_1 \, u \, v \rt)]{j} -         e_1 \, u \pd[v]{j} \rt) \rt. \\
+  &      &                       &\lt. + \lt( \pd[ \lt( e_2 \, u \, u \rt)]{i} - u \pd[ \lt( e_2 u \rt)]{i} \rt)
+                                     + e_2 v \pd[v]{i}                                                         \rt] \\
+  &      &= &\frac{1}{e_1 \; e_2} \lt( -v \pd[(e_2 \, v)]{i} + v \pd[(e_1 \, u)]{j} \rt) + \frac{1}{e_1 e_2} \lt( e_2 \; u \pd[u]{i} + e_2 \; v \pd[v]{i} \rt) + \frac{1}{e_3} \lt( w \; \pd[u]{k} \rt) \\
+  &      &= &\frac{1}{e_1 \; e_2} \lt[ - \lt( v^2 \pd[e_2]{i} + e_2 \, v \pd[v]{i} \rt) + \lt( \pd[ \lt( e_1 \, u \, v \rt)]{j} - e_1 \, u \pd[v]{j} \rt) \rt. \lt. + \lt( \pd[ \lt( e_2 \, u \, u \rt)]{i} - u \pd[ \lt( e_2 u \rt)]{i} \rt) + e_2 v \pd[v]{i} \rt] \\
   &      & &+ \frac{1}{e_3} \lt( \pd[(w \, u)]{k} - u \pd[w]{k} \rt) \\
+  &      &=  &\frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, u)]{i} + \pd[(e_1 \, u \, v)]{j} \rt)
+            + \frac{1}{e_3} \pd[(w \, u)]{k} \\
+  &      & &+ \frac{1}{e_1 e_2} \lt[ - u \lt( \pd[(e_1 v)]{j} - v \, \pd[e_1]{j} \rt)
+                                  - u \pd[(e_2 u)]{i}                              \rt]
+            - \frac{1}{e_3} \pd[w]{k} u \\
+  &      &= &\frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, u)]{i} + \pd[(e_1 \, u \, v)]{j} \rt) + \frac{1}{e_3} \pd[(w \, u)]{k} + \frac{1}{e_1 e_2} \lt[ - u \lt( \pd[(e_1 v)]{j} - v \, \pd[e_1]{j} \rt) - u \pd[(e_2 u)]{i} \rt] - \frac{1}{e_3} \pd[w]{k} u \\
   &      & &+ \frac{1}{e_1 e_2} \lt( - v^2 \pd[e_2]{i} \rt) \\
+  &      &= &\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 becomes:}
+  &      &= &\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) \\
+  \shortintertext{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}
   NLT =   \nabla \cdot \lt(
     \begin{array}{*{20}c}
                             \vect U \, u \\
                             \vect U \, v
     \end{array}
                                          \rt)
         + \frac{1}{e_1 e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \vect k \times \vect U_h
+  \label{eq:MB_flux_form}
+  NLT = \nabla \cdot \lt(
+  \begin{array}{*{20}c}
+    \vect U \, u \\
+    \vect U \, v
+  \end{array}
+  \rt)
+  + \frac{1}{e_1 e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \vect k \times \vect U_h
 \end{equation}
 The flux form has two terms,
+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 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:
 \[
   % \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)
 \]
 …
 the following tensorial formalism:
+\begin{itemize}
+\item
+  \textbf{Vector invariant form of the momentum equations}:
+\begin{description}
+\item [Vector invariant form of the momentum equations]
   \begin{equation}
+    \label{eq:PE_dyn_vect}
+    \begin{split}
+    % \label{eq:PE_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) \\
+                  &+ D_v^{\vect U} + F_v^{\vect U}
+    \end{split}
+    \label{eq:MB_dyn_vect}
+    \begin{gathered}
+    % \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) + D_v^{\vect U} + F_v^{\vect U}
+    \end{gathered}
   \end{equation}
+\item
+  \textbf{flux form of the momentum equations}:
+  % \label{eq:PE_dyn_flux}
+  \begin{multline*}
+    % \label{eq:PE_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) \\
+                - \frac{1}{e_3} \pd[(w \, 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}
+  \end{multline*}
+  \begin{multline*}
+    % \label{eq:PE_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_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,
+  is given by:
+\item [Flux form of the momentum equations]
+  % \label{eq:MB_dyn_flux}
+  \begin{alignat*}{2}
+    % \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) - \frac{1}{e_3} \pd[(w \, 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}
+  \end{alignat*}
+  \begin{alignat*}{2}
+    % \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_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{alignat*}
+  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
   \]
   and $\eta$ is the 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}
+  % \label{eq:MB_w_diag}
     \pd[w]{k} = - \chi \; e_3 \qquad
   % \label{eq:hp_diag}
+  % \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
+  \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 \\
+    \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}.
+  where the divergence of the horizontal velocity, $\chi$ is given by \autoref{eq:MB_div_Uh}.
+\item [Tracer equations]
+  \begin{gather*}
+    \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 \\
+    \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{gather*}
+\end{description}
+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: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}.
+\newpage
+% ================================================================
+% Curvilinear generalised vertical coordinate System
+% ================================================================
+%% =================================================================================================
 \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.
 …
 varying from more than 6,000 meters in abyssal trenches to zero at the coast.
 Last but not least, the ocean stratification exerts a strong barrier to vertical motions and mixing.
 Therefore, in order to represent the ocean with respect to
 the first point a space and time dependent vertical coordinate that follows the variation of the sea surface height
+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;
+for the second point, a space variation to fit the change of bottom topography
+for the second point,
+a space variation to fit the change of bottom topography
 \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 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.smith.ea_JPO03} or
+OPA (mixture of $z$-coordinate in vicinity the surface and steep topography areas and $\sigma$-coordinate elsewhere)
+\citep{madec.delecluse.ea_JPO96} among others.
+and for the third point,
+one will be tempted to use a space and time dependent coordinate that follows the isopycnal surfaces,
+\eg\ an isopycnic coordinate.
+In order to satisfy two or more constraints one can even be tempted to mixed these coordinate systems,
+as in HYCOM (mixture of $z$-coordinate at the surface, isopycnic coordinate in the ocean interior and
+$\sigma$ at the ocean bottom) \citep{chassignet.smith.ea_JPO03} or
+OPA (mixture of $z$-coordinate in vicinity the surface and steep topography areas and
+$\sigma$-coordinate elsewhere) \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
+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: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}.
+\autoref{eq:MB_s}.
 This so-called \textit{generalised vertical coordinate} \citep{kasahara_MWR74} is in fact
+an Arbitrary Lagrangian--Eulerian (ALE) coordinate.
+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.burchard.ea_OM10},
+since the coordinate system is adapted in the course of the simulation.
+an \textbf{A}rbitrary \textbf{L}agrangian--\textbf{E}ulerian (ALE) coordinate.
+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 sometimes referenced as an adaptive coordinate
+\citep{hofmeister.burchard.ea_OM10}, since the coordinate system is adapted in
+the course of the simulation.
 Its most often used implementation is via an ALE algorithm,
 in which a pure lagrangian step is followed by regridding and remapping steps,
 …
 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 of the vertical coordinate, be it geopotential,
 isopycnal, pressure, or terrain following.
+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
 the hydrostatic and geostrophic balances are dominant in the large-scale ocean.
+Use of an alternative quasi -horizontal velocity, for example one oriented parallel to the generalized surface,
+Use of an alternative quasi -horizontal velocity,
+for example one oriented parallel to the generalized surface,
 would lead to unacceptable numerical errors.
 Correspondingly, the vertical direction is anti -parallel to the gravitational force in
 …
 the surface of a constant generalized vertical coordinate.
+It is the method used to measure transport across the generalized vertical coordinate surfaces which differs between
+the vertical coordinate choices.
+That is, computation of the dia-surface velocity component represents the fundamental distinction between
+It is the method used to measure transport across the generalized vertical coordinate surfaces which
+differs between the vertical coordinate choices.
+That is,
+computation of the dia-surface velocity component represents the fundamental distinction between
 the various coordinates.
+In some models, such as geopotential, pressure, and terrain following, this transport is typically diagnosed from
+volume or mass conservation.
+In other models, such as isopycnal layered models, this transport is prescribed based on assumptions about
+the physical processes producing a flux across the layer interfaces.
+In some models, such as geopotential, pressure, and terrain following,
+this transport is typically diagnosed from volume or mass conservation.
+In other models, such as isopycnal layered models,
+this transport is prescribed based on assumptions about the physical processes producing
+a flux across the layer interfaces.
 In this section we first establish the PE in the generalised vertical $s$-coordinate,
 …
 %}
+% -------------------------------------------------------------------------------------------------------------
+% The s-coordinate Formulation
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsection{\textit{S}-coordinate formulation}
+Starting from the set of equations established in \autoref{sec:PE_zco} for the special case $k = z$ and
+thus $e_3 = 1$, we introduce an arbitrary vertical coordinate $s = s(i,j,k,t)$,
+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}.
+Let us define the vertical scale factor by $e_3 = \partial_s z$  ($e_3$ is now a function of $(i,j,k,t)$ ),
+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
 relative to the moving $s$-surfaces and normal to them:
+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}
+  % \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}):
+\begin{itemize}
+\item \textbf{Vector invariant form of the momentum equation}:
+  \begin{multline*}
+  % \label{eq:PE_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
+                + D_u^{\vect U} + F_u^{\vect U}
+  \end{multline*}
+  \begin{multline*}
+  % \label{eq:PE_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
+                + 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}
+    \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}
+  \end{multline*}
+  \begin{multline*}
+  % \label{eq:PE_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}
+  \end{multline*}
+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{description}
+\item [Vector invariant form of the momentum equation]
+  \begin{gather*}
+    % \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 + D_u^{\vect U} + F_u^{\vect U} \\
+    % \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 + D_v^{\vect U} + F_v^{\vect U}
+  \end{gather*}
+\item [Flux form of the momentum equation]
+  \begin{alignat*}{2}
+    % \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}
+  \end{alignat*}
+  \begin{alignat*}{2}
+  % \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}
+  \end{alignat*}
   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}
+    \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) \\
+                                       - \frac{1}{e_3} \pd[(T \, \omega)]{k} + D^T + F^S
+  \end{multline*}
+  \begin{multline}
+  % \label{eq:PE_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) \\
+                                       - \frac{1}{e_3} \pd[(S \, \omega)]{k} + D^S + F^S
+  \end{multline}
+\end{itemize}
+\item [Tracer equations]
+  \begin{gather*}
+    % \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) - \frac{1}{e_3} \pd[(T \, \omega)]{k} + D^T + F^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) - \frac{1}{e_3} \pd[(S \, \omega)]{k} + D^S + F^S
+  \end{gather*}
+\end{description}
 The equation of state has the same expression as in $z$-coordinate,
 and similar expressions are used for mixing and forcing terms.
 …
+}
+% -------------------------------------------------------------------------------------------------------------
+% Curvilinear \zstar-coordinate System
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsection{Curvilinear \zstar-coordinate system}
+\label{subsec:PE_zco_star}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!b]
+  \begin{center}
+    \includegraphics[width=\textwidth]{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
+\label{subsec:MB_zco_star}
+\begin{figure}
+  \centering
+  \includegraphics[width=0.66\textwidth]{Fig_z_zstar}
+  \caption[Curvilinear z-coordinate systems (\{non-\}linear free-surface cases and re-scaled \zstar)]{
+    \begin{enumerate*}[label=(\textit{\alph*})]
+    \item $z$-coordinate in linear free-surface case;
+    \item $z$-coordinate in non-linear free surface case;
+    \item re-scaled height coordinate
       (become popular as the \zstar-coordinate \citep{adcroft.campin_OM04}).
+    }
+  \end{center}
+    \end{enumerate*}
+  }
+  \label{fig:MB_z_zstar}
 \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+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}.
+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.
+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}.
+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 major points are summarized here.
 The position (\zstar) and vertical discretization (\zstar) are expressed as:
+The position (\zstar) and vertical discretization ($\delta \zstar$) are expressed as:
 \[
+  % \label{eq:PE_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} .
+  % \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}
 \]
 Simple re-organisation of the above expressions gives
 \[
   % \label{eq:PE_zstar_2}
   \zstar = H \lt( \frac{z - \eta}{H + \eta} \rt) .
+  % \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,
 the upper and lower boundaries are at fixed  \zstar position,
+the upper and lower boundaries are at fixed \zstar\ position,
 $\zstar = 0$ and $\zstar = -H$ respectively.
 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) + \pd[r \; w^*]{\zstar} = 0 .
+  \pd[r]{t} = \nabla_{\zstar} \cdot \lt( r \; \vect U_h \rt) + \pd[r \; w^*]{\zstar} = 0
 \]
 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).
+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,
 and it has been recently promoted by Adcroft and Campin (2004) for global climate modelling.
 The surfaces of constant \zstar are quasi -horizontal.
 Indeed, the \zstar coordinate reduces to $z$ when $\eta$ is zero.
+The surfaces of constant \zstar\ are quasi-horizontal.
+Indeed, the \zstar\ coordinate reduces to $z$ when $\eta$ is zero.
 In general, when noting the large differences between
 undulations of the bottom topography versus undulations in the surface height,
 it is clear that surfaces constant \zstar are very similar to the depth surfaces.
+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}.
+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
+nontrivial topographic variations can generate nontrivial spontaneous flow from a resting state,
+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 nontrivial topographic variations can generate
+nontrivial spontaneous flow from a resting state,
 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
+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,
 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$.
+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,
+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 vertical increments yields the time independent ocean depth. %k ds = H.
 The \zstar coordinate is therefore invisible to undulations of the free surface,
+The \zstar\ coordinate is therefore invisible to undulations of the free surface,
 since it moves along with the free surface.
 This property means that no spurious vertical transport is induced across surfaces of constant \zstar  by
 the motion of external gravity waves.
+This property means that no spurious vertical transport is induced across
+surfaces of constant \zstar\  by the motion of external gravity waves.
 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$.
+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
+% -------------------------------------------------------------------------------------------------------------
+% Terrain following  coordinate System
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsection{Curvilinear terrain-following \textit{s}--coordinate}
+\label{subsec:PE_sco}
+% -------------------------------------------------------------------------------------------------------------
+% Introduction
+% -------------------------------------------------------------------------------------------------------------
+\subsubsection{Introduction}
+\label{subsec:MB_sco}
 Several important aspects of the ocean circulation are influenced by bottom topography.
+Of course, the most important is that bottom topography determines deep ocean sub-basins, barriers, sills and
+channels that strongly constrain the path of water masses, but more subtle effects exist.
+For example, the topographic $\beta$-effect is usually larger than the planetary one along continental slopes.
+Of course, the most important is that bottom topography determines deep ocean sub-basins, barriers,
+sills and channels that strongly constrain the path of water masses, but more subtle effects exist.
+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.
 …
 large localized depth gradients associated with large localized vertical velocities.
 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}.
+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}.
 Another solution is to introduce a terrain-following coordinate system (hereafter $s$-coordinate).
+The $s$-coordinate avoids the discretisation error in the depth field since the layers of
+computation are gradually adjusted with depth to the ocean bottom.
+Relatively small topographic features as well as  gentle, large-scale slopes of the sea floor in the deep ocean,
+which would be ignored in typical $z$-model applications with the largest grid spacing at greatest depths,
+The $s$-coordinate avoids the discretisation error in the depth field since
+the layers of computation are gradually adjusted with depth to the ocean bottom.
+Relatively small topographic features as well as
+gentle, large-scale slopes of the sea floor in the deep ocean,
+which would be ignored in typical $z$-model applications with
+the largest grid spacing at greatest depths,
 can easily be represented (with relatively low vertical resolution).
+A terrain-following model (hereafter $s$-model) also facilitates the modelling of the boundary layer flows over
+a large depth range, which in the framework of the $z$-model would require high vertical resolution over
+A terrain-following model (hereafter $s$-model) also facilitates
+the modelling of the boundary layer flows over a large depth range,
+which in the framework of the $z$-model would require high vertical resolution over
 the whole depth range.
+Moreover, with a $s$-coordinate it is possible, at least in principle, to have the bottom and the sea surface as
+Moreover,
+with a $s$-coordinate it is possible, at least in principle, to have the bottom and the sea surface as
 the only boundaries of the domain (no more lateral boundary condition to specify).
+Nevertheless, a $s$-coordinate also has its drawbacks. Perfectly adapted to a homogeneous ocean,
+Nevertheless, a $s$-coordinate also has its drawbacks.
+Perfectly adapted to a homogeneous ocean,
 it has strong limitations as soon as stratification is introduced.
 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}
+  \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
+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{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.
+In the special case of a $\sigma$-coordinate
+(i.e. a depth-normalised coordinate system $\sigma = z/H$),
+\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.
 This error limits the possible topographic slopes that a model can handle at
 a given horizontal and vertical resolution.
 This is a severe restriction for large-scale applications using realistic bottom topography.
+The large-scale slopes require high horizontal resolution, and the computational cost becomes prohibitive.
+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{gerdes_JGR93*a,gerdes_JGR93*b,madec.delecluse.ea_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:
 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}.
 For numerical reasons a minimum of diffusion is required along the coordinate surfaces of
 any finite difference model.
+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{subsec:DOM_zgr}).
+For numerical reasons a minimum of diffusion is required along
+the coordinate surfaces of any finite difference model.
 It causes spurious diapycnal mixing when coordinate surfaces do not coincide with isoneutral surfaces.
 This is the case for a $z$-model as well as for a $s$-model.
+However, density varies more strongly on $s$-surfaces than on horizontal surfaces in regions of
+large topographic slopes, implying larger diapycnal diffusion in a $s$-model than in a $z$-model.
+Whereas such a diapycnal diffusion in a $z$-model tends to weaken horizontal density (pressure) gradients and thus
+the horizontal circulation, it usually reinforces these gradients in a $s$-model, creating spurious circulation.
+For example, imagine an isolated bump of topography in an ocean at rest with a horizontally uniform stratification.
+However, density varies more strongly on $s$-surfaces than on horizontal surfaces in
+regions of large topographic slopes,
+implying larger diapycnal diffusion in a $s$-model than in a $z$-model.
+Whereas such a diapycnal diffusion in a $z$-model tends to
+weaken horizontal density (pressure) gradients and thus the horizontal circulation,
+it usually reinforces these gradients in a $s$-model, creating spurious circulation.
+For example, imagine an isolated bump of topography in
+an ocean at rest with a horizontally uniform stratification.
 Spurious diffusion along $s$-surfaces will induce a bump of isoneutral surfaces over the topography,
 and thus will generate there a baroclinic eddy.
 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.delecluse.ea_JPO96}.
+An alternate solution consists of rotating the lateral diffusive tensor to geopotential or to isoneutral surfaces
+(see \autoref{subsec:PE_ldf}).
+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.delecluse.ea_JPO96}.
+An alternate solution consists of rotating the lateral diffusive tensor to
+geopotential or to isoneutral surfaces (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.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;
+strongly exceeding the stability limit of such a operator when it is discretized
+(see \autoref{chap:LDF}).
+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;
 It also offers a completely general transformation, $s=s(i,j,z)$ for the vertical coordinate.
+% -------------------------------------------------------------------------------------------------------------
+% Curvilinear z-tilde coordinate System
+% -------------------------------------------------------------------------------------------------------------
+\subsection{\texorpdfstring{Curvilinear \ztilde-coordinate}{}}
+\label{subsec:PE_zco_tilde}
+The \ztilde -coordinate has been developed by \citet{leclair.madec_OM11}.
+%% =================================================================================================
+\subsection{Curvilinear \ztilde-coordinate}
+\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
+% ================================================================
+% Subgrid Scale Physics
+% ================================================================
+%% =================================================================================================
 \section{Subgrid scale physics}
+\label{sec:PE_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.
+\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.
 The effects of smaller scale motions (coming from the advective terms in the Navier-Stokes equations)
 must be represented entirely in terms of large-scale patterns to close the equations.
 …
 small scale processes \textit{in fine} balance the surface input of kinetic energy and heat.
+The control exerted by gravity on the flow induces a strong anisotropy between the lateral and vertical motions.
+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
 a lateral part \textbf{D}$^{l \vect U}$, $D^{l S}$ and $D^{l T}$ and
+\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}$.
+The formulation of these terms and their underlying physics are briefly discussed in the next two subsections.
+% -------------------------------------------------------------------------------------------------------------
+% Vertical Subgrid Scale Physics
+% -------------------------------------------------------------------------------------------------------------
+The formulation of these terms and their underlying physics are briefly discussed in
+the next two subsections.
+%% =================================================================================================
 \subsection{Vertical subgrid scale physics}
 \label{subsec:PE_zdf}
 The model resolution is always larger than the scale at which the major sources of vertical turbulence occur
 (shear instability, internal wave breaking...).
+\label{subsec:MB_zdf}
+The model resolution is always larger than the scale at which
+the major sources of vertical turbulence occur (shear instability, internal wave breaking...).
 Turbulent motions are thus never explicitly solved, even partially, but always parameterized.
+The vertical turbulent fluxes are assumed to depend linearly on the gradients of large-scale quantities
+(for example, the turbulent heat flux is given by $\overline{T' w'} = -A^{v T} \partial_z \overline T$,
+The vertical turbulent fluxes are assumed to depend linearly on
+the gradients of large-scale quantities (for example,
+the turbulent heat flux is given by $\overline{T' w'} = -A^{v T} \partial_z \overline T$,
 where $A^{v T}$ is an eddy coefficient).
 This formulation is analogous to that of molecular diffusion and dissipation.
 …
 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) \ , \\
           D^{vT}       = \pd[]{z} \lt( A^{vT} \pd[T]{z}         \rt) \quad \text{and} \quad
+    \vect D^{v \vect U} = \pd[]{z} \lt( A^{vm} \pd[\vect U_h]{z} \rt) \text{,} \
+          D^{vT}       = \pd[]{z} \lt( A^{vT} \pd[T]{z}         \rt) \ \text{and} \
           D^{vS}       = \pd[]{z} \lt( A^{vT} \pd[S]{z}         \rt)
   \end{gathered}
 \end{equation}
+where $A^{vm}$ and $A^{vT}$ are the vertical eddy viscosity and diffusivity coefficients, respectively.
+where $A^{vm}$ and $A^{vT}$ are the vertical eddy viscosity and diffusivity coefficients,
+respectively.
 At the sea surface and at the bottom, turbulent fluxes of momentum, heat and salt must be specified
 (see \autoref{chap:SBC} and \autoref{chap:ZDF} and \autoref{sec:TRA_bbl}).
 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, distance from the boundary ...),
+(\eg\ Richardson number, Brunt-V\"{a}is\"{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}).
+% -------------------------------------------------------------------------------------------------------------
+% Lateral Diffusive and Viscous Operators Formulation
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \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
 (which can be solved explicitly if the resolution is sufficient since
 their underlying physics are included in the primitive equations),
+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).
+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).
 In non-eddy-resolving configurations, the closure is similar to that used for the vertical physics.
+The lateral turbulent fluxes are assumed to depend linearly on the lateral gradients of large-scale quantities.
+The lateral turbulent fluxes are assumed to depend linearly on
+the lateral gradients of large-scale quantities.
 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
+Observations show that
+lateral mixing induced by mesoscale turbulence tends to be along isopycnal surfaces
 (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.
+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.
 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
+This assumption can be relaxed:
+the eddy-induced turbulent fluxes can be better approached by assuming that
 they depend linearly on the gradients of large-scale quantities computed along neutral surfaces.
 In such a case, the diffusive operator is an isoneutral second order operator and
 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
+However, 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{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.
 This leads to a formulation of lateral subgrid-scale physics made up of an isoneutral second order operator and
 an eddy induced advective part.
+This leads to a formulation of lateral subgrid-scale physics made up of
+an isoneutral second order operator and an eddy induced advective part.
 In all these lateral diffusive formulations,
 the specification of the lateral eddy coefficients remains the problematic point as
+there is no really satisfactory formulation of these coefficients as a function of large-scale features.
+there is no really satisfactory formulation of these coefficients as
+a function of large-scale features.
 In eddy-resolving configurations, a second order operator can be used,
 …
 not interfering with the resolved mesoscale activity.
 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,
+instead of specifying explicitly a sub-grid scale term in
+the momentum and tracer time evolution equations,
 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.
+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.
+They 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{gent.mcwilliams_JPO90} parameterisation, and various slightly diffusive advection schemes.
+For momentum, the main ones are: Laplacian and bilaplacian operators acting along geopotential surfaces,
+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}
+  D^{lT} = \nabla \vect . \lt( A^{lT} \; \Re \; \nabla T \rt) \quad \text{with} \quad
+  \Re =
+    \begin{pmatrix}
+    & 0    & -r_1          \\
+    & 1    & -r_2          \\
+      -r_1 & -r_2 & r_1^2 + r_2^2 \\
+    \end{pmatrix}
+  \label{eq:MB_iso_tensor}
+  D^{lT} = \nabla \vect . \lt( A^{lT} \; \Re \; \nabla T \rt) \quad \text{with} \quad \Re =
+  \begin{pmatrix}
+    & 0    & -r_1          \\
+    & 1    & -r_2          \\
+    -r_1 & -r_2 & r_1^2 + r_2^2 \\
+  \end{pmatrix}
 \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
+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{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.
+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}).
+For \textit{isoneutral} diffusion $r_1$ and $r_2$ are the slopes between the isoneutral and computational surfaces.
+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.
 Therefore, they are different quantities, but have similar expressions in $z$- and $s$-coordinates.
 In $z$-coordinates:
 \begin{equation}
   \label{eq:PE_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}
+  \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}
 \end{equation}
 while in $s$-coordinates $\pd[]{k}$ is replaced by $\pd[]{s}$.
+%% =================================================================================================
 \subsubsection{Eddy induced velocity}
 …
 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)
 \]
 where $ \vect U^\ast = \lt( u^\ast,v^\ast,w^\ast \rt)$ is a non-divergent,
 eddy-induced transport velocity. This velocity field is defined by:
 \begin{gather}
   % \label{eq:PE_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) \\
+\[
+  % \label{eq:MB_eiv}
+  u^\ast =   \frac{1}{e_3}            \pd[]{k} \lt( A^{eiv} \;        \tilde{r}_1 \rt) \quad
+  v^\ast =   \frac{1}{e_3}            \pd[]{k} \lt( A^{eiv} \;        \tilde{r}_2 \rt) \quad
   w^\ast = - \frac{1}{e_1 e_2} \lt[   \pd[]{i} \lt( A^{eiv} \; e_2 \, \tilde{r}_1 \rt)
                                      + \pd[]{j} \lt( A^{eiv} \; e_1 \, \tilde{r}_2 \rt) \rt]
 \end{gather}
+\]
 where $A^{eiv}$ is the eddy induced velocity coefficient
 (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:
+\begin{align}
+  \label{eq:PE_slopes_eiv}
+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:
+\begin{equation}
+  \label{eq:MB_slopes_eiv}
   \tilde{r}_n =
     \begin{cases}
 …
     \end{cases}
   \quad \text{where~} n = 1, 2
 \end{align}
+\end{equation}
 The normal component of the eddy induced velocity is zero at all the boundaries.
 This can be achieved in a model by tapering either the eddy coefficient or the slopes to zero in the vicinity of
 the boundaries.
+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}).
+%% =================================================================================================
 \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.
+%% =================================================================================================
 \subsubsection{Lateral Laplacian momentum diffusive operator}
 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) \\
 …
 \end{align*}
 Such a formulation ensures a complete separation between the vorticity and horizontal divergence fields
 (see \autoref{apdx:C}).
+Such a formulation ensures a complete separation between
+the vorticity and horizontal divergence fields (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),
+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}
+    D_u^{l \vect U} = \nabla . \lt( A^{lm} \; \Re \; \nabla u \rt) \\
+(\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:
+\[
+  % \label{eq:MB_lapU_iso}
+    D_u^{l \vect U} = \nabla . \lt( A^{lm} \; \Re \; \nabla u \rt) \quad
     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,
 …
 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
+As for tracers,
+the bilaplacian order momentum diffusive operator is a re-entering Laplacian operator with
 the harmonic eddy diffusion coefficient set to the square root of the biharmonic one.
 Nevertheless it is currently not available in the iso-neutral case.
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex

-                      r11435
+                      r11799
 \begin{document}
+% ================================================================
+% Chapter 1 Model Basics
+% ================================================================
+% ================================================================
+% Curvilinear \zstar- \sstar-coordinate System
+% ================================================================
 \chapter{ essai \zstar \sstar}
+\thispagestyle{plain}
+\chaptertoc
+\paragraph{Changes record} ~\\
+{\footnotesize
+  \begin{tabularx}{\textwidth}{l||X|X}
+    Release & Author(s) & Modifications \\
+    \hline
+    {\em   4.0} & {\em ...} & {\em ...} \\
+    {\em   3.6} & {\em ...} & {\em ...} \\
+    {\em   3.4} & {\em ...} & {\em ...} \\
+    {\em <=3.4} & {\em ...} & {\em ...}
+  \end{tabularx}
+}
+\clearpage
+%% =================================================================================================
 \section{Curvilinear \zstar- or \sstar coordinate system}
-% -------------------------------------------------------------------------------------------------------------
-% ????
-% -------------------------------------------------------------------------------------------------------------
 \colorbox{yellow}{ to be updated }
 …
 To overcome problems with vanishing surface and/or bottom cells, we consider the zstar coordinate
 \[
   % \label{eq:PE_}
+  % \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.
 …
 the surface height, again so long as $\eta > -H$.
-%%%
 %  essai update time splitting...
+%%%
+% ================================================================
+% Surface Pressure Gradient and Sea Surface Height
+% ================================================================
+\section[Surface pressure gradient and sea surface heigth (\textit{dynspg.F90})]
+{Surface pressure gradient and sea surface heigth (\protect\mdl{dynspg})}
+\label{sec:DYN_hpg_spg}
+%-----------------------------------------nam_dynspg----------------------------------------------------
+%% =================================================================================================
+\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}
 %\nlst{nam_dynspg}
+%------------------------------------------------------------------------------------------------------------
+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:PE_hor_pg}).
+Options are defined through the \nam{_dynspg}{\_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,
 so that the update of the next velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}.
-%-------------------------------------------------------------
 % Explicit
+%-------------------------------------------------------------
+\subsubsection[Explicit (\texttt{\textbf{key\_dynspg\_exp}})]
+{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}
 …
 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 (\texttt{\textbf{key\_dynspg\_ts}})]
+{Split-explicit time-stepping (\protect\key{dynspg\_ts})}
+\label{subsec:DYN_spg_ts}
+%--------------------------------------------namdom----------------------------------------------------
+\nlst{namdom}
+%--------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
+\subsubsection[Split-explicit time-stepping (\texttt{\textbf{key\_dynspg\_ts}})]{Split-explicit time-stepping (\protect\key{dynspg\_ts})}
+\label{subsec:MBZ_dyn_spg_ts}
 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 \nam{dom} namelist (Figure III.3).
+%>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >
+is a multiple of \np{rdtbt}{rdtbt} in the \nam{dom}{dom} namelist (Figure III.3).
 \begin{figure}[!t]
   \begin{center}
     \includegraphics[width=\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=0.66\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,
 …
 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]
 \]
 \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})
 …
 This is also the time that sets the barotropic time steps via
 \[
   % \label{eq:DYN_spg_ts_t}
+  % \label{eq:MBZ_dyn_spg_ts_t}
   t_n=\tau+n\Delta t
 \]
 …
 The density scaled surface pressure is evaluated via
 \[
   % \label{eq:DYN_spg_ts_ps}
+  % \label{eq:MBZ_dyn_spg_ts_ps}
   p_s^{(b)}(\tau,t_{n}) =
   \begin{cases}
 …
 To get started, we assume the following initial conditions
 \[
   % \label{eq:DYN_spg_ts_eta}
+  % \label{eq:MBZ_dyn_spg_ts_eta}
   \begin{split}
     \eta^{(b)}(\tau,t_{n=0}) &= \overline{\eta^{(b)}(\tau)} \\
 …
 with
 \[
   % \label{eq:DYN_spg_ts_etaF}
+  % \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}
+  % \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})
 \]
 …
 produce the updated vertically integrated velocity at baroclinic time $\tau + \Delta \tau$
 \[
   % \label{eq:DYN_spg_ts_u}
+  % \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})
 …
 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}
 …
 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
 …
 \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}
 …
 \[
   % \label{eq:DYN_spg_ts_sshf2}
+  % \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
+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:DYN_spg_flt}
+%% =================================================================================================
+\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 amplitude of the extra term is given by the namelist variable \np{rnu}{rnu}.
 The default value is 1, as recommended by \citet{Roullet2000?}
+\colorbox{red}{\np{rnu}\forcode{ = 1} to be suppressed from namelist !}
+%-------------------------------------------------------------
+\colorbox{red}{\np[=1]{rnu}{rnu} 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:DYN_spg_vvl}
+%% =================================================================================================
+\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{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.
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_time_domain.tex

-                      r11435
+                      r11799
 \begin{document}
+% ================================================================
+% Chapter 2 ——— Time Domain (step.F90)
+% ================================================================
 \chapter{Time Domain (STP)}
+\label{chap:STP}
+\chapter{Time Domain}
+\label{chap:TD}
+\thispagestyle{plain}
 \chaptertoc
+\paragraph{Changes record} ~\\
+{\footnotesize
+  \begin{tabularx}{0.5\textwidth}{l||X|X}
+    Release          & Author(s)                                       &
+    Modifications                                                      \\
+    \hline
+    {\em        4.0} & {\em J\'{e}r\^{o}me Chanut \newline Tim Graham} &
+    {\em Review \newline Update                                      } \\
+    {\em        3.6} & {\em Christian \'{E}th\'{e}                   } &
+    {\em Update                                                      } \\
+    {\em $\leq$ 3.4} & {\em Gurvan Madec                             } &
+    {\em First version                                               } \\
+  \end{tabularx}
+}
+\clearpage
 % Missing things:
+%  - 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,
+  would help  ==> to be added}
+%%%%
+\newpage
+Having defined the continuous equations in \autoref{chap:PE}, we need now to choose a time discretization,
+% - 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, would help  ==> to be added}
+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
+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.
+% ================================================================
+% Time Discretisation
+% ================================================================
+%% =================================================================================================
 \section{Time stepping environment}
 \label{sec:STP_environment}
+\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:STP}
+  \label{eq:TD}
   x^{t + \rdt} = x^{t - \rdt} + 2 \, \rdt \ \text{RHS}_x^{t - \rdt, \, t, \, t + \rdt}
 \end{equation}
 where $x$ stands for $u$, $v$, $T$ or $S$;
 RHS is the Right-Hand-Side of the corresponding time evolution equation;
+RHS is the \textbf{R}ight-\textbf{H}and-\textbf{S}ide 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 stepping depending on the physics with which it is associated.
+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.
 With such a complex and nonlinear system of equations it would be dangerous to let a prognostic variable evolve in
 time for each term separately.
+With such a complex and nonlinear system of equations it would be dangerous to
+let a prognostic variable evolve in time for each term separately.
 The three level scheme requires three arrays for each prognostic variable.
 …
 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.
+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.
+% -------------------------------------------------------------------------------------------------------------
+%        Non-Diffusive Part---Leapfrog Scheme
+% -------------------------------------------------------------------------------------------------------------
+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}
 The time stepping used for processes other than diffusion is the well-known leapfrog scheme
 \citep{mesinger.arakawa_bk76}.
+\label{sec:TD_leap_frog}
+The time stepping used for processes other than diffusion is
+the well-known \textbf{L}eap\textbf{F}rog (LF) scheme \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.
 It is an efficient method that achieves second-order accuracy with
 just one right hand side evaluation per time step.
 Moreover, it does not artificially damp linear oscillatory motion nor does it produce instability by
 amplifying the oscillations.
+Moreover, it does not artificially damp linear oscillatory motion
+nor does it produce instability by amplifying the oscillations.
 These advantages are somewhat diminished by the large phase-speed error of the leapfrog scheme,
+and the unsuitability of leapfrog differencing for the representation of diffusion and Rayleigh damping processes.
+and the unsuitability of leapfrog differencing for the representation of diffusion and
+Rayleigh damping processes.
 However, the scheme allows the coexistence of a numerical and a physical mode due to
 its leading third order dispersive error.
 In other words a divergence of odd and even time steps may occur.
+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},
+To prevent it, the leapfrog scheme is often used in association with
+a \textbf{R}obert-\textbf{A}sselin time filter (hereafter the LF-RA scheme).
+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}),
+$\gamma$ is initialized as \np{rn_atfp}{rn\_atfp} (namelist parameter).
+Its default value is \np[=10.e-3]{rn_atfp}{rn\_atfp} (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.
 Therefore, the LF-RA is a quasi second order accurate scheme.
+The LF-RA scheme is preferred to other time differencing schemes such as predictor corrector or trapezoidal schemes,
+because the user has an explicit and simple control of the magnitude of the time diffusion of the scheme.
+When used with the 2nd order space centred discretisation of the advection terms in
+The LF-RA scheme is preferred to other time differencing schemes such as
+predictor corrector or trapezoidal schemes, because the user has an explicit and simple control of
+the magnitude of the time diffusion of the scheme.
+When used with the 2$^nd$ 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
+filter parameter and the viscosity and diffusion coefficients.
+% -------------------------------------------------------------------------------------------------------------
+%        Diffusive Part---Forward or Backward Scheme
+% -------------------------------------------------------------------------------------------------------------
+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}
+The leapfrog differencing scheme is unsuitable for the representation of diffusion and damping processes.
+\label{sec:TD_forward_imp}
+The leapfrog differencing scheme is unsuitable for
+the representation of diffusion and damping processes.
 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}:
+The conditions for stability of second and fourth order horizontal diffusion schemes are
+\citep{griffies_bk04}:
 \begin{equation}
   \label{eq:STP_euler_stability}
+  \label{eq:TD_euler_stability}
   A^h <
   \begin{cases}
 …
   \end{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.
+where $e$ is the smallest grid size in the two horizontal directions and
+$A^h$ is the mixing coefficient.
+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.
+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. 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:
+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:STP_imp}
+  \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. 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:
+We rewrite \autoref{eq:TD_imp} as:
 \begin{equation}
   \label{eq:STP_imp_mat}
+  \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*}
+  c(k) &= A_w^{vT} (k) \, / \, e_{3w} (k)     \\
+  d(k) &= e_{3t}   (k)       \, / \, (2 \rdt) + c_k + c_{k + 1}    \\
+  b(k) &= e_{3t}   (k) \; \lt( T^{t - 1}(k) \, / \, (2 \rdt) + \text{RHS} \rt)
+\end{align*}
+\autoref{eq:STP_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,
+\[
+  c(k) = A_w^{vT} (k) \, / \, e_{3w} (k) \text{,} \quad
+  d(k) = e_{3t}   (k)       \, / \, (2 \rdt) + c_k + c_{k + 1} \quad \text{and} \quad
+  b(k) = e_{3t}   (k) \; \lt( T^{t - 1}(k) \, / \, (2 \rdt) + \text{RHS} \rt)
+\]
+\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{richtmyer.morton_bk67}).
+% -------------------------------------------------------------------------------------------------------------
+%        Surface Pressure gradient
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \section{Surface pressure gradient}
+\label{sec:STP_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: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.
+\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[=.true.]{ln_dynspg_exp}{ln\_dynspg\_exp}).
+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[=.true.]{ln_dynspg_ts}{ln\_dynspg\_ts}) 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[width=\textwidth]{Fig_TimeStepping_flowchart_v4}
+    \caption{
+      \protect\label{fig:TimeStep_flowchart}
+      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}.
+    }
+  \end{center}
+\begin{figure}
+  \centering
+  \includegraphics[width=0.66\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}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 %}
+% -------------------------------------------------------------------------------------------------------------
+%        The Modified Leapfrog -- Asselin Filter scheme
+% -------------------------------------------------------------------------------------------------------------
+\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
+ensure tracer conservation and to allow the use of a much smaller value of the Asselin filter parameter.
+%% =================================================================================================
+\section{Modified LeapFrog -- Robert Asselin filter scheme (LF-RA)}
+\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:
+In a classical LF-RA environment,
+the forcing term is centred in time, \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})
+has a significant effect:
+the forcing term no longer excites the divergence of odd and even time steps \citep{leclair.madec_OM09}.
+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}.
 % forcing seen by the model....
 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 explicitly 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}.
 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
+Second, the LF-RA becomes a truly quasi-second order scheme.
+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),
 …
 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},
+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[width=\textwidth]{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}
+\begin{figure}
+  \centering
+  \includegraphics[width=0.66\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}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+% -------------------------------------------------------------------------------------------------------------
+%        Start/Restart strategy
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \section{Start/Restart strategy}
+\label{sec:STP_rst}
+%--------------------------------------------namrun-------------------------------------------
+\nlst{namrun}
+%--------------------------------------------------------------------------------------------------------------
+The first time step of this three level scheme when starting from initial conditions is a forward step
+(Euler time integration):
+\label{sec:TD_rst}
+\begin{listing}
+  \nlst{namrun}
+  \caption{\forcode{&namrun}}
+  \label{lst:namrun}
+\end{listing}
+The first time step of this three level scheme when starting from initial conditions is
+a forward step (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 a leapfrog time step ($2 \rdt$).
 …
 running the model for $2N$ time steps in one go,
 or by performing two consecutive experiments of $N$ steps with a restart.
+This requires saving two time levels and many auxiliary data in the restart files in machine precision.
+This requires saving two time levels and many auxiliary data in
+the restart files in machine precision.
 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.
+%%%
+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[=0]{nn_euler}{nn\_euler}.
+Other options to control the time integration of the model are defined through
+the \nam{run}{run} namelist variables.
 \gmcomment{
 add here how to force the restart to contain only one time step for operational purposes
 …
 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 parameters are truly described
 a word on the check of restart  .....
+}
-%%%
 \gmcomment{       % add a subsection here
+%-------------------------------------------------------------------------------------------------------------
+%        Time Domain
+% -------------------------------------------------------------------------------------------------------------
+%% =================================================================================================
 \subsection{Time domain}
+\label{subsec:STP_time}
+%--------------------------------------------namrun-------------------------------------------
+\nlst{namdom}
+%--------------------------------------------------------------------------------------------------------------
+Options are defined through the  \nam{dom} namelist variables.
+\label{subsec:TD_time}
+Options are defined through the\nam{dom}{dom} namelist variables.
  \colorbox{yellow}{add here a few word on nit000 and nitend}
  \colorbox{yellow}{Write documentation on the calendar and the key variable adatrj}
+add a description of daymod, and the model calandar (leap-year and co)
+}        %% end add
+%%
+add a description of daymod, and the model calendar (leap-year and co)
+}     %% end add
 \gmcomment{       % add implicit in vvl case  and Crant-Nicholson scheme
 …
 \end{flalign*}
-%%
+}
+\biblio
+\pindex
+\onlyinsubfile{\input{../../global/epilogue}}
 \end{document}

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

Context Navigation

Legend:

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/build

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/main/appendices.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/main/bibliography.bib

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/main/chapters.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_ASM.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_DIA.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_DIU.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_DOM.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_DYN.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_LBC.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_LDF.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_OBS.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_SBC.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_STO.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_TRA.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_ZDF.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_conservation.tex

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

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_model_basics.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex

NEMO/branches/2019/dev_r11470_HPC_12_mpi3/doc/latex/NEMO/subfiles/chap_time_domain.tex

Download in other formats: