Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/.svnignore
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/.svnignore	(revision 10999)
+++ 	(revision )
@@ -1,16 +1,0 @@
-*.aux
-*.bbl
-*.blg
-*.dvi
-*.fdb*
-*.fls
-*.idx
-*.ilg
-*.ind
-*.log
-*.maf
-*.mtc*
-*.out
-*.pdf
-*.toc
-_minted-*
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/PDF_creation.sh
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/PDF_creation.sh	(revision 10999)
+++ 	(revision )
@@ -1,47 +1,0 @@
-#!/bin/sh
-
-export opts='-shell-escape -pdf -quiet'
-model='NEMO'
-
-check_python_module() {
-    python -c "
-import sys
-try:
-    import $1
-    print('\nModule $1 is installed')
-except ImportError:
-    print('\nModule $1 is NOT installed')
-    print('')
-    sys.exit(42)"
-}
-
-clean() {
-    ## Delete latex build files
-    find latex -regextype posix-extended                                              \
-         -regex ".*\.(aux|bbl|blg|dvi|fdb|fls|idx|ilg|ind|log|maf|mtc|out|pdf|toc).*" \
-         -exec rm {} \;
-
-    ## Remove 'minted' directories
-    find latex -type d -name '_minted*' -exec rm -r {} \;
-
-    ## HTML exports
-    find latex -type d -name 'html*'    -exec rm -r {} \;
-}
-
-build() {
-    cd latex/$1/main
-    latexmk $opts $1'_manual' > /dev/null
-    mv            $1'_manual'.pdf ../../..
-    cd -
-}
-
-check_python_module pygments
-if [ $? -ne 0 ]; then echo 'Required python module pygments to correctly build the documentation is missing; exit 42'; echo ''; exit 42; fi
-
-clean
-
-[ ! -d figures ] && svn co http://forge.ipsl.jussieu.fr/nemo/svn/utils/figures
-
-build $model
-
-exit 0
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/README.rst
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/README.rst	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/README.rst	(revision 11422)
@@ -0,0 +1,5 @@
+
+
+.. warning::
+
+    Mention `svnignore` hidden file
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/guide_build.sh
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/guide_build.sh	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/guide_build.sh	(revision 11422)
@@ -0,0 +1,29 @@
+#!/bin/sh
+
+## Avoid the use of shell builtin echo (for -e option)
+alias echo='/bin/echo -e'
+
+## Check dependancies
+##-------------------
+
+## Sphinx, BibTeX extension and "Read The Docs" theme
+if [ -n "$( ./tools/check_pkg.py sphinx sphinxcontrib.bibtex sphinx_rtd_theme )" ]; then
+    echo 'One of the Python dependencies is missing => QUIT'
+    exit 2
+fi
+
+cd rst
+
+echo "\t¤ Clean previous build"
+make clean
+echo
+
+echo "\t¤ Generation of the guide"
+make html > /dev/null
+echo
+
+echo "\t¤ End of building run"
+echo "Open ./rst/build/html/NEMO_guide.html"
+cd - > /dev/null
+
+exit 0
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/.svnignore
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/.svnignore	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/.svnignore	(revision 11422)
@@ -0,0 +1,18 @@
+*.aux
+*.bbl
+*.blg
+*.dvi
+*.fdb*
+*.fls
+*.idx
+*.ilg
+*.ind
+*.lof
+*.log
+*.lot
+*.maf
+*.mtc*
+*.out
+*.pdf
+*.toc
+_minted-*
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/DEPS
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/DEPS	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/DEPS	(revision 11422)
@@ -0,0 +1,58 @@
+amsmath
+babel
+caption
+capt-of
+carlisle
+cmap
+courier
+draftwatermark
+ec
+enumitem
+epstopdf
+etoolbox
+everypage
+fancyhdr
+fancyvrb
+float
+fncychap
+framed
+fvextra
+geometry
+graphics
+graphics-cfg
+helvetic
+hyperref
+ifplatform
+imakeidx
+koma-script
+latex
+latexconfig
+latex-bin
+latex-fonts
+latexmk
+lineno
+lm
+marvosym
+minitoc
+minted
+natbib
+needspace
+oberdiek
+parskip
+preview
+psnfss
+subfiles
+tabulary
+times
+titlesec
+titling
+tools
+upquote
+url
+varwidth
+wrapfig
+xcolor
+xkeyval
+xstring
+zapfchan
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/HTML_latex2html.sh
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/HTML_latex2html.sh	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/HTML_latex2html.sh	(revision 11422)
@@ -1,20 +1,27 @@
 #!/bin/bash
 
-./inc/clean.sh
-./inc/build.sh
+#./inc/clean.sh
+#./inc/build.sh
 
-cd tex_main
-sed -i -e 's#\\documentclass#%\\documentclass#' -e '/{document}/ s/^/%/' \
-	../tex_sub/*.tex
-sed -i    's#\\subfile{#\\include{#g' \
-	NEMO_manual.tex
-latex2html -local_icons -no_footnode -split 4 -link 2 -mkdir -dir ../html_LaTeX2HTML 	\
-				$* 																								\
-	NEMO_manual
-sed -i -e 's#%\\documentclass#\\documentclass#' -e '/{document}/ s/^%//' \
-	../tex_sub/*.tex
-sed -i    's#\\include{#\\subfile{#g' \
-	NEMO_manual.tex
+sed -i -e 's#utf8#latin1#'                                 \
+       -e 's#\[outputdir=../build\]{minted}#\[\]{minted}#' \
+       -e '/graphicspath/ s#{../#{../../#g'                \
+          global/packages.tex
+
+cd ./NEMO/main
+sed -i -e 's#\\documentclass#%\\documentclass#' -e '/{document}/ s#^#%#'   ../subfiles/*.tex
+sed -i    's#\\subfile{#\\input{#'                                         chapters.tex appendices.tex
+
+#latex2html                                   -noimages -local_icons -no_footnode -split 4 -link 2 -dir ../html_LaTeX2HTML $*	NEMO_manual
+latex2html -debug -noreuse -init_file ../../l2hconf.pm -local_icons                               -dir ../build/html               NEMO_manual
+
+sed -i -e 's#%\\documentclass#\\documentclass#' -e '/{document}/ s#^%##'   ../subfiles/*.tex
+sed -i    's#\\input{#\\subfile{#'                                         chapters.tex appendices.tex
 cd -
 
+sed -i -e 's#latin1#utf8#'                                 \
+       -e 's#\[\]{minted}#\[outputdir=../build\]{minted}#' \
+       -e '/graphicspath/ s#{../../#{../#g'                \
+	  global/packages.tex
+
 exit 0
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/NEMO_coding_conv.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/NEMO_coding_conv.tex	(revision 10999)
+++ 	(revision )
@@ -1,807 +1,0 @@
-\documentclass{article}
-
-\usepackage{fancyhdr}
-\usepackage{times}
-\usepackage{graphicx}
-\usepackage{hyperref}
-\usepackage{minted}
-%\usepackage[normalem]{ulem}   % striketrough style with \sout{...}
-
-\hypersetup{pdftitle={NEMO coding conventions}, pdfauthor={NEMO System Team}, colorlinks}
-\setminted{style=emacs, breaklines, frame=leftline}
-\newmintinline[forcode]{fortran}{fontsize=auto, frame=lines}   % \forcode{...}
-\newminted[forlines]{fortran}{}                                % \begin{forlines}
-
-\pagestyle{empty}
-\setlength{\leftmargin}{1 cm}
-\setlength{\rightmargin}{1 cm}
-\setlength{\oddsidemargin}{0 cm}
-\setlength{\evensidemargin}{0 cm}
-\setlength{\topmargin}{-1cm}
-\setlength{\textwidth}{16 cm}
-\setlength{\textheight}{25cm}
-\pagestyle{fancy}
-
-\title{
-  \includegraphics[width=0.3\textwidth]{../../../figures/NEMO_grey} \\
-  \vspace{1.0cm} \rule{345pt}{1.5pt} \\
-  \vspace{0.45cm} {\Huge NEMO coding conventions} \rule{345pt}{1.5pt} \\
-}
-%\title{NEMO coding conventions}
-\author{\Large NEMO System Team
-  \thanks{
-    To be completed
-  }
-}
-\date{version X.X -- month year}
-
-\begin{document}
-
-\maketitle
-
-\newpage
-
-\tableofcontents
-
-\newpage
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Introduction}
-
-This document describes conventions\index{conventions} used in NEMO coding and suggested for its development.
-The objectives are to offer a guide to all readers of the NEMO code, and to facilitate the work of
-all the developers, including the validation of their developments, and
-eventually the implementation of these developments within the NEMO platform.
-
-A first approach of these rules can be found in the code in \path{./src/OCE/module_example} where
-all the basics coding conventions are illustrated.
-More details can be found below.
-
-This work is based on the coding conventions in use for the Community Climate System Model
-\footnote {\href{http://www.cesm.ucar.edu/working_groups/Software/dev_guide/dev_guide/node7.html}{UCAR conventions}}, 
-the previous version of this document (``FORTRAN coding standard in the OPA System'') and
-the expertise of the NEMO System Team.
-After a general overview below, this document will describe:
-
-\begin{itemize}
-\item
-  The style rules, $i.e.$ the syntax, appearance and naming conventions chosen to improve readability of the code;
-\item
-  The content rules, $i.e.$ the conventions to improve the reliability of the different parts of the code;
-\item
-  The package rules to go a step further by improving the reliability of the whole and
-  interfaces between routines and modules.
-\end{itemize}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Overview and general conventions}
-
-NEMO has 3 major components: ocean dynamics (\path{./src/OCE}), sea-ice (\path{./src/ICE}) and
-marine biogeochemistry (\path{./src/MBG}).
-%, linear-tangent and adjoint of the dynamics ($TAM$) each of them corresponding to a directory.
-In each directory, one will find some FORTRAN files and/or subdirectories, one per functionality of the code:
-\path{./src/OCE/BDY} (boundaries), \path{./src/OCE/DIA} (diagnostics), \path{./src/OCE/DOM} (domain),
-\path{./src/OCE/DYN} (dynamics), \path{./src/OCE/LDF} (lateral diffusion), etc... \\
-All name are chosen to be as self-explanatory as possible, in English, all prefixes are 3 digits. \\
-English is used for all variables names, comments, and documentation. \\
-Physical units are MKS. The only exception to this is the temperature, which is expressed in degrees Celsius,
-except in bulk formulae and part of SI$^3$ sea-ice model where it is in Kelvin.
-See \path{.src/OCE/DOM/phycst.F90} files for conversions.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Architecture}
-
-Within each directory, organisation of files is driven by orthogonality\index{orthogonality},
-$i.e.$ one functionality of the code is intended to be in one and only one directory, and
-one module and all its related routines are in one file.
-The functional modules\index{module} are:
-
-\begin{itemize}
-\item \path{SBC}             surface module
-\item \path{IOM}             management of the I/O
-\item \path{NST}             interface to AGRIF (nesting model) for dynamics and biogeochemistry
-\item \path{OBC}, \path{BDY} management of structured and unstructured open boundaries 
-\item \path{C1D}             1D (vertical) configuration for dynamics, sea-ice and biogeochemistry
-\item \path{OFF}             off-line module: passive tracer or biogeochemistry alone
-\item \path{...}
-\end{itemize}
-
-For example, the file \textit{domain.F90} contains the module \texttt{domain} and all the subroutines related to
-this module (\texttt{dom\_init, dom\_nam, dom\_ctl}).
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Style rules}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Argument list format}
-
-Routine argument lists will contain a maximum 5 variables\index{variable} per line,
-whilst continuation lines can be used.
-This applies both to the calling routine and the dummy argument list in the routine being called.
-The purpose is to simplify matching up the arguments between caller and callee.
-
-\begin{forlines}
-SUBROUTINE tra_adv_eiv( kt, pun, pvn, pwn )
-
-      CALL tra_adv_eiv( kt, zun, zvn, zwn )
-\end{forlines}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Array syntax}
-
-Except for long loops (see below), array notation should be used if possible.
-To improve readability the array shape must be shown in brackets, $e.g.$:
-
-\begin{forlines}
-onedarraya(:)   = onedarrayb(:) + onedarrayc(:)
-twodarray (:,:) = scalar * anothertwodarray(:,:)
-\end{forlines}
-
-When accessing sections of arrays, for example in finite difference equations,
-do so by using the triplet notation on the full array, $e.g.$:
-
-\begin{forlines}
-twodarray(:,2:len2) =   scalar                      &
-   &                  * ( twodarray2(:,1:len2-1 )   &
-   &                  -   twodarray2(:,2:len2 ) )
-\end{forlines}
-
-For long, complicated loops, explicitly indexed loops should be preferred.
-In general when using this syntax, the order of the loops indices should reflect the following scheme
-(for best usage of data locality):
-
-\begin{forlines}
-DO jk = 1, jpk
-   DO jj = 1, jpj
-      DO ji = 1, jpi
-         threedarray(ji,jj,jk) = ...
-      END DO
-   END DO
-END DO
-\end{forlines}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Case}
-
-All FORTRAN keywords are in capital: \forcode{DIMENSION}, \forcode{WRITE}, \forcode{DO}, \forcode{END DO},
-\forcode{NAMELIST}, ... All other parts of the NEMO code will be written in lower case.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Comments}
-
-Comments in the code are useful when reading the code and changing or developing it. \\
-The full documentation and detailed explanations are to be added in the reference manual
-(TeX files, aside from the code itself). \\
-In the code, the comments should explain variable content and describe each computational step. \\
-Comments in the header start with ``!!''.
-For more details on the content of the headers, see Content rules/Headers in this document. \\
-Comments in the code start with ``!''. \\
-All comments are indented (3, 6, or 9 blank spaces). \\
-Short comments may be included on the same line as executable code, and an additional line can be used with
-proper alignment.
-For example:
-
-\begin{forlines}
-zx = zx *zzy   ! Describe what is going on and if it is
-!              ! too long use another ! for proper
-!              ! alignment with automatic indentation
-\end{forlines}
-
-More in-depth comments should be written in the form:
-
-\begin{forlines}
-   !  Check of some namelist values
-\end{forlines}
-
-or
-
-\begin{forlines}
-!
-!     !<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
-!     !  Bottom boundary condition on tke
-!     !<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
-!
-\end{forlines}
-
-Key features of this style are
-
-\begin{enumerate}
-\item it starts with a "!" in the column required for proper indentation,
-\item the text is offset above and below by a blank line or a content line built for underlying.
-\end{enumerate}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Continuation lines}
-
-Continuation lines can be used with precise alignment for readability. For example:
-
-\begin{forlines}
-avmu(ji,jj,jk) =   avmu(ji,jj,jk) * ( un(ji,jj,jk-1) - un(ji,jj,jk) )   &
-   &                              * ( ub(ji,jj,jk-1) - ub(ji,jj,jk) )   &
-   &             / (   fse3uw_n(ji,jj,jk)                               &
-   &                 * fse3uw_b(ji,jj,jk) )
-\end{forlines}
-
-Code lines, which are continuation lines of assignment statements, must begin to the right of the column of
-the assignment operator.
-Due to the possibility of automatic indentation in some editor (emacs for example),
-use a ``\&'' as first character of the continuing lines to maintain the alignment.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Declaration of arguments and local variables}
-
-In a routine, input arguments and local variables are declared 1 per line,
-with a comment field on the same line as the declaration.
-Multiple comment lines describing a single variable are acceptable if needed.
-For example:
-
-\begin{forlines}
-INTEGER             ::   kstp   ! ocean time-step index
-\end{forlines}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{F90 Standard}
-
-NEMO software adheres to the FORTRAN 95 language standard and does not rely on any specific language or
-vendor extensions.
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Free-Form Source}
-
-Free-form source will be used.
-The F90/95 standard allows lines of up to 132 characters, but a self-imposed limit of 80 should enhance readability,
-or print source files with two columns per page.
-Multi-line comments that extend to column 100 are unacceptable.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Indentation}
-
-Code as well as comment lines within loops, if-blocks, continuation lines, \forcode{MODULE} or
-\forcode{SUBROUTINE} statements will be indented 3 characters for readability
-(except for \forcode{CONTAINS} that remains at first column).
-
-\begin{forlines}
-MODULE mod1
-   REAL(wp) xx
-CONTAINS
-   SUBROUTINE sub76( px, py, pz, pw, pa,   &
-      &              pb, pc, pd, pe          )
-      <instruction>
-   END SUBROUTINE sub76
-END MODULE mod1
-\end{forlines}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Loops}
-
-Loops, if explicit, should be structured with the do-end do construct as opposed to numbered loops.
-Nevertheless non-numeric labels can be used for a big iterative loop of a recursive algorithm.
-In the case of a long loop, a self-descriptive label can be used ($i.e.$ not just a number).
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Naming Conventions: files}
-
-A file containing a module will have the same name as the module it contains
-(because dependency rules used by "make" programs are based on file names).
-\footnote{
-  For example, if routine A "\forcode{USE}"s module B, then "make" must be told of the dependency relation which
-  requires B to be compiled before A.
-  If one can assume that module B resides in file B.o,
-  building a tool to generate this dependency rule ($e.g.$ A.o: B.o) is quite simple.
-  Put another way, it is difficult (to say nothing of CPU-intensive) to search an entire source tree to
-  find the file in which module B resides for each routine or module which "\forcode{USE}"s B.
-}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Naming Conventions: modules}
-
-Use a meaningful English name and the ``3 letters'' naming convention:
-first 3 letters for the code section, and last 3 to describe the module.
-For example, zdftke, where ``zdf'' stands for vertical diffusion, and ``tke'' for turbulent kinetic energy. \\
-Note that by implication multiple modules are not allowed in a single file.
-The use of common blocks is deprecated in Fortran 90 and their use in NEMO is strongly discouraged.
-Modules are a better way to declare static data.
-Among the advantages of modules is the ability to freely mix data of various types, and
-to limit access to contained variables through the use of the \forcode{ONLY} and \forcode{PRIVATE} attributes.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Naming Conventions: variables}
-
-All variable should be named as explicitly as possible in English.
-The naming convention concerns prefix letters of these name, in order to identify the variable type and status. \\
-Never use a FORTRAN keyword as a routine or variable name. \\
-The table below lists the starting letter(s) to be used for variable naming, depending on their type and status:
-%--------------------------------------------------TABLE--------------------------------------------------
-\begin{table}[htbp]
-  \begin{center}
-    \begin{tabular}{|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|}
-      \hline
-      Type \par / Status &   integer&   real&   logical &   character&   double \par precision&   complex \\
-      \hline
-      public  \par or  \par module variable& \textbf{m n} \par \textit{but not } \par \textbf{nn\_}& \textbf{a b e f g h o} \textbf{q} \textit{to} \textbf{x} \par but not \par \textbf{fs rn\_}& \textbf{l} \par \textit{but not} \par \textbf{lp ld ll ln\_}& \textbf{c} \par \textit{but not} \par \textbf{cp cd cl cn\_}& \textbf{d} \par \textit{but not} \par \textbf{dp dd dl dn\_}& \textbf{y} \par \textit{but not} \par \textbf{yp yd yl} \\
-      \hline
-      dummy \par argument& \textbf{k} \par \textit{but not} \par \textbf{kf}& \textbf{p} \par \textit{but not}  \par \textbf{pp pf}& \textbf{ld}& \textbf{cd}& \textbf{dd}& \textbf{yd} \\
-      \hline
-      local \par variable& \textbf{i}& \textbf{z}& \textbf{ll}& \textbf{cl}& \textbf{cd}& \textbf{yl} \\
-      \hline
-      loop \par control& \textbf{j} \par \textit{but not } \par \textbf{jp}& & & & &  \\
-      \hline
-      parameter& \textbf{jp}& \textbf{pp}& \textbf{lp}& \textbf{cp}& \textbf{dp}& \textbf{yp} \\
-      \hline
-      namelist& \textbf{nn\_}& \textbf{rn\_}& \textbf{ln\_}& \textbf{cn\_}& \textbf{dn\_}& \\
-      \hline
-      CPP \par macro& \textbf{kf}& \textbf{sf} \par & & & & \\
-      \hline
-    \end{tabular}
-    \label{tab1}
-  \end{center}
-\end{table}
-%--------------------------------------------------------------------------------------------------------------
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Operators}
-
-Use of the operators \texttt{<, >, <=, >=, ==, /=} is strongly recommended instead of their deprecated counterparts
-(\texttt{.lt., .gt., .le., .ge., .eq., .ne.}).
-The motivation is readability.
-In general use the notation: \\
-$<Blank><Operator><Blank>$
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Pre processor}
-
-Where the use of a language pre-processor is required, it will be the C pre-processor (cpp). \\
-The cpp key is the main feature used, allowing to ignore some useless parts of the code at compilation step. \\
-The advantage is to reduce the memory use; the drawback is that compilation of this part of the code isn't checked. \\
-The cpp key feature should only be used for a few limited options, if it reduces the memory usage.
-In all cases, a logical variable and a FORTRAN \forcode{IF} should be preferred.
-When using a cpp key \textit{key\_optionname},
-a corresponding logical variable \textit{lk\_optionname} should be declared to
-allow FORTRAN \forcode{IF} tests in the code and
-a FORTRAN module with the same name ($i.e.$ \textit{optionname.F90}) should be defined.
-This module is the only place where a \``\#if defined'' command appears, selecting either the whole FORTRAN code or
-a dummy module.
-For example, the TKE vertical physics, the module name is \textit{zdftke.F90},
-the CPP key is \textit{key\_zdftke} and the associated logical is \textit{lk\_zdftke}.
-
-The following syntax:
-
-\begin{forlines}
-#if defined key_optionname
-!! Part of code conditionally compiled if cpp key key_optionname is active
-#endif
-\end{forlines}
-
-Is to be used rather than the \#ifdef abbreviate form since it may have conflicts with some Unix scripts.
-
-Tests on cpp keys included in NEMO at compilation step:
-
-\begin{itemize}
-\item
-  The CPP keys used are compared to the previous list of cpp keys
-  (the compilation will stop if trying to specify a non-existing key)
-\item
-  If a change occurs in the CPP keys used for a given experiment, the whole compilation phase is done again.
-\end{itemize}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Content rules}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Configurations}
-
-The configuration defines the domain and the grid on which NEMO is running.
-It may be useful to associate a cpp key and some variables to a given configuration, although
-the part of the code changed under each of those keys should be minimized.
-As an example, the "ORCA2" configuration (global ocean, 2 degrees grid size) is associated with
-the cpp key \texttt{key\_orca2} for which
-
-\begin{forlines}
-cp_cfg = "orca"
-jp_cfg = 2
-\end{forlines}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Constants}
-
-Physical constants ($e.g.$ $\pi$, gas constants) must never be hardwired into the executable portion of a code.
-Instead, a mnemonically named variable or parameter should be set to the appropriate value,
-in the setup routine for the package\index{package}.
-We realize than many parameterizations rely on empirically derived constants or fudge factors,
-which are not easy to name.
-In these cases it is not forbidden to leave such factors coded as "magic numbers" buried in executable code, but
-comments should be included referring to the source of the empirical formula.
-Hard-coded numbers should never be passed through argument lists.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Declaration for variables and constants}
-
-\subsubsection{Rules}
-
-Variables used as constants should be declared with attribute \forcode{PARAMETER} and
-used always without copying to local variables, in order to
-prevent from using different values for the same constant or changing it accidentally.
-
-\begin{itemize}
-\item
-  Usage of the \forcode{DIMENSION} statement or attribute is required in declaration statements
-\item
-  The ``::'' notation is quite useful to show that this program unit declaration part is written in
-  standard FORTRAN syntax, even if there are no attributes to clarify the declaration section.
-  Always use the notation $<$blank$>$::$<$three blanks$>$ to improve readability.
-\item
-  Declare the length of a character variable using the \forcode{CHARACTER} (len=xxx) syntax
-  \footnote {
-    The len specifier is important because it is possible to have several kinds for characters
-    ($e.g.$ Unicode using two bytes per character, or there might be a different kind for Japanese $e.g.$ NEC).
-  }
-\item
-  For all global data (in contrast to module data, that is all data that can be access by other module)
-  must be accompanied with a comment field on the same line
-  \footnote {
-    This allows a easy research of where and how a variable is declared using the unix command:
-    ``grep var *90 | grep !:''.
-  }.
-  For example:
-  \begin{forlines}
-  REAL(wp), DIMENSION(jpi,jpj,jpk) ::  ua   ! i-horizontal velocity (m/s)
-  \end{forlines}
-\end{itemize}
-
-\subsubsection{Implicit None}
-
-All subroutines and functions will include an \forcode{IMPLICIT NONE} statement.
-Thus all variables must be explicitly typed.
-It also allows the compiler to detect typographical errors in variable names.
-For modules, one \forcode{IMPLICIT NONE} statement in the modules definition section is needed.
-This also removes the need to have \forcode{IMPLICIT NONE} statements in
-any routines that are \forcode{CONTAINS}'ed in the module.
-Improper data initialisation is another common source of errors
-\footnote{
-  A variable could contain an initial value you did not expect.
-  This can happen for several reasons, $e.g.$ the variable has never been assigned a value, its value is outdated,
-  memory has been allocated for a pointer but you have forgotten to initialise the variable pointed to.
-}.
-To avoid problems, initialise variables as close as possible to where they are first used.
-
-\subsubsection{Attributes}
-
-\forcode{PRIVATE} / \forcode{PUBLIC}:
-All resources of a module are \forcode{PUBLIC} by default.
-A reason to store multiple routines and their data in a single module is that
-the scope of the data defined in the module can be limited to the routines which are in the same module.
-This is accomplished with the \forcode{PRIVATE} attribute. \\
-\forcode{INTENT}:
-All dummy arguments of a routine must include the \forcode{INTENT} clause in their declaration in order to
-improve control of variables in routine calls.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Headers}
-
-Prologues are not used in NEMO for now, although it may become an interesting tool in combination with
-ProTeX auto documentation script in the future.
-Rules to code the headers and layout of a module or a routine are illustrated in the example module available with
-the code: \path{./src/OCE/module_example}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Interface blocks}
-
-Explicit interface blocks are required between routines if optional or keyword arguments are to be used.
-They also allow the compiler to check that the type, shape and number of arguments specified in the \forcode{CALL}
-are the same as those specified in the subprogram itself.
-FORTRAN 95 compilers can automatically provide explicit interface blocks for routines contained in a module.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{I/O Error Conditions}
-
-I/O statements which need to check an error condition will use the \texttt{iostat=<integer variable>} construct
-instead of the outmoded \texttt{end=} and \forcode{err=}. \\
-Note that a 0 value means success, a positive value means an error has occurred, and
-a negative value means the end of record or end of file was encountered.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{PRINT - ASCII output files}
-
-Output listing and errors are directed to \texttt{numout} logical unit =6 and
-produces a file called \textit{ocean.output} (use \texttt{ln\_prt} to have one output per process in MPP).
-Logical \texttt{lwp} variable allows for less verbose outputs.
-To output an error from a routine, one can use the following template:
-
-\begin{forlines}
-IF( nstop /= 0 .AND. lwp ) THEN   ! error print
-   WRITE(numout,cform_err)
-   WRITE(numout,*) nstop, ' error have been found'
-ENDIF
-\end{forlines}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Precision}
-
-Parameterizations should not rely on vendor-supplied flags to supply a default floating point precision or
-integer size.
-The F95 \forcode{KIND} feature should be used instead.
-In order to improve portability between 32 and 64 bit platforms,
-it is necessary to make use of kinds by using a specific module \path{./src/OCE/par_kind.F90}
-declaring the "kind definitions" to obtain the required numerical precision and range as well as
-the size of \forcode{INTEGER}.
-It should be noted that numerical constants need to have a suffix of \texttt{\_kindvalue} to
-have the according size. \\
-Thus \forcode{wp} being the "working precision" as declared in \path{./src/OCE/par_kind.F90},
-declaring real array \forcode{zpc} will take the form:
-
-\begin{forlines}
-REAL(wp), DIMENSION(jpi,jpj,jpk) ::  zpc      ! power consumption
-\end{forlines}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Structures}
-
-The \forcode{TYPE} structure allowing to declare some variables is more often used in NEMO,
-especially in the modules dealing with reading fields, or interfaces.
-For example:
-
-\begin{forlines}
-! Definition of a tracer as a structure
-TYPE PTRACER
-   CHARACTER(len = 20)  :: sname  ! short name
-   CHARACTER(len = 80 ) :: lname  ! long name
-   CHARACTER(len = 20 ) :: unit   ! unit
-   LOGICAL              :: lini   ! read in a file or not
-   LOGICAL              :: lsav   ! ouput the tracer or not
-END TYPE PTRACER
-
-TYPE(PTRACER) , DIMENSION(jptra) :: tracer
-\end{forlines}
-
-Missing rule on structure name??
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Packages coding rules}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Bounds checking}
-
-NEMO is able to run when an array bounds checking option is enabled
-(provided the cpp key \texttt{key\_vectopt\_loop} is not defined). \\
-Thus, constructs of the following form are disallowed:
-
-\begin{forlines}
-REAL(wp) :: arr(1)
-\end{forlines}
-
-where "arr" is an input argument into which the user wishes to index beyond 1.
-Use of the (*) construct in array dimensioning is forbidden also because
-it effectively disables array bounds checking.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Communication}
-
-A package should refer only to its own modules and subprograms and to those intrinsic functions included in
-the Fortran standard. \\
-All communication with the package will be through the argument list or namelist input.
-\footnote{
-  The point behind this rule is that packages should not have to know details of
-  the surrounding model data structures, or the names of variables outside of the package.
-  A notable exception to this rule is model resolution parameters.
-  The reason for the exception is to allow compile-time array sizing inside the package.
-  This is often important for efficiency.
-}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Error conditions}
-
-When an error condition occurs inside a package, a message describing what went wrong will be printed
-(see PRINT - ASCII output files).
-The name of the routine in which the error occurred must be included.
-It is acceptable to terminate execution within a package, but
-the developer may instead wish to return an error flag through the argument list,
-see \textit{stpctl.F90}.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Memory management}
-
-The main action is to identify and declare which arrays are \forcode{PUBLIC} and which are \forcode{PRIVATE}. \\
-As of version 3.3.1 of NEMO, the use of static arrays (size fixed at compile time) has been deprecated.
-All module arrays are now declared \forcode{ALLOCATABLE} and
-allocated in either the \texttt{<module\_name>\_alloc()} or \texttt{<module\_name>\_init()} routines.
-The success or otherwise of each \forcode{ALLOCATE} must be checked using
-the \texttt{stat=<integer\ variable>} optional argument. \\
-
-In addition to arrays contained within modules, many routines in NEMO require local, ``workspace'' arrays to
-hold the intermediate results of calculations.
-In previous versions of NEMO, these arrays were declared in such a way as to be automatically allocated on
-the stack when the routine was called.
-An example of an automatic array is:
-
-\begin{forlines}
-SUBROUTINE sub(n)
-   REAL :: a(n)
-   ...
-END SUBROUTINE sub
-\end{forlines}
-
-The downside of this approach is that the program will crash if it runs out of stack space and
-the reason for the crash might not be obvious to the user.
-
-Therefore, as of version 3.3.1, the use of automatic arrays is deprecated.
-Instead, a new module, \textit{wrk\_nemo.F90}, has been introduced which
-contains 1-,2-,3- and 4-dimensional workspace arrays for use in subroutines.
-These workspace arrays should be used in preference to declaring new, local (allocatable) arrays whenever possible.
-The only exceptions to this are when workspace arrays with lower bounds other than 1 and/or
-with extent(s) greater than those in the \textit{wrk\_nemo.F90} module are required. \\
-
-The 2D, 3D and 4D workspace arrays in \textit{wrk\_nemo.F90} have extents \texttt{jpi}, \texttt{jpj},
-\texttt{jpk} and \texttt{jpts} ($x$, $y$, $z$ and tracers) in the first, second, third and fourth dimensions,
-respectively.
-The 1D arrays are allocated with extent MAX($jpi \times jpj, jpk \times jpj, jpi \times jpk$). \\
-
-The \forcode{REAL (KIND = wp)} workspace arrays in \textit{wrk\_nemo.F90}
-are named $e.g.$ \texttt{wrk\_1d\_1, wrk\_4d\_2} etc. and
-should be accessed by USE'ing the \textit{wrk\_nemo.F90} module.
-Since these arrays are available to any routine,
-some care must be taken that a given workspace array is not already being used somewhere up the call stack.
-To help with this, \textit{wrk\_nemo.F90} also contains some utility routines;
-\texttt{wrk\_in\_use()} and \texttt{wrk\_not\_released()}.
-The former first checks that the requested arrays are not already in use and then sets internal flags to show that
-they are now in use.
-The \texttt{wrk\_not\_released()} routine un-sets those internal flags.
-A subroutine using this functionality for two, 3D workspace arrays named \texttt{zwrk1} and
-\texttt{zwrk2} will look something like:
-
-\begin{forlines}
-SUBROUTINE sub()
-   USE wrk_nemo, ONLY: wrk_in_use, wrk_not_released
-   USE wrk_nemo, ONLY: zwrk1 => wrk_3d_5, zwrk2 => wrk_3d_6
-   !
-   IF(wrk_in_use(3, 5,6)THEN
-      CALL ctl_stop('sub: requested workspace arrays unavailable.')
-      RETURN
-   END IF
-   ...
-   ...
-   IF(wrk_not_released(3, 5,6)THEN
-      CALL ctl_stop('sub: failed to release workspace arrays.')
-   END IF
-   !
-END SUBROUTINE sub
-\end{forlines}
-
-The first argument to each of the utility routines is the dimensionality of the required workspace (1--4).
-Following this there must be one or more integers identifying which workspaces are to be used/released.
-Note that, in the interests of keeping the code as simple as possible,
-there is no use of \forcode{POINTER}s etc. in the \textit{wrk\_nemo.F90} module.
-Therefore it is the responsibility of the developer to ensure that the arguments to \texttt{wrk\_in\_use()} and
-\texttt{wrk\_not\_released()} match the workspace arrays actually being used by the subroutine. \\
-
-If a workspace array is required that has extent(s) less than those of the arrays in
-the \textit{wrk\_nemo.F90} module then the advantages of implicit loops and bounds checking may be retained by
-defining a pointer to a sub-array as follows:
-
-\begin{forlines}
-SUBROUTINE sub()
-   USE wrk_nemo, ONLY: wrk_in_use, wrk_not_released
-   USE wrk_nemo, ONLY: wrk_3d_5
-   !
-   REAL(wp), DIMENSION(:,:,:), POINTER :: zwrk1
-   !
-   IF(wrk_in_use(3, 5)THEN
-      CALL ctl_stop('sub: requested workspace arrays unavailable.')
-      RETURN
-   END IF
-   !
-   zwrk1 => wrk_3d_5(1:10,1:10,1:10)
-   ...
-END SUBROUTINE sub
-\end{forlines}
-
-Here, instead of ``use associating'' the variable \texttt{zwrk1} with the array \texttt{wrk\_3d\_5}
-(as in the first example), it is explicitly declared as a pointer to a 3D array.
-It is then associated with a sub-array of \texttt{wrk\_3d\_5} once the call to
-\texttt{wrk\_in\_use()} has completed successfully.
-Note that in F95 (to which NEMO conforms) it is not possible for either the upper or lower array bounds of
-the pointer object to differ from those of the target array. \\
-
-In addition to the \forcode{REAL (KIND = wp)} workspace arrays,
-\textit{wrk\_nemo.F90} also contains 2D integer arrays and 2D REAL arrays with extent (\texttt{jpi}, \texttt{jpk}),
-$i.e.$ $xz$.
-The utility routines for the integer workspaces are \texttt{iwrk\_in\_use()} and \texttt{iwrk\_not\_released()} while
-those for the $xz$ workspaces are \texttt{wrk\_in\_use\_xz()} and \texttt{wrk\_not\_released\_xz()}.
-
-Should a call to one of the \texttt{wrk\_in\_use()} family of utilities fail,
-an error message is printed along with a table showing which of the workspace arrays are currently in use.
-This should enable the developer to choose alternatives for use in the subroutine being worked on. \\
-
-When compiling NEMO for production runs,
-the calls to {\texttt{wrk\_in\_use()} / \texttt{wrk\_not\_released()} can be reduced to stubs that just
-return \forcode{.false.} by setting the cpp key \texttt{key\_no\_workspace\_check}.
-These stubs may then be inlined (and thus effectively removed altogether) by setting appropriate compiler flags
-($e.g.$ ``-finline'' for the Intel compiler or ``-Q'' for the IBM compiler).
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Optimisation}
-
-Considering the new computer architecture, optimisation cannot be considered independently from the computer type.
-In NEMO, portability is a priority, before any too specific optimisation.
-
-Some tools are available to help: for vector computers, \texttt{key\_vectopt\_loop} allows to unroll a loop
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Package attribute: \forcode{PRIVATE}, \forcode{PUBLIC}, \forcode{USE}, \forcode{ONLY}}
-
-Module variables and routines should be encapsulated by using the \forcode{PRIVATE} attribute.
-What shall be used outside the module can be declared \forcode{PUBLIC} instead.
-Use \forcode{USE} with the \forcode{ONLY} attribute to specify which of the variables, type definitions etc...
-defined in a module are to be made available to the using routine.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection {Parallelism using MPI}
-
-NEMO is written in order to be able to run on one processor, or on one or more using MPI
-($i.e.$ activating the cpp key $key\_mpp\_mpi$).
-The domain decomposition divides the global domain in cubes (see NEMO reference manual).
-Whilst coding a new development, the MPI compatibility has to be taken in account
-(see \path{./src/LBC/lib_mpp.F90}) and should be tested.
-By default, the $x$-$z$ part of the decomposition is chosen to be as square as possible.
-However, this may be overriden by specifying the number of subdomains in latitude and longitude in
-the \texttt{nammpp} section of the namelist file.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Features to be avoided}
-
-The code must follow the current standards of FORTRAN and ANSI C.
-In particular, the code should not produce any WARNING at compiling phase, so that
-users can be easily alerted of potential bugs when some appear in their new developments.
-Below is a list of features to avoid:
-\begin{itemize}
-\item
-  \forcode{COMMON} block
-  (use the declaration part of \forcode{MODULE} instead)
-\item
-  \forcode{EQUIVALENCE}
-  (use \forcode{POINTER} or derived data type instead to form data structure)
-\item
-  Assigned and computed \forcode{GOTO}
-  (use the \forcode{CASE} construct instead)
-\item
-  Arithmetic \forcode{IF} statement
-  (use the block \forcode{IF}, \forcode{ELSE}, \forcode{ELSEIF}, \forcode{ENDIF} or
-  \forcode{SELECT CASE} construct instead)
-\item
-  Labeled \forcode{DO} construct
-  (use unlabeled \forcode{END DO} instead)
-\item
-  \forcode{FORMAT} statement
-  (use character parameters or
-  explicit format- specifiers inside the \forcode{READ} or \forcode{WRITE} statement instead)
-\item
-  \forcode{GOTO} and \forcode{CONTINUE} statements
-  (use \forcode{IF}, \forcode{CASE}, \forcode{DO WHILE}, \forcode{EXIT} or \forcode{CYCLE} statements or
-  a contained ?)
-\item
-  \forcode{PAUSE}
-\item
-  \forcode{ENTRY} statement: a subprogram must only have one entry point.
-\item
-  \forcode{RETURN} is obsolete and so not necessary at the end of program units
-\item
-  \forcode{FUNCTION} statement
-\item
-  Avoid functions with side effects.
-  \footnote{
-    First, the code is easier to understand, if you can rely on
-    the rule that functions don't change their arguments.
-    Second, some compilers generate more efficient code for PURE functions
-    (in FORTRAN 95 there are the attributes PURE and ELEMENTAL), because
-    they can store the arguments in different places.
-    This is especially important on massive parallel and as well on vector machines.
-  }
-\item
-  \forcode{DATA} and \forcode{BLOCK DATA}
-  (use initialisers)
-\end{itemize}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-% \printindex
-% \input NEMO_coding.conv.ind
-
-\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/NEMO_manual.bib
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/NEMO_manual.bib	(revision 10999)
+++ 	(revision )
@@ -1,3913 +1,0 @@
-@STRING{AP = {Academic Press}}
-
-@STRING{AREPS = {Annual Review of Earth Planetary Science}}
-
-@STRING{ARFM = {Annual Review of Fluid Mechanics}}
-
-@STRING{ASL = {Atmospheric Science Letters}}
-
-@STRING{AW = {Addison-Wesley}}
-
-@STRING{CP = {Clarendon Press}}
-
-@STRING{CD = {Clim. Dyn.}}
-
-@STRING{CUP = {Cambridge University Press}}
-
-@STRING{CSR = {Cont. Shelf Res.}}
-
-@STRING{D = {Dover Publications}}
-
-@STRING{DAO = {Dyn. Atmos. Ocean}}
-
-@STRING{DSR = {Deep-Sea Res.}}
-
-@STRING{E = {Eyrolles}}
-
-@STRING{EFM ={Environ. Fluid Mech.}}
-
-@STRING{GRL = {Geophys. Res. Let.}}
-
-@STRING{I = {Interscience}}
-
-@STRING{JAOT = {J. Atmos. Ocean Tech.}}
-
-@STRING{JAS = {J. Atmos. Sc.}}
-
-@STRING{JC = {J. Climate}}
-
-@STRING{JCP = {J. Comput. Phys.}}
-
-@STRING{JFM = {J. Fluid Mech.}}
-
-@STRING{JGR = {J. Geophys. Res}}
-
-@STRING{JHUP = {The Johns Hopkins University Press}}
-
-@STRING{JMR = {J. Mar. Res.}}
-
-@STRING{JMS = {J. Mar. Sys.}}
-
-@STRING{JMSJ = {J. Met. Soc. Japan}}
-
-@STRING{JPO = {J. Phys. Oceanogr.}}
-
-@STRING{JSC = {J. Supercomputing.}}
-
-@STRING{JWS = {John Wiley and Sons}}
-
-@STRING{M = {Macmillan}}
-
-@STRING{MGH = {McGraw-Hill}}
-
-@STRING{MWR = {Mon. Wea. Rev.}}
-
-@STRING{Nature = {Nat.}}
-
-@STRING{NH = {North-Holland}}
-
-@STRING{Ocean = {Oceanology}}
-
-@STRING{OD = {Ocean Dyn.}}
-
-@STRING{OM = {Ocean Modelling}}
-
-@STRING{OS = {Ocean Sc.}}
-
-@STRING{OUP = {Oxford University Press}}
-
-@STRING{PH = {Prentice-Hall}}
-
-@STRING{PO = {Prog. Oceangr.}}
-
-@STRING{PP = {Pergamon Press}}
-
-@STRING{PRSL = {Proceedings of the Royal Society of London}}
-
-@STRING{QJRMS = {Quart. J. Roy. Meteor. Soc.}}
-
-@STRING{Recherche = {La Recherche}}
-
-@STRING{RGSP = {Rev. Geophys. Space Phys.}}
-
-@STRING{Science = {Science}}
-
-@STRING{SV = {Springer-Verlag}}
-
-@STRING{Tellus = {Tellus}}
-
-%% No dash for repeated names
-@IEEEtranBSTCTL{IEEEexample:BSTcontrol,
-  CTLdash_repeated_names = "no"
-}
-
-@ARTICLE{Adcroft_Campin_OM04,
-  author =       {A. Adcroft and J.-M. Campin},
-  title =        {Re-scaled height coordinates for accurate
-                  representation of free-surface flows in ocean
-                  circulation models},
-  journal =      OM,
-  year =         2004,
-  volume =       7,
-  pages =        {269--284},
-  doi =          {10.1016/j.ocemod.2003.09.003},
-}
-
-@ARTICLE{Arakawa1966,
-  author =       {A. Arakawa},
-  title =        {Computational design for long term numerical
-                  integration of the equations of fluid motion,
-                  two-dimensional incompressible flow, Part. I.},
-  journal =      JCP,
-  year =         1966,
-  volume =       {I},
-  pages =        {119--149}
-}
-
-@ARTICLE{Arakawa_Hsu_MWR90,
-  author =       {A. Arakawa and Y.-J. G. Hsu},
-  title =        {Energy Conserving and Potential-Enstrophy
-                  Dissipating Schemes for the Shallow Water Equations},
-  journal =      MWR,
-  year =         1990,
-  volume =       118,
-  number =       10,
-  pages =        {1960--1969},
-}
-
-@ARTICLE{Arakawa_Lamb_MWR81,
-  author =       {Arakawa, Akio and Lamb, Vivian R.},
-  title =        {A Potential Enstrophy and Energy Conserving Scheme
-                  for the Shallow Water Equations},
-  journal =      MWR,
-  year =         1981,
-  volume =       109,
-  number =       1,
-  pages =        {18--36}
-}
-
-@ARTICLE{Arbic2004,
-  author =       {B. Arbic and S. Garner and R. Hallberg and
-                  H. Simmons},
-  title =        {The accuracy of surface elevations in forward global
-                  barotropic and baroclinic tide models},
-  journal =      DSR,
-  year =         2004,
-  volume =       51,
-  pages =        {3069-3101}
-}
-
-@ARTICLE{Arbic2010,
-  author =       {Arbic, Wallcraft, Metzger},
-  title =        {Concurrent simulation of the eddying general
-                  circulation and tides in a global ocean model},
-  journal =      OM,
-  year =         2010,
-  volume =       32,
-  number =       {3-4},
-  pages =        {175-187}
-}
-
-@ARTICLE{Arhan2006,
-  author =       {M. Arhan and A.M. Treguier and B. Bourles and
-                  S. Michel},
-  title =        {Diagnosing the annual cycle of the Equatorial
-                  Undercurrent in the Atlantic Ocean from a general
-                  circulation model},
-  journal =      JPO,
-  year =         2006,
-  volume =       36,
-  pages =        {1502--1522}
-}
-
-@ARTICLE{Artale_al_JGR02,
-  author =       {V. Artale and D. Iudicone and R. Santoleri and
-                  V. Rupolo and S. Marullo and F. {D'O}rtenzio},
-  title =        {Role of surface fluxes in ocean general circulation
-                  models using satellite sea surface temperature:
-                  Validation of and sensitivity to the forcing
-                  frequency of the Mediterranean thermohaline
-                  circulation},
-  journal =      JGR,
-  year =         2002,
-  volume =       107,
-  pages =        {1978-2012},
-  doi =          {10.1029/2000JC000452},
-}
-
-@ARTICLE{ASSELIN_MWR72,
-  author =       {R. Asselin},
-  title =        {Frequency Filter for Time Integrations},
-  journal =      MWR,
-  year =         1972,
-  volume =       100,
-  number =       6,
-  pages =        {487--490}
-}
-
-@ARTICLE{Atmadipoera_al_DSR09,
-  author =       {A. Atmadipoera and R. Molcard and G. Madec and
-                  S.Wijffels and J.  Sprintall and A. Koch-Larrouy and
-                  I. Jaya and A. Supangat},
-  title =        {Characteristics and Variability of the Indonesian
-                  Throughflow Water at the Outflow Straits},
-  journal =      DSR,
-  year =         2009,
-  volume =       56,
-  number =       11,
-  pages =        {1942--1954},
-  doi =          {10.1016/j.dsr.2009.06.004},
-}
-
-@ARTICLE{Aumont_al_GBC99,
-  author =       {O. Aumont and P. Monfray and J. C. Orr and G. Madec
-                  and E. Maier-Reimer},
-  title =        {Nutrient trapping in the equatorial Pacific: The
-                  ocean circulation solution},
-  journal =      GBC,
-  year =         1999,
-  volume =       13,
-  pages =        {351--369}
-}
-
-@ARTICLE{Aumont_al_CD98,
-  author =       {O. Aumont and J.C. Orr and D. Jamous and P. Monfray
-                  and O. Marti and G. Madec},
-  title =        {A degradation approach to accelerate simulations to
-                  steady state in a 3-D tracer transport model of the
-                  global ocean},
-  journal =      CD,
-  year =         1998,
-  volume =       14,
-  pages =        {101--116}
-}
-
-@ARTICLE{Axell_JGR02,
-  author =       {L. B. Axell},
-  title =        {Wind-driven internal waves and Langmuir circulations
-                  in a numerical ocean model of the southern Baltic
-                  Sea},
-  journal =      JGR,
-  year =         2002,
-  volume =       107,
-  doi =          {10.1029/2001JC000922},
-}
-
-@ARTICLE{Axell_Liungman_EFM01,
-  author =       {L. B. Axell and O. Liungman},
-  title =        {A one-equation turbulence model for geophysical
-                  applications: Comparison with data and the
-                  k-$\epsilon$ model},
-  journal =      EFM,
-  year =         2001,
-  volume =       1,
-  pages =        {71--106},
-  doi =          {10.1029/2001JC000922},
-}
-
-@ARTICLE{Ayina_al_JC06,
-  author =       {L.-H. Ayina and A. Bentamy and A. Munes-Mestaz and
-                  G. Madec},
-  title =        {The Impact of Satellite Winds and Latent Heat Fluxes
-                  in a Numerical Simulation of the Tropical Pacific
-                  Ocean},
-  journal =      JC,
-  year =         2006,
-  volume =       19,
-  pages =        {5889--5902}
-}
-
-@ARTICLE{Barnier_al_OD06,
-  author =       {B. Barnier and G. Madec and T. Penduff and
-                  J.-M. Molines and A.-M.  Treguier and J. Le Sommer
-                  and A. Beckmann and A. Biastoch and C. Boning and
-                  J. Dengg and C. Derval and E. Durand and S. Gulev
-                  and E. Remy and C. Talandier and S. Theetten and
-                  M. Maltrud and J. McClean and B. De Cuevas},
-  title =        {Impact of partial steps and momentum advection
-                  schemes in a global ocean circulation model at
-                  eddy-permitting resolution.},
-  journal =      OD,
-  year =         2006,
-  volume =       56,
-  pages =        {543--567},
-  doi =          {10.1007/s10236-006-0082-1},
-}
-
-@INCOLLECTION{Barnier1996,
-  author =       {B. Barnier and P. Marchesiello and A.P. de Miranda},
-  title =        {Modeling the ocean circulation in the South
-                  Atlantic: A strategy for dealing with open
-                  boundaries},
-  booktitle =    {The South Atlantic: Present and Past Circulation},
-  publisher =    {Springer-Verlag, Berlin},
-  year =         1996,
-  editor =       {G.Wefer and W.H. Berger and G Siedler and D. Webb},
-  pages =        {289-304}
-}
-
-@ARTICLE{Barnier1998,
-  author =       {B. Barnier and P. Marchesiello and A. P. de Miranda
-                  and J.M. Molines and M. Coulibaly},
-  title =        {A sigma-coordinate primitive equation model for
-                  studying the circulation in the South Atlantic I,
-                  Model configuration with error estimates},
-  journal =      DSR,
-  year =         1998,
-  volume =       45,
-  pages =        {543--572}
-}
-
-@ARTICLE{Barthelet_al_CRAS98,
-  author =       {P. Barthelet and S. Bony and P. Braconnot and
-                  A. Braum and D. Cariolle and E. Cohen-Solal and
-                  J.-L. Dufresne and P. Delecluse and M. D\'{e}qu\'{e}
-                  and L. Fairhead and M.-A. Filiberti and M. Forichon
-                  and J.-Y. Grandpeix and E. Guilyardi and
-                  M.-N. Houssais and M. Imbard and H. Le Treut and
-                  C. Lévy and Z.X. Li and G. Madec and P. Marquet and
-                  O. Marti and S. Planton and L. Terray and O. Thual
-                  and S. Valcke},
-  title =        {Global coupled simulations of climate change due to
-                  increased atmospheric CO2 concentration},
-  journal =      {C. R. Acad. Sci Paris},
-  year =         1998,
-  volume =       326,
-  pages =        {677--684}
-}
-
-@ARTICLE{Beckmann2003,
-  author =       {A. Beckmann and H. Goosse},
-  title =        {A parameterization of ice shelf-ocean interaction
-                  for climate models},
-  journal =      OM,
-  year =         2003,
-  volume =       5,
-  pages =        {157--170}
-}
-
-@ARTICLE{Beckmann1998,
-  author =       {A. Beckmann},
-  title =        {The representation of bottom boundary layer
-                  processes in numerical ocean circulation models.},
-  journal =      {Ocean modelling and parameterization,
-                  E. P. Chassignet and J. Verron (eds.), NATO Science
-                  Series, Kluwer Academic Publishers},
-  year =         1998
-}
-
-@ARTICLE{Beckmann_Doscher1997,
-  author =       {A. Beckmann and R. D\"{o}scher},
-  title =        {A method for improved representation of dense water
-                  spreading over topography in geopotential-coordinate
-                  models},
-  journal =      JPO,
-  year =         1997,
-  volume =       27,
-  pages =        {581--591}
-}
-
-@ARTICLE{Beckmann1993,
-  author =       {A. Beckmann and D. B. Haidvogel},
-  title =        {Numerical Simulation of Flow around a Tall Isolated
-                  Seamount.  Part I - Problem Formulation and Model
-                  Accuracy},
-  journal =      JPO,
-  year =         1993,
-  volume =       23,
-  number =       8,
-  pages =        {1736--1753}
-}
-
-@ARTICLE{Bernie_al_CD07,
-  author =       {D. Bernie and E. Guilyardi and G. Madec and
-                  J. M. Slingo and S. J. Woolnough},
-  title =        {Impact of resolving the diurnal cycle in an
-                  ocean--atmosphere GCM. Part 1: a diurnally forced
-                  OGCM},
-  journal =      CD,
-  year =         2007,
-  volume =       29,
-  number =       6,
-  pages =        {575--590}
-}
-
-@ARTICLE{Bernie_al_CD08,
-  author =       {D. Bernie and E. Guilyardi and G. Madec and
-                  J. M. Slingo and S. J. Woolnough},
-  title =        {Impact of resolving the diurnal cycle in an
-                  ocean--atmosphere GCM. Part 2: A diurnally coupled
-                  CGCM},
-  journal =      CD,
-  year =         2008,
-  volume =       31,
-  number =       7,
-  pages =        {909--925},
-  doi =          {10.1007/s00382-008-0429-z},
-}
-
-@ARTICLE{Bernie_al_JC05,
-  author =       {D. J. Bernie and S. J. Woolnough and J. M. Slingo
-                  and E. Guilyardi},
-  title =        {Modelling diurnal and intraseasonal variability of
-                  the ocean mixed layer},
-  journal =      JC,
-  year =         2005,
-  volume =       18,
-  number =       8,
-  pages =        {1190--1200}
-}
-
-@ARTICLE{Bessiere_al_GRL08,
-  author =       {L. Bessi\'{e}res and G. Madec and F. Lyard},
-  title =        {Global Tidal Residual Mean Circulation: Does it
-                  Affect a Climate OGCM?},
-  journal =      GRL,
-  year =         2008,
-  volume =       35,
-  pages =        {L03609},
-  doi =          {10.1029/2007GL032644},
-}
-
-@ARTICLE{Biastoch_al_JC08,
-  author =       {A. Biastoch and C. W. Böning and J. Getzlaff and
-                  J.-M. Molines and G. Madec},
-  title =        {Causes of interannual – decadal variability in the
-                  meridional overturning circulation of the
-                  mid-latitude North Atlantic Ocean},
-  journal =      JC,
-  year =         2008,
-  volume =       21,
-  number =       24,
-  pages =        {6599-6615},
-  doi =          {10.1175/2008JCLI2404.1},
-}
-
-@ARTICLE{Bignami_al_JGR95,
-  author =       {F. Bignami and S. Marullo and R. Santoleri and
-                  M. E. Schiano},
-  title =        {Longwave radiation budget in the Mediterranean Sea},
-  journal =      JGR,
-  year =         1995,
-  volume =       100,
-  number =       {C2},
-  pages =        {2501--2514},
-  doi =          {10.1029/94JC02496},
-}
-
-@ARTICLE{Blanke_al_JPO99,
-  author =       {B. Blanke and M. Arhan and G. Madec and S. Roche},
-  title =        {Warm Water Paths in the Equatorial Atlantic as
-                  Diagnosed with a General Circulation Model},
-  journal =      JPO,
-  year =         1999,
-  volume =       29,
-  number =       11,
-  pages =        {2753-2768}
-}
-
-@ARTICLE{Blanke1993,
-  author =       {B. Blanke and P. Delecluse},
-  title =        {Low frequency variability of the tropical Atlantic
-                  ocean simulated by a general circulation model with
-                  mixed layer physics},
-  journal =      JPO,
-  year =         1993,
-  volume =       23,
-  pages =        {1363--1388}
-}
-
-@ARTICLE{blanke_al_JC97,
-  author =       {B. Blanke and J. D. Neelin and D. Gutzler},
-  title =        {Estimating the effect of stochastic wind forcing on
-                  ENSO irregularity},
-  journal =      JC,
-  year =         1997,
-  volume =       10,
-  pages =        {1473--1486}
-}
-
-@ARTICLE{Blanke_Raynaud_JPO97,
-  author =       {B. Blanke and S. Raynaud},
-  title =        {Kinematics of the Pacific Equatorial Undercurrent:
-                  An Eulerian and Lagrangian Approach from GCM
-                  Results},
-  journal =      JPO,
-  year =         1997,
-  volume =       27,
-  number =       6,
-  pages =        {1038--1053}
-}
-
-@ARTICLE{Blanke_al_JPO01,
-  author =       {B. Blanke and S. Speich and G. Madec and K. Döös},
-  title =        {A global Diagnostic of interocean mass transfers},
-  journal =      JPO,
-  year =         2001,
-  volume =       31,
-  number =       6,
-  pages =        {1623--1632}
-}
-
-@ARTICLE{Blanke_al_GRL02,
-  author =       {B. Blanke and S. Speich and G. Madec and
-                  R. Maug\'{e}},
-  title =        {A global diagnostic of interior ocean ventilation},
-  journal =      GRL,
-  year =         2002,
-  volume =       29,
-  number =       8,
-  pages =        {1081--1084}
-}
-
-@ARTICLE{Blayo2005,
-  author =       {E. Blayo and L. Debreu},
-  title =        {Revisiting open boundary conditions from the point
-                  of view of characteristic variables},
-  journal =      OM,
-  year =         2005,
-  volume =       9,
-  pages =        {231--252}
-}
-
-@ARTICLE{Bloom_al_MWR96,
-  author =       {S. C. Bloom and L. L. Takacs and A. M. Da Silva and
-                  D. Ledvina},
-  title =        {Data assimilation using incremental analysis
-                  updates},
-  journal =      MWR,
-  year =         1996,
-  volume =       124,
-  pages =        {1256--1271}
-}
-
-@ARTICLE{Bopp_al_GBC01,
-  author =       {L. Bopp and P. Monfray and O. Aumont and
-                  J.-L. Dufresne and H. Le Treut and G. Madec and
-                  L. Terray and J.C. Orr},
-  title =        {Potential impact of climate change on marine export
-                  production},
-  journal =      GBC,
-  year =         2001,
-  volume =       15,
-  number =       1,
-  pages =        {81--101}
-}
-
-@article{bouffard_Boegman_DAO2013,
-  author =       {D. Bouffard and L. Boegman},
-  title =        {A diapycnal diffusivity model for stratified
-                  environmental flows},
-  volume =       {61-62},
-  issn =         03770265,
-  doi =          {10.1016/j.dynatmoce.2013.02.002},
-  journal =      DAO,
-  year =         2013,
-  pages =        {14--34},
-}
-
-@ARTICLE{Bougeault1989,
-  author =       {P. Bougeault and P. Lacarrere},
-  title =        {Parameterization of Orography-Induced Turbulence in
-                  a Mesobeta--Scale Model},
-  journal =      MWR,
-  year =         1989,
-  volume =       117,
-  number =       8,
-  pages =        {1872--1890},
-}
-
-@ARTICLE{Bouillon_al_OM09,
-  author =       {S. Bouillon and M.A. Morales Maqueda and V. Legat
-                  and T. Fichefet},
-  title =        {An Elastic-Viscous-Plastic Sea Ice Model formulated
-                  on Arakawa B and C Grids},
-  journal =      OM,
-  year =         2009,
-  volume =       27,
-  pages =        {174--184},
-  doi =          {10.1016/j.ocemod.2009.01.004},
-}
-
-@ARTICLE{Boulanger_al_GRL01,
-  author =       {J.-P. Boulanger and E. Durand and J.-P. Duvel and
-                  C. Menkes and P.  Delecluse and M. Imbard and
-                  M. Lengaigne and G. Madec and S. Masson},
-  title =        {Role of non-linear oceanic processes in the response
-                  to westerly wind events: new implications for the
-                  1997 El Niño onset},
-  journal =      GRL,
-  year =         2001,
-  volume =       28,
-  number =       8,
-  pages =        {1603--1606}
-}
-
-@article{Brankart_OM2013,
-  author =       "J.-M. Brankart",
-  title =        "Impact of uncertainties in the horizontal density
-                  gradient upon low resolution global ocean modelling
-                  ",
-  journal =      OM,
-  year =         2013,
-  volume =       66,
-  pages =        "64--76",
-  issn =         "1463-5003",
-  doi =          "http://dx.doi.org/10.1016/j.ocemod.2013.02.004",
-}
-
-@Article{Brankart_al_GMD2015,
-  AUTHOR =       {Brankart, J.-M. and Candille, G. and Garnier, F. and
-                  Calone, C. and Melet, A. and Bouttier, P.-A. and
-                  Brasseur, P. and Verron, J.},
-  TITLE =        {A generic approach to explicit simulation of
-                  uncertainty in the NEMO ocean model},
-  JOURNAL =      {Geoscientific Model Development},
-  VOLUME =       8,
-  YEAR =         2015,
-  NUMBER =       5,
-  PAGES =        {1285--1297},
-  DOI =          {10.5194/gmd-8-1285-2015}
-}
-
-@ARTICLE{Breivik_al_JPO2014,
-  AUTHOR =       {{\O}yvind Breivik and Peter A.E.M. Janssen and
-                  Jean-Raymond Bidlot},
-  YEAR =         2014,
-  TITLE =        "{Approximate Stokes Drift Profiles in Deep Water}",
-  JOURNAL =      {JPO},
-  VOLUME =       44,
-  NUMBER =       9,
-  DOI =          {10.1175/JPO-D-14-0020.1.},
-  PAGES =        {2433--2445, arXiv:1406.5039}
-}
-
-@ARTICLE{Breivik_al_OM2016,
-  AUTHOR =       {{\O}yvind Breivik and Jean-Raymond Bidlot and Peter
-                  A.E.M. Janssen},
-  YEAR =         2016,
-  TITLE =        "{A Stokes drift approximation based on the Phillips
-                  spectrum}",
-  JOURNAL =      {OM},
-  VOLUME =       100,
-  DOI =          {10.1016/j.ocemod.2016.01.005},
-  PAGES =        {49--56, arXiv:1601.08092}
-}
-
-@ARTICLE{Brodeau_al_OM09,
-  author =       {L. Brodeau and B. Barnier and A.-M. Tr\'{e}guier and
-                  T. Penduff and S. Gulev},
-  title =        {An ERA40-based atmospheric forcing for global ocean
-                  circulation models},
-  journal =      OM,
-  year =         2009,
-  volume =       31,
-  number =       {3-4},
-  pages =        {88--104}
-}
-
-@ARTICLE{de_Boyer_Montegut_al_JGR04,
-  author =       {C. de Boyer Mont\'{e}gut and G. Madec and
-                  A.S. Fischer and A. Lazar and D. Iudicone},
-  title =        {Mixed layer depth over the global ocean: An
-                  examination of profile data and a profile-based
-                  climatology},
-  journal =      JGR,
-  year =         2004,
-  volume =       109,
-  pages =        {C12003},
-  doi =          {10.1029/2004JC002378},
-}
-
-@ARTICLE{de_Boyer_Montegut_al_JC07,
-  author =       {C. de Boyer Mont\'{e}gut and J. Vialard and
-                  F. Durand and G. Madec},
-  title =        {Simulated seasonal and interannual variability of
-                  mixed layer heat budget in the northern Indian
-                  Ocean},
-  journal =      JC,
-  year =         2007,
-  volume =       20,
-  number =       13,
-  pages =        {3249--3268}
-}
-
-@ARTICLE{Brown_Campana_MWR78,
-  author =       {J. A. Brown and K. A. Campana},
-  title =        {An Economical Time-Differencing System for Numerical
-                  Weather Prediction},
-  journal =      MWR,
-  year =         1978,
-  volume =       106,
-  number =       8,
-  pages =        {1125--1136},
-}
-
-@ARTICLE{Bryan1997,
-  author =       {K. Bryan},
-  title =        {A Numerical Method for the Study of the Circulation
-                  of the World Ocean},
-  journal =      JCP,
-  year =         1997,
-  volume =       135,
-  number =       2
-}
-
-@ARTICLE{Bryan1984,
-  author =       {K. Bryan},
-  title =        {Accelerating the convergence to equilibrium of
-                  ocean-climate models},
-  journal =      JPO,
-  year =         1984,
-  volume =       14,
-  pages =        {666--673}
-}
-
-@ARTICLE{Bryden1973,
-  author =       {H. L. Bryden},
-  title =        {New polynomials for thermal expansion, adiabatic
-                  temperature gradient and potential temperature of
-                  sea water},
-  journal =      DSR,
-  year =         1973,
-  volume =       20,
-  pages =        {401--408}
-}
-
-@ARTICLE{Burchard_OM02,
-  author =       {Hans Burchard},
-  title =        {Energy-conserving discretisation of turbulent shear
-                  and buoyancy production},
-  journal =      OM,
-  year =         2002,
-  volume =       4,
-  number =       {3-4},
-  pages =        {347--361},
-  doi =          {10.1016/S1463-5003(02)00009-4},
-}
-
-@ARTICLE{Campin2004,
-  author =       {J.-M. Campin and A. Adcroft and C. Hill and
-                  J. Marshall},
-  title =        {Conservation of properties in a free-surface model},
-  journal =      OM,
-  year =         2004,
-  volume =       6,
-  number =       {3-4},
-  pages =        {221--244}
-}
-
-@ARTICLE{Campin_al_OM08,
-  author =       {J.-M. Campin and J. Marshall and D. Ferreira},
-  title =        {Sea ice-ocean coupling using a rescaled vertical
-                  coordinate z*},
-  journal =      OM,
-  year =         2008,
-  volume =       24,
-  number =       {1-2},
-  pages =        {1--14},
-  doi =          {10.1016/j.ocemod.2008.05.005},
-}
-
-@ARTICLE{Campin_Goosse_Tel99,
-  author =       {J.-M. Campin and H. Goosse},
-  title =        {Parameterization of density-driven downsloping flow
-                  for a coarse-resolution ocean model in z-coordinate},
-  journal =      {Tellus},
-  year =         1999,
-  volume =       51,
-  pages =        {412--430}
-}
-
-@ARTICLE{Carrere_Lyard_GRL03,
-  author =       {L. Carr\`{e}re and F. Lyard},
-  title =        {Modelling the barotropic response of the global
-                  ocean to atmospheric wind and pressure forcing -
-                  comparisons with observations},
-  journal =      GRL,
-  year =         2003,
-  volume =       30,
-  number =       6,
-  doi =          {10.1029/2002GL016473},
-}
-
-@ARTICLE{Castellari_al_JMS1998,
-  author =       {S> Castellari and N. Pinardi and K. Leaman },
-  title =        {A model study of air-sea interactions in the
-                  Mediterranean Sea.},
-  journal =      JMS,
-  year =         1998,
-  volume =       18,
-  pages =        {89--114}
-}
-
-@TECHREPORT{Chanut2005,
-  author =       {J. Chanut},
-  title =        {Nesting code for NEMO},
-  year =         2005,
-  institution =  {European Union: Marine Environment and Security for
-                  the European Area (MERSEA) Integrated Project},
-  note =         {MERSEA-WP09-MERCA-TASK-9.1.1}
-}
-
-@ARTICLE{Chassignet_al_JPO03,
-  author =       {Eric P. Chassignet and Linda T. Smith and George
-                  R. Halliwell},
-  title =        {North Atlantic Simulations with the Hybrid
-                  Coordinate Ocean Model (HYCOM): Impact of the
-                  Vertical Coordinate Choice, Reference Pressure, and
-                  Thermobaricity},
-  journal =      JPO,
-  year =         2003,
-  volume =       33,
-  pages =        {2504-2526}
-}
-
-@ARTICLE{Covey_al_CD00,
-  author =       {C. Covey and A. Abe-Ouchi and G.J. Boer and
-                  B.A. Boville and U. Cubasch and L. Fairhead and
-                  G.M. Flato and H. Gordon and E. Guilyardi and
-                  X. Jiang and T.C. Johns and H. Le Treut and G. Madec
-                  and G.A. Meehl and R. Miller and A. Noda and
-                  S. B. Power and E. Roeckner and G. Russell and
-                  E.K. Schneider and R.J. Stouffer and L. Terray and
-                  J.-S. von Storch},
-  title =        {The seasonal cycle in coupled ocean-atmosphere
-                  general circulation models},
-  journal =      CD,
-  year =         2000,
-  volume =       16,
-  pages =        {775--787}
-}
-
-@ARTICLE{Canuto_2001,
-  author =       {V. M. Canuto and A. Howard and Y. Cheng and
-                  M. S. Dubovikov},
-  title =        {Ocean turbulence. PartI: One-point closure
-                  model-momentum and heat vertical diffusivities},
-  journal =      JPO,
-  year =         2001,
-  volume =       24,
-  number =       12,
-  pages =        {2546--2559}
-}
-
-@ARTICLE{Cox1987,
-  author =       {M. Cox},
-  title =        {Isopycnal diffusion in a z-coordinate ocean model},
-  journal =      OM,
-  year =         1987,
-  volume =       74,
-  pages =        {1--9}
-}
-
-@ARTICLE{Craig_Banner_JPO94,
-  author =       {P. D. Craig and M. L. Banner},
-  title =        {Modeling wave-enhanced turbulence in the ocean
-                  surface layer},
-  journal =      JPO,
-  year =         1994,
-  volume =       24,
-  number =       12,
-  pages =        {2546--2559}
-}
-
-@ARTICLE{Craik_Leibovich_JFM76,
-  author =       {A. D. D. Craik and S. Leibovich},
-  title =        {A rational model for Langmuir circulations},
-  journal =      JFM,
-  year =         1976,
-  volume =       73,
-  pages =        {401--426}
-}
-
-@ARTICLE{Cravatte_al_OM07,
-  author =       {Cravatte, S. and G. Madec and T. Izumo and C. Menkes
-                  and A. Bozec},
-  title =        {Progress in the 3-D circulation of the eastern
-                  equatorial Pacific in a climate ocean model},
-  journal =      OM,
-  year =         2007,
-  volume =       17,
-  number =       1,
-  pages =        {28--48}
-}
-
-@BOOK{Daley_Barker_Bk01,
-  author =       {R. Daley and E. Barker},
-  title =        {NAVDAS Source Book 2001},
-  publisher =    {NRL/PU/7530-01-441, Available from the Naval
-                  Research Laboratory, Monterey, CA., 93943-5502},
-  year =         2001,
-  pages =        {163pp}
-}
-
-@ARTICLE{D'Alessio_al_JPO98,
-  author =       {S. J. D. D'Alessio and K. Abdella and
-                  N. A. McFarlane},
-  title =        {A new second-order turbulence closure scheme for
-                  modeling the oceanic mixed layer},
-  journal =      JPO,
-  year =         1998,
-  volume =       28,
-  pages =        {1624--1641}
-}
-
-@ARTICLE{Danabasoglu_al_2008,
-  author =       {G. Danabasoglu and R. Ferrari and J. C. McWilliams},
-  title =        {Sensitivity of an ocean general circulation model to
-                  a parameterization of near-surface eddy fluxes},
-  volume =       21,
-  year =         2008,
-  doi =          {10.1175/2007JCLI1508.1},
-  journal =      {J. Climate},
-  pages =        {1192--1208},
-}
-
-@ARTICLE{Dandonneau_al_S04,
-  author =       {Y. Dandonneau and C. Menkes and T. Gorgues and
-                  G. Madec},
-  title =        {Reply to Peter Killworth, 2004 : '' Comment on the
-                  Oceanic Rossby Waves acting as a “Hay Rake” for
-                  ecosystem by-products ''},
-  journal =      {Science},
-  year =         2004,
-  volume =       304,
-  pages =        390
-}
-
-@ARTICLE{Davies_QJRMS76,
-  author =       {H.C. Davies},
-  title =        {A lateral boundary formulation for multi-level
-                  prediction models},
-  year =         1976,
-  journal =      QJRMS,
-  volume =       102,
-  pages =        {405--418}
-}
-
-@ARTICLE{Debreu_al_CG2008,
-  author =       {L. Debreu and C. Vouland and E. Blayo},
-  title =        {AGRIF: Adaptive Grid Refinement In Fortran},
-  journal =      {Computers and Geosciences},
-  year =         2008,
-  volume =       34,
-  pages =        {8--13}
-}
-
-@article{de_lavergne_JPO2016_mixing,
-  author =       {C. de Lavergne and G. Madec and J. Le Sommer and
-                  A. J. G. Nurser and A. C. Naveira Garabato },
-  title =        {On Antarctic Bottom Water consumption in the abyssal
-                  ocean},
-  issn =         {0022-3670},
-  doi =          {10.1175/JPO-D-14-0201.1},
-  journal =      {Journal of Physical Oceanography},
-  year =         2016,
-  volume =       46,
-  pages =        {635-–661}
-}
-
-@article{de_lavergne_JPO2016_efficiency,
-  author =       {C. de Lavergne and G. Madec and J. Le Sommer and
-                  A. J. G. Nurser and A. C. Naveira Garabato },
-  title =        {The impact of a variable mixing efficiency on the
-                  abyssal overturning},
-  issn =         {0022-3670},
-  doi =          {10.1175/JPO-D-14-0259.1},
-  journal =      {Journal of Physical Oceanography},
-  year =         2016,
-  volume =       46,
-  pages =        {663-–681}
-}
-
-@ARTICLE{Delecluse_Madec_Bk00,
-  author =       {P. Delecluse and G. Madec},
-  title =        {Ocean modelling and the role of the ocean in the
-                  climate system},
-  journal =      {In \textit{Modeling the Earth's Climate and its
-                  Variability}, Les Houches, Session, LXVII 1997,
-                  Eds. W. R. Holland, S. Joussaume and F. David,
-                  Elsevier Science},
-  year =         2000,
-  pages =        {237--313}
-}
-
-@PHDTHESIS{Demange_PhD2014,
-  author =       {J. Demange},
-  title =        {Sch\'{e}mas num\'{e}riques d'advection et de
-                  propagation d’ondes de gravit\'{e} dans les
-                  mod\`{e}les de circulation oc\'{e}anique.},
-  school =       {Doctorat es Applied Mathematiques, Grenoble
-                  University, France},
-  year =         2014,
-  pages =        {138pp}
-}
-
-@ARTICLE{Dobricic_al_OS07,
-  author =       {S. Dobricic and N. Pinardi and M. Adani and
-                  M. Tonani and C. Fratianni and A. Bonazzi and
-                  V. Fernandez},
-  title =        {Daily oceanographic analysis by the Mediterranean
-                  basin scale assimilation system},
-  journal =      OS,
-  year =         2007,
-  volume =       3,
-  pages =        {149-157}
-}
-
-@ARTICLE{Doney_al_GBC04,
-  author =       {S.C. Doney and K. Lindsay and K. Caldeira and
-                  J.−M. Campin and H.  Drange and J.−C. Dutay and
-                  M. Follows and Y. Gao and A. Gnanadesikan and
-                  N. Gruber and A. Ishida and F. Joos and G. Madec and
-                  E. Maier−Reimer and J.C. Marshall and R.J. Matear
-                  and P. Monfray and A. Mouchet and R. Najjar and
-                  J.C. Orr and G.−K. Plattner and J. Sarmiento and R.
-                  Schlitzer and R. Slater and I.J. Totterdell and
-                  M.−F. Weirig and Y. Yamanaka and A. Yoo},
-  title =        {Evaluating global ocean carbon models: the
-                  importance of realistic physics},
-  journal =      GBC,
-  year =         2004,
-  volume =       18,
-  pages =        {GB3017},
-  doi =          {10.1029/2003GB002150},
-}
-
-@ARTICLE{Dorscher_Beckmann_JAOT00,
-  author =       {R. D\"{o}scher and A. Beckmann},
-  title =        {Effects of a Bottom Boundary Layer Parameterization
-                  in a Coarse-Resolution Model of the North Atlantic
-                  Ocean},
-  journal =      JAOT,
-  year =         2000,
-  volume =       17,
-  pages =        {698--707}
-}
-
-@ARTICLE{Drijfhout_JPO94,
-  author =       {S. S. Drijfhout},
-  title =        {Heat transport by Mesoscale Eddies in an Ocean
-                  Circulation Model},
-  journal =      JPO,
-  year =         1994,
-  volume =       24,
-  pages =        {353--369}
-}
-
-@ARTICLE{Dukowicz1994,
-  author =       {J. K. Dukowicz and R. D. Smith},
-  title =        {Implicit free-surface method for the
-                  Bryan-Cox-Semtner ocean model},
-  journal =      JGR,
-  year =         1994,
-  volume =       99,
-  pages =        {7991--8014}
-}
-
-@ARTICLE{Durand_al_JC07,
-  author =       {F. Durand and D. Shankar and C. de Boyer
-                  Mont\'{e}gut and S.S.C.  Shenoi and B. Blanke and
-                  G. Madec},
-  title =        {Modeling the barrier-layer formation in the
-                  South-Eastern Arabian Sea},
-  journal =      JC,
-  year =         2007,
-  volume =       20,
-  number =       10,
-  pages =        {2109--2120}
-}
-
-@ARTICLE{Durand_al_GRL04,
-  author =       {F. Durand and S. R. Shetye and J. Vialard and
-                  D. Shankar and S.S.C.  Shenoi and C. Eth\'{e} and
-                  G. Madec},
-  title =        {Impact of temperature inversions on SST evolution in
-                  the South−Eastern Arabian Sea during the pre−summer
-                  monsoon season},
-  journal =      GRL,
-  year =         2004,
-  volume =       31,
-  pages =        {L01305},
-  doi =          {10.1029/2003GL018906},
-}
-
-@INCOLLECTION{Durran2001,
-  author =       {D.R. Durran },
-  title =        {Open boundary conditions: fact and fiction},
-  booktitle =    {Advances in Mathematical Modelling of Atmosphere and
-                  Ocean Dynamics},
-  publisher =    {Kluwer Academic Publishers},
-  year =         2001,
-  editor =       {P.F. Hodnett}
-}
-
-@ARTICLE{Dutay_al_OM02,
-  author =       {J.-C. Dutay and J.L. Bullister and S.C. Doney and
-                  J.C. Orr and R.  Najjar and K. Caldeira and
-                  J.-M. Campin and H. Drange and M. Follows and Y. Gao
-                  and N. Gruber and M. W. Hecht and A. Ishida and
-                  F. Joos and K. Lindsay and G. Madec and
-                  E. Maier-Reimer and J.C. Mashall and R. J. Matear
-                  and P. Monfray and G.-K. Plattner and J. Sarmiento
-                  and R. Schlitzer and R. Slater and I.J. Totterdell
-                  and M.-F. Weirig and Y. Yamanaka and A. Tool},
-  title =        {Evaluation of ocean model ventilation with CFC-11:
-                  comparison of 13 global ocean models},
-  journal =      OM,
-  year =         2002,
-  volume =       4,
-  pages =        {89--120}
-}
-
-@ARTICLE{Dutay_al_EFM09,
-  author =       {J.-C. Dutay and J. Emile-Geay and D. Iudicone and
-                  P. Jean-Baptiste and G. Madec and C. Carouge},
-  title =        {Helium Isotopic Constraints on Simulated Ocean
-                  Circulations - Implications for abyssal theories},
-  journal =      EFM,
-  year =         2009,
-  volume =       10,
-  number =       {1-2},
-  pages =        {257--273},
-  doi =          {10.1007/s10652-009-9159-y}
-}
-
-@ARTICLE{Dutay.J.C2004,
-  author =       {J. -C. Dutay and P. J. -Baptiste and J. -M. Campin
-                  and A. Ishida and E. M. -Reimer and R. J. Matear and
-                  A. Mouchet and I. J. Totterdell and Y. Yamanaka and
-                  K. Rodgers and G. Madec and J.C. Orr},
-  title =        {Evaluation of OCMIP-2 ocean models deep
-                  circulation with mantle helium-3},
-  journal =      JMS,
-  year =         2004,
-  pages =        {1--22}
-}
-
-@ARTICLE{D'Ortenzio_al_GRL05,
-  author =       {F. D\'Ortenzio and D. Iudicone and C. de Boyer
-                  Mont\'{e}gut and P.  Testor and D. Antoine and
-                  S. Marullo and R. Santoleri and G. Madec},
-  title =        {Seasonal variability of the mixed layer depth in the
-                  Mediterranean Sea : a new climatology based on
-                  analysis of individual profiles},
-  journal =      GRL,
-  year =         2005,
-  volume =       32,
-  pages =        {L12605},
-  doi =          {10.1029/2005GL022463},
-}
-
-@ARTICLE{Egbert_Ray_JGR01,
-  author =       {G.B. Egbert and R.D. Ray},
-  title =        {Estimates of M2 tidal energy dissipation from
-                  TOPEX/POSEIDON altimeter data},
-  journal =      JGR,
-  year =         2001,
-  volume =       106,
-  pages =        {22475--22502}
-}
-
-@ARTICLE{Egbert_Ray_Nat00,
-  author =       {G.B. Egbert and R.D Ray},
-  title =        {Significant dissipation of tidal energy in the deep
-                  ocean inferred from satellite altimeter data},
-  journal =      {Nature},
-  year =         2000,
-  volume =       405,
-  pages =        {775--778}
-}
-
-@ARTICLE{Eiseman1980,
-  author =       {P. R. Eiseman and A. P. Stone},
-  title =        {Conservation lows of fluid dynamics -- A survey},
-  journal =      {SIAM Review},
-  year =         1980,
-  volume =       22,
-  pages =        {12--27}
-}
-
-@ARTICLE{Emile-Geay_Madec_OS09,
-  author =       {J. Emile-Geay and G. Madec},
-  title =        {Geothermal heating, diapycnal mixing and the abyssal
-                  circulation},
-  journal =      OS,
-  year =         2009,
-  volume =       5,
-  pages =        {281--325}
-}
-
-@ARTICLE{Engerdahl_Tel95,
-  author =       {H. Engerdahl},
-  year =         1995,
-  title =        {Use of the flow relaxation scheme in a
-                  three-dimensional baroclinic ocean model with
-                  realistic topography},
-  journal =      {Tellus},
-  volume =       {47A},
-  pages =        {365--382}
-}
-
-@ARTICLE{EUROMODEL_OA95,
-  author =       {EUROMODEL Group (P.M. Lehucher, L. Beautier,
-                  M. Chartier, F. Martel, L. Mortier, P. Brehmer,
-                  C. Millot, C. Alberola, M. Benzhora,
-                  I. Taupier-Letage, G. Chabert d'Hieres, H. Didelle,
-                  P. Gleizon, D. Obaton, M. Cr\'{e}pon, C. Herbaut,
-                  G. Madec, S. Speich, J. Nihoul, J. M. Beckers,
-                  P. Brasseur, E. Deleersnijder, S. Djenidi, J. Font,
-                  A. Castellon, E. Garcia-Ladona, M. J. Lopez-Garcia,
-                  M. Manriquez, M. Maso, J. Salat, J. Tintore,
-                  S. Alonso, D. Gomis, A. Viudez, M. Astraldi,
-                  D. Bacciola, M. Borghini, F. Dell'amico, C. Galli,
-                  E. Lazzoni, G. P. Gasparini, S. Sparnocchia, and
-                  A. Harzallah)},
-  title =        {Progress from 1989 to 1992 in
-                  understanding the circulation of the Western
-                  Mediterranean Sea.},
-  journal =      {Oceanologica Acta},
-  year =         1995,
-  volume =       18,
-  number =       2,
-  pages =        {255--271}
-}
-
-@PHDTHESIS{Farge1987,
-  author =       {M. Farge},
-  title =        {Dynamique non lineaire des ondes et des tourbillons
-                  dans les equations de Saint Venant},
-  school =       {Doctorat es Mathematiques, Paris VI University,
-                  France},
-  year =         1987,
-  pages =        {401pp}
-}
-
-@ARTICLE{Farrow1995,
-  author =       {D. E. Farrow and D. P. Stevens},
-  title =        {A new tracer advection scheme for Bryan--Cox type
-                  ocean general circulation models},
-  journal =      JPO,
-  year =         1995,
-  volume =       25,
-  pages =        {1731--1741.}
-}
-
-@ARTICLE{Flather1976,
-  author =       {R.A. Flather},
-  year =         1976,
-  title =        {A tidal model of the north-west European continental
-                  shelf},
-  journal =      {Memoires de la Societ\'{e} Royale des Sciences de
-                  Li\`{e}ge},
-  volume =       6,
-  pages =        {141--164}
-}
-
-@ARTICLE{Flather_JPO94,
-  author =       {R.A. Flather},
-  year =         1994,
-  title =        {A storm surge prediction model for the northern Bay
-                  of Bengal with application to the cyclone disaster
-                  in April 1991},
-  journal =      JPO,
-  volume =       24,
-  pages =        {172--190}
-}
-
-@ARTICLE{Fujio1991,
-  author =       {S. Fujio and N. Imasato},
-  title =        {Diagnostic calculation for circulation and water
-                  mass movement in the deep Pacific},
-  journal =      JGR,
-  year =         1991,
-  volume =       96,
-  pages =        {759--774}
-}
-
-@ARTICLE{Galperin_al_JAS88,
-  author =       {B. Galperin and L. H. Kantha and S. Hassid and
-                  A. Rosati},
-  title =        {A quasi-equilibrium turbulent energy model for
-                  geophysical flows},
-  journal =      JAS,
-  year =         1988,
-  volume =       45,
-  pages =        {55--62}
-}
-
-@ARTICLE{Gargett1984,
-  author =       {A. E. Gargett},
-  title =        {Vertical eddy diffusivity in the ocean interior},
-  journal =      JMR,
-  year =         1984,
-  volume =       42
-}
-
-@ARTICLE{Gaspar1990,
-  author =       {P. Gaspar and Y. Gr{\'e}goris and J.-M. Lefevre},
-  title =        {A simple eddy kinetic energy model for simulations
-                  of the oceanic vertical mixing\: Tests at Station
-                  Papa and long-term upper ocean study site},
-  journal =      JGR,
-  year =         1990,
-  volume =       95,
-  number =       {C9}
-}
-
-@ARTICLE{Gent1990,
-  author =       {P. R. Gent and J. C. Mcwilliams},
-  title =        {Isopycnal Mixing in Ocean Circulation Models},
-  journal =      JPO,
-  year =         1990,
-  volume =       20,
-  number =       1,
-  pages =        {150--155},
-}
-
-@Article{Gentemann_al_JGR09,
-  author =       {C. L. Gentemann and P. J. Minnett and B. Ward},
-  title =        {Profiles of Ocean Surface heating ({POSH}): A new
-                  model of upper ocean diurnal warming},
-  journal =      JGR,
-  year =         2009,
-  Volume =       114,
-  Pages =        {C07017},
-  doi =          {10.1029/2008JC004825}
-}
-
-@ARTICLE{Gerdes1993a,
-  author =       {R. Gerdes},
-  title =        {A primitive equation ocean circulation model using a
-                  general vertical coordinate transformation
-                  1. Description and testing of the model},
-  journal =      JGR,
-  year =         1993,
-  volume =       98
-}
-
-@ARTICLE{Gerdes1993b,
-  author =       {R. Gerdes},
-  title =        {A primitive equation ocean circulation model using a
-                  general vertical coordinate transformation
-                  2. Application to an overflow problem},
-  journal =      JGR,
-  year =         1993,
-  volume =       98,
-  pages =        {14703--14726}
-}
-
-@ARTICLE{Gerdes1991,
-  Author =       {Gerdes, R{\"u}diger and K{\"o}berle, Cornelia and
-                  Willebrand, J{\"u}rgen},
-  Doi =          {10.1007/BF00210006},
-  Journal =      {Clim. Dynamics},
-  Number =       4,
-  Pages =        {211--226},
-  Title =        {The influence of numerical advection schemes on the
-                  results of ocean general circulation models},
-  Volume =       5,
-  Year =         1991,
-}
-
-@TECHREPORT{Gibson_TR86,
-  author =       {J. K. Gibson},
-  title =        {Standard software development and maintenance},
-  institution =  {Operational Dep., ECMWF, Reading, UK.},
-  year =         1986
-}
-
-@BOOK{Gill1982,
-  title =        {Atmosphere-Ocean Dynamics},
-  publisher =    {International Geophysics Series, Academic Press,
-                  New-York},
-  year =         1982,
-  author =       {A. E. Gill}
-}
-
-@article{goff_JGR2010,
-  author =       {J. A. Goff},
-  title =        {Global prediction of abyssal hill root-mean-square
-                  heights from small-scale altimetric gravity
-                  variability},
-  issn =         {2156-2202},
-  doi =          {10.1029/2010JB007867},
-  volume =       115,
-  number =       {B12},
-  journal =      {Journal of Geophysical Research: Solid Earth},
-  year =         2010,
-  pages =        {B12104},
-}
-
-@ARTICLE{Goosse_al_JGR99,
-  author =       {H. Goosse and E. Deleersnijder and T. Fichefet and
-                  M. England},
-  title =        {Sensitivity of a global coupled ocean-sea ice model
-                  to the parameterization of vertical mixing},
-  journal =      JGR,
-  year =         1999,
-  volume =       104,
-  pages =        {13,681--13,695}
-}
-
-@ARTICLE{Gorgues_al_GRL07,
-  author =       {T. Gorgues and C. Menkes and O. Aumont and
-                  K. Rodgers and G. Madec and Y. Dandonneau},
-  title =        {Indonesian Throughflow control of the eastern
-                  equatorial Pacific biogeochemistry},
-  journal =      GRL,
-  year =         2007,
-  volume =       34,
-  pages =        {L05609},
-  doi =          {10.1029/2006GL028210},
-}
-
-@ARTICLE{Graham_McDougall_JPO13,
-  author =       {F.S. Graham and T.J. McDougall},
-  title =        {Quantifying the nonconservative production of
-                  conservative temperature, potential temperature, and
-                  entropy},
-  journal =      JPO,
-  year =         2013,
-  volume =       43,
-  pages =        {838--862},
-  doi =          {10.1175/JPO-D-11-0188.1}
-}
-
-@ARTICLE{Greatbatch_JGR94,
-  author =       {R. J. Greatbatch},
-  title =        {A note on the representation of steric sea level in
-                  models that conserve volume rather than mass},
-  journal =      JGR,
-  year =         1994,
-  volume =       99,
-  number =       {C6},
-  pages =        {12,767--12,771}
-}
-
-@BOOK{Griffies_Bk04,
-  title =        {Fundamentals of ocean climate models},
-  publisher =    {Princeton University Press, 434pp},
-  year =         2004,
-  author =       {S.M. Griffies}
-}
-
-@ARTICLE{Griffies_JPO98,
-  author =       {S.M. Griffies},
-  title =        {The Gent-McWilliams skew-flux},
-  journal =      JPO,
-  year =         1998,
-  volume =       28,
-  pages =        {831--841}
-}
-
-@ARTICLE{Griffies_al_OM09,
-  author =       {S.M. Griffies and A. Biastoch and C. Boning and
-                  F. Bryan and G. Danabasoglu and E. P. Chassignet and
-                  M. H. England and R. Gerdes and H. Haak and
-                  R. W. Hallberg and W. Hazeleger and J. Jungclaus and
-                  W. G. Large and G. Madec and A. Pirani and
-                  B. L. Samuels and M. Scheinert and A. Sen Gupta and
-                  C. A. Severijns and H. L. Simmons and A.-M. Treguier
-                  and M. Winton and S. Yeager and J. Yin},
-  title =        {Coordinated Ocean-ice Reference Experiments (COREs)},
-  journal =      OM,
-  year =         2009,
-  volume =       26,
-  number =       {1-2},
-  pages =        {1--46},
-  doi =          {10.1016/j.ocemod.2008.08.007},
-}
-
-@ARTICLE{Griffies_al_OS05,
-  author =       {S.M. Griffies and A. Gnanadesikan and K.W. Dixon and
-                  J.P. Dunne and R. Gerdes and M.J. Harrison and
-                  A. Rosati and J.L. Russell and B.L.  Samuels and
-                  M.J. Spelman and M. Winton and R. Zhang},
-  title =        {Formulation of an ocean model for global climate
-                  simulations},
-  journal =      OS,
-  year =         2005,
-  volume =       1,
-  pages =        {45--79}
-}
-
-@ARTICLE{Griffies_al_JPO98,
-  author =       {S.M. Griffies and A. Gnanadesikan and
-                  R.C. Pacanowski and V.D. Larichev and J.K. Dukowicz
-                  and R.D. Smith},
-  title =        {Isoneutral Diffusion in a z-Coordinate Ocean Model},
-  journal =      JPO,
-  year =         1998,
-  volume =       28,
-  number =       5,
-  pages =        {805--830},
-}
-
-@ARTICLE{Griffies_al_MWR01,
-  author =       {S.M. Griffies and R.C. Pacanowski and M. Schmidt and
-                  V. Balaji},
-  title =        {Tracer Conservation with an Explicit Free Surface
-                  Method for z-Coordinate Ocean Models},
-  journal =      MWR,
-  year =         2001,
-  volume =       129,
-  number =       5,
-  pages =        {1081--1098},
-}
-
-@ARTICLE{Griffies_Hallberg_MWR00,
-  author =       {S.M. Griffies and R.W. Hallberg},
-  title =        {Biharmonic friction with a Smagorinsky-like
-                  viscosity for use in large-scale eddy-permitting
-                  ocean models},
-  journal =      MWR,
-  year =         2000,
-  volume =       128,
-  pages =        {2935–-2946},
-  doi =          {10.1175/1520-0493(2000)128}
-}
-
-@ARTICLE{Guilyardi_al_JC04,
-  author =       {E. Guilyardi and S. Gualdi and J. M. Slingo and
-                  A. Navarra and P. Delecluse and J. Cole and G. Madec
-                  and M. Roberts and M. Latif and L. Terray},
-  title =        {Representing El Ni\~{n}o in coupled ocean-atmosphere
-                  GCMs: the dominant role of the atmospheric
-                  component},
-  journal =      JC,
-  year =         2004,
-  volume =       17,
-  pages =        {4623--4629}
-}
-
-@ARTICLE{Guilyardi_Madec_CD98,
-  author =       {E. Guilyardi and G. Madec},
-  title =        {Performance of the OPA-ARPEGE-T21 global
-                  ocean-atmosphere coupled model},
-  journal =      CD,
-  year =         1997,
-  volume =       13,
-  pages =        {149--165}
-}
-
-@ARTICLE{Guilyardi_al_CD01,
-  author =       {E. Guilyardi and G. Madec and L. Terray},
-  title =        {The role of lateral ocean physics in the upper ocean
-                  thermal balance of a coupled ocean-atmosphere GCM},
-  journal =      CD,
-  year =         2001,
-  volume =       17,
-  pages =        {589--599},
-  number =       8
-}
-
-@ARTICLE{Guilyardi_al_CRAS95,
-  author =       {E. Guilyardi and G. Madec and L. Terray and
-                  M. D\'{e}qu\'{e} and M. Pontaud and M. Imbard and
-                  D. Stephenson and M.-A. Filiberti and D. Cariolle
-                  and P. Delecluse and O. Thual},
-  title =        {Simulation couplée océan-atmosphère de la
-                  variabilité du climat},
-  journal =      {C. R. Acad. Sci Paris},
-  year =         1995,
-  volume =       320,
-  number =       {s\'{e}rie IIa},
-  pages =        {683--690}
-}
-
-@ARTICLE{Guyon_al_EP99,
-  author =       {M. Guyon and G. Madec and F.-X. Roux and M. Imbard},
-  title =        {A Parallel ocean model for high resolution studies},
-  journal =      {Lecture Notes in Computer Science},
-  year =         1999,
-  volume =       {Euro-Par'99},
-  pages =        {603--607}
-}
-
-@ARTICLE{Guyon_al_CalPar99,
-  author =       {M. Guyon and G. Madec and F.-X. Roux and M. Imbard
-                  and C. Herbaut and P. Fronier},
-  title =        {Parallelization of the OPA ocean model},
-  journal =      {Calculateurs Paralleles},
-  year =         1999,
-  volume =       11,
-  number =       4,
-  pages =        {499--517}
-}
-
-@BOOK{Haltiner1980,
-  title =        {Numerical prediction and dynamic meteorology},
-  publisher =    {John Wiley {\&} Sons Eds., second edition},
-  year =         1980,
-  author =       {G. J. Haltiner and R. T. Williams},
-  pages =        {477pp}
-}
-
-@ARTICLE{Haney1991,
-  author =       {R. L. Haney},
-  title =        {On the Pressure Gradient Force over Steep Topography
-                  in Sigma Coordinate Ocean Models},
-  journal =      JPO,
-  year =         1991,
-  volume =       21,
-  number =       4,
-  pages =        {610--619},
-}
-
-@ARTICLE{Hazeleger_Drijfhout_JPO98,
-  author =       {W. Hazeleger and S. S. Drijfhout},
-  title =        {Mode water variability in a model of the subtropical
-                  gyre: response to anomalous forcing},
-  journal =      JPO,
-  year =         1998,
-  volume =       28,
-  pages =        {266--288},
-}
-
-@ARTICLE{Hazeleger_Drijfhout_JPO99,
-  author =       {W. Hazeleger and S. S. Drijfhout},
-  title =        {Stochastically forced mode water variability},
-  journal =      JPO,
-  year =         1999,
-  volume =       29,
-  pages =        {1772--1786},
-}
-
-@ARTICLE{Hazeleger_Drijfhout_JGR00,
-  author =       {W. Hazeleger and S. S. Drijfhout},
-  title =        {A model study on internally generated variability in
-                  subtropical mode water formation},
-  journal =      JGR,
-  year =         2000,
-  volume =       105,
-  pages =        {13,965--13,979},
-}
-
-@ARTICLE{Hazeleger_Drijfhout_JPO00,
-  author =       {W. Hazeleger and S. S. Drijfhout},
-  title =        {Eddy subduction in a model of the subtropical gyre},
-  journal =      JPO,
-  year =         2000,
-  volume =       30,
-  pages =        {677--695},
-}
-
-@ARTICLE{Hellerman_Rosenstein_JPO83,
-  author =       {S. Hellerman and M. Rosenstein },
-  title =        {Normal monthly wind stress over the world ocean with
-                  error estimates},
-  journal =      JPO,
-  year =         1983,
-  volume =       13,
-  pages =        {1093--1104},
-}
-
-@ARTICLE{He_Ding_JSC01,
-  author =       {Y. He and C. H. Q. Ding},
-  title =        {Using Accurate Arithmetics to Improve Numerical
-                  Reproducibility and Stability in Parallel
-                  Applications},
-  journal =      JSC,
-  year =         2001,
-  volume =       18,
-  pages =        {259--277},
-}
-
-@ARTICLE{Hirt_al_JCP74,
-  author =       {C. W. Hirt and A. A. Amsden and J. L. Cook},
-  title =        {An Arbitrary Lagrangian--Eulerian Computing Method
-                  for All Flow Speeds},
-  journal =      JCP,
-  year =         1974,
-  volume =       14,
-  pages =        {227--253}
-}
-
-@ARTICLE{Hofmeister_al_OM09,
-  author =       {R. Hofmeister and H. Burchard and J.-M. Beckers},
-  title =        {Non-uniform adaptive vertical grids for 3D numerical
-                  ocean models},
-  journal =      OM,
-  year =         2009,
-  volume =       33,
-  pages =        {70--86},
-  doi =          {10.1016/j.ocemod.2009.12.003},
-  issn =         {1463-5003},
-}
-
-@ARTICLE{Holland1999,
-  author =       {D. Holland and A. Jenkins},
-  title =        {Modeling Thermodynamic Ice-Ocean Interactions at the
-                  Base of an Ice Shelf},
-  journal =      JPO,
-  year =         1999,
-  volume =       29,
-  pages =        {1787--1800},
-}
-
-@ARTICLE{HollowayOM86,
-  author =       {Greg Holloway},
-  title =        {A Shelf Wave/Topographic Pump Drives Mean Coastal
-                  Circulation (part I)},
-  journal =      OM,
-  year =         1986,
-  volume =       68,
-}
-
-@ARTICLE{HollowayJPO92,
-  author =       {Greg Holloway},
-  title =        {Representing Topographic Stress for Large-Scale
-                  Ocean Models},
-  journal =      JPO,
-  year =         1992,
-  volume =       22,
-  pages =        {1033--1046},
-}
-
-@ARTICLE{HollowayJPO94,
-  author =       {Michael Eby and Greg Holloway},
-  title =        {Sensitivity of a Large-Scale Ocean Model to a
-                  Parameterization of Topographic Stress},
-  journal =      JPO,
-  year =         1994,
-  volume =       24,
-  pages =        {2577--2587},
-}
-
-@ARTICLE{HollowayJGR09,
-  author =       {Greg Holloway and Zeliang Wang},
-  title =        {Representing eddy stress in an Arctic Ocean model},
-  journal =      JGR,
-  year =         2009,
-  doi =          {10.1029/2008JC005169},
-}
-
-@ARTICLE{HollowayOM08,
-  author =       {Mathew Maltrud and Greg Holloway},
-  title =        {Implementing biharmonic neptune in a global eddying
-                  ocean model},
-  journal =      OM,
-  year =         2008,
-  volume =       21,
-  pages =        {22--34},
-}
-
-@ARTICLE{Hordoir_al_CD08,
-  author =       {R. Hordoir and J. Polcher and J.-C. Brun-Cottan and
-                  G. Madec},
-  title =        {Towards a parametrization of river discharges into
-                  ocean general circulation models: a closure through
-                  energy conservation},
-  journal =      CD,
-  year =         2008,
-  volume =       31,
-  number =       {7-8},
-  pages =        {891--908},
-  doi =          {10.1007/s00382-008-0416-4},
-}
-
-@ARTICLE{Hsu1990,
-  author =       {Hsu, Yueh-Jiuan G. and Arakawa, Akio},
-  title =        {Numerical Modeling of the Atmosphere with an
-                  Isentropic Vertical Coordinate},
-  journal =      MWR,
-  year =         1990,
-  volume =       118,
-  number =       10,
-  pages =        {1933--1959},
-}
-
-@ARTICLE{Huang_JPO93,
-  author =       {R.X. Huang},
-  title =        {Real freshwater flux as a natural boundary condition
-                  for the salinity balance and thermohaline
-                  circulation forced by evaporation and precipitation},
-  journal =      JPO,
-  year =         1993,
-  volume =       23,
-  pages =        {2428--2446}
-}
-
-@TECHREPORT{Hunke2008,
-  author =       {E.C. Hunke and W.H. Lipscomb},
-  title =        {CICE: the Los Alamos sea ice model documentation and
-                  software user's manual, Version 4.0},
-  institution =  { Los Alamos National Laboratory, N.M.},
-  publisher =    {LA-CC-06-012, Los Alamos National Laboratory, N.M.},
-  year =         2008
-}
-
-@TechReport{Hunter2006,
-  Title =        {Specification for Test Models of Ice Shelf Cavities},
-  Author =       {J. R. Hunter},
-  Institution =  {Antarctic Climate \& Ecosystems Cooperative Research
-                  Centre Private Bag 80, Hobart, Tasmania 7001},
-  Year =         2006,
-}
-
-@TECHREPORT{TEOS10,
-  author =       {IOC and SCOR and IAPSO},
-  title =        {The international thermodynamic equation of seawater
-                  - 2010: Calculation and use of thermodynamic
-                  properties},
-  institution =  {Intergovernmental Oceanographic Commission},
-  publisher =    {Manuals and Guides No. 56, UNESCO (English)},
-  year =         2010,
-  pages =        {196pp},
-  url =          {http://www.teos-10.org/pubs/TEOS-10_Manual.pdf}
-}
-
-@ARTICLE{Iudicone_al_JPO08b,
-  author =       {D. Iudicone and G. Madec and B. Blanke and
-                  S. Speich},
-  title =        {The role of Southern Ocean surface forcings and
-                  mixing in the global conveyor},
-  journal =      JPO,
-  year =         2008,
-  volume =       38,
-  pages =        {1377--1400}
-}
-
-@ARTICLE{Iudicone_al_JPO08a,
-  author =       {D. Iudicone and G. Madec and T. J. McDougall},
-  title =        {Diagnosing water transformations and the key role of
-                  light penetration},
-  journal =      JPO,
-  year =         2008,
-  volume =       38,
-  pages =        {1357--1376}
-}
-
-@ARTICLE{Iudicone_al_JPO07,
-  author =       {D. Iudicone and K. Rodgers and R. Schopp and
-                  G. Madec},
-  title =        {An Exchange window for the Antarctic Intermediate
-                  Water Injection into the South Pacific},
-  journal =      JPO,
-  year =         2007,
-  volume =       37,
-  pages =        {31--49}
-}
-
-@ARTICLE{Iudicone_al_JPO08c,
-  author =       {D. Iudicone and S. Speich and G. Madec and
-                  B. Blanke},
-  title =        {The global Conveyor Belt in a Southern Ocean
-                  perspective},
-  journal =      JPO,
-  year =         2008,
-  volume =       38,
-  pages =        {1401--1425}
-}
-
-@ARTICLE{Izumo_al_CD10,
-  author =       {T. Izumo and S.Masson and J. Vialard and C. de Boyer
-                  Montegut and S. K. Behera and G. Madec and
-                  K. Takahashi and T. Yamagata},
-  title =        {Interannual variations of low-frequency
-                  Madden-Julian Oscillation in autral summer:
-                  Observations},
-  journal =      CD,
-  year =         2010,
-  volume =       35,
-  number =       4,
-  pages =        {669--683},
-  doi =          {10.1007/s00382-009-0655-z}
-}
-
-@ARTICLE{JackMcD1995,
-  author =       {D. R. Jackett and T. J. McDougall},
-  title =        {Minimal adjustment of hydrographic data to achieve
-                  static stability},
-  journal =      JAOT,
-  year =         1995,
-  volume =       12,
-  pages =        {381--389}
-}
-
-@article{Jackson_Rehmann_JPO2014,
-  author =       {P. R. Jackson and C. R. Rehmann},
-  title =        {Experiments on differential scalar mixing in
-                  turbulence in a sheared, stratified flow},
-  journal =      JPO,
-  volume =       44,
-  issn =         {0022-3670},
-  doi =          {10.1175/JPO-D-14-0027.1},
-  number =       10,
-  year =         2014,
-  pages =        {2661--2680},
-}
-
-@TECHREPORT{Janssen_al_TM13,
-  author =       {P.A.E.M. Janssen and {\O}. Breivik and K. Mogensen
-                  and F. Vitart and M. Balmaseda and J.B. Bidlot and
-                  S. Keeley and M. Leut-becher and L. Magnusson and
-                  F. Molteni},
-  title =        {Air-Sea Interaction and Surface Waves},
-  year =         2013,
-  volume =       712,
-  institution =  {ECMWF},
-}
-
-@ARTICLE{Jayne_St_Laurent_GRL01,
-  author =       {S.R. Jayne and L.C. {St. Laurent}},
-  title =        {Parameterizing tidal disspiation over rough
-                  topography},
-  journal =      GRL,
-  pages =        {811--814}
-}
-
-@ARTICLE{Jenkins1991,
-  author =       {A. Jenkins},
-  title =        {A one-dimensional model of ice shelf-ocean
-                  interaction},
-  journal =      JGR,
-  year =         1991,
-  volume =       96,
-  number =       {C11},
-  pages =        {2298--2312}
-}
-
-@ARTICLE{Jenkins2001,
-  author =       {A. Jenkins},
-  title =        {The Role of Meltwater Advection in the Formulation
-                  of Conservative Boundary Conditions at an Ice-Ocean
-                  Interface},
-  journal =      JPO,
-  year =         2001,
-  volume =       31,
-  pages =        {285--296}
-}
-
-@ARTICLE{Jenkins2010,
-  author =       {A. Jenkins},
-  title =        {observation and parameterization of ablation at the
-                  base of Ronne Ice Shelf, Antarctica},
-  journal =      JPO,
-  year =         2010,
-  volume =       40,
-  number =       10,
-  pages =        {2298--2312}
-}
-
-@BOOK{Jerlov_Bk68,
-  title =        {Optical Oceanography},
-  publisher =    {Elsevier},
-  year =         1968,
-  author =       {N. G. Jerlov},
-  pages =        {194pp}
-}
-
-@ARTICLE{Jones_MWR99,
-  author =       {P. W. Jones},
-  title =        {First- and second-order conservative remapping
-                  schemes for grids in spherical coordinates},
-  journal =      MWR,
-  year =         1999,
-  volume =       127,
-  pages =        {2204--2210}
-}
-
-@BOOK{Jones_Bk01,
-  title =        {A User's Guide for SCRIP: A Spherical Coordinate
-                  Remapping and Interpolation Package. Version 1.4},
-  publisher =    {Los Alamos National Laboratory},
-  year =         2001,
-  author =       {P. W. Jones},
-  pages =        {27pp},
-  url =
-                  {http://climate.lanl.gov/Software/SCRIP/SCRIPusers.pdf}
-}
-
-@TECHREPORT{Jones_1998,
-  title =        {A User's Guide for SCRIP: A Spherical Coordinate
-                  Remapping and Interpolation Package. Version 1.4},
-  institution =  {Los Alamos National Laboratory},
-  year =         1998,
-  author =       {P. W. Jones},
-  url =
-                  {http://climate.lanl.gov/Software/SCRIP/SCRIPusers.pdf}
-}
-
-@ARTICLE{Kantha_Clayson_1994,
-  author =       {L. H. Kantha and C. A. Clayson},
-  title =        {An improved mixed layer model for geophysical
-                  applications},
-  journal =      JGR,
-  year =         1994,
-  volume =       99,
-  pages =        {25,235--25,266}
-}
-
-@ARTICLE{Kantha_Carniel_CSR05,
-  author =       {L. Kantha and S. Carniel},
-  title =        {Comment on ''Generic length-scale equation for
-                  geophysical turbulence models'' by L. Umlauf and
-                  H. Burchard},
-  journal =      JMS,
-  year =         2005,
-  volume =       61,
-  pages =        {693--702}
-}
-
-@ARTICLE{Kasahara_MWR74,
-  author =       {A. Kasahara},
-  title =        {Various vertical coordinate systems used for
-                  numerical weather prediction},
-  journal =      MWR,
-  year =         1974,
-  volume =       102,
-  pages =        {509--522}
-}
-
-@ARTICLE{Killworth_al_JPO91,
-  author =       {P.D. Killworth and D. Stainforth and D.J. Webb and
-                  S.M. Paterson},
-  title =        {The Development of a Free-Surface Bryan-Cox-Semtner
-                  Ocean Model},
-  journal =      JPO,
-  year =         1991,
-  volume =       21,
-  number =       9,
-  pages =        {1333--1348}
-}
-
-@INPROCEEDINGS{Killworth1989,
-  author =       {P. D. Killworth},
-  title =        {On the parameterization of deep convection in ocean
-                  models},
-  booktitle =    {Parameterization of small-scale processes},
-  year =         1989,
-  editor =       {Hawaiian winter workshop},
-  month =        {January 17-20},
-  organization = {University of Hawaii at Manoa}
-}
-
-@ARTICLE{Killworth1992,
-  author =       {P. D. Killworth},
-  title =        {An equivalent-barotropic mode in the fine resolution
-                  Antarctic model},
-  journal =      JPO,
-  year =         1992,
-  volume =       22,
-  pages =        {1379--1387}
-}
-
-@ARTICLE{Koch-Larrouy_al_CD10,
-  author =       {A. Koch-Larrouy and M. Lengaigne and P. Terray and
-                  G. Madec and S. Masson},
-  title =        {Tidal mixing in the Indonesian Seas and its effect
-                  on the tropical climate system},
-  journal =      CD,
-  year =         2010,
-  volume =       34,
-  number =       6,
-  pages =        {891--904},
-  doi =          {10.1007/s00382-009-0642-4},
-}
-
-@ARTICLE{Koch-Larrouy_al_OD08b,
-  author =       {A. Koch-Larrouy and G. Madec and B. Blanke and
-                  R. Molcard},
-  title =        {Water mass transformation along the Indonesian
-                  throughflow in an OGCM},
-  journal =      OD,
-  year =         2008,
-  volume =       58,
-  number =       {3-4},
-  pages =        {289--309},
-  doi =          {10.1007/s10236-008-0155-4},
-}
-
-@ARTICLE{Koch-Larrouy_al_GRL07,
-  author =       {A. Koch-Larrouy and G. Madec and P. Bouruet-Aubertot
-                  and T. Gerkema and L. Bessieres and R. Molcard},
-  title =        {Tidal mixing in the Indonesian Seas and its effect
-                  on the tropical climate system},
-  journal =      GRL,
-  year =         2007,
-  volume =       34,
-  pages =        {L04604},
-  doi =          {10.1029/2006GL028405},
-}
-
-@ARTICLE{Koch-Larrouy_al_OD08a,
-  author =       {A. Koch-Larrouy and G. Madec and D. Iudicone and
-                  A. Atmadipoera and R. Molcard},
-  title =        {Physical processes contributing to the water mass
-                  transformation of the Indonesian Throughflow},
-  journal =      OD,
-  year =         2008,
-  volume =       58,
-  number =       {3-4},
-  pages =        {275--288},
-  doi =          {10.1007/s10236-008-0154-5},
-}
-
-@ARTICLE{Kolmogorov1942,
-  author =       {A. N. Kolmogorov},
-  title =        {The equation of turbulent motion in an
-                  incompressible fluid},
-  journal =      {Izv. Akad. Nauk SSSR, Ser. Fiz.},
-  year =         1942,
-  volume =       6,
-  pages =        {56--58}
-}
-
-@ARTICLE{Kondo1975,
-  author =       {J. Kondo},
-  title =        {Air-sea bulk transfer coefficients in diabatic
-                  conditions},
-  journal =      {Boundary-Layer Meteorol},
-  year =         1975,
-  volume =       9,
-  pages =        {91--112}
-}
-
-@article{Lemarie_OM2012,
-  author =       "F. Lemari\'{e} and L. Debreu and A.F. Shchepetkin
-                  and J.C. McWilliams",
-  title =        "On the stability and accuracy of the harmonic and
-                  biharmonic isoneutral mixing operators in ocean
-                  models ",
-  journal =      OM,
-  year =         2012,
-  volume =       "52–53",
-  pages =        "9--35",
-  issn =         "1463-5003",
-  doi =          "http://dx.doi.org/10.1016/j.ocemod.2012.04.007",
-}
-
-@ARTICLE{Lemarie_OM2015,
-  author =       {F. Lemari\'{e} and L. Debreu and J. Demange and
-                  G. Madec and J.M. Molines and M. Honnorat},
-  title =        {Stability Constraints for Oceanic Numerical Models:
-                  Implications for the Formulation of time and space
-                  Discretizations},
-  journal =      OM,
-  year =         2015,
-  volume =       92,
-  pages =        {124--148},
-  doi =          {10.1016/j.ocemod.2015.06.006},
-}
-
-@ARTICLE{Lermusiaux2001,
-  author =       {P. F. J. Lermusiaux},
-  title =        {Evolving the subspace of three-dimensional
-                  miltiscale ocean variability: Massachusetts Bay},
-  journal =      JMS,
-  year =         2001,
-  volume =       29,
-  pages =        {385--422}
-}
-
-@PHDTHESIS{Levy_PhD96,
-  author =       {M. L\'{e}vy},
-  title =        {Mod\'{e}lisation des processus biog\'{e}ochimiques
-                  en M\'{e}diterran\'{e}e nord-occidentale. Cycle
-                  saisonnier et variabilit\'{e} m\'{e}so\'{e}chelle},
-  school =       {Universit\'{e} Pierre et Marie Curie, Paris, France,
-                  207pp},
-  year =         1996
-}
-
-@ARTICLE{Levy_al_GRL01,
-  author =       {M. L\'{e}vy and A. Estubier and G Madec},
-  title =        {Choice of an advection scheme for biogeochemical
-                  models},
-  journal =      GRL,
-  year =         2001,
-  volume =       28
-}
-
-@ARTICLE{Levy_al_OM10,
-  author =       {M. L\'{e}vy and P. Klein and A.-M. Tr\'{e}guier and
-                  D. Iovino and G. Madec and S. Masson and
-                  T. Takahashi},
-  title =        {Impacts of sub-mesoscale physics on idealized gyres},
-  journal =      OM,
-  year =         2010,
-  volume =       34,
-  number =       {1-2},
-  doi =          {10.1016/j.ocemod.2010.04.001},
-}
-
-@ARTICLE{Levy_al_JMS99,
-  author =       {M. L\'{e}vy and L. M\'{e}mery and G. Madec},
-  title =        {The onset of a bloom after deep winter convection in
-                  the Northwestern Mediterranean Sea: mesoscale
-                  process study with a primitive equation model},
-  journal =      JMS,
-  year =         1999,
-  volume =       16,
-  number =       {1-2},
-  pages =        {7--21}
-}
-
-@ARTICLE{Levy_al_DSR98,
-  author =       {M. L\'{e}vy and L. M\'{e}mery and G. Madec},
-  title =        {The onset of the spring bloom in the MEDOC area:
-                  mesoscale spatial variability},
-  journal =      DSR,
-  year =         1998,
-  volume =       {I},
-  number =       46,
-  pages =        {1137--1160}
-}
-
-@ARTICLE{Levy_al_DSR00,
-  author =       {M. L\'{e}vy and L. M\'{e}mery and G. Madec},
-  title =        {Combined effects of mesoscale processes and
-                  atmospheric high-frequency variability on the spring
-                  bloom in the MEDOC area},
-  journal =      DSR,
-  year =         2000,
-  volume =       47,
-  pages =        {527--531}
-}
-
-@BOOK{Large_Yeager_Rep04,
-  title =        {Diurnal to decadal global forcing for ocean and
-                  sea-ice models: the data sets and flux
-                  climatologies},
-  publisher =    {NCAR Technical Note, NCAR/TN-460+STR, CGD Division
-                  of the National Center for Atmospheric Research},
-  year =         2004,
-  author =       {W. G. Large and S. Yeager}
-}
-
-@ARTICLE{Large_al_RG94,
-  author =       {W. G. Large and J. C. McWilliams and S. C. Doney},
-  title =        {Oceanic vertical mixing - a review and a model with
-                  a nonlocal boundary layer parameterization},
-  journal =      {Reviews of Geophysics},
-  year =         1994,
-  volume =       32,
-  pages =        {363--404},
-  doi =          {10.1029/94RG01872},
-}
-
-@ARTICLE{Latif_al_JC06,
-  author =       {M. Latif and C. Böning and J. Willebrand and
-                  A. Biastoch and J. Dengg and N. Keenlyside and
-                  U. Schweckendiek and G. Madec},
-  title =        {Is the Thermohaline Circulation Changing?},
-  journal =      JC,
-  year =         2006,
-  volume =       19,
-  pages =        {4631--4637}
-}
-
-@PHDTHESIS{Lazar_PhD97,
-  author =       {A. Lazar},
-  title =        {La branche froide de la circulation thermohaline -
-                  sensibilit\'{e} \`{a} la diffusion turbulente dans
-                  un mod\`{e}le de circulation g\'{e}n\'{e}rale
-                  id\'{e}alis\'{e}e},
-  school =       {Universit\'{e} Pierre et Marie Curie, Paris, France,
-                  200pp},
-  year =         1997
-}
-
-@ARTICLE{Lazar_al_JPO99,
-  author =       {A. Lazar and G. Madec and P. Delecluse},
-  title =        {The Deep Interior Downwelling, the Veronis Effect,
-                  and Mesoscale Tracer Transport Parameterizations in
-                  an OGCM},
-  journal =      JPO,
-  year =         1999,
-  volume =       29,
-  number =       11,
-  pages =        {2945--2961},
-}
-
-@ARTICLE{Le_Sommer_al_OM09,
-  author =       {J. {Le Sommer} and T. Penduff and S. Theetten and
-                  G. Madec and B.  Barnier},
-  title =        {How momentum advection schemes influence
-                  current-topography interactions at eddy permitting
-                  resolution},
-  journal =      OM,
-  year =         2009,
-  volume =       29,
-  number =       1,
-  pages =        {1--14},
-  doi =          {10.1016/j.ocemod.2008.11.007},
-}
-
-@PHDTHESIS{Leclair_PhD2010,
-  author =       {M. Leclair},
-  title =        {introduction d'une coordonn\'{e}e verticale
-                  arbitrairement Lagrangienne Eul\'{e}rienne dans le
-                  code NEMO, 180pp.},
-  school =       {Universit\'{e} Pierre and Marie Curie},
-  year =         2010
-}
-
-@ARTICLE{Leclair_Madec_OM09,
-  author =       {M. Leclair and G. Madec},
-  title =        {A conservative leap-frog time stepping method},
-  journal =      OM,
-  year =         2009,
-  volume =       30,
-  number =       {2-3},
-  pages =        {88-94},
-  doi =          {10.1016/j.ocemod.2009.06.006},
-}
-
-@ARTICLE{Leclair_Madec_OM11,
-  author =       {M. Leclair and G. Madec},
-  title =        {$\tilde{z}$-coordinate, an Arbitrary
-                  Lagrangian-Eulerian coordinate separating high and
-                  low frequency},
-  journal =      OM,
-  year =         2011,
-  volume =       37,
-  pages =        {139--152},
-  doi =          {10.1016/j.ocemod.2011.02.001},
-}
-
-@ARTICLE{Lele_JCP1992,
-  author =       {S.K. Lele},
-  title =        {Compact finite difference schemes with spectral-like
-                  resolution},
-  journal =      JCP,
-  year =         1992,
-  volume =       103,
-  pages =        {16--42}
-}
-
-@ARTICLE{Lengaigne_al_JC03,
-  author =       {M. Lengaigne and J.-P. Boulanger and C. Menkes and
-                  G. Madec and P.  Delecluse and E. Guilyardi, and
-                  J. Slingo},
-  title =        {The March 1997 Westerly Wind Event and the onset of
-                  the 1997/98 El Niño: Understanding the role of the
-                  atmospheric},
-  journal =      JC,
-  year =         2003,
-  volume =       16,
-  number =       20,
-  pages =        {3330--3343}
-}
-
-@ARTICLE{Lengaigne_al_JGR02,
-  author =       {M. Lengaigne and J.-P. Boulanger and C. Menkes and
-                  S. Masson and G. Madec and P. Delecluse},
-  title =        {Ocean response to the March 1997 Westerly Wind
-                  Event},
-  journal =      JGR,
-  year =         2002,
-  doi =          {10.1029/2001JC000841},
-}
-
-@ARTICLE{Lengaigne_al_JGR03,
-  author =       {M. Lengaigne and G. Madec and G. Alory and
-                  C. Menkes},
-  title =        {Sensitivity of the tropical Pacific Ocean to
-                  isopycnal diffusion on tracer and dynamics},
-  journal =      JGR,
-  year =         2003,
-  volume =       108,
-  number =       {C11},
-  pages =        3345,
-  doi =          {10.1029/2002JC001704},
-}
-
-@ARTICLE{Lengaigne_al_GRL09,
-  author =       {M. Lengaigne and G. Madec and L. Bopp and C. Menkes
-                  and O. Aumont and P. Cadule},
-  title =        {Bio-physical feedbacks in the Arctic Ocean using an
-                  Earth System model},
-  journal =      GRL,
-  year =         2009,
-  volume =       36,
-  pages =        {L21602},
-  doi =          {10.1029/2009GL040145},
-}
-
-@ARTICLE{Lengaigne_al_CD07,
-  author =       {M. Lengaigne and C. Menkes and O. Aumont and
-                  T. Gorgues and L. Bopp and J.-M. Andr\'{e} G. Madec},
-  title =        {Bio-physical feedbacks on the tropical Pacific
-                  climate in a Coupled General Circulation Model},
-  journal =      CD,
-  year =         2007,
-  volume =       28,
-  pages =        {503--516}
-}
-
-@ARTICLE{Leonard1991,
-  author =       {B. P. Leonard},
-  title =        {The ULTIMATE conservative difference scheme applied
-                  to unsteady one--dimensional advection},
-  journal =      {Computer Methods in Applied Mechanics and
-                  Engineering},
-  year =         1991,
-  pages =        {17--74}
-}
-
-@TECHREPORT{Leonard_Rep88,
-  author =       {B. P. Leonard},
-  title =        {Universal limiter for transient interpolation
-                  modelling of the advective transport equations},
-  institution =  {Technical Memorandum TM-100916 ICOMP-88-11, NASA},
-  year =         1988
-}
-
-@ARTICLE{Leonard1979,
-  author =       {B. P. Leonard},
-  title =        {A stable and accurate convective modelling procedure
-                  based on quadratic upstream interpolation},
-  journal =      {Computer Methods in Applied Mechanics and
-                  Engineering},
-  year =         1979,
-  volume =       19,
-  pages =        {59--98},
-}
-
-@TECHREPORT{Levier2007,
-  author =       {B. Levier and A.-M. Tr\'{e}guier and G. Madec and
-                  V. Garnier},
-  title =        {Free surface and variable volume in the NEMO code},
-  institution =  {MERSEA MERSEA IP report WP09-CNRS-STR-03-1A, 47pp,
-                  available on the NEMO web site},
-  year =         2007
-}
-
-@BOOK{levitus82,
-  title =        {Climatological Atlas of the world ocean},
-  publisher =    {NOAA professional paper No. 13, 174pp},
-  year =         1982,
-  author =       {S Levitus },
-  pages =        {173 pp}
-}
-
-@ARTICLE{Li_al_OM2017
-},
-   AUTHOR = {Q Li and B Fox-Kemper and {\O} Breivik and A Webb},
-   YEAR = {2017},
-   TITLE = {Statistical Models of Global Langmuir Mixing}, 
-   JOURNAL = {OM},
-   VOLUME = {113},
-   ISSUE = {May},
-   PAGES = {95--114},
-   DOI = {10.1016/j.ocemod.2017.03.016}
-}
-
-@ARTICLE{Li_Garrett_JMR93,
-  author =       {M. Li and C. Garrett},
-  title =        {Cell merging and the jet/downwelling ratio in
-                  Langmuir circulation},
-  journal =      JMR,
-  year =         1993,
-  volume =       51,
-  pages =        {737--769}
-}
-
-@ARTICLE{Losch2008,
-  author =       {M. Losch},
-  title =        {Modeling ice shelf cavities in a z coordinate ocean
-                  general circulation model},
-  journal =      JGR,
-  year =         2008,
-  volume =       113,
-  number =       {C13},
-}
-
-@TECHREPORT{Lott1989,
-  author =       {F. Lott and G. Madec},
-  title =        {Implementation of bottom topography in the Ocean
-                  General Circulation Model OPA of the LODYC:
-                  formalism and experiments.},
-  institution =  {LODYC, France, 36pp.},
-  year =         1989,
-  number =       3
-}
-
-@ARTICLE{Lott_al_OM90,
-  author =       {F. Lott and G. Madec and J. Verron},
-  title =        {Topographic experiments in an Ocean General
-                  Circulation Model},
-  journal =      OM,
-  year =         1990,
-  volume =       88,
-  pages =        {1--4}
-}
-
-@ARTICLE{Luo_al_JC05,
-  author =       {J.-J. Luo and S. Masson and E. Roeckner and G. Madec
-                  and T. Yamagata},
-  title =        {Reducing climatology bias in an ocean-atmosphere
-                  CGCM with improved coupling physics},
-  journal =      JC,
-  year =         2005,
-  volume =       18,
-  number =       13,
-  pages =        {2344--2360}
-}
-
-@BOOK{Madec_Bk08,
-  title =        {NEMO ocean engine},
-  publisher =    {Note du P\^ole de mod\'{e}lisation, Institut
-                  Pierre-Simon Laplace (IPSL), France, No 27, ISSN No
-                  1288-1619},
-  year =         2008,
-  author =       {G. Madec}
-}
-
-@BOOK{Madec_HDR01,
-  title =        {Le Cycle des Masses d'Eau Oc\'{e}aniqueset sa
-                  variabilit\'{e} dans le Syst\'{e}me Climatique},
-  year =         2001,
-  author =       {G. Madec},
-  pages =        {63pp.},
-  series =       {Habilitation \'{a} Diriger des Recherches,
-                  Universit\'{e} Pierre et Marie Curie}
-}
-
-@PHDTHESIS{Madec_PhD90,
-  author =       {G. Madec},
-  title =        {La formation d'eau profonde et son impact sur la
-                  circulation r\'{e}gionale en M\'{e}diterran\'{e}e
-                  Occidentale - une approche num\'{e}rique},
-  school =       {Universit\'{e} Pierre et Marie Curie, Paris, France,
-                  194pp.},
-  year =         1990,
-  month =        {2 mai}
-}
-
-@ARTICLE{Madec_al_DAO91,
-  author =       {G. Madec and M. Chartier and M. Cr\'{e}pon},
-  title =        {Effect of thermohaline forcing variability on deep
-                  water formation in the Northwestern Mediterranean
-                  Sea - a high resulution three-dimensional study},
-  journal =      DAO,
-  year =         1991,
-  volume =       15,
-  pages =        {301--332}
-}
-
-@ARTICLE{Madec_al_JPO91,
-  author =       {G. Madec and M. Chartier and P. Delecluse and
-                  M. Cr\'{e}pon},
-  title =        {A three-dimensional numerical study of deep water
-                  formation in the Northwestern Mediterranean Sea .},
-  journal =      JPO,
-  year =         1991,
-  volume =       21,
-  pages =        {1349--1371}
-}
-
-@INBOOK{Madec_Crepon_Bk91,
-  chapter =      {Thermohaline-driven deep water formation in the
-                  Northwestern Mediterranean Sea},
-  pages =        {241--265},
-  title =        {Deep convection and deep water formation in the
-                  oceans},
-  publisher =    {Elsevier Oceanographic Series, P.C. Chu and
-                  J.C. Gascard (Eds.)},
-  year =         1991,
-  author =       {G. Madec and M. Cr\'{e}pon}
-}
-
-@ARTICLE{Madec1997,
-  author =       {G. Madec and P. Delecluse},
-  title =        {The OPA/ARPEGE and OPA/LMD Global Ocean-Atmosphere
-                  Coupled Model},
-  journal =      {Int. WOCE Newsletter},
-  year =         1997,
-  volume =       26,
-  pages =        {12--15}
-}
-
-@TECHREPORT{Madec1998,
-  author =       {G. Madec and P. Delecluse and M. Imbard and C. Levy},
-  title =        {OPA 8 Ocean General Circulation Model - Reference
-                  Manual},
-  institution =  {LODYC/IPSL Note 11},
-  year =         1998
-}
-
-@ARTICLE{Madec_Imbard_CD96,
-  author =       {G Madec and M Imbard},
-  title =        {A global ocean mesh to overcome the north pole
-                  singularity},
-  journal =      CD,
-  year =         1996,
-  volume =       12,
-  pages =        {381--388}
-}
-
-@ARTICLE{Madec_al_JPO96,
-  author =       {G. Madec and F. Lott and P. Delecluse and
-                  M. Cr\'{e}pon},
-  title =        {Large-Scale Preconditioning of Deep-Water Formation
-                  in the Northwestern Mediterranean Sea},
-  journal =      JPO,
-  year =         1996,
-  volume =       26,
-  number =       8,
-  pages =        {1393--1408},
-}
-
-@ARTICLE{Madec_al_OM88,
-  author =       {G. Madec and C. Rahier and M. Chartier},
-  title =        {A comparison of two-dimensional elliptic solvers for
-                  the streamfunction in a multilevel OGCM},
-  journal =      OM,
-  year =         1988,
-  volume =       78,
-  pages =        {1-6}
-}
-
-@ARTICLE{Maes_al_CD98,
-  author =       {C. Maes and P. Delecluse and G. Madec},
-  title =        {Impact of westerly wind bursts on the warm pool of
-                  the TOGA-COARE domain in an OGCM},
-  journal =      CD,
-  year =         1998,
-  volume =       14,
-  pages =        {55--70}
-}
-
-@ARTICLE{Maes_al_MWR97,
-  author =       {C. Maes and G. Madec and P. Delecluse},
-  title =        {Sensitivity of an Equatorial Pacific OGCM to the
-                  lateral diffusion},
-  journal =      MWR,
-  year =         1997,
-  volume =       125,
-  number =       5,
-  pages =        {958--971}
-}
-
-@ARTICLE{Maggiore_al_PCE98,
-  author =       {A. Maggiore and M. Zavatarelli and M. G. Angelucci
-                  and N. Pinardi},
-  title =        {Surface heat and water fluxes in the Adriatic Sea:
-                  seasonal and interannual variability},
-  journal =      {Phys Chem Earth},
-  year =         1998,
-  volume =       23,
-  pages =        {561--567}
-}
-
-@ARTICLE{Maltrud1998,
-  author =       {M. E. Maltrud and R. D. Smith and A. J. Semtner and
-                  R. C. Malone},
-  title =        {Global eddy-resolving ocean simulations driven by
-                  1985-1995 atmospheric winds},
-  journal =      JGR,
-  year =         1998,
-  volume =       103,
-  number =       {C13},
-  pages =        {30,825--30,854}
-}
-
-@ARTICLE{Marchesiello2001,
-  author =       { P. Marchesiello and J. Mc Williams and
-                  A. Shchepetkin },
-  title =        {Open boundary conditions for long-term integrations
-                  of Regional Oceanic Models},
-  journal =      OM,
-  year =         2001,
-  volume =       3,
-  pages =        {1--20}
-}
-
-@ARTICLE{Marsaleix_al_OM08,
-  author =       {P. Marsaleix and F. Auclair and J. W. Floor and
-                  M. J. Herrmann and C. Estournel and I. Pairaud and
-                  C. Ulses},
-  title =        {Energy conservation issues in sigma-coordinate
-                  free-surface ocean models},
-  journal =      OM,
-  year =         2008,
-  volume =       20,
-  number =       1,
-  pages =        {61--89},
-  doi =          {10.1016/j.ocemod.2007.07.005},
-}
-
-@Article{Marsh_GMD2015,
-  AUTHOR =       {R. Marsh and V. O. Ivchenko and N. Skliris and
-                  S. Alderson and G. R. Bigg and G. Madec and
-                  A. T. Blaker and Y. Aksenov and B. Sinha and
-                  A. C. Coward and J. Le Sommer and N. Merino and
-                  V. B. Zalesny},
-  TITLE =        {NEMO-ICB (v1.0): interactive icebergs in the NEMO
-                  ocean model globally configured at eddy-permitting
-                  resolution},
-  JOURNAL =      {Geoscientific Model Development},
-  VOLUME =       8,
-  YEAR =         2015,
-  NUMBER =       5,
-  PAGES =        {1547--1562},
-  DOI =          {10.5194/gmd-8-1547-2015}
-}
-
-@article{Martin_Adcroft_OM10,
-  author =       {T. Martin and A. Adcroft},
-  title =        {Parameterizing the fresh-water flux from land ice to
-                  ocean with interactive icebergs in a coupled climate
-                  model},
-  journal =      OM,
-  year =         2010,
-  volume =       34,
-  number =       {3--4},
-  pages =        {111--124},
-  issn =         {1463-5003},
-  doi =          {10.1016/j.ocemod.2010.05.001},
-}
-
-@BOOK{MIT-GCM_2004,
-  title =        {MIT-gcm User Manual},
-  year =         2004,
-  editor =       {MIT Department of EAPS},
-  author =       {J. Marshall and A. Adcroft and J.-M. Campin and
-                  P. Heimbach and A.  Molod and S. Dutkiewicz and
-                  H. Hill and M. Losch and B. Fox-Kemper and
-                  D. Menemenlis and D. Ferreira and E. Hill and
-                  M. Follows and C. Hill and C. Evangelinos and
-                  G. Forget}
-}
-
-@PHDTHESIS{Marti_PhD92,
-  author =       {O. Marti},
-  title =        {Etude de l'oc\'{e}an mondial : mod\'{e}lisation de
-                  la circulation et du transport de traceurs
-                  anthropog\'{e}niques},
-  school =       {Universit\'{e} Pierre et Marie Curie, Paris, France,
-                  201pp},
-  year =         1992
-}
-
-@ARTICLE{Marti_al_CD10,
-  author =       {O. Marti and P. Braconnot and J.-L. Dufresne and
-                  J. Bellier and R.  Benshila and S. Bony and
-                  P. Brockmann and P. Cadule and A. Caubel and F
-                  Codron and S. Denvil and L. Fairhead and T. Fichefet
-                  and M.-A.  Filiberti and M.-A. Foujols and
-                  P. Friedlingstein and H. Goosse and J.-Y. Grandpeix
-                  and E. Guilyardi and F. Hourdin and G. Krinner and
-                  C. L\'{e}vy and G. Madec and J. Mignot and I. Musat
-                  and D. Swingedouw and C. Talandier},
-  title =        {Key features of the IPSL ocean atmosphere model and
-                  its sensitivity to atmospheric resolution},
-  journal =      CD,
-  year =         2010,
-  volume =       34,
-  number =       1,
-  pages =        {1--26},
-  doi =          {10.1007/s00382-009-0640-6},
-}
-
-@ARTICLE{Marti_al_JGR92,
-  author =       {O. Marti and G. Madec and P. Delecluse},
-  title =        {Comment on "Net diffusivity in ocean general
-                  circulation models with nonuniform grids" by
-                  F. L. Yin and I. Y. Fung},
-  journal =      JGR,
-  year =         1992,
-  volume =       97,
-  pages =        {12,763--12,766}
-}
-
-@INBOOK{Masson_al_Bk08,
-  chapter =      {OPA9 - French experiments on the Earth Simulator and
-                  Teraflop Workbench tunings},
-  pages =        {25-34},
-  title =        {In High Performance computing on Vector System 2007,
-                  Stuttgart, Germany},
-  publisher =    {Springer-Verlag},
-  year =         2008,
-  editor =       {Resch M, Roller S, Lammers P, Furui T, Galle M, Bez
-                  W},
-  author =       {S. Masson and M.-A. Foujols and P. Klein and
-                  G. Madec and L. Hua and M. Levy and H. Sasaki and
-                  K. Takahashi and F. Svensson},
-  doi =          {10.1007/978-3-540-74384-2},
-}
-
-@ARTICLE{Masson_al_GRL05,
-  author =       {S. Masson and J.-J. Luo and G. Madec and J. Vialard
-                  and F. Durand and S. Gualdi and E. Guilyardi and
-                  S. Behera and P. Delecluse and A. Navarra and
-                  T. Yamagata},
-  title =        {Impact of barrier layer on winter-spring variability
-                  of the South-Eastern Arabian Sea},
-  journal =      GRL,
-  year =         2005,
-  volume =       32,
-  pages =        {L07703},
-  doi =          {10.1029/2004GL021980},
-}
-
-@Article{Mathiot2017,
-  AUTHOR =       {Mathiot, P. and Jenkins, A. and Harris, C. and Madec, G.},
-  TITLE =        {Explicit representation and parametrised impacts of under ice shelf seas in the ${z}^{\ast}$ coordinate ocean model NEMO 3.6},
-  JOURNAL =      {Geoscientific Model Development},
-  VOLUME =       {10},
-  YEAR =         {2017},
-  NUMBER =       {7},
-  PAGES =        {2849--2874},
-  URL =          {https://www.geosci-model-dev.net/10/2849/2017/},
-  DOI =          {10.5194/gmd-10-2849-2017}
-}
-
-@ARTICLE{McDougall1987,
-  author =       {T. J. McDougall},
-  title =        {Neutral Surfaces},
-  journal =      JPO,
-  year =         1987,
-  volume =       17,
-  number =       11,
-  pages =        {1950--1964},
-}
-
-@ARTICLE{McDougall_Taylor_JMR84,
-  author =       {T. J. McDougall and J. R. Taylor},
-  title =        {Flux measurements across a finger interface at low
-                  values of the stability ratio},
-  journal =      JMR,
-  year =         1984,
-  volume =       42,
-  pages =        {1--14}
-}
-
-@ARTICLE{Mellor_Blumberg_JPO04,
-  author =       {G. Mellor and A. Blumberg},
-  title =        {Wave Breaking and Ocean Surface Layer Thermal
-                  Response},
-  journal =      JPO,
-  volume =       34,
-  number =       3,
-  pages =        {693--698},
-  year =         2004,
-  doi =          {10.1175/2517.1},
-}
-
-@ARTICLE{Mellor_Yamada_1982,
-  author =       {G. L. Mellor and T. Yamada},
-  title =        {Development of a turbulence closure model for
-                  geophysical fluid problems},
-  journal =      RGSP,
-  year =         1982,
-  volume =       20,
-  pages =        {851--875}
-}
-
-@ARTICLE{Menkes_al_JPO06,
-  author =       {C. Menkes and J. Vialard and S C. Kennan and
-                  J.-P. Boulanger and G. Madec},
-  title =        {A modelling study of the three-dimensional heat
-                  budget of Tropical Instability Waves in the
-                  Equatorial Pacific},
-  journal =      JPO,
-  year =         2006,
-  volume =       36,
-  number =       5,
-  pages =        {847--865}
-}
-
-@ARTICLE{Merryfield1999,
-  author =       {W. J. Merryfield and G. Holloway and A. E. Gargett},
-  title =        {A Global Ocean Model with Double-Diffusive Mixing},
-  journal =      JPO,
-  year =         1999,
-  volume =       29,
-  number =       6,
-  pages =        {1124--1142}
-}
-
-@BOOK{Mesinger_Arakawa_Bk76,
-  title =        {Numerical methods used in Atmospheric models},
-  publisher =    {GARP Publication Series No 17},
-  year =         1976,
-  author =       {F. Mesinger and A. Arakawa}
-}
-
-@ARTICLE{Morel_JGR88,
-  author =       {A. Morel},
-  title =        {Optical modeling of the upper ocean in relation to
-                  its biogenous matter content (Case I waters)},
-  journal =      JGR,
-  year =         1988,
-  volume =       93,
-  pages =        {10,749--10,768}
-}
-
-@ARTICLE{Morel_Berthon_LO89,
-  author =       {A. Morel and J.-F. Berthon},
-  title =        {Surface pigments, algal biomass profiles, and
-                  potential production of the euphotic layer:
-                  Relationships reinvestigated in view of
-                  remote-sensing applications},
-  journal =      {Limnol. Oceanogr.},
-  year =         1989,
-  volume =       {34(8)},
-  pages =        {1545--1562}
-}
-
-@ARTICLE{Morel_Maritorena_JGR01,
-  author =       {A. Morel and S. Maritorena},
-  title =        {Bio-optical properties of oceanic waters: a
-                  reappraisal},
-  journal =      JGR,
-  year =         2001,
-  volume =       106,
-  number =       {C4},
-  pages =        {7163--7180}
-}
-
-@ARTICLE{Moun_al_JPO02,
-  author =       {J.N. Moum and D.R. Caldwell and J.D. Nash and
-                  G.D. Gunderson},
-  title =        {Observations of boundary mixing over the continental
-                  slope},
-  journal =      JPO,
-  year =         2002,
-  volume =       32,
-  number =       7,
-  pages =        {2113--2130}
-}
-
-@ARTICLE{Murray_JCP96,
-  author =       {R. J. Murray},
-  title =        {Explicit Generation of Orthogonal Grids for Ocean
-                  Models},
-  journal =      JCP,
-  year =         1996,
-  volume =       126,
-  number =       2,
-  pages =        {251--273},
-}
-
-@ARTICLE{Oddo_al_OS09,
-  author =       {P. Oddo and M. Adani and N. Pinardi and C. Fratianni
-                  and M. Tonani and D. Pettenuzzo},
-  title =        {A nested Atlantic-Mediterranean Sea general
-                  circulation model for operational forecasting},
-  journal =      OS,
-  year =         2009,
-  volume =       5,
-  pages =        {1--13},
-}
-
-@ARTICLE{Oey06,
-   author =      {Lie-Yauw Oey},
-   title =       {An OGCM with movable land-sea boundaries},
-   journal =     {Ocean Modelling},
-   volume =      "13",
-   number =      "2",
-   pages =       "176 - 195",
-   year =        "2006",
-   issn =        "1463-5003",
-   doi =         "https://doi.org/10.1016/j.ocemod.2006.01.001",
-   url =         "http://www.sciencedirect.com/science/article/pii/S1463500306000084",
-}
-
-@PHDTHESIS{Olivier_PhD01,
-  author =       {F. Olivier},
-  title =        {Etude de l'activit\'{e} biologique et de la
-                  circulation oc\'{e}anique dans un jet
-                  g\'{e}ostrophique: le front Alm\'{e}ria-Oran},
-  school =       {Universit\'{e} Pierre et Marie Curie, Paris, France},
-  year =         2001
-}
-
-@ARTICLE{Osborn_JPO80,
-  author =       {T.R. Osborn},
-  title =        {Estimates of the local rate of vertical diffusion
-                  from dissipation measurements},
-  journal =      JPO,
-  year =         1980,
-  volume =       10,
-  pages =        {83--89}
-}
-
-@ARTICLE{Pacanowski_Philander_JPO81,
-  author =       {R.C. Pacanowski and S.G.H. Philander},
-  title =        {Parameterization of Vertical Mixing in Numerical
-                  Models of Tropical Oceans},
-  journal =      JPO,
-  year =         1981,
-  volume =       11,
-  number =       11,
-  pages =        {1443--1451}
-}
-
-@ARTICLE{Pacanowski_Gnanadesikan_MWR98,
-  author =       {R. C. Pacanowski and A. Gnanadesikan},
-  title =        {Transient response in a z-level ocean model that
-                  resolves topography with partial-cells},
-  journal =      MWR,
-  year =         1998,
-  volume =       126,
-  pages =        {3248--3270}
-}
-
-@ARTICLE{Park_al_JC09,
-  author =       {W. Park and N. Keenlyside and M. Latif and
-                  A. Str\¨{o}h and R. Redler and E. Roeckner and
-                  G. Madec},
-  title =        {Tropical Pacific Climate and its Response to Global
-                  Warming in the Kiel Climate Model},
-  journal =      JC,
-  year =         2009,
-  volume =       22,
-  number =       1,
-  pages =        {71--92},
-  doi =          {10.1175/2008JCLI2261.1},
-}
-
-@ARTICLE{Paulson1977,
-  author =       {C. A. Paulson and J. J. Simpson},
-  title =        {Irradiance Measurements in the Upper Ocean},
-  journal =      JPO,
-  year =         1977,
-  volume =       7,
-  number =       6,
-  pages =        {952--956}
-}
-
-@ARTICLE{Payne_JAS72,
-  author =       {R. E. Payne},
-  title =        {Albedo of the Sea Surface},
-  journal =      JAS,
-  year =         1972,
-  volume =       29,
-  pages =        {959--970}
-}
-
-@ARTICLE{Penduff_al_OM06,
-  author =       {T. Penduff and B. Barnier and J.-M. Molines and
-                  G. Madec},
-  title =        {On the use of current meter data to assess the
-                  realism of ocean model simulations},
-  journal =      OM,
-  year =         2006,
-  volume =       11,
-  number =       {3--4},
-  pages =        {399--416}
-}
-
-@ARTICLE{Penduff_al_JGR00,
-  author =       {T. Penduff and B. Barnier and A. Colin de
-                  Verdi\`{e}re},
-  title =        {Self-adapting open boundaries for a regional model
-                  of the eastern North Atlantic},
-  journal =      JGR,
-  year =         2000,
-  volume =       105,
-  pages =        {11,279--11,297}
-}
-
-@ARTICLE{Penduff_al_OS07,
-  author =       {T. Penduff and J. Le Sommer and B. Barnier and
-                  A.M. Treguier and J. Molines and G. Madec},
-  title =        {Influence of numerical schemes on current-topography
-                  interactions in 1/4$^{\circ}$ global ocean
-                  simulations},
-  journal =      OS,
-  year =         2007,
-  volume =       3,
-  pages =        {509--524}
-}
-
-@ARTICLE{Phillips1959,
-  author =       {R. S. Phillips},
-  title =        {Dissipative Operators and Hyperbolic Systems of
-                  Partial Differential Equations},
-  journal =      {Transactions of the American Mathematical Society},
-  year =         1959,
-  volume =       90,
-  number =       2,
-  pages =        {193--254},
-  doi =          {10.2307/1993202},
-}
-
-@ARTICLE{Le_Quere_al_GBC00,
-  author =       {C. Le Qu\'{e}r\'{e} and J. C. Orr and P. Monfray and
-                  O. Aumont and G. Madec},
-  title =        {Interannual variability of the global and regional
-                  sea-air flux of C02 from 1979 to 1993},
-  journal =      GBC,
-  year =         2000,
-  volume =       14,
-  pages =        {1247--1266}
-}
-
-@ARTICLE{Raynaud_al_GRL00,
-  author =       {S. Raynaud and S. Speich and E. Guilyardi and
-                  G. Madec},
-  title =        {Impact of the ocean lateral diffusion on the
-                  ENSO-like variability of a global coupled GCM},
-  journal =      GRL,
-  year =         2000,
-  volume =       27,
-  number =       19,
-  pages =        {3041--3044}
-}
-
-@ARTICLE{Redi_JPO82,
-  author =       {M. H. Redi},
-  title =        {Oceanic isopycnal mixing by coordinate rotation},
-  journal =      JPO,
-  year =         1982,
-  volume =       13,
-  pages =        {1154--1158}
-}
-
-@ARTICLE{Reed_JPO77,
-  author =       {R. K. Reed},
-  title =        {On estimating insolation over the ocean},
-  journal =      JPO,
-  year =         1977,
-  volume =       1,
-  pages =        {874--971}
-}
-
-@ARTICLE{Reverdin1991,
-  author =       {G. Reverdin and P. Delecluse and C. L\'{e}vy and
-                  P. Andrich and A. Morli\`{e}re and J. M. Verstraete},
-  title =        {The near surface tropical Atlantic in 1982-1984 :
-                  results from a numerical simulation and a data
-                  analysis},
-  journal =      PO,
-  year =         1991,
-  volume =       27,
-  pages =        {273--340}
-}
-
-@BOOK{Richtmyer1967,
-  title =        {Difference methods for initial-value problems},
-  publisher =    {Interscience Publisher, Second Edition},
-  year =         1967,
-  author =       {R. D. Richtmyer and K. W. Morton},
-  pages =        {405pp}
-}
-
-@ARTICLE{Robert_JMSJ66,
-  author =       {A. J. Robert},
-  title =        {The integration of a Low order spectral form of the
-                  primitive meteorological equations},
-  journal =      JMSJ,
-  year =         1966,
-  volume =       44,
-  number =       2
-}
-
-@ARTICLE{Rodgers_al_GRL04,
-  author =       {K. Rodgers and O. Aumont and G. Madec and C. Menkes},
-  title =        {Radiocarbon as a thermocline proxy for the eastern
-                  equatorial Pacific},
-  journal =      GRL,
-  year =         2004,
-  volume =       31,
-  pages =        {L14314},
-  doi =          {10.1029/2004GL019764},
-}
-
-@ARTICLE{Rodgers_al_GRL03,
-  author =       {K. Rodgers and B. Blanke and G. Madec and O. Aumont
-                  and P. Ciais and J.-C. Dutay},
-  title =        {Extratropical sources of equatorial pacific
-                  upwelling in an OGCM},
-  journal =      GRL,
-  year =         2003,
-  volume =       30,
-  number =       2,
-  doi =          {10.1029/2002GL016003},
-}
-
-@Article{Rodgers_2014,
-  AUTHOR =       {Rodgers, K. B. and Aumont, O. and Mikaloff Fletcher,
-                  S. E. and Plancherel, Y. and Bopp, L. and de Boyer
-                  Mont\'egut, C. and Iudicone, D. and Keeling,
-                  R. F. and Madec, G. and Wanninkhof, R.},
-  TITLE =        {Strong sensitivity of Southern Ocean carbon uptake
-                  and nutrient cycling to wind stirring},
-  JOURNAL =      {Biogeosciences},
-  VOLUME =       11,
-  YEAR =         2014,
-  NUMBER =       15,
-  PAGES =        {4077--4098},
-  DOI =          {10.5194/bg-11-4077-2014}
-}
-
-@ARTICLE{Rodi_1987,
-  author =       {W. Rodi},
-  title =        {Examples of calculation methods for flow and mixing
-                  in stratified fluids},
-  journal =      JGR,
-  year =         1987,
-  volume =       92,
-  number =       {C5},
-  pages =        {5305--5328}
-}
-
-@INCOLLECTION{Roed1986,
-  author =       {L.P. Roed and C.K. Cooper},
-  title =        {Open boundary conditions in numerical ocean models},
-  booktitle =    {Advanced Physical Oceanography Numerical Modelling},
-  publisher =    { NATO ASI Series, vol. 186.},
-  year =         1986,
-  editor =       {J.J. O'Brien}
-}
-
-@article{Roquet_OM2015,
-  author =       "F. Roquet and G. Madec and T.J. McDougall and
-                  P.M. Barker",
-  title =        "Accurate polynomial expressions for the density and
-                  specific volume of seawater using the TEOS-10
-                  standard ",
-  journal =      OM,
-  volume =       90,
-  pages =        "29--43",
-  year =         2015,
-  issn =         "1463-5003",
-  doi =          "10.1016/j.ocemod.2015.04.002",
-}
-
-@article{Roquet_JPO2015,
-  author =       "F. Roquet and G. Madec and L. Brodeau and
-                  J. Nycander",
-  title =        "Defining a Simplified Yet Realistic Equation of
-                  State for Seawater",
-  journal =      JPO,
-  volume =       45,
-  pages =        "2564--2579",
-  year =         2015,
-  doi =          "10.1175/JPO-D-15-0080.1",
-}
-
-@ARTICLE{Roullet_Madec_JGR00,
-  author =       {G. Roullet and G. Madec},
-  title =        {salt conservation, free surface, and varying levels:
-                  a new formulation for ocean general circulation
-                  models},
-  journal =      JGR,
-  year =         2000,
-  volume =       105,
-  pages =        {23,927--23,942}
-}
-
-@ARTICLE{Rousset_GMD2015,
-  author =       {C. Rousset and M. Vancoppenolle and G. Madec and
-                  T. Fichefet and S. Flavoni and A. Barth\'{e}lemy and
-                  R. Benshila and J. Chanut and C. L\'{e}vy and
-                  S. Masson and F. Vivier },
-  title =        {The Louvain-La-Neuve sea-ice model LIM3.6: Global
-                  and regional capabilities},
-  journal =      {Geoscientific Model Development},
-  year =         2015,
-  volume =       8,
-  pages =        {2991--3005},
-  doi =          {10.5194/gmd-8-2991-2015},
-}
-
-@ARTICLE{Sadourny1975,
-  author =       {R. Sadourny},
-  title =        {The Dynamics of Finite-Difference Models of the
-                  Shallow-Water Equations},
-  journal =      JAS,
-  year =         1975,
-  volume =       32,
-  number =       4,
-  pages =        {680--689},
-}
-
-@ARTICLE{Sarmiento1982,
-  author =       {J. L. Sarmiento and K. Bryan},
-  title =        {Ocean transport model for the North Atlantic},
-  journal =      JGR,
-  year =         1982,
-  volume =       87,
-  pages =        {394--409}
-}
-
-@ARTICLE{Saunders_JAS82,
-  author =       {P. M. Saunders},
-  title =        {{The Temperature at the Ocean-air Interface}},
-  journal =      JAS,
-  year =         1967,
-  volume =       24,
-  pages =        {269-273},
-  doi =          {10.1175/1520-0469(1967)024<0269:TTATOA>2.0.CO;2},
-}
-
-@BOOK{Shchepetkin_McWilliams_Bk08,
-  author =       {A. F. Shchepetkin and J. C. McWilliams},
-  title =        {Handbook of Numerical Analysis, Vol. XIV:
-                  Computational Methods for the Ocean and the
-                  Atmosphere, pp 121-183},
-  publisher =    {P. G. Ciarlet, editor, R. Temam and J. Tribbia,
-                  guest eds., Elsevier Science},
-  year =         2008,
-  pages =        784
-}
-
-@ARTICLE{Shchepetkin_McWilliams_OM05,
-  author =       {A. F. Shchepetkin and J. C. McWilliams},
-  title =        {The regional oceanic modeling system (ROMS) - a
-                  split-explicit, free-surface,
-                  topography-following-coordinate oceanic modelr},
-  journal =      OM,
-  year =         2005,
-  volume =       9,
-  number =       4,
-  pages =        {347--404}
-}
-
-@ARTICLE{Sacha2003,
-  author =       {A. F. Shchepetkin and J. C. McWilliams},
-  title =        {A method for computing horizontal pressure-gradient
-                  force in an oceanic model with a nonaligned vertical
-                  coordinate},
-  journal =      JGR,
-  year =         2003,
-  volume =       108,
-  number =       {C3},
-  pages =        3090,
-  doi =          {10.1029/2001JC001047},
-}
-
-@ARTICLE{Shchepetkin1996,
-  author =       {A. F. Shchepetkin and J. J. O'Brien},
-  title =        {A Physically Consistent Formulation of Lateral
-                  Friction in Shallow-Water Equation Ocean Models},
-  journal =      MWR,
-  year =         1996,
-  volume =       124,
-  number =       6,
-  pages =        {1285--1300}
-}
-
-@ARTICLE{Siddorn_Furner_OM12,
-  author =       {J. Siddorn and R. Furner},
-  title =        {An analytical stretching function that combines the
-                  best attributes of geopotential and
-                  terrain-following vertical coordinates},
-  journal =      OM,
-  year =         2012,
-  pages =        {submitted},
-}
-
-@ARTICLE{Simmons_al_OM04,
-  author =       {H. L. Simmons and S. R. Jayne and
-                  L. C. {St. Laurent} and A. J. Weaver},
-  title =        {Tidally driven mixing in a numerical model of the
-                  ocean general circulation},
-  journal =      OM,
-  year =         2004,
-  pages =        {245--263},
-}
-
-@INBOOK{Smagorinsky_93,
-  author =       {Smagorinsky, J.},
-  chapter =      {Some historical remarks on the use of non-linear
-                  viscosities},
-  title =        {Large Eddy Simulation of Complex Engineering and
-                  Geophysical Flows},
-  pages =        {3--36},
-  year =         1993,
-  publisher =    {Cambridge University Press, B. Galperin and
-                  S. A. Orszag (eds.)},
-}
-
-@ARTICLE{Song_Haidvogel_JCP94,
-  author =       {Y. Song and D. Haidvogel},
-  title =        {A semi-implicit ocean circulation model using a
-                  generalized topography-following coordinate system},
-  journal =      JCP,
-  year =         1994,
-  volume =       115,
-  number =       1,
-  pages =        {228--244}
-}
-
-@ARTICLE{Song1998,
-  author =       {Y. T. Song},
-  title =        {A General Pressure Gradient Formulation for Ocean
-                  Models. Part I: Scheme Design and Diagnostic
-                  Analysis},
-  journal =      MWR,
-  year =         1998,
-  volume =       126,
-  number =       12,
-  pages =        {3213--3230}
-}
-
-@ARTICLE{SongWright1998,
-  author =       {Y. T. Song and D. G. Wright},
-  title =        {A General Pressure Gradient Formulation for Ocean
-                  Models.  Part II: Energy, Momentum, and Bottom
-                  Torque Consistency},
-  journal =      MWR,
-  year =         1998,
-  volume =       126,
-  number =       12,
-  pages =        {3231--3247}
-}
-
-@ARTICLE{Speer_al_Tel00,
-  author =       {K. Speer and E. Guilyardi and G. Madec},
-  title =        {Southern Ocean transformation in a coupled model
-                  with and without eddy mass fluxes},
-  journal =      {Tellus},
-  year =         2000,
-  volume =       {52A},
-  number =       5,
-  pages =        {554--565}
-}
-
-@PHDTHESIS{Speich_PhD92,
-  author =       {S. Speich},
-  title =        {Etude du for\c{c}age de la circulation
-                  g\'{e}n\'{e}rale oc\'{e}anique par les d\'{e}troits
-                  - cas de la mer d'Alboran},
-  school =       {Universit\'{e} Pierre et Marie Curie, Paris, France},
-  year =         1992
-}
-
-@ARTICLE{Speich_al_GRL01,
-  author =       {S. Speich and B. Blanke and G. Madec},
-  title =        {Warm and cold water paths of an OGCM thermohaline
-                  conveyor belt},
-  journal =      GRL,
-  year =         2001,
-  volume =       28,
-  number =       2,
-  pages =        {311--314}
-}
-
-@ARTICLE{Speich_al_JPO96,
-  author =       {S. Speich and G. Madec and M. Cr\'{e}pon},
-  title =        {The circulation in the Alboran Sea - a sensitivity
-                  study},
-  journal =      JPO,
-  year =         1996,
-  volume =       26,
-  number =       3,
-  pages =        {320--340}
-}
-
-@ARTICLE{St_Laurent_Garrett_JPO02,
-  author =       {L.C. {St. Laurent} and C. Garrett},
-  title =        {The role of internal tides in mixing the deep ocean},
-  journal =      JPO,
-  pages =        {2882--2899}
-}
-
-@ARTICLE{St_Laurent_Nash_DSR04,
-  author =       {L.C. {St. Laurent} and J. D. Nash},
-  title =        {An examination of the radiative and dissipative
-                  properties of deep ocean internal tides},
-  journal =      DSR,
-  year =         2004,
-  volume =       {II},
-  number =       51,
-  pages =        {3029--3042},
-  doi =          {10.1016/j.dsr2.2004.09.008},
-}
-
-@ARTICLE{St_Laurent_al_GRL02,
-  author =       {L.C. {St. Laurent} and H.L. Simmons and S.R. Jayne},
-  title =        {Estimating tidally driven mixing in the deep ocean},
-  journal =      GRL,
-  year =         2002,
-  volume =       29,
-  pages =        2106,
-  doi =          {10.1029/2002GL015633},
-}
-
-@ARTICLE{Stacey_JPO99,
-  author =       {M. W. Stacey},
-  title =        {Simulations of the wind-forced near-surface
-                  circulation in Knight Inlet: A parameterization of
-                  the roughness length},
-  journal =      JPO,
-  year =         1999,
-  volume =       29,
-  pages =        {1363--1367},
-}
-
-@ARTICLE{Steele2001,
-  author =       {M. Steele and R. Morley and W. Ermold},
-  title =        {PHC- A Global Ocean Hydrography with a High-Quality
-                  Arctic Ocean},
-  journal =      JC,
-  year =         2001,
-  volume =       14,
-  number =       9,
-  pages =        {2079--2087},
-}
-
-@ARTICLE{Stein_Stein_Nat92,
-  author =       {C. A. Stein and S. Stein},
-  title =        {A model for the global variation in oceanic depth
-                  and heat flow with lithospheric age},
-  journal =      {Nature},
-  year =         1992,
-  volume =       359,
-  pages =        {123--129}
-}
-
-@INCOLLECTION{Stokes_1847,
-  author =       {G.G. Stokes},
-  title =        {On the theory of oscillatory waves},
-  booktitle =    {Transactions of the Cambridge Philosophy Society},
-  year =         1847,
-  volume =       8,
-  Pages =        {441--455}
-}
-
-@ARTICLE{Takaya_al_JGR10,
-  author =       {Y. Takaya and J-R. Bidlot and A. C. M. Beljaars and
-                  P. A. E. M. Janssen},
-  title =        {Refinements to a prognostic scheme of sea surface
-                  skin temperature},
-  journal =      JGR,
-  year =         2010,
-  Volume =       115,
-  Pages =        {C06009},
-  doi =          {10.1029/2009JC005985},
-}
-
-@ARTICLE{Talagrand_JAS72,
-  author =       {O. Talagrand},
-  title =        {On the damping of high-frequency motions in
-                  four-dimensional assimilation of meteorological
-                  data},
-  journal =      JAS,
-  year =         1972,
-  volume =       29,
-  pages =        {1571-1574}
-}
-
-@ARTICLE{Thiem_Berntsen_OM06,
-  author =       {O. Thiem and J. Berntsen},
-  title =        {Internal pressure errors in sigma-coordinate ocean
-                  models due to anisotropy},
-  journal =      OM,
-  year =         2006,
-  volume =       12,
-  number =       {1-2},
-}
-
-@ARTICLE{Timmermann_al_OM05,
-  author =       {R. Timmermann and H. Goosse and G. Madec and
-                  T. Fichefet and C. \'{E}the and V. Duli\`{e}re},
-  title =        {On the representation of high latitude processes in
-                  the ORCA-LIM global coupled sea ice-ocean model},
-  journal =      OM,
-  year =         2005,
-  volume =       8,
-  pages =        {175--201}
-}
-
-@ARTICLE{Tonani_al_OS08,
-  author =       {M. Tonani and N. Pinardi and S. Dobricic and
-                  I. Pujol and C. Fratianni},
-  title =        {A high-resolution free-surface model of the
-                  Mediterranean Sea},
-  journal =      OS,
-  year =         2008,
-  volume =       4,
-  pages =        {1--14}
-}
-
-@ARTICLE{Treguier_JGR92,
-  author =       {A.M. Tr\'{e}guier},
-  title =        {Kinetic energy analysis of an eddy resolving,
-                  primitive equation North Atlantic model},
-  journal =      JGR,
-  year =         1992,
-  volume =       97,
-  pages =        {687--701}
-}
-
-@ARTICLE{Treguier_al_JGR01,
-  author =       {A.M. Tr\'{e}guier and B. Barnier and A.P. de Miranda
-                  and J.M. Molines and N. Grima and M. Imbard and
-                  G. Madec and C. Messager and T. Reynaud and
-                  S. Michel},
-  title =        {An Eddy Permitting model of the Atlantic
-                  circulation: evaluating open boundary conditions},
-  journal =      JGR,
-  year =         2001,
-  volume =       106,
-  pages =        {22,115--22,129}
-}
-
-@ARTICLE{Treguier_al_DSR03,
-  author =       {A.-M. Tr\'{e}guier and O. Boedel and B. Barnier and
-                  G. Madec},
-  title =        {Agulhas eddy fluxes in a 1/6^o Atlantic model},
-  journal =      DSR,
-  year =         2003,
-  pages =        {251--280}
-}
-
-@ARTICLE{Treguier1996,
-  author =       {A.-M. Tr\'{e}guier and J. Dukowicz and K. Bryan},
-  title =        {Properties of nonuniform grids used in ocean general
-                  circulation models},
-  journal =      JGR,
-  year =         1996,
-  volume =       101,
-  pages =        {20,877--20,881}
-}
-
-@ARTICLE{Treguier_al_OS07,
-  author =       {A.-M. Tr\'{e}guier and M. H. England and
-                  S. R. Rintoul and G. Madec and J. Le Sommer and
-                  J.-M. Molines},
-  title =        {Southern Ocean overturning across streamlines in an
-                  eddying simulation of the Antarctic Circumpolar
-                  Current},
-  journal =      OS,
-  year =         2007,
-  volume =       4,
-  pages =        {653--698}
-}
-
-@ARTICLE{Treguier_al_OD06,
-  author =       {A.-M. Tr\'{e}guier and C. Gourcuff and P. Lherminier
-                  and H. Mercier and B. Barnier and G. Madec and
-                  J.-M. Molines and T. Penduff and L. Czeschel and
-                  C. Böning},
-  title =        {Internal and forced variability along a section
-                  between Greenland and Portugal in the CLIPPER
-                  Atlantic model},
-  journal =      OD,
-  year =         2006,
-  volume =       56,
-  pages =        {568--580},
-  doi =          {10.1007/s10236-006-0069-y},
-}
-
-@ARTICLE{Treguier1997,
-  author =       {A. M. Tr\'{e}guier and I. M. Held and
-                  V. D. Larichev},
-  title =        {Parameterization of Quasigeostrophic Eddies in
-                  Primitive Equation Ocean Models},
-  journal =      JPO,
-  year =         1997,
-  volume =       27,
-  number =       4,
-  pages =        {567--580}
-}
-
-@ARTICLE{Tu_Tsuang_GRL05,
-  title =        {{Cool-skin simulation by a one-column ocean model}},
-  author =       {{C-Y}. Tu and {B-J}. Tsuang},
-  journal =      GRL,
-  year =         2005,
-  volume =       32,
-  pages =        {L22602},
-  doi =          {10.1029/2005GL024252},
-}
-
-@ARTICLE{Umlauf_Burchard_JMS03,
-  author =       {L. Umlauf and H. Burchard},
-  title =        {A generic length-scale equation for geophysical
-                  turbulence models},
-  journal =      JMS,
-  year =         2003,
-  volume =       61,
-  number =       2,
-  pages =        {235--265}
-}
-
-@ARTICLE{Umlauf_Burchard_CSR05,
-  author =       {L. Umlauf and H. Burchard},
-  title =        {Second-order turbulence closure models for
-                  geophysical boundary layers. A review of recent
-                  work},
-  journal =      JMS,
-  year =         2005,
-  volume =       25,
-  pages =        {795--827}
-}
-
-@BOOK{UNESCO1983,
-  title =        {Algorithms for computation of fundamental property
-                  of sea water},
-  publisher =    {Techn. Paper in Mar. Sci, 44, UNESCO},
-  year =         1983,
-  author =       {UNESCO}
-}
-
-@TECHREPORT{OASIS2006,
-  author =       {S. Valcke},
-  title =        {OASIS3 User Guide (prism\_2-5)},
-  institution =  {PRISM Support Initiative Report No 3, CERFACS,
-                  Toulouse, France},
-  year =         2006,
-  pages =        {64pp}
-}
-
-@TECHREPORT{Valcke_al_Rep00,
-  author =       {S. Valcke and L. Terray and A. Piacentini },
-  title =        {The OASIS Coupled User Guide Version 2.4},
-  institution =  {CERFACS},
-  year =         2000,
-  number =       {TR/CMGC/00-10}
-}
-
-@ARTICLE{Vancoppenolle_al_OM09b,
-  author =       {M. Vancoppenolle and T. Fichefet and H. Goosse},
-  title =        {Simulating the mass balance and salinity of Arctic
-                  and Antarctic sea ice. 2.  Importance of sea ice
-                  salinity variations},
-  journal =      OM,
-  year =         2009,
-  volume =       27,
-  pages =        {54--69}
-}
-
-@book{Vallis06,
-  author =       {Vallis, G. K.},
-  title =        {Atmospheric and Oceanic Fluid Dynamics},
-  publisher =    {Cambridge University Press},
-  address =      {Cambridge, U.K.},
-  year =         2006,
-  pages =        745,
-}
-
-@ARTICLE{Vancoppenolle_al_OM09a,
-  author =       {M. Vancoppenolle and T. Fichefet and H. Goosse and
-                  S. Bouillon and G. Madec and M. A. Morales Maqueda},
-  title =        {Simulating the mass balance and salinity of Arctic
-                  and Antarctic sea ice. 1. Model description and
-                  validation},
-  journal =      OM,
-  year =         2009,
-  volume =       27,
-  pages =        {33--53},
-  doi =          {10.1016/j.ocemod.2008.10.005},
-}
-
-@ARTICLE{Vialard_al_JPO01,
-  author =       {J. Vialard and C. Menkes and J.-P. Boulanger and
-                  P. Delecluse and E. Guilyardi and M.J. McPhaden and
-                  G. Madec},
-  title =        {A Model Study of Oceanic Mechanisms Affecting
-                  Equatorial Pacific Sea Surface Temperature During
-                  the 1997-98 El Niño},
-  journal =      JPO,
-  year =         2001,
-  volume =       31,
-  number =       7,
-  pages =        {1649--1675}
-}
-
-@ARTICLE{Warner_al_OM05,
-  author =       {J. C. Warner and C. R. Sherwood and H. G. Arango and
-                  R. P. Signell},
-  title =        {Performance of four turbulence closure models
-                  implemented using a generic length scale method},
-  journal =      OM,
-  year =         2005,
-  volume =       8,
-  pages =        {81--113},
-  doi =          {10.1016/j.ocemod.2003.12.003},
-}
-
-@ARTICLE{WarnerEtal13,
-   author =      {John C. Warner and Zafer Defne and Kevin Haas and
-                  Hernan G. Arango},
-   title =       {A wetting and drying scheme for ROMS},
-   journal =     "Computers \& Geosciences",
-   volume =      "58", 
-   pages =       "54 - 61",
-   year =        "2013",
-   issn =        "0098-3004",
-   doi =         "https://doi.org/10.1016/j.cageo.2013.05.004",
-   url =         "http://www.sciencedirect.com/science/article/pii/S0098300413001362",
-}
-
-@ARTICLE{Weatherly_JMR84,
-  author =       {G. L. Weatherly},
-  title =        {An estimate of bottom frictional dissipation by Gulf
-                  Stream fluctuations},
-  journal =      JMR,
-  year =         1984,
-  volume =       42,
-  number =       2,
-  pages =        {289--301}
-}
-
-@ARTICLE{Weaver_Eby_JPO97,
-  author =       {A. J. Weaver and M. Eby},
-  title =        {On the numerical implementation of advection schemes
-                  for use in conjuction with various mixing
-                  parameterizations in the GFDL ocean model},
-  journal =      JPO,
-  year =         1997,
-  volume =       27
-}
-
-@ARTICLE{Webb_al_JAOT98,
-  author =       {D. J. Webb and B. A. de Cuevas and C. S. Richmond},
-  title =        {Improved Advection Schemes for Ocean Models},
-  journal =      JAOT,
-  year =         1998,
-  volume =       15,
-  number =       5,
-  pages =        {1171--1187},
-}
-
-@ARTICLE{White_al_JCP09,
-  author =       {L. White and A. Adcroft and R. Hallberg},
-  title =        {High-order regridding-remapping schemes for
-                  continuous isopycnal and generalized coordinates in
-                  ocean models},
-  journal =      JC,
-  year =         2009,
-  volume =       228,
-  pages =        {8665--8692}
-}
-
-@ARTICLE{Wilcox_1988,
-  author =       {D. C. Wilcox},
-  title =        {Reassessment of the scale-determining equation for
-                  advanced turbulence models},
-  journal =      {AIAA journal},
-  year =         1988,
-  volume =       26,
-  number =       11,
-  pages =        {1299--1310}
-}
-
-@ARTICLE{Willebrand_al_PO01,
-  author =       {J. Willebrand and B. Barnier and C. Boning and
-                  C. Dieterich and P.  D. Killworth and C. Le Provost
-                  and Y. Jia and J.-M. Molines and A. L. New},
-  title =        {Circulation characteristics in three eddy-permitting
-                  models of the North Atlantic},
-  journal =      PO,
-  year =         2001,
-  volume =       48,
-  number =       2,
-  pages =        {123--161}
-}
-
-@ARTICLE{Williams_al_DAO09,
-  author =       {P.D. Williams and E. Guilyardi and G. Madec and
-                  S. Gualdi and E. Scoccimarro},
-  title =        {The role of mean ocean salinity on climate},
-  journal =      DAO,
-  year =         2010,
-  volume =       49,
-  number =       {2-3},
-  pages =        {108--123},
-  doi =          {10.1016/j.dynatmoce.2009.02.001},
-}
-
-@ARTICLE{Williams_al_GRL07,
-  author =       {P.D. Williams and E. Guilyardi and R. Sutton and
-                  J.M. Gregory and G. Madec},
-  title =        {A new feedback on climate change from the
-                  hydrological cycle},
-  journal =      GRL,
-  year =         2007,
-  volume =       34,
-  pages =        {L08706},
-  doi =          {10.1029/2007GL029275},
-}
-
-@ARTICLE{Williams_al_CD06,
-  author =       {P.D. Williams and E. Guilyardi and R. Sutton and
-                  J.M. Gregory and G. Madec},
-  title =        {On the climate response of the low-latitude Pacific
-                  ocean to changes in the global freshwater cycle},
-  journal =      CD,
-  year =         2006,
-  volume =       27,
-  pages =        {593--611}
-}
-
-@ARTICLE{Zalesak_JCP79,
-  author =       {S. T. Zalesak},
-  title =        {Fully multidimensional flux corrected transport
-                  algorithms for fluids},
-  journal =      JCP,
-  year =         1979,
-  volume =       31
-}
-
-@ARTICLE{Zhang_Endoh_JGR92,
-  author =       {Zhang, R.-H. and Endoh, M.},
-  title =        {A free surface general circulation model for the
-                  tropical Pacific Ocean},
-  journal =      JGR,
-  year =         1992,
-  volume =       97,
-  pages =        {11,237--11,255}
-}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/NEMO_manual.ist
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/NEMO_manual.ist	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/NEMO_manual.ist	(revision 11422)
@@ -1,3 +1,1 @@
-delim_0 "\\dotfill"
-delim_1 "\\dotfill"
-delim_2 "\\dotfill"
+link ../../global/index.ist
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/NEMO_manual.sty
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/NEMO_manual.sty	(revision 10999)
+++ 	(revision )
@@ -1,176 +1,0 @@
-%% ==============================================================================
-%% NEMO_manual.sty: all customizations (packages, styles, cmds)
-%% ==============================================================================
-
-
-%% LaTeX packages
-%% ==============================================================================
-
-\usepackage{natbib}           %% bib
-\usepackage{caption}          %% caption
-\usepackage{xcolor}           %% color
-\usepackage{times}            %% font
-\usepackage{hyperref}         %% hyper
-\usepackage{idxlayout}        %% index
-\usepackage{enumitem}         %% list
-\usepackage{minted}           %% listing
-\usepackage{amsmath}          %% maths
-\usepackage{fancyhdr}         %% page
-\usepackage{minitoc}          %% toc
-\usepackage{subfiles}         %% subdocs
-\usepackage[utf8]{inputenc}   %% input encoding
-\usepackage{draftwatermark}   %% watermark
-\usepackage{textcomp}         %% Companion fonts
-
-%% Extensions in bundle package
-
-\usepackage{amssymb, graphicx, makeidx, tabularx}
-
-
-%% Configuration
-
-\captionsetup{margin=10pt, font={small}, labelsep=colon, labelfont={bf}}
-\graphicspath{{../../../figures/}}
-\hypersetup{
-	pdftitle={NEMO ocean engine}, pdfauthor={Gurvan Madec, and NEMO System Team},
-	colorlinks
-}
-\idxlayout{font=footnotesize, columns=3}
-\renewcommand{\bibfont}{\footnotesize}
-\renewcommand{\bibsep}{3pt}
-
-
-%% Styles
-%% ==============================================================================
-
-\pagestyle{fancy}
-\bibliographystyle{../main/ametsoc}
-
-%% Additionnal fonts
-
-\DeclareMathAlphabet{\mathpzc}{OT1}{pzc}{m}{it}
-
-
-%% Page layout
-
-\fancyhf{}
-\fancyhead[LE,RO]{\bfseries\thepage}
-\fancyhead[LO]{\bfseries\hspace{-0em}\rightmark}
-\renewcommand{\sectionmark}[1]{\markright{\thesection.\ #1}}
-\fancyhead[RE]{\bfseries\leftmark}
-\renewcommand{\chaptermark}[1]{\markboth{#1}{}}
-\renewcommand{\headrulewidth}{0.5pt}
-\renewcommand{\footrulewidth}{0pt  }
-\addtolength{\headheight}{2.6pt}
-
-
-%% Catcodes
-
-\makeatletter
-\def\LigneVerticale{\vrule height 5cm depth 2cm\hspace{0.1cm}\relax}
-\def\LignesVerticales{\let\LV\LigneVerticale\LV\LV\LV\LV\LV\LV\LV\LV\LV\LV}
-\def\GrosCarreAvecUnChiffre#1{
-	\rlap{\vrule height 0.8cm width 1cm depth 0.2cm}
-	\rlap{\hbox to 1cm{\hss\mbox{\color{white} #1}\hss}}
- 	\vrule height 0pt width 1cm depth 0pt
-}
-\def\@makechapterhead#1{
-	\hbox{
-		\huge\LignesVerticales\hspace{-0.5cm}
-		\GrosCarreAvecUnChiffre{\thechapter}\hspace{0.2cm}
-		\hbox{#1}
-	}
-	\par\vskip
-1cm
-}
-\def\@makeschapterhead#1{
-	\hbox{
-		\huge\LignesVerticales
-		\hbox{#1}
-	}
-	\par\vskip
-2cm
-}
-\def\cleardoublepage{\clearpage\if@twoside \ifodd\c@page\else
-  \hbox{}
-  \vspace*{\fill}
-  \vspace{\fill}
-  \thispagestyle{empty}
-  \newpage
-  \if@twocolumn\hbox{}\newpage\fi\fi\fi}
-\def\@seccntformat#1{\protect\makebox[0pt][r]{\csname the#1\endcsname\quad}}
-\makeatother
-
-
-%% Global custom commands: \newcommand{<name>}[<args>][<first argument value>]{<code>}
-%% ==============================================================================
-
-%% NEMO and Fortran in small capitals
-\newcommand{\NEMO}{\textsc{nemo}}
-\newcommand{\fortran}{\textsc{Fortran}}
-\newcommand{\fninety}{\textsc{Fortran 90}}
-
-%% Common aliases
-\renewcommand{\deg}[1][]{\ensuremath{^{\circ}#1}}
-\newcommand{\zstar }{\ensuremath{z^\star}}
-\newcommand{\sstar }{\ensuremath{s^\star}}
-\newcommand{\ztilde}{\ensuremath{\tilde z}}
-\newcommand{\stilde}{\ensuremath{\tilde s}}
-\newcommand{\ie}{\ensuremath{i.e.}}
-\newcommand{\eg}{\ensuremath{e.g.}}
-
-%% Inline maths
-\newcommand{\fractext}[2]{\textstyle \frac{#1}{#2}}
-\newcommand{\rdt}{\Delta t}
-
-%% Text env. for Gurvan
-\newcommand{\gmcomment}[1]{}
-
-%% Index entries (italic font for files, preformat for code)
-\newcommand{\hf}[1]{\textit{#1.h90}            \index{h90 file!#1}}
-\newcommand{\ifile}[1]{\textit{#1.nc}          \index{Input NetCDF files!#1.nc}}
-\newcommand{\jp}[1]{\texttt{#1}                \index{Model parameters!#1}}
-\newcommand{\key}[1]{\texttt{\textbf{key\_#1}} \index{CPP keys!key\_#1}}
-\newcommand{\mdl}[1]{\textit{#1.F90}           \index{Modules!#1}}
-\newcommand{\ngn}[1]{\texttt{#1}               \index{Namelist Group Name!#1}}
-\newcommand{\np}[1]{\texttt{#1}                \index{Namelist variables!#1}}
-\newcommand{\rou}[1]{\texttt{#1}               \index{Routines!#1}}
-
-%% Maths
-\newcommand{\lt}{\left}
-\newcommand{\rt}{\right}
-\newcommand{\vect}[1]{\ensuremath{\mathbf{#1}}}
-\newcommand{\pd}[2][]{\ensuremath{\frac{\partial #1}{\partial #2}}}
-
-%% Shortened DOI in bibliography
-\newcommand{\doi}[1]{\href{http://dx.doi.org/#1}{doi:#1}}
-
-%% Namelists inclusion
-\newcommand{\nlst}[1]{\forfile{../../../namelists/#1}}
-
-
-%% Minted package: syntax highlighting configuration
-%% ==============================================================================
-
-%% Global highlighting style
-\setminted{style=emacs, fontsize=\scriptsize, breaklines, frame=leftline}
-\setminted[xml]{style=borland} %% Specific per language
-
-%% Oneliner
-\newmint[forline]{fortran}{}   % \forline|...|
-\newmint[xmlline]{xml}{}       % \xmlline|...|
-\newmint[cmd]{console}{}       % \cmd|...|
-
-%% Multi-lines
-\newminted[forlines]{fortran}{}   % \begin{forlines}
-\newminted[xmllines]{xml}{}       % \begin{xmllines}
-\newminted[cmds]{console}{}       % \begin{cmds}
-\newminted[clines]{c}{}           % \begin{clines}
-
-%% File
-\newmintedfile[forfile]{fortran}{}   % \forfile{../namelists/nam...}
-
-%% Inline
-\newmintinline[forcode]{fortran}{fontsize=auto, frame=lines}   % \forcode{...}
-\newmintinline[xmlcode]{xml}{    fontsize=auto, frame=lines}   % \xmlcode{...}
-\newmintinline[snippet]{console}{fontsize=auto, frame=lines}   % \snippet{...}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/NEMO_manual.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/NEMO_manual.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/NEMO_manual.tex	(revision 11422)
@@ -1,131 +1,1 @@
-%% ==============================================================================
-%% NEMO Reference Manual
-%% ==============================================================================
-
-
-%% Run ./PDF_creation.sh to generate the manual with latexmk
-
-
-%% Preamble
-%% ==============================================================================
-
-%% Document layout
-\documentclass{book}
-
-%% Custom style (.sty)
-\usepackage{../main/NEMO_manual}
-
-%% Include references and index for single subfile compilation
-\newcommand{\biblio}{\bibliography{../main/NEMO_manual}}
-\newcommand{\pindex}{\printindex}
-
-\makeindex
-
-%% End of common preamble between main and sub-files
-\begin{document}
-
-%% Override custom cmds for full manual compilation
-\renewcommand{\biblio}{}
-\renewcommand{\pindex}{}
-
-
-%% Frontmatter
-%% ==============================================================================
-
-%% Frontpage
-\title{
-  \includegraphics[height=0.05\textheight]{CMCC}\hfill
-  \includegraphics[height=0.05\textheight]{CNRS}\hfill
-  \includegraphics[height=0.05\textheight]{MOI} \hfill
-  \includegraphics[height=0.05\textheight]{UKMO}\hfill
-  \includegraphics[height=0.05\textheight]{NERC}       \\
-  \includegraphics[ width=0.8\textwidth  ]{NEMO_grey}  \\
-  {\Huge NEMO ocean engine}                            \\
-}
-\author{
-  \Large Gurvan Madec and NEMO System Team
-  \thanks{
-    Yevgeny Aksenov, Mirek Andrejczuk, Mike Bell, Romain Bourdalle-Badie, Cl\'{e}ment Bricaud,
-    J\'{e}r\^{o}me Chanut, Stefania Ciliberti, Emanuela Clementi, Andrew Coward, Damiano Delrosso,
-    Massimiliano Drudi, Christian Eth\'{e}, Simona Flavoni, Doroteaciro Iovino, Claire L\'{e}vy, Tomas Lovato,
-    Nicolas Martin, S\'{e}bastien Masson, Pierre Mathiot, Gelsomina Mattia, Francesca Mele, Silvia Mocavero,
-    Simon M\"{u}ller, George Nurser, Enda O'Dea, Julien Paul, Cl\'{e}ment Rousset, Dave Storkey,
-    Martin Vancoppenolle
-  }                                                        \\
-                                                           \\
-  \textit{Issue 27, Notes du P\^{o}le de mod\'{e}lisation} \\
-  \textit{Institut Pierre-Simon Laplace (IPSL)}            \\
-  \textit{ISSN 1288-1619}
-}
-\date{Version 4.0 -- January 2019}
-%\date{\today}
-
-\maketitle
-\frontmatter
-
-
-%% ToC i.e. Table of Contents
-\dominitoc
-\tableofcontents
-
-
-%% Mainmatter
-%% ==============================================================================
-
-\mainmatter
-
-%% Foreword
-\subfile{../subfiles/foreword}
-
-%% Introduction
-\subfile{../subfiles/introduction}
-
-%% Chapters
-\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
-
-%% Appendix
-\appendix
-\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_D}					% Coding rules
-
-%% Not included
-%\subfile{../subfiles/chap_conservation}	%
-%\subfile{../subfiles/annex_E}				% Notes on some on going staff
-
-
-%% Backmatter
-%% ==============================================================================
-
-\backmatter
-
-%% Bibliography
-\cleardoublepage
-\phantomsection
-\addcontentsline{toc}{chapter}{Bibliography}
-\bibliography{../main/NEMO_manual}
-
-%% Index
-\cleardoublepage
-\phantomsection
-\addcontentsline{toc}{chapter}{Index}
-\printindex
-
-
-\end{document}
+link ../../global/document.tex
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/ametsoc.bst
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/ametsoc.bst	(revision 10999)
+++ 	(revision )
@@ -1,1662 +1,0 @@
-%%
-%% This is file `ametsoc7.bst',
-%% generated with the docstrip utility.
-%%
-%% The original source files were:
-%%
-%% merlin.mbs  (with options: `ay,nat,nm-rev1,ed-rev,jnrlst,nmdash,nmd-3,dt-beg,yr-com,yrp-col,thtit-a,vol-2bf,vnum-sp,volp-com,pgsep-s,num-xser,numser,ser-vol,bkpg-x,pg-bk,pre-edn,agu-doi,doi,edparc,bkedcap,edby,edbyy,blk-tit,in-x,pp,ed,abr,ednx,ord,jabr,eprint,url,url-nt,em-it,nfss,')
-%% ----------------------------------------
-%% *** Bibliography style file for ALL AMS Journals...version 1.0  ***
-%% *** Brian Papa - American Meteorological Society ***
-%% 
-%% Copyright 1994-2004 Patrick W Daly
- % ===============================================================
- % IMPORTANT NOTICE:
- % This bibliographic style (bst) file has been generated from one or
- % more master bibliographic style (mbs) files, listed above.
- %
- % This generated file can be redistributed and/or modified under the terms
- % of the LaTeX Project Public License Distributed from CTAN
- % archives in directory macros/latex/base/lppl.txt; either
- % version 1 of the License, or any later version.
- % ===============================================================
- % Name and version information of the main mbs file:
- % \ProvidesFile{merlin.mbs}[2004/02/09 4.13 (PWD, AO, DPC)]
- %   For use with BibTeX version 0.99a or later
- %-------------------------------------------------------------------
- % This bibliography style file is intended for texts in ENGLISH
- % This is an author-year citation style bibliography. As such, it is
- % non-standard LaTeX, and requires a special package file to function properly.
- % Such a package is    natbib.sty   by Patrick W. Daly
- % The form of the \bibitem entries is
- %   \bibitem[Jones et al.(1990)]{key}...
- %   \bibitem[Jones et al.(1990)Jones, Baker, and Smith]{key}...
- % The essential feature is that the label (the part in brackets) consists
- % of the author names, as they should appear in the citation, with the year
- % in parentheses following. There must be no space before the opening
- % parenthesis!
- % With natbib v5.3, a full list of authors may also follow the year.
- % In natbib.sty, it is possible to define the type of enclosures that is
- % really wanted (brackets or parentheses), but in either case, there must
- % be parentheses in the label.
- % The \cite command functions as follows:
- %   \citet{key} ==>>                Jones et al. (1990)
- %   \citet*{key} ==>>               Jones, Baker, and Smith (1990)
- %   \citep{key} ==>>                (Jones et al., 1990)
- %   \citep*{key} ==>>               (Jones, Baker, and Smith, 1990)
- %   \citep[chap. 2]{key} ==>>       (Jones et al., 1990, chap. 2)
- %   \citep[e.g.][]{key} ==>>        (e.g. Jones et al., 1990)
- %   \citep[e.g.][p. 32]{key} ==>>   (e.g. Jones et al., p. 32)
- %   \citeauthor{key} ==>>           Jones et al.
- %   \citeauthor*{key} ==>>          Jones, Baker, and Smith
- %   \citeyear{key} ==>>             1990
- %---------------------------------------------------------------------
-
-ENTRY
-  { address
-    archive
-    author
-    booktitle
-    chapter
-    doi
-    edition
-    editor
-    eid
-    eprint
-    howpublished
-    department
-    institution
-    journal
-    key
-    month
-    note
-    number
-    organization
-    pages
-    publisher
-    school
-    series
-    title
-    type
-    url
-    volume
-    year
-  }
-  {}
-  { label extra.label sort.label short.list }
-INTEGERS { output.state before.all mid.sentence after.sentence after.block }
-FUNCTION {init.state.consts}
-{ #0 'before.all :=
-  #1 'mid.sentence :=
-  #2 'after.sentence :=
-  #3 'after.block :=
-}
-STRINGS { s t}
-FUNCTION {output.nonnull}
-{ 's :=
-  output.state mid.sentence =
-    { ", " * write$ }
-    { output.state after.block =
-        { add.period$ write$
-          newline$
-          "\newblock " write$
-        }
-        { output.state before.all =
-            'write$
-            { add.period$ " " * write$ }
-          if$
-        }
-      if$
-      mid.sentence 'output.state :=
-    }
-  if$
-  s
-}
-FUNCTION {output}
-{ duplicate$ empty$
-    'pop$
-    'output.nonnull
-  if$
-}
-FUNCTION {output.check}
-{ 't :=
-  duplicate$ empty$
-    { pop$ "empty " t * " in " * cite$ * warning$ }
-    'output.nonnull
-  if$
-}
-FUNCTION {fin.entry}
-{ add.period$
-  write$
-  newline$
-}
-
-FUNCTION {new.block}
-{ output.state before.all =
-    'skip$
-    { after.block 'output.state := }
-  if$
-}
-FUNCTION {new.sentence}
-{ output.state after.block =
-    'skip$
-    { output.state before.all =
-        'skip$
-        { after.sentence 'output.state := }
-      if$
-    }
-  if$
-}
-FUNCTION {add.blank}
-{  " " * before.all 'output.state :=
-}
-
-FUNCTION {date.block}
-{
-  ":" *
-  add.blank
-}
-
-FUNCTION {not}
-{   { #0 }
-    { #1 }
-  if$
-}
-FUNCTION {and}
-{   'skip$
-    { pop$ #0 }
-  if$
-}
-FUNCTION {or}
-{   { pop$ #1 }
-    'skip$
-  if$
-}
-FUNCTION {new.block.checkb}
-{ empty$
-  swap$ empty$
-  and
-    'skip$
-    'new.block
-  if$
-}
-FUNCTION {field.or.null}
-{ duplicate$ empty$
-    { pop$ "" }
-    'skip$
-  if$
-}
-FUNCTION {emphasize}
-{ duplicate$ empty$
-    { pop$ "" }
-    { "\textit{" swap$ * "}" * }
-  if$
-}
-FUNCTION {bolden}
-{ duplicate$ empty$
-    { pop$ "" }
-    { "\textbf{" swap$ * "}" * }
-  if$
-}
-FUNCTION {tie.or.space.prefix}
-{ duplicate$ text.length$ #3 <
-    { "~" }
-    { " " }
-  if$
-  swap$
-}
-
-FUNCTION {capitalize}
-{ "u" change.case$ "t" change.case$ }
-
-FUNCTION {space.word}
-{ " " swap$ * " " * }
- % Here are the language-specific definitions for explicit words.
- % Each function has a name bbl.xxx where xxx is the English word.
- % The language selected here is ENGLISH
-FUNCTION {bbl.and}
-{ "and"}
-
-FUNCTION {bbl.etal}
-{ "et~al." }
-
-FUNCTION {bbl.editors}
-{ "Eds." }
-
-FUNCTION {bbl.editor}
-{ "Ed." }
-
-FUNCTION {bbl.edby}
-{ "edited by" }
-
-FUNCTION {bbl.edition}
-{ "ed." }
-
-FUNCTION {bbl.volume}
-{ "Vol." }
-
-FUNCTION {bbl.of}
-{ "of" }
-
-FUNCTION {bbl.number}
-{ "No." }
-
-FUNCTION {bbl.nr}
-{ "No." }
-
-FUNCTION {bbl.in}
-{ "in" }
-
-FUNCTION {bbl.pages}
-{ "pp." }
-
-FUNCTION {bbl.page}
-{ "p." }
-
-FUNCTION {bbl.chapter}
-{ "chap." }
-
-FUNCTION {bbl.techrep}
-{ "Tech. Rep." }
-
-FUNCTION {bbl.mthesis}
-{ "Master's thesis" }
-
-FUNCTION {bbl.phdthesis}
-{ "Ph.D. thesis" }
-
-FUNCTION {bbl.first}
-{ "1st" }
-
-FUNCTION {bbl.second}
-{ "2d" }
-
-FUNCTION {bbl.third}
-{ "3d" }
-
-FUNCTION {bbl.fourth}
-{ "4th" }
-
-FUNCTION {bbl.fifth}
-{ "5th" }
-
-FUNCTION {bbl.st}
-{ "st" }
-
-FUNCTION {bbl.nd}
-{ "d" }
-
-FUNCTION {bbl.rd}
-{ "d" }
-
-FUNCTION {bbl.th}
-{ "th" }
-
-MACRO {jan} {"Jan."}
-
-MACRO {feb} {"Feb."}
-
-MACRO {mar} {"Mar."}
-
-MACRO {apr} {"Apr."}
-
-MACRO {may} {"May"}
-
-MACRO {jun} {"Jun."}
-
-MACRO {jul} {"Jul."}
-
-MACRO {aug} {"Aug."}
-
-MACRO {sep} {"Sep."}
-
-MACRO {oct} {"Oct."}
-
-MACRO {nov} {"Nov."}
-
-MACRO {dec} {"Dec."}
-
-FUNCTION {eng.ord}
-{ duplicate$ "1" swap$ *
-  #-2 #1 substring$ "1" =
-     { bbl.th * }
-     { duplicate$ #-1 #1 substring$
-       duplicate$ "1" =
-         { pop$ bbl.st * }
-         { duplicate$ "2" =
-             { pop$ bbl.nd * }
-             { "3" =
-                 { bbl.rd * }
-                 { bbl.th * }
-               if$
-             }
-           if$
-          }
-       if$
-     }
-   if$
-}
-
-MACRO {acmcs} {"ACM Comput. Surv."}
-
-MACRO {acta} {"Acta Inf."}
-
-MACRO {cacm} {"Commun. ACM"}
-
-MACRO {ibmjrd} {"IBM J. Res. Dev."}
-
-MACRO {ibmsj} {"IBM Syst.~J."}
-
-MACRO {ieeese} {"IEEE Trans. Software Eng."}
-
-MACRO {ieeetc} {"IEEE Trans. Comput."}
-
-MACRO {ieeetcad}
- {"IEEE Trans. Comput. Aid. Des."}
-
-MACRO {ipl} {"Inf. Process. Lett."}
-
-MACRO {jacm} {"J.~ACM"}
-
-MACRO {jcss} {"J.~Comput. Syst. Sci."}
-
-MACRO {scp} {"Sci. Comput. Program."}
-
-MACRO {sicomp} {"SIAM J. Comput."}
-
-MACRO {tocs} {"ACM Trans. Comput. Syst."}
-
-MACRO {tods} {"ACM Trans. Database Syst."}
-
-MACRO {tog} {"ACM Trans. Graphic."}
-
-MACRO {toms} {"ACM Trans. Math. Software"}
-
-MACRO {toois} {"ACM Trans. Office Inf. Syst."}
-
-MACRO {toplas} {"ACM Trans. Progr. Lang. Syst."}
-
-MACRO {tcs} {"Theor. Comput. Sci."}
-
-FUNCTION {bibinfo.check}
-{ swap$
-  duplicate$ missing$
-    {
-      pop$ pop$
-      ""
-    }
-    { duplicate$ empty$
-        {
-          swap$ pop$
-        }
-        { swap$
-          pop$
-        }
-      if$
-    }
-  if$
-}
-FUNCTION {bibinfo.warn}
-{ swap$
-  duplicate$ missing$
-    {
-      swap$ "missing " swap$ * " in " * cite$ * warning$ pop$
-      ""
-    }
-    { duplicate$ empty$
-        {
-          swap$ "empty " swap$ * " in " * cite$ * warning$
-        }
-        { swap$
-          pop$
-        }
-      if$
-    }
-  if$
-}
-FUNCTION {format.eprint}
-{ eprint duplicate$ empty$
-    'skip$
-    { "\eprint"
-      archive empty$
-        'skip$
-        { "[" * archive * "]" * }
-      if$
-      "{" * swap$ * "}" *
-    }
-  if$
-}
-STRINGS  { bibinfo}
-INTEGERS { nameptr namesleft numnames }
-
-FUNCTION {format.names}
-{ 'bibinfo :=
-  duplicate$ empty$ 'skip$ {
-  's :=
-  "" 't :=
-  #1 'nameptr :=
-  s num.names$ 'numnames :=
-  numnames 'namesleft :=
-    { namesleft #0 > }
-    { s nameptr
-      duplicate$ #1 >
-        { "{f.~}{vv~}{ll}{, jj}" }
-        { "{vv~}{ll}{, f.}{, jj}" }
-      if$
-      format.name$
-      bibinfo bibinfo.check
-      't :=
-      nameptr #1 >
-        {
-          namesleft #1 >
-            { ", " * t * }
-            {
-              numnames #2 >
-                { "," * }
-                'skip$
-              if$
-              s nameptr "{ll}" format.name$ duplicate$ "others" =
-                { 't := }
-                { pop$ }
-              if$
-              t "others" =
-                {
-                  " " * bbl.etal *
-                }
-                {
-                  bbl.and
-                  space.word * t *
-                }
-              if$
-            }
-          if$
-        }
-        't
-      if$
-      nameptr #1 + 'nameptr :=
-      namesleft #1 - 'namesleft :=
-    }
-  while$
-  } if$
-}
-FUNCTION {format.names.ed}
-{
-  format.names
-}
-FUNCTION {format.key}
-{ empty$
-    { key field.or.null }
-    { "" }
-  if$
-}
-
-FUNCTION {format.authors}
-{ author "author" format.names
-}
-FUNCTION {get.bbl.editor}
-{ editor num.names$ #1 > 'bbl.editors 'bbl.editor if$ }
-
-FUNCTION {format.editors}
-{ editor "editor" format.names duplicate$ empty$ 'skip$
-    {
-      "," *
-      " " *
-      get.bbl.editor
-      capitalize
-   "(" swap$ * ")" *
-      *
-    }
-  if$
-}
-FUNCTION {format.book.pages}
-{ pages "pages" bibinfo.check
-  duplicate$ empty$ 'skip$
-    { " " * bbl.pages * }
-  if$
-}
-FUNCTION {format.doi}
-{ doi "doi" bibinfo.check
-  duplicate$ empty$ 'skip$
-    {
-      "\doi{" swap$ * "}" *
-    }
-  if$
-}
-FUNCTION {format.note}
-{
-  url empty$
-    'skip$
-    { "\urlprefix\url{" url * "}" * output }
-  if$
- note empty$
-    { "" }
-    { note #1 #1 substring$
-      duplicate$ "{" =
-        'skip$
-        { output.state mid.sentence =
-          { "l" }
-          { "u" }
-        if$
-        change.case$
-        }
-      if$
-      note #2 global.max$ substring$ * "note" bibinfo.check
-    }
-  if$
-}
-
-FUNCTION {format.title}
-{ title
-  duplicate$ empty$ 'skip$
-    { "t" change.case$ }
-  if$
-  "title" bibinfo.check
-}
-FUNCTION {format.full.names}
-{'s :=
- "" 't :=
-  #1 'nameptr :=
-  s num.names$ 'numnames :=
-  numnames 'namesleft :=
-    { namesleft #0 > }
-    { s nameptr
-      "{vv~}{ll}" format.name$
-      't :=
-      nameptr #1 >
-        {
-          namesleft #1 >
-            { ", " * t * }
-            {
-              s nameptr "{ll}" format.name$ duplicate$ "others" =
-                { 't := }
-                { pop$ }
-              if$
-              t "others" =
-                {
-                  " " * bbl.etal *
-                }
-                {
-                  numnames #2 >
-                    { "," * }
-                    'skip$
-                  if$
-                  bbl.and
-                  space.word * t *
-                }
-              if$
-            }
-          if$
-        }
-        't
-      if$
-      nameptr #1 + 'nameptr :=
-      namesleft #1 - 'namesleft :=
-    }
-  while$
-}
-
-FUNCTION {author.editor.key.full}
-{ author empty$
-    { editor empty$
-        { key empty$
-            { cite$ #1 #3 substring$ }
-            'key
-          if$
-        }
-        { editor format.full.names }
-      if$
-    }
-    { author format.full.names }
-  if$
-}
-
-FUNCTION {author.key.full}
-{ author empty$
-    { key empty$
-         { cite$ #1 #3 substring$ }
-          'key
-      if$
-    }
-    { author format.full.names }
-  if$
-}
-
-FUNCTION {editor.key.full}
-{ editor empty$
-    { key empty$
-         { cite$ #1 #3 substring$ }
-          'key
-      if$
-    }
-    { editor format.full.names }
-  if$
-}
-
-FUNCTION {make.full.names}
-{ type$ "book" =
-  type$ "inbook" =
-  or
-    'author.editor.key.full
-    { type$ "proceedings" =
-        'editor.key.full
-        'author.key.full
-      if$
-    }
-  if$
-}
-
-FUNCTION {output.bibitem}
-{ newline$
-  "\bibitem[{" write$
-  label write$
-  ")" make.full.names duplicate$ short.list =
-     { pop$ }
-     { * }
-   if$
-  "}]{" * write$
-  cite$ write$
-  "}" write$
-  newline$
-  ""
-  before.all 'output.state :=
-}
-
-FUNCTION {if.digit}
-{ duplicate$ "0" =
-  swap$ duplicate$ "1" =
-  swap$ duplicate$ "2" =
-  swap$ duplicate$ "3" =
-  swap$ duplicate$ "4" =
-  swap$ duplicate$ "5" =
-  swap$ duplicate$ "6" =
-  swap$ duplicate$ "7" =
-  swap$ duplicate$ "8" =
-  swap$ "9" = or or or or or or or or or
-}
-FUNCTION {n.separate}
-{ 't :=
-  ""
-  #0 'numnames :=
-  { t empty$ not }
-  { t #-1 #1 substring$ if.digit
-      { numnames #1 + 'numnames := }
-      { #0 'numnames := }
-    if$
-    t #-1 #1 substring$ swap$ *
-    t #-2 global.max$ substring$ 't :=
-    numnames #5 =
-      { duplicate$ #1 #2 substring$ swap$
-        #3 global.max$ substring$
-        "\," swap$ * *
-      }
-      'skip$
-    if$
-  }
-  while$
-}
-FUNCTION {n.dashify}
-{
-  n.separate
-  't :=
-  ""
-    { t empty$ not }
-    { t #1 #1 substring$ "-" =
-        { t #1 #2 substring$ "--" = not
-            { "--" *
-              t #2 global.max$ substring$ 't :=
-            }
-            {   { t #1 #1 substring$ "-" = }
-                { "-" *
-                  t #2 global.max$ substring$ 't :=
-                }
-              while$
-            }
-          if$
-        }
-        { t #1 #1 substring$ *
-          t #2 global.max$ substring$ 't :=
-        }
-      if$
-    }
-  while$
-}
-
-FUNCTION {word.in}
-{ "" }
-
-FUNCTION {format.date}
-{ year "year" bibinfo.check duplicate$ empty$
-    {
-      "empty year in " cite$ * "; set to ????" * warning$
-       pop$ "????"
-    }
-    'skip$
-  if$
-  extra.label *
-  before.all 'output.state :=
-  ", " swap$ *
-}
-FUNCTION {format.btitle}
-{ title "title" bibinfo.check
-  duplicate$ empty$ 'skip$
-    {
-      emphasize
-    }
-  if$
-}
-FUNCTION {either.or.check}
-{ empty$
-    'pop$
-    { "can't use both " swap$ * " fields in " * cite$ * warning$ }
-  if$
-}
-FUNCTION {format.bvolume}
-{ volume empty$
-    { "" }
-    { bbl.volume volume tie.or.space.prefix
-      "volume" bibinfo.check * *
-      series "series" bibinfo.check
-      duplicate$ empty$ 'pop$
-%%% NO ITALIC SERIES        { emphasize ", " * swap$ * }
-      {", " * swap$ * }
-      if$
-      "volume and number" number either.or.check
-    }
-  if$
-}
-FUNCTION {format.number.series}
-{ volume empty$
-    { number empty$
-        { series field.or.null }
-        { series empty$
-            { number "number" bibinfo.check }
-            { output.state mid.sentence =
-                { bbl.number }
-                { bbl.number capitalize }
-              if$
-              number tie.or.space.prefix "number" bibinfo.check * *
-              bbl.in space.word *
-              series "series" bibinfo.check *
-            }
-          if$
-        }
-      if$
-    }
-    { "" }
-  if$
-}
-FUNCTION {is.num}
-{ chr.to.int$
-  duplicate$ "0" chr.to.int$ < not
-  swap$ "9" chr.to.int$ > not and
-}
-
-FUNCTION {extract.num}
-{ duplicate$ 't :=
-  "" 's :=
-  { t empty$ not }
-  { t #1 #1 substring$
-    t #2 global.max$ substring$ 't :=
-    duplicate$ is.num
-      { s swap$ * 's := }
-      { pop$ "" 't := }
-    if$
-  }
-  while$
-  s empty$
-    'skip$
-    { pop$ s }
-  if$
-}
-
-FUNCTION {convert.edition}
-{ extract.num "l" change.case$ 's :=
-  s "first" = s "1" = or
-    { bbl.first 't := }
-    { s "second" = s "2" = or
-        { bbl.second 't := }
-        { s "third" = s "3" = or
-            { bbl.third 't := }
-            { s "fourth" = s "4" = or
-                { bbl.fourth 't := }
-                { s "fifth" = s "5" = or
-                    { bbl.fifth 't := }
-                    { s #1 #1 substring$ is.num
-                        { s eng.ord 't := }
-                        { edition 't := }
-                      if$
-                    }
-                  if$
-                }
-              if$
-            }
-          if$
-        }
-      if$
-    }
-  if$
-  t
-}
-
-FUNCTION {format.edition}
-{ edition duplicate$ empty$ 'skip$
-    {
-      convert.edition
-      output.state mid.sentence =
-        { "l" }
-        { "t" }
-      if$ change.case$
-      "edition" bibinfo.check
-      " " * bbl.edition *
-    }
-  if$
-}
-INTEGERS { multiresult }
-FUNCTION {multi.page.check}
-{ 't :=
-  #0 'multiresult :=
-    { multiresult not
-      t empty$ not
-      and
-    }
-    { t #1 #1 substring$
-      duplicate$ "-" =
-      swap$ duplicate$ "," =
-      swap$ "+" =
-      or or
-        { #1 'multiresult := }
-        { t #2 global.max$ substring$ 't := }
-      if$
-    }
-  while$
-  multiresult
-}
-FUNCTION {format.pages}
-{ pages duplicate$ empty$ 'skip$
-    { duplicate$ multi.page.check
-        {
-          n.dashify
-        }
-        {
-        }
-      if$
-      "pages" bibinfo.check
-    }
-  if$
-}
-FUNCTION {format.journal.pages}
-{ pages duplicate$ empty$ 'pop$
-    { swap$ duplicate$ empty$
-        { pop$ pop$ format.pages }
-        {
-          ", " *
-          swap$
-          n.dashify
-          "pages" bibinfo.check
-          *
-        }
-      if$
-    }
-  if$
-}
-FUNCTION {format.journal.eid}
-{ eid "eid" bibinfo.check
-  duplicate$ empty$ 'pop$
-    { swap$ duplicate$ empty$ 'skip$
-      {
-          ", " *
-      }
-      if$
-      swap$ *
-    }
-  if$
-}
-FUNCTION {format.vol.num.pages}
-{ volume field.or.null
-  duplicate$ empty$ 'skip$
-    {
-      "volume" bibinfo.check
-    }
-  if$
-  number "number" bibinfo.check duplicate$ empty$ 'skip$
-    {
-      swap$ duplicate$ empty$
-        { "there's a number but no volume in " cite$ * warning$ }
-        'skip$
-      if$
-      swap$
-      "~(" swap$ * ")" *
-    }
-  if$ *
-  bolden
-  eid empty$
-    { format.journal.pages }
-    { format.journal.eid }
-  if$
-}
-
-FUNCTION {format.chapter.pages}
-{ chapter empty$
-    'format.pages
-    { type empty$
-        { bbl.chapter }
-        { type "l" change.case$
-          "type" bibinfo.check
-        }
-      if$
-      chapter tie.or.space.prefix
-      "chapter" bibinfo.check
-      * *
-      pages empty$
-        'skip$
-        { ", " * format.pages * }
-      if$
-    }
-  if$
-}
-
-FUNCTION {format.booktitle}
-{
-  booktitle "booktitle" bibinfo.check
-  emphasize
-}
-FUNCTION {format.in.ed.booktitle}
-{ format.booktitle duplicate$ empty$ 'skip$
-    {
-      editor "editor" format.names.ed duplicate$ empty$ 'pop$
-        {
-          get.bbl.editor
-          swap$ "," *
-          " " * swap$ *
-          swap$
-          "," *
-          " " * swap$
-          * }
-      if$
-      word.in swap$ *
-    }
-  if$
-}
-FUNCTION {format.thesis.type}
-{ type duplicate$ empty$
-    'pop$
-    { swap$ pop$
-      "t" change.case$ "type" bibinfo.check
-    }
-  if$
-}
-FUNCTION {format.tr.number}
-{ number "number" bibinfo.check
-  type duplicate$ empty$
-    { pop$ bbl.techrep }
-    'skip$
-  if$
-  "type" bibinfo.check
-  swap$ duplicate$ empty$
-    { pop$ "t" change.case$ }
-    { tie.or.space.prefix * * }
-  if$
-}
-FUNCTION {format.article.crossref}
-{
-  word.in
-  " \cite{" * crossref * "}" *
-}
-FUNCTION {format.book.crossref}
-{ volume duplicate$ empty$
-    { "empty volume in " cite$ * "'s crossref of " * crossref * warning$
-      pop$ word.in
-    }
-    { bbl.volume
-      capitalize
-      swap$ tie.or.space.prefix "volume" bibinfo.check * * bbl.of space.word *
-    }
-  if$
-  " \cite{" * crossref * "}" *
-}
-FUNCTION {format.incoll.inproc.crossref}
-{
-  word.in
-  " \cite{" * crossref * "}" *
-}
-FUNCTION {format.org.or.pub}
-{ 't :=
-  ""
-  address empty$ t empty$ and
-    'skip$
-    {
-      t empty$
-        { address "address" bibinfo.check *
-        }
-        { t *
-          address empty$
-            'skip$
-            { ", " * address "address" bibinfo.check * }
-          if$
-        }
-      if$
-    }
-  if$
-}
-FUNCTION {format.publisher.address}
-{ publisher "publisher" bibinfo.warn format.org.or.pub
-}
-
-FUNCTION {format.organization.address}
-{ organization "organization" bibinfo.check format.org.or.pub
-}
-
-STRINGS {oldname}
-
-FUNCTION {name.or.dash}
-{ 's :=
-   oldname empty$
-     { s 'oldname := s }
-     { s oldname =
-         { "---{}---{}---" }
-         { s 'oldname := s }
-       if$
-     }
-   if$
-}
-
-FUNCTION {article}
-{ output.bibitem
-  format.authors "author" output.check
-  author format.key output
-  name.or.dash
-  format.date "year" output.check
-  date.block
-  format.title "title" output.check
-  new.sentence
-  crossref missing$
-    {
-      journal
-      "journal" bibinfo.check
-      emphasize
-      "journal" output.check
-      format.vol.num.pages output
-  format.doi output
-    }
-    { format.article.crossref output.nonnull
-      format.pages output
-    }
-  if$
-  format.note output
-  format.eprint output
-  fin.entry
-}
-FUNCTION {book}
-{ output.bibitem
-  author empty$
-    { format.editors "author and editor" output.check
-      editor format.key output
-      add.blank
-      name.or.dash
-    }
-    { format.authors output.nonnull
-      name.or.dash
-      crossref missing$
-        { "author and editor" editor either.or.check }
-        'skip$
-      if$
-    }
-  if$
-  format.date "year" output.check
-  date.block
-  format.btitle "title" output.check
-  crossref missing$
-    { format.bvolume output
-  new.sentence
-      format.edition output
-      format.number.series output
-      format.publisher.address output
-    }
-    {
-  new.sentence
-      format.book.crossref output.nonnull
-    }
-  if$
-  format.book.pages output
-  format.doi output
-  format.note output
-  format.eprint output
-  fin.entry
-}
-FUNCTION {booklet}
-{ output.bibitem
-  format.authors output
-  author format.key output
-  name.or.dash
-  format.date "year" output.check
-  date.block
-  format.title "title" output.check
-  new.sentence
-  howpublished "howpublished" bibinfo.check output
-  address "address" bibinfo.check output
-  format.book.pages output
-  format.doi output
-  format.note output
-  format.eprint output
-  fin.entry
-}
-
-FUNCTION {inbook}
-{ output.bibitem
-  author empty$
-    { format.editors "author and editor" output.check
-      editor format.key output
-      name.or.dash
-    }
-    { format.authors output.nonnull
-      name.or.dash
-      crossref missing$
-        { "author and editor" editor either.or.check }
-        'skip$
-      if$
-    }
-  if$
-  format.date "year" output.check
-  date.block
-  format.btitle "title" output.check
-  crossref missing$
-    {
-      format.bvolume output
-      format.chapter.pages "chapter and pages" output.check
-  new.sentence
-      format.edition output
-      format.number.series output
-      format.publisher.address output
-    }
-    {
-      format.chapter.pages "chapter and pages" output.check
-  new.sentence
-      format.book.crossref output.nonnull
-    }
-  if$
-  format.doi output
-  format.note output
-  format.eprint output
-  fin.entry
-}
-
-FUNCTION {incollection}
-{ output.bibitem
-  format.authors "author" output.check
-  author format.key output
-  name.or.dash
-  format.date "year" output.check
-  date.block
-  format.title "title" output.check
-  new.sentence
-  crossref missing$
-    { format.in.ed.booktitle "booktitle" output.check
-      format.publisher.address output      
-      format.bvolume output
-      format.number.series output
-      format.edition output
-      format.chapter.pages output
-    }
-    { format.incoll.inproc.crossref output.nonnull
-      format.chapter.pages output
-    }
-  if$
-  format.doi output
-  format.note output
-  format.eprint output
-  fin.entry
-}
-FUNCTION {inproceedings}
-{ output.bibitem
-  format.authors "author" output.check
-  author format.key output
-  name.or.dash
-  format.date "year" output.check
-  date.block
-  format.title "title" output.check
-  new.sentence
-  crossref missing$
-    { format.in.ed.booktitle "booktitle" output.check
-      publisher empty$
-        { format.organization.address output }
-        { organization "organization" bibinfo.check output
-          format.publisher.address output
-        }
-      if$
-      format.bvolume output
-      format.pages output
-      format.number.series output
-      howpublished "howpublished" bibinfo.check output
-    }
-    { format.incoll.inproc.crossref output.nonnull
-      format.pages output
-    }
-  if$
-  format.doi output
-  format.note output
-  format.eprint output
-  fin.entry
-}
-FUNCTION {conference} { inproceedings }
-FUNCTION {manual}
-{ output.bibitem
-  format.authors output
-  author format.key output
-  name.or.dash
-  format.date "year" output.check
-  date.block
-  format.btitle "title" output.check
-  new.sentence
-  organization "organization" bibinfo.check output
-  address "address" bibinfo.check output
-  format.edition output
-  format.doi output
-  format.note output
-  format.eprint output
-  fin.entry
-}
-
-FUNCTION {mastersthesis}
-{ output.bibitem
-  format.authors "author" output.check
-  author format.key output
-  name.or.dash
-  format.date "year" output.check
-  date.block
-  format.title
-  "title" output.check
-  new.sentence
-  bbl.mthesis format.thesis.type output.nonnull
-  department "department" bibinfo.warn output
-  school "school" bibinfo.warn output
-  address "address" bibinfo.check output
-  format.doi output
-  format.note output
-  format.eprint output
-  fin.entry
-}
-
-FUNCTION {misc}
-{ output.bibitem
-  format.authors output
-  author format.key output
-  name.or.dash
-  format.date "year" output.check
-  date.block
-  format.title output
-  new.sentence
-  howpublished "howpublished" bibinfo.check output
-  format.doi output
-  format.note output
-  format.eprint output
-  fin.entry
-}
-FUNCTION {phdthesis}
-{ output.bibitem
-  format.authors "author" output.check
-  author format.key output
-  name.or.dash
-  format.date "year" output.check
-  date.block
-  format.title
-  "title" output.check
-  new.sentence
-  bbl.phdthesis format.thesis.type output.nonnull
-  school "school" bibinfo.warn output
-  address "address" bibinfo.check output
-  format.doi output
-  format.note output
-  format.eprint output
-  fin.entry
-}
-
-FUNCTION {proceedings}
-{ output.bibitem
-  format.editors output
-  editor format.key output
-  name.or.dash
-  format.date "year" output.check
-  date.block
-  format.btitle "title" output.check
-  format.bvolume output
-  format.number.series output
-  publisher empty$
-    { format.organization.address output }
-    { organization "organization" bibinfo.check output
-      format.publisher.address output
-    }
-  if$
-  format.doi output
-  format.note output
-  format.eprint output
-  fin.entry
-}
-
-FUNCTION {techreport}
-{ output.bibitem
-  format.authors "author" output.check
-  author format.key output
-  name.or.dash
-  format.date "year" output.check
-  date.block
-  format.title
-  "title" output.check
-  new.sentence
-  format.tr.number output.nonnull
-  institution "institution" bibinfo.warn output
-  address "address" bibinfo.check output
-  format.doi output
-  format.note output
-  format.eprint output
-  fin.entry
-}
-
-FUNCTION {unpublished}
-{ output.bibitem
-  format.authors "author" output.check
-  author format.key output
-  name.or.dash
-  format.date "year" output.check
-  date.block
-  format.title "title" output.check
-  format.doi output
-  format.note "note" output.check
-  format.eprint output
-  fin.entry
-}
-
-FUNCTION {default.type} { misc }
-READ
-FUNCTION {sortify}
-{ purify$
-  "l" change.case$
-}
-INTEGERS { len }
-FUNCTION {chop.word}
-{ 's :=
-  'len :=
-  s #1 len substring$ =
-    { s len #1 + global.max$ substring$ }
-    's
-  if$
-}
-FUNCTION {format.lab.names}
-{ 's :=
-  "" 't :=
-  s #1 "{vv~}{ll}" format.name$
-  s num.names$ duplicate$
-  #2 >
-    { pop$
-      " " * bbl.etal *
-    }
-    { #2 <
-        'skip$
-        { s #2 "{ff }{vv }{ll}{ jj}" format.name$ "others" =
-            {
-              " " * bbl.etal *
-            }
-            { bbl.and space.word * s #2 "{vv~}{ll}" format.name$
-              * }
-          if$
-        }
-      if$
-    }
-  if$
-}
-
-FUNCTION {author.key.label}
-{ author empty$
-    { key empty$
-        { cite$ #1 #3 substring$ }
-        'key
-      if$
-    }
-    { author format.lab.names }
-  if$
-}
-
-FUNCTION {author.editor.key.label}
-{ author empty$
-    { editor empty$
-        { key empty$
-            { cite$ #1 #3 substring$ }
-            'key
-          if$
-        }
-        { editor format.lab.names }
-      if$
-    }
-    { author format.lab.names }
-  if$
-}
-
-FUNCTION {editor.key.label}
-{ editor empty$
-    { key empty$
-        { cite$ #1 #3 substring$ }
-        'key
-      if$
-    }
-    { editor format.lab.names }
-  if$
-}
-
-FUNCTION {calc.short.authors}
-{ type$ "book" =
-  type$ "inbook" =
-  or
-    'author.editor.key.label
-    { type$ "proceedings" =
-        'editor.key.label
-        'author.key.label
-      if$
-    }
-  if$
-  'short.list :=
-}
-
-FUNCTION {calc.label}
-{ calc.short.authors
-  short.list
-  "("
-  *
-  year duplicate$ empty$
-     { pop$ "????" }
-     { purify$ #-1 #4 substring$ }
-  if$
-  *
-  'label :=
-}
-
-FUNCTION {sort.format.names}
-{ 's :=
-  #1 'nameptr :=
-  ""
-  s num.names$ 'numnames :=
-  numnames 'namesleft :=
-    { namesleft #0 > }
-    { s nameptr
-      "{vv{ } }{ll{ }}{  f{ }}{  jj{ }}"
-      format.name$ 't :=
-      nameptr #1 >
-        {
-          "   "  *
-          namesleft #1 = t "others" = and
-            { "zzzzz" * }
-            { t sortify * }
-          if$
-        }
-        { t sortify * }
-      if$
-      nameptr #1 + 'nameptr :=
-      namesleft #1 - 'namesleft :=
-    }
-  while$
-}
-
-FUNCTION {sort.format.title}
-{ 't :=
-  "A " #2
-    "An " #3
-      "The " #4 t chop.word
-    chop.word
-  chop.word
-  sortify
-  #1 global.max$ substring$
-}
-FUNCTION {author.sort}
-{ author empty$
-    { key empty$
-        { "to sort, need author or key in " cite$ * warning$
-          ""
-        }
-        { key sortify }
-      if$
-    }
-    { author sort.format.names }
-  if$
-}
-FUNCTION {author.editor.sort}
-{ author empty$
-    { editor empty$
-        { key empty$
-            { "to sort, need author, editor, or key in " cite$ * warning$
-              ""
-            }
-            { key sortify }
-          if$
-        }
-        { editor sort.format.names }
-      if$
-    }
-    { author sort.format.names }
-  if$
-}
-FUNCTION {editor.sort}
-{ editor empty$
-    { key empty$
-        { "to sort, need editor or key in " cite$ * warning$
-          ""
-        }
-        { key sortify }
-      if$
-    }
-    { editor sort.format.names }
-  if$
-}
-FUNCTION {presort}
-{ calc.label
-  label sortify
-  "    "
-  *
-  type$ "book" =
-  type$ "inbook" =
-  or
-    'author.editor.sort
-    { type$ "proceedings" =
-        'editor.sort
-        'author.sort
-      if$
-    }
-  if$
-  #1 entry.max$ substring$
-  'sort.label :=
-  sort.label
-  *
-  "    "
-  *
-  title field.or.null
-  sort.format.title
-  *
-  #1 entry.max$ substring$
-  'sort.key$ :=
-}
-
-ITERATE {presort}
-SORT
-STRINGS { last.label next.extra }
-INTEGERS { last.extra.num number.label }
-FUNCTION {initialize.extra.label.stuff}
-{ #0 int.to.chr$ 'last.label :=
-  "" 'next.extra :=
-  #0 'last.extra.num :=
-  #0 'number.label :=
-}
-FUNCTION {forward.pass}
-{ last.label label =
-    { last.extra.num #1 + 'last.extra.num :=
-      last.extra.num int.to.chr$ 'extra.label :=
-    }
-    { "a" chr.to.int$ 'last.extra.num :=
-      "" 'extra.label :=
-      label 'last.label :=
-    }
-  if$
-  number.label #1 + 'number.label :=
-}
-FUNCTION {reverse.pass}
-{ next.extra "b" =
-    { "a" 'extra.label := }
-    'skip$
-  if$
-  extra.label 'next.extra :=
-  extra.label
-  duplicate$ empty$
-    'skip$
-    { "{\natexlab{" swap$ * "}}" * }
-  if$
-  'extra.label :=
-  label extra.label * 'label :=
-}
-EXECUTE {initialize.extra.label.stuff}
-ITERATE {forward.pass}
-REVERSE {reverse.pass}
-FUNCTION {bib.sort.order}
-{ sort.label
-  "    "
-  *
-  year field.or.null sortify
-  *
-  "    "
-  *
-  title field.or.null
-  sort.format.title
-  *
-  #1 entry.max$ substring$
-  'sort.key$ :=
-}
-ITERATE {bib.sort.order}
-SORT
-FUNCTION {begin.bib}
-{ preamble$ empty$
-    'skip$
-    { preamble$ write$ newline$ }
-  if$
-  "\begin{thebibliography}{" number.label int.to.str$ * "}" *
-  write$ newline$
-  "\providecommand{\natexlab}[1]{#1}"
-  write$ newline$
-  "\providecommand{\url}[1]{\texttt{#1}}"
-  write$ newline$
-  "\providecommand{\urlprefix}{URL }"
-  write$ newline$
-  "\expandafter\ifx\csname urlstyle\endcsname\relax"
-  write$ newline$
-  "  \providecommand{\doi}[1]{doi:\discretionary{}{}{}#1}\else"
-  write$ newline$
-  "  \providecommand{\doi}{doi:\discretionary{}{}{}\begingroup \urlstyle{rm}\Url}\fi"
-  write$ newline$
-  "\providecommand{\eprint}[2][]{\url{#2}}"
-  write$ newline$
-}
-EXECUTE {begin.bib}
-EXECUTE {init.state.consts}
-ITERATE {call.type$}
-FUNCTION {end.bib}
-{ newline$
-  "\end{thebibliography}" write$ newline$
-}
-EXECUTE {end.bib}
-%% End of customized bst file
-%%
-%% End of file `ametsoc7.bst'.
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/appendices.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/appendices.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/appendices.tex	(revision 11422)
@@ -0,0 +1,13 @@
+
+\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
+
+%% Not included
+%\subfile{../subfiles/chap_model_basics_zstar}
+%\subfile{../subfiles/chap_DIU}
+%\subfile{../subfiles/chap_conservation}
+%\subfile{../subfiles/annex_E}				%% Notes on some on going staff
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/bibliography.bib
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/bibliography.bib	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/bibliography.bib	(revision 11422)
@@ -0,0 +1,3106 @@
+
+@article{         adcroft.campin_OM04,
+  title         = "Rescaled height coordinates for accurate representation of
+                  free-surface flows in ocean circulation models",
+  pages         = "269--284",
+  journal       = "Ocean Modelling",
+  volume        = "7",
+  number        = "3-4",
+  author        = "A. Adcroft and J.-M. Campin",
+  year          = "2004",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2003.09.003"
+}
+
+@article{         arakawa.hsu_MWR90,
+  title         = "Energy Conserving and Potential-Enstrophy Dissipating
+                  Schemes for the Shallow Water Equations",
+  pages         = "1960--1969",
+  journal       = "Monthly Weather Review",
+  volume        = "118",
+  number        = "10",
+  author        = "A. Arakawa and Y.-J. G. Hsu",
+  year          = "1990",
+  month         = "oct",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0493",
+  doi           = "10.1175/1520-0493(1990)118<1960:ecaped>2.0.co;2"
+}
+
+@article{         arakawa.lamb_MWR81,
+  title         = "A Potential Enstrophy and Energy Conserving Scheme for the
+                  Shallow Water Equations",
+  pages         = "18--36",
+  journal       = "Monthly Weather Review",
+  volume        = "109",
+  number        = "1",
+  author        = "A. Arakawa and V. R. Lamb",
+  year          = "1981",
+  month         = "jan",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0493",
+  doi           = "10.1175/1520-0493(1981)109<0018:apeaec>2.0.co;2"
+}
+
+@article{         arakawa_JCP66,
+  title         = "Computational design for long-term numerical integration
+                  of the equations of fluid motion: Two-dimensional
+                  incompressible flow. Part {I}",
+  pages         = "119--143",
+  journal       = "Journal of Computational Physics",
+  volume        = "1",
+  number        = "1",
+  author        = "A. Arakawa",
+  year          = "1966",
+  month         = "Aug",
+  publisher     = "Elsevier BV",
+  issn          = "0021-9991",
+  doi           = "10.1016/0021-9991(66)90015-5"
+}
+
+@article{         arbic.garner.ea_DSR04,
+  title         = "The accuracy of surface elevations in forward global
+                  barotropic and baroclinic tide models",
+  pages         = "3069--3101",
+  journal       = "Deep Sea Research",
+  volume        = "51",
+  number        = "25-26",
+  author        = "B. K. Arbic and S. T. Garner and R. W. Hallberg and H. L.
+                  Simmons",
+  year          = "2004",
+  month         = "dec",
+  publisher     = "Elsevier BV",
+  issn          = "0967-0645",
+  doi           = "10.1016/j.dsr2.2004.09.014"
+}
+
+@article{         artale.iudicone.ea_JGR02,
+  title         = "Role of surface fluxes in Ocean General Circulation Models
+                  using satellite sea surface temperature: Validation of and
+                  sensitivity to the forcing frequency of the Mediterranean
+                  thermohaline circulation",
+  pages         = "2901--2924",
+  journal       = "Journal of Geophysical Research",
+  volume        = "107",
+  number        = "C8",
+  author        = "V. Artale and D. Iudicone and R. Santoleri and V. Rupolo
+                  and S. Marullo and F. {D'O}rtenzio",
+  year          = "2002",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/2000jc000452"
+}
+
+@article{         asselin_MWR72,
+  title         = "Frequency Filter for Time Integrations",
+  pages         = "487--490",
+  journal       = "Monthly Weather Review",
+  volume        = "100",
+  number        = "6",
+  author        = "R. Asselin",
+  year          = "1972",
+  month         = "jun",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0493",
+  doi           = "10.1175/1520-0493(1972)100<0487:fffti>2.3.co;2"
+}
+
+@article{         axell_JGR02,
+  title         = "Wind-driven internal waves and Langmuir circulations in a
+                  numerical ocean model of the southern Baltic Sea",
+  journal       = "Journal of Geophysical Research",
+  volume        = "107",
+  number        = "C11",
+  author        = "L. B. Axell",
+  year          = "2002",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/2001jc000922"
+}
+
+@article{         barnier.madec.ea_OD06,
+  title         = "Impact of partial steps and momentum advection schemes in
+                  a global ocean circulation model at eddy-permitting
+                  resolution",
+  pages         = "543--567",
+  journal       = "Ocean Dynamics",
+  volume        = "56",
+  number        = "5-6",
+  author        = "B. Barnier and G. Madec and T. Penduff and J.-M. Molines
+                  and A.-M. Tr\'{e}guier and J. {Le Sommer} and A. Beckmann
+                  and A. Biastoch and C. B{\"{o}}ning and J. Dengg and C.
+                  Derval and E. Durand and S. Gulev and E. Remy and C.
+                  Talandier and S. Theetten and M. Maltrud and J. McClean and
+                  B. {de Cuevas}",
+  year          = "2006",
+  month         = "jun",
+  publisher     = "Springer Nature",
+  issn          = "1616-7228",
+  doi           = "10.1007/s10236-006-0082-1"
+}
+
+@article{         beckmann.doscher_JPO97,
+  title         = "A method for improved representation of dense water
+                  spreading over topography in geopotential-coordinate
+                  models",
+  pages         = "581--591",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "27",
+  number        = "4",
+  author        = "A. Beckmann and R. D{\"{o}}scher",
+  year          = "1997",
+  month         = "apr",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1997)027<0581:amfiro>2.0.co;2"
+}
+
+@article{         beckmann.goosse_OM03,
+  title         = "A parameterization of ice shelf-ocean interaction for
+                  climate models",
+  pages         = "157--170",
+  journal       = "Ocean Modelling",
+  volume        = "5",
+  number        = "2",
+  author        = "A. Beckmann and H. Goosse",
+  year          = "2003",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/s1463-5003(02)00019-7"
+}
+
+@article{         beckmann.haidvogel_JPO93,
+  title         = "Numerical Simulation of Flow around a Tall Isolated
+                  Seamount. Part {I}: Problem Formulation and Model Accuracy",
+  pages         = "1736--1753",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "23",
+  number        = "8",
+  author        = "A. Beckmann and D. B. Haidvogel",
+  year          = "1993",
+  month         = "aug",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1993)023<1736:nsofaa>2.0.co;2"
+}
+
+@article{ beljaars_QJRMS95,
+title = "The parametrization of surface fluxes in large-scale models under free convection",
+pages = "255--270",
+journal = "Quarterly Journal of the Royal Meteorological Society",
+volume = "121",
+number = "522",
+author = "Beljaars, Anton C. M.",
+year = "1995",
+month = "jan",
+ publisher     = "Wiley",
+issn = "00359009",
+doi = "10.1002/qj.49712152203"
+}
+
+@article{         bernie.guilyardi.ea_CD07,
+  title         = "Impact of resolving the diurnal cycle in an
+                  ocean-atmosphere {GCM}. Part 1: a diurnally forced {OGCM}",
+  pages         = "575--590",
+  journal       = "Climate Dynamics",
+  volume        = "29",
+  number        = "6",
+  author        = "D. J. Bernie and E. Guilyardi and G. Madec and J. M.
+                  Slingo and S. J. Woolnough",
+  year          = "2007",
+  month         = "may",
+  publisher     = "Springer Nature",
+  issn          = "1432-0894",
+  doi           = "10.1007/s00382-007-0249-6"
+}
+
+@article{         bernie.woolnough.ea_JC05,
+  title         = "Modeling diurnal and intraseasonal variability of the
+                  ocean mixed layer",
+  pages         = "1190--1202",
+  journal       = "Journal of Climate",
+  volume        = "18",
+  number        = "8",
+  author        = "D. J. Bernie and S. J. Woolnough and J. M. Slingo and E.
+                  Guilyardi",
+  year          = "2005",
+  month         = "apr",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0442",
+  doi           = "10.1175/jcli3319.1"
+}
+
+@article{         blanke.delecluse_JPO93,
+  title         = "Variability of the tropical Atlantic Ocean simulated by a
+                  General Circulation Model with two different mixed-layer
+                  physics",
+  pages         = "1363--1388",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "23",
+  number        = "7",
+  author        = "B. Blanke and P. Del\'{e}cluse",
+  year          = "1993",
+  month         = "jul",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1993)023<1363:vottao>2.0.co;2"
+}
+
+@article{         blanke.raynaud_JPO97,
+  title         = "Kinematics of the Pacific Equatorial Undercurrent: An
+                  Eulerian and Lagrangian Approach from {GCM} Results",
+  pages         = "1038--1053",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "27",
+  number        = "6",
+  author        = "B. Blanke and S. Raynaud",
+  year          = "1997",
+  month         = "jun",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1997)027<1038:kotpeu>2.0.co;2"
+}
+
+@article{         bloom.takacs.ea_MWR96,
+  title         = "Data assimilation using incremental analysis updates",
+  pages         = "1256--1271",
+  journal       = "Monthly Weather Review",
+  volume        = "124",
+  number        = "6",
+  author        = "S. C. Bloom and L. L. Takacs and A. M. Da Silva and D.
+                  Ledvina",
+  year          = "1996",
+  month         = "jun",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0493",
+  doi           = "10.1175/1520-0493(1996)124<1256:dauiau>2.0.co;2"
+}
+
+@article{         bouffard.boegman_DAO13,
+  title         = "A diapycnal diffusivity model for stratified environmental
+                  flows",
+  pages         = "14--34",
+  journal       = "Dynamics of Atmospheres and Oceans",
+  volume        = "61-62",
+  author        = "D. Bouffard and L. Boegman",
+  year          = "2013",
+  month         = "jun",
+  publisher     = "Elsevier BV",
+  issn          = "0377-0265",
+  doi           = "10.1016/j.dynatmoce.2013.02.002"
+}
+
+@article{         bougeault.lacarrere_MWR89,
+  title         = "Parameterization of Orography-Induced Turbulence in a
+                  Mesobeta--Scale Model",
+  pages         = "1872--1890",
+  journal       = "Monthly Weather Review",
+  volume        = "117",
+  number        = "8",
+  author        = "P. Bougeault and P. Lacarrere",
+  year          = "1989",
+  month         = "aug",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0493",
+  doi           = "10.1175/1520-0493(1989)117<1872:pooiti>2.0.co;2"
+}
+
+@article{         bouillon.maqueda.ea_OM09,
+  title         = "An elastic-viscous-plastic sea ice model formulated on
+                  Arakawa {B} and {C} grids",
+  pages         = "174--184",
+  journal       = "Ocean Modelling",
+  volume        = "27",
+  number        = "3-4",
+  author        = "S. Bouillon and M. A. Morales Maqueda and V. Legat and T.
+                  Fichefet",
+  year          = "2009",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2009.01.004"
+}
+
+@article{         brankart.candille.ea_GMD15,
+  title         = "A generic approach to explicit simulation of uncertainty
+                  in the {NEMO} ocean model",
+  pages         = "1285--1297",
+  journal       = "Geoscientific Model Development",
+  volume        = "8",
+  number        = "5",
+  author        = "J.-M. Brankart and G. Candille and F. Garnier and C.
+                  Calone and A. Melet and P.-A. Bouttier and P. Brasseur and
+                  J. Verron",
+  year          = "2015",
+  month         = "may",
+  publisher     = "Copernicus GmbH",
+  issn          = "1991-9603",
+  doi           = "10.5194/gmd-8-1285-2015"
+}
+
+@article{         brankart_OM13,
+  title         = "Impact of uncertainties in the horizontal density gradient
+                  upon low resolution global ocean modelling",
+  pages         = "64--76",
+  journal       = "Ocean Modelling",
+  volume        = "66",
+  author        = "J.-M. Brankart",
+  year          = "2013",
+  month         = "jun",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2013.02.004"
+}
+
+@article{         breivik.bidlot.ea_OM16,
+  title         = "A Stokes drift approximation based on the Phillips
+                  spectrum",
+  pages         = "49--56",
+  journal       = "Ocean Modelling",
+  volume        = "100",
+  author        = "{\O}. Breivik and J.-R. Bidlot and P. A. E. M. Janssen",
+  year          = "2016",
+  month         = "apr",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2016.01.005"
+}
+
+@article{         breivik.janssen.ea_JPO14,
+  title         = "Approximate Stokes Drift Profiles in Deep Water",
+  pages         = "2433--2445",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "44",
+  number        = "9",
+  author        = "{\O}. Breivik and P. A. E. M. Janssen and J.-R. Bidlot",
+  year          = "2014",
+  month         = "sep",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/jpo-d-14-0020.1"
+}
+
+@article{         brodeau.barnier.ea_OM10,
+  title         = "An {ERA40}-based atmospheric forcing for global ocean
+                  circulation models",
+  pages         = "88--104",
+  journal       = "Ocean Modelling",
+  volume        = "31",
+  number        = "3-4",
+  author        = "L. Brodeau and B. Barnier and A.-M. Tr\'{e}guier and T.
+                  Penduff and S. Gulev",
+  year          = "2010",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2009.10.005"
+}
+
+@article{         brodeau.barnier.ea_JPO16,
+  title         = "Climatologically Significant Effects of Some Approximations in the Bulk Parameterizations of Turbulent Air–Sea Fluxes",
+  pages         = "5--28",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "47",
+  number        = "1",
+  author        = "Brodeau, Laurent and Barnier, Bernard and Gulev, Sergey K. and Woods, Cian",
+  year          = "2016",
+  month         = "jan",
+  publisher     = "American Meteorological Society",
+  issn          = "0022-3670",
+  doi           = "10.1175/jpo-d-16-0169.1",
+}
+
+@article{         brown.campana_MWR78,
+  title         = "An economical time-differencing system for numerical
+                  weather prediction",
+  pages         = "1125--1136",
+  journal       = "Monthly Weather Review",
+  volume        = "106",
+  number        = "8",
+  author        = "J. A. Brown and K. A. Campana",
+  year          = "1978",
+  month         = "aug",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0493",
+  doi           = "10.1175/1520-0493(1978)106<1125:aetsfn>2.0.co;2"
+}
+
+@article{         bryan_JCP97,
+  title         = "A numerical method for the study of the circulation of the
+                  world ocean",
+  pages         = "154--169",
+  journal       = "Journal of Computational Physics",
+  volume        = "135",
+  number        = "2",
+  author        = "K. Bryan",
+  year          = "1997",
+  month         = "Aug",
+  publisher     = "Elsevier BV",
+  issn          = "0021-9991",
+  doi           = "10.1006/jcph.1997.5699"
+}
+
+@article{         burchard_OM02,
+  title         = "Energy-conserving discretisation of turbulent shear and
+                  buoyancy production",
+  pages         = "347--361",
+  journal       = "Ocean Modelling",
+  volume        = "4",
+  number        = "3-4",
+  author        = "H. Burchard",
+  year          = "2002",
+  month         = "jun",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/s1463-5003(02)00009-4"
+}
+
+@article{         campin.adcroft.ea_OM04,
+  title         = "Conservation of properties in a free-surface model",
+  pages         = "221--244",
+  journal       = "Ocean Modelling",
+  volume        = "6",
+  number        = "3-4",
+  author        = "J.-M. Campin and A. Adcroft and C. Hill and J. Marshall",
+  year          = "2004",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/s1463-5003(03)00009-x"
+}
+
+@article{         campin.goosse_T99,
+  title         = "Parameterization of density-driven downsloping flow for a
+                  coarse-resolution ocean model in z-coordinate",
+  pages         = "412--430",
+  journal       = "Tellus A",
+  volume        = "51",
+  number        = "3",
+  author        = "J.-M. Campin and H. Goosse",
+  year          = "1999",
+  month         = "may",
+  publisher     = "Informa UK Limited",
+  issn          = "1600-0870",
+  doi           = "10.1034/j.1600-0870.1999.t01-3-00006.x"
+}
+
+@article{         campin.marshall.ea_OM08,
+  title         = "Sea ice-ocean coupling using a rescaled vertical
+                  coordinate \zstar",
+  pages         = "1--14",
+  journal       = "Ocean Modelling",
+  volume        = "24",
+  number        = "1-2",
+  author        = "J.-M. Campin and J. Marshall and D. Ferreira",
+  year          = "2008",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2008.05.005"
+}
+
+@article{         canuto.howard.ea_JPO01,
+  title         = "Ocean turbulence. Part {I}: One-point closure
+                  model-momentum and heat vertical diffusivities",
+  pages         = "1413--1426",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "31",
+  number        = "6",
+  author        = "V. M. Canuto and A. Howard and Y. Cheng and M. S.
+                  Dubovikov",
+  year          = "2001",
+  month         = "jun",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(2001)031<1413:otpiop>2.0.co;2"
+}
+
+@article{         carrere.lyard_GRL03,
+  title         = "Modeling the barotropic response of the global ocean to
+                  atmospheric wind and pressure forcing - comparisons with
+                  observations",
+  journal       = "Geophysical Research Letters",
+  volume        = "30",
+  number        = "6",
+  author        = "L. Carr\`{e}re and F. Lyard",
+  year          = "2003",
+  month         = "mar",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0094-8276",
+  doi           = "10.1029/2002gl016473"
+}
+
+@techreport{      chanut_rpt05,
+  title         = "Nesting code for {NEMO}",
+  pages         = "25",
+  author        = "J. Chanut",
+  institution   = "European Union: Marine Environment and Security for the
+                  European Area (MERSEA) Integrated Project",
+  year          = "2005",
+  month         = "may",
+  doi           = "10.5281/zenodo.3243409"
+}
+
+@article{         chassignet.smith.ea_JPO03,
+  title         = "North Atlantic Simulations with the Hybrid Coordinate
+                  Ocean Model ({HYCOM}): Impact of the Vertical Coordinate
+                  Choice, Reference Pressure, and Thermobaricity",
+  pages         = "2504--2526",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "33",
+  number        = "12",
+  author        = "E. P. Chassignet and L. T. Smith and G. R. Halliwell and
+                  R. Bleck",
+  year          = "2003",
+  month         = "dec",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(2003)033<2504:naswth>2.0.co;2"
+}
+
+@article{         cox_OM87,
+  title         = "Isopycnal diffusion in a z-coordinate ocean model",
+  pages         = "1--9",
+  journal       = "Ocean Modelling",
+  volume        = "74",
+  author        = "M. D. Cox",
+  year          = "1987",
+  month         = "jan",
+  url           = "https://www.researchgate.net/publication/243768762_Isopycnal_diffusion_in_a_z-coordinate_ocean_model"
+}
+
+@article{         craig.banner_JPO94,
+  title         = "Modeling wave-enhanced turbulence in the ocean surface
+                  layer",
+  pages         = "2546--2559",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "24",
+  number        = "12",
+  author        = "P. D. Craig and M. L. Banner",
+  year          = "1994",
+  month         = "dec",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1994)024<2546:mwetit>2.0.co;2"
+}
+
+@article{         craik.leibovich_JFM76,
+  title         = "A rational model for Langmuir circulations",
+  pages         = "401--426",
+  journal       = "Journal of Fluid Mechanics",
+  volume        = "73",
+  number        = "3",
+  author        = "A. D. D. Craik and S. Leibovich",
+  year          = "1976",
+  month         = "feb",
+  publisher     = "Cambridge University Press (CUP)",
+  issn          = "1469-7645",
+  doi           = "10.1017/s0022112076001420"
+}
+
+@article{         dalessio.abdella.ea_JPO98,
+  title         = "A new second-order turbulence closure scheme for modeling
+                  the oceanic mixed layer",
+  pages         = "1624--1641",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "28",
+  number        = "8",
+  author        = "S. J. D. D'Alessio and K. Abdella and N. A. McFarlane",
+  year          = "1998",
+  month         = "aug",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1998)028<1624:ansotc>2.0.co;2"
+}
+
+@book{            daley.barker_bk01,
+  pages         = "163",
+  booktitle     = "{NAVDAS} Source Book 2001: {NRL} Atmospheric Variational
+                  Data Assimilation System",
+  editor        = "Naval Research Laboratory, Marine Meteorology Division",
+  author        = "R. Daley and E. Barker",
+  year          = "2001",
+  month         = "jul",
+  publisher     = "Defense Technical Information Center",
+  doi           = "10.21236/ada396883"
+}
+
+@article{         danabasoglu.ferrari.ea_JC08,
+  title         = "Sensitivity of an Ocean General Circulation Model to a
+                  parameterization of near-surface eddy fluxes",
+  pages         = "1192--1208",
+  journal       = "Journal of Climate",
+  volume        = "21",
+  number        = "6",
+  author        = "G. Danabasoglu and R. Ferrari and J. C. McWilliams",
+  year          = "2008",
+  month         = "mar",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0442",
+  doi           = "10.1175/2007jcli1508.1"
+}
+
+@article{         davies_QJRMS76,
+  title         = "A lateral boundary formulation for multi-level prediction
+                  models",
+  pages         = "405--418",
+  journal       = "Quarterly Journal of the Royal Meteorological Society",
+  volume        = "102",
+  number        = "432",
+  author        = "H. C. Davies",
+  year          = "1976",
+  month         = "apr",
+  publisher     = "Wiley",
+  issn          = "0035-9009",
+  doi           = "10.1002/qj.49710243210"
+}
+
+@article{         de-boyer-montegut.madec.ea_JGR04,
+  title         = "Mixed layer depth over the global ocean: An examination of
+                  profile data and a profile-based climatology",
+  pages         = "C12003",
+  journal       = "Journal of Geophysical Research",
+  volume        = "109",
+  number        = "C12",
+  author        = "C. {de Boyer Mont\'{e}gut} and G. Madec and A. S. Fischer
+                  and A. Lazar and D. Iudicone",
+  year          = "2004",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/2004jc002378"
+}
+
+@article{         de-lavergne.madec.ea_JPO16,
+  title         = "The impact of a variable mixing efficiency on the abyssal
+                  overturning",
+  pages         = "663--681",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "46",
+  number        = "2",
+  author        = "C. {de Lavergne} and G. Madec and J. {Le Sommer} and A. J.
+                  G. Nurser and A. C. Naveira Garabato",
+  year          = "2016",
+  month         = "feb",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/jpo-d-14-0259.1"
+}
+
+@article{         debreu.vouland.ea_CG08,
+  title         = "{AGRIF}: Adaptive Grid Refinement In Fortran",
+  pages         = "8--13",
+  journal       = "Computers \& Geosciences",
+  volume        = "34",
+  number        = "1",
+  author        = "L. Debreu and C. Vouland and E. Blayo",
+  year          = "2008",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "0098-3004",
+  doi           = "10.1016/j.cageo.2007.01.009"
+}
+
+@incollection{    delecluse.madec_icol99,
+  title         = "Ocean modelling and the role of the ocean in the climate
+                  system",
+  pages         = "237--313",
+  booktitle     = "Modeling the Earth's Climate and its Variability",
+  editor        = "W. R. Holland and S. Joussaume and F. David",
+  series        = "Les Houches",
+  volume        = "67",
+  author        = "P. Del\'{e}cluse and G. Madec",
+  year          = "1999",
+  publisher     = "North Holland",
+  isbn          = "978-0-444-50338-1"
+}
+
+@phdthesis{       demange_phd14,
+  title         = "Advection and gravity waves propagation numerical schemes
+                  for oceanic circulation models",
+  pages         = "138",
+  author        = "J. Demange",
+  school        = "Grenoble University, France",
+  year          = "2014",
+  url           = "https://tel.archives-ouvertes.fr/tel-01104703/file/DEMANGE_2014_archivage.pdf"
+}
+
+@article{         dobricic.pinardi.ea_OS07,
+  title         = "Daily oceanographic analyses by Mediterranean Forecasting
+                  System at the basin scale",
+  pages         = "149--157",
+  journal       = "Ocean Science",
+  volume        = "3",
+  number        = "1",
+  author        = "S. Dobricic and N. Pinardi and M. Adani and M. Tonani and
+                  C. Fratianni and A. Bonazzi and V. Fernandez",
+  year          = "2007",
+  month         = "mar",
+  publisher     = "Copernicus GmbH",
+  issn          = "1812-0792",
+  doi           = "10.5194/os-3-149-2007"
+}
+
+@article{         drijfhout_JPO94,
+  title         = "Heat transport by mesoscale eddies in an ocean circulation
+                  Model",
+  pages         = "353--369",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "24",
+  number        = "2",
+  author        = "S. S. Drijfhout",
+  year          = "1994",
+  month         = "feb",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1994)024<0353:htbmei>2.0.co;2"
+}
+
+@article{         dukowicz.smith_JGR94,
+  title         = "Implicit free-surface method for the Bryan-Cox-Semtner
+                  ocean model",
+  pages         = "7991--8014",
+  journal       = "Journal of Geophysical Research",
+  volume        = "99",
+  number        = "C4",
+  author        = "J. K. Dukowicz and R. D. Smith",
+  year          = "1994",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/93jc03455"
+}
+
+@article{ edson.jampana.ea_JPO13,
+title = "On the Exchange of Momentum over the Open Ocean",
+pages = "1589--1610",
+journal = "Journal of Physical Oceanography",
+volume = "43",
+number = "8",
+author = "Edson, James B. and Jampana, Venkata and Weller, Robert A. and Bigorre, Sebastien P. and Plueddemann, Albert J. and Fairall, Christopher W. and Miller, Scott D. and Mahrt, Larry and Vickers, Dean and Hersbach, Hans",
+year = "2013",
+month = "aug",
+publisher = "American Meteorological Society",
+issn = "0022-3670",
+doi = "10.1175/JPO-D-12-0173.1"
+}
+
+@article{         egbert.ray_JGR01,
+  title         = "Estimates of {M2} tidal energy dissipation from
+                  {TOPEX}/Poseidon altimeter data",
+  pages         = "22475--22502",
+  journal       = "Journal of Geophysical Research",
+  volume        = "106",
+  number        = "C10",
+  author        = "G. D. Egbert and R. D. Ray",
+  year          = "2001",
+  month         = "oct",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/2000jc000699"
+}
+
+@article{         egbert.ray_N00,
+  title         = "Significant dissipation of tidal energy in the deep ocean
+                  inferred from satellite altimeter data",
+  pages         = "775--778",
+  journal       = "Nature",
+  volume        = "405",
+  number        = "6788",
+  author        = "G. D. Egbert and R. D. Ray",
+  year          = "2000",
+  month         = "jun",
+  publisher     = "Springer Nature",
+  issn          = "1476-4687",
+  doi           = "10.1038/35015531"
+}
+
+@article{         eiseman.stone_SR80,
+  title         = "Conservation laws of fluid dynamics - {A} survey",
+  pages         = "12--27",
+  journal       = "SIAM Review",
+  volume        = "22",
+  number        = "1",
+  author        = "P. R. Eiseman and A. P. Stone",
+  year          = "1980",
+  month         = "jan",
+  publisher     = "Society for Industrial & Applied Mathematics (SIAM)",
+  issn          = "1095-7200",
+  doi           = "10.1137/1022002"
+}
+
+@article{         emile-geay.madec_OS09,
+  title         = "Geothermal heating, diapycnal mixing and the abyssal
+                  circulation",
+  pages         = "203--217",
+  journal       = "Ocean Science",
+  volume        = "5",
+  number        = "2",
+  author        = "J. Emile-Geay and G. Madec",
+  year          = "2009",
+  month         = "jun",
+  publisher     = "Copernicus GmbH",
+  issn          = "1812-0792",
+  doi           = "10.5194/os-5-203-2009"
+}
+
+@article{         engedahl_T95,
+  title         = "Use of the flow relaxation scheme in a three-dimensional
+                  baroclinic ocean model with realistic topography",
+  pages         = "365--382",
+  journal       = "Tellus A",
+  volume        = "47",
+  number        = "3",
+  author        = "H. Engedahl",
+  year          = "1995",
+  month         = "jan",
+  publisher     = "Informa UK Limited",
+  issn          = "1600-0870",
+  doi           = "10.3402/tellusa.v47i3.11523"
+}
+
+@article{ fairall.bradley.ea_JC03,
+title = "Bulk parameterization of air-sea fluxes: Updates and verification for the COARE algorithm",
+pages = "571--591",
+journal = "Journal of Climate",
+volume = "16",
+number = "4",
+author = "Fairall, C. W. and Bradley, E. F. and Hare, J. E. and Grachev, A. A. and Edson, J. B.",
+year = "2003",
+publisher = "American Meteorological Society",
+issn = "08948755",
+doi = "10.1175/1520-0442(2003)016<0571:BPOASF>2.0.CO;2"
+}
+
+@phdthesis{       farge-coulombier_phd87,
+  title         = "Dynamique non-lin\'{e}aire des ondes et des tourbillons
+                  dans les \'{e}quations de Saint-Venant",
+  pages         = "353",
+  author        = "M. {Farge Coulombier}",
+  school        = "Paris VI University, France",
+  year          = "1987",
+  url           = "http://www.theses.fr/1987PA066365"
+}
+
+@article{         farrow.stevens_JPO95,
+  title         = "A new tracer advection scheme for Bryan and Cox type Ocean
+                  General Circulation Models",
+  pages         = "1731--1741",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "25",
+  number        = "7",
+  author        = "D. E. Farrow and D. P. Stevens",
+  year          = "1995",
+  month         = "jul",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1995)025<1731:antasf>2.0.co;2"
+}
+
+@article{         flather_JPO94,
+  title         = "A storm surge prediction model for the northern Bay of
+                  Bengal with application to the cyclone disaster in April
+                  1991",
+  pages         = "172--190",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "24",
+  number        = "1",
+  author        = "R. A. Flather",
+  year          = "1994",
+  month         = "jan",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1994)024<0172:asspmf>2.0.co;2"
+}
+
+@book{            fofonoff.millard_bk83,
+  pages         = "53",
+  booktitle     = "Algorithms for computation of fundamental properties of
+                  seawater",
+  editor        = "UNESCO/ICES/SCOR/IAPSO",
+  series        = "Technical Paper in Marine Science",
+  volume        = "44",
+  author        = "N P. Fofonoff and R. C. Millard",
+  year          = "1983",
+  publisher     = "UNESCO",
+  url           = "https://unesdoc.unesco.org/ark:/48223/pf0000059832.locale=en"
+}
+
+@article{         foxkemper.ferrari_JPO08,
+  title         = "Parameterization of Mixed Layer Eddies. Part I: Theory and Diagnosis",
+  pages         = "1145--1165",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "38",
+  number        = "6",
+  author        = "B. Fox-Kemper and R. Ferrari and B. Hallberg",
+  year          = "2008",
+  month         = "jun",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/2007JPO3792.1"
+}
+
+@article{         galperin.kantha.ea_JAS88,
+  title         = "A quasi-equilibrium turbulent energy model for geophysical
+                  flows",
+  pages         = "55--62",
+  journal       = "Journal of the Atmospheric Sciences",
+  volume        = "45",
+  number        = "1",
+  author        = "B. Galperin and L. H. Kantha and S. Hassid and A. Rosati",
+  year          = "1988",
+  month         = "jan",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0469",
+  doi           = "10.1175/1520-0469(1988)045<0055:aqetem>2.0.co;2"
+}
+
+@article{         gargett_JMR84,
+  title         = "Vertical eddy diffusivity in the ocean interior",
+  pages         = "359--393",
+  journal       = "Journal of Marine Research",
+  volume        = "42",
+  number        = "2",
+  author        = "A. E. Gargett",
+  year          = "1984",
+  month         = "may",
+  publisher     = "Journal of Marine Research/Yale",
+  issn          = "1543-9542",
+  doi           = "10.1357/002224084788502756"
+}
+
+@article{         gaspar.gregoris.ea_JGR90,
+  title         = "A simple eddy kinetic energy model for simulations of the
+                  oceanic vertical mixing: Tests at station Papa and
+                  long-term upper ocean study site",
+  pages         = "16179",
+  journal       = "Journal of Geophysical Research",
+  volume        = "95",
+  number        = "C9",
+  author        = "P. Gaspar and Y. Gr{\'e}goris and J.-M. Lefevre",
+  year          = "1990",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/jc095ic09p16179"
+}
+
+@article{         gent.mcwilliams_JPO90,
+  title         = "Isopycnal Mixing in Ocean Circulation Models",
+  pages         = "150--155",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "20",
+  number        = "1",
+  author        = "P. R. Gent and J. C. McWilliams",
+  year          = "1990",
+  month         = "jan",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1990)020<0150:imiocm>2.0.co;2"
+}
+
+@article{         gentemann.minnett.ea_JGR09,
+  title         = "Profiles of Ocean Surface Heating ({POSH}): {A} new model
+                  of upper ocean diurnal warming",
+  pages         = "C07017",
+  journal       = "Journal of Geophysical Research",
+  volume        = "114",
+  number        = "C7",
+  author        = "C. L. Gentemann and P. J. Minnett and B. Ward",
+  year          = "2009",
+  month         = "jul",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/2008jc004825"
+}
+
+@article{         gerdes.koberle.ea_CD91,
+  title         = "The influence of numerical advection schemes on the
+                  results of Ocean General Circulation Models",
+  pages         = "211--226",
+  journal       = "Climate Dynamics",
+  volume        = "5",
+  number        = "4",
+  author        = "R. Gerdes and C. K{\"{o}}berle and J. Willebrand",
+  year          = "1991",
+  month         = "jun",
+  publisher     = "Springer Nature",
+  issn          = "1432-0894",
+  doi           = "10.1007/bf00210006"
+}
+
+@article{         gerdes_JGR93*a,
+  title         = "A primitive equation ocean circulation model using a
+                  general vertical coordinate transformation: 1. Description
+                  and testing of the model",
+  pages         = "14683--14701",
+  journal       = "Journal of Geophysical Research",
+  volume        = "98",
+  number        = "C8",
+  author        = "R. Gerdes",
+  year          = "1993",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/93jc00760"
+}
+
+@article{         gerdes_JGR93*b,
+  title         = "A primitive equation ocean circulation model using a
+                  general vertical coordinate transformation: 2. Application
+                  to an overflow problem",
+  pages         = "14703--14726",
+  journal       = "Journal of Geophysical Research",
+  volume        = "98",
+  number        = "C8",
+  author        = "R. Gerdes",
+  year          = "1993",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/93jc00788"
+}
+
+@techreport{      gibson_rpt86,
+  title         = "Standards for software development and maintenance",
+  pages         = "21",
+  series        = "ECMWF Technical Memoranda",
+  number        = "120",
+  author        = "J. K. Gibson",
+  institution   = "ECMWF Operations Department; Reading, United Kingdom",
+  year          = "1986",
+  month         = "aug",
+  doi           = "10.21957/gi113q4gn"
+}
+
+@book{            gill_bk82,
+  pages         = "662",
+  booktitle     = "Atmosphere-Ocean Dynamics",
+  series        = "International Geophysics",
+  volume        = "30",
+  author        = "A. E. Gill",
+  year          = "1982",
+  month         = "nov",
+  publisher     = "Elsevier",
+  issn          = "0074-6142",
+  isbn          = "978-0-12-283522-3",
+  doi           = "10.1016/s0074-6142(08)x6002-4"
+}
+
+@article{         goff_JGR10,
+  title         = "Global prediction of abyssal hill root-mean-square heights
+                  from small-scale altimetric gravity variability",
+  pages         = "B12104",
+  journal       = "Journal of Geophysical Research",
+  volume        = "115",
+  number        = "B12",
+  author        = "J. A. Goff",
+  year          = "2010",
+  month         = "dec",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/2010jb007867"
+}
+
+@article{         goosse.deleersnijder.ea_JGR99,
+  title         = "Sensitivity of a global coupled ocean-sea ice model to the
+                  parameterization of vertical mixing",
+  pages         = "13681--13695",
+  journal       = "Journal of Geophysical Research",
+  volume        = "104",
+  number        = "C6",
+  author        = "H. Goosse and E. Deleersnijder and T. Fichefet and M. H.
+                  England",
+  year          = "1999",
+  month         = "jun",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/1999jc900099"
+}
+
+@article{         graham.mcdougall_JPO13,
+  title         = "Quantifying the nonconservative production of conservative
+                  temperature, potential temperature, and entropy",
+  pages         = "838--862",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "43",
+  number        = "5",
+  author        = "F. S. Graham and T. J. McDougall",
+  year          = "2013",
+  month         = "may",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/jpo-d-11-0188.1"
+}
+
+@article{         greatbatch_JGR94,
+  title         = "A note on the representation of steric sea level in models
+                  that conserve volume rather than mass",
+  pages         = "12767--12771",
+  journal       = "Journal of Geophysical Research",
+  volume        = "99",
+  number        = "C6",
+  author        = "R. J. Greatbatch",
+  year          = "1994",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/94jc00847"
+}
+
+@article{         griffies.biastoch.ea_OM09,
+  title         = "Coordinated Ocean-ice Reference Experiments ({CORE}s)",
+  pages         = "1--46",
+  journal       = "Ocean Modelling",
+  volume        = "26",
+  number        = "1-2",
+  author        = "S. M. Griffies and A. Biastoch and C. B{\"{o}}ning and F.
+                  Bryan and G. Danabasoglu and E. P. Chassignet and M. H.
+                  England and R. Gerdes and H. Haak and R. W. Hallberg and W.
+                  Hazeleger and J. Jungclaus and W. G. Large and G. Madec and
+                  A. Pirani and B. L. Samuels and M. Scheinert and A. Sen
+                  Gupta and C. A. Severijns and H. L. Simmons and A.-M.
+                  Tr\'{e}guier and M. Winton and S. Yeager and J. Yin",
+  year          = "2009",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2008.08.007"
+}
+
+@article{         griffies.gnanadesikan.ea_JPO98,
+  title         = "Isoneutral Diffusion in a z-coordinate Ocean Model",
+  pages         = "805--830",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "28",
+  number        = "5",
+  author        = "S. M. Griffies and A. Gnanadesikan and R. C. Pacanowski
+                  and V. D. Larichev and J. K. Dukowicz and R. D. Smith",
+  year          = "1998",
+  month         = "may",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1998)028<0805:idiazc>2.0.co;2"
+}
+
+@article{         griffies.pacanowski.ea_MWR01,
+  title         = "Tracer Conservation with an Explicit Free Surface Method
+                  for z-coordinate Ocean Models",
+  pages         = "1081--1098",
+  journal       = "Monthly Weather Review",
+  volume        = "129",
+  number        = "5",
+  author        = "S. M. Griffies and R. C. Pacanowski and M. Schmidt and V.
+                  Balaji",
+  year          = "2001",
+  month         = "may",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0493",
+  doi           = "10.1175/1520-0493(2001)129<1081:tcwaef>2.0.co;2"
+}
+
+@article{         griffies_JPO98,
+  title         = "The Gent-McWilliams skew-flux",
+  pages         = "831--841",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "28",
+  number        = "5",
+  author        = "S. M. Griffies",
+  year          = "1998",
+  month         = "may",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1998)028<0831:tgmsf>2.0.co;2"
+}
+
+@book{            griffies_bk04,
+  pages         = "434",
+  booktitle     = "Fundamentals of ocean climate models",
+  author        = "S. M. Griffies",
+  year          = "2004",
+  month         = "dec",
+  publisher     = "Princeton University Press",
+  isbn          = "978-0-691-18712-9",
+  doi           = "10.2307/j.ctv301gzg"
+}
+
+@article{         guilyardi.madec.ea_CD01,
+  title         = "The role of lateral ocean physics in the upper ocean
+                  thermal balance of a coupled ocean-atmosphere {GCM}",
+  pages         = "589--599",
+  journal       = "Climate Dynamics",
+  volume        = "17",
+  number        = "8",
+  author        = "E. Guilyardi and G. Madec and L. Terray",
+  year          = "2001",
+  month         = "may",
+  publisher     = "Springer Science and Business Media LLC",
+  issn          = "0930-7575",
+  doi           = "10.1007/pl00007930"
+}
+
+@article{         haney_JPO91,
+  title         = "On the Pressure Gradient Force over Steep Topography in
+                  Sigma Coordinate Ocean Models",
+  pages         = "610--619",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "21",
+  number        = "4",
+  author        = "R. L. Haney",
+  year          = "1991",
+  month         = "apr",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1991)021<0610:otpgfo>2.0.co;2"
+}
+
+@article{         hazeleger.drijfhout_JGR00,
+  title         = "A model study on internally generated variability in
+                  subtropical mode water formation",
+  pages         = "13965--13979",
+  journal       = "Journal of Geophysical Research",
+  volume        = "105",
+  number        = "C6",
+  author        = "W. Hazeleger and S. S. Drijfhout",
+  year          = "2000",
+  month         = "jun",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/2000jc900041"
+}
+
+@article{         hazeleger.drijfhout_JPO00,
+  title         = "Eddy subduction in a model of the subtropical gyre",
+  pages         = "677--695",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "30",
+  number        = "4",
+  author        = "W. Hazeleger and S. S. Drijfhout",
+  year          = "2000",
+  month         = "apr",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(2000)030<0677:esiamo>2.0.co;2"
+}
+
+@article{         hazeleger.drijfhout_JPO98,
+  title         = "Mode water variability in a model of the subtropical gyre:
+                  response to anomalous forcing",
+  pages         = "266--288",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "28",
+  number        = "2",
+  author        = "W. Hazeleger and S. S. Drijfhout",
+  year          = "1998",
+  month         = "feb",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1998)028<0266:mwviam>2.0.co;2"
+}
+
+@article{         hazeleger.drijfhout_JPO99,
+  title         = "Stochastically forced mode water variability",
+  pages         = "1772--1786",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "29",
+  number        = "8",
+  author        = "W. Hazeleger and S. S. Drijfhout",
+  year          = "1999",
+  month         = "aug",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1999)029<1772:sfmwv>2.0.co;2"
+}
+
+@article{         he.ding_JS01,
+  title         = "Using accurate arithmetics to improve numerical
+                  reproducibility and stability in parallel applications",
+  pages         = "259--277",
+  journal       = "The Journal of Supercomputing",
+  volume        = "18",
+  number        = "3",
+  author        = "Y. He and C. H. Q. Ding",
+  year          = "2001",
+  publisher     = "Springer Nature",
+  issn          = "0920-8542",
+  doi           = "10.1023/a:1008153532043"
+}
+
+@article{         hirt.amsden.ea_JCP74,
+  title         = "An arbitrary Lagrangian-Eulerian computing method for all
+                  flow speeds",
+  pages         = "227--253",
+  journal       = "Journal of Computational Physics",
+  volume        = "14",
+  number        = "3",
+  author        = "C. W. Hirt and A. A. Amsden and J. L. Cook",
+  year          = "1974",
+  month         = "mar",
+  publisher     = "Elsevier BV",
+  issn          = "0021-9991",
+  doi           = "10.1016/0021-9991(74)90051-5"
+}
+
+@article{         hofmeister.burchard.ea_OM10,
+  title         = "Non-uniform adaptive vertical grids for 3{D} numerical
+                  ocean models",
+  pages         = "70--86",
+  journal       = "Ocean Modelling",
+  volume        = "33",
+  number        = "1-2",
+  author        = "R. Hofmeister and H. Burchard and J.-M. Beckers",
+  year          = "2010",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2009.12.003"
+}
+
+@article{         holland.jenkins_JPO99,
+  title         = "Modeling thermodynamic ice-ocean interactions at the base
+                  of an ice shelf",
+  pages         = "1787--1800",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "29",
+  number        = "8",
+  author        = "D. M. Holland and A. Jenkins",
+  year          = "1999",
+  month         = "aug",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1999)029<1787:mtioia>2.0.co;2"
+}
+
+@techreport{      hunter_rpt06,
+  title         = "Specification for Test Models of Ice Shelf Cavities",
+  pages         = "17",
+  number        = "7",
+  author        = "J. R. Hunter",
+  institution   = "Antarctic Climate \& Ecosystems Cooperative Research
+                  Centre",
+  year          = "2006",
+  month         = "jun",
+  url           = "http://staff.acecrc.org.au/~bkgalton/ISOMIP/test_cavities.pdf"
+}
+
+@book{            ioc.iapso_bk10,
+  title         = "The international thermodynamic equation of seawater -
+                  2010: Calculation and use of thermodynamic properties",
+  pages         = "196",
+  editor        = "Intergovernmental Oceanographic Commission",
+  series        = "Manuals and Guides",
+  volume        = "56",
+  author        = "IOC, SCOR and IAPSO",
+  year          = "2010",
+  month         = "mar",
+  publisher     = "UNESCO",
+  url           = "https://unesdoc.unesco.org/ark:/48223/pf0000188170.locale=en"
+}
+
+@article{         jackson.rehmann_JPO14,
+  title         = "Experiments on differential scalar mixing in turbulence in
+                  a sheared, stratified flow",
+  pages         = "2661--2680",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "44",
+  number        = "10",
+  author        = "P. R. Jackson and C. R. Rehmann",
+  year          = "2014",
+  month         = "oct",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/jpo-d-14-0027.1"
+}
+
+@techreport{      janssen.breivik.ea_rpt13,
+  title         = "Air-sea interaction and surface waves",
+  pages         = "36",
+  series        = "ECMWF Technical Memoranda",
+  volume        = "712",
+  author        = "P. A. E. M. Janssen and {\O}. Breivik and K. Mogensen and
+                  F. Vitart and M. Alonso-Balmaseda and J.-R. Bidlot and S.
+                  Keeley and M. Leutbecher and L. Magnusson and F. Molteni",
+  institution   = "ECMWF Research Departement; Reading, United Kingdom",
+  year          = "2013",
+  month         = "nov",
+  doi           = "10.21957/0kg73joh"
+}
+
+@article{         jenkins.nicholls.ea_JPO10,
+  title         = "Observation and parameterization of ablation at the base
+                  of Ronne Ice Shelf, Antarctica",
+  pages         = "2298--2312",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "40",
+  number        = "10",
+  author        = "A. Jenkins and K. W. Nicholls and H. F. J. Corr",
+  year          = "2010",
+  month         = "oct",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/2010jpo4317.1"
+}
+
+@article{         jenkins_JGR91,
+  title         = "A one-dimensional model of ice shelf-ocean interaction",
+  pages         = "20671--20677",
+  journal       = "Journal of Geophysical Research",
+  volume        = "96",
+  number        = "C11",
+  author        = "A. Jenkins",
+  year          = "1991",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/91jc01842"
+}
+
+@article{         kantha.carniel_JMR03,
+  title         = "Comments on ``{A} generic length-scale equation for
+                  geophysical turbulence models'' by {L}. Umlauf and {H}.
+                  Burchard",
+  pages         = "693--702",
+  journal       = "Journal of Marine Research",
+  volume        = "61",
+  number        = "5",
+  author        = "L. Kantha and S. Carniel",
+  year          = "2003",
+  month         = "sep",
+  publisher     = "Journal of Marine Research/Yale",
+  issn          = "1543-9542",
+  doi           = "10.1357/002224003771816007"
+}
+
+@article{         kantha.clayson_JGR94,
+  title         = "An improved mixed layer model for geophysical
+                  applications",
+  pages         = "25235--25266",
+  journal       = "Journal of Geophysical Research",
+  volume        = "99",
+  number        = "C12",
+  author        = "L. H. Kantha and C. A. Clayson",
+  year          = "1994",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/94jc02257"
+}
+
+@article{         kasahara_MWR74,
+  title         = "Various vertical coordinate systems used for numerical
+                  weather prediction",
+  pages         = "509--522",
+  journal       = "Monthly Weather Review",
+  volume        = "102",
+  number        = "7",
+  author        = "A. Kasahara",
+  year          = "1974",
+  month         = "jul",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0493",
+  doi           = "10.1175/1520-0493(1974)102<0509:vvcsuf>2.0.co;2"
+}
+
+@article{         killworth.webb.ea_JPO91,
+  title         = "The development of a free-surface Bryan-Cox-Semtner ocean
+                  model",
+  pages         = "1333--1348",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "21",
+  number        = "9",
+  author        = "P. D. Killworth and D. J. Webb and D. Stainforth and S. M.
+                  Paterson",
+  year          = "1991",
+  month         = "sep",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1991)021<1333:tdoafs>2.0.co;2"
+}
+
+@article{         killworth_JPO92,
+  title         = "An equivalent-barotropic mode in the fine resolution
+                  Antarctic model",
+  pages         = "1379--1387",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "22",
+  number        = "11",
+  author        = "P. D. Killworth",
+  year          = "1992",
+  month         = "nov",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1992)022<1379:aebmit>2.0.co;2"
+}
+
+@inproceedings{   killworth_iprc89,
+  title         = "On the parameterization of deep convection in ocean
+                  models",
+  pages         = "59--74",
+  booktitle     = "Parameterization of small-scale processes",
+  editor        = "P. Muller and D. Henderson",
+  author        = "P. D. Killworth",
+  year          = "1989",
+  month         = "jan",
+  publisher     = "Hawaii Institute of Geophysics",
+  url           = "http://www.soest.hawaii.edu/PubServices/1989pdfs/Killworth.pdf"
+}
+
+@article{         koch-larrouy.lengaigne.ea_CD10,
+  title         = "Tidal mixing in the Indonesian Seas and its effect on the
+                  tropical climate system",
+  pages         = "891--904",
+  journal       = "Climate Dynamics",
+  volume        = "34",
+  number        = "6",
+  author        = "A. Koch-Larrouy and M. Lengaigne and P. Terray and G.
+                  Madec and S. Masson",
+  year          = "2010",
+  month         = "aug",
+  publisher     = "Springer Nature",
+  issn          = "1432-0894",
+  doi           = "10.1007/s00382-009-0642-4"
+}
+
+@article{         koch-larrouy.madec.ea_GRL07,
+  title         = "On the transformation of Pacific water into Indonesian
+                  ThroughFlow water by internal tidal mixing",
+  pages         = "L04604",
+  journal       = "Geophysical Research Letters",
+  volume        = "34",
+  number        = "4",
+  author        = "A. Koch-Larrouy and G. Madec and P. Bouruet-Aubertot and
+                  T. Gerkema and L. Bessi\`{e}res and R. Molcard",
+  year          = "2007",
+  month         = "feb",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0094-8276",
+  doi           = "10.1029/2006gl028405"
+}
+
+@article{         koch-larrouy.madec.ea_OD08*a,
+  title         = "Water mass transformation along the Indonesian ThroughFlow
+                  in an {OGCM}",
+  pages         = "289--309",
+  journal       = "Ocean Dynamics",
+  volume        = "58",
+  number        = "3-4",
+  author        = "A. Koch-Larrouy and G. Madec and B. Blanke and R. Molcard",
+  year          = "2008",
+  month         = "oct",
+  publisher     = "Springer Nature",
+  issn          = "1616-7228",
+  doi           = "10.1007/s10236-008-0155-4"
+}
+
+@article{         koch-larrouy.madec.ea_OD08*b,
+  title         = "Physical processes contributing to the water mass
+                  transformation of the Indonesian ThroughFlow",
+  pages         = "275--288",
+  journal       = "Ocean Dynamics",
+  volume        = "58",
+  number        = "3-4",
+  author        = "A. Koch-Larrouy and G. Madec and D. Iudicone and A.
+                  Atmadipoera and R. Molcard",
+  year          = "2008",
+  month         = "oct",
+  publisher     = "Springer Nature",
+  issn          = "1616-7228",
+  doi           = "10.1007/s10236-008-0154-5"
+}
+
+@article{         kolmogorov_IANS42,
+  title         = "Equations of turbulent motion in an incompressible fluid",
+  pages         = "56--58",
+  journal       = "Izvestiya Akademiya Nauk SSSR",
+  series        = "Fizika",
+  volume        = "6",
+  author        = "A. N. Kolmogorov",
+  year          = "1942"
+}
+
+@techreport{      large.yeager_rpt04,
+  title         = "Diurnal to decadal global forcing for ocean and sea-ice
+                  models: the data sets and flux climatologies",
+  author        = "W. G. Large and S. G. Yeager",
+  institution   = "{NCAR} Climate and global dynamics division; Boulder, CO,
+                  United States",
+  year          = "2004",
+  month         = "may",
+  doi           = "10.5065/d6kk98q6"
+}
+
+@article{         lazar.madec.ea_JPO99,
+  title         = "The Deep Interior Downwelling, the Veronis Effect, and
+                  Mesoscale Tracer Transport Parameterizations in an {OGCM}",
+  pages         = "2945--2961",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "29",
+  number        = "11",
+  author        = "A. Lazar and G. Madec and P. Del\'{e}cluse",
+  year          = "1999",
+  month         = "nov",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1999)029<2945:tdidtv>2.0.co;2"
+}
+
+@phdthesis{       lazar_phd97,
+  title         = "La branche froide de la circulation thermohaline -
+                  sensibilit\'{e} \`{a} la diffusion turbulente dans un
+                  mod\`{e}le de circulation g\'{e}n\'{e}rale
+                  id\'{e}alis\'{e}e",
+  pages         = "269",
+  author        = "A. Lazar",
+  school        = "Universit\'{e} Pierre et Marie Curie, Paris, France",
+  year          = "1997",
+  url           = "http://www.theses.fr/1997PA066680"
+}
+
+@article{         le-sommer.penduff.ea_OM09,
+  title         = "How momentum advection schemes influence
+                  current-topography interactions at eddy permitting
+                  resolution",
+  pages         = "1--14",
+  journal       = "Ocean Modelling",
+  volume        = "29",
+  number        = "1",
+  author        = "J. {Le Sommer} and T. Penduff and S. Theetten and G. Madec
+                  and B. Barnier",
+  year          = "2009",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2008.11.007"
+}
+
+@article{         leclair.madec_OM09,
+  title         = "A conservative leapfrog time stepping method",
+  pages         = "88--94",
+  journal       = "Ocean Modelling",
+  volume        = "30",
+  number        = "2-3",
+  author        = "M. Leclair and G. Madec",
+  year          = "2009",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2009.06.006"
+}
+
+@article{         leclair.madec_OM11,
+  title         = "$\tilde{z}$-coordinate, an arbitrary Lagrangian-Eulerian
+                  coordinate separating high and low frequency motions",
+  pages         = "139--152",
+  journal       = "Ocean Modelling",
+  volume        = "37",
+  number        = "3-4",
+  author        = "M. Leclair and G. Madec",
+  year          = "2011",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2011.02.001"
+}
+
+@phdthesis{       leclair_phd10,
+  title         = "Introduction d'une coordonn\'{e}e verticale arbitrairement
+                  Lagrangienne Eul\'{e}rienne dans le code d'oc\'{e}an
+                  {NEMO}",
+  pages         = "163",
+  author        = "M. Leclair",
+  school        = "Universit\'{e} Pierre and Marie Curie, Paris, France",
+  year          = "2010",
+  url           = "http://www.theses.fr/2010PA066728"
+}
+
+@article{         lele_JCP92,
+  title         = "Compact finite difference schemes with spectral-like
+                  resolution",
+  pages         = "16--42",
+  journal       = "Journal of Computational Physics",
+  volume        = "103",
+  number        = "1",
+  author        = "S. K. Lele",
+  year          = "1992",
+  month         = "nov",
+  publisher     = "Elsevier BV",
+  issn          = "0021-9991",
+  doi           = "10.1016/0021-9991(92)90324-r"
+}
+
+@article{         lemarie.debreu.ea_OM12,
+  title         = "On the stability and accuracy of the harmonic and
+                  biharmonic isoneutral mixing operators in ocean models",
+  pages         = "9--35",
+  journal       = "Ocean Modelling",
+  volume        = "52-53",
+  author        = "F. Lemari\'{e} and L. Debreu and A. F. Shchepetkin and J.
+                  C. McWilliams",
+  year          = "2012",
+  month         = "aug",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2012.04.007"
+}
+
+@article{         lemarie.debreu.ea_OM15,
+  title         = "Stability constraints for oceanic numerical models:
+                  implications for the formulation of time and space
+                  discretizations",
+  pages         = "124--148",
+  journal       = "Ocean Modelling",
+  volume        = "92",
+  author        = "F. Lemari\'{e} and L. Debreu and G. Madec and J. Demange
+                  and J. M. Molines and M. Honnorat",
+  year          = "2015",
+  month         = "aug",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2015.06.006"
+}
+
+@article{         lengaigne.madec.ea_JGR03,
+  title         = "Impact of isopycnal mixing on the tropical ocean
+                  circulation",
+  pages         = "3345",
+  journal       = "Journal of Geophysical Research",
+  volume        = "108",
+  number        = "C11",
+  author        = "M. Lengaigne and G. Madec and G. Alory and C. Menkes",
+  year          = "2003",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/2002jc001704"
+}
+
+@article{         lengaigne.menkes.ea_CD07,
+  title         = "Influence of the oceanic biology on the tropical Pacific
+                  climate in a Coupled General Circulation Model",
+  pages         = "503--516",
+  journal       = "Climate Dynamics",
+  volume        = "28",
+  number        = "5",
+  author        = "M. Lengaigne and C. Menkes and O. Aumont and T. Gorgues
+                  and L. Bopp and J.-M. Andr\'{e} and G. Madec",
+  year          = "2007",
+  month         = "nov",
+  publisher     = "Springer Nature",
+  issn          = "1432-0894",
+  doi           = "10.1007/s00382-006-0200-2"
+}
+
+@article{         leonard_CMAME79,
+  title         = "A stable and accurate convective modelling procedure based
+                  on quadratic upstream interpolation",
+  pages         = "59--98",
+  journal       = "Computer Methods in Applied Mechanics and Engineering",
+  volume        = "19",
+  number        = "1",
+  author        = "B. P. Leonard",
+  year          = "1979",
+  month         = "jun",
+  publisher     = "Elsevier BV",
+  issn          = "0045-7825",
+  doi           = "10.1016/0045-7825(79)90034-3"
+}
+
+@article{         leonard_CMAME91,
+  title         = "The {ULTIMATE} conservative difference scheme applied to
+                  unsteady one-dimensional advection",
+  pages         = "17--74",
+  journal       = "Computer Methods in Applied Mechanics and Engineering",
+  volume        = "88",
+  number        = "1",
+  author        = "B. P. Leonard",
+  year          = "1991",
+  month         = "jun",
+  publisher     = "Elsevier BV",
+  issn          = "0045-7825",
+  doi           = "10.1016/0045-7825(91)90232-u"
+}
+
+@article{         lermusiaux_JMS01,
+  title         = "Evolving the subspace of the three-dimensional multiscale
+                  ocean variability: Massachusetts Bay",
+  pages         = "385--422",
+  journal       = "Journal of Marine Systems",
+  volume        = "29",
+  number        = "1-4",
+  author        = "P. F. J. Lermusiaux",
+  year          = "2001",
+  month         = "may",
+  publisher     = "Elsevier BV",
+  issn          = "0924-7963",
+  doi           = "10.1016/s0924-7963(01)00025-2"
+}
+
+@techreport{      levier.treguier.ea_rpt07,
+  title         = "Free surface and variable volume in the {NEMO} code",
+  pages         = "47",
+  author        = "B. Levier and A.-M. Tr\'{e}guier and G. Madec and V.
+                  Garnier",
+  institution   = "European Union: Marine Environment and Security for the
+                  European Area (MERSEA) Integrated Project",
+  year          = "2007",
+  month         = "may",
+  doi           = "10.5281/zenodo.3244182"
+}
+
+@article{         levy.estublier.ea_GRL01,
+  title         = "Choice of an advection scheme for biogeochemical models",
+  pages         = "3725--3728",
+  journal       = "Geophysical Research Letters",
+  volume        = "28",
+  number        = "19",
+  author        = "M. L\'{e}vy and A. Estublier and G Madec",
+  year          = "2001",
+  month         = "oct",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0094-8276",
+  doi           = "10.1029/2001gl012947"
+}
+
+@article{         levy.klein.ea_OM10,
+  title         = "Modifications of gyre circulation by sub-mesoscale
+                  physics",
+  pages         = "1--15",
+  journal       = "Ocean Modelling",
+  volume        = "34",
+  number        = "1-2",
+  author        = "M. L\'{e}vy and P. Klein and A.-M. Tr\'{e}guier and D.
+                  Iovino and G. Madec and S. Masson and K. Takahashi",
+  year          = "2010",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2010.04.001"
+}
+
+@article{         li.garrett_JMR93,
+  title         = "Cell merging and the jet/downwelling ratio in Langmuir
+                  circulation",
+  pages         = "737--769",
+  journal       = "Journal of Marine Research",
+  volume        = "51",
+  number        = "4",
+  author        = "M. Li and C. Garrett",
+  year          = "1993",
+  month         = "nov",
+  publisher     = "Journal of Marine Research/Yale",
+  issn          = "1543-9542",
+  doi           = "10.1357/0022240933223945"
+}
+
+@article{         losch_JGR08,
+  title         = "Modeling ice shelf cavities in a z coordinate Ocean
+                  General Circulation Model",
+  journal       = "Journal of Geophysical Research",
+  volume        = "113",
+  number        = "C8",
+  author        = "M. Losch",
+  year          = "2008",
+  month         = "aug",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/2007jc004368"
+}
+
+@article{         lott.madec.ea_OM90,
+  title         = "Topographic experiments in an Ocean General Circulation
+                  Model",
+  pages         = "1--4",
+  journal       = "Ocean Modelling",
+  volume        = "88",
+  author        = "F. Lott and G. Madec and J. Verron",
+  year          = "1990"
+}
+
+@article{	  lupkes.gryanik.ea_JGR12,
+  author 	= "L{\"{u}}pkes, Christof and Gryanik, Vladimir M. and Hartmann, J{\"{o}}rg and Andreas, Edgar L.",
+  doi 		= "10.1029/2012JD017630",
+  issn 		= "01480227",
+  journal 	= "Journal of Geophysical Research Atmospheres",
+  number 	= "13",
+  pages 	= "1--18",
+  title 	= "A parametrization, based on sea ice morphology, of the neutral atmospheric drag coefficients for weather prediction and climate models",
+  volume 	= "117",
+  year 		= "2012"
+}
+
+@article{	  lupkes.gryanik_JGR15,
+  author 	= "L{\"{u}}pkes, Christof and Gryanik, Vladimir M.",
+  doi 		= "10.1002/2014JD022418",
+  issn 		= "21562202",
+  journal 	= "Journal of Geophysical Research",
+  number 	= "2",
+  pages 	= "552--581",
+  title 	= "A stability-dependent parametrization of transfer coefficients formomentum and heat over polar sea ice to be used in climate models",
+  volume 	= "120",
+  year 		= "2015"
+}
+
+@article{         madec.chartier.ea_DAO91,
+  title         = "The effect of thermohaline forcing variability on deep
+                  water formation in the western Mediterranean Sea: a
+                  high-resolution three-dimensional numerical study",
+  pages         = "301--332",
+  journal       = "Dynamics of Atmospheres and Oceans",
+  volume        = "15",
+  number        = "3-5",
+  author        = "G. Madec and M. Chartier and M. Cr\'{e}pon",
+  year          = "1991",
+  month         = "apr",
+  publisher     = "Elsevier BV",
+  issn          = "0377-0265",
+  doi           = "10.1016/0377-0265(91)90024-a"
+}
+
+@inproceedings{   madec.crepon_iprc91,
+  title         = "Thermohaline-driven deep water formation in the
+                  northwestern Mediterranean Sea",
+  chapter       = "15",
+  pages         = "241--265",
+  booktitle     = "Deep convection and deep water formation in the oceans,
+                  Proceedings of the international Monterey colloquium on
+                  deep convection and deep water formation in the oceans",
+  editor        = "P.C. Chu and J.C. Gascard",
+  series        = "Elsevier Oceanography",
+  volume        = "57",
+  author        = "G. Madec and M. Cr\'{e}pon",
+  year          = "1991",
+  publisher     = "Elsevier",
+  issn          = "0422-9894",
+  isbn          = "978-0-444-88764-1",
+  doi           = "10.1016/s0422-9894(08)70071-0"
+}
+
+@article{         madec.delecluse.ea_JPO91,
+  title         = "A three-dimensional numerical study of deep-water
+                  formation in the northwestern Mediterranean Sea",
+  pages         = "1349--1371",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "21",
+  number        = "9",
+  author        = "G. Madec and P. Del\'{e}cluse and M. Cr\'{e}pon and M.
+                  Chartier",
+  year          = "1991",
+  month         = "sep",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1991)021<1349:atdnso>2.0.co;2"
+}
+
+@article{         madec.delecluse.ea_JPO96,
+  title         = "Large-Scale Preconditioning of Deep-Water Formation in the
+                  northwestern Mediterranean Sea",
+  pages         = "1393--1408",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "26",
+  number        = "8",
+  author        = "G. Madec and P. Del\'{e}cluse and M. Cr\'{e}pon and F.
+                  Lott",
+  year          = "1996",
+  month         = "aug",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1996)026<1393:lspodw>2.0.co;2"
+}
+
+@book{            madec.delecluse.ea_NPM98,
+  title         = "{OPA} 8.1 Ocean General Circulation Model reference
+                  manual",
+  pages         = "91",
+  journal       = "Note du Pole de Mod\'{e}lisation",
+  volume        = "11",
+  author        = "G. Madec and P. Del\'{e}cluse and M. Imbard and C.
+                  L\'{e}vy",
+  year          = "1998",
+  publisher     = "Institut Pierre Simon Laplace ({IPSL})",
+  issn          = "1288-1619",
+  url           = "http://cmc.ipsl.fr/images/publications/scientific_notes/note11.pdf"
+}
+
+@article{         madec.delecluse_IWN97,
+  title         = "The {OPA}/{ARPEGE} and {OPA}/{LMD} Global Ocean-Atmosphere
+                  Coupled Model",
+  pages         = "12--15",
+  journal       = "International WOCE Newsletter",
+  volume        = "26",
+  author        = "G. Madec and P. Del\'{e}cluse",
+  year          = "1997",
+  month         = "apr",
+  publisher     = "University of Southampton",
+  url           = "https://www.nodc.noaa.gov/woce/wdiu/wocedocs/newsltr/news26/news26.pdf"
+}
+
+@article{         madec.imbard_CD96,
+  title         = "A global ocean mesh to overcome the North Pole
+                  singularity",
+  pages         = "381--388",
+  journal       = "Climate Dynamics",
+  volume        = "12",
+  number        = "6",
+  author        = "G. Madec and M. Imbard",
+  year          = "1996",
+  month         = "may",
+  publisher     = "Springer Nature",
+  issn          = "1432-0894",
+  doi           = "10.1007/bf00211684"
+}
+
+@article{         maltrud.smith.ea_JGR98,
+  title         = "Global eddy-resolving ocean simulations driven by
+                  1985-1995 atmospheric winds",
+  pages         = "30825--30853",
+  journal       = "Journal of Geophysical Research",
+  volume        = "103",
+  number        = "C13",
+  author        = "M. E. Maltrud and R. D. Smith and A. J. Semtner and R. C.
+                  Malone",
+  year          = "1998",
+  month         = "dec",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/1998jc900013"
+}
+
+@article{         marchesiello.mcwilliams.ea_OM01,
+  title         = "Open boundary conditions for long-term integration of
+                  regional oceanic models",
+  pages         = "1--20",
+  journal       = "Ocean Modelling",
+  volume        = "3",
+  number        = "1-2",
+  author        = "P. Marchesiello and J. C. McWilliams and A. Shchepetkin",
+  year          = "2001",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/s1463-5003(00)00013-5"
+}
+
+@article{         marsaleix.auclair.ea_OM08,
+  title         = "Energy conservation issues in sigma-coordinate
+                  free-surface ocean models",
+  pages         = "61--89",
+  journal       = "Ocean Modelling",
+  volume        = "20",
+  number        = "1",
+  author        = "P. Marsaleix and F. Auclair and J. W. Floor and M. J.
+                  Herrmann and C. Estournel and I. Pairaud and C. Ulses",
+  year          = "2008",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2007.07.005"
+}
+
+@article{         marsh.ivchenko.ea_GMD15,
+  title         = "{NEMO}-{ICB} (v1.0): interactive icebergs in the {NEMO}
+                  ocean model globally configured at eddy-permitting
+                  resolution",
+  pages         = "1547--1562",
+  journal       = "Geoscientific Model Development",
+  volume        = "8",
+  number        = "5",
+  author        = "R. Marsh and V. O. Ivchenko and N. Skliris and S. Alderson
+                  and G. R. Bigg and G. Madec and A. T. Blaker and Y. Aksenov
+                  and B. Sinha and A. C. Coward and J. {Le Sommer} and N.
+                  Merino and V. B. Zalesny",
+  year          = "2015",
+  month         = "may",
+  publisher     = "Copernicus GmbH",
+  issn          = "1991-9603",
+  doi           = "10.5194/gmd-8-1547-2015"
+}
+
+@article{         marti.madec.ea_JGR92,
+  title         = "Comment on ``{N}et diffusivity in ocean general
+                  circulation models with nonuniform grids'' by {F}. {L}. Yin
+                  and {I}. {Y}. Fung",
+  pages         = "12763--12766",
+  journal       = "Journal of Geophysical Research",
+  volume        = "97",
+  number        = "C8",
+  author        = "O. Marti and G. Madec and P. Del\'{e}cluse",
+  year          = "1992",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/92jc00306"
+}
+
+@article{         martin.adcroft_OM10,
+  title         = "Parameterizing the fresh-water flux from land ice to ocean
+                  with interactive icebergs in a coupled climate model",
+  pages         = "111--124",
+  journal       = "Ocean Modelling",
+  volume        = "34",
+  number        = "3-4",
+  author        = "T. Martin and A. Adcroft",
+  year          = "2010",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2010.05.001"
+}
+
+@article{         mathiot.jenkins.ea_GMD17,
+  title         = "Explicit representation and parametrised impacts of under
+                  ice shelf seas in the \zstar coordinate ocean model {NEMO}
+                  3.6",
+  pages         = "2849--2874",
+  journal       = "Geoscientific Model Development",
+  volume        = "10",
+  number        = "7",
+  author        = "P. Mathiot and A. Jenkins and C. Harris and G. Madec",
+  year          = "2017",
+  month         = "jul",
+  publisher     = "Copernicus GmbH",
+  issn          = "1991-9603",
+  doi           = "10.5194/gmd-10-2849-2017"
+}
+
+@article{         mcdougall.taylor_JMR84,
+  title         = "Flux measurements across a finger interface at low values
+                  of the stability ratio",
+  pages         = "1--14",
+  journal       = "Journal of Marine Research",
+  volume        = "42",
+  number        = "1",
+  author        = "T. J. McDougall and J. R. Taylor",
+  year          = "1984",
+  month         = "feb",
+  publisher     = "Journal of Marine Research/Yale",
+  issn          = "1543-9542",
+  doi           = "10.1357/002224084788506095"
+}
+
+@article{         mcdougall_JPO87,
+  title         = "Neutral Surfaces",
+  pages         = "1950--1964",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "17",
+  number        = "11",
+  author        = "T. J. McDougall",
+  year          = "1987",
+  month         = "nov",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1987)017<1950:ns>2.0.co;2"
+}
+
+@article{         mellor.blumberg_JPO04,
+  title         = "Wave Breaking and Ocean Surface Layer Thermal Response",
+  pages         = "693--698",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "34",
+  number        = "3",
+  author        = "G. Mellor and A. Blumberg",
+  year          = "2004",
+  month         = "mar",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/2517.1"
+}
+
+@article{         mellor.yamada_RG82,
+  title         = "Development of a turbulence closure model for geophysical
+                  fluid problems",
+  pages         = "851--875",
+  journal       = "Reviews of Geophysics",
+  volume        = "20",
+  number        = "4",
+  author        = "G. L. Mellor and T. Yamada",
+  year          = "1982",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "8755-1209",
+  doi           = "10.1029/rg020i004p00851"
+}
+
+@article{         merryfield.holloway.ea_JPO99,
+  title         = "A Global Ocean Model with Double-Diffusive Mixing",
+  pages         = "1124--1142",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "29",
+  number        = "6",
+  author        = "W. J. Merryfield and G. Holloway and A. E. Gargett",
+  year          = "1999",
+  month         = "jun",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1999)029<1124:agomwd>2.0.co;2"
+}
+
+@book{            mesinger.arakawa_bk76,
+  booktitle     = "Numerical methods used in atmospheric models",
+  series        = "GARP Publication",
+  volume        = "1",
+  number        = "17",
+  author        = "F. Mesinger and A. Arakawa",
+  year          = "1976",
+  month         = "aug",
+  url           = "https://www.researchgate.net/publication/234333726_Numerical_Methods_Used_In_Atmospheric_Models"
+}
+
+@article{         morel.berthon_LO89,
+  title         = "Surface pigments, algal biomass profiles, and potential
+                  production of the euphotic layer: Relationships
+                  reinvestigated in view of remote-sensing applications",
+  pages         = "1545--1562",
+  journal       = "Limnology and Oceanography",
+  volume        = "34",
+  number        = "8",
+  author        = "A. Morel and J.-F. Berthon",
+  year          = "1989",
+  month         = "dec",
+  publisher     = "Wiley",
+  issn          = "0024-3590",
+  doi           = "10.4319/lo.1989.34.8.1545"
+}
+
+@article{         morel.maritorena_JGR01,
+  title         = "Bio-optical properties of oceanic waters: {A} reappraisal",
+  pages         = "7163--7180",
+  journal       = "Journal of Geophysical Research",
+  volume        = "106",
+  number        = "C4",
+  author        = "A. Morel and S. Maritorena",
+  year          = "2001",
+  month         = "apr",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/2000jc000319"
+}
+
+@article{         morel_JGR88,
+  title         = "Optical modeling of the upper ocean in relation to its
+                  biogenous matter content (case {I} waters)",
+  pages         = "10749--10768",
+  journal       = "Journal of Geophysical Research",
+  volume        = "93",
+  number        = "C9",
+  author        = "A. Morel",
+  year          = "1988",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/jc093ic09p10749"
+}
+
+@article{         murray_JCP96,
+  title         = "Explicit Generation of Orthogonal Grids for Ocean Models",
+  pages         = "251--273",
+  journal       = "Journal of Computational Physics",
+  volume        = "126",
+  number        = "2",
+  author        = "R. J. Murray",
+  year          = "1996",
+  month         = "jul",
+  publisher     = "Elsevier BV",
+  issn          = "0021-9991",
+  doi           = "10.1006/jcph.1996.0136"
+}
+
+@article{         oey_OM06,
+  title         = "An {OGCM} with movable land-sea boundaries",
+  pages         = "176--195",
+  journal       = "Ocean Modelling",
+  volume        = "13",
+  number        = "2",
+  author        = "L.-Y. Oey",
+  year          = "2006",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2006.01.001"
+}
+
+@article{         osborn_JPO80,
+  title         = "Estimates of the local rate of vertical diffusion from
+                  dissipation measurements",
+  pages         = "83--89",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "10",
+  number        = "1",
+  author        = "T. R. Osborn",
+  year          = "1980",
+  month         = "jan",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1980)010<0083:eotlro>2.0.co;2"
+}
+
+@article{         pacanowski.gnanadesikan_MWR98,
+  title         = "Transient response in a z-level ocean model that resolves
+                  topography with partial-cells",
+  pages         = "3248--3270",
+  journal       = "Monthly Weather Review",
+  volume        = "126",
+  number        = "12",
+  author        = "R. C. Pacanowski and A. Gnanadesikan",
+  year          = "1998",
+  month         = "dec",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0493",
+  doi           = "10.1175/1520-0493(1998)126<3248:triazl>2.0.co;2"
+}
+
+@article{         pacanowski.philander_JPO81,
+  title         = "Parameterization of Vertical Mixing in Numerical Models of
+                  Tropical Oceans",
+  pages         = "1443--1451",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "11",
+  number        = "11",
+  author        = "R. C. Pacanowski and S. G. H. Philander",
+  year          = "1981",
+  month         = "nov",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1981)011<1443:povmin>2.0.co;2"
+}
+
+@article{         paulson.simpson_JPO77,
+  title         = "Irradiance Measurements in the Upper Ocean",
+  pages         = "952--956",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "7",
+  number        = "6",
+  author        = "C. A. Paulson and J. J. Simpson",
+  year          = "1977",
+  month         = "nov",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1977)007<0952:imituo>2.0.co;2"
+}
+
+@article{         penduff.le-sommer.ea_OS07,
+  title         = "Influence of numerical schemes on current-topography
+                  interactions in 1/4\deg global ocean simulations",
+  pages         = "509--524",
+  journal       = "Ocean Science",
+  volume        = "3",
+  number        = "4",
+  author        = "T. Penduff and J. {Le Sommer} and B. Barnier and A.-M.
+                  Tr\'{e}guier and J.-M. Molines and G. Madec",
+  year          = "2007",
+  month         = "dec",
+  publisher     = "Copernicus GmbH",
+  issn          = "1812-0792",
+  doi           = "10.5194/os-3-509-2007"
+}
+
+@article{         phillips_TAMS59,
+  title         = "Dissipative operators and hyperbolic systems of partial
+                  differential equations",
+  pages         = "193--254",
+  journal       = "Transactions of the American Mathematical Society",
+  volume        = "90",
+  number        = "2",
+  author        = "R. S. Phillips",
+  year          = "1959",
+  month         = "feb",
+  publisher     = "American Mathematical Society (AMS)",
+  issn          = "0002-9947",
+  doi           = "10.1090/s0002-9947-1959-0104919-1"
+}
+
+@article{         qiao.yuan.ea_OD10,
+  title         = "A three-dimensional surface wave–ocean circulation coupled 
+                  model and its initial testing",
+  pages         = "1339--1335",
+  journal       = "Ocean Dynamics",
+  volume        = "60",
+  number        = "5",
+  author        = "F. Qiao and Y. Yuan and T. Ezer and C. Xia and 
+                   Y. Yang and X. Lu and Z. Song ",
+  year          = "2010",
+  month         = "oct",
+  publisher     = "Springer-Verlag",
+  issn          = "1616-7341",
+  doi           = "10.1007/s10236-010-0326-y"
+}
+
+@article{         redi_JPO82,
+  title         = "Oceanic isopycnal mixing by coordinate rotation",
+  pages         = "1154--1158",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "12",
+  number        = "10",
+  author        = "M. H. Redi",
+  year          = "1982",
+  month         = "oct",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1982)012<1154:oimbcr>2.0.co;2"
+}
+
+@article{         reffray.guillaume.ea_GMD15,
+  title         = "Modelling turbulent vertical mixing sensitivity using
+                   a 1-D version of NEMO",
+  pages         = "69--86",
+  journal       = "Geoscientific Model Development",
+  volume        = "8",
+  number        = "1",
+  author        = "G. Reffray. and R. Bourdalle-Badie and C. Calone",
+  year          = "2015",
+  month         = "jan",
+  publisher     = "Copernicus GmbH",
+  issn          = "1991-9603",
+  doi           = "10.5194/gmd-8-69-2015"
+}
+
+@book{            richtmyer.morton_bk67,
+  pages         = "405",
+  booktitle     = "Difference methods for initial-value problems",
+  edition       = "2",
+  series        = "Interscience tracts in pure and applied mathematics",
+  author        = "R. D. Richtmyer and K. W. Morton",
+  year          = "1967",
+  publisher     = "Interscience",
+  issn          = "0074-994X",
+  isbn          = "9780470720400",
+  url           = "https://books.google.fr/books?id=nd1QAAAAMAAJ"
+}
+
+@article{         robert_JMSJ66,
+  title         = "The integration of a low order spectral form of the
+                  primitive meteorological equations",
+  pages         = "237--245",
+  journal       = "Journal of the Meteorological Society of Japan",
+  volume        = "44",
+  number        = "5",
+  author        = "A. J. Robert",
+  year          = "1966",
+  publisher     = "Meteorological Society of Japan",
+  issn          = "2186-9057",
+  doi           = "10.2151/jmsj1965.44.5\_237"
+}
+
+@article{         rodgers.aumont.ea_B14,
+  title         = "Strong sensitivity of Southern Ocean carbon uptake and
+                  nutrient cycling to wind stirring",
+  pages         = "4077--4098",
+  journal       = "Biogeosciences",
+  volume        = "11",
+  number        = "15",
+  author        = "K. B. Rodgers and O. Aumont and S. E. Mikaloff Fletcher
+                  and Y. Plancherel and L. Bopp and C. {de Boyer
+                  Mont\'{e}gut} and D. Iudicone and R. F. Keeling and G.
+                  Madec and R. Wanninkhof",
+  year          = "2014",
+  month         = "aug",
+  publisher     = "Copernicus GmbH",
+  issn          = "1726-4189",
+  doi           = "10.5194/bg-11-4077-2014"
+}
+
+@article{         rodi_JGR87,
+  title         = "Examples of calculation methods for flow and mixing in
+                  stratified fluids",
+  pages         = "5305--5328",
+  journal       = "Journal of Geophysical Research",
+  volume        = "92",
+  number        = "C5",
+  author        = "W. Rodi",
+  year          = "1987",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/jc092ic05p05305"
+}
+
+@article{         roquet.madec.ea_JPO15,
+  title         = "Defining a simplified yet ``realistic'' equation of state
+                  for seawater",
+  pages         = "2564--2579",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "45",
+  number        = "10",
+  author        = "F. Roquet and G. Madec and L. Brodeau and J. Nycander",
+  year          = "2015",
+  month         = "oct",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/jpo-d-15-0080.1"
+}
+
+@article{         roquet.madec.ea_OM15,
+  title         = "Accurate polynomial expressions for the density and
+                  specific volume of seawater using the {TEOS}-10 standard",
+  pages         = "29--43",
+  journal       = "Ocean Modelling",
+  volume        = "90",
+  author        = "F. Roquet and G. Madec and T. J. McDougall and P. M.
+                  Barker",
+  year          = "2015",
+  month         = "jun",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2015.04.002"
+}
+
+@article{         roullet.madec_JGR00,
+  title         = "Salt conservation, free surface, and varying levels: {A}
+                  new formulation for Ocean General Circulation Models",
+  pages         = "23927--23942",
+  journal       = "Journal of Geophysical Research",
+  volume        = "105",
+  number        = "C10",
+  author        = "G. Roullet and G. Madec",
+  year          = "2000",
+  month         = "oct",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/2000jc900089"
+}
+
+@article{         sarmiento.bryan_JGR82,
+  title         = "An ocean transport model for the North Atlantic",
+  pages         = "394--409",
+  journal       = "Journal of Geophysical Research",
+  volume        = "87",
+  number        = "C1",
+  author        = "J. L. Sarmiento and K. Bryan",
+  year          = "1982",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/jc087ic01p00394"
+}
+
+@article{         saunders_JAS67,
+  title         = "The temperature at the ocean-air interface",
+  pages         = "269--273",
+  journal       = "Journal of the Atmospheric Sciences",
+  volume        = "24",
+  number        = "3",
+  author        = "P. M. Saunders",
+  year          = "1967",
+  month         = "may",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0469",
+  doi           = "10.1175/1520-0469(1967)024<0269:ttatoa>2.0.co;2"
+}
+
+@article{         shchepetkin.mcwilliams_OM05,
+  title         = "The regional oceanic modeling system ({ROMS}): a
+                  split-explicit, free-surface,
+                  topography-following-coordinate oceanic model",
+  pages         = "347--404",
+  journal       = "Ocean Modelling",
+  volume        = "9",
+  number        = "4",
+  author        = "A. F. Shchepetkin and J. C. McWilliams",
+  year          = "2005",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2004.08.002"
+}
+
+@inbook{          shchepetkin.mcwilliams_ibk09,
+  title         = "Computational kernel algorithms for fine-scale,
+                  multiprocess, longtime oceanic simulations",
+  chapter       = "2",
+  pages         = "121--183",
+  booktitle     = "Computational Methods for the Atmosphere and the Oceans",
+  editor        = "R. M. Temam and J. J. Tribbia",
+  series        = "Handbook of Numerical Analysis",
+  volume        = "14",
+  author        = "A. F. Shchepetkin and J. C. McWilliams",
+  year          = "2009",
+  publisher     = "Elsevier",
+  issn          = "1570-8659",
+  isbn          = "9780444518934",
+  doi           = "10.1016/s1570-8659(08)01202-0"
+}
+
+@article{         shchepetkin_OM15,
+  title         = "An Adaptive, Courant-number-dependent implicit
+  		 scheme for vertical advection in oceanic modeling",
+  pages         = "38--69",
+  journal       = "Ocean Modelling",
+  volume        = "91",
+  author        = "A. F. Shchepetkin",
+  year          = "2015",
+  month         = "july",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2015.03.006"
+}
+
+@article{         siddorn.furner_OM13,
+  title         = "An analytical stretching function that combines the best
+                  attributes of geopotential and terrain-following vertical
+                  coordinates",
+  pages         = "1--13",
+  journal       = "Ocean Modelling",
+  volume        = "66",
+  author        = "J. R. Siddorn and R. Furner",
+  year          = "2013",
+  month         = "jun",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2013.02.001"
+}
+
+@article{         simmons.jayne.ea_OM04,
+  title         = "Tidally driven mixing in a numerical model of the ocean
+                  general circulation",
+  pages         = "245--263",
+  journal       = "Ocean Modelling",
+  volume        = "6",
+  number        = "3-4",
+  author        = "H. L. Simmons and S. R. Jayne and L. C. {St Laurent} and
+                  A. J. Weaver",
+  year          = "2004",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/s1463-5003(03)00011-8"
+}
+
+@article{         smagorinsky_MW63,
+  title         = "General circulation experiments with the primitive equations: I. The basic experiment ",
+  pages         = "99--164",
+  journal       = "Monthly Weather Review",
+  volume        = "91",
+  number        = "3",
+  author        = "J. Smagorinsky",
+  year          = "1963",
+  month         = "mar",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0493",
+  doi           = "10.1175/1520-0493(1963)091<0099:GCEWTP>2.3.CO;2"
+}
+
+@article{         song.haidvogel_JCP94,
+  title         = "A semi-implicit ocean circulation model using a
+                  generalized topography-following coordinate system",
+  pages         = "228--244",
+  journal       = "Journal of Computational Physics",
+  volume        = "115",
+  number        = "1",
+  author        = "Y. Song and D. Haidvogel",
+  year          = "1994",
+  month         = "nov",
+  publisher     = "Elsevier BV",
+  issn          = "0021-9991",
+  doi           = "10.1006/jcph.1994.1189"
+}
+
+@article{         song_MWR98,
+  title         = "A General Pressure Gradient Formulation for Ocean Models.
+                  Part {I}: Scheme Design and Diagnostic Analysis",
+  pages         = "3213--3230",
+  journal       = "Monthly Weather Review",
+  volume        = "126",
+  number        = "12",
+  author        = "Y. T. Song",
+  year          = "1998",
+  month         = "dec",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0493",
+  doi           = "10.1175/1520-0493(1998)126<3213:agpgff>2.0.co;2"
+}
+
+@article{         st-laurent.nash_DSR04,
+  title         = "An examination of the radiative and dissipative properties
+                  of deep ocean internal tides",
+  pages         = "3029--3042",
+  journal       = "Deep Sea Research",
+  volume        = "51",
+  number        = "25-26",
+  author        = "L. C. {St Laurent} and J. D. Nash",
+  year          = "2004",
+  month         = "dec",
+  publisher     = "Elsevier BV",
+  issn          = "0967-0645",
+  doi           = "10.1016/j.dsr2.2004.09.008"
+}
+
+@article{         st-laurent.simmons.ea_GRL02,
+  title         = "Estimating tidally driven mixing in the deep ocean",
+  pages         = "2101--2104",
+  journal       = "Geophysical Research Letters",
+  volume        = "29",
+  number        = "23",
+  author        = "L. C. {St Laurent} and H. L. Simmons and S. R. Jayne",
+  year          = "2002",
+  month         = "dec",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0094-8276",
+  doi           = "10.1029/2002gl015633"
+}
+
+@article{         stacey_JPO99,
+  title         = "Simulations of the wind-forced near-surface circulation in
+                  Knight Inlet: {A} parameterization of the roughness length",
+  pages         = "1363--1367",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "29",
+  number        = "6",
+  author        = "M. W. Stacey",
+  year          = "1999",
+  month         = "jun",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1999)029<1363:sotwfn>2.0.co;2"
+}
+
+@article{         steele.morley.ea_JC01,
+  title         = "{PHC}: {A} global ocean hydrography with a high-quality
+                  Arctic Ocean",
+  pages         = "2079--2087",
+  journal       = "Journal of Climate",
+  volume        = "14",
+  number        = "9",
+  author        = "M. Steele and R. Morley and W. Ermold",
+  year          = "2001",
+  month         = "may",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0442",
+  doi           = "10.1175/1520-0442(2001)014<2079:pagohw>2.0.co;2"
+}
+
+@article{         stein.stein_N92,
+  title         = "A model for the global variation in oceanic depth and heat
+                  flow with lithospheric age",
+  pages         = "123--129",
+  journal       = "Nature",
+  volume        = "359",
+  number        = "6391",
+  author        = "C. A. Stein and S. Stein",
+  year          = "1992",
+  month         = "sep",
+  publisher     = "Springer Nature",
+  issn          = "1476-4687",
+  doi           = "10.1038/359123a0"
+}
+
+@inbook{          stokes_ibk09,
+  title         = "On the theory of oscillatory waves",
+  chapter       = "12",
+  pages         = "197--229",
+  booktitle     = "Mathematical and Physical Papers",
+  series        = "Cambridge Library Collection - Mathematics",
+  volume        = "1",
+  author        = "G. G. Stokes",
+  year          = "2009",
+  publisher     = "Cambridge University Press",
+  isbn          = "9780511702242",
+  doi           = "10.1017/cbo9780511702242.013"
+}
+
+@article{         takaya.bidlot.ea_JGR10,
+  title         = "Refinements to a prognostic scheme of skin sea surface
+                  temperature",
+  pages         = "C06009",
+  journal       = "Journal of Geophysical Research",
+  volume        = "115",
+  number        = "C6",
+  author        = "Y. Takaya and J-R. Bidlot and A. C. M. Beljaars and P. A.
+                  E. M. Janssen",
+  year          = "2010",
+  month         = "jun",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/2009jc005985"
+}
+
+@article{         talagrand_JAS72,
+  title         = "On the damping of high-frequency motions in
+                  four-dimensional assimilation of meteorological data",
+  pages         = "1571--1574",
+  journal       = "Journal of the Atmospheric Sciences",
+  volume        = "29",
+  number        = "8",
+  author        = "O. Talagrand",
+  year          = "1972",
+  month         = "nov",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0469",
+  doi           = "10.1175/1520-0469(1972)029<1571:otdohf>2.0.co;2"
+}
+
+@article{         treguier.dukowicz.ea_JGR96,
+  title         = "Properties of nonuniform grids used in ocean general
+                  circulation models",
+  pages         = "20877--20881",
+  journal       = "Journal of Geophysical Research",
+  volume        = "101",
+  number        = "C9",
+  author        = "A.-M. Tr\'{e}guier and J. K. Dukowicz and K. Bryan",
+  year          = "1996",
+  month         = "sep",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/96jc01753"
+}
+
+@article{         treguier.held.ea_JPO97,
+  title         = "Parameterization of Quasigeostrophic Eddies in Primitive
+                  Equation Ocean Models",
+  pages         = "567--580",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "27",
+  number        = "4",
+  author        = "A. M. Tr\'{e}guier and I. M. Held and V. D. Larichev",
+  year          = "1997",
+  month         = "apr",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1997)027<0567:poqeip>2.0.co;2"
+}
+
+@article{         treguier_JGR92,
+  title         = "Kinetic energy analysis of an eddy resolving, primitive
+                  equation model of the North Atlantic",
+  pages         = "687--701",
+  journal       = "Journal of Geophysical Research",
+  volume        = "97",
+  number        = "C1",
+  author        = "A. M. Tr\'{e}guier",
+  year          = "1992",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/91jc02350"
+}
+
+@article{         tu.tsuang_GRL05,
+  title         = "Cool-skin simulation by a one-column ocean model",
+  pages         = "L22602",
+  journal       = "Geophysical Research Letters",
+  volume        = "32",
+  number        = "22",
+  author        = "C.-Y. Tu and B.-J. Tsuang",
+  year          = "2005",
+  month         = "nov",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0094-8276",
+  doi           = "10.1029/2005gl024252"
+}
+
+@article{         umlauf.burchard_CSR05,
+  title         = "Second-order turbulence closure models for geophysical
+                  boundary layers. {A} review of recent work",
+  pages         = "795--827",
+  journal       = "Continental Shelf Research",
+  volume        = "25",
+  number        = "7-8",
+  author        = "L. Umlauf and H. Burchard",
+  year          = "2005",
+  month         = "may",
+  publisher     = "Elsevier BV",
+  issn          = "0278-4343",
+  doi           = "10.1016/j.csr.2004.08.004"
+}
+
+@article{         umlauf.burchard_JMR03,
+  title         = "A generic length-scale equation for geophysical turbulence
+                  models",
+  pages         = "235--265",
+  journal       = "Journal of Marine Research",
+  volume        = "61",
+  number        = "2",
+  author        = "L. Umlauf and H. Burchard",
+  year          = "2003",
+  month         = "mar",
+  publisher     = "Journal of Marine Research/Yale",
+  issn          = "0022-2402",
+  doi           = "10.1357/002224003322005087"
+}
+
+@book{            vallis_bk06,
+  booktitle     = "Atmospheric and Oceanic Fluid Dynamics",
+  author        = "G. K. Vallis",
+  year          = "2006",
+  publisher     = "Cambridge University Press",
+  isbn          = "9780511790447",
+  doi           = "10.1017/cbo9780511790447"
+}
+
+@article{         vancoppenolle.fichefet.ea_OM09*a,
+  title         = "Simulating the mass balance and salinity of Arctic and
+                  Antarctic sea ice. 1. Model description and validation",
+  pages         = "33--53",
+  journal       = "Ocean Modelling",
+  volume        = "27",
+  number        = "1-2",
+  author        = "M. Vancoppenolle and T. Fichefet and H. Goosse and S.
+                  Bouillon and G. Madec and M. A. Morales Maqueda",
+  year          = "2009",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2008.10.005"
+}
+
+@article{         vancoppenolle.fichefet.ea_OM09*b,
+  title         = "Simulating the mass balance and salinity of Arctic and
+                  Antarctic sea ice. 2. Importance of sea ice salinity
+                  variations",
+  pages         = "54--69",
+  journal       = "Ocean Modelling",
+  volume        = "27",
+  number        = "1-2",
+  author        = "M. Vancoppenolle and T. Fichefet and H. Goosse",
+  year          = "2009",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2008.11.003"
+}
+
+@article{         warner.defne.ea_CG13,
+  title         = "A wetting and drying scheme for {ROMS}",
+  pages         = "54--61",
+  journal       = "Computers \& Geosciences",
+  volume        = "58",
+  author        = "J. C. Warner and Z. Defne and K. Haas and H. G. Arango",
+  year          = "2013",
+  month         = "aug",
+  publisher     = "Elsevier BV",
+  issn          = "0098-3004",
+  doi           = "10.1016/j.cageo.2013.05.004"
+}
+
+@article{         warner.sherwood.ea_OM05,
+  title         = "Performance of four turbulence closure models implemented
+                  using a generic length scale method",
+  pages         = "81--113",
+  journal       = "Ocean Modelling",
+  volume        = "8",
+  number        = "1-2",
+  author        = "J. C. Warner and C. R. Sherwood and H. G. Arango and R. P.
+                  Signell",
+  year          = "2005",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "1463-5003",
+  doi           = "10.1016/j.ocemod.2003.12.003"
+}
+
+@article{         weatherly_JMR84,
+  title         = "An estimate of bottom frictional dissipation by Gulf
+                  Stream fluctuations",
+  pages         = "289--301",
+  journal       = "Journal of Marine Research",
+  volume        = "42",
+  number        = "2",
+  author        = "G. L. Weatherly",
+  year          = "1984",
+  month         = "may",
+  publisher     = "Journal of Marine Research/Yale",
+  issn          = "1543-9542",
+  doi           = "10.1357/002224084788502729"
+}
+
+@article{         weaver.eby_JPO97,
+  title         = "On the numerical implementation of advection schemes for
+                  use in conjuction with various mixing parameterizations in
+                  the {GFDL} ocean model",
+  pages         = "369--377",
+  journal       = "Journal of Physical Oceanography",
+  volume        = "27",
+  number        = "2",
+  author        = "A. J. Weaver and M. Eby",
+  year          = "1997",
+  month         = "feb",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0485",
+  doi           = "10.1175/1520-0485(1997)027<0369:otnioa>2.0.co;2"
+}
+
+@article{         webb.de-cuevas.ea_JAOT98,
+  title         = "Improved Advection Schemes for Ocean Models",
+  pages         = "1171--1187",
+  journal       = "Journal of Atmospheric and Oceanic Technology",
+  volume        = "15",
+  number        = "5",
+  author        = "D. J. Webb and B. A. {de Cuevas} and C. S. Richmond",
+  year          = "1998",
+  month         = "oct",
+  publisher     = "American Meteorological Society",
+  issn          = "1520-0426",
+  doi           = "10.1175/1520-0426(1998)015<1171:iasfom>2.0.co;2"
+}
+
+@article{         white.hoskins.ea_QJRMS05,
+  title         = "Consistent approximate models of the global atmosphere: shallow, deep,
+                  hydrostatic, quasi-hydrostatic and non-hydrostatic",
+  pages         = "2081--2107",
+  journal       = "Quarterly Journal of the Royal Meteorological Society",
+  volume        = "131",
+  author        = "A. A. White and B. J. Hoskins and I. Roulstone and A. Staniforth",
+  year          = "2005",
+  doi           = "10.1256/qj.04.49"
+}
+
+@article{         white.adcroft.ea_JCP09,
+  title         = "High-order regridding-remapping schemes for continuous
+                  isopycnal and generalized coordinates in ocean models",
+  pages         = "8665--8692",
+  journal       = "Journal of Computational Physics",
+  volume        = "228",
+  number        = "23",
+  author        = "L. White and A. Adcroft and R. Hallberg",
+  year          = "2009",
+  month         = "dec",
+  publisher     = "Elsevier BV",
+  issn          = "0021-9991",
+  doi           = "10.1016/j.jcp.2009.08.016"
+}
+
+@article{         wilcox_AJ88,
+  title         = "Reassessment of the scale-determining equation for
+                  advanced turbulence models",
+  pages         = "1299--1310",
+  journal       = "AIAA Journal",
+  volume        = "26",
+  number        = "11",
+  author        = "D. C. Wilcox",
+  year          = "1988",
+  month         = "nov",
+  publisher     = "American Institute of Aeronautics and Astronautics (AIAA)",
+  issn          = "1533-385X",
+  doi           = "10.2514/3.10041"
+}
+
+@article{         willebrand.barnier.ea_PO01,
+  title         = "Circulation characteristics in three eddy-permitting
+                  models of the North Atlantic",
+  pages         = "123--161",
+  journal       = "Progress in Oceanography",
+  volume        = "48",
+  number        = "2-3",
+  author        = "J. Willebrand and B. Barnier and C. B{\"{o}}ning and C.
+                  Dieterich and P. D. Killworth and C. Le Provost and Y. Jia
+                  and J.-M. Molines and A. L. New",
+  year          = "2001",
+  month         = "jan",
+  publisher     = "Elsevier BV",
+  issn          = "0079-6611",
+  doi           = "10.1016/s0079-6611(01)00003-9"
+}
+
+@article{         zalesak_JCP79,
+  title         = "Fully multidimensional flux-corrected transport algorithms
+                  for fluids",
+  pages         = "335--362",
+  journal       = "Journal of Computational Physics",
+  volume        = "31",
+  number        = "3",
+  author        = "S. T. Zalesak",
+  year          = "1979",
+  month         = "jun",
+  publisher     = "Elsevier BV",
+  issn          = "0021-9991",
+  doi           = "10.1016/0021-9991(79)90051-2"
+}
+
+@article{         zhang.endoh_JGR92,
+  title         = "A free surface General Circulation Model for the tropical
+                  Pacific Ocean",
+  pages         = "11237--11255",
+  journal       = "Journal of Geophysical Research",
+  volume        = "97",
+  number        = "C7",
+  author        = "R.-H. Zhang and M. Endoh",
+  year          = "1992",
+  publisher     = "American Geophysical Union (AGU)",
+  issn          = "0148-0227",
+  doi           = "10.1029/92jc00911"
+}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/blocks.idx
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/blocks.idx	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/blocks.idx	(revision 11422)
@@ -0,0 +1,1 @@
+link ../build/blocks.idx
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/chapters.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/chapters.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/chapters.tex	(revision 11422)
@@ -0,0 +1,16 @@
+\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
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/definitions.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/definitions.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/definitions.tex	(revision 11422)
@@ -0,0 +1,15 @@
+%% Engine (folder name)
+\def \engine{NEMO}
+
+%% Title (variable name already use by 'titling' pkg)
+\def \heading{NEMO ocean engine}
+
+%% Authors (thanks will apply to the second author)
+\def \firstauthor{Gurvan Madec~}
+\def \secondauthor{NEMO System Team}
+
+%% IPSL publication number
+\def \ipslnum{27}
+
+%% Zenodo ID, i.e. doi:10.5281/zenodo.\([0-9]*\)
+\def \zid{1464816}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/foreword.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/foreword.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/foreword.tex	(revision 11422)
@@ -0,0 +1,22 @@
+% ================================================================
+% Foreword
+% ================================================================
+\chapter*{Foreword}
+
+The ocean engine of NEMO (Nucleus for European Modelling of the Ocean) is a primitive equation model adapted to
+regional and global ocean circulation problems.
+It is intended to be a flexible tool for studying the ocean and its interactions with the others components of
+the earth climate system over a wide range of space and time scales.
+
+Prognostic variables are the three-dimensional velocity field, a non-linear sea surface height,
+the \textit{Conservative} Temperature and the \textit{Absolute} Salinity.
+In the horizontal direction, the model uses a curvilinear orthogonal grid and in the vertical direction,
+a full or partial step $z$-coordinate, or $s$-coordinate, or a mixture of the two.
+The distribution of variables is a three-dimensional Arakawa C-type grid.
+Various physical choices are available to describe ocean physics, including TKE, and GLS vertical physics.
+
+Within NEMO, the ocean is interfaced with a sea-ice model (SI$^3$)
+ %or \href{https://github.com/CICE-Consortium/CICE}{CICE}),
+passive tracer and biogeochemical models (TOP-PISCES) and,
+via the \href{https://portal.enes.org/oasis}{OASIS} coupler, with several atmospheric general circulation models.
+It also support two-way grid embedding via the \href{http://agrif.imag.fr}{AGRIF} software.
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/keys.idx
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/keys.idx	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/keys.idx	(revision 11422)
@@ -0,0 +1,1 @@
+link ../build/keys.idx
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/modules.idx
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/modules.idx	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/modules.idx	(revision 11422)
@@ -0,0 +1,1 @@
+link ../build/modules.idx
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/parameters.idx
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/parameters.idx	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/parameters.idx	(revision 11422)
@@ -0,0 +1,1 @@
+link ../build/parameters.idx
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/subroutines.idx
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/subroutines.idx	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/subroutines.idx	(revision 11422)
@@ -0,0 +1,1 @@
+link ../build/subroutines.idx
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/thanks.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/thanks.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main/thanks.tex	(revision 11422)
@@ -0,0 +1,2 @@
+J\'{e}r\^{o}me Chanut,
+Silvia Mocavero
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_A.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_A.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_A.tex	(revision 11422)
@@ -10,4 +10,15 @@
 
 \minitoc
+
+\vfill
+\begin{figure}[b]
+\subsubsection*{Changes record}
+\begin{tabular}{l||l|m{0.65\linewidth}}
+    Release   & Author        & Modifications \\
+    {\em 4.0} & {\em Mike Bell} & {\em review}  \\
+    {\em 3.x} & {\em Gurvan Madec} & {\em original}  \\
+\end{tabular}
+\end{figure}
+
 
 \newpage
@@ -29,38 +40,85 @@
 \begin{equation}
   \label{apdx:A_s_slope}
-  \sigma_1 =\frac{1}{e_1 }\;\left. {\frac{\partial z}{\partial i}} \right|_s
+  \sigma_1 =\frac{1}{e_1 } \; \left. {\frac{\partial z}{\partial i}} \right|_s
   \quad \text{and} \quad
-  \sigma_2 =\frac{1}{e_2 }\;\left. {\frac{\partial z}{\partial j}} \right|_s
-\end{equation}
-
-The chain rule to establish the model equations in the curvilinear $s-$coordinate system is:
+  \sigma_2 =\frac{1}{e_2 } \; \left. {\frac{\partial z}{\partial j}} \right|_s .
+\end{equation}
+
+The model fields (e.g. pressure $p$) can be viewed as functions of $(i,j,z,t)$ (e.g. $p(i,j,z,t)$) or as
+functions of $(i,j,s,t)$ (e.g. $p(i,j,s,t)$). The symbol $\bullet$ will be used to represent any one of 
+these fields.  Any ``infinitesimal'' change in $\bullet$ can be written in two forms: 
+\begin{equation}
+  \label{apdx:A_s_infin_changes}
+  \begin{aligned}
+    & \delta \bullet =  \delta i \left. \frac{ \partial \bullet }{\partial i} \right|_{j,s,t} 
+                + \delta j \left. \frac{ \partial \bullet }{\partial i} \right|_{i,s,t} 
+                + \delta s \left. \frac{ \partial \bullet }{\partial s} \right|_{i,j,t} 
+                + \delta t \left. \frac{ \partial \bullet }{\partial t} \right|_{i,j,s} , \\
+    & \delta \bullet =  \delta i \left. \frac{ \partial \bullet }{\partial i} \right|_{j,z,t} 
+                + \delta j \left. \frac{ \partial \bullet }{\partial i} \right|_{i,z,t} 
+                + \delta z \left. \frac{ \partial \bullet }{\partial z} \right|_{i,j,t} 
+                + \delta t \left. \frac{ \partial \bullet }{\partial t} \right|_{i,j,z} .
+  \end{aligned}
+\end{equation}
+Using the first form and considering a change $\delta i$ with $j, z$ and $t$ held constant, shows that
+\begin{equation}
+  \label{apdx:A_s_chain_rule}
+      \left. {\frac{\partial \bullet }{\partial i}} \right|_{j,z,t}  =
+      \left. {\frac{\partial \bullet }{\partial i}} \right|_{j,s,t}
+    + \left. {\frac{\partial s       }{\partial i}} \right|_{j,z,t} \; 
+      \left. {\frac{\partial \bullet }{\partial s}} \right|_{i,j,t} .    
+\end{equation}
+The term $\left. \partial s / \partial i \right|_{j,z,t}$ can be related to the slope of constant $s$ surfaces, 
+(\autoref{apdx:A_s_slope}), by applying the second of (\autoref{apdx:A_s_infin_changes}) with $\bullet$ set to 
+$s$ and $j, t$ held constant
+\begin{equation}
+\label{apdx:a_delta_s}
+\delta s|_{j,t} = 
+         \delta i \left. \frac{ \partial s }{\partial i} \right|_{j,z,t} 
+       + \delta z \left. \frac{ \partial s }{\partial z} \right|_{i,j,t} .
+\end{equation}
+Choosing to look at a direction in the $(i,z)$ plane in which $\delta s = 0$ and using
+(\autoref{apdx:A_s_slope}) we obtain 
+\begin{equation}
+\left. \frac{ \partial s }{\partial i} \right|_{j,z,t} =  
+         -  \left. \frac{ \partial z }{\partial i} \right|_{j,s,t} \;
+            \left. \frac{ \partial s }{\partial z} \right|_{i,j,t}
+	 = - \frac{e_1 }{e_3 }\sigma_1  .
+\label{apdx:a_ds_di_z}
+\end{equation}
+Another identity, similar in form to (\autoref{apdx:a_ds_di_z}), can be derived
+by choosing $\bullet$ to be $s$ and using the second form of (\autoref{apdx:A_s_infin_changes}) to consider
+changes in which $i , j$ and $s$ are constant. This shows that
+\begin{equation}
+\label{apdx:A_w_in_s}
+w_s = \left. \frac{ \partial z }{\partial t} \right|_{i,j,s} =  
+- \left. \frac{ \partial z }{\partial s} \right|_{i,j,t}
+  \left. \frac{ \partial s }{\partial t} \right|_{i,j,z} 
+  = - e_3 \left. \frac{ \partial s }{\partial t} \right|_{i,j,z} . 
+\end{equation}
+
+In what follows, for brevity, indication of the constancy of the $i, j$ and $t$ indices is 
+usually omitted. Using the arguments outlined above one can show that the chain rules needed to establish 
+the model equations in the curvilinear $s-$coordinate system are:
 \begin{equation}
   \label{apdx:A_s_chain_rule}
   \begin{aligned}
     &\left. {\frac{\partial \bullet }{\partial t}} \right|_z  =
-    \left. {\frac{\partial \bullet }{\partial t}} \right|_s
-	 -\frac{\partial \bullet }{\partial s}\;\frac{\partial s}{\partial t} \\
+    \left. {\frac{\partial \bullet }{\partial t}} \right|_s 
+	 + \frac{\partial \bullet }{\partial s}\; \frac{\partial s}{\partial t} , \\
     &\left. {\frac{\partial \bullet }{\partial i}} \right|_z  =
     \left. {\frac{\partial \bullet }{\partial i}} \right|_s
-    -\frac{\partial \bullet }{\partial s}\;\frac{\partial s}{\partial i}=
-    \left. {\frac{\partial \bullet }{\partial i}} \right|_s
-    -\frac{e_1 }{e_3 }\sigma_1 \frac{\partial \bullet }{\partial s} \\
+    +\frac{\partial \bullet }{\partial s}\; \frac{\partial s}{\partial i}=
+    \left. {\frac{\partial \bullet }{\partial i}} \right|_s 
+    -\frac{e_1 }{e_3 }\sigma_1 \frac{\partial \bullet }{\partial s} , \\
     &\left. {\frac{\partial \bullet }{\partial j}} \right|_z  =
-    \left. {\frac{\partial \bullet }{\partial j}} \right|_s
-    - \frac{\partial \bullet }{\partial s}\;\frac{\partial s}{\partial j}=
-    \left. {\frac{\partial \bullet }{\partial j}} \right|_s
-    - \frac{e_2 }{e_3 }\sigma_2 \frac{\partial \bullet }{\partial s} \\
-    &\;\frac{\partial \bullet }{\partial z}  \;\; = \frac{1}{e_3 }\frac{\partial \bullet }{\partial s}
+    \left. {\frac{\partial \bullet }{\partial j}} \right|_s 
+    + \frac{\partial \bullet }{\partial s}\;\frac{\partial s}{\partial j}=
+    \left. {\frac{\partial \bullet }{\partial j}} \right|_s 
+    - \frac{e_2 }{e_3 }\sigma_2 \frac{\partial \bullet }{\partial s} , \\
+    &\;\frac{\partial \bullet }{\partial z}  \;\; = \frac{1}{e_3 }\frac{\partial \bullet }{\partial s} .
   \end{aligned}
 \end{equation}
 
-In particular applying the time derivative chain rule to $z$ provides the expression for $w_s$,
-the vertical velocity of the $s-$surfaces referenced to a fix z-coordinate:
-\begin{equation}
-  \label{apdx:A_w_in_s}
-  w_s   =  \left.   \frac{\partial z }{\partial t}   \right|_s
-  = \frac{\partial z}{\partial s} \; \frac{\partial s}{\partial t}
-  = e_3 \, \frac{\partial s}{\partial t}
-\end{equation}
 
 % ================================================================
@@ -79,5 +137,5 @@
     {
     \begin{array}{*{20}l}
-      \nabla \cdot {\rm {\bf U}}
+      \nabla \cdot {\mathrm {\mathbf U}}
       &= \frac{1}{e_1 \,e_2 }  \left[ \left. {\frac{\partial (e_2 \,u)}{\partial i}} \right|_z
         +\left. {\frac{\partial(e_1 \,v)}{\partial j}} \right|_z  \right]
@@ -115,5 +173,5 @@
       $, it becomes:}
     %
-      \nabla \cdot {\rm {\bf U}}
+      \nabla \cdot {\mathrm {\mathbf U}}
       & = \frac{1}{e_1 \,e_2 \,e_3 }  \left[
 		  \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s
@@ -131,43 +189,42 @@
 \end{subequations}
 
-Here, $w$ is the vertical velocity relative to the $z-$coordinate system.
-Introducing the dia-surface velocity component,
-$\omega $, defined as the volume flux across the moving $s$-surfaces per unit horizontal area:
+Here, $w$ is the vertical velocity relative to the $z-$coordinate system. 
+Using the first form of (\autoref{apdx:A_s_infin_changes}) 
+and the definitions (\autoref{apdx:A_s_slope}) and (\autoref{apdx:A_w_in_s}) for $\sigma_1$, $\sigma_2$ and  $w_s$,
+one can show that the vertical velocity, $w_p$ of a point
+moving with the horizontal velocity of the fluid along an $s$ surface is given by 
+\begin{equation}
+\label{apdx:A_w_p}
+\begin{split}
+w_p  = & \left. \frac{ \partial z }{\partial t} \right|_s
+     + \frac{u}{e_1} \left. \frac{ \partial z }{\partial i} \right|_s 
+     + \frac{v}{e_2} \left. \frac{ \partial z }{\partial j} \right|_s \\
+     = & w_s + u \sigma_1 + v \sigma_2 .
+\end{split}     
+\end{equation}
+ The vertical velocity across this surface is denoted by
 \begin{equation}
   \label{apdx:A_w_s}
-  \omega  = w - w_s - \sigma_1 \,u - \sigma_2 \,v    \\
-\end{equation}
-with $w_s$ given by \autoref{apdx:A_w_in_s},
-we obtain the expression for the divergence of the velocity in the curvilinear $s-$coordinate system:
-\begin{subequations}
-  \begin{align*}
-    {
-    \begin{array}{*{20}l}
-      \nabla \cdot {\rm {\bf U}}
-      &= \frac{1}{e_1 \,e_2 \,e_3 }    \left[
+  \omega  = w - w_p = w - ( w_s + \sigma_1 \,u + \sigma_2 \,v )  . 
+\end{equation}
+Hence 
+\begin{equation}
+\frac{1}{e_3 } \frac{\partial}{\partial s}   \left[  w -  u\;\sigma_1  - v\;\sigma_2  \right] = 
+\frac{1}{e_3 } \frac{\partial}{\partial s} \left[  \omega + w_s \right] = 
+   \frac{1}{e_3 } \left[ \frac{\partial \omega}{\partial s} 
+ + \left. \frac{ \partial }{\partial t} \right|_s \frac{\partial z}{\partial s} \right] = 
+   \frac{1}{e_3 } \frac{\partial \omega}{\partial s} + \frac{1}{e_3 } \left. \frac{ \partial e_3}{\partial t} . \right|_s 
+\end{equation}
+
+Using (\autoref{apdx:A_w_s}) in our expression for $\nabla \cdot {\mathrm {\mathbf U}}$ we obtain 
+our final expression for the divergence of the velocity in the curvilinear $s-$coordinate system:
+\begin{equation}
+      \nabla \cdot {\mathrm {\mathbf U}} =
+         \frac{1}{e_1 \,e_2 \,e_3 }    \left[
 		  \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s
         +\left.  \frac{\partial (e_1 \,e_3 \,v)}{\partial j} \right|_s        \right]
         + \frac{1}{e_3 } \frac{\partial \omega }{\partial s}
-        + \frac{1}{e_3 } \frac{\partial w_s       }{\partial s} \\ \\
-      &= \frac{1}{e_1 \,e_2 \,e_3 }    \left[
-		  \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s
-        +\left.  \frac{\partial (e_1 \,e_3 \,v)}{\partial j} \right|_s        \right]
-        + \frac{1}{e_3 } \frac{\partial \omega }{\partial s}
-        + \frac{1}{e_3 } \frac{\partial}{\partial s}  \left(  e_3 \; \frac{\partial s}{\partial t}   \right) \\ \\
-      &= \frac{1}{e_1 \,e_2 \,e_3 }    \left[
-		  \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s
-        +\left.  \frac{\partial (e_1 \,e_3 \,v)}{\partial j} \right|_s        \right]
-        + \frac{1}{e_3 } \frac{\partial \omega }{\partial s}
-        + \frac{\partial}{\partial s} \frac{\partial s}{\partial t}
-        + \frac{1}{e_3 } \frac{\partial s}{\partial t} \frac{\partial e_3}{\partial s} \\ \\
-      &= \frac{1}{e_1 \,e_2 \,e_3 }    \left[
-		  \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s
-        +\left.  \frac{\partial (e_1 \,e_3 \,v)}{\partial j} \right|_s        \right]
-        + \frac{1}{e_3 } \frac{\partial \omega }{\partial s}
-        + \frac{1}{e_3 } \frac{\partial e_3}{\partial t}
-    \end{array}
-        }
-  \end{align*}
-\end{subequations}
+        + \frac{1}{e_3 } \left. \frac{\partial e_3}{\partial t} \right|_s .
+\end{equation}
 
 As a result, the continuity equation \autoref{eq:PE_continuity} in the $s-$coordinates is:
@@ -178,7 +235,7 @@
     {\left. {\frac{\partial (e_2 \,e_3 \,u)}{\partial i}} \right|_s
       +  \left. {\frac{\partial (e_1 \,e_3 \,v)}{\partial j}} \right|_s } \right]
-  +\frac{1}{e_3 }\frac{\partial \omega }{\partial s} = 0
-\end{equation}
-A additional term has appeared that take into account
+  +\frac{1}{e_3 }\frac{\partial \omega }{\partial s} = 0 .
+\end{equation}
+An additional term has appeared that takes into account
 the contribution of the time variation of the vertical coordinate to the volume budget.
 
@@ -210,6 +267,5 @@
         + w \;\frac{\partial u}{\partial z} \\ \\
       &= \left. {\frac{\partial u }{\partial t}} \right|_z
-        - \left. \zeta \right|_z v
-        +  \frac{1}{e_1 \,e_2 }\left[ { \left.{ \frac{\partial (e_2 \,v)}{\partial i} }\right|_z
+        -  \frac{1}{e_1 \,e_2 }\left[ { \left.{ \frac{\partial (e_2 \,v)}{\partial i} }\right|_z
         -\left.{ \frac{\partial (e_1 \,u)}{\partial j} }\right|_z } \right] \; v
         +  \frac{1}{2e_1} \left.{ \frac{\partial (u^2+v^2)}{\partial i} } \right|_z
@@ -230,13 +286,13 @@
         } \\ \\
       &= \left. {\frac{\partial u }{\partial t}} \right|_z
-        + \left. \zeta \right|_s \;v
+        - \left. \zeta \right|_s \;v
         + \frac{1}{2\,e_1}\left. {\frac{\partial (u^2+v^2)}{\partial i}} \right|_s \\
       &\qquad \qquad \qquad \quad
         + \frac{w}{e_3 } \;\frac{\partial u}{\partial s}
-        - \left[   {\frac{\sigma_1 }{e_3 }\frac{\partial v}{\partial s}
+        + \left[   {\frac{\sigma_1 }{e_3 }\frac{\partial v}{\partial s}
         - \frac{\sigma_2 }{e_3 }\frac{\partial u}{\partial s}}   \right]\;v
         - \frac{\sigma_1 }{2e_3 }\frac{\partial (u^2+v^2)}{\partial s} \\ \\
       &= \left. {\frac{\partial u }{\partial t}} \right|_z
-        + \left. \zeta \right|_s \;v
+        - \left. \zeta \right|_s \;v
         + \frac{1}{2\,e_1}\left. {\frac{\partial (u^2+v^2)}{\partial i}} \right|_s \\
       &\qquad \qquad \qquad \quad
@@ -245,15 +301,15 @@
         - \sigma_1 u\frac{\partial u}{\partial s} - \sigma_1 v\frac{\partial v}{\partial s}} \right] \\ \\
       &= \left. {\frac{\partial u }{\partial t}} \right|_z
-        + \left. \zeta \right|_s \;v
+        - \left. \zeta \right|_s \;v
         + \frac{1}{2\,e_1}\left. {\frac{\partial (u^2+v^2)}{\partial i}} \right|_s
         + \frac{1}{e_3} \left[  w - \sigma_2 v - \sigma_1 u  \right]
-        \; \frac{\partial u}{\partial s}   \\
+        \; \frac{\partial u}{\partial s} .  \\
         %
-      \intertext{Introducing $\omega$, the dia-a-surface velocity given by (\autoref{apdx:A_w_s}) }
+      \intertext{Introducing $\omega$, the dia-s-surface velocity given by (\autoref{apdx:A_w_s}) }
       %
       &= \left. {\frac{\partial u }{\partial t}} \right|_z
-        + \left. \zeta \right|_s \;v
+        - \left. \zeta \right|_s \;v
         + \frac{1}{2\,e_1}\left. {\frac{\partial (u^2+v^2)}{\partial i}} \right|_s
-        + \frac{1}{e_3 } \left( \omega - w_s \right) \frac{\partial u}{\partial s}   \\
+        + \frac{1}{e_3 } \left( \omega + w_s \right) \frac{\partial u}{\partial s}   \\
     \end{array}
     }
@@ -266,11 +322,11 @@
   {
     \begin{array}{*{20}l}
-      w_s  \;\frac{\partial u}{\partial s}
-      = \frac{\partial s}{\partial t} \;  \frac{\partial u }{\partial s}
-      = \left. {\frac{\partial u }{\partial t}} \right|_s  - \left. {\frac{\partial u }{\partial t}} \right|_z \quad ,
+      \frac{w_s}{e_3}  \;\frac{\partial u}{\partial s}
+      = - \left. \frac{\partial s}{\partial t} \right|_z \;  \frac{\partial u }{\partial s}
+      = \left. {\frac{\partial u }{\partial t}} \right|_s  - \left. {\frac{\partial u }{\partial t}} \right|_z \ .
     \end{array}
   }
 \]
-leads to the $s-$coordinate formulation of the total $z-$coordinate time derivative,
+This leads to the $s-$coordinate formulation of the total $z-$coordinate time derivative,
 \ie the total $s-$coordinate time derivative :
 \begin{align}
@@ -278,7 +334,7 @@
   \left. \frac{D u}{D t} \right|_s
   = \left. {\frac{\partial u }{\partial t}} \right|_s
-  + \left. \zeta \right|_s \;v
+  - \left. \zeta \right|_s \;v
   + \frac{1}{2\,e_1}\left. {\frac{\partial (u^2+v^2)}{\partial i}} \right|_s
-  + \frac{1}{e_3 } \omega \;\frac{\partial u}{\partial s}
+  + \frac{1}{e_3 } \omega \;\frac{\partial u}{\partial s} . 
 \end{align}
 Therefore, the vector invariant form of the total time derivative has exactly the same mathematical form in
@@ -306,5 +362,5 @@
                                          + \frac{1}{e_3}        \frac{\partial \omega}{\partial s}                       \right] \\ \\
                                       &&- \frac{v}{e_1 e_2 }\left(    v	\;\frac{\partial e_2 }{\partial i}
-                                         -u	\;\frac{\partial e_1 }{\partial j} 	\right) \\
+                                         -u	\;\frac{\partial e_1 }{\partial j} 	\right) . \\
   \end{array}
   }
@@ -328,5 +384,5 @@
        -  e_2 u \;\frac{\partial e_3 }{\partial i}
        -  e_1 v \;\frac{\partial e_3 }{\partial j}   \right)
-       -\frac{1}{e_3}        \frac{\partial \omega}{\partial s}                       \right] \\ \\
+       + \frac{1}{e_3}        \frac{\partial \omega}{\partial s}                       \right] \\ \\
     && - \frac{v}{e_1 e_2 }\left( 	v  \;\frac{\partial e_2 }{\partial i}
        -u  \;\frac{\partial e_1 }{\partial j} 	\right) \\ \\
@@ -337,7 +393,7 @@
     && - \,u \left[  \frac{1}{e_1 e_2 e_3} \left(   \frac{\partial(e_2 e_3 \, u)}{\partial i}
        + \frac{\partial(e_1 e_3 \, v)}{\partial j}  \right)
-       -\frac{1}{e_3}        \frac{\partial \omega}{\partial s}                       \right]
+       + \frac{1}{e_3}        \frac{\partial \omega}{\partial s}                       \right]
        - \frac{v}{e_1 e_2 }\left( 	v   \;\frac{\partial e_2 }{\partial i}
-       -u   \;\frac{\partial e_1 }{\partial j} 	\right)                  \\
+       -u   \;\frac{\partial e_1 }{\partial j} 	\right)     .             \\
      %
     \intertext {Introducing a more compact form for the divergence of the momentum fluxes,
@@ -346,5 +402,5 @@
   %
     &= \left. {\frac{\partial u }{\partial t}} \right|_s
-    &+ \left.  \nabla \cdot \left(   {{\rm {\bf U}}\,u}   \right)    \right|_s
+    &+ \left.  \nabla \cdot \left(   {{\mathrm {\mathbf U}}\,u}   \right)    \right|_s
       + \,u \frac{1}{e_3 } \frac{\partial e_3}{\partial t}
       - \frac{v}{e_1 e_2 }\left(    v  \;\frac{\partial e_2 }{\partial i}
@@ -359,7 +415,7 @@
   \label{apdx:A_sco_Dt_flux}
   \left. \frac{D u}{D t} \right|_s   = \frac{1}{e_3}  \left. \frac{\partial ( e_3\,u)}{\partial t} \right|_s
-  + \left.  \nabla \cdot \left(   {{\rm {\bf U}}\,u}   \right)    \right|_s
+  + \left.  \nabla \cdot \left(   {{\mathrm {\mathbf U}}\,u}   \right)    \right|_s
   - \frac{v}{e_1 e_2 }\left(    v  \;\frac{\partial e_2 }{\partial i}
-    -u  \;\frac{\partial e_1 }{\partial j}            \right)
+    -u  \;\frac{\partial e_1 }{\partial j}            \right).
 \end{flalign}
 which is the total time derivative expressed in the curvilinear $s-$coordinate system.
@@ -377,9 +433,9 @@
     & =-\frac{1}{\rho_o e_1 }\left[ {\left. {\frac{\partial p}{\partial i}} \right|_s -\frac{e_1 }{e_3 }\sigma_1 \frac{\partial p}{\partial s}} \right] \\
     & =-\frac{1}{\rho_o \,e_1 }\left. {\frac{\partial p}{\partial i}} \right|_s +\frac{\sigma_1 }{\rho_o \,e_3 }\left( {-g\;\rho \;e_3 } \right) \\
-    &=-\frac{1}{\rho_o \,e_1 }\left. {\frac{\partial p}{\partial i}} \right|_s -\frac{g\;\rho }{\rho_o }\sigma_1
+    &=-\frac{1}{\rho_o \,e_1 }\left. {\frac{\partial p}{\partial i}} \right|_s -\frac{g\;\rho }{\rho_o }\sigma_1 .
   \end{split}
 \]
 Applying similar manipulation to the second component and
-replacing $\sigma_1$ and $\sigma_2$ by their expression \autoref{apdx:A_s_slope}, it comes:
+replacing $\sigma_1$ and $\sigma_2$ by their expression \autoref{apdx:A_s_slope}, it becomes:
 \begin{equation}
   \label{apdx:A_grad_p_1}
@@ -391,5 +447,5 @@
     -\frac{1}{\rho_o \, e_2 }\left. {\frac{\partial p}{\partial j}} \right|_z
     &=-\frac{1}{\rho_o \,e_2 } \left(    \left.               {\frac{\partial p}{\partial j}} \right|_s
-      + g\;\rho \;\left. {\frac{\partial z}{\partial j}} \right|_s   \right) \\
+      + g\;\rho \;\left. {\frac{\partial z}{\partial j}} \right|_s   \right) . \\
   \end{split}
 \end{equation}
@@ -399,5 +455,5 @@
 
 As in $z$-coordinate,
-the horizontal pressure gradient can be split in two parts following \citet{Marsaleix_al_OM08}.
+the horizontal pressure gradient can be split in two parts following \citet{marsaleix.auclair.ea_OM08}.
 Let defined a density anomaly, $d$, by $d=(\rho - \rho_o)/ \rho_o$,
 and a hydrostatic pressure anomaly, $p_h'$, by $p_h'= g \; \int_z^\eta d \; e_3 \; dk$.
@@ -405,6 +461,6 @@
 \[
   \begin{split}
-    p &= g\; \int_z^\eta \rho \; e_3 \; dk = g\; \int_z^\eta \left(  \rho_o \, d + 1 \right) \; e_3 \; dk   \\
-    &= g \, \rho_o \; \int_z^\eta d \; e_3 \; dk + g \, \int_z^\eta e_3 \; dk
+    p &= g\; \int_z^\eta \rho \; e_3 \; dk = g\; \int_z^\eta \rho_o \left( d + 1 \right) \; e_3 \; dk   \\
+    &= g \, \rho_o \; \int_z^\eta d \; e_3 \; dk + \rho_o g \, \int_z^\eta e_3 \; dk .
   \end{split}
 \]
@@ -412,13 +468,13 @@
 \begin{equation}
   \label{apdx:A_pressure}
-  p = \rho_o \; p_h' + g \, ( z + \eta )
+  p = \rho_o \; p_h' + \rho_o \, g \, ( \eta - z )
 \end{equation}
 and the hydrostatic pressure balance expressed in terms of $p_h'$ and $d$ is:
 \[
-  \frac{\partial p_h'}{\partial k} = - d \, g \, e_3
+  \frac{\partial p_h'}{\partial k} = - d \, g \, e_3 .
 \]
 
 Substituing \autoref{apdx:A_pressure} in \autoref{apdx:A_grad_p_1} and
-using the definition of the density anomaly it comes the expression in two parts:
+using the definition of the density anomaly it becomes an expression in two parts:
 \begin{equation}
   \label{apdx:A_grad_p_2}
@@ -426,9 +482,9 @@
     -\frac{1}{\rho_o \, e_1 } \left. {\frac{\partial p}{\partial i}} \right|_z
     &=-\frac{1}{e_1 } \left(     \left.              {\frac{\partial p_h'}{\partial i}} \right|_s
-      + g\; d  \;\left. {\frac{\partial z}{\partial i}} \right|_s    \right)  - \frac{g}{e_1 } \frac{\partial \eta}{\partial i} \\
+      + g\; d  \;\left. {\frac{\partial z}{\partial i}} \right|_s    \right)  - \frac{g}{e_1 } \frac{\partial \eta}{\partial i} ,  \\
              %
     -\frac{1}{\rho_o \, e_2 }\left. {\frac{\partial p}{\partial j}} \right|_z
     &=-\frac{1}{e_2 } \left(    \left.               {\frac{\partial p_h'}{\partial j}} \right|_s
-      + g\; d \;\left. {\frac{\partial z}{\partial j}} \right|_s   \right)  - \frac{g}{e_2 } \frac{\partial \eta}{\partial j}\\
+      + g\; d \;\left. {\frac{\partial z}{\partial j}} \right|_s   \right)  - \frac{g}{e_2 } \frac{\partial \eta}{\partial j} . \\
   \end{split}
 \end{equation}
@@ -463,5 +519,5 @@
     -   \frac{1}{e_1 } \left(    \frac{\partial p_h'}{\partial i} + g\; d  \; \frac{\partial z}{\partial i}    \right)
     -   \frac{g}{e_1 } \frac{\partial \eta}{\partial i}
-    +   D_u^{\vect{U}}  +   F_u^{\vect{U}}
+    +   D_u^{\vect{U}}  +   F_u^{\vect{U}} ,
   \end{multline}
   \begin{multline}
@@ -473,5 +529,5 @@
     -   \frac{1}{e_2 } \left(    \frac{\partial p_h'}{\partial j} + g\; d  \; \frac{\partial z}{\partial j}    \right)
     -   \frac{g}{e_2 } \frac{\partial \eta}{\partial j}
-    +  D_v^{\vect{U}}  +   F_v^{\vect{U}}
+    +  D_v^{\vect{U}}  +   F_v^{\vect{U}} .
   \end{multline}
 \end{subequations}
@@ -483,20 +539,20 @@
     \label{apdx:A_PE_dyn_flux_u}
     \frac{1}{e_3} \frac{\partial \left(  e_3\,u  \right) }{\partial t} =
-    \nabla \cdot \left(   {{\rm {\bf U}}\,u}   \right)
+    - \nabla \cdot \left(   {{\mathrm {\mathbf U}}\,u}   \right)
     +   \left\{ {f + \frac{1}{e_1 e_2 }\left(    v  \;\frac{\partial e_2 }{\partial i}
           -u  \;\frac{\partial e_1 }{\partial j}            \right)} \right\} \,v     \\
     -   \frac{1}{e_1 } \left(    \frac{\partial p_h'}{\partial i} + g\; d  \; \frac{\partial z}{\partial i}    \right)
     -   \frac{g}{e_1 } \frac{\partial \eta}{\partial i}
-    +   D_u^{\vect{U}}  +   F_u^{\vect{U}}
+    +   D_u^{\vect{U}}  +   F_u^{\vect{U}} ,
   \end{multline}
   \begin{multline}
     \label{apdx:A_dyn_flux_v}
     \frac{1}{e_3}\frac{\partial \left(  e_3\,v  \right) }{\partial t}=
-    -  \nabla \cdot \left(   {{\rm {\bf U}}\,v}   \right)
-    +   \left\{ {f + \frac{1}{e_1 e_2 }\left(    v  \;\frac{\partial e_2 }{\partial i}
+    -  \nabla \cdot \left(   {{\mathrm {\mathbf U}}\,v}   \right)
+    -   \left\{ {f + \frac{1}{e_1 e_2 }\left(    v  \;\frac{\partial e_2 }{\partial i}
           -u  \;\frac{\partial e_1 }{\partial j}            \right)} \right\} \,u     \\
     -   \frac{1}{e_2 } \left(    \frac{\partial p_h'}{\partial j} + g\; d  \; \frac{\partial z}{\partial j}    \right)
     -   \frac{g}{e_2 } \frac{\partial \eta}{\partial j}
-    +  D_v^{\vect{U}}  +   F_v^{\vect{U}}
+    +  D_v^{\vect{U}}  +   F_v^{\vect{U}} . 
   \end{multline}
 \end{subequations}
@@ -505,5 +561,5 @@
 \begin{equation}
   \label{apdx:A_dyn_zph}
-  \frac{\partial p_h'}{\partial k} = - d \, g \, e_3
+  \frac{\partial p_h'}{\partial k} = - d \, g \, e_3 .
 \end{equation}
 
@@ -531,9 +587,9 @@
   \left[           \frac{\partial }{\partial i} \left( {e_2 \,e_3 \;Tu} \right)
     +   \frac{\partial }{\partial j} \left( {e_1 \,e_3 \;Tv} \right)               \right]       \\
-  +  \frac{1}{e_3}  \frac{\partial }{\partial k} \left(                   Tw  \right)
+  -  \frac{1}{e_3}  \frac{\partial }{\partial k} \left(                   Tw  \right)
   +  D^{T} +F^{T}
 \end{multline}
 
-The expression for the advection term is a straight consequence of (A.4),
+The expression for the advection term is a straight consequence of (\autoref{apdx:A_sco_Continuity}),
 the expression of the 3D divergence in the $s-$coordinates established above. 
 
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_B.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_B.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_B.tex	(revision 11422)
@@ -53,14 +53,19 @@
   {
   \begin{array}{*{20}l}
-    D^T=& \frac{1}{e_1\,e_2\,e_3 }\;\left[ {\ \ \ \ e_2\,e_3\,A^{lT} \;\left.
-          {\frac{\partial }{\partial i}\left( {\frac{1}{e_1}\;\left. {\frac{\partial T}{\partial i}} \right|_s -\frac{\sigma_1 }{e_3 }\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right.  \\
-        &\qquad \quad \ \ \ +e_1\,e_3\,A^{lT} \;\left. {\frac{\partial }{\partial j}\left( {\frac{1}{e_2 }\;\left. {\frac{\partial T}{\partial j}} \right|_s -\frac{\sigma_2 }{e_3 }\;\frac{\partial T}{\partial s}} \right)} \right|_s \\
-        &\qquad \quad \ \ \ + e_1\,e_2\,A^{lT} \;\frac{\partial }{\partial s}\left( {-\frac{\sigma_1 }{e_1 }\;\left. {\frac{\partial T}{\partial i}} \right|_s -\frac{\sigma_2 }{e_2 }\;\left. {\frac{\partial T}{\partial j}} \right|_s } \right.
-          \left. {\left. {+\left( {\varepsilon +\sigma_1^2+\sigma_2 ^2} \right)\;\frac{1}{e_3 }\;\frac{\partial T}{\partial s}} \right)\;\;} \right]
+    D^T= \frac{1}{e_1\,e_2\,e_3 } & \left\{ \quad \quad \frac{\partial }{\partial i}  \left. \left[  e_2\,e_3 \, A^{lT}
+                               \left( \  \frac{1}{e_1}\; \left. \frac{\partial T}{\partial i} \right|_s 
+                                       -\frac{\sigma_1 }{e_3 } \; \frac{\partial T}{\partial s} \right) \right]  \right|_s  \right. \\
+        &  \quad \  +   \            \left.   \frac{\partial }{\partial j}  \left. \left[  e_1\,e_3 \, A^{lT}
+                               \left( \ \frac{1}{e_2 }\; \left. \frac{\partial T}{\partial j} \right|_s 
+                                       -\frac{\sigma_2 }{e_3 } \; \frac{\partial T}{\partial s} \right) \right]  \right|_s  \right. \\
+        &  \quad \  +   \           \left.  e_1\,e_2\, \frac{\partial }{\partial s}  \left[ A^{lT} \; \left( 
+	                  -\frac{\sigma_1 }{e_1 } \; \left. \frac{\partial T}{\partial i} \right|_s 
+	                  -\frac{\sigma_2 }{e_2 } \; \left. \frac{\partial T}{\partial j} \right|_s 
+                          +\left( \varepsilon +\sigma_1^2+\sigma_2 ^2 \right) \; \frac{1}{e_3 } \; \frac{\partial T}{\partial s} \right) \; \right] \;  \right\} .
   \end{array}
           }
 \end{align*}
 
-Equation \autoref{apdx:B2} is obtained from \autoref{apdx:B1} without any additional assumption.
+\autoref{apdx:B2} is obtained from \autoref{apdx:B1} without any additional assumption.
 Indeed, for the special case $k=z$ and thus $e_3 =1$,
 we introduce an arbitrary vertical coordinate $s = s (i,j,z)$ as in \autoref{apdx:A} and
@@ -90,14 +95,14 @@
   {
   \begin{array}{*{20}l}
-    \intertext{Noting that $\frac{1}{e_1} \left. \frac{\partial e_3 }{\partial i} \right|_s = \frac{\partial \sigma_1 }{\partial s}$, it becomes:}
+    \intertext{Noting that $\frac{1}{e_1} \left. \frac{\partial e_3 }{\partial i} \right|_s = \frac{\partial \sigma_1 }{\partial s}$, this becomes:}
     %
-    & =\frac{1}{e_1\,e_2\,e_3 }\left[ {\left. {\;\;\;\frac{\partial }{\partial i}\left( {\frac{e_2\,e_3 }{e_1}\,A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right)} \right|_s \left. -\, {e_3 \frac{\partial }{\partial i}\left( {\frac{e_2 \,\sigma_1 }{e_3 }A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right. \\
+    D^T & =\frac{1}{e_1\,e_2\,e_3 }\left[ {\left. {\;\;\;\frac{\partial }{\partial i}\left( {\frac{e_2\,e_3 }{e_1}\,A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right)} \right|_s \left. -\, {e_3 \frac{\partial }{\partial i}\left( {\frac{e_2 \,\sigma_1 }{e_3 }A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right. \\
     & \qquad \qquad \quad -e_2 A^{lT}\;\frac{\partial \sigma_1 }{\partial s}\left. {\frac{\partial T}{\partial i}} \right|_s -e_1 \,\sigma_1 \frac{\partial }{\partial s}\left( {\frac{e_2 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right) \\
-    & \qquad \qquad \quad\shoveright{ \left. { +e_1 \,\sigma_1 \frac{\partial }{\partial s}\left( {\frac{e_2 \,\sigma_1 }{e_3 }A^{lT}\;\frac{\partial T}{\partial s}} \right)+\frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 }{e_3 }A^{vT}\;\frac{\partial T}{\partial z}} \right)\;\;\;} \right] }\\
+    & \qquad \qquad \quad\shoveright{ \left. { +e_1 \,\sigma_1 \frac{\partial }{\partial s}\left( {\frac{e_2 \,\sigma_1 }{e_3 }A^{lT}\;\frac{\partial T}{\partial s}} \right)+\frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 }{e_3 }A^{vT}\;\frac{\partial T}{\partial s}} \right)\;\;\;} \right] }\\
     \\
     &=\frac{1}{e_1 \,e_2 \,e_3 } \left[ {\left. {\;\;\;\frac{\partial }{\partial i} \left( {\frac{e_2 \,e_3 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right)} \right|_s \left. {-\frac{\partial }{\partial i}\left( {e_2 \,\sigma_1 A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right. \\
     & \qquad \qquad \quad \left. {+\frac{e_2 \,\sigma_1 }{e_3}A^{lT}\;\frac{\partial T}{\partial s} \;\frac{\partial e_3 }{\partial i}}  \right|_s -e_2 A^{lT}\;\frac{\partial \sigma_1 }{\partial s}\left. {\frac{\partial T}{\partial i}} \right|_s \\
     & \qquad \qquad \quad-e_2 \,\sigma_1 \frac{\partial}{\partial s}\left( {A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right)+\frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 \,\sigma_1 ^2}{e_3 }A^{lT}\;\frac{\partial T}{\partial s}} \right) \\
-    & \qquad \qquad \quad\shoveright{ \left. {-\frac{\partial \left( {e_1 \,e_2 \,\sigma_1 } \right)}{\partial s} \left( {\frac{\sigma_1 }{e_3}A^{lT}\;\frac{\partial T}{\partial s}} \right) + \frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 }{e_3 }A^{vT}\;\frac{\partial T}{\partial s}} \right)\;\;\;} \right]}
+    & \qquad \qquad \quad\shoveright{ \left. {-\frac{\partial \left( {e_1 \,e_2 \,\sigma_1 } \right)}{\partial s} \left( {\frac{\sigma_1 }{e_3}A^{lT}\;\frac{\partial T}{\partial s}} \right) + \frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 }{e_3 }A^{vT}\;\frac{\partial T}{\partial s}} \right)\;\;\;} \right]} .
   \end{array}
       } \\
@@ -105,10 +110,10 @@
   \begin{array}{*{20}l}
     %
-    \intertext{using the same remark as just above, it becomes:}
+    \intertext{Using the same remark as just above, $D^T$ becomes:}
     %
-    &= \frac{1}{e_1 \,e_2 \,e_3 } \left[ {\left. {\;\;\;\frac{\partial }{\partial i} \left( {\frac{e_2 \,e_3 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s -e_2 \,\sigma_1 A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right.\;\;\; \\
+   D^T &= \frac{1}{e_1 \,e_2 \,e_3 } \left[ {\left. {\;\;\;\frac{\partial }{\partial i} \left( {\frac{e_2 \,e_3 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s -e_2 \,\sigma_1 A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right.\;\;\; \\
     & \qquad \qquad \quad+\frac{e_1 \,e_2 \,\sigma_1 }{e_3 }A^{lT}\;\frac{\partial T}{\partial s}\;\frac{\partial \sigma_1 }{\partial s} - \frac {\sigma_1 }{e_3} A^{lT} \;\frac{\partial \left( {e_1 \,e_2 \,\sigma_1 } \right)}{\partial s}\;\frac{\partial T}{\partial s} \\
     & \qquad \qquad \quad-e_2 \left( {A^{lT}\;\frac{\partial \sigma_1 }{\partial s}\left. {\frac{\partial T}{\partial i}} \right|_s +\frac{\partial }{\partial s}\left( {\sigma_1 A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right)-\frac{\partial \sigma_1 }{\partial s}\;A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right) \\
-    & \qquad \qquad \quad\shoveright{\left. {+\frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 \,\sigma_1 ^2}{e_3 }A^{lT}\;\frac{\partial T}{\partial s}+\frac{e_1 \,e_2}{e_3 }A^{vT}\;\frac{\partial T}{\partial s}} \right)\;\;\;} \right] }
+    & \qquad \qquad \quad\shoveright{\left. {+\frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 \,\sigma_1 ^2}{e_3 }A^{lT}\;\frac{\partial T}{\partial s}+\frac{e_1 \,e_2}{e_3 }A^{vT}\;\frac{\partial T}{\partial s}} \right)\;\;\;} \right] . }
   \end{array}
       } \\
@@ -117,11 +122,11 @@
     %
     \intertext{Since the horizontal scale factors do not depend on the vertical coordinate,
-    the last term of the first line and the first term of the last line cancel, while
-    the second line reduces to a single vertical derivative, so it becomes:}
+    the two terms on the second line cancel, while
+    the third line reduces to a single vertical derivative, so it becomes:}
   %
-    & =\frac{1}{e_1 \,e_2 \,e_3 }\left[ {\left. {\;\;\;\frac{\partial }{\partial i}\left( {\frac{e_2 \,e_3 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s -e_2 \,\sigma_1 \,A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right. \\
+    D^T & =\frac{1}{e_1 \,e_2 \,e_3 }\left[ {\left. {\;\;\;\frac{\partial }{\partial i}\left( {\frac{e_2 \,e_3 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s -e_2 \,\sigma_1 \,A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right. \\
     & \qquad \qquad \quad \shoveright{ \left. {+\frac{\partial }{\partial s}\left( {-e_2 \,\sigma_1 \,A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s +A^{lT}\frac{e_1 \,e_2 }{e_3 }\;\left( {\varepsilon +\sigma_1 ^2} \right)\frac{\partial T}{\partial s}} \right)\;\;\;} \right]} \\
     %
-    \intertext{in other words, the horizontal/vertical Laplacian operator in the ($i$,$s$) plane takes the following form:}
+    \intertext{In other words, the horizontal/vertical Laplacian operator in the ($i$,$s$) plane takes the following form:}
   \end{array}
   } \\
@@ -162,5 +167,5 @@
 the ($i$,$j$,$k$) curvilinear coordinate system in which
 the equations of the ocean circulation model are formulated,
-takes the following form \citep{Redi_JPO82}:
+takes the following form \citep{redi_JPO82}:
 
 \begin{equation}
@@ -169,11 +174,14 @@
   \left[ {{
         \begin{array}{*{20}c}
-          {1+a_1 ^2} \hfill & {-a_1 a_2 } \hfill & {-a_1 } \hfill \\
-          {-a_1 a_2 } \hfill & {1+a_2 ^2} \hfill & {-a_2 } \hfill \\
-          {-a_1 } \hfill & {-a_2 } \hfill & {\varepsilon +a_1 ^2+a_2 ^2} \hfill \\
+          {1+a_2 ^2 +\varepsilon a_1 ^2} \hfill & {-a_1 a_2 (1-\varepsilon)} \hfill & {-a_1 (1-\varepsilon) } \hfill \\
+          {-a_1 a_2 (1-\varepsilon) } \hfill & {1+a_1 ^2 +\varepsilon a_2 ^2} \hfill & {-a_2 (1-\varepsilon)} \hfill \\
+          {-a_1 (1-\varepsilon)} \hfill & {-a_2 (1-\varepsilon)} \hfill & {\varepsilon +a_1 ^2+a_2 ^2} \hfill \\
         \end{array}
       }} \right]
 \end{equation}
-where ($a_1$, $a_2$) are the isopycnal slopes in ($\textbf{i}$, $\textbf{j}$) directions, relative to geopotentials:
+where ($a_1$, $a_2$) are $(-1) \times$ the isopycnal slopes in
+($\textbf{i}$, $\textbf{j}$) directions, relative to geopotentials (or
+equivalently the slopes of the geopotential surfaces in the isopycnal
+coordinate framework):
 \[
   a_1 =\frac{e_3 }{e_1 }\left( {\frac{\partial \rho }{\partial i}} \right)\left( {\frac{\partial \rho }{\partial k}} \right)^{-1}
@@ -182,7 +190,9 @@
   \right)\left( {\frac{\partial \rho }{\partial k}} \right)^{-1}
 \]
-
-In practice, isopycnal slopes are generally less than $10^{-2}$ in the ocean,
-so $\textbf {A}_{\textbf I}$ can be simplified appreciably \citep{Cox1987}:
+and, as before, $\epsilon = A^{vT} / A^{lT}$.
+
+In practice, $\epsilon$ is small and isopycnal slopes are generally less than $10^{-2}$ in the ocean,
+so $\textbf {A}_{\textbf I}$ can be simplified appreciably \citep{cox_OM87}. Keeping leading order terms\footnote{Apart from the (1,0) 
+and (0,1) elements which are set to zero. See \citet{griffies_bk04}, section 14.1.4.1 for a discussion of this point.}:
 \begin{subequations}
   \label{apdx:B4}
@@ -226,6 +236,6 @@
 The isopycnal diffusion operator \autoref{apdx:B4},
 \autoref{apdx:B_ldfiso} conserves tracer quantity and dissipates its square.
-The demonstration of the first property is trivial as \autoref{apdx:B4} is the divergence of fluxes.
-Let us demonstrate the second one:
+As \autoref{apdx:B4} is the divergence of a flux, the demonstration of the first property is trivial, providing that the flux normal to the boundary is zero 
+(as it is when $A_h$ is zero at the boundary). Let us demonstrate the second one:
 \[
   \iiint\limits_D T\;\nabla .\left( {\textbf{A}}_{\textbf{I}} \nabla T \right)\,dv
@@ -236,5 +246,5 @@
   {
   \begin{array}{*{20}l}
-    \nabla T\;.\left( {{\rm {\bf A}}_{\rm {\bf I}} \nabla T}
+    \nabla T\;.\left( {{\mathrm {\mathbf A}}_{\mathrm {\mathbf I}} \nabla T}
     \right)&=A^{lT}\left[ {\left( {\frac{\partial T}{\partial i}} \right)^2-2a_1
              \frac{\partial T}{\partial i}\frac{\partial T}{\partial k}+\left(
@@ -246,5 +256,5 @@
              j}-a_2 \frac{\partial T}{\partial k}} \right)^2}
              +\varepsilon \left(\frac{\partial T}{\partial k}\right) ^2\right]      \\
-           & \geq 0
+           & \geq 0 . 
   \end{array}
              }
@@ -275,6 +285,7 @@
 \end{equation}
 
-where ($r_1$, $r_2$) are the isopycnal slopes in ($\textbf{i}$, $\textbf{j}$) directions,
-relative to $s$-coordinate surfaces:
+where ($r_1$, $r_2$) are $(-1)\times$ the isopycnal slopes in ($\textbf{i}$, $\textbf{j}$) directions,
+relative to $s$-coordinate surfaces (or equivalently the slopes of the
+$s$-coordinate surfaces in the isopycnal coordinate framework):
 \[
   r_1 =\frac{e_3 }{e_1 }\left( {\frac{\partial \rho }{\partial i}} \right)\left( {\frac{\partial \rho }{\partial s}} \right)^{-1}
@@ -284,5 +295,5 @@
 \]
 
-To prove \autoref{apdx:B5} by direct re-expression of \autoref{apdx:B_ldfiso} is straightforward, but laborious.
+To prove \autoref{apdx:B_ldfiso_s} by direct re-expression of \autoref{apdx:B_ldfiso} is straightforward, but laborious.
 An easier way is first to note (by reversing the derivation of \autoref{sec:B_2} from \autoref{sec:B_1} ) that
 the weak-slope operator may be \emph{exactly} reexpressed in non-orthogonal $i,j,\rho$-coordinates as
@@ -306,5 +317,5 @@
 the (rotated,orthogonal) isoneutral axes to the non-orthogonal $i,j,\rho$-coordinates.
 The further transformation into $i,j,s$-coordinates is exact, whatever the steepness of the $s$-surfaces,
-in the same way as the transformation of horizontal/vertical Laplacian diffusion in $z$-coordinates,
+in the same way as the transformation of horizontal/vertical Laplacian diffusion in $z$-coordinates in
 \autoref{sec:B_1} onto $s$-coordinates is exact, however steep the $s$-surfaces.
 
@@ -316,5 +327,5 @@
 \label{sec:B_3}
 
-The second order momentum diffusion operator (Laplacian) in the $z$-coordinate is found by
+The second order momentum diffusion operator (Laplacian) in $z$-coordinates is found by
 applying \autoref{eq:PE_lap_vector}, the expression for the Laplacian of a vector,
 to the horizontal velocity vector:
@@ -361,7 +372,7 @@
 \end{align*}
 Using \autoref{eq:PE_div}, the definition of the horizontal divergence,
-the third componant of the second vector is obviously zero and thus :
+the third component of the second vector is obviously zero and thus :
 \[
-  \Delta {\textbf{U}}_h = \nabla _h \left( \chi \right) - \nabla _h \times \left( \zeta \right) + \frac {1}{e_3 } \frac {\partial }{\partial k} \left( {\frac {1}{e_3 } \frac{\partial {\textbf{ U}}_h }{\partial k}} \right)
+  \Delta {\textbf{U}}_h = \nabla _h \left( \chi \right) - \nabla _h \times \left( \zeta \textbf{k} \right) + \frac {1}{e_3 } \frac {\partial }{\partial k} \left( {\frac {1}{e_3 } \frac{\partial {\textbf{ U}}_h }{\partial k}} \right) . 
 \]
 
@@ -379,5 +390,5 @@
   - \nabla _h \times \left( {A^{lm}\;\zeta \;{\textbf{k}}} \right)
   + \frac{1}{e_3 }\frac{\partial }{\partial k}\left( {\frac{A^{vm}\;}{e_3 }
-      \frac{\partial {\rm {\bf U}}_h }{\partial k}} \right) \\
+      \frac{\partial {\mathrm {\mathbf U}}_h }{\partial k}} \right) , \\
 \end{equation}
 that is, in expanded form:
@@ -386,9 +397,9 @@
   & = \frac{1}{e_1} \frac{\partial \left( {A^{lm}\chi   } \right)}{\partial i}
     -\frac{1}{e_2} \frac{\partial \left( {A^{lm}\zeta } \right)}{\partial j}
-    +\frac{1}{e_3} \frac{\partial u}{\partial k}      \\
+    +\frac{1}{e_3} \frac{\partial }{\partial k} \left( \frac{A^{vm}}{e_3} \frac{\partial u}{\partial k} \right)   ,   \\
   D^{\textbf{U}}_v
   & = \frac{1}{e_2 }\frac{\partial \left( {A^{lm}\chi   } \right)}{\partial j}
     +\frac{1}{e_1 }\frac{\partial \left( {A^{lm}\zeta } \right)}{\partial i}
-    +\frac{1}{e_3} \frac{\partial v}{\partial k}
+    +\frac{1}{e_3} \frac{\partial }{\partial k} \left( \frac{A^{vm}}{e_3} \frac{\partial v}{\partial k} \right) .
 \end{align*}
 
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_D.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_D.tex	(revision 10999)
+++ 	(revision )
@@ -1,207 +1,0 @@
-\documentclass[../main/NEMO_manual]{subfiles}
-
-\begin{document}
-% ================================================================
-% Appendix D Coding Rules
-% ================================================================
-\chapter{Coding Rules}
-\label{apdx:D}
-
-\minitoc
-
-\newpage
-
-A "model life" is more than ten years.
-Its software, composed of a few hundred modules, is used by many people who are scientists or students and
-do not necessarily know every aspect of computing very well.
-Moreover, a well thought-out program is easier to read and understand, less difficult to modify,
-produces fewer bugs and is easier to maintain.
-Therefore, it is essential that the model development follows some rules:
-
-- well planned and designed
-
-- well written
-
-- well documented (both on- and off-line)
-
-- maintainable
-
-- easily portable
-
-- flexible.
-
-To satisfy part of these aims, \NEMO is written with a coding standard which is close to the ECMWF rules,
-named DOCTOR \citep{Gibson_TR86}. 
-These rules present some advantages like:
-
-- to provide a well presented program
-
-- to use rules for variable names which allow recognition of their type
-(integer, real, parameter, local or shared variables, etc. ). 
-
-This facilitates both the understanding and the debugging of an algorithm.
-
-% ================================================================
-% The program structure
-% ================================================================
-\section{Program structure}
-\label{sec:D_structure}
-
-Each program begins with a set of headline comments containing:
-
-- the program title
-
-- the purpose of the routine
-
-- the method and algorithms used
-
-- the detail of input and output interfaces
-
-- the external routines and functions used (if they exist)
-
-- references (if they exist)
-
-- the author name(s), the date of creation and any updates.
-
-- Each program is split into several well separated sections and
-sub-sections with an underlined title and specific labelled statements.
-
-- A program has not more than 200 to 300 lines.
-
-A template of a module style can be found on the NEMO depository in the following file:
-NEMO/OPA\_SRC/module\_example.
-% ================================================================
-% Coding conventions
-% ================================================================
-\section{Coding conventions}
-\label{sec:D_coding}
-
-- Use of the universal language \fninety, and try to avoid obsolescent features like statement functions,
-do not use GO TO and EQUIVALENCE statements.
-
-- A continuation line begins with the character {\&} indented by three spaces compared to the previous line,
-while the previous line ended with the character {\&}.
-
-- All the variables must be declared.
-The code is usually compiled with implicit none.
- 
-- Never use continuation lines in the declaration of a variable.
-When searching a variable in the code through a \textit{grep} command, the declaration line will be found.
-
-- In the declaration of a PUBLIC variable, the comment part at the end of the line should start with
-the two characters "\verb?!:?".
-The following UNIX command, \\
-\verb?grep var_name *90 \ grep \!: ? \\
-will display the module name and the line where the var\_name declaration is.
-
-- Always use a three spaces indentation in DO loop, CASE, or IF-ELSEIF-ELSE-ENDIF statements.
-
-- use a space after a comma, except when it appears to separate the indices of an array.
-
-- use call to ctl\_stop routine instead of just a STOP.
-
-\newpage
-
-% ================================================================
-% Naming Conventions
-% ================================================================
-\section{Naming conventions}
-\label{sec:D_naming}
-
-The purpose of the naming conventions is to use prefix letters to classify model variables.
-These conventions allow the variable type to be easily known and rapidly identified.
-The naming conventions are summarised in the Table below:
-
-
-%--------------------------------------------------TABLE--------------------------------------------------
-\begin{table}[htbp]
-  \label{tab:VarName}
-  \begin{center}
-    \begin{tabular}{|p{45pt}|p{35pt}|p{45pt}|p{40pt}|p{40pt}|p{40pt}|p{40pt}|p{40pt}|}
-      \hline
-      Type \par / Status
-      & integer
-      & real
-      & logical
-      & character
-      & structure
-      & double \par precision
-      & complex \\
-      \hline
-      public  \par or  \par module variable
-      & \textbf{m n} \par \textit{but not} \par \textbf{nn\_ np\_}
-      & \textbf{a b e f g h o q r} \par \textbf{t} \textit{to} \textbf{x} \par but not \par \textbf{fs rn\_}
-      & \textbf{l} \par \textit{but not} \par \textbf{lp ld} \par \textbf{ ll ln\_}
-      & \textbf{c} \par \textit{but not} \par \textbf{cp cd} \par \textbf{cl cn\_}
-      & \textbf{s} \par \textit{but not} \par \textbf{sd sd} \par \textbf{sl sn\_}
-      & \textbf{d} \par \textit{but not} \par \textbf{dp dd} \par \textbf{dl dn\_}
-      & \textbf{y} \par \textit{but not} \par \textbf{yp yd} \par \textbf{yl yn} \\
-      \hline
-      dummy \par argument
-      & \textbf{k} \par \textit{but not} \par \textbf{kf}
-      & \textbf{p} \par \textit{but not} \par \textbf{pp pf}
-      & \textbf{ld}
-      & \textbf{cd}
-      & \textbf{sd}
-      & \textbf{dd}
-      & \textbf{yd} \\
-      \hline
-      local \par variable
-      & \textbf{i}
-      & \textbf{z}
-      & \textbf{ll}
-      & \textbf{cl}
-      & \textbf{sl}
-      & \textbf{dl}
-      & \textbf{yl} \\
-      \hline
-      loop \par control
-      & \textbf{j} \par \textit{but not} \par \textbf{jp} &&&&&& \\
-      \hline
-      parameter
-      & \textbf{jp np\_}
-      & \textbf{pp}
-      & \textbf{lp}
-      & \textbf{cp}
-      & \textbf{sp}
-      & \textbf{dp}
-      & \textbf{yp} \\
-      \hline
-      namelist
-      & \textbf{nn\_}
-      & \textbf{rn\_}
-      & \textbf{ln\_}
-      & \textbf{cn\_}
-      & \textbf{sn\_}
-      & \textbf{dn\_}
-      & \textbf{yn\_}
-      \\
-      \hline
-      CPP \par macro
-      & \textbf{kf}
-      & \textbf{fs} \par &&&&& \\
-      \hline
-    \end{tabular}
-    \label{tab:tab1}
-  \end{center}
-\end{table}
-%--------------------------------------------------------------------------------------------------------------
-
-N.B. Parameter here, in not only parameter in the \fortran acceptation,
-it is also used for code variables that are read in namelist and should never been modified during a simulation. 
-It is the case, for example, for the size of a domain (jpi,jpj,jpk).
-
-\newpage
-
-% ================================================================
-% The program structure
-% ================================================================
-%\section{Program structure}
-%\label{sec:Apdx_D_structure}
-
-%To be done....
-\biblio
-
-\pindex
-
-\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_DOMAINcfg.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_DOMAINcfg.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_DOMAINcfg.tex	(revision 11422)
@@ -0,0 +1,563 @@
+\documentclass[../main/NEMO_manual]{subfiles}
+
+\begin{document}
+% ================================================================
+% Appendix DOMAINcfg : A brief guide to the DOMAINcfg tool
+% ================================================================
+\chapter{A brief guide to the DOMAINcfg tool}
+\label{apdx:DOMAINcfg}
+
+\minitoc
+\vfill
+\begin{figure}[b]
+\subsubsection*{Changes record}
+\begin{tabular}{m{0.08\linewidth}||m{0.32\linewidth}|m{0.6\linewidth}}
+    Release   & Author(s)     & Modifications \\
+\hline
+    {\em 4.0} & {\em Andrew Coward} & {\em Created at v4.0 from materials removed from chap\_DOM that are still relevant to the \forcode{DOMAINcfg} tool and which illustrate and explain the choices to be made by the user when setting up new domains }  \\
+\end{tabular}
+\end{figure}
+
+\newpage
+
+This appendix briefly describes some of the options available in the
+\forcode{DOMAINcfg} tool mentioned in \autoref{chap:DOM}.
+
+This tool will evolve into an independent utility with its own documentation but its
+current manifestation is mostly a wrapper for \NEMO \forcode{DOM} modules more aligned to
+those in the previous versions of NEMO. These versions allowed the user to define some
+horizontal and vertical grids through additional namelist parameters. Explanations of
+these parameters are retained here for reference pending better documentation for
+\forcode{DOMAINcfg}. Please note that the namelist blocks named in this appendix refer to
+those read by \forcode{DOMAINcfg} via its own \forcode{namelist_ref} and
+\forcode{namelist_cfg} files. Although, due to their origins, these namelists share names
+with those used by NEMO, they are not interchangeable and should be considered independent
+of those described elsewhere in this manual.
+
+% -------------------------------------------------------------------------------------------------------------
+%        Choice of horizontal grid
+% -------------------------------------------------------------------------------------------------------------
+\section{Choice of horizontal grid}
+\label{sec:DOMCFG_hor}
+
+%--------------------------------------------namdom-------------------------------------------------------
+
+\nlst{namdom_domcfg} 
+%--------------------------------------------------------------------------------------------------------------
+
+The user has three options available in defining a horizontal grid, which involve the
+namelist variable \np{jphgr\_mesh} of the \ngn{namdom} (\forcode{DOMAINcfg} variant only)
+namelist.
+
+\begin{description}
+ \item[\np{jphgr\_mesh}=0]  The most general curvilinear orthogonal grids.
+  The coordinates and their first derivatives with respect to $i$ and $j$ are provided
+  in a input file (\ifile{coordinates}), read in \rou{hgr\_read} subroutine of the domhgr module.
+  This is now the only option available within \NEMO itself from v4.0 onwards.
+\item[\np{jphgr\_mesh}=1 to 5] A few simple analytical grids are provided (see below). 
+  For other analytical grids, the \textit{domhgr.f90} module (\forcode{DOMAINcfg} variant) must be 
+  modified by the user. In most cases, modifying the \mdl{usrdef\_hgr} module of \NEMO is
+  a better alternative since this is designed to allow simple analytical domains to be 
+  configured and used without the need for external data files.
+\end{description}
+
+There are two simple cases of geographical grids on the sphere. With 
+\np{jphgr\_mesh}=1, the grid (expressed in degrees) is regular in space, 
+with grid sizes specified by parameters \np{ppe1\_deg} and \np{ppe2\_deg}, 
+respectively. Such a geographical grid can be very anisotropic at high latitudes 
+because of the convergence of meridians (the zonal scale factors $e_1$ 
+become much smaller than the meridional scale factors $e_2$). The Mercator 
+grid (\np{jphgr\_mesh}=4) avoids this anisotropy by refining the meridional scale 
+factors in the same way as the zonal ones. In this case, meridional scale factors 
+and latitudes are calculated analytically using the formulae appropriate for 
+a Mercator projection, based on \np{ppe1\_deg} which is a reference grid spacing 
+at the equator (this applies even when the geographical equator is situated outside 
+the model domain). 
+
+In these two cases (\np{jphgr\_mesh}=1 or 4), the grid position is defined by the 
+longitude and latitude of the south-westernmost point (\np{ppglamt0} 
+and \np{ppgphi0}). Note that for the Mercator grid the user need only provide 
+an approximate starting latitude: the real latitude will be recalculated analytically, 
+in order to ensure that the equator corresponds to line passing through $t$- 
+and $u$-points.  
+
+Rectangular grids ignoring the spherical geometry are defined with 
+\np{jphgr\_mesh} = 2, 3, 5. The domain is either an $f$-plane (\np{jphgr\_mesh} = 2, 
+Coriolis factor is constant) or a beta-plane (\np{jphgr\_mesh} = 3, the Coriolis factor 
+is linear in the $j$-direction). The grid size is uniform in meter in each direction, 
+and given by the parameters \np{ppe1\_m} and \np{ppe2\_m} respectively. 
+The zonal grid coordinate (\textit{glam} arrays) is in kilometers, starting at zero 
+with the first $t$-point. The meridional coordinate (gphi. arrays) is in kilometers, 
+and the second $t$-point corresponds to coordinate $gphit=0$. The input 
+variable \np{ppglam0} is ignored. \np{ppgphi0} is used to set the reference 
+latitude for computation of the Coriolis parameter. In the case of the beta plane, 
+\np{ppgphi0} corresponds to the center of the domain. Finally, the special case 
+\np{jphgr\_mesh}=5 corresponds to a beta plane in a rotated domain for the 
+GYRE configuration, representing a classical mid-latitude double gyre system. 
+The rotation allows us to maximize the jet length relative to the gyre areas 
+(and the number of grid points). 
+
+% -------------------------------------------------------------------------------------------------------------
+%        vertical reference coordinate transformation
+% -------------------------------------------------------------------------------------------------------------
+\section{Vertical grid}
+\label{sec:DOMCFG_vert}
+\subsection{Vertical reference coordinate}
+\label{sec:DOMCFG_zref}
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!tb]
+  \begin{center}
+    \includegraphics[width=\textwidth]{Fig_zgr}
+    \caption{
+      \protect\label{fig:DOMCFG_zgr}
+      Default vertical mesh for ORCA2: 30 ocean levels (L30).
+      Vertical level functions for (a) T-point depth and (b) the associated scale factor for the $z$-coordinate case.
+    }
+  \end{center}
+\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+The reference coordinate transformation $z_0(k)$ defines the arrays $gdept_0$ and
+$gdepw_0$ for $t$- and $w$-points, respectively. See \autoref{sec:DOMCFG_sco} for the
+S-coordinate options.  As indicated on \autoref{fig:index_vert} \jp{jpk} is the number of
+$w$-levels.  $gdepw_0(1)$ is the ocean surface.  There are at most \jp{jpk}-1 $t$-points
+inside the ocean, the additional $t$-point at $jk = jpk$ is below the sea floor and is not
+used.  The vertical location of $w$- and $t$-levels is defined from the analytic
+expression of the depth $z_0(k)$ whose analytical derivative with respect to $k$ provides
+the vertical scale factors.  The user must provide the analytical expression of both $z_0$
+and its first derivative with respect to $k$.  This is done in routine \mdl{domzgr}
+through statement functions, using parameters provided in the \ngn{namdom} namelist
+(\forcode{DOMAINcfg} variant).
+
+It is possible to define a simple regular vertical grid by giving zero stretching
+(\np{ppacr}\forcode{ = 0}).  In that case, the parameters \jp{jpk} (number of $w$-levels)
+and \np{pphmax} (total ocean depth in meters) fully define the grid.
+
+For climate-related studies it is often desirable to concentrate the vertical resolution
+near the ocean surface.  The following function is proposed as a standard for a
+$z$-coordinate (with either full or partial steps):
+\begin{gather}
+  \label{eq:DOMCFG_zgr_ana_1}
+    z_0  (k) = h_{sur} - h_0 \; k - \; h_1 \; \log  \big[ \cosh ((k - h_{th}) / h_{cr}) \big] \\
+    e_3^0(k) = \lt|    - h_0      -    h_1 \; \tanh \big[        (k - h_{th}) / h_{cr}  \big] \rt|
+\end{gather}
+
+where $k = 1$ to \jp{jpk} for $w$-levels and $k = 1$ to $k = 1$ for $t-$levels.  Such an
+expression allows us to define a nearly uniform vertical location of levels at the ocean
+top and bottom with a smooth hyperbolic tangent transition in between (\autoref{fig:DOMCFG_zgr}).
+
+A double hyperbolic tangent version (\np{ldbletanh}\forcode{ = .true.}) is also available
+which permits finer control and is used, typically, to obtain a well resolved upper ocean
+without compromising on resolution at depth using a moderate number of levels.
+
+\begin{gather}
+  \label{eq:DOMCFG_zgr_ana_1b}
+    \begin{split}
+    z_0  (k) = h_{sur} - h_0 \; k &- \; h_1 \; \log  \big[ \cosh ((k - h_{th}) / h_{cr}) \big] \\
+                             \;   &- \; h2_1 \; \log  \big[ \cosh ((k - h2_{th}) / h2_{cr}) \big] 
+    \end{split}
+\end{gather}
+\begin{gather}
+    \begin{split}
+    e_3^0(k) = \big|    - h_0    &-   h_1 \; \tanh \big[       (k - h_{th})  / h_{cr}   \big]  \\
+                                 &-  h2_1 \; \tanh \big[       (k - h2_{th}) / h2_{cr}  \big] \big|
+    \end{split}
+\end{gather}
+
+If the ice shelf cavities are opened (\np{ln\_isfcav}\forcode{ = .true.}), the definition
+of $z_0$ is the same.  However, definition of $e_3^0$ at $t$- and $w$-points is
+respectively changed to:
+\begin{equation}
+  \label{eq:DOMCFG_zgr_ana_2}
+  \begin{split}
+    e_3^T(k) &= z_W (k + 1) - z_W (k    ) \\
+    e_3^W(k) &= z_T (k    ) - z_T (k - 1)
+  \end{split}
+\end{equation}
+
+This formulation decreases the self-generated circulation into the ice shelf cavity 
+(which can, in extreme case, leads to numerical instability). This is now the recommended formulation for all configurations using v4.0 onwards. The analytical derivation of thicknesses is maintained for backwards compatibility.
+
+The most used vertical grid for ORCA2 has $10~m$ ($500~m$) resolution in the surface
+(bottom) layers and a depth which varies from 0 at the sea surface to a minimum of
+$-5000~m$.  This leads to the following conditions:
+
+\begin{equation}
+  \label{eq:DOMCFG_zgr_coef}
+  \begin{array}{ll}
+    e_3 (1   + 1/2) =  10. & z(1  ) =     0. \\
+    e_3 (jpk - 1/2) = 500. & z(jpk) = -5000.
+  \end{array}
+\end{equation}
+
+With the choice of the stretching $h_{cr} = 3$ and the number of levels \jp{jpk}~$= 31$,
+the four coefficients $h_{sur}$, $h_0$, $h_1$, and $h_{th}$ in
+\autoref{eq:DOMCFG_zgr_ana_2} have been determined such that \autoref{eq:DOMCFG_zgr_coef}
+is satisfied, through an optimisation procedure using a bisection method.
+For the first standard ORCA2 vertical grid this led to the following values:
+$h_{sur} = 4762.96$, $h_0 = 255.58, h_1 = 245.5813$, and $h_{th} = 21.43336$.
+The resulting depths and scale factors as a function of the model levels are shown in
+\autoref{fig:DOMCFG_zgr} and given in \autoref{tab:DOMCFG_orca_zgr}.
+Those values correspond to the parameters \np{ppsur}, \np{ppa0}, \np{ppa1}, \np{ppkth} in \ngn{namcfg} namelist.
+
+Rather than entering parameters $h_{sur}$, $h_0$, and $h_1$ directly, it is possible to
+recalculate them.  In that case the user sets \np{ppsur}~$=$~\np{ppa0}~$=$~\np{ppa1}~$=
+999999$., in \ngn{namcfg} namelist, and specifies instead the four following parameters:
+\begin{itemize}
+\item
+  \np{ppacr}~$= h_{cr}$: stretching factor (nondimensional).
+  The larger \np{ppacr}, the smaller the stretching.
+  Values from $3$ to $10$ are usual.
+\item
+  \np{ppkth}~$= h_{th}$: is approximately the model level at which maximum stretching occurs
+  (nondimensional, usually of order 1/2 or 2/3 of \jp{jpk})
+\item
+  \np{ppdzmin}: minimum thickness for the top layer (in meters).
+\item
+  \np{pphmax}: total depth of the ocean (meters).
+\end{itemize}
+
+As an example, for the $45$ layers used in the DRAKKAR configuration those parameters are:
+\jp{jpk}~$= 46$, \np{ppacr}~$= 9$, \np{ppkth}~$= 23.563$, \np{ppdzmin}~$= 6~m$,
+\np{pphmax}~$= 5750~m$.
+
+%% %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{table}
+  \begin{center}
+    \begin{tabular}{c||r|r|r|r}
+      \hline
+      \textbf{LEVEL} & \textbf{gdept\_1d} & \textbf{gdepw\_1d} & \textbf{e3t\_1d } & \textbf{e3w\_1d} \\
+   \hline
+      1              & \textbf{     5.00} &               0.00 & \textbf{   10.00} &            10.00 \\
+      \hline
+      2              & \textbf{    15.00} &	            10.00 & \textbf{   10.00} &            10.00 \\
+      \hline
+      3              & \textbf{    25.00} &              20.00 & \textbf{   10.00} &            10.00 \\
+      \hline
+      4              & \textbf{    35.01} &	            30.00 & \textbf{   10.01} &            10.00 \\
+      \hline
+      5              & \textbf{    45.01} &              40.01 & \textbf{   10.01} &            10.01 \\
+      \hline
+      6              & \textbf{    55.03} &              50.02 & \textbf{   10.02} &            10.02 \\
+      \hline
+      7              & \textbf{    65.06} &              60.04 & \textbf{   10.04} &            10.03 \\
+      \hline
+      8              & \textbf{    75.13} &              70.09 & \textbf{   10.09} &            10.06 \\
+      \hline
+      9              & \textbf{    85.25} &              80.18 & \textbf{   10.17} &            10.12 \\
+      \hline
+      10             & \textbf{    95.49} &              90.35 & \textbf{   10.33} &            10.24 \\
+      \hline
+      11             & \textbf{   105.97} &             100.69 & \textbf{   10.65} &            10.47 \\
+      \hline
+      12             & \textbf{   116.90} &             111.36 & \textbf{   11.27} &            10.91 \\
+      \hline
+      13             & \textbf{   128.70} &             122.65 & \textbf{   12.47} &            11.77 \\
+      \hline
+      14             & \textbf{   142.20} &             135.16 & \textbf{   14.78} &            13.43 \\
+      \hline
+      15             & \textbf{   158.96} &             150.03 & \textbf{   19.23} &            16.65 \\
+      \hline
+      16             & \textbf{   181.96} &             169.42 & \textbf{   27.66} &            22.78 \\
+      \hline
+      17             & \textbf{   216.65} &             197.37 & \textbf{   43.26} &            34.30 \\
+      \hline
+      18             & \textbf{   272.48} &             241.13 & \textbf{   70.88} &            55.21 \\
+      \hline
+      19             & \textbf{   364.30} &             312.74 & \textbf{  116.11} &            90.99 \\
+      \hline
+      20             & \textbf{   511.53} &             429.72 & \textbf{  181.55} &           146.43 \\
+      \hline
+      21             & \textbf{   732.20} &             611.89 & \textbf{  261.03} &           220.35 \\
+      \hline
+      22             & \textbf{  1033.22} &             872.87 & \textbf{  339.39} &           301.42 \\
+      \hline
+      23             & \textbf{  1405.70} &            1211.59 & \textbf{  402.26} &           373.31 \\
+      \hline
+      24             & \textbf{  1830.89} &            1612.98 & \textbf{  444.87} &           426.00 \\
+      \hline
+      25             & \textbf{  2289.77} &            2057.13 & \textbf{  470.55} &           459.47 \\
+      \hline
+      26             & \textbf{  2768.24} &            2527.22 & \textbf{  484.95} &           478.83 \\
+      \hline
+      27             & \textbf{  3257.48} &            3011.90 & \textbf{  492.70} &           489.44 \\
+      \hline
+      28             & \textbf{  3752.44} &            3504.46 & \textbf{  496.78} &           495.07 \\
+      \hline
+      29             & \textbf{  4250.40} &            4001.16 & \textbf{  498.90} &           498.02 \\
+      \hline
+      30             & \textbf{  4749.91} &            4500.02 & \textbf{  500.00} &           499.54 \\
+      \hline
+      31             & \textbf{  5250.23} &            5000.00 & \textbf{  500.56} &           500.33 \\
+      \hline
+    \end{tabular}
+  \end{center}
+  \caption{
+    \protect\label{tab:DOMCFG_orca_zgr}
+    Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration as computed from
+    \autoref{eq:DOMCFG_zgr_ana_2} using the coefficients given in \autoref{eq:DOMCFG_zgr_coef}
+  }
+\end{table}
+%%%YY
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+%% % -------------------------------------------------------------------------------------------------------------
+%% %        Meter Bathymetry
+%% % -------------------------------------------------------------------------------------------------------------
+\subsection{Model bathymetry}
+\label{subsec:DOMCFG_bathy}
+
+Three options are possible for defining the bathymetry, according to the namelist variable
+\np{nn\_bathy} (found in \ngn{namdom} namelist (\forcode{DOMAINCFG} variant) ):
+\begin{description}
+\item[\np{nn\_bathy}\forcode{ = 0}]:
+  a flat-bottom domain is defined.
+  The total depth $z_w (jpk)$ is given by the coordinate transformation.
+  The domain can either be a closed basin or a periodic channel depending on the parameter \np{jperio}.
+\item[\np{nn\_bathy}\forcode{ = -1}]:
+  a domain with a bump of topography one third of the domain width at the central latitude.
+  This is meant for the "EEL-R5" configuration, a periodic or open boundary channel with a seamount.
+\item[\np{nn\_bathy}\forcode{ = 1}]:
+  read a bathymetry and ice shelf draft (if needed).
+  The \ifile{bathy\_meter} file (Netcdf format) provides the ocean depth (positive, in meters) at
+  each grid point of the model grid.
+  The bathymetry is usually built by interpolating a standard bathymetry product (\eg ETOPO2) onto
+  the horizontal ocean mesh.
+  Defining the bathymetry also defines the coastline: where the bathymetry is zero,
+  no wet levels are defined (all levels are masked).
+
+  The \ifile{isfdraft\_meter} file (Netcdf format) provides the ice shelf draft (positive, in meters) at
+  each grid point of the model grid.
+  This file is only needed if \np{ln\_isfcav}\forcode{ = .true.}.
+  Defining the ice shelf draft will also define the ice shelf edge and the grounding line position.
+\end{description}
+
+\subsection{Choice of vertical grid}
+\label{sec:DOMCFG_vgrd}
+
+After reading the bathymetry, the algorithm for vertical grid definition differs between the different options:
+\begin{description}
+\item[\forcode{ln_zco = .true.}]
+  set a reference coordinate transformation $z_0(k)$, and set $z(i,j,k,t) = z_0(k)$ where $z_0(k)$ is the closest match to the depth at $(i,j)$.
+\item[\forcode{ln_zps = .true.}]
+  set a reference coordinate transformation $z_0(k)$, and calculate the thickness of the deepest level at
+  each $(i,j)$ point using the bathymetry, to obtain the final three-dimensional depth and scale factor arrays.
+\item[\forcode{ln_sco = .true.}]
+  smooth the bathymetry to fulfill the hydrostatic consistency criteria and
+  set the three-dimensional transformation.
+\item[\forcode{s-z and s-zps}]
+  smooth the bathymetry to fulfill the hydrostatic consistency criteria and
+  set the three-dimensional transformation $z(i,j,k)$,
+  and possibly introduce masking of extra land points to better fit the original bathymetry file.
+\end{description}
+%%%
+ 
+% -------------------------------------------------------------------------------------------------------------
+%        z-coordinate with constant thickness
+% -------------------------------------------------------------------------------------------------------------
+\subsubsection[$Z$-coordinate with uniform thickness levels (\forcode{ln_zco = .true.})]
+{$Z$-coordinate with uniform thickness levels (\protect\np{ln\_zco}\forcode{ = .true.})}
+\label{subsec:DOMCFG_zco}
+
+With this option the model topography can be fully described by the reference vertical
+coordinate and a 2D integer field giving the number of wet levels at each location
+(\forcode{bathy_level}). The resulting match to the real topography is likely to be poor
+though (especially with thick, deep levels) and slopes poorly represented. This option is
+rarely used in modern simulations but it can be useful for testing purposes.
+
+% -------------------------------------------------------------------------------------------------------------
+%        z-coordinate with partial step
+% -------------------------------------------------------------------------------------------------------------
+\subsubsection[$Z$-coordinate with partial step (\forcode{ln_zps = .true.})]
+{$Z$-coordinate with partial step (\protect\np{ln\_zps}\forcode{ = .true.})}
+\label{subsec:DOMCFG_zps}
+
+In $z$-coordinate partial step, the depths of the model levels are defined by the
+reference analytical function $z_0(k)$ as described in \autoref{sec:DOMCFG_zref},
+\textit{except} in the bottom layer.  The thickness of the bottom layer is allowed to vary
+as a function of geographical location $(\lambda,\varphi)$ to allow a better
+representation of the bathymetry, especially in the case of small slopes (where the
+bathymetry varies by less than one level thickness from one grid point to the next).  The
+reference layer thicknesses $e_{3t}^0$ have been defined in the absence of bathymetry.
+With partial steps, layers from 1 to \jp{jpk}-2 can have a thickness smaller than
+$e_{3t}(jk)$.
+
+The model deepest layer (\jp{jpk}-1) is allowed to have either a smaller or larger
+thickness than $e_{3t}(jpk)$: the maximum thickness allowed is $2*e_{3t}(jpk - 1)$.
+
+This has to be kept in mind when specifying values in \ngn{namdom} namelist
+(\forcode{DOMMAINCFG} variant), such as the maximum depth \np{pphmax} in partial steps.
+
+For example, with \np{pphmax}~$= 5750~m$ for the DRAKKAR 45 layer grid, the maximum ocean
+depth allowed is actually $6000~m$ (the default thickness $e_{3t}(jpk - 1)$ being
+$250~m$).  Two variables in the namdom namelist are used to define the partial step
+vertical grid.  The mimimum water thickness (in meters) allowed for a cell partially
+filled with bathymetry at level jk is the minimum of \np{rn\_e3zps\_min} (thickness in
+meters, usually $20~m$) or $e_{3t}(jk)*$\np{rn\_e3zps\_rat} (a fraction, usually 10\%, of
+the default thickness $e_{3t}(jk)$).
+
+% -------------------------------------------------------------------------------------------------------------
+%        s-coordinate
+% -------------------------------------------------------------------------------------------------------------
+\subsubsection[$S$-coordinate (\forcode{ln_sco = .true.})]
+{$S$-coordinate (\protect\np{ln\_sco}\forcode{ = .true.})}
+\label{sec:DOMCFG_sco}
+%------------------------------------------nam_zgr_sco---------------------------------------------------
+%
+\nlst{namzgr_sco_domcfg} 
+%--------------------------------------------------------------------------------------------------------------
+Options are defined in \ngn{namzgr\_sco} (\forcode{DOMAINcfg} only).
+In $s$-coordinate (\np{ln\_sco}\forcode{ = .true.}), the depth and thickness of the model levels are defined from
+the product of a depth field and either a stretching function or its derivative, respectively:
+
+\begin{align*}
+  % \label{eq:DOMCFG_sco_ana}
+  z(k)   &= h(i,j) \; z_0 (k) \\
+  e_3(k) &= h(i,j) \; z_0'(k)
+\end{align*}
+
+where $h$ is the depth of the last $w$-level ($z_0(k)$) defined at the $t$-point location in the horizontal and
+$z_0(k)$ is a function which varies from $0$ at the sea surface to $1$ at the ocean bottom.
+The depth field $h$ is not necessary the ocean depth,
+since a mixed step-like and bottom-following representation of the topography can be used
+(\autoref{fig:z_zps_s_sps}) or an envelop bathymetry can be defined (\autoref{fig:z_zps_s_sps}).
+The namelist parameter \np{rn\_rmax} determines the slope at which
+the terrain-following coordinate intersects the sea bed and becomes a pseudo z-coordinate.
+The coordinate can also be hybridised by specifying \np{rn\_sbot\_min} and \np{rn\_sbot\_max} as
+the minimum and maximum depths at which the terrain-following vertical coordinate is calculated.
+
+Options for stretching the coordinate are provided as examples,
+but care must be taken to ensure that the vertical stretch used is appropriate for the application.
+
+The original default NEMO s-coordinate stretching is available if neither of the other options are specified as true
+(\np{ln\_s\_SH94}\forcode{ = .false.} and \np{ln\_s\_SF12}\forcode{ = .false.}).
+This uses a depth independent $\tanh$ function for the stretching \citep{madec.delecluse.ea_JPO96}:
+
+\[
+  z = s_{min} + C (s) (H - s_{min})
+  % \label{eq:SH94_1}
+\]
+
+where $s_{min}$ is the depth at which the $s$-coordinate stretching starts and
+allows a $z$-coordinate to placed on top of the stretched coordinate,
+and $z$ is the depth (negative down from the asea surface).
+\begin{gather*}
+  s = - \frac{k}{n - 1} \quad \text{and} \quad 0 \leq k \leq n - 1
+  % \label{eq:DOMCFG_s}
+ \\
+ \label{eq:DOMCFG_sco_function}
+  C(s) = \frac{[\tanh(\theta \, (s + b)) - \tanh(\theta \, b)]}{2 \; \sinh(\theta)}
+\end{gather*}
+
+A stretching function,
+modified from the commonly used \citet{song.haidvogel_JCP94} stretching (\np{ln\_s\_SH94}\forcode{ = .true.}),
+is also available and is more commonly used for shelf seas modelling:
+
+\[
+  C(s) =   (1 - b) \frac{\sinh(\theta s)}{\sinh(\theta)}
+         + b       \frac{\tanh \lt[ \theta \lt(s + \frac{1}{2} \rt) \rt] -   \tanh \lt( \frac{\theta}{2} \rt)}
+                        {                                                  2 \tanh \lt( \frac{\theta}{2} \rt)}
+ \label{eq:SH94_2}
+\]
+
+%% %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht]
+  \begin{center}
+    \includegraphics[width=\textwidth]{Fig_sco_function}
+    \caption{
+      \protect\label{fig:sco_function}
+      Examples of the stretching function applied to a seamount;
+      from left to right: surface, surface and bottom, and bottom intensified resolutions
+    }
+  \end{center}
+\end{figure}
+%% %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+where $H_c$ is the critical depth (\np{rn\_hc}) at which the coordinate transitions from pure $\sigma$ to
+the stretched coordinate, and $\theta$ (\np{rn\_theta}) and $b$ (\np{rn\_bb}) are the surface and
+bottom control parameters such that $0 \leqslant \theta \leqslant 20$, and $0 \leqslant b \leqslant 1$.
+$b$ has been designed to allow surface and/or bottom increase of the vertical resolution
+(\autoref{fig:sco_function}).
+
+Another example has been provided at version 3.5 (\np{ln\_s\_SF12}) that allows a fixed surface resolution in
+an analytical terrain-following stretching \citet{siddorn.furner_OM13}.
+In this case the a stretching function $\gamma$ is defined such that:
+
+\begin{equation}
+  z = - \gamma h \quad \text{with} \quad 0 \leq \gamma \leq 1
+  % \label{eq:z}
+\end{equation}
+
+The function is defined with respect to $\sigma$, the unstretched terrain-following coordinate:
+
+\begin{gather*}
+  % \label{eq:DOMCFG_gamma_deriv}
+  \gamma =   A \lt( \sigma   - \frac{1}{2} (\sigma^2     + f (\sigma)) \rt)
+           + B \lt( \sigma^3 - f           (\sigma) \rt) + f (\sigma)       \\
+  \intertext{Where:}
+ \label{eq:DOMCFG_gamma}
+  f(\sigma) = (\alpha + 2) \sigma^{\alpha + 1} - (\alpha + 1) \sigma^{\alpha + 2}
+  \quad \text{and} \quad \sigma = \frac{k}{n - 1}
+\end{gather*}
+
+This gives an analytical stretching of $\sigma$ that is solvable in $A$ and $B$ as a function of
+the user prescribed stretching parameter $\alpha$ (\np{rn\_alpha}) that stretches towards
+the surface ($\alpha > 1.0$) or the bottom ($\alpha < 1.0$) and
+user prescribed surface (\np{rn\_zs}) and bottom depths.
+The bottom cell depth in this example is given as a function of water depth:
+
+\[
+  % \label{eq:DOMCFG_zb}
+  Z_b = h a + b
+\]
+
+where the namelist parameters \np{rn\_zb\_a} and \np{rn\_zb\_b} are $a$ and $b$ respectively.
+
+%% %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht]
+  \includegraphics[width=\textwidth]{Fig_DOM_compare_coordinates_surface}
+  \caption{
+    A comparison of the \citet{song.haidvogel_JCP94} $S$-coordinate (solid lines),
+    a 50 level $Z$-coordinate (contoured surfaces) and
+    the \citet{siddorn.furner_OM13} $S$-coordinate (dashed lines) in the surface $100~m$ for
+    a idealised bathymetry that goes from $50~m$ to $5500~m$ depth.
+    For clarity every third coordinate surface is shown.
+  }
+  \label{fig:fig_compare_coordinates_surface}
+\end{figure}
+ % >>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+This gives a smooth analytical stretching in computational space that is constrained to
+given specified surface and bottom grid cell thicknesses in real space.
+This is not to be confused with the hybrid schemes that
+superimpose geopotential coordinates on terrain following coordinates thus
+creating a non-analytical vertical coordinate that
+therefore may suffer from large gradients in the vertical resolutions.
+This stretching is less straightforward to implement than the \citet{song.haidvogel_JCP94} stretching,
+but has the advantage of resolving diurnal processes in deep water and has generally flatter slopes.
+
+As with the \citet{song.haidvogel_JCP94} stretching the stretch is only applied at depths greater than
+the critical depth $h_c$.
+In this example two options are available in depths shallower than $h_c$,
+with pure sigma being applied if the \np{ln\_sigcrit} is true and pure z-coordinates if it is false
+(the z-coordinate being equal to the depths of the stretched coordinate at $h_c$).
+
+Minimising the horizontal slope of the vertical coordinate is important in terrain-following systems as
+large slopes lead to hydrostatic consistency.
+A hydrostatic consistency parameter diagnostic following \citet{haney_JPO91} has been implemented,
+and is output as part of the model mesh file at the start of the run.
+
+% -------------------------------------------------------------------------------------------------------------
+%        z*- or s*-coordinate
+% -------------------------------------------------------------------------------------------------------------
+\subsubsection[\zstar- or \sstar-coordinate (\forcode{ln_linssh = .false.})]
+{\zstar- or \sstar-coordinate (\protect\np{ln\_linssh}\forcode{ = .false.})}
+\label{subsec:DOMCFG_zgr_star}
+
+This option is described in the Report by Levier \textit{et al.} (2007), available on the \NEMO web site.
+
+\biblio
+
+\pindex
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_E.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_E.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_E.tex	(revision 11422)
@@ -49,6 +49,6 @@
 
 This results in a dissipatively dominant (\ie hyper-diffusive) truncation error
-\citep{Shchepetkin_McWilliams_OM05}.
-The overall performance of the advection scheme is similar to that reported in \cite{Farrow1995}.
+\citep{shchepetkin.mcwilliams_OM05}.
+The overall performance of the advection scheme is similar to that reported in \cite{farrow.stevens_JPO95}.
 It is a relatively good compromise between accuracy and smoothness.
 It is not a \emph{positive} scheme meaning false extrema are permitted but
@@ -65,7 +65,7 @@
 the second term which is the diffusive part of the scheme, is evaluated using the \textit{before} velocity
 (forward in time).
-This is discussed by \citet{Webb_al_JAOT98} in the context of the Quick advection scheme.
+This is discussed by \citet{webb.de-cuevas.ea_JAOT98} in the context of the Quick advection scheme.
 UBS and QUICK schemes only differ by one coefficient.
-Substituting 1/6 with 1/8 in (\autoref{eq:tra_adv_ubs}) leads to the QUICK advection scheme \citep{Webb_al_JAOT98}.
+Substituting 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 \mdl{traadv\_ubs} module and obtain a QUICK scheme.
@@ -80,5 +80,5 @@
 $\tau_w^{ubs}$ will be evaluated using either \textit{(a)} a centered $2^{nd}$ order scheme,
 or \textit{(b)} a TVD scheme, or \textit{(c)} an interpolation based on conservative parabolic splines following
-\citet{Shchepetkin_McWilliams_OM05} implementation of UBS in ROMS, or \textit{(d)} an UBS.
+\citet{shchepetkin.mcwilliams_OM05} implementation of UBS in ROMS, or \textit{(d)} an UBS.
 The $3^{rd}$ case has dispersion properties similar to an eight-order accurate conventional scheme.
 
@@ -255,5 +255,5 @@
 \subsection{Griffies iso-neutral diffusion operator}
 
-Let try to define a scheme that get its inspiration from the \citet{Griffies_al_JPO98} scheme,
+Let try to define a scheme that get its inspiration from the \citet{griffies.gnanadesikan.ea_JPO98} scheme,
 but is formulated within the \NEMO framework
 (\ie using scale factors rather than grid-size and having a position of $T$-points that
@@ -272,5 +272,5 @@
 Nevertheless, this technique works fine for $T$ and $S$ as they are active tracers
 (\ie they enter the computation of density), but it does not work for a passive tracer.
-\citep{Griffies_al_JPO98} introduce a different way to discretise the off-diagonal terms that
+\citep{griffies.gnanadesikan.ea_JPO98} introduce a different way to discretise the off-diagonal terms that
 nicely solve the problem.
 The idea is to get rid of combinations of an averaged in one direction combined with
@@ -308,5 +308,5 @@
 \begin{figure}[!ht]
   \begin{center}
-    \includegraphics[width=0.70\textwidth]{Fig_ISO_triad}
+    \includegraphics[width=\textwidth]{Fig_ISO_triad}
     \caption{
       \protect\label{fig:ISO_triad}
@@ -508,5 +508,5 @@
 \]
 
-\citep{Griffies_JPO98} introduces another way to implement the eddy induced advection, the so-called skew form.
+\citep{griffies_JPO98} introduces another way to implement the eddy induced advection, the so-called skew form.
 It is based on a transformation of the advective fluxes using the non-divergent nature of the eddy induced velocity.
 For example in the (\textbf{i},\textbf{k}) plane, the tracer advective fluxes can be transformed as follows:
@@ -574,5 +574,5 @@
 The horizontal component reduces to the one use for an horizontal laplacian operator and
 the vertical one keeps the same complexity, but not more.
-This property has been used to reduce the computational time \citep{Griffies_JPO98},
+This property has been used to reduce the computational time \citep{griffies_JPO98},
 but it is not of practical use as usually $A \neq A_e$.
 Nevertheless this property can be used to choose a discret form of \autoref{eq:eiv_skew_continuous} which
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_iso.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_iso.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_iso.tex	(revision 11422)
@@ -4,5 +4,6 @@
 \newcommand{\rML}[1][i]{\ensuremath{_{\mathrm{ML}\,#1}}}
 \newcommand{\rMLt}[1][i]{\tilde{r}_{\mathrm{ML}\,#1}}
-\newcommand{\triad}[6][]{\ensuremath{{}_{#2}^{#3}{\mathbb{#4}_{#1}}_{#5}^{\,#6}}}
+%% Move to ../../global/new_cmds.tex to avoid error with \listoffigures
+%\newcommand{\triad}[6][]{\ensuremath{{}_{#2}^{#3}{\mathbb{#4}_{#1}}_{#5}^{\,#6}}
 \newcommand{\triadd}[5]{\ensuremath{{}_{#1}^{#2}{\mathbb{#3}}_{#4}^{\,#5}}}
 \newcommand{\triadt}[5]{\ensuremath{{}_{#1}^{#2}{\tilde{\mathbb{#3}}}_{#4}^{\,#5}}}
@@ -52,5 +53,5 @@
   the vertical skew flux is further reduced to ensure no vertical buoyancy flux,
   giving an almost pure horizontal diffusive tracer flux within the mixed layer.
-  This is similar to the tapering suggested by \citet{Gerdes1991}. See \autoref{subsec:Gerdes-taper}
+  This is similar to the tapering suggested by \citet{gerdes.koberle.ea_CD91}. See \autoref{subsec:Gerdes-taper}
 \item[\np{ln\_botmix\_triad}]
   See \autoref{sec:iso_bdry}. 
@@ -71,5 +72,5 @@
 \label{sec:iso}
 
-We have implemented into \NEMO a scheme inspired by \citet{Griffies_al_JPO98},
+We have implemented into \NEMO a scheme inspired by \citet{griffies.gnanadesikan.ea_JPO98},
 but formulated within the \NEMO framework, using scale factors rather than grid-sizes.
 
@@ -194,5 +195,5 @@
 \subsection{Expression of the skew-flux in terms of triad slopes}
 
-\citep{Griffies_al_JPO98} introduce a different discretization of the off-diagonal terms that
+\citep{griffies.gnanadesikan.ea_JPO98} introduce a different discretization of the off-diagonal terms that
 nicely solves the problem.
 % Instead of multiplying the mean slope calculated at the $u$-point by
@@ -201,5 +202,5 @@
 \begin{figure}[tb]
   \begin{center}
-    \includegraphics[width=1.05\textwidth]{Fig_GRIFF_triad_fluxes}
+    \includegraphics[width=\textwidth]{Fig_GRIFF_triad_fluxes}
     \caption{
       \protect\label{fig:ISO_triad}
@@ -265,5 +266,5 @@
 \begin{figure}[tb]
   \begin{center}
-    \includegraphics[width=0.80\textwidth]{Fig_GRIFF_qcells}
+    \includegraphics[width=\textwidth]{Fig_GRIFF_qcells}
     \caption{
       \protect\label{fig:qcells}
@@ -473,5 +474,5 @@
 
 To complete the discretization we now need only specify the triad volumes $_i^k\mathbb{V}_{i_p}^{k_p}$.
-\citet{Griffies_al_JPO98} identifies these $_i^k\mathbb{V}_{i_p}^{k_p}$ as the volumes of the quarter cells,
+\citet{griffies.gnanadesikan.ea_JPO98} identifies these $_i^k\mathbb{V}_{i_p}^{k_p}$ as the volumes of the quarter cells,
 defined in terms of the distances between $T$, $u$,$f$ and $w$-points.
 This is the natural discretization of \autoref{eq:cts-var}.
@@ -658,5 +659,5 @@
 \begin{figure}[h]
   \begin{center}
-    \includegraphics[width=0.60\textwidth]{Fig_GRIFF_bdry_triads}
+    \includegraphics[width=\textwidth]{Fig_GRIFF_bdry_triads}
     \caption{
       \protect\label{fig:bdry_triads}
@@ -685,5 +686,5 @@
 As discussed in \autoref{subsec:LDF_slp_iso},
 iso-neutral slopes relative to geopotentials must be bounded everywhere,
-both for consistency with the small-slope approximation and for numerical stability \citep{Cox1987, Griffies_Bk04}.
+both for consistency with the small-slope approximation and for numerical stability \citep{cox_OM87, griffies_bk04}.
 The bound chosen in \NEMO is applied to each component of the slope separately and
 has a value of $1/100$ in the ocean interior.
@@ -732,5 +733,5 @@
 \[
   % \label{eq:iso_tensor_ML}
-  D^{lT}=\nabla {\rm {\bf .}}\left( {A^{lT}\;\Re \;\nabla T} \right) \qquad
+  D^{lT}=\nabla {\mathrm {\mathbf .}}\left( {A^{lT}\;\Re \;\nabla T} \right) \qquad
   \mbox{with}\quad \;\;\Re =\left( {{
         \begin{array}{*{20}c}
@@ -829,5 +830,5 @@
     (\eg the green triad $i_p=1/2,k_p=-1/2$) are tapered to the appropriate basal triad.}
   % }
-  \includegraphics[width=0.60\textwidth]{Fig_GRIFF_MLB_triads}
+  \includegraphics[width=\textwidth]{Fig_GRIFF_MLB_triads}
 \end{figure}
 % >>>>>>>>>>>>>>>>>>>>>>>>>>>>
@@ -847,5 +848,5 @@
 \[
   % \label{eq:iso_tensor_ML2}
-  D^{lT}=\nabla {\rm {\bf .}}\left( {A^{lT}\;\Re \;\nabla T} \right) \qquad
+  D^{lT}=\nabla {\mathrm {\mathbf .}}\left( {A^{lT}\;\Re \;\nabla T} \right) \qquad
   \mbox{with}\quad \;\;\Re =\left( {{
         \begin{array}{*{20}c}
@@ -859,5 +860,5 @@
 \footnote{
   To ensure good behaviour where horizontal density gradients are weak,
-  we in fact follow \citet{Gerdes1991} and
+  we in fact follow \citet{gerdes.koberle.ea_CD91} and
   set $\rML^*=\mathrm{sgn}(\tilde{r}_i)\min(|\rMLt^2/\tilde{r}_i|,|\tilde{r}_i|)-\sigma_i$.
 }
@@ -865,5 +866,5 @@
 This approach is similar to multiplying the iso-neutral diffusion coefficient by
 $\tilde{r}_{\mathrm{max}}^{-2}\tilde{r}_i^{-2}$ for steep slopes,
-as suggested by \citet{Gerdes1991} (see also \citet{Griffies_Bk04}).
+as suggested by \citet{gerdes.koberle.ea_CD91} (see also \citet{griffies_bk04}).
 Again it is applied separately to each triad $_i^k\mathbb{R}_{i_p}^{k_p}$
 
@@ -925,5 +926,5 @@
 
 However, when \np{ln\_traldf\_triad} is set true,
-\NEMO instead implements eddy induced advection according to the so-called skew form \citep{Griffies_JPO98}.
+\NEMO instead implements eddy induced advection according to the so-called skew form \citep{griffies_JPO98}.
 It is based on a transformation of the advective fluxes using the non-divergent nature of the eddy induced velocity.
 For example in the (\textbf{i},\textbf{k}) plane,
@@ -1139,5 +1140,5 @@
 it is equivalent to a horizontal eiv (eddy-induced velocity) that is uniform within the mixed layer
 \autoref{eq:eiv_v}.
-This ensures that the eiv velocities do not restratify the mixed layer \citep{Treguier1997,Danabasoglu_al_2008}.
+This ensures that the eiv velocities do not restratify the mixed layer \citep{treguier.held.ea_JPO97,danabasoglu.ferrari.ea_JC08}.
 Equivantly, in terms of the skew-flux formulation we use here,
 the linear slope tapering within the mixed-layer gives a linearly varying vertical flux,
@@ -1153,5 +1154,5 @@
 $uw$ (integer +1/2 $i$, integer $j$, integer +1/2 $k$) and $vw$ (integer $i$, integer +1/2 $j$, integer +1/2 $k$)
 points (see Table \autoref{tab:cell}) respectively.
-We follow \citep{Griffies_Bk04} and calculate the streamfunction at a given $uw$-point from
+We follow \citep{griffies_bk04} and calculate the streamfunction at a given $uw$-point from
 the surrounding four triads according to:
 \[
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_ASM.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_ASM.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_ASM.tex	(revision 11422)
@@ -8,12 +8,20 @@
 \label{chap:ASM}
 
-Authors: D. Lea,  M. Martin, K. Mogensen, A. Weaver, ...   % do we keep
+\minitoc
 
-\minitoc
+\vfill
+\begin{figure}[b]
+\subsubsection*{Changes record}
+\begin{tabular}{l||l|m{0.65\linewidth}}
+    Release   & Author        & Modifications \\
+    {\em 4.0} & {\em D. J. Lea} & {\em \NEMO 4.0 updates}  \\
+    {\em 3.4} & {\em D. J. Lea, M. Martin, K. Mogensen, A. Weaver} & {\em Initial version}  \\
+\end{tabular}
+\end{figure}
 
 \newpage
 
 The ASM code adds the functionality to apply increments to the model variables: temperature, salinity,
-sea surface height, velocity and sea ice concentration. 
+sea surface height, velocity and sea ice concentration.
 These are read into the model from a NetCDF file which may be produced by separate data assimilation code.
 The code can also output model background fields which are used as an input to data assimilation code.
@@ -37,18 +45,18 @@
 it may be preferable to introduce the increment gradually into the ocean model in order to
 minimize spurious adjustment processes.
-This technique is referred to as Incremental Analysis Updates (IAU) \citep{Bloom_al_MWR96}.
+This technique is referred to as Incremental Analysis Updates (IAU) \citep{bloom.takacs.ea_MWR96}.
 IAU is a common technique used with 3D assimilation methods such as 3D-Var or OI.
 IAU is used when \np{ln\_asmiau} is set to true.
 
-With IAU, the model state trajectory ${\bf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$)
+With IAU, the model state trajectory ${\mathbf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$)
 is corrected by adding the analysis increments for temperature, salinity, horizontal velocity and SSH as
 additional tendency terms to the prognostic equations:
 \begin{align*}
   % \label{eq:wa_traj_iau}
-  {\bf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\bf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\bf x}^{a}
+  {\mathbf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\mathbf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\mathbf x}^{a}
 \end{align*}
-where $F_{i}$ is a weighting function for applying the increments $\delta\tilde{\bf x}^{a}$ defined such that
+where $F_{i}$ is a weighting function for applying the increments $\delta\tilde{\mathbf x}^{a}$ defined such that
 $\sum_{i=1}^{N} F_{i}=1$.
-${\bf x}^b$ denotes the model initial state and ${\bf x}^a$ is the model state after the increments are applied.
+${\mathbf x}^b$ denotes the model initial state and ${\mathbf x}^a$ is the model state after the increments are applied.
 To control the adjustment time of the model to the increment,
 the increment can be applied over an arbitrary sub-window, $t_{m} \leq t_{i} \leq t_{n}$,
@@ -56,5 +64,5 @@
 Typically the increments are spread evenly over the full window.
 In addition, two different weighting functions have been implemented.
-The first function employs constant weights, 
+The first function (namelist option \np{niaufn} = 0) employs constant weights,
 \begin{align}
   \label{eq:F1_i}
@@ -62,12 +70,12 @@
   =\left\{
   \begin{array}{ll}
-    0     &    {\rm if} \; \; \; t_{i} < t_{m}                \\
-    1/M &    {\rm if} \; \; \; t_{m} < t_{i} \leq t_{n} \\
-    0     &    {\rm if} \; \; \; t_{i} > t_{n}
+    0     &    {\mathrm if} \; \; \; t_{i} < t_{m}                \\
+    1/M &    {\mathrm if} \; \; \; t_{m} < t_{i} \leq t_{n} \\
+    0     &    {\mathrm if} \; \; \; t_{i} > t_{n}
   \end{array}
-            \right. 
+            \right.
 \end{align}
 where $M = m-n$.
-The second function employs peaked hat-like weights in order to give maximum weight in the centre of the sub-window,
+The second function (namelist option \np{niaufn} = 1) employs peaked hat-like weights in order to give maximum weight in the centre of the sub-window,
 with the weighting reduced linearly to a small value at the window end-points:
 \begin{align}
@@ -76,12 +84,12 @@
   =\left\{
   \begin{array}{ll}
-    0                           &    {\rm if} \; \; \; t_{i}       <     t_{m}                        \\
-    \alpha \, i               &    {\rm if} \; \; \; t_{m}    \leq t_{i}    \leq   t_{M/2}   \\
-    \alpha \, (M - i +1) &    {\rm if} \; \; \; t_{M/2}  <    t_{i}    \leq   t_{n}       \\
-    0                            &   {\rm if} \; \; \; t_{i}        >    t_{n}
+    0                           &    {\mathrm if} \; \; \; t_{i}       <     t_{m}                        \\
+    \alpha \, i               &    {\mathrm if} \; \; \; t_{m}    \leq t_{i}    \leq   t_{M/2}   \\
+    \alpha \, (M - i +1) &    {\mathrm if} \; \; \; t_{M/2}  <    t_{i}    \leq   t_{n}       \\
+    0                            &   {\mathrm if} \; \; \; t_{i}        >    t_{n}
   \end{array}
                                    \right.
 \end{align}
-where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even. 
+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}.
@@ -92,6 +100,9 @@
 \label{sec:ASM_div_dmp}
 
-The velocity increments may be initialized by the iterative application of a divergence damping operator.
-In iteration step $n$ new estimates of velocity increments $u^{n}_I$ and $v^{n}_I$ are updated by:
+It is quite challenging for data assimilation systems to provide non-divergent velocity increments.
+Applying divergent velocity increments will likely cause spurious vertical velocities in the model. This section describes a method to take velocity increments provided to \NEMO ($u^0_I$ and $v^0_I$) and adjust them by the iterative application of a divergence damping operator. The method is also described in \citet{dobricic.pinardi.ea_OS07}.
+
+In iteration step $n$ (starting at $n=1$) new estimates of velocity increments $u^{n}_I$ and $v^{n}_I$ are updated by:
+
 \begin{equation}
   \label{eq:asm_dmp}
@@ -105,5 +116,7 @@
   \right.,
 \end{equation}
-where
+
+where the divergence is defined as
+
 \[
   % \label{eq:asm_div}
@@ -112,5 +125,6 @@
       +\delta_j \left[ {e_{1v}\,e_{3v}\,v^{n-1}_I} \right]} \right).
 \]
-By the application of \autoref{eq:asm_dmp} and \autoref{eq:asm_dmp} the divergence is filtered in each iteration,
+
+By the application of \autoref{eq:asm_dmp} the divergence is filtered in each iteration,
 and the vorticity is left unchanged.
 In the presence of coastal boundaries with zero velocity increments perpendicular to the coast
@@ -118,10 +132,9 @@
 This type of the initialisation reduces the vertical velocity magnitude and
 alleviates the problem of the excessive unphysical vertical mixing in the first steps of the model integration
-\citep{Talagrand_JAS72, Dobricic_al_OS07}.
+\citep{talagrand_JAS72, dobricic.pinardi.ea_OS07}.
 Diffusion coefficients are defined as $A_D = \alpha e_{1t} e_{2t}$, where $\alpha = 0.2$.
 The divergence damping is activated by assigning to \np{nn\_divdmp} in the \textit{nam\_asminc} namelist
 a value greater than zero.
-By choosing this value to be of the order of 100 the increments in
-the vertical velocity will be significantly reduced.
+This specifies the number of iterations of the divergence damping. Setting a value of the order of 100 will result in a significant reduction in the vertical velocity induced by the increments.
 
 
@@ -131,8 +144,8 @@
 \label{sec:ASM_details}
 
-Here we show an example \ngn{namasm} namelist and the header of an example assimilation increments file on
+Here we show an example \ngn{nam\_asminc} namelist and the header of an example assimilation increments file on
 the ORCA2 grid.
 
-%------------------------------------------namasm-----------------------------------------------------
+%------------------------------------------nam_asminc-----------------------------------------------------
 %
 \nlst{nam_asminc}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_CONFIG.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_CONFIG.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_CONFIG.tex	(revision 11422)
@@ -18,5 +18,5 @@
 \label{sec:CFG_intro}
 
-The purpose of this part of the manual is to introduce the \NEMO reference configurations.
+The purpose of this part of the manual is to introduce the NEMO reference configurations.
 These configurations are offered as means to explore various numerical and physical options,
 thus allowing the user to verify that the code is performing in a manner consistent with that we are running.
@@ -24,4 +24,5 @@
 The reference configurations also provide a sense for some of the options available in the code,
 though by no means are all options exercised in the reference configurations.
+Configuration is defined manually through the \textit{namcfg} namelist variables.
 
 %------------------------------------------namcfg----------------------------------------------------
@@ -33,13 +34,12 @@
 % 1D model configuration
 % ================================================================
-\section{C1D: 1D Water column model (\protect\key{c1d}) }
+\section[C1D: 1D Water column model (\texttt{\textbf{key\_c1d}})]
+{C1D: 1D Water column model (\protect\key{c1d})}
 \label{sec:CFG_c1d}
 
-BE careful: to be re-written according to suppression of jpizoom and jpjzoom !!!!
-
-The 1D model option simulates a stand alone water column within the 3D \NEMO system.
+The 1D model option simulates a stand alone water column within the 3D NEMO system.
 It can be applied to the ocean alone or to the ocean-ice system and can include passive tracers or a biogeochemical model.
 It is set up by defining the position of the 1D water column in the grid
-(see \textit{CONFIG/SHARED/namelist\_ref} ). 
+(see \textit{cfgs/SHARED/namelist\_ref}). 
 The 1D model is a very useful tool
 \textit{(a)} to learn about the physics and numerical treatment of vertical mixing processes;
@@ -50,32 +50,23 @@
 \textit{(d)} to produce extra diagnostics, without the large memory requirement of the full 3D model.
 
-The methodology is based on the use of the zoom functionality over the smallest possible domain:
-a 3x3 domain centered on the grid point of interest, with some extra routines.
-There is no need to define a new mesh, bathymetry, initial state or forcing,
-since the 1D model will use those of the configuration it is a zoom of.
-The chosen grid point is set in \textit{\ngn{namcfg}} namelist by
-setting the \np{jpizoom} and \np{jpjzoom} parameters to the indices of the location of the chosen grid point.
+The methodology is based on the configuration of the smallest possible domain:
+a 3x3 domain with 75 vertical levels.
 
 The 1D model has some specifies. First, all the horizontal derivatives are assumed to be zero,
 and second, the two components of the velocity are moved on a $T$-point. 
-Therefore, defining \key{c1d} changes five main things in the code behaviour: 
+Therefore, defining \key{c1d} changes some things in the code behaviour: 
 \begin{description}
 \item[(1)]
-  the lateral boundary condition routine (\rou{lbc\_lnk}) set the value of the central column of
-  the 3x3 domain is imposed over the whole domain;
-\item[(3)]
-  a call to \rou{lbc\_lnk} is systematically done when reading input data (\ie in \mdl{iom});
-\item[(3)]
   a simplified \rou{stp} routine is used (\rou{stp\_c1d}, see \mdl{step\_c1d} module) in which
   both lateral tendancy terms and lateral physics are not called;
-\item[(4)]
+\item[(2)]
   the vertical velocity is zero
   (so far, no attempt at introducing a Ekman pumping velocity has been made);
-\item[(5)]
+\item[(3)]
   a simplified treatment of the Coriolis term is performed as $U$- and $V$-points are the same
   (see \mdl{dyncor\_c1d}).
 \end{description}
-All the relevant \textit{\_c1d} modules can be found in the NEMOGCM/NEMO/OPA\_SRC/C1D directory of
-the \NEMO distribution.
+All the relevant \textit{\_c1d} modules can be found in the src/OCE/C1D directory of
+the NEMO distribution.
 
 % to be added:  a test case on the yearlong Ocean Weather Station (OWS) Papa dataset of Martin (1985)
@@ -88,10 +79,10 @@
 
 The ORCA family is a series of global ocean configurations that are run together with
-the LIM sea-ice model (ORCA-LIM) and possibly with PISCES biogeochemical model (ORCA-LIM-PISCES),
-using various resolutions.
-An appropriate namelist is available in \path{CONFIG/ORCA2_LIM3_PISCES/EXP00/namelist_cfg} for ORCA2.
+the SI3 model (ORCA-ICE) and possibly with PISCES biogeochemical model (ORCA-ICE-PISCES).
+An appropriate namelist is available in \path{cfgs/ORCA2_ICE_PISCES/EXPREF/namelist_cfg} for ORCA2.
 The domain of ORCA2 configuration is defined in \ifile{ORCA\_R2\_zps\_domcfg} file,
-this file is available in tar file in the wiki of NEMO: \\
-https://forge.ipsl.jussieu.fr/nemo/wiki/Users/ReferenceConfigurations/ORCA2\_LIM3\_PISCES \\
+this file is available in tar file on the NEMO community zenodo platform: \\
+https://doi.org/10.5281/zenodo.2640723
+
 In this namelist\_cfg the name of domain input file is set in \ngn{namcfg} block of namelist. 
 
@@ -99,5 +90,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=0.98\textwidth]{Fig_ORCA_NH_mesh}
+    \includegraphics[width=\textwidth]{Fig_ORCA_NH_mesh}
     \caption{
       \protect\label{fig:MISC_ORCA_msh}
@@ -106,5 +97,5 @@
       The two "north pole" are the foci of a series of embedded ellipses (blue curves) which
       are determined analytically and form the i-lines of the ORCA mesh (pseudo latitudes).
-      Then, following \citet{Madec_Imbard_CD96}, the normal to the series of ellipses (red curves) is computed which
+      Then, following \citet{madec.imbard_CD96}, the normal to the series of ellipses (red curves) is computed which
       provides the j-lines of the mesh (pseudo longitudes).
     }
@@ -119,5 +110,5 @@
 \label{subsec:CFG_orca_grid}
 
-The ORCA grid is a tripolar is based on the semi-analytical method of \citet{Madec_Imbard_CD96}.
+The ORCA grid is a tripolar grid based on the semi-analytical method of \citet{madec.imbard_CD96}.
 It allows to construct a global orthogonal curvilinear ocean mesh which has no singularity point inside
 the computational domain since two north mesh poles are introduced and placed on lands.
@@ -131,6 +122,6 @@
 \begin{figure}[!tbp]
   \begin{center}
-    \includegraphics[width=1.0\textwidth]{Fig_ORCA_NH_msh05_e1_e2}
-    \includegraphics[width=0.80\textwidth]{Fig_ORCA_aniso}
+    \includegraphics[width=\textwidth]{Fig_ORCA_NH_msh05_e1_e2}
+    \includegraphics[width=\textwidth]{Fig_ORCA_aniso}
     \caption {
       \protect\label{fig:MISC_ORCA_e1e2}
@@ -158,5 +149,5 @@
 
 % -------------------------------------------------------------------------------------------------------------
-%       ORCA-LIM(-PISCES) configurations
+%       ORCA-ICE(-PISCES) configurations
 % -------------------------------------------------------------------------------------------------------------
 \subsection{ORCA pre-defined resolution}
@@ -199,7 +190,7 @@
 The ORCA\_R2 configuration has the following specificity: starting from a 2\deg~ORCA mesh,
 local mesh refinements were applied to the Mediterranean, Red, Black and Caspian Seas,
-so that the resolution is 1\deg \time 1\deg there.
+so that the resolution is 1\deg~ there.
 A local transformation were also applied with in the Tropics in order to refine the meridional resolution up to
-0.5\deg at the Equator.
+0.5\deg~ at the Equator.
 
 The ORCA\_R1 configuration has only a local tropical transformation to refine the meridional resolution up to
@@ -211,24 +202,24 @@
 For ORCA\_R1 and R025, setting the configuration key to 75 allows to use 75 vertical levels, otherwise 46 are used.
 In the other ORCA configurations, 31 levels are used
-(see \autoref{tab:orca_zgr} %\sfcomment{HERE I need to put new table for ORCA2 values} and \autoref{fig:zgr}).
-
-Only the ORCA\_R2 is provided with all its input files in the \NEMO distribution.
-It is very similar to that used as part of the climate model developed at IPSL for the 4th IPCC assessment of
-climate change (Marti et al., 2009).
-It is also the basis for the \NEMO contribution to the Coordinate Ocean-ice Reference Experiments (COREs)
-documented in \citet{Griffies_al_OM09}. 
+(see \autoref{tab:orca_zgr}). %\sfcomment{HERE I need to put new table for ORCA2 values} and \autoref{fig:zgr}).
+
+Only the ORCA\_R2 is provided with all its input files in the NEMO distribution.
+%It is very similar to that used as part of the climate model developed at IPSL for the 4th IPCC assessment of
+%climate change (Marti et al., 2009).
+%It is also the basis for the \NEMO contribution to the Coordinate Ocean-ice Reference Experiments (COREs)
+%documented in \citet{griffies.biastoch.ea_OM09}. 
 
 This version of ORCA\_R2 has 31 levels in the vertical, with the highest resolution (10m) in the upper 150m
 (see \autoref{tab:orca_zgr} and \autoref{fig:zgr}). 
 The bottom topography and the coastlines are derived from the global atlas of Smith and Sandwell (1997). 
-The default forcing uses the boundary forcing from \citet{Large_Yeager_Rep04} (see \autoref{subsec:SBC_blk_core}), 
+The default forcing uses the boundary forcing from \citet{large.yeager_rpt04} (see \autoref{subsec:SBC_blk_core}), 
 which was developed for the purpose of running global coupled ocean-ice simulations without
 an interactive atmosphere.
-This \citet{Large_Yeager_Rep04} dataset is available through
+This \citet{large.yeager_rpt04} dataset is available through
 the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/CORE.html}{GFDL web site}.
-The "normal year" of \citet{Large_Yeager_Rep04} has been chosen of the \NEMO distribution since release v3.3. 
-
-ORCA\_R2 pre-defined configuration can also be run with an AGRIF zoom over the Agulhas current area
-(\key{agrif} defined) and, by setting the appropriate variables, see \path{CONFIG/SHARED/namelist_ref}.
+The "normal year" of \citet{large.yeager_rpt04} has been chosen of the NEMO distribution since release v3.3. 
+
+ORCA\_R2 pre-defined configuration can also be run with multiply online nested zooms (\ie with AGRIF, \key{agrif} defined). This is available as the AGRIF\_DEMO configuration that can be found in the \path{cfgs/AGRIF_DEMO/} directory.
+
 A regional Arctic or peri-Antarctic configuration is extracted from an ORCA\_R2 or R05 configurations using
 sponge layers at open boundaries. 
@@ -237,15 +228,16 @@
 %       GYRE family: double gyre basin
 % -------------------------------------------------------------------------------------------------------------
-\section{GYRE family: double gyre basin }
+\section{GYRE family: double gyre basin}
 \label{sec:CFG_gyre}
 
-The GYRE configuration \citep{Levy_al_OM10} has been built to
+The GYRE configuration \citep{levy.klein.ea_OM10} has been built to
 simulate the seasonal cycle of a double-gyre box model.
-It consists in an idealized domain similar to that used in the studies of \citet{Drijfhout_JPO94} and
-\citet{Hazeleger_Drijfhout_JPO98, Hazeleger_Drijfhout_JPO99, Hazeleger_Drijfhout_JGR00, Hazeleger_Drijfhout_JPO00},
+It consists in an idealized domain similar to that used in the studies of \citet{drijfhout_JPO94} and
+\citet{hazeleger.drijfhout_JPO98, hazeleger.drijfhout_JPO99, hazeleger.drijfhout_JGR00, hazeleger.drijfhout_JPO00},
 over which an analytical seasonal forcing is applied.
 This allows to investigate the spontaneous generation of a large number of interacting, transient mesoscale eddies 
 and their contribution to the large scale circulation. 
 
+The GYRE configuration run together with the PISCES biogeochemical model (GYRE-PISCES).
 The domain geometry is a closed rectangular basin on the $\beta$-plane centred at $\sim$ 30\deg{N} and
 rotated by 45\deg, 3180~km long, 2120~km wide and 4~km deep (\autoref{fig:MISC_strait_hand}).
@@ -253,5 +245,5 @@
 The configuration is meant to represent an idealized North Atlantic or North Pacific basin.
 The circulation is forced by analytical profiles of wind and buoyancy fluxes.
-The applied forcings vary seasonally in a sinusoidal manner between winter and summer extrema \citep{Levy_al_OM10}. 
+The applied forcings vary seasonally in a sinusoidal manner between winter and summer extrema \citep{levy.klein.ea_OM10}. 
 The wind stress is zonal and its curl changes sign at 22\deg{N} and 36\deg{N}.
 It forces a subpolar gyre in the north, a subtropical gyre in the wider part of the domain and
@@ -266,12 +258,15 @@
 The GYRE configuration is set like an analytical configuration.
 Through \np{ln\_read\_cfg}\forcode{ = .false.} in \textit{namcfg} namelist defined in
-the reference configuration \path{CONFIG/GYRE/EXP00/namelist_cfg}
+the reference configuration \path{cfgs/GYRE_PISCES/EXPREF/namelist_cfg}
 analytical definition of grid in GYRE is done in usrdef\_hrg, usrdef\_zgr routines.
 Its horizontal resolution (and thus the size of the domain) is determined by
 setting \np{nn\_GYRE} in \ngn{namusr\_def}: \\
+
 \np{jpiglo} $= 30 \times$ \np{nn\_GYRE} + 2   \\
+
 \np{jpjglo} $= 20 \times$ \np{nn\_GYRE} + 2   \\
+
 Obviously, the namelist parameters have to be adjusted to the chosen resolution,
-see the Configurations pages on the NEMO web site (Using NEMO\/Configurations).
+see the Configurations pages on the NEMO web site (NEMO Configurations).
 In the vertical, GYRE uses the default 30 ocean levels (\jp{jpk}\forcode{ = 31}) (\autoref{fig:zgr}).
 
@@ -281,14 +276,14 @@
 even though the physical integrity of the solution can be compromised.
 Benchmark is activate via \np{ln\_bench}\forcode{ = .true.} in \ngn{namusr\_def} in
-namelist \path{CONFIG/GYRE/EXP00/namelist_cfg}.
+namelist \path{cfgs/GYRE_PISCES/EXPREF/namelist_cfg}.
 
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=1.0\textwidth]{Fig_GYRE}
+    \includegraphics[width=\textwidth]{Fig_GYRE}
     \caption{
       \protect\label{fig:GYRE}
       Snapshot of relative vorticity at the surface of the model domain in GYRE R9, R27 and R54.
-      From \citet{Levy_al_OM10}.
+      From \citet{levy.klein.ea_OM10}.
     }
   \end{center}
@@ -304,12 +299,11 @@
 The AMM, Atlantic Margins Model, is a regional model covering the Northwest European Shelf domain on
 a regular lat-lon grid at approximately 12km horizontal resolution.
-The appropriate \textit{\&namcfg} namelist  is available in \textit{CONFIG/AMM12/EXP00/namelist\_cfg}.
+The appropriate \textit{\&namcfg} namelist  is available in \textit{cfgs/AMM12/EXPREF/namelist\_cfg}.
 It is used to build the correct dimensions of the AMM domain.
 
 This configuration tests several features of NEMO functionality specific to the shelf seas.
-In particular, the AMM uses $S$-coordinates in the vertical rather than $z$-coordinates and
-is forced with tidal lateral boundary conditions using a flather boundary condition from the BDY module.
-The AMM configuration uses the GLS (\key{zdfgls}) turbulence scheme,
-the VVL non-linear free surface(\key{vvl}) and time-splitting (\key{dynspg\_ts}).
+In particular, the AMM uses $s$-coordinates in the vertical rather than $z$-coordinates and
+is forced with tidal lateral boundary conditions using a Flather boundary condition from the BDY module.
+Also specific to the AMM configuration is the use of the GLS turbulence scheme (\np{ln\_zdfgls} \forcode{= .true.}).
 
 In addition to the tidal boundary condition the model may also take open boundary conditions from
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DIA.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DIA.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DIA.tex	(revision 11422)
@@ -10,4 +10,17 @@
 \minitoc
 
+\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
 
@@ -15,5 +28,5 @@
 %       Old Model Output 
 % ================================================================
-\section{Old model output (default)}
+\section{Model output}
 \label{sec:DIA_io_old}
 
@@ -25,6 +38,5 @@
 the same run performed in one step.
 It should be noted that this requires that the restart file contains two consecutive time steps for
-all the prognostic variables, and that it is saved in the same binary format as the one used by the computer that
-is to read it (in particular, 32 bits binary IEEE format must not be used for this file).
+all the prognostic variables.
 
 The output listing and file(s) are predefined but should be checked and eventually adapted to the user's needs.
@@ -38,13 +50,4 @@
 the writing work is distributed over the processors in massively parallel computing.
 A complete description of the use of this I/O server is presented in the next section.
-
-By default, \key{iomput} is not defined,
-NEMO produces NetCDF with the old IOIPSL library which has been kept for compatibility and its easy installation.
-However, the IOIPSL library is quite inefficient on parallel machines and, since version 3.2,
-many diagnostic options have been added presuming the use of \key{iomput}.
-The usefulness of the default IOIPSL-based option is expected to reduce with each new release.
-If \key{iomput} is not defined, output files and content are defined in the \mdl{diawri} module and
-contain mean (or instantaneous if \key{diainstant} is defined) values over a regular period of
-nn\_write time-steps (namelist parameter). 
 
 %\gmcomment{                    % start of gmcomment
@@ -91,6 +94,9 @@
 in a very easy way.
 All details of iomput functionalities are listed in the following subsections.
-Examples of the XML files that control the outputs can be found in: \path{NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef.xml},
-\path{NEMOGCM/CONFIG/SHARED/field_def.xml} and \path{NEMOGCM/CONFIG/SHARED/domain_def.xml}. \\
+Examples of the XML files that control the outputs can be found in: 
+\path{cfgs/ORCA2_ICE_PISCES/EXPREF/iodef.xml},
+\path{cfgs/SHARED/field_def_nemo-oce.xml},
+\path{cfgs/SHARED/field_def_nemo-pisces.xml},
+\path{cfgs/SHARED/field_def_nemo-ice.xml} and \path{cfgs/SHARED/domain_def_nemo.xml}. \\
 
 The second functionality targets output performance when running in parallel (\key{mpp\_mpi}).
@@ -101,5 +107,5 @@
 
 In version 3.6, the iom\_put interface depends on
-an external code called \href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/branchs/xios-1.0}{XIOS-1.0} 
+an external code called \href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/branchs/xios-2.5}{XIOS-2.5} 
 (use of revision 618 or higher is required).
 This new IO server can take advantage of the parallel I/O functionality of NetCDF4 to
@@ -168,7 +174,7 @@
 \xmlline|<variable id="using_server" type="bool"></variable>|
 
-The {\tt using\_server} setting determines whether or not the server will be used in \textit{attached mode}
-(as a library) [{\tt> false <}] or in \textit{detached mode}
-(as an external executable on N additional, dedicated cpus) [{\tt > true <}].
+The {\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 type of each file can be either ''multiple\_file'' or ''one\_file''.
@@ -207,5 +213,5 @@
 \subsubsection{Control of XIOS: the context in iodef.xml}
 
-As well as the {\tt using\_server} flag, other controls on the use of XIOS are set in the XIOS context in iodef.xml.
+As well as the {\ttfamily using\_server} flag, other controls on the use of XIOS are set in the XIOS context in iodef.xml.
 See the XML basics section below for more details on XML syntax and rules.
 
@@ -257,6 +263,6 @@
 See the installation guide on the \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS} wiki for help and guidance.
 NEMO will need to link to the compiled XIOS library.
-The \href{https://forge.ipsl.jussieu.fr/nemo/wiki/Users/ModelInterfacing/InputsOutputs#Inputs-OutputsusingXIOS}
-{XIOS with NEMO} guide provides an example illustration of how this can be achieved.
+The \href{https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/guide/html/install.html#extract-and-install-xios}
+{Extract and install XIOS} guide provides an example illustration of how this can be achieved.
 
 \subsubsection{Add your own outputs}
@@ -269,5 +275,5 @@
 \begin{enumerate}
 \item[1.]
-  in NEMO code, add a \forcode{CALL iom\_put( 'identifier', array )} where you want to output a 2D or 3D array.
+  in NEMO code, add a \forcode{CALL iom_put( 'identifier', array )} where you want to output a 2D or 3D array.
 \item[2.]
   If necessary, add \forcode{USE iom ! I/O manager library} to the list of used modules in
@@ -442,10 +448,12 @@
 \xmlline|<context src="./nemo_def.xml" />|
  
-\noindent In NEMO, by default, the field and domain definition is done in 2 separate files:
-\path{NEMOGCM/CONFIG/SHARED/field_def.xml} and \path{NEMOGCM/CONFIG/SHARED/domain_def.xml} that
+\noindent In NEMO, by default, the field definition is done in 3 separate files (
+\path{cfgs/SHARED/field_def_nemo-oce.xml},
+\path{cfgs/SHARED/field_def_nemo-pisces.xml} and
+\path{cfgs/SHARED/field_def_nemo-ice.xml} ) and the  domain definition is done in another file ( \path{cfgs/SHARED/domain_def_nemo.xml} )
+that
 are included in the main iodef.xml file through the following commands:
 \begin{xmllines}
-<field_definition src="./field_def.xml" />
-<domain_definition src="./domain_def.xml" />
+<context id="nemo" src="./context_nemo.xml"/> 
 \end{xmllines}
 
@@ -508,5 +516,8 @@
 
 Secondly, the group can be used to replace a list of elements.
-Several examples of groups of fields are proposed at the end of the file \path{CONFIG/SHARED/field_def.xml}.
+Several examples of groups of fields are proposed at the end of the XML field files (
+\path{cfgs/SHARED/field_def_nemo-oce.xml},
+\path{cfgs/SHARED/field_def_nemo-pisces.xml} and
+\path{cfgs/SHARED/field_def_nemo-ice.xml} ) .
 For example, a short list of the usual variables related to the U grid:
 
@@ -514,5 +525,5 @@
 <field_group id="groupU" >
 	<field field_ref="uoce"  />
-	<field field_ref="suoce" />
+	<field field_ref="ssu" />
 	<field field_ref="utau"  />
 </field_group>
@@ -538,10 +549,10 @@
 the tag family domain.
 It must therefore be done in the domain part of the XML file. 
-For example, in \path{CONFIG/SHARED/domain_def.xml}, we provide the following example of a definition of 
+For example, in \path{cfgs/SHARED/domain_def.xml}, we provide the following example of a definition of 
 a 5 by 5 box with the bottom left corner at point (10,10).
 
 \begin{xmllines}
-<domain_group id="grid_T">
-	<domain id="myzoom" zoom_ibegin="10" zoom_jbegin="10" zoom_ni="5" zoom_nj="5" />
+<domain id="myzoomT" domain_ref="grid_T">
+	<zoom_domain ibegin="10" jbegin="10" ni="5" nj="5" />
 \end{xmllines}
 
@@ -551,5 +562,5 @@
 \begin{xmllines}
 <file id="myfile_vzoom" output_freq="1d" >
-	<field field_ref="toce" domain_ref="myzoom"/>
+	<field field_ref="toce" domain_ref="myzoomT"/>
 </file>
 \end{xmllines}
@@ -576,12 +587,14 @@
 \subsubsection{Define vertical zooms}
 
-Vertical zooms are defined through the attributs zoom\_begin and zoom\_end of the tag family axis.
+Vertical zooms are defined through the attributs zoom\_begin and zoom\_n of the tag family axis.
 It must therefore be done in the axis part of the XML file.
-For example, in \path{NEMOGCM/CONFIG/ORCA2_LIM/iodef_demo.xml}, we provide the following example:
-
-\begin{xmllines}
-<axis_group id="deptht" long_name="Vertical T levels" unit="m" positive="down" >
-	<axis id="deptht" />
-	<axis id="deptht_myzoom" zoom_begin="1" zoom_end="10" />
+For example, in \path{cfgs/ORCA2_ICE_PISCES/EXPREF/iodef_demo.xml}, we provide the following example:
+
+\begin{xmllines}
+<axis_definition>
+	<axis id="deptht" long_name="Vertical T levels" unit="m" positive="down" />
+	<axis id="deptht_zoom" azix_ref="deptht" >
+		<zoom_axis zoom_begin="1" zoom_n="10" />
+	</axis>
 \end{xmllines}
 
@@ -765,5 +778,5 @@
 \end{xmllines}
 
-Note that, then the code is crashing, writting real4 variables forces a numerical convection from 
+Note that, then the code is crashing, writting real4 variables forces a numerical conversion from 
 real8 to real4 which will create an internal error in NetCDF and will avoid the creation of the output files.
 Forcing double precision outputs with prec="8" (for example in the field\_definition) will avoid this problem.
@@ -938,5 +951,5 @@
     \hline
   \end{tabularx}
-  \caption{Field tags ("\tt{field\_*}")}
+  \caption{Field tags ("\ttfamily{field\_*}")}
 \end{table}
 
@@ -974,5 +987,5 @@
     \hline
   \end{tabularx}
-  \caption{File tags ("\tt{file\_*}")}
+  \caption{File tags ("\ttfamily{file\_*}")}
 \end{table}
 
@@ -1007,5 +1020,5 @@
     \hline
   \end{tabularx}
-  \caption{Axis tags ("\tt{axis\_*}")}
+  \caption{Axis tags ("\ttfamily{axis\_*}")}
 \end{table}
 
@@ -1040,5 +1053,5 @@
     \hline
   \end{tabularx}
-  \caption{Domain tags ("\tt{domain\_*)}"}
+  \caption{Domain tags ("\ttfamily{domain\_*)}"}
 \end{table}
 
@@ -1073,5 +1086,5 @@
     \hline
   \end{tabularx}
-  \caption{Grid tags ("\tt{grid\_*}")}
+  \caption{Grid tags ("\ttfamily{grid\_*}")}
 \end{table}
 
@@ -1114,5 +1127,5 @@
     \hline
   \end{tabularx}
-  \caption{Reference attributes ("\tt{*\_ref}")}
+  \caption{Reference attributes ("\ttfamily{*\_ref}")}
 \end{table}
 
@@ -1150,5 +1163,5 @@
     \hline
   \end{tabularx}
-  \caption{Domain attributes ("\tt{zoom\_*}")}
+  \caption{Domain attributes ("\ttfamily{zoom\_*}")}
 \end{table}
 
@@ -1318,5 +1331,5 @@
 \subsection{CF metadata standard compliance}
 
-Output from the XIOS-1.0 IO server is compliant with 
+Output from the XIOS IO server is compliant with 
 \href{http://cfconventions.org/Data/cf-conventions/cf-conventions-1.5/build/cf-conventions.html}{version 1.5} of
 the CF metadata standard. 
@@ -1332,5 +1345,6 @@
 %       NetCDF4 support
 % ================================================================
-\section{NetCDF4 support (\protect\key{netcdf4})}
+\section[NetCDF4 support (\texttt{\textbf{key\_netcdf4}})]
+{NetCDF4 support (\protect\key{netcdf4})}
 \label{sec:DIA_nc4}
 
@@ -1340,5 +1354,5 @@
 Chunking and compression can lead to significant reductions in file sizes for a small runtime overhead.
 For a fuller discussion on chunking and other performance issues the reader is referred to
-the NetCDF4 documentation found \href{http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Chunking}{here}.
+the NetCDF4 documentation found \href{https://www.unidata.ucar.edu/software/netcdf/docs/netcdf_perf_chunking.html}{here}.
 
 The new features are only available when the code has been linked with a NetCDF4 library
@@ -1389,6 +1403,6 @@
 \end{forlines}
 
-\noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\tt 46x38x1} respectively in
-the mono-processor case (\ie global domain of {\small\tt 182x149x31}).
+\noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\ttfamily 46x38x1} respectively in
+the mono-processor case (\ie global domain of {\small\ttfamily 182x149x31}).
 An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in 
 table \autoref{tab:NC4} which compares the results of two short runs of the ORCA2\_LIM reference configuration with
@@ -1450,5 +1464,6 @@
 %       Tracer/Dynamics Trends
 % -------------------------------------------------------------------------------------------------------------
-\section{Tracer/Dynamics trends  (\protect\ngn{namtrd})}
+\section[Tracer/Dynamics trends (\texttt{namtrd})]
+{Tracer/Dynamics trends (\protect\ngn{namtrd})}
 \label{sec:DIA_trd}
 
@@ -1462,5 +1477,5 @@
 (\ie at the end of each $dyn\cdots.F90$ and/or $tra\cdots.F90$ routines).
 This capability is controlled by options offered in \ngn{namtrd} namelist.
-Note that the output are done with xIOS, and therefore the \key{IOM} is required.
+Note that the output are done with XIOS, and therefore the \key{iomput} is required.
 
 What is done depends on the \ngn{namtrd} logical set to \forcode{.true.}:
@@ -1488,14 +1503,15 @@
 
 Note that the mixed layer tendency diagnostic can also be used on biogeochemical models via 
-the \key{trdtrc} and \key{trdmld\_trc} CPP keys.
+the \key{trdtrc} and \key{trdmxl\_trc} CPP keys.
 
 \textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested.
 In particular, options associated with \np{ln\_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl} are not working,
-and none of the options have been tested with variable volume (\ie \key{vvl} defined).
+and none of the options have been tested with variable volume (\ie \np{ln\_linssh}\forcode{ = .true.}).
 
 % -------------------------------------------------------------------------------------------------------------
 %       On-line Floats trajectories
 % -------------------------------------------------------------------------------------------------------------
-\section{FLO: On-Line Floats trajectories (\protect\key{floats})}
+\section[FLO: On-Line Floats trajectories (\texttt{\textbf{key\_floats}})]
+{FLO: On-Line Floats trajectories (\protect\key{floats})}
 \label{sec:FLO}
 %--------------------------------------------namflo-------------------------------------------------------
@@ -1506,8 +1522,8 @@
 The on-line computation of floats advected either by the three dimensional velocity field or constraint to
 remain at a given depth ($w = 0$ in the computation) have been introduced in the system during the CLIPPER project.
-Options are defined by \ngn{namflo} namelis variables.
-The algorithm used is based either on the work of \cite{Blanke_Raynaud_JPO97} (default option),
+Options are defined by \ngn{namflo} namelist variables.
+The algorithm used is based either on the work of \cite{blanke.raynaud_JPO97} (default option),
 or on a $4^th$ Runge-Hutta algorithm (\np{ln\_flork4}\forcode{ = .true.}).
-Note that the \cite{Blanke_Raynaud_JPO97} algorithm have the advantage of providing trajectories which
+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.
 
@@ -1519,5 +1535,5 @@
 In case of Ariane convention, input filename is \np{init\_float\_ariane}.
 Its format is: \\
-{\scriptsize \texttt{I J K nisobfl itrash itrash}}
+{\scriptsize \texttt{I J K nisobfl itrash}}
 
 \noindent with:
@@ -1577,8 +1593,6 @@
 In that case, output filename is trajec\_float.
 
-Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}).
-There are 2 possibilities:
-
-- if (\key{iomput}) is used, outputs are selected in  iodef.xml.
+Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}) with
+\key{iomput} and outputs selected in iodef.xml.
 Here it is an example of specification to put in files description section:
 
@@ -1597,16 +1611,13 @@
 \end{xmllines}
 
- -  if (\key{iomput}) is not used, a file called \ifile{trajec\_float} will be created by IOIPSL library.
-
- See also \href{http://stockage.univ-brest.fr/~grima/Ariane/}{here} the web site describing the off-line use of
- this marvellous diagnostic tool.
 
 % -------------------------------------------------------------------------------------------------------------
 %       Harmonic analysis of tidal constituents
 % -------------------------------------------------------------------------------------------------------------
-\section{Harmonic analysis of tidal constituents (\protect\key{diaharm}) }
+\section[Harmonic analysis of tidal constituents (\texttt{\textbf{key\_diaharm}})]
+{Harmonic analysis of tidal constituents (\protect\key{diaharm})}
 \label{sec:DIA_diag_harm}
 
-%------------------------------------------namdia_harm----------------------------------------------------
+%------------------------------------------nam_diaharm----------------------------------------------------
 %
 \nlst{nam_diaharm}
@@ -1616,5 +1627,5 @@
 This on-line Harmonic analysis is actived with \key{diaharm}.
 
-Some parameters are available in namelist \ngn{namdia\_harm}:
+Some parameters are available in namelist \ngn{nam\_diaharm}:
 
  - \np{nit000\_han} is the first time step used for harmonic analysis
@@ -1652,5 +1663,6 @@
 %       Sections transports
 % -------------------------------------------------------------------------------------------------------------
-\section{Transports across sections (\protect\key{diadct}) }
+\section[Transports across sections (\texttt{\textbf{key\_diadct}})]
+{Transports across sections (\protect\key{diadct})}
 \label{sec:DIA_diag_dct}
 
@@ -1664,6 +1676,6 @@
 
 Each section is defined by the coordinates of its 2 extremities.
-The pathways between them are contructed using tools which can be found in \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT}
-and are written in a binary file \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is later read in by
+The pathways between them are contructed using tools which can be found in \texttt{tools/SECTIONS\_DIADCT}
+and are written in a binary file \texttt{section\_ijglobal.diadct} which is later read in by
 NEMO to compute on-line transports.
 
@@ -1684,5 +1696,5 @@
 \subsubsection{Creating a binary file containing the pathway of each section}
 
-In \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT/run},
+In \texttt{tools/SECTIONS\_DIADCT/run},
 the file \textit{ {list\_sections.ascii\_global}} contains a list of all the sections that are to be computed
 (this list of sections is based on MERSEA project metrics).
@@ -1733,5 +1745,5 @@
   
  The script \texttt{job.ksh} computes the pathway for each section and creates a binary file
- \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is read by NEMO. \\
+ \texttt{section\_ijglobal.diadct} which is read by NEMO. \\
 
  It is possible to use this tools for new configuations: \texttt{job.ksh} has to be updated with
@@ -1809,10 +1821,10 @@
 The steric effect is therefore not explicitely represented.
 This approximation does not represent a serious error with respect to the flow field calculated by the model
-\citep{Greatbatch_JGR94}, but extra attention is required when investigating sea level,
+\citep{greatbatch_JGR94}, but extra attention is required when investigating sea level,
 as steric changes are an important contribution to local changes in sea level on seasonal and climatic time scales.
 This is especially true for investigation into sea level rise due to global warming.
 
 Fortunately, the steric contribution to the sea level consists of a spatially uniform component that
-can be diagnosed by considering the mass budget of the world ocean \citep{Greatbatch_JGR94}.
+can be diagnosed by considering the mass budget of the world ocean \citep{greatbatch_JGR94}.
 In order to better understand how global mean sea level evolves and thus how the steric sea level can be diagnosed,
 we compare, in the following, the non-Boussinesq and Boussinesq cases.
@@ -1888,9 +1900,9 @@
 the ocean surface, not by changes in mean mass of the ocean: the steric effect is missing in a Boussinesq fluid.
 
-Nevertheless, following \citep{Greatbatch_JGR94}, the steric effect on the volume can be diagnosed by
+Nevertheless, following \citep{greatbatch_JGR94}, the steric effect on the volume can be diagnosed by
 considering the mass budget of the ocean. 
 The apparent changes in $\mathcal{M}$, mass of the ocean, which are not induced by surface mass flux
 must be compensated by a spatially uniform change in the mean sea level due to expansion/contraction of the ocean
-\citep{Greatbatch_JGR94}.
+\citep{greatbatch_JGR94}.
 In others words, the Boussinesq mass, $\mathcal{M}_o$, can be related to $\mathcal{M}$,
 the total mass of the ocean seen by the Boussinesq model, via the steric contribution to the sea level,
@@ -1924,5 +1936,5 @@
 This value is a sensible choice for the reference density used in a Boussinesq ocean climate model since,
 with the exception of only a small percentage of the ocean, density in the World Ocean varies by no more than
-2$\%$ from this value (\cite{Gill1982}, page 47).
+2$\%$ from this value (\cite{gill_bk82}, page 47).
 
 Second, we have assumed here that the total ocean surface, $\mathcal{A}$,
@@ -1931,5 +1943,5 @@
   
 Third, the discretisation of \autoref{eq:steric_Bq} depends on the type of free surface which is considered.
-In the non linear free surface case, \ie \key{vvl} defined, it is given by
+In the non linear free surface case, \ie \np{ln\_linssh}\forcode{ = .true.}, it is given by
 
 \[
@@ -1954,5 +1966,5 @@
 so that there are no associated ocean currents.
 Hence, the dynamically relevant sea level is the effective sea level,
-\ie the sea level as if sea ice (and snow) were converted to liquid seawater \citep{Campin_al_OM08}.
+\ie the sea level as if sea ice (and snow) were converted to liquid seawater \citep{campin.marshall.ea_OM08}.
 However, in the current version of \NEMO the sea-ice is levitating above the ocean without mass exchanges between
 ice and ocean.
@@ -1970,11 +1982,11 @@
 where $S_o$ and $p_o$ are the initial salinity and pressure, respectively.
 
-Both steric and thermosteric sea level are computed in \mdl{diaar5} which needs the \key{diaar5} defined to
-be called.
+Both steric and thermosteric sea level are computed in \mdl{diaar5}.
 
 % -------------------------------------------------------------------------------------------------------------
 %       Other Diagnostics
 % -------------------------------------------------------------------------------------------------------------
-\section{Other diagnostics (\protect\key{diahth}, \protect\key{diaar5})}
+\section[Other diagnostics]
+{Other diagnostics}
 \label{sec:DIA_diag_others}
 
@@ -1982,9 +1994,10 @@
 The available ready-to-add diagnostics modules can be found in directory DIA.
 
-\subsection{Depth of various quantities (\protect\mdl{diahth})}
+\subsection[Depth of various quantities (\textit{diahth.F90})]
+{Depth of various quantities (\protect\mdl{diahth})}
 
 Among the available diagnostics the following ones are obtained when defining the \key{diahth} CPP key:
 
-- the mixed layer depth (based on a density criterion \citep{de_Boyer_Montegut_al_JGR04}) (\mdl{diahth})
+- the mixed layer depth (based on a density criterion \citep{de-boyer-montegut.madec.ea_JGR04}) (\mdl{diahth})
 
 - the turbocline depth (based on a turbulent mixing coefficient criterion) (\mdl{diahth})
@@ -1994,27 +2007,9 @@
 - the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth})
 
-% -----------------------------------------------------------
-%     Poleward heat and salt transports
-% -----------------------------------------------------------
-
-\subsection{Poleward heat and salt transports (\protect\mdl{diaptr})}
-
-%------------------------------------------namptr-----------------------------------------
-
-\nlst{namptr} 
-%-----------------------------------------------------------------------------------------
-
-The poleward heat and salt transports, their advective and diffusive component,
-and the meriodional stream function can be computed on-line in \mdl{diaptr} \np{ln\_diaptr} to true
-(see the \textit{\ngn{namptr} } namelist below).
-When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed for the Atlantic, Indian,
-Pacific and Indo-Pacific Oceans (defined north of 30\deg{S}) as well as for the World Ocean.
-The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains three 2D mask arrays,
-the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:mask_subasins}).
 
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=1.0\textwidth]{Fig_mask_subasins}
+    \includegraphics[width=\textwidth]{Fig_mask_subasins}
     \caption{
       \protect\label{fig:mask_subasins}
@@ -2032,10 +2027,23 @@
 %       CMIP specific diagnostics 
 % -----------------------------------------------------------
-\subsection{CMIP specific diagnostics (\protect\mdl{diaar5})}
-
-A series of diagnostics has been added in the \mdl{diaar5}.
-They corresponds to outputs that are required for AR5 simulations (CMIP5)
+\subsection[CMIP specific diagnostics (\textit{diaar5.F90}, \textit{diaptr.F90})]
+{CMIP specific diagnostics (\protect\mdl{diaar5})}
+
+A series of diagnostics has been added in the \mdl{diaar5} and \mdl{diaptr}.
+In \mdl{diaar5} they correspond to outputs that are required for AR5 simulations (CMIP5)
 (see also \autoref{sec:DIA_steric} for one of them).
-Activating those outputs requires to define the \key{diaar5} CPP key.
+The module \mdl{diaar5} is active when one of the following outputs is required : global total volume (voltot), global mean ssh (sshtot), global total mass (masstot), global mean temperature (temptot), global mean ssh steric (sshsteric), global mean ssh thermosteric (sshthster), global mean salinity (saltot), sea water pressure at sea floor (botpres), dynamic sea surface height (sshdyn).
+
+In \mdl{diaptr} when \np{ln\_diaptr}\forcode{ = .true.} 
+(see the \textit{\ngn{namptr} } namelist below) can be computed on-line the poleward heat and salt transports, their advective and diffusive component, and the meriodional stream function .
+When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed for the Atlantic, Indian,
+Pacific and Indo-Pacific Oceans (defined north of 30\deg{S}) as well as for the World Ocean.
+The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains three 2D mask arrays,
+the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:mask_subasins}).
+
+%------------------------------------------namptr-----------------------------------------
+
+\nlst{namptr} 
+%-----------------------------------------------------------------------------------------
 
 % -----------------------------------------------------------
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DIU.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DIU.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DIU.tex	(revision 11422)
@@ -33,5 +33,5 @@
 (\ie from the temperature of the top few model levels) or from some other source.  
 It must be noted that both the cool skin and warm layer models produce estimates of the change in temperature
-($\Delta T_{\rm{cs}}$ and $\Delta T_{\rm{wl}}$) and
+($\Delta T_{\mathrm{cs}}$ and $\Delta T_{\mathrm{wl}}$) and
 both must be added to a foundation SST to obtain the true skin temperature.
 
@@ -60,18 +60,18 @@
 %===============================================================
 
-The warm layer is calculated using the model of \citet{Takaya_al_JGR10} (TAKAYA10 model hereafter).
+The warm layer is calculated using the model of \citet{takaya.bidlot.ea_JGR10} (TAKAYA10 model hereafter).
 This is a simple flux based model that is defined by the equations
 \begin{align}
-\frac{\partial{\Delta T_{\rm{wl}}}}{\partial{t}}&=&\frac{Q(\nu+1)}{D_T\rho_w c_p
+\frac{\partial{\Delta T_{\mathrm{wl}}}}{\partial{t}}&=&\frac{Q(\nu+1)}{D_T\rho_w c_p
 \nu}-\frac{(\nu+1)ku^*_{w}f(L_a)\Delta T}{D_T\Phi\!\left(\frac{D_T}{L}\right)} \mbox{,}
 \label{eq:ecmwf1} \\
 L&=&\frac{\rho_w c_p u^{*^3}_{w}}{\kappa g \alpha_w Q }\mbox{,}\label{eq:ecmwf2}
 \end{align}
-where $\Delta T_{\rm{wl}}$ is the temperature difference between the top of the warm layer and the depth $D_T=3$\,m at which there is assumed to be no diurnal signal.
+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,
 $\kappa=0.4$ is von K\'{a}rm\'{a}n's constant, $c_p$ is the heat capacity at constant pressure of sea water,
 $\rho_w$ is the water density, and $L$ is the Monin-Obukhov length.
 The tunable variable $\nu$ is a shape parameter that defines the expected subskin temperature profile via
-$T(z) = T(0) - \left( \frac{z}{D_T} \right)^\nu \Delta T_{\rm{wl}}$,
+$T(z) = T(0) - \left( \frac{z}{D_T} \right)^\nu \Delta T_{\mathrm{wl}}$,
 where $T$ is the absolute temperature and $z\le D_T$ is the depth below the top of the warm layer.
 The influence of wind on TAKAYA10 comes through the magnitude of the friction velocity of the water $u^*_{w}$,
@@ -82,10 +82,10 @@
 the diurnal layer, \ie
 \[
-  Q = Q_{\rm{sol}} + Q_{\rm{lw}} + Q_{\rm{h}}\mbox{,}
+  Q = Q_{\mathrm{sol}} + Q_{\mathrm{lw}} + Q_{\mathrm{h}}\mbox{,}
   % \label{eq:e_flux_eqn}
 \]
-where $Q_{\rm{h}}$ is the sensible and latent heat flux, $Q_{\rm{lw}}$ is the long wave flux,
-and $Q_{\rm{sol}}$ is the solar flux absorbed within the diurnal warm layer.
-For $Q_{\rm{sol}}$ the 9 term representation of \citet{Gentemann_al_JGR09} is used.
+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}})$,
 where $L_a=0.3$\footnote{
@@ -118,11 +118,11 @@
 %===============================================================
 
-The cool skin is modelled using the framework of \citet{Saunders_JAS82} who used a formulation of the near surface temperature difference based upon the heat flux and the friction velocity $u^*_{w}$.
-As the cool skin is so thin (~1\,mm) we ignore the solar flux component to the heat flux and the Saunders equation for the cool skin temperature difference $\Delta T_{\rm{cs}}$ becomes
+The cool skin is modelled using the framework of \citet{saunders_JAS67} who used a formulation of the near surface temperature difference based upon the heat flux and the friction velocity $u^*_{w}$.
+As the cool skin is so thin (~1\,mm) we ignore the solar flux component to the heat flux and the Saunders equation for the cool skin temperature difference $\Delta T_{\mathrm{cs}}$ becomes
 \[
   % \label{eq:sunders_eqn}
-  \Delta T_{\rm{cs}}=\frac{Q_{\rm{ns}}\delta}{k_t} \mbox{,}
+  \Delta T_{\mathrm{cs}}=\frac{Q_{\mathrm{ns}}\delta}{k_t} \mbox{,}
 \]
-where $Q_{\rm{ns}}$ is the, usually negative, non-solar heat flux into the ocean and
+where $Q_{\mathrm{ns}}$ is the, usually negative, non-solar heat flux into the ocean and
 $k_t$ is the thermal conductivity of sea water.
 $\delta$ is the thickness of the skin layer and is given by
@@ -132,8 +132,8 @@
 \end{equation}
 where $\mu$ is the kinematic viscosity of sea water and $\lambda$ is a constant of proportionality which
-\citet{Saunders_JAS82} suggested varied between 5 and 10.
+\citet{saunders_JAS67} suggested varied between 5 and 10.
 
-The value of $\lambda$ used in equation (\autoref{eq:sunders_thick_eqn}) is that of \citet{Artale_al_JGR02},
-which is shown in \citet{Tu_Tsuang_GRL05} to outperform a number of other parametrisations at
+The value of $\lambda$ used in equation (\autoref{eq: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,
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DOM.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DOM.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DOM.tex	(revision 11422)
@@ -18,10 +18,21 @@
 %     - domclo:  closed sea and lakes.... management of closea sea area : specific to global configuration, both forced and coupled
 
+\vfill
+\begin{figure}[b]
+\subsubsection*{Changes record}
+\begin{tabular}{m{0.08\linewidth}||m{0.32\linewidth}|m{0.6\linewidth}}
+    Release   & Author(s)     & Modifications \\
+\hline
+    {\em 4.0} & {\em Simon M{\"u}ller \& Andrew Coward} & {\em Compatibility changes for v4.0. Major simplication has moved many of the options to external domain configuration tools. For now this information has been retained in \autoref{apdx:DOMAINcfg} }  \\
+    {\em 3.x} & {\em Sebastien Masson, Gurvan Madec \& Rashid Benshila } & {\em }  \\
+\end{tabular}
+\end{figure}
+
 \newpage
 
 Having defined the continuous equations in \autoref{chap:PE} and chosen a time discretization \autoref{chap:STP},
-we need to choose a discretization on a grid, and numerical algorithms.
+we need to choose a grid for spatial discretization and related numerical algorithms.
 In the present chapter, we provide a general description of the staggered grid used in \NEMO,
-and other information relevant to the main directory routines as well as the DOM (DOMain) directory.
+and other relevant information about the DOM (DOMain) source-code modules .
 
 % ================================================================
@@ -40,5 +51,5 @@
 \begin{figure}[!tb]
   \begin{center}
-    \includegraphics[]{Fig_cell}
+    \includegraphics[width=\textwidth]{Fig_cell}
     \caption{
       \protect\label{fig:cell}
@@ -55,10 +66,10 @@
 The numerical techniques used to solve the Primitive Equations in this model are based on the traditional,
 centred second-order finite difference approximation.
-Special attention has been given to the homogeneity of the solution in the three space directions.
+Special attention has been given to the homogeneity of the solution in the three spatial directions.
 The arrangement of variables is the same in all directions.
 It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with vector points $(u, v, w)$ defined in
 the centre of each face of the cells (\autoref{fig:cell}).
 This is the generalisation to three dimensions of the well-known ``C'' grid in Arakawa's classification
-\citep{Mesinger_Arakawa_Bk76}.
+\citep{mesinger.arakawa_bk76}.
 The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge and
 the barotropic stream function $\psi$ is defined at horizontal points overlying the $\zeta$ and $f$-points.
@@ -71,5 +82,5 @@
 Each scale factor is defined as the local analytical value provided by \autoref{eq:scale_factors}.
 As a result, the mesh on which partial derivatives $\pd[]{\lambda}$, $\pd[]{\varphi}$ and
-$\pd[]{z}$ are evaluated in a uniform mesh with a grid size of unity.
+$\pd[]{z}$ are evaluated is a uniform mesh with a grid size of unity.
 Discrete partial derivatives are formulated by the traditional, centred second order finite difference approximation
 while the scale factors are chosen equal to their local analytical value.
@@ -79,5 +90,5 @@
 the continuous properties (see \autoref{apdx:C}).
 A similar, related remark can be made about the domain size:
-when needed, an area, volume, or the total ocean depth must be evaluated as the sum of the relevant scale factors
+when needed, an area, volume, or the total ocean depth must be evaluated as the product or sum of the relevant scale factors
 (see \autoref{eq:DOM_bar} in the next section).
 
@@ -87,5 +98,5 @@
     \begin{tabular}{|p{46pt}|p{56pt}|p{56pt}|p{56pt}|}
       \hline
-      T	& $i 		 $ & $j      $ & $k      $ \\
+      t	& $i 		 $ & $j      $ & $k      $ \\
       \hline
       u	& $i + 1/2$ & $j      $ & $k      $ \\
@@ -107,10 +118,42 @@
       \protect\label{tab:cell}
       Location of grid-points as a function of integer or integer and a half value of the column, line or level.
-      This indexing is only used for the writing of the semi -discrete equation.
-      In the code, the indexing uses integer values only and has a reverse direction in the vertical
+      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}
 \end{table}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+Note that the definition of the scale factors
+(\ie as the analytical first derivative of the transformation that
+results in $(\lambda,\varphi,z)$ as a function of $(i,j,k)$)
+is specific to the \NEMO model \citep{marti.madec.ea_JGR92}.
+As an example, a scale factor in the $i$ direction is defined locally at a $t$-point,
+whereas many other models on a C grid choose to define such a scale factor as
+the distance between the $u$-points on each side of the $t$-point.
+Relying on an analytical transformation has two advantages:
+firstly, there is no ambiguity in the scale factors appearing in the discrete equations,
+since they are first introduced in the continuous equations;
+secondly, analytical transformations encourage good practice by the definition of smoothly varying grids
+(rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{treguier.dukowicz.ea_JGR96}.
+An example of the effect of such a choice is shown in \autoref{fig: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}
+\end{figure}
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 
@@ -132,5 +175,5 @@
 Following \autoref{eq:PE_grad} and \autoref{eq:PE_lap}, the gradient of a variable $q$ defined at
 a $t$-point has its three components defined at $u$-, $v$- and $w$-points while
-its Laplacian is defined at $t$-point.
+its Laplacian is defined at the $t$-point.
 These operators have the following discrete forms in the curvilinear $s$-coordinates system:
 \[
@@ -171,6 +214,6 @@
 \end{equation}
 
-The vertical average over the whole water column denoted by an overbar becomes for a quantity $q$ which
-is a masked field (i.e. equal to zero inside solid area):
+The vertical average over the whole water column is denoted by an overbar and is for
+a masked field $q$ (\ie a quantity that is equal to zero inside solid areas):
 \begin{equation}
   \label{eq:DOM_bar}
@@ -178,5 +221,5 @@
 \end{equation}
 where $H_q$  is the ocean depth, which is the masked sum of the vertical scale factors at $q$ points,
-$k^b$ and $k^o$ are the bottom and surface $k$-indices, and the symbol $k^o$ refers to a summation over
+$k^b$ and $k^o$ are the bottom and surface $k$-indices, and the symbol $\sum \limits_k$ refers to a summation over
 all grid points of the same type in the direction indicated by the subscript (here $k$).
 
@@ -193,6 +236,6 @@
 vector points $(u,v,w)$.
 
-Let $a$ and $b$ be two fields defined on the mesh, with value zero inside continental area.
-Using integration by parts it can be shown that the differencing operators ($\delta_i$, $\delta_j$ and $\delta_k$)
+Let $a$ and $b$ be two fields defined on the mesh, with a value of zero inside continental areas.
+It can be shown that the differencing operators ($\delta_i$, $\delta_j$ and $\delta_k$)
 are skew-symmetric linear operators, and further that the averaging operators $\overline{\cdots}^{\, i}$,
 $\overline{\cdots}^{\, j}$ and $\overline{\cdots}^{\, k}$) are symmetric linear operators, \ie
@@ -218,5 +261,5 @@
 \begin{figure}[!tb]
   \begin{center}
-    \includegraphics[]{Fig_index_hor}
+    \includegraphics[width=\textwidth]{Fig_index_hor}
     \caption{
       \protect\label{fig:index_hor}
@@ -228,10 +271,10 @@
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 
-The array representation used in the \fortran code requires an integer indexing while
-the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with the use of
-integer values for $t$-points and both integer and integer and a half values for all the other points.
-Therefore a specific integer indexing must be defined for points other than $t$-points
+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 changed so that the surface level is at $k = 1$.
+Furthermore, the direction of the vertical indexing has been reversed and the surface level set at $k = 1$.
 
 % -----------------------------------
@@ -253,29 +296,28 @@
 \label{subsec:DOM_Num_Index_vertical}
 
-In the vertical, the chosen indexing requires special attention since the $k$-axis is re-orientated downward in
-the \fortran code compared to the indexing used in the semi -discrete equations and
+In the vertical, the chosen indexing requires special attention since the direction of the $k$-axis in
+the \fortran code is the reverse of that used in the semi -discrete equations and
 given in \autoref{subsec:DOM_cell}.
-The sea surface corresponds to the $w$-level $k = 1$ which is the same index as $t$-level just below
+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}).
-The last $w$-level ($k = jpk$) either corresponds to the ocean floor or is inside the bathymetry while
-the last $t$-level is always inside the bathymetry (\autoref{fig:index_vert}).
-Note that for an increasing $k$ index, a $w$-point and the $t$-point just below have the same $k$ index,
-in opposition to what is done in the horizontal plane where
-it is the $t$-point and the nearest velocity points in the direction of the horizontal axis that
-have the same $i$ or $j$ index
+The last $w$-level ($k = jpk$) either corresponds to or is below the ocean floor while
+the last $t$-level is always outside the ocean domain (\autoref{fig:index_vert}).
+Note that a $w$-point and the directly underlaying $t$-point have a common $k$ index (\ie $t$-points and their
+nearest $w$-point neighbour in negative index direction), in contrast to the indexing on the horizontal plane where
+the $t$-point has the same index as the nearest velocity points in the positive direction of the respective horizontal axis index
 (compare the dashed area in \autoref{fig:index_hor} and \autoref{fig:index_vert}).
 Since the scale factors are chosen to be strictly positive,
-a \textit{minus sign} appears in the \fortran code \textit{before all the vertical derivatives} of
-the discrete equations given in this documentation.
+a \textit{minus sign} is included in the \fortran implementations of \textit{all the vertical derivatives} of
+the discrete equations given in this manual in order to accommodate the opposing vertical index directions in implementation and documentation.
 
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!pt]
   \begin{center}
-    \includegraphics[]{Fig_index_vert}
+    \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 orientated downward.
-      The dashed area indicates the cell in which variables contained in arrays have the same $k$-index.
+      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}
@@ -283,193 +325,151 @@
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 
+% -------------------------------------------------------------------------------------------------------------
+%        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 \ngn{namcfg}. 
+
+If \np{ln\_read\_cfg} is set to \forcode{.true.}, the domain-specific parameters
+and fields are read from a netCDF input file, whose name (without its .nc
+suffix) can be specified as the value of the \np{cn\_domcfg} parameter in
+namelist \ngn{namcfg}.
+
+If \np{ln\_read\_cfg} is set to \forcode{.false.}, the domain-specific
+parameters and fields can be provided (\eg analytically computed) by subroutines
+\mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}. These subroutines can be supplied in
+the \path{MY_SRC} directory of the configuration, and default versions that
+configure the spatial domain for the GYRE reference configuration are present in
+the \path{src/OCE/USR} directory.
+
+In version 4.0 there are no longer any options for reading complex bathmetries and 
+performing a vertical discretization at run-time. Whilst it is occasionally convenient
+to have a common bathymetry file and, for example, to run similar models with and
+without partial bottom boxes and/or sigma-coordinates, supporting such choices leads to
+overly complex code. Worse still is the difficulty of ensuring the model configurations 
+intended to be identical are indeed so when the model domain itself can be altered by runtime
+selections. The code previously used to perform vertical discretization has be incorporated 
+into an external tool (\path{tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMAINcfg}.
+
+The next subsections summarise the parameter and fields related to the
+configuration of the whole model domain. These represent the minimum information
+that must be provided either via the \np{cn\_domcfg} file or set by code
+inserted into user-supplied versions of the \mdl{usrdef\_*} subroutines. The
+requirements are presented in three sections: the domain size
+(\autoref{subsec:DOM_size}), the horizontal mesh
+(\autoref{subsec:DOM_hgr}), and the vertical grid
+(\autoref{subsec:DOM_zgr}).
+
 % -----------------------------------
 %        Domain Size
 % -----------------------------------
-\subsubsection{Domain size}
+\subsection{Domain size}
 \label{subsec:DOM_size}
 
-The total size of the computational domain is set by the parameters \np{jpiglo},
-\np{jpjglo} and \np{jpkglo} in the $i$, $j$ and $k$ directions respectively.
-Parameters $jpi$ and $jpj$ refer to the size of each processor subdomain when
-the code is run in parallel using domain decomposition (\key{mpp\_mpi} defined,
-see \autoref{sec:LBC_mpp}).
-
-% ================================================================
-% Domain: List of fields needed
-% ================================================================
-\section{Needed fields}
-\label{sec:DOM_fields}
-The ocean mesh (\ie the position of all the scalar and vector points) is defined by the transformation that
-gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$.
-The grid-points are located at integer or integer and a half values of as indicated in \autoref{tab:cell}.
-The associated scale factors are defined using the analytical first derivative of the transformation
-\autoref{eq:scale_factors}.
-Necessary fields for configuration definition are:
-
-\begin{itemize}
-\item
-  Geographic position:
-  longitude with \texttt{glamt}, \texttt{glamu}, \texttt{glamv}, \texttt{glamf} and
-  latitude  with \texttt{gphit}, \texttt{gphiu}, \texttt{gphiv}, \texttt{gphif}
-  (all respectively at T, U, V and F point)
-\item
-  Coriolis parameter (if domain not on the sphere): \texttt{ff\_f} and \texttt{ff\_t}
-  (at T and F point)
-\item
-  Scale factors:
-  \texttt{e1t}, \texttt{e1u}, \texttt{e1v} and \texttt{e1f} (on i direction),
-  \texttt{e2t}, \texttt{e2u}, \texttt{e2v} and \texttt{e2f} (on j direction) and
-  \texttt{ie1e2u\_v}, \texttt{e1e2u}, \texttt{e1e2v}. \\
-  \texttt{e1e2u}, \texttt{e1e2v} are u and v surfaces (if gridsize reduction in some straits), 
-  \texttt{ie1e2u\_v} is to flag set u and v surfaces are neither read nor computed.
-\end{itemize}
- 
-These fields can be read in an domain input file which name is setted in \np{cn\_domcfg} parameter specified in
-\ngn{namcfg}.
-
-\nlst{namcfg}
-
-Or they can be defined in an analytical way in \path{MY_SRC} directory of the configuration.
-For Reference Configurations of NEMO input domain files are supplied by NEMO System Team.
-For analytical definition of input fields two routines are supplied: \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}.
-They are an example of GYRE configuration parameters, and they are available in \path{src/OCE/USR} directory,
-they provide the horizontal and vertical mesh.
-% -------------------------------------------------------------------------------------------------------------
-%        Needed fields 
-% -------------------------------------------------------------------------------------------------------------
-%\subsection{List of needed fields to build DOMAIN}
-%\label{subsec:DOM_fields_list}
-
+The total size of the computational domain is set by the parameters
+\np{jpiglo}, \np{jpjglo} and \np{jpkglo} for the $i$, $j$ and $k$
+directions, respectively. Note, that the variables \forcode{jpi} and \forcode{jpj}
+refer to the size of each processor subdomain when the code is run in
+parallel using domain decomposition (\key{mpp\_mpi} defined, see
+\autoref{sec:LBC_mpp}).
+
+The name of the configuration is set through parameter \np{cn\_cfg},
+and the nominal resolution through parameter \np{nn\_cfg} (unless in
+the input file both of variables \forcode{ORCA} and \forcode{ORCA_index}
+are present, in which case \np{cn\_cfg} and \np{nn\_cfg} are set from these
+values accordingly).
+
+The global lateral boundary condition type is selected from 8 options
+using parameter \np{jperio}. See \autoref{sec:LBC_jperio} for
+details on the available options and the corresponding values for
+\np{jperio}.
 
 % ================================================================
 % Domain: Horizontal Grid (mesh) 
 % ================================================================
-\section{Horizontal grid mesh (\protect\mdl{domhgr})}
-\label{sec:DOM_hgr}
-
-% -------------------------------------------------------------------------------------------------------------
-%        Coordinates and scale factors 
-% -------------------------------------------------------------------------------------------------------------
-\subsection{Coordinates and scale factors}
-\label{subsec:DOM_hgr_coord_e}
-
-The ocean mesh (\ie the position of all the scalar and vector points) is defined by
-the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$.
-The grid-points are located at integer or integer and a half values of as indicated in \autoref{tab:cell}.
-The associated scale factors are defined using the analytical first derivative of the transformation
-\autoref{eq:scale_factors}.
-These definitions are done in two modules, \mdl{domhgr} and \mdl{domzgr},
-which provide the horizontal and vertical meshes, respectively.
-This section deals with the horizontal mesh parameters.
-
-In a horizontal plane, the location of all the model grid points is defined from
-the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$.
-The horizontal scale factors are calculated using \autoref{eq:scale_factors}.
-For example, when the longitude and latitude are function of a single value
-($i$ and $j$, respectively) (geographical configuration of the mesh),
-the horizontal mesh definition reduces to define the wanted $\lambda(i)$, $\varphi(j)$,
-and their derivatives $\lambda'(i) \ \varphi'(j)$ in the \mdl{domhgr} module.
-The model computes the grid-point positions and scale factors in the horizontal plane as follows:
-\begin{align*}
-   \lambda_t &\equiv \text{glamt} =      \lambda (i      )
-  &\varphi_t &\equiv \text{gphit} =      \varphi (j      ) \\
-   \lambda_u &\equiv \text{glamu} =      \lambda (i + 1/2)
-  &\varphi_u &\equiv \text{gphiu} =      \varphi (j      ) \\
-   \lambda_v &\equiv \text{glamv} =      \lambda (i      )
-  &\varphi_v &\equiv \text{gphiv} =      \varphi (j + 1/2) \\
-   \lambda_f &\equiv \text{glamf} =      \lambda (i + 1/2)
-  &\varphi_f &\equiv \text{gphif} =      \varphi (j + 1/2) \\
-   e_{1t}    &\equiv \text{e1t}   = r_a |\lambda'(i      ) \; \cos\varphi(j      ) |
-  &e_{2t}    &\equiv \text{e2t}   = r_a |\varphi'(j      )                         | \\
-   e_{1u}    &\equiv \text{e1t}   = r_a |\lambda'(i + 1/2) \; \cos\varphi(j      ) |
-  &e_{2u}    &\equiv \text{e2t}   = r_a |\varphi'(j      )                         | \\
-   e_{1v}    &\equiv \text{e1t}   = r_a |\lambda'(i      ) \; \cos\varphi(j + 1/2) |
-  &e_{2v}    &\equiv \text{e2t}   = r_a |\varphi'(j + 1/2)                         | \\
-   e_{1f}    &\equiv \text{e1t}   = r_a |\lambda'(i + 1/2) \; \cos\varphi(j + 1/2) |
-  &e_{2f}    &\equiv \text{e2t}   = r_a |\varphi'(j + 1/2)                         |
-\end{align*}
-where the last letter of each computational name indicates the grid point considered and
-$r_a$ is the earth radius (defined in \mdl{phycst} along with all universal constants).
-Note that the horizontal position of and scale factors at $w$-points are exactly equal to those of $t$-points,
-thus no specific arrays are defined at $w$-points.
-
-Note that the definition of the scale factors
-(\ie as the analytical first derivative of the transformation that
-gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$)
-is specific to the \NEMO model \citep{Marti_al_JGR92}.
-As an example, $e_{1t}$ is defined locally at a $t$-point,
-whereas many other models on a C grid choose to define such a scale factor as
-the distance between the $U$-points on each side of the $t$-point.
-Relying on an analytical transformation has two advantages:
-firstly, there is no ambiguity in the scale factors appearing in the discrete equations,
-since they are first introduced in the continuous equations;
-secondly, analytical transformations encourage good practice by the definition of smoothly varying grids
-(rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{Treguier1996}.
-An example of the effect of such a choice is shown in \autoref{fig:zgr_e3}.
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-\begin{figure}[!t]
-  \begin{center}
-    \includegraphics[]{Fig_zgr_e3}
-    \caption{
-      \protect\label{fig:zgr_e3}
-      Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical,
-      and (b) analytically derived grid-point position and scale factors.
-      For both grids here, the same $w$-point depth has been chosen but
-      in (a) the $t$-points are set half way between $w$-points while
-      in (b) they are defined from an analytical function:
-      $z(k) = 5 \, (k - 1/2)^3 - 45 \, (k - 1/2)^2 + 140 \, (k - 1/2) - 150$.
-      Note the resulting difference between the value of the grid-size $\Delta_k$ and
-      those of the scale factor $e_k$.
-    }
-  \end{center}
-\end{figure}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-
-% -------------------------------------------------------------------------------------------------------------
-%        Choice of horizontal grid
-% -------------------------------------------------------------------------------------------------------------
-\subsection{Choice of horizontal grid}
-\label{subsec:DOM_hgr_msh_choice}
-
-% -------------------------------------------------------------------------------------------------------------
-%        Grid files
-% -------------------------------------------------------------------------------------------------------------
-\subsection{Output grid files}
-\label{subsec:DOM_hgr_files}
-
-All the arrays relating to a particular ocean model configuration (grid-point position, scale factors, masks)
-can be saved in files if \np{nn\_msh} $\not = 0$ (namelist variable in \ngn{namdom}).
-This can be particularly useful for plots and off-line diagnostics.
-In some cases, the user may choose to make a local modification of a scale factor in the code.
-This is the case in global configurations when restricting the width of a specific strait
-(usually a one-grid-point strait that happens to be too wide due to insufficient model resolution).
-An example is Gibraltar Strait in the ORCA2 configuration.
-When such modifications are done,
-the output grid written when \np{nn\_msh} $\not = 0$ is no more equal to the input grid.
+\subsection{Horizontal grid mesh (\protect\mdl{domhgr})}
+\label{subsec:DOM_hgr}
+
+% ================================================================
+% Domain: List of hgr-related fields needed
+% ================================================================
+\subsubsection{Required fields}
+\label{sec:DOM_hgr_fields}
+The explicit specification of a range of mesh-related fields are required for the definition of a configuration. These include:
+
+\begin{Verbatim}[fontsize=\tiny]
+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{Verbatim}
+
+The values of the geographic longitude and latitude arrays at indices $i,j$ correspond to the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$, evaluated at the values as specified in Table \autoref{tab:cell} for the respective grid-point position. The calculation of the values of the horizontal scale factor arrays in general additionally involves partial derivatives of $\lambda$ and $\varphi$ with respect to $i$ and $j$, evaluated for the same arguments as $\lambda$ and $\varphi$.
+
+\subsubsection{Optional fields}
+\begin{Verbatim}[fontsize=\tiny]
+                                         /* Optional:                                                    */
+int    ORCA, ORCA_index                  /* configuration name, configuration resolution                 */
+double e1e2u, e1e2v                      /* U and V surfaces (if grid size reduction in some straits)    */
+double ff_f, ff_t                        /* Coriolis parameter (if not on the sphere)                    */
+\end{Verbatim}
+
+NEMO can support the local reduction of key strait widths by altering individual values of
+e2u or e1v at the appropriate locations. This is particularly useful for locations such as
+Gibraltar or Indonesian Throughflow pinch-points (see \autoref{sec:MISC_strait} for
+illustrated examples). The key is to reduce the faces of $T$-cell (\ie change the value of
+the horizontal scale factors at $u$- or $v$-point) but not the volume of the cells. Doing
+otherwise can lead to numerical instability issues.  In normal operation the surface areas
+are computed from $\texttt{e1u} * \texttt{e2u}$ and $\texttt{e1v} * \texttt{e2v}$ but in
+cases where a gridsize reduction is required, the unaltered surface areas at $u$ and $v$
+grid points (\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or pre-computed
+in \mdl{usrdef\_hgr}. If these arrays are present in the \np{cn\_domcfg} file they are
+read and the internal computation is suppressed. Versions of \mdl{usrdef\_hgr} which set
+their own values of \texttt{e1e2u} and \texttt{e1e2v} should set the surface-area
+computation flag: \texttt{ie1e2u\_v} to a non-zero value to suppress their re-computation.
+
+\smallskip
+Similar logic applies to the other optional fields: \texttt{ff\_f} and \texttt{ff\_t}
+which can be used to provide the Coriolis parameter at F- and T-points respectively if the
+mesh is not on a sphere. If present these fields will be read and used and the normal
+calculation ($2*\Omega*\sin(\varphi)$) suppressed. Versions of \mdl{usrdef\_hgr} which set
+their own values of \texttt{ff\_f} and \texttt{ff\_t} should set the Coriolis computation
+flag: \texttt{iff} to a non-zero value to suppress their re-computation.
+
+Note that longitudes, latitudes, and scale factors at $w$ points are exactly
+equal to those of $t$ points, thus no specific arrays are defined at $w$ points.
+
 
 % ================================================================
 % Domain: Vertical Grid (domzgr)
 % ================================================================
-\section{Vertical grid (\protect\mdl{domzgr})}
-\label{sec:DOM_zgr}
-%-----------------------------------------nam_zgr & namdom-------------------------------------------
-%
-%\nlst{namzgr} 
-
-\nlst{namdom} 
+\subsection[Vertical grid (\textit{domzgr.F90})]
+{Vertical grid (\protect\mdl{domzgr})}
+\label{subsec:DOM_zgr}
+%-----------------------------------------namdom-------------------------------------------
+\nlst{namdom}
 %-------------------------------------------------------------------------------------------------------------
 
-Variables are defined through the \ngn{namzgr} and \ngn{namdom} namelists.
 In the vertical, the model mesh is determined by four things: 
-(1) the bathymetry given in meters; 
-(2) the number of levels of the model (\jp{jpk}); 
-(3) the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and
-(4) the masking system, \ie the number of wet model levels at each 
-$(i,j)$ column of points.
+\begin{enumerate}
+  \item the bathymetry given in meters; 
+  \item the number of levels of the model (\jp{jpk}); 
+  \item the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and
+  \item the masking system, \ie the number of wet model levels at each 
+$(i,j)$ location of the horizontal grid.
+\end{enumerate}
 
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!tb]
   \begin{center}
-    \includegraphics[]{Fig_z_zps_s_sps}
+    \includegraphics[width=\textwidth]{Fig_z_zps_s_sps}
     \caption{
       \protect\label{fig:z_zps_s_sps}
@@ -480,5 +480,5 @@
       (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.}).
+      (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).
     }
@@ -487,507 +487,108 @@
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 
-The choice of a vertical coordinate, even if it is made through \ngn{namzgr} namelist parameters, 
-must be done once of all at the beginning of an experiment.
-It is not intended as an option which can be enabled or disabled in the middle of an experiment.
-Three main choices are offered (\autoref{fig:z_zps_s_sps}):
-$z$-coordinate with full step bathymetry (\np{ln\_zco}~\forcode{= .true.}),
-$z$-coordinate with partial step bathymetry (\np{ln\_zps}~\forcode{= .true.}),
-or generalized, $s$-coordinate (\np{ln\_sco}~\forcode{= .true.}).
-Hybridation of the three main coordinates are available:
-$s-z$ or $s-zps$ coordinate (\autoref{fig:z_zps_s_sps} and \autoref{fig:z_zps_s_sps}).
-By default a non-linear free surface is used: the coordinate follow the time-variation of the free surface so that
-the transformation is time dependent: $z(i,j,k,t)$ (\autoref{fig:z_zps_s_sps}).
-When a linear free surface is assumed (\np{ln\_linssh}~\forcode{= .true.}),
-the vertical coordinate are fixed in time, but the seawater can move up and down across the $z_0$ surface
-(in other words, the top of the ocean in not a rigid-lid).
-The last choice in terms of vertical coordinate concerns the presence (or not) in
-the model domain of ocean cavities beneath ice shelves.
-Setting \np{ln\_isfcav} to true allows to manage ocean cavities, otherwise they are filled in.
-This option is currently only available in $z$- or $zps$-coordinate,
-and partial step are also applied at the ocean/ice shelf interface.
-
-Contrary to the horizontal grid, the vertical grid is computed in the code and no provision is made for
-reading it from a file.
-The only input file is the bathymetry (in meters) (\ifile{bathy\_meter})
-\footnote{
-  N.B. in full step $z$-coordinate, a \ifile{bathy\_level} file can replace the \ifile{bathy\_meter} file,
-  so that the computation of the number of wet ocean point in each water column is by-passed}.
-If \np{ln\_isfcav}~\forcode{= .true.}, an extra file input file (\ifile{isf\_draft\_meter}) describing
-the ice shelf draft (in meters) is needed.
-
-After reading the bathymetry, the algorithm for vertical grid definition differs between the different options:
-\begin{description}
-\item[\textit{zco}]
-  set a reference coordinate transformation $z_0(k)$, and set $z(i,j,k,t) = z_0(k)$.
-\item[\textit{zps}]
-  set a reference coordinate transformation $z_0(k)$, and calculate the thickness of the deepest level at
-  each $(i,j)$ point using the bathymetry, to obtain the final three-dimensional depth and scale factor arrays.
-\item[\textit{sco}]
-  smooth the bathymetry to fulfill the hydrostatic consistency criteria and
-  set the three-dimensional transformation.
-\item[\textit{s-z} and \textit{s-zps}]
-  smooth the bathymetry to fulfill the hydrostatic consistency criteria and
-  set the three-dimensional transformation $z(i,j,k)$,
-  and possibly introduce masking of extra land points to better fit the original bathymetry file.
-\end{description}
-%%%
-\gmcomment{   add the description of the smoothing:  envelop topography...}
-%%%
-
-Unless a linear free surface is used (\np{ln\_linssh}~\forcode{= .false.}),
-the arrays describing the grid point depths and vertical scale factors are three set of
-three dimensional arrays $(i,j,k)$ defined at \textit{before}, \textit{now} and \textit{after} time step.
-The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively.
-They are updated at each model time step using a fixed reference coordinate system which
-computer names have a $\_0$ suffix.
-When the linear free surface option is used (\np{ln\_linssh}~\forcode{= .true.}), \textit{before},
-\textit{now} and \textit{after} arrays are simply set one for all to their reference counterpart.
-
-% -------------------------------------------------------------------------------------------------------------
-%        Meter Bathymetry
-% -------------------------------------------------------------------------------------------------------------
-\subsection{Meter bathymetry}
-\label{subsec:DOM_bathy}
-
-Three options are possible for defining the bathymetry, according to the namelist variable \np{nn\_bathy}
-(found in \ngn{namdom} namelist): 
-\begin{description}
-\item[\np{nn\_bathy}~\forcode{= 0}]:
-  a flat-bottom domain is defined.
-  The total depth $z_w (jpk)$ is given by the coordinate transformation.
-  The domain can either be a closed basin or a periodic channel depending on the parameter \np{jperio}.
-\item[\np{nn\_bathy}~\forcode{= -1}]:
-  a domain with a bump of topography one third of the domain width at the central latitude.
-  This is meant for the "EEL-R5" configuration, a periodic or open boundary channel with a seamount.
-\item[\np{nn\_bathy}~\forcode{= 1}]:
-  read a bathymetry and ice shelf draft (if needed).
-  The \ifile{bathy\_meter} file (Netcdf format) provides the ocean depth (positive, in meters) at
-  each grid point of the model grid.
-  The bathymetry is usually built by interpolating a standard bathymetry product (\eg ETOPO2) onto
-  the horizontal ocean mesh.
-  Defining the bathymetry also defines the coastline: where the bathymetry is zero,
-  no model levels are defined (all levels are masked).
-
-  The \ifile{isfdraft\_meter} file (Netcdf format) provides the ice shelf draft (positive, in meters) at
-  each grid point of the model grid.
-  This file is only needed if \np{ln\_isfcav}~\forcode{= .true.}.
-  Defining the ice shelf draft will also define the ice shelf edge and the grounding line position.
-\end{description}
-
-When a global ocean is coupled to an atmospheric model it is better to represent all large water bodies
-(\eg great lakes, Caspian sea...) even if the model resolution does not allow their communication with
-the rest of the ocean.
-This is unnecessary when the ocean is forced by fixed atmospheric conditions,
-so these seas can be removed from the ocean domain.
-The user has the option to set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}),
-but the code has to be adapted to the user's configuration.
-
-% -------------------------------------------------------------------------------------------------------------
-%        z-coordinate  and reference coordinate transformation
-% -------------------------------------------------------------------------------------------------------------
-\subsection[$Z$-coordinate (\protect\np{ln\_zco}~\forcode{= .true.}) and ref. coordinate]
-				{$Z$-coordinate (\protect\np{ln\_zco}~\forcode{= .true.}) and reference coordinate}
-\label{subsec:DOM_zco}
-
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-\begin{figure}[!tb]
-  \begin{center}
-    \includegraphics[]{Fig_zgr}
-    \caption{
-      \protect\label{fig:zgr}
-      Default vertical mesh for ORCA2: 30 ocean levels (L30).
-      Vertical level functions for (a) T-point depth and (b) the associated scale factor as computed from
-      \autoref{eq:DOM_zgr_ana_1} using \autoref{eq:DOM_zgr_coef} in $z$-coordinate.
-    }
-  \end{center}
-\end{figure}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-
-The reference coordinate transformation $z_0(k)$ defines the arrays $gdept_0$ and $gdepw_0$ for $t$- and $w$-points,
-respectively.
-As indicated on \autoref{fig:index_vert} \jp{jpk} is the number of $w$-levels.
-$gdepw_0(1)$ is the ocean surface.
-There are at most \jp{jpk}-1 $t$-points inside the ocean,
-the additional $t$-point at $jk = jpk$ is below the sea floor and is not used.
-The vertical location of $w$- and $t$-levels is defined from the analytic expression of the depth $z_0(k)$ whose
-analytical derivative with respect to $k$ provides the vertical scale factors.
-The user must provide the analytical expression of both $z_0$ and its first derivative with respect to $k$.
-This is done in routine \mdl{domzgr} through statement functions,
-using parameters provided in the \ngn{namcfg} namelist.
-
-It is possible to define a simple regular vertical grid by giving zero stretching (\np{ppacr}~\forcode{= 0}).
-In that case, the parameters \jp{jpk} (number of $w$-levels) and
-\np{pphmax} (total ocean depth in meters) fully define the grid.
-
-For climate-related studies it is often desirable to concentrate the vertical resolution near the ocean surface.
-The following function is proposed as a standard for a $z$-coordinate (with either full or partial steps): 
-\begin{gather}
-  \label{eq:DOM_zgr_ana_1}
-    z_0  (k) = h_{sur} - h_0 \; k - \; h_1 \; \log  \big[ \cosh ((k - h_{th}) / h_{cr}) \big] \\
-    e_3^0(k) = \lt|    - h_0      -    h_1 \; \tanh \big[        (k - h_{th}) / h_{cr}  \big] \rt|
-\end{gather}
-where $k = 1$ to \jp{jpk} for $w$-levels and $k = 1$ to $k = 1$ for $T-$levels.
-Such an expression allows us to define a nearly uniform vertical location of levels at the ocean top and bottom with
-a smooth hyperbolic tangent transition in between (\autoref{fig:zgr}).
-
-If the ice shelf cavities are opened (\np{ln\_isfcav}~\forcode{= .true.}), the definition of $z_0$ is the same.
-However, definition of $e_3^0$ at $t$- and $w$-points is respectively changed to:
-\begin{equation}
-  \label{eq:DOM_zgr_ana_2}
-  \begin{split}
-    e_3^T(k) &= z_W (k + 1) - z_W (k    ) \\
-    e_3^W(k) &= z_T (k    ) - z_T (k - 1)
-  \end{split}
-\end{equation}
-This formulation decrease the self-generated circulation into the ice shelf cavity 
-(which can, in extreme case, leads to blow up).\\
- 
-The most used vertical grid for ORCA2 has $10~m$ ($500~m$) resolution in the surface (bottom) layers and
-a depth which varies from 0 at the sea surface to a minimum of $-5000~m$.
-This leads to the following conditions:
-\begin{equation}
-  \label{eq:DOM_zgr_coef}
-  \begin{array}{ll}
-    e_3 (1   + 1/2) =  10. & z(1  ) =     0. \\
-    e_3 (jpk - 1/2) = 500. & z(jpk) = -5000.
-  \end{array}
-\end{equation}
-
-With the choice of the stretching $h_{cr} = 3$ and the number of levels \jp{jpk}~$= 31$,
-the four coefficients $h_{sur}$, $h_0$, $h_1$, and $h_{th}$ in
-\autoref{eq:DOM_zgr_ana_2} have been determined such that
-\autoref{eq:DOM_zgr_coef} is satisfied, through an optimisation procedure using a bisection method.
-For the first standard ORCA2 vertical grid this led to the following values:
-$h_{sur} = 4762.96$, $h_0 = 255.58, h_1 = 245.5813$, and $h_{th} = 21.43336$.
-The resulting depths and scale factors as a function of the model levels are shown in
-\autoref{fig:zgr} and given in \autoref{tab:orca_zgr}.
-Those values correspond to the parameters \np{ppsur}, \np{ppa0}, \np{ppa1}, \np{ppkth} in \ngn{namcfg} namelist.
-
-Rather than entering parameters $h_{sur}$, $h_0$, and $h_1$ directly, it is possible to recalculate them.
-In that case the user sets \np{ppsur}~$=$~\np{ppa0}~$=$~\np{ppa1}~$= 999999$.,
-in \ngn{namcfg} namelist, and specifies instead the four following parameters:
+The choice of a vertical coordinate is made when setting up the configuration;
+it is not intended to be an option which can be changed in the middle of an
+experiment. The one exception to this statement being the choice of linear or
+non-linear free surface. In v4.0 the linear free surface option is implemented
+as a special case of the non-linear free surface. This is computationally
+wasteful since it uses the structures for time-varying 3D metrics for fields
+that (in the linear free surface case) are fixed. However, the linear
+free-surface is rarely used and implementing it this way means a single configuration
+file can support both options.
+
+By default a non-linear free surface is used (\np{ln\_linssh} set to \forcode{ =
+.false.} in \ngn{namdom}): the coordinate follow the time-variation of the free
+surface so that the transformation is time dependent: $z(i,j,k,t)$
+(\eg \autoref{fig:z_zps_s_sps}f).  When a linear free surface is assumed
+(\np{ln\_linssh} set to \forcode{ = .true.} in \ngn{namdom}), the vertical
+coordinates are fixed in time, but the seawater can move up and down across the
+$z_0$ surface (in other words, the top of the ocean in not a rigid lid).
+
+Note that settings: \np{ln\_zco}, \np{ln\_zps}, \np{ln\_sco} and \np{ln\_isfcav} mentioned
+in the following sections appear to be namelist options but they are no longer truly
+namelist options for NEMO. Their value is written to and read from the domain configuration file
+and they should be treated as fixed parameters for a particular configuration. They are
+namelist options for the \forcode{DOMAINcfg} tool that can be used to build the
+configuration file and serve both to provide a record of the choices made whilst building the
+configuration and to trigger appropriate code blocks within NEMO.
+These values should not be altered in the \np{cn\_domcfg} file.
+
+\medskip
+The decision on these choices must be made when the \np{cn\_domcfg} file is constructed.
+Three main choices are offered (\autoref{fig:z_zps_s_sps}a-c):
+
 \begin{itemize}
-\item
-  \np{ppacr}~$= h_{cr}$: stretching factor (nondimensional).
-  The larger \np{ppacr}, the smaller the stretching.
-  Values from $3$ to $10$ are usual.
-\item
-  \np{ppkth}~$= h_{th}$: is approximately the model level at which maximum stretching occurs
-  (nondimensional, usually of order 1/2 or 2/3 of \jp{jpk})
-\item
-  \np{ppdzmin}: minimum thickness for the top layer (in meters).
-\item
-  \np{pphmax}: total depth of the ocean (meters).
+\item $z$-coordinate with full step bathymetry (\np{ln\_zco}\forcode{ = .true.}),
+\item $z$-coordinate with partial step ($zps$) bathymetry (\np{ln\_zps}\forcode{ = .true.}),
+\item Generalized, $s$-coordinate (\np{ln\_sco}\forcode{ = .true.}).
 \end{itemize}
-As an example, for the $45$ layers used in the DRAKKAR configuration those parameters are:
-\jp{jpk}~$= 46$, \np{ppacr}~$= 9$, \np{ppkth}~$= 23.563$, \np{ppdzmin}~$= 6~m$, \np{pphmax}~$= 5750~m$.
-
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-\begin{table}
-  \begin{center}
-    \begin{tabular}{c||r|r|r|r}
-      \hline
-      \textbf{LEVEL} & \textbf{gdept\_1d} & \textbf{gdepw\_1d} & \textbf{e3t\_1d } & \textbf{e3w\_1d} \\
-      \hline
-      1              & \textbf{     5.00} &               0.00 & \textbf{   10.00} &            10.00 \\
-      \hline
-      2              & \textbf{    15.00} &	            10.00 & \textbf{   10.00} &            10.00 \\
-      \hline
-      3              & \textbf{    25.00} &              20.00 & \textbf{   10.00} &            10.00 \\
-      \hline
-      4              & \textbf{    35.01} &	            30.00 & \textbf{   10.01} &            10.00 \\
-      \hline
-      5              & \textbf{    45.01} &              40.01 & \textbf{   10.01} &            10.01 \\
-      \hline
-      6              & \textbf{    55.03} &              50.02 & \textbf{   10.02} &            10.02 \\
-      \hline
-      7              & \textbf{    65.06} &              60.04 & \textbf{   10.04} &            10.03 \\
-      \hline
-      8              & \textbf{    75.13} &              70.09 & \textbf{   10.09} &            10.06 \\
-      \hline
-      9              & \textbf{    85.25} &              80.18 & \textbf{   10.17} &            10.12 \\
-      \hline
-      10             & \textbf{    95.49} &              90.35 & \textbf{   10.33} &            10.24 \\
-      \hline
-      11             & \textbf{   105.97} &             100.69 & \textbf{   10.65} &            10.47 \\
-      \hline
-      12             & \textbf{   116.90} &             111.36 & \textbf{   11.27} &            10.91 \\
-      \hline
-      13             & \textbf{   128.70} &             122.65 & \textbf{   12.47} &            11.77 \\
-      \hline
-      14             & \textbf{   142.20} &             135.16 & \textbf{   14.78} &            13.43 \\
-      \hline
-      15             & \textbf{   158.96} &             150.03 & \textbf{   19.23} &            16.65 \\
-      \hline
-      16             & \textbf{   181.96} &             169.42 & \textbf{   27.66} &            22.78 \\
-      \hline
-      17             & \textbf{   216.65} &             197.37 & \textbf{   43.26} &            34.30 \\
-      \hline
-      18             & \textbf{   272.48} &             241.13 & \textbf{   70.88} &            55.21 \\
-      \hline
-      19             & \textbf{   364.30} &             312.74 & \textbf{  116.11} &            90.99 \\
-      \hline
-      20             & \textbf{   511.53} &             429.72 & \textbf{  181.55} &           146.43 \\
-      \hline
-      21             & \textbf{   732.20} &             611.89 & \textbf{  261.03} &           220.35 \\
-      \hline
-      22             & \textbf{  1033.22} &             872.87 & \textbf{  339.39} &           301.42 \\
-      \hline
-      23             & \textbf{  1405.70} &            1211.59 & \textbf{  402.26} &           373.31 \\
-      \hline
-      24             & \textbf{  1830.89} &            1612.98 & \textbf{  444.87} &           426.00 \\
-      \hline
-      25             & \textbf{  2289.77} &            2057.13 & \textbf{  470.55} &           459.47 \\
-      \hline
-      26             & \textbf{  2768.24} &            2527.22 & \textbf{  484.95} &           478.83 \\
-      \hline
-      27             & \textbf{  3257.48} &            3011.90 & \textbf{  492.70} &           489.44 \\
-      \hline
-      28             & \textbf{  3752.44} &            3504.46 & \textbf{  496.78} &           495.07 \\
-      \hline
-      29             & \textbf{  4250.40} &            4001.16 & \textbf{  498.90} &           498.02 \\
-      \hline
-      30             & \textbf{  4749.91} &            4500.02 & \textbf{  500.00} &           499.54 \\
-      \hline
-      31             & \textbf{  5250.23} &            5000.00 & \textbf{  500.56} &           500.33 \\
-      \hline
-    \end{tabular}
-  \end{center}
-  \caption{
-    \protect\label{tab:orca_zgr}
-    Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration as computed from
-    \autoref{eq:DOM_zgr_ana_2} using the coefficients given in \autoref{eq:DOM_zgr_coef}
-  }
-\end{table}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-
-% -------------------------------------------------------------------------------------------------------------
-%        z-coordinate with partial step
-% -------------------------------------------------------------------------------------------------------------
-\subsection{$Z$-coordinate with partial step (\protect\np{ln\_zps}~\forcode{= .true.})}
-\label{subsec:DOM_zps}
-%--------------------------------------------namdom-------------------------------------------------------
-
-\nlst{namdom} 
-%--------------------------------------------------------------------------------------------------------------
-
-In $z$-coordinate partial step,
-the depths of the model levels are defined by the reference analytical function $z_0(k)$ as described in
-the previous section, \textit{except} in the bottom layer.
-The thickness of the bottom layer is allowed to vary as a function of geographical location $(\lambda,\varphi)$ to
-allow a better representation of the bathymetry, especially in the case of small slopes
-(where the bathymetry varies by less than one level thickness from one grid point to the next).
-The reference layer thicknesses $e_{3t}^0$ have been defined in the absence of bathymetry.
-With partial steps, layers from 1 to \jp{jpk}-2 can have a thickness smaller than $e_{3t}(jk)$.
-The model deepest layer (\jp{jpk}-1) is allowed to have either a smaller or larger thickness than $e_{3t}(jpk)$:
-the maximum thickness allowed is $2*e_{3t}(jpk - 1)$.
-This has to be kept in mind when specifying values in \ngn{namdom} namelist,
-as the maximum depth \np{pphmax} in partial steps:
-for example, with \np{pphmax}~$= 5750~m$ for the DRAKKAR 45 layer grid,
-the maximum ocean depth allowed is actually $6000~m$ (the default thickness $e_{3t}(jpk - 1)$ being $250~m$).
-Two variables in the namdom namelist are used to define the partial step vertical grid.
-The mimimum water thickness (in meters) allowed for a cell partially filled with bathymetry at level jk is
-the minimum of \np{rn\_e3zps\_min} (thickness in meters, usually $20~m$) or $e_{3t}(jk)*$\np{rn\_e3zps\_rat}
-(a fraction, usually 10\%, of the default thickness $e_{3t}(jk)$).
-
-\gmcomment{ \colorbox{yellow}{Add a figure here of pstep especially at last ocean level }  }
-
-% -------------------------------------------------------------------------------------------------------------
-%        s-coordinate
-% -------------------------------------------------------------------------------------------------------------
-\subsection{$S$-coordinate (\protect\np{ln\_sco}~\forcode{= .true.})}
-\label{subsec:DOM_sco}
-%------------------------------------------nam_zgr_sco---------------------------------------------------
-%
-%\nlst{namzgr_sco} 
-%--------------------------------------------------------------------------------------------------------------
-Options are defined in \ngn{namzgr\_sco}.
-In $s$-coordinate (\np{ln\_sco}~\forcode{= .true.}), the depth and thickness of the model levels are defined from
-the product of a depth field and either a stretching function or its derivative, respectively:
-
-\begin{align*}
-  % \label{eq:DOM_sco_ana}
-  z(k)   &= h(i,j) \; z_0 (k) \\
-  e_3(k) &= h(i,j) \; z_0'(k)
-\end{align*}
-
-where $h$ is the depth of the last $w$-level ($z_0(k)$) defined at the $t$-point location in the horizontal and
-$z_0(k)$ is a function which varies from $0$ at the sea surface to $1$ at the ocean bottom.
-The depth field $h$ is not necessary the ocean depth,
-since a mixed step-like and bottom-following representation of the topography can be used
-(\autoref{fig:z_zps_s_sps}) or an envelop bathymetry can be defined (\autoref{fig:z_zps_s_sps}).
-The namelist parameter \np{rn\_rmax} determines the slope at which
-the terrain-following coordinate intersects the sea bed and becomes a pseudo z-coordinate.
-The coordinate can also be hybridised by specifying \np{rn\_sbot\_min} and \np{rn\_sbot\_max} as
-the minimum and maximum depths at which the terrain-following vertical coordinate is calculated.
-
-Options for stretching the coordinate are provided as examples,
-but care must be taken to ensure that the vertical stretch used is appropriate for the application.
-
-The original default NEMO s-coordinate stretching is available if neither of the other options are specified as true
-(\np{ln\_s\_SH94}~\forcode{= .false.} and \np{ln\_s\_SF12}~\forcode{= .false.}).
-This uses a depth independent $\tanh$ function for the stretching \citep{Madec_al_JPO96}:
-
-\[
-  z = s_{min} + C (s) (H - s_{min})
-  % \label{eq:SH94_1}
-\]
-
-where $s_{min}$ is the depth at which the $s$-coordinate stretching starts and
-allows a $z$-coordinate to placed on top of the stretched coordinate,
-and $z$ is the depth (negative down from the asea surface).
-\begin{gather*}
-  s = - \frac{k}{n - 1} \quad \text{and} \quad 0 \leq k \leq n - 1
-  % \label{eq:DOM_s}
- \\
-  % \label{eq:DOM_sco_function}
-  C(s) = \frac{[\tanh(\theta \, (s + b)) - \tanh(\theta \, b)]}{2 \; \sinh(\theta)}
-\end{gather*}
-
-A stretching function,
-modified from the commonly used \citet{Song_Haidvogel_JCP94} stretching (\np{ln\_s\_SH94}~\forcode{= .true.}),
-is also available and is more commonly used for shelf seas modelling:
-
-\[
-  C(s) =   (1 - b) \frac{\sinh(\theta s)}{\sinh(\theta)}
-         + b       \frac{\tanh \lt[ \theta \lt(s + \frac{1}{2} \rt) \rt] -   \tanh \lt( \frac{\theta}{2} \rt)}
-                        {                                                  2 \tanh \lt( \frac{\theta}{2} \rt)}
-  % \label{eq:SH94_2}
-\]
-
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-\begin{figure}[!ht]
-  \begin{center}
-    \includegraphics[]{Fig_sco_function}
-    \caption{
-      \protect\label{fig:sco_function}
-      Examples of the stretching function applied to a seamount;
-      from left to right: surface, surface and bottom, and bottom intensified resolutions
-    }
-  \end{center}
-\end{figure}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-
-where $H_c$ is the critical depth (\np{rn\_hc}) at which the coordinate transitions from pure $\sigma$ to
-the stretched coordinate, and $\theta$ (\np{rn\_theta}) and $b$ (\np{rn\_bb}) are the surface and
-bottom control parameters such that $0 \leqslant \theta \leqslant 20$, and $0 \leqslant b \leqslant 1$.
-$b$ has been designed to allow surface and/or bottom increase of the vertical resolution
-(\autoref{fig:sco_function}).
-
-Another example has been provided at version 3.5 (\np{ln\_s\_SF12}) that allows a fixed surface resolution in
-an analytical terrain-following stretching \citet{Siddorn_Furner_OM12}.
-In this case the a stretching function $\gamma$ is defined such that:
-
-\begin{equation}
-  z = - \gamma h \quad \text{with} \quad 0 \leq \gamma \leq 1
-  % \label{eq:z}
-\end{equation}
-
-The function is defined with respect to $\sigma$, the unstretched terrain-following coordinate:
-
-\begin{gather*}
-  % \label{eq:DOM_gamma_deriv}
-  \gamma =   A \lt( \sigma   - \frac{1}{2} (\sigma^2     + f (\sigma)) \rt)
-           + B \lt( \sigma^3 - f           (\sigma) \rt) + f (\sigma)       \\
-  \intertext{Where:}
-  % \label{eq:DOM_gamma}
-  f(\sigma) = (\alpha + 2) \sigma^{\alpha + 1} - (\alpha + 1) \sigma^{\alpha + 2}
-  \quad \text{and} \quad \sigma = \frac{k}{n - 1}
-\end{gather*}
-
-This gives an analytical stretching of $\sigma$ that is solvable in $A$ and $B$ as a function of
-the user prescribed stretching parameter $\alpha$ (\np{rn\_alpha}) that stretches towards
-the surface ($\alpha > 1.0$) or the bottom ($\alpha < 1.0$) and
-user prescribed surface (\np{rn\_zs}) and bottom depths.
-The bottom cell depth in this example is given as a function of water depth:
-
-\[
-  % \label{eq:DOM_zb}
-  Z_b = h a + b
-\]
-
-where the namelist parameters \np{rn\_zb\_a} and \np{rn\_zb\_b} are $a$ and $b$ respectively.
-
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-\begin{figure}[!ht]
-  \includegraphics[]{Fig_DOM_compare_coordinates_surface}
-  \caption{
-    A comparison of the \citet{Song_Haidvogel_JCP94} $S$-coordinate (solid lines),
-    a 50 level $Z$-coordinate (contoured surfaces) and
-    the \citet{Siddorn_Furner_OM12} $S$-coordinate (dashed lines) in the surface $100~m$ for
-    a idealised bathymetry that goes from $50~m$ to $5500~m$ depth.
-    For clarity every third coordinate surface is shown.
-  }
-  \label{fig:fig_compare_coordinates_surface}
-\end{figure}
- % >>>>>>>>>>>>>>>>>>>>>>>>>>>>
-
-This gives a smooth analytical stretching in computational space that is constrained to
-given specified surface and bottom grid cell thicknesses in real space.
-This is not to be confused with the hybrid schemes that
-superimpose geopotential coordinates on terrain following coordinates thus
-creating a non-analytical vertical coordinate that
-therefore may suffer from large gradients in the vertical resolutions.
-This stretching is less straightforward to implement than the \citet{Song_Haidvogel_JCP94} stretching,
-but has the advantage of resolving diurnal processes in deep water and has generally flatter slopes.
-
-As with the \citet{Song_Haidvogel_JCP94} stretching the stretch is only applied at depths greater than
-the critical depth $h_c$.
-In this example two options are available in depths shallower than $h_c$,
-with pure sigma being applied if the \np{ln\_sigcrit} is true and pure z-coordinates if it is false
-(the z-coordinate being equal to the depths of the stretched coordinate at $h_c$).
-
-Minimising the horizontal slope of the vertical coordinate is important in terrain-following systems as
-large slopes lead to hydrostatic consistency.
-A hydrostatic consistency parameter diagnostic following \citet{Haney1991} has been implemented,
-and is output as part of the model mesh file at the start of the run.
-
-% -------------------------------------------------------------------------------------------------------------
-%        z*- or s*-coordinate
-% -------------------------------------------------------------------------------------------------------------
-\subsection{\zstar- or \sstar-coordinate (\protect\np{ln\_linssh}~\forcode{= .false.})}
-\label{subsec:DOM_zgr_star}
-
-This option is described in the Report by Levier \textit{et al.} (2007), available on the \NEMO web site.
-
-%gm% key advantage: minimise the diffusion/dispertion associated with advection in response to high frequency surface disturbances
+
+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).
+
+A further choice related to vertical coordinate concerns the presence (or not) of ocean
+cavities beneath ice shelves within the model domain.  A setting of \np{ln\_isfcav} as
+\forcode{.true.} indicates that the domain contains  ocean cavities, otherwise the top,
+wet layer of the ocean will always be at the ocean surface.  This option is currently only
+available for $z$- or $zps$-coordinates. In the latter case, partial steps are also applied
+at the ocean/ice shelf interface.
+
+Within the model, the arrays describing the grid point depths and vertical scale factors
+are three set of three dimensional arrays $(i,j,k)$ defined at \textit{before},
+\textit{now} and \textit{after} time step.  The time at which they are defined is
+indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively.  They are updated at each
+model time step. The initial fixed reference coordinate system is held in variable names
+with a $\_0$ suffix.  When the linear free surface option is used
+(\np{ln\_linssh}\forcode{ = .true.}), \textit{before}, \textit{now} and \textit{after}
+arrays are initially set to their reference counterpart and remain fixed.
+
+\subsubsection{Required fields}
+\label{sec:DOM_zgr_fields}
+The explicit specification of a range of fields related to the vertical grid are required for the definition of a configuration. These include:
+
+\begin{Verbatim}[fontsize=\tiny]
+int    ln_zco, ln_zps, ln_sco            /* flags for z-coord, z-coord with partial steps and s-coord    */
+int    ln_isfcav                         /* flag  for ice shelf cavities                                 */
+double e3t_1d, e3w_1d                    /* reference vertical scale factors at T and W points           */
+double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0 /* vertical scale factors 3D coordinate at T,U,V,F and W points */
+double e3uw_0, e3vw_0                    /* vertical scale factors 3D coordinate at UW and VW points     */
+int    bottom_level, top_level           /* last wet T-points, 1st wet T-points (for ice shelf cavities) */
+                                         /* For reference:                                               */
+float  bathy_metry                       /* bathymetry used in setting top and bottom levels             */
+\end{Verbatim}
+
+This set of vertical metrics is sufficient to describe the initial depth and thickness of
+every gridcell in the model regardless of the choice of vertical coordinate. With constant
+z-levels, e3 metrics will be uniform across each horizontal level. In the partial step
+case each e3 at the \np{bottom\_level} (and, possibly, \np{top\_level} if ice cavities are
+present) may vary from its horizontal neighbours. And, in s-coordinates, variations can
+occur throughout the water column. With the non-linear free-surface, all the coordinates
+behave more like the s-coordinate in that variations occurr throughout the water column
+with displacements related to the sea surface height. These variations are typically much
+smaller than those arising from bottom fitted coordinates. The values for vertical metrics
+supplied in the domain configuration file can be considered as those arising from a flat
+sea surface with zero elevation.
+
+The \np{bottom\_level} and \np{top\_level} 2D arrays define the \np{bottom\_level} and top
+wet levels in each grid column. Without ice cavities, \np{top\_level} is essentially a land
+mask (0 on land; 1 everywhere else). With ice cavities, \np{top\_level} determines the
+first wet point below the overlying ice shelf.
+
+
 
 % -------------------------------------------------------------------------------------------------------------
 %        level bathymetry and mask 
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Level bathymetry and mask}
+\subsubsection{Level bathymetry and mask}
 \label{subsec:DOM_msk}
 
-Whatever the vertical coordinate used, the model offers the possibility of representing the bottom topography with
-steps that follow the face of the model cells (step like topography) \citep{Madec_al_JPO96}.
-The distribution of the steps in the horizontal is defined in a 2D integer array, mbathy, which
-gives the number of ocean levels (\ie those that are not masked) at each $t$-point.
-mbathy is computed from the meter bathymetry using the definiton of gdept as the number of $t$-points which
-gdept $\leq$ bathy.
-
-Modifications of the model bathymetry are performed in the \textit{bat\_ctl} routine (see \mdl{domzgr} module) after
-mbathy is computed.
-Isolated grid points that do not communicate with another ocean point at the same level are eliminated.
-
-As for the representation of bathymetry, a 2D integer array, misfdep, is created.
-misfdep defines the level of the first wet $t$-point.
-All the cells between $k = 1$ and $misfdep(i,j) - 1$ are masked.
-By default, $misfdep(:,:) = 1$ and no cells are masked.
-
-In case of ice shelf cavities, modifications of the model bathymetry and ice shelf draft into 
-the cavities are performed in the \textit{zgr\_isf} routine.
-The compatibility between ice shelf draft and bathymetry is checked.
-All the locations where the isf cavity is thinnest than \np{rn\_isfhmin} meters are grounded (\ie masked).
-If only one cell on the water column is opened at $t$-, $u$- or $v$-points,
-the bathymetry or the ice shelf draft is dug to fit this constrain.
-If the incompatibility is too strong (need to dig more than 1 cell), the cell is masked.
-
-From the \textit{mbathy} and \textit{misfdep} array, the mask fields are defined as follows:
+
+From \np{top\_level} and \np{bottom\_level} fields, the mask fields are defined as follows:
 \begin{alignat*}{2}
   tmask(i,j,k) &= &  &
     \begin{cases}
-                  0 &\text{if $                  k  <    misfdep(i,j)$} \\
-                  1 &\text{if $misfdep(i,j) \leq k \leq   mbathy(i,j)$} \\
-                  0 &\text{if $                  k  >     mbathy(i,j)$}
+                  0 &\text{if $                  k  <    top\_level(i,j)$} \\
+                  1 &\text{if $bottom\_level(i,j) \leq k \leq   top\_level(i,j)$} \\
+                  0 &\text{if $                  k  >     bottom\_level(i,j)$}
     \end{cases}
   \\
@@ -1005,34 +606,80 @@
 exactly in the same way as for the bottom boundary.
 
-The specification of closed lateral boundaries requires that at least
-the first and last rows and columns of the \textit{mbathy} array are set to zero.
-In the particular case of an east-west cyclical boundary condition, \textit{mbathy} has its last column equal to
-the second one and its first column equal to the last but one (and so too the mask arrays)
-(see \autoref{fig:LBC_jperio}).
+%% The specification of closed lateral boundaries requires that at least
+%% the first and last rows and columns of the \textit{mbathy} array are set to zero.
+%% In the particular case of an east-west cyclical boundary condition, \textit{mbathy} has its last column equal to
+%% the second one and its first column equal to the last but one (and so too the mask arrays)
+%% (see \autoref{fig:LBC_jperio}).
+
+
+%-------------------------------------------------------------------------------------------------
+%        Closed seas 
+%-------------------------------------------------------------------------------------------------
+\subsection{Closed seas} \label{subsec:DOM_closea} 
+
+When a global ocean is coupled to an atmospheric model it is better to represent all large
+water bodies (\eg great lakes, Caspian sea...) even if the model resolution does not allow
+their communication with the rest of the ocean.  This is unnecessary when the ocean is
+forced by fixed atmospheric conditions, so these seas can be removed from the ocean
+domain.  The user has the option to set the bathymetry in closed seas to zero (see
+\autoref{sec:MISC_closea}) and to optionally decide on the fate of any freshwater
+imbalance over the area. The options are explained in \autoref{sec:MISC_closea} but it
+should be noted here that a successful use of these options requires appropriate mask
+fields to be present in the domain configuration file. Among the possibilities are:
+
+\begin{Verbatim}[fontsize=\tiny]
+int    closea_mask          /* non-zero values in closed sea areas for optional masking                  */
+int    closea_mask_rnf      /* non-zero values in closed sea areas with runoff locations (precip only)   */
+int    closea_mask_emp      /* non-zero values in closed sea areas with runoff locations (total emp)     */
+\end{Verbatim}
+
+% -------------------------------------------------------------------------------------------------------------
+%        Grid files
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Output grid files}
+\label{subsec:DOM_meshmask}
+
+\nlst{namcfg}
+
+Most of the arrays relating to a particular ocean model configuration dicussed in this
+chapter (grid-point position, scale factors) can be saved in a file if namelist parameter
+\np{ln\_write\_cfg} (namelist \ngn{namcfg}) is set to \forcode{.true.}; the output
+filename is set thorugh parameter \np{cn\_domcfg\_out}. This is only really useful
+if the fields are computed in subroutines \mdl{usrdef\_hgr} or \mdl{usrdef\_zgr} and
+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 \ngn{namdom}) is set
+to \forcode{.true.}. This file contains additional fields that can be useful for
+post-processing applications
 
 % ================================================================
 % Domain: Initial State (dtatsd & istate)
 % ================================================================
-\section{Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})}
+\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} 
 %------------------------------------------------------------------------------------------
 
-Options are defined in \ngn{namtsd}.
-By default, the ocean start from rest (the velocity field is set to zero) and the initialization of temperature and
-salinity fields is controlled through the \np{ln\_tsd\_ini} namelist parameter.
+Basic initial state options are defined in \ngn{namtsd}.  By default, the ocean starts
+from rest (the velocity field is set to zero) and the initialization of temperature and
+salinity fields is controlled through the \np{ln\_tsd\_init} namelist parameter.
+
 \begin{description}
-\item[\np{ln\_tsd\_init}~\forcode{= .true.}]
-  use a T and S input files that can be given on the model grid itself or on their native input data grid.
-  In the latter case,
-  the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid
-  (see \autoref{subsec:SBC_iof}).
-  The information relative to the input files are given in the \np{sn\_tem} and \np{sn\_sal} structures.
-  The computation is done in the \mdl{dtatsd} module.
-\item[\np{ln\_tsd\_init}~\forcode{= .false.}]
-  use constant salinity value of $35.5~psu$ and an analytical profile of temperature
-  (typical of the tropical ocean), see \rou{istate\_t\_s} subroutine called from \mdl{istate} module.
+\item[\np{ln\_tsd\_init}\forcode{= .true.}]
+  Use T and S input files that can be given on the model grid itself or on their native
+  input data grids.  In the latter case, the data will be interpolated on-the-fly both in
+  the horizontal and the vertical to the model grid (see \autoref{subsec:SBC_iof}).  The
+  information relating to the input files are specified in the \np{sn\_tem} and
+  \np{sn\_sal} structures.  The computation is done in the \mdl{dtatsd} module.
+\item[\np{ln\_tsd\_init}\forcode{= .false.}]
+  Initial values for T and S are set via a user supplied \rou{usr\_def\_istate} routine
+  contained in \mdl{userdef\_istate}. The default version sets horizontally uniform T and
+  profiles as used in the  GYRE configuration (see \autoref{sec:CFG_gyre}).
 \end{description}
 
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DYN.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DYN.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DYN.tex	(revision 11422)
@@ -65,5 +65,6 @@
 %           Horizontal divergence and relative vorticity
 %--------------------------------------------------------------------------------------------------------------
-\subsection{Horizontal divergence and relative vorticity (\protect\mdl{divcur})}
+\subsection[Horizontal divergence and relative vorticity (\textit{divcur.F90})]
+{Horizontal divergence and relative vorticity (\protect\mdl{divcur})}
 \label{subsec:DYN_divcur}
 
@@ -101,5 +102,6 @@
 %           Sea Surface Height evolution
 %--------------------------------------------------------------------------------------------------------------
-\subsection{Horizontal divergence and relative vorticity (\protect\mdl{sshwzv})}
+\subsection[Horizontal divergence and relative vorticity (\textit{sshwzv.F90})]
+{Horizontal divergence and relative vorticity (\protect\mdl{sshwzv})}
 \label{subsec:DYN_sshwzv}
 
@@ -127,5 +129,5 @@
 Replacing $T$ by the number $1$ in the tracer equation and summing over the water column must lead to
 the sea surface height equation otherwise tracer content will not be conserved
-\citep{Griffies_al_MWR01, Leclair_Madec_OM09}.
+\citep{griffies.pacanowski.ea_MWR01, leclair.madec_OM09}.
 
 The vertical velocity is computed by an upward integration of the horizontal divergence starting at the bottom,
@@ -181,5 +183,6 @@
 %        Vorticity term 
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Vorticity term (\protect\mdl{dynvor})}
+\subsection[Vorticity term (\textit{dynvor.F90})]
+{Vorticity term (\protect\mdl{dynvor})}
 \label{subsec:DYN_vor}
 %------------------------------------------nam_dynvor----------------------------------------------------
@@ -203,5 +206,6 @@
 %                 enstrophy conserving scheme
 %-------------------------------------------------------------
-\subsubsection{Enstrophy conserving scheme (\protect\np{ln\_dynvor\_ens}\forcode{ = .true.})}
+\subsubsection[Enstrophy conserving scheme (\forcode{ln_dynvor_ens = .true.})]
+{Enstrophy conserving scheme (\protect\np{ln\_dynvor\_ens}\forcode{ = .true.})}
 \label{subsec:DYN_vor_ens}
 
@@ -226,5 +230,6 @@
 %                 energy conserving scheme
 %-------------------------------------------------------------
-\subsubsection{Energy conserving scheme (\protect\np{ln\_dynvor\_ene}\forcode{ = .true.})}
+\subsubsection[Energy conserving scheme (\forcode{ln_dynvor_ene = .true.})]
+{Energy conserving scheme (\protect\np{ln\_dynvor\_ene}\forcode{ = .true.})}
 \label{subsec:DYN_vor_ene}
 
@@ -246,5 +251,6 @@
 %                 mix energy/enstrophy conserving scheme
 %-------------------------------------------------------------
-\subsubsection{Mixed energy/enstrophy conserving scheme (\protect\np{ln\_dynvor\_mix}\forcode{ = .true.}) }
+\subsubsection[Mixed energy/enstrophy conserving scheme (\forcode{ln_dynvor_mix = .true.})]
+{Mixed energy/enstrophy conserving scheme (\protect\np{ln\_dynvor\_mix}\forcode{ = .true.})}
 \label{subsec:DYN_vor_mix}
 
@@ -271,5 +277,6 @@
 %                 energy and enstrophy conserving scheme
 %-------------------------------------------------------------
-\subsubsection{Energy and enstrophy conserving scheme (\protect\np{ln\_dynvor\_een}\forcode{ = .true.}) }
+\subsubsection[Energy and enstrophy conserving scheme (\forcode{ln_dynvor_een = .true.})]
+{Energy and enstrophy conserving scheme (\protect\np{ln\_dynvor\_een}\forcode{ = .true.})}
 \label{subsec:DYN_vor_een}
 
@@ -287,11 +294,11 @@
 Nevertheless, this technique strongly distort the phase and group velocity of Rossby waves....}
 
-A very nice solution to the problem of double averaging was proposed by \citet{Arakawa_Hsu_MWR90}.
+A very nice solution to the problem of double averaging was proposed by \citet{arakawa.hsu_MWR90}.
 The idea is to get rid of the double averaging by considering triad combinations of vorticity.
 It is noteworthy that this solution is conceptually quite similar to the one proposed by
-\citep{Griffies_al_JPO98} for the discretization of the iso-neutral diffusion operator (see \autoref{apdx:C}).
-
-The \citet{Arakawa_Hsu_MWR90} vorticity advection scheme for a single layer is modified 
-for spherical coordinates as described by \citet{Arakawa_Lamb_MWR81} to obtain the EEN scheme. 
+\citep{griffies.gnanadesikan.ea_JPO98} for the discretization of the iso-neutral diffusion operator (see \autoref{apdx:C}).
+
+The \citet{arakawa.hsu_MWR90} vorticity advection scheme for a single layer is modified 
+for spherical coordinates as described by \citet{arakawa.lamb_MWR81} to obtain the EEN scheme. 
 First consider the discrete expression of the potential vorticity, $q$, defined at an $f$-point: 
 \[
@@ -309,5 +316,5 @@
 \begin{figure}[!ht]
   \begin{center}
-    \includegraphics[width=0.70\textwidth]{Fig_DYN_een_triad}
+    \includegraphics[width=\textwidth]{Fig_DYN_een_triad}
     \caption{
       \protect\label{fig:DYN_een_triad}
@@ -327,5 +334,5 @@
 (with a systematic reduction of $e_{3f}$ when a model level intercept the bathymetry)
 that tends to reinforce the topostrophy of the flow
-(\ie the tendency of the flow to follow the isobaths) \citep{Penduff_al_OS07}. 
+(\ie the tendency of the flow to follow the isobaths) \citep{penduff.le-sommer.ea_OS07}. 
 
 Next, the vorticity triads, $ {^i_j}\mathbb{Q}^{i_p}_{j_p}$ can be defined at a $T$-point as
@@ -356,13 +363,14 @@
 (\ie $\chi$=$0$) (see \autoref{subsec:C_vorEEN}). 
 Applied to a realistic ocean configuration, it has been shown that it leads to a significant reduction of
-the noise in the vertical velocity field \citep{Le_Sommer_al_OM09}.
+the noise in the vertical velocity field \citep{le-sommer.penduff.ea_OM09}.
 Furthermore, used in combination with a partial steps representation of bottom topography,
 it improves the interaction between current and topography,
-leading to a larger topostrophy of the flow \citep{Barnier_al_OD06, Penduff_al_OS07}. 
+leading to a larger topostrophy of the flow \citep{barnier.madec.ea_OD06, penduff.le-sommer.ea_OS07}. 
 
 %--------------------------------------------------------------------------------------------------------------
 %           Kinetic Energy Gradient term
 %--------------------------------------------------------------------------------------------------------------
-\subsection{Kinetic energy gradient term (\protect\mdl{dynkeg})}
+\subsection[Kinetic energy gradient term (\textit{dynkeg.F90})]
+{Kinetic energy gradient term (\protect\mdl{dynkeg})}
 \label{subsec:DYN_keg}
 
@@ -384,5 +392,6 @@
 %           Vertical advection term
 %--------------------------------------------------------------------------------------------------------------
-\subsection{Vertical advection term (\protect\mdl{dynzad}) }
+\subsection[Vertical advection term (\textit{dynzad.F90})]
+{Vertical advection term (\protect\mdl{dynzad})}
 \label{subsec:DYN_zad}
 
@@ -403,5 +412,5 @@
 When \np{ln\_dynzad\_zts}\forcode{ = .true.},
 a split-explicit time stepping with 5 sub-timesteps is used on the vertical advection term.
-This option can be useful when the value of the timestep is limited by vertical advection \citep{Lemarie_OM2015}. 
+This option can be useful when the value of the timestep is limited by vertical advection \citep{lemarie.debreu.ea_OM15}. 
 Note that in this case,
 a similar split-explicit time stepping should be used on vertical advection of tracer to ensure a better stability,
@@ -430,5 +439,6 @@
 %           Coriolis plus curvature metric terms
 %--------------------------------------------------------------------------------------------------------------
-\subsection{Coriolis plus curvature metric terms (\protect\mdl{dynvor}) }
+\subsection[Coriolis plus curvature metric terms (\textit{dynvor.F90})]
+{Coriolis plus curvature metric terms (\protect\mdl{dynvor})}
 \label{subsec:DYN_cor_flux}
 
@@ -451,5 +461,6 @@
 %           Flux form Advection term
 %--------------------------------------------------------------------------------------------------------------
-\subsection{Flux form advection term (\protect\mdl{dynadv}) }
+\subsection[Flux form advection term (\textit{dynadv.F90})]
+{Flux form advection term (\protect\mdl{dynadv})}
 \label{subsec:DYN_adv_flux}
 
@@ -475,5 +486,5 @@
 a $2^{nd}$ order centered finite difference scheme, CEN2,
 or a $3^{rd}$ order upstream biased scheme, UBS.
-The latter is described in \citet{Shchepetkin_McWilliams_OM05}.
+The latter is described in \citet{shchepetkin.mcwilliams_OM05}.
 The schemes are selected using the namelist logicals \np{ln\_dynadv\_cen2} and \np{ln\_dynadv\_ubs}. 
 In flux form, the schemes differ by the choice of a space and time interpolation to define the value of
@@ -484,5 +495,6 @@
 %                 2nd order centred scheme
 %-------------------------------------------------------------
-\subsubsection{CEN2: $2^{nd}$ order centred scheme (\protect\np{ln\_dynadv\_cen2}\forcode{ = .true.})}
+\subsubsection[CEN2: $2^{nd}$ order centred scheme (\forcode{ln_dynadv_cen2 = .true.})]
+{CEN2: $2^{nd}$ order centred scheme (\protect\np{ln\_dynadv\_cen2}\forcode{ = .true.})}
 \label{subsec:DYN_adv_cen2}
 
@@ -507,5 +519,6 @@
 %                 UBS scheme
 %-------------------------------------------------------------
-\subsubsection{UBS: Upstream Biased Scheme (\protect\np{ln\_dynadv\_ubs}\forcode{ = .true.})}
+\subsubsection[UBS: Upstream Biased Scheme (\forcode{ln_dynadv_ubs = .true.})]
+{UBS: Upstream Biased Scheme (\protect\np{ln\_dynadv\_ubs}\forcode{ = .true.})}
 \label{subsec:DYN_adv_ubs}
 
@@ -523,6 +536,6 @@
 where $u"_{i+1/2} =\delta_{i+1/2} \left[ {\delta_i \left[ u \right]} \right]$.
 This results in a dissipatively dominant (\ie hyper-diffusive) truncation error
-\citep{Shchepetkin_McWilliams_OM05}.
-The overall performance of the advection scheme is similar to that reported in \citet{Farrow1995}.
+\citep{shchepetkin.mcwilliams_OM05}.
+The overall performance of the advection scheme is similar to that reported in \citet{farrow.stevens_JPO95}.
 It is a relatively good compromise between accuracy and smoothness.
 It is not a \emph{positive} scheme, meaning that false extrema are permitted.
@@ -542,9 +555,9 @@
 while the second term, which is the diffusion part of the scheme,
 is evaluated using the \textit{before} velocity (forward in time).
-This is discussed by \citet{Webb_al_JAOT98} in the context of the Quick advection scheme.
+This is discussed by \citet{webb.de-cuevas.ea_JAOT98} in the context of the Quick advection scheme.
 
 Note that the UBS and QUICK (Quadratic Upstream Interpolation for Convective Kinematics) schemes only differ by
 one coefficient.
-Replacing $1/6$ by $1/8$ in (\autoref{eq:dynadv_ubs}) leads to the QUICK advection scheme \citep{Webb_al_JAOT98}.
+Replacing $1/6$ by $1/8$ in (\autoref{eq:dynadv_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.
@@ -560,5 +573,6 @@
 %           Hydrostatic pressure gradient term
 % ================================================================
-\section{Hydrostatic pressure gradient (\protect\mdl{dynhpg})}
+\section[Hydrostatic pressure gradient (\textit{dynhpg.F90})]
+{Hydrostatic pressure gradient (\protect\mdl{dynhpg})}
 \label{sec:DYN_hpg}
 %------------------------------------------nam_dynhpg---------------------------------------------------
@@ -582,5 +596,6 @@
 %           z-coordinate with full step
 %--------------------------------------------------------------------------------------------------------------
-\subsection{Full step $Z$-coordinate (\protect\np{ln\_dynhpg\_zco}\forcode{ = .true.})}
+\subsection[Full step $Z$-coordinate (\forcode{ln_dynhpg_zco = .true.})]
+{Full step $Z$-coordinate (\protect\np{ln\_dynhpg\_zco}\forcode{ = .true.})}
 \label{subsec:DYN_hpg_zco}
 
@@ -627,5 +642,6 @@
 %           z-coordinate with partial step
 %--------------------------------------------------------------------------------------------------------------
-\subsection{Partial step $Z$-coordinate (\protect\np{ln\_dynhpg\_zps}\forcode{ = .true.})}
+\subsection[Partial step $Z$-coordinate (\forcode{ln_dynhpg_zps = .true.})]
+{Partial step $Z$-coordinate (\protect\np{ln\_dynhpg\_zps}\forcode{ = .true.})}
 \label{subsec:DYN_hpg_zps}
 
@@ -652,9 +668,9 @@
 
 Pressure gradient formulations in an $s$-coordinate have been the subject of a vast number of papers
-(\eg, \citet{Song1998, Shchepetkin_McWilliams_OM05}). 
+(\eg, \citet{song_MWR98, shchepetkin.mcwilliams_OM05}). 
 A number of different pressure gradient options are coded but the ROMS-like,
 density Jacobian with cubic polynomial method is currently disabled whilst known bugs are under investigation.
 
-$\bullet$ Traditional coding (see for example \citet{Madec_al_JPO96}: (\np{ln\_dynhpg\_sco}\forcode{ = .true.})
+$\bullet$ Traditional coding (see for example \citet{madec.delecluse.ea_JPO96}: (\np{ln\_dynhpg\_sco}\forcode{ = .true.})
 \begin{equation}
   \label{eq:dynhpg_sco}
@@ -679,10 +695,10 @@
 $\bullet$ Pressure Jacobian scheme (prj) (a research paper in preparation) (\np{ln\_dynhpg\_prj}\forcode{ = .true.})
 
-$\bullet$ Density Jacobian with cubic polynomial scheme (DJC) \citep{Shchepetkin_McWilliams_OM05} 
+$\bullet$ Density Jacobian with cubic polynomial scheme (DJC) \citep{shchepetkin.mcwilliams_OM05} 
 (\np{ln\_dynhpg\_djc}\forcode{ = .true.}) (currently disabled; under development)
 
 Note that expression \autoref{eq:dynhpg_sco} is commonly used when the variable volume formulation is activated
 (\key{vvl}) because in that case, even with a flat bottom,
-the coordinate surfaces are not horizontal but follow the free surface \citep{Levier2007}.
+the coordinate surfaces are not horizontal but follow the free surface \citep{levier.treguier.ea_rpt07}.
 The pressure jacobian scheme (\np{ln\_dynhpg\_prj}\forcode{ = .true.}) is available as
 an improved option to \np{ln\_dynhpg\_sco}\forcode{ = .true.} when \key{vvl} is active.
@@ -704,5 +720,5 @@
 corresponds to the water replaced by the ice shelf.
 This top pressure is constant over time.
-A detailed description of this method is described in \citet{Losch2008}.\\
+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
@@ -712,5 +728,6 @@
 %           Time-scheme
 %--------------------------------------------------------------------------------------------------------------
-\subsection{Time-scheme (\protect\np{ln\_dynhpg\_imp}\forcode{ = .true./.false.})}
+\subsection[Time-scheme (\forcode{ln_dynhpg_imp = .{true,false}.})]
+{Time-scheme (\protect\np{ln\_dynhpg\_imp}\forcode{ = .\{true,false\}}.)}
 \label{subsec:DYN_hpg_imp}
 
@@ -722,5 +739,5 @@
 the physical phenomenon that controls the time-step is internal gravity waves (IGWs).
 A semi-implicit scheme for doubling the stability limit associated with IGWs can be used
-\citep{Brown_Campana_MWR78, Maltrud1998}.
+\citep{brown.campana_MWR78, maltrud.smith.ea_JGR98}.
 It involves the evaluation of the hydrostatic pressure gradient as
 an average over the three time levels $t-\rdt$, $t$, and $t+\rdt$
@@ -773,5 +790,6 @@
 % Surface Pressure Gradient
 % ================================================================
-\section{Surface pressure gradient (\protect\mdl{dynspg})}
+\section[Surface pressure gradient (\textit{dynspg.F90})]
+{Surface pressure gradient (\protect\mdl{dynspg})}
 \label{sec:DYN_spg}
 %-----------------------------------------nam_dynspg----------------------------------------------------
@@ -790,5 +808,5 @@
 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:PE_flt?}), 
 and the split-explicit free surface described below.
 The extra term introduced in the filtered method is calculated implicitly, 
@@ -811,5 +829,6 @@
 % Explicit free surface formulation
 %--------------------------------------------------------------------------------------------------------------
-\subsection{Explicit free surface (\protect\key{dynspg\_exp})}
+\subsection[Explicit free surface (\texttt{\textbf{key\_dynspg\_exp}})]
+{Explicit free surface (\protect\key{dynspg\_exp})}
 \label{subsec:DYN_spg_exp}
 
@@ -837,5 +856,6 @@
 % Split-explict free surface formulation
 %--------------------------------------------------------------------------------------------------------------
-\subsection{Split-explicit free surface (\protect\key{dynspg\_ts})}
+\subsection[Split-explicit free surface (\texttt{\textbf{key\_dynspg\_ts}})]
+{Split-explicit free surface (\protect\key{dynspg\_ts})}
 \label{subsec:DYN_spg_ts}
 %------------------------------------------namsplit-----------------------------------------------------------
@@ -845,5 +865,5 @@
 
 The split-explicit free surface formulation used in \NEMO (\key{dynspg\_ts} defined),
-also called the time-splitting formulation, follows the one proposed by \citet{Shchepetkin_McWilliams_OM05}.
+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
@@ -862,21 +882,21 @@
 \begin{equation}
   \label{eq:BT_dyn}
-  \frac{\partial {\rm \overline{{\bf U}}_h} }{\partial t}=
-  -f\;{\rm {\bf k}}\times {\rm \overline{{\bf U}}_h}
-  -g\nabla _h \eta -\frac{c_b^{\textbf U}}{H+\eta} \rm {\overline{{\bf U}}_h} + \rm {\overline{\bf G}}
+  \frac{\partial {\mathrm \overline{{\mathbf U}}_h} }{\partial t}=
+  -f\;{\mathrm {\mathbf k}}\times {\mathrm \overline{{\mathbf U}}_h}
+  -g\nabla _h \eta -\frac{c_b^{\textbf U}}{H+\eta} \mathrm {\overline{{\mathbf U}}_h} + \mathrm {\overline{\mathbf G}}
 \end{equation}
 \[
   % \label{eq:BT_ssh}
-  \frac{\partial \eta }{\partial t}=-\nabla \cdot \left[ {\left( {H+\eta } \right) \; {\rm{\bf \overline{U}}}_h \,} \right]+P-E
+  \frac{\partial \eta }{\partial t}=-\nabla \cdot \left[ {\left( {H+\eta } \right) \; {\mathrm{\mathbf \overline{U}}}_h \,} \right]+P-E
 \]
 % \end{subequations}
-where $\rm {\overline{\bf G}}$ is a forcing term held constant, containing coupling term between modes,
+where $\mathrm {\overline{\mathbf G}}$ is a forcing term held constant, containing coupling term between modes,
 surface atmospheric forcing as well as slowly varying barotropic terms not explicitly computed to gain efficiency.
 The third term on the right hand side of \autoref{eq:BT_dyn} represents the bottom stress
 (see section \autoref{sec:ZDF_bfr}), explicitly accounted for at each barotropic iteration.
 Temporal discretization of the system above follows a three-time step Generalized Forward Backward algorithm
-detailed in \citet{Shchepetkin_McWilliams_OM05}.
+detailed in \citet{shchepetkin.mcwilliams_OM05}.
 AB3-AM4 coefficients used in \NEMO follow the second-order accurate,
-"multi-purpose" stability compromise as defined in \citet{Shchepetkin_McWilliams_Bk08}
+"multi-purpose" stability compromise as defined in \citet{shchepetkin.mcwilliams_ibk09}
 (see their figure 12, lower left). 
 
@@ -884,5 +904,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=0.7\textwidth]{Fig_DYN_dynspg_ts}
+    \includegraphics[width=\textwidth]{Fig_DYN_dynspg_ts}
     \caption{
       \protect\label{fig:DYN_dynspg_ts}
@@ -936,5 +956,5 @@
 and time splitting not compatible.
 Advective barotropic velocities are obtained by using a secondary set of filtering weights,
-uniquely defined from the filter coefficients used for the time averaging (\citet{Shchepetkin_McWilliams_OM05}).
+uniquely defined from the filter coefficients used for the time averaging (\citet{shchepetkin.mcwilliams_OM05}).
 Consistency between the time averaged continuity equation and the time stepping of tracers is here the key to
 obtain exact conservation.
@@ -953,5 +973,5 @@
 external gravity waves in idealized or weakly non-linear cases.
 Although the damping is lower than for the filtered free surface,
-it is still significant as shown by \citet{Levier2007} in the case of an analytical barotropic Kelvin wave.
+it is still significant as shown by \citet{levier.treguier.ea_rpt07} in the case of an analytical barotropic Kelvin wave.
 
 %>>>>>===============
@@ -1051,5 +1071,5 @@
 the leap-frog splitting mode in equation \autoref{eq:DYN_spg_ts_ssh}.
 We have tried various forms of such filtering,
-with the following method discussed in \cite{Griffies_al_MWR01} chosen due to
+with the following method discussed in \cite{griffies.pacanowski.ea_MWR01} chosen due to
 its stability and reasonably good maintenance of tracer conservation properties (see ??).
 
@@ -1081,8 +1101,9 @@
 % Filtered free surface formulation
 %--------------------------------------------------------------------------------------------------------------
-\subsection{Filtered free surface (\protect\key{dynspg\_flt})}
+\subsection[Filtered free surface (\texttt{\textbf{key\_dynspg\_flt}})]
+{Filtered free surface (\protect\key{dynspg\_flt})}
 \label{subsec:DYN_spg_fltp}
 
-The filtered formulation follows the \citet{Roullet_Madec_JGR00} implementation. 
+The filtered formulation follows the \citet{roullet.madec_JGR00} implementation. 
 The extra term introduced in the equations (see \autoref{subsec:PE_free_surface}) is solved implicitly. 
 The elliptic solvers available in the code are documented in \autoref{chap:MISC}.
@@ -1092,5 +1113,5 @@
   \[
     % \label{eq:spg_flt}
-    \frac{\partial {\rm {\bf U}}_h }{\partial t}= {\rm {\bf M}}
+    \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= {\mathrm {\mathbf M}}
     - g \nabla \left( \tilde{\rho} \ \eta \right)
     - g \ T_c \nabla \left( \widetilde{\rho} \ \partial_t \eta \right)
@@ -1098,5 +1119,5 @@
   where $T_c$, is a parameter with dimensions of time which characterizes the force,
   $\widetilde{\rho} = \rho / \rho_o$ is the dimensionless density,
-  and $\rm {\bf M}$ represents the collected contributions of the Coriolis, hydrostatic pressure gradient,
+  and $\mathrm {\mathbf M}$ represents the collected contributions of the Coriolis, hydrostatic pressure gradient,
   non-linear and viscous terms in \autoref{eq:PE_dyn}.
 }   %end gmcomment
@@ -1109,5 +1130,6 @@
 % Lateral diffusion term
 % ================================================================
-\section{Lateral diffusion term and operators (\protect\mdl{dynldf})}
+\section[Lateral diffusion term and operators (\textit{dynldf.F90})]
+{Lateral diffusion term and operators (\protect\mdl{dynldf})}
 \label{sec:DYN_ldf}
 %------------------------------------------nam_dynldf----------------------------------------------------
@@ -1143,6 +1165,6 @@
 
 % ================================================================
-\subsection[Iso-level laplacian (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})]
-				{Iso-level laplacian operator (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})}
+\subsection[Iso-level laplacian (\forcode{ln_dynldf_lap = .true.})]
+{Iso-level laplacian operator (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})}
 \label{subsec:DYN_ldf_lap}
 
@@ -1152,8 +1174,8 @@
   \left\{
     \begin{aligned}
-      D_u^{l{\rm {\bf U}}} =\frac{1}{e_{1u} }\delta_{i+1/2} \left[ {A_T^{lm}
+      D_u^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{1u} }\delta_{i+1/2} \left[ {A_T^{lm}
           \;\chi } \right]-\frac{1}{e_{2u} {\kern 1pt}e_{3u} }\delta_j \left[ 
         {A_f^{lm} \;e_{3f} \zeta } \right] \\ \\
-      D_v^{l{\rm {\bf U}}} =\frac{1}{e_{2v} }\delta_{j+1/2} \left[ {A_T^{lm}
+      D_v^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{2v} }\delta_{j+1/2} \left[ {A_T^{lm}
           \;\chi } \right]+\frac{1}{e_{1v} {\kern 1pt}e_{3v} }\delta_i \left[ 
         {A_f^{lm} \;e_{3f} \zeta } \right]
@@ -1169,6 +1191,6 @@
 %           Rotated laplacian operator
 %--------------------------------------------------------------------------------------------------------------
-\subsection[Rotated laplacian (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})]
-				{Rotated laplacian operator (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})}
+\subsection[Rotated laplacian (\forcode{ln_dynldf_iso = .true.})]
+{Rotated laplacian operator (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})}
 \label{subsec:DYN_ldf_iso}
 
@@ -1228,6 +1250,6 @@
 %           Iso-level bilaplacian operator
 %--------------------------------------------------------------------------------------------------------------
-\subsection[Iso-level bilaplacian (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})]
-				{Iso-level bilaplacian operator (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})}
+\subsection[Iso-level bilaplacian (\forcode{ln_dynldf_bilap = .true.})]
+{Iso-level bilaplacian operator (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})}
 \label{subsec:DYN_ldf_bilap}
 
@@ -1243,5 +1265,6 @@
 %           Vertical diffusion term
 % ================================================================
-\section{Vertical diffusion term (\protect\mdl{dynzdf})}
+\section[Vertical diffusion term (\textit{dynzdf.F90})]
+{Vertical diffusion term (\protect\mdl{dynzdf})}
 \label{sec:DYN_zdf}
 %----------------------------------------------namzdf------------------------------------------------------
@@ -1326,7 +1349,7 @@
 There are two main options for wetting and drying code (wd):
 (a) an iterative limiter (il) and (b) a directional limiter (dl).
-The directional limiter is based on the scheme developed by \cite{WarnerEtal13} for RO
+The directional limiter is based on the scheme developed by \cite{warner.defne.ea_CG13} for RO
 MS
-which was in turn based on ideas developed for POM by \cite{Oey06}. The iterative
+which was in turn based on ideas developed for POM by \cite{oey_OM06}. The iterative
 limiter is a new scheme.  The iterative limiter is activated by setting $\mathrm{ln\_wd\_il} = \mathrm{.true.}$
 and $\mathrm{ln\_wd\_dl} = \mathrm{.false.}$. The directional limiter is activated
@@ -1372,6 +1395,6 @@
 %   Iterative limiters
 %-----------------------------------------------------------------------------------------
-\subsection   [Directional limiter (\textit{wet\_dry})]
-         {Directional limiter (\mdl{wet\_dry})}
+\subsection[Directional limiter (\textit{wet\_dry.F90})]
+{Directional limiter (\mdl{wet\_dry})}
 \label{subsec:DYN_wd_directional_limiter}
 The principal idea of the directional limiter is that
@@ -1400,5 +1423,5 @@
 
 
-\cite{WarnerEtal13} state that in their scheme the velocity masks at the cell faces for the baroclinic
+\cite{warner.defne.ea_CG13} state that in their scheme the velocity masks at the cell faces for the baroclinic
 timesteps are set to 0 or 1 depending on whether the average of the masks over the barotropic sub-steps is respectively less than
 or greater than 0.5. That scheme does not conserve tracers in integrations started from constant tracer
@@ -1412,10 +1435,10 @@
 %-----------------------------------------------------------------------------------------
 
-\subsection   [Iterative limiter (\textit{wet\_dry})]
-         {Iterative limiter (\mdl{wet\_dry})}
+\subsection[Iterative limiter (\textit{wet\_dry.F90})]
+{Iterative limiter (\mdl{wet\_dry})}
 \label{subsec:DYN_wd_iterative_limiter}
 
-\subsubsection [Iterative flux limiter (\textit{wet\_dry})]
-         {Iterative flux limiter (\mdl{wet\_dry})}
+\subsubsection[Iterative flux limiter (\textit{wet\_dry.F90})]
+{Iterative flux limiter (\mdl{wet\_dry})}
 \label{subsubsec:DYN_wd_il_spg_limiter}
 
@@ -1494,5 +1517,5 @@
 \end{equation}
 
-Note a small tolerance ($\mathrm{rn\_wdmin2}$) has been introduced here {\it [Q: Why is
+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
 expression for the coefficient needed to multiply the outward flux at this cell in order
@@ -1522,6 +1545,6 @@
 %      Surface pressure gradients
 %----------------------------------------------------------------------------------------
-\subsubsection   [Modification of surface pressure gradients (\textit{dynhpg})]
-         {Modification of surface pressure gradients (\mdl{dynhpg})}
+\subsubsection[Modification of surface pressure gradients (\textit{dynhpg.F90})]
+{Modification of surface pressure gradients (\mdl{dynhpg})}
 \label{subsubsec:DYN_wd_il_spg}
 
@@ -1541,5 +1564,5 @@
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!ht] \begin{center}
-\includegraphics[width=0.8\textwidth]{Fig_WAD_dynhpg}
+\includegraphics[width=\textwidth]{Fig_WAD_dynhpg}
 \caption{ \label{Fig_WAD_dynhpg}
 Illustrations of the three possible combinations of the logical variables controlling the
@@ -1588,6 +1611,6 @@
 conditions.
 
-\subsubsection   [Additional considerations (\textit{usrdef\_zgr})]
-         {Additional considerations (\mdl{usrdef\_zgr})}
+\subsubsection[Additional considerations (\textit{usrdef\_zgr.F90})]
+{Additional considerations (\mdl{usrdef\_zgr})}
 \label{subsubsec:WAD_additional}
 
@@ -1603,6 +1626,6 @@
 %      The WAD test cases
 %----------------------------------------------------------------------------------------
-\subsection   [The WAD test cases (\textit{usrdef\_zgr})]
-         {The WAD test cases (\mdl{usrdef\_zgr})}
+\subsection[The WAD test cases (\textit{usrdef\_zgr.F90})]
+{The WAD test cases (\mdl{usrdef\_zgr})}
 \label{WAD_test_cases}
 
@@ -1614,5 +1637,6 @@
 % Time evolution term 
 % ================================================================
-\section{Time evolution term (\protect\mdl{dynnxt})}
+\section[Time evolution term (\textit{dynnxt.F90})]
+{Time evolution term (\protect\mdl{dynnxt})}
 \label{sec:DYN_nxt}
 
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_LBC.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_LBC.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_LBC.tex	(revision 11422)
@@ -17,5 +17,6 @@
 % Boundary Condition at the Coast
 % ================================================================
-\section{Boundary condition at the coast (\protect\np{rn\_shlat})}
+\section[Boundary condition at the coast (\texttt{rn\_shlat})]
+{Boundary condition at the coast (\protect\np{rn\_shlat})}
 \label{sec:LBC_coast}
 %--------------------------------------------nam_lbc-------------------------------------------------------
@@ -56,5 +57,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=0.90\textwidth]{Fig_LBC_uv}
+    \includegraphics[width=\textwidth]{Fig_LBC_uv}
     \caption{
       \protect\label{fig:LBC_uv}
@@ -85,5 +86,5 @@
 \begin{figure}[!p]
   \begin{center}
-    \includegraphics[width=0.90\textwidth]{Fig_LBC_shlat}
+    \includegraphics[width=\textwidth]{Fig_LBC_shlat}
     \caption{
       \protect\label{fig:LBC_shlat}
@@ -147,5 +148,6 @@
 % Boundary Condition around the Model Domain
 % ================================================================
-\section{Model domain boundary condition (\protect\np{jperio})}
+\section[Model domain boundary condition (\texttt{jperio})]
+{Model domain boundary condition (\protect\np{jperio})}
 \label{sec:LBC_jperio}
 
@@ -158,5 +160,6 @@
 %        Closed, cyclic (\np{jperio}\forcode{ = 0..2}) 
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Closed, cyclic (\protect\np{jperio}\forcode{= [0127]})}
+\subsection[Closed, cyclic (\forcode{jperio = [0127]})]
+{Closed, cyclic (\protect\np{jperio}\forcode{ = [0127]})}
 \label{subsec:LBC_jperio012}
 
@@ -194,5 +197,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=1.0\textwidth]{Fig_LBC_jperio}
+    \includegraphics[width=\textwidth]{Fig_LBC_jperio}
     \caption{
       \protect\label{fig:LBC_jperio}
@@ -206,5 +209,6 @@
 %        North fold (\textit{jperio = 3 }to $6)$ 
 % -------------------------------------------------------------------------------------------------------------
-\subsection{North-fold (\protect\np{jperio}\forcode{ = 3..6})}
+\subsection[North-fold (\forcode{jperio = [3-6]})]
+{North-fold (\protect\np{jperio}\forcode{ = [3-6]})}
 \label{subsec:LBC_north_fold}
 
@@ -218,5 +222,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=0.90\textwidth]{Fig_North_Fold_T}
+    \includegraphics[width=\textwidth]{Fig_North_Fold_T}
     \caption{
       \protect\label{fig:North_Fold_T}
@@ -232,5 +236,6 @@
 % Exchange with neighbouring processors 
 % ====================================================================
-\section{Exchange with neighbouring processors (\protect\mdl{lbclnk}, \protect\mdl{lib\_mpp})}
+\section[Exchange with neighbouring processors (\textit{lbclnk.F90}, \textit{lib\_mpp.F90})]
+{Exchange with neighbouring processors (\protect\mdl{lbclnk}, \protect\mdl{lib\_mpp})}
 \label{sec:LBC_mpp}
 
@@ -280,5 +285,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=0.90\textwidth]{Fig_mpp}
+    \includegraphics[width=\textwidth]{Fig_mpp}
     \caption{
       \protect\label{fig:mpp}
@@ -360,5 +365,5 @@
 \begin{figure}[!ht]
   \begin{center}
-    \includegraphics[width=0.90\textwidth]{Fig_mppini2}
+    \includegraphics[width=\textwidth]{Fig_mppini2}
     \caption {
       \protect\label{fig:mppini2}
@@ -395,5 +400,5 @@
 
 The BDY module was modelled on the OBC module (see NEMO 3.4) and shares many features and
-a similar coding structure \citep{Chanut2005}.
+a similar coding structure \citep{chanut_rpt05}.
 The specification of the location of the open boundary is completely flexible and
 allows for example the open boundary to follow an isobath or other irregular contour. 
@@ -475,5 +480,5 @@
 \label{subsec:BDY_FRS_scheme}
 
-The Flow Relaxation Scheme (FRS) \citep{Davies_QJRMS76,Engerdahl_Tel95},
+The Flow Relaxation Scheme (FRS) \citep{davies_QJRMS76,engedahl_T95},
 applies a simple relaxation of the model fields to externally-specified values over
 a zone next to the edge of the model domain.
@@ -514,5 +519,5 @@
 \label{subsec:BDY_flather_scheme}
 
-The \citet{Flather_JPO94} scheme is a radiation condition on the normal,
+The \citet{flather_JPO94} scheme is a radiation condition on the normal,
 depth-mean transport across the open boundary.
 It takes the form
@@ -535,5 +540,5 @@
 \label{subsec:BDY_orlanski_scheme}
 
-The Orlanski scheme is based on the algorithm described by \citep{Marchesiello2001}, hereafter MMS.
+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:
@@ -636,5 +641,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=1.0\textwidth]{Fig_LBC_bdy_geom}
+    \includegraphics[width=\textwidth]{Fig_LBC_bdy_geom}
     \caption {
       \protect\label{fig:LBC_bdy_geom}
@@ -670,5 +675,5 @@
 These restrictions mean that data files used with versions of the
 model prior to Version 3.4 may not work with Version 3.4 onwards.
-A \fortran utility {\it bdy\_reorder} exists in the TOOLS directory which
+A \fortran utility {\itshape bdy\_reorder} exists in the TOOLS directory which
 will re-order the data in old BDY data files.
 
@@ -676,5 +681,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=1.0\textwidth]{Fig_LBC_nc_header}
+    \includegraphics[width=\textwidth]{Fig_LBC_nc_header}
     \caption {
       \protect\label{fig:LBC_nc_header}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_LDF.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_LDF.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_LDF.tex	(revision 11422)
@@ -23,9 +23,9 @@
 These three aspects of the lateral diffusion are set through namelist parameters
 (see the \ngn{nam\_traldf} and \ngn{nam\_dynldf} below).
-Note that this chapter describes the standard implementation of iso-neutral tracer mixing,
-and Griffies's implementation, which is used if \np{traldf\_grif}\forcode{ = .true.},
-is described in Appdx\autoref{apdx:triad}
-
-%-----------------------------------nam_traldf - nam_dynldf--------------------------------------------
+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} 
@@ -34,9 +34,37 @@
 %--------------------------------------------------------------------------------------------------------------
 
+% ================================================================
+% Lateral Mixing Operator
+% ================================================================
+\section[Lateral mixing operators]
+{Lateral mixing operators}
+\label{sec:LDF_op}
+We remind here the different lateral mixing operators that can be used. Further details can be found in \autoref{subsec:TRA_ldf_op} and  \autoref{sec:DYN_ldf}.
+
+\subsection[No lateral mixing (\forcode{ln_traldf_OFF}, \forcode{ln_dynldf_OFF})]
+{No lateral mixing (\protect\np{ln\_traldf\_OFF}, \protect\np{ln\_dynldf\_OFF})}
+
+It is possible to run without explicit lateral diffusion on tracers (\protect\np{ln\_traldf\_OFF}\forcode{ = .true.}) and/or 
+momentum (\protect\np{ln\_dynldf\_OFF}\forcode{ = .true.}). The latter option is even recommended if using the 
+UBS advection scheme on momentum (\np{ln\_dynadv\_ubs}\forcode{ = .true.},
+see \autoref{subsec:DYN_adv_ubs}) and can be useful for testing purposes.
+
+\subsection[Laplacian mixing (\forcode{ln_traldf_lap}, \forcode{ln_dynldf_lap})]
+{Laplacian mixing (\protect\np{ln\_traldf\_lap}, \protect\np{ln\_dynldf\_lap})}
+Setting \protect\np{ln\_traldf\_lap}\forcode{ = .true.} and/or \protect\np{ln\_dynldf\_lap}\forcode{ = .true.} enables 
+a second order diffusion on tracers and momentum respectively. Note that in \NEMO 4, one can not combine 
+Laplacian and Bilaplacian operators for the same variable.
+
+\subsection[Bilaplacian mixing (\forcode{ln_traldf_blp}, \forcode{ln_dynldf_blp})]
+{Bilaplacian mixing (\protect\np{ln\_traldf\_blp}, \protect\np{ln\_dynldf\_blp})}
+Setting \protect\np{ln\_traldf\_blp}\forcode{ = .true.} and/or \protect\np{ln\_dynldf\_blp}\forcode{ = .true.} enables 
+a fourth order diffusion on tracers and momentum respectively. It is implemented by calling the above Laplacian operator twice. 
+We stress again that from \NEMO 4, the simultaneous use Laplacian and Bilaplacian operators is not allowed.
 
 % ================================================================
 % Direction of lateral Mixing
 % ================================================================
-\section{Direction of lateral mixing (\protect\mdl{ldfslp})}
+\section[Direction of lateral mixing (\textit{ldfslp.F90})]
+{Direction of lateral mixing (\protect\mdl{ldfslp})}
 \label{sec:LDF_slp}
 
@@ -44,5 +72,5 @@
 \gmcomment{
   we should emphasize here that the implementation is a rather old one.
-  Better work can be achieved by using \citet{Griffies_al_JPO98, Griffies_Bk04} iso-neutral scheme.
+  Better work can be achieved by using \citet{griffies.gnanadesikan.ea_JPO98, griffies_bk04} iso-neutral scheme.
 }
 
@@ -87,5 +115,5 @@
 %gm%  caution I'm not sure the simplification was a good idea! 
 
-These slopes are computed once in \rou{ldfslp\_init} when \np{ln\_sco}\forcode{ = .true.}rue,
+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.}. 
 
@@ -119,5 +147,5 @@
 %In practice, \autoref{eq:ldfslp_iso} is of little help in evaluating the neutral surface slopes. Indeed, for an unsimplified equation of state, the density has a strong dependancy on pressure (here approximated as the depth), therefore applying \autoref{eq:ldfslp_iso} using the $in situ$ density, $\rho$, computed at T-points leads to a flattening of slopes as the depth increases. This is due to the strong increase of the $in situ$ density with depth. 
 
-%By definition, neutral surfaces are tangent to the local $in situ$ density \citep{McDougall1987}, therefore in \autoref{eq:ldfslp_iso}, all the derivatives have to be evaluated at the same local pressure (which in decibars is approximated by the depth in meters).
+%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. 
@@ -135,5 +163,5 @@
   thus the $in situ$ density can be used.
   This is not the case for the vertical derivatives: $\delta_{k+1/2}[\rho]$ is replaced by $-\rho N^2/g$,
-  where $N^2$ is the local Brunt-Vais\"{a}l\"{a} frequency evaluated following \citet{McDougall1987}
+  where $N^2$ is the local Brunt-Vais\"{a}l\"{a} frequency evaluated following \citet{mcdougall_JPO87}
   (see \autoref{subsec:TRA_bn2}). 
 
@@ -144,8 +172,8 @@
 \item[$s$- or hybrid $s$-$z$- coordinate: ]
   in the current release of \NEMO, iso-neutral mixing is only employed for $s$-coordinates if
-  the Griffies scheme is used (\np{traldf\_grif}\forcode{ = .true.};
-  see Appdx \autoref{apdx:triad}).
+  the Griffies scheme is used (\np{ln\_traldf\_triad}\forcode{ = .true.};
+  see \autoref{apdx:triad}).
   In other words, iso-neutral mixing will only be accurately represented with a linear equation of state
-  (\np{nn\_eos}\forcode{ = 1..2}).
+  (\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}
   will include a pressure dependent part, leading to the wrong evaluation of the neutral slopes.
@@ -154,5 +182,5 @@
   Note: The solution for $s$-coordinate passes trough the use of different (and better) expression for
   the constraint on iso-neutral fluxes.
-  Following \citet{Griffies_Bk04}, instead of specifying directly that there is a zero neutral diffusive flux of
+  Following \citet{griffies_bk04}, instead of specifying directly that there is a zero neutral diffusive flux of
   locally referenced potential density, we stay in the $T$-$S$ plane and consider the balance between
   the neutral direction diffusive fluxes of potential temperature and salinity:
@@ -197,11 +225,11 @@
 
 This implementation is a rather old one.
-It is similar to the one proposed by Cox [1987], except for the background horizontal diffusion.
-Indeed, the Cox implementation of isopycnal diffusion in GFDL-type models requires
+It is similar to the one proposed by \citet{cox_OM87}, except for the background horizontal diffusion.
+Indeed, the \citet{cox_OM87} implementation of isopycnal diffusion in GFDL-type models requires
 a minimum background horizontal diffusion for numerical stability reasons.
 To overcome this problem, several techniques have been proposed in which the numerical schemes of
-the ocean model are modified \citep{Weaver_Eby_JPO97, Griffies_al_JPO98}.
-Griffies's scheme is now available in \NEMO if \np{traldf\_grif\_iso} is set true; see Appdx \autoref{apdx:triad}.
-Here, another strategy is presented \citep{Lazar_PhD97}:
+the ocean model are modified \citep{weaver.eby_JPO97, griffies.gnanadesikan.ea_JPO98}.
+Griffies's scheme is now available in \NEMO if \np{ln\_traldf\_triad}=\forcode{= .true.}; see \autoref{apdx:triad}.
+Here, another strategy is presented \citep{lazar_phd97}:
 a local filtering of the iso-neutral slopes (made on 9 grid-points) prevents the development of
 grid point noise generated by the iso-neutral diffusion operator (\autoref{fig:LDF_ZDF1}).
@@ -212,10 +240,10 @@
 
 Nevertheless, this iso-neutral operator does not ensure that variance cannot increase,
-contrary to the \citet{Griffies_al_JPO98} operator which has that property. 
+contrary to the \citet{griffies.gnanadesikan.ea_JPO98} operator which has that property. 
 
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!ht]
   \begin{center}
-    \includegraphics[width=0.70\textwidth]{Fig_LDF_ZDF1}
+    \includegraphics[width=\textwidth]{Fig_LDF_ZDF1}
     \caption {
       \protect\label{fig:LDF_ZDF1}
@@ -235,19 +263,20 @@
 
 
-% In addition and also for numerical stability reasons \citep{Cox1987, Griffies_Bk04}, 
+% In addition and also for numerical stability reasons \citep{cox_OM87, griffies_bk04}, 
 % the slopes are bounded by $1/100$ everywhere. This limit is decreasing linearly 
 % to zero fom $70$ meters depth and the surface (the fact that the eddies "feel" the 
 % surface motivates this flattening of isopycnals near the surface).
 
-For numerical stability reasons \citep{Cox1987, Griffies_Bk04}, the slopes must also be bounded by
-$1/100$ everywhere.
+For numerical stability reasons \citep{cox_OM87, griffies_bk04}, the slopes must also be bounded by
+the namelist scalar \np{rn\_slpmax} (usually $1/100$) everywhere.
 This constraint is applied in a piecewise linear fashion, increasing from zero at the surface to
 $1/100$ at $70$ metres and thereafter decreasing to zero at the bottom of the ocean
 (the fact that the eddies "feel" the surface motivates this flattening of isopycnals near the surface).
+\colorbox{yellow}{The way slopes are tapered has be checked. Not sure that this is still what is actually done.}
 
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!ht]
   \begin{center}
-    \includegraphics[width=0.70\textwidth]{Fig_eiv_slp}
+    \includegraphics[width=\textwidth]{Fig_eiv_slp}
     \caption{
       \protect\label{fig:eiv_slp}
@@ -297,59 +326,72 @@
 (see \autoref{sec:LBC_coast}).
 
-
-% ================================================================
-% Lateral Mixing Operator
-% ================================================================
-\section{Lateral mixing operators (\protect\mdl{traldf}, \protect\mdl{traldf}) }
-\label{sec:LDF_op}
-
-
    
 % ================================================================
 % Lateral Mixing Coefficients
 % ================================================================
-\section{Lateral mixing coefficient (\protect\mdl{ldftra}, \protect\mdl{ldfdyn}) }
+\section[Lateral mixing coefficient (\forcode{nn_aht_ijk_t}, \forcode{nn_ahm_ijk_t})]
+{Lateral mixing coefficient (\protect\np{nn\_aht\_ijk\_t}, \protect\np{nn\_ahm\_ijk\_t})}
 \label{sec:LDF_coef}
 
-Introducing a space variation in the lateral eddy mixing coefficients changes the model core memory requirement,
-adding up to four extra three-dimensional arrays for the geopotential or isopycnal second order operator applied to 
-momentum.
-Six CPP keys control the space variation of eddy coefficients: three for momentum and three for tracer.
-The three choices allow:
-a space variation in the three space directions (\key{traldf\_c3d},  \key{dynldf\_c3d}),
-in the horizontal plane (\key{traldf\_c2d},  \key{dynldf\_c2d}),
-or in the vertical only (\key{traldf\_c1d},  \key{dynldf\_c1d}).
-The default option is a constant value over the whole ocean on both momentum and tracers. 
-   
-The number of additional arrays that have to be defined and the gridpoint position at which
-they are defined depend on both the space variation chosen and the type of operator used.
-The resulting eddy viscosity and diffusivity coefficients can be a function of more than one variable.
-Changes in the computer code when switching from one option to another have been minimized by
-introducing the eddy coefficients as statement functions
-(include file \textit{ldftra\_substitute.h90} and \textit{ldfdyn\_substitute.h90}).
-The functions are replaced by their actual meaning during the preprocessing step (CPP).
-The specification of the space variation of the coefficient is made in \mdl{ldftra} and \mdl{ldfdyn},
-or more precisely in include files \textit{traldf\_cNd.h90} and \textit{dynldf\_cNd.h90}, with N=1, 2 or 3.
-The user can modify these include files as he/she wishes.
-The way the mixing coefficient are set in the reference version can be briefly described as follows:
-
-\subsubsection{Constant mixing coefficients (default option)}
-When none of the \key{dynldf\_...} and \key{traldf\_...} keys are defined,
-a constant value is used over the whole ocean for momentum and tracers,
-which is specified through the \np{rn\_ahm0} and \np{rn\_aht0} namelist parameters.
-
-\subsubsection{Vertically varying mixing coefficients (\protect\key{traldf\_c1d} and \key{dynldf\_c1d})} 
-The 1D option is only available when using the $z$-coordinate with full step.
-Indeed in all the other types of vertical coordinate,
-the depth is a 3D function of (\textbf{i},\textbf{j},\textbf{k}) and therefore,
-introducing depth-dependent mixing coefficients will require 3D arrays.
-In the 1D option, a hyperbolic variation of the lateral mixing coefficient is introduced in which
-the surface value is \np{rn\_aht0} (\np{rn\_ahm0}), the bottom value is 1/4 of the surface value,
-and the transition takes place around z=300~m with a width of 300~m
-(\ie both the depth and the width of the inflection point are set to 300~m).
-This profile is hard coded in file \textit{traldf\_c1d.h90}, but can be easily modified by users.
-
-\subsubsection{Horizontally varying mixing coefficients (\protect\key{traldf\_c2d} and \protect\key{dynldf\_c2d})}
-By default the horizontal variation of the eddy coefficient depends on the local mesh size and
+The specification of the space variation of the coefficient is made in modules \mdl{ldftra} and \mdl{ldfdyn}. 
+The way the mixing coefficients are set in the reference version can be described as follows:
+
+\subsection[Mixing coefficients read from file (\forcode{nn_aht_ijk_t = -20, -30}, \forcode{nn_ahm_ijk_t = -20,-30})]
+{ Mixing coefficients read from file (\protect\np{nn\_aht\_ijk\_t}\forcode{ = -20, -30}, \protect\np{nn\_ahm\_ijk\_t}\forcode{ = -20, -30})}
+
+Mixing coefficients can be read from file if a particular geographical variation is needed. For example, in the ORCA2 global ocean model, 
+the laplacian viscosity operator uses $A^l$~= 4.10$^4$ m$^2$/s poleward of 20$^{\circ}$ north and south and
+decreases linearly to $A^l$~= 2.10$^3$ m$^2$/s at the equator \citep{madec.delecluse.ea_JPO96, delecluse.madec_icol99}. 
+Similar modified horizontal variations can be found with the Antarctic or Arctic sub-domain options of ORCA2 and ORCA05. 
+The provided fields can either be 2d (\np{nn\_aht\_ijk\_t}\forcode{ = -20}, \np{nn\_ahm\_ijk\_t}\forcode{ = -20}) or 3d (\np{nn\_aht\_ijk\_t}\forcode{ = -30},  \np{nn\_ahm\_ijk\_t}\forcode{ = -30}). They must be given at U, V points for tracers and T, F points for momentum (see \autoref{tab:LDF_files}).
+
+%-------------------------------------------------TABLE---------------------------------------------------
+\begin{table}[htb]
+  \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}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+
+\subsection[Constant mixing coefficients (\forcode{nn_aht_ijk_t = 0}, \forcode{nn_ahm_ijk_t = 0})]
+{ Constant mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{ = 0}, \protect\np{nn\_ahm\_ijk\_t}\forcode{ = 0})}
+
+If constant, mixing coefficients are set thanks to a velocity and a length scales ($U_{scl}$, $L_{scl}$) such that:
+
+\begin{equation}
+  \label{eq:constantah}
+  A_o^l = \left\{
+    \begin{aligned}
+      & \frac{1}{2} U_{scl} L_{scl}  		     & \text{for laplacian operator } \\
+      & \frac{1}{12} U_{scl} L_{scl}^3                    & \text{for bilaplacian operator }
+    \end{aligned}
+  \right.
+\end{equation}
+
+ $U_{scl}$ and $L_{scl}$ are given by the namelist parameters \np{rn\_Ud}, \np{rn\_Uv}, \np{rn\_Ld} and \np{rn\_Lv}.
+
+\subsection[Vertically varying mixing coefficients (\forcode{nn_aht_ijk_t = 10}, \forcode{nn_ahm_ijk_t = 10})]
+{Vertically varying mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{ = 10}, \protect\np{nn\_ahm\_ijk\_t}\forcode{ = 10})}
+
+In the vertically varying case, a hyperbolic variation of the lateral mixing coefficient is introduced in which
+the surface value is given by \autoref{eq:constantah}, the bottom value is 1/4 of the surface value,
+and the transition takes place around z=500~m with a width of 200~m.
+This profile is hard coded in module \mdl{ldfc1d\_c2d}, but can be easily modified by users.
+
+\subsection[Mesh size dependent mixing coefficients (\forcode{nn_aht_ijk_t = 20}, \forcode{nn_ahm_ijk_t = 20})]
+{Mesh size dependent mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{ = 20}, \protect\np{nn\_ahm\_ijk\_t}\forcode{ = 20})}
+
+In that case, the horizontal variation of the eddy coefficient depends on the local mesh size and
 the type of operator used:
 \begin{equation}
@@ -357,41 +399,81 @@
   A_l = \left\{
     \begin{aligned}
-      & \frac{\max(e_1,e_2)}{e_{max}} A_o^l  			& \text{for laplacian operator } \\
-      & \frac{\max(e_1,e_2)^{3}}{e_{max}^{3}} A_o^l          & \text{for bilaplacian operator }
+      & \frac{1}{2} U_{scl}  \max(e_1,e_2)  			& \text{for laplacian operator } \\
+      & \frac{1}{12} U_{scl}  \max(e_1,e_2)^{3}             & \text{for bilaplacian operator }
     \end{aligned}
   \right.
 \end{equation}
-where $e_{max}$ is the maximum of $e_1$ and $e_2$ taken over the whole masked ocean domain,
-and $A_o^l$ is the \np{rn\_ahm0} (momentum) or \np{rn\_aht0} (tracer) namelist parameter.
+where $U_{scl}$ is a user defined velocity scale (\np{rn\_Ud}, \np{rn\_Uv}).
 This variation is intended to reflect the lesser need for subgrid scale eddy mixing where
 the grid size is smaller in the domain.
-It was introduced in the context of the DYNAMO modelling project \citep{Willebrand_al_PO01}.
-Note that such a grid scale dependance of mixing coefficients significantly increase the range of stability of
-model configurations presenting large changes in grid pacing such as global ocean models.
+It was introduced in the context of the DYNAMO modelling project \citep{willebrand.barnier.ea_PO01}.
+Note that such a grid scale dependance of mixing coefficients significantly increases the range of stability of
+model configurations presenting large changes in grid spacing such as global ocean models.
 Indeed, in such a case, a constant mixing coefficient can lead to a blow up of the model due to
 large coefficient compare to the smallest grid size (see \autoref{sec:STP_forward_imp}),
 especially when using a bilaplacian operator.
 
-Other formulations can be introduced by the user for a given configuration.
-For example, in the ORCA2 global ocean model (see Configurations),
-the laplacian viscosity operator uses \np{rn\_ahm0}~= 4.10$^4$ m$^2$/s poleward of 20$^{\circ}$ north and south and
-decreases linearly to \np{rn\_aht0}~= 2.10$^3$ m$^2$/s at the equator \citep{Madec_al_JPO96, Delecluse_Madec_Bk00}.
-This modification can be found in routine \rou{ldf\_dyn\_c2d\_orca} defined in \mdl{ldfdyn\_c2d}.
-Similar modified horizontal variations can be found with the Antarctic or Arctic sub-domain options of
-ORCA2 and ORCA05 (see \&namcfg namelist).
-
-\subsubsection{Space varying mixing coefficients (\protect\key{traldf\_c3d} and \key{dynldf\_c3d})}
-
-The 3D space variation of the mixing coefficient is simply the combination of the 1D and 2D cases,
+\colorbox{yellow}{CASE \np{nn\_aht\_ijk\_t} = 21 to be added}
+
+\subsection[Mesh size and depth dependent mixing coefficients (\forcode{nn_aht_ijk_t = 30}, \forcode{nn_ahm_ijk_t = 30})]
+{Mesh size and depth dependent mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{ = 30}, \protect\np{nn\_ahm\_ijk\_t}\forcode{ = 30})}
+
+The 3D space variation of the mixing coefficient is simply the combination of the 1D and 2D cases above,
 \ie a hyperbolic tangent variation with depth associated with a grid size dependence of
 the magnitude of the coefficient. 
 
-\subsubsection{Space and time varying mixing coefficients}
-
-There is no default specification of space and time varying mixing coefficient. 
-The only case available is specific to the ORCA2 and ORCA05 global ocean configurations.
-It provides only a tracer mixing coefficient for eddy induced velocity (ORCA2) or both iso-neutral and
-eddy induced velocity (ORCA05) that depends on the local growth rate of baroclinic instability.
-This specification is actually used when an ORCA key and both \key{traldf\_eiv} and \key{traldf\_c2d} are defined.
+\subsection[Velocity dependent mixing coefficients (\forcode{nn_aht_ijk_t = 31}, \forcode{nn_ahm_ijk_t = 31})]
+{Flow dependent mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{ = 31}, \protect\np{nn\_ahm\_ijk\_t}\forcode{ = 31})}
+In that case, the eddy coefficient is proportional to the local velocity magnitude so that the Reynolds number $Re =  \lvert U \rvert  e / A_l$ is constant (and here hardcoded to $12$):
+\colorbox{yellow}{JC comment: The Reynolds is effectively set to 12 in the code for both operators but shouldn't it be 2 for Laplacian ?}
+
+\begin{equation}
+  \label{eq:flowah}
+  A_l = \left\{
+    \begin{aligned}
+      & \frac{1}{12} \lvert U \rvert e  			& \text{for laplacian operator } \\
+      & \frac{1}{12} \lvert U \rvert e^3 		        & \text{for bilaplacian operator } 
+    \end{aligned}
+  \right.
+\end{equation}
+
+\subsection[Deformation rate dependent viscosities (\forcode{nn_ahm_ijk_t = 32})]
+{Deformation rate dependent viscosities (\protect\np{nn\_ahm\_ijk\_t}\forcode{ = 32})}
+
+This option refers to the \citep{smagorinsky_MW63} scheme which is here implemented for momentum only. Smagorinsky chose as a 
+characteristic time scale $T_{smag}$ the deformation rate and for the lengthscale $L_{smag}$ the maximum wavenumber possible on the horizontal grid, e.g.:
+
+\begin{equation}
+  \label{eq:smag1}
+  \begin{split}
+    T_{smag}^{-1} & = \sqrt{\left( \partial_x u - \partial_y v\right)^2 + \left( \partial_y u + \partial_x v\right)^2  } \\
+    L_{smag} & = \frac{1}{\pi}\frac{e_1 e_2}{e_1 + e_2}
+  \end{split}
+\end{equation}
+
+Introducing a user defined constant $C$ (given in the namelist as \np{rn\_csmc}), one can deduce the mixing coefficients as follows:
+
+\begin{equation}
+  \label{eq:smag2}
+  A_{smag} = \left\{
+    \begin{aligned}
+      & C^2  T_{smag}^{-1}  L_{smag}^2			& \text{for laplacian operator } \\
+      & \frac{C^2}{8} T_{smag}^{-1} L_{smag}^4     	& \text{for bilaplacian operator } 
+    \end{aligned}
+  \right.
+\end{equation}
+
+For stability reasons, upper and lower limits are applied on the resulting coefficient (see \autoref{sec:STP_forward_imp}) so that:
+\begin{equation}
+  \label{eq:smag3}
+    \begin{aligned}
+      & C_{min} \frac{1}{2}   \lvert U \rvert  e    < A_{smag} < C_{max} \frac{e^2}{   8\rdt}                 & \text{for laplacian operator } \\
+      & C_{min} \frac{1}{12} \lvert U \rvert  e^3 < A_{smag} < C_{max} \frac{e^4}{64 \rdt}                 & \text{for bilaplacian operator } 
+    \end{aligned}
+\end{equation}
+
+where $C_{min}$ and $C_{max}$ are adimensional namelist parameters given by \np{rn\_minfac} and \np{rn\_maxfac} respectively.
+
+\subsection{About space and time varying mixing coefficients}
 
 The following points are relevant when the eddy coefficient varies spatially:
@@ -406,30 +488,18 @@
 (\autoref{sec:dynldf_properties}).
 
-(3) for isopycnal diffusion on momentum or tracers, an additional purely horizontal background diffusion with
-uniform coefficient can be added by setting a non zero value of \np{rn\_ahmb0} or \np{rn\_ahtb0},
-a background horizontal eddy viscosity or diffusivity coefficient
-(namelist parameters whose default values are $0$).
-However, the technique used to compute the isopycnal slopes is intended to get rid of such a background diffusion,
-since it introduces spurious diapycnal diffusion (see \autoref{sec:LDF_slp}).
-
-(4) when an eddy induced advection term is used (\key{traldf\_eiv}),
-$A^{eiv}$, the eddy induced coefficient has to be defined.
-Its space variations are controlled by the same CPP variable as for the eddy diffusivity coefficient
-(\ie \key{traldf\_cNd}). 
-
-(5) the eddy coefficient associated with a biharmonic operator must be set to a \emph{negative} value.
-
-(6) it is possible to use both the laplacian and biharmonic operators concurrently.
-
-(7) it is possible to run without explicit lateral diffusion on momentum
-(\np{ln\_dynldf\_lap}\forcode{ = .?.}\np{ln\_dynldf\_bilap}\forcode{ = .false.}).
-This is recommended when using the UBS advection scheme on momentum (\np{ln\_dynadv\_ubs}\forcode{ = .true.},
-see \autoref{subsec:DYN_adv_ubs}) and can be useful for testing purposes.
-
 % ================================================================
 % Eddy Induced Mixing
 % ================================================================
-\section{Eddy induced velocity (\protect\mdl{traadv\_eiv}, \protect\mdl{ldfeiv})}
+\section[Eddy induced velocity (\forcode{ln_ldfeiv = .true.})]
+{Eddy induced velocity (\protect\np{ln\_ldfeiv}\forcode{ = .true.})}
+
 \label{sec:LDF_eiv}
+
+%--------------------------------------------namtra_eiv---------------------------------------------------
+
+\nlst{namtra_eiv}
+
+%--------------------------------------------------------------------------------------------------------------
+
 
 %%gm  from Triad appendix  : to be incorporated....
@@ -453,5 +523,5 @@
 }
 
-When Gent and McWilliams [1990] diffusion is used (\key{traldf\_eiv} defined),
+When  \citet{gent.mcwilliams_JPO90} diffusion is used (\np{ln\_ldfeiv}\forcode{ = .true.}),
 an eddy induced tracer advection term is added,
 the formulation of which depends on the slopes of iso-neutral surfaces.
@@ -459,5 +529,6 @@
 \ie \autoref{eq:ldfslp_geo} is used in $z$-coordinates,
 and the sum \autoref{eq:ldfslp_geo} + \autoref{eq:ldfslp_iso} in $s$-coordinates.
-The eddy induced velocity is given by: 
+
+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}
@@ -468,12 +539,11 @@
   \end{split}
 \end{equation}
-where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{rn\_aeiv},
-a \textit{nam\_traldf} namelist parameter.
-The three components of the eddy induced velocity are computed and
-add to the eulerian velocity in \mdl{traadv\_eiv}.
+where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{nn\_aei\_ijk\_t} \ngn{namtra\_eiv} namelist parameter. 
+The three components of the eddy induced velocity are computed in \rou{ldf\_eiv\_trp} and
+added to the eulerian velocity in \rou{tra\_adv} where tracer advection is performed.
 This has been preferred to a separate computation of the advective trends associated with the eiv velocity,
 since it allows us to take advantage of all the advection schemes offered for the tracers
 (see \autoref{sec:TRA_adv}) and not just the $2^{nd}$ order advection scheme as in
-previous releases of OPA \citep{Madec1998}.
+previous releases of OPA \citep{madec.delecluse.ea_NPM98}.
 This is particularly useful for passive tracers where \emph{positivity} of the advection scheme is of
 paramount importance. 
@@ -481,4 +551,26 @@
 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.})}
+
+\label{sec:LDF_mle}
+
+%--------------------------------------------namtra_eiv---------------------------------------------------
+
+\nlst{namtra_mle}
+
+%--------------------------------------------------------------------------------------------------------------
+
+If  \np{ln\_mle}\forcode{ = .true.} in \ngn{namtra\_mle} namelist, a parameterization of the mixing due to unresolved mixed layer instabilities is activated (\citet{foxkemper.ferrari_JPO08}). Additional transport is computed in \rou{ldf\_mle\_trp} and added to the eulerian transport in \rou{tra\_adv} as done for eddy induced advection.
+
+\colorbox{yellow}{TBC}
 
 \biblio
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_OBS.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_OBS.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_OBS.tex	(revision 11422)
@@ -8,19 +8,29 @@
 \label{chap:OBS}
 
-Authors: D. Lea, M. Martin, K. Mogensen, A. Vidard, A. Weaver, A. Ryan, ...   % do we keep that ?
-
 \minitoc
 
+\vfill
+\begin{figure}[b]
+\subsubsection*{Changes record}
+\begin{tabular}{l||l|m{0.65\linewidth}}
+    Release   & Author        & Modifications \\
+    {\em 4.0} & {\em D. J. Lea} & {\em \NEMO 4.0 updates}  \\
+    {\em 3.6} & {\em M. Martin, A. Ryan} & {\em Add averaging operator, standalone obs oper} \\
+    {\em 3.4} & {\em D. J. Lea, M. Martin, ...} & {\em Initial version}  \\
+    {\em --\texttt{"}--} & {\em ... K. Mogensen, A. Vidard, A. Weaver} & {\em ---\texttt{"}---}  \\
+\end{tabular}
+\end{figure}
+
 \newpage
 
-The observation and model comparison code (OBS) reads in observation files
-(profile temperature and salinity, sea surface temperature, sea level anomaly, sea ice concentration, and velocity) and calculates an interpolated model equivalent value at the observation location and nearest model timestep.
+The observation and model comparison code, the observation operator (OBS), reads in observation files
+(profile temperature and salinity, sea surface temperature, sea level anomaly, sea ice concentration, and velocity) and calculates an interpolated model equivalent value at the observation location and nearest model time step.
 The resulting data are saved in a ``feedback'' file (or files).
 The code was originally developed for use with the NEMOVAR data assimilation code,
 but can be used for validation or verification of the model or with any other data assimilation system.
 
-The OBS code is called from \mdl{nemogcm} for model initialisation and to calculate the model equivalent values for observations on the 0th timestep.
-The code is then called again after each timestep from \mdl{step}.
-The code is only activated if the namelist logical \np{ln\_diaobs} is set to true.
+The OBS code is called from \mdl{nemogcm} for model initialisation and to calculate the model equivalent values for observations on the 0th time step.
+The code is then called again after each time step from \mdl{step}.
+The code is only activated if the \ngn{namobs} namelist logical \np{ln\_diaobs} is set to true.
 
 For all data types a 2D horizontal interpolator or averager is needed to
@@ -28,5 +38,5 @@
 For {\em in situ} profiles, a 1D vertical interpolator is needed in addition to
 provide model fields at the observation depths.
-This now works in a generalised vertical coordinate system. 
+This now works in a generalised vertical coordinate system.
 
 Some profile observation types (\eg tropical moored buoys) are made available as daily averaged quantities.
@@ -36,17 +46,17 @@
 the observation operator code can calculate equivalent night-time average model SST fields by
 setting the namelist value \np{ln\_sstnight} to true.
-Otherwise the model value from the nearest timestep to the observation time is used.
-
-The code is controlled by the namelist \textit{namobs}.
+Otherwise (by default) the model value from the nearest time step to the observation time is used.
+
+The code is controlled by the namelist \ngn{namobs}.
 See the following sections for more details on setting up the namelist.
 
-\autoref{sec:OBS_example} introduces a test example of the observation operator code including
+In \autoref{sec:OBS_example} a test example of the observation operator code is introduced, including
 where to obtain data and how to setup the namelist.
-\autoref{sec:OBS_details} introduces some more technical details of the different observation types used and
-also shows a more complete namelist.
-\autoref{sec:OBS_theory} introduces some of the theoretical aspects of the observation operator including
+In \autoref{sec:OBS_details} some more technical details of the different observation types used are introduced, and we
+also show a more complete namelist.
+In \autoref{sec:OBS_theory} some of the theoretical aspects of the observation operator are described including
 interpolation methods and running on multiple processors.
-\autoref{sec:OBS_ooo} describes the offline observation operator code.
-\autoref{sec:OBS_obsutils} introduces some utilities to help working with the files produced by the OBS code.
+In \autoref{sec:OBS_sao} the standalone observation operator code is described.
+In \autoref{sec:OBS_obsutils} we describe some utilities to help work with the files produced by the OBS code.
 
 % ================================================================
@@ -56,7 +66,7 @@
 \label{sec:OBS_example}
 
-This section describes an example of running the observation operator code using
-profile data which can be freely downloaded.
-It shows how to adapt an existing run and build of NEMO to run the observation operator.
+In this section an example of running the observation operator code is described using
+profile observation data which can be freely downloaded.
+It shows how to adapt an existing run and build of \NEMO to run the observation operator. Note also the observation operator and the assimilation increments code are run in the \np{ORCA2\_ICE\_OBS} SETTE test.
 
 \begin{enumerate}
@@ -65,17 +75,19 @@
 \item Download some EN4 data from \href{http://www.metoffice.gov.uk/hadobs}{www.metoffice.gov.uk/hadobs}.
   Choose observations which are valid for the period of your test run because
-  the observation operator compares the model and observations for a matching date and time. 
-
-\item Compile the OBSTOOLS code using: 
+  the observation operator compares the model and observations for a matching date and time.
+
+\item Compile the OBSTOOLS code in the \np{tools} directory using:
 \begin{cmds}
-./maketools -n OBSTOOLS -m [ARCH].
+./maketools -n OBSTOOLS -m [ARCH]
 \end{cmds}
 
-\item Convert the EN4 data into feedback format: 
+replacing \np{[ARCH]} with the build architecture file for your machine. Note the tools are checked out from a separate repository under \np{utils/tools}.
+
+\item Convert the EN4 data into feedback format:
 \begin{cmds}
 enact2fb.exe profiles_01.nc EN.4.1.1.f.profiles.g10.YYYYMM.nc
 \end{cmds}
 
-\item Include the following in the NEMO namelist to run the observation operator on this data:
+\item Include the following in the \NEMO namelist to run the observation operator on this data:
 \end{enumerate}
 
@@ -87,15 +99,15 @@
 This can be expensive, particularly for large numbers of observations,
 setting \np{ln\_grid\_search\_lookup} allows the use of a lookup table which
-is saved into an ``xypos`` file (or files).
+is saved into an \np{cn\_gridsearch} file (or files).
 This will need to be generated the first time if it does not exist in the run directory.
 However, once produced it will significantly speed up future grid searches.
 Setting \np{ln\_grid\_global} means that the code distributes the observations evenly between processors.
 Alternatively each processor will work with observations located within the model subdomain
-(see section~\autoref{subsec:OBS_parallel}).
+(see \autoref{subsec:OBS_parallel}).
 
 A number of utilities are now provided to plot the feedback files, convert and recombine the files.
-These are explained in more detail in section~\autoref{sec:OBS_obsutils}.
-Utilites to convert other input data formats into the feedback format are also described in
-section~\autoref{sec:OBS_obsutils}.
+These are explained in more detail in \autoref{sec:OBS_obsutils}.
+Utilities to convert other input data formats into the feedback format are also described in
+\autoref{sec:OBS_obsutils}.
 
 \section{Technical details (feedback type observation file headers)}
@@ -110,10 +122,10 @@
 %-------------------------------------------------------------------------------------------------------------
 
-The observation operator code uses the "feedback" observation file format for all data types.
+The observation operator code uses the feedback observation file format for all data types.
 All the observation files must be in NetCDF format.
 Some example headers (produced using \mbox{\textit{ncdump~-h}}) for profile data, sea level anomaly and
 sea surface temperature are in the following subsections.
 
-\subsection{Profile feedback}
+\subsection{Profile feedback file}
 
 \begin{clines}
@@ -271,5 +283,5 @@
 \end{clines}
 
-\subsection{Sea level anomaly feedback}
+\subsection{Sea level anomaly feedback file}
 
 \begin{clines}
@@ -395,5 +407,5 @@
 \end{clines}
 
-The mean dynamic topography (MDT) must be provided in a separate file defined on
+To use Sea Level Anomaly (SLA) data the mean dynamic topography (MDT) must be provided in a separate file defined on
 the model grid called \ifile{slaReferenceLevel}.
 The MDT is required in order to produce the model equivalent sea level anomaly from the model sea surface height.
@@ -417,5 +429,5 @@
 \end{clines}
 
-\subsection{Sea surface temperature feedback}
+\subsection{Sea surface temperature feedback file}
 
 \begin{clines}
@@ -546,6 +558,6 @@
 In those cases the model counterpart should be calculated by averaging the model grid points over
 the same size as the footprint.
-NEMO therefore has the capability to specify either an interpolation or an averaging
-(for surface observation types only). 
+\NEMO therefore has the capability to specify either an interpolation or an averaging
+(for surface observation types only).
 
 The main namelist option associated with the interpolation/averaging is \np{nn\_2dint}.
@@ -559,13 +571,13 @@
 \item \np{nn\_2dint}\forcode{ = 4}: Polynomial interpolation
 \item \np{nn\_2dint}\forcode{ = 5}: Radial footprint averaging with diameter specified in the namelist as
-  \np{rn\_???\_avglamscl} in degrees or metres (set using \np{ln\_???\_fp\_indegs})
+  \np{rn\_[var]\_avglamscl} in degrees or metres (set using \np{ln\_[var]\_fp\_indegs})
 \item \np{nn\_2dint}\forcode{ = 6}: Rectangular footprint averaging with E/W and N/S size specified in
-  the namelist as \np{rn\_???\_avglamscl} and \np{rn\_???\_avgphiscl} in degrees or metres
-  (set using \np{ln\_???\_fp\_indegs})
+  the namelist as \np{rn\_[var]\_avglamscl} and \np{rn\_[var]\_avgphiscl} in degrees or metres
+  (set using \np{ln\_[var]\_fp\_indegs})
 \end{itemize}
-The ??? in the last two options indicate these options should be specified for each observation type for
+Replace \np{[var]} in the last two options with the observation type (sla, sst, sss or sic) for
 which the averaging is to be performed (see namelist example above).
 The \np{nn\_2dint} default option can be overridden for surface observation types using
-namelist values \np{nn\_2dint\_???} where ??? is one of sla,sst,sss,sic.
+namelist values \np{nn\_2dint\_[var]} where \np{[var]} is the observation type.
 
 Below is some more detail on the various options for interpolation and averaging available in NEMO.
@@ -573,18 +585,20 @@
 \subsubsection{Horizontal interpolation}
 
-Consider an observation point ${\rm P}$ with with longitude and latitude $({\lambda_{}}_{\rm P}, \phi_{\rm P})$ and
-the four nearest neighbouring model grid points ${\rm A}$, ${\rm B}$, ${\rm C}$ and ${\rm D}$ with
-longitude and latitude ($\lambda_{\rm A}$, $\phi_{\rm A}$),($\lambda_{\rm B}$, $\phi_{\rm B}$) etc.
-All horizontal interpolation methods implemented in NEMO estimate the value of a model variable $x$ at point $P$ as
-a weighted linear combination of the values of the model variables at the grid points ${\rm A}$, ${\rm B}$ etc.:
+Consider an observation point ${\mathrm P}$ with longitude and latitude (${\lambda_{}}_{\mathrm P}$, $\phi_{\mathrm P}$) and
+the four nearest neighbouring model grid points ${\mathrm A}$, ${\mathrm B}$, ${\mathrm C}$ and ${\mathrm D}$ with
+longitude and latitude ($\lambda_{\mathrm A}$, $\phi_{\mathrm A}$),($\lambda_{\mathrm B}$, $\phi_{\mathrm B}$) etc.
+All horizontal interpolation methods implemented in \NEMO estimate the value of a model variable $x$ at point $P$ as
+a weighted linear combination of the values of the model variables at the grid points ${\mathrm A}$, ${\mathrm B}$ etc.:
+
 \begin{align*}
-  {x_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} &
-                                                   \frac{1}{w} \left( {w_{}}_{\rm A} {x_{}}_{\rm A} +
-                                                   {w_{}}_{\rm B} {x_{}}_{\rm B} +
-                                                   {w_{}}_{\rm C} {x_{}}_{\rm C} +
-                                                   {w_{}}_{\rm D} {x_{}}_{\rm D} \right)
+  {x_{}}_{\mathrm P} =
+\frac{1}{w} \left( {w_{}}_{\mathrm A} {x_{}}_{\mathrm A} +
+{w_{}}_{\mathrm B} {x_{}}_{\mathrm B} +
+{w_{}}_{\mathrm C} {x_{}}_{\mathrm C} +
+{w_{}}_{\mathrm D} {x_{}}_{\mathrm D} \right)
 \end{align*}
-where ${w_{}}_{\rm A}$, ${w_{}}_{\rm B}$ etc. are the respective weights for the model field at
-points ${\rm A}$, ${\rm B}$ etc., and $w = {w_{}}_{\rm A} + {w_{}}_{\rm B} + {w_{}}_{\rm C} + {w_{}}_{\rm D}$.
+
+where ${w_{}}_{\mathrm A}$, ${w_{}}_{\mathrm B}$ etc. are the respective weights for the model field at
+points ${\mathrm A}$, ${\mathrm B}$ etc., and $w = {w_{}}_{\mathrm A} + {w_{}}_{\mathrm B} + {w_{}}_{\mathrm C} + {w_{}}_{\mathrm D}$.
 
 Four different possibilities are available for computing the weights.
@@ -592,62 +606,67 @@
 \begin{enumerate}
 
-\item[1.] {\bf Great-Circle distance-weighted interpolation.}
+\item[1.] {\bfseries Great-Circle distance-weighted interpolation.}
   The weights are computed as a function of the great-circle distance $s(P, \cdot)$ between $P$ and
   the model grid points $A$, $B$ etc.
-  For example, the weight given to the field ${x_{}}_{\rm A}$ is specified as the product of the distances
-  from ${\rm P}$ to the other points:
-  \begin{align*}
-    {w_{}}_{\rm A} = s({\rm P}, {\rm B}) \, s({\rm P}, {\rm C}) \, s({\rm P}, {\rm D})
-  \end{align*}
-  where 
-  \begin{align*}
-    s\left ({\rm P}, {\rm M} \right ) 
-     & \hspace{-2mm} = \hspace{-2mm} & 
-      \cos^{-1} \! \left\{ 
-               \sin {\phi_{}}_{\rm P} \sin {\phi_{}}_{\rm M}
-             + \cos {\phi_{}}_{\rm P} \cos {\phi_{}}_{\rm M} 
-               \cos ({\lambda_{}}_{\rm M} - {\lambda_{}}_{\rm P}) 
+  For example, the weight given to the field ${x_{}}_{\mathrm A}$ is specified as the product of the distances
+  from ${\mathrm P}$ to the other points:
+
+  \begin{alignat*}{2}
+    {w_{}}_{\mathrm A} = s({\mathrm P}, {\mathrm B}) \, s({\mathrm P}, {\mathrm C}) \, s({\mathrm P}, {\mathrm D})
+  \end{alignat*}
+
+  where
+
+  \begin{alignat*}{2}
+    s\left({\mathrm P}, {\mathrm M} \right) & = & \hspace{0.25em} \cos^{-1} \! \left\{
+               \sin {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm M}
+             + \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm M}
+               \cos ({\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P})
                    \right\}
-   \end{align*}
+   \end{alignat*}
+
    and $M$ corresponds to $B$, $C$ or $D$.
    A more stable form of the great-circle distance formula for small distances ($x$ near 1)
-   involves the arcsine function (\eg see p.~101 of \citet{Daley_Barker_Bk01}:
-   \begin{align*}
-     s\left( {\rm P}, {\rm M} \right) & \hspace{-2mm} = \hspace{-2mm} & \sin^{-1} \! \left\{ \sqrt{ 1 - x^2 } \right\}
-   \end{align*}
+   involves the arcsine function (\eg see p.~101 of \citet{daley.barker_bk01}:
+
+   \begin{alignat*}{2}
+     s\left( {\mathrm P}, {\mathrm M} \right) = \sin^{-1} \! \left\{ \sqrt{ 1 - x^2 } \right\}
+   \end{alignat*}
+
    where
-   \begin{align*}
-     x & \hspace{-2mm} = \hspace{-2mm} &
-                                         {a_{}}_{\rm M} {a_{}}_{\rm P} + {b_{}}_{\rm M} {b_{}}_{\rm P} + {c_{}}_{\rm M} {c_{}}_{\rm P}
-   \end{align*}
-   and 
-   \begin{align*}
-      {a_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\rm M}, \\
-      {a_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\rm P}, \\
-      {b_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm M} \cos {\phi_{}}_{\rm M}, \\
-      {b_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm P} \cos {\phi_{}}_{\rm P}, \\
-      {c_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm M} \sin {\phi_{}}_{\rm M}, \\
-      {c_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm P} \sin {\phi_{}}_{\rm P}.
-  \end{align*}
-
-\item[2.] {\bf Great-Circle distance-weighted interpolation with small angle approximation.}
+
+   \begin{alignat*}{2}
+     x = {a_{}}_{\mathrm M} {a_{}}_{\mathrm P} + {b_{}}_{\mathrm M} {b_{}}_{\mathrm P} + {c_{}}_{\mathrm M} {c_{}}_{\mathrm P}
+   \end{alignat*}
+
+   and
+
+   \begin{alignat*}{3}
+   & {a_{}}_{\mathrm M} & = && \quad \sin {\phi_{}}_{\mathrm M}, \\
+   & {a_{}}_{\mathrm P} & = && \quad \sin {\phi_{}}_{\mathrm P}, \\
+   & {b_{}}_{\mathrm M} & = && \quad \cos {\phi_{}}_{\mathrm M} \cos {\phi_{}}_{\mathrm M}, \\
+   & {b_{}}_{\mathrm P} & = && \quad \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm P}, \\
+   & {c_{}}_{\mathrm M} & = && \quad \cos {\phi_{}}_{\mathrm M} \sin {\phi_{}}_{\mathrm M}, \\
+   & {c_{}}_{\mathrm P} & = && \quad \cos {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm P}.
+   \end{alignat*}
+
+\item[2.] {\bfseries Great-Circle distance-weighted interpolation with small angle approximation.}
   Similar to the previous interpolation but with the distance $s$ computed as
-  \begin{align*}
-    s\left( {\rm P}, {\rm M} \right)
-    & \hspace{-2mm} = \hspace{-2mm} &
-                                      \sqrt{ \left( {\phi_{}}_{\rm M} - {\phi_{}}_{\rm P} \right)^{2}
-                                      + \left( {\lambda_{}}_{\rm M} - {\lambda_{}}_{\rm P} \right)^{2}
-                                      \cos^{2} {\phi_{}}_{\rm M} }
-  \end{align*}
+  \begin{alignat*}{2}
+    s\left( {\mathrm P}, {\mathrm M} \right)
+    & = & \sqrt{ \left( {\phi_{}}_{\mathrm M} - {\phi_{}}_{\mathrm P} \right)^{2}
+                                      + \left( {\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P} \right)^{2}
+                                      \cos^{2} {\phi_{}}_{\mathrm M} }
+  \end{alignat*}
   where $M$ corresponds to $A$, $B$, $C$ or $D$.
 
-\item[3.] {\bf Bilinear interpolation for a regular spaced grid.}
+\item[3.] {\bfseries Bilinear interpolation for a regular spaced grid.}
   The interpolation is split into two 1D interpolations in the longitude and latitude directions, respectively.
 
-\item[4.] {\bf Bilinear remapping interpolation for a general grid.}
+\item[4.] {\bfseries Bilinear remapping interpolation for a general grid.}
   An iterative scheme that involves first mapping a quadrilateral cell into
   a cell with coordinates (0,0), (1,0), (0,1) and (1,1).
-  This method is based on the SCRIP interpolation package \citep{Jones_1998}.
-  
+  This method is based on the \href{https://github.com/SCRIP-Project/SCRIP}{SCRIP interpolation package}.
+
 \end{enumerate}
 
@@ -658,8 +677,7 @@
 \item The standard grid-searching code is used to find the nearest model grid point to the observation location
   (see next subsection).
-\item The maximum number of grid points is calculated in the local grid domain for which
-  the averaging is likely need to cover.
-\item The lats/longs of the grid points surrounding the nearest model grid box are extracted using
-  existing mpi routines.
+\item The maximum number of grid points required for that observation in each local grid domain is calculated. Some of these points may later turn out to have zero weight depending on the shape of the footprint.
+\item The longitudes and latitudes of the grid points surrounding the nearest model grid box are extracted using
+  existing MPI routines.
 \item The weights for each grid point associated with each observation are calculated,
   either for radial or rectangular footprints.
@@ -673,10 +691,10 @@
 
 Examples of the weights calculated for an observation with rectangular and radial footprints are shown in
-Figs.~\autoref{fig:obsavgrec} and~\autoref{fig:obsavgrad}.
+\autoref{fig:obsavgrec} and~\autoref{fig:obsavgrad}.
 
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}
   \begin{center}
-    \includegraphics[width=0.90\textwidth]{Fig_OBS_avg_rec}
+    \includegraphics[width=\textwidth]{Fig_OBS_avg_rec}
     \caption{
       \protect\label{fig:obsavgrec}
@@ -691,10 +709,10 @@
 \begin{figure}
   \begin{center}
-    \includegraphics[width=0.90\textwidth]{Fig_OBS_avg_rad}
+    \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}
 \end{figure}
@@ -704,45 +722,45 @@
 \subsection{Grid search}
 
-For many grids used by the NEMO model, such as the ORCA family, the horizontal grid coordinates $i$ and $j$ are not simple functions of latitude and longitude.
+For many grids used by the \NEMO model, such as the ORCA family, the horizontal grid coordinates $i$ and $j$ are not simple functions of latitude and longitude.
 Therefore, it is not always straightforward to determine the grid points surrounding any given observational position.
-Before the interpolation can be performed, a search algorithm is then required to determine the corner points of 
+Before the interpolation can be performed, a search algorithm is then required to determine the corner points of
 the quadrilateral cell in which the observation is located.
-This is the most difficult and time consuming part of the 2D interpolation procedure. 
+This is the most difficult and time consuming part of the 2D interpolation procedure.
 A robust test for determining if an observation falls within a given quadrilateral cell is as follows.
-Let ${\rm P}({\lambda_{}}_{\rm P} ,{\phi_{}}_{\rm P} )$ denote the observation point,
-and let ${\rm A}({\lambda_{}}_{\rm A} ,{\phi_{}}_{\rm A} )$, ${\rm B}({\lambda_{}}_{\rm B} ,{\phi_{}}_{\rm B} )$,
-${\rm C}({\lambda_{}}_{\rm C} ,{\phi_{}}_{\rm C} )$ and ${\rm D}({\lambda_{}}_{\rm D} ,{\phi_{}}_{\rm D} )$
-denote the bottom left, bottom right, top left and top right corner points of the cell, respectively. 
-To determine if P is inside the cell, we verify that the cross-products 
+Let ${\mathrm P}({\lambda_{}}_{\mathrm P} ,{\phi_{}}_{\mathrm P} )$ denote the observation point,
+and let ${\mathrm A}({\lambda_{}}_{\mathrm A} ,{\phi_{}}_{\mathrm A} )$, ${\mathrm B}({\lambda_{}}_{\mathrm B} ,{\phi_{}}_{\mathrm B} )$,
+${\mathrm C}({\lambda_{}}_{\mathrm C} ,{\phi_{}}_{\mathrm C} )$ and ${\mathrm D}({\lambda_{}}_{\mathrm D} ,{\phi_{}}_{\mathrm D} )$
+denote the bottom left, bottom right, top left and top right corner points of the cell, respectively.
+To determine if P is inside the cell, we verify that the cross-products
 \begin{align*}
   \begin{array}{lllll}
-    {{\bf r}_{}}_{\rm PA} \times {{\bf r}_{}}_{\rm PC}
-    & = & [({\lambda_{}}_{\rm A}\; -\; {\lambda_{}}_{\rm P} )
-          ({\phi_{}}_{\rm C}   \; -\; {\phi_{}}_{\rm P} )
-          - ({\lambda_{}}_{\rm C}\; -\; {\lambda_{}}_{\rm P} )
-          ({\phi_{}}_{\rm A}   \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\
-    {{\bf r}_{}}_{\rm PB} \times {{\bf r}_{}}_{\rm PA}
-    & = & [({\lambda_{}}_{\rm B}\; -\; {\lambda_{}}_{\rm P} )
-          ({\phi_{}}_{\rm A}   \; -\; {\phi_{}}_{\rm P} )
-          - ({\lambda_{}}_{\rm A}\; -\; {\lambda_{}}_{\rm P} )
-          ({\phi_{}}_{\rm B}   \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\
-    {{\bf r}_{}}_{\rm PC} \times {{\bf r}_{}}_{\rm PD}
-    & = & [({\lambda_{}}_{\rm C}\; -\; {\lambda_{}}_{\rm P} )
-          ({\phi_{}}_{\rm D}   \; -\; {\phi_{}}_{\rm P} )
-          - ({\lambda_{}}_{\rm D}\; -\; {\lambda_{}}_{\rm P} )
-          ({\phi_{}}_{\rm C}   \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\
-    {{\bf r}_{}}_{\rm PD} \times {{\bf r}_{}}_{\rm PB}
-    & = & [({\lambda_{}}_{\rm D}\; -\; {\lambda_{}}_{\rm P} )
-          ({\phi_{}}_{\rm B}   \; -\; {\phi_{}}_{\rm P} )
-          - ({\lambda_{}}_{\rm B}\; -\; {\lambda_{}}_{\rm P} )
-          ({\phi_{}}_{\rm D}  \;  - \; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\
+    {{\mathbf r}_{}}_{\mathrm PA} \times {{\mathbf r}_{}}_{\mathrm PC}
+    & = & [({\lambda_{}}_{\mathrm A}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm C}   \; -\; {\phi_{}}_{\mathrm P} )
+          - ({\lambda_{}}_{\mathrm C}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm A}   \; -\; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\
+    {{\mathbf r}_{}}_{\mathrm PB} \times {{\mathbf r}_{}}_{\mathrm PA}
+    & = & [({\lambda_{}}_{\mathrm B}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm A}   \; -\; {\phi_{}}_{\mathrm P} )
+          - ({\lambda_{}}_{\mathrm A}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm B}   \; -\; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\
+    {{\mathbf r}_{}}_{\mathrm PC} \times {{\mathbf r}_{}}_{\mathrm PD}
+    & = & [({\lambda_{}}_{\mathrm C}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm D}   \; -\; {\phi_{}}_{\mathrm P} )
+          - ({\lambda_{}}_{\mathrm D}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm C}   \; -\; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\
+    {{\mathbf r}_{}}_{\mathrm PD} \times {{\mathbf r}_{}}_{\mathrm PB}
+    & = & [({\lambda_{}}_{\mathrm D}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm B}   \; -\; {\phi_{}}_{\mathrm P} )
+          - ({\lambda_{}}_{\mathrm B}\; -\; {\lambda_{}}_{\mathrm P} )
+          ({\phi_{}}_{\mathrm D}  \;  - \; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\
   \end{array}
   % \label{eq:cross}
 \end{align*}
-point in the opposite direction to the unit normal $\widehat{\bf k}$
-(\ie that the coefficients of $\widehat{\bf k}$ are negative),
-where ${{\bf r}_{}}_{\rm PA}$, ${{\bf r}_{}}_{\rm PB}$, etc. correspond to
+point in the opposite direction to the unit normal $\widehat{\mathbf k}$
+(\ie that the coefficients of $\widehat{\mathbf k}$ are negative),
+where ${{\mathbf r}_{}}_{\mathrm PA}$, ${{\mathbf r}_{}}_{\mathrm PB}$, etc. correspond to
 the vectors between points P and A, P and B, etc..
-The method used is similar to the method used in the SCRIP interpolation package \citep{Jones_1998}.
+The method used is similar to the method used in the \href{https://github.com/SCRIP-Project/SCRIP}{SCRIP interpolation package}.
 
 In order to speed up the grid search, there is the possibility to construct a lookup table for a user specified resolution.
@@ -750,5 +768,5 @@
 be searched for on a regular grid.
 For each observation position, the closest point on the regular grid of this position is computed and
-the $i$ and $j$ ranges of this point searched to determine the precise four points surrounding the observation. 
+the $i$ and $j$ ranges of this point searched to determine the precise four points surrounding the observation.
 
 \subsection{Parallel aspects of horizontal interpolation}
@@ -757,10 +775,9 @@
 For horizontal interpolation, there is the basic problem that
 the observations are unevenly distributed on the globe.
-In numerical models, it is common to divide the model grid into subgrids (or domains) where
+In \NEMO the model grid is divided into subgrids (or domains) where
 each subgrid is executed on a single processing element with explicit message passing for
 exchange of information along the domain boundaries when running on a massively parallel processor (MPP) system.
-This approach is used by \NEMO.
-
-For observations there is no natural distribution since the observations are not equally distributed on the globe. 
+
+For observations there is no natural distribution since the observations are not equally distributed on the globe.
 Two options have been made available:
 1) geographical distribution;
@@ -772,5 +789,5 @@
 \begin{figure}
   \begin{center}
-    \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_ASM_obsdist_local}
+    \includegraphics[width=\textwidth]{Fig_ASM_obsdist_local}
     \caption{
       \protect\label{fig:obslocal}
@@ -784,10 +801,10 @@
 the domain of the grid-point parallelization.
 \autoref{fig:obslocal} shows an example of the distribution of the {\em in situ} data on processors with
-a different colour for each observation on a given processor for a 4 $\times$ 2 decomposition with ORCA2. 
+a different colour for each observation on a given processor for a 4 $\times$ 2 decomposition with ORCA2.
 The grid-point domain decomposition is clearly visible on the plot.
 
 The advantage of this approach is that all information needed for horizontal interpolation is available without
 any MPP communication.
-Of course, this is under the assumption that we are only using a $2 \times 2$ grid-point stencil for
+This is under the assumption that we are dealing with point observations and only using a $2 \times 2$ grid-point stencil for
 the interpolation (\eg bilinear interpolation).
 For higher order interpolation schemes this is no longer valid.
@@ -801,5 +818,5 @@
 \begin{figure}
   \begin{center}
-    \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_ASM_obsdist_global}
+    \includegraphics[width=\textwidth]{Fig_ASM_obsdist_global}
     \caption{
       \protect\label{fig:obsglobal}
@@ -827,87 +844,70 @@
 At the bottom boundary, this is done using the land-ocean mask.
 
+For profile observation types we do both vertical and horizontal interpolation. \NEMO has a generalised vertical coordinate system this means the vertical level depths can vary with location. Therefore, it is necessary first to perform vertical interpolation of the model value to the observation depths for each of the four surrounding grid points. After this the model values, at these points, at the observation depth, are horizontally interpolated to the observation location.
+
 \newpage
 
 % ================================================================
-% Offline observation operator documentation
+% Standalone observation operator documentation
 % ================================================================
 
 %\usepackage{framed}
 
-\section{Offline observation operator}
-\label{sec:OBS_ooo}
+\section{Standalone observation operator}
+\label{sec:OBS_sao}
 
 \subsection{Concept}
 
-The obs oper maps model variables to observation space.
-It is possible to apply this mapping without running the model.
-The software which performs this functionality is known as the \textbf{offline obs oper}.
-The obs oper is divided into three stages.
-An initialisation phase, an interpolation phase and an output phase.
-The implementation of which is outlined in the previous sections.
-During the interpolation phase the offline obs oper populates the model arrays by
-reading saved model fields from disk.
-
-There are two ways of exploiting this offline capacity.
+The observation operator maps model variables to observation space. This is normally done while the model is running, i.e. online, it is possible to apply this mapping offline without running the model with the \textbf{standalone observation operator} (SAO). The process is divided into an initialisation phase, an interpolation phase and an output phase.
+During the interpolation phase the SAO populates the model arrays by
+reading saved model fields from disk. The interpolation and the output phases use the same OBS code described in the preceding sections.
+
+There are two ways of exploiting the standalone capacity.
 The first is to mimic the behaviour of the online system by supplying model fields at
 regular intervals between the start and the end of the run.
 This approach results in a single model counterpart per observation.
-This kind of usage produces feedback files the same file format as the online obs oper.
-The second is to take advantage of the offline setting in which
-multiple model counterparts can be calculated per observation.
+This kind of usage produces feedback files the same file format as the online observation operator.
+The second is to take advantage of the ability to run offline by calculating
+multiple model counterparts for each observation.
 In this case it is possible to consider all forecasts verifying at the same time.
-By forecast, I mean any method which produces an estimate of physical reality which is not an observed value.
-In the case of class 4 files this means forecasts, analyses, persisted analyses and
-climatological values verifying at the same time.
-Although the class 4 file format doesn't account for multiple ensemble members or
-multiple experiments per observation, it is possible to include these components in the same or multiple files.
+By forecast, we mean any method which produces an estimate of physical reality which is not an observed value.
 
 %--------------------------------------------------------------------------------------------------------
-% offline_oper.exe 
+% sao.exe
 %--------------------------------------------------------------------------------------------------------
 
-\subsection{Using the offline observation operator}
+\subsection{Using the standalone observation operator}
 
 \subsubsection{Building}
 
-In addition to \emph{OPA\_SRC} the offline obs oper requires the inclusion of the \emph{OOO\_SRC} directory.
-\emph{OOO\_SRC} contains a replacement \mdl{nemo} and \mdl{nemogcm} which
+In addition to \emph{OPA\_SRC} the SAO requires the inclusion of the \emph{SAO\_SRC} directory.
+\emph{SAO\_SRC} contains a replacement \mdl{nemo} and \mdl{nemogcm} which
 overwrites the resultant \textbf{nemo.exe}.
-This is the approach taken by \emph{SAS\_SRC} and \emph{OFF\_SRC}.
+Note this a similar approach to that taken by the standalone surface scheme \emph{SAS\_SRC} and the offline TOP model \emph{OFF\_SRC}.
 
 %--------------------------------------------------------------------------------------------------------
-% Running 
+% Running
 %--------------------------------------------------------------------------------------------------------
 \subsubsection{Running}
 
-The simplest way to use the executable is to edit and append the \textbf{ooo.nml} namelist to
-a full NEMO namelist and then to run the executable as if it were nemo.exe. 
-
-\subsubsection{Quick script}
-
-A useful Python utility to control the namelist options can be found in \textbf{OBSTOOLS/OOO}.
-The functions which locate model fields and observation files can be manually specified.
-The package can be installed by appropriate use of the included setup.py script.
-
-Documentation can be auto-generated by Sphinx by running \emph{make html} in the \textbf{doc} directory.
+The simplest way to use the executable is to edit and append the \textbf{sao.nml} namelist to
+a full \NEMO namelist and then to run the executable as if it were nemo.exe.
 
 %--------------------------------------------------------------------------------------------------------
 % Configuration section
 %--------------------------------------------------------------------------------------------------------
-\subsection{Configuring the offline observation operator}
-The observation files and settings understood by \textbf{namobs} have been outlined in the online obs oper section.
-In addition there are two further namelists wich control the operation of the offline obs oper.
-\textbf{namooo} which controls the input model fields and \textbf{namcl4} which
-controls the production of class 4 files. 
+\subsection{Configuring the standalone observation operator}
+The observation files and settings understood by \ngn{namobs} have been outlined in the online observation operator section.
+In addition is a further namelist \ngn{namsao} which used to set the input model fields for the SAO
 
 \subsubsection{Single field}
 
-In offline mode model arrays are populated at appropriate time steps via input files.
-At present, \textbf{tsn} and \textbf{sshn} are populated by the default read routines. 
+In the SAO the model arrays are populated at appropriate time steps via input files.
+At present, \textbf{tsn} and \textbf{sshn} are populated by the default read routines.
 These routines will be expanded upon in future versions to allow the specification of any model variable.
 As such, input files must be global versions of the model domain with
 \textbf{votemper}, \textbf{vosaline} and optionally \textbf{sshn} present.
 
-For each field read there must be an entry in the \textbf{namooo} namelist specifying
+For each field read there must be an entry in the \ngn{namsao} 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.
@@ -915,11 +915,11 @@
 \begin{forlines}
 !----------------------------------------------------------------------
-!       namooo Offline obs_oper namelist
+!       namsao Standalone obs_oper namelist
 !----------------------------------------------------------------------
-!   ooo_files    specifies the files containing the model counterpart
-!   nn_ooo_idx   specifies the time_counter index within the model file
-&namooo
-   ooo_files = "foo.nc"
-   nn_ooo_idx = 2
+!   sao_files    specifies the files containing the model counterpart
+!   nn_sao_idx   specifies the time_counter index within the model file
+&namsao
+   sao_files = "foo.nc"
+   nn_sao_idx = 2
 /
 \end{forlines}
@@ -927,5 +927,5 @@
 \subsubsection{Multiple fields per run}
 
-Model field iteration is controlled via \textbf{nn\_ooo\_freq} which
+Model field iteration is controlled via \textbf{nn\_sao\_freq} which
 specifies the number of model steps at which the next field gets read.
 For example, if 12 hourly fields are to be interpolated in a setup where 288 steps equals 24 hours.
@@ -933,13 +933,13 @@
 \begin{forlines}
 !----------------------------------------------------------------------
-!       namooo Offline obs_oper namelist
+!       namsao Standalone obs_oper namelist
 !----------------------------------------------------------------------
-!   ooo_files    specifies the files containing the model counterpart
-!   nn_ooo_idx   specifies the time_counter index within the model file
-!   nn_ooo_freq  specifies number of time steps between read operations
-&namooo
-   ooo_files = "foo.nc" "foo.nc"
-   nn_ooo_idx = 1 2
-   nn_ooo_freq = 144
+!   sao_files    specifies the files containing the model counterpart
+!   nn_sao_idx   specifies the time_counter index within the model file
+!   nn_sao_freq  specifies number of time steps between read operations
+&namsao
+   sao_files = "foo.nc" "foo.nc"
+   nn_sao_idx = 1 2
+   nn_sao_freq = 144
 /
 \end{forlines}
@@ -952,208 +952,11 @@
 %\end{framed}
 
-It is easy to see how a collection of fields taken fron a number of files at different indices can be combined at
+A collection of fields taken from a number of files at different indices can be combined at
 a particular frequency in time to generate a pseudo model evolution.
-As long as all that is needed is a single model counterpart at a regular interval then
-namooo is all that needs to be edited.
-However, a far more interesting approach can be taken in which multiple forecasts, analyses, persisted analyses and
-climatologies are considered against the same set of observations.
-For this a slightly more complicated approach is needed.
-It is referred to as \emph{Class 4} since it is the fourth metric defined by the GODAE intercomparison project.
-
-%--------------------------------------------------------------------------------------------------------
-% Class 4 file section
-%--------------------------------------------------------------------------------------------------------
-\subsubsection{Multiple model counterparts per observation a.k.a Class 4}
-
-A generalisation of feedback files to allow multiple model components per observation.
-For a single observation, as well as previous forecasts verifying at the same time
-there are also analyses, persisted analyses and climatologies. 
-
-
-The above namelist performs two basic functions.
-It organises the fields given in \textbf{namooo} into groups so that observations can be matched up multiple times.
-It also controls the metadata and the output variable of the class 4 file when a write routine is called.
-
-%\begin{framed}
-\textbf{Note: ln\_cl4} must be set to \forcode{.true.} in \textbf{namobs} to use class 4 outputs.
-%\end{framed}
-
-\subsubsection{Class 4 naming convention}
-
-The standard class 4 file naming convention is as follows.
-
-\noindent
-\linebreak
-\textbf{\$\{prefix\}\_\$\{yyyymmdd\}\_\$\{sys\}\_\$\{cfg\}\_\$\{vn\}\_\$\{kind\}\_\$\{nproc\}}.nc
-
-\noindent
-\linebreak
-Much of the namelist is devoted to specifying this convention.
-The following namelist settings control the elements of the output file names.
-Each should be specified as a single string of character data.
-
-\begin{description}
-\item[cl4\_prefix]
-  Prefix for class 4 files \eg class4
-\item[cl4\_date]
-  YYYYMMDD validity date
-\item[cl4\_sys]
-  The name of the class 4 model system \eg FOAM
-\item[cl4\_cfg]
-  The name of the class 4 model configuration \eg orca025
-\item[cl4\_vn]
-  The name of the class 4 model version \eg 12.0
-\end{description}
-
-\noindent
-The kind is specified by the observation type internally to the obs oper.
-The processor number is specified internally in NEMO. 
-
-\subsubsection{Class 4 file global attributes}
-
-Global attributes necessary to fulfill the class 4 file definition.
-These are also useful pieces of information when collaborating with external partners.
-
-\begin{description}
-\item[cl4\_contact]
-  Contact email for class 4 files.
-\item[cl4\_inst]
-  The name of the producers institution.
-\item[cl4\_cfg]
-  The name of the class 4 model configuration \eg orca025
-\item[cl4\_vn]
-  The name of the class 4 model version \eg 12.0
-\end{description}
-
-\noindent
-The obs\_type, creation date and validity time are specified internally to the obs oper.
-
-\subsubsection{Class 4 model counterpart configuration}
-
-As seen previously it is possible to perform a single sweep of the obs oper and
-specify a collection of model fields equally spaced along that sweep.
-In the class 4 case the single sweep is replaced with multiple sweeps and
-a certain ammount of book keeping is needed to ensure each model counterpart makes its way to
-the correct piece of memory in the output files.
-
-\noindent
-\linebreak
-In terms of book keeping, the offline obs oper needs to know how many full sweeps need to be performed.
-This is specified via the \textbf{cl4\_match\_len} variable and
-is the total number of model counterparts per observation.
-For example, a 3 forecasts plus 3 persistence fields plus an analysis field would be 7 counterparts per observation.
-
-\begin{forlines}
-   cl4_match_len = 7
-\end{forlines}
-
-Then to correctly allocate a class 4 file the forecast axis must be defined.
-This is controlled via \textbf{cl4\_fcst\_len}, which in out above example would be 3.
-
-\begin{forlines}
-   cl4_fcst_len = 3
-\end{forlines}
-
-Then for each model field it is necessary to designate what class 4 variable and index along
-the forecast dimension the model counterpart should be stored in the output file.
-As well as a value for that lead time in hours, this will be useful when interpreting the data afterwards. 
-
-\begin{forlines}
-   cl4_vars = "forecast" "forecast" "forecast" "persistence" "persistence"
-              "persistence" "best_estimate"
-   cl4_fcst_idx = 1 2 3 1 2 3 1
-   cl4_leadtime = 12 36 60 
-\end{forlines}
-
-In terms of files and indices of fields inside each file the class 4 approach makes use of
-the \textbf{namooo} namelist.
-If our fields are in separate files with a single field per file our example inputs will be specified.
-
-\begin{forlines}
-   ooo_files = "F.1.nc" "F.2.nc" "F.3.nc" "P.1.nc" "P.2.nc" "P.3.nc" "A.1.nc"
-   nn_ooo_idx = 1 1 1 1 1 1 1
-\end{forlines}
-
-When we combine all of the naming conventions, global attributes and i/o instructions the class 4 namelist becomes.
-
-\begin{forlines}
-!----------------------------------------------------------------------
-!       namooo Offline obs_oper namelist
-!----------------------------------------------------------------------
-!   ooo_files    specifies the files containing the model counterpart
-!   nn_ooo_idx   specifies the time_counter index within the model file
-!   nn_ooo_freq  specifies number of time steps between read operations
-&namooo
-   ooo_files = "F.1.nc" "F.2.nc" "F.3.nc" "P.1.nc" "P.2.nc" "P.3.nc" "A.1.nc"
-   nn_ooo_idx = 1 1 1 1 1 1 1
-/
-!----------------------------------------------------------------------
-!       namcl4 Offline obs_oper class 4 namelist
-!----------------------------------------------------------------------
-!
-!  Naming convention
-!  -----------------
-!  cl4_prefix    specifies the output file prefix
-!  cl4_date      specifies the output file validity date
-!  cl4_sys       specifies the model counterpart system
-!  cl4_cfg       specifies the model counterpart configuration
-!  cl4_vn        specifies the model counterpart version
-!  cl4_inst      specifies the model counterpart institute
-!  cl4_contact   specifies the file producers contact details
-!
-!  I/O specification
-!  -----------------
-!  cl4_vars      specifies the names of the output file netcdf variable
-!  cl4_fcst_idx  specifies output file forecast index
-!  cl4_fcst_len  specifies forecast axis length
-!  cl4_match_len specifies number of unique matches per observation
-!  cl4_leadtime  specifies the forecast axis lead time 
-!
-&namcl4
-   cl4_match_len = 7
-   cl4_fcst_len = 3
-   cl4_fcst_idx = 1 2 3 1 2 3 1
-   cl4_vars = "forecast" "forecast" "forecast" "persistence" "persistence"
-              "persistence" "best_estimate"
-   cl4_leadtime = 12 36 60
-   cl4_prefix = "class4"
-   cl4_date = "20130101"
-   cl4_vn = "12.0"
-   cl4_sys = "FOAM"
-   cl4_cfg = "AMM7"
-   cl4_contact = "example@example.com"
-   cl4_inst = "UK Met Office"
-/
-\end{forlines}
-
-\subsubsection{Climatology interpolation}
-
-The climatological counterpart is generated at the start of the run by
-restarting the model from climatology through appropriate use of \textbf{namtsd}.
-To override the offline observation operator read routine and to take advantage of the restart settings,
-specify the first entry in \textbf{cl4\_vars} as "climatology".
-This will then pipe the restart from climatology into the output class 4 file.
-As in every other class 4 matchup the input file, input index and output index must be specified.
-These can be replaced with dummy data since they are not used but
-they must be present to cycle through the matchups correctly. 
-
-\subsection{Advanced usage}
-
-In certain cases it may be desirable to include both multiple model fields per observation window with
-multiple match ups per observation.
-This can be achieved by specifying \textbf{nn\_ooo\_freq} as well as the class 4 settings.
-Care must be taken in generating the ooo\_files list such that the files are arranged into
-consecutive blocks of single match ups.
-For example, 2 forecast fields of 12 hourly data would result in 4 separate read operations but
-only 2 write operations, 1 per forecast.
-
-\begin{forlines}
-   ooo_files = "F1.nc" "F1.nc" "F2.nc" "F2.nc"
-...
-   cl4_fcst_idx = 1 2
-\end{forlines}
-
-The above notation reveals the internal split between match up iterators and file iterators.
-This technique has not been used before so experimentation is needed before results can be trusted.
+If all that is needed is a single model counterpart at a regular interval then
+the standard SAO is all that is required.
+However, just to note, it is possible to extend this approach by comparing multiple forecasts, analyses, persisted analyses and
+climatologies with the same set of observations.
+This approach is referred to as \emph{Class 4} since it is the fourth metric defined by the GODAE intercomparison project. This requires multiple runs of the SAO and running an additional utility (not currently in the \NEMO repository) to combine the feedback files into one class 4 file.
 
 \newpage
@@ -1162,10 +965,10 @@
 \label{sec:OBS_obsutils}
 
-Some tools for viewing and processing of observation and feedback files are provided in
-the NEMO repository for convenience.
-These include OBSTOOLS which are a collection of \fortran programs which are helpful to deal with feedback files.
+For convenience some tools for viewing and processing of observation and feedback files are provided in
+the \NEMO repository.
+These tools include OBSTOOLS which are a collection of \fortran programs which are helpful to deal with feedback files.
 They do such tasks as observation file conversion, printing of file contents,
 some basic statistical analysis of feedback files.
-The other tool is an IDL program called dataplot which uses a graphical interface to
+The other main tool is an IDL program called dataplot which uses a graphical interface to
 visualise observations and feedback files.
 OBSTOOLS and dataplot are described in more detail below.
@@ -1173,26 +976,12 @@
 \subsection{Obstools}
 
-A series of \fortran utilities is provided with NEMO called OBSTOOLS.
-This are helpful in handling observation files and the feedback file output from the NEMO observation operator.
-The utilities are as follows
-
-\subsubsection{c4comb}
-
-The program c4comb combines multiple class 4 files produced by individual processors in
-an MPI run of NEMO offline obs\_oper into a single class 4 file.
-The program is called in the following way:
-
-
-\footnotesize
-\begin{cmds}
-c4comb.exe outputfile inputfile1 inputfile2 ...
-\end{cmds}
+A series of \fortran utilities is provided with \NEMO called OBSTOOLS.
+This are helpful in handling observation files and the feedback file output from the observation operator. A brief description of some of the utilities follows
 
 \subsubsection{corio2fb}
 
 The program corio2fb converts profile observation files from the Coriolis format to the standard feedback format.
-The program is called in the following way:
-
-\footnotesize
+It is called in the following way:
+
 \begin{cmds}
 corio2fb.exe outputfile inputfile1 inputfile2 ...
@@ -1202,7 +991,6 @@
 
 The program enact2fb converts profile observation files from the ENACT format to the standard feedback format.
-The program is called in the following way:
-
-\footnotesize
+It is called in the following way:
+
 \begin{cmds}
 enact2fb.exe outputfile inputfile1 inputfile2 ...
@@ -1212,8 +1000,7 @@
 
 The program fbcomb combines multiple feedback files produced by individual processors in
-an MPI run of NEMO into a single feedback file.
-The program is called in the following way:
-
-\footnotesize
+an MPI run of \NEMO into a single feedback file.
+It is called in the following way:
+
 \begin{cmds}
 fbcomb.exe outputfile inputfile1 inputfile2 ...
@@ -1223,7 +1010,6 @@
 
 The program fbmatchup will match observations from two feedback files.
-The program is called in the following way:
-
-\footnotesize
+It is called in the following way:
+
 \begin{cmds}
 fbmatchup.exe outputfile inputfile1 varname1 inputfile2 varname2 ...
@@ -1234,7 +1020,6 @@
 The program fbprint will print the contents of a feedback file or files to standard output.
 Selected information can be output using optional arguments.
-The program is called in the following way:
-
-\footnotesize
+It is called in the following way:
+
 \begin{cmds}
 fbprint.exe [options] inputfile
@@ -1246,11 +1031,11 @@
      -B            Select observations based on QC flags
      -u            unsorted
-     -s ID         select station ID  
+     -s ID         select station ID
      -t TYPE       select observation type
-     -v NUM1-NUM2  select variable range to print by number 
+     -v NUM1-NUM2  select variable range to print by number
                       (default all)
-     -a NUM1-NUM2  select additional variable range to print by number 
+     -a NUM1-NUM2  select additional variable range to print by number
                       (default all)
-     -e NUM1-NUM2  select extra variable range to print by number 
+     -e NUM1-NUM2  select extra variable range to print by number
                       (default all)
      -d            output date range
@@ -1262,7 +1047,6 @@
 
 The program fbsel will select or subsample observations.
-The program is called in the following way:
-
-\footnotesize
+It is called in the following way:
+
 \begin{cmds}
 fbsel.exe <input filename> <output filename>
@@ -1272,7 +1056,6 @@
 
 The program fbstat will output summary statistics in different global areas into a number of files.
-The program is called in the following way:
-
-\footnotesize
+It is called in the following way:
+
 \begin{cmds}
 fbstat.exe [-nmlev] <filenames>
@@ -1283,7 +1066,6 @@
 The program fbthin will thin the data to 1 degree resolution.
 The code could easily be modified to thin to a different resolution.
-The program is called in the following way:
-
-\footnotesize
+It is called in the following way:
+
 \begin{cmds}
 fbthin.exe inputfile outputfile
@@ -1293,7 +1075,6 @@
 
 The program sla2fb will convert an AVISO SLA format file to feedback format.
-The program is called in the following way:
-
-\footnotesize
+It is called in the following way:
+
 \begin{cmds}
 sla2fb.exe [-s type] outputfile inputfile1 inputfile2 ...
@@ -1306,7 +1087,6 @@
 
 The program vel2fb will convert TAO/PIRATA/RAMA currents files to feedback format.
-The program is called in the following way:
-
-\footnotesize
+It is called in the following way:
+
 \begin{cmds}
 vel2fb.exe outputfile inputfile1 inputfile2 ...
@@ -1320,8 +1100,9 @@
 
 An IDL program called dataplot is included which uses a graphical interface to
-visualise observations and feedback files.
+visualise observations and feedback files. Note a similar package has recently developed in python (also called dataplot) which does some of the same things that the IDL dataplot does. Please contact the authors of the this chapter if you are interested in this.
+
 It is possible to zoom in, plot individual profiles and calculate some basic statistics.
 To plot some data run IDL and then:
-\footnotesize
+
 \begin{minted}{idl}
 IDL> dataplot, "filename"
@@ -1331,5 +1112,5 @@
 for example multiple feedback files from different processors or from different days,
 the easiest method is to use the spawn command to generate a list of files which can then be passed to dataplot.
-\footnotesize
+
 \begin{minted}{idl}
 IDL> spawn, 'ls profb*.nc', files
@@ -1350,5 +1131,5 @@
 The plotting colour range can be changed by clicking on the colour bar.
 The title of the plot gives some basic information about the date range and depth range shown,
-the extreme values, and the mean and rms values.
+the extreme values, and the mean and RMS values.
 It is possible to zoom in using a drag-box.
 You may also zoom in or out using the mouse wheel.
@@ -1362,5 +1143,5 @@
 observation minus background value.
 The next group of radio buttons selects the map projection.
-This can either be regular latitude longitude grid, or north or south polar stereographic.
+This can either be regular longitude latitude grid, or north or south polar stereographic.
 The next group of radio buttons will plot bad observations, switch to salinity and
 plot density for profile observations.
@@ -1370,6 +1151,6 @@
 \begin{figure}
   \begin{center}
-    % \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_OBS_dataplot_main}
-    \includegraphics[width=9cm,angle=-90.]{Fig_OBS_dataplot_main}
+    % \includegraphics[width=\textwidth]{Fig_OBS_dataplot_main}
+    \includegraphics[width=\textwidth]{Fig_OBS_dataplot_main}
     \caption{
       \protect\label{fig:obsdataplotmain}
@@ -1386,6 +1167,6 @@
 \begin{figure}
   \begin{center}
-    % \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_OBS_dataplot_prof}
-    \includegraphics[width=7cm,angle=-90.]{Fig_OBS_dataplot_prof}
+    % \includegraphics[width=\textwidth]{Fig_OBS_dataplot_prof}
+    \includegraphics[width=\textwidth]{Fig_OBS_dataplot_prof}
     \caption{
       \protect\label{fig:obsdataplotprofile}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_SBC.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_SBC.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_SBC.tex	(revision 11422)
@@ -2,8 +2,9 @@
 
 \begin{document}
-% ================================================================
-% Chapter —— Surface Boundary Condition (SBC, ISF, ICB) 
-% ================================================================
-\chapter{Surface Boundary Condition (SBC, ISF, ICB) }
+
+% ================================================================
+% Chapter —— Surface Boundary Condition (SBC, SAS, ISF, ICB) 
+% ================================================================
+\chapter{Surface Boundary Condition (SBC, SAS, ISF, ICB)}
 \label{chap:SBC}
 \minitoc
@@ -16,5 +17,6 @@
 %--------------------------------------------------------------------------------------------------------------
 
-The ocean needs six fields as surface boundary condition:
+The ocean needs seven fields as surface boundary condition:
+
 \begin{itemize}
 \item
@@ -26,66 +28,85 @@
 \item
   the surface salt flux associated with freezing/melting of seawater $\left( {\textit{sfx}} \right)$
+\item
+  the atmospheric pressure at the ocean surface $\left( p_a \right)$
 \end{itemize}
-plus an optional field:
+
+Four different ways are available to provide the seven fields to the ocean. They are controlled by
+namelist \ngn{namsbc} variables:
+
 \begin{itemize}
-	\item the atmospheric pressure at the ocean surface $\left( p_a \right)$
+\item
+  a bulk formulation (\np{ln\_blk}\forcode{ = .true.} with four possible bulk algorithms),
+\item
+  a flux formulation (\np{ln\_flx}\forcode{ = .true.}),
+\item
+  a coupled or mixed forced/coupled formulation (exchanges with a atmospheric model via the OASIS coupler),
+(\np{ln\_cpl} or \np{ln\_mixcpl}\forcode{ = .true.}),
+\item
+  a user defined formulation (\np{ln\_usr}\forcode{ = .true.}).
 \end{itemize}
 
-Four different ways to provide the first six fields to the ocean are available which are controlled by
-namelist \ngn{namsbc} variables:
-an analytical formulation (\np{ln\_ana}\forcode{ = .true.}),
-a flux formulation (\np{ln\_flx}\forcode{ = .true.}),
-a bulk formulae formulation (CORE (\np{ln\_blk\_core}\forcode{ = .true.}),
-CLIO (\np{ln\_blk\_clio}\forcode{ = .true.}) bulk formulae) and
-a coupled or mixed forced/coupled formulation (exchanges with a atmospheric model via the OASIS coupler)
-(\np{ln\_cpl} or \np{ln\_mixcpl}\forcode{ = .true.}). 
-When used (\ie \np{ln\_apr\_dyn}\forcode{ = .true.}),
-the atmospheric pressure forces both ocean and ice dynamics.
 
 The frequency at which the forcing fields have to be updated is given by the \np{nn\_fsbc} namelist parameter.
-When the fields are supplied from data files (flux and bulk formulations),
-the input fields need not be supplied on the model grid.
-Instead a file of coordinates and weights can be supplied which maps the data from the supplied grid to
+
+When the fields are supplied from data files (bulk, flux and mixed formulations),
+the input fields do not need to be supplied on the model grid.
+Instead, a file of coordinates and weights can be supplied to map the data from the input fields grid to
 the model points (so called "Interpolation on the Fly", see \autoref{subsec:SBC_iof}).
-If the Interpolation on the Fly option is used, input data belonging to land points (in the native grid),
-can be masked to avoid spurious results in proximity of the coasts as
+If the "Interpolation on the Fly" option is used, input data belonging to land points (in the native grid)
+should be masked or filled to avoid spurious results in proximity of the coasts, as
 large sea-land gradients characterize most of the atmospheric variables.
 
 In addition, the resulting fields can be further modified using several namelist options.
-These options control 
+These options control:
+
 \begin{itemize}
 \item
   the rotation of vector components supplied relative to an east-north coordinate system onto
-  the local grid directions in the model;
-\item
-  the addition of a surface restoring term to observed SST and/or SSS (\np{ln\_ssr}\forcode{ = .true.});
-\item
-  the modification of fluxes below ice-covered areas (using observed ice-cover or a sea-ice model)
-  (\np{nn\_ice}\forcode{ = 0..3});
-\item
-  the addition of river runoffs as surface freshwater fluxes or lateral inflow (\np{ln\_rnf}\forcode{ = .true.});
-\item
-  the addition of isf melting as lateral inflow (parameterisation) or
-  as fluxes applied at the land-ice ocean interface (\np{ln\_isf}) ; 
+  the local grid directions in the model,
+\item
+  the use of a land/sea mask for input fields (\np{nn\_lsm}\forcode{ = .true.}),
+\item
+  the addition of a surface restoring term to observed SST and/or SSS (\np{ln\_ssr}\forcode{ = .true.}),
+\item
+  the modification of fluxes below ice-covered areas (using climatological ice-cover or a sea-ice model)
+  (\np{nn\_ice}\forcode{ = 0..3}),
+\item
+  the addition of river runoffs as surface freshwater fluxes or lateral inflow (\np{ln\_rnf}\forcode{ = .true.}),
+\item
+  the addition of ice-shelf melting as lateral inflow (parameterisation) or
+  as fluxes applied at the land-ice ocean interface (\np{ln\_isf}\forcode{ = .true.}),
 \item
   the addition of a freshwater flux adjustment in order to avoid a mean sea-level drift
-  (\np{nn\_fwb}\forcode{ = 0..2});
-\item
-  the transformation of the solar radiation (if provided as daily mean) into a diurnal cycle
-  (\np{ln\_dm2dc}\forcode{ = .true.});
-\item
-  a neutral drag coefficient can be read from an external wave model (\np{ln\_cdgw}\forcode{ = .true.});
-\item
-  the Stokes drift rom an external wave model can be accounted (\np{ln\_sdw}\forcode{ = .true.}); 
-\item
-  the Stokes-Coriolis term can be included (\np{ln\_stcor}\forcode{ = .true.});
-\item
-  the surface stress felt by the ocean can be modified by surface waves (\np{ln\_tauwoc}\forcode{ = .true.}).
+  (\np{nn\_fwb}\forcode{ = 0..2}),
+\item
+  the transformation of the solar radiation (if provided as daily mean) into an analytical diurnal cycle
+  (\np{ln\_dm2dc}\forcode{ = .true.}),
+\item
+  the activation of wave effects from an external wave model  (\np{ln\_wave}\forcode{ = .true.}),
+\item
+  a neutral drag coefficient is read from an external wave model (\np{ln\_cdgw}\forcode{ = .true.}),
+\item
+  the Stokes drift from an external wave model is accounted for (\np{ln\_sdw}\forcode{ = .true.}), 
+\item
+  the choice of the Stokes drift profile parameterization (\np{nn\_sdrift}\forcode{ = 0..2}), 
+\item
+  the surface stress given to the ocean is modified by surface waves (\np{ln\_tauwoc}\forcode{ = .true.}),
+\item
+  the surface stress given to the ocean is read from an external wave model (\np{ln\_tauw}\forcode{ = .true.}),
+\item
+  the Stokes-Coriolis term is included (\np{ln\_stcor}\forcode{ = .true.}),
+\item
+  the light penetration in the ocean (\np{ln\_traqsr}\forcode{ = .true.} with namelist \ngn{namtra\_qsr}),
+\item
+  the atmospheric surface pressure gradient effect on ocean and ice dynamics (\np{ln\_apr\_dyn}\forcode{ = .true.} with namelist \ngn{namsbc\_apr}),
+\item
+  the effect of sea-ice pressure on the ocean (\np{ln\_ice\_embd}\forcode{ = .true.}).
 \end{itemize}
 
-In this chapter, we first discuss where the surface boundary condition appears in the model equations.
-Then we present the five ways of providing the surface boundary condition, 
+In this chapter, we first discuss where the surface boundary conditions appear in the model equations.
+Then we present the three ways of providing the surface boundary conditions, 
 followed by the description of the atmospheric pressure and the river runoff. 
-Next the scheme for interpolation on the fly is described.
+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}),
@@ -95,9 +116,10 @@
 
 
+
 % ================================================================
 % Surface boundary condition for the ocean
 % ================================================================
 \section{Surface boundary condition for the ocean}
-\label{sec:SBC_general}
+\label{sec:SBC_ocean}
 
 The surface ocean stress is the stress exerted by the wind and the sea-ice on the ocean.
@@ -111,10 +133,10 @@
 The former is the non penetrative part of the heat flux
 (\ie the sum of sensible, latent and long wave heat fluxes plus
-the heat content of the mass exchange with the atmosphere and sea-ice).
+the heat content of the mass exchange between the ocean and sea-ice).
 It is applied in \mdl{trasbc} module as a surface boundary condition trend of
 the first level temperature time evolution equation
-(see \autoref{eq:tra_sbc} and \autoref{eq:tra_sbc_lin} in \autoref{subsec:TRA_sbc}). 
+(see \autoref{eq:tra_sbc} and \autoref{eq:tra_sbc_lin} in \autoref{subsec:TRA_sbc}).
 The latter is the penetrative part of the heat flux.
-It is applied as a 3D trends of the temperature equation (\mdl{traqsr} module) when
+It is applied as a 3D trend of the temperature equation (\mdl{traqsr} module) when
 \np{ln\_traqsr}\forcode{ = .true.}.
 The way the light penetrates inside the water column is generally a sum of decreasing exponentials
@@ -124,9 +146,9 @@
 It represents the mass flux exchanged with the atmosphere (evaporation minus precipitation) and
 possibly with the sea-ice and ice shelves (freezing minus melting of ice).
-It affects both the ocean in two different ways:
-$(i)$  it changes the volume of the ocean and therefore appears in the sea surface height equation as
+It affects the ocean in two different ways:
+$(i)$  it changes the volume of the ocean, and therefore appears in the sea surface height equation as		%GS: autoref ssh equation to be added
 a volume flux, and 
 $(ii)$ it changes the surface temperature and salinity through the heat and salt contents of
-the mass exchanged with the atmosphere, the sea-ice and the ice shelves. 
+the mass exchanged with atmosphere, sea-ice and ice shelves.
 
 
@@ -157,5 +179,5 @@
 the surface currents, temperature and salinity.  
 These variables are averaged over \np{nn\_fsbc} time-step (\autoref{tab:ssm}), and
-it is these averaged fields which are used to computes the surface fluxes at a frequency of \np{nn\_fsbc} time-step.
+these averaged fields are used to compute the surface fluxes at the frequency of \np{nn\_fsbc} time-steps.
 
 
@@ -165,14 +187,14 @@
     \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
+      Variable description			                  & Model variable	& Units	& point                 \\\hline
+      i-component of the surface current	& ssu\_m	              & $m.s^{-1}$	    & U     \\\hline
+      j-component of the surface current	& ssv\_m	              & $m.s^{-1}$	    & V     \\	\hline
+      Sea surface temperature			         & sst\_m	              & \r{}$K$	             & T     \\\hline
+      Sea surface salinty			                  & sss\_m	              & $psu$		        & T     \\	\hline
     \end{tabular}
     \caption{
       \protect\label{tab:ssm}
       Ocean variables provided by the ocean to the surface module (SBC).
-      The variable are averaged over nn{\_}fsbc time step,
+      The variable are averaged over \np{nn\_fsbc} time-step,
       \ie the frequency of computation of surface fluxes.
     }
@@ -184,4 +206,5 @@
 
 
+
 % ================================================================
 %       Input Data 
@@ -191,10 +214,10 @@
 
 A generic interface has been introduced to manage the way input data
-(2D or 3D fields, like surface forcing or ocean T and S) are specify in \NEMO.
-This task is archieved by \mdl{fldread}.
-The module was design with four main objectives in mind: 
+(2D or 3D fields, like surface forcing or ocean T and S) are specified in \NEMO.
+This task is achieved by \mdl{fldread}.
+The module is designed with four main objectives in mind: 
 \begin{enumerate}
 \item
-  optionally provide a time interpolation of the input data at model time-step, whatever their input frequency is,
+  optionally provide a time interpolation of the input data every specified model time-step, whatever their input frequency is,
   and according to the different calendars available in the model.
 \item
@@ -204,11 +227,11 @@
 \item
   provide a simple user interface and a rather simple developer interface by
-  limiting the number of prerequisite information. 
-\end{enumerate}  
-
-As a results the user have only to fill in for each variable a structure in the namelist file to
+  limiting the number of prerequisite informations. 
+\end{enumerate}
+
+As a result, the user has only to fill in for each variable a structure in the namelist file to
 define the input data file and variable names, the frequency of the data (in hours or months),
 whether its is climatological data or not, the period covered by the input file (one year, month, week or day),
-and three additional parameters for on-the-fly interpolation.
+and three additional parameters for the on-the-fly interpolation.
 When adding a new input variable, the developer has to add the associated structure in the namelist,
 read this information by mirroring the namelist read in \rou{sbc\_blk\_init} for example,
@@ -220,11 +243,13 @@
 
 Note that when an input data is archived on a disc which is accessible directly from the workspace where
-the code is executed, then the use can set the \np{cn\_dir} to the pathway leading to the data.
-By default, the data are assumed to have been copied so that cn\_dir='./'.
+the code is executed, then the user can set the \np{cn\_dir} to the pathway leading to the data.
+By default, the data are assumed to be in the same directory as the executable, so that cn\_dir='./'.
+
 
 % -------------------------------------------------------------------------------------------------------------
 % Input Data specification (\mdl{fldread})
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Input data specification (\protect\mdl{fldread})}
+\subsection[Input data specification (\textit{fldread.F90})]
+{Input data specification (\protect\mdl{fldread})}
 \label{subsec:SBC_fldread}
 
@@ -237,5 +262,5 @@
 \begin{description}  
 \item[File name]:
-  the stem name of the NetCDF file to be open.
+  the stem name of the NetCDF file to be opened.
   This stem will be completed automatically by the model, with the addition of a '.nc' at its end and
   by date information and possibly a prefix (when using AGRIF).
@@ -248,12 +273,12 @@
       \begin{tabular}{|l|c|c|c|}
         \hline
-        & daily or weekLLL	        & monthly                   &   yearly          \\   \hline
-        \np{clim}\forcode{ = .false.}	& fn\_yYYYYmMMdDD.nc  &   fn\_yYYYYmMM.nc   &   fn\_yYYYY.nc  \\   \hline
-        \np{clim}\forcode{ = .true.}	 	   & not possible 	              &  fn\_m??.nc             &   fn                \\   \hline
+                                        &  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, as a function of the Open/close frequency.
+      naming nomenclature for climatological or interannual input file(s), 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
@@ -262,5 +287,5 @@
       Note that (1) in mpp, if the file is split over each subdomain, the suffix '.nc' is replaced by '\_PPPP.nc',
       where 'PPPP' is the process number coded with 4 digits;
-      (2) when using AGRIF, the prefix '\_N' is added to files, where 'N'  is the child grid number.
+      (2) when using AGRIF, the prefix '\_N' is added to files, where 'N' is the child grid number.
     }
   \end{table}
@@ -272,6 +297,6 @@
   Its unit is in hours if it is positive (for example 24 for daily forcing) or in months if negative
   (for example -1 for monthly forcing or -12 for annual forcing).
-  Note that this frequency must really be an integer and not a real.
-  On some computers, seting it to '24.' can be interpreted as 240!
+  Note that this frequency must REALLY be an integer and not a real.
+  On some computers, setting it to '24.' can be interpreted as 240!
 
 \item[Variable name]:
@@ -284,5 +309,5 @@
   00h00'00'' to 23h59'59".
   If set to 'true', the forcing will have a broken line shape.
-  Records are assumed to be dated the middle of the forcing period.
+  Records are assumed to be dated at the middle of the forcing period.
   For example, when using a daily forcing with time interpolation,
   linear interpolation will be performed between mid-day of two consecutive days. 
@@ -291,6 +316,6 @@
   a logical to specify if a input file contains climatological forcing which can be cycle in time,
   or an interannual forcing which will requires additional files if
-  the period covered by the simulation exceed the one of the file.
-  See the above the file naming strategy which impacts the expected name of the file to be opened. 
+  the period covered by the simulation exceeds the one of the file.
+  See the above file naming strategy which impacts the expected name of the file to be opened. 
 
 \item[Open/close frequency]:
@@ -301,5 +326,5 @@
   Files are assumed to contain data from the beginning of the open/close period.
   For example, the first record of a yearly file containing daily data is Jan 1st even if
-  the experiment is not starting at the beginning of the year. 
+  the experiment is not starting at the beginning of the year.
 
 \item[Others]:
@@ -313,11 +338,11 @@
 The only tricky point is therefore to specify the date at which we need to do the interpolation and
 the date of the records read in the input files.
-Following \citet{Leclair_Madec_OM09}, the date of a time step is set at the middle of the time step.
-For example, for an experiment starting at 0h00'00" with a one hour time-step,
+Following \citet{leclair.madec_OM09}, the date of a time step is set at the middle of the time step.
+For example, for an experiment starting at 0h00'00" with a one-hour time-step,
 a time interpolation will be performed at the following time: 0h30'00", 1h30'00", 2h30'00", etc.
 However, for forcing data related to the surface module,
 values are not needed at every time-step but at every \np{nn\_fsbc} time-step.
 For example with \np{nn\_fsbc}\forcode{ = 3}, the surface module will be called at time-steps 1, 4, 7, etc.
-The date used for the time interpolation is thus redefined to be at the middle of \np{nn\_fsbc} time-step period.
+The date used for the time interpolation is thus redefined to the middle of \np{nn\_fsbc} time-step period.
 In the previous example, this leads to: 1h30'00", 4h30'00", 7h30'00", etc. \\ 
 (2) For code readablility and maintenance issues, we don't take into account the NetCDF input file calendar.
@@ -325,5 +350,5 @@
 user in the record frequency, the open/close frequency and the type of temporal interpolation.
 For example, the first record of a yearly file containing daily data that will be interpolated in time is assumed to
-be start Jan 1st at 12h00'00" and end Dec 31st at 12h00'00". \\
+start Jan 1st at 12h00'00" and end Dec 31st at 12h00'00". \\
 (3) If a time interpolation is requested, the code will pick up the needed data in the previous (next) file when
 interpolating data with the first (last) record of the open/close period.
@@ -333,7 +358,7 @@
 If the forcing is climatological, Dec and Jan will be keep-up from the same year.
 However, if the forcing is not climatological, at the end of
-the open/close period the code will automatically close the current file and open the next one.
+the open/close period, the code will automatically close the current file and open the next one.
 Note that, if the experiment is starting (ending) at the beginning (end) of
-an open/close period we do accept that the previous (next) file is not existing.
+an open/close period, we do accept that the previous (next) file is not existing.
 In this case, the time interpolation will be performed between two identical values.
 For example, when starting an experiment on Jan 1st of year Y with yearly files and daily data to be interpolated,
@@ -353,11 +378,11 @@
 Interpolation on the Fly allows the user to supply input files required for the surface forcing on
 grids other than the model grid.
-To do this he or she must supply, in addition to the source data file, a file of weights to be used to
+To do this, he or she must supply, in addition to the source data file(s), a file of weights to be used to
 interpolate from the data grid to the model grid.
 The original development of this code used the SCRIP package
 (freely available \href{http://climate.lanl.gov/Software/SCRIP}{here} under a copyright agreement).
-In principle, any package can be used to generate the weights, but the variables in
+In principle, any package such as CDO can be used to generate the weights, but the variables in
 the input weights file must have the same names and meanings as assumed by the model.
-Two methods are currently available: bilinear and bicubic interpolation.
+Two methods are currently available: bilinear and bicubic interpolations.
 Prior to the interpolation, providing a land/sea mask file, the user can decide to remove land points from
 the input file and substitute the corresponding values with the average of the 8 neighbouring points in
@@ -365,9 +390,13 @@
 Only "sea points" are considered for the averaging.
 The land/sea mask file must be provided in the structure associated with the input variable.
-The netcdf land/sea mask variable name must be 'LSM' it must have the same horizontal and vertical dimensions of
-the associated variable and should be equal to 1 over land and 0 elsewhere.
-The procedure can be recursively applied setting nn\_lsm > 1 in namsbc namelist.
-Note that nn\_lsm=0 forces the code to not apply the procedure even if a file for land/sea mask is supplied.
-
+The netcdf land/sea mask variable name must be 'LSM' and must have the same horizontal and vertical dimensions as
+the associated variables and should be equal to 1 over land and 0 elsewhere.
+The procedure can be recursively applied by setting nn\_lsm > 1 in namsbc namelist.
+Note that nn\_lsm=0 forces the code to not apply the procedure, even if a land/sea mask file is supplied.
+
+
+% -------------------------------------------------------------------------------------------------------------
+% Bilinear interpolation
+% -------------------------------------------------------------------------------------------------------------
 \subsubsection{Bilinear interpolation}
 \label{subsec:SBC_iof_bilinear}
@@ -375,5 +404,5 @@
 The input weights file in this case has two sets of variables:
 src01, src02, src03, src04 and wgt01, wgt02, wgt03, wgt04.
-The "src" variables correspond to the point in the input grid to which the weight "wgt" is to be applied.
+The "src" variables correspond to the point in the input grid to which the weight "wgt" is applied.
 Each src value is an integer corresponding to the index of a point in the input grid when
 written as a one dimensional array.
@@ -391,9 +420,13 @@
 and wgt(1) corresponds to variable "wgt01" for example.
 
+
+% -------------------------------------------------------------------------------------------------------------
+% Bicubic interpolation
+% -------------------------------------------------------------------------------------------------------------
 \subsubsection{Bicubic interpolation}
 \label{subsec:SBC_iof_bicubic}
 
-Again there are two sets of variables: "src" and "wgt".
-But in this case there are 16 of each.
+Again, there are two sets of variables: "src" and "wgt".
+But in this case, there are 16 of each.
 The symbolic algorithm used to calculate values on the model grid is now:
 
@@ -401,12 +434,16 @@
   \begin{split}
     f_{m}(i,j) =  f_{m}(i,j) +& \sum_{k=1}^{4} {wgt(k)f(idx(src(k)))}
-    +   \sum_{k=5}^{8} {wgt(k)\left.\frac{\partial f}{\partial i}\right| _{idx(src(k))} }    \\
-    +& \sum_{k=9}^{12} {wgt(k)\left.\frac{\partial f}{\partial j}\right| _{idx(src(k))} }
-    +   \sum_{k=13}^{16} {wgt(k)\left.\frac{\partial ^2 f}{\partial i \partial j}\right| _{idx(src(k))} }
+    +  \sum_{k=5 }^{8 } {wgt(k)\left.\frac{\partial f}{\partial i}\right| _{idx(src(k))} }    \\
+    +& \sum_{k=9 }^{12} {wgt(k)\left.\frac{\partial f}{\partial j}\right| _{idx(src(k))} }
+    +  \sum_{k=13}^{16} {wgt(k)\left.\frac{\partial ^2 f}{\partial i \partial j}\right| _{idx(src(k))} }
   \end{split}
 \]
 The gradients here are taken with respect to the horizontal indices and not distances since
-the spatial dependency has been absorbed into the weights.
-
+the spatial dependency has been included into the weights.
+
+
+% -------------------------------------------------------------------------------------------------------------
+% Implementation
+% -------------------------------------------------------------------------------------------------------------
 \subsubsection{Implementation}
 \label{subsec:SBC_iof_imp}
@@ -420,12 +457,12 @@
 inspecting a global attribute stored in the weights input file.
 This attribute must be called "ew\_wrap" and be of integer type.
-If it is negative, the input non-model grid is assumed not to be cyclic.
+If it is negative, the input non-model grid is assumed to be not cyclic.
 If zero or greater, then the value represents the number of columns that overlap.
 $E.g.$ if the input grid has columns at longitudes 0, 1, 2, .... , 359, then ew\_wrap should be set to 0;
 if longitudes are 0.5, 2.5, .... , 358.5, 360.5, 362.5, ew\_wrap should be 2.
 If the model does not find attribute ew\_wrap, then a value of -999 is assumed.
-In this case the \rou{fld\_read} routine defaults ew\_wrap to value 0 and
+In this case, the \rou{fld\_read} routine defaults ew\_wrap to value 0 and
 therefore the grid is assumed to be cyclic with no overlapping columns.
-(In fact this only matters when bicubic interpolation is required.)
+(In fact, this only matters when bicubic interpolation is required.)
 Note that no testing is done to check the validity in the model,
 since there is no way of knowing the name used for the longitude variable,
@@ -444,4 +481,8 @@
 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}
@@ -449,5 +490,5 @@
 \begin{enumerate}  
 \item
-  The case where input data grids are not logically rectangular has not been tested.
+  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
@@ -470,16 +511,17 @@
 (see the directory NEMOGCM/TOOLS/WEIGHTS).
 
+
 % -------------------------------------------------------------------------------------------------------------
 % Standalone Surface Boundary Condition Scheme
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Standalone surface boundary condition scheme}
-\label{subsec:SAS_iof}
-
-%---------------------------------------namsbc_ana--------------------------------------------------
+\subsection{Standalone surface boundary condition scheme (SAS)}
+\label{subsec:SAS}
+
+%---------------------------------------namsbc_sas--------------------------------------------------
 
 \nlst{namsbc_sas}
 %--------------------------------------------------------------------------------------------------------------
 
-In some circumstances it may be useful to avoid calculating the 3D temperature,
+In some circumstances, it may be useful to avoid calculating the 3D temperature,
 salinity and velocity fields and simply read them in from a previous run or receive them from OASIS.  
 For example:
@@ -496,11 +538,11 @@
   Spinup of the iceberg floats
 \item
-  Ocean/sea-ice simulation with both media running in parallel (\np{ln\_mixcpl}\forcode{ = .true.})
+  Ocean/sea-ice simulation with both models running in parallel (\np{ln\_mixcpl}\forcode{ = .true.})
 \end{itemize}
 
-The StandAlone Surface scheme provides this utility.
+The Standalone Surface scheme provides this capacity.
 Its options are defined through the \ngn{namsbc\_sas} namelist variables.
 A new copy of the model has to be compiled with a configuration based on ORCA2\_SAS\_LIM.
-However no namelist parameters need be changed from the settings of the previous run (except perhaps nn{\_}date0).
+However, no namelist parameters need be changed from the settings of the previous run (except perhaps nn{\_}date0).
 In this configuration, a few routines in the standard model are overriden by new versions.
 Routines replaced are:
@@ -524,5 +566,5 @@
   so calls to restart functions have been removed.
   This also means that the calendar cannot be controlled by time in a restart file,
-  so the user must make sure that nn{\_}date0 in the model namelist is correct for his or her purposes.
+  so the user must check that nn{\_}date0 in the model namelist is correct for his or her purposes.
 \item
   \mdl{stpctl}:
@@ -543,5 +585,5 @@
   velocity arrays at the surface.
   These filenames are supplied in namelist namsbc{\_}sas.
-  Unfortunately because of limitations with the \mdl{iom} module,
+  Unfortunately, because of limitations with the \mdl{iom} module,
   the full 3D fields from the mean files have to be read in and interpolated in time,
   before using just the top level.
@@ -550,33 +592,7 @@
 
 
-% Missing the description of the 2 following variables:
-%   ln_3d_uve   = .true.    !  specify whether we are supplying a 3D u,v and e3 field
-%   ln_read_frq = .false.    !  specify whether we must read frq or not
-
-
-
-% ================================================================
-% Analytical formulation (sbcana module) 
-% ================================================================
-\section{Analytical formulation (\protect\mdl{sbcana})}
-\label{sec:SBC_ana}
-
-%---------------------------------------namsbc_ana--------------------------------------------------
-%
-%\nlst{namsbc_ana}
-%--------------------------------------------------------------------------------------------------------------
-
-The analytical formulation of the surface boundary condition is the default scheme.
-In this case, all the six fluxes needed by the ocean are assumed to be uniform in space.
-They take constant values given in the namelist \ngn{namsbc{\_}ana} by
-the variables \np{rn\_utau0}, \np{rn\_vtau0}, \np{rn\_qns0}, \np{rn\_qsr0}, and \np{rn\_emp0}
-($\textit{emp}=\textit{emp}_S$).
-The runoff is set to zero.
-In addition, the wind is allowed to reach its nominal value within a given number of time steps (\np{nn\_tau000}).
-
-If a user wants to apply a different analytical forcing,
-the \mdl{sbcana} module can be modified to use another scheme.
-As an example, the \mdl{sbc\_ana\_gyre} routine provides the analytical forcing for the GYRE configuration
-(see GYRE configuration manual, in preparation).
+The user can also choose in the \ngn{namsbc\_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.
+
 
 
@@ -584,5 +600,6 @@
 % Flux formulation 
 % ================================================================
-\section{Flux formulation (\protect\mdl{sbcflx})}
+\section[Flux formulation (\textit{sbcflx.F90})]
+{Flux formulation (\protect\mdl{sbcflx})}
 \label{sec:SBC_flx}
 %------------------------------------------namsbc_flx----------------------------------------------------
@@ -602,62 +619,49 @@
 
 
+
 % ================================================================
 % Bulk formulation
 % ================================================================
-\section[Bulk formulation {(\textit{sbcblk\{\_core,\_clio\}.F90})}]
-                        {Bulk formulation {(\protect\mdl{sbcblk\_core}, \protect\mdl{sbcblk\_clio})}}
+\section[Bulk formulation (\textit{sbcblk.F90})]
+{Bulk formulation (\protect\mdl{sbcblk})}
 \label{sec:SBC_blk}
-
-In the bulk formulation, the surface boundary condition fields are computed using bulk formulae and atmospheric fields and ocean (and ice) variables.
+%---------------------------------------namsbc_blk--------------------------------------------------
+
+\nlst{namsbc_blk}
+%--------------------------------------------------------------------------------------------------------------
+
+In the bulk formulation, the surface boundary condition fields are computed with bulk formulae using atmospheric fields 
+and ocean (and sea-ice) variables averaged over \np{nn\_fsbc} time-step.
 
 The atmospheric fields used depend on the bulk formulae used.
-Two bulk formulations are available:
-the CORE and the CLIO bulk formulea.
+In forced mode, when a sea-ice model is used, a specific bulk formulation is used.
+Therefore, different bulk formulae are used for the turbulent fluxes computation
+over the ocean and over sea-ice surface. 
+For the ocean, four bulk formulations are available thanks to the \href{https://brodeau.github.io/aerobulk/}{Aerobulk} package (\citet{brodeau.barnier.ea_JPO16}): 
+the NCAR (formerly named CORE), COARE 3.0, COARE 3.5 and ECMWF bulk formulae.
 The choice is made by setting to true one of the following namelist variable:
-\np{ln\_core} or \np{ln\_clio}.
-
-Note:
-in forced mode, when a sea-ice model is used, a bulk formulation (CLIO or CORE) have to be used.
-Therefore the two bulk (CLIO and CORE) formulea include the computation of the fluxes over
-both an ocean and an ice surface. 
-
-% -------------------------------------------------------------------------------------------------------------
-%        CORE Bulk formulea
-% -------------------------------------------------------------------------------------------------------------
-\subsection{CORE formulea (\protect\mdl{sbcblk\_core}, \protect\np{ln\_core}\forcode{ = .true.})}
-\label{subsec:SBC_blk_core}
-%------------------------------------------namsbc_core----------------------------------------------------
-%
-%\nlst{namsbc_core}
-%-------------------------------------------------------------------------------------------------------------
-
-The CORE bulk formulae have been developed by \citet{Large_Yeager_Rep04}.
-They have been designed to handle the CORE forcing, a mixture of NCEP reanalysis and satellite data.
-They use an inertial dissipative method to compute the turbulent transfer coefficients
-(momentum, sensible heat and evaporation) from the 10 metre wind speed, air temperature and specific humidity.
-This \citet{Large_Yeager_Rep04} dataset is available through
-the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/CORE.html}{GFDL web site}.
-
-Note that substituting ERA40 to NCEP reanalysis fields does not require changes in the bulk formulea themself.
-This is the so-called DRAKKAR Forcing Set (DFS) \citep{Brodeau_al_OM09}.
-
-Options are defined through the  \ngn{namsbc\_core} namelist variables.
-The required 8 input fields are:
+ \np{ln\_NCAR}, \np{ln\_COARE\_3p0},  \np{ln\_COARE\_3p5} and  \np{ln\_ECMWF}.
+For sea-ice, three possibilities can be selected:
+a constant transfer coefficient (1.4e-3; default value), \citet{lupkes.gryanik.ea_JGR12} (\np{ln\_Cd\_L12}), and \citet{lupkes.gryanik_JGR15} (\np{ln\_Cd\_L15}) parameterizations
+
+Common options are defined through the \ngn{namsbc\_blk} namelist variables.
+The required 9 input fields are:
 
 %--------------------------------------------------TABLE--------------------------------------------------
 \begin{table}[htbp]
-  \label{tab:CORE}
+  \label{tab:BULK}
   \begin{center}
     \begin{tabular}{|l|c|c|c|}
       \hline
-      Variable desciption					& Model variable	& Units	 & point \\		\hline
-      i-component of the 10m air velocity	& utau		& $m.s^{-1}$			& T  \\ 	\hline
-      j-component of the 10m air velocity	& vtau		& $m.s^{-1}$			& T  \\	\hline
-      10m 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
+      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
+      10m 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}
@@ -678,56 +682,87 @@
 \np{rn\_zu}: is the height of wind measurements (m)
 
-Three multiplicative factors are availables: 
-\np{rn\_pfac} and \np{rn\_efac} allows to adjust (if necessary) the global freshwater budget by
+Three multiplicative factors are available: 
+\np{rn\_pfac} and \np{rn\_efac} allow to adjust (if necessary) the global freshwater budget by
 increasing/reducing the precipitations (total and snow) and or evaporation, respectively.
 The third one,\np{rn\_vfac}, control to which extend the ice/ocean velocities are taken into account in
 the calculation of surface wind stress.
-Its range should be between zero and one, and it is recommended to set it to 0.
-
-% -------------------------------------------------------------------------------------------------------------
-%        CLIO Bulk formulea
-% -------------------------------------------------------------------------------------------------------------
-\subsection{CLIO formulea (\protect\mdl{sbcblk\_clio}, \protect\np{ln\_clio}\forcode{ = .true.})}
-\label{subsec:SBC_blk_clio}
-%------------------------------------------namsbc_clio----------------------------------------------------
-%
-%\nlst{namsbc_clio}
-%-------------------------------------------------------------------------------------------------------------
-
-The CLIO bulk formulae were developed several years ago for the Louvain-la-neuve coupled ice-ocean model
-(CLIO, \cite{Goosse_al_JGR99}). 
-They are simpler bulk formulae.
-They assume the stress to be known and compute the radiative fluxes from a climatological cloud cover. 
-
-Options are defined through the  \ngn{namsbc\_clio} namelist variables.
-The required 7 input fields are:
-
-%--------------------------------------------------TABLE--------------------------------------------------
-\begin{table}[htbp]
-  \label{tab:CLIO}
-  \begin{center}
-    \begin{tabular}{|l|l|l|l|}
-      \hline
-      Variable desciption				& Model variable	& Units				& point \\	\hline
-      i-component of the ocean stress		& utau			& $N.m^{-2}$			& U \\	\hline
-      j-component of the ocean stress		& vtau			& $N.m^{-2}$			& V \\	\hline
-      Wind speed module					& vatm			& $m.s^{-1}$			& T \\	\hline
-      10m air temperature					& tair			& \r{}$K$				& T \\	\hline
-      Specific humidity						& humi			& \%					& T \\	\hline
-      Cloud cover							& 				& \%					& T \\	\hline
-      Total precipitation (liquid + solid)	& precip		& $Kg.m^{-2}.s^{-1}$	& T \\	\hline
-      Solid precipitation 					& snow			& $Kg.m^{-2}.s^{-1}$	& T \\	\hline
-    \end{tabular}
-  \end{center}
-\end{table}
-%--------------------------------------------------------------------------------------------------------------
+Its range must be between zero and one, and it is recommended to set it to 0 at low-resolution (ORCA2 configuration).
 
 As for the flux formulation, information about the input data required by the model is provided in
-the namsbc\_blk\_core or namsbc\_blk\_clio namelist (see \autoref{subsec:SBC_fldread}). 
+the namsbc\_blk namelist (see \autoref{subsec:SBC_fldread}). 
+
+
+% -------------------------------------------------------------------------------------------------------------
+%        Ocean-Atmosphere Bulk formulae
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Ocean-Atmosphere Bulk formulae}
+%\subsection[Ocean-Atmosphere Bulk formulae (\textit{sbcblk_algo\{\_ncar,\_coare,\_coare3p5,\_ecmwf}.F90})]
+\label{subsec:SBC_blk_ocean}
+
+Four different bulk algorithms are available to compute surface turbulent momentum and heat fluxes over the ocean.
+COARE 3.0, COARE 3.5 and ECMWF schemes mainly differ by their roughness lenghts computation and consequently 
+their neutral transfer coefficients relationships with neutral wind.
+\begin{itemize}
+\item
+  NCAR (\np{ln\_NCAR}\forcode{ = .true.}):
+  The NCAR bulk formulae have been developed by \citet{large.yeager_rpt04}.
+  They have been designed to handle the NCAR forcing, a mixture of NCEP reanalysis and satellite data.
+  They use an inertial dissipative method to compute the turbulent transfer coefficients
+  (momentum, sensible heat and evaporation) from the 10m wind speed, air temperature and specific humidity.
+  This \citet{large.yeager_rpt04} dataset is available through
+  the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/NCAR.html}{GFDL web site}.
+  Note that substituting ERA40 to NCEP reanalysis fields does not require changes in the bulk formulea themself.
+  This is the so-called DRAKKAR Forcing Set (DFS) \citep{brodeau.barnier.ea_OM10}.
+\item
+  COARE 3.0 (\np{ln\_COARE\_3p0}\forcode{ = .true.}): 
+  See \citet{fairall.bradley.ea_JC03} for more details
+\item
+  COARE 3.5 (\np{ln\_COARE\_3p5}\forcode{ = .true.}): 
+  See \citet{edson.jampana.ea_JPO13} for more details
+\item
+  ECMWF (\np{ln\_ECMWF}\forcode{ = .true.}): 
+  Based on \href{https://www.ecmwf.int/node/9221}{IFS (Cy31)} implementation and documentation.
+  Surface roughness lengths needed for the Obukhov length are computed following \citet{beljaars_QJRMS95}.
+\end{itemize}
+
+
+% -------------------------------------------------------------------------------------------------------------
+%        Ice-Atmosphere Bulk formulae
+% -------------------------------------------------------------------------------------------------------------
+\subsection{ Ice-Atmosphere Bulk formulae }
+\label{subsec:SBC_blk_ice}
+
+Surface turbulent fluxes between sea-ice and the atmosphere can be computed in three different ways:
+
+\begin{itemize}
+\item
+  Constant value (\np{constant\ value}\forcode{ Cd_ice = 1.4e-3 }):
+  default constant value used for momentum and heat neutral transfer coefficients
+\item
+  \citet{lupkes.gryanik.ea_JGR12} (\np{ln\_Cd\_L12}\forcode{ = .true.}):
+  This scheme adds a dependency on edges at leads, melt ponds and flows
+  of the constant neutral air-ice drag. After some approximations, 
+  this can be resumed to a dependency on ice concentration (A).
+  This drag coefficient has a parabolic shape (as a function of ice concentration)
+  starting at 1.5e-3 for A=0, reaching 1.97e-3 for A=0.5 and going down 1.4e-3 for A=1.
+  It is theoretically applicable to all ice conditions (not only MIZ).
+\item
+  \citet{lupkes.gryanik_JGR15} (\np{ln\_Cd\_L15}\forcode{ = .true.}):
+  Alternative turbulent transfer coefficients formulation between sea-ice 
+  and atmosphere with distinct momentum and heat coefficients depending 
+  on sea-ice concentration and atmospheric stability (no melt-ponds effect for now).
+  The parameterization is adapted from ECHAM6 atmospheric model.
+  Compared to Lupkes2012 scheme, it considers specific skin and form drags
+  to compute neutral transfer coefficients for both heat and momentum fluxes.
+  Atmospheric stability effect on transfer coefficient is also taken into account.
+\end{itemize}
+
+
 
 % ================================================================
 % Coupled formulation
 % ================================================================
-\section{Coupled formulation (\protect\mdl{sbccpl})}
+\section[Coupled formulation (\textit{sbccpl.F90})]
+{Coupled formulation (\protect\mdl{sbccpl})}
 \label{sec:SBC_cpl}
 %------------------------------------------namsbc_cpl----------------------------------------------------
@@ -737,19 +772,17 @@
 
 In the coupled formulation of the surface boundary condition,
-the fluxes are provided by the OASIS coupler at a frequency which is defined in the OASIS coupler,
+the fluxes are provided by the OASIS coupler at a frequency which is defined in the OASIS coupler namelist,
 while sea and ice surface temperature, ocean and ice albedo, and ocean currents are sent to
 the atmospheric component.
 
 A generalised coupled interface has been developed.
-It is currently interfaced with OASIS-3-MCT (\key{oasis3}).
+It is currently interfaced with OASIS-3-MCT versions 1 to 4 (\key{oasis3}).
+An additional specific CPP key (\key{oa3mct\_v1v2}) is needed for OASIS-3-MCT versions 1 and 2.
 It has been successfully used to interface \NEMO to most of the European atmospheric GCM
 (ARPEGE, ECHAM, ECMWF, HadAM, HadGAM, LMDz), as well as to \href{http://wrf-model.org/}{WRF}
 (Weather Research and Forecasting Model).
 
-Note that in addition to the setting of \np{ln\_cpl} to true, the \key{coupled} have to be defined.
-The CPP key is mainly used in sea-ice to ensure that the atmospheric fluxes are actually received by
-the ice-ocean system (no calculation of ice sublimation in coupled mode).
-When PISCES biogeochemical model (\key{top} and \key{pisces}) is also used in the coupled system, 
-the whole carbon cycle is computed by defining \key{cpl\_carbon\_cycle}.
+When PISCES biogeochemical model (\key{top}) is also used in the coupled system, 
+the whole carbon cycle is computed.
 In this case, CO$_2$ fluxes will be exchanged between the atmosphere and the ice-ocean system
 (and need to be activated in \ngn{namsbc{\_}cpl} ).
@@ -757,12 +790,11 @@
 The namelist above allows control of various aspects of the coupling fields (particularly for vectors) and
 now allows for any coupling fields to have multiple sea ice categories (as required by LIM3 and CICE).
-When indicating a multi-category coupling field in namsbc{\_}cpl the number of categories will be determined by
+When indicating a multi-category coupling field in \ngn{namsbc{\_}cpl}, the number of categories will be determined by
 the number used in the sea ice model.
-In some limited cases it may be possible to specify single category coupling fields even when
+In some limited cases, it may be possible to specify single category coupling fields even when
 the sea ice model is running with multiple categories -
-in this case the user should examine the code to be sure the assumptions made are satisfactory.
-In cases where this is definitely not possible the model should abort with an error message.
-The new code has been tested using ECHAM with LIM2, and HadGAM3 with CICE but
-although it will compile with \key{lim3} additional minor code changes may be required to run using LIM3.
+in this case, the user should examine the code to be sure the assumptions made are satisfactory.
+In cases where this is definitely not possible, the model should abort with an error message.
+
 
 
@@ -770,5 +802,6 @@
 %        Atmospheric pressure
 % ================================================================
-\section{Atmospheric pressure (\protect\mdl{sbcapr})}
+\section[Atmospheric pressure (\textit{sbcapr.F90})]
+{Atmospheric pressure (\protect\mdl{sbcapr})}
 \label{sec:SBC_apr}
 %------------------------------------------namsbc_apr----------------------------------------------------
@@ -778,6 +811,6 @@
 
 The optional atmospheric pressure can be used to force ocean and ice dynamics
-(\np{ln\_apr\_dyn}\forcode{ = .true.}, \textit{\ngn{namsbc}} namelist).
-The input atmospheric forcing defined via \np{sn\_apr} structure (\textit{namsbc\_apr} namelist)
+(\np{ln\_apr\_dyn}\forcode{ = .true.}, \ngn{namsbc} namelist).
+The input atmospheric forcing defined via \np{sn\_apr} structure (\ngn{namsbc\_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
@@ -789,11 +822,11 @@
 where $P_{atm}$ is the atmospheric pressure and $P_o$ a reference atmospheric pressure.
 A value of $101,000~N/m^2$ is used unless \np{ln\_ref\_apr} is set to true.
-In this case $P_o$ is set to the value of $P_{atm}$ averaged over the ocean domain,
-\ie the mean value of $\eta_{ib}$ is kept to zero at all time step.
+In this case, $P_o$ is set to the value of $P_{atm}$ averaged over the ocean domain,
+\ie the mean value of $\eta_{ib}$ is kept to zero at all time steps.
 
 The gradient of $\eta_{ib}$ is added to the RHS of the ocean momentum equation (see \mdl{dynspg} for the ocean).
 For sea-ice, the sea surface height, $\eta_m$, which is provided to the sea ice model is set to $\eta - \eta_{ib}$
 (see \mdl{sbcssr} module).
-$\eta_{ib}$ can be set in the output.
+$\eta_{ib}$ can be written in the output.
 This can simplify altimetry data and model comparison as
 inverse barometer sea surface height is usually removed from these date prior to their distribution.
@@ -803,8 +836,11 @@
 \np{ln\_apr\_obc}  might be set to true.
 
+
+
 % ================================================================
 %        Surface Tides Forcing
 % ================================================================
-\section{Surface tides (\protect\mdl{sbctide})}
+\section[Surface tides (\textit{sbctide.F90})]
+{Surface tides (\protect\mdl{sbctide})}
 \label{sec:SBC_tide}
 
@@ -819,5 +855,5 @@
 \[
   % \label{eq:PE_dyn_tides}
-  \frac{\partial {\rm {\bf U}}_h }{\partial t}= ...
+  \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= ...
   +g\nabla (\Pi_{eq} + \Pi_{sal})
 \]
@@ -827,5 +863,5 @@
 The equilibrium tidal forcing is expressed as a sum over a subset of
 constituents chosen from the set of available tidal constituents
-defined in file \rou{SBC/tide.h90} (this comprises the tidal
+defined in file \textit{SBC/tide.h90} (this comprises the tidal
 constituents \textit{M2, N2, 2N2, S2, K2, K1, O1, Q1, P1, M4, Mf, Mm,
   Msqm, Mtm, S1, MU2, NU2, L2}, and \textit{T2}). Individual
@@ -839,8 +875,8 @@
 
 The SAL term should in principle be computed online as it depends on
-the model tidal prediction itself (see \citet{Arbic2004} for a
+the model tidal prediction itself (see \citet{arbic.garner.ea_DSR04} for a
 discussion about the practical implementation of this term).
 Nevertheless, the complex calculations involved would make this
-computationally too expensive.  Here, two options are available:
+computationally too expensive. Here, two options are available:
 $\Pi_{sal}$ generated by an external model can be read in
 (\np{ln\_read\_load=.true.}), or a ``scalar approximation'' can be
@@ -854,8 +890,11 @@
 \forcode{.false.} removes the SAL contribution.
 
+
+
 % ================================================================
 %        River runoffs
 % ================================================================
-\section{River runoffs (\protect\mdl{sbcrnf})}
+\section[River runoffs (\textit{sbcrnf.F90})]
+{River runoffs (\protect\mdl{sbcrnf})}
 \label{sec:SBC_rnf}
 %------------------------------------------namsbc_rnf----------------------------------------------------
@@ -871,5 +910,5 @@
 %coastal modelling and becomes more and more often open ocean and climate modelling 
 %\footnote{At least a top cells thickness of 1~meter and a 3 hours forcing frequency are
-%required to properly represent the diurnal cycle \citep{Bernie_al_JC05}. see also \autoref{fig:SBC_dcy}.}.
+%required to properly represent the diurnal cycle \citep{bernie.woolnough.ea_JC05}. see also \autoref{fig:SBC_dcy}.}.
 
 
@@ -892,5 +931,5 @@
 \footnote{
   At least a top cells thickness of 1~meter and a 3 hours forcing frequency are required to
-  properly represent the diurnal cycle \citep{Bernie_al_JC05}.
+  properly represent the diurnal cycle \citep{bernie.woolnough.ea_JC05}.
   see also \autoref{fig:SBC_dcy}.}.
 
@@ -935,5 +974,5 @@
 As such the volume of water does not change, but the water is diluted.
 
-For the non-linear free surface case (\key{vvl}), no flux is allowed through the surface.
+For the non-linear free surface case, no flux is allowed through the surface.
 Instead in the surface box (as well as water moving up from the boxes below) a volume of runoff water is added with
 no corresponding heat and salt addition and so as happens in the lower boxes there is a dilution effect.
@@ -978,9 +1017,11 @@
 %To do this we need to treat evaporation/precipitation fluxes and river runoff differently in the tra_sbc module.  We decided to separate them throughout the code, so that the variable emp represented solely evaporation minus precipitation fluxes, and a new 2d variable rnf was added which represents the volume flux of river runoff (in kg/m2s to remain consistent with emp).  This meant many uses of emp and emps needed to be changed, a list of all modules which use emp or emps and the changes made are below:
 
-%}
+
+
 % ================================================================
 %        Ice shelf melting
 % ================================================================
-\section{Ice shelf melting (\protect\mdl{sbcisf})}
+\section[Ice shelf melting (\textit{sbcisf.F90})]
+{Ice shelf melting (\protect\mdl{sbcisf})}
 \label{sec:SBC_isf}
 %------------------------------------------namsbc_isf----------------------------------------------------
@@ -988,12 +1029,15 @@
 \nlst{namsbc_isf}
 %--------------------------------------------------------------------------------------------------------
+
 The namelist variable in \ngn{namsbc}, \np{nn\_isf}, controls the ice shelf representation.
-Description and result of sensitivity test to \np{nn\_isf} are presented in \citet{Mathiot2017}. 
+Description and result of sensitivity test to \np{nn\_isf} are presented in \citet{mathiot.jenkins.ea_GMD17}. 
 The different options are illustrated in \autoref{fig:SBC_isf}.
 
 \begin{description}
-\item[\np{nn\_isf}\forcode{ = 1}]:
+
+  \item[\np{nn\_isf}\forcode{ = 1}]:
   The ice shelf cavity is represented (\np{ln\_isfcav}\forcode{ = .true.} needed).
   The fwf and heat flux are depending of the local water properties.
+  
   Two different bulk formulae are available:
 
@@ -1001,12 +1045,12 @@
 	\item[\np{nn\_isfblk}\forcode{ = 1}]:
      The melt rate is based on a balance between the upward ocean heat flux and
-     the latent heat flux at the ice shelf base. A complete description is available in \citet{Hunter2006}.
+     the latent heat flux at the ice shelf base. A complete description is available in \citet{hunter_rpt06}.
 	\item[\np{nn\_isfblk}\forcode{ = 2}]:
      The melt rate and the heat flux are based on a 3 equations formulation
      (a heat flux budget at the ice base, a salt flux budget at the ice base and a linearised freezing point temperature equation). 
-     A complete description is available in \citet{Jenkins1991}.
+     A complete description is available in \citet{jenkins_JGR91}.
 	\end{description}
 
-     Temperature and salinity used to compute the melt are the average temperature in the top boundary layer \citet{Losch2008}. 
+     Temperature and salinity used to compute the melt are the average temperature in the top boundary layer \citet{losch_JGR08}. 
      Its thickness is defined by \np{rn\_hisf\_tbl}.
      The fluxes and friction velocity are computed using the mean temperature, salinity and velocity in the the first \np{rn\_hisf\_tbl} m.
@@ -1038,5 +1082,5 @@
 \]
      where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters).
-     See \citet{Jenkins2010} for all the details on this formulation. It is the recommended formulation for realistic application.
+     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:
@@ -1047,15 +1091,15 @@
      $\Gamma_{Turb}$ the contribution of the ocean stability and
      $\Gamma^{T,S}_{Mole}$ the contribution of the molecular diffusion.
-     See \citet{Holland1999} for all the details on this formulation. 
+     See \citet{holland.jenkins_JPO99} for all the details on this formulation. 
      This formulation has not been extensively tested in NEMO (not recommended).
    \end{description}
- \item[\np{nn\_isf}\forcode{ = 2}]:
+  \item[\np{nn\_isf}\forcode{ = 2}]:
    The ice shelf cavity is not represented.
-   The fwf and heat flux are computed using the \citet{Beckmann2003} parameterisation of isf melting.
+   The fwf and heat flux are computed using the \citet{beckmann.goosse_OM03} parameterisation of isf melting.
    The fluxes are distributed along the ice shelf edge between the depth of the average grounding line (GL)
    (\np{sn\_depmax\_isf}) and the base of the ice shelf along the calving front
    (\np{sn\_depmin\_isf}) as in (\np{nn\_isf}\forcode{ = 3}).
    The effective melting length (\np{sn\_Leff\_isf}) is read from a file.
- \item[\np{nn\_isf}\forcode{ = 3}]:
+  \item[\np{nn\_isf}\forcode{ = 3}]:
    The ice shelf cavity is not represented.
    The fwf (\np{sn\_rnfisf}) is prescribed and distributed along the ice shelf edge between
@@ -1063,5 +1107,5 @@
    the base of the ice shelf along the calving front (\np{sn\_depmin\_isf}).
    The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$.
- \item[\np{nn\_isf}\forcode{ = 4}]:
+  \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}).
@@ -1089,5 +1133,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=0.8\textwidth]{Fig_SBC_isf}
+    \includegraphics[width=\textwidth]{Fig_SBC_isf}
     \caption{
       \protect\label{fig:SBC_isf}
@@ -1098,4 +1142,9 @@
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 
+
+
+% ================================================================
+%        Ice sheet coupling
+% ================================================================
 \section{Ice sheet coupling}
 \label{sec:SBC_iscpl}
@@ -1104,6 +1153,8 @@
 \nlst{namsbc_iscpl}
 %--------------------------------------------------------------------------------------------------------
+
 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.
@@ -1117,4 +1168,5 @@
 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]:
@@ -1155,5 +1207,6 @@
 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
@@ -1166,6 +1219,6 @@
 %-------------------------------------------------------------------------------------------------------------
 
-Icebergs are modelled as lagrangian particles in NEMO \citep{Marsh_GMD2015}.
-Their physical behaviour is controlled by equations as described in \citet{Martin_Adcroft_OM10} ).
+Icebergs are modelled as lagrangian particles in NEMO \citep{marsh.ivchenko.ea_GMD15}.
+Their physical behaviour is controlled by equations as described in \citet{martin.adcroft_OM10} ).
 (Note that the authors kindly provided a copy of their code to act as a basis for implementation in NEMO).
 Icebergs are initially spawned into one of ten classes which have specific mass and thickness as
@@ -1186,5 +1239,5 @@
   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.
+  In this scheme, the model reads a calving file supplied in the \np{sn\_icb} parameter.
   This should be a file with a field on the configuration grid (typically ORCA)
   representing ice accumulation rate at each model point.
@@ -1224,8 +1277,11 @@
 since its trajectory data may be spread across multiple files.
 
-% -------------------------------------------------------------------------------------------------------------
+
+
+% =============================================================================================================
 %        Interactions with waves (sbcwave.F90, ln_wave)
-% -------------------------------------------------------------------------------------------------------------
-\section{Interactions with waves (\protect\mdl{sbcwave}, \protect\np{ln\_wave})}
+% =============================================================================================================
+\section[Interactions with waves (\textit{sbcwave.F90}, \texttt{ln\_wave})]
+{Interactions with waves (\protect\mdl{sbcwave}, \protect\np{ln\_wave})}
 \label{sec:SBC_wave}
 %------------------------------------------namsbc_wave--------------------------------------------------------
@@ -1241,6 +1297,6 @@
 
 Physical processes related to ocean surface waves can be accounted by setting the logical variable 
-\np{ln\_wave}\forcode{= .true.} in \ngn{namsbc} namelist. In addition, specific flags accounting for 
-different porcesses should be activated as explained in the following sections.
+\np{ln\_wave} \forcode{= .true.} in \ngn{namsbc} 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:
@@ -1254,32 +1310,34 @@
 
 
-% ================================================================
+% ----------------------------------------------------------------
 % Neutral drag coefficient from wave model (ln_cdgw)
 
-% ================================================================
-\subsection{Neutral drag coefficient from wave model (\protect\np{ln\_cdgw})}
+% ----------------------------------------------------------------
+\subsection[Neutral drag coefficient from wave model (\texttt{ln\_cdgw})]
+{Neutral drag coefficient from wave model (\protect\np{ln\_cdgw})}
 \label{subsec:SBC_wave_cdgw}
 
 The neutral surface drag coefficient provided from an external data source (\ie a wave model), 
 can be used by setting the logical variable \np{ln\_cdgw} \forcode{= .true.} in \ngn{namsbc} namelist. 
-Then using the routine \rou{turb\_ncar} and starting from the neutral drag coefficent provided, 
+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_Rep04}. 
-
-
-% ================================================================
+air-sea interface following \citet{large.yeager_rpt04}. 
+
+
+% ----------------------------------------------------------------
 % 3D Stokes Drift (ln_sdw, nn_sdrift)
-% ================================================================
-\subsection{3D Stokes Drift (\protect\np{ln\_sdw, nn\_sdrift})}
+% ----------------------------------------------------------------
+\subsection[3D Stokes Drift (\texttt{ln\_sdw}, \texttt{nn\_sdrift})]
+{3D Stokes Drift (\protect\np{ln\_sdw, nn\_sdrift})}
 \label{subsec:SBC_wave_sdw}
 
-The Stokes drift is a wave driven mechanism of mass and momentum transport \citep{Stokes_1847}. 
+The Stokes drift is a wave driven mechanism of mass and momentum transport \citep{stokes_ibk09}. 
 It is defined as the difference between the average velocity of a fluid parcel (Lagrangian velocity) 
 and the current measured at a fixed point (Eulerian velocity). 
 As waves travel, the water particles that make up the waves travel in orbital motions but 
 without a closed path. Their movement is enhanced at the top of the orbit and slowed slightly 
-at the bottom so the result is a net forward motion of water particles, referred to as the Stokes drift. 
+at the bottom, so the result is a net forward motion of water particles, referred to as the Stokes drift. 
 An accurate evaluation of the Stokes drift and the inclusion of related processes may lead to improved 
-representation of surface physics in ocean general circulation models.
+representation of surface physics in ocean general circulation models. %GS: reference needed
 The Stokes drift velocity $\mathbf{U}_{st}$ in deep water can be computed from the wave spectrum and may be written as: 
 
@@ -1296,5 +1354,5 @@
 $k=\frac{2\pi}{\lambda}$ (being $\lambda$ the wavelength). \\
 
-In order to evaluate the Stokes drift in a realistic ocean wave field the wave spectral shape is required 
+In order to evaluate the Stokes drift in a realistic ocean wave field, the wave spectral shape is required 
 and its computation quickly becomes expensive as the 2D spectrum must be integrated for each vertical level. 
 To simplify, it is customary to use approximations to the full Stokes profile.
@@ -1307,5 +1365,5 @@
 \begin{description}
 \item[\np{nn\_sdrift} = 0]: exponential integral profile parameterization proposed by 
-\citet{Breivik_al_JPO2014}:
+\citet{breivik.janssen.ea_JPO14}:
 
 \[
@@ -1326,6 +1384,6 @@
 
 \item[\np{nn\_sdrift} = 1]: velocity profile based on the Phillips spectrum which is considered to be a 
-reasonable estimate of the part of the spectrum most contributing to the Stokes drift velocity near the surface
-\citep{Breivik_al_OM2016}:
+reasonable estimate of the part of the spectrum mostly contributing to the Stokes drift velocity near the surface
+\citep{breivik.bidlot.ea_OM16}:
 
 \[
@@ -1364,8 +1422,9 @@
 
 
-% ================================================================
+% ----------------------------------------------------------------
 % Stokes-Coriolis term (ln_stcor)
-% ================================================================
-\subsection{Stokes-Coriolis term (\protect\np{ln\_stcor})}
+% ----------------------------------------------------------------
+\subsection[Stokes-Coriolis term (\texttt{ln\_stcor})]
+{Stokes-Coriolis term (\protect\np{ln\_stcor})}
 \label{subsec:SBC_wave_stcor}
 
@@ -1378,16 +1437,17 @@
 
 
-% ================================================================
+% ----------------------------------------------------------------
 % Waves modified stress (ln_tauwoc, ln_tauw)
-% ================================================================
-\subsection{Wave modified sress (\protect\np{ln\_tauwoc, ln\_tauw})} 
+% ----------------------------------------------------------------
+\subsection[Wave modified stress (\texttt{ln\_tauwoc}, \texttt{ln\_tauw})]
+{Wave modified sress (\protect\np{ln\_tauwoc, ln\_tauw})}
 \label{subsec:SBC_wave_tauw}
 
 The surface stress felt by the ocean is the atmospheric stress minus the net stress going 
-into the waves \citep{Janssen_al_TM13}. Therefore, when waves are growing, momentum and energy is spent and is not 
+into the waves \citep{janssen.breivik.ea_rpt13}. Therefore, when waves are growing, momentum and energy is spent and is not 
 available for forcing the mean circulation, while in the opposite case of a decaying sea 
-state more momentum is available for forcing the ocean. 
-Only when the sea state is in equilibrium the ocean is forced by the atmospheric stress, 
-but in practice an equilibrium sea state is a fairly rare event. 
+state, more momentum is available for forcing the ocean. 
+Only when the sea state is in equilibrium, the ocean is forced by the atmospheric stress, 
+but in practice, an equilibrium sea state is a fairly rare event. 
 So the atmospheric stress felt by the ocean circulation $\tau_{oc,a}$ can be expressed as: 
 
@@ -1419,4 +1479,5 @@
 
 
+
 % ================================================================
 % Miscellanea options
@@ -1425,10 +1486,12 @@
 \label{sec:SBC_misc}
 
+
 % -------------------------------------------------------------------------------------------------------------
 %        Diurnal cycle
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Diurnal cycle (\protect\mdl{sbcdcy})}
+\subsection[Diurnal cycle (\textit{sbcdcy.F90})]
+{Diurnal cycle (\protect\mdl{sbcdcy})}
 \label{subsec:SBC_dcy}
-%------------------------------------------namsbc_rnf----------------------------------------------------
+%------------------------------------------namsbc-------------------------------------------------------------
 %
 \nlst{namsbc} 
@@ -1438,5 +1501,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=0.8\textwidth]{Fig_SBC_diurnal}
+    \includegraphics[width=\textwidth]{Fig_SBC_diurnal}
     \caption{
       \protect\label{fig:SBC_diurnal}
@@ -1445,5 +1508,5 @@
       the mean value of the analytical cycle (blue line) over a time step,
       not as the mid time step value of the analytically cycle (red square).
-      From \citet{Bernie_al_CD07}.
+      From \citet{bernie.guilyardi.ea_CD07}.
     }
   \end{center}
@@ -1451,22 +1514,21 @@
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 
-\cite{Bernie_al_JC05} have shown that to capture 90$\%$ of the diurnal variability of SST requires a vertical resolution in upper ocean of 1~m or better and a temporal resolution of the surface fluxes of 3~h or less.
-Unfortunately high frequency forcing fields are rare, not to say inexistent.
-Nevertheless, it is possible to obtain a reasonable diurnal cycle of the SST knowning only short wave flux (SWF) at
-high frequency \citep{Bernie_al_CD07}.
+\cite{bernie.woolnough.ea_JC05} have shown that to capture 90$\%$ of the diurnal variability of SST requires a vertical resolution in upper ocean of 1~m or better and a temporal resolution of the surface fluxes of 3~h or less.
+%Unfortunately high frequency forcing fields are rare, not to say inexistent. GS: not true anymore !
+Nevertheless, it is possible to obtain a reasonable diurnal cycle of the SST knowning only short wave flux (SWF) at high frequency \citep{bernie.guilyardi.ea_CD07}.
 Furthermore, only the knowledge of daily mean value of SWF is needed,
 as higher frequency variations can be reconstructed from them,
 assuming that the diurnal cycle of SWF is a scaling of the top of the atmosphere diurnal cycle of incident SWF.
-The \cite{Bernie_al_CD07} reconstruction algorithm is available in \NEMO by
+The \cite{bernie.guilyardi.ea_CD07} reconstruction algorithm is available in \NEMO by
 setting \np{ln\_dm2dc}\forcode{ = .true.} (a \textit{\ngn{namsbc}} namelist variable) when
-using CORE bulk formulea (\np{ln\_blk\_core}\forcode{ = .true.}) or
+using a bulk formulation (\np{ln\_blk}\forcode{ = .true.}) or
 the flux formulation (\np{ln\_flx}\forcode{ = .true.}).
 The reconstruction is performed in the \mdl{sbcdcy} module.
-The detail of the algoritm used can be found in the appendix~A of \cite{Bernie_al_CD07}.
-The algorithm preserve the daily mean incoming SWF as the reconstructed SWF at
+The detail of the algoritm used can be found in the appendix~A of \cite{bernie.guilyardi.ea_CD07}.
+The algorithm preserves the daily mean incoming SWF as the reconstructed SWF at
 a given time step is the mean value of the analytical cycle over this time step (\autoref{fig:SBC_diurnal}).
 The use of diurnal cycle reconstruction requires the input SWF to be daily
-(\ie a frequency of 24 and a time interpolation set to true in \np{sn\_qsr} namelist parameter).
-Furthermore, it is recommended to have a least 8 surface module time step per day,
+(\ie a frequency of 24 hours and a time interpolation set to true in \np{sn\_qsr} namelist parameter).
+Furthermore, it is recommended to have a least 8 surface module time steps per day,
 that is  $\rdt \ nn\_fsbc < 10,800~s = 3~h$.
 An example of recontructed SWF is given in \autoref{fig:SBC_dcy} for a 12 reconstructed diurnal cycle,
@@ -1476,5 +1538,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=0.7\textwidth]{Fig_SBC_dcy}
+    \includegraphics[width=\textwidth]{Fig_SBC_dcy}
     \caption{
       \protect\label{fig:SBC_dcy}
@@ -1491,4 +1553,5 @@
 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
@@ -1497,10 +1560,9 @@
 \label{subsec:SBC_rotation}
 
-When using a flux (\np{ln\_flx}\forcode{ = .true.}) or
-bulk (\np{ln\_clio}\forcode{ = .true.} or \np{ln\_core}\forcode{ = .true.}) formulation,
+When using a flux (\np{ln\_flx}\forcode{ = .true.}) or bulk (\np{ln\_blk}\forcode{ = .true.}) formulation,
 pairs of vector components can be rotated from east-north directions onto the local grid directions.
 This is particularly useful when interpolation on the fly is used since here any vectors are likely to
 be defined relative to a rectilinear grid.
-To activate this option a non-empty string is supplied in the rotation pair column of the relevant namelist.
+To activate this option, a non-empty string is supplied in the rotation pair column of the relevant namelist.
 The eastward component must start with "U" and the northward component with "V".  
 The remaining characters in the strings are used to identify which pair of components go together.
@@ -1511,8 +1573,10 @@
 The rot\_rep routine from the \mdl{geo2ocean} module is used to perform the rotation.
 
+
 % -------------------------------------------------------------------------------------------------------------
 %        Surface restoring to observed SST and/or SSS
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Surface restoring to observed SST and/or SSS (\protect\mdl{sbcssr})}
+\subsection[Surface restoring to observed SST and/or SSS (\textit{sbcssr.F90})]
+{Surface restoring to observed SST and/or SSS (\protect\mdl{sbcssr})}
 \label{subsec:SBC_ssr}
 %------------------------------------------namsbc_ssr----------------------------------------------------
@@ -1521,5 +1585,5 @@
 %-------------------------------------------------------------------------------------------------------------
 
-IOptions are defined through the \ngn{namsbc\_ssr} namelist variables.
+Options are defined through the \ngn{namsbc\_ssr} namelist variables.
 On forced mode using a flux formulation (\np{ln\_flx}\forcode{ = .true.}),
 a feedback term \emph{must} be added to the surface heat flux $Q_{ns}^o$:
@@ -1546,11 +1610,12 @@
 (observed, climatological or an atmospheric model product),
 \textit{SSS}$_{Obs}$ is a sea surface salinity
-(usually a time interpolation of the monthly mean Polar Hydrographic Climatology \citep{Steele2001}),
+(usually a time interpolation of the monthly mean Polar Hydrographic Climatology \citep{steele.morley.ea_JC01}),
 $\left.S\right|_{k=1}$ is the model surface layer salinity and
 $\gamma_s$ is a negative feedback coefficient which is provided as a namelist parameter.
 Unlike heat flux, there is no physical justification for the feedback term in \autoref{eq:sbc_dmp_emp} as
-the atmosphere does not care about ocean surface salinity \citep{Madec1997}.
+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.
+
 
 % -------------------------------------------------------------------------------------------------------------
@@ -1578,5 +1643,5 @@
   This prevents deep convection to occur when trying to reach the freezing point
   (and so ice covered area condition) while the SSS is too large.
-  This manner of managing sea-ice area, just by using si IF case,
+  This manner of managing sea-ice area, just by using a IF case,
   is usually referred as the \textit{ice-if} model.
   It can be found in the \mdl{sbcice{\_}if} module.
@@ -1585,16 +1650,22 @@
   This model computes the ice-ocean fluxes,
   that are combined with the air-sea fluxes using the ice fraction of each model cell to
-  provide the surface ocean fluxes.
-  Note that the activation of a sea-ice model is is done by defining a CPP key (\key{lim3} or \key{cice}).
+  provide the surface averaged ocean fluxes.
+  Note that the activation of a sea-ice model is done by defining a CPP key (\key{si3} or \key{cice}).
   The activation automatically overwrites the read value of nn{\_}ice to its appropriate value
-  (\ie $2$ for LIM-3 or $3$ for CICE).
+  (\ie $2$ for SI3 or $3$ for CICE).
 \end{description}
 
 % {Description of Ice-ocean interface to be added here or in LIM 2 and 3 doc ?}
-
-\subsection{Interface to CICE (\protect\mdl{sbcice\_cice})}
+%GS: ocean-ice (SI3) interface is not located in SBC directory anymore, so it should be included in SI3 doc
+
+
+% -------------------------------------------------------------------------------------------------------------
+%        CICE-ocean Interface
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Interface to CICE (\textit{sbcice\_cice.F90})]
+{Interface to CICE (\protect\mdl{sbcice\_cice})}
 \label{subsec:SBC_cice}
 
-It is now possible to couple a regional or global NEMO configuration (without AGRIF)
+It is possible to couple a regional or global NEMO configuration (without AGRIF)
 to the CICE sea-ice model by using \key{cice}.
 The CICE code can be obtained from \href{http://oceans11.lanl.gov/trac/CICE/}{LANL} and
@@ -1603,5 +1674,5 @@
 and CICE CPP keys \textbf{ORCA\_GRID}, \textbf{CICE\_IN\_NEMO} and \textbf{coupled} should be used
 (seek advice from UKMO if necessary).
-Currently the code is only designed to work when using the CORE forcing option for NEMO
+Currently, the code is only designed to work when using the NCAR forcing option for NEMO %GS: still true ?
 (with \textit{calc\_strair}\forcode{ = .true.} and \textit{calc\_Tsfc}\forcode{ = .true.} in the CICE name-list),
 or alternatively when NEMO is coupled to the HadGAM3 atmosphere model
@@ -1623,13 +1694,16 @@
 there is no sea ice.
 
+
 % -------------------------------------------------------------------------------------------------------------
 %        Freshwater budget control 
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Freshwater budget control (\protect\mdl{sbcfwb})}
+\subsection[Freshwater budget control (\textit{sbcfwb.F90})]
+{Freshwater budget control (\protect\mdl{sbcfwb})}
 \label{subsec:SBC_fwb}
 
-For global ocean simulation it can be useful to introduce a control of the mean sea level in order to
+For global ocean simulation, it can be useful to introduce a control of the mean sea level in order to
 prevent unrealistic drift of the sea surface height due to inaccuracy in the freshwater fluxes.
-In \NEMO, two way of controlling the the freshwater budget. 
+In \NEMO, two way of controlling the freshwater budget are proposed:
+ 
 \begin{description}
 \item[\np{nn\_fwb}\forcode{ = 0}]
@@ -1638,5 +1712,6 @@
 \item[\np{nn\_fwb}\forcode{ = 1}]
   global mean \textit{emp} set to zero at each model time step. 
-%Note that with a sea-ice model, this technique only control the mean sea level with linear free surface (\key{vvl} not defined) and no mass flux between ocean and ice (as it is implemented in the current ice-ocean coupling). 
+  %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
@@ -1645,6 +1720,4 @@
   the change in the mean sea level at January the first and saved in the \textit{EMPav.dat} file. 
 \end{description}
-
-
 
 % Griffies doc:
@@ -1655,5 +1728,5 @@
 % The result of the normalization should be a global integrated zero net water input to the ocean-ice system over 
 % a chosen time scale. 
-%How often the normalization is done is a matter of choice. In mom4p1, we choose to do so at each model time step, 
+% How often the normalization is done is a matter of choice. In mom4p1, we choose to do so at each model time step, 
 % so that there is always a zero net input of water to the ocean-ice system. 
 % Others choose to normalize over an annual cycle, in which case the net imbalance over an annual cycle is used 
@@ -1670,4 +1743,5 @@
 % in ocean-ice models. 
 
+
 \biblio
 
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_STO.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_STO.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_STO.tex	(revision 11422)
@@ -8,18 +8,25 @@
 \label{chap:STO}
 
-Authors: P.-A. Bouttier
+\minitoc
 
-\minitoc
+% \vfill
+% \begin{figure}[b]
+% \subsubsection*{Changes record}
+% \begin{tabular}{l||l|m{0.65\linewidth}}
+%    Release   & Author        & Modifications \\
+%    {\em 4.0.1} & {\em C. Levy} & {\em 4.0.1 update}  \\
+%    {\em 3.6} & {\em P.-A. Bouttier} & {\em initial version}  \\
+% \end{tabular}
+% \end{figure}
+
+Authors: \\
+C. Levy release 4.0.1 update \\
+P.-A. Bouttier release 3.6 inital version
 
 \newpage
 
-The stochastic parametrization module aims to explicitly simulate uncertainties in the model.
-More particularly, \cite{Brankart_OM2013} has shown that,
-because of the nonlinearity of the seawater equation of state, unresolved scales represent a major source of
-uncertainties in the computation of the large scale horizontal density gradient (from T/S large scale fields),
-and that the impact of these uncertainties can be simulated by
-random processes representing unresolved T/S fluctuations.
+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.
 
-The stochastic formulation of the equation of state can be written as:
+As detailed in \cite{brankart_OM13}, the stochastic formulation of the equation of state can be written as:
 \begin{equation}
   \label{eq:eos_sto}
@@ -27,5 +34,5 @@
 \end{equation}
 where $p_o(z)$ is the reference pressure depending on the depth and,
-$\Delta T_i$ and $\Delta S_i$ are a set of T/S perturbations defined as
+$\Delta T_i$ and $\Delta S_i$ (i=1,m) is a set of T/S perturbations defined as
 the scalar product of the respective local T/S gradients with random walks $\mathbf{\xi}$:
 \begin{equation}
@@ -33,5 +40,5 @@
   \Delta T_i = \mathbf{\xi}_i \cdot \nabla T \qquad \hbox{and} \qquad \Delta S_i = \mathbf{\xi}_i \cdot \nabla S
 \end{equation}
-$\mathbf{\xi}_i$ are produced by a first-order autoregressive processes (AR-1) with
+$\mathbf{\xi}_i$ are produced by a first-order autoregressive process (AR-1) with
 a parametrized decorrelation time scale, and horizontal and vertical standard deviations $\sigma_s$.
 $\mathbf{\xi}$ are uncorrelated over the horizontal and fully correlated along the vertical.
@@ -41,12 +48,11 @@
 \label{sec:STO_the_details}
 
-The starting point of our implementation of stochastic parameterizations in NEMO is to observe that
-many existing parameterizations are based on autoregressive processes,
+There are many existing parameterizations based on autoregressive processes,
 which are used as a basic source of randomness to transform a deterministic model into a probabilistic model.
-A generic approach is thus to add one single new module in NEMO,
-generating processes with appropriate statistics to simulate each kind of uncertainty in the model
-(see \cite{Brankart_al_GMD2015} for more details).
+The generic approach here is to a new STO module,
+generating processes features with appropriate statistics to simulate these uncertainties in the model
+(see \cite{brankart.candille.ea_GMD15} for more details).
 
-In practice, at every model grid point,
+In practice, at each model grid point,
 independent Gaussian autoregressive processes~$\xi^{(i)},\,i=1,\ldots,m$ are first generated using
 the same basic equation:
@@ -101,41 +107,39 @@
 \noindent
 In this way, higher order processes can be easily generated recursively using the same piece of code implementing
-(\autoref{eq:autoreg}), and using succesively processes from order $0$ to~$n-1$ as~$w^{(i)}$.
-The parameters in (\autoref{eq:ord2}) are computed so that this recursive application of
-(\autoref{eq:autoreg}) leads to processes with the required standard deviation and correlation timescale,
+\autoref{eq: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,
 with the additional condition that the $n-1$ first derivatives of the autocorrelation function are equal to
-zero at~$t=0$, so that the resulting processes become smoother and smoother as $n$ is increased.
+zero at~$t=0$, so that the resulting processes become smoother and smoother as $n$ increases.
 
 Overall, this method provides quite a simple and generic way of generating a wide class of stochastic processes.
 However, this also means that new model parameters are needed to specify each of these stochastic processes.
-As in any parameterization of lacking physics, a very important issues then to tune these new parameters using
+As in any parameterization, the main issue is to tune the parameters using
 either first principles, model simulations, or real-world observations.
+The parameters are set by default as described in \cite{brankart_OM13}, which has been shown in the paper
+to give good results for a global low resolution (2°) NEMO configuration. where this parametrization produces a major effect on the average large-scale circulation, especilally in regions of intense mesoscale activity.
+The set of parameters will need further investigation to find appropriate values
+for any other configuration or resolution of the model.
 
 \section{Implementation details}
 \label{sec:STO_thech_details}
 
-%---------------------------------------namsbc--------------------------------------------------
 
-\nlst{namsto}
-%--------------------------------------------------------------------------------------------------------------
+The code implementing stochastic parametrisation is located in the src/OCE/STO directory.
+It contains three modules : 
+% \begin{description}
 
-The computer code implementing stochastic parametrisations can be found in the STO directory.
-It involves three modules : 
-\begin{description}
-\item[\mdl{stopar}:]
-  define the Stochastic parameters and their time evolution.
-\item[\mdl{storng}:]
-  a random number generator based on (and includes) the 64-bit KISS (Keep It Simple Stupid) random number generator
-  distributed by George Marsaglia
-  (see \href{https://groups.google.com/forum/#!searchin/comp.lang.fortran/64-bit$20KISS$20RNGs}{here})
-\item[\mdl{stopts}:]
-  stochastic parametrisation associated with the non-linearity of the equation of seawater,
-  implementing \autoref{eq:sto_pert} and specific piece of code in
-  the equation of state implementing \autoref{eq:eos_sto}.
-\end{description}
+\mdl{stopar} : define the Stochastic parameters and their time evolution
 
-The \mdl{stopar} module has 3 public routines to be called by the model (in our case, NEMO):
+\mdl{storng} : random number generator based on and including the 64-bit KISS (Keep It Simple Stupid) random number generator distributed by George Marsaglia
 
-The first routine (\rou{sto\_par}) is a direct implementation of (\autoref{eq:autoreg}),
+\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}.
+% \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},
 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$).
@@ -143,14 +147,37 @@
 to introduce a spatial correlation between the stochastic processes.
 
-The second routine (\rou{sto\_par\_init}) is an initialization routine mainly dedicated to
-the computation of parameters $a^{(i)}, b^{(i)}, c^{(i)}$ for each autoregressive process,
+(\rou{sto\_par\_init}) is the initialization routine computing
+the values $a^{(i)}, b^{(i)}, c^{(i)}$ for each autoregressive process,
 as a function of the statistical properties required by the model user
 (mean, standard deviation, time correlation, order of the process,\ldots). 
+This routine also includes the initialization (seeding) of the random number generator.
 
-Parameters for the processes can be specified through the following \ngn{namsto} namelist parameters:
+(\rou{sto\_rst\_write}) writes a restart file
+(which suffix name is given by \np{cn\_storst\_out} namelist parameter) containing the current value of
+all autoregressive processes to allow creating the file needed for a restart.
+This restart file also contains the current state of the random number generator.
+When \np{ln\_rststo} is set to \forcode{.true.}),
+the restart file (which suffix name is given by \np{cn\_storst\_in} namelist parameter) is read by
+the initialization routine (\rou{sto\_par\_init}).
+The simulation will continue exactly as if it was not interrupted only
+when \np{ln\_rstseed} is set to \forcode{.true.},
+\ie when the state of the random number generator is read in the restart file.\\
+
+The implementation includes the basics for a few possible stochastic parametrisations including equation of state, lateral diffusion, horizontal pressure gradient, ice strength, trend, tracers dynamics. As for this release, only the stochastic parametrisation of equation of state is fully available and tested. \\ 
+
+Options and parameters \\
+
+The \np{ln\_sto\_eos} namelist variable activates stochastic parametrisation of equation of state. By default it set to \forcode{.false.}) and not active.
+The set of parameters is available in \ngn{namsto} namelist(only the subset for equation of state stochastic parametrisation is listed below):
+%---------------------------------------namsto--------------------------------------------------
+
+\nlst{namsto}
+%--------------------------------------------------------------------------------------------------------------
+
+The variables of stochastic paramtetrisation itself (based on the global 2° experiments as in \cite{brankart_OM13} are:
 \begin{description}
 \item[\np{nn\_sto\_eos}:]   number of independent random walks
-\item[\np{rn\_eos\_stdxy}:] random walk horz. standard deviation (in grid points)
-\item[\np{rn\_eos\_stdz}:]  random walk vert. standard deviation (in grid points)
+\item[\np{rn\_eos\_stdxy}:] random walk horizontal standard deviation (in grid points)
+\item[\np{rn\_eos\_stdz}:]  random walk vertical standard deviation (in grid points)
 \item[\np{rn\_eos\_tcor}:]  random walk time correlation (in timesteps)
 \item[\np{nn\_eos\_ord}:]   order of autoregressive processes
@@ -158,17 +185,6 @@
 \item[\np{rn\_eos\_lim}:]   limitation factor (default = 3.0)
 \end{description}
-This routine also includes the initialization (seeding) of the random number generator.
 
-The third routine (\rou{sto\_rst\_write}) writes a restart file
-(which suffix name is given by \np{cn\_storst\_out} namelist parameter) containing the current value of
-all autoregressive processes to allow restarting a simulation from where it has been interrupted.
-This file also contains the current state of the random number generator.
-When \np{ln\_rststo} is set to \forcode{.true.}),
-the restart file (which suffix name is given by \np{cn\_storst\_in} namelist parameter) is read by
-the initialization routine (\rou{sto\_par\_init}).
-The simulation will continue exactly as if it was not interrupted only
-when \np{ln\_rstseed} is set to \forcode{.true.},
-\ie when the state of the random number generator is read in the restart file.
-
+The first four parameters define the stochastic part of equation of state.
 \biblio
 
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_TRA.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_TRA.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_TRA.tex	(revision 11422)
@@ -55,10 +55,11 @@
 
 The user has the option of extracting each tendency term on the RHS of the tracer equation for output
-(\np{ln\_tra\_trd} or \np{ln\_tra\_mxl}~\forcode{= .true.}), as described in \autoref{chap:DIA}.
+(\np{ln\_tra\_trd} or \np{ln\_tra\_mxl}\forcode{ = .true.}), as described in \autoref{chap:DIA}.
 
 % ================================================================
 % Tracer Advection
 % ================================================================
-\section{Tracer advection (\protect\mdl{traadv})}
+\section[Tracer advection (\textit{traadv.F90})]
+{Tracer advection (\protect\mdl{traadv})}
 \label{sec:TRA_adv}
 %------------------------------------------namtra_adv-----------------------------------------------------
@@ -81,5 +82,5 @@
 Indeed, it is obtained by using the following equality: $\nabla \cdot (\vect U \, T) = \vect U \cdot \nabla T$ which
 results from the use of the continuity equation, $\partial_t e_3 + e_3 \; \nabla \cdot \vect U = 0$
-(which reduces to $\nabla \cdot \vect U = 0$ in linear free surface, \ie \np{ln\_linssh}~\forcode{= .true.}).
+(which reduces to $\nabla \cdot \vect U = 0$ in linear free surface, \ie \np{ln\_linssh}\forcode{ = .true.}).
 Therefore it is of paramount importance to design the discrete analogue of the advection tendency so that
 it is consistent with the continuity equation in order to enforce the conservation properties of
@@ -90,5 +91,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[]{Fig_adv_scheme}
+    \includegraphics[width=\textwidth]{Fig_adv_scheme}
     \caption{
       \protect\label{fig:adv_scheme}
@@ -119,5 +120,5 @@
 \begin{description}
 \item[linear free surface:]
-  (\np{ln\_linssh}~\forcode{= .true.})
+  (\np{ln\_linssh}\forcode{ = .true.})
   the first level thickness is constant in time:
   the vertical boundary condition is applied at the fixed surface $z = 0$ rather than on
@@ -127,5 +128,5 @@
   the first level tracer value.
 \item[non-linear free surface:]
-  (\np{ln\_linssh}~\forcode{= .false.})
+  (\np{ln\_linssh}\forcode{ = .false.})
   convergence/divergence in the first ocean level moves the free surface up/down.
   There is no tracer advection through it so that the advective fluxes through the surface are also zero.
@@ -136,7 +137,7 @@
 Nevertheless, in the latter case, it is achieved to a good approximation since
 the non-conservative term is the product of the time derivative of the tracer and the free surface height,
-two quantities that are not correlated \citep{Roullet_Madec_JGR00, Griffies_al_MWR01, Campin2004}.
-
-The velocity field that appears in (\autoref{eq:tra_adv} and \autoref{eq:tra_adv_zco}) is
+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} and \autoref{eq:tra_adv_zco?}) 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
@@ -183,10 +184,11 @@
 %        2nd and 4th order centred schemes
 % -------------------------------------------------------------------------------------------------------------
-\subsection{CEN: Centred scheme (\protect\np{ln\_traadv\_cen}~\forcode{= .true.})}
+\subsection[CEN: Centred scheme (\forcode{ln_traadv_cen = .true.})]
+{CEN: Centred scheme (\protect\np{ln\_traadv\_cen}\forcode{ = .true.})}
 \label{subsec:TRA_adv_cen}
 
 %        2nd order centred scheme  
 
-The centred advection scheme (CEN) is used when \np{ln\_traadv\_cen}~\forcode{= .true.}.
+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$.
@@ -220,8 +222,8 @@
   \tau_u^{cen4} = \overline{T - \frac{1}{6} \, \delta_i \Big[ \delta_{i + 1/2}[T] \, \Big]}^{\,i + 1/2}
 \end{equation}
-In the vertical direction (\np{nn\_cen\_v}~\forcode{= 4}),
-a $4^{th}$ COMPACT interpolation has been prefered \citep{Demange_PhD2014}.
+In the vertical direction (\np{nn\_cen\_v}\forcode{ = 4}),
+a $4^{th}$ COMPACT interpolation has been prefered \citep{demange_phd14}.
 In the COMPACT scheme, both the field and its derivative are interpolated, which leads, after a matrix inversion,
-spectral characteristics similar to schemes of higher order \citep{Lele_JCP1992}. 
+spectral characteristics similar to schemes of higher order \citep{lele_JCP92}. 
 
 Strictly speaking, the CEN4 scheme is not a $4^{th}$ order advection scheme but
@@ -250,8 +252,9 @@
 %        FCT scheme  
 % -------------------------------------------------------------------------------------------------------------
-\subsection{FCT: Flux Corrected Transport scheme (\protect\np{ln\_traadv\_fct}~\forcode{= .true.})}
+\subsection[FCT: Flux Corrected Transport scheme (\forcode{ln_traadv_fct = .true.})]
+{FCT: Flux Corrected Transport scheme (\protect\np{ln\_traadv\_fct}\forcode{ = .true.})}
 \label{subsec:TRA_adv_tvd}
 
-The Flux Corrected Transport schemes (FCT) is used when \np{ln\_traadv\_fct}~\forcode{= .true.}.
+The Flux Corrected Transport schemes (FCT) is used when \np{ln\_traadv\_fct}\forcode{ = .true.}.
 Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) and vertical direction by
 setting \np{nn\_fct\_h} and \np{nn\_fct\_v} to $2$ or $4$.
@@ -277,9 +280,9 @@
 (\ie it depends on the setting of \np{nn\_fct\_h} and \np{nn\_fct\_v}).
 There exist many ways to define $c_u$, each corresponding to a different FCT scheme.
-The one chosen in \NEMO is described in \citet{Zalesak_JCP79}.
+The one chosen in \NEMO is described in \citet{zalesak_JCP79}.
 $c_u$ only departs from $1$ when the advective term produces a local extremum in the tracer field.
 The resulting scheme is quite expensive but \textit{positive}.
 It can be used on both active and passive tracers.
-A comparison of FCT-2 with MUSCL and a MPDATA scheme can be found in \citet{Levy_al_GRL01}.
+A comparison of FCT-2 with MUSCL and a MPDATA scheme can be found in \citet{levy.estublier.ea_GRL01}.
 
 An additional option has been added controlled by \np{nn\_fct\_zts}.
@@ -287,5 +290,5 @@
 a $2^{nd}$ order FCT scheme is used on both horizontal and vertical direction, but on the latter,
 a split-explicit time stepping is used, with a number of sub-timestep equals to \np{nn\_fct\_zts}.
-This option can be useful when the size of the timestep is limited by vertical advection \citep{Lemarie_OM2015}.
+This option can be useful when the size 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 momentum to
 insure a better stability (see \autoref{subsec:DYN_zad}).
@@ -300,11 +303,12 @@
 %        MUSCL scheme  
 % -------------------------------------------------------------------------------------------------------------
-\subsection{MUSCL: Monotone Upstream Scheme for Conservative Laws (\protect\np{ln\_traadv\_mus}~\forcode{= .true.})}
+\subsection[MUSCL: Monotone Upstream Scheme for Conservative Laws (\forcode{ln_traadv_mus = .true.})]
+{MUSCL: Monotone Upstream Scheme for Conservative Laws (\protect\np{ln\_traadv\_mus}\forcode{ = .true.})}
 \label{subsec:TRA_adv_mus}
 
-The Monotone Upstream Scheme for Conservative Laws (MUSCL) is used when \np{ln\_traadv\_mus}~\forcode{= .true.}.
+The Monotone Upstream Scheme for Conservative Laws (MUSCL) is used when \np{ln\_traadv\_mus}\forcode{ = .true.}.
 MUSCL implementation can be found in the \mdl{traadv\_mus} module.
 
-MUSCL has been first implemented in \NEMO by \citet{Levy_al_GRL01}.
+MUSCL has been first implemented in \NEMO by \citet{levy.estublier.ea_GRL01}.
 In its formulation, the tracer at velocity points is evaluated assuming a linear tracer variation between
 two $T$-points (\autoref{fig:adv_scheme}).
@@ -331,13 +335,14 @@
 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.}).
+(\np{ln\_mus\_ups}\forcode{ = .true.}).
 
 % -------------------------------------------------------------------------------------------------------------
 %        UBS scheme  
 % -------------------------------------------------------------------------------------------------------------
-\subsection{UBS a.k.a. UP3: Upstream-Biased Scheme (\protect\np{ln\_traadv\_ubs}~\forcode{= .true.})}
+\subsection[UBS a.k.a. UP3: Upstream-Biased Scheme (\forcode{ln_traadv_ubs = .true.})]
+{UBS a.k.a. UP3: Upstream-Biased Scheme (\protect\np{ln\_traadv\_ubs}\forcode{ = .true.})}
 \label{subsec:TRA_adv_ubs}
 
-The Upstream-Biased Scheme (UBS) is used when \np{ln\_traadv\_ubs}~\forcode{= .true.}.
+The Upstream-Biased Scheme (UBS) is used when \np{ln\_traadv\_ubs}\forcode{ = .true.}.
 UBS implementation can be found in the \mdl{traadv\_mus} module.
 
@@ -358,6 +363,6 @@
 
 This results in a dissipatively dominant (i.e. hyper-diffusive) truncation error
-\citep{Shchepetkin_McWilliams_OM05}.
-The overall performance of the advection scheme is similar to that reported in \cite{Farrow1995}.
+\citep{shchepetkin.mcwilliams_OM05}.
+The overall performance of the advection scheme is similar to that reported in \cite{farrow.stevens_JPO95}.
 It is a relatively good compromise between accuracy and smoothness.
 Nevertheless the scheme is not \textit{positive}, meaning that false extrema are permitted,
@@ -367,7 +372,7 @@
 The intrinsic diffusion of UBS makes its use risky in the vertical direction where
 the control of artificial diapycnal fluxes is of paramount importance
-\citep{Shchepetkin_McWilliams_OM05, Demange_PhD2014}.
+\citep{shchepetkin.mcwilliams_OM05, demange_phd14}.
 Therefore the vertical flux is evaluated using either a $2^nd$ order FCT scheme or a $4^th$ order COMPACT scheme
-(\np{nn\_cen\_v}~\forcode{= 2 or 4}).
+(\np{nn\_cen\_v}\forcode{ = 2 or 4}).
 
 For stability reasons (see \autoref{chap:STP}), the first term  in \autoref{eq:tra_adv_ubs}
@@ -376,7 +381,7 @@
 (which is the diffusive part of the scheme),
 is evaluated using the \textit{before} tracer (forward in time).
-This choice is discussed by \citet{Webb_al_JAOT98} in the context of the QUICK advection scheme.
+This choice is discussed by \citet{webb.de-cuevas.ea_JAOT98} in the context of the QUICK advection scheme.
 UBS and QUICK schemes only differ by one coefficient.
-Replacing 1/6 with 1/8 in \autoref{eq:tra_adv_ubs} leads to the QUICK advection scheme \citep{Webb_al_JAOT98}.
+Replacing 1/6 with 1/8 in \autoref{eq:tra_adv_ubs} leads to the QUICK advection scheme \citep{webb.de-cuevas.ea_JAOT98}.
 This option is not available through a namelist parameter, since the 1/6 coefficient is hard coded.
 Nevertheless it is quite easy to make the substitution in the \mdl{traadv\_ubs} module and obtain a QUICK scheme.
@@ -408,13 +413,14 @@
 %        QCK scheme  
 % -------------------------------------------------------------------------------------------------------------
-\subsection{QCK: QuiCKest scheme (\protect\np{ln\_traadv\_qck}~\forcode{= .true.})}
+\subsection[QCK: QuiCKest scheme (\forcode{ln_traadv_qck = .true.})]
+{QCK: QuiCKest scheme (\protect\np{ln\_traadv\_qck}\forcode{ = .true.})}
 \label{subsec:TRA_adv_qck}
 
 The Quadratic Upstream Interpolation for Convective Kinematics with Estimated Streaming Terms (QUICKEST) scheme
-proposed by \citet{Leonard1979} is used when \np{ln\_traadv\_qck}~\forcode{= .true.}.
+proposed by \citet{leonard_CMAME79} is used when \np{ln\_traadv\_qck}\forcode{ = .true.}.
 QUICKEST implementation can be found in the \mdl{traadv\_qck} module.
 
 QUICKEST is the third order Godunov scheme which is associated with the ULTIMATE QUICKEST limiter
-\citep{Leonard1991}.
+\citep{leonard_CMAME91}.
 It has been implemented in NEMO by G. Reffray (MERCATOR-ocean) and can be found in the \mdl{traadv\_qck} module.
 The resulting scheme is quite expensive but \textit{positive}.
@@ -431,5 +437,6 @@
 % Tracer Lateral Diffusion
 % ================================================================
-\section{Tracer lateral diffusion (\protect\mdl{traldf})}
+\section[Tracer lateral diffusion (\textit{traldf.F90})]
+{Tracer lateral diffusion (\protect\mdl{traldf})}
 \label{sec:TRA_ldf}
 %-----------------------------------------nam_traldf------------------------------------------------------
@@ -453,11 +460,12 @@
 except for the pure vertical component that appears when a rotation tensor is used.
 This latter component is solved implicitly together with the vertical diffusion term (see \autoref{chap:STP}).
-When \np{ln\_traldf\_msc}~\forcode{= .true.}, a Method of Stabilizing Correction is used in which
-the pure vertical component is split into an explicit and an implicit part \citep{Lemarie_OM2012}.
+When \np{ln\_traldf\_msc}\forcode{ = .true.}, a Method of Stabilizing Correction is used in which
+the pure vertical component is split into an explicit and an implicit part \citep{lemarie.debreu.ea_OM12}.
 
 % -------------------------------------------------------------------------------------------------------------
 %        Type of operator
 % -------------------------------------------------------------------------------------------------------------
-\subsection[Type of operator (\protect\np{ln\_traldf}\{\_NONE,\_lap,\_blp\}\})]{Type of operator (\protect\np{ln\_traldf\_NONE}, \protect\np{ln\_traldf\_lap}, or \protect\np{ln\_traldf\_blp}) } 
+\subsection[Type of operator (\texttt{ln\_traldf}\{\texttt{\_NONE,\_lap,\_blp}\})]
+{Type of operator (\protect\np{ln\_traldf\_NONE}, \protect\np{ln\_traldf\_lap}, or \protect\np{ln\_traldf\_blp}) } 
 \label{subsec:TRA_ldf_op}
 
@@ -465,13 +473,13 @@
 
 \begin{description}
-\item[\np{ln\_traldf\_NONE}~\forcode{= .true.}:]
+\item[\np{ln\_traldf\_NONE}\forcode{ = .true.}:]
   no operator selected, the lateral diffusive tendency will not be applied to the tracer equation.
   This option can be used when the selected advection scheme is diffusive enough (MUSCL scheme for example).
-\item[\np{ln\_traldf\_lap}~\forcode{= .true.}:]
+\item[\np{ln\_traldf\_lap}\forcode{ = .true.}:]
   a laplacian operator is selected.
   This harmonic operator takes the following expression:  $\mathpzc{L}(T) = \nabla \cdot A_{ht} \; \nabla T $,
   where the gradient operates along the selected direction (see \autoref{subsec:TRA_ldf_dir}),
   and $A_{ht}$ is the eddy diffusivity coefficient expressed in $m^2/s$ (see \autoref{chap:LDF}).
-\item[\np{ln\_traldf\_blp}~\forcode{= .true.}]:
+\item[\np{ln\_traldf\_blp}\forcode{ = .true.}]:
   a bilaplacian operator is selected.
   This biharmonic operator takes the following expression:
@@ -493,10 +501,11 @@
 %        Direction of action
 % -------------------------------------------------------------------------------------------------------------
-\subsection[Action direction (\protect\np{ln\_traldf}\{\_lev,\_hor,\_iso,\_triad\})]{Direction of action (\protect\np{ln\_traldf\_lev}, \protect\np{ln\_traldf\_hor}, \protect\np{ln\_traldf\_iso}, or \protect\np{ln\_traldf\_triad}) } 
+\subsection[Action direction (\texttt{ln\_traldf}\{\texttt{\_lev,\_hor,\_iso,\_triad}\})]
+{Direction of action (\protect\np{ln\_traldf\_lev}, \protect\np{ln\_traldf\_hor}, \protect\np{ln\_traldf\_iso}, or \protect\np{ln\_traldf\_triad}) } 
 \label{subsec:TRA_ldf_dir}
 
 The choice of a direction of action determines the form of operator used.
 The operator is a simple (re-entrant) laplacian acting in the (\textbf{i},\textbf{j}) plane when
-iso-level option is used (\np{ln\_traldf\_lev}~\forcode{= .true.}) or
+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.}).
@@ -519,5 +528,6 @@
 %       iso-level operator
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Iso-level (bi -)laplacian operator ( \protect\np{ln\_traldf\_iso}) }
+\subsection[Iso-level (bi-)laplacian operator (\texttt{ln\_traldf\_iso})]
+{Iso-level (bi-)laplacian operator ( \protect\np{ln\_traldf\_iso})}
 \label{subsec:TRA_ldf_lev}
 
@@ -537,10 +547,10 @@
 It is a \textit{horizontal} operator (\ie acting along geopotential surfaces) in
 the $z$-coordinate with or without partial steps, but is simply an iso-level operator in the $s$-coordinate.
-It is thus used when, in addition to \np{ln\_traldf\_lap} or \np{ln\_traldf\_blp}~\forcode{= .true.},
-we have \np{ln\_traldf\_lev}~\forcode{= .true.} or \np{ln\_traldf\_hor}~=~\np{ln\_zco}~\forcode{= .true.}.
+It is thus used when, in addition to \np{ln\_traldf\_lap} or \np{ln\_traldf\_blp}\forcode{ = .true.},
+we have \np{ln\_traldf\_lev}\forcode{ = .true.} or \np{ln\_traldf\_hor}~=~\np{ln\_zco}\forcode{ = .true.}.
 In both cases, it significantly contributes to diapycnal mixing.
 It is therefore never recommended, even when using it in the bilaplacian case.
 
-Note that in the partial step $z$-coordinate (\np{ln\_zps}~\forcode{= .true.}),
+Note that in the partial step $z$-coordinate (\np{ln\_zps}\forcode{ = .true.}),
 tracers in horizontally adjacent cells are located at different depths in the vicinity of the bottom.
 In this case, horizontal derivatives in (\autoref{eq:tra_ldf_lap}) at the bottom level require a specific treatment.
@@ -550,10 +560,11 @@
 %         Rotated laplacian operator
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Standard and triad (bi -)laplacian operator}
+\subsection{Standard and triad (bi-)laplacian operator}
 \label{subsec:TRA_ldf_iso_triad}
 
-%&&    Standard rotated (bi -)laplacian operator
+%&&    Standard rotated (bi-)laplacian operator
 %&& ----------------------------------------------
-\subsubsection{Standard rotated (bi -)laplacian operator (\protect\mdl{traldf\_iso})}
+\subsubsection[Standard rotated (bi-)laplacian operator (\textit{traldf\_iso.F90})]
+{Standard rotated (bi-)laplacian operator (\protect\mdl{traldf\_iso})}
 \label{subsec:TRA_ldf_iso}
 The general form of the second order lateral tracer subgrid scale physics (\autoref{eq:PE_zdf})
@@ -574,7 +585,7 @@
 $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{ln\_traldf\_lap}\forcode{ = .true.},
+we have \np{ln\_traldf\_iso}\forcode{ = .true.},
+or both \np{ln\_traldf\_hor}\forcode{ = .true.} and \np{ln\_zco}\forcode{ = .true.}.
 The way these slopes are evaluated is given in \autoref{sec:LDF_slp}.
 At the surface, bottom and lateral boundaries, the turbulent fluxes of heat and salt are set to zero using
@@ -590,19 +601,20 @@
 This formulation conserves the tracer but does not ensure the decrease of the tracer variance.
 Nevertheless the treatment performed on the slopes (see \autoref{chap:LDF}) allows the model to run safely without
-any additional background horizontal diffusion \citep{Guilyardi_al_CD01}.
-
-Note that in the partial step $z$-coordinate (\np{ln\_zps}~\forcode{= .true.}),
+any additional background horizontal diffusion \citep{guilyardi.madec.ea_CD01}.
+
+Note that in the partial step $z$-coordinate (\np{ln\_zps}\forcode{ = .true.}),
 the horizontal derivatives at the bottom level in \autoref{eq:tra_ldf_iso} require a specific treatment.
 They are calculated in module zpshde, described in \autoref{sec:TRA_zpshde}.
 
-%&&     Triad rotated (bi -)laplacian operator
+%&&     Triad rotated (bi-)laplacian operator
 %&&  -------------------------------------------
-\subsubsection{Triad rotated (bi -)laplacian operator (\protect\np{ln\_traldf\_triad})}
+\subsubsection[Triad rotated (bi-)laplacian operator (\textit{ln\_traldf\_triad})]
+{Triad rotated (bi-)laplacian operator (\protect\np{ln\_traldf\_triad})}
 \label{subsec:TRA_ldf_triad}
 
-If the Griffies triad scheme is employed (\np{ln\_traldf\_triad}~\forcode{= .true.}; see \autoref{apdx:triad})
-
-An alternative scheme developed by \cite{Griffies_al_JPO98} which ensures tracer variance decreases
-is also available in \NEMO (\np{ln\_traldf\_grif}~\forcode{= .true.}).
+If the Griffies triad scheme is employed (\np{ln\_traldf\_triad}\forcode{ = .true.}; see \autoref{apdx:triad})
+
+An alternative scheme developed by \cite{griffies.gnanadesikan.ea_JPO98} which ensures tracer variance decreases
+is also available in \NEMO (\np{ln\_traldf\_grif}\forcode{ = .true.}).
 A complete description of the algorithm is given in \autoref{apdx:triad}.
 
@@ -632,5 +644,6 @@
 % Tracer Vertical Diffusion
 % ================================================================
-\section{Tracer vertical diffusion (\protect\mdl{trazdf})}
+\section[Tracer vertical diffusion (\textit{trazdf.F90})]
+{Tracer vertical diffusion (\protect\mdl{trazdf})}
 \label{sec:TRA_zdf}
 %--------------------------------------------namzdf---------------------------------------------------------
@@ -663,9 +676,9 @@
 
 The large eddy coefficient found in the mixed layer together with high vertical resolution implies that
-in the case of explicit time stepping (\np{ln\_zdfexp}~\forcode{= .true.})
+in the case of explicit time stepping (\np{ln\_zdfexp}\forcode{ = .true.})
 there would be too restrictive a constraint on the time step.
 Therefore, the default implicit time stepping is preferred for the vertical diffusion since
 it overcomes the stability constraint.
-A forward time differencing scheme (\np{ln\_zdfexp}~\forcode{= .true.}) using
+A forward time differencing scheme (\np{ln\_zdfexp}\forcode{ = .true.}) using
 a time splitting technique (\np{nn\_zdfexp} $> 1$) is provided as an alternative.
 Namelist variables \np{ln\_zdfexp} and \np{nn\_zdfexp} apply to both tracers and dynamics.
@@ -680,5 +693,6 @@
 %        surface boundary condition
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Surface boundary condition (\protect\mdl{trasbc})}
+\subsection[Surface boundary condition (\textit{trasbc.F90})]
+{Surface boundary condition (\protect\mdl{trasbc})}
 \label{subsec:TRA_sbc}
 
@@ -730,5 +744,5 @@
 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
+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}$.
@@ -747,5 +761,5 @@
 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}.
+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}).
 
@@ -753,5 +767,6 @@
 %        Solar Radiation Penetration 
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Solar radiation penetration (\protect\mdl{traqsr})}
+\subsection[Solar radiation penetration (\textit{traqsr.F90})]
+{Solar radiation penetration (\protect\mdl{traqsr})}
 \label{subsec:TRA_qsr}
 %--------------------------------------------namqsr--------------------------------------------------------
@@ -761,7 +776,7 @@
 
 Options are defined through the \ngn{namtra\_qsr} namelist variables.
-When the penetrative solar radiation option is used (\np{ln\_flxqsr}~\forcode{= .true.}),
+When the penetrative solar radiation option is used (\np{ln\_flxqsr}\forcode{ = .true.}),
 the solar radiation penetrates the top few tens of meters of the ocean.
-If it is not used (\np{ln\_flxqsr}~\forcode{= .false.}) all the heat flux is absorbed in the first ocean level.
+If it is not used (\np{ln\_flxqsr}\forcode{ = .false.}) all the heat flux is absorbed in the first ocean level.
 Thus, in the former case a term is added to the time evolution equation of temperature \autoref{eq:PE_tra_T} and
 the surface boundary condition is modified to take into account only the non-penetrative part of the surface 
@@ -792,7 +807,7 @@
 larger depths where it contributes to local heating.
 The way this second part of the solar energy penetrates into the ocean depends on which formulation is chosen.
-In the simple 2-waveband light penetration scheme (\np{ln\_qsr\_2bd}~\forcode{= .true.})
+In the simple 2-waveband light penetration scheme (\np{ln\_qsr\_2bd}\forcode{ = .true.})
 a chlorophyll-independent monochromatic formulation is chosen for the shorter wavelengths,
-leading to the following expression \citep{Paulson1977}:
+leading to the following expression \citep{paulson.simpson_JPO77}:
 \[
   % \label{eq:traqsr_iradiance}
@@ -805,13 +820,13 @@
 
 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:traqsr_irradiance}).
 Light absorption in the ocean depends on particle concentration and is spectrally selective.
-\cite{Morel_JGR88} has shown that an accurate representation of light penetration can be provided by
+\cite{morel_JGR88} has shown that an accurate representation of light penetration can be provided by
 a 61 waveband formulation.
 Unfortunately, such a model is very computationally expensive.
-Thus, \cite{Lengaigne_al_CD07} have constructed a simplified version of this formulation in which
+Thus, \cite{lengaigne.menkes.ea_CD07} have constructed a simplified version of this formulation in which
 visible light is split into three wavebands: blue (400-500 nm), green (500-600 nm) and red (600-700nm).
 For each wave-band, the chlorophyll-dependent attenuation coefficient is fitted to the coefficients computed from
-the full spectral model of \cite{Morel_JGR88} (as modified by \cite{Morel_Maritorena_JGR01}),
+the full spectral model of \cite{morel_JGR88} (as modified by \cite{morel.maritorena_JGR01}),
 assuming the same power-law relationship.
 As shown in \autoref{fig:traqsr_irradiance}, this formulation, called RGB (Red-Green-Blue),
@@ -820,5 +835,5 @@
 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 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
 61 nonuniform chlorophyll classes ranging from 0.01 to 10 g.Chl/L
@@ -827,13 +842,13 @@
 
 \begin{description}
-\item[\np{nn\_chdta}~\forcode{= 0}]
+\item[\np{nn\_chdta}\forcode{ = 0}]
   a constant 0.05 g.Chl/L value everywhere ; 
-\item[\np{nn\_chdta}~\forcode{= 1}]
+\item[\np{nn\_chdta}\forcode{ = 1}]
   an observed time varying chlorophyll deduced from satellite surface ocean color measurement spread uniformly in
   the vertical direction;
-\item[\np{nn\_chdta}~\forcode{= 2}]
+\item[\np{nn\_chdta}\forcode{ = 2}]
   same as previous case except that a vertical profile of chlorophyl is used.
-  Following \cite{Morel_Berthon_LO89}, the profile is computed from the local surface chlorophyll value;
-\item[\np{ln\_qsr\_bio}~\forcode{= .true.}]
+  Following \cite{morel.berthon_LO89}, the profile is computed from the local surface chlorophyll value;
+\item[\np{ln\_qsr\_bio}\forcode{ = .true.}]
   simulated time varying chlorophyll by TOP biogeochemical model.
   In this case, the RGB formulation is used to calculate both the phytoplankton light limitation in
@@ -856,5 +871,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[]{Fig_TRA_Irradiance}
+    \includegraphics[width=\textwidth]{Fig_TRA_Irradiance}
     \caption{
       \protect\label{fig:traqsr_irradiance}
@@ -865,5 +880,5 @@
       61 waveband Morel (1988) formulation (black) for a chlorophyll concentration of
       (a) Chl=0.05 mg/m$^3$ and (b) Chl=0.5 mg/m$^3$.
-      From \citet{Lengaigne_al_CD07}.
+      From \citet{lengaigne.menkes.ea_CD07}.
     }
   \end{center}
@@ -874,5 +889,6 @@
 %        Bottom Boundary Condition
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Bottom boundary condition (\protect\mdl{trabbc})}
+\subsection[Bottom boundary condition (\textit{trabbc.F90})]
+{Bottom boundary condition (\protect\mdl{trabbc})}
 \label{subsec:TRA_bbc}
 %--------------------------------------------nambbc--------------------------------------------------------
@@ -883,9 +899,9 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[]{Fig_TRA_geoth}
+    \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_Nat92}.
+      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}
@@ -897,8 +913,8 @@
 This is the default option in \NEMO, and it is implemented using the masking technique.
 However, there is a non-zero heat flux across the seafloor that is associated with solid earth cooling.
-This flux is weak compared to surface fluxes (a mean global value of $\sim 0.1 \, W/m^2$ \citep{Stein_Stein_Nat92}),
+This flux is weak compared to surface fluxes (a mean global value of $\sim 0.1 \, W/m^2$ \citep{stein.stein_N92}),
 but it warms systematically the ocean and acts on the densest water masses.
 Taking this flux into account in a global ocean model increases the deepest overturning cell
-(\ie the one associated with the Antarctic Bottom Water) by a few Sverdrups \citep{Emile-Geay_Madec_OS09}.
+(\ie the one associated with the Antarctic Bottom Water) by a few Sverdrups \citep{emile-geay.madec_OS09}.
 
 Options are defined through the  \ngn{namtra\_bbc} namelist variables.
@@ -907,10 +923,11 @@
 the \np{nn\_geoflx\_cst}, which is also a namelist parameter.
 When \np{nn\_geoflx} is set to 2, a spatially varying geothermal heat flux is introduced which is provided in
-the \ifile{geothermal\_heating} NetCDF file (\autoref{fig:geothermal}) \citep{Emile-Geay_Madec_OS09}.
+the \ifile{geothermal\_heating} NetCDF file (\autoref{fig:geothermal}) \citep{emile-geay.madec_OS09}.
 
 % ================================================================
 % Bottom Boundary Layer
 % ================================================================
-\section{Bottom boundary layer (\protect\mdl{trabbl} - \protect\key{trabbl})}
+\section[Bottom boundary layer (\textit{trabbl.F90} - \texttt{\textbf{key\_trabbl}})]
+{Bottom boundary layer (\protect\mdl{trabbl} - \protect\key{trabbl})}
 \label{sec:TRA_bbl}
 %--------------------------------------------nambbl---------------------------------------------------------
@@ -931,7 +948,7 @@
 sometimes over a thickness much larger than the thickness of the observed gravity plume.
 A similar problem occurs in the $s$-coordinate when the thickness of the bottom level varies rapidly downstream of
-a sill \citep{Willebrand_al_PO01}, and the thickness of the plume is not resolved.
-
-The idea of the bottom boundary layer (BBL) parameterisation, first introduced by \citet{Beckmann_Doscher1997},
+a sill \citep{willebrand.barnier.ea_PO01}, and the thickness of the plume is not resolved.
+
+The idea of the bottom boundary layer (BBL) parameterisation, first introduced by \citet{beckmann.doscher_JPO97},
 is to allow a direct communication between two adjacent bottom cells at different levels,
 whenever the densest water is located above the less dense water.
@@ -939,10 +956,11 @@
 In the current implementation of the BBL, only the tracers are modified, not the velocities.
 Furthermore, it only connects ocean bottom cells, and therefore does not include all the improvements introduced by
-\citet{Campin_Goosse_Tel99}.
+\citet{campin.goosse_T99}.
 
 % -------------------------------------------------------------------------------------------------------------
 %        Diffusive BBL
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Diffusive bottom boundary layer (\protect\np{nn\_bbl\_ldf}~\forcode{= 1})}
+\subsection[Diffusive bottom boundary layer (\forcode{nn_bbl_ldf = 1})]
+{Diffusive bottom boundary layer (\protect\np{nn\_bbl\_ldf}\forcode{ = 1})}
 \label{subsec:TRA_bbl_diff}
 
@@ -955,5 +973,5 @@
 with $\nabla_\sigma$ the lateral gradient operator taken between bottom cells, and
 $A_l^\sigma$ the lateral diffusivity in the BBL.
-Following \citet{Beckmann_Doscher1997}, the latter is prescribed with a spatial dependence,
+Following \citet{beckmann.doscher_JPO97}, the latter is prescribed with a spatial dependence,
 \ie in the conditional form
 \begin{equation}
@@ -983,5 +1001,6 @@
 %        Advective BBL
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Advective bottom boundary layer  (\protect\np{nn\_bbl\_adv}~\forcode{= 1..2})}
+\subsection[Advective bottom boundary layer (\forcode{nn_bbl_adv = [12]})]
+{Advective bottom boundary layer (\protect\np{nn\_bbl\_adv}\forcode{ = [12]})}
 \label{subsec:TRA_bbl_adv}
 
@@ -994,5 +1013,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[]{Fig_BBL_adv}
+    \includegraphics[width=\textwidth]{Fig_BBL_adv}
     \caption{
       \protect\label{fig:bbl}
@@ -1014,18 +1033,18 @@
 %%%gmcomment   :  this section has to be really written
 
-When applying an advective BBL (\np{nn\_bbl\_adv}~\forcode{= 1..2}), an overturning circulation is added which
+When applying an advective BBL (\np{nn\_bbl\_adv}\forcode{ = 1..2}), an overturning circulation is added which
 connects two adjacent bottom grid-points only if dense water overlies less dense water on the slope.
 The density difference causes dense water to move down the slope.
 
-\np{nn\_bbl\_adv}~\forcode{= 1}:
+\np{nn\_bbl\_adv}\forcode{ = 1}:
 the downslope velocity is chosen to be the Eulerian ocean velocity just above the topographic step
-(see black arrow in \autoref{fig:bbl}) \citep{Beckmann_Doscher1997}.
+(see black arrow in \autoref{fig: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}:
+\np{nn\_bbl\_adv}\forcode{ = 2}:
 the downslope velocity is chosen to be proportional to $\Delta \rho$,
-the density difference between the higher cell and lower cell densities \citep{Campin_Goosse_Tel99}.
+the density difference between the higher cell and lower cell densities \citep{campin.goosse_T99}.
 The advection is allowed only  if dense water overlies less dense water on the slope
 (\ie $\nabla_\sigma \rho \cdot \nabla H < 0$).
@@ -1041,5 +1060,5 @@
 The parameter $\gamma$ should take a different value for each bathymetric step, but for simplicity,
 and because no direct estimation of this parameter is available, a uniform value has been assumed.
-The possible values for $\gamma$ range between 1 and $10~s$ \citep{Campin_Goosse_Tel99}.
+The possible values for $\gamma$ range between 1 and $10~s$ \citep{campin.goosse_T99}.
 
 Scalar properties are advected by this additional transport $(u^{tr}_{bbl},v^{tr}_{bbl})$ using the upwind scheme.
@@ -1074,5 +1093,6 @@
 % Tracer damping
 % ================================================================
-\section{Tracer damping (\protect\mdl{tradmp})}
+\section[Tracer damping (\textit{tradmp.F90})]
+{Tracer damping (\protect\mdl{tradmp})}
 \label{sec:TRA_dmp}
 %--------------------------------------------namtra_dmp-------------------------------------------------
@@ -1109,5 +1129,5 @@
 In the vicinity of these walls, $\gamma$ takes large values (equivalent to a time scale of a few days) whereas
 it is zero in the interior of the model domain.
-The second case corresponds to the use of the robust diagnostic method \citep{Sarmiento1982}.
+The second case corresponds to the use of the robust diagnostic method \citep{sarmiento.bryan_JGR82}.
 It allows us to find the velocity field consistent with the model dynamics whilst
 having a $T$, $S$ field close to a given climatological field ($T_o$, $S_o$).
@@ -1121,5 +1141,5 @@
 only below the mixed layer (defined either on a density or $S_o$ criterion).
 It is common to set the damping to zero in the mixed layer as the adjustment time scale is short here
-\citep{Madec_al_JPO96}.
+\citep{madec.delecluse.ea_JPO96}.
 
 For generating \ifile{resto}, see the documentation for the DMP tool provided with the source code under
@@ -1129,5 +1149,6 @@
 % Tracer time evolution
 % ================================================================
-\section{Tracer time evolution (\protect\mdl{tranxt})}
+\section[Tracer time evolution (\textit{tranxt.F90})]
+{Tracer time evolution (\protect\mdl{tranxt})}
 \label{sec:TRA_nxt}
 %--------------------------------------------namdom-----------------------------------------------------
@@ -1137,5 +1158,5 @@
 
 Options are defined through the \ngn{namdom} namelist variables.
-The general framework for tracer time stepping is a modified leap-frog scheme \citep{Leclair_Madec_OM09},
+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}
@@ -1151,7 +1172,7 @@
 (\ie fluxes plus content in mass exchanges).
 $\gamma$ is initialized as \np{rn\_atfp} (\textbf{namelist} parameter).
-Its default value is \np{rn\_atfp}~\forcode{= 10.e-3}.
+Its default value is \np{rn\_atfp}\forcode{ = 10.e-3}.
 Note that the forcing correction term in the filter is not applied in linear free surface
-(\jp{lk\_vvl}~\forcode{= .false.}) (see \autoref{subsec:TRA_sbc}).
+(\jp{lk\_vvl}\forcode{ = .false.}) (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$.
 
@@ -1166,5 +1187,6 @@
 % Equation of State (eosbn2) 
 % ================================================================
-\section{Equation of state (\protect\mdl{eosbn2}) }
+\section[Equation of state (\textit{eosbn2.F90})]
+{Equation of state (\protect\mdl{eosbn2})}
 \label{sec:TRA_eosbn2}
 %--------------------------------------------nameos-----------------------------------------------------
@@ -1176,5 +1198,6 @@
 %        Equation of State
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Equation of seawater (\protect\np{nn\_eos}~\forcode{= -1..1})}
+\subsection[Equation of seawater (\forcode{nn_eos = {-1,1}})]
+{Equation of seawater (\protect\np{nn\_eos}\forcode{ = {-1,1}})}
 \label{subsec:TRA_eos}
 
@@ -1186,8 +1209,8 @@
 Nonlinearities of the EOS are of major importance, in particular influencing the circulation through
 determination of the static stability below the mixed layer,
-thus controlling rates of exchange between the atmosphere and the ocean interior \citep{Roquet_JPO2015}.
-Therefore an accurate EOS based on either the 1980 equation of state (EOS-80, \cite{UNESCO1983}) or
-TEOS-10 \citep{TEOS10} standards should be used anytime a simulation of the real ocean circulation is attempted
-\citep{Roquet_JPO2015}.
+thus controlling rates of exchange between the atmosphere and the ocean interior \citep{roquet.madec.ea_JPO15}.
+Therefore an accurate EOS based on either the 1980 equation of state (EOS-80, \cite{fofonoff.millard_bk83}) or
+TEOS-10 \citep{ioc.iapso_bk10} standards should be used anytime a simulation of the real ocean circulation is attempted
+\citep{roquet.madec.ea_JPO15}.
 The use of TEOS-10 is highly recommended because
 \textit{(i)}   it is the new official EOS,
@@ -1195,8 +1218,8 @@
 \textit{(iii)} it uses Conservative Temperature and Absolute Salinity (instead of potential temperature and
 practical salinity for EOS-980, both variables being more suitable for use as model variables
-\citep{TEOS10, Graham_McDougall_JPO13}.
+\citep{ioc.iapso_bk10, graham.mcdougall_JPO13}.
 EOS-80 is an obsolescent feature of the NEMO system, kept only for backward compatibility.
 For process studies, it is often convenient to use an approximation of the EOS.
-To that purposed, a simplified EOS (S-EOS) inspired by \citet{Vallis06} is also available.
+To that purposed, a simplified EOS (S-EOS) inspired by \citet{vallis_bk06} is also available.
 
 In the computer code, a density anomaly, $d_a = \rho / \rho_o - 1$, is computed, with $\rho_o$ a reference density.
@@ -1204,5 +1227,5 @@
 This is a sensible choice for the reference density used in a Boussinesq ocean climate model, as,
 with the exception of only a small percentage of the ocean,
-density in the World Ocean varies by no more than 2$\%$ from that value \citep{Gill1982}.
+density in the World Ocean varies by no more than 2$\%$ from that value \citep{gill_bk82}.
 
 Options are defined through the \ngn{nameos} namelist variables, and in particular \np{nn\_eos} which
@@ -1210,6 +1233,6 @@
 
 \begin{description}
-\item[\np{nn\_eos}~\forcode{= -1}]
-  the polyTEOS10-bsq equation of seawater \citep{Roquet_OM2015} is used.
+\item[\np{nn\_eos}\forcode{ = -1}]
+  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
@@ -1217,10 +1240,10 @@
   use in ocean models.
   Note that a slightly higher precision polynomial form is now used replacement of
-  the TEOS-10 rational function approximation for hydrographic data analysis \citep{TEOS10}.
+  the TEOS-10 rational function approximation for hydrographic data analysis \citep{ioc.iapso_bk10}.
   A key point is that conservative state variables are used:
   Absolute Salinity (unit: g/kg, notation: $S_A$) and Conservative Temperature (unit: \deg{C}, notation: $\Theta$).
   The pressure in decibars is approximated by the depth in meters.
   With TEOS10, the specific heat capacity of sea water, $C_p$, is a constant.
-  It is set to $C_p = 3991.86795711963~J\,Kg^{-1}\,^{\circ}K^{-1}$, according to \citet{TEOS10}.
+  It is set to $C_p = 3991.86795711963~J\,Kg^{-1}\,^{\circ}K^{-1}$, according to \citet{ioc.iapso_bk10}.
   Choosing polyTEOS10-bsq implies that the state variables used by the model are $\Theta$ and $S_A$.
   In particular, the initial state deined by the user have to be given as \textit{Conservative} Temperature and
@@ -1229,5 +1252,5 @@
   either computing the air-sea and ice-sea fluxes (forced mode) or
   sending the SST field to the atmosphere (coupled mode).
-\item[\np{nn\_eos}~\forcode{= 0}]
+\item[\np{nn\_eos}\forcode{ = 0}]
   the polyEOS80-bsq equation of seawater is used.
   It takes the same polynomial form as the polyTEOS10, but the coefficients have been optimized to
@@ -1238,13 +1261,13 @@
   The pressure in decibars is approximated by the depth in meters.
   With thsi EOS, the specific heat capacity of sea water, $C_p$, is a function of temperature, salinity and
-  pressure \citep{UNESCO1983}.
+  pressure \citep{fofonoff.millard_bk83}.
   Nevertheless, a severe assumption is made in order to have a heat content ($C_p T_p$) which
   is conserved by the model: $C_p$ is set to a constant value, the TEOS10 value.
-\item[\np{nn\_eos}~\forcode{= 1}]
-  a simplified EOS (S-EOS) inspired by \citet{Vallis06} is chosen,
+\item[\np{nn\_eos}\forcode{ = 1}]
+  a simplified EOS (S-EOS) inspired by \citet{vallis_bk06} is chosen,
   the coefficients of which has been optimized to fit the behavior of TEOS10
-  (Roquet, personal comm.) (see also \citet{Roquet_JPO2015}).
+  (Roquet, personal comm.) (see also \citet{roquet.madec.ea_JPO15}).
   It provides a simplistic linear representation of both cabbeling and thermobaricity effects which
-  is enough for a proper treatment of the EOS in theoretical studies \citep{Roquet_JPO2015}.
+  is enough for a proper treatment of the EOS in theoretical studies \citep{roquet.madec.ea_JPO15}.
   With such an equation of state there is no longer a distinction between
   \textit{conservative} and \textit{potential} temperature,
@@ -1303,5 +1326,6 @@
 %        Brunt-V\"{a}is\"{a}l\"{a} Frequency
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Brunt-V\"{a}is\"{a}l\"{a} frequency (\protect\np{nn\_eos}~\forcode{= 0..2})}
+\subsection[Brunt-V\"{a}is\"{a}l\"{a} frequency (\forcode{nn_eos = [0-2]})]
+{Brunt-V\"{a}is\"{a}l\"{a} frequency (\protect\np{nn\_eos}\forcode{ = [0-2]})}
 \label{subsec:TRA_bn2}
 
@@ -1329,5 +1353,5 @@
 \label{subsec:TRA_fzp}
 
-The freezing point of seawater is a function of salinity and pressure \citep{UNESCO1983}:
+The freezing point of seawater is a function of salinity and pressure \citep{fofonoff.millard_bk83}:
 \begin{equation}
   \label{eq:tra_eos_fzp}
@@ -1357,5 +1381,6 @@
 % Horizontal Derivative in zps-coordinate 
 % ================================================================
-\section{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}
 
@@ -1363,9 +1388,9 @@
 I've changed "derivative" to "difference" and "mean" to "average"}
 
-With partial cells (\np{ln\_zps}~\forcode{= .true.}) at bottom and top (\np{ln\_isfcav}~\forcode{= .true.}),
+With partial cells (\np{ln\_zps}\forcode{ = .true.}) at bottom and top (\np{ln\_isfcav}\forcode{ = .true.}),
 in general, tracers in horizontally adjacent cells live at different depths.
 Horizontal gradients of tracers are needed for horizontal diffusion (\mdl{traldf} module) and
 the hydrostatic pressure gradient calculations (\mdl{dynhpg} module).
-The partial cell properties at the top (\np{ln\_isfcav}~\forcode{= .true.}) are computed in the same way as
+The partial cell properties at the top (\np{ln\_isfcav}\forcode{ = .true.}) are computed in the same way as
 for the bottom.
 So, only the bottom interpolation is explained below.
@@ -1379,9 +1404,9 @@
 \begin{figure}[!p]
   \begin{center}
-    \includegraphics[]{Fig_partial_step_scheme}
+    \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$.
+      (\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.
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_ZDF.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_ZDF.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_ZDF.tex	(revision 11422)
@@ -25,7 +25,7 @@
 At the surface they are prescribed from the surface forcing (see \autoref{chap:SBC}),
 while at the bottom they are set to zero for heat and salt,
-unless a geothermal flux forcing is prescribed as a bottom boundary condition (\ie \key{trabbl} defined,
+unless a geothermal flux forcing is prescribed as a bottom boundary condition (\ie \np{ln\_trabbc} defined,
 see \autoref{subsec:TRA_bbc}), and specified through a bottom friction parameterisation for momentum
-(see \autoref{sec:ZDF_bfr}).
+(see \autoref{sec:ZDF_drg}). 
 
 In this section we briefly discuss the various choices offered to compute the vertical eddy viscosity and
@@ -33,29 +33,31 @@
 respectively (see \autoref{sec:TRA_zdf} and \autoref{sec:DYN_zdf}).
 These coefficients can be assumed to be either constant, or a function of the local Richardson number,
-or computed from a turbulent closure model (either TKE or GLS formulation).
-The computation of these coefficients is initialized in the \mdl{zdfini} module and performed in
-the \mdl{zdfric}, \mdl{zdftke} or \mdl{zdfgls} modules.
+or computed from a turbulent closure model (either TKE or GLS or OSMOSIS formulation).
+The computation of these coefficients is initialized in the \mdl{zdfphy} module and performed in
+the \mdl{zdfric}, \mdl{zdftke} or \mdl{zdfgls} or \mdl{zdfosm} modules.
 The trends due to the vertical momentum and tracer diffusion, including the surface forcing,
 are computed and added to the general trend in the \mdl{dynzdf} and \mdl{trazdf} modules, respectively. 
-These trends can be computed using either a forward time stepping scheme
-(namelist parameter \np{ln\_zdfexp}\forcode{ = .true.}) or a backward time stepping scheme
-(\np{ln\_zdfexp}\forcode{ = .false.}) depending on the magnitude of the mixing coefficients,
-and thus of the formulation used (see \autoref{chap:STP}).
-
-% -------------------------------------------------------------------------------------------------------------
-%        Constant 
-% -------------------------------------------------------------------------------------------------------------
-\subsection{Constant (\protect\key{zdfcst})}
-\label{subsec:ZDF_cst}
-%--------------------------------------------namzdf---------------------------------------------------------
+%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.})}
+\label{subsec:ZDF_cst}
+
 Options are defined through the \ngn{namzdf} namelist variables.
-When \key{zdfcst} is defined, the momentum and tracer vertical eddy coefficients are set to
+When \np{ln\_zdfcst} is defined, the momentum and tracer vertical eddy coefficients are set to
 constant values over the whole ocean.
 This is the crudest way to define the vertical ocean physics.
-It is recommended that this option is only used in process studies, not in basin scale simulations.
+It is recommended to use this option only in process studies, not in basin scale simulations.
 Typical values used in this case are:
 \begin{align*}
@@ -72,5 +74,6 @@
 %        Richardson Number Dependent
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Richardson number dependent (\protect\key{zdfric})}
+\subsection[Richardson number dependent (\forcode{ln_zdfric = .true.})]
+{Richardson number dependent (\protect\np{ln\_zdfric}\forcode{ = .true.})}
 \label{subsec:ZDF_ric}
 
@@ -80,5 +83,5 @@
 %--------------------------------------------------------------------------------------------------------------
 
-When \key{zdfric} is defined, a local Richardson number dependent formulation for the vertical momentum and
+When \np{ln\_zdfric}\forcode{ = .true.}, a local Richardson number dependent formulation for the vertical momentum and
 tracer eddy coefficients is set through the \ngn{namzdf\_ric} namelist variables.
 The vertical mixing coefficients are diagnosed from the large scale variables computed by the model. 
@@ -87,5 +90,5 @@
 a dependency between the vertical eddy coefficients and the local Richardson number
 (\ie the ratio of stratification to vertical shear).
-Following \citet{Pacanowski_Philander_JPO81}, the following formulation has been implemented:
+Following \citet{pacanowski.philander_JPO81}, the following formulation has been implemented:
 \[
   % \label{eq:zdfric}
@@ -124,12 +127,12 @@
 The final $h_{e}$ is further constrained by the adjustable bounds \np{rn\_mldmin} and \np{rn\_mldmax}.
 Once $h_{e}$ is computed, the vertical eddy coefficients within $h_{e}$ are set to
-the empirical values \np{rn\_wtmix} and \np{rn\_wvmix} \citep{Lermusiaux2001}.
+the empirical values \np{rn\_wtmix} and \np{rn\_wvmix} \citep{lermusiaux_JMS01}.
 
 % -------------------------------------------------------------------------------------------------------------
 %        TKE Turbulent Closure Scheme 
 % -------------------------------------------------------------------------------------------------------------
-\subsection{TKE turbulent closure scheme (\protect\key{zdftke})}
+\subsection[TKE turbulent closure scheme (\forcode{ln_zdftke = .true.})]
+{TKE turbulent closure scheme (\protect\np{ln\_zdftke}\forcode{ = .true.})}
 \label{subsec:ZDF_tke}
-
 %--------------------------------------------namzdf_tke--------------------------------------------------
 
@@ -140,11 +143,11 @@
 a prognostic equation for $\bar{e}$, the turbulent kinetic energy,
 and a closure assumption for the turbulent length scales.
-This turbulent closure model has been developed by \citet{Bougeault1989} in the atmospheric case,
-adapted by \citet{Gaspar1990} for the oceanic case, and embedded in OPA, the ancestor of NEMO,
-by \citet{Blanke1993} for equatorial Atlantic simulations.
-Since then, significant modifications have been introduced by \citet{Madec1998} in both the implementation and
+This turbulent closure model has been developed by \citet{bougeault.lacarrere_MWR89} in the atmospheric case,
+adapted by \citet{gaspar.gregoris.ea_JGR90} for the oceanic case, and embedded in OPA, the ancestor of NEMO,
+by \citet{blanke.delecluse_JPO93} for equatorial Atlantic simulations.
+Since then, significant modifications have been introduced by \citet{madec.delecluse.ea_NPM98} in both the implementation and
 the formulation of the mixing length scale.
 The time evolution of $\bar{e}$ is the result of the production of $\bar{e}$ through vertical shear,
-its destruction through stratification, its vertical diffusion, and its dissipation of \citet{Kolmogorov1942} type:
+its destruction through stratification, its vertical diffusion, and its dissipation of \citet{kolmogorov_IANS42} type:
 \begin{equation}
   \label{eq:zdftke_e}
@@ -168,7 +171,7 @@
 $P_{rt}$ is the Prandtl number, $K_m$ and $K_\rho$ are the vertical eddy viscosity and diffusivity coefficients.
 The constants $C_k =  0.1$ and $C_\epsilon = \sqrt {2} /2$ $\approx 0.7$ are designed to deal with
-vertical mixing at any depth \citep{Gaspar1990}. 
+vertical mixing at any depth \citep{gaspar.gregoris.ea_JGR90}. 
 They are set through namelist parameters \np{nn\_ediff} and \np{nn\_ediss}.
-$P_{rt}$ can be set to unity or, following \citet{Blanke1993}, be a function of the local Richardson number, $R_i$:
+$P_{rt}$ can be set to unity or, following \citet{blanke.delecluse_JPO93}, be a function of the local Richardson number, $R_i$:
 \begin{align*}
   % \label{eq:prt}
@@ -180,10 +183,9 @@
   \end{cases}
 \end{align*}
-Options are defined through the  \ngn{namzdfy\_tke} namelist variables.
 The choice of $P_{rt}$ is controlled by the \np{nn\_pdl} namelist variable.
 
 At the sea surface, the value of $\bar{e}$ is prescribed from the wind stress field as
 $\bar{e}_o = e_{bb} |\tau| / \rho_o$, with $e_{bb}$ the \np{rn\_ebb} namelist parameter.
-The default value of $e_{bb}$ is 3.75. \citep{Gaspar1990}), however a much larger value can be used when
+The default value of $e_{bb}$ is 3.75. \citep{gaspar.gregoris.ea_JGR90}), however a much larger value can be used when
 taking into account the surface wave breaking (see below Eq. \autoref{eq:ZDF_Esbc}).
 The bottom value of TKE is assumed to be equal to the value of the level just above.
@@ -191,18 +193,18 @@
 the numerical scheme does not ensure its positivity.
 To overcome this problem, a cut-off in the minimum value of $\bar{e}$ is used (\np{rn\_emin} namelist parameter).
-Following \citet{Gaspar1990}, the cut-off value is set to $\sqrt{2}/2~10^{-6}~m^2.s^{-2}$.
-This allows the subsequent formulations to match that of \citet{Gargett1984} for the diffusion in
+Following \citet{gaspar.gregoris.ea_JGR90}, the cut-off value is set to $\sqrt{2}/2~10^{-6}~m^2.s^{-2}$.
+This allows the subsequent formulations to match that of \citet{gargett_JMR84} for the diffusion in
 the thermocline and deep ocean :  $K_\rho = 10^{-3} / N$.
 In addition, a cut-off is applied on $K_m$ and $K_\rho$ to avoid numerical instabilities associated with
 too weak vertical diffusion.
 They must be specified at least larger than the molecular values, and are set through \np{rn\_avm0} and
-\np{rn\_avt0} (namzdf namelist, see \autoref{subsec:ZDF_cst}).
+\np{rn\_avt0} (\ngn{namzdf} namelist, see \autoref{subsec:ZDF_cst}).
 
 \subsubsection{Turbulent length scale}
 
 For computational efficiency, the original formulation of the turbulent length scales proposed by
-\citet{Gaspar1990} has been simplified.
+\citet{gaspar.gregoris.ea_JGR90} has been simplified.
 Four formulations are proposed, the choice of which is controlled by the \np{nn\_mxl} namelist parameter.
-The first two are based on the following first order approximation \citep{Blanke1993}:
+The first two are based on the following first order approximation \citep{blanke.delecluse_JPO93}:
 \begin{equation}
   \label{eq:tke_mxl0_1}
@@ -212,8 +214,8 @@
 The resulting length scale is bounded by the distance to the surface or to the bottom
 (\np{nn\_mxl}\forcode{ = 0}) or by the local vertical scale factor (\np{nn\_mxl}\forcode{ = 1}).
-\citet{Blanke1993} notice that this simplification has two major drawbacks:
+\citet{blanke.delecluse_JPO93} notice that this simplification has two major drawbacks:
 it makes no sense for locally unstable stratification and the computation no longer uses all
 the information contained in the vertical density profile.
-To overcome these drawbacks, \citet{Madec1998} introduces the \np{nn\_mxl}\forcode{ = 2..3} cases,
+To overcome these drawbacks, \citet{madec.delecluse.ea_NPM98} introduces the \np{nn\_mxl}\forcode{ = 2, 3} cases,
 which add an extra assumption concerning the vertical gradient of the computed length scale.
 So, the length scales are first evaluated as in \autoref{eq:tke_mxl0_1} and then bounded such that:
@@ -225,5 +227,5 @@
 \autoref{eq:tke_mxl_constraint} means that the vertical variations of the length scale cannot be larger than
 the variations of depth.
-It provides a better approximation of the \citet{Gaspar1990} formulation while being much less 
+It provides a better approximation of the \citet{gaspar.gregoris.ea_JGR90} formulation while being much less 
 time consuming.
 In particular, it allows the length scale to be limited not only by the distance to the surface or
@@ -237,5 +239,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=1.00\textwidth]{Fig_mixing_length}
+    \includegraphics[width=\textwidth]{Fig_mixing_length}
     \caption{
       \protect\label{fig:mixing_length}
@@ -258,5 +260,5 @@
 In the \np{nn\_mxl}\forcode{ = 2} case, the dissipation and mixing length scales take the same value:
 $ l_k=  l_\epsilon = \min \left(\ l_{up} \;,\;  l_{dwn}\ \right)$, while in the \np{nn\_mxl}\forcode{ = 3} case,
-the dissipation and mixing turbulent length scales are give as in \citet{Gaspar1990}:
+the dissipation and mixing turbulent length scales are give as in \citet{gaspar.gregoris.ea_JGR90}:
 \[
   % \label{eq:tke_mxl_gaspar}
@@ -270,5 +272,5 @@
 Usually the surface scale is given by $l_o = \kappa \,z_o$ where $\kappa = 0.4$ is von Karman's constant and
 $z_o$ the roughness parameter of the surface.
-Assuming $z_o=0.1$~m \citep{Craig_Banner_JPO94} leads to a 0.04~m, the default value of \np{rn\_mxl0}.
+Assuming $z_o=0.1$~m \citep{craig.banner_JPO94} leads to a 0.04~m, the default value of \np{rn\_mxl0}.
 In the ocean interior a minimum length scale is set to recover the molecular viscosity when
 $\bar{e}$ reach its minimum value ($1.10^{-6}= C_k\, l_{min} \,\sqrt{\bar{e}_{min}}$ ).
@@ -277,18 +279,18 @@
 %-----------------------------------------------------------------------%
 
-Following \citet{Mellor_Blumberg_JPO04}, the TKE turbulence closure model has been modified to
+Following \citet{mellor.blumberg_JPO04}, the TKE turbulence closure model has been modified to
 include the effect of surface wave breaking energetics.
 This results in a reduction of summertime surface temperature when the mixed layer is relatively shallow.
-The \citet{Mellor_Blumberg_JPO04} modifications acts on surface length scale and TKE values and
+The \citet{mellor.blumberg_JPO04} modifications acts on surface length scale and TKE values and
 air-sea drag coefficient. 
-The latter concerns the bulk formulea and is not discussed here. 
-
-Following \citet{Craig_Banner_JPO94}, the boundary condition on surface TKE value is :
+The latter concerns the bulk formulae and is not discussed here. 
+
+Following \citet{craig.banner_JPO94}, the boundary condition on surface TKE value is :
 \begin{equation}
   \label{eq:ZDF_Esbc}
   \bar{e}_o = \frac{1}{2}\,\left(  15.8\,\alpha_{CB} \right)^{2/3} \,\frac{|\tau|}{\rho_o}
 \end{equation}
-where $\alpha_{CB}$ is the \citet{Craig_Banner_JPO94} constant of proportionality which depends on the ''wave age'',
-ranging from 57 for mature waves to 146 for younger waves \citep{Mellor_Blumberg_JPO04}. 
+where $\alpha_{CB}$ is the \citet{craig.banner_JPO94} constant of proportionality which depends on the ''wave age'',
+ranging from 57 for mature waves to 146 for younger waves \citep{mellor.blumberg_JPO04}. 
 The boundary condition on the turbulent length scale follows the Charnock's relation:
 \begin{equation}
@@ -297,13 +299,13 @@
 \end{equation}
 where $\kappa=0.40$ is the von Karman constant, and $\beta$ is the Charnock's constant.
-\citet{Mellor_Blumberg_JPO04} suggest $\beta = 2.10^{5}$ the value chosen by
-\citet{Stacey_JPO99} citing observation evidence, and
+\citet{mellor.blumberg_JPO04} suggest $\beta = 2.10^{5}$ the value chosen by
+\citet{stacey_JPO99} citing observation evidence, and
 $\alpha_{CB} = 100$ the Craig and Banner's value.
 As the surface boundary condition on TKE is prescribed through $\bar{e}_o = e_{bb} |\tau| / \rho_o$,
 with $e_{bb}$ the \np{rn\_ebb} namelist parameter, setting \np{rn\_ebb}\forcode{ = 67.83} corresponds 
 to $\alpha_{CB} = 100$.
-Further setting  \np{ln\_mxl0} to true applies \autoref{eq:ZDF_Lsbc} as surface boundary condition on length scale,
+Further setting  \np{ln\_mxl0=.true.},  applies \autoref{eq:ZDF_Lsbc} as the surface boundary condition on the length scale,
 with $\beta$ hard coded to the Stacey's value.
-Note that a minimal threshold of \np{rn\_emin0}$=10^{-4}~m^2.s^{-2}$ (namelist parameters) is applied on
+Note that a minimal threshold of \np{rn\_emin0}$=10^{-4}~m^2.s^{-2}$ (namelist parameters) is applied on the 
 surface $\bar{e}$ value.
 
@@ -315,16 +317,16 @@
 Although LC have nothing to do with convection, the circulation pattern is rather similar to
 so-called convective rolls in the atmospheric boundary layer.
-The detailed physics behind LC is described in, for example, \citet{Craik_Leibovich_JFM76}.
+The detailed physics behind LC is described in, for example, \citet{craik.leibovich_JFM76}.
 The prevailing explanation is that LC arise from a nonlinear interaction between the Stokes drift and
 wind drift currents. 
 
 Here we introduced in the TKE turbulent closure the simple parameterization of Langmuir circulations proposed by
-\citep{Axell_JGR02} for a $k-\epsilon$ turbulent closure.
+\citep{axell_JGR02} for a $k-\epsilon$ turbulent closure.
 The parameterization, tuned against large-eddy simulation, includes the whole effect of LC in
-an extra source terms of TKE, $P_{LC}$.
+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 namtke namelist.
+\forcode{.true.} in the \ngn{namzdf\_tke} namelist.
  
-By making an analogy with the characteristic convective velocity scale (\eg, \citet{D'Alessio_al_JPO98}),
+By making an analogy with the characteristic convective velocity scale (\eg, \citet{dalessio.abdella.ea_JPO98}),
 $P_{LC}$ is assumed to be : 
 \[
@@ -334,5 +336,5 @@
 With no information about the wave field, $w_{LC}$ is assumed to be proportional to 
 the Stokes drift $u_s = 0.377\,\,|\tau|^{1/2}$, where $|\tau|$ is the surface wind stress module 
-\footnote{Following \citet{Li_Garrett_JMR93}, the surface Stoke drift velocity may be expressed as
+\footnote{Following \citet{li.garrett_JMR93}, the surface Stoke drift velocity may be expressed as
   $u_s =  0.016 \,|U_{10m}|$.
   Assuming an air density of $\rho_a=1.22 \,Kg/m^3$ and a drag coefficient of
@@ -350,11 +352,11 @@
   \end{cases}
 \]
-where $c_{LC} = 0.15$ has been chosen by \citep{Axell_JGR02} as a good compromise to fit LES data.
+where $c_{LC} = 0.15$ has been chosen by \citep{axell_JGR02} as a good compromise to fit LES data.
 The chosen value yields maximum vertical velocities $w_{LC}$ of the order of a few centimeters per second.
 The value of $c_{LC}$ is set through the \np{rn\_lc} namelist parameter,
-having in mind that it should stay between 0.15 and 0.54 \citep{Axell_JGR02}. 
+having in mind that it should stay between 0.15 and 0.54 \citep{axell_JGR02}. 
 
 The $H_{LC}$ is estimated in a similar way as the turbulent length scale of TKE equations:
-$H_{LC}$ is depth to which a water parcel with kinetic energy due to Stoke drift can reach on its own by
+$H_{LC}$ is the depth to which a water parcel with kinetic energy due to Stoke drift can reach on its own by
 converting its kinetic energy to potential energy, according to 
 \[
@@ -368,5 +370,5 @@
 produce mixed-layer depths that are too shallow during summer months and windy conditions.
 This bias is particularly acute over the Southern Ocean.
-To overcome this systematic bias, an ad hoc parameterization is introduced into the TKE scheme \cite{Rodgers_2014}. 
+To overcome this systematic bias, an ad hoc parameterization is introduced into the TKE scheme \cite{rodgers.aumont.ea_B14}. 
 The parameterization is an empirical one, \ie not derived from theoretical considerations,
 but rather is meant to account for observed processes that affect the density structure of 
@@ -383,7 +385,7 @@
 \end{equation}
 where $z$ is the depth, $e_s$ is TKE surface boundary condition, $f_r$ is the fraction of the surface TKE that
-penetrate in the ocean, $h_\tau$ is a vertical mixing length scale that controls exponential shape of
+penetrates in the ocean, $h_\tau$ is a vertical mixing length scale that controls exponential shape of
 the penetration, and $f_i$ is the ice concentration
-(no penetration if $f_i=1$, that is if the ocean is entirely covered by sea-ice).
+(no penetration if $f_i=1$, \ie if the ocean is entirely covered by sea-ice).
 The value of $f_r$, usually a few percents, is specified through \np{rn\_efr} namelist parameter.
 The vertical mixing length scale, $h_\tau$, can be set as a 10~m uniform value (\np{nn\_etau}\forcode{ = 0}) or
@@ -391,9 +393,14 @@
 (\np{nn\_etau}\forcode{ = 1}). 
 
-Note that two other option existe, \np{nn\_etau}\forcode{ = 2..3}.
+Note that two other option exist, \np{nn\_etau}\forcode{ = 2, 3}.
 They correspond to applying \autoref{eq:ZDF_Ehtau} only at the base of the mixed layer,
-or to using the high frequency part of the stress to evaluate the fraction of TKE that penetrate the ocean. 
+or to using the high frequency part of the stress to evaluate the fraction of TKE that penetrates the ocean. 
 Those two options are obsolescent features introduced for test purposes.
 They will be removed in the next release. 
+
+% This should be explain better below what this rn_eice parameter is meant for:
+In presence of Sea Ice, the value of this mixing can be modulated by the \np{rn\_eice} namelist parameter.
+This parameter varies from \forcode{0} for no effect to \forcode{4} to suppress the TKE input into the ocean when Sea Ice concentration
+is greater than 25\%. 
 
 % from Burchard et al OM 2008 : 
@@ -406,7 +413,143 @@
 
 % -------------------------------------------------------------------------------------------------------------
-%        TKE discretization considerations
-% -------------------------------------------------------------------------------------------------------------
-\subsection{TKE discretization considerations (\protect\key{zdftke})}
+%        GLS Generic Length Scale Scheme 
+% -------------------------------------------------------------------------------------------------------------
+\subsection[GLS: Generic Length Scale (\forcode{ln_zdfgls = .true.})]
+{GLS: Generic Length Scale (\protect\np{ln\_zdfgls}\forcode{ = .true.})}
+\label{subsec:ZDF_gls}
+
+%--------------------------------------------namzdf_gls---------------------------------------------------------
+
+\nlst{namzdf_gls}
+%--------------------------------------------------------------------------------------------------------------
+
+The Generic Length Scale (GLS) scheme is a turbulent closure scheme based on two prognostic equations:
+one for the turbulent kinetic energy $\bar {e}$, and another for the generic length scale,
+$\psi$ \citep{umlauf.burchard_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
+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}
+  \frac{\partial \bar{e}}{\partial t} =
+  \frac{K_m}{\sigma_e e_3 }\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2
+      +\left( \frac{\partial v}{\partial k} \right)^2} \right]
+  -K_\rho \,N^2
+  +\frac{1}{e_3}\,\frac{\partial}{\partial k} \left[ \frac{K_m}{e_3}\,\frac{\partial \bar{e}}{\partial k} \right]
+  - \epsilon
+\end{equation}
+
+\[
+  % \label{eq:zdfgls_psi}
+  \begin{split}
+    \frac{\partial \psi}{\partial t} =& \frac{\psi}{\bar{e}} \left\{
+      \frac{C_1\,K_m}{\sigma_{\psi} {e_3}}\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2
+          +\left( \frac{\partial v}{\partial k} \right)^2} \right]
+      - C_3 \,K_\rho\,N^2   - C_2 \,\epsilon \,Fw   \right\}             \\
+    &+\frac{1}{e_3}  \;\frac{\partial }{\partial k}\left[ {\frac{K_m}{e_3 }
+        \;\frac{\partial \psi}{\partial k}} \right]\;
+  \end{split}
+\]
+
+\[
+  % \label{eq:zdfgls_kz}
+  \begin{split}
+    K_m    &= C_{\mu} \ \sqrt {\bar{e}} \ l         \\
+    K_\rho &= C_{\mu'}\ \sqrt {\bar{e}} \ l
+  \end{split}
+\]
+
+\[
+  % \label{eq:zdfgls_eps}
+  {\epsilon} = C_{0\mu} \,\frac{\bar {e}^{3/2}}{l} \;
+\]
+where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}) and
+$\epsilon$ the dissipation rate. 
+The constants $C_1$, $C_2$, $C_3$, ${\sigma_e}$, ${\sigma_{\psi}}$ and the wall function ($Fw$) depends of
+the choice of the turbulence model.
+Four different turbulent models are pre-defined (\autoref{tab:GLS}).
+They are made available through the \np{nn\_clo} namelist parameter. 
+
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[htbp]
+  \begin{center}
+    % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}c}
+    \begin{tabular}{ccccc}
+      &   $k-kl$   & $k-\epsilon$ & $k-\omega$ &   generic   \\
+      % & \citep{mellor.yamada_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\ngn{namzdf\_gls}.
+    }
+  \end{center}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+
+In the Mellor-Yamada model, the negativity of $n$ allows to use a wall function to force the convergence of
+the mixing length towards $\kappa z_b$ ($\kappa$ is the Von Karman constant and $z_b$ the rugosity length scale) value near physical boundaries
+(logarithmic boundary layer law).
+$C_{\mu}$ and $C_{\mu'}$ are calculated from stability function proposed by \citet{galperin.kantha.ea_JAS88},
+or by \citet{kantha.clayson_JGR94} or one of the two functions suggested by \citet{canuto.howard.ea_JPO01}
+(\np{nn\_stab\_func}\forcode{ = 0, 3}, resp.).  
+The value of $C_{0\mu}$ depends on the choice of the stability function.
+
+The surface and bottom boundary condition on both $\bar{e}$ and $\psi$ can be calculated thanks to Dirichlet or
+Neumann condition through \np{nn\_bc\_surf} and \np{nn\_bc\_bot}, resp.
+As for TKE closure, the wave effect on the mixing is considered when
+\np{rn\_crban}\forcode{ > 0.} \citep{craig.banner_JPO94, mellor.blumberg_JPO04}.
+The \np{rn\_crban} namelist parameter is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and
+\np{rn\_charn} provides the value of $\beta$ in \autoref{eq:ZDF_Lsbc}. 
+
+The $\psi$ equation is known to fail in stably stratified flows, and for this reason
+almost all authors apply a clipping of the length scale as an \textit{ad hoc} remedy.
+With this clipping, the maximum permissible length scale is determined by $l_{max} = c_{lim} \sqrt{2\bar{e}}/ N$.
+A value of $c_{lim} = 0.53$ is often used \citep{galperin.kantha.ea_JAS88}.
+\cite{umlauf.burchard_CSR05} show that the value of the clipping factor is of crucial importance for
+the entrainment depth predicted in stably stratified situations,
+and that its value has to be chosen in accordance with the algebraic model for the turbulent fluxes.
+The clipping is only activated if \np{ln\_length\_lim}\forcode{ = .true.},
+and the $c_{lim}$ is set to the \np{rn\_clim\_galp} value.
+
+The time and space discretization of the GLS equations follows the same energetic consideration as for
+the TKE case described in \autoref{subsec:ZDF_tke_ene} \citep{burchard_OM02}.
+Evaluation of the 4 GLS turbulent closure schemes can be found in \citet{warner.sherwood.ea_OM05} in ROMS model and
+ in \citet{reffray.guillaume.ea_GMD15} for the \NEMO model.
+
+
+% -------------------------------------------------------------------------------------------------------------
+%        OSM OSMOSIS BL Scheme 
+% -------------------------------------------------------------------------------------------------------------
+\subsection[OSM: OSMosis boundary layer scheme (\forcode{ln_zdfosm = .true.})]
+{OSM: OSMosis boundary layer scheme (\protect\np{ln\_zdfosm}\forcode{ = .true.})}
+\label{subsec:ZDF_osm}
+%--------------------------------------------namzdf_osm---------------------------------------------------------
+
+\nlst{namzdf_osm}
+%--------------------------------------------------------------------------------------------------------------
+
+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}
 
@@ -414,8 +557,8 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=1.00\textwidth]{Fig_ZDF_TKE_time_scheme}
+    \includegraphics[width=\textwidth]{Fig_ZDF_TKE_time_scheme}
     \caption{
       \protect\label{fig:TKE_time_scheme}
-      Illustration of the TKE time integration and its links to the momentum and tracer time integration.
+      Illustration of the subgrid kinetic energy integration in GLS and TKE schemes and its links to the momentum and tracer time integration.
     }
   \end{center}  
@@ -424,12 +567,12 @@
 
 The production of turbulence by vertical shear (the first term of the right hand side of
-\autoref{eq:zdftke_e}) should balance the loss of kinetic energy associated with the vertical momentum diffusion
+\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}).
-To do so a special care have to be taken for both the time and space discretization of
-the TKE equation \citep{Burchard_OM02,Marsaleix_al_OM08}.
+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
 the two-level Leap-Frog time stepping of the momentum and tracer equations interplays with
-the one-level forward time stepping of TKE equation.
+the one-level forward time stepping of the equation for $\bar{e}$.
 With this framework, the total loss of kinetic energy (in 1D for the demonstration) due to
 the vertical momentum diffusion is obtained by multiplying this quantity by $u^t$ and
@@ -456,8 +599,8 @@
 
 A similar consideration applies on the destruction rate of $\bar{e}$ due to stratification
-(second term of the right hand side of \autoref{eq:zdftke_e}).
+(second term of the right hand side of \autoref{eq:zdftke_e} and \autoref{eq:zdfgls_e}).
 This term must balance the input of potential energy resulting from vertical mixing.
-The rate of change of potential energy (in 1D for the demonstration) due vertical mixing is obtained by
-multiplying vertical density diffusion tendency by $g\,z$ and and summing the result vertically:
+The rate of change of potential energy (in 1D for the demonstration) due to vertical mixing is obtained by
+multiplying the vertical density diffusion tendency by $g\,z$ and and summing the result vertically:
 \begin{equation}
   \label{eq:energ2}
@@ -475,5 +618,5 @@
 The second term is minus the destruction rate of  $\bar{e}$ due to stratification.
 Therefore \autoref{eq:energ1} implies that, to be energetically consistent,
-the product ${K_\rho}^{t-\rdt}\,(N^2)^t$ should be used in \autoref{eq:zdftke_e}, the TKE equation.
+the product ${K_\rho}^{t-\rdt}\,(N^2)^t$ should be used in \autoref{eq:zdftke_e} and  \autoref{eq:zdfgls_e}.
 
 Let us now address the space discretization issue.
@@ -483,5 +626,5 @@
 By redoing the \autoref{eq:energ1} in the 3D case, it can be shown that the product of eddy coefficient by
 the shear at $t$ and $t-\rdt$ must be performed prior to the averaging.
-Furthermore, the possible time variation of $e_3$ (\key{vvl} case) have to be taken into account.
+Furthermore, the time variation of $e_3$ has be taken into account.
 
 The above energetic considerations leads to the following final discrete form for the TKE equation:
@@ -507,139 +650,7 @@
 are time stepped using a backward scheme (see\autoref{sec:STP_forward_imp}).
 Note that the Kolmogorov term has been linearized in time in order to render the implicit computation possible.
-The restart of the TKE scheme requires the storage of $\bar {e}$, $K_m$, $K_\rho$ and $l_\epsilon$ as
-they all appear in the right hand side of \autoref{eq:zdftke_ene}.
-For the latter, it is in fact the ratio $\sqrt{\bar{e}}/l_\epsilon$ which is stored. 
-
-% -------------------------------------------------------------------------------------------------------------
-%        GLS Generic Length Scale Scheme 
-% -------------------------------------------------------------------------------------------------------------
-\subsection{GLS: Generic Length Scale (\protect\key{zdfgls})}
-\label{subsec:ZDF_gls}
-
-%--------------------------------------------namzdf_gls---------------------------------------------------------
-
-\nlst{namzdf_gls}
-%--------------------------------------------------------------------------------------------------------------
-
-The Generic Length Scale (GLS) scheme is a turbulent closure scheme based on two prognostic equations:
-one for the turbulent kinetic energy $\bar {e}$, and another for the generic length scale,
-$\psi$ \citep{Umlauf_Burchard_JMS03, Umlauf_Burchard_CSR05}.
-This later variable is defined as: $\psi = {C_{0\mu}}^{p} \ {\bar{e}}^{m} \ l^{n}$, 
-where the triplet $(p, m, n)$ value given in Tab.\autoref{tab:GLS} allows to recover a number of
-well-known turbulent closures ($k$-$kl$ \citep{Mellor_Yamada_1982}, $k$-$\epsilon$ \citep{Rodi_1987},
-$k$-$\omega$ \citep{Wilcox_1988} among others \citep{Umlauf_Burchard_JMS03,Kantha_Carniel_CSR05}). 
-The GLS scheme is given by the following set of equations:
-\begin{equation}
-  \label{eq:zdfgls_e}
-  \frac{\partial \bar{e}}{\partial t} =
-  \frac{K_m}{\sigma_e e_3 }\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2
-      +\left( \frac{\partial v}{\partial k} \right)^2} \right]
-  -K_\rho \,N^2
-  +\frac{1}{e_3}\,\frac{\partial}{\partial k} \left[ \frac{K_m}{e_3}\,\frac{\partial \bar{e}}{\partial k} \right]
-  - \epsilon
-\end{equation}
-
-\[
-  % \label{eq:zdfgls_psi}
-  \begin{split}
-    \frac{\partial \psi}{\partial t} =& \frac{\psi}{\bar{e}} \left\{
-      \frac{C_1\,K_m}{\sigma_{\psi} {e_3}}\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2
-          +\left( \frac{\partial v}{\partial k} \right)^2} \right]
-      - C_3 \,K_\rho\,N^2   - C_2 \,\epsilon \,Fw   \right\}             \\
-    &+\frac{1}{e_3}  \;\frac{\partial }{\partial k}\left[ {\frac{K_m}{e_3 }
-        \;\frac{\partial \psi}{\partial k}} \right]\;
-  \end{split}
-\]
-
-\[
-  % \label{eq:zdfgls_kz}
-  \begin{split}
-    K_m    &= C_{\mu} \ \sqrt {\bar{e}} \ l         \\
-    K_\rho &= C_{\mu'}\ \sqrt {\bar{e}} \ l
-  \end{split}
-\]
-
-\[
-  % \label{eq:zdfgls_eps}
-  {\epsilon} = C_{0\mu} \,\frac{\bar {e}^{3/2}}{l} \;
-\]
-where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}) and
-$\epsilon$ the dissipation rate. 
-The constants $C_1$, $C_2$, $C_3$, ${\sigma_e}$, ${\sigma_{\psi}}$ and the wall function ($Fw$) depends of
-the choice of the turbulence model.
-Four different turbulent models are pre-defined (Tab.\autoref{tab:GLS}).
-They are made available through the \np{nn\_clo} namelist parameter. 
-
-%--------------------------------------------------TABLE--------------------------------------------------
-\begin{table}[htbp]
-  \begin{center}
-    % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}c}
-    \begin{tabular}{ccccc}
-      &   $k-kl$   & $k-\epsilon$ & $k-\omega$ &   generic   \\
-      % & \citep{Mellor_Yamada_1982} &  \citep{Rodi_1987}       & \citep{Wilcox_1988} &                 \\
-      \hline
-      \hline
-      \np{nn\_clo}     & \textbf{0} &   \textbf{1}  &   \textbf{2}   &    \textbf{3}   \\
-      \hline
-      $( p , n , m )$	       &   ( 0 , 1 , 1 )   & ( 3 , 1.5 , -1 )   & ( -1 , 0.5 , -1 )    &  ( 2 , 1 , -0.67 )  \\
-      $\sigma_k$      &    2.44         &     1.              &      2.                &      0.8          \\
-      $\sigma_\psi$  &    2.44         &     1.3            &      2.                 &       1.07       \\
-      $C_1$              &      0.9         &     1.44          &      0.555          &       1.           \\
-      $C_2$              &      0.5         &     1.92          &      0.833          &       1.22       \\
-      $C_3$              &      1.           &     1.              &      1.                &       1.           \\
-      $F_{wall}$        &      Yes        &       --             &     --                  &      --          \\
-      \hline
-      \hline
-    \end{tabular}
-    \caption{
-      \protect\label{tab:GLS}
-      Set of predefined GLS parameters, or equivalently predefined turbulence models available with
-      \protect\key{zdfgls} and controlled by the \protect\np{nn\_clos} namelist variable in \protect\ngn{namzdf\_gls}.
-    }
-  \end{center}
-\end{table}
-%--------------------------------------------------------------------------------------------------------------
-
-In the Mellor-Yamada model, the negativity of $n$ allows to use a wall function to force the convergence of
-the mixing length towards $K z_b$ ($K$: Kappa and $z_b$: rugosity length) value near physical boundaries
-(logarithmic boundary layer law).
-$C_{\mu}$ and $C_{\mu'}$ are calculated from stability function proposed by \citet{Galperin_al_JAS88},
-or by \citet{Kantha_Clayson_1994} or one of the two functions suggested by \citet{Canuto_2001}
-(\np{nn\_stab\_func}\forcode{ = 0..3}, resp.). 
-The value of $C_{0\mu}$ depends of the choice of the stability function.
-
-The surface and bottom boundary condition on both $\bar{e}$ and $\psi$ can be calculated thanks to Dirichlet or
-Neumann condition through \np{nn\_tkebc\_surf} and \np{nn\_tkebc\_bot}, resp.
-As for TKE closure, the wave effect on the mixing is considered when
-\np{ln\_crban}\forcode{ = .true.} \citep{Craig_Banner_JPO94, Mellor_Blumberg_JPO04}.
-The \np{rn\_crban} namelist parameter is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and
-\np{rn\_charn} provides the value of $\beta$ in \autoref{eq:ZDF_Lsbc}. 
-
-The $\psi$ equation is known to fail in stably stratified flows, and for this reason
-almost all authors apply a clipping of the length scale as an \textit{ad hoc} remedy.
-With this clipping, the maximum permissible length scale is determined by $l_{max} = c_{lim} \sqrt{2\bar{e}}/ N$.
-A value of $c_{lim} = 0.53$ is often used \citep{Galperin_al_JAS88}.
-\cite{Umlauf_Burchard_CSR05} show that the value of the clipping factor is of crucial importance for
-the entrainment depth predicted in stably stratified situations,
-and that its value has to be chosen in accordance with the algebraic model for the turbulent fluxes.
-The clipping is only activated if \np{ln\_length\_lim}\forcode{ = .true.},
-and the $c_{lim}$ is set to the \np{rn\_clim\_galp} value.
-
-The time and space discretization of the GLS equations follows the same energetic consideration as for
-the TKE case described in \autoref{subsec:ZDF_tke_ene} \citep{Burchard_OM02}.
-Examples of performance of the 4 turbulent closure scheme can be found in \citet{Warner_al_OM05}.
-
-% -------------------------------------------------------------------------------------------------------------
-%        OSM OSMOSIS BL Scheme 
-% -------------------------------------------------------------------------------------------------------------
-\subsection{OSM: OSMOSIS boundary layer scheme (\protect\key{zdfosm})}
-\label{subsec:ZDF_osm}
-
-%--------------------------------------------namzdf_osm---------------------------------------------------------
-
-\nlst{namzdf_osm}
-%--------------------------------------------------------------------------------------------------------------
-
-The OSMOSIS turbulent closure scheme is based on......   TBC
+%The restart of the TKE scheme requires the storage of $\bar {e}$, $K_m$, $K_\rho$ and $l_\epsilon$ as
+%they all appear in the right hand side of \autoref{eq:zdftke_ene}.
+%For the latter, it is in fact the ratio $\sqrt{\bar{e}}/l_\epsilon$ which is stored. 
 
 % ================================================================
@@ -648,9 +659,4 @@
 \section{Convection}
 \label{sec:ZDF_conv}
-
-%--------------------------------------------namzdf--------------------------------------------------------
-
-\nlst{namzdf}
-%--------------------------------------------------------------------------------------------------------------
 
 Static instabilities (\ie light potential densities under heavy ones) may occur at particular ocean grid points.
@@ -664,17 +670,12 @@
 %       Non-Penetrative Convective Adjustment 
 % -------------------------------------------------------------------------------------------------------------
-\subsection[Non-penetrative convective adjmt (\protect\np{ln\_tranpc}\forcode{ = .true.})]
-				{Non-penetrative convective adjustment (\protect\np{ln\_tranpc}\forcode{ = .true.})}
+\subsection[Non-penetrative convective adjustment (\forcode{ln_tranpc = .true.})]
+{Non-penetrative convective adjustment (\protect\np{ln\_tranpc}\forcode{ = .true.})}
 \label{subsec:ZDF_npc}
-
-%--------------------------------------------namzdf--------------------------------------------------------
-
-\nlst{namzdf}
-%--------------------------------------------------------------------------------------------------------------
 
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!htb]
   \begin{center}
-    \includegraphics[width=0.90\textwidth]{Fig_npc}
+    \includegraphics[width=\textwidth]{Fig_npc}
     \caption{
       \protect\label{fig:npc}
@@ -700,5 +701,5 @@
 the water column, but only until the density structure becomes neutrally stable
 (\ie until the mixed portion of the water column has \textit{exactly} the density of the water just below)
-\citep{Madec_al_JPO91}.
+\citep{madec.delecluse.ea_JPO91}.
 The associated algorithm is an iterative process used in the following way (\autoref{fig:npc}):
 starting from the top of the ocean, the first instability is found.
@@ -718,8 +719,8 @@
 the algorithm used in \NEMO converges for any profile in a number of iterations which is less than
 the number of vertical levels.
-This property is of paramount importance as pointed out by \citet{Killworth1989}:
+This property is of paramount importance as pointed out by \citet{killworth_iprc89}:
 it avoids the existence of permanent and unrealistic static instabilities at the sea surface.
 This non-penetrative convective algorithm has been proved successful in studies of the deep water formation in
-the north-western Mediterranean Sea \citep{Madec_al_JPO91, Madec_al_DAO91, Madec_Crepon_Bk91}.
+the north-western Mediterranean Sea \citep{madec.delecluse.ea_JPO91, madec.chartier.ea_DAO91, madec.crepon_iprc91}.
 
 The current implementation has been modified in order to deal with any non linear equation of seawater
@@ -727,5 +728,5 @@
 Two main differences have been introduced compared to the original algorithm:
 $(i)$ the stability is now checked using the Brunt-V\"{a}is\"{a}l\"{a} frequency 
-(not the the difference in potential density); 
+(not the difference in potential density); 
 $(ii)$ when two levels are found unstable, their thermal and haline expansion coefficients are vertically mixed in
 the same way their temperature and salinity has been mixed.
@@ -736,17 +737,13 @@
 %       Enhanced Vertical Diffusion 
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Enhanced vertical diffusion (\protect\np{ln\_zdfevd}\forcode{ = .true.})}
+\subsection[Enhanced vertical diffusion (\forcode{ln_zdfevd = .true.})]
+{Enhanced vertical diffusion (\protect\np{ln\_zdfevd}\forcode{ = .true.})}
 \label{subsec:ZDF_evd}
-
-%--------------------------------------------namzdf--------------------------------------------------------
-
-\nlst{namzdf}
-%--------------------------------------------------------------------------------------------------------------
 
 Options are defined through the  \ngn{namzdf} namelist variables.
 The enhanced vertical diffusion parameterisation is used when \np{ln\_zdfevd}\forcode{ = .true.}.
-In this case, the vertical eddy mixing coefficients are assigned very large values
-(a typical value is $10\;m^2s^{-1})$ in regions where the stratification is unstable
-(\ie when $N^2$ the Brunt-Vais\"{a}l\"{a} frequency is negative) \citep{Lazar_PhD97, Lazar_al_JPO99}.
+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}).
@@ -759,23 +756,24 @@
 the convective adjustment algorithm presented above when mixing both tracers and
 momentum in the case of static instabilities.
-It requires the use of an implicit time stepping on vertical diffusion terms
-(\ie np{ln\_zdfexp}\forcode{ = .false.}).
 
 Note that the stability test is performed on both \textit{before} and \textit{now} values of $N^2$.
 This removes a potential source of divergence of odd and even time step in
-a leapfrog environment \citep{Leclair_PhD2010} (see \autoref{sec:STP_mLF}).
+a leapfrog environment \citep{leclair_phd10} (see \autoref{sec:STP_mLF}).
 
 % -------------------------------------------------------------------------------------------------------------
 %       Turbulent Closure Scheme 
 % -------------------------------------------------------------------------------------------------------------
-\subsection[Turbulent closure scheme (\protect\key{zdf}\{tke,gls,osm\})]{Turbulent Closure Scheme (\protect\key{zdftke}, \protect\key{zdfgls} or \protect\key{zdfosm})}
+\subsection[Handling convection with turbulent closure schemes (\forcode{ln_zdf/tke/gls/osm = .true.})]
+{Handling convection with turbulent closure schemes (\protect\np{ln\_zdf/tke/gls/osm}\forcode{ = .true.})}
 \label{subsec:ZDF_tcs}
 
-The turbulent closure scheme presented in \autoref{subsec:ZDF_tke} and \autoref{subsec:ZDF_gls}
-(\key{zdftke} or \key{zdftke} is defined) in theory solves the problem of statically unstable density profiles.
+
+The turbulent closure schemes presented in \autoref{subsec:ZDF_tke}, \autoref{subsec:ZDF_gls} and
+\autoref{subsec:ZDF_osm} (\ie \np{ln\_zdftke} or \np{ln\_zdfgls} or \np{ln\_zdfosm} defined) deal, in theory, 
+with statically unstable density profiles.
 In such a case, the term corresponding to the destruction of turbulent kinetic energy through stratification in
 \autoref{eq:zdftke_e} or \autoref{eq:zdfgls_e} becomes a source term, since $N^2$ is negative. 
-It results in large values of $A_T^{vT}$ and  $A_T^{vT}$, and also the four neighbouring $A_u^{vm} {and}\;A_v^{vm}$
-(up to $1\;m^2s^{-1}$).
+It results in large values of $A_T^{vT}$ and  $A_T^{vT}$, and also of the four neighboring values at 
+velocity points $A_u^{vm} {and}\;A_v^{vm}$ (up to $1\;m^2s^{-1}$).
 These large values restore the static stability of the water column in a way similar to that of
 the enhanced vertical diffusion parameterisation (\autoref{subsec:ZDF_evd}).
@@ -785,9 +783,9 @@
 It can thus be useful to combine the enhanced vertical diffusion with the turbulent closure scheme,
 \ie setting the \np{ln\_zdfnpc} namelist parameter to true and
-defining the turbulent closure CPP key all together.
-
-The KPP turbulent closure scheme already includes enhanced vertical diffusion in the case of convection,
-as governed by the variables $bvsqcon$ and $difcon$ found in \mdl{zdfkpp},
-therefore \np{ln\_zdfevd}\forcode{ = .false.} should be used with the KPP scheme.
+defining the turbulent closure (\np{ln\_zdftke} or \np{ln\_zdfgls} = \forcode{.true.}) all together.
+
+The OSMOSIS turbulent closure scheme already includes enhanced vertical diffusion in the case of convection,
+%as governed by the variables $bvsqcon$ and $difcon$ found in \mdl{zdfkpp},
+therefore \np{ln\_zdfevd}\forcode{ = .false.} should be used with the OSMOSIS scheme.
 % gm%  + one word on non local flux with KPP scheme trakpp.F90 module...
 
@@ -795,6 +793,8 @@
 % Double Diffusion Mixing
 % ================================================================
-\section{Double diffusion mixing (\protect\key{zdfddm})}
-\label{sec:ZDF_ddm}
+\section[Double diffusion mixing (\forcode{ln_zdfddm = .true.})]
+{Double diffusion mixing (\protect\np{ln\_zdfddm}\forcode{ = .true.})}
+\label{subsec:ZDF_ddm}
+
 
 %-------------------------------------------namzdf_ddm-------------------------------------------------
@@ -803,12 +803,13 @@
 %--------------------------------------------------------------------------------------------------------------
 
-Options are defined through the  \ngn{namzdf\_ddm} namelist variables.
+This parameterisation has been introduced in \mdl{zdfddm} module and is controlled by the namelist parameter
+\np{ln\_zdfddm} in \ngn{namzdf}.
 Double diffusion occurs when relatively warm, salty water overlies cooler, fresher water, or vice versa.
 The former condition leads to salt fingering and the latter to diffusive convection.
 Double-diffusive phenomena contribute to diapycnal mixing in extensive regions of the ocean.
-\citet{Merryfield1999} include a parameterisation of such phenomena in a global ocean model and show that 
+\citet{merryfield.holloway.ea_JPO99} include a parameterisation of such phenomena in a global ocean model and show that 
 it leads to relatively minor changes in circulation but exerts significant regional influences on
 temperature and salinity.
-This parameterisation has been introduced in \mdl{zdfddm} module and is controlled by the \key{zdfddm} CPP key.
+
 
 Diapycnal mixing of S and T are described by diapycnal diffusion coefficients 
@@ -839,8 +840,8 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=0.99\textwidth]{Fig_zdfddm}
+    \includegraphics[width=\textwidth]{Fig_zdfddm}
     \caption{
       \protect\label{fig:zdfddm}
-      From \citet{Merryfield1999} :
+      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}$;
@@ -855,6 +856,6 @@
 
 The factor 0.7 in \autoref{eq:zdfddm_f_T} reflects the measured ratio $\alpha F_T /\beta F_S \approx  0.7$ of
-buoyancy flux of heat to buoyancy flux of salt (\eg, \citet{McDougall_Taylor_JMR84}).
-Following  \citet{Merryfield1999}, we adopt $R_c = 1.6$, $n = 6$, and $A^{\ast v} = 10^{-4}~m^2.s^{-1}$.
+buoyancy flux of heat to buoyancy flux of salt (\eg, \citet{mcdougall.taylor_JMR84}).
+Following  \citet{merryfield.holloway.ea_JPO99}, we adopt $R_c = 1.6$, $n = 6$, and $A^{\ast v} = 10^{-4}~m^2.s^{-1}$.
 
 To represent mixing of S and T by diffusive layering,  the diapycnal diffusivities suggested by
@@ -887,17 +888,21 @@
 % Bottom Friction
 % ================================================================
-\section{Bottom and top friction (\protect\mdl{zdfbfr})}
-\label{sec:ZDF_bfr}
+ \section[Bottom and top friction (\textit{zdfdrg.F90})]
+ {Bottom and top friction (\protect\mdl{zdfdrg})}
+ \label{sec:ZDF_drg}
 
 %--------------------------------------------nambfr--------------------------------------------------------
 %
-%\nlst{nambfr}
+\nlst{namdrg}
+\nlst{namdrg_top}
+\nlst{namdrg_bot}
+
 %--------------------------------------------------------------------------------------------------------------
 
-Options to define the top and bottom friction are defined through the \ngn{nambfr} namelist variables.
+Options to define the top and bottom friction are defined through the \ngn{namdrg} namelist variables.
 The bottom friction represents the friction generated by the bathymetry.
 The top friction represents the friction generated by the ice shelf/ocean interface.
-As the friction processes at the top and bottom are treated in similar way,
-only the bottom friction is described in detail below.
+As the friction processes at the top and the bottom are treated in and identical way, 
+the description below considers mostly the bottom friction case, if not stated otherwise.
 
 
@@ -905,8 +910,8 @@
 a condition on the vertical diffusive flux.
 For the bottom boundary layer, one has:
-\[
-  % \label{eq:zdfbfr_flux}
-  A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U}
-\]
+ \[
+   % \label{eq:zdfbfr_flux}
+   A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U}
+ \]
 where ${\cal F}_h^{\textbf U}$ is represents the downward flux of horizontal momentum outside
 the logarithmic turbulent boundary layer (thickness of the order of 1~m in the ocean).
@@ -922,5 +927,5 @@
 To illustrate this, consider the equation for $u$ at $k$, the last ocean level:
 \begin{equation}
-  \label{eq:zdfbfr_flux2}
+  \label{eq:zdfdrg_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}
@@ -935,10 +940,10 @@
 
 In the code, the bottom friction is imposed by adding the trend due to the bottom friction to
-the general momentum trend in \mdl{dynbfr}.
+ the general momentum trend in \mdl{dynzdf}.
 For the time-split surface pressure gradient algorithm, the momentum trend due to
 the barotropic component needs to be handled separately.
 For this purpose it is convenient to compute and store coefficients which can be simply combined with
 bottom velocities and geometric values to provide the momentum trend due to bottom friction.
-These coefficients are computed in \mdl{zdfbfr} and generally take the form $c_b^{\textbf U}$ where:
+ These coefficients are computed in \mdl{zdfdrg} and generally take the form $c_b^{\textbf U}$ where:
 \begin{equation}
   \label{eq:zdfbfr_bdef}
@@ -946,127 +951,134 @@
   - \frac{{\cal F}^{\textbf U}_{h}}{e_{3u}} = \frac{c_b^{\textbf U}}{e_{3u}} \;{\textbf U}_h^b
 \end{equation}
-where $\textbf{U}_h^b = (u_b\;,\;v_b)$ is the near-bottom, horizontal, ocean velocity.
+where $\textbf{U}_h^b = (u_b\;,\;v_b)$ is the near-bottom, horizontal, ocean velocity. 
+Note than from \NEMO 4.0, drag coefficients are only computed at cell centers (\ie at T-points) and refer to as $c_b^T$ in the following. These are then linearly interpolated in space to get $c_b^\textbf{U}$ at velocity points.
 
 % -------------------------------------------------------------------------------------------------------------
 %       Linear Bottom Friction
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Linear bottom friction (\protect\np{nn\_botfr}\forcode{ = 0..1})}
-\label{subsec:ZDF_bfr_linear}
-
-The linear bottom friction parameterisation (including the special case of a free-slip condition) assumes that
-the bottom friction is proportional to the interior velocity (\ie the velocity of the last model level):
+ \subsection[Linear top/bottom friction (\forcode{ln_lin = .true.})]
+ {Linear top/bottom friction (\protect\np{ln\_lin}\forcode{ = .true.)}}
+ \label{subsec:ZDF_drg_linear}
+
+The linear friction parameterisation (including the special case of a free-slip condition) assumes that
+the friction is proportional to the interior velocity (\ie the velocity of the first/last model level):
 \[
   % \label{eq:zdfbfr_linear}
   {\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3} \; \frac{\partial \textbf{U}_h}{\partial k} = r \; \textbf{U}_h^b
 \]
-where $r$ is a friction coefficient expressed in ms$^{-1}$.
+where $r$ is a friction coefficient expressed in $m s^{-1}$.
 This coefficient is generally estimated by setting a typical decay time $\tau$ in the deep ocean, 
 and setting $r = H / \tau$, where $H$ is the ocean depth.
-Commonly accepted values of $\tau$ are of the order of 100 to 200 days \citep{Weatherly_JMR84}.
+Commonly accepted values of $\tau$ are of the order of 100 to 200 days \citep{weatherly_JMR84}.
 A value $\tau^{-1} = 10^{-7}$~s$^{-1}$ equivalent to 115 days, is usually used in quasi-geostrophic models.
 One may consider the linear friction as an approximation of quadratic friction, $r \approx 2\;C_D\;U_{av}$
-(\citet{Gill1982}, Eq. 9.6.6).
+(\citet{gill_bk82}, Eq. 9.6.6).
 For example, with a drag coefficient $C_D = 0.002$, a typical speed of tidal currents of $U_{av} =0.1$~m\;s$^{-1}$,
 and assuming an ocean depth $H = 4000$~m, the resulting friction coefficient is $r = 4\;10^{-4}$~m\;s$^{-1}$.
 This is the default value used in \NEMO. It corresponds to a decay time scale of 115~days.
-It can be changed by specifying \np{rn\_bfri1} (namelist parameter).
-
-For the linear friction case the coefficients defined in the general expression \autoref{eq:zdfbfr_bdef} are: 
+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}
-  \begin{split}
-    c_b^u &= - r\\
-    c_b^v &= - r\\
-  \end{split}
-\]
-When \np{nn\_botfr}\forcode{ = 1}, the value of $r$ used is \np{rn\_bfri1}.
-Setting \np{nn\_botfr}\forcode{ = 0} is equivalent to setting $r=0$ and
-leads to a free-slip bottom boundary condition.
-These values are assigned in \mdl{zdfbfr}.
-From v3.2 onwards there is support for local enhancement of these values via an externally defined 2D mask array
-(\np{ln\_bfr2d}\forcode{ = .true.}) given in the \ifile{bfr\_coef} input NetCDF file.
+    c_b^T = - r
+\]
+When \np{ln\_lin} \forcode{= .true.}, the value of $r$ used is \np{rn\_Uc0}*\np{rn\_Cd0}.
+Setting \np{ln\_OFF} \forcode{= .true.} (and \forcode{ln_lin = .true.}) is equivalent to setting $r=0$ and leads to a free-slip boundary condition.
+
+These values are assigned in \mdl{zdfdrg}.
+Note that there is support for local enhancement of these values via an externally defined 2D mask array
+(\np{ln\_boost}\forcode{ = .true.}) given in the \ifile{bfr\_coef} input NetCDF file.
 The mask values should vary from 0 to 1.
 Locations with a non-zero mask value will have the friction coefficient increased by
-$mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri1}.
+$mask\_value$ * \np{rn\_boost} * \np{rn\_Cd0}.
 
 % -------------------------------------------------------------------------------------------------------------
 %       Non-Linear Bottom Friction
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Non-linear bottom friction (\protect\np{nn\_botfr}\forcode{ = 2})}
-\label{subsec:ZDF_bfr_nonlinear}
-
-The non-linear bottom friction parameterisation assumes that the bottom friction is quadratic: 
-\[
-  % \label{eq:zdfbfr_nonlinear}
+ \subsection[Non-linear top/bottom friction (\forcode{ln_non_lin = .true.})]
+ {Non-linear top/bottom friction (\protect\np{ln\_non\_lin}\forcode{ = .true.})}
+ \label{subsec:ZDF_drg_nonlinear}
+
+The non-linear bottom friction parameterisation assumes that the top/bottom friction is quadratic: 
+\[
+  % \label{eq:zdfdrg_nonlinear}
   {\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3 }\frac{\partial \textbf {U}_h
   }{\partial k}=C_D \;\sqrt {u_b ^2+v_b ^2+e_b } \;\; \textbf {U}_h^b
 \]
-where $C_D$ is a drag coefficient, and $e_b $ a bottom turbulent kinetic energy due to tides,
+where $C_D$ is a drag coefficient, and $e_b $ a top/bottom turbulent kinetic energy due to tides,
 internal waves breaking and other short time scale currents.
 A typical value of the drag coefficient is $C_D = 10^{-3} $.
-As an example, the CME experiment \citep{Treguier_JGR92} uses $C_D = 10^{-3}$ and
-$e_b = 2.5\;10^{-3}$m$^2$\;s$^{-2}$, while the FRAM experiment \citep{Killworth1992} uses $C_D = 1.4\;10^{-3}$ and
+As an example, the CME experiment \citep{treguier_JGR92} uses $C_D = 10^{-3}$ and
+$e_b = 2.5\;10^{-3}$m$^2$\;s$^{-2}$, while the FRAM experiment \citep{killworth_JPO92} uses $C_D = 1.4\;10^{-3}$ and
 $e_b =2.5\;\;10^{-3}$m$^2$\;s$^{-2}$.
-The CME choices have been set as default values (\np{rn\_bfri2} and \np{rn\_bfeb2} namelist parameters).
-
-As for the linear case, the bottom friction is imposed in the code by adding the trend due to
-the bottom friction to the general momentum trend in \mdl{dynbfr}.
-For the non-linear friction case the terms computed in \mdl{zdfbfr} are:
-\[
-  % \label{eq:zdfbfr_nonlinbfr}
-  \begin{split}
-    c_b^u &= - \; C_D\;\left[ u^2 + \left(\bar{\bar{v}}^{i+1,j}\right)^2 + e_b \right]^{1/2}\\
-    c_b^v &= - \; C_D\;\left[  \left(\bar{\bar{u}}^{i,j+1}\right)^2 + v^2 + e_b \right]^{1/2}\\
-  \end{split}
-\]
-
-The coefficients that control the strength of the non-linear bottom friction are initialised as namelist parameters:
-$C_D$= \np{rn\_bfri2}, and $e_b$ =\np{rn\_bfeb2}.
-Note for applications which treat tides explicitly a low or even zero value of \np{rn\_bfeb2} is recommended.
-From v3.2 onwards a local enhancement of $C_D$ is possible via an externally defined 2D mask array
-(\np{ln\_bfr2d}\forcode{ = .true.}).
-This works in the same way as for the linear bottom friction case with non-zero masked locations increased by
-$mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri2}.
+The CME choices have been set as default values (\np{rn\_Cd0} and \np{rn\_ke0} namelist parameters).
+
+As for the linear case, the friction is imposed in the code by adding the trend due to
+the friction to the general momentum trend in \mdl{dynzdf}.
+For the non-linear friction case the term computed in \mdl{zdfdrg} is:
+\[
+  % \label{eq:zdfdrg_nonlinbfr}
+    c_b^T = - \; C_D\;\left[ \left(\bar{u_b}^{i}\right)^2 + \left(\bar{v_b}^{j}\right)^2 + e_b \right]^{1/2}
+\]
+
+The coefficients that control the strength of the non-linear friction are initialised as namelist parameters:
+$C_D$= \np{rn\_Cd0}, and $e_b$ =\np{rn\_bfeb2}.
+Note that for applications which consider tides explicitly, a low or even zero value of \np{rn\_bfeb2} is recommended. A local enhancement of $C_D$ is again possible via an externally defined 2D mask array
+(\np{ln\_boost}\forcode{ = .true.}).
+This works in the same way as for the linear friction case with non-zero masked locations increased by
+$mask\_value$ * \np{rn\_boost} * \np{rn\_Cd0}.
 
 % -------------------------------------------------------------------------------------------------------------
 %       Bottom Friction Log-layer
 % -------------------------------------------------------------------------------------------------------------
-\subsection[Log-layer btm frict enhncmnt (\protect\np{nn\_botfr}\forcode{ = 2}, \protect\np{ln\_loglayer}\forcode{ = .true.})]
-				{Log-layer bottom friction enhancement (\protect\np{nn\_botfr}\forcode{ = 2}, \protect\np{ln\_loglayer}\forcode{ = .true.})}
-\label{subsec:ZDF_bfr_loglayer}
-
-In the non-linear bottom friction case, the drag coefficient, $C_D$, can be optionally enhanced using
-a "law of the wall" scaling.
-If  \np{ln\_loglayer} = .true., $C_D$ is no longer constant but is related to the thickness of
-the last wet layer in each column by:
-\[
-  C_D = \left ( {\kappa \over {\rm log}\left ( 0.5e_{3t}/rn\_bfrz0 \right ) } \right )^2
-\]
-
-\noindent where $\kappa$ is the von-Karman constant and \np{rn\_bfrz0} is a roughness length provided via
-the namelist.
-
-For stability, the drag coefficient is bounded such that it is kept greater or equal to
-the base \np{rn\_bfri2} value and it is not allowed to exceed the value of an additional namelist parameter:
-\np{rn\_bfri2\_max}, \ie
-\[
-  rn\_bfri2 \leq C_D \leq rn\_bfri2\_max
-\]
-
-\noindent Note also that a log-layer enhancement can also be applied to the top boundary friction if
-under ice-shelf cavities are in use (\np{ln\_isfcav}\forcode{ = .true.}).
-In this case, the relevant namelist parameters are \np{rn\_tfrz0}, \np{rn\_tfri2} and \np{rn\_tfri2\_max}.
-
-% -------------------------------------------------------------------------------------------------------------
-%       Bottom Friction stability
-% -------------------------------------------------------------------------------------------------------------
-\subsection{Bottom friction stability considerations}
-\label{subsec:ZDF_bfr_stability}
-
-Some care needs to exercised over the choice of parameters to ensure that the implementation of
-bottom friction does not induce numerical instability.
-For the purposes of stability analysis, an approximation to \autoref{eq:zdfbfr_flux2} is:
+ \subsection[Log-layer top/bottom friction (\forcode{ln_loglayer = .true.})]
+ {Log-layer top/bottom friction (\protect\np{ln\_loglayer}\forcode{ = .true.})}
+ \label{subsec:ZDF_drg_loglayer}
+
+In the non-linear friction case, the drag coefficient, $C_D$, can be optionally enhanced using
+a "law of the wall" scaling. This assumes that the model vertical resolution can capture the logarithmic layer which typically occur for layers thinner than 1 m or so.
+If  \np{ln\_loglayer} \forcode{= .true.}, $C_D$ is no longer constant but is related to the distance to the wall (or equivalently to the half of the top/bottom layer thickness):
+\[
+  C_D = \left ( {\kappa \over {\mathrm log}\left ( 0.5 \; e_{3b} / rn\_{z0} \right ) } \right )^2
+\]
+
+\noindent where $\kappa$ is the von-Karman constant and \np{rn\_z0} is a roughness length provided via the namelist.
+
+The drag coefficient is bounded such that it is kept greater or equal to
+the base \np{rn\_Cd0} value which occurs where layer thicknesses become large and presumably logarithmic layers are not resolved at all. For stability reason, it is also not allowed to exceed the value of an additional namelist parameter:
+\np{rn\_Cdmax}, \ie
+\[
+  rn\_Cd0 \leq C_D \leq rn\_Cdmax
+\]
+
+\noindent The log-layer enhancement can also be applied to the top boundary friction if
+under ice-shelf cavities are activated (\np{ln\_isfcav}\forcode{ = .true.}).
+%In this case, the relevant namelist parameters are \np{rn\_tfrz0}, \np{rn\_tfri2} and \np{rn\_tfri2\_max}.
+
+% -------------------------------------------------------------------------------------------------------------
+%       Explicit bottom Friction
+% -------------------------------------------------------------------------------------------------------------
+ \subsection{Explicit top/bottom friction (\forcode{ln_drgimp = .false.})}
+ \label{subsec:ZDF_drg_stability}
+
+Setting \np{ln\_drgimp} \forcode{= .false.} means that bottom friction is treated explicitly in time, which has the advantage of simplifying the interaction with the split-explicit free surface (see \autoref{subsec:ZDF_drg_ts}). The latter does indeed require the knowledge of bottom stresses in the course of the barotropic sub-iteration, which becomes less straightforward in the implicit case. In the explicit case, top/bottom stresses can be computed using \textit{before} velocities and inserted in the overall momentum tendency budget. This reads:
+
+At the top (below an ice shelf cavity):
+\[
+  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{t}
+  = c_{t}^{\textbf{U}}\textbf{u}^{n-1}_{t}
+\]
+
+At the bottom (above the sea floor):
+\[
+  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{b}
+  = c_{b}^{\textbf{U}}\textbf{u}^{n-1}_{b}
+\]
+
+Since this is conditionally stable, some care needs to exercised over the choice of parameters to ensure that the implementation of explicit top/bottom friction does not induce numerical instability.
+For the purposes of stability analysis, an approximation to \autoref{eq:zdfdrg_flux2} is:
 \begin{equation}
-  \label{eq:Eqn_bfrstab}
+  \label{eq:Eqn_drgstab}
   \begin{split}
     \Delta u &= -\frac{{{\cal F}_h}^u}{e_{3u}}\;2 \rdt    \\
@@ -1074,10 +1086,10 @@
   \end{split}
 \end{equation}
-\noindent where linear bottom friction and a leapfrog timestep have been assumed.
-To ensure that the bottom friction cannot reverse the direction of flow it is necessary to have:
+\noindent where linear friction and a leapfrog timestep have been assumed.
+To ensure that the friction cannot reverse the direction of flow it is necessary to have:
 \[
   |\Delta u| < \;|u| 
 \]
-\noindent which, using \autoref{eq:Eqn_bfrstab}, gives:
+\noindent which, using \autoref{eq:Eqn_drgstab}, gives:
 \[
   r\frac{2\rdt}{e_{3u}} < 1 \qquad  \Rightarrow \qquad r < \frac{e_{3u}}{2\rdt}\\
@@ -1093,15 +1105,15 @@
 For most applications, with physically sensible parameters these restrictions should not be of concern.
 But caution may be necessary if attempts are made to locally enhance the bottom friction parameters. 
-To ensure stability limits are imposed on the bottom friction coefficients both
+To ensure stability limits are imposed on the top/bottom friction coefficients both
 during initialisation and at each time step.
-Checks at initialisation are made in \mdl{zdfbfr} (assuming a 1 m.s$^{-1}$ velocity in the non-linear case).
+Checks at initialisation are made in \mdl{zdfdrg} (assuming a 1 m.s$^{-1}$ velocity in the non-linear case).
 The number of breaches of the stability criterion are reported as well as
 the minimum and maximum values that have been set.
-The criterion is also checked at each time step, using the actual velocity, in \mdl{dynbfr}.
-Values of the bottom friction coefficient are reduced as necessary to ensure stability;
+The criterion is also checked at each time step, using the actual velocity, in \mdl{dynzdf}.
+Values of the friction coefficient are reduced as necessary to ensure stability;
 these changes are not reported.
 
-Limits on the bottom friction coefficient are not imposed if the user has elected to
-handle the bottom friction implicitly (see \autoref{subsec:ZDF_bfr_imp}).
+Limits on the top/bottom friction coefficient are not imposed if the user has elected to
+handle the friction implicitly (see \autoref{subsec:ZDF_drg_imp}).
 The number of potential breaches of the explicit stability criterion are still reported for information purposes.
 
@@ -1109,247 +1121,64 @@
 %       Implicit Bottom Friction
 % -------------------------------------------------------------------------------------------------------------
-\subsection{Implicit bottom friction (\protect\np{ln\_bfrimp}\forcode{ = .true.})}
-\label{subsec:ZDF_bfr_imp}
+ \subsection[Implicit top/bottom friction (\forcode{ln_drgimp = .true.})]
+ {Implicit top/bottom friction (\protect\np{ln\_drgimp}\forcode{ = .true.})}
+ \label{subsec:ZDF_drg_imp}
 
 An optional implicit form of bottom friction has been implemented to improve model stability.
-We recommend this option for shelf sea and coastal ocean applications, especially for split-explicit time splitting.
-This option can be invoked by setting \np{ln\_bfrimp} to \forcode{.true.} in the \textit{nambfr} namelist.
-This option requires \np{ln\_zdfexp} to be \forcode{.false.} in the \textit{namzdf} namelist. 
-
-This implementation is realised in \mdl{dynzdf\_imp} and \mdl{dynspg\_ts}. In \mdl{dynzdf\_imp},
-the bottom boundary condition is implemented implicitly.
-
-\[
-  % \label{eq:dynzdf_bfr}
-  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{mbk}
-  = \binom{c_{b}^{u}u^{n+1}_{mbk}}{c_{b}^{v}v^{n+1}_{mbk}}
-\]
-
-where $mbk$ is the layer number of the bottom wet layer.
-Superscript $n+1$ means the velocity used in the friction formula is to be calculated, so, it is implicit.
-
-If split-explicit time splitting is used, care must be taken to avoid the double counting of the bottom friction in
-the 2-D barotropic momentum equations.
-As NEMO only updates the barotropic pressure gradient and Coriolis' forcing terms in the 2-D barotropic calculation,
-we need to remove the bottom friction induced by these two terms which has been included in the 3-D momentum trend 
-and update it with the latest value.
-On the other hand, the bottom friction contributed by the other terms
-(\eg the advection term, viscosity term) has been included in the 3-D momentum equations and
-should not be added in the 2-D barotropic mode.
-
-The implementation of the implicit bottom friction in \mdl{dynspg\_ts} is done in two steps as the following:
-
-\[
-  % \label{eq:dynspg_ts_bfr1}
-  \frac{\textbf{U}_{med}-\textbf{U}^{m-1}}{2\Delta t}=-g\nabla\eta-f\textbf{k}\times\textbf{U}^{m}+c_{b}
-  \left(\textbf{U}_{med}-\textbf{U}^{m-1}\right)
-\]
-\[
-  \frac{\textbf{U}^{m+1}-\textbf{U}_{med}}{2\Delta t}=\textbf{T}+
-  \left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{U}^{'}\right)-
-  2\Delta t_{bc}c_{b}\left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{u}_{b}\right)
-\]
-
-where $\textbf{T}$ is the vertical integrated 3-D momentum trend.
-We assume the leap-frog time-stepping is used here.
-$\Delta t$ is the barotropic mode time step and $\Delta t_{bc}$ is the baroclinic mode time step.
-$c_{b}$ is the friction coefficient.
-$\eta$ is the sea surface level calculated in the barotropic loops while $\eta^{'}$ is the sea surface level used in
-the 3-D baroclinic mode.
-$\textbf{u}_{b}$ is the bottom layer horizontal velocity.
-
-% -------------------------------------------------------------------------------------------------------------
-%       Bottom Friction with split-explicit time splitting
-% -------------------------------------------------------------------------------------------------------------
-\subsection[Bottom friction w/ split-explicit time splitting (\protect\np{ln\_bfrimp})]
-				{Bottom friction with split-explicit time splitting (\protect\np{ln\_bfrimp})}
-\label{subsec:ZDF_bfr_ts}
-
-When calculating the momentum trend due to bottom friction in \mdl{dynbfr},
-the bottom velocity at the before time step is used.
-This velocity includes both the baroclinic and barotropic components which is appropriate when
-using either the explicit or filtered surface pressure gradient algorithms
-(\key{dynspg\_exp} or \key{dynspg\_flt}).
-Extra attention is required, however, when using split-explicit time stepping (\key{dynspg\_ts}).
-In this case the free surface equation is solved with a small time step \np{rn\_rdt}/\np{nn\_baro},
-while the three dimensional prognostic variables are solved with the longer time step of \np{rn\_rdt} seconds.
-The trend in the barotropic momentum due to bottom friction appropriate to this method is that given by
-the selected parameterisation (\ie linear or non-linear bottom friction) computed with
-the evolving velocities at each barotropic timestep. 
-
-In the case of non-linear bottom friction, we have elected to partially linearise the problem by
-keeping the coefficients fixed throughout the barotropic time-stepping to those computed in
-\mdl{zdfbfr} using the now timestep.
-This decision allows an efficient use of the $c_b^{\vect{U}}$ coefficients to:
-
+We recommend this option for shelf sea and coastal ocean applications. %, especially for split-explicit time splitting.
+This option can be invoked by setting \np{ln\_drgimp} to \forcode{.true.} in the \textit{namdrg} namelist.
+%This option requires \np{ln\_zdfexp} to be \forcode{.false.} in the \textit{namzdf} 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}
+  \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}
+  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{b}
+  = c_{b}^{\textbf{U}}\textbf{u}^{n+1}_{b}
+\]
+
+where $t$ and $b$ refers to top and bottom layers respectively. 
+Superscript $n+1$ means the velocity used in the friction formula is to be calculated, so it is implicit.
+
+% -------------------------------------------------------------------------------------------------------------
+%       Bottom Friction with split-explicit free surface
+% -------------------------------------------------------------------------------------------------------------
+ \subsection[Bottom friction with split-explicit free surface]
+ {Bottom friction with split-explicit free surface}
+ \label{subsec:ZDF_drg_ts}
+
+With split-explicit free surface, the sub-stepping of barotropic equations needs the knowledge of top/bottom stresses. An obvious way to satisfy this is to take them as constant over the course of the barotropic integration and equal to the value used to update the baroclinic momentum trend. Provided \np{ln\_drgimp}\forcode{= .false.} and a centred or \textit{leap-frog} like integration of barotropic equations is used (\ie \forcode{ln_bt_fw = .false.}, cf \autoref{subsec:DYN_spg_ts}), this does ensure that barotropic and baroclinic dynamics feel the same stresses during one leapfrog time step. However, if \np{ln\_drgimp}\forcode{= .true.},  stresses depend on the \textit{after} value of the velocities which themselves depend on the barotropic iteration result. This cyclic dependency makes difficult obtaining consistent stresses in 2d and 3d dynamics. Part of this mismatch is then removed when setting the final barotropic component of 3d velocities to the time splitting estimate. This last step can be seen as a necessary evil but should be minimized since it interferes with the adjustment to the boundary conditions. 
+
+The strategy to handle top/bottom stresses with split-explicit free surface in \NEMO is as follows:
 \begin{enumerate}
-\item On entry to \rou{dyn\_spg\_ts}, remove the contribution of the before barotropic velocity to
-  the bottom friction component of the vertically integrated momentum trend.
-  Note the same stability check that is carried out on the bottom friction coefficient in \mdl{dynbfr} has to
-  be applied here to ensure that the trend removed matches that which was added in \mdl{dynbfr}.
-\item At each barotropic step, compute the contribution of the current barotropic velocity to
-  the trend due to bottom friction.
-  Add this contribution to the vertically integrated momentum trend.
-  This contribution is handled implicitly which eliminates the need to impose a stability criteria on
-  the values of the bottom friction coefficient within the barotropic loop. 
-\end{enumerate}
-
-Note that the use of an implicit formulation within the barotropic loop for the bottom friction trend means that
-any limiting of the bottom friction coefficient in \mdl{dynbfr} does not adversely affect the solution when
-using split-explicit time splitting.
-This is because the major contribution to bottom friction is likely to come from the barotropic component which
-uses the unrestricted value of the coefficient.
-However, if the limiting is thought to be having a major effect
-(a more likely prospect in coastal and shelf seas applications) then
-the fully implicit form of the bottom friction should be used (see \autoref{subsec:ZDF_bfr_imp})
-which can be selected by setting \np{ln\_bfrimp} $=$ \forcode{.true.}.
-
-Otherwise, the implicit formulation takes the form:
-\[
-  % \label{eq:zdfbfr_implicitts}
-  \bar{U}^{t+ \rdt} = \; \left [ \bar{U}^{t-\rdt}\; + 2 \rdt\;RHS \right ] / \left [ 1 - 2 \rdt \;c_b^{u} / H_e \right ]
-\]
-where $\bar U$ is the barotropic velocity, $H_e$ is the full depth (including sea surface height), 
-$c_b^u$ is the bottom friction coefficient as calculated in \rou{zdf\_bfr} and
-$RHS$ represents all the components to the vertically integrated momentum trend except for
-that due to bottom friction.
-
-% ================================================================
-% Tidal Mixing
-% ================================================================
-\section{Tidal mixing (\protect\key{zdftmx})}
-\label{sec:ZDF_tmx}
-
-%--------------------------------------------namzdf_tmx--------------------------------------------------
+\item To extend the stability of the barotropic sub-stepping, bottom stresses are refreshed at each sub-iteration. The baroclinic part of the flow entering the stresses is frozen at the initial time of the barotropic iteration. In case of non-linear friction, the drag coefficient is also constant.
+\item In case of an implicit drag, specific computations are performed in \mdl{dynzdf} which renders the overall scheme mixed explicit/implicit: the barotropic components of 3d velocities are removed before seeking for the implicit vertical diffusion result. Top/bottom stresses due to the barotropic components are explicitly accounted for thanks to the updated values of barotropic velocities. Then the implicit solution of 3d velocities is obtained. Lastly, the residual barotropic component is replaced by the time split estimate.
+\end{enumerate} 
+
+Note that other strategies are possible, like considering vertical diffusion step in advance, \ie prior barotropic integration.  
+
+
+% ================================================================
+% Internal wave-driven mixing
+% ================================================================
+\section[Internal wave-driven mixing (\forcode{ln_zdfiwm = .true.})]
+{Internal wave-driven mixing (\protect\np{ln\_zdfiwm}\forcode{ = .true.})}
+\label{subsec:ZDF_tmx_new}
+
+%--------------------------------------------namzdf_iwm------------------------------------------
 %
-%\nlst{namzdf_tmx}
+\nlst{namzdf_iwm}
 %--------------------------------------------------------------------------------------------------------------
 
-
-% -------------------------------------------------------------------------------------------------------------
-%        Bottom intensified tidal mixing 
-% -------------------------------------------------------------------------------------------------------------
-\subsection{Bottom intensified tidal mixing}
-\label{subsec:ZDF_tmx_bottom}
-
-Options are defined through the  \ngn{namzdf\_tmx} namelist variables.
-The parameterization of tidal mixing follows the general formulation for the vertical eddy diffusivity proposed by
-\citet{St_Laurent_al_GRL02} and first introduced in an OGCM by \citep{Simmons_al_OM04}. 
-In this formulation an additional vertical diffusivity resulting from internal tide breaking,
-$A^{vT}_{tides}$ is expressed as a function of $E(x,y)$,
-the energy transfer from barotropic tides to baroclinic tides:
-\begin{equation}
-  \label{eq:Ktides}
-  A^{vT}_{tides} =  q \,\Gamma \,\frac{ E(x,y) \, F(z) }{ \rho \, N^2 }
-\end{equation}
-where $\Gamma$ is the mixing efficiency, $N$ the Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}),
-$\rho$ the density, $q$ the tidal dissipation efficiency, and $F(z)$ the vertical structure function. 
-
-The mixing efficiency of turbulence is set by $\Gamma$ (\np{rn\_me} namelist parameter) and
-is usually taken to be the canonical value of $\Gamma = 0.2$ (Osborn 1980). 
-The tidal dissipation efficiency is given by the parameter $q$ (\np{rn\_tfe} namelist parameter)
-represents the part of the internal wave energy flux $E(x, y)$ that is dissipated locally,
-with the remaining $1-q$ radiating away as low mode internal waves and
-contributing to the background internal wave field.
-A value of $q=1/3$ is typically used \citet{St_Laurent_al_GRL02}.
-The vertical structure function $F(z)$ models the distribution of the turbulent mixing in the vertical.
-It is implemented as a simple exponential decaying upward away from the bottom,
-with a vertical scale of $h_o$ (\np{rn\_htmx} namelist parameter,
-with a typical value of $500\,m$) \citep{St_Laurent_Nash_DSR04}, 
-\[
-  % \label{eq:Fz}
-  F(i,j,k) = \frac{ e^{ -\frac{H+z}{h_o} } }{ h_o \left( 1- e^{ -\frac{H}{h_o} } \right) }
-\]
-and is normalized so that vertical integral over the water column is unity. 
-
-The associated vertical viscosity is calculated from the vertical diffusivity assuming a Prandtl number of 1,
-\ie $A^{vm}_{tides}=A^{vT}_{tides}$.
-In the limit of $N \rightarrow 0$ (or becoming negative), the vertical diffusivity is capped at $300\,cm^2/s$ and
-impose a lower limit on $N^2$ of \np{rn\_n2min} usually set to $10^{-8} s^{-2}$.
-These bounds are usually rarely encountered.
-
-The internal wave energy map, $E(x, y)$ in \autoref{eq:Ktides}, is derived from a barotropic model of
-the tides utilizing a parameterization of the conversion of barotropic tidal energy into internal waves.
-The essential goal of the parameterization is to represent the momentum exchange between the barotropic tides and
-the unrepresented internal waves induced by the tidal flow over rough topography in a stratified ocean.
-In the current version of \NEMO, the map is built from the output of
-the barotropic global ocean tide model MOG2D-G \citep{Carrere_Lyard_GRL03}.
-This model provides the dissipation associated with internal wave energy for the M2 and K1 tides component
-(\autoref{fig:ZDF_M2_K1_tmx}).
-The S2 dissipation is simply approximated as being $1/4$ of the M2 one.
-The internal wave energy is thus : $E(x, y) = 1.25 E_{M2} + E_{K1}$.
-Its global mean value is $1.1$ TW,
-in agreement with independent estimates \citep{Egbert_Ray_Nat00, Egbert_Ray_JGR01}. 
-
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-\begin{figure}[!t]
-  \begin{center}
-    \includegraphics[width=0.90\textwidth]{Fig_ZDF_M2_K1_tmx}
-    \caption{
-      \protect\label{fig:ZDF_M2_K1_tmx}
-      (a) M2 and (b) K1 internal wave drag energy from \citet{Carrere_Lyard_GRL03} ($W/m^2$).
-    }
-  \end{center}
-\end{figure}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
- 
-% -------------------------------------------------------------------------------------------------------------
-%        Indonesian area specific treatment 
-% -------------------------------------------------------------------------------------------------------------
-\subsection{Indonesian area specific treatment (\protect\np{ln\_zdftmx\_itf})}
-\label{subsec:ZDF_tmx_itf}
-
-When the Indonesian Through Flow (ITF) area is included in the model domain,
-a specific treatment of tidal induced mixing in this area can be used.
-It is activated through the namelist logical \np{ln\_tmx\_itf}, and the user must provide an input NetCDF file,
-\ifile{mask\_itf}, which contains a mask array defining the ITF area where the specific treatment is applied.
-
-When \np{ln\_tmx\_itf}\forcode{ = .true.}, the two key parameters $q$ and $F(z)$ are adjusted following
-the parameterisation developed by \citet{Koch-Larrouy_al_GRL07}:
-
-First, the Indonesian archipelago is a complex geographic region with a series of
-large, deep, semi-enclosed basins connected via numerous narrow straits.
-Once generated, internal tides remain confined within this semi-enclosed area and hardly radiate away.
-Therefore all the internal tides energy is consumed within this area.
-So it is assumed that $q = 1$, \ie all the energy generated is available for mixing.
-Note that for test purposed, the ITF tidal dissipation efficiency is a namelist parameter (\np{rn\_tfe\_itf}).
-A value of $1$ or close to is this recommended for this parameter.
-
-Second, the vertical structure function, $F(z)$, is no more associated with a bottom intensification of the mixing,
-but with a maximum of energy available within the thermocline.
-\citet{Koch-Larrouy_al_GRL07} have suggested that the vertical distribution of
-the energy dissipation proportional to $N^2$ below the core of the thermocline and to $N$ above. 
-The resulting $F(z)$ is:
-\[
-  % \label{eq:Fz_itf}
-  F(i,j,k) \sim     \left\{
-    \begin{aligned}
-      \frac{q\,\Gamma E(i,j) } {\rho N \, \int N     dz}    \qquad \text{when $\partial_z N < 0$} \\
-      \frac{q\,\Gamma E(i,j) } {\rho     \, \int N^2 dz}    \qquad \text{when $\partial_z N > 0$}
-    \end{aligned}
-  \right.
-\]
-
-Averaged over the ITF area, the resulting tidal mixing coefficient is $1.5\,cm^2/s$, 
-which agrees with the independent estimates inferred from observations.
-Introduced in a regional OGCM, the parameterization improves the water mass characteristics in
-the different Indonesian seas, suggesting that the horizontal and vertical distributions of
-the mixing are adequately prescribed \citep{Koch-Larrouy_al_GRL07, Koch-Larrouy_al_OD08a, Koch-Larrouy_al_OD08b}.
-Note also that such a parameterisation has a significant impact on the behaviour of
-global coupled GCMs \citep{Koch-Larrouy_al_CD10}.
-
-% ================================================================
-% Internal wave-driven mixing
-% ================================================================
-\section{Internal wave-driven mixing (\protect\key{zdftmx\_new})}
-\label{sec:ZDF_tmx_new}
-
-%--------------------------------------------namzdf_tmx_new------------------------------------------
-%
-%\nlst{namzdf_tmx_new}
-%--------------------------------------------------------------------------------------------------------------
-
 The parameterization of mixing induced by breaking internal waves is a generalization of
-the approach originally proposed by \citet{St_Laurent_al_GRL02}.
+the approach originally proposed by \citet{st-laurent.simmons.ea_GRL02}.
 A three-dimensional field of internal wave energy dissipation $\epsilon(x,y,z)$ is first constructed,
 and the resulting diffusivity is obtained as 
@@ -1360,25 +1189,25 @@
 where $R_f$ is the mixing efficiency and $\epsilon$ is a specified three dimensional distribution of
 the energy available for mixing.
-If the \np{ln\_mevar} namelist parameter is set to false, the mixing efficiency is taken as constant and
-equal to 1/6 \citep{Osborn_JPO80}.
+If the \np{ln\_mevar} namelist parameter is set to \forcode{.false.}, the mixing efficiency is taken as constant and
+equal to 1/6 \citep{osborn_JPO80}.
 In the opposite (recommended) case, $R_f$ is instead a function of
 the turbulence intensity parameter $Re_b = \frac{ \epsilon}{\nu \, N^2}$,
-with $\nu$ the molecular viscosity of seawater, following the model of \cite{Bouffard_Boegman_DAO2013} and
-the implementation of \cite{de_lavergne_JPO2016_efficiency}.
+with $\nu$ the molecular viscosity of seawater, following the model of \cite{bouffard.boegman_DAO13} and
+the implementation of \cite{de-lavergne.madec.ea_JPO16}.
 Note that $A^{vT}_{wave}$ is bounded by $10^{-2}\,m^2/s$, a limit that is often reached when
 the mixing efficiency is constant.
 
 In addition to the mixing efficiency, the ratio of salt to heat diffusivities can chosen to vary 
-as a function of $Re_b$ by setting the \np{ln\_tsdiff} parameter to true, a recommended choice. 
-This parameterization of differential mixing, due to \cite{Jackson_Rehmann_JPO2014},
-is implemented as in \cite{de_lavergne_JPO2016_efficiency}.
+as a function of $Re_b$ by setting the \np{ln\_tsdiff} parameter to \forcode{.true.}, a recommended choice. 
+This parameterization of differential mixing, due to \cite{jackson.rehmann_JPO14},
+is implemented as in \cite{de-lavergne.madec.ea_JPO16}.
 
 The three-dimensional distribution of the energy available for mixing, $\epsilon(i,j,k)$,
 is constructed from three static maps of column-integrated internal wave energy dissipation,
-$E_{cri}(i,j)$, $E_{pyc}(i,j)$, and $E_{bot}(i,j)$, combined to three corresponding vertical structures
-(de Lavergne et al., in prep):
+$E_{cri}(i,j)$, $E_{pyc}(i,j)$, and $E_{bot}(i,j)$, combined to three corresponding vertical structures:
+
 \begin{align*}
   F_{cri}(i,j,k) &\propto e^{-h_{ab} / h_{cri} }\\
-  F_{pyc}(i,j,k) &\propto N^{n\_p}\\
+  F_{pyc}(i,j,k) &\propto N^{n_p}\\
   F_{bot}(i,j,k) &\propto N^2 \, e^{- h_{wkb} / h_{bot} }
 \end{align*} 
@@ -1388,12 +1217,282 @@
   h_{wkb} = H \, \frac{ \int_{-H}^{z} N \, dz' } { \int_{-H}^{\eta} N \, dz'  } \; ,
 \]
-The $n_p$ parameter (given by \np{nn\_zpyc} in \ngn{namzdf\_tmx\_new} namelist)
+The $n_p$ parameter (given by \np{nn\_zpyc} in \ngn{namzdf\_iwm} namelist)
 controls the stratification-dependence of the pycnocline-intensified dissipation.
-It can take values of 1 (recommended) or 2.
+It can take values of $1$ (recommended) or $2$.
 Finally, the vertical structures $F_{cri}$ and $F_{bot}$ require the specification of
 the decay scales $h_{cri}(i,j)$ and $h_{bot}(i,j)$, which are defined by two additional input maps.
 $h_{cri}$ is related to the large-scale topography of the ocean (etopo2) and
 $h_{bot}$ is a function of the energy flux $E_{bot}$, the characteristic horizontal scale of
-the abyssal hill topography \citep{Goff_JGR2010} and the latitude.
+the abyssal hill topography \citep{goff_JGR10} and the latitude.
+%
+% Jc: input files names ?
+
+% ================================================================
+% surface wave-induced mixing 
+% ================================================================
+\section[Surface wave-induced mixing (\forcode{ln_zdfswm = .true.})]
+{Surface wave-induced mixing (\protect\np{ln\_zdfswm}\forcode{ = .true.})}
+\label{subsec:ZDF_swm}
+
+Surface waves produce an enhanced mixing through wave-turbulence interaction.
+In addition to breaking waves induced turbulence (\autoref{subsec:ZDF_tke}),
+the influence of non-breaking waves can be accounted introducing 
+wave-induced viscosity and diffusivity as a function of the wave number spectrum.
+Following \citet{qiao.yuan.ea_OD10}, a formulation of wave-induced mixing coefficient
+is provided  as a function of wave amplitude, Stokes Drift and wave-number:
+
+\begin{equation}
+  \label{eq:Bv}
+  B_{v} = \alpha {A} {U}_{st} {exp(3kz)}
+\end{equation}
+
+Where $B_{v}$ is the wave-induced mixing coefficient, $A$ is the wave amplitude, 
+${U}_{st}$ is the Stokes Drift velocity, $k$ is the wave number and $\alpha$ 
+is a constant which should be determined by observations or 
+numerical experiments and is set to be 1.
+
+The coefficient $B_{v}$ is then directly added to the vertical viscosity 
+and diffusivity coefficients.
+
+In order to account for this contribution set: \forcode{ln_zdfswm = .true.},
+then wave interaction has to be activated through \forcode{ln_wave = .true.},
+the Stokes Drift can be evaluated by setting \forcode{ln_sdw = .true.} 
+(see \autoref{subsec:SBC_wave_sdw})
+and the needed wave fields can be provided either in forcing or coupled mode
+(for more information on wave parameters and settings see \autoref{sec:SBC_wave})
+
+% ================================================================
+% Adaptive-implicit vertical advection
+% ================================================================
+\section[Adaptive-implicit vertical advection (\forcode{ln_zad_Aimp = .true.})]
+{Adaptive-implicit vertical advection(\protect\np{ln\_zad\_Aimp}\forcode{ = .true.})}
+\label{subsec:ZDF_aimp}
+
+The adaptive-implicit vertical advection option in NEMO is based on the work of
+\citep{shchepetkin_OM15}.  In common with most ocean models, the timestep used with NEMO
+needs to satisfy multiple criteria associated with different physical processes in order
+to maintain numerical stability. \citep{shchepetkin_OM15} pointed out that the vertical
+CFL criterion is commonly the most limiting. \citep{lemarie.debreu.ea_OM15} examined the
+constraints for a range of time and space discretizations and provide the CFL stability
+criteria for a range of advection schemes. The values for the Leap-Frog with Robert
+asselin filter time-stepping (as used in NEMO) are reproduced in
+\autoref{tab:zad_Aimp_CFLcrit}. Treating the vertical advection implicitly can avoid these
+restrictions but at the cost of large dispersive errors and, possibly, large numerical
+viscosity. The adaptive-implicit vertical advection option provides a targetted use of the
+implicit scheme only when and where potential breaches of the vertical CFL condition
+occur. In many practical applications these events may occur remote from the main area of
+interest or due to short-lived conditions such that the extra numerical diffusion or
+viscosity does not greatly affect the overall solution. With such applications, setting:
+\forcode{ln_zad_Aimp = .true.} should allow much longer model timesteps to be used whilst
+retaining the accuracy of the high order explicit schemes over most of the domain.
+
+\begin{table}[htbp]
+  \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}
+\end{table}
+
+In particular, the advection scheme remains explicit everywhere except where and when
+local vertical velocities exceed a threshold set just below the explicit stability limit.
+Once the threshold is reached a tapered transition towards an implicit scheme is used by
+partitioning the vertical velocity into a part that can be treated explicitly and any
+excess that must be treated implicitly. The partitioning is achieved via a Courant-number
+dependent weighting algorithm as described in \citep{shchepetkin_OM15}.
+
+The local cell Courant number ($Cu$) used for this partitioning is:
+
+\begin{equation}
+  \label{eq:Eqn_zad_Aimp_Courant}
+  \begin{split}
+    Cu &= {2 \rdt \over e^n_{3t_{ijk}}} \bigg (\big [ \texttt{Max}(w^n_{ijk},0.0) - \texttt{Min}(w^n_{ijk+1},0.0) \big ]    \\
+       &\phantom{=} +\big [ \texttt{Max}(e_{{2_u}ij}e^n_{{3_{u}}ijk}u^n_{ijk},0.0) - \texttt{Min}(e_{{2_u}i-1j}e^n_{{3_{u}}i-1jk}u^n_{i-1jk},0.0) \big ]
+                     \big / e_{{1_t}ij}e_{{2_t}ij}            \\
+       &\phantom{=} +\big [ \texttt{Max}(e_{{1_v}ij}e^n_{{3_{v}}ijk}v^n_{ijk},0.0) - \texttt{Min}(e_{{1_v}ij-1}e^n_{{3_{v}}ij-1k}v^n_{ij-1k},0.0) \big ]
+                     \big / e_{{1_t}ij}e_{{2_t}ij} \bigg )    \\
+  \end{split}
+\end{equation}
+
+\noindent and the tapering algorithm follows \citep{shchepetkin_OM15} as:
+
+\begin{align}
+  \label{eq: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 &=
+     \begin{cases}
+        0.0                                                        &\text{if $Cu \leq Cu_{min}$} \\
+        (Cu - Cu_{min})^2 / (Fcu +  (Cu - Cu_{min})^2)             &\text{else if $Cu < Cu_{cut}$} \\
+        (Cu - Cu_{max}) / Cu                                       &\text{else}
+     \end{cases}
+\end{align}
+
+\begin{figure}[!t]
+  \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}
+\end{figure}
+
+\noindent The partitioning coefficient is used to determine the part of the vertical
+velocity that must be handled implicitly ($w_i$) and to subtract this from the total
+vertical velocity ($w_n$) to leave that which can continue to be handled explicitly:
+
+\begin{align}
+  \label{eq: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}}           
+\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:
+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
+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.
+
+The $w_i$ component is added to the implicit solvers for the vertical mixing in
+\mdl{dynzdf} and \mdl{trazdf} in a similar way to \citep{shchepetkin_OM15}.  This is
+sufficient for the flux-limited advection scheme (\forcode{ln_traadv_mus}) but further
+intervention is required when using the flux-corrected scheme (\forcode{ln_traadv_fct}).
+For these schemes the implicit upstream fluxes must be added to both the monotonic guess
+and to the higher order solution when calculating the antidiffusive fluxes. The implicit
+vertical fluxes are then removed since they are added by the implicit solver later on.
+
+The adaptive-implicit vertical advection option is new to NEMO at v4.0 and has yet to be 
+used in a wide range of simulations. The following test simulation, however, does illustrate
+the potential benefits and will hopefully encourage further testing and feedback from users:
+
+\begin{figure}[!t]
+  \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}
+\end{figure}
+
+\subsection{Adaptive-implicit vertical advection in the OVERFLOW test-case}
+The \href{https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/guide/html/test\_cases.html\#overflow}{OVERFLOW test case}
+provides a simple illustration of the adaptive-implicit advection in action. The example here differs from the basic test case
+by only a few extra physics choices namely:
+
+\begin{verbatim}
+     ln_dynldf_OFF = .false.
+     ln_dynldf_lap = .true.
+     ln_dynldf_hor = .true.
+     ln_zdfnpc     = .true.
+     ln_traadv_fct = .true.
+        nn_fct_h   =  2
+        nn_fct_v   =  2
+\end{verbatim}
+
+\noindent which were chosen to provide a slightly more stable and less noisy solution. The
+result when using the default value of \forcode{nn_rdt = 10.} without adaptive-implicit
+vertical velocity is illustrated in \autoref{fig:zad_Aimp_overflow_frames}. The mass of
+cold water, initially sitting on the shelf, moves down the slope and forms a
+bottom-trapped, dense plume. Even with these extra physics choices the model is close to
+stability limits and attempts with \forcode{nn_rdt = 30.} will fail after about 5.5 hours
+with excessively high horizontal velocities. This time-scale corresponds with the time the
+plume reaches the steepest part of the topography and, although detected as a horizontal
+CFL breach, the instability originates from a breach of the vertical CFL limit. This is a good
+candidate, therefore, for use of the adaptive-implicit vertical advection scheme.
+
+The results with \forcode{ln_zad_Aimp=.true.} and a variety of model timesteps
+are shown in \autoref{fig:zad_Aimp_overflow_all_rdt} (together with the equivalent
+frames from the base run).  In this simple example the use of the adaptive-implicit
+vertcal advection scheme has enabled a 12x increase in the model timestep without
+significantly altering the solution (although at this extreme the plume is more diffuse
+and has not travelled so far).  Notably, the solution with and without the scheme is
+slightly different even with \forcode{nn_rdt = 10.}; suggesting that the base run was
+close enough to instability to trigger the scheme despite completing successfully.
+To assist in diagnosing how active the scheme is, in both location and time, the 3D
+implicit and explicit components of the vertical velocity are available via XIOS as
+\texttt{wimp} and \texttt{wexp} respectively.  Likewise, the partitioning coefficient
+($C\kern-0.14em f$) is also available as \texttt{wi\_cff}. For a quick oversight of
+the schemes activity the global maximum values of the absolute implicit component
+of the vertical velocity and the partitioning coefficient are written to the netCDF
+version of the run statistics file (\texttt{run.stat.nc}) if this is active (see
+\autoref{sec:MISC_opt} for activation details).
+
+\autoref{fig:zad_Aimp_maxCf} shows examples of the maximum partitioning coefficient for
+the various overflow tests.  Note that the adaptive-implicit vertical advection scheme is
+active even in the base run with \forcode{nn_rdt=10.0s} adding to the evidence that the
+test case is close to stability limits even with this value. At the larger timesteps, the
+vertical velocity is treated mostly implicitly at some location throughout the run. The
+oscillatory nature of this measure appears to be linked to the progress of the plume front
+as each cusp is associated with the location of the maximum shifting to the adjacent cell.
+This is illustrated in \autoref{fig:zad_Aimp_maxCf_loc} where the i- and k- locations of the
+maximum have been overlaid for the base run case.
+
+\medskip
+\noindent Only limited tests have been performed in more realistic configurations. In the
+ORCA2\_ICE\_PISCES reference configuration the scheme does activate and passes
+restartability and reproducibility tests but it is unable to improve the model's stability
+enough to allow an increase in the model time-step. A view of the time-series of maximum
+partitioning coefficient (not shown here)  suggests that the default time-step of 5400s is
+already pushing at stability limits, especially in the initial start-up phase. The
+time-series does not, however, exhibit any of the 'cuspiness' found with the overflow
+tests.
+
+\medskip
+\noindent A short test with an eORCA1 configuration promises more since a test using a
+time-step of 3600s remains stable with \forcode{ln_zad_Aimp=.true.} whereas the
+time-step is limited to 2700s without.
+
+\begin{figure}[!t]
+  \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}
+\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}
+\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}
+\end{figure}
 
 % ================================================================
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_conservation.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_conservation.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_conservation.tex	(revision 11422)
@@ -21,11 +21,11 @@
 horizontal kinetic energy and/or potential enstrophy of horizontally non-divergent flow,
 and variance of temperature and salinity will be conserved in the absence of dissipative effects and forcing.
-\citet{Arakawa1966} has first pointed out the advantage of this approach.
+\citet{arakawa_JCP66} has first pointed out the advantage of this approach.
 He showed that if integral constraints on energy are maintained,
 the computation will be free of the troublesome "non linear" instability originally pointed out by
-\citet{Phillips1959}.
+\citet{phillips_TAMS59}.
 A consistent formulation of the energetic properties is also extremely important in carrying out
 long-term numerical simulations for an oceanographic model.
-Such a formulation avoids systematic errors that accumulate with time \citep{Bryan1997}.
+Such a formulation avoids systematic errors that accumulate with time \citep{bryan_JCP97}.
 
 The general philosophy of OPA which has led to the discrete formulation presented in {\S}II.2 and II.3 is to
@@ -39,5 +39,5 @@
 Note that in some very specific cases as passive tracer studies, the positivity of the advective scheme is required.
 In that case, and in that case only, the advective scheme used for passive tracer is a flux correction scheme
-\citep{Marti1992, Levy1996, Levy1998}.
+\citep{Marti1992?, Levy1996?, Levy1998?}.
 
 % -------------------------------------------------------------------------------------------------------------
@@ -65,5 +65,5 @@
   % \label{eq:vor_vorticity}
   \int_D {{\textbf {k}}\cdot \frac{1}{e_3 }\nabla \times \left( {\varsigma
-        \;{\rm {\bf k}}\times {\textbf {U}}_h } \right)\;dv} =0
+        \;{\mathrm {\mathbf k}}\times {\textbf {U}}_h } \right)\;dv} =0
 \]
 
@@ -189,7 +189,7 @@
 \[
   % \label{eq:dynldf_dyn}
-  \int\limits_D {\frac{1}{e_3 }{\rm {\bf k}}\cdot \nabla \times \left[ {\nabla
+  \int\limits_D {\frac{1}{e_3 }{\mathrm {\mathbf k}}\cdot \nabla \times \left[ {\nabla
         _h \left( {A^{lm}\;\chi } \right)-\nabla _h \times \left( {A^{lm}\;\zeta
-            \;{\rm {\bf k}}} \right)} \right]\;dv} =0
+            \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} =0
 \]
 
@@ -197,5 +197,5 @@
   % \label{eq:dynldf_div}
   \int\limits_D {\nabla _h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi }
-        \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)}
+        \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)}
     \right]\;dv} =0
 \]
@@ -203,6 +203,6 @@
 \[
   % \label{eq:dynldf_curl}
-  \int_D {{\rm {\bf U}}_h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi }
-        \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)}
+  \int_D {{\mathrm {\mathbf U}}_h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi }
+        \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)}
     \right]\;dv} \leqslant 0
 \]
@@ -210,7 +210,7 @@
 \[
   % \label{eq:dynldf_curl2}
-  \mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\zeta \;{\rm {\bf k}}\cdot
+  \mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\zeta \;{\mathrm {\mathbf k}}\cdot
     \nabla \times \left[ {\nabla _h \left( {A^{lm}\;\chi } \right)-\nabla _h
-        \times \left( {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} \right]\;dv}
+        \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} \right]\;dv}
   \leqslant 0
 \]
@@ -220,5 +220,5 @@
   \mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\chi \;\nabla _h \cdot \left[
       {\nabla _h \left( {A^{lm}\;\chi } \right)-\nabla _h \times \left(
-          {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} \right]\;dv} \leqslant 0
+          {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} \leqslant 0
 \]
 
@@ -260,10 +260,10 @@
   % \label{eq:dynzdf_vor}
   \begin{aligned}
-    & \int_D {\frac{1}{e_3 }{\rm {\bf k}}\cdot \nabla \times \left( {\frac{1}{e_3
-          }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm
-                  {\bf U}}_h }{\partial k}} \right)} \right)\;dv} =0 \\
-    & \int_D {\zeta \,{\rm {\bf k}}\cdot \nabla \times \left( {\frac{1}{e_3
-          }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm
-                  {\bf U}}_h }{\partial k}} \right)} \right)\;dv} \leq 0 \\
+    & \int_D {\frac{1}{e_3 }{\mathrm {\mathbf k}}\cdot \nabla \times \left( {\frac{1}{e_3
+          }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm
+                  {\mathbf U}}_h }{\partial k}} \right)} \right)\;dv} =0 \\
+    & \int_D {\zeta \,{\mathrm {\mathbf k}}\cdot \nabla \times \left( {\frac{1}{e_3
+          }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm
+                  {\mathbf U}}_h }{\partial k}} \right)} \right)\;dv} \leq 0 \\
   \end{aligned}
 \]
@@ -273,8 +273,8 @@
   \begin{aligned}
     &\int_D {\nabla \cdot \left( {\frac{1}{e_3 }\frac{\partial }{\partial
-            k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm {\bf U}}_h }{\partial k}}
+            k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm {\mathbf U}}_h }{\partial k}}
           \right)} \right)\;dv} =0 \\
     & \int_D {\chi \;\nabla \cdot \left( {\frac{1}{e_3 }\frac{\partial }{\partial
-            k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm {\bf U}}_h }{\partial k}}
+            k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm {\mathbf U}}_h }{\partial k}}
           \right)} \right)\;dv} \leq 0 \\
   \end{aligned}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_misc.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_misc.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_misc.tex	(revision 11422)
@@ -30,13 +30,9 @@
 are much narrow than even a single ocean grid-point.
 
-We describe briefly here the three methods that can be used in \NEMO to handle such improperly resolved straits.
-The first two consist of opening the strait by hand while ensuring that the mass exchanges through
-the strait are not too large by either artificially reducing the surface of the strait grid-cells or,
-locally increasing the lateral friction.
-In the third one, the strait is closed but exchanges of mass, heat and salt across the land are allowed.
-Note that such modifications are so specific to a given configuration that no attempt has been made to
-set them in a generic way.
-However, examples of how they can be set up is given in the ORCA 2\deg and 0.5\deg configurations.
-For example, for details of implementation in ORCA2, search: \texttt{IF( cp\_cfg == "orca" .AND. jp\_cfg == 2 )}
+We describe briefly here the two methods that can be used in \NEMO to handle such
+improperly resolved straits. The methods consist of opening the strait while ensuring
+that the mass exchanges through the strait are not too large by either artificially
+reducing the cross-sectional area of the strait grid-cells or, locally increasing the
+lateral friction.
 
 % -------------------------------------------------------------------------------------------------------------
@@ -46,23 +42,51 @@
 \label{subsec:MISC_strait_hand}
 
-$\bullet$ reduced scale factor in the cross-strait direction to a value in better agreement with
-the true mean width of the strait (\autoref{fig:MISC_strait_hand}).
-This technique is sometime called "partially open face" or "partially closed cells".
-The key issue here is only to reduce the faces of $T$-cell
-(\ie change the value of the horizontal scale factors at $u$- or $v$-point) but not the volume of the $T$-cell.
-Indeed, reducing the volume of strait $T$-cell can easily produce a numerical instability at
-that grid point that would require a reduction of the model time step.
-The changes associated with strait management are done in \mdl{domhgr},
-just after the definition or reading of the horizontal scale factors. 
-
-$\bullet$ increase of the viscous boundary layer thickness by local increase of the fmask value at the coast
-(\autoref{fig:MISC_strait_hand}).
-This is done in \mdl{dommsk} together with the setting of the coastal value of fmask (see  \autoref{sec:LBC_coast}).
+The first method involves reducing the scale factor in the cross-strait direction to a
+value in better agreement with the true mean width of the strait
+(\autoref{fig:MISC_strait_hand}).  This technique is sometime called "partially open face"
+or "partially closed cells".  The key issue here is only to reduce the faces of $T$-cell
+(\ie change the value of the horizontal scale factors at $u$- or $v$-point) but not the
+volume of the $T$-cell.  Indeed, reducing the volume of strait $T$-cell can easily produce
+a numerical instability at that grid point which would require a reduction of the model
+time step.  Thus to instigate a local change in the width of a Strait requires two steps:
+
+\begin{itemize}
+
+\item Add \texttt{e1e2u} and \texttt{e1e2v} arrays to the \np{cn\_domcfg} file. These 2D
+arrays should contain the products of the unaltered values of: $\texttt{e1u}*\texttt{e2u}$
+and $\texttt{e1u}*\texttt{e2v}$ respectively. That is the original surface areas of $u$-
+and $v$- cells respectively.  These areas are usually defined by the corresponding product
+within the \NEMO code but the presence of \texttt{e1e2u} and \texttt{e1e2v} in the
+\np{cn\_domcfg} file will suppress this calculation and use the supplied fields instead.
+If the model domain is provided by user-supplied code in \mdl{usrdef\_hgr}, then this
+routine should also return \texttt{e1e2u} and \texttt{e1e2v} and set the integer return
+argument \texttt{ie1e2u\_v} to a non-zero value. Values other than 0 for this argument
+will suppress the calculation of the areas.
+
+\item Change values of \texttt{e2u} or \texttt{e1v} (either in the \np{cn\_domcfg} file or
+via code in  \mdl{usrdef\_hgr}), whereever a Strait reduction is required. The choice of
+whether to alter \texttt{e2u} or \texttt{e1v} depends. respectively,  on whether the
+Strait in question is North-South orientated (\eg Gibraltar) or East-West orientated (\eg
+Lombok).
+
+\end{itemize}
+
+
+The second method is to increase the viscous boundary layer thickness by a local increase
+of the fmask value at the coast. This method can also be effective in wider passages.  The
+concept is illustarted in the second part of  \autoref{fig:MISC_strait_hand} and changes
+to specific locations can be coded in \mdl{usrdef\_fmask}. The \forcode{usr_def_fmask}
+routine is always called after \texttt{fmask} has been defined according to the choice of
+lateral boundary condition as discussed in \autoref{sec:LBC_coast}. The default version of
+\mdl{usrdef\_fmask} contains settings specific to ORCA2 and ORCA1 configurations. These are
+meant as examples only; it is up to the user to verify settings and provide alternatives
+for their own configurations. The default \forcode{usr_def_fmask} makes no changes to
+\texttt{fmask} for any other configuration.
 
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 \begin{figure}[!tbp]
   \begin{center}
-    \includegraphics[width=0.80\textwidth]{Fig_Gibraltar}
-    \includegraphics[width=0.80\textwidth]{Fig_Gibraltar2}
+    \includegraphics[width=\textwidth]{Fig_Gibraltar}
+    \includegraphics[width=\textwidth]{Fig_Gibraltar2}
     \caption{
       \protect\label{fig:MISC_strait_hand}
@@ -84,5 +108,5 @@
 \begin{figure}[!tbp]
   \begin{center}
-    \includegraphics[width=1.0\textwidth]{Fig_closea_mask_example}
+    \includegraphics[width=\textwidth]{Fig_closea_mask_example}
     \caption{
       \protect\label{fig:closea_mask_example}
@@ -102,5 +126,6 @@
 % Closed seas
 % ================================================================
-\section{Closed seas (\protect\mdl{closea})}
+\section[Closed seas (\textit{closea.F90})]
+{Closed seas (\protect\mdl{closea})}
 \label{sec:MISC_closea}
 
@@ -122,8 +147,8 @@
 
 \begin{enumerate}
-\item{{\bf No ``closea\_mask'' field is included in domain configuration
+\item{{\bfseries No ``closea\_mask'' field is included in domain configuration
   file.} In this case the closea module does nothing.}
 
-\item{{\bf A field called closea\_mask is included in the domain
+\item{{\bfseries A field called closea\_mask is included in the domain
 configuration file and ln\_closea=.false. in namelist namcfg.} In this
 case the inland seas defined by the closea\_mask field are filled in
@@ -131,5 +156,5 @@
 closea\_mask that is nonzero is set to be a land point.}
 
-\item{{\bf A field called closea\_mask is included in the domain
+\item{{\bfseries A field called closea\_mask is included in the domain
 configuration file and ln\_closea=.true. in namelist namcfg.} Each
 inland sea or group of inland seas is set to a positive integer value
@@ -140,5 +165,5 @@
 closea\_mask is zero).}
 
-\item{{\bf Fields called closea\_mask and closea\_mask\_rnf are
+\item{{\bfseries Fields called closea\_mask and closea\_mask\_rnf are
 included in the domain configuration file and ln\_closea=.true. in
 namelist namcfg.} This option works as for option 3, except that if
@@ -154,5 +179,5 @@
 ocean.}
 
-\item{{\bf Fields called closea\_mask and closea\_mask\_emp are
+\item{{\bfseries Fields called closea\_mask and closea\_mask\_emp are
 included in the domain configuration file and ln\_closea=.true. in
 namelist namcfg.} This option works the same as option 4 except that
@@ -174,70 +199,70 @@
 \subsection{Simple subsetting of input files via NetCDF attributes}
 
-The extended grids for use with the under-shelf ice cavities will result in redundant rows around Antarctica if
-the ice cavities are not active.
-A simple mechanism for subsetting input files associated with the extended domains has been implemented to
-avoid the need to maintain different sets of input fields for use with or without active ice cavities.
-The existing 'zoom' options are overly complex for this task and marked for deletion anyway.
-This alternative subsetting operates for the j-direction only and works by optionally looking for and
-using a global file attribute (named: \np{open\_ocean\_jstart}) to determine the starting j-row for input.
-The use of this option is best explained with an example:
-consider an ORCA1 configuration using the extended grid bathymetry and coordinate files:
-\vspace{-10pt}
-\ifile{eORCA1\_bathymetry\_v2}
-\ifile{eORCA1\_coordinates}
-\noindent These files define a horizontal domain of 362x332.
-Assuming the first row with open ocean wet points in the non-isf bathymetry for this set is row 42
-(\fortran indexing) then the formally correct setting for \np{open\_ocean\_jstart} is 41.
-Using this value as the first row to be read will result in a 362x292 domain which is the same size as
-the original ORCA1 domain.
-Thus the extended coordinates and bathymetry files can be used with all the original input files for ORCA1 if
-the ice cavities are not active (\np{ln\_isfcav = .false.}).
-Full instructions for achieving this are:
-
-\noindent Add the new attribute to any input files requiring a j-row offset, i.e:
-\vspace{-10pt}
+The extended grids for use with the under-shelf ice cavities will result in redundant rows
+around Antarctica if the ice cavities are not active.  A simple mechanism for subsetting
+input files associated with the extended domains has been implemented to avoid the need to
+maintain different sets of input fields for use with or without active ice cavities.  This
+subsetting operates for the j-direction only and works by optionally looking for and using
+a global file attribute (named: \np{open\_ocean\_jstart}) to determine the starting j-row
+for input.  The use of this option is best explained with an example: 
+\medskip
+
+\noindent Consider an ORCA1
+configuration using the extended grid domain configuration file: \ifile{eORCA1\_domcfg.nc}
+This file define a horizontal domain of 362x332.  The first row with
+open ocean wet points in the non-isf bathymetry for this set is row 42 (\fortran indexing)
+then the formally correct setting for \np{open\_ocean\_jstart} is 41.  Using this value as
+the first row to be read will result in a 362x292 domain which is the same size as the
+original ORCA1 domain.  Thus the extended domain configuration file can be used with all
+the original input files for ORCA1 if the ice cavities are not active (\np{ln\_isfcav =
+.false.}).  Full instructions for achieving this are:
+
+\begin{itemize}
+\item  Add the new attribute to any input files requiring a j-row offset, i.e:
+\begin{cmds} 
+ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_domcfg.nc 
+\end{cmds}
+
+\item Add the logical switch \np{ln\_use\_jattr} to \ngn{namcfg} in the configuration
+namelist (if it is not already there) and set \np{.true.}
+\end{itemize}
+
+\noindent Note that with this option, the j-size of the global domain is (extended
+j-size minus \np{open\_ocean\_jstart} + 1 ) and this must match the \texttt{jpjglo} value
+for the configuration. This means an alternative version of \ifile{eORCA1\_domcfg.nc} must
+be created for when \np{ln\_use\_jattr} is active. The \texttt{ncap2} tool provides a
+convenient way of achieving this:
+
 \begin{cmds}
-ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_coordinates.nc 
-ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_bathymetry_v2.nc
+ncap2 -s 'jpjglo=292' eORCA1_domcfg.nc nORCA1_domcfg.nc
 \end{cmds}
- 
-\noindent Add the logical switch to \ngn{namcfg} in the configuration namelist and set true:
-%--------------------------------------------namcfg--------------------------------------------------------
-
-\nlst{namcfg}
-%--------------------------------------------------------------------------------------------------------------
-
-\noindent Note the j-size of the global domain is the (extended j-size minus \np{open\_ocean\_jstart} + 1 ) and
-this must match the size of all datasets other than bathymetry and coordinates currently.
-However the option can be extended to any global, 2D and 3D, netcdf, input field by adding the:
-\vspace{-10pt}
+
+The domain configuration file is unique in this respect since it also contains the value
+of \texttt{jpjglo} that is read and used by the model. Any other global, 2D and 3D,
+netcdf, input field can be prepared for use in a reduced domain by adding the
+\texttt{open\_ocean\_jstart} attribute to the file's  global attributes. In particular
+this is true for any field that is read by \NEMO using the following optional argument to
+the appropriate call to \np{iom\_get}.
 \begin{forlines}
 lrowattr=ln_use_jattr
 \end{forlines}
-optional argument to the appropriate \np{iom\_get} call and the \np{open\_ocean\_jstart} attribute to
-the corresponding input files.
-It remains the users responsibility to set \np{jpjdta} and \np{jpjglo} values in
-the \np{namelist\_cfg} file according to their needs.
-
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-\begin{figure}[!ht]
-  \begin{center}
-    \includegraphics[width=0.90\textwidth]{Fig_LBC_zoom}
-    \caption{
-      \protect\label{fig:LBC_zoom}
-      Position of a model domain compared to the data input domain when the zoom functionality is used.
-    }
-  \end{center}
-\end{figure}
-%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-
+
+Currently, only the domain configuration variables make use of this optional argument so
+this facility is of little practical use except for tests where no other external input
+files are needed or you wish to use an extended domain configuration with inputs from
+earlier, non-extended configurations. Alternatively, it should be possible to exclude
+empty rows for extended domain, forced ocean runs using interpolation on the fly, by
+adding the optional argument to \texttt{iom\_get} calls for the weights and initial
+conditions. Experimenting with this remains an exercise for the user.
 
 % ================================================================
 % Accuracy and Reproducibility
 % ================================================================
-\section{Accuracy and reproducibility (\protect\mdl{lib\_fortran})}
+\section[Accuracy and reproducibility (\textit{lib\_fortran.F90})]
+{Accuracy and reproducibility (\protect\mdl{lib\_fortran})}
 \label{sec:MISC_fortran}
 
-\subsection{Issues with intrinsinc SIGN function (\protect\key{nosignedzero})}
+\subsection[Issues with intrinsinc SIGN function (\texttt{\textbf{key\_nosignedzero}})]
+{Issues with intrinsinc SIGN function (\protect\key{nosignedzero})}
 \label{subsec:MISC_sign}
 
@@ -272,5 +297,5 @@
 and their propagation and accumulation cause uncertainty in final simulation reproducibility on
 different numbers of processors.
-To avoid so, based on \citet{He_Ding_JSC01} review of different technics,
+To avoid so, based on \citet{he.ding_JS01} review of different technics,
 we use a so called self-compensated summation method.
 The idea is to estimate the roundoff error, store it in a buffer, and then add it back in the next addition. 
@@ -314,5 +339,5 @@
 This alternative method should give identical results to the default \textsc{ALLGATHER} method and
 is recommended for large values of \np{jpni}.
-The new method is activated by setting \np{ln\_nnogather} to be true ({\bf nammpp}).
+The new method is activated by setting \np{ln\_nnogather} to be true (\ngn{nammpp}).
 The reproducibility of results using the two methods should be confirmed for each new,
 non-reference configuration.
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_model_basics.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_model_basics.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_model_basics.tex	(revision 11422)
@@ -32,6 +32,8 @@
 \begin{enumerate}
 \item
-  \textit{spherical earth approximation}: the geopotential surfaces are assumed to be spheres so that
-  gravity (local vertical) is parallel to the earth's radius
+  \textit{spherical Earth approximation}: the geopotential surfaces are assumed to be oblate spheriods
+  that follow the Earth's bulge; these spheroids are approximated by spheres with
+  gravity locally vertical (parallel to the Earth's radius) and independent of latitude 
+  \citep[][section 2]{white.hoskins.ea_QJRMS05}.   
 \item
   \textit{thin-shell approximation}: the ocean depth is neglected compared to the earth's radius
@@ -63,8 +65,14 @@
     \nabla \cdot \vect U = 0
   \end{equation}
+ \item 
+  \textit{Neglect of additional Coriolis terms}: the Coriolis terms that vary with the cosine of latitude are neglected. 
+  These terms may be non-negligible where the Brunt-Vaisala frequency $N$ is small, either in the deep ocean or
+  in the sub-mesoscale motions of the mixed layer, or near the equator \citep[][section 1]{white.hoskins.ea_QJRMS05}. 
+  They can be consistently included as part of the ocean dynamics \citep[][section 3(d)]{white.hoskins.ea_QJRMS05} and are 
+  retained in the MIT ocean model.     
 \end{enumerate}
 
 Because the gravitational force is so dominant in the equations of large-scale motions,
-it is useful to choose an orthogonal set of unit vectors $(i,j,k)$ linked to the earth such that
+it is useful to choose an orthogonal set of unit vectors $(i,j,k)$ linked to the Earth such that
 $k$ is the local upward vector and $(i,j)$ are two vectors orthogonal to $k$,
 \ie tangent to the geopotential surfaces.
@@ -107,6 +115,7 @@
 an air-sea or ice-sea interface at its top.
 These boundaries can be defined by two surfaces, $z = - H(i,j)$ and $z = \eta(i,j,k,t)$,
-where $H$ is the depth of the ocean bottom and $\eta$ is the height of the sea surface.
-Both $H$ and $\eta$ are usually referenced to a given surface, $z = 0$, chosen as a mean sea surface
+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
@@ -120,5 +129,5 @@
 \begin{figure}[!ht]
   \begin{center}
-    \includegraphics[]{Fig_I_ocean_bc}
+    \includegraphics[width=\textwidth]{Fig_I_ocean_bc}
     \caption{
       \protect\label{fig:ocean_bc}
@@ -210,5 +219,5 @@
 The flow is barotropic and the surface moves up and down with gravity as the restoring force.
 The phase speed of such waves is high (some hundreds of metres per second) so that
-the time step would have to be very short if they were present in the model.
+the time step has to be very short when they are present in the model.
 The latter strategy filters out these waves since the rigid lid approximation implies $\eta = 0$,
 \ie the sea surface is the surface $z = 0$.
@@ -217,5 +226,5 @@
 The rigid-lid hypothesis is an obsolescent feature in modern OGCMs.
 It has been available until the release 3.1 of \NEMO, and it has been removed in release 3.2 and followings.
-Only the free surface formulation is now described in the this document (see the next sub-section).
+Only the free surface formulation is now described in this document (see the next sub-section).
 
 % -------------------------------------------------------------------------------------------------------------
@@ -237,5 +246,5 @@
 Allowing the air-sea interface to move introduces the external gravity waves (EGWs) as
 a class of solution of the primitive equations.
-These waves are barotropic because of hydrostatic assumption, and their phase speed is quite high.
+These waves are barotropic (\ie nearly independent of depth) and their phase speed is quite high.
 Their time scale is short with respect to the other processes described by the primitive equations.
 
@@ -258,15 +267,15 @@
 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}.
+which still allows to take into account freshwater fluxes applied at the ocean surface \citep{roullet.madec_JGR00}.
 Nevertheless, with the linearization, an exact conservation of heat and salt contents is lost.
 
 The filtering of EGWs in models with a free surface is usually a matter of discretisation of
 the temporal derivatives,
-using a split-explicit method \citep{Killworth_al_JPO91, Zhang_Endoh_JGR92} or
-the implicit scheme \citep{Dukowicz1994} or
-the addition of a filtering force in the momentum equation \citep{Roullet_Madec_JGR00}.
-With the present release, \NEMO offers the choice between
+using a split-explicit method \citep{killworth.webb.ea_JPO91, zhang.endoh_JGR92} or
+the implicit scheme \citep{dukowicz.smith_JGR94} or
+the addition of a filtering force in the momentum equation \citep{roullet.madec_JGR00}.
+With the present release, \NEMO  offers the choice between
 an explicit free surface (see \autoref{subsec:DYN_spg_exp}) or
-a split-explicit scheme strongly inspired the one proposed by \citet{Shchepetkin_McWilliams_OM05}
+a split-explicit scheme strongly inspired the one proposed by \citet{shchepetkin.mcwilliams_OM05}
 (see \autoref{subsec:DYN_spg_ts}).
 
@@ -292,5 +301,5 @@
 cannot be easily treated in a global model without filtering.
 A solution consists of introducing an appropriate coordinate transformation that
-shifts the singular point onto land \citep{Madec_Imbard_CD96, Murray_JCP96}.
+shifts the singular point onto land \citep{madec.imbard_CD96, murray_JCP96}.
 As a consequence, it is important to solve the primitive equations in various curvilinear coordinate systems.
 An efficient way of introducing an appropriate coordinate transform can be found when using a tensorial formalism.
@@ -298,5 +307,5 @@
 Ocean modellers mainly use three-dimensional orthogonal grids on the sphere (spherical earth approximation),
 with preservation of the local vertical. Here we give the simplified equations for this particular case.
-The general case is detailed by \citet{Eiseman1980} in their survey of the conservation laws of fluid dynamics.
+The general case is detailed by \citet{eiseman.stone_SR80} in their survey of the conservation laws of fluid dynamics.
 
 Let $(i,j,k)$ be a set of orthogonal curvilinear coordinates on
@@ -323,5 +332,5 @@
 \begin{figure}[!tb]
   \begin{center}
-    \includegraphics[]{Fig_I_earth_referential}
+    \includegraphics[width=\textwidth]{Fig_I_earth_referential}
     \caption{
       \protect\label{fig:referential}
@@ -338,5 +347,5 @@
 the vertical scale factor is a single function of $k$ as $k$ is parallel to $z$.
 The scalar and vector operators that appear in the primitive equations
-(\autoref{eq:PE_dyn} to \autoref{eq:PE_eos}) can be written in the tensorial form,
+(\autoref{eq:PE_dyn} to \autoref{eq:PE_eos}) can then be written in the tensorial form,
 invariant in any orthogonal horizontal curvilinear coordinate system transformation:
 \begin{subequations}
@@ -384,5 +393,5 @@
 \end{gather}
 
-Using the fact that the horizontal scale factors $e_1$ and $e_2$ are independent of $k$ and that
+Using again the fact that the horizontal scale factors $e_1$ and $e_2$ are independent of $k$ and that
 $e_3$  is a function of the single variable $k$,
 $NLT$ the nonlinear term of \autoref{eq:PE_dyn} can be transformed as follows:
@@ -456,5 +465,5 @@
   &      &= &\nabla \cdot (\vect U \, u) - (\nabla \cdot \vect U) \ u
             + \frac{1}{e_1 e_2} \lt( -v^2 \pd[e_2]{i} + u v \, \pd[e_1]{j} \rt) \\
-  \intertext{as $\nabla \cdot {\vect U} \; = 0$ (incompressibility) it comes:}
+  \intertext{as $\nabla \cdot {\vect U} \; = 0$ (incompressibility) it becomes:}
   &      &= &\, \nabla \cdot (\vect U \, u) + \frac{1}{e_1 e_2} \lt( v \; \pd[e_2]{i} - u \; \pd[e_1]{j} \rt) (-v)
 \end{alignat*}
@@ -516,5 +525,5 @@
     % \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_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}
@@ -526,5 +535,5 @@
     p_s = \rho \,g \, \eta
   \]
-  with $\eta$ is solution of \autoref{eq:PE_ssh}.
+  and $\eta$ is the solution of \autoref{eq:PE_ssh}.
 
   The vertical velocity and the hydrostatic pressure are diagnosed from the following equations:
@@ -536,15 +545,16 @@
   \]
   where the divergence of the horizontal velocity, $\chi$ is given by \autoref{eq:PE_div_Uh}.
-\item \textit{tracer equations}:
-  \[
-    %\label{eq:S}
-    \pd[T]{t} = - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 T \, u)]{i} + \pd[(e_1 T \, v)]{j} \rt]
+
+\item 
+  \textbf{tracer equations}:
+  \begin{equation}
+  \begin{split}
+    \pd[T]{t} = & - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 T \, u)]{i} + \pd[(e_1 T \, v)]{j} \rt]
                 - \frac{1}{e_3} \pd[(T \, w)]{k} + D^T + F^T \\
-    %\label{eq:T}
-    \pd[S]{t} = - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 S \, u)]{i} + \pd[(e_1 S \, v)]{j} \rt]
-                - \frac{1}{e_3} \pd[(S \, w)]{k} + D^S + F^S
-    %\label{eq:rho}
-    \rho = \rho \big( T,S,z(k) \big)
-  \]
+    \pd[S]{t} = & - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 S \, u)]{i} + \pd[(e_1 S \, v)]{j} \rt]
+                - \frac{1}{e_3} \pd[(S \, w)]{k} + D^S + F^S \\
+    \rho = & \rho \big( T,S,z(k) \big)
+  \end{split}
+  \end{equation}
 \end{itemize}
 
@@ -575,9 +585,9 @@
 follows the isopycnal surfaces, \eg an isopycnic coordinate.
 
-In order to satisfy two or more constrains one can even be tempted to mixed these coordinate systems, as in
+In order to satisfy two or more constraints one can even be tempted to mixed these coordinate systems, as in
 HYCOM (mixture of $z$-coordinate at the surface, isopycnic coordinate in the ocean interior and $\sigma$ at
-the ocean bottom) \citep{Chassignet_al_JPO03} or
+the ocean bottom) \citep{chassignet.smith.ea_JPO03} or
 OPA (mixture of $z$-coordinate in vicinity the surface and steep topography areas and $\sigma$-coordinate elsewhere)
-\citep{Madec_al_JPO96} among others.
+\citep{madec.delecluse.ea_JPO96} among others.
 
 In fact one is totally free to choose any space and time vertical coordinate by
@@ -592,22 +602,22 @@
 the $(i,j,s,t)$ generalised coordinate system with $s$ depending on the other three variables through
 \autoref{eq:PE_s}.
-This so-called \textit{generalised vertical coordinate} \citep{Kasahara_MWR74} is in fact
+This so-called \textit{generalised vertical coordinate} \citep{kasahara_MWR74} is in fact
 an Arbitrary Lagrangian--Eulerian (ALE) coordinate.
-Indeed, choosing an expression for $s$ is an arbitrary choice that determines
+Indeed, one has a great deal of freedom in the choice of expression for $s$. The choice determines
 which part of the vertical velocity (defined from a fixed referential) will cross the levels (Eulerian part) and
 which part will be used to move them (Lagrangian part).
-The coordinate is also sometime referenced as an adaptive coordinate \citep{Hofmeister_al_OM09},
+The coordinate is also sometime referenced as an adaptive coordinate \citep{hofmeister.burchard.ea_OM10},
 since the coordinate system is adapted in the course of the simulation.
 Its most often used implementation is via an ALE algorithm,
 in which a pure lagrangian step is followed by regridding and remapping steps,
-the later step implicitly embedding the vertical advection
-\citep{Hirt_al_JCP74, Chassignet_al_JPO03, White_al_JCP09}.
-Here we follow the \citep{Kasahara_MWR74} strategy:
-a regridding step (an update of the vertical coordinate) followed by an eulerian step with
+the latter step implicitly embedding the vertical advection
+\citep{hirt.amsden.ea_JCP74, chassignet.smith.ea_JPO03, white.adcroft.ea_JCP09}.
+Here we follow the \citep{kasahara_MWR74} strategy:
+a regridding step (an update of the vertical coordinate) followed by an Eulerian step with
 an explicit computation of vertical advection relative to the moving s-surfaces.
 
 %\gmcomment{
 %A key point here is that the $s$-coordinate depends on $(i,j)$ ==> horizontal pressure gradient...
-the generalized vertical coordinates used in ocean modelling are not orthogonal,
+The generalized vertical coordinates used in ocean modelling are not orthogonal,
 which contrasts with many other applications in mathematical physics.
 Hence, it is useful to keep in mind the following properties that may seem odd on initial encounter.
@@ -615,5 +625,5 @@
 The horizontal velocity in ocean models measures motions in the horizontal plane,
 perpendicular to the local gravitational field.
-That is, horizontal velocity is mathematically the same regardless the vertical coordinate, be it geopotential,
+That is, horizontal velocity is mathematically the same regardless of the vertical coordinate, be it geopotential,
 isopycnal, pressure, or terrain following.
 The key motivation for maintaining the same horizontal velocity component is that
@@ -660,5 +670,5 @@
 \[
   % \label{eq:PE_sco_w}
-  \omega = w - e_3 \, \pd[s]{t} - \sigma_1 \, u - \sigma_2 \, v
+  \omega = w -  \, \lt. \pd[z]{t} \rt|_s - \sigma_1 \, u - \sigma_2 \, v
 \]
 
@@ -671,5 +681,5 @@
   % \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
+                - \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*}
@@ -677,5 +687,5 @@
   % \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
+                - \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*}
@@ -687,5 +697,5 @@
                                        - \frac{1}{e_3} \pd[(\omega \, u)]{k}
                                        - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt)
-                                       + g \frac{\rho}{\rho_o} \sigma_1 + D_u^{\vect U} + F_u^{\vect U}
+                                       - g \frac{\rho}{\rho_o} \sigma_1 + D_u^{\vect U} + F_u^{\vect U}
   \end{multline*}
   \begin{multline*}
@@ -695,5 +705,5 @@
                                        - \frac{1}{e_3} \pd[(\omega \, v)]{k}
                                        - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt)
-                                       + g \frac{\rho}{\rho_o}\sigma_2 + D_v^{\vect U} + F_v^{\vect U}
+                                       - g \frac{\rho}{\rho_o}\sigma_2 + D_v^{\vect U} + F_v^{\vect U}
   \end{multline*}
   where the relative vorticity, $\zeta$, the surface pressure gradient,
@@ -738,5 +748,5 @@
 \begin{figure}[!b]
   \begin{center}
-    \includegraphics[]{Fig_z_zstar}
+    \includegraphics[width=\textwidth]{Fig_z_zstar}
     \caption{
       \protect\label{fig:z_zstar}
@@ -744,5 +754,5 @@
       (b) $z$-coordinate in non-linear free surface case ;
       (c) re-scaled height coordinate
-      (become popular as the \zstar-coordinate \citep{Adcroft_Campin_OM04}).
+      (become popular as the \zstar-coordinate \citep{adcroft.campin_OM04}).
     }
   \end{center}
@@ -750,9 +760,9 @@
 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 
-In that case, the free surface equation is nonlinear, and the variations of volume are fully taken into account.
-These coordinates systems is presented in a report \citep{Levier2007} available on the \NEMO web site.
+In this case, the free surface equation is nonlinear, and the variations of volume are fully taken into account.
+These coordinates systems is presented in a report \citep{levier.treguier.ea_rpt07} available on the \NEMO web site.
 
 The \zstar coordinate approach is an unapproximated, non-linear free surface implementation which allows one to
-deal with large amplitude free-surface variations relative to the vertical resolution \citep{Adcroft_Campin_OM04}.
+deal with large amplitude free-surface variations relative to the vertical resolution \citep{adcroft.campin_OM04}.
 In the \zstar formulation,
 the variation of the column thickness due to sea-surface undulations is not concentrated in the surface level,
@@ -766,8 +776,13 @@
 The position (\zstar) and vertical discretization (\zstar) are expressed as:
 \[
-  % \label{eq:z-star}
+  % \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}
+              = \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) . 
 \]
 Since the vertical displacement of the free surface is incorporated in the vertical coordinate \zstar,
@@ -776,15 +791,7 @@
 Also the divergence of the flow field is no longer zero as shown by the continuity equation:
 \[
-  \pd[r]{t} = \nabla_{\zstar} \cdot \lt( r \; \vect U_h \rt) (r \; w *) = 0
+  \pd[r]{t} = \nabla_{\zstar} \cdot \lt( r \; \vect U_h \rt) + \pd[r \; w^*]{\zstar} = 0 .
 \]
-
-% from MOM4p1 documentation
-To overcome problems with vanishing surface and/or bottom cells, we consider the zstar coordinate 
-\[
-  % \label{eq:PE_}
-  \zstar = H \lt( \frac{z - \eta}{H + \eta} \rt)
-\]
-
-This coordinate is closely related to the "eta" coordinate used in many atmospheric models
+This \zstar coordinate is closely related to the "eta" coordinate used in many atmospheric models
 (see Black (1994) for a review of eta coordinate atmospheric models).
 It was originally used in ocean models by Stacey et al. (1995) for studies of tides next to shelves,
@@ -798,5 +805,5 @@
 These properties greatly reduce difficulties of computing the horizontal pressure gradient relative to
 terrain following sigma models discussed in \autoref{subsec:PE_sco}.
-Additionally, since \zstar when $\eta = 0$,
+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
@@ -804,21 +811,21 @@
 depending on the sophistication of the pressure gradient solver.
 The quasi -horizontal nature of the coordinate surfaces also facilitates the implementation of
-neutral physics parameterizations in \zstar models using the same techniques as in $z$-models
-(see Chapters 13-16 of \cite{Griffies_Bk04}) for a discussion of neutral physics in $z$-models,
+neutral physics parameterizations in \zstar  models using the same techniques as in $z$-models
+(see Chapters 13-16 of \cite{griffies_bk04}) for a discussion of neutral physics in $z$-models,
 as well as \autoref{sec:LDF_slp} in this document for treatment in \NEMO).
 
-The range over which \zstar varies is time independent $-H \leq \zstar \leq 0$.
-Hence, all cells remain nonvanishing, so long as the surface height maintains $\eta > ?H$.
+The range over which \zstar  varies is time independent $-H \leq \zstar \leq 0$.
+Hence, all cells remain nonvanishing, so long as the surface height maintains $\eta > -H$.
 This is a minor constraint relative to that encountered on the surface height when using $s = z$ or $s = z - \eta$.
 
-Because \zstar has a time independent range, all grid cells have static increments ds,
-and the sum of the ver tical increments yields the time independent ocean depth. %k ds = H.
+Because \zstar  has a time independent range, all grid cells have static increments ds,
+and the sum of the vertical increments yields the time independent ocean depth. %k ds = H.
 The \zstar coordinate is therefore invisible to undulations of the free surface,
 since it moves along with the free surface.
-This proper ty means that no spurious vertical transport is induced across surfaces of constant \zstar by
+This property means that no spurious vertical transport is induced across surfaces of constant \zstar  by
 the motion of external gravity waves.
-Such spurious transpor t can be a problem in z-models, especially those with tidal forcing.
-Quite generally, the time independent range for the \zstar coordinate is a very convenient property that
-allows for a nearly arbitrary ver tical resolution even in the presence of large amplitude fluctuations of
+Such spurious transport can be a problem in z-models, especially those with tidal forcing.
+Quite generally, the time independent range for the \zstar  coordinate is a very convenient property that
+allows for a nearly arbitrary vertical resolution even in the presence of large amplitude fluctuations of
 the surface height, again so long as $\eta > -H$.
 %end MOM doc %%%
@@ -849,5 +856,5 @@
 The response to such a velocity field often leads to numerical dispersion effects.
 One solution to strongly reduce this error is to use a partial step representation of bottom topography instead of
-a full step one \cite{Pacanowski_Gnanadesikan_MWR98}.
+a full step one \cite{pacanowski.gnanadesikan_MWR98}.
 Another solution is to introduce a terrain-following coordinate system (hereafter $s$-coordinate).
 
@@ -870,11 +877,11 @@
 \begin{equation}
   \label{eq:PE_p_sco}
-  \nabla p |_z = \nabla p |_s - \pd[p]{s} \nabla z |_s
+  \nabla p |_z = \nabla p |_s - \frac{1}{e_3} \pd[p]{s} \nabla z |_s
 \end{equation}
 
 The second term in \autoref{eq:PE_p_sco} depends on the tilt of the coordinate surface and
-introduces a truncation error that is not present in a $z$-model.
+leads to a truncation error that is not present in a $z$-model.
 In the special case of a $\sigma$-coordinate (i.e. a depth-normalised coordinate system $\sigma = z/H$),
-\citet{Haney1991} and \citet{Beckmann1993} have given estimates of the magnitude of this truncation error.
+\citet{haney_JPO91} and \citet{beckmann.haidvogel_JPO93} have given estimates of the magnitude of this truncation error.
 It depends on topographic slope, stratification, horizontal and vertical resolution, the equation of state,
 and the finite difference scheme.
@@ -884,8 +891,8 @@
 The large-scale slopes require high horizontal resolution, and the computational cost becomes prohibitive.
 This problem can be at least partially overcome by mixing $s$-coordinate and
-step-like representation of bottom topography \citep{Gerdes1993a,Gerdes1993b,Madec_al_JPO96}.
+step-like representation of bottom topography \citep{gerdes_JGR93*a,gerdes_JGR93*b,madec.delecluse.ea_JPO96}.
 However, the definition of the model domain vertical coordinate becomes then a non-trivial thing for
 a realistic bottom topography:
-a envelope topography is defined in $s$-coordinate on which a full or
+an envelope topography is defined in $s$-coordinate on which a full or
 partial step bottom topography is then applied in order to adjust the model depth to the observed one
 (see \autoref{sec:DOM_zgr}.
@@ -904,5 +911,5 @@
 In contrast, the ocean will stay at rest in a $z$-model.
 As for the truncation error, the problem can be reduced by introducing the terrain-following coordinate below
-the strongly stratified portion of the water column (\ie the main thermocline) \citep{Madec_al_JPO96}.
+the strongly stratified portion of the water column (\ie the main thermocline) \citep{madec.delecluse.ea_JPO96}.
 An alternate solution consists of rotating the lateral diffusive tensor to geopotential or to isoneutral surfaces
 (see \autoref{subsec:PE_ldf}).
@@ -910,5 +917,5 @@
 strongly exceeding the stability limit of such a operator when it is discretized (see \autoref{chap:LDF}).
 
-The $s$-coordinates introduced here \citep{Lott_al_OM90,Madec_al_JPO96} differ mainly in two aspects from
+The $s$-coordinates introduced here \citep{lott.madec.ea_OM90,madec.delecluse.ea_JPO96} differ mainly in two aspects from
 similar models:
 it allows a representation of bottom topography with mixed full or partial step-like/terrain following topography;
@@ -921,6 +928,6 @@
 \label{subsec:PE_zco_tilde}
 
-The \ztilde -coordinate has been developed by \citet{Leclair_Madec_OM11}.
-It is available in \NEMO since the version 3.4.
+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.
@@ -934,5 +941,5 @@
 \label{sec:PE_zdf_ldf}
 
-The primitive equations describe the behaviour of a geophysical fluid at space and time scales larger than
+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.
@@ -984,5 +991,5 @@
 All the vertical physics is embedded in the specification of the eddy coefficients.
 They can be assumed to be either constant, or function of the local fluid properties
-(\eg Richardson number, Brunt-Vais\"{a}l\"{a} frequency...),
+(\eg Richardson number, Brunt-Vais\"{a}l\"{a} frequency, distance from the boundary ...),
 or computed from a turbulent closure model.
 The choices available in \NEMO are discussed in \autoref{chap:ZDF}).
@@ -1005,5 +1012,5 @@
 The resulting lateral diffusive and dissipative operators are of second order.
 Observations show that lateral mixing induced by mesoscale turbulence tends to be along isopycnal surfaces
-(or more precisely neutral surfaces \cite{McDougall1987}) rather than across them.
+(or more precisely neutral surfaces \cite{mcdougall_JPO87}) rather than across them.
 As the slope of neutral surfaces is small in the ocean, a common approximation is to assume that
 the `lateral' direction is the horizontal, \ie the lateral mixing is performed along geopotential surfaces.
@@ -1016,5 +1023,5 @@
 both horizontal and isoneutral operators have no effect on mean (\ie large scale) potential energy whereas
 potential energy is a main source of turbulence (through baroclinic instabilities).
-\citet{Gent1990} have proposed a parameterisation of mesoscale eddy-induced turbulence which
+\citet{gent.mcwilliams_JPO90} proposed a parameterisation of mesoscale eddy-induced turbulence which
 associates an eddy-induced velocity to the isoneutral diffusion.
 Its mean effect is to reduce the mean potential energy of the ocean.
@@ -1033,12 +1040,12 @@
 Another approach is becoming more and more popular:
 instead of specifying explicitly a sub-grid scale term in the momentum and tracer time evolution equations,
-one uses a advective scheme which is diffusive enough to maintain the model stability.
+one uses an advective scheme which is diffusive enough to maintain the model stability.
 It must be emphasised that then, all the sub-grid scale physics is included in the formulation of
 the advection scheme.
 
 All these parameterisations of subgrid scale physics have advantages and drawbacks.
-There are not all available in \NEMO. For active tracers (temperature and salinity) the main ones are:
+They are not all available in \NEMO. For active tracers (temperature and salinity) the main ones are:
 Laplacian and bilaplacian operators acting along geopotential or iso-neutral surfaces,
-\citet{Gent1990} parameterisation, and various slightly diffusive advection schemes.
+\citet{gent.mcwilliams_JPO90} parameterisation, and various slightly diffusive advection schemes.
 For momentum, the main ones are: Laplacian and bilaplacian operators acting along geopotential surfaces,
 and UBS advection schemes when flux form is chosen for the momentum advection.
@@ -1062,5 +1069,5 @@
 the rotation between geopotential and $s$-surfaces,
 while it is only an approximation for the rotation between isoneutral and $z$- or $s$-surfaces.
-Indeed, in the latter case, two assumptions are made to simplify \autoref{eq:PE_iso_tensor} \citep{Cox1987}.
+Indeed, in the latter case, two assumptions are made to simplify \autoref{eq: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.
@@ -1087,5 +1094,5 @@
 \subsubsection{Eddy induced velocity}
 
-When the \textit{eddy induced velocity} parametrisation (eiv) \citep{Gent1990} is used,
+When the \textit{eddy induced velocity} parametrisation (eiv) \citep{gent.mcwilliams_JPO90} is used,
 an additional tracer advection is introduced in combination with the isoneutral diffusion of tracers:
 \[
@@ -1141,5 +1148,5 @@
                          - \nabla_h \times \big( A^{lm} \, \zeta \; \vect k \big) \\
                       &= \lt(   \frac{1}{e_1}     \pd[ \lt( A^{lm}    \chi      \rt) ]{i} \rt.
-                              - \frac{1}{e_2 e_3} \pd[ \lt( A^{lm} \; e_3 \zeta \rt) ]{j}
+                              - \frac{1}{e_2 e_3} \pd[ \lt( A^{lm} \; e_3 \zeta \rt) ]{j} , 
                                 \frac{1}{e_2}     \pd[ \lt( A^{lm}    \chi      \rt) ]{j}
                          \lt. + \frac{1}{e_1 e_3} \pd[ \lt( A^{lm} \; e_3 \zeta \rt) ]{i} \rt)
@@ -1162,7 +1169,7 @@
 \ie on a $f$- or $\beta$-plane, not on the sphere.
 It is also a very good approximation in vicinity of the Equator in
-a geographical coordinate system \citep{Lengaigne_al_JGR03}.
-
-\subsubsection{lateral bilaplacian momentum diffusive operator}
+a geographical coordinate system \citep{lengaigne.madec.ea_JGR03}.
+
+\subsubsection{Lateral bilaplacian momentum diffusive operator}
 
 As for tracers, the bilaplacian order momentum diffusive operator is a re-entering Laplacian operator with
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex	(revision 11422)
@@ -18,5 +18,5 @@
 
 In that case, the free surface equation is nonlinear, and the variations of volume are fully taken into account.
-These coordinates systems is presented in a report \citep{Levier2007} available on the \NEMO web site. 
+These coordinates systems is presented in a report \citep{levier.treguier.ea_rpt07} available on the \NEMO web site. 
 
 \colorbox{yellow}{  end of to be updated}
@@ -73,5 +73,6 @@
 % Surface Pressure Gradient and Sea Surface Height
 % ================================================================
-\section{Surface pressure gradient and sea surface heigth (\protect\mdl{dynspg})}
+\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----------------------------------------------------
@@ -89,5 +90,5 @@
 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:PE_flt?}),
 and the split-explicit free surface described below.
 The extra term introduced in the filtered method is calculated implicitly,
@@ -97,5 +98,6 @@
 % Explicit
 %-------------------------------------------------------------
-\subsubsection{Explicit (\protect\key{dynspg\_exp})}
+\subsubsection[Explicit (\texttt{\textbf{key\_dynspg\_exp}})]
+{Explicit (\protect\key{dynspg\_exp})}
 \label{subsec:DYN_spg_exp}
 
@@ -133,5 +135,6 @@
 % Split-explicit time-stepping
 %-------------------------------------------------------------
-\subsubsection{Split-explicit time-stepping (\protect\key{dynspg\_ts})}
+\subsubsection[Split-explicit time-stepping (\texttt{\textbf{key\_dynspg\_ts}})]
+{Split-explicit time-stepping (\protect\key{dynspg\_ts})}
 \label{subsec:DYN_spg_ts}
 %--------------------------------------------namdom----------------------------------------------------
@@ -139,5 +142,5 @@
 \nlst{namdom} 
 %--------------------------------------------------------------------------------------------------------------
-The split-explicit free surface formulation used in OPA follows the one proposed by \citet{Griffies2004}.
+The split-explicit free surface formulation used in OPA follows the one proposed by \citet{Griffies2004?}.
 The general idea is to solve the free surface equation with a small time step,
 while the three dimensional prognostic variables are solved with a longer time step that
@@ -147,9 +150,9 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[width=0.90\textwidth]{Fig_DYN_dynspg_ts}
+    \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}.
+      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$.
@@ -171,5 +174,5 @@
 
 The split-explicit formulation has a damping effect on external gravity waves,
-which is weaker than the filtered free surface but still significant as shown by \citet{Levier2007} in
+which is weaker than the filtered free surface but still significant as shown by \citet{levier.treguier.ea_rpt07} in
 the case of an analytical barotropic Kelvin wave. 
 
@@ -291,12 +294,13 @@
 % Filtered formulation 
 %-------------------------------------------------------------
-\subsubsection{Filtered formulation (\protect\key{dynspg\_flt})}
+\subsubsection[Filtered formulation (\texttt{\textbf{key\_dynspg\_flt}})]
+{Filtered formulation (\protect\key{dynspg\_flt})}
 \label{subsec:DYN_spg_flt}
 
-The filtered formulation follows the \citet{Roullet2000} implementation.
+The filtered formulation follows the \citet{Roullet2000?} implementation.
 The extra term introduced in the equations (see {\S}I.2.2) is solved implicitly.
 The elliptic solvers available in the code are documented in \autoref{chap:MISC}.
 The amplitude of the extra term is given by the namelist variable \np{rnu}.
-The default value is 1, as recommended by \citet{Roullet2000}
+The default value is 1, as recommended by \citet{Roullet2000?}
 
 \colorbox{red}{\np{rnu}\forcode{ = 1} to be suppressed from namelist !}
@@ -305,9 +309,10 @@
 % Non-linear free surface formulation 
 %-------------------------------------------------------------
-\subsection{Non-linear free surface formulation (\protect\key{vvl})}
+\subsection[Non-linear free surface formulation (\texttt{\textbf{key\_vvl}})]
+{Non-linear free surface formulation (\protect\key{vvl})}
 \label{subsec:DYN_spg_vvl}
 
 In the non-linear free surface formulation, the variations of volume are fully taken into account.
-This option is presented in a report \citep{Levier2007} available on the NEMO web site.
+This option is presented in a report \citep{levier.treguier.ea_rpt07} available on the NEMO web site.
 The three time-stepping methods (explicit, split-explicit and filtered) are the same as in
 \autoref{DYN_spg_linear} except that the ocean depth is now time-dependent.
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_time_domain.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_time_domain.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_time_domain.tex	(revision 11422)
@@ -11,5 +11,5 @@
 
 % Missing things:
-%	- daymod: definition of the time domain (nit000, nitend andd the calendar)
+%	- daymod: definition of the time domain (nit000, nitend and the calendar)
 
 \gmcomment{STEVEN :maybe a picture of the directory structure in the introduction which could be referred to here,
@@ -22,5 +22,5 @@
 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.
 
@@ -40,7 +40,7 @@
 $\rdt$ is the time step;
 and the superscripts indicate the time at which a quantity is evaluated.
-Each term of the RHS is evaluated at a specific time step depending on the physics with which it is associated.
-
-The choice of the time step used for this evaluation is discussed below as well as
+Each term of the RHS is evaluated at a specific time stepping depending on the physics with which it is associated.
+
+The choice of the time stepping used for this evaluation is discussed below as well as
 the implications for starting or restarting a model simulation.
 Note that the time stepping calculation is generally performed in a single operation.
@@ -53,7 +53,5 @@
 is usually not the variable at the after time step;
 but rather it is used to store the time derivative (RHS in \autoref{eq:STP}) prior to time-stepping the equation.
-Generally, the time stepping is performed once at each time step in the \mdl{tranxt} and \mdl{dynnxt} modules,
-except when using implicit vertical diffusion or calculating sea surface height in which
-case time-splitting options are used.
+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.
 
 % -------------------------------------------------------------------------------------------------------------
@@ -64,5 +62,5 @@
 
 The time stepping used for processes other than diffusion is the well-known leapfrog scheme
-\citep{Mesinger_Arakawa_Bk76}.
+\citep{mesinger.arakawa_bk76}.
 This scheme is widely used for advection processes in low-viscosity fluids.
 It is a time centred scheme, \ie the RHS in \autoref{eq:STP} is evaluated at time step $t$, the now time step.
@@ -80,5 +78,5 @@
 To prevent it, the leapfrog scheme is often used in association with a Robert-Asselin time filter
 (hereafter the LF-RA scheme).
-This filter, first designed by \citet{Robert_JMSJ66} and more comprehensively studied by \citet{Asselin_MWR72},
+This filter, first designed by \citet{robert_JMSJ66} and more comprehensively studied by \citet{asselin_MWR72},
 is a kind of laplacian diffusion in time that mixes odd and even time steps:
 \begin{equation}
@@ -88,11 +86,11 @@
 where the subscript $F$ denotes filtered values and $\gamma$ is the Asselin coefficient.
 $\gamma$ is initialized as \np{rn\_atfp} (namelist parameter).
-Its default value is \np{rn\_atfp}~\forcode{= 10.e-3} (see \autoref{sec:STP_mLF}),
-causing only a weak dissipation of high frequency motions (\citep{Farge1987}).
+Its default value is \np{rn\_atfp}\forcode{ = 10.e-3} (see \autoref{sec:STP_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.
+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 momentum and tracer equations, LF-RA avoids implicit numerical diffusion:
@@ -107,5 +105,5 @@
 
 The leapfrog differencing scheme is unsuitable for the representation of diffusion and damping processes.
-For a tendancy $D_x$, representing a diffusion term or a restoring term to a tracer climatology
+For a tendency $D_x$, representing a diffusion term or a restoring term to a tracer climatology
 (when present, see \autoref{sec:TRA_dmp}), a forward time differencing scheme is used :
 \[
@@ -115,5 +113,5 @@
 
 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}
@@ -130,22 +128,6 @@
 
 For the vertical diffusion terms, a forward time differencing scheme can be used,
-but usually the numerical stability condition imposes a strong constraint on the time step.
-Two solutions are available in \NEMO to overcome the stability constraint:
-$(a)$ a forward time differencing scheme using a time splitting technique (\np{ln\_zdfexp}~\forcode{= .true.}) or
-$(b)$ a backward (or implicit) time differencing scheme                   (\np{ln\_zdfexp}~\forcode{= .false.}).
-In $(a)$, the master time step $\Delta$t is cut into $N$ fractional time steps so that
-the stability criterion is reduced by a factor of $N$.
-The computation is performed as follows:
-\begin{alignat*}{2}
-  % \label{eq:STP_ts}
-  &x_\ast^{t - \rdt}                      &= &x^{t - \rdt} \\
-  &x_\ast^{t - \rdt + L \frac{2 \rdt}{N}} &=   &x_\ast ^{t - \rdt + (L - 1) \frac{2 \rdt}{N}}
-                                             + \frac{2 \rdt}{N} \; DF^{t - \rdt + (L - 1) \frac{2 \rdt}{N}}
-  \quad \text{for $L = 1$ to $N$} \\
-  &x^{t + \rdt}                           &= &x_\ast^{t + \rdt}
-\end{alignat*}
-with DF a vertical diffusion term.
-The number of fractional time steps, $N$, is given by setting \np{nn\_zdfexp}, (namelist parameter).
-The scheme $(b)$ is unconditionally stable but diffusive. It can be written as follows:
+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}
@@ -157,7 +139,5 @@
 %%gm
 
-This scheme is rather time consuming since it requires a matrix inversion,
-but it becomes attractive since a value of 3 or more is needed for N in the forward time differencing scheme.
-For example, the finite difference approximation of the temperature equation is:
+This scheme is rather time consuming since it requires a matrix inversion. For example, the finite difference approximation of the temperature equation is:
 \[
   % \label{eq:STP_imp_zdf}
@@ -183,5 +163,5 @@
 $c(k)$ and $d(k)$ are positive and the diagonal term is greater than the sum of the two extra-diagonal terms,
 therefore a special adaptation of the Gauss elimination procedure is used to find the solution
-(see for example \citet{Richtmyer1967}).
+(see for example \citet{richtmyer.morton_bk67}).
 
 % -------------------------------------------------------------------------------------------------------------
@@ -191,5 +171,15 @@
 \label{sec:STP_spg_ts}
 
-===>>>>  TO BE written....  :-)
+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. 
 
 %\gmcomment{ 
@@ -197,14 +187,12 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[]{Fig_TimeStepping_flowchart}
+    \includegraphics[width=\textwidth]{Fig_TimeStepping_flowchart_v4}
     \caption{
       \protect\label{fig:TimeStep_flowchart}
-      Sketch of the leapfrog time stepping sequence in \NEMO from \citet{Leclair_Madec_OM09}.
-      The use of a semi -implicit computation of the hydrostatic pressure gradient requires the tracer equation to
-      be stepped forward prior to the momentum equation.
-      The need for knowledge of the vertical scale factor (here denoted as $h$) requires the sea surface height and
-      the continuity equation to be stepped forward prior to the computation of the tracer equation.
-      Note that the method for the evaluation of the surface pressure gradient $\nabla p_s$ is not presented here
-      (see \autoref{sec:DYN_spg}).
+      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}
@@ -219,5 +207,5 @@
 \label{sec:STP_mLF}
 
-Significant changes have been introduced by \cite{Leclair_Madec_OM09} in the LF-RA scheme in order to
+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.
@@ -237,17 +225,17 @@
 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 forcing term no longer excites the divergence of odd and even time steps \citep{leclair.madec_OM09}.
 % forcing seen by the model....
-This property improves the LF-RA scheme in two respects.
+This property improves the LF-RA scheme in two aspects.
 First, the LF-RA can now ensure the local and global conservation of tracers.
 Indeed, time filtering is no longer required on the forcing part.
-The influence of the Asselin filter on the forcing is be removed by adding a new term in the filter
+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}).
 Since the filtering of the forcing was the source of non-conservation in the classical LF-RA scheme,
-the modified formulation becomes conservative \citep{Leclair_Madec_OM09}.
+the modified formulation becomes conservative \citep{leclair.madec_OM09}.
 Second, the LF-RA becomes a truly quasi -second order scheme.
 Indeed, \autoref{eq:STP_forcing} used in combination with a careful treatment of static instability
-(\autoref{subsec:ZDF_evd}) and of the TKE physics (\autoref{subsec:ZDF_tke_ene}),
-the two other main sources of time step divergence,
+(\autoref{subsec:ZDF_evd}) and of the TKE physics (\autoref{subsec:ZDF_tke_ene}) 
+(the two other main sources of time step divergence),
 allows a reduction by two orders of magnitude of the Asselin filter parameter.
 
@@ -255,5 +243,5 @@
 $Q^{t + \rdt / 2}$ is the forcing applied over the $[t,t + \rdt]$ time interval.
 This and the change in the time filter, \autoref{eq:STP_RA},
-allows an exact evaluation of the contribution due to the forcing term between any two time steps,
+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.
 
@@ -261,5 +249,5 @@
 \begin{figure}[!t]
   \begin{center}
-    \includegraphics[]{Fig_MLF_forcing}
+    \includegraphics[width=\textwidth]{Fig_MLF_forcing}
     \caption{
       \protect\label{fig:MLF_forcing}
@@ -294,5 +282,5 @@
 This is done simply by keeping the leapfrog environment (\ie the \autoref{eq:STP} three level time stepping) but
 setting all $x^0$ (\textit{before}) and $x^1$ (\textit{now}) fields equal at the first time step and
-using half the value of $\rdt$.
+using half the value of a leapfrog time step ($2 \rdt$). 
 
 It is also possible to restart from a previous computation, by using a restart file.
@@ -303,14 +291,9 @@
 This requires saving two time levels and many auxiliary data in the restart files in machine precision.
 
-Note that when a semi -implicit scheme is used to evaluate the hydrostatic pressure gradient
-(see \autoref{subsec:DYN_hpg_imp}), an extra three-dimensional field has to
-be added to the restart file to ensure an exact restartability.
-This is done optionally via the  \np{nn\_dynhpg\_rst} namelist parameter,
-so that the size of the restart file can be reduced when restartability is not a key issue
-(operational oceanography or in ensemble simulations for seasonal forecasting).
-
-Note the size of the time step used, $\rdt$, is also saved in the restart file.
-When restarting, if the the time step has been changed, a restart using an Euler time stepping scheme is imposed.
-Options are defined through the  \ngn{namrun} namelist variables.
+Note that the time step $\rdt$, is also saved in the restart file.
+When restarting, if the time step has been changed, or one of the prognostic variables at \textit{before} time step 
+is missing, an Euler time stepping scheme is imposed. A forward initial step can still be enforced by the user by setting 
+the namelist variable \np{nn\_euler}\forcode{=0}. Other options to control the time integration of the model 
+are defined through the  \ngn{namrun} namelist variables.
 %%%
 \gmcomment{
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/foreword.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/foreword.tex	(revision 10999)
+++ 	(revision )
@@ -1,81 +1,0 @@
-\documentclass[../main/NEMO_manual]{subfiles}
-
-\begin{document}
-
-% ================================================================
-% Chapter Foreword
-% ================================================================
-\chapter*{Foreword}
-
-% ================================================================
-% Abstract
-% ================================================================
-\section*{Abstract}
-
-The ocean engine of NEMO (Nucleus for European Modelling of the Ocean) is a primitive equation model adapted to
-regional and global ocean circulation problems.
-It is intended to be a flexible tool for studying the ocean and its interactions with the others components of
-the earth climate system over a wide range of space and time scales.
-
-Prognostic variables are the three-dimensional velocity field, a non-linear sea surface height,
-the \textit{Conservative} Temperature and the \textit{Absolute} Salinity.
-In the horizontal direction, the model uses a curvilinear orthogonal grid and in the vertical direction,
-a full or partial step $z$-coordinate, or $s$-coordinate, or a mixture of the two.
-The distribution of variables is a three-dimensional Arakawa C-type grid.
-Various physical choices are available to describe ocean physics, including TKE, and GLS vertical physics.
-
-Within NEMO, the ocean is interfaced with a sea-ice model (SI$^3$)
- %or \href{https://github.com/CICE-Consortium/CICE}{CICE}),
-passive tracer and biogeochemical models (TOP-PISCES) and,
-via the \href{https://portal.enes.org/oasis}{OASIS} coupler, with several atmospheric general circulation models.
-It also support two-way grid embedding via the \href{http://agrif.imag.fr}{AGRIF} software.
-
-
-% ================================================================
-% Disclaimer
-% ================================================================
-\section*{Disclaimer}
-
-Like all components of NEMO, the ocean component is developed under
-the \href{http://www.cecill.info}{CECILL license}, which is a French adaptation of the GNU GPL
-(General Public License).
-Anyone may use it freely for research purposes, and is encouraged to communicate back to the NEMO team
-its own developments and improvements.
-
-The model and the present document have been made available as a service to the community.
-We cannot certify that the code and its manual are free of errors.
-Bugs are inevitable and some have undoubtedly survived the testing phase.
-Users are encouraged to bring them to our attention.
-
-The author assumes no responsibility for problems, errors, or incorrect usage of NEMO.
-
-% ================================================================
-% Citation
-% ================================================================
-\section*{Citation}
-
-Reference for papers and other publications is as follows:
-\vspace{0.5cm}
-
-{\sffamily
-NEMO ocean engine,
-Madec Gurvan and NEMO System Team, NEMO Consortium,
-Issue 27, Notes du Pôle de modélisation de l'Institut Pierre-Simon Laplace (IPSL), ISSN 1288-1619,
-\href{http://doi.org/10.5281/zenodo.1464816}{doi:10.5281/zenodo.1464816}
-}
-
-% ================================================================
-% External resources
-% ================================================================
-\section*{External resources}
-
-Additional information can be found on the \href{http://www.nemo-ocean.eu}{website} of the project and
-the \href{http://forge.ipsl.jussieu.fr/nemo}{forge platform} of the source code.
-A \href{http://listes.ipsl.fr/sympa/info/nemo-newsletter}{newsletter list} is also open for subscription to
-receive top-down communication from the consortium (announcements, job opportunities, ...).
-
-\biblio
-
-\pindex
-
-\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/introduction.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/introduction.tex	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/introduction.tex	(revision 11422)
@@ -27,5 +27,5 @@
 
 The ocean component of \NEMO has been developed from the legacy of the OPA model, release 8.2, 
-described in \citet{Madec1998}.
+described in \citet{madec.delecluse.ea_NPM98}.
 This model has been used for a wide range of applications, both regional or global, as a forced ocean model and 
 as a model coupled with the sea-ice and/or the atmosphere.
@@ -67,7 +67,7 @@
 Within the \NEMO system the ocean model is interactively coupled with a sea ice model (SI$^3$) and
 a biogeochemistry model (PISCES).
-Interactive coupling to Atmospheric models is possible via the OASIS coupler \citep{OASIS2006}.
+Interactive coupling to Atmospheric models is possible via the \href{https://portal.enes.org/oasis}{OASIS coupler}.
 Two-way nesting is also available through an interface to the AGRIF package
-(Adaptative Grid Refinement in \fortran) \citep{Debreu_al_CG2008}.
+(Adaptative Grid Refinement in \fortran) \citep{debreu.vouland.ea_CG08}.
 % Needs to be reviewed
 %The interface code for coupling to an alternative sea ice model (CICE, \citet{Hunke2008}) has now been upgraded so
@@ -83,9 +83,9 @@
 The lateral Laplacian and biharmonic viscosity and diffusion can be rotated following
 a geopotential or neutral direction.
-There is an optional eddy induced velocity \citep{Gent1990} with a space and time variable coefficient
-\citet{Treguier1997}.
+There is an optional eddy induced velocity \citep{gent.mcwilliams_JPO90} with a space and time variable coefficient
+\citet{treguier.held.ea_JPO97}.
 The model has vertical harmonic viscosity and diffusion with a space and time variable coefficient,
-with options to compute the coefficients with \citet{Blanke1993}, \citet{Pacanowski_Philander_JPO81}, or 
-\citet{Umlauf_Burchard_JMS03} mixing schemes.
+with options to compute the coefficients with \citet{blanke.delecluse_JPO93}, \citet{pacanowski.philander_JPO81}, or 
+\citet{umlauf.burchard_JMR03} mixing schemes.
  
 %%gm    To be put somewhere else ....
@@ -151,5 +151,5 @@
 The coding rules for OPA include conventions for naming variables,
 with different starting letters for different types of variables (real, integer, parameter\ldots).
-Those rules are briefly presented in \autoref{apdx:D} and a more complete document is available .
+Those rules are briefly presented in \autoref{apdx:coding} and a more complete document is available .
 
 The model is organized with a high internal modularity based on physics.
@@ -158,5 +158,5 @@
 To make it easier for the user to find his way around the code, the module names follow a three-letter rule.
 For example, \mdl{traldf} is a module related to the TRAcers equation, computing the Lateral DiFfussion.
-%The complete list of module names is presented in \autoref{apdx:D}.      %====>>>> to be done !
+%The complete list of module names is presented in \autoref{apdx:coding}.      %====>>>> to be done !
 Furthermore, modules are organized in a few directories that correspond to their category,
 as indicated by the first three letters of their name (\autoref{tab:chapters}).
@@ -213,5 +213,5 @@
 NEMO/OPA, like all research tools, is in perpetual evolution.
 The present document describes the OPA version include in the release 3.4 of NEMO.
-This release differs significantly from version 8, documented in \citet{Madec1998}. \\
+This release differs significantly from version 8, documented in \citet{madec.delecluse.ea_NPM98}. \\
 
 The main modifications from OPA v8 and NEMO/OPA v3.2 are :
@@ -222,5 +222,5 @@
 \item
   introduction of partial step representation of bottom topography
-  \citep{Barnier_al_OD06, Le_Sommer_al_OM09, Penduff_al_OS07};
+  \citep{barnier.madec.ea_OD06, le-sommer.penduff.ea_OM09, penduff.le-sommer.ea_OS07};
 \item
   partial reactivation of a terrain-following vertical coordinate ($s$- and hybrid $s$-$z$) with
@@ -242,5 +242,5 @@
   additional advection schemes for tracers;
 \item
-  implementation of the AGRIF package (Adaptative Grid Refinement in \fortran) \citep{Debreu_al_CG2008};
+  implementation of the AGRIF package (Adaptative Grid Refinement in \fortran) \citep{debreu.vouland.ea_CG08};
 \item
   online diagnostics : tracers trend in the mixed layer and vorticity balance;
@@ -255,14 +255,14 @@
   RGB light penetration and optional use of ocean color 
 \item
-  major changes in the TKE schemes: it now includes a Langmuir cell parameterization \citep{Axell_JGR02},
-  the \citet{Mellor_Blumberg_JPO04} surface wave breaking parameterization, and has a time discretization which
-  is energetically consistent with the ocean model equations \citep{Burchard_OM02, Marsaleix_al_OM08};
+  major changes in the TKE schemes: it now includes a Langmuir cell parameterization \citep{axell_JGR02},
+  the \citet{mellor.blumberg_JPO04} surface wave breaking parameterization, and has a time discretization which
+  is energetically consistent with the ocean model equations \citep{burchard_OM02, marsaleix.auclair.ea_OM08};
 \item
   tidal mixing parametrisation (bottom intensification) + Indonesian specific tidal mixing
-  \citep{Koch-Larrouy_al_GRL07};
+  \citep{koch-larrouy.madec.ea_GRL07};
 \item
   introduction of LIM-3, the new Louvain-la-Neuve sea-ice model
   (C-grid rheology and new thermodynamics including bulk ice salinity)
-  \citep{Vancoppenolle_al_OM09a, Vancoppenolle_al_OM09b}
+  \citep{vancoppenolle.fichefet.ea_OM09*a, vancoppenolle.fichefet.ea_OM09*b}
 \end{itemize}
 
@@ -272,15 +272,15 @@
 \item
   introduction of a modified leapfrog-Asselin filter time stepping scheme
-  \citep{Leclair_Madec_OM09}; 
-\item
-  additional scheme for iso-neutral mixing \citep{Griffies_al_JPO98}, although it is still a "work in progress";
-\item
-  a rewriting of the bottom boundary layer scheme, following \citet{Campin_Goosse_Tel99};
-\item
-  addition of a Generic Length Scale vertical mixing scheme, following \citet{Umlauf_Burchard_JMS03};
+  \citep{leclair.madec_OM09}; 
+\item
+  additional scheme for iso-neutral mixing \citep{griffies.gnanadesikan.ea_JPO98}, although it is still a "work in progress";
+\item
+  a rewriting of the bottom boundary layer scheme, following \citet{campin.goosse_T99};
+\item
+  addition of a Generic Length Scale vertical mixing scheme, following \citet{umlauf.burchard_JMR03};
 \item
   addition of the atmospheric pressure as an external forcing on both ocean and sea-ice dynamics;
 \item
-  addition of a diurnal cycle on solar radiation \citep{Bernie_al_CD07};
+  addition of a diurnal cycle on solar radiation \citep{bernie.guilyardi.ea_CD07};
 \item
   river runoffs added through a non-zero depth, and having its own temperature and salinity;
@@ -296,5 +296,5 @@
   coupling interface adjusted for WRF atmospheric model;
 \item
-  C-grid ice rheology now available fro both LIM-2 and LIM-3 \citep{Bouillon_al_OM09};
+  C-grid ice rheology now available fro both LIM-2 and LIM-3 \citep{bouillon.maqueda.ea_OM09};
 \item
   LIM-3 ice-ocean momentum coupling applied to LIM-2;
@@ -318,5 +318,5 @@
 
 \begin{itemize}
-\item finalisation of above iso-neutral mixing \citep{Griffies_al_JPO98}";
+\item finalisation of above iso-neutral mixing \citep{griffies.gnanadesikan.ea_JPO98}";
 \item "Neptune effect" parametrisation;
 \item horizontal pressure gradient suitable for s-coordinate;
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/build/SI3_manual.ist
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/build/SI3_manual.ist	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/build/SI3_manual.ist	(revision 11422)
@@ -0,0 +1,1 @@
+link ../../global/index.ist
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/SI3_manual.ist
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/SI3_manual.ist	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/SI3_manual.ist	(revision 11422)
@@ -0,0 +1,1 @@
+link ../../global/index.ist
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/SI3_manual.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/SI3_manual.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/SI3_manual.tex	(revision 11422)
@@ -0,0 +1,1 @@
+link ../../global/document.tex
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/bibliography.bib
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/bibliography.bib	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/bibliography.bib	(revision 11422)
@@ -0,0 +1,677 @@
+
+@Article{	  assur_1958,
+  author	= {Assur, A},
+  year		= {1958},
+  month		= {01},
+  pages		= {106-138},
+  title		= {Composition of sea ice and its tensile strength},
+  volume	= {598},
+  journal	= {Arctic Sea Ice}
+}
+
+@Article{	  babko_2002,
+  author	= {Babko, O.},
+  title		= {Role of rafting in the mechanical redistribution of sea
+		  ice thickness},
+  year		= 2002,
+  volume	= 107,
+  number	= {C8},
+  issn		= {0148-0227},
+  doi		= {10.1029/1999jc000190},
+  url		= {http://dx.doi.org/10.1029/1999JC000190},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  bitz_1999,
+  author	= {Bitz, C. M. and Lipscomb, William H.},
+  title		= {An energy-conserving thermodynamic model of sea ice},
+  year		= 1999,
+  volume	= 104,
+  number	= {C7},
+  month		= {Jul},
+  pages		= {15669–15677},
+  issn		= {0148-0227},
+  doi		= {10.1029/1999jc900100},
+  url		= {http://dx.doi.org/10.1029/1999jc900100},
+  journal	= {Journal of Geophysical Research: Oceans},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  bitz_2001,
+  author	= {Bitz, C. M. and Holland, M. M. and Weaver, A. J. and Eby,
+		  M.},
+  title		= {Simulating the ice-thickness distribution in a coupled
+		  climate model},
+  year		= 2001,
+  volume	= 106,
+  number	= {C2},
+  month		= {Feb},
+  pages		= {2441–2463},
+  issn		= {0148-0227},
+  doi		= {10.1029/1999jc000113},
+  url		= {http://dx.doi.org/10.1029/1999jc000113},
+  journal	= {Journal of Geophysical Research: Oceans},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  bouillon_2013,
+  author	= {Bouillon, Sylvain and Fichefet, Thierry and Legat, Vincent
+		  and Madec, Gurvan},
+  title		= {The elastic–viscous–plastic method revisited},
+  year		= 2013,
+  volume	= 71,
+  month		= {Nov},
+  pages		= {2–12},
+  issn		= {1463-5003},
+  doi		= {10.1016/j.ocemod.2013.05.013},
+  url		= {http://dx.doi.org/10.1016/j.ocemod.2013.05.013},
+  journal	= {Ocean Modelling},
+  publisher	= {Elsevier BV}
+}
+
+@Article{	  brandt_2005,
+  author	= {Brandt, Richard E. and Warren, Stephen G. and Worby,
+		  Anthony P. and Grenfell, Thomas C.},
+  title		= {Surface Albedo of the Antarctic Sea Ice Zone},
+  year		= 2005,
+  volume	= 18,
+  number	= 17,
+  month		= {Sep},
+  pages		= {3606–3622},
+  issn		= {1520-0442},
+  doi		= {10.1175/jcli3489.1},
+  url		= {http://dx.doi.org/10.1175/jcli3489.1},
+  journal	= {Journal of Climate},
+  publisher	= {American Meteorological Society}
+}
+
+@Article{	  coon_1974,
+  author	= {Coon, M.D. and Maykut, G.A. and Pritchard, R.S. and
+		  Rothrock, D.A. and Thorndike, A.S.},
+  year		= {1974},
+  month		= {01},
+  pages		= {1-106},
+  title		= {Modeling the pack ice as an elastic-plastic material},
+  volume	= {24},
+  journal	= {AIDJEX Bull.}
+}
+
+@Article{	  ebert_1993,
+  author	= {Ebert, Elizabeth E. and Curry, Judith A.},
+  title		= {An intermediate one-dimensional thermodynamic sea ice
+		  model for investigating ice-atmosphere interactions},
+  year		= 1993,
+  volume	= 98,
+  number	= {C6},
+  pages		= 10085,
+  issn		= {0148-0227},
+  doi		= {10.1029/93jc00656},
+  url		= {http://dx.doi.org/10.1029/93jc00656},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  fichefet_1997,
+  author	= {Fichefet, T. and Maqueda, M. A. Morales},
+  title		= {Sensitivity of a global sea ice model to the treatment of
+		  ice thermodynamics and dynamics},
+  year		= 1997,
+  volume	= 102,
+  number	= {C6},
+  month		= {Jun},
+  pages		= {12609–12646},
+  issn		= {0148-0227},
+  doi		= {10.1029/97jc00480},
+  url		= {http://dx.doi.org/10.1029/97jc00480},
+  journal	= {Journal of Geophysical Research: Oceans},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  flato_1995,
+  author	= {Flato, Gregory M. and Hibler, William D.},
+  title		= {Ridging and strength in modeling the thickness
+		  distribution of Arctic sea ice},
+  year		= 1995,
+  volume	= 100,
+  number	= {C9},
+  pages		= 18611,
+  issn		= {0148-0227},
+  doi		= {10.1029/95jc02091},
+  url		= {http://dx.doi.org/10.1029/95jc02091},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  girard_2009,
+  author	= {Girard, L. and Weiss, J. and Molines, J. M. and Barnier,
+		  B. and Bouillon, S.},
+  title		= {Evaluation of high-resolution sea ice models on the basis
+		  of statistical and scaling properties of Arctic sea ice
+		  drift and deformation},
+  year		= 2009,
+  volume	= 114,
+  number	= {C8},
+  month		= {Aug},
+  issn		= {0148-0227},
+  doi		= {10.1029/2008jc005182},
+  url		= {http://dx.doi.org/10.1029/2008JC005182},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  grenfell_1977,
+  author	= {Grenfell, Thomas C. and Maykut, Gary A.},
+  title		= {The Optical Properties of Ice and Snow in the Arctic
+		  Basin},
+  year		= 1977,
+  volume	= 18,
+  number	= 80,
+  pages		= {445–463},
+  issn		= {1727-5652},
+  doi		= {10.3189/s0022143000021122},
+  url		= {http://dx.doi.org/10.3189/s0022143000021122},
+  journal	= {Journal of Glaciology},
+  publisher	= {Cambridge University Press (CUP)}
+}
+
+@Article{	  grenfell_2004,
+  author	= {Grenfell, Thomas C.},
+  title		= {Seasonal and spatial evolution of albedo in a
+		  snow-ice-land-ocean environment},
+  year		= 2004,
+  volume	= 109,
+  number	= {C1},
+  issn		= {0148-0227},
+  doi		= {10.1029/2003jc001866},
+  url		= {http://dx.doi.org/10.1029/2003JC001866},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  haapala_2000,
+  author	= {Haapala, Jari},
+  title		= {On the modelling of ice-thickness redistribution},
+  year		= 2000,
+  volume	= 46,
+  number	= 154,
+  pages		= {427–437},
+  issn		= {1727-5652},
+  doi		= {10.3189/172756500781833106},
+  url		= {http://dx.doi.org/10.3189/172756500781833106},
+  journal	= {Journal of Glaciology},
+  publisher	= {Cambridge University Press (CUP)}
+}
+
+@Article{	  hibler_1979,
+  author	= {Hibler, W. D.},
+  title		= {A Dynamic Thermodynamic Sea Ice Model},
+  year		= 1979,
+  volume	= 9,
+  number	= 4,
+  month		= {Jul},
+  pages		= {815–846},
+  issn		= {1520-0485},
+  doi		= {10.1175/1520-0485(1979)009<0815:adtsim>2.0.co;2},
+  url		= {http://dx.doi.org/10.1175/1520-0485(1979)009<0815:adtsim>2.0.co;2},
+  journal	= {Journal of Physical Oceanography},
+  publisher	= {American Meteorological Society}
+}
+
+@Article{	  hibler_1980,
+  author	= {Hibler, W. D.},
+  title		= {Modeling a Variable Thickness Sea Ice Cover},
+  year		= 1980,
+  volume	= 108,
+  number	= 12,
+  month		= {Dec},
+  pages		= {1943–1973},
+  issn		= {1520-0493},
+  doi		= {10.1175/1520-0493(1980)108<1943:mavtsi>2.0.co;2},
+  url		= {http://dx.doi.org/10.1175/1520-0493(1980)108<1943:mavtsi>2.0.co;2},
+  journal	= {Monthly Weather Review},
+  publisher	= {American Meteorological Society}
+}
+
+@Article{	  hoyland_2002,
+  author	= {Høyland, Knut V.},
+  title		= {Consolidation of first-year sea ice ridges},
+  year		= 2002,
+  volume	= 107,
+  number	= {C6},
+  issn		= {0148-0227},
+  doi		= {10.1029/2000jc000526},
+  url		= {http://dx.doi.org/10.1029/2000JC000526},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@techreport{	  kovacs_1996,
+  author	= {Kovacs, Austin},
+  title		= {Sea Ice. Part 1. Bulk Salinity Versus Ice Floe
+		  Thickness,},
+  year		= 1996,
+  month		= {Jun},
+  doi		= {10.21236/ada312027},
+  url		= {http://dx.doi.org/10.21236/ada312027},
+  publisher	= {Defense Technical Information Center}
+}
+
+@Article{	  kreyscher_2000,
+  author	= {Kreyscher, Martin and Harder, Markus and Lemke, Peter and
+		  Flato, Gregory M.},
+  title		= {Results of the Sea Ice Model Intercomparison Project:
+		  Evaluation of sea ice rheology schemes for use in climate
+		  simulations},
+  year		= 2000,
+  volume	= 105,
+  number	= {C5},
+  month		= {May},
+  pages		= {11299–11320},
+  issn		= {0148-0227},
+  doi		= {10.1029/1999jc000016},
+  url		= {http://dx.doi.org/10.1029/1999jc000016},
+  journal	= {Journal of Geophysical Research: Oceans},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  lecomte_2011,
+  author	= {Lecomte, Olivier and Fichefet, Thierry and Vancoppenolle,
+		  Martin and Nicolaus, Marcel},
+  title		= {A new snow thermodynamic scheme for large-scale sea-ice
+		  models},
+  year		= 2011,
+  volume	= 52,
+  number	= 57,
+  pages		= {337–346},
+  issn		= {1727-5644},
+  doi		= {10.3189/172756411795931453},
+  url		= {http://dx.doi.org/10.3189/172756411795931453},
+  journal	= {Annals of Glaciology},
+  publisher	= {Cambridge University Press (CUP)}
+}
+
+@Article{	  lecomte_2015,
+  author	= {Lecomte, Olivier and Fichefet, Thierry and Flocco, Daniela
+		  and Schroeder, David and Vancoppenolle, Martin},
+  title		= {Interactions between wind-blown snow redistribution and
+		  melt ponds in a coupled ocean–sea ice model},
+  year		= 2015,
+  volume	= 87,
+  month		= {Mar},
+  pages		= {67–80},
+  issn		= {1463-5003},
+  doi		= {10.1016/j.ocemod.2014.12.003},
+  url		= {http://dx.doi.org/10.1016/j.ocemod.2014.12.003},
+  journal	= {Ocean Modelling},
+  publisher	= {Elsevier BV}
+}
+
+@Article{	  lepparanta_1995,
+  author	= {Leppäranta, Matti and Lensu, Mikko and Kosloff, Pekka and
+		  Veitch, Brian},
+  title		= {The life story of a first-year sea ice ridge},
+  year		= 1995,
+  volume	= 23,
+  number	= 3,
+  month		= {May},
+  pages		= {279–290},
+  issn		= {0165-232X},
+  doi		= {10.1016/0165-232x(94)00019-t},
+  url		= {http://dx.doi.org/10.1016/0165-232x(94)00019-t},
+  journal	= {Cold Regions Science and Technology},
+  publisher	= {Elsevier BV}
+}
+
+@Article{	  lepparanta_2011,
+  author	= {Leppäranta, Matti},
+  title		= {Drift ice material},
+  year		= 2011,
+  pages		= {11–63},
+  doi		= {10.1007/978-3-642-04683-4\_2},
+  url		= {http://dx.doi.org/10.1007/978-3-642-04683-4\_2},
+  isbn		= 9783642046834,
+  journal	= {The Drift of Sea Ice},
+  publisher	= {Springer Berlin Heidelberg}
+}
+
+@Article{	  lipscomb_2001,
+  author	= {Lipscomb, William H.},
+  title		= {Remapping the thickness distribution in sea ice models},
+  year		= 2001,
+  volume	= 106,
+  number	= {C7},
+  month		= {Jul},
+  pages		= {13989–14000},
+  issn		= {0148-0227},
+  doi		= {10.1029/2000jc000518},
+  url		= {http://dx.doi.org/10.1029/2000jc000518},
+  journal	= {Journal of Geophysical Research: Oceans},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  lipscomb_2007,
+  author	= {Lipscomb, William H. and Hunke, Elizabeth C. and
+		  Maslowski, Wieslaw and Jakacki, Jaromir},
+  title		= {Ridging, strength, and stability in high-resolution sea
+		  ice models},
+  year		= 2007,
+  volume	= 112,
+  number	= {C3},
+  month		= {Mar},
+  issn		= {0148-0227},
+  doi		= {10.1029/2005jc003355},
+  url		= {http://dx.doi.org/10.1029/2005JC003355},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  massonnet_2018,
+  author	= {Massonnet, F. and Barth\'el\'emy, A. and Worou, K. and
+		  Fichefet, T. and Vancoppenolle, M. and Rousset, C.},
+  title		= {Insights on the discretization of the ice thickness
+		  distribution in large-scale sea ice models},
+  journal	= {submitted},
+  year		= {2018}
+}
+
+@Article{	  maykut_1971,
+  author	= {Maykut, Gary A. and Untersteiner, Norbert},
+  title		= {Some results from a time-dependent thermodynamic model of
+		  sea ice},
+  year		= 1971,
+  volume	= 76,
+  number	= 6,
+  month		= {Feb},
+  pages		= {1550–1575},
+  issn		= {0148-0227},
+  doi		= {10.1029/jc076i006p01550},
+  url		= {http://dx.doi.org/10.1029/jc076i006p01550},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  maykut_1973,
+  author	= {Maykut, G. A. and Thorndike, A. S.},
+  title		= {An approach to coupling the dynamics and thermodynamics of
+		  Arctic sea ice},
+  journal	= {AIDJEX Bulletin},
+  year		= {1973},
+  volume	= {21},
+  pages		= {23--29}
+}
+
+@Article{	  maykut_1986,
+  author	= {Maykut, Gary A.},
+  title		= {The Surface Heat and Mass Balance},
+  year		= 1986,
+  pages		= {395–463},
+  doi		= {10.1007/978-1-4899-5352-0\_6},
+  url		= {http://dx.doi.org/10.1007/978-1-4899-5352-0\_6},
+  isbn		= 9781489953520,
+  journal	= {The Geophysics of Sea Ice},
+  publisher	= {Springer US}
+}
+
+@Article{	  maykut_1995,
+  author	= {Maykut, G. A. and McPhee, Miles G.},
+  title		= {Solar heating of the Arctic mixed layer},
+  year		= 1995,
+  volume	= 100,
+  number	= {C12},
+  pages		= 24691,
+  issn		= {0148-0227},
+  doi		= {10.1029/95jc02554},
+  url		= {http://dx.doi.org/10.1029/95jc02554},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  mcphee_1992,
+  author	= {McPhee, Miles G.},
+  title		= {Turbulent heat flux in the upper ocean under sea ice},
+  year		= 1992,
+  volume	= 97,
+  number	= {C4},
+  pages		= 5365,
+  issn		= {0148-0227},
+  doi		= {10.1029/92jc00239},
+  url		= {http://dx.doi.org/10.1029/92jc00239},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  mellor_1989,
+  author	= {Mellor, George L. and Kantha, Lakshmi},
+  title		= {An ice-ocean coupled model},
+  year		= 1989,
+  volume	= 94,
+  number	= {C8},
+  pages		= 10937,
+  issn		= {0148-0227},
+  doi		= {10.1029/jc094ic08p10937},
+  url		= {http://dx.doi.org/10.1029/jc094ic08p10937},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  notz_2016,
+  author	= {Notz, Dirk and Jahn, Alexandra and Holland, Marika and
+		  Hunke, Elizabeth and Massonnet, François and Stroeve,
+		  Julienne and Tremblay, Bruno and Vancoppenolle, Martin},
+  title		= {The CMIP6 Sea-Ice Model Intercomparison Project (SIMIP):
+		  understanding sea ice through climate-model simulations},
+  year		= 2016,
+  volume	= 9,
+  number	= 9,
+  month		= {Sep},
+  pages		= {3427–3446},
+  issn		= {1991-9603},
+  doi		= {10.5194/gmd-9-3427-2016},
+  url		= {http://dx.doi.org/10.5194/gmd-9-3427-2016},
+  journal	= {Geoscientific Model Development},
+  publisher	= {Copernicus GmbH}
+}
+
+@Article{	  parmerter_1975,
+  author	= {Parmerter, R. Reid},
+  title		= {A model of simple rafting in sea ice},
+  year		= 1975,
+  volume	= 80,
+  number	= 15,
+  month		= {May},
+  pages		= {1948–1952},
+  issn		= {0148-0227},
+  doi		= {10.1029/jc080i015p01948},
+  url		= {http://dx.doi.org/10.1029/jc080i015p01948},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  perovich_2002,
+  author	= {Perovich, D. K.},
+  title		= {Seasonal evolution of the albedo of multiyear Arctic sea
+		  ice},
+  year		= 2002,
+  volume	= 107,
+  number	= {C10},
+  issn		= {0148-0227},
+  doi		= {10.1029/2000jc000438},
+  url		= {http://dx.doi.org/10.1029/2000JC000438},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  prather_1986,
+  author	= {Prather, Michael J.},
+  title		= {Numerical advection by conservation of second-order
+		  moments},
+  year		= 1986,
+  volume	= 91,
+  number	= {D6},
+  pages		= 6671,
+  issn		= {0148-0227},
+  doi		= {10.1029/jd091id06p06671},
+  url		= {http://dx.doi.org/10.1029/jd091id06p06671},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  pringle_2007,
+  author	= {Pringle, D. J. and Eicken, H. and Trodahl, H. J. and
+		  Backstrom, L. G. E.},
+  title		= {Thermal conductivity of landfast Antarctic and Arctic sea
+		  ice},
+  year		= 2007,
+  volume	= 112,
+  number	= {C4},
+  month		= {Apr},
+  issn		= {0148-0227},
+  doi		= {10.1029/2006jc003641},
+  url		= {http://dx.doi.org/10.1029/2006JC003641},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  schmidt_2004,
+  author	= {Schmidt, Gavin A. and Bitz, Cecilia M. and Mikolajewicz,
+		  Uwe and Tremblay, L.-Bruno},
+  title		= {Ice–ocean boundary conditions for coupled models},
+  year		= 2004,
+  volume	= 7,
+  number	= {1-2},
+  month		= {Jan},
+  pages		= {59–74},
+  issn		= {1463-5003},
+  doi		= {10.1016/s1463-5003(03)00030-1},
+  url		= {http://dx.doi.org/10.1016/S1463-5003(03)00030-1},
+  journal	= {Ocean Modelling},
+  publisher	= {Elsevier BV}
+}
+
+@Article{	  shine_1985,
+  author	= {Shine, K. P. and Henderson-Sellers, A.},
+  title		= {The sensitivity of a thermodynamic sea ice model to
+		  changes in surface albedo parameterization},
+  year		= 1985,
+  volume	= 90,
+  number	= {D1},
+  pages		= 2243,
+  issn		= {0148-0227},
+  doi		= {10.1029/jd090id01p02243},
+  url		= {http://dx.doi.org/10.1029/jd090id01p02243},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Book{		  teos-10_2010,
+  title		= {{The international thermodynamic equation of seawater -
+		  2010: Calculation and use of thermodynamic properties}},
+  publisher	= {UNESCO (English)},
+  year		= {2010},
+  author	= {{IOC, SCOR and IAPSO}},
+  series	= {Intergovernmental Oceanographic Commission, Manuals and
+		  Guides No. 56},
+  url =          {http://www.teos-10.org/pubs/TEOS-10_Manual.pdf}
+}
+
+@Article{	  thorndike_1975,
+  author	= {Thorndike, A. S. and Rothrock, D. A. and Maykut, G. A. and
+		  Colony, R.},
+  title		= {The thickness distribution of sea ice},
+  year		= 1975,
+  volume	= 80,
+  number	= 33,
+  month		= {Nov},
+  pages		= {4501–4513},
+  issn		= {0148-0227},
+  doi		= {10.1029/jc080i033p04501},
+  url		= {http://dx.doi.org/10.1029/JC080i033p04501},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  tuhkuri_2002,
+  author	= {Tuhkuri, Jukka},
+  title		= {Laboratory tests on ridging and rafting of ice sheets},
+  year		= 2002,
+  volume	= 107,
+  number	= {C9},
+  issn		= {0148-0227},
+  doi		= {10.1029/2001jc000848},
+  url		= {http://dx.doi.org/10.1029/2001JC000848},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  vancoppenolle_2009,
+  author	= {Vancoppenolle, Martin and Fichefet, Thierry and Goosse,
+		  Hugues},
+  title		= {Simulating the mass balance and salinity of Arctic and
+		  Antarctic sea ice. 2. Importance of sea ice salinity
+		  variations},
+  year		= 2009,
+  volume	= 27,
+  number	= {1-2},
+  month		= {Jan},
+  pages		= {54–69},
+  issn		= {1463-5003},
+  doi		= {10.1016/j.ocemod.2008.11.003},
+  url		= {http://dx.doi.org/10.1016/j.ocemod.2008.11.003},
+  journal	= {Ocean Modelling},
+  publisher	= {Elsevier BV}
+}
+
+@Article{	  weiss_2013,
+  author	= {Weiss, Jérôme},
+  title		= {Drift, Deformation, and Fracture of Sea Ice},
+  year		= 2013,
+  issn		= {2191-5377},
+  doi		= {10.1007/978-94-007-6202-2},
+  url		= {http://dx.doi.org/10.1007/978-94-007-6202-2},
+  isbn		= 9789400762022,
+  journal	= {SpringerBriefs in Earth Sciences},
+  publisher	= {Springer Netherlands}
+}
+
+@Article{	  worster_1992,
+  author	= {Worster, M. G.},
+  title		= {The Dynamics of Mushy Layers},
+  year		= 1992,
+  pages		= {113–138},
+  doi		= {10.1007/978-94-011-2809-4\_20},
+  url		= {http://dx.doi.org/10.1007/978-94-011-2809-4\_20},
+  isbn		= 9789401128094,
+  journal	= {Interactive Dynamics of Convection and Solidification},
+  publisher	= {Springer Netherlands}
+}
+
+@Article{	  zhang_2001,
+  author	= {Zhang, Jinlun and Rothrock, Drew},
+  title		= {A Thickness and Enthalpy Distribution Sea-Ice Model},
+  year		= 2001,
+  volume	= 31,
+  number	= 10,
+  month		= {Oct},
+  pages		= {2986–3001},
+  issn		= {1520-0485},
+  doi		= {10.1175/1520-0485(2001)031<2986:ataeds>2.0.co;2},
+  url		= {http://dx.doi.org/10.1175/1520-0485(2001)031<2986:ataeds>2.0.co;2},
+  journal	= {Journal of Physical Oceanography},
+  publisher	= {American Meteorological Society}
+}
+
+@Article{	  zuo_1996,
+  author	= {Zuo, Z. and Oerlemans, J.},
+  title		= {Modelling albedo and specific balance of the Greenland ice
+		  sheet: calculations for the Søndre Strømfjord transect},
+  year		= 1996,
+  volume	= 42,
+  number	= 141,
+  pages		= {305–317},
+  issn		= {1727-5652},
+  doi		= {10.1017/s0022143000004160},
+  url		= {http://dx.doi.org/10.1017/s0022143000004160},
+  journal	= {Journal of Glaciology},
+  publisher	= {Cambridge University Press (CUP)}
+}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/blocks.idx
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/blocks.idx	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/blocks.idx	(revision 11422)
@@ -0,0 +1,1 @@
+link ../build/blocks.idx
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/chapters.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/chapters.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/chapters.tex	(revision 11422)
@@ -0,0 +1,16 @@
+\subfile{../subfiles/todolist}
+
+\subfile{../subfiles/introduction}               % Introduction
+
+\subfile{../subfiles/chap_model_basics}
+\subfile{../subfiles/chap_domain}
+\subfile{../subfiles/chap_dynamics}
+\subfile{../subfiles/chap_transport}
+\subfile{../subfiles/chap_ridging_rafting}
+\subfile{../subfiles/chap_radiative_transfer}
+\subfile{../subfiles/chap_thermo}
+\subfile{../subfiles/chap_interfaces}
+\subfile{../subfiles/chap_output_diagnostics}
+\subfile{../subfiles/chap_single_category_use}
+\subfile{../subfiles/chap_bdy_agrif}
+\subfile{../subfiles/chap_miscellaneous}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/definitions.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/definitions.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/definitions.tex	(revision 11422)
@@ -0,0 +1,15 @@
+%% Engine (folder name)
+\def \engine{SI3}
+
+%% Title (variable name already use by 'titling' pkg)
+\def \heading{Sea Ice modelling Integrated Initiative (SI$^3$) \\ The NEMO sea ice engine}
+
+%% Authors (thanks will apply to the second author)
+\def \firstauthor{}
+\def \secondauthor{NEMO Sea Ice Working Group}
+
+%% IPSL publication number
+\def \ipslnum{31}
+
+%% Zenodo ID, i.e. doi:10.5281/zenodo.\([0-9]*\)
+\def \zid{1471689}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/keys.idx
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/keys.idx	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/keys.idx	(revision 11422)
@@ -0,0 +1,1 @@
+link ../build/keys.idx
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/modules.idx
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/modules.idx	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/modules.idx	(revision 11422)
@@ -0,0 +1,1 @@
+link ../build/modules.idx
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/parameters.idx
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/parameters.idx	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/parameters.idx	(revision 11422)
@@ -0,0 +1,1 @@
+link ../build/parameters.idx
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/subroutines.idx
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/subroutines.idx	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/subroutines.idx	(revision 11422)
@@ -0,0 +1,1 @@
+link ../build/subroutines.idx
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/thanks.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/thanks.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/main/thanks.tex	(revision 11422)
@@ -0,0 +1,1 @@
+TBD
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namalb
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namalb	(revision 10999)
+++ 	(revision )
@@ -1,10 +1,0 @@
-!------------------------------------------------------------------------------
-&namalb         !   albedo parameters
-!------------------------------------------------------------------------------
-   !                                  !                          !  obs range (cloud-sky)
-   rn_alb_sdry      =   0.85          !  dry snow albedo         :  0.85 -- 0.87
-   rn_alb_smlt      =   0.75          !  melting snow albedo     :  0.72 -- 0.82
-   rn_alb_idry      =   0.60          !  dry ice albedo          :  0.54 -- 0.65
-   rn_alb_imlt      =   0.50          !  bare puddled ice albedo :  0.49 -- 0.58
-   rn_alb_dpnd      =   0.27          !  ponded ice albedo       :  0.10 -- 0.30 
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namdia
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namdia	(revision 10999)
+++ 	(revision )
@@ -1,9 +1,0 @@
-!------------------------------------------------------------------------------
-&namdia         !   Diagnostics
-!------------------------------------------------------------------------------
-   ln_icediachk     = .false.         !  check online the heat, mass & salt budgets (T) or not (F)
-   ln_icediahsb     = .false.         !  output the heat, mass & salt budgets (T) or not (F)
-   ln_icectl        = .false.         !  ice points output for debug (T or F)
-   iiceprt          =  10             !  i-index for debug
-   jiceprt          =  10             !  j-index for debug
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namdyn
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namdyn	(revision 10999)
+++ 	(revision )
@@ -1,17 +1,0 @@
-!------------------------------------------------------------------------------
-&namdyn         !   Ice dynamics
-!------------------------------------------------------------------------------
-   ln_dynFULL       = .true.          !  dyn.: full ice dynamics               (rheology + advection + ridging/rafting + correction)
-   ln_dynRHGADV     = .false.         !  dyn.: no ridge/raft & no corrections  (rheology + advection)
-   ln_dynADV        = .false.         !  dyn.: only advection w prescribed vel.(rn_uvice + advection)
-      rn_uice       =   0.00001       !        prescribed ice u-velocity
-      rn_vice       =   0.            !        prescribed ice v-velocity
-   rn_ishlat        =   2.            !  free slip (0) ; partial slip (0-2) ; no slip (2) ; strong slip (>2)
-   ln_landfast      = .false.         !  landfast ice parameterization (T or F)                           
-      rn_gamma      =   0.15          !     fraction of ocean depth that ice must reach to initiate landfast
-                                      !        recommended range: [0.1 ; 0.25]
-      rn_icebfr     =  10.            !     maximum bottom stress per unit area of contact [N/m2]                 
-                                      !        a very large value ensures ice velocity=0 even with a small contact area
-                                      !        recommended range: ?? (should be greater than atm-ice stress => >0.1 N/m2)
-      rn_lfrelax    =   1.e-5         !     relaxation time scale to reach static friction [s-1]
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namdyn_rdgrft
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namdyn_rdgrft	(revision 10999)
+++ 	(revision )
@@ -1,25 +1,0 @@
-!------------------------------------------------------------------------------
-&namdyn_rdgrft  !   Ice ridging/rafting
-!------------------------------------------------------------------------------
-          ! -- ice_rdgrft_strength -- !
-   ln_str_H79       = .true.          !  ice strength param.: Hibler_79   => P = pstar*<h>*exp(-c_rhg*A)                      
-      rn_pstar      =   2.0e+04       !     ice strength thickness parameter [N/m2]
-      rn_crhg       =   20.0          !     ice strength conc. parameter (-)
-                   ! -- ice_rdgrft -- !
-   rn_csrdg         =   0.5           !  fraction of shearing energy contributing to ridging
-              ! -- ice_rdgrft_prep -- !
-   ln_partf_lin     = .false.         !  Linear ridging participation function (Thorndike et al, 1975)
-      rn_gstar      =   0.15          !     fractional area of thin ice being ridged 
-   ln_partf_exp     = .true.          !  Exponential ridging participation function (Lipscomb, 2007)
-      rn_astar      =   0.03          !     exponential measure of ridging ice fraction [set to 0.05 if hstar=100]
-   ln_ridging       = .true.          !  ridging activated (T) or not (F)
-      rn_hstar      =  25.0           !     determines the maximum thickness of ridged ice [m] (Hibler, 1980)
-      rn_porordg    =   0.3           !     porosity of newly ridged ice (Lepparanta et al., 1995)
-      rn_fsnwrdg    =   0.5           !     snow volume fraction that survives in ridging
-      rn_fpndrdg    =   1.0           !     pond fraction that survives in ridging (small a priori)
-   ln_rafting       = .true.          !  rafting activated (T) or not (F)
-      rn_hraft      =   0.75          !     threshold thickness for rafting [m]
-      rn_craft      =   5.0           !     squeezing coefficient used in the rafting function
-      rn_fsnwrft    =   0.5           !     snow volume fraction that survives in rafting
-      rn_fpndrft    =   1.0           !     pond fraction that survives in rafting (0.5 a priori)
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namdyn_rhg
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namdyn_rhg	(revision 10999)
+++ 	(revision )
@@ -1,11 +1,0 @@
-!------------------------------------------------------------------------------
-&namdyn_rhg     !   Ice rheology
-!------------------------------------------------------------------------------
-   ln_rhg_EVP       = .true.          !  EVP rheology
-      ln_aEVP       = .true.          !     adaptive rheology (Kimmritz et al. 2016 & 2017)
-      rn_creepl     =   2.0e-9        !     creep limit [1/s]
-      rn_ecc        =   2.0           !     eccentricity of the elliptical yield curve          
-      nn_nevp       = 120             !     number of EVP subcycles                             
-      rn_relast     =   0.333         !     ratio of elastic timescale to ice time step: Telast = dt_ice * rn_relast 
-                                      !        advised value: 1/3 (rn_nevp=120) or 1/9 (rn_nevp=300)
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namforcing
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namforcing	(revision 10999)
+++ 	(revision )
@@ -1,13 +1,0 @@
-!------------------------------------------------------------------------------
-&namforcing     !   Ice surface forcing
-!------------------------------------------------------------------------------
-   rn_cio           =   5.0e-03       !  ice-ocean drag coefficient (-)
-   rn_blow_s        =   0.66          !  mesure of snow blowing into the leads
-                                      !     = 1 => no snow blowing, < 1 => some snow blowing
-   nn_flxdist       =  -1             !  Redistribute heat flux over ice categories
-                                      !     =-1  Do nothing (needs N(cat) fluxes)
-                                      !     = 0  Average N(cat) fluxes then apply the average over the N(cat) ice
-                                      !     = 1  Average N(cat) fluxes then redistribute over the N(cat) ice using T-ice and albedo sensitivity
-                                      !     = 2  Redistribute a single flux over categories
-   nice_jules       = 0               !  Jules coupling (0=OFF, 1=EMULATED, 2=ACTIVE)
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namini
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namini	(revision 10999)
+++ 	(revision )
@@ -1,25 +1,0 @@
-!------------------------------------------------------------------------------
-&namini         !   Ice initialization
-!------------------------------------------------------------------------------
-   ln_iceini        = .true.          !  activate ice initialization (T) or not (F)
-   ln_iceini_file   = .false.         !  netcdf file provided for initialization (T) or not (F)
-   rn_thres_sst     =   2.0           !  max delta temp. above Tfreeze with initial ice = (sst - tfreeze)
-   rn_hts_ini_n     =   0.3           !  initial real snow thickness (m), North
-   rn_hts_ini_s     =   0.3           !        "            "             South
-   rn_hti_ini_n     =   3.0           !  initial real ice thickness  (m), North
-   rn_hti_ini_s     =   1.0           !        "            "             South
-   rn_ati_ini_n     =   0.9           !  initial ice concentration   (-), North
-   rn_ati_ini_s     =   0.9           !        "            "             South
-   rn_smi_ini_n     =   6.3           !  initial ice salinity     (g/kg), North
-   rn_smi_ini_s     =   6.3           !        "            "             South
-   rn_tmi_ini_n     = 270.            !  initial ice/snw temperature (K), North
-   rn_tmi_ini_s     = 270.            !        "            "             South
-
-   sn_hti = 'Ice_initialization'    , -12 ,'hti'   ,  .false.  , .true., 'yearly'  , '' , '', ''
-   sn_hts = 'Ice_initialization'    , -12 ,'hts'   ,  .false.  , .true., 'yearly'  , '' , '', ''
-   sn_ati = 'Ice_initialization'    , -12 ,'ati'   ,  .false.  , .true., 'yearly'  , '' , '', ''
-   sn_tsu = 'Ice_initialization'    , -12 ,'tsu'   ,  .false.  , .true., 'yearly'  , '' , '', ''
-   sn_tmi = 'Ice_initialization'    , -12 ,'tmi'   ,  .false.  , .true., 'yearly'  , '' , '', ''
-   sn_smi = 'Ice_initialization'    , -12 ,'smi'   ,  .false.  , .true., 'yearly'  , '' , '', ''
-   cn_dir='./'
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namitd
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namitd	(revision 10999)
+++ 	(revision )
@@ -1,9 +1,0 @@
-!------------------------------------------------------------------------------
-&namitd         !   Ice discretization
-!------------------------------------------------------------------------------
-   ln_cat_hfn       = .true.          !  ice categories are defined by a function following rn_himean**(-0.05)
-      rn_himean     =   2.0           !  expected domain-average ice thickness (m)
-   ln_cat_usr       = .false.         !  ice categories are defined by rn_catbnd below (m)
-      rn_catbnd     =   0.,0.45,1.1,2.1,3.7,6.0  
-   rn_himin         =   0.1           !  minimum ice thickness (m) used in remapping
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/nampar
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/nampar	(revision 10999)
+++ 	(revision )
@@ -1,10 +1,0 @@
-!------------------------------------------------------------------------------
-&nampar         !   Generic parameters
-!------------------------------------------------------------------------------
-   jpl              =   5             !  number of ice  categories
-   nlay_i           =   2             !  number of ice  layers
-   nlay_s           =   1             !  number of snow layers (only 1 is working)
-   nn_virtual_itd   =   0             !  virtual ITD mono-category parameterizations (1-3 => jpl = 1 only) or not (0)
-                                      !     2: activate enhanced thermal conductivity only --- temporary option
-                                      !     3: activate virtual thin ice melting only      ---  temporary option
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namsbc
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namsbc	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namsbc	(revision 11422)
@@ -0,0 +1,14 @@
+!------------------------------------------------------------------------------
+&namsbc         !   Ice surface boundary conditions
+!------------------------------------------------------------------------------
+   rn_cio           =   5.0e-03       !  ice-ocean drag coefficient (-)
+   rn_blow_s        =   0.66          !  mesure of snow blowing into the leads
+                                      !     = 1 => no snow blowing, < 1 => some snow blowing
+   nn_flxdist       =  -1             !  Redistribute heat flux over ice categories
+                                      !     =-1  Do nothing (needs N(cat) fluxes)
+                                      !     = 0  Average N(cat) fluxes then apply the average over the N(cat) ice
+                                      !     = 1  Average N(cat) fluxes then redistribute over the N(cat) ice using T-ice and albedo sensitivity
+                                      !     = 2  Redistribute a single flux over categories
+   ln_cndflx        = .false.         !  Use conduction flux as surface boundary conditions (i.e. for Jules coupling)
+      ln_cndemulate = .false.         !     emulate conduction flux (if not provided in the inputs)
+/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namthd
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namthd	(revision 10999)
+++ 	(revision )
@@ -1,8 +1,0 @@
-!------------------------------------------------------------------------------
-&namthd         !   Ice thermodynamics
-!------------------------------------------------------------------------------
-   ln_icedH         = .true.          !  activate ice thickness change from growing/melting (T) or not (F)
-   ln_icedA         = .true.          !  activate lateral melting param. (T) or not (F)
-   ln_icedO         = .true.          !  activate ice growth in open-water (T) or not (F)
-   ln_icedS         = .true.          !  activate brine drainage (T) or not (F)
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namthd_da
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namthd_da	(revision 10999)
+++ 	(revision )
@@ -1,11 +1,0 @@
-!------------------------------------------------------------------------------
-&namthd_da      !   Ice lateral melting
-!------------------------------------------------------------------------------
-   rn_beta          =   1.0           !  coef. beta for lateral melting param. Recommended range=[0.8-1.2]
-                                      !   => decrease = more melt and melt peaks toward higher concentration (A~0.5 for beta=1 ; A~0.8 for beta=0.2)
-                                      !      0.3 = best fit for western Fram Strait and Antarctica
-                                      !      1.4 = best fit for eastern Fram Strait      
-   rn_dmin          =   8.            !  minimum floe diameter for lateral melting param. Recommended range=[6-10]
-                                      !   => 6  vs 8m = +40% melting at the peak (A~0.5)
-                                      !      10 vs 8m = -20% melting
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namthd_do
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namthd_do	(revision 10999)
+++ 	(revision )
@@ -1,9 +1,0 @@
-!------------------------------------------------------------------------------
-&namthd_do      !   Ice growth in open water
-!------------------------------------------------------------------------------
-   rn_hinew         =   0.1           !  thickness for new ice formation in open water (m), must be larger than rn_hnewice
-   ln_frazil        = .false.         !  Frazil ice parameterization (ice collection as a function of wind)
-      rn_maxfraz    =   1.0           !     maximum fraction of frazil ice collecting at the ice base
-      rn_vfraz      =   0.417         !     thresold drift speed for frazil ice collecting at the ice bottom (m/s)
-      rn_Cfraz      =   5.0           !     squeezing coefficient for frazil ice collecting at the ice bottom
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namthd_pnd
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namthd_pnd	(revision 10999)
+++ 	(revision )
@@ -1,10 +1,0 @@
-!------------------------------------------------------------------------------
-&namthd_pnd     !   Melt ponds
-!------------------------------------------------------------------------------
-   ln_pnd_H12       = .false.         !  activate evolutive melt ponds (from Holland et al 2012)
-      ln_pnd_fwb    = .false.         !     melt ponds store freshwater or not
-   ln_pnd_CST       = .false.         !  activate constant melt ponds
-      rn_apnd       =   0.2           !     prescribed pond fraction, at Tsu=0
-      rn_hpnd       =   0.05          !     prescribed pond depth, at Tsu=0
-   ln_pnd_alb       = .false.         !  melt ponds affect albedo or not
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namthd_sal
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namthd_sal	(revision 10999)
+++ 	(revision )
@@ -1,15 +1,0 @@
-!------------------------------------------------------------------------------
-&namthd_sal     !   Ice salinity
-!------------------------------------------------------------------------------
-   nn_icesal        =   2             !  ice salinity option
-                                      !     1: constant ice salinity (S=rn_icesal)
-                                      !     2: varying salinity parameterization S(z,t)
-                                      !     3: prescribed salinity profile S(z), Schwarzacher, 1959
-   rn_icesal        =   4.            !    (nn_icesal=1) ice salinity (g/kg)
-   rn_sal_gd        =   5.            !  restoring ice salinity, gravity drainage (g/kg)
-   rn_time_gd       =   1.73e+6       !  restoring time scale, gravity drainage  (s)
-   rn_sal_fl        =   2.            !  restoring ice salinity, flushing (g/kg)
-   rn_time_fl       =   8.64e+5       !  restoring time scale, flushing (s)
-   rn_simax         =  20.            !  maximum tolerated ice salinity (g/kg)
-   rn_simin         =   0.1           !  minimum tolerated ice salinity (g/kg)
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namthd_zdf
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namthd_zdf	(revision 10999)
+++ 	(revision )
@@ -1,10 +1,0 @@
-!------------------------------------------------------------------------------
-&namthd_zdf     !   Ice heat diffusion
-!------------------------------------------------------------------------------
-   ln_zdf_BL99      = .true.          !  Heat diffusion follows Bitz and Lipscomb 1999
-   ln_cndi_U64      = .false.         !  sea ice thermal conductivity: k = k0 + beta.S/T            (Untersteiner, 1964)
-   ln_cndi_P07      = .true.          !  sea ice thermal conductivity: k = k0 + beta1.S/T - beta2.T (Pringle et al., 2007)
-   rn_cnd_s         =   0.31          !  thermal conductivity of the snow (0.31 W/m/K, Maykut and Untersteiner, 1971)
-                                      !     Obs: 0.1-0.5 (Lecomte et al, JAMES 2013)
-   rn_kappa_i       =   1.0           !  radiation attenuation coefficient in sea ice [1/m]
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/abstract_foreword.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/abstract_foreword.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/abstract_foreword.tex	(revision 11422)
@@ -0,0 +1,44 @@
+
+\documentclass[../main/SI3_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Abstract
+% ================================================================
+
+\chapter*{Abstract}
+
+SI$^3$ (Sea Ice modelling Integrated Initiative) is the sea ice engine of NEMO (Nucleus for European Modelling of the Ocean). It is adapted to regional and global sea ice and climate problems. It is intended to be a flexible tool for studying sea ice and its interactions with the other components of the Earth System over a wide range of space and time scales. SI$^3$ is based on the Arctic Ice Dynamics Joint EXperiment (AIDJEX) framework \citep{coon_1974}, combining the ice thickness distribution framework, the conservation of horizontal momentum, an elastic-viscous plastic rheology, and energy-conserving halo-thermodynamics. Prognostic variables are the two-dimensional horizontal velocity field, ice volume, area, enthalpy, salt content, snow volume and enthalpy. In the horizontal direction, the model uses a curvilinear orthogonal grid. In the vertical direction, the model uses equally-spaced layers. In thickness space, the model uses thickness categories with prescribed boundaries. Various physical and numerical choices are available to describe sea ice physics. SI$^3$ is interfaced with the NEMO ocean engine, and, via the OASIS coupler, with several atmospheric general circulation models. It also supports two-way grid embedding via the AGRIF software.
+
+%\vspace{-40pt}
+
+{\small
+} 
+
+% ================================================================
+% Disclaimer
+% ================================================================
+\chapter*{Disclaimer}
+
+Like all components of NEMO, the sea ice component is developed under the \href{http://www.cecill.info/}{CECILL license}, 
+which is a French adaptation of the GNU GPL (General Public License). Anyone may use it 
+freely for research purposes, and is encouraged to communicate back to the NEMO team 
+its own developments and improvements. The model and the present document have been 
+made available as a service to the community. We cannot certify that the code and its manual 
+are free of errors. Bugs are inevitable and some have undoubtedly survived the testing phase. 
+Users are encouraged to bring them to our attention. The authors assume no responsibility 
+for problems, errors, or incorrect usage of NEMO.
+
+\vspace{1cm}
+SI3 reference in papers and other publications is as follows:
+\vspace{0.5cm}
+
+The NEMO Sea Ice Working Group, 2018: SI$^3$ -- Sea Ice modelling Integrated Initiative -- The NEMO Sea Ice Engine, \textit{Note du P\^ole de mod\'{e}lisation}, Institut Pierre-Simon Laplace (IPSL), France, 
+No XX, ISSN No 1288-1619.\\
+
+\vspace{0.5cm}
+Additional information can be found on \href{http://www.nemo-ocean.eu/}{www.nemo-ocean.eu}.
+\vspace{0.5cm}
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_bdy_agrif.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_bdy_agrif.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_bdy_agrif.tex	(revision 11422)
@@ -0,0 +1,16 @@
+\documentclass[../main/SI3_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 11 - BDY and AGRIF with SI$^3$
+% ================================================================
+
+\chapter{BDY and AGRIF with SI$^3$}
+\label{chap:REG}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_domain.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_domain.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_domain.tex	(revision 11422)
@@ -0,0 +1,106 @@
+
+\documentclass[../main/SI3_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 2 Ñ Domain
+% ================================================================
+
+\chapter{Time, space and thickness space domain}
+\label{chap:DOM}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+Having defined the model equations in previous Chapter, we need now to choose the numerical discretization.  In the present chapter, we provide a general description of the SI$^3$ discretization strategy, in terms of time, space and thickness, which is considered as an extra independent variable. 
+
+Sea ice state variables are typically expressed as:
+\begin{equation}
+X(ji,jj,\textcolor{gray}{jk},jl).
+\end{equation}
+$ji$ and $jj$ are x-y spatial indices, as in the ocean. $jk=1, ..., nlay\_i$ corresponds to the vertical coordinate system in sea ice (ice layers), and only applies to vertically-resolved quantities (ice enthalpy and salinity). $jl=1, ..., jpl$ corresponds to the ice categories, discretizing thickness space.
+
+\section{Time domain}
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Time Stepping
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=6cm,angle=-00]{time_stepping}
+\caption{Schematic representation of time stepping in SI$^3$, assuming $nn\_fsbc=5$.}
+\label{ice_scheme}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+The sea ice time stepping is synchronized with that of the ocean. Because of the potentially large numerical cost of sea ice physics, in particular rheology, SI$^3$ can be called every nn\_fsbc time steps (namsbc in \textit{namelist\_ref}). The sea ice time step is therefore $rdt\_ice = rdt * nn\_fsbc$. In terms of quality, the best value for \textit{nn\_fsbc} is 1, providing full consistency between sea ice and oceanic fields. Larger values (typically 2 to 5) can be used but numerical instabilities can appear because of the progressive decoupling between the state of sea ice and that of the ocean, hence changing $nn\_fsbc$ must be done carefully.
+
+Ice dynamics (rheology, advection, ridging/rafting) and thermodynamics are called successively. To avoid pathological situations, thermodynamics were chosen to be applied on fields that have been updated by dynamics, in a somehow semi-implicit procedure.
+
+There are a few iterative / subcycling procedures throughout the code, notably for rheology, advection, ridging/ rafting and the diffusion of heat. In some cases, the arrays at the beginning of the sea ice time step are required. Those are referred to as $X\_b$.
+
+\section{Spatial domain}
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIGx : Vertical grid
+%
+%
+\begin{figure}[!ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=10cm,angle=-00]{thermogrid.eps}
+\caption{\footnotesize{Vertical grid of the model, used to resolve vertical temperature and salinity profiles}}\label{fig_dom_icelayers}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+The horizontal indices $ji$ and $jj$ are handled as for the ocean in NEMO, assuming C-grid discretization and in most cases a finite difference expression for scale factors.
+
+The vertical index $jk=1, ..., nlay\_i$ is used for enthalpy (temperature) and salinity. In each ice category, the temperature and salinity profiles are vertically resolved over $nlay\_i$ equally-spaced layers. The number of snow layers can currently only be set to $nlay\_s=1$ (Fig. \ref{fig_dom_icelayers}).
+
+To increase numerical efficiency of the code, the two horizontal dimensions of an array $X(ji,jj,jk,jl)$ are collapsed into one (array $X\_1d(ji,jk,jl)$) for thermodynamic computations, and re-expanded afterwards.
+
+\nlst{nampar}
+
+\section{Thickness space domain}
+
+\nlst{namitd}
+
+Thickness space is discretized using $jl=1, ..., jpl$ thickness categories, with prescribed boundaries $hi\_max(jl-1),hi\_max(jl)$. Following \cite{lipscomb_2001}, ice thickness can freely evolve between these boundaries. The number of ice categories $jpl$ can be adjusted from the namelist ($nampar$).
+
+There are two means to specify the position of the thickness boundaries of ice categories. The first option (ln\_cat\_hfn) is to use a fitting function that places the category boundaries between 0 and 3$\overline h$, with $\overline h$ the expected mean ice thickness over the domain (namelist parameter rn\_himean), and with a greater resolution for thin ice (Fig. \ref{fig_dom_icecats}). More specifically, the upper limits for ice in category $jl=1, ..., jpl-1$ are:
+\begin{eqnarray} 
+hi\_max(jl) = \biggr ( \frac{jl \cdot (3\overline h + 1 )^{\alpha}}{ (jpl-jl)(3 \overline h + 1)^{\alpha} + jl }\biggr )^{\alpha^{-1}} - 1,
+\end{eqnarray}
+with $hi\_max(0)$=0 m and $\alpha = 0.05$. The last category has no upper boundary, so that it can contain arbitrarily thick ice.
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIGx : Ice categories
+%
+%
+\begin{figure}[!ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=6cm,angle=-00]{ice_cats.eps}
+\caption{\footnotesize{Boundaries of the model ice thickness categories (m) for varying number of categories and prescribed mean thickness ($\overline h$). The formerly used $tanh$ formulation is also depicted.}}\label{fig_dom_icecats}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+The other option (ln\_cat\_usr) is to specify category boundaries by hand using rn\_catbnd. The first category must always be thickner than rn\_himin (0.1 m by default).
+
+The choice of ice categories is important, because it constraints the ability of the model to resolve the ice thickness distribution. The latest study \citep{massonnet_2018} recommends to use at least 5 categories, which should include one thick ice with lower bounds at $\sim$4 m and $\sim$2 m for the Arctic and Antarctic, respectively, for allowing the storage of deformed ice.
+
+With a fixed number of cores, the cost of the model linearly increases with the number of ice categories. Using $jpl=1$ single ice category is also much cheaper than with 5 categories, but seriously deteriorates the ability of the model to grow and melt ice. Indeed, thin ice thicknes faster than thick ice, and shrinks more rapidly as well. When nn\_virtual\_itd=1 ($jpl$ = 1 only), two parameterizations are activated to compensate for these shortcomings. Heat conduction and areal decay of melting ice are adjusted to closely approach the 5 categories case.
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_dynamics.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_dynamics.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_dynamics.tex	(revision 11422)
@@ -0,0 +1,35 @@
+
+\documentclass[../main/SI3_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 3 Ñ Ice dynamics
+% ================================================================
+
+\chapter{Ice dynamics}
+\label{chap:DYN}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+In this chapter, we describe how the momentum equation is solved.
+
+I guess we could be brief. Gurvan and Clem should take the lead to write this.
+
+1) aEVP approach, revisited by Bouillon et al (2013).
+
+2) Short description of the numerical method. NEMO scale factors.
+
+3) Landfast ice option
+
+4) Boundary conditions (free-slip, no-slip, ...)
+
+4) Practical use of namelist parameters (nevp, telast, ...).
+
+\end{document}
+
+
+
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_interfaces.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_interfaces.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_interfaces.tex	(revision 11422)
@@ -0,0 +1,30 @@
+\documentclass[../main/SI3_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 8 Ñ Interfaces
+% ================================================================
+
+\chapter{Ice-atmosphere and ice-ocean interfaces}
+\label{chap:INT}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+In this chapter, we give information on the representation of interfaces.
+
+\section{Ice-ocean interface}
+
+\section{Ice-atmosphere interface}
+
+Drags?
+
+Blowing snow parameter
+
+Flux redistributor
+
+Jules coupling
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_miscellaneous.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_miscellaneous.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_miscellaneous.tex	(revision 11422)
@@ -0,0 +1,18 @@
+\documentclass[../main/SI3_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 12 -Miscellaneous
+% ================================================================
+
+\chapter{Miscellaneous topics}
+\label{chap:MIS}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+getting started, namelists, configs, ...
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_model_basics.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_model_basics.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_model_basics.tex	(revision 11422)
@@ -0,0 +1,457 @@
+
+\documentclass[../main/SI3_manual]{subfiles}
+
+\begin{document}
+% ================================================================
+% Chapter 1 Ñ Model Basics
+% ================================================================
+
+\chapter{Model Basics}
+\label{chap:MB}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+%-------------------------------------------------------------------------------------------------------------------------
+%
+% 2.1 Assumptions
+\section{Rationale and assumptions}
+%
+%-------------------------------------------------------------------------------------------------------------------------
+\begin{itemize}
+\item Separation of horizontal dynamics and vertical thermodynamics;
+\item Dynamics: sea ice is a viscous-plastic continuum;
+\item Thermodynamics: sea ice is a mushy layer covered by snow
+\item Subgrid-scale physics
+\end{itemize}
+
+\subsection{Scales, thermodynamics and dynamics}
+Because sea ice is much wider -- $\mathcal{O}$(100-1000 km) -- than thick -- $\mathcal{O}$(1 m) -- ice drift can be considered as purely horizontal: vertical motions around the hydrostatic equilibrium position are negligible. The same scaling argument justifies the assumption that heat exchanges are purely vertical\footnote{The latter assumption is probably less valid, because the horizontal scales of temperature variations are $\mathcal{O}$(10-100 m)}. It is on this basis that thermodynamics and dynamics are separated and rely upon different frameworks and sets of hypotheses: thermodynamics use the ice thickness distribution \citep{thorndike_1975} and the mushy-layer \citep{worster_1992} frameworks, whereas dynamics assume continuum mechanics \citep[e.g.,][]{lepparanta_2011}. Thermodynamics and dynamics interact by two means: first, advection impacts state variables; second, the horizontal momentum equation depends, among other things, on the ice state.
+
+\subsection{Subgrid scale variations}
+
+Sea ice properties -- in particular ice thickness -- feature important changes at horizontal scales $\mathcal{O}$(1m) \citep{thorndike_1975}. An explicit representation of these variations is not and will not be -- at least in the next twenty years or so -- accessible to large-scale sea ice models. Yet important features, such as energy exchanges through the ice, quite non-linearly depend on ice thickness \citep{maykut_1986}; whereas ice motion depends on the presence of open water, thin and thick ice at the very least, suggesting that subgrid-scale variations in ice properties must be accounted for, at least in a statistical fashion \citep{maykut_1973}. 
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Ice scheme
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=10cm,angle=-00]{ice_scheme}
+\caption{Representation of the ice pack, using multiple categories with specific ice concentration ($a_l, l=1, 2, ..., L$), thickness ($h^i_l$), snow depth ($h^s_l$), vertical temperature and salinity profiles ($T^i_{kl}$, $S^{*}_{kl}$) and a single ice velocity vector ($\mathbf{u}$).}
+\label{ice_scheme}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+The \textit{multi-category} framework \citep{maykut_1973} addresses this issue by treating the ice thickness as an independent variable next to spatial coordinates and time, and introducing a thickness distribution\footnote{$g(h)$, termed the \textit{ice thickness distribution} is the density of probability of ice thickness \citep{thorndike_1975}.} $g(h)$ as the main prognostic model field. In the discrete world, the thickness distribution is converted into $L$ thickness categories. Ice thickness categories occupy a fraction of each grid cell, termed ice concentration ($a_l, l=1, 2, ..., L$), with specific thickness and properties. 
+
+The \textit{single-category} framework \citep{hibler_1979} tackles the subgrid-scale issue by drastically simplifying the ice thickness distribution. The grid cell is divided into open water and sea ice characterized by a single ice concentration $A$ and mean thickness $H$. Single-category models (in particular LIM2) typically add parameterizations to represent the effects of unresolved ice thickness distribution on ice growth and melt \citep[see, e.g.][]{mellor_1989,fichefet_1997}.
+
+SI$^3$ provides the choice between either a multi- or a single-category framework. The default mode is multi-category. The single-category mode can be activated by setting the number of categories ($jpl=1$) and by activating the virtual thickness distribution parameterizations (nn\_monocat=1).
+
+\subsection{Thermodynamic formulation}
+
+%
+%--------------------------------------------------------------------------------------------------------------------
+%
+% TABLE x Physical constants
+%
+%
+\begin{table}[ht]
+\begin{footnotesize}
+\caption{Thermodynamic constants of the model.}
+\begin{center}
+\begin{tabular}{@{}llccl}\hline
+ & Description & Value & Units & Ref \\ \hline
+$c_i$ (cpic) & Pure ice specific heat & 2067 & J/kg/K & ? \\
+$c_w$ (rcp) & Seawater specific heat & 3991 & J/kg/K & \cite{teos-10_2010} \\
+$L$ (lfus) & Latent heat of fusion (0$^\circ$C) & 334000 & J/kg/K & \cite{bitz_1999} \\
+$\rho_i$ (rhoic) & Sea ice density & 917 & kg/m$^3$ & \cite{bitz_1999} \\
+$\rho_s$ (rhosn) & Snow density & 330 & kg/m$^3$ & \cite{maykut_1971} \\
+$\mu$ (tmut) & Linear liquidus coefficient & 0.054 & $^\circ$C/(g/kg) & \cite{assur_1958} \\
+\hline
+\end{tabular}
+\end{center}
+\label{PhysicalConstants_table}
+\end{footnotesize}
+\end{table}
+%
+%--------------------------------------------------------------------------------------------------------------------
+%
+
+Ice thermodynamics are formulated assuming that sea ice is covered by snow. Within each thickness category, both snow and sea ice are horizontally uniform, hence each thickness category has a specific ice thickness ($h_i^l$) and snow depth ($h_s^l$). Snow is assumed to be fresh, with constant density and thermal conductivity. Sea ice is assumed to be a \textit{mushy layer}\footnote{Mushy layers are two-phase, two-component porous media.} \citep{worster_1992} of constant density, made of pure ice and brine in thermal equilibrium, related by a linear liquidus relationship \citep{bitz_1999}. A vertically-averaged bulk salinity $S_l$ uniquely characterizes brine fraction for each thickness category, and changes through  time from a simple parametrization of brine drainage. The linear vertical salinity profile ($S^*_{kl}$) is reconstructed from the vertical mean \citep{vancoppenolle_2009}. The diffusion of heat affects the vertical temperature profile, discretized on a unique layer of snow and multiple ice layers (typically 2-5) for each category, whereas thermal properties depend on local brine fraction. Growth and melt rates are computed, also for each ice category. The choice of the main thermodynamic constants  is described in Tab. \ref{PhysicalConstants_table}.
+
+
+
+%
+%--------------------------------------------------------------------------------------------------------------------
+%
+% TABLE x Global variables
+%
+%
+\begin{table}[ht]
+\begin{footnotesize}
+\caption{LIM global variables.}
+\begin{center}
+\begin{tabular}{@{}llcc}\hline
+Symbol   & Description & Units & Code name \\ \hline
+$\mathbf{u}$ & Sea ice velocity & [$m.s^{-1}$] & \textit{u\_ice, v\_ice (ji,jj)} \\
+$\mathbf{\sigma}$ & Stress tensor & [$Pa.m$] & \textit{stress1\_i, stress2\_i} \\
+ & & & \textit{stress12\_i (ji,jj)} \\
+$a_l$ & Concentration of sea ice in category $l$ & [-] & \textit{a\_i(ji,jj,jl)} \\
+$v^i_l$ & Volume of sea ice per unit area in category $l$ & [$m$] & \textit{v\_i(ji,jj,jl)} \\
+$v^s_l$ & Volume of snow per unit area in category $l$ & [$m$] & \textit{v\_s(ji,jj,jl)} \\
+$e^i_{kl}$ & Sea ice enthalpy per unit area in layer $k$ and category $l$ & [$J.m^{-2}$] & \textit{e\_i(ji,jj,jk,jl)} \\
+$e^s_{l}$ & Snow enthalpy per unit area in category $l$ & [$J.m^{-2}$] & \textit{e\_s(ji,jj,jl)} \\
+$M^s_l$ & Sea ice salt content in category $l$ & [$g/kg.m$] & \textit{smv\_i(ji,jj,jl)}\\
+%$O_l$ & Sea ice age content in category $l$ & $[days.m]$ \\
+\hline
+\end{tabular}
+\end{center}
+\label{GVariables_table}
+\end{footnotesize}
+\end{table}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+ Temperature, salinity, ice thickness, and snow depth are not extensive variables and therefore not conservative. Hence, conservative, extensive variables, must be introduced to ensure mass, salt and energy conservation. There are several back-and-forth conversions from extensive (conservative) state variables (see Table \ref{GVariables_table}) to intensive state variables of practical use (Table \ref{IVariables_table}).
+ 
+ %--------------------------------------------------------------------------------------------------------------------
+%
+% TABLE x Equivalent variables
+%
+%
+\begin{table}[ht]
+\begin{footnotesize}
+\caption{Intensive variables of practical use.}
+\begin{center}
+\begin{tabular}{@{}llcc}\hline
+Symbol   & Description & Units \\ \hline
+$h^i_l=v^i_l/g^i_l$ & Ice thickness & [$m$] \\
+$h^s_l=v^s_l/g^i_l$ & Snow depth & [$m$] \\
+$q^i_{m,kl}=e^i_{l,k}/(h^i_l/N)$ & Ice specific enthalpy & [$J.kg^{-1}$]\\
+$q^s_{m,l}=e^s_{l}/h^s_l$ & Snow specific enthalpy & [$J.kg^{-1}$] \\
+$T^i_{kl}=T(q^i_{kl})$ & Ice temperature & [$K$] \\
+$T^s_{l} =T(q^s_{l}) $ & Snow temperature & [$K$] \\
+$\overline S^i_{l}=M^s_l / v^i_l$ & Vertically-averaged bulk ice salinity & [g/kg] \\
+$S^*_{kl}$ & Depth-dependent ice salinity & [g/kg] \\
+$\phi_{kl}$ & Brine fraction & [-] \\
+%$o^i_{l}=O_l / g^i_l $ & Ice age & [$days$] \\
+\hline
+\end{tabular}
+\end{center}
+\label{IVariables_table}
+\end{footnotesize}
+\end{table}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+\subsection{Dynamic formulation}
+
+The formulation of ice dynamics is based on the continuum approach. The latter holds provided the drift ice particles are much larger than single ice floes, and much smaller than typical gradient scales. This compromise is rarely achieved in practice \citep{lepparanta_2011}. Yet the continuum approach generates a convenient momentum equation for the horizontal ice velocity vector $\mathbf{u}=(u,v)$, which can be solved with classical numerical methods (here, finite differences on the NEMO C-grid). The most important term in the momentum equation is internal stress. We follow the viscous-plastic (VP) rheological framework \citep{hibler_1979}, assuming that sea ice has no tensile strength but responds to compressive and shear deformations in a plastic way. In practice, the elastic-viscous-plastic (EVP) technique of  \citep{bouillon_2013} is used, more convient numerically than VP.  It is well accepted that the VP rheology and its relatives are the minimum complexity to get reasonable ice drift patterns \citep{kreyscher_2000}, but fail at generating the observed deformation patterns \citep{girard_2009}. This is a long-lasting problem: what is the ideal rheological model for sea ice and how it should be applied are still being debated \citep[see, e.g.][]{weiss_2013}. 
+
+%-------------------------------------------------------------------------------------------------------------------------
+%
+\section{Thickness distribution framework}
+%
+%-------------------------------------------------------------------------------------------------------------------------
+
+We first present the essentials of the thickness distribution framework \citep{thorndike_1975}. Consider a given region of area $R$ centered at spatial coordinates $(\mathbf{x})$ at a given time $t$. $R$ could be e.g. a model grid cell. The ice thickness distribution $g(\mathbf{x},t, h)$ is introduced as follows:
+\begin{linenomath}
+\begin{align}
+g(h) &= \lim_{dh \to 0} \frac{dA(h,h+dh)}{dh},
+\end{align}
+\end{linenomath}
+where $dA(h,h+dh)$ is the surface fraction of all parts of $R$ with ice thickness between $h$ and $h+dh$. Using this definition, the spatial structure of ice thickness is lost (see Fig. \ref{fig_g_h}), and $h$ becomes an extra independent variable, next to spatial coordinates and time, that can be thought as random. $g$ is by definition normalized to 1. The conservation of area, expressed in terms of $g(h)$, is given by \citep{thorndike_1975}: 
+\begin{linenomath}
+\begin{align}
+\frac{\partial g}{\partial t} = - \nabla .(g \mathbf{u}) - \frac{\partial}{\partial h} (f g) + \psi,
+\label{eq:gt}
+\end{align}
+\end{linenomath}
+where the terms on the right hand side refer to horizontal transport, thermodynamic transport in thickness space ($f$, m/s is the growth/melt rate), and mechanical redistribution rate, e.g. by ridging and rafting, where $\psi$ must conserve ice area and volume by construction.
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Ice thickness distribution
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=6cm,angle=-00]{g_h}
+\caption{Representation of the relation between real thickness profiles and the ice thickness distribution function $g(h)$}
+\label{fig_g_h}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+In numerical implementations, the thickness distribution is discretized into several thickness categories, with specific ice concentration $a_l$ and ice volume per area $v_l^i$:
+\begin{linenomath}
+\begin{align}
+a_l &= \int _{H^*_{l-1}}^{H^*_l} dh \cdot g(h) , \\
+v_l^i &= \int _{H^*_{l-1}}^{H^*_l} dh \cdot h \cdot g(h).
+\end{align}
+\end{linenomath}
+Ice volume per area is the extensive counterpart for ice thickness, connected with volume through $h_l^i = v_l^i / a_l$. Evolution equations for extensive variables can be readily derived from equation \ref{eq:gt} by integration between thickness boundaries of the $l^{th}$ category \citep{bitz_2001}. This applies to all model extensive variables (see Table \ref{GVariables_table}). For ice area, this reads:
+\begin{linenomath}
+\begin{align}
+\frac{\partial a_l}{\partial t} = - \mathbf{\nabla} \cdot (a_l \mathbf{u}) + \Theta^a_l + \int_{H^*_{l-1}}^{H^*_l} dh \psi.
+\label{eq:gt}
+\end{align}
+\end{linenomath}
+wher $\Theta^a_l$ refers to the effect of thermodynamics. Enthalpy is a particular case because it also has a vertical depth dependence $z$, which corresponds to $K$ vertical layers of equal thickness. The solution adopted here, following from \cite{zhang_2001}, is that enthalpy from the individual layers are conserved separately. This is a practical solution, for lack of better.
+
+One of the major actions of LIM is to resolve conservation equations for all extensive variables that characterize the ice state.  Let us now connect this detailed information with classical sea ice fields. The ice concentration $A$ and the ice volume per area\footnote{Ice volume per area is equivalent to the grid-cell averaged ice thickness.} $V_i$ (m) directly derive from $g$: 
+\begin{linenomath}
+\begin{align}
+ A(\mathbf{x},t) &=\int_{0^+}^{\infty} dh \cdot g(h,\mathbf{x},t) \sim A_{ij} = \sum_{l=1}^L a_{ijl}, & \\
+ V_i(\mathbf{x},t)&=\int_{0}^{\infty} dh \cdot g(h,\mathbf{x},t) \cdot h \sim V^i_{ij} = \sum_{l=1}^L v^i_{ijl}. & \\
+\end{align}
+\end{linenomath}
+where the $0^+$ boundary implies that the means exclude open water. The mean ice thicknesses $H_i$ (m) is:
+\begin{linenomath}
+\begin{align}
+H_i = V_i/A,
+\end{align}
+\end{linenomath}
+whereas the open water fraction is simply $1-A$.
+
+\section{Governing equations}
+
+Let us now readily present the set of the LIM "governing" equations in the framework of the assumptions developed above. The conservation of horizontal momentum reads:
+\begin{linenomath}
+\begin{align}
+m \frac{\partial \mathbf{u}} {\partial t} & = \mathbf{\nabla}\cdot\mathbf{\sigma} +A \left(\mathbf{\tau}_{a}+\mathbf{\tau}_{w}\right) - m f \mathbf{k} \times \mathbf{u} - m g \mathbf{\nabla}{\eta},
+\label{a}
+\end{align}
+\end{linenomath}
+where $m=\rho_i V_i + \rho_s V_s $ is the ice and snow mass per unit area, $\mathbf{u}$ is the ice velocity, $\mathbf{\sigma}$ is the internal stress tensor, $\mathbf{\tau}_a$ and $\mathbf{\tau}_w$ are the air and ocean stresses, respectively, $f$ is the Coriolis parameter, $\mathbf{k}$ is a unit vector pointing upwards, $g$ is the gravity acceleration and $\eta$ is the ocean surface elevation. The EVP approach used in LIM \citep{bouillon_2013} gives the stress tensor as a function of the strain rate tensor $\dot{\mathbf{\epsilon}}$ and some of the sea ice state variables:
+\begin{linenomath}
+\begin{align}
+\mathbf{\sigma} & = \mathbf{\sigma} (\dot{ \mathbf{\epsilon}}, \text{ice state}).
+\end{align}
+\end{linenomath}
+To the exception of velocity and internal stress, all extensive variables in Table \ref{GVariables_table} follow a conservation equation of the form:
+\begin{linenomath}
+\begin{align}
+\frac{\partial X}{\partial t} & = - \nabla .(\mathbf{u}X) + \Theta^X + \Psi^X,
+\label{eq:Xt}
+\end{align}
+\end{linenomath}
+including the effets of transport, thermodynamics ($\Theta^X$) and mechanical redistribution ($\Psi^X$). Solving these $jpl.(4+2.jpk)$ equations gives the temporal evolution of $\mathbf{u}$, $\mathbf{\sigma}$ and the rest of the global (extensive) variables listed in Table \ref{GVariables_table}.
+
+\section{Ice Dynamics}
+
+Dynamical processes include the conservation of momentum, rheology, transport and mechanical redistribution.
+To resolve the momentum equation, atmospheric stress is taken either as forcing or from an atmospheric model, oceanic stress and sea surface elevation from the ocean model, the Coriolis term is trivial. The last term, the divergence of the internal stress tensor $\sigma$, is the most critical term in the momentum equation and requires a rheological formulation. The EVP approach used in LIM gives the stress tensor components as \citep{bouillon_2013}:
+\begin{linenomath}
+\begin{align}
+\sigma_{ij} & = \frac{P}{2(\Delta + \Delta_{min}) }
+\biggr [ ( \dot{\epsilon}_{kk} - \Delta) \delta_{ij} + \frac{1}{e^2} ( 2 \dot{\epsilon}_{ij} - \dot{\epsilon}_{kk} \delta_{ij} ) \biggr ],
+\end{align}
+\end{linenomath}
+where $\Delta$ is a particular measure of the deformation rate, $\Delta_{min}$ a parameter determining a smooth transition from pure viscous vlow ($\Delta<<\Delta_{min}$) to pure plastic flow ($\Delta >> \Delta_{min}$), and $e$ is a parameter giving the ratio between the maximum compressive stress and twice the maximum shear stress. In the pure plastic regime, the stress principal components should lie on the edge of an elliptical yield curve (Fig. \ref{fig_yield}). In the viscous regime, they are within the ellipse. The ice strength $P$ determines the plastic failure criterion and connects the momentum equation with the state of the sea ice. $P$ is not well constrained and must be parameterized. The heuristic option of \cite{hibler_1979} was here adopted as a reference formulation:
+\begin{linenomath}
+\begin{align}
+P & = P^* V_i e^{-C(1-A)},
+\end{align}
+\end{linenomath}
+where $P^*$ and $C$ are empirical constants (see Table \ref{Modelparameters_table} for the values of the main model parameters).
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Ice thickness distribution
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=6cm,angle=-00]{yield_curve}
+\caption{Elliptical yield curve used in the VP rheologies, drawn in the space of the principal components of the stress tensor ($\sigma_1$ and $\sigma_2$).}
+\label{fig_yield}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+%
+%--------------------------------------------------------------------------------------------------------------------
+%
+% TABLE x Model parameters %
+%
+\begin{table}[ht]
+\begin{footnotesize}
+\caption{Main model parameters.}
+\begin{center}
+\begin{tabular}{@{}llccl}\hline
+ & Description & Value & Units & Ref \\ \hline
+ 
+% Parameters
+$P*$ (rn\_pstar) & ice strength thickness param. & 20000 & N/m2 & - \\
+$C$ (rn\_crhg) & ice strength concentration param. & 20 & - & \citep{hibler_1979} \\
+$H^*$ (rn\_hstar) & maximum ridged ice thickness param. & 25 & m & \citep{lipscomb_2007} \\
+$p$ (rn\_por\_rdg) & porosity of new ridges & 0.3 & - & \citep{lepparanta_1995} \\
+$amax$ (rn\_amax) & maximum ice concentration & 0.999 & - & -\\
+$h_0$ (rn\_hnewice) & thickness of newly formed ice & 0.1 & m & - \\
+ 
+\hline
+\end{tabular}
+\end{center}
+\label{Modelparameters_table}
+\end{footnotesize}
+\end{table}
+%
+%--------------------------------------------------------------------------------------------------------------------
+%
+
+
+Transport connects the horizontal velocity fields and the rest of the ice properties. LIM assumes that the ice properties in the different thickness categories are transported at the same velocity. The scheme of \cite{prather_1986}, based on the conservation of 0, 1$^{st}$ and 2$^{nd}$ order moments in $x-$ and $y-$directions,  is used, with some numerical diffusion if desired. Whereas this scheme is accurate, nearly conservative, it is also quite expensive since, for each advected field, five moments need to be advected, which proves CPU consuming, in particular when multiple categories are used. Other solutions are currently explored.
+
+The dissipation of energy associated with plastic failure under convergence and shear is accomplished by rafting (overriding of two ice plates) and ridging (breaking of an ice plate and subsequent piling of the broken ice blocks into pressure ridges). Thin ice preferentially rafts whereas thick ice preferentially ridges \citep{tuhkuri_2002}. Because observations of these processes are limited, their representation in LIM is rather heuristic. The amount of ice that rafts/ridges depends on the strain rate tensor invariants (shear and divergence) as in \citep{flato_1995}, while the ice categories involved are determined by a participation function favouring thin ice \citep{lipscomb_2007}. The thickness of ice being deformed ($h'$) determines whether ice rafts ($h'<$ 0.75 m) or ridges ($h'>$ 0.75 m), following \cite{haapala_2000}. The deformed ice thickness is $2h'$ after rafting, and is distributed between $2h'$ and $2 \sqrt{H^*h'}$ after ridging, where $H^* = 25$ m \citep{lipscomb_2007}. Newly ridged ice is highly porous, effectively trapping seawater. To represent this, a prescribed volume fraction (30\%) of newly ridged ice \citep{lepparanta_1995} incorporates mass, salt and heat are extracted from the ocean. Hence, in contrast with other models, the net thermodynamic ice production during convergence is not zero in LIM, since mass is added to sea ice during ridging. Consequently, simulated new ridges have high temperature and salinity as observed \citep{hoyland_2002}. A fraction of snow (50 \%) falls into the ocean during deformation.
+
+\section{Ice thermodynamics}
+In this section, we develop the underlying principles of the thermodynamic formulation, summarized in the term $\Theta^X$, where $X$ refers to all extensive state variables. $\Theta^X$ includes the contributions of transport in thickness space and thermodynamic source and sink terms.
+
+\subsection{Transport in thickness space}
+Transport in thickness space describes how vertical growth and melt moves ice state variables among the different thicknesses at a velocity $f(h)$, the net ice growth/melt rate, which needs to be first computed.  In discretized form, this term moves ice properties between neighbouring categories. The linear remapping scheme of \cite{lipscomb_2001} is used. This scheme is semi-lagrangian, second-order, is less diffusive and converges faster than other options.
+
+\subsection{Thermodynamic source and sink terms}
+
+Since heat, salt and mass are strongly inter-dependent for sea ice, the thermodynamic source and sink terms are treated together. They include the changes in extensive sea ice state associated with thermodynamic processes. The latter are separated in two main parts: (i) open water fraction processes, where atmosphere and ocean are in direct interaction; and (ii) vertical ice thermodynamic processes, driven by surface snow/ice-atmosphere and basal ice-ocean exchanges, for each thickness category. For each part, first, the energy available or lost is specified. Then the impact on mass exchanges is evaluated. The latter part requires to specify how sea ice and snow responds to energy supply or loss, which is achieved through the enthalpy formulation.
+
+%\subsubsection{Atmosphere-ice-ocean heat and mass exchanges}
+%
+%The atmosphere-ice heat exchanges are either specified in external files (forcing) or computed from an atmospheric model. The following heat and mass fluxes should be specified:
+%\begin{itemize}
+%\item Net solar flux, for open water ($Q^{sol}$) and ice categories ($Q^{sol,ice}_{l}$);
+%\item Net non-solar flux, for open water ($Q^{nsol}$) and ice categories ($Q^{nsol,ice}_{l}$);
+%\item Solid and liquid precipitation (kg/m$^2$/s).
+%\end{itemize}
+%
+%In terms of mass (freshwater), the ocean gets:
+%\begin{itemize}
+%\item All liquid precipitation;
+%\item The part of solid precipitation that is not intercepted by the ice, accounting for the part that is blown off the sea ice by winds;
+%\item The net melting minus freezing mass flux, as diagnosed from thermodynamic sea ice calculations.
+%\end{itemize}
+%
+%In terms of energy, the ocean gets:
+%\begin{itemize}
+%\item The net atmospheric solar flux, minus what is intercepted by the ice; plus what is transmitted below the ice; 
+%\item The net atmospheric non-solar heat flux, minus what is used by the sea ice; 
+%\item The sensible heat exchange associated with ice-ocean and atmosphere-ocean mass fluxes. 
+%\end{itemize}
+%
+%In terms of salt, the ocean gets the net salt release minus uptake associated with sea ice growth, melt and brine drainage. There is no atmosphere-ocean salt flux.
+
+\subsubsection{Enthalpy formulation}
+
+% Add snow and water
+
+A first overarching aspect of the thermodynamic calculations is the specification of the response of sea ice to energy supply. This is achieved by defining the internal energy (or enthalpy\footnote{Wording it internal energy or enthalpy is equivalent since pressure effects are not considered.}). This ultimately relies on the response of the phase composition to salinity and temperature changes. The enthalpy formulation used in LIM is based on the following assumptions:
+\begin{itemize}
+\item Sea ice is gas-free, composed solely of pure ice and saline brine, characterized by brine fraction $\phi$;
+\item brine and pure ice are in thermodynamic equilibrium;
+\item the salinity-dependence of the freezing point is linear (linear liquidus);
+\item the density of the sea ice (ice+brine) medium is constant ($\rho_i$).
+\end{itemize}
+%In this context, the bulk salinity of a small control sea ice volume is related to the salinity of brine ($S_{br}$):
+%\begin{linenomath}
+%\begin{align}
+%S = \phi S_{br}
+%\label{eq_S_Sbr}
+%\end{align}
+%\end{linenomath}
+%Because of thermal equilibrium and linear liquidus, brine salinity directly depends on local temperature: $T=-\mu S_{br}$. Hence, brine fraction is given by
+%\begin{linenomath}
+%\begin{align}
+%\phi = -\frac{\mu S}{T}.
+%\end{align}
+%\end{linenomath}
+%This equation relates brine fraction to bulk salinity and temperature, which therefore can be seen as the two main state variables in this linear mushy layer formulation for sea ice thermodynamics. 
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Thermal properties
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=8cm,angle=-00]{Thermal_properties}
+\caption{Thermal properties of sea ice vs temperature for different bulk salinities: brine fraction, specific enthalpy, thermal conductivity, and effective specific heat.}
+\label{fig_thermal_properties}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+Based on these, brine fraction reduces to $\phi = -\mu S/T$ (see Fig. \ref{fig_thermal_properties}), where $\mu$ relates the freezing point of brine to salinity, and one can derive the specific enthalpy $q_m(S,T)$, defined as the energy required to warm and melt a unit control volume of sea ice at temperature $T$ (in Celsius) and salinity $S$ until 0$^\circ$ C, taken as a reference zero-energy level \citep{bitz_1999,schmidt_2004}:
+\begin{linenomath}
+\begin{align}
+q_m(S,T) = \biggr [ c_i ( T + \mu S) - L \biggr ( 1 + \frac{\mu S}{T} \biggr ) - c_w \mu S \biggr ]
+\end{align}
+\end{linenomath}
+where $c_i$ is pure ice specific heat, $L$ is latent heat of fusion at 0$^\circ$C, and $c_w$ is water specific heat. The first term expresses the warming of solid ice. The second term expresses internal change in brine fraction, which is often the largest because the Stefan number  ($c_i T/L$) is generally small. The last term gives the warming of the remaining water from $T_{fr} = -\mu S$ until 0$^\circ$C. Similar, but simpler and linear expressions for snow and water can be derived.
+
+The second overarching aspect is that all growth and melt processes must be calculated consistently with the enthalpy formulation. Energetics of phase transitions are handled using the formalism of \cite{schmidt_2004}. For each phase transition, initial and final states (temperature and salinity) are defined, and the ice-to-ocean mass flux to the ice $F_m$ (kg/s) relates to the energy gain or loss $\Delta Q$ through:
+\begin{linenomath}
+\begin{align}
+\Delta Q / \Delta q_m = F_m,
+\label{eq_phasechange}
+\end{align}
+\end{linenomath}
+where $\Delta q_m$ is the change in specific enthalpy involved in the considered phase transition, from initial to final state.
+
+
+\subsubsection{Open water processes}
+
+As part of the sea ice thermodynamic calculations, a heat budget estimate for the uppermost ocean level ($B^{opw}$) must be included, to compute the rate of new ice formation or the contribution of sensible heat to bottom melting. $B^{opw}$ includes:
+\begin{itemize}
+\item the absorption of a fraction $f_1^{qsr}$ of solar radiation (given by radiative transfer component of the ocean model);
+\item the non-solar heat flux absorbed at the surface;
+\item the sensible heat content of precipitation
+\item the sensible heat flux from the ocean to the sea ice ($A.F_w$)
+\end{itemize}
+Other contributions are not assumed not to contribute. The ocean-to-ice sensible heat flux is formulated the bulk formula of \citep{mcphee_1992}.
+
+% Ice growth
+If $B^{opw}$ is such that the SST would decrease below the freezing point, the remainder of the heat is used to form new ice. The heat loss is converted into a volume of new ice $v_0$. The thickness $h_0$ of the new ice grown during a sea ice time step depends on unresolved small-scale currents and waves and is prescribed. The fraction $a_0=v_0/h_0$ is computed accordingly. The salinity of this new ice $S_0$ is given by the salinity-thickness empirical relationship of \cite{kovacs_1996}. The temperature assumed for this new ice is the local freezing point. If by contrast $B^{opw}$ is positive and there still is ice in the grid cell, then $B^{opw}$ is directly redirected to bottom melting. This argument follows from \cite{maykut_1995}, who found that most of solar heat absorbed in the surface waters is converted into melting. In practise, this prevents the SST to be above freezing as long ice is present.
+
+$B^{opw}$ can be seen as a predictor of the heat budget of the first ocean level. As such, it only helps to compute new ice formation and the extra bottom melt in summer, but is not part of the conservation of heat in the model. To ensure heat conservation, the heat effectively contributing to changing sea ice is removed from the non-solar flux sent to the ocean. This includes: (i) the heat loss used for ice formation, (ii) the heat gain used to melt ice, and (iii) the sensible heat given by the ocean to the ice. Finally, because ice dynamics are not able to maintain the small amount of open water that is observed, a maximum ice fraction ($amax, <1$) is prescribed.
+
+\subsubsection{Vertical ice thermodynamic processes}
+
+The second part of the computations regard the computation of purerly vertical processes in the ice-covered part of the grid cell, similarly for each ice category. 
+
+\textbf{Surface melt, basal growth and melt and diffusion of heat}. The surface melt rate, as well as the basal growth / melt rate depend on the energy budget at the upper and lower interfaces, respectively, between the external fluxes either from the atmosphere or the ocean, and the internal conduction fluxes. The internal conduction fluxes depend on the internal temperature profile, which is determined by solving the enthalpy equation:
+\begin{linenomath}
+\begin{align}
+\rho \frac{\partial q_m}{\partial t} = - \frac{\partial}{\partial z} (F_c + F_r ).
+\end{align}
+\end{linenomath}
+which state that the local change in enthalpy is given by the divergence of the vertical conduction ($F_c=-k(S,T) \partial T / \partial z$) and radiation ($F_r$) fluxes. $\rho$ is the density of ice or snow. Re-expressed as a function of temperature, this becomes the heat diffusion equation.  This equation is non-linear in $T$, because of $q$ and $k$, and its main specificity is that internal melting requires large amounts of energy near the freezing point. The thermal conductivity is formulated following \cite{pringle_2007}, empirically accounting for the reduction of thermal conductivity at large brine fractions. 
+
+At the ice base, we assume that the temperature is at the local freezing point.  Ice grows or melt if the heat balance between the oceanic sensible heat flux ($F_w$) and internal conduction is negative or positive.
+
+At the ice surface, the boundary condition on the heat diffusion equation is:
+\begin{linenomath}
+\begin{align}
+Q^{sr}  + Q^{ns}(T_{su})= F_c + Q^{sum}.
+\end{align}
+\end{linenomath}
+where $Q^{sr}$ and $Q^{ns}$ are the net downwelling atmospheric solar and non-solar flux components. If the solution of this equation without melting gives a surface temperature ($T_{su}$) below 0$^\circ$ C, then there is no melting and the heat available for surface melting $Q_{sum}=0$.  Otherwise $T_{su}$ is capped at 0$^\circ$ C and $Q_{sum}$ is calculated as a residual.
+
+\textbf{Radiation}. Radiation contributes to the surface and internal heat budget. The radiative transfer scheme is currently basic, composed of surface albedo, transmission through the ice interior and attenuation with vertical depth. The albedo is computed empirically as a function of ice thickness, snow depth and surface temperature, using a reformulation of the parameterization of \cite{shine_1985}. When snow is present, all the absorbed radiation is transformed into sensible heat available for conduction or melting. Over snow-free ice, a fraction of solar radiation is transmitted below the surface and attenuates exponentially with depth, until it reaches the base of the ice.
+
+\textbf{Growth and melt processes}.  Snow grows from precipitation and loses mass from melting and snow-ice conversion once the snow base is below sea level. Sea ice grows and melts by various means. Ice forms by congelation or melt at the base, can melt at the surface and form from snow-to-ice conversion at the snow-ice interface if the latter is below sea level. Some new ice is also added to the system when seawater is trapped into newly formed pressure ridges.
+
+\textbf{Salt dynamics}. Bulk salinity is empirically parameterized, as a function of salt uptake during growth, gravity drainage and flushing. The shape of the vertical profile depends on the bulk salinity \citep{vancoppenolle_2009}.
+
+\textbf{Single-category parameterizations}. If the single-category representation is adopted, then two parameterizations can be activated, following \citep{fichefet_1997}. First, the thermal conductivity of both ice and snow is multiplied by a factor $>1$ accounting for the unresolved thin ice, effectively increasing the ice growth rate. Second, to account for the loss of thin ice in summer, the ice concentration is reduced in proportion to the loss of ice thickness. Both parameterizations have been tuned to match the results in multi-category mode.
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_output_diagnostics.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_output_diagnostics.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_output_diagnostics.tex	(revision 11422)
@@ -0,0 +1,65 @@
+\documentclass[../main/SI3_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 9 - Outputs and diagnostics
+% ================================================================
+
+\chapter{Output and diagnostics}
+\label{chap:DIA}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+\section{SIMIP diagnostics}
+
+The SIMIP protocol \citep{notz_2016} was designed for CMIP6, to standardize sea ice model outputs in climate simulations. We tried to follow the data request as closely as possible. Outputs are in most cases directly managed with XIOS2 in \textbf{limwri.F90}, but not always. In the code, output fields keep their native LIM reference name. 
+
+A corresponding entry exists in \textbf{field\_def\_nemo-lim.xml}, where fields are given their SIMIP specifications (standard name, long name, units). At the end of the file the fields are gathered in the field groups \textbf{SIday\_fields}, \textbf{SImon\_fields} and \textbf{SImon\_scalar} for separation of the daily (SIday) and monthly (SImon) requests. 
+
+In \textbf{file\_def\_nemo-lim.xml}, the daily, monthly and scalar output files are created.
+
+In the reference xml files, the largest possible SIMIP-based diagnostics with LIM are distributed among the field groups. If some fields are to be discarded, the best way to do so is to remove them from the field groups in  field\_def\_nemo-lim.xml.
+
+\subsection{Missing SIMIP fields}
+
+About 90\% of the SIMIP fields can be output. Below is the list of the missing fields and why they are missing. \\
+
+\textbf{1. Fields that are not part of the sea ice representation in LIM3.6}
+\begin{itemize}
+\item sisnconc (snow area fraction), siitdsnconc (snow area fractions in thickness categories);
+\item simpconc (meltpond area fraction), simpmass (melt pond mass per area), simprefrozen (thickness of refrozen ice on ponds);
+\item sirdgconc (ridged ice area fraction), sirdgmass (ridged ice thickness);
+\item sidmasslat (lateral sea ice melt rate);
+\item sndmasswindrif (snow mass change through wind drift of snow);
+\end{itemize}
+
+\textbf{2. Fields which value is trivial}
+\begin{itemize}
+\item sipr (rainfall over sea ice): all rain falls in open water;
+\item sidragtop (atmospheric drag over sea ice): namelist parameter;
+\item sidragbot (oceanic drag over sea ice): namelist parameter
+\end{itemize}
+
+\textbf{3. Fields that belong to the atmospheric component}
+\begin{itemize}
+\item siflswdtop, siflswutop, siflswdbot, sifllwdtop, sifllwutop, siflsenstop, sifllatstop (surface energy budget components)
+\end{itemize}
+
+Ice thickness and snow depth were masked below 5\% ice concentration, because below this value, they become meaninglessly large in LIM. This is notably because of the Prather advection scheme. We hope to fix these issues for our next release. For similar reasons, the ice age is masked below 15\% concentration.
+
+Fluxes through straits and passages were not directly implemented. Instead, ice mass, snow mass, and ice area transports were implemented as 2D arrays, for x- and y- directions. A python script is available to derive the fluxes through straits and passages from full 2D arrays for ORCA2 and eORCA1 grids.
+
+\subsection{Links}
+
+\begin{itemize}
+\item \textcolor{blue}{\href{http://www.geosci-model-dev.net/9/3427/2016/}{Paper of Notz et al}};
+\item \textcolor{blue}{\href{http://clipc-services.ceda.ac.uk/dreq/u/SIMIP.html}{SIMIP CMIP6 data request page}};
+\item \textcolor{blue}{\href{http://www.climate-cryosphere.org/activities/targeted/simip}{SIMIP description on CliC website}}.
+\end{itemize}
+
+\section{Conservation checks}
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_radiative_transfer.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_radiative_transfer.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_radiative_transfer.tex	(revision 11422)
@@ -0,0 +1,210 @@
+
+\documentclass[../main/SI3_manual]{subfiles}
+
+\begin{document}
+
+
+
+
+% ================================================================
+% Chapter 6 Ñ Radiative transfer
+% ================================================================
+
+\chapter{Radiative transfer}
+\label{chap:RAD}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+Radiative transfer in SI$^3$ currently reduces to the parameterization of solar radiation partitionning through the snow/ice/open water system, treated using a single wavelength band. This will likely be improved in future versions of the code. In this chapter, we first explain how solar radiation is partionned in the snow-ice system, then describe how, solar radiation-wise, the snow-ice system is framed in the context of the atmosphere-ice-ocean boundary.
+
+\section{Solar radiation partitionning in the snow-ice system}
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Radiation balance %
+\begin{figure}[!ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=6cm,angle=-00]{radiative_transfer}
+\caption{Partitionning of solar radiation in the snow-ice system, as represented in SI$^3$.}
+\label{fig_radiative_transfer}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+Solar radiation in the snow-ice system is represented following the principles of \cite{maykut_1971}, see Fig.\ref{fig_radiative_transfer}, using a unique band of solar radiation. Incident solar radiation (W/m$^2$, counted per unit ice area - not per grid cell area) is specified in the SBC routines and is a priori category dependent, because multiple atmosphere-surface reflexions are frequent in polar regions imply that incident radiation depends on the surface albedo and therefore surface state. 
+
+Net solar radiation qsr\_ice(i,j,l) is obtained by substracting the reflected part of the incident radiation using the surface albedo $\alpha(i,j,l)$, parameterized as a function of environmental conditions. 
+
+The subsequent attenuation of solar radiation through the snow-ice system is represented assuming the presence of a highly diffusive surface scattering layer, absorbing a fraction $i_o$ of net solar radiation, which is transformed into sensible heat, contributing to the surface energy balance. 
+
+The remainder of solar radiation, qtr\_ice\_top(i,j,l), is transmitted below the surface and attenuates following Beer-Lambert law. The part of solar radiation that is absorbed on its path to the base of the ice is given as sensible heat to the snow/ice system, via a source term in the heat diffusion equation. The rest of solar radiation that reaches the ice base, qtr\_ice\_bot(i,j,l), is transmitted to the ocean. 
+
+In the rest of this section, we describe how the albedo, the surface transmission parameter $i_o$ and the attenuation of solar radiation are parameterized.
+
+\subsection{Surface albedo}
+
+The surface albedo determines the amount of solar radiation that is reflected by the ice surface, hence also net solar radiation. The philosophy of the parameterization of surface albedo is the following: each ice category has its own albedo value $\alpha(i,j,l)$, determined as a function of cloud fraction, ice thickness, snow depth, melt pond fraction and depth, using observation-based empirical fits. 
+
+The original \cite{shine_1985} parameterization had a few inconsistencies and flaws that the revisited parameterization described hereafter fixes. In particular, the dependencies of albedos on ice thickness, snow depth and cloud fraction have been revised in the light of recent observational constraints \citep{brandt_2005,grenfell_2004}. In addition, the asymptotic properties of albedo are better specified and now fully consistent with oceanic values. Finally, the effect of melt ponds has been included \citep{lecomte_2015}.
+
+The user has control on 5 reference namelist values, which describe the asymptotic values of albedo of snow and ice for dry and wet conditions, as well as the deep ponded-ice albedo. Observational surveys, in particular during SHEBA in the Arctic \citep{perovich_2002} and further additional experiments \citep{grenfell_2004}, as well as by \cite{brandt_2005} in the Antarctic, have provided relatively strong constraints on the surface albedo. In this context, the albedo can hardly be used as the main model tuning parameter, at least outside of these observation-based bounds (see namalb for reference values).
+
+\nlst{namalb}
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : cloud correction
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=10cm,angle=-00]{albedo_cloud_correction}
+\caption{Albedo correction $\Delta \alpha$ as a function of overcast sky (diffuse light) albedo $\alpha_os$, from field observations \cite[][their Table 3]{grenfell_2004} (squares) and 2nd-order fit (Eq. \ref{eq_albedo_cloud_correction}). Red squares represent the irrelevant data points excluded from the fit. For indication, the amplitude of the correction used in the ocean component is also depicted (blue circle).}
+% ocean uses 0.06 for overcast sky (Payne 74) and Briegleb and Ramanathan parameterization
+\label{fig_albedo_cloud_correction}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+Because the albedo is not an intrinsic optical property, it depends on the type of light (diffuse of direct), which is practically handled by weighting the clear (cs) and overcast (os) skies values by cloud fraction $c(i,j)$ \citep{fichefet_1997}:
+\begin{equation}
+\alpha(i,j,l) = [ 1 - c(i,j) ] \cdot \alpha_{cs} (i,j,l) + c (i,j) \cdot \alpha_{os}(i,j,l).
+\end{equation}
+For concision, we drop the spatial and category indices hereafter. \cite{grenfell_2004} observations at Point Barrow, on the Alaskan Coast, suggest that clear and overcast sky albedos are directly related through
+\begin{equation}
+\alpha_{cs} = \alpha_{os} - \Delta \alpha(\alpha_{os}).
+\end{equation}
+The relation between $\Delta \alpha$ and $ \alpha_{os}$ can well be handled using a 2$^{nd}$-order polynomial fit (Fig. \ref{fig_albedo_cloud_correction}):
+\begin{equation}
+\Delta \alpha =  ( -0.1010 \cdot \alpha_{os}^2 + 0.1933 \cdot \alpha_{os} - 0.0148 ).
+\label{eq_albedo_cloud_correction}
+\end{equation}
+Overcast sky surface albedo is used as a reference, from which the clear-sky value is derived.
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : thickness, snow depth, pond depth dependencies
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=4cm,angle=-00]{albedo_dependencies}
+\caption{Example albedo dependencies on ice thickness, snow depth and pond depth, as parameterized in SI$^3$.}
+\label{fig_albedo_dependencies}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+The second important parameter that controls surface albedo is surface type. In each category, we assume that three types of surfaces can coexist (bare, snow-covered and ponded ice), with respective fractions $f_{ice}$, $f_{snw}$ and $f_{pnd}$ summing to 1. Then the overcast albedo is expressed as
+\begin{equation}
+\alpha_{os}(i,j,l) = f_{ice} \cdot \alpha_{ice} + f_{snw} \cdot \alpha_{snw} + f_{pnd}\cdot \alpha_{pnd}
+\end{equation}
+with a specific albedo value for each surface type. 
+
+The surface fractions $f_{ice}$, $f_{snw}$ and $f_{pnd}$ are currently crudely parameterized: if snow is present ($h_s>0$), then $f_{snw}=1$ and $f_{ice}=f_{pnd}=0$. In the absence of snow, $f_{pnd}$ is either specified or calculated (depending on melt pond options in nampnd), and $f_{ice}=1.-f_{pnd}$. Admittedly, more refined parameterizations of $f_{snw}$ could improve the realism of the model. Note finally that the dependence of surface albedo on the presence of melt ponds can be included or not (namelist parameter ln\_pnd\_alb). If the latter is set to false, $f_{pnd}$ is always assumed zero in the albedo computations.
+
+Works by \cite{brandt_2005} and references therein, indicate that the dependence of the albedo of bare ice on ice thickness depends is linear/logarithmic/constant from thin to thick ice. Hence, the following expressions capture  the essence of their works:
+\begin{eqnarray}
+\alpha_{ice} = 
+\begin{cases}
+\alpha_{ice}^{\infty} & \text{ if } h_i > 1.5, \\
+\alpha_{ice}^{\infty} + ( 0.18 - \alpha_{ice}^{\infty} ) \cdot \frac{ln(1.5) - ln(h_i)}{ln(1.5) - ln(0.05)} & \text{ if } 0.05 < h_i ,<= 1.5 \\
+\alpha_{oce}  + ( 0.18 - \alpha_{oce} ) h_i /0.05 & \text{ if } h_i < 0.05.
+\end{cases}
+\end{eqnarray}
+The thick-ice constant albedo value depends on whether the surface is dry or melting:
+\begin{eqnarray}
+\alpha_{ice}^{\infty} =
+\begin{cases}
+\alpha_{i,dry} & \text{ if } T_{su} < T_{fr} \\
+\alpha_{i,mlt} & \text{ if } T_{su} = T_{fr},
+\end{cases}
+\end{eqnarray}
+values that are to be specified from the namelist.
+
+\cite{grenfell_2004} suggest that the dependence of surface albedo on snow depth is exponential,
+\begin{eqnarray}
+\alpha_{snw} = \alpha_{snw}^{\infty} - ( \alpha_{snw}^{\infty} - \alpha_{ice} ) * exp( -h_s / h_s^{ref} ),
+\end{eqnarray}
+where $h_s^{ref} = 0.02$ $(0.03)$ m for dry (wet) snow. As for bare ice, the deep-snow asymptotic albedo also depends on whether the surface is dry or melting:
+\begin{eqnarray}
+\alpha_{snw}^{\infty} =
+\begin{cases}
+\alpha_{s,dry} & \text{ if } T_{su} < T_{fr} \\
+\alpha_{s,mlt} & \text{ if } T_{su} = T_{fr},
+\end{cases}
+\end{eqnarray}
+values that are to be specified from the namelist.
+
+Based on ideas developed from melt ponds on continental ice \citep{zuo_1996}, the albedo of ponded ice was proposed to follow \citep{lecomte_2011}:
+\begin{eqnarray}
+\alpha_{pnd} = \alpha_{dpnd} - ( \alpha_{dpnd} -\alpha_{ice} ) \cdot exp( -h_{pnd} / 0.05 )
+\end{eqnarray}
+$\alpha_{dpnd}$ is a namelist parameter. \cite{ebert_1993} also use such dependency for their multi-spectral albedo.
+
+The dependencies of surface albedo on ice thickness, snow depth and pond depth are illustrated in Fig. \ref{fig_albedo_dependencies}.
+
+\subsection{Transmission below the snow/ice surface}
+
+The transmitted solar radiation below the surface is represented following \cite{fichefet_1997} and \cite{maykut_1971}:
+\begin{eqnarray}
+qtr\_ice\_top(i,j,l) = i_o(i,j) qsr\_ice(i,j,l),
+\end{eqnarray}
+where $i_o=0$ in presence of snow, and depends on cloud fraction otherwise, based on works of \cite{grenfell_1977}. This parameterization needs to be re-evaluated and likely updated.
+
+\subsection{Attenuation and transmission below the ice/ocean interface}
+
+Attenuation of solar radiation through the ice follows Beer-Lambert law. In practise, we assume that irradiance below layer $k$ is given by
+
+\begin{eqnarray}
+radtr\_i(i,j,k,l) = qtr\_ice\_top(i,j,l) \cdot exp(-\kappa_i z),
+\end{eqnarray}
+where $\kappa_i = 1$ m$^{-1}$ is the exponential attenuation coefficient (namelist parameter rn\_kappa\_i). Hence, at the ice base, remains below the $l^{th}$ category a transmitted flux: 
+\begin{eqnarray}
+qtr\_ice\_bot(i,j,l) = qtr\_ice\_top(i,j,l) \cdot exp(-\kappa_i h_i).
+\end{eqnarray}
+
+\section{Solar radiation: framing sea ice at the ocean-atmosphere boundary}
+
+How solar radiation transfer through sea ice is framed into the atmosphere-ice-ocean is nearly identical but not exactly the same in forced and coupled mode (see Fig. \ref{fig_radiative_transfer}.
+
+The basic principle of the computation is that the irradiant flux given to the ocean model (qsr) is computed as the average flux per grid cell area (qsr\_tot) minus what is given to the sea ice ($\sum a(l) qsr\_ice(l)$), plus what is transmitted below sea ice $\sum$ qtr\_ice\_bot(jl) (see at the base of Fig. \ref{fig_radiative_transfer}). Such formulation ensures heat conservation by construction.
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Radiation balance %
+\begin{figure}[!ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=8cm,angle=-00]{radiation_atm_ice_oce}
+\caption{Framing solar radiation transfer through sea ice into the atmosphere-ice-ocean context.}
+% ocean uses 0.06 for overcast sky (Payne 74) and Briegleb and Ramanathan parameterization
+\label{fig_radiative_transfer}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+\subsection{Forced mode}
+
+In forced-atmosphere mode, it is the incoming solar irradiance fluxes above the ocean and sea ice (categories) that are specified (from files) or computed (from bulk formulae), and constitute the basis of solar radiation transfer computations. Then the net solar fluxes above open water (qsr\_oce) and ice categories (qsr\_ice) are obtained by multiplication by $1-\alpha$. qsr\_tot is then diagnosed as a weighted sum of qsr\_oce and the qsr\_ice(jl)'s.
+
+\subsection{Coupled mode}
+
+In coupled-atmosphere mode, qsr\_tot and qsr\_ice have to be provided by the atmospheric model, whereas qsr\_oce is diagnosed from qsr\_ice and qsr\_tot.
+
+Some atmospheric models enable \textit{tiling} and can provide solar fluxes over individual ice categories. For such atmospheric models, net solar radiation fluxes are directly useable by SI$^3$ (nn\_flxdist =  -1). Other models cannot do tiling, being only able to provide a net solar flux above all ice categories, seen as a single surface type. For such models a first option is to give the net solar flux above sea ice identically to all sea ice categories (nn\_flxdist = 0). Yet a better option is to redistribute the mean solar flux above sea ice $< qsr_ice >$ above categories (nn\_flxdist = 2) using the following scaling, conserving heat by construction:
+
+\begin{eqnarray}
+qsr\_ice(jl) = < qsr\_ice > \frac{1 - \alpha(jl)}{1 - < \alpha >}
+\end{eqnarray}
+
+where $ < \alpha >$ is the albedo averaged over the ice categories. Note that for testing, the flux redistributor can be emulated in forced mode (nn\_flxdist = 1).
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_ridging_rafting.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_ridging_rafting.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_ridging_rafting.tex	(revision 11422)
@@ -0,0 +1,156 @@
+
+\documentclass[../main/SI3_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 5 Ñ Ridging and rafting
+% ================================================================
+
+\chapter{Ridging and rafting}
+\label{chap:RDG}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+This chapter focuses on how LIM solves the red part of the general equation:
+\begin{equation}
+\frac{\partial X}{\partial t} = - \nabla .(\mathbf{u} X)  \color{black} \Theta^X  + \color{red} \Psi^X,
+\label{eq:Xt}
+\end{equation}
+where $X$ refers to any global sea ice state variable.
+
+Divergence and shear open the ice pack and create ice of zero thickness. Convergence and shear consumes thin ice and create thicker ice by mechanical deformation. The redistribution functions $\Psi^X$ describe how opening and mechanical deformation redistribute the global ice state variables into the various ice thickness categories. 
+
+The fundamental redistribution function is $\Psi^g$, which accounts for area redistribution. The other redistribution functions $\Psi^X$ associated with other state variables will derive naturally. The redistribution function $\Psi^g$ should first ensure area conservation. By integrating the evolution equation for $g(h)$ over all thicknesses, recalling that $\int_0^\infty g(h) = 1$, and that the total areal change due to thermodynamics must be zero, e.g. $\int_0^\infty \partial (fg) / \partial h=0$, then the area conservation reads: 
+\begin{equation}
+\int_0^\infty h \Psi^g dh = \nabla \cdot \mathbf{u}.
+\end{equation}
+
+Second, we must say something about volume conservation, and this will be done more specifically later. Following \cite{thorndike_1975}, we separate the $\Psi^X$'s into \textbf{(i)} \textit{dynamical inputs}, \textbf{(ii)} \textit{participation functions}, i.e., how much area of ice with a given thickness participates to mechanical deformation \textbf{(iii)} \textit{transfer functions}, i.e., where in thickness space the ice is transferred after deformation.
+
+\section{Dynamical inputs}
+
+A general expression of $\Psi^g$, the mechanical redistribution function associated to the ice concentration, was proposed by \cite{thorndike_1975}:
+\begin{equation}
+\Psi^g = \vert \dot{\epsilon} \vert [ \alpha_o(\theta) \delta(h) + \alpha_d(\theta) w_d(h,g) ],
+\label{eq:psi}
+\end{equation}
+which is convenient to separate the dependence in $\mathbf{u}$ from those in $g$ and $h$. The first and second terms on the right-hand side correspond to opening and deformation, respectively. $\vert \dot{\epsilon} \vert = (\dot{\epsilon}_{I}^2+ \dot{\epsilon}_{II}^2)^{1/2}$, where $\dot{\epsilon}_{I}=\nabla \cdot \mathbf{u}$ and $\dot{ \epsilon}_{II}$ are the strain rate tensor invariants; $\theta=\textrm{atan}(\dot{\epsilon_{II}} / \dot{\epsilon_{I}} )$. $w_d(h,g)$, the deformation mode will be discussed in the next section. $\vert \dot{\epsilon} \vert \alpha_o$ and $\vert \dot{\epsilon} \vert \alpha_d$ are called the lead opening and closing rates, respectively.
+
+The \textbf{dynamical} inputs of the mechanical redistribution in LIM are:
+\begin{itemize}
+\item $\vert \dot{\epsilon} \vert \alpha_o$, the opening rate,
+\item $\vert \dot{\epsilon} \vert \alpha_d$, the net closing rate.
+\end{itemize}
+Following \cite{thorndike_1975}, we choose $\int_0^\infty w_d(h,g) = - 1$. In order to satisfy area conservation, the relation $\vert \dot{\epsilon} \vert \alpha_o - \vert \dot{\epsilon} \vert \alpha_d = \nabla \cdot \mathbf{u}$ must be verified. In the model, there are two ways to compute the divergence of the velocity field. A first way is to use the velocity components ($\dot{\epsilon}_I = \nabla \cdot \mathbf{u}\vert^{rhg}$) as computed after the rheology (superscript $rhg$). Another way is to derive it from the horizontal transport of ice concentration and open water fraction. In principle, the equality $A^o + \sum_{l=1}^L g^i_L = 1$ should always be verified. However, after ice transport (superscript $trp$), this is not the case, and one can diagnose a velocity divergence using the departure from this equality: $\nabla \cdot \mathbf{u}\vert^{trp} = ( 1 - A^o - \sum_{l=1}^L g^i_L )/ \Delta t$. In general, we will use $\dot{\epsilon}_I$ unless otherwise stated.
+
+The \textbf{net closing rate} is written as a sum of two terms representing the energy dissipation by shear and convergence \citep{flato_1995}:
+\begin{equation}
+\vert \dot{\epsilon} \vert \alpha_d (\theta) = C_s \frac{1}{2} ( \Delta - \vert \dot{\epsilon}_I \vert) - \textrm{min} (\dot{\epsilon}_I,0),
+\end{equation}
+where $\Delta$ is a measure of deformation (defined in the rheology section). The factor $C_s=0.5$ (\textit{Cs} in \textit{namelist\_ice}) is added to allow for energy sinks other than ridge building (e.g., sliding friction) during shear. In case of convergence, the closing rate must be large enough to satisfy area conservation after ridging, so we take:
+\begin{equation}
+\vert \dot{\epsilon} \vert \alpha_d (\theta) = \text{max}(\vert \dot{\epsilon} \vert \alpha_d (\theta), - \nabla \cdot \mathbf{u} \vert^{trp}) \quad \text{if } \nabla \cdot \mathbf{u} < 0.
+\end{equation}
+
+The \textbf{opening rate} is obtained by taking the difference:
+\begin{equation}
+\vert \dot{\epsilon} \vert \alpha_o = \vert \dot{\epsilon} \vert \alpha_d = \nabla \cdot \mathbf{u}\vert^{trp}
+\end{equation}
+
+\section{The two deformation modes: ridging and rafting}
+
+The deformation mode is separated into ridging $w^{ri}$ and rafting $w^{ra}$ modes:
+\begin{equation}
+w^d(h,g) = w^{ri}(g,h) + w^{ra}(g,h).
+\end{equation}
+
+\textbf{Rafting} is the piling of two ice sheets on top of each other. Rafting doubles the participating ice thickness and is a volume-conserving process. \cite{babko_2002} concluded that rafting plays a significant role during initial ice growth in fall, therefore we included it into the model. 
+
+\textbf{Ridging} is the piling of a series of broken ice blocks into pressure ridges. Ridging redistributes participating ice on a various range of thicknesses. Ridging does not conserve ice volume, as pressure ridges are porous. Therefore, the volume of ridged ice is larger than the volume of new ice being ridged. In the model, newly ridged is has a prescribed porosity $p=30\%$ (\textit{ridge\_por} in \textit{namelist\_ice}), following observations \citep{lepparanta_1995,hoyland_2002}. The importance of ridging is now since the early works of \citep{thorndike_1975}.
+
+The deformation modes are formulated using \textbf{participation} and \textbf{transfer} functions with specific contributions from ridging and rafting:
+\begin{equation}
+w_d(h,g) = - [ b^{ra}(h) + b^{ri}(h) ] g(h) + n^{ra}(h)+n^{ri}(h).
+\label{eq:wd}
+\end{equation}
+$b^{ra}(h)$ and $b^{ri}(h)$ are the rafting and ridging participation functions. They determine which regions of the ice thickness space participate in the redistribution. $n^{ra}(h)$ and $n^{ri}(h)$, called transfer functions, specify how thin, deformation ice is redistributed onto thick, deformed ice. Participation and transfer functions are normalized in order to conserve area.
+
+\section{Participation functions}
+
+We assume that the participation of ice in redistribution does not depend upon whether the deformation process is rafting or ridging. Therefore, the participation functions can be written as follows:
+\begin{equation}
+b^{ra}(h)= \beta(h) b(h),
+\label{eq:bra}
+\end{equation}
+\begin{equation}
+b^{ri}(h) = [1-\beta(h)] b(h),
+\label{eq:bri}
+\end{equation}
+where $b(h)$ is an exponential weighting function with an e-folding scale $a*$ \citep{lipscomb_2007} (\textit{astar} in \textit{namelist\_ice}) which preferentially apportions the thinnest available ice to ice deformation:
+\begin{equation}
+b(h) = \frac{\text{exp} [ - G(h) / a^\star ]}{a^\star[1-\text{exp}(-1/a^\star)]} ,
+\end{equation}
+It is numerically more stable than the original version of \cite{thorndike_1975}. This scheme is still present in the code and can be activated using \textit{partfun\_swi} from \textit{namelist\_ice}, with the associated parameter \textit{Gstar}.
+
+$\beta(h)$ partitions deformation ice between rafted and ridged ice. $\beta(h)$ is formulated following \cite{haapala_2000}, using the \cite{parmerter_1975} law, which states that, under a critical participating ice thickness $h_P$, ice rafts, otherwise it ridges:
+\begin{equation}
+\beta(h)= \frac{ \textrm{tanh} [ -C_{ra} (h-h_P) ] + 1 } {2},
+\end{equation}
+where $C_{ra}=5$ m$^{-1}$ (\textit{Craft} in \textit{namelist\_ice})  and $h_P=0.75$ m (\textit{hparmeter} in \textit{namelist\_ice}) \citep{haapala_2000,babko_2002}. The $tanh$ function is used to smooth the transition between ridging and rafting.  If namelist parameter \textit{raftswi} is set to 0, ice only ridges and does not raft. 
+
+\section{Transfer functions}
+
+The rafting transfer function assumes a doubling of ice thickness :
+\begin{equation}
+n^{ra}(h)=\frac{1}{2}\int_0^\infty \delta(h-2h') b(h') g(h') dh,
+\end{equation}
+where $\delta$ is the Dirac delta function. 
+
+The ridging transfer function is :
+\begin{equation}
+n^{ri}(h)=\int_0^\infty \gamma(h',h) (1+p) b(h') g(h') dh.
+\label{eq:nri}
+\end{equation}
+The redistributor $\gamma(h',h)$ specifies how area of thickness $h'$ is redistributed on area of thickness $h$. We follow \citep{hibler_1980} who constructed a rule, based on observations, that forces all ice participating in ridging with thickness $h'$ to be linearly distributed between ice that is between $2h'$ and $2\sqrt{H^*h'}$ thick, where $H^\star=100$ m (\textit{Hstar} in \textit{namelist\_ice}). This in turn determines how to construct the ice volume redistribution function $\Psi^v$. Volumes equal to participating area times thickness are removed from thin ice. They are redistributed following Hibler's rule. The factor $(1+p)$ accounts for initial ridge porosity $p$ (\textit{ridge\_por} in \textit{namelist\_ice}, defined as the fractional volume of seawater initially included into ridges. In many previous models, the initial ridge porosity has been assumed to be 0, which is not the case in reality since newly formed ridges are porous, as indicated by in-situ observations \citep{lepparanta_1995,hoyland_2002}. In other words, LIM3 creates a higher volume of ridged ice with the same participating ice.
+
+For the numerical computation of the integrals, we have to compute several temporary values:
+\begin{itemize}
+\item The thickness of rafted ice $h^{ra}_l = 2 h^i_l$
+\item The mean thickness of ridged ice $h^{ri,mean}_l=\text{max} ( \sqrt{H^\star h^i_l} , h^i_l \cdot 1.1 )$
+\item The minimum thickness of ridged ice $h^{ri,min}_l = \text{min} [ 2*h^i_l, 0.5\cdot(h^{ri,mean}_l+h^i_l) ]$
+\item The maximum thickness of ridged ice $h^{ri,min}_l = 2 h^{ri,mean}_l - h^{ri,min}_l$
+\item The mean rate of thickening of ridged ice $k^{ri}_l = h^{ri,mean}_l / h^{i}_l$
+\end{itemize}
+
+\section{Ridging shift}
+
+%\textit{Subroutine}: \textbf{lim\_itd\_ridgeshift}
+
+The numerical computation of the impact of mechanical redistribution on ice concentration involves:
+\begin{itemize}
+\item A normalization factor that ensures volume conservation (\textit{aksum})
+\item The removal of ice participating in deformation (including the closing of open water)
+\item The addition of deformed ice
+\end{itemize}
+
+For ice concentrations, the numerical procedure reads:
+\begin{equation}
+\Delta g^i_l = C^{net} \Delta t \biggr [ - ( b^{ri}_l + b^{ra}_l) + \sum_{l_2=1}^L \biggr ( f^{ra}_{l,l_2}  \frac{b^{ra}_{l_2}}{k^{ra}} + f^{ri}_{l,l_2} \frac{ b^{ri}_{l_2} }{k^{ri}_{l_2}} \biggr ) \biggr ]
+\end{equation}
+\begin{itemize}
+\item $C^{net}$ is the normalized closing rate ($\vert \dot{\epsilon} \vert \alpha^d/\textit{aksum}$)
+\item $b^{ri}_l$ and $b^{ra}_l$ are the area participating into redistribution for category $l$
+\item $f^{ra}_{l,l_2}$ and $f^{ri}_{l,l_2}$ are the fractions of are of category $l$ being redistributed into category $l_2$
+\item $k^{ra}$ is the rate of thickening of rafted ice (=2)
+\end{itemize}
+
+Because of the nonlinearities involved in the integrals, the ridging procedure has to be iterated until $A^\star = A^{ow} + \sum_{l=1}^L g^i_l = 1$.
+
+\section{Mechanical redistribution for other global ice variables}
+
+The other global ice state variables redistribution functions $\Psi^X$ are computed based on $\Psi^g$ for the ice age content and on $\Psi^{v^i}$ for the remainder (ice enthalpy and salt content, snow volume and enthalpy). The general principles behind this derivation are described in Appendix A of \cite{bitz_2001}. A fraction $f_s=0.5$ (\textit{fsnowrdg} and \textit{fsnowrft} in \textit{namelist\_ice}) of the snow volume and enthalpy is assumed to be lost during ridging and rafting and transferred to the ocean. The contribution of the seawater trapped into the porous ridges is included in the computation of the redistribution of ice enthalpy and salt content (i.e., $\Psi^{e^i}$ and $\Psi^{M^s}$). During this computation, seawater is supposed to be in thermal equilibrium with the surrounding ice blocks. Ridged ice desalination induces an implicit decrease in internal brine volume, and heat supply to the ocean, which accounts for ridge consolidation as described by \cite{hoyland_2002}. The inclusion of seawater in ridges does not imply any net change in ocean salinity. The energy used to cool down the seawater trapped in porous ridges until the seawater freezing point is rejected into the ocean.
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_single_category_use.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_single_category_use.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_single_category_use.tex	(revision 11422)
@@ -0,0 +1,22 @@
+
+\documentclass[../main/SI3_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 10 Ñ Single-category use
+% ================================================================
+
+\chapter{Using SI$^3$ with a single category}
+
+\label{chap:INT}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+\section{Enhanced conduction}
+\section{Virtual thin ice melting (fake lateral melting)}
+\section{Ridging and rafting with a single ice category}
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_thermo.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_thermo.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_thermo.tex	(revision 11422)
@@ -0,0 +1,88 @@
+\documentclass[../main/SI3_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 7 Ñ Ice thermodynamics
+% ================================================================
+
+\chapter{Ice thermodynamics}
+\label{chap:THD}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+
+% ================================================================
+% Thermodynamics % ================================================================
+
+Mass, energy and salt are intertwined for sea ice. Referred to as thermodynamics, or more exactly halo-thermodynamics. Mushy-layer theory.
+
+\section{Open water and new ice formation}
+
+% There is everything in here, but there are too much details.
+% Move things around into chapters and summarize.
+
+As part of the sea ice computations, a heat budget of the uppermost oceanic level is estimated. This heat budget is used if negative to compute the production of new ice or, if positive, for bottom melting. 
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Open water energy budget
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=10cm,angle=-00]{Openwater_eb}
+\caption{Scheme of the estimate of the heat budget of the first ocean level.}
+\label{fig_yield}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+We estimate the heat budget of the first ocean level ($B^{opw}$) assuming four contributions, namely:
+\begin{itemize}
+\item The absorption of a fraction $f_1^{qsr}$ of solar radiation (given by radiative transfer component of the ocean model);
+\item The non-solar heat flux absorbed at the surface;
+\item The sensible heat content of precipitation
+\item The sensible heat loss to the sea ice
+\end{itemize}
+The estimated heat budget thus reads:
+\begin{linenomath}
+\begin{align}
+B^{opw} = Q^{sr} ( 1 - A ) f_1^{qsr} + Q^{ns} ( 1 - A ) + Q^{emp} - A F_w,
+\end{align}
+\end{linenomath}
+Hence there is no consideration of the entrainment of heat at the base of the first ocean level, or of solar radiation transmitted below the ice. The ocean-to-ice turbulent sensible heat flux is formulated following \citep{mcphee_1992}
+\begin{linenomath}
+\begin{align}
+F_w = \rho_0 c_w C_h u^* ( SST - T_b )
+\end{align}
+\end{linenomath}
+where $\rho_0$ is the reference ocean density, $c_w$ is the seawater specific heat, $C_h = 7.5 \times 10^{-3}$ is a heat transfer coefficient, and $u^*=\sqrt{\tau_{iw}/\rho_0}$. There are two additional conditions, the oceanic heat flux cannot be negative. Second, $F_w$ cannot exceed the heat content of the first ocean level.
+
+% Ice growth
+If the $B^{opw}$ is such that the SST would decrease below the freezing point, the remainder of the heat is used to form new ice. The heat loss is converted into mass through [\ref{eq_phasechange}], giving by multiplication by density a volume of new ice $v_0$. The thickness $h_0$ of the new ice grown during a sea ice time step depends on unresolved small currents and waves and is prescribed. The fraction $a_0=v_0/h_0$ is computed accordingly. The salinity of this new ice $S_0$ is given by the S-h empirical relationship of \cite{kovacs_1996}. The temperature assumed for this new ice is the local freezing point.
+
+% Ice melt
+If there is ice in the grid cell and that the $B^{opw}$ is positive, it is directly given attributed to the heat available for bottom melting. This argument follows from \cite{maykut_1995}, who found that most of solar heat absorbed in the surface waters is converted into melting. In practise, this means that the SST cannot go above freezing as long ice is present.
+
+The heat loss used for ice formation, heat gain used to melt ice and the sensible heat given by the ocean to the ice, are all removed from the non-solar heat flux transmitted to the ocean.
+
+Because ice dynamics are not able to maintain the small amount of open water that is observed, a maximum ice fraction ($amax, <1$) is prescribed.
+
+\section{Diffusion of heat}
+
+\section{Vertical growth and melt}
+
+\section{Desalination}
+
+\section{Remapping}
+
+\section{Transport in thickness space}
+
+\section{True lateral melting}
+
+\end{document}
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_transport.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_transport.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/chap_transport.tex	(revision 11422)
@@ -0,0 +1,27 @@
+
+\documentclass[../main/SI3_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 4 Ñ Ice transport
+% ================================================================
+
+\chapter{Ice transport}
+\label{chap:TRP}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+As soon as ice dynamics are activated (\textit{ln\_dyn\_xxx}), all extensive state variables are to be advected following the horizontal velocity field.
+
+\section{Second order moments conserving (Prather 1986) scheme (\textit{ln\_adv\_Pra})}
+
+The scheme of  \cite{prather_1986} explicitly computes the conservation of second-order moments of the spatial distribution of global sea ice state variables. This scheme preserves positivity of the transported variables and is practically non-diffusive. It is also computationally expensive, however it allows to localize the ice edge quite accurately. As the scheme is conditionally stable, the time step is split into two parts if the ice drift is too fast, based on the CFL criterion. 
+
+State variables per unit grid cell area are first multiplied by grid cell area. Then, for each state variable, the 0$^{th}$ (mean), 1$^{st}$ (x, y) and 2$^{nd}$ (xx, xy, yy) order moments of the spatial distribution are transported. At 1st time step, all moments are zero (if prescribed initial state); or read from a restart file, and then evolve through the course of the run. Therefore, for each global variable, 5 additional tracers have to be kept into memory and written in the restart file, which significantly increases the required memory. Advection following x and y are computed independently. The succession order of x- and y- advection is reversed every day.
+
+\section{5$^{th}$ order flux-corrected transport scheme (UM5)}
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/introduction.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/introduction.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/introduction.tex	(revision 11422)
@@ -0,0 +1,59 @@
+
+% ================================================================
+% INTRODUCTION
+% ================================================================
+
+\chapter*{Introduction}
+
+\textcolor{red}{[ \textit{July 2018} ]} \\
+
+%Near the poles of the Earth, the seas and oceans freeze when seawater at the freezing point loses heat. The resulting forms of saline ice are collectively called \textit{sea ice} \citep{WMO70}, reaching up to a few meters in thickness, where as sea ice coverage is about 5\% of the global ocean, about 30 million square kilometers. All sea ice characteristics vary over a wide range of spatio-temporal scales, reflecting changes in heat, mass and momentum exchanges with the atmosphere and the ocean; the clearest temporal signal being an ample seasonal cycle. Sea ice formation and melting affects water mass formation in the ocean \citep{goosse_1999}. It not only impacts, but also reflects the state of the climate system \citep{budyko_1969,notz_2016}.  Sea ice also affects marine life, water chemistry and human activities in polar regions. Local populations use sea ice for travelling and hunting, whereas navigation and resource exploitation are dependent on sea ice conditions. For such reasons, ocean modelling systems, including NEMO, must include a sea ice component.
+
+The sea Ice Modelling Integrated Initiative (SI$^3$) is the sea ice engine of the Nucleus for European Modelling of the Ocean (NEMO). It is intended to be a flexible tool for studying sea ice and its interactions with the other components of the Earth System over a wide range of space and time scales. SI$^3$ is a curvilinear grid, finite-difference implementation of the classical AIDJEX\footnote{AIDJEX=\textbf{A}rctic \textbf{I}ce \textbf{D}ynamics \textbf{J}oint \textbf{EX}periment} model \citep{coon_1974}, combining the conservation of momentum for viscous-plastic continuum, energy and salt-conserving halo-thermodynamics, an explicit representation of subgrid-scale ice thickness variations, snow and melt ponds. An option to switch back to the \textit{single-category} (or \textit{2-level}) framework of \cite{hibler_1979} provides a cheap sea ice modelling solution.
+
+SI$^3$ is the result of the recommendation of the Sea Ice Working Group (SIWG) to reduce duplication and better use development resources. SI$^3$ merges the capabilities of the 3 formerly used NEMO sea ice models (CICE, GELATO and LIM). The \textbf{3} in SI$^3$ refers to the three formerly used sea ice models. It also refers to linkages between 3 different media (ocean, ice, snow). The model can be spelt 'SI3' in situations where the superscript could be problematic (i.e., within code and svn repository etc.) The model name would be pronounced as 'si-cube' for short (or 'sea ice cubed' for slightly longer). 
+
+% Limitations & scope
+%There are limitations to the applicability of models such as SI$^3$. The continuum approach is not invalid for grid cell size above at least 1 km, below which sea ice particles may include just a few floes, which is not sufficient \citep{lepparanta_2011}. Second, one must remember that our current knowledge of sea ice is not as complete as for the ocean: there are no fundamental equations such as Navier Stokes equations for sea ice. Besides, important features and processes span widely different scales, such as brine inclusions (1 $\mu$m-1 mm) \citep{perovich_1996}, horizontal thickness variations (1 m-100 km) \citep{percival_2008}, deformation and fracturing (10 m-1000 km) \citep{marsan_2004}. These impose complicated and often subjective subgrid-scale treatments. All in all, there is more empirism in sea ice models than in ocean models. 
+
+In order to handle all the subsequent required subjective choices, we applied the following guidelines or principles:
+\begin{itemize}
+\item Sea ice is frozen seawater that is in tight interaction with the underlying ocean. This close connexion suggests that the sea ice and ocean model components must be as consistent as possible. In practice, this is materialized by the close match between LIM and NEMO, in terms of numerical choices, regarding the grid (Arakawa C-type) and the numerical discretization (finite differences with NEMO scale factors).
+\item It is useful to be able to either prescribe the atmospheric state or to use an atmospheric model. For consistency and simplicity of the code, we choose to use formulations as close as possible in both cases.
+\item Different resolutions and time steps can be used. There are parameters that depend on such choices. We thrieved to achieve a resolution and time-step independent code, by imposing a priori scaling on the resolution / time step dependence of such parameters.
+\item Energy, mass and salt must be conserved as much as possible.
+\end{itemize}
+
+This manual is organised as follows. \\
+
+List of chapters... \\
+
+There are no more CPP keys in the code. \\
+
+Namelists and output management follow NEMO guidelines. \\
+
+Changes between releases. \\
+
+The list of people that should be acknowledged is too long, but a great number of people or more exactly a number of great people contributed to the code and should be gratefully acknowledged. As for today,
+the SIWG members are \textit{(July 2018)}.
+
+\begin{itemize}
+\begin{footnotesize}
+\item Yevgeny Aksenov (NOCS, Southampton, UK)
+\item Ed Blockley (Met Office, Exeter, UK, co-chair)
+\item Matthieu Chevallier (CNRM-GAME, M\'et\'eo France, Toulouse)
+\item Danny Feltham (CPOM, Reading, UK)
+\item Thierry Fichefet (UCL, Louvain-la-Neuve, Belgium)
+\item Gilles Garric (Mercator-Oc\'ean, Toulouse, France)
+\item Paul Holland (BAS, Cambridge, UK)
+\item Dorotea Iovino (CMCC, Bologna, Italy)
+\item Gurvan Madec (LOCEAN, CNRS, Paris, France)
+\item Fran\c cois Massonnet (UCL, Louain-la-Neuve, Belgium)
+\item Jeff Ridley (Met Office, Exeter, UK)
+\item Cl\'ement Rousset (LOCEAN, CNRS, Paris, France)
+\item David Salas (CNRM-GAME, M\'et\'eo France, Toulouse)
+\item David Schroeder (CPOM, Reading, UK)
+\item Steffen Tietsche (ECMWF, Reading, UK)
+\item Martin Vancoppenolle (LOCEAN, CNRS, Paris, France, co-chair) 
+\end{footnotesize}
+\end{itemize}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/todolist.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/todolist.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/subfiles/todolist.tex	(revision 11422)
@@ -0,0 +1,56 @@
+\documentclass[../main/SI3_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Dummy Chapter - To do list
+% ================================================================
+
+\chapter*{To-do-list for documentation}
+\label{chap:TDL}
+
+\begin{itemize}
+
+\item \textcolor{gray}{Documentation infrastructure ready by Jul 19, 2018.}
+
+\item \textcolor{gray}{Abstract: v1 written.}
+
+\item \textcolor{gray}{Disclaimer: v1 written.}
+
+\item Introduction: list of chapters and change between realeases to be written (1h)
+
+\item \textcolor{gray}{1. Model basics: v1 written.}
+
+\item \textcolor{gray}{Add namelist infrastructure as in NEMO doc (done)}
+
+\item \textcolor{gray}{2. Time, space and thickness space domain}
+
+\item 3. Ice dynamics: to be written (Clem \& Martin, 3h)
+
+\item 4. Ice transport: UM5 description to be written (Clem, 3h)
+
+\item 5. Ridging and rafting: V1 from previous doc. Should be refreshed. A bit too long. All namelist parameters are not explained (namdyn\_rdgrft).
+
+\item \textcolor{gray}{6. Radiative transfer: Full rewriting required (Martin \& Clem, 3-6h). Available elements from previous documentation, but mostly obsolete.}
+
+\item 7. Thermodynamics: Lots of rewriting required. Available elements from previous documentation, but mostly obsolete (Martin, 6h)
+
+\item 8. Interfaces: Full writing required 
+
+\item 9. Output and diagnostics: Full writing required
+
+\item 10. Single category (Martin, 3h). Full writing required.
+
+\item 11. BDY-AGRIF (Clem, 3h). Full writing required.
+
+\item 12. Miscellaneous. Full writing required.
+
+\item Melt ponds are not currently considered in the plan.
+
+\item Make sure all namelist parameters are properly described.
+
+\item Peer-review by SIWG members.
+
+\end{itemize}
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/build/TOP_manual.ist
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/build/TOP_manual.ist	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/build/TOP_manual.ist	(revision 11422)
@@ -0,0 +1,1 @@
+link ../../global/index.ist
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/TOP_manual.ist
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/TOP_manual.ist	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/TOP_manual.ist	(revision 11422)
@@ -0,0 +1,1 @@
+link ../../global/index.ist
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/TOP_manual.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/TOP_manual.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/TOP_manual.tex	(revision 11422)
@@ -0,0 +1,1 @@
+link ../../global/document.tex
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/bibliography.bib
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/bibliography.bib	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/bibliography.bib	(revision 11422)
@@ -0,0 +1,619 @@
+
+@Article{	  ahn_2007,
+  author	= {Ahn, Jinho and Brook, Edward J.},
+  title		= {Atmospheric CO2and climate from 65 to 30 ka B.P.},
+  year		= 2007,
+  volume	= 34,
+  number	= 10,
+  month		= {May},
+  issn		= {0094-8276},
+  doi		= {10.1029/2007gl029551},
+  url		= {http://dx.doi.org/10.1029/2007GL029551},
+  journal	= {Geophysical Research Letters},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  ahn_2008,
+  author	= {Ahn, J. and Brook, E. J.},
+  title		= {Atmospheric CO2 and Climate on Millennial Time Scales
+		  During the Last Glacial Period},
+  year		= 2008,
+  volume	= 322,
+  number	= 5898,
+  month		= {Oct},
+  pages		= {83–85},
+  issn		= {1095-9203},
+  doi		= {10.1126/science.1160832},
+  url		= {http://dx.doi.org/10.1126/science.1160832},
+  journal	= {Science},
+  publisher	= {American Association for the Advancement of Science
+		  (AAAS)}
+}
+
+@Article{	  armstrong_2001,
+  author	= {Armstrong, Robert A. and Lee, Cindy and Hedges, John I.
+		  and Honjo, Susumu and Wakeham, Stuart G.},
+  title		= {A new, mechanistic model for organic carbon fluxes in the
+		  ocean based on the quantitative association of POC with
+		  ballast minerals},
+  year		= 2001,
+  volume	= 49,
+  number	= {1-3},
+  month		= {Jan},
+  pages		= {219–236},
+  issn		= {0967-0645},
+  doi		= {10.1016/s0967-0645(01)00101-1},
+  url		= {http://dx.doi.org/10.1016/S0967-0645(01)00101-1},
+  journal	= {Deep Sea Research Part II: Topical Studies in
+		  Oceanography},
+  publisher	= {Elsevier BV}
+}
+
+@Article{	  aumont_2015,
+  author	= {Aumont, O. and Ethé, C. and Tagliabue, A. and Bopp, L.
+		  and Gehlen, M.},
+  title		= {PISCES-v2: an ocean biogeochemical model for carbon and
+		  ecosystem studies},
+  year		= 2015,
+  volume	= 8,
+  number	= 8,
+  month		= {Aug},
+  pages		= {2465–2513},
+  issn		= {1991-9603},
+  doi		= {10.5194/gmd-8-2465-2015},
+  url		= {http://dx.doi.org/10.5194/gmd-8-2465-2015},
+  journal	= {Geoscientific Model Development},
+  publisher	= {Copernicus GmbH}
+}
+
+@Article{	  bacastow_1990,
+  author	= {Bacastow, R and Maier-Reimer, E},
+  title		= {Ocean-circulation model of the carbon cycle},
+  year		= 1990,
+  volume	= 4,
+  number	= 2,
+  month		= {Apr},
+  pages		= {95–125},
+  issn		= {1432-0894},
+  doi		= {10.1007/bf00208905},
+  url		= {http://dx.doi.org/10.1007/bf00208905},
+  journal	= {Climate Dynamics},
+  publisher	= {Springer Nature}
+}
+
+@Misc{		  bullister_2017,
+  author	= {Bullister, J.L.},
+  title		= {Atmospheric Histories (1765-2015) for CFC-11, CFC-12,
+		  CFC-113, CCl4, SF6 and N2O (NCEI Accession 0164584)},
+  year		= 2017,
+  doi		= {10.3334/cdiac/otg.cfc\_atm\_hist\_2015},
+  url		= {https://accession.nodc.noaa.gov/0164584},
+  publisher	= {NOAA National Centers for Environmental Information}
+}
+
+@Article{	  butzin_2005,
+  author	= {BUTZIN, M and PRANGE, M and LOHMANN, G},
+  title		= {Radiocarbon simulations for the glacial ocean: The effects
+		  of wind stress, Southern Ocean sea ice and Heinrich
+		  events},
+  year		= 2005,
+  volume	= 235,
+  number	= {1-2},
+  month		= {Jun},
+  pages		= {45–61},
+  issn		= {0012-821X},
+  doi		= {10.1016/j.epsl.2005.03.003},
+  url		= {http://dx.doi.org/10.1016/j.epsl.2005.03.003},
+  journal	= {Earth and Planetary Science Letters},
+  publisher	= {Elsevier BV}
+}
+
+@Article{	  danabasoglu_2014,
+  author	= {Danabasoglu, Gokhan and Yeager, Steve G. and Bailey, David
+		  and Behrens, Erik and Bentsen, Mats and Bi, Daohua and
+		  Biastoch, Arne and Böning, Claus and Bozec, Alexandra and
+		  Canuto, Vittorio M. and et al.},
+  title		= {North Atlantic simulations in Coordinated Ocean-ice
+		  Reference Experiments phase II (CORE-II). Part I: Mean
+		  states},
+  year		= 2014,
+  volume	= 73,
+  month		= {Jan},
+  pages		= {76–107},
+  issn		= {1463-5003},
+  doi		= {10.1016/j.ocemod.2013.10.005},
+  url		= {http://dx.doi.org/10.1016/j.ocemod.2013.10.005},
+  journal	= {Ocean Modelling},
+  publisher	= {Elsevier BV}
+}
+
+@Article{	  dutay_2002,
+  author	= {Dutay, J.-C and Bullister, J.L and Doney, S.C and Orr, J.C
+		  and Najjar, R and Caldeira, K and Campin, J.-M and Drange,
+		  H and Follows, M and Gao, Y and et al.},
+  title		= {Evaluation of ocean model ventilation with CFC-11:
+		  comparison of 13 global ocean models},
+  year		= 2002,
+  volume	= 4,
+  number	= 2,
+  month		= {Jan},
+  pages		= {89–120},
+  issn		= {1463-5003},
+  doi		= {10.1016/s1463-5003(01)00013-0},
+  url		= {http://dx.doi.org/10.1016/S1463-5003(01)00013-0},
+  journal	= {Ocean Modelling},
+  publisher	= {Elsevier BV}
+}
+
+@Article{	  enting_1994,
+  author	= {G Enting, I and M L Wigley, T and Heimann, Martin},
+  year		= {1994},
+  month		= {01},
+  pages		= {},
+  title		= {Future Emissions and Concentrations of Carbon Dioxide: Key
+		  Ocean/Atmosphere/Land Analyses},
+  volume	= {31},
+  journal	= {CSIRO Division Atmospheric Research Technical Paper}
+}
+
+@Article{	  fiadeiro_1982,
+  author	= {Fiadeiro, M.E.},
+  year		= {1982},
+  month		= {01},
+  pages		= {537-550},
+  title		= {Three-dimensional modeling of tracers in the deep Pacific
+		  Ocean II. Radiocarbon and the circulation},
+  volume	= {40},
+  journal	= {J. Mar. Res.}
+}
+
+@Article{	  fluckiger_2002,
+  author	= {Flückiger, Jacqueline and Monnin, Eric and Stauffer,
+		  Bernhard and Schwander, Jakob and Stocker, Thomas F. and
+		  Chappellaz, Jérôme and Raynaud, Dominique and Barnola,
+		  Jean-Marc},
+  title		= {High-resolution Holocene N2O ice core record and its
+		  relationship with CH4and CO2},
+  year		= 2002,
+  volume	= 16,
+  number	= 1,
+  month		= {Feb},
+  pages		= {10–1–10–8},
+  issn		= {0886-6236},
+  doi		= {10.1029/2001gb001417},
+  url		= {http://dx.doi.org/10.1029/2001GB001417},
+  journal	= {Global Biogeochemical Cycles},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  haine_2006,
+  author	= {Haine, T. W. N.},
+  title		= {On tracer boundary conditions for geophysical reservoirs:
+		  How to find the boundary concentration from a mixed
+		  condition},
+  year		= 2006,
+  volume	= 111,
+  number	= {C5},
+  issn		= {0148-0227},
+  doi		= {10.1029/2005jc003215},
+  url		= {http://dx.doi.org/10.1029/2005JC003215},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Book{		  honjo_1996,
+  title		= {Fluxes of Particles to the Interior of the Open Oceans},
+  author	= {Honjo, S.},
+  url		= {https://books.google.fr/books?id=FwA6cgAACAAJ},
+  year		= {1996},
+  publisher	= {John Wiley \& Sons}
+}
+
+@Article{	  joos_1997,
+  author	= {Joos, Fortunat and Orr, James C. and Siegenthaler,
+		  Ulrich},
+  title		= {Ocean carbon transport in a box-diffusion versus a general
+		  circulation model},
+  year		= 1997,
+  volume	= 102,
+  number	= {C6},
+  month		= {Jun},
+  pages		= {12367–12388},
+  issn		= {0148-0227},
+  doi		= {10.1029/97jc00470},
+  url		= {http://dx.doi.org/10.1029/97JC00470},
+  journal	= {Journal of Geophysical Research: Oceans},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  key_2004,
+  author	= {Key, R. M. and Kozyr, A. and Sabine, C. L. and Lee, K. and
+		  Wanninkhof, R. and Bullister, J. L. and Feely, R. A. and
+		  Millero, F. J. and Mordy, C. and Peng, T.-H.},
+  title		= {A global ocean carbon climatology: Results from Global
+		  Data Analysis Project (GLODAP)},
+  year		= 2004,
+  volume	= 18,
+  number	= 4,
+  month		= {Dec},
+  pages		= {n/a–n/a},
+  issn		= {0886-6236},
+  doi		= {10.1029/2004gb002247},
+  url		= {http://dx.doi.org/10.1029/2004gb002247},
+  journal	= {Global Biogeochemical Cycles},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  kortzinger_2001,
+  author	= {Körtzinger, Arne and Hedges, John I. and Quay, Paul D.},
+  title		= {Redfield ratios revisited: Removing the biasing effect of
+		  anthropogenic CO2},
+  year		= 2001,
+  volume	= 46,
+  number	= 4,
+  month		= {Jun},
+  pages		= {964–970},
+  issn		= {0024-3590},
+  doi		= {10.4319/lo.2001.46.4.0964},
+  url		= {http://dx.doi.org/10.4319/lo.2001.46.4.0964},
+  journal	= {Limnology and Oceanography},
+  publisher	= {Wiley}
+}
+
+@Manual{	  nemo_manual,
+  author	= {Madec Gurvan and NEMO System Team},
+  title		= {NEMO ocean engine},
+  organization	= {NEMO Consortium},
+  journal	= {Notes du Pôle de modélisation de l\'Institut
+		  Pierre-Simon Laplace (IPSL)},
+  issn		= {1288-1619},
+  number	= {27},
+  publisher	= {Zenodo},
+  doi		= {10.5281/zenodo.1464816},
+  url		= {https://zenodo.org/record/1464816},
+  edition	= {TBD},
+  year		= {TBD}
+}
+
+@Article{	  meunier_2014,
+  author	= {Meunier, Cédric L. and Malzahn, Arne M. and Boersma,
+		  Maarten},
+  title		= {A New Approach to Homeostatic Regulation: Towards a
+		  Unified View of Physiological and Ecological Concepts},
+  year		= 2014,
+  editor	= {Munn, Adam J.Editor},
+  volume	= 9,
+  number	= 9,
+  month		= {Sep},
+  pages		= {e107737},
+  issn		= {1932-6203},
+  doi		= {10.1371/journal.pone.0107737},
+  url		= {http://dx.doi.org/10.1371/journal.pone.0107737},
+  journal	= {PLoS ONE},
+  publisher	= {Public Library of Science (PLoS)}
+}
+
+@Article{	  monnin_2001,
+  author	= {Monnin, E.},
+  title		= {Atmospheric CO2 Concentrations over the Last Glacial
+		  Termination},
+  year		= 2001,
+  volume	= 291,
+  number	= 5501,
+  month		= {Jan},
+  pages		= {112–114},
+  issn		= {1095-9203},
+  doi		= {10.1126/science.291.5501.112},
+  url		= {http://dx.doi.org/10.1126/science.291.5501.112},
+  journal	= {Science},
+  publisher	= {American Association for the Advancement of Science
+		  (AAAS)}
+}
+
+@Article{	  monnin_2004,
+  author	= {Monnin, Eric and Steig, Eric J and Siegenthaler, Urs and
+		  Kawamura, Kenji and Schwander, Jakob and Stauffer, Bernhard
+		  and Stocker, Thomas F and Morse, David L and Barnola,
+		  Jean-Marc and Bellier, Blandine and et al.},
+  title		= {Evidence for substantial accumulation rate variability in
+		  Antarctica during the Holocene, through synchronization of
+		  CO 2 in the Taylor Dome, Dome C and DML ice cores},
+  year		= 2004,
+  volume	= 224,
+  number	= {1-2},
+  month		= {Jul},
+  pages		= {45–54},
+  issn		= {0012-821X},
+  doi		= {10.1016/j.epsl.2004.05.007},
+  url		= {http://dx.doi.org/10.1016/j.epsl.2004.05.007},
+  journal	= {Earth and Planetary Science Letters},
+  publisher	= {Elsevier BV}
+}
+
+@Book{		  monod_1958,
+  title		= {Recherches sur la croissance des cultures
+		  bact{\'e}riennes},
+  author	= {Monod, J.},
+  lccn		= {nlm11031168},
+  series	= {Actualit{\'e}s scientifiques et industrielles},
+  url		= {https://books.google.fr/books?id=yhy6AAAAIAAJ},
+  year		= {1958},
+  publisher	= {Hermann}
+}
+
+@Article{	  mouchet_2013,
+  author	= {Mouchet, Anne},
+  title		= {The Ocean Bomb Radiocarbon Inventory Revisited},
+  year		= 2013,
+  volume	= 55,
+  number	= {3–4},
+  issn		= {0033-8222},
+  doi		= {10.2458/azu\_js\_rc.55.16402},
+  url		= {http://dx.doi.org/10.2458/azu\_js\_rc.55.16402},
+  journal	= {Radiocarbon},
+  publisher	= {Cambridge University Press (CUP)}
+}
+
+@Article{	  naegler_2009,
+  author	= {Naegler, Tobias},
+  title		= {Reconciliation of excess14C-constrained global CO2piston
+		  velocity estimates},
+  year		= 2009,
+  volume	= 61,
+  number	= 2,
+  month		= {Jan},
+  pages		= {372–384},
+  issn		= {1600-0889},
+  doi		= {10.1111/j.1600-0889.2008.00408.x},
+  url		= {http://dx.doi.org/10.1111/j.1600-0889.2008.00408.x},
+  journal	= {Tellus B: Chemical and Physical Meteorology},
+  publisher	= {Informa UK Limited}
+}
+
+@TechReport{	  orr_2000,
+  author	= {Orr, J. and Najjar, R. and Sabine, C. and Joos, F.},
+  title		= {Abiotic-HOWTO. Ocean-Carbon Cycle Model Intercomparison
+		  Project (OCMIP)},
+  url		= {http://ocmip5.ipsl.jussieu.fr/OCMIP/},
+  year		= {2000}
+}
+
+@Article{	  orr_2001,
+  author	= {Orr, James C. and Maier-Reimer, Ernst and Mikolajewicz,
+		  Uwe and Monfray, Patrick and Sarmiento, Jorge L. and
+		  Toggweiler, J. R. and Taylor, Nicholas K. and Palmer,
+		  Jonathan and Gruber, Nicolas and Sabine, Christopher L. and
+		  et al.},
+  title		= {Estimates of anthropogenic carbon uptake from four
+		  three-dimensional global ocean models},
+  year		= 2001,
+  volume	= 15,
+  number	= 1,
+  month		= {Mar},
+  pages		= {43–60},
+  issn		= {0886-6236},
+  doi		= {10.1029/2000gb001273},
+  url		= {http://dx.doi.org/10.1029/2000GB001273},
+  journal	= {Global Biogeochemical Cycles},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  orr_2017,
+  author	= {Orr, James C. and Najjar, Raymond G. and Aumont, Olivier
+		  and Bopp, Laurent and Bullister, John L. and Danabasoglu,
+		  Gokhan and Doney, Scott C. and Dunne, John P. and Dutay,
+		  Jean-Claude and Graven, Heather and et al.},
+  title		= {Biogeochemical protocols and diagnostics for the CMIP6
+		  Ocean Model Intercomparison Project (OMIP)},
+  year		= 2017,
+  volume	= 10,
+  number	= 6,
+  month		= {Jun},
+  pages		= {2169–2199},
+  issn		= {1991-9603},
+  doi		= {10.5194/gmd-10-2169-2017},
+  url		= {http://dx.doi.org/10.5194/gmd-10-2169-2017},
+  journal	= {Geoscientific Model Development},
+  publisher	= {Copernicus GmbH}
+}
+
+@Article{	  palmieri_2015,
+  author	= {Palmiéri, J. and Orr, J. C. and Dutay, J.-C. and
+		  Béranger, K. and Schneider, A. and Beuvier, J. and Somot,
+		  S.},
+  title		= {Simulated anthropogenic CO$_{2}$ storage
+		  and acidification of the Mediterranean Sea},
+  year		= 2015,
+  volume	= 12,
+  number	= 3,
+  month		= {Feb},
+  pages		= {781–802},
+  issn		= {1726-4189},
+  doi		= {10.5194/bg-12-781-2015},
+  url		= {http://dx.doi.org/10.5194/bg-12-781-2015},
+  journal	= {Biogeosciences},
+  publisher	= {Copernicus GmbH}
+}
+
+@Article{	  reimer_2013,
+  author	= {Reimer, Paula J and Bard, Edouard and Bayliss, Alex and
+		  Beck, J Warren and Blackwell, Paul G and Ramsey,
+		  Christopher Bronk and Buck, Caitlin E and Cheng, Hai and
+		  Edwards, R Lawrence and Friedrich, Michael and et al.},
+  title		= {IntCal13 and Marine13 Radiocarbon Age Calibration Curves
+		  0–50,000 Years cal BP},
+  year		= 2013,
+  volume	= 55,
+  number	= 4,
+  pages		= {1869–1887},
+  issn		= {1945-5755},
+  doi		= {10.2458/azu\_js\_rc.55.16947},
+  url		= {http://dx.doi.org/10.2458/azu\_js\_rc.55.16947},
+  journal	= {Radiocarbon},
+  publisher	= {Cambridge University Press (CUP)}
+}
+
+@Article{	  sterner_2003,
+  author	= {Sterner, Robert W. and Elser, James J.},
+  title		= {Ecological Stoichiometry},
+  year		= 2003,
+  month		= {Dec},
+  doi		= {10.1515/9781400885695},
+  url		= {http://dx.doi.org/10.1515/9781400885695},
+  isbn		= 9781400885695,
+  publisher	= {Princeton University Press}
+}
+
+@Article{	  stuiver_1977,
+  author	= {Stuiver, Minze and Polach, Henry A},
+  title		= {Discussion Reporting of 14C Data},
+  year		= 1977,
+  volume	= 19,
+  number	= 03,
+  pages		= {355–363},
+  issn		= {1945-5755},
+  doi		= {10.1017/s0033822200003672},
+  url		= {http://dx.doi.org/10.1017/s0033822200003672},
+  journal	= {Radiocarbon},
+  publisher	= {Cambridge University Press (CUP)}
+}
+
+@Article{	  takahashi_1985,
+  author	= {Takahashi, Taro and Broecker, Wallace S. and Langer,
+		  Sara},
+  title		= {Redfield ratio based on chemical data from isopycnal
+		  surfaces},
+  year		= 1985,
+  volume	= 90,
+  number	= {C4},
+  pages		= 6907,
+  issn		= {0148-0227},
+  doi		= {10.1029/jc090ic04p06907},
+  url		= {http://dx.doi.org/10.1029/jc090ic04p06907},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  toggweiler_1989a,
+  author	= {Toggweiler, J. R. and Dixon, K. and Bryan, K.},
+  title		= {Simulations of radiocarbon in a coarse-resolution world
+		  ocean model: 1. Steady state prebomb distributions},
+  year		= 1989,
+  volume	= 94,
+  number	= {C6},
+  pages		= 8217,
+  issn		= {0148-0227},
+  doi		= {10.1029/jc094ic06p08217},
+  url		= {http://dx.doi.org/10.1029/JC094iC06p08217},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  toggweiler_1989b,
+  author	= {Toggweiler, J. R. and Dixon, K. and Bryan, K.},
+  title		= {Simulations of radiocarbon in a coarse-resolution world
+		  ocean model: 2. Distributions of bomb-produced carbon 14},
+  year		= 1989,
+  volume	= 94,
+  number	= {C6},
+  pages		= 8243,
+  issn		= {0148-0227},
+  doi		= {10.1029/jc094ic06p08243},
+  url		= {http://dx.doi.org/10.1029/JC094iC06p08243},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  wanninkhof_1992,
+  author	= {Wanninkhof, Rik},
+  title		= {Relationship between wind speed and gas exchange over the
+		  ocean},
+  year		= 1992,
+  volume	= 97,
+  number	= {C5},
+  pages		= 7373,
+  issn		= {0148-0227},
+  doi		= {10.1029/92jc00188},
+  url		= {http://dx.doi.org/10.1029/92jc00188},
+  journal	= {Journal of Geophysical Research},
+  publisher	= {American Geophysical Union (AGU)}
+}
+
+@Article{	  wanninkhof_1996,
+  author	= {Wanninkhof, Rik and Knox, Molly},
+  title		= {Chemical enhancement of CO2exchange in natural waters},
+  year		= 1996,
+  volume	= 41,
+  number	= 4,
+  month		= {Jun},
+  pages		= {689–697},
+  issn		= {0024-3590},
+  doi		= {10.4319/lo.1996.41.4.0689},
+  url		= {http://dx.doi.org/10.4319/lo.1996.41.4.0689},
+  journal	= {Limnology and Oceanography},
+  publisher	= {Wiley}
+}
+
+@Article{	  wanninkhof_2014,
+  author	= {Wanninkhof, Rik},
+  title		= {Relationship between wind speed and gas exchange over the
+		  ocean revisited},
+  year		= 2014,
+  volume	= 12,
+  number	= 6,
+  month		= {Jun},
+  pages		= {351–362},
+  issn		= {1541-5856},
+  doi		= {10.4319/lom.2014.12.351},
+  url		= {http://dx.doi.org/10.4319/lom.2014.12.351},
+  journal	= {Limnology and Oceanography: Methods},
+  publisher	= {Wiley}
+}
+
+@Article{	  warner_1985,
+  author	= {Warner, M.J. and Weiss, R.F.},
+  title		= {Solubilities of chlorofluorocarbons 11 and 12 in water and
+		  seawater},
+  year		= 1985,
+  volume	= 32,
+  number	= 12,
+  month		= {Dec},
+  pages		= {1485–1497},
+  issn		= {0198-0149},
+  doi		= {10.1016/0198-0149(85)90099-8},
+  url		= {http://dx.doi.org/10.1016/0198-0149(85)90099-8},
+  journal	= {Deep Sea Research Part A. Oceanographic Research Papers},
+  publisher	= {Elsevier BV}
+}
+
+@Article{	  weiss_1974,
+  author	= {Weiss, R.F.},
+  title		= {Carbon dioxide in water and seawater: the solubility of a
+		  non-ideal gas},
+  year		= 1974,
+  volume	= 2,
+  number	= 3,
+  month		= {Nov},
+  pages		= {203–215},
+  issn		= {0304-4203},
+  doi		= {10.1016/0304-4203(74)90015-2},
+  url		= {http://dx.doi.org/10.1016/0304-4203(74)90015-2},
+  journal	= {Marine Chemistry},
+  publisher	= {Elsevier BV}
+}
+
+@Article{	  woods_2013,
+  author	= {Woods, H. Arthur and Wilson, J. Keaton},
+  title		= {An information hypothesis for the evolution of
+		  homeostasis},
+  year		= 2013,
+  volume	= 28,
+  number	= 5,
+  month		= {May},
+  pages		= {283–289},
+  issn		= {0169-5347},
+  doi		= {10.1016/j.tree.2012.10.021},
+  url		= {http://dx.doi.org/10.1016/j.tree.2012.10.021},
+  journal	= {Trends in Ecology \& Evolution},
+  publisher	= {Elsevier BV}
+}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/blocks.idx
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/blocks.idx	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/blocks.idx	(revision 11422)
@@ -0,0 +1,1 @@
+link ../build/blocks.idx
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/byrd-co2-2008.txt
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/byrd-co2-2008.txt	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/byrd-co2-2008.txt	(revision 11422)
@@ -0,0 +1,273 @@
+Byrd Ice Core CO2 Data for 20-90 KYrBP
+-----------------------------------------------------------------------
+               World Data Center for Paleoclimatology, Boulder
+                                  and
+                     NOAA Paleoclimatology Program
+-----------------------------------------------------------------------
+NOTE: PLEASE CITE ORIGINAL REFERENCE WHEN USING THIS DATA!!!!!
+
+
+NAME OF DATA SET: Byrd Ice Core CO2 Data for 20-90 KYrBP
+
+LAST UPDATE: 10/2008 (Original receipt by WDC Paleo)
+CONTRIBUTORS: Jinho Ahn and Edward J. Brook
+IGBP PAGES/WDCA CONTRIBUTION SERIES NUMBER: 2008-095
+
+WDC PALEO CONTRIBUTION SERIES CITATION: 
+Ahn, J. and E.J. Brook. 2008.
+Byrd Ice Core CO2 Data for 20-90 KYrBP. 
+IGBP PAGES/World Data Center for Paleoclimatology 
+Data Contribution Series # 2008-095. 
+NOAA/NCDC Paleoclimatology Program, Boulder CO, USA.
+
+
+ORIGINAL REFERENCES: 
+References for CO2 data: 
+ 
+Ahn, J. and E.J. Brook. 2008.
+Atmospheric CO2 and Climate on Millennial Time Scales During 
+the Last Glacial Period. 
+Science, 322, 83-85, doi: 10.1126/science.1160832.
+
+Ahn, J. and Brook, E.J.  2007.  
+Atmospheric CO2 and climate from 65 to 30 ka B.P.. 
+Geophysical Research Letters, 34, L10703, doi:10.1029/2007GL029551.
+
+ 
+References for CO2 age:	 
+  
+Blunier-01 age: 
+Blunier, T., and Brook, E.J.  2001. 
+Timing of millennial-scale climate change in Antarctica and Greenland 
+during the last glacial period.  
+Science, 291, 109-112.  
+	   
+Ahn-08 age: 
+Ahn, J. and E.J. Brook. 2008.
+Atmospheric CO2 and Climate on Millennial Time Scales During 
+the Last Glacial Period. 
+Science, 322, 83-85, doi: 10.1126/science.1160832.
+
+
+ABSTRACT (Ahn and Brook 2008):
+Reconstructions of ancient atmospheric carbon dioxide (CO2) variations 
+help us better understand how the global carbon cycle and climate are 
+linked.  We compared CO2 variations on millennial time scales between 
+20,000 and 90,000 years ago with an Antarctic temperature proxy and 
+records of abrupt climate change in the Northern Hemisphere. CO2 
+concentration and Antarctic temperature were positively correlated 
+over millennial-scale climate cycles, implying a strong connection 
+to Southern Ocean processes. Evidence from marine sediment proxies 
+indicates that CO2 concentration rose most rapidly when North Atlantic 
+Deep Water shoaled and stratification in the Southern Ocean was reduced. 
+These increases in CO2 concentration occurred during stadial (cold) 
+periods in the Northern Hemisphere, several thousand years before 
+abrupt warming events in Greenland.
+
+
+
+GEOGRAPHIC REGION: Antarctica
+PERIOD OF RECORD:  90 - 20 KYrBP
+
+FUNDING SOURCES: 
+Gary Comer Science and Education Foundation, and
+US National Science Foundation  grants OPP 0337891 and ATM 0602395.
+
+
+
+DESCRIPTION:  
+Byrd ice core carbon dioxide data for 20-90 KYrBP, analyzed at 
+Oregon State University.  
+
+Byrd Ice Core location: 
+80.01°S , 119.51°W; 1530 m elev. 
+  
+
+
+
+DATA:
+Byrd Ice Core CO2 Data for 20-90 KYrBP
+
+Column 1: Depth (m) 
+Column 2: Blunier 2001 Age (ka before 1950 AD)
+Column 3: Ahn 2008 Age (ka before 1950 AD)
+Column 4: Mean CO2 (ppm)
+Column 5: Number of replicates
+Column 6: Uncertainty (ppm)*
+Column 7: Reference
+
+*Uncertainty is estimated from the standard deviation of the mean for 2~5 ice samples
+
+Depth       Age Bl01  Age Ahn08   Mean CO2    Repl.  Uncert.    Ref.
+1315.91       19.460     19.286     194.36      2     0.97     AB-08
+1332.34       20.061     19.887     191.14      2     0.19     AB-08
+1334.20       20.152     19.978     192.54      2     0.09     AB-08
+1346.28       20.578     20.404     204.27      2     0.48     AB-08
+1353.02       20.759     20.585     195.37      2     0.02     AB-08
+1363.17       21.065     20.891     197.12      2     1.04     AB-08
+1381.14       21.731     21.557     195.81      2     1.66     AB-08
+1401.95       22.399     22.225     199.75      3     4.49     AB-08
+1410.30       22.729     22.555     194.62      2     0.31     AB-08
+1420.27       23.530     23.356     195.97      2     1.88     AB-08
+1430.78       24.824     24.650     194.74      2     1.94     AB-08
+1441.45       26.002     25.828     189.76      2     1.30     AB-08
+1460.20       26.711     26.537     192.21      2     1.28     AB-08
+1470.77       27.148     26.974     184.40      2     1.42     AB-08
+1480.48       27.619     27.445     188.07      2     1.48     AB-08
+1490.87       27.989     27.815     201.96      2     0.46     AB-08
+1496.52       28.135     27.961     204.98      2     1.71     AB-08
+1503.54       28.395     28.221     205.91      3     2.43     AB-08
+1512.46       28.660     28.486     207.48      2     1.73     AB-08
+1523.46       29.147     28.973     205.54      2     0.40     AB-08
+1533.76       29.568     29.396     201.49      2     1.84     AB-08
+1543.63       30.013     29.843     197.51      2     3.18     AB-08
+1552.76       30.412     30.245     195.36      2     0.89     AB-08
+1573.34       31.216     31.053     195.09      3     2.37     AB-08
+1581.93       31.738     31.577     202.29      2     0.38     AB-08
+1594.06       32.328     32.170     203.67      2     0.40     AB-08
+1615.15       33.450     33.297     208.11      2     0.11     AB-08
+1620.38       33.692     33.541     205.25      2     0.53     AB-08
+1631.11       34.183     34.033     201.53      2     1.67     AB-08
+1640.90       34.630     34.484     213.08      2     0.47     AB-08
+1650.56       35.097     34.953     206.62      2     1.72     AB-08
+1658.96       35.428     35.286     209.93      2     1.10     AB-08
+1677.79       36.249     36.111     207.76      2     0.00     AB-08
+1688.63       36.840     36.704     212.63      2     0.99     AB-08
+1693.68       37.167     37.033     213.98      2     1.37     AB-08
+1699.73       37.621     37.488     217.48      2     1.16     AB-08
+1708.70       38.122     37.992     216.21      2     1.03     AB-08
+1714.20       38.428     38.298     216.52      2     2.21     AB-08
+1717.20       38.545     38.415     212.50      2     1.51     AB-08
+1719.47       38.655     38.520     211.09      2     1.83     AB-08
+1723.22       38.850     38.708     214.78      2     2.64     AB-08
+1730.78       39.163     39.006     207.63      2     0.18     AB-08
+1740.51       39.539     39.364     214.06      2     0.14     AB-08
+1743.27       39.651     39.470     213.84      2     1.23     AB-08
+1747.69       39.811     39.621     203.03      2     1.03     AB-08
+1755.15       40.038     39.834     202.11      2     0.45     AB-08
+1760.29       40.172     39.958     203.78      2     2.59     AB-08
+1770.24       40.544     40.311     203.40      2     1.56     AB-08
+1779.99       40.966     40.714     201.30      2     1.46     AB-08
+1790.29       41.585     41.313     202.69      2     2.43     AB-08
+1802.03       42.320     42.025     204.64      2     0.56     AB-08
+1811.74       42.851     42.537     207.18      2     1.53     AB-08
+1821.19       43.591     43.259     210.31      2     0.60     AB-08
+1830.63       44.137     43.786     214.57      2     0.51     AB-08
+1840.93       44.598     44.228     216.83      3     2.50     AB-08
+1844.41       44.760     44.383     215.54      2     1.26     AB-08
+1847.46       44.899     44.516     219.62      2     0.94     AB-08
+1855.09       45.229     44.831     221.00      2     0.60     AB-08
+1859.57       45.526     45.120     217.56      2     0.82     AB-08
+1861.17       45.633     45.223     219.39      2     0.53     AB-08
+1862.59       45.725     45.313     218.62      2     2.56     AB-08
+1864.56       45.852     45.436     217.23      2     2.04     AB-08
+1867.90       46.075     45.654     211.58      2     0.64     AB-08
+1871.26       46.298     45.872     206.99      2     0.29     AB-08
+1873.26       46.431     46.002     209.25      2     1.24     AB-08
+1880.36       46.889     46.448     205.61      2     1.63     AB-08
+1884.88       47.187     46.740     204.28      2     1.02     AB-08
+1892.21       47.687     47.228     205.36      2     1.00     AB-08
+1894.8        47.865     47.402     205.51      2     1.63     AB-07
+1903.72       48.450     47.973     201.79      2     2.79     AB-07
+1909.75       48.874     48.388     211.47      4     1.09     AB-07
+1911.29       48.984     48.495     207.15      4     1.93     AB-07
+1914.31       49.191     48.697     212.35      2     0.57     AB-07
+1920.25       49.596     49.092     213.91      4     2.43     AB-07
+1929.4        50.230     49.712     216.76      2     0.28     AB-07
+1938.5        50.857     50.325     215.07      2     0.30     AB-07
+1943.09       51.175     50.636     218.12      5     2.35     AB-07
+1945.98       51.394     50.850     221.08      3     0.35     AB-07
+1953.17       51.894     51.339     216.69      4     2.96     AB-07
+1956.34       52.193     51.633     217.93      2     2.81     AB-07
+1959.23       52.505     51.941     218.83      2     1.55     AB-07
+1962.18       52.812     52.259     219.08      4     2.10     AB-07
+1963.62       52.963     52.423     215.70      2     1.94     AB-07
+1968.07       53.422     52.923     212.28      2     2.52     AB-07
+1972.66       53.926     53.470     213.25      2     0.74     AB-07
+1978.74       54.577     54.177     205.57      2     0.58     AB-07
+1981.61       54.859     54.486     212.48      4     2.46     AB-07
+1988.98       55.644     55.339     215.94      2     0.96     AB-07
+1995.01       56.317     56.068     215.25      2     0.38     AB-07
+2001.46       57.022     56.833     218.27      2     3.65     AB-07
+2003.23       57.222     57.049     223.09      2     0.30     AB-07
+2013.21       58.096     58.016     222.69      3     2.59     AB-07
+2017.71       58.467     58.421     224.99      2     0.97     AB-07
+2022.42       59.125     59.072     220.11      2     1.49     AB-07
+2026.9        59.806     59.746     224.21      3     1.18     AB-07
+2028.47       60.039     59.976     217.96      2     1.39     AB-07
+2031.5        60.526     60.459     218.85      2     3.26     AB-07
+2037.68       61.451     61.374     210.28      2     1.65     AB-07
+2042.43       62.186     62.102     212.26      2     0.85     AB-07
+2048.32       63.079     62.986     204.65      2     0.39     AB-07
+2051.4        63.526     63.429     206.76      2     2.20     AB-07
+2055.9        64.152     64.048     204.06      2     0.84     AB-07
+2066.85       65.565     65.444     208.22      2     2.01     AB-08
+2069.64       65.938     65.813     207.08      2     2.09     AB-08
+2072.65       66.333     66.204     217.67      2     2.07     AB-08
+2075.59       66.779     66.644     211.79      2     0.25     AB-08
+2075.745      66.818    66.6833     219.64      3     1.17     AB-08
+2076.02       66.890     66.755     222.40      2     0.47     AB-08
+2076.43       66.997     66.861     223.63      2     0.27     AB-08
+2077.02       67.151     67.014     220.43      2     3.79     AB-08
+2080.12       67.959     67.818     244.03      2     5.52     AB-08
+2080.61       68.086     67.944     240.28      2     0.28     AB-08
+2081.10       68.213     68.071     246.47      2     0.93     AB-08
+2081.59       68.340     68.197     247.22      2     2.42     AB-08
+2082.54       68.582     68.435     249.96      3     3.97     AB-08
+2082.64       68.608     68.460     248.32      2     2.08     AB-08
+2083.085      68.721    68.5708     238.70      4     4.19     AB-08
+2083.54       68.837     68.685     238.61      2     0.33     AB-08
+2083.82       68.908     68.755     238.78      2     1.42     AB-08
+2084.14       68.989     68.834     238.84      2     0.02     AB-08
+2084.52       69.086     68.929     231.99      3     4.59     AB-08
+2085.44       69.314     69.149     237.98      2     0.97     AB-08
+2087.02       69.706     69.527     237.26      3     0.40     AB-08
+2087.75       69.886     69.700     233.74      2     0.93     AB-08
+2089.24       70.246     70.048     234.85      2     0.19     AB-08
+2090.16       70.469     70.262     234.35      2     3.03     AB-08
+2093.50       71.337     71.101     237.17      2     0.49     AB-08
+2093.71       71.395     71.158     236.62      3     1.43     AB-08
+2095.46       71.875     71.622     240.58      2     3.79     AB-08
+2097.91       72.515     72.240     246.81      3     2.23     AB-08
+2099.29       72.885     72.598     244.19      1              AB-08
+2100.05       73.073     72.783     246.30      2     0.85     AB-08
+2100.69       73.230     72.937     236.93      2     0.88     AB-08
+2101.27       73.369     73.079     242.80      2     3.41     AB-08
+2101.80       73.492     73.209     241.26      2     0.14     AB-08
+2101.97       73.531     73.251     237.79      4     2.31     AB-08
+2103.15       73.805     73.542     240.63      3     0.85     AB-08
+2103.60       73.909     73.653     235.11      2     0.58     AB-08
+2104.68       74.184     73.944     231.11      2     0.89     AB-08
+2105.52       74.410     74.182     228.82      2     2.08     AB-08
+2106.32       74.656     74.440     223.79      2     1.22     AB-08
+2107.63       75.055     74.858     230.49      2     0.28     AB-08
+2109.17       75.518     75.343     228.85      2     0.25     AB-08
+2110.06       75.783     75.621     226.25      1              AB-08
+2111.20       76.120     75.975     229.45      2     2.14     AB-08
+2113.37       76.765     76.651     229.56      2     1.56     AB-08
+2116.08       77.586     77.513     232.82      3     1.97     AB-08
+2116.73       77.785     77.721     240.83      3     1.24     AB-08
+2120.16       78.809     78.795     235.51      2     0.11     AB-08
+2122.78       79.604     79.628     238.65      2     4.76     AB-08
+2125.62       80.449     80.515     240.08      3     1.03     AB-08
+2126.13       80.635     80.708     233.00      3     1.69     AB-08
+2130.20       82.116     82.248     250.22      2     4.72     AB-08
+2130.67       82.399     82.539     246.47      2     0.04     AB-08
+2130.78       82.466     82.607     244.08      2     2.06     AB-08
+2131.99       83.195     83.354     250.70      2     0.33     AB-08
+2132.50       83.503     83.669     248.75      2     2.37     AB-08
+2132.66       83.600     83.766     237.44      2     2.38     AB-08
+2134.46       84.687     84.855     240.19      2     1.00     AB-08
+2134.70       84.828     84.996     240.36      2     1.19     AB-08
+2135.22       85.133     85.301     233.84      2     0.20     AB-08
+2135.97       85.572     85.740     241.73      2     1.76     AB-08
+2136.25       85.734     85.902     220.23      2     5.01     AB-08
+2136.93       86.127     86.295     225.72      2     1.15     AB-08
+2137.57       86.498     86.666     228.99      3     1.73     AB-08
+2138.02       86.764     86.932     229.26      2     1.58     AB-08
+2138.32       86.942     87.110     218.37      2     0.94     AB-08
+2138.79       87.221     87.389     222.25      2     1.43     AB-08
+2143.57       90.075     90.266     236.19      5     2.31     AB-08
+2144.02       90.342     90.534     235.65      2     2.86     AB-08
+2144.72       90.759     90.953     242.07      3     4.54     AB-08
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/chapters.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/chapters.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/chapters.tex	(revision 11422)
@@ -0,0 +1,4 @@
+\subfile{../subfiles/introduction}
+\subfile{../subfiles/model_description}
+\subfile{../subfiles/model_setup}
+\subfile{../subfiles/miscellaneous}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/definitions.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/definitions.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/definitions.tex	(revision 11422)
@@ -0,0 +1,15 @@
+%% Engine (folder name)
+\def \engine{TOP}
+
+%% Title (variable name already use by 'titling' pkg)
+\def \heading{Tracers in Ocean Paradigm (TOP) \\ The NEMO passive tracers engine}
+
+%% Authors (thanks will apply to the second author)
+\def \firstauthor{}
+\def \secondauthor{NEMO TOP Working Group}
+
+%% IPSL publication number
+\def \ipslnum{28}
+
+%% Zenodo ID, i.e. doi:10.5281/zenodo.\([0-9]*\)
+\def \zid{1471700}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/edc-co2.txt
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/edc-co2.txt	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/edc-co2.txt	(revision 11422)
@@ -0,0 +1,620 @@
+EPICA Dome C Ice Core High Resolution Holocene and Transition CO2 Data
+-----------------------------------------------------------------------
+               World Data Center for Paleoclimatology, Boulder
+                                  and
+                     NOAA Paleoclimatology Program
+-----------------------------------------------------------------------
+NOTE: PLEASE CITE CONTRIBUTORS WHEN USING THIS DATA!!!!!
+
+
+NAME OF DATA SET: 
+EPICA Dome C Ice Core High Resolution Holocene and Transition CO2 Data
+LAST UPDATE: 9/2004 (Original receipt by WDC Paleo)
+CONTRIBUTOR:  Eric Monnin, University of Bern
+IGBP PAGES/WDCA CONTRIBUTION SERIES NUMBER: 2004-055
+
+
+SUGGESTED DATA CITATION: Monnin, E., et al.. 2004. 
+EPICA Dome C Ice Core High Resolution Holocene and Transition CO2 Data. 
+IGBP PAGES/World Data Center for Paleoclimatology 
+Data Contribution Series # 2004-055.
+NOAA/NGDC Paleoclimatology Program, Boulder CO, USA.
+
+
+ORIGINAL REFERENCE:  
+Monnin, E., E.J. Steig, U. Siegenthaler, K. Kawamura, J. Schwander, B. Stauffer, 
+T.F. Stocker, D.L. Morse, J.-M. Barnola, B. Bellier, D. Raynaud, and H. Fischer. 2004.  
+Evidence for substantial accumulation rate variability in Antarctica during the Holocene, 
+through synchronization of CO2 in the Taylor Dome, Dome C and DML ice cores. 
+Earth and Planetary Science Letters, 224, 45-54, doi: 10.1016/j.epsl.2004.05.007. 
+
+
+ADDITIONAL REFERENCES FOR DATA:
+Flückiger, J.,  E. Monnin, B. Stauffer, J. Schwander, T. F. Stocker, J. Chappellaz, 
+D. Raynaud and J.-M. Barnola.  2002.
+High resolution Holocene N2O ice core record and its relationship with CH4 and CO2. 
+Global Biogeochemical Cycles, 16 (1), 1010, doi:10.1029/2001GB001417.
+
+Monnin, E., A. Indermühle, A. Dällenbach, J. Flückiger, B. Stauffer, T. F. Stocker, 
+D. Raynaud, and J.-M. Barnola.  2001. 
+Atmospheric CO2 concentrations over the last glacial termination. 
+Science 291, 112-114.
+
+ 
+ADDITIONAL REFERENCE FOR DATING:
+Schwander, J., J. Jouzel, C. U. Hammer, J.-R. Petit, R. Udisti, and E. Wolff. 2001.
+A tentative chronology for the EPICA Dome Concordia ice core. 
+Geophys. Res. Lett. Vol. 28, No. 22, p. 4243.
+
+
+ABSTRACT (Monnin et al. 2004):
+High resolution records of atmospheric CO2 concentration during the Holocene 
+are obtained from the Dome Concordia and Dronning Maud Land (Antarctica) ice cores. 
+These records confirm that the CO2 concentration varied between 260 and 280 ppmv in 
+the Holocene as measured in the Taylor Dome ice core. However, there are differences 
+in the CO2 records most likely caused by mismatches in timescales. Matching the 
+Taylor Dome timescale to the Dome C timescale by synchronization of CO2 indicates that 
+the accumulation rate at Taylor Dome increased through the Holocene by a factor of two 
+and bears little resemblance to the stable isotope record used as a proxy for temperature. 
+This result shows that different locations experienced substantially different 
+accumulation changes, and casts doubt on the often-used assumption that accumulation 
+rate scales with the saturation vapor pressure as a function of temperature, at least 
+for coastal locations. 
+
+
+GEOGRAPHIC REGION: Antarctica
+PERIOD OF RECORD:  22 KYrBP - present
+
+
+DESCRIPTION: High Resolution CO2 Data for the EPICA Dome C ice core, 
+and derived timescale for Taylor Dome Ice Core. 
+
+
+Core locations: 
+EPICA Dome C:  75° 06'S, 123° 21'E 
+Dronning Maud Land (DML): 75° 00'S, 00° 04'E 
+Taylor Dome:  77° 47'47" S,  158° 43'26" E
+
+
+
+
+Data:
+1. High-resolution EDC CO2 data
+
+Column 1: Depth (m)
+Column 2: Age (Years before 1950 AD, EDC1 Timescale)
+Column 3: CO2 mean (ppmv)
+Column 4: CO2 sigma mean (ppmv) sigma mean is one sigma of the mean value 
+          (of 6 neighboring samples)
+
+
+  Depth      Age    CO2      sigma
+  102.83     173   280.4     1.8
+ 106.885     311   274.9     0.7
+ 107.195     322   277.9     0.7
+ 110.245     427   279.1     1.3
+   110.5     435   281.9     1.1
+ 113.265     530   277.7     0.7
+  115.48     604   281.1     1.1
+ 118.615     709   282.2     0.5
+   121.5     806   280.1     0.6
+ 124.815     917   278.4     1.5
+ 127.015     991   276.6     1.4
+ 129.745    1083   279.1       1
+   132.5    1175   277.7     1.2
+ 134.715    1249   278.7     1.2
+ 138.015    1362   277.4     0.8
+ 141.295    1477   279.2     0.9
+  144.05    1574     280     0.8
+ 146.265    1653   278.9     0.8
+ 149.015    1751   278.7     0.7
+ 151.195    1830     278     1.2
+   154.5    1948   276.9     0.7
+ 157.815    2069   276.7     0.8
+  160.03    2150   276.7     0.8
+ 162.165    2228   277.6     1.3
+ 165.515    2352   277.9     0.5
+  168.28    2453   273.9     1.1
+     171    2550   278.9     0.6
+ 173.135    2625   275.3     1.6
+ 176.515    2743   274.7     1.2
+ 178.715    2820   276.3     0.9
+ 181.445    2918   274.6     0.8
+ 185.845    3078   276.3     1.5
+ 187.515    3138   273.1     1.1
+ 189.715    3219     274     0.3
+     193    3337     275     0.6
+ 196.295    3454   273.4     1.3
+ 198.515    3531     273     0.8
+  201.28    3628   271.5       1
+     204    3724   275.4     0.5
+ 206.195    3802   274.9     1.3
+ 209.515    3921   271.7       1
+ 212.265    4019   271.6     0.7
+     215    4117   272.8     0.8
+ 216.645    4176   271.5     0.9
+  221.05    4335   271.1     0.8
+ 222.715    4395   269.1     0.6
+  225.48    4496   269.8       1
+ 228.195    4596   271.5     0.8
+  232.05    4737   270.7     0.5
+ 233.715    4797   269.3       1
+ 236.465    4895   268.6     1.1
+ 240.265    5033   269.8     1.2
+   242.5    5114   267.6     0.6
+ 244.715    5196   265.3     1.7
+ 248.015    5318   265.2     0.8
+ 250.715    5419   267.6       2
+   253.5    5521   265.9     0.9
+ 256.265    5621   265.5     0.8
+ 259.015    5721   260.7     1.6
+ 260.645    5780   266.7     0.9
+   264.5    5921   265.5     0.8
+ 268.365    6064   263.2     0.6
+ 269.415    6102   262.7     0.9
+ 272.195    6205   261.2     0.7
+ 276.065    6349   261.1     0.4
+ 278.265    6430   259.4     0.6
+  280.53    6514   262.1     0.9
+ 283.715    6631   262.9     0.5
+ 285.965    6713   258.1     1.4
+ 288.165    6792   257.6     0.9
+     292    6930   262.3     0.9
+ 294.745    7031     263     0.7
+ 297.515    7132   260.7     0.6
+ 299.715    7211   258.4     0.8
+     303    7328   260.1     0.6
+ 305.745    7424   260.4     0.4
+ 308.515    7521   259.7     0.9
+  311.26    7617   259.2     0.7
+ 313.995    7714   260.8     1.4
+ 316.745    7813   259.6     0.5
+ 319.515    7915   259.3     0.9
+ 322.265    8017   258.3     1.2
+     325    8118   261.3     0.9
+ 326.545    8174   260.7     0.4
+   330.5    8315   261.8       1
+ 333.265    8412     259     1.1
+ 336.015    8508   260.9     0.7
+ 338.645    8599   260.4     0.6
+   341.5    8697   259.3       1
+ 343.715    8772     262     0.8
+ 347.015    8883   263.7     1.2
+ 349.745    8974   263.8     0.8
+  352.58    9067   265.2     0.9
+ 355.815    9171   260.6     1.7
+ 357.465    9224   260.9     0.6
+ 360.195    9310     263     0.4
+  362.98    9399   263.8     1.2
+ 369.545    9604   264.4     0.4
+  371.23    9657   264.2     0.9
+ 375.045    9776     264     0.3
+ 377.265    9846   263.4     0.1
+ 379.995    9931   265.7     0.5
+ 382.215   10001   264.9     0.4
+ 385.125   10093   267.5     0.4
+ 388.225   10192   266.9     0.6
+ 390.445   10263     266     1.1
+  393.78   10370   265.1     1.6
+ 396.495   10458   267.6     0.7
+  399.28   10550   264.8     0.6
+ 401.995   10640   264.8     0.4
+ 404.185   10712     265     0.8
+  404.78   10732   265.3     0.4
+ 406.385   10785   264.4     1.5
+ 407.495   10822   264.1     0.7
+   409.7   10896   264.2     1.1
+  411.38   10952   264.5     0.4
+  413.03   11008     264     0.5
+  414.75   11066     263     1.3
+  415.73   11099   265.2     0.8
+ 417.065   11144   258.8     0.7
+  418.53   11195   260.8     0.5
+ 420.485   11263   255.4     0.3
+ 421.795   11310   253.9     0.6
+   422.9   11349   253.8     0.8
+   426.1   11468   250.7     1.1
+  427.33   11515   249.7     0.4
+   428.3   11554   251.1     0.3
+ 429.495   11602   250.7     0.9
+  431.73   11695   245.3     1.1
+ 433.785   11784   245.3     0.6
+ 434.995   11838   246.6     0.5
+  437.23   11941   243.2     0.4
+  438.85   12017   240.3     0.3
+ 443.795   12258   237.5     0.5
+  446.03   12372   237.6     0.6
+ 448.745   12511   234.2     0.3
+  450.98   12625   238.3     1.1
+ 454.245   12789   237.3     0.5
+  457.03   12927   237.9     0.2
+ 459.895   13068   237.6     0.6
+  463.63   13252   236.4     0.9
+ 465.245   13332   239.2     0.5
+  467.45   13440   238.6     0.6
+ 470.195   13574   238.6     0.3
+ 473.055   13711   239.1     0.4
+ 479.705   14022   228.5     0.6
+   484.1   14230   228.4     0.7
+ 487.245   14387   226.1     0.6
+  490.03   14532   225.2     0.5
+ 492.195   14647   224.5     0.6
+  496.07   14855     222     0.8
+ 499.345   15037     221     0.8
+  501.58   15166   220.9     0.5
+ 504.195   15323   219.4     0.6
+  506.53   15466     214     0.8
+ 509.245   15637   207.5     0.9
+  512.03   15818   207.7     0.5
+ 514.745   16002   202.9     0.7
+  517.53   16199   200.8       1
+ 520.245   16400   195.2     0.3
+  523.03   16616   193.9     0.5
+ 526.295   16883     191     0.5
+  528.53   17073   188.5     0.7
+ 531.245   17311   188.5     0.7
+  532.93   17463   189.2     0.4
+ 536.745   17815     187     0.2
+  539.53   18074   188.6     0.5
+   542.9   18391   189.4     0.4
+ 543.345   18433   192.3     0.6
+  543.93   18487   188.3     0.6
+ 548.845   18948   188.7     0.2
+  550.51   19104   188.8     0.5
+ 553.245   19360     190     0.8
+  556.03   19621     188     0.9
+  557.89   19795   188.2     0.7
+ 558.195   19824     195     0.7
+  561.53   20137   187.8     0.4
+  564.26   20390   186.9     0.3
+  567.03   20646   186.5     0.3
+ 569.745   20897   184.7     1.2
+  572.53   21156   186.1     0.4
+ 576.325   21511   185.7     1.3
+ 578.105   21676   184.4     0.8
+
+
+2.  CO2 synchronization timescale for Taylor Dome Ice Core
+
+A. Gas age:
+
+ depth(m)    gas age (yr BP 1950)
+      86       94.5
+      90      149.2
+      94      205.2
+      98      260.9
+     102      316.2
+     106        372
+     110      427.9
+     114      483.7
+     118      540.1
+     122      598.1
+     126      658.4
+     130      722.7
+     134      790.3
+     138      860.5
+   142.1      929.8
+   146.1      995.5
+   150.1     1058.1
+   154.1     1119.4
+   158.1     1180.7
+   162.1     1243.2
+   166.1       1308
+   170.1     1377.6
+   174.1     1454.7
+   178.1     1539.6
+   182.1       1633
+   186.1     1731.9
+   190.1     1835.6
+   194.1       1940
+   198.1     2045.1
+   202.1       2150
+   206.1     2254.5
+   210.1     2361.9
+   214.1     2475.5
+   218.1     2594.6
+   222.1     2715.6
+   226.1     2835.7
+   230.1     2954.2
+   234.1     3070.8
+   238.1     3188.2
+   242.1       3308
+   246.1     3429.6
+   250.1     3550.6
+   254.2     3670.1
+   258.2     3787.9
+   262.2     3905.9
+   266.2     4026.1
+   270.2     4153.3
+   274.2     4295.3
+   278.2     4454.1
+   282.2     4629.4
+   286.2       4814
+   290.2     4998.6
+   294.2     5174.8
+   298.2     5342.8
+   302.2     5507.9
+   306.2     5674.9
+   310.2     5846.8
+   314.2     6031.1
+   318.2     6242.5
+   322.2       6502
+   326.2     6830.5
+   330.2     7238.7
+   334.2     7710.2
+   338.2     8215.9
+   342.2     8735.9
+   346.2     9226.8
+   350.2     9762.8
+   354.2    10289.2
+   358.2    10720.5
+   362.3    11224.1
+
+
+
+B. Ice age:
+
+ depth(m)    ice age (yr BP 1950)
+      86     730.1
+    87.3     746.9
+    88.5     763.6
+    89.7     780.4
+    90.9     797.2
+      92     813.9
+    93.2     830.5
+    94.4       847
+    95.5     863.4
+    96.7     879.7
+    97.8     895.9
+    98.9     912.1
+     100     928.3
+   101.2     944.6
+   102.3     961.1
+   103.4     977.6
+   104.6     994.2
+   105.7    1010.5
+   106.8    1026.6
+   107.9    1042.7
+     109      1059
+   110.1    1075.2
+   111.1    1091.5
+   112.2    1107.9
+   113.3    1124.3
+   114.4    1140.8
+   115.5    1157.4
+   116.5      1174
+   117.6    1190.8
+   118.6    1207.9
+   119.7      1225
+   120.8    1242.2
+   121.8    1259.8
+   122.9    1277.8
+   123.9    1295.9
+     125    1314.1
+     126    1332.7
+   127.1    1351.4
+   128.1      1370
+   129.2    1388.5
+   130.2    1407.3
+   131.2    1426.3
+   132.3      1445
+   133.3    1463.6
+   134.4    1482.2
+   135.4    1500.9
+   136.5    1519.5
+   137.5    1537.9
+   138.5      1556
+   139.6    1573.9
+   140.6    1591.7
+   141.6    1609.4
+   142.7    1626.8
+   143.7    1644.1
+   144.7    1661.2
+   145.7    1678.1
+   146.8    1694.6
+   147.8      1711
+   148.8    1727.5
+   149.8    1743.9
+   150.9    1760.3
+   151.9    1776.6
+   152.9    1793.1
+   153.9    1809.6
+   154.9    1826.2
+     156    1842.9
+     157    1859.6
+     158    1876.5
+     159    1893.5
+     160    1910.6
+     161    1927.7
+   162.1    1945.1
+   163.1    1962.8
+   164.1    1980.5
+   165.1    1998.3
+   166.1      2017
+   167.1    2036.8
+   168.1    2056.8
+   169.1    2077.2
+   170.2    2098.8
+   171.2    2121.7
+   172.2      2145
+   173.2    2168.6
+   174.2    2193.2
+   175.2      2219
+   176.2    2244.7
+   177.2    2270.3
+   178.2    2296.7
+   179.3    2323.9
+   180.3      2351
+   181.3    2378.2
+   182.3      2406
+   183.3    2434.1
+   184.3    2462.3
+   185.3    2490.5
+   186.3    2519.3
+   187.3    2548.5
+   188.3    2577.7
+   189.3    2606.7
+   190.4    2635.8
+   191.4      2665
+   192.4    2694.1
+   193.4    2723.2
+   194.4    2752.3
+   195.4    2781.6
+   196.4    2810.8
+   197.4    2839.9
+   198.4    2868.9
+   199.4    2897.8
+   200.4    2926.4
+   201.4    2954.9
+   202.4      2983
+   203.5    3010.9
+   204.5    3038.5
+   205.5      3066
+   206.5    3093.6
+   207.5    3121.2
+   208.5    3148.4
+   209.5    3175.7
+   210.5    3203.4
+   211.5    3231.3
+   212.5      3259
+   213.5    3286.9
+   214.5    3315.4
+   215.5    3344.4
+   216.5    3373.3
+   217.5    3402.5
+   218.6    3431.9
+   219.6    3461.4
+   220.6    3490.9
+   221.6    3520.3
+   222.6    3549.6
+   223.6      3579
+   224.6    3608.4
+   225.6    3637.6
+   226.6    3666.2
+   227.6    3694.6
+   228.6      3723
+   229.6      3751
+   230.6    3778.4
+   231.6    3805.5
+   232.6    3832.5
+   233.6    3859.3
+   234.6      3886
+   235.7    3912.7
+   236.7    3939.3
+   237.7      3966
+   238.7    3992.9
+   239.7    4020.1
+   240.7    4047.4
+   241.7    4074.9
+   242.7    4102.9
+   243.7    4130.9
+   244.7    4158.9
+   245.7    4186.9
+   246.7    4215.2
+   247.7    4243.7
+   248.7    4272.2
+   249.7    4300.6
+   250.8    4328.8
+   251.8    4357.3
+   252.8    4385.9
+   253.8    4414.9
+   254.8    4444.3
+   255.8    4474.3
+   256.8    4504.4
+   257.8    4534.8
+   258.8    4565.6
+   259.8    4596.7
+   260.8      4628
+   261.8    4659.4
+   262.8    4691.3
+   263.8    4723.4
+   264.8    4755.4
+   265.8    4788.2
+   266.8    4821.8
+   267.9    4855.7
+   268.9    4889.6
+   269.9    4924.9
+   270.9    4961.8
+   271.9    4999.1
+   272.9    5036.2
+   273.9    5074.7
+   274.9      5115
+   275.9    5155.8
+   276.9    5196.5
+   277.9    5238.6
+   278.9    5282.7
+   279.9    5327.3
+   280.9    5371.8
+   281.9    5417.1
+   282.9    5463.7
+   283.9    5510.6
+   284.9    5557.4
+   285.9    5604.1
+   286.9    5650.6
+     288    5697.3
+     289    5743.8
+     290    5789.3
+     291    5833.8
+     292    5878.1
+     293    5922.3
+     294    5965.5
+     295    6007.8
+     296    6050.3
+     297      6093
+     298    6135.2
+     299    6177.2
+     300    6219.5
+     301    6262.3
+     302    6305.5
+     303    6349.4
+     304    6393.8
+     305    6438.7
+     306    6484.6
+     307    6531.7
+     308    6579.1
+     309    6626.8
+     310    6676.5
+     311    6728.2
+     312    6780.3
+   313.1    6832.7
+   314.1    6888.4
+   315.1    6947.6
+   316.1    7007.4
+   317.1    7067.1
+   318.1    7132.1
+   319.1    7203.1
+   320.1    7274.9
+   321.1    7346.6
+   322.1      7426
+   323.1    7514.1
+   324.1    7603.5
+   325.1    7693.4
+   326.1    7792.7
+   327.1    7902.5
+   328.1    8013.9
+   329.1    8125.8
+   330.1    8245.7
+   331.1    8373.8
+   332.1    8502.4
+   333.1    8630.8
+   334.1    8761.6
+   335.1    8894.5
+   336.1    9026.4
+   337.1    9157.7
+   338.1    9290.6
+   339.1    9425.8
+   340.1    9561.1
+   341.2    9695.7
+   342.2    9826.2
+   343.2    9951.2
+   344.2   10075.6
+   345.2   10201.2
+   346.2   10331.7
+   347.2   10467.7
+   348.2   10603.6
+   349.2   10739.5
+   350.2   10873.8
+   351.2   11006.9
+   352.2   11139.9
+   353.2     11273
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/keys.idx
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/keys.idx	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/keys.idx	(revision 11422)
@@ -0,0 +1,1 @@
+link ../build/keys.idx
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/modules.idx
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/modules.idx	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/modules.idx	(revision 11422)
@@ -0,0 +1,1 @@
+link ../build/modules.idx
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/parameters.idx
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/parameters.idx	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/parameters.idx	(revision 11422)
@@ -0,0 +1,1 @@
+link ../build/parameters.idx
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/subroutines.idx
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/subroutines.idx	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/subroutines.idx	(revision 11422)
@@ -0,0 +1,1 @@
+link ../build/subroutines.idx
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/thanks.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/thanks.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/main/thanks.tex	(revision 11422)
@@ -0,0 +1,8 @@
+\'{E}th\'{e} Christian, 
+Lovato Tomas, 
+Aumont Olivier, 
+Palmi\'{e}ri Julien, 
+Mouchet Anne, 
+Nurser Georges, 
+Yool Andrew
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/subfiles/introduction.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/subfiles/introduction.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/subfiles/introduction.tex	(revision 11422)
@@ -0,0 +1,47 @@
+\documentclass[../../NEMO/main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% INTRODUCTION
+% ================================================================
+
+\chapter*{Introduction}
+
+TOP (Tracers in the Ocean Paradigm) handles oceanic passive tracers in NEMO. At present, this component provides the physical constraints and boundaries conditions for oceanic tracers transport and represents a generalized, hardwired interface toward biogeochemical models to enable a seamless coupling.
+
+It includes three independent components :  
+
+\begin{itemize}
+        \item a transport code TRP sharing the same advection/diffusion routines with the dynamics, with specific treatment of some features like the surface boundary
+conditions, or the positivity of passive tracers concentrations
+        \item sources and sinks - SMS - models that can be typically biogeochemical, biological or radioactive
+        \item an offline option which is a simplified OPA 9 model using fields of physics variables that are previously stored to disk
+\end{itemize}
+
+There is two ways of coupling TOP to the dynamics :
+
+\begin{itemize}
+        \item \textit{online coupling} : the evolution of passive tracers is computed along with the dynamics
+        \item \textit{offline coupling} : the fields of physics variables are read from files and interpolated at each model time step, with no constraints on the time sampling in the input files
+\end{itemize}
+
+TOP is designed to handle multiple oceanic tracers through a modular approach and it includes different sub-modules :
+
+\begin{itemize}
+        \item the ocean water age module (AGE) tracks down the time-dependent spread of surface waters into the ocean interior
+        \item inorganic carbon (e.g. CFCs, SF6) and radiocarbon (C14) passive tracers can be modeled to assess ocean absorption timescales of anthropogenic emissions and further address water masses ventilation
+        \item a built-in biogeochemical model (PISCES) to simulate lower trophic levels ecosystem dynamics in the global ocean
+        \item a prototype tracer module (MY\_TRC) to enable user-defined cases or the coupling with alternative biogeochemical models ( e.g. BFM, MEDUSA, ERSEM, BFM, ECO3M)
+\end{itemize}
+
+\begin{figure}[ht]        
+\begin{center}
+\vspace{0cm}
+\includegraphics[width=0.80\textwidth]{Fig_TOP_design}
+%\includegraphics[height=6cm,angle=-00]{Fig_TOP_design}
+\caption{A schematic view of NEMO-TOP component}
+\label{topdesign}
+\end{center}   
+\end{figure}
+
+\end{document}
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/subfiles/miscellaneous.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/subfiles/miscellaneous.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/subfiles/miscellaneous.tex	(revision 11422)
@@ -0,0 +1,70 @@
+\documentclass[../../NEMO/main/NEMO_manual]{subfiles}
+
+\begin{document}
+
+\chapter{Miscellaneous}
+
+\section{TOP synthetic Workflow}
+
+\subsection{Model initialization}
+
+\subsection{Time marching procedure}
+
+\section{Coupling an external BGC model using NEMO framework}
+
+The coupling with an external BGC model through the NEMO compilation framework can be achieved in different ways according to the degree of coding complexity of the Biogeochemical model, like e.g., the whole code is made only by one file or it has multiple modules and interfaces spread across several subfolders.\\ \\
+Beside the 6 core files of MY\_TRC module, see (see \label{Mytrc}, let's assume an external BGC model named \textit{"MYBGC"} and constituted by a rather essential coding structure, likely few Fortran files. The new coupled configuration name is NEMO\_MYBGC. \\ \\
+The best solution is to have all files (the modified MY\_TRC routines and the BGC model ones) placed in a unique folder with root \path{<MYBGCPATH>} and to use the \textit{makenemo} external readdressing of MY\_SRC folder. \\ \\
+The coupled configuration listed in \textbf{cfg.txt}  will look like
+
+\begin{minted}{bash}
+   NEMO_MYBGC OPA_SRC TOP_SRC
+\end{minted}
+and the related cpp\_MYBGC.fcm content will be
+%
+\begin{minted}{bash}
+    bld::tool::fppkeys   key_iomput key_mpp_mpi key_top
+\end{minted}
+
+the compilation with \textit{makenemo} will be executed through the following syntax
+
+\begin{minted}{bash}
+   makenemo -n NEMO_MYBGC -m <arch_my_machine> -j 8 -e <MYBGCPATH>
+\end{minted}
+%The makenemo feature ?-e? was introduced to readdress at compilation time the standard MY_SRC folder (usually found in NEMO configurations) with a user defined external one.
+%
+%
+%The compilation of more articulated BGC model code & infrastructure, like in the case of BFM (?BFM-NEMO coupling manual), requires some additional features.
+%
+%As before, let?s assume a coupled configuration name NEMO_MYBGC, but in this case MYBGC model root becomes <MYBGCPATH> that contains 4 different subfolders for biogeochemistry, named initialization, pelagic, and benthic, and a separate one named nemo_coupling including the modified MY_SRC routines. The latter folder containing the modified NEMO coupling interface will be still linked using the makenemo ?-e? option.
+%
+%In order to include the BGC model subfolders in the compilation of NEMO code, it will be necessary to extend the configuration cpp_NEMO_MYBGC.fcm file to include the specific paths of MYBGC folders, as in the following example
+%
+\begin{minted}{bash}
+   bld::tool::fppkeys   key_iomput key_mpp_mpi key_top
+   
+   src::MYBGC::initialization         <MYBGCPATH>/initialization
+   src::MYBGC::pelagic                <MYBGCPATH>/pelagic
+   src::MYBGC::benthic                <MYBGCPATH>/benthic
+
+   bld::pp::MYBGC      1
+   bld::tool::fppflags::MYBGC   %FPPFLAGS
+   bld::tool::fppkeys   %bld::tool::fppkeys MYBGC_MACROS
+\end{minted}
+
+%where MYBGC_MACROS is the space delimited list of macros used in MYBGC model for selecting/excluding specific parts of the code. The BGC model code will be preprocessed in the configuration BLD folder as for NEMO, but with an independent path, like NEMO_MYBGC/BLD/MYBGC/<subforlders>.
+%
+%The compilation will be performed similarly to in the previous case with the following
+%
+%makenemo -n NEMO_MYBGC -m <arch_my_machine> -j 8 -e <MYBGCPATH>/nemo_coupling
+%Note that, the additional lines specific for the BGC model source and build paths, can be written into a separate file, e.g. named MYBGC.fcm, and then simply included in the cpp_NEMO_MYBGC.fcm as follow
+%
+%bld::tool::fppkeys  key_zdftke key_dynspg_ts key_iomput key_mpp_mpi key_top
+%inc <MYBGCPATH>/MYBGC.fcm
+%This will enable a more portable compilation structure for all MYBGC related configurations.
+%
+%Important: the coupling interface contained in nemo_coupling cannot be added using the FCM syntax, as the same files already exists in NEMO and they are overridden only with the readdressing of MY_SRC contents to avoid compilation conflicts due to duplicate routines.
+%
+%All modifications illustrated above, can be easily implemented using shell or python scripting to edit the NEMO configuration cpp.fcm file and to create the BGC model specific FCM compilation file with code paths.
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/subfiles/model_description.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/subfiles/model_description.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/subfiles/model_description.tex	(revision 11422)
@@ -0,0 +1,616 @@
+\documentclass[../../NEMO/main/NEMO_manual]{subfiles}
+
+\newcommand{\cd}{\mathrm{CO_2}}
+\newcommand{\Ct}{\mathrm{C_T}}
+\newcommand{\pacd}{\mathrm{p^a_{CO_2}}}
+\newcommand{\cq}{\mathrm{^{14}C}}
+\newcommand{\Dcq}{\Delta ^{14}\mathrm{C}}
+\newcommand{\Rq}{\mathrm{^{14}{R}}}
+\newcommand{\CODE}[1]{\textsc{#1}}
+%\newcommand{\CODE}[1]{\textcolor{black}{\textsc{#1}}\xspace}
+
+\begin{document}
+
+\chapter{Model Description}
+\label{chap:ModDes}
+\minitoc
+
+\section{Basics}
+\label{sec:Bas}
+
+The time evolution of any passive tracer $C$ follows the transport equation, which is similar to that of active tracer - temperature or salinity :
+
+\begin{equation}
+\frac{\partial C}{\partial t} = {S(C)} -  \frac{1}{b_t} \left[   \frac{\partial e_{2u}\,e_{3u} \;  u\, C}{\partial i} +   \frac{\partial e_{1v}\,e_{3v} \;  uv, C}{\partial i}  \right] + \frac{1}{e_{3t}} \frac{\partial w\, C}{\partial k} + D^{lC} + D^{vC}
+\label{Eq_tracer}
+\end{equation}
+
+where expressions of $D^{lC}$ and $D^{vC}$ depend on the choice for the lateral and vertical subgrid scale parameterizations, see equations 5.10 and 5.11 in \citep{nemo_manual} 
+
+{S(C)} , the first term on the right hand side of \ref{Eq_tracer}; is the SMS - Source Minus Sink - inherent to the tracer.  In the case of biological tracer such as phytoplankton, {S(C)} is the balance between phytoplankton growth and its decay through mortality and grazing. In the case of a tracer comprising carbon,  {S(C)} accounts for gas exchange, river discharge, flux to the sediments, gravitational sinking and other biological processes. In the case of a radioactive tracer, {S(C)} is simply loss due to radioactive decay.
+
+The second term (within brackets) represents the advection of the tracer in the three directions. It can be interpreted as the budget between the incoming and outgoing tracer fluxes in a volume $T$-cells $b_t= e_{1t}\,e_{2t}\,e_{3t}$ 
+
+The third term  represents the change due to lateral diffusion. 
+
+The fourth term is change due to vertical diffusion, parameterized as eddy diffusion to represent vertical turbulent fluxes :
+
+\begin{equation}
+D^{vC} =  \frac{1}{e_{3t}} \frac{\partial}{\partial k} \left[  A^{vT} \frac{\partial C}{\partial k} \right]
+\label{Eq_trczdf}
+\end{equation}
+
+where $A^{vT}$ is the vertical eddy diffusivity coefficient of active tracers
+
+\section{The NEMO-TOP interface}
+\label{sec:TopInt}
+
+TOP is the NEMO hardwired interface toward biogeochemical models and provide the physical constraints/boundaries for oceanic tracers. It consists of a modular framework to handle multiple ocean tracers, including also a variety of built-in modules.
+
+This component of the NEMO framework allows one to exploit available modules  and further develop a range of applications, spanning from the implementation of a dye passive tracer to evaluate dispersion processes (by means of MY\_TRC), track water masses age (AGE module), assess the ocean interior penetration of persistent chemical compounds (e.g., gases like CFC or even PCBs), up to the full set of equations involving marine biogeochemical cycles.
+
+TOP interface has the following location in the code repository : \path{<repository>/src/TOP/}
+
+and the following modules are available:
+
+% -----------  tableau  ------------------------------------
+\begin{itemize}
+        \item \textbf{TRP}    	    :    Interface to NEMO physical core for computing tracers transport
+        \item \textbf{CFC}	    :    Inert carbon tracers (CFC11,CFC12, SF6)
+        \item \textbf{C14}	    :    Radiocarbon passive tracer
+        \item \textbf{AGE}	    :    Water age tracking
+        \item \textbf{MY\_TRC}  :	Template for creation of new modules and external BGC models coupling
+        \item \textbf{PISCES}    :	 Built in BGC model. See \citep{aumont_2015} for a throughout description.
+\end{itemize}
+%  ----------------------------------------------------------
+
+\section{The transport component : TRP}
+
+The passive tracer transport component  shares the same advection/diffusion routines with the dynamics, with specific treatment of some features like the surface boundary conditions, or the positivity of passive tracers concentrations.
+ 
+ \subsection{ Advection}
+%------------------------------------------namtrc_adv----------------------------------------------------
+\nlst{namtrc_adv}
+%-------------------------------------------------------------------------------------------------------------
+The advection schemes used for the passive tracers are the same than the ones for $T$ and $S$ and described in section 5.1 of \citep{nemo_manual}. The choice of an advection scheme  can be selected independently and  can differ from the ones used for active tracers. This choice is made in the \textit{namtrc\_adv} namelist, by  setting to \textit{true} one and only one of the logicals \textit{ln\_trcadv\_xxx}, the same way of what is done for dynamics.
+cen2, MUSCL2, and UBS are not \textit{positive} schemes meaning that 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
+
+ \subsection{ Lateral diffusion}
+%------------------------------------------namtrc_ldf----------------------------------------------------
+\nlst{namtrc_ldf}
+%-------------------------------------------------------------------------------------------------------------
+In NEMO v4.0, the passive tracer diffusion has necessarily the same form as the active tracer diffusion, meaning that the numerical scheme must be the same. However the passive tracer mixing coefficient can be chosen as a multiple of the active ones by changing the value of \textit{rn\_ldf\_multi} in namelist \textit{namtrc\_ldf}. The choice of numerical scheme is then set  in the \ngn{namtra\_ldf} namelist for the dynamic described in section 5.2 of \citep{nemo_manual}. 
+
+
+%-----------------We also offers the possibility to increase zonal equatorial diffusion for passive tracers by introducing an enhanced zonal diffusivity coefficent in the equatorial domain which can be defined by the equation below :
+%-----------------\begin{equation} \label{eq:traqsr_iradiance}
+%-----------------Aht  = Aht *  rn_fact_lap * \exp( - \max( 0., z -1000  ) / 1000}  \quad \text{for $L=1$ to $N$}  
+%-----------------\end{equation}
+
+ \subsection{ Tracer damping}
+ 
+%------------------------------------------namtrc_dmp----------------------------------------------------
+\nlst{namtrc_dmp}
+%-------------------------------------------------------------------------------------------------------------
+
+The use of newtonian damping  to climatological fields or observations is also coded, sharing the same routine dans active tracers. Boolean variables are defined in the namelist\_top\_ref to select the tracers on which restoring is applied
+Options are defined through the  \ngn{namtrc\_dmp} namelist variables. The restoring term is added when the namelist parameter \np{ln\_trcdmp} is set to true. The restoring coefficient is a three-dimensional array read in a file, which name is specified by the namelist variable \np{cn\_resto\_tr}. This netcdf file can be generated using the DMP\_TOOLS tool.
+
+ \subsection{ Tracer positivity}
+ 
+%------------------------------------------namtrc_rad----------------------------------------------------
+\nlst{namtrc_rad}
+%-------------------------------------------------------------------------------------------------------------
+
+Sometimes, numerical scheme can generates negative values of passive tracers concentration that must be positive. For exemple,  isopycnal diffusion can created extrema. The trcrad routine artificially corrects negative concentrations with a very crude solution that either sets negative concentration to zero without adjusting the tracer budget, or by removing negative concentration and keeping mass conservation.
+The treatment of negative concentrations is an option and can be selected in the namelist \ngn{namtrc\_rad} by setting the parameter \np{ln\_trcrad}  to true.
+
+\section{The SMS modules}
+
+\label{SMS_models}
+%------------------------------------------namtrc_sms----------------------------------------------------
+%\nlst{namtrc}
+%-------------------------------------------------------------------------------------------------------------
+
+\subsection{Ideal Age}
+%------------------------------------------namage----------------------------------------------------
+%
+\nlst{namage}
+%----------------------------------------------------------------------------------------------------------
+
+
+ An `ideal age' tracer is integrated online in TOP when \textit{ln\_age} = \texttt{.true.} in namelist \textit{namtrc}. This tracer marks the length of time in units of years that fluid has spent in the interior of the ocean, insulated from exposure to the atmosphere. Thus, away from the surface for $z<-H_{\mathrm{Age}}$ where $H_{\mathrm{Age}}$ is specified by the \textit{namage} namelist variable \textit{rn\_age\_depth}, whose default value is 10~m, there is a source $\mathrm{SMS_{\mathrm{Age}}}$ of the age tracer $A$:
+\begin{equation}
+  \label{eq:TOP-age-interior}
+  \mathrm{SMS_{\mathrm{Age}}} = 1 \mathrm{yr}\;^{-1} = 1/T_{\mathrm{year}},
+ \end{equation}
+ where the length of the current year $T_{\mathrm{year}} = 86400*N_{\mathrm{days\;in\;current\; year}}\;\mathrm{s}$, where $N_{\mathrm{days\;in\;current\; year}}$ may be 366 or 365 depending on whether the current year is a leap year or not.
+ Near the surface, for $z>-H_{\mathrm{Age}}$, ideal age is relaxed back to zero:
+\begin{equation}
+  \label{eq:TOP-age-surface}
+   \mathrm{SMS_{\mathrm{Age}}} = -\lambda_{\mathrm{Age}}A,
+ \end{equation}
+ where the relaxation rate $\lambda_{\mathrm{Age}}$  (units $\mathrm{s}\;^{-1}$) is specified by the \textit{namage} namelist variable \textit{rn\_age\_kill\_rate} and has a default value of 1/7200~s. Since this relaxation is applied explicitly, this relaxation rate in principle should not exceed $1/\Delta t$, where $\Delta t$ is the time step used to step forward passive tracers (2 * \textit{nn\_dttrc * rn\_rdt} when the default  leapfrog time-stepping scheme is employed).
+
+ Currently the 1-dimensional reference depth of the grid boxes is used rather than the dynamically evolving depth to determine whether the age tracer is incremented or relaxed to zero. This means that the tracer only works correctly in z-coordinates. To ensure that the forcing is independent of the level thicknesses, where the tracer cell at level $k$ has its upper face $z=-depw(k)$ above the depth $-H_{\mathrm{Age}}$, but its lower face $z=-depw(k+1)$ below that depth, then the age source
+ \begin{equation}
+  \label{eq:TOP-age-mixed}
+   \mathrm{SMS_{\mathrm{Age}}} = -f_{\mathrm{kill}}\lambda_{\mathrm{Age}}A +f_{\mathrm{add}}/T_{\mathrm{year}} ,
+ \end{equation}
+ where
+ \begin{align}
+    f_{\mathrm{kill}} &= e3t_k^{-1}(H_{\mathrm{Age}} - depw(k)) , \\
+    f_{\mathrm{add}} &= 1 - f_{\mathrm{kill}}.
+ \end{align}
+
+
+ This implementation was first used in the CORE-II intercomparison runs described e.g.\ in \citet{danabasoglu_2014}.
+
+\subsection{Inert carbons tracer}
+
+%------------------------------------------namage----------------------------------------------------
+%
+\nlst{namcfc}
+%----------------------------------------------------------------------------------------------------------
+
+Chlorofluorocarbons 11 and 12 (CFC-11 and CFC-12), and sulfur hexafluoride (SF6), are synthetic chemicals manufactured for industrial and domestic applications from the early 20th century onwards.
+CFC-11 (CCl$_{3}$F) is a volatile liquid at room temperature, and was widely used in refrigeration. CFC-12 (CCl$_{2}$F$_{2}$) is a gas at room temperature, and, like CFC-11, was widely used as a refrigerant,
+and additionally as an aerosol propellant. SF6 (SF$_{6}$) is also a gas at room temperature, with a range of applications based around its property as an excellent electrical insulator (often replacing more toxic alternatives).
+All three are relatively inert chemicals that are both non-toxic and non-flammable, and their wide use has led to their accumulation within the Earth's atmosphere. Large-scale production of CFC-11 and CFC-12 began in the 1930s, while production of SF6 began in the 1950s, and their atmospheric concentration time-histories are shown in Figure \ref{img_cfcatm}.
+As can be seen in the figure, while the concentration of SF6 continues to rise to the present  day, the concentrations of both CFC-11 and CFC-12 have levelled off and declined since around the 1990s.
+These declines have been driven by the Montreal Protocol (effective since August 1989), which has banned the production of CFC-11 and CFC-12 (as well as other CFCs) because of their role in the depletion of
+stratospheric ozone (O$_{3}$), critical in decreasing the flux of ultraviolet radiation to the Earth's surface. Separate to this role in ozone-depletion, all three chemicals are significantly more potent greenhouse gases 
+than CO$_{2}$ (especially SF6), although their relatively low atmospheric concentrations limit their role in climate change. \\
+
+% Chlorofluorocarbons 11 and 12 (CFC-11 and CFC-12), and sulfur hexafluoride (SF6),
+% are greenhouse gases that have been released into the atmosphere by human activities.
+% In the case of CFC-11 and CFC-12, this release began in the 1930s, and atmospheric
+% concentrations increased until around the late 1990s afterwhich they began to decline in
+% response to the Montreal Protocol.
+% In the case of SF6, release began in the 1950s 
+% This release began in the 1930s for CFC-11 and CFC-12, and the 1950s for SF6, and
+% regularly increasing their atmospheric concentration until the 1090s, 2000s for respectively CFC11, CFC12, 
+% and is still increasing, and SF6 (see Figure \ref{img_cfcatm}).  \\
+
+The ocean is a notable sink for all three gases, and their relatively recent occurrence in the atmosphere, coupled to the ease of making high precision measurements of their dissolved concentrations, has made them
+valuable in oceanography. % for tracking interior ventilation and mixing.
+Because they only enter the ocean via surface air-sea exchange, and are almost completely chemically and biologically inert, their distribution within the ocean interior reveals its ventilation via transport and mixing.
+Measuring the dissolved concentrations of the gases -- as well as the mixing ratios between them -- shows circulation pathways within the ocean as well as water mass ages (i.e. the time since last contact with the
+atmosphere). This feature of the gases has made them valuable across a wide range of oceanographic problems. One use lies in ocean modelling, where they can be used to evaluate the realism of the circulation and 
+ventilation of models, key for understanding the behaviour of wider modelled marine biogeochemistry (e.g. \citep{dutay_2002,palmieri_2015}). \\
+
+Modelling these gases (henceforth CFCs) in NEMO is done within the passive tracer transport module, TOP, using the conservation state equation \ref{Eq_tracer}
+
+Advection and diffusion of the CFCs in NEMO are calculated by the physical module, OPA,
+whereas sources and sinks are done by the CFC module within TOP. 
+The only source for CFCs in the ocean is via air-sea gas exchange at its surface, and since CFCs are generally 
+stable within the ocean, we assume that there are no sinks (i.e. no loss processes) within the ocean interior. 
+Consequently, the sinks-minus-sources term for CFCs consists only of their air-sea fluxes, $F_{cfc}$, as
+described in the Ocean Model Inter-comparison Project (OMIP) protocol \citep{orr_2017}:
+
+% Because CFCs being stable in the ocean, we consider that there is no CFCs sink.
+% The only CFC source in the ocean is through the Air-Sea gas exchange at the surface.
+% These are calculated as air-sea fluxes (F$_{cfc}$), as described in the OMIP6 protocol \citep{artOMIP6}:
+
+\begin{eqnarray}
+F_{cfc} = K_{w} \, \cdot \, (C_{sat} - C_{surf}) \, \cdot  \, (1 - f_{i})
+\label{equ_CFC_flux}
+\end{eqnarray}  
+
+Where $K_{w}$ is the piston velocity (in m~s$^{-1}$), as defined in Equation \ref{equ_Kw}; 
+$C_{sat}$ is the saturation concentration of the CFC tracer, as defined in Equation \ref{equ_C_sat}; 
+$C_{surf}$ is the local surface concentration of the CFC tracer within the model (in mol~m$^{-3}$); 
+and $f_{i}$ is the fractional sea-ice cover of the local ocean (ranging between 0.0 for ice-free ocean,
+through to 1.0 for completely ice-covered ocean with no air-sea exchange).
+
+The saturation concentration of the CFC, $C_{sat}$, is calculated as follows:
+
+\begin{eqnarray}
+C_{sat} = Sol \, \cdot \, P_{cfc}
+\label{equ_C_sat}
+\end{eqnarray}  
+
+Where $Sol$ is the gas solubility in mol~m$^{-3}$~pptv$^{-1}$, as defined in Equation \ref{equ_Sol_CFC}; 
+and $P_{cfc}$ is the atmosphere concentration of the CFC (in parts per trillion by volume, pptv).
+This latter concentration is provided to the model by the historical time-series of \citet{bullister_2017}.
+This includes bulk atmospheric concentrations of the CFCs for both hemispheres -- this is necessary because of 
+the geographical asymmetry in the production and release of CFCs to the atmosphere. 
+Within the model, hemispheric concentrations are uniform, with the exception of the region between 
+10$^{\circ}$N and 10$^{\circ}$ in which they are linearly interpolated.
+
+The piston velocity $K_{w}$ is a function of 10~m wind speed (in m~s$^{-1}$) and sea surface temperature, 
+$T$ (in $^{\circ}$C), and is calculated here following \citet{wanninkhof_1992}:
+
+\begin{eqnarray}
+K_{w} = X_{conv} \, \cdot \, a \, \cdot \, u^2 \, \cdot \, \sqrt{ \frac{Sc(T)}{660} }
+\label{equ_Kw}
+\end{eqnarray} 
+
+Where $X_{conv}$ = $\frac{0.01}{3600}$, a conversion factor that changes the piston velocity 
+from cm~h$^{-1}$ to m~s$^{-1}$; 
+$a$ is a constant re-estimated by \citet{wanninkhof_2014} to 0.251 (in $\frac{cm~h^{-1}}{(m~s^{-1})^{2}}$);
+and $u$ is the 10~m wind speed in m~s$^{-1}$ from either an atmosphere model or reanalysis atmospheric forcing.
+$Sc$ is the Schmidt number, and is calculated as follow, using coefficients from \citet{wanninkhof_2014} (see Table \ref{tab_Sc}).
+
+\begin{eqnarray}
+Sc =  a0 + (a1 \, \cdot \, T) + (a2  \, \cdot \, T^2) + (a3 \, \cdot \, T^3) + (a4 \, \cdot \, T^4)
+\label{equ_Sc}
+\end{eqnarray} 
+
+The solubility, $Sol$, used in Equation \ref{equ_C_sat} is calculated in mol~l$^{-1}$~atm$^{-1}$, 
+and is specific for each gas. 
+It has been experimentally estimated by \citet{warner_1985} as a function of temperature 
+and salinity:
+
+% AXY: this equation looks both weird and possibly wrong; it doesn't look like the one in the
+% code version that I have to hand, although this might be out of date; in any case, I'dag
+% strongly suggest avoiding the use of the \frac{}{100}, and instead substitute a term that is
+% "degrees Kelvin divided by 100" (which is weird in itself); and make this term use Celcius 
+% so that you're not using T twice in different ways
+
+\begin{eqnarray}
+\ln{(Sol)} = a_1 + \frac{a_2}{ T_{X}} + a_3 \, \cdot \, \ln{ T_{X} } + a_4 \, \cdot \, T_{X}^2 + S \, \cdot \, ( b_1 + b_2 \, \cdot \, T_{X} + b_3 \, \cdot \, T_{X}^2 )
+\label{equ_Sol_CFC}
+\end{eqnarray}  
+
+% \begin{eqnarray}
+% \ln{(Sol)} = a1 + a2 \, \frac{100}{T} + a3 \, \ln{ (\frac{T}{100}) } + a4 \, \frac{T}{100}^2 + S \, ( b1 + b2 \, \frac{T}{100} + b3 \, \frac{T}{100}^2 )
+% \label{equ_Sol_CFC}
+% \end{eqnarray}  
+
+Where $T_{X}$ is $\frac{T + 273.16}{100}$, a function of temperature; 
+and the $a_{x}$ and $b_{x}$ coefficients are specific for each gas (see Table \ref{tab_ref_CFC}).
+This is then converted to mol~m$^{-3}$~pptv$^{-1}$ assuming a constant atmospheric surface pressure of 1~atm.
+The solubility of CFCs thus decreases with rising $T$ while being relatively insensitive to salinity changes. 
+Consequently, this translates to a pattern of solubility where it is greatest in cold, polar regions (see Figure \ref{img_cfcsol}).
+
+% AXY: not 100% sure about the units below; they might be in nanomol, or in seconds or years
+
+The standard outputs of the CFC module are seawater CFC concentrations (in mol~m$^{-3}$), the net air-sea flux (in mol~m$^{-2}$~d$^{-1}$) and the cumulative net air-sea flux (in mol~m$^{-2}$).
+Using XIOS, it is possible to obtain outputs such as the vertical integral of CFC concentrations (in mol~m$^{-2}$; see Figure \ref{img_cfcinv}).
+This property, when divided by the surface CFC concentration, estimates the local penetration depth (in m) of the CFC.
+
+% AXY: not sure what's meant by some of the below; I've tried to reword it above
+% The standard outputs of the CFC module are the CFCs concentration in the sea water, and the records of the outputs-frequency-averaged as well as the total air-sea fluxes.
+% Using XIOS, it is also possible to ask for the CFCs vertical inventory in the output file (see Figure cfc inventory example ?).
+
+\subsubsection{Notes}
+
+In comparison to the OMIP protocol, the CFC module in NEMO has several differences:
+
+% AXY: consider an itemized list here if you've got a list of differences
+
+For instance, C$_{sat}$ is calculated for a fixed surface pressure of 1atm, what could be corrected in a further version of the module.
+
+
+\begin{table}[!t]
+\caption{Coefficients for fit of the CFCs solubility (Eq. \ref{equ_Sol_CFC}).}
+\vskip4mm
+\centering
+\begin{tabular}{l l l l l l l l l}
+\hline 
+Gas   & & a1 & a2 & a3 & a4 & b1 & b2 & b3 \\          
+\hline
+CFC-11 & & -218.0971 & 298.9702 & 113.8049 & -1.39165 & -0.143566  & 0.091015   & -0.0153924 \\
+CFC-12 & & -229.9261 & 319.6552 & 119.4471 & -1.39165 & -0.142382  & 0.091459   & -0.0157274 \\
+SF6    & & -80.0343  & 117.232  & 29.5817  & 0.0      & 0.0335183  & -0.0373942 & 0.00774862 \\
+\hline
+\end{tabular} 
+\label{tab_ref_CFC}
+\end{table}
+
+
+\begin{table}[!t]
+\caption{Coefficients for fit of the CFCs Schmidt number (Eq. \ref{equ_Sc}). }
+\vskip4mm
+\centering
+\begin{tabular}{l l l l l l l }
+\hline 
+Gas  & & a0 & a1 & a2 & a3 & a4 \\          
+\hline
+CFC-11 & & 3579.2  & -222.63 & 7.5749 & -0.14595 & 0.0011874   \\
+CFC-12 & & 3828.1  & -249.86 & 8.7603 & -0.1716  & 0.001408    \\
+SF6    & & 3177.5  & -200.57 & 6.8865 & -0.13335 & 0.0010877   \\
+\hline
+\end{tabular} 
+\label{tab_Sc}
+\end{table}
+
+%% -----------------------------------
+%% -----------------------------------
+%% Figures %%
+
+
+\begin{figure}[!h]
+\centering
+\includegraphics[width=0.80\textwidth]{CFC-atm-evol}
+  \caption{Atmospheric CFC11, CFC12 and SF6 partial pressure evolution in both hemispheres.}
+\label{img_cfcatm}
+\end{figure}
+
+\begin{figure}[!h]
+\centering
+\includegraphics[width=0.80\textwidth]{CFC_solub}
+  \caption{CFC11 solubility in mol m$^{-3}$ pptv$^{-1}$, calculated from the World Ocean Atlas 2013 temperature and salinity annual climatology.}
+\label{img_cfcsol}
+\end{figure}
+
+\begin{figure}[!h]
+\centering
+\includegraphics[width=0.80\textwidth]{CFC_inventory}
+  \caption{CFC11 vertical inventory in $\mu$mol m$^{-2}$, from one of the UK Earth System Model 1 model (UKESM1 - which uses NEMO as ocean component, with TOP for the passive tracers) historical run at year 2000.}
+\label{img_cfcinv}
+\end{figure}
+
+
+\subsection{Radiocarbon}
+
+%------------------------------------------namage----------------------------------------------------
+%
+\nlst{namc14_fcg}
+\nlst{namc14_typ}
+\nlst{namc14_sbc}
+%----------------------------------------------------------------------------------------------------------
+
+The C14 package implemented in NEMO by Anne Mouchet models ocean $\Dcq$. It offers several possibilities: $\Dcq$ as a physical tracer of the ocean ventilation (natural $\cq$), assessment of bomb radiocarbon uptake, as well as transient studies of paleo-historical ocean radiocarbon distributions. 
+
+\subsubsection{Method}
+
+ Let  $\Rq$ represent the ratio of $\cq$ atoms to the total number of carbon atoms in the sample, i.e. $\cq/\mathrm{C}$. Then, radiocarbon anomalies are reported as
+\begin{equation}
+\Dcq = \left( \frac{\Rq}{\Rq_\mathrm{ref}} - 1 \right) 10^3, \label{eq:c14dcq}
+\end{equation}
+where $\Rq_{\textrm{ref}}$ is a reference ratio. For the purpose of ocean ventilation studies $\Rq_{\textrm{ref}}$ is set to one.
+
+Here we adopt the approach of \cite{fiadeiro_1982} and \cite{toggweiler_1989a,toggweiler_1989b} in which  the ratio $\Rq$ is transported rather than the individual concentrations C and $\cq$.
+This approach calls for a strong assumption, i.e., that of a homogeneous and constant dissolved inorganic carbon (DIC) field \citep{toggweiler_1989a,mouchet_2013}. While in terms of
+oceanic $\Dcq$, it yields similar results to approaches involving carbonate chemistry, it underestimates the bomb radiocarbon inventory because it assumes a constant air-sea $\cd$ disequilibrium (Mouchet, 2013). Yet, field reconstructions of the ocean bomb $\cq$ inventory are also biased low \citep{naegler_2009} since they assume that the anthropogenic perturbation did not affect ocean DIC since the pre-bomb epoch. For these reasons, bomb $\cq$ inventories obtained with the present method are directly comparable to reconstructions based on field measurements.
+
+This simplified approach also neglects the effects of fractionation (e.g.,  air-sea exchange) and of biological processes. Previous studies by \cite{bacastow_1990} and \cite{joos_1997} resulted in nearly identical $\Dcq$ distributions among experiments considering biology or not.
+Since observed $\Rq$ ratios are corrected for the isotopic fractionation when converted to the standard $\Dcq$ notation \citep{stuiver_1977} the model results are directly comparable to observations. 
+
+Therefore the simplified approach is justified for the purpose of assessing the circulation and ventilation of OGCMs.
+
+The equation governing the transport of $\Rq$  in the ocean is
+\begin{equation}
+\frac{\partial}{\partial t} {\Rq} =  - \bigtriangledown \cdot ( \mathbf{u} \Rq - \mathbf{K} \cdot \bigtriangledown \Rq )  - \lambda \Rq, \label{eq:quick}
+\end{equation}
+where $\lambda$ is the radiocarbon decay rate, ${\mathbf{u}}$ the 3-D velocity field, and $\mathbf{K}$ the diffusivity tensor.
+
+At the air-sea interface a Robin boundary condition \citep{haine_2006} is applied to \eqref{eq:quick}, i.e., the flux
+through the interface is proportional to the difference in the ratios between
+the ocean and the atmosphere
+\begin{equation}
+\mathcal{\!F} =  \kappa_{R}  (\Rq  - \Rq_{a} ), \label{eq:BCR}
+\end{equation}
+where $\mathcal{\!F}$ is the flux out of the ocean, and $\Rq_{a}$ is the atmospheric $\cq/\mathrm{C}$ ratio. The transfer velocity $ \kappa_{R} $ for the radiocarbon ratio in \eqref{eq:BCR} is computed as
+\begin{equation}
+ \kappa_{R} =  \frac{\kappa_{\cd} K_0}{\overline{\Ct}} \, \pacd   \label{eq:Rspeed}
+\end{equation}
+with $\kappa_{\cd}$ the carbon dioxide transfer or piston velocity, $K_0$ the $\cd$ solubility in seawater, $\pacd$ the atmospheric $\cd$ pressure at sea level, and $\overline{\Ct}$ the average sea-surface dissolved inorganic carbon concentration.
+
+
+The $\cd$ transfer velocity is based on the empirical formulation of \cite{wanninkhof_1992} with chemical enhancement \citep{wanninkhof_1996,wanninkhof_2014}. The original formulation is modified to account for the reduction of the  air-sea exchange rate in the presence of sea ice. Hence
+\begin{equation}
+\kappa_\cd=\left( K_W\,\mathrm{w}^2 + b  \right)\, (1-f_\mathrm{ice})\,\sqrt{660/Sc}, \label{eq:wanc14}
+\end{equation}
+with $\mathrm{w}$ the wind magnitude, $f_\mathrm{ice}$ the fractional ice cover, and $Sc$ the Schmidt number.
+$K_W$ in \eqref{eq:wanc14} is an empirical coefficient with dimension of an inverse velocity.
+The chemical enhancement term $b$ is represented as a function of temperature $T$ \citep{wanninkhof_1992}
+\begin{equation}
+b=2.5 ( 0.5246 + 0.016256 T+ 0.00049946  * T^2 ). \label{eq:wanchem}
+\end{equation}
+
+%We compare the results of equilibrium and transient experiments obtained with both methods in section \ref{sec:UNDEU}.
+
+%
+\subsubsection{Model setup}
+\label{sec:setup}
+
+To activate the \texttt{C14} package, set the parameter \textit{ln\_c14} = \texttt{.true.} in namelist \textit{namtrc}.
+
+\paragraph{Parameters and formulations}
+\label{sec:param}
+ %
+The radiocarbon decay rate (\CODE{rlam14}; in \texttt{trcnam\_c14} module) is set to $\lambda=(1/8267)$ yr$^{-1}$ \citep{stuiver_1977}, which corresponds to a half-life of 5730 yr.\\[1pt]
+%
+The Schmidt number $Sc$, Eq. \eqref{eq:wanc14}, is calculated with the help of the formulation of \cite{wanninkhof_2014}. The $\cd$ solubility $K_0$ in \eqref{eq:Rspeed} is taken from \cite{weiss_1974}. $K_0$ and $Sc$ are computed with the OGCM temperature and salinity fields (\texttt{trcsms\_c14} module).\\[1pt]
+%
+The following parameters intervening in the air-sea exchange rate are set in \texttt{namelist\_c14}:
+\begin{itemize}
+\item The reference DIC concentration $\overline{\Ct}$ (\CODE{xdicsur}) intervening in \eqref{eq:Rspeed} is classically set to 2 mol m$^{-3}$ \citep{toggweiler_1989a,orr_2001,butzin_2005}.
+%
+\item The value of the empirical coefficient $K_W$ (\CODE{xkwind}) in \eqref{eq:wanc14} depends on the wind field and on the model upper ocean mixing rate \citep{toggweiler_1989a,wanninkhof_1992,naegler_2009,wanninkhof_2014}.
+It should be adjusted so that the globally averaged $\cd$ piston velocity is $\kappa_\cd = 16.5\pm 3.2$ cm/h \citep{naegler_2009}.
+%The sensitivity to this parametrization is discussed in section \ref{sec:result}.
+%
+\item Chemical enhancement (term $b$  in Eq. \ref{eq:wanchem}) may be set on/off by means of the logical variable \CODE{ln\_chemh}. 
+\end{itemize}
+
+%
+\paragraph{Experiment type}
+The type of experiment is determined by the value given to \CODE{kc14typ} in \texttt{namelist\_c14}. There are three possibilities:
+\begin{enumerate}
+\item natural $\Dcq$: \CODE{kc14typ}=0
+\item bomb $\Dcq$: \CODE{kc14typ}=1
+\item transient paleo-historical $\Dcq$: \CODE{kc14typ}=2
+\end{enumerate}
+%
+\textbf{Natural or Equilibrium radiocarbon}
+\CODE{kc14typ}=0
+
+Unless otherwise specified in \texttt{namelist\_c14}, the atmospheric $\Rq_a$ (\CODE{rc14at}) is set to one, the atmospheric $\cd$ (\CODE{pco2at}) to 280 ppm, and the ocean $\Rq$ is initialized with \CODE{rc14init=0.85}, i.e., $\Dcq=$-150\textperthousand  \cite[typical for deep-ocean, Fig 6 in][]{key_2004}.
+
+Equilibrium experiment should last until 98\% of the ocean volume exhibit a drift of less than 0.001\textperthousand/year \citep{orr_2000}; this is usually achieved after few kyr (Fig. \ref{fig:drift}).
+%
+\begin{figure}[!h]
+\begin{center}
+\includegraphics[width=0.9\hsize]{drift-EXP06}
+\end{center}
+\vspace{-4ex}
+\caption{ Time evolution of $\Rq$ inventory anomaly for equilibrium run with homogeneous ocean initial state. The anomaly (or drift) is given in \%  change in total ocean inventory per 50 years. Time on x-axis is in simulation year.\label{fig:drift} }
+\end{figure}
+
+\textbf{Transient: Bomb}
+\label{sec:bomb}
+\CODE{kc14typ}=1
+
+\begin{figure}[!h]
+\begin{center}
+\includegraphics[width=0.9\hsize]{C14bombCO2-NB}
+\end{center}
+\vspace{-4ex}
+\caption{Atmospheric $\Dcq$ (solid; left axis) and $\cd$ (dashed; right axis)  forcing for the $\cq$-bomb experiments. The $\Dcq$ is illustrated for the three zonal bands (upper, middle, and lower curves correspond to latitudes $> 20$N, $\in [20\mathrm{S},20\mathrm{N}]$, and $< 20$S, respectively.} \label{fig:bomb}
+\end{figure}
+
+Performing this type of experiment requires that a pre-industrial equilibrium run be performed beforehand (\CODE{ln\_rsttr} should be set to \texttt{.TRUE.}). 
+
+An exception to this rule is when wishing to perform a perturbation bomb experiment as was possible with the package \texttt{C14b}. It is still possible to easily set-up that type of transient experiment for which no previous run is needed.  In addition to the instructions as given in this section it is however necessary to adapt the \texttt{atmc14.dat} file so that it does no longer contain any negative $\Dcq$ values (Suess effect in the pre-bomb period).
+
+The model  is integrated from a given initial date following the observed records provided from 1765 AD on ( Fig. \ref{fig:bomb}).
+The file \texttt{atmc14.dat}  \cite[][\& I. Levin, personal comm.]{enting_1994} provides atmospheric $\Dcq$ for three latitudinal bands: 90S-20S,    20S-20N \&    20N-90N.
+Atmospheric $\cd$ in the file \texttt{splco2.dat} is obtained from a spline fit through ice core data and direct atmospheric measurements \cite[][\& J. Orr, personal comm.]{orr_2000}.
+Dates in these forcing files are expressed as yr AD.
+
+To ensure that the atmospheric forcing is applied properly as well as that output files contain consistent dates and inventories the experiment should be set up carefully:
+\begin{itemize}
+\item Specify the starting date of the experiment: \CODE{nn\_date0} in \texttt{namelist}.  \CODE{nn\_date0} is written as Year0101 where Year may take any positive value (AD).
+\item Then the parameters \CODE{nn\_rstctl} in  \texttt{namelist} (on-line) and \CODE{nn\_rsttr} in \texttt{namelist\_top} (off-line)  must be \textbf{set to 0} at the start of the experiment (force the date to \CODE{nn\_date0} for the \textbf{first} experiment year). 
+\item These two parameters (\CODE{nn\_rstctl} and \CODE{nn\_rsttr}) have then to be \textbf{set to 2} for the following years (the date must be read in the restart file).
+\end{itemize}
+ If the experiment date is outside the data time span then the first or last atmospheric concentrations are prescribed depending on whether the date is earlier or later. Note that \CODE{tyrc14\_beg} (\texttt{namelist\_c14}) is not used in this context.
+
+%
+\textbf{Transient: Past}
+\CODE{kc14typ}=2
+%
+\begin{figure}[!h]
+\begin{center}
+\includegraphics[width=0.9\hsize]{PaleoCO2C14-NB}
+\end{center}
+\vspace{-4ex}
+\caption{Atmospheric $\Dcq$ (solid) and $\cd$ (dashed)  forcing for the Paleo experiments. The $\cd$ scale is given on the right axis.} \label{fig:paleo}
+\end{figure}
+
+This experiment type does not need a previous equilibrium run. It should start 5--6 kyr earlier than the period to be analyzed.
+Atmospheric $\Rq_a$ and $\cd$ are prescribed from forcing files. The ocean $\Rq$ is initialized with the value attributed to \CODE{rc14init} in \texttt{namelist\_c14}.
+
+The file \texttt{intcal13.14c} \citep{reimer_2013} contains atmospheric $\Dcq$ from 0 to 50 kyr cal BP\footnote{cal BP: number of years before 1950 AD}.
+The $\cd$ forcing is provided in file \texttt{ByrdEdcCO2.txt}. The content of this file is based on  the high resolution record from EPICA Dome C \citep{monnin_2004} for the Holocene and the Transition, and on Byrd Ice Core CO2 Data for 20--90 kyr BP  \citep{ahn_2008}. These atmospheric values are reproduced in Fig. \ref{fig:paleo}. Dates in these files are expressed as yr BP. 
+
+To ensure that the atmospheric forcing is applied properly as well as that output files contain consistent dates and inventories the experiment should be set up carefully.
+The true experiment starting date is given by \CODE{tyrc14\_beg} (in yr BP) in \texttt{namelist\_c14}. In consequence, \CODE{nn\_date0} in \texttt{namelist} MUST be set to 00010101.\\
+Then the parameters \CODE{nn\_rstctl} in  \texttt{namelist} (on-line) and \CODE{nn\_rsttr} in \texttt{namelist\_top} (off-line)  must be set to 0 at the start of the experiment (force the date to \CODE{nn\_date0} for the first experiment year). These two parameters have then to be set to 2 for the following years (read the date in the restart file). \\
+ If the experiment date is outside the data time span then the first or last atmospheric concentrations are prescribed depending on whether the date is earlier or later.
+
+%
+\paragraph{Model output}
+\label{sec:output}
+All output fields in Table \ref{tab:out} are routinely computed. It depends on the actual settings in \texttt{iodef.xml} whether they are stored or not.
+%
+\begin{table}[!h]
+\begin{center}
+\caption{Standard output fields for the C14 package \label{tab:out}.
+}
+%\begin{small}
+\renewcommand{\arraystretch}{1.3}%
+\begin{tabular}[h]{|l*{3}{|c}|l|}
+\hline
+Field & Type & Dim & Units & Description \\ \hline
+RC14 & ptrc & 3-D & -        & Radiocarbon ratio \\
+DeltaC14 & diad & 3-D & \textperthousand & $\Dcq$\\ 
+C14Age & diad & 3-D & yr &   Radiocarbon age \\
+RAge & diad & 2-D & yr & Reservoir age\\
+qtr\_c14 &  diad & 2-D & m$^{-2}$ yr$^{-1}$ & Air-to-sea net $\Rq$ flux\\
+qint\_c14 & diad & 2-D &   m$^{-2}$ &  Cumulative air-to-sea $\Rq$ flux \\
+AtmCO2 & scalar & 0-D & ppm & Global atmospheric $\cd$ \\ 
+AtmC14 & scalar & 0-D & \textperthousand  & Global atmospheric $\Dcq$\\ 
+K\_CO2 & scalar & 0-D & cm h$^{-1}$  & Global $\cd$ piston velocity ($ \overline{\kappa_{\cd}}$) \\ 
+K\_C14 & scalar & 0-D &m yr$^{-1}$ & Global $\Rq$ transfer velocity  ($ \overline{\kappa_R}$)\\ 
+C14Inv & scalar & 0-D & $10^{26}$ atoms & Ocean radiocarbon inventory \\ \hline
+\end{tabular}
+%\end{small}
+\end{center}
+\end{table}
+%!   Standard ratio: 1.176E-12 ; Avogadro's nbr = 6.022E+23 at/mol ; bomb C14 traditionally reported as 1.E+26 atoms
+%   REAL(wp), PARAMETER            :: atomc14=1.176*6.022E-15   ! conversion factor 
+% atomc14 * xdicsur * zdum
+
+The radiocarbon age is computed as  $(-1/\lambda) \ln{ \left( \Rq \right)}$, with zero age corresponding to $\Rq=1$. 
+
+The reservoir age is the age difference between the ocean uppermost layer and the atmosphere. It is usually reported as conventional radiocarbon age; i.e., computed by means of the Libby radiocarbon mean life \cite[8033 yr;][]{stuiver_1977}
+\begin{align}
+{^{14}\tau_\mathrm{c}}= -8033 \; \ln \left(1 + \frac{\Dcq}{10^3}\right), \label{eq:convage}
+\end{align}
+where ${^{14}\tau_\mathrm{c}}$ is expressed in years B.P. Here we do not use that convention and compute reservoir ages with the mean lifetime $1/\lambda$. Conversion from one scale to the other is readily performed. The conventional radiocarbon age is lower than the radiocarbon age by $\simeq3\%$.
+
+The ocean radiocarbon  inventory is computed as
+\begin{equation}
+N_A \Rq_\mathrm{oxa} \overline{\Ct} \left( \int_\Omega \Rq d\Omega \right) /10^{26}, \label{eq:inv}
+\end{equation}
+where $N_A$ is the Avogadro's number ($N_A=6.022\times10^{23}$ at/mol), $\Rq_\mathrm{oxa}$ is the oxalic acid radiocarbon standard \cite[$\Rq_\mathrm{oxa}=1.176\times10^{-12}$;][]{stuiver_1977}, and $\Omega$ is the ocean volume.  Bomb $\cq$ inventories are traditionally reported in units of $10^{26}$ atoms, hence the denominator in \eqref{eq:inv}.
+
+All transformations from second to year, and inversely, are performed with the help of the physical constant \CODE{rsiyea} the sideral year length expressed in seconds\footnote{The variable (\CODE{nyear\_len}) which reports the length in days of the previous/current/future year (see \textrm{oce\_trc.F90}) is not a constant. }.
+
+The global transfer velocities represent time-averaged\footnote{the actual duration is set in \texttt{iodef.xml}} global integrals of the transfer rates:
+ \begin{equation}
+ \overline{\kappa_{\cd}}= \int_\mathcal{S} \kappa_{\cd} d\mathcal{S}  \text{ and } \overline{\kappa_R}= \int_\mathcal{S} \kappa_R d\mathcal{S}
+\end{equation}
+
+
+\subsection{PISCES biogeochemical model}
+
+PISCES is a biogeochemical model which simulates the lower trophic levels of marine ecosystem (phytoplankton, microzooplankton and mesozooplankton) and the biogeochemical cycles of carbonand of the main nutrients (P, N, Fe, and Si). The  model is intended to be used for both regional and global configurations at high or low spatial resolutions as well as for  short-term (seasonal, interannual) and long-term (climate change, paleoceanography) analyses. 
+Two versions of PISCES are available in NEMO v4.0 :
+
+PISCES-v2, by setting in namelist\_pisces\_ref  \np{ln\_p4z} to true,  can be seen as one of the many Monod models \citep{monod_1958}. It assumes a constant Redfield ratio and phytoplankton growth depends on the external concentration in nutrients. There are twenty-four prognostic variables (tracers) including two phytoplankton compartments  (diatoms and nanophytoplankton), two zooplankton size-classes (microzooplankton and  mesozooplankton) and a description of the carbonate chemistry. Formulations in PISCES-v2 are based on a mixed Monod/Quota formalism: On one hand, stoichiometry of C/N/P is fixed and growth rate of phytoplankton is limited by the external availability in N, P and Si. On the other hand, the iron and silicium quotas are variable and growth rate of phytoplankton is limited by the internal availability in Fe. Various parameterizations can be activated in PISCES-v2, setting for instance the complexity of iron chemistry or the description of particulate organic materials. 
+
+PISCES-QUOTA has been built on the PISCES-v2 model described in \citet{aumont_2015}. PISCES-QUOTA has thirty-nine prognostic compartments. Phytoplankton growth can be controlled by five modeled limiting nutrients: Nitrate and Ammonium, Phosphate, Silicate and Iron. Five living compartments are represented: Three phytoplankton size classes/groups corresponding to picophytoplankton, nanophytoplankton and diatoms, and two zooplankton size classes which are microzooplankton and mesozooplankton. For phytoplankton, the prognostic variables are the carbon, nitrogen, phosphorus,  iron, chlorophyll and silicon biomasses (the latter only for diatoms). This means that the N/C, P/C, Fe/C and Chl/C ratios of both phytoplankton groups as well as the Si/C ratio of diatoms are prognostically predicted  by the model. Zooplankton are assumed to be strictly homeostatic \citep[e.g.,][]{sterner_2003,woods_2013,meunier_2014}. As a consequence, the C/N/P/Fe ratios of these groups are maintained constant and are not allowed to vary. In PISCES, the Redfield ratios C/N/P are set to 122/16/1 \citep{takahashi_1985} and the -O/C ratio is set to 1.34 \citep{kortzinger_2001}. No silicified zooplankton is assumed. The bacterial pool is not yet explicitly modeled.
+
+There are three non-living compartments: Semi-labile dissolved organic matter, small sinking particles, and large sinking particles. As a consequence of the variable stoichiometric ratios of phytoplankton and of the stoichiometric regulation of zooplankton, elemental ratios in organic matter cannot be supposed constant anymore as that was the case in PISCES-v2. Indeed, the nitrogen, phosphorus, iron, silicon and calcite pools of the particles are now all explicitly modeled. The sinking speed of the particles is not altered by their content in calcite and biogenic silicate (''The ballast effect'', \citep{honjo_1996,armstrong_2001}). The latter particles are assumed to sink at the same speed as the large organic matter particles. All the non-living compartments experience aggregation due to turbulence and differential settling as well as Brownian coagulation for DOM.
+
+ 
+\subsection{MY\_TRC interface for coupling external BGC models}
+\label{Mytrc}
+
+The NEMO-TOP has only one built-in biogeochemical model - PISCES - but there are several BGC models - MEDUSA, ERSEM, BFM or ECO3M - which are meant to be coupled with the NEMO dynamics. Therefore it was necessary to provide to the users a framework for easily add their own BGCM model, that can be a single passive tracer.
+The generalized interface is pivoted on MY\_TRC module that contains template files to build the coupling between NEMO and any external BGC model. The call to MY\_TRC is activated by setting  \textit{ln\_my\_trc} = \texttt{.true.} in namelist \textit{namtrc}
+
+The following 6 fortran files are available in MY\_TRC with the specific purposes here described.
+
+\begin{itemize}
+   \item \textit{par\_my\_trc.F90} :  This module allows to define additional arrays and public variables to be used within the MY\_TRC interface
+   \item \textit{trcini\_my\_trc.F90} :  Here are initialized user defined namelists and the call to the external BGC model initialization procedures to populate general tracer array (trn and trb). Here are also likely to be defined suport arrays related to system metrics that could be needed by the BGC model.
+  \item \textit{trcnam\_my\_trc.F90} :  This routine is called at the beginning of trcini\_my\_trc and should contain the initialization of additional namelists for the BGC model or user-defined code.
+  \item \textit{trcsms\_my\_trc.F90} :  The routine performs the call to Boundary Conditions and its main purpose is to contain the Source-Minus-Sinks terms due to the biogeochemical processes of the external model. Be aware that lateral boundary conditions are applied in trcnxt routine. IMPORTANT: the routines to compute the light penetration along the water column and the tracer vertical sinking should be defined/called in here, as generalized modules are still missing in the code.
+ \item \textit{trcice\_my\_trc.F90} : Here it is possible to prescribe the tracers concentrations in the seaice that will be used as boundary conditions when ice melting occurs (nn\_ice\_tr =1 in namtrc\_ice). See e.g. the correspondent PISCES subroutine.
+ \item \textit{trcwri\_my\_trc.F90} : This routine performs the output of the model tracers using IOM module (see Manual Chapter Output and Diagnostics). It is possible to place here the output of additional variables produced by the model, if not done elsewhere in the code, using the call to \textit{iom\_put}.
+\end{itemize}
+
+
+\section{The Offline Option}
+\label{Offline}
+
+%------------------------------------------namtrc_sms----------------------------------------------------
+\nlst{namdta_dyn}
+%-------------------------------------------------------------------------------------------------------------
+
+Coupling passive tracers offline with NEMO requires precomputed  physical fields from OGCM. Those fields are read from files and interpolated on-the-fly at each model time step
+At least the following dynamical parameters should be absolutely passed to the transport : ocean velocities, temperature, salinity, mixed layer depth and for ecosystem models like PISCES, sea ice concentration, short wave radiation at the ocean surface, wind speed (or at least, wind stress). 
+The so-called offline mode is useful since it has lower computational costs for example to perform very longer simulations - about 3000 years - to reach equilibrium of CO2 sinks for climate-carbon studies.
+
+The offline interface is located in the code repository : \path{<repository>/src/OFF/}. It is activated by adding the CPP key  \textit{key\_offline} to the CPP keys list. There are two specifics routines for the Offline code :
+
+\begin{itemize}
+   \item \textit{dtadyn.F90} :  this module allows to read and compute the dynamical fields at each model time-step 
+   \item \textit{nemogcm.F90} :  a degraded version of the main nemogcm.F90 code of NEMO to manage the time-stepping
+\end{itemize}
+
+
+%-
+%-
+%-
+%-  Describes here the specifities of oflline : At least the dynamical variables needed - u/v/w transport T/S for isopycnal MLD for biogeo models etc ...
+%-  the specfities of vvl - ssh + runoffs and how to
+%-
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/subfiles/model_setup.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/subfiles/model_setup.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP/subfiles/model_setup.tex	(revision 11422)
@@ -0,0 +1,46 @@
+\documentclass[../../NEMO/main/NEMO_manual]{subfiles}
+
+\begin{document}
+
+\chapter{ Model Setup}
+
+\section{ Setting up a passive tracer configuration}
+%------------------------------------------namtrc_int----------------------------------------------------
+\nlst{namtrc}
+%-------------------------------------------------------------------------------------------------------------
+
+The usage of TOP is activated 
+
+\begin{itemize}
+         \item by including in the configuration definition the component TOP\_SRC
+         \item by adding the macro \textit{key\_top} in the configuration cpp file
+\end{itemize}
+
+As an example, the user can refer to already available configurations in the code, GYRE\_PISCES being the NEMO biogeochemical demonstrator and GYRE\_BFM to see the required configuration elements to couple with an external biogeochemical model (see also section \S\ref{SMS_models}) .
+
+Note that, since version 4.0, TOP interface core functionalities are activated by means of logical keys and all submodules preprocessing macros from previous versions were removed. 
+
+There are only three specific keys remaining in TOP
+
+\begin{itemize}
+        \item \textit{key\_top} : to enables passive tracer module
+        \item \textit{key\_trdtrc} and \textit{key\_trdmxl\_trc} : trend computation for tracers
+\end{itemize}
+
+For a remind, the revisited structure of TOP interface now counts for five different modules handled in namelist\_top : 
+
+\begin{itemize}
+        \item \textbf{PISCES}, default BGC model
+        \item \textbf{MY\_TRC}, template for creation of new modules couplings (maybe run a single passive tracer)
+        \item \textbf{CFC}, inert carbon tracers dynamics (CFC11,CFC12,SF6) Updated with OMIP-BGC guidelines (Orr et al, 2016)
+        \item \textbf{C14}, radiocarbon passive tracer
+        \item \textbf{AGE}, water age tracking revised implementation
+\end{itemize}
+
+The modular approach was implemented also in the definition of the total number of passive tracers (jptra). This results from to user setting from the namelist \textit{namtrc}
+
+\section{ TOP Tracer Initialisation}
+
+\section{ TOP Boundaries Conditions}
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/ametsoc.bst
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/ametsoc.bst	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/ametsoc.bst	(revision 11422)
@@ -0,0 +1,1662 @@
+%%
+%% This is file `ametsoc7.bst',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% merlin.mbs  (with options: `ay,nat,nm-rev1,ed-rev,jnrlst,nmdash,nmd-3,dt-beg,yr-com,yrp-col,thtit-a,vol-2bf,vnum-sp,volp-com,pgsep-s,num-xser,numser,ser-vol,bkpg-x,pg-bk,pre-edn,agu-doi,doi,edparc,bkedcap,edby,edbyy,blk-tit,in-x,pp,ed,abr,ednx,ord,jabr,eprint,url,url-nt,em-it,nfss,')
+%% ----------------------------------------
+%% *** Bibliography style file for ALL AMS Journals...version 1.0  ***
+%% *** Brian Papa - American Meteorological Society ***
+%% 
+%% Copyright 1994-2004 Patrick W Daly
+ % ===============================================================
+ % IMPORTANT NOTICE:
+ % This bibliographic style (bst) file has been generated from one or
+ % more master bibliographic style (mbs) files, listed above.
+ %
+ % This generated file can be redistributed and/or modified under the terms
+ % of the LaTeX Project Public License Distributed from CTAN
+ % archives in directory macros/latex/base/lppl.txt; either
+ % version 1 of the License, or any later version.
+ % ===============================================================
+ % Name and version information of the main mbs file:
+ % \ProvidesFile{merlin.mbs}[2004/02/09 4.13 (PWD, AO, DPC)]
+ %   For use with BibTeX version 0.99a or later
+ %-------------------------------------------------------------------
+ % This bibliography style file is intended for texts in ENGLISH
+ % This is an author-year citation style bibliography. As such, it is
+ % non-standard LaTeX, and requires a special package file to function properly.
+ % Such a package is    natbib.sty   by Patrick W. Daly
+ % The form of the \bibitem entries is
+ %   \bibitem[Jones et al.(1990)]{key}...
+ %   \bibitem[Jones et al.(1990)Jones, Baker, and Smith]{key}...
+ % The essential feature is that the label (the part in brackets) consists
+ % of the author names, as they should appear in the citation, with the year
+ % in parentheses following. There must be no space before the opening
+ % parenthesis!
+ % With natbib v5.3, a full list of authors may also follow the year.
+ % In natbib.sty, it is possible to define the type of enclosures that is
+ % really wanted (brackets or parentheses), but in either case, there must
+ % be parentheses in the label.
+ % The \cite command functions as follows:
+ %   \citet{key} ==>>                Jones et al. (1990)
+ %   \citet*{key} ==>>               Jones, Baker, and Smith (1990)
+ %   \citep{key} ==>>                (Jones et al., 1990)
+ %   \citep*{key} ==>>               (Jones, Baker, and Smith, 1990)
+ %   \citep[chap. 2]{key} ==>>       (Jones et al., 1990, chap. 2)
+ %   \citep[e.g.][]{key} ==>>        (e.g. Jones et al., 1990)
+ %   \citep[e.g.][p. 32]{key} ==>>   (e.g. Jones et al., p. 32)
+ %   \citeauthor{key} ==>>           Jones et al.
+ %   \citeauthor*{key} ==>>          Jones, Baker, and Smith
+ %   \citeyear{key} ==>>             1990
+ %---------------------------------------------------------------------
+
+ENTRY
+  { address
+    archive
+    author
+    booktitle
+    chapter
+    doi
+    edition
+    editor
+    eid
+    eprint
+    howpublished
+    department
+    institution
+    journal
+    key
+    month
+    note
+    number
+    organization
+    pages
+    publisher
+    school
+    series
+    title
+    type
+    url
+    volume
+    year
+  }
+  {}
+  { label extra.label sort.label short.list }
+INTEGERS { output.state before.all mid.sentence after.sentence after.block }
+FUNCTION {init.state.consts}
+{ #0 'before.all :=
+  #1 'mid.sentence :=
+  #2 'after.sentence :=
+  #3 'after.block :=
+}
+STRINGS { s t}
+FUNCTION {output.nonnull}
+{ 's :=
+  output.state mid.sentence =
+    { ", " * write$ }
+    { output.state after.block =
+        { add.period$ write$
+          newline$
+          "\newblock " write$
+        }
+        { output.state before.all =
+            'write$
+            { add.period$ " " * write$ }
+          if$
+        }
+      if$
+      mid.sentence 'output.state :=
+    }
+  if$
+  s
+}
+FUNCTION {output}
+{ duplicate$ empty$
+    'pop$
+    'output.nonnull
+  if$
+}
+FUNCTION {output.check}
+{ 't :=
+  duplicate$ empty$
+    { pop$ "empty " t * " in " * cite$ * warning$ }
+    'output.nonnull
+  if$
+}
+FUNCTION {fin.entry}
+{ add.period$
+  write$
+  newline$
+}
+
+FUNCTION {new.block}
+{ output.state before.all =
+    'skip$
+    { after.block 'output.state := }
+  if$
+}
+FUNCTION {new.sentence}
+{ output.state after.block =
+    'skip$
+    { output.state before.all =
+        'skip$
+        { after.sentence 'output.state := }
+      if$
+    }
+  if$
+}
+FUNCTION {add.blank}
+{  " " * before.all 'output.state :=
+}
+
+FUNCTION {date.block}
+{
+  ":" *
+  add.blank
+}
+
+FUNCTION {not}
+{   { #0 }
+    { #1 }
+  if$
+}
+FUNCTION {and}
+{   'skip$
+    { pop$ #0 }
+  if$
+}
+FUNCTION {or}
+{   { pop$ #1 }
+    'skip$
+  if$
+}
+FUNCTION {new.block.checkb}
+{ empty$
+  swap$ empty$
+  and
+    'skip$
+    'new.block
+  if$
+}
+FUNCTION {field.or.null}
+{ duplicate$ empty$
+    { pop$ "" }
+    'skip$
+  if$
+}
+FUNCTION {emphasize}
+{ duplicate$ empty$
+    { pop$ "" }
+    { "\textit{" swap$ * "}" * }
+  if$
+}
+FUNCTION {bolden}
+{ duplicate$ empty$
+    { pop$ "" }
+    { "\textbf{" swap$ * "}" * }
+  if$
+}
+FUNCTION {tie.or.space.prefix}
+{ duplicate$ text.length$ #3 <
+    { "~" }
+    { " " }
+  if$
+  swap$
+}
+
+FUNCTION {capitalize}
+{ "u" change.case$ "t" change.case$ }
+
+FUNCTION {space.word}
+{ " " swap$ * " " * }
+ % Here are the language-specific definitions for explicit words.
+ % Each function has a name bbl.xxx where xxx is the English word.
+ % The language selected here is ENGLISH
+FUNCTION {bbl.and}
+{ "and"}
+
+FUNCTION {bbl.etal}
+{ "et~al." }
+
+FUNCTION {bbl.editors}
+{ "Eds." }
+
+FUNCTION {bbl.editor}
+{ "Ed." }
+
+FUNCTION {bbl.edby}
+{ "edited by" }
+
+FUNCTION {bbl.edition}
+{ "ed." }
+
+FUNCTION {bbl.volume}
+{ "Vol." }
+
+FUNCTION {bbl.of}
+{ "of" }
+
+FUNCTION {bbl.number}
+{ "No." }
+
+FUNCTION {bbl.nr}
+{ "No." }
+
+FUNCTION {bbl.in}
+{ "in" }
+
+FUNCTION {bbl.pages}
+{ "pp." }
+
+FUNCTION {bbl.page}
+{ "p." }
+
+FUNCTION {bbl.chapter}
+{ "chap." }
+
+FUNCTION {bbl.techrep}
+{ "Tech. Rep." }
+
+FUNCTION {bbl.mthesis}
+{ "Master's thesis" }
+
+FUNCTION {bbl.phdthesis}
+{ "Ph.D. thesis" }
+
+FUNCTION {bbl.first}
+{ "1st" }
+
+FUNCTION {bbl.second}
+{ "2d" }
+
+FUNCTION {bbl.third}
+{ "3d" }
+
+FUNCTION {bbl.fourth}
+{ "4th" }
+
+FUNCTION {bbl.fifth}
+{ "5th" }
+
+FUNCTION {bbl.st}
+{ "st" }
+
+FUNCTION {bbl.nd}
+{ "d" }
+
+FUNCTION {bbl.rd}
+{ "d" }
+
+FUNCTION {bbl.th}
+{ "th" }
+
+MACRO {jan} {"Jan."}
+
+MACRO {feb} {"Feb."}
+
+MACRO {mar} {"Mar."}
+
+MACRO {apr} {"Apr."}
+
+MACRO {may} {"May"}
+
+MACRO {jun} {"Jun."}
+
+MACRO {jul} {"Jul."}
+
+MACRO {aug} {"Aug."}
+
+MACRO {sep} {"Sep."}
+
+MACRO {oct} {"Oct."}
+
+MACRO {nov} {"Nov."}
+
+MACRO {dec} {"Dec."}
+
+FUNCTION {eng.ord}
+{ duplicate$ "1" swap$ *
+  #-2 #1 substring$ "1" =
+     { bbl.th * }
+     { duplicate$ #-1 #1 substring$
+       duplicate$ "1" =
+         { pop$ bbl.st * }
+         { duplicate$ "2" =
+             { pop$ bbl.nd * }
+             { "3" =
+                 { bbl.rd * }
+                 { bbl.th * }
+               if$
+             }
+           if$
+          }
+       if$
+     }
+   if$
+}
+
+MACRO {acmcs} {"ACM Comput. Surv."}
+
+MACRO {acta} {"Acta Inf."}
+
+MACRO {cacm} {"Commun. ACM"}
+
+MACRO {ibmjrd} {"IBM J. Res. Dev."}
+
+MACRO {ibmsj} {"IBM Syst.~J."}
+
+MACRO {ieeese} {"IEEE Trans. Software Eng."}
+
+MACRO {ieeetc} {"IEEE Trans. Comput."}
+
+MACRO {ieeetcad}
+ {"IEEE Trans. Comput. Aid. Des."}
+
+MACRO {ipl} {"Inf. Process. Lett."}
+
+MACRO {jacm} {"J.~ACM"}
+
+MACRO {jcss} {"J.~Comput. Syst. Sci."}
+
+MACRO {scp} {"Sci. Comput. Program."}
+
+MACRO {sicomp} {"SIAM J. Comput."}
+
+MACRO {tocs} {"ACM Trans. Comput. Syst."}
+
+MACRO {tods} {"ACM Trans. Database Syst."}
+
+MACRO {tog} {"ACM Trans. Graphic."}
+
+MACRO {toms} {"ACM Trans. Math. Software"}
+
+MACRO {toois} {"ACM Trans. Office Inf. Syst."}
+
+MACRO {toplas} {"ACM Trans. Progr. Lang. Syst."}
+
+MACRO {tcs} {"Theor. Comput. Sci."}
+
+FUNCTION {bibinfo.check}
+{ swap$
+  duplicate$ missing$
+    {
+      pop$ pop$
+      ""
+    }
+    { duplicate$ empty$
+        {
+          swap$ pop$
+        }
+        { swap$
+          pop$
+        }
+      if$
+    }
+  if$
+}
+FUNCTION {bibinfo.warn}
+{ swap$
+  duplicate$ missing$
+    {
+      swap$ "missing " swap$ * " in " * cite$ * warning$ pop$
+      ""
+    }
+    { duplicate$ empty$
+        {
+          swap$ "empty " swap$ * " in " * cite$ * warning$
+        }
+        { swap$
+          pop$
+        }
+      if$
+    }
+  if$
+}
+FUNCTION {format.eprint}
+{ eprint duplicate$ empty$
+    'skip$
+    { "\eprint"
+      archive empty$
+        'skip$
+        { "[" * archive * "]" * }
+      if$
+      "{" * swap$ * "}" *
+    }
+  if$
+}
+STRINGS  { bibinfo}
+INTEGERS { nameptr namesleft numnames }
+
+FUNCTION {format.names}
+{ 'bibinfo :=
+  duplicate$ empty$ 'skip$ {
+  's :=
+  "" 't :=
+  #1 'nameptr :=
+  s num.names$ 'numnames :=
+  numnames 'namesleft :=
+    { namesleft #0 > }
+    { s nameptr
+      duplicate$ #1 >
+        { "{f.~}{vv~}{ll}{, jj}" }
+        { "{vv~}{ll}{, f.}{, jj}" }
+      if$
+      format.name$
+      bibinfo bibinfo.check
+      't :=
+      nameptr #1 >
+        {
+          namesleft #1 >
+            { ", " * t * }
+            {
+              numnames #2 >
+                { "," * }
+                'skip$
+              if$
+              s nameptr "{ll}" format.name$ duplicate$ "others" =
+                { 't := }
+                { pop$ }
+              if$
+              t "others" =
+                {
+                  " " * bbl.etal *
+                }
+                {
+                  bbl.and
+                  space.word * t *
+                }
+              if$
+            }
+          if$
+        }
+        't
+      if$
+      nameptr #1 + 'nameptr :=
+      namesleft #1 - 'namesleft :=
+    }
+  while$
+  } if$
+}
+FUNCTION {format.names.ed}
+{
+  format.names
+}
+FUNCTION {format.key}
+{ empty$
+    { key field.or.null }
+    { "" }
+  if$
+}
+
+FUNCTION {format.authors}
+{ author "author" format.names
+}
+FUNCTION {get.bbl.editor}
+{ editor num.names$ #1 > 'bbl.editors 'bbl.editor if$ }
+
+FUNCTION {format.editors}
+{ editor "editor" format.names duplicate$ empty$ 'skip$
+    {
+      "," *
+      " " *
+      get.bbl.editor
+      capitalize
+   "(" swap$ * ")" *
+      *
+    }
+  if$
+}
+FUNCTION {format.book.pages}
+{ pages "pages" bibinfo.check
+  duplicate$ empty$ 'skip$
+    { " " * bbl.pages * }
+  if$
+}
+FUNCTION {format.doi}
+{ doi "doi" bibinfo.check
+  duplicate$ empty$ 'skip$
+    {
+      "\href{http://dx.doi.org/" swap$ * "}{DOI}" *
+    }
+  if$
+}
+FUNCTION {format.note}
+{
+  url empty$
+    'skip$
+    { "\href{" url * "}{URL}" * output }
+  if$
+ note empty$
+    { "" }
+    { note #1 #1 substring$
+      duplicate$ "{" =
+        'skip$
+        { output.state mid.sentence =
+          { "l" }
+          { "u" }
+        if$
+        change.case$
+        }
+      if$
+      note #2 global.max$ substring$ * "note" bibinfo.check
+    }
+  if$
+}
+
+FUNCTION {format.title}
+{ title
+  duplicate$ empty$ 'skip$
+    { "t" change.case$ }
+  if$
+  "title" bibinfo.check
+}
+FUNCTION {format.full.names}
+{'s :=
+ "" 't :=
+  #1 'nameptr :=
+  s num.names$ 'numnames :=
+  numnames 'namesleft :=
+    { namesleft #0 > }
+    { s nameptr
+      "{vv~}{ll}" format.name$
+      't :=
+      nameptr #1 >
+        {
+          namesleft #1 >
+            { ", " * t * }
+            {
+              s nameptr "{ll}" format.name$ duplicate$ "others" =
+                { 't := }
+                { pop$ }
+              if$
+              t "others" =
+                {
+                  " " * bbl.etal *
+                }
+                {
+                  numnames #2 >
+                    { "," * }
+                    'skip$
+                  if$
+                  bbl.and
+                  space.word * t *
+                }
+              if$
+            }
+          if$
+        }
+        't
+      if$
+      nameptr #1 + 'nameptr :=
+      namesleft #1 - 'namesleft :=
+    }
+  while$
+}
+
+FUNCTION {author.editor.key.full}
+{ author empty$
+    { editor empty$
+        { key empty$
+            { cite$ #1 #3 substring$ }
+            'key
+          if$
+        }
+        { editor format.full.names }
+      if$
+    }
+    { author format.full.names }
+  if$
+}
+
+FUNCTION {author.key.full}
+{ author empty$
+    { key empty$
+         { cite$ #1 #3 substring$ }
+          'key
+      if$
+    }
+    { author format.full.names }
+  if$
+}
+
+FUNCTION {editor.key.full}
+{ editor empty$
+    { key empty$
+         { cite$ #1 #3 substring$ }
+          'key
+      if$
+    }
+    { editor format.full.names }
+  if$
+}
+
+FUNCTION {make.full.names}
+{ type$ "book" =
+  type$ "inbook" =
+  or
+    'author.editor.key.full
+    { type$ "proceedings" =
+        'editor.key.full
+        'author.key.full
+      if$
+    }
+  if$
+}
+
+FUNCTION {output.bibitem}
+{ newline$
+  "\bibitem[{" write$
+  label write$
+  ")" make.full.names duplicate$ short.list =
+     { pop$ }
+     { * }
+   if$
+  "}]{" * write$
+  cite$ write$
+  "}" write$
+  newline$
+  ""
+  before.all 'output.state :=
+}
+
+FUNCTION {if.digit}
+{ duplicate$ "0" =
+  swap$ duplicate$ "1" =
+  swap$ duplicate$ "2" =
+  swap$ duplicate$ "3" =
+  swap$ duplicate$ "4" =
+  swap$ duplicate$ "5" =
+  swap$ duplicate$ "6" =
+  swap$ duplicate$ "7" =
+  swap$ duplicate$ "8" =
+  swap$ "9" = or or or or or or or or or
+}
+FUNCTION {n.separate}
+{ 't :=
+  ""
+  #0 'numnames :=
+  { t empty$ not }
+  { t #-1 #1 substring$ if.digit
+      { numnames #1 + 'numnames := }
+      { #0 'numnames := }
+    if$
+    t #-1 #1 substring$ swap$ *
+    t #-2 global.max$ substring$ 't :=
+    numnames #5 =
+      { duplicate$ #1 #2 substring$ swap$
+        #3 global.max$ substring$
+        "\," swap$ * *
+      }
+      'skip$
+    if$
+  }
+  while$
+}
+FUNCTION {n.dashify}
+{
+  n.separate
+  't :=
+  ""
+    { t empty$ not }
+    { t #1 #1 substring$ "-" =
+        { t #1 #2 substring$ "--" = not
+            { "--" *
+              t #2 global.max$ substring$ 't :=
+            }
+            {   { t #1 #1 substring$ "-" = }
+                { "-" *
+                  t #2 global.max$ substring$ 't :=
+                }
+              while$
+            }
+          if$
+        }
+        { t #1 #1 substring$ *
+          t #2 global.max$ substring$ 't :=
+        }
+      if$
+    }
+  while$
+}
+
+FUNCTION {word.in}
+{ "" }
+
+FUNCTION {format.date}
+{ year "year" bibinfo.check duplicate$ empty$
+    {
+      "empty year in " cite$ * "; set to ????" * warning$
+       pop$ "????"
+    }
+    'skip$
+  if$
+  extra.label *
+  before.all 'output.state :=
+  ", " swap$ *
+}
+FUNCTION {format.btitle}
+{ title "title" bibinfo.check
+  duplicate$ empty$ 'skip$
+    {
+      emphasize
+    }
+  if$
+}
+FUNCTION {either.or.check}
+{ empty$
+    'pop$
+    { "can't use both " swap$ * " fields in " * cite$ * warning$ }
+  if$
+}
+FUNCTION {format.bvolume}
+{ volume empty$
+    { "" }
+    { bbl.volume volume tie.or.space.prefix
+      "volume" bibinfo.check * *
+      series "series" bibinfo.check
+      duplicate$ empty$ 'pop$
+%%% NO ITALIC SERIES        { emphasize ", " * swap$ * }
+      {", " * swap$ * }
+      if$
+      "volume and number" number either.or.check
+    }
+  if$
+}
+FUNCTION {format.number.series}
+{ volume empty$
+    { number empty$
+        { series field.or.null }
+        { series empty$
+            { number "number" bibinfo.check }
+            { output.state mid.sentence =
+                { bbl.number }
+                { bbl.number capitalize }
+              if$
+              number tie.or.space.prefix "number" bibinfo.check * *
+              bbl.in space.word *
+              series "series" bibinfo.check *
+            }
+          if$
+        }
+      if$
+    }
+    { "" }
+  if$
+}
+FUNCTION {is.num}
+{ chr.to.int$
+  duplicate$ "0" chr.to.int$ < not
+  swap$ "9" chr.to.int$ > not and
+}
+
+FUNCTION {extract.num}
+{ duplicate$ 't :=
+  "" 's :=
+  { t empty$ not }
+  { t #1 #1 substring$
+    t #2 global.max$ substring$ 't :=
+    duplicate$ is.num
+      { s swap$ * 's := }
+      { pop$ "" 't := }
+    if$
+  }
+  while$
+  s empty$
+    'skip$
+    { pop$ s }
+  if$
+}
+
+FUNCTION {convert.edition}
+{ extract.num "l" change.case$ 's :=
+  s "first" = s "1" = or
+    { bbl.first 't := }
+    { s "second" = s "2" = or
+        { bbl.second 't := }
+        { s "third" = s "3" = or
+            { bbl.third 't := }
+            { s "fourth" = s "4" = or
+                { bbl.fourth 't := }
+                { s "fifth" = s "5" = or
+                    { bbl.fifth 't := }
+                    { s #1 #1 substring$ is.num
+                        { s eng.ord 't := }
+                        { edition 't := }
+                      if$
+                    }
+                  if$
+                }
+              if$
+            }
+          if$
+        }
+      if$
+    }
+  if$
+  t
+}
+
+FUNCTION {format.edition}
+{ edition duplicate$ empty$ 'skip$
+    {
+      convert.edition
+      output.state mid.sentence =
+        { "l" }
+        { "t" }
+      if$ change.case$
+      "edition" bibinfo.check
+      " " * bbl.edition *
+    }
+  if$
+}
+INTEGERS { multiresult }
+FUNCTION {multi.page.check}
+{ 't :=
+  #0 'multiresult :=
+    { multiresult not
+      t empty$ not
+      and
+    }
+    { t #1 #1 substring$
+      duplicate$ "-" =
+      swap$ duplicate$ "," =
+      swap$ "+" =
+      or or
+        { #1 'multiresult := }
+        { t #2 global.max$ substring$ 't := }
+      if$
+    }
+  while$
+  multiresult
+}
+FUNCTION {format.pages}
+{ pages duplicate$ empty$ 'skip$
+    { duplicate$ multi.page.check
+        {
+          n.dashify
+        }
+        {
+        }
+      if$
+      "pages" bibinfo.check
+    }
+  if$
+}
+FUNCTION {format.journal.pages}
+{ pages duplicate$ empty$ 'pop$
+    { swap$ duplicate$ empty$
+        { pop$ pop$ format.pages }
+        {
+          ", " *
+          swap$
+          n.dashify
+          "pages" bibinfo.check
+          *
+        }
+      if$
+    }
+  if$
+}
+FUNCTION {format.journal.eid}
+{ eid "eid" bibinfo.check
+  duplicate$ empty$ 'pop$
+    { swap$ duplicate$ empty$ 'skip$
+      {
+          ", " *
+      }
+      if$
+      swap$ *
+    }
+  if$
+}
+FUNCTION {format.vol.num.pages}
+{ volume field.or.null
+  duplicate$ empty$ 'skip$
+    {
+      "volume" bibinfo.check
+    }
+  if$
+  number "number" bibinfo.check duplicate$ empty$ 'skip$
+    {
+      swap$ duplicate$ empty$
+        { "there's a number but no volume in " cite$ * warning$ }
+        'skip$
+      if$
+      swap$
+      "~(" swap$ * ")" *
+    }
+  if$ *
+  bolden
+  eid empty$
+    { format.journal.pages }
+    { format.journal.eid }
+  if$
+}
+
+FUNCTION {format.chapter.pages}
+{ chapter empty$
+    'format.pages
+    { type empty$
+        { bbl.chapter }
+        { type "l" change.case$
+          "type" bibinfo.check
+        }
+      if$
+      chapter tie.or.space.prefix
+      "chapter" bibinfo.check
+      * *
+      pages empty$
+        'skip$
+        { ", " * format.pages * }
+      if$
+    }
+  if$
+}
+
+FUNCTION {format.booktitle}
+{
+  booktitle "booktitle" bibinfo.check
+  emphasize
+}
+FUNCTION {format.in.ed.booktitle}
+{ format.booktitle duplicate$ empty$ 'skip$
+    {
+      editor "editor" format.names.ed duplicate$ empty$ 'pop$
+        {
+          get.bbl.editor
+          swap$ "," *
+          " " * swap$ *
+          swap$
+          "," *
+          " " * swap$
+          * }
+      if$
+      word.in swap$ *
+    }
+  if$
+}
+FUNCTION {format.thesis.type}
+{ type duplicate$ empty$
+    'pop$
+    { swap$ pop$
+      "t" change.case$ "type" bibinfo.check
+    }
+  if$
+}
+FUNCTION {format.tr.number}
+{ number "number" bibinfo.check
+  type duplicate$ empty$
+    { pop$ bbl.techrep }
+    'skip$
+  if$
+  "type" bibinfo.check
+  swap$ duplicate$ empty$
+    { pop$ "t" change.case$ }
+    { tie.or.space.prefix * * }
+  if$
+}
+FUNCTION {format.article.crossref}
+{
+  word.in
+  " \cite{" * crossref * "}" *
+}
+FUNCTION {format.book.crossref}
+{ volume duplicate$ empty$
+    { "empty volume in " cite$ * "'s crossref of " * crossref * warning$
+      pop$ word.in
+    }
+    { bbl.volume
+      capitalize
+      swap$ tie.or.space.prefix "volume" bibinfo.check * * bbl.of space.word *
+    }
+  if$
+  " \cite{" * crossref * "}" *
+}
+FUNCTION {format.incoll.inproc.crossref}
+{
+  word.in
+  " \cite{" * crossref * "}" *
+}
+FUNCTION {format.org.or.pub}
+{ 't :=
+  ""
+  address empty$ t empty$ and
+    'skip$
+    {
+      t empty$
+        { address "address" bibinfo.check *
+        }
+        { t *
+          address empty$
+            'skip$
+            { ", " * address "address" bibinfo.check * }
+          if$
+        }
+      if$
+    }
+  if$
+}
+FUNCTION {format.publisher.address}
+{ publisher "publisher" bibinfo.warn format.org.or.pub
+}
+
+FUNCTION {format.organization.address}
+{ organization "organization" bibinfo.check format.org.or.pub
+}
+
+STRINGS {oldname}
+
+FUNCTION {name.or.dash}
+{ 's :=
+   oldname empty$
+     { s 'oldname := s }
+     { s oldname =
+         { "---{}---{}---" }
+         { s 'oldname := s }
+       if$
+     }
+   if$
+}
+
+FUNCTION {article}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title "title" output.check
+  new.sentence
+  crossref missing$
+    {
+      journal
+      "journal" bibinfo.check
+      emphasize
+      "journal" output.check
+      format.vol.num.pages output
+  format.doi output
+    }
+    { format.article.crossref output.nonnull
+      format.pages output
+    }
+  if$
+  format.note output
+  format.eprint output
+  fin.entry
+}
+FUNCTION {book}
+{ output.bibitem
+  author empty$
+    { format.editors "author and editor" output.check
+      editor format.key output
+      add.blank
+      name.or.dash
+    }
+    { format.authors output.nonnull
+      name.or.dash
+      crossref missing$
+        { "author and editor" editor either.or.check }
+        'skip$
+      if$
+    }
+  if$
+  format.date "year" output.check
+  date.block
+  format.btitle "title" output.check
+  crossref missing$
+    { format.bvolume output
+  new.sentence
+      format.edition output
+      format.number.series output
+      format.publisher.address output
+    }
+    {
+  new.sentence
+      format.book.crossref output.nonnull
+    }
+  if$
+  format.book.pages output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+FUNCTION {booklet}
+{ output.bibitem
+  format.authors output
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title "title" output.check
+  new.sentence
+  howpublished "howpublished" bibinfo.check output
+  address "address" bibinfo.check output
+  format.book.pages output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {inbook}
+{ output.bibitem
+  author empty$
+    { format.editors "author and editor" output.check
+      editor format.key output
+      name.or.dash
+    }
+    { format.authors output.nonnull
+      name.or.dash
+      crossref missing$
+        { "author and editor" editor either.or.check }
+        'skip$
+      if$
+    }
+  if$
+  format.date "year" output.check
+  date.block
+  format.btitle "title" output.check
+  crossref missing$
+    {
+      format.bvolume output
+      format.chapter.pages "chapter and pages" output.check
+  new.sentence
+      format.edition output
+      format.number.series output
+      format.publisher.address output
+    }
+    {
+      format.chapter.pages "chapter and pages" output.check
+  new.sentence
+      format.book.crossref output.nonnull
+    }
+  if$
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {incollection}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title "title" output.check
+  new.sentence
+  crossref missing$
+    { format.in.ed.booktitle "booktitle" output.check
+      format.publisher.address output      
+      format.bvolume output
+      format.number.series output
+      format.edition output
+      format.chapter.pages output
+    }
+    { format.incoll.inproc.crossref output.nonnull
+      format.chapter.pages output
+    }
+  if$
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+FUNCTION {inproceedings}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title "title" output.check
+  new.sentence
+  crossref missing$
+    { format.in.ed.booktitle "booktitle" output.check
+      publisher empty$
+        { format.organization.address output }
+        { organization "organization" bibinfo.check output
+          format.publisher.address output
+        }
+      if$
+      format.bvolume output
+      format.pages output
+      format.number.series output
+      howpublished "howpublished" bibinfo.check output
+    }
+    { format.incoll.inproc.crossref output.nonnull
+      format.pages output
+    }
+  if$
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+FUNCTION {conference} { inproceedings }
+FUNCTION {manual}
+{ output.bibitem
+  format.authors output
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.btitle "title" output.check
+  new.sentence
+  organization "organization" bibinfo.check output
+  address "address" bibinfo.check output
+  format.edition output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {mastersthesis}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title
+  "title" output.check
+  new.sentence
+  bbl.mthesis format.thesis.type output.nonnull
+  department "department" bibinfo.warn output
+  school "school" bibinfo.warn output
+  address "address" bibinfo.check output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {misc}
+{ output.bibitem
+  format.authors output
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title output
+  new.sentence
+  howpublished "howpublished" bibinfo.check output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+FUNCTION {phdthesis}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title
+  "title" output.check
+  new.sentence
+  bbl.phdthesis format.thesis.type output.nonnull
+  school "school" bibinfo.warn output
+  address "address" bibinfo.check output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {proceedings}
+{ output.bibitem
+  format.editors output
+  editor format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.btitle "title" output.check
+  format.bvolume output
+  format.number.series output
+  publisher empty$
+    { format.organization.address output }
+    { organization "organization" bibinfo.check output
+      format.publisher.address output
+    }
+  if$
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {techreport}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title
+  "title" output.check
+  new.sentence
+  format.tr.number output.nonnull
+  institution "institution" bibinfo.warn output
+  address "address" bibinfo.check output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {unpublished}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title "title" output.check
+  format.doi output
+  format.note "note" output.check
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {default.type} { misc }
+READ
+FUNCTION {sortify}
+{ purify$
+  "l" change.case$
+}
+INTEGERS { len }
+FUNCTION {chop.word}
+{ 's :=
+  'len :=
+  s #1 len substring$ =
+    { s len #1 + global.max$ substring$ }
+    's
+  if$
+}
+FUNCTION {format.lab.names}
+{ 's :=
+  "" 't :=
+  s #1 "{vv~}{ll}" format.name$
+  s num.names$ duplicate$
+  #2 >
+    { pop$
+      " " * bbl.etal *
+    }
+    { #2 <
+        'skip$
+        { s #2 "{ff }{vv }{ll}{ jj}" format.name$ "others" =
+            {
+              " " * bbl.etal *
+            }
+            { bbl.and space.word * s #2 "{vv~}{ll}" format.name$
+              * }
+          if$
+        }
+      if$
+    }
+  if$
+}
+
+FUNCTION {author.key.label}
+{ author empty$
+    { key empty$
+        { cite$ #1 #3 substring$ }
+        'key
+      if$
+    }
+    { author format.lab.names }
+  if$
+}
+
+FUNCTION {author.editor.key.label}
+{ author empty$
+    { editor empty$
+        { key empty$
+            { cite$ #1 #3 substring$ }
+            'key
+          if$
+        }
+        { editor format.lab.names }
+      if$
+    }
+    { author format.lab.names }
+  if$
+}
+
+FUNCTION {editor.key.label}
+{ editor empty$
+    { key empty$
+        { cite$ #1 #3 substring$ }
+        'key
+      if$
+    }
+    { editor format.lab.names }
+  if$
+}
+
+FUNCTION {calc.short.authors}
+{ type$ "book" =
+  type$ "inbook" =
+  or
+    'author.editor.key.label
+    { type$ "proceedings" =
+        'editor.key.label
+        'author.key.label
+      if$
+    }
+  if$
+  'short.list :=
+}
+
+FUNCTION {calc.label}
+{ calc.short.authors
+  short.list
+  "("
+  *
+  year duplicate$ empty$
+     { pop$ "????" }
+     { purify$ #-1 #4 substring$ }
+  if$
+  *
+  'label :=
+}
+
+FUNCTION {sort.format.names}
+{ 's :=
+  #1 'nameptr :=
+  ""
+  s num.names$ 'numnames :=
+  numnames 'namesleft :=
+    { namesleft #0 > }
+    { s nameptr
+      "{vv{ } }{ll{ }}{  f{ }}{  jj{ }}"
+      format.name$ 't :=
+      nameptr #1 >
+        {
+          "   "  *
+          namesleft #1 = t "others" = and
+            { "zzzzz" * }
+            { t sortify * }
+          if$
+        }
+        { t sortify * }
+      if$
+      nameptr #1 + 'nameptr :=
+      namesleft #1 - 'namesleft :=
+    }
+  while$
+}
+
+FUNCTION {sort.format.title}
+{ 't :=
+  "A " #2
+    "An " #3
+      "The " #4 t chop.word
+    chop.word
+  chop.word
+  sortify
+  #1 global.max$ substring$
+}
+FUNCTION {author.sort}
+{ author empty$
+    { key empty$
+        { "to sort, need author or key in " cite$ * warning$
+          ""
+        }
+        { key sortify }
+      if$
+    }
+    { author sort.format.names }
+  if$
+}
+FUNCTION {author.editor.sort}
+{ author empty$
+    { editor empty$
+        { key empty$
+            { "to sort, need author, editor, or key in " cite$ * warning$
+              ""
+            }
+            { key sortify }
+          if$
+        }
+        { editor sort.format.names }
+      if$
+    }
+    { author sort.format.names }
+  if$
+}
+FUNCTION {editor.sort}
+{ editor empty$
+    { key empty$
+        { "to sort, need editor or key in " cite$ * warning$
+          ""
+        }
+        { key sortify }
+      if$
+    }
+    { editor sort.format.names }
+  if$
+}
+FUNCTION {presort}
+{ calc.label
+  label sortify
+  "    "
+  *
+  type$ "book" =
+  type$ "inbook" =
+  or
+    'author.editor.sort
+    { type$ "proceedings" =
+        'editor.sort
+        'author.sort
+      if$
+    }
+  if$
+  #1 entry.max$ substring$
+  'sort.label :=
+  sort.label
+  *
+  "    "
+  *
+  title field.or.null
+  sort.format.title
+  *
+  #1 entry.max$ substring$
+  'sort.key$ :=
+}
+
+ITERATE {presort}
+SORT
+STRINGS { last.label next.extra }
+INTEGERS { last.extra.num number.label }
+FUNCTION {initialize.extra.label.stuff}
+{ #0 int.to.chr$ 'last.label :=
+  "" 'next.extra :=
+  #0 'last.extra.num :=
+  #0 'number.label :=
+}
+FUNCTION {forward.pass}
+{ last.label label =
+    { last.extra.num #1 + 'last.extra.num :=
+      last.extra.num int.to.chr$ 'extra.label :=
+    }
+    { "a" chr.to.int$ 'last.extra.num :=
+      "" 'extra.label :=
+      label 'last.label :=
+    }
+  if$
+  number.label #1 + 'number.label :=
+}
+FUNCTION {reverse.pass}
+{ next.extra "b" =
+    { "a" 'extra.label := }
+    'skip$
+  if$
+  extra.label 'next.extra :=
+  extra.label
+  duplicate$ empty$
+    'skip$
+    { "{\natexlab{" swap$ * "}}" * }
+  if$
+  'extra.label :=
+  label extra.label * 'label :=
+}
+EXECUTE {initialize.extra.label.stuff}
+ITERATE {forward.pass}
+REVERSE {reverse.pass}
+FUNCTION {bib.sort.order}
+{ sort.label
+  "    "
+  *
+  year field.or.null sortify
+  *
+  "    "
+  *
+  title field.or.null
+  sort.format.title
+  *
+  #1 entry.max$ substring$
+  'sort.key$ :=
+}
+ITERATE {bib.sort.order}
+SORT
+FUNCTION {begin.bib}
+{ preamble$ empty$
+    'skip$
+    { preamble$ write$ newline$ }
+  if$
+  "\begin{thebibliography}{" number.label int.to.str$ * "}" *
+  write$ newline$
+  "\providecommand{\natexlab}[1]{#1}"
+  write$ newline$
+%  "\providecommand{\url}[1]{\texttt{#1}}"
+%  write$ newline$
+%  "\providecommand{\urlprefix}{URL }"
+%  write$ newline$
+%  "\expandafter\ifx\csname urlstyle\endcsname\relax"
+%  write$ newline$
+%  "  \providecommand{\doi}[1]{doi:\discretionary{}{}{}#1}\else"
+%  write$ newline$
+%  "  \providecommand{\doi}{doi:\discretionary{}{}{}\begingroup \urlstyle{rm}\Url}\fi"
+%  write$ newline$
+%  "\providecommand{\eprint}[2][]{\url{#2}}"
+%  write$ newline$
+}
+EXECUTE {begin.bib}
+EXECUTE {init.state.consts}
+ITERATE {call.type$}
+FUNCTION {end.bib}
+{ newline$
+  "\end{thebibliography}" write$ newline$
+}
+EXECUTE {end.bib}
+%% End of customized bst file
+%%
+%% End of file `ametsoc7.bst'.
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/annex_D.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/annex_D.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/annex_D.tex	(revision 11422)
@@ -0,0 +1,207 @@
+\documentclass[../main/NEMO_manual]{subfiles}
+
+\begin{document}
+% ================================================================
+% Appendix D Coding Rules
+% ================================================================
+\chapter{Coding Rules}
+\label{apdx:D}
+
+\minitoc
+
+\newpage
+
+A "model life" is more than ten years.
+Its software, composed of a few hundred modules, is used by many people who are scientists or students and
+do not necessarily know every aspect of computing very well.
+Moreover, a well thought-out program is easier to read and understand, less difficult to modify,
+produces fewer bugs and is easier to maintain.
+Therefore, it is essential that the model development follows some rules:
+
+- well planned and designed
+
+- well written
+
+- well documented (both on- and off-line)
+
+- maintainable
+
+- easily portable
+
+- flexible.
+
+To satisfy part of these aims, \NEMO is written with a coding standard which is close to the ECMWF rules,
+named DOCTOR \citep{gibson_rpt86}. 
+These rules present some advantages like:
+
+- to provide a well presented program
+
+- to use rules for variable names which allow recognition of their type
+(integer, real, parameter, local or shared variables, etc. ). 
+
+This facilitates both the understanding and the debugging of an algorithm.
+
+% ================================================================
+% The program structure
+% ================================================================
+\section{Program structure}
+\label{sec:D_structure}
+
+Each program begins with a set of headline comments containing:
+
+- the program title
+
+- the purpose of the routine
+
+- the method and algorithms used
+
+- the detail of input and output interfaces
+
+- the external routines and functions used (if they exist)
+
+- references (if they exist)
+
+- the author name(s), the date of creation and any updates.
+
+- Each program is split into several well separated sections and
+sub-sections with an underlined title and specific labelled statements.
+
+- A program has not more than 200 to 300 lines.
+
+A template of a module style can be found on the NEMO depository in the following file:
+NEMO/OPA\_SRC/module\_example.
+% ================================================================
+% Coding conventions
+% ================================================================
+\section{Coding conventions}
+\label{sec:D_coding}
+
+- Use of the universal language \fninety, and try to avoid obsolescent features like statement functions,
+do not use GO TO and EQUIVALENCE statements.
+
+- A continuation line begins with the character {\&} indented by three spaces compared to the previous line,
+while the previous line ended with the character {\&}.
+
+- All the variables must be declared.
+The code is usually compiled with implicit none.
+ 
+- Never use continuation lines in the declaration of a variable.
+When searching a variable in the code through a \textit{grep} command, the declaration line will be found.
+
+- In the declaration of a PUBLIC variable, the comment part at the end of the line should start with
+the two characters "\verb?!:?".
+The following UNIX command, \\
+\verb?grep var_name *90 \ grep \!: ? \\
+will display the module name and the line where the var\_name declaration is.
+
+- Always use a three spaces indentation in DO loop, CASE, or IF-ELSEIF-ELSE-ENDIF statements.
+
+- use a space after a comma, except when it appears to separate the indices of an array.
+
+- use call to ctl\_stop routine instead of just a STOP.
+
+\newpage
+
+% ================================================================
+% Naming Conventions
+% ================================================================
+\section{Naming conventions}
+\label{sec:D_naming}
+
+The purpose of the naming conventions is to use prefix letters to classify model variables.
+These conventions allow the variable type to be easily known and rapidly identified.
+The naming conventions are summarised in the Table below:
+
+
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[htbp]
+  \label{tab:VarName}
+  \begin{center}
+    \begin{tabular}{|p{45pt}|p{35pt}|p{45pt}|p{40pt}|p{40pt}|p{40pt}|p{40pt}|p{40pt}|}
+      \hline
+      Type \par / Status
+      & integer
+      & real
+      & logical
+      & character
+      & structure
+      & double \par precision
+      & complex \\
+      \hline
+      public  \par or  \par module variable
+      & \textbf{m n} \par \textit{but not} \par \textbf{nn\_ np\_}
+      & \textbf{a b e f g h o q r} \par \textbf{t} \textit{to} \textbf{x} \par but not \par \textbf{fs rn\_}
+      & \textbf{l} \par \textit{but not} \par \textbf{lp ld} \par \textbf{ ll ln\_}
+      & \textbf{c} \par \textit{but not} \par \textbf{cp cd} \par \textbf{cl cn\_}
+      & \textbf{s} \par \textit{but not} \par \textbf{sd sd} \par \textbf{sl sn\_}
+      & \textbf{d} \par \textit{but not} \par \textbf{dp dd} \par \textbf{dl dn\_}
+      & \textbf{y} \par \textit{but not} \par \textbf{yp yd} \par \textbf{yl yn} \\
+      \hline
+      dummy \par argument
+      & \textbf{k} \par \textit{but not} \par \textbf{kf}
+      & \textbf{p} \par \textit{but not} \par \textbf{pp pf}
+      & \textbf{ld}
+      & \textbf{cd}
+      & \textbf{sd}
+      & \textbf{dd}
+      & \textbf{yd} \\
+      \hline
+      local \par variable
+      & \textbf{i}
+      & \textbf{z}
+      & \textbf{ll}
+      & \textbf{cl}
+      & \textbf{sl}
+      & \textbf{dl}
+      & \textbf{yl} \\
+      \hline
+      loop \par control
+      & \textbf{j} \par \textit{but not} \par \textbf{jp} &&&&&& \\
+      \hline
+      parameter
+      & \textbf{jp np\_}
+      & \textbf{pp}
+      & \textbf{lp}
+      & \textbf{cp}
+      & \textbf{sp}
+      & \textbf{dp}
+      & \textbf{yp} \\
+      \hline
+      namelist
+      & \textbf{nn\_}
+      & \textbf{rn\_}
+      & \textbf{ln\_}
+      & \textbf{cn\_}
+      & \textbf{sn\_}
+      & \textbf{dn\_}
+      & \textbf{yn\_}
+      \\
+      \hline
+      CPP \par macro
+      & \textbf{kf}
+      & \textbf{fs} \par &&&&& \\
+      \hline
+    \end{tabular}
+    \label{tab:tab1}
+  \end{center}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+
+N.B. Parameter here, in not only parameter in the \fortran acceptation,
+it is also used for code variables that are read in namelist and should never been modified during a simulation. 
+It is the case, for example, for the size of a domain (jpi,jpj,jpk).
+
+\newpage
+
+% ================================================================
+% The program structure
+% ================================================================
+%\section{Program structure}
+%\label{sec:Apdx_D_structure}
+
+%To be done....
+\biblio
+
+\pindex
+
+\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/coding_rules.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/coding_rules.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/coding_rules.tex	(revision 11422)
@@ -0,0 +1,844 @@
+%\documentclass{article}
+
+%\usepackage{fancyhdr}
+%\usepackage{times}
+%\usepackage{graphicx}
+%\usepackage{hyperref}
+%\usepackage{minted}
+%\usepackage[normalem]{ulem}   % striketrough style with \sout{...}
+
+%\hypersetup{pdftitle={NEMO coding conventions}, pdfauthor={NEMO System Team}, colorlinks}
+%\setminted{style=emacs, breaklines, frame=leftline}
+%\newmintinline[forcode]{fortran}{fontsize=auto, frame=lines}   % \forcode{...}
+%\newminted[forlines]{fortran}{}                                % \begin{forlines}
+
+%\pagestyle{empty}
+%\setlength{\leftmargin}{1 cm}
+%\setlength{\rightmargin}{1 cm}
+%\setlength{\oddsidemargin}{0 cm}
+%\setlength{\evensidemargin}{0 cm}
+%\setlength{\topmargin}{-1cm}
+%\setlength{\textwidth}{16 cm}
+%\setlength{\textheight}{25cm}
+%\pagestyle{fancy}
+
+%\title{
+%  \includegraphics[width=0.3\textwidth]{../../../figures/NEMO_grey} \\
+%  \vspace{1.0cm} \rule{345pt}{1.5pt} \\
+%  \vspace{0.45cm} {\Huge NEMO coding conventions} \rule{345pt}{1.5pt} \\
+%}
+%\title{NEMO coding conventions}
+%\author{\Large NEMO System Team
+%  \thanks{
+%    To be completed
+%  }
+%}
+%\date{version X.X -- month year}
+
+%\begin{document}
+
+%\maketitle
+
+%\newpage
+
+%\tableofcontents
+
+%\newpage
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\chapter{Coding Rules}
+\label{apdx:coding}
+
+\minitoc
+
+\newpage
+
+A "model life" is more than ten years.
+Its software, composed of a few hundred modules, is used by many people who are scientists or students and
+do not necessarily know every aspect of computing very well.
+Moreover, a well thought-out program is easier to read and understand, less difficult to modify,
+produces fewer bugs and is easier to maintain.
+Therefore, it is essential that the model development follows some rules:
+
+- well planned and designed
+
+- well written
+
+- well documented (both on- and off-line)
+
+- maintainable
+
+- easily portable
+
+- flexible.
+
+To satisfy part of these aims, \NEMO is written with a coding standard which is close to the ECMWF rules,
+named DOCTOR \citep{gibson_rpt86}. 
+These rules present some advantages like:
+
+- to provide a well presented program
+
+- to use rules for variable names which allow recognition of their type
+(integer, real, parameter, local or shared variables, etc. ). 
+
+This facilitates both the understanding and the debugging of an algorithm.
+
+\section{Introduction}
+
+This document describes conventions\index{conventions} used in NEMO coding and suggested for its development.
+The objectives are to offer a guide to all readers of the NEMO code, and to facilitate the work of
+all the developers, including the validation of their developments, and
+eventually the implementation of these developments within the NEMO platform.
+
+A first approach of these rules can be found in the code in \path{./src/OCE/module_example} where
+all the basics coding conventions are illustrated.
+More details can be found below.
+
+This work is based on the coding conventions in use for the Community Climate System Model
+\footnote {\href{http://www.cesm.ucar.edu/working_groups/Software/dev_guide/dev_guide/node7.html}{UCAR conventions}}, 
+the previous version of this document (``FORTRAN coding standard in the OPA System'') and
+the expertise of the NEMO System Team.
+After a general overview below, this document will describe:
+
+\begin{itemize}
+\item
+  The style rules, $i.e.$ the syntax, appearance and naming conventions chosen to improve readability of the code;
+\item
+  The content rules, $i.e.$ the conventions to improve the reliability of the different parts of the code;
+\item
+  The package rules to go a step further by improving the reliability of the whole and
+  interfaces between routines and modules.
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Overview and general conventions}
+
+NEMO has 3 major components: ocean dynamics (\path{./src/OCE}), sea-ice (\path{./src/ICE}) and
+marine biogeochemistry (\path{./src/MBG}).
+%, linear-tangent and adjoint of the dynamics ($TAM$) each of them corresponding to a directory.
+In each directory, one will find some FORTRAN files and/or subdirectories, one per functionality of the code:
+\path{./src/OCE/BDY} (boundaries), \path{./src/OCE/DIA} (diagnostics), \path{./src/OCE/DOM} (domain),
+\path{./src/OCE/DYN} (dynamics), \path{./src/OCE/LDF} (lateral diffusion), etc... \\
+All name are chosen to be as self-explanatory as possible, in English, all prefixes are 3 digits. \\
+English is used for all variables names, comments, and documentation. \\
+Physical units are MKS. The only exception to this is the temperature, which is expressed in degrees Celsius,
+except in bulk formulae and part of SI$^3$ sea-ice model where it is in Kelvin.
+See \path{.src/OCE/DOM/phycst.F90} files for conversions.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Architecture}
+
+Within each directory, organisation of files is driven by orthogonality\index{orthogonality},
+$i.e.$ one functionality of the code is intended to be in one and only one directory, and
+one module and all its related routines are in one file.
+The functional modules\index{module} are:
+
+\begin{itemize}
+\item \path{SBC}             surface module
+\item \path{IOM}             management of the I/O
+\item \path{NST}             interface to AGRIF (nesting model) for dynamics and biogeochemistry
+\item \path{OBC}, \path{BDY} management of structured and unstructured open boundaries 
+\item \path{C1D}             1D (vertical) configuration for dynamics, sea-ice and biogeochemistry
+\item \path{OFF}             off-line module: passive tracer or biogeochemistry alone
+\item \path{...}
+\end{itemize}
+
+For example, the file \textit{domain.F90} contains the module \texttt{domain} and all the subroutines related to
+this module (\texttt{dom\_init, dom\_nam, dom\_ctl}).
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Style rules}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Argument list format}
+
+Routine argument lists will contain a maximum 5 variables\index{variable} per line,
+whilst continuation lines can be used.
+This applies both to the calling routine and the dummy argument list in the routine being called.
+The purpose is to simplify matching up the arguments between caller and callee.
+
+\begin{forlines}
+SUBROUTINE tra_adv_eiv( kt, pun, pvn, pwn )
+
+      CALL tra_adv_eiv( kt, zun, zvn, zwn )
+\end{forlines}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Array syntax}
+
+Except for long loops (see below), array notation should be used if possible.
+To improve readability the array shape must be shown in brackets, $e.g.$:
+
+\begin{forlines}
+onedarraya(:)   = onedarrayb(:) + onedarrayc(:)
+twodarray (:,:) = scalar * anothertwodarray(:,:)
+\end{forlines}
+
+When accessing sections of arrays, for example in finite difference equations,
+do so by using the triplet notation on the full array, $e.g.$:
+
+\begin{forlines}
+twodarray(:,2:len2) =   scalar                      &
+   &                  * ( twodarray2(:,1:len2-1 )   &
+   &                  -   twodarray2(:,2:len2 ) )
+\end{forlines}
+
+For long, complicated loops, explicitly indexed loops should be preferred.
+In general when using this syntax, the order of the loops indices should reflect the following scheme
+(for best usage of data locality):
+
+\begin{forlines}
+DO jk = 1, jpk
+   DO jj = 1, jpj
+      DO ji = 1, jpi
+         threedarray(ji,jj,jk) = ...
+      END DO
+   END DO
+END DO
+\end{forlines}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Case}
+
+All FORTRAN keywords are in capital: \forcode{DIMENSION}, \forcode{WRITE}, \forcode{DO}, \forcode{END DO},
+\forcode{NAMELIST}, ... All other parts of the NEMO code will be written in lower case.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Comments}
+
+Comments in the code are useful when reading the code and changing or developing it. \\
+The full documentation and detailed explanations are to be added in the reference manual
+(TeX files, aside from the code itself). \\
+In the code, the comments should explain variable content and describe each computational step. \\
+Comments in the header start with ``!!''.
+For more details on the content of the headers, see Content rules/Headers in this document. \\
+Comments in the code start with ``!''. \\
+All comments are indented (3, 6, or 9 blank spaces). \\
+Short comments may be included on the same line as executable code, and an additional line can be used with
+proper alignment.
+For example:
+
+\begin{forlines}
+zx = zx *zzy   ! Describe what is going on and if it is
+!              ! too long use another ! for proper
+!              ! alignment with automatic indentation
+\end{forlines}
+
+More in-depth comments should be written in the form:
+
+\begin{forlines}
+   !  Check of some namelist values
+\end{forlines}
+
+or
+
+\begin{forlines}
+!
+!     !<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+!     !  Bottom boundary condition on tke
+!     !<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+!
+\end{forlines}
+
+Key features of this style are
+
+\begin{enumerate}
+\item it starts with a "!" in the column required for proper indentation,
+\item the text is offset above and below by a blank line or a content line built for underlying.
+\end{enumerate}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Continuation lines}
+
+Continuation lines can be used with precise alignment for readability. For example:
+
+\begin{forlines}
+avmu(ji,jj,jk) =   avmu(ji,jj,jk) * ( un(ji,jj,jk-1) - un(ji,jj,jk) )   &
+   &                              * ( ub(ji,jj,jk-1) - ub(ji,jj,jk) )   &
+   &             / (   fse3uw_n(ji,jj,jk)                               &
+   &                 * fse3uw_b(ji,jj,jk) )
+\end{forlines}
+
+Code lines, which are continuation lines of assignment statements, must begin to the right of the column of
+the assignment operator.
+Due to the possibility of automatic indentation in some editor (emacs for example),
+use a ``\&'' as first character of the continuing lines to maintain the alignment.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Declaration of arguments and local variables}
+
+In a routine, input arguments and local variables are declared 1 per line,
+with a comment field on the same line as the declaration.
+Multiple comment lines describing a single variable are acceptable if needed.
+For example:
+
+\begin{forlines}
+INTEGER             ::   kstp   ! ocean time-step index
+\end{forlines}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{F90 Standard}
+
+NEMO software adheres to the FORTRAN 95 language standard and does not rely on any specific language or
+vendor extensions.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Free-Form Source}
+
+Free-form source will be used.
+The F90/95 standard allows lines of up to 132 characters, but a self-imposed limit of 80 should enhance readability,
+or print source files with two columns per page.
+Multi-line comments that extend to column 100 are unacceptable.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Indentation}
+
+Code as well as comment lines within loops, if-blocks, continuation lines, \forcode{MODULE} or
+\forcode{SUBROUTINE} statements will be indented 3 characters for readability
+(except for \forcode{CONTAINS} that remains at first column).
+
+\begin{forlines}
+MODULE mod1
+   REAL(wp) xx
+CONTAINS
+   SUBROUTINE sub76( px, py, pz, pw, pa,   &
+      &              pb, pc, pd, pe          )
+      <instruction>
+   END SUBROUTINE sub76
+END MODULE mod1
+\end{forlines}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Loops}
+
+Loops, if explicit, should be structured with the do-end do construct as opposed to numbered loops.
+Nevertheless non-numeric labels can be used for a big iterative loop of a recursive algorithm.
+In the case of a long loop, a self-descriptive label can be used ($i.e.$ not just a number).
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Naming Conventions: files}
+
+A file containing a module will have the same name as the module it contains
+(because dependency rules used by "make" programs are based on file names).
+\footnote{
+  For example, if routine A "\forcode{USE}"s module B, then "make" must be told of the dependency relation which
+  requires B to be compiled before A.
+  If one can assume that module B resides in file B.o,
+  building a tool to generate this dependency rule ($e.g.$ A.o: B.o) is quite simple.
+  Put another way, it is difficult (to say nothing of CPU-intensive) to search an entire source tree to
+  find the file in which module B resides for each routine or module which "\forcode{USE}"s B.
+}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Naming Conventions: modules}
+
+Use a meaningful English name and the ``3 letters'' naming convention:
+first 3 letters for the code section, and last 3 to describe the module.
+For example, zdftke, where ``zdf'' stands for vertical diffusion, and ``tke'' for turbulent kinetic energy. \\
+Note that by implication multiple modules are not allowed in a single file.
+The use of common blocks is deprecated in Fortran 90 and their use in NEMO is strongly discouraged.
+Modules are a better way to declare static data.
+Among the advantages of modules is the ability to freely mix data of various types, and
+to limit access to contained variables through the use of the \forcode{ONLY} and \forcode{PRIVATE} attributes.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Naming Conventions: variables}
+
+All variable should be named as explicitly as possible in English.
+The naming convention concerns prefix letters of these name, in order to identify the variable type and status. \\
+Never use a FORTRAN keyword as a routine or variable name. \\
+The table below lists the starting letter(s) to be used for variable naming, depending on their type and status:
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[htbp]
+  \begin{center}
+    \begin{tabular}{|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|}
+      \hline
+      Type \par / Status &   integer&   real&   logical &   character&   double \par precision&   complex \\
+      \hline
+      public  \par or  \par module variable& \textbf{m n} \par \textit{but not } \par \textbf{nn\_}& \textbf{a b e f g h o} \textbf{q} \textit{to} \textbf{x} \par but not \par \textbf{fs rn\_}& \textbf{l} \par \textit{but not} \par \textbf{lp ld ll ln\_}& \textbf{c} \par \textit{but not} \par \textbf{cp cd cl cn\_}& \textbf{d} \par \textit{but not} \par \textbf{dp dd dl dn\_}& \textbf{y} \par \textit{but not} \par \textbf{yp yd yl} \\
+      \hline
+      dummy \par argument& \textbf{k} \par \textit{but not} \par \textbf{kf}& \textbf{p} \par \textit{but not}  \par \textbf{pp pf}& \textbf{ld}& \textbf{cd}& \textbf{dd}& \textbf{yd} \\
+      \hline
+      local \par variable& \textbf{i}& \textbf{z}& \textbf{ll}& \textbf{cl}& \textbf{cd}& \textbf{yl} \\
+      \hline
+      loop \par control& \textbf{j} \par \textit{but not } \par \textbf{jp}& & & & &  \\
+      \hline
+      parameter& \textbf{jp}& \textbf{pp}& \textbf{lp}& \textbf{cp}& \textbf{dp}& \textbf{yp} \\
+      \hline
+      namelist& \textbf{nn\_}& \textbf{rn\_}& \textbf{ln\_}& \textbf{cn\_}& \textbf{dn\_}& \\
+      \hline
+      CPP \par macro& \textbf{kf}& \textbf{sf} \par & & & & \\
+      \hline
+    \end{tabular}
+    \label{tab1}
+  \end{center}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Operators}
+
+Use of the operators \texttt{<, >, <=, >=, ==, /=} is strongly recommended instead of their deprecated counterparts
+(\texttt{.lt., .gt., .le., .ge., .eq., .ne.}).
+The motivation is readability.
+In general use the notation: \\
+$<Blank><Operator><Blank>$
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Pre processor}
+
+Where the use of a language pre-processor is required, it will be the C pre-processor (cpp). \\
+The cpp key is the main feature used, allowing to ignore some useless parts of the code at compilation step. \\
+The advantage is to reduce the memory use; the drawback is that compilation of this part of the code isn't checked. \\
+The cpp key feature should only be used for a few limited options, if it reduces the memory usage.
+In all cases, a logical variable and a FORTRAN \forcode{IF} should be preferred.
+When using a cpp key \textit{key\_optionname},
+a corresponding logical variable \textit{lk\_optionname} should be declared to
+allow FORTRAN \forcode{IF} tests in the code and
+a FORTRAN module with the same name ($i.e.$ \textit{optionname.F90}) should be defined.
+This module is the only place where a \``\#if defined'' command appears, selecting either the whole FORTRAN code or
+a dummy module.
+For example, the TKE vertical physics, the module name is \textit{zdftke.F90},
+the CPP key is \textit{key\_zdftke} and the associated logical is \textit{lk\_zdftke}.
+
+The following syntax:
+
+\begin{forlines}
+#if defined key_optionname
+!! Part of code conditionally compiled if cpp key key_optionname is active
+#endif
+\end{forlines}
+
+Is to be used rather than the \#ifdef abbreviate form since it may have conflicts with some Unix scripts.
+
+Tests on cpp keys included in NEMO at compilation step:
+
+\begin{itemize}
+\item
+  The CPP keys used are compared to the previous list of cpp keys
+  (the compilation will stop if trying to specify a non-existing key)
+\item
+  If a change occurs in the CPP keys used for a given experiment, the whole compilation phase is done again.
+\end{itemize}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Content rules}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Configurations}
+
+The configuration defines the domain and the grid on which NEMO is running.
+It may be useful to associate a cpp key and some variables to a given configuration, although
+the part of the code changed under each of those keys should be minimized.
+As an example, the "ORCA2" configuration (global ocean, 2 degrees grid size) is associated with
+the cpp key \texttt{key\_orca2} for which
+
+\begin{forlines}
+cp_cfg = "orca"
+jp_cfg = 2
+\end{forlines}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Constants}
+
+Physical constants ($e.g.$ $\pi$, gas constants) must never be hardwired into the executable portion of a code.
+Instead, a mnemonically named variable or parameter should be set to the appropriate value,
+in the setup routine for the package\index{package}.
+We realize than many parameterizations rely on empirically derived constants or fudge factors,
+which are not easy to name.
+In these cases it is not forbidden to leave such factors coded as "magic numbers" buried in executable code, but
+comments should be included referring to the source of the empirical formula.
+Hard-coded numbers should never be passed through argument lists.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Declaration for variables and constants}
+
+\subsubsection{Rules}
+
+Variables used as constants should be declared with attribute \forcode{PARAMETER} and
+used always without copying to local variables, in order to
+prevent from using different values for the same constant or changing it accidentally.
+
+\begin{itemize}
+\item
+  Usage of the \forcode{DIMENSION} statement or attribute is required in declaration statements
+\item
+  The ``::'' notation is quite useful to show that this program unit declaration part is written in
+  standard FORTRAN syntax, even if there are no attributes to clarify the declaration section.
+  Always use the notation $<$blank$>$::$<$three blanks$>$ to improve readability.
+\item
+  Declare the length of a character variable using the \forcode{CHARACTER} (len=xxx) syntax
+  \footnote {
+    The len specifier is important because it is possible to have several kinds for characters
+    ($e.g.$ Unicode using two bytes per character, or there might be a different kind for Japanese $e.g.$ NEC).
+  }
+\item
+  For all global data (in contrast to module data, that is all data that can be access by other module)
+  must be accompanied with a comment field on the same line
+  \footnote {
+    This allows a easy research of where and how a variable is declared using the unix command:
+    ``grep var *90 | grep !:''.
+  }.
+  For example:
+  \begin{forlines}
+  REAL(wp), DIMENSION(jpi,jpj,jpk) ::  ua   ! i-horizontal velocity (m/s)
+  \end{forlines}
+\end{itemize}
+
+\subsubsection{Implicit None}
+
+All subroutines and functions will include an \forcode{IMPLICIT NONE} statement.
+Thus all variables must be explicitly typed.
+It also allows the compiler to detect typographical errors in variable names.
+For modules, one \forcode{IMPLICIT NONE} statement in the modules definition section is needed.
+This also removes the need to have \forcode{IMPLICIT NONE} statements in
+any routines that are \forcode{CONTAINS}'ed in the module.
+Improper data initialisation is another common source of errors
+\footnote{
+  A variable could contain an initial value you did not expect.
+  This can happen for several reasons, $e.g.$ the variable has never been assigned a value, its value is outdated,
+  memory has been allocated for a pointer but you have forgotten to initialise the variable pointed to.
+}.
+To avoid problems, initialise variables as close as possible to where they are first used.
+
+\subsubsection{Attributes}
+
+\forcode{PRIVATE} / \forcode{PUBLIC}:
+All resources of a module are \forcode{PUBLIC} by default.
+A reason to store multiple routines and their data in a single module is that
+the scope of the data defined in the module can be limited to the routines which are in the same module.
+This is accomplished with the \forcode{PRIVATE} attribute. \\
+\forcode{INTENT}:
+All dummy arguments of a routine must include the \forcode{INTENT} clause in their declaration in order to
+improve control of variables in routine calls.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Headers}
+
+Prologues are not used in NEMO for now, although it may become an interesting tool in combination with
+ProTeX auto documentation script in the future.
+Rules to code the headers and layout of a module or a routine are illustrated in the example module available with
+the code: \path{./src/OCE/module_example}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Interface blocks}
+
+Explicit interface blocks are required between routines if optional or keyword arguments are to be used.
+They also allow the compiler to check that the type, shape and number of arguments specified in the \forcode{CALL}
+are the same as those specified in the subprogram itself.
+FORTRAN 95 compilers can automatically provide explicit interface blocks for routines contained in a module.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{I/O Error Conditions}
+
+I/O statements which need to check an error condition will use the \texttt{iostat=<integer variable>} construct
+instead of the outmoded \texttt{end=} and \forcode{err=}. \\
+Note that a 0 value means success, a positive value means an error has occurred, and
+a negative value means the end of record or end of file was encountered.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{PRINT - ASCII output files}
+
+Output listing and errors are directed to \texttt{numout} logical unit =6 and
+produces a file called \textit{ocean.output} (use \texttt{ln\_prt} to have one output per process in MPP).
+Logical \texttt{lwp} variable allows for less verbose outputs.
+To output an error from a routine, one can use the following template:
+
+\begin{forlines}
+IF( nstop /= 0 .AND. lwp ) THEN   ! error print
+   WRITE(numout,cform_err)
+   WRITE(numout,*) nstop, ' error have been found'
+ENDIF
+\end{forlines}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Precision}
+
+Parameterizations should not rely on vendor-supplied flags to supply a default floating point precision or
+integer size.
+The F95 \forcode{KIND} feature should be used instead.
+In order to improve portability between 32 and 64 bit platforms,
+it is necessary to make use of kinds by using a specific module \path{./src/OCE/par_kind.F90}
+declaring the "kind definitions" to obtain the required numerical precision and range as well as
+the size of \forcode{INTEGER}.
+It should be noted that numerical constants need to have a suffix of \texttt{\_kindvalue} to
+have the according size. \\
+Thus \forcode{wp} being the "working precision" as declared in \path{./src/OCE/par_kind.F90},
+declaring real array \forcode{zpc} will take the form:
+
+\begin{forlines}
+REAL(wp), DIMENSION(jpi,jpj,jpk) ::  zpc      ! power consumption
+\end{forlines}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Structures}
+
+The \forcode{TYPE} structure allowing to declare some variables is more often used in NEMO,
+especially in the modules dealing with reading fields, or interfaces.
+For example:
+
+\begin{forlines}
+! Definition of a tracer as a structure
+TYPE PTRACER
+   CHARACTER(len = 20)  :: sname  ! short name
+   CHARACTER(len = 80 ) :: lname  ! long name
+   CHARACTER(len = 20 ) :: unit   ! unit
+   LOGICAL              :: lini   ! read in a file or not
+   LOGICAL              :: lsav   ! ouput the tracer or not
+END TYPE PTRACER
+
+TYPE(PTRACER) , DIMENSION(jptra) :: tracer
+\end{forlines}
+
+Missing rule on structure name??
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Packages coding rules}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Bounds checking}
+
+NEMO is able to run when an array bounds checking option is enabled
+(provided the cpp key \texttt{key\_vectopt\_loop} is not defined). \\
+Thus, constructs of the following form are disallowed:
+
+\begin{forlines}
+REAL(wp) :: arr(1)
+\end{forlines}
+
+where "arr" is an input argument into which the user wishes to index beyond 1.
+Use of the (*) construct in array dimensioning is forbidden also because
+it effectively disables array bounds checking.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Communication}
+
+A package should refer only to its own modules and subprograms and to those intrinsic functions included in
+the Fortran standard. \\
+All communication with the package will be through the argument list or namelist input.
+\footnote{
+  The point behind this rule is that packages should not have to know details of
+  the surrounding model data structures, or the names of variables outside of the package.
+  A notable exception to this rule is model resolution parameters.
+  The reason for the exception is to allow compile-time array sizing inside the package.
+  This is often important for efficiency.
+}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Error conditions}
+
+When an error condition occurs inside a package, a message describing what went wrong will be printed
+(see PRINT - ASCII output files).
+The name of the routine in which the error occurred must be included.
+It is acceptable to terminate execution within a package, but
+the developer may instead wish to return an error flag through the argument list,
+see \textit{stpctl.F90}.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Memory management}
+
+The main action is to identify and declare which arrays are \forcode{PUBLIC} and which are \forcode{PRIVATE}. \\
+As of version 3.3.1 of NEMO, the use of static arrays (size fixed at compile time) has been deprecated.
+All module arrays are now declared \forcode{ALLOCATABLE} and
+allocated in either the \texttt{<module\_name>\_alloc()} or \texttt{<module\_name>\_init()} routines.
+The success or otherwise of each \forcode{ALLOCATE} must be checked using
+the \texttt{stat=<integer\ variable>} optional argument. \\
+
+In addition to arrays contained within modules, many routines in NEMO require local, ``workspace'' arrays to
+hold the intermediate results of calculations.
+In previous versions of NEMO, these arrays were declared in such a way as to be automatically allocated on
+the stack when the routine was called.
+An example of an automatic array is:
+
+\begin{forlines}
+SUBROUTINE sub(n)
+   REAL :: a(n)
+   ...
+END SUBROUTINE sub
+\end{forlines}
+
+The downside of this approach is that the program will crash if it runs out of stack space and
+the reason for the crash might not be obvious to the user.
+
+Therefore, as of version 3.3.1, the use of automatic arrays is deprecated.
+Instead, a new module, \textit{wrk\_nemo.F90}, has been introduced which
+contains 1-,2-,3- and 4-dimensional workspace arrays for use in subroutines.
+These workspace arrays should be used in preference to declaring new, local (allocatable) arrays whenever possible.
+The only exceptions to this are when workspace arrays with lower bounds other than 1 and/or
+with extent(s) greater than those in the \textit{wrk\_nemo.F90} module are required. \\
+
+The 2D, 3D and 4D workspace arrays in \textit{wrk\_nemo.F90} have extents \texttt{jpi}, \texttt{jpj},
+\texttt{jpk} and \texttt{jpts} ($x$, $y$, $z$ and tracers) in the first, second, third and fourth dimensions,
+respectively.
+The 1D arrays are allocated with extent MAX($jpi \times jpj, jpk \times jpj, jpi \times jpk$). \\
+
+The \forcode{REAL (KIND = wp)} workspace arrays in \textit{wrk\_nemo.F90}
+are named $e.g.$ \texttt{wrk\_1d\_1, wrk\_4d\_2} etc. and
+should be accessed by USE'ing the \textit{wrk\_nemo.F90} module.
+Since these arrays are available to any routine,
+some care must be taken that a given workspace array is not already being used somewhere up the call stack.
+To help with this, \textit{wrk\_nemo.F90} also contains some utility routines;
+\texttt{wrk\_in\_use()} and \texttt{wrk\_not\_released()}.
+The former first checks that the requested arrays are not already in use and then sets internal flags to show that
+they are now in use.
+The \texttt{wrk\_not\_released()} routine un-sets those internal flags.
+A subroutine using this functionality for two, 3D workspace arrays named \texttt{zwrk1} and
+\texttt{zwrk2} will look something like:
+
+\begin{forlines}
+SUBROUTINE sub()
+   USE wrk_nemo, ONLY: wrk_in_use, wrk_not_released
+   USE wrk_nemo, ONLY: zwrk1 => wrk_3d_5, zwrk2 => wrk_3d_6
+   !
+   IF(wrk_in_use(3, 5,6)THEN
+      CALL ctl_stop('sub: requested workspace arrays unavailable.')
+      RETURN
+   END IF
+   ...
+   ...
+   IF(wrk_not_released(3, 5,6)THEN
+      CALL ctl_stop('sub: failed to release workspace arrays.')
+   END IF
+   !
+END SUBROUTINE sub
+\end{forlines}
+
+The first argument to each of the utility routines is the dimensionality of the required workspace (1--4).
+Following this there must be one or more integers identifying which workspaces are to be used/released.
+Note that, in the interests of keeping the code as simple as possible,
+there is no use of \forcode{POINTER}s etc. in the \textit{wrk\_nemo.F90} module.
+Therefore it is the responsibility of the developer to ensure that the arguments to \texttt{wrk\_in\_use()} and
+\texttt{wrk\_not\_released()} match the workspace arrays actually being used by the subroutine. \\
+
+If a workspace array is required that has extent(s) less than those of the arrays in
+the \textit{wrk\_nemo.F90} module then the advantages of implicit loops and bounds checking may be retained by
+defining a pointer to a sub-array as follows:
+
+\begin{forlines}
+SUBROUTINE sub()
+   USE wrk_nemo, ONLY: wrk_in_use, wrk_not_released
+   USE wrk_nemo, ONLY: wrk_3d_5
+   !
+   REAL(wp), DIMENSION(:,:,:), POINTER :: zwrk1
+   !
+   IF(wrk_in_use(3, 5)THEN
+      CALL ctl_stop('sub: requested workspace arrays unavailable.')
+      RETURN
+   END IF
+   !
+   zwrk1 => wrk_3d_5(1:10,1:10,1:10)
+   ...
+END SUBROUTINE sub
+\end{forlines}
+
+Here, instead of ``use associating'' the variable \texttt{zwrk1} with the array \texttt{wrk\_3d\_5}
+(as in the first example), it is explicitly declared as a pointer to a 3D array.
+It is then associated with a sub-array of \texttt{wrk\_3d\_5} once the call to
+\texttt{wrk\_in\_use()} has completed successfully.
+Note that in F95 (to which NEMO conforms) it is not possible for either the upper or lower array bounds of
+the pointer object to differ from those of the target array. \\
+
+In addition to the \forcode{REAL (KIND = wp)} workspace arrays,
+\textit{wrk\_nemo.F90} also contains 2D integer arrays and 2D REAL arrays with extent (\texttt{jpi}, \texttt{jpk}),
+$i.e.$ $xz$.
+The utility routines for the integer workspaces are \texttt{iwrk\_in\_use()} and \texttt{iwrk\_not\_released()} while
+those for the $xz$ workspaces are \texttt{wrk\_in\_use\_xz()} and \texttt{wrk\_not\_released\_xz()}.
+
+Should a call to one of the \texttt{wrk\_in\_use()} family of utilities fail,
+an error message is printed along with a table showing which of the workspace arrays are currently in use.
+This should enable the developer to choose alternatives for use in the subroutine being worked on. \\
+
+When compiling NEMO for production runs,
+the calls to {\texttt{wrk\_in\_use()} / \texttt{wrk\_not\_released()} can be reduced to stubs that just
+return \forcode{.false.} by setting the cpp key \texttt{key\_no\_workspace\_check}.
+These stubs may then be inlined (and thus effectively removed altogether) by setting appropriate compiler flags
+($e.g.$ ``-finline'' for the Intel compiler or ``-Q'' for the IBM compiler).
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Optimisation}
+
+Considering the new computer architecture, optimisation cannot be considered independently from the computer type.
+In NEMO, portability is a priority, before any too specific optimisation.
+
+Some tools are available to help: for vector computers, \texttt{key\_vectopt\_loop} allows to unroll a loop
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Package attribute: \forcode{PRIVATE}, \forcode{PUBLIC}, \forcode{USE}, \forcode{ONLY}}
+
+Module variables and routines should be encapsulated by using the \forcode{PRIVATE} attribute.
+What shall be used outside the module can be declared \forcode{PUBLIC} instead.
+Use \forcode{USE} with the \forcode{ONLY} attribute to specify which of the variables, type definitions etc...
+defined in a module are to be made available to the using routine.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection {Parallelism using MPI}
+
+NEMO is written in order to be able to run on one processor, or on one or more using MPI
+($i.e.$ activating the cpp key $key\_mpp\_mpi$).
+The domain decomposition divides the global domain in cubes (see NEMO reference manual).
+Whilst coding a new development, the MPI compatibility has to be taken in account
+(see \path{./src/LBC/lib_mpp.F90}) and should be tested.
+By default, the $x$-$z$ part of the decomposition is chosen to be as square as possible.
+However, this may be overriden by specifying the number of subdomains in latitude and longitude in
+the \texttt{nammpp} section of the namelist file.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Features to be avoided}
+
+The code must follow the current standards of FORTRAN and ANSI C.
+In particular, the code should not produce any WARNING at compiling phase, so that
+users can be easily alerted of potential bugs when some appear in their new developments.
+Below is a list of features to avoid:
+\begin{itemize}
+\item
+  \forcode{COMMON} block
+  (use the declaration part of \forcode{MODULE} instead)
+\item
+  \forcode{EQUIVALENCE}
+  (use \forcode{POINTER} or derived data type instead to form data structure)
+\item
+  Assigned and computed \forcode{GOTO}
+  (use the \forcode{CASE} construct instead)
+\item
+  Arithmetic \forcode{IF} statement
+  (use the block \forcode{IF}, \forcode{ELSE}, \forcode{ELSEIF}, \forcode{ENDIF} or
+  \forcode{SELECT CASE} construct instead)
+\item
+  Labeled \forcode{DO} construct
+  (use unlabeled \forcode{END DO} instead)
+\item
+  \forcode{FORMAT} statement
+  (use character parameters or
+  explicit format- specifiers inside the \forcode{READ} or \forcode{WRITE} statement instead)
+\item
+  \forcode{GOTO} and \forcode{CONTINUE} statements
+  (use \forcode{IF}, \forcode{CASE}, \forcode{DO WHILE}, \forcode{EXIT} or \forcode{CYCLE} statements or
+  a contained ?)
+\item
+  \forcode{PAUSE}
+\item
+  \forcode{ENTRY} statement: a subprogram must only have one entry point.
+\item
+  \forcode{RETURN} is obsolete and so not necessary at the end of program units
+\item
+  \forcode{FUNCTION} statement
+\item
+  Avoid functions with side effects.
+  \footnote{
+    First, the code is easier to understand, if you can rely on
+    the rule that functions don't change their arguments.
+    Second, some compilers generate more efficient code for PURE functions
+    (in FORTRAN 95 there are the attributes PURE and ELEMENTAL), because
+    they can store the arguments in different places.
+    This is especially important on massive parallel and as well on vector machines.
+  }
+\item
+  \forcode{DATA} and \forcode{BLOCK DATA}
+  (use initialisers)
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% \printindex
+% \input NEMO_coding.conv.ind
+
+%\end{document}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/document.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/document.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/document.tex	(revision 11422)
@@ -0,0 +1,112 @@
+
+%% ==============================================================================
+%% Template structure for reference manual
+%% ==============================================================================
+
+%% NEMO release version
+\def \version{4.0rc~}
+
+%% Preamble
+%% ==============================================================================
+
+%% Document layout
+\documentclass[draft]{scrreprt}
+
+%% Load the configuration of the manual
+\input{../main/definitions}
+
+%% Load global *.tex files
+\input{../../global/preamble}
+
+\dominitoc
+
+%% Launch the creation of the indexes
+\input{../../global/indexes}
+
+
+%% End of common preamble between main and sub-files
+%% Override custom cmds for full manual compilation
+\newcommand{\onlyinsubfile}[1]{#1}
+\newcommand{\notinsubfile}[1]{}
+
+\begin{document}
+
+\renewcommand{\onlyinsubfile}[1]{}
+\renewcommand{\notinsubfile}[1]{#1}
+
+\renewcommand{\biblio}{}
+\renewcommand{\pindex}{}
+
+
+%% Frontmatter
+%% ==============================================================================
+
+\pagenumbering{gobble}
+
+%% Title page
+\input{../../global/frontpage}
+
+\maketitle
+\emptythanks
+
+%% Information page (2nd page)
+\input{../../global/info_page}
+
+%% Foreword
+%\frontmatter   %% Chapter numbering off and Roman numerals for page numbers
+\pagenumbering{roman}
+\input{foreword}
+
+%% Table of Contents
+\tableofcontents
+\listoffigures
+\listoftables
+\listoflistings
+
+\clearpage
+%\end{document}
+
+
+%% Mainmatter
+%% ==============================================================================
+
+%\mainmatter   %% Chapter numbering on, page numbering is reset with Arabic numerals
+\pagenumbering{arabic}
+
+\include{chapters}
+
+
+%% Appendix
+%% ==============================================================================
+
+%% Chapter numbering is reset with letters now
+\appendix   
+
+\include{appendices}
+
+%% Append coding rules for every manual
+\input{../../global/coding_rules}
+
+
+%% Backmatter
+%% ==============================================================================
+
+%\backmatter   %% Chapter numbering off
+
+%% Bibliography
+\phantomsection
+\addcontentsline{toc}{chapter}{Bibliography}
+\bibliography{../main/bibliography}
+
+%% Index
+\clearpage
+\phantomsection
+\addcontentsline{toc}{chapter}{Indexes}
+\printindex[keys]
+\printindex[modules]
+\printindex[blocks]
+\printindex[parameters]
+\printindex[subroutines]
+
+\end{document}
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/frontpage.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/frontpage.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/frontpage.tex	(revision 11422)
@@ -0,0 +1,49 @@
+
+\title{\heading}
+\author{\firstauthor \and \secondauthor\thanks{\protect\input{thanks}}}
+\date{\today}
+
+\pretitle{
+  \begin{center}
+\begin{figure}[H]
+  \begin{minipage}[c]{0.35\textwidth}
+    \href{http://www.nemo-ocean.eu}{\includegraphics[width=0.7\textwidth]{logos/NEMO_grey}}
+  \end{minipage}
+  \hfill
+  \begin{minipage}[c]{0.65\textwidth}
+    \centering
+    \large{\em{{N}ucleus for {E}uropean {M}odelling of the {O}cean}}
+  \end{minipage}
+\end{figure}
+\vfill
+    \Huge
+}
+\posttitle{\par\end{center}\vskip 0.5em}
+\preauthor{\begin{center}\Large\lineskip0.5em\begin{tabular}[t]{c}}
+\postauthor{\end{tabular}\par\end{center}}
+\predate{
+  \vfill
+  \begin{center}
+    \large Version \version ---
+}
+\postdate{
+    \par~\\
+    \href{http://doi.org/10.5281/zenodo.\zid}{\includegraphics{{badges/zenodo.\zid}.pdf}}
+  \end{center}
+  \vfill
+  \begin{center}
+    \href{http://www.cmcc.it}{          \includegraphics[height=0.055\textheight]{logos/CMCC}}
+    \hspace{0.5em}
+    \href{http://www.cnrs.fr}{          \includegraphics[height=0.055\textheight]{logos/CNRS}}
+    \hspace{0.9em}
+    \href{http://www.mercator-ocean.fr}{\includegraphics[height=0.055\textheight]{logos/MOI} }
+    \hspace{0.45em}
+    \href{http://www.metoffice.gov.uk}{ \includegraphics[height=0.055\textheight]{logos/UKMO}}
+    \hspace{0.5em}
+    \href{http://nerc.ukri.org}{        \includegraphics[height=0.055\textheight]{logos/NERC}} \\
+    \large{{\em{C}ommunity \hspace{1.5em} {O}cean \hspace{1.5em} {M}odel}}
+  \end{center}
+}
+
+\thanksmarkseries{fnsymbol}
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/highlighting.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/highlighting.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/highlighting.tex	(revision 11422)
@@ -0,0 +1,33 @@
+%% Syntax highlighting configuration
+%% ==============================================================================
+
+\usepackage[outputdir=../build]{minted}
+
+%% Global highlighting style
+\definecolor{bg}{HTML}{f8f8f8}
+\usemintedstyle{emacs}
+\setminted{bgcolor=bg, fontsize=\scriptsize, breaklines, frame=leftline}
+\setminted[xml]{style=borland} %% Specific per language
+
+%% Oneliner
+\newmint[forline]{fortran}{}   % \forline|...|
+\newmint[xmlline]{xml}{}       % \xmlline|...|
+\newmint[cmd]{console}{}       % \cmd|...|
+
+%% Multi-lines
+\newminted[forlines]{fortran}{}   % \begin{forlines}
+\newminted[xmllines]{xml}{}       % \begin{xmllines}
+\newminted[cmds]{console}{}       % \begin{cmds}
+\newminted[clines]{c}{}           % \begin{clines}
+
+%% File
+\newmintedfile[forfile]{fortran}{}   % \forfile{../namelists/nam...}
+
+%% Inline
+\newmintinline[forcode]{fortran}{bgcolor=, fontsize=auto, frame=lines}   % \forcode{...}
+\newmintinline[xmlcode]{xml}{    bgcolor=, fontsize=auto, frame=lines}   % \xmlcode{...}
+\newmintinline[snippet]{console}{bgcolor=, fontsize=auto, frame=lines}   % \snippet{...}
+
+%% Namelists inclusion
+\newcommand{\nlst}[1]{\forfile{../../../namelists/#1}}
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/index.ist
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/index.ist	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/index.ist	(revision 11422)
@@ -0,0 +1,8 @@
+headings_flag 1
+heading_prefix "{\\medskip\\hfill\\large\\textsf{\\textbf{"
+heading_suffix "}}\\hfill}\\medskip\\nopagebreak\n"
+
+delim_0 "\\dotfill~"
+delim_1 "\\dotfill~"
+delim_2 "\\dotfill~"
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/indexes.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/indexes.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/indexes.tex	(revision 11422)
@@ -0,0 +1,32 @@
+
+\usepackage{imakeidx}
+
+%% Index entries (italic font for files, preformat for code)
+\newcommand{\hf}[1]{\textit{#1.h90}   \index{h90 files!#1}}
+\newcommand{\ifile}[1]{\textit{#1.nc} \index{Input NetCDF files!#1.nc}}
+\newcommand{\jp}[1]{\texttt{#1}       \index{Model parameters!#1}}
+\newcommand{\key}[1]{\index[keys]{#1}        \texttt{\textbf{key\_#1}}}
+\newcommand{\mdl}[1]{\index[modules]{#1}     \textit{#1.F90}          }
+\newcommand{\ngn}[1]{\index[blocks]{#1}      \texttt{#1}              }
+\newcommand{\np}[1]{ \index[parameters]{#1}  \texttt{#1}              }
+\newcommand{\rou}[1]{\index[subroutines]{#1} \texttt{#1}              }
+
+\indexsetup{toclevel=section, othercode=\small}
+
+\makeindex[intoc=true, name=keys       , title=CPP keys                      ]
+\makeindex[intoc=true, name=modules    , title=Modules                       ]
+\makeindex[intoc=true, name=blocks     , title=Namelist blocks               ]
+\makeindex[intoc=true, name=parameters , title=Namelist parameters, columns=3]
+\makeindex[intoc=true, name=subroutines, title=Subroutines                   ]
+
+
+%% Load hyperref at the end of the preamble to make it work with other pkgs
+\usepackage{hyperref}                    %% hyper
+\hypersetup{
+%  pdftitle={\heading},
+%  pdfauthor={\firstauthor and \secondauthor},
+  colorlinks,
+  citecolor=olive,
+  linkcolor=blue,
+  urlcolor=gray
+}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/info_page.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/info_page.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/info_page.tex	(revision 11422)
@@ -0,0 +1,72 @@
+
+\thispagestyle{plain}
+
+% ================================================================
+% Disclaimer
+% ================================================================
+\subsubsection*{Disclaimer}
+
+Like all components of the modelling framework,
+the \engine~core engine is developed under the \href{http://www.cecill.info}{CECILL license},
+which is a French adaptation of the GNU GPL (General Public License).
+Anyone may use it freely for research purposes, and is encouraged to
+communicate back to the NEMO team its own developments and improvements.
+
+The model and the present document have been made available as a service to the community.
+We cannot certify that the code and its manual are free of errors.
+Bugs are inevitable and some have undoubtedly survived the testing phase.
+Users are encouraged to bring them to our attention.
+
+The authors assume no responsibility for problems, errors, or incorrect usage of NEMO.
+
+% ================================================================
+% External resources
+% ================================================================
+\subsubsection*{Other resources}
+
+Additional information can be found on:
+\begin{itemize}
+\item the \href{http://www.nemo-ocean.eu}{website} of the project detailing several
+  associated applications and an exhaustive users bibliography
+\item the \href{http://forge.ipsl.jussieu.fr/nemo}{development platform} of the model with
+  the code repository and some main resources (wiki, ticket system, forums, \ldots)
+\item the \href{http://zenodo.org/communities/nemo-ocean}{online archive}
+  delivering the publications issued by the consortium
+\item two mailing lists:
+  the \href{http://listes.ipsl.fr/sympa/info/nemo-newsletter}{newsletter} for
+  top-down communications from the project
+  (announcements, calls, job opportunities, \ldots)
+  and the \href{http://listes.ipsl.fr/sympa/info/nemo-forge}{forge updates}
+  (commits, tickets and forums)
+\end{itemize}
+
+% ================================================================
+% Citation
+% ================================================================
+\subsubsection*{Citation}
+
+Reference for papers and other publications is as follows:
+
+\vspace{0.5cm}
+
+%% \sloppy: workaround for breaking DOI URL
+\sloppy
+``{\bfseries \heading}'', 
+\firstauthor and \secondauthor, 
+{\em Scientific Notes of Climate Modelling Center}, \textbf{\ipslnum} --- ISSN 1288-1619, 
+Institut Pierre-Simon Laplace (IPSL), 
+\href{https://doi.org/10.5281/zenodo.\zid}{doi:10.5281/zenodo.\zid}
+
+\begin{figure}[b]
+  \begin{minipage}[c]{0.72\textwidth}
+    \small\ttfamily{Scientific Notes of Climate Modelling Center \\
+      ISSN 1288-1619                                             \\
+      Institut Pierre-Simon Laplace (IPSL)
+    }
+  \end{minipage}
+  \hfill
+  \begin{minipage}[c]{0.25\textwidth}
+    \href{http://www.cmc.ipsl.fr}{\includegraphics[width=\textwidth]{logos/IPSL_upright}}
+  \end{minipage}
+\end{figure}
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/latexmkrc
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/latexmkrc	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/latexmkrc	(revision 11422)
@@ -0,0 +1,17 @@
+
+## Defaults
+$silent   = 1;
+$pdf_mode = 1;
+
+## Using relative paths
+$ENV{'openout_any'}='a';
+$out_dir = '../build';
+
+## Custom cmds
+$makeindex = 'makeindex -s %R.ist %O -o %D %S';
+$pdflatex  = 'pdflatex -shell-escape %O %S';
+
+#@BIBINPUTS=('.', '../main');
+#$bibtex    = 'bibtex %O ../main/bibliography.bib';
+#$kpsewhich = 'kpsewhich bibliography.bib'
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/new_cmds.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/new_cmds.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/new_cmds.tex	(revision 11422)
@@ -0,0 +1,37 @@
+%% Global custom commands: \newcommand{<name>}[<args>][<first argument value>]{<code>}
+%% ==============================================================================
+
+%% Include references and index for compilation of single subfile 
+\newcommand{\mtoc}{\minitoc}
+\newcommand{\biblio}{\bibliography{../main/bibliography}}
+\newcommand{\pindex}{\printindex}
+
+%% NEMO and Fortran in small capitals
+\newcommand{\NEMO}{\textsc{nemo}~}
+\newcommand{\fortran}{\textsc{Fortran}~}
+\newcommand{\fninety}{\textsc{Fortran 90}~}
+
+%% Common aliases
+\renewcommand{\deg}[1][]{\ensuremath{^{\circ}#1}}
+\newcommand{\zstar }{\ensuremath{z^\star}}
+\newcommand{\sstar }{\ensuremath{s^\star}}
+\newcommand{\ztilde}{\ensuremath{\tilde z}}
+\newcommand{\stilde}{\ensuremath{\tilde s}}
+\newcommand{\ie}{\ensuremath{i.e.}~}
+\newcommand{\eg}{\ensuremath{e.g.}~}
+
+%% Inline maths
+\newcommand{\fractext}[2]{\textstyle \frac{#1}{#2}}
+\newcommand{\rdt}{\Delta t}
+
+%% Text env. for Gurvan
+\newcommand{\gmcomment}[1]{}
+
+%% Maths
+\newcommand{\lt}{\left}
+\newcommand{\rt}{\right}
+\newcommand{\vect}[1]{\ensuremath{\mathbf{#1}}}
+\newcommand{\pd}[2][]{\ensuremath{\frac{\partial #1}{\partial #2}}}
+
+%% Workaround for issue with \listoffigures
+\DeclareRobustCommand{\triad}[6][]{\ensuremath{{}_{#2}^{#3}{\mathbb{#4}_{#1}}_{#5}^{\,#6}}}
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/packages.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/packages.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/packages.tex	(revision 11422)
@@ -0,0 +1,26 @@
+
+%% LaTeX packages in use
+%% ==============================================================================
+
+\usepackage{natbib}                      %% bib
+\usepackage{caption}                     %% caption
+\usepackage{xcolor}                      %% color
+\usepackage{times}                       %% font
+\usepackage{enumitem}                    %% list
+\usepackage{amsmath}                     %% maths
+%\usepackage{fancyhdr}                    %% page
+\usepackage{minitoc}                     %% toc
+\usepackage{subfiles}                    %% subdocs
+\usepackage{draftwatermark}              %% watermark
+\usepackage{titling}                     %% titlepage
+
+%% Extensions in bundle package
+\usepackage{amssymb, graphicx, tabularx, textcomp}
+\usepackage[utf8]{inputenc}              %% input encoding
+
+%% Configuration
+\graphicspath{ {../../figures/} {../../figures/\engine/} }
+%\captionsetup{margin=10pt, font={small}, labelsep=colon, labelfont={bf}}
+\renewcommand{\bibfont}{\small}
+%\renewcommand{\bibsep}{3pt}
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/preamble.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/preamble.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/preamble.tex	(revision 11422)
@@ -0,0 +1,7 @@
+
+\input{../../global/packages}
+\input{../../global/highlighting}
+\input{../../global/new_cmds}
+\input{../../global/styles}
+%\input{../../global/todonotes}
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/styles.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/styles.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/styles.tex	(revision 11422)
@@ -0,0 +1,61 @@
+
+%% Styles
+%% ==============================================================================
+
+%\pagestyle{fancy}
+\bibliographystyle{../../global/ametsoc}
+\renewcommand{\bibpreamble}{\begin{multicols}{2}}
+\renewcommand{\bibpostamble}{\end{multicols}}
+
+%% Additional fonts
+\DeclareMathAlphabet{\mathpzc}{OT1}{pzc}{m}{it}
+
+%% Page layout
+%\fancyhf{}
+%\fancyhead[LE,RO]{\bfseries\thepage}
+%\fancyhead[LO]{\bfseries\hspace{-0em}\rightmark}
+%\renewcommand{\sectionmark}[1]{\markright{\thesection.\ #1}}
+%\fancyhead[RE]{\bfseries\leftmark}
+%\renewcommand{\chaptermark}[1]{\markboth{#1}{}}
+%\renewcommand{\headrulewidth}{0.5pt}
+%\renewcommand{\footrulewidth}{0pt  }
+%\addtolength{\headheight}{2.6pt}
+
+
+%% Catcodes
+%\makeatletter
+%\def\LigneVerticale{\vrule height 5cm depth 2cm\hspace{0.1cm}\relax}
+%\def\LignesVerticales{\let\LV\LigneVerticale\LV\LV\LV\LV\LV\LV\LV\LV\LV\LV}
+%\def\GrosCarreAvecUnChiffre#1{
+%	\rlap{\vrule height 0.8cm width 1cm depth 0.2cm}
+%	\rlap{\hbox to 1cm{\hss\mbox{\color{white} #1}\hss}}
+% 	\vrule height 0pt width 1cm depth 0pt
+%}
+%\def\@makechapterhead#1{
+%	\hbox{
+%		\huge\LignesVerticales\hspace{-0.5cm}
+%		\GrosCarreAvecUnChiffre{\thechapter}\hspace{0.2cm}
+%		\hbox{#1}
+%	}
+%	\par\vskip
+%1cm
+%}
+%\def\@makeschapterhead#1{
+%	\hbox{
+%		\huge\LignesVerticales
+%		\hbox{#1}
+%	}
+%	\par\vskip
+%2cm
+%}
+%\def\cleardoublepage{\clearpage\if@twoside \ifodd\c@page\else
+%  \hbox{}
+%  \vspace*{\fill}
+%  \vspace{\fill}
+%  \thispagestyle{empty}
+%  \newpage
+%  \if@twocolumn\hbox{}\newpage\fi\fi\fi}
+%\def\@seccntformat#1{\protect\makebox[0pt][r]{\csname the#1\endcsname\quad}}
+%\makeatother
+
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/todonotes.tex
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/todonotes.tex	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/global/todonotes.tex	(revision 11422)
@@ -0,0 +1,40 @@
+\usepackage[]{todonotes}
+
+\newcounter{ubcomment}
+\newcommand{\ubcomment}[2][]{%
+\refstepcounter{ubcomment}%
+{%
+\todo[linecolor=black,backgroundcolor={green!40!},size=\footnotesize]{%
+\textbf{Fixme: UB [\uppercase{#1}\theubcomment]:}~#2}%
+}}
+\newcommand{\ubcommentinline}[2][]{%
+\refstepcounter{ubcomment}%
+{%
+\todo[linecolor=black,inline,backgroundcolor={green!40!},size=\footnotesize]{%
+\textbf{Fixme: UB [\uppercase{#1}\theubcomment]:}~#2}%
+}}
+
+\newcommand{\ubcommentmultiline}[2]{%
+\refstepcounter{ubcomment}%
+{%
+\todo[linecolor=black,inline,caption={\textbf{{Fixme: UB}
+    [\theubcomment] #1}} ,backgroundcolor={green!40!},size=\footnotesize]{%
+\textbf{Fixme: UB [\theubcomment]:}~#2}%
+}}
+
+% add support for todo in equations
+%\usepackage{marginnote}
+%\makeatletter
+%\renewcommand{\@todonotes@drawMarginNoteWithLine}{%
+%\begin{tikzpicture}[remember picture, overlay, baseline=-0.75ex]%
+%    \node [coordinate] (inText) {};%
+%\end{tikzpicture}%
+%\marginnote[{% Draw note in left margin
+%    \@todonotes@drawMarginNote%
+%    \@todonotes@drawLineToLeftMargin%
+%}]{% Draw note in right margin
+%    \@todonotes@drawMarginNote%
+%    \@todonotes@drawLineToRightMargin%
+%}%
+%}
+%\makeatother
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/manual_build.sh
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/manual_build.sh	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/manual_build.sh	(revision 11422)
@@ -0,0 +1,47 @@
+#!/bin/sh
+
+## Initialisation
+##---------------
+
+## Default selection for models
+if   [ "$1" = 'all' ]; then
+    models='NEMO SI3 TOP'
+elif [ "$1" =    '' ]; then
+    models='NEMO'
+else
+    models=$*
+fi
+
+# Source shared functions
+. tools/shr_func.sh
+
+
+## Check dependancies
+##-------------------
+
+## LaTeX installation, find latexmk should be enough
+[ -z $( which latexmk ) ] && { echo 'latexmk not installed => QUIT'; exit 2; }
+
+## Pygments package for syntax highlighting of source code (namelists & snippets)
+[ -n "$( ./tools/check_pkg.py pygments )" ] && { echo 'Python pygments is missing => QUIT'; exit 2; }
+
+## Retrieve figures if not already there
+if [ ! -d latex/figures ]; then
+    printf "Downloading of shared figures and logos\n\n"
+    svn co https://forge.ipsl.jussieu.fr/nemo/svn/utils/figures latex/figures > /dev/null
+fi
+
+
+## Loop on the models
+##-------------------
+
+for model in $models; do
+    echo $model
+    clean $model
+    build $model
+    printf "\t¤ End of building run\n"
+    echo
+done
+
+exit 0
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nambdy
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nambdy	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nambdy	(revision 11422)
@@ -3,42 +3,34 @@
 !-----------------------------------------------------------------------
    ln_bdy         = .false.   !  Use unstructured open boundaries
-   nb_bdy         = 2         !  number of open boundary sets
-   ln_coords_file = .true. , .false.    !  =T : read bdy coordinates from file
+   nb_bdy         = 0         !  number of open boundary sets
+   ln_coords_file = .true.    !  =T : read bdy coordinates from file
       cn_coords_file = 'coordinates.bdy.nc'  !  bdy coordinates files
    ln_mask_file   = .false.   !  =T : read mask from file
-      cn_mask_file = ''       !  name of mask file (if ln_mask_file=.TRUE.)
-   cn_dyn2d    = 'flather', 'none'       !
-   nn_dyn2d_dta   =  3 , 0    !  = 0, bdy data are equal to the initial state
+      cn_mask_file = ''        !  name of mask file (if ln_mask_file=.TRUE.)
+   cn_dyn2d    = 'none'       !
+   nn_dyn2d_dta   =  0        !  = 0, bdy data are equal to the initial state
       !                       !  = 1, bdy data are read in 'bdydata   .nc' files
       !                       !  = 2, use tidal harmonic forcing data from files
       !                       !  = 3, use external data AND tidal harmonic forcing
-   cn_dyn3d      =  'none' , 'none'
-   nn_dyn3d_dta  =  0 , 0     !  = 0, bdy data are equal to the initial state
+   cn_dyn3d      =  'none'    !
+   nn_dyn3d_dta  =  0         !  = 0, bdy data are equal to the initial state
    !                          !  = 1, bdy data are read in 'bdydata   .nc' files
-   cn_tra        =  'frs' , 'frs'
-   nn_tra_dta    =  1 , 0     !  = 0, bdy data are equal to the initial state
+   cn_tra        =  'none'    !
+   nn_tra_dta    =  0         !  = 0, bdy data are equal to the initial state
    !                          !  = 1, bdy data are read in 'bdydata   .nc' files
-   cn_ice        =  'none' , 'none'
-   nn_ice_dta    =  0, 0      !  = 0, bdy data are equal to the initial state
+   cn_ice        =  'none'    !
+   nn_ice_dta    =  0         !  = 0, bdy data are equal to the initial state
    !                          !  = 1, bdy data are read in 'bdydata   .nc' files
-   rn_ice_tem    = 270., 270. !  si3 only: arbitrary temperature of incoming sea ice
-   rn_ice_sal    = 10. ,  10. !  si3 only:      --   salinity           --
-   rn_ice_age    = 30. ,  30. !  si3 only:      --   age                --
+   rn_ice_tem    = 270.       !  si3 only: arbitrary temperature of incoming sea ice
+   rn_ice_sal    = 10.        !  si3 only:      --   salinity           --
+   rn_ice_age    = 30.        !  si3 only:      --   age                --
    !
-   ln_tra_dmp    =.false., .false.  !  open boudaries conditions for tracers
-   ln_dyn3d_dmp  =.false., .false.  !  open boundary condition for baroclinic velocities
-   rn_time_dmp   =  1., 1.    !  Damping time scale in days
-   rn_time_dmp_out = 1., 1.    !  Outflow damping time scale
-   nn_rimwidth   = 10, 5      !  width of the relaxation zone
+   ln_tra_dmp    =.false.     !  open boudaries conditions for tracers
+   ln_dyn3d_dmp  =.false.     !  open boundary condition for baroclinic velocities
+   rn_time_dmp   =  1.        !  Damping time scale in days
+   rn_time_dmp_out = 1.        !  Outflow damping time scale
+   nn_rimwidth   = 10         !  width of the relaxation zone
    ln_vol        = .false.    !  total volume correction (see nn_volctl parameter)
    nn_volctl     =  1         !  = 0, the total water flux across open boundaries is zero
    nb_jpk_bdy    = -1         ! number of levels in the bdy data (set < 0 if consistent with planned run)
 /
-!-----------------------------------------------------------------------
-&nambdy_index     ! index definition of bdy
-!-----------------------------------------------------------------------
-    ctypebdy = 'S'
-    nbdyind  =  2
-    nbdybeg  = 2
-    nbdyend  = 273
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namberg
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namberg	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namberg	(revision 11422)
@@ -5,31 +5,31 @@
    !
    !                          ! diagnostics:
-   ln_bergdia        = .true.       ! Calculate budgets
-   nn_verbose_level  = 1            ! Turn on more verbose output if level > 0
-   nn_verbose_write  = 15           ! Timesteps between verbose messages
-   nn_sample_rate    = 1            ! Timesteps between sampling for trajectory storage
+   ln_bergdia        = .true.        ! Calculate budgets
+   nn_verbose_level  = 0             ! Turn on more verbose output if level > 0
+   nn_verbose_write  = 15            ! Timesteps between verbose messages
+   nn_sample_rate    = 1             ! Timesteps between sampling for trajectory storage
    !
    !                          ! iceberg setting:
-   !                                ! Initial mass required for an iceberg of each class
+   !                                 ! Initial mass required for an iceberg of each class
    rn_initial_mass   = 8.8e7, 4.1e8, 3.3e9, 1.8e10, 3.8e10, 7.5e10, 1.2e11, 2.2e11, 3.9e11, 7.4e11
-   !                                ! Proportion of calving mass to apportion to each class
+   !                                 ! Proportion of calving mass to apportion to each class
    rn_distribution   = 0.24, 0.12, 0.15, 0.18, 0.12, 0.07, 0.03, 0.03, 0.03, 0.02
-   !                                ! Ratio between effective and real iceberg mass (non-dim)
-   !                                ! i.e. number of icebergs represented at a point
-   rn_mass_scaling   = 2000, 200, 50, 20, 10, 5, 2, 1, 1, 1
-                                    ! thickness of newly calved bergs (m)
+   !                                 ! Ratio between effective and real iceberg mass (non-dim)
+   !                                 ! i.e. number of icebergs represented at a point
+   rn_mass_scaling   = 2000., 200., 50., 20., 10., 5., 2., 1., 1., 1.
+                                     ! thickness of newly calved bergs (m)
    rn_initial_thickness     = 40., 67., 133., 175., 250., 250., 250., 250., 250., 250.
    !
-   rn_rho_bergs            = 850.   ! Density of icebergs
-   rn_LoW_ratio            = 1.5    ! Initial ratio L/W for newly calved icebergs
-   ln_operator_splitting   = .true. ! Use first order operator splitting for thermodynamics
-   rn_bits_erosion_fraction = 0.    ! Fraction of erosion melt flux to divert to bergy bits
-   rn_sicn_shift           = 0.     ! Shift of sea-ice concn in erosion flux (0<sicn_shift<1)
-   ln_passive_mode         = .false.! iceberg - ocean decoupling
-   nn_test_icebergs        =  10    ! Create test icebergs of this class (-1 = no)
-   !                                ! Put a test iceberg at each gridpoint in box (lon1,lon2,lat1,lat2)
+   rn_rho_bergs            = 850.    ! Density of icebergs
+   rn_LoW_ratio            = 1.5     ! Initial ratio L/W for newly calved icebergs
+   ln_operator_splitting   = .true.  ! Use first order operator splitting for thermodynamics
+   rn_bits_erosion_fraction = 0.     ! Fraction of erosion melt flux to divert to bergy bits
+   rn_sicn_shift           = 0.      ! Shift of sea-ice concn in erosion flux (0<sicn_shift<1)
+   ln_passive_mode         = .false. ! iceberg - ocean decoupling
+   nn_test_icebergs        =  10     ! Create test icebergs of this class (-1 = no)
+   !                                 ! Put a test iceberg at each gridpoint in box (lon1,lon2,lat1,lat2)
    rn_test_box             = 108.0,  116.0, -66.0, -58.0
-   ln_use_calving          = .false.! Use calving data even when nn_test_icebergs > 0
-   rn_speed_limit          = 0.     ! CFL speed limit for a berg
+   ln_use_calving          = .false. ! Use calving data even when nn_test_icebergs > 0
+   rn_speed_limit          = 0.      ! CFL speed limit for a berg
 
    cn_dir      = './'      !  root directory for the calving data location
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdom
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdom	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdom	(revision 11422)
@@ -5,5 +5,5 @@
    rn_isfhmin  =    1.00   !  treshold [m] to discriminate grounding ice from floating ice
    !
-   rn_rdt      = 5760.     !  time step for the dynamics and tracer
+   rn_rdt      = 5400.     !  time step for the dynamics and tracer
    rn_atfp     =    0.1    !  asselin time filter parameter
    !
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdom_domcfg
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdom_domcfg	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdom_domcfg	(revision 11422)
@@ -0,0 +1,39 @@
+!-----------------------------------------------------------------------
+&namdom        !   space and time domain (bathymetry, mesh, timestep)
+!-----------------------------------------------------------------------
+   nn_bathy    =    1      !  compute (=0) or read (=1) the bathymetry file
+   rn_bathy    =    0.     !  value of the bathymetry. if (=0) bottom flat at jpkm1
+   nn_closea   =    0      !  remove (=0) or keep (=1) closed seas and lakes (ORCA)
+   nn_msh      =    1      !  create (=1) a mesh file or not (=0)
+   rn_hmin     =   -3.     !  min depth of the ocean (>0) or min number of ocean level (<0)
+   rn_isfhmin  =    1.00   !  treshold (m) to discriminate grounding ice to floating ice
+   rn_e3zps_min=   20.     !  partial step thickness is set larger than the minimum of
+   rn_e3zps_rat=    0.1    !  rn_e3zps_min and rn_e3zps_rat*e3t, with 0<rn_e3zps_rat<1
+                           !
+   rn_rdt      = 5760.     !  time step for the dynamics (and tracer if nn_acc=0)
+   rn_atfp     =    0.1    !  asselin time filter parameter
+   ln_crs      = .false.      !  Logical switch for coarsening module
+   jphgr_msh   =       0               !  type of horizontal mesh
+                                       !  = 0 curvilinear coordinate on the sphere read in coordinate.nc
+                                       !  = 1 geographical mesh on the sphere with regular grid-spacing
+                                       !  = 2 f-plane with regular grid-spacing
+                                       !  = 3 beta-plane with regular grid-spacing
+                                       !  = 4 Mercator grid with T/U point at the equator
+   ppglam0     =       0.0             !  longitude of first raw and column T-point (jphgr_msh = 1)
+   ppgphi0     =     -35.0             ! latitude  of first raw and column T-point (jphgr_msh = 1)
+   ppe1_deg    =       1.0             !  zonal      grid-spacing (degrees)
+   ppe2_deg    =       0.5             !  meridional grid-spacing (degrees)
+   ppe1_m      =    5000.0             !  zonal      grid-spacing (degrees)
+   ppe2_m      =    5000.0             !  meridional grid-spacing (degrees)
+   ppsur       =    -4762.96143546300  !  ORCA r4, r2 and r05 coefficients
+   ppa0        =      255.58049070440  ! (default coefficients)
+   ppa1        =      245.58132232490  !
+   ppkth       =       21.43336197938  !
+   ppacr       =        3.0            !
+   ppdzmin     =       10.             !  Minimum vertical spacing
+   pphmax      =     5000.             !  Maximum depth
+   ldbletanh   =    .TRUE.             !  Use/do not use double tanf function for vertical coordinates
+   ppa2        =      100.760928500000 !  Double tanh function parameters
+   ppkth2      =       48.029893720000 !
+   ppacr2      =       13.000000000000 !
+/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdyn
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdyn	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdyn	(revision 11422)
@@ -17,4 +17,4 @@
                                       !          recommended range: ?? L16=15 - home=10
       rn_lfrelax    =   1.e-5         !        relaxation time scale to reach static friction [s-1]
-      rn_tensile    =   0.2           !        isotropic tensile strength
+      rn_tensile    =   0.2           !        ln_landfast_L16: isotropic tensile strength
 /
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdyn_rhg
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdyn_rhg	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdyn_rhg	(revision 11422)
@@ -3,5 +3,5 @@
 !------------------------------------------------------------------------------
    ln_rhg_EVP       = .true.          !  EVP rheology
-      ln_aEVP       = .true.          !     adaptive rheology (Kimmritz et al. 2016 & 2017)
+      ln_aEVP       = .false.         !     adaptive rheology (Kimmritz et al. 2016 & 2017)
       rn_creepl     =   2.0e-9        !     creep limit [1/s]
       rn_ecc        =   2.0           !     eccentricity of the elliptical yield curve          
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdyn_vor
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdyn_vor	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdyn_vor	(revision 11422)
@@ -8,5 +8,5 @@
    ln_dynvor_eeT = .false. !  energy conserving scheme (een using e3t)
    ln_dynvor_een = .false. !  energy & enstrophy scheme
-      nn_een_e3f = 1          ! =0  e3f = mi(mj(e3t))/4 
+      nn_een_e3f = 0          ! =0  e3f = mi(mj(e3t))/4 
       !                       ! =1  e3f = mi(mj(e3t))/mi(mj( tmask))
    ln_dynvor_msk = .false. !  vorticity multiplied by fmask (=T)        ==>>> PLEASE DO NOT ACTIVATE
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namforcing
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namforcing	(revision 10999)
+++ 	(revision )
@@ -1,13 +1,0 @@
-!------------------------------------------------------------------------------
-&namforcing     !   Ice surface forcing
-!------------------------------------------------------------------------------
-   rn_cio           =   5.0e-03       !  ice-ocean drag coefficient (-)
-   rn_blow_s        =   0.66          !  mesure of snow blowing into the leads
-                                      !     = 1 => no snow blowing, < 1 => some snow blowing
-   nn_flxdist       =  -1             !  Redistribute heat flux over ice categories
-                                      !     =-1  Do nothing (needs N(cat) fluxes)
-                                      !     = 0  Average N(cat) fluxes then apply the average over the N(cat) ice
-                                      !     = 1  Average N(cat) fluxes then redistribute over the N(cat) ice using T-ice and albedo sensitivity
-                                      !     = 2  Redistribute a single flux over categories
-   nice_jules       = 0               !  Jules coupling (0=OFF, 1=EMULATED, 2=ACTIVE)
-/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namobs
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namobs	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namobs	(revision 11422)
@@ -8,5 +8,5 @@
    ln_sla      = .false.             ! Logical switch for SLA observations
    ln_sst      = .false.             ! Logical switch for SST observations
-   ln_sss      = .false.             ! Logical swithc for SSS observations
+   ln_sss      = .false.             ! Logical switch for SSS observations
    ln_sic      = .false.             ! Logical switch for Sea Ice observations
    ln_vel3d    = .false.             ! Logical switch for velocity observations
@@ -19,4 +19,5 @@
    ln_s_at_t   = .false.             ! Logical switch for computing model S at T obs if not there
    ln_sstnight = .false.             ! Logical switch for calculating night-time average for SST obs
+   ln_bound_reject  = .false.        ! Logical to remove obs near boundaries in LAMs.
    ln_sla_fp_indegs = .true.         ! Logical for SLA: T=> averaging footprint is in degrees, F=> in metres
    ln_sst_fp_indegs = .true.         ! Logical for SST: T=> averaging footprint is in degrees, F=> in metres
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampar
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampar	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampar	(revision 11422)
@@ -5,7 +5,6 @@
    nlay_i           =   2             !  number of ice  layers
    nlay_s           =   1             !  number of snow layers (only 1 is working)
-   nn_virtual_itd   =   0             !  virtual ITD mono-category parameterizations (1-3 => jpl = 1 only) or not (0)
-                                      !     2: activate enhanced thermal conductivity only --- temporary option
-                                      !     3: activate virtual thin ice melting only      ---  temporary option
+   ln_virtual_itd   =   .false.       !  virtual ITD mono-category parameterization (jpl=1 only)
+                                      !     i.e. enhanced thermal conductivity & virtual thin ice melting
    ln_icedyn        = .true.          !  ice dynamics (T) or not (F)
    ln_icethd        = .true.          !  ice thermo   (T) or not (F)
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampisfer
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampisfer	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampisfer	(revision 11422)
@@ -2,5 +2,5 @@
 &nampisfer     !   parameters for iron chemistry
 !-----------------------------------------------------------------------
-   ln_ligvar =  .true.    ! variable ligand concentration
+   ln_ligvar =  .false.    ! variable ligand concentration
    xlam1     =  0.005     ! scavenging rate of Iron
    xlamdust  =  150.0     ! Scavenging rate of dust
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namrun
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namrun	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namrun	(revision 11422)
@@ -5,5 +5,5 @@
    cn_exp      =  "ORCA2"  !  experience name
    nn_it000    =       1   !  first time step
-   nn_itend    =    5475   !  last  time step (std 5475)
+   nn_itend    =    5840   !  last  time step (std 5840)
    nn_date0    =  010101   !  date at nit_0000 (format yyyymmdd) used if ln_rstart=F or (ln_rstart=T and nn_rstctl=0 or 1)
    nn_time0    =       0   !  initial time of day in hhmm
@@ -22,7 +22,7 @@
    nn_istate   =       0   !  output the initial state (1) or not (0)
    ln_rst_list = .false.   !  output restarts at list of times using nn_stocklist (T) or at set frequency with nn_stock (F)
-   nn_stock    =    5475   !  frequency of creation of a restart file (modulo referenced to 1)
+   nn_stock    =    5840   !  frequency of creation of a restart file (modulo referenced to 1)
    nn_stocklist = 0,0,0,0,0,0,0,0,0,0 ! List of timesteps when a restart file is to be written
-   nn_write    =    5475   !  frequency of write in the output file   (modulo referenced to nn_it000)
+   nn_write    =    5840   !  frequency of write in the output file   (modulo referenced to nn_it000)
    ln_mskland  = .false.   !  mask land points in NetCDF outputs (costly: + ~15%)
    ln_cfmeta   = .false.   !  output additional data to netCDF files required for compliance with the CF metadata standard
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namsbc
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namsbc	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namsbc	(revision 11422)
@@ -2,5 +2,5 @@
 &namsbc        !   Surface Boundary Condition manager                   (default: NO selection)
 !-----------------------------------------------------------------------
-   nn_fsbc     = 5         !  frequency of SBC module call
+   nn_fsbc     = 2         !  frequency of SBC module call
       !                    !  (control sea-ice & iceberg model call)
                      ! Type of air-sea fluxes 
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namthd_do
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namthd_do	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namthd_do	(revision 11422)
@@ -2,5 +2,5 @@
 &namthd_do      !   Ice growth in open water
 !------------------------------------------------------------------------------
-   rn_hinew         =   0.1           !  thickness for new ice formation in open water (m), must be larger than rn_hnewice
+   rn_hinew         =   0.1           !  thickness for new ice formation in open water (m), must be larger than rn_himin
    ln_frazil        = .false.         !  Frazil ice parameterization (ice collection as a function of wind)
       rn_maxfraz    =   1.0           !     maximum fraction of frazil ice collecting at the ice base
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namthd_pnd
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namthd_pnd	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namthd_pnd	(revision 11422)
@@ -3,8 +3,7 @@
 !------------------------------------------------------------------------------
    ln_pnd_H12       = .false.         !  activate evolutive melt ponds (from Holland et al 2012)
-      ln_pnd_fwb    = .false.         !     melt ponds store freshwater or not
-   ln_pnd_CST       = .false.         !  activate constant melt ponds
-      rn_apnd       =   0.2           !     prescribed pond fraction, at Tsu=0
-      rn_hpnd       =   0.05          !     prescribed pond depth, at Tsu=0
+   ln_pnd_CST       = .false.         !  activate constant  melt ponds
+      rn_apnd       =   0.2           !     prescribed pond fraction, at Tsu=0 degC
+      rn_hpnd       =   0.05          !     prescribed pond depth,    at Tsu=0 degC
    ln_pnd_alb       = .false.         !  melt ponds affect albedo or not
 /
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namthd_sal
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namthd_sal	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namthd_sal	(revision 11422)
@@ -5,10 +5,10 @@
                                       !     1: constant ice salinity (S=rn_icesal)
                                       !     2: varying salinity parameterization S(z,t)
-                                      !     3: prescribed salinity profile S(z), Schwarzacher, 1959
-   rn_icesal        =   4.            !    (nn_icesal=1) ice salinity (g/kg)
-   rn_sal_gd        =   5.            !  restoring ice salinity, gravity drainage (g/kg)
-   rn_time_gd       =   1.73e+6       !  restoring time scale, gravity drainage  (s)
-   rn_sal_fl        =   2.            !  restoring ice salinity, flushing (g/kg)
-   rn_time_fl       =   8.64e+5       !  restoring time scale, flushing (s)
+                                      !     3: prescribed salinity profile S(z) (Schwarzacher 1959)
+   rn_icesal        =   4.            !      (nn_icesal=1) ice salinity (g/kg)
+   rn_sal_gd        =   5.            !      (nn_icesal=2) restoring ice salinity, gravity drainage (g/kg)
+   rn_time_gd       =   1.73e+6       !      (nn_icesal=2) restoring time scale,   gravity drainage  (s)
+   rn_sal_fl        =   2.            !      (nn_icesal=2) restoring ice salinity, flushing (g/kg)
+   rn_time_fl       =   8.64e+5       !      (nn_icesal=2) restoring time scale,   flushing (s)
    rn_simax         =  20.            !  maximum tolerated ice salinity (g/kg)
    rn_simin         =   0.1           !  minimum tolerated ice salinity (g/kg)
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namwad
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namwad	(revision 10999)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namwad	(revision 11422)
@@ -1,15 +1,15 @@
 !-----------------------------------------------------------------------
-&namwad  !   Wetting and drying
+&namwad        !   Wetting and Drying (WaD)                             (default: OFF)
 !-----------------------------------------------------------------------
-   ln_wd_il          = .false   ! T/F activation of iterative limiter for  wetting and drying scheme
-   ln_wd_dl          = .true.   ! T/F activation of directional llimiter for wetting drying scheme
-   ln_wd_dl_bc       = .true.   ! T/F Directional limiteer Baroclinic option
-   ln_wd_dl_rmp      = .true.   ! T/F Turn on directional limiter ramp
-   rn_wdmin0         =  0.30    ! dpoth at which wetting/drying starts
-   rn_wdmin1         =  0.2     ! Minimum wet depth on dried cells
-   rn_wdmin2         =  0.0001  ! Tolerance of min wet depth on dried cells
-   rn_wdld           =  2.5     ! Land elevation below which wetting/drying is allowed
-   nn_wdit           =   20     ! Max iterations for W/D limiter
-   rn_wd_sbcdep      =  5.0     ! Depth at which to taper sbc fluxes
-   rn_wd_sbcfra      =  0.999   ! Fraction of SBC fluxes at taper depth (Must be <1)
+   ln_wd_il    = .false.   !  T/F activation of iterative   limiter
+   ln_wd_dl    = .false.   !  T/F activation of directional limiter
+   ln_wd_dl_bc = .false.   !  T/F Directional limiteer Baroclinic option
+   ln_wd_dl_rmp = .false.  !  T/F Turn on directional limiter ramp
+   rn_wdmin0   =  0.30     !  depth at which WaD starts
+   rn_wdmin1   =  0.2      !  Minimum wet depth on dried cells
+   rn_wdmin2   =  0.0001   !  Tolerance of min wet depth on dried cells
+   rn_wdld     =  2.5      !  Land elevation below which WaD is allowed
+   nn_wdit     =   20      !  Max iterations for WaD limiter
+   rn_wd_sbcdep =  5.0     !  Depth at which to taper sbc fluxes
+   rn_wd_sbcfra =  0.999   !  Fraction of SBC fluxes at taper depth (Must be <1)
 /
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namzgr_domcfg
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namzgr_domcfg	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namzgr_domcfg	(revision 11422)
@@ -0,0 +1,9 @@
+!-----------------------------------------------------------------------
+&namzgr        !   vertical coordinate                                  (default: NO selection)
+!-----------------------------------------------------------------------
+   ln_zco      = .false.   !  z-coordinate - full    steps
+   ln_zps      = .false.   !  z-coordinate - partial steps
+   ln_sco      = .false.   !  s- or hybrid z-s-coordinate
+   ln_isfcav   = .false.   !  ice shelf cavity
+   ln_linssh   = .false.   !  linear free surface
+/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namzgr_sco_domcfg
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namzgr_sco_domcfg	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namzgr_sco_domcfg	(revision 11422)
@@ -0,0 +1,25 @@
+!-----------------------------------------------------------------------
+&namzgr_sco    !   s-coordinate or hybrid z-s-coordinate                (default F)
+!-----------------------------------------------------------------------
+   ln_s_sh94   = .false.    !  Song & Haidvogel 1994 hybrid S-sigma   (T)|
+   ln_s_sf12   = .false.   !  Siddorn & Furner 2012 hybrid S-z-sigma (T)| if both are false the NEMO tanh stretching is applied
+   ln_sigcrit  = .false.   !  use sigma coordinates below critical depth (T) or Z coordinates (F) for Siddorn & Furner stretch
+                           !  stretching coefficients for all functions
+   rn_sbot_min =   10.0    !  minimum depth of s-bottom surface (>0) (m)
+   rn_sbot_max = 7000.0    !  maximum depth of s-bottom surface (= ocean depth) (>0) (m)
+   rn_hc       =  150.0    !  critical depth for transition to stretched coordinates
+                        !!!!!!!  Envelop bathymetry
+   rn_rmax     =    0.3    !  maximum cut-off r-value allowed (0<r_max<1)
+                        !!!!!!!  SH94 stretching coefficients  (ln_s_sh94 = .true.)
+   rn_theta    =    6.0    !  surface control parameter (0<=theta<=20)
+   rn_bb       =    0.8    !  stretching with SH94 s-sigma
+                        !!!!!!!  SF12 stretching coefficient  (ln_s_sf12 = .true.)
+   rn_alpha    =    4.4    !  stretching with SF12 s-sigma
+   rn_efold    =    0.0    !  efold length scale for transition to stretched coord
+   rn_zs       =    1.0    !  depth of surface grid box
+                           !  bottom cell depth (Zb) is a linear function of water depth Zb = H*a + b
+   rn_zb_a     =    0.024  !  bathymetry scaling factor for calculating Zb
+   rn_zb_b     =   -0.2    !  offset for calculating Zb
+                        !!!!!!!! Other stretching (not SH94 or SF12) [also uses rn_theta above]
+   rn_thetb    =    1.0    !  bottom control parameter  (0<=thetb<= 1)
+/
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/requirements_latex.txt
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/requirements_latex.txt	(revision 10999)
+++ 	(revision )
@@ -1,53 +1,0 @@
-amsmath
-babel
-caption
-capt-of
-carlisle
-cmap
-courier
-draftwatermark
-ec
-enumitem
-epstopdf
-etoolbox
-everypage
-fancyhdr
-fancyvrb
-float
-fncychap
-framed
-fvextra
-geometry
-graphics
-graphics-cfg
-helvetic
-hyperref
-idxlayout
-ifplatform
-latex
-latex-bin
-latexconfig
-latex-fonts
-latexmk
-lineno
-lm
-marvosym
-minitoc
-minted
-natbib
-needspace
-oberdiek
-parskip
-psnfss
-subfiles
-tabulary
-times
-titlesec
-tools
-upquote
-url
-varwidth
-wrapfig
-xcolor
-xstring
-zapfchan
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/tools/check_pkg.py
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/tools/check_pkg.py	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/tools/check_pkg.py	(revision 11422)
@@ -0,0 +1,10 @@
+#!/usr/bin/env python
+
+import sys, importlib
+
+for argv in sys.argv[1:]:
+	try:
+		importlib.import_module(argv)
+	except ImportError:
+		print("Package %s is missing in Python" % argv)
+
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/tools/manuals_checking.sh
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/tools/manuals_checking.sh	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/tools/manuals_checking.sh	(revision 11422)
@@ -0,0 +1,80 @@
+#!/bin/sh
+
+#set -evx
+
+if [[ $* != '' ]]; then
+	 if [[ $1 = 'all' ]]; then models='NEMO SI3 TOP'; else models=$1; fi
+else
+	 models='NEMO'
+fi
+
+for model in $models; do
+	 [[ $model =~ ^(SI3|TOP)$ ]] && continue
+
+    files=$( find latex/$model -type f -name *.tex )
+
+	 echo '¤ Missing namelist groups in '$model' manual'
+
+	 for nlst in $( ls namelists ); do
+        [[ ! $( grep \\nlst{$nlst} $files ) ]] && printf '%s ' $nlst
+	 done
+
+    echo; echo
+	 echo '¤ Vanished index entries in '$model' manual (\{hf,jp,key,mdl,ngn,nlst,np,rou}{...})'
+
+    for file in $files; do
+
+        items=$( grep -Eho "(hf|jp|key|mdl|ngn|nlst|np|rou){[a-zA-Z0-9_\]*}" $file | sort -u )
+
+        if [[ $items == '' ]]; then
+            continue
+        else
+            printf ${file/latex\/*\/subfiles\/}': '
+        fi
+
+        for item in $items; do
+
+            arg=$( echo $item | sed 's/.*{\([^}]*\)}/\1/' | tr -d '\\' )
+
+		      if [[ ( $item =~ ^hf   && ! $( find ../src -type f -name   $arg.h90               ) ) || \
+                  ( $item =~ ^jp   && ! $( grep ":: *$arg"             ../src/OCE/par_oce.F90 ) ) || \
+                  ( $item =~ ^key  && ! $( grep -ri "#if .* $arg"      ../src                 ) ) || \
+		            ( $item =~ ^mdl  && ! $( find ../src -type f -name   $arg.[Ff]90            ) ) || \
+                  ( $item =~ ^ngn  && ! $( grep \&$arg                 namelists/*            ) ) || \
+                  ( $item =~ ^nlst && ! -f namelists/$arg                                       ) || \
+                  ( $item =~ ^np   && ! $( grep " $arg *="             namelists/*            ) ) || \
+                  ( $item =~ ^rou  && ! $( grep -ri "SUBROUTINE *$arg" ../src                 ) )      ]]; then
+                printf $item' '
+            fi
+
+        done
+
+        echo
+
+    done
+
+done
+
+echo
+echo '¤ Namelist parameters unfollowing naming conventions (^[cdlnr]n_* or uppercase somewhere)'
+
+for nlst in $( ls namelists ); do
+    np_list=$( sed '/^ *[!/&]/d; s|[!/&].*||' namelists/$nlst | tr -d ' ' | cut -d= -f1 )
+    array=()
+
+    for np in ${np_list}; do
+
+        if [[ ! ${np:0:3} =~ ^[cdlnr]n_$ || $( echo $np | grep [A-Z] ) ]]; then
+            array+=$np' '
+        fi
+
+    done
+
+	 if (( ${#array[@]} != 0 )); then
+        printf '%15s: ' $nlst
+        echo ${array[@]}
+    fi
+
+done
+
+exit 0
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/tools/nlsts_releases.sh
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/tools/nlsts_releases.sh	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/tools/nlsts_releases.sh	(revision 11422)
@@ -0,0 +1,26 @@
+#!/bin/sh
+
+## Estimate changes in namelists between two releases
+#####################################################
+
+## Prerequisites: f90nml to parse Fortran namelists (http://f90nml.readthedocs.org)
+## Launch under ./doc, edit the path to previous namelists accordingly
+
+for nlst in ../../releases/release-3.6/DOC/Namelists/*; do
+
+    if [ -f namelists/$( basename $nlst ) ]; then
+        printf "%s: " $( basename $nlst )
+        f90nml namelists/$( basename $nlst ) | awk '/=/ { print $0 }' | sort > nlst_new.txt
+        f90nml                       $nlst   | awk '/=/ { print $0 }' | sort > nlst_old.txt
+
+        if [[ $( diff -q nlst_*.txt ) ]]; then
+            diff -y --suppress-common-lines nlst_*.txt | wc -l
+        else
+            echo 0
+        fi
+
+    fi
+
+done | sort -k2rn
+
+\rm nlst_*.txt
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/tools/nlsts_update.sh
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/tools/nlsts_update.sh	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/tools/nlsts_update.sh	(revision 11422)
@@ -0,0 +1,247 @@
+#! /bin/sh
+#
+#       usage for NEMO doc to create an update of the Namelists directory :
+# 1- delete the existing directory (You can also choose to save it somewhere) 
+#    rm -rf Namelists
+# 2- create the updated Namelists directory from the SHARED/namelist_ref :
+#    ./namelist_split.sh -i ../NEMOGCM/CONFIG/SHARED/namelist_ref -o Namelists
+#
+# .. _namelist_split.sh:
+#
+# =================
+# namelist_split.sh
+# =================
+#
+# ----------------
+# split a namelist
+# ----------------
+#
+# SYNOPSIS
+# ========
+#
+# .. code-block:: bash
+#
+#    namelist_split.sh -i namelist -o dirout [-n]
+#
+# DESCRIPTION
+# ===========
+#
+# Split a namelist file (NEMO convention syntax) given in parameter
+# into files in a given output directory.
+#
+# .. option:: -i <input file (namelist)>
+# .. option:: -o <output directory>
+# .. option:: -n <numbered output files>
+#
+# Each file of the output directory is named after the *block* it contains.
+#
+# We assume here that the input file is written with this pattern of block:
+#
+# .. parsed-literal::
+#
+#    !---------------
+#    &nameblock
+#    !---------------
+#    var1 = val1
+#    ...
+#    varn = valn
+#    /
+#
+# If ``-n`` option is used, files in the directory output are named after
+# the number of the block it contains and the name of this block. This might
+# be useful to recombine blocks in the same order.
+#
+# EXAMPLES
+# ========
+#
+# To split the namelist NEMO ORCA2_LIM experiment 00 if you are in NEMO
+# working space :
+#
+# .. code-block:: bash
+#
+#    namelist_split.sh -i CONFIG/ORCA2_LIM/EXP00/namelist -o /tmp/EXP00_namelist_split/
+#
+# To split the namelist under data directory with numbered files:
+#
+# .. code-block:: bash
+#
+#    namelist_split.sh -i ./data/namelist -o /tmp/EXP00_namelist_split/ -n
+#
+# Check can be made by concatenation of files in output directory if ``-n``
+# option have been used and comparison with original file :
+#
+# .. code-block:: bash
+#
+#    cat /tmp/EXP00_namelist_split/b???_* > /tmp/EXP00_namelist_rebuild
+#    sdiff -w80 ./data/namelist /tmp/EXP00_namelist_rebuild
+#
+# Output contains lines which are before the first block, after the last
+# block and lines between blocks.
+#
+# EVOLUTIONS
+# ==========
+#
+# $Id$
+#
+# - fplod 2008-08-11T08:56:44Z aedon.locean-ipsl.upmc.fr (Darwin)
+#
+#   * commentaires dans ce fichier en reStructuredText
+#     cf. reStructuredText_ and Docutils_
+#
+# .. _reStructuredText: http://docutils.sourceforge.net/rst.html
+# .. _Docutils: http://docutils.sourceforge.net/
+#
+# - fplod 2008-07-22T12:41:04Z aedon.locean-ipsl.upmc.fr (Darwin)
+#
+#   * creation with test on
+#     http://forge.ipsl.jussieu.fr/nemo/browser/trunk/CONFIG/ORCA2_LIM/EXP00/namelist revision 1151
+#-
+#
+system=$(uname)
+case "${system}" in
+    AIX|IRIX64)
+        echo " www : no specific posix checking"
+    ;;
+    *)
+        #set -o posix
+    ;;
+esac
+unset system
+#
+command=$(basename ${0})
+log_date=$(date -u +"%Y%m%dT%H%M%SZ")
+#
+usage=" Usage : ${command} -i namelist -o dirout [-n]"
+#
+# default
+blocknum=0
+#
+minargcount=4
+if [ ${#} -lt ${minargcount} ]
+then
+    echo "eee : not enough arguments"
+    echo "${usage}"
+    exit 1
+fi
+#
+while [ ${#} -gt 0 ]
+do
+    case ${1} in
+        -i)
+            filein=${2}
+            shift
+        ;;
+        -o)
+            dirout=${2}
+            shift
+        ;;
+        -h)
+            echo "${usage}"
+            exit 0
+        ;;
+        -n)
+            blocknum=1
+        ;;
+        *)
+            # anything else
+            echo "eee : unknown option ${1}"
+            echo "eee : ${usage}"
+            exit 1
+        ;;
+    esac
+    # next flag
+    shift
+done
+unset usage
+#
+set -u
+#
+# check for filein
+if [ ! -r ${filein} ]
+then
+    echo "eee : ${filein} not accessible"
+    exit 1
+fi
+#
+# check for dirout
+# the idea is to prevent unwanted overwrite
+if [ -d ${dirout} ]
+then
+    echo "eee : ${dirout} already exist"
+    exit 1
+else
+    mkdir -p ${dirout}
+    if [ ${?} -ne 0 ]
+    then
+        echo "eee : cannot create ${dirout}"
+        exit 1
+    fi
+fi
+#
+# loop on each line of ${filein} ie the namelist to be split
+fileout=/dev/null
+begin=0
+if [ ${blocknum} -eq 1 ]
+then
+    iblock=0
+fi
+nbline=$(wc -l ${filein} | awk '{print $1}')
+il=1
+while [ ${il} -le ${nbline} ]
+do
+    line=$(sed -ne "${il},${il}p" ${filein})
+    # if current line start with "&", we can establish the name of output file
+    echo ${line} | grep -q "^&"
+    if [ ${?} -eq 0 ]
+    then
+        begin=1
+        # the form of this line is "&block   !"
+        block=${line#&}
+        block=${block%% *}
+        echo "iii : detection of the beginning of ${block}"
+        if [ ${blocknum} -eq 1 ]
+        then
+            iblock=$(( ${iblock} + 1))
+            fileout=${dirout}/b$(echo ${iblock} | awk '{printf "%3.3d", $1}')_${block}
+        else
+            fileout="${dirout}/${block}"
+        fi
+        # check for ${fileout}
+        if [ -f ${fileout} ]
+        then
+            echo "eee : ${fileout} already exists"
+            exit 1
+        fi
+        # write the previous line and the current line
+        echo "${memoline}" > ${fileout}
+        echo "${line}" >> ${fileout}
+    fi
+    # if current line contains "/" there will be no more lines to put in fileout
+    echo ${line} | grep -q "^/$"
+    if [ ${?} -eq 0 ]
+    then
+        echo "iii : detection of the end of ${block}"
+        echo "${line}" >> ${fileout}
+        fileout="/dev/null"
+    fi
+    # if current line is between "&" and "/", it should be written in fileout
+    # if current line is before the first &, it won't be written
+    if [ "${fileout}" != "/dev/null" ]
+    then
+        if [ ${begin} -eq 0 ]
+        then
+            echo "${line}" >> ${fileout}
+        fi
+    fi
+    # keep memory of this current line to use it if the next one is the
+    # beginning of a block
+    memoline=${line}
+    begin=0
+    # next line
+    il=$(( ${il} + 1 ))
+done
+#
+echo "iii : ${filein} is split in ${dirout}"
+#
+# end
+exit 0
Index: NEMO/branches/2019/fix_vvl_ticket1791/doc/tools/shr_func.sh
===================================================================
--- NEMO/branches/2019/fix_vvl_ticket1791/doc/tools/shr_func.sh	(revision 11422)
+++ NEMO/branches/2019/fix_vvl_ticket1791/doc/tools/shr_func.sh	(revision 11422)
@@ -0,0 +1,23 @@
+#!/bin/sh
+
+clean() {
+    ## Not sure if this step is needed, guess latexmk should be able to detect a change
+    printf "\t¤ Clean previous build"
+    find latex/$1/build -mindepth 1 -prune -not -name $1_manual.pyg -exec rm -rf {} \;
+
+    ## HTML exports
+    #printf '   - possible HTML export'
+    #find latex/$1 -type d -name 'html*'    -exec rm -r {} \;
+
+    echo
+}
+
+build() {
+    printf "\t¤ Generation of the PDF format\n"
+    latexmk -r  ./latex/global/latexmkrc  \
+	    -cd ./latex/$1/main/$1_manual \
+	    1> /dev/null
+    [ -f ./latex/$1/build/$1_manual.pdf ] && mv ./latex/$1/build/$1_manual.pdf .
+    echo
+}
+
