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

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
Changeset 11831 for NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex – NEMO

Ignore:
Timestamp:
2019-10-29T18:14:49+01:00 (4 years ago)
Author:
laurent
Message:

Update the branch to r11830 of the trunk!

Location:
NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc
Files:
21 deleted
47 edited
68 copied

Legend:

Unmodified
Added
Removed
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc

    • Property svn:ignore deleted
    • Property svn:externals set to
      ^/utils/badges badges
      ^/utils/logos logos
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex

    • Property svn:ignore deleted
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/DEPS

    r11004 r11831  
    2323helvetic 
    2424hyperref 
    25 idxlayout 
    2625ifplatform 
     26imakeidx 
     27koma-script 
    2728latex 
     29latexconfig 
    2830latex-bin 
    29 latexconfig 
    3031latex-fonts 
    3132latexmk 
     
    3940oberdiek 
    4041parskip 
     42preview 
    4143psnfss 
    4244subfiles 
     
    4446times 
    4547titlesec 
     48titling 
    4649tools 
    4750upquote 
     
    5053wrapfig 
    5154xcolor 
     55xkeyval 
    5256xstring 
    5357zapfchan 
     58 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/HTML_latex2html.sh

    r10146 r11831  
    11#!/bin/bash 
    22 
    3 ./inc/clean.sh 
    4 ./inc/build.sh 
     3#./inc/clean.sh 
     4#./inc/build.sh 
    55 
    6 cd tex_main 
    7 sed -i -e 's#\\documentclass#%\\documentclass#' -e '/{document}/ s/^/%/' \ 
    8    ../tex_sub/*.tex 
    9 sed -i    's#\\subfile{#\\include{#g' \ 
    10    NEMO_manual.tex 
    11 latex2html -local_icons -no_footnode -split 4 -link 2 -mkdir -dir ../html_LaTeX2HTML   \ 
    12             $*                                                                         \ 
    13    NEMO_manual 
    14 sed -i -e 's#%\\documentclass#\\documentclass#' -e '/{document}/ s/^%//' \ 
    15    ../tex_sub/*.tex 
    16 sed -i    's#\\include{#\\subfile{#g' \ 
    17    NEMO_manual.tex 
     6sed -i -e 's#utf8#latin1#'                                 \ 
     7       -e 's#\[outputdir=../build\]{minted}#\[\]{minted}#' \ 
     8       -e '/graphicspath/ s#{../#{../../#g'                \ 
     9          global/packages.tex 
     10 
     11cd ./NEMO/main 
     12sed -i -e 's#\\documentclass#%\\documentclass#' -e '/{document}/ s#^#%#'   ../subfiles/*.tex 
     13sed -i    's#\\subfile{#\\input{#'                                         chapters.tex appendices.tex 
     14 
     15#latex2html                                   -noimages -local_icons -no_footnode -split 4 -link 2 -dir ../html_LaTeX2HTML $* NEMO_manual 
     16latex2html -debug -noreuse -init_file ../../l2hconf.pm -local_icons                               -dir ../build/html               NEMO_manual 
     17 
     18sed -i -e 's#%\\documentclass#\\documentclass#' -e '/{document}/ s#^%##'   ../subfiles/*.tex 
     19sed -i    's#\\input{#\\subfile{#'                                         chapters.tex appendices.tex 
    1820cd - 
    1921 
     22sed -i -e 's#latin1#utf8#'                                 \ 
     23       -e 's#\[\]{minted}#\[outputdir=../build\]{minted}#' \ 
     24       -e '/graphicspath/ s#{../../#{../#g'                \ 
     25     global/packages.tex 
     26 
    2027exit 0 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO

    • Property svn:ignore deleted
    • Property svn:externals set to
      ^/utils/figures/NEMO figures
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/main

    • Property svn:ignore
      •  

        old new  
        1 *.aux 
        2 *.bbl 
        3 *.blg 
        4 *.dvi 
        5 *.fdb* 
        6 *.fls 
        7 *.idx 
        81*.ilg 
        92*.ind 
        10 *.log 
        11 *.maf 
        12 *.mtc* 
        13 *.out 
        14 *.pdf 
        15 *.toc 
        16 _minted-* 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles

    • Property svn:ignore
      •  

        old new  
        1 *.aux 
        2 *.bbl 
        3 *.blg 
        4 *.dvi 
        5 *.fdb* 
        6 *.fls 
        7 *.idx 
         1*.ind 
        82*.ilg 
        9 *.ind 
        10 *.log 
        11 *.maf 
        12 *.mtc* 
        13 *.out 
        14 *.pdf 
        15 *.toc 
        16 _minted-* 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_ASM.tex

    r10442 r11831  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter Assimilation increments (ASM) 
    6 % ================================================================ 
     4 
    75\chapter{Apply Assimilation Increments (ASM)} 
    86\label{chap:ASM} 
    97 
    10 Authors: D. Lea,  M. Martin, K. Mogensen, A. Weaver, ...   % do we keep 
     8%    {\em 4.0} & {\em D. J. Lea} & {\em \NEMO\ 4.0 updates}  \\ 
     9%    {\em 3.4} & {\em D. J. Lea, M. Martin, K. Mogensen, A. Weaver} & {\em Initial version}  \\ 
    1110 
    12 \minitoc 
     11\thispagestyle{plain} 
    1312 
    14 \newpage 
     13\chaptertoc 
     14 
     15\paragraph{Changes record} ~\\ 
     16 
     17{\footnotesize 
     18  \begin{tabularx}{\textwidth}{l||X|X} 
     19    Release & Author(s) & Modifications \\ 
     20    \hline 
     21    {\em   4.0} & {\em ...} & {\em ...} \\ 
     22    {\em   3.6} & {\em ...} & {\em ...} \\ 
     23    {\em   3.4} & {\em ...} & {\em ...} \\ 
     24    {\em <=3.4} & {\em ...} & {\em ...} 
     25  \end{tabularx} 
     26} 
     27 
     28\clearpage 
    1529 
    1630The ASM code adds the functionality to apply increments to the model variables: temperature, salinity, 
    17 sea surface height, velocity and sea ice concentration.  
     31sea surface height, velocity and sea ice concentration. 
    1832These are read into the model from a NetCDF file which may be produced by separate data assimilation code. 
    1933The code can also output model background fields which are used as an input to data assimilation code. 
    20 This is all controlled by the namelist \textit{\ngn{nam\_asminc} }. 
     34This is all controlled by the namelist \nam{_asminc}{\_asminc}. 
    2135There is a brief description of all the namelist options provided. 
    2236To build the ASM code \key{asminc} must be set. 
    2337 
    24 %=============================================================== 
    25  
     38%% ================================================================================================= 
    2639\section{Direct initialization} 
    2740\label{sec:ASM_DI} 
     
    2942Direct initialization (DI) refers to the instantaneous correction of the model background state using 
    3043the analysis increment. 
    31 DI is used when \np{ln\_asmdin} is set to true. 
     44DI is used when \np{ln_asmdin}{ln\_asmdin} is set to true. 
    3245 
     46%% ================================================================================================= 
    3347\section{Incremental analysis updates} 
    3448\label{sec:ASM_IAU} 
     
    3751it may be preferable to introduce the increment gradually into the ocean model in order to 
    3852minimize spurious adjustment processes. 
    39 This technique is referred to as Incremental Analysis Updates (IAU) \citep{Bloom_al_MWR96}. 
     53This technique is referred to as Incremental Analysis Updates (IAU) \citep{bloom.takacs.ea_MWR96}. 
    4054IAU is a common technique used with 3D assimilation methods such as 3D-Var or OI. 
    41 IAU is used when \np{ln\_asmiau} is set to true. 
     55IAU is used when \np{ln_asmiau}{ln\_asmiau} is set to true. 
    4256 
    43 With IAU, the model state trajectory ${\bf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$) 
     57With IAU, the model state trajectory ${\mathbf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$) 
    4458is corrected by adding the analysis increments for temperature, salinity, horizontal velocity and SSH as 
    4559additional tendency terms to the prognostic equations: 
    4660\begin{align*} 
    47   % \label{eq:wa_traj_iau} 
    48   {\bf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\bf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\bf x}^{a} 
     61  % \label{eq:ASM_wa_traj_iau} 
     62  {\mathbf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\mathbf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\mathbf x}^{a} 
    4963\end{align*} 
    50 where $F_{i}$ is a weighting function for applying the increments $\delta\tilde{\bf x}^{a}$ defined such that 
     64where $F_{i}$ is a weighting function for applying the increments $\delta\tilde{\mathbf x}^{a}$ defined such that 
    5165$\sum_{i=1}^{N} F_{i}=1$. 
    52 ${\bf x}^b$ denotes the model initial state and ${\bf x}^a$ is the model state after the increments are applied. 
     66${\mathbf x}^b$ denotes the model initial state and ${\mathbf x}^a$ is the model state after the increments are applied. 
    5367To control the adjustment time of the model to the increment, 
    5468the increment can be applied over an arbitrary sub-window, $t_{m} \leq t_{i} \leq t_{n}$, 
     
    5670Typically the increments are spread evenly over the full window. 
    5771In addition, two different weighting functions have been implemented. 
    58 The first function employs constant weights,  
     72The first function (namelist option \np{niaufn}{niaufn}=0) employs constant weights, 
    5973\begin{align} 
    60   \label{eq:F1_i} 
     74  \label{eq:ASM_F1_i} 
    6175  F^{(1)}_{i} 
    6276  =\left\{ 
    6377  \begin{array}{ll} 
    64     0     &    {\rm if} \; \; \; t_{i} < t_{m}                \\ 
    65     1/M &    {\rm if} \; \; \; t_{m} < t_{i} \leq t_{n} \\ 
    66     0     &    {\rm if} \; \; \; t_{i} > t_{n} 
     78    0     &    {\mathrm if} \; \; \; t_{i} < t_{m}                \\ 
     79    1/M &    {\mathrm if} \; \; \; t_{m} < t_{i} \leq t_{n} \\ 
     80    0     &    {\mathrm if} \; \; \; t_{i} > t_{n} 
    6781  \end{array} 
    68             \right.  
     82            \right. 
    6983\end{align} 
    7084where $M = m-n$. 
    71 The second function employs peaked hat-like weights in order to give maximum weight in the centre of the sub-window, 
     85The second function (namelist option \np{niaufn}{niaufn}=1) employs peaked hat-like weights in order to give maximum weight in the centre of the sub-window, 
    7286with the weighting reduced linearly to a small value at the window end-points: 
    7387\begin{align} 
    74   \label{eq:F2_i} 
     88  \label{eq:ASM_F2_i} 
    7589  F^{(2)}_{i} 
    7690  =\left\{ 
    7791  \begin{array}{ll} 
    78     0                           &    {\rm if} \; \; \; t_{i}       <     t_{m}                        \\ 
    79     \alpha \, i               &    {\rm if} \; \; \; t_{m}    \leq t_{i}    \leq   t_{M/2}   \\ 
    80     \alpha \, (M - i +1) &    {\rm if} \; \; \; t_{M/2}  <    t_{i}    \leq   t_{n}       \\ 
    81     0                            &   {\rm if} \; \; \; t_{i}        >    t_{n} 
     92    0                           &    {\mathrm if} \; \; \; t_{i}       <     t_{m}                        \\ 
     93    \alpha \, i               &    {\mathrm if} \; \; \; t_{m}    \leq t_{i}    \leq   t_{M/2}   \\ 
     94    \alpha \, (M - i +1) &    {\mathrm if} \; \; \; t_{M/2}  <    t_{i}    \leq   t_{n}       \\ 
     95    0                            &   {\mathrm if} \; \; \; t_{i}        >    t_{n} 
    8296  \end{array} 
    8397                                   \right. 
    8498\end{align} 
    85 where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even.  
    86 The weights described by \autoref{eq:F2_i} provide a smoother transition of the analysis trajectory from 
    87 one assimilation cycle to the next than that described by \autoref{eq:F1_i}. 
     99where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even. 
     100The weights described by \autoref{eq:ASM_F2_i} provide a smoother transition of the analysis trajectory from 
     101one assimilation cycle to the next than that described by \autoref{eq:ASM_F1_i}. 
    88102 
    89 %========================================================================== 
    90 % Divergence damping description %%% 
     103%% ================================================================================================= 
    91104\section{Divergence damping initialisation} 
    92105\label{sec:ASM_div_dmp} 
    93106 
    94 The velocity increments may be initialized by the iterative application of a divergence damping operator. 
    95 In iteration step $n$ new estimates of velocity increments $u^{n}_I$ and $v^{n}_I$ are updated by: 
     107It is quite challenging for data assimilation systems to provide non-divergent velocity increments. 
     108Applying 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}. 
     109 
     110In iteration step $n$ (starting at $n=1$) new estimates of velocity increments $u^{n}_I$ and $v^{n}_I$ are updated by: 
     111 
    96112\begin{equation} 
    97   \label{eq:asm_dmp} 
     113  \label{eq:ASM_dmp} 
    98114  \left\{ 
    99115    \begin{aligned} 
     
    105121  \right., 
    106122\end{equation} 
    107 where 
     123 
     124where the divergence is defined as 
     125 
    108126\[ 
    109   % \label{eq:asm_div} 
     127  % \label{eq:ASM_div} 
    110128  \chi^{n-1}_I = \frac{1}{e_{1t}\,e_{2t}\,e_{3t} } 
    111129  \left( {\delta_i \left[ {e_{2u}\,e_{3u}\,u^{n-1}_I} \right] 
    112130      +\delta_j \left[ {e_{1v}\,e_{3v}\,v^{n-1}_I} \right]} \right). 
    113131\] 
    114 By the application of \autoref{eq:asm_dmp} and \autoref{eq:asm_dmp} the divergence is filtered in each iteration, 
     132 
     133By the application of \autoref{eq:ASM_dmp} the divergence is filtered in each iteration, 
    115134and the vorticity is left unchanged. 
    116135In the presence of coastal boundaries with zero velocity increments perpendicular to the coast 
     
    118137This type of the initialisation reduces the vertical velocity magnitude and 
    119138alleviates the problem of the excessive unphysical vertical mixing in the first steps of the model integration 
    120 \citep{Talagrand_JAS72, Dobricic_al_OS07}. 
     139\citep{talagrand_JAS72, dobricic.pinardi.ea_OS07}. 
    121140Diffusion coefficients are defined as $A_D = \alpha e_{1t} e_{2t}$, where $\alpha = 0.2$. 
    122 The divergence damping is activated by assigning to \np{nn\_divdmp} in the \textit{nam\_asminc} namelist 
     141The divergence damping is activated by assigning to \np{nn_divdmp}{nn\_divdmp} in the \nam{_asminc}{\_asminc} namelist 
    123142a value greater than zero. 
    124 By choosing this value to be of the order of 100 the increments in 
    125 the vertical velocity will be significantly reduced. 
     143This 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. 
    126144 
    127  
    128 %========================================================================== 
    129  
     145%% ================================================================================================= 
    130146\section{Implementation details} 
    131147\label{sec:ASM_details} 
    132148 
    133 Here we show an example \ngn{namasm} namelist and the header of an example assimilation increments file on 
     149Here we show an example \nam{_asminc}{\_asminc} namelist and the header of an example assimilation increments file on 
    134150the ORCA2 grid. 
    135151 
    136 %------------------------------------------namasm----------------------------------------------------- 
    137 % 
    138 \nlst{nam_asminc} 
    139 %------------------------------------------------------------------------------------------------------------- 
     152\begin{listing} 
     153  \nlst{nam_asminc} 
     154  \caption{\forcode{&nam_asminc}} 
     155  \label{lst:nam_asminc} 
     156\end{listing} 
    140157 
    141158The header of an assimilation increments file produced using the NetCDF tool 
     
    177194\end{clines} 
    178195 
    179 \biblio 
    180  
    181 \pindex 
     196\subinc{\input{../../global/epilogue}} 
    182197 
    183198\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_DIA.tex

    r10509 r11831  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter I/O & Diagnostics 
    6 % ================================================================ 
     4 
    75\chapter{Output and Diagnostics (IOM, DIA, TRD, FLO)} 
    86\label{chap:DIA} 
    97 
    10 \minitoc 
    11  
    12 \newpage 
    13  
    14 % ================================================================ 
    15 %       Old Model Output  
    16 % ================================================================ 
    17 \section{Old model output (default)} 
     8%    {\em 4.0} & {\em Mirek Andrejczuk, Massimiliano Drudi} & {\em }  \\ 
     9%    {\em }      & {\em Dorotea Iovino, Nicolas Martin} & {\em }  \\ 
     10%    {\em 3.6} & {\em Gurvan Madec, Sebastien Masson } & {\em }  \\ 
     11%    {\em 3.4} & {\em Gurvan Madec, Rachid Benshila, Andrew Coward } & {\em }  \\ 
     12%    {\em }      & {\em Christian Ethe, Sebastien Masson } & {\em }  \\ 
     13 
     14\thispagestyle{plain} 
     15 
     16\chaptertoc 
     17 
     18\paragraph{Changes record} ~\\ 
     19 
     20{\footnotesize 
     21  \begin{tabularx}{\textwidth}{l||X|X} 
     22    Release & Author(s) & Modifications \\ 
     23    \hline 
     24    {\em   4.0} & {\em ...} & {\em ...} \\ 
     25    {\em   3.6} & {\em ...} & {\em ...} \\ 
     26    {\em   3.4} & {\em ...} & {\em ...} \\ 
     27    {\em <=3.4} & {\em ...} & {\em ...} 
     28  \end{tabularx} 
     29} 
     30 
     31\clearpage 
     32 
     33%% ================================================================================================= 
     34\section{Model output} 
    1835\label{sec:DIA_io_old} 
    1936 
     
    2542the same run performed in one step. 
    2643It should be noted that this requires that the restart file contains two consecutive time steps for 
    27 all the prognostic variables, and that it is saved in the same binary format as the one used by the computer that 
    28 is to read it (in particular, 32 bits binary IEEE format must not be used for this file). 
     44all the prognostic variables. 
    2945 
    3046The output listing and file(s) are predefined but should be checked and eventually adapted to the user's needs. 
    31 The output listing is stored in the $ocean.output$ file. 
    32 The information is printed from within the code on the logical unit $numout$. 
     47The output listing is stored in the \textit{ocean.output} file. 
     48The information is printed from within the code on the logical unit \texttt{numout}. 
    3349To locate these prints, use the UNIX command "\textit{grep -i numout}" in the source code directory. 
    3450 
     
    3955A complete description of the use of this I/O server is presented in the next section. 
    4056 
    41 By default, \key{iomput} is not defined, 
    42 NEMO produces NetCDF with the old IOIPSL library which has been kept for compatibility and its easy installation. 
    43 However, the IOIPSL library is quite inefficient on parallel machines and, since version 3.2, 
    44 many diagnostic options have been added presuming the use of \key{iomput}. 
    45 The usefulness of the default IOIPSL-based option is expected to reduce with each new release. 
    46 If \key{iomput} is not defined, output files and content are defined in the \mdl{diawri} module and 
    47 contain mean (or instantaneous if \key{diainstant} is defined) values over a regular period of 
    48 nn\_write time-steps (namelist parameter).  
    49  
    50 %\gmcomment{                    % start of gmcomment 
    51  
    52 % ================================================================ 
    53 % Diagnostics 
    54 % ================================================================ 
     57%\cmtgm{                    % start of gmcomment 
     58 
     59%% ================================================================================================= 
    5560\section{Standard model output (IOM)} 
    5661\label{sec:DIA_iom} 
    5762 
    58 Since version 3.2, iomput is the NEMO output interface of choice. 
     63Since version 3.2, iomput is the \NEMO\ output interface of choice. 
    5964It has been designed to be simple to use, flexible and efficient. 
    60 The two main purposes of iomput are:  
     65The two main purposes of iomput are: 
    6166 
    6267\begin{enumerate} 
    63 \item 
    64   The complete and flexible control of the output files through external XML files adapted by 
     68\item The complete and flexible control of the output files through external XML files adapted by 
    6569  the user from standard templates. 
    66 \item 
    67   To achieve high performance and scalable output through the optional distribution of 
     70\item To achieve high performance and scalable output through the optional distribution of 
    6871  all diagnostic output related tasks to dedicated processes. 
    6972\end{enumerate} 
    7073 
    71 The first functionality allows the user to specify, without code changes or recompilation,  
     74The first functionality allows the user to specify, without code changes or recompilation, 
    7275aspects of the diagnostic output stream, such as: 
    7376 
    7477\begin{itemize} 
    75 \item 
    76   The choice of output frequencies that can be different for each file (including real months and years). 
    77 \item 
    78   The choice of file contents; includes complete flexibility over which data are written in which files 
     78\item The choice of output frequencies that can be different for each file (including real months and years). 
     79\item The choice of file contents; includes complete flexibility over which data are written in which files 
    7980  (the same data can be written in different files). 
    80 \item 
    81   The possibility to split output files at a chosen frequency. 
    82 \item 
    83   The possibility to extract a vertical or an horizontal subdomain. 
    84 \item 
    85   The choice of the temporal operation to perform, \eg: average, accumulate, instantaneous, min, max and once. 
    86 \item 
    87   Control over metadata via a large XML "database" of possible output fields. 
     81\item The possibility to split output files at a chosen frequency. 
     82\item The possibility to extract a vertical or an horizontal subdomain. 
     83\item The choice of the temporal operation to perform, \eg: average, accumulate, instantaneous, min, max and once. 
     84\item Control over metadata via a large XML "database" of possible output fields. 
    8885\end{itemize} 
    8986 
     
    9188in a very easy way. 
    9289All details of iomput functionalities are listed in the following subsections. 
    93 Examples of the XML files that control the outputs can be found in: \path{NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef.xml}, 
    94 \path{NEMOGCM/CONFIG/SHARED/field_def.xml} and \path{NEMOGCM/CONFIG/SHARED/domain_def.xml}. \\ 
     90Examples of the XML files that control the outputs can be found in: 
     91\path{cfgs/ORCA2_ICE_PISCES/EXPREF/iodef.xml}, 
     92\path{cfgs/SHARED/field_def_nemo-oce.xml}, 
     93\path{cfgs/SHARED/field_def_nemo-pisces.xml}, 
     94\path{cfgs/SHARED/field_def_nemo-ice.xml} and \path{cfgs/SHARED/domain_def_nemo.xml}. \\ 
    9595 
    9696The second functionality targets output performance when running in parallel (\key{mpp\_mpi}). 
    97 Iomput provides the possibility to specify N dedicated I/O processes (in addition to the NEMO processes) 
     97Iomput provides the possibility to specify N dedicated I/O processes (in addition to the \NEMO\ processes) 
    9898to collect and write the outputs. 
    9999With an appropriate choice of N by the user, the bottleneck associated with the writing of 
    100100the output files can be greatly reduced. 
    101101 
    102 In version 3.6, the iom\_put interface depends on 
    103 an external code called \href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/branchs/xios-1.0}{XIOS-1.0}  
    104 (use of revision 618 or higher is required). 
     102In version 3.6, the \rou{iom\_put} interface depends on 
     103an external code called \href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/branchs/xios-2.5}{XIOS-2.5} 
     104%(use of revision 618 or higher is required). 
    105105This new IO server can take advantage of the parallel I/O functionality of NetCDF4 to 
    106106create a single output file and therefore to bypass the rebuilding phase. 
    107107Note that writing in parallel into the same NetCDF files requires that your NetCDF4 library is linked to 
    108 an HDF5 library that has been correctly compiled (\ie with the configure option $--$enable-parallel). 
     108an HDF5 library that has been correctly compiled (\ie\ with the configure option $--$enable-parallel). 
    109109Note that the files created by iomput through XIOS are incompatible with NetCDF3. 
    110110All post-processsing and visualization tools must therefore be compatible with NetCDF4 and not only NetCDF3. 
    111111 
    112112Even if not using the parallel I/O functionality of NetCDF4, using N dedicated I/O servers, 
    113 where N is typically much less than the number of NEMO processors, will reduce the number of output files created. 
    114 This can greatly reduce the post-processing burden usually associated with using large numbers of NEMO processors. 
     113where N is typically much less than the number of \NEMO\ processors, will reduce the number of output files created. 
     114This can greatly reduce the post-processing burden usually associated with using large numbers of \NEMO\ processors. 
    115115Note that for smaller configurations, the rebuilding phase can be avoided, 
    116116even without a parallel-enabled NetCDF4 library, simply by employing only one dedicated I/O server. 
    117117 
     118%% ================================================================================================= 
    118119\subsection{XIOS: Reading and writing restart file} 
    119120 
    120 XIOS may be used to read single file restart produced by NEMO. Currently only the variables written to  
    121 file \forcode{numror} can be handled by XIOS. To activate restart reading using XIOS, set \np{ln\_xios\_read}\forcode{ = .true. } 
    122 in \textit{namelist\_cfg}. This setting will be ignored when multiple restart files are present, and default NEMO  
    123 functionality will be used for reading. There is no need to change iodef.xml file to use XIOS to read  
    124 restart, all definitions are done within the NEMO code. For high resolution configuration, however,  
     121XIOS may be used to read single file restart produced by \NEMO. Currently only the variables written to 
     122file \forcode{numror} can be handled by XIOS. To activate restart reading using XIOS, set \np[=.true. ]{ln_xios_read}{ln\_xios\_read} 
     123in \textit{namelist\_cfg}. This setting will be ignored when multiple restart files are present, and default \NEMO 
     124functionality will be used for reading. There is no need to change iodef.xml file to use XIOS to read 
     125restart, all definitions are done within the \NEMO\ code. For high resolution configuration, however, 
    125126there may be a need to add the following line in iodef.xml (xios context): 
    126127 
     
    129130\end{xmllines} 
    130131 
    131 This variable sets timeout for reading.  
    132  
    133 If XIOS is to be used to read restart from file generated with an earlier NEMO version (3.6 for instance), 
     132This variable sets timeout for reading. 
     133 
     134If XIOS is to be used to read restart from file generated with an earlier \NEMO\ version (3.6 for instance), 
    134135dimension \forcode{z} defined in restart file must be renamed to \forcode{nav_lev}.\\ 
    135136 
    136 XIOS can also be used to write NEMO restart. A namelist parameter \np{nn\_wxios} is used to determine the  
    137 type of restart NEMO will write. If it is set to 0, default NEMO functionality will be used - each  
    138 processor writes its own restart file; if it is set to 1 XIOS will write restart into a single file;  
    139 for \np{nn\_wxios = 2} the restart will be written by XIOS into multiple files, one for each XIOS server.  
    140 Note, however, that \textbf{NEMO will not read restart generated by XIOS when \np{nn\_wxios = 2}}. The restart will  
    141 have to be rebuild before continuing the run. This option aims to reduce number of restart files generated by NEMO only,  
    142 and may be useful when there is a need to change number of processors used to run simulation.  
     137XIOS can also be used to write \NEMO\ restart. A namelist parameter \np{nn_wxios}{nn\_wxios} is used to determine the 
     138type of restart \NEMO\ will write. If it is set to 0, default \NEMO\ functionality will be used - each 
     139processor writes its own restart file; if it is set to 1 XIOS will write restart into a single file; 
     140for \np[=2]{nn_wxios}{nn\_wxios} the restart will be written by XIOS into multiple files, one for each XIOS server. 
     141Note, however, that \textbf{\NEMO\ will not read restart generated by XIOS when \np[=2]{nn_wxios}{nn\_wxios}}. The restart will 
     142have to be rebuild before continuing the run. This option aims to reduce number of restart files generated by \NEMO\ only, 
     143and may be useful when there is a need to change number of processors used to run simulation. 
    143144 
    144145If an additional variable must be written to a restart file, the following steps are needed: 
    145 \begin{description} 
    146    \item[step 1:] add variable name to a list of restart variables (in subroutine \rou{iom\_set\_rst\_vars,} \mdl{iom}) and  
    147 define correct grid for the variable (\forcode{grid_N_3D} - 3D variable, \forcode{grid_N} - 2D variable, \forcode{grid_vector} -  
     146\begin{enumerate} 
     147\item Add variable name to a list of restart variables (in subroutine \rou{iom\_set\_rst\_vars,} \mdl{iom}) and 
     148define correct grid for the variable (\forcode{grid_N_3D} - 3D variable, \forcode{grid_N} - 2D variable, \forcode{grid_vector} - 
    1481491D variable, \forcode{grid_scalar} - scalar), 
    149    \item[step 2:] add variable to the list of fields written by restart.  This can be done either in subroutine  
    150 \rou{iom\_set\_rstw\_core} (\mdl{iom}) or by calling  \rou{iom\_set\_rstw\_active} (\mdl{iom}) with the name of a variable  
    151 as an argument. This convention follows approach for writing restart using iom, where variables are  
     150\item Add variable to the list of fields written by restart.  This can be done either in subroutine 
     151\rou{iom\_set\_rstw\_core} (\mdl{iom}) or by calling  \rou{iom\_set\_rstw\_active} (\mdl{iom}) with the name of a variable 
     152as an argument. This convention follows approach for writing restart using iom, where variables are 
    152153written either by \rou{rst\_write} or by calling \rou{iom\_rstput} from individual routines. 
    153 \end{description} 
    154  
     154\end{enumerate} 
    155155 
    156156An older versions of XIOS do not support reading functionality. It's recommended to use at least XIOS2@1451. 
    157157 
    158  
     158%% ================================================================================================= 
    159159\subsection{XIOS: XML Inputs-Outputs Server} 
    160160 
     161%% ================================================================================================= 
    161162\subsubsection{Attached or detached mode?} 
    162163 
     
    168169\xmlline|<variable id="using_server" type="bool"></variable>| 
    169170 
    170 The {\tt using\_server} setting determines whether or not the server will be used in \textit{attached mode} 
    171 (as a library) [{\tt> false <}] or in \textit{detached mode} 
    172 (as an external executable on N additional, dedicated cpus) [{\tt > true <}]. 
    173 The \textit{attached mode} is simpler to use but much less efficient for massively parallel applications. 
     171The \texttt{using\_server} setting determines whether or not the server will be used in 
     172\textit{attached mode} 
     173(as a library) [\texttt{> false <}] or in \textit{detached mode} 
     174(as an external executable on N additional, dedicated cpus) [\texttt{ > true <}]. 
     175The \textit{attached mode} is simpler to use but much less efficient for 
     176massively parallel applications. 
    174177The type of each file can be either ''multiple\_file'' or ''one\_file''. 
    175178 
    176179In \textit{attached mode} and if the type of file is ''multiple\_file'', 
    177 then each NEMO process will also act as an IO server and produce its own set of output files. 
     180then each \NEMO\ process will also act as an IO server and produce its own set of output files. 
    178181Superficially, this emulates the standard behaviour in previous versions. 
    179182However, the subdomain written out by each process does not correspond to 
     
    187190write to its own set of output files. 
    188191If the ''one\_file'' option is chosen then all XIOS processes will collect their longitudinal strips and 
    189 write (in parallel) to a single output file.  
     192write (in parallel) to a single output file. 
    190193Note running in detached mode requires launching a Multiple Process Multiple Data (MPMD) parallel job. 
    191194The following subsection provides a typical example but the syntax will vary in different MPP environments. 
    192195 
     196%% ================================================================================================= 
    193197\subsubsection{Number of cpu used by XIOS in detached mode} 
    194198 
    195199The number of cores used by the XIOS is specified when launching the model. 
    196 The number of cores dedicated to XIOS should be from \texttildelow1/10 to \texttildelow1/50 of the number of  
    197 cores dedicated to NEMO. 
     200The number of cores dedicated to XIOS should be from \texttildelow1/10 to \texttildelow1/50 of the number of 
     201cores dedicated to \NEMO. 
    198202Some manufacturers suggest using O($\sqrt{N}$) dedicated IO processors for N processors but 
    199 this is a general recommendation and not specific to NEMO. 
     203this is a general recommendation and not specific to \NEMO. 
    200204It is difficult to provide precise recommendations because the optimal choice will depend on 
    201 the particular hardware properties of the target system  
     205the particular hardware properties of the target system 
    202206(parallel filesystem performance, available memory, memory bandwidth etc.) 
    203207and the volume and frequency of data to be created. 
     
    205209\cmd|mpirun -np 62 ./nemo.exe : -np 2 ./xios_server.exe| 
    206210 
     211%% ================================================================================================= 
    207212\subsubsection{Control of XIOS: the context in iodef.xml} 
    208213 
    209 As well as the {\tt using\_server} flag, other controls on the use of XIOS are set in the XIOS context in iodef.xml. 
     214As well as the \texttt{using\_server} flag, other controls on the use of XIOS are set in 
     215the XIOS context in \textit{iodef.xml}. 
    210216See the XML basics section below for more details on XML syntax and rules. 
    211217 
    212218\begin{table} 
    213   \scriptsize 
    214219  \begin{tabularx}{\textwidth}{|lXl|} 
    215220    \hline 
     
    220225    \hline 
    221226    buffer\_size                                                            & 
    222     buffer size used by XIOS to send data from NEMO to XIOS. 
     227    buffer size used by XIOS to send data from \NEMO\ to XIOS. 
    223228    Larger is more efficient. 
    224229    Note that needed/used buffer sizes are summarized at the end of the job & 
     
    226231    \hline 
    227232    buffer\_server\_factor\_size                                            & 
    228     ratio between NEMO and XIOS buffer size. 
     233    ratio between \NEMO\ and XIOS buffer size. 
    229234    Should be 2.                                                            & 
    230235    2        \\ 
     
    243248    \hline 
    244249    oasis\_codes\_id                                                        & 
    245     when using oasis, define the identifier of NEMO in the namcouple. 
     250    when using oasis, define the identifier of \NEMO\ in the namcouple. 
    246251    Note that the identifier of XIOS is xios.x                              & 
    247252    oceanx   \\ 
     
    250255\end{table} 
    251256 
     257%% ================================================================================================= 
    252258\subsection{Practical issues} 
    253259 
     260%% ================================================================================================= 
    254261\subsubsection{Installation} 
    255262 
    256 As mentioned, XIOS is supported separately and must be downloaded and compiled before it can be used with NEMO. 
     263As mentioned, XIOS is supported separately and must be downloaded and compiled before it can be used with \NEMO. 
    257264See the installation guide on the \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS} wiki for help and guidance. 
    258 NEMO will need to link to the compiled XIOS library. 
    259 The \href{https://forge.ipsl.jussieu.fr/nemo/wiki/Users/ModelInterfacing/InputsOutputs#Inputs-OutputsusingXIOS} 
    260 {XIOS with NEMO} guide provides an example illustration of how this can be achieved. 
    261  
     265\NEMO\ will need to link to the compiled XIOS library. 
     266The \href{https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/guide/html/install.html#extract-and-install-xios} 
     267{Extract and install XIOS} guide provides an example illustration of how this can be achieved. 
     268 
     269%% ================================================================================================= 
    262270\subsubsection{Add your own outputs} 
    263271 
     
    268276 
    269277\begin{enumerate} 
    270 \item[1.] 
    271   in NEMO code, add a \forcode{CALL iom\_put( 'identifier', array )} where you want to output a 2D or 3D array. 
    272 \item[2.] 
    273   If necessary, add \forcode{USE iom ! I/O manager library} to the list of used modules in 
     278\item in \NEMO\ code, add a \forcode{CALL iom_put( 'identifier', array )} where you want to output a 2D or 3D array. 
     279\item If necessary, add \forcode{USE iom ! I/O manager library} to the list of used modules in 
    274280  the upper part of your module. 
    275 \item[3.] 
    276   in the field\_def.xml file, add the definition of your variable using the same identifier you used in the f90 code 
     281\item in the field\_def.xml file, add the definition of your variable using the same identifier you used in the f90 code 
    277282  (see subsequent sections for a details of the XML syntax and rules). 
    278283  For example: 
    279  
    280284\begin{xmllines} 
    281285<field_definition> 
    282286   <field_group id="grid_T" grid_ref="grid_T_3D"> <!-- T grid --> 
    283287   ... 
    284       <field id="identifier" long_name="blabla" ... />    
     288      <field id="identifier" long_name="blabla" ... /> 
    285289      ... 
    286 </field_definition>  
    287 \end{xmllines} 
    288  
     290</field_definition> 
     291\end{xmllines} 
    289292Note your definition must be added to the field\_group whose reference grid is consistent with the size of 
    290293the array passed to iomput. 
     
    293296(iom\_set\_domain\_attr and iom\_set\_axis\_attr in \mdl{iom}) or defined in the domain\_def.xml file. 
    294297\eg: 
    295  
    296298\begin{xmllines} 
    297299<grid id="grid_T_3D" domain_ref="grid_T" axis_ref="deptht"/> 
    298300\end{xmllines} 
    299  
    300 Note, if your array is computed within the surface module each \np{nn\_fsbc} time\_step, 
     301Note, if your array is computed within the surface module each \np{nn_fsbc}{nn\_fsbc} time\_step, 
    301302add the field definition within the field\_group defined with the id "SBC": 
    302303\xmlcode{<field_group id="SBC" ...>} which has been defined with the correct frequency of operations 
    303304(iom\_set\_field\_attr in \mdl{iom}) 
    304 \item[4.] 
    305   add your field in one of the output files defined in iodef.xml 
     305\item add your field in one of the output files defined in iodef.xml 
    306306  (again see subsequent sections for syntax and rules) 
    307  
    308 \begin{xmllines} 
    309 <file id="file1" .../>    
     307\begin{xmllines} 
     308<file id="file1" .../> 
    310309... 
    311    <field field_ref="identifier" />    
     310   <field field_ref="identifier" /> 
    312311   ... 
    313 </file>    
    314 \end{xmllines} 
    315  
     312</file> 
     313\end{xmllines} 
    316314\end{enumerate} 
    317315 
     316%% ================================================================================================= 
    318317\subsection{XML fundamentals} 
    319318 
     319%% ================================================================================================= 
    320320\subsubsection{ XML basic rules} 
    321321 
     
    327327See \href{http://www.xmlnews.org/docs/xml-basics.html}{here} for more details. 
    328328 
    329 \subsubsection{Structure of the XML file used in NEMO} 
     329%% ================================================================================================= 
     330\subsubsection{Structure of the XML file used in \NEMO} 
    330331 
    331332The XML file used in XIOS is structured by 7 families of tags: 
     
    334335 
    335336\begin{table} 
    336   \scriptsize 
    337337  \begin{tabular*}{\textwidth}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} 
    338338    \hline 
     
    366366 
    367367\begin{table} 
    368   \scriptsize 
    369368  \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} 
    370369    \hline 
     
    376375                                                                                                     \xmlcode{<context id="xios" ... >}   \\ 
    377376    \hline 
    378     context nemo    &   context containing IO information for NEMO (mother grid when using AGRIF)  &  
     377    context nemo    &   context containing IO information for \NEMO\ (mother grid when using AGRIF)  & 
    379378                                                                                                     \xmlcode{<context id="nemo" ... >}   \\ 
    380379    \hline 
    381     context 1\_nemo &   context containing IO information for NEMO child grid 1 (when using AGRIF) &  
     380    context 1\_nemo &   context containing IO information for \NEMO\ child grid 1 (when using AGRIF) & 
    382381                                                                                                     \xmlcode{<context id="1_nemo" ... >} \\ 
    383382    \hline 
    384     context n\_nemo &   context containing IO information for NEMO child grid n (when using AGRIF) &  
     383    context n\_nemo &   context containing IO information for \NEMO\ child grid n (when using AGRIF) & 
    385384                                                                                                     \xmlcode{<context id="n_nemo" ... >} \\ 
    386385    \hline 
     
    391390 
    392391\begin{table} 
    393   \scriptsize 
    394392  \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} 
    395393    \hline 
     
    407405\end{table} 
    408406 
    409 \noindent Each context tag related to NEMO (mother or child grids) is divided into 5 parts  
     407\noindent Each context tag related to \NEMO\ (mother or child grids) is divided into 5 parts 
    410408(that can be defined in any order): 
    411409 
    412410\begin{table} 
    413   \scriptsize 
    414411  \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} 
    415412    \hline 
     
    436433\end{table} 
    437434 
     435%% ================================================================================================= 
    438436\subsubsection{Nesting XML files} 
    439437 
     
    441439The inclusion of XML files into the main XML file can be done through the attribute src: 
    442440\xmlline|<context src="./nemo_def.xml" />| 
    443   
    444 \noindent In NEMO, by default, the field and domain definition is done in 2 separate files: 
    445 \path{NEMOGCM/CONFIG/SHARED/field_def.xml} and \path{NEMOGCM/CONFIG/SHARED/domain_def.xml} that 
     441 
     442\noindent In \NEMO, by default, the field definition is done in 3 separate files ( 
     443\path{cfgs/SHARED/field_def_nemo-oce.xml}, 
     444\path{cfgs/SHARED/field_def_nemo-pisces.xml} and 
     445\path{cfgs/SHARED/field_def_nemo-ice.xml} ) and the  domain definition is done in another file ( \path{cfgs/SHARED/domain_def_nemo.xml} ) 
     446that 
    446447are included in the main iodef.xml file through the following commands: 
    447448\begin{xmllines} 
    448 <field_definition src="./field_def.xml" /> 
    449 <domain_definition src="./domain_def.xml" /> 
    450 \end{xmllines} 
    451  
     449<context id="nemo" src="./context_nemo.xml"/> 
     450\end{xmllines} 
     451 
     452%% ================================================================================================= 
    452453\subsubsection{Use of inheritance} 
    453454 
     
    462463\begin{xmllines} 
    463464<field_definition operation="average" > 
    464    <field id="sst"                    />   <!-- averaged      sst -->  
    465    <field id="sss" operation="instant"/>   <!-- instantaneous sss -->  
    466 </field_definition>  
     465   <field id="sst"                    />   <!-- averaged      sst --> 
     466   <field id="sss" operation="instant"/>   <!-- instantaneous sss --> 
     467</field_definition> 
    467468\end{xmllines} 
    468469 
     
    481482</field_definition> 
    482483<file_definition> 
    483    <file id="myfile" output_freq="1d" />    
     484   <file id="myfile" output_freq="1d" /> 
    484485      <field field_ref="sst"                            />  <!-- default def --> 
    485486      <field field_ref="sss" long_name="my description" />  <!-- overwrite   --> 
    486487   </file> 
    487 </file_definition>  
     488</file_definition> 
    488489\end{xmllines} 
    489490 
    490491Inherit (and overwrite, if needed) the attributes of a tag you are refering to. 
    491492 
     493%% ================================================================================================= 
    492494\subsubsection{Use of groups} 
    493495 
     
    508510 
    509511Secondly, the group can be used to replace a list of elements. 
    510 Several examples of groups of fields are proposed at the end of the file \path{CONFIG/SHARED/field_def.xml}. 
     512Several examples of groups of fields are proposed at the end of the XML field files ( 
     513\path{cfgs/SHARED/field_def_nemo-oce.xml}, 
     514\path{cfgs/SHARED/field_def_nemo-pisces.xml} and 
     515\path{cfgs/SHARED/field_def_nemo-ice.xml} ) . 
    511516For example, a short list of the usual variables related to the U grid: 
    512517 
     
    514519<field_group id="groupU" > 
    515520   <field field_ref="uoce"  /> 
    516    <field field_ref="suoce" /> 
     521   <field field_ref="ssu" /> 
    517522   <field field_ref="utau"  /> 
    518523</field_group> 
     
    525530   <field_group group_ref="groupU" /> 
    526531   <field field_ref="uocetr_eff"   />  <!-- add another field --> 
    527 </file>    
    528 \end{xmllines} 
    529  
     532</file> 
     533\end{xmllines} 
     534 
     535%% ================================================================================================= 
    530536\subsection{Detailed functionalities} 
    531537 
     
    533539the new functionalities offered by the XML interface of XIOS. 
    534540 
     541%% ================================================================================================= 
    535542\subsubsection{Define horizontal subdomains} 
    536543 
    537544Horizontal subdomains are defined through the attributs zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj of 
    538545the tag family domain. 
    539 It must therefore be done in the domain part of the XML file.  
    540 For example, in \path{CONFIG/SHARED/domain_def.xml}, we provide the following example of a definition of  
     546It must therefore be done in the domain part of the XML file. 
     547For example, in \path{cfgs/SHARED/domain_def.xml}, we provide the following example of a definition of 
    541548a 5 by 5 box with the bottom left corner at point (10,10). 
    542549 
    543550\begin{xmllines} 
    544 <domain_group id="grid_T"> 
    545    <domain id="myzoom" zoom_ibegin="10" zoom_jbegin="10" zoom_ni="5" zoom_nj="5" /> 
     551<domain id="myzoomT" domain_ref="grid_T"> 
     552   <zoom_domain ibegin="10" jbegin="10" ni="5" nj="5" /> 
    546553\end{xmllines} 
    547554 
     
    551558\begin{xmllines} 
    552559<file id="myfile_vzoom" output_freq="1d" > 
    553    <field field_ref="toce" domain_ref="myzoom"/> 
     560   <field field_ref="toce" domain_ref="myzoomT"/> 
    554561</file> 
    555562\end{xmllines} 
    556563 
    557 Moorings are seen as an extrem case corresponding to a 1 by 1 subdomain.  
     564Moorings are seen as an extrem case corresponding to a 1 by 1 subdomain. 
    558565The Equatorial section, the TAO, RAMA and PIRATA moorings are already registered in the code and 
    559566can therefore be outputted without taking care of their (i,j) position in the grid. 
     
    568575\end{xmllines} 
    569576 
    570 Note that if the domain decomposition used in XIOS cuts the subdomain in several parts and if  
    571 you use the ''multiple\_file'' type for your output files,  
    572 you will endup with several files you will need to rebuild using unprovided tools (like ncpdq and ncrcat,  
     577Note that if the domain decomposition used in XIOS cuts the subdomain in several parts and if 
     578you use the ''multiple\_file'' type for your output files, 
     579you will endup with several files you will need to rebuild using unprovided tools (like ncpdq and ncrcat, 
    573580\href{http://nco.sourceforge.net/nco.html#Concatenation}{see nco manual}). 
    574581We are therefore advising to use the ''one\_file'' type in this case. 
    575582 
     583%% ================================================================================================= 
    576584\subsubsection{Define vertical zooms} 
    577585 
    578 Vertical zooms are defined through the attributs zoom\_begin and zoom\_end of the tag family axis. 
     586Vertical zooms are defined through the attributs zoom\_begin and zoom\_n of the tag family axis. 
    579587It must therefore be done in the axis part of the XML file. 
    580 For example, in \path{NEMOGCM/CONFIG/ORCA2_LIM/iodef_demo.xml}, we provide the following example: 
    581  
    582 \begin{xmllines} 
    583 <axis_group id="deptht" long_name="Vertical T levels" unit="m" positive="down" > 
    584    <axis id="deptht" /> 
    585    <axis id="deptht_myzoom" zoom_begin="1" zoom_end="10" /> 
     588For example, in \path{cfgs/ORCA2_ICE_PISCES/EXPREF/iodef_demo.xml}, we provide the following example: 
     589 
     590\begin{xmllines} 
     591<axis_definition> 
     592   <axis id="deptht" long_name="Vertical T levels" unit="m" positive="down" /> 
     593   <axis id="deptht_zoom" azix_ref="deptht" > 
     594      <zoom_axis zoom_begin="1" zoom_n="10" /> 
     595   </axis> 
    586596\end{xmllines} 
    587597 
     
    595605\end{xmllines} 
    596606 
     607%% ================================================================================================= 
    597608\subsubsection{Control of the output file names} 
    598609 
     
    601612 
    602613\begin{xmllines} 
    603 <file_group id="1d" output_freq="1d" name="myfile_1d" >  
     614<file_group id="1d" output_freq="1d" name="myfile_1d" > 
    604615   <file id="myfileA" name_suffix="_AAA" > <!-- will create file "myfile_1d_AAA"  --> 
    605616      ... 
     
    620631 
    621632\begin{table} 
    622   \scriptsize 
    623633  \begin{tabularx}{\textwidth}{|lX|} 
    624634    \hline 
     
    656666\end{table} 
    657667 
    658 \noindent For example,  
     668\noindent For example, 
    659669\xmlline|<file id="myfile_hzoom" name="myfile_@expname@_@startdate@_freq@freq@" output_freq="1d" >| 
    660670 
     
    668678\noindent will give the following file name radical: \ifile{myfile\_ORCA2\_19891231\_freq1d} 
    669679 
    670 \subsubsection{Other controls of the XML attributes from NEMO} 
    671  
    672 The values of some attributes are defined by subroutine calls within NEMO  
     680%% ================================================================================================= 
     681\subsubsection{Other controls of the XML attributes from \NEMO} 
     682 
     683The values of some attributes are defined by subroutine calls within \NEMO 
    673684(calls to iom\_set\_domain\_attr, iom\_set\_axis\_attr and iom\_set\_field\_attr in \mdl{iom}). 
    674685Any definition given in the XML file will be overwritten. 
     
    681692 
    682693\begin{table} 
    683   \scriptsize 
    684   \begin{tabularx}{\textwidth}{|X|c|c|c|} 
     694  \begin{tabular}{|l|c|c|} 
    685695    \hline 
    686696    tag ids affected by automatic definition of some of their attributes & 
    687697    name attribute                                                       & 
    688     attribute value                      \\ 
     698    attribute value                                                      \\ 
    689699    \hline 
    690700    \hline 
    691701    field\_definition                                                    & 
    692702    freq\_op                                                             & 
    693     \np{rn\_rdt}                         \\ 
     703    \np{rn_rdt}{rn\_rdt}                                                         \\ 
    694704    \hline 
    695705    SBC                                                                  & 
    696706    freq\_op                                                             & 
    697     \np{rn\_rdt} $\times$ \np{nn\_fsbc}  \\ 
     707    \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_fsbc}{nn\_fsbc}                                  \\ 
    698708    \hline 
    699709    ptrc\_T                                                              & 
    700710    freq\_op                                                             & 
    701     \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ 
     711    \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_dttrc}{nn\_dttrc}                                \\ 
    702712    \hline 
    703713    diad\_T                                                              & 
    704714    freq\_op                                                             & 
    705     \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ 
     715    \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_dttrc}{nn\_dttrc}                                \\ 
    706716    \hline 
    707717    EqT, EqU, EqW                                                        & 
    708718    jbegin, ni,                                                          & 
    709     according to the grid                \\ 
    710     & 
     719    according to the grid                                                \\ 
     720                                                                         & 
    711721    name\_suffix                                                         & 
    712     \\ 
     722                                                                         \\ 
    713723    \hline 
    714724    TAO, RAMA and PIRATA moorings                                        & 
    715725    zoom\_ibegin, zoom\_jbegin,                                          & 
    716     according to the grid                \\ 
    717     & 
     726    according to the grid                                                \\ 
     727                                                                         & 
    718728    name\_suffix                                                         & 
    719     \\ 
    720     \hline 
    721   \end{tabularx} 
     729                                                                         \\ 
     730    \hline 
     731  \end{tabular} 
    722732\end{table} 
    723733 
     734%% ================================================================================================= 
    724735\subsubsection{Advanced use of XIOS functionalities} 
    725736 
     737%% ================================================================================================= 
    726738\subsection{XML reference tables} 
    727 \label{subsec:IOM_xmlref} 
     739\label{subsec:DIA_IOM_xmlref} 
    728740 
    729741\begin{enumerate} 
    730 \item 
    731   Simple computation: directly define the computation when refering to the variable in the file definition. 
     742\item Simple computation: directly define the computation when refering to the variable in the file definition. 
    732743 
    733744\begin{xmllines} 
     
    737748\end{xmllines} 
    738749 
    739 \item 
    740   Simple computation: define a new variable and use it in the file definition. 
     750\item Simple computation: define a new variable and use it in the file definition. 
    741751 
    742752in field\_definition: 
     
    755765sst2 won't be evaluated. 
    756766 
    757 \item 
    758   Change of variable precision: 
     767\item Change of variable precision: 
    759768 
    760769\begin{xmllines} 
     
    765774\end{xmllines} 
    766775 
    767 Note that, then the code is crashing, writting real4 variables forces a numerical convection from  
     776Note that, then the code is crashing, writting real4 variables forces a numerical conversion from 
    768777real8 to real4 which will create an internal error in NetCDF and will avoid the creation of the output files. 
    769778Forcing double precision outputs with prec="8" (for example in the field\_definition) will avoid this problem. 
    770779 
    771 \item 
    772   add user defined attributes: 
    773  
    774 \begin{xmllines} 
    775 <file_group id="1d" output_freq="1d" output_level="10" enabled=".true."> <!-- 1d files -->  
     780\item add user defined attributes: 
     781 
     782\begin{xmllines} 
     783<file_group id="1d" output_freq="1d" output_level="10" enabled=".true."> <!-- 1d files --> 
    776784   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > 
    777785      <field field_ref="sst" name="tos" > 
     
    782790      <variable id="my_global_attribute" type="string" > blabla_global </variable> 
    783791   </file> 
    784 </file_group>  
    785 \end{xmllines} 
    786  
    787 \item 
    788   use of the ``@'' function: example 1, weighted temporal average 
     792</file_group> 
     793\end{xmllines} 
     794 
     795\item use of the ``@'' function: example 1, weighted temporal average 
    789796 
    790797 - define a new variable in field\_definition 
     
    797804 
    798805\begin{xmllines} 
    799 <file_group id="5d" output_freq="5d"  output_level="10" enabled=".true." >  <!-- 5d files -->   
     806<file_group id="5d" output_freq="5d"  output_level="10" enabled=".true." >  <!-- 5d files --> 
    800807   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > 
    801808      <field field_ref="toce" operation="instant" freq_op="5d" > @toce_e3t / @e3t </field> 
    802809   </file> 
    803 </file_group>  
     810</file_group> 
    804811\end{xmllines} 
    805812 
     
    814821Note that in this case, freq\_op must be equal to the file output\_freq. 
    815822 
    816 \item 
    817   use of the ``@'' function: example 2, monthly SSH standard deviation 
     823\item use of the ``@'' function: example 2, monthly SSH standard deviation 
    818824 
    819825 - define a new variable in field\_definition 
     
    826832 
    827833\begin{xmllines} 
    828 <file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files -->   
     834<file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files --> 
    829835   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > 
    830       <field field_ref="ssh" name="sshstd" long_name="sea_surface_temperature_standard_deviation"  
     836      <field field_ref="ssh" name="sshstd" long_name="sea_surface_temperature_standard_deviation" 
    831837      operation="instant" freq_op="1m" > 
    832838         sqrt( @ssh2 - @ssh * @ssh ) 
    833839      </field> 
    834840   </file> 
    835 </file_group>  
     841</file_group> 
    836842\end{xmllines} 
    837843 
     
    840846here we use the default, average. 
    841847So, in the above case, @ssh2 will do the monthly mean of ssh*ssh. 
    842 Operation="instant" refers to the temporal operation to be performed on the field ''sqrt( @ssh2 - @ssh * @ssh )'':  
     848Operation="instant" refers to the temporal operation to be performed on the field ''sqrt( @ssh2 - @ssh * @ssh )'': 
    843849here the temporal average is alreday done by the ``@'' function so we just use instant. 
    844850field\_ref="ssh" means that attributes not explicitely defined, are inherited from ssh field. 
    845851Note that in this case, freq\_op must be equal to the file output\_freq. 
    846852 
    847 \item 
    848   use of the ``@'' function: example 3, monthly average of SST diurnal cycle 
     853\item use of the ``@'' function: example 3, monthly average of SST diurnal cycle 
    849854 
    850855 - define 2 new variables in field\_definition 
     
    858863 
    859864\begin{xmllines} 
    860 <file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files -->   
     865<file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files --> 
    861866   <file id="file1" name_suffix="_grid_T" description="ocean T grid variables" > 
    862867      <field field_ref="sst" name="sstdcy" long_name="amplitude of sst diurnal cycle" operation="average" freq_op="1d" > 
     
    864869      </field> 
    865870   </file> 
    866 </file_group>  
     871</file_group> 
    867872\end{xmllines} 
    868873 
     
    877882field\_ref="sst" means that attributes not explicitely defined, are inherited from sst field. 
    878883 
     884%% ================================================================================================= 
    879885\subsubsection{Tag list per family} 
    880886 
    881887\begin{table} 
    882   \scriptsize 
    883888  \begin{tabularx}{\textwidth}{|l|X|X|l|X|} 
    884889    \hline 
     
    903908    \hline 
    904909  \end{tabularx} 
    905   \caption{Context tags} 
     910  \caption{XIOS: context tags} 
    906911\end{table} 
    907912 
    908913\begin{table} 
    909   \scriptsize 
    910914  \begin{tabularx}{\textwidth}{|l|X|X|X|l|} 
    911915    \hline 
     
    938942    \hline 
    939943  \end{tabularx} 
    940   \caption{Field tags ("\tt{field\_*}")} 
     944  \caption{XIOS: field tags ("\texttt{field\_*}")} 
    941945\end{table} 
    942946 
    943947\begin{table} 
    944   \scriptsize 
    945948  \begin{tabularx}{\textwidth}{|l|X|X|X|l|} 
    946949    \hline 
     
    974977    \hline 
    975978  \end{tabularx} 
    976   \caption{File tags ("\tt{file\_*}")} 
     979  \caption{XIOS: file tags ("\texttt{file\_*}")} 
    977980\end{table} 
    978981 
    979982\begin{table} 
    980   \scriptsize 
    981983  \begin{tabularx}{\textwidth}{|l|X|X|X|X|} 
    982984    \hline 
     
    10071009    \hline 
    10081010  \end{tabularx} 
    1009   \caption{Axis tags ("\tt{axis\_*}")} 
     1011  \caption{XIOS: axis tags ("\texttt{axis\_*}")} 
    10101012\end{table} 
    10111013 
    10121014\begin{table} 
    1013   \scriptsize 
    10141015  \begin{tabularx}{\textwidth}{|l|X|X|X|X|} 
    10151016    \hline 
     
    10401041    \hline 
    10411042  \end{tabularx} 
    1042   \caption{Domain tags ("\tt{domain\_*)}"} 
     1043  \caption{XIOS: domain tags ("\texttt{domain\_*)}"} 
    10431044\end{table} 
    10441045 
    10451046\begin{table} 
    1046   \scriptsize 
    10471047  \begin{tabularx}{\textwidth}{|l|X|X|X|X|} 
    10481048    \hline 
     
    10731073    \hline 
    10741074  \end{tabularx} 
    1075   \caption{Grid tags ("\tt{grid\_*}")} 
     1075  \caption{XIOS: grid tags ("\texttt{grid\_*}")} 
    10761076\end{table} 
    10771077 
     1078%% ================================================================================================= 
    10781079\subsubsection{Attributes list per family} 
    10791080 
    10801081\begin{table} 
    1081   \scriptsize 
    10821082  \begin{tabularx}{\textwidth}{|l|X|l|l|} 
    10831083    \hline 
     
    11141114    \hline 
    11151115  \end{tabularx} 
    1116   \caption{Reference attributes ("\tt{*\_ref}")} 
     1116  \caption{XIOS: reference attributes ("\texttt{*\_ref}")} 
    11171117\end{table} 
    11181118 
    11191119\begin{table} 
    1120   \scriptsize 
    11211120  \begin{tabularx}{\textwidth}{|l|X|l|l|} 
    11221121    \hline 
     
    11501149    \hline 
    11511150  \end{tabularx} 
    1152   \caption{Domain attributes ("\tt{zoom\_*}")} 
     1151  \caption{XIOS: domain attributes ("\texttt{zoom\_*}")} 
    11531152\end{table} 
    11541153 
    11551154\begin{table} 
    1156   \scriptsize 
    11571155  \begin{tabularx}{\textwidth}{|l|X|l|l|} 
    11581156    \hline 
     
    12051203    \hline 
    12061204  \end{tabularx} 
    1207   \caption{File attributes} 
     1205  \caption{XIOS: file attributes} 
    12081206\end{table} 
    12091207 
    12101208\begin{table} 
    1211   \scriptsize 
    12121209  \begin{tabularx}{\textwidth}{|l|X|l|l|} 
    12131210    \hline 
     
    12541251    \hline 
    12551252  \end{tabularx} 
    1256   \caption{Field attributes} 
     1253  \caption{XIOS: field attributes} 
    12571254\end{table} 
    12581255 
    12591256\begin{table} 
    1260   \scriptsize 
    12611257  \begin{tabularx}{\textwidth}{|l|X|X|X|} 
    12621258    \hline 
     
    13131309    \hline 
    13141310  \end{tabularx} 
    1315   \caption{Miscellaneous attributes} 
     1311  \caption{XIOS: miscellaneous attributes} 
    13161312\end{table} 
    13171313 
     1314%% ================================================================================================= 
    13181315\subsection{CF metadata standard compliance} 
    13191316 
    1320 Output from the XIOS-1.0 IO server is compliant with  
     1317Output from the XIOS IO server is compliant with 
    13211318\href{http://cfconventions.org/Data/cf-conventions/cf-conventions-1.5/build/cf-conventions.html}{version 1.5} of 
    1322 the CF metadata standard.  
     1319the CF metadata standard. 
    13231320Therefore while a user may wish to add their own metadata to the output files (as demonstrated in example 4 of 
    1324 section \autoref{subsec:IOM_xmlref}) the metadata should, for the most part, comply with the CF-1.5 standard. 
     1321section \autoref{subsec:DIA_IOM_xmlref}) the metadata should, for the most part, comply with the CF-1.5 standard. 
    13251322 
    13261323Some metadata that may significantly increase the file size (horizontal cell areas and vertices) are controlled by 
    1327 the namelist parameter \np{ln\_cfmeta} in the \ngn{namrun} namelist. 
     1324the namelist parameter \np{ln_cfmeta}{ln\_cfmeta} in the \nam{run}{run} namelist. 
    13281325This must be set to true if these metadata are to be included in the output files. 
    13291326 
    1330  
    1331 % ================================================================ 
    1332 %       NetCDF4 support 
    1333 % ================================================================ 
    1334 \section{NetCDF4 support (\protect\key{netcdf4})} 
     1327%% ================================================================================================= 
     1328\section[NetCDF4 support (\texttt{\textbf{key\_netcdf4}})]{NetCDF4 support (\protect\key{netcdf4})} 
    13351329\label{sec:DIA_nc4} 
    13361330 
     
    13401334Chunking and compression can lead to significant reductions in file sizes for a small runtime overhead. 
    13411335For a fuller discussion on chunking and other performance issues the reader is referred to 
    1342 the NetCDF4 documentation found \href{http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Chunking}{here}. 
     1336the NetCDF4 documentation found \href{https://www.unidata.ucar.edu/software/netcdf/docs/netcdf_perf_chunking.html}{here}. 
    13431337 
    13441338The new features are only available when the code has been linked with a NetCDF4 library 
     
    13461340Datasets created with chunking and compression are not backwards compatible with NetCDF3 "classic" format but 
    13471341most analysis codes can be relinked simply with the new libraries and will then read both NetCDF3 and NetCDF4 files. 
    1348 NEMO executables linked with NetCDF4 libraries can be made to produce NetCDF3 files by 
    1349 setting the \np{ln\_nc4zip} logical to false in the \textit{namnc4} namelist: 
    1350  
    1351 %------------------------------------------namnc4---------------------------------------------------- 
    1352  
    1353 \nlst{namnc4} 
    1354 %------------------------------------------------------------------------------------------------------------- 
     1342\NEMO\ executables linked with NetCDF4 libraries can be made to produce NetCDF3 files by 
     1343setting the \np{ln_nc4zip}{ln\_nc4zip} logical to false in the \nam{nc4}{nc4} namelist: 
     1344 
     1345\begin{listing} 
     1346  \nlst{namnc4} 
     1347  \caption{\forcode{&namnc4}} 
     1348  \label{lst:namnc4} 
     1349\end{listing} 
    13551350 
    13561351If \key{netcdf4} has not been defined, these namelist parameters are not read. 
    1357 In this case, \np{ln\_nc4zip} is set false and dummy routines for a few NetCDF4-specific functions are defined. 
     1352In this case, \np{ln_nc4zip}{ln\_nc4zip} is set false and dummy routines for a few NetCDF4-specific functions are defined. 
    13581353These functions will not be used but need to be included so that compilation is possible with NetCDF3 libraries. 
    13591354 
     
    13891384\end{forlines} 
    13901385 
    1391 \noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\tt 46x38x1} respectively in 
    1392 the mono-processor case (\ie global domain of {\small\tt 182x149x31}). 
    1393 An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in  
    1394 table \autoref{tab:NC4} which compares the results of two short runs of the ORCA2\_LIM reference configuration with 
     1386\noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\texttt 46x38x1} respectively in 
     1387the mono-processor case (\ie\ global domain of {\small\texttt 182x149x31}). 
     1388An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in 
     1389table \autoref{tab:DIA_NC4} which compares the results of two short runs of the ORCA2\_LIM reference configuration with 
    13951390a 4x2 mpi partitioning. 
    13961391Note the variation in the compression ratio achieved which reflects chiefly the dry to wet volume ratio of 
    13971392each processing region. 
    13981393 
    1399 %------------------------------------------TABLE---------------------------------------------------- 
    14001394\begin{table} 
    1401   \scriptsize 
    14021395  \centering 
    14031396  \begin{tabular}{lrrr} 
     
    14311424    ORCA2\_2d\_grid\_W\_0007.nc & 4416    & 1368     & 70\%      \\ 
    14321425  \end{tabular} 
    1433   \caption{ 
    1434     \protect\label{tab:NC4} 
    1435     Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression 
    1436   } 
     1426  \caption{Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression} 
     1427  \label{tab:DIA_NC4} 
    14371428\end{table} 
    1438 %---------------------------------------------------------------------------------------------------- 
    14391429 
    14401430When \key{iomput} is activated with \key{netcdf4} chunking and compression parameters for fields produced via 
    1441 \np{iom\_put} calls are set via an equivalent and identically named namelist to \textit{namnc4} in 
    1442 \np{xmlio\_server.def}. 
    1443 Typically this namelist serves the mean files whilst the \ngn{ namnc4} in the main namelist file continues to 
     1431\rou{iom\_put} calls are set via an equivalent and identically named namelist to \nam{nc4}{nc4} in 
     1432\textit{xmlio\_server.def}. 
     1433Typically this namelist serves the mean files whilst the \nam{nc4}{nc4} in the main namelist file continues to 
    14441434serve the restart files. 
    14451435This duplication is unfortunate but appropriate since, if using io\_servers, the domain sizes of 
    14461436the individual files produced by the io\_server processes may be different to those produced by 
    14471437the invidual processing regions and different chunking choices may be desired. 
    1448   
    1449 % ------------------------------------------------------------------------------------------------------------- 
    1450 %       Tracer/Dynamics Trends 
    1451 % ------------------------------------------------------------------------------------------------------------- 
    1452 \section{Tracer/Dynamics trends  (\protect\ngn{namtrd})} 
     1438 
     1439%% ================================================================================================= 
     1440\section[Tracer/Dynamics trends (\forcode{&namtrd})]{Tracer/Dynamics trends (\protect\nam{trd}{trd})} 
    14531441\label{sec:DIA_trd} 
    14541442 
    1455 %------------------------------------------namtrd---------------------------------------------------- 
    1456  
    1457 \nlst{namtrd}  
    1458 %------------------------------------------------------------------------------------------------------------- 
     1443\begin{listing} 
     1444  \nlst{namtrd} 
     1445  \caption{\forcode{&namtrd}} 
     1446  \label{lst:namtrd} 
     1447\end{listing} 
    14591448 
    14601449Each trend of the dynamics and/or temperature and salinity time evolution equations can be send to 
    14611450\mdl{trddyn} and/or \mdl{trdtra} modules (see TRD directory) just after their computation 
    1462 (\ie at the end of each $dyn\cdots.F90$ and/or $tra\cdots.F90$ routines). 
    1463 This capability is controlled by options offered in \ngn{namtrd} namelist. 
    1464 Note that the output are done with xIOS, and therefore the \key{IOM} is required. 
    1465  
    1466 What is done depends on the \ngn{namtrd} logical set to \forcode{.true.}: 
     1451(\ie\ at the end of each \textit{dyn....F90} and/or \textit{tra....F90} routines). 
     1452This capability is controlled by options offered in \nam{trd}{trd} namelist. 
     1453Note that the output are done with XIOS, and therefore the \key{iomput} is required. 
     1454 
     1455What is done depends on the \nam{trd}{trd} logical set to \forcode{.true.}: 
    14671456 
    14681457\begin{description} 
    1469 \item[\np{ln\_glo\_trd}]: 
    1470   at each \np{nn\_trd} time-step a check of the basin averaged properties of 
     1458\item [{\np{ln_glo_trd}{ln\_glo\_trd}}]: at each \np{nn_trd}{nn\_trd} time-step a check of the basin averaged properties of 
    14711459  the momentum and tracer equations is performed. 
    14721460  This also includes a check of $T^2$, $S^2$, $\tfrac{1}{2} (u^2+v2)$, 
    14731461  and potential energy time evolution equations properties; 
    1474 \item[\np{ln\_dyn\_trd}]: 
    1475   each 3D trend of the evolution of the two momentum components is output; 
    1476 \item[\np{ln\_dyn\_mxl}]: 
    1477   each 3D trend of the evolution of the two momentum components averaged over the mixed layer is output; 
    1478 \item[\np{ln\_vor\_trd}]: 
    1479   a vertical summation of the moment tendencies is performed, 
     1462\item [{\np{ln_dyn_trd}{ln\_dyn\_trd}}]: each 3D trend of the evolution of the two momentum components is output; 
     1463\item [{\np{ln_dyn_mxl}{ln\_dyn\_mxl}}]: each 3D trend of the evolution of the two momentum components averaged over the mixed layer is output; 
     1464\item [{\np{ln_vor_trd}{ln\_vor\_trd}}]: a vertical summation of the moment tendencies is performed, 
    14801465  then the curl is computed to obtain the barotropic vorticity tendencies which are output; 
    1481 \item[\np{ln\_KE\_trd}] : 
    1482   each 3D trend of the Kinetic Energy equation is output; 
    1483 \item[\np{ln\_tra\_trd}]: 
    1484   each 3D trend of the evolution of temperature and salinity is output; 
    1485 \item[\np{ln\_tra\_mxl}]: 
    1486   each 2D trend of the evolution of temperature and salinity averaged over the mixed layer is output; 
     1466\item [{\np{ln_KE_trd}{ln\_KE\_trd}}]  : each 3D trend of the Kinetic Energy equation is output; 
     1467\item [{\np{ln_tra_trd}{ln\_tra\_trd}}]: each 3D trend of the evolution of temperature and salinity is output; 
     1468\item [{\np{ln_tra_mxl}{ln\_tra\_mxl}}]: each 2D trend of the evolution of temperature and salinity averaged over the mixed layer is output; 
    14871469\end{description} 
    14881470 
    1489 Note that the mixed layer tendency diagnostic can also be used on biogeochemical models via  
    1490 the \key{trdtrc} and \key{trdmld\_trc} CPP keys. 
     1471Note that the mixed layer tendency diagnostic can also be used on biogeochemical models via 
     1472the \key{trdtrc} and \key{trdmxl\_trc} CPP keys. 
    14911473 
    14921474\textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested. 
    1493 In particular, options associated with \np{ln\_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl} are not working, 
    1494 and none of the options have been tested with variable volume (\ie \key{vvl} defined). 
    1495  
    1496 % ------------------------------------------------------------------------------------------------------------- 
    1497 %       On-line Floats trajectories 
    1498 % ------------------------------------------------------------------------------------------------------------- 
    1499 \section{FLO: On-Line Floats trajectories (\protect\key{floats})} 
    1500 \label{sec:FLO} 
    1501 %--------------------------------------------namflo------------------------------------------------------- 
    1502  
    1503 \nlst{namflo}  
    1504 %-------------------------------------------------------------------------------------------------------------- 
     1475In particular, options associated with \np{ln_dyn_mxl}{ln\_dyn\_mxl}, \np{ln_vor_trd}{ln\_vor\_trd}, and \np{ln_tra_mxl}{ln\_tra\_mxl} are not working, 
     1476and none of the options have been tested with variable volume (\ie\ \np[=.true.]{ln_linssh}{ln\_linssh}). 
     1477 
     1478%% ================================================================================================= 
     1479\section[FLO: On-Line Floats trajectories (\texttt{\textbf{key\_floats}})]{FLO: On-Line Floats trajectories (\protect\key{floats})} 
     1480\label{sec:DIA_FLO} 
     1481 
     1482\begin{listing} 
     1483  \nlst{namflo} 
     1484  \caption{\forcode{&namflo}} 
     1485  \label{lst:namflo} 
     1486\end{listing} 
    15051487 
    15061488The on-line computation of floats advected either by the three dimensional velocity field or constraint to 
    15071489remain at a given depth ($w = 0$ in the computation) have been introduced in the system during the CLIPPER project. 
    1508 Options are defined by \ngn{namflo} namelis variables. 
    1509 The algorithm used is based either on the work of \cite{Blanke_Raynaud_JPO97} (default option), 
    1510 or on a $4^th$ Runge-Hutta algorithm (\np{ln\_flork4}\forcode{ = .true.}). 
    1511 Note that the \cite{Blanke_Raynaud_JPO97} algorithm have the advantage of providing trajectories which 
     1490Options are defined by \nam{flo}{flo} namelist variables. 
     1491The algorithm used is based either on the work of \cite{blanke.raynaud_JPO97} (default option), 
     1492or on a $4^th$ Runge-Hutta algorithm (\np[=.true.]{ln_flork4}{ln\_flork4}). 
     1493Note that the \cite{blanke.raynaud_JPO97} algorithm have the advantage of providing trajectories which 
    15121494are consistent with the numeric of the code, so that the trajectories never intercept the bathymetry. 
    15131495 
     1496%% ================================================================================================= 
    15141497\subsubsection{Input data: initial coordinates} 
    15151498 
    15161499Initial coordinates can be given with Ariane Tools convention 
    1517 (IJK coordinates, (\np{ln\_ariane}\forcode{ = .true.}) ) or with longitude and latitude. 
    1518  
    1519 In case of Ariane convention, input filename is \np{init\_float\_ariane}. 
     1500(IJK coordinates, (\np[=.true.]{ln_ariane}{ln\_ariane}) ) or with longitude and latitude. 
     1501 
     1502In case of Ariane convention, input filename is \textit{init\_float\_ariane}. 
    15201503Its format is: \\ 
    1521 {\scriptsize \texttt{I J K nisobfl itrash itrash}} 
     1504{ \texttt{I J K nisobfl itrash}} 
    15221505 
    15231506\noindent with: 
     
    15251508 - I,J,K  : indexes of initial position 
    15261509 
    1527  - nisobfl: 0 for an isobar float, 1 for a float following the w velocity   
     1510 - nisobfl: 0 for an isobar float, 1 for a float following the w velocity 
    15281511 
    15291512 - itrash : set to zero; it is a dummy variable to respect Ariane Tools convention 
     
    15311514\noindent Example: \\ 
    15321515\noindent 
    1533 {\scriptsize 
     1516{ 
    15341517  \texttt{ 
    15351518    100.00000  90.00000  -1.50000 1.00000   0.00000   \\ 
     
    15421525In the other case (longitude and latitude), input filename is init\_float. 
    15431526Its format is: \\ 
    1544 {\scriptsize \texttt{Long Lat depth nisobfl ngrpfl itrash}} 
     1527{ \texttt{Long Lat depth nisobfl ngrpfl itrash}} 
    15451528 
    15461529\noindent with: 
     
    15561539\noindent Example: \\ 
    15571540\noindent 
    1558 {\scriptsize 
     1541{ 
    15591542  \texttt{ 
    15601543    20.0 0.0 0.0 0 1 1    \\ 
     
    15651548} \\ 
    15661549 
    1567 \np{jpnfl} is the total number of floats during the run. 
    1568 When initial positions are read in a restart file (\np{ln\_rstflo}\forcode{ = .true.} ), 
    1569 \np{jpnflnewflo} can be added in the initialization file. 
    1570  
     1550\np{jpnfl}{jpnfl} is the total number of floats during the run. 
     1551When initial positions are read in a restart file (\np[=.true.]{ln_rstflo}{ln\_rstflo} ), 
     1552\np{jpnflnewflo}{jpnflnewflo} can be added in the initialization file. 
     1553 
     1554%% ================================================================================================= 
    15711555\subsubsection{Output data} 
    15721556 
    1573 \np{nn\_writefl} is the frequency of writing in float output file and \np{nn\_stockfl} is the frequency of 
     1557\np{nn_writefl}{nn\_writefl} is the frequency of writing in float output file and \np{nn_stockfl}{nn\_stockfl} is the frequency of 
    15741558creation of the float restart file. 
    15751559 
    1576 Output data can be written in ascii files (\np{ln\_flo\_ascii}\forcode{ = .true.}). 
     1560Output data can be written in ascii files (\np[=.true.]{ln_flo_ascii}{ln\_flo\_ascii}). 
    15771561In that case, output filename is trajec\_float. 
    15781562 
    1579 Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}). 
    1580 There are 2 possibilities: 
    1581  
    1582 - if (\key{iomput}) is used, outputs are selected in  iodef.xml. 
     1563Another possiblity of writing format is Netcdf (\np[=.false.]{ln_flo_ascii}{ln\_flo\_ascii}) with 
     1564\key{iomput} and outputs selected in iodef.xml. 
    15831565Here it is an example of specification to put in files description section: 
    15841566 
     
    15971579\end{xmllines} 
    15981580 
    1599  -  if (\key{iomput}) is not used, a file called \ifile{trajec\_float} will be created by IOIPSL library. 
    1600  
    1601  See also \href{http://stockage.univ-brest.fr/~grima/Ariane/}{here} the web site describing the off-line use of 
    1602  this marvellous diagnostic tool. 
    1603  
    1604 % ------------------------------------------------------------------------------------------------------------- 
    1605 %       Harmonic analysis of tidal constituents 
    1606 % ------------------------------------------------------------------------------------------------------------- 
    1607 \section{Harmonic analysis of tidal constituents (\protect\key{diaharm}) } 
     1581%% ================================================================================================= 
     1582\section[Harmonic analysis of tidal constituents (\texttt{\textbf{key\_diaharm}})]{Harmonic analysis of tidal constituents (\protect\key{diaharm})} 
    16081583\label{sec:DIA_diag_harm} 
    16091584 
    1610 %------------------------------------------namdia_harm---------------------------------------------------- 
    1611 % 
    1612 \nlst{nam_diaharm} 
    1613 %---------------------------------------------------------------------------------------------------------- 
     1585\begin{listing} 
     1586  \nlst{nam_diaharm} 
     1587  \caption{\forcode{&nam_diaharm}} 
     1588  \label{lst:nam_diaharm} 
     1589\end{listing} 
    16141590 
    16151591A module is available to compute the amplitude and phase of tidal waves. 
    16161592This on-line Harmonic analysis is actived with \key{diaharm}. 
    16171593 
    1618 Some parameters are available in namelist \ngn{namdia\_harm}: 
    1619  
    1620  - \np{nit000\_han} is the first time step used for harmonic analysis 
    1621  
    1622  - \np{nitend\_han} is the  last time step used for harmonic analysis 
    1623  
    1624  - \np{nstep\_han}  is the  time step frequency for harmonic analysis 
    1625  
    1626  - \np{nb\_ana}     is the number of harmonics to analyse 
    1627  
    1628  - \np{tname}       is an array with names of tidal constituents to analyse 
    1629  
    1630  \np{nit000\_han} and \np{nitend\_han} must be between \np{nit000} and \np{nitend} of the simulation. 
     1594Some parameters are available in namelist \nam{_diaharm}{\_diaharm}: 
     1595 
     1596 - \np{nit000_han}{nit000\_han} is the first time step used for harmonic analysis 
     1597 
     1598 - \np{nitend_han}{nitend\_han} is the  last time step used for harmonic analysis 
     1599 
     1600 - \np{nstep_han}{nstep\_han}  is the  time step frequency for harmonic analysis 
     1601 
     1602% - \np{nb_ana}{nb\_ana}     is the number of harmonics to analyse 
     1603 
     1604 - \np{tname}{tname}       is an array with names of tidal constituents to analyse 
     1605 
     1606 \np{nit000_han}{nit000\_han} and \np{nitend_han}{nitend\_han} must be between \np{nit000}{nit000} and \np{nitend}{nitend} of the simulation. 
    16311607 The restart capability is not implemented. 
    16321608 
     
    16491625We obtain in output $C_{j}$ and $S_{j}$ for each tidal wave. 
    16501626 
    1651 % ------------------------------------------------------------------------------------------------------------- 
    1652 %       Sections transports 
    1653 % ------------------------------------------------------------------------------------------------------------- 
    1654 \section{Transports across sections (\protect\key{diadct}) } 
     1627%% ================================================================================================= 
     1628\section[Transports across sections (\texttt{\textbf{key\_diadct}})]{Transports across sections (\protect\key{diadct})} 
    16551629\label{sec:DIA_diag_dct} 
    16561630 
    1657 %------------------------------------------namdct---------------------------------------------------- 
    1658  
    1659 \nlst{namdct} 
    1660 %------------------------------------------------------------------------------------------------------------- 
     1631\begin{listing} 
     1632  \nlst{nam_diadct} 
     1633  \caption{\forcode{&nam_diadct}} 
     1634  \label{lst:nam_diadct} 
     1635\end{listing} 
    16611636 
    16621637A module is available to compute the transport of volume, heat and salt through sections. 
     
    16641639 
    16651640Each section is defined by the coordinates of its 2 extremities. 
    1666 The pathways between them are contructed using tools which can be found in \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT} 
    1667 and are written in a binary file \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is later read in by 
    1668 NEMO to compute on-line transports. 
     1641The pathways between them are contructed using tools which can be found in \texttt{tools/SECTIONS\_DIADCT} 
     1642and are written in a binary file \texttt{section\_ijglobal.diadct} which is later read in by 
     1643\NEMO\ to compute on-line transports. 
    16691644 
    16701645The on-line transports module creates three output ascii files: 
     
    16761651- \texttt{salt\_transport}   for   salt transports (unit: $10^{9}Kg s^{-1}$) \\ 
    16771652 
    1678 Namelist variables in \ngn{namdct} control how frequently the flows are summed and the time scales over which 
     1653Namelist variables in \nam{_diadct}{\_diadct} control how frequently the flows are summed and the time scales over which 
    16791654they are averaged, as well as the level of output for debugging: 
    1680 \np{nn\_dct}   : frequency of instantaneous transports computing 
    1681 \np{nn\_dctwri}: frequency of writing ( mean of instantaneous transports ) 
    1682 \np{nn\_debug} : debugging of the section 
    1683  
     1655\np{nn_dct}{nn\_dct}   : frequency of instantaneous transports computing 
     1656\np{nn_dctwri}{nn\_dctwri}: frequency of writing ( mean of instantaneous transports ) 
     1657\np{nn_debug}{nn\_debug} : debugging of the section 
     1658 
     1659%% ================================================================================================= 
    16841660\subsubsection{Creating a binary file containing the pathway of each section} 
    16851661 
    1686 In \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT/run}, 
     1662In \texttt{tools/SECTIONS\_DIADCT/run}, 
    16871663the file \textit{ {list\_sections.ascii\_global}} contains a list of all the sections that are to be computed 
    16881664(this list of sections is based on MERSEA project metrics). 
     
    16911667 
    16921668Each section is defined by: \\ 
    1693 \noindent {\scriptsize \texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name}} \\ 
     1669\noindent { \texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name}} \\ 
    16941670with: 
    16951671 
     
    16981674 - \texttt{long2 lat2}, coordinates of the second extremity of the section; 
    16991675 
    1700  - \texttt{nclass}    the number of bounds of your classes (\eg bounds for 2 classes); 
     1676 - \texttt{nclass}    the number of bounds of your classes (\eg\ bounds for 2 classes); 
    17011677 
    17021678 - \texttt{okstrpond} to compute    heat and       salt transports, \texttt{nostrpond} if no; 
     
    17081684 
    17091685\noindent If nclass $\neq$ 0, the next lines contain the class type and the nclass bounds: \\ 
    1710 {\scriptsize 
     1686{ 
    17111687  \texttt{ 
    17121688    long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name \\ 
     
    17311707 
    17321708 - \texttt{zsigp} for potential density classes \\ 
    1733    
     1709 
    17341710 The script \texttt{job.ksh} computes the pathway for each section and creates a binary file 
    1735  \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is read by NEMO. \\ 
     1711 \texttt{section\_ijglobal.diadct} which is read by \NEMO. \\ 
    17361712 
    17371713 It is possible to use this tools for new configuations: \texttt{job.ksh} has to be updated with 
     
    17411717 and the ATL\_Cuba\_Florida with 4 temperature clases (5 class bounds), are shown: \\ 
    17421718 \noindent 
    1743  {\scriptsize 
     1719 { 
    17441720   \texttt{ 
    17451721     -68.    -54.5   -60.    -64.7  00 okstrpond noice ACC\_Drake\_Passage \\ 
     
    17531729 } 
    17541730 
     1731%% ================================================================================================= 
    17551732\subsubsection{To read the output files} 
    17561733 
    17571734The output format is: \\ 
    1758 {\scriptsize 
     1735{ 
    17591736  \texttt{ 
    17601737    date, time-step number, section number,                \\ 
     
    17781755 
    17791756\begin{table} 
    1780   \scriptsize 
    17811757  \begin{tabular}{|l|l|l|l|l|} 
    17821758    \hline 
     
    17921768\end{table} 
    17931769 
    1794 % ================================================================ 
    1795 % Steric effect in sea surface height 
    1796 % ================================================================ 
     1770%% ================================================================================================= 
    17971771\section{Diagnosing the steric effect in sea surface height} 
    17981772\label{sec:DIA_steric} 
    1799  
    18001773 
    18011774Changes in steric sea level are caused when changes in the density of the water column imply an expansion or 
     
    18091782The steric effect is therefore not explicitely represented. 
    18101783This approximation does not represent a serious error with respect to the flow field calculated by the model 
    1811 \citep{Greatbatch_JGR94}, but extra attention is required when investigating sea level, 
     1784\citep{greatbatch_JGR94}, but extra attention is required when investigating sea level, 
    18121785as steric changes are an important contribution to local changes in sea level on seasonal and climatic time scales. 
    18131786This is especially true for investigation into sea level rise due to global warming. 
    18141787 
    18151788Fortunately, the steric contribution to the sea level consists of a spatially uniform component that 
    1816 can be diagnosed by considering the mass budget of the world ocean \citep{Greatbatch_JGR94}. 
     1789can be diagnosed by considering the mass budget of the world ocean \citep{greatbatch_JGR94}. 
    18171790In order to better understand how global mean sea level evolves and thus how the steric sea level can be diagnosed, 
    18181791we compare, in the following, the non-Boussinesq and Boussinesq cases. 
    18191792 
    18201793Let denote 
    1821 $\mathcal{M}$ the total mass    of liquid seawater ($\mathcal{M} = \int_D \rho dv$),  
    1822 $\mathcal{V}$ the total volume  of        seawater      ($\mathcal{V} = \int_D dv$),  
    1823 $\mathcal{A}$ the total surface of       the ocean      ($\mathcal{A} = \int_S ds$),  
    1824 $\bar{\rho}$ the global mean  seawater (\textit{in situ}) density  
     1794$\mathcal{M}$ the total mass    of liquid seawater ($\mathcal{M} = \int_D \rho dv$), 
     1795$\mathcal{V}$ the total volume  of        seawater      ($\mathcal{V} = \int_D dv$), 
     1796$\mathcal{A}$ the total surface of       the ocean      ($\mathcal{A} = \int_S ds$), 
     1797$\bar{\rho}$ the global mean  seawater (\textit{in situ}) density 
    18251798($\bar{\rho} = 1/\mathcal{V} \int_D \rho \,dv$), and 
    1826 $\bar{\eta}$ the global mean sea level  
     1799$\bar{\eta}$ the global mean sea level 
    18271800($\bar{\eta} = 1/\mathcal{A} \int_S \eta \,ds$). 
    18281801 
     
    18341807    \mathcal{V} &=  \mathcal{A}  \;\bar{\eta} 
    18351808  \end{split} 
    1836   \label{eq:MV_nBq} 
     1809  \label{eq:DIA_MV_nBq} 
    18371810\end{equation} 
    18381811 
     
    18421815  \frac{1}{e_3} \partial_t ( e_3\,\rho) + \nabla( \rho \, \textbf{U} ) 
    18431816  = \left. \frac{\textit{emp}}{e_3}\right|_\textit{surface} 
    1844   \label{eq:Co_nBq} 
     1817  \label{eq:DIA_Co_nBq} 
    18451818\end{equation} 
    18461819 
    18471820where $\rho$ is the \textit{in situ} density, and \textit{emp} the surface mass exchanges with the other media of 
    18481821the Earth system (atmosphere, sea-ice, land). 
    1849 Its global averaged leads to the total mass change  
     1822Its global averaged leads to the total mass change 
    18501823 
    18511824\begin{equation} 
    18521825  \partial_t \mathcal{M} = \mathcal{A} \;\overline{\textit{emp}} 
    1853   \label{eq:Mass_nBq} 
     1826  \label{eq:DIA_Mass_nBq} 
    18541827\end{equation} 
    18551828 
    18561829where $\overline{\textit{emp}} = \int_S \textit{emp}\,ds$ is the net mass flux through the ocean surface. 
    1857 Bringing \autoref{eq:Mass_nBq} and the time derivative of \autoref{eq:MV_nBq} together leads to 
     1830Bringing \autoref{eq:DIA_Mass_nBq} and the time derivative of \autoref{eq:DIA_MV_nBq} together leads to 
    18581831the evolution equation of the mean sea level 
    18591832 
     
    18611834  \partial_t \bar{\eta} = \frac{\overline{\textit{emp}}}{ \bar{\rho}} 
    18621835  - \frac{\mathcal{V}}{\mathcal{A}} \;\frac{\partial_t \bar{\rho} }{\bar{\rho}} 
    1863   \label{eq:ssh_nBq} 
     1836  \label{eq:DIA_ssh_nBq} 
    18641837\end{equation} 
    18651838 
    1866 The first term in equation \autoref{eq:ssh_nBq} alters sea level by adding or subtracting mass from the ocean.  
    1867 The second term arises from temporal changes in the global mean density; \ie from steric effects. 
     1839The first term in equation \autoref{eq:DIA_ssh_nBq} alters sea level by adding or subtracting mass from the ocean. 
     1840The second term arises from temporal changes in the global mean density; \ie\ from steric effects. 
    18681841 
    18691842In a Boussinesq fluid, $\rho$ is replaced by $\rho_o$ in all the equation except when $\rho$ appears multiplied by 
    1870 the gravity (\ie in the hydrostatic balance of the primitive Equations). 
    1871 In particular, the mass conservation equation, \autoref{eq:Co_nBq}, degenerates into the incompressibility equation: 
     1843the gravity (\ie\ in the hydrostatic balance of the primitive Equations). 
     1844In particular, the mass conservation equation, \autoref{eq:DIA_Co_nBq}, degenerates into the incompressibility equation: 
    18721845 
    18731846\[ 
    18741847  \frac{1}{e_3} \partial_t ( e_3 ) + \nabla( \textbf{U} ) = \left. \frac{\textit{emp}}{\rho_o \,e_3}\right|_ \textit{surface} 
    1875   % \label{eq:Co_Bq} 
     1848  % \label{eq:DIA_Co_Bq} 
    18761849\] 
    18771850 
     
    18801853\[ 
    18811854  \partial_t \mathcal{V} = \mathcal{A} \;\frac{\overline{\textit{emp}}}{\rho_o} 
    1882   % \label{eq:V_Bq} 
     1855  % \label{eq:DIA_V_Bq} 
    18831856\] 
    18841857 
     
    18881861the ocean surface, not by changes in mean mass of the ocean: the steric effect is missing in a Boussinesq fluid. 
    18891862 
    1890 Nevertheless, following \citep{Greatbatch_JGR94}, the steric effect on the volume can be diagnosed by 
    1891 considering the mass budget of the ocean.  
     1863Nevertheless, following \citep{greatbatch_JGR94}, the steric effect on the volume can be diagnosed by 
     1864considering the mass budget of the ocean. 
    18921865The apparent changes in $\mathcal{M}$, mass of the ocean, which are not induced by surface mass flux 
    18931866must be compensated by a spatially uniform change in the mean sea level due to expansion/contraction of the ocean 
    1894 \citep{Greatbatch_JGR94}. 
     1867\citep{greatbatch_JGR94}. 
    18951868In others words, the Boussinesq mass, $\mathcal{M}_o$, can be related to $\mathcal{M}$, 
    18961869the total mass of the ocean seen by the Boussinesq model, via the steric contribution to the sea level, 
     
    18991872\begin{equation} 
    19001873  \mathcal{M}_o = \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A} 
    1901   \label{eq:M_Bq} 
     1874  \label{eq:DIA_M_Bq} 
    19021875\end{equation} 
    19031876 
     
    19051878is converted into a mean change in sea level. 
    19061879Introducing the total density anomaly, $\mathcal{D}= \int_D d_a \,dv$, 
    1907 where $d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO (cf. \autoref{subsec:TRA_eos}) 
    1908 in \autoref{eq:M_Bq} leads to a very simple form for the steric height: 
     1880where $d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO\ (cf. \autoref{subsec:TRA_eos}) 
     1881in \autoref{eq:DIA_M_Bq} leads to a very simple form for the steric height: 
    19091882 
    19101883\begin{equation} 
    19111884  \eta_s = - \frac{1}{\mathcal{A}} \mathcal{D} 
    1912   \label{eq:steric_Bq} 
     1885  \label{eq:DIA_steric_Bq} 
    19131886\end{equation} 
    19141887 
    19151888The above formulation of the steric height of a Boussinesq ocean requires four remarks. 
    19161889First, one can be tempted to define $\rho_o$ as the initial value of $\mathcal{M}/\mathcal{V}$, 
    1917 \ie set $\mathcal{D}_{t=0}=0$, so that the initial steric height is zero. 
     1890\ie\ set $\mathcal{D}_{t=0}=0$, so that the initial steric height is zero. 
    19181891We do not recommend that. 
    19191892Indeed, in this case $\rho_o$ depends on the initial state of the ocean. 
     
    19241897This value is a sensible choice for the reference density used in a Boussinesq ocean climate model since, 
    19251898with the exception of only a small percentage of the ocean, density in the World Ocean varies by no more than 
    1926 2$\%$ from this value (\cite{Gill1982}, page 47). 
     18992$\%$ from this value (\cite{gill_bk82}, page 47). 
    19271900 
    19281901Second, we have assumed here that the total ocean surface, $\mathcal{A}$, 
    19291902does not change when the sea level is changing as it is the case in all global ocean GCMs 
    19301903(wetting and drying of grid point is not allowed). 
    1931    
    1932 Third, the discretisation of \autoref{eq:steric_Bq} depends on the type of free surface which is considered. 
    1933 In the non linear free surface case, \ie \key{vvl} defined, it is given by 
     1904 
     1905Third, the discretisation of \autoref{eq:DIA_steric_Bq} depends on the type of free surface which is considered. 
     1906In the non linear free surface case, \ie\ \np[=.true.]{ln_linssh}{ln\_linssh}, it is given by 
    19341907 
    19351908\[ 
    19361909  \eta_s = - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t} e_{2t} e_{3t} }{ \sum_{i,\,j,\,k}       e_{1t} e_{2t} e_{3t} } 
    1937   % \label{eq:discrete_steric_Bq_nfs} 
     1910  % \label{eq:DIA_discrete_steric_Bq_nfs} 
    19381911\] 
    19391912 
     
    19451918  \eta_s = - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t}e_{2t}e_{3t} + \sum_{i,\,j} d_a\; e_{1t}e_{2t} \eta } 
    19461919                  { \sum_{i,\,j,\,k}       e_{1t}e_{2t}e_{3t} + \sum_{i,\,j}       e_{1t}e_{2t} \eta } 
    1947   % \label{eq:discrete_steric_Bq_fs} 
     1920  % \label{eq:DIA_discrete_steric_Bq_fs} 
    19481921\] 
    19491922 
     
    19541927so that there are no associated ocean currents. 
    19551928Hence, the dynamically relevant sea level is the effective sea level, 
    1956 \ie the sea level as if sea ice (and snow) were converted to liquid seawater \citep{Campin_al_OM08}. 
    1957 However, in the current version of \NEMO the sea-ice is levitating above the ocean without mass exchanges between 
     1929\ie\ the sea level as if sea ice (and snow) were converted to liquid seawater \citep{campin.marshall.ea_OM08}. 
     1930However, in the current version of \NEMO\ the sea-ice is levitating above the ocean without mass exchanges between 
    19581931ice and ocean. 
    19591932Therefore the model effective sea level is always given by $\eta + \eta_s$, whether or not there is sea ice present. 
     
    19651938\[ 
    19661939  \eta_s = - \frac{1}{\mathcal{A}} \int_D d_a(T,S_o,p_o) \,dv 
    1967   % \label{eq:thermosteric_Bq} 
     1940  % \label{eq:DIA_thermosteric_Bq} 
    19681941\] 
    19691942 
    19701943where $S_o$ and $p_o$ are the initial salinity and pressure, respectively. 
    19711944 
    1972 Both steric and thermosteric sea level are computed in \mdl{diaar5} which needs the \key{diaar5} defined to 
    1973 be called. 
    1974  
    1975 % ------------------------------------------------------------------------------------------------------------- 
    1976 %       Other Diagnostics 
    1977 % ------------------------------------------------------------------------------------------------------------- 
    1978 \section{Other diagnostics (\protect\key{diahth}, \protect\key{diaar5})} 
     1945Both steric and thermosteric sea level are computed in \mdl{diaar5}. 
     1946 
     1947%% ================================================================================================= 
     1948\section{Other diagnostics} 
    19791949\label{sec:DIA_diag_others} 
    19801950 
     
    19821952The available ready-to-add diagnostics modules can be found in directory DIA. 
    19831953 
    1984 \subsection{Depth of various quantities (\protect\mdl{diahth})} 
     1954%% ================================================================================================= 
     1955\subsection[Depth of various quantities (\textit{diahth.F90})]{Depth of various quantities (\protect\mdl{diahth})} 
    19851956 
    19861957Among the available diagnostics the following ones are obtained when defining the \key{diahth} CPP key: 
    19871958 
    1988 - the mixed layer depth (based on a density criterion \citep{de_Boyer_Montegut_al_JGR04}) (\mdl{diahth}) 
     1959- the mixed layer depth (based on a density criterion \citep{de-boyer-montegut.madec.ea_JGR04}) (\mdl{diahth}) 
    19891960 
    19901961- the turbocline depth (based on a turbulent mixing coefficient criterion) (\mdl{diahth}) 
     
    19941965- the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth}) 
    19951966 
    1996 % ----------------------------------------------------------- 
    1997 %     Poleward heat and salt transports 
    1998 % ----------------------------------------------------------- 
    1999  
    2000 \subsection{Poleward heat and salt transports (\protect\mdl{diaptr})} 
    2001  
    2002 %------------------------------------------namptr----------------------------------------- 
    2003  
    2004 \nlst{namptr}  
    2005 %----------------------------------------------------------------------------------------- 
    2006  
    2007 The poleward heat and salt transports, their advective and diffusive component, 
    2008 and the meriodional stream function can be computed on-line in \mdl{diaptr} \np{ln\_diaptr} to true 
    2009 (see the \textit{\ngn{namptr} } namelist below). 
    2010 When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed for the Atlantic, Indian, 
     1967\begin{figure}[!t] 
     1968  \centering 
     1969  \includegraphics[width=0.66\textwidth]{DIA_mask_subasins} 
     1970  \caption[Decomposition of the World Ocean to compute transports as well as 
     1971  the meridional stream-function]{ 
     1972    Decomposition of the World Ocean (here ORCA2) into sub-basin used in to 
     1973    compute the heat and salt transports as well as the meridional stream-function: 
     1974    Atlantic basin (red), Pacific basin (green), 
     1975    Indian basin (blue), Indo-Pacific basin (blue+green). 
     1976    Note that semi-enclosed seas (Red, Med and Baltic seas) as well as 
     1977    Hudson Bay are removed from the sub-basins. 
     1978    Note also that the Arctic Ocean has been split into Atlantic and 
     1979    Pacific basins along the North fold line. 
     1980  } 
     1981  \label{fig:DIA_mask_subasins} 
     1982\end{figure} 
     1983 
     1984%% ================================================================================================= 
     1985\subsection[CMIP specific diagnostics (\textit{diaar5.F90}, \textit{diaptr.F90})]{CMIP specific diagnostics (\protect\mdl{diaar5})} 
     1986 
     1987A series of diagnostics has been added in the \mdl{diaar5} and \mdl{diaptr}. 
     1988In \mdl{diaar5} they correspond to outputs that are required for AR5 simulations (CMIP5) 
     1989(see also \autoref{sec:DIA_steric} for one of them). 
     1990The module \mdl{diaar5} is active when one of the following outputs is required : 
     1991global total volume (voltot), global mean ssh (sshtot), global total mass (masstot), global mean temperature (temptot), 
     1992global mean ssh steric (sshsteric), global mean ssh thermosteric (sshthster), global mean salinity (saltot), 
     1993sea water pressure at sea floor (botpres), dynamic sea surface height (sshdyn). 
     1994 
     1995In \mdl{diaptr} when \np[=.true.]{ln_diaptr}{ln\_diaptr} 
     1996(see the \nam{ptr}{ptr} namelist below) can be computed on-line the poleward heat and salt transports, 
     1997their advective and diffusive component, and the meriodional stream function . 
     1998When \np[=.true.]{ln_subbas}{ln\_subbas}, transports and stream function are computed for the Atlantic, Indian, 
    20111999Pacific and Indo-Pacific Oceans (defined north of 30\deg{S}) as well as for the World Ocean. 
    20122000The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains three 2D mask arrays, 
    2013 the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:mask_subasins}). 
    2014  
    2015 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    2016 \begin{figure}[!t] 
    2017   \begin{center} 
    2018     \includegraphics[width=1.0\textwidth]{Fig_mask_subasins} 
    2019     \caption{ 
    2020       \protect\label{fig:mask_subasins} 
    2021       Decomposition of the World Ocean (here ORCA2) into sub-basin used in to 
    2022       compute the heat and salt transports as well as the meridional stream-function: 
    2023       Atlantic basin (red), Pacific basin (green), Indian basin (bleue), Indo-Pacific basin (bleue+green). 
    2024       Note that semi-enclosed seas (Red, Med and Baltic seas) as well as Hudson Bay are removed from the sub-basins. 
    2025       Note also that the Arctic Ocean has been split into Atlantic and Pacific basins along the North fold line. 
    2026     } 
    2027   \end{center} 
    2028 \end{figure}   
    2029 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    2030  
    2031 % ----------------------------------------------------------- 
    2032 %       CMIP specific diagnostics  
    2033 % ----------------------------------------------------------- 
    2034 \subsection{CMIP specific diagnostics (\protect\mdl{diaar5})} 
    2035  
    2036 A series of diagnostics has been added in the \mdl{diaar5}. 
    2037 They corresponds to outputs that are required for AR5 simulations (CMIP5) 
    2038 (see also \autoref{sec:DIA_steric} for one of them). 
    2039 Activating those outputs requires to define the \key{diaar5} CPP key. 
    2040  
    2041 % ----------------------------------------------------------- 
    2042 %       25 hour mean and hourly Surface, Mid and Bed  
    2043 % ----------------------------------------------------------- 
     2001the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:DIA_mask_subasins}). 
     2002 
     2003\begin{listing} 
     2004  \nlst{namptr} 
     2005  \caption{\forcode{&namptr}} 
     2006  \label{lst:namptr} 
     2007\end{listing} 
     2008 
     2009%% ================================================================================================= 
    20442010\subsection{25 hour mean output for tidal models} 
    20452011 
    2046 %------------------------------------------nam_dia25h------------------------------------- 
    2047  
    2048 \nlst{nam_dia25h} 
    2049 %----------------------------------------------------------------------------------------- 
     2012\begin{listing} 
     2013  \nlst{nam_dia25h} 
     2014  \caption{\forcode{&nam_dia25h}} 
     2015  \label{lst:nam_dia25h} 
     2016\end{listing} 
    20502017 
    20512018A module is available to compute a crudely detided M2 signal by obtaining a 25 hour mean. 
     
    20542021This diagnostic is actived with the logical $ln\_dia25h$. 
    20552022 
    2056 % ----------------------------------------------------------- 
    2057 %     Top Middle and Bed hourly output 
    2058 % ----------------------------------------------------------- 
     2023%% ================================================================================================= 
    20592024\subsection{Top middle and bed hourly output} 
    20602025 
    2061 %------------------------------------------nam_diatmb----------------------------------------------------- 
    2062  
    2063 \nlst{nam_diatmb} 
    2064 %---------------------------------------------------------------------------------------------------------- 
     2026\begin{listing} 
     2027  \nlst{nam_diatmb} 
     2028  \caption{\forcode{&nam_diatmb}} 
     2029  \label{lst:nam_diatmb} 
     2030\end{listing} 
    20652031 
    20662032A module is available to output the surface (top), mid water and bed diagnostics of a set of standard variables. 
     
    20702036This diagnostic is actived with the logical $ln\_diatmb$. 
    20712037 
    2072 % ----------------------------------------------------------- 
    2073 %     Courant numbers 
    2074 % ----------------------------------------------------------- 
     2038%% ================================================================================================= 
    20752039\subsection{Courant numbers} 
    20762040 
     
    20802044\[ 
    20812045  C_u = |u|\frac{\rdt}{e_{1u}}, \quad C_v = |v|\frac{\rdt}{e_{2v}}, \quad C_w = |w|\frac{\rdt}{e_{3w}} 
    2082   % \label{eq:CFL} 
     2046  % \label{eq:DIA_CFL} 
    20832047\] 
    20842048 
     
    20892053Values greater than 1 indicate that information is propagated across more than one grid cell in a single time step. 
    20902054 
    2091 The variables can be activated by setting the \np{nn\_diacfl} namelist parameter to 1 in the \ngn{namctl} namelist. 
     2055The variables can be activated by setting the \np{nn_diacfl}{nn\_diacfl} namelist parameter to 1 in the \nam{ctl}{ctl} namelist. 
    20922056The diagnostics will be written out to an ascii file named cfl\_diagnostics.ascii. 
    20932057In this file the maximum value of $C_u$, $C_v$, and $C_w$ are printed at each timestep along with the coordinates of 
     
    20952059At the end of the model run the maximum value of $C_u$, $C_v$, and $C_w$ for the whole model run is printed along 
    20962060with the coordinates of each. 
    2097 The maximum values from the run are also copied to the ocean.output file.  
    2098  
    2099 % ================================================================ 
    2100  
    2101 \biblio 
    2102  
    2103 \pindex 
     2061The maximum values from the run are also copied to the ocean.output file. 
     2062 
     2063\subinc{\input{../../global/epilogue}} 
    21042064 
    21052065\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_DIU.tex

    r10442 r11831  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Diurnal SST models (DIU) 
    6 % Edited by James While 
    7 % ================================================================ 
     4 
    85\chapter{Diurnal SST Models (DIU)} 
    96\label{chap:DIU} 
    107 
    11 \minitoc 
     8\thispagestyle{plain} 
    129 
     10\chaptertoc 
    1311 
    14 \newpage 
    15 $\ $\newline % force a new line 
     12\paragraph{Changes record} ~\\ 
     13 
     14{\footnotesize 
     15  \begin{tabularx}{\textwidth}{l||X|X} 
     16    Release & Author(s) & Modifications \\ 
     17    \hline 
     18    {\em   4.0} & {\em ...} & {\em ...} \\ 
     19    {\em   3.6} & {\em ...} & {\em ...} \\ 
     20    {\em   3.4} & {\em ...} & {\em ...} \\ 
     21    {\em <=3.4} & {\em ...} & {\em ...} 
     22  \end{tabularx} 
     23} 
     24 
     25\clearpage 
    1626 
    1727Code to produce an estimate of the diurnal warming and cooling of the sea surface skin 
    18 temperature (skin SST) is found in the DIU directory.   
     28temperature (skin SST) is found in the DIU directory. 
    1929The skin temperature can be split into three parts: 
    2030\begin{itemize} 
    21 \item 
    22   A foundation SST which is free from diurnal warming. 
    23 \item 
    24   A warm layer, typically ~3\,m thick, 
     31\item A foundation SST which is free from diurnal warming. 
     32\item A warm layer, typically ~3\,m thick, 
    2533  where heating from solar radiation can cause a warm stably stratified layer during the daytime 
    26 \item 
    27   A cool skin, a thin layer, approximately ~1\, mm thick, 
     34\item A cool skin, a thin layer, approximately ~1\, mm thick, 
    2835  where long wave cooling is dominant and cools the immediate ocean surface. 
    2936\end{itemize} 
    3037 
    3138Models are provided for both the warm layer, \mdl{diurnal\_bulk}, and the cool skin, \mdl{cool\_skin}. 
    32 Foundation SST is not considered as it can be obtained either from the main NEMO model 
    33 (\ie from the temperature of the top few model levels) or from some other source.   
     39Foundation SST is not considered as it can be obtained either from the main \NEMO\ model 
     40(\ie\ from the temperature of the top few model levels) or from some other source. 
    3441It must be noted that both the cool skin and warm layer models produce estimates of the change in temperature 
    35 ($\Delta T_{\rm{cs}}$ and $\Delta T_{\rm{wl}}$) and 
     42($\Delta T_{\mathrm{cs}}$ and $\Delta T_{\mathrm{wl}}$) and 
    3643both must be added to a foundation SST to obtain the true skin temperature. 
    3744 
    38 Both the cool skin and warm layer models are controlled through the namelist \ngn{namdiu}: 
     45Both the cool skin and warm layer models are controlled through the namelist \nam{diu}{diu}: 
    3946 
    40 \nlst{namdiu} 
     47\begin{listing} 
     48  \nlst{namdiu} 
     49  \caption{\forcode{&namdiu}} 
     50  \label{lst:namdiu} 
     51\end{listing} 
     52 
    4153This namelist contains only two variables: 
    4254\begin{description} 
    43 \item[\np{ln\_diurnal}] 
    44   A logical switch for turning on/off both the cool skin and warm layer. 
    45 \item[\np{ln\_diurnal\_only}] 
    46   A logical switch which if \forcode{.true.} will run the diurnal model without the other dynamical parts of NEMO. 
    47   \np{ln\_diurnal\_only} must be \forcode{.false.} if \np{ln\_diurnal} is \forcode{.false.}. 
     55\item [{\np{ln_diurnal}{ln\_diurnal}}] A logical switch for turning on/off both the cool skin and warm layer. 
     56\item [{\np{ln_diurnal_only}{ln\_diurnal\_only}}] A logical switch which if \forcode{.true.} will run the diurnal model without the other dynamical parts of \NEMO. 
     57  \np{ln_diurnal_only}{ln\_diurnal\_only} must be \forcode{.false.} if \np{ln_diurnal}{ln\_diurnal} is \forcode{.false.}. 
    4858\end{description} 
    4959 
     
    5363Initialisation is through the restart file. 
    5464Specifically the code will expect the presence of the 2-D variable ``Dsst'' to initialise the warm layer. 
    55 The cool skin model, which is determined purely by the instantaneous fluxes, has no initialisation variable.   
     65The cool skin model, which is determined purely by the instantaneous fluxes, has no initialisation variable. 
    5666 
    57 %=============================================================== 
     67%% ================================================================================================= 
    5868\section{Warm layer model} 
    59 \label{sec:warm_layer_sec} 
    60 %=============================================================== 
     69\label{sec:DIU_warm_layer_sec} 
    6170 
    62 The warm layer is calculated using the model of \citet{Takaya_al_JGR10} (TAKAYA10 model hereafter). 
     71The warm layer is calculated using the model of \citet{takaya.bidlot.ea_JGR10} (TAKAYA10 model hereafter). 
    6372This is a simple flux based model that is defined by the equations 
    6473\begin{align} 
    65 \frac{\partial{\Delta T_{\rm{wl}}}}{\partial{t}}&=&\frac{Q(\nu+1)}{D_T\rho_w c_p 
     74\frac{\partial{\Delta T_{\mathrm{wl}}}}{\partial{t}}&=&\frac{Q(\nu+1)}{D_T\rho_w c_p 
    6675\nu}-\frac{(\nu+1)ku^*_{w}f(L_a)\Delta T}{D_T\Phi\!\left(\frac{D_T}{L}\right)} \mbox{,} 
    67 \label{eq:ecmwf1} \\ 
    68 L&=&\frac{\rho_w c_p u^{*^3}_{w}}{\kappa g \alpha_w Q }\mbox{,}\label{eq:ecmwf2} 
     76\label{eq:DIU_ecmwf1} \\ 
     77L&=&\frac{\rho_w c_p u^{*^3}_{w}}{\kappa g \alpha_w Q }\mbox{,}\label{eq:DIU_ecmwf2} 
    6978\end{align} 
    70 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. 
    71 In equation (\autoref{eq:ecmwf1}) $\alpha_w=2\times10^{-4}$ is the thermal expansion coefficient of water, 
     79where $\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. 
     80In equation (\autoref{eq:DIU_ecmwf1}) $\alpha_w=2\times10^{-4}$ is the thermal expansion coefficient of water, 
    7281$\kappa=0.4$ is von K\'{a}rm\'{a}n's constant, $c_p$ is the heat capacity at constant pressure of sea water, 
    7382$\rho_w$ is the water density, and $L$ is the Monin-Obukhov length. 
    7483The tunable variable $\nu$ is a shape parameter that defines the expected subskin temperature profile via 
    75 $T(z) = T(0) - \left( \frac{z}{D_T} \right)^\nu \Delta T_{\rm{wl}}$, 
     84$T(z) = T(0) - \left( \frac{z}{D_T} \right)^\nu \Delta T_{\mathrm{wl}}$, 
    7685where $T$ is the absolute temperature and $z\le D_T$ is the depth below the top of the warm layer. 
    7786The influence of wind on TAKAYA10 comes through the magnitude of the friction velocity of the water $u^*_{w}$, 
     
    7988the relationship $u^*_{w} = u_{10}\sqrt{\frac{C_d\rho_a}{\rho_w}}$, where $C_d$ is the drag coefficient, 
    8089and $\rho_a$ is the density of air. 
    81 The symbol $Q$ in equation (\autoref{eq:ecmwf1}) is the instantaneous total thermal energy flux into 
     90The symbol $Q$ in equation (\autoref{eq:DIU_ecmwf1}) is the instantaneous total thermal energy flux into 
    8291the diurnal layer, \ie 
    8392\[ 
    84   Q = Q_{\rm{sol}} + Q_{\rm{lw}} + Q_{\rm{h}}\mbox{,} 
    85   % \label{eq:e_flux_eqn} 
     93  Q = Q_{\mathrm{sol}} + Q_{\mathrm{lw}} + Q_{\mathrm{h}}\mbox{,} 
     94  % \label{eq:DIU_e_flux_eqn} 
    8695\] 
    87 where $Q_{\rm{h}}$ is the sensible and latent heat flux, $Q_{\rm{lw}}$ is the long wave flux, 
    88 and $Q_{\rm{sol}}$ is the solar flux absorbed within the diurnal warm layer. 
    89 For $Q_{\rm{sol}}$ the 9 term representation of \citet{Gentemann_al_JGR09} is used. 
    90 In equation \autoref{eq:ecmwf1} the function $f(L_a)=\max(1,L_a^{\frac{2}{3}})$, 
     96where $Q_{\mathrm{h}}$ is the sensible and latent heat flux, $Q_{\mathrm{lw}}$ is the long wave flux, 
     97and $Q_{\mathrm{sol}}$ is the solar flux absorbed within the diurnal warm layer. 
     98For $Q_{\mathrm{sol}}$ the 9 term representation of \citet{gentemann.minnett.ea_JGR09} is used. 
     99In equation \autoref{eq:DIU_ecmwf1} the function $f(L_a)=\max(1,L_a^{\frac{2}{3}})$, 
    91100where $L_a=0.3$\footnote{ 
    92101  This is a global average value, more accurately $L_a$ could be computed as $L_a=(u^*_{w}/u_s)^{\frac{1}{2}}$, 
     
    991084\zeta^2}{1+3\zeta+0.25\zeta^2} &(\zeta \ge 0) \\ 
    100109                                    (1 - 16\zeta)^{-\frac{1}{2}} & (\zeta < 0) \mbox{,} 
    101                                     \end{array} \right. \label{eq:stab_func_eqn} 
     110                                    \end{array} \right. \label{eq:DIU_stab_func_eqn} 
    102111\end{equation} 
    103 where $\zeta=\frac{D_T}{L}$.  It is clear that the first derivative of (\autoref{eq:stab_func_eqn}), 
    104 and thus of (\autoref{eq:ecmwf1}), is discontinuous at $\zeta=0$ (\ie $Q\rightarrow0$ in 
    105 equation (\autoref{eq:ecmwf2})). 
     112where $\zeta=\frac{D_T}{L}$.  It is clear that the first derivative of (\autoref{eq:DIU_stab_func_eqn}), 
     113and thus of (\autoref{eq:DIU_ecmwf1}), is discontinuous at $\zeta=0$ (\ie\ $Q\rightarrow0$ in 
     114equation (\autoref{eq:DIU_ecmwf2})). 
    106115 
    107 The two terms on the right hand side of (\autoref{eq:ecmwf1}) represent different processes. 
     116The two terms on the right hand side of (\autoref{eq:DIU_ecmwf1}) represent different processes. 
    108117The first term is simply the diabatic heating or cooling of the diurnal warm layer due to 
    109118thermal energy fluxes into and out of the layer. 
     
    111120In practice the second term acts as a relaxation on the temperature. 
    112121 
    113 %=============================================================== 
     122%% ================================================================================================= 
     123\section{Cool skin model} 
     124\label{sec:DIU_cool_skin_sec} 
    114125 
    115 \section{Cool skin model} 
    116 \label{sec:cool_skin_sec} 
    117  
    118 %=============================================================== 
    119  
    120 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}$. 
    121 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 
     126The 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}$. 
     127As 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 
    122128\[ 
    123   % \label{eq:sunders_eqn} 
    124   \Delta T_{\rm{cs}}=\frac{Q_{\rm{ns}}\delta}{k_t} \mbox{,} 
     129  % \label{eq:DIU_sunders_eqn} 
     130  \Delta T_{\mathrm{cs}}=\frac{Q_{\mathrm{ns}}\delta}{k_t} \mbox{,} 
    125131\] 
    126 where $Q_{\rm{ns}}$ is the, usually negative, non-solar heat flux into the ocean and 
     132where $Q_{\mathrm{ns}}$ is the, usually negative, non-solar heat flux into the ocean and 
    127133$k_t$ is the thermal conductivity of sea water. 
    128134$\delta$ is the thickness of the skin layer and is given by 
    129135\begin{equation} 
    130 \label{eq:sunders_thick_eqn} 
     136\label{eq:DIU_sunders_thick_eqn} 
    131137\delta=\frac{\lambda \mu}{u^*_{w}} \mbox{,} 
    132138\end{equation} 
    133139where $\mu$ is the kinematic viscosity of sea water and $\lambda$ is a constant of proportionality which 
    134 \citet{Saunders_JAS82} suggested varied between 5 and 10. 
     140\citet{saunders_JAS67} suggested varied between 5 and 10. 
    135141 
    136 The value of $\lambda$ used in equation (\autoref{eq:sunders_thick_eqn}) is that of \citet{Artale_al_JGR02}, 
    137 which is shown in \citet{Tu_Tsuang_GRL05} to outperform a number of other parametrisations at 
     142The value of $\lambda$ used in equation (\autoref{eq:DIU_sunders_thick_eqn}) is that of \citet{artale.iudicone.ea_JGR02}, 
     143which is shown in \citet{tu.tsuang_GRL05} to outperform a number of other parametrisations at 
    138144both low and high wind speeds. 
    139145Specifically, 
    140146\[ 
    141   % \label{eq:artale_lambda_eqn} 
     147  % \label{eq:DIU_artale_lambda_eqn} 
    142148  \lambda = \frac{ 8.64\times10^4 u^*_{w} k_t }{ \rho c_p h \mu \gamma }\mbox{,} 
    143149\] 
     
    145151$\gamma$ is a dimensionless function of wind speed $u$: 
    146152\[ 
    147   % \label{eq:artale_gamma_eqn} 
     153  % \label{eq:DIU_artale_gamma_eqn} 
    148154  \gamma = 
    149155  \begin{cases} 
     
    154160\] 
    155161 
    156 \biblio 
    157  
    158 \pindex 
     162\subinc{\input{../../global/epilogue}} 
    159163 
    160164\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_DOM.tex

    r10502 r11831  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter 2 ——— Space and Time Domain (DOM) 
    6 % ================================================================ 
     4 
    75\chapter{Space Domain (DOM)} 
    86\label{chap:DOM} 
    97 
    10 \minitoc 
    11  
    12 % Missing things: 
    13 %  - istate: description of the initial state   ==> this has to be put elsewhere.. 
    14 %                  perhaps in MISC ?  By the way the initialisation of T S and dynamics  
    15 %                  should be put outside of DOM routine (better with TRC staff and off-line 
    16 %                  tracers) 
    17 %  -geo2ocean:  how to switch from geographic to mesh coordinate 
    18 %     - domclo:  closed sea and lakes.... management of closea sea area : specific to global configuration, both forced and coupled 
    19  
    20 \newpage 
    21  
    22 Having defined the continuous equations in \autoref{chap:PE} and chosen a time discretization \autoref{chap:STP}, 
    23 we need to choose a discretization on a grid, and numerical algorithms. 
     8% Missing things 
     9% -    istate: description of the initial state   ==> this has to be put elsewhere.. 
     10%              perhaps in MISC ?  By the way the initialisation of T S and dynamics 
     11%              should be put outside of DOM routine (better with TRC staff and off-line 
     12%              tracers) 
     13% - geo2ocean: how to switch from geographic to mesh coordinate 
     14% -    domclo: closed sea and lakes.... 
     15%              management of closea sea area: specific to global cfg, both forced and coupled 
     16 
     17\thispagestyle{plain} 
     18 
     19\chaptertoc 
     20 
     21\paragraph{Changes record} ~\\ 
     22 
     23{\footnotesize 
     24  \begin{tabularx}{0.8\textwidth}{l||X|X} 
     25    Release                                                                                 & 
     26    Author(s)                                                                               & 
     27    Modifications                                                                           \\ 
     28    \hline 
     29    {\em 4.0                                                                              } & 
     30    {\em Simon M\"{u}ller \& Andrew Coward \newline \newline 
     31      Simona Flavoni and Tim Graham                                                       } & 
     32    {\em Compatibility changes: many options moved to external domain configuration tools 
     33      (see \autoref{apdx:DOMCFG}). \newline 
     34      Updates                                                                             } \\ 
     35    {\em 3.6                                                                              } & 
     36    {\em Rachid Benshila, Christian \'{E}th\'{e}, Pierre Mathiot and Gurvan Madec         } & 
     37    {\em Updates                                                                          } \\ 
     38    {\em $\leq$ 3.4                                                                       } & 
     39    {\em Gurvan Madec and S\'{e}bastien Masson                                            } & 
     40    {\em First version                                                                    } 
     41  \end{tabularx} 
     42} 
     43 
     44\clearpage 
     45 
     46Having defined the continuous equations in \autoref{chap:MB} and 
     47chosen a time discretisation \autoref{chap:TD}, 
     48we need to choose a grid for spatial discretisation and related numerical algorithms. 
    2449In the present chapter, we provide a general description of the staggered grid used in \NEMO, 
    25 and other information relevant to the main directory routines as well as the DOM (DOMain) directory. 
    26  
    27 % ================================================================ 
    28 % Fundamentals of the Discretisation 
    29 % ================================================================ 
     50and other relevant information about the DOM (DOMain) source code modules. 
     51 
     52%% ================================================================================================= 
    3053\section{Fundamentals of the discretisation} 
    3154\label{sec:DOM_basics} 
    3255 
    33 % ------------------------------------------------------------------------------------------------------------- 
    34 %        Arrangement of Variables  
    35 % ------------------------------------------------------------------------------------------------------------- 
     56%% ================================================================================================= 
    3657\subsection{Arrangement of variables} 
    3758\label{subsec:DOM_cell} 
    3859 
    39 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    40 \begin{figure}[!tb] 
    41   \begin{center} 
    42     \includegraphics[]{Fig_cell} 
    43     \caption{ 
    44       \protect\label{fig:cell} 
    45       Arrangement of variables. 
    46       $t$ indicates scalar points where temperature, salinity, density, pressure and 
    47       horizontal divergence are defined. 
    48       $(u,v,w)$ indicates vector points, and $f$ indicates vorticity points where both relative and 
    49       planetary vorticities are defined. 
    50     } 
    51   \end{center} 
     60\begin{figure} 
     61  \centering 
     62  \includegraphics[width=0.33\textwidth]{DOM_cell} 
     63  \caption[Arrangement of variables in the unit cell of space domain]{ 
     64    Arrangement of variables in the unit cell of space domain. 
     65    $t$ indicates scalar points where 
     66    temperature, salinity, density, pressure and horizontal divergence are defined. 
     67    $(u,v,w)$ indicates vector points, and $f$ indicates vorticity points where 
     68    both relative and planetary vorticities are defined.} 
     69  \label{fig:DOM_cell} 
    5270\end{figure} 
    53 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    54  
    55 The numerical techniques used to solve the Primitive Equations in this model are based on the traditional, 
    56 centred second-order finite difference approximation. 
    57 Special attention has been given to the homogeneity of the solution in the three space directions. 
     71 
     72The numerical techniques used to solve the Primitive Equations in this model are based on 
     73the traditional, centred second-order finite difference approximation. 
     74Special attention has been given to the homogeneity of the solution in the three spatial directions. 
    5875The arrangement of variables is the same in all directions. 
    59 It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with vector points $(u, v, w)$ defined in 
    60 the centre of each face of the cells (\autoref{fig:cell}). 
    61 This is the generalisation to three dimensions of the well-known ``C'' grid in Arakawa's classification 
    62 \citep{Mesinger_Arakawa_Bk76}. 
    63 The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge and 
    64 the barotropic stream function $\psi$ is defined at horizontal points overlying the $\zeta$ and $f$-points. 
    65  
    66 The ocean mesh (\ie the position of all the scalar and vector points) is defined by the transformation that 
    67 gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 
    68 The grid-points are located at integer or integer and a half value of $(i,j,k)$ as indicated on \autoref{tab:cell}. 
    69 In all the following, subscripts $u$, $v$, $w$, $f$, $uw$, $vw$ or $fw$ indicate the position of 
    70 the grid-point where the scale factors are defined. 
    71 Each scale factor is defined as the local analytical value provided by \autoref{eq:scale_factors}. 
     76It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with 
     77vector points $(u, v, w)$ defined in the centre of each face of the cells (\autoref{fig:DOM_cell}). 
     78This is the generalisation to three dimensions of the well-known ``C'' grid in 
     79Arakawa's classification \citep{mesinger.arakawa_bk76}. 
     80The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each 
     81vertical edge and the barotropic stream function $\psi$ is defined at horizontal points overlying 
     82the $\zeta$ and $f$-points. 
     83 
     84The ocean mesh (\ie\ the position of all the scalar and vector points) is defined by 
     85the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 
     86The grid-points are located at integer or integer and a half value of $(i,j,k)$ as indicated on 
     87\autoref{tab:DOM_cell}. 
     88In all the following, 
     89subscripts $u$, $v$, $w$, $f$, $uw$, $vw$ or $fw$ indicate the position of the grid-point where 
     90the scale factors are defined. 
     91Each scale factor is defined as the local analytical value provided by \autoref{eq:MB_scale_factors}. 
    7292As a result, the mesh on which partial derivatives $\pd[]{\lambda}$, $\pd[]{\varphi}$ and 
    73 $\pd[]{z}$ are evaluated in a uniform mesh with a grid size of unity. 
    74 Discrete partial derivatives are formulated by the traditional, centred second order finite difference approximation 
    75 while the scale factors are chosen equal to their local analytical value. 
     93$\pd[]{z}$ are evaluated is a uniform mesh with a grid size of unity. 
     94Discrete partial derivatives are formulated by 
     95the traditional, centred second order finite difference approximation while 
     96the scale factors are chosen equal to their local analytical value. 
    7697An important point here is that the partial derivative of the scale factors must be evaluated by 
    7798centred finite difference approximation, not from their analytical expression. 
    78 This preserves the symmetry of the discrete set of equations and therefore satisfies many of 
    79 the continuous properties (see \autoref{apdx:C}). 
     99This preserves the symmetry of the discrete set of equations and 
     100therefore satisfies many of the continuous properties (see \autoref{apdx:INVARIANTS}). 
    80101A similar, related remark can be made about the domain size: 
    81 when needed, an area, volume, or the total ocean depth must be evaluated as the sum of the relevant scale factors 
    82 (see \autoref{eq:DOM_bar} in the next section). 
    83  
    84 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    85 \begin{table}[!tb] 
    86   \begin{center} 
    87     \begin{tabular}{|p{46pt}|p{56pt}|p{56pt}|p{56pt}|} 
    88       \hline 
    89       T  & $i      $ & $j      $ & $k      $ \\ 
    90       \hline 
    91       u  & $i + 1/2$ & $j      $ & $k      $ \\ 
    92       \hline 
    93       v  & $i      $ & $j + 1/2$ & $k      $ \\ 
    94       \hline 
    95       w  & $i      $ & $j      $ & $k + 1/2$ \\ 
    96       \hline 
    97       f  & $i + 1/2$ & $j + 1/2$ & $k      $ \\ 
    98       \hline 
    99       uw & $i + 1/2$ & $j      $ & $k + 1/2$ \\ 
    100       \hline 
    101       vw & $i      $ & $j + 1/2$ & $k + 1/2$ \\ 
    102       \hline 
    103       fw & $i + 1/2$ & $j + 1/2$ & $k + 1/2$ \\ 
    104       \hline 
    105     \end{tabular} 
    106     \caption{ 
    107       \protect\label{tab:cell} 
    108       Location of grid-points as a function of integer or integer and a half value of the column, line or level. 
    109       This indexing is only used for the writing of the semi -discrete equation. 
    110       In the code, the indexing uses integer values only and has a reverse direction in the vertical 
    111       (see \autoref{subsec:DOM_Num_Index}) 
    112     } 
    113   \end{center} 
     102when needed, an area, volume, or the total ocean depth must be evaluated as 
     103the product or sum of the relevant scale factors (see \autoref{eq:DOM_bar} in the next section). 
     104 
     105\begin{table} 
     106  \centering 
     107  \begin{tabular}{|l|l|l|l|} 
     108    \hline 
     109    t   & $i      $ & $j      $ & $k      $ \\ 
     110    \hline 
     111    u   & $i + 1/2$ & $j      $ & $k      $ \\ 
     112    \hline 
     113    v   & $i      $ & $j + 1/2$ & $k      $ \\ 
     114    \hline 
     115    w   & $i      $ & $j      $ & $k + 1/2$ \\ 
     116    \hline 
     117    f   & $i + 1/2$ & $j + 1/2$ & $k      $ \\ 
     118    \hline 
     119    uw  & $i + 1/2$ & $j      $ & $k + 1/2$ \\ 
     120    \hline 
     121    vw  & $i      $ & $j + 1/2$ & $k + 1/2$ \\ 
     122    \hline 
     123    fw  & $i + 1/2$ & $j + 1/2$ & $k + 1/2$ \\ 
     124    \hline 
     125  \end{tabular} 
     126  \caption[Location of grid-points]{ 
     127    Location of grid-points as a function of integer or 
     128    integer and a half value of the column, line or level. 
     129    This indexing is only used for the writing of the semi-discrete equations. 
     130    In the code, the indexing uses integer values only and 
     131    is positive downwards in the vertical with $k=1$ at the surface. 
     132    (see \autoref{subsec:DOM_Num_Index})} 
     133  \label{tab:DOM_cell} 
    114134\end{table} 
    115 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    116  
    117 % ------------------------------------------------------------------------------------------------------------- 
    118 %        Vector Invariant Formulation  
    119 % ------------------------------------------------------------------------------------------------------------- 
     135 
     136Note that the definition of the scale factors 
     137(\ie\ as the analytical first derivative of the transformation that 
     138results in $(\lambda,\varphi,z)$ as a function of $(i,j,k)$) 
     139is specific to the \NEMO\ model \citep{marti.madec.ea_JGR92}. 
     140As an example, a scale factor in the $i$ direction is defined locally at a $t$-point, 
     141whereas many other models on a C grid choose to define such a scale factor as 
     142the distance between the $u$-points on each side of the $t$-point. 
     143Relying on an analytical transformation has two advantages: 
     144firstly, there is no ambiguity in the scale factors appearing in the discrete equations, 
     145since they are first introduced in the continuous equations; 
     146secondly, analytical transformations encourage good practice by 
     147the definition of smoothly varying grids 
     148(rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) 
     149\citep{treguier.dukowicz.ea_JGR96}. 
     150An example of the effect of such a choice is shown in \autoref{fig:DOM_zgr_e3}. 
     151\begin{figure} 
     152  \centering 
     153  \includegraphics[width=0.5\textwidth]{DOM_zgr_e3} 
     154  \caption[Comparison of grid-point position, vertical grid-size and scale factors]{ 
     155    Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical, 
     156    and (b) analytically derived grid-point position and scale factors. 
     157    For both grids here, the same $w$-point depth has been chosen but 
     158    in (a) the $t$-points are set half way between $w$-points while 
     159    in (b) they are defined from an analytical function: 
     160    $z(k) = 5 \, (k - 1/2)^3 - 45 \, (k - 1/2)^2 + 140 \, (k - 1/2) - 150$. 
     161    Note the resulting difference between the value of the grid-size $\Delta_k$ and 
     162    those of the scale factor $e_k$.} 
     163  \label{fig:DOM_zgr_e3} 
     164\end{figure} 
     165 
     166%% ================================================================================================= 
    120167\subsection{Discrete operators} 
    121168\label{subsec:DOM_operators} 
    122169 
    123 Given the values of a variable $q$ at adjacent points, the differencing and averaging operators at 
    124 the midpoint between them are: 
     170Given the values of a variable $q$ at adjacent points, 
     171the differencing and averaging operators at the midpoint between them are: 
    125172\begin{alignat*}{2} 
    126   % \label{eq:di_mi} 
     173  % \label{eq:DOM_di_mi} 
    127174  \delta_i [q]      &= &       &q (i + 1/2) - q (i - 1/2) \\ 
    128175  \overline q^{\, i} &= &\big\{ &q (i + 1/2) + q (i - 1/2) \big\} / 2 
     
    130177 
    131178Similar operators are defined with respect to $i + 1/2$, $j$, $j + 1/2$, $k$, and $k + 1/2$. 
    132 Following \autoref{eq:PE_grad} and \autoref{eq:PE_lap}, the gradient of a variable $q$ defined at 
    133 a $t$-point has its three components defined at $u$-, $v$- and $w$-points while 
    134 its Laplacian is defined at $t$-point. 
     179Following \autoref{eq:MB_grad} and \autoref{eq:MB_lap}, 
     180the gradient of a variable $q$ defined at a $t$-point has 
     181its three components defined at $u$-, $v$- and $w$-points while 
     182its Laplacian is defined at the $t$-point. 
    135183These operators have the following discrete forms in the curvilinear $s$-coordinates system: 
    136 \[ 
     184\begin{gather*} 
    137185  % \label{eq:DOM_grad} 
    138186  \nabla q \equiv   \frac{1}{e_{1u}} \delta_{i + 1/2} [q] \; \, \vect i 
    139187                  + \frac{1}{e_{2v}} \delta_{j + 1/2} [q] \; \, \vect j 
    140                   + \frac{1}{e_{3w}} \delta_{k + 1/2} [q] \; \, \vect k 
    141 \] 
    142 \begin{multline*} 
     188                  + \frac{1}{e_{3w}} \delta_{k + 1/2} [q] \; \, \vect k \\ 
    143189  % \label{eq:DOM_lap} 
    144190  \Delta q \equiv   \frac{1}{e_{1t} \, e_{2t} \, e_{3t}} 
    145191                    \; \lt[   \delta_i \lt( \frac{e_{2u} \, e_{3u}}{e_{1u}} \; \delta_{i + 1/2} [q] \rt) 
    146                             + \delta_j \lt( \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [q] \rt) \; \rt] \\ 
     192                            + \delta_j \lt( \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [q] \rt) \; \rt] 
    147193                  + \frac{1}{e_{3t}} 
    148194                              \delta_k \lt[ \frac{1              }{e_{3w}} \; \delta_{k + 1/2} [q] \rt] 
    149 \end{multline*} 
    150  
    151 Following \autoref{eq:PE_curl} and \autoref{eq:PE_div}, a vector $\vect A = (a_1,a_2,a_3)$ defined at 
    152 vector points $(u,v,w)$ has its three curl components defined at $vw$-, $uw$, and $f$-points, and 
     195\end{gather*} 
     196 
     197Following \autoref{eq:MB_curl} and \autoref{eq:MB_div}, 
     198a vector $\vect A = (a_1,a_2,a_3)$ defined at vector points $(u,v,w)$ has 
     199its three curl components defined at $vw$-, $uw$, and $f$-points, and 
    153200its divergence defined at $t$-points: 
    154 \begin{multline} 
     201\begin{multline*} 
    155202% \label{eq:DOM_curl} 
    156203  \nabla \times \vect A \equiv   \frac{1}{e_{2v} \, e_{3vw}} 
     
    163210                                 \Big[   \delta_{i + 1/2} (e_{2v} \, a_2) 
    164211                                       - \delta_{j + 1/2} (e_{1u} \, a_1) \Big] \vect k 
    165 \end{multline} 
    166 \begin{equation} 
     212\end{multline*} 
     213\[ 
    167214% \label{eq:DOM_div} 
    168215  \nabla \cdot \vect A \equiv   \frac{1}{e_{1t} \, e_{2t} \, e_{3t}} 
    169216                                \Big[ \delta_i (e_{2u} \, e_{3u} \, a_1) + \delta_j (e_{1v} \, e_{3v} \, a_2) \Big] 
    170217                              + \frac{1}{e_{3t}} \delta_k (a_3) 
    171 \end{equation} 
    172  
    173 The vertical average over the whole water column denoted by an overbar becomes for a quantity $q$ which 
    174 is a masked field (i.e. equal to zero inside solid area): 
     218\] 
     219 
     220The vertical average over the whole water column is denoted by an overbar and 
     221is for a masked field $q$ (\ie\ a quantity that is equal to zero inside solid areas): 
    175222\begin{equation} 
    176223  \label{eq:DOM_bar} 
     
    178225\end{equation} 
    179226where $H_q$  is the ocean depth, which is the masked sum of the vertical scale factors at $q$ points, 
    180 $k^b$ and $k^o$ are the bottom and surface $k$-indices, and the symbol $k^o$ refers to a summation over 
    181 all grid points of the same type in the direction indicated by the subscript (here $k$). 
     227$k^b$ and $k^o$ are the bottom and surface $k$-indices, 
     228and the symbol $\sum \limits_k$ refers to a summation over all grid points of the same type in 
     229the direction indicated by the subscript (here $k$). 
    182230 
    183231In continuous form, the following properties are satisfied: 
     
    189237\end{gather} 
    190238 
    191 It is straightforward to demonstrate that these properties are verified locally in discrete form as soon as 
    192 the scalar $q$ is taken at $t$-points and the vector $\vect A$ has its components defined at 
     239It is straightforward to demonstrate that these properties are verified locally in discrete form as 
     240soon as the scalar $q$ is taken at $t$-points and the vector $\vect A$ has its components defined at 
    193241vector points $(u,v,w)$. 
    194242 
    195 Let $a$ and $b$ be two fields defined on the mesh, with value zero inside continental area. 
    196 Using integration by parts it can be shown that the differencing operators ($\delta_i$, $\delta_j$ and $\delta_k$) 
    197 are skew-symmetric linear operators, and further that the averaging operators $\overline{\cdots}^{\, i}$, 
    198 $\overline{\cdots}^{\, j}$ and $\overline{\cdots}^{\, k}$) are symmetric linear operators, \ie 
    199 \begin{alignat}{4} 
     243Let $a$ and $b$ be two fields defined on the mesh, with a value of zero inside continental areas. 
     244It can be shown that the differencing operators ($\delta_i$, $\delta_j$ and 
     245$\delta_k$) are skew-symmetric linear operators, 
     246and further that the averaging operators ($\overline{\cdots}^{\, i}$, $\overline{\cdots}^{\, j}$ and 
     247$\overline{\cdots}^{\, k}$) are symmetric linear operators, \ie 
     248\begin{alignat}{5} 
    200249  \label{eq:DOM_di_adj} 
    201250  &\sum \limits_i a_i \; \delta_i [b]      &\equiv &- &&\sum \limits_i \delta      _{   i + 1/2} [a] &b_{i + 1/2} \\ 
     
    204253\end{alignat} 
    205254 
    206 In other words, the adjoint of the differencing and averaging operators are $\delta_i^* = \delta_{i + 1/2}$ and  
     255In other words, 
     256the adjoint of the differencing and averaging operators are $\delta_i^* = \delta_{i + 1/2}$ and 
    207257$(\overline{\cdots}^{\, i})^* = \overline{\cdots}^{\, i + 1/2}$, respectively. 
    208 These two properties will be used extensively in the \autoref{apdx:C} to 
     258These two properties will be used extensively in the \autoref{apdx:INVARIANTS} to 
    209259demonstrate integral conservative properties of the discrete formulation chosen. 
    210260 
    211 % ------------------------------------------------------------------------------------------------------------- 
    212 %        Numerical Indexing  
    213 % ------------------------------------------------------------------------------------------------------------- 
     261%% ================================================================================================= 
    214262\subsection{Numerical indexing} 
    215263\label{subsec:DOM_Num_Index} 
    216264 
    217 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    218 \begin{figure}[!tb] 
    219   \begin{center} 
    220     \includegraphics[]{Fig_index_hor} 
    221     \caption{ 
    222       \protect\label{fig:index_hor} 
    223       Horizontal integer indexing used in the \fortran code. 
    224       The dashed area indicates the cell in which variables contained in arrays have the same $i$- and $j$-indices 
    225     } 
    226   \end{center} 
     265\begin{figure} 
     266  \centering 
     267  \includegraphics[width=0.33\textwidth]{DOM_index_hor} 
     268  \caption[Horizontal integer indexing]{ 
     269    Horizontal integer indexing used in the \fortran\ code. 
     270    The dashed area indicates the cell in which 
     271    variables contained in arrays have the same $i$- and $j$-indices} 
     272  \label{fig:DOM_index_hor} 
    227273\end{figure} 
    228 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    229  
    230 The array representation used in the \fortran code requires an integer indexing while 
    231 the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with the use of 
    232 integer values for $t$-points and both integer and integer and a half values for all the other points. 
    233 Therefore a specific integer indexing must be defined for points other than $t$-points 
    234 (\ie velocity and vorticity grid-points). 
    235 Furthermore, the direction of the vertical indexing has been changed so that the surface level is at $k = 1$. 
    236  
    237 % ----------------------------------- 
    238 %        Horizontal Indexing  
    239 % ----------------------------------- 
     274 
     275The array representation used in the \fortran\ code requires an integer indexing. 
     276However, the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with 
     277the use of integer values for $t$-points only while 
     278all the other points involve integer and a half values. 
     279Therefore, a specific integer indexing has been defined for points other than $t$-points 
     280(\ie\ velocity and vorticity grid-points). 
     281Furthermore, the direction of the vertical indexing has been reversed and 
     282the surface level set at $k = 1$. 
     283 
     284%% ================================================================================================= 
    240285\subsubsection{Horizontal indexing} 
    241286\label{subsec:DOM_Num_Index_hor} 
    242287 
    243 The indexing in the horizontal plane has been chosen as shown in \autoref{fig:index_hor}. 
     288The indexing in the horizontal plane has been chosen as shown in \autoref{fig:DOM_index_hor}. 
    244289For an increasing $i$ index ($j$ index), 
    245290the $t$-point and the eastward $u$-point (northward $v$-point) have the same index 
    246 (see the dashed area in \autoref{fig:index_hor}). 
    247 A $t$-point and its nearest northeast $f$-point have the same $i$-and $j$-indices. 
    248  
    249 % ----------------------------------- 
    250 %        Vertical indexing  
    251 % ----------------------------------- 
     291(see the dashed area in \autoref{fig:DOM_index_hor}). 
     292A $t$-point and its nearest north-east $f$-point have the same $i$-and $j$-indices. 
     293 
     294%% ================================================================================================= 
    252295\subsubsection{Vertical indexing} 
    253296\label{subsec:DOM_Num_Index_vertical} 
    254297 
    255 In the vertical, the chosen indexing requires special attention since the $k$-axis is re-orientated downward in 
    256 the \fortran code compared to the indexing used in the semi -discrete equations and 
    257 given in \autoref{subsec:DOM_cell}. 
    258 The sea surface corresponds to the $w$-level $k = 1$ which is the same index as $t$-level just below 
    259 (\autoref{fig:index_vert}). 
    260 The last $w$-level ($k = jpk$) either corresponds to the ocean floor or is inside the bathymetry while 
    261 the last $t$-level is always inside the bathymetry (\autoref{fig:index_vert}). 
    262 Note that for an increasing $k$ index, a $w$-point and the $t$-point just below have the same $k$ index, 
    263 in opposition to what is done in the horizontal plane where 
    264 it is the $t$-point and the nearest velocity points in the direction of the horizontal axis that 
    265 have the same $i$ or $j$ index 
    266 (compare the dashed area in \autoref{fig:index_hor} and \autoref{fig:index_vert}). 
     298In the vertical, the chosen indexing requires special attention since 
     299the direction of the $k$-axis in the \fortran\ code is the reverse of 
     300that used in the semi-discrete equations and given in \autoref{subsec:DOM_cell}. 
     301The sea surface corresponds to the $w$-level $k = 1$, 
     302which is the same index as the $t$-level just below (\autoref{fig:DOM_index_vert}). 
     303The last $w$-level ($k = jpk$) either corresponds to or is below the ocean floor while 
     304the last $t$-level is always outside the ocean domain (\autoref{fig:DOM_index_vert}). 
     305Note that a $w$-point and the directly underlaying $t$-point have a common $k$ index 
     306(\ie\ $t$-points and their nearest $w$-point neighbour in negative index direction), 
     307in contrast to the indexing on the horizontal plane where 
     308the $t$-point has the same index as the nearest velocity points in 
     309the positive direction of the respective horizontal axis index 
     310(compare the dashed area in \autoref{fig:DOM_index_hor} and \autoref{fig:DOM_index_vert}). 
    267311Since the scale factors are chosen to be strictly positive, 
    268 a \textit{minus sign} appears in the \fortran code \textit{before all the vertical derivatives} of 
    269 the discrete equations given in this documentation. 
    270  
    271 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    272 \begin{figure}[!pt] 
    273   \begin{center} 
    274     \includegraphics[]{Fig_index_vert} 
    275     \caption{ 
    276       \protect\label{fig:index_vert} 
    277       Vertical integer indexing used in the \fortran code. 
    278       Note that the $k$-axis is orientated downward. 
    279       The dashed area indicates the cell in which variables contained in arrays have the same $k$-index. 
    280     } 
    281   \end{center} 
     312a \textit{minus sign} is included in the \fortran\ implementations of 
     313\textit{all the vertical derivatives} of the discrete equations given in this manual in order to 
     314accommodate the opposing vertical index directions in implementation and documentation. 
     315 
     316\begin{figure} 
     317  \centering 
     318  \includegraphics[width=0.33\textwidth]{DOM_index_vert} 
     319  \caption[Vertical integer indexing]{ 
     320    Vertical integer indexing used in the \fortran\ code. 
     321    Note that the $k$-axis is oriented downward. 
     322    The dashed area indicates the cell in which 
     323    variables contained in arrays have a common $k$-index.} 
     324  \label{fig:DOM_index_vert} 
    282325\end{figure} 
    283 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    284  
    285 % ----------------------------------- 
    286 %        Domain Size 
    287 % ----------------------------------- 
    288 \subsubsection{Domain size} 
     326 
     327%% ================================================================================================= 
     328\section{Spatial domain configuration} 
     329\label{subsec:DOM_config} 
     330 
     331Two typical methods are available to specify the spatial domain configuration; 
     332they can be selected using parameter \np{ln_read_cfg}{ln\_read\_cfg} parameter in 
     333namelist \nam{cfg}{cfg}. 
     334 
     335If \np{ln_read_cfg}{ln\_read\_cfg} is set to \forcode{.true.}, 
     336the domain-specific parameters and fields are read from a NetCDF input file, 
     337whose name (without its .nc suffix) can be specified as 
     338the value of the \np{cn_domcfg}{cn\_domcfg} parameter in namelist \nam{cfg}{cfg}. 
     339 
     340If \np{ln_read_cfg}{ln\_read\_cfg} is set to \forcode{.false.}, 
     341the domain-specific parameters and fields can be provided (\eg\ analytically computed) by 
     342subroutines \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}. 
     343These subroutines can be supplied in the \path{MY_SRC} directory of the configuration, 
     344and default versions that configure the spatial domain for the GYRE reference configuration are 
     345present in the \path{./src/OCE/USR} directory. 
     346 
     347In version 4.0 there are no longer any options for reading complex bathymetries and 
     348performing a vertical discretisation at run-time. 
     349Whilst it is occasionally convenient to have a common bathymetry file and, for example, 
     350to run similar models with and without partial bottom boxes and/or sigma-coordinates, 
     351supporting such choices leads to overly complex code. 
     352Worse still is the difficulty of ensuring the model configurations intended to be identical are 
     353indeed so when the model domain itself can be altered by runtime selections. 
     354The code previously used to perform vertical discretisation has been incorporated into 
     355an external tool (\path{./tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMCFG}. 
     356 
     357The next subsections summarise the parameter and fields related to 
     358the configuration of the whole model domain. 
     359These represent the minimum information that must be provided either via 
     360the \np{cn_domcfg}{cn\_domcfg} file or 
     361set by code inserted into user-supplied versions of the \texttt{usrdef\_*} subroutines. 
     362The requirements are presented in three sections: 
     363the domain size (\autoref{subsec:DOM_size}), the horizontal mesh (\autoref{subsec:DOM_hgr}), 
     364and the vertical grid (\autoref{subsec:DOM_zgr}). 
     365 
     366%% ================================================================================================= 
     367\subsection{Domain size} 
    289368\label{subsec:DOM_size} 
    290369 
    291 The total size of the computational domain is set by the parameters \np{jpiglo}, 
    292 \np{jpjglo} and \np{jpkglo} in the $i$, $j$ and $k$ directions respectively. 
    293 Parameters $jpi$ and $jpj$ refer to the size of each processor subdomain when 
    294 the code is run in parallel using domain decomposition (\key{mpp\_mpi} defined, 
    295 see \autoref{sec:LBC_mpp}). 
    296  
    297 % ================================================================ 
    298 % Domain: List of fields needed 
    299 % ================================================================ 
    300 \section{Needed fields} 
    301 \label{sec:DOM_fields} 
    302 The ocean mesh (\ie the position of all the scalar and vector points) is defined by the transformation that 
    303 gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 
    304 The grid-points are located at integer or integer and a half values of as indicated in \autoref{tab:cell}. 
    305 The associated scale factors are defined using the analytical first derivative of the transformation 
    306 \autoref{eq:scale_factors}. 
    307 Necessary fields for configuration definition are: 
     370The total size of the computational domain is set by the parameters \jp{jpiglo}, \jp{jpjglo} and 
     371\jp{jpkglo} for the $i$, $j$ and $k$ directions, respectively. 
     372Note, that the variables \texttt{jpi} and \texttt{jpj} refer to 
     373the size of each processor subdomain when the code is run in parallel using domain decomposition 
     374(\key{mpp\_mpi} defined, see \autoref{sec:LBC_mpp}). 
     375 
     376The name of the configuration is set through parameter \np{cn_cfg}{cn\_cfg}, 
     377and the nominal resolution through parameter \np{nn_cfg}{nn\_cfg} 
     378(unless in the input file both of variables \texttt{ORCA} and \texttt{ORCA\_index} are present, 
     379in which case \np{cn_cfg}{cn\_cfg} and \np{nn_cfg}{nn\_cfg} are set from these values accordingly). 
     380 
     381The global lateral boundary condition type is selected from 8 options using parameter \jp{jperio}. 
     382See \autoref{sec:LBC_jperio} for details on the available options and 
     383the corresponding values for \jp{jperio}. 
     384 
     385%% ================================================================================================= 
     386\subsection[Horizontal grid mesh (\textit{domhgr.F90}]{Horizontal grid mesh (\protect\mdl{domhgr})} 
     387\label{subsec:DOM_hgr} 
     388 
     389%% ================================================================================================= 
     390\subsubsection{Required fields} 
     391\label{sec:DOM_hgr_fields} 
     392 
     393The explicit specification of a range of mesh-related fields are required for 
     394the definition of a configuration. 
     395These include: 
     396 
     397\begin{clines} 
     398int    jpiglo, jpjglo, jpkglo     /* global domain sizes                                    */ 
     399int    jperio                     /* lateral global domain b.c.                             */ 
     400double glamt, glamu, glamv, glamf /* geographic longitude (t,u,v and f points respectively) */ 
     401double gphit, gphiu, gphiv, gphif /* geographic latitude                                    */ 
     402double e1t, e1u, e1v, e1f         /* horizontal scale factors                               */ 
     403double e2t, e2u, e2v, e2f         /* horizontal scale factors                               */ 
     404\end{clines} 
     405 
     406The values of the geographic longitude and latitude arrays at indices $i,j$ correspond to 
     407the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$, 
     408evaluated at the values as specified in \autoref{tab:DOM_cell} for the respective grid-point position. 
     409The calculation of the values of the horizontal scale factor arrays in general additionally involves 
     410partial derivatives of $\lambda$ and $\varphi$ with respect to $i$ and $j$, 
     411evaluated for the same arguments as $\lambda$ and $\varphi$. 
     412 
     413%% ================================================================================================= 
     414\subsubsection{Optional fields} 
     415 
     416\begin{clines} 
     417                        /* Optional:                                                 */ 
     418int    ORCA, ORCA_index /* configuration name, configuration resolution              */ 
     419double e1e2u, e1e2v     /* U and V surfaces (if grid size reduction in some straits) */ 
     420double ff_f, ff_t       /* Coriolis parameter (if not on the sphere)                 */ 
     421\end{clines} 
     422 
     423\NEMO\ can support the local reduction of key strait widths by 
     424altering individual values of e2u or e1v at the appropriate locations. 
     425This is particularly useful for locations such as Gibraltar or Indonesian Throughflow pinch-points 
     426(see \autoref{sec:MISC_strait} for illustrated examples). 
     427The key is to reduce the faces of $T$-cell 
     428(\ie\ change the value of the horizontal scale factors at $u$- or $v$-point) but 
     429not the volume of the cells. 
     430Doing otherwise can lead to numerical instability issues. 
     431In normal operation the surface areas are computed from $e1u * e2u$ and $e1v * e2v$ but 
     432in cases where a gridsize reduction is required, 
     433the unaltered surface areas at $u$ and $v$ grid points 
     434(\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or pre-computed in \mdl{usrdef\_hgr}. 
     435If these arrays are present in the \np{cn_domcfg}{cn\_domcfg} file they are read and 
     436the internal computation is suppressed. 
     437Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{e1e2u} and \texttt{e1e2v} should 
     438set the surface-area computation flag: 
     439\texttt{ie1e2u\_v} to a non-zero value to suppress their re-computation. 
     440 
     441\smallskip 
     442Similar logic applies to the other optional fields: 
     443\texttt{ff\_f} and \texttt{ff\_t} which can be used to 
     444provide the Coriolis parameter at F- and T-points respectively if the mesh is not on a sphere. 
     445If present these fields will be read and used and 
     446the normal calculation ($2 * \Omega * \sin(\varphi)$) suppressed. 
     447Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{ff\_f} and \texttt{ff\_t} should 
     448set the Coriolis computation flag: 
     449\texttt{iff} to a non-zero value to suppress their re-computation. 
     450 
     451Note that longitudes, latitudes, and scale factors at $w$ points are exactly equal to 
     452those of $t$ points, thus no specific arrays are defined at $w$ points. 
     453 
     454%% ================================================================================================= 
     455\subsection[Vertical grid (\textit{domzgr.F90})]{Vertical grid (\protect\mdl{domzgr})} 
     456\label{subsec:DOM_zgr} 
     457 
     458\begin{listing} 
     459  \nlst{namdom} 
     460  \caption{\forcode{&namdom}} 
     461  \label{lst:namdom} 
     462\end{listing} 
     463 
     464In the vertical, the model mesh is determined by four things: 
     465\begin{enumerate} 
     466\item the bathymetry given in meters; 
     467\item the number of levels of the model (\jp{jpk}); 
     468\item the analytical transformation $z(i,j,k)$ and the vertical scale factors 
     469  (derivatives of the transformation); and 
     470\item the masking system, 
     471  \ie\ the number of wet model levels at each $(i,j)$ location of the horizontal grid. 
     472\end{enumerate} 
     473 
     474\begin{figure} 
     475  \centering 
     476  \includegraphics[width=0.5\textwidth]{DOM_z_zps_s_sps} 
     477  \caption[Ocean bottom regarding coordinate systems ($z$, $s$ and hybrid $s-z$)]{ 
     478    The ocean bottom as seen by the model: 
     479    \begin{enumerate*}[label=(\textit{\alph*})] 
     480    \item $z$-coordinate with full step, 
     481    \item $z$-coordinate with partial step, 
     482    \item $s$-coordinate: terrain following representation, 
     483    \item hybrid $s-z$ coordinate, 
     484    \item hybrid $s-z$ coordinate with partial step, and 
     485    \item same as (e) but in the non-linear free surface 
     486      (\protect\np[=.false.]{ln_linssh}{ln\_linssh}). 
     487  \end{enumerate*} 
     488  Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e).} 
     489  \label{fig:DOM_z_zps_s_sps} 
     490\end{figure} 
     491 
     492The choice of a vertical coordinate is made when setting up the configuration; 
     493it is not intended to be an option which can be changed in the middle of an experiment. 
     494The one exception to this statement being the choice of linear or non-linear free surface. 
     495In v4.0 the linear free surface option is implemented as 
     496a special case of the non-linear free surface. 
     497This is computationally wasteful since it uses the structures for time-varying 3D metrics 
     498for fields that (in the linear free surface case) are fixed. 
     499However, the linear free-surface is rarely used and 
     500implementing it this way means a single configuration file can support both options. 
     501 
     502By default a non-linear free surface is used 
     503(\np{ln_linssh}{ln\_linssh} set to \forcode{=.false.} in \nam{dom}{dom}): 
     504the coordinate follow the time-variation of the free surface so that 
     505the transformation is time dependent: $z(i,j,k,t)$ (\eg\ \autoref{fig:DOM_z_zps_s_sps}f). 
     506When a linear free surface is assumed 
     507(\np{ln_linssh}{ln\_linssh} set to \forcode{=.true.} in \nam{dom}{dom}), 
     508the vertical coordinates are fixed in time, but 
     509the seawater can move up and down across the $z_0$ surface 
     510(in other words, the top of the ocean in not a rigid lid). 
     511 
     512Note that settings: 
     513\np{ln_zco}{ln\_zco}, \np{ln_zps}{ln\_zps}, \np{ln_sco}{ln\_sco} and \np{ln_isfcav}{ln\_isfcav} 
     514mentioned in the following sections appear to be namelist options but 
     515they are no longer truly namelist options for \NEMO. 
     516Their value is written to and read from the domain configuration file and 
     517they should be treated as fixed parameters for a particular configuration. 
     518They are namelist options for the \texttt{DOMAINcfg} tool that can be used to 
     519build the configuration file and serve both to provide a record of the choices made whilst 
     520building the configuration and to trigger appropriate code blocks within \NEMO. 
     521These values should not be altered in the \np{cn_domcfg}{cn\_domcfg} file. 
     522 
     523\medskip 
     524The decision on these choices must be made when the \np{cn_domcfg}{cn\_domcfg} file is constructed. 
     525Three main choices are offered (\autoref{fig:DOM_z_zps_s_sps}a-c): 
    308526 
    309527\begin{itemize} 
    310 \item 
    311   Geographic position: 
    312   longitude with \texttt{glamt}, \texttt{glamu}, \texttt{glamv}, \texttt{glamf} and 
    313   latitude  with \texttt{gphit}, \texttt{gphiu}, \texttt{gphiv}, \texttt{gphif} 
    314   (all respectively at T, U, V and F point) 
    315 \item 
    316   Coriolis parameter (if domain not on the sphere): \texttt{ff\_f} and \texttt{ff\_t} 
    317   (at T and F point) 
    318 \item 
    319   Scale factors: 
    320   \texttt{e1t}, \texttt{e1u}, \texttt{e1v} and \texttt{e1f} (on i direction), 
    321   \texttt{e2t}, \texttt{e2u}, \texttt{e2v} and \texttt{e2f} (on j direction) and 
    322   \texttt{ie1e2u\_v}, \texttt{e1e2u}, \texttt{e1e2v}. \\ 
    323   \texttt{e1e2u}, \texttt{e1e2v} are u and v surfaces (if gridsize reduction in some straits),  
    324   \texttt{ie1e2u\_v} is to flag set u and v surfaces are neither read nor computed. 
     528\item $z$-coordinate with full step bathymetry (\np[=.true.]{ln_zco}{ln\_zco}), 
     529\item $z$-coordinate with partial step ($zps$) bathymetry (\np[=.true.]{ln_zps}{ln\_zps}), 
     530\item Generalized, $s$-coordinate (\np[=.true.]{ln_sco}{ln\_sco}). 
    325531\end{itemize} 
    326   
    327 These fields can be read in an domain input file which name is setted in \np{cn\_domcfg} parameter specified in 
    328 \ngn{namcfg}. 
    329  
    330 \nlst{namcfg} 
    331  
    332 Or they can be defined in an analytical way in \path{MY_SRC} directory of the configuration. 
    333 For Reference Configurations of NEMO input domain files are supplied by NEMO System Team. 
    334 For analytical definition of input fields two routines are supplied: \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}. 
    335 They are an example of GYRE configuration parameters, and they are available in \path{src/OCE/USR} directory, 
    336 they provide the horizontal and vertical mesh. 
    337 % ------------------------------------------------------------------------------------------------------------- 
    338 %        Needed fields  
    339 % ------------------------------------------------------------------------------------------------------------- 
    340 %\subsection{List of needed fields to build DOMAIN} 
    341 %\label{subsec:DOM_fields_list} 
    342  
    343  
    344 % ================================================================ 
    345 % Domain: Horizontal Grid (mesh)  
    346 % ================================================================ 
    347 \section{Horizontal grid mesh (\protect\mdl{domhgr})} 
    348 \label{sec:DOM_hgr} 
    349  
    350 % ------------------------------------------------------------------------------------------------------------- 
    351 %        Coordinates and scale factors  
    352 % ------------------------------------------------------------------------------------------------------------- 
    353 \subsection{Coordinates and scale factors} 
    354 \label{subsec:DOM_hgr_coord_e} 
    355  
    356 The ocean mesh (\ie the position of all the scalar and vector points) is defined by 
    357 the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 
    358 The grid-points are located at integer or integer and a half values of as indicated in \autoref{tab:cell}. 
    359 The associated scale factors are defined using the analytical first derivative of the transformation 
    360 \autoref{eq:scale_factors}. 
    361 These definitions are done in two modules, \mdl{domhgr} and \mdl{domzgr}, 
    362 which provide the horizontal and vertical meshes, respectively. 
    363 This section deals with the horizontal mesh parameters. 
    364  
    365 In a horizontal plane, the location of all the model grid points is defined from 
    366 the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$. 
    367 The horizontal scale factors are calculated using \autoref{eq:scale_factors}. 
    368 For example, when the longitude and latitude are function of a single value 
    369 ($i$ and $j$, respectively) (geographical configuration of the mesh), 
    370 the horizontal mesh definition reduces to define the wanted $\lambda(i)$, $\varphi(j)$, 
    371 and their derivatives $\lambda'(i) \ \varphi'(j)$ in the \mdl{domhgr} module. 
    372 The model computes the grid-point positions and scale factors in the horizontal plane as follows: 
     532 
     533Additionally, hybrid combinations of the three main coordinates are available: 
     534$s-z$ or $s-zps$ coordinate (\autoref{fig:DOM_z_zps_s_sps}d and \autoref{fig:DOM_z_zps_s_sps}e). 
     535 
     536A further choice related to vertical coordinate concerns 
     537the presence (or not) of ocean cavities beneath ice shelves within the model domain. 
     538A setting of \np{ln_isfcav}{ln\_isfcav} as \forcode{.true.} indicates that 
     539the domain contains ocean cavities, 
     540otherwise the top, wet layer of the ocean will always be at the ocean surface. 
     541This option is currently only available for $z$- or $zps$-coordinates. 
     542In the latter case, partial steps are also applied at the ocean/ice shelf interface. 
     543 
     544Within the model, 
     545the arrays describing the grid point depths and vertical scale factors are 
     546three set of three dimensional arrays $(i,j,k)$ defined at 
     547\textit{before}, \textit{now} and \textit{after} time step. 
     548The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively. 
     549They are updated at each model time step. 
     550The initial fixed reference coordinate system is held in variable names with a $\_0$ suffix. 
     551When the linear free surface option is used (\np[=.true.]{ln_linssh}{ln\_linssh}), 
     552\textit{before}, \textit{now} and \textit{after} arrays are initially set to 
     553their reference counterpart and remain fixed. 
     554 
     555%% ================================================================================================= 
     556\subsubsection{Required fields} 
     557\label{sec:DOM_zgr_fields} 
     558 
     559The explicit specification of a range of fields related to the vertical grid are required for 
     560the definition of a configuration. 
     561These include: 
     562 
     563\begin{clines} 
     564int    ln_zco, ln_zps, ln_sco            /* flags for z-coord, z-coord with partial steps and s-coord    */ 
     565int    ln_isfcav                         /* flag  for ice shelf cavities                                 */ 
     566double e3t_1d, e3w_1d                    /* reference vertical scale factors at T and W points           */ 
     567double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0 /* vertical scale factors 3D coordinate at T,U,V,F and W points */ 
     568double e3uw_0, e3vw_0                    /* vertical scale factors 3D coordinate at UW and VW points     */ 
     569int    bottom_level, top_level           /* last wet T-points, 1st wet T-points (for ice shelf cavities) */ 
     570                                         /* For reference:                                               */ 
     571float  bathy_metry                       /* bathymetry used in setting top and bottom levels             */ 
     572\end{clines} 
     573 
     574This set of vertical metrics is sufficient to describe the initial depth and thickness of 
     575every gridcell in the model regardless of the choice of vertical coordinate. 
     576With constant z-levels, e3 metrics will be uniform across each horizontal level. 
     577In the partial step case each e3 at the \jp{bottom\_level} 
     578(and, possibly, \jp{top\_level} if ice cavities are present) 
     579may vary from its horizontal neighbours. 
     580And, in s-coordinates, variations can occur throughout the water column. 
     581With the non-linear free-surface, all the coordinates behave more like the s-coordinate in that 
     582variations occur throughout the water column with displacements related to the sea surface height. 
     583These variations are typically much smaller than those arising from bottom fitted coordinates. 
     584The values for vertical metrics supplied in the domain configuration file can be considered as 
     585those arising from a flat sea surface with zero elevation. 
     586 
     587The \jp{bottom\_level} and \jp{top\_level} 2D arrays define 
     588the \jp{bottom\_level} and top wet levels in each grid column. 
     589Without ice cavities, \jp{top\_level} is essentially a land mask (0 on land; 1 everywhere else). 
     590With ice cavities, \jp{top\_level} determines the first wet point below the overlying ice shelf. 
     591 
     592%% ================================================================================================= 
     593\subsubsection{Level bathymetry and mask} 
     594\label{subsec:DOM_msk} 
     595 
     596From \jp{top\_level} and \jp{bottom\_level} fields, the mask fields are defined as follows: 
    373597\begin{align*} 
    374    \lambda_t &\equiv \text{glamt} =      \lambda (i      ) 
    375   &\varphi_t &\equiv \text{gphit} =      \varphi (j      ) \\ 
    376    \lambda_u &\equiv \text{glamu} =      \lambda (i + 1/2) 
    377   &\varphi_u &\equiv \text{gphiu} =      \varphi (j      ) \\ 
    378    \lambda_v &\equiv \text{glamv} =      \lambda (i      ) 
    379   &\varphi_v &\equiv \text{gphiv} =      \varphi (j + 1/2) \\ 
    380    \lambda_f &\equiv \text{glamf} =      \lambda (i + 1/2) 
    381   &\varphi_f &\equiv \text{gphif} =      \varphi (j + 1/2) \\ 
    382    e_{1t}    &\equiv \text{e1t}   = r_a |\lambda'(i      ) \; \cos\varphi(j      ) | 
    383   &e_{2t}    &\equiv \text{e2t}   = r_a |\varphi'(j      )                         | \\ 
    384    e_{1u}    &\equiv \text{e1t}   = r_a |\lambda'(i + 1/2) \; \cos\varphi(j      ) | 
    385   &e_{2u}    &\equiv \text{e2t}   = r_a |\varphi'(j      )                         | \\ 
    386    e_{1v}    &\equiv \text{e1t}   = r_a |\lambda'(i      ) \; \cos\varphi(j + 1/2) | 
    387   &e_{2v}    &\equiv \text{e2t}   = r_a |\varphi'(j + 1/2)                         | \\ 
    388    e_{1f}    &\equiv \text{e1t}   = r_a |\lambda'(i + 1/2) \; \cos\varphi(j + 1/2) | 
    389   &e_{2f}    &\equiv \text{e2t}   = r_a |\varphi'(j + 1/2)                         | 
     598  tmask(i,j,k) &= 
     599  \begin{cases} 
     600    0 &\text{if $                             k <    top\_level(i,j)$} \\ 
     601    1 &\text{if $     bottom\_level(i,j) \leq k \leq top\_level(i,j)$} \\ 
     602    0 &\text{if $k >  bottom\_level(i,j)                            $} 
     603  \end{cases} \\ 
     604  umask(i,j,k) &= tmask(i,j,k) * tmask(i + 1,j,    k) \\ 
     605  vmask(i,j,k) &= tmask(i,j,k) * tmask(i    ,j + 1,k) \\ 
     606  fmask(i,j,k) &= tmask(i,j,k) * tmask(i + 1,j,    k) * tmask(i,j,k) * tmask(i + 1,j,    k) \\ 
     607  wmask(i,j,k) &= tmask(i,j,k) * tmask(i    ,j,k - 1) \\ 
     608  \text{with~} wmask(i,j,1) &= tmask(i,j,1) 
    390609\end{align*} 
    391 where the last letter of each computational name indicates the grid point considered and 
    392 $r_a$ is the earth radius (defined in \mdl{phycst} along with all universal constants). 
    393 Note that the horizontal position of and scale factors at $w$-points are exactly equal to those of $t$-points, 
    394 thus no specific arrays are defined at $w$-points. 
    395  
    396 Note that the definition of the scale factors 
    397 (\ie as the analytical first derivative of the transformation that 
    398 gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$) 
    399 is specific to the \NEMO model \citep{Marti_al_JGR92}. 
    400 As an example, $e_{1t}$ is defined locally at a $t$-point, 
    401 whereas many other models on a C grid choose to define such a scale factor as 
    402 the distance between the $U$-points on each side of the $t$-point. 
    403 Relying on an analytical transformation has two advantages: 
    404 firstly, there is no ambiguity in the scale factors appearing in the discrete equations, 
    405 since they are first introduced in the continuous equations; 
    406 secondly, analytical transformations encourage good practice by the definition of smoothly varying grids 
    407 (rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{Treguier1996}. 
    408 An example of the effect of such a choice is shown in \autoref{fig:zgr_e3}. 
    409 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    410 \begin{figure}[!t] 
    411   \begin{center} 
    412     \includegraphics[]{Fig_zgr_e3} 
    413     \caption{ 
    414       \protect\label{fig:zgr_e3} 
    415       Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical, 
    416       and (b) analytically derived grid-point position and scale factors. 
    417       For both grids here, the same $w$-point depth has been chosen but 
    418       in (a) the $t$-points are set half way between $w$-points while 
    419       in (b) they are defined from an analytical function: 
    420       $z(k) = 5 \, (k - 1/2)^3 - 45 \, (k - 1/2)^2 + 140 \, (k - 1/2) - 150$. 
    421       Note the resulting difference between the value of the grid-size $\Delta_k$ and 
    422       those of the scale factor $e_k$. 
    423     } 
    424   \end{center} 
    425 \end{figure} 
    426 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    427  
    428 % ------------------------------------------------------------------------------------------------------------- 
    429 %        Choice of horizontal grid 
    430 % ------------------------------------------------------------------------------------------------------------- 
    431 \subsection{Choice of horizontal grid} 
    432 \label{subsec:DOM_hgr_msh_choice} 
    433  
    434 % ------------------------------------------------------------------------------------------------------------- 
    435 %        Grid files 
    436 % ------------------------------------------------------------------------------------------------------------- 
    437 \subsection{Output grid files} 
    438 \label{subsec:DOM_hgr_files} 
    439  
    440 All the arrays relating to a particular ocean model configuration (grid-point position, scale factors, masks) 
    441 can be saved in files if \np{nn\_msh} $\not = 0$ (namelist variable in \ngn{namdom}). 
    442 This can be particularly useful for plots and off-line diagnostics. 
    443 In some cases, the user may choose to make a local modification of a scale factor in the code. 
    444 This is the case in global configurations when restricting the width of a specific strait 
    445 (usually a one-grid-point strait that happens to be too wide due to insufficient model resolution). 
    446 An example is Gibraltar Strait in the ORCA2 configuration. 
    447 When such modifications are done, 
    448 the output grid written when \np{nn\_msh} $\not = 0$ is no more equal to the input grid. 
    449  
    450 % ================================================================ 
    451 % Domain: Vertical Grid (domzgr) 
    452 % ================================================================ 
    453 \section{Vertical grid (\protect\mdl{domzgr})} 
    454 \label{sec:DOM_zgr} 
    455 %-----------------------------------------nam_zgr & namdom------------------------------------------- 
    456 % 
    457 %\nlst{namzgr}  
    458  
    459 \nlst{namdom}  
    460 %------------------------------------------------------------------------------------------------------------- 
    461  
    462 Variables are defined through the \ngn{namzgr} and \ngn{namdom} namelists. 
    463 In the vertical, the model mesh is determined by four things:  
    464 (1) the bathymetry given in meters;  
    465 (2) the number of levels of the model (\jp{jpk});  
    466 (3) the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and 
    467 (4) the masking system, \ie the number of wet model levels at each  
    468 $(i,j)$ column of points. 
    469  
    470 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    471 \begin{figure}[!tb] 
    472   \begin{center} 
    473     \includegraphics[]{Fig_z_zps_s_sps} 
    474     \caption{ 
    475       \protect\label{fig:z_zps_s_sps} 
    476       The ocean bottom as seen by the model: 
    477       (a) $z$-coordinate with full step, 
    478       (b) $z$-coordinate with partial step, 
    479       (c) $s$-coordinate: terrain following representation, 
    480       (d) hybrid $s-z$ coordinate, 
    481       (e) hybrid $s-z$ coordinate with partial step, and 
    482       (f) same as (e) but in the non-linear free surface (\protect\np{ln\_linssh}~\forcode{= .false.}). 
    483       Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e). 
    484     } 
    485   \end{center} 
    486 \end{figure} 
    487 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    488  
    489 The choice of a vertical coordinate, even if it is made through \ngn{namzgr} namelist parameters,  
    490 must be done once of all at the beginning of an experiment. 
    491 It is not intended as an option which can be enabled or disabled in the middle of an experiment. 
    492 Three main choices are offered (\autoref{fig:z_zps_s_sps}): 
    493 $z$-coordinate with full step bathymetry (\np{ln\_zco}~\forcode{= .true.}), 
    494 $z$-coordinate with partial step bathymetry (\np{ln\_zps}~\forcode{= .true.}), 
    495 or generalized, $s$-coordinate (\np{ln\_sco}~\forcode{= .true.}). 
    496 Hybridation of the three main coordinates are available: 
    497 $s-z$ or $s-zps$ coordinate (\autoref{fig:z_zps_s_sps} and \autoref{fig:z_zps_s_sps}). 
    498 By default a non-linear free surface is used: the coordinate follow the time-variation of the free surface so that 
    499 the transformation is time dependent: $z(i,j,k,t)$ (\autoref{fig:z_zps_s_sps}). 
    500 When a linear free surface is assumed (\np{ln\_linssh}~\forcode{= .true.}), 
    501 the vertical coordinate are fixed in time, but the seawater can move up and down across the $z_0$ surface 
    502 (in other words, the top of the ocean in not a rigid-lid). 
    503 The last choice in terms of vertical coordinate concerns the presence (or not) in 
    504 the model domain of ocean cavities beneath ice shelves. 
    505 Setting \np{ln\_isfcav} to true allows to manage ocean cavities, otherwise they are filled in. 
    506 This option is currently only available in $z$- or $zps$-coordinate, 
    507 and partial step are also applied at the ocean/ice shelf interface. 
    508  
    509 Contrary to the horizontal grid, the vertical grid is computed in the code and no provision is made for 
    510 reading it from a file. 
    511 The only input file is the bathymetry (in meters) (\ifile{bathy\_meter}) 
    512 \footnote{ 
    513   N.B. in full step $z$-coordinate, a \ifile{bathy\_level} file can replace the \ifile{bathy\_meter} file, 
    514   so that the computation of the number of wet ocean point in each water column is by-passed}. 
    515 If \np{ln\_isfcav}~\forcode{= .true.}, an extra file input file (\ifile{isf\_draft\_meter}) describing 
    516 the ice shelf draft (in meters) is needed. 
    517  
    518 After reading the bathymetry, the algorithm for vertical grid definition differs between the different options: 
    519 \begin{description} 
    520 \item[\textit{zco}] 
    521   set a reference coordinate transformation $z_0(k)$, and set $z(i,j,k,t) = z_0(k)$. 
    522 \item[\textit{zps}] 
    523   set a reference coordinate transformation $z_0(k)$, and calculate the thickness of the deepest level at 
    524   each $(i,j)$ point using the bathymetry, to obtain the final three-dimensional depth and scale factor arrays. 
    525 \item[\textit{sco}] 
    526   smooth the bathymetry to fulfill the hydrostatic consistency criteria and 
    527   set the three-dimensional transformation. 
    528 \item[\textit{s-z} and \textit{s-zps}] 
    529   smooth the bathymetry to fulfill the hydrostatic consistency criteria and 
    530   set the three-dimensional transformation $z(i,j,k)$, 
    531   and possibly introduce masking of extra land points to better fit the original bathymetry file. 
    532 \end{description} 
    533 %%% 
    534 \gmcomment{   add the description of the smoothing:  envelop topography...} 
    535 %%% 
    536  
    537 Unless a linear free surface is used (\np{ln\_linssh}~\forcode{= .false.}), 
    538 the arrays describing the grid point depths and vertical scale factors are three set of 
    539 three dimensional arrays $(i,j,k)$ defined at \textit{before}, \textit{now} and \textit{after} time step. 
    540 The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively. 
    541 They are updated at each model time step using a fixed reference coordinate system which 
    542 computer names have a $\_0$ suffix. 
    543 When the linear free surface option is used (\np{ln\_linssh}~\forcode{= .true.}), \textit{before}, 
    544 \textit{now} and \textit{after} arrays are simply set one for all to their reference counterpart. 
    545  
    546 % ------------------------------------------------------------------------------------------------------------- 
    547 %        Meter Bathymetry 
    548 % ------------------------------------------------------------------------------------------------------------- 
    549 \subsection{Meter bathymetry} 
    550 \label{subsec:DOM_bathy} 
    551  
    552 Three options are possible for defining the bathymetry, according to the namelist variable \np{nn\_bathy} 
    553 (found in \ngn{namdom} namelist):  
    554 \begin{description} 
    555 \item[\np{nn\_bathy}~\forcode{= 0}]: 
    556   a flat-bottom domain is defined. 
    557   The total depth $z_w (jpk)$ is given by the coordinate transformation. 
    558   The domain can either be a closed basin or a periodic channel depending on the parameter \np{jperio}. 
    559 \item[\np{nn\_bathy}~\forcode{= -1}]: 
    560   a domain with a bump of topography one third of the domain width at the central latitude. 
    561   This is meant for the "EEL-R5" configuration, a periodic or open boundary channel with a seamount. 
    562 \item[\np{nn\_bathy}~\forcode{= 1}]: 
    563   read a bathymetry and ice shelf draft (if needed). 
    564   The \ifile{bathy\_meter} file (Netcdf format) provides the ocean depth (positive, in meters) at 
    565   each grid point of the model grid. 
    566   The bathymetry is usually built by interpolating a standard bathymetry product (\eg ETOPO2) onto 
    567   the horizontal ocean mesh. 
    568   Defining the bathymetry also defines the coastline: where the bathymetry is zero, 
    569   no model levels are defined (all levels are masked). 
    570  
    571   The \ifile{isfdraft\_meter} file (Netcdf format) provides the ice shelf draft (positive, in meters) at 
    572   each grid point of the model grid. 
    573   This file is only needed if \np{ln\_isfcav}~\forcode{= .true.}. 
    574   Defining the ice shelf draft will also define the ice shelf edge and the grounding line position. 
    575 \end{description} 
    576  
    577 When a global ocean is coupled to an atmospheric model it is better to represent all large water bodies 
    578 (\eg great lakes, Caspian sea...) even if the model resolution does not allow their communication with 
    579 the rest of the ocean. 
     610 
     611Note that, without ice shelves cavities, 
     612masks at $t-$ and $w-$points are identical with the numerical indexing used 
     613(\autoref{subsec:DOM_Num_Index}). 
     614Nevertheless, 
     615$wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface) 
     616exactly in the same way as for the bottom boundary. 
     617 
     618%% The specification of closed lateral boundaries requires that at least 
     619%% the first and last rows and columns of the \textit{mbathy} array are set to zero. 
     620%% In the particular case of an east-west cyclical boundary condition, \textit{mbathy} has its last column equal to 
     621%% the second one and its first column equal to the last but one (and so too the mask arrays) 
     622%% (see \autoref{fig:LBC_jperio}). 
     623 
     624%        Closed seas 
     625%% ================================================================================================= 
     626\subsection{Closed seas} 
     627\label{subsec:DOM_closea} 
     628 
     629When a global ocean is coupled to an atmospheric model it is better to 
     630represent all large water bodies (\eg\ Great Lakes, Caspian sea, \dots) even if 
     631the model resolution does not allow their communication with the rest of the ocean. 
    580632This is unnecessary when the ocean is forced by fixed atmospheric conditions, 
    581633so these seas can be removed from the ocean domain. 
    582 The user has the option to set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}), 
    583 but the code has to be adapted to the user's configuration. 
    584  
    585 % ------------------------------------------------------------------------------------------------------------- 
    586 %        z-coordinate  and reference coordinate transformation 
    587 % ------------------------------------------------------------------------------------------------------------- 
    588 \subsection[$Z$-coordinate (\protect\np{ln\_zco}~\forcode{= .true.}) and ref. coordinate] 
    589             {$Z$-coordinate (\protect\np{ln\_zco}~\forcode{= .true.}) and reference coordinate} 
    590 \label{subsec:DOM_zco} 
    591  
    592 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    593 \begin{figure}[!tb] 
    594   \begin{center} 
    595     \includegraphics[]{Fig_zgr} 
    596     \caption{ 
    597       \protect\label{fig:zgr} 
    598       Default vertical mesh for ORCA2: 30 ocean levels (L30). 
    599       Vertical level functions for (a) T-point depth and (b) the associated scale factor as computed from 
    600       \autoref{eq:DOM_zgr_ana_1} using \autoref{eq:DOM_zgr_coef} in $z$-coordinate. 
    601     } 
    602   \end{center} 
    603 \end{figure} 
    604 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    605  
    606 The reference coordinate transformation $z_0(k)$ defines the arrays $gdept_0$ and $gdepw_0$ for $t$- and $w$-points, 
    607 respectively. 
    608 As indicated on \autoref{fig:index_vert} \jp{jpk} is the number of $w$-levels. 
    609 $gdepw_0(1)$ is the ocean surface. 
    610 There are at most \jp{jpk}-1 $t$-points inside the ocean, 
    611 the additional $t$-point at $jk = jpk$ is below the sea floor and is not used. 
    612 The vertical location of $w$- and $t$-levels is defined from the analytic expression of the depth $z_0(k)$ whose 
    613 analytical derivative with respect to $k$ provides the vertical scale factors. 
    614 The user must provide the analytical expression of both $z_0$ and its first derivative with respect to $k$. 
    615 This is done in routine \mdl{domzgr} through statement functions, 
    616 using parameters provided in the \ngn{namcfg} namelist. 
    617  
    618 It is possible to define a simple regular vertical grid by giving zero stretching (\np{ppacr}~\forcode{= 0}). 
    619 In that case, the parameters \jp{jpk} (number of $w$-levels) and 
    620 \np{pphmax} (total ocean depth in meters) fully define the grid. 
    621  
    622 For climate-related studies it is often desirable to concentrate the vertical resolution near the ocean surface. 
    623 The following function is proposed as a standard for a $z$-coordinate (with either full or partial steps):  
    624 \begin{gather} 
    625   \label{eq:DOM_zgr_ana_1} 
    626     z_0  (k) = h_{sur} - h_0 \; k - \; h_1 \; \log  \big[ \cosh ((k - h_{th}) / h_{cr}) \big] \\ 
    627     e_3^0(k) = \lt|    - h_0      -    h_1 \; \tanh \big[        (k - h_{th}) / h_{cr}  \big] \rt| 
    628 \end{gather} 
    629 where $k = 1$ to \jp{jpk} for $w$-levels and $k = 1$ to $k = 1$ for $T-$levels. 
    630 Such an expression allows us to define a nearly uniform vertical location of levels at the ocean top and bottom with 
    631 a smooth hyperbolic tangent transition in between (\autoref{fig:zgr}). 
    632  
    633 If the ice shelf cavities are opened (\np{ln\_isfcav}~\forcode{= .true.}), the definition of $z_0$ is the same. 
    634 However, definition of $e_3^0$ at $t$- and $w$-points is respectively changed to: 
    635 \begin{equation} 
    636   \label{eq:DOM_zgr_ana_2} 
    637   \begin{split} 
    638     e_3^T(k) &= z_W (k + 1) - z_W (k    ) \\ 
    639     e_3^W(k) &= z_T (k    ) - z_T (k - 1) 
    640   \end{split} 
    641 \end{equation} 
    642 This formulation decrease the self-generated circulation into the ice shelf cavity  
    643 (which can, in extreme case, leads to blow up).\\ 
    644   
    645 The most used vertical grid for ORCA2 has $10~m$ ($500~m$) resolution in the surface (bottom) layers and 
    646 a depth which varies from 0 at the sea surface to a minimum of $-5000~m$. 
    647 This leads to the following conditions: 
    648 \begin{equation} 
    649   \label{eq:DOM_zgr_coef} 
    650   \begin{array}{ll} 
    651     e_3 (1   + 1/2) =  10. & z(1  ) =     0. \\ 
    652     e_3 (jpk - 1/2) = 500. & z(jpk) = -5000. 
    653   \end{array} 
    654 \end{equation} 
    655  
    656 With the choice of the stretching $h_{cr} = 3$ and the number of levels \jp{jpk}~$= 31$, 
    657 the four coefficients $h_{sur}$, $h_0$, $h_1$, and $h_{th}$ in 
    658 \autoref{eq:DOM_zgr_ana_2} have been determined such that 
    659 \autoref{eq:DOM_zgr_coef} is satisfied, through an optimisation procedure using a bisection method. 
    660 For the first standard ORCA2 vertical grid this led to the following values: 
    661 $h_{sur} = 4762.96$, $h_0 = 255.58, h_1 = 245.5813$, and $h_{th} = 21.43336$. 
    662 The resulting depths and scale factors as a function of the model levels are shown in 
    663 \autoref{fig:zgr} and given in \autoref{tab:orca_zgr}. 
    664 Those values correspond to the parameters \np{ppsur}, \np{ppa0}, \np{ppa1}, \np{ppkth} in \ngn{namcfg} namelist. 
    665  
    666 Rather than entering parameters $h_{sur}$, $h_0$, and $h_1$ directly, it is possible to recalculate them. 
    667 In that case the user sets \np{ppsur}~$=$~\np{ppa0}~$=$~\np{ppa1}~$= 999999$., 
    668 in \ngn{namcfg} namelist, and specifies instead the four following parameters: 
    669 \begin{itemize} 
    670 \item 
    671   \np{ppacr}~$= h_{cr}$: stretching factor (nondimensional). 
    672   The larger \np{ppacr}, the smaller the stretching. 
    673   Values from $3$ to $10$ are usual. 
    674 \item 
    675   \np{ppkth}~$= h_{th}$: is approximately the model level at which maximum stretching occurs 
    676   (nondimensional, usually of order 1/2 or 2/3 of \jp{jpk}) 
    677 \item 
    678   \np{ppdzmin}: minimum thickness for the top layer (in meters). 
    679 \item 
    680   \np{pphmax}: total depth of the ocean (meters). 
    681 \end{itemize} 
    682 As an example, for the $45$ layers used in the DRAKKAR configuration those parameters are: 
    683 \jp{jpk}~$= 46$, \np{ppacr}~$= 9$, \np{ppkth}~$= 23.563$, \np{ppdzmin}~$= 6~m$, \np{pphmax}~$= 5750~m$. 
    684  
    685 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    686 \begin{table} 
    687   \begin{center} 
    688     \begin{tabular}{c||r|r|r|r} 
    689       \hline 
    690       \textbf{LEVEL} & \textbf{gdept\_1d} & \textbf{gdepw\_1d} & \textbf{e3t\_1d } & \textbf{e3w\_1d} \\ 
    691       \hline 
    692       1              & \textbf{     5.00} &               0.00 & \textbf{   10.00} &            10.00 \\ 
    693       \hline 
    694       2              & \textbf{    15.00} &              10.00 & \textbf{   10.00} &            10.00 \\ 
    695       \hline 
    696       3              & \textbf{    25.00} &              20.00 & \textbf{   10.00} &            10.00 \\ 
    697       \hline 
    698       4              & \textbf{    35.01} &              30.00 & \textbf{   10.01} &            10.00 \\ 
    699       \hline 
    700       5              & \textbf{    45.01} &              40.01 & \textbf{   10.01} &            10.01 \\ 
    701       \hline 
    702       6              & \textbf{    55.03} &              50.02 & \textbf{   10.02} &            10.02 \\ 
    703       \hline 
    704       7              & \textbf{    65.06} &              60.04 & \textbf{   10.04} &            10.03 \\ 
    705       \hline 
    706       8              & \textbf{    75.13} &              70.09 & \textbf{   10.09} &            10.06 \\ 
    707       \hline 
    708       9              & \textbf{    85.25} &              80.18 & \textbf{   10.17} &            10.12 \\ 
    709       \hline 
    710       10             & \textbf{    95.49} &              90.35 & \textbf{   10.33} &            10.24 \\ 
    711       \hline 
    712       11             & \textbf{   105.97} &             100.69 & \textbf{   10.65} &            10.47 \\ 
    713       \hline 
    714       12             & \textbf{   116.90} &             111.36 & \textbf{   11.27} &            10.91 \\ 
    715       \hline 
    716       13             & \textbf{   128.70} &             122.65 & \textbf{   12.47} &            11.77 \\ 
    717       \hline 
    718       14             & \textbf{   142.20} &             135.16 & \textbf{   14.78} &            13.43 \\ 
    719       \hline 
    720       15             & \textbf{   158.96} &             150.03 & \textbf{   19.23} &            16.65 \\ 
    721       \hline 
    722       16             & \textbf{   181.96} &             169.42 & \textbf{   27.66} &            22.78 \\ 
    723       \hline 
    724       17             & \textbf{   216.65} &             197.37 & \textbf{   43.26} &            34.30 \\ 
    725       \hline 
    726       18             & \textbf{   272.48} &             241.13 & \textbf{   70.88} &            55.21 \\ 
    727       \hline 
    728       19             & \textbf{   364.30} &             312.74 & \textbf{  116.11} &            90.99 \\ 
    729       \hline 
    730       20             & \textbf{   511.53} &             429.72 & \textbf{  181.55} &           146.43 \\ 
    731       \hline 
    732       21             & \textbf{   732.20} &             611.89 & \textbf{  261.03} &           220.35 \\ 
    733       \hline 
    734       22             & \textbf{  1033.22} &             872.87 & \textbf{  339.39} &           301.42 \\ 
    735       \hline 
    736       23             & \textbf{  1405.70} &            1211.59 & \textbf{  402.26} &           373.31 \\ 
    737       \hline 
    738       24             & \textbf{  1830.89} &            1612.98 & \textbf{  444.87} &           426.00 \\ 
    739       \hline 
    740       25             & \textbf{  2289.77} &            2057.13 & \textbf{  470.55} &           459.47 \\ 
    741       \hline 
    742       26             & \textbf{  2768.24} &            2527.22 & \textbf{  484.95} &           478.83 \\ 
    743       \hline 
    744       27             & \textbf{  3257.48} &            3011.90 & \textbf{  492.70} &           489.44 \\ 
    745       \hline 
    746       28             & \textbf{  3752.44} &            3504.46 & \textbf{  496.78} &           495.07 \\ 
    747       \hline 
    748       29             & \textbf{  4250.40} &            4001.16 & \textbf{  498.90} &           498.02 \\ 
    749       \hline 
    750       30             & \textbf{  4749.91} &            4500.02 & \textbf{  500.00} &           499.54 \\ 
    751       \hline 
    752       31             & \textbf{  5250.23} &            5000.00 & \textbf{  500.56} &           500.33 \\ 
    753       \hline 
    754     \end{tabular} 
    755   \end{center} 
    756   \caption{ 
    757     \protect\label{tab:orca_zgr} 
    758     Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration as computed from 
    759     \autoref{eq:DOM_zgr_ana_2} using the coefficients given in \autoref{eq:DOM_zgr_coef} 
    760   } 
    761 \end{table} 
    762 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    763  
    764 % ------------------------------------------------------------------------------------------------------------- 
    765 %        z-coordinate with partial step 
    766 % ------------------------------------------------------------------------------------------------------------- 
    767 \subsection{$Z$-coordinate with partial step (\protect\np{ln\_zps}~\forcode{= .true.})} 
    768 \label{subsec:DOM_zps} 
    769 %--------------------------------------------namdom------------------------------------------------------- 
    770  
    771 \nlst{namdom}  
    772 %-------------------------------------------------------------------------------------------------------------- 
    773  
    774 In $z$-coordinate partial step, 
    775 the depths of the model levels are defined by the reference analytical function $z_0(k)$ as described in 
    776 the previous section, \textit{except} in the bottom layer. 
    777 The thickness of the bottom layer is allowed to vary as a function of geographical location $(\lambda,\varphi)$ to 
    778 allow a better representation of the bathymetry, especially in the case of small slopes 
    779 (where the bathymetry varies by less than one level thickness from one grid point to the next). 
    780 The reference layer thicknesses $e_{3t}^0$ have been defined in the absence of bathymetry. 
    781 With partial steps, layers from 1 to \jp{jpk}-2 can have a thickness smaller than $e_{3t}(jk)$. 
    782 The model deepest layer (\jp{jpk}-1) is allowed to have either a smaller or larger thickness than $e_{3t}(jpk)$: 
    783 the maximum thickness allowed is $2*e_{3t}(jpk - 1)$. 
    784 This has to be kept in mind when specifying values in \ngn{namdom} namelist, 
    785 as the maximum depth \np{pphmax} in partial steps: 
    786 for example, with \np{pphmax}~$= 5750~m$ for the DRAKKAR 45 layer grid, 
    787 the maximum ocean depth allowed is actually $6000~m$ (the default thickness $e_{3t}(jpk - 1)$ being $250~m$). 
    788 Two variables in the namdom namelist are used to define the partial step vertical grid. 
    789 The mimimum water thickness (in meters) allowed for a cell partially filled with bathymetry at level jk is 
    790 the minimum of \np{rn\_e3zps\_min} (thickness in meters, usually $20~m$) or $e_{3t}(jk)*$\np{rn\_e3zps\_rat} 
    791 (a fraction, usually 10\%, of the default thickness $e_{3t}(jk)$). 
    792  
    793 \gmcomment{ \colorbox{yellow}{Add a figure here of pstep especially at last ocean level }  } 
    794  
    795 % ------------------------------------------------------------------------------------------------------------- 
    796 %        s-coordinate 
    797 % ------------------------------------------------------------------------------------------------------------- 
    798 \subsection{$S$-coordinate (\protect\np{ln\_sco}~\forcode{= .true.})} 
    799 \label{subsec:DOM_sco} 
    800 %------------------------------------------nam_zgr_sco--------------------------------------------------- 
    801 % 
    802 %\nlst{namzgr_sco}  
    803 %-------------------------------------------------------------------------------------------------------------- 
    804 Options are defined in \ngn{namzgr\_sco}. 
    805 In $s$-coordinate (\np{ln\_sco}~\forcode{= .true.}), the depth and thickness of the model levels are defined from 
    806 the product of a depth field and either a stretching function or its derivative, respectively: 
    807  
    808 \begin{align*} 
    809   % \label{eq:DOM_sco_ana} 
    810   z(k)   &= h(i,j) \; z_0 (k) \\ 
    811   e_3(k) &= h(i,j) \; z_0'(k) 
    812 \end{align*} 
    813  
    814 where $h$ is the depth of the last $w$-level ($z_0(k)$) defined at the $t$-point location in the horizontal and 
    815 $z_0(k)$ is a function which varies from $0$ at the sea surface to $1$ at the ocean bottom. 
    816 The depth field $h$ is not necessary the ocean depth, 
    817 since a mixed step-like and bottom-following representation of the topography can be used 
    818 (\autoref{fig:z_zps_s_sps}) or an envelop bathymetry can be defined (\autoref{fig:z_zps_s_sps}). 
    819 The namelist parameter \np{rn\_rmax} determines the slope at which 
    820 the terrain-following coordinate intersects the sea bed and becomes a pseudo z-coordinate. 
    821 The coordinate can also be hybridised by specifying \np{rn\_sbot\_min} and \np{rn\_sbot\_max} as 
    822 the minimum and maximum depths at which the terrain-following vertical coordinate is calculated. 
    823  
    824 Options for stretching the coordinate are provided as examples, 
    825 but care must be taken to ensure that the vertical stretch used is appropriate for the application. 
    826  
    827 The original default NEMO s-coordinate stretching is available if neither of the other options are specified as true 
    828 (\np{ln\_s\_SH94}~\forcode{= .false.} and \np{ln\_s\_SF12}~\forcode{= .false.}). 
    829 This uses a depth independent $\tanh$ function for the stretching \citep{Madec_al_JPO96}: 
    830  
    831 \[ 
    832   z = s_{min} + C (s) (H - s_{min}) 
    833   % \label{eq:SH94_1} 
    834 \] 
    835  
    836 where $s_{min}$ is the depth at which the $s$-coordinate stretching starts and 
    837 allows a $z$-coordinate to placed on top of the stretched coordinate, 
    838 and $z$ is the depth (negative down from the asea surface). 
    839 \begin{gather*} 
    840   s = - \frac{k}{n - 1} \quad \text{and} \quad 0 \leq k \leq n - 1 
    841   % \label{eq:DOM_s} 
    842  \\ 
    843   % \label{eq:DOM_sco_function} 
    844   C(s) = \frac{[\tanh(\theta \, (s + b)) - \tanh(\theta \, b)]}{2 \; \sinh(\theta)} 
    845 \end{gather*} 
    846  
    847 A stretching function, 
    848 modified from the commonly used \citet{Song_Haidvogel_JCP94} stretching (\np{ln\_s\_SH94}~\forcode{= .true.}), 
    849 is also available and is more commonly used for shelf seas modelling: 
    850  
    851 \[ 
    852   C(s) =   (1 - b) \frac{\sinh(\theta s)}{\sinh(\theta)} 
    853          + b       \frac{\tanh \lt[ \theta \lt(s + \frac{1}{2} \rt) \rt] -   \tanh \lt( \frac{\theta}{2} \rt)} 
    854                         {                                                  2 \tanh \lt( \frac{\theta}{2} \rt)} 
    855   % \label{eq:SH94_2} 
    856 \] 
    857  
    858 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    859 \begin{figure}[!ht] 
    860   \begin{center} 
    861     \includegraphics[]{Fig_sco_function} 
    862     \caption{ 
    863       \protect\label{fig:sco_function} 
    864       Examples of the stretching function applied to a seamount; 
    865       from left to right: surface, surface and bottom, and bottom intensified resolutions 
    866     } 
    867   \end{center} 
    868 \end{figure} 
    869 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    870  
    871 where $H_c$ is the critical depth (\np{rn\_hc}) at which the coordinate transitions from pure $\sigma$ to 
    872 the stretched coordinate, and $\theta$ (\np{rn\_theta}) and $b$ (\np{rn\_bb}) are the surface and 
    873 bottom control parameters such that $0 \leqslant \theta \leqslant 20$, and $0 \leqslant b \leqslant 1$. 
    874 $b$ has been designed to allow surface and/or bottom increase of the vertical resolution 
    875 (\autoref{fig:sco_function}). 
    876  
    877 Another example has been provided at version 3.5 (\np{ln\_s\_SF12}) that allows a fixed surface resolution in 
    878 an analytical terrain-following stretching \citet{Siddorn_Furner_OM12}. 
    879 In this case the a stretching function $\gamma$ is defined such that: 
    880  
    881 \begin{equation} 
    882   z = - \gamma h \quad \text{with} \quad 0 \leq \gamma \leq 1 
    883   % \label{eq:z} 
    884 \end{equation} 
    885  
    886 The function is defined with respect to $\sigma$, the unstretched terrain-following coordinate: 
    887  
    888 \begin{gather*} 
    889   % \label{eq:DOM_gamma_deriv} 
    890   \gamma =   A \lt( \sigma   - \frac{1}{2} (\sigma^2     + f (\sigma)) \rt) 
    891            + B \lt( \sigma^3 - f           (\sigma) \rt) + f (\sigma)       \\ 
    892   \intertext{Where:} 
    893   % \label{eq:DOM_gamma} 
    894   f(\sigma) = (\alpha + 2) \sigma^{\alpha + 1} - (\alpha + 1) \sigma^{\alpha + 2} 
    895   \quad \text{and} \quad \sigma = \frac{k}{n - 1} 
    896 \end{gather*} 
    897  
    898 This gives an analytical stretching of $\sigma$ that is solvable in $A$ and $B$ as a function of 
    899 the user prescribed stretching parameter $\alpha$ (\np{rn\_alpha}) that stretches towards 
    900 the surface ($\alpha > 1.0$) or the bottom ($\alpha < 1.0$) and 
    901 user prescribed surface (\np{rn\_zs}) and bottom depths. 
    902 The bottom cell depth in this example is given as a function of water depth: 
    903  
    904 \[ 
    905   % \label{eq:DOM_zb} 
    906   Z_b = h a + b 
    907 \] 
    908  
    909 where the namelist parameters \np{rn\_zb\_a} and \np{rn\_zb\_b} are $a$ and $b$ respectively. 
    910  
    911 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    912 \begin{figure}[!ht] 
    913   \includegraphics[]{Fig_DOM_compare_coordinates_surface} 
    914   \caption{ 
    915     A comparison of the \citet{Song_Haidvogel_JCP94} $S$-coordinate (solid lines), 
    916     a 50 level $Z$-coordinate (contoured surfaces) and 
    917     the \citet{Siddorn_Furner_OM12} $S$-coordinate (dashed lines) in the surface $100~m$ for 
    918     a idealised bathymetry that goes from $50~m$ to $5500~m$ depth. 
    919     For clarity every third coordinate surface is shown. 
    920   } 
    921   \label{fig:fig_compare_coordinates_surface} 
    922 \end{figure} 
    923  % >>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    924  
    925 This gives a smooth analytical stretching in computational space that is constrained to 
    926 given specified surface and bottom grid cell thicknesses in real space. 
    927 This is not to be confused with the hybrid schemes that 
    928 superimpose geopotential coordinates on terrain following coordinates thus 
    929 creating a non-analytical vertical coordinate that 
    930 therefore may suffer from large gradients in the vertical resolutions. 
    931 This stretching is less straightforward to implement than the \citet{Song_Haidvogel_JCP94} stretching, 
    932 but has the advantage of resolving diurnal processes in deep water and has generally flatter slopes. 
    933  
    934 As with the \citet{Song_Haidvogel_JCP94} stretching the stretch is only applied at depths greater than 
    935 the critical depth $h_c$. 
    936 In this example two options are available in depths shallower than $h_c$, 
    937 with pure sigma being applied if the \np{ln\_sigcrit} is true and pure z-coordinates if it is false 
    938 (the z-coordinate being equal to the depths of the stretched coordinate at $h_c$). 
    939  
    940 Minimising the horizontal slope of the vertical coordinate is important in terrain-following systems as 
    941 large slopes lead to hydrostatic consistency. 
    942 A hydrostatic consistency parameter diagnostic following \citet{Haney1991} has been implemented, 
    943 and is output as part of the model mesh file at the start of the run. 
    944  
    945 % ------------------------------------------------------------------------------------------------------------- 
    946 %        z*- or s*-coordinate 
    947 % ------------------------------------------------------------------------------------------------------------- 
    948 \subsection{\zstar- or \sstar-coordinate (\protect\np{ln\_linssh}~\forcode{= .false.})} 
    949 \label{subsec:DOM_zgr_star} 
    950  
    951 This option is described in the Report by Levier \textit{et al.} (2007), available on the \NEMO web site. 
    952  
    953 %gm% key advantage: minimise the diffusion/dispertion associated with advection in response to high frequency surface disturbances 
    954  
    955 % ------------------------------------------------------------------------------------------------------------- 
    956 %        level bathymetry and mask  
    957 % ------------------------------------------------------------------------------------------------------------- 
    958 \subsection{Level bathymetry and mask} 
    959 \label{subsec:DOM_msk} 
    960  
    961 Whatever the vertical coordinate used, the model offers the possibility of representing the bottom topography with 
    962 steps that follow the face of the model cells (step like topography) \citep{Madec_al_JPO96}. 
    963 The distribution of the steps in the horizontal is defined in a 2D integer array, mbathy, which 
    964 gives the number of ocean levels (\ie those that are not masked) at each $t$-point. 
    965 mbathy is computed from the meter bathymetry using the definiton of gdept as the number of $t$-points which 
    966 gdept $\leq$ bathy. 
    967  
    968 Modifications of the model bathymetry are performed in the \textit{bat\_ctl} routine (see \mdl{domzgr} module) after 
    969 mbathy is computed. 
    970 Isolated grid points that do not communicate with another ocean point at the same level are eliminated. 
    971  
    972 As for the representation of bathymetry, a 2D integer array, misfdep, is created. 
    973 misfdep defines the level of the first wet $t$-point. 
    974 All the cells between $k = 1$ and $misfdep(i,j) - 1$ are masked. 
    975 By default, $misfdep(:,:) = 1$ and no cells are masked. 
    976  
    977 In case of ice shelf cavities, modifications of the model bathymetry and ice shelf draft into  
    978 the cavities are performed in the \textit{zgr\_isf} routine. 
    979 The compatibility between ice shelf draft and bathymetry is checked. 
    980 All the locations where the isf cavity is thinnest than \np{rn\_isfhmin} meters are grounded (\ie masked). 
    981 If only one cell on the water column is opened at $t$-, $u$- or $v$-points, 
    982 the bathymetry or the ice shelf draft is dug to fit this constrain. 
    983 If the incompatibility is too strong (need to dig more than 1 cell), the cell is masked. 
    984  
    985 From the \textit{mbathy} and \textit{misfdep} array, the mask fields are defined as follows: 
    986 \begin{alignat*}{2} 
    987   tmask(i,j,k) &= &  & 
    988     \begin{cases} 
    989                   0 &\text{if $                  k  <    misfdep(i,j)$} \\ 
    990                   1 &\text{if $misfdep(i,j) \leq k \leq   mbathy(i,j)$} \\ 
    991                   0 &\text{if $                  k  >     mbathy(i,j)$} 
    992     \end{cases} 
    993   \\ 
    994   umask(i,j,k) &= &  &tmask(i,j,k) * tmask(i + 1,j,    k) \\ 
    995   vmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i    ,j + 1,k) \\ 
    996   fmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i + 1,j,    k) \\ 
    997                &  &* &tmask(i,j,k) * tmask(i + 1,j,    k) \\ 
    998   wmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i    ,j,k - 1) \\ 
    999   \text{with~} wmask(i,j,1) &= & &tmask(i,j,1) 
    1000 \end{alignat*} 
    1001  
    1002 Note that, without ice shelves cavities, 
    1003 masks at $t-$ and $w-$points are identical with the numerical indexing used (\autoref{subsec:DOM_Num_Index}). 
    1004 Nevertheless, $wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface)  
    1005 exactly in the same way as for the bottom boundary. 
    1006  
    1007 The specification of closed lateral boundaries requires that at least 
    1008 the first and last rows and columns of the \textit{mbathy} array are set to zero. 
    1009 In the particular case of an east-west cyclical boundary condition, \textit{mbathy} has its last column equal to 
    1010 the second one and its first column equal to the last but one (and so too the mask arrays) 
    1011 (see \autoref{fig:LBC_jperio}). 
    1012  
    1013 % ================================================================ 
    1014 % Domain: Initial State (dtatsd & istate) 
    1015 % ================================================================ 
    1016 \section{Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})} 
    1017 \label{sec:DTA_tsd} 
    1018 %-----------------------------------------namtsd------------------------------------------- 
    1019  
    1020 \nlst{namtsd}  
    1021 %------------------------------------------------------------------------------------------ 
    1022  
    1023 Options are defined in \ngn{namtsd}. 
    1024 By default, the ocean start from rest (the velocity field is set to zero) and the initialization of temperature and 
    1025 salinity fields is controlled through the \np{ln\_tsd\_ini} namelist parameter. 
     634The user has the option to 
     635set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}) and to 
     636optionally decide on the fate of any freshwater imbalance over the area. 
     637The options are explained in \autoref{sec:MISC_closea} but 
     638it should be noted here that a successful use of these options requires 
     639appropriate mask fields to be present in the domain configuration file. 
     640Among the possibilities are: 
     641 
     642\begin{clines} 
     643int closea_mask     /* non-zero values in closed sea areas for optional masking                */ 
     644int closea_mask_rnf /* non-zero values in closed sea areas with runoff locations (precip only) */ 
     645int closea_mask_emp /* non-zero values in closed sea areas with runoff locations (total emp)   */ 
     646\end{clines} 
     647 
     648%% ================================================================================================= 
     649\subsection{Output grid files} 
     650\label{subsec:DOM_meshmask} 
     651 
     652Most of the arrays relating to a particular ocean model configuration discussed in this chapter 
     653(grid-point position, scale factors) can be saved in a file if 
     654namelist parameter \np{ln_write_cfg}{ln\_write\_cfg} (namelist \nam{cfg}{cfg}) is set to 
     655\forcode{.true.}; 
     656the output filename is set through parameter \np{cn_domcfg_out}{cn\_domcfg\_out}. 
     657This is only really useful if 
     658the fields are computed in subroutines \mdl{usrdef\_hgr} or \mdl{usrdef\_zgr} and 
     659checking or confirmation is required. 
     660 
     661Alternatively, all the arrays relating to a particular ocean model configuration 
     662(grid-point position, scale factors, depths and masks) can be saved in 
     663a file called \texttt{mesh\_mask} if 
     664namelist parameter \np{ln_meshmask}{ln\_meshmask} (namelist \nam{dom}{dom}) is set to 
     665\forcode{.true.}. 
     666This file contains additional fields that can be useful for post-processing applications. 
     667 
     668%% ================================================================================================= 
     669\section[Initial state (\textit{istate.F90} and \textit{dtatsd.F90})]{Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})} 
     670\label{sec:DOM_DTA_tsd} 
     671 
     672\begin{listing} 
     673  \nlst{namtsd} 
     674  \caption{\forcode{&namtsd}} 
     675  \label{lst:namtsd} 
     676\end{listing} 
     677 
     678Basic initial state options are defined in \nam{tsd}{tsd}. 
     679By default, the ocean starts from rest (the velocity field is set to zero) and 
     680the initialization of temperature and salinity fields is controlled through the \np{ln_tsd_init}{ln\_tsd\_init} namelist parameter. 
     681 
    1026682\begin{description} 
    1027 \item[\np{ln\_tsd\_init}~\forcode{= .true.}] 
    1028   use a T and S input files that can be given on the model grid itself or on their native input data grid. 
     683\item [{\np[=.true.]{ln_tsd_init}{ln\_tsd\_init}}] Use T and S input files that can be given on 
     684  the model grid itself or on their native input data grids. 
    1029685  In the latter case, 
    1030686  the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid 
    1031687  (see \autoref{subsec:SBC_iof}). 
    1032   The information relative to the input files are given in the \np{sn\_tem} and \np{sn\_sal} structures. 
     688  The information relating to the input files are specified in 
     689  the \np{sn_tem}{sn\_tem} and \np{sn_sal}{sn\_sal} structures. 
    1033690  The computation is done in the \mdl{dtatsd} module. 
    1034 \item[\np{ln\_tsd\_init}~\forcode{= .false.}] 
    1035   use constant salinity value of $35.5~psu$ and an analytical profile of temperature 
    1036   (typical of the tropical ocean), see \rou{istate\_t\_s} subroutine called from \mdl{istate} module. 
     691\item [{\np[=.false.]{ln_tsd_init}{ln\_tsd\_init}}] Initial values for T and S are set via 
     692  a user supplied \rou{usr\_def\_istate} routine contained in \mdl{userdef\_istate}. 
     693  The default version sets horizontally uniform T and profiles as used in the GYRE configuration 
     694  (see \autoref{sec:CFGS_gyre}). 
    1037695\end{description} 
    1038696 
    1039 \biblio 
    1040  
    1041 \pindex 
     697\subinc{\input{../../global/epilogue}} 
    1042698 
    1043699\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_DYN.tex

    r10499 r11831  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter ——— Ocean Dynamics (DYN) 
    6 % ================================================================ 
     4 
    75\chapter{Ocean Dynamics (DYN)} 
    86\label{chap:DYN} 
    97 
    10 \minitoc 
     8\thispagestyle{plain} 
     9 
     10\chaptertoc 
     11 
     12\paragraph{Changes record} ~\\ 
     13 
     14{\footnotesize 
     15  \begin{tabularx}{\textwidth}{l||X|X} 
     16    Release & Author(s) & Modifications \\ 
     17    \hline 
     18    {\em   4.0} & {\em ...} & {\em ...} \\ 
     19    {\em   3.6} & {\em ...} & {\em ...} \\ 
     20    {\em   3.4} & {\em ...} & {\em ...} \\ 
     21    {\em <=3.4} & {\em ...} & {\em ...} 
     22  \end{tabularx} 
     23} 
     24 
     25\clearpage 
    1126 
    1227Using the representation described in \autoref{chap:DOM}, 
     
    3651(surface wind stress calculation using bulk formulae, estimation of mixing coefficients) 
    3752that are carried out in modules SBC, LDF and ZDF and are described in 
    38 \autoref{chap:SBC}, \autoref{chap:LDF} and \autoref{chap:ZDF}, respectively.  
     53\autoref{chap:SBC}, \autoref{chap:LDF} and \autoref{chap:ZDF}, respectively. 
    3954 
    4055In the present chapter we also describe the diagnostic equations used to compute the horizontal divergence, 
    4156curl of the velocities (\emph{divcur} module) and the vertical velocity (\emph{wzvmod} module). 
    4257 
    43 The different options available to the user are managed by namelist variables.  
    44 For term \textit{ttt} in the momentum equations, the logical namelist variables are \textit{ln\_dynttt\_xxx},  
     58The different options available to the user are managed by namelist variables. 
     59For term \textit{ttt} in the momentum equations, the logical namelist variables are \textit{ln\_dynttt\_xxx}, 
    4560where \textit{xxx} is a 3 or 4 letter acronym corresponding to each optional scheme. 
    46 If a CPP key is used for this term its name is \key{ttt}. 
     61%If a CPP key is used for this term its name is \key{ttt}. 
    4762The corresponding code can be found in the \textit{dynttt\_xxx} module in the DYN directory, 
    4863and it is usually computed in the \textit{dyn\_ttt\_xxx} subroutine. 
    4964 
    5065The user has the option of extracting and outputting each tendency term from the 3D momentum equations 
    51 (\key{trddyn} defined), as described in \autoref{chap:MISC}. 
    52 Furthermore, the tendency terms associated with the 2D barotropic vorticity balance (when \key{trdvor} is defined) 
     66(\texttt{trddyn?} defined), as described in \autoref{chap:MISC}. 
     67Furthermore, the tendency terms associated with the 2D barotropic vorticity balance (when \texttt{trdvor?} is defined) 
    5368can be derived from the 3D terms. 
    54 %%% 
    55 \gmcomment{STEVEN: not quite sure I've got the sense of the last sentence. does  
    56 MISC correspond to "extracting tendency terms" or "vorticity balance"?} 
    57  
    58 % ================================================================ 
    59 % Sea Surface Height evolution & Diagnostics variables 
    60 % ================================================================ 
     69\cmtgm{STEVEN: not quite sure I've got the sense of the last sentence. 
     70  Does MISC correspond to "extracting tendency terms" or "vorticity balance"?} 
     71 
     72%% ================================================================================================= 
    6173\section{Sea surface height and diagnostic variables ($\eta$, $\zeta$, $\chi$, $w$)} 
    6274\label{sec:DYN_divcur_wzv} 
    6375 
    64 %-------------------------------------------------------------------------------------------------------------- 
    65 %           Horizontal divergence and relative vorticity 
    66 %-------------------------------------------------------------------------------------------------------------- 
    67 \subsection{Horizontal divergence and relative vorticity (\protect\mdl{divcur})} 
     76%% ================================================================================================= 
     77\subsection[Horizontal divergence and relative vorticity (\textit{divcur.F90})]{Horizontal divergence and relative vorticity (\protect\mdl{divcur})} 
    6878\label{subsec:DYN_divcur} 
    6979 
    70 The vorticity is defined at an $f$-point (\ie corner point) as follows: 
    71 \begin{equation} 
    72   \label{eq:divcur_cur} 
     80The vorticity is defined at an $f$-point (\ie\ corner point) as follows: 
     81\begin{equation} 
     82  \label{eq:DYN_divcur_cur} 
    7383  \zeta =\frac{1}{e_{1f}\,e_{2f} }\left( {\;\delta_{i+1/2} \left[ {e_{2v}\;v} \right] 
    7484      -\delta_{j+1/2} \left[ {e_{1u}\;u} \right]\;} \right) 
    75 \end{equation}  
     85\end{equation} 
    7686 
    7787The horizontal divergence is defined at a $T$-point. 
    7888It is given by: 
    7989\[ 
    80   % \label{eq:divcur_div} 
     90  % \label{eq:DYN_divcur_div} 
    8191  \chi =\frac{1}{e_{1t}\,e_{2t}\,e_{3t} } 
    8292  \left( {\delta_i \left[ {e_{2u}\,e_{3u}\,u} \right] 
     
    96106ensure perfect restartability. 
    97107The vorticity and divergence at the \textit{now} time step are used for the computation of 
    98 the nonlinear advection and of the vertical velocity respectively.  
    99  
    100 %-------------------------------------------------------------------------------------------------------------- 
    101 %           Sea Surface Height evolution 
    102 %-------------------------------------------------------------------------------------------------------------- 
    103 \subsection{Horizontal divergence and relative vorticity (\protect\mdl{sshwzv})} 
     108the nonlinear advection and of the vertical velocity respectively. 
     109 
     110%% ================================================================================================= 
     111\subsection[Horizontal divergence and relative vorticity (\textit{sshwzv.F90})]{Horizontal divergence and relative vorticity (\protect\mdl{sshwzv})} 
    104112\label{subsec:DYN_sshwzv} 
    105113 
    106114The sea surface height is given by: 
    107115\begin{equation} 
    108   \label{eq:dynspg_ssh} 
     116  \label{eq:DYN_spg_ssh} 
    109117  \begin{aligned} 
    110118    \frac{\partial \eta }{\partial t} 
     
    115123  \end{aligned} 
    116124\end{equation} 
    117 where \textit{emp} is the surface freshwater budget (evaporation minus precipitation),  
     125where \textit{emp} is the surface freshwater budget (evaporation minus precipitation), 
    118126expressed in Kg/m$^2$/s (which is equal to mm/s), 
    119127and $\rho_w$=1,035~Kg/m$^3$ is the reference density of sea water (Boussinesq approximation). 
    120128If river runoff is expressed as a surface freshwater flux (see \autoref{chap:SBC}) then 
    121 \textit{emp} can be written as the evaporation minus precipitation, minus the river runoff.  
     129\textit{emp} can be written as the evaporation minus precipitation, minus the river runoff. 
    122130The sea-surface height is evaluated using exactly the same time stepping scheme as 
    123 the tracer equation \autoref{eq:tra_nxt}: 
     131the tracer equation \autoref{eq:TRA_nxt}: 
    124132a leapfrog scheme in combination with an Asselin time filter, 
    125 \ie the velocity appearing in \autoref{eq:dynspg_ssh} is centred in time (\textit{now} velocity). 
     133\ie\ the velocity appearing in \autoref{eq:DYN_spg_ssh} is centred in time (\textit{now} velocity). 
    126134This is of paramount importance. 
    127135Replacing $T$ by the number $1$ in the tracer equation and summing over the water column must lead to 
    128136the sea surface height equation otherwise tracer content will not be conserved 
    129 \citep{Griffies_al_MWR01, Leclair_Madec_OM09}. 
     137\citep{griffies.pacanowski.ea_MWR01, leclair.madec_OM09}. 
    130138 
    131139The vertical velocity is computed by an upward integration of the horizontal divergence starting at the bottom, 
    132140taking into account the change of the thickness of the levels: 
    133141\begin{equation} 
    134   \label{eq:wzv} 
     142  \label{eq:DYN_wzv} 
    135143  \left\{ 
    136144    \begin{aligned} 
     
    142150\end{equation} 
    143151 
    144 In the case of a non-linear free surface (\key{vvl}), the top vertical velocity is $-\textit{emp}/\rho_w$,  
     152In the case of a non-linear free surface (\texttt{vvl?}), the top vertical velocity is $-\textit{emp}/\rho_w$, 
    145153as changes in the divergence of the barotropic transport are absorbed into the change of the level thicknesses, 
    146154re-orientated downward. 
    147 \gmcomment{not sure of this...  to be modified with the change in emp setting} 
    148 In the case of a linear free surface, the time derivative in \autoref{eq:wzv} disappears. 
     155\cmtgm{not sure of this...  to be modified with the change in emp setting} 
     156In the case of a linear free surface, the time derivative in \autoref{eq:DYN_wzv} disappears. 
    149157The upper boundary condition applies at a fixed level $z=0$. 
    150158The top vertical velocity is thus equal to the divergence of the barotropic transport 
    151 (\ie the first term in the right-hand-side of \autoref{eq:dynspg_ssh}). 
     159(\ie\ the first term in the right-hand-side of \autoref{eq:DYN_spg_ssh}). 
    152160 
    153161Note also that whereas the vertical velocity has the same discrete expression in $z$- and $s$-coordinates, 
    154162its physical meaning is not the same: 
    155163in the second case, $w$ is the velocity normal to the $s$-surfaces. 
    156 Note also that the $k$-axis is re-orientated downwards in the \fortran code compared to 
    157 the indexing used in the semi-discrete equations such as \autoref{eq:wzv} 
    158 (see \autoref{subsec:DOM_Num_Index_vertical}).  
    159  
    160  
    161 % ================================================================ 
    162 % Coriolis and Advection terms: vector invariant form 
    163 % ================================================================ 
     164Note also that the $k$-axis is re-orientated downwards in the \fortran\ code compared to 
     165the indexing used in the semi-discrete equations such as \autoref{eq:DYN_wzv} 
     166(see \autoref{subsec:DOM_Num_Index_vertical}). 
     167 
     168%% ================================================================================================= 
    164169\section{Coriolis and advection: vector invariant form} 
    165170\label{sec:DYN_adv_cor_vect} 
    166 %-----------------------------------------nam_dynadv---------------------------------------------------- 
    167  
    168 \nlst{namdyn_adv}  
    169 %------------------------------------------------------------------------------------------------------------- 
     171 
     172\begin{listing} 
     173  \nlst{namdyn_adv} 
     174  \caption{\forcode{&namdyn_adv}} 
     175  \label{lst:namdyn_adv} 
     176\end{listing} 
    170177 
    171178The vector invariant form of the momentum equations is the one most often used in 
    172 applications of the \NEMO ocean model. 
     179applications of the \NEMO\ ocean model. 
    173180The flux form option (see next section) has been present since version $2$. 
    174 Options are defined through the \ngn{namdyn\_adv} namelist variables Coriolis and 
     181Options are defined through the \nam{dyn_adv}{dyn\_adv} namelist variables Coriolis and 
    175182momentum advection terms are evaluated using a leapfrog scheme, 
    176 \ie the velocity appearing in these expressions is centred in time (\textit{now} velocity).  
     183\ie\ the velocity appearing in these expressions is centred in time (\textit{now} velocity). 
    177184At the lateral boundaries either free slip, no slip or partial slip boundary conditions are applied following 
    178185\autoref{chap:LBC}. 
    179186 
    180 % ------------------------------------------------------------------------------------------------------------- 
    181 %        Vorticity term  
    182 % ------------------------------------------------------------------------------------------------------------- 
    183 \subsection{Vorticity term (\protect\mdl{dynvor})} 
     187%% ================================================================================================= 
     188\subsection[Vorticity term (\textit{dynvor.F90})]{Vorticity term (\protect\mdl{dynvor})} 
    184189\label{subsec:DYN_vor} 
    185 %------------------------------------------nam_dynvor---------------------------------------------------- 
    186  
    187 \nlst{namdyn_vor}  
    188 %------------------------------------------------------------------------------------------------------------- 
    189  
    190 Options are defined through the \ngn{namdyn\_vor} namelist variables. 
    191 Four discretisations of the vorticity term (\np{ln\_dynvor\_xxx}\forcode{ = .true.}) are available: 
     190 
     191\begin{listing} 
     192  \nlst{namdyn_vor} 
     193  \caption{\forcode{&namdyn_vor}} 
     194  \label{lst:namdyn_vor} 
     195\end{listing} 
     196 
     197Options are defined through the \nam{dyn_vor}{dyn\_vor} namelist variables. 
     198Four discretisations of the vorticity term (\texttt{ln\_dynvor\_xxx}\forcode{=.true.}) are available: 
    192199conserving potential enstrophy of horizontally non-divergent flow (ENS scheme); 
    193200conserving horizontal kinetic energy (ENE scheme); 
     
    195202horizontal kinetic energy for the planetary vorticity term (MIX scheme); 
    196203or conserving both the potential enstrophy of horizontally non-divergent flow and horizontal kinetic energy 
    197 (EEN scheme) (see \autoref{subsec:C_vorEEN}). 
     204(EEN scheme) (see \autoref{subsec:INVARIANTS_vorEEN}). 
    198205In the case of ENS, ENE or MIX schemes the land sea mask may be slightly modified to ensure the consistency of 
    199 vorticity term with analytical equations (\np{ln\_dynvor\_con}\forcode{ = .true.}). 
     206vorticity term with analytical equations (\np[=.true.]{ln_dynvor_con}{ln\_dynvor\_con}). 
    200207The vorticity terms are all computed in dedicated routines that can be found in the \mdl{dynvor} module. 
    201208 
    202 %------------------------------------------------------------- 
    203209%                 enstrophy conserving scheme 
    204 %------------------------------------------------------------- 
    205 \subsubsection{Enstrophy conserving scheme (\protect\np{ln\_dynvor\_ens}\forcode{ = .true.})} 
     210%% ================================================================================================= 
     211\subsubsection[Enstrophy conserving scheme (\forcode{ln_dynvor_ens})]{Enstrophy conserving scheme (\protect\np{ln_dynvor_ens}{ln\_dynvor\_ens})} 
    206212\label{subsec:DYN_vor_ens} 
    207213 
    208214In the enstrophy conserving case (ENS scheme), 
    209215the discrete formulation of the vorticity term provides a global conservation of the enstrophy 
    210 ($ [ (\zeta +f ) / e_{3f} ]^2 $ in $s$-coordinates) for a horizontally non-divergent flow (\ie $\chi$=$0$), 
     216($ [ (\zeta +f ) / e_{3f} ]^2 $ in $s$-coordinates) for a horizontally non-divergent flow (\ie\ $\chi$=$0$), 
    211217but does not conserve the total kinetic energy. 
    212218It is given by: 
    213219\begin{equation} 
    214   \label{eq:dynvor_ens} 
     220  \label{eq:DYN_vor_ens} 
    215221  \left\{ 
    216222    \begin{aligned} 
     
    221227    \end{aligned} 
    222228  \right. 
    223 \end{equation}  
    224  
    225 %------------------------------------------------------------- 
     229\end{equation} 
     230 
    226231%                 energy conserving scheme 
    227 %------------------------------------------------------------- 
    228 \subsubsection{Energy conserving scheme (\protect\np{ln\_dynvor\_ene}\forcode{ = .true.})} 
     232%% ================================================================================================= 
     233\subsubsection[Energy conserving scheme (\forcode{ln_dynvor_ene})]{Energy conserving scheme (\protect\np{ln_dynvor_ene}{ln\_dynvor\_ene})} 
    229234\label{subsec:DYN_vor_ene} 
    230235 
     
    232237It is given by: 
    233238\begin{equation} 
    234   \label{eq:dynvor_ene} 
     239  \label{eq:DYN_vor_ene} 
    235240  \left\{ 
    236241    \begin{aligned} 
     
    241246    \end{aligned} 
    242247  \right. 
    243 \end{equation}  
    244  
    245 %------------------------------------------------------------- 
     248\end{equation} 
     249 
    246250%                 mix energy/enstrophy conserving scheme 
    247 %------------------------------------------------------------- 
    248 \subsubsection{Mixed energy/enstrophy conserving scheme (\protect\np{ln\_dynvor\_mix}\forcode{ = .true.}) } 
     251%% ================================================================================================= 
     252\subsubsection[Mixed energy/enstrophy conserving scheme (\forcode{ln_dynvor_mix})]{Mixed energy/enstrophy conserving scheme (\protect\np{ln_dynvor_mix}{ln\_dynvor\_mix})} 
    249253\label{subsec:DYN_vor_mix} 
    250254 
    251255For the mixed energy/enstrophy conserving scheme (MIX scheme), a mixture of the two previous schemes is used. 
    252 It consists of the ENS scheme (\autoref{eq:dynvor_ens}) for the relative vorticity term, 
    253 and of the ENE scheme (\autoref{eq:dynvor_ene}) applied to the planetary vorticity term. 
    254 \[ 
    255   % \label{eq:dynvor_mix} 
     256It consists of the ENS scheme (\autoref{eq:DYN_vor_ens}) for the relative vorticity term, 
     257and of the ENE scheme (\autoref{eq:DYN_vor_ene}) applied to the planetary vorticity term. 
     258\[ 
     259  % \label{eq:DYN_vor_mix} 
    256260  \left\{ { 
    257261      \begin{aligned} 
     
    268272\] 
    269273 
    270 %------------------------------------------------------------- 
    271274%                 energy and enstrophy conserving scheme 
    272 %------------------------------------------------------------- 
    273 \subsubsection{Energy and enstrophy conserving scheme (\protect\np{ln\_dynvor\_een}\forcode{ = .true.}) } 
     275%% ================================================================================================= 
     276\subsubsection[Energy and enstrophy conserving scheme (\forcode{ln_dynvor_een})]{Energy and enstrophy conserving scheme (\protect\np{ln_dynvor_een}{ln\_dynvor\_een})} 
    274277\label{subsec:DYN_vor_een} 
    275278 
     
    278281the presence of grid point oscillation structures that will be invisible to the operator. 
    279282These structures are \textit{computational modes} that will be at least partly damped by 
    280 the momentum diffusion operator (\ie the subgrid-scale advection), but not by the resolved advection term. 
     283the momentum diffusion operator (\ie\ the subgrid-scale advection), but not by the resolved advection term. 
    281284The ENS and ENE schemes therefore do not contribute to dump any grid point noise in the horizontal velocity field. 
    282285Such noise would result in more noise in the vertical velocity field, an undesirable feature. 
     
    284287$u$ and $v$ are located at different grid points, 
    285288a price worth paying to avoid a double averaging in the pressure gradient term as in the $B$-grid. 
    286 \gmcomment{ To circumvent this, Adcroft (ADD REF HERE)  
     289\cmtgm{ To circumvent this, Adcroft (ADD REF HERE) 
    287290Nevertheless, this technique strongly distort the phase and group velocity of Rossby waves....} 
    288291 
    289 A very nice solution to the problem of double averaging was proposed by \citet{Arakawa_Hsu_MWR90}. 
     292A very nice solution to the problem of double averaging was proposed by \citet{arakawa.hsu_MWR90}. 
    290293The idea is to get rid of the double averaging by considering triad combinations of vorticity. 
    291294It is noteworthy that this solution is conceptually quite similar to the one proposed by 
    292 \citep{Griffies_al_JPO98} for the discretization of the iso-neutral diffusion operator (see \autoref{apdx:C}). 
    293  
    294 The \citet{Arakawa_Hsu_MWR90} vorticity advection scheme for a single layer is modified  
    295 for spherical coordinates as described by \citet{Arakawa_Lamb_MWR81} to obtain the EEN scheme.  
    296 First consider the discrete expression of the potential vorticity, $q$, defined at an $f$-point:  
    297 \[ 
    298   % \label{eq:pot_vor} 
     295\citep{griffies.gnanadesikan.ea_JPO98} for the discretization of the iso-neutral diffusion operator (see \autoref{apdx:INVARIANTS}). 
     296 
     297The \citet{arakawa.hsu_MWR90} vorticity advection scheme for a single layer is modified 
     298for spherical coordinates as described by \citet{arakawa.lamb_MWR81} to obtain the EEN scheme. 
     299First consider the discrete expression of the potential vorticity, $q$, defined at an $f$-point: 
     300\[ 
     301  % \label{eq:DYN_pot_vor} 
    299302  q  = \frac{\zeta +f} {e_{3f} } 
    300303\] 
    301 where the relative vorticity is defined by (\autoref{eq:divcur_cur}), 
    302 the Coriolis parameter is given by $f=2 \,\Omega \;\sin \varphi _f $ and the layer thickness at $f$-points is:  
    303 \begin{equation} 
    304   \label{eq:een_e3f} 
     304where the relative vorticity is defined by (\autoref{eq:DYN_divcur_cur}), 
     305the Coriolis parameter is given by $f=2 \,\Omega \;\sin \varphi _f $ and the layer thickness at $f$-points is: 
     306\begin{equation} 
     307  \label{eq:DYN_een_e3f} 
    305308  e_{3f} = \overline{\overline {e_{3t} }} ^{\,i+1/2,j+1/2} 
    306309\end{equation} 
    307310 
    308 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    309311\begin{figure}[!ht] 
    310   \begin{center} 
    311     \includegraphics[width=0.70\textwidth]{Fig_DYN_een_triad} 
    312     \caption{ 
    313       \protect\label{fig:DYN_een_triad} 
    314       Triads used in the energy and enstrophy conserving scheme (een) for 
    315       $u$-component (upper panel) and $v$-component (lower panel). 
    316     } 
    317   \end{center} 
     312  \centering 
     313  \includegraphics[width=0.66\textwidth]{DYN_een_triad} 
     314  \caption[Triads used in the energy and enstrophy conserving scheme (EEN)]{ 
     315    Triads used in the energy and enstrophy conserving scheme (EEN) for 
     316    $u$-component (upper panel) and $v$-component (lower panel).} 
     317  \label{fig:DYN_een_triad} 
    318318\end{figure} 
    319 % >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    320  
    321 A key point in \autoref{eq:een_e3f} is how the averaging in the \textbf{i}- and \textbf{j}- directions is made.  
     319 
     320A key point in \autoref{eq:DYN_een_e3f} is how the averaging in the \textbf{i}- and \textbf{j}- directions is made. 
    322321It uses the sum of masked t-point vertical scale factor divided either by the sum of the four t-point masks 
    323 (\np{nn\_een\_e3f}\forcode{ = 1}), or just by $4$ (\np{nn\_een\_e3f}\forcode{ = .true.}). 
     322(\np[=1]{nn_een_e3f}{nn\_een\_e3f}), or just by $4$ (\np[=.true.]{nn_een_e3f}{nn\_een\_e3f}). 
    324323The latter case preserves the continuity of $e_{3f}$ when one or more of the neighbouring $e_{3t}$ tends to zero and 
    325324extends by continuity the value of $e_{3f}$ into the land areas. 
     
    327326(with a systematic reduction of $e_{3f}$ when a model level intercept the bathymetry) 
    328327that tends to reinforce the topostrophy of the flow 
    329 (\ie the tendency of the flow to follow the isobaths) \citep{Penduff_al_OS07}.  
     328(\ie\ the tendency of the flow to follow the isobaths) \citep{penduff.le-sommer.ea_OS07}. 
    330329 
    331330Next, the vorticity triads, $ {^i_j}\mathbb{Q}^{i_p}_{j_p}$ can be defined at a $T$-point as 
    332331the following triad combinations of the neighbouring potential vorticities defined at f-points 
    333 (\autoref{fig:DYN_een_triad}):  
    334 \begin{equation} 
    335   \label{eq:Q_triads} 
     332(\autoref{fig:DYN_een_triad}): 
     333\begin{equation} 
     334  \label{eq:DYN_Q_triads} 
    336335  _i^j \mathbb{Q}^{i_p}_{j_p} 
    337336  = \frac{1}{12} \ \left(   q^{i-i_p}_{j+j_p} + q^{i+j_p}_{j+i_p} + q^{i+i_p}_{j-j_p}  \right) 
    338337\end{equation} 
    339 where the indices $i_p$ and $k_p$ take the values: $i_p = -1/2$ or $1/2$ and $j_p = -1/2$ or $1/2$.  
    340  
    341 Finally, the vorticity terms are represented as:  
    342 \begin{equation} 
    343   \label{eq:dynvor_een} 
     338where the indices $i_p$ and $k_p$ take the values: $i_p = -1/2$ or $1/2$ and $j_p = -1/2$ or $1/2$. 
     339 
     340Finally, the vorticity terms are represented as: 
     341\begin{equation} 
     342  \label{eq:DYN_vor_een} 
    344343  \left\{ { 
    345344      \begin{aligned} 
     
    350349      \end{aligned} 
    351350    } \right. 
    352 \end{equation}  
     351\end{equation} 
    353352 
    354353This EEN scheme in fact combines the conservation properties of the ENS and ENE schemes. 
    355354It conserves both total energy and potential enstrophy in the limit of horizontally nondivergent flow 
    356 (\ie $\chi$=$0$) (see \autoref{subsec:C_vorEEN}).  
     355(\ie\ $\chi$=$0$) (see \autoref{subsec:INVARIANTS_vorEEN}). 
    357356Applied to a realistic ocean configuration, it has been shown that it leads to a significant reduction of 
    358 the noise in the vertical velocity field \citep{Le_Sommer_al_OM09}. 
     357the noise in the vertical velocity field \citep{le-sommer.penduff.ea_OM09}. 
    359358Furthermore, used in combination with a partial steps representation of bottom topography, 
    360359it improves the interaction between current and topography, 
    361 leading to a larger topostrophy of the flow \citep{Barnier_al_OD06, Penduff_al_OS07}.  
    362  
    363 %-------------------------------------------------------------------------------------------------------------- 
    364 %           Kinetic Energy Gradient term 
    365 %-------------------------------------------------------------------------------------------------------------- 
    366 \subsection{Kinetic energy gradient term (\protect\mdl{dynkeg})} 
     360leading to a larger topostrophy of the flow \citep{barnier.madec.ea_OD06, penduff.le-sommer.ea_OS07}. 
     361 
     362%% ================================================================================================= 
     363\subsection[Kinetic energy gradient term (\textit{dynkeg.F90})]{Kinetic energy gradient term (\protect\mdl{dynkeg})} 
    367364\label{subsec:DYN_keg} 
    368365 
    369 As demonstrated in \autoref{apdx:C}, 
     366As demonstrated in \autoref{apdx:INVARIANTS}, 
    370367there is a single discrete formulation of the kinetic energy gradient term that, 
    371368together with the formulation chosen for the vertical advection (see below), 
    372369conserves the total kinetic energy: 
    373370\[ 
    374   % \label{eq:dynkeg} 
     371  % \label{eq:DYN_keg} 
    375372  \left\{ 
    376373    \begin{aligned} 
     
    381378\] 
    382379 
    383 %-------------------------------------------------------------------------------------------------------------- 
    384 %           Vertical advection term 
    385 %-------------------------------------------------------------------------------------------------------------- 
    386 \subsection{Vertical advection term (\protect\mdl{dynzad}) } 
     380%% ================================================================================================= 
     381\subsection[Vertical advection term (\textit{dynzad.F90})]{Vertical advection term (\protect\mdl{dynzad})} 
    387382\label{subsec:DYN_zad} 
    388383 
     
    391386conserves the total kinetic energy. 
    392387Indeed, the change of KE due to the vertical advection is exactly balanced by 
    393 the change of KE due to the gradient of KE (see \autoref{apdx:C}). 
    394 \[ 
    395   % \label{eq:dynzad} 
     388the change of KE due to the gradient of KE (see \autoref{apdx:INVARIANTS}). 
     389\[ 
     390  % \label{eq:DYN_zad} 
    396391  \left\{ 
    397392    \begin{aligned} 
     
    401396  \right. 
    402397\] 
    403 When \np{ln\_dynzad\_zts}\forcode{ = .true.}, 
     398When \np[=.true.]{ln_dynzad_zts}{ln\_dynzad\_zts}, 
    404399a split-explicit time stepping with 5 sub-timesteps is used on the vertical advection term. 
    405 This option can be useful when the value of the timestep is limited by vertical advection \citep{Lemarie_OM2015}.  
     400This option can be useful when the value of the timestep is limited by vertical advection \citep{lemarie.debreu.ea_OM15}. 
    406401Note that in this case, 
    407402a similar split-explicit time stepping should be used on vertical advection of tracer to ensure a better stability, 
    408 an option which is only available with a TVD scheme (see \np{ln\_traadv\_tvd\_zts} in \autoref{subsec:TRA_adv_tvd}). 
    409  
    410  
    411 % ================================================================ 
    412 % Coriolis and Advection : flux form 
    413 % ================================================================ 
     403an option which is only available with a TVD scheme (see \np{ln_traadv_tvd_zts}{ln\_traadv\_tvd\_zts} in \autoref{subsec:TRA_adv_tvd}). 
     404 
     405%% ================================================================================================= 
    414406\section{Coriolis and advection: flux form} 
    415407\label{sec:DYN_adv_cor_flux} 
    416 %------------------------------------------nam_dynadv---------------------------------------------------- 
    417  
    418 \nlst{namdyn_adv}  
    419 %------------------------------------------------------------------------------------------------------------- 
    420  
    421 Options are defined through the \ngn{namdyn\_adv} namelist variables. 
     408 
     409Options are defined through the \nam{dyn_adv}{dyn\_adv} namelist variables. 
    422410In the flux form (as in the vector invariant form), 
    423411the Coriolis and momentum advection terms are evaluated using a leapfrog scheme, 
    424 \ie the velocity appearing in their expressions is centred in time (\textit{now} velocity). 
     412\ie\ the velocity appearing in their expressions is centred in time (\textit{now} velocity). 
    425413At the lateral boundaries either free slip, 
    426414no slip or partial slip boundary conditions are applied following \autoref{chap:LBC}. 
    427415 
    428  
    429 %-------------------------------------------------------------------------------------------------------------- 
    430 %           Coriolis plus curvature metric terms 
    431 %-------------------------------------------------------------------------------------------------------------- 
    432 \subsection{Coriolis plus curvature metric terms (\protect\mdl{dynvor}) } 
     416%% ================================================================================================= 
     417\subsection[Coriolis plus curvature metric terms (\textit{dynvor.F90})]{Coriolis plus curvature metric terms (\protect\mdl{dynvor})} 
    433418\label{subsec:DYN_cor_flux} 
    434419 
    435420In flux form, the vorticity term reduces to a Coriolis term in which the Coriolis parameter has been modified to account for the "metric" term. 
    436421This altered Coriolis parameter is thus discretised at $f$-points. 
    437 It is given by:  
     422It is given by: 
    438423\begin{multline*} 
    439   % \label{eq:dyncor_metric} 
     424  % \label{eq:DYN_cor_metric} 
    440425  f+\frac{1}{e_1 e_2 }\left( {v\frac{\partial e_2 }{\partial i}  -  u\frac{\partial e_1 }{\partial j}} \right)  \\ 
    441426  \equiv   f + \frac{1}{e_{1f} e_{2f} } \left( { \ \overline v ^{i+1/2}\delta_{i+1/2} \left[ {e_{2u} } \right] 
    442427      -  \overline u ^{j+1/2}\delta_{j+1/2} \left[ {e_{1u} } \right]  }  \ \right) 
    443 \end{multline*}  
    444  
    445 Any of the (\autoref{eq:dynvor_ens}), (\autoref{eq:dynvor_ene}) and (\autoref{eq:dynvor_een}) schemes can be used to 
     428\end{multline*} 
     429 
     430Any of the (\autoref{eq:DYN_vor_ens}), (\autoref{eq:DYN_vor_ene}) and (\autoref{eq:DYN_vor_een}) schemes can be used to 
    446431compute the product of the Coriolis parameter and the vorticity. 
    447 However, the energy-conserving scheme (\autoref{eq:dynvor_een}) has exclusively been used to date. 
    448 This term is evaluated using a leapfrog scheme, \ie the velocity is centred in time (\textit{now} velocity). 
    449  
    450 %-------------------------------------------------------------------------------------------------------------- 
    451 %           Flux form Advection term 
    452 %-------------------------------------------------------------------------------------------------------------- 
    453 \subsection{Flux form advection term (\protect\mdl{dynadv}) } 
     432However, the energy-conserving scheme (\autoref{eq:DYN_vor_een}) has exclusively been used to date. 
     433This term is evaluated using a leapfrog scheme, \ie\ the velocity is centred in time (\textit{now} velocity). 
     434 
     435%% ================================================================================================= 
     436\subsection[Flux form advection term (\textit{dynadv.F90})]{Flux form advection term (\protect\mdl{dynadv})} 
    454437\label{subsec:DYN_adv_flux} 
    455438 
    456439The discrete expression of the advection term is given by: 
    457440\[ 
    458   % \label{eq:dynadv} 
     441  % \label{eq:DYN_adv} 
    459442  \left\{ 
    460443    \begin{aligned} 
     
    475458a $2^{nd}$ order centered finite difference scheme, CEN2, 
    476459or a $3^{rd}$ order upstream biased scheme, UBS. 
    477 The latter is described in \citet{Shchepetkin_McWilliams_OM05}. 
    478 The schemes are selected using the namelist logicals \np{ln\_dynadv\_cen2} and \np{ln\_dynadv\_ubs}.  
     460The latter is described in \citet{shchepetkin.mcwilliams_OM05}. 
     461The schemes are selected using the namelist logicals \np{ln_dynadv_cen2}{ln\_dynadv\_cen2} and \np{ln_dynadv_ubs}{ln\_dynadv\_ubs}. 
    479462In flux form, the schemes differ by the choice of a space and time interpolation to define the value of 
    480 $u$ and $v$ at the centre of each face of $u$- and $v$-cells, \ie at the $T$-, $f$-, 
    481 and $uw$-points for $u$ and at the $f$-, $T$- and $vw$-points for $v$.  
    482  
    483 %------------------------------------------------------------- 
     463$u$ and $v$ at the centre of each face of $u$- and $v$-cells, \ie\ at the $T$-, $f$-, 
     464and $uw$-points for $u$ and at the $f$-, $T$- and $vw$-points for $v$. 
     465 
    484466%                 2nd order centred scheme 
    485 %------------------------------------------------------------- 
    486 \subsubsection{CEN2: $2^{nd}$ order centred scheme (\protect\np{ln\_dynadv\_cen2}\forcode{ = .true.})} 
     467%% ================================================================================================= 
     468\subsubsection[CEN2: $2^{nd}$ order centred scheme (\forcode{ln_dynadv_cen2})]{CEN2: $2^{nd}$ order centred scheme (\protect\np{ln_dynadv_cen2}{ln\_dynadv\_cen2})} 
    487469\label{subsec:DYN_adv_cen2} 
    488470 
    489471In the centered $2^{nd}$ order formulation, the velocity is evaluated as the mean of the two neighbouring points: 
    490472\begin{equation} 
    491   \label{eq:dynadv_cen2} 
     473  \label{eq:DYN_adv_cen2} 
    492474  \left\{ 
    493475    \begin{aligned} 
     
    496478    \end{aligned} 
    497479  \right. 
    498 \end{equation}  
    499  
    500 The scheme is non diffusive (\ie conserves the kinetic energy) but dispersive (\ie it may create false extrema). 
     480\end{equation} 
     481 
     482The scheme is non diffusive (\ie\ conserves the kinetic energy) but dispersive (\ie\ it may create false extrema). 
    501483It is therefore notoriously noisy and must be used in conjunction with an explicit diffusion operator to 
    502484produce a sensible solution. 
     
    504486so $u$ and $v$ are the \emph{now} velocities. 
    505487 
    506 %------------------------------------------------------------- 
    507488%                 UBS scheme 
    508 %------------------------------------------------------------- 
    509 \subsubsection{UBS: Upstream Biased Scheme (\protect\np{ln\_dynadv\_ubs}\forcode{ = .true.})} 
     489%% ================================================================================================= 
     490\subsubsection[UBS: Upstream Biased Scheme (\forcode{ln_dynadv_ubs})]{UBS: Upstream Biased Scheme (\protect\np{ln_dynadv_ubs}{ln\_dynadv\_ubs})} 
    510491\label{subsec:DYN_adv_ubs} 
    511492 
     
    514495For example, the evaluation of $u_T^{ubs} $ is done as follows: 
    515496\begin{equation} 
    516   \label{eq:dynadv_ubs} 
     497  \label{eq:DYN_adv_ubs} 
    517498  u_T^{ubs} =\overline u ^i-\;\frac{1}{6} 
    518499  \begin{cases} 
     
    522503\end{equation} 
    523504where $u"_{i+1/2} =\delta_{i+1/2} \left[ {\delta_i \left[ u \right]} \right]$. 
    524 This results in a dissipatively dominant (\ie hyper-diffusive) truncation error 
    525 \citep{Shchepetkin_McWilliams_OM05}. 
    526 The overall performance of the advection scheme is similar to that reported in \citet{Farrow1995}. 
     505This results in a dissipatively dominant (\ie\ hyper-diffusive) truncation error 
     506\citep{shchepetkin.mcwilliams_OM05}. 
     507The overall performance of the advection scheme is similar to that reported in \citet{farrow.stevens_JPO95}. 
    527508It is a relatively good compromise between accuracy and smoothness. 
    528509It is not a \emph{positive} scheme, meaning that false extrema are permitted. 
    529510But the amplitudes of the false extrema are significantly reduced over those in the centred second order method. 
    530 As the scheme already includes a diffusion component, it can be used without explicit lateral diffusion on momentum  
    531 (\ie \np{ln\_dynldf\_lap}\forcode{ = }\np{ln\_dynldf\_bilap}\forcode{ = .false.}), 
     511As the scheme already includes a diffusion component, it can be used without explicit lateral diffusion on momentum 
     512(\ie\ \np[=]{ln_dynldf_lap}{ln\_dynldf\_lap}\np[=.false.]{ln_dynldf_bilap}{ln\_dynldf\_bilap}), 
    532513and it is recommended to do so. 
    533514 
    534515The UBS scheme is not used in all directions. 
    535 In the vertical, the centred $2^{nd}$ order evaluation of the advection is preferred, \ie $u_{uw}^{ubs}$ and 
    536 $u_{vw}^{ubs}$ in \autoref{eq:dynadv_cen2} are used. 
    537 UBS is diffusive and is associated with vertical mixing of momentum. \gmcomment{ gm  pursue the  
     516In the vertical, the centred $2^{nd}$ order evaluation of the advection is preferred, \ie\ $u_{uw}^{ubs}$ and 
     517$u_{vw}^{ubs}$ in \autoref{eq:DYN_adv_cen2} are used. 
     518UBS is diffusive and is associated with vertical mixing of momentum. \cmtgm{ gm  pursue the 
    538519sentence:Since vertical mixing of momentum is a source term of the TKE equation...  } 
    539520 
    540 For stability reasons, the first term in (\autoref{eq:dynadv_ubs}), 
     521For stability reasons, the first term in (\autoref{eq:DYN_adv_ubs}), 
    541522which corresponds to a second order centred scheme, is evaluated using the \textit{now} velocity (centred in time), 
    542523while the second term, which is the diffusion part of the scheme, 
    543524is evaluated using the \textit{before} velocity (forward in time). 
    544 This is discussed by \citet{Webb_al_JAOT98} in the context of the Quick advection scheme. 
     525This is discussed by \citet{webb.de-cuevas.ea_JAOT98} in the context of the Quick advection scheme. 
    545526 
    546527Note that the UBS and QUICK (Quadratic Upstream Interpolation for Convective Kinematics) schemes only differ by 
    547528one coefficient. 
    548 Replacing $1/6$ by $1/8$ in (\autoref{eq:dynadv_ubs}) leads to the QUICK advection scheme \citep{Webb_al_JAOT98}. 
     529Replacing $1/6$ by $1/8$ in (\autoref{eq:DYN_adv_ubs}) leads to the QUICK advection scheme \citep{webb.de-cuevas.ea_JAOT98}. 
    549530This option is not available through a namelist parameter, since the $1/6$ coefficient is hard coded. 
    550531Nevertheless it is quite easy to make the substitution in the \mdl{dynadv\_ubs} module and obtain a QUICK scheme. 
     
    553534there is also the possibility of using a $4^{th}$ order evaluation of the advective velocity as in ROMS. 
    554535This is an error and should be suppressed soon. 
    555 %%% 
    556 \gmcomment{action :  this have to be done} 
    557 %%% 
    558  
    559 % ================================================================ 
    560 %           Hydrostatic pressure gradient term 
    561 % ================================================================ 
    562 \section{Hydrostatic pressure gradient (\protect\mdl{dynhpg})} 
     536\cmtgm{action :  this have to be done} 
     537 
     538%% ================================================================================================= 
     539\section[Hydrostatic pressure gradient (\textit{dynhpg.F90})]{Hydrostatic pressure gradient (\protect\mdl{dynhpg})} 
    563540\label{sec:DYN_hpg} 
    564 %------------------------------------------nam_dynhpg--------------------------------------------------- 
    565  
    566 \nlst{namdyn_hpg}  
    567 %------------------------------------------------------------------------------------------------------------- 
    568  
    569 Options are defined through the \ngn{namdyn\_hpg} namelist variables. 
     541 
     542\begin{listing} 
     543  \nlst{namdyn_hpg} 
     544  \caption{\forcode{&namdyn_hpg}} 
     545  \label{lst:namdyn_hpg} 
     546\end{listing} 
     547 
     548Options are defined through the \nam{dyn_hpg}{dyn\_hpg} namelist variables. 
    570549The key distinction between the different algorithms used for 
    571550the hydrostatic pressure gradient is the vertical coordinate used, 
    572 since HPG is a \emph{horizontal} pressure gradient, \ie computed along geopotential surfaces. 
     551since HPG is a \emph{horizontal} pressure gradient, \ie\ computed along geopotential surfaces. 
    573552As a result, any tilt of the surface of the computational levels will require a specific treatment to 
    574553compute the hydrostatic pressure gradient. 
    575554 
    576555The hydrostatic pressure gradient term is evaluated either using a leapfrog scheme, 
    577 \ie the density appearing in its expression is centred in time (\emph{now} $\rho$), 
     556\ie\ the density appearing in its expression is centred in time (\emph{now} $\rho$), 
    578557or a semi-implcit scheme. 
    579558At the lateral boundaries either free slip, no slip or partial slip boundary conditions are applied. 
    580559 
    581 %-------------------------------------------------------------------------------------------------------------- 
    582 %           z-coordinate with full step 
    583 %-------------------------------------------------------------------------------------------------------------- 
    584 \subsection{Full step $Z$-coordinate (\protect\np{ln\_dynhpg\_zco}\forcode{ = .true.})} 
     560%% ================================================================================================= 
     561\subsection[Full step $Z$-coordinate (\forcode{ln_dynhpg_zco})]{Full step $Z$-coordinate (\protect\np{ln_dynhpg_zco}{ln\_dynhpg\_zco})} 
    585562\label{subsec:DYN_hpg_zco} 
    586563 
     
    592569for $k=km$ (surface layer, $jk=1$ in the code) 
    593570\begin{equation} 
    594   \label{eq:dynhpg_zco_surf} 
     571  \label{eq:DYN_hpg_zco_surf} 
    595572  \left\{ 
    596573    \begin{aligned} 
     
    601578    \end{aligned} 
    602579  \right. 
    603 \end{equation}  
     580\end{equation} 
    604581 
    605582for $1<k<km$ (interior layer) 
    606583\begin{equation} 
    607   \label{eq:dynhpg_zco} 
     584  \label{eq:DYN_hpg_zco} 
    608585  \left\{ 
    609586    \begin{aligned} 
     
    616593    \end{aligned} 
    617594  \right. 
    618 \end{equation}  
    619  
    620 Note that the $1/2$ factor in (\autoref{eq:dynhpg_zco_surf}) is adequate because of the definition of $e_{3w}$ as 
     595\end{equation} 
     596 
     597Note that the $1/2$ factor in (\autoref{eq:DYN_hpg_zco_surf}) is adequate because of the definition of $e_{3w}$ as 
    621598the vertical derivative of the scale factor at the surface level ($z=0$). 
    622 Note also that in case of variable volume level (\key{vvl} defined), 
    623 the surface pressure gradient is included in \autoref{eq:dynhpg_zco_surf} and 
    624 \autoref{eq:dynhpg_zco} through the space and time variations of the vertical scale factor $e_{3w}$. 
    625  
    626 %-------------------------------------------------------------------------------------------------------------- 
    627 %           z-coordinate with partial step 
    628 %-------------------------------------------------------------------------------------------------------------- 
    629 \subsection{Partial step $Z$-coordinate (\protect\np{ln\_dynhpg\_zps}\forcode{ = .true.})} 
     599Note also that in case of variable volume level (\texttt{vvl?} defined), 
     600the surface pressure gradient is included in \autoref{eq:DYN_hpg_zco_surf} and 
     601\autoref{eq:DYN_hpg_zco} through the space and time variations of the vertical scale factor $e_{3w}$. 
     602 
     603%% ================================================================================================= 
     604\subsection[Partial step $Z$-coordinate (\forcode{ln_dynhpg_zps})]{Partial step $Z$-coordinate (\protect\np{ln_dynhpg_zps}{ln\_dynhpg\_zps})} 
    630605\label{subsec:DYN_hpg_zps} 
    631606 
     
    633608Before taking horizontal gradients between these tracer points, 
    634609a linear interpolation is used to approximate the deeper tracer as if 
    635 it actually lived at the depth of the shallower tracer point.  
     610it actually lived at the depth of the shallower tracer point. 
    636611 
    637612Apart from this modification, 
     
    645620module \mdl{zpsdhe} located in the TRA directory and described in \autoref{sec:TRA_zpshde}. 
    646621 
    647 %-------------------------------------------------------------------------------------------------------------- 
    648 %           s- and s-z-coordinates 
    649 %-------------------------------------------------------------------------------------------------------------- 
     622%% ================================================================================================= 
    650623\subsection{$S$- and $Z$-$S$-coordinates} 
    651624\label{subsec:DYN_hpg_sco} 
    652625 
    653626Pressure gradient formulations in an $s$-coordinate have been the subject of a vast number of papers 
    654 (\eg, \citet{Song1998, Shchepetkin_McWilliams_OM05}).  
     627(\eg, \citet{song_MWR98, shchepetkin.mcwilliams_OM05}). 
    655628A number of different pressure gradient options are coded but the ROMS-like, 
    656629density Jacobian with cubic polynomial method is currently disabled whilst known bugs are under investigation. 
    657630 
    658 $\bullet$ Traditional coding (see for example \citet{Madec_al_JPO96}: (\np{ln\_dynhpg\_sco}\forcode{ = .true.}) 
    659 \begin{equation} 
    660   \label{eq:dynhpg_sco} 
     631$\bullet$ Traditional coding (see for example \citet{madec.delecluse.ea_JPO96}: (\np[=.true.]{ln_dynhpg_sco}{ln\_dynhpg\_sco}) 
     632\begin{equation} 
     633  \label{eq:DYN_hpg_sco} 
    661634  \left\{ 
    662635    \begin{aligned} 
     
    667640    \end{aligned} 
    668641  \right. 
    669 \end{equation}  
     642\end{equation} 
    670643 
    671644Where the first term is the pressure gradient along coordinates, 
    672 computed as in \autoref{eq:dynhpg_zco_surf} - \autoref{eq:dynhpg_zco}, 
    673 and $z_T$ is the depth of the $T$-point evaluated from the sum of the vertical scale factors at the $w$-point  
     645computed as in \autoref{eq:DYN_hpg_zco_surf} - \autoref{eq:DYN_hpg_zco}, 
     646and $z_T$ is the depth of the $T$-point evaluated from the sum of the vertical scale factors at the $w$-point 
    674647($e_{3w}$). 
    675   
    676 $\bullet$ Traditional coding with adaptation for ice shelf cavities (\np{ln\_dynhpg\_isf}\forcode{ = .true.}). 
    677 This scheme need the activation of ice shelf cavities (\np{ln\_isfcav}\forcode{ = .true.}). 
    678  
    679 $\bullet$ Pressure Jacobian scheme (prj) (a research paper in preparation) (\np{ln\_dynhpg\_prj}\forcode{ = .true.}) 
    680  
    681 $\bullet$ Density Jacobian with cubic polynomial scheme (DJC) \citep{Shchepetkin_McWilliams_OM05}  
    682 (\np{ln\_dynhpg\_djc}\forcode{ = .true.}) (currently disabled; under development) 
    683  
    684 Note that expression \autoref{eq:dynhpg_sco} is commonly used when the variable volume formulation is activated 
    685 (\key{vvl}) because in that case, even with a flat bottom, 
    686 the coordinate surfaces are not horizontal but follow the free surface \citep{Levier2007}. 
    687 The pressure jacobian scheme (\np{ln\_dynhpg\_prj}\forcode{ = .true.}) is available as 
    688 an improved option to \np{ln\_dynhpg\_sco}\forcode{ = .true.} when \key{vvl} is active. 
     648 
     649$\bullet$ Traditional coding with adaptation for ice shelf cavities (\np[=.true.]{ln_dynhpg_isf}{ln\_dynhpg\_isf}). 
     650This scheme need the activation of ice shelf cavities (\np[=.true.]{ln_isfcav}{ln\_isfcav}). 
     651 
     652$\bullet$ Pressure Jacobian scheme (prj) (a research paper in preparation) (\np[=.true.]{ln_dynhpg_prj}{ln\_dynhpg\_prj}) 
     653 
     654$\bullet$ Density Jacobian with cubic polynomial scheme (DJC) \citep{shchepetkin.mcwilliams_OM05} 
     655(\np[=.true.]{ln_dynhpg_djc}{ln\_dynhpg\_djc}) (currently disabled; under development) 
     656 
     657Note that expression \autoref{eq:DYN_hpg_sco} is commonly used when the variable volume formulation is activated 
     658(\texttt{vvl?}) because in that case, even with a flat bottom, 
     659the coordinate surfaces are not horizontal but follow the free surface \citep{levier.treguier.ea_rpt07}. 
     660The pressure jacobian scheme (\np[=.true.]{ln_dynhpg_prj}{ln\_dynhpg\_prj}) is available as 
     661an improved option to \np[=.true.]{ln_dynhpg_sco}{ln\_dynhpg\_sco} when \texttt{vvl?} is active. 
    689662The pressure Jacobian scheme uses a constrained cubic spline to 
    690663reconstruct the density profile across the water column. 
     
    694667This method can provide a more accurate calculation of the horizontal pressure gradient than the standard scheme. 
    695668 
     669%% ================================================================================================= 
    696670\subsection{Ice shelf cavity} 
    697671\label{subsec:DYN_hpg_isf} 
     672 
    698673Beneath an ice shelf, the total pressure gradient is the sum of the pressure gradient due to the ice shelf load and 
    699 the pressure gradient due to the ocean load (\np{ln\_dynhpg\_isf}\forcode{ = .true.}).\\ 
     674the pressure gradient due to the ocean load (\np[=.true.]{ln_dynhpg_isf}{ln\_dynhpg\_isf}).\\ 
    700675 
    701676The main hypothesis to compute the ice shelf load is that the ice shelf is in an isostatic equilibrium. 
     
    704679corresponds to the water replaced by the ice shelf. 
    705680This top pressure is constant over time. 
    706 A detailed description of this method is described in \citet{Losch2008}.\\ 
    707  
    708 The pressure gradient due to ocean load is computed using the expression \autoref{eq:dynhpg_sco} described in 
    709 \autoref{subsec:DYN_hpg_sco}.  
    710  
    711 %-------------------------------------------------------------------------------------------------------------- 
    712 %           Time-scheme 
    713 %-------------------------------------------------------------------------------------------------------------- 
    714 \subsection{Time-scheme (\protect\np{ln\_dynhpg\_imp}\forcode{ = .true./.false.})} 
     681A detailed description of this method is described in \citet{losch_JGR08}.\\ 
     682 
     683The pressure gradient due to ocean load is computed using the expression \autoref{eq:DYN_hpg_sco} described in 
     684\autoref{subsec:DYN_hpg_sco}. 
     685 
     686%% ================================================================================================= 
     687\subsection[Time-scheme (\forcode{ln_dynhpg_imp})]{Time-scheme (\protect\np{ln_dynhpg_imp}{ln\_dynhpg\_imp})} 
    715688\label{subsec:DYN_hpg_imp} 
    716689 
     
    722695the physical phenomenon that controls the time-step is internal gravity waves (IGWs). 
    723696A semi-implicit scheme for doubling the stability limit associated with IGWs can be used 
    724 \citep{Brown_Campana_MWR78, Maltrud1998}. 
     697\citep{brown.campana_MWR78, maltrud.smith.ea_JGR98}. 
    725698It involves the evaluation of the hydrostatic pressure gradient as 
    726699an average over the three time levels $t-\rdt$, $t$, and $t+\rdt$ 
    727 (\ie \textit{before}, \textit{now} and  \textit{after} time-steps), 
    728 rather than at the central time level $t$ only, as in the standard leapfrog scheme.  
    729  
    730 $\bullet$ leapfrog scheme (\np{ln\_dynhpg\_imp}\forcode{ = .true.}): 
    731  
    732 \begin{equation} 
    733   \label{eq:dynhpg_lf} 
     700(\ie\ \textit{before}, \textit{now} and  \textit{after} time-steps), 
     701rather than at the central time level $t$ only, as in the standard leapfrog scheme. 
     702 
     703$\bullet$ leapfrog scheme (\np[=.true.]{ln_dynhpg_imp}{ln\_dynhpg\_imp}): 
     704 
     705\begin{equation} 
     706  \label{eq:DYN_hpg_lf} 
    734707  \frac{u^{t+\rdt}-u^{t-\rdt}}{2\rdt} = \;\cdots \; 
    735708  -\frac{1}{\rho_o \,e_{1u} }\delta_{i+1/2} \left[ {p_h^t } \right] 
    736709\end{equation} 
    737710 
    738 $\bullet$ semi-implicit scheme (\np{ln\_dynhpg\_imp}\forcode{ = .true.}): 
    739 \begin{equation} 
    740   \label{eq:dynhpg_imp} 
     711$\bullet$ semi-implicit scheme (\np[=.true.]{ln_dynhpg_imp}{ln\_dynhpg\_imp}): 
     712\begin{equation} 
     713  \label{eq:DYN_hpg_imp} 
    741714  \frac{u^{t+\rdt}-u^{t-\rdt}}{2\rdt} = \;\cdots \; 
    742715  -\frac{1}{4\,\rho_o \,e_{1u} } \delta_{i+1/2} \left[ p_h^{t+\rdt} +2\,p_h^t +p_h^{t-\rdt}  \right] 
    743716\end{equation} 
    744717 
    745 The semi-implicit time scheme \autoref{eq:dynhpg_imp} is made possible without 
     718The semi-implicit time scheme \autoref{eq:DYN_hpg_imp} is made possible without 
    746719significant additional computation since the density can be updated to time level $t+\rdt$ before 
    747720computing the horizontal hydrostatic pressure gradient. 
    748721It can be easily shown that the stability limit associated with the hydrostatic pressure gradient doubles using 
    749 \autoref{eq:dynhpg_imp} compared to that using the standard leapfrog scheme \autoref{eq:dynhpg_lf}. 
    750 Note that \autoref{eq:dynhpg_imp} is equivalent to applying a time filter to the pressure gradient to 
     722\autoref{eq:DYN_hpg_imp} compared to that using the standard leapfrog scheme \autoref{eq:DYN_hpg_lf}. 
     723Note that \autoref{eq:DYN_hpg_imp} is equivalent to applying a time filter to the pressure gradient to 
    751724eliminate high frequency IGWs. 
    752 Obviously, when using \autoref{eq:dynhpg_imp}, 
     725Obviously, when using \autoref{eq:DYN_hpg_imp}, 
    753726the doubling of the time-step is achievable only if no other factors control the time-step, 
    754727such as the stability limits associated with advection or diffusion. 
    755728 
    756 In practice, the semi-implicit scheme is used when \np{ln\_dynhpg\_imp}\forcode{ = .true.}. 
     729In practice, the semi-implicit scheme is used when \np[=.true.]{ln_dynhpg_imp}{ln\_dynhpg\_imp}. 
    757730In this case, we choose to apply the time filter to temperature and salinity used in the equation of state, 
    758731instead of applying it to the hydrostatic pressure or to the density, 
     
    760733The density used to compute the hydrostatic pressure gradient (whatever the formulation) is evaluated as follows: 
    761734\[ 
    762   % \label{eq:rho_flt} 
     735  % \label{eq:DYN_rho_flt} 
    763736  \rho^t = \rho( \widetilde{T},\widetilde {S},z_t) 
    764737  \quad    \text{with}  \quad 
     
    768741Note that in the semi-implicit case, it is necessary to save the filtered density, 
    769742an extra three-dimensional field, in the restart file to restart the model with exact reproducibility. 
    770 This option is controlled by  \np{nn\_dynhpg\_rst}, a namelist parameter. 
    771  
    772 % ================================================================ 
    773 % Surface Pressure Gradient 
    774 % ================================================================ 
    775 \section{Surface pressure gradient (\protect\mdl{dynspg})} 
     743This option is controlled by  \np{nn_dynhpg_rst}{nn\_dynhpg\_rst}, a namelist parameter. 
     744 
     745%% ================================================================================================= 
     746\section[Surface pressure gradient (\textit{dynspg.F90})]{Surface pressure gradient (\protect\mdl{dynspg})} 
    776747\label{sec:DYN_spg} 
    777 %-----------------------------------------nam_dynspg---------------------------------------------------- 
    778  
    779 \nlst{namdyn_spg}  
    780 %------------------------------------------------------------------------------------------------------------ 
    781  
    782 Options are defined through the \ngn{namdyn\_spg} namelist variables. 
    783 The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:PE_hor_pg}). 
     748 
     749\begin{listing} 
     750  \nlst{namdyn_spg} 
     751  \caption{\forcode{&namdyn_spg}} 
     752  \label{lst:namdyn_spg} 
     753\end{listing} 
     754 
     755Options are defined through the \nam{dyn_spg}{dyn\_spg} namelist variables. 
     756The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:MB_hor_pg}). 
    784757The main distinction is between the fixed volume case (linear free surface) and 
    785 the variable volume case (nonlinear free surface, \key{vvl} is defined). 
    786 In the linear free surface case (\autoref{subsec:PE_free_surface}) 
     758the variable volume case (nonlinear free surface, \texttt{vvl?} is defined). 
     759In the linear free surface case (\autoref{subsec:MB_free_surface}) 
    787760the vertical scale factors $e_{3}$ are fixed in time, 
    788 while they are time-dependent in the nonlinear case (\autoref{subsec:PE_free_surface}). 
    789 With both linear and nonlinear free surface, external gravity waves are allowed in the equations,  
     761while they are time-dependent in the nonlinear case (\autoref{subsec:MB_free_surface}). 
     762With both linear and nonlinear free surface, external gravity waves are allowed in the equations, 
    790763which imposes a very small time step when an explicit time stepping is used. 
    791 Two methods are proposed to allow a longer time step for the three-dimensional equations:  
    792 the filtered free surface, which is a modification of the continuous equations (see \autoref{eq:PE_flt}),  
     764Two methods are proposed to allow a longer time step for the three-dimensional equations: 
     765the filtered free surface, which is a modification of the continuous equations (see \autoref{eq:MB_flt?}), 
    793766and the split-explicit free surface described below. 
    794 The extra term introduced in the filtered method is calculated implicitly,  
     767The extra term introduced in the filtered method is calculated implicitly, 
    795768so that the update of the next velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}. 
    796769 
    797  
    798770The form of the surface pressure gradient term depends on how the user wants to 
    799 handle the fast external gravity waves that are a solution of the analytical equation (\autoref{sec:PE_hor_pg}). 
     771handle the fast external gravity waves that are a solution of the analytical equation (\autoref{sec:MB_hor_pg}). 
    800772Three formulations are available, all controlled by a CPP key (ln\_dynspg\_xxx): 
    801773an explicit formulation which requires a small time step; 
    802774a filtered free surface formulation which allows a larger time step by 
    803 adding a filtering term into the momentum equation;  
     775adding a filtering term into the momentum equation; 
    804776and a split-explicit free surface formulation, described below, which also allows a larger time step. 
    805777 
     
    807779As a consequence the update of the $next$ velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}. 
    808780 
    809  
    810 %-------------------------------------------------------------------------------------------------------------- 
    811 % Explicit free surface formulation 
    812 %-------------------------------------------------------------------------------------------------------------- 
    813 \subsection{Explicit free surface (\protect\key{dynspg\_exp})} 
     781%% ================================================================================================= 
     782\subsection[Explicit free surface (\forcode{ln_dynspg_exp})]{Explicit free surface (\protect\np{ln_dynspg_exp}{ln\_dynspg\_exp})} 
    814783\label{subsec:DYN_spg_exp} 
    815784 
    816 In the explicit free surface formulation (\key{dynspg\_exp} defined), 
     785In the explicit free surface formulation (\np{ln_dynspg_exp}{ln\_dynspg\_exp} set to true), 
    817786the model time step is chosen to be small enough to resolve the external gravity waves 
    818787(typically a few tens of seconds). 
    819 The surface pressure gradient, evaluated using a leap-frog scheme (\ie centered in time), 
     788The surface pressure gradient, evaluated using a leap-frog scheme (\ie\ centered in time), 
    820789is thus simply given by : 
    821790\begin{equation} 
    822   \label{eq:dynspg_exp} 
     791  \label{eq:DYN_spg_exp} 
    823792  \left\{ 
    824793    \begin{aligned} 
     
    827796    \end{aligned} 
    828797  \right. 
    829 \end{equation}  
    830  
    831 Note that in the non-linear free surface case (\ie \key{vvl} defined), 
     798\end{equation} 
     799 
     800Note that in the non-linear free surface case (\ie\ \texttt{vvl?} defined), 
    832801the surface pressure gradient is already included in the momentum tendency through 
    833802the level thickness variation allowed in the computation of the hydrostatic pressure gradient. 
    834803Thus, nothing is done in the \mdl{dynspg\_exp} module. 
    835804 
    836 %-------------------------------------------------------------------------------------------------------------- 
    837 % Split-explict free surface formulation 
    838 %-------------------------------------------------------------------------------------------------------------- 
    839 \subsection{Split-explicit free surface (\protect\key{dynspg\_ts})} 
     805%% ================================================================================================= 
     806\subsection[Split-explicit free surface (\forcode{ln_dynspg_ts})]{Split-explicit free surface (\protect\np{ln_dynspg_ts}{ln\_dynspg\_ts})} 
    840807\label{subsec:DYN_spg_ts} 
    841 %------------------------------------------namsplit----------------------------------------------------------- 
    842 % 
    843808%\nlst{namsplit} 
    844 %------------------------------------------------------------------------------------------------------------- 
    845  
    846 The split-explicit free surface formulation used in \NEMO (\key{dynspg\_ts} defined), 
    847 also called the time-splitting formulation, follows the one proposed by \citet{Shchepetkin_McWilliams_OM05}. 
     809 
     810The split-explicit free surface formulation used in \NEMO\ (\np{ln_dynspg_ts}{ln\_dynspg\_ts} set to true), 
     811also called the time-splitting formulation, follows the one proposed by \citet{shchepetkin.mcwilliams_OM05}. 
    848812The general idea is to solve the free surface equation and the associated barotropic velocity equations with 
    849813a smaller time step than $\rdt$, the time step used for the three dimensional prognostic variables 
    850 (\autoref{fig:DYN_dynspg_ts}). 
     814(\autoref{fig:DYN_spg_ts}). 
    851815The size of the small time step, $\rdt_e$ (the external mode or barotropic time step) is provided through 
    852 the \np{nn\_baro} namelist parameter as: $\rdt_e = \rdt / nn\_baro$. 
    853 This parameter can be optionally defined automatically (\np{ln\_bt\_nn\_auto}\forcode{ = .true.}) considering that 
     816the \np{nn_baro}{nn\_baro} namelist parameter as: $\rdt_e = \rdt / nn\_baro$. 
     817This parameter can be optionally defined automatically (\np[=.true.]{ln_bt_nn_auto}{ln\_bt\_nn\_auto}) considering that 
    854818the stability of the barotropic system is essentially controled by external waves propagation. 
    855819Maximum Courant number is in that case time independent, and easily computed online from the input bathymetry. 
    856 Therefore, $\rdt_e$ is adjusted so that the Maximum allowed Courant number is smaller than \np{rn\_bt\_cmax}. 
    857  
    858 %%% 
     820Therefore, $\rdt_e$ is adjusted so that the Maximum allowed Courant number is smaller than \np{rn_bt_cmax}{rn\_bt\_cmax}. 
     821 
    859822The barotropic mode solves the following equations: 
    860823% \begin{subequations} 
    861 %  \label{eq:BT} 
    862 \begin{equation} 
    863   \label{eq:BT_dyn} 
    864   \frac{\partial {\rm \overline{{\bf U}}_h} }{\partial t}= 
    865   -f\;{\rm {\bf k}}\times {\rm \overline{{\bf U}}_h} 
    866   -g\nabla _h \eta -\frac{c_b^{\textbf U}}{H+\eta} \rm {\overline{{\bf U}}_h} + \rm {\overline{\bf G}} 
    867 \end{equation} 
    868 \[ 
    869   % \label{eq:BT_ssh} 
    870   \frac{\partial \eta }{\partial t}=-\nabla \cdot \left[ {\left( {H+\eta } \right) \; {\rm{\bf \overline{U}}}_h \,} \right]+P-E 
     824%  \label{eq:DYN_BT} 
     825\begin{equation} 
     826  \label{eq:DYN_BT_dyn} 
     827  \frac{\partial {\mathrm \overline{{\mathbf U}}_h} }{\partial t}= 
     828  -f\;{\mathrm {\mathbf k}}\times {\mathrm \overline{{\mathbf U}}_h} 
     829  -g\nabla _h \eta -\frac{c_b^{\textbf U}}{H+\eta} \mathrm {\overline{{\mathbf U}}_h} + \mathrm {\overline{\mathbf G}} 
     830\end{equation} 
     831\[ 
     832  % \label{eq:DYN_BT_ssh} 
     833  \frac{\partial \eta }{\partial t}=-\nabla \cdot \left[ {\left( {H+\eta } \right) \; {\mathrm{\mathbf \overline{U}}}_h \,} \right]+P-E 
    871834\] 
    872835% \end{subequations} 
    873 where $\rm {\overline{\bf G}}$ is a forcing term held constant, containing coupling term between modes, 
     836where $\mathrm {\overline{\mathbf G}}$ is a forcing term held constant, containing coupling term between modes, 
    874837surface atmospheric forcing as well as slowly varying barotropic terms not explicitly computed to gain efficiency. 
    875 The third term on the right hand side of \autoref{eq:BT_dyn} represents the bottom stress 
    876 (see section \autoref{sec:ZDF_bfr}), explicitly accounted for at each barotropic iteration. 
     838The third term on the right hand side of \autoref{eq:DYN_BT_dyn} represents the bottom stress 
     839(see section \autoref{sec:ZDF_drg}), explicitly accounted for at each barotropic iteration. 
    877840Temporal discretization of the system above follows a three-time step Generalized Forward Backward algorithm 
    878 detailed in \citet{Shchepetkin_McWilliams_OM05}. 
    879 AB3-AM4 coefficients used in \NEMO follow the second-order accurate, 
    880 "multi-purpose" stability compromise as defined in \citet{Shchepetkin_McWilliams_Bk08} 
    881 (see their figure 12, lower left).  
    882  
    883 %>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   > 
     841detailed in \citet{shchepetkin.mcwilliams_OM05}. 
     842AB3-AM4 coefficients used in \NEMO\ follow the second-order accurate, 
     843"multi-purpose" stability compromise as defined in \citet{shchepetkin.mcwilliams_ibk09} 
     844(see their figure 12, lower left). 
     845 
    884846\begin{figure}[!t] 
    885   \begin{center} 
    886     \includegraphics[width=0.7\textwidth]{Fig_DYN_dynspg_ts} 
    887     \caption{ 
    888       \protect\label{fig:DYN_dynspg_ts} 
    889       Schematic of the split-explicit time stepping scheme for the external and internal modes. 
    890       Time increases to the right. In this particular exemple, 
    891       a boxcar averaging window over $nn\_baro$ barotropic time steps is used ($nn\_bt\_flt=1$) and $nn\_baro=5$. 
    892       Internal mode time steps (which are also the model time steps) are denoted by $t-\rdt$, $t$ and $t+\rdt$. 
    893       Variables with $k$ superscript refer to instantaneous barotropic variables, 
    894       $< >$ and $<< >>$ operator refer to time filtered variables using respectively primary (red vertical bars) and 
    895       secondary weights (blue vertical bars). 
    896       The former are used to obtain time filtered quantities at $t+\rdt$ while 
    897       the latter are used to obtain time averaged transports to advect tracers. 
    898       a) Forward time integration: \protect\np{ln\_bt\_fw}\forcode{ = .true.}, 
    899       \protect\np{ln\_bt\_av}\forcode{ = .true.}. 
    900       b) Centred time integration: \protect\np{ln\_bt\_fw}\forcode{ = .false.}, 
    901       \protect\np{ln\_bt\_av}\forcode{ = .true.}. 
    902       c) Forward time integration with no time filtering (POM-like scheme): 
    903       \protect\np{ln\_bt\_fw}\forcode{ = .true.}, \protect\np{ln\_bt\_av}\forcode{ = .false.}. 
    904     } 
    905   \end{center} 
     847  \centering 
     848  \includegraphics[width=0.66\textwidth]{DYN_dynspg_ts} 
     849  \caption[Split-explicit time stepping scheme for the external and internal modes]{ 
     850    Schematic of the split-explicit time stepping scheme for the external and internal modes. 
     851    Time increases to the right. 
     852    In this particular exemple, 
     853    a boxcar averaging window over \np{nn_baro}{nn\_baro} barotropic time steps is used 
     854    (\np[=1]{nn_bt_flt}{nn\_bt\_flt}) and \np[=5]{nn_baro}{nn\_baro}. 
     855    Internal mode time steps (which are also the model time steps) are denoted by 
     856    $t-\rdt$, $t$ and $t+\rdt$. 
     857    Variables with $k$ superscript refer to instantaneous barotropic variables, 
     858    $< >$ and $<< >>$ operator refer to time filtered variables using respectively primary 
     859    (red vertical bars) and secondary weights (blue vertical bars). 
     860    The former are used to obtain time filtered quantities at $t+\rdt$ while 
     861    the latter are used to obtain time averaged transports to advect tracers. 
     862    a) Forward time integration: 
     863    \protect\np[=.true.]{ln_bt_fw}{ln\_bt\_fw},  \protect\np[=.true.]{ln_bt_av}{ln\_bt\_av}. 
     864    b) Centred time integration: 
     865    \protect\np[=.false.]{ln_bt_fw}{ln\_bt\_fw}, \protect\np[=.true.]{ln_bt_av}{ln\_bt\_av}. 
     866    c) Forward time integration with no time filtering (POM-like scheme): 
     867    \protect\np[=.true.]{ln_bt_fw}{ln\_bt\_fw},  \protect\np[=.false.]{ln_bt_av}{ln\_bt\_av}.} 
     868  \label{fig:DYN_spg_ts} 
    906869\end{figure} 
    907 %>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   > 
    908  
    909 In the default case (\np{ln\_bt\_fw}\forcode{ = .true.}), 
     870 
     871In the default case (\np[=.true.]{ln_bt_fw}{ln\_bt\_fw}), 
    910872the external mode is integrated between \textit{now} and \textit{after} baroclinic time-steps 
    911 (\autoref{fig:DYN_dynspg_ts}a). 
     873(\autoref{fig:DYN_spg_ts}a). 
    912874To avoid aliasing of fast barotropic motions into three dimensional equations, 
    913 time filtering is eventually applied on barotropic quantities (\np{ln\_bt\_av}\forcode{ = .true.}). 
     875time filtering is eventually applied on barotropic quantities (\np[=.true.]{ln_bt_av}{ln\_bt\_av}). 
    914876In that case, the integration is extended slightly beyond \textit{after} time step to 
    915877provide time filtered quantities. 
    916878These are used for the subsequent initialization of the barotropic mode in the following baroclinic step. 
    917 Since external mode equations written at baroclinic time steps finally follow a forward time stepping scheme,  
     879Since external mode equations written at baroclinic time steps finally follow a forward time stepping scheme, 
    918880asselin filtering is not applied to barotropic quantities.\\ 
    919881Alternatively, one can choose to integrate barotropic equations starting from \textit{before} time step 
    920 (\np{ln\_bt\_fw}\forcode{ = .false.}). 
    921 Although more computationaly expensive ( \np{nn\_baro} additional iterations are indeed necessary), 
     882(\np[=.false.]{ln_bt_fw}{ln\_bt\_fw}). 
     883Although more computationaly expensive ( \np{nn_baro}{nn\_baro} additional iterations are indeed necessary), 
    922884the baroclinic to barotropic forcing term given at \textit{now} time step become centred in 
    923885the middle of the integration window. 
     
    926888%references to Patrick Marsaleix' work here. Also work done by SHOM group. 
    927889 
    928 %%% 
    929890 
    930891As far as tracer conservation is concerned, 
     
    936897and time splitting not compatible. 
    937898Advective barotropic velocities are obtained by using a secondary set of filtering weights, 
    938 uniquely defined from the filter coefficients used for the time averaging (\citet{Shchepetkin_McWilliams_OM05}). 
     899uniquely defined from the filter coefficients used for the time averaging (\citet{shchepetkin.mcwilliams_OM05}). 
    939900Consistency between the time averaged continuity equation and the time stepping of tracers is here the key to 
    940901obtain exact conservation. 
    941902 
    942 %%% 
    943903 
    944904One can eventually choose to feedback instantaneous values by not using any time filter 
    945 (\np{ln\_bt\_av}\forcode{ = .false.}).  
     905(\np[=.false.]{ln_bt_av}{ln\_bt\_av}). 
    946906In that case, external mode equations are continuous in time, 
    947 \ie they are not re-initialized when starting a new sub-stepping sequence. 
     907\ie\ they are not re-initialized when starting a new sub-stepping sequence. 
    948908This is the method used so far in the POM model, the stability being maintained by 
    949909refreshing at (almost) each barotropic time step advection and horizontal diffusion terms. 
    950 Since the latter terms have not been added in \NEMO for computational efficiency, 
     910Since the latter terms have not been added in \NEMO\ for computational efficiency, 
    951911removing time filtering is not recommended except for debugging purposes. 
    952912This may be used for instance to appreciate the damping effect of the standard formulation on 
    953913external gravity waves in idealized or weakly non-linear cases. 
    954914Although the damping is lower than for the filtered free surface, 
    955 it is still significant as shown by \citet{Levier2007} in the case of an analytical barotropic Kelvin wave. 
    956  
    957 %>>>>>=============== 
    958 \gmcomment{               %%% copy from griffies Book  
     915it is still significant as shown by \citet{levier.treguier.ea_rpt07} in the case of an analytical barotropic Kelvin wave. 
     916 
     917\cmtgm{               %%% copy from griffies Book 
    959918 
    960919\textbf{title: Time stepping the barotropic system } 
     
    963922Hence, we can update the surface height and vertically integrated velocity with a leap-frog scheme using 
    964923the small barotropic time step $\rdt$. 
    965 We have  
     924We have 
    966925 
    967926\[ 
     
    986945and total depth of the ocean $H(\tau)$ are held for the duration of the barotropic time stepping over 
    987946a single cycle. 
    988 This is also the time that sets the barotropic time steps via  
     947This is also the time that sets the barotropic time steps via 
    989948\[ 
    990949  % \label{eq:DYN_spg_ts_t} 
     
    992951\] 
    993952with $n$ an integer. 
    994 The density scaled surface pressure is evaluated via  
     953The density scaled surface pressure is evaluated via 
    995954\[ 
    996955  % \label{eq:DYN_spg_ts_ps} 
     
    1001960  \end{cases} 
    1002961\] 
    1003 To get started, we assume the following initial conditions  
     962To get started, we assume the following initial conditions 
    1004963\[ 
    1005964  % \label{eq:DYN_spg_ts_eta} 
     
    1009968  \end{split} 
    1010969\] 
    1011 with  
     970with 
    1012971\[ 
    1013972  % \label{eq:DYN_spg_ts_etaF} 
     
    1015974\] 
    1016975the time averaged surface height taken from the previous barotropic cycle. 
    1017 Likewise,  
     976Likewise, 
    1018977\[ 
    1019978  % \label{eq:DYN_spg_ts_u} 
     
    1021980  \textbf{U}(\tau,t_{n=1}) = \textbf{U}^{(b)}(\tau,t_{n=0}) + \rdt \ \text{RHS}_{n=0} 
    1022981\] 
    1023 with  
     982with 
    1024983\[ 
    1025984  % \label{eq:DYN_spg_ts_u} 
     
    1027986\] 
    1028987the time averaged vertically integrated transport. 
    1029 Notably, there is no Robert-Asselin time filter used in the barotropic portion of the integration.  
     988Notably, there is no Robert-Asselin time filter used in the barotropic portion of the integration. 
    1030989 
    1031990Upon reaching $t_{n=N} = \tau + 2\rdt \tau$ , 
    1032991the vertically integrated velocity is time averaged to produce the updated vertically integrated velocity at 
    1033 baroclinic time $\tau + \rdt \tau$  
     992baroclinic time $\tau + \rdt \tau$ 
    1034993\[ 
    1035994  % \label{eq:DYN_spg_ts_u} 
     
    1037996\] 
    1038997The surface height on the new baroclinic time step is then determined via a baroclinic leap-frog using 
    1039 the following form  
     998the following form 
    1040999 
    10411000\begin{equation} 
    10421001  \label{eq:DYN_spg_ts_ssh} 
    1043   \eta(\tau+\Delta) - \eta^{F}(\tau-\Delta) = 2\rdt \ \left[ - \nabla \cdot \textbf{U}(\tau) + \text{EMP}_w \right]   
     1002  \eta(\tau+\Delta) - \eta^{F}(\tau-\Delta) = 2\rdt \ \left[ - \nabla \cdot \textbf{U}(\tau) + \text{EMP}_w \right] 
    10441003\end{equation} 
    10451004 
    10461005The use of this "big-leap-frog" scheme for the surface height ensures compatibility between 
    10471006the mass/volume budgets and the tracer budgets. 
    1048 More discussion of this point is provided in Chapter 10 (see in particular Section 10.2).  
    1049   
     1007More discussion of this point is provided in Chapter 10 (see in particular Section 10.2). 
     1008 
    10501009In general, some form of time filter is needed to maintain integrity of the surface height field due to 
    10511010the leap-frog splitting mode in equation \autoref{eq:DYN_spg_ts_ssh}. 
    10521011We have tried various forms of such filtering, 
    1053 with the following method discussed in \cite{Griffies_al_MWR01} chosen due to 
     1012with the following method discussed in \cite{griffies.pacanowski.ea_MWR01} chosen due to 
    10541013its stability and reasonably good maintenance of tracer conservation properties (see ??). 
    10551014 
     
    10581017  \eta^{F}(\tau-\Delta) =  \overline{\eta^{(b)}(\tau)} 
    10591018\end{equation} 
    1060 Another approach tried was  
     1019Another approach tried was 
    10611020 
    10621021\[ 
     
    10711030eliminating tracer and surface height time filtering (see ?? for more complete discussion). 
    10721031However, in the general case with a non-zero $\alpha$, 
    1073 the filter \autoref{eq:DYN_spg_ts_sshf} was found to be more conservative, and so is recommended.  
     1032the filter \autoref{eq:DYN_spg_ts_sshf} was found to be more conservative, and so is recommended. 
    10741033 
    10751034}            %%end gm comment (copy of griffies book) 
    10761035 
    1077 %>>>>>=============== 
    1078  
    1079  
    1080 %-------------------------------------------------------------------------------------------------------------- 
    1081 % Filtered free surface formulation 
    1082 %-------------------------------------------------------------------------------------------------------------- 
    1083 \subsection{Filtered free surface (\protect\key{dynspg\_flt})} 
     1036%% ================================================================================================= 
     1037\subsection{Filtered free surface (\forcode{dynspg_flt?})} 
    10841038\label{subsec:DYN_spg_fltp} 
    10851039 
    1086 The filtered formulation follows the \citet{Roullet_Madec_JGR00} implementation.  
    1087 The extra term introduced in the equations (see \autoref{subsec:PE_free_surface}) is solved implicitly.  
     1040The filtered formulation follows the \citet{roullet.madec_JGR00} implementation. 
     1041The extra term introduced in the equations (see \autoref{subsec:MB_free_surface}) is solved implicitly. 
    10881042The elliptic solvers available in the code are documented in \autoref{chap:MISC}. 
    10891043 
    10901044%% gm %%======>>>>   given here the discrete eqs provided to the solver 
    1091 \gmcomment{               %%% copy from chap-model basics  
     1045\cmtgm{               %%% copy from chap-model basics 
    10921046  \[ 
    1093     % \label{eq:spg_flt} 
    1094     \frac{\partial {\rm {\bf U}}_h }{\partial t}= {\rm {\bf M}} 
     1047    % \label{eq:DYN_spg_flt} 
     1048    \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= {\mathrm {\mathbf M}} 
    10951049    - g \nabla \left( \tilde{\rho} \ \eta \right) 
    10961050    - g \ T_c \nabla \left( \widetilde{\rho} \ \partial_t \eta \right) 
     
    10981052  where $T_c$, is a parameter with dimensions of time which characterizes the force, 
    10991053  $\widetilde{\rho} = \rho / \rho_o$ is the dimensionless density, 
    1100   and $\rm {\bf M}$ represents the collected contributions of the Coriolis, hydrostatic pressure gradient, 
    1101   non-linear and viscous terms in \autoref{eq:PE_dyn}. 
    1102 }   %end gmcomment 
    1103  
    1104 Note that in the linear free surface formulation (\key{vvl} not defined), 
     1054  and $\mathrm {\mathbf M}$ represents the collected contributions of the Coriolis, hydrostatic pressure gradient, 
     1055  non-linear and viscous terms in \autoref{eq:MB_dyn}. 
     1056}   %end cmtgm 
     1057 
     1058Note that in the linear free surface formulation (\texttt{vvl?} not defined), 
    11051059the ocean depth is time-independent and so is the matrix to be inverted. 
    1106 It is computed once and for all and applies to all ocean time steps.  
    1107  
    1108 % ================================================================ 
    1109 % Lateral diffusion term 
    1110 % ================================================================ 
    1111 \section{Lateral diffusion term and operators (\protect\mdl{dynldf})} 
     1060It is computed once and for all and applies to all ocean time steps. 
     1061 
     1062%% ================================================================================================= 
     1063\section[Lateral diffusion term and operators (\textit{dynldf.F90})]{Lateral diffusion term and operators (\protect\mdl{dynldf})} 
    11121064\label{sec:DYN_ldf} 
    1113 %------------------------------------------nam_dynldf---------------------------------------------------- 
    1114  
    1115 \nlst{namdyn_ldf}  
    1116 %------------------------------------------------------------------------------------------------------------- 
    1117  
    1118 Options are defined through the \ngn{namdyn\_ldf} namelist variables. 
     1065 
     1066\begin{listing} 
     1067  \nlst{namdyn_ldf} 
     1068  \caption{\forcode{&namdyn_ldf}} 
     1069  \label{lst:namdyn_ldf} 
     1070\end{listing} 
     1071 
     1072Options are defined through the \nam{dyn_ldf}{dyn\_ldf} namelist variables. 
    11191073The options available for lateral diffusion are to use either laplacian (rotated or not) or biharmonic operators. 
    11201074The coefficients may be constant or spatially variable; 
    11211075the description of the coefficients is found in the chapter on lateral physics (\autoref{chap:LDF}). 
    11221076The lateral diffusion of momentum is evaluated using a forward scheme, 
    1123 \ie the velocity appearing in its expression is the \textit{before} velocity in time, 
     1077\ie\ the velocity appearing in its expression is the \textit{before} velocity in time, 
    11241078except for the pure vertical component that appears when a tensor of rotation is used. 
    1125 This latter term is solved implicitly together with the vertical diffusion term (see \autoref{chap:STP}). 
     1079This latter term is solved implicitly together with the vertical diffusion term (see \autoref{chap:TD}). 
    11261080 
    11271081At the lateral boundaries either free slip, 
    11281082no slip or partial slip boundary conditions are applied according to the user's choice (see \autoref{chap:LBC}). 
    11291083 
    1130 \gmcomment{ 
     1084\cmtgm{ 
    11311085  Hyperviscous operators are frequently used in the simulation of turbulent flows to 
    11321086  control the dissipation of unresolved small scale features. 
     
    11371091  In finite difference methods, 
    11381092  the biharmonic operator is frequently the method of choice to achieve this scale selective dissipation since 
    1139   its damping time (\ie its spin down time) scale like $\lambda^{-4}$ for disturbances of wavelength $\lambda$ 
     1093  its damping time (\ie\ its spin down time) scale like $\lambda^{-4}$ for disturbances of wavelength $\lambda$ 
    11401094  (so that short waves damped more rapidelly than long ones), 
    11411095  whereas the Laplace operator damping time scales only like $\lambda^{-2}$. 
    11421096} 
    11431097 
    1144 % ================================================================ 
    1145 \subsection[Iso-level laplacian (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})] 
    1146             {Iso-level laplacian operator (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})} 
     1098%% ================================================================================================= 
     1099\subsection[Iso-level laplacian (\forcode{ln_dynldf_lap})]{Iso-level laplacian operator (\protect\np{ln_dynldf_lap}{ln\_dynldf\_lap})} 
    11471100\label{subsec:DYN_ldf_lap} 
    11481101 
    1149 For lateral iso-level diffusion, the discrete operator is:  
    1150 \begin{equation} 
    1151   \label{eq:dynldf_lap} 
     1102For lateral iso-level diffusion, the discrete operator is: 
     1103\begin{equation} 
     1104  \label{eq:DYN_ldf_lap} 
    11521105  \left\{ 
    11531106    \begin{aligned} 
    1154       D_u^{l{\rm {\bf U}}} =\frac{1}{e_{1u} }\delta_{i+1/2} \left[ {A_T^{lm} 
    1155           \;\chi } \right]-\frac{1}{e_{2u} {\kern 1pt}e_{3u} }\delta_j \left[  
     1107      D_u^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{1u} }\delta_{i+1/2} \left[ {A_T^{lm} 
     1108          \;\chi } \right]-\frac{1}{e_{2u} {\kern 1pt}e_{3u} }\delta_j \left[ 
    11561109        {A_f^{lm} \;e_{3f} \zeta } \right] \\ \\ 
    1157       D_v^{l{\rm {\bf U}}} =\frac{1}{e_{2v} }\delta_{j+1/2} \left[ {A_T^{lm} 
    1158           \;\chi } \right]+\frac{1}{e_{1v} {\kern 1pt}e_{3v} }\delta_i \left[  
     1110      D_v^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{2v} }\delta_{j+1/2} \left[ {A_T^{lm} 
     1111          \;\chi } \right]+\frac{1}{e_{1v} {\kern 1pt}e_{3v} }\delta_i \left[ 
    11591112        {A_f^{lm} \;e_{3f} \zeta } \right] 
    11601113    \end{aligned} 
    11611114  \right. 
    1162 \end{equation}  
    1163  
    1164 As explained in \autoref{subsec:PE_ldf}, 
     1115\end{equation} 
     1116 
     1117As explained in \autoref{subsec:MB_ldf}, 
    11651118this formulation (as the gradient of a divergence and curl of the vorticity) preserves symmetry and 
    1166 ensures a complete separation between the vorticity and divergence parts of the momentum diffusion.  
    1167  
    1168 %-------------------------------------------------------------------------------------------------------------- 
    1169 %           Rotated laplacian operator 
    1170 %-------------------------------------------------------------------------------------------------------------- 
    1171 \subsection[Rotated laplacian (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})] 
    1172             {Rotated laplacian operator (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})} 
     1119ensures a complete separation between the vorticity and divergence parts of the momentum diffusion. 
     1120 
     1121%% ================================================================================================= 
     1122\subsection[Rotated laplacian (\forcode{ln_dynldf_iso})]{Rotated laplacian operator (\protect\np{ln_dynldf_iso}{ln\_dynldf\_iso})} 
    11731123\label{subsec:DYN_ldf_iso} 
    11741124 
    11751125A rotation of the lateral momentum diffusion operator is needed in several cases: 
    1176 for iso-neutral diffusion in the $z$-coordinate (\np{ln\_dynldf\_iso}\forcode{ = .true.}) and 
    1177 for either iso-neutral (\np{ln\_dynldf\_iso}\forcode{ = .true.}) or 
    1178 geopotential (\np{ln\_dynldf\_hor}\forcode{ = .true.}) diffusion in the $s$-coordinate. 
     1126for iso-neutral diffusion in the $z$-coordinate (\np[=.true.]{ln_dynldf_iso}{ln\_dynldf\_iso}) and 
     1127for either iso-neutral (\np[=.true.]{ln_dynldf_iso}{ln\_dynldf\_iso}) or 
     1128geopotential (\np[=.true.]{ln_dynldf_hor}{ln\_dynldf\_hor}) diffusion in the $s$-coordinate. 
    11791129In the partial step case, coordinates are horizontal except at the deepest level and 
    1180 no rotation is performed when \np{ln\_dynldf\_hor}\forcode{ = .true.}. 
     1130no rotation is performed when \np[=.true.]{ln_dynldf_hor}{ln\_dynldf\_hor}. 
    11811131The diffusion operator is defined simply as the divergence of down gradient momentum fluxes on 
    11821132each momentum component. 
     
    11841134The resulting discrete representation is: 
    11851135\begin{equation} 
    1186   \label{eq:dyn_ldf_iso} 
     1136  \label{eq:DYN_ldf_iso} 
    11871137  \begin{split} 
    11881138    D_u^{l\textbf{U}} &= \frac{1}{e_{1u} \, e_{2u} \, e_{3u} } \\ 
     
    12081158                -e_{2f} \; r_{1f} \,\overline{\overline {\delta_{k+1/2}[v]}}^{\,i+1/2,\,k}} 
    12091159            \right)} \right]}    \right. \\ 
    1210     & \qquad +\ \delta_j \left[ {A_T^{lm} \left( {\frac{e_{1t}\,e_{3t} }{e_{2t}  
     1160    & \qquad +\ \delta_j \left[ {A_T^{lm} \left( {\frac{e_{1t}\,e_{3t} }{e_{2t} 
    12111161            }\,\delta_{j} [v] - e_{1t}\, r_{2t} 
    12121162            \,\overline{\overline {\delta_{k+1/2} [v]}} ^{\,j,\,k}} 
    12131163        \right)} \right] \\ 
    1214     & \qquad +\ \delta_k \left[ {A_{vw}^{lm} \left( {-e_{2v} \, r_{1vw} \,\overline{\overline  
     1164    & \qquad +\ \delta_k \left[ {A_{vw}^{lm} \left( {-e_{2v} \, r_{1vw} \,\overline{\overline 
    12151165              {\delta_{i+1/2} [v]}}^{\,i+1/2,\,k+1/2} }\right.} \right. \\ 
    12161166    &  \ \qquad \qquad \qquad \quad\ 
    12171167    - e_{1v} \, r_{2vw} \,\overline{\overline {\delta_{j+1/2} [v]}} ^{\,j+1/2,\,k+1/2} \\ 
    1218     & \left. {\left. { \ \qquad \qquad \qquad \ \ \ \left. {\  
     1168    & \left. {\left. { \ \qquad \qquad \qquad \ \ \ \left. {\ 
    12191169                +\frac{e_{1v}\, e_{2v} }{e_{3vw} }\,\left( {r_{1vw}^2+r_{2vw}^2} 
    1220                 \right)\,\delta_{k+1/2} [v]} \right)} \right]\;\;\;} \right\}  
     1170                \right)\,\delta_{k+1/2} [v]} \right)} \right]\;\;\;} \right\} 
    12211171  \end{split} 
    12221172\end{equation} 
    12231173where $r_1$ and $r_2$ are the slopes between the surface along which the diffusion operator acts and 
    1224 the surface of computation ($z$- or $s$-surfaces).  
     1174the surface of computation ($z$- or $s$-surfaces). 
    12251175The way these slopes are evaluated is given in the lateral physics chapter (\autoref{chap:LDF}). 
    12261176 
    1227 %-------------------------------------------------------------------------------------------------------------- 
    1228 %           Iso-level bilaplacian operator 
    1229 %-------------------------------------------------------------------------------------------------------------- 
    1230 \subsection[Iso-level bilaplacian (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})] 
    1231             {Iso-level bilaplacian operator (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})} 
     1177%% ================================================================================================= 
     1178\subsection[Iso-level bilaplacian (\forcode{ln_dynldf_bilap})]{Iso-level bilaplacian operator (\protect\np{ln_dynldf_bilap}{ln\_dynldf\_bilap})} 
    12321179\label{subsec:DYN_ldf_bilap} 
    12331180 
    1234 The lateral fourth order operator formulation on momentum is obtained by applying \autoref{eq:dynldf_lap} twice. 
     1181The lateral fourth order operator formulation on momentum is obtained by applying \autoref{eq:DYN_ldf_lap} twice. 
    12351182It requires an additional assumption on boundary conditions: 
    12361183the first derivative term normal to the coast depends on the free or no-slip lateral boundary conditions chosen, 
    12371184while the third derivative terms normal to the coast are set to zero (see \autoref{chap:LBC}). 
    1238 %%% 
    1239 \gmcomment{add a remark on the the change in the position of the coefficient} 
    1240 %%% 
    1241  
    1242 % ================================================================ 
    1243 %           Vertical diffusion term 
    1244 % ================================================================ 
    1245 \section{Vertical diffusion term (\protect\mdl{dynzdf})} 
     1185\cmtgm{add a remark on the the change in the position of the coefficient} 
     1186 
     1187%% ================================================================================================= 
     1188\section[Vertical diffusion term (\textit{dynzdf.F90})]{Vertical diffusion term (\protect\mdl{dynzdf})} 
    12461189\label{sec:DYN_zdf} 
    1247 %----------------------------------------------namzdf------------------------------------------------------ 
    1248  
    1249 \nlst{namzdf}  
    1250 %------------------------------------------------------------------------------------------------------------- 
    1251  
    1252 Options are defined through the \ngn{namzdf} namelist variables. 
     1190 
     1191Options are defined through the \nam{zdf}{zdf} namelist variables. 
    12531192The large vertical diffusion coefficient found in the surface mixed layer together with high vertical resolution implies that in the case of explicit time stepping there would be too restrictive a constraint on the time step. 
    12541193Two time stepping schemes can be used for the vertical diffusion term: 
    12551194$(a)$ a forward time differencing scheme 
    1256 (\np{ln\_zdfexp}\forcode{ = .true.}) using a time splitting technique (\np{nn\_zdfexp} $>$ 1) or 
    1257 $(b)$ a backward (or implicit) time differencing scheme (\np{ln\_zdfexp}\forcode{ = .false.}) 
    1258 (see \autoref{chap:STP}). 
    1259 Note that namelist variables \np{ln\_zdfexp} and \np{nn\_zdfexp} apply to both tracers and dynamics.  
     1195(\np[=.true.]{ln_zdfexp}{ln\_zdfexp}) using a time splitting technique (\np{nn_zdfexp}{nn\_zdfexp} $>$ 1) or 
     1196$(b)$ a backward (or implicit) time differencing scheme (\np[=.false.]{ln_zdfexp}{ln\_zdfexp}) 
     1197(see \autoref{chap:TD}). 
     1198Note that namelist variables \np{ln_zdfexp}{ln\_zdfexp} and \np{nn_zdfexp}{nn\_zdfexp} apply to both tracers and dynamics. 
    12601199 
    12611200The formulation of the vertical subgrid scale physics is the same whatever the vertical coordinate is. 
    1262 The vertical diffusion operators given by \autoref{eq:PE_zdf} take the following semi-discrete space form: 
    1263 \[ 
    1264   % \label{eq:dynzdf} 
     1201The vertical diffusion operators given by \autoref{eq:MB_zdf} take the following semi-discrete space form: 
     1202\[ 
     1203  % \label{eq:DYN_zdf} 
    12651204  \left\{ 
    12661205    \begin{aligned} 
     
    12801219the vertical turbulent momentum fluxes, 
    12811220\begin{equation} 
    1282   \label{eq:dynzdf_sbc} 
     1221  \label{eq:DYN_zdf_sbc} 
    12831222  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{z=1} 
    12841223  = \frac{1}{\rho_o} \binom{\tau_u}{\tau_v } 
     
    12861225where $\left( \tau_u ,\tau_v \right)$ are the two components of the wind stress vector in 
    12871226the (\textbf{i},\textbf{j}) coordinate system. 
    1288 The high mixing coefficients in the surface mixed layer ensure that the surface wind stress is distributed in  
     1227The high mixing coefficients in the surface mixed layer ensure that the surface wind stress is distributed in 
    12891228the vertical over the mixed layer depth. 
    12901229If the vertical mixing coefficient is small (when no mixed layer scheme is used) 
     
    12931232 
    12941233The turbulent flux of momentum at the bottom of the ocean is specified through a bottom friction parameterisation 
    1295 (see \autoref{sec:ZDF_bfr}) 
    1296  
    1297 % ================================================================ 
    1298 % External Forcing 
    1299 % ================================================================ 
     1234(see \autoref{sec:ZDF_drg}) 
     1235 
     1236%% ================================================================================================= 
    13001237\section{External forcings} 
    13011238\label{sec:DYN_forcing} 
     
    13031240Besides the surface and bottom stresses (see the above section) 
    13041241which are introduced as boundary conditions on the vertical mixing, 
    1305 three other forcings may enter the dynamical equations by affecting the surface pressure gradient.  
    1306  
    1307 (1) When \np{ln\_apr\_dyn}\forcode{ = .true.} (see \autoref{sec:SBC_apr}), 
     1242three other forcings may enter the dynamical equations by affecting the surface pressure gradient. 
     1243 
     1244(1) When \np[=.true.]{ln_apr_dyn}{ln\_apr\_dyn} (see \autoref{sec:SBC_apr}), 
    13081245the atmospheric pressure is taken into account when computing the surface pressure gradient. 
    13091246 
    1310 (2) When \np{ln\_tide\_pot}\forcode{ = .true.} and \np{ln\_tide}\forcode{ = .true.} (see \autoref{sec:SBC_tide}), 
     1247(2) When \np[=.true.]{ln_tide_pot}{ln\_tide\_pot} and \np[=.true.]{ln_tide}{ln\_tide} (see \autoref{sec:SBC_tide}), 
    13111248the tidal potential is taken into account when computing the surface pressure gradient. 
    13121249 
    1313 (3) When \np{nn\_ice\_embd}\forcode{ = 2} and LIM or CICE is used 
    1314 (\ie when the sea-ice is embedded in the ocean), 
     1250(3) When \np[=2]{nn_ice_embd}{nn\_ice\_embd} and LIM or CICE is used 
     1251(\ie\ when the sea-ice is embedded in the ocean), 
    13151252the snow-ice mass is taken into account when computing the surface pressure gradient. 
    13161253 
    1317  
    1318 \gmcomment{ missing : the lateral boundary condition !!!   another external forcing 
     1254\cmtgm{ missing : the lateral boundary condition !!!   another external forcing 
    13191255 } 
    13201256 
    1321 % ================================================================ 
    1322 % Wetting and drying  
    1323 % ================================================================ 
     1257%% ================================================================================================= 
    13241258\section{Wetting and drying } 
    13251259\label{sec:DYN_wetdry} 
     1260 
    13261261There are two main options for wetting and drying code (wd): 
    13271262(a) an iterative limiter (il) and (b) a directional limiter (dl). 
    1328 The directional limiter is based on the scheme developed by \cite{WarnerEtal13} for RO 
     1263The directional limiter is based on the scheme developed by \cite{warner.defne.ea_CG13} for RO 
    13291264MS 
    1330 which was in turn based on ideas developed for POM by \cite{Oey06}. The iterative 
     1265which was in turn based on ideas developed for POM by \cite{oey_OM06}. The iterative 
    13311266limiter is a new scheme.  The iterative limiter is activated by setting $\mathrm{ln\_wd\_il} = \mathrm{.true.}$ 
    13321267and $\mathrm{ln\_wd\_dl} = \mathrm{.false.}$. The directional limiter is activated 
    13331268by setting $\mathrm{ln\_wd\_dl} = \mathrm{.true.}$ and $\mathrm{ln\_wd\_il} = \mathrm{.false.}$. 
    13341269 
    1335 \nlst{namwad} 
     1270\begin{listing} 
     1271  \nlst{namwad} 
     1272  \caption{\forcode{&namwad}} 
     1273  \label{lst:namwad} 
     1274\end{listing} 
    13361275 
    13371276The following terminology is used. The depth of the topography (positive downwards) 
    1338 at each $(i,j)$ point is the quantity stored in array $\mathrm{ht\_wd}$ in the NEMO code. 
     1277at each $(i,j)$ point is the quantity stored in array $\mathrm{ht\_wd}$ in the \NEMO\ code. 
    13391278The height of the free surface (positive upwards) is denoted by $ \mathrm{ssh}$. Given the sign 
    13401279conventions used, the water depth, $h$, is the height of the free surface plus the depth of the 
     
    13441283covered by water. They require the topography specified with a model 
    13451284configuration to have negative depths at points where the land is higher than the 
    1346 topography's reference sea-level. The vertical grid in NEMO is normally computed relative to an 
     1285topography's reference sea-level. The vertical grid in \NEMO\ is normally computed relative to an 
    13471286initial state with zero sea surface height elevation. 
    13481287The user can choose to compute the vertical grid and heights in the model relative to 
     
    13631302All these configurations have used pure sigma coordinates. It is expected that 
    13641303the wetting and drying code will work in domains with more general s-coordinates provided 
    1365 the coordinates are pure sigma in the region where wetting and drying actually occurs.  
     1304the coordinates are pure sigma in the region where wetting and drying actually occurs. 
    13661305 
    13671306The next sub-section descrbies the directional limiter and the following sub-section the iterative limiter. 
    13681307The final sub-section covers some additional considerations that are relevant to both schemes. 
    13691308 
    1370  
    1371 %----------------------------------------------------------------------------------------- 
    13721309%   Iterative limiters 
    1373 %----------------------------------------------------------------------------------------- 
    1374 \subsection   [Directional limiter (\textit{wet\_dry})] 
    1375          {Directional limiter (\mdl{wet\_dry})} 
     1310%% ================================================================================================= 
     1311\subsection[Directional limiter (\textit{wet\_dry.F90})]{Directional limiter (\mdl{wet\_dry})} 
    13761312\label{subsec:DYN_wd_directional_limiter} 
     1313 
    13771314The principal idea of the directional limiter is that 
    1378 water should not be allowed to flow out of a dry tracer cell (i.e. one whose water depth is less than rn\_wdmin1). 
     1315water should not be allowed to flow out of a dry tracer cell (i.e. one whose water depth is less than \np{rn_wdmin1}{rn\_wdmin1}). 
    13791316 
    13801317All the changes associated with this option are made to the barotropic solver for the non-linear 
     
    13861323 
    13871324The flux across each $u$-face of a tracer cell is multiplied by a factor zuwdmask (an array which depends on ji and jj). 
    1388 If the user sets ln\_wd\_dl\_ramp = .False. then zuwdmask is 1 when the 
    1389 flux is from a cell with water depth greater than rn\_wdmin1 and 0 otherwise. If the user sets 
    1390 ln\_wd\_dl\_ramp = .True. the flux across the face is ramped down as the water depth decreases 
    1391 from 2 * rn\_wdmin1 to rn\_wdmin1. The use of this ramp reduced grid-scale noise in idealised test cases. 
     1325If the user sets \np[=.false.]{ln_wd_dl_ramp}{ln\_wd\_dl\_ramp} then zuwdmask is 1 when the 
     1326flux is from a cell with water depth greater than \np{rn_wdmin1}{rn\_wdmin1} and 0 otherwise. If the user sets 
     1327\np[=.true.]{ln_wd_dl_ramp}{ln\_wd\_dl\_ramp} the flux across the face is ramped down as the water depth decreases 
     1328from 2 * \np{rn_wdmin1}{rn\_wdmin1} to \np{rn_wdmin1}{rn\_wdmin1}. The use of this ramp reduced grid-scale noise in idealised test cases. 
    13921329 
    13931330At the point where the flux across a $u$-face is multiplied by zuwdmask , we have chosen 
     
    13991336treatment in the calculation of the flux of mass across the cell face. 
    14001337 
    1401  
    1402 \cite{WarnerEtal13} state that in their scheme the velocity masks at the cell faces for the baroclinic 
     1338\cite{warner.defne.ea_CG13} state that in their scheme the velocity masks at the cell faces for the baroclinic 
    14031339timesteps are set to 0 or 1 depending on whether the average of the masks over the barotropic sub-steps is respectively less than 
    14041340or greater than 0.5. That scheme does not conserve tracers in integrations started from constant tracer 
    14051341fields (tracers independent of $x$, $y$ and $z$). Our scheme conserves constant tracers because 
    14061342the velocities used at the tracer cell faces on the baroclinic timesteps are carefully calculated by dynspg\_ts 
    1407 to equal their mean value during the barotropic steps. If the user sets ln\_wd\_dl\_bc = .True., the 
    1408 baroclinic velocities are also multiplied by a suitably weighted average of zuwdmask.   
    1409  
    1410 %----------------------------------------------------------------------------------------- 
     1343to equal their mean value during the barotropic steps. If the user sets \np[=.true.]{ln_wd_dl_bc}{ln\_wd\_dl\_bc}, the 
     1344baroclinic velocities are also multiplied by a suitably weighted average of zuwdmask. 
     1345 
    14111346%   Iterative limiters 
    1412 %----------------------------------------------------------------------------------------- 
    1413  
    1414 \subsection   [Iterative limiter (\textit{wet\_dry})] 
    1415          {Iterative limiter (\mdl{wet\_dry})} 
     1347 
     1348%% ================================================================================================= 
     1349\subsection[Iterative limiter (\textit{wet\_dry.F90})]{Iterative limiter (\mdl{wet\_dry})} 
    14161350\label{subsec:DYN_wd_iterative_limiter} 
    14171351 
    1418 \subsubsection [Iterative flux limiter (\textit{wet\_dry})] 
    1419          {Iterative flux limiter (\mdl{wet\_dry})} 
    1420 \label{subsubsec:DYN_wd_il_spg_limiter} 
     1352%% ================================================================================================= 
     1353\subsubsection[Iterative flux limiter (\textit{wet\_dry.F90})]{Iterative flux limiter (\mdl{wet\_dry})} 
     1354\label{subsec:DYN_wd_il_spg_limiter} 
    14211355 
    14221356The iterative limiter modifies the fluxes across the faces of cells that are either already ``dry'' 
     
    14261360 
    14271361The continuity equation for the total water depth in a column 
    1428 \begin{equation} \label{dyn_wd_continuity} 
    1429  \frac{\partial h}{\partial t} + \mathbf{\nabla.}(h\mathbf{u}) = 0 . 
     1362\begin{equation} 
     1363  \label{eq:DYN_wd_continuity} 
     1364  \frac{\partial h}{\partial t} + \mathbf{\nabla.}(h\mathbf{u}) = 0 . 
    14301365\end{equation} 
    14311366can be written in discrete form  as 
    14321367 
    1433 \begin{align} \label{dyn_wd_continuity_2} 
    1434 \frac{e_1 e_2}{\Delta t} ( h_{i,j}(t_{n+1}) - h_{i,j}(t_e) )  
    1435 &= - ( \mathrm{flxu}_{i+1,j} - \mathrm{flxu}_{i,j}  + \mathrm{flxv}_{i,j+1} - \mathrm{flxv}_{i,j} ) \\ 
    1436 &= \mathrm{zzflx}_{i,j} . 
     1368\begin{align} 
     1369  \label{eq:DYN_wd_continuity_2} 
     1370  \frac{e_1 e_2}{\Delta t} ( h_{i,j}(t_{n+1}) - h_{i,j}(t_e) ) 
     1371  &= - ( \mathrm{flxu}_{i+1,j} - \mathrm{flxu}_{i,j}  + \mathrm{flxv}_{i,j+1} - \mathrm{flxv}_{i,j} ) \\ 
     1372  &= \mathrm{zzflx}_{i,j} . 
    14371373\end{align} 
    14381374 
     
    14471383(zzflxp) and fluxes that are into the cell (zzflxn).  Clearly 
    14481384 
    1449 \begin{equation} \label{dyn_wd_zzflx_p_n_1} 
    1450 \mathrm{zzflx}_{i,j} = \mathrm{zzflxp}_{i,j} + \mathrm{zzflxn}_{i,j} .   
     1385\begin{equation} 
     1386  \label{eq:DYN_wd_zzflx_p_n_1} 
     1387  \mathrm{zzflx}_{i,j} = \mathrm{zzflxp}_{i,j} + \mathrm{zzflxn}_{i,j} . 
    14511388\end{equation} 
    14521389 
     
    14591396$\mathrm{zcoef}_{i,j}^{(m)}$ such that: 
    14601397 
    1461 \begin{equation} \label{dyn_wd_continuity_coef} 
    1462 \begin{split} 
    1463 \mathrm{zzflxp}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxp}^{(0)}_{i,j} \\ 
    1464 \mathrm{zzflxn}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxn}^{(0)}_{i,j} 
    1465 \end{split} 
     1398\begin{equation} 
     1399  \label{eq:DYN_wd_continuity_coef} 
     1400  \begin{split} 
     1401    \mathrm{zzflxp}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxp}^{(0)}_{i,j} \\ 
     1402    \mathrm{zzflxn}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxn}^{(0)}_{i,j} 
     1403  \end{split} 
    14661404\end{equation} 
    14671405 
     
    14711409The iteration is initialised by setting 
    14721410 
    1473 \begin{equation} \label{dyn_wd_zzflx_initial} 
    1474 \mathrm{zzflxp^{(0)}}_{i,j} = \mathrm{zzflxp}_{i,j} , \quad  \mathrm{zzflxn^{(0)}}_{i,j} = \mathrm{zzflxn}_{i,j} .  
     1411\begin{equation} 
     1412  \label{eq:DYN_wd_zzflx_initial} 
     1413  \mathrm{zzflxp^{(0)}}_{i,j} = \mathrm{zzflxp}_{i,j} , \quad  \mathrm{zzflxn^{(0)}}_{i,j} = \mathrm{zzflxn}_{i,j} . 
    14751414\end{equation} 
    14761415 
    14771416The fluxes out of cell $(i,j)$ are updated at the $m+1$th iteration if the depth of the 
    14781417cell on timestep $t_e$, namely $h_{i,j}(t_e)$, is less than the total flux out of the cell 
    1479 times the timestep divided by the cell area. Using (\ref{dyn_wd_continuity_2}) this 
     1418times the timestep divided by the cell area. Using (\autoref{eq:DYN_wd_continuity_2}) this 
    14801419condition is 
    14811420 
    1482 \begin{equation} \label{dyn_wd_continuity_if} 
    1483 h_{i,j}(t_e)  - \mathrm{rn\_wdmin1} <  \frac{\Delta t}{e_1 e_2} ( \mathrm{zzflxp}^{(m)}_{i,j} + \mathrm{zzflxn}^{(m)}_{i,j} ) . 
    1484 \end{equation} 
    1485  
    1486 Rearranging (\ref{dyn_wd_continuity_if}) we can obtain an expression for the maximum 
     1421\begin{equation} 
     1422  \label{eq:DYN_wd_continuity_if} 
     1423  h_{i,j}(t_e)  - \mathrm{rn\_wdmin1} <  \frac{\Delta t}{e_1 e_2} ( \mathrm{zzflxp}^{(m)}_{i,j} + \mathrm{zzflxn}^{(m)}_{i,j} ) . 
     1424\end{equation} 
     1425 
     1426Rearranging (\autoref{eq:DYN_wd_continuity_if}) we can obtain an expression for the maximum 
    14871427outward flux that can be allowed and still maintain the minimum wet depth: 
    14881428 
    1489 \begin{equation} \label{dyn_wd_max_flux} 
    1490 \begin{split} 
    1491 \mathrm{zzflxp}^{(m+1)}_{i,j} = \Big[ (h_{i,j}(t_e) & - \mathrm{rn\_wdmin1} - \mathrm{rn\_wdmin2})  \frac{e_1 e_2}{\Delta t} \phantom{]} \\ 
    1492 \phantom{[} & -  \mathrm{zzflxn}^{(m)}_{i,j} \Big] 
    1493 \end{split} 
    1494 \end{equation} 
    1495  
    1496 Note a small tolerance ($\mathrm{rn\_wdmin2}$) has been introduced here {\it [Q: Why is 
    1497 this necessary/desirable?]}. Substituting from (\ref{dyn_wd_continuity_coef}) gives an 
     1429\begin{equation} 
     1430  \label{eq:DYN_wd_max_flux} 
     1431  \begin{split} 
     1432    \mathrm{zzflxp}^{(m+1)}_{i,j} = \Big[ (h_{i,j}(t_e) & - \mathrm{rn\_wdmin1} - \mathrm{rn\_wdmin2})  \frac{e_1 e_2}{\Delta t} \phantom{]} \\ 
     1433    \phantom{[} & -  \mathrm{zzflxn}^{(m)}_{i,j} \Big] 
     1434  \end{split} 
     1435\end{equation} 
     1436 
     1437Note a small tolerance ($\mathrm{rn\_wdmin2}$) has been introduced here {\itshape [Q: Why is 
     1438this necessary/desirable?]}. Substituting from (\autoref{eq:DYN_wd_continuity_coef}) gives an 
    14981439expression for the coefficient needed to multiply the outward flux at this cell in order 
    14991440to avoid drying. 
    15001441 
    1501 \begin{equation} \label{dyn_wd_continuity_nxtcoef} 
    1502 \begin{split} 
    1503 \mathrm{zcoef}^{(m+1)}_{i,j} = \Big[ (h_{i,j}(t_e) & - \mathrm{rn\_wdmin1} - \mathrm{rn\_wdmin2})  \frac{e_1 e_2}{\Delta t} \phantom{]} \\ 
    1504 \phantom{[} & -  \mathrm{zzflxn}^{(m)}_{i,j} \Big] \frac{1}{ \mathrm{zzflxp}^{(0)}_{i,j} }  
    1505 \end{split} 
     1442\begin{equation} 
     1443  \label{eq:DYN_wd_continuity_nxtcoef} 
     1444  \begin{split} 
     1445    \mathrm{zcoef}^{(m+1)}_{i,j} = \Big[ (h_{i,j}(t_e) & - \mathrm{rn\_wdmin1} - \mathrm{rn\_wdmin2})  \frac{e_1 e_2}{\Delta t} \phantom{]} \\ 
     1446    \phantom{[} & -  \mathrm{zzflxn}^{(m)}_{i,j} \Big] \frac{1}{ \mathrm{zzflxp}^{(0)}_{i,j} } 
     1447  \end{split} 
    15061448\end{equation} 
    15071449 
     
    15181460directional limiter does. 
    15191461 
    1520  
    1521 %---------------------------------------------------------------------------------------- 
    15221462%      Surface pressure gradients 
    1523 %---------------------------------------------------------------------------------------- 
    1524 \subsubsection   [Modification of surface pressure gradients (\textit{dynhpg})] 
    1525          {Modification of surface pressure gradients (\mdl{dynhpg})} 
    1526 \label{subsubsec:DYN_wd_il_spg} 
     1463%% ================================================================================================= 
     1464\subsubsection[Modification of surface pressure gradients (\textit{dynhpg.F90})]{Modification of surface pressure gradients (\mdl{dynhpg})} 
     1465\label{subsec:DYN_wd_il_spg} 
    15271466 
    15281467At ``dry'' points the water depth is usually close to $\mathrm{rn\_wdmin1}$. If the 
     
    15371476neighbouring $(i+1,j)$ and $(i,j)$ tracer points.  zcpx is calculated using two logicals 
    15381477variables, $\mathrm{ll\_tmp1}$ and $\mathrm{ll\_tmp2}$ which are evaluated for each grid 
    1539 column.  The three possible combinations are illustrated in figure \ref{Fig_WAD_dynhpg}. 
    1540  
    1541 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1542 \begin{figure}[!ht] \begin{center} 
    1543 \includegraphics[width=0.8\textwidth]{Fig_WAD_dynhpg} 
    1544 \caption{ \label{Fig_WAD_dynhpg} 
    1545 Illustrations of the three possible combinations of the logical variables controlling the 
    1546 limiting of the horizontal pressure gradient in wetting and drying regimes} 
    1547 \end{center}\end{figure} 
    1548 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     1478column.  The three possible combinations are illustrated in \autoref{fig:DYN_WAD_dynhpg}. 
     1479 
     1480\begin{figure}[!ht] 
     1481  \centering 
     1482  \includegraphics[width=0.66\textwidth]{DYN_WAD_dynhpg} 
     1483  \caption[Combinations controlling the limiting of the horizontal pressure gradient in 
     1484  wetting and drying regimes]{ 
     1485    Three possible combinations of the logical variables controlling the 
     1486    limiting of the horizontal pressure gradient in wetting and drying regimes} 
     1487  \label{fig:DYN_WAD_dynhpg} 
     1488\end{figure} 
    15491489 
    15501490The first logical, $\mathrm{ll\_tmp1}$, is set to true if and only if the water depth at 
     
    15531493of the topography at the two points: 
    15541494 
    1555 \begin{equation} \label{dyn_ll_tmp1} 
    1556 \begin{split} 
    1557 \mathrm{ll\_tmp1}  = & \mathrm{MIN(sshn(ji,jj), sshn(ji+1,jj))} > \\ 
     1495\begin{equation} 
     1496  \label{eq:DYN_ll_tmp1} 
     1497  \begin{split} 
     1498    \mathrm{ll\_tmp1}  = & \mathrm{MIN(sshn(ji,jj), sshn(ji+1,jj))} > \\ 
    15581499                     & \quad \mathrm{MAX(-ht\_wd(ji,jj), -ht\_wd(ji+1,jj))\  .and.} \\ 
    1559 & \mathrm{MAX(sshn(ji,jj) + ht\_wd(ji,jj),} \\ 
    1560 & \mathrm{\phantom{MAX(}sshn(ji+1,jj) + ht\_wd(ji+1,jj))} >\\ 
    1561 & \quad\quad\mathrm{rn\_wdmin1 + rn\_wdmin2 } 
    1562 \end{split} 
     1500                     & \mathrm{MAX(sshn(ji,jj) + ht\_wd(ji,jj),} \\ 
     1501                     & \mathrm{\phantom{MAX(}sshn(ji+1,jj) + ht\_wd(ji+1,jj))} >\\ 
     1502                     & \quad\quad\mathrm{rn\_wdmin1 + rn\_wdmin2 } 
     1503  \end{split} 
    15631504\end{equation} 
    15641505 
     
    15671508at the two points plus $\mathrm{rn\_wdmin1} + \mathrm{rn\_wdmin2}$ 
    15681509 
    1569 \begin{equation} \label{dyn_ll_tmp2} 
    1570 \begin{split} 
    1571 \mathrm{ ll\_tmp2 } = & \mathrm{( ABS( sshn(ji,jj) - sshn(ji+1,jj) ) > 1.E-12 )\ .AND.}\\ 
    1572 & \mathrm{( MAX(sshn(ji,jj), sshn(ji+1,jj)) > } \\ 
    1573 & \mathrm{\phantom{(} MAX(-ht\_wd(ji,jj), -ht\_wd(ji+1,jj)) + rn\_wdmin1 + rn\_wdmin2}) . 
    1574 \end{split} 
     1510\begin{equation} 
     1511  \label{eq:DYN_ll_tmp2} 
     1512  \begin{split} 
     1513    \mathrm{ ll\_tmp2 } = & \mathrm{( ABS( sshn(ji,jj) - sshn(ji+1,jj) ) > 1.E-12 )\ .AND.}\\ 
     1514    & \mathrm{( MAX(sshn(ji,jj), sshn(ji+1,jj)) > } \\ 
     1515    & \mathrm{\phantom{(} MAX(-ht\_wd(ji,jj), -ht\_wd(ji+1,jj)) + rn\_wdmin1 + rn\_wdmin2}) . 
     1516  \end{split} 
    15751517\end{equation} 
    15761518 
     
    15881530conditions. 
    15891531 
    1590 \subsubsection   [Additional considerations (\textit{usrdef\_zgr})] 
    1591          {Additional considerations (\mdl{usrdef\_zgr})} 
    1592 \label{subsubsec:WAD_additional} 
     1532%% ================================================================================================= 
     1533\subsubsection[Additional considerations (\textit{usrdef\_zgr.F90})]{Additional considerations (\mdl{usrdef\_zgr})} 
     1534\label{subsec:DYN_WAD_additional} 
    15931535 
    15941536In the very shallow water where wetting and drying occurs the parametrisation of 
     
    16001542in uncoupled integrations the net surface heat fluxes need to be appropriately limited. 
    16011543 
    1602 %---------------------------------------------------------------------------------------- 
    16031544%      The WAD test cases 
    1604 %---------------------------------------------------------------------------------------- 
    1605 \subsection   [The WAD test cases (\textit{usrdef\_zgr})] 
    1606          {The WAD test cases (\mdl{usrdef\_zgr})} 
    1607 \label{WAD_test_cases} 
     1545%% ================================================================================================= 
     1546\subsection[The WAD test cases (\textit{usrdef\_zgr.F90})]{The WAD test cases (\mdl{usrdef\_zgr})} 
     1547\label{subsec:DYN_WAD_test_cases} 
    16081548 
    16091549See the WAD tests MY\_DOC documention for details of the WAD test cases. 
    16101550 
    1611  
    1612  
    1613 % ================================================================ 
    1614 % Time evolution term  
    1615 % ================================================================ 
    1616 \section{Time evolution term (\protect\mdl{dynnxt})} 
     1551%% ================================================================================================= 
     1552\section[Time evolution term (\textit{dynnxt.F90})]{Time evolution term (\protect\mdl{dynnxt})} 
    16171553\label{sec:DYN_nxt} 
    16181554 
    1619 %----------------------------------------------namdom---------------------------------------------------- 
    1620  
    1621 \nlst{namdom}  
    1622 %------------------------------------------------------------------------------------------------------------- 
    1623  
    1624 Options are defined through the \ngn{namdom} namelist variables. 
     1555Options are defined through the \nam{dom}{dom} namelist variables. 
    16251556The general framework for dynamics time stepping is a leap-frog scheme, 
    1626 \ie a three level centred time scheme associated with an Asselin time filter (cf. \autoref{chap:STP}). 
     1557\ie\ a three level centred time scheme associated with an Asselin time filter (cf. \autoref{chap:TD}). 
    16271558The scheme is applied to the velocity, except when 
    16281559using the flux form of momentum advection (cf. \autoref{sec:DYN_adv_cor_flux}) 
    1629 in the variable volume case (\key{vvl} defined), 
    1630 where it has to be applied to the thickness weighted velocity (see \autoref{sec:A_momentum})   
     1560in the variable volume case (\texttt{vvl?} defined), 
     1561where it has to be applied to the thickness weighted velocity (see \autoref{sec:SCOORD_momentum}) 
    16311562 
    16321563$\bullet$ vector invariant form or linear free surface 
    1633 (\np{ln\_dynhpg\_vec}\forcode{ = .true.} ; \key{vvl} not defined): 
    1634 \[ 
    1635   % \label{eq:dynnxt_vec} 
     1564(\np[=.true.]{ln_dynhpg_vec}{ln\_dynhpg\_vec} ; \texttt{vvl?} not defined): 
     1565\[ 
     1566  % \label{eq:DYN_nxt_vec} 
    16361567  \left\{ 
    16371568    \begin{aligned} 
     
    16431574 
    16441575$\bullet$ flux form and nonlinear free surface 
    1645 (\np{ln\_dynhpg\_vec}\forcode{ = .false.} ; \key{vvl} defined): 
    1646 \[ 
    1647   % \label{eq:dynnxt_flux} 
     1576(\np[=.false.]{ln_dynhpg_vec}{ln\_dynhpg\_vec} ; \texttt{vvl?} defined): 
     1577\[ 
     1578  % \label{eq:DYN_nxt_flux} 
    16481579  \left\{ 
    16491580    \begin{aligned} 
     
    16561587where RHS is the right hand side of the momentum equation, 
    16571588the subscript $f$ denotes filtered values and $\gamma$ is the Asselin coefficient. 
    1658 $\gamma$ is initialized as \np{nn\_atfp} (namelist parameter). 
    1659 Its default value is \np{nn\_atfp}\forcode{ = 10.e-3}. 
     1589$\gamma$ is initialized as \np{nn_atfp}{nn\_atfp} (namelist parameter). 
     1590Its default value is \np[=10.e-3]{nn_atfp}{nn\_atfp}. 
    16601591In both cases, the modified Asselin filter is not applied since perfect conservation is not an issue for 
    16611592the momentum equations. 
     
    16651596and only array swapping and Asselin filtering is done in \mdl{dynnxt}. 
    16661597 
    1667 % ================================================================ 
    1668 \biblio 
    1669  
    1670 \pindex 
     1598\subinc{\input{../../global/epilogue}} 
    16711599 
    16721600\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_LBC.tex

    r10614 r11831  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter — Lateral Boundary Condition (LBC)  
    6 % ================================================================ 
     4 
    75\chapter{Lateral Boundary Condition (LBC)} 
    86\label{chap:LBC} 
    97 
    10 \minitoc 
    11  
    12 \newpage 
    13  
    14 %gm% add here introduction to this chapter 
    15  
    16 % ================================================================ 
    17 % Boundary Condition at the Coast 
    18 % ================================================================ 
    19 \section{Boundary condition at the coast (\protect\np{rn\_shlat})} 
     8\thispagestyle{plain} 
     9 
     10\chaptertoc 
     11 
     12\paragraph{Changes record} ~\\ 
     13 
     14{\footnotesize 
     15  \begin{tabularx}{\textwidth}{l||X|X} 
     16    Release & Author(s) & Modifications \\ 
     17    \hline 
     18    {\em   4.0} & {\em ...} & {\em ...} \\ 
     19    {\em   3.6} & {\em ...} & {\em ...} \\ 
     20    {\em   3.4} & {\em ...} & {\em ...} \\ 
     21    {\em <=3.4} & {\em ...} & {\em ...} 
     22  \end{tabularx} 
     23} 
     24 
     25\clearpage 
     26 
     27\cmtgm{Add here introduction to this chapter} 
     28 
     29%% ================================================================================================= 
     30\section[Boundary condition at the coast (\forcode{rn_shlat})]{Boundary condition at the coast (\protect\np{rn_shlat}{rn\_shlat})} 
    2031\label{sec:LBC_coast} 
    21 %--------------------------------------------nam_lbc------------------------------------------------------- 
    22  
    23 \nlst{namlbc}  
    24 %-------------------------------------------------------------------------------------------------------------- 
    25  
    26 %The lateral ocean boundary conditions contiguous to coastlines are Neumann conditions for heat and salt (no flux across boundaries) and Dirichlet conditions for momentum (ranging from free-slip to "strong" no-slip). They are handled automatically by the mask system (see \autoref{subsec:DOM_msk}).  
    27  
    28 %OPA allows land and topography grid points in the computational domain due to the presence of continents or islands, and includes the use of a full or partial step representation of bottom topography. The computation is performed over the whole domain, \ie we do not try to restrict the computation to ocean-only points. This choice has two motivations. Firstly, working on ocean only grid points overloads the code and harms the code readability. Secondly, and more importantly, it drastically reduces the vector portion of the computation, leading to a dramatic increase of CPU time requirement on vector computers.  The current section describes how the masking affects the computation of the various terms of the equations with respect to the boundary condition at solid walls. The process of defining which areas are to be masked is described in \autoref{subsec:DOM_msk}. 
    29  
    30 Options are defined through the \ngn{namlbc} namelist variables. 
     32 
     33\begin{listing} 
     34  \nlst{namlbc} 
     35  \caption{\forcode{&namlbc}} 
     36  \label{lst:namlbc} 
     37\end{listing} 
     38 
     39%The lateral ocean boundary conditions contiguous to coastlines are Neumann conditions for heat and salt 
     40%(no flux across boundaries) and Dirichlet conditions for momentum (ranging from free-slip to "strong" no-slip). 
     41%They are handled automatically by the mask system (see \autoref{subsec:DOM_msk}). 
     42 
     43%OPA allows land and topography grid points in the computational domain due to the presence of continents or islands, 
     44%and includes the use of a full or partial step representation of bottom topography. 
     45%The computation is performed over the whole domain, \ie\ we do not try to restrict the computation to ocean-only points. 
     46%This choice has two motivations. 
     47%Firstly, working on ocean only grid points overloads the code and harms the code readability. 
     48%Secondly, and more importantly, it drastically reduces the vector portion of the computation, 
     49%leading to a dramatic increase of CPU time requirement on vector computers. 
     50%The current section describes how the masking affects the computation of the various terms of the equations 
     51%with respect to the boundary condition at solid walls. 
     52%The process of defining which areas are to be masked is described in \autoref{subsec:DOM_msk}. 
     53 
     54Options are defined through the \nam{lbc}{lbc} namelist variables. 
    3155The discrete representation of a domain with complex boundaries (coastlines and bottom topography) leads to 
    3256arrays that include large portions where a computation is not required as the model variables remain at zero. 
     
    4064Since most of the boundary conditions consist of a zero flux across the solid boundaries, 
    4165they can be simply applied by multiplying variables by the correct mask arrays, 
    42 \ie the mask array of the grid point where the flux is evaluated. 
     66\ie\ the mask array of the grid point where the flux is evaluated. 
    4367For example, the heat flux in the \textbf{i}-direction is evaluated at $u$-points. 
    4468Evaluating this quantity as, 
    4569 
    4670\[ 
    47   % \label{eq:lbc_aaaa} 
     71  % \label{eq:LBC_aaaa} 
    4872  \frac{A^{lT} }{e_1 }\frac{\partial T}{\partial i}\equiv \frac{A_u^{lT} 
    4973  }{e_{1u} } \; \delta_{i+1 / 2} \left[ T \right]\;\;mask_u 
     
    5175(where mask$_{u}$ is the mask array at a $u$-point) ensures that the heat flux is zero inside land and 
    5276at the boundaries, since mask$_{u}$ is zero at solid boundaries which in this case are defined at $u$-points 
    53 (normal velocity $u$ remains zero at the coast) (\autoref{fig:LBC_uv}).  
    54  
    55 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     77(normal velocity $u$ remains zero at the coast) (\autoref{fig:LBC_uv}). 
     78 
    5679\begin{figure}[!t] 
    57   \begin{center} 
    58     \includegraphics[width=0.90\textwidth]{Fig_LBC_uv} 
    59     \caption{ 
    60       \protect\label{fig:LBC_uv} 
    61       Lateral boundary (thick line) at T-level. 
    62       The velocity normal to the boundary is set to zero. 
    63     } 
    64   \end{center} 
     80  \centering 
     81  \includegraphics[width=0.66\textwidth]{LBC_uv} 
     82  \caption[Lateral boundary at $T$-level]{ 
     83    Lateral boundary (thick line) at T-level. 
     84    The velocity normal to the boundary is set to zero.} 
     85  \label{fig:LBC_uv} 
    6586\end{figure} 
    66 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    6787 
    6888For momentum the situation is a bit more complex as two boundary conditions must be provided along the coast 
     
    7898and is required in order to compute the vorticity at the coast. 
    7999Four different types of lateral boundary condition are available, 
    80 controlled by the value of the \np{rn\_shlat} namelist parameter 
     100controlled by the value of the \np{rn_shlat}{rn\_shlat} namelist parameter 
    81101(The value of the mask$_{f}$ array along the coastline is set equal to this parameter). 
    82102These are: 
    83103 
    84 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    85104\begin{figure}[!p] 
    86   \begin{center} 
    87     \includegraphics[width=0.90\textwidth]{Fig_LBC_shlat} 
    88     \caption{ 
    89       \protect\label{fig:LBC_shlat} 
    90       lateral boundary condition 
    91       (a) free-slip ($rn\_shlat=0$); 
    92       (b) no-slip ($rn\_shlat=2$); 
    93       (c) "partial" free-slip ($0<rn\_shlat<2$) and 
    94       (d) "strong" no-slip ($2<rn\_shlat$). 
    95       Implied "ghost" velocity inside land area is display in grey. 
    96     } 
    97   \end{center} 
     105  \centering 
     106  \includegraphics[width=0.66\textwidth]{LBC_shlat} 
     107  \caption[Lateral boundary conditions]{ 
     108    Lateral boundary conditions 
     109    (a) free-slip                       (\protect\np[=0]{rn_shlat}{rn\_shlat}); 
     110    (b) no-slip                         (\protect\np[=2]{rn_shlat}{rn\_shlat}); 
     111    (c) "partial" free-slip (\forcode{0<}\protect\np[<2]{rn_shlat}{rn\_shlat}) and 
     112    (d) "strong" no-slip    (\forcode{2<}\protect\np{rn_shlat}{rn\_shlat}). 
     113    Implied "ghost" velocity inside land area is display in grey.} 
     114  \label{fig:LBC_shlat} 
    98115\end{figure} 
    99 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    100116 
    101117\begin{description} 
    102118 
    103 \item[free-slip boundary condition (\np{rn\_shlat}\forcode{ = 0}):] the tangential velocity at 
     119\item [free-slip boundary condition ({\np[=0]{rn_shlat}{rn\_shlat}})] the tangential velocity at 
    104120  the coastline is equal to the offshore velocity, 
    105   \ie the normal derivative of the tangential velocity is zero at the coast, 
     121  \ie\ the normal derivative of the tangential velocity is zero at the coast, 
    106122  so the vorticity: mask$_{f}$ array is set to zero inside the land and just at the coast 
    107123  (\autoref{fig:LBC_shlat}-a). 
    108124 
    109 \item[no-slip boundary condition (\np{rn\_shlat}\forcode{ = 2}):] the tangential velocity vanishes at the coastline. 
     125\item [no-slip boundary condition ({\np[=2]{rn_shlat}{rn\_shlat}})] the tangential velocity vanishes at the coastline. 
    110126  Assuming that the tangential velocity decreases linearly from 
    111127  the closest ocean velocity grid point to the coastline, 
     
    113129  the closest ocean velocity gridpoint were of the same magnitude but in the opposite direction 
    114130  (\autoref{fig:LBC_shlat}-b). 
    115   Therefore, the vorticity along the coastlines is given by:  
     131  Therefore, the vorticity along the coastlines is given by: 
    116132 
    117133  \[ 
     
    122138  the no-slip boundary condition, simply by multiplying it by the mask$_{f}$ : 
    123139  \[ 
    124     % \label{eq:lbc_bbbb} 
     140    % \label{eq:LBC_bbbb} 
    125141    \zeta \equiv \frac{1}{e_{1f} {\kern 1pt}e_{2f} }\left( {\delta_{i+1/2} 
    126142        \left[ {e_{2v} \,v} \right]-\delta_{j+1/2} \left[ {e_{1u} \,u} \right]} 
     
    128144  \] 
    129145 
    130 \item["partial" free-slip boundary condition (0$<$\np{rn\_shlat}$<$2):] the tangential velocity at 
    131   the coastline is smaller than the offshore velocity, \ie there is a lateral friction but 
     146\item ["partial" free-slip boundary condition (0$<$\np{rn_shlat}{rn\_shlat}$<$2)] the tangential velocity at 
     147  the coastline is smaller than the offshore velocity, \ie\ there is a lateral friction but 
    132148  not strong enough to make the tangential velocity at the coast vanish (\autoref{fig:LBC_shlat}-c). 
    133149  This can be selected by providing a value of mask$_{f}$ strictly inbetween $0$ and $2$. 
    134150 
    135 \item["strong" no-slip boundary condition (2$<$\np{rn\_shlat}):] the viscous boundary layer is assumed to 
     151\item ["strong" no-slip boundary condition (2$<$\np{rn_shlat}{rn\_shlat})] the viscous boundary layer is assumed to 
    136152  be smaller than half the grid size (\autoref{fig:LBC_shlat}-d). 
    137153  The friction is thus larger than in the no-slip case. 
     
    139155\end{description} 
    140156 
    141 Note that when the bottom topography is entirely represented by the $s$-coor-dinates (pure $s$-coordinate), 
     157Note that when the bottom topography is entirely represented by the $s$-coordinates (pure $s$-coordinate), 
    142158the lateral boundary condition on tangential velocity is of much less importance as 
    143159it is only applied next to the coast where the minimum water depth can be quite shallow. 
    144160 
    145  
    146 % ================================================================ 
    147 % Boundary Condition around the Model Domain 
    148 % ================================================================ 
    149 \section{Model domain boundary condition (\protect\np{jperio})} 
     161%% ================================================================================================= 
     162\section[Model domain boundary condition (\forcode{jperio})]{Model domain boundary condition (\protect\jp{jperio})} 
    150163\label{sec:LBC_jperio} 
    151164 
     
    153166closed, cyclic east-west, cyclic north-south, a north-fold, and combination closed-north fold or 
    154167bi-cyclic east-west and north-fold. 
    155 The north-fold boundary condition is associated with the 3-pole ORCA mesh.  
    156  
    157 % ------------------------------------------------------------------------------------------------------------- 
    158 %        Closed, cyclic (\np{jperio}\forcode{ = 0..2})  
    159 % ------------------------------------------------------------------------------------------------------------- 
    160 \subsection{Closed, cyclic (\protect\np{jperio}\forcode{= [0127]})} 
     168The north-fold boundary condition is associated with the 3-pole ORCA mesh. 
     169 
     170%% ================================================================================================= 
     171\subsection[Closed, cyclic (\forcode{=0,1,2,7})]{Closed, cyclic (\protect\jp{jperio}\forcode{=0,1,2,7})} 
    161172\label{subsec:LBC_jperio012} 
    162173 
    163174The choice of closed or cyclic model domain boundary condition is made by 
    164 setting \np{jperio} to 0, 1, 2 or 7 in namelist \ngn{namcfg}. 
     175setting \jp{jperio} to 0, 1, 2 or 7 in namelist \nam{cfg}{cfg}. 
    165176Each time such a boundary condition is needed, it is set by a call to routine \mdl{lbclnk}. 
    166177The computation of momentum and tracer trends proceeds from $i=2$ to $i=jpi-1$ and from $j=2$ to $j=jpj-1$, 
    167 \ie in the model interior. 
     178\ie\ in the model interior. 
    168179To choose a lateral model boundary condition is to specify the first and last rows and columns of 
    169 the model variables.  
     180the model variables. 
    170181 
    171182\begin{description} 
    172183 
    173 \item[For closed boundary (\np{jperio}\forcode{ = 0})], 
    174   solid walls are imposed at all model boundaries: 
     184\item [For closed boundary (\jp{jperio}\forcode{=0})], solid walls are imposed at all model boundaries: 
    175185  first and last rows and columns are set to zero. 
    176186 
    177 \item[For cyclic east-west boundary (\np{jperio}\forcode{ = 1})], 
    178   first and last rows are set to zero (closed) whilst the first column is set to 
     187\item [For cyclic east-west boundary (\jp{jperio}\forcode{=1})], first and last rows are set to zero (closed) whilst the first column is set to 
    179188  the value of the last-but-one column and the last column to the value of the second one 
    180189  (\autoref{fig:LBC_jperio}-a). 
    181190  Whatever flows out of the eastern (western) end of the basin enters the western (eastern) end. 
    182191 
    183 \item[For cyclic north-south boundary (\np{jperio}\forcode{ = 2})], 
    184   first and last columns are set to zero (closed) whilst the first row is set to 
     192\item [For cyclic north-south boundary (\jp{jperio}\forcode{=2})], first and last columns are set to zero (closed) whilst the first row is set to 
    185193  the value of the last-but-one row and the last row to the value of the second one 
    186194  (\autoref{fig:LBC_jperio}-a). 
    187195  Whatever flows out of the northern (southern) end of the basin enters the southern (northern) end. 
    188196 
    189 \item[Bi-cyclic east-west and north-south boundary (\np{jperio}\forcode{ = 7})] combines cases 1 and 2. 
     197\item [Bi-cyclic east-west and north-south boundary (\jp{jperio}\forcode{=7})] combines cases 1 and 2. 
    190198 
    191199\end{description} 
    192200 
    193 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    194201\begin{figure}[!t] 
    195   \begin{center} 
    196     \includegraphics[width=1.0\textwidth]{Fig_LBC_jperio} 
    197     \caption{ 
    198       \protect\label{fig:LBC_jperio} 
    199       setting of (a) east-west cyclic  (b) symmetric across the equator boundary conditions. 
    200     } 
    201   \end{center} 
     202  \centering 
     203  \includegraphics[width=0.66\textwidth]{LBC_jperio} 
     204  \caption[Setting of east-west cyclic and symmetric across the Equator boundary conditions]{ 
     205    Setting of (a) east-west cyclic (b) symmetric across the Equator boundary conditions} 
     206  \label{fig:LBC_jperio} 
    202207\end{figure} 
    203 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    204  
    205 % ------------------------------------------------------------------------------------------------------------- 
    206 %        North fold (\textit{jperio = 3 }to $6)$  
    207 % ------------------------------------------------------------------------------------------------------------- 
    208 \subsection{North-fold (\protect\np{jperio}\forcode{ = 3..6})} 
     208 
     209%% ================================================================================================= 
     210\subsection[North-fold (\forcode{=3,6})]{North-fold (\protect\jp{jperio}\forcode{=3,6})} 
    209211\label{subsec:LBC_north_fold} 
    210212 
    211213The north fold boundary condition has been introduced in order to handle the north boundary of 
    212214a three-polar ORCA grid. 
    213 Such a grid has two poles in the northern hemisphere (\autoref{fig:MISC_ORCA_msh}, 
    214 and thus requires a specific treatment illustrated in \autoref{fig:North_Fold_T}.  
     215Such a grid has two poles in the northern hemisphere (\autoref{fig:CFGS_ORCA_msh}, 
     216and thus requires a specific treatment illustrated in \autoref{fig:LBC_North_Fold_T}. 
    215217Further information can be found in \mdl{lbcnfd} module which applies the north fold boundary condition. 
    216218 
    217 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    218219\begin{figure}[!t] 
    219   \begin{center} 
    220     \includegraphics[width=0.90\textwidth]{Fig_North_Fold_T} 
    221     \caption{ 
    222       \protect\label{fig:North_Fold_T} 
    223       North fold boundary with a $T$-point pivot and cyclic east-west boundary condition ($jperio=4$), 
    224       as used in ORCA 2, 1/4, and 1/12. 
    225       Pink shaded area corresponds to the inner domain mask (see text). 
    226     } 
    227   \end{center} 
     220  \centering 
     221  \includegraphics[width=0.66\textwidth]{LBC_North_Fold_T} 
     222  \caption[North fold boundary in ORCA 2\deg, 1/4\deg and 1/12\deg]{ 
     223    North fold boundary with a $T$-point pivot and cyclic east-west boundary condition ($jperio=4$), 
     224    as used in ORCA 2\deg, 1/4\deg and 1/12\deg. 
     225    Pink shaded area corresponds to the inner domain mask (see text).} 
     226  \label{fig:LBC_North_Fold_T} 
    228227\end{figure} 
    229 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    230  
    231 % ==================================================================== 
    232 % Exchange with neighbouring processors  
    233 % ==================================================================== 
    234 \section{Exchange with neighbouring processors (\protect\mdl{lbclnk}, \protect\mdl{lib\_mpp})} 
     228 
     229%% ================================================================================================= 
     230\section[Exchange with neighbouring processors (\textit{lbclnk.F90}, \textit{lib\_mpp.F90})]{Exchange with neighbouring processors (\protect\mdl{lbclnk}, \protect\mdl{lib\_mpp})} 
    235231\label{sec:LBC_mpp} 
    236232 
     233\begin{listing} 
     234  \nlst{nammpp} 
     235  \caption{\forcode{&nammpp}} 
     236  \label{lst:nammpp} 
     237\end{listing} 
     238 
    237239For massively parallel processing (mpp), a domain decomposition method is used. 
    238 The basic idea of the method is to split the large computation domain of a numerical experiment into 
    239 several smaller domains and solve the set of equations by addressing independent local problems. 
     240The basic idea of the method is to split the large computation domain of a numerical experiment into several smaller domains and 
     241solve the set of equations by addressing independent local problems. 
    240242Each processor has its own local memory and computes the model equation over a subdomain of the whole model domain. 
    241 The subdomain boundary conditions are specified through communications between processors which 
    242 are organized by explicit statements (message passing method). 
    243  
    244 A big advantage is that the method does not need many modifications of the initial \fortran code. 
    245 From the modeller's point of view, each sub domain running on a processor is identical to the "mono-domain" code. 
    246 In addition, the programmer manages the communications between subdomains, 
    247 and the code is faster when the number of processors is increased. 
    248 The porting of OPA code on an iPSC860 was achieved during Guyon's PhD [Guyon et al. 1994, 1995] 
    249 in collaboration with CETIIS and ONERA. 
    250 The implementation in the operational context and the studies of performance on 
    251 a T3D and T3E Cray computers have been made in collaboration with IDRIS and CNRS. 
     243The subdomain boundary conditions are specified through communications between processors which are organized by 
     244explicit statements (message passing method). 
    252245The present implementation is largely inspired by Guyon's work [Guyon 1995]. 
    253246 
     
    256249depend at the very most on one neighbouring point. 
    257250The only non-local computations concern the vertical physics 
    258 (implicit diffusion, turbulent closure scheme, ...) (delocalization over the whole water column), 
    259 and the solving of the elliptic equation associated with the surface pressure gradient computation 
    260 (delocalization over the whole horizontal domain). 
     251(implicit diffusion, turbulent closure scheme, ...). 
    261252Therefore, a pencil strategy is used for the data sub-structuration: 
    262253the 3D initial domain is laid out on local processor memories following a 2D horizontal topological splitting. 
     
    267258After a computation, a communication phase starts: 
    268259each processor sends to its neighbouring processors the update values of the points corresponding to 
    269 the interior overlapping area to its neighbouring sub-domain (\ie the innermost of the two overlapping rows). 
    270 The communication is done through the Message Passing Interface (MPI). 
     260the interior overlapping area to its neighbouring sub-domain (\ie\ the innermost of the two overlapping rows). 
     261Communications are first done according to the east-west direction and next according to the north-south direction. 
     262There is no specific communications for the corners. 
     263The communication is done through the Message Passing Interface (MPI) and requires \key{mpp\_mpi}. 
     264Use also \key{mpi2} if MPI3 is not available on your computer. 
    271265The data exchanges between processors are required at the very place where 
    272266lateral domain boundary conditions are set in the mono-domain computation: 
    273267the \rou{lbc\_lnk} routine (found in \mdl{lbclnk} module) which manages such conditions is interfaced with 
    274 routines found in \mdl{lib\_mpp} module when running on an MPP computer (\ie when \key{mpp\_mpi} defined). 
    275 It has to be pointed out that when using the MPP version of the model, 
    276 the east-west cyclic boundary condition is done implicitly, 
    277 whilst the south-symmetric boundary condition option is not available. 
    278  
    279 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     268routines found in \mdl{lib\_mpp} module. 
     269The output file \textit{communication\_report.txt} provides the list of which routines do how 
     270many communications during 1 time step of the model.\\ 
     271 
    280272\begin{figure}[!t] 
    281   \begin{center} 
    282     \includegraphics[width=0.90\textwidth]{Fig_mpp} 
    283     \caption{ 
    284       \protect\label{fig:mpp} 
    285       Positioning of a sub-domain when massively parallel processing is used. 
    286     } 
    287   \end{center} 
     273  \centering 
     274  \includegraphics[width=0.66\textwidth]{LBC_mpp} 
     275  \caption{Positioning of a sub-domain when massively parallel processing is used} 
     276  \label{fig:LBC_mpp} 
    288277\end{figure} 
    289 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    290  
    291 In the standard version of \NEMO, the splitting is regular and arithmetic. 
    292 The i-axis is divided by \jp{jpni} and 
    293 the j-axis by \jp{jpnj} for a number of processors \jp{jpnij} most often equal to $jpni \times jpnj$ 
    294 (parameters set in  \ngn{nammpp} namelist). 
    295 Each processor is independent and without message passing or synchronous process, 
    296 programs run alone and access just its own local memory. 
    297 For this reason, the main model dimensions are now the local dimensions of the subdomain (pencil) that 
    298 are named \jp{jpi}, \jp{jpj}, \jp{jpk}. 
     278 
     279In \NEMO, the splitting is regular and arithmetic. 
     280The total number of subdomains corresponds to the number of MPI processes allocated to \NEMO\ when the model is launched 
     281(\ie\ mpirun -np x ./nemo will automatically give x subdomains). 
     282The i-axis is divided by \np{jpni}{jpni} and the j-axis by \np{jpnj}{jpnj}. 
     283These parameters are defined in \nam{mpp}{mpp} namelist. 
     284If \np{jpni}{jpni} and \np{jpnj}{jpnj} are < 1, they will be automatically redefined in the code to give the best domain decomposition 
     285(see bellow). 
     286 
     287Each processor is independent and without message passing or synchronous process, programs run alone and access just its own local memory. 
     288For this reason, 
     289the main model dimensions are now the local dimensions of the subdomain (pencil) that are named \jp{jpi}, \jp{jpj}, \jp{jpk}. 
    299290These dimensions include the internal domain and the overlapping rows. 
    300 The number of rows to exchange (known as the halo) is usually set to one (\jp{jpreci}=1, in \mdl{par\_oce}). 
    301 The whole domain dimensions are named \np{jpiglo}, \np{jpjglo} and \jp{jpk}. 
     291The number of rows to exchange (known as the halo) is usually set to one (nn\_hls=1, in \mdl{par\_oce}, 
     292and must be kept to one until further notice). 
     293The whole domain dimensions are named \jp{jpiglo}, \jp{jpjglo} and \jp{jpk}. 
    302294The relationship between the whole domain and a sub-domain is: 
     295\begin{gather*} 
     296  jpi = ( jpiglo-2\times nn\_hls + (jpni-1) ) / jpni + 2\times nn\_hls \\ 
     297  jpj = ( jpjglo-2\times nn\_hls + (jpnj-1) ) / jpnj + 2\times nn\_hls 
     298\end{gather*} 
     299 
     300One also defines variables nldi and nlei which correspond to the internal domain bounds, and the variables nimpp and njmpp which are the position of the (1,1) grid-point in the global domain (\autoref{fig:LBC_mpp}). Note that since the version 4, there is no more extra-halo area as defined in \autoref{fig:LBC_mpp} so \jp{jpi} is now always equal to nlci and \jp{jpj} equal to nlcj. 
     301 
     302An element of $T_{l}$, a local array (subdomain) corresponds to an element of $T_{g}$, 
     303a global array (whole domain) by the relationship: 
    303304\[ 
    304   jpi = ( jpiglo-2*jpreci + (jpni-1) ) / jpni + 2*jpreci 
    305   jpj = ( jpjglo-2*jprecj + (jpnj-1) ) / jpnj + 2*jprecj 
    306 \] 
    307 where \jp{jpni}, \jp{jpnj} are the number of processors following the i- and j-axis. 
    308  
    309 One also defines variables nldi and nlei which correspond to the internal domain bounds,  
    310 and the variables nimpp and njmpp which are the position of the (1,1) grid-point in the global domain.  
    311 An element of $T_{l}$, a local array (subdomain) corresponds to an element of $T_{g}$, 
    312 a global array (whole domain) by the relationship:  
    313 \[ 
    314   % \label{eq:lbc_nimpp} 
     305  % \label{eq:LBC_nimpp} 
    315306  T_{g} (i+nimpp-1,j+njmpp-1,k) = T_{l} (i,j,k), 
    316307\] 
    317 with  $1 \leq i \leq jpi$, $1  \leq j \leq jpj $ , and  $1  \leq k \leq jpk$. 
    318  
    319 Processors are numbered from 0 to $jpnij-1$, the number is saved in the variable nproc. 
    320 In the standard version, a processor has no more than 
    321 four neighbouring processors named nono (for north), noea (east), noso (south) and nowe (west) and 
    322 two variables, nbondi and nbondj, indicate the relative position of the processor: 
    323 \begin{itemize} 
    324 \item       nbondi = -1    an east neighbour, no west processor, 
    325 \item       nbondi =  0 an east neighbour, a west neighbour, 
    326 \item       nbondi =  1    no east processor, a west neighbour, 
    327 \item       nbondi =  2    no splitting following the i-axis. 
    328 \end{itemize} 
    329 During the simulation, processors exchange data with their neighbours. 
    330 If there is effectively a neighbour, the processor receives variables from this processor on its overlapping row, 
    331 and sends the data issued from internal domain corresponding to the overlapping row of the other processor. 
    332  
    333  
    334 The \NEMO model computes equation terms with the help of mask arrays (0 on land points and 1 on sea points). 
    335 It is easily readable and very efficient in the context of a computer with vectorial architecture. 
    336 However, in the case of a scalar processor, computations over the land regions become more expensive in 
    337 terms of CPU time.  
    338 It is worse when we use a complex configuration with a realistic bathymetry like the global ocean where 
    339 more than 50 \% of points are land points. 
    340 For this reason, a pre-processing tool can be used to choose the mpp domain decomposition with a maximum number of 
    341 only land points processors, which can then be eliminated (\autoref{fig:mppini2}) 
    342 (For example, the mpp\_optimiz tools, available from the DRAKKAR web site). 
    343 This optimisation is dependent on the specific bathymetry employed. 
    344 The user then chooses optimal parameters \jp{jpni}, \jp{jpnj} and \jp{jpnij} with $jpnij < jpni \times jpnj$, 
    345 leading to the elimination of $jpni \times jpnj - jpnij$ land processors. 
    346 When those parameters are specified in \ngn{nammpp} namelist, 
    347 the algorithm in the \rou{inimpp2} routine sets each processor's parameters (nbound, nono, noea,...) so that 
    348 the land-only processors are not taken into account. 
    349  
    350 \gmcomment{Note that the inimpp2 routine is general so that the original inimpp  
    351 routine should be suppressed from the code.} 
    352  
    353 When land processors are eliminated, 
    354 the value corresponding to these locations in the model output files is undefined. 
    355 Note that this is a problem for the meshmask file which requires to be defined over the whole domain. 
    356 Therefore, user should not eliminate land processors when creating a meshmask file 
    357 (\ie when setting a non-zero value to \np{nn\_msh}). 
    358  
    359 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     308with $1 \leq i \leq jpi$, $1  \leq j \leq jpj $ , and  $1  \leq k \leq jpk$. 
     309 
     310The 1-d arrays $mig(1:\jp{jpi})$ and $mjg(1:\jp{jpj})$, defined in \rou{dom\_glo} routine (\mdl{domain} module), should be used to get global domain indices from local domain indices. The 1-d arrays, $mi0(1:\jp{jpiglo})$, $mi1(1:\jp{jpiglo})$ and $mj0(1:\jp{jpjglo})$, $mj1(1:\jp{jpjglo})$ have the reverse purpose and should be used to define loop indices expressed in global domain indices (see examples in \mdl{dtastd} module).\\ 
     311 
     312The \NEMO\ model computes equation terms with the help of mask arrays (0 on land points and 1 on sea points). It is therefore possible that an MPI subdomain contains only land points. To save ressources, we try to supress from the computational domain as much land subdomains as possible. For example if $N_{mpi}$ processes are allocated to NEMO, the domain decomposition will be given by the following equation: 
     313\[ 
     314  N_{mpi} = jpni \times jpnj - N_{land} + N_{useless} 
     315\] 
     316$N_{land}$ is the total number of land subdomains in the domain decomposition defined by \np{jpni}{jpni} and \np{jpnj}{jpnj}. $N_{useless}$ is the number of land subdomains that are kept in the compuational domain in order to make sure that $N_{mpi}$ MPI processes are indeed allocated to a given subdomain. The values of $N_{mpi}$, \np{jpni}{jpni}, \np{jpnj}{jpnj},  $N_{land}$ and $N_{useless}$ are printed in the output file \texttt{ocean.output}. $N_{useless}$ must, of course, be as small as possible to limit the waste of ressources. A warning is issued in  \texttt{ocean.output} if $N_{useless}$ is not zero. Note that non-zero value of $N_{useless}$ is uselly required when using AGRIF as, up to now, the parent grid and each of the child grids must use all the $N_{mpi}$ processes. 
     317 
     318If the domain decomposition is automatically defined (when \np{jpni}{jpni} and \np{jpnj}{jpnj} are < 1), the decomposition chosen by the model will minimise the sub-domain size (defined as $max_{all domains}(jpi \times jpj)$) and maximize the number of eliminated land subdomains. This means that no other domain decomposition (a set of \np{jpni}{jpni} and \np{jpnj}{jpnj} values) will use less processes than $(jpni  \times  jpnj - N_{land})$ and get a smaller subdomain size. 
     319In order to specify $N_{mpi}$ properly (minimize $N_{useless}$), you must run the model once with \np{ln_list}{ln\_list} activated. In this case, the model will start the initialisation phase, print the list of optimum decompositions ($N_{mpi}$, \np{jpni}{jpni} and \np{jpnj}{jpnj}) in \texttt{ocean.output} and directly abort. The maximum value of $N_{mpi}$ tested in this list is given by $max(N_{MPI\_tasks}, jpni \times jpnj)$. For example, run the model on 40 nodes with ln\_list activated and $jpni = 10000$ and $jpnj = 1$, will print the list of optimum domains decomposition from 1 to about 10000. 
     320 
     321Processors are numbered from 0 to $N_{mpi} - 1$. Subdomains containning some ocean points are numbered first from 0 to $jpni * jpnj - N_{land} -1$. The remaining $N_{useless}$ land subdomains are numbered next, which means that, for a given (\np{jpni}{jpni}, \np{jpnj}{jpnj}), the numbers attributed to he ocean subdomains do not vary with $N_{useless}$. 
     322 
     323When land processors are eliminated, the value corresponding to these locations in the model output files is undefined. \np{ln_mskland}{ln\_mskland} must be activated in order avoid Not a Number values in output files. Note that it is better to not eliminate land processors when creating a meshmask file (\ie\ when setting a non-zero value to \np{nn_msh}{nn\_msh}). 
     324 
    360325\begin{figure}[!ht] 
    361   \begin{center} 
    362     \includegraphics[width=0.90\textwidth]{Fig_mppini2} 
    363     \caption { 
    364       \protect\label{fig:mppini2} 
    365       Example of Atlantic domain defined for the CLIPPER projet. 
    366       Initial grid is composed of 773 x 1236 horizontal points. 
    367       (a) the domain is split onto 9 \time 20 subdomains (jpni=9, jpnj=20). 
    368       52 subdomains are land areas. 
    369       (b) 52 subdomains are eliminated (white rectangles) and 
    370       the resulting number of processors really used during the computation is jpnij=128. 
    371     } 
    372   \end{center} 
     326  \centering 
     327  \includegraphics[width=0.66\textwidth]{LBC_mppini2} 
     328  \caption[Atlantic domain defined for the CLIPPER projet]{ 
     329    Example of Atlantic domain defined for the CLIPPER projet. 
     330    Initial grid is composed of 773 x 1236 horizontal points. 
     331    (a) the domain is split onto 9 $times$ 20 subdomains (jpni=9, jpnj=20). 
     332    52 subdomains are land areas. 
     333    (b) 52 subdomains are eliminated (white rectangles) and 
     334    the resulting number of processors really used during the computation is jpnij=128.} 
     335  \label{fig:LBC_mppini2} 
    373336\end{figure} 
    374 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    375  
    376  
    377 % ==================================================================== 
    378 % Unstructured open boundaries BDY  
    379 % ==================================================================== 
     337 
     338%% ================================================================================================= 
    380339\section{Unstructured open boundary conditions (BDY)} 
    381340\label{sec:LBC_bdy} 
    382341 
    383 %-----------------------------------------nambdy-------------------------------------------- 
    384  
    385 \nlst{nambdy}  
    386 %----------------------------------------------------------------------------------------------- 
    387 %-----------------------------------------nambdy_dta-------------------------------------------- 
    388  
    389 \nlst{nambdy_dta}  
    390 %----------------------------------------------------------------------------------------------- 
    391  
    392 Options are defined through the \ngn{nambdy} \ngn{nambdy\_dta} namelist variables. 
    393 The BDY module is the core implementation of open boundary conditions for regional configurations on  
    394 temperature, salinity, barotropic and baroclinic velocities, as well as ice concentration, ice and snow thicknesses). 
    395  
    396 The BDY module was modelled on the OBC module (see NEMO 3.4) and shares many features and 
    397 a similar coding structure \citep{Chanut2005}. 
     342\begin{listing} 
     343  \nlst{nambdy} 
     344  \caption{\forcode{&nambdy}} 
     345  \label{lst:nambdy} 
     346\end{listing} 
     347 
     348\begin{listing} 
     349  \nlst{nambdy_dta} 
     350  \caption{\forcode{&nambdy_dta}} 
     351  \label{lst:nambdy_dta} 
     352\end{listing} 
     353 
     354Options are defined through the \nam{bdy}{bdy} and \nam{bdy_dta}{bdy\_dta} namelist variables. 
     355The BDY module is the core implementation of open boundary conditions for regional configurations on 
     356ocean temperature, salinity, barotropic-baroclinic velocities, ice-snow concentration, thicknesses, temperatures, salinity and melt ponds concentration and thickness. 
     357 
     358The BDY module was modelled on the OBC module (see \NEMO\ 3.4) and shares many features and 
     359a similar coding structure \citep{chanut_rpt05}. 
    398360The specification of the location of the open boundary is completely flexible and 
    399 allows for example the open boundary to follow an isobath or other irregular contour.  
    400 Boundary data files used with versions of NEMO prior to Version 3.4 may need to be re-ordered to work with this version. 
     361allows any type of setup, from regular boundaries to irregular contour (it includes the possibility to set an open boundary able to follow an isobath). 
     362Boundary data files used with versions of \NEMO\ prior to Version 3.4 may need to be re-ordered to work with this version. 
    401363See the section on the Input Boundary Data Files for details. 
    402364 
    403 %---------------------------------------------- 
     365%% ================================================================================================= 
    404366\subsection{Namelists} 
    405 \label{subsec:BDY_namelist} 
    406  
    407 The BDY module is activated by setting \np{ln\_bdy}\forcode{ = .true.} . 
     367\label{subsec:LBC_bdy_namelist} 
     368 
     369The BDY module is activated by setting \np[=.true.]{ln_bdy}{ln\_bdy} . 
    408370It is possible to define more than one boundary ``set'' and apply different boundary conditions to each set. 
    409 The number of boundary sets is defined by \np{nb\_bdy}. 
    410 Each boundary set may be defined as a set of straight line segments in a namelist 
    411 (\np{ln\_coords\_file}\forcode{ = .false.}) or read in from a file (\np{ln\_coords\_file}\forcode{ = .true.}). 
    412 If the set is defined in a namelist, then the namelists \ngn{nambdy\_index} must be included separately, one for each set. 
    413 If the set is defined by a file, then a ``\ifile{coordinates.bdy}'' file must be provided. 
    414 The coordinates.bdy file is analagous to the usual NEMO ``\ifile{coordinates}'' file. 
     371The number of boundary sets is defined by \np{nb_bdy}{nb\_bdy}. 
     372Each boundary set can be either defined as a series of straight line segments directly in the namelist 
     373(\np[=.false.]{ln_coords_file}{ln\_coords\_file}, and a namelist block \nam{bdy_index}{bdy\_index} must be included for each set) or read in from a file (\np[=.true.]{ln_coords_file}{ln\_coords\_file}, and a ``\ifile{coordinates.bdy}'' file must be provided). 
     374The coordinates.bdy file is analagous to the usual \NEMO\ ``\ifile{coordinates}'' file. 
    415375In the example above, there are two boundary sets, the first of which is defined via a file and 
    416 the second is defined in a namelist. 
    417 For more details of the definition of the boundary geometry see section \autoref{subsec:BDY_geometry}. 
     376the second is defined in the namelist. 
     377For more details of the definition of the boundary geometry see section \autoref{subsec:LBC_bdy_geometry}. 
    418378 
    419379For each boundary set a boundary condition has to be chosen for the barotropic solution 
    420 (``u2d'':sea-surface height and barotropic velocities), for the baroclinic velocities (``u3d''),  
    421 for the active tracers \footnote{The BDY module does not deal with passive tracers at this version} (``tra''), and sea-ice (``ice''). 
    422 For each set of variables there is a choice of algorithm and a choice for the data, 
    423 eg. for the active tracers the algorithm is set by \np{cn\_tra} and the choice of data is set by \np{nn\_tra\_dta}.\\  
     380(``u2d'':sea-surface height and barotropic velocities), for the baroclinic velocities (``u3d''), 
     381for the active tracers \footnote{The BDY module does not deal with passive tracers at this version} (``tra''), and for sea-ice (``ice''). 
     382For each set of variables one has to choose an algorithm and the boundary data (set resp. by \np{cn_tra}{cn\_tra} and \np{nn_tra_dta}{nn\_tra\_dta} for tracers).\\ 
    424383 
    425384The choice of algorithm is currently as follows: 
    426385 
    427386\begin{description} 
    428 \item[\forcode{'none'}:] No boundary condition applied. 
     387\item [\forcode{'none'}:] No boundary condition applied. 
    429388  So the solution will ``see'' the land points around the edge of the edge of the domain. 
    430 \item[\forcode{'specified'}:] Specified boundary condition applied (only available for baroclinic velocity and tracer variables). 
    431 \item[\forcode{'neumann'}:] Value at the boundary are duplicated (No gradient). Only available for baroclinic velocity and tracer variables. 
    432 \item[\forcode{'frs'}:] Flow Relaxation Scheme (FRS) available for all variables. 
    433 \item[\forcode{'Orlanski'}:] Orlanski radiation scheme (fully oblique) for barotropic, baroclinic and tracer variables.  
    434 \item[\forcode{'Orlanski_npo'}:] Orlanski radiation scheme for barotropic, baroclinic and tracer variables.  
    435 \item[\forcode{'flather'}:] Flather radiation scheme for the barotropic variables only. 
     389\item [\forcode{'specified'}:] Specified boundary condition applied (only available for baroclinic velocity and tracer variables). 
     390\item [\forcode{'neumann'}:] Value at the boundary are duplicated (No gradient). Only available for baroclinic velocity and tracer variables. 
     391\item [\forcode{'frs'}:] Flow Relaxation Scheme (FRS) available for all variables. 
     392\item [\forcode{'Orlanski'}:] Orlanski radiation scheme (fully oblique) for barotropic, baroclinic and tracer variables. 
     393\item [\forcode{'Orlanski_npo'}:] Orlanski radiation scheme for barotropic, baroclinic and tracer variables. 
     394\item [\forcode{'flather'}:] Flather radiation scheme for the barotropic variables only. 
    436395\end{description} 
    437396 
    438 The main choice for the boundary data is to use initial conditions as boundary data 
    439 (\np{nn\_tra\_dta}\forcode{ = 0}) or to use external data from a file (\np{nn\_tra\_dta}\forcode{ = 1}). 
    440 In case the 3d velocity data contain the total velocity (ie, baroclinic and barotropic velocity),  
    441 the bdy code can derived baroclinic and barotropic velocities by setting \np{ln\_full\_vel}\forcode{ = .true. } 
     397The boundary data is either set to initial conditions 
     398(\np[=0]{nn_tra_dta}{nn\_tra\_dta}) or forced with external data from a file (\np[=1]{nn_tra_dta}{nn\_tra\_dta}). 
     399In case the 3d velocity data contain the total velocity (ie, baroclinic and barotropic velocity), 
     400the bdy code can derived baroclinic and barotropic velocities by setting \np[=.true.]{ln_full_vel}{ln\_full\_vel} 
    442401For the barotropic solution there is also the option to use tidal harmonic forcing either by 
    443 itself (\np{nn\_dyn2d\_dta}\forcode{ = 2}) or in addition to other external data (\np{nn\_dyn2d\_dta}\forcode{ = 3}).\\ 
    444 Sea-ice salinity, temperature and age data at the boundary are constant and defined repectively by \np{rn\_ice\_sal}, \np{rn\_ice\_tem} and \np{rn\_ice\_age}.  
    445  
    446 If external boundary data is required then the \ngn{nambdy\_dta} namelist must be defined. 
    447 One \ngn{nambdy\_dta} namelist is required for each boundary set in the order in which 
    448 the boundary sets are defined in nambdy. 
    449 In the example given, two boundary sets have been defined. The first one is reading data file in the \ngn{nambdy\_dta} namelist shown above  
    450 and the second one is using data from intial condition (no namelist bloc needed). 
     402itself (\np[=2]{nn_dyn2d_dta}{nn\_dyn2d\_dta}) or in addition to other external data (\np[=3]{nn_dyn2d_dta}{nn\_dyn2d\_dta}).\\ 
     403If not set to initial conditions, sea-ice salinity, temperatures and melt ponds data at the boundary can either be read in a file or defined as constant (by \np{rn_ice_sal}{rn\_ice\_sal}, \np{rn_ice_tem}{rn\_ice\_tem}, \np{rn_ice_apnd}{rn\_ice\_apnd}, \np{rn_ice_hpnd}{rn\_ice\_hpnd}). Ice age is constant and defined by \np{rn_ice_age}{rn\_ice\_age}. 
     404 
     405If external boundary data is required then the \nam{bdy_dta}{bdy\_dta} namelist must be defined. 
     406One \nam{bdy_dta}{bdy\_dta} namelist is required for each boundary set, adopting the same order of indexes in which the boundary sets are defined in nambdy. 
     407In the example given, two boundary sets have been defined. The first one is reading data file in the \nam{bdy_dta}{bdy\_dta} namelist shown above 
     408and the second one is using data from intial condition (no namelist block needed). 
    451409The boundary data is read in using the fldread module, 
    452 so the \ngn{nambdy\_dta} namelist is in the format required for fldread. 
    453 For each variable required, the filename, the frequency of the files and 
    454 the frequency of the data in the files is given. 
    455 Also whether or not time-interpolation is required and whether the data is climatological (time-cyclic) data.\\ 
     410so the \nam{bdy_dta}{bdy\_dta} namelist is in the format required for fldread. 
     411For each required variable, the filename, the frequency of the files and 
     412the frequency of the data in the files are given. 
     413Also whether or not time-interpolation is required and whether the data is climatological (time-cyclic) data. 
     414For sea-ice salinity, temperatures and melt ponds, reading the files are skipped and constant values are used if filenames are defined as {'NOT USED'}.\\ 
    456415 
    457416There is currently an option to vertically interpolate the open boundary data onto the native grid at run-time. 
    458 If \np{nn\_bdy\_jpk} $< -1$, it is assumed that the lateral boundary data are already on the native grid.  
    459 However, if \np{nn\_bdy\_jpk} is set to the number of vertical levels present in the boundary data,  
    460 a bilinear interpolation onto the native grid will be triggered at runtime.  
    461 For this to be successful the additional variables: $gdept$, $gdepu$, $gdepv$, $e3t$, $e3u$ and $e3v$, are required to be present in the lateral boundary files.  
    462 These correspond to the depths and scale factors of the input data,  
     417If \np{nn_bdy_jpk}{nn\_bdy\_jpk}$<-1$, it is assumed that the lateral boundary data are already on the native grid. 
     418However, if \np{nn_bdy_jpk}{nn\_bdy\_jpk} is set to the number of vertical levels present in the boundary data, 
     419a bilinear interpolation onto the native grid will be triggered at runtime. 
     420For this to be successful the additional variables: $gdept$, $gdepu$, $gdepv$, $e3t$, $e3u$ and $e3v$, are required to be present in the lateral boundary files. 
     421These correspond to the depths and scale factors of the input data, 
    463422the latter used to make any adjustment to the velocity fields due to differences in the total water depths between the two vertical grids.\\ 
    464423 
    465 In the example namelists given, two boundary sets are defined. 
     424In the example of given namelists, two boundary sets are defined. 
    466425The first set is defined via a file and applies FRS conditions to temperature and salinity and 
    467426Flather conditions to the barotropic variables. No condition specified for the baroclinic velocity and sea-ice. 
     
    469428Tidal harmonic forcing is also used. 
    470429The second set is defined in a namelist. 
    471 FRS conditions are applied on temperature and salinity and climatological data is read from initial condition files.  
    472  
    473 %---------------------------------------------- 
     430FRS conditions are applied on temperature and salinity and climatological data is read from initial condition files. 
     431 
     432%% ================================================================================================= 
    474433\subsection{Flow relaxation scheme} 
    475 \label{subsec:BDY_FRS_scheme} 
    476  
    477 The Flow Relaxation Scheme (FRS) \citep{Davies_QJRMS76,Engerdahl_Tel95}, 
     434\label{subsec:LBC_bdy_FRS_scheme} 
     435 
     436The Flow Relaxation Scheme (FRS) \citep{davies_QJRMS76,engedahl_T95}, 
    478437applies a simple relaxation of the model fields to externally-specified values over 
    479438a zone next to the edge of the model domain. 
    480439Given a model prognostic variable $\Phi$ 
    481440\[ 
    482   % \label{eq:bdy_frs1} 
     441  % \label{eq:LBC_bdy_frs1} 
    483442  \Phi(d) = \alpha(d)\Phi_{e}(d) + (1-\alpha(d))\Phi_{m}(d)\;\;\;\;\; d=1,N 
    484443\] 
     
    489448the prognostic equation for $\Phi$ of the form: 
    490449\[ 
    491   % \label{eq:bdy_frs2} 
     450  % \label{eq:LBC_bdy_frs2} 
    492451  -\frac{1}{\tau}\left(\Phi - \Phi_{e}\right) 
    493452\] 
    494453where the relaxation time scale $\tau$ is given by a function of $\alpha$ and the model time step $\Delta t$: 
    495454\[ 
    496   % \label{eq:bdy_frs3} 
     455  % \label{eq:LBC_bdy_frs3} 
    497456  \tau = \frac{1-\alpha}{\alpha}  \,\rdt 
    498457\] 
     
    500459is relaxed towards the external conditions over the rest of the FRS zone. 
    501460The application of a relaxation zone helps to prevent spurious reflection of 
    502 outgoing signals from the model boundary.  
     461outgoing signals from the model boundary. 
    503462 
    504463The function $\alpha$ is specified as a $tanh$ function: 
    505464\[ 
    506   % \label{eq:bdy_frs4} 
     465  % \label{eq:LBC_bdy_frs4} 
    507466  \alpha(d) = 1 - \tanh\left(\frac{d-1}{2}\right),       \quad d=1,N 
    508467\] 
    509 The width of the FRS zone is specified in the namelist as \np{nn\_rimwidth}. 
     468The width of the FRS zone is specified in the namelist as \np{nn_rimwidth}{nn\_rimwidth}. 
    510469This is typically set to a value between 8 and 10. 
    511470 
    512 %---------------------------------------------- 
     471%% ================================================================================================= 
    513472\subsection{Flather radiation scheme} 
    514 \label{subsec:BDY_flather_scheme} 
    515  
    516 The \citet{Flather_JPO94} scheme is a radiation condition on the normal, 
     473\label{subsec:LBC_bdy_flather_scheme} 
     474 
     475The \citet{flather_JPO94} scheme is a radiation condition on the normal, 
    517476depth-mean transport across the open boundary. 
    518477It takes the form 
    519 \begin{equation}  \label{eq:bdy_fla1} 
    520 U = U_{e} + \frac{c}{h}\left(\eta - \eta_{e}\right), 
     478\begin{equation} 
     479  \label{eq:LBC_bdy_fla1} 
     480  U = U_{e} + \frac{c}{h}\left(\eta - \eta_{e}\right), 
    521481\end{equation} 
    522482where $U$ is the depth-mean velocity normal to the boundary and $\eta$ is the sea surface height, 
     
    527487the external depth-mean normal velocity, 
    528488plus a correction term that allows gravity waves generated internally to exit the model boundary. 
    529 Note that the sea-surface height gradient in \autoref{eq:bdy_fla1} is a spatial gradient across the model boundary, 
     489Note that the sea-surface height gradient in \autoref{eq:LBC_bdy_fla1} is a spatial gradient across the model boundary, 
    530490so that $\eta_{e}$ is defined on the $T$ points with $nbr=1$ and $\eta$ is defined on the $T$ points with $nbr=2$. 
    531 $U$ and $U_{e}$ are defined on the $U$ or $V$ points with $nbr=1$, \ie between the two $T$ grid points. 
    532  
    533 %---------------------------------------------- 
     491$U$ and $U_{e}$ are defined on the $U$ or $V$ points with $nbr=1$, \ie\ between the two $T$ grid points. 
     492 
     493%% ================================================================================================= 
    534494\subsection{Orlanski radiation scheme} 
    535 \label{subsec:BDY_orlanski_scheme} 
    536  
    537 The Orlanski scheme is based on the algorithm described by \citep{Marchesiello2001}, hereafter MMS. 
     495\label{subsec:LBC_bdy_orlanski_scheme} 
     496 
     497The Orlanski scheme is based on the algorithm described by \citep{marchesiello.mcwilliams.ea_OM01}, hereafter MMS. 
    538498 
    539499The adaptive Orlanski condition solves a wave plus relaxation equation at the boundary: 
    540500\begin{equation} 
    541 \frac{\partial\phi}{\partial t} + c_x \frac{\partial\phi}{\partial x} + c_y \frac{\partial\phi}{\partial y} = 
    542                                                 -\frac{1}{\tau}(\phi - \phi^{ext}) 
    543 \label{eq:wave_continuous} 
     501  \label{eq:LBC_wave_continuous} 
     502  \frac{\partial\phi}{\partial t} + c_x \frac{\partial\phi}{\partial x} + c_y \frac{\partial\phi}{\partial y} = 
     503  -\frac{1}{\tau}(\phi - \phi^{ext}) 
    544504\end{equation} 
    545505 
     
    547507velocities are diagnosed from the model fields as: 
    548508 
    549 \begin{equation} \label{eq:cx} 
    550 c_x = -\frac{\partial\phi}{\partial t}\frac{\partial\phi / \partial x}{(\partial\phi /\partial x)^2 + (\partial\phi /\partial y)^2} 
     509\begin{equation} 
     510  \label{eq:LBC_cx} 
     511  c_x = -\frac{\partial\phi}{\partial t}\frac{\partial\phi / \partial x}{(\partial\phi /\partial x)^2 + (\partial\phi /\partial y)^2} 
    551512\end{equation} 
    552513\begin{equation} 
    553 \label{eq:cy} 
    554 c_y = -\frac{\partial\phi}{\partial t}\frac{\partial\phi / \partial y}{(\partial\phi /\partial x)^2 + (\partial\phi /\partial y)^2} 
     514  \label{eq:LBC_cy} 
     515  c_y = -\frac{\partial\phi}{\partial t}\frac{\partial\phi / \partial y}{(\partial\phi /\partial x)^2 + (\partial\phi /\partial y)^2} 
    555516\end{equation} 
    556517 
    557518(As noted by MMS, this is a circular diagnosis of the phase speeds which only makes sense on a discrete grid). 
    558 Equation (\autoref{eq:wave_continuous}) is defined adaptively depending on the sign of the phase velocity normal to the boundary $c_x$. 
     519Equation (\autoref{eq:LBC_wave_continuous}) is defined adaptively depending on the sign of the phase velocity normal to the boundary $c_x$. 
    559520For $c_x$ outward, we have 
    560521 
     
    566527 
    567528\begin{equation} 
    568 \tau = \tau_{in}\,\,\,;\,\,\, c_x = c_y = 0 
    569 \label{eq:tau_in} 
     529  \label{eq:LBC_tau_in} 
     530  \tau = \tau_{in}\,\,\,;\,\,\, c_x = c_y = 0 
    570531\end{equation} 
    571532 
    572 Generally the relaxation time scale at inward propagation points \np{(rn\_time\_dmp}) is set much shorter than the time scale at outward propagation 
    573 points (\np{rn\_time\_dmp\_out}) so that the solution is constrained more strongly by the external data at inward propagation points. 
    574 See \autoref{subsec:BDY_relaxation} for detailed on the spatial shape of the scaling.\\  
    575 The ``normal propagation of oblique radiation'' or NPO approximation (called \forcode{'orlanski_npo'}) involves assuming  
    576 that $c_y$ is zero in equation (\autoref{eq:wave_continuous}), but including 
    577 this term in the denominator of equation (\autoref{eq:cx}). Both versions of the scheme are options in BDY. Equations 
    578 (\autoref{eq:wave_continuous}) - (\autoref{eq:tau_in}) correspond to equations (13) - (15) and (2) - (3) in MMS.\\ 
    579  
    580 %---------------------------------------------- 
     533Generally the relaxation time scale at inward propagation points (\np{rn_time_dmp}{rn\_time\_dmp}) is set much shorter than the time scale at outward propagation 
     534points (\np{rn_time_dmp_out}{rn\_time\_dmp\_out}) so that the solution is constrained more strongly by the external data at inward propagation points. 
     535See \autoref{subsec:LBC_bdy_relaxation} for detailed on the spatial shape of the scaling.\\ 
     536The ``normal propagation of oblique radiation'' or NPO approximation (called \forcode{'orlanski_npo'}) involves assuming 
     537that $c_y$ is zero in equation (\autoref{eq:LBC_wave_continuous}), but including 
     538this term in the denominator of equation (\autoref{eq:LBC_cx}). Both versions of the scheme are options in BDY. Equations 
     539(\autoref{eq:LBC_wave_continuous}) - (\autoref{eq:LBC_tau_in}) correspond to equations (13) - (15) and (2) - (3) in MMS.\\ 
     540 
     541%% ================================================================================================= 
    581542\subsection{Relaxation at the boundary} 
    582 \label{subsec:BDY_relaxation} 
    583  
    584 In addition to a specific boundary condition specified as \np{cn\_tra} and \np{cn\_dyn3d}, relaxation on baroclinic velocities and tracers variables are available.  
    585 It is control by the namelist parameter \np{ln\_tra\_dmp} and \np{ln\_dyn3d\_dmp} for each boundary set. 
    586  
    587 The relaxation time scale value (\np{rn\_time\_dmp} and \np{rn\_time\_dmp\_out}, $\tau$) are defined at the boundaries itself.  
    588 This time scale ($\alpha$) is weighted by the distance ($d$) from the boundary over \np{nn\_rimwidth} cells ($N$): 
     543\label{subsec:LBC_bdy_relaxation} 
     544 
     545In addition to a specific boundary condition specified as \np{cn_tra}{cn\_tra} and \np{cn_dyn3d}{cn\_dyn3d}, relaxation on baroclinic velocities and tracers variables are available. 
     546It is control by the namelist parameter \np{ln_tra_dmp}{ln\_tra\_dmp} and \np{ln_dyn3d_dmp}{ln\_dyn3d\_dmp} for each boundary set. 
     547 
     548The relaxation time scale value (\np{rn_time_dmp}{rn\_time\_dmp} and \np{rn_time_dmp_out}{rn\_time\_dmp\_out}, $\tau$) are defined at the boundaries itself. 
     549This time scale ($\alpha$) is weighted by the distance ($d$) from the boundary over \np{nn_rimwidth}{nn\_rimwidth} cells ($N$): 
    589550 
    590551\[ 
     
    592553\] 
    593554 
    594 The same scaling is applied in the Orlanski damping.  
    595  
    596 %---------------------------------------------- 
     555The same scaling is applied in the Orlanski damping. 
     556 
     557%% ================================================================================================= 
    597558\subsection{Boundary geometry} 
    598 \label{subsec:BDY_geometry} 
     559\label{subsec:LBC_bdy_geometry} 
    599560 
    600561Each open boundary set is defined as a list of points. 
    601562The information is stored in the arrays $nbi$, $nbj$, and $nbr$ in the $idx\_bdy$ structure. 
    602 The $nbi$ and $nbj$ arrays define the local $(i,j)$ indices of each point in the boundary zone and 
    603 the $nbr$ array defines the discrete distance from the boundary with $nbr=1$ meaning that 
    604 the point is next to the edge of the model domain and $nbr>1$ showing that 
    605 the point is increasingly further away from the edge of the model domain. 
     563The $nbi$ and $nbj$ arrays define the local $(i,j)$ indexes of each point in the boundary zone and 
     564the $nbr$ array defines the discrete distance from the boundary: $nbr=1$ means that 
     565the boundary point is next to the edge of the model domain, while $nbr>1$ means that 
     566the boundary point is increasingly further away from the edge of the model domain. 
    606567A set of $nbi$, $nbj$, and $nbr$ arrays is defined for each of the $T$, $U$ and $V$ grids. 
    607 Figure \autoref{fig:LBC_bdy_geom} shows an example of an irregular boundary.  
     568\autoref{fig:LBC_bdy_geom} shows an example of an irregular boundary. 
    608569 
    609570The boundary geometry for each set may be defined in a namelist nambdy\_index or 
    610571by reading in a ``\ifile{coordinates.bdy}'' file. 
    611572The nambdy\_index namelist defines a series of straight-line segments for north, east, south and west boundaries. 
    612 One nambdy\_index namelist bloc is needed for each boundary condition defined by indexes.  
    613 For the northern boundary, \np{nbdysegn} gives the number of segments, 
    614 \np{jpjnob} gives the $j$ index for each segment and \np{jpindt} and 
    615 \np{jpinft} give the start and end $i$ indices for each segment with similar for the other boundaries. 
     573One nambdy\_index namelist block is needed for each boundary condition defined by indexes. 
     574For the northern boundary, \texttt{nbdysegn} gives the number of segments, 
     575\jp{jpjnob} gives the $j$ index for each segment and \jp{jpindt} and 
     576\jp{jpinft} give the start and end $i$ indices for each segment with similar for the other boundaries. 
    616577These segments define a list of $T$ grid points along the outermost row of the boundary ($nbr\,=\, 1$). 
    617 The code deduces the $U$ and $V$ points and also the points for $nbr\,>\, 1$ if \np{nn\_rimwidth}\forcode{ > 1}. 
     578The code deduces the $U$ and $V$ points and also the points for $nbr\,>\, 1$ if \np[>1]{nn_rimwidth}{nn\_rimwidth}. 
    618579 
    619580The boundary geometry may also be defined from a ``\ifile{coordinates.bdy}'' file. 
    620 Figure \autoref{fig:LBC_nc_header} gives an example of the header information from such a file. 
     581\autoref{fig:LBC_nc_header} gives an example of the header information from such a file, based on the description of geometrical setup given above. 
    621582The file should contain the index arrays for each of the $T$, $U$ and $V$ grids. 
    622583The arrays must be in order of increasing $nbr$. 
     
    624585Typically this file will be used to generate external boundary data via interpolation and so 
    625586will also contain the latitudes and longitudes of each point as shown. 
    626 However, this is not necessary to run the model.  
     587However, this is not necessary to run the model. 
    627588 
    628589For some choices of irregular boundary the model domain may contain areas of ocean which 
    629590are not part of the computational domain. 
    630 For example if an open boundary is defined along an isobath, say at the shelf break, 
     591For example, if an open boundary is defined along an isobath, say at the shelf break, 
    631592then the areas of ocean outside of this boundary will need to be masked out. 
    632 This can be done by reading a mask file defined as \np{cn\_mask\_file} in the nam\_bdy namelist. 
     593This can be done by reading a mask file defined as \np{cn_mask_file}{cn\_mask\_file} in the nam\_bdy namelist. 
    633594Only one mask file is used even if multiple boundary sets are defined. 
    634595 
    635 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    636596\begin{figure}[!t] 
    637   \begin{center} 
    638     \includegraphics[width=1.0\textwidth]{Fig_LBC_bdy_geom} 
    639     \caption { 
    640       \protect\label{fig:LBC_bdy_geom} 
    641       Example of geometry of unstructured open boundary 
    642     } 
    643   \end{center} 
     597  \centering 
     598  \includegraphics[width=0.66\textwidth]{LBC_bdy_geom} 
     599  \caption[Geometry of unstructured open boundary]{Example of geometry of unstructured open boundary} 
     600  \label{fig:LBC_bdy_geom} 
    644601\end{figure} 
    645 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    646  
    647 %---------------------------------------------- 
     602 
     603%% ================================================================================================= 
    648604\subsection{Input boundary data files} 
    649 \label{subsec:BDY_data} 
     605\label{subsec:LBC_bdy_data} 
    650606 
    651607The data files contain the data arrays in the order in which the points are defined in the $nbi$ and $nbj$ arrays. 
     
    653609a time dimension; 
    654610$xb$ which is the index of the boundary data point in the horizontal; 
    655 and $yb$ which is a degenerate dimension of 1 to enable the file to be read by the standard NEMO I/O routines. 
    656 The 3D fields also have a depth dimension.  
     611and $yb$ which is a degenerate dimension of 1 to enable the file to be read by the standard \NEMO\ I/O routines. 
     612The 3D fields also have a depth dimension. 
    657613 
    658614From Version 3.4 there are new restrictions on the order in which the boundary points are defined 
     
    665621\item All the data for a particular boundary set must be in the same order. 
    666622  (Prior to 3.4 it was possible to define barotropic data in a different order to 
    667   the data for tracers and baroclinic velocities).  
     623  the data for tracers and baroclinic velocities). 
    668624\end{enumerate} 
    669625 
    670626These restrictions mean that data files used with versions of the 
    671627model prior to Version 3.4 may not work with Version 3.4 onwards. 
    672 A \fortran utility {\it bdy\_reorder} exists in the TOOLS directory which 
     628A \fortran\ utility {\itshape bdy\_reorder} exists in the TOOLS directory which 
    673629will re-order the data in old BDY data files. 
    674630 
    675 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    676631\begin{figure}[!t] 
    677   \begin{center} 
    678     \includegraphics[width=1.0\textwidth]{Fig_LBC_nc_header} 
    679     \caption { 
    680       \protect\label{fig:LBC_nc_header} 
    681       Example of the header for a \protect\ifile{coordinates.bdy} file 
    682     } 
    683   \end{center} 
     632  \centering 
     633  \includegraphics[width=0.66\textwidth]{LBC_nc_header} 
     634  \caption[Header for a \protect\ifile{coordinates.bdy} file]{ 
     635    Example of the header for a \protect\ifile{coordinates.bdy} file} 
     636  \label{fig:LBC_nc_header} 
    684637\end{figure} 
    685 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    686  
    687 %---------------------------------------------- 
     638 
     639%% ================================================================================================= 
    688640\subsection{Volume correction} 
    689 \label{subsec:BDY_vol_corr} 
     641\label{subsec:LBC_bdy_vol_corr} 
    690642 
    691643There is an option to force the total volume in the regional model to be constant. 
    692 This is controlled  by the \np{ln\_vol} parameter in the namelist. 
    693 A value of \np{ln\_vol}\forcode{ = .false.} indicates that this option is not used. 
    694 Two options to control the volume are available (\np{nn\_volctl}).  
    695 If \np{nn\_volctl}\forcode{ = 0} then a correction is applied to the normal barotropic velocities around the boundary at 
     644This is controlled  by the \np{ln_vol}{ln\_vol} parameter in the namelist. 
     645A value of \np[=.false.]{ln_vol}{ln\_vol} indicates that this option is not used. 
     646Two options to control the volume are available (\np{nn_volctl}{nn\_volctl}). 
     647If \np[=0]{nn_volctl}{nn\_volctl} then a correction is applied to the normal barotropic velocities around the boundary at 
    696648each timestep to ensure that the integrated volume flow through the boundary is zero. 
    697 If \np{nn\_volctl}\forcode{ = 1} then the calculation of the volume change on 
     649If \np[=1]{nn_volctl}{nn\_volctl} then the calculation of the volume change on 
    698650the timestep includes the change due to the freshwater flux across the surface and 
    699651the correction velocity corrects for this as well. 
     
    702654applied to all boundaries at once. 
    703655 
    704 %---------------------------------------------- 
     656%% ================================================================================================= 
    705657\subsection{Tidal harmonic forcing} 
    706 \label{subsec:BDY_tides} 
    707  
    708 %-----------------------------------------nambdy_tide-------------------------------------------- 
    709  
    710 \nlst{nambdy_tide}  
    711 %----------------------------------------------------------------------------------------------- 
     658\label{subsec:LBC_bdy_tides} 
     659 
     660\begin{listing} 
     661  \nlst{nambdy_tide} 
     662  \caption{\forcode{&nambdy_tide}} 
     663  \label{lst:nambdy_tide} 
     664\end{listing} 
    712665 
    713666Tidal forcing at open boundaries requires the activation of surface 
    714 tides (i.e., in \ngn{nam\_tide}, \np{ln\_tide} needs to be set to 
     667tides (i.e., in \nam{_tide}{\_tide}, \np{ln_tide}{ln\_tide} needs to be set to 
    715668\forcode{.true.} and the required constituents need to be activated by 
    716 including their names in the \np{cname} array; see 
     669including their names in the \np{clname}{clname} array; see 
    717670\autoref{sec:SBC_tide}). Specific options related to the reading in of 
    718671the complex harmonic amplitudes of elevation (SSH) and barotropic 
    719672velocity (u,v) at open boundaries are defined through the 
    720 \ngn{nambdy\_tide} namelist parameters.\\ 
     673\nam{bdy_tide}{bdy\_tide} namelist parameters.\\ 
    721674 
    722675The tidal harmonic data at open boundaries can be specified in two 
    723676different ways, either on a two-dimensional grid covering the entire 
    724677model domain or along open boundary segments; these two variants can 
    725 be selected by setting \np{ln\_bdytide\_2ddta } to \forcode{.true.} or 
     678be selected by setting \np{ln_bdytide_2ddta }{ln\_bdytide\_2ddta } to \forcode{.true.} or 
    726679\forcode{.false.}, respectively. In either case, the real and 
    727680imaginary parts of SSH and the two barotropic velocity components for 
     
    729682separately: when two-dimensional data is used, variables 
    730683\textit{tcname\_z1} and \textit{tcname\_z2} for real and imaginary SSH, 
    731 respectively, are expected in input file \np{filtide} with suffix 
     684respectively, are expected in input file \np{filtide}{filtide} with suffix 
    732685\ifile{\_grid\_T}, variables \textit{tcname\_u1} and 
    733686\textit{tcname\_u2} for real and imaginary u, respectively, are 
    734 expected in input file \np{filtide} with suffix \ifile{\_grid\_U}, and 
     687expected in input file \np{filtide}{filtide} with suffix \ifile{\_grid\_U}, and 
    735688\textit{tcname\_v1} and \textit{tcname\_v2} for real and imaginary v, 
    736 respectively, are expected in input file \np{filtide} with suffix 
     689respectively, are expected in input file \np{filtide}{filtide} with suffix 
    737690\ifile{\_grid\_V}; when data along open boundary segments is used, 
    738691variables \textit{z1} and \textit{z2} (real and imaginary part of SSH) 
    739 are expected to be available from file \np{filtide} with suffix 
     692are expected to be available from file \np{filtide}{filtide} with suffix 
    740693\ifile{tcname\_grid\_T}, variables \textit{u1} and \textit{u2} (real 
    741694and imaginary part of u) are expected to be available from file 
    742 \np{filtide} with suffix \ifile{tcname\_grid\_U}, and variables 
     695\np{filtide}{filtide} with suffix \ifile{tcname\_grid\_U}, and variables 
    743696\textit{v1} and \textit{v2} (real and imaginary part of v) are 
    744 expected to be available from file \np{filtide} with suffix 
    745 \ifile{tcname\_grid\_V}. If \np{ln\_bdytide\_conj} is set to 
     697expected to be available from file \np{filtide}{filtide} with suffix 
     698\ifile{tcname\_grid\_V}. If \np{ln_bdytide_conj}{ln\_bdytide\_conj} is set to 
    746699\forcode{.true.}, the data is expected to be in complex conjugate 
    747700form. 
     
    755708direction of rotation). %, e.g. anticlockwise or clockwise. 
    756709 
    757 \biblio 
    758  
    759 \pindex 
     710\subinc{\input{../../global/epilogue}} 
    760711 
    761712\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_LDF.tex

    r10442 r11831  
    33\begin{document} 
    44 
    5 % ================================================================ 
    6 % Chapter Lateral Ocean Physics (LDF) 
    7 % ================================================================ 
    85\chapter{Lateral Ocean Physics (LDF)} 
    96\label{chap:LDF} 
    107 
    11 \minitoc 
    12  
    13 \newpage 
    14  
    15 The lateral physics terms in the momentum and tracer equations have been described in \autoref{eq:PE_zdf} and 
     8\thispagestyle{plain} 
     9 
     10\chaptertoc 
     11 
     12\paragraph{Changes record} ~\\ 
     13 
     14{\footnotesize 
     15  \begin{tabularx}{\textwidth}{l||X|X} 
     16    Release & Author(s) & Modifications \\ 
     17    \hline 
     18    {\em   4.0} & {\em ...} & {\em ...} \\ 
     19    {\em   3.6} & {\em ...} & {\em ...} \\ 
     20    {\em   3.4} & {\em ...} & {\em ...} \\ 
     21    {\em <=3.4} & {\em ...} & {\em ...} 
     22  \end{tabularx} 
     23} 
     24 
     25\clearpage 
     26 
     27The lateral physics terms in the momentum and tracer equations have been described in \autoref{eq:MB_zdf} and 
    1628their discrete formulation in \autoref{sec:TRA_ldf} and \autoref{sec:DYN_ldf}). 
    1729In this section we further discuss each lateral physics option. 
     
    2234(3) the space and time variations of the eddy coefficients. 
    2335These three aspects of the lateral diffusion are set through namelist parameters 
    24 (see the \ngn{nam\_traldf} and \ngn{nam\_dynldf} below). 
    25 Note that this chapter describes the standard implementation of iso-neutral tracer mixing, 
    26 and Griffies's implementation, which is used if \np{traldf\_grif}\forcode{ = .true.}, 
    27 is described in Appdx\autoref{apdx:triad} 
    28  
    29 %-----------------------------------nam_traldf - nam_dynldf-------------------------------------------- 
    30  
    31 \nlst{namtra_ldf}  
    32  
    33 \nlst{namdyn_ldf}  
    34 %-------------------------------------------------------------------------------------------------------------- 
    35  
    36  
    37 % ================================================================ 
    38 % Direction of lateral Mixing 
    39 % ================================================================ 
    40 \section{Direction of lateral mixing (\protect\mdl{ldfslp})} 
     36(see the \nam{tra_ldf}{tra\_ldf} and \nam{dyn_ldf}{dyn\_ldf} below). 
     37Note that this chapter describes the standard implementation of iso-neutral tracer mixing. 
     38Griffies's implementation, which is used if \np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}, 
     39is described in \autoref{apdx:TRIADS} 
     40 
     41%% ================================================================================================= 
     42\section[Lateral mixing operators]{Lateral mixing operators} 
     43\label{sec:LDF_op} 
     44We 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}. 
     45 
     46%% ================================================================================================= 
     47\subsection[No lateral mixing (\forcode{ln_traldf_OFF} \& \forcode{ln_dynldf_OFF})]{No lateral mixing (\protect\np{ln_traldf_OFF}{ln\_traldf\_OFF} \& \protect\np{ln_dynldf_OFF}{ln\_dynldf\_OFF})} 
     48 
     49It is possible to run without explicit lateral diffusion on tracers (\protect\np[=.true.]{ln_traldf_OFF}{ln\_traldf\_OFF}) and/or 
     50momentum (\protect\np[=.true.]{ln_dynldf_OFF}{ln\_dynldf\_OFF}). The latter option is even recommended if using the 
     51UBS advection scheme on momentum (\np[=.true.]{ln_dynadv_ubs}{ln\_dynadv\_ubs}, 
     52see \autoref{subsec:DYN_adv_ubs}) and can be useful for testing purposes. 
     53 
     54%% ================================================================================================= 
     55\subsection[Laplacian mixing (\forcode{ln_traldf_lap} \& \forcode{ln_dynldf_lap})]{Laplacian mixing (\protect\np{ln_traldf_lap}{ln\_traldf\_lap} \& \protect\np{ln_dynldf_lap}{ln\_dynldf\_lap})} 
     56Setting \protect\np[=.true.]{ln_traldf_lap}{ln\_traldf\_lap} and/or \protect\np[=.true.]{ln_dynldf_lap}{ln\_dynldf\_lap} enables 
     57a second order diffusion on tracers and momentum respectively. Note that in \NEMO\ 4, one can not combine 
     58Laplacian and Bilaplacian operators for the same variable. 
     59 
     60%% ================================================================================================= 
     61\subsection[Bilaplacian mixing (\forcode{ln_traldf_blp} \& \forcode{ln_dynldf_blp})]{Bilaplacian mixing (\protect\np{ln_traldf_blp}{ln\_traldf\_blp} \& \protect\np{ln_dynldf_blp}{ln\_dynldf\_blp})} 
     62Setting \protect\np[=.true.]{ln_traldf_blp}{ln\_traldf\_blp} and/or \protect\np[=.true.]{ln_dynldf_blp}{ln\_dynldf\_blp} enables 
     63a fourth order diffusion on tracers and momentum respectively. It is implemented by calling the above Laplacian operator twice. 
     64We stress again that from \NEMO\ 4, the simultaneous use Laplacian and Bilaplacian operators is not allowed. 
     65 
     66%% ================================================================================================= 
     67\section[Direction of lateral mixing (\textit{ldfslp.F90})]{Direction of lateral mixing (\protect\mdl{ldfslp})} 
    4168\label{sec:LDF_slp} 
    4269 
    43 %%% 
    44 \gmcomment{ 
     70\cmtgm{ 
    4571  we should emphasize here that the implementation is a rather old one. 
    46   Better work can be achieved by using \citet{Griffies_al_JPO98, Griffies_Bk04} iso-neutral scheme. 
     72  Better work can be achieved by using \citet{griffies.gnanadesikan.ea_JPO98, griffies_bk04} iso-neutral scheme. 
    4773} 
    4874 
    4975A direction for lateral mixing has to be defined when the desired operator does not act along the model levels. 
    5076This occurs when $(a)$ horizontal mixing is required on tracer or momentum 
    51 (\np{ln\_traldf\_hor} or \np{ln\_dynldf\_hor}) in $s$- or mixed $s$-$z$- coordinates, 
     77(\np{ln_traldf_hor}{ln\_traldf\_hor} or \np{ln_dynldf_hor}{ln\_dynldf\_hor}) in $s$- or mixed $s$-$z$- coordinates, 
    5278and $(b)$ isoneutral mixing is required whatever the vertical coordinate is. 
    5379This direction of mixing is defined by its slopes in the \textbf{i}- and \textbf{j}-directions at the face of 
    5480the cell of the quantity to be diffused. 
    5581For a tracer, this leads to the following four slopes: 
    56 $r_{1u}$, $r_{1w}$, $r_{2v}$, $r_{2w}$ (see \autoref{eq:tra_ldf_iso}), 
     82$r_{1u}$, $r_{1w}$, $r_{2v}$, $r_{2w}$ (see \autoref{eq:TRA_ldf_iso}), 
    5783while for momentum the slopes are  $r_{1t}$, $r_{1uw}$, $r_{2f}$, $r_{2uw}$ for $u$ and 
    58 $r_{1f}$, $r_{1vw}$, $r_{2t}$, $r_{2vw}$ for $v$.  
    59  
    60 %gm% add here afigure of the slope in i-direction 
    61  
     84$r_{1f}$, $r_{1vw}$, $r_{2t}$, $r_{2vw}$ for $v$. 
     85 
     86\cmtgm{Add here afigure of the slope in i-direction} 
     87 
     88%% ================================================================================================= 
    6289\subsection{Slopes for tracer geopotential mixing in the $s$-coordinate} 
    6390 
    64 In $s$-coordinates, geopotential mixing (\ie horizontal mixing) $r_1$ and $r_2$ are the slopes between 
     91In $s$-coordinates, geopotential mixing (\ie\ horizontal mixing) $r_1$ and $r_2$ are the slopes between 
    6592the geopotential and computational surfaces. 
    66 Their discrete formulation is found by locally solving \autoref{eq:tra_ldf_iso} when 
     93Their discrete formulation is found by locally solving \autoref{eq:TRA_ldf_iso} when 
    6794the diffusive fluxes in the three directions are set to zero and $T$ is assumed to be horizontally uniform, 
    68 \ie a linear function of $z_T$, the depth of a $T$-point.  
    69 %gm { Steven : My version is obviously wrong since I'm left with an arbitrary constant which is the local vertical temperature gradient} 
    70  
    71 \begin{equation} 
    72   \label{eq:ldfslp_geo} 
     95\ie\ a linear function of $z_T$, the depth of a $T$-point. 
     96\cmtgm{Steven : My version is obviously wrong since 
     97  I'm left with an arbitrary constant which is the local vertical temperature gradient} 
     98 
     99\begin{equation} 
     100  \label{eq:LDF_slp_geo} 
    73101  \begin{aligned} 
    74102    r_{1u} &= \frac{e_{3u}}{ \left( e_{1u}\;\overline{\overline{e_{3w}}}^{\,i+1/2,\,k} \right)} 
     
    85113\end{equation} 
    86114 
    87 %gm%  caution I'm not sure the simplification was a good idea!  
    88  
    89 These slopes are computed once in \rou{ldfslp\_init} when \np{ln\_sco}\forcode{ = .true.}rue, 
    90 and either \np{ln\_traldf\_hor}\forcode{ = .true.} or \np{ln\_dynldf\_hor}\forcode{ = .true.}.  
    91  
     115\cmtgm{Caution I'm not sure the simplification was a good idea!} 
     116 
     117These slopes are computed once in \rou{ldf\_slp\_init} when \np[=.true.]{ln_sco}{ln\_sco}, 
     118and either \np[=.true.]{ln_traldf_hor}{ln\_traldf\_hor} or \np[=.true.]{ln_dynldf_hor}{ln\_dynldf\_hor}. 
     119 
     120%% ================================================================================================= 
    92121\subsection{Slopes for tracer iso-neutral mixing} 
    93122\label{subsec:LDF_slp_iso} 
     
    96125Their formulation does not depend on the vertical coordinate used. 
    97126Their discrete formulation is found using the fact that the diffusive fluxes of 
    98 locally referenced potential density (\ie $in situ$ density) vanish. 
    99 So, substituting $T$ by $\rho$ in \autoref{eq:tra_ldf_iso} and setting the diffusive fluxes in 
     127locally referenced potential density (\ie\ $in situ$ density) vanish. 
     128So, substituting $T$ by $\rho$ in \autoref{eq:TRA_ldf_iso} and setting the diffusive fluxes in 
    100129the three directions to zero leads to the following definition for the neutral slopes: 
    101130 
    102131\begin{equation} 
    103   \label{eq:ldfslp_iso} 
     132  \label{eq:LDF_slp_iso} 
    104133  \begin{split} 
    105134    r_{1u} &= \frac{e_{3u}}{e_{1u}}\; \frac{\delta_{i+1/2}[\rho]} 
     
    116145\end{equation} 
    117146 
    118 %gm% rewrite this as the explanation is not very clear !!! 
    119 %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.  
    120  
    121 %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). 
    122  
    123 %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.  
    124  
    125 As the mixing is performed along neutral surfaces, the gradient of $\rho$ in \autoref{eq:ldfslp_iso} has to 
     147\cmtgm{rewrite this as the explanation is not very clear !!!} 
     148%In practice, \autoref{eq:LDF_slp_iso} is of little help in evaluating the neutral surface slopes. Indeed, for an unsimplified equation of state, the density has a strong dependancy on pressure (here approximated as the depth), therefore applying \autoref{eq:LDF_slp_iso} using the $in situ$ density, $\rho$, computed at T-points leads to a flattening of slopes as the depth increases. This is due to the strong increase of the $in situ$ density with depth. 
     149 
     150%By definition, neutral surfaces are tangent to the local $in situ$ density \citep{mcdougall_JPO87}, therefore in \autoref{eq:LDF_slp_iso}, all the derivatives have to be evaluated at the same local pressure (which in decibars is approximated by the depth in meters). 
     151 
     152%In the $z$-coordinate, the derivative of the  \autoref{eq:LDF_slp_iso} numerator is evaluated at the same depth \nocite{as what?} ($T$-level, which is the same as the $u$- and $v$-levels), so  the $in situ$ density can be used for its evaluation. 
     153 
     154As the mixing is performed along neutral surfaces, the gradient of $\rho$ in \autoref{eq:LDF_slp_iso} has to 
    126155be evaluated at the same local pressure 
    127156(which, in decibars, is approximated by the depth in meters in the model). 
    128 Therefore \autoref{eq:ldfslp_iso} cannot be used as such, 
     157Therefore \autoref{eq:LDF_slp_iso} cannot be used as such, 
    129158but further transformation is needed depending on the vertical coordinate used: 
    130159 
    131160\begin{description} 
    132  
    133 \item[$z$-coordinate with full step: ] 
    134   in \autoref{eq:ldfslp_iso} the densities appearing in the $i$ and $j$ derivatives  are taken at the same depth, 
     161\item [$z$-coordinate with full step:] in \autoref{eq:LDF_slp_iso} the densities appearing in the $i$ and $j$ derivatives  are taken at the same depth, 
    135162  thus the $in situ$ density can be used. 
    136163  This is not the case for the vertical derivatives: $\delta_{k+1/2}[\rho]$ is replaced by $-\rho N^2/g$, 
    137   where $N^2$ is the local Brunt-Vais\"{a}l\"{a} frequency evaluated following \citet{McDougall1987} 
    138   (see \autoref{subsec:TRA_bn2}).  
    139  
    140 \item[$z$-coordinate with partial step: ] 
    141   this case is identical to the full step case except that at partial step level, 
     164  where $N^2$ is the local Brunt-Vais\"{a}l\"{a} frequency evaluated following \citet{mcdougall_JPO87} 
     165  (see \autoref{subsec:TRA_bn2}). 
     166\item [$z$-coordinate with partial step:] this case is identical to the full step case except that at partial step level, 
    142167  the \emph{horizontal} density gradient is evaluated as described in \autoref{sec:TRA_zpshde}. 
    143  
    144 \item[$s$- or hybrid $s$-$z$- coordinate: ] 
    145   in the current release of \NEMO, iso-neutral mixing is only employed for $s$-coordinates if 
    146   the Griffies scheme is used (\np{traldf\_grif}\forcode{ = .true.}; 
    147   see Appdx \autoref{apdx:triad}). 
     168\item [$s$- or hybrid $s$-$z$- coordinate:] in the current release of \NEMO, iso-neutral mixing is only employed for $s$-coordinates if 
     169  the Griffies scheme is used (\np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}; 
     170  see \autoref{apdx:TRIADS}). 
    148171  In other words, iso-neutral mixing will only be accurately represented with a linear equation of state 
    149   (\np{nn\_eos}\forcode{ = 1..2}). 
    150   In the case of a "true" equation of state, the evaluation of $i$ and $j$ derivatives in \autoref{eq:ldfslp_iso} 
     172  (\np[=.true.]{ln_seos}{ln\_seos}). 
     173  In the case of a "true" equation of state, the evaluation of $i$ and $j$ derivatives in \autoref{eq:LDF_slp_iso} 
    151174  will include a pressure dependent part, leading to the wrong evaluation of the neutral slopes. 
    152175 
    153 %gm%  
    154176  Note: The solution for $s$-coordinate passes trough the use of different (and better) expression for 
    155177  the constraint on iso-neutral fluxes. 
    156   Following \citet{Griffies_Bk04}, instead of specifying directly that there is a zero neutral diffusive flux of 
     178  Following \citet{griffies_bk04}, instead of specifying directly that there is a zero neutral diffusive flux of 
    157179  locally referenced potential density, we stay in the $T$-$S$ plane and consider the balance between 
    158180  the neutral direction diffusive fluxes of potential temperature and salinity: 
     
    160182    \alpha \ \textbf{F}(T) = \beta \ \textbf{F}(S) 
    161183  \] 
    162   % gm{  where vector F is ....} 
     184  \cmtgm{where vector F is ....} 
    163185 
    164186This constraint leads to the following definition for the slopes: 
    165187 
    166188\[ 
    167   % \label{eq:ldfslp_iso2} 
     189  % \label{eq:LDF_slp_iso2} 
    168190  \begin{split} 
    169191    r_{1u} &= \frac{e_{3u}}{e_{1u}}\; \frac 
     
    193215 
    194216Note that such a formulation could be also used in the $z$-coordinate and $z$-coordinate with partial steps cases. 
    195  
    196217\end{description} 
    197218 
    198219This implementation is a rather old one. 
    199 It is similar to the one proposed by Cox [1987], except for the background horizontal diffusion. 
    200 Indeed, the Cox implementation of isopycnal diffusion in GFDL-type models requires 
     220It is similar to the one proposed by \citet{cox_OM87}, except for the background horizontal diffusion. 
     221Indeed, the \citet{cox_OM87} implementation of isopycnal diffusion in GFDL-type models requires 
    201222a minimum background horizontal diffusion for numerical stability reasons. 
    202223To overcome this problem, several techniques have been proposed in which the numerical schemes of 
    203 the ocean model are modified \citep{Weaver_Eby_JPO97, Griffies_al_JPO98}. 
    204 Griffies's scheme is now available in \NEMO if \np{traldf\_grif\_iso} is set true; see Appdx \autoref{apdx:triad}. 
    205 Here, another strategy is presented \citep{Lazar_PhD97}: 
     224the ocean model are modified \citep{weaver.eby_JPO97, griffies.gnanadesikan.ea_JPO98}. 
     225Griffies's scheme is now available in \NEMO\ if \np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}; see \autoref{apdx:TRIADS}. 
     226Here, another strategy is presented \citep{lazar_phd97}: 
    206227a local filtering of the iso-neutral slopes (made on 9 grid-points) prevents the development of 
    207228grid point noise generated by the iso-neutral diffusion operator (\autoref{fig:LDF_ZDF1}). 
    208229This allows an iso-neutral diffusion scheme without additional background horizontal mixing. 
    209230This technique can be viewed as a diffusion operator that acts along large-scale 
    210 (2~$\Delta$x) \gmcomment{2deltax doesnt seem very large scale} iso-neutral surfaces. 
     231(2~$\Delta$x) \cmtgm{2deltax doesnt seem very large scale} iso-neutral surfaces. 
    211232The diapycnal diffusion required for numerical stability is thus minimized and its net effect on the flow is quite small when compared to the effect of an horizontal background mixing. 
    212233 
    213234Nevertheless, this iso-neutral operator does not ensure that variance cannot increase, 
    214 contrary to the \citet{Griffies_al_JPO98} operator which has that property.  
    215  
    216 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     235contrary to the \citet{griffies.gnanadesikan.ea_JPO98} operator which has that property. 
     236 
    217237\begin{figure}[!ht] 
    218   \begin{center} 
    219     \includegraphics[width=0.70\textwidth]{Fig_LDF_ZDF1} 
    220     \caption { 
    221       \protect\label{fig:LDF_ZDF1} 
    222       averaging procedure for isopycnal slope computation. 
    223     } 
    224   \end{center} 
     238  \centering 
     239  \includegraphics[width=0.66\textwidth]{LDF_ZDF1} 
     240  \caption{Averaging procedure for isopycnal slope computation} 
     241  \label{fig:LDF_ZDF1} 
    225242\end{figure} 
    226 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    227  
    228 %There are three additional questions about the slope calculation.  
    229 %First the expression for the rotation tensor has been obtain assuming the "small slope" approximation, so a bound has to be imposed on slopes.  
    230 %Second, numerical stability issues also require a bound on slopes.  
     243 
     244%There are three additional questions about the slope calculation. 
     245%First the expression for the rotation tensor has been obtain assuming the "small slope" approximation, so a bound has to be imposed on slopes. 
     246%Second, numerical stability issues also require a bound on slopes. 
    231247%Third, the question of boundary condition specified on slopes... 
    232248 
    233249%from griffies: chapter 13.1.... 
    234250 
    235  
    236  
    237 % In addition and also for numerical stability reasons \citep{Cox1987, Griffies_Bk04},  
    238 % the slopes are bounded by $1/100$ everywhere. This limit is decreasing linearly  
    239 % to zero fom $70$ meters depth and the surface (the fact that the eddies "feel" the  
     251% In addition and also for numerical stability reasons \citep{cox_OM87, griffies_bk04}, 
     252% the slopes are bounded by $1/100$ everywhere. This limit is decreasing linearly 
     253% to zero fom $70$ meters depth and the surface (the fact that the eddies "feel" the 
    240254% surface motivates this flattening of isopycnals near the surface). 
    241255 
    242 For numerical stability reasons \citep{Cox1987, Griffies_Bk04}, the slopes must also be bounded by 
    243 $1/100$ everywhere. 
     256For numerical stability reasons \citep{cox_OM87, griffies_bk04}, the slopes must also be bounded by 
     257the namelist scalar \np{rn_slpmax}{rn\_slpmax} (usually $1/100$) everywhere. 
    244258This constraint is applied in a piecewise linear fashion, increasing from zero at the surface to 
    245259$1/100$ at $70$ metres and thereafter decreasing to zero at the bottom of the ocean 
    246260(the fact that the eddies "feel" the surface motivates this flattening of isopycnals near the surface). 
    247  
    248 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     261\colorbox{yellow}{The way slopes are tapered has be checked. Not sure that this is still what is actually done.} 
     262 
    249263\begin{figure}[!ht] 
    250   \begin{center} 
    251     \includegraphics[width=0.70\textwidth]{Fig_eiv_slp} 
    252     \caption{ 
    253       \protect\label{fig:eiv_slp} 
    254       Vertical profile of the slope used for lateral mixing in the mixed layer: 
    255       \textit{(a)} in the real ocean the slope is the iso-neutral slope in the ocean interior, 
    256       which has to be adjusted at the surface boundary 
    257       \ie it must tend to zero at the surface since there is no mixing across the air-sea interface: 
    258       wall boundary condition). 
    259       Nevertheless, the profile between the surface zero value and the interior iso-neutral one is unknown, 
    260       and especially the value at the base of the mixed layer; 
    261       \textit{(b)} profile of slope using a linear tapering of the slope near the surface and 
    262       imposing a maximum slope of 1/100; 
    263       \textit{(c)} profile of slope actually used in \NEMO: a linear decrease of the slope from 
    264       zero at the surface to its ocean interior value computed just below the mixed layer. 
    265       Note the huge change in the slope at the base of the mixed layer between \textit{(b)} and \textit{(c)}. 
    266     } 
    267   \end{center} 
     264  \centering 
     265  \includegraphics[width=0.66\textwidth]{LDF_eiv_slp} 
     266  \caption[Vertical profile of the slope used for lateral mixing in the mixed layer]{ 
     267    Vertical profile of the slope used for lateral mixing in the mixed layer: 
     268    \textit{(a)} in the real ocean the slope is the iso-neutral slope in the ocean interior, 
     269    which has to be adjusted at the surface boundary 
     270    \ie\ it must tend to zero at the surface since there is no mixing across the air-sea interface: 
     271    wall boundary condition). 
     272    Nevertheless, 
     273    the profile between the surface zero value and the interior iso-neutral one is unknown, 
     274    and especially the value at the base of the mixed layer; 
     275    \textit{(b)} profile of slope using a linear tapering of the slope near the surface and 
     276    imposing a maximum slope of 1/100; 
     277    \textit{(c)} profile of slope actually used in \NEMO: 
     278    a linear decrease of the slope from zero at the surface to 
     279    its ocean interior value computed just below the mixed layer. 
     280    Note the huge change in the slope at the base of the mixed layer between 
     281    \textit{(b)} and \textit{(c)}.} 
     282  \label{fig:LDF_eiv_slp} 
    268283\end{figure} 
    269 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    270284 
    271285\colorbox{yellow}{add here a discussion about the flattening of the slopes, vs tapering the coefficient.} 
    272286 
     287%% ================================================================================================= 
    273288\subsection{Slopes for momentum iso-neutral mixing} 
    274289 
    275290The iso-neutral diffusion operator on momentum is the same as the one used on tracers but 
    276291applied to each component of the velocity separately 
    277 (see \autoref{eq:dyn_ldf_iso} in section~\autoref{subsec:DYN_ldf_iso}). 
     292(see \autoref{eq:DYN_ldf_iso} in section~\autoref{subsec:DYN_ldf_iso}). 
    278293The slopes between the surface along which the diffusion operator acts and the surface of computation 
    279294($z$- or $s$-surfaces) are defined at $T$-, $f$-, and \textit{uw}- points for the $u$-component, and $T$-, $f$- and 
    280295\textit{vw}- points for the $v$-component. 
    281296They are computed from the slopes used for tracer diffusion, 
    282 \ie \autoref{eq:ldfslp_geo} and \autoref{eq:ldfslp_iso}: 
     297\ie\ \autoref{eq:LDF_slp_geo} and \autoref{eq:LDF_slp_iso}: 
    283298 
    284299\[ 
    285   % \label{eq:ldfslp_dyn} 
     300  % \label{eq:LDF_slp_dyn} 
    286301  \begin{aligned} 
    287302    &r_{1t}\ \ = \overline{r_{1u}}^{\,i}       &&&    r_{1f}\ \ &= \overline{r_{1u}}^{\,i+1/2} \\ 
     
    294309The major issue remaining is in the specification of the boundary conditions. 
    295310The same boundary conditions are chosen as those used for lateral diffusion along model level surfaces, 
    296 \ie using the shear computed along the model levels and with no additional friction at the ocean bottom 
     311\ie\ using the shear computed along the model levels and with no additional friction at the ocean bottom 
    297312(see \autoref{sec:LBC_coast}). 
    298313 
    299  
    300 % ================================================================ 
    301 % Lateral Mixing Operator 
    302 % ================================================================ 
    303 \section{Lateral mixing operators (\protect\mdl{traldf}, \protect\mdl{traldf}) } 
    304 \label{sec:LDF_op} 
    305  
    306  
    307     
    308 % ================================================================ 
    309 % Lateral Mixing Coefficients 
    310 % ================================================================ 
    311 \section{Lateral mixing coefficient (\protect\mdl{ldftra}, \protect\mdl{ldfdyn}) } 
     314%% ================================================================================================= 
     315\section[Lateral mixing coefficient (\forcode{nn_aht_ijk_t} \& \forcode{nn_ahm_ijk_t})]{Lateral mixing coefficient (\protect\np{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 
    312316\label{sec:LDF_coef} 
    313317 
    314 Introducing a space variation in the lateral eddy mixing coefficients changes the model core memory requirement, 
    315 adding up to four extra three-dimensional arrays for the geopotential or isopycnal second order operator applied to  
    316 momentum. 
    317 Six CPP keys control the space variation of eddy coefficients: three for momentum and three for tracer. 
    318 The three choices allow: 
    319 a space variation in the three space directions (\key{traldf\_c3d},  \key{dynldf\_c3d}), 
    320 in the horizontal plane (\key{traldf\_c2d},  \key{dynldf\_c2d}), 
    321 or in the vertical only (\key{traldf\_c1d},  \key{dynldf\_c1d}). 
    322 The default option is a constant value over the whole ocean on both momentum and tracers.  
    323     
    324 The number of additional arrays that have to be defined and the gridpoint position at which 
    325 they are defined depend on both the space variation chosen and the type of operator used. 
    326 The resulting eddy viscosity and diffusivity coefficients can be a function of more than one variable. 
    327 Changes in the computer code when switching from one option to another have been minimized by 
    328 introducing the eddy coefficients as statement functions 
    329 (include file \textit{ldftra\_substitute.h90} and \textit{ldfdyn\_substitute.h90}). 
    330 The functions are replaced by their actual meaning during the preprocessing step (CPP). 
    331 The specification of the space variation of the coefficient is made in \mdl{ldftra} and \mdl{ldfdyn}, 
    332 or more precisely in include files \textit{traldf\_cNd.h90} and \textit{dynldf\_cNd.h90}, with N=1, 2 or 3. 
    333 The user can modify these include files as he/she wishes. 
    334 The way the mixing coefficient are set in the reference version can be briefly described as follows: 
    335  
    336 \subsubsection{Constant mixing coefficients (default option)} 
    337 When none of the \key{dynldf\_...} and \key{traldf\_...} keys are defined, 
    338 a constant value is used over the whole ocean for momentum and tracers, 
    339 which is specified through the \np{rn\_ahm0} and \np{rn\_aht0} namelist parameters. 
    340  
    341 \subsubsection{Vertically varying mixing coefficients (\protect\key{traldf\_c1d} and \key{dynldf\_c1d})}  
    342 The 1D option is only available when using the $z$-coordinate with full step. 
    343 Indeed in all the other types of vertical coordinate, 
    344 the depth is a 3D function of (\textbf{i},\textbf{j},\textbf{k}) and therefore, 
    345 introducing depth-dependent mixing coefficients will require 3D arrays. 
    346 In the 1D option, a hyperbolic variation of the lateral mixing coefficient is introduced in which 
    347 the surface value is \np{rn\_aht0} (\np{rn\_ahm0}), the bottom value is 1/4 of the surface value, 
    348 and the transition takes place around z=300~m with a width of 300~m 
    349 (\ie both the depth and the width of the inflection point are set to 300~m). 
    350 This profile is hard coded in file \textit{traldf\_c1d.h90}, but can be easily modified by users. 
    351  
    352 \subsubsection{Horizontally varying mixing coefficients (\protect\key{traldf\_c2d} and \protect\key{dynldf\_c2d})} 
    353 By default the horizontal variation of the eddy coefficient depends on the local mesh size and 
     318The specification of the space variation of the coefficient is made in modules \mdl{ldftra} and \mdl{ldfdyn}. 
     319The way the mixing coefficients are set in the reference version can be described as follows: 
     320 
     321%% ================================================================================================= 
     322\subsection[Mixing coefficients read from file (\forcode{=-20, -30})]{ Mixing coefficients read from file (\protect\np[=-20, -30]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=-20, -30]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 
     323 
     324Mixing coefficients can be read from file if a particular geographical variation is needed. For example, in the ORCA2 global ocean model, 
     325the laplacian viscosity operator uses $A^l$~= 4.10$^4$ m$^2$/s poleward of 20$^{\circ}$ north and south and 
     326decreases linearly to $A^l$~= 2.10$^3$ m$^2$/s at the equator \citep{madec.delecluse.ea_JPO96, delecluse.madec_icol99}. 
     327Similar modified horizontal variations can be found with the Antarctic or Arctic sub-domain options of ORCA2 and ORCA05. 
     328The provided fields can either be 2d (\np[=-20]{nn_aht_ijk_t}{nn\_aht\_ijk\_t}, \np[=-20]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t}) or 3d (\np[=-30]{nn_aht_ijk_t}{nn\_aht\_ijk\_t},  \np[=-30]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t}). They must be given at U, V points for tracers and T, F points for momentum (see \autoref{tab:LDF_files}). 
     329 
     330\begin{table}[htb] 
     331  \centering 
     332  \begin{tabular}{|l|l|l|l|} 
     333    \hline 
     334    Namelist parameter                       & Input filename                               & dimensions & variable names                      \\  \hline 
     335    \np[=-20]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t}     & \forcode{eddy_viscosity_2D.nc }            &     $(i,j)$         & \forcode{ahmt_2d, ahmf_2d}  \\  \hline 
     336    \np[=-20]{nn_aht_ijk_t}{nn\_aht\_ijk\_t}           & \forcode{eddy_diffusivity_2D.nc }           &     $(i,j)$           & \forcode{ahtu_2d, ahtv_2d}    \\   \hline 
     337    \np[=-30]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t}        & \forcode{eddy_viscosity_3D.nc }            &     $(i,j,k)$          & \forcode{ahmt_3d, ahmf_3d}  \\  \hline 
     338    \np[=-30]{nn_aht_ijk_t}{nn\_aht\_ijk\_t}     & \forcode{eddy_diffusivity_3D.nc }           &     $(i,j,k)$         & \forcode{ahtu_3d, ahtv_3d}    \\   \hline 
     339  \end{tabular} 
     340  \caption{Description of expected input files if mixing coefficients are read from NetCDF files} 
     341  \label{tab:LDF_files} 
     342\end{table} 
     343 
     344%% ================================================================================================= 
     345\subsection[Constant mixing coefficients (\forcode{=0})]{ Constant mixing coefficients (\protect\np[=0]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=0]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 
     346 
     347If constant, mixing coefficients are set thanks to a velocity and a length scales ($U_{scl}$, $L_{scl}$) such that: 
     348 
     349\begin{equation} 
     350  \label{eq:LDF_constantah} 
     351  A_o^l = \left\{ 
     352    \begin{aligned} 
     353      & \frac{1}{2} U_{scl} L_{scl}            & \text{for laplacian operator } \\ 
     354      & \frac{1}{12} U_{scl} L_{scl}^3                    & \text{for bilaplacian operator } 
     355    \end{aligned} 
     356  \right. 
     357\end{equation} 
     358 
     359 $U_{scl}$ and $L_{scl}$ are given by the namelist parameters \np{rn_Ud}{rn\_Ud}, \np{rn_Uv}{rn\_Uv}, \np{rn_Ld}{rn\_Ld} and \np{rn_Lv}{rn\_Lv}. 
     360 
     361%% ================================================================================================= 
     362\subsection[Vertically varying mixing coefficients (\forcode{=10})]{Vertically varying mixing coefficients (\protect\np[=10]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=10]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 
     363 
     364In the vertically varying case, a hyperbolic variation of the lateral mixing coefficient is introduced in which 
     365the surface value is given by \autoref{eq:LDF_constantah}, the bottom value is 1/4 of the surface value, 
     366and the transition takes place around z=500~m with a width of 200~m. 
     367This profile is hard coded in module \mdl{ldfc1d\_c2d}, but can be easily modified by users. 
     368 
     369%% ================================================================================================= 
     370\subsection[Mesh size dependent mixing coefficients (\forcode{=20})]{Mesh size dependent mixing coefficients (\protect\np[=20]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=20]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 
     371 
     372In that case, the horizontal variation of the eddy coefficient depends on the local mesh size and 
    354373the type of operator used: 
    355374\begin{equation} 
    356   \label{eq:title} 
     375  \label{eq:LDF_title} 
    357376  A_l = \left\{ 
    358377    \begin{aligned} 
    359       & \frac{\max(e_1,e_2)}{e_{max}} A_o^l           & \text{for laplacian operator } \\ 
    360       & \frac{\max(e_1,e_2)^{3}}{e_{max}^{3}} A_o^l          & \text{for bilaplacian operator } 
     378      & \frac{1}{2} U_{scl}  \max(e_1,e_2)         & \text{for laplacian operator } \\ 
     379      & \frac{1}{12} U_{scl}  \max(e_1,e_2)^{3}             & \text{for bilaplacian operator } 
    361380    \end{aligned} 
    362381  \right. 
    363382\end{equation} 
    364 where $e_{max}$ is the maximum of $e_1$ and $e_2$ taken over the whole masked ocean domain, 
    365 and $A_o^l$ is the \np{rn\_ahm0} (momentum) or \np{rn\_aht0} (tracer) namelist parameter. 
     383where $U_{scl}$ is a user defined velocity scale (\np{rn_Ud}{rn\_Ud}, \np{rn_Uv}{rn\_Uv}). 
    366384This variation is intended to reflect the lesser need for subgrid scale eddy mixing where 
    367385the grid size is smaller in the domain. 
    368 It was introduced in the context of the DYNAMO modelling project \citep{Willebrand_al_PO01}. 
    369 Note that such a grid scale dependance of mixing coefficients significantly increase the range of stability of 
    370 model configurations presenting large changes in grid pacing such as global ocean models. 
     386It was introduced in the context of the DYNAMO modelling project \citep{willebrand.barnier.ea_PO01}. 
     387Note that such a grid scale dependance of mixing coefficients significantly increases the range of stability of 
     388model configurations presenting large changes in grid spacing such as global ocean models. 
    371389Indeed, in such a case, a constant mixing coefficient can lead to a blow up of the model due to 
    372 large coefficient compare to the smallest grid size (see \autoref{sec:STP_forward_imp}), 
     390large coefficient compare to the smallest grid size (see \autoref{sec:TD_forward_imp}), 
    373391especially when using a bilaplacian operator. 
    374392 
    375 Other formulations can be introduced by the user for a given configuration. 
    376 For example, in the ORCA2 global ocean model (see Configurations), 
    377 the laplacian viscosity operator uses \np{rn\_ahm0}~= 4.10$^4$ m$^2$/s poleward of 20$^{\circ}$ north and south and 
    378 decreases linearly to \np{rn\_aht0}~= 2.10$^3$ m$^2$/s at the equator \citep{Madec_al_JPO96, Delecluse_Madec_Bk00}. 
    379 This modification can be found in routine \rou{ldf\_dyn\_c2d\_orca} defined in \mdl{ldfdyn\_c2d}. 
    380 Similar modified horizontal variations can be found with the Antarctic or Arctic sub-domain options of 
    381 ORCA2 and ORCA05 (see \&namcfg namelist). 
    382  
    383 \subsubsection{Space varying mixing coefficients (\protect\key{traldf\_c3d} and \key{dynldf\_c3d})} 
    384  
    385 The 3D space variation of the mixing coefficient is simply the combination of the 1D and 2D cases, 
    386 \ie a hyperbolic tangent variation with depth associated with a grid size dependence of 
    387 the magnitude of the coefficient.  
    388  
    389 \subsubsection{Space and time varying mixing coefficients} 
    390  
    391 There is no default specification of space and time varying mixing coefficient.  
    392 The only case available is specific to the ORCA2 and ORCA05 global ocean configurations. 
    393 It provides only a tracer mixing coefficient for eddy induced velocity (ORCA2) or both iso-neutral and 
    394 eddy induced velocity (ORCA05) that depends on the local growth rate of baroclinic instability. 
    395 This specification is actually used when an ORCA key and both \key{traldf\_eiv} and \key{traldf\_c2d} are defined. 
     393\colorbox{yellow}{CASE \np{nn_aht_ijk_t}{nn\_aht\_ijk\_t} = 21 to be added} 
     394 
     395%% ================================================================================================= 
     396\subsection[Mesh size and depth dependent mixing coefficients (\forcode{=30})]{Mesh size and depth dependent mixing coefficients (\protect\np[=30]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=30]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 
     397 
     398The 3D space variation of the mixing coefficient is simply the combination of the 1D and 2D cases above, 
     399\ie\ a hyperbolic tangent variation with depth associated with a grid size dependence of 
     400the magnitude of the coefficient. 
     401 
     402%% ================================================================================================= 
     403\subsection[Velocity dependent mixing coefficients (\forcode{=31})]{Flow dependent mixing coefficients (\protect\np[=31]{nn_aht_ijk_t}{nn\_aht\_ijk\_t} \& \protect\np[=31]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 
     404In 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$): 
     405\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 ?} 
     406 
     407\begin{equation} 
     408  \label{eq:LDF_flowah} 
     409  A_l = \left\{ 
     410    \begin{aligned} 
     411      & \frac{1}{12} \lvert U \rvert e          & \text{for laplacian operator } \\ 
     412      & \frac{1}{12} \lvert U \rvert e^3             & \text{for bilaplacian operator } 
     413    \end{aligned} 
     414  \right. 
     415\end{equation} 
     416 
     417%% ================================================================================================= 
     418\subsection[Deformation rate dependent viscosities (\forcode{nn_ahm_ijk_t=32})]{Deformation rate dependent viscosities (\protect\np[=32]{nn_ahm_ijk_t}{nn\_ahm\_ijk\_t})} 
     419 
     420This option refers to the \citep{smagorinsky_MW63} scheme which is here implemented for momentum only. Smagorinsky chose as a 
     421characteristic time scale $T_{smag}$ the deformation rate and for the lengthscale $L_{smag}$ the maximum wavenumber possible on the horizontal grid, e.g.: 
     422 
     423\begin{equation} 
     424  \label{eq:LDF_smag1} 
     425  \begin{split} 
     426    T_{smag}^{-1} & = \sqrt{\left( \partial_x u - \partial_y v\right)^2 + \left( \partial_y u + \partial_x v\right)^2  } \\ 
     427    L_{smag} & = \frac{1}{\pi}\frac{e_1 e_2}{e_1 + e_2} 
     428  \end{split} 
     429\end{equation} 
     430 
     431Introducing a user defined constant $C$ (given in the namelist as \np{rn_csmc}{rn\_csmc}), one can deduce the mixing coefficients as follows: 
     432 
     433\begin{equation} 
     434  \label{eq:LDF_smag2} 
     435  A_{smag} = \left\{ 
     436    \begin{aligned} 
     437      & C^2  T_{smag}^{-1}  L_{smag}^2       & \text{for laplacian operator } \\ 
     438      & \frac{C^2}{8} T_{smag}^{-1} L_{smag}^4        & \text{for bilaplacian operator } 
     439    \end{aligned} 
     440  \right. 
     441\end{equation} 
     442 
     443For stability reasons, upper and lower limits are applied on the resulting coefficient (see \autoref{sec:TD_forward_imp}) so that: 
     444\begin{equation} 
     445  \label{eq:LDF_smag3} 
     446    \begin{aligned} 
     447      & C_{min} \frac{1}{2}   \lvert U \rvert  e    < A_{smag} < C_{max} \frac{e^2}{   8\rdt}                 & \text{for laplacian operator } \\ 
     448      & C_{min} \frac{1}{12} \lvert U \rvert  e^3 < A_{smag} < C_{max} \frac{e^4}{64 \rdt}                 & \text{for bilaplacian operator } 
     449    \end{aligned} 
     450\end{equation} 
     451 
     452where $C_{min}$ and $C_{max}$ are adimensional namelist parameters given by \np{rn_minfac}{rn\_minfac} and \np{rn_maxfac}{rn\_maxfac} respectively. 
     453 
     454%% ================================================================================================= 
     455\subsection{About space and time varying mixing coefficients} 
    396456 
    397457The following points are relevant when the eddy coefficient varies spatially: 
    398458 
    399459(1) the momentum diffusion operator acting along model level surfaces is written in terms of curl and 
    400 divergent components of the horizontal current (see \autoref{subsec:PE_ldf}). 
     460divergent components of the horizontal current (see \autoref{subsec:MB_ldf}). 
    401461Although the eddy coefficient could be set to different values in these two terms, 
    402 this option is not currently available.  
     462this option is not currently available. 
    403463 
    404464(2) with an horizontally varying viscosity, the quadratic integral constraints on enstrophy and on the square of 
    405465the horizontal divergence for operators acting along model-surfaces are no longer satisfied 
    406 (\autoref{sec:dynldf_properties}). 
    407  
    408 (3) for isopycnal diffusion on momentum or tracers, an additional purely horizontal background diffusion with 
    409 uniform coefficient can be added by setting a non zero value of \np{rn\_ahmb0} or \np{rn\_ahtb0}, 
    410 a background horizontal eddy viscosity or diffusivity coefficient 
    411 (namelist parameters whose default values are $0$). 
    412 However, the technique used to compute the isopycnal slopes is intended to get rid of such a background diffusion, 
    413 since it introduces spurious diapycnal diffusion (see \autoref{sec:LDF_slp}). 
    414  
    415 (4) when an eddy induced advection term is used (\key{traldf\_eiv}), 
    416 $A^{eiv}$, the eddy induced coefficient has to be defined. 
    417 Its space variations are controlled by the same CPP variable as for the eddy diffusivity coefficient 
    418 (\ie \key{traldf\_cNd}).  
    419  
    420 (5) the eddy coefficient associated with a biharmonic operator must be set to a \emph{negative} value. 
    421  
    422 (6) it is possible to use both the laplacian and biharmonic operators concurrently. 
    423  
    424 (7) it is possible to run without explicit lateral diffusion on momentum 
    425 (\np{ln\_dynldf\_lap}\forcode{ = .?.}\np{ln\_dynldf\_bilap}\forcode{ = .false.}). 
    426 This is recommended when using the UBS advection scheme on momentum (\np{ln\_dynadv\_ubs}\forcode{ = .true.}, 
    427 see \autoref{subsec:DYN_adv_ubs}) and can be useful for testing purposes. 
    428  
    429 % ================================================================ 
    430 % Eddy Induced Mixing 
    431 % ================================================================ 
    432 \section{Eddy induced velocity (\protect\mdl{traadv\_eiv}, \protect\mdl{ldfeiv})} 
     466(\autoref{sec:INVARIANTS_dynldf_properties}). 
     467 
     468%% ================================================================================================= 
     469\section[Eddy induced velocity (\forcode{ln_ldfeiv})]{Eddy induced velocity (\protect\np{ln_ldfeiv}{ln\_ldfeiv})} 
     470 
    433471\label{sec:LDF_eiv} 
    434472 
     473\begin{listing} 
     474  \nlst{namtra_eiv} 
     475  \caption{\forcode{&namtra_eiv}} 
     476  \label{lst:namtra_eiv} 
     477\end{listing} 
     478 
    435479%%gm  from Triad appendix  : to be incorporated.... 
    436 \gmcomment{ 
     480\cmtgm{ 
    437481  Values of iso-neutral diffusivity and GM coefficient are set as described in \autoref{sec:LDF_coef}. 
    438482  If none of the keys \key{traldf\_cNd}, N=1,2,3 is set (the default), spatially constant iso-neutral $A_l$ and 
    439   GM diffusivity $A_e$ are directly set by \np{rn\_aeih\_0} and \np{rn\_aeiv\_0}. 
     483  GM diffusivity $A_e$ are directly set by \np{rn_aeih_0}{rn\_aeih\_0} and \np{rn_aeiv_0}{rn\_aeiv\_0}. 
    440484  If 2D-varying coefficients are set with \key{traldf\_c2d} then $A_l$ is reduced in proportion with horizontal 
    441485  scale factor according to \autoref{eq:title} 
     
    450494    In this case, $A_e$ at low latitudes $|\theta|<20^{\circ}$ is further reduced by a factor $|f/f_{20}|$, 
    451495    where $f_{20}$ is the value of $f$ at $20^{\circ}$~N 
    452   } (\mdl{ldfeiv}) and \np{rn\_aeiv\_0} is ignored unless it is zero. 
     496  } (\mdl{ldfeiv}) and \np{rn_aeiv_0}{rn\_aeiv\_0} is ignored unless it is zero. 
    453497} 
    454498 
    455 When Gent and McWilliams [1990] diffusion is used (\key{traldf\_eiv} defined), 
     499When  \citet{gent.mcwilliams_JPO90} diffusion is used (\np[=.true.]{ln_ldfeiv}{ln\_ldfeiv}), 
    456500an eddy induced tracer advection term is added, 
    457501the formulation of which depends on the slopes of iso-neutral surfaces. 
    458502Contrary to the case of iso-neutral mixing, the slopes used here are referenced to the geopotential surfaces, 
    459 \ie \autoref{eq:ldfslp_geo} is used in $z$-coordinates, 
    460 and the sum \autoref{eq:ldfslp_geo} + \autoref{eq:ldfslp_iso} in $s$-coordinates. 
    461 The eddy induced velocity is given by:  
    462 \begin{equation} 
    463   \label{eq:ldfeiv} 
     503\ie\ \autoref{eq:LDF_slp_geo} is used in $z$-coordinates, 
     504and the sum \autoref{eq:LDF_slp_geo} + \autoref{eq:LDF_slp_iso} in $s$-coordinates. 
     505 
     506If isopycnal mixing is used in the standard way, \ie\ \np[=.false.]{ln_traldf_triad}{ln\_traldf\_triad}, the eddy induced velocity is given by: 
     507\begin{equation} 
     508  \label{eq:LDF_eiv} 
    464509  \begin{split} 
    465510    u^* & = \frac{1}{e_{2u}e_{3u}}\; \delta_k \left[e_{2u} \, A_{uw}^{eiv} \; \overline{r_{1w}}^{\,i+1/2} \right]\\ 
     
    468513  \end{split} 
    469514\end{equation} 
    470 where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{rn\_aeiv}, 
    471 a \textit{nam\_traldf} namelist parameter. 
    472 The three components of the eddy induced velocity are computed and 
    473 add to the eulerian velocity in \mdl{traadv\_eiv}. 
     515where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{nn_aei_ijk_t}{nn\_aei\_ijk\_t} \nam{tra_eiv}{tra\_eiv} namelist parameter. 
     516The three components of the eddy induced velocity are computed in \rou{ldf\_eiv\_trp} and 
     517added to the eulerian velocity in \rou{tra\_adv} where tracer advection is performed. 
    474518This has been preferred to a separate computation of the advective trends associated with the eiv velocity, 
    475519since it allows us to take advantage of all the advection schemes offered for the tracers 
    476520(see \autoref{sec:TRA_adv}) and not just the $2^{nd}$ order advection scheme as in 
    477 previous releases of OPA \citep{Madec1998}. 
     521previous releases of OPA \citep{madec.delecluse.ea_NPM98}. 
    478522This is particularly useful for passive tracers where \emph{positivity} of the advection scheme is of 
    479 paramount importance.  
     523paramount importance. 
    480524 
    481525At the surface, lateral and bottom boundaries, the eddy induced velocity, 
    482 and thus the advective eddy fluxes of heat and salt, are set to zero.  
    483  
    484 \biblio 
    485  
    486 \pindex 
     526and thus the advective eddy fluxes of heat and salt, are set to zero. 
     527The value of the eddy induced mixing coefficient and its space variation is controlled in a similar way as for lateral mixing coefficient described in the preceding subsection (\np{nn_aei_ijk_t}{nn\_aei\_ijk\_t}, \np{rn_Ue}{rn\_Ue}, \np{rn_Le}{rn\_Le} namelist parameters). 
     528\colorbox{yellow}{CASE \np{nn_aei_ijk_t}{nn\_aei\_ijk\_t} = 21 to be added} 
     529 
     530In case of setting \np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}, a skew form of the eddy induced advective fluxes is used, which is described in \autoref{apdx:TRIADS}. 
     531 
     532%% ================================================================================================= 
     533\section[Mixed layer eddies (\forcode{ln_mle})]{Mixed layer eddies (\protect\np{ln_mle}{ln\_mle})} 
     534\label{sec:LDF_mle} 
     535 
     536\begin{listing} 
     537  \nlst{namtra_mle} 
     538  \caption{\forcode{&namtra_mle}} 
     539  \label{lst:namtra_mle} 
     540\end{listing} 
     541 
     542If  \np[=.true.]{ln_mle}{ln\_mle} in \nam{tra_mle}{tra\_mle} namelist, a parameterization of the mixing due to unresolved mixed layer instabilities is activated (\citet{foxkemper.ferrari_JPO08}). Additional transport is computed in \rou{ldf\_mle\_trp} and added to the eulerian transport in \rou{tra\_adv} as done for eddy induced advection. 
     543 
     544\colorbox{yellow}{TBC} 
     545 
     546\subinc{\input{../../global/epilogue}} 
    487547 
    488548\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_OBS.tex

    r10442 r11831  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter observation operator (OBS) 
    6 % ================================================================ 
     4 
    75\chapter{Observation and Model Comparison (OBS)} 
    86\label{chap:OBS} 
    97 
    10 Authors: D. Lea, M. Martin, K. Mogensen, A. Vidard, A. Weaver, A. Ryan, ...   % do we keep that ? 
    11  
    12 \minitoc 
    13  
    14 \newpage 
    15  
    16 The observation and model comparison code (OBS) reads in observation files 
    17 (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. 
     8%\subsubsection*{Changes record} 
     9%\begin{tabular}{l||l|m{0.65\linewidth}} 
     10%    Release   & Author        & Modifications \\ 
     11%    {\em 4.0} & {\em D. J. Lea} & {\em \NEMO\ 4.0 updates}  \\ 
     12%    {\em 3.6} & {\em M. Martin, A. Ryan} & {\em Add averaging operator, standalone obs oper} \\ 
     13%    {\em 3.4} & {\em D. J. Lea, M. Martin, ...} & {\em Initial version}  \\ 
     14%    {\em --\texttt{"}--} & {\em ... K. Mogensen, A. Vidard, A. Weaver} & {\em ---\texttt{"}---}  \\ 
     15%\end{tabular} 
     16 
     17\thispagestyle{plain} 
     18 
     19\chaptertoc 
     20 
     21\paragraph{Changes record} ~\\ 
     22 
     23{\footnotesize 
     24  \begin{tabularx}{\textwidth}{l||X|X} 
     25    Release & Author(s) & Modifications \\ 
     26    \hline 
     27    {\em   4.0} & {\em ...} & {\em ...} \\ 
     28    {\em   3.6} & {\em ...} & {\em ...} \\ 
     29    {\em   3.4} & {\em ...} & {\em ...} \\ 
     30    {\em <=3.4} & {\em ...} & {\em ...} 
     31  \end{tabularx} 
     32} 
     33 
     34\clearpage 
     35 
     36The observation and model comparison code, the observation operator (OBS), reads in observation files 
     37(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. 
    1838The resulting data are saved in a ``feedback'' file (or files). 
    1939The code was originally developed for use with the NEMOVAR data assimilation code, 
    2040but can be used for validation or verification of the model or with any other data assimilation system. 
    2141 
    22 The OBS code is called from \mdl{nemogcm} for model initialisation and to calculate the model equivalent values for observations on the 0th timestep. 
    23 The code is then called again after each timestep from \mdl{step}. 
    24 The code is only activated if the namelist logical \np{ln\_diaobs} is set to true. 
     42The OBS code is called from \mdl{nemogcm} for model initialisation and to calculate the model equivalent values for observations on the 0th time step. 
     43The code is then called again after each time step from \mdl{step}. 
     44The code is only activated if the \nam{obs}{obs} namelist logical \np{ln_diaobs}{ln\_diaobs} is set to true. 
    2545 
    2646For all data types a 2D horizontal interpolator or averager is needed to 
     
    2848For {\em in situ} profiles, a 1D vertical interpolator is needed in addition to 
    2949provide model fields at the observation depths. 
    30 This now works in a generalised vertical coordinate system.  
    31  
    32 Some profile observation types (\eg tropical moored buoys) are made available as daily averaged quantities. 
     50This now works in a generalised vertical coordinate system. 
     51 
     52Some profile observation types (\eg\ tropical moored buoys) are made available as daily averaged quantities. 
    3353The observation operator code can be set-up to calculate the equivalent daily average model temperature fields using 
    34 the \np{nn\_profdavtypes} namelist array. 
     54the \np{nn_profdavtypes}{nn\_profdavtypes} namelist array. 
    3555Some SST observations are equivalent to a night-time average value and 
    3656the observation operator code can calculate equivalent night-time average model SST fields by 
    37 setting the namelist value \np{ln\_sstnight} to true. 
    38 Otherwise the model value from the nearest timestep to the observation time is used. 
    39  
    40 The code is controlled by the namelist \textit{namobs}. 
     57setting the namelist value \np{ln_sstnight}{ln\_sstnight} to true. 
     58Otherwise (by default) the model value from the nearest time step to the observation time is used. 
     59 
     60The code is controlled by the namelist \nam{obs}{obs}. 
    4161See the following sections for more details on setting up the namelist. 
    4262 
    43 \autoref{sec:OBS_example} introduces a test example of the observation operator code including 
     63In \autoref{sec:OBS_example} a test example of the observation operator code is introduced, including 
    4464where to obtain data and how to setup the namelist. 
    45 \autoref{sec:OBS_details} introduces some more technical details of the different observation types used and 
    46 also shows a more complete namelist. 
    47 \autoref{sec:OBS_theory} introduces some of the theoretical aspects of the observation operator including 
     65In \autoref{sec:OBS_details} some more technical details of the different observation types used are introduced, and we 
     66also show a more complete namelist. 
     67In \autoref{sec:OBS_theory} some of the theoretical aspects of the observation operator are described including 
    4868interpolation methods and running on multiple processors. 
    49 \autoref{sec:OBS_ooo} describes the offline observation operator code. 
    50 \autoref{sec:OBS_obsutils} introduces some utilities to help working with the files produced by the OBS code. 
    51  
    52 % ================================================================ 
    53 % Example 
    54 % ================================================================ 
     69In \autoref{sec:OBS_sao} the standalone observation operator code is described. 
     70In \autoref{sec:OBS_obsutils} we describe some utilities to help work with the files produced by the OBS code. 
     71 
     72%% ================================================================================================= 
    5573\section{Running the observation operator code example} 
    5674\label{sec:OBS_example} 
    5775 
    58 This section describes an example of running the observation operator code using 
    59 profile data which can be freely downloaded. 
    60 It shows how to adapt an existing run and build of NEMO to run the observation operator. 
     76In this section an example of running the observation operator code is described using 
     77profile observation data which can be freely downloaded. 
     78It shows how to adapt an existing run and build of \NEMO\ to run the observation operator. Note also the observation operator and the assimilation increments code are run in the ORCA2\_ICE\_OBS SETTE test. 
    6179 
    6280\begin{enumerate} 
    63 \item Compile NEMO. 
     81\item Compile \NEMO. 
    6482 
    6583\item Download some EN4 data from \href{http://www.metoffice.gov.uk/hadobs}{www.metoffice.gov.uk/hadobs}. 
    6684  Choose observations which are valid for the period of your test run because 
    67   the observation operator compares the model and observations for a matching date and time.  
    68  
    69 \item Compile the OBSTOOLS code using:  
     85  the observation operator compares the model and observations for a matching date and time. 
     86 
     87\item Compile the OBSTOOLS code in the \path{tools} directory using: 
    7088\begin{cmds} 
    71 ./maketools -n OBSTOOLS -m [ARCH]. 
     89./maketools -n OBSTOOLS -m [ARCH] 
    7290\end{cmds} 
    7391 
    74 \item Convert the EN4 data into feedback format:  
     92replacing \texttt{[ARCH]} with the build architecture file for your machine. Note the tools are checked out from a separate location of the repository (under \path{/utils/tools}). 
     93 
     94\item Convert the EN4 data into feedback format: 
    7595\begin{cmds} 
    7696enact2fb.exe profiles_01.nc EN.4.1.1.f.profiles.g10.YYYYMM.nc 
    7797\end{cmds} 
    7898 
    79 \item Include the following in the NEMO namelist to run the observation operator on this data: 
     99\item Include the following in the \NEMO\ namelist to run the observation operator on this data: 
    80100\end{enumerate} 
    81101 
    82 Options are defined through the \ngn{namobs} namelist variables. 
    83 The options \np{ln\_t3d} and \np{ln\_s3d} switch on the temperature and salinity profile observation operator code. 
    84 The filename or array of filenames are specified using the \np{cn\_profbfiles} variable. 
     102Options are defined through the \nam{obs}{obs} namelist variables. 
     103The options \np{ln_t3d}{ln\_t3d} and \np{ln_s3d}{ln\_s3d} switch on the temperature and salinity profile observation operator code. 
     104The filename or array of filenames are specified using the \np{cn_profbfiles}{cn\_profbfiles} variable. 
    85105The model grid points for a particular observation latitude and longitude are found using 
    86106the grid searching part of the code. 
    87107This can be expensive, particularly for large numbers of observations, 
    88 setting \np{ln\_grid\_search\_lookup} allows the use of a lookup table which 
    89 is saved into an ``xypos`` file (or files). 
     108setting \np{ln_grid_search_lookup}{ln\_grid\_search\_lookup} allows the use of a lookup table which 
     109is saved into an \np{cn_gridsearch}{cn\_gridsearch} file (or files). 
    90110This will need to be generated the first time if it does not exist in the run directory. 
    91111However, once produced it will significantly speed up future grid searches. 
    92 Setting \np{ln\_grid\_global} means that the code distributes the observations evenly between processors. 
     112Setting \np{ln_grid_global}{ln\_grid\_global} means that the code distributes the observations evenly between processors. 
    93113Alternatively each processor will work with observations located within the model subdomain 
    94 (see section~\autoref{subsec:OBS_parallel}). 
     114(see \autoref{subsec:OBS_parallel}). 
    95115 
    96116A number of utilities are now provided to plot the feedback files, convert and recombine the files. 
    97 These are explained in more detail in section~\autoref{sec:OBS_obsutils}. 
    98 Utilites to convert other input data formats into the feedback format are also described in 
    99 section~\autoref{sec:OBS_obsutils}. 
    100  
     117These are explained in more detail in \autoref{sec:OBS_obsutils}. 
     118Utilities to convert other input data formats into the feedback format are also described in 
     119\autoref{sec:OBS_obsutils}. 
     120 
     121%% ================================================================================================= 
    101122\section{Technical details (feedback type observation file headers)} 
    102123\label{sec:OBS_details} 
    103124 
    104 Here we show a more complete example namelist \ngn{namobs} and also show the NetCDF headers of 
     125Here we show a more complete example namelist \nam{obs}{obs} and also show the NetCDF headers of 
    105126the observation files that may be used with the observation operator. 
    106127 
    107 %------------------------------------------namobs-------------------------------------------------------- 
    108  
    109 \nlst{namobs} 
    110 %------------------------------------------------------------------------------------------------------------- 
    111  
    112 The observation operator code uses the "feedback" observation file format for all data types. 
     128\begin{listing} 
     129  \nlst{namobs} 
     130  \caption{\forcode{&namobs}} 
     131  \label{lst:namobs} 
     132\end{listing} 
     133 
     134The observation operator code uses the feedback observation file format for all data types. 
    113135All the observation files must be in NetCDF format. 
    114136Some example headers (produced using \mbox{\textit{ncdump~-h}}) for profile data, sea level anomaly and 
    115137sea surface temperature are in the following subsections. 
    116138 
    117 \subsection{Profile feedback} 
     139%% ================================================================================================= 
     140\subsection{Profile feedback file} 
    118141 
    119142\begin{clines} 
     
    271294\end{clines} 
    272295 
    273 \subsection{Sea level anomaly feedback} 
     296%% ================================================================================================= 
     297\subsection{Sea level anomaly feedback file} 
    274298 
    275299\begin{clines} 
     
    395419\end{clines} 
    396420 
    397 The mean dynamic topography (MDT) must be provided in a separate file defined on 
     421To use Sea Level Anomaly (SLA) data the mean dynamic topography (MDT) must be provided in a separate file defined on 
    398422the model grid called \ifile{slaReferenceLevel}. 
    399423The MDT is required in order to produce the model equivalent sea level anomaly from the model sea surface height. 
     
    417441\end{clines} 
    418442 
    419 \subsection{Sea surface temperature feedback} 
     443%% ================================================================================================= 
     444\subsection{Sea surface temperature feedback file} 
    420445 
    421446\begin{clines} 
     
    534559\end{clines} 
    535560 
     561%% ================================================================================================= 
    536562\section{Theoretical details} 
    537563\label{sec:OBS_theory} 
    538564 
     565%% ================================================================================================= 
    539566\subsection{Horizontal interpolation and averaging methods} 
    540567 
     
    542569the model equivalent of the observation is calculated by interpolating from 
    543570the four surrounding grid points to the observation location. 
    544 Some satellite observations (\eg microwave satellite SST data, or satellite SSS data) have a footprint which 
     571Some satellite observations (\eg\ microwave satellite SST data, or satellite SSS data) have a footprint which 
    545572is similar in size or larger than the model grid size (particularly when the grid size is small). 
    546573In those cases the model counterpart should be calculated by averaging the model grid points over 
    547574the same size as the footprint. 
    548 NEMO therefore has the capability to specify either an interpolation or an averaging 
    549 (for surface observation types only).  
    550  
    551 The main namelist option associated with the interpolation/averaging is \np{nn\_2dint}. 
     575\NEMO\ therefore has the capability to specify either an interpolation or an averaging 
     576(for surface observation types only). 
     577 
     578The main namelist option associated with the interpolation/averaging is \np{nn_2dint}{nn\_2dint}. 
    552579This default option can be set to values from 0 to 6. 
    553580Values between 0 to 4 are associated with interpolation while values 5 or 6 are associated with averaging. 
    554581\begin{itemize} 
    555 \item \np{nn\_2dint}\forcode{ = 0}: Distance-weighted interpolation 
    556 \item \np{nn\_2dint}\forcode{ = 1}: Distance-weighted interpolation (small angle) 
    557 \item \np{nn\_2dint}\forcode{ = 2}: Bilinear interpolation (geographical grid) 
    558 \item \np{nn\_2dint}\forcode{ = 3}: Bilinear remapping interpolation (general grid) 
    559 \item \np{nn\_2dint}\forcode{ = 4}: Polynomial interpolation 
    560 \item \np{nn\_2dint}\forcode{ = 5}: Radial footprint averaging with diameter specified in the namelist as 
    561   \np{rn\_???\_avglamscl} in degrees or metres (set using \np{ln\_???\_fp\_indegs}) 
    562 \item \np{nn\_2dint}\forcode{ = 6}: Rectangular footprint averaging with E/W and N/S size specified in 
    563   the namelist as \np{rn\_???\_avglamscl} and \np{rn\_???\_avgphiscl} in degrees or metres 
    564   (set using \np{ln\_???\_fp\_indegs}) 
     582\item \np[=0]{nn_2dint}{nn\_2dint}: Distance-weighted interpolation 
     583\item \np[=1]{nn_2dint}{nn\_2dint}: Distance-weighted interpolation (small angle) 
     584\item \np[=2]{nn_2dint}{nn\_2dint}: Bilinear interpolation (geographical grid) 
     585\item \np[=3]{nn_2dint}{nn\_2dint}: Bilinear remapping interpolation (general grid) 
     586\item \np[=4]{nn_2dint}{nn\_2dint}: Polynomial interpolation 
     587\item \np[=5]{nn_2dint}{nn\_2dint}: Radial footprint averaging with diameter specified in the namelist as 
     588  \texttt{rn\_[var]\_avglamscl} in degrees or metres (set using \texttt{ln\_[var]\_fp\_indegs}) 
     589\item \np[=6]{nn_2dint}{nn\_2dint}: Rectangular footprint averaging with E/W and N/S size specified in 
     590  the namelist as \texttt{rn\_[var]\_avglamscl} and \texttt{rn\_[var]\_avgphiscl} in degrees or metres 
     591  (set using \texttt{ln\_[var]\_fp\_indegs}) 
    565592\end{itemize} 
    566 The ??? in the last two options indicate these options should be specified for each observation type for 
     593Replace \texttt{[var]} in the last two options with the observation type (sla, sst, sss or sic) for 
    567594which the averaging is to be performed (see namelist example above). 
    568 The \np{nn\_2dint} default option can be overridden for surface observation types using 
    569 namelist values \np{nn\_2dint\_???} where ??? is one of sla,sst,sss,sic. 
    570  
    571 Below is some more detail on the various options for interpolation and averaging available in NEMO. 
    572  
     595The \np{nn_2dint}{nn\_2dint} default option can be overridden for surface observation types using 
     596namelist values \texttt{nn\_2dint\_[var]} where \texttt{[var]} is the observation type. 
     597 
     598Below is some more detail on the various options for interpolation and averaging available in \NEMO. 
     599 
     600%% ================================================================================================= 
    573601\subsubsection{Horizontal interpolation} 
    574602 
    575 Consider an observation point ${\rm P}$ with with longitude and latitude $({\lambda_{}}_{\rm P}, \phi_{\rm P})$ and 
    576 the four nearest neighbouring model grid points ${\rm A}$, ${\rm B}$, ${\rm C}$ and ${\rm D}$ with 
    577 longitude and latitude ($\lambda_{\rm A}$, $\phi_{\rm A}$),($\lambda_{\rm B}$, $\phi_{\rm B}$) etc. 
    578 All horizontal interpolation methods implemented in NEMO estimate the value of a model variable $x$ at point $P$ as 
    579 a weighted linear combination of the values of the model variables at the grid points ${\rm A}$, ${\rm B}$ etc.: 
     603Consider an observation point ${\mathrm P}$ with longitude and latitude (${\lambda_{}}_{\mathrm P}$, $\phi_{\mathrm P}$) and 
     604the four nearest neighbouring model grid points ${\mathrm A}$, ${\mathrm B}$, ${\mathrm C}$ and ${\mathrm D}$ with 
     605longitude and latitude ($\lambda_{\mathrm A}$, $\phi_{\mathrm A}$),($\lambda_{\mathrm B}$, $\phi_{\mathrm B}$) etc. 
     606All horizontal interpolation methods implemented in \NEMO\ estimate the value of a model variable $x$ at point $P$ as 
     607a weighted linear combination of the values of the model variables at the grid points ${\mathrm A}$, ${\mathrm B}$ etc.: 
     608 
    580609\begin{align*} 
    581   {x_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & 
    582                                                    \frac{1}{w} \left( {w_{}}_{\rm A} {x_{}}_{\rm A} + 
    583                                                    {w_{}}_{\rm B} {x_{}}_{\rm B} + 
    584                                                    {w_{}}_{\rm C} {x_{}}_{\rm C} + 
    585                                                    {w_{}}_{\rm D} {x_{}}_{\rm D} \right) 
     610  {x_{}}_{\mathrm P} = 
     611\frac{1}{w} \left( {w_{}}_{\mathrm A} {x_{}}_{\mathrm A} + 
     612{w_{}}_{\mathrm B} {x_{}}_{\mathrm B} + 
     613{w_{}}_{\mathrm C} {x_{}}_{\mathrm C} + 
     614{w_{}}_{\mathrm D} {x_{}}_{\mathrm D} \right) 
    586615\end{align*} 
    587 where ${w_{}}_{\rm A}$, ${w_{}}_{\rm B}$ etc. are the respective weights for the model field at 
    588 points ${\rm A}$, ${\rm B}$ etc., and $w = {w_{}}_{\rm A} + {w_{}}_{\rm B} + {w_{}}_{\rm C} + {w_{}}_{\rm D}$. 
     616 
     617where ${w_{}}_{\mathrm A}$, ${w_{}}_{\mathrm B}$ etc. are the respective weights for the model field at 
     618points ${\mathrm A}$, ${\mathrm B}$ etc., and $w = {w_{}}_{\mathrm A} + {w_{}}_{\mathrm B} + {w_{}}_{\mathrm C} + {w_{}}_{\mathrm D}$. 
    589619 
    590620Four different possibilities are available for computing the weights. 
    591621 
    592622\begin{enumerate} 
    593  
    594 \item[1.] {\bf Great-Circle distance-weighted interpolation.} 
     623\item {\bfseries Great-Circle distance-weighted interpolation.} 
    595624  The weights are computed as a function of the great-circle distance $s(P, \cdot)$ between $P$ and 
    596625  the model grid points $A$, $B$ etc. 
    597   For example, the weight given to the field ${x_{}}_{\rm A}$ is specified as the product of the distances 
    598   from ${\rm P}$ to the other points: 
    599   \begin{align*} 
    600     {w_{}}_{\rm A} = s({\rm P}, {\rm B}) \, s({\rm P}, {\rm C}) \, s({\rm P}, {\rm D}) 
    601   \end{align*} 
    602   where  
    603   \begin{align*} 
    604     s\left ({\rm P}, {\rm M} \right )  
    605      & \hspace{-2mm} = \hspace{-2mm} &  
    606       \cos^{-1} \! \left\{  
    607                \sin {\phi_{}}_{\rm P} \sin {\phi_{}}_{\rm M} 
    608              + \cos {\phi_{}}_{\rm P} \cos {\phi_{}}_{\rm M}  
    609                \cos ({\lambda_{}}_{\rm M} - {\lambda_{}}_{\rm P})  
     626  For example, the weight given to the field ${x_{}}_{\mathrm A}$ is specified as the product of the distances 
     627  from ${\mathrm P}$ to the other points: 
     628 
     629  \begin{alignat*}{2} 
     630    {w_{}}_{\mathrm A} = s({\mathrm P}, {\mathrm B}) \, s({\mathrm P}, {\mathrm C}) \, s({\mathrm P}, {\mathrm D}) 
     631  \end{alignat*} 
     632 
     633  where 
     634 
     635  \begin{alignat*}{2} 
     636    s\left({\mathrm P}, {\mathrm M} \right) & = & \hspace{0.25em} \cos^{-1} \! \left\{ 
     637               \sin {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm M} 
     638             + \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm M} 
     639               \cos ({\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P}) 
    610640                   \right\} 
    611    \end{align*} 
     641   \end{alignat*} 
     642 
    612643   and $M$ corresponds to $B$, $C$ or $D$. 
    613644   A more stable form of the great-circle distance formula for small distances ($x$ near 1) 
    614    involves the arcsine function (\eg see p.~101 of \citet{Daley_Barker_Bk01}: 
    615    \begin{align*} 
    616      s\left( {\rm P}, {\rm M} \right) & \hspace{-2mm} = \hspace{-2mm} & \sin^{-1} \! \left\{ \sqrt{ 1 - x^2 } \right\} 
    617    \end{align*} 
     645   involves the arcsine function (\eg\ see p.~101 of \citet{daley.barker_bk01}: 
     646 
     647   \begin{alignat*}{2} 
     648     s\left( {\mathrm P}, {\mathrm M} \right) = \sin^{-1} \! \left\{ \sqrt{ 1 - x^2 } \right\} 
     649   \end{alignat*} 
     650 
    618651   where 
    619    \begin{align*} 
    620      x & \hspace{-2mm} = \hspace{-2mm} & 
    621                                          {a_{}}_{\rm M} {a_{}}_{\rm P} + {b_{}}_{\rm M} {b_{}}_{\rm P} + {c_{}}_{\rm M} {c_{}}_{\rm P} 
    622    \end{align*} 
    623    and  
    624    \begin{align*} 
    625       {a_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\rm M}, \\ 
    626       {a_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\rm P}, \\ 
    627       {b_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm M} \cos {\phi_{}}_{\rm M}, \\ 
    628       {b_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm P} \cos {\phi_{}}_{\rm P}, \\ 
    629       {c_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm M} \sin {\phi_{}}_{\rm M}, \\ 
    630       {c_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm P} \sin {\phi_{}}_{\rm P}. 
    631   \end{align*} 
    632  
    633 \item[2.] {\bf Great-Circle distance-weighted interpolation with small angle approximation.} 
     652 
     653   \begin{alignat*}{2} 
     654     x = {a_{}}_{\mathrm M} {a_{}}_{\mathrm P} + {b_{}}_{\mathrm M} {b_{}}_{\mathrm P} + {c_{}}_{\mathrm M} {c_{}}_{\mathrm P} 
     655   \end{alignat*} 
     656 
     657   and 
     658 
     659   \begin{alignat*}{3} 
     660   & {a_{}}_{\mathrm M} & = && \quad \sin {\phi_{}}_{\mathrm M}, \\ 
     661   & {a_{}}_{\mathrm P} & = && \quad \sin {\phi_{}}_{\mathrm P}, \\ 
     662   & {b_{}}_{\mathrm M} & = && \quad \cos {\phi_{}}_{\mathrm M} \cos {\phi_{}}_{\mathrm M}, \\ 
     663   & {b_{}}_{\mathrm P} & = && \quad \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm P}, \\ 
     664   & {c_{}}_{\mathrm M} & = && \quad \cos {\phi_{}}_{\mathrm M} \sin {\phi_{}}_{\mathrm M}, \\ 
     665   & {c_{}}_{\mathrm P} & = && \quad \cos {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm P}. 
     666   \end{alignat*} 
     667 
     668\item {\bfseries Great-Circle distance-weighted interpolation with small angle approximation.} 
    634669  Similar to the previous interpolation but with the distance $s$ computed as 
    635   \begin{align*} 
    636     s\left( {\rm P}, {\rm M} \right) 
    637     & \hspace{-2mm} = \hspace{-2mm} & 
    638                                       \sqrt{ \left( {\phi_{}}_{\rm M} - {\phi_{}}_{\rm P} \right)^{2} 
    639                                       + \left( {\lambda_{}}_{\rm M} - {\lambda_{}}_{\rm P} \right)^{2} 
    640                                       \cos^{2} {\phi_{}}_{\rm M} } 
    641   \end{align*} 
     670  \begin{alignat*}{2} 
     671    s\left( {\mathrm P}, {\mathrm M} \right) 
     672    & = & \sqrt{ \left( {\phi_{}}_{\mathrm M} - {\phi_{}}_{\mathrm P} \right)^{2} 
     673                                      + \left( {\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P} \right)^{2} 
     674                                      \cos^{2} {\phi_{}}_{\mathrm M} } 
     675  \end{alignat*} 
    642676  where $M$ corresponds to $A$, $B$, $C$ or $D$. 
    643677 
    644 \item[3.] {\bf Bilinear interpolation for a regular spaced grid.} 
     678\item {\bfseries Bilinear interpolation for a regular spaced grid.} 
    645679  The interpolation is split into two 1D interpolations in the longitude and latitude directions, respectively. 
    646680 
    647 \item[4.] {\bf Bilinear remapping interpolation for a general grid.} 
     681\item {\bfseries Bilinear remapping interpolation for a general grid.} 
    648682  An iterative scheme that involves first mapping a quadrilateral cell into 
    649683  a cell with coordinates (0,0), (1,0), (0,1) and (1,1). 
    650   This method is based on the SCRIP interpolation package \citep{Jones_1998}. 
    651    
     684  This method is based on the \href{https://github.com/SCRIP-Project/SCRIP}{SCRIP interpolation package}. 
     685 
    652686\end{enumerate} 
    653687 
     688%% ================================================================================================= 
    654689\subsubsection{Horizontal averaging} 
    655690 
     
    658693\item The standard grid-searching code is used to find the nearest model grid point to the observation location 
    659694  (see next subsection). 
    660 \item The maximum number of grid points is calculated in the local grid domain for which 
    661   the averaging is likely need to cover. 
    662 \item The lats/longs of the grid points surrounding the nearest model grid box are extracted using 
    663   existing mpi routines. 
     695\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. 
     696\item The longitudes and latitudes of the grid points surrounding the nearest model grid box are extracted using 
     697  existing MPI routines. 
    664698\item The weights for each grid point associated with each observation are calculated, 
    665699  either for radial or rectangular footprints. 
     
    673707 
    674708Examples of the weights calculated for an observation with rectangular and radial footprints are shown in 
    675 Figs.~\autoref{fig:obsavgrec} and~\autoref{fig:obsavgrad}. 
    676  
    677 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     709\autoref{fig:OBS_avgrec} and~\autoref{fig:OBS_avgrad}. 
     710 
    678711\begin{figure} 
    679   \begin{center} 
    680     \includegraphics[width=0.90\textwidth]{Fig_OBS_avg_rec} 
    681     \caption{ 
    682       \protect\label{fig:obsavgrec} 
    683       Weights associated with each model grid box (blue lines and numbers) 
    684       for an observation at -170.5\deg{E}, 56.0\deg{N} with a rectangular footprint of 1\deg x 1\deg. 
    685     } 
    686   \end{center} 
     712  \centering 
     713  \includegraphics[width=0.66\textwidth]{OBS_avg_rec} 
     714  \caption[Observational weights with a rectangular footprint]{ 
     715    Weights associated with each model grid box (blue lines and numbers) 
     716    for an observation at -170.5\deg{E}, 56.0\deg{N} with a rectangular footprint of 1\deg\ x 1\deg.} 
     717  \label{fig:OBS_avgrec} 
    687718\end{figure} 
    688 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    689  
    690 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     719 
    691720\begin{figure} 
    692   \begin{center} 
    693     \includegraphics[width=0.90\textwidth]{Fig_OBS_avg_rad} 
    694     \caption{ 
    695       \protect\label{fig:obsavgrad} 
    696       Weights associated with each model grid box (blue lines and numbers) 
    697       for an observation at -170.5\deg{E}, 56.0\deg{N} with a radial footprint with diameter 1\deg. 
    698     }  
    699   \end{center} 
     721  \centering 
     722  \includegraphics[width=0.66\textwidth]{OBS_avg_rad} 
     723  \caption[Observational weights with a radial footprint]{ 
     724    Weights associated with each model grid box (blue lines and numbers) 
     725    for an observation at -170.5\deg{E}, 56.0\deg{N} with a radial footprint with diameter 1\deg.} 
     726  \label{fig:OBS_avgrad} 
    700727\end{figure} 
    701 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    702  
    703  
     728 
     729%% ================================================================================================= 
    704730\subsection{Grid search} 
    705731 
    706 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. 
     732For 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. 
    707733Therefore, it is not always straightforward to determine the grid points surrounding any given observational position. 
    708 Before the interpolation can be performed, a search algorithm is then required to determine the corner points of  
     734Before the interpolation can be performed, a search algorithm is then required to determine the corner points of 
    709735the quadrilateral cell in which the observation is located. 
    710 This is the most difficult and time consuming part of the 2D interpolation procedure.  
     736This is the most difficult and time consuming part of the 2D interpolation procedure. 
    711737A robust test for determining if an observation falls within a given quadrilateral cell is as follows. 
    712 Let ${\rm P}({\lambda_{}}_{\rm P} ,{\phi_{}}_{\rm P} )$ denote the observation point, 
    713 and let ${\rm A}({\lambda_{}}_{\rm A} ,{\phi_{}}_{\rm A} )$, ${\rm B}({\lambda_{}}_{\rm B} ,{\phi_{}}_{\rm B} )$, 
    714 ${\rm C}({\lambda_{}}_{\rm C} ,{\phi_{}}_{\rm C} )$ and ${\rm D}({\lambda_{}}_{\rm D} ,{\phi_{}}_{\rm D} )$ 
    715 denote the bottom left, bottom right, top left and top right corner points of the cell, respectively.  
    716 To determine if P is inside the cell, we verify that the cross-products  
     738Let ${\mathrm P}({\lambda_{}}_{\mathrm P} ,{\phi_{}}_{\mathrm P} )$ denote the observation point, 
     739and let ${\mathrm A}({\lambda_{}}_{\mathrm A} ,{\phi_{}}_{\mathrm A} )$, ${\mathrm B}({\lambda_{}}_{\mathrm B} ,{\phi_{}}_{\mathrm B} )$, 
     740${\mathrm C}({\lambda_{}}_{\mathrm C} ,{\phi_{}}_{\mathrm C} )$ and ${\mathrm D}({\lambda_{}}_{\mathrm D} ,{\phi_{}}_{\mathrm D} )$ 
     741denote the bottom left, bottom right, top left and top right corner points of the cell, respectively. 
     742To determine if P is inside the cell, we verify that the cross-products 
    717743\begin{align*} 
    718744  \begin{array}{lllll} 
    719     {{\bf r}_{}}_{\rm PA} \times {{\bf r}_{}}_{\rm PC} 
    720     & = & [({\lambda_{}}_{\rm A}\; -\; {\lambda_{}}_{\rm P} ) 
    721           ({\phi_{}}_{\rm C}   \; -\; {\phi_{}}_{\rm P} ) 
    722           - ({\lambda_{}}_{\rm C}\; -\; {\lambda_{}}_{\rm P} ) 
    723           ({\phi_{}}_{\rm A}   \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\ 
    724     {{\bf r}_{}}_{\rm PB} \times {{\bf r}_{}}_{\rm PA} 
    725     & = & [({\lambda_{}}_{\rm B}\; -\; {\lambda_{}}_{\rm P} ) 
    726           ({\phi_{}}_{\rm A}   \; -\; {\phi_{}}_{\rm P} ) 
    727           - ({\lambda_{}}_{\rm A}\; -\; {\lambda_{}}_{\rm P} ) 
    728           ({\phi_{}}_{\rm B}   \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\ 
    729     {{\bf r}_{}}_{\rm PC} \times {{\bf r}_{}}_{\rm PD} 
    730     & = & [({\lambda_{}}_{\rm C}\; -\; {\lambda_{}}_{\rm P} ) 
    731           ({\phi_{}}_{\rm D}   \; -\; {\phi_{}}_{\rm P} ) 
    732           - ({\lambda_{}}_{\rm D}\; -\; {\lambda_{}}_{\rm P} ) 
    733           ({\phi_{}}_{\rm C}   \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\ 
    734     {{\bf r}_{}}_{\rm PD} \times {{\bf r}_{}}_{\rm PB} 
    735     & = & [({\lambda_{}}_{\rm D}\; -\; {\lambda_{}}_{\rm P} ) 
    736           ({\phi_{}}_{\rm B}   \; -\; {\phi_{}}_{\rm P} ) 
    737           - ({\lambda_{}}_{\rm B}\; -\; {\lambda_{}}_{\rm P} ) 
    738           ({\phi_{}}_{\rm D}  \;  - \; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\ 
     745    {{\mathbf r}_{}}_{\mathrm PA} \times {{\mathbf r}_{}}_{\mathrm PC} 
     746    & = & [({\lambda_{}}_{\mathrm A}\; -\; {\lambda_{}}_{\mathrm P} ) 
     747          ({\phi_{}}_{\mathrm C}   \; -\; {\phi_{}}_{\mathrm P} ) 
     748          - ({\lambda_{}}_{\mathrm C}\; -\; {\lambda_{}}_{\mathrm P} ) 
     749          ({\phi_{}}_{\mathrm A}   \; -\; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\ 
     750    {{\mathbf r}_{}}_{\mathrm PB} \times {{\mathbf r}_{}}_{\mathrm PA} 
     751    & = & [({\lambda_{}}_{\mathrm B}\; -\; {\lambda_{}}_{\mathrm P} ) 
     752          ({\phi_{}}_{\mathrm A}   \; -\; {\phi_{}}_{\mathrm P} ) 
     753          - ({\lambda_{}}_{\mathrm A}\; -\; {\lambda_{}}_{\mathrm P} ) 
     754          ({\phi_{}}_{\mathrm B}   \; -\; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\ 
     755    {{\mathbf r}_{}}_{\mathrm PC} \times {{\mathbf r}_{}}_{\mathrm PD} 
     756    & = & [({\lambda_{}}_{\mathrm C}\; -\; {\lambda_{}}_{\mathrm P} ) 
     757          ({\phi_{}}_{\mathrm D}   \; -\; {\phi_{}}_{\mathrm P} ) 
     758          - ({\lambda_{}}_{\mathrm D}\; -\; {\lambda_{}}_{\mathrm P} ) 
     759          ({\phi_{}}_{\mathrm C}   \; -\; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\ 
     760    {{\mathbf r}_{}}_{\mathrm PD} \times {{\mathbf r}_{}}_{\mathrm PB} 
     761    & = & [({\lambda_{}}_{\mathrm D}\; -\; {\lambda_{}}_{\mathrm P} ) 
     762          ({\phi_{}}_{\mathrm B}   \; -\; {\phi_{}}_{\mathrm P} ) 
     763          - ({\lambda_{}}_{\mathrm B}\; -\; {\lambda_{}}_{\mathrm P} ) 
     764          ({\phi_{}}_{\mathrm D}  \;  - \; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\ 
    739765  \end{array} 
    740   % \label{eq:cross} 
     766  % \label{eq:OBS_cross} 
    741767\end{align*} 
    742 point in the opposite direction to the unit normal $\widehat{\bf k}$ 
    743 (\ie that the coefficients of $\widehat{\bf k}$ are negative), 
    744 where ${{\bf r}_{}}_{\rm PA}$, ${{\bf r}_{}}_{\rm PB}$, etc. correspond to 
     768point in the opposite direction to the unit normal $\widehat{\mathbf k}$ 
     769(\ie\ that the coefficients of $\widehat{\mathbf k}$ are negative), 
     770where ${{\mathbf r}_{}}_{\mathrm PA}$, ${{\mathbf r}_{}}_{\mathrm PB}$, etc. correspond to 
    745771the vectors between points P and A, P and B, etc.. 
    746 The method used is similar to the method used in the SCRIP interpolation package \citep{Jones_1998}. 
     772The method used is similar to the method used in the \href{https://github.com/SCRIP-Project/SCRIP}{SCRIP interpolation package}. 
    747773 
    748774In order to speed up the grid search, there is the possibility to construct a lookup table for a user specified resolution. 
     
    750776be searched for on a regular grid. 
    751777For each observation position, the closest point on the regular grid of this position is computed and 
    752 the $i$ and $j$ ranges of this point searched to determine the precise four points surrounding the observation.  
    753  
     778the $i$ and $j$ ranges of this point searched to determine the precise four points surrounding the observation. 
     779 
     780%% ================================================================================================= 
    754781\subsection{Parallel aspects of horizontal interpolation} 
    755782\label{subsec:OBS_parallel} 
     
    757784For horizontal interpolation, there is the basic problem that 
    758785the observations are unevenly distributed on the globe. 
    759 In numerical models, it is common to divide the model grid into subgrids (or domains) where 
     786In \NEMO\ the model grid is divided into subgrids (or domains) where 
    760787each subgrid is executed on a single processing element with explicit message passing for 
    761788exchange of information along the domain boundaries when running on a massively parallel processor (MPP) system. 
    762 This approach is used by \NEMO. 
    763  
    764 For observations there is no natural distribution since the observations are not equally distributed on the globe.  
     789 
     790For observations there is no natural distribution since the observations are not equally distributed on the globe. 
    765791Two options have been made available: 
    7667921) geographical distribution; 
    767793and 2) round-robin. 
    768794 
     795%% ================================================================================================= 
    769796\subsubsection{Geographical distribution of observations among processors} 
    770797 
    771 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    772798\begin{figure} 
    773   \begin{center} 
    774     \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_ASM_obsdist_local} 
    775     \caption{ 
    776       \protect\label{fig:obslocal} 
    777       Example of the distribution of observations with the geographical distribution of observational data. 
    778     } 
    779   \end{center} 
     799  \centering 
     800  \includegraphics[width=0.66\textwidth]{OBS_obsdist_local} 
     801  \caption[Observations with the geographical distribution]{ 
     802    Example of the distribution of observations with 
     803    the geographical distribution of observational data} 
     804  \label{fig:OBS_local} 
    780805\end{figure} 
    781 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    782806 
    783807This is the simplest option in which the observations are distributed according to 
    784808the domain of the grid-point parallelization. 
    785 \autoref{fig:obslocal} shows an example of the distribution of the {\em in situ} data on processors with 
    786 a different colour for each observation on a given processor for a 4 $\times$ 2 decomposition with ORCA2.  
     809\autoref{fig:OBS_local} shows an example of the distribution of the {\em in situ} data on processors with 
     810a different colour for each observation on a given processor for a 4 $\times$ 2 decomposition with ORCA2. 
    787811The grid-point domain decomposition is clearly visible on the plot. 
    788812 
    789813The advantage of this approach is that all information needed for horizontal interpolation is available without 
    790814any MPP communication. 
    791 Of course, this is under the assumption that we are only using a $2 \times 2$ grid-point stencil for 
    792 the interpolation (\eg bilinear interpolation). 
     815This is under the assumption that we are dealing with point observations and only using a $2 \times 2$ grid-point stencil for 
     816the interpolation (\eg\ bilinear interpolation). 
    793817For higher order interpolation schemes this is no longer valid. 
    794818A disadvantage with the above scheme is that the number of observations on each processor can be very different. 
     
    796820this could lead to load imbalance. 
    797821 
     822%% ================================================================================================= 
    798823\subsubsection{Round-robin distribution of observations among processors} 
    799824 
    800 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    801825\begin{figure} 
    802   \begin{center} 
    803     \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_ASM_obsdist_global} 
    804     \caption{ 
    805       \protect\label{fig:obsglobal} 
    806       Example of the distribution of observations with the round-robin distribution of observational data. 
    807     } 
    808   \end{center} 
     826  \centering 
     827  \includegraphics[width=0.66\textwidth]{OBS_obsdist_global} 
     828  \caption[Observations with the round-robin distribution]{ 
     829    Example of the distribution of observations with 
     830    the round-robin distribution of observational data.} 
     831  \label{fig:OBS_global} 
    809832\end{figure} 
    810 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    811833 
    812834An alternative approach is to distribute the observations equally among processors and 
    813835use message passing in order to retrieve the stencil for interpolation. 
    814836The simplest distribution of the observations is to distribute them using a round-robin scheme. 
    815 \autoref{fig:obsglobal} shows the distribution of the {\em in situ} data on processors for 
     837\autoref{fig:OBS_global} shows the distribution of the {\em in situ} data on processors for 
    816838the round-robin distribution of observations with a different colour for each observation on a given processor for 
    817 a 4 $\times$ 2 decomposition with ORCA2 for the same input data as in \autoref{fig:obslocal}. 
     839a 4 $\times$ 2 decomposition with ORCA2 for the same input data as in \autoref{fig:OBS_local}. 
    818840The observations are now clearly randomly distributed on the globe. 
    819841In order to be able to perform horizontal interpolation in this case, 
    820842a subroutine has been developed that retrieves any grid points in the global space. 
    821843 
     844%% ================================================================================================= 
    822845\subsection{Vertical interpolation operator} 
    823846 
     
    827850At the bottom boundary, this is done using the land-ocean mask. 
    828851 
    829 \newpage 
    830  
    831 % ================================================================ 
    832 % Offline observation operator documentation 
    833 % ================================================================ 
     852For 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. 
    834853 
    835854%\usepackage{framed} 
    836855 
    837 \section{Offline observation operator} 
    838 \label{sec:OBS_ooo} 
    839  
     856%% ================================================================================================= 
     857\section{Standalone observation operator (\texttt{SAO})} 
     858\label{sec:OBS_sao} 
     859 
     860%% ================================================================================================= 
    840861\subsection{Concept} 
    841862 
    842 The obs oper maps model variables to observation space. 
    843 It is possible to apply this mapping without running the model. 
    844 The software which performs this functionality is known as the \textbf{offline obs oper}. 
    845 The obs oper is divided into three stages. 
    846 An initialisation phase, an interpolation phase and an output phase. 
    847 The implementation of which is outlined in the previous sections. 
    848 During the interpolation phase the offline obs oper populates the model arrays by 
    849 reading saved model fields from disk. 
    850  
    851 There are two ways of exploiting this offline capacity. 
     863The 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. 
     864During the interpolation phase the SAO populates the model arrays by 
     865reading saved model fields from disk. The interpolation and the output phases use the same OBS code described in the preceding sections. 
     866 
     867There are two ways of exploiting the standalone capacity. 
    852868The first is to mimic the behaviour of the online system by supplying model fields at 
    853869regular intervals between the start and the end of the run. 
    854870This approach results in a single model counterpart per observation. 
    855 This kind of usage produces feedback files the same file format as the online obs oper. 
    856 The second is to take advantage of the offline setting in which 
    857 multiple model counterparts can be calculated per observation. 
     871This kind of usage produces feedback files the same file format as the online observation operator. 
     872The second is to take advantage of the ability to run offline by calculating 
     873multiple model counterparts for each observation. 
    858874In this case it is possible to consider all forecasts verifying at the same time. 
    859 By forecast, I mean any method which produces an estimate of physical reality which is not an observed value. 
    860 In the case of class 4 files this means forecasts, analyses, persisted analyses and 
    861 climatological values verifying at the same time. 
    862 Although the class 4 file format doesn't account for multiple ensemble members or 
    863 multiple experiments per observation, it is possible to include these components in the same or multiple files. 
    864  
    865 %-------------------------------------------------------------------------------------------------------- 
    866 % offline_oper.exe  
    867 %-------------------------------------------------------------------------------------------------------- 
    868  
    869 \subsection{Using the offline observation operator} 
    870  
     875By forecast, we mean any method which produces an estimate of physical reality which is not an observed value. 
     876 
     877% sao.exe 
     878 
     879%% ================================================================================================= 
     880\subsection{Using the standalone observation operator} 
     881 
     882%% ================================================================================================= 
    871883\subsubsection{Building} 
    872884 
    873 In addition to \emph{OPA\_SRC} the offline obs oper requires the inclusion of the \emph{OOO\_SRC} directory. 
    874 \emph{OOO\_SRC} contains a replacement \mdl{nemo} and \mdl{nemogcm} which 
     885In addition to \emph{OPA\_SRC} the SAO requires the inclusion of the \emph{SAO\_SRC} directory. 
     886\emph{SAO\_SRC} contains a replacement \mdl{nemo} and \mdl{nemogcm} which 
    875887overwrites the resultant \textbf{nemo.exe}. 
    876 This is the approach taken by \emph{SAS\_SRC} and \emph{OFF\_SRC}. 
    877  
    878 %-------------------------------------------------------------------------------------------------------- 
    879 % Running  
    880 %-------------------------------------------------------------------------------------------------------- 
     888Note this a similar approach to that taken by the standalone surface scheme \emph{SAS\_SRC} and the offline TOP model \emph{OFF\_SRC}. 
     889 
     890% Running 
     891%% ================================================================================================= 
    881892\subsubsection{Running} 
    882893 
    883 The simplest way to use the executable is to edit and append the \textbf{ooo.nml} namelist to 
    884 a full NEMO namelist and then to run the executable as if it were nemo.exe.  
    885  
    886 \subsubsection{Quick script} 
    887  
    888 A useful Python utility to control the namelist options can be found in \textbf{OBSTOOLS/OOO}. 
    889 The functions which locate model fields and observation files can be manually specified. 
    890 The package can be installed by appropriate use of the included setup.py script. 
    891  
    892 Documentation can be auto-generated by Sphinx by running \emph{make html} in the \textbf{doc} directory. 
    893  
    894 %-------------------------------------------------------------------------------------------------------- 
     894The simplest way to use the executable is to edit and append the \textbf{sao.nml} namelist to 
     895a full \NEMO\ namelist and then to run the executable as if it were nemo.exe. 
     896 
    895897% Configuration section 
    896 %-------------------------------------------------------------------------------------------------------- 
    897 \subsection{Configuring the offline observation operator} 
    898 The observation files and settings understood by \textbf{namobs} have been outlined in the online obs oper section. 
    899 In addition there are two further namelists wich control the operation of the offline obs oper. 
    900 \textbf{namooo} which controls the input model fields and \textbf{namcl4} which 
    901 controls the production of class 4 files.  
    902  
     898%% ================================================================================================= 
     899\subsection{Configuring the standalone observation operator} 
     900The observation files and settings understood by \nam{obs}{obs} have been outlined in the online observation operator section. 
     901In addition is a further namelist \nam{sao}{sao} which used to set the input model fields for the SAO 
     902 
     903%% ================================================================================================= 
    903904\subsubsection{Single field} 
    904905 
    905 In offline mode model arrays are populated at appropriate time steps via input files. 
    906 At present, \textbf{tsn} and \textbf{sshn} are populated by the default read routines.  
     906In the SAO the model arrays are populated at appropriate time steps via input files. 
     907At present, \textbf{tsn} and \textbf{sshn} are populated by the default read routines. 
    907908These routines will be expanded upon in future versions to allow the specification of any model variable. 
    908909As such, input files must be global versions of the model domain with 
    909910\textbf{votemper}, \textbf{vosaline} and optionally \textbf{sshn} present. 
    910911 
    911 For each field read there must be an entry in the \textbf{namooo} namelist specifying 
     912For each field read there must be an entry in the \nam{sao}{sao} namelist specifying 
    912913the name of the file to read and the index along the \emph{time\_counter}. 
    913914For example, to read the second time counter from a single file the namelist would be. 
     
    915916\begin{forlines} 
    916917!---------------------------------------------------------------------- 
    917 !       namooo Offline obs_oper namelist 
     918!       namsao Standalone obs_oper namelist 
    918919!---------------------------------------------------------------------- 
    919 !   ooo_files    specifies the files containing the model counterpart 
    920 !   nn_ooo_idx   specifies the time_counter index within the model file 
    921 &namooo 
    922    ooo_files = "foo.nc" 
    923    nn_ooo_idx = 2 
     920!   sao_files    specifies the files containing the model counterpart 
     921!   nn_sao_idx   specifies the time_counter index within the model file 
     922&namsao 
     923   sao_files = "foo.nc" 
     924   nn_sao_idx = 2 
    924925/ 
    925926\end{forlines} 
    926927 
     928%% ================================================================================================= 
    927929\subsubsection{Multiple fields per run} 
    928930 
    929 Model field iteration is controlled via \textbf{nn\_ooo\_freq} which 
     931Model field iteration is controlled via \textbf{nn\_sao\_freq} which 
    930932specifies the number of model steps at which the next field gets read. 
    931933For example, if 12 hourly fields are to be interpolated in a setup where 288 steps equals 24 hours. 
     
    933935\begin{forlines} 
    934936!---------------------------------------------------------------------- 
    935 !       namooo Offline obs_oper namelist 
     937!       namsao Standalone obs_oper namelist 
    936938!---------------------------------------------------------------------- 
    937 !   ooo_files    specifies the files containing the model counterpart 
    938 !   nn_ooo_idx   specifies the time_counter index within the model file 
    939 !   nn_ooo_freq  specifies number of time steps between read operations 
    940 &namooo 
    941    ooo_files = "foo.nc" "foo.nc" 
    942    nn_ooo_idx = 1 2 
    943    nn_ooo_freq = 144 
     939!   sao_files    specifies the files containing the model counterpart 
     940!   nn_sao_idx   specifies the time_counter index within the model file 
     941!   nn_sao_freq  specifies number of time steps between read operations 
     942&namsao 
     943   sao_files = "foo.nc" "foo.nc" 
     944   nn_sao_idx = 1 2 
     945   nn_sao_freq = 144 
    944946/ 
    945947\end{forlines} 
     
    952954%\end{framed} 
    953955 
    954 It is easy to see how a collection of fields taken fron a number of files at different indices can be combined at 
     956A collection of fields taken from a number of files at different indices can be combined at 
    955957a particular frequency in time to generate a pseudo model evolution. 
    956 As long as all that is needed is a single model counterpart at a regular interval then 
    957 namooo is all that needs to be edited. 
    958 However, a far more interesting approach can be taken in which multiple forecasts, analyses, persisted analyses and 
    959 climatologies are considered against the same set of observations. 
    960 For this a slightly more complicated approach is needed. 
    961 It is referred to as \emph{Class 4} since it is the fourth metric defined by the GODAE intercomparison project. 
    962  
    963 %-------------------------------------------------------------------------------------------------------- 
    964 % Class 4 file section 
    965 %-------------------------------------------------------------------------------------------------------- 
    966 \subsubsection{Multiple model counterparts per observation a.k.a Class 4} 
    967  
    968 A generalisation of feedback files to allow multiple model components per observation. 
    969 For a single observation, as well as previous forecasts verifying at the same time 
    970 there are also analyses, persisted analyses and climatologies.  
    971  
    972  
    973 The above namelist performs two basic functions. 
    974 It organises the fields given in \textbf{namooo} into groups so that observations can be matched up multiple times. 
    975 It also controls the metadata and the output variable of the class 4 file when a write routine is called. 
    976  
    977 %\begin{framed} 
    978 \textbf{Note: ln\_cl4} must be set to \forcode{.true.} in \textbf{namobs} to use class 4 outputs. 
    979 %\end{framed} 
    980  
    981 \subsubsection{Class 4 naming convention} 
    982  
    983 The standard class 4 file naming convention is as follows. 
    984  
    985 \noindent 
    986 \linebreak 
    987 \textbf{\$\{prefix\}\_\$\{yyyymmdd\}\_\$\{sys\}\_\$\{cfg\}\_\$\{vn\}\_\$\{kind\}\_\$\{nproc\}}.nc 
    988  
    989 \noindent 
    990 \linebreak 
    991 Much of the namelist is devoted to specifying this convention. 
    992 The following namelist settings control the elements of the output file names. 
    993 Each should be specified as a single string of character data. 
    994  
    995 \begin{description} 
    996 \item[cl4\_prefix] 
    997   Prefix for class 4 files \eg class4 
    998 \item[cl4\_date] 
    999   YYYYMMDD validity date 
    1000 \item[cl4\_sys] 
    1001   The name of the class 4 model system \eg FOAM 
    1002 \item[cl4\_cfg] 
    1003   The name of the class 4 model configuration \eg orca025 
    1004 \item[cl4\_vn] 
    1005   The name of the class 4 model version \eg 12.0 
    1006 \end{description} 
    1007  
    1008 \noindent 
    1009 The kind is specified by the observation type internally to the obs oper. 
    1010 The processor number is specified internally in NEMO.  
    1011  
    1012 \subsubsection{Class 4 file global attributes} 
    1013  
    1014 Global attributes necessary to fulfill the class 4 file definition. 
    1015 These are also useful pieces of information when collaborating with external partners. 
    1016  
    1017 \begin{description} 
    1018 \item[cl4\_contact] 
    1019   Contact email for class 4 files. 
    1020 \item[cl4\_inst] 
    1021   The name of the producers institution. 
    1022 \item[cl4\_cfg] 
    1023   The name of the class 4 model configuration \eg orca025 
    1024 \item[cl4\_vn] 
    1025   The name of the class 4 model version \eg 12.0 
    1026 \end{description} 
    1027  
    1028 \noindent 
    1029 The obs\_type, creation date and validity time are specified internally to the obs oper. 
    1030  
    1031 \subsubsection{Class 4 model counterpart configuration} 
    1032  
    1033 As seen previously it is possible to perform a single sweep of the obs oper and 
    1034 specify a collection of model fields equally spaced along that sweep. 
    1035 In the class 4 case the single sweep is replaced with multiple sweeps and 
    1036 a certain ammount of book keeping is needed to ensure each model counterpart makes its way to 
    1037 the correct piece of memory in the output files. 
    1038  
    1039 \noindent 
    1040 \linebreak 
    1041 In terms of book keeping, the offline obs oper needs to know how many full sweeps need to be performed. 
    1042 This is specified via the \textbf{cl4\_match\_len} variable and 
    1043 is the total number of model counterparts per observation. 
    1044 For example, a 3 forecasts plus 3 persistence fields plus an analysis field would be 7 counterparts per observation. 
    1045  
    1046 \begin{forlines} 
    1047    cl4_match_len = 7 
    1048 \end{forlines} 
    1049  
    1050 Then to correctly allocate a class 4 file the forecast axis must be defined. 
    1051 This is controlled via \textbf{cl4\_fcst\_len}, which in out above example would be 3. 
    1052  
    1053 \begin{forlines} 
    1054    cl4_fcst_len = 3 
    1055 \end{forlines} 
    1056  
    1057 Then for each model field it is necessary to designate what class 4 variable and index along 
    1058 the forecast dimension the model counterpart should be stored in the output file. 
    1059 As well as a value for that lead time in hours, this will be useful when interpreting the data afterwards.  
    1060  
    1061 \begin{forlines} 
    1062    cl4_vars = "forecast" "forecast" "forecast" "persistence" "persistence" 
    1063               "persistence" "best_estimate" 
    1064    cl4_fcst_idx = 1 2 3 1 2 3 1 
    1065    cl4_leadtime = 12 36 60  
    1066 \end{forlines} 
    1067  
    1068 In terms of files and indices of fields inside each file the class 4 approach makes use of 
    1069 the \textbf{namooo} namelist. 
    1070 If our fields are in separate files with a single field per file our example inputs will be specified. 
    1071  
    1072 \begin{forlines} 
    1073    ooo_files = "F.1.nc" "F.2.nc" "F.3.nc" "P.1.nc" "P.2.nc" "P.3.nc" "A.1.nc" 
    1074    nn_ooo_idx = 1 1 1 1 1 1 1 
    1075 \end{forlines} 
    1076  
    1077 When we combine all of the naming conventions, global attributes and i/o instructions the class 4 namelist becomes. 
    1078  
    1079 \begin{forlines} 
    1080 !---------------------------------------------------------------------- 
    1081 !       namooo Offline obs_oper namelist 
    1082 !---------------------------------------------------------------------- 
    1083 !   ooo_files    specifies the files containing the model counterpart 
    1084 !   nn_ooo_idx   specifies the time_counter index within the model file 
    1085 !   nn_ooo_freq  specifies number of time steps between read operations 
    1086 &namooo 
    1087    ooo_files = "F.1.nc" "F.2.nc" "F.3.nc" "P.1.nc" "P.2.nc" "P.3.nc" "A.1.nc" 
    1088    nn_ooo_idx = 1 1 1 1 1 1 1 
    1089 / 
    1090 !---------------------------------------------------------------------- 
    1091 !       namcl4 Offline obs_oper class 4 namelist 
    1092 !---------------------------------------------------------------------- 
    1093 ! 
    1094 !  Naming convention 
    1095 !  ----------------- 
    1096 !  cl4_prefix    specifies the output file prefix 
    1097 !  cl4_date      specifies the output file validity date 
    1098 !  cl4_sys       specifies the model counterpart system 
    1099 !  cl4_cfg       specifies the model counterpart configuration 
    1100 !  cl4_vn        specifies the model counterpart version 
    1101 !  cl4_inst      specifies the model counterpart institute 
    1102 !  cl4_contact   specifies the file producers contact details 
    1103 ! 
    1104 !  I/O specification 
    1105 !  ----------------- 
    1106 !  cl4_vars      specifies the names of the output file netcdf variable 
    1107 !  cl4_fcst_idx  specifies output file forecast index 
    1108 !  cl4_fcst_len  specifies forecast axis length 
    1109 !  cl4_match_len specifies number of unique matches per observation 
    1110 !  cl4_leadtime  specifies the forecast axis lead time  
    1111 ! 
    1112 &namcl4 
    1113    cl4_match_len = 7 
    1114    cl4_fcst_len = 3 
    1115    cl4_fcst_idx = 1 2 3 1 2 3 1 
    1116    cl4_vars = "forecast" "forecast" "forecast" "persistence" "persistence" 
    1117               "persistence" "best_estimate" 
    1118    cl4_leadtime = 12 36 60 
    1119    cl4_prefix = "class4" 
    1120    cl4_date = "20130101" 
    1121    cl4_vn = "12.0" 
    1122    cl4_sys = "FOAM" 
    1123    cl4_cfg = "AMM7" 
    1124    cl4_contact = "example@example.com" 
    1125    cl4_inst = "UK Met Office" 
    1126 / 
    1127 \end{forlines} 
    1128  
    1129 \subsubsection{Climatology interpolation} 
    1130  
    1131 The climatological counterpart is generated at the start of the run by 
    1132 restarting the model from climatology through appropriate use of \textbf{namtsd}. 
    1133 To override the offline observation operator read routine and to take advantage of the restart settings, 
    1134 specify the first entry in \textbf{cl4\_vars} as "climatology". 
    1135 This will then pipe the restart from climatology into the output class 4 file. 
    1136 As in every other class 4 matchup the input file, input index and output index must be specified. 
    1137 These can be replaced with dummy data since they are not used but 
    1138 they must be present to cycle through the matchups correctly.  
    1139  
    1140 \subsection{Advanced usage} 
    1141  
    1142 In certain cases it may be desirable to include both multiple model fields per observation window with 
    1143 multiple match ups per observation. 
    1144 This can be achieved by specifying \textbf{nn\_ooo\_freq} as well as the class 4 settings. 
    1145 Care must be taken in generating the ooo\_files list such that the files are arranged into 
    1146 consecutive blocks of single match ups. 
    1147 For example, 2 forecast fields of 12 hourly data would result in 4 separate read operations but 
    1148 only 2 write operations, 1 per forecast. 
    1149  
    1150 \begin{forlines} 
    1151    ooo_files = "F1.nc" "F1.nc" "F2.nc" "F2.nc" 
    1152 ... 
    1153    cl4_fcst_idx = 1 2 
    1154 \end{forlines} 
    1155  
    1156 The above notation reveals the internal split between match up iterators and file iterators. 
    1157 This technique has not been used before so experimentation is needed before results can be trusted. 
    1158  
    1159 \newpage 
    1160  
     958If all that is needed is a single model counterpart at a regular interval then 
     959the standard SAO is all that is required. 
     960However, just to note, it is possible to extend this approach by comparing multiple forecasts, analyses, persisted analyses and 
     961climatologies with the same set of observations. 
     962This 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. 
     963 
     964%% ================================================================================================= 
    1161965\section{Observation utilities} 
    1162966\label{sec:OBS_obsutils} 
    1163967 
    1164 Some tools for viewing and processing of observation and feedback files are provided in 
    1165 the NEMO repository for convenience. 
    1166 These include OBSTOOLS which are a collection of \fortran programs which are helpful to deal with feedback files. 
     968For convenience some tools for viewing and processing of observation and feedback files are provided in 
     969the \NEMO\ repository. 
     970These tools include OBSTOOLS which are a collection of \fortran\ programs which are helpful to deal with feedback files. 
    1167971They do such tasks as observation file conversion, printing of file contents, 
    1168972some basic statistical analysis of feedback files. 
    1169 The other tool is an IDL program called dataplot which uses a graphical interface to 
     973The other main tool is an IDL program called dataplot which uses a graphical interface to 
    1170974visualise observations and feedback files. 
    1171975OBSTOOLS and dataplot are described in more detail below. 
    1172976 
     977%% ================================================================================================= 
    1173978\subsection{Obstools} 
    1174979 
    1175 A series of \fortran utilities is provided with NEMO called OBSTOOLS. 
    1176 This are helpful in handling observation files and the feedback file output from the NEMO observation operator. 
    1177 The utilities are as follows 
    1178  
    1179 \subsubsection{c4comb} 
    1180  
    1181 The program c4comb combines multiple class 4 files produced by individual processors in 
    1182 an MPI run of NEMO offline obs\_oper into a single class 4 file. 
    1183 The program is called in the following way: 
    1184  
    1185  
    1186 \footnotesize 
    1187 \begin{cmds} 
    1188 c4comb.exe outputfile inputfile1 inputfile2 ... 
    1189 \end{cmds} 
    1190  
     980A series of \fortran\ utilities is provided with \NEMO\ called OBSTOOLS. 
     981This are helpful in handling observation files and the feedback file output from the observation operator. A brief description of some of the utilities follows 
     982 
     983%% ================================================================================================= 
    1191984\subsubsection{corio2fb} 
    1192985 
    1193986The program corio2fb converts profile observation files from the Coriolis format to the standard feedback format. 
    1194 The program is called in the following way: 
    1195  
    1196 \footnotesize 
     987It is called in the following way: 
     988 
    1197989\begin{cmds} 
    1198990corio2fb.exe outputfile inputfile1 inputfile2 ... 
    1199991\end{cmds} 
    1200992 
     993%% ================================================================================================= 
    1201994\subsubsection{enact2fb} 
    1202995 
    1203996The program enact2fb converts profile observation files from the ENACT format to the standard feedback format. 
    1204 The program is called in the following way: 
    1205  
    1206 \footnotesize 
     997It is called in the following way: 
     998 
    1207999\begin{cmds} 
    12081000enact2fb.exe outputfile inputfile1 inputfile2 ... 
    12091001\end{cmds} 
    12101002 
     1003%% ================================================================================================= 
    12111004\subsubsection{fbcomb} 
    12121005 
    12131006The program fbcomb combines multiple feedback files produced by individual processors in 
    1214 an MPI run of NEMO into a single feedback file. 
    1215 The program is called in the following way: 
    1216  
    1217 \footnotesize 
     1007an MPI run of \NEMO\ into a single feedback file. 
     1008It is called in the following way: 
     1009 
    12181010\begin{cmds} 
    12191011fbcomb.exe outputfile inputfile1 inputfile2 ... 
    12201012\end{cmds} 
    12211013 
     1014%% ================================================================================================= 
    12221015\subsubsection{fbmatchup} 
    12231016 
    12241017The program fbmatchup will match observations from two feedback files. 
    1225 The program is called in the following way: 
    1226  
    1227 \footnotesize 
     1018It is called in the following way: 
     1019 
    12281020\begin{cmds} 
    12291021fbmatchup.exe outputfile inputfile1 varname1 inputfile2 varname2 ... 
    12301022\end{cmds} 
    12311023 
     1024%% ================================================================================================= 
    12321025\subsubsection{fbprint} 
    12331026 
    12341027The program fbprint will print the contents of a feedback file or files to standard output. 
    12351028Selected information can be output using optional arguments. 
    1236 The program is called in the following way: 
    1237  
    1238 \footnotesize 
     1029It is called in the following way: 
     1030 
    12391031\begin{cmds} 
    12401032fbprint.exe [options] inputfile 
     
    12461038     -B            Select observations based on QC flags 
    12471039     -u            unsorted 
    1248      -s ID         select station ID   
     1040     -s ID         select station ID 
    12491041     -t TYPE       select observation type 
    1250      -v NUM1-NUM2  select variable range to print by number  
     1042     -v NUM1-NUM2  select variable range to print by number 
    12511043                      (default all) 
    1252      -a NUM1-NUM2  select additional variable range to print by number  
     1044     -a NUM1-NUM2  select additional variable range to print by number 
    12531045                      (default all) 
    1254      -e NUM1-NUM2  select extra variable range to print by number  
     1046     -e NUM1-NUM2  select extra variable range to print by number 
    12551047                      (default all) 
    12561048     -d            output date range 
     
    12591051\end{cmds} 
    12601052 
     1053%% ================================================================================================= 
    12611054\subsubsection{fbsel} 
    12621055 
    12631056The program fbsel will select or subsample observations. 
    1264 The program is called in the following way: 
    1265  
    1266 \footnotesize 
     1057It is called in the following way: 
     1058 
    12671059\begin{cmds} 
    12681060fbsel.exe <input filename> <output filename> 
    12691061\end{cmds} 
    12701062 
     1063%% ================================================================================================= 
    12711064\subsubsection{fbstat} 
    12721065 
    12731066The program fbstat will output summary statistics in different global areas into a number of files. 
    1274 The program is called in the following way: 
    1275  
    1276 \footnotesize 
     1067It is called in the following way: 
     1068 
    12771069\begin{cmds} 
    12781070fbstat.exe [-nmlev] <filenames> 
    12791071\end{cmds} 
    12801072 
     1073%% ================================================================================================= 
    12811074\subsubsection{fbthin} 
    12821075 
    12831076The program fbthin will thin the data to 1 degree resolution. 
    12841077The code could easily be modified to thin to a different resolution. 
    1285 The program is called in the following way: 
    1286  
    1287 \footnotesize 
     1078It is called in the following way: 
     1079 
    12881080\begin{cmds} 
    12891081fbthin.exe inputfile outputfile 
    12901082\end{cmds} 
    12911083 
     1084%% ================================================================================================= 
    12921085\subsubsection{sla2fb} 
    12931086 
    12941087The program sla2fb will convert an AVISO SLA format file to feedback format. 
    1295 The program is called in the following way: 
    1296  
    1297 \footnotesize 
     1088It is called in the following way: 
     1089 
    12981090\begin{cmds} 
    12991091sla2fb.exe [-s type] outputfile inputfile1 inputfile2 ... 
     
    13031095\end{cmds} 
    13041096 
     1097%% ================================================================================================= 
    13051098\subsubsection{vel2fb} 
    13061099 
    13071100The program vel2fb will convert TAO/PIRATA/RAMA currents files to feedback format. 
    1308 The program is called in the following way: 
    1309  
    1310 \footnotesize 
     1101It is called in the following way: 
     1102 
    13111103\begin{cmds} 
    13121104vel2fb.exe outputfile inputfile1 inputfile2 ... 
    13131105\end{cmds} 
    13141106 
     1107%% ================================================================================================= 
    13151108\subsection{Building the obstools} 
    13161109 
    13171110To build the obstools use in the tools directory use ./maketools -n OBSTOOLS -m [ARCH]. 
    13181111 
     1112%% ================================================================================================= 
    13191113\subsection{Dataplot} 
    13201114 
    13211115An IDL program called dataplot is included which uses a graphical interface to 
    1322 visualise observations and feedback files. 
     1116visualise 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. 
     1117 
    13231118It is possible to zoom in, plot individual profiles and calculate some basic statistics. 
    13241119To plot some data run IDL and then: 
    1325 \footnotesize 
     1120 
    13261121\begin{minted}{idl} 
    13271122IDL> dataplot, "filename" 
     
    13311126for example multiple feedback files from different processors or from different days, 
    13321127the easiest method is to use the spawn command to generate a list of files which can then be passed to dataplot. 
    1333 \footnotesize 
     1128 
    13341129\begin{minted}{idl} 
    13351130IDL> spawn, 'ls profb*.nc', files 
     
    13371132\end{minted} 
    13381133 
    1339 \autoref{fig:obsdataplotmain} shows the main window which is launched when dataplot starts. 
     1134\autoref{fig:OBS_dataplotmain} shows the main window which is launched when dataplot starts. 
    13401135This is split into three parts. 
    13411136At the top there is a menu bar which contains a variety of drop down menus. 
     
    13501145The plotting colour range can be changed by clicking on the colour bar. 
    13511146The title of the plot gives some basic information about the date range and depth range shown, 
    1352 the extreme values, and the mean and rms values. 
     1147the extreme values, and the mean and RMS values. 
    13531148It is possible to zoom in using a drag-box. 
    13541149You may also zoom in or out using the mouse wheel. 
     
    13621157observation minus background value. 
    13631158The next group of radio buttons selects the map projection. 
    1364 This can either be regular latitude longitude grid, or north or south polar stereographic. 
     1159This can either be regular longitude latitude grid, or north or south polar stereographic. 
    13651160The next group of radio buttons will plot bad observations, switch to salinity and 
    13661161plot density for profile observations. 
    13671162The rightmost group of buttons will print the plot window as a postscript, save it as png, or exit from dataplot. 
    13681163 
    1369 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    13701164\begin{figure} 
    1371   \begin{center} 
    1372     % \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_OBS_dataplot_main} 
    1373     \includegraphics[width=9cm,angle=-90.]{Fig_OBS_dataplot_main} 
    1374     \caption{ 
    1375       \protect\label{fig:obsdataplotmain} 
    1376       Main window of dataplot. 
    1377     } 
    1378   \end{center} 
     1165  \centering 
     1166  \includegraphics[width=0.66\textwidth]{OBS_dataplot_main} 
     1167  \caption{Main window of dataplot} 
     1168  \label{fig:OBS_dataplotmain} 
    13791169\end{figure} 
    1380 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    13811170 
    13821171If a profile point is clicked with the mouse button a plot of the observation and background values as 
    1383 a function of depth (\autoref{fig:obsdataplotprofile}). 
    1384  
    1385 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     1172a function of depth (\autoref{fig:OBS_dataplotprofile}). 
     1173 
    13861174\begin{figure} 
    1387   \begin{center} 
    1388     % \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_OBS_dataplot_prof} 
    1389     \includegraphics[width=7cm,angle=-90.]{Fig_OBS_dataplot_prof} 
    1390     \caption{ 
    1391       \protect\label{fig:obsdataplotprofile} 
    1392       Profile plot from dataplot produced by right clicking on a point in the main window. 
    1393     } 
    1394   \end{center} 
     1175  \centering 
     1176  \includegraphics[width=0.66\textwidth]{OBS_dataplot_prof} 
     1177  \caption[Profile plot from dataplot]{ 
     1178    Profile plot from dataplot produced by right clicking on a point in the main window} 
     1179  \label{fig:OBS_dataplotprofile} 
    13951180\end{figure} 
    1396 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1397  
    1398 \biblio 
    1399  
    1400 \pindex 
     1181 
     1182\subinc{\input{../../global/epilogue}} 
    14011183 
    14021184\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_SBC.tex

    r10614 r11831  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter —— Surface Boundary Condition (SBC, ISF, ICB)  
    6 % ================================================================ 
    7 \chapter{Surface Boundary Condition (SBC, ISF, ICB) } 
     4 
     5\chapter{Surface Boundary Condition (SBC, SAS, ISF, ICB)} 
    86\label{chap:SBC} 
    9 \minitoc 
    10  
    11 \newpage 
    12  
    13 %---------------------------------------namsbc-------------------------------------------------- 
    14  
    15 \nlst{namsbc} 
    16 %-------------------------------------------------------------------------------------------------------------- 
    17  
    18 The ocean needs six fields as surface boundary condition: 
     7 
     8\thispagestyle{plain} 
     9 
     10\chaptertoc 
     11 
     12\paragraph{Changes record} ~\\ 
     13 
     14{\footnotesize 
     15  \begin{tabularx}{\textwidth}{l||X|X} 
     16    Release & Author(s) & Modifications \\ 
     17    \hline 
     18    {\em   4.0} & {\em ...} & {\em ...} \\ 
     19    {\em   3.6} & {\em ...} & {\em ...} \\ 
     20    {\em   3.4} & {\em ...} & {\em ...} \\ 
     21    {\em <=3.4} & {\em ...} & {\em ...} 
     22  \end{tabularx} 
     23} 
     24 
     25\clearpage 
     26 
     27\begin{listing} 
     28  \nlst{namsbc} 
     29  \caption{\forcode{&namsbc}} 
     30  \label{lst:namsbc} 
     31\end{listing} 
     32 
     33The ocean needs seven fields as surface boundary condition: 
     34 
    1935\begin{itemize} 
    20 \item 
    21   the two components of the surface ocean stress $\left( {\tau_u \;,\;\tau_v} \right)$ 
    22 \item 
    23   the incoming solar and non solar heat fluxes $\left( {Q_{ns} \;,\;Q_{sr} } \right)$ 
    24 \item 
    25   the surface freshwater budget $\left( {\textit{emp}} \right)$ 
    26 \item 
    27   the surface salt flux associated with freezing/melting of seawater $\left( {\textit{sfx}} \right)$ 
     36\item the two components of the surface ocean stress $\left( {\tau_u \;,\;\tau_v} \right)$ 
     37\item the incoming solar and non solar heat fluxes $\left( {Q_{ns} \;,\;Q_{sr} } \right)$ 
     38\item the surface freshwater budget $\left( {\textit{emp}} \right)$ 
     39\item the surface salt flux associated with freezing/melting of seawater $\left( {\textit{sfx}} \right)$ 
     40\item the atmospheric pressure at the ocean surface $\left( p_a \right)$ 
    2841\end{itemize} 
    29 plus an optional field: 
     42 
     43Four different ways are available to provide the seven fields to the ocean. They are controlled by 
     44namelist \nam{sbc}{sbc} variables: 
     45 
    3046\begin{itemize} 
    31    \item the atmospheric pressure at the ocean surface $\left( p_a \right)$ 
     47\item a bulk formulation (\np[=.true.]{ln_blk}{ln\_blk} with four possible bulk algorithms), 
     48\item a flux formulation (\np[=.true.]{ln_flx}{ln\_flx}), 
     49\item a coupled or mixed forced/coupled formulation (exchanges with a atmospheric model via the OASIS coupler), 
     50(\np{ln_cpl}{ln\_cpl} or \np[=.true.]{ln_mixcpl}{ln\_mixcpl}), 
     51\item a user defined formulation (\np[=.true.]{ln_usr}{ln\_usr}). 
    3252\end{itemize} 
    3353 
    34 Four different ways to provide the first six fields to the ocean are available which are controlled by 
    35 namelist \ngn{namsbc} variables: 
    36 an analytical formulation (\np{ln\_ana}\forcode{ = .true.}), 
    37 a flux formulation (\np{ln\_flx}\forcode{ = .true.}), 
    38 a bulk formulae formulation (CORE (\np{ln\_blk\_core}\forcode{ = .true.}), 
    39 CLIO (\np{ln\_blk\_clio}\forcode{ = .true.}) bulk formulae) and 
    40 a coupled or mixed forced/coupled formulation (exchanges with a atmospheric model via the OASIS coupler) 
    41 (\np{ln\_cpl} or \np{ln\_mixcpl}\forcode{ = .true.}).  
    42 When used (\ie \np{ln\_apr\_dyn}\forcode{ = .true.}), 
    43 the atmospheric pressure forces both ocean and ice dynamics. 
    44  
    45 The frequency at which the forcing fields have to be updated is given by the \np{nn\_fsbc} namelist parameter. 
    46 When the fields are supplied from data files (flux and bulk formulations), 
    47 the input fields need not be supplied on the model grid. 
    48 Instead a file of coordinates and weights can be supplied which maps the data from the supplied grid to 
     54The frequency at which the forcing fields have to be updated is given by the \np{nn_fsbc}{nn\_fsbc} namelist parameter. 
     55 
     56When the fields are supplied from data files (bulk, flux and mixed formulations), 
     57the input fields do not need to be supplied on the model grid. 
     58Instead, a file of coordinates and weights can be supplied to map the data from the input fields grid to 
    4959the model points (so called "Interpolation on the Fly", see \autoref{subsec:SBC_iof}). 
    50 If the Interpolation on the Fly option is used, input data belonging to land points (in the native grid), 
    51 can be masked to avoid spurious results in proximity of the coasts as 
     60If the "Interpolation on the Fly" option is used, input data belonging to land points (in the native grid) 
     61should be masked or filled to avoid spurious results in proximity of the coasts, as 
    5262large sea-land gradients characterize most of the atmospheric variables. 
    5363 
    5464In addition, the resulting fields can be further modified using several namelist options. 
    55 These options control  
     65These options control: 
     66 
    5667\begin{itemize} 
    57 \item 
    58   the rotation of vector components supplied relative to an east-north coordinate system onto 
    59   the local grid directions in the model; 
    60 \item 
    61   the addition of a surface restoring term to observed SST and/or SSS (\np{ln\_ssr}\forcode{ = .true.}); 
    62 \item 
    63   the modification of fluxes below ice-covered areas (using observed ice-cover or a sea-ice model) 
    64   (\np{nn\_ice}\forcode{ = 0..3}); 
    65 \item 
    66   the addition of river runoffs as surface freshwater fluxes or lateral inflow (\np{ln\_rnf}\forcode{ = .true.}); 
    67 \item 
    68   the addition of isf melting as lateral inflow (parameterisation) or 
    69   as fluxes applied at the land-ice ocean interface (\np{ln\_isf}) ;  
    70 \item 
    71   the addition of a freshwater flux adjustment in order to avoid a mean sea-level drift 
    72   (\np{nn\_fwb}\forcode{ = 0..2}); 
    73 \item 
    74   the transformation of the solar radiation (if provided as daily mean) into a diurnal cycle 
    75   (\np{ln\_dm2dc}\forcode{ = .true.}); 
    76 \item 
    77   a neutral drag coefficient can be read from an external wave model (\np{ln\_cdgw}\forcode{ = .true.}); 
    78 \item 
    79   the Stokes drift rom an external wave model can be accounted (\np{ln\_sdw}\forcode{ = .true.});  
    80 \item 
    81   the Stokes-Coriolis term can be included (\np{ln\_stcor}\forcode{ = .true.}); 
    82 \item 
    83   the surface stress felt by the ocean can be modified by surface waves (\np{ln\_tauwoc}\forcode{ = .true.}). 
     68\item the rotation of vector components supplied relative to an east-north coordinate system onto 
     69  the local grid directions in the model, 
     70\item the use of a land/sea mask for input fields (\np[=.true.]{nn_lsm}{nn\_lsm}), 
     71\item the addition of a surface restoring term to observed SST and/or SSS (\np[=.true.]{ln_ssr}{ln\_ssr}), 
     72\item the modification of fluxes below ice-covered areas (using climatological ice-cover or a sea-ice model) 
     73  (\np[=0..3]{nn_ice}{nn\_ice}), 
     74\item the addition of river runoffs as surface freshwater fluxes or lateral inflow (\np[=.true.]{ln_rnf}{ln\_rnf}), 
     75\item the addition of ice-shelf melting as lateral inflow (parameterisation) or 
     76  as fluxes applied at the land-ice ocean interface (\np[=.true.]{ln_isf}{ln\_isf}), 
     77\item the addition of a freshwater flux adjustment in order to avoid a mean sea-level drift 
     78  (\np[=0..2]{nn_fwb}{nn\_fwb}), 
     79\item the transformation of the solar radiation (if provided as daily mean) into an analytical diurnal cycle 
     80  (\np[=.true.]{ln_dm2dc}{ln\_dm2dc}), 
     81\item the activation of wave effects from an external wave model  (\np[=.true.]{ln_wave}{ln\_wave}), 
     82\item a neutral drag coefficient is read from an external wave model (\np[=.true.]{ln_cdgw}{ln\_cdgw}), 
     83\item the Stokes drift from an external wave model is accounted for (\np[=.true.]{ln_sdw}{ln\_sdw}), 
     84\item the choice of the Stokes drift profile parameterization (\np[=0..2]{nn_sdrift}{nn\_sdrift}), 
     85\item the surface stress given to the ocean is modified by surface waves (\np[=.true.]{ln_tauwoc}{ln\_tauwoc}), 
     86\item the surface stress given to the ocean is read from an external wave model (\np[=.true.]{ln_tauw}{ln\_tauw}), 
     87\item the Stokes-Coriolis term is included (\np[=.true.]{ln_stcor}{ln\_stcor}), 
     88\item the light penetration in the ocean (\np[=.true.]{ln_traqsr}{ln\_traqsr} with namelist \nam{tra_qsr}{tra\_qsr}), 
     89\item the atmospheric surface pressure gradient effect on ocean and ice dynamics (\np[=.true.]{ln_apr_dyn}{ln\_apr\_dyn} with namelist \nam{sbc_apr}{sbc\_apr}), 
     90\item the effect of sea-ice pressure on the ocean (\np[=.true.]{ln_ice_embd}{ln\_ice\_embd}). 
    8491\end{itemize} 
    8592 
    86 In this chapter, we first discuss where the surface boundary condition appears in the model equations. 
    87 Then we present the five ways of providing the surface boundary condition,  
    88 followed by the description of the atmospheric pressure and the river runoff.  
    89 Next the scheme for interpolation on the fly is described. 
     93In this chapter, we first discuss where the surface boundary conditions appear in the model equations. 
     94Then we present the three ways of providing the surface boundary conditions, 
     95followed by the description of the atmospheric pressure and the river runoff. 
     96Next, the scheme for interpolation on the fly is described. 
    9097Finally, the different options that further modify the fluxes applied to the ocean are discussed. 
    91 One of these is modification by icebergs (see \autoref{sec:ICB_icebergs}), 
     98One of these is modification by icebergs (see \autoref{sec:SBC_ICB_icebergs}), 
    9299which act as drifting sources of fresh water. 
    93 Another example of modification is that due to the ice shelf melting/freezing (see \autoref{sec:SBC_isf}),  
     100Another example of modification is that due to the ice shelf melting/freezing (see \autoref{sec:SBC_isf}), 
    94101which provides additional sources of fresh water. 
    95102 
    96  
    97 % ================================================================ 
    98 % Surface boundary condition for the ocean 
    99 % ================================================================ 
     103%% ================================================================================================= 
    100104\section{Surface boundary condition for the ocean} 
    101 \label{sec:SBC_general} 
     105\label{sec:SBC_ocean} 
    102106 
    103107The surface ocean stress is the stress exerted by the wind and the sea-ice on the ocean. 
    104108It is applied in \mdl{dynzdf} module as a surface boundary condition of the computation of 
    105 the momentum vertical mixing trend (see \autoref{eq:dynzdf_sbc} in \autoref{sec:DYN_zdf}). 
     109the momentum vertical mixing trend (see \autoref{eq:DYN_zdf_sbc} in \autoref{sec:DYN_zdf}). 
    106110As such, it has to be provided as a 2D vector interpolated onto the horizontal velocity ocean mesh, 
    107 \ie resolved onto the model (\textbf{i},\textbf{j}) direction at $u$- and $v$-points. 
     111\ie\ resolved onto the model (\textbf{i},\textbf{j}) direction at $u$- and $v$-points. 
    108112 
    109113The surface heat flux is decomposed into two parts, a non solar and a solar heat flux, 
    110114$Q_{ns}$ and $Q_{sr}$, respectively. 
    111115The former is the non penetrative part of the heat flux 
    112 (\ie the sum of sensible, latent and long wave heat fluxes plus 
    113 the heat content of the mass exchange with the atmosphere and sea-ice). 
     116(\ie\ the sum of sensible, latent and long wave heat fluxes plus 
     117the heat content of the mass exchange between the ocean and sea-ice). 
    114118It is applied in \mdl{trasbc} module as a surface boundary condition trend of 
    115119the first level temperature time evolution equation 
    116 (see \autoref{eq:tra_sbc} and \autoref{eq:tra_sbc_lin} in \autoref{subsec:TRA_sbc}).  
     120(see \autoref{eq:TRA_sbc} and \autoref{eq:TRA_sbc_lin} in \autoref{subsec:TRA_sbc}). 
    117121The latter is the penetrative part of the heat flux. 
    118 It is applied as a 3D trends of the temperature equation (\mdl{traqsr} module) when 
    119 \np{ln\_traqsr}\forcode{ = .true.}. 
     122It is applied as a 3D trend of the temperature equation (\mdl{traqsr} module) when 
     123\np[=.true.]{ln_traqsr}{ln\_traqsr}. 
    120124The way the light penetrates inside the water column is generally a sum of decreasing exponentials 
    121 (see \autoref{subsec:TRA_qsr}).  
     125(see \autoref{subsec:TRA_qsr}). 
    122126 
    123127The surface freshwater budget is provided by the \textit{emp} field. 
    124128It represents the mass flux exchanged with the atmosphere (evaporation minus precipitation) and 
    125129possibly with the sea-ice and ice shelves (freezing minus melting of ice). 
    126 It affects both the ocean in two different ways: 
    127 $(i)$  it changes the volume of the ocean and therefore appears in the sea surface height equation as 
    128 a volume flux, and  
     130It affects the ocean in two different ways: 
     131$(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 
     132a volume flux, and 
    129133$(ii)$ it changes the surface temperature and salinity through the heat and salt contents of 
    130 the mass exchanged with the atmosphere, the sea-ice and the ice shelves.  
    131  
     134the mass exchanged with atmosphere, sea-ice and ice shelves. 
    132135 
    133136%\colorbox{yellow}{Miss: } 
    134 % 
    135 %A extensive description of all namsbc namelist (parameter that have to be  
     137%A extensive description of all namsbc namelist (parameter that have to be 
    136138%created!) 
    137 % 
    138 %Especially the \np{nn\_fsbc}, the \mdl{sbc\_oce} module (fluxes + mean sst sss ssu  
    139 %ssv) \ie information required by flux computation or sea-ice 
    140 % 
    141 %\mdl{sbc\_oce} containt the definition in memory of the 7 fields (6+runoff), add  
     139%Especially the \np{nn_fsbc}{nn\_fsbc}, the \mdl{sbc\_oce} module (fluxes + mean sst sss ssu 
     140%ssv) \ie\ information required by flux computation or sea-ice 
     141%\mdl{sbc\_oce} containt the definition in memory of the 7 fields (6+runoff), add 
    142142%a word on runoff: included in surface bc or add as lateral obc{\ldots}. 
    143 % 
    144143%Sbcmod manage the ``providing'' (fourniture) to the ocean the 7 fields 
    145 % 
    146 %Fluxes update only each nf{\_}sbc time step (namsbc) explain relation  
    147 %between nf{\_}sbc and nf{\_}ice, do we define nf{\_}blk??? ? only one  
    148 %nf{\_}sbc 
    149 % 
     144%Fluxes update only each nf\_sbc time step (namsbc) explain relation 
     145%between nf\_sbc and nf\_ice, do we define nf\_blk??? ? only one 
     146%nf\_sbc 
    150147%Explain here all the namlist namsbc variable{\ldots}. 
    151 %  
    152148% explain : use or not of surface currents 
    153 % 
    154149%\colorbox{yellow}{End Miss } 
    155150 
    156151The ocean model provides, at each time step, to the surface module (\mdl{sbcmod}) 
    157 the surface currents, temperature and salinity.   
    158 These variables are averaged over \np{nn\_fsbc} time-step (\autoref{tab:ssm}), and 
    159 it is these averaged fields which are used to computes the surface fluxes at a frequency of \np{nn\_fsbc} time-step. 
    160  
    161  
    162 %-------------------------------------------------TABLE--------------------------------------------------- 
     152the surface currents, temperature and salinity. 
     153These variables are averaged over \np{nn_fsbc}{nn\_fsbc} time-step (\autoref{tab:SBC_ssm}), and 
     154these averaged fields are used to compute the surface fluxes at the frequency of \np{nn_fsbc}{nn\_fsbc} time-steps. 
     155 
    163156\begin{table}[tb] 
    164   \begin{center} 
    165     \begin{tabular}{|l|l|l|l|} 
    166       \hline 
    167       Variable description             & Model variable  & Units  & point \\  \hline 
    168       i-component of the surface current  & ssu\_m & $m.s^{-1}$   & U \\   \hline 
    169       j-component of the surface current  & ssv\_m & $m.s^{-1}$   & V \\   \hline 
    170       Sea surface temperature          & sst\_m & \r{}$K$      & T \\   \hline 
    171       Sea surface salinty              & sss\_m & $psu$        & T \\   \hline 
    172     \end{tabular} 
    173     \caption{ 
    174       \protect\label{tab:ssm} 
    175       Ocean variables provided by the ocean to the surface module (SBC). 
    176       The variable are averaged over nn{\_}fsbc time step, 
    177       \ie the frequency of computation of surface fluxes. 
    178     } 
    179   \end{center} 
     157  \centering 
     158  \begin{tabular}{|l|l|l|l|} 
     159    \hline 
     160    Variable description                           & Model variable  & Units  & point                 \\ 
     161    \hline 
     162    i-component of the surface current & ssu\_m               & $m.s^{-1}$     & U     \\ 
     163    \hline 
     164    j-component of the surface current & ssv\_m               & $m.s^{-1}$     & V     \\ 
     165    \hline 
     166    Sea surface temperature                  & sst\_m               & \r{}$K$              & T     \\\hline 
     167    Sea surface salinty                         & sss\_m               & $psu$              & T     \\   \hline 
     168  \end{tabular} 
     169  \caption[Ocean variables provided to the surface module)]{ 
     170    Ocean variables provided to the surface module (\texttt{SBC}). 
     171    The variable are averaged over \protect\np{nn_fsbc}{nn\_fsbc} time-step, 
     172    \ie\ the frequency of computation of surface fluxes.} 
     173  \label{tab:SBC_ssm} 
    180174\end{table} 
    181 %-------------------------------------------------------------------------------------------------------------- 
    182  
    183 %\colorbox{yellow}{Penser a} mettre dans le restant l'info nn{\_}fsbc ET nn{\_}fsbc*rdt de sorte de reinitialiser la moyenne si on change la frequence ou le pdt 
    184  
    185  
    186 % ================================================================ 
    187 %       Input Data  
    188 % ================================================================ 
     175 
     176%\colorbox{yellow}{Penser a} mettre dans le restant l'info nn\_fsbc ET nn\_fsbc*rdt de sorte de reinitialiser la moyenne si on change la frequence ou le pdt 
     177 
     178%% ================================================================================================= 
    189179\section{Input data generic interface} 
    190180\label{sec:SBC_input} 
    191181 
    192182A generic interface has been introduced to manage the way input data 
    193 (2D or 3D fields, like surface forcing or ocean T and S) are specify in \NEMO. 
    194 This task is archieved by \mdl{fldread}. 
    195 The module was design with four main objectives in mind:  
     183(2D or 3D fields, like surface forcing or ocean T and S) are specified in \NEMO. 
     184This task is achieved by \mdl{fldread}. 
     185The module is designed with four main objectives in mind: 
    196186\begin{enumerate} 
    197 \item 
    198   optionally provide a time interpolation of the input data at model time-step, whatever their input frequency is, 
     187\item optionally provide a time interpolation of the input data every specified model time-step, whatever their input frequency is, 
    199188  and according to the different calendars available in the model. 
    200 \item 
    201   optionally provide an on-the-fly space interpolation from the native input data grid to the model grid. 
    202 \item 
    203   make the run duration independent from the period cover by the input files. 
    204 \item 
    205   provide a simple user interface and a rather simple developer interface by 
    206   limiting the number of prerequisite information.  
    207 \end{enumerate}   
    208  
    209 As a results the user have only to fill in for each variable a structure in the namelist file to 
     189\item optionally provide an on-the-fly space interpolation from the native input data grid to the model grid. 
     190\item make the run duration independent from the period cover by the input files. 
     191\item provide a simple user interface and a rather simple developer interface by 
     192  limiting the number of prerequisite informations. 
     193\end{enumerate} 
     194 
     195As a result, the user has only to fill in for each variable a structure in the namelist file to 
    210196define the input data file and variable names, the frequency of the data (in hours or months), 
    211197whether its is climatological data or not, the period covered by the input file (one year, month, week or day), 
    212 and three additional parameters for on-the-fly interpolation. 
     198and three additional parameters for the on-the-fly interpolation. 
    213199When adding a new input variable, the developer has to add the associated structure in the namelist, 
    214200read this information by mirroring the namelist read in \rou{sbc\_blk\_init} for example, 
    215201and simply call \rou{fld\_read} to obtain the desired input field at the model time-step and grid points. 
    216202 
    217 The only constraints are that the input file is a NetCDF file, the file name follows a nomenclature  
     203The only constraints are that the input file is a NetCDF file, the file name follows a nomenclature 
    218204(see \autoref{subsec:SBC_fldread}), the period it cover is one year, month, week or day, and, 
    219205if on-the-fly interpolation is used, a file of weights must be supplied (see \autoref{subsec:SBC_iof}). 
    220206 
    221207Note that when an input data is archived on a disc which is accessible directly from the workspace where 
    222 the code is executed, then the use can set the \np{cn\_dir} to the pathway leading to the data. 
    223 By default, the data are assumed to have been copied so that cn\_dir='./'. 
    224  
    225 % ------------------------------------------------------------------------------------------------------------- 
    226 % Input Data specification (\mdl{fldread}) 
    227 % ------------------------------------------------------------------------------------------------------------- 
    228 \subsection{Input data specification (\protect\mdl{fldread})} 
     208the code is executed, then the user can set the \np{cn_dir}{cn\_dir} to the pathway leading to the data. 
     209By default, the data are assumed to be in the same directory as the executable, so that cn\_dir='./'. 
     210 
     211%% ================================================================================================= 
     212\subsection[Input data specification (\textit{fldread.F90})]{Input data specification (\protect\mdl{fldread})} 
    229213\label{subsec:SBC_fldread} 
    230214 
    231215The structure associated with an input variable contains the following information: 
    232216\begin{forlines} 
    233 !  file name  ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !  
     217!  file name  ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask ! 
    234218!             !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      ! 
    235219\end{forlines} 
    236 where  
    237 \begin{description}   
    238 \item[File name]: 
    239   the stem name of the NetCDF file to be open. 
     220where 
     221\begin{description} 
     222\item [File name]: the stem name of the NetCDF file to be opened. 
    240223  This stem will be completed automatically by the model, with the addition of a '.nc' at its end and 
    241224  by date information and possibly a prefix (when using AGRIF). 
    242   Tab.\autoref{tab:fldread} provides the resulting file name in all possible cases according to 
     225  \autoref{tab:SBC_fldread} provides the resulting file name in all possible cases according to 
    243226  whether it is a climatological file or not, and to the open/close frequency (see below for definition). 
    244  
    245 %--------------------------------------------------TABLE-------------------------------------------------- 
    246227  \begin{table}[htbp] 
    247     \begin{center} 
    248       \begin{tabular}{|l|c|c|c|} 
    249         \hline 
    250         & daily or weekLLL         & monthly                   &   yearly          \\   \hline 
    251         \np{clim}\forcode{ = .false.}  & fn\_yYYYYmMMdDD.nc  &   fn\_yYYYYmMM.nc   &   fn\_yYYYY.nc  \\   \hline 
    252         \np{clim}\forcode{ = .true.}         & not possible                  &  fn\_m??.nc             &   fn                \\   \hline 
    253       \end{tabular} 
    254     \end{center} 
    255     \caption{ 
    256       \protect\label{tab:fldread} 
    257       naming nomenclature for climatological or interannual input file, as a function of the Open/close frequency. 
     228    \centering 
     229    \begin{tabular}{|l|c|c|c|} 
     230      \hline 
     231                                  &  daily or weekLL     &  monthly           &  yearly        \\ 
     232      \hline 
     233      \np[=.false.]{clim}{clim} &  fn\_yYYYYmMMdDD.nc  &  fn\_yYYYYmMM.nc   &  fn\_yYYYY.nc  \\ 
     234      \hline 
     235      \np[=.true.]{clim}{clim}  &  not possible        &  fn\_m??.nc        &  fn            \\ 
     236      \hline 
     237    \end{tabular} 
     238    \caption[Naming nomenclature for climatological or interannual input file]{ 
     239      Naming nomenclature for climatological or interannual input file, 
     240      as a function of the open/close frequency. 
    258241      The stem name is assumed to be 'fn'. 
    259242      For weekly files, the 'LLL' corresponds to the first three letters of the first day of the week 
    260       (\ie 'sun','sat','fri','thu','wed','tue','mon'). 
    261       The 'YYYY', 'MM' and 'DD' should be replaced by the actual year/month/day, always coded with 4 or 2 digits. 
    262       Note that (1) in mpp, if the file is split over each subdomain, the suffix '.nc' is replaced by '\_PPPP.nc', 
     243      (\ie\ 'sun','sat','fri','thu','wed','tue','mon'). 
     244      The 'YYYY', 'MM' and 'DD' should be replaced by the actual year/month/day, 
     245      always coded with 4 or 2 digits. 
     246      Note that (1) in mpp, if the file is split over each subdomain, 
     247      the suffix '.nc' is replaced by '\_PPPP.nc', 
    263248      where 'PPPP' is the process number coded with 4 digits; 
    264       (2) when using AGRIF, the prefix '\_N' is added to files, where 'N'  is the child grid number. 
     249      (2) when using AGRIF, the prefix '\_N' is added to files, where 'N' is the child grid number. 
    265250    } 
     251    \label{tab:SBC_fldread} 
    266252  \end{table} 
    267 %-------------------------------------------------------------------------------------------------------------- 
    268    
    269  
    270 \item[Record frequency]: 
    271   the frequency of the records contained in the input file. 
     253\item [Record frequency]: the frequency of the records contained in the input file. 
    272254  Its unit is in hours if it is positive (for example 24 for daily forcing) or in months if negative 
    273255  (for example -1 for monthly forcing or -12 for annual forcing). 
    274   Note that this frequency must really be an integer and not a real. 
    275   On some computers, seting it to '24.' can be interpreted as 240! 
    276  
    277 \item[Variable name]: 
    278   the name of the variable to be read in the input NetCDF file. 
    279  
    280 \item[Time interpolation]: 
    281   a logical to activate, or not, the time interpolation. 
     256  Note that this frequency must REALLY be an integer and not a real. 
     257  On some computers, setting it to '24.' can be interpreted as 240! 
     258\item [Variable name]: the name of the variable to be read in the input NetCDF file. 
     259\item [Time interpolation]: a logical to activate, or not, the time interpolation. 
    282260  If set to 'false', the forcing will have a steplike shape remaining constant during each forcing period. 
    283261  For example, when using a daily forcing without time interpolation, the forcing remaining constant from 
    284262  00h00'00'' to 23h59'59". 
    285263  If set to 'true', the forcing will have a broken line shape. 
    286   Records are assumed to be dated the middle of the forcing period. 
     264  Records are assumed to be dated at the middle of the forcing period. 
    287265  For example, when using a daily forcing with time interpolation, 
    288   linear interpolation will be performed between mid-day of two consecutive days.  
    289  
    290 \item[Climatological forcing]: 
    291   a logical to specify if a input file contains climatological forcing which can be cycle in time, 
     266  linear interpolation will be performed between mid-day of two consecutive days. 
     267\item [Climatological forcing]: a logical to specify if a input file contains climatological forcing which can be cycle in time, 
    292268  or an interannual forcing which will requires additional files if 
    293   the period covered by the simulation exceed the one of the file. 
    294   See the above the file naming strategy which impacts the expected name of the file to be opened.  
    295  
    296 \item[Open/close frequency]: 
    297   the frequency at which forcing files must be opened/closed. 
     269  the period covered by the simulation exceeds the one of the file. 
     270  See the above file naming strategy which impacts the expected name of the file to be opened. 
     271\item [Open/close frequency]: the frequency at which forcing files must be opened/closed. 
    298272  Four cases are coded: 
    299273  'daily', 'weekLLL' (with 'LLL' the first 3 letters of the first day of the week), 'monthly' and 'yearly' which 
     
    301275  Files are assumed to contain data from the beginning of the open/close period. 
    302276  For example, the first record of a yearly file containing daily data is Jan 1st even if 
    303   the experiment is not starting at the beginning of the year.  
    304  
    305 \item[Others]: 
    306   'weights filename', 'pairing rotation' and 'land/sea mask' are associated with 
     277  the experiment is not starting at the beginning of the year. 
     278\item [Others]:  'weights filename', 'pairing rotation' and 'land/sea mask' are associated with 
    307279  on-the-fly interpolation which is described in \autoref{subsec:SBC_iof}. 
    308  
    309280\end{description} 
    310281 
     
    313284The only tricky point is therefore to specify the date at which we need to do the interpolation and 
    314285the date of the records read in the input files. 
    315 Following \citet{Leclair_Madec_OM09}, the date of a time step is set at the middle of the time step. 
    316 For example, for an experiment starting at 0h00'00" with a one hour time-step, 
     286Following \citet{leclair.madec_OM09}, the date of a time step is set at the middle of the time step. 
     287For example, for an experiment starting at 0h00'00" with a one-hour time-step, 
    317288a time interpolation will be performed at the following time: 0h30'00", 1h30'00", 2h30'00", etc. 
    318289However, for forcing data related to the surface module, 
    319 values are not needed at every time-step but at every \np{nn\_fsbc} time-step. 
    320 For example with \np{nn\_fsbc}\forcode{ = 3}, the surface module will be called at time-steps 1, 4, 7, etc. 
    321 The date used for the time interpolation is thus redefined to be at the middle of \np{nn\_fsbc} time-step period. 
    322 In the previous example, this leads to: 1h30'00", 4h30'00", 7h30'00", etc. \\  
     290values are not needed at every time-step but at every \np{nn_fsbc}{nn\_fsbc} time-step. 
     291For example with \np[=3]{nn_fsbc}{nn\_fsbc}, the surface module will be called at time-steps 1, 4, 7, etc. 
     292The date used for the time interpolation is thus redefined to the middle of \np{nn_fsbc}{nn\_fsbc} time-step period. 
     293In the previous example, this leads to: 1h30'00", 4h30'00", 7h30'00", etc. \\ 
    323294(2) For code readablility and maintenance issues, we don't take into account the NetCDF input file calendar. 
    324295The calendar associated with the forcing field is build according to the information provided by 
    325296user in the record frequency, the open/close frequency and the type of temporal interpolation. 
    326297For example, the first record of a yearly file containing daily data that will be interpolated in time is assumed to 
    327 be start Jan 1st at 12h00'00" and end Dec 31st at 12h00'00". \\ 
     298start Jan 1st at 12h00'00" and end Dec 31st at 12h00'00". \\ 
    328299(3) If a time interpolation is requested, the code will pick up the needed data in the previous (next) file when 
    329300interpolating data with the first (last) record of the open/close period. 
    330 For example, if the input file specifications are ''yearly, containing daily data to be interpolated in time'',  
     301For example, if the input file specifications are ''yearly, containing daily data to be interpolated in time'', 
    331302the values given by the code between 00h00'00" and 11h59'59" on Jan 1st will be interpolated values between 
    332303Dec 31st 12h00'00" and Jan 1st 12h00'00". 
    333304If the forcing is climatological, Dec and Jan will be keep-up from the same year. 
    334305However, if the forcing is not climatological, at the end of 
    335 the open/close period the code will automatically close the current file and open the next one. 
     306the open/close period, the code will automatically close the current file and open the next one. 
    336307Note that, if the experiment is starting (ending) at the beginning (end) of 
    337 an open/close period we do accept that the previous (next) file is not existing. 
     308an open/close period, we do accept that the previous (next) file is not existing. 
    338309In this case, the time interpolation will be performed between two identical values. 
    339310For example, when starting an experiment on Jan 1st of year Y with yearly files and daily data to be interpolated, 
    340311we do accept that the file related to year Y-1 is not existing. 
    341312The value of Jan 1st will be used as the missing one for Dec 31st of year Y-1. 
    342 If the file of year Y-1 exists, the code will read its last record.  
     313If the file of year Y-1 exists, the code will read its last record. 
    343314Therefore, this file can contain only one record corresponding to Dec 31st, 
    344315a useful feature for user considering that it is too heavy to manipulate the complete file for year Y-1. 
    345316 
    346  
    347 % ------------------------------------------------------------------------------------------------------------- 
    348 % Interpolation on the Fly 
    349 % ------------------------------------------------------------------------------------------------------------- 
     317%% ================================================================================================= 
    350318\subsection{Interpolation on-the-fly} 
    351319\label{subsec:SBC_iof} 
     
    353321Interpolation on the Fly allows the user to supply input files required for the surface forcing on 
    354322grids other than the model grid. 
    355 To do this he or she must supply, in addition to the source data file, a file of weights to be used to 
     323To do this, he or she must supply, in addition to the source data file(s), a file of weights to be used to 
    356324interpolate from the data grid to the model grid. 
    357325The original development of this code used the SCRIP package 
    358326(freely available \href{http://climate.lanl.gov/Software/SCRIP}{here} under a copyright agreement). 
    359 In principle, any package can be used to generate the weights, but the variables in 
     327In principle, any package such as CDO can be used to generate the weights, but the variables in 
    360328the input weights file must have the same names and meanings as assumed by the model. 
    361 Two methods are currently available: bilinear and bicubic interpolation. 
     329Two methods are currently available: bilinear and bicubic interpolations. 
    362330Prior to the interpolation, providing a land/sea mask file, the user can decide to remove land points from 
    363331the input file and substitute the corresponding values with the average of the 8 neighbouring points in 
     
    365333Only "sea points" are considered for the averaging. 
    366334The land/sea mask file must be provided in the structure associated with the input variable. 
    367 The netcdf land/sea mask variable name must be 'LSM' it must have the same horizontal and vertical dimensions of 
    368 the associated variable and should be equal to 1 over land and 0 elsewhere. 
    369 The procedure can be recursively applied setting nn\_lsm > 1 in namsbc namelist. 
    370 Note that nn\_lsm=0 forces the code to not apply the procedure even if a file for land/sea mask is supplied. 
    371  
     335The netcdf land/sea mask variable name must be 'LSM' and must have the same horizontal and vertical dimensions as 
     336the associated variables and should be equal to 1 over land and 0 elsewhere. 
     337The procedure can be recursively applied by setting nn\_lsm > 1 in namsbc namelist. 
     338Note that nn\_lsm=0 forces the code to not apply the procedure, even if a land/sea mask file is supplied. 
     339 
     340%% ================================================================================================= 
    372341\subsubsection{Bilinear interpolation} 
    373342\label{subsec:SBC_iof_bilinear} 
     
    375344The input weights file in this case has two sets of variables: 
    376345src01, src02, src03, src04 and wgt01, wgt02, wgt03, wgt04. 
    377 The "src" variables correspond to the point in the input grid to which the weight "wgt" is to be applied. 
     346The "src" variables correspond to the point in the input grid to which the weight "wgt" is applied. 
    378347Each src value is an integer corresponding to the index of a point in the input grid when 
    379348written as a one dimensional array. 
     
    391360and wgt(1) corresponds to variable "wgt01" for example. 
    392361 
     362%% ================================================================================================= 
    393363\subsubsection{Bicubic interpolation} 
    394364\label{subsec:SBC_iof_bicubic} 
    395365 
    396 Again there are two sets of variables: "src" and "wgt". 
    397 But in this case there are 16 of each. 
     366Again, there are two sets of variables: "src" and "wgt". 
     367But in this case, there are 16 of each. 
    398368The symbolic algorithm used to calculate values on the model grid is now: 
    399369 
     
    401371  \begin{split} 
    402372    f_{m}(i,j) =  f_{m}(i,j) +& \sum_{k=1}^{4} {wgt(k)f(idx(src(k)))} 
    403     +   \sum_{k=5}^{8} {wgt(k)\left.\frac{\partial f}{\partial i}\right| _{idx(src(k))} }    \\ 
    404     +& \sum_{k=9}^{12} {wgt(k)\left.\frac{\partial f}{\partial j}\right| _{idx(src(k))} } 
    405     +   \sum_{k=13}^{16} {wgt(k)\left.\frac{\partial ^2 f}{\partial i \partial j}\right| _{idx(src(k))} } 
     373    +  \sum_{k=5 }^{8 } {wgt(k)\left.\frac{\partial f}{\partial i}\right| _{idx(src(k))} }    \\ 
     374    +& \sum_{k=9 }^{12} {wgt(k)\left.\frac{\partial f}{\partial j}\right| _{idx(src(k))} } 
     375    +  \sum_{k=13}^{16} {wgt(k)\left.\frac{\partial ^2 f}{\partial i \partial j}\right| _{idx(src(k))} } 
    406376  \end{split} 
    407377\] 
    408378The gradients here are taken with respect to the horizontal indices and not distances since 
    409 the spatial dependency has been absorbed into the weights. 
    410  
     379the spatial dependency has been included into the weights. 
     380 
     381%% ================================================================================================= 
    411382\subsubsection{Implementation} 
    412383\label{subsec:SBC_iof_imp} 
     
    420391inspecting a global attribute stored in the weights input file. 
    421392This attribute must be called "ew\_wrap" and be of integer type. 
    422 If it is negative, the input non-model grid is assumed not to be cyclic. 
     393If it is negative, the input non-model grid is assumed to be not cyclic. 
    423394If zero or greater, then the value represents the number of columns that overlap. 
    424395$E.g.$ if the input grid has columns at longitudes 0, 1, 2, .... , 359, then ew\_wrap should be set to 0; 
    425396if longitudes are 0.5, 2.5, .... , 358.5, 360.5, 362.5, ew\_wrap should be 2. 
    426397If the model does not find attribute ew\_wrap, then a value of -999 is assumed. 
    427 In this case the \rou{fld\_read} routine defaults ew\_wrap to value 0 and 
     398In this case, the \rou{fld\_read} routine defaults ew\_wrap to value 0 and 
    428399therefore the grid is assumed to be cyclic with no overlapping columns. 
    429 (In fact this only matters when bicubic interpolation is required.) 
     400(In fact, this only matters when bicubic interpolation is required.) 
    430401Note that no testing is done to check the validity in the model, 
    431402since there is no way of knowing the name used for the longitude variable, 
     
    444415or is a copy of one from the first few columns on the opposite side of the grid (cyclical case). 
    445416 
     417%% ================================================================================================= 
    446418\subsubsection{Limitations} 
    447419\label{subsec:SBC_iof_lim} 
    448420 
    449 \begin{enumerate}   
    450 \item 
    451   The case where input data grids are not logically rectangular has not been tested. 
    452 \item 
    453   This code is not guaranteed to produce positive definite answers from positive definite inputs when 
     421\begin{enumerate} 
     422\item The case where input data grids are not logically rectangular (irregular grid case) has not been tested. 
     423\item This code is not guaranteed to produce positive definite answers from positive definite inputs when 
    454424  a bicubic interpolation method is used. 
    455 \item 
    456   The cyclic condition is only applied on left and right columns, and not to top and bottom rows. 
    457 \item 
    458   The gradients across the ends of a cyclical grid assume that the grid spacing between 
     425\item The cyclic condition is only applied on left and right columns, and not to top and bottom rows. 
     426\item The gradients across the ends of a cyclical grid assume that the grid spacing between 
    459427  the two columns involved are consistent with the weights used. 
    460 \item 
    461   Neither interpolation scheme is conservative. (There is a conservative scheme available in SCRIP, 
     428\item Neither interpolation scheme is conservative. (There is a conservative scheme available in SCRIP, 
    462429  but this has not been implemented.) 
    463430\end{enumerate} 
    464431 
     432%% ================================================================================================= 
    465433\subsubsection{Utilities} 
    466434\label{subsec:SBC_iof_util} 
     
    470438(see the directory NEMOGCM/TOOLS/WEIGHTS). 
    471439 
    472 % ------------------------------------------------------------------------------------------------------------- 
    473 % Standalone Surface Boundary Condition Scheme 
    474 % ------------------------------------------------------------------------------------------------------------- 
    475 \subsection{Standalone surface boundary condition scheme} 
    476 \label{subsec:SAS_iof} 
    477  
    478 %---------------------------------------namsbc_ana-------------------------------------------------- 
    479  
    480 \nlst{namsbc_sas} 
    481 %-------------------------------------------------------------------------------------------------------------- 
    482  
    483 In some circumstances it may be useful to avoid calculating the 3D temperature, 
    484 salinity and velocity fields and simply read them in from a previous run or receive them from OASIS.   
     440%% ================================================================================================= 
     441\subsection{Standalone surface boundary condition scheme (SAS)} 
     442\label{subsec:SBC_SAS} 
     443 
     444\begin{listing} 
     445  \nlst{namsbc_sas} 
     446  \caption{\forcode{&namsbc_sas}} 
     447  \label{lst:namsbc_sas} 
     448\end{listing} 
     449 
     450In some circumstances, it may be useful to avoid calculating the 3D temperature, 
     451salinity and velocity fields and simply read them in from a previous run or receive them from OASIS. 
    485452For example: 
    486453 
    487454\begin{itemize} 
    488 \item 
    489   Multiple runs of the model are required in code development to 
     455\item Multiple runs of the model are required in code development to 
    490456  see the effect of different algorithms in the bulk formulae. 
    491 \item 
    492   The effect of different parameter sets in the ice model is to be examined. 
    493 \item 
    494   Development of sea-ice algorithms or parameterizations. 
    495 \item 
    496   Spinup of the iceberg floats 
    497 \item 
    498   Ocean/sea-ice simulation with both media running in parallel (\np{ln\_mixcpl}\forcode{ = .true.}) 
     457\item The effect of different parameter sets in the ice model is to be examined. 
     458\item Development of sea-ice algorithms or parameterizations. 
     459\item Spinup of the iceberg floats 
     460\item Ocean/sea-ice simulation with both models running in parallel (\np[=.true.]{ln_mixcpl}{ln\_mixcpl}) 
    499461\end{itemize} 
    500462 
    501 The StandAlone Surface scheme provides this utility. 
    502 Its options are defined through the \ngn{namsbc\_sas} namelist variables. 
     463The Standalone Surface scheme provides this capacity. 
     464Its options are defined through the \nam{sbc_sas}{sbc\_sas} namelist variables. 
    503465A new copy of the model has to be compiled with a configuration based on ORCA2\_SAS\_LIM. 
    504 However no namelist parameters need be changed from the settings of the previous run (except perhaps nn{\_}date0). 
     466However, no namelist parameters need be changed from the settings of the previous run (except perhaps nn\_date0). 
    505467In this configuration, a few routines in the standard model are overriden by new versions. 
    506468Routines replaced are: 
    507469 
    508470\begin{itemize} 
    509 \item 
    510   \mdl{nemogcm}: 
    511   This routine initialises the rest of the model and repeatedly calls the stp time stepping routine (\mdl{step}). 
     471\item \mdl{nemogcm}: This routine initialises the rest of the model and repeatedly calls the stp time stepping routine (\mdl{step}). 
    512472  Since the ocean state is not calculated all associated initialisations have been removed. 
    513 \item 
    514   \mdl{step}: 
    515   The main time stepping routine now only needs to call the sbc routine (and a few utility functions). 
    516 \item 
    517   \mdl{sbcmod}: 
    518   This has been cut down and now only calculates surface forcing and the ice model required. 
     473\item \mdl{step}: The main time stepping routine now only needs to call the sbc routine (and a few utility functions). 
     474\item \mdl{sbcmod}: This has been cut down and now only calculates surface forcing and the ice model required. 
    519475  New surface modules that can function when only the surface level of the ocean state is defined can also be added 
    520   (\eg icebergs). 
    521 \item 
    522   \mdl{daymod}: 
    523   No ocean restarts are read or written (though the ice model restarts are retained), 
     476  (\eg\ icebergs). 
     477\item \mdl{daymod}: No ocean restarts are read or written (though the ice model restarts are retained), 
    524478  so calls to restart functions have been removed. 
    525479  This also means that the calendar cannot be controlled by time in a restart file, 
    526   so the user must make sure that nn{\_}date0 in the model namelist is correct for his or her purposes. 
    527 \item 
    528   \mdl{stpctl}: 
    529   Since there is no free surface solver, references to it have been removed from \rou{stp\_ctl} module. 
    530 \item 
    531   \mdl{diawri}: 
    532   All 3D data have been removed from the output. 
     480  so the user must check that nn\_date0 in the model namelist is correct for his or her purposes. 
     481\item \mdl{stpctl}: Since there is no free surface solver, references to it have been removed from \rou{stp\_ctl} module. 
     482\item \mdl{diawri}: All 3D data have been removed from the output. 
    533483  The surface temperature, salinity and velocity components (which have been read in) are written along with 
    534484  relevant forcing and ice data. 
     
    538488 
    539489\begin{itemize} 
    540 \item 
    541   \mdl{sbcsas}: 
    542   This module initialises the input files needed for reading temperature, salinity and 
     490\item \mdl{sbcsas}: This module initialises the input files needed for reading temperature, salinity and 
    543491  velocity arrays at the surface. 
    544   These filenames are supplied in namelist namsbc{\_}sas. 
    545   Unfortunately because of limitations with the \mdl{iom} module, 
     492  These filenames are supplied in namelist namsbc\_sas. 
     493  Unfortunately, because of limitations with the \mdl{iom} module, 
    546494  the full 3D fields from the mean files have to be read in and interpolated in time, 
    547495  before using just the top level. 
     
    549497\end{itemize} 
    550498 
    551  
    552 % Missing the description of the 2 following variables: 
    553 %   ln_3d_uve   = .true.    !  specify whether we are supplying a 3D u,v and e3 field 
    554 %   ln_read_frq = .false.    !  specify whether we must read frq or not 
    555  
    556  
    557  
    558 % ================================================================ 
    559 % Analytical formulation (sbcana module)  
    560 % ================================================================ 
    561 \section{Analytical formulation (\protect\mdl{sbcana})} 
    562 \label{sec:SBC_ana} 
    563  
    564 %---------------------------------------namsbc_ana-------------------------------------------------- 
    565 % 
    566 %\nlst{namsbc_ana} 
    567 %-------------------------------------------------------------------------------------------------------------- 
    568  
    569 The analytical formulation of the surface boundary condition is the default scheme. 
    570 In this case, all the six fluxes needed by the ocean are assumed to be uniform in space. 
    571 They take constant values given in the namelist \ngn{namsbc{\_}ana} by 
    572 the variables \np{rn\_utau0}, \np{rn\_vtau0}, \np{rn\_qns0}, \np{rn\_qsr0}, and \np{rn\_emp0} 
    573 ($\textit{emp}=\textit{emp}_S$). 
    574 The runoff is set to zero. 
    575 In addition, the wind is allowed to reach its nominal value within a given number of time steps (\np{nn\_tau000}). 
    576  
    577 If a user wants to apply a different analytical forcing, 
    578 the \mdl{sbcana} module can be modified to use another scheme. 
    579 As an example, the \mdl{sbc\_ana\_gyre} routine provides the analytical forcing for the GYRE configuration 
    580 (see GYRE configuration manual, in preparation). 
    581  
    582  
    583 % ================================================================ 
    584 % Flux formulation  
    585 % ================================================================ 
    586 \section{Flux formulation (\protect\mdl{sbcflx})} 
     499The user can also choose in the \nam{sbc_sas}{sbc\_sas} namelist to read the mean (nn\_fsbc time-step) fraction of solar net radiation absorbed in the 1st T level using 
     500 (\np[=.true.]{ln_flx}{ln\_flx}) and to provide 3D oceanic velocities instead of 2D ones (\np{ln_flx}{ln\_flx}\forcode{=.true.}). In that last case, only the 1st level will be read in. 
     501 
     502%% ================================================================================================= 
     503\section[Flux formulation (\textit{sbcflx.F90})]{Flux formulation (\protect\mdl{sbcflx})} 
    587504\label{sec:SBC_flx} 
    588 %------------------------------------------namsbc_flx---------------------------------------------------- 
    589  
    590 \nlst{namsbc_flx}  
    591 %------------------------------------------------------------------------------------------------------------- 
    592  
    593 In the flux formulation (\np{ln\_flx}\forcode{ = .true.}), 
     505 
     506\begin{listing} 
     507  \nlst{namsbc_flx} 
     508  \caption{\forcode{&namsbc_flx}} 
     509  \label{lst:namsbc_flx} 
     510\end{listing} 
     511 
     512In the flux formulation (\np[=.true.]{ln_flx}{ln\_flx}), 
    594513the surface boundary condition fields are directly read from input files. 
    595 The user has to define in the namelist \ngn{namsbc{\_}flx} the name of the file, 
     514The user has to define in the namelist \nam{sbc_flx}{sbc\_flx} the name of the file, 
    596515the name of the variable read in the file, the time frequency at which it is given (in hours), 
    597516and a logical setting whether a time interpolation to the model time step is required for this field. 
     
    601520See \autoref{subsec:SBC_ssr} for its specification. 
    602521 
    603  
    604 % ================================================================ 
    605 % Bulk formulation 
    606 % ================================================================ 
    607 \section[Bulk formulation {(\textit{sbcblk\{\_core,\_clio\}.F90})}] 
    608                         {Bulk formulation {(\protect\mdl{sbcblk\_core}, \protect\mdl{sbcblk\_clio})}} 
     522%% ================================================================================================= 
     523\section[Bulk formulation (\textit{sbcblk.F90})]{Bulk formulation (\protect\mdl{sbcblk})} 
    609524\label{sec:SBC_blk} 
    610525 
    611 In the bulk formulation, the surface boundary condition fields are computed using bulk formulae and atmospheric fields and ocean (and ice) variables. 
     526\begin{listing} 
     527  \nlst{namsbc_blk} 
     528  \caption{\forcode{&namsbc_blk}} 
     529  \label{lst:namsbc_blk} 
     530\end{listing} 
     531 
     532In the bulk formulation, the surface boundary condition fields are computed with bulk formulae using atmospheric fields 
     533and ocean (and sea-ice) variables averaged over \np{nn_fsbc}{nn\_fsbc} time-step. 
    612534 
    613535The atmospheric fields used depend on the bulk formulae used. 
    614 Two bulk formulations are available: 
    615 the CORE and the CLIO bulk formulea. 
     536In forced mode, when a sea-ice model is used, a specific bulk formulation is used. 
     537Therefore, different bulk formulae are used for the turbulent fluxes computation 
     538over the ocean and over sea-ice surface. 
     539For the ocean, four bulk formulations are available thanks to the \href{https://brodeau.github.io/aerobulk/}{Aerobulk} package (\citet{brodeau.barnier.ea_JPO16}): 
     540the NCAR (formerly named CORE), COARE 3.0, COARE 3.5 and ECMWF bulk formulae. 
    616541The choice is made by setting to true one of the following namelist variable: 
    617 \np{ln\_core} or \np{ln\_clio}. 
    618  
    619 Note: 
    620 in forced mode, when a sea-ice model is used, a bulk formulation (CLIO or CORE) have to be used. 
    621 Therefore the two bulk (CLIO and CORE) formulea include the computation of the fluxes over 
    622 both an ocean and an ice surface.  
    623  
    624 % ------------------------------------------------------------------------------------------------------------- 
    625 %        CORE Bulk formulea 
    626 % ------------------------------------------------------------------------------------------------------------- 
    627 \subsection{CORE formulea (\protect\mdl{sbcblk\_core}, \protect\np{ln\_core}\forcode{ = .true.})} 
    628 \label{subsec:SBC_blk_core} 
    629 %------------------------------------------namsbc_core---------------------------------------------------- 
    630 % 
    631 %\nlst{namsbc_core} 
    632 %------------------------------------------------------------------------------------------------------------- 
    633  
    634 The CORE bulk formulae have been developed by \citet{Large_Yeager_Rep04}. 
    635 They have been designed to handle the CORE forcing, a mixture of NCEP reanalysis and satellite data. 
    636 They use an inertial dissipative method to compute the turbulent transfer coefficients 
    637 (momentum, sensible heat and evaporation) from the 10 metre wind speed, air temperature and specific humidity. 
    638 This \citet{Large_Yeager_Rep04} dataset is available through 
    639 the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/CORE.html}{GFDL web site}. 
    640  
    641 Note that substituting ERA40 to NCEP reanalysis fields does not require changes in the bulk formulea themself. 
    642 This is the so-called DRAKKAR Forcing Set (DFS) \citep{Brodeau_al_OM09}. 
    643  
    644 Options are defined through the  \ngn{namsbc\_core} namelist variables. 
    645 The required 8 input fields are: 
    646  
    647 %--------------------------------------------------TABLE-------------------------------------------------- 
     542 \np{ln_NCAR}{ln\_NCAR}, \np{ln_COARE_3p0}{ln\_COARE\_3p0},  \np{ln_COARE_3p5}{ln\_COARE\_3p5} and  \np{ln_ECMWF}{ln\_ECMWF}. 
     543For sea-ice, three possibilities can be selected: 
     544a constant transfer coefficient (1.4e-3; default value), \citet{lupkes.gryanik.ea_JGR12} (\np{ln_Cd_L12}{ln\_Cd\_L12}), and \citet{lupkes.gryanik_JGR15} (\np{ln_Cd_L15}{ln\_Cd\_L15}) parameterizations 
     545 
     546Common options are defined through the \nam{sbc_blk}{sbc\_blk} namelist variables. 
     547The required 9 input fields are: 
     548 
    648549\begin{table}[htbp] 
    649   \label{tab:CORE} 
    650   \begin{center} 
    651     \begin{tabular}{|l|c|c|c|} 
    652       \hline 
    653       Variable desciption              & Model variable  & Units   & point \\    \hline 
    654       i-component of the 10m air velocity & utau      & $m.s^{-1}$         & T  \\  \hline 
    655       j-component of the 10m air velocity & vtau      & $m.s^{-1}$         & T  \\  \hline 
    656       10m air temperature              & tair      & \r{}$K$            & T   \\ \hline 
    657       Specific humidity             & humi      & \%              & T \\      \hline 
    658       Incoming long wave radiation     & qlw    & $W.m^{-2}$         & T \\      \hline 
    659       Incoming short wave radiation    & qsr    & $W.m^{-2}$         & T \\      \hline 
    660       Total precipitation (liquid + solid)   & precip & $Kg.m^{-2}.s^{-1}$ & T \\   \hline 
    661       Solid precipitation              & snow      & $Kg.m^{-2}.s^{-1}$ & T \\   \hline 
     550  \centering 
     551  \begin{tabular}{|l|c|c|c|} 
     552    \hline 
     553    Variable description                 & Model variable & Units              & point \\ 
     554    \hline 
     555    i-component of the 10m air velocity  & utau           & $m.s^{-1}$         & T     \\ 
     556    \hline 
     557    j-component of the 10m air velocity  & vtau           & $m.s^{-1}$         & T     \\ 
     558    \hline 
     559    10m air temperature                  & tair           & \r{}$K$            & T     \\ 
     560    \hline 
     561    Specific humidity                    & humi           & \%                 & T     \\ 
     562    \hline 
     563    Incoming long wave radiation         & qlw            & $W.m^{-2}$         & T     \\ 
     564    \hline 
     565    Incoming short wave radiation        & qsr            & $W.m^{-2}$         & T     \\ 
     566    \hline 
     567    Total precipitation (liquid + solid) & precip         & $Kg.m^{-2}.s^{-1}$ & T     \\ 
     568    \hline 
     569    Solid precipitation                  & snow           & $Kg.m^{-2}.s^{-1}$ & T     \\ 
     570    \hline 
     571    Mean sea-level pressure              & slp            & $hPa$              & T     \\ 
     572    \hline 
    662573    \end{tabular} 
    663   \end{center} 
     574  \label{tab:SBC_BULK} 
    664575\end{table} 
    665 %-------------------------------------------------------------------------------------------------------------- 
    666576 
    667577Note that the air velocity is provided at a tracer ocean point, not at a velocity ocean point ($u$- and $v$-points). 
     
    669579the ocean grid size is the same or larger than the one of the input atmospheric fields. 
    670580 
    671 The \np{sn\_wndi}, \np{sn\_wndj}, \np{sn\_qsr}, \np{sn\_qlw}, \np{sn\_tair}, \np{sn\_humi}, \np{sn\_prec}, 
    672 \np{sn\_snow}, \np{sn\_tdif} parameters describe the fields and the way they have to be used 
    673 (spatial and temporal interpolations).  
    674  
    675 \np{cn\_dir} is the directory of location of bulk files 
    676 \np{ln\_taudif} is the flag to specify if we use Hight Frequency (HF) tau information (.true.) or not (.false.) 
    677 \np{rn\_zqt}: is the height of humidity and temperature measurements (m) 
    678 \np{rn\_zu}: is the height of wind measurements (m) 
    679  
    680 Three multiplicative factors are availables:  
    681 \np{rn\_pfac} and \np{rn\_efac} allows to adjust (if necessary) the global freshwater budget by 
     581The \np{sn_wndi}{sn\_wndi}, \np{sn_wndj}{sn\_wndj}, \np{sn_qsr}{sn\_qsr}, \np{sn_qlw}{sn\_qlw}, \np{sn_tair}{sn\_tair}, \np{sn_humi}{sn\_humi}, \np{sn_prec}{sn\_prec}, 
     582\np{sn_snow}{sn\_snow}, \np{sn_tdif}{sn\_tdif} parameters describe the fields and the way they have to be used 
     583(spatial and temporal interpolations). 
     584 
     585\np{cn_dir}{cn\_dir} is the directory of location of bulk files 
     586\np{ln_taudif}{ln\_taudif} is the flag to specify if we use Hight Frequency (HF) tau information (.true.) or not (.false.) 
     587\np{rn_zqt}{rn\_zqt}: is the height of humidity and temperature measurements (m) 
     588\np{rn_zu}{rn\_zu}: is the height of wind measurements (m) 
     589 
     590Three multiplicative factors are available: 
     591\np{rn_pfac}{rn\_pfac} and \np{rn_efac}{rn\_efac} allow to adjust (if necessary) the global freshwater budget by 
    682592increasing/reducing the precipitations (total and snow) and or evaporation, respectively. 
    683 The third one,\np{rn\_vfac}, control to which extend the ice/ocean velocities are taken into account in 
     593The third one,\np{rn_vfac}{rn\_vfac}, control to which extend the ice/ocean velocities are taken into account in 
    684594the calculation of surface wind stress. 
    685 Its range should be between zero and one, and it is recommended to set it to 0. 
    686  
    687 % ------------------------------------------------------------------------------------------------------------- 
    688 %        CLIO Bulk formulea 
    689 % ------------------------------------------------------------------------------------------------------------- 
    690 \subsection{CLIO formulea (\protect\mdl{sbcblk\_clio}, \protect\np{ln\_clio}\forcode{ = .true.})} 
    691 \label{subsec:SBC_blk_clio} 
    692 %------------------------------------------namsbc_clio---------------------------------------------------- 
    693 % 
    694 %\nlst{namsbc_clio} 
    695 %------------------------------------------------------------------------------------------------------------- 
    696  
    697 The CLIO bulk formulae were developed several years ago for the Louvain-la-neuve coupled ice-ocean model 
    698 (CLIO, \cite{Goosse_al_JGR99}).  
    699 They are simpler bulk formulae. 
    700 They assume the stress to be known and compute the radiative fluxes from a climatological cloud cover.  
    701  
    702 Options are defined through the  \ngn{namsbc\_clio} namelist variables. 
    703 The required 7 input fields are: 
    704  
    705 %--------------------------------------------------TABLE-------------------------------------------------- 
    706 \begin{table}[htbp] 
    707   \label{tab:CLIO} 
    708   \begin{center} 
    709     \begin{tabular}{|l|l|l|l|} 
    710       \hline 
    711       Variable desciption           & Model variable  & Units           & point \\  \hline 
    712       i-component of the ocean stress     & utau         & $N.m^{-2}$         & U \\   \hline 
    713       j-component of the ocean stress     & vtau         & $N.m^{-2}$         & V \\   \hline 
    714       Wind speed module             & vatm         & $m.s^{-1}$         & T \\   \hline 
    715       10m air temperature              & tair         & \r{}$K$            & T \\   \hline 
    716       Specific humidity                & humi         & \%              & T \\   \hline 
    717       Cloud cover                   &           & \%              & T \\   \hline 
    718       Total precipitation (liquid + solid)   & precip    & $Kg.m^{-2}.s^{-1}$ & T \\   \hline 
    719       Solid precipitation              & snow         & $Kg.m^{-2}.s^{-1}$ & T \\   \hline 
    720     \end{tabular} 
    721   \end{center} 
    722 \end{table} 
    723 %-------------------------------------------------------------------------------------------------------------- 
     595Its range must be between zero and one, and it is recommended to set it to 0 at low-resolution (ORCA2 configuration). 
    724596 
    725597As for the flux formulation, information about the input data required by the model is provided in 
    726 the namsbc\_blk\_core or namsbc\_blk\_clio namelist (see \autoref{subsec:SBC_fldread}).  
    727  
    728 % ================================================================ 
    729 % Coupled formulation 
    730 % ================================================================ 
    731 \section{Coupled formulation (\protect\mdl{sbccpl})} 
     598the namsbc\_blk namelist (see \autoref{subsec:SBC_fldread}). 
     599 
     600%% ================================================================================================= 
     601\subsection[Ocean-Atmosphere Bulk formulae (\textit{sbcblk\_algo\_coare.F90, sbcblk\_algo\_coare3p5.F90, sbcblk\_algo\_ecmwf.F90, sbcblk\_algo\_ncar.F90})]{Ocean-Atmosphere Bulk formulae (\mdl{sbcblk\_algo\_coare}, \mdl{sbcblk\_algo\_coare3p5}, \mdl{sbcblk\_algo\_ecmwf}, \mdl{sbcblk\_algo\_ncar})} 
     602\label{subsec:SBC_blk_ocean} 
     603 
     604Four different bulk algorithms are available to compute surface turbulent momentum and heat fluxes over the ocean. 
     605COARE 3.0, COARE 3.5 and ECMWF schemes mainly differ by their roughness lenghts computation and consequently 
     606their neutral transfer coefficients relationships with neutral wind. 
     607\begin{itemize} 
     608\item NCAR (\np[=.true.]{ln_NCAR}{ln\_NCAR}): The NCAR bulk formulae have been developed by \citet{large.yeager_rpt04}. 
     609  They have been designed to handle the NCAR forcing, a mixture of NCEP reanalysis and satellite data. 
     610  They use an inertial dissipative method to compute the turbulent transfer coefficients 
     611  (momentum, sensible heat and evaporation) from the 10m wind speed, air temperature and specific humidity. 
     612  This \citet{large.yeager_rpt04} dataset is available through 
     613  the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/NCAR.html}{GFDL web site}. 
     614  Note that substituting ERA40 to NCEP reanalysis fields does not require changes in the bulk formulea themself. 
     615  This is the so-called DRAKKAR Forcing Set (DFS) \citep{brodeau.barnier.ea_OM10}. 
     616\item COARE 3.0 (\np[=.true.]{ln_COARE_3p0}{ln\_COARE\_3p0}): See \citet{fairall.bradley.ea_JC03} for more details 
     617\item COARE 3.5 (\np[=.true.]{ln_COARE_3p5}{ln\_COARE\_3p5}): See \citet{edson.jampana.ea_JPO13} for more details 
     618\item ECMWF (\np[=.true.]{ln_ECMWF}{ln\_ECMWF}): Based on \href{https://www.ecmwf.int/node/9221}{IFS (Cy31)} implementation and documentation. 
     619  Surface roughness lengths needed for the Obukhov length are computed following \citet{beljaars_QJRMS95}. 
     620\end{itemize} 
     621 
     622%% ================================================================================================= 
     623\subsection{Ice-Atmosphere Bulk formulae} 
     624\label{subsec:SBC_blk_ice} 
     625 
     626Surface turbulent fluxes between sea-ice and the atmosphere can be computed in three different ways: 
     627 
     628\begin{itemize} 
     629\item Constant value (\np[ Cd_ice=1.4e-3 ]{constant value}{constant\ value}): 
     630  default constant value used for momentum and heat neutral transfer coefficients 
     631\item \citet{lupkes.gryanik.ea_JGR12} (\np[=.true.]{ln_Cd_L12}{ln\_Cd\_L12}): 
     632  This scheme adds a dependency on edges at leads, melt ponds and flows 
     633  of the constant neutral air-ice drag. After some approximations, 
     634  this can be resumed to a dependency on ice concentration (A). 
     635  This drag coefficient has a parabolic shape (as a function of ice concentration) 
     636  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. 
     637  It is theoretically applicable to all ice conditions (not only MIZ). 
     638\item \citet{lupkes.gryanik_JGR15} (\np[=.true.]{ln_Cd_L15}{ln\_Cd\_L15}): 
     639  Alternative turbulent transfer coefficients formulation between sea-ice 
     640  and atmosphere with distinct momentum and heat coefficients depending 
     641  on sea-ice concentration and atmospheric stability (no melt-ponds effect for now). 
     642  The parameterization is adapted from ECHAM6 atmospheric model. 
     643  Compared to Lupkes2012 scheme, it considers specific skin and form drags 
     644  to compute neutral transfer coefficients for both heat and momentum fluxes. 
     645  Atmospheric stability effect on transfer coefficient is also taken into account. 
     646\end{itemize} 
     647 
     648%% ================================================================================================= 
     649\section[Coupled formulation (\textit{sbccpl.F90})]{Coupled formulation (\protect\mdl{sbccpl})} 
    732650\label{sec:SBC_cpl} 
    733 %------------------------------------------namsbc_cpl---------------------------------------------------- 
    734  
    735 \nlst{namsbc_cpl}  
    736 %------------------------------------------------------------------------------------------------------------- 
     651 
     652\begin{listing} 
     653  \nlst{namsbc_cpl} 
     654  \caption{\forcode{&namsbc_cpl}} 
     655  \label{lst:namsbc_cpl} 
     656\end{listing} 
    737657 
    738658In the coupled formulation of the surface boundary condition, 
    739 the fluxes are provided by the OASIS coupler at a frequency which is defined in the OASIS coupler, 
     659the fluxes are provided by the OASIS coupler at a frequency which is defined in the OASIS coupler namelist, 
    740660while sea and ice surface temperature, ocean and ice albedo, and ocean currents are sent to 
    741661the atmospheric component. 
    742662 
    743663A generalised coupled interface has been developed. 
    744 It is currently interfaced with OASIS-3-MCT (\key{oasis3}). 
    745 It has been successfully used to interface \NEMO to most of the European atmospheric GCM 
     664It is currently interfaced with OASIS-3-MCT versions 1 to 4 (\key{oasis3}). 
     665An additional specific CPP key (\key{oa3mct\_v1v2}) is needed for OASIS-3-MCT versions 1 and 2. 
     666It has been successfully used to interface \NEMO\ to most of the European atmospheric GCM 
    746667(ARPEGE, ECHAM, ECMWF, HadAM, HadGAM, LMDz), as well as to \href{http://wrf-model.org/}{WRF} 
    747668(Weather Research and Forecasting Model). 
    748669 
    749 Note that in addition to the setting of \np{ln\_cpl} to true, the \key{coupled} have to be defined. 
    750 The CPP key is mainly used in sea-ice to ensure that the atmospheric fluxes are actually received by 
    751 the ice-ocean system (no calculation of ice sublimation in coupled mode). 
    752 When PISCES biogeochemical model (\key{top} and \key{pisces}) is also used in the coupled system,  
    753 the whole carbon cycle is computed by defining \key{cpl\_carbon\_cycle}. 
     670When PISCES biogeochemical model (\key{top}) is also used in the coupled system, 
     671the whole carbon cycle is computed. 
    754672In this case, CO$_2$ fluxes will be exchanged between the atmosphere and the ice-ocean system 
    755 (and need to be activated in \ngn{namsbc{\_}cpl} ). 
     673(and need to be activated in \nam{sbc_cpl}{sbc\_cpl} ). 
    756674 
    757675The namelist above allows control of various aspects of the coupling fields (particularly for vectors) and 
    758676now allows for any coupling fields to have multiple sea ice categories (as required by LIM3 and CICE). 
    759 When indicating a multi-category coupling field in namsbc{\_}cpl the number of categories will be determined by 
     677When indicating a multi-category coupling field in \nam{sbc_cpl}{sbc\_cpl}, the number of categories will be determined by 
    760678the number used in the sea ice model. 
    761 In some limited cases it may be possible to specify single category coupling fields even when 
     679In some limited cases, it may be possible to specify single category coupling fields even when 
    762680the sea ice model is running with multiple categories - 
    763 in this case the user should examine the code to be sure the assumptions made are satisfactory. 
    764 In cases where this is definitely not possible the model should abort with an error message. 
    765 The new code has been tested using ECHAM with LIM2, and HadGAM3 with CICE but 
    766 although it will compile with \key{lim3} additional minor code changes may be required to run using LIM3. 
    767  
    768  
    769 % ================================================================ 
    770 %        Atmospheric pressure 
    771 % ================================================================ 
    772 \section{Atmospheric pressure (\protect\mdl{sbcapr})} 
     681in this case, the user should examine the code to be sure the assumptions made are satisfactory. 
     682In cases where this is definitely not possible, the model should abort with an error message. 
     683 
     684%% ================================================================================================= 
     685\section[Atmospheric pressure (\textit{sbcapr.F90})]{Atmospheric pressure (\protect\mdl{sbcapr})} 
    773686\label{sec:SBC_apr} 
    774 %------------------------------------------namsbc_apr---------------------------------------------------- 
    775  
    776 \nlst{namsbc_apr}  
    777 %------------------------------------------------------------------------------------------------------------- 
     687 
     688\begin{listing} 
     689  \nlst{namsbc_apr} 
     690  \caption{\forcode{&namsbc_apr}} 
     691  \label{lst:namsbc_apr} 
     692\end{listing} 
    778693 
    779694The optional atmospheric pressure can be used to force ocean and ice dynamics 
    780 (\np{ln\_apr\_dyn}\forcode{ = .true.}, \textit{\ngn{namsbc}} namelist). 
    781 The input atmospheric forcing defined via \np{sn\_apr} structure (\textit{namsbc\_apr} namelist) 
     695(\np[=.true.]{ln_apr_dyn}{ln\_apr\_dyn}, \nam{sbc}{sbc} namelist). 
     696The input atmospheric forcing defined via \np{sn_apr}{sn\_apr} structure (\nam{sbc_apr}{sbc\_apr} namelist) 
    782697can be interpolated in time to the model time step, and even in space when the interpolation on-the-fly is used. 
    783698When used to force the dynamics, the atmospheric pressure is further transformed into 
     
    788703\] 
    789704where $P_{atm}$ is the atmospheric pressure and $P_o$ a reference atmospheric pressure. 
    790 A value of $101,000~N/m^2$ is used unless \np{ln\_ref\_apr} is set to true. 
    791 In this case $P_o$ is set to the value of $P_{atm}$ averaged over the ocean domain, 
    792 \ie the mean value of $\eta_{ib}$ is kept to zero at all time step. 
     705A value of $101,000~N/m^2$ is used unless \np{ln_ref_apr}{ln\_ref\_apr} is set to true. 
     706In this case, $P_o$ is set to the value of $P_{atm}$ averaged over the ocean domain, 
     707\ie\ the mean value of $\eta_{ib}$ is kept to zero at all time steps. 
    793708 
    794709The gradient of $\eta_{ib}$ is added to the RHS of the ocean momentum equation (see \mdl{dynspg} for the ocean). 
    795710For sea-ice, the sea surface height, $\eta_m$, which is provided to the sea ice model is set to $\eta - \eta_{ib}$ 
    796711(see \mdl{sbcssr} module). 
    797 $\eta_{ib}$ can be set in the output. 
     712$\eta_{ib}$ can be written in the output. 
    798713This can simplify altimetry data and model comparison as 
    799714inverse barometer sea surface height is usually removed from these date prior to their distribution. 
    800715 
    801716When using time-splitting and BDY package for open boundaries conditions, 
    802 the equivalent inverse barometer sea surface height $\eta_{ib}$ can be added to BDY ssh data:  
    803 \np{ln\_apr\_obc}  might be set to true. 
    804  
    805 % ================================================================ 
    806 %        Surface Tides Forcing 
    807 % ================================================================ 
    808 \section{Surface tides (\protect\mdl{sbctide})} 
     717the equivalent inverse barometer sea surface height $\eta_{ib}$ can be added to BDY ssh data: 
     718\np{ln_apr_obc}{ln\_apr\_obc}  might be set to true. 
     719 
     720%% ================================================================================================= 
     721\section[Surface tides (\textit{sbctide.F90})]{Surface tides (\protect\mdl{sbctide})} 
    809722\label{sec:SBC_tide} 
    810723 
    811 %------------------------------------------nam_tide--------------------------------------- 
    812  
    813 \nlst{nam_tide} 
    814 %----------------------------------------------------------------------------------------- 
     724\begin{listing} 
     725  \nlst{nam_tide} 
     726  \caption{\forcode{&nam_tide}} 
     727  \label{lst:nam_tide} 
     728\end{listing} 
    815729 
    816730The tidal forcing, generated by the gravity forces of the Earth-Moon and Earth-Sun sytems, 
    817 is activated if \np{ln\_tide} and \np{ln\_tide\_pot} are both set to \forcode{.true.} in \ngn{nam\_tide}. 
    818 This translates as an additional barotropic force in the momentum equations \ref{eq:PE_dyn} such that: 
     731is activated if \np{ln_tide}{ln\_tide} and \np{ln_tide_pot}{ln\_tide\_pot} are both set to \forcode{.true.} in \nam{_tide}{\_tide}. 
     732This translates as an additional barotropic force in the momentum \autoref{eq:MB_PE_dyn} such that: 
    819733\[ 
    820   % \label{eq:PE_dyn_tides} 
    821   \frac{\partial {\rm {\bf U}}_h }{\partial t}= ... 
     734  % \label{eq:SBC_PE_dyn_tides} 
     735  \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= ... 
    822736  +g\nabla (\Pi_{eq} + \Pi_{sal}) 
    823737\] 
    824738where $\Pi_{eq}$ stands for the equilibrium tidal forcing and 
    825739$\Pi_{sal}$ is a self-attraction and loading term (SAL). 
    826   
     740 
    827741The equilibrium tidal forcing is expressed as a sum over a subset of 
    828742constituents chosen from the set of available tidal constituents 
    829 defined in file \rou{SBC/tide.h90} (this comprises the tidal 
     743defined in file \hf{SBC/tide} (this comprises the tidal 
    830744constituents \textit{M2, N2, 2N2, S2, K2, K1, O1, Q1, P1, M4, Mf, Mm, 
    831745  Msqm, Mtm, S1, MU2, NU2, L2}, and \textit{T2}). Individual 
    832746constituents are selected by including their names in the array 
    833 \np{clname} in \ngn{nam\_tide} (e.g., \np{clname(1) = 'M2', 
    834   clname(2)='S2'} to select solely the tidal consituents \textit{M2} 
    835 and \textit{S2}). Optionally, when \np{ln\_tide\_ramp} is set to 
     747\np{clname}{clname} in \nam{_tide}{\_tide} (e.g., \np{clname}{clname}\forcode{(1)='M2', } 
     748\np{clname}{clname}\forcode{(2)='S2'} to select solely the tidal consituents \textit{M2} 
     749and \textit{S2}). Optionally, when \np{ln_tide_ramp}{ln\_tide\_ramp} is set to 
    836750\forcode{.true.}, the equilibrium tidal forcing can be ramped up 
    837 linearly from zero during the initial \np{rdttideramp} days of the 
     751linearly from zero during the initial \np{rdttideramp}{rdttideramp} days of the 
    838752model run. 
    839753 
    840754The SAL term should in principle be computed online as it depends on 
    841 the model tidal prediction itself (see \citet{Arbic2004} for a 
     755the model tidal prediction itself (see \citet{arbic.garner.ea_DSR04} for a 
    842756discussion about the practical implementation of this term). 
    843757Nevertheless, the complex calculations involved would make this 
    844 computationally too expensive.  Here, two options are available: 
     758computationally too expensive. Here, two options are available: 
    845759$\Pi_{sal}$ generated by an external model can be read in 
    846 (\np{ln\_read\_load=.true.}), or a ``scalar approximation'' can be 
    847 used (\np{ln\_scal\_load=.true.}). In the latter case 
     760(\np[=.true.]{ln_read_load}{ln\_read\_load}), or a ``scalar approximation'' can be 
     761used (\np[=.true.]{ln_scal_load}{ln\_scal\_load}). In the latter case 
    848762\[ 
    849763  \Pi_{sal} = \beta \eta, 
    850764\] 
    851 where $\beta$ (\np{rn\_scal\_load} with a default value of 0.094) is a 
     765where $\beta$ (\np{rn_scal_load}{rn\_scal\_load} with a default value of 0.094) is a 
    852766spatially constant scalar, often chosen to minimize tidal prediction 
    853 errors. Setting both \np{ln\_read\_load} and \np{ln\_scal\_load} to 
     767errors. Setting both \np{ln_read_load}{ln\_read\_load} and \np{ln_scal_load}{ln\_scal\_load} to 
    854768\forcode{.false.} removes the SAL contribution. 
    855769 
    856 % ================================================================ 
    857 %        River runoffs 
    858 % ================================================================ 
    859 \section{River runoffs (\protect\mdl{sbcrnf})} 
     770%% ================================================================================================= 
     771\section[River runoffs (\textit{sbcrnf.F90})]{River runoffs (\protect\mdl{sbcrnf})} 
    860772\label{sec:SBC_rnf} 
    861 %------------------------------------------namsbc_rnf---------------------------------------------------- 
    862  
    863 \nlst{namsbc_rnf}  
    864 %------------------------------------------------------------------------------------------------------------- 
    865  
    866 %River runoff generally enters the ocean at a nonzero depth rather than through the surface.  
     773 
     774\begin{listing} 
     775  \nlst{namsbc_rnf} 
     776  \caption{\forcode{&namsbc_rnf}} 
     777  \label{lst:namsbc_rnf} 
     778\end{listing} 
     779 
     780%River runoff generally enters the ocean at a nonzero depth rather than through the surface. 
    867781%Many models, however, have traditionally inserted river runoff to the top model cell. 
    868 %This was the case in \NEMO prior to the version 3.3. The switch toward a input of runoff  
    869 %throughout a nonzero depth has been motivated by the numerical and physical problems  
    870 %that arise when the top grid cells are of the order of one meter. This situation is common in  
    871 %coastal modelling and becomes more and more often open ocean and climate modelling  
     782%This was the case in \NEMO\ prior to the version 3.3. The switch toward a input of runoff 
     783%throughout a nonzero depth has been motivated by the numerical and physical problems 
     784%that arise when the top grid cells are of the order of one meter. This situation is common in 
     785%coastal modelling and becomes more and more often open ocean and climate modelling 
    872786%\footnote{At least a top cells thickness of 1~meter and a 3 hours forcing frequency are 
    873 %required to properly represent the diurnal cycle \citep{Bernie_al_JC05}. see also \autoref{fig:SBC_dcy}.}. 
    874  
    875  
    876 %To do this we need to treat evaporation/precipitation fluxes and river runoff differently in the  
    877 %\mdl{tra\_sbc} module.  We decided to separate them throughout the code, so that the variable  
    878 %\textit{emp} represented solely evaporation minus precipitation fluxes, and a new 2d variable  
    879 %rnf was added which represents the volume flux of river runoff (in kg/m2s to remain consistent with  
    880 %emp).  This meant many uses of emp and emps needed to be changed, a list of all modules which use  
     787%required to properly represent the diurnal cycle \citep{bernie.woolnough.ea_JC05}. see also \autoref{fig:SBC_dcy}.}. 
     788 
     789%To do this we need to treat evaporation/precipitation fluxes and river runoff differently in the 
     790%\mdl{tra\_sbc} module.  We decided to separate them throughout the code, so that the variable 
     791%\textit{emp} represented solely evaporation minus precipitation fluxes, and a new 2d variable 
     792%rnf was added which represents the volume flux of river runoff (in kg/m2s to remain consistent with 
     793%emp).  This meant many uses of emp and emps needed to be changed, a list of all modules which use 
    881794%emp or emps and the changes made are below: 
    882  
    883795 
    884796%Rachel: 
    885797River runoff generally enters the ocean at a nonzero depth rather than through the surface. 
    886798Many models, however, have traditionally inserted river runoff to the top model cell. 
    887 This was the case in \NEMO prior to the version 3.3, 
     799This was the case in \NEMO\ prior to the version 3.3, 
    888800and was combined with an option to increase vertical mixing near the river mouth. 
    889801 
    890802However, with this method numerical and physical problems arise when the top grid cells are of the order of one meter. 
    891 This situation is common in coastal modelling and is becoming more common in open ocean and climate modelling  
     803This situation is common in coastal modelling and is becoming more common in open ocean and climate modelling 
    892804\footnote{ 
    893805  At least a top cells thickness of 1~meter and a 3 hours forcing frequency are required to 
    894   properly represent the diurnal cycle \citep{Bernie_al_JC05}. 
     806  properly represent the diurnal cycle \citep{bernie.woolnough.ea_JC05}. 
    895807  see also \autoref{fig:SBC_dcy}.}. 
    896808 
     
    900812along with the depth (in metres) which the river should be added to. 
    901813 
    902 Namelist variables in \ngn{namsbc\_rnf}, \np{ln\_rnf\_depth}, \np{ln\_rnf\_sal} and 
    903 \np{ln\_rnf\_temp} control whether the river attributes (depth, salinity and temperature) are read in and used. 
     814Namelist variables in \nam{sbc_rnf}{sbc\_rnf}, \np{ln_rnf_depth}{ln\_rnf\_depth}, \np{ln_rnf_sal}{ln\_rnf\_sal} and 
     815\np{ln_rnf_temp}{ln\_rnf\_temp} control whether the river attributes (depth, salinity and temperature) are read in and used. 
    904816If these are set as false the river is added to the surface box only, assumed to be fresh (0~psu), 
    905817and/or taken as surface temperature respectively. 
    906818 
    907 The runoff value and attributes are read in in sbcrnf.   
     819The runoff value and attributes are read in in sbcrnf. 
    908820For temperature -999 is taken as missing data and the river temperature is taken to 
    909821be the surface temperatue at the river point. 
    910 For the depth parameter a value of -1 means the river is added to the surface box only,  
    911 and a value of -999 means the river is added through the entire water column.  
     822For the depth parameter a value of -1 means the river is added to the surface box only, 
     823and a value of -999 means the river is added through the entire water column. 
    912824After being read in the temperature and salinity variables are multiplied by the amount of runoff 
    913825(converted into m/s) to give the heat and salt content of the river runoff. 
    914826After the user specified depth is read ini, 
    915 the number of grid boxes this corresponds to is calculated and stored in the variable \np{nz\_rnf}. 
     827the number of grid boxes this corresponds to is calculated and stored in the variable \np{nz_rnf}{nz\_rnf}. 
    916828The variable \textit{h\_dep} is then calculated to be the depth (in metres) of 
    917829the bottom of the lowest box the river water is being added to 
    918 (\ie the total depth that river water is being added to in the model). 
     830(\ie\ the total depth that river water is being added to in the model). 
    919831 
    920832The mass/volume addition due to the river runoff is, at each relevant depth level, added to 
     
    922834This increases the diffusion term in the vicinity of the river, thereby simulating a momentum flux. 
    923835The sea surface height is calculated using the sum of the horizontal divergence terms, 
    924 and so the river runoff indirectly forces an increase in sea surface height.  
     836and so the river runoff indirectly forces an increase in sea surface height. 
    925837 
    926838The \textit{hdivn} terms are used in the tracer advection modules to force vertical velocities. 
     
    935847As such the volume of water does not change, but the water is diluted. 
    936848 
    937 For the non-linear free surface case (\key{vvl}), no flux is allowed through the surface. 
     849For the non-linear free surface case, no flux is allowed through the surface. 
    938850Instead in the surface box (as well as water moving up from the boxes below) a volume of runoff water is added with 
    939851no corresponding heat and salt addition and so as happens in the lower boxes there is a dilution effect. 
     
    944856This is done in the same way for both vvl and non-vvl. 
    945857The temperature and salinity are increased through the specified depth according to 
    946 the heat and salt content of the river.  
     858the heat and salt content of the river. 
    947859 
    948860In the non-linear free surface case (vvl), 
     
    953865 
    954866It is also possible for runnoff to be specified as a negative value for modelling flow through straits, 
    955 \ie modelling the Baltic flow in and out of the North Sea. 
     867\ie\ modelling the Baltic flow in and out of the North Sea. 
    956868When the flow is out of the domain there is no change in temperature and salinity, 
    957869regardless of the namelist options used, 
    958 as the ocean water leaving the domain removes heat and salt (at the same concentration) with it.  
    959  
    960  
    961 %\colorbox{yellow}{Nevertheless, Pb of vertical resolution and 3D input : increase vertical mixing near river mouths to mimic a 3D river  
     870as the ocean water leaving the domain removes heat and salt (at the same concentration) with it. 
     871 
     872%\colorbox{yellow}{Nevertheless, Pb of vertical resolution and 3D input : increase vertical mixing near river mouths to mimic a 3D river 
    962873 
    963874%All river runoff and emp fluxes are assumed to be fresh water (zero salinity) and at the same temperature as the sea surface.} 
     
    969880%ENDIF 
    970881 
    971 %\gmcomment{  word doc of runoffs: 
    972 % 
    973 %In the current \NEMO setup river runoff is added to emp fluxes, these are then applied at just the sea surface as a volume change (in the variable volume case this is a literal volume change, and in the linear free surface case the free surface is moved) and a salt flux due to the concentration/dilution effect.  There is also an option to increase vertical mixing near river mouths; this gives the effect of having a 3d river.  All river runoff and emp fluxes are assumed to be fresh water (zero salinity) and at the same temperature as the sea surface. 
    974 %Our aim was to code the option to specify the temperature and salinity of river runoff, (as well as the amount), along with the depth that the river water will affect.  This would make it possible to model low salinity outflow, such as the Baltic, and would allow the ocean temperature to be affected by river runoff.   
    975  
    976 %The depth option makes it possible to have the river water affecting just the surface layer, throughout depth, or some specified point in between. 
    977  
    978 %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: 
    979  
    980 %} 
    981 % ================================================================ 
    982 %        Ice shelf melting 
    983 % ================================================================ 
    984 \section{Ice shelf melting (\protect\mdl{sbcisf})} 
     882\cmtgm{  word doc of runoffs: 
     883In the current \NEMO\ setup river runoff is added to emp fluxes, 
     884these are then applied at just the sea surface as a volume change (in the variable volume case 
     885this is a literal volume change, and in the linear free surface case the free surface is moved) 
     886and a salt flux due to the concentration/dilution effect. 
     887There is also an option to increase vertical mixing near river mouths; 
     888this gives the effect of having a 3d river. 
     889All river runoff and emp fluxes are assumed to be fresh water (zero salinity) and 
     890at the same temperature as the sea surface. 
     891Our aim was to code the option to specify the temperature and salinity of river runoff, 
     892(as well as the amount), along with the depth that the river water will affect. 
     893This would make it possible to model low salinity outflow, such as the Baltic, 
     894and would allow the ocean temperature to be affected by river runoff. 
     895 
     896The depth option makes it possible to have the river water affecting just the surface layer, 
     897throughout depth, or some specified point in between. 
     898 
     899To do this we need to treat evaporation/precipitation fluxes and river runoff differently in 
     900the \mdl{tra_sbc} module. 
     901We decided to separate them throughout the code, 
     902so that the variable emp represented solely evaporation minus precipitation fluxes, 
     903and a new 2d variable rnf was added which represents the volume flux of river runoff 
     904(in $kg/m^2s$ to remain consistent with $emp$). 
     905This meant many uses of emp and emps needed to be changed, 
     906a list of all modules which use $emp$ or $emps$ and the changes made are below:} 
     907 
     908%% ================================================================================================= 
     909\section[Ice shelf melting (\textit{sbcisf.F90})]{Ice shelf melting (\protect\mdl{sbcisf})} 
    985910\label{sec:SBC_isf} 
    986 %------------------------------------------namsbc_isf---------------------------------------------------- 
    987  
    988 \nlst{namsbc_isf} 
    989 %-------------------------------------------------------------------------------------------------------- 
    990 The namelist variable in \ngn{namsbc}, \np{nn\_isf}, controls the ice shelf representation. 
    991 Description and result of sensitivity test to \np{nn\_isf} are presented in \citet{Mathiot2017}.  
     911 
     912\begin{listing} 
     913  \nlst{namsbc_isf} 
     914  \caption{\forcode{&namsbc_isf}} 
     915  \label{lst:namsbc_isf} 
     916\end{listing} 
     917 
     918The namelist variable in \nam{sbc}{sbc}, \np{nn_isf}{nn\_isf}, controls the ice shelf representation. 
     919Description and result of sensitivity test to \np{nn_isf}{nn\_isf} are presented in \citet{mathiot.jenkins.ea_GMD17}. 
    992920The different options are illustrated in \autoref{fig:SBC_isf}. 
    993921 
    994922\begin{description} 
    995 \item[\np{nn\_isf}\forcode{ = 1}]: 
    996   The ice shelf cavity is represented (\np{ln\_isfcav}\forcode{ = .true.} needed). 
     923  \item [{\np[=1]{nn_isf}{nn\_isf}}]: The ice shelf cavity is represented (\np[=.true.]{ln_isfcav}{ln\_isfcav} needed). 
    997924  The fwf and heat flux are depending of the local water properties. 
     925 
    998926  Two different bulk formulae are available: 
    999927 
    1000    \begin{description} 
    1001    \item[\np{nn\_isfblk}\forcode{ = 1}]: 
    1002      The melt rate is based on a balance between the upward ocean heat flux and 
    1003      the latent heat flux at the ice shelf base. A complete description is available in \citet{Hunter2006}. 
    1004    \item[\np{nn\_isfblk}\forcode{ = 2}]: 
    1005      The melt rate and the heat flux are based on a 3 equations formulation 
    1006      (a heat flux budget at the ice base, a salt flux budget at the ice base and a linearised freezing point temperature equation).  
    1007      A complete description is available in \citet{Jenkins1991}. 
    1008    \end{description} 
    1009  
    1010      Temperature and salinity used to compute the melt are the average temperature in the top boundary layer \citet{Losch2008}.  
    1011      Its thickness is defined by \np{rn\_hisf\_tbl}. 
    1012      The fluxes and friction velocity are computed using the mean temperature, salinity and velocity in the the first \np{rn\_hisf\_tbl} m. 
    1013      Then, the fluxes are spread over the same thickness (ie over one or several cells). 
    1014      If \np{rn\_hisf\_tbl} larger than top $e_{3}t$, there is no more feedback between the freezing point at the interface and the the top cell temperature. 
    1015      This can lead to super-cool temperature in the top cell under melting condition. 
    1016      If \np{rn\_hisf\_tbl} smaller than top $e_{3}t$, the top boundary layer thickness is set to the top cell thickness.\\ 
    1017  
    1018      Each melt bulk formula depends on a exchange coeficient ($\Gamma^{T,S}$) between the ocean and the ice.  
    1019      There are 3 different ways to compute the exchange coeficient: 
    1020    \begin{description} 
    1021         \item[\np{nn\_gammablk}\forcode{ = 0}]: 
    1022      The salt and heat exchange coefficients are constant and defined by \np{rn\_gammas0} and \np{rn\_gammat0}.  
    1023 \[ 
    1024   % \label{eq:sbc_isf_gamma_iso} 
    1025 \gamma^{T} = \np{rn\_gammat0} 
    1026 \] 
    1027 \[ 
    1028 \gamma^{S} = \np{rn\_gammas0} 
    1029 \] 
    1030      This is the recommended formulation for ISOMIP. 
    1031    \item[\np{nn\_gammablk}\forcode{ = 1}]: 
    1032      The salt and heat exchange coefficients are velocity dependent and defined as 
    1033 \[ 
    1034 \gamma^{T} = \np{rn\_gammat0} \times u_{*}  
    1035 \] 
    1036 \[ 
    1037 \gamma^{S} = \np{rn\_gammas0} \times u_{*} 
    1038 \] 
    1039      where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters). 
    1040      See \citet{Jenkins2010} for all the details on this formulation. It is the recommended formulation for realistic application. 
    1041    \item[\np{nn\_gammablk}\forcode{ = 2}]: 
    1042      The salt and heat exchange coefficients are velocity and stability dependent and defined as: 
    1043 \[ 
    1044 \gamma^{T,S} = \frac{u_{*}}{\Gamma_{Turb} + \Gamma^{T,S}_{Mole}}  
    1045 \] 
    1046      where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters), 
    1047      $\Gamma_{Turb}$ the contribution of the ocean stability and 
    1048      $\Gamma^{T,S}_{Mole}$ the contribution of the molecular diffusion. 
    1049      See \citet{Holland1999} for all the details on this formulation.  
    1050      This formulation has not been extensively tested in NEMO (not recommended). 
    1051    \end{description} 
    1052  \item[\np{nn\_isf}\forcode{ = 2}]: 
    1053    The ice shelf cavity is not represented. 
    1054    The fwf and heat flux are computed using the \citet{Beckmann2003} parameterisation of isf melting. 
    1055    The fluxes are distributed along the ice shelf edge between the depth of the average grounding line (GL) 
    1056    (\np{sn\_depmax\_isf}) and the base of the ice shelf along the calving front 
    1057    (\np{sn\_depmin\_isf}) as in (\np{nn\_isf}\forcode{ = 3}). 
    1058    The effective melting length (\np{sn\_Leff\_isf}) is read from a file. 
    1059  \item[\np{nn\_isf}\forcode{ = 3}]: 
    1060    The ice shelf cavity is not represented. 
    1061    The fwf (\np{sn\_rnfisf}) is prescribed and distributed along the ice shelf edge between 
    1062    the depth of the average grounding line (GL) (\np{sn\_depmax\_isf}) and 
    1063    the base of the ice shelf along the calving front (\np{sn\_depmin\_isf}). 
    1064    The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$. 
    1065  \item[\np{nn\_isf}\forcode{ = 4}]: 
    1066    The ice shelf cavity is opened (\np{ln\_isfcav}\forcode{ = .true.} needed). 
    1067    However, the fwf is not computed but specified from file \np{sn\_fwfisf}). 
    1068    The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$. 
    1069    As in \np{nn\_isf}\forcode{ = 1}, the fluxes are spread over the top boundary layer thickness (\np{rn\_hisf\_tbl})\\ 
     928  \begin{description} 
     929  \item [{\np[=1]{nn_isfblk}{nn\_isfblk}}]: The melt rate is based on a balance between the upward ocean heat flux and 
     930    the latent heat flux at the ice shelf base. A complete description is available in \citet{hunter_rpt06}. 
     931  \item [{\np[=2]{nn_isfblk}{nn\_isfblk}}]: The melt rate and the heat flux are based on a 3 equations formulation 
     932    (a heat flux budget at the ice base, a salt flux budget at the ice base and a linearised freezing point temperature equation). 
     933    A complete description is available in \citet{jenkins_JGR91}. 
     934  \end{description} 
     935 
     936  Temperature and salinity used to compute the melt are the average temperature in the top boundary layer \citet{losch_JGR08}. 
     937  Its thickness is defined by \np{rn_hisf_tbl}{rn\_hisf\_tbl}. 
     938  The fluxes and friction velocity are computed using the mean temperature, salinity and velocity in the the first \np{rn_hisf_tbl}{rn\_hisf\_tbl} m. 
     939  Then, the fluxes are spread over the same thickness (ie over one or several cells). 
     940  If \np{rn_hisf_tbl}{rn\_hisf\_tbl} larger than top $e_{3}t$, there is no more feedback between the freezing point at the interface and the the top cell temperature. 
     941  This can lead to super-cool temperature in the top cell under melting condition. 
     942  If \np{rn_hisf_tbl}{rn\_hisf\_tbl} smaller than top $e_{3}t$, the top boundary layer thickness is set to the top cell thickness.\\ 
     943 
     944  Each melt bulk formula depends on a exchange coeficient ($\Gamma^{T,S}$) between the ocean and the ice. 
     945  There are 3 different ways to compute the exchange coeficient: 
     946  \begin{description} 
     947  \item [{\np[=0]{nn_gammablk}{nn\_gammablk}}]: The salt and heat exchange coefficients are constant and defined by \np{rn_gammas0}{rn\_gammas0} and \np{rn_gammat0}{rn\_gammat0}. 
     948    \begin{gather*} 
     949       % \label{eq:SBC_isf_gamma_iso} 
     950      \gamma^{T} = rn\_gammat0 \\ 
     951      \gamma^{S} = rn\_gammas0 
     952    \end{gather*} 
     953    This is the recommended formulation for ISOMIP. 
     954  \item [{\np[=1]{nn_gammablk}{nn\_gammablk}}]: The salt and heat exchange coefficients are velocity dependent and defined as 
     955    \begin{gather*} 
     956      \gamma^{T} = rn\_gammat0 \times u_{*} \\ 
     957      \gamma^{S} = rn\_gammas0 \times u_{*} 
     958    \end{gather*} 
     959    where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn_hisf_tbl}{rn\_hisf\_tbl} meters). 
     960    See \citet{jenkins.nicholls.ea_JPO10} for all the details on this formulation. It is the recommended formulation for realistic application. 
     961  \item [{\np[=2]{nn_gammablk}{nn\_gammablk}}]: The salt and heat exchange coefficients are velocity and stability dependent and defined as: 
     962    \[ 
     963      \gamma^{T,S} = \frac{u_{*}}{\Gamma_{Turb} + \Gamma^{T,S}_{Mole}} 
     964    \] 
     965    where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn_hisf_tbl}{rn\_hisf\_tbl} meters), 
     966    $\Gamma_{Turb}$ the contribution of the ocean stability and 
     967    $\Gamma^{T,S}_{Mole}$ the contribution of the molecular diffusion. 
     968    See \citet{holland.jenkins_JPO99} for all the details on this formulation. 
     969    This formulation has not been extensively tested in \NEMO\ (not recommended). 
     970  \end{description} 
     971\item [{\np[=2]{nn_isf}{nn\_isf}}]: The ice shelf cavity is not represented. 
     972  The fwf and heat flux are computed using the \citet{beckmann.goosse_OM03} parameterisation of isf melting. 
     973  The fluxes are distributed along the ice shelf edge between the depth of the average grounding line (GL) 
     974  (\np{sn_depmax_isf}{sn\_depmax\_isf}) and the base of the ice shelf along the calving front 
     975  (\np{sn_depmin_isf}{sn\_depmin\_isf}) as in (\np[=3]{nn_isf}{nn\_isf}). 
     976  The effective melting length (\np{sn_Leff_isf}{sn\_Leff\_isf}) is read from a file. 
     977\item [{\np[=3]{nn_isf}{nn\_isf}}]: The ice shelf cavity is not represented. 
     978  The fwf (\np{sn_rnfisf}{sn\_rnfisf}) is prescribed and distributed along the ice shelf edge between 
     979  the depth of the average grounding line (GL) (\np{sn_depmax_isf}{sn\_depmax\_isf}) and 
     980  the base of the ice shelf along the calving front (\np{sn_depmin_isf}{sn\_depmin\_isf}). 
     981  The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$. 
     982\item [{\np[=4]{nn_isf}{nn\_isf}}]: The ice shelf cavity is opened (\np[=.true.]{ln_isfcav}{ln\_isfcav} needed). 
     983  However, the fwf is not computed but specified from file \np{sn_fwfisf}{sn\_fwfisf}). 
     984  The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$. 
     985  As in \np[=1]{nn_isf}{nn\_isf}, the fluxes are spread over the top boundary layer thickness (\np{rn_hisf_tbl}{rn\_hisf\_tbl}) 
    1070986\end{description} 
    1071987 
    1072 $\bullet$ \np{nn\_isf}\forcode{ = 1} and \np{nn\_isf}\forcode{ = 2} compute a melt rate based on 
     988$\bullet$ \np[=1]{nn_isf}{nn\_isf} and \np[=2]{nn_isf}{nn\_isf} compute a melt rate based on 
    1073989the water mass properties, ocean velocities and depth. 
    1074990This flux is thus highly dependent of the model resolution (horizontal and vertical), 
    1075991realism of the water masses onto the shelf ...\\ 
    1076992 
    1077 $\bullet$ \np{nn\_isf}\forcode{ = 3} and \np{nn\_isf}\forcode{ = 4} read the melt rate from a file. 
     993$\bullet$ \np[=3]{nn_isf}{nn\_isf} and \np[=4]{nn_isf}{nn\_isf} read the melt rate from a file. 
    1078994You have total control of the fwf forcing. 
    1079995This can be useful if the water masses on the shelf are not realistic or 
    1080996the resolution (horizontal/vertical) are too coarse to have realistic melting or 
    1081 for studies where you need to control your heat and fw input.\\  
     997for studies where you need to control your heat and fw input.\\ 
    1082998 
    1083999The ice shelf melt is implemented as a volume flux as for the runoff. 
     
    10861002See the runoff section \autoref{sec:SBC_rnf} for all the details about the divergence correction.\\ 
    10871003 
    1088 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    10891004\begin{figure}[!t] 
    1090   \begin{center} 
    1091     \includegraphics[width=0.8\textwidth]{Fig_SBC_isf} 
    1092     \caption{ 
    1093       \protect\label{fig:SBC_isf} 
    1094       Illustration the location where the fwf is injected and whether or not the fwf is interactif or not depending of \np{nn\_isf}. 
    1095     } 
    1096   \end{center} 
     1005  \centering 
     1006  \includegraphics[width=0.66\textwidth]{SBC_isf} 
     1007  \caption[Ice shelf location and fresh water flux definition]{ 
     1008    Illustration of the location where the fwf is injected and 
     1009    whether or not the fwf is interactif or not depending of \protect\np{nn_isf}{nn\_isf}.} 
     1010  \label{fig:SBC_isf} 
    10971011\end{figure} 
    1098 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1099  
     1012 
     1013%% ================================================================================================= 
    11001014\section{Ice sheet coupling} 
    11011015\label{sec:SBC_iscpl} 
    1102 %------------------------------------------namsbc_iscpl---------------------------------------------------- 
    1103  
    1104 \nlst{namsbc_iscpl} 
    1105 %-------------------------------------------------------------------------------------------------------- 
     1016 
     1017\begin{listing} 
     1018  \nlst{namsbc_iscpl} 
     1019  \caption{\forcode{&namsbc_iscpl}} 
     1020  \label{lst:namsbc_iscpl} 
     1021\end{listing} 
     1022 
    11061023Ice sheet/ocean coupling is done through file exchange at the restart step. 
    11071024At each restart step: 
    1108 \begin{description} 
    1109 \item[Step 1]: the ice sheet model send a new bathymetry and ice shelf draft netcdf file. 
    1110 \item[Step 2]: a new domcfg.nc file is built using the DOMAINcfg tools. 
    1111 \item[Step 3]: NEMO run for a specific period and output the average melt rate over the period. 
    1112 \item[Step 4]: the ice sheet model run using the melt rate outputed in step 4. 
    1113 \item[Step 5]: go back to 1. 
    1114 \end{description} 
    1115  
    1116 If \np{ln\_iscpl}\forcode{ = .true.}, the isf draft is assume to be different at each restart step with 
     1025 
     1026\begin{enumerate} 
     1027\item the ice sheet model send a new bathymetry and ice shelf draft netcdf file. 
     1028\item a new domcfg.nc file is built using the DOMAINcfg tools. 
     1029\item \NEMO\ run for a specific period and output the average melt rate over the period. 
     1030\item the ice sheet model run using the melt rate outputed in step 4. 
     1031\item go back to 1. 
     1032\end{enumerate} 
     1033 
     1034If \np[=.true.]{ln_iscpl}{ln\_iscpl}, the isf draft is assume to be different at each restart step with 
    11171035potentially some new wet/dry cells due to the ice sheet dynamics/thermodynamics. 
    11181036The wetting and drying scheme applied on the restart is very simple and described below for the 6 different possible cases: 
     1037 
    11191038\begin{description} 
    1120 \item[Thin a cell down]: 
    1121   T/S/ssh are unchanged and U/V in the top cell are corrected to keep the barotropic transport (bt) constant 
     1039\item [Thin a cell down]: T/S/ssh are unchanged and U/V in the top cell are corrected to keep the barotropic transport (bt) constant 
    11221040  ($bt_b=bt_n$). 
    1123 \item[Enlarge  a cell]: 
    1124   See case "Thin a cell down" 
    1125 \item[Dry a cell]: 
    1126   mask, T/S, U/V and ssh are set to 0. 
     1041\item [Enlarge  a cell]: See case "Thin a cell down" 
     1042\item [Dry a cell]: mask, T/S, U/V and ssh are set to 0. 
    11271043  Furthermore, U/V into the water column are modified to satisfy ($bt_b=bt_n$). 
    1128 \item[Wet a cell]:  
    1129   mask is set to 1, T/S is extrapolated from neighbours, $ssh_n = ssh_b$ and U/V set to 0. 
    1130   If no neighbours, T/S is extrapolated from old top cell value.  
     1044\item [Wet a cell]: mask is set to 1, T/S is extrapolated from neighbours, $ssh_n = ssh_b$ and U/V set to 0. 
     1045  If no neighbours, T/S is extrapolated from old top cell value. 
    11311046  If no neighbours along i,j and k (both previous test failed), T/S/U/V/ssh and mask are set to 0. 
    1132 \item[Dry a column]: 
    1133    mask, T/S, U/V are set to 0 everywhere in the column and ssh set to 0. 
    1134 \item[Wet a column]: 
    1135   set mask to 1, T/S is extrapolated from neighbours, ssh is extrapolated from neighbours and U/V set to 0. 
     1047\item [Dry a column]: mask, T/S, U/V are set to 0 everywhere in the column and ssh set to 0. 
     1048\item [Wet a column]: set mask to 1, T/S is extrapolated from neighbours, ssh is extrapolated from neighbours and U/V set to 0. 
    11361049  If no neighbour, T/S/U/V and mask set to 0. 
    11371050\end{description} 
     
    11401053the restart time step is prescribed to be an euler time step instead of a leap frog and $fields_b = fields_n$.\\ 
    11411054 
    1142 The horizontal extrapolation to fill new cell with realistic value is called \np{nn\_drown} times. 
    1143 It means that if the grounding line retreat by more than \np{nn\_drown} cells between 2 coupling steps, 
     1055The horizontal extrapolation to fill new cell with realistic value is called \np{nn_drown}{nn\_drown} times. 
     1056It means that if the grounding line retreat by more than \np{nn_drown}{nn\_drown} cells between 2 coupling steps, 
    11441057the code will be unable to fill all the new wet cells properly. 
    11451058The default number is set up for the MISOMIP idealised experiments. 
    11461059This coupling procedure is able to take into account grounding line and calving front migration. 
    1147 However, it is a non-conservative processe.  
     1060However, it is a non-conservative processe. 
    11481061This could lead to a trend in heat/salt content and volume.\\ 
    11491062 
    11501063In order to remove the trend and keep the conservation level as close to 0 as possible, 
    1151 a simple conservation scheme is available with \np{ln\_hsb}\forcode{ = .true.}. 
     1064a simple conservation scheme is available with \np[=.true.]{ln_hsb}{ln\_hsb}. 
    11521065The heat/salt/vol. gain/loss is diagnosed, as well as the location. 
    1153 A correction increment is computed and apply each time step during the next \np{rn\_fiscpl} time steps.  
    1154 For safety, it is advised to set \np{rn\_fiscpl} equal to the coupling period (smallest increment possible). 
     1066A correction increment is computed and apply each time step during the next \np{rn_fiscpl}{rn\_fiscpl} time steps. 
     1067For safety, it is advised to set \np{rn_fiscpl}{rn\_fiscpl} equal to the coupling period (smallest increment possible). 
    11551068The 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). 
    11561069 
    1157 % 
    1158 % ================================================================ 
    1159 %        Handling of icebergs 
    1160 % ================================================================ 
     1070%% ================================================================================================= 
    11611071\section{Handling of icebergs (ICB)} 
    1162 \label{sec:ICB_icebergs} 
    1163 %------------------------------------------namberg---------------------------------------------------- 
    1164  
    1165 \nlst{namberg} 
    1166 %------------------------------------------------------------------------------------------------------------- 
    1167  
    1168 Icebergs are modelled as lagrangian particles in NEMO \citep{Marsh_GMD2015}. 
    1169 Their physical behaviour is controlled by equations as described in \citet{Martin_Adcroft_OM10} ). 
    1170 (Note that the authors kindly provided a copy of their code to act as a basis for implementation in NEMO). 
     1072\label{sec:SBC_ICB_icebergs} 
     1073 
     1074\begin{listing} 
     1075  \nlst{namberg} 
     1076  \caption{\forcode{&namberg}} 
     1077  \label{lst:namberg} 
     1078\end{listing} 
     1079 
     1080Icebergs are modelled as lagrangian particles in \NEMO\ \citep{marsh.ivchenko.ea_GMD15}. 
     1081Their physical behaviour is controlled by equations as described in \citet{martin.adcroft_OM10} ). 
     1082(Note that the authors kindly provided a copy of their code to act as a basis for implementation in \NEMO). 
    11711083Icebergs are initially spawned into one of ten classes which have specific mass and thickness as 
    1172 described in the \ngn{namberg} namelist: \np{rn\_initial\_mass} and \np{rn\_initial\_thickness}. 
    1173 Each class has an associated scaling (\np{rn\_mass\_scaling}), 
     1084described in the \nam{berg}{berg} namelist: \np{rn_initial_mass}{rn\_initial\_mass} and \np{rn_initial_thickness}{rn\_initial\_thickness}. 
     1085Each class has an associated scaling (\np{rn_mass_scaling}{rn\_mass\_scaling}), 
    11741086which is an integer representing how many icebergs of this class are being described as one lagrangian point 
    11751087(this reduces the numerical problem of tracking every single iceberg). 
    1176 They are enabled by setting \np{ln\_icebergs}\forcode{ = .true.}. 
     1088They are enabled by setting \np[=.true.]{ln_icebergs}{ln\_icebergs}. 
    11771089 
    11781090Two initialisation schemes are possible. 
    11791091\begin{description} 
    1180 \item[\np{nn\_test\_icebergs}~$>$~0] 
    1181   In this scheme, the value of \np{nn\_test\_icebergs} represents the class of iceberg to generate 
    1182   (so between 1 and 10), and \np{nn\_test\_icebergs} provides a lon/lat box in the domain at each grid point of 
     1092\item [{\np{nn_test_icebergs}{nn\_test\_icebergs}~$>$~0}] In this scheme, the value of \np{nn_test_icebergs}{nn\_test\_icebergs} represents the class of iceberg to generate 
     1093  (so between 1 and 10), and \np{nn_test_icebergs}{nn\_test\_icebergs} provides a lon/lat box in the domain at each grid point of 
    11831094  which an iceberg is generated at the beginning of the run. 
    1184   (Note that this happens each time the timestep equals \np{nn\_nit000}.) 
    1185   \np{nn\_test\_icebergs} is defined by four numbers in \np{nn\_test\_box} representing the corners of 
     1095  (Note that this happens each time the timestep equals \np{nn_nit000}{nn\_nit000}.) 
     1096  \np{nn_test_icebergs}{nn\_test\_icebergs} is defined by four numbers in \np{nn_test_box}{nn\_test\_box} representing the corners of 
    11861097  the geographical box: lonmin,lonmax,latmin,latmax 
    1187 \item[\np{nn\_test\_icebergs}\forcode{ = -1}] 
    1188   In this scheme the model reads a calving file supplied in the \np{sn\_icb} parameter. 
     1098\item [{\np[=-1]{nn_test_icebergs}{nn\_test\_icebergs}}] In this scheme, the model reads a calving file supplied in the \np{sn_icb}{sn\_icb} parameter. 
    11891099  This should be a file with a field on the configuration grid (typically ORCA) 
    11901100  representing ice accumulation rate at each model point. 
     
    11941104  At each time step, a test is performed to see if there is enough ice mass to 
    11951105  calve an iceberg of each class in order (1 to 10). 
    1196   Note that this is the initial mass multiplied by the number each particle represents (\ie the scaling). 
     1106  Note that this is the initial mass multiplied by the number each particle represents (\ie\ the scaling). 
    11971107  If there is enough ice, a new iceberg is spawned and the total available ice reduced accordingly. 
    11981108\end{description} 
     
    12011111The latter act to disintegrate the iceberg. 
    12021112This is either all melted freshwater, 
    1203 or (if \np{rn\_bits\_erosion\_fraction}~$>$~0) into melt and additionally small ice bits 
     1113or (if \np{rn_bits_erosion_fraction}{rn\_bits\_erosion\_fraction}~$>$~0) into melt and additionally small ice bits 
    12041114which are assumed to propagate with their larger parent and thus delay fluxing into the ocean. 
    1205 Melt water (and other variables on the configuration grid) are written into the main NEMO model output files. 
     1115Melt water (and other variables on the configuration grid) are written into the main \NEMO\ model output files. 
    12061116 
    12071117Extensive diagnostics can be produced. 
    12081118Separate output files are maintained for human-readable iceberg information. 
    1209 A separate file is produced for each processor (independent of \np{ln\_ctl}). 
     1119A separate file is produced for each processor (independent of \np{ln_ctl}{ln\_ctl}). 
    12101120The amount of information is controlled by two integer parameters: 
    12111121\begin{description} 
    1212 \item[\np{nn\_verbose\_level}] takes a value between one and four and 
     1122\item [{\np{nn_verbose_level}{nn\_verbose\_level}}] takes a value between one and four and 
    12131123  represents an increasing number of points in the code at which variables are written, 
    12141124  and an increasing level of obscurity. 
    1215 \item[\np{nn\_verbose\_write}] is the number of timesteps between writes 
     1125\item [{\np{nn_verbose_write}{nn\_verbose\_write}}] is the number of timesteps between writes 
    12161126\end{description} 
    12171127 
    1218 Iceberg trajectories can also be written out and this is enabled by setting \np{nn\_sample\_rate}~$>$~0. 
     1128Iceberg trajectories can also be written out and this is enabled by setting \np{nn_sample_rate}{nn\_sample\_rate}~$>$~0. 
    12191129A non-zero value represents how many timesteps between writes of information into the output file. 
    12201130These output files are in NETCDF format. 
     
    12241134since its trajectory data may be spread across multiple files. 
    12251135 
    1226 % ------------------------------------------------------------------------------------------------------------- 
    1227 %        Interactions with waves (sbcwave.F90, ln_wave) 
    1228 % ------------------------------------------------------------------------------------------------------------- 
    1229 \section{Interactions with waves (\protect\mdl{sbcwave}, \protect\np{ln\_wave})} 
     1136%% ================================================================================================= 
     1137\section[Interactions with waves (\textit{sbcwave.F90}, \forcode{ln_wave})]{Interactions with waves (\protect\mdl{sbcwave}, \protect\np{ln_wave}{ln\_wave})} 
    12301138\label{sec:SBC_wave} 
    1231 %------------------------------------------namsbc_wave-------------------------------------------------------- 
    1232  
    1233 \nlst{namsbc_wave} 
    1234 %------------------------------------------------------------------------------------------------------------- 
    1235  
    1236 Ocean waves represent the interface between the ocean and the atmosphere, so NEMO is extended to incorporate  
    1237 physical processes related to ocean surface waves, namely the surface stress modified by growth and  
    1238 dissipation of the oceanic wave field, the Stokes-Coriolis force and the Stokes drift impact on mass and  
    1239 tracer advection; moreover the neutral surface drag coefficient from a wave model can be used to evaluate  
     1139 
     1140\begin{listing} 
     1141  \nlst{namsbc_wave} 
     1142  \caption{\forcode{&namsbc_wave}} 
     1143  \label{lst:namsbc_wave} 
     1144\end{listing} 
     1145 
     1146Ocean waves represent the interface between the ocean and the atmosphere, so \NEMO\ is extended to incorporate 
     1147physical processes related to ocean surface waves, namely the surface stress modified by growth and 
     1148dissipation of the oceanic wave field, the Stokes-Coriolis force and the Stokes drift impact on mass and 
     1149tracer advection; moreover the neutral surface drag coefficient from a wave model can be used to evaluate 
    12401150the wind stress. 
    12411151 
    1242 Physical processes related to ocean surface waves can be accounted by setting the logical variable  
    1243 \np{ln\_wave}\forcode{= .true.} in \ngn{namsbc} namelist. In addition, specific flags accounting for  
    1244 different porcesses should be activated as explained in the following sections. 
     1152Physical processes related to ocean surface waves can be accounted by setting the logical variable 
     1153\np[=.true.]{ln_wave}{ln\_wave} in \nam{sbc}{sbc} namelist. In addition, specific flags accounting for 
     1154different processes should be activated as explained in the following sections. 
    12451155 
    12461156Wave fields can be provided either in forced or coupled mode: 
    12471157\begin{description} 
    1248 \item[forced mode]: wave fields should be defined through the \ngn{namsbc\_wave} namelist  
    1249 for external data names, locations, frequency, interpolation and all the miscellanous options allowed by  
    1250 Input Data generic Interface (see \autoref{sec:SBC_input}).  
    1251 \item[coupled mode]: NEMO and an external wave model can be coupled by setting \np{ln\_cpl} \forcode{= .true.}  
    1252 in \ngn{namsbc} namelist and filling the \ngn{namsbc\_cpl} namelist. 
     1158\item [forced mode]: wave fields should be defined through the \nam{sbc_wave}{sbc\_wave} namelist 
     1159for external data names, locations, frequency, interpolation and all the miscellanous options allowed by 
     1160Input Data generic Interface (see \autoref{sec:SBC_input}). 
     1161\item [coupled mode]: \NEMO\ and an external wave model can be coupled by setting \np[=.true.]{ln_cpl}{ln\_cpl} 
     1162in \nam{sbc}{sbc} namelist and filling the \nam{sbc_cpl}{sbc\_cpl} namelist. 
    12531163\end{description} 
    12541164 
    1255  
    1256 % ================================================================ 
    1257 % Neutral drag coefficient from wave model (ln_cdgw) 
    1258  
    1259 % ================================================================ 
    1260 \subsection{Neutral drag coefficient from wave model (\protect\np{ln\_cdgw})} 
     1165%% ================================================================================================= 
     1166\subsection[Neutral drag coefficient from wave model (\forcode{ln_cdgw})]{Neutral drag coefficient from wave model (\protect\np{ln_cdgw}{ln\_cdgw})} 
    12611167\label{subsec:SBC_wave_cdgw} 
    12621168 
    1263 The neutral surface drag coefficient provided from an external data source (\ie a wave model),  
    1264 can be used by setting the logical variable \np{ln\_cdgw} \forcode{= .true.} in \ngn{namsbc} namelist.  
    1265 Then using the routine \rou{turb\_ncar} and starting from the neutral drag coefficent provided,  
    1266 the drag coefficient is computed according to the stable/unstable conditions of the  
    1267 air-sea interface following \citet{Large_Yeager_Rep04}.  
    1268  
    1269  
    1270 % ================================================================ 
    1271 % 3D Stokes Drift (ln_sdw, nn_sdrift) 
    1272 % ================================================================ 
    1273 \subsection{3D Stokes Drift (\protect\np{ln\_sdw, nn\_sdrift})} 
     1169The neutral surface drag coefficient provided from an external data source (\ie\ a wave model), 
     1170can be used by setting the logical variable \np[=.true.]{ln_cdgw}{ln\_cdgw} in \nam{sbc}{sbc} namelist. 
     1171Then using the routine \rou{sbcblk\_algo\_ncar} and starting from the neutral drag coefficent provided, 
     1172the drag coefficient is computed according to the stable/unstable conditions of the 
     1173air-sea interface following \citet{large.yeager_rpt04}. 
     1174 
     1175%% ================================================================================================= 
     1176\subsection[3D Stokes Drift (\forcode{ln_sdw} \& \forcode{nn_sdrift})]{3D Stokes Drift (\protect\np{ln_sdw}{ln\_sdw} \& \np{nn_sdrift}{nn\_sdrift})} 
    12741177\label{subsec:SBC_wave_sdw} 
    12751178 
    1276 The Stokes drift is a wave driven mechanism of mass and momentum transport \citep{Stokes_1847}.  
    1277 It is defined as the difference between the average velocity of a fluid parcel (Lagrangian velocity)  
    1278 and the current measured at a fixed point (Eulerian velocity).  
    1279 As waves travel, the water particles that make up the waves travel in orbital motions but  
    1280 without a closed path. Their movement is enhanced at the top of the orbit and slowed slightly  
    1281 at the bottom so the result is a net forward motion of water particles, referred to as the Stokes drift.  
    1282 An accurate evaluation of the Stokes drift and the inclusion of related processes may lead to improved  
    1283 representation of surface physics in ocean general circulation models. 
    1284 The Stokes drift velocity $\mathbf{U}_{st}$ in deep water can be computed from the wave spectrum and may be written as:  
     1179The Stokes drift is a wave driven mechanism of mass and momentum transport \citep{stokes_ibk09}. 
     1180It is defined as the difference between the average velocity of a fluid parcel (Lagrangian velocity) 
     1181and the current measured at a fixed point (Eulerian velocity). 
     1182As waves travel, the water particles that make up the waves travel in orbital motions but 
     1183without a closed path. Their movement is enhanced at the top of the orbit and slowed slightly 
     1184at the bottom, so the result is a net forward motion of water particles, referred to as the Stokes drift. 
     1185An accurate evaluation of the Stokes drift and the inclusion of related processes may lead to improved 
     1186representation of surface physics in ocean general circulation models. %GS: reference needed 
     1187The Stokes drift velocity $\mathbf{U}_{st}$ in deep water can be computed from the wave spectrum and may be written as: 
    12851188 
    12861189\[ 
    1287   % \label{eq:sbc_wave_sdw} 
     1190  % \label{eq:SBC_wave_sdw} 
    12881191  \mathbf{U}_{st} = \frac{16{\pi^3}} {g} 
    12891192  \int_0^\infty \int_{-\pi}^{\pi} (cos{\theta},sin{\theta}) {f^3} 
     
    12911194\] 
    12921195 
    1293 where: ${\theta}$ is the wave direction, $f$ is the wave intrinsic frequency,  
    1294 $\mathrm{S}($f$,\theta)$ is the 2D frequency-direction spectrum,  
    1295 $k$ is the mean wavenumber defined as:  
     1196where: ${\theta}$ is the wave direction, $f$ is the wave intrinsic frequency, 
     1197$\mathrm{S}($f$,\theta)$ is the 2D frequency-direction spectrum, 
     1198$k$ is the mean wavenumber defined as: 
    12961199$k=\frac{2\pi}{\lambda}$ (being $\lambda$ the wavelength). \\ 
    12971200 
    1298 In order to evaluate the Stokes drift in a realistic ocean wave field the wave spectral shape is required  
    1299 and its computation quickly becomes expensive as the 2D spectrum must be integrated for each vertical level.  
     1201In order to evaluate the Stokes drift in a realistic ocean wave field, the wave spectral shape is required 
     1202and its computation quickly becomes expensive as the 2D spectrum must be integrated for each vertical level. 
    13001203To simplify, it is customary to use approximations to the full Stokes profile. 
    1301 Three possible parameterizations for the calculation for the approximate Stokes drift velocity profile  
    1302 are included in the code through the \np{nn\_sdrift} parameter once provided the surface Stokes drift  
    1303 $\mathbf{U}_{st |_{z=0}}$ which is evaluated by an external wave model that accurately reproduces the wave spectra  
    1304 and makes possible the estimation of the surface Stokes drift for random directional waves in  
     1204Three possible parameterizations for the calculation for the approximate Stokes drift velocity profile 
     1205are included in the code through the \np{nn_sdrift}{nn\_sdrift} parameter once provided the surface Stokes drift 
     1206$\mathbf{U}_{st |_{z=0}}$ which is evaluated by an external wave model that accurately reproduces the wave spectra 
     1207and makes possible the estimation of the surface Stokes drift for random directional waves in 
    13051208realistic wave conditions: 
    13061209 
    13071210\begin{description} 
    1308 \item[\np{nn\_sdrift} = 0]: exponential integral profile parameterization proposed by  
    1309 \citet{Breivik_al_JPO2014}: 
     1211\item [{\np{nn_sdrift}{nn\_sdrift} = 0}]: exponential integral profile parameterization proposed by 
     1212\citet{breivik.janssen.ea_JPO14}: 
    13101213 
    13111214\[ 
    1312   % \label{eq:sbc_wave_sdw_0a} 
    1313   \mathbf{U}_{st} \cong \mathbf{U}_{st |_{z=0}} \frac{\mathrm{e}^{-2k_ez}} {1-8k_ez}  
     1215  % \label{eq:SBC_wave_sdw_0a} 
     1216  \mathbf{U}_{st} \cong \mathbf{U}_{st |_{z=0}} \frac{\mathrm{e}^{-2k_ez}} {1-8k_ez} 
    13141217\] 
    13151218 
     
    13171220 
    13181221\[ 
    1319   % \label{eq:sbc_wave_sdw_0b} 
     1222  % \label{eq:SBC_wave_sdw_0b} 
    13201223  k_e = \frac{|\mathbf{U}_{\left.st\right|_{z=0}}|} {|T_{st}|} 
    13211224  \quad \text{and }\ 
    1322   T_{st} = \frac{1}{16} \bar{\omega} H_s^2  
     1225  T_{st} = \frac{1}{16} \bar{\omega} H_s^2 
    13231226\] 
    13241227 
    13251228where $H_s$ is the significant wave height and $\omega$ is the wave frequency. 
    13261229 
    1327 \item[\np{nn\_sdrift} = 1]: velocity profile based on the Phillips spectrum which is considered to be a  
    1328 reasonable estimate of the part of the spectrum most contributing to the Stokes drift velocity near the surface 
    1329 \citep{Breivik_al_OM2016}: 
     1230\item [{\np{nn_sdrift}{nn\_sdrift} = 1}]: velocity profile based on the Phillips spectrum which is considered to be a 
     1231reasonable estimate of the part of the spectrum mostly contributing to the Stokes drift velocity near the surface 
     1232\citep{breivik.bidlot.ea_OM16}: 
    13301233 
    13311234\[ 
    1332   % \label{eq:sbc_wave_sdw_1} 
     1235  % \label{eq:SBC_wave_sdw_1} 
    13331236  \mathbf{U}_{st} \cong \mathbf{U}_{st |_{z=0}} \Big[exp(2k_pz)-\beta \sqrt{-2 \pi k_pz} 
    13341237  \textit{ erf } \Big(\sqrt{-2 k_pz}\Big)\Big] 
     
    13371240where $erf$ is the complementary error function and $k_p$ is the peak wavenumber. 
    13381241 
    1339 \item[\np{nn\_sdrift} = 2]: velocity profile based on the Phillips spectrum as for \np{nn\_sdrift} = 1  
     1242\item [{\np{nn_sdrift}{nn\_sdrift} = 2}]: velocity profile based on the Phillips spectrum as for \np{nn_sdrift}{nn\_sdrift} = 1 
    13401243but using the wave frequency from a wave model. 
    13411244 
    13421245\end{description} 
    13431246 
    1344 The Stokes drift enters the wave-averaged momentum equation, as well as the tracer advection equations  
    1345 and its effect on the evolution of the sea-surface height ${\eta}$ is considered as follows:  
     1247The Stokes drift enters the wave-averaged momentum equation, as well as the tracer advection equations 
     1248and its effect on the evolution of the sea-surface height ${\eta}$ is considered as follows: 
    13461249 
    13471250\[ 
    1348   % \label{eq:sbc_wave_eta_sdw} 
     1251  % \label{eq:SBC_wave_eta_sdw} 
    13491252  \frac{\partial{\eta}}{\partial{t}} = 
    13501253  -\nabla_h \int_{-H}^{\eta} (\mathbf{U} + \mathbf{U}_{st}) dz 
    13511254\] 
    13521255 
    1353 The tracer advection equation is also modified in order for Eulerian ocean models to properly account  
    1354 for unresolved wave effect. The divergence of the wave tracer flux equals the mean tracer advection  
    1355 that is induced by the three-dimensional Stokes velocity.  
    1356 The advective equation for a tracer $c$ combining the effects of the mean current and sea surface waves  
    1357 can be formulated as follows:  
     1256The tracer advection equation is also modified in order for Eulerian ocean models to properly account 
     1257for unresolved wave effect. The divergence of the wave tracer flux equals the mean tracer advection 
     1258that is induced by the three-dimensional Stokes velocity. 
     1259The advective equation for a tracer $c$ combining the effects of the mean current and sea surface waves 
     1260can be formulated as follows: 
    13581261 
    13591262\[ 
    1360   % \label{eq:sbc_wave_tra_sdw} 
     1263  % \label{eq:SBC_wave_tra_sdw} 
    13611264  \frac{\partial{c}}{\partial{t}} = 
    13621265  - (\mathbf{U} + \mathbf{U}_{st}) \cdot \nabla{c} 
    13631266\] 
    13641267 
    1365  
    1366 % ================================================================ 
    1367 % Stokes-Coriolis term (ln_stcor) 
    1368 % ================================================================ 
    1369 \subsection{Stokes-Coriolis term (\protect\np{ln\_stcor})} 
     1268%% ================================================================================================= 
     1269\subsection[Stokes-Coriolis term (\forcode{ln_stcor})]{Stokes-Coriolis term (\protect\np{ln_stcor}{ln\_stcor})} 
    13701270\label{subsec:SBC_wave_stcor} 
    13711271 
    1372 In a rotating ocean, waves exert a wave-induced stress on the mean ocean circulation which results  
    1373 in a force equal to $\mathbf{U}_{st}$×$f$, where $f$ is the Coriolis parameter.  
    1374 This additional force may have impact on the Ekman turning of the surface current.  
    1375 In order to include this term, once evaluated the Stokes drift (using one of the 3 possible  
    1376 approximations described in \autoref{subsec:SBC_wave_sdw}),  
    1377 \np{ln\_stcor}\forcode{ = .true.} has to be set. 
    1378  
    1379  
    1380 % ================================================================ 
    1381 % Waves modified stress (ln_tauwoc, ln_tauw) 
    1382 % ================================================================ 
    1383 \subsection{Wave modified sress (\protect\np{ln\_tauwoc, ln\_tauw})}  
     1272In a rotating ocean, waves exert a wave-induced stress on the mean ocean circulation which results 
     1273in a force equal to $\mathbf{U}_{st}$×$f$, where $f$ is the Coriolis parameter. 
     1274This additional force may have impact on the Ekman turning of the surface current. 
     1275In order to include this term, once evaluated the Stokes drift (using one of the 3 possible 
     1276approximations described in \autoref{subsec:SBC_wave_sdw}), 
     1277\np[=.true.]{ln_stcor}{ln\_stcor} has to be set. 
     1278 
     1279%% ================================================================================================= 
     1280\subsection[Wave modified stress (\forcode{ln_tauwoc} \& \forcode{ln_tauw})]{Wave modified sress (\protect\np{ln_tauwoc}{ln\_tauwoc} \& \np{ln_tauw}{ln\_tauw})} 
    13841281\label{subsec:SBC_wave_tauw} 
    13851282 
    1386 The surface stress felt by the ocean is the atmospheric stress minus the net stress going  
    1387 into the waves \citep{Janssen_al_TM13}. Therefore, when waves are growing, momentum and energy is spent and is not  
    1388 available for forcing the mean circulation, while in the opposite case of a decaying sea  
    1389 state more momentum is available for forcing the ocean.  
    1390 Only when the sea state is in equilibrium the ocean is forced by the atmospheric stress,  
    1391 but in practice an equilibrium sea state is a fairly rare event.  
    1392 So the atmospheric stress felt by the ocean circulation $\tau_{oc,a}$ can be expressed as:  
     1283The surface stress felt by the ocean is the atmospheric stress minus the net stress going 
     1284into the waves \citep{janssen.breivik.ea_rpt13}. Therefore, when waves are growing, momentum and energy is spent and is not 
     1285available for forcing the mean circulation, while in the opposite case of a decaying sea 
     1286state, more momentum is available for forcing the ocean. 
     1287Only when the sea state is in equilibrium, the ocean is forced by the atmospheric stress, 
     1288but in practice, an equilibrium sea state is a fairly rare event. 
     1289So the atmospheric stress felt by the ocean circulation $\tau_{oc,a}$ can be expressed as: 
    13931290 
    13941291\[ 
    1395   % \label{eq:sbc_wave_tauoc} 
     1292  % \label{eq:SBC_wave_tauoc} 
    13961293  \tau_{oc,a} = \tau_a - \tau_w 
    13971294\] 
     
    14011298 
    14021299\[ 
    1403   % \label{eq:sbc_wave_tauw} 
     1300  % \label{eq:SBC_wave_tauw} 
    14041301  \tau_w = \rho g \int {\frac{dk}{c_p} (S_{in}+S_{nl}+S_{diss})} 
    14051302\] 
    14061303 
    14071304where: $c_p$ is the phase speed of the gravity waves, 
    1408 $S_{in}$, $S_{nl}$ and $S_{diss}$ are three source terms that represent  
    1409 the physics of ocean waves. The first one, $S_{in}$, describes the generation  
    1410 of ocean waves by wind and therefore represents the momentum and energy transfer  
    1411 from air to ocean waves; the second term $S_{nl}$ denotes  
    1412 the nonlinear transfer by resonant four-wave interactions; while the third term $S_{diss}$  
    1413 describes the dissipation of waves by processes such as white-capping, large scale breaking  
     1305$S_{in}$, $S_{nl}$ and $S_{diss}$ are three source terms that represent 
     1306the physics of ocean waves. The first one, $S_{in}$, describes the generation 
     1307of ocean waves by wind and therefore represents the momentum and energy transfer 
     1308from air to ocean waves; the second term $S_{nl}$ denotes 
     1309the nonlinear transfer by resonant four-wave interactions; while the third term $S_{diss}$ 
     1310describes the dissipation of waves by processes such as white-capping, large scale breaking 
    14141311eddy-induced damping. 
    14151312 
    1416 The wave stress derived from an external wave model can be provided either through the normalized  
    1417 wave stress into the ocean by setting \np{ln\_tauwoc}\forcode{ = .true.}, or through the zonal and  
    1418 meridional stress components by setting \np{ln\_tauw}\forcode{ = .true.}. 
    1419  
    1420  
    1421 % ================================================================ 
    1422 % Miscellanea options 
    1423 % ================================================================ 
     1313The wave stress derived from an external wave model can be provided either through the normalized 
     1314wave stress into the ocean by setting \np[=.true.]{ln_tauwoc}{ln\_tauwoc}, or through the zonal and 
     1315meridional stress components by setting \np[=.true.]{ln_tauw}{ln\_tauw}. 
     1316 
     1317%% ================================================================================================= 
    14241318\section{Miscellaneous options} 
    14251319\label{sec:SBC_misc} 
    14261320 
    1427 % ------------------------------------------------------------------------------------------------------------- 
    1428 %        Diurnal cycle 
    1429 % ------------------------------------------------------------------------------------------------------------- 
    1430 \subsection{Diurnal cycle (\protect\mdl{sbcdcy})} 
     1321%% ================================================================================================= 
     1322\subsection[Diurnal cycle (\textit{sbcdcy.F90})]{Diurnal cycle (\protect\mdl{sbcdcy})} 
    14311323\label{subsec:SBC_dcy} 
    1432 %------------------------------------------namsbc_rnf---------------------------------------------------- 
    1433 % 
    1434 \nlst{namsbc}  
    1435 %------------------------------------------------------------------------------------------------------------- 
    1436  
    1437 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     1324 
    14381325\begin{figure}[!t] 
    1439   \begin{center} 
    1440     \includegraphics[width=0.8\textwidth]{Fig_SBC_diurnal} 
    1441     \caption{ 
    1442       \protect\label{fig:SBC_diurnal} 
    1443       Example of recontruction of the diurnal cycle variation of short wave flux from daily mean values. 
    1444       The reconstructed diurnal cycle (black line) is chosen as 
    1445       the mean value of the analytical cycle (blue line) over a time step, 
    1446       not as the mid time step value of the analytically cycle (red square). 
    1447       From \citet{Bernie_al_CD07}. 
    1448     } 
    1449   \end{center} 
     1326  \centering 
     1327  \includegraphics[width=0.66\textwidth]{SBC_diurnal} 
     1328  \caption[Reconstruction of the diurnal cycle variation of short wave flux]{ 
     1329    Example of reconstruction of the diurnal cycle variation of short wave flux from 
     1330    daily mean values. 
     1331    The reconstructed diurnal cycle (black line) is chosen as 
     1332    the mean value of the analytical cycle (blue line) over a time step, 
     1333    not as the mid time step value of the analytically cycle (red square). 
     1334    From \citet{bernie.guilyardi.ea_CD07}.} 
     1335  \label{fig:SBC_diurnal} 
    14501336\end{figure} 
    1451 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1452  
    1453 \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. 
    1454 Unfortunately high frequency forcing fields are rare, not to say inexistent. 
    1455 Nevertheless, it is possible to obtain a reasonable diurnal cycle of the SST knowning only short wave flux (SWF) at 
    1456 high frequency \citep{Bernie_al_CD07}. 
     1337 
     1338\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. 
     1339%Unfortunately high frequency forcing fields are rare, not to say inexistent. GS: not true anymore ! 
     1340Nevertheless, 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}. 
    14571341Furthermore, only the knowledge of daily mean value of SWF is needed, 
    14581342as higher frequency variations can be reconstructed from them, 
    14591343assuming that the diurnal cycle of SWF is a scaling of the top of the atmosphere diurnal cycle of incident SWF. 
    1460 The \cite{Bernie_al_CD07} reconstruction algorithm is available in \NEMO by 
    1461 setting \np{ln\_dm2dc}\forcode{ = .true.} (a \textit{\ngn{namsbc}} namelist variable) when 
    1462 using CORE bulk formulea (\np{ln\_blk\_core}\forcode{ = .true.}) or 
    1463 the flux formulation (\np{ln\_flx}\forcode{ = .true.}). 
     1344The \cite{bernie.guilyardi.ea_CD07} reconstruction algorithm is available in \NEMO\ by 
     1345setting \np[=.true.]{ln_dm2dc}{ln\_dm2dc} (a \textit{\nam{sbc}{sbc}} namelist variable) when 
     1346using a bulk formulation (\np[=.true.]{ln_blk}{ln\_blk}) or 
     1347the flux formulation (\np[=.true.]{ln_flx}{ln\_flx}). 
    14641348The reconstruction is performed in the \mdl{sbcdcy} module. 
    1465 The detail of the algoritm used can be found in the appendix~A of \cite{Bernie_al_CD07}. 
    1466 The algorithm preserve the daily mean incoming SWF as the reconstructed SWF at 
     1349The detail of the algoritm used can be found in the appendix~A of \cite{bernie.guilyardi.ea_CD07}. 
     1350The algorithm preserves the daily mean incoming SWF as the reconstructed SWF at 
    14671351a given time step is the mean value of the analytical cycle over this time step (\autoref{fig:SBC_diurnal}). 
    14681352The use of diurnal cycle reconstruction requires the input SWF to be daily 
    1469 (\ie a frequency of 24 and a time interpolation set to true in \np{sn\_qsr} namelist parameter). 
    1470 Furthermore, it is recommended to have a least 8 surface module time step per day, 
     1353(\ie\ a frequency of 24 hours and a time interpolation set to true in \np{sn_qsr}{sn\_qsr} namelist parameter). 
     1354Furthermore, it is recommended to have a least 8 surface module time steps per day, 
    14711355that is  $\rdt \ nn\_fsbc < 10,800~s = 3~h$. 
    14721356An example of recontructed SWF is given in \autoref{fig:SBC_dcy} for a 12 reconstructed diurnal cycle, 
    14731357one every 2~hours (from 1am to 11pm). 
    14741358 
    1475 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    14761359\begin{figure}[!t] 
    1477   \begin{center} 
    1478     \includegraphics[width=0.7\textwidth]{Fig_SBC_dcy} 
    1479     \caption{ 
    1480       \protect\label{fig:SBC_dcy} 
    1481       Example of recontruction of the diurnal cycle variation of short wave flux from 
    1482       daily mean values on an ORCA2 grid with a time sampling of 2~hours (from 1am to 11pm). 
    1483       The display is on (i,j) plane. 
    1484     } 
    1485   \end{center} 
     1360  \centering 
     1361  \includegraphics[width=0.66\textwidth]{SBC_dcy} 
     1362  \caption[Reconstruction of the diurnal cycle variation of short wave flux on an ORCA2 grid]{ 
     1363    Example of reconstruction of the diurnal cycle variation of short wave flux from 
     1364    daily mean values on an ORCA2 grid with a time sampling of 2~hours (from 1am to 11pm). 
     1365    The display is on (i,j) plane.} 
     1366  \label{fig:SBC_dcy} 
    14861367\end{figure} 
    1487 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    14881368 
    14891369Note also that the setting a diurnal cycle in SWF is highly recommended when 
     
    14911371an inconsistency between the scale of the vertical resolution and the forcing acting on that scale. 
    14921372 
    1493 % ------------------------------------------------------------------------------------------------------------- 
    1494 %        Rotation of vector pairs onto the model grid directions 
    1495 % ------------------------------------------------------------------------------------------------------------- 
     1373%% ================================================================================================= 
    14961374\subsection{Rotation of vector pairs onto the model grid directions} 
    14971375\label{subsec:SBC_rotation} 
    14981376 
    1499 When using a flux (\np{ln\_flx}\forcode{ = .true.}) or 
    1500 bulk (\np{ln\_clio}\forcode{ = .true.} or \np{ln\_core}\forcode{ = .true.}) formulation, 
     1377When using a flux (\np[=.true.]{ln_flx}{ln\_flx}) or bulk (\np[=.true.]{ln_blk}{ln\_blk}) formulation, 
    15011378pairs of vector components can be rotated from east-north directions onto the local grid directions. 
    15021379This is particularly useful when interpolation on the fly is used since here any vectors are likely to 
    15031380be defined relative to a rectilinear grid. 
    1504 To activate this option a non-empty string is supplied in the rotation pair column of the relevant namelist. 
    1505 The eastward component must start with "U" and the northward component with "V".   
     1381To activate this option, a non-empty string is supplied in the rotation pair column of the relevant namelist. 
     1382The eastward component must start with "U" and the northward component with "V". 
    15061383The remaining characters in the strings are used to identify which pair of components go together. 
    15071384So for example, strings "U1" and "V1" next to "utau" and "vtau" would pair the wind stress components together and 
     
    15111388The rot\_rep routine from the \mdl{geo2ocean} module is used to perform the rotation. 
    15121389 
    1513 % ------------------------------------------------------------------------------------------------------------- 
    1514 %        Surface restoring to observed SST and/or SSS 
    1515 % ------------------------------------------------------------------------------------------------------------- 
    1516 \subsection{Surface restoring to observed SST and/or SSS (\protect\mdl{sbcssr})} 
     1390%% ================================================================================================= 
     1391\subsection[Surface restoring to observed SST and/or SSS (\textit{sbcssr.F90})]{Surface restoring to observed SST and/or SSS (\protect\mdl{sbcssr})} 
    15171392\label{subsec:SBC_ssr} 
    1518 %------------------------------------------namsbc_ssr---------------------------------------------------- 
    1519  
    1520 \nlst{namsbc_ssr}  
    1521 %------------------------------------------------------------------------------------------------------------- 
    1522  
    1523 IOptions are defined through the \ngn{namsbc\_ssr} namelist variables. 
    1524 On forced mode using a flux formulation (\np{ln\_flx}\forcode{ = .true.}), 
     1393 
     1394\begin{listing} 
     1395  \nlst{namsbc_ssr} 
     1396  \caption{\forcode{&namsbc_ssr}} 
     1397  \label{lst:namsbc_ssr} 
     1398\end{listing} 
     1399 
     1400Options are defined through the \nam{sbc_ssr}{sbc\_ssr} namelist variables. 
     1401On forced mode using a flux formulation (\np[=.true.]{ln_flx}{ln\_flx}), 
    15251402a feedback term \emph{must} be added to the surface heat flux $Q_{ns}^o$: 
    15261403\[ 
    1527   % \label{eq:sbc_dmp_q} 
     1404  % \label{eq:SBC_dmp_q} 
    15281405  Q_{ns} = Q_{ns}^o + \frac{dQ}{dT} \left( \left. T \right|_{k=1} - SST_{Obs} \right) 
    15291406\] 
     
    15311408$T$ is the model surface layer temperature and 
    15321409$\frac{dQ}{dT}$ is a negative feedback coefficient usually taken equal to $-40~W/m^2/K$. 
    1533 For a $50~m$ mixed-layer depth, this value corresponds to a relaxation time scale of two months.  
    1534 This term ensures that if $T$ perfectly matches the supplied SST, then $Q$ is equal to $Q_o$.  
     1410For a $50~m$ mixed-layer depth, this value corresponds to a relaxation time scale of two months. 
     1411This term ensures that if $T$ perfectly matches the supplied SST, then $Q$ is equal to $Q_o$. 
    15351412 
    15361413In the fresh water budget, a feedback term can also be added. 
     
    15381415 
    15391416\begin{equation} 
    1540   \label{eq:sbc_dmp_emp} 
     1417  \label{eq:SBC_dmp_emp} 
    15411418  \textit{emp} = \textit{emp}_o + \gamma_s^{-1} e_{3t}  \frac{  \left(\left.S\right|_{k=1}-SSS_{Obs}\right)} 
    15421419  {\left.S\right|_{k=1}} 
     
    15461423(observed, climatological or an atmospheric model product), 
    15471424\textit{SSS}$_{Obs}$ is a sea surface salinity 
    1548 (usually a time interpolation of the monthly mean Polar Hydrographic Climatology \citep{Steele2001}), 
     1425(usually a time interpolation of the monthly mean Polar Hydrographic Climatology \citep{steele.morley.ea_JC01}), 
    15491426$\left.S\right|_{k=1}$ is the model surface layer salinity and 
    15501427$\gamma_s$ is a negative feedback coefficient which is provided as a namelist parameter. 
    1551 Unlike heat flux, there is no physical justification for the feedback term in \autoref{eq:sbc_dmp_emp} as 
    1552 the atmosphere does not care about ocean surface salinity \citep{Madec1997}. 
     1428Unlike heat flux, there is no physical justification for the feedback term in \autoref{eq:SBC_dmp_emp} as 
     1429the atmosphere does not care about ocean surface salinity \citep{madec.delecluse_IWN97}. 
    15531430The SSS restoring term should be viewed as a flux correction on freshwater fluxes to 
    15541431reduce the uncertainties we have on the observed freshwater budget. 
    15551432 
    1556 % ------------------------------------------------------------------------------------------------------------- 
    1557 %        Handling of ice-covered area 
    1558 % ------------------------------------------------------------------------------------------------------------- 
     1433%% ================================================================================================= 
    15591434\subsection{Handling of ice-covered area  (\textit{sbcice\_...})} 
    15601435\label{subsec:SBC_ice-cover} 
     
    15621437The presence at the sea surface of an ice covered area modifies all the fluxes transmitted to the ocean. 
    15631438There are several way to handle sea-ice in the system depending on 
    1564 the value of the \np{nn\_ice} namelist parameter found in \ngn{namsbc} namelist. 
     1439the value of the \np{nn_ice}{nn\_ice} namelist parameter found in \nam{sbc}{sbc} namelist. 
    15651440\begin{description} 
    1566 \item[nn{\_}ice = 0] 
    1567   there will never be sea-ice in the computational domain. 
     1441\item [nn\_ice = 0] there will never be sea-ice in the computational domain. 
    15681442  This is a typical namelist value used for tropical ocean domain. 
    15691443  The surface fluxes are simply specified for an ice-free ocean. 
    15701444  No specific things is done for sea-ice. 
    1571 \item[nn{\_}ice = 1] 
    1572   sea-ice can exist in the computational domain, but no sea-ice model is used. 
     1445\item [nn\_ice = 1] sea-ice can exist in the computational domain, but no sea-ice model is used. 
    15731446  An observed ice covered area is read in a file. 
    15741447  Below this area, the SST is restored to the freezing point and 
     
    15781451  This prevents deep convection to occur when trying to reach the freezing point 
    15791452  (and so ice covered area condition) while the SSS is too large. 
    1580   This manner of managing sea-ice area, just by using si IF case, 
     1453  This manner of managing sea-ice area, just by using a IF case, 
    15811454  is usually referred as the \textit{ice-if} model. 
    1582   It can be found in the \mdl{sbcice{\_}if} module. 
    1583 \item[nn{\_}ice = 2 or more] 
    1584   A full sea ice model is used. 
     1455  It can be found in the \mdl{sbcice\_if} module. 
     1456\item [nn\_ice = 2 or more] A full sea ice model is used. 
    15851457  This model computes the ice-ocean fluxes, 
    15861458  that are combined with the air-sea fluxes using the ice fraction of each model cell to 
    1587   provide the surface ocean fluxes. 
    1588   Note that the activation of a sea-ice model is is done by defining a CPP key (\key{lim3} or \key{cice}). 
    1589   The activation automatically overwrites the read value of nn{\_}ice to its appropriate value 
    1590   (\ie $2$ for LIM-3 or $3$ for CICE). 
     1459  provide the surface averaged ocean fluxes. 
     1460  Note that the activation of a sea-ice model is done by defining a CPP key (\key{si3} or \key{cice}). 
     1461  The activation automatically overwrites the read value of nn\_ice to its appropriate value 
     1462  (\ie\ $2$ for SI3 or $3$ for CICE). 
    15911463\end{description} 
    15921464 
    15931465% {Description of Ice-ocean interface to be added here or in LIM 2 and 3 doc ?} 
    1594  
    1595 \subsection{Interface to CICE (\protect\mdl{sbcice\_cice})} 
     1466%GS: ocean-ice (SI3) interface is not located in SBC directory anymore, so it should be included in SI3 doc 
     1467 
     1468%% ================================================================================================= 
     1469\subsection[Interface to CICE (\textit{sbcice\_cice.F90})]{Interface to CICE (\protect\mdl{sbcice\_cice})} 
    15961470\label{subsec:SBC_cice} 
    15971471 
    1598 It is now possible to couple a regional or global NEMO configuration (without AGRIF) 
     1472It is possible to couple a regional or global \NEMO\ configuration (without AGRIF) 
    15991473to the CICE sea-ice model by using \key{cice}. 
    16001474The CICE code can be obtained from \href{http://oceans11.lanl.gov/trac/CICE/}{LANL} and 
    16011475the additional 'hadgem3' drivers will be required, even with the latest code release. 
    1602 Input grid files consistent with those used in NEMO will also be needed, 
     1476Input grid files consistent with those used in \NEMO\ will also be needed, 
    16031477and CICE CPP keys \textbf{ORCA\_GRID}, \textbf{CICE\_IN\_NEMO} and \textbf{coupled} should be used 
    16041478(seek advice from UKMO if necessary). 
    1605 Currently the code is only designed to work when using the CORE forcing option for NEMO 
    1606 (with \textit{calc\_strair}\forcode{ = .true.} and \textit{calc\_Tsfc}\forcode{ = .true.} in the CICE name-list), 
    1607 or alternatively when NEMO is coupled to the HadGAM3 atmosphere model 
    1608 (with \textit{calc\_strair}\forcode{ = .false.} and \textit{calc\_Tsfc}\forcode{ = false}). 
    1609 The code is intended to be used with \np{nn\_fsbc} set to 1 
     1479Currently, the code is only designed to work when using the NCAR forcing option for \NEMO\ %GS: still true ? 
     1480(with \textit{calc\_strair}\forcode{=.true.} and \textit{calc\_Tsfc}\forcode{=.true.} in the CICE name-list), 
     1481or alternatively when \NEMO\ is coupled to the HadGAM3 atmosphere model 
     1482(with \textit{calc\_strair}\forcode{=.false.} and \textit{calc\_Tsfc}\forcode{=false}). 
     1483The code is intended to be used with \np{nn_fsbc}{nn\_fsbc} set to 1 
    16101484(although coupling ocean and ice less frequently should work, 
    16111485it is possible the calculation of some of the ocean-ice fluxes needs to be modified slightly - 
    16121486the user should check that results are not significantly different to the standard case). 
    16131487 
    1614 There are two options for the technical coupling between NEMO and CICE. 
     1488There are two options for the technical coupling between \NEMO\ and CICE. 
    16151489The standard version allows complete flexibility for the domain decompositions in the individual models, 
    16161490but this is at the expense of global gather and scatter operations in the coupling which 
    16171491become very expensive on larger numbers of processors. 
    1618 The alternative option (using \key{nemocice\_decomp} for both NEMO and CICE) ensures that 
     1492The alternative option (using \key{nemocice\_decomp} for both \NEMO\ and CICE) ensures that 
    16191493the domain decomposition is identical in both models (provided domain parameters are set appropriately, 
    16201494and \textit{processor\_shape~=~square-ice} and \textit{distribution\_wght~=~block} in the CICE name-list) and 
     
    16231497there is no sea ice. 
    16241498 
    1625 % ------------------------------------------------------------------------------------------------------------- 
    1626 %        Freshwater budget control  
    1627 % ------------------------------------------------------------------------------------------------------------- 
    1628 \subsection{Freshwater budget control (\protect\mdl{sbcfwb})} 
     1499%% ================================================================================================= 
     1500\subsection[Freshwater budget control (\textit{sbcfwb.F90})]{Freshwater budget control (\protect\mdl{sbcfwb})} 
    16291501\label{subsec:SBC_fwb} 
    16301502 
    1631 For global ocean simulation it can be useful to introduce a control of the mean sea level in order to 
     1503For global ocean simulation, it can be useful to introduce a control of the mean sea level in order to 
    16321504prevent unrealistic drift of the sea surface height due to inaccuracy in the freshwater fluxes. 
    1633 In \NEMO, two way of controlling the the freshwater budget.  
     1505In \NEMO, two way of controlling the freshwater budget are proposed: 
     1506 
    16341507\begin{description} 
    1635 \item[\np{nn\_fwb}\forcode{ = 0}] 
    1636   no control at all. 
     1508\item [{\np[=0]{nn_fwb}{nn\_fwb}}] no control at all. 
    16371509  The mean sea level is free to drift, and will certainly do so. 
    1638 \item[\np{nn\_fwb}\forcode{ = 1}] 
    1639   global mean \textit{emp} set to zero at each model time step.  
    1640 %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).  
    1641 \item[\np{nn\_fwb}\forcode{ = 2}] 
    1642   freshwater budget is adjusted from the previous year annual mean budget which 
     1510\item [{\np[=1]{nn_fwb}{nn\_fwb}}] global mean \textit{emp} set to zero at each model time step. 
     1511  %GS: comment below still relevant ? 
     1512  %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). 
     1513\item [{\np[=2]{nn_fwb}{nn\_fwb}}] freshwater budget is adjusted from the previous year annual mean budget which 
    16431514  is read in the \textit{EMPave\_old.dat} file. 
    16441515  As the model uses the Boussinesq approximation, the annual mean fresh water budget is simply evaluated from 
    1645   the change in the mean sea level at January the first and saved in the \textit{EMPav.dat} file.  
     1516  the change in the mean sea level at January the first and saved in the \textit{EMPav.dat} file. 
    16461517\end{description} 
    16471518 
    1648  
    1649  
    16501519% Griffies doc: 
    1651 % When running ocean-ice simulations, we are not explicitly representing land processes,  
    1652 % such as rivers, catchment areas, snow accumulation, etc. However, to reduce model drift,  
    1653 % it is important to balance the hydrological cycle in ocean-ice models.  
    1654 % We thus need to prescribe some form of global normalization to the precipitation minus evaporation plus river runoff.  
    1655 % The result of the normalization should be a global integrated zero net water input to the ocean-ice system over  
    1656 % a chosen time scale.  
    1657 %How often the normalization is done is a matter of choice. In mom4p1, we choose to do so at each model time step,  
    1658 % so that there is always a zero net input of water to the ocean-ice system.  
    1659 % Others choose to normalize over an annual cycle, in which case the net imbalance over an annual cycle is used  
    1660 % to alter the subsequent year�s water budget in an attempt to damp the annual water imbalance.  
    1661 % Note that the annual budget approach may be inappropriate with interannually varying precipitation forcing.  
    1662 % When running ocean-ice coupled models, it is incorrect to include the water transport between the ocean  
    1663 % and ice models when aiming to balance the hydrological cycle.  
    1664 % The reason is that it is the sum of the water in the ocean plus ice that should be balanced when running ocean-ice models,  
    1665 % not the water in any one sub-component. As an extreme example to illustrate the issue,  
    1666 % consider an ocean-ice model with zero initial sea ice. As the ocean-ice model spins up,  
    1667 % there should be a net accumulation of water in the growing sea ice, and thus a net loss of water from the ocean.  
    1668 % The total water contained in the ocean plus ice system is constant, but there is an exchange of water between  
    1669 % the subcomponents. This exchange should not be part of the normalization used to balance the hydrological cycle  
    1670 % in ocean-ice models.  
    1671  
    1672 \biblio 
    1673  
    1674 \pindex 
     1520% When running ocean-ice simulations, we are not explicitly representing land processes, 
     1521% such as rivers, catchment areas, snow accumulation, etc. However, to reduce model drift, 
     1522% it is important to balance the hydrological cycle in ocean-ice models. 
     1523% We thus need to prescribe some form of global normalization to the precipitation minus evaporation plus river runoff. 
     1524% The result of the normalization should be a global integrated zero net water input to the ocean-ice system over 
     1525% a chosen time scale. 
     1526% How often the normalization is done is a matter of choice. In mom4p1, we choose to do so at each model time step, 
     1527% so that there is always a zero net input of water to the ocean-ice system. 
     1528% Others choose to normalize over an annual cycle, in which case the net imbalance over an annual cycle is used 
     1529% to alter the subsequent year�s water budget in an attempt to damp the annual water imbalance. 
     1530% Note that the annual budget approach may be inappropriate with interannually varying precipitation forcing. 
     1531% When running ocean-ice coupled models, it is incorrect to include the water transport between the ocean 
     1532% and ice models when aiming to balance the hydrological cycle. 
     1533% The reason is that it is the sum of the water in the ocean plus ice that should be balanced when running ocean-ice models, 
     1534% not the water in any one sub-component. As an extreme example to illustrate the issue, 
     1535% consider an ocean-ice model with zero initial sea ice. As the ocean-ice model spins up, 
     1536% there should be a net accumulation of water in the growing sea ice, and thus a net loss of water from the ocean. 
     1537% The total water contained in the ocean plus ice system is constant, but there is an exchange of water between 
     1538% the subcomponents. This exchange should not be part of the normalization used to balance the hydrological cycle 
     1539% in ocean-ice models. 
     1540 
     1541\subinc{\input{../../global/epilogue}} 
    16751542 
    16761543\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_STO.tex

    r10442 r11831  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter stochastic parametrization of EOS (STO) 
    6 % ================================================================ 
     4 
    75\chapter{Stochastic Parametrization of EOS (STO)} 
    86\label{chap:STO} 
    97 
    10 Authors: P.-A. Bouttier 
    11  
    12 \minitoc 
    13  
    14 \newpage 
    15  
    16 The stochastic parametrization module aims to explicitly simulate uncertainties in the model. 
    17 More particularly, \cite{Brankart_OM2013} has shown that, 
    18 because of the nonlinearity of the seawater equation of state, unresolved scales represent a major source of 
    19 uncertainties in the computation of the large scale horizontal density gradient (from T/S large scale fields), 
    20 and that the impact of these uncertainties can be simulated by 
    21 random processes representing unresolved T/S fluctuations. 
    22  
    23 The stochastic formulation of the equation of state can be written as: 
     8\thispagestyle{plain} 
     9 
     10\chaptertoc 
     11 
     12\paragraph{Changes record} ~\\ 
     13 
     14{\footnotesize 
     15  \begin{tabularx}{\textwidth}{l||X|X} 
     16    Release & Author(s) & Modifications \\ 
     17    \hline 
     18    {\em   4.0} & {\em ...} & {\em ...} \\ 
     19    {\em   3.6} & {\em ...} & {\em ...} \\ 
     20    {\em   3.4} & {\em ...} & {\em ...} \\ 
     21    {\em <=3.4} & {\em ...} & {\em ...} 
     22  \end{tabularx} 
     23} 
     24 
     25% \vfill 
     26% \begin{figure}[b] 
     27%% ================================================================================================= 
     28% \subsubsection*{Changes record} 
     29% \begin{tabular}{l||l|m{0.65\linewidth}} 
     30%    Release   & Author        & Modifications \\ 
     31%    {\em 4.0.1} & {\em C. Levy} & {\em 4.0.1 update}  \\ 
     32%    {\em 3.6} & {\em P.-A. Bouttier} & {\em initial version}  \\ 
     33% \end{tabular} 
     34% \end{figure} 
     35 
     36\clearpage 
     37 
     38As 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. 
     39 
     40As detailed in \cite{brankart_OM13}, the stochastic formulation of the equation of state can be written as: 
    2441\begin{equation} 
    25   \label{eq:eos_sto} 
     42  \label{eq:STO_eos_sto} 
    2643  \rho = \frac{1}{2} \sum_{i=1}^m\{ \rho[T+\Delta T_i,S+\Delta S_i,p_o(z)] + \rho[T-\Delta T_i,S-\Delta S_i,p_o(z)] \} 
    2744\end{equation} 
    2845where $p_o(z)$ is the reference pressure depending on the depth and, 
    29 $\Delta T_i$ and $\Delta S_i$ are a set of T/S perturbations defined as 
     46$\Delta T_i$ and $\Delta S_i$ (i=1,m) is a set of T/S perturbations defined as 
    3047the scalar product of the respective local T/S gradients with random walks $\mathbf{\xi}$: 
    3148\begin{equation} 
    32   \label{eq:sto_pert} 
     49  \label{eq:STO_sto_pert} 
    3350  \Delta T_i = \mathbf{\xi}_i \cdot \nabla T \qquad \hbox{and} \qquad \Delta S_i = \mathbf{\xi}_i \cdot \nabla S 
    3451\end{equation} 
    35 $\mathbf{\xi}_i$ are produced by a first-order autoregressive processes (AR-1) with 
     52$\mathbf{\xi}_i$ are produced by a first-order autoregressive process (AR-1) with 
    3653a parametrized decorrelation time scale, and horizontal and vertical standard deviations $\sigma_s$. 
    3754$\mathbf{\xi}$ are uncorrelated over the horizontal and fully correlated along the vertical. 
    3855 
    39  
     56%% ================================================================================================= 
    4057\section{Stochastic processes} 
    4158\label{sec:STO_the_details} 
    4259 
    43 The starting point of our implementation of stochastic parameterizations in NEMO is to observe that 
    44 many existing parameterizations are based on autoregressive processes, 
     60There are many existing parameterizations based on autoregressive processes, 
    4561which are used as a basic source of randomness to transform a deterministic model into a probabilistic model. 
    46 A generic approach is thus to add one single new module in NEMO, 
    47 generating processes with appropriate statistics to simulate each kind of uncertainty in the model 
    48 (see \cite{Brankart_al_GMD2015} for more details). 
    49  
    50 In practice, at every model grid point, 
     62The generic approach here is to a new STO module, 
     63generating processes features with appropriate statistics to simulate these uncertainties in the model 
     64(see \cite{brankart.candille.ea_GMD15} for more details). 
     65 
     66In practice, at each model grid point, 
    5167independent Gaussian autoregressive processes~$\xi^{(i)},\,i=1,\ldots,m$ are first generated using 
    5268the same basic equation: 
    5369 
    5470\begin{equation} 
    55   \label{eq:autoreg} 
     71  \label{eq:STO_autoreg} 
    5672  \xi^{(i)}_{k+1} = a^{(i)} \xi^{(i)}_k + b^{(i)} w^{(i)} + c^{(i)} 
    5773\end{equation} 
     
    6379 
    6480\begin{itemize} 
    65 \item 
    66   for order~1 processes, $w^{(i)}$ is a Gaussian white noise, with zero mean and standard deviation equal to~1, 
     81\item for order~1 processes, $w^{(i)}$ is a Gaussian white noise, with zero mean and standard deviation equal to~1, 
    6782  and the parameters $a^{(i)}$, $b^{(i)}$, $c^{(i)}$ are given by: 
    6883 
    6984  \[ 
    70     % \label{eq:ord1} 
     85    % \label{eq:STO_ord1} 
    7186    \left\{ 
    7287      \begin{array}{l} 
     
    7893  \] 
    7994 
    80 \item 
    81   for order~$n>1$ processes, $w^{(i)}$ is an order~$n-1$ autoregressive process, with zero mean, 
     95\item for order~$n>1$ processes, $w^{(i)}$ is an order~$n-1$ autoregressive process, with zero mean, 
    8296  standard deviation equal to~$\sigma^{(i)}$; 
    8397  correlation timescale equal to~$\tau^{(i)}$; 
     
    8599 
    86100  \begin{equation} 
    87     \label{eq:ord2} 
     101    \label{eq:STO_ord2} 
    88102    \left\{ 
    89103      \begin{array}{l} 
     
    101115\noindent 
    102116In this way, higher order processes can be easily generated recursively using the same piece of code implementing 
    103 (\autoref{eq:autoreg}), and using succesively processes from order $0$ to~$n-1$ as~$w^{(i)}$. 
    104 The parameters in (\autoref{eq:ord2}) are computed so that this recursive application of 
    105 (\autoref{eq:autoreg}) leads to processes with the required standard deviation and correlation timescale, 
     117\autoref{eq:STO_autoreg}, and using successive processes from order $0$ to~$n-1$ as~$w^{(i)}$. 
     118The parameters in \autoref{eq:STO_ord2} are computed so that this recursive application of 
     119\autoref{eq:STO_autoreg} leads to processes with the required standard deviation and correlation timescale, 
    106120with the additional condition that the $n-1$ first derivatives of the autocorrelation function are equal to 
    107 zero at~$t=0$, so that the resulting processes become smoother and smoother as $n$ is increased. 
     121zero at~$t=0$, so that the resulting processes become smoother and smoother as $n$ increases. 
    108122 
    109123Overall, this method provides quite a simple and generic way of generating a wide class of stochastic processes. 
    110124However, this also means that new model parameters are needed to specify each of these stochastic processes. 
    111 As in any parameterization of lacking physics, a very important issues then to tune these new parameters using 
     125As in any parameterization, the main issue is to tune the parameters using 
    112126either first principles, model simulations, or real-world observations. 
    113  
     127The parameters are set by default as described in \cite{brankart_OM13}, which has been shown in the paper 
     128to 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. 
     129The set of parameters will need further investigation to find appropriate values 
     130for any other configuration or resolution of the model. 
     131 
     132%% ================================================================================================= 
    114133\section{Implementation details} 
    115134\label{sec:STO_thech_details} 
    116135 
    117 %---------------------------------------namsbc-------------------------------------------------- 
    118  
    119 \nlst{namsto} 
    120 %-------------------------------------------------------------------------------------------------------------- 
    121  
    122 The computer code implementing stochastic parametrisations can be found in the STO directory. 
    123 It involves three modules :  
    124 \begin{description} 
    125 \item[\mdl{stopar}:] 
    126   define the Stochastic parameters and their time evolution. 
    127 \item[\mdl{storng}:] 
    128   a random number generator based on (and includes) the 64-bit KISS (Keep It Simple Stupid) random number generator 
    129   distributed by George Marsaglia 
    130   (see \href{https://groups.google.com/forum/#!searchin/comp.lang.fortran/64-bit$20KISS$20RNGs}{here}) 
    131 \item[\mdl{stopts}:] 
    132   stochastic parametrisation associated with the non-linearity of the equation of seawater, 
    133   implementing \autoref{eq:sto_pert} and specific piece of code in 
    134   the equation of state implementing \autoref{eq:eos_sto}. 
    135 \end{description} 
    136  
    137 The \mdl{stopar} module has 3 public routines to be called by the model (in our case, NEMO): 
    138  
    139 The first routine (\rou{sto\_par}) is a direct implementation of (\autoref{eq:autoreg}), 
     136The code implementing stochastic parametrisation is located in the src/OCE/STO directory. 
     137It contains three modules : 
     138% \begin{description} 
     139 
     140\mdl{stopar} : define the Stochastic parameters and their time evolution 
     141 
     142\mdl{storng} : random number generator based on and including the 64-bit KISS (Keep It Simple Stupid) random number generator distributed by George Marsaglia 
     143 
     144\mdl{stopts} : stochastic parametrisation associated with the non-linearity of the equation of 
     145 seawater, implementing \autoref{eq:STO_sto_pert} so as specifics in the equation of state 
     146 implementing \autoref{eq:STO_eos_sto}. 
     147% \end{description} 
     148 
     149The \mdl{stopar} module includes three public routines called in the model: 
     150 
     151(\rou{sto\_par}) is a direct implementation of \autoref{eq:STO_autoreg}, 
    140152applied at each model grid point (in 2D or 3D), and called at each model time step ($k$) to 
    141153update every autoregressive process ($i=1,\ldots,m$). 
     
    143155to introduce a spatial correlation between the stochastic processes. 
    144156 
    145 The second routine (\rou{sto\_par\_init}) is an initialization routine mainly dedicated to 
    146 the computation of parameters $a^{(i)}, b^{(i)}, c^{(i)}$ for each autoregressive process, 
     157(\rou{sto\_par\_init}) is the initialization routine computing 
     158the values $a^{(i)}, b^{(i)}, c^{(i)}$ for each autoregressive process, 
    147159as a function of the statistical properties required by the model user 
    148 (mean, standard deviation, time correlation, order of the process,\ldots).  
    149  
    150 Parameters for the processes can be specified through the following \ngn{namsto} namelist parameters: 
    151 \begin{description} 
    152 \item[\np{nn\_sto\_eos}:]   number of independent random walks 
    153 \item[\np{rn\_eos\_stdxy}:] random walk horz. standard deviation (in grid points) 
    154 \item[\np{rn\_eos\_stdz}:]  random walk vert. standard deviation (in grid points) 
    155 \item[\np{rn\_eos\_tcor}:]  random walk time correlation (in timesteps) 
    156 \item[\np{nn\_eos\_ord}:]   order of autoregressive processes 
    157 \item[\np{nn\_eos\_flt}:]   passes of Laplacian filter 
    158 \item[\np{rn\_eos\_lim}:]   limitation factor (default = 3.0) 
    159 \end{description} 
     160(mean, standard deviation, time correlation, order of the process,\ldots). 
    160161This routine also includes the initialization (seeding) of the random number generator. 
    161162 
    162 The third routine (\rou{sto\_rst\_write}) writes a restart file 
    163 (which suffix name is given by \np{cn\_storst\_out} namelist parameter) containing the current value of 
    164 all autoregressive processes to allow restarting a simulation from where it has been interrupted. 
    165 This file also contains the current state of the random number generator. 
    166 When \np{ln\_rststo} is set to \forcode{.true.}), 
    167 the restart file (which suffix name is given by \np{cn\_storst\_in} namelist parameter) is read by 
     163(\rou{sto\_rst\_write}) writes a restart file 
     164(which suffix name is given by \np{cn_storst_out}{cn\_storst\_out} namelist parameter) containing the current value of 
     165all autoregressive processes to allow creating the file needed for a restart. 
     166This restart file also contains the current state of the random number generator. 
     167When \np{ln_rststo}{ln\_rststo} is set to \forcode{.true.}), 
     168the restart file (which suffix name is given by \np{cn_storst_in}{cn\_storst\_in} namelist parameter) is read by 
    168169the initialization routine (\rou{sto\_par\_init}). 
    169170The simulation will continue exactly as if it was not interrupted only 
    170 when \np{ln\_rstseed} is set to \forcode{.true.}, 
    171 \ie when the state of the random number generator is read in the restart file. 
    172  
    173 \biblio 
    174  
    175 \pindex 
     171when \np{ln_rstseed}{ln\_rstseed} is set to \forcode{.true.}, 
     172\ie\ when the state of the random number generator is read in the restart file.\\ 
     173 
     174The implementation includes the basics for a few possible stochastic parametrisations including equation of state, 
     175lateral diffusion, horizontal pressure gradient, ice strength, trend, tracers dynamics. 
     176As for this release, only the stochastic parametrisation of equation of state is fully available and tested. \\ 
     177 
     178Options and parameters \\ 
     179 
     180The \np{ln_sto_eos}{ln\_sto\_eos} namelist variable activates stochastic parametrisation of equation of state. 
     181By default it set to \forcode{.false.}) and not active. 
     182The set of parameters is available in \nam{sto}{sto} namelist 
     183(only the subset for equation of state stochastic parametrisation is listed below): 
     184 
     185\begin{listing} 
     186  \nlst{namsto} 
     187  \caption{\forcode{&namsto}} 
     188  \label{lst:namsto} 
     189\end{listing} 
     190 
     191The variables of stochastic paramtetrisation itself (based on the global 2° experiments as in \cite{brankart_OM13} are: 
     192 
     193\begin{description} 
     194\item [{\np{nn_sto_eos}{nn\_sto\_eos}:}]     number of independent random walks 
     195\item [{\np{rn_eos_stdxy}{rn\_eos\_stdxy}:}] random walk horizontal standard deviation 
     196  (in grid points) 
     197\item [{\np{rn_eos_stdz}{rn\_eos\_stdz}:}]   random walk vertical standard deviation 
     198  (in grid points) 
     199\item [{\np{rn_eos_tcor}{rn\_eos\_tcor}:}]   random walk time correlation (in timesteps) 
     200\item [{\np{nn_eos_ord}{nn\_eos\_ord}:}]     order of autoregressive processes 
     201\item [{\np{nn_eos_flt}{nn\_eos\_flt}:}]     passes of Laplacian filter 
     202\item [{\np{rn_eos_lim}{rn\_eos\_lim}:}]     limitation factor (default = 3.0) 
     203\end{description} 
     204 
     205The first four parameters define the stochastic part of equation of state. 
     206 
     207\subinc{\input{../../global/epilogue}} 
    176208 
    177209\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_TRA.tex

    r10544 r11831  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter 1 ——— Ocean Tracers (TRA) 
    6 % ================================================================ 
     4 
    75\chapter{Ocean Tracers (TRA)} 
    86\label{chap:TRA} 
    97 
    10 \minitoc 
    11  
    12 % missing/update  
     8\thispagestyle{plain} 
     9 
     10\chaptertoc 
     11 
     12\paragraph{Changes record} ~\\ 
     13 
     14{\footnotesize 
     15  \begin{tabularx}{\textwidth}{l||X|X} 
     16    Release          & Author(s)                                   & Modifications       \\ 
     17    \hline 
     18    {\em        4.0} & {\em Christian \'{E}th\'{e}               } & {\em Review       } \\ 
     19    {\em        3.6} & {\em Gurvan Madec                         } & {\em Update       } \\ 
     20    {\em $\leq$ 3.4} & {\em Gurvan Madec and S\'{e}bastien Masson} & {\em First version} \\ 
     21  \end{tabularx} 
     22} 
     23 
     24\clearpage 
     25 
     26% missing/update 
    1327% traqsr: need to coordinate with SBC module 
    1428 
    15 %STEVEN :  is the use of the word "positive" to describe a scheme enough, or should it be "positive definite"? I added a comment to this effect on some instances of this below 
     29%STEVEN :  is the use of the word "positive" to describe a scheme enough, or should it be "positive definite"? 
     30%I added a comment to this effect on some instances of this below 
    1631 
    1732Using the representation described in \autoref{chap:DOM}, several semi -discrete space forms of 
    1833the tracer equations are available depending on the vertical coordinate used and on the physics used. 
    1934In all the equations presented here, the masking has been omitted for simplicity. 
    20 One must be aware that all the quantities are masked fields and that each time a mean or 
    21 difference operator is used, the resulting field is multiplied by a mask. 
     35One must be aware that all the quantities are masked fields and that 
     36each time a mean or difference operator is used, the resulting field is multiplied by a mask. 
    2237 
    2338The two active tracers are potential temperature and salinity. 
     
    3045NXT stands for next, referring to the time-stepping. 
    3146From left to right, the terms on the rhs of the tracer equations are the advection (ADV), 
    32 the lateral diffusion (LDF), the vertical diffusion (ZDF), the contributions from the external forcings 
    33 (SBC: Surface Boundary Condition, QSR: penetrative Solar Radiation, and BBC: Bottom Boundary Condition), 
    34 the contribution from the bottom boundary Layer (BBL) parametrisation, and an internal damping (DMP) term. 
     47the lateral diffusion (LDF), the vertical diffusion (ZDF), 
     48the contributions from the external forcings (SBC: Surface Boundary Condition, 
     49QSR: penetrative Solar Radiation, and BBC: Bottom Boundary Condition), 
     50the contribution from the bottom boundary Layer (BBL) parametrisation, 
     51and an internal damping (DMP) term. 
    3552The terms QSR, BBC, BBL and DMP are optional. 
    3653The external forcings and parameterisations require complex inputs and complex calculations 
    37 (\eg bulk formulae, estimation of mixing coefficients) that are carried out in the SBC, 
     54(\eg\ bulk formulae, estimation of mixing coefficients) that are carried out in the SBC, 
    3855LDF and ZDF modules and described in \autoref{chap:SBC}, \autoref{chap:LDF} and 
    3956\autoref{chap:ZDF}, respectively. 
    40 Note that \mdl{tranpc}, the non-penetrative convection module, although located in 
    41 the \path{./src/OCE/TRA} directory as it directly modifies the tracer fields, 
     57Note that \mdl{tranpc}, the non-penetrative convection module, 
     58although located in the \path{./src/OCE/TRA} directory as it directly modifies the tracer fields, 
    4259is described with the model vertical physics (ZDF) together with 
    4360other available parameterization of convection. 
    4461 
    45 In the present chapter we also describe the diagnostic equations used to compute the sea-water properties 
    46 (density, Brunt-V\"{a}is\"{a}l\"{a} frequency, specific heat and freezing point with 
    47 associated modules \mdl{eosbn2} and \mdl{phycst}). 
    48  
    49 The different options available to the user are managed by namelist logicals or CPP keys. 
     62In the present chapter we also describe the diagnostic equations used to 
     63compute the sea-water properties (density, Brunt-V\"{a}is\"{a}l\"{a} frequency, specific heat and 
     64freezing point with associated modules \mdl{eosbn2} and \mdl{phycst}). 
     65 
     66The different options available to the user are managed by namelist logicals. 
    5067For each equation term \textit{TTT}, the namelist logicals are \textit{ln\_traTTT\_xxx}, 
    5168where \textit{xxx} is a 3 or 4 letter acronym corresponding to each optional scheme. 
    52 The CPP key (when it exists) is \key{traTTT}. 
    5369The equivalent code can be found in the \textit{traTTT} or \textit{traTTT\_xxx} module, 
    5470in the \path{./src/OCE/TRA} directory. 
    5571 
    5672The user has the option of extracting each tendency term on the RHS of the tracer equation for output 
    57 (\np{ln\_tra\_trd} or \np{ln\_tra\_mxl}~\forcode{= .true.}), as described in \autoref{chap:DIA}. 
    58  
    59 % ================================================================ 
    60 % Tracer Advection 
    61 % ================================================================ 
    62 \section{Tracer advection (\protect\mdl{traadv})} 
     73(\np{ln_tra_trd}{ln\_tra\_trd} or \np[=.true.]{ln_tra_mxl}{ln\_tra\_mxl}), 
     74as described in \autoref{chap:DIA}. 
     75 
     76%% ================================================================================================= 
     77\section[Tracer advection (\textit{traadv.F90})]{Tracer advection (\protect\mdl{traadv})} 
    6378\label{sec:TRA_adv} 
    64 %------------------------------------------namtra_adv----------------------------------------------------- 
    65  
    66 \nlst{namtra_adv} 
    67 %------------------------------------------------------------------------------------------------------------- 
    68  
    69 When considered (\ie when \np{ln\_traadv\_NONE} is not set to \forcode{.true.}), 
     79 
     80\begin{listing} 
     81  \nlst{namtra_adv} 
     82  \caption{\forcode{&namtra_adv}} 
     83  \label{lst:namtra_adv} 
     84\end{listing} 
     85 
     86When considered (\ie\ when \np{ln_traadv_OFF}{ln\_traadv\_OFF} is not set to \forcode{.true.}), 
    7087the advection tendency of a tracer is expressed in flux form, 
    71 \ie as the divergence of the advective fluxes. 
    72 Its discrete expression is given by : 
    73 \begin{equation} 
    74   \label{eq:tra_adv} 
     88\ie\ as the divergence of the advective fluxes. 
     89Its discrete expression is given by: 
     90\begin{equation} 
     91  \label{eq:TRA_adv} 
    7592  ADV_\tau = - \frac{1}{b_t} \Big(   \delta_i [ e_{2u} \, e_{3u} \; u \; \tau_u] 
    7693                                   + \delta_j [ e_{1v} \, e_{3v} \; v \; \tau_v] \Big) 
     
    7895\end{equation} 
    7996where $\tau$ is either T or S, and $b_t = e_{1t} \, e_{2t} \, e_{3t}$ is the volume of $T$-cells. 
    80 The flux form in \autoref{eq:tra_adv} implicitly requires the use of the continuity equation. 
    81 Indeed, it is obtained by using the following equality: $\nabla \cdot (\vect U \, T) = \vect U \cdot \nabla T$ which 
    82 results from the use of the continuity equation, $\partial_t e_3 + e_3 \; \nabla \cdot \vect U = 0$ 
    83 (which reduces to $\nabla \cdot \vect U = 0$ in linear free surface, \ie \np{ln\_linssh}~\forcode{= .true.}). 
    84 Therefore it is of paramount importance to design the discrete analogue of the advection tendency so that 
    85 it is consistent with the continuity equation in order to enforce the conservation properties of 
    86 the continuous equations. 
    87 In other words, by setting $\tau = 1$ in (\autoref{eq:tra_adv}) we recover the discrete form of 
    88 the continuity equation which is used to calculate the vertical velocity. 
    89 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    90 \begin{figure}[!t] 
    91   \begin{center} 
    92     \includegraphics[]{Fig_adv_scheme} 
    93     \caption{ 
    94       \protect\label{fig:adv_scheme} 
    95       Schematic representation of some ways used to evaluate the tracer value at $u$-point and 
    96       the amount of tracer exchanged between two neighbouring grid points. 
    97       Upsteam biased scheme (ups): 
    98       the upstream value is used and the black area is exchanged. 
    99       Piecewise parabolic method (ppm): 
    100       a parabolic interpolation is used and the black and dark grey areas are exchanged. 
    101       Monotonic upstream scheme for conservative laws (muscl): 
    102       a parabolic interpolation is used and black, dark grey and grey areas are exchanged. 
    103       Second order scheme (cen2): 
    104       the mean value is used and black, dark grey, grey and light grey areas are exchanged. 
    105       Note that this illustration does not include the flux limiter used in ppm and muscl schemes. 
    106     } 
    107   \end{center} 
     97The flux form in \autoref{eq:TRA_adv} implicitly requires the use of the continuity equation. 
     98Indeed, it is obtained by using the following equality: 
     99$\nabla \cdot (\vect U \, T) = \vect U \cdot \nabla T$ which 
     100results from the use of the continuity equation, 
     101$\partial_t e_3 + e_3 \; \nabla \cdot \vect U = 0$ 
     102(which reduces to $\nabla \cdot \vect U = 0$ in linear free surface, 
     103\ie\ \np[=.true.]{ln_linssh}{ln\_linssh}). 
     104Therefore it is of paramount importance to 
     105design the discrete analogue of the advection tendency so that 
     106it is consistent with the continuity equation in order to 
     107enforce the conservation properties of the continuous equations. 
     108In other words, by setting $\tau = 1$ in (\autoref{eq:TRA_adv}) we recover 
     109the discrete form of the continuity equation which is used to calculate the vertical velocity. 
     110\begin{figure} 
     111  \centering 
     112  \includegraphics[width=0.66\textwidth]{TRA_adv_scheme} 
     113  \caption[Ways to evaluate the tracer value and the amount of tracer exchanged]{ 
     114    Schematic representation of some ways used to evaluate the tracer value at $u$-point and 
     115    the amount of tracer exchanged between two neighbouring grid points. 
     116    Upsteam biased scheme (ups): 
     117    the upstream value is used and the black area is exchanged. 
     118    Piecewise parabolic method (ppm): 
     119    a parabolic interpolation is used and the black and dark grey areas are exchanged. 
     120    Monotonic upstream scheme for conservative laws (muscl): 
     121    a parabolic interpolation is used and black, dark grey and grey areas are exchanged. 
     122    Second order scheme (cen2): 
     123    the mean value is used and black, dark grey, grey and light grey areas are exchanged. 
     124    Note that this illustration does not include the flux limiter used in ppm and muscl schemes.} 
     125  \label{fig:TRA_adv_scheme} 
    108126\end{figure} 
    109 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    110  
    111 The key difference between the advection schemes available in \NEMO is the choice made in space and 
    112 time interpolation to define the value of the tracer at the velocity points 
    113 (\autoref{fig:adv_scheme}). 
     127 
     128The key difference between the advection schemes available in \NEMO\ is the choice made in 
     129space and time interpolation to define the value of the tracer at the velocity points 
     130(\autoref{fig:TRA_adv_scheme}). 
    114131 
    115132Along solid lateral and bottom boundaries a zero tracer flux is automatically specified, 
     
    118135 
    119136\begin{description} 
    120 \item[linear free surface:] 
    121   (\np{ln\_linssh}~\forcode{= .true.}) 
     137\item [linear free surface] (\np[=.true.]{ln_linssh}{ln\_linssh}) 
    122138  the first level thickness is constant in time: 
    123   the vertical boundary condition is applied at the fixed surface $z = 0$ rather than on 
    124   the moving surface $z = \eta$. 
    125   There is a non-zero advective flux which is set for all advection schemes as 
    126   $\tau_w|_{k = 1/2} = T_{k = 1}$, \ie the product of surface velocity (at $z = 0$) by 
    127   the first level tracer value. 
    128 \item[non-linear free surface:] 
    129   (\np{ln\_linssh}~\forcode{= .false.}) 
     139  the vertical boundary condition is applied at the fixed surface $z = 0$ rather than 
     140  on the moving surface $z = \eta$. 
     141  There is a non-zero advective flux which is set for 
     142  all advection schemes as $\tau_w|_{k = 1/2} = T_{k = 1}$, 
     143  \ie\ the product of surface velocity (at $z = 0$) by the first level tracer value. 
     144\item [non-linear free surface] (\np[=.false.]{ln_linssh}{ln\_linssh}) 
    130145  convergence/divergence in the first ocean level moves the free surface up/down. 
    131   There is no tracer advection through it so that the advective fluxes through the surface are also zero. 
     146  There is no tracer advection through it so that 
     147  the advective fluxes through the surface are also zero. 
    132148\end{description} 
    133149 
    134150In all cases, this boundary condition retains local conservation of tracer. 
    135 Global conservation is obtained in non-linear free surface case, but \textit{not} in the linear free surface case. 
    136 Nevertheless, in the latter case, it is achieved to a good approximation since 
    137 the non-conservative term is the product of the time derivative of the tracer and the free surface height, 
    138 two quantities that are not correlated \citep{Roullet_Madec_JGR00, Griffies_al_MWR01, Campin2004}. 
    139  
    140 The velocity field that appears in (\autoref{eq:tra_adv} and \autoref{eq:tra_adv_zco}) is 
    141 the centred (\textit{now}) \textit{effective} ocean velocity, \ie the \textit{eulerian} velocity 
     151Global conservation is obtained in non-linear free surface case, 
     152but \textit{not} in the linear free surface case. 
     153Nevertheless, in the latter case, 
     154it is achieved to a good approximation since the non-conservative term is 
     155the product of the time derivative of the tracer and the free surface height, 
     156two quantities that are not correlated 
     157\citep{roullet.madec_JGR00, griffies.pacanowski.ea_MWR01, campin.adcroft.ea_OM04}. 
     158 
     159The velocity field that appears in (\autoref{eq:TRA_adv} is 
     160the centred (\textit{now}) \textit{effective} ocean velocity, \ie\ the \textit{eulerian} velocity 
    142161(see \autoref{chap:DYN}) plus the eddy induced velocity (\textit{eiv}) and/or 
    143162the mixed layer eddy induced velocity (\textit{eiv}) when those parameterisations are used 
    144163(see \autoref{chap:LDF}). 
    145164 
    146 Several tracer advection scheme are proposed, namely a $2^{nd}$ or $4^{th}$ order centred schemes (CEN), 
    147 a $2^{nd}$ or $4^{th}$ order Flux Corrected Transport scheme (FCT), a Monotone Upstream Scheme for 
    148 Conservative Laws scheme (MUSCL), a $3^{rd}$ Upstream Biased Scheme (UBS, also often called UP3), 
    149 and a Quadratic Upstream Interpolation for Convective Kinematics with Estimated Streaming Terms scheme (QUICKEST). 
    150 The choice is made in the \ngn{namtra\_adv} namelist, by setting to \forcode{.true.} one of 
    151 the logicals \textit{ln\_traadv\_xxx}. 
    152 The corresponding code can be found in the \textit{traadv\_xxx.F90} module, where 
    153 \textit{xxx} is a 3 or 4 letter acronym corresponding to each scheme. 
    154 By default (\ie in the reference namelist, \textit{namelist\_ref}), all the logicals are set to \forcode{.false.}. 
    155 If the user does not select an advection scheme in the configuration namelist (\textit{namelist\_cfg}), 
    156 the tracers will \textit{not} be advected! 
     165Several tracer advection scheme are proposed, 
     166namely a $2^{nd}$ or $4^{th}$ order \textbf{CEN}tred schemes (CEN), 
     167a $2^{nd}$ or $4^{th}$ order \textbf{F}lux \textbf{C}orrected \textbf{T}ransport scheme (FCT), 
     168a \textbf{M}onotone \textbf{U}pstream \textbf{S}cheme for 
     169\textbf{C}onservative \textbf{L}aws scheme (MUSCL), 
     170a $3^{rd}$ \textbf{U}pstream \textbf{B}iased \textbf{S}cheme (UBS, also often called UP3), 
     171and a \textbf{Q}uadratic \textbf{U}pstream \textbf{I}nterpolation for 
     172\textbf{C}onvective \textbf{K}inematics with 
     173\textbf{E}stimated \textbf{S}treaming \textbf{T}erms scheme (QUICKEST). 
     174The choice is made in the \nam{tra_adv}{tra\_adv} namelist, 
     175by setting to \forcode{.true.} one of the logicals \textit{ln\_traadv\_xxx}. 
     176The corresponding code can be found in the \textit{traadv\_xxx.F90} module, 
     177where \textit{xxx} is a 3 or 4 letter acronym corresponding to each scheme. 
     178By default (\ie\ in the reference namelist, \textit{namelist\_ref}), 
     179all the logicals are set to \forcode{.false.}. 
     180If the user does not select an advection scheme in the configuration namelist 
     181(\textit{namelist\_cfg}), the tracers will \textit{not} be advected! 
    157182 
    158183Details of the advection schemes are given below. 
    159 The choosing an advection scheme is a complex matter which depends on the model physics, model resolution, 
    160 type of tracer, as well as the issue of numerical cost. In particular, we note that 
     184The choosing an advection scheme is a complex matter which depends on the 
     185model physics, model resolution, type of tracer, as well as the issue of numerical cost. 
     186In particular, we note that 
    161187 
    162188\begin{enumerate} 
    163 \item 
    164   CEN and FCT schemes require an explicit diffusion operator while the other schemes are diffusive enough so that 
    165   they do not necessarily need additional diffusion; 
    166 \item 
    167   CEN and UBS are not \textit{positive} schemes 
    168   \footnote{negative values can appear in an initially strictly positive tracer field which is advected}, 
     189\item CEN and FCT schemes require an explicit diffusion operator while 
     190  the other schemes are diffusive enough so that they do not necessarily need additional diffusion; 
     191\item CEN and UBS are not \textit{positive} schemes \footnote{negative values can appear in 
     192    an initially strictly positive tracer field which is advected}, 
    169193  implying that false extrema are permitted. 
    170194  Their use is not recommended on passive tracers; 
    171 \item 
    172   It is recommended that the same advection-diffusion scheme is used on both active and passive tracers. 
     195\item It is recommended that the same advection-diffusion scheme is used on 
     196  both active and passive tracers. 
    173197\end{enumerate} 
    174198 
    175 Indeed, if a source or sink of a passive tracer depends on an active one, the difference of treatment of active and 
    176 passive tracers can create very nice-looking frontal structures that are pure numerical artefacts. 
     199Indeed, if a source or sink of a passive tracer depends on an active one, 
     200the difference of treatment of active and passive tracers can create 
     201very nice-looking frontal structures that are pure numerical artefacts. 
    177202Nevertheless, most of our users set a different treatment on passive and active tracers, 
    178203that's the reason why this possibility is offered. 
    179 We strongly suggest them to perform a sensitivity experiment using a same treatment to assess the robustness of 
    180 their results. 
    181  
    182 % ------------------------------------------------------------------------------------------------------------- 
    183 %        2nd and 4th order centred schemes 
    184 % ------------------------------------------------------------------------------------------------------------- 
    185 \subsection{CEN: Centred scheme (\protect\np{ln\_traadv\_cen}~\forcode{= .true.})} 
     204We strongly suggest them to perform a sensitivity experiment using a same treatment to 
     205assess the robustness of their results. 
     206 
     207%% ================================================================================================= 
     208\subsection[CEN: Centred scheme (\forcode{ln_traadv_cen})]{CEN: Centred scheme (\protect\np{ln_traadv_cen}{ln\_traadv\_cen})} 
    186209\label{subsec:TRA_adv_cen} 
    187210 
    188 %        2nd order centred scheme   
    189  
    190 The centred advection scheme (CEN) is used when \np{ln\_traadv\_cen}~\forcode{= .true.}. 
    191 Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) and vertical direction by 
    192 setting \np{nn\_cen\_h} and \np{nn\_cen\_v} to $2$ or $4$. 
     211%        2nd order centred scheme 
     212 
     213The \textbf{CEN}tred advection scheme (CEN) is used when \np[=.true.]{ln_traadv_cen}{ln\_traadv\_cen}. 
     214Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on 
     215horizontal (iso-level) and vertical direction by 
     216setting \np{nn_cen_h}{nn\_cen\_h} and \np{nn_cen_v}{nn\_cen\_v} to $2$ or $4$. 
    193217CEN implementation can be found in the \mdl{traadv\_cen} module. 
    194218 
    195 In the $2^{nd}$ order centred formulation (CEN2), the tracer at velocity points is evaluated as the mean of 
    196 the two neighbouring $T$-point values. 
     219In the $2^{nd}$ order centred formulation (CEN2), the tracer at velocity points is evaluated as 
     220the mean of the two neighbouring $T$-point values. 
    197221For example, in the $i$-direction : 
    198222\begin{equation} 
    199   \label{eq:tra_adv_cen2} 
     223  \label{eq:TRA_adv_cen2} 
    200224  \tau_u^{cen2} = \overline T ^{i + 1/2} 
    201225\end{equation} 
    202226 
    203 CEN2 is non diffusive (\ie it conserves the tracer variance, $\tau^2$) but dispersive 
    204 (\ie it may create false extrema). 
    205 It is therefore notoriously noisy and must be used in conjunction with an explicit diffusion operator to 
    206 produce a sensible solution. 
    207 The associated time-stepping is performed using a leapfrog scheme in conjunction with an Asselin time-filter, 
    208 so $T$ in (\autoref{eq:tra_adv_cen2}) is the \textit{now} tracer value. 
     227CEN2 is non diffusive (\ie\ it conserves the tracer variance, $\tau^2$) but 
     228dispersive (\ie\ it may create false extrema). 
     229It is therefore notoriously noisy and must be used in conjunction with 
     230an explicit diffusion operator to produce a sensible solution. 
     231The associated time-stepping is performed using 
     232a leapfrog scheme in conjunction with an Asselin time-filter, 
     233so $T$ in (\autoref{eq:TRA_adv_cen2}) is the \textit{now} tracer value. 
    209234 
    210235Note that using the CEN2, the overall tracer advection is of second order accuracy since 
    211 both (\autoref{eq:tra_adv}) and (\autoref{eq:tra_adv_cen2}) have this order of accuracy. 
    212  
    213 %        4nd order centred scheme   
    214  
    215 In the $4^{th}$ order formulation (CEN4), tracer values are evaluated at u- and v-points as 
    216 a $4^{th}$ order interpolation, and thus depend on the four neighbouring $T$-points. 
     236both (\autoref{eq:TRA_adv}) and (\autoref{eq:TRA_adv_cen2}) have this order of accuracy. 
     237 
     238%        4nd order centred scheme 
     239 
     240In the $4^{th}$ order formulation (CEN4), 
     241tracer values are evaluated at u- and v-points as a $4^{th}$ order interpolation, 
     242and thus depend on the four neighbouring $T$-points. 
    217243For example, in the $i$-direction: 
    218244\begin{equation} 
    219   \label{eq:tra_adv_cen4} 
     245  \label{eq:TRA_adv_cen4} 
    220246  \tau_u^{cen4} = \overline{T - \frac{1}{6} \, \delta_i \Big[ \delta_{i + 1/2}[T] \, \Big]}^{\,i + 1/2} 
    221247\end{equation} 
    222 In the vertical direction (\np{nn\_cen\_v}~\forcode{= 4}), 
    223 a $4^{th}$ COMPACT interpolation has been prefered \citep{Demange_PhD2014}. 
    224 In the COMPACT scheme, both the field and its derivative are interpolated, which leads, after a matrix inversion, 
    225 spectral characteristics similar to schemes of higher order \citep{Lele_JCP1992}.  
     248In the vertical direction (\np[=4]{nn_cen_v}{nn\_cen\_v}), 
     249a $4^{th}$ COMPACT interpolation has been prefered \citep{demange_phd14}. 
     250In the COMPACT scheme, both the field and its derivative are interpolated, 
     251which leads, after a matrix inversion, spectral characteristics similar to schemes of higher order 
     252\citep{lele_JCP92}. 
    226253 
    227254Strictly speaking, the CEN4 scheme is not a $4^{th}$ order advection scheme but 
    228255a $4^{th}$ order evaluation of advective fluxes, 
    229 since the divergence of advective fluxes \autoref{eq:tra_adv} is kept at $2^{nd}$ order. 
    230 The expression \textit{$4^{th}$ order scheme} used in oceanographic literature is usually associated with 
    231 the scheme presented here. 
    232 Introducing a \forcode{.true.} $4^{th}$ order advection scheme is feasible but, for consistency reasons, 
    233 it requires changes in the discretisation of the tracer advection together with changes in the continuity equation, 
    234 and the momentum advection and pressure terms. 
     256since the divergence of advective fluxes \autoref{eq:TRA_adv} is kept at $2^{nd}$ order. 
     257The expression \textit{$4^{th}$ order scheme} used in oceanographic literature is 
     258usually associated with the scheme presented here. 
     259Introducing a ``true'' $4^{th}$ order advection scheme is feasible but, for consistency reasons, 
     260it requires changes in the discretisation of the tracer advection together with 
     261changes in the continuity equation, and the momentum advection and pressure terms. 
    235262 
    236263A direct consequence of the pseudo-fourth order nature of the scheme is that it is not non-diffusive, 
    237 \ie the global variance of a tracer is not preserved using CEN4. 
    238 Furthermore, it must be used in conjunction with an explicit diffusion operator to produce a sensible solution. 
    239 As in CEN2 case, the time-stepping is performed using a leapfrog scheme in conjunction with an Asselin time-filter, 
    240 so $T$ in (\autoref{eq:tra_adv_cen4}) is the \textit{now} tracer. 
     264\ie\ the global variance of a tracer is not preserved using CEN4. 
     265Furthermore, it must be used in conjunction with an explicit diffusion operator to 
     266produce a sensible solution. 
     267As in CEN2 case, the time-stepping is performed using a leapfrog scheme in conjunction with 
     268an Asselin time-filter, so $T$ in (\autoref{eq:TRA_adv_cen4}) is the \textit{now} tracer. 
    241269 
    242270At a $T$-grid cell adjacent to a boundary (coastline, bottom and surface), 
     
    244272This hypothesis usually reduces the order of the scheme. 
    245273Here we choose to set the gradient of $T$ across the boundary to zero. 
    246 Alternative conditions can be specified, such as a reduction to a second order scheme for 
    247 these near boundary grid points. 
    248  
    249 % ------------------------------------------------------------------------------------------------------------- 
    250 %        FCT scheme   
    251 % ------------------------------------------------------------------------------------------------------------- 
    252 \subsection{FCT: Flux Corrected Transport scheme (\protect\np{ln\_traadv\_fct}~\forcode{= .true.})} 
     274Alternative conditions can be specified, 
     275such as a reduction to a second order scheme for these near boundary grid points. 
     276 
     277%% ================================================================================================= 
     278\subsection[FCT: Flux Corrected Transport scheme (\forcode{ln_traadv_fct})]{FCT: Flux Corrected Transport scheme (\protect\np{ln_traadv_fct}{ln\_traadv\_fct})} 
    253279\label{subsec:TRA_adv_tvd} 
    254280 
    255 The Flux Corrected Transport schemes (FCT) is used when \np{ln\_traadv\_fct}~\forcode{= .true.}. 
    256 Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) and vertical direction by 
    257 setting \np{nn\_fct\_h} and \np{nn\_fct\_v} to $2$ or $4$. 
     281The \textbf{F}lux \textbf{C}orrected \textbf{T}ransport schemes (FCT) is used when 
     282\np[=.true.]{ln_traadv_fct}{ln\_traadv\_fct}. 
     283Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on 
     284horizontal (iso-level) and vertical direction by 
     285setting \np{nn_fct_h}{nn\_fct\_h} and \np{nn_fct_v}{nn\_fct\_v} to $2$ or $4$. 
    258286FCT implementation can be found in the \mdl{traadv\_fct} module. 
    259287 
    260 In FCT formulation, the tracer at velocity points is evaluated using a combination of an upstream and 
    261 a centred scheme. 
     288In FCT formulation, the tracer at velocity points is evaluated using 
     289a combination of an upstream and a centred scheme. 
    262290For example, in the $i$-direction : 
    263291\begin{equation} 
    264   \label{eq:tra_adv_fct} 
     292  \label{eq:TRA_adv_fct} 
    265293  \begin{split} 
    266294    \tau_u^{ups} &= 
     
    268296                     T_{i + 1} & \text{if~} u_{i + 1/2} <    0 \\ 
    269297                     T_i       & \text{if~} u_{i + 1/2} \geq 0 \\ 
    270     \end{cases} 
    271     \\ 
     298    \end{cases} \\ 
    272299    \tau_u^{fct} &= \tau_u^{ups} + c_u \, \big( \tau_u^{cen} - \tau_u^{ups} \big) 
    273300  \end{split} 
     
    275302where $c_u$ is a flux limiter function taking values between 0 and 1. 
    276303The FCT order is the one of the centred scheme used 
    277 (\ie it depends on the setting of \np{nn\_fct\_h} and \np{nn\_fct\_v}). 
     304(\ie\ it depends on the setting of \np{nn_fct_h}{nn\_fct\_h} and \np{nn_fct_v}{nn\_fct\_v}). 
    278305There exist many ways to define $c_u$, each corresponding to a different FCT scheme. 
    279 The one chosen in \NEMO is described in \citet{Zalesak_JCP79}. 
     306The one chosen in \NEMO\ is described in \citet{zalesak_JCP79}. 
    280307$c_u$ only departs from $1$ when the advective term produces a local extremum in the tracer field. 
    281308The resulting scheme is quite expensive but \textit{positive}. 
    282309It can be used on both active and passive tracers. 
    283 A comparison of FCT-2 with MUSCL and a MPDATA scheme can be found in \citet{Levy_al_GRL01}. 
    284  
    285 An additional option has been added controlled by \np{nn\_fct\_zts}. 
    286 By setting this integer to a value larger than zero, 
    287 a $2^{nd}$ order FCT scheme is used on both horizontal and vertical direction, but on the latter, 
    288 a split-explicit time stepping is used, with a number of sub-timestep equals to \np{nn\_fct\_zts}. 
    289 This option can be useful when the size of the timestep is limited by vertical advection \citep{Lemarie_OM2015}. 
    290 Note that in this case, a similar split-explicit time stepping should be used on vertical advection of momentum to 
    291 insure a better stability (see \autoref{subsec:DYN_zad}). 
    292  
    293 For stability reasons (see \autoref{chap:STP}), 
    294 $\tau_u^{cen}$ is evaluated in (\autoref{eq:tra_adv_fct}) using the \textit{now} tracer while 
     310A comparison of FCT-2 with MUSCL and a MPDATA scheme can be found in \citet{levy.estublier.ea_GRL01}. 
     311 
     312For stability reasons (see \autoref{chap:TD}), 
     313$\tau_u^{cen}$ is evaluated in (\autoref{eq:TRA_adv_fct}) using the \textit{now} tracer while 
    295314$\tau_u^{ups}$ is evaluated using the \textit{before} tracer. 
    296 In other words, the advective part of the scheme is time stepped with a leap-frog scheme 
    297 while a forward scheme is used for the diffusive part. 
    298  
    299 % ------------------------------------------------------------------------------------------------------------- 
    300 %        MUSCL scheme   
    301 % ------------------------------------------------------------------------------------------------------------- 
    302 \subsection{MUSCL: Monotone Upstream Scheme for Conservative Laws (\protect\np{ln\_traadv\_mus}~\forcode{= .true.})} 
     315In other words, the advective part of the scheme is time stepped with a leap-frog scheme while 
     316a forward scheme is used for the diffusive part. 
     317 
     318%% ================================================================================================= 
     319\subsection[MUSCL: Monotone Upstream Scheme for Conservative Laws (\forcode{ln_traadv_mus})]{MUSCL: Monotone Upstream Scheme for Conservative Laws (\protect\np{ln_traadv_mus}{ln\_traadv\_mus})} 
    303320\label{subsec:TRA_adv_mus} 
    304321 
    305 The Monotone Upstream Scheme for Conservative Laws (MUSCL) is used when \np{ln\_traadv\_mus}~\forcode{= .true.}. 
     322The \textbf{M}onotone \textbf{U}pstream \textbf{S}cheme for \textbf{C}onservative \textbf{L}aws 
     323(MUSCL) is used when \np[=.true.]{ln_traadv_mus}{ln\_traadv\_mus}. 
    306324MUSCL implementation can be found in the \mdl{traadv\_mus} module. 
    307325 
    308 MUSCL has been first implemented in \NEMO by \citet{Levy_al_GRL01}. 
    309 In its formulation, the tracer at velocity points is evaluated assuming a linear tracer variation between 
    310 two $T$-points (\autoref{fig:adv_scheme}). 
     326MUSCL has been first implemented in \NEMO\ by \citet{levy.estublier.ea_GRL01}. 
     327In its formulation, the tracer at velocity points is evaluated assuming 
     328a linear tracer variation between two $T$-points (\autoref{fig:TRA_adv_scheme}). 
    311329For example, in the $i$-direction : 
    312 \begin{equation} 
    313   % \label{eq:tra_adv_mus} 
     330\[ 
     331  % \label{eq:TRA_adv_mus} 
    314332  \tau_u^{mus} = \lt\{ 
    315333  \begin{split} 
    316                        \tau_i         &+ \frac{1}{2} \lt( 1 - \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt) 
    317                        \widetilde{\partial_i         \tau} & \text{if~} u_{i + 1/2} \geqslant 0 \\ 
    318                        \tau_{i + 1/2} &+ \frac{1}{2} \lt( 1 + \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt) 
    319                        \widetilde{\partial_{i + 1/2} \tau} & \text{if~} u_{i + 1/2} <         0 
     334    \tau_i        &+ \frac{1}{2} \lt( 1 - \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt) 
     335    \widetilde{\partial_i        \tau} & \text{if~} u_{i + 1/2} \geqslant 0 \\ 
     336    \tau_{i + 1/2} &+ \frac{1}{2} \lt( 1 + \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt) 
     337    \widetilde{\partial_{i + 1/2} \tau} & \text{if~} u_{i + 1/2} <         0 
    320338  \end{split} 
    321339                                                                                                      \rt. 
    322 \end{equation} 
    323 where $\widetilde{\partial_i \tau}$ is the slope of the tracer on which a limitation is imposed to 
    324 ensure the \textit{positive} character of the scheme. 
    325  
    326 The time stepping is performed using a forward scheme, that is the \textit{before} tracer field is used to 
    327 evaluate $\tau_u^{mus}$. 
     340\] 
     341where $\widetilde{\partial_i \tau}$ is the slope of the tracer on which 
     342a limitation is imposed to ensure the \textit{positive} character of the scheme. 
     343 
     344The time stepping is performed using a forward scheme, 
     345that is the \textit{before} tracer field is used to evaluate $\tau_u^{mus}$. 
    328346 
    329347For an ocean grid point adjacent to land and where the ocean velocity is directed toward land, 
    330348an upstream flux is used. 
    331349This choice ensure the \textit{positive} character of the scheme. 
    332 In addition, fluxes round a grid-point where a runoff is applied can optionally be computed using upstream fluxes 
    333 (\np{ln\_mus\_ups}~\forcode{= .true.}). 
    334  
    335 % ------------------------------------------------------------------------------------------------------------- 
    336 %        UBS scheme   
    337 % ------------------------------------------------------------------------------------------------------------- 
    338 \subsection{UBS a.k.a. UP3: Upstream-Biased Scheme (\protect\np{ln\_traadv\_ubs}~\forcode{= .true.})} 
     350In addition, fluxes round a grid-point where a runoff is applied can optionally be computed using 
     351upstream fluxes (\np[=.true.]{ln_mus_ups}{ln\_mus\_ups}). 
     352 
     353%% ================================================================================================= 
     354\subsection[UBS a.k.a. UP3: Upstream-Biased Scheme (\forcode{ln_traadv_ubs})]{UBS a.k.a. UP3: Upstream-Biased Scheme (\protect\np{ln_traadv_ubs}{ln\_traadv\_ubs})} 
    339355\label{subsec:TRA_adv_ubs} 
    340356 
    341 The Upstream-Biased Scheme (UBS) is used when \np{ln\_traadv\_ubs}~\forcode{= .true.}. 
     357The \textbf{U}pstream-\textbf{B}iased \textbf{S}cheme (UBS) is used when 
     358\np[=.true.]{ln_traadv_ubs}{ln\_traadv\_ubs}. 
    342359UBS implementation can be found in the \mdl{traadv\_mus} module. 
    343360 
    344361The UBS scheme, often called UP3, is also known as the Cell Averaged QUICK scheme 
    345 (Quadratic Upstream Interpolation for Convective Kinematics). 
     362(\textbf{Q}uadratic \textbf{U}pstream \textbf{I}nterpolation for 
     363\textbf{C}onvective \textbf{K}inematics). 
    346364It is an upstream-biased third order scheme based on an upstream-biased parabolic interpolation. 
    347365For example, in the $i$-direction: 
    348366\begin{equation} 
    349   \label{eq:tra_adv_ubs} 
     367  \label{eq:TRA_adv_ubs} 
    350368  \tau_u^{ubs} = \overline T ^{i + 1/2} - \frac{1}{6} 
    351369    \begin{cases} 
    352                                                       \tau"_i       & \text{if~} u_{i + 1/2} \geqslant 0 \\ 
    353                                                       \tau"_{i + 1} & \text{if~} u_{i + 1/2} <         0 
     370      \tau"_i       & \text{if~} u_{i + 1/2} \geqslant 0 \\ 
     371      \tau"_{i + 1} & \text{if~} u_{i + 1/2} <         0 
    354372    \end{cases} 
    355   \quad 
    356   \text{where~} \tau"_i = \delta_i \lt[ \delta_{i + 1/2} [\tau] \rt] 
     373  \quad \text{where~} \tau"_i = \delta_i \lt[ \delta_{i + 1/2} [\tau] \rt] 
    357374\end{equation} 
    358375 
    359376This results in a dissipatively dominant (i.e. hyper-diffusive) truncation error 
    360 \citep{Shchepetkin_McWilliams_OM05}. 
    361 The overall performance of the advection scheme is similar to that reported in \cite{Farrow1995}. 
     377\citep{shchepetkin.mcwilliams_OM05}. 
     378The overall performance of the advection scheme is similar to that reported in 
     379\cite{farrow.stevens_JPO95}. 
    362380It is a relatively good compromise between accuracy and smoothness. 
    363381Nevertheless the scheme is not \textit{positive}, meaning that false extrema are permitted, 
    364382but the amplitude of such are significantly reduced over the centred second or fourth order method. 
    365 Therefore it is not recommended that it should be applied to a passive tracer that requires positivity. 
     383Therefore it is not recommended that it should be applied to 
     384a passive tracer that requires positivity. 
    366385 
    367386The intrinsic diffusion of UBS makes its use risky in the vertical direction where 
    368387the control of artificial diapycnal fluxes is of paramount importance 
    369 \citep{Shchepetkin_McWilliams_OM05, Demange_PhD2014}. 
    370 Therefore the vertical flux is evaluated using either a $2^nd$ order FCT scheme or a $4^th$ order COMPACT scheme 
    371 (\np{nn\_cen\_v}~\forcode{= 2 or 4}). 
    372  
    373 For stability reasons (see \autoref{chap:STP}), the first term  in \autoref{eq:tra_adv_ubs} 
    374 (which corresponds to a second order centred scheme) 
    375 is evaluated using the \textit{now} tracer (centred in time) while the second term 
    376 (which is the diffusive part of the scheme), 
     388\citep{shchepetkin.mcwilliams_OM05, demange_phd14}. 
     389Therefore the vertical flux is evaluated using either a $2^nd$ order FCT scheme or 
     390a $4^th$ order COMPACT scheme (\np[=2 or 4]{nn_ubs_v}{nn\_ubs\_v}). 
     391 
     392For stability reasons (see \autoref{chap:TD}), 
     393the first term  in \autoref{eq:TRA_adv_ubs} (which corresponds to a second order centred scheme) 
     394is evaluated using the \textit{now}    tracer (centred in time) while 
     395the second term (which is the diffusive part of the scheme), 
    377396is evaluated using the \textit{before} tracer (forward in time). 
    378 This choice is discussed by \citet{Webb_al_JAOT98} in the context of the QUICK advection scheme. 
     397This choice is discussed by \citet{webb.de-cuevas.ea_JAOT98} in 
     398the context of the QUICK advection scheme. 
    379399UBS and QUICK schemes only differ by one coefficient. 
    380 Replacing 1/6 with 1/8 in \autoref{eq:tra_adv_ubs} leads to the QUICK advection scheme \citep{Webb_al_JAOT98}. 
     400Replacing 1/6 with 1/8 in \autoref{eq:TRA_adv_ubs} leads to the QUICK advection scheme 
     401\citep{webb.de-cuevas.ea_JAOT98}. 
    381402This option is not available through a namelist parameter, since the 1/6 coefficient is hard coded. 
    382 Nevertheless it is quite easy to make the substitution in the \mdl{traadv\_ubs} module and obtain a QUICK scheme. 
    383  
    384 Note that it is straightforward to rewrite \autoref{eq:tra_adv_ubs} as follows: 
     403Nevertheless it is quite easy to make the substitution in the \mdl{traadv\_ubs} module and 
     404obtain a QUICK scheme. 
     405 
     406Note that it is straightforward to rewrite \autoref{eq:TRA_adv_ubs} as follows: 
    385407\begin{gather} 
    386   \label{eq:traadv_ubs2} 
     408  \label{eq:TRA_adv_ubs2} 
    387409  \tau_u^{ubs} = \tau_u^{cen4} + \frac{1}{12} 
    388410    \begin{cases} 
     
    391413    \end{cases} 
    392414  \intertext{or equivalently} 
    393   % \label{eq:traadv_ubs2b} 
     415  % \label{eq:TRA_adv_ubs2b} 
    394416  u_{i + 1/2} \ \tau_u^{ubs} = u_{i + 1/2} \, \overline{T - \frac{1}{6} \, \delta_i \Big[ \delta_{i + 1/2}[T] \Big]}^{\,i + 1/2} 
    395417                             - \frac{1}{2} |u|_{i + 1/2} \, \frac{1}{6} \, \delta_{i + 1/2} [\tau"_i] \nonumber 
    396418\end{gather} 
    397419 
    398 \autoref{eq:traadv_ubs2} has several advantages. 
     420\autoref{eq:TRA_adv_ubs2} has several advantages. 
    399421Firstly, it clearly reveals that the UBS scheme is based on the fourth order scheme to which 
    400422an upstream-biased diffusion term is added. 
    401 Secondly, this emphasises that the $4^{th}$ order part (as well as the $2^{nd}$ order part as stated above) has to 
    402 be evaluated at the \textit{now} time step using \autoref{eq:tra_adv_ubs}. 
    403 Thirdly, the diffusion term is in fact a biharmonic operator with an eddy coefficient which 
    404 is simply proportional to the velocity: $A_u^{lm} = \frac{1}{12} \, {e_{1u}}^3 \, |u|$. 
    405 Note the current version of NEMO uses the computationally more efficient formulation \autoref{eq:tra_adv_ubs}. 
    406  
    407 % ------------------------------------------------------------------------------------------------------------- 
    408 %        QCK scheme   
    409 % ------------------------------------------------------------------------------------------------------------- 
    410 \subsection{QCK: QuiCKest scheme (\protect\np{ln\_traadv\_qck}~\forcode{= .true.})} 
     423Secondly, 
     424this emphasises that the $4^{th}$ order part (as well as the $2^{nd}$ order part as stated above) has to be evaluated at the \textit{now} time step using \autoref{eq:TRA_adv_ubs}. 
     425Thirdly, the diffusion term is in fact a biharmonic operator with 
     426an eddy coefficient which is simply proportional to the velocity: 
     427$A_u^{lm} = \frac{1}{12} \, {e_{1u}}^3 \, |u|$. 
     428Note the current version of \NEMO\ uses the computationally more efficient formulation 
     429\autoref{eq:TRA_adv_ubs}. 
     430 
     431%% ================================================================================================= 
     432\subsection[QCK: QuiCKest scheme (\forcode{ln_traadv_qck})]{QCK: QuiCKest scheme (\protect\np{ln_traadv_qck}{ln\_traadv\_qck})} 
    411433\label{subsec:TRA_adv_qck} 
    412434 
    413 The Quadratic Upstream Interpolation for Convective Kinematics with Estimated Streaming Terms (QUICKEST) scheme 
    414 proposed by \citet{Leonard1979} is used when \np{ln\_traadv\_qck}~\forcode{= .true.}. 
     435The \textbf{Q}uadratic \textbf{U}pstream \textbf{I}nterpolation for 
     436\textbf{C}onvective \textbf{K}inematics with \textbf{E}stimated \textbf{S}treaming \textbf{T}erms 
     437(QUICKEST) scheme proposed by \citet{leonard_CMAME79} is used when 
     438\np[=.true.]{ln_traadv_qck}{ln\_traadv\_qck}. 
    415439QUICKEST implementation can be found in the \mdl{traadv\_qck} module. 
    416440 
    417441QUICKEST is the third order Godunov scheme which is associated with the ULTIMATE QUICKEST limiter 
    418 \citep{Leonard1991}. 
    419 It has been implemented in NEMO by G. Reffray (MERCATOR-ocean) and can be found in the \mdl{traadv\_qck} module. 
     442\citep{leonard_CMAME91}. 
     443It has been implemented in \NEMO\ by G. Reffray (Mercator Ocean) and 
     444can be found in the \mdl{traadv\_qck} module. 
    420445The resulting scheme is quite expensive but \textit{positive}. 
    421446It can be used on both active and passive tracers. 
     
    424449Therefore the vertical flux is evaluated using the CEN2 scheme. 
    425450This no longer guarantees the positivity of the scheme. 
    426 The use of FCT in the vertical direction (as for the UBS case) should be implemented to restore this property. 
    427  
    428 %%%gmcomment   :  Cross term are missing in the current implementation.... 
    429  
    430 % ================================================================ 
    431 % Tracer Lateral Diffusion 
    432 % ================================================================ 
    433 \section{Tracer lateral diffusion (\protect\mdl{traldf})} 
     451The use of FCT in the vertical direction (as for the UBS case) should be implemented to 
     452restore this property. 
     453 
     454\cmtgm{Cross term are missing in the current implementation....} 
     455 
     456%% ================================================================================================= 
     457\section[Tracer lateral diffusion (\textit{traldf.F90})]{Tracer lateral diffusion (\protect\mdl{traldf})} 
    434458\label{sec:TRA_ldf} 
    435 %-----------------------------------------nam_traldf------------------------------------------------------ 
    436  
    437 \nlst{namtra_ldf} 
    438 %------------------------------------------------------------------------------------------------------------- 
    439   
    440 Options are defined through the \ngn{namtra\_ldf} namelist variables. 
    441 They are regrouped in four items, allowing to specify  
    442 $(i)$   the type of operator used (none, laplacian, bilaplacian), 
    443 $(ii)$  the direction along which the operator acts (iso-level, horizontal, iso-neutral), 
    444 $(iii)$ some specific options related to the rotated operators (\ie non-iso-level operator), and 
    445 $(iv)$  the specification of eddy diffusivity coefficient (either constant or variable in space and time). 
    446 Item $(iv)$ will be described in \autoref{chap:LDF}. 
     459 
     460\begin{listing} 
     461  \nlst{namtra_ldf} 
     462  \caption{\forcode{&namtra_ldf}} 
     463  \label{lst:namtra_ldf} 
     464\end{listing} 
     465 
     466Options are defined through the \nam{tra_ldf}{tra\_ldf} namelist variables. 
     467They are regrouped in four items, allowing to specify 
     468\begin{enumerate*}[label=(\textit{\roman*})] 
     469\item the type of operator used (none, laplacian, bilaplacian), 
     470\item the direction along which the operator acts (iso-level, horizontal, iso-neutral), 
     471\item some specific options related to the rotated operators (\ie\ non-iso-level operator), and 
     472\item the specification of eddy diffusivity coefficient 
     473  (either constant or variable in space and time). 
     474\end{enumerate*} 
     475Item (iv) will be described in \autoref{chap:LDF}. 
    447476The direction along which the operators act is defined through the slope between 
    448477this direction and the iso-level surfaces. 
     
    450479 
    451480The lateral diffusion of tracers is evaluated using a forward scheme, 
    452 \ie the tracers appearing in its expression are the \textit{before} tracers in time, 
     481\ie\ the tracers appearing in its expression are the \textit{before} tracers in time, 
    453482except for the pure vertical component that appears when a rotation tensor is used. 
    454 This latter component is solved implicitly together with the vertical diffusion term (see \autoref{chap:STP}). 
    455 When \np{ln\_traldf\_msc}~\forcode{= .true.}, a Method of Stabilizing Correction is used in which 
    456 the pure vertical component is split into an explicit and an implicit part \citep{Lemarie_OM2012}. 
    457  
    458 % ------------------------------------------------------------------------------------------------------------- 
    459 %        Type of operator 
    460 % ------------------------------------------------------------------------------------------------------------- 
    461 \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}) }  
     483This latter component is solved implicitly together with the vertical diffusion term 
     484(see \autoref{chap:TD}). 
     485When \np[=.true.]{ln_traldf_msc}{ln\_traldf\_msc}, 
     486a Method of Stabilizing Correction is used in which the pure vertical component is split into 
     487an explicit and an implicit part \citep{lemarie.debreu.ea_OM12}. 
     488 
     489%% ================================================================================================= 
     490\subsection[Type of operator (\forcode{ln_traldf_}\{\forcode{OFF,lap,blp}\})]{Type of operator (\protect\np{ln_traldf_OFF}{ln\_traldf\_OFF}, \protect\np{ln_traldf_lap}{ln\_traldf\_lap}, or \protect\np{ln_traldf_blp}{ln\_traldf\_blp})} 
    462491\label{subsec:TRA_ldf_op} 
    463492 
     
    465494 
    466495\begin{description} 
    467 \item[\np{ln\_traldf\_NONE}~\forcode{= .true.}:] 
    468   no operator selected, the lateral diffusive tendency will not be applied to the tracer equation. 
    469   This option can be used when the selected advection scheme is diffusive enough (MUSCL scheme for example). 
    470 \item[\np{ln\_traldf\_lap}~\forcode{= .true.}:] 
    471   a laplacian operator is selected. 
    472   This harmonic operator takes the following expression:  $\mathpzc{L}(T) = \nabla \cdot A_{ht} \; \nabla T $, 
     496\item [{\np[=.true.]{ln_traldf_OFF}{ln\_traldf\_OFF}}] no operator selected, 
     497  the lateral diffusive tendency will not be applied to the tracer equation. 
     498  This option can be used when the selected advection scheme is diffusive enough 
     499  (MUSCL scheme for example). 
     500\item [{\np[=.true.]{ln_traldf_lap}{ln\_traldf\_lap}}] a laplacian operator is selected. 
     501  This harmonic operator takes the following expression: 
     502  $\mathcal{L}(T) = \nabla \cdot A_{ht} \; \nabla T $, 
    473503  where the gradient operates along the selected direction (see \autoref{subsec:TRA_ldf_dir}), 
    474504  and $A_{ht}$ is the eddy diffusivity coefficient expressed in $m^2/s$ (see \autoref{chap:LDF}). 
    475 \item[\np{ln\_traldf\_blp}~\forcode{= .true.}]: 
    476   a bilaplacian operator is selected. 
     505\item [{\np[=.true.]{ln_traldf_blp}{ln\_traldf\_blp}}] a bilaplacian operator is selected. 
    477506  This biharmonic operator takes the following expression: 
    478   $\mathpzc{B} = - \mathpzc{L}(\mathpzc{L}(T)) = - \nabla \cdot b \nabla (\nabla \cdot b \nabla T)$ 
     507  $\mathcal{B} = - \mathcal{L}(\mathcal{L}(T)) = - \nabla \cdot b \nabla (\nabla \cdot b \nabla T)$ 
    479508  where the gradient operats along the selected direction, 
    480   and $b^2 = B_{ht}$ is the eddy diffusivity coefficient expressed in $m^4/s$ (see \autoref{chap:LDF}). 
     509  and $b^2 = B_{ht}$ is the eddy diffusivity coefficient expressed in $m^4/s$ 
     510  (see \autoref{chap:LDF}). 
    481511  In the code, the bilaplacian operator is obtained by calling the laplacian twice. 
    482512\end{description} 
     
    486516minimizing the impact on the larger scale features. 
    487517The main difference between the two operators is the scale selectiveness. 
    488 The bilaplacian damping time (\ie its spin down time) scales like $\lambda^{-4}$ for 
    489 disturbances of wavelength $\lambda$ (so that short waves damped more rapidelly than long ones), 
     518The bilaplacian damping time (\ie\ its spin down time) scales like 
     519$\lambda^{-4}$ for disturbances of wavelength $\lambda$ 
     520(so that short waves damped more rapidelly than long ones), 
    490521whereas the laplacian damping time scales only like $\lambda^{-2}$. 
    491522 
    492 % ------------------------------------------------------------------------------------------------------------- 
    493 %        Direction of action 
    494 % ------------------------------------------------------------------------------------------------------------- 
    495 \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}) }  
     523%% ================================================================================================= 
     524\subsection[Action direction (\forcode{ln_traldf_}\{\forcode{lev,hor,iso,triad}\})]{Direction of action (\protect\np{ln_traldf_lev}{ln\_traldf\_lev}, \protect\np{ln_traldf_hor}{ln\_traldf\_hor}, \protect\np{ln_traldf_iso}{ln\_traldf\_iso}, or \protect\np{ln_traldf_triad}{ln\_traldf\_triad})} 
    496525\label{subsec:TRA_ldf_dir} 
    497526 
    498527The choice of a direction of action determines the form of operator used. 
    499528The operator is a simple (re-entrant) laplacian acting in the (\textbf{i},\textbf{j}) plane when 
    500 iso-level option is used (\np{ln\_traldf\_lev}~\forcode{= .true.}) or 
    501 when a horizontal (\ie geopotential) operator is demanded in \textit{z}-coordinate 
    502 (\np{ln\_traldf\_hor} and \np{ln\_zco} equal \forcode{.true.}). 
     529iso-level option is used (\np[=.true.]{ln_traldf_lev}{ln\_traldf\_lev}) or when 
     530a horizontal (\ie\ geopotential) operator is demanded in \textit{z}-coordinate 
     531(\np{ln_traldf_hor}{ln\_traldf\_hor} and \np[=.true.]{ln_zco}{ln\_zco}). 
    503532The associated code can be found in the \mdl{traldf\_lap\_blp} module. 
    504533The operator is a rotated (re-entrant) laplacian when 
    505534the direction along which it acts does not coincide with the iso-level surfaces, 
    506535that is when standard or triad iso-neutral option is used 
    507 (\np{ln\_traldf\_iso} or \np{ln\_traldf\_triad} equals \forcode{.true.}, 
     536(\np{ln_traldf_iso}{ln\_traldf\_iso} or \np{ln_traldf_triad}{ln\_traldf\_triad} = \forcode{.true.}, 
    508537see \mdl{traldf\_iso} or \mdl{traldf\_triad} module, resp.), or 
    509 when a horizontal (\ie geopotential) operator is demanded in \textit{s}-coordinate 
    510 (\np{ln\_traldf\_hor} and \np{ln\_sco} equal \forcode{.true.}) 
    511 \footnote{In this case, the standard iso-neutral operator will be automatically selected}. 
     538when a horizontal (\ie\ geopotential) operator is demanded in \textit{s}-coordinate 
     539(\np{ln_traldf_hor}{ln\_traldf\_hor} and \np{ln_sco}{ln\_sco} = \forcode{.true.}) \footnote{ 
     540  In this case, the standard iso-neutral operator will be automatically selected}. 
    512541In that case, a rotation is applied to the gradient(s) that appears in the operator so that 
    513542diffusive fluxes acts on the three spatial direction. 
     
    516545the next two sub-sections. 
    517546 
    518 % ------------------------------------------------------------------------------------------------------------- 
    519 %       iso-level operator 
    520 % ------------------------------------------------------------------------------------------------------------- 
    521 \subsection{Iso-level (bi -)laplacian operator ( \protect\np{ln\_traldf\_iso}) } 
     547%% ================================================================================================= 
     548\subsection[Iso-level (bi-)laplacian operator (\forcode{ln_traldf_iso})]{Iso-level (bi-)laplacian operator ( \protect\np{ln_traldf_iso}{ln\_traldf\_iso})} 
    522549\label{subsec:TRA_ldf_lev} 
    523550 
    524 The laplacian diffusion operator acting along the model (\textit{i,j})-surfaces is given by:  
    525 \begin{equation} 
    526   \label{eq:tra_ldf_lap} 
     551The laplacian diffusion operator acting along the model (\textit{i,j})-surfaces is given by: 
     552\begin{equation} 
     553  \label{eq:TRA_ldf_lap} 
    527554  D_t^{lT} = \frac{1}{b_t} \Bigg(   \delta_{i} \lt[ A_u^{lT} \; \frac{e_{2u} \, e_{3u}}{e_{1u}} \; \delta_{i + 1/2} [T] \rt] 
    528555                                  + \delta_{j} \lt[ A_v^{lT} \; \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [T] \rt] \Bigg) 
     
    531558where zero diffusive fluxes is assumed across solid boundaries, 
    532559first (and third in bilaplacian case) horizontal tracer derivative are masked. 
    533 It is implemented in the \rou{traldf\_lap} subroutine found in the \mdl{traldf\_lap} module. 
    534 The module also contains \rou{traldf\_blp}, the subroutine calling twice \rou{traldf\_lap} in order to 
     560It is implemented in the \rou{tra\_ldf\_lap} subroutine found in the \mdl{traldf\_lap\_blp} module. 
     561The module also contains \rou{tra\_ldf\_blp}, 
     562the subroutine calling twice \rou{tra\_ldf\_lap} in order to 
    535563compute the iso-level bilaplacian operator. 
    536564 
    537565It is a \textit{horizontal} operator (\ie acting along geopotential surfaces) in 
    538 the $z$-coordinate with or without partial steps, but is simply an iso-level operator in the $s$-coordinate. 
    539 It is thus used when, in addition to \np{ln\_traldf\_lap} or \np{ln\_traldf\_blp}~\forcode{= .true.}, 
    540 we have \np{ln\_traldf\_lev}~\forcode{= .true.} or \np{ln\_traldf\_hor}~=~\np{ln\_zco}~\forcode{= .true.}. 
     566the $z$-coordinate with or without partial steps, 
     567but is simply an iso-level operator in the $s$-coordinate. 
     568It is thus used when, 
     569in addition to \np{ln_traldf_lap}{ln\_traldf\_lap} or \np[=.true.]{ln_traldf_blp}{ln\_traldf\_blp}, 
     570we have \np[=.true.]{ln_traldf_lev}{ln\_traldf\_lev} or 
     571\np[=]{ln_traldf_hor}{ln\_traldf\_hor}\np[=.true.]{ln_zco}{ln\_zco}. 
    541572In both cases, it significantly contributes to diapycnal mixing. 
    542573It is therefore never recommended, even when using it in the bilaplacian case. 
    543574 
    544 Note that in the partial step $z$-coordinate (\np{ln\_zps}~\forcode{= .true.}), 
     575Note that in the partial step $z$-coordinate (\np[=.true.]{ln_zps}{ln\_zps}), 
    545576tracers in horizontally adjacent cells are located at different depths in the vicinity of the bottom. 
    546 In this case, horizontal derivatives in (\autoref{eq:tra_ldf_lap}) at the bottom level require a specific treatment. 
     577In this case, 
     578horizontal derivatives in (\autoref{eq:TRA_ldf_lap}) at the bottom level require a specific treatment. 
    547579They are calculated in the \mdl{zpshde} module, described in \autoref{sec:TRA_zpshde}. 
    548580 
    549 % ------------------------------------------------------------------------------------------------------------- 
    550 %         Rotated laplacian operator 
    551 % ------------------------------------------------------------------------------------------------------------- 
    552 \subsection{Standard and triad (bi -)laplacian operator} 
     581%% ================================================================================================= 
     582\subsection{Standard and triad (bi-)laplacian operator} 
    553583\label{subsec:TRA_ldf_iso_triad} 
    554584 
    555 %&&    Standard rotated (bi -)laplacian operator 
    556 %&& ---------------------------------------------- 
    557 \subsubsection{Standard rotated (bi -)laplacian operator (\protect\mdl{traldf\_iso})} 
     585%% ================================================================================================= 
     586\subsubsection[Standard rotated (bi-)laplacian operator (\textit{traldf\_iso.F90})]{Standard rotated (bi-)laplacian operator (\protect\mdl{traldf\_iso})} 
    558587\label{subsec:TRA_ldf_iso} 
    559 The general form of the second order lateral tracer subgrid scale physics (\autoref{eq:PE_zdf}) 
    560 takes the following semi -discrete space form in $z$- and $s$-coordinates: 
    561 \begin{equation} 
    562   \label{eq:tra_ldf_iso} 
     588 
     589The general form of the second order lateral tracer subgrid scale physics (\autoref{eq:MB_zdf}) 
     590takes the following semi-discrete space form in $z$- and $s$-coordinates: 
     591\begin{equation} 
     592  \label{eq:TRA_ldf_iso} 
    563593  \begin{split} 
    564594    D_T^{lT} = \frac{1}{b_t} \Bigg[ \quad &\delta_i A_u^{lT} \lt( \frac{e_{2u} e_{3u}}{e_{1u}}                      \, \delta_{i + 1/2} [T] 
     
    573603where $b_t = e_{1t} \, e_{2t} \, e_{3t}$  is the volume of $T$-cells, 
    574604$r_1$ and $r_2$ are the slopes between the surface of computation ($z$- or $s$-surfaces) and 
    575 the surface along which the diffusion operator acts (\ie horizontal or iso-neutral surfaces). 
    576 It is thus used when, in addition to \np{ln\_traldf\_lap}~\forcode{= .true.}, 
    577 we have \np{ln\_traldf\_iso}~\forcode{= .true.}, 
    578 or both \np{ln\_traldf\_hor}~\forcode{= .true.} and \np{ln\_zco}~\forcode{= .true.}. 
     605the surface along which the diffusion operator acts (\ie\ horizontal or iso-neutral surfaces). 
     606It is thus used when, in addition to \np[=.true.]{ln_traldf_lap}{ln\_traldf\_lap}, 
     607we have \np[=.true.]{ln_traldf_iso}{ln\_traldf\_iso}, 
     608or both \np[=.true.]{ln_traldf_hor}{ln\_traldf\_hor} and \np[=.true.]{ln_zco}{ln\_zco}. 
    579609The way these slopes are evaluated is given in \autoref{sec:LDF_slp}. 
    580 At the surface, bottom and lateral boundaries, the turbulent fluxes of heat and salt are set to zero using 
    581 the mask technique (see \autoref{sec:LBC_coast}). 
    582  
    583 The operator in \autoref{eq:tra_ldf_iso} involves both lateral and vertical derivatives. 
    584 For numerical stability, the vertical second derivative must be solved using the same implicit time scheme as that 
    585 used in the vertical physics (see \autoref{sec:TRA_zdf}). 
     610At the surface, bottom and lateral boundaries, 
     611the turbulent fluxes of heat and salt are set to zero using the mask technique 
     612(see \autoref{sec:LBC_coast}). 
     613 
     614The operator in \autoref{eq:TRA_ldf_iso} involves both lateral and vertical derivatives. 
     615For numerical stability, the vertical second derivative must be solved using 
     616the same implicit time scheme as that used in the vertical physics (see \autoref{sec:TRA_zdf}). 
    586617For computer efficiency reasons, this term is not computed in the \mdl{traldf\_iso} module, 
    587618but in the \mdl{trazdf} module where, if iso-neutral mixing is used, 
    588 the vertical mixing coefficient is simply increased by $\frac{e_{1w} e_{2w}}{e_{3w}}(r_{1w}^2 + r_{2w}^2)$. 
     619the vertical mixing coefficient is simply increased by 
     620$\frac{e_{1w} e_{2w}}{e_{3w}}(r_{1w}^2 + r_{2w}^2)$. 
    589621 
    590622This formulation conserves the tracer but does not ensure the decrease of the tracer variance. 
    591 Nevertheless the treatment performed on the slopes (see \autoref{chap:LDF}) allows the model to run safely without 
    592 any additional background horizontal diffusion \citep{Guilyardi_al_CD01}. 
    593  
    594 Note that in the partial step $z$-coordinate (\np{ln\_zps}~\forcode{= .true.}), 
    595 the horizontal derivatives at the bottom level in \autoref{eq:tra_ldf_iso} require a specific treatment. 
     623Nevertheless the treatment performed on the slopes (see \autoref{chap:LDF}) allows the model to 
     624run safely without any additional background horizontal diffusion \citep{guilyardi.madec.ea_CD01}. 
     625 
     626Note that in the partial step $z$-coordinate (\np[=.true.]{ln_zps}{ln\_zps}), 
     627the horizontal derivatives at the bottom level in \autoref{eq:TRA_ldf_iso} require 
     628a specific treatment. 
    596629They are calculated in module zpshde, described in \autoref{sec:TRA_zpshde}. 
    597630 
    598 %&&     Triad rotated (bi -)laplacian operator 
    599 %&&  ------------------------------------------- 
    600 \subsubsection{Triad rotated (bi -)laplacian operator (\protect\np{ln\_traldf\_triad})} 
     631%% ================================================================================================= 
     632\subsubsection[Triad rotated (bi-)laplacian operator (\forcode{ln_traldf_triad})]{Triad rotated (bi-)laplacian operator (\protect\np{ln_traldf_triad}{ln\_traldf\_triad})} 
    601633\label{subsec:TRA_ldf_triad} 
    602634 
    603 If the Griffies triad scheme is employed (\np{ln\_traldf\_triad}~\forcode{= .true.}; see \autoref{apdx:triad}) 
    604  
    605 An alternative scheme developed by \cite{Griffies_al_JPO98} which ensures tracer variance decreases 
    606 is also available in \NEMO (\np{ln\_traldf\_grif}~\forcode{= .true.}). 
    607 A complete description of the algorithm is given in \autoref{apdx:triad}. 
    608  
    609 The lateral fourth order bilaplacian operator on tracers is obtained by applying (\autoref{eq:tra_ldf_lap}) twice. 
     635An alternative scheme developed by \cite{griffies.gnanadesikan.ea_JPO98} which 
     636ensures tracer variance decreases is also available in \NEMO\ 
     637(\np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}). 
     638A complete description of the algorithm is given in \autoref{apdx:TRIADS}. 
     639 
     640The lateral fourth order bilaplacian operator on tracers is obtained by 
     641applying (\autoref{eq:TRA_ldf_lap}) twice. 
    610642The operator requires an additional assumption on boundary conditions: 
    611643both first and third derivative terms normal to the coast are set to zero. 
    612644 
    613 The lateral fourth order operator formulation on tracers is obtained by applying (\autoref{eq:tra_ldf_iso}) twice. 
     645The lateral fourth order operator formulation on tracers is obtained by 
     646applying (\autoref{eq:TRA_ldf_iso}) twice. 
    614647It requires an additional assumption on boundary conditions: 
    615648first and third derivative terms normal to the coast, 
    616649normal to the bottom and normal to the surface are set to zero. 
    617650 
    618 %&&    Option for the rotated operators 
    619 %&& ---------------------------------------------- 
     651%% ================================================================================================= 
    620652\subsubsection{Option for the rotated operators} 
    621653\label{subsec:TRA_ldf_options} 
    622654 
    623 \begin{itemize} 
    624 \item \np{ln\_traldf\_msc} = Method of Stabilizing Correction (both operators) 
    625 \item \np{rn\_slpmax} = slope limit (both operators) 
    626 \item \np{ln\_triad\_iso} = pure horizontal mixing in ML (triad only) 
    627 \item \np{rn\_sw\_triad} $= 1$ switching triad; $= 0$ all 4 triads used (triad only)  
    628 \item \np{ln\_botmix\_triad} = lateral mixing on bottom (triad only) 
    629 \end{itemize} 
    630  
    631 % ================================================================ 
    632 % Tracer Vertical Diffusion 
    633 % ================================================================ 
    634 \section{Tracer vertical diffusion (\protect\mdl{trazdf})} 
     655\begin{labeling}{{\np{ln_botmix_triad}{ln\_botmix\_triad}}} 
     656\item [{\np{ln_traldf_msc}{ln\_traldf\_msc}    }] Method of Stabilizing Correction (both operators) 
     657\item [{\np{rn_slpmax}{rn\_slpmax}             }] Slope limit (both operators) 
     658\item [{\np{ln_triad_iso}{ln\_triad\_iso}      }] Pure horizontal mixing in ML (triad only) 
     659\item [{\np{rn_sw_triad}{rn\_sw\_triad}        }] \forcode{=1} switching triad; 
     660  \forcode{= 0} all 4 triads used (triad only) 
     661\item [{\np{ln_botmix_triad}{ln\_botmix\_triad}}] Lateral mixing on bottom (triad only) 
     662\end{labeling} 
     663 
     664%% ================================================================================================= 
     665\section[Tracer vertical diffusion (\textit{trazdf.F90})]{Tracer vertical diffusion (\protect\mdl{trazdf})} 
    635666\label{sec:TRA_zdf} 
    636 %--------------------------------------------namzdf--------------------------------------------------------- 
    637  
    638 \nlst{namzdf} 
    639 %-------------------------------------------------------------------------------------------------------------- 
    640  
    641 Options are defined through the \ngn{namzdf} namelist variables. 
    642 The formulation of the vertical subgrid scale tracer physics is the same for all the vertical coordinates, 
    643 and is based on a laplacian operator. 
    644 The vertical diffusion operator given by (\autoref{eq:PE_zdf}) takes the following semi -discrete space form: 
    645 \begin{gather*} 
    646   % \label{eq:tra_zdf} 
    647     D^{vT}_T = \frac{1}{e_{3t}} \, \delta_k \lt[ \, \frac{A^{vT}_w}{e_{3w}} \delta_{k + 1/2}[T] \, \rt] \\ 
    648     D^{vS}_T = \frac{1}{e_{3t}} \; \delta_k \lt[ \, \frac{A^{vS}_w}{e_{3w}} \delta_{k + 1/2}[S] \, \rt] 
    649 \end{gather*} 
    650 where $A_w^{vT}$ and $A_w^{vS}$ are the vertical eddy diffusivity coefficients on temperature and salinity, 
    651 respectively. 
     667 
     668Options are defined through the \nam{zdf}{zdf} namelist variables. 
     669The formulation of the vertical subgrid scale tracer physics is the same for 
     670all the vertical coordinates, and is based on a laplacian operator. 
     671The vertical diffusion operator given by (\autoref{eq:MB_zdf}) takes 
     672the following semi-discrete space form: 
     673\[ 
     674  % \label{eq:TRA_zdf} 
     675  D^{vT}_T = \frac{1}{e_{3t}} \, \delta_k \lt[ \, \frac{A^{vT}_w}{e_{3w}} \delta_{k + 1/2}[T] \, \rt] \quad 
     676  D^{vS}_T = \frac{1}{e_{3t}} \; \delta_k \lt[ \, \frac{A^{vS}_w}{e_{3w}} \delta_{k + 1/2}[S] \, \rt] 
     677\] 
     678where $A_w^{vT}$ and $A_w^{vS}$ are the vertical eddy diffusivity coefficients on 
     679temperature and salinity, respectively. 
    652680Generally, $A_w^{vT} = A_w^{vS}$ except when double diffusive mixing is parameterised 
    653 (\ie \key{zdfddm} is defined). 
     681(\ie\ \np[=.true.]{ln_zdfddm}{ln\_zdfddm},). 
    654682The way these coefficients are evaluated is given in \autoref{chap:ZDF} (ZDF). 
    655 Furthermore, when iso-neutral mixing is used, both mixing coefficients are increased by 
    656 $\frac{e_{1w} e_{2w}}{e_{3w} }({r_{1w}^2 + r_{2w}^2})$ to account for the vertical second derivative of 
    657 \autoref{eq:tra_ldf_iso}. 
     683Furthermore, when iso-neutral mixing is used, 
     684both mixing coefficients are increased by $\frac{e_{1w} e_{2w}}{e_{3w} }({r_{1w}^2 + r_{2w}^2})$ to 
     685account for the vertical second derivative of \autoref{eq:TRA_ldf_iso}. 
    658686 
    659687At the surface and bottom boundaries, the turbulent fluxes of heat and salt must be specified. 
     
    662690a geothermal flux forcing is prescribed as a bottom boundary condition (see \autoref{subsec:TRA_bbc}). 
    663691 
    664 The large eddy coefficient found in the mixed layer together with high vertical resolution implies that 
    665 in the case of explicit time stepping (\np{ln\_zdfexp}~\forcode{= .true.}) 
    666 there would be too restrictive a constraint on the time step. 
    667 Therefore, the default implicit time stepping is preferred for the vertical diffusion since 
     692The large eddy coefficient found in the mixed layer together with high vertical resolution implies 
     693that there would be too restrictive constraint on the time step if we use explicit time stepping. 
     694Therefore an implicit time stepping is preferred for the vertical diffusion since 
    668695it overcomes the stability constraint. 
    669 A forward time differencing scheme (\np{ln\_zdfexp}~\forcode{= .true.}) using 
    670 a time splitting technique (\np{nn\_zdfexp} $> 1$) is provided as an alternative. 
    671 Namelist variables \np{ln\_zdfexp} and \np{nn\_zdfexp} apply to both tracers and dynamics. 
    672  
    673 % ================================================================ 
    674 % External Forcing 
    675 % ================================================================ 
     696 
     697%% ================================================================================================= 
    676698\section{External forcing} 
    677699\label{sec:TRA_sbc_qsr_bbc} 
    678700 
    679 % ------------------------------------------------------------------------------------------------------------- 
    680 %        surface boundary condition 
    681 % ------------------------------------------------------------------------------------------------------------- 
    682 \subsection{Surface boundary condition (\protect\mdl{trasbc})} 
     701%% ================================================================================================= 
     702\subsection[Surface boundary condition (\textit{trasbc.F90})]{Surface boundary condition (\protect\mdl{trasbc})} 
    683703\label{subsec:TRA_sbc} 
    684704 
     
    690710 
    691711Due to interactions and mass exchange of water ($F_{mass}$) with other Earth system components 
    692 (\ie atmosphere, sea-ice, land), the change in the heat and salt content of the surface layer of the ocean is due 
    693 both to the heat and salt fluxes crossing the sea surface (not linked with $F_{mass}$) and 
     712(\ie\ atmosphere, sea-ice, land), 
     713the change in the heat and salt content of the surface layer of the ocean is due both to 
     714the heat and salt fluxes crossing the sea surface (not linked with $F_{mass}$) and 
    694715to the heat and salt content of the mass exchange. 
    695716They are both included directly in $Q_{ns}$, the surface heat flux, 
    696717and $F_{salt}$, the surface salt flux (see \autoref{chap:SBC} for further details). 
    697 By doing this, the forcing formulation is the same for any tracer (including temperature and salinity). 
    698  
    699 The surface module (\mdl{sbcmod}, see \autoref{chap:SBC}) provides the following forcing fields (used on tracers): 
    700  
    701 \begin{itemize} 
    702 \item 
    703   $Q_{ns}$, the non-solar part of the net surface heat flux that crosses the sea surface 
    704   (\ie the difference between the total surface heat flux and the fraction of the short wave flux that 
    705   penetrates into the water column, see \autoref{subsec:TRA_qsr}) 
     718By doing this, the forcing formulation is the same for any tracer 
     719(including temperature and salinity). 
     720 
     721The surface module (\mdl{sbcmod}, see \autoref{chap:SBC}) provides the following forcing fields 
     722(used on tracers): 
     723 
     724\begin{labeling}{\textit{fwfisf}} 
     725\item [$Q_{ns}$] The non-solar part of the net surface heat flux that crosses the sea surface 
     726  (\ie\ the difference between the total surface heat flux and 
     727  the fraction of the short wave flux that penetrates into the water column, 
     728  see \autoref{subsec:TRA_qsr}) 
    706729  plus the heat content associated with of the mass exchange with the atmosphere and lands. 
    707 \item 
    708   $\textit{sfx}$, the salt flux resulting from ice-ocean mass exchange (freezing, melting, ridging...) 
    709 \item 
    710   \textit{emp}, the mass flux exchanged with the atmosphere (evaporation minus precipitation) and 
     730\item [\textit{sfx}] The salt flux resulting from ice-ocean mass exchange 
     731  (freezing, melting, ridging...) 
     732\item [\textit{emp}] The mass flux exchanged with the atmosphere (evaporation minus precipitation) and 
    711733  possibly with the sea-ice and ice-shelves. 
    712 \item 
    713   \textit{rnf}, the mass flux associated with runoff 
     734\item [\textit{rnf}] The mass flux associated with runoff 
    714735  (see \autoref{sec:SBC_rnf} for further detail of how it acts on temperature and salinity tendencies) 
    715 \item 
    716   \textit{fwfisf}, the mass flux associated with ice shelf melt, 
     736\item [\textit{fwfisf}] The mass flux associated with ice shelf melt, 
    717737  (see \autoref{sec:SBC_isf} for further details on how the ice shelf melt is computed and applied). 
    718 \end{itemize} 
     738\end{labeling} 
    719739 
    720740The surface boundary condition on temperature and salinity is applied as follows: 
    721741\begin{equation} 
    722   \label{eq:tra_sbc} 
    723   \begin{alignedat}{2} 
    724     F^T &= \frac{1}{C_p} &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} &\overline{Q_{ns}      }^t \\ 
    725     F^S &=               &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} &\overline{\textit{sfx}}^t 
    726   \end{alignedat} 
     742  \label{eq:TRA_sbc} 
     743    F^T = \frac{1}{C_p} \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} \overline{Q_{ns}      }^t \qquad 
     744    F^S =               \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} \overline{\textit{sfx}}^t 
    727745\end{equation} 
    728746where $\overline x^t$ means that $x$ is averaged over two consecutive time steps 
    729747($t - \rdt / 2$ and $t + \rdt / 2$). 
    730 Such time averaging prevents the divergence of odd and even time step (see \autoref{chap:STP}). 
    731  
    732 In the linear free surface case (\np{ln\_linssh}~\forcode{= .true.}), an additional term has to be added on 
    733 both temperature and salinity. 
    734 On temperature, this term remove the heat content associated with mass exchange that has been added to $Q_{ns}$. 
    735 On salinity, this term mimics the concentration/dilution effect that would have resulted from a change in 
    736 the volume of the first level. 
     748Such time averaging prevents the divergence of odd and even time step (see \autoref{chap:TD}). 
     749 
     750In the linear free surface case (\np[=.true.]{ln_linssh}{ln\_linssh}), 
     751an additional term has to be added on both temperature and salinity. 
     752On temperature, this term remove the heat content associated with 
     753mass exchange that has been added to $Q_{ns}$. 
     754On salinity, this term mimics the concentration/dilution effect that would have resulted from 
     755a change in the volume of the first level. 
    737756The resulting surface boundary condition is applied as follows: 
    738757\begin{equation} 
    739   \label{eq:tra_sbc_lin} 
    740   \begin{alignedat}{2} 
    741     F^T &= \frac{1}{C_p} &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} 
    742           &\overline{(Q_{ns}       - C_p \, \textit{emp} \lt. T \rt|_{k = 1})}^t \\ 
    743     F^S &=               &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} 
    744           &\overline{(\textit{sfx} -        \textit{emp} \lt. S \rt|_{k = 1})}^t 
    745   \end{alignedat} 
    746 \end{equation}  
    747 Note that an exact conservation of heat and salt content is only achieved with non-linear free surface. 
     758  \label{eq:TRA_sbc_lin} 
     759    F^T = \frac{1}{C_p} \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} 
     760          \overline{(Q_{ns}       - C_p \, \textit{emp} \lt. T \rt|_{k = 1})}^t \qquad 
     761    F^S =               \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} 
     762          \overline{(\textit{sfx} -        \textit{emp} \lt. S \rt|_{k = 1})}^t 
     763\end{equation} 
     764Note that an exact conservation of heat and salt content is only achieved with 
     765non-linear free surface. 
    748766In the linear free surface case, there is a small imbalance. 
    749 The imbalance is larger than the imbalance associated with the Asselin time filter \citep{Leclair_Madec_OM09}. 
    750 This is the reason why the modified filter is not applied in the linear free surface case (see \autoref{chap:STP}). 
    751  
    752 % ------------------------------------------------------------------------------------------------------------- 
    753 %        Solar Radiation Penetration  
    754 % ------------------------------------------------------------------------------------------------------------- 
    755 \subsection{Solar radiation penetration (\protect\mdl{traqsr})} 
     767The imbalance is larger than the imbalance associated with the Asselin time filter 
     768\citep{leclair.madec_OM09}. 
     769This is the reason why the modified filter is not applied in the linear free surface case 
     770(see \autoref{chap:TD}). 
     771 
     772%% ================================================================================================= 
     773\subsection[Solar radiation penetration (\textit{traqsr.F90})]{Solar radiation penetration (\protect\mdl{traqsr})} 
    756774\label{subsec:TRA_qsr} 
    757 %--------------------------------------------namqsr-------------------------------------------------------- 
    758  
    759 \nlst{namtra_qsr} 
    760 %-------------------------------------------------------------------------------------------------------------- 
    761  
    762 Options are defined through the \ngn{namtra\_qsr} namelist variables. 
    763 When the penetrative solar radiation option is used (\np{ln\_flxqsr}~\forcode{= .true.}), 
     775 
     776\begin{listing} 
     777  \nlst{namtra_qsr} 
     778  \caption{\forcode{&namtra_qsr}} 
     779  \label{lst:namtra_qsr} 
     780\end{listing} 
     781 
     782Options are defined through the \nam{tra_qsr}{tra\_qsr} namelist variables. 
     783When the penetrative solar radiation option is used (\np[=.true.]{ln_traqsr}{ln\_traqsr}), 
    764784the solar radiation penetrates the top few tens of meters of the ocean. 
    765 If it is not used (\np{ln\_flxqsr}~\forcode{= .false.}) all the heat flux is absorbed in the first ocean level. 
    766 Thus, in the former case a term is added to the time evolution equation of temperature \autoref{eq:PE_tra_T} and 
    767 the surface boundary condition is modified to take into account only the non-penetrative part of the surface  
    768 heat flux: 
    769 \begin{equation} 
    770   \label{eq:PE_qsr} 
     785If it is not used (\np[=.false.]{ln_traqsr}{ln\_traqsr}) all the heat flux is absorbed in 
     786the first ocean level. 
     787Thus, in the former case a term is added to the time evolution equation of temperature 
     788\autoref{eq:MB_PE_tra_T} and the surface boundary condition is modified to 
     789take into account only the non-penetrative part of the surface heat flux: 
     790\begin{equation} 
     791  \label{eq:TRA_PE_qsr} 
    771792  \begin{gathered} 
    772793    \pd[T]{t} = \ldots + \frac{1}{\rho_o \, C_p \, e_3} \; \pd[I]{k} \\ 
     
    774795  \end{gathered} 
    775796\end{equation} 
    776 where $Q_{sr}$ is the penetrative part of the surface heat flux (\ie the shortwave radiation) and 
     797where $Q_{sr}$ is the penetrative part of the surface heat flux (\ie\ the shortwave radiation) and 
    777798$I$ is the downward irradiance ($\lt. I \rt|_{z = \eta} = Q_{sr}$). 
    778 The additional term in \autoref{eq:PE_qsr} is discretized as follows: 
    779 \begin{equation} 
    780   \label{eq:tra_qsr} 
     799The additional term in \autoref{eq:TRA_PE_qsr} is discretized as follows: 
     800\begin{equation} 
     801  \label{eq:TRA_qsr} 
    781802  \frac{1}{\rho_o \, C_p \, e_3} \, \pd[I]{k} \equiv \frac{1}{\rho_o \, C_p \, e_{3t}} \delta_k [I_w] 
    782803\end{equation} 
    783804 
    784805The shortwave radiation, $Q_{sr}$, consists of energy distributed across a wide spectral range. 
    785 The ocean is strongly absorbing for wavelengths longer than 700~nm and these wavelengths contribute to 
    786 heating the upper few tens of centimetres. 
    787 The fraction of $Q_{sr}$ that resides in these almost non-penetrative wavebands, $R$, is $\sim 58\%$ 
    788 (specified through namelist parameter \np{rn\_abs}). 
    789 It is assumed to penetrate the ocean with a decreasing exponential profile, with an e-folding depth scale, $\xi_0$, 
    790 of a few tens of centimetres (typically $\xi_0 = 0.35~m$ set as \np{rn\_si0} in the \ngn{namtra\_qsr} namelist). 
    791 For shorter wavelengths (400-700~nm), the ocean is more transparent, and solar energy propagates to 
    792 larger depths where it contributes to local heating. 
    793 The way this second part of the solar energy penetrates into the ocean depends on which formulation is chosen. 
    794 In the simple 2-waveband light penetration scheme (\np{ln\_qsr\_2bd}~\forcode{= .true.}) 
     806The ocean is strongly absorbing for wavelengths longer than 700 $nm$ and 
     807these wavelengths contribute to heat the upper few tens of centimetres. 
     808The fraction of $Q_{sr}$ that resides in these almost non-penetrative wavebands, $R$, is $\sim$ 58\% 
     809(specified through namelist parameter \np{rn_abs}{rn\_abs}). 
     810It is assumed to penetrate the ocean with a decreasing exponential profile, 
     811with an e-folding depth scale, $\xi_0$, of a few tens of centimetres 
     812(typically $\xi_0 = 0.35~m$ set as \np{rn_si0}{rn\_si0} in the \nam{tra_qsr}{tra\_qsr} namelist). 
     813For shorter wavelengths (400-700 $nm$), the ocean is more transparent, 
     814and solar energy propagates to larger depths where it contributes to local heating. 
     815The way this second part of the solar energy penetrates into 
     816the ocean depends on which formulation is chosen. 
     817In the simple 2-waveband light penetration scheme (\np[=.true.]{ln_qsr_2bd}{ln\_qsr\_2bd}) 
    795818a chlorophyll-independent monochromatic formulation is chosen for the shorter wavelengths, 
    796 leading to the following expression \citep{Paulson1977}: 
     819leading to the following expression \citep{paulson.simpson_JPO77}: 
    797820\[ 
    798   % \label{eq:traqsr_iradiance} 
     821  % \label{eq:TRA_qsr_iradiance} 
    799822  I(z) = Q_{sr} \lt[ Re^{- z / \xi_0} + (1 - R) e^{- z / \xi_1} \rt] 
    800823\] 
    801824where $\xi_1$ is the second extinction length scale associated with the shorter wavelengths. 
    802 It is usually chosen to be 23~m by setting the \np{rn\_si0} namelist parameter. 
    803 The set of default values ($\xi_0, \xi_1, R$) corresponds to a Type I water in Jerlov's (1968) classification 
    804 (oligotrophic waters). 
     825It is usually chosen to be 23~m by setting the \np{rn_si0}{rn\_si0} namelist parameter. 
     826The set of default values ($\xi_0, \xi_1, R$) corresponds to 
     827a Type I water in Jerlov's (1968) classification (oligotrophic waters). 
    805828 
    806829Such assumptions have been shown to provide a very crude and simplistic representation of 
    807 observed light penetration profiles (\cite{Morel_JGR88}, see also \autoref{fig:traqsr_irradiance}). 
     830observed light penetration profiles (\cite{morel_JGR88}, see also \autoref{fig:TRA_qsr_irradiance}). 
    808831Light absorption in the ocean depends on particle concentration and is spectrally selective. 
    809 \cite{Morel_JGR88} has shown that an accurate representation of light penetration can be provided by 
     832\cite{morel_JGR88} has shown that an accurate representation of light penetration can be provided by 
    810833a 61 waveband formulation. 
    811834Unfortunately, such a model is very computationally expensive. 
    812 Thus, \cite{Lengaigne_al_CD07} have constructed a simplified version of this formulation in which 
    813 visible light is split into three wavebands: blue (400-500 nm), green (500-600 nm) and red (600-700nm). 
    814 For each wave-band, the chlorophyll-dependent attenuation coefficient is fitted to the coefficients computed from 
    815 the full spectral model of \cite{Morel_JGR88} (as modified by \cite{Morel_Maritorena_JGR01}), 
    816 assuming the same power-law relationship. 
    817 As shown in \autoref{fig:traqsr_irradiance}, this formulation, called RGB (Red-Green-Blue), 
     835Thus, \cite{lengaigne.menkes.ea_CD07} have constructed a simplified version of 
     836this formulation in which visible light is split into three wavebands: 
     837blue (400-500 $nm$), green (500-600 $nm$) and red (600-700 $nm$). 
     838For each wave-band, the chlorophyll-dependent attenuation coefficient is fitted to 
     839the coefficients computed from the full spectral model of \cite{morel_JGR88} 
     840(as modified by \cite{morel.maritorena_JGR01}), assuming the same power-law relationship. 
     841As shown in \autoref{fig:TRA_qsr_irradiance}, this formulation, 
     842called RGB (\textbf{R}ed-\textbf{G}reen-\textbf{B}lue), 
    818843reproduces quite closely the light penetration profiles predicted by the full spectal model, 
    819844but with much greater computational efficiency. 
    820845The 2-bands formulation does not reproduce the full model very well. 
    821846 
    822 The RGB formulation is used when \np{ln\_qsr\_rgb}~\forcode{= .true.}. 
    823 The RGB attenuation coefficients (\ie the inverses of the extinction length scales) are tabulated over 
    824 61 nonuniform chlorophyll classes ranging from 0.01 to 10 g.Chl/L 
     847The RGB formulation is used when \np[=.true.]{ln_qsr_rgb}{ln\_qsr\_rgb}. 
     848The RGB attenuation coefficients (\ie\ the inverses of the extinction length scales) are 
     849tabulated over 61 nonuniform chlorophyll classes ranging from 0.01 to 10 $g.Chl/L$ 
    825850(see the routine \rou{trc\_oce\_rgb} in \mdl{trc\_oce} module). 
    826851Four types of chlorophyll can be chosen in the RGB formulation: 
    827852 
    828853\begin{description} 
    829 \item[\np{nn\_chdta}~\forcode{= 0}] 
    830   a constant 0.05 g.Chl/L value everywhere ;  
    831 \item[\np{nn\_chdta}~\forcode{= 1}] 
    832   an observed time varying chlorophyll deduced from satellite surface ocean color measurement spread uniformly in 
    833   the vertical direction; 
    834 \item[\np{nn\_chdta}~\forcode{= 2}] 
    835   same as previous case except that a vertical profile of chlorophyl is used. 
    836   Following \cite{Morel_Berthon_LO89}, the profile is computed from the local surface chlorophyll value; 
    837 \item[\np{ln\_qsr\_bio}~\forcode{= .true.}] 
    838   simulated time varying chlorophyll by TOP biogeochemical model. 
    839   In this case, the RGB formulation is used to calculate both the phytoplankton light limitation in 
    840   PISCES or LOBSTER and the oceanic heating rate. 
    841 \end{description}  
    842  
    843 The trend in \autoref{eq:tra_qsr} associated with the penetration of the solar radiation is added to 
     854\item [{\np[=0]{nn_chldta}{nn\_chldta}}] a constant 0.05 $g.Chl/L$ value everywhere; 
     855\item [{\np[=1]{nn_chldta}{nn\_chldta}}] an observed time varying chlorophyll deduced from 
     856  satellite surface ocean color measurement spread uniformly in the vertical direction; 
     857\item [{\np[=2]{nn_chldta}{nn\_chldta}}] same as previous case except that 
     858  a vertical profile of chlorophyl is used. 
     859  Following \cite{morel.berthon_LO89}, 
     860  the profile is computed from the local surface chlorophyll value; 
     861\item [{\np[=.true.]{ln_qsr_bio}{ln\_qsr\_bio}}] simulated time varying chlorophyll by 
     862  \TOP\ biogeochemical model. 
     863  In this case, the RGB formulation is used to calculate both 
     864  the phytoplankton light limitation in \PISCES\ and the oceanic heating rate. 
     865\end{description} 
     866 
     867The trend in \autoref{eq:TRA_qsr} associated with the penetration of the solar radiation is added to 
    844868the temperature trend, and the surface heat flux is modified in routine \mdl{traqsr}. 
    845869 
     
    847871the depth of $w-$levels does not significantly vary with location. 
    848872The level at which the light has been totally absorbed 
    849 (\ie it is less than the computer precision) is computed once, 
     873(\ie\ it is less than the computer precision) is computed once, 
    850874and the trend associated with the penetration of the solar radiation is only added down to that level. 
    851 Finally, note that when the ocean is shallow ($<$ 200~m), part of the solar radiation can reach the ocean floor. 
     875Finally, note that when the ocean is shallow ($<$ 200~m), 
     876part of the solar radiation can reach the ocean floor. 
    852877In this case, we have chosen that all remaining radiation is absorbed in the last ocean level 
    853 (\ie $I$ is masked). 
    854  
    855 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    856 \begin{figure}[!t] 
    857   \begin{center} 
    858     \includegraphics[]{Fig_TRA_Irradiance} 
    859     \caption{ 
    860       \protect\label{fig:traqsr_irradiance} 
    861       Penetration profile of the downward solar irradiance calculated by four models. 
    862       Two waveband chlorophyll-independent formulation (blue), 
    863       a chlorophyll-dependent monochromatic formulation (green), 
    864       4 waveband RGB formulation (red), 
    865       61 waveband Morel (1988) formulation (black) for a chlorophyll concentration of 
    866       (a) Chl=0.05 mg/m$^3$ and (b) Chl=0.5 mg/m$^3$. 
    867       From \citet{Lengaigne_al_CD07}. 
    868     } 
    869   \end{center} 
     878(\ie\ $I$ is masked). 
     879 
     880\begin{figure} 
     881  \centering 
     882  \includegraphics[width=0.66\textwidth]{TRA_Irradiance} 
     883  \caption[Penetration profile of the downward solar irradiance calculated by four models]{ 
     884    Penetration profile of the downward solar irradiance calculated by four models. 
     885    Two waveband chlorophyll-independent formulation (blue), 
     886    a chlorophyll-dependent monochromatic formulation (green), 
     887    4 waveband RGB formulation (red), 
     888    61 waveband Morel (1988) formulation (black) for a chlorophyll concentration of 
     889    (a) Chl=0.05 $mg/m^3$ and (b) Chl=0.5 $mg/m^3$. 
     890    From \citet{lengaigne.menkes.ea_CD07}.} 
     891  \label{fig:TRA_qsr_irradiance} 
    870892\end{figure} 
    871 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    872  
    873 % ------------------------------------------------------------------------------------------------------------- 
    874 %        Bottom Boundary Condition 
    875 % ------------------------------------------------------------------------------------------------------------- 
    876 \subsection{Bottom boundary condition (\protect\mdl{trabbc})} 
     893 
     894%% ================================================================================================= 
     895\subsection[Bottom boundary condition (\textit{trabbc.F90}) - \forcode{ln_trabbc})]{Bottom boundary condition (\protect\mdl{trabbc} - \protect\np{ln_trabbc}{ln\_trabbc})} 
    877896\label{subsec:TRA_bbc} 
    878 %--------------------------------------------nambbc-------------------------------------------------------- 
    879  
    880 \nlst{nambbc} 
    881 %-------------------------------------------------------------------------------------------------------------- 
    882 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    883 \begin{figure}[!t] 
    884   \begin{center} 
    885     \includegraphics[]{Fig_TRA_geoth} 
    886     \caption{ 
    887       \protect\label{fig:geothermal} 
    888       Geothermal Heat flux (in $mW.m^{-2}$) used by \cite{Emile-Geay_Madec_OS09}. 
    889       It is inferred from the age of the sea floor and the formulae of \citet{Stein_Stein_Nat92}. 
    890     } 
    891   \end{center} 
     897 
     898\begin{listing} 
     899  \nlst{nambbc} 
     900  \caption{\forcode{&nambbc}} 
     901  \label{lst:nambbc} 
     902\end{listing} 
     903 
     904\begin{figure} 
     905  \centering 
     906  \includegraphics[width=0.66\textwidth]{TRA_geoth} 
     907  \caption[Geothermal heat flux]{ 
     908    Geothermal Heat flux (in $mW.m^{-2}$) used by \cite{emile-geay.madec_OS09}. 
     909    It is inferred from the age of the sea floor and the formulae of \citet{stein.stein_N92}.} 
     910  \label{fig:TRA_geothermal} 
    892911\end{figure} 
    893 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    894912 
    895913Usually it is assumed that there is no exchange of heat or salt through the ocean bottom, 
    896 \ie a no flux boundary condition is applied on active tracers at the bottom. 
     914\ie\ a no flux boundary condition is applied on active tracers at the bottom. 
    897915This is the default option in \NEMO, and it is implemented using the masking technique. 
    898 However, there is a non-zero heat flux across the seafloor that is associated with solid earth cooling. 
    899 This flux is weak compared to surface fluxes (a mean global value of $\sim 0.1 \, W/m^2$ \citep{Stein_Stein_Nat92}), 
     916However, there is a non-zero heat flux across the seafloor that 
     917is associated with solid earth cooling. 
     918This flux is weak compared to surface fluxes 
     919(a mean global value of $\sim 0.1 \, W/m^2$ \citep{stein.stein_N92}), 
    900920but it warms systematically the ocean and acts on the densest water masses. 
    901921Taking this flux into account in a global ocean model increases the deepest overturning cell 
    902 (\ie the one associated with the Antarctic Bottom Water) by a few Sverdrups \citep{Emile-Geay_Madec_OS09}. 
    903  
    904 Options are defined through the  \ngn{namtra\_bbc} namelist variables. 
    905 The presence of geothermal heating is controlled by setting the namelist parameter \np{ln\_trabbc} to true. 
    906 Then, when \np{nn\_geoflx} is set to 1, a constant geothermal heating is introduced whose value is given by 
    907 the \np{nn\_geoflx\_cst}, which is also a namelist parameter. 
    908 When \np{nn\_geoflx} is set to 2, a spatially varying geothermal heat flux is introduced which is provided in 
    909 the \ifile{geothermal\_heating} NetCDF file (\autoref{fig:geothermal}) \citep{Emile-Geay_Madec_OS09}. 
    910  
    911 % ================================================================ 
    912 % Bottom Boundary Layer 
    913 % ================================================================ 
    914 \section{Bottom boundary layer (\protect\mdl{trabbl} - \protect\key{trabbl})} 
     922(\ie\ the one associated with the Antarctic Bottom Water) by 
     923a few Sverdrups \citep{emile-geay.madec_OS09}. 
     924 
     925Options are defined through the \nam{bbc}{bbc} namelist variables. 
     926The presence of geothermal heating is controlled by 
     927setting the namelist parameter \np{ln_trabbc}{ln\_trabbc} to true. 
     928Then, when \np{nn_geoflx}{nn\_geoflx} is set to 1, a constant geothermal heating is introduced whose 
     929value is given by the \np{rn_geoflx_cst}{rn\_geoflx\_cst}, which is also a namelist parameter. 
     930When \np{nn_geoflx}{nn\_geoflx} is set to 2, 
     931a spatially varying geothermal heat flux is introduced which is provided in 
     932the \ifile{geothermal\_heating} NetCDF file 
     933(\autoref{fig:TRA_geothermal}) \citep{emile-geay.madec_OS09}. 
     934 
     935%% ================================================================================================= 
     936\section[Bottom boundary layer (\textit{trabbl.F90} - \forcode{ln_trabbl})]{Bottom boundary layer (\protect\mdl{trabbl} - \protect\np{ln_trabbl}{ln\_trabbl})} 
    915937\label{sec:TRA_bbl} 
    916 %--------------------------------------------nambbl--------------------------------------------------------- 
    917  
    918 \nlst{nambbl} 
    919 %-------------------------------------------------------------------------------------------------------------- 
    920  
    921 Options are defined through the \ngn{nambbl} namelist variables. 
     938 
     939\begin{listing} 
     940  \nlst{nambbl} 
     941  \caption{\forcode{&nambbl}} 
     942  \label{lst:nambbl} 
     943\end{listing} 
     944 
     945Options are defined through the \nam{bbl}{bbl} namelist variables. 
    922946In a $z$-coordinate configuration, the bottom topography is represented by a series of discrete steps. 
    923947This is not adequate to represent gravity driven downslope flows. 
     
    925949where dense water formed in marginal seas flows into a basin filled with less dense water, 
    926950or along the continental slope when dense water masses are formed on a continental shelf. 
    927 The amount of entrainment that occurs in these gravity plumes is critical in determining the density and 
    928 volume flux of the densest waters of the ocean, such as Antarctic Bottom Water, or North Atlantic Deep Water. 
     951The amount of entrainment that occurs in these gravity plumes is critical in 
     952determining the density and volume flux of the densest waters of the ocean, 
     953such as Antarctic Bottom Water, or North Atlantic Deep Water. 
    929954$z$-coordinate models tend to overestimate the entrainment, 
    930 because the gravity flow is mixed vertically by convection as it goes ''downstairs'' following the step topography, 
     955because the gravity flow is mixed vertically by convection as 
     956it goes ''downstairs'' following the step topography, 
    931957sometimes over a thickness much larger than the thickness of the observed gravity plume. 
    932 A similar problem occurs in the $s$-coordinate when the thickness of the bottom level varies rapidly downstream of 
    933 a sill \citep{Willebrand_al_PO01}, and the thickness of the plume is not resolved. 
    934  
    935 The idea of the bottom boundary layer (BBL) parameterisation, first introduced by \citet{Beckmann_Doscher1997}, 
     958A similar problem occurs in the $s$-coordinate when 
     959the thickness of the bottom level varies rapidly downstream of a sill 
     960\citep{willebrand.barnier.ea_PO01}, and the thickness of the plume is not resolved. 
     961 
     962The idea of the bottom boundary layer (BBL) parameterisation, first introduced by 
     963\citet{beckmann.doscher_JPO97}, 
    936964is to allow a direct communication between two adjacent bottom cells at different levels, 
    937965whenever the densest water is located above the less dense water. 
    938 The communication can be by a diffusive flux (diffusive BBL), an advective flux (advective BBL), or both. 
     966The communication can be by a diffusive flux (diffusive BBL), 
     967an advective flux (advective BBL), or both. 
    939968In the current implementation of the BBL, only the tracers are modified, not the velocities. 
    940 Furthermore, it only connects ocean bottom cells, and therefore does not include all the improvements introduced by 
    941 \citet{Campin_Goosse_Tel99}. 
    942  
    943 % ------------------------------------------------------------------------------------------------------------- 
    944 %        Diffusive BBL 
    945 % ------------------------------------------------------------------------------------------------------------- 
    946 \subsection{Diffusive bottom boundary layer (\protect\np{nn\_bbl\_ldf}~\forcode{= 1})} 
     969Furthermore, it only connects ocean bottom cells, 
     970and therefore does not include all the improvements introduced by \citet{campin.goosse_T99}. 
     971 
     972%% ================================================================================================= 
     973\subsection[Diffusive bottom boundary layer (\forcode{nn_bbl_ldf=1})]{Diffusive bottom boundary layer (\protect\np[=1]{nn_bbl_ldf}{nn\_bbl\_ldf})} 
    947974\label{subsec:TRA_bbl_diff} 
    948975 
    949 When applying sigma-diffusion (\key{trabbl} defined and \np{nn\_bbl\_ldf} set to 1), 
    950 the diffusive flux between two adjacent cells at the ocean floor is given by  
     976When applying sigma-diffusion 
     977(\np[=.true.]{ln_trabbl}{ln\_trabbl} and \np{nn_bbl_ldf}{nn\_bbl\_ldf} set to 1), 
     978the diffusive flux between two adjacent cells at the ocean floor is given by 
    951979\[ 
    952   % \label{eq:tra_bbl_diff} 
     980  % \label{eq:TRA_bbl_diff} 
    953981  \vect F_\sigma = A_l^\sigma \, \nabla_\sigma T 
    954982\] 
    955 with $\nabla_\sigma$ the lateral gradient operator taken between bottom cells, and 
    956 $A_l^\sigma$ the lateral diffusivity in the BBL. 
    957 Following \citet{Beckmann_Doscher1997}, the latter is prescribed with a spatial dependence, 
    958 \ie in the conditional form 
    959 \begin{equation} 
    960   \label{eq:tra_bbl_coef} 
     983with $\nabla_\sigma$ the lateral gradient operator taken between bottom cells, 
     984and $A_l^\sigma$ the lateral diffusivity in the BBL. 
     985Following \citet{beckmann.doscher_JPO97}, the latter is prescribed with a spatial dependence, 
     986\ie\ in the conditional form 
     987\begin{equation} 
     988  \label{eq:TRA_bbl_coef} 
    961989  A_l^\sigma (i,j,t) = 
    962990      \begin{cases} 
    963991        A_{bbl} & \text{if~} \nabla_\sigma \rho \cdot \nabla H < 0 \\ 
    964         \\ 
    965         0      & \text{otherwise} \\ 
     992        0      & \text{otherwise} 
    966993      \end{cases} 
    967994\end{equation} 
    968 where $A_{bbl}$ is the BBL diffusivity coefficient, given by the namelist parameter \np{rn\_ahtbbl} and 
     995where $A_{bbl}$ is the BBL diffusivity coefficient, 
     996given by the namelist parameter \np{rn_ahtbbl}{rn\_ahtbbl} and 
    969997usually set to a value much larger than the one used for lateral mixing in the open ocean. 
    970 The constraint in \autoref{eq:tra_bbl_coef} implies that sigma-like diffusion only occurs when 
     998The constraint in \autoref{eq:TRA_bbl_coef} implies that sigma-like diffusion only occurs when 
    971999the density above the sea floor, at the top of the slope, is larger than in the deeper ocean 
    972 (see green arrow in \autoref{fig:bbl}). 
     1000(see green arrow in \autoref{fig:TRA_bbl}). 
    9731001In practice, this constraint is applied separately in the two horizontal directions, 
    974 and the density gradient in \autoref{eq:tra_bbl_coef} is evaluated with the log gradient formulation:  
     1002and the density gradient in \autoref{eq:TRA_bbl_coef} is evaluated with the log gradient formulation: 
    9751003\[ 
    976   % \label{eq:tra_bbl_Drho} 
     1004  % \label{eq:TRA_bbl_Drho} 
    9771005  \nabla_\sigma \rho / \rho = \alpha \, \nabla_\sigma T + \beta \, \nabla_\sigma S 
    9781006\] 
    979 where $\rho$, $\alpha$ and $\beta$ are functions of $\overline T^\sigma$, $\overline S^\sigma$ and 
    980 $\overline H^\sigma$, the along bottom mean temperature, salinity and depth, respectively. 
    981  
    982 % ------------------------------------------------------------------------------------------------------------- 
    983 %        Advective BBL 
    984 % ------------------------------------------------------------------------------------------------------------- 
    985 \subsection{Advective bottom boundary layer  (\protect\np{nn\_bbl\_adv}~\forcode{= 1..2})} 
     1007where $\rho$, $\alpha$ and $\beta$ are functions of 
     1008$\overline T^\sigma$, $\overline S^\sigma$ and $\overline H^\sigma$, 
     1009the along bottom mean temperature, salinity and depth, respectively. 
     1010 
     1011%% ================================================================================================= 
     1012\subsection[Advective bottom boundary layer (\forcode{nn_bbl_adv=1,2})]{Advective bottom boundary layer (\protect\np[=1,2]{nn_bbl_adv}{nn\_bbl\_adv})} 
    9861013\label{subsec:TRA_bbl_adv} 
    9871014 
     
    9911018%} 
    9921019 
    993 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    994 \begin{figure}[!t] 
    995   \begin{center} 
    996     \includegraphics[]{Fig_BBL_adv} 
    997     \caption{ 
    998       \protect\label{fig:bbl} 
    999       Advective/diffusive Bottom Boundary Layer. 
    1000       The BBL parameterisation is activated when $\rho^i_{kup}$ is larger than $\rho^{i + 1}_{kdnw}$. 
    1001       Red arrows indicate the additional overturning circulation due to the advective BBL. 
    1002       The transport of the downslope flow is defined either as the transport of the bottom ocean cell (black arrow), 
    1003       or as a function of the along slope density gradient. 
    1004       The green arrow indicates the diffusive BBL flux directly connecting $kup$ and $kdwn$ ocean bottom cells. 
    1005     } 
    1006   \end{center} 
     1020\begin{figure} 
     1021  \centering 
     1022  \includegraphics[width=0.33\textwidth]{TRA_BBL_adv} 
     1023  \caption[Advective/diffusive bottom boundary layer]{ 
     1024    Advective/diffusive Bottom Boundary Layer. 
     1025    The BBL parameterisation is activated when $\rho^i_{kup}$ is larger than $\rho^{i + 1}_{kdnw}$. 
     1026    Red arrows indicate the additional overturning circulation due to the advective BBL. 
     1027    The transport of the downslope flow is defined either 
     1028    as the transport of the bottom ocean cell (black arrow), 
     1029    or as a function of the along slope density gradient. 
     1030    The green arrow indicates the diffusive BBL flux directly connecting 
     1031    $kup$ and $kdwn$ ocean bottom cells.} 
     1032  \label{fig:TRA_bbl} 
    10071033\end{figure} 
    1008 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    10091034 
    10101035%!!      nn_bbl_adv = 1   use of the ocean velocity as bbl velocity 
     
    10121037%!!        i.e. transport proportional to the along-slope density gradient 
    10131038 
    1014 %%%gmcomment   :  this section has to be really written 
    1015  
    1016 When applying an advective BBL (\np{nn\_bbl\_adv}~\forcode{= 1..2}), an overturning circulation is added which 
    1017 connects two adjacent bottom grid-points only if dense water overlies less dense water on the slope. 
     1039\cmtgm{This section has to be really written} 
     1040 
     1041When applying an advective BBL (\np[=1..2]{nn_bbl_adv}{nn\_bbl\_adv}), 
     1042an overturning circulation is added which connects two adjacent bottom grid-points only if 
     1043dense water overlies less dense water on the slope. 
    10181044The density difference causes dense water to move down the slope. 
    10191045 
    1020 \np{nn\_bbl\_adv}~\forcode{= 1}: 
    1021 the downslope velocity is chosen to be the Eulerian ocean velocity just above the topographic step 
    1022 (see black arrow in \autoref{fig:bbl}) \citep{Beckmann_Doscher1997}. 
    1023 It is a \textit{conditional advection}, that is, advection is allowed only 
    1024 if dense water overlies less dense water on the slope (\ie $\nabla_\sigma \rho \cdot \nabla H < 0$) and 
    1025 if the velocity is directed towards greater depth (\ie $\vect U \cdot \nabla H > 0$). 
    1026  
    1027 \np{nn\_bbl\_adv}~\forcode{= 2}: 
    1028 the downslope velocity is chosen to be proportional to $\Delta \rho$, 
    1029 the density difference between the higher cell and lower cell densities \citep{Campin_Goosse_Tel99}. 
    1030 The advection is allowed only  if dense water overlies less dense water on the slope 
    1031 (\ie $\nabla_\sigma \rho \cdot \nabla H < 0$). 
    1032 For example, the resulting transport of the downslope flow, here in the $i$-direction (\autoref{fig:bbl}), 
    1033 is simply given by the following expression: 
    1034 \[ 
    1035   % \label{eq:bbl_Utr} 
    1036   u^{tr}_{bbl} = \gamma g \frac{\Delta \rho}{\rho_o} e_{1u} \, min ({e_{3u}}_{kup},{e_{3u}}_{kdwn}) 
    1037 \] 
    1038 where $\gamma$, expressed in seconds, is the coefficient of proportionality provided as \np{rn\_gambbl}, 
    1039 a namelist parameter, and \textit{kup} and \textit{kdwn} are the vertical index of the higher and lower cells, 
    1040 respectively. 
    1041 The parameter $\gamma$ should take a different value for each bathymetric step, but for simplicity, 
    1042 and because no direct estimation of this parameter is available, a uniform value has been assumed. 
    1043 The possible values for $\gamma$ range between 1 and $10~s$ \citep{Campin_Goosse_Tel99}. 
    1044  
    1045 Scalar properties are advected by this additional transport $(u^{tr}_{bbl},v^{tr}_{bbl})$ using the upwind scheme. 
    1046 Such a diffusive advective scheme has been chosen to mimic the entrainment between the downslope plume and 
    1047 the surrounding water at intermediate depths. 
     1046\begin{description} 
     1047\item [{\np[=1]{nn_bbl_adv}{nn\_bbl\_adv}}] the downslope velocity is chosen to 
     1048  be the Eulerian ocean velocity just above the topographic step 
     1049  (see black arrow in \autoref{fig:TRA_bbl}) \citep{beckmann.doscher_JPO97}. 
     1050  It is a \textit{conditional advection}, that is, 
     1051  advection is allowed only if dense water overlies less dense water on the slope 
     1052  (\ie\ $\nabla_\sigma \rho \cdot \nabla H < 0$) and if the velocity is directed towards greater depth 
     1053  (\ie\ $\vect U \cdot \nabla H > 0$). 
     1054\item [{\np[=2]{nn_bbl_adv}{nn\_bbl\_adv}}] the downslope velocity is chosen to be proportional to 
     1055  $\Delta \rho$, the density difference between the higher cell and lower cell densities 
     1056  \citep{campin.goosse_T99}. 
     1057  The advection is allowed only  if dense water overlies less dense water on the slope 
     1058  (\ie\ $\nabla_\sigma \rho \cdot \nabla H < 0$). 
     1059  For example, the resulting transport of the downslope flow, here in the $i$-direction 
     1060  (\autoref{fig:TRA_bbl}), is simply given by the following expression: 
     1061  \[ 
     1062    % \label{eq:TRA_bbl_Utr} 
     1063    u^{tr}_{bbl} = \gamma g \frac{\Delta \rho}{\rho_o} e_{1u} \, min ({e_{3u}}_{kup},{e_{3u}}_{kdwn}) 
     1064  \] 
     1065  where $\gamma$, expressed in seconds, is the coefficient of proportionality provided as 
     1066  \np{rn_gambbl}{rn\_gambbl}, a namelist parameter, and 
     1067  \textit{kup} and \textit{kdwn} are the vertical index of the higher and lower cells, respectively. 
     1068  The parameter $\gamma$ should take a different value for each bathymetric step, but for simplicity, 
     1069  and because no direct estimation of this parameter is available, a uniform value has been assumed. 
     1070  The possible values for $\gamma$ range between 1 and $10~s$ \citep{campin.goosse_T99}. 
     1071\end{description} 
     1072 
     1073Scalar properties are advected by this additional transport $(u^{tr}_{bbl},v^{tr}_{bbl})$ using 
     1074the upwind scheme. 
     1075Such a diffusive advective scheme has been chosen to mimic the entrainment between 
     1076the downslope plume and the surrounding water at intermediate depths. 
    10481077The entrainment is replaced by the vertical mixing implicit in the advection scheme. 
    1049 Let us consider as an example the case displayed in \autoref{fig:bbl} where 
     1078Let us consider as an example the case displayed in \autoref{fig:TRA_bbl} where 
    10501079the density at level $(i,kup)$ is larger than the one at level $(i,kdwn)$. 
    1051 The advective BBL scheme modifies the tracer time tendency of the ocean cells near the topographic step by 
    1052 the downslope flow \autoref{eq:bbl_dw}, the horizontal \autoref{eq:bbl_hor} and 
    1053 the upward \autoref{eq:bbl_up} return flows as follows:  
    1054 \begin{alignat}{3} 
    1055   \label{eq:bbl_dw} 
    1056   \partial_t T^{do}_{kdw} &\equiv \partial_t T^{do}_{kdw} 
    1057                                 &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{kdw}} &&\lt( T^{sh}_{kup} - T^{do}_{kdw} \rt) \\ 
    1058   \label{eq:bbl_hor} 
    1059   \partial_t T^{sh}_{kup} &\equiv \partial_t T^{sh}_{kup} 
    1060                                 &&+ \frac{u^{tr}_{bbl}}{{b_t}^{sh}_{kup}} &&\lt( T^{do}_{kup} - T^{sh}_{kup} \rt) \\ 
    1061   % 
    1062   \intertext{and for $k =kdw-1,\;..., \; kup$ :} 
    1063   % 
    1064   \label{eq:bbl_up} 
    1065   \partial_t T^{do}_{k} &\equiv \partial_t S^{do}_{k} 
    1066                                 &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{k}}   &&\lt( T^{do}_{k +1} - T^{sh}_{k}   \rt) 
     1080The advective BBL scheme modifies the tracer time tendency of 
     1081the ocean cells near the topographic step by the downslope flow \autoref{eq:TRA_bbl_dw}, 
     1082the horizontal \autoref{eq:TRA_bbl_hor} and the upward \autoref{eq:TRA_bbl_up} return flows as follows: 
     1083\begin{alignat}{5} 
     1084  \label{eq:TRA_bbl_dw} 
     1085  \partial_t T^{do}_{kdw} &\equiv \partial_t T^{do}_{kdw} &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{kdw}} &&\lt( T^{sh}_{kup} - T^{do}_{kdw} \rt) \\ 
     1086  \label{eq:TRA_bbl_hor} 
     1087  \partial_t T^{sh}_{kup} &\equiv \partial_t T^{sh}_{kup} &&+ \frac{u^{tr}_{bbl}}{{b_t}^{sh}_{kup}} &&\lt( T^{do}_{kup} - T^{sh}_{kup} \rt) \\ 
     1088  \shortintertext{and for $k =kdw-1,\;..., \; kup$ :} 
     1089  \label{eq:TRA_bbl_up} 
     1090  \partial_t T^{do}_{k}   &\equiv \partial_t S^{do}_{k}   &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{k}}   &&\lt( T^{do}_{k +1} - T^{sh}_{k}   \rt) 
    10671091\end{alignat} 
    10681092where $b_t$ is the $T$-cell volume. 
     
    10711095It has to be used to compute the effective velocity as well as the effective overturning circulation. 
    10721096 
    1073 % ================================================================ 
    1074 % Tracer damping 
    1075 % ================================================================ 
    1076 \section{Tracer damping (\protect\mdl{tradmp})} 
     1097%% ================================================================================================= 
     1098\section[Tracer damping (\textit{tradmp.F90})]{Tracer damping (\protect\mdl{tradmp})} 
    10771099\label{sec:TRA_dmp} 
    1078 %--------------------------------------------namtra_dmp------------------------------------------------- 
    1079  
    1080 \nlst{namtra_dmp} 
    1081 %-------------------------------------------------------------------------------------------------------------- 
    1082  
    1083 In some applications it can be useful to add a Newtonian damping term into the temperature and salinity equations: 
    1084 \begin{equation} 
    1085   \label{eq:tra_dmp} 
    1086   \begin{gathered} 
    1087     \pd[T]{t} = \cdots - \gamma (T - T_o) \\ 
    1088     \pd[S]{t} = \cdots - \gamma (S - S_o) 
    1089   \end{gathered} 
    1090 \end{equation}  
    1091 where $\gamma$ is the inverse of a time scale, and $T_o$ and $S_o$ are given temperature and salinity fields 
    1092 (usually a climatology). 
    1093 Options are defined through the  \ngn{namtra\_dmp} namelist variables. 
    1094 The restoring term is added when the namelist parameter \np{ln\_tradmp} is set to true. 
    1095 It also requires that both \np{ln\_tsd\_init} and \np{ln\_tsd\_tradmp} are set to true in 
    1096 \ngn{namtsd} namelist as well as \np{sn\_tem} and \np{sn\_sal} structures are correctly set 
    1097 (\ie that $T_o$ and $S_o$ are provided in input files and read using \mdl{fldread}, 
     1100 
     1101\begin{listing} 
     1102  \nlst{namtra_dmp} 
     1103  \caption{\forcode{&namtra_dmp}} 
     1104  \label{lst:namtra_dmp} 
     1105\end{listing} 
     1106 
     1107In some applications it can be useful to add a Newtonian damping term into 
     1108the temperature and salinity equations: 
     1109\begin{equation} 
     1110  \label{eq:TRA_dmp} 
     1111    \pd[T]{t} = \cdots - \gamma (T - T_o) \qquad \pd[S]{t} = \cdots - \gamma (S - S_o) 
     1112\end{equation} 
     1113where $\gamma$ is the inverse of a time scale, 
     1114and $T_o$ and $S_o$ are given temperature and salinity fields (usually a climatology). 
     1115Options are defined through the \nam{tra_dmp}{tra\_dmp} namelist variables. 
     1116The restoring term is added when the namelist parameter \np{ln_tradmp}{ln\_tradmp} is set to true. 
     1117It also requires that both \np{ln_tsd_init}{ln\_tsd\_init} and 
     1118\np{ln_tsd_dmp}{ln\_tsd\_dmp} are set to true in \nam{tsd}{tsd} namelist as well as 
     1119\np{sn_tem}{sn\_tem} and \np{sn_sal}{sn\_sal} structures are correctly set 
     1120(\ie\ that $T_o$ and $S_o$ are provided in input files and read using \mdl{fldread}, 
    10981121see \autoref{subsec:SBC_fldread}). 
    1099 The restoring coefficient $\gamma$ is a three-dimensional array read in during the \rou{tra\_dmp\_init} routine. 
    1100 The file name is specified by the namelist variable \np{cn\_resto}. 
    1101 The DMP\_TOOLS tool is provided to allow users to generate the netcdf file. 
    1102  
    1103 The two main cases in which \autoref{eq:tra_dmp} is used are 
    1104 \textit{(a)} the specification of the boundary conditions along artificial walls of a limited domain basin and 
    1105 \textit{(b)} the computation of the velocity field associated with a given $T$-$S$ field 
    1106 (for example to build the initial state of a prognostic simulation, 
    1107 or to use the resulting velocity field for a passive tracer study). 
     1122The restoring coefficient $\gamma$ is a three-dimensional array read in during 
     1123the \rou{tra\_dmp\_init} routine. 
     1124The file name is specified by the namelist variable \np{cn_resto}{cn\_resto}. 
     1125The \texttt{DMP\_TOOLS} are provided to allow users to generate the netcdf file. 
     1126 
     1127The two main cases in which \autoref{eq:TRA_dmp} is used are 
     1128\begin{enumerate*}[label=(\textit{\alph*})] 
     1129\item the specification of the boundary conditions along 
     1130  artificial walls of a limited domain basin and 
     1131\item the computation of the velocity field associated with a given $T$-$S$ field 
     1132  (for example to build the initial state of a prognostic simulation, 
     1133  or to use the resulting velocity field for a passive tracer study). 
     1134\end{enumerate*} 
    11081135The first case applies to regional models that have artificial walls instead of open boundaries. 
    1109 In the vicinity of these walls, $\gamma$ takes large values (equivalent to a time scale of a few days) whereas 
    1110 it is zero in the interior of the model domain. 
    1111 The second case corresponds to the use of the robust diagnostic method \citep{Sarmiento1982}. 
     1136In the vicinity of these walls, $\gamma$ takes large values (equivalent to a time scale of a few days) 
     1137whereas it is zero in the interior of the model domain. 
     1138The second case corresponds to the use of the robust diagnostic method \citep{sarmiento.bryan_JGR82}. 
    11121139It allows us to find the velocity field consistent with the model dynamics whilst 
    11131140having a $T$, $S$ field close to a given climatological field ($T_o$, $S_o$). 
    11141141 
    1115 The robust diagnostic method is very efficient in preventing temperature drift in intermediate waters but 
    1116 it produces artificial sources of heat and salt within the ocean. 
     1142The robust diagnostic method is very efficient in preventing temperature drift in 
     1143intermediate waters but it produces artificial sources of heat and salt within the ocean. 
    11171144It also has undesirable effects on the ocean convection. 
    1118 It tends to prevent deep convection and subsequent deep-water formation, by stabilising the water column too much. 
    1119  
    1120 The namelist parameter \np{nn\_zdmp} sets whether the damping should be applied in the whole water column or 
    1121 only below the mixed layer (defined either on a density or $S_o$ criterion). 
     1145It tends to prevent deep convection and subsequent deep-water formation, 
     1146by stabilising the water column too much. 
     1147 
     1148The namelist parameter \np{nn_zdmp}{nn\_zdmp} sets whether the damping should be applied in 
     1149the whole water column or only below the mixed layer (defined either on a density or $S_o$ criterion). 
    11221150It is common to set the damping to zero in the mixed layer as the adjustment time scale is short here 
    1123 \citep{Madec_al_JPO96}. 
    1124  
    1125 For generating \ifile{resto}, see the documentation for the DMP tool provided with the source code under 
    1126 \path{./tools/DMP_TOOLS}. 
    1127  
    1128 % ================================================================ 
    1129 % Tracer time evolution 
    1130 % ================================================================ 
    1131 \section{Tracer time evolution (\protect\mdl{tranxt})} 
     1151\citep{madec.delecluse.ea_JPO96}. 
     1152 
     1153For generating \ifile{resto}, 
     1154see the documentation for the DMP tools provided with the source code under \path{./tools/DMP_TOOLS}. 
     1155 
     1156%% ================================================================================================= 
     1157\section[Tracer time evolution (\textit{tranxt.F90})]{Tracer time evolution (\protect\mdl{tranxt})} 
    11321158\label{sec:TRA_nxt} 
    1133 %--------------------------------------------namdom----------------------------------------------------- 
    1134  
    1135 \nlst{namdom} 
    1136 %-------------------------------------------------------------------------------------------------------------- 
    1137  
    1138 Options are defined through the \ngn{namdom} namelist variables. 
    1139 The general framework for tracer time stepping is a modified leap-frog scheme \citep{Leclair_Madec_OM09}, 
    1140 \ie a three level centred time scheme associated with a Asselin time filter (cf. \autoref{sec:STP_mLF}): 
    1141 \begin{equation} 
    1142   \label{eq:tra_nxt} 
    1143   \begin{alignedat}{3} 
     1159 
     1160Options are defined through the \nam{dom}{dom} namelist variables. 
     1161The general framework for tracer time stepping is a modified leap-frog scheme 
     1162\citep{leclair.madec_OM09}, \ie\ a three level centred time scheme associated with 
     1163a Asselin time filter (cf. \autoref{sec:TD_mLF}): 
     1164\begin{equation} 
     1165  \label{eq:TRA_nxt} 
     1166  \begin{alignedat}{5} 
    11441167    &(e_{3t}T)^{t + \rdt} &&= (e_{3t}T)_f^{t - \rdt} &&+ 2 \, \rdt \,e_{3t}^t \ \text{RHS}^t \\ 
    11451168    &(e_{3t}T)_f^t        &&= (e_{3t}T)^t            &&+ \, \gamma \, \lt[ (e_{3t}T)_f^{t - \rdt} - 2(e_{3t}T)^t + (e_{3t}T)^{t + \rdt} \rt] \\ 
    1146     &                     &&                         &&- \, \gamma \, \rdt \, \lt[ Q^{t + \rdt/2} - Q^{t - \rdt/2} \rt]   
     1169    &                     &&                         &&- \, \gamma \, \rdt \, \lt[ Q^{t + \rdt/2} - Q^{t - \rdt/2} \rt] 
    11471170  \end{alignedat} 
    1148 \end{equation}  
    1149 where RHS is the right hand side of the temperature equation, the subscript $f$ denotes filtered values, 
    1150 $\gamma$ is the Asselin coefficient, and $S$ is the total forcing applied on $T$ 
    1151 (\ie fluxes plus content in mass exchanges). 
    1152 $\gamma$ is initialized as \np{rn\_atfp} (\textbf{namelist} parameter). 
    1153 Its default value is \np{rn\_atfp}~\forcode{= 10.e-3}. 
     1171\end{equation} 
     1172where RHS is the right hand side of the temperature equation, 
     1173the subscript $f$ denotes filtered values, $\gamma$ is the Asselin coefficient, 
     1174and $S$ is the total forcing applied on $T$ (\ie\ fluxes plus content in mass exchanges). 
     1175$\gamma$ is initialized as \np{rn_atfp}{rn\_atfp}, its default value is \forcode{10.e-3}. 
    11541176Note that the forcing correction term in the filter is not applied in linear free surface 
    1155 (\jp{lk\_vvl}~\forcode{= .false.}) (see \autoref{subsec:TRA_sbc}). 
    1156 Not also that in constant volume case, the time stepping is performed on $T$, not on its content, $e_{3t}T$. 
    1157  
    1158 When the vertical mixing is solved implicitly, the update of the \textit{next} tracer fields is done in 
    1159 \mdl{trazdf} module. 
     1177(\jp{ln\_linssh}\forcode{=.true.}) (see \autoref{subsec:TRA_sbc}). 
     1178Not also that in constant volume case, the time stepping is performed on $T$, 
     1179not on its content, $e_{3t}T$. 
     1180 
     1181When the vertical mixing is solved implicitly, 
     1182the update of the \textit{next} tracer fields is done in \mdl{trazdf} module. 
    11601183In this case only the swapping of arrays and the Asselin filtering is done in the \mdl{tranxt} module. 
    11611184 
    1162 In order to prepare for the computation of the \textit{next} time step, a swap of tracer arrays is performed: 
    1163 $T^{t - \rdt} = T^t$ and $T^t = T_f$. 
    1164  
    1165 % ================================================================ 
    1166 % Equation of State (eosbn2)  
    1167 % ================================================================ 
    1168 \section{Equation of state (\protect\mdl{eosbn2}) } 
     1185In order to prepare for the computation of the \textit{next} time step, 
     1186a swap of tracer arrays is performed: $T^{t - \rdt} = T^t$ and $T^t = T_f$. 
     1187 
     1188%% ================================================================================================= 
     1189\section[Equation of state (\textit{eosbn2.F90})]{Equation of state (\protect\mdl{eosbn2})} 
    11691190\label{sec:TRA_eosbn2} 
    1170 %--------------------------------------------nameos----------------------------------------------------- 
    1171  
    1172 \nlst{nameos} 
    1173 %-------------------------------------------------------------------------------------------------------------- 
    1174  
    1175 % ------------------------------------------------------------------------------------------------------------- 
    1176 %        Equation of State 
    1177 % ------------------------------------------------------------------------------------------------------------- 
    1178 \subsection{Equation of seawater (\protect\np{nn\_eos}~\forcode{= -1..1})} 
     1191 
     1192\begin{listing} 
     1193  \nlst{nameos} 
     1194  \caption{\forcode{&nameos}} 
     1195  \label{lst:nameos} 
     1196\end{listing} 
     1197 
     1198%% ================================================================================================= 
     1199\subsection[Equation of seawater (\forcode{ln_}\{\forcode{teos10,eos80,seos}\})]{Equation of seawater (\protect\np{ln_teos10}{ln\_teos10}, \protect\np{ln_teos80}{ln\_teos80}, or \protect\np{ln_seos}{ln\_seos})} 
    11791200\label{subsec:TRA_eos} 
    11801201 
    1181 The Equation Of Seawater (EOS) is an empirical nonlinear thermodynamic relationship linking seawater density, 
    1182 $\rho$, to a number of state variables, most typically temperature, salinity and pressure. 
     1202The \textbf{E}quation \textbf{O}f \textbf{S}eawater (EOS) is 
     1203an empirical nonlinear thermodynamic relationship linking 
     1204seawater density, $\rho$, to a number of state variables, 
     1205most typically temperature, salinity and pressure. 
    11831206Because density gradients control the pressure gradient force through the hydrostatic balance, 
    1184 the equation of state provides a fundamental bridge between the distribution of active tracers and 
    1185 the fluid dynamics. 
     1207the equation of state provides a fundamental bridge between 
     1208the distribution of active tracers and the fluid dynamics. 
    11861209Nonlinearities of the EOS are of major importance, in particular influencing the circulation through 
    11871210determination of the static stability below the mixed layer, 
    1188 thus controlling rates of exchange between the atmosphere and the ocean interior \citep{Roquet_JPO2015}. 
    1189 Therefore an accurate EOS based on either the 1980 equation of state (EOS-80, \cite{UNESCO1983}) or 
    1190 TEOS-10 \citep{TEOS10} standards should be used anytime a simulation of the real ocean circulation is attempted 
    1191 \citep{Roquet_JPO2015}. 
     1211thus controlling rates of exchange between the atmosphere and the ocean interior 
     1212\citep{roquet.madec.ea_JPO15}. 
     1213Therefore an accurate EOS based on either the 1980 equation of state 
     1214(EOS-80, \cite{fofonoff.millard_bk83}) or TEOS-10 \citep{ioc.iapso_bk10} standards should 
     1215be used anytime a simulation of the real ocean circulation is attempted \citep{roquet.madec.ea_JPO15}. 
    11921216The use of TEOS-10 is highly recommended because 
    1193 \textit{(i)}   it is the new official EOS, 
    1194 \textit{(ii)}  it is more accurate, being based on an updated database of laboratory measurements, and 
    1195 \textit{(iii)} it uses Conservative Temperature and Absolute Salinity (instead of potential temperature and 
    1196 practical salinity for EOS-980, both variables being more suitable for use as model variables 
    1197 \citep{TEOS10, Graham_McDougall_JPO13}. 
    1198 EOS-80 is an obsolescent feature of the NEMO system, kept only for backward compatibility. 
     1217\begin{enumerate*}[label=(\textit{\roman*})] 
     1218\item it is the new official EOS, 
     1219\item it is more accurate, being based on an updated database of laboratory measurements, and 
     1220\item it uses Conservative Temperature and Absolute Salinity 
     1221  (instead of potential temperature and practical salinity for EOS-80), 
     1222  both variables being more suitable for use as model variables 
     1223  \citep{ioc.iapso_bk10, graham.mcdougall_JPO13}. 
     1224\end{enumerate*} 
     1225EOS-80 is an obsolescent feature of the \NEMO\ system, kept only for backward compatibility. 
    11991226For process studies, it is often convenient to use an approximation of the EOS. 
    1200 To that purposed, a simplified EOS (S-EOS) inspired by \citet{Vallis06} is also available. 
    1201  
    1202 In the computer code, a density anomaly, $d_a = \rho / \rho_o - 1$, is computed, with $\rho_o$ a reference density. 
    1203 Called \textit{rau0} in the code, $\rho_o$ is set in \mdl{phycst} to a value of $1,026~Kg/m^3$. 
    1204 This is a sensible choice for the reference density used in a Boussinesq ocean climate model, as, 
    1205 with the exception of only a small percentage of the ocean, 
    1206 density in the World Ocean varies by no more than 2$\%$ from that value \citep{Gill1982}. 
    1207  
    1208 Options are defined through the \ngn{nameos} namelist variables, and in particular \np{nn\_eos} which 
    1209 controls the EOS used (\forcode{= -1} for TEOS10 ; \forcode{= 0} for EOS-80 ; \forcode{= 1} for S-EOS). 
     1227To that purposed, a simplified EOS (S-EOS) inspired by \citet{vallis_bk06} is also available. 
     1228 
     1229In the computer code, a density anomaly, $d_a = \rho / \rho_o - 1$, is computed, 
     1230with $\rho_o$ a reference density. 
     1231Called \textit{rau0} in the code, 
     1232$\rho_o$ is set in \mdl{phycst} to a value of \texttt{1,026} $Kg/m^3$. 
     1233This is a sensible choice for the reference density used in a Boussinesq ocean climate model, 
     1234as, with the exception of only a small percentage of the ocean, 
     1235density in the World Ocean varies by no more than 2\% from that value \citep{gill_bk82}. 
     1236 
     1237Options which control the EOS used are defined through the \nam{eos}{eos} namelist variables. 
    12101238 
    12111239\begin{description} 
    1212 \item[\np{nn\_eos}~\forcode{= -1}] 
    1213   the polyTEOS10-bsq equation of seawater \citep{Roquet_OM2015} is used. 
     1240\item [{\np[=.true.]{ln_teos10}{ln\_teos10}}] the polyTEOS10-bsq equation of seawater 
     1241  \citep{roquet.madec.ea_OM15} is used. 
    12141242  The accuracy of this approximation is comparable to the TEOS-10 rational function approximation, 
    1215   but it is optimized for a boussinesq fluid and the polynomial expressions have simpler and 
    1216   more computationally efficient expressions for their derived quantities which make them more adapted for 
    1217   use in ocean models. 
    1218   Note that a slightly higher precision polynomial form is now used replacement of 
    1219   the TEOS-10 rational function approximation for hydrographic data analysis \citep{TEOS10}. 
     1243  but it is optimized for a Boussinesq fluid and 
     1244  the polynomial expressions have simpler and more computationally efficient expressions for 
     1245  their derived quantities which make them more adapted for use in ocean models. 
     1246  Note that a slightly higher precision polynomial form is now used 
     1247  replacement of the TEOS-10 rational function approximation for hydrographic data analysis 
     1248  \citep{ioc.iapso_bk10}. 
    12201249  A key point is that conservative state variables are used: 
    1221   Absolute Salinity (unit: g/kg, notation: $S_A$) and Conservative Temperature (unit: \deg{C}, notation: $\Theta$). 
     1250  Absolute Salinity (unit: $g/kg$, notation: $S_A$) and 
     1251  Conservative Temperature (unit: $\deg{C}$, notation: $\Theta$). 
    12221252  The pressure in decibars is approximated by the depth in meters. 
    12231253  With TEOS10, the specific heat capacity of sea water, $C_p$, is a constant. 
    1224   It is set to $C_p = 3991.86795711963~J\,Kg^{-1}\,^{\circ}K^{-1}$, according to \citet{TEOS10}. 
     1254  It is set to $C_p$ = 3991.86795711963 $J.Kg^{-1}.\deg{K}^{-1}$, 
     1255  according to \citet{ioc.iapso_bk10}. 
    12251256  Choosing polyTEOS10-bsq implies that the state variables used by the model are $\Theta$ and $S_A$. 
    1226   In particular, the initial state deined by the user have to be given as \textit{Conservative} Temperature and 
    1227   \textit{Absolute} Salinity. 
    1228   In addition, setting \np{ln\_useCT} to \forcode{.true.} convert the Conservative SST to potential SST prior to 
     1257  In particular, the initial state defined by the user have to be given as 
     1258  \textit{Conservative} Temperature and \textit{Absolute} Salinity. 
     1259  In addition, when using TEOS10, the Conservative SST is converted to potential SST prior to 
    12291260  either computing the air-sea and ice-sea fluxes (forced mode) or 
    12301261  sending the SST field to the atmosphere (coupled mode). 
    1231 \item[\np{nn\_eos}~\forcode{= 0}] 
    1232   the polyEOS80-bsq equation of seawater is used. 
    1233   It takes the same polynomial form as the polyTEOS10, but the coefficients have been optimized to 
    1234   accurately fit EOS80 (Roquet, personal comm.). 
     1262\item [{\np[=.true.]{ln_eos80}{ln\_eos80}}] the polyEOS80-bsq equation of seawater is used. 
     1263  It takes the same polynomial form as the polyTEOS10, 
     1264  but the coefficients have been optimized to accurately fit EOS80 (Roquet, personal comm.). 
    12351265  The state variables used in both the EOS80 and the ocean model are: 
    1236   the Practical Salinity ((unit: psu, notation: $S_p$)) and 
    1237   Potential Temperature (unit: $^{\circ}C$, notation: $\theta$). 
     1266  the Practical Salinity (unit: $psu$, notation: $S_p$) and 
     1267  Potential Temperature (unit: $\deg{C}$, notation: $\theta$). 
    12381268  The pressure in decibars is approximated by the depth in meters. 
    1239   With thsi EOS, the specific heat capacity of sea water, $C_p$, is a function of temperature, salinity and 
    1240   pressure \citep{UNESCO1983}. 
     1269  With EOS, the specific heat capacity of sea water, $C_p$, is a function of 
     1270  temperature, salinity and pressure \citep{fofonoff.millard_bk83}. 
    12411271  Nevertheless, a severe assumption is made in order to have a heat content ($C_p T_p$) which 
    12421272  is conserved by the model: $C_p$ is set to a constant value, the TEOS10 value. 
    1243 \item[\np{nn\_eos}~\forcode{= 1}] 
    1244   a simplified EOS (S-EOS) inspired by \citet{Vallis06} is chosen, 
    1245   the coefficients of which has been optimized to fit the behavior of TEOS10 
    1246   (Roquet, personal comm.) (see also \citet{Roquet_JPO2015}). 
     1273\item [{\np[=.true.]{ln_seos}{ln\_seos}}] a simplified EOS (S-EOS) inspired by 
     1274  \citet{vallis_bk06} is chosen, 
     1275  the coefficients of which has been optimized to fit the behavior of TEOS10 (Roquet, personal comm.) 
     1276  (see also \citet{roquet.madec.ea_JPO15}). 
    12471277  It provides a simplistic linear representation of both cabbeling and thermobaricity effects which 
    1248   is enough for a proper treatment of the EOS in theoretical studies \citep{Roquet_JPO2015}. 
    1249   With such an equation of state there is no longer a distinction between 
    1250   \textit{conservative} and \textit{potential} temperature, 
    1251   as well as between \textit{absolute} and \textit{practical} salinity. 
     1278  is enough for a proper treatment of the EOS in theoretical studies \citep{roquet.madec.ea_JPO15}. 
     1279  With such an equation of state there is no longer a distinction between \textit{conservative} and 
     1280  \textit{potential} temperature, as well as between \textit{absolute} and 
     1281  \textit{practical} salinity. 
    12521282  S-EOS takes the following expression: 
    12531283  \begin{gather*} 
    1254     % \label{eq:tra_S-EOS} 
    1255     \begin{alignedat}{2} 
    1256     &d_a(T,S,z) = \frac{1}{\rho_o} \big[ &- a_0 \; ( 1 + 0.5 \; \lambda_1 \; T_a + \mu_1 \; z ) * &T_a \big. \\ 
    1257     &                                    &+ b_0 \; ( 1 - 0.5 \; \lambda_2 \; S_a - \mu_2 \; z ) * &S_a       \\   
    1258     &                              \big. &- \nu \;                           T_a                  &S_a \big] \\ 
    1259     \end{alignedat} 
    1260     \\ 
     1284    % \label{eq:TRA_S-EOS} 
     1285    d_a(T,S,z) = \frac{1}{\rho_o} \big[ - a_0 \; ( 1 + 0.5 \; \lambda_1 \; T_a + \mu_1 \; z ) * T_a \big. 
     1286                                        + b_0 \; ( 1 - 0.5 \; \lambda_2 \; S_a - \mu_2 \; z ) * S_a 
     1287                                  \big. - \nu \;                           T_a                  S_a \big] \\ 
    12611288    \text{with~} T_a = T - 10 \, ; \, S_a = S - 35 \, ; \, \rho_o = 1026~Kg/m^3 
    12621289  \end{gather*} 
    1263   where the computer name of the coefficients as well as their standard value are given in \autoref{tab:SEOS}. 
     1290  where the computer name of the coefficients as well as their standard value are given in 
     1291  \autoref{tab:TRA_SEOS}. 
    12641292  In fact, when choosing S-EOS, various approximation of EOS can be specified simply by 
    12651293  changing the associated coefficients. 
    1266   Setting to zero the two thermobaric coefficients $(\mu_1,\mu_2)$ remove thermobaric effect from S-EOS. 
    1267   setting to zero the three cabbeling coefficients $(\lambda_1,\lambda_2,\nu)$ remove cabbeling effect from 
    1268   S-EOS. 
     1294  Setting to zero the two thermobaric coefficients $(\mu_1,\mu_2)$ 
     1295  remove thermobaric effect from S-EOS. 
     1296  Setting to zero the three cabbeling coefficients $(\lambda_1,\lambda_2,\nu)$ 
     1297  remove   cabbeling effect from S-EOS. 
    12691298  Keeping non-zero value to $a_0$ and $b_0$ provide a linear EOS function of T and S. 
    12701299\end{description} 
    12711300 
    1272 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1273 \begin{table}[!tb] 
    1274   \begin{center} 
    1275     \begin{tabular}{|l|l|l|l|} 
    1276       \hline 
    1277       coeff.      & computer name   & S-EOS           & description                      \\ 
    1278       \hline 
    1279       $a_0$       & \np{rn\_a0}     & $1.6550~10^{-1}$ & linear thermal expansion coeff. \\ 
    1280       \hline 
    1281       $b_0$       & \np{rn\_b0}     & $7.6554~10^{-1}$ & linear haline  expansion coeff. \\ 
    1282       \hline 
    1283       $\lambda_1$ & \np{rn\_lambda1}& $5.9520~10^{-2}$ & cabbeling coeff. in $T^2$       \\ 
    1284       \hline 
    1285       $\lambda_2$ & \np{rn\_lambda2}& $5.4914~10^{-4}$ & cabbeling coeff. in $S^2$       \\ 
    1286       \hline 
    1287       $\nu$       & \np{rn\_nu}     & $2.4341~10^{-3}$ & cabbeling coeff. in $T \, S$    \\ 
    1288       \hline 
    1289       $\mu_1$     & \np{rn\_mu1}    & $1.4970~10^{-4}$ & thermobaric coeff. in T         \\ 
    1290       \hline 
    1291       $\mu_2$     & \np{rn\_mu2}    & $1.1090~10^{-5}$ & thermobaric coeff. in S         \\ 
    1292       \hline 
    1293     \end{tabular} 
    1294     \caption{ 
    1295       \protect\label{tab:SEOS} 
    1296       Standard value of S-EOS coefficients. 
    1297     } 
    1298 \end{center} 
     1301\begin{table} 
     1302  \centering 
     1303  \begin{tabular}{|l|l|l|l|} 
     1304    \hline 
     1305    coeff.      & computer name                & S-EOS            & description                     \\ 
     1306    \hline 
     1307    $a_0      $ & \np{rn_a0}{rn\_a0}           & $1.6550~10^{-1}$ & linear thermal expansion coeff. \\ 
     1308    \hline 
     1309    $b_0      $ & \np{rn_b0}{rn\_b0}           & $7.6554~10^{-1}$ & linear haline  expansion coeff. \\ 
     1310    \hline 
     1311    $\lambda_1$ & \np{rn_lambda1}{rn\_lambda1} & $5.9520~10^{-2}$ & cabbeling coeff. in $T^2$       \\ 
     1312    \hline 
     1313    $\lambda_2$ & \np{rn_lambda2}{rn\_lambda2} & $5.4914~10^{-4}$ & cabbeling coeff. in $S^2$       \\ 
     1314    \hline 
     1315    $\nu      $ & \np{rn_nu}{rn\_nu}           & $2.4341~10^{-3}$ & cabbeling coeff. in $T \, S$    \\ 
     1316    \hline 
     1317    $\mu_1    $ & \np{rn_mu1}{rn\_mu1}         & $1.4970~10^{-4}$ & thermobaric coeff. in T         \\ 
     1318    \hline 
     1319    $\mu_2    $ & \np{rn_mu2}{rn\_mu2}         & $1.1090~10^{-5}$ & thermobaric coeff. in S         \\ 
     1320    \hline 
     1321  \end{tabular} 
     1322  \caption{Standard value of S-EOS coefficients} 
     1323  \label{tab:TRA_SEOS} 
    12991324\end{table} 
    1300 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1301  
    1302 % ------------------------------------------------------------------------------------------------------------- 
    1303 %        Brunt-V\"{a}is\"{a}l\"{a} Frequency 
    1304 % ------------------------------------------------------------------------------------------------------------- 
    1305 \subsection{Brunt-V\"{a}is\"{a}l\"{a} frequency (\protect\np{nn\_eos}~\forcode{= 0..2})} 
     1325 
     1326%% ================================================================================================= 
     1327\subsection[Brunt-V\"{a}is\"{a}l\"{a} frequency]{Brunt-V\"{a}is\"{a}l\"{a} frequency} 
    13061328\label{subsec:TRA_bn2} 
    13071329 
    1308 An accurate computation of the ocean stability (i.e. of $N$, the brunt-V\"{a}is\"{a}l\"{a} frequency) is of 
    1309 paramount importance as determine the ocean stratification and is used in several ocean parameterisations 
     1330An accurate computation of the ocean stability (i.e. of $N$, the Brunt-V\"{a}is\"{a}l\"{a} frequency) is of paramount importance as determine the ocean stratification and 
     1331is used in several ocean parameterisations 
    13101332(namely TKE, GLS, Richardson number dependent vertical diffusion, enhanced vertical diffusion, 
    13111333non-penetrative convection, tidal mixing  parameterisation, iso-neutral diffusion). 
    13121334In particular, $N^2$ has to be computed at the local pressure 
    13131335(pressure in decibar being approximated by the depth in meters). 
    1314 The expression for $N^2$  is given by:  
     1336The expression for $N^2$  is given by: 
    13151337\[ 
    1316   % \label{eq:tra_bn2} 
     1338  % \label{eq:TRA_bn2} 
    13171339  N^2 = \frac{g}{e_{3w}} \lt( \beta \; \delta_{k + 1/2}[S] - \alpha \; \delta_{k + 1/2}[T] \rt) 
    13181340\] 
    13191341where $(T,S) = (\Theta,S_A)$ for TEOS10, $(\theta,S_p)$ for TEOS-80, or $(T,S)$ for S-EOS, and, 
    13201342$\alpha$ and $\beta$ are the thermal and haline expansion coefficients. 
    1321 The coefficients are a polynomial function of temperature, salinity and depth which expression depends on 
    1322 the chosen EOS. 
    1323 They are computed through \textit{eos\_rab}, a \fortran function that can be found in \mdl{eosbn2}. 
    1324  
    1325 % ------------------------------------------------------------------------------------------------------------- 
    1326 %        Freezing Point of Seawater 
    1327 % ------------------------------------------------------------------------------------------------------------- 
     1343The coefficients are a polynomial function of temperature, salinity and depth which 
     1344expression depends on the chosen EOS. 
     1345They are computed through \textit{eos\_rab}, a \fortran\ function that can be found in \mdl{eosbn2}. 
     1346 
     1347%% ================================================================================================= 
    13281348\subsection{Freezing point of seawater} 
    13291349\label{subsec:TRA_fzp} 
    13301350 
    1331 The freezing point of seawater is a function of salinity and pressure \citep{UNESCO1983}: 
    1332 \begin{equation} 
    1333   \label{eq:tra_eos_fzp} 
    1334   \begin{split} 
    1335     &T_f (S,p) = \lt( a + b \, \sqrt{S} + c \, S \rt) \, S + d \, p \\ 
    1336     &\text{where~} a = -0.0575, \, b = 1.710523~10^{-3}, \, c = -2.154996~10^{-4} \\  
    1337     &\text{and~} d = -7.53~10^{-3} 
    1338     \end{split} 
    1339 \end{equation} 
    1340  
    1341 \autoref{eq:tra_eos_fzp} is only used to compute the potential freezing point of sea water 
    1342 (\ie referenced to the surface $p = 0$), 
    1343 thus the pressure dependent terms in \autoref{eq:tra_eos_fzp} (last term) have been dropped. 
     1351The freezing point of seawater is a function of salinity and pressure \citep{fofonoff.millard_bk83}: 
     1352\begin{equation} 
     1353  \label{eq:TRA_eos_fzp} 
     1354  \begin{gathered} 
     1355    T_f (S,p) = \lt( a + b \, \sqrt{S} + c \, S \rt) \, S + d \, p \\ 
     1356    \text{where~} a = -0.0575, \, b = 1.710523~10^{-3}, \, c = -2.154996~10^{-4} \text{and~} d = -7.53~10^{-3} 
     1357    \end{gathered} 
     1358\end{equation} 
     1359 
     1360\autoref{eq:TRA_eos_fzp} is only used to compute the potential freezing point of sea water 
     1361(\ie\ referenced to the surface $p = 0$), 
     1362thus the pressure dependent terms in \autoref{eq:TRA_eos_fzp} (last term) have been dropped. 
    13441363The freezing point is computed through \textit{eos\_fzp}, 
    1345 a \fortran function that can be found in \mdl{eosbn2}. 
    1346  
    1347 % ------------------------------------------------------------------------------------------------------------- 
    1348 %        Potential Energy      
    1349 % ------------------------------------------------------------------------------------------------------------- 
     1364a \fortran\ function that can be found in \mdl{eosbn2}. 
     1365 
     1366%% ================================================================================================= 
    13501367%\subsection{Potential Energy anomalies} 
    13511368%\label{subsec:TRA_bn2} 
    13521369 
    13531370%    =====>>>>> TO BE written 
    1354 % 
    1355  
    1356 % ================================================================ 
    1357 % Horizontal Derivative in zps-coordinate  
    1358 % ================================================================ 
    1359 \section{Horizontal derivative in \textit{zps}-coordinate (\protect\mdl{zpshde})} 
     1371 
     1372%% ================================================================================================= 
     1373\section[Horizontal derivative in \textit{zps}-coordinate (\textit{zpshde.F90})]{Horizontal derivative in \textit{zps}-coordinate (\protect\mdl{zpshde})} 
    13601374\label{sec:TRA_zpshde} 
    13611375 
    1362 \gmcomment{STEVEN: to be consistent with earlier discussion of differencing and averaging operators,  
     1376\cmtgm{STEVEN: to be consistent with earlier discussion of differencing and averaging operators, 
    13631377I've changed "derivative" to "difference" and "mean" to "average"} 
    13641378 
    1365 With partial cells (\np{ln\_zps}~\forcode{= .true.}) at bottom and top (\np{ln\_isfcav}~\forcode{= .true.}), 
     1379With partial cells (\np[=.true.]{ln_zps}{ln\_zps}) at bottom and top 
     1380(\np[=.true.]{ln_isfcav}{ln\_isfcav}), 
    13661381in general, tracers in horizontally adjacent cells live at different depths. 
    1367 Horizontal gradients of tracers are needed for horizontal diffusion (\mdl{traldf} module) and 
    1368 the hydrostatic pressure gradient calculations (\mdl{dynhpg} module). 
    1369 The partial cell properties at the top (\np{ln\_isfcav}~\forcode{= .true.}) are computed in the same way as 
    1370 for the bottom. 
     1382Horizontal gradients of tracers are needed for horizontal diffusion 
     1383(\mdl{traldf} module) and the hydrostatic pressure gradient calculations (\mdl{dynhpg} module). 
     1384The partial cell properties at the top (\np[=.true.]{ln_isfcav}{ln\_isfcav}) are computed in 
     1385the same way as for the bottom. 
    13711386So, only the bottom interpolation is explained below. 
    13721387 
    13731388Before taking horizontal gradients between the tracers next to the bottom, 
    13741389a linear interpolation in the vertical is used to approximate the deeper tracer as if 
    1375 it actually lived at the depth of the shallower tracer point (\autoref{fig:Partial_step_scheme}). 
    1376 For example, for temperature in the $i$-direction the needed interpolated temperature, $\widetilde T$, is: 
    1377  
    1378 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1379 \begin{figure}[!p] 
    1380   \begin{center} 
    1381     \includegraphics[]{Fig_partial_step_scheme} 
    1382     \caption{ 
    1383       \protect\label{fig:Partial_step_scheme} 
    1384       Discretisation of the horizontal difference and average of tracers in the $z$-partial step coordinate 
    1385       (\protect\np{ln\_zps}~\forcode{= .true.}) in the case $(e3w_k^{i + 1} - e3w_k^i) > 0$. 
    1386       A linear interpolation is used to estimate $\widetilde T_k^{i + 1}$, 
    1387       the tracer value at the depth of the shallower tracer point of the two adjacent bottom $T$-points. 
    1388       The horizontal difference is then given by: $\delta_{i + 1/2} T_k = \widetilde T_k^{\, i + 1} -T_k^{\, i}$ and 
    1389       the average by: $\overline T_k^{\, i + 1/2} = (\widetilde T_k^{\, i + 1/2} - T_k^{\, i}) / 2$. 
    1390     } 
    1391   \end{center} 
     1390it actually lived at the depth of the shallower tracer point (\autoref{fig:TRA_Partial_step_scheme}). 
     1391For example, for temperature in the $i$-direction the needed interpolated temperature, 
     1392$\widetilde T$, is: 
     1393 
     1394\begin{figure} 
     1395  \centering 
     1396  \includegraphics[width=0.33\textwidth]{TRA_partial_step_scheme} 
     1397  \caption[Discretisation of the horizontal difference and average of tracers in 
     1398  the $z$-partial step coordinate]{ 
     1399    Discretisation of the horizontal difference and average of tracers in 
     1400    the $z$-partial step coordinate (\protect\np[=.true.]{ln_zps}{ln\_zps}) in 
     1401    the case $(e3w_k^{i + 1} - e3w_k^i) > 0$. 
     1402    A linear interpolation is used to estimate $\widetilde T_k^{i + 1}$, 
     1403    the tracer value at the depth of the shallower tracer point of the two adjacent bottom $T$-points. 
     1404    The horizontal difference is then given by: 
     1405    $\delta_{i + 1/2} T_k = \widetilde T_k^{\, i + 1} -T_k^{\, i}$ and the average by: 
     1406    $\overline T_k^{\, i + 1/2} = (\widetilde T_k^{\, i + 1/2} - T_k^{\, i}) / 2$.} 
     1407  \label{fig:TRA_Partial_step_scheme} 
    13921408\end{figure} 
    1393 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     1409 
    13941410\[ 
    13951411  \widetilde T = \lt\{ 
    13961412    \begin{alignedat}{2} 
    13971413      &T^{\, i + 1} &-\frac{ \lt( e_{3w}^{i + 1} -e_{3w}^i \rt) }{ e_{3w}^{i + 1} } \; \delta_k T^{i + 1} 
    1398       & \quad \text{if $e_{3w}^{i + 1} \geq e_{3w}^i$} \\ \\ 
     1414      & \quad \text{if $e_{3w}^{i + 1} \geq e_{3w}^i$} \\ 
    13991415      &T^{\, i}     &+\frac{ \lt( e_{3w}^{i + 1} -e_{3w}^i \rt )}{e_{3w}^i       } \; \delta_k T^{i + 1} 
    14001416      & \quad \text{if $e_{3w}^{i + 1} <    e_{3w}^i$} 
     
    14021418  \rt. 
    14031419\] 
    1404 and the resulting forms for the horizontal difference and the horizontal average value of $T$ at a $U$-point are:  
    1405 \begin{equation} 
    1406   \label{eq:zps_hde} 
     1420and the resulting forms for the horizontal difference and the horizontal average value of 
     1421$T$ at a $U$-point are: 
     1422\begin{equation} 
     1423  \label{eq:TRA_zps_hde} 
    14071424  \begin{split} 
    14081425    \delta_{i + 1/2} T       &= 
    14091426    \begin{cases} 
    1410                                 \widetilde T - T^i          & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\ 
    1411                                 \\ 
    1412                                 T^{\, i + 1} - \widetilde T & \text{if~} e_{3w}^{i + 1} <    e_{3w}^i 
    1413     \end{cases} 
    1414     \\ 
     1427      \widetilde T - T^i          & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\ 
     1428      T^{\, i + 1} - \widetilde T & \text{if~} e_{3w}^{i + 1} <    e_{3w}^i 
     1429    \end{cases} \\ 
    14151430    \overline T^{\, i + 1/2} &= 
    14161431    \begin{cases} 
    1417                                 (\widetilde T - T^{\, i}   ) / 2 & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\ 
    1418                                 \\ 
    1419                                 (T^{\, i + 1} - \widetilde T) / 2 & \text{if~} e_{3w}^{i + 1} <   e_{3w}^i 
     1432      (\widetilde T - T^{\, i}    ) / 2 & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\ 
     1433      (T^{\, i + 1} - \widetilde T) / 2 & \text{if~} e_{3w}^{i + 1} <   e_{3w}^i 
    14201434    \end{cases} 
    14211435  \end{split} 
     
    14241438The computation of horizontal derivative of tracers as well as of density is performed once for all at 
    14251439each time step in \mdl{zpshde} module and stored in shared arrays to be used when needed. 
    1426 It has to be emphasized that the procedure used to compute the interpolated density, $\widetilde \rho$, 
    1427 is not the same as that used for $T$ and $S$. 
    1428 Instead of forming a linear approximation of density, we compute $\widetilde \rho$ from the interpolated values of 
    1429 $T$ and $S$, and the pressure at a $u$-point 
    1430 (in the equation of state pressure is approximated by depth, see \autoref{subsec:TRA_eos}):  
     1440It has to be emphasized that the procedure used to compute the interpolated density, 
     1441$\widetilde \rho$, is not the same as that used for $T$ and $S$. 
     1442Instead of forming a linear approximation of density, 
     1443we compute $\widetilde \rho$ from the interpolated values of $T$ and $S$, 
     1444and the pressure at a $u$-point 
     1445(in the equation of state pressure is approximated by depth, see \autoref{subsec:TRA_eos}): 
    14311446\[ 
    1432   % \label{eq:zps_hde_rho} 
     1447  % \label{eq:TRA_zps_hde_rho} 
    14331448  \widetilde \rho = \rho (\widetilde T,\widetilde S,z_u) \quad \text{where~} z_u = \min \lt( z_T^{i + 1},z_T^i \rt) 
    14341449\] 
    14351450 
    14361451This is a much better approximation as the variation of $\rho$ with depth (and thus pressure) 
    1437 is highly non-linear with a true equation of state and thus is badly approximated with a linear interpolation. 
    1438 This approximation is used to compute both the horizontal pressure gradient (\autoref{sec:DYN_hpg}) and 
    1439 the slopes of neutral surfaces (\autoref{sec:LDF_slp}). 
    1440  
    1441 Note that in almost all the advection schemes presented in this Chapter, 
     1452is highly non-linear with a true equation of state and thus is badly approximated with 
     1453a linear interpolation. 
     1454This approximation is used to compute both the horizontal pressure gradient (\autoref{sec:DYN_hpg}) 
     1455and the slopes of neutral surfaces (\autoref{sec:LDF_slp}). 
     1456 
     1457Note that in almost all the advection schemes presented in this chapter, 
    14421458both averaging and differencing operators appear. 
    1443 Yet \autoref{eq:zps_hde} has not been used in these schemes: 
     1459Yet \autoref{eq:TRA_zps_hde} has not been used in these schemes: 
    14441460in contrast to diffusion and pressure gradient computations, 
    14451461no correction for partial steps is applied for advection. 
    14461462The main motivation is to preserve the domain averaged mean variance of the advected field when 
    14471463using the $2^{nd}$ order centred scheme. 
    1448 Sensitivity of the advection schemes to the way horizontal averages are performed in the vicinity of 
    1449 partial cells should be further investigated in the near future. 
    1450 %%% 
    1451 \gmcomment{gm :   this last remark has to be done} 
    1452 %%% 
    1453  
    1454 \biblio 
    1455  
    1456 \pindex 
     1464Sensitivity of the advection schemes to the way horizontal averages are performed in 
     1465the vicinity of partial cells should be further investigated in the near future. 
     1466\cmtgm{gm :   this last remark has to be done} 
     1467 
     1468\subinc{\input{../../global/epilogue}} 
    14571469 
    14581470\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_ZDF.tex

    r10442 r11831  
    11\documentclass[../main/NEMO_manual]{subfiles} 
    22 
     3%% Custom aliases 
     4\newcommand{\cf}{\ensuremath{C\kern-0.14em f}} 
     5 
    36\begin{document} 
    4 % ================================================================ 
    5 % Chapter  Vertical Ocean Physics (ZDF) 
    6 % ================================================================ 
     7 
    78\chapter{Vertical Ocean Physics (ZDF)} 
    89\label{chap:ZDF} 
    910 
    10 \minitoc 
    11  
    12 %gm% Add here a small introduction to ZDF and naming of the different physics (similar to what have been written for TRA and DYN. 
    13  
    14 \newpage 
    15  
    16 % ================================================================ 
    17 % Vertical Mixing 
    18 % ================================================================ 
     11\thispagestyle{plain} 
     12 
     13\chaptertoc 
     14 
     15\paragraph{Changes record} ~\\ 
     16 
     17{\footnotesize 
     18  \begin{tabularx}{\textwidth}{l||X|X} 
     19    Release & Author(s) & Modifications \\ 
     20    \hline 
     21    {\em   4.0} & {\em ...} & {\em ...} \\ 
     22    {\em   3.6} & {\em ...} & {\em ...} \\ 
     23    {\em   3.4} & {\em ...} & {\em ...} \\ 
     24    {\em <=3.4} & {\em ...} & {\em ...} 
     25  \end{tabularx} 
     26} 
     27 
     28\clearpage 
     29 
     30\cmtgm{ Add here a small introduction to ZDF and naming of the different physics 
     31(similar to what have been written for TRA and DYN).} 
     32 
     33%% ================================================================================================= 
    1934\section{Vertical mixing} 
    20 \label{sec:ZDF_zdf} 
     35\label{sec:ZDF} 
    2136 
    2237The discrete form of the ocean subgrid scale physics has been presented in 
     
    2540At the surface they are prescribed from the surface forcing (see \autoref{chap:SBC}), 
    2641while at the bottom they are set to zero for heat and salt, 
    27 unless a geothermal flux forcing is prescribed as a bottom boundary condition (\ie \key{trabbl} defined, 
     42unless a geothermal flux forcing is prescribed as a bottom boundary condition (\ie\ \np{ln_trabbc}{ln\_trabbc} defined, 
    2843see \autoref{subsec:TRA_bbc}), and specified through a bottom friction parameterisation for momentum 
    29 (see \autoref{sec:ZDF_bfr}). 
     44(see \autoref{sec:ZDF_drg}). 
    3045 
    3146In this section we briefly discuss the various choices offered to compute the vertical eddy viscosity and 
     
    3348respectively (see \autoref{sec:TRA_zdf} and \autoref{sec:DYN_zdf}). 
    3449These coefficients can be assumed to be either constant, or a function of the local Richardson number, 
    35 or computed from a turbulent closure model (either TKE or GLS formulation). 
    36 The computation of these coefficients is initialized in the \mdl{zdfini} module and performed in 
    37 the \mdl{zdfric}, \mdl{zdftke} or \mdl{zdfgls} modules. 
     50or computed from a turbulent closure model (either TKE or GLS or OSMOSIS formulation). 
     51The computation of these coefficients is initialized in the \mdl{zdfphy} module and performed in 
     52the \mdl{zdfric}, \mdl{zdftke} or \mdl{zdfgls} or \mdl{zdfosm} modules. 
    3853The trends due to the vertical momentum and tracer diffusion, including the surface forcing, 
    39 are computed and added to the general trend in the \mdl{dynzdf} and \mdl{trazdf} modules, respectively.  
    40 These trends can be computed using either a forward time stepping scheme 
    41 (namelist parameter \np{ln\_zdfexp}\forcode{ = .true.}) or a backward time stepping scheme 
    42 (\np{ln\_zdfexp}\forcode{ = .false.}) depending on the magnitude of the mixing coefficients, 
    43 and thus of the formulation used (see \autoref{chap:STP}). 
    44  
    45 % ------------------------------------------------------------------------------------------------------------- 
    46 %        Constant  
    47 % ------------------------------------------------------------------------------------------------------------- 
    48 \subsection{Constant (\protect\key{zdfcst})} 
     54are computed and added to the general trend in the \mdl{dynzdf} and \mdl{trazdf} modules, respectively. 
     55%These trends can be computed using either a forward time stepping scheme 
     56%(namelist parameter \np[=.true.]{ln_zdfexp}{ln\_zdfexp}) or a backward time stepping scheme 
     57%(\np[=.false.]{ln_zdfexp}{ln\_zdfexp}) depending on the magnitude of the mixing coefficients, 
     58%and thus of the formulation used (see \autoref{chap:TD}). 
     59 
     60\begin{listing} 
     61  \nlst{namzdf} 
     62  \caption{\forcode{&namzdf}} 
     63  \label{lst:namzdf} 
     64\end{listing} 
     65 
     66%% ================================================================================================= 
     67\subsection[Constant (\forcode{ln_zdfcst})]{Constant (\protect\np{ln_zdfcst}{ln\_zdfcst})} 
    4968\label{subsec:ZDF_cst} 
    50 %--------------------------------------------namzdf--------------------------------------------------------- 
    51  
    52 \nlst{namzdf} 
    53 %-------------------------------------------------------------------------------------------------------------- 
    54  
    55 Options are defined through the \ngn{namzdf} namelist variables. 
    56 When \key{zdfcst} is defined, the momentum and tracer vertical eddy coefficients are set to 
     69 
     70Options are defined through the \nam{zdf}{zdf} namelist variables. 
     71When \np{ln_zdfcst}{ln\_zdfcst} is defined, the momentum and tracer vertical eddy coefficients are set to 
    5772constant values over the whole ocean. 
    5873This is the crudest way to define the vertical ocean physics. 
    59 It is recommended that this option is only used in process studies, not in basin scale simulations. 
     74It is recommended to use this option only in process studies, not in basin scale simulations. 
    6075Typical values used in this case are: 
    6176\begin{align*} 
     
    6479\end{align*} 
    6580 
    66 These values are set through the \np{rn\_avm0} and \np{rn\_avt0} namelist parameters.  
     81These values are set through the \np{rn_avm0}{rn\_avm0} and \np{rn_avt0}{rn\_avt0} namelist parameters. 
    6782In all cases, do not use values smaller that those associated with the molecular viscosity and diffusivity, 
    6883that is $\sim10^{-6}~m^2.s^{-1}$ for momentum, $\sim10^{-7}~m^2.s^{-1}$ for temperature and 
    6984$\sim10^{-9}~m^2.s^{-1}$ for salinity. 
    7085 
    71 % ------------------------------------------------------------------------------------------------------------- 
    72 %        Richardson Number Dependent 
    73 % ------------------------------------------------------------------------------------------------------------- 
    74 \subsection{Richardson number dependent (\protect\key{zdfric})} 
     86%% ================================================================================================= 
     87\subsection[Richardson number dependent (\forcode{ln_zdfric})]{Richardson number dependent (\protect\np{ln_zdfric}{ln\_zdfric})} 
    7588\label{subsec:ZDF_ric} 
    7689 
    77 %--------------------------------------------namric--------------------------------------------------------- 
    78  
    79 \nlst{namzdf_ric} 
    80 %-------------------------------------------------------------------------------------------------------------- 
    81  
    82 When \key{zdfric} is defined, a local Richardson number dependent formulation for the vertical momentum and 
    83 tracer eddy coefficients is set through the \ngn{namzdf\_ric} namelist variables. 
    84 The vertical mixing coefficients are diagnosed from the large scale variables computed by the model.  
     90\begin{listing} 
     91  \nlst{namzdf_ric} 
     92  \caption{\forcode{&namzdf_ric}} 
     93  \label{lst:namzdf_ric} 
     94\end{listing} 
     95 
     96When \np[=.true.]{ln_zdfric}{ln\_zdfric}, a local Richardson number dependent formulation for the vertical momentum and 
     97tracer eddy coefficients is set through the \nam{zdf_ric}{zdf\_ric} namelist variables. 
     98The vertical mixing coefficients are diagnosed from the large scale variables computed by the model. 
    8599\textit{In situ} measurements have been used to link vertical turbulent activity to large scale ocean structures. 
    86100The hypothesis of a mixing mainly maintained by the growth of Kelvin-Helmholtz like instabilities leads to 
    87101a dependency between the vertical eddy coefficients and the local Richardson number 
    88 (\ie the ratio of stratification to vertical shear). 
    89 Following \citet{Pacanowski_Philander_JPO81}, the following formulation has been implemented: 
    90 \[ 
    91   % \label{eq:zdfric} 
     102(\ie\ the ratio of stratification to vertical shear). 
     103Following \citet{pacanowski.philander_JPO81}, the following formulation has been implemented: 
     104\[ 
     105  % \label{eq:ZDF_ric} 
    92106  \left\{ 
    93107    \begin{aligned} 
     
    98112\] 
    99113where $Ri = N^2 / \left(\partial_z \textbf{U}_h \right)^2$ is the local Richardson number, 
    100 $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}),  
     114$N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}), 
    101115$A_b^{vT} $ and $A_b^{vm}$ are the constant background values set as in the constant case 
    102116(see \autoref{subsec:ZDF_cst}), and $A_{ric}^{vT} = 10^{-4}~m^2.s^{-1}$ is the maximum value that 
    103117can be reached by the coefficient when $Ri\leq 0$, $a=5$ and $n=2$. 
    104 The last three values can be modified by setting the \np{rn\_avmri}, \np{rn\_alp} and 
    105 \np{nn\_ric} namelist parameters, respectively. 
     118The last three values can be modified by setting the \np{rn_avmri}{rn\_avmri}, \np{rn_alp}{rn\_alp} and 
     119\np{nn_ric}{nn\_ric} namelist parameters, respectively. 
    106120 
    107121A simple mixing-layer model to transfer and dissipate the atmospheric forcings 
    108 (wind-stress and buoyancy fluxes) can be activated setting the \np{ln\_mldw}\forcode{ = .true.} in the namelist. 
     122(wind-stress and buoyancy fluxes) can be activated setting the \np[=.true.]{ln_mldw}{ln\_mldw} in the namelist. 
    109123 
    110124In this case, the local depth of turbulent wind-mixing or "Ekman depth" $h_{e}(x,y,t)$ is evaluated and 
     
    122136\] 
    123137is computed from the wind stress vector $|\tau|$ and the reference density $ \rho_o$. 
    124 The final $h_{e}$ is further constrained by the adjustable bounds \np{rn\_mldmin} and \np{rn\_mldmax}. 
     138The final $h_{e}$ is further constrained by the adjustable bounds \np{rn_mldmin}{rn\_mldmin} and \np{rn_mldmax}{rn\_mldmax}. 
    125139Once $h_{e}$ is computed, the vertical eddy coefficients within $h_{e}$ are set to 
    126 the empirical values \np{rn\_wtmix} and \np{rn\_wvmix} \citep{Lermusiaux2001}. 
    127  
    128 % ------------------------------------------------------------------------------------------------------------- 
    129 %        TKE Turbulent Closure Scheme  
    130 % ------------------------------------------------------------------------------------------------------------- 
    131 \subsection{TKE turbulent closure scheme (\protect\key{zdftke})} 
     140the empirical values \np{rn_wtmix}{rn\_wtmix} and \np{rn_wvmix}{rn\_wvmix} \citep{lermusiaux_JMS01}. 
     141 
     142%% ================================================================================================= 
     143\subsection[TKE turbulent closure scheme (\forcode{ln_zdftke})]{TKE turbulent closure scheme (\protect\np{ln_zdftke}{ln\_zdftke})} 
    132144\label{subsec:ZDF_tke} 
    133145 
    134 %--------------------------------------------namzdf_tke-------------------------------------------------- 
    135  
    136 \nlst{namzdf_tke} 
    137 %-------------------------------------------------------------------------------------------------------------- 
     146\begin{listing} 
     147  \nlst{namzdf_tke} 
     148  \caption{\forcode{&namzdf_tke}} 
     149  \label{lst:namzdf_tke} 
     150\end{listing} 
    138151 
    139152The vertical eddy viscosity and diffusivity coefficients are computed from a TKE turbulent closure model based on 
    140153a prognostic equation for $\bar{e}$, the turbulent kinetic energy, 
    141154and a closure assumption for the turbulent length scales. 
    142 This turbulent closure model has been developed by \citet{Bougeault1989} in the atmospheric case, 
    143 adapted by \citet{Gaspar1990} for the oceanic case, and embedded in OPA, the ancestor of NEMO, 
    144 by \citet{Blanke1993} for equatorial Atlantic simulations. 
    145 Since then, significant modifications have been introduced by \citet{Madec1998} in both the implementation and 
     155This turbulent closure model has been developed by \citet{bougeault.lacarrere_MWR89} in the atmospheric case, 
     156adapted by \citet{gaspar.gregoris.ea_JGR90} for the oceanic case, and embedded in OPA, the ancestor of \NEMO, 
     157by \citet{blanke.delecluse_JPO93} for equatorial Atlantic simulations. 
     158Since then, significant modifications have been introduced by \citet{madec.delecluse.ea_NPM98} in both the implementation and 
    146159the formulation of the mixing length scale. 
    147160The time evolution of $\bar{e}$ is the result of the production of $\bar{e}$ through vertical shear, 
    148 its destruction through stratification, its vertical diffusion, and its dissipation of \citet{Kolmogorov1942} type: 
     161its destruction through stratification, its vertical diffusion, and its dissipation of \citet{kolmogorov_IANS42} type: 
    149162\begin{equation} 
    150   \label{eq:zdftke_e} 
     163  \label{eq:ZDF_tke_e} 
    151164  \frac{\partial \bar{e}}{\partial t} = 
    152165  \frac{K_m}{{e_3}^2 }\;\left[ {\left( {\frac{\partial u}{\partial k}} \right)^2 
     
    158171\end{equation} 
    159172\[ 
    160   % \label{eq:zdftke_kz} 
     173  % \label{eq:ZDF_tke_kz} 
    161174  \begin{split} 
    162175    K_m &= C_k\  l_k\  \sqrt {\bar{e}\; }    \\ 
     
    164177  \end{split} 
    165178\] 
    166 where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}),  
    167 $l_{\epsilon }$ and $l_{\kappa }$ are the dissipation and mixing length scales,  
     179where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}), 
     180$l_{\epsilon }$ and $l_{\kappa }$ are the dissipation and mixing length scales, 
    168181$P_{rt}$ is the Prandtl number, $K_m$ and $K_\rho$ are the vertical eddy viscosity and diffusivity coefficients. 
    169182The constants $C_k =  0.1$ and $C_\epsilon = \sqrt {2} /2$ $\approx 0.7$ are designed to deal with 
    170 vertical mixing at any depth \citep{Gaspar1990}.  
    171 They are set through namelist parameters \np{nn\_ediff} and \np{nn\_ediss}. 
    172 $P_{rt}$ can be set to unity or, following \citet{Blanke1993}, be a function of the local Richardson number, $R_i$: 
     183vertical mixing at any depth \citep{gaspar.gregoris.ea_JGR90}. 
     184They are set through namelist parameters \np{nn_ediff}{nn\_ediff} and \np{nn_ediss}{nn\_ediss}. 
     185$P_{rt}$ can be set to unity or, following \citet{blanke.delecluse_JPO93}, be a function of the local Richardson number, $R_i$: 
    173186\begin{align*} 
    174   % \label{eq:prt} 
     187  % \label{eq:ZDF_prt} 
    175188  P_{rt} = 
    176189  \begin{cases} 
     
    180193  \end{cases} 
    181194\end{align*} 
    182 Options are defined through the  \ngn{namzdfy\_tke} namelist variables. 
    183 The choice of $P_{rt}$ is controlled by the \np{nn\_pdl} namelist variable. 
     195The choice of $P_{rt}$ is controlled by the \np{nn_pdl}{nn\_pdl} namelist variable. 
    184196 
    185197At the sea surface, the value of $\bar{e}$ is prescribed from the wind stress field as 
    186 $\bar{e}_o = e_{bb} |\tau| / \rho_o$, with $e_{bb}$ the \np{rn\_ebb} namelist parameter. 
    187 The default value of $e_{bb}$ is 3.75. \citep{Gaspar1990}), however a much larger value can be used when 
     198$\bar{e}_o = e_{bb} |\tau| / \rho_o$, with $e_{bb}$ the \np{rn_ebb}{rn\_ebb} namelist parameter. 
     199The default value of $e_{bb}$ is 3.75. \citep{gaspar.gregoris.ea_JGR90}), however a much larger value can be used when 
    188200taking into account the surface wave breaking (see below Eq. \autoref{eq:ZDF_Esbc}). 
    189201The bottom value of TKE is assumed to be equal to the value of the level just above. 
    190202The time integration of the $\bar{e}$ equation may formally lead to negative values because 
    191203the numerical scheme does not ensure its positivity. 
    192 To overcome this problem, a cut-off in the minimum value of $\bar{e}$ is used (\np{rn\_emin} namelist parameter). 
    193 Following \citet{Gaspar1990}, the cut-off value is set to $\sqrt{2}/2~10^{-6}~m^2.s^{-2}$. 
    194 This allows the subsequent formulations to match that of \citet{Gargett1984} for the diffusion in 
     204To overcome this problem, a cut-off in the minimum value of $\bar{e}$ is used (\np{rn_emin}{rn\_emin} namelist parameter). 
     205Following \citet{gaspar.gregoris.ea_JGR90}, the cut-off value is set to $\sqrt{2}/2~10^{-6}~m^2.s^{-2}$. 
     206This allows the subsequent formulations to match that of \citet{gargett_JMR84} for the diffusion in 
    195207the thermocline and deep ocean :  $K_\rho = 10^{-3} / N$. 
    196208In addition, a cut-off is applied on $K_m$ and $K_\rho$ to avoid numerical instabilities associated with 
    197209too weak vertical diffusion. 
    198 They must be specified at least larger than the molecular values, and are set through \np{rn\_avm0} and 
    199 \np{rn\_avt0} (namzdf namelist, see \autoref{subsec:ZDF_cst}). 
    200  
     210They must be specified at least larger than the molecular values, and are set through \np{rn_avm0}{rn\_avm0} and 
     211\np{rn_avt0}{rn\_avt0} (\nam{zdf}{zdf} namelist, see \autoref{subsec:ZDF_cst}). 
     212 
     213%% ================================================================================================= 
    201214\subsubsection{Turbulent length scale} 
    202215 
    203216For computational efficiency, the original formulation of the turbulent length scales proposed by 
    204 \citet{Gaspar1990} has been simplified. 
    205 Four formulations are proposed, the choice of which is controlled by the \np{nn\_mxl} namelist parameter. 
    206 The first two are based on the following first order approximation \citep{Blanke1993}: 
     217\citet{gaspar.gregoris.ea_JGR90} has been simplified. 
     218Four formulations are proposed, the choice of which is controlled by the \np{nn_mxl}{nn\_mxl} namelist parameter. 
     219The first two are based on the following first order approximation \citep{blanke.delecluse_JPO93}: 
    207220\begin{equation} 
    208   \label{eq:tke_mxl0_1} 
     221  \label{eq:ZDF_tke_mxl0_1} 
    209222  l_k = l_\epsilon = \sqrt {2 \bar{e}\; } / N 
    210223\end{equation} 
    211224which is valid in a stable stratified region with constant values of the Brunt-Vais\"{a}l\"{a} frequency. 
    212225The resulting length scale is bounded by the distance to the surface or to the bottom 
    213 (\np{nn\_mxl}\forcode{ = 0}) or by the local vertical scale factor (\np{nn\_mxl}\forcode{ = 1}). 
    214 \citet{Blanke1993} notice that this simplification has two major drawbacks: 
     226(\np[=0]{nn_mxl}{nn\_mxl}) or by the local vertical scale factor (\np[=1]{nn_mxl}{nn\_mxl}). 
     227\citet{blanke.delecluse_JPO93} notice that this simplification has two major drawbacks: 
    215228it makes no sense for locally unstable stratification and the computation no longer uses all 
    216229the information contained in the vertical density profile. 
    217 To overcome these drawbacks, \citet{Madec1998} introduces the \np{nn\_mxl}\forcode{ = 2..3} cases, 
     230To overcome these drawbacks, \citet{madec.delecluse.ea_NPM98} introduces the \np[=2, 3]{nn_mxl}{nn\_mxl} cases, 
    218231which add an extra assumption concerning the vertical gradient of the computed length scale. 
    219 So, the length scales are first evaluated as in \autoref{eq:tke_mxl0_1} and then bounded such that: 
     232So, the length scales are first evaluated as in \autoref{eq:ZDF_tke_mxl0_1} and then bounded such that: 
    220233\begin{equation} 
    221   \label{eq:tke_mxl_constraint} 
     234  \label{eq:ZDF_tke_mxl_constraint} 
    222235  \frac{1}{e_3 }\left| {\frac{\partial l}{\partial k}} \right| \leq 1 
    223236  \qquad \text{with }\  l =  l_k = l_\epsilon 
    224237\end{equation} 
    225 \autoref{eq:tke_mxl_constraint} means that the vertical variations of the length scale cannot be larger than 
     238\autoref{eq:ZDF_tke_mxl_constraint} means that the vertical variations of the length scale cannot be larger than 
    226239the variations of depth. 
    227 It provides a better approximation of the \citet{Gaspar1990} formulation while being much less  
     240It provides a better approximation of the \citet{gaspar.gregoris.ea_JGR90} formulation while being much less 
    228241time consuming. 
    229242In particular, it allows the length scale to be limited not only by the distance to the surface or 
    230243to the ocean bottom but also by the distance to a strongly stratified portion of the water column such as 
    231 the thermocline (\autoref{fig:mixing_length}). 
    232 In order to impose the \autoref{eq:tke_mxl_constraint} constraint, we introduce two additional length scales: 
     244the thermocline (\autoref{fig:ZDF_mixing_length}). 
     245In order to impose the \autoref{eq:ZDF_tke_mxl_constraint} constraint, we introduce two additional length scales: 
    233246$l_{up}$ and $l_{dwn}$, the upward and downward length scales, and 
    234247evaluate the dissipation and mixing length scales as 
    235248(and note that here we use numerical indexing): 
    236 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    237249\begin{figure}[!t] 
    238   \begin{center} 
    239     \includegraphics[width=1.00\textwidth]{Fig_mixing_length} 
    240     \caption{ 
    241       \protect\label{fig:mixing_length} 
    242       Illustration of the mixing length computation. 
    243     } 
    244   \end{center} 
     250  \centering 
     251  \includegraphics[width=0.66\textwidth]{ZDF_mixing_length} 
     252  \caption[Mixing length computation]{Illustration of the mixing length computation} 
     253  \label{fig:ZDF_mixing_length} 
    245254\end{figure} 
    246 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    247 \[ 
    248   % \label{eq:tke_mxl2} 
     255\[ 
     256  % \label{eq:ZDF_tke_mxl2} 
    249257  \begin{aligned} 
    250258    l_{up\ \ }^{(k)} &= \min \left(  l^{(k)} \ , \ l_{up}^{(k+1)} + e_{3t}^{(k)}\ \ \ \;  \right) 
     
    254262  \end{aligned} 
    255263\] 
    256 where $l^{(k)}$ is computed using \autoref{eq:tke_mxl0_1}, \ie $l^{(k)} = \sqrt {2 {\bar e}^{(k)} / {N^2}^{(k)} }$. 
    257  
    258 In the \np{nn\_mxl}\forcode{ = 2} case, the dissipation and mixing length scales take the same value: 
    259 $ l_k=  l_\epsilon = \min \left(\ l_{up} \;,\;  l_{dwn}\ \right)$, while in the \np{nn\_mxl}\forcode{ = 3} case, 
    260 the dissipation and mixing turbulent length scales are give as in \citet{Gaspar1990}: 
    261 \[ 
    262   % \label{eq:tke_mxl_gaspar} 
     264where $l^{(k)}$ is computed using \autoref{eq:ZDF_tke_mxl0_1}, \ie\ $l^{(k)} = \sqrt {2 {\bar e}^{(k)} / {N^2}^{(k)} }$. 
     265 
     266In the \np[=2]{nn_mxl}{nn\_mxl} case, the dissipation and mixing length scales take the same value: 
     267$ l_k=  l_\epsilon = \min \left(\ l_{up} \;,\;  l_{dwn}\ \right)$, while in the \np[=3]{nn_mxl}{nn\_mxl} case, 
     268the dissipation and mixing turbulent length scales are give as in \citet{gaspar.gregoris.ea_JGR90}: 
     269\[ 
     270  % \label{eq:ZDF_tke_mxl_gaspar} 
    263271  \begin{aligned} 
    264272    & l_k          = \sqrt{\  l_{up} \ \ l_{dwn}\ }   \\ 
     
    267275\] 
    268276 
    269 At the ocean surface, a non zero length scale is set through the  \np{rn\_mxl0} namelist parameter. 
     277At the ocean surface, a non zero length scale is set through the  \np{rn_mxl0}{rn\_mxl0} namelist parameter. 
    270278Usually the surface scale is given by $l_o = \kappa \,z_o$ where $\kappa = 0.4$ is von Karman's constant and 
    271279$z_o$ the roughness parameter of the surface. 
    272 Assuming $z_o=0.1$~m \citep{Craig_Banner_JPO94} leads to a 0.04~m, the default value of \np{rn\_mxl0}. 
     280Assuming $z_o=0.1$~m \citep{craig.banner_JPO94} leads to a 0.04~m, the default value of \np{rn_mxl0}{rn\_mxl0}. 
    273281In the ocean interior a minimum length scale is set to recover the molecular viscosity when 
    274282$\bar{e}$ reach its minimum value ($1.10^{-6}= C_k\, l_{min} \,\sqrt{\bar{e}_{min}}$ ). 
    275283 
     284%% ================================================================================================= 
    276285\subsubsection{Surface wave breaking parameterization} 
    277 %-----------------------------------------------------------------------% 
    278  
    279 Following \citet{Mellor_Blumberg_JPO04}, the TKE turbulence closure model has been modified to 
     286 
     287Following \citet{mellor.blumberg_JPO04}, the TKE turbulence closure model has been modified to 
    280288include the effect of surface wave breaking energetics. 
    281289This results in a reduction of summertime surface temperature when the mixed layer is relatively shallow. 
    282 The \citet{Mellor_Blumberg_JPO04} modifications acts on surface length scale and TKE values and 
    283 air-sea drag coefficient.  
    284 The latter concerns the bulk formulea and is not discussed here.  
    285  
    286 Following \citet{Craig_Banner_JPO94}, the boundary condition on surface TKE value is : 
     290The \citet{mellor.blumberg_JPO04} modifications acts on surface length scale and TKE values and 
     291air-sea drag coefficient. 
     292The latter concerns the bulk formulae and is not discussed here. 
     293 
     294Following \citet{craig.banner_JPO94}, the boundary condition on surface TKE value is : 
    287295\begin{equation} 
    288296  \label{eq:ZDF_Esbc} 
    289297  \bar{e}_o = \frac{1}{2}\,\left(  15.8\,\alpha_{CB} \right)^{2/3} \,\frac{|\tau|}{\rho_o} 
    290298\end{equation} 
    291 where $\alpha_{CB}$ is the \citet{Craig_Banner_JPO94} constant of proportionality which depends on the ''wave age'', 
    292 ranging from 57 for mature waves to 146 for younger waves \citep{Mellor_Blumberg_JPO04}.  
     299where $\alpha_{CB}$ is the \citet{craig.banner_JPO94} constant of proportionality which depends on the ''wave age'', 
     300ranging from 57 for mature waves to 146 for younger waves \citep{mellor.blumberg_JPO04}. 
    293301The boundary condition on the turbulent length scale follows the Charnock's relation: 
    294302\begin{equation} 
     
    297305\end{equation} 
    298306where $\kappa=0.40$ is the von Karman constant, and $\beta$ is the Charnock's constant. 
    299 \citet{Mellor_Blumberg_JPO04} suggest $\beta = 2.10^{5}$ the value chosen by 
    300 \citet{Stacey_JPO99} citing observation evidence, and 
     307\citet{mellor.blumberg_JPO04} suggest $\beta = 2.10^{5}$ the value chosen by 
     308\citet{stacey_JPO99} citing observation evidence, and 
    301309$\alpha_{CB} = 100$ the Craig and Banner's value. 
    302310As the surface boundary condition on TKE is prescribed through $\bar{e}_o = e_{bb} |\tau| / \rho_o$, 
    303 with $e_{bb}$ the \np{rn\_ebb} namelist parameter, setting \np{rn\_ebb}\forcode{ = 67.83} corresponds  
     311with $e_{bb}$ the \np{rn_ebb}{rn\_ebb} namelist parameter, setting \np[=67.83]{rn_ebb}{rn\_ebb} corresponds 
    304312to $\alpha_{CB} = 100$. 
    305 Further setting  \np{ln\_mxl0} to true applies \autoref{eq:ZDF_Lsbc} as surface boundary condition on length scale, 
     313Further setting  \np[=.true.]{ln_mxl0}{ln\_mxl0},  applies \autoref{eq:ZDF_Lsbc} as the surface boundary condition on the length scale, 
    306314with $\beta$ hard coded to the Stacey's value. 
    307 Note that a minimal threshold of \np{rn\_emin0}$=10^{-4}~m^2.s^{-2}$ (namelist parameters) is applied on 
     315Note that a minimal threshold of \np{rn_emin0}{rn\_emin0}$=10^{-4}~m^2.s^{-2}$ (namelist parameters) is applied on the 
    308316surface $\bar{e}$ value. 
    309317 
     318%% ================================================================================================= 
    310319\subsubsection{Langmuir cells} 
    311 %--------------------------------------% 
    312320 
    313321Langmuir circulations (LC) can be described as ordered large-scale vertical motions in 
     
    315323Although LC have nothing to do with convection, the circulation pattern is rather similar to 
    316324so-called convective rolls in the atmospheric boundary layer. 
    317 The detailed physics behind LC is described in, for example, \citet{Craik_Leibovich_JFM76}. 
     325The detailed physics behind LC is described in, for example, \citet{craik.leibovich_JFM76}. 
    318326The prevailing explanation is that LC arise from a nonlinear interaction between the Stokes drift and 
    319 wind drift currents.  
     327wind drift currents. 
    320328 
    321329Here we introduced in the TKE turbulent closure the simple parameterization of Langmuir circulations proposed by 
    322 \citep{Axell_JGR02} for a $k-\epsilon$ turbulent closure. 
     330\citep{axell_JGR02} for a $k-\epsilon$ turbulent closure. 
    323331The parameterization, tuned against large-eddy simulation, includes the whole effect of LC in 
    324 an extra source terms of TKE, $P_{LC}$. 
    325 The presence of $P_{LC}$ in \autoref{eq:zdftke_e}, the TKE equation, is controlled by setting \np{ln\_lc} to 
    326 \forcode{.true.} in the namtke namelist. 
    327   
    328 By making an analogy with the characteristic convective velocity scale (\eg, \citet{D'Alessio_al_JPO98}), 
    329 $P_{LC}$ is assumed to be :  
     332an extra source term of TKE, $P_{LC}$. 
     333The presence of $P_{LC}$ in \autoref{eq:ZDF_tke_e}, the TKE equation, is controlled by setting \np{ln_lc}{ln\_lc} to 
     334\forcode{.true.} in the \nam{zdf_tke}{zdf\_tke} namelist. 
     335 
     336By making an analogy with the characteristic convective velocity scale (\eg, \citet{dalessio.abdella.ea_JPO98}), 
     337$P_{LC}$ is assumed to be : 
    330338\[ 
    331339P_{LC}(z) = \frac{w_{LC}^3(z)}{H_{LC}} 
    332340\] 
    333341where $w_{LC}(z)$ is the vertical velocity profile of LC, and $H_{LC}$ is the LC depth. 
    334 With no information about the wave field, $w_{LC}$ is assumed to be proportional to  
    335 the Stokes drift $u_s = 0.377\,\,|\tau|^{1/2}$, where $|\tau|$ is the surface wind stress module  
    336 \footnote{Following \citet{Li_Garrett_JMR93}, the surface Stoke drift velocity may be expressed as 
     342With no information about the wave field, $w_{LC}$ is assumed to be proportional to 
     343the Stokes drift $u_s = 0.377\,\,|\tau|^{1/2}$, where $|\tau|$ is the surface wind stress module 
     344\footnote{Following \citet{li.garrett_JMR93}, the surface Stoke drift velocity may be expressed as 
    337345  $u_s =  0.016 \,|U_{10m}|$. 
    338346  Assuming an air density of $\rho_a=1.22 \,Kg/m^3$ and a drag coefficient of 
     
    341349For the vertical variation, $w_{LC}$ is assumed to be zero at the surface as well as at 
    342350a finite depth $H_{LC}$ (which is often close to the mixed layer depth), 
    343 and simply varies as a sine function in between (a first-order profile for the Langmuir cell structures).  
     351and simply varies as a sine function in between (a first-order profile for the Langmuir cell structures). 
    344352The resulting expression for $w_{LC}$ is : 
    345353\[ 
     
    350358  \end{cases} 
    351359\] 
    352 where $c_{LC} = 0.15$ has been chosen by \citep{Axell_JGR02} as a good compromise to fit LES data. 
     360where $c_{LC} = 0.15$ has been chosen by \citep{axell_JGR02} as a good compromise to fit LES data. 
    353361The chosen value yields maximum vertical velocities $w_{LC}$ of the order of a few centimeters per second. 
    354 The value of $c_{LC}$ is set through the \np{rn\_lc} namelist parameter, 
    355 having in mind that it should stay between 0.15 and 0.54 \citep{Axell_JGR02}.  
     362The value of $c_{LC}$ is set through the \np{rn_lc}{rn\_lc} namelist parameter, 
     363having in mind that it should stay between 0.15 and 0.54 \citep{axell_JGR02}. 
    356364 
    357365The $H_{LC}$ is estimated in a similar way as the turbulent length scale of TKE equations: 
    358 $H_{LC}$ is depth to which a water parcel with kinetic energy due to Stoke drift can reach on its own by 
    359 converting its kinetic energy to potential energy, according to  
     366$H_{LC}$ is the depth to which a water parcel with kinetic energy due to Stoke drift can reach on its own by 
     367converting its kinetic energy to potential energy, according to 
    360368\[ 
    361369- \int_{-H_{LC}}^0 { N^2\;z  \;dz} = \frac{1}{2} u_s^2 
    362370\] 
    363371 
     372%% ================================================================================================= 
    364373\subsubsection{Mixing just below the mixed layer} 
    365 %--------------------------------------------------------------% 
    366374 
    367375Vertical mixing parameterizations commonly used in ocean general circulation models tend to 
    368376produce mixed-layer depths that are too shallow during summer months and windy conditions. 
    369377This bias is particularly acute over the Southern Ocean. 
    370 To overcome this systematic bias, an ad hoc parameterization is introduced into the TKE scheme \cite{Rodgers_2014}.  
    371 The parameterization is an empirical one, \ie not derived from theoretical considerations, 
    372 but rather is meant to account for observed processes that affect the density structure of  
    373 the ocean’s planetary boundary layer that are not explicitly captured by default in the TKE scheme  
    374 (\ie near-inertial oscillations and ocean swells and waves). 
    375  
    376 When using this parameterization (\ie when \np{nn\_etau}\forcode{ = 1}), 
     378To overcome this systematic bias, an ad hoc parameterization is introduced into the TKE scheme \cite{rodgers.aumont.ea_B14}. 
     379The parameterization is an empirical one, \ie\ not derived from theoretical considerations, 
     380but rather is meant to account for observed processes that affect the density structure of 
     381the ocean’s planetary boundary layer that are not explicitly captured by default in the TKE scheme 
     382(\ie\ near-inertial oscillations and ocean swells and waves). 
     383 
     384When using this parameterization (\ie\ when \np[=1]{nn_etau}{nn\_etau}), 
    377385the TKE input to the ocean ($S$) imposed by the winds in the form of near-inertial oscillations, 
    378386swell and waves is parameterized by \autoref{eq:ZDF_Esbc} the standard TKE surface boundary condition, 
     
    383391\end{equation} 
    384392where $z$ is the depth, $e_s$ is TKE surface boundary condition, $f_r$ is the fraction of the surface TKE that 
    385 penetrate in the ocean, $h_\tau$ is a vertical mixing length scale that controls exponential shape of 
     393penetrates in the ocean, $h_\tau$ is a vertical mixing length scale that controls exponential shape of 
    386394the penetration, and $f_i$ is the ice concentration 
    387 (no penetration if $f_i=1$, that is if the ocean is entirely covered by sea-ice). 
    388 The value of $f_r$, usually a few percents, is specified through \np{rn\_efr} namelist parameter. 
    389 The vertical mixing length scale, $h_\tau$, can be set as a 10~m uniform value (\np{nn\_etau}\forcode{ = 0}) or 
     395(no penetration if $f_i=1$, \ie\ if the ocean is entirely covered by sea-ice). 
     396The value of $f_r$, usually a few percents, is specified through \np{rn_efr}{rn\_efr} namelist parameter. 
     397The vertical mixing length scale, $h_\tau$, can be set as a 10~m uniform value (\np[=0]{nn_etau}{nn\_etau}) or 
    390398a latitude dependent value (varying from 0.5~m at the Equator to a maximum value of 30~m at high latitudes 
    391 (\np{nn\_etau}\forcode{ = 1}).  
    392  
    393 Note that two other option existe, \np{nn\_etau}\forcode{ = 2..3}. 
     399(\np[=1]{nn_etau}{nn\_etau}). 
     400 
     401Note that two other option exist, \np[=2, 3]{nn_etau}{nn\_etau}. 
    394402They correspond to applying \autoref{eq:ZDF_Ehtau} only at the base of the mixed layer, 
    395 or to using the high frequency part of the stress to evaluate the fraction of TKE that penetrate the ocean.  
     403or to using the high frequency part of the stress to evaluate the fraction of TKE that penetrates the ocean. 
    396404Those two options are obsolescent features introduced for test purposes. 
    397 They will be removed in the next release.  
    398  
    399 % from Burchard et al OM 2008 :  
    400 % the most critical process not reproduced by statistical turbulence models is the activity of  
    401 % internal waves and their interaction with turbulence. After the Reynolds decomposition,  
    402 % internal waves are in principle included in the RANS equations, but later partially  
    403 % excluded by the hydrostatic assumption and the model resolution.  
    404 % Thus far, the representation of internal wave mixing in ocean models has been relatively crude  
    405 % (\eg Mellor, 1989; Large et al., 1994; Meier, 2001; Axell, 2002; St. Laurent and Garrett, 2002). 
     405They will be removed in the next release. 
     406 
     407% This should be explain better below what this rn_eice parameter is meant for: 
     408In presence of Sea Ice, the value of this mixing can be modulated by the \np{rn_eice}{rn\_eice} namelist parameter. 
     409This parameter varies from \forcode{0} for no effect to \forcode{4} to suppress the TKE input into the ocean when Sea Ice concentration 
     410is greater than 25\%. 
     411 
     412% from Burchard et al OM 2008 : 
     413% the most critical process not reproduced by statistical turbulence models is the activity of 
     414% internal waves and their interaction with turbulence. After the Reynolds decomposition, 
     415% internal waves are in principle included in the RANS equations, but later partially 
     416% excluded by the hydrostatic assumption and the model resolution. 
     417% Thus far, the representation of internal wave mixing in ocean models has been relatively crude 
     418% (\eg\ Mellor, 1989; Large et al., 1994; Meier, 2001; Axell, 2002; St. Laurent and Garrett, 2002). 
     419 
     420%% ================================================================================================= 
     421\subsection[GLS: Generic Length Scale (\forcode{ln_zdfgls})]{GLS: Generic Length Scale (\protect\np{ln_zdfgls}{ln\_zdfgls})} 
     422\label{subsec:ZDF_gls} 
     423 
     424\begin{listing} 
     425  \nlst{namzdf_gls} 
     426  \caption{\forcode{&namzdf_gls}} 
     427  \label{lst:namzdf_gls} 
     428\end{listing} 
     429 
     430The Generic Length Scale (GLS) scheme is a turbulent closure scheme based on two prognostic equations: 
     431one for the turbulent kinetic energy $\bar {e}$, and another for the generic length scale, 
     432$\psi$ \citep{umlauf.burchard_JMR03, umlauf.burchard_CSR05}. 
     433This later variable is defined as: $\psi = {C_{0\mu}}^{p} \ {\bar{e}}^{m} \ l^{n}$, 
     434where the triplet $(p, m, n)$ value given in Tab.\autoref{tab:ZDF_GLS} allows to recover a number of 
     435well-known turbulent closures ($k$-$kl$ \citep{mellor.yamada_RG82}, $k$-$\epsilon$ \citep{rodi_JGR87}, 
     436$k$-$\omega$ \citep{wilcox_AJ88} among others \citep{umlauf.burchard_JMR03,kantha.carniel_JMR03}). 
     437The GLS scheme is given by the following set of equations: 
     438\begin{equation} 
     439  \label{eq:ZDF_gls_e} 
     440  \frac{\partial \bar{e}}{\partial t} = 
     441  \frac{K_m}{\sigma_e e_3 }\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 
     442      +\left( \frac{\partial v}{\partial k} \right)^2} \right] 
     443  -K_\rho \,N^2 
     444  +\frac{1}{e_3}\,\frac{\partial}{\partial k} \left[ \frac{K_m}{e_3}\,\frac{\partial \bar{e}}{\partial k} \right] 
     445  - \epsilon 
     446\end{equation} 
     447 
     448\[ 
     449  % \label{eq:ZDF_gls_psi} 
     450  \begin{split} 
     451    \frac{\partial \psi}{\partial t} =& \frac{\psi}{\bar{e}} \left\{ 
     452      \frac{C_1\,K_m}{\sigma_{\psi} {e_3}}\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 
     453          +\left( \frac{\partial v}{\partial k} \right)^2} \right] 
     454      - C_3 \,K_\rho\,N^2   - C_2 \,\epsilon \,Fw   \right\}             \\ 
     455    &+\frac{1}{e_3}  \;\frac{\partial }{\partial k}\left[ {\frac{K_m}{e_3 } 
     456        \;\frac{\partial \psi}{\partial k}} \right]\; 
     457  \end{split} 
     458\] 
     459 
     460\[ 
     461  % \label{eq:ZDF_gls_kz} 
     462  \begin{split} 
     463    K_m    &= C_{\mu} \ \sqrt {\bar{e}} \ l         \\ 
     464    K_\rho &= C_{\mu'}\ \sqrt {\bar{e}} \ l 
     465  \end{split} 
     466\] 
     467 
     468\[ 
     469  % \label{eq:ZDF_gls_eps} 
     470  {\epsilon} = C_{0\mu} \,\frac{\bar {e}^{3/2}}{l} \; 
     471\] 
     472where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}) and 
     473$\epsilon$ the dissipation rate. 
     474The constants $C_1$, $C_2$, $C_3$, ${\sigma_e}$, ${\sigma_{\psi}}$ and the wall function ($Fw$) depends of 
     475the choice of the turbulence model. 
     476Four different turbulent models are pre-defined (\autoref{tab:ZDF_GLS}). 
     477They are made available through the \np{nn_clo}{nn\_clo} namelist parameter. 
     478 
     479\begin{table}[htbp] 
     480  \centering 
     481  % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}c} 
     482  \begin{tabular}{ccccc} 
     483    &   $k-kl$   & $k-\epsilon$ & $k-\omega$ &   generic   \\ 
     484    % & \citep{mellor.yamada_RG82} &  \citep{rodi_JGR87}       & \citep{wilcox_AJ88} &                 \\ 
     485    \hline 
     486    \hline 
     487    \np{nn_clo}{nn\_clo}     & \textbf{0} &   \textbf{1}  &   \textbf{2}   &    \textbf{3}   \\ 
     488    \hline 
     489    $( p , n , m )$         &   ( 0 , 1 , 1 )   & ( 3 , 1.5 , -1 )   & ( -1 , 0.5 , -1 )    &  ( 2 , 1 , -0.67 )  \\ 
     490    $\sigma_k$      &    2.44         &     1.              &      2.                &      0.8          \\ 
     491    $\sigma_\psi$  &    2.44         &     1.3            &      2.                 &       1.07       \\ 
     492    $C_1$              &      0.9         &     1.44          &      0.555          &       1.           \\ 
     493    $C_2$              &      0.5         &     1.92          &      0.833          &       1.22       \\ 
     494    $C_3$              &      1.           &     1.              &      1.                &       1.           \\ 
     495    $F_{wall}$        &      Yes        &       --             &     --                  &      --          \\ 
     496    \hline 
     497    \hline 
     498  \end{tabular} 
     499  \caption[Set of predefined GLS parameters or equivalently predefined turbulence models available]{ 
     500    Set of predefined GLS parameters, or equivalently predefined turbulence models available with 
     501    \protect\np[=.true.]{ln_zdfgls}{ln\_zdfgls} and controlled by 
     502    the \protect\np{nn_clos}{nn\_clos} namelist variable in \protect\nam{zdf_gls}{zdf\_gls}.} 
     503  \label{tab:ZDF_GLS} 
     504\end{table} 
     505 
     506In the Mellor-Yamada model, the negativity of $n$ allows to use a wall function to force the convergence of 
     507the mixing length towards $\kappa z_b$ ($\kappa$ is the Von Karman constant and $z_b$ the rugosity length scale) value near physical boundaries 
     508(logarithmic boundary layer law). 
     509$C_{\mu}$ and $C_{\mu'}$ are calculated from stability function proposed by \citet{galperin.kantha.ea_JAS88}, 
     510or by \citet{kantha.clayson_JGR94} or one of the two functions suggested by \citet{canuto.howard.ea_JPO01} 
     511(\np[=0, 3]{nn_stab_func}{nn\_stab\_func}, resp.). 
     512The value of $C_{0\mu}$ depends on the choice of the stability function. 
     513 
     514The surface and bottom boundary condition on both $\bar{e}$ and $\psi$ can be calculated thanks to Dirichlet or 
     515Neumann condition through \np{nn_bc_surf}{nn\_bc\_surf} and \np{nn_bc_bot}{nn\_bc\_bot}, resp. 
     516As for TKE closure, the wave effect on the mixing is considered when 
     517\np[ > 0.]{rn_crban}{rn\_crban} \citep{craig.banner_JPO94, mellor.blumberg_JPO04}. 
     518The \np{rn_crban}{rn\_crban} namelist parameter is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and 
     519\np{rn_charn}{rn\_charn} provides the value of $\beta$ in \autoref{eq:ZDF_Lsbc}. 
     520 
     521The $\psi$ equation is known to fail in stably stratified flows, and for this reason 
     522almost all authors apply a clipping of the length scale as an \textit{ad hoc} remedy. 
     523With this clipping, the maximum permissible length scale is determined by $l_{max} = c_{lim} \sqrt{2\bar{e}}/ N$. 
     524A value of $c_{lim} = 0.53$ is often used \citep{galperin.kantha.ea_JAS88}. 
     525\cite{umlauf.burchard_CSR05} show that the value of the clipping factor is of crucial importance for 
     526the entrainment depth predicted in stably stratified situations, 
     527and that its value has to be chosen in accordance with the algebraic model for the turbulent fluxes. 
     528The clipping is only activated if \np[=.true.]{ln_length_lim}{ln\_length\_lim}, 
     529and the $c_{lim}$ is set to the \np{rn_clim_galp}{rn\_clim\_galp} value. 
     530 
     531The time and space discretization of the GLS equations follows the same energetic consideration as for 
     532the TKE case described in \autoref{subsec:ZDF_tke_ene} \citep{burchard_OM02}. 
     533Evaluation of the 4 GLS turbulent closure schemes can be found in \citet{warner.sherwood.ea_OM05} in ROMS model and 
     534 in \citet{reffray.guillaume.ea_GMD15} for the \NEMO\ model. 
    406535 
    407536% ------------------------------------------------------------------------------------------------------------- 
    408 %        TKE discretization considerations 
     537%        OSM OSMOSIS BL Scheme 
    409538% ------------------------------------------------------------------------------------------------------------- 
    410 \subsection{TKE discretization considerations (\protect\key{zdftke})} 
    411 \label{subsec:ZDF_tke_ene} 
    412  
    413 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     539\subsection[OSM: OSMOSIS boundary layer scheme (\forcode{ln_zdfosm = .true.})] 
     540{OSM: OSMOSIS boundary layer scheme (\protect\np{ln_zdfosm}{ln\_zdfosm})} 
     541\label{subsec:ZDF_osm} 
     542 
     543\begin{listing} 
     544  \nlst{namzdf_osm} 
     545  \caption{\forcode{&namzdf_osm}} 
     546  \label{lst:namzdf_osm} 
     547\end{listing} 
     548 
     549%-------------------------------------------------------------------------------------------------------------- 
     550\paragraph{Namelist choices} 
     551Most of the namelist options refer to how to specify the Stokes 
     552surface drift and penetration depth. There are three options: 
     553\begin{description} 
     554  \item \protect\np[=0]{nn_osm_wave}{nn\_osm\_wave} Default value in \texttt{namelist\_ref}. In this case the Stokes drift is 
     555      assumed to be parallel to the surface wind stress, with 
     556      magnitude consistent with a constant turbulent Langmuir number 
     557    $\mathrm{La}_t=$ \protect\np{rn_m_la} {rn\_m\_la} i.e.\ 
     558    $u_{s0}=\tau/(\mathrm{La}_t^2\rho_0)$.  Default value of 
     559    \protect\np{rn_m_la}{rn\_m\_la} is 0.3. The Stokes penetration 
     560      depth $\delta = $ \protect\np{rn_osm_dstokes}{rn\_osm\_dstokes}; this has default value 
     561      of 5~m. 
     562 
     563  \item \protect\np[=1]{nn_osm_wave}{nn\_osm\_wave} In this case the Stokes drift is 
     564      assumed to be parallel to the surface wind stress, with 
     565      magnitude as in the classical Pierson-Moskowitz wind-sea 
     566      spectrum.  Significant wave height and 
     567      wave-mean period taken from this spectrum are used to calculate the Stokes penetration 
     568      depth, following the approach set out in  \citet{breivik.janssen.ea_JPO14}. 
     569 
     570    \item \protect\np[=2]{nn_osm_wave}{nn\_osm\_wave} In this case the Stokes drift is 
     571      taken from  ECMWF wave model output, though only the component parallel 
     572      to the wind stress is retained. Significant wave height and 
     573      wave-mean period from ECMWF wave model output are used to calculate the Stokes penetration 
     574      depth, again following \citet{breivik.janssen.ea_JPO14}. 
     575 
     576    \end{description} 
     577 
     578    Others refer to the treatment of diffusion and viscosity beneath 
     579    the surface boundary layer: 
     580\begin{description} 
     581   \item \protect\np{ln_kpprimix} {ln\_kpprimix}  Default is \np{.true.}. Switches on KPP-style Ri \#-dependent 
     582     mixing below the surface boundary layer. If this is set 
     583     \texttt{.true.}  the following variable settings are honoured: 
     584    \item \protect\np{rn_riinfty}{rn\_riinfty} Critical value of local Ri \# below which 
     585      shear instability increases vertical mixing from background value. 
     586    \item \protect\np{rn_difri} {rn\_difri} Maximum value of Ri \#-dependent mixing at $\mathrm{Ri}=0$. 
     587    \item \protect\np{ln_convmix}{ln\_convmix} If \texttt{.true.} then, where water column is unstable, specify 
     588       diffusivity equal to \protect\np{rn_dif_conv}{rn\_dif\_conv} (default value is 1 m~s$^{-2}$). 
     589 \end{description} 
     590 Diagnostic output is controlled by: 
     591  \begin{description} 
     592    \item \protect\np{ln_dia_osm}{ln\_dia\_osm} Default is \np{.false.}; allows XIOS output of OSMOSIS internal fields. 
     593  \end{description} 
     594Obsolete namelist parameters include: 
     595\begin{description} 
     596   \item \protect\np{ln_use_osm_la}\np{ln\_use\_osm\_la} With \protect\np[=0]{nn_osm_wave}{nn\_osm\_wave}, 
     597      \protect\np{rn_osm_dstokes} {rn\_osm\_dstokes} is always used to specify the Stokes 
     598      penetration depth. 
     599   \item \protect\np{nn_ave} {nn\_ave} Choice of averaging method for KPP-style Ri \# 
     600      mixing. Not taken account of. 
     601   \item \protect\np{rn_osm_hbl0} {rn\_osm\_hbl0} Depth of initial boundary layer is now set 
     602     by a density criterion similar to that used in calculating \emph{hmlp} (output as \texttt{mldr10\_1}) in \mdl{zdfmxl}. 
     603\end{description} 
     604 
     605\subsubsection{Summary} 
     606Much of the time the turbulent motions in the ocean surface boundary 
     607layer (OSBL) are not given by 
     608classical shear turbulence. Instead they are in a regime known as 
     609`Langmuir turbulence',  dominated by an 
     610interaction between the currents and the Stokes drift of the surface waves \citep[e.g.][]{mcwilliams.ea_JFM97}. 
     611This regime is characterised by strong vertical turbulent motion, and appears when the surface Stokes drift $u_{s0}$ is much greater than the friction velocity $u_{\ast}$. More specifically Langmuir turbulence is thought to be crucial where the turbulent Langmuir number $\mathrm{La}_{t}=(u_{\ast}/u_{s0}) > 0.4$. 
     612 
     613The OSMOSIS model is fundamentally based on results of Large Eddy 
     614Simulations (LES) of Langmuir turbulence and aims to fully describe 
     615this Langmuir regime. The description in this section is of necessity incomplete and further details are available in Grant. A (2019); in prep. 
     616 
     617The OSMOSIS turbulent closure scheme is a similarity-scale scheme in 
     618the same spirit as the K-profile 
     619parameterization (KPP) scheme of \citet{large.ea_RG97}. 
     620A specified shape of diffusivity, scaled by the (OSBL) depth 
     621$h_{\mathrm{BL}}$ and a turbulent velocity scale, is imposed throughout the 
     622boundary layer 
     623$-h_{\mathrm{BL}}<z<\eta$. The turbulent closure model 
     624also includes fluxes of tracers and momentum that are``non-local'' (independent of the local property gradient). 
     625 
     626Rather than the OSBL 
     627depth being diagnosed in terms of a bulk Richardson number criterion, 
     628as in KPP, it is set by a prognostic equation that is informed by 
     629energy budget considerations reminiscent of the classical mixed layer 
     630models of \citet{kraus.turner_tellus67}. 
     631The model also includes an explicit parametrization of the structure 
     632of the pycnocline (the stratified region at the bottom of the OSBL). 
     633 
     634Presently, mixing below the OSBL is handled by the Richardson 
     635number-dependent mixing scheme used in \citet{large.ea_RG97}. 
     636 
     637Convective parameterizations such as described in \ref{sec:ZDF_conv} 
     638below should not be used with the OSMOSIS-OBL model: instabilities 
     639within the OSBL are part of the model, while instabilities below the 
     640ML are handled by the Ri \# dependent scheme. 
     641 
     642\subsubsection{Depth and velocity scales} 
     643The model supposes a boundary layer of thickness $h_{\mathrm{bl}}$ enclosing a well-mixed layer of thickness $h_{\mathrm{ml}}$ and a relatively thin pycnocline at the base of thickness $\Delta h$; Fig.~\ref{fig: OSBL_structure} shows typical (a) buoyancy structure and (b) turbulent buoyancy flux profile for the unstable boundary layer (losing buoyancy at the surface; e.g.\ cooling). 
    414644\begin{figure}[!t] 
    415645  \begin{center} 
    416     \includegraphics[width=1.00\textwidth]{Fig_ZDF_TKE_time_scheme} 
     646    %\includegraphics[width=0.7\textwidth]{ZDF_OSM_structure_of_OSBL} 
    417647    \caption{ 
    418       \protect\label{fig:TKE_time_scheme} 
    419       Illustration of the TKE time integration and its links to the momentum and tracer time integration. 
     648      \protect\label{fig: OSBL_structure} 
     649     The structure of the entraining  boundary layer. (a) Mean buoyancy profile. (b) Profile of the buoyancy flux. 
    420650    } 
    421   \end{center}   
     651  \end{center} 
    422652\end{figure} 
    423 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     653The pycnocline in the OSMOSIS scheme is assumed to have a finite thickness, and may include a number of model levels. This means that the OSMOSIS scheme must parametrize both the thickness of the pycnocline, and the turbulent fluxes within the pycnocline. 
     654 
     655Consideration of the power input by wind acting on the Stokes drift suggests that the Langmuir turbulence has velocity scale: 
     656\begin{equation}\label{eq:w_La} 
     657w_{*L}= \left(u_*^2 u_{s\,0}\right)^{1/3}; 
     658\end{equation} 
     659but at times the Stokes drift may be weak due to e.g.\ ice cover, short fetch, misalignment with the surface stress, etc.\ so  a composite velocity scale is assumed for the stable (warming) boundary layer: 
     660\begin{equation}\label{eq:composite-nu} 
     661  \nu_{\ast}= \left\{ u_*^3 \left[1-\exp(-.5 \mathrm{La}_t^2)\right]+w_{*L}^3\right\}^{1/3}. 
     662\end{equation} 
     663For the unstable boundary layer this is merged with the standard convective velocity scale $w_{*C}=\left(\overline{w^\prime b^\prime}_0 \,h_\mathrm{ml}\right)^{1/3}$, where $\overline{w^\prime b^\prime}_0$ is the upwards surface buoyancy flux, to give: 
     664\begin{equation}\label{eq:vel-scale-unstable} 
     665\omega_* = \left(\nu_*^3 + 0.5 w_{*C}^3\right)^{1/3}. 
     666\end{equation} 
     667 
     668\subsubsection{The flux gradient model} 
     669The flux-gradient relationships used in the OSMOSIS scheme take the form: 
     670% 
     671\begin{equation}\label{eq:flux-grad-gen} 
     672\overline{w^\prime\chi^\prime}=-K\frac{\partial\overline{\chi}}{\partial z} + N_{\chi,s} +N_{\chi,b} +N_{\chi,t}, 
     673\end{equation} 
     674% 
     675where $\chi$ is a general variable and $N_{\chi,s}, N_{\chi,b} \mathrm{and} N_{\chi,t}$  are the non-gradient terms, and represent the effects of the different terms in the turbulent flux-budget on the transport of $\chi$. $N_{\chi,s}$ represents the effects that the Stokes shear has on the transport of $\chi$, $N_{\chi,b}$  the effect of buoyancy, and $N_{\chi,t}$ the effect of the turbulent transport.  The same general form for the flux-gradient relationship is used to parametrize the transports of momentum, heat and salinity. 
     676 
     677In terms of the non-dimensionalized depth variables 
     678% 
     679\begin{equation}\label{eq:sigma} 
     680\sigma_{\mathrm{ml}}= -z/h_{\mathrm{ml}}; \;\sigma_{\mathrm{bl}}= -z/h_{\mathrm{bl}}, 
     681\end{equation} 
     682% 
     683in unstable conditions the eddy diffusivity ($K_d$) and eddy viscosity ($K_\nu$) profiles are parametrized as: 
     684% 
     685\begin{align}\label{eq:diff-unstable} 
     686K_d=&0.8\, \omega_*\, h_{\mathrm{ml}} \, \sigma_{\mathrm{ml}} \left(1-\beta_d \sigma_{\mathrm{ml}}\right)^{3/2} 
     687\\\label{eq:visc-unstable} 
     688K_\nu =& 0.3\, \omega_* \,h_{\mathrm{ml}}\, \sigma_{\mathrm{ml}} \left(1-\beta_\nu \sigma_{\mathrm{ml}}\right)\left(1-\tfrac{1}{2}\sigma_{\mathrm{ml}}^2\right) 
     689\end{align} 
     690% 
     691where $\beta_d$ and $\beta_\nu$ are parameters that are determined by matching Eqs \ref{eq:diff-unstable} and \ref{eq:visc-unstable} to the eddy diffusivity and viscosity at the base of the well-mixed layer, given by 
     692% 
     693\begin{equation}\label{eq:diff-wml-base} 
     694K_{d,\mathrm{ml}}=K_{\nu,\mathrm{ml}}=\,0.16\,\omega_* \Delta h. 
     695\end{equation} 
     696% 
     697For stable conditions the eddy diffusivity/viscosity profiles are given by: 
     698% 
     699\begin{align}\label{diff-stable} 
     700K_d= & 0.75\,\, \nu_*\, h_{\mathrm{ml}}\,\,  \exp\left[-2.8 \left(h_{\mathrm{bl}}/L_L\right)^2\right]\sigma_{\mathrm{ml}} \left(1-\sigma_{\mathrm{ml}}\right)^{3/2} \\\label{eq:visc-stable} 
     701K_\nu = & 0.375\,\,  \nu_*\, h_{\mathrm{ml}} \,\, \exp\left[-2.8 \left(h_{\mathrm{bl}}/L_L\right)^2\right] \sigma_{\mathrm{ml}} \left(1-\sigma_{\mathrm{ml}}\right)\left(1-\tfrac{1}{2}\sigma_{\mathrm{ml}}^2\right). 
     702\end{align} 
     703% 
     704The shape of the eddy viscosity and diffusivity profiles is the same as the shape in the unstable OSBL. The eddy diffusivity/viscosity depends on the stability parameter $h_{\mathrm{bl}}/{L_L}$ where $ L_L$ is analogous to the Obukhov length, but for Langmuir turbulence: 
     705\begin{equation}\label{eq:L_L} 
     706  L_L=-w_{*L}^3/\left<\overline{w^\prime b^\prime}\right>_L, 
     707\end{equation} 
     708with the mean turbulent buoyancy flux averaged over the boundary layer given in terms of its surface value $\overline{w^\prime b^\prime}_0$ and (downwards) )solar irradiance $I(z)$ by 
     709\begin{equation} \label{eq:stable-av-buoy-flux} 
     710\left<\overline{w^\prime b^\prime}\right>_L = \tfrac{1}{2} {\overline{w^\prime b^\prime}}_0-g\alpha_E\left[\tfrac{1}{2}(I(0)+I(-h))-\left<I\right>\right]. 
     711\end{equation} 
     712% 
     713In unstable conditions the eddy diffusivity and viscosity depend on stability through the velocity scale $\omega_*$, which depends on the two velocity scales $\nu_*$ and $w_{*C}$. 
     714 
     715Details of the non-gradient terms in \eqref{eq:flux-grad-gen} and of the fluxes within the pycnocline $-h_{\mathrm{bl}}<z<h_{\mathrm{ml}}$ can be found in Grant (2019). 
     716 
     717\subsubsection{Evolution of the boundary layer depth} 
     718 
     719The prognostic equation for the depth of the neutral/unstable boundary layer is given by \citep{grant+etal18}, 
     720 
     721\begin{equation} \label{eq:dhdt-unstable} 
     722%\frac{\partial h_\mathrm{bl}}{\partial t} + \mathbf{U}_b\cdot\nabla h_\mathrm{bl}= W_b - \frac{{\overline{w^\prime b^\prime}}_\mathrm{ent}}{\Delta B_\mathrm{bl}} 
     723\frac{\partial h_\mathrm{bl}}{\partial t} = W_b - \frac{{\overline{w^\prime b^\prime}}_\mathrm{ent}}{\Delta B_\mathrm{bl}} 
     724\end{equation} 
     725where $h_\mathrm{bl}$ is the horizontally-varying depth of the OSBL, 
     726$\mathbf{U}_b$ and $W_b$ are the mean horizontal and vertical 
     727velocities at the base of the OSBL, ${\overline{w^\prime 
     728    b^\prime}}_\mathrm{ent}$ is the buoyancy flux due to entrainment 
     729and $\Delta B_\mathrm{bl}$ is the difference between the buoyancy 
     730averaged over the depth of the OSBL (i.e.\ including the ML and 
     731pycnocline) and the buoyancy just below the base of the OSBL. This 
     732equation for the case when the pycnocline has a finite thickness, 
     733based on the potential energy budget of the OSBL, is the leading term 
     734\citep{grant+etal18} of a generalization of that used in mixed-layer 
     735models e.g.\ \citet{kraus.turner_tellus67}, in which the thickness of the pycnocline is taken to be zero. 
     736 
     737The entrainment flux for the combination of convective and Langmuir turbulence is given by 
     738\begin{equation} \label{eq:entrain-flux} 
     739  {\overline{w^\prime b^\prime}}_\mathrm{ent} = -\alpha_{\mathrm{B}} {\overline{w^\prime b^\prime}}_0 - \alpha_{\mathrm{S}} \frac{u_*^3}{h_{\mathrm{ml}}} 
     740  + G\left(\delta/h_{\mathrm{ml}} \right)\left[\alpha_{\mathrm{S}}e^{-1.5\, \mathrm{La}_t}-\alpha_{\mathrm{L}} \frac{w_{\mathrm{*L}}^3}{h_{\mathrm{ml}}}\right] 
     741\end{equation} 
     742where the factor $G\equiv 1 - \mathrm{e}^ {-25\delta/h_{\mathrm{bl}}}(1-4\delta/h_{\mathrm{bl}})$ models the lesser efficiency of Langmuir mixing when the boundary-layer depth is much greater than the Stokes depth, and $\alpha_{\mathrm{B}}$, $\alpha_{S}$  and $\alpha_{\mathrm{L}}$ depend on the ratio of the appropriate eddy turnover time to the inertial timescale $f^{-1}$. Results from the LES suggest $\alpha_{\mathrm{B}}=0.18 F(fh_{\mathrm{bl}}/w_{*C})$, $\alpha_{S}=0.15 F(fh_{\mathrm{bl}}/u_*$  and $\alpha_{\mathrm{L}}=0.035 F(fh_{\mathrm{bl}}/u_{*L})$, where $F(x)\equiv\tanh(x^{-1})^{0.69}$. 
     743 
     744For the stable boundary layer, the equation for the depth of the OSBL is: 
     745 
     746\begin{equation}\label{eq:dhdt-stable} 
     747\max\left(\Delta B_{bl},\frac{w_{*L}^2}{h_\mathrm{bl}}\right)\frac{\partial h_\mathrm{bl}}{\partial t} = \left(0.06 + 0.52\,\frac{ h_\mathrm{bl}}{L_L}\right) \frac{w_{*L}^3}{h_\mathrm{bl}} +\left<\overline{w^\prime b^\prime}\right>_L. 
     748\end{equation} 
     749 
     750Equation. \ref{eq:dhdt-unstable} always leads to the depth of the entraining OSBL increasing (ignoring the effect of the mean vertical motion), but the change in the thickness of the stable OSBL given by Eq. \ref{eq:dhdt-stable} can be positive or negative, depending on the magnitudes of $\left<\overline{w^\prime b^\prime}\right>_L$ and $h_\mathrm{bl}/L_L$. The rate at which the depth of the OSBL can decrease is limited by choosing an effective buoyancy $w_{*L}^2/h_\mathrm{bl}$, in place of $\Delta B_{bl}$ which will be $\approx 0$ for the collapsing OSBL. 
     751 
     752 
     753%% ================================================================================================= 
     754\subsection[ Discrete energy conservation for TKE and GLS schemes]{Discrete energy conservation for TKE and GLS schemes} 
     755\label{subsec:ZDF_tke_ene} 
     756 
     757\begin{figure}[!t] 
     758  \centering 
     759  \includegraphics[width=0.66\textwidth]{ZDF_TKE_time_scheme} 
     760  \caption[Subgrid kinetic energy integration in GLS and TKE schemes]{ 
     761    Illustration of the subgrid kinetic energy integration in GLS and TKE schemes and 
     762    its links to the momentum and tracer time integration.} 
     763  \label{fig:ZDF_TKE_time_scheme} 
     764\end{figure} 
    424765 
    425766The production of turbulence by vertical shear (the first term of the right hand side of 
    426 \autoref{eq:zdftke_e}) should balance the loss of kinetic energy associated with the vertical momentum diffusion 
    427 (first line in \autoref{eq:PE_zdf}). 
    428 To do so a special care have to be taken for both the time and space discretization of 
    429 the TKE equation \citep{Burchard_OM02,Marsaleix_al_OM08}. 
    430  
    431 Let us first address the time stepping issue. \autoref{fig:TKE_time_scheme} shows how 
     767\autoref{eq:ZDF_tke_e}) and  \autoref{eq:ZDF_gls_e}) should balance the loss of kinetic energy associated with the vertical momentum diffusion 
     768(first line in \autoref{eq:MB_zdf}). 
     769To do so a special care has to be taken for both the time and space discretization of 
     770the kinetic energy equation \citep{burchard_OM02,marsaleix.auclair.ea_OM08}. 
     771 
     772Let us first address the time stepping issue. \autoref{fig:ZDF_TKE_time_scheme} shows how 
    432773the two-level Leap-Frog time stepping of the momentum and tracer equations interplays with 
    433 the one-level forward time stepping of TKE equation. 
     774the one-level forward time stepping of the equation for $\bar{e}$. 
    434775With this framework, the total loss of kinetic energy (in 1D for the demonstration) due to 
    435776the vertical momentum diffusion is obtained by multiplying this quantity by $u^t$ and 
    436 summing the result vertically:    
     777summing the result vertically: 
    437778\begin{equation} 
    438   \label{eq:energ1} 
     779  \label{eq:ZDF_energ1} 
    439780  \begin{split} 
    440781    \int_{-H}^{\eta}  u^t \,\partial_z &\left( {K_m}^t \,(\partial_z u)^{t+\rdt}  \right) \,dz   \\ 
     
    444785\end{equation} 
    445786Here, the vertical diffusion of momentum is discretized backward in time with a coefficient, $K_m$, 
    446 known at time $t$ (\autoref{fig:TKE_time_scheme}), as it is required when using the TKE scheme 
    447 (see \autoref{sec:STP_forward_imp}). 
    448 The first term of the right hand side of \autoref{eq:energ1} represents the kinetic energy transfer at 
     787known at time $t$ (\autoref{fig:ZDF_TKE_time_scheme}), as it is required when using the TKE scheme 
     788(see \autoref{sec:TD_forward_imp}). 
     789The first term of the right hand side of \autoref{eq:ZDF_energ1} represents the kinetic energy transfer at 
    449790the surface (atmospheric forcing) and at the bottom (friction effect). 
    450791The second term is always negative. 
    451792It is the dissipation rate of kinetic energy, and thus minus the shear production rate of $\bar{e}$. 
    452 \autoref{eq:energ1} implies that, to be energetically consistent, 
     793\autoref{eq:ZDF_energ1} implies that, to be energetically consistent, 
    453794the production rate of $\bar{e}$ used to compute $(\bar{e})^t$ (and thus ${K_m}^t$) should be expressed as 
    454795${K_m}^{t-\rdt}\,(\partial_z u)^{t-\rdt} \,(\partial_z u)^t$ 
     
    456797 
    457798A similar consideration applies on the destruction rate of $\bar{e}$ due to stratification 
    458 (second term of the right hand side of \autoref{eq:zdftke_e}). 
     799(second term of the right hand side of \autoref{eq:ZDF_tke_e} and \autoref{eq:ZDF_gls_e}). 
    459800This term must balance the input of potential energy resulting from vertical mixing. 
    460 The rate of change of potential energy (in 1D for the demonstration) due vertical mixing is obtained by 
    461 multiplying vertical density diffusion tendency by $g\,z$ and and summing the result vertically: 
     801The rate of change of potential energy (in 1D for the demonstration) due to vertical mixing is obtained by 
     802multiplying the vertical density diffusion tendency by $g\,z$ and and summing the result vertically: 
    462803\begin{equation} 
    463   \label{eq:energ2} 
     804  \label{eq:ZDF_energ2} 
    464805  \begin{split} 
    465806    \int_{-H}^{\eta} g\,z\,\partial_z &\left( {K_\rho}^t \,(\partial_k \rho)^{t+\rdt}   \right) \,dz    \\ 
     
    470811  \end{split} 
    471812\end{equation} 
    472 where we use $N^2 = -g \,\partial_k \rho / (e_3 \rho)$.  
    473 The first term of the right hand side of \autoref{eq:energ2} is always zero because 
     813where we use $N^2 = -g \,\partial_k \rho / (e_3 \rho)$. 
     814The first term of the right hand side of \autoref{eq:ZDF_energ2} is always zero because 
    474815there is no diffusive flux through the ocean surface and bottom). 
    475816The second term is minus the destruction rate of  $\bar{e}$ due to stratification. 
    476 Therefore \autoref{eq:energ1} implies that, to be energetically consistent, 
    477 the product ${K_\rho}^{t-\rdt}\,(N^2)^t$ should be used in \autoref{eq:zdftke_e}, the TKE equation. 
     817Therefore \autoref{eq:ZDF_energ1} implies that, to be energetically consistent, 
     818the product ${K_\rho}^{t-\rdt}\,(N^2)^t$ should be used in \autoref{eq:ZDF_tke_e} and  \autoref{eq:ZDF_gls_e}. 
    478819 
    479820Let us now address the space discretization issue. 
    480821The vertical eddy coefficients are defined at $w$-point whereas the horizontal velocity components are in 
    481 the centre of the side faces of a $t$-box in staggered C-grid (\autoref{fig:cell}). 
     822the centre of the side faces of a $t$-box in staggered C-grid (\autoref{fig:DOM_cell}). 
    482823A space averaging is thus required to obtain the shear TKE production term. 
    483 By redoing the \autoref{eq:energ1} in the 3D case, it can be shown that the product of eddy coefficient by 
     824By redoing the \autoref{eq:ZDF_energ1} in the 3D case, it can be shown that the product of eddy coefficient by 
    484825the shear at $t$ and $t-\rdt$ must be performed prior to the averaging. 
    485 Furthermore, the possible time variation of $e_3$ (\key{vvl} case) have to be taken into account. 
     826Furthermore, the time variation of $e_3$ has be taken into account. 
    486827 
    487828The above energetic considerations leads to the following final discrete form for the TKE equation: 
    488829\begin{equation} 
    489   \label{eq:zdftke_ene} 
     830  \label{eq:ZDF_tke_ene} 
    490831  \begin{split} 
    491832    \frac { (\bar{e})^t - (\bar{e})^{t-\rdt} } {\rdt}  \equiv 
     
    504845  \end{split} 
    505846\end{equation} 
    506 where the last two terms in \autoref{eq:zdftke_ene} (vertical diffusion and Kolmogorov dissipation) 
    507 are time stepped using a backward scheme (see\autoref{sec:STP_forward_imp}). 
     847where the last two terms in \autoref{eq:ZDF_tke_ene} (vertical diffusion and Kolmogorov dissipation) 
     848are time stepped using a backward scheme (see\autoref{sec:TD_forward_imp}). 
    508849Note that the Kolmogorov term has been linearized in time in order to render the implicit computation possible. 
    509 The restart of the TKE scheme requires the storage of $\bar {e}$, $K_m$, $K_\rho$ and $l_\epsilon$ as 
    510 they all appear in the right hand side of \autoref{eq:zdftke_ene}. 
    511 For the latter, it is in fact the ratio $\sqrt{\bar{e}}/l_\epsilon$ which is stored.  
    512  
    513 % ------------------------------------------------------------------------------------------------------------- 
    514 %        GLS Generic Length Scale Scheme  
    515 % ------------------------------------------------------------------------------------------------------------- 
    516 \subsection{GLS: Generic Length Scale (\protect\key{zdfgls})} 
    517 \label{subsec:ZDF_gls} 
    518  
    519 %--------------------------------------------namzdf_gls--------------------------------------------------------- 
    520  
    521 \nlst{namzdf_gls} 
    522 %-------------------------------------------------------------------------------------------------------------- 
    523  
    524 The Generic Length Scale (GLS) scheme is a turbulent closure scheme based on two prognostic equations: 
    525 one for the turbulent kinetic energy $\bar {e}$, and another for the generic length scale, 
    526 $\psi$ \citep{Umlauf_Burchard_JMS03, Umlauf_Burchard_CSR05}. 
    527 This later variable is defined as: $\psi = {C_{0\mu}}^{p} \ {\bar{e}}^{m} \ l^{n}$,  
    528 where the triplet $(p, m, n)$ value given in Tab.\autoref{tab:GLS} allows to recover a number of 
    529 well-known turbulent closures ($k$-$kl$ \citep{Mellor_Yamada_1982}, $k$-$\epsilon$ \citep{Rodi_1987}, 
    530 $k$-$\omega$ \citep{Wilcox_1988} among others \citep{Umlauf_Burchard_JMS03,Kantha_Carniel_CSR05}).  
    531 The GLS scheme is given by the following set of equations: 
    532 \begin{equation} 
    533   \label{eq:zdfgls_e} 
    534   \frac{\partial \bar{e}}{\partial t} = 
    535   \frac{K_m}{\sigma_e e_3 }\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 
    536       +\left( \frac{\partial v}{\partial k} \right)^2} \right] 
    537   -K_\rho \,N^2 
    538   +\frac{1}{e_3}\,\frac{\partial}{\partial k} \left[ \frac{K_m}{e_3}\,\frac{\partial \bar{e}}{\partial k} \right] 
    539   - \epsilon 
    540 \end{equation} 
    541  
    542 \[ 
    543   % \label{eq:zdfgls_psi} 
    544   \begin{split} 
    545     \frac{\partial \psi}{\partial t} =& \frac{\psi}{\bar{e}} \left\{ 
    546       \frac{C_1\,K_m}{\sigma_{\psi} {e_3}}\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 
    547           +\left( \frac{\partial v}{\partial k} \right)^2} \right] 
    548       - C_3 \,K_\rho\,N^2   - C_2 \,\epsilon \,Fw   \right\}             \\ 
    549     &+\frac{1}{e_3}  \;\frac{\partial }{\partial k}\left[ {\frac{K_m}{e_3 } 
    550         \;\frac{\partial \psi}{\partial k}} \right]\; 
    551   \end{split} 
    552 \] 
    553  
    554 \[ 
    555   % \label{eq:zdfgls_kz} 
    556   \begin{split} 
    557     K_m    &= C_{\mu} \ \sqrt {\bar{e}} \ l         \\ 
    558     K_\rho &= C_{\mu'}\ \sqrt {\bar{e}} \ l 
    559   \end{split} 
    560 \] 
    561  
    562 \[ 
    563   % \label{eq:zdfgls_eps} 
    564   {\epsilon} = C_{0\mu} \,\frac{\bar {e}^{3/2}}{l} \; 
    565 \] 
    566 where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}) and 
    567 $\epsilon$ the dissipation rate.  
    568 The constants $C_1$, $C_2$, $C_3$, ${\sigma_e}$, ${\sigma_{\psi}}$ and the wall function ($Fw$) depends of 
    569 the choice of the turbulence model. 
    570 Four different turbulent models are pre-defined (Tab.\autoref{tab:GLS}). 
    571 They are made available through the \np{nn\_clo} namelist parameter.  
    572  
    573 %--------------------------------------------------TABLE-------------------------------------------------- 
    574 \begin{table}[htbp] 
    575   \begin{center} 
    576     % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}c} 
    577     \begin{tabular}{ccccc} 
    578       &   $k-kl$   & $k-\epsilon$ & $k-\omega$ &   generic   \\ 
    579       % & \citep{Mellor_Yamada_1982} &  \citep{Rodi_1987}       & \citep{Wilcox_1988} &                 \\ 
    580       \hline 
    581       \hline 
    582       \np{nn\_clo}     & \textbf{0} &   \textbf{1}  &   \textbf{2}   &    \textbf{3}   \\ 
    583       \hline 
    584       $( p , n , m )$          &   ( 0 , 1 , 1 )   & ( 3 , 1.5 , -1 )   & ( -1 , 0.5 , -1 )    &  ( 2 , 1 , -0.67 )  \\ 
    585       $\sigma_k$      &    2.44         &     1.              &      2.                &      0.8          \\ 
    586       $\sigma_\psi$  &    2.44         &     1.3            &      2.                 &       1.07       \\ 
    587       $C_1$              &      0.9         &     1.44          &      0.555          &       1.           \\ 
    588       $C_2$              &      0.5         &     1.92          &      0.833          &       1.22       \\ 
    589       $C_3$              &      1.           &     1.              &      1.                &       1.           \\ 
    590       $F_{wall}$        &      Yes        &       --             &     --                  &      --          \\ 
    591       \hline 
    592       \hline 
    593     \end{tabular} 
    594     \caption{ 
    595       \protect\label{tab:GLS} 
    596       Set of predefined GLS parameters, or equivalently predefined turbulence models available with 
    597       \protect\key{zdfgls} and controlled by the \protect\np{nn\_clos} namelist variable in \protect\ngn{namzdf\_gls}. 
    598     } 
    599   \end{center} 
    600 \end{table} 
    601 %-------------------------------------------------------------------------------------------------------------- 
    602  
    603 In the Mellor-Yamada model, the negativity of $n$ allows to use a wall function to force the convergence of 
    604 the mixing length towards $K z_b$ ($K$: Kappa and $z_b$: rugosity length) value near physical boundaries 
    605 (logarithmic boundary layer law). 
    606 $C_{\mu}$ and $C_{\mu'}$ are calculated from stability function proposed by \citet{Galperin_al_JAS88}, 
    607 or by \citet{Kantha_Clayson_1994} or one of the two functions suggested by \citet{Canuto_2001} 
    608 (\np{nn\_stab\_func}\forcode{ = 0..3}, resp.).  
    609 The value of $C_{0\mu}$ depends of the choice of the stability function. 
    610  
    611 The surface and bottom boundary condition on both $\bar{e}$ and $\psi$ can be calculated thanks to Dirichlet or 
    612 Neumann condition through \np{nn\_tkebc\_surf} and \np{nn\_tkebc\_bot}, resp. 
    613 As for TKE closure, the wave effect on the mixing is considered when 
    614 \np{ln\_crban}\forcode{ = .true.} \citep{Craig_Banner_JPO94, Mellor_Blumberg_JPO04}. 
    615 The \np{rn\_crban} namelist parameter is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and 
    616 \np{rn\_charn} provides the value of $\beta$ in \autoref{eq:ZDF_Lsbc}.  
    617  
    618 The $\psi$ equation is known to fail in stably stratified flows, and for this reason 
    619 almost all authors apply a clipping of the length scale as an \textit{ad hoc} remedy. 
    620 With this clipping, the maximum permissible length scale is determined by $l_{max} = c_{lim} \sqrt{2\bar{e}}/ N$. 
    621 A value of $c_{lim} = 0.53$ is often used \citep{Galperin_al_JAS88}. 
    622 \cite{Umlauf_Burchard_CSR05} show that the value of the clipping factor is of crucial importance for 
    623 the entrainment depth predicted in stably stratified situations, 
    624 and that its value has to be chosen in accordance with the algebraic model for the turbulent fluxes. 
    625 The clipping is only activated if \np{ln\_length\_lim}\forcode{ = .true.}, 
    626 and the $c_{lim}$ is set to the \np{rn\_clim\_galp} value. 
    627  
    628 The time and space discretization of the GLS equations follows the same energetic consideration as for 
    629 the TKE case described in \autoref{subsec:ZDF_tke_ene} \citep{Burchard_OM02}. 
    630 Examples of performance of the 4 turbulent closure scheme can be found in \citet{Warner_al_OM05}. 
    631  
    632 % ------------------------------------------------------------------------------------------------------------- 
    633 %        OSM OSMOSIS BL Scheme  
    634 % ------------------------------------------------------------------------------------------------------------- 
    635 \subsection{OSM: OSMOSIS boundary layer scheme (\protect\key{zdfosm})} 
    636 \label{subsec:ZDF_osm} 
    637  
    638 %--------------------------------------------namzdf_osm--------------------------------------------------------- 
    639  
    640 \nlst{namzdf_osm} 
    641 %-------------------------------------------------------------------------------------------------------------- 
    642  
    643 The OSMOSIS turbulent closure scheme is based on......   TBC 
    644  
    645 % ================================================================ 
    646 % Convection 
    647 % ================================================================ 
     850%The restart of the TKE scheme requires the storage of $\bar {e}$, $K_m$, $K_\rho$ and $l_\epsilon$ as 
     851%they all appear in the right hand side of \autoref{eq:ZDF_tke_ene}. 
     852%For the latter, it is in fact the ratio $\sqrt{\bar{e}}/l_\epsilon$ which is stored. 
     853 
     854%% ================================================================================================= 
    648855\section{Convection} 
    649856\label{sec:ZDF_conv} 
    650857 
    651 %--------------------------------------------namzdf-------------------------------------------------------- 
    652  
    653 \nlst{namzdf} 
    654 %-------------------------------------------------------------------------------------------------------------- 
    655  
    656 Static instabilities (\ie light potential densities under heavy ones) may occur at particular ocean grid points. 
     858Static instabilities (\ie\ light potential densities under heavy ones) may occur at particular ocean grid points. 
    657859In nature, convective processes quickly re-establish the static stability of the water column. 
    658860These processes have been removed from the model via the hydrostatic assumption so they must be parameterized. 
     
    661863or/and the use of a turbulent closure scheme. 
    662864 
    663 % ------------------------------------------------------------------------------------------------------------- 
    664 %       Non-Penetrative Convective Adjustment  
    665 % ------------------------------------------------------------------------------------------------------------- 
    666 \subsection[Non-penetrative convective adjmt (\protect\np{ln\_tranpc}\forcode{ = .true.})] 
    667             {Non-penetrative convective adjustment (\protect\np{ln\_tranpc}\forcode{ = .true.})} 
     865%% ================================================================================================= 
     866\subsection[Non-penetrative convective adjustment (\forcode{ln_tranpc})]{Non-penetrative convective adjustment (\protect\np{ln_tranpc}{ln\_tranpc})} 
    668867\label{subsec:ZDF_npc} 
    669868 
    670 %--------------------------------------------namzdf-------------------------------------------------------- 
    671  
    672 \nlst{namzdf} 
    673 %-------------------------------------------------------------------------------------------------------------- 
    674  
    675 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    676869\begin{figure}[!htb] 
    677   \begin{center} 
    678     \includegraphics[width=0.90\textwidth]{Fig_npc} 
    679     \caption{ 
    680       \protect\label{fig:npc} 
    681       Example of an unstable density profile treated by the non penetrative convective adjustment algorithm. 
    682       $1^{st}$ step: the initial profile is checked from the surface to the bottom. 
    683       It is found to be unstable between levels 3 and 4. 
    684       They are mixed. 
    685       The resulting $\rho$ is still larger than $\rho$(5): levels 3 to 5 are mixed. 
    686       The resulting $\rho$ is still larger than $\rho$(6): levels 3 to 6 are mixed. 
    687       The $1^{st}$ step ends since the density profile is then stable below the level 3. 
    688       $2^{nd}$ step: the new $\rho$ profile is checked following the same procedure as in $1^{st}$ step: 
    689       levels 2 to 5 are mixed. 
    690       The new density profile is checked. 
    691       It is found stable: end of algorithm. 
    692     } 
    693   \end{center} 
     870  \centering 
     871  \includegraphics[width=0.66\textwidth]{ZDF_npc} 
     872  \caption[Unstable density profile treated by the non penetrative convective adjustment algorithm]{ 
     873    Example of an unstable density profile treated by 
     874    the non penetrative convective adjustment algorithm. 
     875    $1^{st}$ step: the initial profile is checked from the surface to the bottom. 
     876    It is found to be unstable between levels 3 and 4. 
     877    They are mixed. 
     878    The resulting $\rho$ is still larger than $\rho$(5): levels 3 to 5 are mixed. 
     879    The resulting $\rho$ is still larger than $\rho$(6): levels 3 to 6 are mixed. 
     880    The $1^{st}$ step ends since the density profile is then stable below the level 3. 
     881    $2^{nd}$ step: the new $\rho$ profile is checked following the same procedure as in $1^{st}$ step: 
     882    levels 2 to 5 are mixed. 
     883    The new density profile is checked. 
     884    It is found stable: end of algorithm.} 
     885  \label{fig:ZDF_npc} 
    694886\end{figure} 
    695 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    696  
    697 Options are defined through the \ngn{namzdf} namelist variables. 
    698 The non-penetrative convective adjustment is used when \np{ln\_zdfnpc}\forcode{ = .true.}. 
    699 It is applied at each \np{nn\_npc} time step and mixes downwards instantaneously the statically unstable portion of 
     887 
     888Options are defined through the \nam{zdf}{zdf} namelist variables. 
     889The non-penetrative convective adjustment is used when \np[=.true.]{ln_zdfnpc}{ln\_zdfnpc}. 
     890It is applied at each \np{nn_npc}{nn\_npc} time step and mixes downwards instantaneously the statically unstable portion of 
    700891the water column, but only until the density structure becomes neutrally stable 
    701 (\ie until the mixed portion of the water column has \textit{exactly} the density of the water just below) 
    702 \citep{Madec_al_JPO91}. 
    703 The associated algorithm is an iterative process used in the following way (\autoref{fig:npc}): 
     892(\ie\ until the mixed portion of the water column has \textit{exactly} the density of the water just below) 
     893\citep{madec.delecluse.ea_JPO91}. 
     894The associated algorithm is an iterative process used in the following way (\autoref{fig:ZDF_npc}): 
    704895starting from the top of the ocean, the first instability is found. 
    705896Assume in the following that the instability is located between levels $k$ and $k+1$. 
     
    716907This algorithm is significantly different from mixing statically unstable levels two by two. 
    717908The latter procedure cannot converge with a finite number of iterations for some vertical profiles while 
    718 the algorithm used in \NEMO converges for any profile in a number of iterations which is less than 
     909the algorithm used in \NEMO\ converges for any profile in a number of iterations which is less than 
    719910the number of vertical levels. 
    720 This property is of paramount importance as pointed out by \citet{Killworth1989}: 
     911This property is of paramount importance as pointed out by \citet{killworth_iprc89}: 
    721912it avoids the existence of permanent and unrealistic static instabilities at the sea surface. 
    722913This non-penetrative convective algorithm has been proved successful in studies of the deep water formation in 
    723 the north-western Mediterranean Sea \citep{Madec_al_JPO91, Madec_al_DAO91, Madec_Crepon_Bk91}. 
     914the north-western Mediterranean Sea \citep{madec.delecluse.ea_JPO91, madec.chartier.ea_DAO91, madec.crepon_iprc91}. 
    724915 
    725916The current implementation has been modified in order to deal with any non linear equation of seawater 
    726917(L. Brodeau, personnal communication). 
    727918Two main differences have been introduced compared to the original algorithm: 
    728 $(i)$ the stability is now checked using the Brunt-V\"{a}is\"{a}l\"{a} frequency  
    729 (not the the difference in potential density);  
     919$(i)$ the stability is now checked using the Brunt-V\"{a}is\"{a}l\"{a} frequency 
     920(not the difference in potential density); 
    730921$(ii)$ when two levels are found unstable, their thermal and haline expansion coefficients are vertically mixed in 
    731922the same way their temperature and salinity has been mixed. 
     
    733924having to recompute the expansion coefficients at each mixing iteration. 
    734925 
    735 % ------------------------------------------------------------------------------------------------------------- 
    736 %       Enhanced Vertical Diffusion  
    737 % ------------------------------------------------------------------------------------------------------------- 
    738 \subsection{Enhanced vertical diffusion (\protect\np{ln\_zdfevd}\forcode{ = .true.})} 
     926%% ================================================================================================= 
     927\subsection[Enhanced vertical diffusion (\forcode{ln_zdfevd})]{Enhanced vertical diffusion (\protect\np{ln_zdfevd}{ln\_zdfevd})} 
    739928\label{subsec:ZDF_evd} 
    740929 
    741 %--------------------------------------------namzdf-------------------------------------------------------- 
    742  
    743 \nlst{namzdf} 
    744 %-------------------------------------------------------------------------------------------------------------- 
    745  
    746 Options are defined through the  \ngn{namzdf} namelist variables. 
    747 The enhanced vertical diffusion parameterisation is used when \np{ln\_zdfevd}\forcode{ = .true.}. 
     930Options are defined through the  \nam{zdf}{zdf} namelist variables. 
     931The enhanced vertical diffusion parameterisation is used when \np[=.true.]{ln_zdfevd}{ln\_zdfevd}. 
    748932In this case, the vertical eddy mixing coefficients are assigned very large values 
    749 (a typical value is $10\;m^2s^{-1})$ in regions where the stratification is unstable 
    750 (\ie when $N^2$ the Brunt-Vais\"{a}l\"{a} frequency is negative) \citep{Lazar_PhD97, Lazar_al_JPO99}. 
    751 This is done either on tracers only (\np{nn\_evdm}\forcode{ = 0}) or 
    752 on both momentum and tracers (\np{nn\_evdm}\forcode{ = 1}). 
    753  
    754 In practice, where $N^2\leq 10^{-12}$, $A_T^{vT}$ and $A_T^{vS}$, and if \np{nn\_evdm}\forcode{ = 1}, 
     933in regions where the stratification is unstable 
     934(\ie\ when $N^2$ the Brunt-Vais\"{a}l\"{a} frequency is negative) \citep{lazar_phd97, lazar.madec.ea_JPO99}. 
     935This is done either on tracers only (\np[=0]{nn_evdm}{nn\_evdm}) or 
     936on both momentum and tracers (\np[=1]{nn_evdm}{nn\_evdm}). 
     937 
     938In practice, where $N^2\leq 10^{-12}$, $A_T^{vT}$ and $A_T^{vS}$, and if \np[=1]{nn_evdm}{nn\_evdm}, 
    755939the four neighbouring $A_u^{vm} \;\mbox{and}\;A_v^{vm}$ values also, are set equal to 
    756 the namelist parameter \np{rn\_avevd}. 
     940the namelist parameter \np{rn_avevd}{rn\_avevd}. 
    757941A typical value for $rn\_avevd$ is between 1 and $100~m^2.s^{-1}$. 
    758942This parameterisation of convective processes is less time consuming than 
    759943the convective adjustment algorithm presented above when mixing both tracers and 
    760944momentum in the case of static instabilities. 
    761 It requires the use of an implicit time stepping on vertical diffusion terms 
    762 (\ie np{ln\_zdfexp}\forcode{ = .false.}). 
    763945 
    764946Note that the stability test is performed on both \textit{before} and \textit{now} values of $N^2$. 
    765947This removes a potential source of divergence of odd and even time step in 
    766 a leapfrog environment \citep{Leclair_PhD2010} (see \autoref{sec:STP_mLF}). 
    767  
    768 % ------------------------------------------------------------------------------------------------------------- 
    769 %       Turbulent Closure Scheme  
    770 % ------------------------------------------------------------------------------------------------------------- 
    771 \subsection[Turbulent closure scheme (\protect\key{zdf}\{tke,gls,osm\})]{Turbulent Closure Scheme (\protect\key{zdftke}, \protect\key{zdfgls} or \protect\key{zdfosm})} 
     948a leapfrog environment \citep{leclair_phd10} (see \autoref{sec:TD_mLF}). 
     949 
     950%% ================================================================================================= 
     951\subsection[Handling convection with turbulent closure schemes (\forcode{ln_zdf_}\{\forcode{tke,gls,osm}\})]{Handling convection with turbulent closure schemes (\forcode{ln_zdf{tke,gls,osm}})} 
    772952\label{subsec:ZDF_tcs} 
    773953 
    774 The turbulent closure scheme presented in \autoref{subsec:ZDF_tke} and \autoref{subsec:ZDF_gls} 
    775 (\key{zdftke} or \key{zdftke} is defined) in theory solves the problem of statically unstable density profiles. 
     954The turbulent closure schemes presented in \autoref{subsec:ZDF_tke}, \autoref{subsec:ZDF_gls} and 
     955\autoref{subsec:ZDF_osm} (\ie\ \np{ln_zdftke}{ln\_zdftke} or \np{ln_zdfgls}{ln\_zdfgls} or \np{ln_zdfosm}{ln\_zdfosm} defined) deal, in theory, 
     956with statically unstable density profiles. 
    776957In such a case, the term corresponding to the destruction of turbulent kinetic energy through stratification in 
    777 \autoref{eq:zdftke_e} or \autoref{eq:zdfgls_e} becomes a source term, since $N^2$ is negative.  
    778 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}$ 
    779 (up to $1\;m^2s^{-1}$). 
     958\autoref{eq:ZDF_tke_e} or \autoref{eq:ZDF_gls_e} becomes a source term, since $N^2$ is negative. 
     959It results in large values of $A_T^{vT}$ and  $A_T^{vT}$, and also of the four neighboring values at 
     960velocity points $A_u^{vm} {and}\;A_v^{vm}$ (up to $1\;m^2s^{-1}$). 
    780961These large values restore the static stability of the water column in a way similar to that of 
    781962the enhanced vertical diffusion parameterisation (\autoref{subsec:ZDF_evd}). 
     
    784965because the mixing length scale is bounded by the distance to the sea surface. 
    785966It can thus be useful to combine the enhanced vertical diffusion with the turbulent closure scheme, 
    786 \ie setting the \np{ln\_zdfnpc} namelist parameter to true and 
    787 defining the turbulent closure CPP key all together. 
    788  
    789 The KPP turbulent closure scheme already includes enhanced vertical diffusion in the case of convection, 
    790 as governed by the variables $bvsqcon$ and $difcon$ found in \mdl{zdfkpp}, 
    791 therefore \np{ln\_zdfevd}\forcode{ = .false.} should be used with the KPP scheme. 
     967\ie\ setting the \np{ln_zdfnpc}{ln\_zdfnpc} namelist parameter to true and 
     968defining the turbulent closure (\np{ln_zdftke}{ln\_zdftke} or \np{ln_zdfgls}{ln\_zdfgls} = \forcode{.true.}) all together. 
     969 
     970The OSMOSIS turbulent closure scheme already includes enhanced vertical diffusion in the case of convection, 
     971%as governed by the variables $bvsqcon$ and $difcon$ found in \mdl{zdfkpp}, 
     972therefore \np[=.false.]{ln_zdfevd}{ln\_zdfevd} should be used with the OSMOSIS scheme. 
    792973% gm%  + one word on non local flux with KPP scheme trakpp.F90 module... 
    793974 
    794 % ================================================================ 
    795 % Double Diffusion Mixing 
    796 % ================================================================ 
    797 \section{Double diffusion mixing (\protect\key{zdfddm})} 
    798 \label{sec:ZDF_ddm} 
    799  
    800 %-------------------------------------------namzdf_ddm------------------------------------------------- 
    801 % 
     975%% ================================================================================================= 
     976\section[Double diffusion mixing (\forcode{ln_zdfddm})]{Double diffusion mixing (\protect\np{ln_zdfddm}{ln\_zdfddm})} 
     977\label{subsec:ZDF_ddm} 
     978 
    802979%\nlst{namzdf_ddm} 
    803 %-------------------------------------------------------------------------------------------------------------- 
    804  
    805 Options are defined through the  \ngn{namzdf\_ddm} namelist variables. 
     980 
     981This parameterisation has been introduced in \mdl{zdfddm} module and is controlled by the namelist parameter 
     982\np{ln_zdfddm}{ln\_zdfddm} in \nam{zdf}{zdf}. 
    806983Double diffusion occurs when relatively warm, salty water overlies cooler, fresher water, or vice versa. 
    807984The former condition leads to salt fingering and the latter to diffusive convection. 
    808985Double-diffusive phenomena contribute to diapycnal mixing in extensive regions of the ocean. 
    809 \citet{Merryfield1999} include a parameterisation of such phenomena in a global ocean model and show that  
     986\citet{merryfield.holloway.ea_JPO99} include a parameterisation of such phenomena in a global ocean model and show that 
    810987it leads to relatively minor changes in circulation but exerts significant regional influences on 
    811988temperature and salinity. 
    812 This parameterisation has been introduced in \mdl{zdfddm} module and is controlled by the \key{zdfddm} CPP key. 
    813  
    814 Diapycnal mixing of S and T are described by diapycnal diffusion coefficients  
     989 
     990Diapycnal mixing of S and T are described by diapycnal diffusion coefficients 
    815991\begin{align*} 
    816   % \label{eq:zdfddm_Kz} 
     992  % \label{eq:ZDF_ddm_Kz} 
    817993  &A^{vT} = A_o^{vT}+A_f^{vT}+A_d^{vT} \\ 
    818994  &A^{vS} = A_o^{vS}+A_f^{vS}+A_d^{vS} 
     
    8261002(1981): 
    8271003\begin{align} 
    828   \label{eq:zdfddm_f} 
     1004  \label{eq:ZDF_ddm_f} 
    8291005  A_f^{vS} &= 
    8301006             \begin{cases} 
     
    8321008               0                              &\text{otherwise} 
    8331009             \end{cases} 
    834   \\         \label{eq:zdfddm_f_T} 
    835   A_f^{vT} &= 0.7 \ A_f^{vS} / R_\rho  
     1010  \\         \label{eq:ZDF_ddm_f_T} 
     1011  A_f^{vT} &= 0.7 \ A_f^{vS} / R_\rho 
    8361012\end{align} 
    8371013 
    838 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    8391014\begin{figure}[!t] 
    840   \begin{center} 
    841     \includegraphics[width=0.99\textwidth]{Fig_zdfddm} 
    842     \caption{ 
    843       \protect\label{fig:zdfddm} 
    844       From \citet{Merryfield1999} : 
    845       (a) Diapycnal diffusivities $A_f^{vT}$ and $A_f^{vS}$ for temperature and salt in regions of salt fingering. 
    846       Heavy curves denote $A^{\ast v} = 10^{-3}~m^2.s^{-1}$ and thin curves $A^{\ast v} = 10^{-4}~m^2.s^{-1}$; 
    847       (b) diapycnal diffusivities $A_d^{vT}$ and $A_d^{vS}$ for temperature and salt in regions of 
    848       diffusive convection. 
    849       Heavy curves denote the Federov parameterisation and thin curves the Kelley parameterisation. 
    850       The latter is not implemented in \NEMO. 
    851     } 
    852   \end{center} 
     1015  \centering 
     1016  \includegraphics[width=0.66\textwidth]{ZDF_ddm} 
     1017  \caption[Diapycnal diffusivities for temperature and salt in regions of salt fingering and 
     1018  diffusive convection]{ 
     1019    From \citet{merryfield.holloway.ea_JPO99}: 
     1020    (a) Diapycnal diffusivities $A_f^{vT}$ and $A_f^{vS}$ for temperature and salt in 
     1021    regions of salt fingering. 
     1022    Heavy curves denote $A^{\ast v} = 10^{-3}~m^2.s^{-1}$ and 
     1023    thin curves $A^{\ast v} = 10^{-4}~m^2.s^{-1}$; 
     1024    (b) diapycnal diffusivities $A_d^{vT}$ and $A_d^{vS}$ for temperature and salt in 
     1025    regions of diffusive convection. 
     1026    Heavy curves denote the Federov parameterisation and thin curves the Kelley parameterisation. 
     1027    The latter is not implemented in \NEMO.} 
     1028  \label{fig:ZDF_ddm} 
    8531029\end{figure} 
    854 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    855  
    856 The factor 0.7 in \autoref{eq:zdfddm_f_T} reflects the measured ratio $\alpha F_T /\beta F_S \approx  0.7$ of 
    857 buoyancy flux of heat to buoyancy flux of salt (\eg, \citet{McDougall_Taylor_JMR84}). 
    858 Following  \citet{Merryfield1999}, we adopt $R_c = 1.6$, $n = 6$, and $A^{\ast v} = 10^{-4}~m^2.s^{-1}$. 
     1030 
     1031The factor 0.7 in \autoref{eq:ZDF_ddm_f_T} reflects the measured ratio $\alpha F_T /\beta F_S \approx  0.7$ of 
     1032buoyancy flux of heat to buoyancy flux of salt (\eg, \citet{mcdougall.taylor_JMR84}). 
     1033Following  \citet{merryfield.holloway.ea_JPO99}, we adopt $R_c = 1.6$, $n = 6$, and $A^{\ast v} = 10^{-4}~m^2.s^{-1}$. 
    8591034 
    8601035To represent mixing of S and T by diffusive layering,  the diapycnal diffusivities suggested by 
    861 Federov (1988) is used:  
     1036Federov (1988) is used: 
    8621037\begin{align} 
    863   % \label{eq:zdfddm_d} 
     1038  % \label{eq:ZDF_ddm_d} 
    8641039  A_d^{vT} &= 
    8651040             \begin{cases} 
     
    8691044             \end{cases} 
    8701045                                       \nonumber \\ 
    871   \label{eq:zdfddm_d_S} 
     1046  \label{eq:ZDF_ddm_d_S} 
    8721047  A_d^{vS} &= 
    8731048             \begin{cases} 
     
    8781053\end{align} 
    8791054 
    880 The dependencies of \autoref{eq:zdfddm_f} to \autoref{eq:zdfddm_d_S} on $R_\rho$ are illustrated in 
    881 \autoref{fig:zdfddm}. 
     1055The dependencies of \autoref{eq:ZDF_ddm_f} to \autoref{eq:ZDF_ddm_d_S} on $R_\rho$ are illustrated in 
     1056\autoref{fig:ZDF_ddm}. 
    8821057Implementing this requires computing $R_\rho$ at each grid point on every time step. 
    8831058This is done in \mdl{eosbn2} at the same time as $N^2$ is computed. 
    8841059This avoids duplication in the computation of $\alpha$ and $\beta$ (which is usually quite expensive). 
    8851060 
    886 % ================================================================ 
    887 % Bottom Friction 
    888 % ================================================================ 
    889 \section{Bottom and top friction (\protect\mdl{zdfbfr})} 
    890 \label{sec:ZDF_bfr} 
    891  
    892 %--------------------------------------------nambfr-------------------------------------------------------- 
    893 % 
    894 %\nlst{nambfr} 
    895 %-------------------------------------------------------------------------------------------------------------- 
    896  
    897 Options to define the top and bottom friction are defined through the \ngn{nambfr} namelist variables. 
     1061%% ================================================================================================= 
     1062\section[Bottom and top friction (\textit{zdfdrg.F90})]{Bottom and top friction (\protect\mdl{zdfdrg})} 
     1063\label{sec:ZDF_drg} 
     1064 
     1065\begin{listing} 
     1066  \nlst{namdrg} 
     1067  \caption{\forcode{&namdrg}} 
     1068  \label{lst:namdrg} 
     1069\end{listing} 
     1070\begin{listing} 
     1071  \nlst{namdrg_top} 
     1072  \caption{\forcode{&namdrg_top}} 
     1073  \label{lst:namdrg_top} 
     1074\end{listing} 
     1075\begin{listing} 
     1076  \nlst{namdrg_bot} 
     1077  \caption{\forcode{&namdrg_bot}} 
     1078  \label{lst:namdrg_bot} 
     1079\end{listing} 
     1080 
     1081Options to define the top and bottom friction are defined through the \nam{drg}{drg} namelist variables. 
    8981082The bottom friction represents the friction generated by the bathymetry. 
    8991083The top friction represents the friction generated by the ice shelf/ocean interface. 
    900 As the friction processes at the top and bottom are treated in similar way, 
    901 only the bottom friction is described in detail below. 
    902  
     1084As the friction processes at the top and the bottom are treated in and identical way, 
     1085the description below considers mostly the bottom friction case, if not stated otherwise. 
    9031086 
    9041087Both the surface momentum flux (wind stress) and the bottom momentum flux (bottom friction) enter the equations as 
    9051088a condition on the vertical diffusive flux. 
    9061089For the bottom boundary layer, one has: 
    907 \[ 
    908   % \label{eq:zdfbfr_flux} 
    909   A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U} 
    910 \] 
     1090 \[ 
     1091   % \label{eq:ZDF_bfr_flux} 
     1092   A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U} 
     1093 \] 
    9111094where ${\cal F}_h^{\textbf U}$ is represents the downward flux of horizontal momentum outside 
    9121095the logarithmic turbulent boundary layer (thickness of the order of 1~m in the ocean). 
     
    9161099one needs a vertical diffusion coefficient $A^{vm} = 0.125$~m$^2$s$^{-1}$ 
    9171100(for a Coriolis frequency $f = 10^{-4}$~m$^2$s$^{-1}$). 
    918 With a background diffusion coefficient $A^{vm} = 10^{-4}$~m$^2$s$^{-1}$, the Ekman layer depth is only 1.4~m.  
     1101With a background diffusion coefficient $A^{vm} = 10^{-4}$~m$^2$s$^{-1}$, the Ekman layer depth is only 1.4~m. 
    9191102When the vertical mixing coefficient is this small, using a flux condition is equivalent to 
    9201103entering the viscous forces (either wind stress or bottom friction) as a body force over the depth of the top or 
     
    9221105To illustrate this, consider the equation for $u$ at $k$, the last ocean level: 
    9231106\begin{equation} 
    924   \label{eq:zdfbfr_flux2} 
     1107  \label{eq:ZDF_drg_flux2} 
    9251108  \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}} 
    9261109\end{equation} 
     
    9351118 
    9361119In the code, the bottom friction is imposed by adding the trend due to the bottom friction to 
    937 the general momentum trend in \mdl{dynbfr}. 
     1120 the general momentum trend in \mdl{dynzdf}. 
    9381121For the time-split surface pressure gradient algorithm, the momentum trend due to 
    9391122the barotropic component needs to be handled separately. 
    9401123For this purpose it is convenient to compute and store coefficients which can be simply combined with 
    9411124bottom velocities and geometric values to provide the momentum trend due to bottom friction. 
    942 These coefficients are computed in \mdl{zdfbfr} and generally take the form $c_b^{\textbf U}$ where: 
     1125 These coefficients are computed in \mdl{zdfdrg} and generally take the form $c_b^{\textbf U}$ where: 
    9431126\begin{equation} 
    944   \label{eq:zdfbfr_bdef} 
     1127  \label{eq:ZDF_bfr_bdef} 
    9451128  \frac{\partial {\textbf U_h}}{\partial t} = 
    9461129  - \frac{{\cal F}^{\textbf U}_{h}}{e_{3u}} = \frac{c_b^{\textbf U}}{e_{3u}} \;{\textbf U}_h^b 
    9471130\end{equation} 
    9481131where $\textbf{U}_h^b = (u_b\;,\;v_b)$ is the near-bottom, horizontal, ocean velocity. 
    949  
    950 % ------------------------------------------------------------------------------------------------------------- 
    951 %       Linear Bottom Friction 
    952 % ------------------------------------------------------------------------------------------------------------- 
    953 \subsection{Linear bottom friction (\protect\np{nn\_botfr}\forcode{ = 0..1})} 
    954 \label{subsec:ZDF_bfr_linear} 
    955  
    956 The linear bottom friction parameterisation (including the special case of a free-slip condition) assumes that 
    957 the bottom friction is proportional to the interior velocity (\ie the velocity of the last model level): 
    958 \[ 
    959   % \label{eq:zdfbfr_linear} 
     1132Note 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. 
     1133 
     1134%% ================================================================================================= 
     1135\subsection[Linear top/bottom friction (\forcode{ln_lin})]{Linear top/bottom friction (\protect\np{ln_lin}{ln\_lin})} 
     1136\label{subsec:ZDF_drg_linear} 
     1137 
     1138The linear friction parameterisation (including the special case of a free-slip condition) assumes that 
     1139the friction is proportional to the interior velocity (\ie\ the velocity of the first/last model level): 
     1140\[ 
     1141  % \label{eq:ZDF_bfr_linear} 
    9601142  {\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3} \; \frac{\partial \textbf{U}_h}{\partial k} = r \; \textbf{U}_h^b 
    9611143\] 
    962 where $r$ is a friction coefficient expressed in ms$^{-1}$. 
    963 This coefficient is generally estimated by setting a typical decay time $\tau$ in the deep ocean,  
     1144where $r$ is a friction coefficient expressed in $m s^{-1}$. 
     1145This coefficient is generally estimated by setting a typical decay time $\tau$ in the deep ocean, 
    9641146and setting $r = H / \tau$, where $H$ is the ocean depth. 
    965 Commonly accepted values of $\tau$ are of the order of 100 to 200 days \citep{Weatherly_JMR84}. 
     1147Commonly accepted values of $\tau$ are of the order of 100 to 200 days \citep{weatherly_JMR84}. 
    9661148A value $\tau^{-1} = 10^{-7}$~s$^{-1}$ equivalent to 115 days, is usually used in quasi-geostrophic models. 
    9671149One may consider the linear friction as an approximation of quadratic friction, $r \approx 2\;C_D\;U_{av}$ 
    968 (\citet{Gill1982}, Eq. 9.6.6). 
     1150(\citet{gill_bk82}, Eq. 9.6.6). 
    9691151For example, with a drag coefficient $C_D = 0.002$, a typical speed of tidal currents of $U_{av} =0.1$~m\;s$^{-1}$, 
    9701152and assuming an ocean depth $H = 4000$~m, the resulting friction coefficient is $r = 4\;10^{-4}$~m\;s$^{-1}$. 
    9711153This is the default value used in \NEMO. It corresponds to a decay time scale of 115~days. 
    972 It can be changed by specifying \np{rn\_bfri1} (namelist parameter). 
    973  
    974 For the linear friction case the coefficients defined in the general expression \autoref{eq:zdfbfr_bdef} are:  
    975 \[ 
    976   % \label{eq:zdfbfr_linbfr_b} 
    977   \begin{split} 
    978     c_b^u &= - r\\ 
    979     c_b^v &= - r\\ 
    980   \end{split} 
    981 \] 
    982 When \np{nn\_botfr}\forcode{ = 1}, the value of $r$ used is \np{rn\_bfri1}. 
    983 Setting \np{nn\_botfr}\forcode{ = 0} is equivalent to setting $r=0$ and 
    984 leads to a free-slip bottom boundary condition. 
    985 These values are assigned in \mdl{zdfbfr}. 
    986 From v3.2 onwards there is support for local enhancement of these values via an externally defined 2D mask array 
    987 (\np{ln\_bfr2d}\forcode{ = .true.}) given in the \ifile{bfr\_coef} input NetCDF file. 
     1154It can be changed by specifying \np{rn_Uc0}{rn\_Uc0} (namelist parameter). 
     1155 
     1156 For the linear friction case the drag coefficient used in the general expression \autoref{eq:ZDF_bfr_bdef} is: 
     1157\[ 
     1158  % \label{eq:ZDF_bfr_linbfr_b} 
     1159    c_b^T = - r 
     1160\] 
     1161When \np[=.true.]{ln_lin}{ln\_lin}, the value of $r$ used is \np{rn_Uc0}{rn\_Uc0}*\np{rn_Cd0}{rn\_Cd0}. 
     1162Setting \np[=.true.]{ln_OFF}{ln\_OFF} (and \forcode{ln_lin=.true.}) is equivalent to setting $r=0$ and leads to a free-slip boundary condition. 
     1163 
     1164These values are assigned in \mdl{zdfdrg}. 
     1165Note that there is support for local enhancement of these values via an externally defined 2D mask array 
     1166(\np[=.true.]{ln_boost}{ln\_boost}) given in the \ifile{bfr\_coef} input NetCDF file. 
    9881167The mask values should vary from 0 to 1. 
    9891168Locations with a non-zero mask value will have the friction coefficient increased by 
    990 $mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri1}. 
    991  
    992 % ------------------------------------------------------------------------------------------------------------- 
    993 %       Non-Linear Bottom Friction 
    994 % ------------------------------------------------------------------------------------------------------------- 
    995 \subsection{Non-linear bottom friction (\protect\np{nn\_botfr}\forcode{ = 2})} 
    996 \label{subsec:ZDF_bfr_nonlinear} 
    997  
    998 The non-linear bottom friction parameterisation assumes that the bottom friction is quadratic:  
    999 \[ 
    1000   % \label{eq:zdfbfr_nonlinear} 
     1169$mask\_value$ * \np{rn_boost}{rn\_boost} * \np{rn_Cd0}{rn\_Cd0}. 
     1170 
     1171%% ================================================================================================= 
     1172\subsection[Non-linear top/bottom friction (\forcode{ln_non_lin})]{Non-linear top/bottom friction (\protect\np{ln_non_lin}{ln\_non\_lin})} 
     1173\label{subsec:ZDF_drg_nonlinear} 
     1174 
     1175The non-linear bottom friction parameterisation assumes that the top/bottom friction is quadratic: 
     1176\[ 
     1177  % \label{eq:ZDF_drg_nonlinear} 
    10011178  {\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3 }\frac{\partial \textbf {U}_h 
    10021179  }{\partial k}=C_D \;\sqrt {u_b ^2+v_b ^2+e_b } \;\; \textbf {U}_h^b 
    10031180\] 
    1004 where $C_D$ is a drag coefficient, and $e_b $ a bottom turbulent kinetic energy due to tides, 
     1181where $C_D$ is a drag coefficient, and $e_b $ a top/bottom turbulent kinetic energy due to tides, 
    10051182internal waves breaking and other short time scale currents. 
    10061183A typical value of the drag coefficient is $C_D = 10^{-3} $. 
    1007 As an example, the CME experiment \citep{Treguier_JGR92} uses $C_D = 10^{-3}$ and 
    1008 $e_b = 2.5\;10^{-3}$m$^2$\;s$^{-2}$, while the FRAM experiment \citep{Killworth1992} uses $C_D = 1.4\;10^{-3}$ and 
     1184As an example, the CME experiment \citep{treguier_JGR92} uses $C_D = 10^{-3}$ and 
     1185$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 
    10091186$e_b =2.5\;\;10^{-3}$m$^2$\;s$^{-2}$. 
    1010 The CME choices have been set as default values (\np{rn\_bfri2} and \np{rn\_bfeb2} namelist parameters). 
    1011  
    1012 As for the linear case, the bottom friction is imposed in the code by adding the trend due to 
    1013 the bottom friction to the general momentum trend in \mdl{dynbfr}. 
    1014 For the non-linear friction case the terms computed in \mdl{zdfbfr} are: 
    1015 \[ 
    1016   % \label{eq:zdfbfr_nonlinbfr} 
    1017   \begin{split} 
    1018     c_b^u &= - \; C_D\;\left[ u^2 + \left(\bar{\bar{v}}^{i+1,j}\right)^2 + e_b \right]^{1/2}\\ 
    1019     c_b^v &= - \; C_D\;\left[  \left(\bar{\bar{u}}^{i,j+1}\right)^2 + v^2 + e_b \right]^{1/2}\\ 
    1020   \end{split} 
    1021 \] 
    1022  
    1023 The coefficients that control the strength of the non-linear bottom friction are initialised as namelist parameters: 
    1024 $C_D$= \np{rn\_bfri2}, and $e_b$ =\np{rn\_bfeb2}. 
    1025 Note for applications which treat tides explicitly a low or even zero value of \np{rn\_bfeb2} is recommended. 
    1026 From v3.2 onwards a local enhancement of $C_D$ is possible via an externally defined 2D mask array 
    1027 (\np{ln\_bfr2d}\forcode{ = .true.}). 
    1028 This works in the same way as for the linear bottom friction case with non-zero masked locations increased by 
    1029 $mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri2}. 
    1030  
    1031 % ------------------------------------------------------------------------------------------------------------- 
    1032 %       Bottom Friction Log-layer 
    1033 % ------------------------------------------------------------------------------------------------------------- 
    1034 \subsection[Log-layer btm frict enhncmnt (\protect\np{nn\_botfr}\forcode{ = 2}, \protect\np{ln\_loglayer}\forcode{ = .true.})] 
    1035             {Log-layer bottom friction enhancement (\protect\np{nn\_botfr}\forcode{ = 2}, \protect\np{ln\_loglayer}\forcode{ = .true.})} 
    1036 \label{subsec:ZDF_bfr_loglayer} 
    1037  
    1038 In the non-linear bottom friction case, the drag coefficient, $C_D$, can be optionally enhanced using 
    1039 a "law of the wall" scaling. 
    1040 If  \np{ln\_loglayer} = .true., $C_D$ is no longer constant but is related to the thickness of 
    1041 the last wet layer in each column by: 
    1042 \[ 
    1043   C_D = \left ( {\kappa \over {\rm log}\left ( 0.5e_{3t}/rn\_bfrz0 \right ) } \right )^2 
    1044 \] 
    1045  
    1046 \noindent where $\kappa$ is the von-Karman constant and \np{rn\_bfrz0} is a roughness length provided via 
    1047 the namelist. 
    1048  
    1049 For stability, the drag coefficient is bounded such that it is kept greater or equal to 
    1050 the base \np{rn\_bfri2} value and it is not allowed to exceed the value of an additional namelist parameter: 
    1051 \np{rn\_bfri2\_max}, \ie 
    1052 \[ 
    1053   rn\_bfri2 \leq C_D \leq rn\_bfri2\_max 
    1054 \] 
    1055  
    1056 \noindent Note also that a log-layer enhancement can also be applied to the top boundary friction if 
    1057 under ice-shelf cavities are in use (\np{ln\_isfcav}\forcode{ = .true.}). 
    1058 In this case, the relevant namelist parameters are \np{rn\_tfrz0}, \np{rn\_tfri2} and \np{rn\_tfri2\_max}. 
    1059  
    1060 % ------------------------------------------------------------------------------------------------------------- 
    1061 %       Bottom Friction stability 
    1062 % ------------------------------------------------------------------------------------------------------------- 
    1063 \subsection{Bottom friction stability considerations} 
    1064 \label{subsec:ZDF_bfr_stability} 
    1065  
    1066 Some care needs to exercised over the choice of parameters to ensure that the implementation of 
    1067 bottom friction does not induce numerical instability. 
    1068 For the purposes of stability analysis, an approximation to \autoref{eq:zdfbfr_flux2} is: 
     1187The CME choices have been set as default values (\np{rn_Cd0}{rn\_Cd0} and \np{rn_ke0}{rn\_ke0} namelist parameters). 
     1188 
     1189As for the linear case, the friction is imposed in the code by adding the trend due to 
     1190the friction to the general momentum trend in \mdl{dynzdf}. 
     1191For the non-linear friction case the term computed in \mdl{zdfdrg} is: 
     1192\[ 
     1193  % \label{eq:ZDF_drg_nonlinbfr} 
     1194    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} 
     1195\] 
     1196 
     1197The coefficients that control the strength of the non-linear friction are initialised as namelist parameters: 
     1198$C_D$= \np{rn_Cd0}{rn\_Cd0}, and $e_b$ =\np{rn_bfeb2}{rn\_bfeb2}. 
     1199Note that for applications which consider tides explicitly, a low or even zero value of \np{rn_bfeb2}{rn\_bfeb2} is recommended. A local enhancement of $C_D$ is again possible via an externally defined 2D mask array 
     1200(\np[=.true.]{ln_boost}{ln\_boost}). 
     1201This works in the same way as for the linear friction case with non-zero masked locations increased by 
     1202$mask\_value$ * \np{rn_boost}{rn\_boost} * \np{rn_Cd0}{rn\_Cd0}. 
     1203 
     1204%% ================================================================================================= 
     1205\subsection[Log-layer top/bottom friction (\forcode{ln_loglayer})]{Log-layer top/bottom friction (\protect\np{ln_loglayer}{ln\_loglayer})} 
     1206\label{subsec:ZDF_drg_loglayer} 
     1207 
     1208In the non-linear friction case, the drag coefficient, $C_D$, can be optionally enhanced using 
     1209a "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. 
     1210If  \np[=.true.]{ln_loglayer}{ln\_loglayer}, $C_D$ is no longer constant but is related to the distance to the wall (or equivalently to the half of the top/bottom layer thickness): 
     1211\[ 
     1212  C_D = \left ( {\kappa \over {\mathrm log}\left ( 0.5 \; e_{3b} / rn\_{z0} \right ) } \right )^2 
     1213\] 
     1214 
     1215\noindent where $\kappa$ is the von-Karman constant and \np{rn_z0}{rn\_z0} is a roughness length provided via the namelist. 
     1216 
     1217The drag coefficient is bounded such that it is kept greater or equal to 
     1218the base \np{rn_Cd0}{rn\_Cd0} value which occurs where layer thicknesses become large and presumably logarithmic layers are not resolved at all. For stability reason, it is also not allowed to exceed the value of an additional namelist parameter: 
     1219\np{rn_Cdmax}{rn\_Cdmax}, \ie 
     1220\[ 
     1221  rn\_Cd0 \leq C_D \leq rn\_Cdmax 
     1222\] 
     1223 
     1224\noindent The log-layer enhancement can also be applied to the top boundary friction if 
     1225under ice-shelf cavities are activated (\np[=.true.]{ln_isfcav}{ln\_isfcav}). 
     1226%In this case, the relevant namelist parameters are \np{rn_tfrz0}{rn\_tfrz0}, \np{rn_tfri2}{rn\_tfri2} and \np{rn_tfri2_max}{rn\_tfri2\_max}. 
     1227 
     1228%% ================================================================================================= 
     1229\subsection[Explicit top/bottom friction (\forcode{ln_drgimp=.false.})]{Explicit top/bottom friction (\protect\np[=.false.]{ln_drgimp}{ln\_drgimp})} 
     1230\label{subsec:ZDF_drg_stability} 
     1231 
     1232Setting \np[=.false.]{ln_drgimp}{ln\_drgimp} means that bottom friction is treated explicitly in time, which has the advantage of simplifying the interaction with the split-explicit free surface (see \autoref{subsec:ZDF_drg_ts}). The latter does indeed require the knowledge of bottom stresses in the course of the barotropic sub-iteration, which becomes less straightforward in the implicit case. In the explicit case, top/bottom stresses can be computed using \textit{before} velocities and inserted in the overall momentum tendency budget. This reads: 
     1233 
     1234At the top (below an ice shelf cavity): 
     1235\[ 
     1236  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{t} 
     1237  = c_{t}^{\textbf{U}}\textbf{u}^{n-1}_{t} 
     1238\] 
     1239 
     1240At the bottom (above the sea floor): 
     1241\[ 
     1242  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{b} 
     1243  = c_{b}^{\textbf{U}}\textbf{u}^{n-1}_{b} 
     1244\] 
     1245 
     1246Since 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. 
     1247For the purposes of stability analysis, an approximation to \autoref{eq:ZDF_drg_flux2} is: 
    10691248\begin{equation} 
    1070   \label{eq:Eqn_bfrstab} 
     1249  \label{eq:ZDF_Eqn_drgstab} 
    10711250  \begin{split} 
    10721251    \Delta u &= -\frac{{{\cal F}_h}^u}{e_{3u}}\;2 \rdt    \\ 
     
    10741253  \end{split} 
    10751254\end{equation} 
    1076 \noindent where linear bottom friction and a leapfrog timestep have been assumed. 
    1077 To ensure that the bottom friction cannot reverse the direction of flow it is necessary to have: 
    1078 \[ 
    1079   |\Delta u| < \;|u|  
    1080 \] 
    1081 \noindent which, using \autoref{eq:Eqn_bfrstab}, gives: 
     1255\noindent where linear friction and a leapfrog timestep have been assumed. 
     1256To ensure that the friction cannot reverse the direction of flow it is necessary to have: 
     1257\[ 
     1258  |\Delta u| < \;|u| 
     1259\] 
     1260\noindent which, using \autoref{eq:ZDF_Eqn_drgstab}, gives: 
    10821261\[ 
    10831262  r\frac{2\rdt}{e_{3u}} < 1 \qquad  \Rightarrow \qquad r < \frac{e_{3u}}{2\rdt}\\ 
     
    10921271For example, if $|u| = 1$ m.s$^{-1}$, $rdt = 1800$ s, $r = 10^{-3}$ then $e_{3u}$ should be greater than 3.6 m. 
    10931272For most applications, with physically sensible parameters these restrictions should not be of concern. 
    1094 But caution may be necessary if attempts are made to locally enhance the bottom friction parameters.  
    1095 To ensure stability limits are imposed on the bottom friction coefficients both 
     1273But caution may be necessary if attempts are made to locally enhance the bottom friction parameters. 
     1274To ensure stability limits are imposed on the top/bottom friction coefficients both 
    10961275during initialisation and at each time step. 
    1097 Checks at initialisation are made in \mdl{zdfbfr} (assuming a 1 m.s$^{-1}$ velocity in the non-linear case). 
     1276Checks at initialisation are made in \mdl{zdfdrg} (assuming a 1 m.s$^{-1}$ velocity in the non-linear case). 
    10981277The number of breaches of the stability criterion are reported as well as 
    10991278the minimum and maximum values that have been set. 
    1100 The criterion is also checked at each time step, using the actual velocity, in \mdl{dynbfr}. 
    1101 Values of the bottom friction coefficient are reduced as necessary to ensure stability; 
     1279The criterion is also checked at each time step, using the actual velocity, in \mdl{dynzdf}. 
     1280Values of the friction coefficient are reduced as necessary to ensure stability; 
    11021281these changes are not reported. 
    11031282 
    1104 Limits on the bottom friction coefficient are not imposed if the user has elected to 
    1105 handle the bottom friction implicitly (see \autoref{subsec:ZDF_bfr_imp}). 
     1283Limits on the top/bottom friction coefficient are not imposed if the user has elected to 
     1284handle the friction implicitly (see \autoref{subsec:ZDF_drg_imp}). 
    11061285The number of potential breaches of the explicit stability criterion are still reported for information purposes. 
    11071286 
    1108 % ------------------------------------------------------------------------------------------------------------- 
    1109 %       Implicit Bottom Friction 
    1110 % ------------------------------------------------------------------------------------------------------------- 
    1111 \subsection{Implicit bottom friction (\protect\np{ln\_bfrimp}\forcode{ = .true.})} 
    1112 \label{subsec:ZDF_bfr_imp} 
     1287%% ================================================================================================= 
     1288\subsection[Implicit top/bottom friction (\forcode{ln_drgimp=.true.})]{Implicit top/bottom friction (\protect\np[=.true.]{ln_drgimp}{ln\_drgimp})} 
     1289\label{subsec:ZDF_drg_imp} 
    11131290 
    11141291An optional implicit form of bottom friction has been implemented to improve model stability. 
    1115 We recommend this option for shelf sea and coastal ocean applications, especially for split-explicit time splitting. 
    1116 This option can be invoked by setting \np{ln\_bfrimp} to \forcode{.true.} in the \textit{nambfr} namelist. 
    1117 This option requires \np{ln\_zdfexp} to be \forcode{.false.} in the \textit{namzdf} namelist.  
    1118  
    1119 This implementation is realised in \mdl{dynzdf\_imp} and \mdl{dynspg\_ts}. In \mdl{dynzdf\_imp}, 
    1120 the bottom boundary condition is implemented implicitly. 
    1121  
    1122 \[ 
    1123   % \label{eq:dynzdf_bfr} 
    1124   \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{mbk} 
    1125   = \binom{c_{b}^{u}u^{n+1}_{mbk}}{c_{b}^{v}v^{n+1}_{mbk}} 
    1126 \] 
    1127  
    1128 where $mbk$ is the layer number of the bottom wet layer. 
    1129 Superscript $n+1$ means the velocity used in the friction formula is to be calculated, so, it is implicit. 
    1130  
    1131 If split-explicit time splitting is used, care must be taken to avoid the double counting of the bottom friction in 
    1132 the 2-D barotropic momentum equations. 
    1133 As NEMO only updates the barotropic pressure gradient and Coriolis' forcing terms in the 2-D barotropic calculation, 
    1134 we need to remove the bottom friction induced by these two terms which has been included in the 3-D momentum trend  
    1135 and update it with the latest value. 
    1136 On the other hand, the bottom friction contributed by the other terms 
    1137 (\eg the advection term, viscosity term) has been included in the 3-D momentum equations and 
    1138 should not be added in the 2-D barotropic mode. 
    1139  
    1140 The implementation of the implicit bottom friction in \mdl{dynspg\_ts} is done in two steps as the following: 
    1141  
    1142 \[ 
    1143   % \label{eq:dynspg_ts_bfr1} 
    1144   \frac{\textbf{U}_{med}-\textbf{U}^{m-1}}{2\Delta t}=-g\nabla\eta-f\textbf{k}\times\textbf{U}^{m}+c_{b} 
    1145   \left(\textbf{U}_{med}-\textbf{U}^{m-1}\right) 
    1146 \] 
    1147 \[ 
    1148   \frac{\textbf{U}^{m+1}-\textbf{U}_{med}}{2\Delta t}=\textbf{T}+ 
    1149   \left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{U}^{'}\right)- 
    1150   2\Delta t_{bc}c_{b}\left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{u}_{b}\right) 
    1151 \] 
    1152  
    1153 where $\textbf{T}$ is the vertical integrated 3-D momentum trend. 
    1154 We assume the leap-frog time-stepping is used here. 
    1155 $\Delta t$ is the barotropic mode time step and $\Delta t_{bc}$ is the baroclinic mode time step. 
    1156 $c_{b}$ is the friction coefficient. 
    1157 $\eta$ is the sea surface level calculated in the barotropic loops while $\eta^{'}$ is the sea surface level used in 
    1158 the 3-D baroclinic mode. 
    1159 $\textbf{u}_{b}$ is the bottom layer horizontal velocity. 
    1160  
    1161 % ------------------------------------------------------------------------------------------------------------- 
    1162 %       Bottom Friction with split-explicit time splitting 
    1163 % ------------------------------------------------------------------------------------------------------------- 
    1164 \subsection[Bottom friction w/ split-explicit time splitting (\protect\np{ln\_bfrimp})] 
    1165             {Bottom friction with split-explicit time splitting (\protect\np{ln\_bfrimp})} 
    1166 \label{subsec:ZDF_bfr_ts} 
    1167  
    1168 When calculating the momentum trend due to bottom friction in \mdl{dynbfr}, 
    1169 the bottom velocity at the before time step is used. 
    1170 This velocity includes both the baroclinic and barotropic components which is appropriate when 
    1171 using either the explicit or filtered surface pressure gradient algorithms 
    1172 (\key{dynspg\_exp} or \key{dynspg\_flt}). 
    1173 Extra attention is required, however, when using split-explicit time stepping (\key{dynspg\_ts}). 
    1174 In this case the free surface equation is solved with a small time step \np{rn\_rdt}/\np{nn\_baro}, 
    1175 while the three dimensional prognostic variables are solved with the longer time step of \np{rn\_rdt} seconds. 
    1176 The trend in the barotropic momentum due to bottom friction appropriate to this method is that given by 
    1177 the selected parameterisation (\ie linear or non-linear bottom friction) computed with 
    1178 the evolving velocities at each barotropic timestep.  
    1179  
    1180 In the case of non-linear bottom friction, we have elected to partially linearise the problem by 
    1181 keeping the coefficients fixed throughout the barotropic time-stepping to those computed in 
    1182 \mdl{zdfbfr} using the now timestep. 
    1183 This decision allows an efficient use of the $c_b^{\vect{U}}$ coefficients to: 
    1184  
     1292We recommend this option for shelf sea and coastal ocean applications. %, especially for split-explicit time splitting. 
     1293This option can be invoked by setting \np{ln_drgimp}{ln\_drgimp} to \forcode{.true.} in the \nam{drg}{drg} namelist. 
     1294%This option requires \np{ln_zdfexp}{ln\_zdfexp} to be \forcode{.false.} in the \nam{zdf}{zdf} namelist. 
     1295 
     1296This implementation is performed in \mdl{dynzdf} where the following boundary conditions are set while solving the fully implicit diffusion step: 
     1297 
     1298At the top (below an ice shelf cavity): 
     1299\[ 
     1300  % \label{eq:ZDF_dynZDF__drg_top} 
     1301  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{t} 
     1302  = c_{t}^{\textbf{U}}\textbf{u}^{n+1}_{t} 
     1303\] 
     1304 
     1305At the bottom (above the sea floor): 
     1306\[ 
     1307  % \label{eq:ZDF_dynZDF__drg_bot} 
     1308  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{b} 
     1309  = c_{b}^{\textbf{U}}\textbf{u}^{n+1}_{b} 
     1310\] 
     1311 
     1312where $t$ and $b$ refers to top and bottom layers respectively. 
     1313Superscript $n+1$ means the velocity used in the friction formula is to be calculated, so it is implicit. 
     1314 
     1315%% ================================================================================================= 
     1316\subsection[Bottom friction with split-explicit free surface]{Bottom friction with split-explicit free surface} 
     1317\label{subsec:ZDF_drg_ts} 
     1318 
     1319With split-explicit free surface, the sub-stepping of barotropic equations needs the knowledge of top/bottom stresses. An obvious way to satisfy this is to take them as constant over the course of the barotropic integration and equal to the value used to update the baroclinic momentum trend. Provided \np[=.false.]{ln_drgimp}{ln\_drgimp} and a centred or \textit{leap-frog} like integration of barotropic equations is used (\ie\ \forcode{ln_bt_fw=.false.}, cf \autoref{subsec:DYN_spg_ts}), this does ensure that barotropic and baroclinic dynamics feel the same stresses during one leapfrog time step. However, if \np[=.true.]{ln_drgimp}{ln\_drgimp},  stresses depend on the \textit{after} value of the velocities which themselves depend on the barotropic iteration result. This cyclic dependency makes difficult obtaining consistent stresses in 2d and 3d dynamics. Part of this mismatch is then removed when setting the final barotropic component of 3d velocities to the time splitting estimate. This last step can be seen as a necessary evil but should be minimized since it interferes with the adjustment to the boundary conditions. 
     1320 
     1321The strategy to handle top/bottom stresses with split-explicit free surface in \NEMO\ is as follows: 
    11851322\begin{enumerate} 
    1186 \item On entry to \rou{dyn\_spg\_ts}, remove the contribution of the before barotropic velocity to 
    1187   the bottom friction component of the vertically integrated momentum trend. 
    1188   Note the same stability check that is carried out on the bottom friction coefficient in \mdl{dynbfr} has to 
    1189   be applied here to ensure that the trend removed matches that which was added in \mdl{dynbfr}. 
    1190 \item At each barotropic step, compute the contribution of the current barotropic velocity to 
    1191   the trend due to bottom friction. 
    1192   Add this contribution to the vertically integrated momentum trend. 
    1193   This contribution is handled implicitly which eliminates the need to impose a stability criteria on 
    1194   the values of the bottom friction coefficient within the barotropic loop.  
     1323\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. 
     1324\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. 
    11951325\end{enumerate} 
    11961326 
    1197 Note that the use of an implicit formulation within the barotropic loop for the bottom friction trend means that 
    1198 any limiting of the bottom friction coefficient in \mdl{dynbfr} does not adversely affect the solution when 
    1199 using split-explicit time splitting. 
    1200 This is because the major contribution to bottom friction is likely to come from the barotropic component which 
    1201 uses the unrestricted value of the coefficient. 
    1202 However, if the limiting is thought to be having a major effect 
    1203 (a more likely prospect in coastal and shelf seas applications) then 
    1204 the fully implicit form of the bottom friction should be used (see \autoref{subsec:ZDF_bfr_imp}) 
    1205 which can be selected by setting \np{ln\_bfrimp} $=$ \forcode{.true.}. 
    1206  
    1207 Otherwise, the implicit formulation takes the form: 
    1208 \[ 
    1209   % \label{eq:zdfbfr_implicitts} 
    1210   \bar{U}^{t+ \rdt} = \; \left [ \bar{U}^{t-\rdt}\; + 2 \rdt\;RHS \right ] / \left [ 1 - 2 \rdt \;c_b^{u} / H_e \right ] 
    1211 \] 
    1212 where $\bar U$ is the barotropic velocity, $H_e$ is the full depth (including sea surface height),  
    1213 $c_b^u$ is the bottom friction coefficient as calculated in \rou{zdf\_bfr} and 
    1214 $RHS$ represents all the components to the vertically integrated momentum trend except for 
    1215 that due to bottom friction. 
    1216  
    1217 % ================================================================ 
    1218 % Tidal Mixing 
    1219 % ================================================================ 
    1220 \section{Tidal mixing (\protect\key{zdftmx})} 
    1221 \label{sec:ZDF_tmx} 
    1222  
    1223 %--------------------------------------------namzdf_tmx-------------------------------------------------- 
    1224 % 
    1225 %\nlst{namzdf_tmx} 
    1226 %-------------------------------------------------------------------------------------------------------------- 
    1227  
    1228  
    1229 % ------------------------------------------------------------------------------------------------------------- 
    1230 %        Bottom intensified tidal mixing  
    1231 % ------------------------------------------------------------------------------------------------------------- 
    1232 \subsection{Bottom intensified tidal mixing} 
    1233 \label{subsec:ZDF_tmx_bottom} 
    1234  
    1235 Options are defined through the  \ngn{namzdf\_tmx} namelist variables. 
    1236 The parameterization of tidal mixing follows the general formulation for the vertical eddy diffusivity proposed by 
    1237 \citet{St_Laurent_al_GRL02} and first introduced in an OGCM by \citep{Simmons_al_OM04}.  
    1238 In this formulation an additional vertical diffusivity resulting from internal tide breaking, 
    1239 $A^{vT}_{tides}$ is expressed as a function of $E(x,y)$, 
    1240 the energy transfer from barotropic tides to baroclinic tides: 
    1241 \begin{equation} 
    1242   \label{eq:Ktides} 
    1243   A^{vT}_{tides} =  q \,\Gamma \,\frac{ E(x,y) \, F(z) }{ \rho \, N^2 } 
    1244 \end{equation} 
    1245 where $\Gamma$ is the mixing efficiency, $N$ the Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}), 
    1246 $\rho$ the density, $q$ the tidal dissipation efficiency, and $F(z)$ the vertical structure function.  
    1247  
    1248 The mixing efficiency of turbulence is set by $\Gamma$ (\np{rn\_me} namelist parameter) and 
    1249 is usually taken to be the canonical value of $\Gamma = 0.2$ (Osborn 1980).  
    1250 The tidal dissipation efficiency is given by the parameter $q$ (\np{rn\_tfe} namelist parameter) 
    1251 represents the part of the internal wave energy flux $E(x, y)$ that is dissipated locally, 
    1252 with the remaining $1-q$ radiating away as low mode internal waves and 
    1253 contributing to the background internal wave field. 
    1254 A value of $q=1/3$ is typically used \citet{St_Laurent_al_GRL02}. 
    1255 The vertical structure function $F(z)$ models the distribution of the turbulent mixing in the vertical. 
    1256 It is implemented as a simple exponential decaying upward away from the bottom, 
    1257 with a vertical scale of $h_o$ (\np{rn\_htmx} namelist parameter, 
    1258 with a typical value of $500\,m$) \citep{St_Laurent_Nash_DSR04},  
    1259 \[ 
    1260   % \label{eq:Fz} 
    1261   F(i,j,k) = \frac{ e^{ -\frac{H+z}{h_o} } }{ h_o \left( 1- e^{ -\frac{H}{h_o} } \right) } 
    1262 \] 
    1263 and is normalized so that vertical integral over the water column is unity.  
    1264  
    1265 The associated vertical viscosity is calculated from the vertical diffusivity assuming a Prandtl number of 1, 
    1266 \ie $A^{vm}_{tides}=A^{vT}_{tides}$. 
    1267 In the limit of $N \rightarrow 0$ (or becoming negative), the vertical diffusivity is capped at $300\,cm^2/s$ and 
    1268 impose a lower limit on $N^2$ of \np{rn\_n2min} usually set to $10^{-8} s^{-2}$. 
    1269 These bounds are usually rarely encountered. 
    1270  
    1271 The internal wave energy map, $E(x, y)$ in \autoref{eq:Ktides}, is derived from a barotropic model of 
    1272 the tides utilizing a parameterization of the conversion of barotropic tidal energy into internal waves. 
    1273 The essential goal of the parameterization is to represent the momentum exchange between the barotropic tides and 
    1274 the unrepresented internal waves induced by the tidal flow over rough topography in a stratified ocean. 
    1275 In the current version of \NEMO, the map is built from the output of 
    1276 the barotropic global ocean tide model MOG2D-G \citep{Carrere_Lyard_GRL03}. 
    1277 This model provides the dissipation associated with internal wave energy for the M2 and K1 tides component 
    1278 (\autoref{fig:ZDF_M2_K1_tmx}). 
    1279 The S2 dissipation is simply approximated as being $1/4$ of the M2 one. 
    1280 The internal wave energy is thus : $E(x, y) = 1.25 E_{M2} + E_{K1}$. 
    1281 Its global mean value is $1.1$ TW, 
    1282 in agreement with independent estimates \citep{Egbert_Ray_Nat00, Egbert_Ray_JGR01}.  
    1283  
    1284 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1285 \begin{figure}[!t] 
    1286   \begin{center} 
    1287     \includegraphics[width=0.90\textwidth]{Fig_ZDF_M2_K1_tmx} 
    1288     \caption{ 
    1289       \protect\label{fig:ZDF_M2_K1_tmx} 
    1290       (a) M2 and (b) K1 internal wave drag energy from \citet{Carrere_Lyard_GRL03} ($W/m^2$). 
    1291     } 
    1292   \end{center} 
    1293 \end{figure} 
    1294 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>  
    1295   
    1296 % ------------------------------------------------------------------------------------------------------------- 
    1297 %        Indonesian area specific treatment  
    1298 % ------------------------------------------------------------------------------------------------------------- 
    1299 \subsection{Indonesian area specific treatment (\protect\np{ln\_zdftmx\_itf})} 
    1300 \label{subsec:ZDF_tmx_itf} 
    1301  
    1302 When the Indonesian Through Flow (ITF) area is included in the model domain, 
    1303 a specific treatment of tidal induced mixing in this area can be used. 
    1304 It is activated through the namelist logical \np{ln\_tmx\_itf}, and the user must provide an input NetCDF file, 
    1305 \ifile{mask\_itf}, which contains a mask array defining the ITF area where the specific treatment is applied. 
    1306  
    1307 When \np{ln\_tmx\_itf}\forcode{ = .true.}, the two key parameters $q$ and $F(z)$ are adjusted following 
    1308 the parameterisation developed by \citet{Koch-Larrouy_al_GRL07}: 
    1309  
    1310 First, the Indonesian archipelago is a complex geographic region with a series of 
    1311 large, deep, semi-enclosed basins connected via numerous narrow straits. 
    1312 Once generated, internal tides remain confined within this semi-enclosed area and hardly radiate away. 
    1313 Therefore all the internal tides energy is consumed within this area. 
    1314 So it is assumed that $q = 1$, \ie all the energy generated is available for mixing. 
    1315 Note that for test purposed, the ITF tidal dissipation efficiency is a namelist parameter (\np{rn\_tfe\_itf}). 
    1316 A value of $1$ or close to is this recommended for this parameter. 
    1317  
    1318 Second, the vertical structure function, $F(z)$, is no more associated with a bottom intensification of the mixing, 
    1319 but with a maximum of energy available within the thermocline. 
    1320 \citet{Koch-Larrouy_al_GRL07} have suggested that the vertical distribution of 
    1321 the energy dissipation proportional to $N^2$ below the core of the thermocline and to $N$ above.  
    1322 The resulting $F(z)$ is: 
    1323 \[ 
    1324   % \label{eq:Fz_itf} 
    1325   F(i,j,k) \sim     \left\{ 
    1326     \begin{aligned} 
    1327       \frac{q\,\Gamma E(i,j) } {\rho N \, \int N     dz}    \qquad \text{when $\partial_z N < 0$} \\ 
    1328       \frac{q\,\Gamma E(i,j) } {\rho     \, \int N^2 dz}    \qquad \text{when $\partial_z N > 0$} 
    1329     \end{aligned} 
    1330   \right. 
    1331 \] 
    1332  
    1333 Averaged over the ITF area, the resulting tidal mixing coefficient is $1.5\,cm^2/s$,  
    1334 which agrees with the independent estimates inferred from observations. 
    1335 Introduced in a regional OGCM, the parameterization improves the water mass characteristics in 
    1336 the different Indonesian seas, suggesting that the horizontal and vertical distributions of 
    1337 the mixing are adequately prescribed \citep{Koch-Larrouy_al_GRL07, Koch-Larrouy_al_OD08a, Koch-Larrouy_al_OD08b}. 
    1338 Note also that such a parameterisation has a significant impact on the behaviour of 
    1339 global coupled GCMs \citep{Koch-Larrouy_al_CD10}. 
    1340  
    1341 % ================================================================ 
    1342 % Internal wave-driven mixing 
    1343 % ================================================================ 
    1344 \section{Internal wave-driven mixing (\protect\key{zdftmx\_new})} 
    1345 \label{sec:ZDF_tmx_new} 
    1346  
    1347 %--------------------------------------------namzdf_tmx_new------------------------------------------ 
    1348 % 
    1349 %\nlst{namzdf_tmx_new} 
    1350 %-------------------------------------------------------------------------------------------------------------- 
     1327Note that other strategies are possible, like considering vertical diffusion step in advance, \ie\ prior barotropic integration. 
     1328 
     1329%% ================================================================================================= 
     1330\section[Internal wave-driven mixing (\forcode{ln_zdfiwm})]{Internal wave-driven mixing (\protect\np{ln_zdfiwm}{ln\_zdfiwm})} 
     1331\label{subsec:ZDF_tmx_new} 
     1332 
     1333\begin{listing} 
     1334  \nlst{namzdf_iwm} 
     1335  \caption{\forcode{&namzdf_iwm}} 
     1336  \label{lst:namzdf_iwm} 
     1337\end{listing} 
    13511338 
    13521339The parameterization of mixing induced by breaking internal waves is a generalization of 
    1353 the approach originally proposed by \citet{St_Laurent_al_GRL02}. 
     1340the approach originally proposed by \citet{st-laurent.simmons.ea_GRL02}. 
    13541341A three-dimensional field of internal wave energy dissipation $\epsilon(x,y,z)$ is first constructed, 
    1355 and the resulting diffusivity is obtained as  
    1356 \[ 
    1357   % \label{eq:Kwave} 
     1342and the resulting diffusivity is obtained as 
     1343\[ 
     1344  % \label{eq:ZDF_Kwave} 
    13581345  A^{vT}_{wave} =  R_f \,\frac{ \epsilon }{ \rho \, N^2 } 
    13591346\] 
    13601347where $R_f$ is the mixing efficiency and $\epsilon$ is a specified three dimensional distribution of 
    13611348the energy available for mixing. 
    1362 If the \np{ln\_mevar} namelist parameter is set to false, the mixing efficiency is taken as constant and 
    1363 equal to 1/6 \citep{Osborn_JPO80}. 
     1349If the \np{ln_mevar}{ln\_mevar} namelist parameter is set to \forcode{.false.}, the mixing efficiency is taken as constant and 
     1350equal to 1/6 \citep{osborn_JPO80}. 
    13641351In the opposite (recommended) case, $R_f$ is instead a function of 
    13651352the turbulence intensity parameter $Re_b = \frac{ \epsilon}{\nu \, N^2}$, 
    1366 with $\nu$ the molecular viscosity of seawater, following the model of \cite{Bouffard_Boegman_DAO2013} and 
    1367 the implementation of \cite{de_lavergne_JPO2016_efficiency}. 
     1353with $\nu$ the molecular viscosity of seawater, following the model of \cite{bouffard.boegman_DAO13} and 
     1354the implementation of \cite{de-lavergne.madec.ea_JPO16}. 
    13681355Note that $A^{vT}_{wave}$ is bounded by $10^{-2}\,m^2/s$, a limit that is often reached when 
    13691356the mixing efficiency is constant. 
    13701357 
    1371 In addition to the mixing efficiency, the ratio of salt to heat diffusivities can chosen to vary  
    1372 as a function of $Re_b$ by setting the \np{ln\_tsdiff} parameter to true, a recommended choice.  
    1373 This parameterization of differential mixing, due to \cite{Jackson_Rehmann_JPO2014}, 
    1374 is implemented as in \cite{de_lavergne_JPO2016_efficiency}. 
     1358In addition to the mixing efficiency, the ratio of salt to heat diffusivities can chosen to vary 
     1359as a function of $Re_b$ by setting the \np{ln_tsdiff}{ln\_tsdiff} parameter to \forcode{.true.}, a recommended choice. 
     1360This parameterization of differential mixing, due to \cite{jackson.rehmann_JPO14}, 
     1361is implemented as in \cite{de-lavergne.madec.ea_JPO16}. 
    13751362 
    13761363The three-dimensional distribution of the energy available for mixing, $\epsilon(i,j,k)$, 
    13771364is constructed from three static maps of column-integrated internal wave energy dissipation, 
    1378 $E_{cri}(i,j)$, $E_{pyc}(i,j)$, and $E_{bot}(i,j)$, combined to three corresponding vertical structures 
    1379 (de Lavergne et al., in prep): 
     1365$E_{cri}(i,j)$, $E_{pyc}(i,j)$, and $E_{bot}(i,j)$, combined to three corresponding vertical structures: 
     1366 
    13801367\begin{align*} 
    13811368  F_{cri}(i,j,k) &\propto e^{-h_{ab} / h_{cri} }\\ 
    1382   F_{pyc}(i,j,k) &\propto N^{n\_p}\\ 
     1369  F_{pyc}(i,j,k) &\propto N^{n_p}\\ 
    13831370  F_{bot}(i,j,k) &\propto N^2 \, e^{- h_{wkb} / h_{bot} } 
    1384 \end{align*}  
     1371\end{align*} 
    13851372In the above formula, $h_{ab}$ denotes the height above bottom, 
    13861373$h_{wkb}$ denotes the WKB-stretched height above bottom, defined by 
     
    13881375  h_{wkb} = H \, \frac{ \int_{-H}^{z} N \, dz' } { \int_{-H}^{\eta} N \, dz'  } \; , 
    13891376\] 
    1390 The $n_p$ parameter (given by \np{nn\_zpyc} in \ngn{namzdf\_tmx\_new} namelist) 
     1377The $n_p$ parameter (given by \np{nn_zpyc}{nn\_zpyc} in \nam{zdf_iwm}{zdf\_iwm} namelist) 
    13911378controls the stratification-dependence of the pycnocline-intensified dissipation. 
    1392 It can take values of 1 (recommended) or 2. 
     1379It can take values of $1$ (recommended) or $2$. 
    13931380Finally, the vertical structures $F_{cri}$ and $F_{bot}$ require the specification of 
    13941381the decay scales $h_{cri}(i,j)$ and $h_{bot}(i,j)$, which are defined by two additional input maps. 
    13951382$h_{cri}$ is related to the large-scale topography of the ocean (etopo2) and 
    13961383$h_{bot}$ is a function of the energy flux $E_{bot}$, the characteristic horizontal scale of 
    1397 the abyssal hill topography \citep{Goff_JGR2010} and the latitude. 
    1398  
    1399 % ================================================================ 
    1400  
    1401 \biblio 
    1402  
    1403 \pindex 
     1384the abyssal hill topography \citep{goff_JGR10} and the latitude. 
     1385% Jc: input files names ? 
     1386 
     1387%% ================================================================================================= 
     1388\section[Surface wave-induced mixing (\forcode{ln_zdfswm})]{Surface wave-induced mixing (\protect\np{ln_zdfswm}{ln\_zdfswm})} 
     1389\label{subsec:ZDF_swm} 
     1390 
     1391Surface waves produce an enhanced mixing through wave-turbulence interaction. 
     1392In addition to breaking waves induced turbulence (\autoref{subsec:ZDF_tke}), 
     1393the influence of non-breaking waves can be accounted introducing 
     1394wave-induced viscosity and diffusivity as a function of the wave number spectrum. 
     1395Following \citet{qiao.yuan.ea_OD10}, a formulation of wave-induced mixing coefficient 
     1396is provided  as a function of wave amplitude, Stokes Drift and wave-number: 
     1397 
     1398\begin{equation} 
     1399  \label{eq:ZDF_Bv} 
     1400  B_{v} = \alpha {A} {U}_{st} {exp(3kz)} 
     1401\end{equation} 
     1402 
     1403Where $B_{v}$ is the wave-induced mixing coefficient, $A$ is the wave amplitude, 
     1404${U}_{st}$ is the Stokes Drift velocity, $k$ is the wave number and $\alpha$ 
     1405is a constant which should be determined by observations or 
     1406numerical experiments and is set to be 1. 
     1407 
     1408The coefficient $B_{v}$ is then directly added to the vertical viscosity 
     1409and diffusivity coefficients. 
     1410 
     1411In order to account for this contribution set: \forcode{ln_zdfswm=.true.}, 
     1412then wave interaction has to be activated through \forcode{ln_wave=.true.}, 
     1413the Stokes Drift can be evaluated by setting \forcode{ln_sdw=.true.} 
     1414(see \autoref{subsec:SBC_wave_sdw}) 
     1415and the needed wave fields can be provided either in forcing or coupled mode 
     1416(for more information on wave parameters and settings see \autoref{sec:SBC_wave}) 
     1417 
     1418%% ================================================================================================= 
     1419\section[Adaptive-implicit vertical advection (\forcode{ln_zad_Aimp})]{Adaptive-implicit vertical advection(\protect\np{ln_zad_Aimp}{ln\_zad\_Aimp})} 
     1420\label{subsec:ZDF_aimp} 
     1421 
     1422The adaptive-implicit vertical advection option in NEMO is based on the work of 
     1423\citep{shchepetkin_OM15}.  In common with most ocean models, the timestep used with NEMO 
     1424needs to satisfy multiple criteria associated with different physical processes in order 
     1425to maintain numerical stability. \citep{shchepetkin_OM15} pointed out that the vertical 
     1426CFL criterion is commonly the most limiting. \citep{lemarie.debreu.ea_OM15} examined the 
     1427constraints for a range of time and space discretizations and provide the CFL stability 
     1428criteria for a range of advection schemes. The values for the Leap-Frog with Robert 
     1429asselin filter time-stepping (as used in NEMO) are reproduced in 
     1430\autoref{tab:ZDF_zad_Aimp_CFLcrit}. Treating the vertical advection implicitly can avoid these 
     1431restrictions but at the cost of large dispersive errors and, possibly, large numerical 
     1432viscosity. The adaptive-implicit vertical advection option provides a targetted use of the 
     1433implicit scheme only when and where potential breaches of the vertical CFL condition 
     1434occur. In many practical applications these events may occur remote from the main area of 
     1435interest or due to short-lived conditions such that the extra numerical diffusion or 
     1436viscosity does not greatly affect the overall solution. With such applications, setting: 
     1437\forcode{ln_zad_Aimp=.true.} should allow much longer model timesteps to be used whilst 
     1438retaining the accuracy of the high order explicit schemes over most of the domain. 
     1439 
     1440\begin{table}[htbp] 
     1441  \centering 
     1442  % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}} 
     1443  \begin{tabular}{r|ccc} 
     1444    \hline 
     1445    spatial discretization  & 2$^nd$ order centered & 3$^rd$ order upwind & 4$^th$ order compact \\ 
     1446    advective CFL criterion &                 0.904 &              0.472  &                0.522 \\ 
     1447    \hline 
     1448  \end{tabular} 
     1449  \caption[Advective CFL criteria for the leapfrog with Robert Asselin filter time-stepping]{ 
     1450    The advective CFL criteria for a range of spatial discretizations for 
     1451    the leapfrog with Robert Asselin filter time-stepping 
     1452    ($\nu=0.1$) as given in \citep{lemarie.debreu.ea_OM15}.} 
     1453  \label{tab:ZDF_zad_Aimp_CFLcrit} 
     1454\end{table} 
     1455 
     1456In particular, the advection scheme remains explicit everywhere except where and when 
     1457local vertical velocities exceed a threshold set just below the explicit stability limit. 
     1458Once the threshold is reached a tapered transition towards an implicit scheme is used by 
     1459partitioning the vertical velocity into a part that can be treated explicitly and any 
     1460excess that must be treated implicitly. The partitioning is achieved via a Courant-number 
     1461dependent weighting algorithm as described in \citep{shchepetkin_OM15}. 
     1462 
     1463The local cell Courant number ($Cu$) used for this partitioning is: 
     1464 
     1465\begin{equation} 
     1466  \label{eq:ZDF_Eqn_zad_Aimp_Courant} 
     1467  \begin{split} 
     1468    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 ]    \\ 
     1469       &\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 ] 
     1470                     \big / e_{{1_t}ij}e_{{2_t}ij}            \\ 
     1471       &\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 ] 
     1472                     \big / e_{{1_t}ij}e_{{2_t}ij} \bigg )    \\ 
     1473  \end{split} 
     1474\end{equation} 
     1475 
     1476\noindent and the tapering algorithm follows \citep{shchepetkin_OM15} as: 
     1477 
     1478\begin{align} 
     1479  \label{eq:ZDF_Eqn_zad_Aimp_partition} 
     1480Cu_{min} &= 0.15 \nonumber \\ 
     1481Cu_{max} &= 0.3  \nonumber \\ 
     1482Cu_{cut} &= 2Cu_{max} - Cu_{min} \nonumber \\ 
     1483Fcu    &= 4Cu_{max}*(Cu_{max}-Cu_{min}) \nonumber \\ 
     1484\cf &= 
     1485     \begin{cases} 
     1486        0.0                                                        &\text{if $Cu \leq Cu_{min}$} \\ 
     1487        (Cu - Cu_{min})^2 / (Fcu +  (Cu - Cu_{min})^2)             &\text{else if $Cu < Cu_{cut}$} \\ 
     1488        (Cu - Cu_{max}) / Cu                                       &\text{else} 
     1489     \end{cases} 
     1490\end{align} 
     1491 
     1492\begin{figure}[!t] 
     1493  \centering 
     1494  \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_coeff} 
     1495  \caption[Partitioning coefficient used to partition vertical velocities into parts]{ 
     1496    The value of the partitioning coefficient (\cf) used to partition vertical velocities into 
     1497    parts to be treated implicitly and explicitly for a range of typical Courant numbers 
     1498    (\forcode{ln_zad_Aimp=.true.}).} 
     1499  \label{fig:ZDF_zad_Aimp_coeff} 
     1500\end{figure} 
     1501 
     1502\noindent The partitioning coefficient is used to determine the part of the vertical 
     1503velocity that must be handled implicitly ($w_i$) and to subtract this from the total 
     1504vertical velocity ($w_n$) to leave that which can continue to be handled explicitly: 
     1505 
     1506\begin{align} 
     1507  \label{eq:ZDF_Eqn_zad_Aimp_partition2} 
     1508    w_{i_{ijk}} &= \cf_{ijk} w_{n_{ijk}}     \nonumber \\ 
     1509    w_{n_{ijk}} &= (1-\cf_{ijk}) w_{n_{ijk}} 
     1510\end{align} 
     1511 
     1512\noindent Note that the coefficient is such that the treatment is never fully implicit; 
     1513the three cases from \autoref{eq:ZDF_Eqn_zad_Aimp_partition} can be considered as: 
     1514fully-explicit; mixed explicit/implicit and mostly-implicit.  With the settings shown the 
     1515coefficient (\cf) varies as shown in \autoref{fig:ZDF_zad_Aimp_coeff}. Note with these values 
     1516the $Cu_{cut}$ boundary between the mixed implicit-explicit treatment and 'mostly 
     1517implicit' is 0.45 which is just below the stability limited given in 
     1518\autoref{tab:ZDF_zad_Aimp_CFLcrit}  for a 3rd order scheme. 
     1519 
     1520The $w_i$ component is added to the implicit solvers for the vertical mixing in 
     1521\mdl{dynzdf} and \mdl{trazdf} in a similar way to \citep{shchepetkin_OM15}.  This is 
     1522sufficient for the flux-limited advection scheme (\forcode{ln_traadv_mus}) but further 
     1523intervention is required when using the flux-corrected scheme (\forcode{ln_traadv_fct}). 
     1524For these schemes the implicit upstream fluxes must be added to both the monotonic guess 
     1525and to the higher order solution when calculating the antidiffusive fluxes. The implicit 
     1526vertical fluxes are then removed since they are added by the implicit solver later on. 
     1527 
     1528The adaptive-implicit vertical advection option is new to NEMO at v4.0 and has yet to be 
     1529used in a wide range of simulations. The following test simulation, however, does illustrate 
     1530the potential benefits and will hopefully encourage further testing and feedback from users: 
     1531 
     1532\begin{figure}[!t] 
     1533  \centering 
     1534  \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_overflow_frames} 
     1535  \caption[OVERFLOW: time-series of temperature vertical cross-sections]{ 
     1536    A time-series of temperature vertical cross-sections for the OVERFLOW test case. 
     1537    These results are for the default settings with \forcode{nn_rdt=10.0} and 
     1538    without adaptive implicit vertical advection (\forcode{ln_zad_Aimp=.false.}).} 
     1539  \label{fig:ZDF_zad_Aimp_overflow_frames} 
     1540\end{figure} 
     1541 
     1542%% ================================================================================================= 
     1543\subsection{Adaptive-implicit vertical advection in the OVERFLOW test-case} 
     1544 
     1545The \href{https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/guide/html/test\_cases.html\#overflow}{OVERFLOW test case} 
     1546provides a simple illustration of the adaptive-implicit advection in action. The example here differs from the basic test case 
     1547by only a few extra physics choices namely: 
     1548 
     1549\begin{verbatim} 
     1550     ln_dynldf_OFF = .false. 
     1551     ln_dynldf_lap = .true. 
     1552     ln_dynldf_hor = .true. 
     1553     ln_zdfnpc     = .true. 
     1554     ln_traadv_fct = .true. 
     1555        nn_fct_h   =  2 
     1556        nn_fct_v   =  2 
     1557\end{verbatim} 
     1558 
     1559\noindent which were chosen to provide a slightly more stable and less noisy solution. The 
     1560result when using the default value of \forcode{nn_rdt=10.} without adaptive-implicit 
     1561vertical velocity is illustrated in \autoref{fig:ZDF_zad_Aimp_overflow_frames}. The mass of 
     1562cold water, initially sitting on the shelf, moves down the slope and forms a 
     1563bottom-trapped, dense plume. Even with these extra physics choices the model is close to 
     1564stability limits and attempts with \forcode{nn_rdt=30.} will fail after about 5.5 hours 
     1565with excessively high horizontal velocities. This time-scale corresponds with the time the 
     1566plume reaches the steepest part of the topography and, although detected as a horizontal 
     1567CFL breach, the instability originates from a breach of the vertical CFL limit. This is a good 
     1568candidate, therefore, for use of the adaptive-implicit vertical advection scheme. 
     1569 
     1570The results with \forcode{ln_zad_Aimp=.true.} and a variety of model timesteps 
     1571are shown in \autoref{fig:ZDF_zad_Aimp_overflow_all_rdt} (together with the equivalent 
     1572frames from the base run).  In this simple example the use of the adaptive-implicit 
     1573vertcal advection scheme has enabled a 12x increase in the model timestep without 
     1574significantly altering the solution (although at this extreme the plume is more diffuse 
     1575and has not travelled so far).  Notably, the solution with and without the scheme is 
     1576slightly different even with \forcode{nn_rdt=10.}; suggesting that the base run was 
     1577close enough to instability to trigger the scheme despite completing successfully. 
     1578To assist in diagnosing how active the scheme is, in both location and time, the 3D 
     1579implicit and explicit components of the vertical velocity are available via XIOS as 
     1580\texttt{wimp} and \texttt{wexp} respectively.  Likewise, the partitioning coefficient 
     1581(\cf) is also available as \texttt{wi\_cff}. For a quick oversight of 
     1582the schemes activity the global maximum values of the absolute implicit component 
     1583of the vertical velocity and the partitioning coefficient are written to the netCDF 
     1584version of the run statistics file (\texttt{run.stat.nc}) if this is active (see 
     1585\autoref{sec:MISC_opt} for activation details). 
     1586 
     1587\autoref{fig:ZDF_zad_Aimp_maxCf} shows examples of the maximum partitioning coefficient for 
     1588the various overflow tests.  Note that the adaptive-implicit vertical advection scheme is 
     1589active even in the base run with \forcode{nn_rdt=10.0s} adding to the evidence that the 
     1590test case is close to stability limits even with this value. At the larger timesteps, the 
     1591vertical velocity is treated mostly implicitly at some location throughout the run. The 
     1592oscillatory nature of this measure appears to be linked to the progress of the plume front 
     1593as each cusp is associated with the location of the maximum shifting to the adjacent cell. 
     1594This is illustrated in \autoref{fig:ZDF_zad_Aimp_maxCf_loc} where the i- and k- locations of the 
     1595maximum have been overlaid for the base run case. 
     1596 
     1597\medskip 
     1598\noindent Only limited tests have been performed in more realistic configurations. In the 
     1599ORCA2\_ICE\_PISCES reference configuration the scheme does activate and passes 
     1600restartability and reproducibility tests but it is unable to improve the model's stability 
     1601enough to allow an increase in the model time-step. A view of the time-series of maximum 
     1602partitioning coefficient (not shown here)  suggests that the default time-step of 5400s is 
     1603already pushing at stability limits, especially in the initial start-up phase. The 
     1604time-series does not, however, exhibit any of the 'cuspiness' found with the overflow 
     1605tests. 
     1606 
     1607\medskip 
     1608\noindent A short test with an eORCA1 configuration promises more since a test using a 
     1609time-step of 3600s remains stable with \forcode{ln_zad_Aimp=.true.} whereas the 
     1610time-step is limited to 2700s without. 
     1611 
     1612\begin{figure}[!t] 
     1613  \centering 
     1614  \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_overflow_all_rdt} 
     1615  \caption[OVERFLOW: sample temperature vertical cross-sections from mid- and end-run]{ 
     1616    Sample temperature vertical cross-sections from mid- and end-run using 
     1617    different values for \forcode{nn_rdt} and with or without adaptive implicit vertical advection. 
     1618    Without the adaptive implicit vertical advection 
     1619    only the run with the shortest timestep is able to run to completion. 
     1620    Note also that the colour-scale has been chosen to confirm that 
     1621    temperatures remain within the original range of 10$^o$ to 20$^o$.} 
     1622  \label{fig:ZDF_zad_Aimp_overflow_all_rdt} 
     1623\end{figure} 
     1624 
     1625\begin{figure}[!t] 
     1626  \centering 
     1627  \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_maxCf} 
     1628  \caption[OVERFLOW: maximum partitioning coefficient during a series of test runs]{ 
     1629    The maximum partitioning coefficient during a series of test runs with 
     1630    increasing model timestep length. 
     1631    At the larger timesteps, 
     1632    the vertical velocity is treated mostly implicitly at some location throughout the run.} 
     1633  \label{fig:ZDF_zad_Aimp_maxCf} 
     1634\end{figure} 
     1635 
     1636\begin{figure}[!t] 
     1637  \centering 
     1638  \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_maxCf_loc} 
     1639  \caption[OVERFLOW: maximum partitioning coefficient for the case overlaid]{ 
     1640    The maximum partitioning coefficient for the \forcode{nn_rdt=10.0} case overlaid with 
     1641    information on the gridcell i- and k-locations of the maximum value.} 
     1642  \label{fig:ZDF_zad_Aimp_maxCf_loc} 
     1643\end{figure} 
     1644 
     1645\subinc{\input{../../global/epilogue}} 
    14041646 
    14051647\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_conservation.tex

    r10442 r11831  
    33\begin{document} 
    44 
    5 % ================================================================ 
    6 % Invariant of the Equations 
    7 % ================================================================ 
    85\chapter{Invariants of the Primitive Equations} 
    9 \label{chap:Invariant} 
    10 \minitoc 
     6\label{chap:CONS} 
     7 
     8\thispagestyle{plain} 
     9 
     10\chaptertoc 
     11 
     12\paragraph{Changes record} ~\\ 
     13 
     14{\footnotesize 
     15  \begin{tabularx}{\textwidth}{l||X|X} 
     16    Release & Author(s) & Modifications \\ 
     17    \hline 
     18    {\em   4.0} & {\em ...} & {\em ...} \\ 
     19    {\em   3.6} & {\em ...} & {\em ...} \\ 
     20    {\em   3.4} & {\em ...} & {\em ...} \\ 
     21    {\em <=3.4} & {\em ...} & {\em ...} 
     22  \end{tabularx} 
     23} 
     24 
     25\clearpage 
    1126 
    1227The continuous equations of motion have many analytic properties. 
     
    2136horizontal kinetic energy and/or potential enstrophy of horizontally non-divergent flow, 
    2237and variance of temperature and salinity will be conserved in the absence of dissipative effects and forcing. 
    23 \citet{Arakawa1966} has first pointed out the advantage of this approach. 
     38\citet{arakawa_JCP66} has first pointed out the advantage of this approach. 
    2439He showed that if integral constraints on energy are maintained, 
    2540the computation will be free of the troublesome "non linear" instability originally pointed out by 
    26 \citet{Phillips1959}. 
     41\citet{phillips_TAMS59}. 
    2742A consistent formulation of the energetic properties is also extremely important in carrying out 
    2843long-term numerical simulations for an oceanographic model. 
    29 Such a formulation avoids systematic errors that accumulate with time \citep{Bryan1997}. 
     44Such a formulation avoids systematic errors that accumulate with time \citep{bryan_JCP97}. 
    3045 
    3146The general philosophy of OPA which has led to the discrete formulation presented in {\S}II.2 and II.3 is to 
     
    3550The alternative is to use diffusive schemes such as upstream or flux corrected schemes. 
    3651This last option was rejected because we prefer a complete handling of the model diffusion, 
    37 \ie of the model physics rather than letting the advective scheme produces its own implicit diffusion without 
     52\ie\ of the model physics rather than letting the advective scheme produces its own implicit diffusion without 
    3853controlling the space and time structure of this implicit diffusion. 
    3954Note that in some very specific cases as passive tracer studies, the positivity of the advective scheme is required. 
    4055In that case, and in that case only, the advective scheme used for passive tracer is a flux correction scheme 
    41 \citep{Marti1992, Levy1996, Levy1998}. 
    42  
    43 % ------------------------------------------------------------------------------------------------------------- 
    44 %       Conservation Properties on Ocean Dynamics 
    45 % ------------------------------------------------------------------------------------------------------------- 
     56\citep{Marti1992?, Levy1996?, Levy1998?}. 
     57 
     58%% ================================================================================================= 
    4659\section{Conservation properties on ocean dynamics} 
    47 \label{sec:Invariant_dyn} 
     60\label{sec:CONS_Invariant_dyn} 
    4861 
    4962The non linear term of the momentum equations has been split into a vorticity term, 
     
    6376The continuous formulation of the vorticity term satisfies following integral constraints: 
    6477\[ 
    65   % \label{eq:vor_vorticity} 
     78  % \label{eq:CONS_vor_vorticity} 
    6679  \int_D {{\textbf {k}}\cdot \frac{1}{e_3 }\nabla \times \left( {\varsigma 
    67         \;{\rm {\bf k}}\times {\textbf {U}}_h } \right)\;dv} =0 
    68 \] 
    69  
    70 \[ 
    71   % \label{eq:vor_enstrophy} 
     80        \;{\mathrm {\mathbf k}}\times {\textbf {U}}_h } \right)\;dv} =0 
     81\] 
     82 
     83\[ 
     84  % \label{eq:CONS_vor_enstrophy} 
    7285  if\quad \chi =0\quad \quad \int\limits_D {\varsigma \;{\textbf{k}}\cdot 
    7386    \frac{1}{e_3 }\nabla \times \left( {\varsigma {\textbf{k}}\times {\textbf{U}}_h } \right)\;dv} =-\int\limits_D {\frac{1}{2}\varsigma ^2\,\chi \;dv} 
     
    7689 
    7790\[ 
    78   % \label{eq:vor_energy} 
     91  % \label{eq:CONS_vor_energy} 
    7992  \int_D {{\textbf{U}}_h \times \left( {\varsigma \;{\textbf{k}}\times {\textbf{U}}_h } \right)\;dv} =0 
    8093\] 
     
    88101Using the symmetry or anti-symmetry properties of the operators (Eqs II.1.10 and 11), 
    89102it can be shown that the scheme (II.2.11) satisfies (II.4.1b) but not (II.4.1c), 
    90 while scheme (II.2.12) satisfies (II.4.1c) but not (II.4.1b) (see appendix C).  
     103while scheme (II.2.12) satisfies (II.4.1c) but not (II.4.1b) (see appendix C). 
    91104Note that the enstrophy conserving scheme on total vorticity has been chosen as the standard discrete form of 
    92105the vorticity term. 
     
    102115the horizontal gradient of horizontal kinetic energy: 
    103116 
    104 \begin{equation} \label{eq:keg_zad} 
    105 \int_D {{\textbf{U}}_h \cdot \nabla _h \left( {1/2\;{\textbf{U}}_h ^2} \right)\;dv} =-\int_D {{\textbf{U}}_h \cdot \frac{w}{e_3 }\;\frac{\partial  
     117\begin{equation} \label{eq:CONS_keg_zad} 
     118\int_D {{\textbf{U}}_h \cdot \nabla _h \left( {1/2\;{\textbf{U}}_h ^2} \right)\;dv} =-\int_D {{\textbf{U}}_h \cdot \frac{w}{e_3 }\;\frac{\partial 
    106119{\textbf{U}}_h }{\partial k}\;dv} 
    107120\end{equation} 
    108121 
    109122Using the discrete form given in {\S}II.2-a and the symmetry or anti-symmetry properties of 
    110 the mean and difference operators, \autoref{eq:keg_zad} is demonstrated in the Appendix C. 
    111 The main point here is that satisfying \autoref{eq:keg_zad} links the choice of the discrete forms of 
     123the mean and difference operators, \autoref{eq:CONS_keg_zad} is demonstrated in the Appendix C. 
     124The main point here is that satisfying \autoref{eq:CONS_keg_zad} links the choice of the discrete forms of 
    112125the vertical advection and of the horizontal gradient of horizontal kinetic energy. 
    113126Choosing one imposes the other. 
     
    122135This properties is satisfied locally with the choice of discretization we have made (property (II.1.9)~). 
    123136In addition, when the equation of state is linear 
    124 (\ie when an advective-diffusive equation for density can be derived from those of temperature and salinity) 
     137(\ie\ when an advective-diffusive equation for density can be derived from those of temperature and salinity) 
    125138the change of horizontal kinetic energy due to the work of pressure forces is balanced by the change of 
    126139potential energy due to buoyancy forces: 
    127140 
    128141\[ 
    129   % \label{eq:hpg_pe} 
     142  % \label{eq:CONS_hpg_pe} 
    130143  \int_D {-\frac{1}{\rho_o }\left. {\nabla p^h} \right|_z \cdot {\textbf {U}}_h \;dv} \;=\;\int_D {\nabla .\left( {\rho \,{\textbf{U}}} \right)\;g\;z\;\;dv} 
    131144\] 
     
    133146Using the discrete form given in {\S}~II.2-a and the symmetry or anti-symmetry properties of 
    134147the mean and difference operators, (II.4.3) is demonstrated in the Appendix C. 
    135 The main point here is that satisfying (II.4.3) strongly constraints the discrete expression of the depth of  
     148The main point here is that satisfying (II.4.3) strongly constraints the discrete expression of the depth of 
    136149$T$-points and of the term added to the pressure gradient in $s-$coordinates: the depth of a $T$-point, $z_T$, 
    137150is defined as the sum the vertical scale factors at $w$-points starting from the surface. 
     
    145158Nevertheless, the $\psi$-equation is solved numerically by an iterative solver (see {\S}~III.5), 
    146159thus the property is only satisfied with the accuracy required on the solver. 
    147 In addition, with the rigid-lid approximation, the change of horizontal kinetic energy due to the work of  
     160In addition, with the rigid-lid approximation, the change of horizontal kinetic energy due to the work of 
    148161surface pressure forces is exactly zero: 
    149162\[ 
    150   % \label{eq:spg} 
     163  % \label{eq:CONS_spg} 
    151164  \int_D {-\frac{1}{\rho_o }\nabla _h } \left( {p_s } \right)\cdot {\textbf{U}}_h \;dv=0 
    152165\] 
     
    157170otherwise there is no guarantee that the surface pressure force work vanishes. 
    158171 
    159 % ------------------------------------------------------------------------------------------------------------- 
    160 %       Conservation Properties on Ocean Thermodynamics 
    161 % ------------------------------------------------------------------------------------------------------------- 
     172%% ================================================================================================= 
    162173\section{Conservation properties on ocean thermodynamics} 
    163 \label{sec:Invariant_tra} 
     174\label{sec:CONS_Invariant_tra} 
    164175 
    165176In continuous formulation, the advective terms of the tracer equations conserve the tracer content and 
    166177the quadratic form of the tracer, \ie 
    167178\[ 
    168   % \label{eq:tra_tra2} 
     179  % \label{eq:CONS_tra_tra2} 
    169180  \int_D {\nabla .\left( {T\;{\textbf{U}}} \right)\;dv} =0 
    170181  \;\text{and} 
     
    176187Note that in both continuous and discrete formulations, there is generally no strict conservation of mass, 
    177188since the equation of state is non linear with respect to $T$ and $S$. 
    178 In practice, the mass is conserved with a very good accuracy.  
    179  
    180 % ------------------------------------------------------------------------------------------------------------- 
    181 %       Conservation Properties on Momentum Physics 
    182 % ------------------------------------------------------------------------------------------------------------- 
     189In practice, the mass is conserved with a very good accuracy. 
     190 
     191%% ================================================================================================= 
    183192\subsection{Conservation properties on momentum physics} 
    184 \label{subsec:Invariant_dyn_physics} 
     193\label{subsec:CONS_Invariant_dyn_physics} 
    185194 
    186195\textbf{* lateral momentum diffusion term} 
     
    188197The continuous formulation of the horizontal diffusion of momentum satisfies the following integral constraints~: 
    189198\[ 
    190   % \label{eq:dynldf_dyn} 
    191   \int\limits_D {\frac{1}{e_3 }{\rm {\bf k}}\cdot \nabla \times \left[ {\nabla 
     199  % \label{eq:CONS_dynldf_dyn} 
     200  \int\limits_D {\frac{1}{e_3 }{\mathrm {\mathbf k}}\cdot \nabla \times \left[ {\nabla 
    192201        _h \left( {A^{lm}\;\chi } \right)-\nabla _h \times \left( {A^{lm}\;\zeta 
    193             \;{\rm {\bf k}}} \right)} \right]\;dv} =0 
    194 \] 
    195  
    196 \[ 
    197   % \label{eq:dynldf_div} 
     202            \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} =0 
     203\] 
     204 
     205\[ 
     206  % \label{eq:CONS_dynldf_div} 
    198207  \int\limits_D {\nabla _h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi } 
    199         \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} 
     208        \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} 
    200209    \right]\;dv} =0 
    201210\] 
    202211 
    203212\[ 
    204   % \label{eq:dynldf_curl} 
    205   \int_D {{\rm {\bf U}}_h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi } 
    206         \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} 
     213  % \label{eq:CONS_dynldf_curl} 
     214  \int_D {{\mathrm {\mathbf U}}_h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi } 
     215        \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} 
    207216    \right]\;dv} \leqslant 0 
    208217\] 
    209218 
    210219\[ 
    211   % \label{eq:dynldf_curl2} 
    212   \mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\zeta \;{\rm {\bf k}}\cdot 
     220  % \label{eq:CONS_dynldf_curl2} 
     221  \mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\zeta \;{\mathrm {\mathbf k}}\cdot 
    213222    \nabla \times \left[ {\nabla _h \left( {A^{lm}\;\chi } \right)-\nabla _h 
    214         \times \left( {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} \right]\;dv} 
     223        \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} 
    215224  \leqslant 0 
    216225\] 
    217226 
    218227\[ 
    219   % \label{eq:dynldf_div2} 
     228  % \label{eq:CONS_dynldf_div2} 
    220229  \mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\chi \;\nabla _h \cdot \left[ 
    221230      {\nabla _h \left( {A^{lm}\;\chi } \right)-\nabla _h \times \left( 
    222           {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} \right]\;dv} \leqslant 0 
    223 \] 
    224  
     231          {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} \leqslant 0 
     232\] 
    225233 
    226234(II.4.6a) and (II.4.6b) means that the horizontal diffusion of momentum conserve both the potential vorticity and 
     
    250258 
    251259\[ 
    252   % \label{eq:dynzdf_dyn} 
     260  % \label{eq:CONS_dynzdf_dyn} 
    253261  \begin{aligned} 
    254262    & \int_D {\frac{1}{e_3 }}  \frac{\partial }{\partial k}\left( \frac{A^{vm}}{e_3 }\frac{\partial {\textbf{U}}_h }{\partial k} \right) \;dv = \overrightarrow{\textbf{0}} \\ 
     
    258266conservation of vorticity, dissipation of enstrophy 
    259267\[ 
    260   % \label{eq:dynzdf_vor} 
    261   \begin{aligned} 
    262     & \int_D {\frac{1}{e_3 }{\rm {\bf k}}\cdot \nabla \times \left( {\frac{1}{e_3 
    263           }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm 
    264                   {\bf U}}_h }{\partial k}} \right)} \right)\;dv} =0 \\ 
    265     & \int_D {\zeta \,{\rm {\bf k}}\cdot \nabla \times \left( {\frac{1}{e_3 
    266           }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm 
    267                   {\bf U}}_h }{\partial k}} \right)} \right)\;dv} \leq 0 \\ 
     268  % \label{eq:CONS_dynzdf_vor} 
     269  \begin{aligned} 
     270    & \int_D {\frac{1}{e_3 }{\mathrm {\mathbf k}}\cdot \nabla \times \left( {\frac{1}{e_3 
     271          }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm 
     272                  {\mathbf U}}_h }{\partial k}} \right)} \right)\;dv} =0 \\ 
     273    & \int_D {\zeta \,{\mathrm {\mathbf k}}\cdot \nabla \times \left( {\frac{1}{e_3 
     274          }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm 
     275                  {\mathbf U}}_h }{\partial k}} \right)} \right)\;dv} \leq 0 \\ 
    268276  \end{aligned} 
    269277\] 
    270278conservation of horizontal divergence, dissipation of square of the horizontal divergence 
    271279\[ 
    272   % \label{eq:dynzdf_div} 
     280  % \label{eq:CONS_dynzdf_div} 
    273281  \begin{aligned} 
    274282    &\int_D {\nabla \cdot \left( {\frac{1}{e_3 }\frac{\partial }{\partial 
    275             k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm {\bf U}}_h }{\partial k}} 
     283            k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm {\mathbf U}}_h }{\partial k}} 
    276284          \right)} \right)\;dv} =0 \\ 
    277285    & \int_D {\chi \;\nabla \cdot \left( {\frac{1}{e_3 }\frac{\partial }{\partial 
    278             k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm {\bf U}}_h }{\partial k}} 
     286            k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm {\mathbf U}}_h }{\partial k}} 
    279287          \right)} \right)\;dv} \leq 0 \\ 
    280288  \end{aligned} 
     
    283291In discrete form, all these properties are satisfied in $z$-coordinate (see Appendix C). 
    284292In $s$-coordinates, only first order properties can be demonstrated, 
    285 \ie the vertical momentum physics conserve momentum, potential vorticity, and horizontal divergence. 
    286  
    287 % ------------------------------------------------------------------------------------------------------------- 
    288 %       Conservation Properties on Tracer Physics 
    289 % ------------------------------------------------------------------------------------------------------------- 
     293\ie\ the vertical momentum physics conserve momentum, potential vorticity, and horizontal divergence. 
     294 
     295%% ================================================================================================= 
    290296\subsection{Conservation properties on tracer physics} 
    291 \label{subsec:Invariant_tra_physics} 
     297\label{subsec:CONS_Invariant_tra_physics} 
    292298 
    293299The numerical schemes used for tracer subgridscale physics are written in such a way that 
    294300the heat and salt contents are conserved (equations in flux form, second order centred finite differences). 
    295301As a form flux is used to compute the temperature and salinity, 
    296 the quadratic form of these quantities (\ie their variance) globally tends to diminish. 
     302the quadratic form of these quantities (\ie\ their variance) globally tends to diminish. 
    297303As for the advective term, there is generally no strict conservation of mass even if, 
    298 in practice, the mass is conserved with a very good accuracy.  
    299  
    300 \textbf{* lateral physics: }conservation of tracer, dissipation of tracer  
     304in practice, the mass is conserved with a very good accuracy. 
     305 
     306\textbf{* lateral physics: }conservation of tracer, dissipation of tracer 
    301307variance, i.e. 
    302308 
    303309\[ 
    304   % \label{eq:traldf_t_t2} 
     310  % \label{eq:CONS_traldf_t_t2} 
    305311  \begin{aligned} 
    306312    &\int_D \nabla\, \cdot\, \left( A^{lT} \,\Re \,\nabla \,T \right)\;dv = 0 \\ 
     
    312318 
    313319\[ 
    314   % \label{eq:trazdf_t_t2} 
     320  % \label{eq:CONS_trazdf_t_t2} 
    315321  \begin{aligned} 
    316322    & \int_D \frac{1}{e_3 } \frac{\partial }{\partial k}\left( \frac{A^{vT}}{e_3 }  \frac{\partial T}{\partial k}  \right)\;dv = 0 \\ 
     
    328334It has not been implemented. 
    329335 
    330 \biblio 
    331  
    332 \pindex 
     336\subinc{\input{../../global/epilogue}} 
    333337 
    334338\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_misc.tex

    r10601 r11831  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter --- Miscellaneous Topics 
    6 % ================================================================ 
     4 
    75\chapter{Miscellaneous Topics} 
    86\label{chap:MISC} 
    97 
    10 \minitoc 
    11  
    12 \newpage 
    13  
    14 % ================================================================ 
    15 % Representation of Unresolved Straits 
    16 % ================================================================ 
     8\thispagestyle{plain} 
     9 
     10\chaptertoc 
     11 
     12\paragraph{Changes record} ~\\ 
     13 
     14{\footnotesize 
     15  \begin{tabularx}{\textwidth}{l||X|X} 
     16    Release & Author(s) & Modifications \\ 
     17    \hline 
     18    {\em   4.0} & {\em ...} & {\em ...} \\ 
     19    {\em   3.6} & {\em ...} & {\em ...} \\ 
     20    {\em   3.4} & {\em ...} & {\em ...} \\ 
     21    {\em <=3.4} & {\em ...} & {\em ...} 
     22  \end{tabularx} 
     23} 
     24 
     25\clearpage 
     26 
     27%% ================================================================================================= 
    1728\section{Representation of unresolved straits} 
    1829\label{sec:MISC_strait} 
     
    2738balance the net evaporation occurring over the Mediterranean region. 
    2839This problem occurs even in eddy permitting simulations. 
    29 For example, in ORCA 1/4\deg several straits of the Indonesian archipelago (Ombai, Lombok...) 
     40For example, in ORCA 1/4\deg\ several straits of the Indonesian archipelago (Ombai, Lombok...) 
    3041are much narrow than even a single ocean grid-point. 
    3142 
    32 We describe briefly here the three methods that can be used in \NEMO to handle such improperly resolved straits. 
    33 The first two consist of opening the strait by hand while ensuring that the mass exchanges through 
    34 the strait are not too large by either artificially reducing the surface of the strait grid-cells or, 
    35 locally increasing the lateral friction. 
    36 In the third one, the strait is closed but exchanges of mass, heat and salt across the land are allowed. 
    37 Note that such modifications are so specific to a given configuration that no attempt has been made to 
    38 set them in a generic way. 
    39 However, examples of how they can be set up is given in the ORCA 2\deg and 0.5\deg configurations. 
    40 For example, for details of implementation in ORCA2, search: \texttt{IF( cp\_cfg == "orca" .AND. jp\_cfg == 2 )} 
    41  
    42 % ------------------------------------------------------------------------------------------------------------- 
    43 %       Hand made geometry changes 
    44 % ------------------------------------------------------------------------------------------------------------- 
     43We describe briefly here the two methods that can be used in \NEMO\ to handle such 
     44improperly resolved straits. The methods consist of opening the strait while ensuring 
     45that the mass exchanges through the strait are not too large by either artificially 
     46reducing the cross-sectional area of the strait grid-cells or, locally increasing the 
     47lateral friction. 
     48 
     49%% ================================================================================================= 
    4550\subsection{Hand made geometry changes} 
    4651\label{subsec:MISC_strait_hand} 
    4752 
    48 $\bullet$ reduced scale factor in the cross-strait direction to a value in better agreement with 
    49 the true mean width of the strait (\autoref{fig:MISC_strait_hand}). 
    50 This technique is sometime called "partially open face" or "partially closed cells". 
    51 The key issue here is only to reduce the faces of $T$-cell 
    52 (\ie change the value of the horizontal scale factors at $u$- or $v$-point) but not the volume of the $T$-cell. 
    53 Indeed, reducing the volume of strait $T$-cell can easily produce a numerical instability at 
    54 that grid point that would require a reduction of the model time step. 
    55 The changes associated with strait management are done in \mdl{domhgr}, 
    56 just after the definition or reading of the horizontal scale factors.  
    57  
    58 $\bullet$ increase of the viscous boundary layer thickness by local increase of the fmask value at the coast 
    59 (\autoref{fig:MISC_strait_hand}). 
    60 This is done in \mdl{dommsk} together with the setting of the coastal value of fmask (see  \autoref{sec:LBC_coast}). 
    61  
    62 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     53The first method involves reducing the scale factor in the cross-strait direction to a 
     54value in better agreement with the true mean width of the strait 
     55(\autoref{fig:MISC_strait_hand}).  This technique is sometime called "partially open face" 
     56or "partially closed cells".  The key issue here is only to reduce the faces of $T$-cell 
     57(\ie\ change the value of the horizontal scale factors at $u$- or $v$-point) but not the 
     58volume of the $T$-cell.  Indeed, reducing the volume of strait $T$-cell can easily produce 
     59a numerical instability at that grid point which would require a reduction of the model 
     60time step.  Thus to instigate a local change in the width of a Strait requires two steps: 
     61 
     62\begin{itemize} 
     63 
     64\item Add \texttt{e1e2u} and \texttt{e1e2v} arrays to the \np{cn_domcfg}{cn\_domcfg} file. These 2D 
     65arrays should contain the products of the unaltered values of: $\texttt{e1u}*\texttt{e2u}$ 
     66and $\texttt{e1u}*\texttt{e2v}$ respectively. That is the original surface areas of $u$- 
     67and $v$- cells respectively.  These areas are usually defined by the corresponding product 
     68within the \NEMO\ code but the presence of \texttt{e1e2u} and \texttt{e1e2v} in the 
     69\np{cn_domcfg}{cn\_domcfg} file will suppress this calculation and use the supplied fields instead. 
     70If the model domain is provided by user-supplied code in \mdl{usrdef\_hgr}, then this 
     71routine should also return \texttt{e1e2u} and \texttt{e1e2v} and set the integer return 
     72argument \texttt{ie1e2u\_v} to a non-zero value. Values other than 0 for this argument 
     73will suppress the calculation of the areas. 
     74 
     75\item Change values of \texttt{e2u} or \texttt{e1v} (either in the \np{cn_domcfg}{cn\_domcfg} file or 
     76via code in  \mdl{usrdef\_hgr}), whereever a Strait reduction is required. The choice of 
     77whether to alter \texttt{e2u} or \texttt{e1v} depends. respectively,  on whether the 
     78Strait in question is North-South orientated (\eg\ Gibraltar) or East-West orientated (\eg 
     79Lombok). 
     80 
     81\end{itemize} 
     82 
     83The second method is to increase the viscous boundary layer thickness by a local increase 
     84of the fmask value at the coast. This method can also be effective in wider passages.  The 
     85concept is illustarted in the second part of  \autoref{fig:MISC_strait_hand} and changes 
     86to specific locations can be coded in \mdl{usrdef\_fmask}. The \forcode{usr_def_fmask} 
     87routine is always called after \texttt{fmask} has been defined according to the choice of 
     88lateral boundary condition as discussed in \autoref{sec:LBC_coast}. The default version of 
     89\mdl{usrdef\_fmask} contains settings specific to ORCA2 and ORCA1 configurations. These are 
     90meant as examples only; it is up to the user to verify settings and provide alternatives 
     91for their own configurations. The default \forcode{usr_def_fmask} makes no changes to 
     92\texttt{fmask} for any other configuration. 
     93 
    6394\begin{figure}[!tbp] 
    64   \begin{center} 
    65     \includegraphics[width=0.80\textwidth]{Fig_Gibraltar} 
    66     \includegraphics[width=0.80\textwidth]{Fig_Gibraltar2} 
    67     \caption{ 
    68       \protect\label{fig:MISC_strait_hand} 
    69       Example of the Gibraltar strait defined in a $1^{\circ} \times 1^{\circ}$ mesh. 
    70       \textit{Top}: using partially open cells. 
    71       The meridional scale factor at $v$-point is reduced on both sides of the strait to account for 
    72       the real width of the strait (about 20 km). 
    73       Note that the scale factors of the strait $T$-point remains unchanged. 
    74       \textit{Bottom}: using viscous boundary layers. 
    75       The four fmask parameters along the strait coastlines are set to a value larger than 4, 
    76       \ie "strong" no-slip case (see \autoref{fig:LBC_shlat}) creating a large viscous boundary layer that 
    77       allows a reduced transport through the strait. 
    78     } 
    79   \end{center} 
     95  \centering 
     96  \includegraphics[width=0.66\textwidth]{MISC_Gibraltar} 
     97  \includegraphics[width=0.66\textwidth]{MISC_Gibraltar2} 
     98  \caption[Two methods to defined the Gibraltar strait]{ 
     99    Example of the Gibraltar strait defined in a 1\deg\ $\times$ 1\deg\ mesh. 
     100    \textit{Top}: using partially open cells. 
     101    The meridional scale factor at $v$-point is reduced on both sides of the strait to 
     102    account for the real width of the strait (about 20 km). 
     103    Note that the scale factors of the strait $T$-point remains unchanged. 
     104    \textit{Bottom}: using viscous boundary layers. 
     105    The four fmask parameters along the strait coastlines are set to a value larger than 4, 
     106    \ie\ "strong" no-slip case (see \autoref{fig:LBC_shlat}) creating a large viscous boundary layer 
     107    that allows a reduced transport through the strait.} 
     108  \label{fig:MISC_strait_hand} 
    80109\end{figure} 
    81 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    82  
    83 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     110 
    84111\begin{figure}[!tbp] 
    85   \begin{center} 
    86     \includegraphics[width=1.0\textwidth]{Fig_closea_mask_example} 
    87     \caption{ 
    88       \protect\label{fig:closea_mask_example} 
    89       Example of mask fields for the closea module. \textit{Left}: a 
    90       closea\_mask field; \textit{Right}: a closea\_mask\_rnf 
    91       field. In this example, if ln\_closea is set to .true., the mean 
    92       freshwater flux over each of the American Great Lakes will be 
    93       set to zero, and the total residual for all the lakes, if 
    94       negative, will be put into the St Laurence Seaway in the area 
    95       shown.  
    96     } 
    97   \end{center} 
     112  \centering 
     113  \includegraphics[width=0.66\textwidth]{MISC_closea_mask_example} 
     114  \caption[Mask fields for the \protect\mdl{closea} module]{ 
     115    Example of mask fields for the \protect\mdl{closea} module. 
     116    \textit{Left}: a closea\_mask field; 
     117    \textit{Right}: a closea\_mask\_rnf field. 
     118    In this example, if \protect\np{ln_closea}{ln\_closea} is set to \forcode{.true.}, 
     119    the mean freshwater flux over each of the American Great Lakes will be set to zero, 
     120    and the total residual for all the lakes, if negative, will be put into 
     121    the St Laurence Seaway in the area shown.} 
     122  \label{fig:MISC_closea_mask_example} 
    98123\end{figure} 
    99 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    100  
    101 % ================================================================ 
    102 % Closed seas 
    103 % ================================================================ 
    104 \section{Closed seas (\protect\mdl{closea})} 
     124 
     125%% ================================================================================================= 
     126\section[Closed seas (\textit{closea.F90})]{Closed seas (\protect\mdl{closea})} 
    105127\label{sec:MISC_closea} 
    106128 
     
    116138to zero and put the residual flux into the ocean. 
    117139 
    118 Prior to NEMO 4 the locations of inland seas and lakes was set via 
    119 hardcoded indices for various ORCA configurations. From NEMO 4 onwards 
     140Prior to \NEMO\ 4 the locations of inland seas and lakes was set via 
     141hardcoded indices for various ORCA configurations. From \NEMO\ 4 onwards 
    120142the inland seas and lakes are defined using mask fields in the 
    121143domain configuration file. The options are as follows. 
    122144 
    123145\begin{enumerate} 
    124 \item{{\bf No ``closea\_mask'' field is included in domain configuration 
     146\item {{\bfseries No ``closea\_mask'' field is included in domain configuration 
    125147  file.} In this case the closea module does nothing.} 
    126148 
    127 \item{{\bf A field called closea\_mask is included in the domain 
     149\item {{\bfseries A field called closea\_mask is included in the domain 
    128150configuration file and ln\_closea=.false. in namelist namcfg.} In this 
    129151case the inland seas defined by the closea\_mask field are filled in 
     
    131153closea\_mask that is nonzero is set to be a land point.} 
    132154 
    133 \item{{\bf A field called closea\_mask is included in the domain 
     155\item {{\bfseries A field called closea\_mask is included in the domain 
    134156configuration file and ln\_closea=.true. in namelist namcfg.} Each 
    135157inland sea or group of inland seas is set to a positive integer value 
    136 in the closea\_mask field (see Figure \ref{fig:closea_mask_example} 
     158in the closea\_mask field (see \autoref{fig:MISC_closea_mask_example} 
    137159for an example). The net surface flux over each inland sea or group of 
    138160inland seas is set to zero each timestep and the residual flux is 
     
    140162closea\_mask is zero).} 
    141163 
    142 \item{{\bf Fields called closea\_mask and closea\_mask\_rnf are 
     164\item {{\bfseries Fields called closea\_mask and closea\_mask\_rnf are 
    143165included in the domain configuration file and ln\_closea=.true. in 
    144166namelist namcfg.} This option works as for option 3, except that if 
     
    149171by the closea\_mask\_rnf field. Each mapping is defined by a positive 
    150172integer value for the inland sea(s) and the corresponding runoff 
    151 points. An example is given in Figure 
    152 \ref{fig:closea_mask_example}. If no mapping is provided for a 
     173points. An example is given in 
     174\autoref{fig:MISC_closea_mask_example}. If no mapping is provided for a 
    153175particular inland sea then the residual is spread over the global 
    154176ocean.} 
    155177 
    156 \item{{\bf Fields called closea\_mask and closea\_mask\_emp are 
     178\item {{\bfseries Fields called closea\_mask and closea\_mask\_emp are 
    157179included in the domain configuration file and ln\_closea=.true. in 
    158180namelist namcfg.} This option works the same as option 4 except that 
     
    164186 
    165187There is a python routine to create the closea\_mask fields and append 
    166 them to the domain configuration file in the utils/tools/DOMAINcfg directory.  
    167  
    168 % ================================================================ 
    169 % Sub-Domain Functionality  
    170 % ================================================================ 
     188them to the domain configuration file in the utils/tools/DOMAINcfg directory. 
     189 
     190%% ================================================================================================= 
    171191\section{Sub-domain functionality} 
    172192\label{sec:MISC_zoom} 
    173193 
     194%% ================================================================================================= 
    174195\subsection{Simple subsetting of input files via NetCDF attributes} 
    175196 
    176 The extended grids for use with the under-shelf ice cavities will result in redundant rows around Antarctica if 
    177 the ice cavities are not active. 
    178 A simple mechanism for subsetting input files associated with the extended domains has been implemented to 
    179 avoid the need to maintain different sets of input fields for use with or without active ice cavities. 
    180 The existing 'zoom' options are overly complex for this task and marked for deletion anyway. 
    181 This alternative subsetting operates for the j-direction only and works by optionally looking for and 
    182 using a global file attribute (named: \np{open\_ocean\_jstart}) to determine the starting j-row for input. 
    183 The use of this option is best explained with an example: 
    184 consider an ORCA1 configuration using the extended grid bathymetry and coordinate files: 
    185 \vspace{-10pt} 
    186 \ifile{eORCA1\_bathymetry\_v2} 
    187 \ifile{eORCA1\_coordinates} 
    188 \noindent These files define a horizontal domain of 362x332. 
    189 Assuming the first row with open ocean wet points in the non-isf bathymetry for this set is row 42 
    190 (\fortran indexing) then the formally correct setting for \np{open\_ocean\_jstart} is 41. 
    191 Using this value as the first row to be read will result in a 362x292 domain which is the same size as 
    192 the original ORCA1 domain. 
    193 Thus the extended coordinates and bathymetry files can be used with all the original input files for ORCA1 if 
    194 the ice cavities are not active (\np{ln\_isfcav = .false.}). 
    195 Full instructions for achieving this are: 
    196  
    197 \noindent Add the new attribute to any input files requiring a j-row offset, i.e: 
    198 \vspace{-10pt} 
     197The extended grids for use with the under-shelf ice cavities will result in redundant rows 
     198around Antarctica if the ice cavities are not active.  A simple mechanism for subsetting 
     199input files associated with the extended domains has been implemented to avoid the need to 
     200maintain different sets of input fields for use with or without active ice cavities.  This 
     201subsetting operates for the j-direction only and works by optionally looking for and using 
     202a global file attribute (named: \np{open_ocean_jstart}{open\_ocean\_jstart}) to determine the starting j-row 
     203for input.  The use of this option is best explained with an example: 
     204\medskip 
     205 
     206\noindent Consider an ORCA1 
     207configuration using the extended grid domain configuration file: \ifile{eORCA1\_domcfg.nc} 
     208This file define a horizontal domain of 362x332.  The first row with 
     209open ocean wet points in the non-isf bathymetry for this set is row 42 (\fortran\ indexing) 
     210then the formally correct setting for \np{open_ocean_jstart}{open\_ocean\_jstart} is 41.  Using this value as 
     211the first row to be read will result in a 362x292 domain which is the same size as the 
     212original ORCA1 domain.  Thus the extended domain configuration file can be used with all 
     213the original input files for ORCA1 if the ice cavities are not active (\np{ln\_isfcav = 
     214.false.}).  Full instructions for achieving this are: 
     215 
     216\begin{itemize} 
     217\item Add the new attribute to any input files requiring a j-row offset, i.e: 
    199218\begin{cmds} 
    200 ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_coordinates.nc  
    201 ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_bathymetry_v2.nc 
     219ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_domcfg.nc 
    202220\end{cmds} 
    203   
    204 \noindent Add the logical switch to \ngn{namcfg} in the configuration namelist and set true: 
    205 %--------------------------------------------namcfg-------------------------------------------------------- 
    206  
    207 \nlst{namcfg} 
    208 %-------------------------------------------------------------------------------------------------------------- 
    209  
    210 \noindent Note the j-size of the global domain is the (extended j-size minus \np{open\_ocean\_jstart} + 1 ) and 
    211 this must match the size of all datasets other than bathymetry and coordinates currently. 
    212 However the option can be extended to any global, 2D and 3D, netcdf, input field by adding the: 
    213 \vspace{-10pt} 
     221 
     222\item Add the logical switch \np{ln_use_jattr}{ln\_use\_jattr} to \nam{cfg}{cfg} in the configuration 
     223namelist (if it is not already there) and set \forcode{.true.} 
     224\end{itemize} 
     225 
     226\noindent Note that with this option, the j-size of the global domain is (extended 
     227j-size minus \np{open_ocean_jstart}{open\_ocean\_jstart} + 1 ) and this must match the \texttt{jpjglo} value 
     228for the configuration. This means an alternative version of \ifile{eORCA1\_domcfg.nc} must 
     229be created for when \np{ln_use_jattr}{ln\_use\_jattr} is active. The \texttt{ncap2} tool provides a 
     230convenient way of achieving this: 
     231 
     232\begin{cmds} 
     233ncap2 -s 'jpjglo=292' eORCA1_domcfg.nc nORCA1_domcfg.nc 
     234\end{cmds} 
     235 
     236The domain configuration file is unique in this respect since it also contains the value of \jp{jpjglo} 
     237that is read and used by the model. 
     238Any other global, 2D and 3D, netcdf, input field can be prepared for use in a reduced domain by adding the 
     239\texttt{open\_ocean\_jstart} attribute to the file's global attributes. 
     240In particular this is true for any field that is read by \NEMO\ using the following optional argument to 
     241the appropriate call to \np{iom_get}{iom\_get}. 
     242 
    214243\begin{forlines} 
    215244lrowattr=ln_use_jattr 
    216245\end{forlines} 
    217 optional argument to the appropriate \np{iom\_get} call and the \np{open\_ocean\_jstart} attribute to 
    218 the corresponding input files. 
    219 It remains the users responsibility to set \np{jpjdta} and \np{jpjglo} values in 
    220 the \np{namelist\_cfg} file according to their needs. 
    221  
    222 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    223 \begin{figure}[!ht] 
    224   \begin{center} 
    225     \includegraphics[width=0.90\textwidth]{Fig_LBC_zoom} 
    226     \caption{ 
    227       \protect\label{fig:LBC_zoom} 
    228       Position of a model domain compared to the data input domain when the zoom functionality is used. 
    229     } 
    230   \end{center} 
    231 \end{figure} 
    232 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    233  
    234  
    235 % ================================================================ 
    236 % Accuracy and Reproducibility 
    237 % ================================================================ 
    238 \section{Accuracy and reproducibility (\protect\mdl{lib\_fortran})} 
     246 
     247Currently, only the domain configuration variables make use of this optional argument so 
     248this facility is of little practical use except for tests where no other external input 
     249files are needed or you wish to use an extended domain configuration with inputs from 
     250earlier, non-extended configurations. Alternatively, it should be possible to exclude 
     251empty rows for extended domain, forced ocean runs using interpolation on the fly, by 
     252adding the optional argument to \texttt{iom\_get} calls for the weights and initial 
     253conditions. Experimenting with this remains an exercise for the user. 
     254 
     255%% ================================================================================================= 
     256\section[Accuracy and reproducibility (\textit{lib\_fortran.F90})]{Accuracy and reproducibility (\protect\mdl{lib\_fortran})} 
    239257\label{sec:MISC_fortran} 
    240258 
    241 \subsection{Issues with intrinsinc SIGN function (\protect\key{nosignedzero})} 
     259%% ================================================================================================= 
     260\subsection[Issues with intrinsinc SIGN function (\texttt{\textbf{key\_nosignedzero}})]{Issues with intrinsinc SIGN function (\protect\key{nosignedzero})} 
    242261\label{subsec:MISC_sign} 
    243262 
    244 The SIGN(A, B) is the \fortran intrinsic function delivers the magnitude of A with the sign of B. 
     263The SIGN(A, B) is the \fortran\ intrinsic function delivers the magnitude of A with the sign of B. 
    245264For example, SIGN(-3.0,2.0) has the value 3.0. 
    246265The problematic case is when the second argument is zero, because, on platforms that support IEEE arithmetic, 
     
    254273and the processor is capable of distinguishing between positive and negative zero, 
    255274and B is negative real zero. 
    256 Then SIGN delivers a negative result where, under \fninety rules, it used to return a positive result. 
     275Then SIGN delivers a negative result where, under \fninety\ rules, it used to return a positive result. 
    257276This change may be especially sensitive for the ice model, 
    258277so we overwrite the intrinsinc function with our own function simply performing :   \\ 
     
    264283some computers/compilers. 
    265284 
    266  
     285%% ================================================================================================= 
    267286\subsection{MPP reproducibility} 
    268287\label{subsec:MISC_glosum} 
    269288 
    270289The numerical reproducibility of simulations on distributed memory parallel computers is a critical issue. 
    271 In particular, within NEMO global summation of distributed arrays is most susceptible to rounding errors, 
     290In particular, within \NEMO\ global summation of distributed arrays is most susceptible to rounding errors, 
    272291and their propagation and accumulation cause uncertainty in final simulation reproducibility on 
    273292different numbers of processors. 
    274 To avoid so, based on \citet{He_Ding_JSC01} review of different technics, 
     293To avoid so, based on \citet{he.ding_JS01} review of different technics, 
    275294we use a so called self-compensated summation method. 
    276 The idea is to estimate the roundoff error, store it in a buffer, and then add it back in the next addition.  
     295The idea is to estimate the roundoff error, store it in a buffer, and then add it back in the next addition. 
    277296 
    278297Suppose we need to calculate $b = a_1 + a_2 + a_3$. 
     
    292311The self-compensated summation method should be used in all summation in i- and/or j-direction. 
    293312See \mdl{closea} module for an example. 
    294 Note also that this implementation may be sensitive to the optimization level.  
    295  
     313Note also that this implementation may be sensitive to the optimization level. 
     314 
     315%% ================================================================================================= 
    296316\subsection{MPP scalability} 
    297317\label{subsec:MISC_mppsca} 
     
    313333be set at all the locations actually required by each individual for the fold operation. 
    314334This alternative method should give identical results to the default \textsc{ALLGATHER} method and 
    315 is recommended for large values of \np{jpni}. 
    316 The new method is activated by setting \np{ln\_nnogather} to be true ({\bf nammpp}). 
     335is recommended for large values of \np{jpni}{jpni}. 
     336The new method is activated by setting \np{ln_nnogather}{ln\_nnogather} to be true (\nam{mpp}{mpp}). 
    317337The reproducibility of results using the two methods should be confirmed for each new, 
    318338non-reference configuration. 
    319339 
    320 % ================================================================ 
    321 % Model optimisation, Control Print and Benchmark 
    322 % ================================================================ 
     340%% ================================================================================================= 
    323341\section{Model optimisation, control print and benchmark} 
    324342\label{sec:MISC_opt} 
    325 %--------------------------------------------namctl------------------------------------------------------- 
    326  
    327 \nlst{namctl}  
    328 %-------------------------------------------------------------------------------------------------------------- 
    329  
    330 Options are defined through the  \ngn{namctl} namelist variables. 
    331  
     343 
     344\begin{listing} 
     345  \nlst{namctl} 
     346  \caption{\forcode{&namctl}} 
     347  \label{lst:namctl} 
     348\end{listing} 
     349 
     350Options are defined through the  \nam{ctl}{ctl} namelist variables. 
     351 
     352%% ================================================================================================= 
    332353\subsection{Vector optimisation} 
    333354 
     
    335356This is very a very efficient way to increase the length of vector calculations and thus 
    336357to speed up the model on vector computers. 
    337   
     358 
    338359% Add here also one word on NPROMA technique that has been found useless, since compiler have made significant progress during the last decade. 
    339   
     360 
    340361% Add also one word on NEC specific optimisation (Novercheck option for example) 
    341   
     362 
     363%% ================================================================================================= 
    342364\subsection{Control print} 
    343365 
    344 The \np{ln\_ctl} switch was originally used as a debugging option in two modes: 
     366The \np{ln_ctl}{ln\_ctl} switch was originally used as a debugging option in two modes: 
    345367 
    346368\begin{enumerate} 
    347 \item{\np{ln\_ctl}: compute and print the trends averaged over the interior domain in all TRA, DYN, LDF and 
     369\item {\np{ln_ctl}{ln\_ctl}: compute and print the trends averaged over the interior domain in all TRA, DYN, LDF and 
    348370ZDF modules. 
    349371This option is very helpful when diagnosing the origin of an undesired change in model results. } 
    350372 
    351 \item{also \np{ln\_ctl} but using the nictl and njctl namelist parameters to check the source of differences between 
     373\item {also \np{ln_ctl}{ln\_ctl} but using the nictl and njctl namelist parameters to check the source of differences between 
    352374mono and multi processor runs.} 
    353375\end{enumerate} 
    354376 
    355377However, in recent versions it has also been used to force all processors to assume the 
    356 reporting role. Thus when \np{ln\_ctl} is true all processors produce their own versions 
     378reporting role. Thus when \np{ln_ctl}{ln\_ctl} is true all processors produce their own versions 
    357379of files such as: ocean.output, layout.dat, etc.  All such files, beyond the the normal 
    358380reporting processor (narea == 1), are named with a \_XXXX extension to their name, where 
     
    360382such as run.stat (and its netCDF counterpart: run.stat.nc) and tracer.stat contain global 
    361383information and are only ever produced by the reporting master (narea == 1). For version 
    362 4.0 a start has been made to return \np{ln\_ctl} to its original function by introducing 
     3844.0 a start has been made to return \np{ln_ctl}{ln\_ctl} to its original function by introducing 
    363385a new control structure which allows finer control over which files are produced. This 
    364386feature is still evolving but it does already allow the user to: select individually the 
     
    386408at a suitably long interval. For example: 
    387409 
    388 \begin{verbatim}      
     410\begin{verbatim} 
    389411       sn_cfctl%ptimincr  = 25 
    390412\end{verbatim} 
    391413 
    392 will carry out the global communications and write the information every 25 timesteps. This  
     414will carry out the global communications and write the information every 25 timesteps. This 
    393415increment also applies to the time.step file which is otherwise updated every timestep. 
    394416 
    395 % ================================================================ 
    396 \biblio 
    397  
    398 \pindex 
     417\subinc{\input{../../global/epilogue}} 
    399418 
    400419\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_model_basics.tex

    r10544 r11831  
    33\begin{document} 
    44 
    5 % ================================================================ 
    6 % Chapter 1  Model Basics 
    7 % ================================================================ 
    85\chapter{Model Basics} 
    9 \label{chap:PE} 
    10 \minitoc 
    11  
    12 \newpage 
    13  
    14 % ================================================================ 
    15 % Primitive Equations 
    16 % ================================================================ 
     6\label{chap:MB} 
     7 
     8\thispagestyle{plain} 
     9 
     10\chaptertoc 
     11 
     12\paragraph{Changes record} ~\\ 
     13 
     14{\footnotesize 
     15  \begin{tabular}{l||l|l} 
     16    Release          & Author(s)                                   & Modifications       \\ 
     17    \hline 
     18    {\em        4.0} & {\em Mike Bell                            } & {\em Review       } \\ 
     19    {\em        3.6} & {\em Tim Graham and Gurvan Madec          } & {\em Updates      } \\ 
     20    {\em $\leq$ 3.4} & {\em Gurvan Madec and S\'{e}bastien Masson} & {\em First version} \\ 
     21  \end{tabular} 
     22} 
     23 
     24\clearpage 
     25 
     26%% ================================================================================================= 
    1727\section{Primitive equations} 
    18 \label{sec:PE_PE} 
    19  
    20 % ------------------------------------------------------------------------------------------------------------- 
    21 %        Vector Invariant Formulation  
    22 % ------------------------------------------------------------------------------------------------------------- 
    23  
     28\label{sec:MB_PE} 
     29 
     30%% ================================================================================================= 
    2431\subsection{Vector invariant formulation} 
    25 \label{subsec:PE_Vector} 
     32\label{subsec:MB_PE_vector} 
    2633 
    2734The ocean is a fluid that can be described to a good approximation by the primitive equations, 
    28 \ie the Navier-Stokes equations along with a nonlinear equation of state which 
     35\ie\ the Navier-Stokes equations along with a nonlinear equation of state which 
    2936couples the two active tracers (temperature and salinity) to the fluid velocity, 
    3037plus the following additional assumptions made from scale considerations: 
    3138 
    32 \begin{enumerate} 
    33 \item 
    34   \textit{spherical earth approximation}: the geopotential surfaces are assumed to be spheres so that 
    35   gravity (local vertical) is parallel to the earth's radius 
    36 \item 
    37   \textit{thin-shell approximation}: the ocean depth is neglected compared to the earth's radius 
    38 \item 
    39   \textit{turbulent closure hypothesis}: the turbulent fluxes 
     39\begin{labeling}{Neglect of additional Coriolis terms} 
     40\item [\textit{Spherical Earth approximation}] The geopotential surfaces are assumed to 
     41  be oblate spheroids that follow the Earth's bulge; 
     42  these spheroids are approximated by spheres with gravity locally vertical 
     43  (parallel to the Earth's radius) and independent of latitude 
     44  \citep[][section 2]{white.hoskins.ea_QJRMS05}. 
     45\item [\textit{Thin-shell approximation}] The ocean depth is neglected compared to the earth's radius 
     46\item [\textit{Turbulent closure hypothesis}] The turbulent fluxes 
    4047  (which represent the effect of small scale processes on the large-scale) 
    4148  are expressed in terms of large-scale features 
    42 \item 
    43   \textit{Boussinesq hypothesis}: density variations are neglected except in their contribution to 
    44   the buoyancy force 
     49\item [\textit{Boussinesq hypothesis}] Density variations are neglected except in 
     50  their contribution to the buoyancy force 
    4551  \begin{equation} 
    46     \label{eq:PE_eos} 
     52    \label{eq:MB_PE_eos} 
    4753    \rho = \rho \ (T,S,p) 
    4854  \end{equation} 
    49 \item 
    50   \textit{Hydrostatic hypothesis}: the vertical momentum equation is reduced to a balance between 
    51   the vertical pressure gradient and the buoyancy force 
     55\item [\textit{Hydrostatic hypothesis}] The vertical momentum equation is reduced to 
     56  a balance between the vertical pressure gradient and the buoyancy force 
    5257  (this removes convective processes from the initial Navier-Stokes equations and so 
    5358  convective processes must be parameterized instead) 
    5459  \begin{equation} 
    55     \label{eq:PE_hydrostatic} 
     60    \label{eq:MB_PE_hydrostatic} 
    5661    \pd[p]{z} = - \rho \ g 
    5762  \end{equation} 
    58 \item 
    59   \textit{Incompressibility hypothesis}: the three dimensional divergence of the velocity vector $\vect U$ 
    60   is assumed to be zero. 
     63\item [\textit{Incompressibility hypothesis}] The three dimensional divergence of 
     64  the velocity vector $\vect U$ is assumed to be zero. 
    6165  \begin{equation} 
    62     \label{eq:PE_continuity} 
     66    \label{eq:MB_PE_continuity} 
    6367    \nabla \cdot \vect U = 0 
    6468  \end{equation} 
    65 \end{enumerate} 
     69\item [\textit{Neglect of additional Coriolis terms}] The Coriolis terms that vary with 
     70  the cosine of latitude are neglected. 
     71  These terms may be non-negligible where the Brunt-V\"{a}is\"{a}l\"{a} frequency $N$ is small, 
     72  either in the deep ocean or in the sub-mesoscale motions of the mixed layer, 
     73  or near the equator \citep[][section 1]{white.hoskins.ea_QJRMS05}. 
     74  They can be consistently included as part of the ocean dynamics 
     75  \citep[][section 3(d)]{white.hoskins.ea_QJRMS05} and are retained in the MIT ocean model. 
     76\end{labeling} 
    6677 
    6778Because the gravitational force is so dominant in the equations of large-scale motions, 
    68 it is useful to choose an orthogonal set of unit vectors $(i,j,k)$ linked to the earth such that 
     79it is useful to choose an orthogonal set of unit vectors $(i,j,k)$ linked to the Earth such that 
    6980$k$ is the local upward vector and $(i,j)$ are two vectors orthogonal to $k$, 
    70 \ie tangent to the geopotential surfaces. 
    71 Let us define the following variables: $\vect U$ the vector velocity, $\vect U = \vect U_h + w \, \vect k$ 
    72 (the subscript $h$ denotes the local horizontal vector, \ie over the $(i,j)$ plane),  
     81\ie\ tangent to the geopotential surfaces. 
     82Let us define the following variables: 
     83$\vect U$ the vector velocity, $\vect U = \vect U_h + w \, \vect k$ 
     84(the subscript $h$ denotes the local horizontal vector, \ie\ over the $(i,j)$ plane), 
    7385$T$ the potential temperature, $S$ the salinity, $\rho$ the \textit{in situ} density. 
    7486The vector invariant form of the primitive equations in the $(i,j,k)$ vector system provides 
    7587the following equations: 
    7688\begin{subequations} 
    77   \label{eq:PE} 
     89  \label{eq:MB_PE} 
    7890  \begin{gather} 
    79     \intertext{$-$ the momentum balance} 
    80     \label{eq:PE_dyn} 
    81     \pd[\vect U_h]{t} = - \lt[ (\nabla \times \vect U) \times \vect U + \frac{1}{2} \nabla \lt( \vect U^2 \rt) \rt]_h 
    82                         - f \; k \times \vect U_h - \frac{1}{\rho_o} \nabla_h p 
    83                         + \vect D^{\vect U} + \vect F^{\vect U} \\ 
    84     \intertext{$-$ the heat and salt conservation equations} 
    85     \label{eq:PE_tra_T} 
     91    \shortintertext{$-$ the momentum balance} 
     92    \label{eq:MB_PE_dyn} 
     93    \pd[\vect U_h]{t} = - \lt[ (\nabla \times \vect U) \times \vect U + \frac{1}{2} \nabla \lt( \vect U^2 \rt) \rt]_h - f \; k \times \vect U_h - \frac{1}{\rho_o} \nabla_h p + \vect D^{\vect U} + \vect F^{\vect U} 
     94    \shortintertext{$-$ the heat and salt conservation equations} 
     95    \label{eq:MB_PE_tra_T} 
    8696    \pd[T]{t} = - \nabla \cdot (T \ \vect U) + D^T + F^T \\ 
    87     \label{eq:PE_tra_S} 
     97    \label{eq:MB_PE_tra_S} 
    8898    \pd[S]{t} = - \nabla \cdot (S \ \vect U) + D^S + F^S 
    8999  \end{gather} 
     
    91101where $\nabla$ is the generalised derivative vector operator in $(i,j,k)$ directions, $t$ is the time, 
    92102$z$ is the vertical coordinate, $\rho$ is the \textit{in situ} density given by the equation of state 
    93 (\autoref{eq:PE_eos}), $\rho_o$ is a reference density, $p$ the pressure, 
     103(\autoref{eq:MB_PE_eos}), $\rho_o$ is a reference density, $p$ the pressure, 
    94104$f = 2 \vect \Omega \cdot k$ is the Coriolis acceleration 
    95 (where $\vect \Omega$ is the Earth's angular velocity vector), and $g$ is the gravitational acceleration. 
     105(where $\vect \Omega$ is the Earth's angular velocity vector), 
     106and $g$ is the gravitational acceleration. 
    96107$\vect D^{\vect U}$, $D^T$ and $D^S$ are the parameterisations of small-scale physics for momentum, 
    97108temperature and salinity, and $\vect F^{\vect U}$, $F^T$ and $F^S$ surface forcing terms. 
    98 Their nature and formulation are discussed in \autoref{sec:PE_zdf_ldf} and \autoref{subsec:PE_boundary_condition}. 
    99  
    100 % ------------------------------------------------------------------------------------------------------------- 
    101 % Boundary condition 
    102 % ------------------------------------------------------------------------------------------------------------- 
     109Their nature and formulation are discussed in \autoref{sec:MB_zdf_ldf} and 
     110\autoref{subsec:MB_boundary_condition}. 
     111 
     112%% ================================================================================================= 
    103113\subsection{Boundary conditions} 
    104 \label{subsec:PE_boundary_condition} 
     114\label{subsec:MB_boundary_condition} 
    105115 
    106116An ocean is bounded by complex coastlines, bottom topography at its base and 
    107117an air-sea or ice-sea interface at its top. 
    108118These boundaries can be defined by two surfaces, $z = - H(i,j)$ and $z = \eta(i,j,k,t)$, 
    109 where $H$ is the depth of the ocean bottom and $\eta$ is the height of the sea surface. 
    110 Both $H$ and $\eta$ are usually referenced to a given surface, $z = 0$, chosen as a mean sea surface 
    111 (\autoref{fig:ocean_bc}). 
    112 Through these two boundaries, the ocean can exchange fluxes of heat, fresh water, salt, and momentum with 
    113 the solid earth, the continental margins, the sea ice and the atmosphere. 
    114 However, some of these fluxes are so weak that even on climatic time scales of thousands of years 
    115 they can be neglected. 
     119where $H$ is the depth of the ocean bottom and $\eta$ is the height of the sea surface 
     120(discretisation can introduce additional artificial ``side-wall'' boundaries). 
     121Both $H$ and $\eta$ are referenced to a surface of constant geopotential 
     122(\ie\ a mean sea surface height) on which $z = 0$ (\autoref{fig:MB_ocean_bc}). 
     123Through these two boundaries, the ocean can exchange fluxes of heat, fresh water, salt, 
     124and momentum with the solid earth, the continental margins, the sea ice and the atmosphere. 
     125However, some of these fluxes are so weak that 
     126even on climatic time scales of thousands of years they can be neglected. 
    116127In the following, we briefly review the fluxes exchanged at the interfaces between the ocean and 
    117128the other components of the earth system. 
    118129 
    119 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    120 \begin{figure}[!ht] 
    121   \begin{center} 
    122     \includegraphics[]{Fig_I_ocean_bc} 
    123     \caption{ 
    124       \protect\label{fig:ocean_bc} 
    125       The ocean is bounded by two surfaces, $z = - H(i,j)$ and $z = \eta(i,j,t)$, 
    126       where $H$ is the depth of the sea floor and $\eta$ the height of the sea surface. 
    127       Both $H$ and $\eta$ are referenced to $z = 0$. 
    128     } 
    129   \end{center} 
     130\begin{figure} 
     131  \centering 
     132  \includegraphics[width=0.66\textwidth]{MB_ocean_bc} 
     133  \caption[Ocean boundary conditions]{ 
     134    The ocean is bounded by two surfaces, $z = - H(i,j)$ and $z = \eta(i,j,t)$, 
     135    where $H$ is the depth of the sea floor and $\eta$ the height of the sea surface. 
     136    Both $H$ and $\eta$ are referenced to $z = 0$.} 
     137  \label{fig:MB_ocean_bc} 
    130138\end{figure} 
    131 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    132139 
    133140\begin{description} 
    134 \item[Land - ocean interface:] 
    135   the major flux between continental margins and the ocean is a mass exchange of fresh water through river runoff. 
     141\item [Land - ocean] The major flux between continental margins and the ocean is a mass exchange of 
     142  fresh water through river runoff. 
    136143  Such an exchange modifies the sea surface salinity especially in the vicinity of major river mouths. 
    137   It can be neglected for short range integrations but has to be taken into account for long term integrations as 
     144  It can be neglected for short range integrations but 
     145  has to be taken into account for long term integrations as 
    138146  it influences the characteristics of water masses formed (especially at high latitudes). 
    139147  It is required in order to close the water cycle of the climate system. 
    140   It is usually specified as a fresh water flux at the air-sea interface in the vicinity of river mouths. 
    141 \item[Solid earth - ocean interface:] 
    142   heat and salt fluxes through the sea floor are small, except in special areas of little extent. 
    143   They are usually neglected in the model 
    144   \footnote{ 
     148  It is usually specified as a fresh water flux at the air-sea interface in 
     149  the vicinity of river mouths. 
     150\item [Solid earth - ocean] Heat and salt fluxes through the sea floor are small, 
     151  except in special areas of little extent. 
     152  They are usually neglected in the model \footnote{ 
    145153    In fact, it has been shown that the heat flux associated with the solid Earth cooling 
    146     (\ie the geothermal heating) is not negligible for the thermohaline circulation of the world ocean 
    147     (see \autoref{subsec:TRA_bbc}). 
     154    (\ie\ the geothermal heating) is not negligible for 
     155    the thermohaline circulation of the world ocean (see \autoref{subsec:TRA_bbc}). 
    148156  }. 
    149157  The boundary condition is thus set to no flux of heat and salt across solid boundaries. 
    150   For momentum, the situation is different. There is no flow across solid boundaries, 
    151   \ie the velocity normal to the ocean bottom and coastlines is zero (in other words, 
    152   the bottom velocity is parallel to solid boundaries). This kinematic boundary condition 
    153   can be expressed as: 
     158  For momentum, the situation is different. 
     159  There is no flow across solid boundaries, 
     160  \ie\ the velocity normal to the ocean bottom and coastlines is zero 
     161  (in other words, the bottom velocity is parallel to solid boundaries). 
     162  This kinematic boundary condition can be expressed as: 
    154163  \begin{equation} 
    155     \label{eq:PE_w_bbc} 
     164    \label{eq:MB_w_bbc} 
    156165    w = - \vect U_h \cdot \nabla_h (H) 
    157166  \end{equation} 
    158167  In addition, the ocean exchanges momentum with the earth through frictional processes. 
    159168  Such momentum transfer occurs at small scales in a boundary layer. 
    160   It must be parameterized in terms of turbulent fluxes using bottom and/or lateral boundary conditions. 
     169  It must be parameterized in terms of turbulent fluxes using 
     170  bottom and/or lateral boundary conditions. 
    161171  Its specification depends on the nature of the physical parameterisation used for 
    162   $\vect D^{\vect U}$ in \autoref{eq:PE_dyn}. 
    163   It is discussed in \autoref{eq:PE_zdf}.% and Chap. III.6 to 9. 
    164 \item[Atmosphere - ocean interface:] 
    165   the kinematic surface condition plus the mass flux of fresh water PE (the precipitation minus evaporation budget) 
    166   leads to: 
     172  $\vect D^{\vect U}$ in \autoref{eq:MB_PE_dyn}. 
     173  It is discussed in \autoref{eq:MB_zdf}. % and Chap. III.6 to 9. 
     174\item [Atmosphere - ocean] The kinematic surface condition plus the mass flux of fresh water PE 
     175  (the precipitation minus evaporation budget) leads to: 
    167176  \[ 
    168     % \label{eq:PE_w_sbc} 
     177    % \label{eq:MB_w_sbc} 
    169178    w = \pd[\eta]{t} + \lt. \vect U_h \rt|_{z = \eta} \cdot \nabla_h (\eta) + P - E 
    170179  \] 
    171   The dynamic boundary condition, neglecting the surface tension (which removes capillary waves from the system) 
    172   leads to the continuity of pressure across the interface $z = \eta$. 
     180  The dynamic boundary condition, neglecting the surface tension 
     181  (which removes capillary waves from the system) leads to 
     182  the continuity of pressure across the interface $z = \eta$. 
    173183  The atmosphere and ocean also exchange horizontal momentum (wind stress), and heat. 
    174 \item[Sea ice - ocean interface:] 
    175   the ocean and sea ice exchange heat, salt, fresh water and momentum. 
     184\item [Sea ice - ocean] The ocean and sea ice exchange heat, salt, fresh water and momentum. 
    176185  The sea surface temperature is constrained to be at the freezing point at the interface. 
    177186  Sea ice salinity is very low ($\sim4-6 \, psu$) compared to those of the ocean ($\sim34 \, psu$). 
    178   The cycle of freezing/melting is associated with fresh water and salt fluxes that cannot be neglected. 
     187  The cycle of freezing/melting is associated with fresh water and salt fluxes that 
     188  cannot be neglected. 
    179189\end{description} 
    180190 
    181 % ================================================================ 
    182 % The Horizontal Pressure Gradient 
    183 % ================================================================ 
     191%% ================================================================================================= 
    184192\section{Horizontal pressure gradient} 
    185 \label{sec:PE_hor_pg} 
    186  
    187 % ------------------------------------------------------------------------------------------------------------- 
    188 % Pressure Formulation 
    189 % ------------------------------------------------------------------------------------------------------------- 
     193\label{sec:MB_hor_pg} 
     194 
     195%% ================================================================================================= 
    190196\subsection{Pressure formulation} 
    191 \label{subsec:PE_p_formulation} 
     197\label{subsec:MB_p_formulation} 
    192198 
    193199The total pressure at a given depth $z$ is composed of a surface pressure $p_s$ at 
    194200a reference geopotential surface ($z = 0$) and a hydrostatic pressure $p_h$ such that: 
    195201$p(i,j,k,t) = p_s(i,j,t) + p_h(i,j,k,t)$. 
    196 The latter is computed by integrating (\autoref{eq:PE_hydrostatic}), 
    197 assuming that pressure in decibars can be approximated by depth in meters in (\autoref{eq:PE_eos}). 
     202The latter is computed by integrating (\autoref{eq:MB_PE_hydrostatic}), 
     203assuming that pressure in decibars can be approximated by depth in meters in (\autoref{eq:MB_PE_eos}). 
    198204The hydrostatic pressure is then given by: 
    199205\[ 
    200   % \label{eq:PE_pressure} 
     206  % \label{eq:MB_pressure} 
    201207  p_h (i,j,z,t) = \int_{\varsigma = z}^{\varsigma = 0} g \; \rho (T,S,\varsigma) \; d \varsigma 
    202208\] 
    203209Two strategies can be considered for the surface pressure term: 
    204 $(a)$ introduce of a  new variable $\eta$, the free-surface elevation, 
     210\begin{enumerate*}[label=(\textit{\alph*})] 
     211\item introduce of a new variable $\eta$, the free-surface elevation, 
    205212for which a prognostic equation can be established and solved; 
    206 $(b)$ assume that the ocean surface is a rigid lid, 
     213\item assume that the ocean surface is a rigid lid, 
    207214on which the pressure (or its horizontal gradient) can be diagnosed. 
     215\end{enumerate*} 
    208216When the former strategy is used, one solution of the free-surface elevation consists of 
    209217the excitation of external gravity waves. 
    210218The flow is barotropic and the surface moves up and down with gravity as the restoring force. 
    211219The phase speed of such waves is high (some hundreds of metres per second) so that 
    212 the time step would have to be very short if they were present in the model. 
     220the time step has to be very short when they are present in the model. 
    213221The latter strategy filters out these waves since the rigid lid approximation implies $\eta = 0$, 
    214 \ie the sea surface is the surface $z = 0$. 
     222\ie\ the sea surface is the surface $z = 0$. 
    215223This well known approximation increases the surface wave speed to infinity and 
    216 modifies certain other longwave dynamics (\eg barotropic Rossby or planetary waves). 
     224modifies certain other longwave dynamics (\eg\ barotropic Rossby or planetary waves). 
    217225The rigid-lid hypothesis is an obsolescent feature in modern OGCMs. 
    218 It has been available until the release 3.1 of \NEMO, and it has been removed in release 3.2 and followings. 
    219 Only the free surface formulation is now described in the this document (see the next sub-section). 
    220  
    221 % ------------------------------------------------------------------------------------------------------------- 
    222 % Free Surface Formulation 
    223 % ------------------------------------------------------------------------------------------------------------- 
     226It has been available until the release 3.1 of \NEMO, 
     227and it has been removed in release 3.2 and followings. 
     228Only the free surface formulation is now described in this document (see the next sub-section). 
     229 
     230%% ================================================================================================= 
    224231\subsection{Free surface formulation} 
    225 \label{subsec:PE_free_surface} 
     232\label{subsec:MB_free_surface} 
    226233 
    227234In the free surface formulation, a variable $\eta$, the sea-surface height, 
    228235is introduced which describes the shape of the air-sea interface. 
    229 This variable is solution of a prognostic equation which is established by forming the vertical average of 
    230 the kinematic surface condition (\autoref{eq:PE_w_bbc}): 
     236This variable is solution of a prognostic equation which is established by 
     237forming the vertical average of the kinematic surface condition (\autoref{eq:MB_w_bbc}): 
    231238\begin{equation} 
    232   \label{eq:PE_ssh} 
     239  \label{eq:MB_ssh} 
    233240  \pd[\eta]{t} = - D + P - E \quad \text{where} \quad D = \nabla \cdot \lt[ (H + \eta) \; \overline{U}_h \, \rt] 
    234241\end{equation} 
    235 and using (\autoref{eq:PE_hydrostatic}) the surface pressure is given by: $p_s = \rho \, g \, \eta$. 
    236  
    237 Allowing the air-sea interface to move introduces the external gravity waves (EGWs) as 
     242and using (\autoref{eq:MB_PE_hydrostatic}) the surface pressure is given by: 
     243$p_s = \rho \, g \, \eta$. 
     244 
     245Allowing the air-sea interface to move introduces 
     246the \textbf{E}xternal \textbf{G}ravity \textbf{W}aves (EGWs) as 
    238247a class of solution of the primitive equations. 
    239 These waves are barotropic because of hydrostatic assumption, and their phase speed is quite high. 
     248These waves are barotropic (\ie\ nearly independent of depth) and their phase speed is quite high. 
    240249Their time scale is short with respect to the other processes described by the primitive equations. 
    241250 
    242251Two choices can be made regarding the implementation of the free surface in the model, 
    243252depending on the physical processes of interest. 
    244  
    245 $\bullet$ If one is interested in EGWs, in particular the tides and their interaction with 
    246 the baroclinic structure of the ocean (internal waves) possibly in shallow seas, 
    247 then a non linear free surface is the most appropriate. 
    248 This means that no approximation is made in \autoref{eq:PE_ssh} and that 
    249 the variation of the ocean volume is fully taken into account. 
    250 Note that in order to study the fast time scales associated with EGWs it is necessary to 
    251 minimize time filtering effects 
    252 (use an explicit time scheme with very small time step, or a split-explicit scheme with reasonably small time step, 
    253 see \autoref{subsec:DYN_spg_exp} or \autoref{subsec:DYN_spg_ts}). 
    254  
    255 $\bullet$ If one is not interested in EGW but rather sees them as high frequency noise, 
    256 it is possible to apply an explicit filter to slow down the fastest waves while 
    257 not altering the slow barotropic Rossby waves. 
    258 If further, an approximative conservation of heat and salt contents is sufficient for the problem solved, 
    259 then it is sufficient to solve a linearized version of \autoref{eq:PE_ssh}, 
    260 which still allows to take into account freshwater fluxes applied at the ocean surface \citep{Roullet_Madec_JGR00}. 
    261 Nevertheless, with the linearization, an exact conservation of heat and salt contents is lost. 
    262  
    263 The filtering of EGWs in models with a free surface is usually a matter of discretisation of 
    264 the temporal derivatives, 
    265 using a split-explicit method \citep{Killworth_al_JPO91, Zhang_Endoh_JGR92} or 
    266 the implicit scheme \citep{Dukowicz1994} or 
    267 the addition of a filtering force in the momentum equation \citep{Roullet_Madec_JGR00}. 
    268 With the present release, \NEMO offers the choice between 
    269 an explicit free surface (see \autoref{subsec:DYN_spg_exp}) or 
    270 a split-explicit scheme strongly inspired the one proposed by \citet{Shchepetkin_McWilliams_OM05} 
    271 (see \autoref{subsec:DYN_spg_ts}). 
    272  
    273 % ================================================================ 
    274 % Curvilinear z-coordinate System 
    275 % ================================================================ 
    276 \section{Curvilinear \textit{z-}coordinate system} 
    277 \label{sec:PE_zco} 
    278  
    279 % ------------------------------------------------------------------------------------------------------------- 
    280 % Tensorial Formalism 
    281 % ------------------------------------------------------------------------------------------------------------- 
     253\begin{itemize} 
     254\item If one is interested in EGWs, in particular the tides and their interaction with 
     255  the baroclinic structure of the ocean (internal waves) possibly in shallow seas, 
     256  then a non linear free surface is the most appropriate. 
     257  This means that no approximation is made in \autoref{eq:MB_ssh} and that 
     258  the variation of the ocean volume is fully taken into account. 
     259  Note that in order to study the fast time scales associated with EGWs it is necessary to 
     260  minimize time filtering effects 
     261  (use an explicit time scheme with very small time step, 
     262  or a split-explicit scheme with reasonably small time step, 
     263  see \autoref{subsec:DYN_spg_exp} or \autoref{subsec:DYN_spg_ts}). 
     264\item If one is not interested in EGWs but rather sees them as high frequency noise, 
     265  it is possible to apply an explicit filter to slow down the fastest waves while 
     266  not altering the slow barotropic Rossby waves. 
     267  If further, an approximative conservation of heat and salt contents is sufficient for 
     268  the problem solved, then it is sufficient to solve a linearized version of \autoref{eq:MB_ssh}, 
     269  which still allows to take into account freshwater fluxes applied at the ocean surface 
     270  \citep{roullet.madec_JGR00}. 
     271  Nevertheless, with the linearization, an exact conservation of heat and salt contents is lost. 
     272\end{itemize} 
     273The filtering of EGWs in models with a free surface is usually 
     274a matter of discretisation of the temporal derivatives, 
     275using a split-explicit method \citep{killworth.webb.ea_JPO91, zhang.endoh_JGR92} or 
     276the implicit scheme \citep{dukowicz.smith_JGR94} or the addition of a filtering force in 
     277the momentum equation \citep{roullet.madec_JGR00}. 
     278With the present release, \NEMO\ offers the choice between an explicit free surface 
     279(see \autoref{subsec:DYN_spg_exp}) or a split-explicit scheme strongly inspired the one proposed by 
     280\citet{shchepetkin.mcwilliams_OM05} (see \autoref{subsec:DYN_spg_ts}). 
     281 
     282%% ================================================================================================= 
     283\section{Curvilinear \textit{z}-coordinate system} 
     284\label{sec:MB_zco} 
     285 
     286%% ================================================================================================= 
    282287\subsection{Tensorial formalism} 
    283 \label{subsec:PE_tensorial} 
     288\label{subsec:MB_tensorial} 
    284289 
    285290In many ocean circulation problems, the flow field has regions of enhanced dynamics 
    286 (\ie surface layers, western boundary currents, equatorial currents, or ocean fronts). 
     291(\ie\ surface layers, western boundary currents, equatorial currents, or ocean fronts). 
    287292The representation of such dynamical processes can be improved by 
    288293specifically increasing the model resolution in these regions. 
     
    292297cannot be easily treated in a global model without filtering. 
    293298A solution consists of introducing an appropriate coordinate transformation that 
    294 shifts the singular point onto land \citep{Madec_Imbard_CD96, Murray_JCP96}. 
    295 As a consequence, it is important to solve the primitive equations in various curvilinear coordinate systems. 
    296 An efficient way of introducing an appropriate coordinate transform can be found when using a tensorial formalism. 
     299shifts the singular point onto land \citep{madec.imbard_CD96, murray_JCP96}. 
     300As a consequence, 
     301it is important to solve the primitive equations in various curvilinear coordinate systems. 
     302An efficient way of introducing an appropriate coordinate transform can be found when 
     303using a tensorial formalism. 
    297304This formalism is suited to any multidimensional curvilinear coordinate system. 
    298 Ocean modellers mainly use three-dimensional orthogonal grids on the sphere (spherical earth approximation), 
    299 with preservation of the local vertical. Here we give the simplified equations for this particular case. 
    300 The general case is detailed by \citet{Eiseman1980} in their survey of the conservation laws of fluid dynamics. 
     305Ocean modellers mainly use three-dimensional orthogonal grids on the sphere 
     306(spherical earth approximation), with preservation of the local vertical. 
     307Here we give the simplified equations for this particular case. 
     308The general case is detailed by \citet{eiseman.stone_SR80} in 
     309their survey of the conservation laws of fluid dynamics. 
    301310 
    302311Let $(i,j,k)$ be a set of orthogonal curvilinear coordinates on 
     
    304313$(i,j,k)$ linked to the earth such that 
    305314$k$ is the local upward vector and $(i,j)$ are two vectors orthogonal to $k$, 
    306 \ie along geopotential surfaces (\autoref{fig:referential}). 
     315\ie\ along geopotential surfaces (\autoref{fig:MB_referential}). 
    307316Let $(\lambda,\varphi,z)$ be the geographical coordinate system in which a position is defined by 
    308317the latitude $\varphi(i,j)$, the longitude $\lambda(i,j)$ and 
    309318the distance from the centre of the earth $a + z(k)$ where $a$ is the earth's radius and 
    310 $z$ the altitude above a reference sea level (\autoref{fig:referential}). 
     319$z$ the altitude above a reference sea level (\autoref{fig:MB_referential}). 
    311320The local deformation of the curvilinear coordinate system is given by $e_1$, $e_2$ and $e_3$, 
    312321the three scale factors: 
    313322\begin{equation} 
    314   \label{eq:scale_factors} 
    315   \begin{aligned} 
    316     e_1 &= (a + z) \lt[ \lt( \pd[\lambda]{i} \cos \varphi \rt)^2 + \lt( \pd[\varphi]{i} \rt)^2 \rt]^{1/2} \\ 
    317     e_2 &= (a + z) \lt[ \lt( \pd[\lambda]{j} \cos \varphi \rt)^2 + \lt( \pd[\varphi]{j} \rt)^2 \rt]^{1/2} \\ 
    318     e_3 &= \lt( \pd[z]{k} \rt) 
    319   \end{aligned} 
     323  \label{eq:MB_scale_factors} 
     324    e_1 = (a + z) \lt[ \lt( \pd[\lambda]{i} \cos \varphi \rt)^2 + \lt( \pd[\varphi]{i} \rt)^2 \rt]^{1/2} \quad e_2 = (a + z) \lt[ \lt( \pd[\lambda]{j} \cos \varphi \rt)^2 + \lt( \pd[\varphi]{j} \rt)^2 \rt]^{1/2} \quad e_3 = \lt( \pd[z]{k} \rt) 
    320325\end{equation} 
    321326 
    322 % >>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    323 \begin{figure}[!tb] 
    324   \begin{center} 
    325     \includegraphics[]{Fig_I_earth_referential} 
    326     \caption{ 
    327       \protect\label{fig:referential} 
    328       the geographical coordinate system $(\lambda,\varphi,z)$ and the curvilinear 
    329       coordinate system $(i,j,k)$. 
    330     } 
    331   \end{center} 
     327\begin{figure} 
     328  \centering 
     329  \includegraphics[width=0.33\textwidth]{MB_earth_referential} 
     330  \caption[Geographical and curvilinear coordinate systems]{ 
     331    the geographical coordinate system $(\lambda,\varphi,z)$ and the curvilinear 
     332    coordinate system $(i,j,k)$.} 
     333  \label{fig:MB_referential} 
    332334\end{figure} 
    333 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    334335 
    335336Since the ocean depth is far smaller than the earth's radius, $a + z$, can be replaced by $a$ in 
    336 (\autoref{eq:scale_factors}) (thin-shell approximation). 
     337(\autoref{eq:MB_scale_factors}) (thin-shell approximation). 
    337338The resulting horizontal scale factors $e_1$, $e_2$  are independent of $k$ while 
    338339the vertical scale factor is a single function of $k$ as $k$ is parallel to $z$. 
    339340The scalar and vector operators that appear in the primitive equations 
    340 (\autoref{eq:PE_dyn} to \autoref{eq:PE_eos}) can be written in the tensorial form, 
     341(\autoref{eq:MB_PE_dyn} to \autoref{eq:MB_PE_eos}) can then be written in the tensorial form, 
    341342invariant in any orthogonal horizontal curvilinear coordinate system transformation: 
    342343\begin{subequations} 
    343   % \label{eq:PE_discrete_operators} 
    344   \begin{gather} 
    345     \label{eq:PE_grad} 
    346     \nabla q =   \frac{1}{e_1} \pd[q]{i} \; \vect i 
    347                + \frac{1}{e_2} \pd[q]{j} \; \vect j 
    348                + \frac{1}{e_3} \pd[q]{k} \; \vect k \\ 
    349     \label{eq:PE_div} 
    350     \nabla \cdot \vect A =   \frac{1}{e_1 \; e_2} \lt[ \pd[(e_2 \; a_1)]{\partial i} + \pd[(e_1 \; a_2)]{j} \rt] 
    351                            + \frac{1}{e_3} \lt[ \pd[a_3]{k} \rt] 
    352   \end{gather} 
    353   \begin{multline} 
    354     \label{eq:PE_curl} 
    355       \nabla \times \vect{A} =   \lt[ \frac{1}{e_2} \pd[a_3]{j} - \frac{1}{e_3} \pd[a_2]{k}   \rt] \vect i \\ 
    356                                + \lt[ \frac{1}{e_3} \pd[a_1]{k} - \frac{1}{e_1} \pd[a_3]{i}   \rt] \vect j \\ 
    357                                + \frac{1}{e_1 e_2} \lt[ \pd[(e_2 a_2)]{i} - \pd[(e_1 a_1)]{j} \rt] \vect k 
    358   \end{multline} 
    359   \begin{gather} 
    360     \label{eq:PE_lap} 
    361     \Delta q = \nabla \cdot (\nabla q) \\ 
    362     \label{eq:PE_lap_vector} 
    363     \Delta \vect A = \nabla (\nabla \cdot \vect A) - \nabla \times (\nabla \times \vect A) 
    364   \end{gather} 
     344  % \label{eq:MB_discrete_operators} 
     345  \begin{align} 
     346    \label{eq:MB_grad} 
     347    \nabla q &=   \frac{1}{e_1} \pd[q]{i} \; \vect i + \frac{1}{e_2} \pd[q]{j} \; \vect j + \frac{1}{e_3} \pd[q]{k} \; \vect k \\ 
     348    \label{eq:MB_div} 
     349    \nabla \cdot \vect A &=   \frac{1}{e_1 \; e_2} \lt[ \pd[(e_2 \; a_1)]{\partial i} + \pd[(e_1 \; a_2)]{j} \rt] + \frac{1}{e_3} \lt[ \pd[a_3]{k} \rt] \\ 
     350    \label{eq:MB_curl} 
     351      \nabla \times \vect{A} &=   \lt[ \frac{1}{e_2} \pd[a_3]{j} - \frac{1}{e_3} \pd[a_2]{k}   \rt] \vect i + \lt[ \frac{1}{e_3} \pd[a_1]{k} - \frac{1}{e_1} \pd[a_3]{i}   \rt] \vect j + \frac{1}{e_1 e_2} \lt[ \pd[(e_2 a_2)]{i} - \pd[(e_1 a_1)]{j} \rt] \vect k \\ 
     352    \label{eq:MB_lap} 
     353    \Delta q &= \nabla \cdot (\nabla q) \\ 
     354    \label{eq:MB_lap_vector} 
     355    \Delta \vect A &= \nabla (\nabla \cdot \vect A) - \nabla \times (\nabla \times \vect A) 
     356  \end{align} 
    365357\end{subequations} 
    366 where $q$ is a scalar quantity and $\vect A = (a_1,a_2,a_3)$ a vector in the $(i,j,k)$ coordinates system. 
    367  
    368 % ------------------------------------------------------------------------------------------------------------- 
    369 % Continuous Model Equations 
    370 % ------------------------------------------------------------------------------------------------------------- 
     358where $q$ is a scalar quantity and 
     359$\vect A = (a_1,a_2,a_3)$ a vector in the $(i,j,k)$ coordinates system. 
     360 
     361%% ================================================================================================= 
    371362\subsection{Continuous model equations} 
    372 \label{subsec:PE_zco_Eq} 
     363\label{subsec:MB_zco_Eq} 
    373364 
    374365In order to express the Primitive Equations in tensorial formalism, 
    375 it is necessary to compute the horizontal component of the non-linear and viscous terms of the equation using 
    376 \autoref{eq:PE_grad}) to \autoref{eq:PE_lap_vector}. 
    377 Let us set $\vect U = (u,v,w) = \vect U_h + w \; \vect k $, the velocity in the $(i,j,k)$ coordinates system and 
    378 define the relative vorticity $\zeta$ and the divergence of the horizontal velocity field $\chi$, by: 
     366it is necessary to compute the horizontal component of the non-linear and viscous terms of 
     367the equation using \autoref{eq:MB_grad}) to \autoref{eq:MB_lap_vector}. 
     368Let us set $\vect U = (u,v,w) = \vect U_h + w \; \vect k $, 
     369the velocity in the $(i,j,k)$ coordinates system, 
     370and define the relative vorticity $\zeta$ and the divergence of the horizontal velocity field $\chi$, 
     371by: 
    379372\begin{gather} 
    380   \label{eq:PE_curl_Uh} 
     373  \label{eq:MB_curl_Uh} 
    381374  \zeta = \frac{1}{e_1 e_2} \lt[ \pd[(e_2 \, v)]{i} - \pd[(e_1 \, u)]{j} \rt] \\ 
    382   \label{eq:PE_div_Uh} 
     375  \label{eq:MB_div_Uh} 
    383376  \chi  = \frac{1}{e_1 e_2} \lt[ \pd[(e_2 \, u)]{i} + \pd[(e_1 \, v)]{j} \rt] 
    384377\end{gather} 
    385378 
    386 Using the fact that the horizontal scale factors $e_1$ and $e_2$ are independent of $k$ and that 
     379Using again the fact that the horizontal scale factors $e_1$ and $e_2$ are independent of $k$ and that 
    387380$e_3$  is a function of the single variable $k$, 
    388 $NLT$ the nonlinear term of \autoref{eq:PE_dyn} can be transformed as follows: 
    389 \begin{alignat*}{2} 
    390   &NLT &=   &\lt[ (\nabla \times {\vect U}) \times {\vect U} + \frac{1}{2} \nabla \lt( {\vect U}^2 \rt) \rt]_h \\ 
    391   &    &=   &\lt( 
    392     \begin{array}{*{20}c} 
    393                 \lt[ \frac{1}{e_3} \pd[u]{k} - \frac{1}{e_1} \pd[w]{i} \rt] w - \zeta \; v   \\ 
    394                 \zeta \; u - \lt[ \frac{1}{e_2} \pd[w]{j} - \frac{1}{e_3} \pd[v]{k} \rt] \ w 
    395     \end{array} 
    396                                                                                              \rt) 
    397           + \frac{1}{2} \lt( 
    398     \begin{array}{*{20}c} 
    399                              \frac{1}{e_1} \pd[(u^2 + v^2 + w^2)]{i} \\ 
    400                              \frac{1}{e_2} \pd[(u^2 + v^2 + w^2)]{j} 
    401     \end{array} 
    402                                                                      \rt) \\ 
    403   &    &=   &\lt( 
    404     \begin{array}{*{20}c} 
    405                   -\zeta \; v \\ 
    406                    \zeta \; u 
    407     \end{array} 
    408                               \rt) 
    409           + \frac{1}{2} \lt( 
    410     \begin{array}{*{20}c} 
    411                              \frac{1}{e_1} \pd[(u^2 + v^2)]{i} \\ 
    412                              \frac{1}{e_2} \pd[(u^2 + v^2)]{j} 
    413     \end{array} 
    414                                                                \rt) \\ 
    415   &    &  &+ \frac{1}{e_3} \lt( 
    416     \begin{array}{*{20}c} 
    417                                 w \; \pd[u]{k} \\ 
    418                                 w \; \pd[v]{k} 
    419     \end{array} 
    420                                                \rt) 
    421            - \lt( 
    422     \begin{array}{*{20}c} 
    423                   \frac{w}{e_1} \pd[w]{i} - \frac{1}{2 e_1} \pd[w^2]{i} \\ 
    424                   \frac{w}{e_2} \pd[w]{j} - \frac{1}{2 e_2} \pd[w^2]{j} 
    425     \end{array} 
    426                                                                         \rt) 
    427 \end{alignat*} 
    428 The last term of the right hand side is obviously zero, and thus the nonlinear term of 
    429 \autoref{eq:PE_dyn} is written in the $(i,j,k)$ coordinate system: 
     381$NLT$ the nonlinear term of \autoref{eq:MB_PE_dyn} can be transformed as follows: 
     382\begin{align*} 
     383  NLT &= \lt[ (\nabla \times {\vect U}) \times {\vect U} + \frac{1}{2} \nabla \lt( {\vect U}^2 \rt) \rt]_h \\ 
     384      &= \lt( 
     385        \begin{array}{*{20}c} 
     386          \lt[ \frac{1}{e_3} \pd[u]{k} - \frac{1}{e_1} \pd[w]{i} \rt] w - \zeta \; v   \\ 
     387          \zeta \; u - \lt[ \frac{1}{e_2} \pd[w]{j} - \frac{1}{e_3} \pd[v]{k} \rt] \ w 
     388        \end{array} 
     389  \rt) 
     390  + \frac{1}{2} \lt( 
     391  \begin{array}{*{20}c} 
     392    \frac{1}{e_1} \pd[(u^2 + v^2 + w^2)]{i} \\ 
     393    \frac{1}{e_2} \pd[(u^2 + v^2 + w^2)]{j} 
     394  \end{array} 
     395  \rt) \\ 
     396      &= \lt( 
     397        \begin{array}{*{20}c} 
     398          -\zeta \; v \\ 
     399          \zeta \; u 
     400        \end{array} 
     401  \rt) 
     402  + \frac{1}{2} \lt( 
     403  \begin{array}{*{20}c} 
     404    \frac{1}{e_1} \pd[(u^2 + v^2)]{i} \\ 
     405    \frac{1}{e_2} \pd[(u^2 + v^2)]{j} 
     406  \end{array} 
     407  \rt) 
     408  + \frac{1}{e_3} \lt( 
     409  \begin{array}{*{20}c} 
     410    w \; \pd[u]{k} \\ 
     411    w \; \pd[v]{k} 
     412  \end{array} 
     413  \rt) 
     414  - \lt( 
     415  \begin{array}{*{20}c} 
     416    \frac{w}{e_1} \pd[w]{i} - \frac{1}{2 e_1} \pd[w^2]{i} \\ 
     417    \frac{w}{e_2} \pd[w]{j} - \frac{1}{2 e_2} \pd[w^2]{j} 
     418  \end{array} 
     419  \rt) 
     420\end{align*} 
     421The last term of the right hand side is obviously zero, 
     422and thus the \textbf{N}on\textbf{L}inear \textbf{T}erm ($NLT$) of \autoref{eq:MB_PE_dyn} is written in 
     423the $(i,j,k)$ coordinate system: 
    430424\begin{equation} 
    431   \label{eq:PE_vector_form} 
    432   NLT =   \zeta \; \vect k \times \vect U_h + \frac{1}{2} \nabla_h \lt( \vect U_h^2 \rt) 
    433         + \frac{1}{e_3} w \pd[\vect U_h]{k} 
     425  \label{eq:MB_vector_form} 
     426  NLT = \zeta \; \vect k \times \vect U_h + \frac{1}{2} \nabla_h \lt( \vect U_h^2 \rt) + \frac{1}{e_3} w \pd[\vect U_h]{k} 
    434427\end{equation} 
    435428 
    436429This is the so-called \textit{vector invariant form} of the momentum advection term. 
    437430For some purposes, it can be advantageous to write this term in the so-called flux form, 
    438 \ie to write it as the divergence of fluxes. 
    439 For example, the first component of \autoref{eq:PE_vector_form} (the $i$-component) is transformed as follows: 
    440 \begin{alignat*}{2} 
     431\ie\ to write it as the divergence of fluxes. 
     432For example, 
     433the first component of \autoref{eq:MB_vector_form} (the $i$-component) is transformed as follows: 
     434\begin{alignat*}{3} 
    441435  &NLT_i &= &- \zeta \; v + \frac{1}{2 \; e_1} \pd[ (u^2 + v^2) ]{i} + \frac{1}{e_3} w \ \pd[u]{k} \\ 
    442   &      &=  &\frac{1}{e_1 \; e_2} \lt( -v \pd[(e_2 \, v)]{i} + v \pd[(e_1 \, u)]{j} \rt) 
    443             + \frac{1}{e_1 e_2} \lt( e_2 \; u \pd[u]{i} + e_2 \; v \pd[v]{i} \rt) \\ 
    444   &      & &+ \frac{1}{e_3} \lt( w \; \pd[u]{k} \rt) \\ 
    445   &      &=  &\frac{1}{e_1 \; e_2} \lt[ - \lt( v^2 \pd[e_2]{i} + e_2 \, v \pd[v]{i} \rt) 
    446                                      + \lt( \pd[ \lt( e_1 \, u \, v \rt)]{j} -         e_1 \, u \pd[v]{j} \rt) \rt. \\ 
    447   &      &                       &\lt. + \lt( \pd[ \lt( e_2 \, u \, u \rt)]{i} - u \pd[ \lt( e_2 u \rt)]{i} \rt) 
    448                                      + e_2 v \pd[v]{i}                                                         \rt] \\ 
     436  &      &= &\frac{1}{e_1 \; e_2} \lt( -v \pd[(e_2 \, v)]{i} + v \pd[(e_1 \, u)]{j} \rt) + \frac{1}{e_1 e_2} \lt( e_2 \; u \pd[u]{i} + e_2 \; v \pd[v]{i} \rt) + \frac{1}{e_3} \lt( w \; \pd[u]{k} \rt) \\ 
     437  &      &= &\frac{1}{e_1 \; e_2} \lt[ - \lt( v^2 \pd[e_2]{i} + e_2 \, v \pd[v]{i} \rt) + \lt( \pd[ \lt( e_1 \, u \, v \rt)]{j} - e_1 \, u \pd[v]{j} \rt) \rt. \lt. + \lt( \pd[ \lt( e_2 \, u \, u \rt)]{i} - u \pd[ \lt( e_2 u \rt)]{i} \rt) + e_2 v \pd[v]{i} \rt] \\ 
    449438  &      & &+ \frac{1}{e_3} \lt( \pd[(w \, u)]{k} - u \pd[w]{k} \rt) \\ 
    450   &      &=  &\frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, u)]{i} + \pd[(e_1 \, u \, v)]{j} \rt) 
    451             + \frac{1}{e_3} \pd[(w \, u)]{k} \\ 
    452   &      & &+ \frac{1}{e_1 e_2} \lt[ - u \lt( \pd[(e_1 v)]{j} - v \, \pd[e_1]{j} \rt) 
    453                                   - u \pd[(e_2 u)]{i}                              \rt] 
    454             - \frac{1}{e_3} \pd[w]{k} u \\ 
     439  &      &= &\frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, u)]{i} + \pd[(e_1 \, u \, v)]{j} \rt) + \frac{1}{e_3} \pd[(w \, u)]{k} + \frac{1}{e_1 e_2} \lt[ - u \lt( \pd[(e_1 v)]{j} - v \, \pd[e_1]{j} \rt) - u \pd[(e_2 u)]{i} \rt] - \frac{1}{e_3} \pd[w]{k} u \\ 
    455440  &      & &+ \frac{1}{e_1 e_2} \lt( - v^2 \pd[e_2]{i} \rt) \\ 
    456   &      &= &\nabla \cdot (\vect U \, u) - (\nabla \cdot \vect U) \ u 
    457             + \frac{1}{e_1 e_2} \lt( -v^2 \pd[e_2]{i} + u v \, \pd[e_1]{j} \rt) \\ 
    458   \intertext{as $\nabla \cdot {\vect U} \; = 0$ (incompressibility) it comes:} 
     441  &      &= &\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) \\ 
     442  \shortintertext{as $\nabla \cdot {\vect U} \; = 0$ (incompressibility) it becomes:} 
    459443  &      &= &\, \nabla \cdot (\vect U \, u) + \frac{1}{e_1 e_2} \lt( v \; \pd[e_2]{i} - u \; \pd[e_1]{j} \rt) (-v) 
    460444\end{alignat*} 
     
    462446The flux form of the momentum advection term is therefore given by: 
    463447\begin{equation} 
    464   \label{eq:PE_flux_form} 
    465   NLT =   \nabla \cdot \lt( 
    466     \begin{array}{*{20}c} 
    467                             \vect U \, u \\ 
    468                             \vect U \, v 
    469     \end{array} 
    470                                          \rt) 
    471         + \frac{1}{e_1 e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \vect k \times \vect U_h 
     448  \label{eq:MB_flux_form} 
     449  NLT = \nabla \cdot \lt( 
     450  \begin{array}{*{20}c} 
     451    \vect U \, u \\ 
     452    \vect U \, v 
     453  \end{array} 
     454  \rt) 
     455  + \frac{1}{e_1 e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \vect k \times \vect U_h 
    472456\end{equation} 
    473457 
    474458The flux form has two terms, 
    475 the first one is expressed as the divergence of momentum fluxes (hence the flux form name given to this formulation) 
    476 and the second one is due to the curvilinear nature of the coordinate system used. 
    477 The latter is called the \textit{metric} term and can be viewed as a modification of the Coriolis parameter:  
     459the first one is expressed as the divergence of momentum fluxes 
     460(hence the flux form name given to this formulation) and 
     461the second one is due to the curvilinear nature of the coordinate system used. 
     462The latter is called the \textit{metric} term and can be viewed as 
     463a modification of the Coriolis parameter: 
    478464\[ 
    479   % \label{eq:PE_cor+metric} 
     465  % \label{eq:MB_cor+metric} 
    480466  f \to f + \frac{1}{e_1 e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) 
    481467\] 
    482468 
    483469Note that in the case of geographical coordinate, 
    484 \ie when $(i,j) \to (\lambda,\varphi)$ and $(e_1,e_2) \to (a \, \cos \varphi,a)$, 
     470\ie\ when $(i,j) \to (\lambda,\varphi)$ and $(e_1,e_2) \to (a \, \cos \varphi,a)$, 
    485471we recover the commonly used modification of the Coriolis parameter $f \to f + (u / a) \tan \varphi$. 
    486472 
     
    488474the following tensorial formalism: 
    489475 
    490 \begin{itemize} 
    491 \item 
    492   \textbf{Vector invariant form of the momentum equations}: 
     476\begin{description} 
     477\item [Vector invariant form of the momentum equations] 
    493478  \begin{equation} 
    494     \label{eq:PE_dyn_vect} 
    495     \begin{split} 
    496     % \label{eq:PE_dyn_vect_u} 
    497       \pd[u]{t} = &+ (\zeta + f) \, v - \frac{1}{2 e_1} \pd[]{i} (u^2 + v^2) 
    498                    - \frac{1}{e_3} w \pd[u]{k} - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) \\ 
    499                   &+ D_u^{\vect U} + F_u^{\vect U} \\ 
    500       \pd[v]{t} = &- (\zeta + f) \, u - \frac{1}{2 e_2} \pd[]{j} (u^2 + v^2) 
    501                    - \frac{1}{e_3} w \pd[v]{k} - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) \\  
    502                   &+ D_v^{\vect U} + F_v^{\vect U} 
    503     \end{split} 
     479    \label{eq:MB_dyn_vect} 
     480    \begin{gathered} 
     481    % \label{eq:MB_dyn_vect_u} 
     482      \pd[u]{t} = + (\zeta + f) \, v - \frac{1}{2 e_1} \pd[]{i} (u^2 + v^2) - \frac{1}{e_3} w \pd[u]{k} - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) + D_u^{\vect U} + F_u^{\vect U} \\ 
     483      \pd[v]{t} = - (\zeta + f) \, u - \frac{1}{2 e_2} \pd[]{j} (u^2 + v^2) - \frac{1}{e_3} w \pd[v]{k} - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) + D_v^{\vect U} + F_v^{\vect U} 
     484    \end{gathered} 
    504485  \end{equation} 
    505 \item 
    506   \textbf{flux form of the momentum equations}: 
    507   % \label{eq:PE_dyn_flux} 
    508   \begin{multline*} 
    509     % \label{eq:PE_dyn_flux_u} 
    510     \pd[u]{t} = + \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, v \\ 
    511                 - \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, u)]{i} + \pd[(e_1 \, v \, u)]{j} \rt) \\ 
    512                 - \frac{1}{e_3} \pd[(w \, u)]{k} - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) 
    513                 + D_u^{\vect U} + F_u^{\vect U} 
    514   \end{multline*} 
    515   \begin{multline*} 
    516     % \label{eq:PE_dyn_flux_v} 
    517     \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 \\ 
    518                 + \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, v)]{i} + \pd[(e_1 \, v \, v)]{j} \rt) \\ 
    519                 - \frac{1}{e_3} \pd[(w \, v)]{k} - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) 
    520                 + D_v^{\vect U} + F_v^{\vect U} 
    521   \end{multline*} 
    522   where $\zeta$, the relative vorticity, is given by \autoref{eq:PE_curl_Uh} and $p_s$, the surface pressure, 
    523   is given by: 
     486\item [Flux form of the momentum equations] 
     487  % \label{eq:MB_dyn_flux} 
     488  \begin{alignat*}{2} 
     489    % \label{eq:MB_dyn_flux_u} 
     490    \pd[u]{t} = &+ \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, v - \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, u)]{i} + \pd[(e_1 \, v \, u)]{j} \rt) - \frac{1}{e_3} \pd[(w \, u)]{k} \\ 
     491    &- \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) + D_u^{\vect U} + F_u^{\vect U} 
     492  \end{alignat*} 
     493  \begin{alignat*}{2} 
     494    % \label{eq:MB_dyn_flux_v} 
     495    \pd[v]{t} = &- \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, u - \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, v)]{i} + \pd[(e_1 \, v \, v)]{j} \rt) - \frac{1}{e_3} \pd[(w \, v)]{k} \\ 
     496    &- \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) + D_v^{\vect U} + F_v^{\vect U} 
     497  \end{alignat*} 
     498  where $\zeta$, the relative vorticity, is given by \autoref{eq:MB_curl_Uh} and 
     499  $p_s$, the surface pressure, is given by: 
    524500  \[ 
    525   % \label{eq:PE_spg} 
     501  % \label{eq:MB_spg} 
    526502    p_s = \rho \,g \, \eta 
    527503  \] 
    528   with $\eta$ is solution of \autoref{eq:PE_ssh}. 
     504  and $\eta$ is the solution of \autoref{eq:MB_ssh}. 
    529505 
    530506  The vertical velocity and the hydrostatic pressure are diagnosed from the following equations: 
    531507  \[ 
    532   % \label{eq:w_diag} 
    533     \pd[w]{k} = - \chi \; e_3 \qquad  
    534   % \label{eq:hp_diag} 
     508  % \label{eq:MB_w_diag} 
     509    \pd[w]{k} = - \chi \; e_3 \qquad 
     510  % \label{eq:MB_hp_diag} 
    535511    \pd[p_h]{k} = - \rho \; g \; e_3 
    536512  \] 
    537   where the divergence of the horizontal velocity, $\chi$ is given by \autoref{eq:PE_div_Uh}. 
    538 \item \textit{tracer equations}: 
    539   \[ 
    540     %\label{eq:S} 
    541     \pd[T]{t} = - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 T \, u)]{i} + \pd[(e_1 T \, v)]{j} \rt] 
    542                 - \frac{1}{e_3} \pd[(T \, w)]{k} + D^T + F^T \\ 
    543     %\label{eq:T} 
    544     \pd[S]{t} = - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 S \, u)]{i} + \pd[(e_1 S \, v)]{j} \rt] 
    545                 - \frac{1}{e_3} \pd[(S \, w)]{k} + D^S + F^S 
    546     %\label{eq:rho} 
     513  where the divergence of the horizontal velocity, $\chi$ is given by \autoref{eq:MB_div_Uh}. 
     514\item [Tracer equations] 
     515  \begin{gather*} 
     516    \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 \\ 
     517    \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 \\ 
    547518    \rho = \rho \big( T,S,z(k) \big) 
    548   \] 
    549 \end{itemize} 
    550  
    551 The expression of $\vect D^{U}$, $D^{S}$ and $D^{T}$ depends on the subgrid scale parameterisation used. 
    552 It will be defined in \autoref{eq:PE_zdf}. 
     519  \end{gather*} 
     520\end{description} 
     521 
     522The expression of $\vect D^{U}$, $D^{S}$ and $D^{T}$ depends on 
     523the subgrid scale parameterisation used. 
     524It will be defined in \autoref{eq:MB_zdf}. 
    553525The nature and formulation of $\vect F^{\vect U}$, $F^T$ and $F^S$, the surface forcing terms, 
    554526are discussed in \autoref{chap:SBC}. 
    555527 
    556 \newpage 
    557  
    558 % ================================================================ 
    559 % Curvilinear generalised vertical coordinate System 
    560 % ================================================================ 
     528%% ================================================================================================= 
    561529\section{Curvilinear generalised vertical coordinate system} 
    562 \label{sec:PE_gco} 
     530\label{sec:MB_gco} 
    563531 
    564532The ocean domain presents a huge diversity of situation in the vertical. 
     
    567535varying from more than 6,000 meters in abyssal trenches to zero at the coast. 
    568536Last but not least, the ocean stratification exerts a strong barrier to vertical motions and mixing. 
    569 Therefore, in order to represent the ocean with respect to 
    570 the first point a space and time dependent vertical coordinate that follows the variation of the sea surface height 
    571 \eg an \zstar-coordinate; 
    572 for the second point, a space variation to fit the change of bottom topography 
    573 \eg a terrain-following or $\sigma$-coordinate; 
    574 and for the third point, one will be tempted to use a space and time dependent coordinate that 
    575 follows the isopycnal surfaces, \eg an isopycnic coordinate. 
    576  
    577 In order to satisfy two or more constrains one can even be tempted to mixed these coordinate systems, as in 
    578 HYCOM (mixture of $z$-coordinate at the surface, isopycnic coordinate in the ocean interior and $\sigma$ at 
    579 the ocean bottom) \citep{Chassignet_al_JPO03} or 
    580 OPA (mixture of $z$-coordinate in vicinity the surface and steep topography areas and $\sigma$-coordinate elsewhere) 
    581 \citep{Madec_al_JPO96} among others. 
     537Therefore, in order to represent the ocean with respect to the first point 
     538a space and time dependent vertical coordinate that follows the variation of the sea surface height 
     539\eg\ an \zstar-coordinate; 
     540for the second point, 
     541a space variation to fit the change of bottom topography 
     542\eg\ a terrain-following or $\sigma$-coordinate; 
     543and for the third point, 
     544one will be tempted to use a space and time dependent coordinate that follows the isopycnal surfaces, 
     545\eg\ an isopycnic coordinate. 
     546 
     547In order to satisfy two or more constraints one can even be tempted to mixed these coordinate systems, 
     548as in HYCOM (mixture of $z$-coordinate at the surface, isopycnic coordinate in the ocean interior and 
     549$\sigma$ at the ocean bottom) \citep{chassignet.smith.ea_JPO03} or 
     550OPA (mixture of $z$-coordinate in vicinity the surface and steep topography areas and 
     551$\sigma$-coordinate elsewhere) \citep{madec.delecluse.ea_JPO96} among others. 
    582552 
    583553In fact one is totally free to choose any space and time vertical coordinate by 
    584554introducing an arbitrary vertical coordinate : 
    585555\begin{equation} 
    586   \label{eq:PE_s} 
     556  \label{eq:MB_s} 
    587557  s = s(i,j,k,t) 
    588558\end{equation} 
    589 with the restriction that the above equation gives a single-valued monotonic relationship between $s$ and $k$, 
    590 when $i$, $j$ and $t$ are held fixed. 
    591 \autoref{eq:PE_s} is a transformation from the $(i,j,k,t)$ coordinate system with independent variables into 
     559with the restriction that the above equation gives a single-valued monotonic relationship between 
     560$s$ and $k$, when $i$, $j$ and $t$ are held fixed. 
     561\autoref{eq:MB_s} is a transformation from 
     562the $(i,j,k,t)$ coordinate system with independent variables into 
    592563the $(i,j,s,t)$ generalised coordinate system with $s$ depending on the other three variables through 
    593 \autoref{eq:PE_s}. 
    594 This so-called \textit{generalised vertical coordinate} \citep{Kasahara_MWR74} is in fact 
    595 an Arbitrary Lagrangian--Eulerian (ALE) coordinate. 
    596 Indeed, choosing an expression for $s$ is an arbitrary choice that determines 
    597 which part of the vertical velocity (defined from a fixed referential) will cross the levels (Eulerian part) and 
    598 which part will be used to move them (Lagrangian part). 
    599 The coordinate is also sometime referenced as an adaptive coordinate \citep{Hofmeister_al_OM09}, 
    600 since the coordinate system is adapted in the course of the simulation. 
     564\autoref{eq:MB_s}. 
     565This so-called \textit{generalised vertical coordinate} \citep{kasahara_MWR74} is in fact 
     566an \textbf{A}rbitrary \textbf{L}agrangian--\textbf{E}ulerian (ALE) coordinate. 
     567Indeed, one has a great deal of freedom in the choice of expression for $s$. 
     568The choice determines which part of the vertical velocity (defined from a fixed referential) 
     569will cross the levels (Eulerian part) and which part will be used to move them (Lagrangian part). 
     570The coordinate is also sometimes referenced as an adaptive coordinate 
     571\citep{hofmeister.burchard.ea_OM10}, since the coordinate system is adapted in 
     572the course of the simulation. 
    601573Its most often used implementation is via an ALE algorithm, 
    602574in which a pure lagrangian step is followed by regridding and remapping steps, 
    603 the later step implicitly embedding the vertical advection 
    604 \citep{Hirt_al_JCP74, Chassignet_al_JPO03, White_al_JCP09}. 
    605 Here we follow the \citep{Kasahara_MWR74} strategy: 
    606 a regridding step (an update of the vertical coordinate) followed by an eulerian step with 
     575the latter step implicitly embedding the vertical advection 
     576\citep{hirt.amsden.ea_JCP74, chassignet.smith.ea_JPO03, white.adcroft.ea_JCP09}. 
     577Here we follow the \citep{kasahara_MWR74} strategy: 
     578a regridding step (an update of the vertical coordinate) followed by an Eulerian step with 
    607579an explicit computation of vertical advection relative to the moving s-surfaces. 
    608580 
    609 %\gmcomment{ 
    610 %A key point here is that the $s$-coordinate depends on $(i,j)$ ==> horizontal pressure gradient... 
    611 the generalized vertical coordinates used in ocean modelling are not orthogonal, 
     581\cmtgm{A key point here is that the $s$-coordinate depends on $(i,j)$ 
     582  ==> horizontal pressure gradient...} 
     583The generalized vertical coordinates used in ocean modelling are not orthogonal, 
    612584which contrasts with many other applications in mathematical physics. 
    613585Hence, it is useful to keep in mind the following properties that may seem odd on initial encounter. 
     
    615587The horizontal velocity in ocean models measures motions in the horizontal plane, 
    616588perpendicular to the local gravitational field. 
    617 That is, horizontal velocity is mathematically the same regardless the vertical coordinate, be it geopotential, 
    618 isopycnal, pressure, or terrain following. 
     589That is, horizontal velocity is mathematically the same regardless of the vertical coordinate, 
     590be it geopotential, isopycnal, pressure, or terrain following. 
    619591The key motivation for maintaining the same horizontal velocity component is that 
    620592the hydrostatic and geostrophic balances are dominant in the large-scale ocean. 
    621 Use of an alternative quasi -horizontal velocity, for example one oriented parallel to the generalized surface, 
     593Use of an alternative quasi -horizontal velocity, 
     594for example one oriented parallel to the generalized surface, 
    622595would lead to unacceptable numerical errors. 
    623596Correspondingly, the vertical direction is anti -parallel to the gravitational force in 
     
    626599the surface of a constant generalized vertical coordinate. 
    627600 
    628 It is the method used to measure transport across the generalized vertical coordinate surfaces which differs between 
    629 the vertical coordinate choices. 
    630 That is, computation of the dia-surface velocity component represents the fundamental distinction between 
     601It is the method used to measure transport across the generalized vertical coordinate surfaces which 
     602differs between the vertical coordinate choices. 
     603That is, 
     604computation of the dia-surface velocity component represents the fundamental distinction between 
    631605the various coordinates. 
    632 In some models, such as geopotential, pressure, and terrain following, this transport is typically diagnosed from 
    633 volume or mass conservation. 
    634 In other models, such as isopycnal layered models, this transport is prescribed based on assumptions about 
    635 the physical processes producing a flux across the layer interfaces. 
     606In some models, such as geopotential, pressure, and terrain following, 
     607this transport is typically diagnosed from volume or mass conservation. 
     608In other models, such as isopycnal layered models, 
     609this transport is prescribed based on assumptions about the physical processes producing 
     610a flux across the layer interfaces. 
    636611 
    637612In this section we first establish the PE in the generalised vertical $s$-coordinate, 
     
    639614%} 
    640615 
    641 % ------------------------------------------------------------------------------------------------------------- 
    642 % The s-coordinate Formulation 
    643 % ------------------------------------------------------------------------------------------------------------- 
     616%% ================================================================================================= 
    644617\subsection{\textit{S}-coordinate formulation} 
    645618 
    646 Starting from the set of equations established in \autoref{sec:PE_zco} for the special case $k = z$ and 
    647 thus $e_3 = 1$, we introduce an arbitrary vertical coordinate $s = s(i,j,k,t)$, 
     619Starting from the set of equations established in \autoref{sec:MB_zco} for 
     620the special case $k = z$ and thus $e_3 = 1$, 
     621we introduce an arbitrary vertical coordinate $s = s(i,j,k,t)$, 
    648622which includes $z$-, \zstar- and $\sigma$-coordinates as special cases 
    649623($s = z$, $s = \zstar$, and $s = \sigma = z / H$ or $ = z / \lt( H + \eta \rt)$, resp.). 
    650 A formal derivation of the transformed equations is given in \autoref{apdx:A}. 
    651 Let us define the vertical scale factor by $e_3 = \partial_s z$  ($e_3$ is now a function of $(i,j,k,t)$ ), 
     624A formal derivation of the transformed equations is given in \autoref{apdx:SCOORD}. 
     625Let us define the vertical scale factor by $e_3 = \partial_s z$ 
     626($e_3$ is now a function of $(i,j,k,t)$ ), 
    652627and the slopes in the $(i,j)$ directions between $s$- and $z$-surfaces by: 
    653628\begin{equation} 
    654   \label{eq:PE_sco_slope} 
     629  \label{eq:MB_sco_slope} 
    655630  \sigma_1 = \frac{1}{e_1} \; \lt. \pd[z]{i} \rt|_s \quad \text{and} \quad 
    656631  \sigma_2 = \frac{1}{e_2} \; \lt. \pd[z]{j} \rt|_s 
    657632\end{equation} 
    658 We also introduce $\omega$, a dia-surface velocity component, defined as the velocity  
    659 relative to the moving $s$-surfaces and normal to them: 
     633We also introduce $\omega$, a dia-surface velocity component, 
     634defined as the velocity relative to the moving $s$-surfaces and normal to them: 
    660635\[ 
    661   % \label{eq:PE_sco_w} 
    662   \omega = w - e_3 \, \pd[s]{t} - \sigma_1 \, u - \sigma_2 \, v 
     636  % \label{eq:MB_sco_w} 
     637  \omega = w -  \, \lt. \pd[z]{t} \rt|_s - \sigma_1 \, u - \sigma_2 \, v 
    663638\] 
    664639 
    665 The equations solved by the ocean model \autoref{eq:PE} in $s$-coordinate can be written as follows 
    666 (see \autoref{sec:A_momentum}): 
    667  
    668 \begin{itemize} 
    669 \item \textbf{Vector invariant form of the momentum equation}: 
    670   \begin{multline*} 
    671   % \label{eq:PE_sco_u_vector} 
    672     \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} \\ 
    673                 - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) + g \frac{\rho}{\rho_o} \sigma_1 
    674                 + D_u^{\vect U} + F_u^{\vect U} 
    675   \end{multline*} 
    676   \begin{multline*} 
    677   % \label{eq:PE_sco_v_vector} 
    678     \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} \\ 
    679                 - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) + g \frac{\rho}{\rho_o} \sigma_2 
    680                 + D_v^{\vect U} + F_v^{\vect U} 
    681   \end{multline*} 
    682 \item \textbf{Flux form of the momentum equation}: 
    683   \begin{multline*} 
    684   % \label{eq:PE_sco_u_flux} 
    685     \frac{1}{e_3} \pd[(e_3 \, u)]{t} = + \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, v \\ 
    686                                        - \frac{1}{e_1 \; e_2 \; e_3} \lt( \pd[(e_2 \, e_3 \, u \, u)]{i} + \pd[(e_1 \, e_3 \, v \, u)]{j} \rt) \\ 
    687                                        - \frac{1}{e_3} \pd[(\omega \, u)]{k} 
    688                                        - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) 
    689                                        + g \frac{\rho}{\rho_o} \sigma_1 + D_u^{\vect U} + F_u^{\vect U} 
    690   \end{multline*} 
    691   \begin{multline*} 
    692   % \label{eq:PE_sco_v_flux} 
    693     \frac{1}{e_3} \pd[(e_3 \, v)]{t} = - \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, u \\ 
    694                                        - \frac{1}{e_1 \; e_2 \; e_3} \lt( \pd[( e_2 \; e_3 \, u \, v)]{i} + \pd[(e_1 \; e_3 \, v \, v)]{j} \rt) \\ 
    695                                        - \frac{1}{e_3} \pd[(\omega \, v)]{k} 
    696                                        - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) 
    697                                        + g \frac{\rho}{\rho_o}\sigma_2 + D_v^{\vect U} + F_v^{\vect U} 
    698   \end{multline*} 
     640The equations solved by the ocean model \autoref{eq:MB_PE} in $s$-coordinate can be written as follows 
     641(see \autoref{sec:SCOORD_momentum}): 
     642 
     643\begin{description} 
     644\item [Vector invariant form of the momentum equation] 
     645  \begin{gather*} 
     646    % \label{eq:MB_sco_u_vector} 
     647    \pd[u]{t} = + (\zeta + f) \, v - \frac{1}{2 \, e_1} \pd[]{i} (u^2 + v^2) - \frac{1}{e_3} \omega \pd[u]{k} - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) - g \frac{\rho}{\rho_o} \sigma_1 + D_u^{\vect U} + F_u^{\vect U} \\ 
     648    % \label{eq:MB_sco_v_vector} 
     649    \pd[v]{t} = - (\zeta + f) \, u - \frac{1}{2 \, e_2} \pd[]{j} (u^2 + v^2) - \frac{1}{e_3} \omega \pd[v]{k} - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) - g \frac{\rho}{\rho_o} \sigma_2 + D_v^{\vect U} + F_v^{\vect U} 
     650  \end{gather*} 
     651\item [Flux form of the momentum equation] 
     652  \begin{alignat*}{2} 
     653    % \label{eq:MB_sco_u_flux} 
     654    \frac{1}{e_3} \pd[(e_3 \, u)]{t} = &+ \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, v - \frac{1}{e_1 \; e_2 \; e_3} \lt( \pd[(e_2 \, e_3 \, u \, u)]{i} + \pd[(e_1 \, e_3 \, v \, u)]{j} \rt) - \frac{1}{e_3} \pd[(\omega \, u)]{k} \\ 
     655    &- \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} 
     656  \end{alignat*} 
     657  \begin{alignat*}{2} 
     658  % \label{eq:MB_sco_v_flux} 
     659    \frac{1}{e_3} \pd[(e_3 \, v)]{t} = &- \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, u - \frac{1}{e_1 \; e_2 \; e_3} \lt( \pd[( e_2 \; e_3 \, u \, v)]{i} + \pd[(e_1 \; e_3 \, v \, v)]{j} \rt) - \frac{1}{e_3} \pd[(\omega \, v)]{k} \\ 
     660    &- \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} 
     661  \end{alignat*} 
    699662  where the relative vorticity, $\zeta$, the surface pressure gradient, 
    700663  and the hydrostatic pressure have the same expressions as in $z$-coordinates although 
    701664  they do not represent exactly the same quantities. 
    702   $\omega$ is provided by the continuity equation (see \autoref{apdx:A}): 
     665  $\omega$ is provided by the continuity equation (see \autoref{apdx:SCOORD}): 
    703666  \[ 
    704   % \label{eq:PE_sco_continuity} 
     667  % \label{eq:MB_sco_continuity} 
    705668    \pd[e_3]{t} + e_3 \; \chi + \pd[\omega]{s} = 0 \quad \text{with} \quad 
    706669    \chi = \frac{1}{e_1 e_2 e_3} \lt( \pd[(e_2 e_3 \, u)]{i} + \pd[(e_1 e_3 \, v)]{j} \rt) 
    707670  \] 
    708 \item \textit{tracer equations}: 
    709   \begin{multline*} 
    710   % \label{eq:PE_sco_t} 
    711     \frac{1}{e_3} \pd[(e_3 \, T)]{t} = - \frac{1}{e_1 e_2 e_3} \lt(   \pd[(e_2 e_3 \, u \, T)]{i} 
    712                                                                     + \pd[(e_1 e_3 \, v \, T)]{j} \rt) \\ 
    713                                        - \frac{1}{e_3} \pd[(T \, \omega)]{k} + D^T + F^S 
    714   \end{multline*} 
    715   \begin{multline} 
    716   % \label{eq:PE_sco_s} 
    717     \frac{1}{e_3} \pd[(e_3 \, S)]{t} = - \frac{1}{e_1 e_2 e_3} \lt(   \pd[(e_2 e_3 \, u \, S)]{i} 
    718                                                                     + \pd[(e_1 e_3 \, v \, S)]{j} \rt) \\ 
    719                                        - \frac{1}{e_3} \pd[(S \, \omega)]{k} + D^S + F^S 
    720   \end{multline} 
    721 \end{itemize} 
     671\item [Tracer equations] 
     672  \begin{gather*} 
     673    % \label{eq:MB_sco_t} 
     674    \frac{1}{e_3} \pd[(e_3 \, T)]{t} = - \frac{1}{e_1 e_2 e_3} \lt(   \pd[(e_2 e_3 \, u \, T)]{i} + \pd[(e_1 e_3 \, v \, T)]{j} \rt) - \frac{1}{e_3} \pd[(T \, \omega)]{k} + D^T + F^S \\ 
     675    % \label{eq:MB_sco_s} 
     676    \frac{1}{e_3} \pd[(e_3 \, S)]{t} = - \frac{1}{e_1 e_2 e_3} \lt(   \pd[(e_2 e_3 \, u \, S)]{i} + \pd[(e_1 e_3 \, v \, S)]{j} \rt) - \frac{1}{e_3} \pd[(S \, \omega)]{k} + D^S + F^S 
     677  \end{gather*} 
     678\end{description} 
    722679The equation of state has the same expression as in $z$-coordinate, 
    723680and similar expressions are used for mixing and forcing terms. 
    724681 
    725 \gmcomment{ 
     682\cmtgm{ 
    726683  \colorbox{yellow}{ to be updated $= = >$} 
    727684  Add a few works on z and zps and s and underlies the differences between all of them 
     
    729686} 
    730687 
    731 % ------------------------------------------------------------------------------------------------------------- 
    732 % Curvilinear \zstar-coordinate System 
    733 % ------------------------------------------------------------------------------------------------------------- 
     688%% ================================================================================================= 
    734689\subsection{Curvilinear \zstar-coordinate system} 
    735 \label{subsec:PE_zco_star} 
    736  
    737 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    738 \begin{figure}[!b] 
    739   \begin{center} 
    740     \includegraphics[]{Fig_z_zstar} 
    741     \caption{ 
    742       \protect\label{fig:z_zstar} 
    743       (a) $z$-coordinate in linear free-surface case ; 
    744       (b) $z$-coordinate in non-linear free surface case ; 
    745       (c) re-scaled height coordinate 
    746       (become popular as the \zstar-coordinate \citep{Adcroft_Campin_OM04}). 
    747     } 
    748   \end{center} 
     690\label{subsec:MB_zco_star} 
     691 
     692\begin{figure} 
     693  \centering 
     694  \includegraphics[width=0.66\textwidth]{MB_z_zstar} 
     695  \caption[Curvilinear z-coordinate systems (\{non-\}linear free-surface cases and re-scaled \zstar)]{ 
     696    \begin{enumerate*}[label=(\textit{\alph*})] 
     697    \item $z$-coordinate in linear free-surface case; 
     698    \item $z$-coordinate in non-linear free surface case; 
     699    \item re-scaled height coordinate 
     700      (become popular as the \zstar-coordinate \citep{adcroft.campin_OM04}). 
     701    \end{enumerate*} 
     702  } 
     703  \label{fig:MB_z_zstar} 
    749704\end{figure} 
    750 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    751  
    752 In that case, the free surface equation is nonlinear, and the variations of volume are fully taken into account. 
    753 These coordinates systems is presented in a report \citep{Levier2007} available on the \NEMO web site. 
    754  
    755 The \zstar coordinate approach is an unapproximated, non-linear free surface implementation which allows one to 
    756 deal with large amplitude free-surface variations relative to the vertical resolution \citep{Adcroft_Campin_OM04}. 
    757 In the \zstar formulation, 
    758 the variation of the column thickness due to sea-surface undulations is not concentrated in the surface level, 
    759 as in the $z$-coordinate formulation, but is equally distributed over the full water column. 
     705 
     706In this case, the free surface equation is nonlinear, 
     707and the variations of volume are fully taken into account. 
     708These coordinates systems is presented in a report \citep{levier.treguier.ea_rpt07} available on 
     709the \NEMO\ web site. 
     710 
     711The \zstar\ coordinate approach is an unapproximated, non-linear free surface implementation which 
     712allows one to deal with large amplitude free-surface variations relative to the vertical resolution 
     713\citep{adcroft.campin_OM04}. 
     714In the \zstar\ formulation, the variation of the column thickness due to sea-surface undulations is 
     715not concentrated in the surface level, as in the $z$-coordinate formulation, 
     716but is equally distributed over the full water column. 
    760717Thus vertical levels naturally follow sea-surface variations, with a linear attenuation with depth, 
    761 as illustrated by \autoref{fig:z_zstar}. 
    762 Note that with a flat bottom, such as in \autoref{fig:z_zstar}, the bottom-following $z$ coordinate and \zstar are equivalent. 
     718as illustrated by \autoref{fig:MB_z_zstar}. 
     719Note that with a flat bottom, such as in \autoref{fig:MB_z_zstar}, 
     720the bottom-following $z$ coordinate and \zstar\ are equivalent. 
    763721The definition and modified oceanic equations for the rescaled vertical coordinate \zstar, 
    764722including the treatment of fresh-water flux at the surface, are detailed in Adcroft and Campin (2004). 
    765723The major points are summarized here. 
    766 The position (\zstar) and vertical discretization (\zstar) are expressed as: 
     724The position (\zstar) and vertical discretization ($\delta \zstar$) are expressed as: 
    767725\[ 
    768   % \label{eq:z-star} 
    769   H + \zstar = (H + z)  / r \quad \text{and}  \quad \delta \zstar 
    770               = \delta z / r \quad \text{with} \quad r 
    771               = \frac{H + \eta}{H} 
     726  % \label{eq:MB_z-star} 
     727  H + \zstar = (H + z)  / r \quad \text{and}  \quad \delta \zstar = \delta z / r \quad \text{with} \quad r = \frac{H + \eta}{H} 
     728\] 
     729Simple re-organisation of the above expressions gives 
     730\[ 
     731  % \label{eq:MB_zstar_2} 
     732  \zstar = H \lt( \frac{z - \eta}{H + \eta} \rt) 
    772733\] 
    773734Since the vertical displacement of the free surface is incorporated in the vertical coordinate \zstar, 
    774 the upper and lower boundaries are at fixed  \zstar position, 
     735the upper and lower boundaries are at fixed \zstar\ position, 
    775736$\zstar = 0$ and $\zstar = -H$ respectively. 
    776737Also the divergence of the flow field is no longer zero as shown by the continuity equation: 
    777738\[ 
    778   \pd[r]{t} = \nabla_{\zstar} \cdot \lt( r \; \vect U_h \rt) (r \; w *) = 0 
     739  \pd[r]{t} = \nabla_{\zstar} \cdot \lt( r \; \vect U_h \rt) + \pd[r \; w^*]{\zstar} = 0 
    779740\] 
    780  
    781 % from MOM4p1 documentation 
    782 To overcome problems with vanishing surface and/or bottom cells, we consider the zstar coordinate  
    783 \[ 
    784   % \label{eq:PE_} 
    785   \zstar = H \lt( \frac{z - \eta}{H + \eta} \rt) 
    786 \] 
    787  
    788 This coordinate is closely related to the "eta" coordinate used in many atmospheric models 
    789 (see Black (1994) for a review of eta coordinate atmospheric models). 
     741This \zstar\ coordinate is closely related to the $\eta$ coordinate used in many atmospheric models 
     742(see Black (1994) for a review of $\eta$ coordinate atmospheric models). 
    790743It was originally used in ocean models by Stacey et al. (1995) for studies of tides next to shelves, 
    791744and it has been recently promoted by Adcroft and Campin (2004) for global climate modelling. 
    792745 
    793 The surfaces of constant \zstar are quasi -horizontal. 
    794 Indeed, the \zstar coordinate reduces to $z$ when $\eta$ is zero. 
     746The surfaces of constant \zstar\ are quasi-horizontal. 
     747Indeed, the \zstar\ coordinate reduces to $z$ when $\eta$ is zero. 
    795748In general, when noting the large differences between 
    796749undulations of the bottom topography versus undulations in the surface height, 
    797 it is clear that surfaces constant \zstar are very similar to the depth surfaces. 
     750it is clear that surfaces constant \zstar\ are very similar to the depth surfaces. 
    798751These properties greatly reduce difficulties of computing the horizontal pressure gradient relative to 
    799 terrain following sigma models discussed in \autoref{subsec:PE_sco}. 
    800 Additionally, since \zstar when $\eta = 0$, 
    801 no flow is spontaneously generated in an unforced ocean starting from rest, regardless the bottom topography. 
    802 This behaviour is in contrast to the case with "s"-models, where pressure gradient errors in the presence of 
    803 nontrivial topographic variations can generate nontrivial spontaneous flow from a resting state, 
     752terrain following sigma models discussed in \autoref{subsec:MB_sco}. 
     753Additionally, since $\zstar = z$ when $\eta = 0$, 
     754no flow is spontaneously generated in an unforced ocean starting from rest, 
     755regardless the bottom topography. 
     756This behaviour is in contrast to the case with ``s''-models, 
     757where pressure gradient errors in the presence of nontrivial topographic variations can generate 
     758nontrivial spontaneous flow from a resting state, 
    804759depending on the sophistication of the pressure gradient solver. 
    805 The quasi -horizontal nature of the coordinate surfaces also facilitates the implementation of 
    806 neutral physics parameterizations in \zstar models using the same techniques as in $z$-models 
    807 (see Chapters 13-16 of \cite{Griffies_Bk04}) for a discussion of neutral physics in $z$-models, 
     760The quasi-horizontal nature of the coordinate surfaces also facilitates the implementation of 
     761neutral physics parameterizations in \zstar\ models using the same techniques as in $z$-models 
     762(see Chapters 13-16 of \cite{griffies_bk04}) for a discussion of neutral physics in $z$-models, 
    808763as well as \autoref{sec:LDF_slp} in this document for treatment in \NEMO). 
    809764 
    810 The range over which \zstar varies is time independent $-H \leq \zstar \leq 0$. 
    811 Hence, all cells remain nonvanishing, so long as the surface height maintains $\eta > ?H$. 
    812 This is a minor constraint relative to that encountered on the surface height when using $s = z$ or $s = z - \eta$. 
    813  
    814 Because \zstar has a time independent range, all grid cells have static increments ds, 
    815 and the sum of the ver tical increments yields the time independent ocean depth. %k ds = H. 
    816 The \zstar coordinate is therefore invisible to undulations of the free surface, 
     765The range over which \zstar\ varies is time independent $-H \leq \zstar \leq 0$. 
     766Hence, all cells remain nonvanishing, so long as the surface height maintains $\eta > -H$. 
     767This is a minor constraint relative to that encountered on the surface height when 
     768using $s = z$ or $s = z - \eta$. 
     769 
     770Because \zstar\ has a time independent range, all grid cells have static increments ds, 
     771and the sum of the vertical increments yields the time independent ocean depth. %k ds = H. 
     772The \zstar\ coordinate is therefore invisible to undulations of the free surface, 
    817773since it moves along with the free surface. 
    818 This proper ty means that no spurious vertical transport is induced across surfaces of constant \zstar by 
    819 the motion of external gravity waves. 
    820 Such spurious transpor t can be a problem in z-models, especially those with tidal forcing. 
    821 Quite generally, the time independent range for the \zstar coordinate is a very convenient property that 
    822 allows for a nearly arbitrary ver tical resolution even in the presence of large amplitude fluctuations of 
    823 the surface height, again so long as $\eta > -H$. 
     774This property means that no spurious vertical transport is induced across 
     775surfaces of constant \zstar\  by the motion of external gravity waves. 
     776Such spurious transport can be a problem in z-models, especially those with tidal forcing. 
     777Quite generally, 
     778the time independent range for the \zstar\ coordinate is a very convenient property that 
     779allows for a nearly arbitrary vertical resolution even in 
     780the presence of large amplitude fluctuations of the surface height, again so long as $\eta > -H$. 
    824781%end MOM doc %%% 
    825782 
    826 \newpage  
    827  
    828 % ------------------------------------------------------------------------------------------------------------- 
    829 % Terrain following  coordinate System 
    830 % ------------------------------------------------------------------------------------------------------------- 
     783%% ================================================================================================= 
    831784\subsection{Curvilinear terrain-following \textit{s}--coordinate} 
    832 \label{subsec:PE_sco} 
    833  
    834 % ------------------------------------------------------------------------------------------------------------- 
    835 % Introduction 
    836 % ------------------------------------------------------------------------------------------------------------- 
    837 \subsubsection{Introduction} 
     785\label{subsec:MB_sco} 
    838786 
    839787Several important aspects of the ocean circulation are influenced by bottom topography. 
    840 Of course, the most important is that bottom topography determines deep ocean sub-basins, barriers, sills and 
    841 channels that strongly constrain the path of water masses, but more subtle effects exist. 
    842 For example, the topographic $\beta$-effect is usually larger than the planetary one along continental slopes. 
     788Of course, the most important is that bottom topography determines deep ocean sub-basins, barriers, 
     789sills and channels that strongly constrain the path of water masses, but more subtle effects exist. 
     790For example, 
     791the topographic $\beta$-effect is usually larger than the planetary one along continental slopes. 
    843792Topographic Rossby waves can be excited and can interact with the mean current. 
    844 In the $z$-coordinate system presented in the previous section (\autoref{sec:PE_zco}), 
     793In the $z$-coordinate system presented in the previous section (\autoref{sec:MB_zco}), 
    845794$z$-surfaces are geopotential surfaces. 
    846795The bottom topography is discretised by steps. 
     
    848797large localized depth gradients associated with large localized vertical velocities. 
    849798The response to such a velocity field often leads to numerical dispersion effects. 
    850 One solution to strongly reduce this error is to use a partial step representation of bottom topography instead of 
    851 a full step one \cite{Pacanowski_Gnanadesikan_MWR98}. 
     799One solution to strongly reduce this error is to use a partial step representation of 
     800bottom topography instead of a full step one \cite{pacanowski.gnanadesikan_MWR98}. 
    852801Another solution is to introduce a terrain-following coordinate system (hereafter $s$-coordinate). 
    853802 
    854 The $s$-coordinate avoids the discretisation error in the depth field since the layers of 
    855 computation are gradually adjusted with depth to the ocean bottom. 
    856 Relatively small topographic features as well as  gentle, large-scale slopes of the sea floor in the deep ocean, 
    857 which would be ignored in typical $z$-model applications with the largest grid spacing at greatest depths, 
     803The $s$-coordinate avoids the discretisation error in the depth field since 
     804the layers of computation are gradually adjusted with depth to the ocean bottom. 
     805Relatively small topographic features as well as 
     806gentle, large-scale slopes of the sea floor in the deep ocean, 
     807which would be ignored in typical $z$-model applications with 
     808the largest grid spacing at greatest depths, 
    858809can easily be represented (with relatively low vertical resolution). 
    859 A terrain-following model (hereafter $s$-model) also facilitates the modelling of the boundary layer flows over 
    860 a large depth range, which in the framework of the $z$-model would require high vertical resolution over 
     810A terrain-following model (hereafter $s$-model) also facilitates 
     811the modelling of the boundary layer flows over a large depth range, 
     812which in the framework of the $z$-model would require high vertical resolution over 
    861813the whole depth range. 
    862 Moreover, with a $s$-coordinate it is possible, at least in principle, to have the bottom and the sea surface as 
     814Moreover, 
     815with a $s$-coordinate it is possible, at least in principle, to have the bottom and the sea surface as 
    863816the only boundaries of the domain (no more lateral boundary condition to specify). 
    864 Nevertheless, a $s$-coordinate also has its drawbacks. Perfectly adapted to a homogeneous ocean, 
     817Nevertheless, a $s$-coordinate also has its drawbacks. 
     818Perfectly adapted to a homogeneous ocean, 
    865819it has strong limitations as soon as stratification is introduced. 
    866820The main two problems come from the truncation error in the horizontal pressure gradient and 
    867821a possibly increased diapycnal diffusion. 
    868 The horizontal pressure force in $s$-coordinate consists of two terms (see \autoref{apdx:A}), 
    869  
     822The horizontal pressure force in $s$-coordinate consists of two terms (see \autoref{apdx:SCOORD}), 
    870823\begin{equation} 
    871   \label{eq:PE_p_sco} 
    872   \nabla p |_z = \nabla p |_s - \pd[p]{s} \nabla z |_s 
     824  \label{eq:MB_p_sco} 
     825  \nabla p |_z = \nabla p |_s - \frac{1}{e_3} \pd[p]{s} \nabla z |_s 
    873826\end{equation} 
    874827 
    875 The second term in \autoref{eq:PE_p_sco} depends on the tilt of the coordinate surface and 
    876 introduces a truncation error that is not present in a $z$-model. 
    877 In the special case of a $\sigma$-coordinate (i.e. a depth-normalised coordinate system $\sigma = z/H$), 
    878 \citet{Haney1991} and \citet{Beckmann1993} have given estimates of the magnitude of this truncation error. 
    879 It depends on topographic slope, stratification, horizontal and vertical resolution, the equation of state, 
    880 and the finite difference scheme. 
     828The second term in \autoref{eq:MB_p_sco} depends on the tilt of the coordinate surface and 
     829leads to a truncation error that is not present in a $z$-model. 
     830In the special case of a $\sigma$-coordinate 
     831(i.e. a depth-normalised coordinate system $\sigma = z/H$), 
     832\citet{haney_JPO91} and \citet{beckmann.haidvogel_JPO93} have given estimates of 
     833the magnitude of this truncation error. 
     834It depends on topographic slope, stratification, horizontal and vertical resolution, 
     835the equation of state, and the finite difference scheme. 
    881836This error limits the possible topographic slopes that a model can handle at 
    882837a given horizontal and vertical resolution. 
    883838This is a severe restriction for large-scale applications using realistic bottom topography. 
    884 The large-scale slopes require high horizontal resolution, and the computational cost becomes prohibitive. 
     839The large-scale slopes require high horizontal resolution, 
     840and the computational cost becomes prohibitive. 
    885841This problem can be at least partially overcome by mixing $s$-coordinate and 
    886 step-like representation of bottom topography \citep{Gerdes1993a,Gerdes1993b,Madec_al_JPO96}. 
     842step-like representation of bottom topography 
     843\citep{gerdes_JGR93*a,gerdes_JGR93*b,madec.delecluse.ea_JPO96}. 
    887844However, the definition of the model domain vertical coordinate becomes then a non-trivial thing for 
    888845a realistic bottom topography: 
    889 a envelope topography is defined in $s$-coordinate on which a full or 
    890 partial step bottom topography is then applied in order to adjust the model depth to the observed one 
    891 (see \autoref{sec:DOM_zgr}. 
    892  
    893 For numerical reasons a minimum of diffusion is required along the coordinate surfaces of 
    894 any finite difference model. 
     846an envelope topography is defined in $s$-coordinate on which 
     847a full or partial step bottom topography is then applied in order to 
     848adjust the model depth to the observed one (see \autoref{subsec:DOM_zgr}). 
     849 
     850For numerical reasons a minimum of diffusion is required along 
     851the coordinate surfaces of any finite difference model. 
    895852It causes spurious diapycnal mixing when coordinate surfaces do not coincide with isoneutral surfaces. 
    896853This is the case for a $z$-model as well as for a $s$-model. 
    897 However, density varies more strongly on $s$-surfaces than on horizontal surfaces in regions of 
    898 large topographic slopes, implying larger diapycnal diffusion in a $s$-model than in a $z$-model. 
    899 Whereas such a diapycnal diffusion in a $z$-model tends to weaken horizontal density (pressure) gradients and thus 
    900 the horizontal circulation, it usually reinforces these gradients in a $s$-model, creating spurious circulation. 
    901 For example, imagine an isolated bump of topography in an ocean at rest with a horizontally uniform stratification. 
     854However, density varies more strongly on $s$-surfaces than on horizontal surfaces in 
     855regions of large topographic slopes, 
     856implying larger diapycnal diffusion in a $s$-model than in a $z$-model. 
     857Whereas such a diapycnal diffusion in a $z$-model tends to 
     858weaken horizontal density (pressure) gradients and thus the horizontal circulation, 
     859it usually reinforces these gradients in a $s$-model, creating spurious circulation. 
     860For example, imagine an isolated bump of topography in 
     861an ocean at rest with a horizontally uniform stratification. 
    902862Spurious diffusion along $s$-surfaces will induce a bump of isoneutral surfaces over the topography, 
    903863and thus will generate there a baroclinic eddy. 
    904864In contrast, the ocean will stay at rest in a $z$-model. 
    905 As for the truncation error, the problem can be reduced by introducing the terrain-following coordinate below 
    906 the strongly stratified portion of the water column (\ie the main thermocline) \citep{Madec_al_JPO96}. 
    907 An alternate solution consists of rotating the lateral diffusive tensor to geopotential or to isoneutral surfaces 
    908 (see \autoref{subsec:PE_ldf}). 
     865As for the truncation error, the problem can be reduced by 
     866introducing the terrain-following coordinate below the strongly stratified portion of the water column 
     867(\ie\ the main thermocline) \citep{madec.delecluse.ea_JPO96}. 
     868An alternate solution consists of rotating the lateral diffusive tensor to 
     869geopotential or to isoneutral surfaces (see \autoref{subsec:MB_ldf}). 
    909870Unfortunately, the slope of isoneutral surfaces relative to the $s$-surfaces can very large, 
    910 strongly exceeding the stability limit of such a operator when it is discretized (see \autoref{chap:LDF}). 
    911  
    912 The $s$-coordinates introduced here \citep{Lott_al_OM90,Madec_al_JPO96} differ mainly in two aspects from 
    913 similar models: 
    914 it allows a representation of bottom topography with mixed full or partial step-like/terrain following topography; 
     871strongly exceeding the stability limit of such a operator when it is discretized 
     872(see \autoref{chap:LDF}). 
     873 
     874The $s$-coordinates introduced here \citep{lott.madec.ea_OM90,madec.delecluse.ea_JPO96} 
     875differ mainly in two aspects from similar models: 
     876it allows a representation of bottom topography with 
     877mixed full or partial step-like/terrain following topography; 
    915878It also offers a completely general transformation, $s=s(i,j,z)$ for the vertical coordinate. 
    916879 
    917 % ------------------------------------------------------------------------------------------------------------- 
    918 % Curvilinear z-tilde coordinate System 
    919 % ------------------------------------------------------------------------------------------------------------- 
    920 \subsection{\texorpdfstring{Curvilinear \ztilde-coordinate}{}} 
    921 \label{subsec:PE_zco_tilde} 
    922  
    923 The \ztilde -coordinate has been developed by \citet{Leclair_Madec_OM11}. 
    924 It is available in \NEMO since the version 3.4. 
     880%% ================================================================================================= 
     881\subsection{Curvilinear \ztilde-coordinate} 
     882\label{subsec:MB_zco_tilde} 
     883 
     884The \ztilde-coordinate has been developed by \citet{leclair.madec_OM11}. 
     885It is available in \NEMO\ since the version 3.4 and is more robust in version 4.0 than previously. 
    925886Nevertheless, it is currently not robust enough to be used in all possible configurations. 
    926887Its use is therefore not recommended. 
    927888 
    928 \newpage  
    929  
    930 % ================================================================ 
    931 % Subgrid Scale Physics 
    932 % ================================================================ 
     889%% ================================================================================================= 
    933890\section{Subgrid scale physics} 
    934 \label{sec:PE_zdf_ldf} 
    935  
    936 The primitive equations describe the behaviour of a geophysical fluid at space and time scales larger than 
    937 a few kilometres in the horizontal, a few meters in the vertical and a few minutes. 
    938 They are usually solved at larger scales: the specified grid spacing and time step of the numerical model. 
     891\label{sec:MB_zdf_ldf} 
     892 
     893The hydrostatic primitive equations describe the behaviour of a geophysical fluid at 
     894space and time scales larger than a few kilometres in the horizontal, 
     895a few meters in the vertical and a few minutes. 
     896They are usually solved at larger scales: the specified grid spacing and time step of 
     897the numerical model. 
    939898The effects of smaller scale motions (coming from the advective terms in the Navier-Stokes equations) 
    940899must be represented entirely in terms of large-scale patterns to close the equations. 
    941900These effects appear in the equations as the divergence of turbulent fluxes 
    942 (\ie fluxes associated with the mean correlation of small scale perturbations). 
     901(\ie\ fluxes associated with the mean correlation of small scale perturbations). 
    943902Assuming a turbulent closure hypothesis is equivalent to choose a formulation for these fluxes. 
    944903It is usually called the subgrid scale physics. 
     
    947906small scale processes \textit{in fine} balance the surface input of kinetic energy and heat. 
    948907 
    949 The control exerted by gravity on the flow induces a strong anisotropy between the lateral and vertical motions. 
     908The control exerted by gravity on the flow induces a strong anisotropy between 
     909the lateral and vertical motions. 
    950910Therefore subgrid-scale physics \textbf{D}$^{\vect U}$, $D^{S}$ and $D^{T}$  in 
    951 \autoref{eq:PE_dyn}, \autoref{eq:PE_tra_T} and \autoref{eq:PE_tra_S} are divided into 
    952 a lateral part \textbf{D}$^{l \vect U}$, $D^{l S}$ and $D^{l T}$ and 
     911\autoref{eq:MB_PE_dyn}, \autoref{eq:MB_PE_tra_T} and \autoref{eq:MB_PE_tra_S} are divided into 
     912a  lateral part \textbf{D}$^{l \vect U}$, $D^{l S}$ and $D^{l T}$ and 
    953913a vertical part \textbf{D}$^{v \vect U}$, $D^{v S}$ and $D^{v T}$. 
    954 The formulation of these terms and their underlying physics are briefly discussed in the next two subsections. 
    955  
    956 % ------------------------------------------------------------------------------------------------------------- 
    957 % Vertical Subgrid Scale Physics 
    958 % ------------------------------------------------------------------------------------------------------------- 
     914The formulation of these terms and their underlying physics are briefly discussed in 
     915the next two subsections. 
     916 
     917%% ================================================================================================= 
    959918\subsection{Vertical subgrid scale physics} 
    960 \label{subsec:PE_zdf} 
    961  
    962 The model resolution is always larger than the scale at which the major sources of vertical turbulence occur 
    963 (shear instability, internal wave breaking...). 
     919\label{subsec:MB_zdf} 
     920 
     921The model resolution is always larger than the scale at which 
     922the major sources of vertical turbulence occur (shear instability, internal wave breaking...). 
    964923Turbulent motions are thus never explicitly solved, even partially, but always parameterized. 
    965 The vertical turbulent fluxes are assumed to depend linearly on the gradients of large-scale quantities 
    966 (for example, the turbulent heat flux is given by $\overline{T' w'} = -A^{v T} \partial_z \overline T$, 
     924The vertical turbulent fluxes are assumed to depend linearly on 
     925the gradients of large-scale quantities (for example, 
     926the turbulent heat flux is given by $\overline{T' w'} = -A^{v T} \partial_z \overline T$, 
    967927where $A^{v T}$ is an eddy coefficient). 
    968928This formulation is analogous to that of molecular diffusion and dissipation. 
     
    972932The resulting vertical momentum and tracer diffusive operators are of second order: 
    973933\begin{equation} 
    974   \label{eq:PE_zdf} 
     934  \label{eq:MB_zdf} 
    975935  \begin{gathered} 
    976     \vect D^{v \vect U} = \pd[]{z} \lt( A^{vm} \pd[\vect U_h]{z} \rt) \ , \\ 
    977           D^{vT}       = \pd[]{z} \lt( A^{vT} \pd[T]{z}         \rt) \quad \text{and} \quad 
     936    \vect D^{v \vect U} = \pd[]{z} \lt( A^{vm} \pd[\vect U_h]{z} \rt) \text{,} \ 
     937          D^{vT}       = \pd[]{z} \lt( A^{vT} \pd[T]{z}         \rt) \ \text{and} \ 
    978938          D^{vS}       = \pd[]{z} \lt( A^{vT} \pd[S]{z}         \rt) 
    979939  \end{gathered} 
    980940\end{equation} 
    981 where $A^{vm}$ and $A^{vT}$ are the vertical eddy viscosity and diffusivity coefficients, respectively. 
     941where $A^{vm}$ and $A^{vT}$ are the vertical eddy viscosity and diffusivity coefficients, 
     942respectively. 
    982943At the sea surface and at the bottom, turbulent fluxes of momentum, heat and salt must be specified 
    983944(see \autoref{chap:SBC} and \autoref{chap:ZDF} and \autoref{sec:TRA_bbl}). 
    984945All the vertical physics is embedded in the specification of the eddy coefficients. 
    985946They can be assumed to be either constant, or function of the local fluid properties 
    986 (\eg Richardson number, Brunt-Vais\"{a}l\"{a} frequency...), 
     947(\eg\ Richardson number, Brunt-V\"{a}is\"{a}l\"{a} frequency, distance from the boundary ...), 
    987948or computed from a turbulent closure model. 
    988 The choices available in \NEMO are discussed in \autoref{chap:ZDF}). 
    989  
    990 % ------------------------------------------------------------------------------------------------------------- 
    991 % Lateral Diffusive and Viscous Operators Formulation 
    992 % ------------------------------------------------------------------------------------------------------------- 
     949The choices available in \NEMO\ are discussed in \autoref{chap:ZDF}). 
     950 
     951%% ================================================================================================= 
    993952\subsection{Formulation of the lateral diffusive and viscous operators} 
    994 \label{subsec:PE_ldf} 
     953\label{subsec:MB_ldf} 
    995954 
    996955Lateral turbulence can be roughly divided into a mesoscale turbulence associated with eddies 
    997956(which can be solved explicitly if the resolution is sufficient since 
    998957their underlying physics are included in the primitive equations), 
    999 and a sub mesoscale turbulence which is never explicitly solved even partially, but always parameterized. 
    1000 The formulation of lateral eddy fluxes depends on whether the mesoscale is below or above the grid-spacing 
    1001 (\ie the model is eddy-resolving or not). 
     958and a sub mesoscale turbulence which is never explicitly solved even partially, 
     959but always parameterized. 
     960The formulation of lateral eddy fluxes depends on whether 
     961the mesoscale is below or above the grid-spacing (\ie\ the model is eddy-resolving or not). 
    1002962 
    1003963In non-eddy-resolving configurations, the closure is similar to that used for the vertical physics. 
    1004 The lateral turbulent fluxes are assumed to depend linearly on the lateral gradients of large-scale quantities. 
     964The lateral turbulent fluxes are assumed to depend linearly on 
     965the lateral gradients of large-scale quantities. 
    1005966The resulting lateral diffusive and dissipative operators are of second order. 
    1006 Observations show that lateral mixing induced by mesoscale turbulence tends to be along isopycnal surfaces 
    1007 (or more precisely neutral surfaces \cite{McDougall1987}) rather than across them. 
    1008 As the slope of neutral surfaces is small in the ocean, a common approximation is to assume that 
    1009 the `lateral' direction is the horizontal, \ie the lateral mixing is performed along geopotential surfaces. 
     967Observations show that 
     968lateral mixing induced by mesoscale turbulence tends to be along isopycnal surfaces 
     969(or more precisely neutral surfaces \cite{mcdougall_JPO87}) rather than across them. 
     970As the slope of neutral surfaces is small in the ocean, 
     971a common approximation is to assume that the ``lateral'' direction is the horizontal, 
     972\ie\ the lateral mixing is performed along geopotential surfaces. 
    1010973This leads to a geopotential second order operator for lateral subgrid scale physics. 
    1011 This assumption can be relaxed: the eddy-induced turbulent fluxes can be better approached by assuming that 
     974This assumption can be relaxed: 
     975the eddy-induced turbulent fluxes can be better approached by assuming that 
    1012976they depend linearly on the gradients of large-scale quantities computed along neutral surfaces. 
    1013977In such a case, the diffusive operator is an isoneutral second order operator and 
    1014978it has components in the three space directions. 
    1015 However, 
    1016 both horizontal and isoneutral operators have no effect on mean (\ie large scale) potential energy whereas 
     979However, both horizontal and isoneutral operators have no effect on 
     980mean (\ie\ large scale) potential energy whereas 
    1017981potential energy is a main source of turbulence (through baroclinic instabilities). 
    1018 \citet{Gent1990} have proposed a parameterisation of mesoscale eddy-induced turbulence which 
     982\citet{gent.mcwilliams_JPO90} proposed a parameterisation of mesoscale eddy-induced turbulence which 
    1019983associates an eddy-induced velocity to the isoneutral diffusion. 
    1020984Its mean effect is to reduce the mean potential energy of the ocean. 
    1021 This leads to a formulation of lateral subgrid-scale physics made up of an isoneutral second order operator and 
    1022 an eddy induced advective part. 
     985This leads to a formulation of lateral subgrid-scale physics made up of 
     986an isoneutral second order operator and an eddy induced advective part. 
    1023987In all these lateral diffusive formulations, 
    1024988the specification of the lateral eddy coefficients remains the problematic point as 
    1025 there is no really satisfactory formulation of these coefficients as a function of large-scale features. 
     989there is no really satisfactory formulation of these coefficients as 
     990a function of large-scale features. 
    1026991 
    1027992In eddy-resolving configurations, a second order operator can be used, 
     
    1032997not interfering with the resolved mesoscale activity. 
    1033998Another approach is becoming more and more popular: 
    1034 instead of specifying explicitly a sub-grid scale term in the momentum and tracer time evolution equations, 
    1035 one uses a advective scheme which is diffusive enough to maintain the model stability. 
    1036 It must be emphasised that then, all the sub-grid scale physics is included in the formulation of 
    1037 the advection scheme. 
     999instead of specifying explicitly a sub-grid scale term in 
     1000the momentum and tracer time evolution equations, 
     1001one uses an advective scheme which is diffusive enough to maintain the model stability. 
     1002It must be emphasised that then, 
     1003all the sub-grid scale physics is included in the formulation of the advection scheme. 
    10381004 
    10391005All these parameterisations of subgrid scale physics have advantages and drawbacks. 
    1040 There are not all available in \NEMO. For active tracers (temperature and salinity) the main ones are: 
     1006They are not all available in \NEMO. 
     1007For active tracers (temperature and salinity) the main ones are: 
    10411008Laplacian and bilaplacian operators acting along geopotential or iso-neutral surfaces, 
    1042 \citet{Gent1990} parameterisation, and various slightly diffusive advection schemes. 
    1043 For momentum, the main ones are: Laplacian and bilaplacian operators acting along geopotential surfaces, 
     1009\citet{gent.mcwilliams_JPO90} parameterisation, and various slightly diffusive advection schemes. 
     1010For momentum, the main ones are: 
     1011Laplacian and bilaplacian operators acting along geopotential surfaces, 
    10441012and UBS advection schemes when flux form is chosen for the momentum advection. 
    10451013 
     1014%% ================================================================================================= 
    10461015\subsubsection{Lateral laplacian tracer diffusive operator} 
    10471016 
    1048 The lateral Laplacian tracer diffusive operator is defined by (see \autoref{apdx:B}): 
     1017The lateral Laplacian tracer diffusive operator is defined by (see \autoref{apdx:DIFFOPERS}): 
    10491018\begin{equation} 
    1050   \label{eq:PE_iso_tensor} 
    1051   D^{lT} = \nabla \vect . \lt( A^{lT} \; \Re \; \nabla T \rt) \quad \text{with} \quad 
    1052   \Re = 
    1053     \begin{pmatrix} 
    1054       1    & 0    & -r_1          \\ 
    1055       0    & 1    & -r_2          \\ 
    1056       -r_1 & -r_2 & r_1^2 + r_2^2 \\ 
    1057     \end{pmatrix} 
     1019  \label{eq:MB_iso_tensor} 
     1020  D^{lT} = \nabla \vect . \lt( A^{lT} \; \Re \; \nabla T \rt) \quad \text{with} \quad \Re = 
     1021  \begin{pmatrix} 
     1022    1    & 0    & -r_1          \\ 
     1023    0    & 1    & -r_2          \\ 
     1024    -r_1 & -r_2 & r_1^2 + r_2^2 \\ 
     1025  \end{pmatrix} 
    10581026\end{equation} 
    10591027where $r_1$ and $r_2$ are the slopes between the surface along which the diffusive operator acts and 
    1060 the model level (\eg $z$- or $s$-surfaces). 
    1061 Note that the formulation \autoref{eq:PE_iso_tensor} is exact for 
     1028the model level (\eg\ $z$- or $s$-surfaces). 
     1029Note that the formulation \autoref{eq:MB_iso_tensor} is exact for 
    10621030the rotation between geopotential and $s$-surfaces, 
    10631031while it is only an approximation for the rotation between isoneutral and $z$- or $s$-surfaces. 
    1064 Indeed, in the latter case, two assumptions are made to simplify \autoref{eq:PE_iso_tensor} \citep{Cox1987}. 
    1065 First, the horizontal contribution of the dianeutral mixing is neglected since the ratio between iso and 
    1066 dia-neutral diffusive coefficients is known to be several orders of magnitude smaller than unity. 
     1032Indeed, in the latter case, two assumptions are made to simplify \autoref{eq:MB_iso_tensor} 
     1033\citep{cox_OM87}. 
     1034First, the horizontal contribution of the dianeutral mixing is neglected since 
     1035the ratio between iso and dia-neutral diffusive coefficients is known to be 
     1036several orders of magnitude smaller than unity. 
    10671037Second, the two isoneutral directions of diffusion are assumed to be independent since 
    1068 the slopes are generally less than $10^{-2}$ in the ocean (see \autoref{apdx:B}). 
     1038the slopes are generally less than $10^{-2}$ in the ocean (see \autoref{apdx:DIFFOPERS}). 
    10691039 
    10701040For \textit{iso-level} diffusion, $r_1$ and $r_2 $ are zero. 
     
    10731043For \textit{geopotential} diffusion, 
    10741044$r_1$ and $r_2 $ are the slopes between the geopotential and computational surfaces: 
    1075 they are equal to $\sigma_1$ and $\sigma_2$, respectively (see \autoref{eq:PE_sco_slope}). 
    1076  
    1077 For \textit{isoneutral} diffusion $r_1$ and $r_2$ are the slopes between the isoneutral and computational surfaces. 
     1045they are equal to $\sigma_1$ and $\sigma_2$, respectively (see \autoref{eq:MB_sco_slope}). 
     1046 
     1047For \textit{isoneutral} diffusion $r_1$ and $r_2$ are the slopes between 
     1048the isoneutral and computational surfaces. 
    10781049Therefore, they are different quantities, but have similar expressions in $z$- and $s$-coordinates. 
    10791050In $z$-coordinates: 
    10801051\begin{equation} 
    1081   \label{eq:PE_iso_slopes} 
    1082   r_1 = \frac{e_3}{e_1} \lt( \pd[\rho]{i} \rt) \lt( \pd[\rho]{k} \rt)^{-1} \quad 
    1083   r_2 = \frac{e_3}{e_2} \lt( \pd[\rho]{j} \rt) \lt( \pd[\rho]{k} \rt)^{-1} 
     1052  \label{eq:MB_iso_slopes} 
     1053  r_1 = \frac{e_3}{e_1} \lt( \pd[\rho]{i} \rt) \lt( \pd[\rho]{k} \rt)^{-1} \quad 
     1054  r_2 = \frac{e_3}{e_2} \lt( \pd[\rho]{j} \rt) \lt( \pd[\rho]{k} \rt)^{-1} 
    10841055\end{equation} 
    10851056while in $s$-coordinates $\pd[]{k}$ is replaced by $\pd[]{s}$. 
    10861057 
     1058%% ================================================================================================= 
    10871059\subsubsection{Eddy induced velocity} 
    10881060 
    1089 When the \textit{eddy induced velocity} parametrisation (eiv) \citep{Gent1990} is used, 
     1061When the \textit{eddy induced velocity} parametrisation (eiv) \citep{gent.mcwilliams_JPO90} is used, 
    10901062an additional tracer advection is introduced in combination with the isoneutral diffusion of tracers: 
    10911063\[ 
    1092   % \label{eq:PE_iso+eiv} 
     1064  % \label{eq:MB_iso+eiv} 
    10931065  D^{lT} = \nabla \cdot \lt( A^{lT} \; \Re \; \nabla T \rt) + \nabla \cdot \lt( \vect U^\ast \, T \rt) 
    10941066\] 
    10951067where $ \vect U^\ast = \lt( u^\ast,v^\ast,w^\ast \rt)$ is a non-divergent, 
    10961068eddy-induced transport velocity. This velocity field is defined by: 
    1097 \begin{gather} 
    1098   % \label{eq:PE_eiv} 
    1099   u^\ast =   \frac{1}{e_3}            \pd[]{k} \lt( A^{eiv} \;        \tilde{r}_1 \rt) \\ 
    1100   v^\ast =   \frac{1}{e_3}            \pd[]{k} \lt( A^{eiv} \;        \tilde{r}_2 \rt) \\ 
     1069\[ 
     1070  % \label{eq:MB_eiv} 
     1071  u^\ast =   \frac{1}{e_3}            \pd[]{k} \lt( A^{eiv} \;        \tilde{r}_1 \rt) \quad 
     1072  v^\ast =   \frac{1}{e_3}            \pd[]{k} \lt( A^{eiv} \;        \tilde{r}_2 \rt) \quad 
    11011073  w^\ast = - \frac{1}{e_1 e_2} \lt[   \pd[]{i} \lt( A^{eiv} \; e_2 \, \tilde{r}_1 \rt) 
    11021074                                     + \pd[]{j} \lt( A^{eiv} \; e_1 \, \tilde{r}_2 \rt) \rt] 
    1103 \end{gather} 
     1075\] 
    11041076where $A^{eiv}$ is the eddy induced velocity coefficient 
    11051077(or equivalently the isoneutral thickness diffusivity coefficient), 
    1106 and $\tilde r_1$ and $\tilde r_2$ are the slopes between isoneutral and \textit{geopotential} surfaces. 
    1107 Their values are thus independent of the vertical coordinate, but their expression depends on the coordinate:  
    1108 \begin{align} 
    1109   \label{eq:PE_slopes_eiv} 
     1078and $\tilde r_1$ and $\tilde r_2$ are the slopes between 
     1079isoneutral and \textit{geopotential} surfaces. 
     1080Their values are thus independent of the vertical coordinate, 
     1081but their expression depends on the coordinate: 
     1082\begin{equation} 
     1083  \label{eq:MB_slopes_eiv} 
    11101084  \tilde{r}_n = 
    11111085    \begin{cases} 
     
    11141088    \end{cases} 
    11151089  \quad \text{where~} n = 1, 2 
    1116 \end{align} 
     1090\end{equation} 
    11171091 
    11181092The normal component of the eddy induced velocity is zero at all the boundaries. 
    1119 This can be achieved in a model by tapering either the eddy coefficient or the slopes to zero in the vicinity of 
    1120 the boundaries. 
    1121 The latter strategy is used in \NEMO (cf. \autoref{chap:LDF}). 
    1122  
     1093This can be achieved in a model by tapering either the eddy coefficient or the slopes to zero in 
     1094the vicinity of the boundaries. 
     1095The latter strategy is used in \NEMO\ (cf. \autoref{chap:LDF}). 
     1096 
     1097%% ================================================================================================= 
    11231098\subsubsection{Lateral bilaplacian tracer diffusive operator} 
    11241099 
    11251100The lateral bilaplacian tracer diffusive operator is defined by: 
    11261101\[ 
    1127   % \label{eq:PE_bilapT} 
     1102  % \label{eq:MB_bilapT} 
    11281103  D^{lT}= - \Delta \; (\Delta T) \quad \text{where} \quad 
    11291104  \Delta \bullet = \nabla \lt( \sqrt{B^{lT}} \; \Re \; \nabla \bullet \rt) 
    11301105\] 
    1131 It is the Laplacian operator given by \autoref{eq:PE_iso_tensor} applied twice with 
     1106It is the Laplacian operator given by \autoref{eq:MB_iso_tensor} applied twice with 
    11321107the harmonic eddy diffusion coefficient set to the square root of the biharmonic one. 
    11331108 
     1109%% ================================================================================================= 
    11341110\subsubsection{Lateral Laplacian momentum diffusive operator} 
    11351111 
    11361112The Laplacian momentum diffusive operator along $z$- or $s$-surfaces is found by 
    1137 applying \autoref{eq:PE_lap_vector} to the horizontal velocity vector (see \autoref{apdx:B}): 
     1113applying \autoref{eq:MB_lap_vector} to the horizontal velocity vector (see \autoref{apdx:DIFFOPERS}): 
    11381114\begin{align*} 
    1139   % \label{eq:PE_lapU} 
     1115  % \label{eq:MB_lapU} 
    11401116  \vect D^{l \vect U} &=   \nabla_h        \big( A^{lm}    \chi             \big) 
    11411117                         - \nabla_h \times \big( A^{lm} \, \zeta \; \vect k \big) \\ 
    11421118                      &= \lt(   \frac{1}{e_1}     \pd[ \lt( A^{lm}    \chi      \rt) ]{i} \rt. 
    1143                               - \frac{1}{e_2 e_3} \pd[ \lt( A^{lm} \; e_3 \zeta \rt) ]{j} 
     1119                              - \frac{1}{e_2 e_3} \pd[ \lt( A^{lm} \; e_3 \zeta \rt) ]{j} , 
    11441120                                \frac{1}{e_2}     \pd[ \lt( A^{lm}    \chi      \rt) ]{j} 
    11451121                         \lt. + \frac{1}{e_1 e_3} \pd[ \lt( A^{lm} \; e_3 \zeta \rt) ]{i} \rt) 
    11461122\end{align*} 
    11471123 
    1148 Such a formulation ensures a complete separation between the vorticity and horizontal divergence fields 
    1149 (see \autoref{apdx:C}). 
     1124Such a formulation ensures a complete separation between 
     1125the vorticity and horizontal divergence fields (see \autoref{apdx:INVARIANTS}). 
    11501126Unfortunately, it is only available in \textit{iso-level} direction. 
    11511127When a rotation is required 
    1152 (\ie geopotential diffusion in $s$-coordinates or isoneutral diffusion in both $z$- and $s$-coordinates), 
    1153 the $u$ and $v$-fields are considered as independent scalar fields, so that the diffusive operator is given by: 
    1154 \begin{gather*} 
    1155   % \label{eq:PE_lapU_iso} 
    1156     D_u^{l \vect U} = \nabla . \lt( A^{lm} \; \Re \; \nabla u \rt) \\ 
     1128(\ie\ geopotential diffusion in $s$-coordinates or 
     1129isoneutral diffusion in both $z$- and $s$-coordinates), 
     1130the $u$ and $v$-fields are considered as independent scalar fields, 
     1131so that the diffusive operator is given by: 
     1132\[ 
     1133  % \label{eq:MB_lapU_iso} 
     1134    D_u^{l \vect U} = \nabla . \lt( A^{lm} \; \Re \; \nabla u \rt) \quad 
    11571135    D_v^{l \vect U} = \nabla . \lt( A^{lm} \; \Re \; \nabla v \rt) 
    1158 \end{gather*} 
    1159 where $\Re$ is given by \autoref{eq:PE_iso_tensor}. 
     1136\] 
     1137where $\Re$ is given by \autoref{eq:MB_iso_tensor}. 
    11601138It is the same expression as those used for diffusive operator on tracers. 
    11611139It must be emphasised that such a formulation is only exact in a Cartesian coordinate system, 
    1162 \ie on a $f$- or $\beta$-plane, not on the sphere. 
     1140\ie\ on a $f$- or $\beta$-plane, not on the sphere. 
    11631141It is also a very good approximation in vicinity of the Equator in 
    1164 a geographical coordinate system \citep{Lengaigne_al_JGR03}. 
    1165  
    1166 \subsubsection{lateral bilaplacian momentum diffusive operator} 
    1167  
    1168 As for tracers, the bilaplacian order momentum diffusive operator is a re-entering Laplacian operator with 
     1142a geographical coordinate system \citep{lengaigne.madec.ea_JGR03}. 
     1143 
     1144%% ================================================================================================= 
     1145\subsubsection{Lateral bilaplacian momentum diffusive operator} 
     1146 
     1147As for tracers, 
     1148the bilaplacian order momentum diffusive operator is a re-entering Laplacian operator with 
    11691149the harmonic eddy diffusion coefficient set to the square root of the biharmonic one. 
    11701150Nevertheless it is currently not available in the iso-neutral case. 
    11711151 
    1172 \biblio 
    1173  
    1174 \pindex 
     1152\subinc{\input{../../global/epilogue}} 
    11751153 
    11761154\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex

    r10544 r11831  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter 1 Model Basics 
    6 % ================================================================ 
    7 % ================================================================ 
    8 % Curvilinear \zstar- \sstar-coordinate System 
    9 % ================================================================ 
     4 
    105\chapter{ essai \zstar \sstar} 
     6 
     7\thispagestyle{plain} 
     8 
     9\chaptertoc 
     10 
     11\paragraph{Changes record} ~\\ 
     12 
     13{\footnotesize 
     14  \begin{tabularx}{\textwidth}{l||X|X} 
     15    Release & Author(s) & Modifications \\ 
     16    \hline 
     17    {\em   4.0} & {\em ...} & {\em ...} \\ 
     18    {\em   3.6} & {\em ...} & {\em ...} \\ 
     19    {\em   3.4} & {\em ...} & {\em ...} \\ 
     20    {\em <=3.4} & {\em ...} & {\em ...} 
     21  \end{tabularx} 
     22} 
     23 
     24\clearpage 
     25 
     26%% ================================================================================================= 
    1127\section{Curvilinear \zstar- or \sstar coordinate system} 
    1228 
    13 % ------------------------------------------------------------------------------------------------------------- 
    14 % ???? 
    15 % ------------------------------------------------------------------------------------------------------------- 
    16  
    1729\colorbox{yellow}{ to be updated } 
    1830 
    1931In that case, the free surface equation is nonlinear, and the variations of volume are fully taken into account. 
    20 These coordinates systems is presented in a report \citep{Levier2007} available on the \NEMO web site.  
     32These coordinates systems is presented in a report \citep{levier.treguier.ea_rpt07} available on the \NEMO\ web site. 
    2133 
    2234\colorbox{yellow}{  end of to be updated} 
     
    2436% from MOM4p1 documentation 
    2537 
    26 To overcome problems with vanishing surface and/or bottom cells, we consider the zstar coordinate  
    27 \[ 
    28   % \label{eq:PE_} 
     38To overcome problems with vanishing surface and/or bottom cells, we consider the zstar coordinate 
     39\[ 
     40  % \label{eq:MBZ_PE_} 
    2941  z^\star = H \left( \frac{z-\eta}{H+\eta} \right) 
    3042\] 
     
    4052the surface height, it is clear that surfaces constant $z^\star$ are very similar to the depth surfaces. 
    4153These properties greatly reduce difficulties of computing the horizontal pressure gradient relative to 
    42 terrain following sigma models discussed in \autoref{subsec:PE_sco}.  
     54terrain following sigma models discussed in \autoref{subsec:MB_sco}. 
    4355Additionally, since $z^\star$ when $\eta = 0$, no flow is spontaneously generated in 
    4456an unforced ocean starting from rest, regardless the bottom topography. 
     
    4961neutral physics parameterizations in $z^\star$ models using the same techniques as in $z$-models 
    5062(see Chapters 13-16 of Griffies (2004) for a discussion of neutral physics in $z$-models, 
    51 as well as  \autoref{sec:LDF_slp} in this document for treatment in \NEMO).  
     63as well as  \autoref{sec:LDF_slp} in this document for treatment in \NEMO). 
    5264 
    5365The range over which $z^\star$ varies is time independent $-H \leq z^\star \leq 0$. 
    5466Hence, all cells remain nonvanishing, so long as the surface height maintains $\eta > ?H$. 
    55 This is a minor constraint relative to that encountered on the surface height when using $s = z$ or $s = z - \eta$.  
     67This is a minor constraint relative to that encountered on the surface height when using $s = z$ or $s = z - \eta$. 
    5668 
    5769Because $z^\star$ has a time independent range, all grid cells have static increments ds, 
    58 and the sum of the ver tical increments yields the time independent ocean depth %�k ds = H.  
     70and the sum of the ver tical increments yields the time independent ocean depth %�k ds = H. 
    5971The $z^\star$ coordinate is therefore invisible to undulations of the free surface, 
    6072since it moves along with the free surface. 
     
    6476Quite generally, the time independent range for the $z^\star$ coordinate is a very convenient property that 
    6577allows for a nearly arbitrary vertical resolution even in the presence of large amplitude fluctuations of 
    66 the surface height, again so long as $\eta > -H$.  
    67  
    68 %%% 
     78the surface height, again so long as $\eta > -H$. 
     79 
    6980%  essai update time splitting... 
    70 %%% 
    71  
    72 % ================================================================ 
    73 % Surface Pressure Gradient and Sea Surface Height 
    74 % ================================================================ 
    75 \section{Surface pressure gradient and sea surface heigth (\protect\mdl{dynspg})} 
    76 \label{sec:DYN_hpg_spg} 
    77 %-----------------------------------------nam_dynspg---------------------------------------------------- 
    78  
    79 %\nlst{nam_dynspg}  
    80 %------------------------------------------------------------------------------------------------------------ 
    81 Options are defined through the \ngn{nam\_dynspg} namelist variables. 
    82 The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:PE_hor_pg}). 
     81 
     82%% ================================================================================================= 
     83\section[Surface pressure gradient and sea surface heigth (\textit{dynspg.F90})]{Surface pressure gradient and sea surface heigth (\protect\mdl{dynspg})} 
     84\label{sec:MBZ_dyn_hpg_spg} 
     85 
     86%\nlst{nam_dynspg} 
     87Options are defined through the \nam{_dynspg}{\_dynspg} namelist variables. 
     88The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:MB_hor_pg}). 
    8389The main distinction is between the fixed volume case (linear free surface or rigid lid) and 
    8490the variable volume case (nonlinear free surface, \key{vvl} is active). 
    85 In the linear free surface case (\autoref{subsec:PE_free_surface}) and rigid lid (\autoref{PE_rigid_lid}), 
     91In the linear free surface case (\autoref{subsec:MB_free_surface}) and rigid lid (\autoref{PE_rigid_lid}), 
    8692the vertical scale factors $e_{3}$ are fixed in time, 
    87 while in the nonlinear case (\autoref{subsec:PE_free_surface}) they are time-dependent. 
     93while in the nonlinear case (\autoref{subsec:MB_free_surface}) they are time-dependent. 
    8894With both linear and nonlinear free surface, external gravity waves are allowed in the equations, 
    8995which imposes a very small time step when an explicit time stepping is used. 
    9096Two methods are proposed to allow a longer time step for the three-dimensional equations: 
    91 the filtered free surface, which is a modification of the continuous equations %(see \autoref{eq:PE_flt}), 
     97the filtered free surface, which is a modification of the continuous equations %(see \autoref{eq:MB_flt?}), 
    9298and the split-explicit free surface described below. 
    9399The extra term introduced in the filtered method is calculated implicitly, 
    94100so that the update of the next velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}. 
    95101 
    96 %------------------------------------------------------------- 
    97102% Explicit 
    98 %------------------------------------------------------------- 
    99 \subsubsection{Explicit (\protect\key{dynspg\_exp})} 
    100 \label{subsec:DYN_spg_exp} 
     103%% ================================================================================================= 
     104\subsubsection[Explicit (\texttt{\textbf{key\_dynspg\_exp}})]{Explicit (\protect\key{dynspg\_exp})} 
     105\label{subsec:MBZ_dyn_spg_exp} 
    101106 
    102107In the explicit free surface formulation, the model time step is chosen small enough to 
     
    104109The sea surface height is given by: 
    105110\begin{equation} 
    106   \label{eq:dynspg_ssh} 
     111  \label{eq:MBZ_dynspg_ssh} 
    107112  \frac{\partial \eta }{\partial t}\equiv \frac{\text{EMP}}{\rho_w }+\frac{1}{e_{1T} 
    108113    e_{2T} }\sum\limits_k {\left( {\delta_i \left[ {e_{2u} e_{3u} u} 
     
    114119and $\rho_w =1,000\,Kg.m^{-3}$ is the volumic mass of pure water. 
    115120The sea-surface height is evaluated using a leapfrog scheme in combination with an Asselin time filter, 
    116 (\ie the velocity appearing in (\autoref{eq:dynspg_ssh}) is centred in time (\textit{now} velocity).  
     121(\ie\ the velocity appearing in (\autoref{eq:DYN_spg_ssh}) is centred in time (\textit{now} velocity). 
    117122 
    118123The surface pressure gradient, also evaluated using a leap-frog scheme, is then simply given by: 
    119124\begin{equation} 
    120   \label{eq:dynspg_exp} 
     125  \label{eq:MBZ_dynspg_exp} 
    121126  \left\{ 
    122127    \begin{aligned} 
     
    125130    \end{aligned} 
    126131  \right. 
    127 \end{equation}  
     132\end{equation} 
    128133 
    129134Consistent with the linearization, a $\left. \rho \right|_{k=1} / \rho_o$ factor is omitted in 
    130 (\autoref{eq:dynspg_exp}).  
    131  
    132 %------------------------------------------------------------- 
     135(\autoref{eq:DYN_spg_exp}). 
     136 
    133137% Split-explicit time-stepping 
    134 %------------------------------------------------------------- 
    135 \subsubsection{Split-explicit time-stepping (\protect\key{dynspg\_ts})} 
    136 \label{subsec:DYN_spg_ts} 
    137 %--------------------------------------------namdom---------------------------------------------------- 
    138  
    139 \nlst{namdom}  
    140 %-------------------------------------------------------------------------------------------------------------- 
    141 The split-explicit free surface formulation used in OPA follows the one proposed by \citet{Griffies2004}. 
     138%% ================================================================================================= 
     139\subsubsection[Split-explicit time-stepping (\texttt{\textbf{key\_dynspg\_ts}})]{Split-explicit time-stepping (\protect\key{dynspg\_ts})} 
     140\label{subsec:MBZ_dyn_spg_ts} 
     141 
     142The split-explicit free surface formulation used in OPA follows the one proposed by \citet{Griffies2004?}. 
    142143The general idea is to solve the free surface equation with a small time step, 
    143144while the three dimensional prognostic variables are solved with a longer time step that 
    144 is a multiple of \np{rdtbt} in the \ngn{namdom} namelist (Figure III.3).  
    145  
    146 %>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   > 
     145is a multiple of \np{rdtbt}{rdtbt} in the \nam{dom}{dom} namelist (Figure III.3). 
     146 
    147147\begin{figure}[!t] 
    148   \begin{center} 
    149     \includegraphics[width=0.90\textwidth]{Fig_DYN_dynspg_ts} 
    150     \caption{ 
    151       \protect\label{fig:DYN_dynspg_ts} 
    152       Schematic of the split-explicit time stepping scheme for the barotropic and baroclinic modes, 
    153       after \citet{Griffies2004}. 
    154       Time increases to the right. 
    155       Baroclinic time steps are denoted by $t-\Delta t$, $t, t+\Delta t$, and $t+2\Delta t$. 
    156       The curved line represents a leap-frog time step, 
    157       and the smaller barotropic time steps $N \Delta t=2\Delta t$ are denoted by the zig-zag line. 
    158       The vertically integrated forcing \textbf{M}(t) computed at 
    159       baroclinic time step t represents the interaction between the barotropic and baroclinic motions. 
    160       While keeping the total depth, tracer, and freshwater forcing fields fixed, 
    161       a leap-frog integration carries the surface height and vertically integrated velocity from 
    162       t to $t+2 \Delta t$ using N barotropic time steps of length $\Delta t$. 
    163       Time averaging the barotropic fields over the N+1 time steps (endpoints included) 
    164       centers the vertically integrated velocity at the baroclinic timestep $t+\Delta t$. 
    165       A baroclinic leap-frog time step carries the surface height to $t+\Delta t$ using the convergence of 
    166       the time averaged vertically integrated velocity taken from baroclinic time step t. 
    167     } 
    168   \end{center} 
     148  \centering 
     149  %\includegraphics[width=0.66\textwidth]{MBZ_DYN_dynspg_ts} 
     150  \caption[Schematic of the split-explicit time stepping scheme for 
     151  the barotropic and baroclinic modes, after \citet{Griffies2004?}]{ 
     152    Schematic of the split-explicit time stepping scheme for the barotropic and baroclinic modes, 
     153    after \citet{Griffies2004?}. 
     154    Time increases to the right. 
     155    Baroclinic time steps are denoted by $t-\Delta t$, $t, t+\Delta t$, and $t+2\Delta t$. 
     156    The curved line represents a leap-frog time step, 
     157    and the smaller barotropic time steps $N \Delta t=2\Delta t$ are denoted by the zig-zag line. 
     158    The vertically integrated forcing \textbf{M}(t) computed at 
     159    baroclinic time step t represents the interaction between the barotropic and baroclinic motions. 
     160    While keeping the total depth, tracer, and freshwater forcing fields fixed, 
     161    a leap-frog integration carries the surface height and vertically integrated velocity from 
     162    t to $t+2 \Delta t$ using N barotropic time steps of length $\Delta t$. 
     163    Time averaging the barotropic fields over the N+1 time steps (endpoints included) 
     164    centers the vertically integrated velocity at the baroclinic timestep $t+\Delta t$. 
     165    A baroclinic leap-frog time step carries the surface height to $t+\Delta t$ using 
     166    the convergence of the time averaged vertically integrated velocity taken from 
     167    baroclinic time step t.} 
     168  \label{fig:MBZ_dyn_dynspg_ts} 
    169169\end{figure} 
    170 %>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   > 
    171170 
    172171The split-explicit formulation has a damping effect on external gravity waves, 
    173 which is weaker than the filtered free surface but still significant as shown by \citet{Levier2007} in 
    174 the case of an analytical barotropic Kelvin wave.  
     172which is weaker than the filtered free surface but still significant as shown by \citet{levier.treguier.ea_rpt07} in 
     173the case of an analytical barotropic Kelvin wave. 
    175174 
    176175%from griffies book: .....   copy past ! 
     
    183182We have 
    184183\[ 
    185   % \label{eq:DYN_spg_ts_eta} 
     184  % \label{eq:MBZ_dyn_spg_ts_eta} 
    186185  \eta^{(b)}(\tau,t_{n+1}) - \eta^{(b)}(\tau,t_{n+1}) (\tau,t_{n-1}) 
    187   = 2 \Delta t \left[-\nabla \cdot \textbf{U}^{(b)}(\tau,t_n) + \text{EMP}_w(\tau) \right]  
     186  = 2 \Delta t \left[-\nabla \cdot \textbf{U}^{(b)}(\tau,t_n) + \text{EMP}_w(\tau) \right] 
    188187\] 
    189188\begin{multline*} 
    190   % \label{eq:DYN_spg_ts_u} 
     189  % \label{eq:MBZ_dyn_spg_ts_u} 
    191190  \textbf{U}^{(b)}(\tau,t_{n+1}) - \textbf{U}^{(b)}(\tau,t_{n-1})  \\ 
    192191  = 2\Delta t \left[ - f \textbf{k} \times \textbf{U}^{(b)}(\tau,t_{n}) 
     
    202201the freshwater flux $\text{EMP}_w(\tau)$, and total depth of the ocean $H(\tau)$ are held for 
    203202the duration of the barotropic time stepping over a single cycle. 
    204 This is also the time that sets the barotropic time steps via  
    205 \[ 
    206   % \label{eq:DYN_spg_ts_t} 
    207   t_n=\tau+n\Delta t    
     203This is also the time that sets the barotropic time steps via 
     204\[ 
     205  % \label{eq:MBZ_dyn_spg_ts_t} 
     206  t_n=\tau+n\Delta t 
    208207\] 
    209208with $n$ an integer. 
    210 The density scaled surface pressure is evaluated via  
    211 \[ 
    212   % \label{eq:DYN_spg_ts_ps} 
     209The density scaled surface pressure is evaluated via 
     210\[ 
     211  % \label{eq:MBZ_dyn_spg_ts_ps} 
    213212  p_s^{(b)}(\tau,t_{n}) = 
    214213  \begin{cases} 
     
    217216  \end{cases} 
    218217\] 
    219 To get started, we assume the following initial conditions  
    220 \[ 
    221   % \label{eq:DYN_spg_ts_eta} 
     218To get started, we assume the following initial conditions 
     219\[ 
     220  % \label{eq:MBZ_dyn_spg_ts_eta} 
    222221  \begin{split} 
    223222    \eta^{(b)}(\tau,t_{n=0}) &= \overline{\eta^{(b)}(\tau)} \\ 
     
    225224  \end{split} 
    226225\] 
    227 with  
    228 \[ 
    229   % \label{eq:DYN_spg_ts_etaF} 
     226with 
     227\[ 
     228  % \label{eq:MBZ_dyn_spg_ts_etaF} 
    230229  \overline{\eta^{(b)}(\tau)} = \frac{1}{N+1} \sum\limits_{n=0}^N \eta^{(b)}(\tau-\Delta t,t_{n}) 
    231230\] 
     
    233232Likewise, 
    234233\[ 
    235   % \label{eq:DYN_spg_ts_u} 
     234  % \label{eq:MBZ_dyn_spg_ts_u} 
    236235  \textbf{U}^{(b)}(\tau,t_{n=0}) = \overline{\textbf{U}^{(b)}(\tau)} \\ \\ 
    237236  \textbf{U}(\tau,t_{n=1}) = \textbf{U}^{(b)}(\tau,t_{n=0}) + \Delta t \ \text{RHS}_{n=0} 
    238237\] 
    239 with  
    240 \[ 
    241   % \label{eq:DYN_spg_ts_u} 
     238with 
     239\[ 
     240  % \label{eq:MBZ_dyn_spg_ts_u} 
    242241  \overline{\textbf{U}^{(b)}(\tau)} = \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau-\Delta t,t_{n}) 
    243242\] 
    244243the time averaged vertically integrated transport. 
    245 Notably, there is no Robert-Asselin time filter used in the barotropic portion of the integration.  
     244Notably, there is no Robert-Asselin time filter used in the barotropic portion of the integration. 
    246245 
    247246Upon reaching $t_{n=N} = \tau + 2\Delta \tau$ , the vertically integrated velocity is time averaged to 
    248 produce the updated vertically integrated velocity at baroclinic time $\tau + \Delta \tau$  
    249 \[ 
    250   % \label{eq:DYN_spg_ts_u} 
     247produce the updated vertically integrated velocity at baroclinic time $\tau + \Delta \tau$ 
     248\[ 
     249  % \label{eq:MBZ_dyn_spg_ts_u} 
    251250  \textbf{U}(\tau+\Delta t) = \overline{\textbf{U}^{(b)}(\tau+\Delta t)} 
    252251  = \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau,t_{n}) 
    253252\] 
    254253The surface height on the new baroclinic time step is then determined via 
    255 a baroclinic leap-frog using the following form  
     254a baroclinic leap-frog using the following form 
    256255\begin{equation} 
    257   \label{eq:DYN_spg_ts_ssh} 
     256  \label{eq:MBZ_dyn_spg_ts_ssh} 
    258257  \eta(\tau+\Delta) - \eta^{F}(\tau-\Delta) = 2\Delta t \ \left[ - \nabla \cdot \textbf{U}(\tau) + \text{EMP}_w \right] 
    259258\end{equation} 
     
    261260The use of this "big-leap-frog" scheme for the surface height ensures compatibility between 
    262261the mass/volume budgets and the tracer budgets. 
    263 More discussion of this point is provided in Chapter 10 (see in particular Section 10.2).  
    264   
     262More discussion of this point is provided in Chapter 10 (see in particular Section 10.2). 
     263 
    265264In general, some form of time filter is needed to maintain integrity of the surface height field due to 
    266 the leap-frog splitting mode in equation \autoref{eq:DYN_spg_ts_ssh}. 
     265the leap-frog splitting mode in equation \autoref{eq:MBZ_dyn_spg_ts_ssh}. 
    267266We have tried various forms of such filtering, 
    268267with the following method discussed in Griffies et al. (2001) chosen due to its stability and 
    269 reasonably good maintenance of tracer conservation properties (see ??)  
     268reasonably good maintenance of tracer conservation properties (see ??) 
    270269 
    271270\begin{equation} 
    272   \label{eq:DYN_spg_ts_sshf} 
     271  \label{eq:MBZ_dyn_spg_ts_sshf} 
    273272  \eta^{F}(\tau-\Delta) =  \overline{\eta^{(b)}(\tau)} 
    274273\end{equation} 
    275 Another approach tried was  
    276  
    277 \[ 
    278   % \label{eq:DYN_spg_ts_sshf2} 
     274Another approach tried was 
     275 
     276\[ 
     277  % \label{eq:MBZ_dyn_spg_ts_sshf2} 
    279278  \eta^{F}(\tau-\Delta) = \eta(\tau) 
    280279  + (\alpha/2) \left[\overline{\eta^{(b)}}(\tau+\Delta t) 
     
    285284This isolation allows for an easy check that tracer conservation is exact when eliminating tracer and 
    286285surface height time filtering (see ?? for more complete discussion). 
    287 However, in the general case with a non-zero $\alpha$, the filter \autoref{eq:DYN_spg_ts_sshf} was found to 
    288 be more conservative, and so is recommended.  
    289  
    290 %------------------------------------------------------------- 
    291 % Filtered formulation  
    292 %------------------------------------------------------------- 
    293 \subsubsection{Filtered formulation (\protect\key{dynspg\_flt})} 
    294 \label{subsec:DYN_spg_flt} 
    295  
    296 The filtered formulation follows the \citet{Roullet2000} implementation. 
     286However, in the general case with a non-zero $\alpha$, the filter \autoref{eq:MBZ_dyn_spg_ts_sshf} was found to 
     287be more conservative, and so is recommended. 
     288 
     289% Filtered formulation 
     290%% ================================================================================================= 
     291\subsubsection[Filtered formulation (\texttt{\textbf{key\_dynspg\_flt}})]{Filtered formulation (\protect\key{dynspg\_flt})} 
     292\label{subsec:MBZ_dyn_spg_flt} 
     293 
     294The filtered formulation follows the \citet{Roullet2000?} implementation. 
    297295The extra term introduced in the equations (see {\S}I.2.2) is solved implicitly. 
    298296The elliptic solvers available in the code are documented in \autoref{chap:MISC}. 
    299 The amplitude of the extra term is given by the namelist variable \np{rnu}. 
    300 The default value is 1, as recommended by \citet{Roullet2000} 
    301  
    302 \colorbox{red}{\np{rnu}\forcode{ = 1} to be suppressed from namelist !} 
    303  
    304 %------------------------------------------------------------- 
    305 % Non-linear free surface formulation  
    306 %------------------------------------------------------------- 
    307 \subsection{Non-linear free surface formulation (\protect\key{vvl})} 
    308 \label{subsec:DYN_spg_vvl} 
     297The amplitude of the extra term is given by the namelist variable \np{rnu}{rnu}. 
     298The default value is 1, as recommended by \citet{Roullet2000?} 
     299 
     300\colorbox{red}{\np[=1]{rnu}{rnu} to be suppressed from namelist !} 
     301 
     302% Non-linear free surface formulation 
     303%% ================================================================================================= 
     304\subsection[Non-linear free surface formulation (\texttt{\textbf{key\_vvl}})]{Non-linear free surface formulation (\protect\key{vvl})} 
     305\label{subsec:MBZ_dyn_spg_vvl} 
    309306 
    310307In the non-linear free surface formulation, the variations of volume are fully taken into account. 
    311 This option is presented in a report \citep{Levier2007} available on the NEMO web site. 
     308This option is presented in a report \citep{levier.treguier.ea_rpt07} available on the \NEMO\ web site. 
    312309The three time-stepping methods (explicit, split-explicit and filtered) are the same as in 
    313 \autoref{DYN_spg_linear} except that the ocean depth is now time-dependent. 
     310\autoref{?:DYN_spg_linear?} except that the ocean depth is now time-dependent. 
    314311In particular, this means that in filtered case, the matrix to be inverted has to be recomputed at each time-step. 
    315312 
    316 \biblio 
    317  
    318 \pindex 
     313\subinc{\input{../../global/epilogue}} 
    319314 
    320315\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/NEMO/subfiles/chap_time_domain.tex

    r10501 r11831  
    33\begin{document} 
    44 
    5 % ================================================================ 
    6 % Chapter 2 ——— Time Domain (step.F90) 
    7 % ================================================================ 
    8 \chapter{Time Domain (STP)} 
    9 \label{chap:STP} 
    10 \minitoc 
     5\chapter{Time Domain} 
     6\label{chap:TD} 
     7 
     8\thispagestyle{plain} 
     9 
     10\chaptertoc 
     11 
     12\paragraph{Changes record} ~\\ 
     13 
     14{\footnotesize 
     15  \begin{tabularx}{0.5\textwidth}{l||X|X} 
     16    Release          & Author(s)                                       & 
     17    Modifications                                                      \\ 
     18    \hline 
     19    {\em        4.0} & {\em J\'{e}r\^{o}me Chanut \newline Tim Graham} & 
     20    {\em Review \newline Update                                      } \\ 
     21    {\em        3.6} & {\em Christian \'{E}th\'{e}                   } & 
     22    {\em Update                                                      } \\ 
     23    {\em $\leq$ 3.4} & {\em Gurvan Madec                             } & 
     24    {\em First version                                               } \\ 
     25  \end{tabularx} 
     26} 
     27 
     28\clearpage 
    1129 
    1230% Missing things: 
    13 %  - daymod: definition of the time domain (nit000, nitend andd the calendar) 
    14  
    15 \gmcomment{STEVEN :maybe a picture of the directory structure in the introduction which could be referred to here, 
    16   would help  ==> to be added} 
    17 %%%% 
    18  
    19 \newpage 
    20  
    21 Having defined the continuous equations in \autoref{chap:PE}, we need now to choose a time discretization, 
     31% - daymod: definition of the time domain (nit000, nitend and the calendar) 
     32 
     33\cmtgm{STEVEN :maybe a picture of the directory structure in the introduction which 
     34could be referred to here, would help  ==> to be added} 
     35 
     36Having defined the continuous equations in \autoref{chap:MB}, 
     37we need now to choose a time discretization, 
    2238a key feature of an ocean model as it exerts a strong influence on the structure of the computer code 
    23 (\ie on its flowchart). 
    24 In the present chapter, we provide a general description of the \NEMO time stepping strategy and 
     39(\ie\ on its flowchart). 
     40In the present chapter, we provide a general description of the \NEMO\ time stepping strategy and 
    2541the consequences for the order in which the equations are solved. 
    2642 
    27 % ================================================================ 
    28 % Time Discretisation 
    29 % ================================================================ 
     43%% ================================================================================================= 
    3044\section{Time stepping environment} 
    31 \label{sec:STP_environment} 
    32  
    33 The time stepping used in \NEMO is a three level scheme that can be represented as follows: 
     45\label{sec:TD_environment} 
     46 
     47The time stepping used in \NEMO\ is a three level scheme that can be represented as follows: 
    3448\begin{equation} 
    35   \label{eq:STP} 
     49  \label{eq:TD} 
    3650  x^{t + \rdt} = x^{t - \rdt} + 2 \, \rdt \ \text{RHS}_x^{t - \rdt, \, t, \, t + \rdt} 
    37 \end{equation}  
     51\end{equation} 
    3852where $x$ stands for $u$, $v$, $T$ or $S$; 
    39 RHS is the Right-Hand-Side of the corresponding time evolution equation; 
     53RHS is the \textbf{R}ight-\textbf{H}and-\textbf{S}ide of the corresponding time evolution equation; 
    4054$\rdt$ is the time step; 
    4155and the superscripts indicate the time at which a quantity is evaluated. 
    42 Each term of the RHS is evaluated at a specific time step depending on the physics with which it is associated. 
    43  
    44 The choice of the time step used for this evaluation is discussed below as well as 
     56Each term of the RHS is evaluated at a specific time stepping depending on 
     57the physics with which it is associated. 
     58 
     59The choice of the time stepping used for this evaluation is discussed below as well as 
    4560the implications for starting or restarting a model simulation. 
    4661Note that the time stepping calculation is generally performed in a single operation. 
    47 With such a complex and nonlinear system of equations it would be dangerous to let a prognostic variable evolve in 
    48 time for each term separately. 
     62With such a complex and nonlinear system of equations it would be dangerous to 
     63let a prognostic variable evolve in time for each term separately. 
    4964 
    5065The three level scheme requires three arrays for each prognostic variable. 
     
    5267The third array, although referred to as $x_a$ (after) in the code, 
    5368is usually not the variable at the after time step; 
    54 but rather it is used to store the time derivative (RHS in \autoref{eq:STP}) prior to time-stepping the equation. 
    55 Generally, the time stepping is performed once at each time step in the \mdl{tranxt} and \mdl{dynnxt} modules, 
    56 except when using implicit vertical diffusion or calculating sea surface height in which 
    57 case time-splitting options are used. 
    58  
    59 % ------------------------------------------------------------------------------------------------------------- 
    60 %        Non-Diffusive Part---Leapfrog Scheme 
    61 % ------------------------------------------------------------------------------------------------------------- 
     69but rather it is used to store the time derivative (RHS in \autoref{eq:TD}) 
     70prior to time-stepping the equation. 
     71The time stepping itself is performed once at each time step where 
     72implicit vertical diffusion is computed, 
     73\ie\ in the \mdl{trazdf} and \mdl{dynzdf} modules. 
     74 
     75%% ================================================================================================= 
    6276\section{Non-diffusive part --- Leapfrog scheme} 
    63 \label{sec:STP_leap_frog} 
    64  
    65 The time stepping used for processes other than diffusion is the well-known leapfrog scheme 
    66 \citep{Mesinger_Arakawa_Bk76}. 
     77\label{sec:TD_leap_frog} 
     78 
     79The time stepping used for processes other than diffusion is 
     80the well-known \textbf{L}eap\textbf{F}rog (LF) scheme \citep{mesinger.arakawa_bk76}. 
    6781This scheme is widely used for advection processes in low-viscosity fluids. 
    68 It is a time centred scheme, \ie the RHS in \autoref{eq:STP} is evaluated at time step $t$, the now time step. 
     82It is a time centred scheme, \ie\ the RHS in \autoref{eq:TD} is evaluated at 
     83time step $t$, the now time step. 
    6984It may be used for momentum and tracer advection, pressure gradient, and Coriolis terms, 
    7085but not for diffusion terms. 
    7186It is an efficient method that achieves second-order accuracy with 
    7287just one right hand side evaluation per time step. 
    73 Moreover, it does not artificially damp linear oscillatory motion nor does it produce instability by 
    74 amplifying the oscillations. 
     88Moreover, it does not artificially damp linear oscillatory motion 
     89nor does it produce instability by amplifying the oscillations. 
    7590These advantages are somewhat diminished by the large phase-speed error of the leapfrog scheme, 
    76 and the unsuitability of leapfrog differencing for the representation of diffusion and Rayleigh damping processes. 
     91and the unsuitability of leapfrog differencing for the representation of diffusion and 
     92Rayleigh damping processes. 
    7793However, the scheme allows the coexistence of a numerical and a physical mode due to 
    7894its leading third order dispersive error. 
    7995In other words a divergence of odd and even time steps may occur. 
    80 To prevent it, the leapfrog scheme is often used in association with a Robert-Asselin time filter 
    81 (hereafter the LF-RA scheme). 
    82 This filter, first designed by \citet{Robert_JMSJ66} and more comprehensively studied by \citet{Asselin_MWR72}, 
     96To prevent it, the leapfrog scheme is often used in association with 
     97a \textbf{R}obert-\textbf{A}sselin time filter (hereafter the LF-RA scheme). 
     98This filter, 
     99first designed by \citet{robert_JMSJ66} and more comprehensively studied by \citet{asselin_MWR72}, 
    83100is a kind of laplacian diffusion in time that mixes odd and even time steps: 
    84101\begin{equation} 
    85   \label{eq:STP_asselin} 
     102  \label{eq:TD_asselin} 
    86103  x_F^t = x^t + \gamma \, \lt[ x_F^{t - \rdt} - 2 x^t + x^{t + \rdt} \rt] 
    87104\end{equation} 
    88105where the subscript $F$ denotes filtered values and $\gamma$ is the Asselin coefficient. 
    89 $\gamma$ is initialized as \np{rn\_atfp} (namelist parameter). 
    90 Its default value is \np{rn\_atfp}~\forcode{= 10.e-3} (see \autoref{sec:STP_mLF}), 
    91 causing only a weak dissipation of high frequency motions (\citep{Farge1987}). 
     106$\gamma$ is initialized as \np{rn_atfp}{rn\_atfp} (namelist parameter). 
     107Its default value is \np[=10.e-3]{rn_atfp}{rn\_atfp} (see \autoref{sec:TD_mLF}), 
     108causing only a weak dissipation of high frequency motions (\citep{farge-coulombier_phd87}). 
    92109The addition of a time filter degrades the accuracy of the calculation from second to first order. 
    93110However, the second order truncation error is proportional to $\gamma$, which is small compared to 1. 
    94111Therefore, the LF-RA is a quasi second order accurate scheme. 
    95 The LF-RA scheme is preferred to other time differencing schemes such as predictor corrector or trapezoidal schemes, 
    96 because the user has an explicit and simple control of the magnitude of the time diffusion of the scheme. 
    97 When used with the 2nd order space centred discretisation of the advection terms in 
     112The LF-RA scheme is preferred to other time differencing schemes such as 
     113predictor corrector or trapezoidal schemes, because the user has an explicit and simple control of 
     114the magnitude of the time diffusion of the scheme. 
     115When used with the 2$^nd$ order space centred discretisation of the advection terms in 
    98116the momentum and tracer equations, LF-RA avoids implicit numerical diffusion: 
    99 diffusion is set explicitly by the user through the Robert-Asselin  
    100 filter parameter and the viscosity and diffusion coefficients. 
    101  
    102 % ------------------------------------------------------------------------------------------------------------- 
    103 %        Diffusive Part---Forward or Backward Scheme 
    104 % ------------------------------------------------------------------------------------------------------------- 
     117diffusion is set explicitly by the user through the Robert-Asselin filter parameter and 
     118the viscosity and diffusion coefficients. 
     119 
     120%% ================================================================================================= 
    105121\section{Diffusive part --- Forward or backward scheme} 
    106 \label{sec:STP_forward_imp} 
    107  
    108 The leapfrog differencing scheme is unsuitable for the representation of diffusion and damping processes. 
    109 For a tendancy $D_x$, representing a diffusion term or a restoring term to a tracer climatology 
     122\label{sec:TD_forward_imp} 
     123 
     124The leapfrog differencing scheme is unsuitable for 
     125the representation of diffusion and damping processes. 
     126For a tendency $D_x$, representing a diffusion term or a restoring term to a tracer climatology 
    110127(when present, see \autoref{sec:TRA_dmp}), a forward time differencing scheme is used : 
    111128\[ 
    112   %\label{eq:STP_euler} 
     129  %\label{eq:TD_euler} 
    113130  x^{t + \rdt} = x^{t - \rdt} + 2 \, \rdt \ D_x^{t - \rdt} 
    114131\] 
    115132 
    116133This is diffusive in time and conditionally stable. 
    117 The conditions for stability of second and fourth order horizontal diffusion schemes are \citep{Griffies_Bk04}: 
     134The conditions for stability of second and fourth order horizontal diffusion schemes are 
     135\citep{griffies_bk04}: 
    118136\begin{equation} 
    119   \label{eq:STP_euler_stability} 
     137  \label{eq:TD_euler_stability} 
    120138  A^h < 
    121139  \begin{cases} 
     
    124142  \end{cases} 
    125143\end{equation} 
    126 where $e$ is the smallest grid size in the two horizontal directions and $A^h$ is the mixing coefficient. 
    127 The linear constraint \autoref{eq:STP_euler_stability} is a necessary condition, but not sufficient. 
     144where $e$ is the smallest grid size in the two horizontal directions and 
     145$A^h$ is the mixing coefficient. 
     146The linear constraint \autoref{eq:TD_euler_stability} is a necessary condition, but not sufficient. 
    128147If it is not satisfied, even mildly, then the model soon becomes wildly unstable. 
    129 The instability can be removed by either reducing the length of the time steps or reducing the mixing coefficient. 
     148The instability can be removed by either reducing the length of the time steps or 
     149reducing the mixing coefficient. 
    130150 
    131151For the vertical diffusion terms, a forward time differencing scheme can be used, 
    132152but usually the numerical stability condition imposes a strong constraint on the time step. 
    133 Two solutions are available in \NEMO to overcome the stability constraint: 
    134 $(a)$ a forward time differencing scheme using a time splitting technique (\np{ln\_zdfexp}~\forcode{= .true.}) or 
    135 $(b)$ a backward (or implicit) time differencing scheme                   (\np{ln\_zdfexp}~\forcode{= .false.}). 
    136 In $(a)$, the master time step $\Delta$t is cut into $N$ fractional time steps so that 
    137 the stability criterion is reduced by a factor of $N$. 
    138 The computation is performed as follows: 
    139 \begin{alignat*}{2} 
    140   % \label{eq:STP_ts} 
    141   &x_\ast^{t - \rdt}                      &= &x^{t - \rdt} \\ 
    142   &x_\ast^{t - \rdt + L \frac{2 \rdt}{N}} &=   &x_\ast ^{t - \rdt + (L - 1) \frac{2 \rdt}{N}} 
    143                                              + \frac{2 \rdt}{N} \; DF^{t - \rdt + (L - 1) \frac{2 \rdt}{N}} 
    144   \quad \text{for $L = 1$ to $N$} \\ 
    145   &x^{t + \rdt}                           &= &x_\ast^{t + \rdt} 
    146 \end{alignat*} 
    147 with DF a vertical diffusion term. 
    148 The number of fractional time steps, $N$, is given by setting \np{nn\_zdfexp}, (namelist parameter). 
    149 The scheme $(b)$ is unconditionally stable but diffusive. It can be written as follows: 
     153To overcome the stability constraint, a backward (or implicit) time differencing scheme is used. 
     154This scheme is unconditionally stable but diffusive and can be written as follows: 
    150155\begin{equation} 
    151   \label{eq:STP_imp} 
     156  \label{eq:TD_imp} 
    152157  x^{t + \rdt} = x^{t - \rdt} + 2 \, \rdt \ \text{RHS}_x^{t + \rdt} 
    153158\end{equation} 
    154159 
    155 %%gm 
    156 %%gm   UPDATE the next paragraphs with time varying thickness ... 
    157 %%gm 
    158  
    159 This scheme is rather time consuming since it requires a matrix inversion, 
    160 but it becomes attractive since a value of 3 or more is needed for N in the forward time differencing scheme. 
     160\cmtgm{UPDATE the next paragraphs with time varying thickness ...} 
     161 
     162This scheme is rather time consuming since it requires a matrix inversion. 
    161163For example, the finite difference approximation of the temperature equation is: 
    162164\[ 
    163   % \label{eq:STP_imp_zdf} 
     165  % \label{eq:TD_imp_zdf} 
    164166  \frac{T(k)^{t + 1} - T(k)^{t - 1}}{2 \; \rdt} 
    165167  \equiv 
     
    167169\] 
    168170where RHS is the right hand side of the equation except for the vertical diffusion term. 
    169 We rewrite \autoref{eq:STP_imp} as: 
     171We rewrite \autoref{eq:TD_imp} as: 
    170172\begin{equation} 
    171   \label{eq:STP_imp_mat} 
     173  \label{eq:TD_imp_mat} 
    172174  -c(k + 1) \; T^{t + 1}(k + 1) + d(k) \; T^{t + 1}(k) - \; c(k) \; T^{t + 1}(k - 1) \equiv b(k) 
    173175\end{equation} 
    174 where  
    175 \begin{align*}  
    176   c(k) &= A_w^{vT} (k) \, / \, e_{3w} (k)     \\ 
    177   d(k) &= e_{3t}   (k)       \, / \, (2 \rdt) + c_k + c_{k + 1}    \\ 
    178   b(k) &= e_{3t}   (k) \; \lt( T^{t - 1}(k) \, / \, (2 \rdt) + \text{RHS} \rt) 
    179 \end{align*} 
    180  
    181 \autoref{eq:STP_imp_mat} is a linear system of equations with an associated matrix which is tridiagonal. 
    182 Moreover, 
    183 $c(k)$ and $d(k)$ are positive and the diagonal term is greater than the sum of the two extra-diagonal terms, 
     176where 
     177\[ 
     178  c(k) = A_w^{vT} (k) \, / \, e_{3w} (k) \text{,} \quad 
     179  d(k) = e_{3t}   (k)       \, / \, (2 \rdt) + c_k + c_{k + 1} \quad \text{and} \quad 
     180  b(k) = e_{3t}   (k) \; \lt( T^{t - 1}(k) \, / \, (2 \rdt) + \text{RHS} \rt) 
     181\] 
     182 
     183\autoref{eq:TD_imp_mat} is a linear system of equations with 
     184an associated matrix which is tridiagonal. 
     185Moreover, $c(k)$ and $d(k)$ are positive and 
     186the diagonal term is greater than the sum of the two extra-diagonal terms, 
    184187therefore a special adaptation of the Gauss elimination procedure is used to find the solution 
    185 (see for example \citet{Richtmyer1967}). 
    186  
    187 % ------------------------------------------------------------------------------------------------------------- 
    188 %        Surface Pressure gradient 
    189 % ------------------------------------------------------------------------------------------------------------- 
     188(see for example \citet{richtmyer.morton_bk67}). 
     189 
     190%% ================================================================================================= 
    190191\section{Surface pressure gradient} 
    191 \label{sec:STP_spg_ts} 
    192  
    193 ===>>>>  TO BE written....  :-) 
    194  
    195 %\gmcomment{  
    196 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    197 \begin{figure}[!t] 
    198   \begin{center} 
    199     \includegraphics[]{Fig_TimeStepping_flowchart} 
    200     \caption{ 
    201       \protect\label{fig:TimeStep_flowchart} 
    202       Sketch of the leapfrog time stepping sequence in \NEMO from \citet{Leclair_Madec_OM09}. 
    203       The use of a semi -implicit computation of the hydrostatic pressure gradient requires the tracer equation to 
    204       be stepped forward prior to the momentum equation. 
    205       The need for knowledge of the vertical scale factor (here denoted as $h$) requires the sea surface height and 
    206       the continuity equation to be stepped forward prior to the computation of the tracer equation. 
    207       Note that the method for the evaluation of the surface pressure gradient $\nabla p_s$ is not presented here 
    208       (see \autoref{sec:DYN_spg}). 
    209     } 
    210   \end{center} 
     192\label{sec:TD_spg_ts} 
     193 
     194The leapfrog environment supports a centred in time computation of the surface pressure, 
     195\ie\ evaluated at \textit{now} time step. 
     196This refers to as the explicit free surface case in the code 
     197(\np[=.true.]{ln_dynspg_exp}{ln\_dynspg\_exp}). 
     198This choice however imposes a strong constraint on the time step which 
     199should be small enough to resolve the propagation of external gravity waves. 
     200As a matter of fact, one rather use in a realistic setup, 
     201a split-explicit free surface (\np[=.true.]{ln_dynspg_ts}{ln\_dynspg\_ts}) in which 
     202barotropic and baroclinic dynamical equations are solved separately with ad-hoc time steps. 
     203The use of the time-splitting (in combination with non-linear free surface) imposes 
     204some constraints on the design of the overall flowchart, 
     205in particular to ensure exact tracer conservation (see \autoref{fig:TD_TimeStep_flowchart}). 
     206 
     207Compared to the former use of the filtered free surface in \NEMO\ v3.6 (\citet{roullet.madec_JGR00}), 
     208the use of a split-explicit free surface is advantageous on massively parallel computers. 
     209Indeed, no global computations are anymore required by the elliptic solver which 
     210saves a substantial amount of communication time. 
     211Fast barotropic motions (such as tides) are also simulated with a better accuracy. 
     212 
     213%\cmtgm{ 
     214\begin{figure} 
     215  \centering 
     216  \includegraphics[width=0.66\textwidth]{TD_TimeStepping_flowchart_v4} 
     217  \caption[Leapfrog time stepping sequence with split-explicit free surface]{ 
     218    Sketch of the leapfrog time stepping sequence in \NEMO\ with split-explicit free surface. 
     219    The latter combined with non-linear free surface requires 
     220    the dynamical tendency being updated prior tracers tendency to ensure conservation. 
     221    Note the use of time integrated fluxes issued from the barotropic loop in 
     222    subsequent calculations of tracer advection and in the continuity equation. 
     223    Details about the time-splitting scheme can be found in \autoref{subsec:DYN_spg_ts}.} 
     224  \label{fig:TD_TimeStep_flowchart} 
    211225\end{figure} 
    212 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    213226%} 
    214227 
    215 % ------------------------------------------------------------------------------------------------------------- 
    216 %        The Modified Leapfrog -- Asselin Filter scheme 
    217 % ------------------------------------------------------------------------------------------------------------- 
    218 \section{Modified Leapfrog -- Asselin filter scheme} 
    219 \label{sec:STP_mLF} 
    220  
    221 Significant changes have been introduced by \cite{Leclair_Madec_OM09} in the LF-RA scheme in order to 
    222 ensure tracer conservation and to allow the use of a much smaller value of the Asselin filter parameter. 
     228%% ================================================================================================= 
     229\section{Modified LeapFrog -- Robert Asselin filter scheme (LF-RA)} 
     230\label{sec:TD_mLF} 
     231 
     232Significant changes have been introduced by \cite{leclair.madec_OM09} in 
     233the LF-RA scheme in order to ensure tracer conservation and to 
     234allow the use of a much smaller value of the Asselin filter parameter. 
    223235The modifications affect both the forcing and filtering treatments in the LF-RA scheme. 
    224236 
    225 In a classical LF-RA environment, the forcing term is centred in time, 
    226 \ie it is time-stepped over a $2 \rdt$ period: 
     237In a classical LF-RA environment, 
     238the forcing term is centred in time, \ie\ it is time-stepped over a $2 \rdt$ period: 
    227239$x^t = x^t + 2 \rdt Q^t$ where $Q$ is the forcing applied to $x$, 
    228 and the time filter is given by \autoref{eq:STP_asselin} so that $Q$ is redistributed over several time step. 
     240and the time filter is given by \autoref{eq:TD_asselin} so that 
     241$Q$ is redistributed over several time step. 
    229242In the modified LF-RA environment, these two formulations have been replaced by: 
    230243\begin{gather} 
    231   \label{eq:STP_forcing} 
     244  \label{eq:TD_forcing} 
    232245  x^{t + \rdt} = x^{t - \rdt} + \rdt \lt( Q^{t - \rdt / 2} + Q^{t + \rdt / 2} \rt)  \\ 
    233   \label{eq:STP_RA} 
     246  \label{eq:TD_RA} 
    234247  x_F^t       = x^t + \gamma \, \lt( x_F^{t - \rdt} - 2 x^t + x^{t + \rdt} \rt) 
    235248                    - \gamma \, \rdt \, \lt( Q^{t + \rdt / 2} - Q^{t - \rdt / 2} \rt) 
    236249\end{gather} 
    237 The change in the forcing formulation given by \autoref{eq:STP_forcing} (see \autoref{fig:MLF_forcing}) 
    238 has a significant effect: 
    239 the forcing term no longer excites the divergence of odd and even time steps \citep{Leclair_Madec_OM09}. 
     250The change in the forcing formulation given by \autoref{eq:TD_forcing} 
     251(see \autoref{fig:TD_MLF_forcing}) has a significant effect: 
     252the forcing term no longer excites the divergence of odd and even time steps 
     253\citep{leclair.madec_OM09}. 
    240254% forcing seen by the model.... 
    241 This property improves the LF-RA scheme in two respects. 
     255This property improves the LF-RA scheme in two aspects. 
    242256First, the LF-RA can now ensure the local and global conservation of tracers. 
    243257Indeed, time filtering is no longer required on the forcing part. 
    244 The influence of the Asselin filter on the forcing is be removed by adding a new term in the filter 
    245 (last term in \autoref{eq:STP_RA} compared to \autoref{eq:STP_asselin}). 
     258The influence of the Asselin filter on the forcing is explicitly removed by 
     259adding a new term in the filter (last term in \autoref{eq:TD_RA} compared to \autoref{eq:TD_asselin}). 
    246260Since the filtering of the forcing was the source of non-conservation in the classical LF-RA scheme, 
    247 the modified formulation becomes conservative \citep{Leclair_Madec_OM09}. 
    248 Second, the LF-RA becomes a truly quasi -second order scheme. 
    249 Indeed, \autoref{eq:STP_forcing} used in combination with a careful treatment of static instability 
    250 (\autoref{subsec:ZDF_evd}) and of the TKE physics (\autoref{subsec:ZDF_tke_ene}), 
    251 the two other main sources of time step divergence, 
     261the modified formulation becomes conservative \citep{leclair.madec_OM09}. 
     262Second, the LF-RA becomes a truly quasi-second order scheme. 
     263Indeed, \autoref{eq:TD_forcing} used in combination with a careful treatment of static instability 
     264(\autoref{subsec:ZDF_evd}) and of the TKE physics (\autoref{subsec:ZDF_tke_ene}) 
     265(the two other main sources of time step divergence), 
    252266allows a reduction by two orders of magnitude of the Asselin filter parameter. 
    253267 
    254268Note that the forcing is now provided at the middle of a time step: 
    255269$Q^{t + \rdt / 2}$ is the forcing applied over the $[t,t + \rdt]$ time interval. 
    256 This and the change in the time filter, \autoref{eq:STP_RA}, 
    257 allows an exact evaluation of the contribution due to the forcing term between any two time steps, 
     270This and the change in the time filter, \autoref{eq:TD_RA}, 
     271allows for an exact evaluation of the contribution due to the forcing term between any two time steps, 
    258272even if separated by only $\rdt$ since the time filter is no longer applied to the forcing term. 
    259273 
    260 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    261 \begin{figure}[!t] 
    262   \begin{center} 
    263     \includegraphics[]{Fig_MLF_forcing} 
    264     \caption{ 
    265       \protect\label{fig:MLF_forcing} 
    266       Illustration of forcing integration methods. 
    267       (top) ''Traditional'' formulation: 
    268       the forcing is defined at the same time as the variable to which it is applied 
    269       (integer value of the time step index) and it is applied over a $2 \rdt$ period. 
    270       (bottom)  modified formulation: 
    271       the forcing is defined in the middle of the time (integer and a half value of the time step index) and 
    272       the mean of two successive forcing values ($n - 1 / 2$, $n + 1 / 2$) is applied over a $2 \rdt$ period. 
    273     } 
    274   \end{center} 
     274\begin{figure} 
     275  \centering 
     276  \includegraphics[width=0.66\textwidth]{TD_MLF_forcing} 
     277  \caption[Forcing integration methods for modified leapfrog (top and bottom)]{ 
     278    Illustration of forcing integration methods. 
     279    (top) ''Traditional'' formulation: 
     280    the forcing is defined at the same time as the variable to which it is applied 
     281    (integer value of the time step index) and it is applied over a $2 \rdt$ period. 
     282    (bottom)  modified formulation: 
     283    the forcing is defined in the middle of the time 
     284    (integer and a half value of the time step index) and 
     285    the mean of two successive forcing values ($n - 1 / 2$, $n + 1 / 2$) is applied over 
     286    a $2 \rdt$ period.} 
     287  \label{fig:TD_MLF_forcing} 
    275288\end{figure} 
    276 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    277  
    278 % ------------------------------------------------------------------------------------------------------------- 
    279 %        Start/Restart strategy 
    280 % ------------------------------------------------------------------------------------------------------------- 
     289 
     290%% ================================================================================================= 
    281291\section{Start/Restart strategy} 
    282 \label{sec:STP_rst} 
    283  
    284 %--------------------------------------------namrun------------------------------------------- 
    285 \nlst{namrun} 
    286 %-------------------------------------------------------------------------------------------------------------- 
    287  
    288 The first time step of this three level scheme when starting from initial conditions is a forward step 
    289 (Euler time integration): 
     292\label{sec:TD_rst} 
     293 
     294\begin{listing} 
     295  \nlst{namrun} 
     296  \caption{\forcode{&namrun}} 
     297  \label{lst:namrun} 
     298\end{listing} 
     299 
     300The first time step of this three level scheme when starting from initial conditions is 
     301a forward step (Euler time integration): 
    290302\[ 
    291   % \label{eq:DOM_euler} 
     303  % \label{eq:TD_DOM_euler} 
    292304  x^1 = x^0 + \rdt \ \text{RHS}^0 
    293305\] 
    294 This is done simply by keeping the leapfrog environment (\ie the \autoref{eq:STP} three level time stepping) but 
     306This is done simply by keeping the leapfrog environment 
     307(\ie\ the \autoref{eq:TD} three level time stepping) but 
    295308setting all $x^0$ (\textit{before}) and $x^1$ (\textit{now}) fields equal at the first time step and 
    296 using half the value of $\rdt$. 
     309using half the value of a leapfrog time step ($2 \rdt$). 
    297310 
    298311It is also possible to restart from a previous computation, by using a restart file. 
     
    301314running the model for $2N$ time steps in one go, 
    302315or by performing two consecutive experiments of $N$ steps with a restart. 
    303 This requires saving two time levels and many auxiliary data in the restart files in machine precision. 
    304  
    305 Note that when a semi -implicit scheme is used to evaluate the hydrostatic pressure gradient 
    306 (see \autoref{subsec:DYN_hpg_imp}), an extra three-dimensional field has to 
    307 be added to the restart file to ensure an exact restartability. 
    308 This is done optionally via the  \np{nn\_dynhpg\_rst} namelist parameter, 
    309 so that the size of the restart file can be reduced when restartability is not a key issue 
    310 (operational oceanography or in ensemble simulations for seasonal forecasting). 
    311  
    312 Note the size of the time step used, $\rdt$, is also saved in the restart file. 
    313 When restarting, if the the time step has been changed, a restart using an Euler time stepping scheme is imposed. 
    314 Options are defined through the  \ngn{namrun} namelist variables. 
    315 %%% 
    316 \gmcomment{ 
     316This requires saving two time levels and many auxiliary data in 
     317the restart files in machine precision. 
     318 
     319Note that the time step $\rdt$, is also saved in the restart file. 
     320When restarting, if the time step has been changed, or 
     321one of the prognostic variables at \textit{before} time step is missing, 
     322an Euler time stepping scheme is imposed. 
     323A forward initial step can still be enforced by the user by 
     324setting the namelist variable \np[=0]{nn_euler}{nn\_euler}. 
     325Other options to control the time integration of the model are defined through 
     326the \nam{run}{run} namelist variables. 
     327 
     328\cmtgm{ 
    317329add here how to force the restart to contain only one time step for operational purposes 
    318330 
    319331add also the idea of writing several restart for seasonal forecast : how is it done ? 
    320332 
    321 verify that all namelist pararmeters are truly described  
     333verify that all namelist parameters are truly described 
    322334 
    323335a word on the check of restart  ..... 
    324336} 
    325 %%% 
    326  
    327 \gmcomment{       % add a subsection here   
    328  
    329 %------------------------------------------------------------------------------------------------------------- 
    330 %        Time Domain 
    331 % ------------------------------------------------------------------------------------------------------------- 
     337 
     338\cmtgm{       % add a subsection here 
     339 
     340%% ================================================================================================= 
    332341\subsection{Time domain} 
    333 \label{subsec:STP_time} 
    334 %--------------------------------------------namrun------------------------------------------- 
    335  
    336 \nlst{namdom}          
    337 %-------------------------------------------------------------------------------------------------------------- 
    338  
    339 Options are defined through the  \ngn{namdom} namelist variables. 
     342\label{subsec:TD_time} 
     343 
     344Options are defined through the\nam{dom}{dom} namelist variables. 
    340345 \colorbox{yellow}{add here a few word on nit000 and nitend} 
    341346 
    342347 \colorbox{yellow}{Write documentation on the calendar and the key variable adatrj} 
    343348 
    344 add a description of daymod, and the model calandar (leap-year and co) 
    345  
    346 }        %% end add 
    347  
    348  
    349  
    350 %% 
    351 \gmcomment{       % add implicit in vvl case  and Crant-Nicholson scheme    
     349add a description of daymod, and the model calendar (leap-year and co) 
     350 
     351}     %% end add 
     352 
     353\cmtgm{       % add implicit in vvl case  and Crant-Nicholson scheme 
    352354 
    353355Implicit time stepping in case of variable volume thickness. 
     
    398400\end{flalign*} 
    399401 
    400 %% 
    401402} 
    402403 
    403 \biblio 
    404  
    405 \pindex 
     404\subinc{\input{../../global/epilogue}} 
    406405 
    407406\end{document} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3

    • Property svn:ignore deleted
    • Property svn:externals set to
      ^/utils/figures/SI3 figures
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/main

    • Property svn:ignore
      •  

        old new  
        1 *.aux 
        2 *.bbl 
        3 *.blg 
        4 *.dvi 
        5 *.fdb* 
        6 *.fls 
        7 *.idx 
        81*.ilg 
        92*.ind 
        10 *.log 
        11 *.maf 
        12 *.mtc* 
        13 *.out 
        14 *.pdf 
        15 *.toc 
        16 _minted-* 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/namelists

    • Property svn:ignore deleted
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/namelists/namdyn_adv

    r11026 r11831  
    22&namdyn_adv     !   Ice advection 
    33!------------------------------------------------------------------------------ 
    4    ln_adv_Pra       = .false.         !  Advection scheme (Prather) 
    5    ln_adv_UMx       = .true.          !  Advection scheme (Ultimate-Macho) 
     4   ln_adv_Pra       = .true.         !  Advection scheme (Prather) 
     5   ln_adv_UMx       = .false.          !  Advection scheme (Ultimate-Macho) 
    66      nn_UMx        =   5             !     order of the scheme for UMx (1-5 ; 20=centered 2nd order) 
    77/ 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/subfiles

    • Property svn:ignore
      •  

        old new  
        1 *.aux 
        2 *.bbl 
        3 *.blg 
        4 *.dvi 
        5 *.fdb* 
        6 *.fls 
        7 *.idx 
         1*.ind 
        82*.ilg 
        9 *.ind 
        10 *.log 
        11 *.maf 
        12 *.mtc* 
        13 *.out 
        14 *.pdf 
        15 *.toc 
        16 _minted-* 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/subfiles/chap_bdy_agrif.tex

    r11015 r11831  
    99\chapter{BDY and AGRIF with SI$^3$} 
    1010\label{chap:REG} 
    11 \minitoc 
     11\chaptertoc 
    1212 
    1313\newpage 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/subfiles/chap_domain.tex

    r11031 r11831  
    1010\chapter{Time, space and thickness space domain} 
    1111\label{chap:DOM} 
    12 \minitoc 
     12\chaptertoc 
    1313 
    1414\newpage 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/subfiles/chap_dynamics.tex

    r11015 r11831  
    1010\chapter{Ice dynamics} 
    1111\label{chap:DYN} 
    12 \minitoc 
     12\chaptertoc 
    1313 
    1414\newpage 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/subfiles/chap_interfaces.tex

    r11015 r11831  
    99\chapter{Ice-atmosphere and ice-ocean interfaces} 
    1010\label{chap:INT} 
    11 \minitoc 
     11\chaptertoc 
    1212 
    1313\newpage 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/subfiles/chap_miscellaneous.tex

    r11015 r11831  
    99\chapter{Miscellaneous topics} 
    1010\label{chap:MIS} 
    11 \minitoc 
     11\chaptertoc 
    1212 
    1313\newpage 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/subfiles/chap_model_basics.tex

    r11043 r11831  
    99\chapter{Model Basics} 
    1010\label{chap:MB} 
    11 \minitoc 
     11\chaptertoc 
    1212 
    1313\newpage 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/subfiles/chap_output_diagnostics.tex

    r11031 r11831  
    99\chapter{Output and diagnostics} 
    1010\label{chap:DIA} 
    11 \minitoc 
     11\chaptertoc 
    1212 
    1313\newpage 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/subfiles/chap_radiative_transfer.tex

    r11031 r11831  
    1313\chapter{Radiative transfer} 
    1414\label{chap:RAD} 
    15 \minitoc 
     15\chaptertoc 
    1616 
    1717\newpage 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/subfiles/chap_ridging_rafting.tex

    r11043 r11831  
    1010\chapter{Ridging and rafting} 
    1111\label{chap:RDG} 
    12 \minitoc 
     12\chaptertoc 
    1313 
    1414\newpage 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/subfiles/chap_single_category_use.tex

    r11015 r11831  
    1111 
    1212\label{chap:INT} 
    13 \minitoc 
     13\chaptertoc 
    1414 
    1515\newpage 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/subfiles/chap_thermo.tex

    r11031 r11831  
    99\chapter{Ice thermodynamics} 
    1010\label{chap:THD} 
    11 \minitoc 
     11\chaptertoc 
    1212 
    1313\newpage 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/SI3/subfiles/chap_transport.tex

    r11031 r11831  
    1010\chapter{Ice transport} 
    1111\label{chap:TRP} 
    12 \minitoc 
     12\chaptertoc 
    1313 
    1414\newpage 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/TOP

    • Property svn:ignore deleted
    • Property svn:externals set to
      ^/utils/figures/TOP figures
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/TOP/main

    • Property svn:ignore
      •  

        old new  
        1 *.aux 
        2 *.bbl 
        3 *.blg 
        4 *.dvi 
        5 *.fdb* 
        6 *.fls 
        7 *.idx 
        81*.ilg 
        92*.ind 
        10 *.log 
        11 *.maf 
        12 *.mtc* 
        13 *.out 
        14 *.pdf 
        15 *.toc 
        16 _minted-* 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/TOP/subfiles

    • Property svn:ignore
      •  

        old new  
        1 *.aux 
        2 *.bbl 
        3 *.blg 
        4 *.dvi 
        5 *.fdb* 
        6 *.fls 
        7 *.idx 
        81*.ilg 
        92*.ind 
        10 *.log 
        11 *.maf 
        12 *.mtc* 
        13 *.out 
        14 *.pdf 
        15 *.toc 
        16 _minted-* 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/TOP/subfiles/miscellaneous.tex

    r10896 r11831  
    1 \documentclass[../../NEMO/main/NEMO_manual]{subfiles} 
     1\documentclass[../main/TOP_manual]{subfiles} 
    22 
    33\begin{document} 
     
    4343\begin{minted}{bash} 
    4444   bld::tool::fppkeys   key_iomput key_mpp_mpi key_top 
    45     
     45 
    4646   src::MYBGC::initialization         <MYBGCPATH>/initialization 
    4747   src::MYBGC::pelagic                <MYBGCPATH>/pelagic 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/TOP/subfiles/model_description.tex

    r11043 r11831  
    1 \documentclass[../../NEMO/main/NEMO_manual]{subfiles} 
     1\documentclass[../main/TOP_manual]{subfiles} 
    22 
    33\newcommand{\cd}{\mathrm{CO_2}} 
     
    1414\chapter{Model Description} 
    1515\label{chap:ModDes} 
    16 \minitoc 
     16\chaptertoc 
    1717 
    1818\section{Basics} 
     
    2626\end{equation} 
    2727 
    28 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}  
     28where 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} 
    2929 
    3030{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. 
    3131 
    32 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}$  
    33  
    34 The third term  represents the change due to lateral diffusion.  
     32The 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}$ 
     33 
     34The third term  represents the change due to lateral diffusion. 
    3535 
    3636The fourth term is change due to vertical diffusion, parameterized as eddy diffusion to represent vertical turbulent fluxes : 
     
    6868 
    6969The 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. 
    70   
     70 
    7171 \subsection{ Advection} 
    7272%------------------------------------------namtrc_adv---------------------------------------------------- 
     
    8080\nlst{namtrc_ldf} 
    8181%------------------------------------------------------------------------------------------------------------- 
    82 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}.  
     82In 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 \nam{namtra_ldf}{namtra\_ldf} namelist for the dynamic described in section 5.2 of \citep{nemo_manual}. 
    8383 
    8484 
    8585%-----------------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 : 
    8686%-----------------\begin{equation} \label{eq:traqsr_iradiance} 
    87 %-----------------Aht  = Aht *  rn_fact_lap * \exp( - \max( 0., z -1000  ) / 1000}  \quad \text{for $L=1$ to $N$}   
     87%-----------------Aht  = Aht *  rn_fact_lap * \exp( - \max( 0., z -1000  ) / 1000}  \quad \text{for $L=1$ to $N$} 
    8888%-----------------\end{equation} 
    8989 
    9090 \subsection{ Tracer damping} 
    91   
     91 
    9292%------------------------------------------namtrc_dmp---------------------------------------------------- 
    9393\nlst{namtrc_dmp} 
     
    9595 
    9696The 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 
    97 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. 
     97Options are defined through the \nam{namtrc_dmp}{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. 
    9898 
    9999 \subsection{ Tracer positivity} 
    100   
     100 
    101101%------------------------------------------namtrc_rad---------------------------------------------------- 
    102102\nlst{namtrc_rad} 
     
    104104 
    105105Sometimes, 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. 
    106 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. 
     106The treatment of negative concentrations is an option and can be selected in the namelist \nam{namtrc_rad}{namtrc\_rad} by setting the parameter \np{ln\_trcrad}  to true. 
    107107 
    108108\section{The SMS modules} 
     
    160160As 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. 
    161161These 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 
    162 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  
     162stratospheric 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 
    163163than CO$_{2}$ (especially SF6), although their relatively low atmospheric concentrations limit their role in climate change. \\ 
    164164 
     
    168168% concentrations increased until around the late 1990s afterwhich they began to decline in 
    169169% response to the Montreal Protocol. 
    170 % In the case of SF6, release began in the 1950s  
     170% In the case of SF6, release began in the 1950s 
    171171% This release began in the 1930s for CFC-11 and CFC-12, and the 1950s for SF6, and 
    172 % regularly increasing their atmospheric concentration until the 1090s, 2000s for respectively CFC11, CFC12,  
     172% regularly increasing their atmospheric concentration until the 1090s, 2000s for respectively CFC11, CFC12, 
    173173% and is still increasing, and SF6 (see Figure \ref{img_cfcatm}).  \\ 
    174174 
     
    177177Because 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. 
    178178Measuring 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 
    179 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  
     179atmosphere). 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 
    180180ventilation of models, key for understanding the behaviour of wider modelled marine biogeochemistry (e.g. \citep{dutay_2002,palmieri_2015}). \\ 
    181181 
     
    183183 
    184184Advection and diffusion of the CFCs in NEMO are calculated by the physical module, OPA, 
    185 whereas sources and sinks are done by the CFC module within TOP.  
    186 The only source for CFCs in the ocean is via air-sea gas exchange at its surface, and since CFCs are generally  
    187 stable within the ocean, we assume that there are no sinks (i.e. no loss processes) within the ocean interior.  
     185whereas sources and sinks are done by the CFC module within TOP. 
     186The only source for CFCs in the ocean is via air-sea gas exchange at its surface, and since CFCs are generally 
     187stable within the ocean, we assume that there are no sinks (i.e. no loss processes) within the ocean interior. 
    188188Consequently, the sinks-minus-sources term for CFCs consists only of their air-sea fluxes, $F_{cfc}$, as 
    189189described in the Ocean Model Inter-comparison Project (OMIP) protocol \citep{orr_2017}: 
     
    196196F_{cfc} = K_{w} \, \cdot \, (C_{sat} - C_{surf}) \, \cdot  \, (1 - f_{i}) 
    197197\label{equ_CFC_flux} 
    198 \end{eqnarray}   
    199  
    200 Where $K_{w}$ is the piston velocity (in m~s$^{-1}$), as defined in Equation \ref{equ_Kw};  
    201 $C_{sat}$ is the saturation concentration of the CFC tracer, as defined in Equation \ref{equ_C_sat};  
    202 $C_{surf}$ is the local surface concentration of the CFC tracer within the model (in mol~m$^{-3}$);  
     198\end{eqnarray} 
     199 
     200Where $K_{w}$ is the piston velocity (in m~s$^{-1}$), as defined in Equation \ref{equ_Kw}; 
     201$C_{sat}$ is the saturation concentration of the CFC tracer, as defined in Equation \ref{equ_C_sat}; 
     202$C_{surf}$ is the local surface concentration of the CFC tracer within the model (in mol~m$^{-3}$); 
    203203and $f_{i}$ is the fractional sea-ice cover of the local ocean (ranging between 0.0 for ice-free ocean, 
    204204through to 1.0 for completely ice-covered ocean with no air-sea exchange). 
     
    209209C_{sat} = Sol \, \cdot \, P_{cfc} 
    210210\label{equ_C_sat} 
    211 \end{eqnarray}   
    212  
    213 Where $Sol$ is the gas solubility in mol~m$^{-3}$~pptv$^{-1}$, as defined in Equation \ref{equ_Sol_CFC};  
     211\end{eqnarray} 
     212 
     213Where $Sol$ is the gas solubility in mol~m$^{-3}$~pptv$^{-1}$, as defined in Equation \ref{equ_Sol_CFC}; 
    214214and $P_{cfc}$ is the atmosphere concentration of the CFC (in parts per trillion by volume, pptv). 
    215215This latter concentration is provided to the model by the historical time-series of \citet{bullister_2017}. 
    216 This includes bulk atmospheric concentrations of the CFCs for both hemispheres -- this is necessary because of  
    217 the geographical asymmetry in the production and release of CFCs to the atmosphere.  
    218 Within the model, hemispheric concentrations are uniform, with the exception of the region between  
     216This includes bulk atmospheric concentrations of the CFCs for both hemispheres -- this is necessary because of 
     217the geographical asymmetry in the production and release of CFCs to the atmosphere. 
     218Within the model, hemispheric concentrations are uniform, with the exception of the region between 
    21921910$^{\circ}$N and 10$^{\circ}$ in which they are linearly interpolated. 
    220220 
    221 The piston velocity $K_{w}$ is a function of 10~m wind speed (in m~s$^{-1}$) and sea surface temperature,  
     221The piston velocity $K_{w}$ is a function of 10~m wind speed (in m~s$^{-1}$) and sea surface temperature, 
    222222$T$ (in $^{\circ}$C), and is calculated here following \citet{wanninkhof_1992}: 
    223223 
     
    225225K_{w} = X_{conv} \, \cdot \, a \, \cdot \, u^2 \, \cdot \, \sqrt{ \frac{Sc(T)}{660} } 
    226226\label{equ_Kw} 
    227 \end{eqnarray}  
    228  
    229 Where $X_{conv}$ = $\frac{0.01}{3600}$, a conversion factor that changes the piston velocity  
    230 from cm~h$^{-1}$ to m~s$^{-1}$;  
     227\end{eqnarray} 
     228 
     229Where $X_{conv}$ = $\frac{0.01}{3600}$, a conversion factor that changes the piston velocity 
     230from cm~h$^{-1}$ to m~s$^{-1}$; 
    231231$a$ is a constant re-estimated by \citet{wanninkhof_2014} to 0.251 (in $\frac{cm~h^{-1}}{(m~s^{-1})^{2}}$); 
    232232and $u$ is the 10~m wind speed in m~s$^{-1}$ from either an atmosphere model or reanalysis atmospheric forcing. 
     
    236236Sc =  a0 + (a1 \, \cdot \, T) + (a2  \, \cdot \, T^2) + (a3 \, \cdot \, T^3) + (a4 \, \cdot \, T^4) 
    237237\label{equ_Sc} 
    238 \end{eqnarray}  
    239  
    240 The solubility, $Sol$, used in Equation \ref{equ_C_sat} is calculated in mol~l$^{-1}$~atm$^{-1}$,  
    241 and is specific for each gas.  
    242 It has been experimentally estimated by \citet{warner_1985} as a function of temperature  
     238\end{eqnarray} 
     239 
     240The solubility, $Sol$, used in Equation \ref{equ_C_sat} is calculated in mol~l$^{-1}$~atm$^{-1}$, 
     241and is specific for each gas. 
     242It has been experimentally estimated by \citet{warner_1985} as a function of temperature 
    243243and salinity: 
    244244 
     
    246246% code version that I have to hand, although this might be out of date; in any case, I'dag 
    247247% strongly suggest avoiding the use of the \frac{}{100}, and instead substitute a term that is 
    248 % "degrees Kelvin divided by 100" (which is weird in itself); and make this term use Celcius  
     248% "degrees Kelvin divided by 100" (which is weird in itself); and make this term use Celcius 
    249249% so that you're not using T twice in different ways 
    250250 
     
    252252\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 ) 
    253253\label{equ_Sol_CFC} 
    254 \end{eqnarray}   
     254\end{eqnarray} 
    255255 
    256256% \begin{eqnarray} 
    257257% \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 ) 
    258258% \label{equ_Sol_CFC} 
    259 % \end{eqnarray}   
    260  
    261 Where $T_{X}$ is $\frac{T + 273.16}{100}$, a function of temperature;  
     259% \end{eqnarray} 
     260 
     261Where $T_{X}$ is $\frac{T + 273.16}{100}$, a function of temperature; 
    262262and the $a_{x}$ and $b_{x}$ coefficients are specific for each gas (see Table \ref{tab_ref_CFC}). 
    263263This is then converted to mol~m$^{-3}$~pptv$^{-1}$ assuming a constant atmospheric surface pressure of 1~atm. 
    264 The solubility of CFCs thus decreases with rising $T$ while being relatively insensitive to salinity changes.  
     264The solubility of CFCs thus decreases with rising $T$ while being relatively insensitive to salinity changes. 
    265265Consequently, this translates to a pattern of solubility where it is greatest in cold, polar regions (see Figure \ref{img_cfcsol}). 
    266266 
     
    289289\centering 
    290290\begin{tabular}{l l l l l l l l l} 
    291 \hline  
    292 Gas   & & a1 & a2 & a3 & a4 & b1 & b2 & b3 \\           
     291\hline 
     292Gas   & & a1 & a2 & a3 & a4 & b1 & b2 & b3 \\ 
    293293\hline 
    294294CFC-11 & & -218.0971 & 298.9702 & 113.8049 & -1.39165 & -0.143566  & 0.091015   & -0.0153924 \\ 
     
    296296SF6    & & -80.0343  & 117.232  & 29.5817  & 0.0      & 0.0335183  & -0.0373942 & 0.00774862 \\ 
    297297\hline 
    298 \end{tabular}  
     298\end{tabular} 
    299299\label{tab_ref_CFC} 
    300300\end{table} 
     
    306306\centering 
    307307\begin{tabular}{l l l l l l l } 
    308 \hline  
    309 Gas  & & a0 & a1 & a2 & a3 & a4 \\           
     308\hline 
     309Gas  & & a0 & a1 & a2 & a3 & a4 \\ 
    310310\hline 
    311311CFC-11 & & 3579.2  & -222.63 & 7.5749 & -0.14595 & 0.0011874   \\ 
     
    313313SF6    & & 3177.5  & -200.57 & 6.8865 & -0.13335 & 0.0010877   \\ 
    314314\hline 
    315 \end{tabular}  
     315\end{tabular} 
    316316\label{tab_Sc} 
    317317\end{table} 
     
    353353%---------------------------------------------------------------------------------------------------------- 
    354354 
    355 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.  
     355The 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. 
    356356 
    357357\subsubsection{Method} 
     
    368368 
    369369This 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. 
    370 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.  
     370Since 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. 
    371371 
    372372Therefore the simplified approach is justified for the purpose of assessing the circulation and ventilation of OGCMs. 
     
    425425%The sensitivity to this parametrization is discussed in section \ref{sec:result}. 
    426426% 
    427 \item Chemical enhancement (term $b$  in Eq. \ref{eq:wanchem}) may be set on/off by means of the logical variable \CODE{ln\_chemh}.  
     427\item Chemical enhancement (term $b$  in Eq. \ref{eq:wanchem}) may be set on/off by means of the logical variable \CODE{ln\_chemh}. 
    428428\end{itemize} 
    429429 
     
    464464\end{figure} 
    465465 
    466 Performing this type of experiment requires that a pre-industrial equilibrium run be performed beforehand (\CODE{ln\_rsttr} should be set to \texttt{.TRUE.}).  
     466Performing this type of experiment requires that a pre-industrial equilibrium run be performed beforehand (\CODE{ln\_rsttr} should be set to \texttt{.TRUE.}). 
    467467 
    468468An 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). 
     
    476476\begin{itemize} 
    477477\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). 
    478 \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).  
     478\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). 
    479479\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). 
    480480\end{itemize} 
     
    497497 
    498498The 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}. 
    499 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.  
     499The $\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. 
    500500 
    501501To 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. 
     
    519519Field & Type & Dim & Units & Description \\ \hline 
    520520RC14 & ptrc & 3-D & -        & Radiocarbon ratio \\ 
    521 DeltaC14 & diad & 3-D & \textperthousand & $\Dcq$\\  
     521DeltaC14 & diad & 3-D & \textperthousand & $\Dcq$\\ 
    522522C14Age & diad & 3-D & yr &   Radiocarbon age \\ 
    523523RAge & diad & 2-D & yr & Reservoir age\\ 
    524524qtr\_c14 &  diad & 2-D & m$^{-2}$ yr$^{-1}$ & Air-to-sea net $\Rq$ flux\\ 
    525525qint\_c14 & diad & 2-D &   m$^{-2}$ &  Cumulative air-to-sea $\Rq$ flux \\ 
    526 AtmCO2 & scalar & 0-D & ppm & Global atmospheric $\cd$ \\  
    527 AtmC14 & scalar & 0-D & \textperthousand  & Global atmospheric $\Dcq$\\  
    528 K\_CO2 & scalar & 0-D & cm h$^{-1}$  & Global $\cd$ piston velocity ($ \overline{\kappa_{\cd}}$) \\  
    529 K\_C14 & scalar & 0-D &m yr$^{-1}$ & Global $\Rq$ transfer velocity  ($ \overline{\kappa_R}$)\\  
     526AtmCO2 & scalar & 0-D & ppm & Global atmospheric $\cd$ \\ 
     527AtmC14 & scalar & 0-D & \textperthousand  & Global atmospheric $\Dcq$\\ 
     528K\_CO2 & scalar & 0-D & cm h$^{-1}$  & Global $\cd$ piston velocity ($ \overline{\kappa_{\cd}}$) \\ 
     529K\_C14 & scalar & 0-D &m yr$^{-1}$ & Global $\Rq$ transfer velocity  ($ \overline{\kappa_R}$)\\ 
    530530C14Inv & scalar & 0-D & $10^{26}$ atoms & Ocean radiocarbon inventory \\ \hline 
    531531\end{tabular} 
     
    534534\end{table} 
    535535%!   Standard ratio: 1.176E-12 ; Avogadro's nbr = 6.022E+23 at/mol ; bomb C14 traditionally reported as 1.E+26 atoms 
    536 %   REAL(wp), PARAMETER            :: atomc14=1.176*6.022E-15   ! conversion factor  
     536%   REAL(wp), PARAMETER            :: atomc14=1.176*6.022E-15   ! conversion factor 
    537537% atomc14 * xdicsur * zdum 
    538538 
    539 The radiocarbon age is computed as  $(-1/\lambda) \ln{ \left( \Rq \right)}$, with zero age corresponding to $\Rq=1$.  
     539The radiocarbon age is computed as  $(-1/\lambda) \ln{ \left( \Rq \right)}$, with zero age corresponding to $\Rq=1$. 
    540540 
    541541The 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} 
     
    561561\subsection{PISCES biogeochemical model} 
    562562 
    563 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.  
     563PISCES 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. 
    564564Two versions of PISCES are available in NEMO v4.0 : 
    565565 
    566 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.  
     566PISCES-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. 
    567567 
    568568PISCES-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. 
     
    570570There 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. 
    571571 
    572   
     572 
    573573\subsection{MY\_TRC interface for coupling external BGC models} 
    574574\label{Mytrc} 
     
    597597 
    598598Coupling 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 
    599 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).  
     599At 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). 
    600600The 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. 
    601601 
     
    603603 
    604604\begin{itemize} 
    605    \item \textit{dtadyn.F90} :  this module allows to read and compute the dynamical fields at each model time-step  
     605   \item \textit{dtadyn.F90} :  this module allows to read and compute the dynamical fields at each model time-step 
    606606   \item \textit{nemogcm.F90} :  a degraded version of the main nemogcm.F90 code of NEMO to manage the time-stepping 
    607607\end{itemize} 
  • NEMO/branches/2019/dev_r11085_ASINTER-05_Brodeau_Advanced_Bulk/doc/latex/TOP/subfiles/model_setup.tex

    r11019 r11831  
    1 \documentclass[../../NEMO/main/NEMO_manual]{subfiles} 
     1\documentclass[../main/TOP_manual]{subfiles} 
    22 
    33\begin{document} 
     
    1010%------------------------------------------------------------------------------------------------------------- 
    1111 
    12 The usage of TOP is activated  
     12The usage of TOP is activated 
    1313 
    1414\begin{itemize} 
     
    1919As 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}) . 
    2020 
    21 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.  
     21Note 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. 
    2222 
    2323There are only three specific keys remaining in TOP 
     
    2828\end{itemize} 
    2929 
    30 For a remind, the revisited structure of TOP interface now counts for five different modules handled in namelist\_top :  
     30For a remind, the revisited structure of TOP interface now counts for five different modules handled in namelist\_top : 
    3131 
    3232\begin{itemize} 
Note: See TracChangeset for help on using the changeset viewer.