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 12149 for NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles – NEMO

Ignore:
Timestamp:
2019-12-10T15:03:24+01:00 (4 years ago)
Author:
ayoung
Message:

Updated trunk to 12072

Location:
NEMO/branches/2019/ENHANCE-03_closea/doc
Files:
8 deleted
21 edited
12 copied

Legend:

Unmodified
Added
Removed
  • NEMO/branches/2019/ENHANCE-03_closea/doc

    • Property svn:externals set to
      ^/utils/badges badges
      ^/utils/logos logos
  • NEMO/branches/2019/ENHANCE-03_closea/doc/latex

    • Property svn:ignore deleted
  • NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO

    • Property svn:externals set to
      ^/utils/figures/NEMO figures
  • NEMO/branches/2019/ENHANCE-03_closea/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/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_ASM.tex

    r11151 r12149  
    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} 
     
    3953This 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 
    4357With IAU, the model state trajectory ${\mathbf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$) 
     
    4559additional tendency terms to the prognostic equations: 
    4660\begin{align*} 
    47   % \label{eq:wa_traj_iau} 
     61  % \label{eq:ASM_wa_traj_iau} 
    4862  {\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*} 
     
    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\{ 
     
    6680    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\{ 
     
    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 
     
    120139\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/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_DIA.tex

    r11179 r12149  
    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 {\ttfamily using\_server} setting determines whether or not the server will be used in \textit{attached mode} 
    171 (as a library) [{\ttfamily> false <}] or in \textit{detached mode} 
    172 (as an external executable on N additional, dedicated cpus) [{\ttfamily > 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 {\ttfamily 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 ("\ttfamily{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 ("\ttfamily{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 ("\ttfamily{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 ("\ttfamily{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 ("\ttfamily{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 ("\ttfamily{*\_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 ("\ttfamily{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 (\texttt{\textbf{key\_netcdf4}})] 
    1335 {NetCDF4 support (\protect\key{netcdf4})} 
     1327%% ================================================================================================= 
     1328\section[NetCDF4 support (\texttt{\textbf{key\_netcdf4}})]{NetCDF4 support (\protect\key{netcdf4})} 
    13361329\label{sec:DIA_nc4} 
    13371330 
     
    13411334Chunking and compression can lead to significant reductions in file sizes for a small runtime overhead. 
    13421335For a fuller discussion on chunking and other performance issues the reader is referred to 
    1343 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}. 
    13441337 
    13451338The new features are only available when the code has been linked with a NetCDF4 library 
     
    13471340Datasets created with chunking and compression are not backwards compatible with NetCDF3 "classic" format but 
    13481341most analysis codes can be relinked simply with the new libraries and will then read both NetCDF3 and NetCDF4 files. 
    1349 NEMO executables linked with NetCDF4 libraries can be made to produce NetCDF3 files by 
    1350 setting the \np{ln\_nc4zip} logical to false in the \textit{namnc4} namelist: 
    1351  
    1352 %------------------------------------------namnc4---------------------------------------------------- 
    1353  
    1354 \nlst{namnc4} 
    1355 %------------------------------------------------------------------------------------------------------------- 
     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} 
    13561350 
    13571351If \key{netcdf4} has not been defined, these namelist parameters are not read. 
    1358 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. 
    13591353These functions will not be used but need to be included so that compilation is possible with NetCDF3 libraries. 
    13601354 
     
    13901384\end{forlines} 
    13911385 
    1392 \noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\ttfamily 46x38x1} respectively in 
    1393 the mono-processor case (\ie global domain of {\small\ttfamily 182x149x31}). 
    1394 An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in  
    1395 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 
    13961390a 4x2 mpi partitioning. 
    13971391Note the variation in the compression ratio achieved which reflects chiefly the dry to wet volume ratio of 
    13981392each processing region. 
    13991393 
    1400 %------------------------------------------TABLE---------------------------------------------------- 
    14011394\begin{table} 
    1402   \scriptsize 
    14031395  \centering 
    14041396  \begin{tabular}{lrrr} 
     
    14321424    ORCA2\_2d\_grid\_W\_0007.nc & 4416    & 1368     & 70\%      \\ 
    14331425  \end{tabular} 
    1434   \caption{ 
    1435     \protect\label{tab:NC4} 
    1436     Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression 
    1437   } 
     1426  \caption{Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression} 
     1427  \label{tab:DIA_NC4} 
    14381428\end{table} 
    1439 %---------------------------------------------------------------------------------------------------- 
    14401429 
    14411430When \key{iomput} is activated with \key{netcdf4} chunking and compression parameters for fields produced via 
    1442 \np{iom\_put} calls are set via an equivalent and identically named namelist to \textit{namnc4} in 
    1443 \np{xmlio\_server.def}. 
    1444 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 
    14451434serve the restart files. 
    14461435This duplication is unfortunate but appropriate since, if using io\_servers, the domain sizes of 
    14471436the individual files produced by the io\_server processes may be different to those produced by 
    14481437the invidual processing regions and different chunking choices may be desired. 
    1449   
    1450 % ------------------------------------------------------------------------------------------------------------- 
    1451 %       Tracer/Dynamics Trends 
    1452 % ------------------------------------------------------------------------------------------------------------- 
    1453 \section[Tracer/Dynamics trends (\texttt{namtrd})] 
    1454 {Tracer/Dynamics trends (\protect\ngn{namtrd})} 
     1438 
     1439%% ================================================================================================= 
     1440\section[Tracer/Dynamics trends (\forcode{&namtrd})]{Tracer/Dynamics trends (\protect\nam{trd}{trd})} 
    14551441\label{sec:DIA_trd} 
    14561442 
    1457 %------------------------------------------namtrd---------------------------------------------------- 
    1458  
    1459 \nlst{namtrd}  
    1460 %------------------------------------------------------------------------------------------------------------- 
     1443\begin{listing} 
     1444  \nlst{namtrd} 
     1445  \caption{\forcode{&namtrd}} 
     1446  \label{lst:namtrd} 
     1447\end{listing} 
    14611448 
    14621449Each trend of the dynamics and/or temperature and salinity time evolution equations can be send to 
    14631450\mdl{trddyn} and/or \mdl{trdtra} modules (see TRD directory) just after their computation 
    1464 (\ie at the end of each $dyn\cdots.F90$ and/or $tra\cdots.F90$ routines). 
    1465 This capability is controlled by options offered in \ngn{namtrd} namelist. 
    1466 Note that the output are done with xIOS, and therefore the \key{IOM} is required. 
    1467  
    1468 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.}: 
    14691456 
    14701457\begin{description} 
    1471 \item[\np{ln\_glo\_trd}]: 
    1472   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 
    14731459  the momentum and tracer equations is performed. 
    14741460  This also includes a check of $T^2$, $S^2$, $\tfrac{1}{2} (u^2+v2)$, 
    14751461  and potential energy time evolution equations properties; 
    1476 \item[\np{ln\_dyn\_trd}]: 
    1477   each 3D trend of the evolution of the two momentum components is output; 
    1478 \item[\np{ln\_dyn\_mxl}]: 
    1479   each 3D trend of the evolution of the two momentum components averaged over the mixed layer is output; 
    1480 \item[\np{ln\_vor\_trd}]: 
    1481   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, 
    14821465  then the curl is computed to obtain the barotropic vorticity tendencies which are output; 
    1483 \item[\np{ln\_KE\_trd}] : 
    1484   each 3D trend of the Kinetic Energy equation is output; 
    1485 \item[\np{ln\_tra\_trd}]: 
    1486   each 3D trend of the evolution of temperature and salinity is output; 
    1487 \item[\np{ln\_tra\_mxl}]: 
    1488   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; 
    14891469\end{description} 
    14901470 
    1491 Note that the mixed layer tendency diagnostic can also be used on biogeochemical models via  
    1492 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. 
    14931473 
    14941474\textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested. 
    1495 In particular, options associated with \np{ln\_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl} are not working, 
    1496 and none of the options have been tested with variable volume (\ie \key{vvl} defined). 
    1497  
    1498 % ------------------------------------------------------------------------------------------------------------- 
    1499 %       On-line Floats trajectories 
    1500 % ------------------------------------------------------------------------------------------------------------- 
    1501 \section[FLO: On-Line Floats trajectories (\texttt{\textbf{key\_floats}})] 
    1502 {FLO: On-Line Floats trajectories (\protect\key{floats})} 
    1503 \label{sec:FLO} 
    1504 %--------------------------------------------namflo------------------------------------------------------- 
    1505  
    1506 \nlst{namflo}  
    1507 %-------------------------------------------------------------------------------------------------------------- 
     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} 
    15081487 
    15091488The on-line computation of floats advected either by the three dimensional velocity field or constraint to 
    15101489remain at a given depth ($w = 0$ in the computation) have been introduced in the system during the CLIPPER project. 
    1511 Options are defined by \ngn{namflo} namelis variables. 
     1490Options are defined by \nam{flo}{flo} namelist variables. 
    15121491The algorithm used is based either on the work of \cite{blanke.raynaud_JPO97} (default option), 
    1513 or on a $4^th$ Runge-Hutta algorithm (\np{ln\_flork4}\forcode{ = .true.}). 
     1492or on a $4^th$ Runge-Hutta algorithm (\np[=.true.]{ln_flork4}{ln\_flork4}). 
    15141493Note that the \cite{blanke.raynaud_JPO97} algorithm have the advantage of providing trajectories which 
    15151494are consistent with the numeric of the code, so that the trajectories never intercept the bathymetry. 
    15161495 
     1496%% ================================================================================================= 
    15171497\subsubsection{Input data: initial coordinates} 
    15181498 
    15191499Initial coordinates can be given with Ariane Tools convention 
    1520 (IJK coordinates, (\np{ln\_ariane}\forcode{ = .true.}) ) or with longitude and latitude. 
    1521  
    1522 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}. 
    15231503Its format is: \\ 
    1524 {\scriptsize \texttt{I J K nisobfl itrash itrash}} 
     1504{ \texttt{I J K nisobfl itrash}} 
    15251505 
    15261506\noindent with: 
     
    15281508 - I,J,K  : indexes of initial position 
    15291509 
    1530  - 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 
    15311511 
    15321512 - itrash : set to zero; it is a dummy variable to respect Ariane Tools convention 
     
    15341514\noindent Example: \\ 
    15351515\noindent 
    1536 {\scriptsize 
     1516{ 
    15371517  \texttt{ 
    15381518    100.00000  90.00000  -1.50000 1.00000   0.00000   \\ 
     
    15451525In the other case (longitude and latitude), input filename is init\_float. 
    15461526Its format is: \\ 
    1547 {\scriptsize \texttt{Long Lat depth nisobfl ngrpfl itrash}} 
     1527{ \texttt{Long Lat depth nisobfl ngrpfl itrash}} 
    15481528 
    15491529\noindent with: 
     
    15591539\noindent Example: \\ 
    15601540\noindent 
    1561 {\scriptsize 
     1541{ 
    15621542  \texttt{ 
    15631543    20.0 0.0 0.0 0 1 1    \\ 
     
    15681548} \\ 
    15691549 
    1570 \np{jpnfl} is the total number of floats during the run. 
    1571 When initial positions are read in a restart file (\np{ln\_rstflo}\forcode{ = .true.} ), 
    1572 \np{jpnflnewflo} can be added in the initialization file. 
    1573  
     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%% ================================================================================================= 
    15741555\subsubsection{Output data} 
    15751556 
    1576 \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 
    15771558creation of the float restart file. 
    15781559 
    1579 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}). 
    15801561In that case, output filename is trajec\_float. 
    15811562 
    1582 Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}). 
    1583 There are 2 possibilities: 
    1584  
    1585 - 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. 
    15861565Here it is an example of specification to put in files description section: 
    15871566 
     
    16001579\end{xmllines} 
    16011580 
    1602  -  if (\key{iomput}) is not used, a file called \ifile{trajec\_float} will be created by IOIPSL library. 
    1603  
    1604  See also \href{http://stockage.univ-brest.fr/~grima/Ariane/}{here} the web site describing the off-line use of 
    1605  this marvellous diagnostic tool. 
    1606  
    1607 % ------------------------------------------------------------------------------------------------------------- 
    1608 %       Harmonic analysis of tidal constituents 
    1609 % ------------------------------------------------------------------------------------------------------------- 
    1610 \section[Harmonic analysis of tidal constituents (\texttt{\textbf{key\_diaharm}})] 
    1611 {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})} 
    16121583\label{sec:DIA_diag_harm} 
    16131584 
    1614 %------------------------------------------namdia_harm---------------------------------------------------- 
    1615 % 
    1616 \nlst{nam_diaharm} 
    1617 %---------------------------------------------------------------------------------------------------------- 
     1585\begin{listing} 
     1586  \nlst{nam_diaharm} 
     1587  \caption{\forcode{&nam_diaharm}} 
     1588  \label{lst:nam_diaharm} 
     1589\end{listing} 
    16181590 
    16191591A module is available to compute the amplitude and phase of tidal waves. 
    16201592This on-line Harmonic analysis is actived with \key{diaharm}. 
    16211593 
    1622 Some parameters are available in namelist \ngn{namdia\_harm}: 
    1623  
    1624  - \np{nit000\_han} is the first time step used for harmonic analysis 
    1625  
    1626  - \np{nitend\_han} is the  last time step used for harmonic analysis 
    1627  
    1628  - \np{nstep\_han}  is the  time step frequency for harmonic analysis 
    1629  
    1630  - \np{nb\_ana}     is the number of harmonics to analyse 
    1631  
    1632  - \np{tname}       is an array with names of tidal constituents to analyse 
    1633  
    1634  \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. 
    16351607 The restart capability is not implemented. 
    16361608 
     
    16531625We obtain in output $C_{j}$ and $S_{j}$ for each tidal wave. 
    16541626 
    1655 % ------------------------------------------------------------------------------------------------------------- 
    1656 %       Sections transports 
    1657 % ------------------------------------------------------------------------------------------------------------- 
    1658 \section[Transports across sections (\texttt{\textbf{key\_diadct}})] 
    1659 {Transports across sections (\protect\key{diadct})} 
     1627%% ================================================================================================= 
     1628\section[Transports across sections (\texttt{\textbf{key\_diadct}})]{Transports across sections (\protect\key{diadct})} 
    16601629\label{sec:DIA_diag_dct} 
    16611630 
    1662 %------------------------------------------namdct---------------------------------------------------- 
    1663  
    1664 \nlst{namdct} 
    1665 %------------------------------------------------------------------------------------------------------------- 
     1631\begin{listing} 
     1632  \nlst{nam_diadct} 
     1633  \caption{\forcode{&nam_diadct}} 
     1634  \label{lst:nam_diadct} 
     1635\end{listing} 
    16661636 
    16671637A module is available to compute the transport of volume, heat and salt through sections. 
     
    16691639 
    16701640Each section is defined by the coordinates of its 2 extremities. 
    1671 The pathways between them are contructed using tools which can be found in \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT} 
    1672 and are written in a binary file \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is later read in by 
    1673 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. 
    16741644 
    16751645The on-line transports module creates three output ascii files: 
     
    16811651- \texttt{salt\_transport}   for   salt transports (unit: $10^{9}Kg s^{-1}$) \\ 
    16821652 
    1683 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 
    16841654they are averaged, as well as the level of output for debugging: 
    1685 \np{nn\_dct}   : frequency of instantaneous transports computing 
    1686 \np{nn\_dctwri}: frequency of writing ( mean of instantaneous transports ) 
    1687 \np{nn\_debug} : debugging of the section 
    1688  
     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%% ================================================================================================= 
    16891660\subsubsection{Creating a binary file containing the pathway of each section} 
    16901661 
    1691 In \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT/run}, 
     1662In \texttt{tools/SECTIONS\_DIADCT/run}, 
    16921663the file \textit{ {list\_sections.ascii\_global}} contains a list of all the sections that are to be computed 
    16931664(this list of sections is based on MERSEA project metrics). 
     
    16961667 
    16971668Each section is defined by: \\ 
    1698 \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}} \\ 
    16991670with: 
    17001671 
     
    17031674 - \texttt{long2 lat2}, coordinates of the second extremity of the section; 
    17041675 
    1705  - \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); 
    17061677 
    17071678 - \texttt{okstrpond} to compute    heat and       salt transports, \texttt{nostrpond} if no; 
     
    17131684 
    17141685\noindent If nclass $\neq$ 0, the next lines contain the class type and the nclass bounds: \\ 
    1715 {\scriptsize 
     1686{ 
    17161687  \texttt{ 
    17171688    long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name \\ 
     
    17361707 
    17371708 - \texttt{zsigp} for potential density classes \\ 
    1738    
     1709 
    17391710 The script \texttt{job.ksh} computes the pathway for each section and creates a binary file 
    1740  \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is read by NEMO. \\ 
     1711 \texttt{section\_ijglobal.diadct} which is read by \NEMO. \\ 
    17411712 
    17421713 It is possible to use this tools for new configuations: \texttt{job.ksh} has to be updated with 
     
    17461717 and the ATL\_Cuba\_Florida with 4 temperature clases (5 class bounds), are shown: \\ 
    17471718 \noindent 
    1748  {\scriptsize 
     1719 { 
    17491720   \texttt{ 
    17501721     -68.    -54.5   -60.    -64.7  00 okstrpond noice ACC\_Drake\_Passage \\ 
     
    17581729 } 
    17591730 
     1731%% ================================================================================================= 
    17601732\subsubsection{To read the output files} 
    17611733 
    17621734The output format is: \\ 
    1763 {\scriptsize 
     1735{ 
    17641736  \texttt{ 
    17651737    date, time-step number, section number,                \\ 
     
    17831755 
    17841756\begin{table} 
    1785   \scriptsize 
    17861757  \begin{tabular}{|l|l|l|l|l|} 
    17871758    \hline 
     
    17971768\end{table} 
    17981769 
    1799 % ================================================================ 
    1800 % Steric effect in sea surface height 
    1801 % ================================================================ 
     1770%% ================================================================================================= 
    18021771\section{Diagnosing the steric effect in sea surface height} 
    18031772\label{sec:DIA_steric} 
    1804  
    18051773 
    18061774Changes in steric sea level are caused when changes in the density of the water column imply an expansion or 
     
    18241792 
    18251793Let denote 
    1826 $\mathcal{M}$ the total mass    of liquid seawater ($\mathcal{M} = \int_D \rho dv$),  
    1827 $\mathcal{V}$ the total volume  of        seawater      ($\mathcal{V} = \int_D dv$),  
    1828 $\mathcal{A}$ the total surface of       the ocean      ($\mathcal{A} = \int_S ds$),  
    1829 $\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 
    18301798($\bar{\rho} = 1/\mathcal{V} \int_D \rho \,dv$), and 
    1831 $\bar{\eta}$ the global mean sea level  
     1799$\bar{\eta}$ the global mean sea level 
    18321800($\bar{\eta} = 1/\mathcal{A} \int_S \eta \,ds$). 
    18331801 
     
    18391807    \mathcal{V} &=  \mathcal{A}  \;\bar{\eta} 
    18401808  \end{split} 
    1841   \label{eq:MV_nBq} 
     1809  \label{eq:DIA_MV_nBq} 
    18421810\end{equation} 
    18431811 
     
    18471815  \frac{1}{e_3} \partial_t ( e_3\,\rho) + \nabla( \rho \, \textbf{U} ) 
    18481816  = \left. \frac{\textit{emp}}{e_3}\right|_\textit{surface} 
    1849   \label{eq:Co_nBq} 
     1817  \label{eq:DIA_Co_nBq} 
    18501818\end{equation} 
    18511819 
    18521820where $\rho$ is the \textit{in situ} density, and \textit{emp} the surface mass exchanges with the other media of 
    18531821the Earth system (atmosphere, sea-ice, land). 
    1854 Its global averaged leads to the total mass change  
     1822Its global averaged leads to the total mass change 
    18551823 
    18561824\begin{equation} 
    18571825  \partial_t \mathcal{M} = \mathcal{A} \;\overline{\textit{emp}} 
    1858   \label{eq:Mass_nBq} 
     1826  \label{eq:DIA_Mass_nBq} 
    18591827\end{equation} 
    18601828 
    18611829where $\overline{\textit{emp}} = \int_S \textit{emp}\,ds$ is the net mass flux through the ocean surface. 
    1862 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 
    18631831the evolution equation of the mean sea level 
    18641832 
     
    18661834  \partial_t \bar{\eta} = \frac{\overline{\textit{emp}}}{ \bar{\rho}} 
    18671835  - \frac{\mathcal{V}}{\mathcal{A}} \;\frac{\partial_t \bar{\rho} }{\bar{\rho}} 
    1868   \label{eq:ssh_nBq} 
     1836  \label{eq:DIA_ssh_nBq} 
    18691837\end{equation} 
    18701838 
    1871 The first term in equation \autoref{eq:ssh_nBq} alters sea level by adding or subtracting mass from the ocean.  
    1872 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. 
    18731841 
    18741842In a Boussinesq fluid, $\rho$ is replaced by $\rho_o$ in all the equation except when $\rho$ appears multiplied by 
    1875 the gravity (\ie in the hydrostatic balance of the primitive Equations). 
    1876 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: 
    18771845 
    18781846\[ 
    18791847  \frac{1}{e_3} \partial_t ( e_3 ) + \nabla( \textbf{U} ) = \left. \frac{\textit{emp}}{\rho_o \,e_3}\right|_ \textit{surface} 
    1880   % \label{eq:Co_Bq} 
     1848  % \label{eq:DIA_Co_Bq} 
    18811849\] 
    18821850 
     
    18851853\[ 
    18861854  \partial_t \mathcal{V} = \mathcal{A} \;\frac{\overline{\textit{emp}}}{\rho_o} 
    1887   % \label{eq:V_Bq} 
     1855  % \label{eq:DIA_V_Bq} 
    18881856\] 
    18891857 
     
    18941862 
    18951863Nevertheless, following \citep{greatbatch_JGR94}, the steric effect on the volume can be diagnosed by 
    1896 considering the mass budget of the ocean.  
     1864considering the mass budget of the ocean. 
    18971865The apparent changes in $\mathcal{M}$, mass of the ocean, which are not induced by surface mass flux 
    18981866must be compensated by a spatially uniform change in the mean sea level due to expansion/contraction of the ocean 
     
    19041872\begin{equation} 
    19051873  \mathcal{M}_o = \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A} 
    1906   \label{eq:M_Bq} 
     1874  \label{eq:DIA_M_Bq} 
    19071875\end{equation} 
    19081876 
     
    19101878is converted into a mean change in sea level. 
    19111879Introducing the total density anomaly, $\mathcal{D}= \int_D d_a \,dv$, 
    1912 where $d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO (cf. \autoref{subsec:TRA_eos}) 
    1913 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: 
    19141882 
    19151883\begin{equation} 
    19161884  \eta_s = - \frac{1}{\mathcal{A}} \mathcal{D} 
    1917   \label{eq:steric_Bq} 
     1885  \label{eq:DIA_steric_Bq} 
    19181886\end{equation} 
    19191887 
    19201888The above formulation of the steric height of a Boussinesq ocean requires four remarks. 
    19211889First, one can be tempted to define $\rho_o$ as the initial value of $\mathcal{M}/\mathcal{V}$, 
    1922 \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. 
    19231891We do not recommend that. 
    19241892Indeed, in this case $\rho_o$ depends on the initial state of the ocean. 
     
    19341902does not change when the sea level is changing as it is the case in all global ocean GCMs 
    19351903(wetting and drying of grid point is not allowed). 
    1936    
    1937 Third, the discretisation of \autoref{eq:steric_Bq} depends on the type of free surface which is considered. 
    1938 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 
    19391907 
    19401908\[ 
    19411909  \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} } 
    1942   % \label{eq:discrete_steric_Bq_nfs} 
     1910  % \label{eq:DIA_discrete_steric_Bq_nfs} 
    19431911\] 
    19441912 
     
    19501918  \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 } 
    19511919                  { \sum_{i,\,j,\,k}       e_{1t}e_{2t}e_{3t} + \sum_{i,\,j}       e_{1t}e_{2t} \eta } 
    1952   % \label{eq:discrete_steric_Bq_fs} 
     1920  % \label{eq:DIA_discrete_steric_Bq_fs} 
    19531921\] 
    19541922 
     
    19591927so that there are no associated ocean currents. 
    19601928Hence, the dynamically relevant sea level is the effective sea level, 
    1961 \ie the sea level as if sea ice (and snow) were converted to liquid seawater \citep{campin.marshall.ea_OM08}. 
    1962 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 
    19631931ice and ocean. 
    19641932Therefore the model effective sea level is always given by $\eta + \eta_s$, whether or not there is sea ice present. 
     
    19701938\[ 
    19711939  \eta_s = - \frac{1}{\mathcal{A}} \int_D d_a(T,S_o,p_o) \,dv 
    1972   % \label{eq:thermosteric_Bq} 
     1940  % \label{eq:DIA_thermosteric_Bq} 
    19731941\] 
    19741942 
    19751943where $S_o$ and $p_o$ are the initial salinity and pressure, respectively. 
    19761944 
    1977 Both steric and thermosteric sea level are computed in \mdl{diaar5} which needs the \key{diaar5} defined to 
    1978 be called. 
    1979  
    1980 % ------------------------------------------------------------------------------------------------------------- 
    1981 %       Other Diagnostics 
    1982 % ------------------------------------------------------------------------------------------------------------- 
    1983 \section[Other diagnostics (\texttt{\textbf{key\_diahth}}, \texttt{\textbf{key\_diaar5}})] 
    1984 {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} 
    19851949\label{sec:DIA_diag_others} 
    19861950 
     
    19881952The available ready-to-add diagnostics modules can be found in directory DIA. 
    19891953 
    1990 \subsection[Depth of various quantities (\textit{diahth.F90})] 
    1991 {Depth of various quantities (\protect\mdl{diahth})} 
     1954%% ================================================================================================= 
     1955\subsection[Depth of various quantities (\textit{diahth.F90})]{Depth of various quantities (\protect\mdl{diahth})} 
    19921956 
    19931957Among the available diagnostics the following ones are obtained when defining the \key{diahth} CPP key: 
     
    20011965- the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth}) 
    20021966 
    2003 % ----------------------------------------------------------- 
    2004 %     Poleward heat and salt transports 
    2005 % ----------------------------------------------------------- 
    2006  
    2007 \subsection[Poleward heat and salt transports (\textit{diaptr.F90})] 
    2008 {Poleward heat and salt transports (\protect\mdl{diaptr})} 
    2009  
    2010 %------------------------------------------namptr----------------------------------------- 
    2011  
    2012 \nlst{namptr}  
    2013 %----------------------------------------------------------------------------------------- 
    2014  
    2015 The poleward heat and salt transports, their advective and diffusive component, 
    2016 and the meriodional stream function can be computed on-line in \mdl{diaptr} \np{ln\_diaptr} to true 
    2017 (see the \textit{\ngn{namptr} } namelist below). 
    2018 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, 
    20191999Pacific and Indo-Pacific Oceans (defined north of 30\deg{S}) as well as for the World Ocean. 
    20202000The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains three 2D mask arrays, 
    2021 the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:mask_subasins}). 
    2022  
    2023 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    2024 \begin{figure}[!t] 
    2025   \begin{center} 
    2026     \includegraphics[width=\textwidth]{Fig_mask_subasins} 
    2027     \caption{ 
    2028       \protect\label{fig:mask_subasins} 
    2029       Decomposition of the World Ocean (here ORCA2) into sub-basin used in to 
    2030       compute the heat and salt transports as well as the meridional stream-function: 
    2031       Atlantic basin (red), Pacific basin (green), Indian basin (bleue), Indo-Pacific basin (bleue+green). 
    2032       Note that semi-enclosed seas (Red, Med and Baltic seas) as well as Hudson Bay are removed from the sub-basins. 
    2033       Note also that the Arctic Ocean has been split into Atlantic and Pacific basins along the North fold line. 
    2034     } 
    2035   \end{center} 
    2036 \end{figure}   
    2037 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    2038  
    2039 % ----------------------------------------------------------- 
    2040 %       CMIP specific diagnostics  
    2041 % ----------------------------------------------------------- 
    2042 \subsection[CMIP specific diagnostics (\textit{diaar5.F90})] 
    2043 {CMIP specific diagnostics (\protect\mdl{diaar5})} 
    2044  
    2045 A series of diagnostics has been added in the \mdl{diaar5}. 
    2046 They corresponds to outputs that are required for AR5 simulations (CMIP5) 
    2047 (see also \autoref{sec:DIA_steric} for one of them). 
    2048 Activating those outputs requires to define the \key{diaar5} CPP key. 
    2049  
    2050 % ----------------------------------------------------------- 
    2051 %       25 hour mean and hourly Surface, Mid and Bed  
    2052 % ----------------------------------------------------------- 
     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%% ================================================================================================= 
    20532010\subsection{25 hour mean output for tidal models} 
    20542011 
    2055 %------------------------------------------nam_dia25h------------------------------------- 
    2056  
    2057 \nlst{nam_dia25h} 
    2058 %----------------------------------------------------------------------------------------- 
     2012\begin{listing} 
     2013  \nlst{nam_dia25h} 
     2014  \caption{\forcode{&nam_dia25h}} 
     2015  \label{lst:nam_dia25h} 
     2016\end{listing} 
    20592017 
    20602018A module is available to compute a crudely detided M2 signal by obtaining a 25 hour mean. 
     
    20632021This diagnostic is actived with the logical $ln\_dia25h$. 
    20642022 
    2065 % ----------------------------------------------------------- 
    2066 %     Top Middle and Bed hourly output 
    2067 % ----------------------------------------------------------- 
     2023%% ================================================================================================= 
    20682024\subsection{Top middle and bed hourly output} 
    20692025 
    2070 %------------------------------------------nam_diatmb----------------------------------------------------- 
    2071  
    2072 \nlst{nam_diatmb} 
    2073 %---------------------------------------------------------------------------------------------------------- 
     2026\begin{listing} 
     2027  \nlst{nam_diatmb} 
     2028  \caption{\forcode{&nam_diatmb}} 
     2029  \label{lst:nam_diatmb} 
     2030\end{listing} 
    20742031 
    20752032A module is available to output the surface (top), mid water and bed diagnostics of a set of standard variables. 
     
    20792036This diagnostic is actived with the logical $ln\_diatmb$. 
    20802037 
    2081 % ----------------------------------------------------------- 
    2082 %     Courant numbers 
    2083 % ----------------------------------------------------------- 
     2038%% ================================================================================================= 
    20842039\subsection{Courant numbers} 
    20852040 
     
    20892044\[ 
    20902045  C_u = |u|\frac{\rdt}{e_{1u}}, \quad C_v = |v|\frac{\rdt}{e_{2v}}, \quad C_w = |w|\frac{\rdt}{e_{3w}} 
    2091   % \label{eq:CFL} 
     2046  % \label{eq:DIA_CFL} 
    20922047\] 
    20932048 
     
    20982053Values greater than 1 indicate that information is propagated across more than one grid cell in a single time step. 
    20992054 
    2100 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. 
    21012056The diagnostics will be written out to an ascii file named cfl\_diagnostics.ascii. 
    21022057In this file the maximum value of $C_u$, $C_v$, and $C_w$ are printed at each timestep along with the coordinates of 
     
    21042059At 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 
    21052060with the coordinates of each. 
    2106 The maximum values from the run are also copied to the ocean.output file.  
    2107  
    2108 % ================================================================ 
    2109  
    2110 \biblio 
    2111  
    2112 \pindex 
     2061The maximum values from the run are also copied to the ocean.output file. 
     2062 
     2063\subinc{\input{../../global/epilogue}} 
    21132064 
    21142065\end{document} 
  • NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_DIU.tex

    r11151 r12149  
    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 
    3542($\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 
    6271The warm layer is calculated using the model of \citet{takaya.bidlot.ea_JGR10} (TAKAYA10 model hereafter). 
     
    6574\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} 
    7079where $\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. 
    71 In equation (\autoref{eq:ecmwf1}) $\alpha_w=2\times10^{-4}$ is the thermal expansion coefficient of water, 
     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. 
     
    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\[ 
    8493  Q = Q_{\mathrm{sol}} + Q_{\mathrm{lw}} + Q_{\mathrm{h}}\mbox{,} 
    85   % \label{eq:e_flux_eqn} 
     94  % \label{eq:DIU_e_flux_eqn} 
    8695\] 
    8796where $Q_{\mathrm{h}}$ is the sensible and latent heat flux, $Q_{\mathrm{lw}}$ is the long wave flux, 
    8897and $Q_{\mathrm{sol}}$ is the solar flux absorbed within the diurnal warm layer. 
    8998For $Q_{\mathrm{sol}}$ the 9 term representation of \citet{gentemann.minnett.ea_JGR09} is used. 
    90 In equation \autoref{eq:ecmwf1} the function $f(L_a)=\max(1,L_a^{\frac{2}{3}})$, 
     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 %=============================================================== 
    114  
     122%% ================================================================================================= 
    115123\section{Cool skin model} 
    116 \label{sec:cool_skin_sec} 
    117  
    118 %=============================================================== 
     124\label{sec:DIU_cool_skin_sec} 
    119125 
    120126The 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}$. 
    121127As 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} 
     129  % \label{eq:DIU_sunders_eqn} 
    124130  \Delta T_{\mathrm{cs}}=\frac{Q_{\mathrm{ns}}\delta}{k_t} \mbox{,} 
    125131\] 
     
    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} 
     
    134140\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.iudicone.ea_JGR02}, 
     142The value of $\lambda$ used in equation (\autoref{eq:DIU_sunders_thick_eqn}) is that of \citet{artale.iudicone.ea_JGR02}, 
    137143which 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/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_DOM.tex

    r11179 r12149  
    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[width=\textwidth]{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[width=\textwidth]{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[width=\textwidth]{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 (\textit{domhgr.F90})] 
    348 {Horizontal grid mesh (\protect\mdl{domhgr})} 
    349 \label{sec:DOM_hgr} 
    350  
    351 % ------------------------------------------------------------------------------------------------------------- 
    352 %        Coordinates and scale factors  
    353 % ------------------------------------------------------------------------------------------------------------- 
    354 \subsection{Coordinates and scale factors} 
    355 \label{subsec:DOM_hgr_coord_e} 
    356  
    357 The ocean mesh (\ie the position of all the scalar and vector points) is defined by 
    358 the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 
    359 The grid-points are located at integer or integer and a half values of as indicated in \autoref{tab:cell}. 
    360 The associated scale factors are defined using the analytical first derivative of the transformation 
    361 \autoref{eq:scale_factors}. 
    362 These definitions are done in two modules, \mdl{domhgr} and \mdl{domzgr}, 
    363 which provide the horizontal and vertical meshes, respectively. 
    364 This section deals with the horizontal mesh parameters. 
    365  
    366 In a horizontal plane, the location of all the model grid points is defined from 
    367 the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$. 
    368 The horizontal scale factors are calculated using \autoref{eq:scale_factors}. 
    369 For example, when the longitude and latitude are function of a single value 
    370 ($i$ and $j$, respectively) (geographical configuration of the mesh), 
    371 the horizontal mesh definition reduces to define the wanted $\lambda(i)$, $\varphi(j)$, 
    372 and their derivatives $\lambda'(i) \ \varphi'(j)$ in the \mdl{domhgr} module. 
    373 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: 
    374597\begin{align*} 
    375    \lambda_t &\equiv \text{glamt} =      \lambda (i      ) 
    376   &\varphi_t &\equiv \text{gphit} =      \varphi (j      ) \\ 
    377    \lambda_u &\equiv \text{glamu} =      \lambda (i + 1/2) 
    378   &\varphi_u &\equiv \text{gphiu} =      \varphi (j      ) \\ 
    379    \lambda_v &\equiv \text{glamv} =      \lambda (i      ) 
    380   &\varphi_v &\equiv \text{gphiv} =      \varphi (j + 1/2) \\ 
    381    \lambda_f &\equiv \text{glamf} =      \lambda (i + 1/2) 
    382   &\varphi_f &\equiv \text{gphif} =      \varphi (j + 1/2) \\ 
    383    e_{1t}    &\equiv \text{e1t}   = r_a |\lambda'(i      ) \; \cos\varphi(j      ) | 
    384   &e_{2t}    &\equiv \text{e2t}   = r_a |\varphi'(j      )                         | \\ 
    385    e_{1u}    &\equiv \text{e1t}   = r_a |\lambda'(i + 1/2) \; \cos\varphi(j      ) | 
    386   &e_{2u}    &\equiv \text{e2t}   = r_a |\varphi'(j      )                         | \\ 
    387    e_{1v}    &\equiv \text{e1t}   = r_a |\lambda'(i      ) \; \cos\varphi(j + 1/2) | 
    388   &e_{2v}    &\equiv \text{e2t}   = r_a |\varphi'(j + 1/2)                         | \\ 
    389    e_{1f}    &\equiv \text{e1t}   = r_a |\lambda'(i + 1/2) \; \cos\varphi(j + 1/2) | 
    390   &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) 
    391609\end{align*} 
    392 where the last letter of each computational name indicates the grid point considered and 
    393 $r_a$ is the earth radius (defined in \mdl{phycst} along with all universal constants). 
    394 Note that the horizontal position of and scale factors at $w$-points are exactly equal to those of $t$-points, 
    395 thus no specific arrays are defined at $w$-points. 
    396  
    397 Note that the definition of the scale factors 
    398 (\ie as the analytical first derivative of the transformation that 
    399 gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$) 
    400 is specific to the \NEMO model \citep{marti.madec.ea_JGR92}. 
    401 As an example, $e_{1t}$ is defined locally at a $t$-point, 
    402 whereas many other models on a C grid choose to define such a scale factor as 
    403 the distance between the $U$-points on each side of the $t$-point. 
    404 Relying on an analytical transformation has two advantages: 
    405 firstly, there is no ambiguity in the scale factors appearing in the discrete equations, 
    406 since they are first introduced in the continuous equations; 
    407 secondly, analytical transformations encourage good practice by the definition of smoothly varying grids 
    408 (rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{treguier.dukowicz.ea_JGR96}. 
    409 An example of the effect of such a choice is shown in \autoref{fig:zgr_e3}. 
    410 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    411 \begin{figure}[!t] 
    412   \begin{center} 
    413     \includegraphics[width=\textwidth]{Fig_zgr_e3} 
    414     \caption{ 
    415       \protect\label{fig:zgr_e3} 
    416       Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical, 
    417       and (b) analytically derived grid-point position and scale factors. 
    418       For both grids here, the same $w$-point depth has been chosen but 
    419       in (a) the $t$-points are set half way between $w$-points while 
    420       in (b) they are defined from an analytical function: 
    421       $z(k) = 5 \, (k - 1/2)^3 - 45 \, (k - 1/2)^2 + 140 \, (k - 1/2) - 150$. 
    422       Note the resulting difference between the value of the grid-size $\Delta_k$ and 
    423       those of the scale factor $e_k$. 
    424     } 
    425   \end{center} 
    426 \end{figure} 
    427 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    428  
    429 % ------------------------------------------------------------------------------------------------------------- 
    430 %        Choice of horizontal grid 
    431 % ------------------------------------------------------------------------------------------------------------- 
    432 \subsection{Choice of horizontal grid} 
    433 \label{subsec:DOM_hgr_msh_choice} 
    434  
    435 % ------------------------------------------------------------------------------------------------------------- 
    436 %        Grid files 
    437 % ------------------------------------------------------------------------------------------------------------- 
    438 \subsection{Output grid files} 
    439 \label{subsec:DOM_hgr_files} 
    440  
    441 All the arrays relating to a particular ocean model configuration (grid-point position, scale factors, masks) 
    442 can be saved in files if \np{nn\_msh} $\not = 0$ (namelist variable in \ngn{namdom}). 
    443 This can be particularly useful for plots and off-line diagnostics. 
    444 In some cases, the user may choose to make a local modification of a scale factor in the code. 
    445 This is the case in global configurations when restricting the width of a specific strait 
    446 (usually a one-grid-point strait that happens to be too wide due to insufficient model resolution). 
    447 An example is Gibraltar Strait in the ORCA2 configuration. 
    448 When such modifications are done, 
    449 the output grid written when \np{nn\_msh} $\not = 0$ is no more equal to the input grid. 
    450  
    451 % ================================================================ 
    452 % Domain: Vertical Grid (domzgr) 
    453 % ================================================================ 
    454 \section[Vertical grid (\textit{domzgr.F90})] 
    455 {Vertical grid (\protect\mdl{domzgr})} 
    456 \label{sec:DOM_zgr} 
    457 %-----------------------------------------nam_zgr & namdom------------------------------------------- 
    458 % 
    459 %\nlst{namzgr}  
    460  
    461 \nlst{namdom}  
    462 %------------------------------------------------------------------------------------------------------------- 
    463  
    464 Variables are defined through the \ngn{namzgr} and \ngn{namdom} namelists. 
    465 In the vertical, the model mesh is determined by four things:  
    466 (1) the bathymetry given in meters;  
    467 (2) the number of levels of the model (\jp{jpk});  
    468 (3) the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and 
    469 (4) the masking system, \ie the number of wet model levels at each  
    470 $(i,j)$ column of points. 
    471  
    472 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    473 \begin{figure}[!tb] 
    474   \begin{center} 
    475     \includegraphics[width=\textwidth]{Fig_z_zps_s_sps} 
    476     \caption{ 
    477       \protect\label{fig:z_zps_s_sps} 
    478       The ocean bottom as seen by the model: 
    479       (a) $z$-coordinate with full step, 
    480       (b) $z$-coordinate with partial step, 
    481       (c) $s$-coordinate: terrain following representation, 
    482       (d) hybrid $s-z$ coordinate, 
    483       (e) hybrid $s-z$ coordinate with partial step, and 
    484       (f) same as (e) but in the non-linear free surface (\protect\np{ln\_linssh}\forcode{ = .false.}). 
    485       Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e). 
    486     } 
    487   \end{center} 
    488 \end{figure} 
    489 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    490  
    491 The choice of a vertical coordinate, even if it is made through \ngn{namzgr} namelist parameters,  
    492 must be done once of all at the beginning of an experiment. 
    493 It is not intended as an option which can be enabled or disabled in the middle of an experiment. 
    494 Three main choices are offered (\autoref{fig:z_zps_s_sps}): 
    495 $z$-coordinate with full step bathymetry (\np{ln\_zco}\forcode{ = .true.}), 
    496 $z$-coordinate with partial step bathymetry (\np{ln\_zps}\forcode{ = .true.}), 
    497 or generalized, $s$-coordinate (\np{ln\_sco}\forcode{ = .true.}). 
    498 Hybridation of the three main coordinates are available: 
    499 $s-z$ or $s-zps$ coordinate (\autoref{fig:z_zps_s_sps} and \autoref{fig:z_zps_s_sps}). 
    500 By default a non-linear free surface is used: the coordinate follow the time-variation of the free surface so that 
    501 the transformation is time dependent: $z(i,j,k,t)$ (\autoref{fig:z_zps_s_sps}). 
    502 When a linear free surface is assumed (\np{ln\_linssh}\forcode{ = .true.}), 
    503 the vertical coordinate are fixed in time, but the seawater can move up and down across the $z_0$ surface 
    504 (in other words, the top of the ocean in not a rigid-lid). 
    505 The last choice in terms of vertical coordinate concerns the presence (or not) in 
    506 the model domain of ocean cavities beneath ice shelves. 
    507 Setting \np{ln\_isfcav} to true allows to manage ocean cavities, otherwise they are filled in. 
    508 This option is currently only available in $z$- or $zps$-coordinate, 
    509 and partial step are also applied at the ocean/ice shelf interface. 
    510  
    511 Contrary to the horizontal grid, the vertical grid is computed in the code and no provision is made for 
    512 reading it from a file. 
    513 The only input file is the bathymetry (in meters) (\ifile{bathy\_meter}) 
    514 \footnote{ 
    515   N.B. in full step $z$-coordinate, a \ifile{bathy\_level} file can replace the \ifile{bathy\_meter} file, 
    516   so that the computation of the number of wet ocean point in each water column is by-passed}. 
    517 If \np{ln\_isfcav}\forcode{ = .true.}, an extra file input file (\ifile{isf\_draft\_meter}) describing 
    518 the ice shelf draft (in meters) is needed. 
    519  
    520 After reading the bathymetry, the algorithm for vertical grid definition differs between the different options: 
    521 \begin{description} 
    522 \item[\textit{zco}] 
    523   set a reference coordinate transformation $z_0(k)$, and set $z(i,j,k,t) = z_0(k)$. 
    524 \item[\textit{zps}] 
    525   set a reference coordinate transformation $z_0(k)$, and calculate the thickness of the deepest level at 
    526   each $(i,j)$ point using the bathymetry, to obtain the final three-dimensional depth and scale factor arrays. 
    527 \item[\textit{sco}] 
    528   smooth the bathymetry to fulfill the hydrostatic consistency criteria and 
    529   set the three-dimensional transformation. 
    530 \item[\textit{s-z} and \textit{s-zps}] 
    531   smooth the bathymetry to fulfill the hydrostatic consistency criteria and 
    532   set the three-dimensional transformation $z(i,j,k)$, 
    533   and possibly introduce masking of extra land points to better fit the original bathymetry file. 
    534 \end{description} 
    535 %%% 
    536 \gmcomment{   add the description of the smoothing:  envelop topography...} 
    537 %%% 
    538  
    539 Unless a linear free surface is used (\np{ln\_linssh}\forcode{ = .false.}), 
    540 the arrays describing the grid point depths and vertical scale factors are three set of 
    541 three dimensional arrays $(i,j,k)$ defined at \textit{before}, \textit{now} and \textit{after} time step. 
    542 The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively. 
    543 They are updated at each model time step using a fixed reference coordinate system which 
    544 computer names have a $\_0$ suffix. 
    545 When the linear free surface option is used (\np{ln\_linssh}\forcode{ = .true.}), \textit{before}, 
    546 \textit{now} and \textit{after} arrays are simply set one for all to their reference counterpart. 
    547  
    548 % ------------------------------------------------------------------------------------------------------------- 
    549 %        Meter Bathymetry 
    550 % ------------------------------------------------------------------------------------------------------------- 
    551 \subsection{Meter bathymetry} 
    552 \label{subsec:DOM_bathy} 
    553  
    554 Three options are possible for defining the bathymetry, according to the namelist variable \np{nn\_bathy} 
    555 (found in \ngn{namdom} namelist):  
    556 \begin{description} 
    557 \item[\np{nn\_bathy}\forcode{ = 0}]: 
    558   a flat-bottom domain is defined. 
    559   The total depth $z_w (jpk)$ is given by the coordinate transformation. 
    560   The domain can either be a closed basin or a periodic channel depending on the parameter \np{jperio}. 
    561 \item[\np{nn\_bathy}\forcode{ = -1}]: 
    562   a domain with a bump of topography one third of the domain width at the central latitude. 
    563   This is meant for the "EEL-R5" configuration, a periodic or open boundary channel with a seamount. 
    564 \item[\np{nn\_bathy}\forcode{ = 1}]: 
    565   read a bathymetry and ice shelf draft (if needed). 
    566   The \ifile{bathy\_meter} file (Netcdf format) provides the ocean depth (positive, in meters) at 
    567   each grid point of the model grid. 
    568   The bathymetry is usually built by interpolating a standard bathymetry product (\eg ETOPO2) onto 
    569   the horizontal ocean mesh. 
    570   Defining the bathymetry also defines the coastline: where the bathymetry is zero, 
    571   no model levels are defined (all levels are masked). 
    572  
    573   The \ifile{isfdraft\_meter} file (Netcdf format) provides the ice shelf draft (positive, in meters) at 
    574   each grid point of the model grid. 
    575   This file is only needed if \np{ln\_isfcav}\forcode{ = .true.}. 
    576   Defining the ice shelf draft will also define the ice shelf edge and the grounding line position. 
    577 \end{description} 
    578  
    579 When a global ocean is coupled to an atmospheric model it is better to represent all large water bodies 
    580 (\eg great lakes, Caspian sea...) even if the model resolution does not allow their communication with 
    581 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. 
    582632This is unnecessary when the ocean is forced by fixed atmospheric conditions, 
    583633so these seas can be removed from the ocean domain. 
    584 The user has the option to set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}), 
    585 but the code has to be adapted to the user's configuration. 
    586  
    587 % ------------------------------------------------------------------------------------------------------------- 
    588 %        z-coordinate  and reference coordinate transformation 
    589 % ------------------------------------------------------------------------------------------------------------- 
    590 \subsection[$Z$-coordinate (\forcode{ln_zco = .true.}) and ref. coordinate] 
    591 {$Z$-coordinate (\protect\np{ln\_zco}\forcode{ = .true.}) and reference coordinate} 
    592 \label{subsec:DOM_zco} 
    593  
    594 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    595 \begin{figure}[!tb] 
    596   \begin{center} 
    597     \includegraphics[width=\textwidth]{Fig_zgr} 
    598     \caption{ 
    599       \protect\label{fig:zgr} 
    600       Default vertical mesh for ORCA2: 30 ocean levels (L30). 
    601       Vertical level functions for (a) T-point depth and (b) the associated scale factor as computed from 
    602       \autoref{eq:DOM_zgr_ana_1} using \autoref{eq:DOM_zgr_coef} in $z$-coordinate. 
    603     } 
    604   \end{center} 
    605 \end{figure} 
    606 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    607  
    608 The reference coordinate transformation $z_0(k)$ defines the arrays $gdept_0$ and $gdepw_0$ for $t$- and $w$-points, 
    609 respectively. 
    610 As indicated on \autoref{fig:index_vert} \jp{jpk} is the number of $w$-levels. 
    611 $gdepw_0(1)$ is the ocean surface. 
    612 There are at most \jp{jpk}-1 $t$-points inside the ocean, 
    613 the additional $t$-point at $jk = jpk$ is below the sea floor and is not used. 
    614 The vertical location of $w$- and $t$-levels is defined from the analytic expression of the depth $z_0(k)$ whose 
    615 analytical derivative with respect to $k$ provides the vertical scale factors. 
    616 The user must provide the analytical expression of both $z_0$ and its first derivative with respect to $k$. 
    617 This is done in routine \mdl{domzgr} through statement functions, 
    618 using parameters provided in the \ngn{namcfg} namelist. 
    619  
    620 It is possible to define a simple regular vertical grid by giving zero stretching (\np{ppacr}\forcode{ = 0}). 
    621 In that case, the parameters \jp{jpk} (number of $w$-levels) and 
    622 \np{pphmax} (total ocean depth in meters) fully define the grid. 
    623  
    624 For climate-related studies it is often desirable to concentrate the vertical resolution near the ocean surface. 
    625 The following function is proposed as a standard for a $z$-coordinate (with either full or partial steps):  
    626 \begin{gather} 
    627   \label{eq:DOM_zgr_ana_1} 
    628     z_0  (k) = h_{sur} - h_0 \; k - \; h_1 \; \log  \big[ \cosh ((k - h_{th}) / h_{cr}) \big] \\ 
    629     e_3^0(k) = \lt|    - h_0      -    h_1 \; \tanh \big[        (k - h_{th}) / h_{cr}  \big] \rt| 
    630 \end{gather} 
    631 where $k = 1$ to \jp{jpk} for $w$-levels and $k = 1$ to $k = 1$ for $T-$levels. 
    632 Such an expression allows us to define a nearly uniform vertical location of levels at the ocean top and bottom with 
    633 a smooth hyperbolic tangent transition in between (\autoref{fig:zgr}). 
    634  
    635 If the ice shelf cavities are opened (\np{ln\_isfcav}\forcode{ = .true.}), the definition of $z_0$ is the same. 
    636 However, definition of $e_3^0$ at $t$- and $w$-points is respectively changed to: 
    637 \begin{equation} 
    638   \label{eq:DOM_zgr_ana_2} 
    639   \begin{split} 
    640     e_3^T(k) &= z_W (k + 1) - z_W (k    ) \\ 
    641     e_3^W(k) &= z_T (k    ) - z_T (k - 1) 
    642   \end{split} 
    643 \end{equation} 
    644 This formulation decrease the self-generated circulation into the ice shelf cavity  
    645 (which can, in extreme case, leads to blow up).\\ 
    646   
    647 The most used vertical grid for ORCA2 has $10~m$ ($500~m$) resolution in the surface (bottom) layers and 
    648 a depth which varies from 0 at the sea surface to a minimum of $-5000~m$. 
    649 This leads to the following conditions: 
    650 \begin{equation} 
    651   \label{eq:DOM_zgr_coef} 
    652   \begin{array}{ll} 
    653     e_3 (1   + 1/2) =  10. & z(1  ) =     0. \\ 
    654     e_3 (jpk - 1/2) = 500. & z(jpk) = -5000. 
    655   \end{array} 
    656 \end{equation} 
    657  
    658 With the choice of the stretching $h_{cr} = 3$ and the number of levels \jp{jpk}~$= 31$, 
    659 the four coefficients $h_{sur}$, $h_0$, $h_1$, and $h_{th}$ in 
    660 \autoref{eq:DOM_zgr_ana_2} have been determined such that 
    661 \autoref{eq:DOM_zgr_coef} is satisfied, through an optimisation procedure using a bisection method. 
    662 For the first standard ORCA2 vertical grid this led to the following values: 
    663 $h_{sur} = 4762.96$, $h_0 = 255.58, h_1 = 245.5813$, and $h_{th} = 21.43336$. 
    664 The resulting depths and scale factors as a function of the model levels are shown in 
    665 \autoref{fig:zgr} and given in \autoref{tab:orca_zgr}. 
    666 Those values correspond to the parameters \np{ppsur}, \np{ppa0}, \np{ppa1}, \np{ppkth} in \ngn{namcfg} namelist. 
    667  
    668 Rather than entering parameters $h_{sur}$, $h_0$, and $h_1$ directly, it is possible to recalculate them. 
    669 In that case the user sets \np{ppsur}~$=$~\np{ppa0}~$=$~\np{ppa1}~$= 999999$., 
    670 in \ngn{namcfg} namelist, and specifies instead the four following parameters: 
    671 \begin{itemize} 
    672 \item 
    673   \np{ppacr}~$= h_{cr}$: stretching factor (nondimensional). 
    674   The larger \np{ppacr}, the smaller the stretching. 
    675   Values from $3$ to $10$ are usual. 
    676 \item 
    677   \np{ppkth}~$= h_{th}$: is approximately the model level at which maximum stretching occurs 
    678   (nondimensional, usually of order 1/2 or 2/3 of \jp{jpk}) 
    679 \item 
    680   \np{ppdzmin}: minimum thickness for the top layer (in meters). 
    681 \item 
    682   \np{pphmax}: total depth of the ocean (meters). 
    683 \end{itemize} 
    684 As an example, for the $45$ layers used in the DRAKKAR configuration those parameters are: 
    685 \jp{jpk}~$= 46$, \np{ppacr}~$= 9$, \np{ppkth}~$= 23.563$, \np{ppdzmin}~$= 6~m$, \np{pphmax}~$= 5750~m$. 
    686  
    687 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    688 \begin{table} 
    689   \begin{center} 
    690     \begin{tabular}{c||r|r|r|r} 
    691       \hline 
    692       \textbf{LEVEL} & \textbf{gdept\_1d} & \textbf{gdepw\_1d} & \textbf{e3t\_1d } & \textbf{e3w\_1d} \\ 
    693       \hline 
    694       1              & \textbf{     5.00} &               0.00 & \textbf{   10.00} &            10.00 \\ 
    695       \hline 
    696       2              & \textbf{    15.00} &              10.00 & \textbf{   10.00} &            10.00 \\ 
    697       \hline 
    698       3              & \textbf{    25.00} &              20.00 & \textbf{   10.00} &            10.00 \\ 
    699       \hline 
    700       4              & \textbf{    35.01} &              30.00 & \textbf{   10.01} &            10.00 \\ 
    701       \hline 
    702       5              & \textbf{    45.01} &              40.01 & \textbf{   10.01} &            10.01 \\ 
    703       \hline 
    704       6              & \textbf{    55.03} &              50.02 & \textbf{   10.02} &            10.02 \\ 
    705       \hline 
    706       7              & \textbf{    65.06} &              60.04 & \textbf{   10.04} &            10.03 \\ 
    707       \hline 
    708       8              & \textbf{    75.13} &              70.09 & \textbf{   10.09} &            10.06 \\ 
    709       \hline 
    710       9              & \textbf{    85.25} &              80.18 & \textbf{   10.17} &            10.12 \\ 
    711       \hline 
    712       10             & \textbf{    95.49} &              90.35 & \textbf{   10.33} &            10.24 \\ 
    713       \hline 
    714       11             & \textbf{   105.97} &             100.69 & \textbf{   10.65} &            10.47 \\ 
    715       \hline 
    716       12             & \textbf{   116.90} &             111.36 & \textbf{   11.27} &            10.91 \\ 
    717       \hline 
    718       13             & \textbf{   128.70} &             122.65 & \textbf{   12.47} &            11.77 \\ 
    719       \hline 
    720       14             & \textbf{   142.20} &             135.16 & \textbf{   14.78} &            13.43 \\ 
    721       \hline 
    722       15             & \textbf{   158.96} &             150.03 & \textbf{   19.23} &            16.65 \\ 
    723       \hline 
    724       16             & \textbf{   181.96} &             169.42 & \textbf{   27.66} &            22.78 \\ 
    725       \hline 
    726       17             & \textbf{   216.65} &             197.37 & \textbf{   43.26} &            34.30 \\ 
    727       \hline 
    728       18             & \textbf{   272.48} &             241.13 & \textbf{   70.88} &            55.21 \\ 
    729       \hline 
    730       19             & \textbf{   364.30} &             312.74 & \textbf{  116.11} &            90.99 \\ 
    731       \hline 
    732       20             & \textbf{   511.53} &             429.72 & \textbf{  181.55} &           146.43 \\ 
    733       \hline 
    734       21             & \textbf{   732.20} &             611.89 & \textbf{  261.03} &           220.35 \\ 
    735       \hline 
    736       22             & \textbf{  1033.22} &             872.87 & \textbf{  339.39} &           301.42 \\ 
    737       \hline 
    738       23             & \textbf{  1405.70} &            1211.59 & \textbf{  402.26} &           373.31 \\ 
    739       \hline 
    740       24             & \textbf{  1830.89} &            1612.98 & \textbf{  444.87} &           426.00 \\ 
    741       \hline 
    742       25             & \textbf{  2289.77} &            2057.13 & \textbf{  470.55} &           459.47 \\ 
    743       \hline 
    744       26             & \textbf{  2768.24} &            2527.22 & \textbf{  484.95} &           478.83 \\ 
    745       \hline 
    746       27             & \textbf{  3257.48} &            3011.90 & \textbf{  492.70} &           489.44 \\ 
    747       \hline 
    748       28             & \textbf{  3752.44} &            3504.46 & \textbf{  496.78} &           495.07 \\ 
    749       \hline 
    750       29             & \textbf{  4250.40} &            4001.16 & \textbf{  498.90} &           498.02 \\ 
    751       \hline 
    752       30             & \textbf{  4749.91} &            4500.02 & \textbf{  500.00} &           499.54 \\ 
    753       \hline 
    754       31             & \textbf{  5250.23} &            5000.00 & \textbf{  500.56} &           500.33 \\ 
    755       \hline 
    756     \end{tabular} 
    757   \end{center} 
    758   \caption{ 
    759     \protect\label{tab:orca_zgr} 
    760     Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration as computed from 
    761     \autoref{eq:DOM_zgr_ana_2} using the coefficients given in \autoref{eq:DOM_zgr_coef} 
    762   } 
    763 \end{table} 
    764 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    765  
    766 % ------------------------------------------------------------------------------------------------------------- 
    767 %        z-coordinate with partial step 
    768 % ------------------------------------------------------------------------------------------------------------- 
    769 \subsection[$Z$-coordinate with partial step (\forcode{ln_zps = .true.})] 
    770 {$Z$-coordinate with partial step (\protect\np{ln\_zps}\forcode{ = .true.})} 
    771 \label{subsec:DOM_zps} 
    772 %--------------------------------------------namdom------------------------------------------------------- 
    773  
    774 \nlst{namdom}  
    775 %-------------------------------------------------------------------------------------------------------------- 
    776  
    777 In $z$-coordinate partial step, 
    778 the depths of the model levels are defined by the reference analytical function $z_0(k)$ as described in 
    779 the previous section, \textit{except} in the bottom layer. 
    780 The thickness of the bottom layer is allowed to vary as a function of geographical location $(\lambda,\varphi)$ to 
    781 allow a better representation of the bathymetry, especially in the case of small slopes 
    782 (where the bathymetry varies by less than one level thickness from one grid point to the next). 
    783 The reference layer thicknesses $e_{3t}^0$ have been defined in the absence of bathymetry. 
    784 With partial steps, layers from 1 to \jp{jpk}-2 can have a thickness smaller than $e_{3t}(jk)$. 
    785 The model deepest layer (\jp{jpk}-1) is allowed to have either a smaller or larger thickness than $e_{3t}(jpk)$: 
    786 the maximum thickness allowed is $2*e_{3t}(jpk - 1)$. 
    787 This has to be kept in mind when specifying values in \ngn{namdom} namelist, 
    788 as the maximum depth \np{pphmax} in partial steps: 
    789 for example, with \np{pphmax}~$= 5750~m$ for the DRAKKAR 45 layer grid, 
    790 the maximum ocean depth allowed is actually $6000~m$ (the default thickness $e_{3t}(jpk - 1)$ being $250~m$). 
    791 Two variables in the namdom namelist are used to define the partial step vertical grid. 
    792 The mimimum water thickness (in meters) allowed for a cell partially filled with bathymetry at level jk is 
    793 the minimum of \np{rn\_e3zps\_min} (thickness in meters, usually $20~m$) or $e_{3t}(jk)*$\np{rn\_e3zps\_rat} 
    794 (a fraction, usually 10\%, of the default thickness $e_{3t}(jk)$). 
    795  
    796 \gmcomment{ \colorbox{yellow}{Add a figure here of pstep especially at last ocean level }  } 
    797  
    798 % ------------------------------------------------------------------------------------------------------------- 
    799 %        s-coordinate 
    800 % ------------------------------------------------------------------------------------------------------------- 
    801 \subsection[$S$-coordinate (\forcode{ln_sco = .true.})] 
    802 {$S$-coordinate (\protect\np{ln\_sco}\forcode{ = .true.})} 
    803 \label{subsec:DOM_sco} 
    804 %------------------------------------------nam_zgr_sco--------------------------------------------------- 
    805 % 
    806 %\nlst{namzgr_sco}  
    807 %-------------------------------------------------------------------------------------------------------------- 
    808 Options are defined in \ngn{namzgr\_sco}. 
    809 In $s$-coordinate (\np{ln\_sco}\forcode{ = .true.}), the depth and thickness of the model levels are defined from 
    810 the product of a depth field and either a stretching function or its derivative, respectively: 
    811  
    812 \begin{align*} 
    813   % \label{eq:DOM_sco_ana} 
    814   z(k)   &= h(i,j) \; z_0 (k) \\ 
    815   e_3(k) &= h(i,j) \; z_0'(k) 
    816 \end{align*} 
    817  
    818 where $h$ is the depth of the last $w$-level ($z_0(k)$) defined at the $t$-point location in the horizontal and 
    819 $z_0(k)$ is a function which varies from $0$ at the sea surface to $1$ at the ocean bottom. 
    820 The depth field $h$ is not necessary the ocean depth, 
    821 since a mixed step-like and bottom-following representation of the topography can be used 
    822 (\autoref{fig:z_zps_s_sps}) or an envelop bathymetry can be defined (\autoref{fig:z_zps_s_sps}). 
    823 The namelist parameter \np{rn\_rmax} determines the slope at which 
    824 the terrain-following coordinate intersects the sea bed and becomes a pseudo z-coordinate. 
    825 The coordinate can also be hybridised by specifying \np{rn\_sbot\_min} and \np{rn\_sbot\_max} as 
    826 the minimum and maximum depths at which the terrain-following vertical coordinate is calculated. 
    827  
    828 Options for stretching the coordinate are provided as examples, 
    829 but care must be taken to ensure that the vertical stretch used is appropriate for the application. 
    830  
    831 The original default NEMO s-coordinate stretching is available if neither of the other options are specified as true 
    832 (\np{ln\_s\_SH94}\forcode{ = .false.} and \np{ln\_s\_SF12}\forcode{ = .false.}). 
    833 This uses a depth independent $\tanh$ function for the stretching \citep{madec.delecluse.ea_JPO96}: 
    834  
    835 \[ 
    836   z = s_{min} + C (s) (H - s_{min}) 
    837   % \label{eq:SH94_1} 
    838 \] 
    839  
    840 where $s_{min}$ is the depth at which the $s$-coordinate stretching starts and 
    841 allows a $z$-coordinate to placed on top of the stretched coordinate, 
    842 and $z$ is the depth (negative down from the asea surface). 
    843 \begin{gather*} 
    844   s = - \frac{k}{n - 1} \quad \text{and} \quad 0 \leq k \leq n - 1 
    845   % \label{eq:DOM_s} 
    846  \\ 
    847   % \label{eq:DOM_sco_function} 
    848   C(s) = \frac{[\tanh(\theta \, (s + b)) - \tanh(\theta \, b)]}{2 \; \sinh(\theta)} 
    849 \end{gather*} 
    850  
    851 A stretching function, 
    852 modified from the commonly used \citet{song.haidvogel_JCP94} stretching (\np{ln\_s\_SH94}\forcode{ = .true.}), 
    853 is also available and is more commonly used for shelf seas modelling: 
    854  
    855 \[ 
    856   C(s) =   (1 - b) \frac{\sinh(\theta s)}{\sinh(\theta)} 
    857          + b       \frac{\tanh \lt[ \theta \lt(s + \frac{1}{2} \rt) \rt] -   \tanh \lt( \frac{\theta}{2} \rt)} 
    858                         {                                                  2 \tanh \lt( \frac{\theta}{2} \rt)} 
    859   % \label{eq:SH94_2} 
    860 \] 
    861  
    862 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    863 \begin{figure}[!ht] 
    864   \begin{center} 
    865     \includegraphics[width=\textwidth]{Fig_sco_function} 
    866     \caption{ 
    867       \protect\label{fig:sco_function} 
    868       Examples of the stretching function applied to a seamount; 
    869       from left to right: surface, surface and bottom, and bottom intensified resolutions 
    870     } 
    871   \end{center} 
    872 \end{figure} 
    873 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    874  
    875 where $H_c$ is the critical depth (\np{rn\_hc}) at which the coordinate transitions from pure $\sigma$ to 
    876 the stretched coordinate, and $\theta$ (\np{rn\_theta}) and $b$ (\np{rn\_bb}) are the surface and 
    877 bottom control parameters such that $0 \leqslant \theta \leqslant 20$, and $0 \leqslant b \leqslant 1$. 
    878 $b$ has been designed to allow surface and/or bottom increase of the vertical resolution 
    879 (\autoref{fig:sco_function}). 
    880  
    881 Another example has been provided at version 3.5 (\np{ln\_s\_SF12}) that allows a fixed surface resolution in 
    882 an analytical terrain-following stretching \citet{siddorn.furner_OM13}. 
    883 In this case the a stretching function $\gamma$ is defined such that: 
    884  
    885 \begin{equation} 
    886   z = - \gamma h \quad \text{with} \quad 0 \leq \gamma \leq 1 
    887   % \label{eq:z} 
    888 \end{equation} 
    889  
    890 The function is defined with respect to $\sigma$, the unstretched terrain-following coordinate: 
    891  
    892 \begin{gather*} 
    893   % \label{eq:DOM_gamma_deriv} 
    894   \gamma =   A \lt( \sigma   - \frac{1}{2} (\sigma^2     + f (\sigma)) \rt) 
    895            + B \lt( \sigma^3 - f           (\sigma) \rt) + f (\sigma)       \\ 
    896   \intertext{Where:} 
    897   % \label{eq:DOM_gamma} 
    898   f(\sigma) = (\alpha + 2) \sigma^{\alpha + 1} - (\alpha + 1) \sigma^{\alpha + 2} 
    899   \quad \text{and} \quad \sigma = \frac{k}{n - 1} 
    900 \end{gather*} 
    901  
    902 This gives an analytical stretching of $\sigma$ that is solvable in $A$ and $B$ as a function of 
    903 the user prescribed stretching parameter $\alpha$ (\np{rn\_alpha}) that stretches towards 
    904 the surface ($\alpha > 1.0$) or the bottom ($\alpha < 1.0$) and 
    905 user prescribed surface (\np{rn\_zs}) and bottom depths. 
    906 The bottom cell depth in this example is given as a function of water depth: 
    907  
    908 \[ 
    909   % \label{eq:DOM_zb} 
    910   Z_b = h a + b 
    911 \] 
    912  
    913 where the namelist parameters \np{rn\_zb\_a} and \np{rn\_zb\_b} are $a$ and $b$ respectively. 
    914  
    915 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    916 \begin{figure}[!ht] 
    917   \includegraphics[width=\textwidth]{Fig_DOM_compare_coordinates_surface} 
    918   \caption{ 
    919     A comparison of the \citet{song.haidvogel_JCP94} $S$-coordinate (solid lines), 
    920     a 50 level $Z$-coordinate (contoured surfaces) and 
    921     the \citet{siddorn.furner_OM13} $S$-coordinate (dashed lines) in the surface $100~m$ for 
    922     a idealised bathymetry that goes from $50~m$ to $5500~m$ depth. 
    923     For clarity every third coordinate surface is shown. 
    924   } 
    925   \label{fig:fig_compare_coordinates_surface} 
    926 \end{figure} 
    927  % >>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    928  
    929 This gives a smooth analytical stretching in computational space that is constrained to 
    930 given specified surface and bottom grid cell thicknesses in real space. 
    931 This is not to be confused with the hybrid schemes that 
    932 superimpose geopotential coordinates on terrain following coordinates thus 
    933 creating a non-analytical vertical coordinate that 
    934 therefore may suffer from large gradients in the vertical resolutions. 
    935 This stretching is less straightforward to implement than the \citet{song.haidvogel_JCP94} stretching, 
    936 but has the advantage of resolving diurnal processes in deep water and has generally flatter slopes. 
    937  
    938 As with the \citet{song.haidvogel_JCP94} stretching the stretch is only applied at depths greater than 
    939 the critical depth $h_c$. 
    940 In this example two options are available in depths shallower than $h_c$, 
    941 with pure sigma being applied if the \np{ln\_sigcrit} is true and pure z-coordinates if it is false 
    942 (the z-coordinate being equal to the depths of the stretched coordinate at $h_c$). 
    943  
    944 Minimising the horizontal slope of the vertical coordinate is important in terrain-following systems as 
    945 large slopes lead to hydrostatic consistency. 
    946 A hydrostatic consistency parameter diagnostic following \citet{haney_JPO91} has been implemented, 
    947 and is output as part of the model mesh file at the start of the run. 
    948  
    949 % ------------------------------------------------------------------------------------------------------------- 
    950 %        z*- or s*-coordinate 
    951 % ------------------------------------------------------------------------------------------------------------- 
    952 \subsection[\zstar- or \sstar-coordinate (\forcode{ln_linssh = .false.})] 
    953 {\zstar- or \sstar-coordinate (\protect\np{ln\_linssh}\forcode{ = .false.})} 
    954 \label{subsec:DOM_zgr_star} 
    955  
    956 This option is described in the Report by Levier \textit{et al.} (2007), available on the \NEMO web site. 
    957  
    958 %gm% key advantage: minimise the diffusion/dispertion associated with advection in response to high frequency surface disturbances 
    959  
    960 % ------------------------------------------------------------------------------------------------------------- 
    961 %        level bathymetry and mask  
    962 % ------------------------------------------------------------------------------------------------------------- 
    963 \subsection{Level bathymetry and mask} 
    964 \label{subsec:DOM_msk} 
    965  
    966 Whatever the vertical coordinate used, the model offers the possibility of representing the bottom topography with 
    967 steps that follow the face of the model cells (step like topography) \citep{madec.delecluse.ea_JPO96}. 
    968 The distribution of the steps in the horizontal is defined in a 2D integer array, mbathy, which 
    969 gives the number of ocean levels (\ie those that are not masked) at each $t$-point. 
    970 mbathy is computed from the meter bathymetry using the definiton of gdept as the number of $t$-points which 
    971 gdept $\leq$ bathy. 
    972  
    973 Modifications of the model bathymetry are performed in the \textit{bat\_ctl} routine (see \mdl{domzgr} module) after 
    974 mbathy is computed. 
    975 Isolated grid points that do not communicate with another ocean point at the same level are eliminated. 
    976  
    977 As for the representation of bathymetry, a 2D integer array, misfdep, is created. 
    978 misfdep defines the level of the first wet $t$-point. 
    979 All the cells between $k = 1$ and $misfdep(i,j) - 1$ are masked. 
    980 By default, $misfdep(:,:) = 1$ and no cells are masked. 
    981  
    982 In case of ice shelf cavities, modifications of the model bathymetry and ice shelf draft into  
    983 the cavities are performed in the \textit{zgr\_isf} routine. 
    984 The compatibility between ice shelf draft and bathymetry is checked. 
    985 All the locations where the isf cavity is thinnest than \np{rn\_isfhmin} meters are grounded (\ie masked). 
    986 If only one cell on the water column is opened at $t$-, $u$- or $v$-points, 
    987 the bathymetry or the ice shelf draft is dug to fit this constrain. 
    988 If the incompatibility is too strong (need to dig more than 1 cell), the cell is masked. 
    989  
    990 From the \textit{mbathy} and \textit{misfdep} array, the mask fields are defined as follows: 
    991 \begin{alignat*}{2} 
    992   tmask(i,j,k) &= &  & 
    993     \begin{cases} 
    994                   0 &\text{if $                  k  <    misfdep(i,j)$} \\ 
    995                   1 &\text{if $misfdep(i,j) \leq k \leq   mbathy(i,j)$} \\ 
    996                   0 &\text{if $                  k  >     mbathy(i,j)$} 
    997     \end{cases} 
    998   \\ 
    999   umask(i,j,k) &= &  &tmask(i,j,k) * tmask(i + 1,j,    k) \\ 
    1000   vmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i    ,j + 1,k) \\ 
    1001   fmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i + 1,j,    k) \\ 
    1002                &  &* &tmask(i,j,k) * tmask(i + 1,j,    k) \\ 
    1003   wmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i    ,j,k - 1) \\ 
    1004   \text{with~} wmask(i,j,1) &= & &tmask(i,j,1) 
    1005 \end{alignat*} 
    1006  
    1007 Note that, without ice shelves cavities, 
    1008 masks at $t-$ and $w-$points are identical with the numerical indexing used (\autoref{subsec:DOM_Num_Index}). 
    1009 Nevertheless, $wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface)  
    1010 exactly in the same way as for the bottom boundary. 
    1011  
    1012 The specification of closed lateral boundaries requires that at least 
    1013 the first and last rows and columns of the \textit{mbathy} array are set to zero. 
    1014 In the particular case of an east-west cyclical boundary condition, \textit{mbathy} has its last column equal to 
    1015 the second one and its first column equal to the last but one (and so too the mask arrays) 
    1016 (see \autoref{fig:LBC_jperio}). 
    1017  
    1018 % ================================================================ 
    1019 % Domain: Initial State (dtatsd & istate) 
    1020 % ================================================================ 
    1021 \section[Initial state (\textit{istate.F90} and \textit{dtatsd.F90})] 
    1022 {Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})} 
    1023 \label{sec:DTA_tsd} 
    1024 %-----------------------------------------namtsd------------------------------------------- 
    1025  
    1026 \nlst{namtsd}  
    1027 %------------------------------------------------------------------------------------------ 
    1028  
    1029 Options are defined in \ngn{namtsd}. 
    1030 By default, the ocean start from rest (the velocity field is set to zero) and the initialization of temperature and 
    1031 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 
    1032682\begin{description} 
    1033 \item[\np{ln\_tsd\_init}\forcode{ = .true.}] 
    1034   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. 
    1035685  In the latter case, 
    1036686  the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid 
    1037687  (see \autoref{subsec:SBC_iof}). 
    1038   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. 
    1039690  The computation is done in the \mdl{dtatsd} module. 
    1040 \item[\np{ln\_tsd\_init}\forcode{ = .false.}] 
    1041   use constant salinity value of $35.5~psu$ and an analytical profile of temperature 
    1042   (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}). 
    1043695\end{description} 
    1044696 
    1045 \biblio 
    1046  
    1047 \pindex 
     697\subinc{\input{../../global/epilogue}} 
    1048698 
    1049699\end{document} 
  • NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_DYN.tex

    r11187 r12149  
    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 (\textit{divcur.F90})] 
    68 {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})} 
    6978\label{subsec:DYN_divcur} 
    7079 
    71 The vorticity is defined at an $f$-point (\ie corner point) as follows: 
    72 \begin{equation} 
    73   \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} 
    7483  \zeta =\frac{1}{e_{1f}\,e_{2f} }\left( {\;\delta_{i+1/2} \left[ {e_{2v}\;v} \right] 
    7584      -\delta_{j+1/2} \left[ {e_{1u}\;u} \right]\;} \right) 
    76 \end{equation}  
     85\end{equation} 
    7786 
    7887The horizontal divergence is defined at a $T$-point. 
    7988It is given by: 
    8089\[ 
    81   % \label{eq:divcur_div} 
     90  % \label{eq:DYN_divcur_div} 
    8291  \chi =\frac{1}{e_{1t}\,e_{2t}\,e_{3t} } 
    8392  \left( {\delta_i \left[ {e_{2u}\,e_{3u}\,u} \right] 
     
    97106ensure perfect restartability. 
    98107The vorticity and divergence at the \textit{now} time step are used for the computation of 
    99 the nonlinear advection and of the vertical velocity respectively.  
    100  
    101 %-------------------------------------------------------------------------------------------------------------- 
    102 %           Sea Surface Height evolution 
    103 %-------------------------------------------------------------------------------------------------------------- 
    104 \subsection[Horizontal divergence and relative vorticity (\textit{sshwzv.F90})] 
    105 {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})} 
    106112\label{subsec:DYN_sshwzv} 
    107113 
    108114The sea surface height is given by: 
    109115\begin{equation} 
    110   \label{eq:dynspg_ssh} 
     116  \label{eq:DYN_spg_ssh} 
    111117  \begin{aligned} 
    112118    \frac{\partial \eta }{\partial t} 
     
    117123  \end{aligned} 
    118124\end{equation} 
    119 where \textit{emp} is the surface freshwater budget (evaporation minus precipitation),  
     125where \textit{emp} is the surface freshwater budget (evaporation minus precipitation), 
    120126expressed in Kg/m$^2$/s (which is equal to mm/s), 
    121127and $\rho_w$=1,035~Kg/m$^3$ is the reference density of sea water (Boussinesq approximation). 
    122128If river runoff is expressed as a surface freshwater flux (see \autoref{chap:SBC}) then 
    123 \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. 
    124130The sea-surface height is evaluated using exactly the same time stepping scheme as 
    125 the tracer equation \autoref{eq:tra_nxt}: 
     131the tracer equation \autoref{eq:TRA_nxt}: 
    126132a leapfrog scheme in combination with an Asselin time filter, 
    127 \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). 
    128134This is of paramount importance. 
    129135Replacing $T$ by the number $1$ in the tracer equation and summing over the water column must lead to 
     
    134140taking into account the change of the thickness of the levels: 
    135141\begin{equation} 
    136   \label{eq:wzv} 
     142  \label{eq:DYN_wzv} 
    137143  \left\{ 
    138144    \begin{aligned} 
     
    144150\end{equation} 
    145151 
    146 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$, 
    147153as changes in the divergence of the barotropic transport are absorbed into the change of the level thicknesses, 
    148154re-orientated downward. 
    149 \gmcomment{not sure of this...  to be modified with the change in emp setting} 
    150 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. 
    151157The upper boundary condition applies at a fixed level $z=0$. 
    152158The top vertical velocity is thus equal to the divergence of the barotropic transport 
    153 (\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}). 
    154160 
    155161Note also that whereas the vertical velocity has the same discrete expression in $z$- and $s$-coordinates, 
    156162its physical meaning is not the same: 
    157163in the second case, $w$ is the velocity normal to the $s$-surfaces. 
    158 Note also that the $k$-axis is re-orientated downwards in the \fortran code compared to 
    159 the indexing used in the semi-discrete equations such as \autoref{eq:wzv} 
    160 (see \autoref{subsec:DOM_Num_Index_vertical}).  
    161  
    162  
    163 % ================================================================ 
    164 % Coriolis and Advection terms: vector invariant form 
    165 % ================================================================ 
     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%% ================================================================================================= 
    166169\section{Coriolis and advection: vector invariant form} 
    167170\label{sec:DYN_adv_cor_vect} 
    168 %-----------------------------------------nam_dynadv---------------------------------------------------- 
    169  
    170 \nlst{namdyn_adv}  
    171 %------------------------------------------------------------------------------------------------------------- 
     171 
     172\begin{listing} 
     173  \nlst{namdyn_adv} 
     174  \caption{\forcode{&namdyn_adv}} 
     175  \label{lst:namdyn_adv} 
     176\end{listing} 
    172177 
    173178The vector invariant form of the momentum equations is the one most often used in 
    174 applications of the \NEMO ocean model. 
     179applications of the \NEMO\ ocean model. 
    175180The flux form option (see next section) has been present since version $2$. 
    176 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 
    177182momentum advection terms are evaluated using a leapfrog scheme, 
    178 \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). 
    179184At the lateral boundaries either free slip, no slip or partial slip boundary conditions are applied following 
    180185\autoref{chap:LBC}. 
    181186 
    182 % ------------------------------------------------------------------------------------------------------------- 
    183 %        Vorticity term  
    184 % ------------------------------------------------------------------------------------------------------------- 
    185 \subsection[Vorticity term (\textit{dynvor.F90})] 
    186 {Vorticity term (\protect\mdl{dynvor})} 
     187%% ================================================================================================= 
     188\subsection[Vorticity term (\textit{dynvor.F90})]{Vorticity term (\protect\mdl{dynvor})} 
    187189\label{subsec:DYN_vor} 
    188 %------------------------------------------nam_dynvor---------------------------------------------------- 
    189  
    190 \nlst{namdyn_vor}  
    191 %------------------------------------------------------------------------------------------------------------- 
    192  
    193 Options are defined through the \ngn{namdyn\_vor} namelist variables. 
    194 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: 
    195199conserving potential enstrophy of horizontally non-divergent flow (ENS scheme); 
    196200conserving horizontal kinetic energy (ENE scheme); 
     
    198202horizontal kinetic energy for the planetary vorticity term (MIX scheme); 
    199203or conserving both the potential enstrophy of horizontally non-divergent flow and horizontal kinetic energy 
    200 (EEN scheme) (see \autoref{subsec:C_vorEEN}). 
     204(EEN scheme) (see \autoref{subsec:INVARIANTS_vorEEN}). 
    201205In the case of ENS, ENE or MIX schemes the land sea mask may be slightly modified to ensure the consistency of 
    202 vorticity term with analytical equations (\np{ln\_dynvor\_con}\forcode{ = .true.}). 
     206vorticity term with analytical equations (\np[=.true.]{ln_dynvor_con}{ln\_dynvor\_con}). 
    203207The vorticity terms are all computed in dedicated routines that can be found in the \mdl{dynvor} module. 
    204208 
    205 %------------------------------------------------------------- 
    206209%                 enstrophy conserving scheme 
    207 %------------------------------------------------------------- 
    208 \subsubsection[Enstrophy conserving scheme (\forcode{ln_dynvor_ens = .true.})] 
    209 {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})} 
    210212\label{subsec:DYN_vor_ens} 
    211213 
    212214In the enstrophy conserving case (ENS scheme), 
    213215the discrete formulation of the vorticity term provides a global conservation of the enstrophy 
    214 ($ [ (\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$), 
    215217but does not conserve the total kinetic energy. 
    216218It is given by: 
    217219\begin{equation} 
    218   \label{eq:dynvor_ens} 
     220  \label{eq:DYN_vor_ens} 
    219221  \left\{ 
    220222    \begin{aligned} 
     
    225227    \end{aligned} 
    226228  \right. 
    227 \end{equation}  
    228  
    229 %------------------------------------------------------------- 
     229\end{equation} 
     230 
    230231%                 energy conserving scheme 
    231 %------------------------------------------------------------- 
    232 \subsubsection[Energy conserving scheme (\forcode{ln_dynvor_ene = .true.})] 
    233 {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})} 
    234234\label{subsec:DYN_vor_ene} 
    235235 
     
    237237It is given by: 
    238238\begin{equation} 
    239   \label{eq:dynvor_ene} 
     239  \label{eq:DYN_vor_ene} 
    240240  \left\{ 
    241241    \begin{aligned} 
     
    246246    \end{aligned} 
    247247  \right. 
    248 \end{equation}  
    249  
    250 %------------------------------------------------------------- 
     248\end{equation} 
     249 
    251250%                 mix energy/enstrophy conserving scheme 
    252 %------------------------------------------------------------- 
    253 \subsubsection[Mixed energy/enstrophy conserving scheme (\forcode{ln_dynvor_mix = .true.})] 
    254 {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})} 
    255253\label{subsec:DYN_vor_mix} 
    256254 
    257255For the mixed energy/enstrophy conserving scheme (MIX scheme), a mixture of the two previous schemes is used. 
    258 It consists of the ENS scheme (\autoref{eq:dynvor_ens}) for the relative vorticity term, 
    259 and of the ENE scheme (\autoref{eq:dynvor_ene}) applied to the planetary vorticity term. 
    260 \[ 
    261   % \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} 
    262260  \left\{ { 
    263261      \begin{aligned} 
     
    274272\] 
    275273 
    276 %------------------------------------------------------------- 
    277274%                 energy and enstrophy conserving scheme 
    278 %------------------------------------------------------------- 
    279 \subsubsection[Energy and enstrophy conserving scheme (\forcode{ln_dynvor_een = .true.})] 
    280 {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})} 
    281277\label{subsec:DYN_vor_een} 
    282278 
     
    285281the presence of grid point oscillation structures that will be invisible to the operator. 
    286282These structures are \textit{computational modes} that will be at least partly damped by 
    287 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. 
    288284The ENS and ENE schemes therefore do not contribute to dump any grid point noise in the horizontal velocity field. 
    289285Such noise would result in more noise in the vertical velocity field, an undesirable feature. 
     
    291287$u$ and $v$ are located at different grid points, 
    292288a price worth paying to avoid a double averaging in the pressure gradient term as in the $B$-grid. 
    293 \gmcomment{ To circumvent this, Adcroft (ADD REF HERE)  
     289\cmtgm{ To circumvent this, Adcroft (ADD REF HERE) 
    294290Nevertheless, this technique strongly distort the phase and group velocity of Rossby waves....} 
    295291 
     
    297293The idea is to get rid of the double averaging by considering triad combinations of vorticity. 
    298294It is noteworthy that this solution is conceptually quite similar to the one proposed by 
    299 \citep{griffies.gnanadesikan.ea_JPO98} for the discretization of the iso-neutral diffusion operator (see \autoref{apdx:C}). 
    300  
    301 The \citet{arakawa.hsu_MWR90} vorticity advection scheme for a single layer is modified  
    302 for spherical coordinates as described by \citet{arakawa.lamb_MWR81} to obtain the EEN scheme.  
    303 First consider the discrete expression of the potential vorticity, $q$, defined at an $f$-point:  
    304 \[ 
    305   % \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} 
    306302  q  = \frac{\zeta +f} {e_{3f} } 
    307303\] 
    308 where the relative vorticity is defined by (\autoref{eq:divcur_cur}), 
    309 the Coriolis parameter is given by $f=2 \,\Omega \;\sin \varphi _f $ and the layer thickness at $f$-points is:  
    310 \begin{equation} 
    311   \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} 
    312308  e_{3f} = \overline{\overline {e_{3t} }} ^{\,i+1/2,j+1/2} 
    313309\end{equation} 
    314310 
    315 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    316311\begin{figure}[!ht] 
    317   \begin{center} 
    318     \includegraphics[width=\textwidth]{Fig_DYN_een_triad} 
    319     \caption{ 
    320       \protect\label{fig:DYN_een_triad} 
    321       Triads used in the energy and enstrophy conserving scheme (een) for 
    322       $u$-component (upper panel) and $v$-component (lower panel). 
    323     } 
    324   \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} 
    325318\end{figure} 
    326 % >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    327  
    328 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. 
    329321It uses the sum of masked t-point vertical scale factor divided either by the sum of the four t-point masks 
    330 (\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}). 
    331323The latter case preserves the continuity of $e_{3f}$ when one or more of the neighbouring $e_{3t}$ tends to zero and 
    332324extends by continuity the value of $e_{3f}$ into the land areas. 
     
    334326(with a systematic reduction of $e_{3f}$ when a model level intercept the bathymetry) 
    335327that tends to reinforce the topostrophy of the flow 
    336 (\ie the tendency of the flow to follow the isobaths) \citep{penduff.le-sommer.ea_OS07}.  
     328(\ie\ the tendency of the flow to follow the isobaths) \citep{penduff.le-sommer.ea_OS07}. 
    337329 
    338330Next, the vorticity triads, $ {^i_j}\mathbb{Q}^{i_p}_{j_p}$ can be defined at a $T$-point as 
    339331the following triad combinations of the neighbouring potential vorticities defined at f-points 
    340 (\autoref{fig:DYN_een_triad}):  
    341 \begin{equation} 
    342   \label{eq:Q_triads} 
     332(\autoref{fig:DYN_een_triad}): 
     333\begin{equation} 
     334  \label{eq:DYN_Q_triads} 
    343335  _i^j \mathbb{Q}^{i_p}_{j_p} 
    344336  = \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) 
    345337\end{equation} 
    346 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$.  
    347  
    348 Finally, the vorticity terms are represented as:  
    349 \begin{equation} 
    350   \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} 
    351343  \left\{ { 
    352344      \begin{aligned} 
     
    357349      \end{aligned} 
    358350    } \right. 
    359 \end{equation}  
     351\end{equation} 
    360352 
    361353This EEN scheme in fact combines the conservation properties of the ENS and ENE schemes. 
    362354It conserves both total energy and potential enstrophy in the limit of horizontally nondivergent flow 
    363 (\ie $\chi$=$0$) (see \autoref{subsec:C_vorEEN}).  
     355(\ie\ $\chi$=$0$) (see \autoref{subsec:INVARIANTS_vorEEN}). 
    364356Applied to a realistic ocean configuration, it has been shown that it leads to a significant reduction of 
    365357the noise in the vertical velocity field \citep{le-sommer.penduff.ea_OM09}. 
    366358Furthermore, used in combination with a partial steps representation of bottom topography, 
    367359it improves the interaction between current and topography, 
    368 leading to a larger topostrophy of the flow \citep{barnier.madec.ea_OD06, penduff.le-sommer.ea_OS07}.  
    369  
    370 %-------------------------------------------------------------------------------------------------------------- 
    371 %           Kinetic Energy Gradient term 
    372 %-------------------------------------------------------------------------------------------------------------- 
    373 \subsection[Kinetic energy gradient term (\textit{dynkeg.F90})] 
    374 {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})} 
    375364\label{subsec:DYN_keg} 
    376365 
    377 As demonstrated in \autoref{apdx:C}, 
     366As demonstrated in \autoref{apdx:INVARIANTS}, 
    378367there is a single discrete formulation of the kinetic energy gradient term that, 
    379368together with the formulation chosen for the vertical advection (see below), 
    380369conserves the total kinetic energy: 
    381370\[ 
    382   % \label{eq:dynkeg} 
     371  % \label{eq:DYN_keg} 
    383372  \left\{ 
    384373    \begin{aligned} 
     
    389378\] 
    390379 
    391 %-------------------------------------------------------------------------------------------------------------- 
    392 %           Vertical advection term 
    393 %-------------------------------------------------------------------------------------------------------------- 
    394 \subsection[Vertical advection term (\textit{dynzad.F90})] 
    395 {Vertical advection term (\protect\mdl{dynzad})} 
     380%% ================================================================================================= 
     381\subsection[Vertical advection term (\textit{dynzad.F90})]{Vertical advection term (\protect\mdl{dynzad})} 
    396382\label{subsec:DYN_zad} 
    397383 
     
    400386conserves the total kinetic energy. 
    401387Indeed, the change of KE due to the vertical advection is exactly balanced by 
    402 the change of KE due to the gradient of KE (see \autoref{apdx:C}). 
    403 \[ 
    404   % \label{eq:dynzad} 
     388the change of KE due to the gradient of KE (see \autoref{apdx:INVARIANTS}). 
     389\[ 
     390  % \label{eq:DYN_zad} 
    405391  \left\{ 
    406392    \begin{aligned} 
     
    410396  \right. 
    411397\] 
    412 When \np{ln\_dynzad\_zts}\forcode{ = .true.}, 
     398When \np[=.true.]{ln_dynzad_zts}{ln\_dynzad\_zts}, 
    413399a split-explicit time stepping with 5 sub-timesteps is used on the vertical advection term. 
    414 This option can be useful when the value of the timestep is limited by vertical advection \citep{lemarie.debreu.ea_OM15}.  
     400This option can be useful when the value of the timestep is limited by vertical advection \citep{lemarie.debreu.ea_OM15}. 
    415401Note that in this case, 
    416402a similar split-explicit time stepping should be used on vertical advection of tracer to ensure a better stability, 
    417 an option which is only available with a TVD scheme (see \np{ln\_traadv\_tvd\_zts} in \autoref{subsec:TRA_adv_tvd}). 
    418  
    419  
    420 % ================================================================ 
    421 % Coriolis and Advection : flux form 
    422 % ================================================================ 
     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%% ================================================================================================= 
    423406\section{Coriolis and advection: flux form} 
    424407\label{sec:DYN_adv_cor_flux} 
    425 %------------------------------------------nam_dynadv---------------------------------------------------- 
    426  
    427 \nlst{namdyn_adv}  
    428 %------------------------------------------------------------------------------------------------------------- 
    429  
    430 Options are defined through the \ngn{namdyn\_adv} namelist variables. 
     408 
     409Options are defined through the \nam{dyn_adv}{dyn\_adv} namelist variables. 
    431410In the flux form (as in the vector invariant form), 
    432411the Coriolis and momentum advection terms are evaluated using a leapfrog scheme, 
    433 \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). 
    434413At the lateral boundaries either free slip, 
    435414no slip or partial slip boundary conditions are applied following \autoref{chap:LBC}. 
    436415 
    437  
    438 %-------------------------------------------------------------------------------------------------------------- 
    439 %           Coriolis plus curvature metric terms 
    440 %-------------------------------------------------------------------------------------------------------------- 
    441 \subsection[Coriolis plus curvature metric terms (\textit{dynvor.F90})] 
    442 {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})} 
    443418\label{subsec:DYN_cor_flux} 
    444419 
    445420In flux form, the vorticity term reduces to a Coriolis term in which the Coriolis parameter has been modified to account for the "metric" term. 
    446421This altered Coriolis parameter is thus discretised at $f$-points. 
    447 It is given by:  
     422It is given by: 
    448423\begin{multline*} 
    449   % \label{eq:dyncor_metric} 
     424  % \label{eq:DYN_cor_metric} 
    450425  f+\frac{1}{e_1 e_2 }\left( {v\frac{\partial e_2 }{\partial i}  -  u\frac{\partial e_1 }{\partial j}} \right)  \\ 
    451426  \equiv   f + \frac{1}{e_{1f} e_{2f} } \left( { \ \overline v ^{i+1/2}\delta_{i+1/2} \left[ {e_{2u} } \right] 
    452427      -  \overline u ^{j+1/2}\delta_{j+1/2} \left[ {e_{1u} } \right]  }  \ \right) 
    453 \end{multline*}  
    454  
    455 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 
    456431compute the product of the Coriolis parameter and the vorticity. 
    457 However, the energy-conserving scheme (\autoref{eq:dynvor_een}) has exclusively been used to date. 
    458 This term is evaluated using a leapfrog scheme, \ie the velocity is centred in time (\textit{now} velocity). 
    459  
    460 %-------------------------------------------------------------------------------------------------------------- 
    461 %           Flux form Advection term 
    462 %-------------------------------------------------------------------------------------------------------------- 
    463 \subsection[Flux form advection term (\textit{dynadv.F90})] 
    464 {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})} 
    465437\label{subsec:DYN_adv_flux} 
    466438 
    467439The discrete expression of the advection term is given by: 
    468440\[ 
    469   % \label{eq:dynadv} 
     441  % \label{eq:DYN_adv} 
    470442  \left\{ 
    471443    \begin{aligned} 
     
    487459or a $3^{rd}$ order upstream biased scheme, UBS. 
    488460The latter is described in \citet{shchepetkin.mcwilliams_OM05}. 
    489 The schemes are selected using the namelist logicals \np{ln\_dynadv\_cen2} and \np{ln\_dynadv\_ubs}.  
     461The schemes are selected using the namelist logicals \np{ln_dynadv_cen2}{ln\_dynadv\_cen2} and \np{ln_dynadv_ubs}{ln\_dynadv\_ubs}. 
    490462In flux form, the schemes differ by the choice of a space and time interpolation to define the value of 
    491 $u$ and $v$ at the centre of each face of $u$- and $v$-cells, \ie at the $T$-, $f$-, 
    492 and $uw$-points for $u$ and at the $f$-, $T$- and $vw$-points for $v$.  
    493  
    494 %------------------------------------------------------------- 
     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 
    495466%                 2nd order centred scheme 
    496 %------------------------------------------------------------- 
    497 \subsubsection[CEN2: $2^{nd}$ order centred scheme (\forcode{ln_dynadv_cen2 = .true.})] 
    498 {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})} 
    499469\label{subsec:DYN_adv_cen2} 
    500470 
    501471In the centered $2^{nd}$ order formulation, the velocity is evaluated as the mean of the two neighbouring points: 
    502472\begin{equation} 
    503   \label{eq:dynadv_cen2} 
     473  \label{eq:DYN_adv_cen2} 
    504474  \left\{ 
    505475    \begin{aligned} 
     
    508478    \end{aligned} 
    509479  \right. 
    510 \end{equation}  
    511  
    512 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). 
    513483It is therefore notoriously noisy and must be used in conjunction with an explicit diffusion operator to 
    514484produce a sensible solution. 
     
    516486so $u$ and $v$ are the \emph{now} velocities. 
    517487 
    518 %------------------------------------------------------------- 
    519488%                 UBS scheme 
    520 %------------------------------------------------------------- 
    521 \subsubsection[UBS: Upstream Biased Scheme (\forcode{ln_dynadv_ubs = .true.})] 
    522 {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})} 
    523491\label{subsec:DYN_adv_ubs} 
    524492 
     
    527495For example, the evaluation of $u_T^{ubs} $ is done as follows: 
    528496\begin{equation} 
    529   \label{eq:dynadv_ubs} 
     497  \label{eq:DYN_adv_ubs} 
    530498  u_T^{ubs} =\overline u ^i-\;\frac{1}{6} 
    531499  \begin{cases} 
     
    535503\end{equation} 
    536504where $u"_{i+1/2} =\delta_{i+1/2} \left[ {\delta_i \left[ u \right]} \right]$. 
    537 This results in a dissipatively dominant (\ie hyper-diffusive) truncation error 
     505This results in a dissipatively dominant (\ie\ hyper-diffusive) truncation error 
    538506\citep{shchepetkin.mcwilliams_OM05}. 
    539507The overall performance of the advection scheme is similar to that reported in \citet{farrow.stevens_JPO95}. 
     
    541509It is not a \emph{positive} scheme, meaning that false extrema are permitted. 
    542510But the amplitudes of the false extrema are significantly reduced over those in the centred second order method. 
    543 As the scheme already includes a diffusion component, it can be used without explicit lateral diffusion on momentum  
    544 (\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}), 
    545513and it is recommended to do so. 
    546514 
    547515The UBS scheme is not used in all directions. 
    548 In the vertical, the centred $2^{nd}$ order evaluation of the advection is preferred, \ie $u_{uw}^{ubs}$ and 
    549 $u_{vw}^{ubs}$ in \autoref{eq:dynadv_cen2} are used. 
    550 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 
    551519sentence:Since vertical mixing of momentum is a source term of the TKE equation...  } 
    552520 
    553 For stability reasons, the first term in (\autoref{eq:dynadv_ubs}), 
     521For stability reasons, the first term in (\autoref{eq:DYN_adv_ubs}), 
    554522which corresponds to a second order centred scheme, is evaluated using the \textit{now} velocity (centred in time), 
    555523while the second term, which is the diffusion part of the scheme, 
     
    559527Note that the UBS and QUICK (Quadratic Upstream Interpolation for Convective Kinematics) schemes only differ by 
    560528one coefficient. 
    561 Replacing $1/6$ by $1/8$ in (\autoref{eq:dynadv_ubs}) leads to the QUICK advection scheme \citep{webb.de-cuevas.ea_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}. 
    562530This option is not available through a namelist parameter, since the $1/6$ coefficient is hard coded. 
    563531Nevertheless it is quite easy to make the substitution in the \mdl{dynadv\_ubs} module and obtain a QUICK scheme. 
     
    566534there is also the possibility of using a $4^{th}$ order evaluation of the advective velocity as in ROMS. 
    567535This is an error and should be suppressed soon. 
    568 %%% 
    569 \gmcomment{action :  this have to be done} 
    570 %%% 
    571  
    572 % ================================================================ 
    573 %           Hydrostatic pressure gradient term 
    574 % ================================================================ 
    575 \section[Hydrostatic pressure gradient (\textit{dynhpg.F90})] 
    576 {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})} 
    577540\label{sec:DYN_hpg} 
    578 %------------------------------------------nam_dynhpg--------------------------------------------------- 
    579  
    580 \nlst{namdyn_hpg}  
    581 %------------------------------------------------------------------------------------------------------------- 
    582  
    583 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. 
    584549The key distinction between the different algorithms used for 
    585550the hydrostatic pressure gradient is the vertical coordinate used, 
    586 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. 
    587552As a result, any tilt of the surface of the computational levels will require a specific treatment to 
    588553compute the hydrostatic pressure gradient. 
    589554 
    590555The hydrostatic pressure gradient term is evaluated either using a leapfrog scheme, 
    591 \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$), 
    592557or a semi-implcit scheme. 
    593558At the lateral boundaries either free slip, no slip or partial slip boundary conditions are applied. 
    594559 
    595 %-------------------------------------------------------------------------------------------------------------- 
    596 %           z-coordinate with full step 
    597 %-------------------------------------------------------------------------------------------------------------- 
    598 \subsection[Full step $Z$-coordinate (\forcode{ln_dynhpg_zco = .true.})] 
    599 {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})} 
    600562\label{subsec:DYN_hpg_zco} 
    601563 
     
    607569for $k=km$ (surface layer, $jk=1$ in the code) 
    608570\begin{equation} 
    609   \label{eq:dynhpg_zco_surf} 
     571  \label{eq:DYN_hpg_zco_surf} 
    610572  \left\{ 
    611573    \begin{aligned} 
     
    616578    \end{aligned} 
    617579  \right. 
    618 \end{equation}  
     580\end{equation} 
    619581 
    620582for $1<k<km$ (interior layer) 
    621583\begin{equation} 
    622   \label{eq:dynhpg_zco} 
     584  \label{eq:DYN_hpg_zco} 
    623585  \left\{ 
    624586    \begin{aligned} 
     
    631593    \end{aligned} 
    632594  \right. 
    633 \end{equation}  
    634  
    635 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 
    636598the vertical derivative of the scale factor at the surface level ($z=0$). 
    637 Note also that in case of variable volume level (\key{vvl} defined), 
    638 the surface pressure gradient is included in \autoref{eq:dynhpg_zco_surf} and 
    639 \autoref{eq:dynhpg_zco} through the space and time variations of the vertical scale factor $e_{3w}$. 
    640  
    641 %-------------------------------------------------------------------------------------------------------------- 
    642 %           z-coordinate with partial step 
    643 %-------------------------------------------------------------------------------------------------------------- 
    644 \subsection[Partial step $Z$-coordinate (\forcode{ln_dynhpg_zps = .true.})] 
    645 {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})} 
    646605\label{subsec:DYN_hpg_zps} 
    647606 
     
    649608Before taking horizontal gradients between these tracer points, 
    650609a linear interpolation is used to approximate the deeper tracer as if 
    651 it actually lived at the depth of the shallower tracer point.  
     610it actually lived at the depth of the shallower tracer point. 
    652611 
    653612Apart from this modification, 
     
    661620module \mdl{zpsdhe} located in the TRA directory and described in \autoref{sec:TRA_zpshde}. 
    662621 
    663 %-------------------------------------------------------------------------------------------------------------- 
    664 %           s- and s-z-coordinates 
    665 %-------------------------------------------------------------------------------------------------------------- 
     622%% ================================================================================================= 
    666623\subsection{$S$- and $Z$-$S$-coordinates} 
    667624\label{subsec:DYN_hpg_sco} 
    668625 
    669626Pressure gradient formulations in an $s$-coordinate have been the subject of a vast number of papers 
    670 (\eg, \citet{song_MWR98, shchepetkin.mcwilliams_OM05}).  
     627(\eg, \citet{song_MWR98, shchepetkin.mcwilliams_OM05}). 
    671628A number of different pressure gradient options are coded but the ROMS-like, 
    672629density Jacobian with cubic polynomial method is currently disabled whilst known bugs are under investigation. 
    673630 
    674 $\bullet$ Traditional coding (see for example \citet{madec.delecluse.ea_JPO96}: (\np{ln\_dynhpg\_sco}\forcode{ = .true.}) 
    675 \begin{equation} 
    676   \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} 
    677634  \left\{ 
    678635    \begin{aligned} 
     
    683640    \end{aligned} 
    684641  \right. 
    685 \end{equation}  
     642\end{equation} 
    686643 
    687644Where the first term is the pressure gradient along coordinates, 
    688 computed as in \autoref{eq:dynhpg_zco_surf} - \autoref{eq:dynhpg_zco}, 
    689 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 
    690647($e_{3w}$). 
    691   
    692 $\bullet$ Traditional coding with adaptation for ice shelf cavities (\np{ln\_dynhpg\_isf}\forcode{ = .true.}). 
    693 This scheme need the activation of ice shelf cavities (\np{ln\_isfcav}\forcode{ = .true.}). 
    694  
    695 $\bullet$ Pressure Jacobian scheme (prj) (a research paper in preparation) (\np{ln\_dynhpg\_prj}\forcode{ = .true.}) 
    696  
    697 $\bullet$ Density Jacobian with cubic polynomial scheme (DJC) \citep{shchepetkin.mcwilliams_OM05}  
    698 (\np{ln\_dynhpg\_djc}\forcode{ = .true.}) (currently disabled; under development) 
    699  
    700 Note that expression \autoref{eq:dynhpg_sco} is commonly used when the variable volume formulation is activated 
    701 (\key{vvl}) because in that case, even with a flat bottom, 
     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, 
    702659the coordinate surfaces are not horizontal but follow the free surface \citep{levier.treguier.ea_rpt07}. 
    703 The pressure jacobian scheme (\np{ln\_dynhpg\_prj}\forcode{ = .true.}) is available as 
    704 an improved option to \np{ln\_dynhpg\_sco}\forcode{ = .true.} when \key{vvl} is active. 
     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. 
    705662The pressure Jacobian scheme uses a constrained cubic spline to 
    706663reconstruct the density profile across the water column. 
     
    710667This method can provide a more accurate calculation of the horizontal pressure gradient than the standard scheme. 
    711668 
     669%% ================================================================================================= 
    712670\subsection{Ice shelf cavity} 
    713671\label{subsec:DYN_hpg_isf} 
     672 
    714673Beneath an ice shelf, the total pressure gradient is the sum of the pressure gradient due to the ice shelf load and 
    715 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}).\\ 
    716675 
    717676The main hypothesis to compute the ice shelf load is that the ice shelf is in an isostatic equilibrium. 
     
    722681A detailed description of this method is described in \citet{losch_JGR08}.\\ 
    723682 
    724 The pressure gradient due to ocean load is computed using the expression \autoref{eq:dynhpg_sco} described in 
    725 \autoref{subsec:DYN_hpg_sco}.  
    726  
    727 %-------------------------------------------------------------------------------------------------------------- 
    728 %           Time-scheme 
    729 %-------------------------------------------------------------------------------------------------------------- 
    730 \subsection[Time-scheme (\forcode{ln_dynhpg_imp = .{true,false}.})] 
    731 {Time-scheme (\protect\np{ln\_dynhpg\_imp}\forcode{ = .\{true,false\}}.)} 
     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})} 
    732688\label{subsec:DYN_hpg_imp} 
    733689 
     
    742698It involves the evaluation of the hydrostatic pressure gradient as 
    743699an average over the three time levels $t-\rdt$, $t$, and $t+\rdt$ 
    744 (\ie \textit{before}, \textit{now} and  \textit{after} time-steps), 
    745 rather than at the central time level $t$ only, as in the standard leapfrog scheme.  
    746  
    747 $\bullet$ leapfrog scheme (\np{ln\_dynhpg\_imp}\forcode{ = .true.}): 
    748  
    749 \begin{equation} 
    750   \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} 
    751707  \frac{u^{t+\rdt}-u^{t-\rdt}}{2\rdt} = \;\cdots \; 
    752708  -\frac{1}{\rho_o \,e_{1u} }\delta_{i+1/2} \left[ {p_h^t } \right] 
    753709\end{equation} 
    754710 
    755 $\bullet$ semi-implicit scheme (\np{ln\_dynhpg\_imp}\forcode{ = .true.}): 
    756 \begin{equation} 
    757   \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} 
    758714  \frac{u^{t+\rdt}-u^{t-\rdt}}{2\rdt} = \;\cdots \; 
    759715  -\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] 
    760716\end{equation} 
    761717 
    762 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 
    763719significant additional computation since the density can be updated to time level $t+\rdt$ before 
    764720computing the horizontal hydrostatic pressure gradient. 
    765721It can be easily shown that the stability limit associated with the hydrostatic pressure gradient doubles using 
    766 \autoref{eq:dynhpg_imp} compared to that using the standard leapfrog scheme \autoref{eq:dynhpg_lf}. 
    767 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 
    768724eliminate high frequency IGWs. 
    769 Obviously, when using \autoref{eq:dynhpg_imp}, 
     725Obviously, when using \autoref{eq:DYN_hpg_imp}, 
    770726the doubling of the time-step is achievable only if no other factors control the time-step, 
    771727such as the stability limits associated with advection or diffusion. 
    772728 
    773 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}. 
    774730In this case, we choose to apply the time filter to temperature and salinity used in the equation of state, 
    775731instead of applying it to the hydrostatic pressure or to the density, 
     
    777733The density used to compute the hydrostatic pressure gradient (whatever the formulation) is evaluated as follows: 
    778734\[ 
    779   % \label{eq:rho_flt} 
     735  % \label{eq:DYN_rho_flt} 
    780736  \rho^t = \rho( \widetilde{T},\widetilde {S},z_t) 
    781737  \quad    \text{with}  \quad 
     
    785741Note that in the semi-implicit case, it is necessary to save the filtered density, 
    786742an extra three-dimensional field, in the restart file to restart the model with exact reproducibility. 
    787 This option is controlled by  \np{nn\_dynhpg\_rst}, a namelist parameter. 
    788  
    789 % ================================================================ 
    790 % Surface Pressure Gradient 
    791 % ================================================================ 
    792 \section[Surface pressure gradient (\textit{dynspg.F90})] 
    793 {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})} 
    794747\label{sec:DYN_spg} 
    795 %-----------------------------------------nam_dynspg---------------------------------------------------- 
    796  
    797 \nlst{namdyn_spg}  
    798 %------------------------------------------------------------------------------------------------------------ 
    799  
    800 Options are defined through the \ngn{namdyn\_spg} namelist variables. 
    801 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}). 
    802757The main distinction is between the fixed volume case (linear free surface) and 
    803 the variable volume case (nonlinear free surface, \key{vvl} is defined). 
    804 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}) 
    805760the vertical scale factors $e_{3}$ are fixed in time, 
    806 while they are time-dependent in the nonlinear case (\autoref{subsec:PE_free_surface}). 
    807 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, 
    808763which imposes a very small time step when an explicit time stepping is used. 
    809 Two methods are proposed to allow a longer time step for the three-dimensional equations:  
    810 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?}), 
    811766and the split-explicit free surface described below. 
    812 The extra term introduced in the filtered method is calculated implicitly,  
     767The extra term introduced in the filtered method is calculated implicitly, 
    813768so that the update of the next velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}. 
    814769 
    815  
    816770The form of the surface pressure gradient term depends on how the user wants to 
    817 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}). 
    818772Three formulations are available, all controlled by a CPP key (ln\_dynspg\_xxx): 
    819773an explicit formulation which requires a small time step; 
    820774a filtered free surface formulation which allows a larger time step by 
    821 adding a filtering term into the momentum equation;  
     775adding a filtering term into the momentum equation; 
    822776and a split-explicit free surface formulation, described below, which also allows a larger time step. 
    823777 
     
    825779As a consequence the update of the $next$ velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}. 
    826780 
    827  
    828 %-------------------------------------------------------------------------------------------------------------- 
    829 % Explicit free surface formulation 
    830 %-------------------------------------------------------------------------------------------------------------- 
    831 \subsection[Explicit free surface (\texttt{\textbf{key\_dynspg\_exp}})] 
    832 {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})} 
    833783\label{subsec:DYN_spg_exp} 
    834784 
    835 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), 
    836786the model time step is chosen to be small enough to resolve the external gravity waves 
    837787(typically a few tens of seconds). 
    838 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), 
    839789is thus simply given by : 
    840790\begin{equation} 
    841   \label{eq:dynspg_exp} 
     791  \label{eq:DYN_spg_exp} 
    842792  \left\{ 
    843793    \begin{aligned} 
     
    846796    \end{aligned} 
    847797  \right. 
    848 \end{equation}  
    849  
    850 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), 
    851801the surface pressure gradient is already included in the momentum tendency through 
    852802the level thickness variation allowed in the computation of the hydrostatic pressure gradient. 
    853803Thus, nothing is done in the \mdl{dynspg\_exp} module. 
    854804 
    855 %-------------------------------------------------------------------------------------------------------------- 
    856 % Split-explict free surface formulation 
    857 %-------------------------------------------------------------------------------------------------------------- 
    858 \subsection[Split-explicit free surface (\texttt{\textbf{key\_dynspg\_ts}})] 
    859 {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})} 
    860807\label{subsec:DYN_spg_ts} 
    861 %------------------------------------------namsplit----------------------------------------------------------- 
    862 % 
    863808%\nlst{namsplit} 
    864 %------------------------------------------------------------------------------------------------------------- 
    865  
    866 The split-explicit free surface formulation used in \NEMO (\key{dynspg\_ts} defined), 
     809 
     810The split-explicit free surface formulation used in \NEMO\ (\np{ln_dynspg_ts}{ln\_dynspg\_ts} set to true), 
    867811also called the time-splitting formulation, follows the one proposed by \citet{shchepetkin.mcwilliams_OM05}. 
    868812The general idea is to solve the free surface equation and the associated barotropic velocity equations with 
    869813a smaller time step than $\rdt$, the time step used for the three dimensional prognostic variables 
    870 (\autoref{fig:DYN_dynspg_ts}). 
     814(\autoref{fig:DYN_spg_ts}). 
    871815The size of the small time step, $\rdt_e$ (the external mode or barotropic time step) is provided through 
    872 the \np{nn\_baro} namelist parameter as: $\rdt_e = \rdt / nn\_baro$. 
    873 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 
    874818the stability of the barotropic system is essentially controled by external waves propagation. 
    875819Maximum Courant number is in that case time independent, and easily computed online from the input bathymetry. 
    876 Therefore, $\rdt_e$ is adjusted so that the Maximum allowed Courant number is smaller than \np{rn\_bt\_cmax}. 
    877  
    878 %%% 
     820Therefore, $\rdt_e$ is adjusted so that the Maximum allowed Courant number is smaller than \np{rn_bt_cmax}{rn\_bt\_cmax}. 
     821 
    879822The barotropic mode solves the following equations: 
    880823% \begin{subequations} 
    881 %  \label{eq:BT} 
    882 \begin{equation} 
    883   \label{eq:BT_dyn} 
     824%  \label{eq:DYN_BT} 
     825\begin{equation} 
     826  \label{eq:DYN_BT_dyn} 
    884827  \frac{\partial {\mathrm \overline{{\mathbf U}}_h} }{\partial t}= 
    885828  -f\;{\mathrm {\mathbf k}}\times {\mathrm \overline{{\mathbf U}}_h} 
     
    887830\end{equation} 
    888831\[ 
    889   % \label{eq:BT_ssh} 
     832  % \label{eq:DYN_BT_ssh} 
    890833  \frac{\partial \eta }{\partial t}=-\nabla \cdot \left[ {\left( {H+\eta } \right) \; {\mathrm{\mathbf \overline{U}}}_h \,} \right]+P-E 
    891834\] 
     
    893836where $\mathrm {\overline{\mathbf G}}$ is a forcing term held constant, containing coupling term between modes, 
    894837surface atmospheric forcing as well as slowly varying barotropic terms not explicitly computed to gain efficiency. 
    895 The third term on the right hand side of \autoref{eq:BT_dyn} represents the bottom stress 
    896 (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. 
    897840Temporal discretization of the system above follows a three-time step Generalized Forward Backward algorithm 
    898841detailed in \citet{shchepetkin.mcwilliams_OM05}. 
    899 AB3-AM4 coefficients used in \NEMO follow the second-order accurate, 
     842AB3-AM4 coefficients used in \NEMO\ follow the second-order accurate, 
    900843"multi-purpose" stability compromise as defined in \citet{shchepetkin.mcwilliams_ibk09} 
    901 (see their figure 12, lower left).  
    902  
    903 %>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   > 
     844(see their figure 12, lower left). 
     845 
    904846\begin{figure}[!t] 
    905   \begin{center} 
    906     \includegraphics[width=\textwidth]{Fig_DYN_dynspg_ts} 
    907     \caption{ 
    908       \protect\label{fig:DYN_dynspg_ts} 
    909       Schematic of the split-explicit time stepping scheme for the external and internal modes. 
    910       Time increases to the right. In this particular exemple, 
    911       a boxcar averaging window over $nn\_baro$ barotropic time steps is used ($nn\_bt\_flt=1$) and $nn\_baro=5$. 
    912       Internal mode time steps (which are also the model time steps) are denoted by $t-\rdt$, $t$ and $t+\rdt$. 
    913       Variables with $k$ superscript refer to instantaneous barotropic variables, 
    914       $< >$ and $<< >>$ operator refer to time filtered variables using respectively primary (red vertical bars) and 
    915       secondary weights (blue vertical bars). 
    916       The former are used to obtain time filtered quantities at $t+\rdt$ while 
    917       the latter are used to obtain time averaged transports to advect tracers. 
    918       a) Forward time integration: \protect\np{ln\_bt\_fw}\forcode{ = .true.}, 
    919       \protect\np{ln\_bt\_av}\forcode{ = .true.}. 
    920       b) Centred time integration: \protect\np{ln\_bt\_fw}\forcode{ = .false.}, 
    921       \protect\np{ln\_bt\_av}\forcode{ = .true.}. 
    922       c) Forward time integration with no time filtering (POM-like scheme): 
    923       \protect\np{ln\_bt\_fw}\forcode{ = .true.}, \protect\np{ln\_bt\_av}\forcode{ = .false.}. 
    924     } 
    925   \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} 
    926869\end{figure} 
    927 %>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   > 
    928  
    929 In the default case (\np{ln\_bt\_fw}\forcode{ = .true.}), 
     870 
     871In the default case (\np[=.true.]{ln_bt_fw}{ln\_bt\_fw}), 
    930872the external mode is integrated between \textit{now} and \textit{after} baroclinic time-steps 
    931 (\autoref{fig:DYN_dynspg_ts}a). 
     873(\autoref{fig:DYN_spg_ts}a). 
    932874To avoid aliasing of fast barotropic motions into three dimensional equations, 
    933 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}). 
    934876In that case, the integration is extended slightly beyond \textit{after} time step to 
    935877provide time filtered quantities. 
    936878These are used for the subsequent initialization of the barotropic mode in the following baroclinic step. 
    937 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, 
    938880asselin filtering is not applied to barotropic quantities.\\ 
    939881Alternatively, one can choose to integrate barotropic equations starting from \textit{before} time step 
    940 (\np{ln\_bt\_fw}\forcode{ = .false.}). 
    941 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), 
    942884the baroclinic to barotropic forcing term given at \textit{now} time step become centred in 
    943885the middle of the integration window. 
     
    946888%references to Patrick Marsaleix' work here. Also work done by SHOM group. 
    947889 
    948 %%% 
    949890 
    950891As far as tracer conservation is concerned, 
     
    960901obtain exact conservation. 
    961902 
    962 %%% 
    963903 
    964904One can eventually choose to feedback instantaneous values by not using any time filter 
    965 (\np{ln\_bt\_av}\forcode{ = .false.}).  
     905(\np[=.false.]{ln_bt_av}{ln\_bt\_av}). 
    966906In that case, external mode equations are continuous in time, 
    967 \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. 
    968908This is the method used so far in the POM model, the stability being maintained by 
    969909refreshing at (almost) each barotropic time step advection and horizontal diffusion terms. 
    970 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, 
    971911removing time filtering is not recommended except for debugging purposes. 
    972912This may be used for instance to appreciate the damping effect of the standard formulation on 
     
    975915it is still significant as shown by \citet{levier.treguier.ea_rpt07} in the case of an analytical barotropic Kelvin wave. 
    976916 
    977 %>>>>>=============== 
    978 \gmcomment{               %%% copy from griffies Book  
     917\cmtgm{               %%% copy from griffies Book 
    979918 
    980919\textbf{title: Time stepping the barotropic system } 
     
    983922Hence, we can update the surface height and vertically integrated velocity with a leap-frog scheme using 
    984923the small barotropic time step $\rdt$. 
    985 We have  
     924We have 
    986925 
    987926\[ 
     
    1006945and total depth of the ocean $H(\tau)$ are held for the duration of the barotropic time stepping over 
    1007946a single cycle. 
    1008 This is also the time that sets the barotropic time steps via  
     947This is also the time that sets the barotropic time steps via 
    1009948\[ 
    1010949  % \label{eq:DYN_spg_ts_t} 
     
    1012951\] 
    1013952with $n$ an integer. 
    1014 The density scaled surface pressure is evaluated via  
     953The density scaled surface pressure is evaluated via 
    1015954\[ 
    1016955  % \label{eq:DYN_spg_ts_ps} 
     
    1021960  \end{cases} 
    1022961\] 
    1023 To get started, we assume the following initial conditions  
     962To get started, we assume the following initial conditions 
    1024963\[ 
    1025964  % \label{eq:DYN_spg_ts_eta} 
     
    1029968  \end{split} 
    1030969\] 
    1031 with  
     970with 
    1032971\[ 
    1033972  % \label{eq:DYN_spg_ts_etaF} 
     
    1035974\] 
    1036975the time averaged surface height taken from the previous barotropic cycle. 
    1037 Likewise,  
     976Likewise, 
    1038977\[ 
    1039978  % \label{eq:DYN_spg_ts_u} 
     
    1041980  \textbf{U}(\tau,t_{n=1}) = \textbf{U}^{(b)}(\tau,t_{n=0}) + \rdt \ \text{RHS}_{n=0} 
    1042981\] 
    1043 with  
     982with 
    1044983\[ 
    1045984  % \label{eq:DYN_spg_ts_u} 
     
    1047986\] 
    1048987the time averaged vertically integrated transport. 
    1049 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. 
    1050989 
    1051990Upon reaching $t_{n=N} = \tau + 2\rdt \tau$ , 
    1052991the vertically integrated velocity is time averaged to produce the updated vertically integrated velocity at 
    1053 baroclinic time $\tau + \rdt \tau$  
     992baroclinic time $\tau + \rdt \tau$ 
    1054993\[ 
    1055994  % \label{eq:DYN_spg_ts_u} 
     
    1057996\] 
    1058997The surface height on the new baroclinic time step is then determined via a baroclinic leap-frog using 
    1059 the following form  
     998the following form 
    1060999 
    10611000\begin{equation} 
    10621001  \label{eq:DYN_spg_ts_ssh} 
    1063   \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] 
    10641003\end{equation} 
    10651004 
    10661005The use of this "big-leap-frog" scheme for the surface height ensures compatibility between 
    10671006the mass/volume budgets and the tracer budgets. 
    1068 More discussion of this point is provided in Chapter 10 (see in particular Section 10.2).  
    1069   
     1007More discussion of this point is provided in Chapter 10 (see in particular Section 10.2). 
     1008 
    10701009In general, some form of time filter is needed to maintain integrity of the surface height field due to 
    10711010the leap-frog splitting mode in equation \autoref{eq:DYN_spg_ts_ssh}. 
     
    10781017  \eta^{F}(\tau-\Delta) =  \overline{\eta^{(b)}(\tau)} 
    10791018\end{equation} 
    1080 Another approach tried was  
     1019Another approach tried was 
    10811020 
    10821021\[ 
     
    10911030eliminating tracer and surface height time filtering (see ?? for more complete discussion). 
    10921031However, in the general case with a non-zero $\alpha$, 
    1093 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. 
    10941033 
    10951034}            %%end gm comment (copy of griffies book) 
    10961035 
    1097 %>>>>>=============== 
    1098  
    1099  
    1100 %-------------------------------------------------------------------------------------------------------------- 
    1101 % Filtered free surface formulation 
    1102 %-------------------------------------------------------------------------------------------------------------- 
    1103 \subsection[Filtered free surface (\texttt{\textbf{key\_dynspg\_flt}})] 
    1104 {Filtered free surface (\protect\key{dynspg\_flt})} 
     1036%% ================================================================================================= 
     1037\subsection{Filtered free surface (\forcode{dynspg_flt?})} 
    11051038\label{subsec:DYN_spg_fltp} 
    11061039 
    1107 The filtered formulation follows the \citet{roullet.madec_JGR00} implementation.  
    1108 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. 
    11091042The elliptic solvers available in the code are documented in \autoref{chap:MISC}. 
    11101043 
    11111044%% gm %%======>>>>   given here the discrete eqs provided to the solver 
    1112 \gmcomment{               %%% copy from chap-model basics  
     1045\cmtgm{               %%% copy from chap-model basics 
    11131046  \[ 
    1114     % \label{eq:spg_flt} 
     1047    % \label{eq:DYN_spg_flt} 
    11151048    \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= {\mathrm {\mathbf M}} 
    11161049    - g \nabla \left( \tilde{\rho} \ \eta \right) 
     
    11201053  $\widetilde{\rho} = \rho / \rho_o$ is the dimensionless density, 
    11211054  and $\mathrm {\mathbf M}$ represents the collected contributions of the Coriolis, hydrostatic pressure gradient, 
    1122   non-linear and viscous terms in \autoref{eq:PE_dyn}. 
    1123 }   %end gmcomment 
    1124  
    1125 Note that in the linear free surface formulation (\key{vvl} not defined), 
     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), 
    11261059the ocean depth is time-independent and so is the matrix to be inverted. 
    1127 It is computed once and for all and applies to all ocean time steps.  
    1128  
    1129 % ================================================================ 
    1130 % Lateral diffusion term 
    1131 % ================================================================ 
    1132 \section[Lateral diffusion term and operators (\textit{dynldf.F90})] 
    1133 {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})} 
    11341064\label{sec:DYN_ldf} 
    1135 %------------------------------------------nam_dynldf---------------------------------------------------- 
    1136  
    1137 \nlst{namdyn_ldf}  
    1138 %------------------------------------------------------------------------------------------------------------- 
    1139  
    1140 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. 
    11411073The options available for lateral diffusion are to use either laplacian (rotated or not) or biharmonic operators. 
    11421074The coefficients may be constant or spatially variable; 
    11431075the description of the coefficients is found in the chapter on lateral physics (\autoref{chap:LDF}). 
    11441076The lateral diffusion of momentum is evaluated using a forward scheme, 
    1145 \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, 
    11461078except for the pure vertical component that appears when a tensor of rotation is used. 
    1147 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}). 
    11481080 
    11491081At the lateral boundaries either free slip, 
    11501082no slip or partial slip boundary conditions are applied according to the user's choice (see \autoref{chap:LBC}). 
    11511083 
    1152 \gmcomment{ 
     1084\cmtgm{ 
    11531085  Hyperviscous operators are frequently used in the simulation of turbulent flows to 
    11541086  control the dissipation of unresolved small scale features. 
     
    11591091  In finite difference methods, 
    11601092  the biharmonic operator is frequently the method of choice to achieve this scale selective dissipation since 
    1161   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$ 
    11621094  (so that short waves damped more rapidelly than long ones), 
    11631095  whereas the Laplace operator damping time scales only like $\lambda^{-2}$. 
    11641096} 
    11651097 
    1166 % ================================================================ 
    1167 \subsection[Iso-level laplacian (\forcode{ln_dynldf_lap = .true.})] 
    1168 {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})} 
    11691100\label{subsec:DYN_ldf_lap} 
    11701101 
    1171 For lateral iso-level diffusion, the discrete operator is:  
    1172 \begin{equation} 
    1173   \label{eq:dynldf_lap} 
     1102For lateral iso-level diffusion, the discrete operator is: 
     1103\begin{equation} 
     1104  \label{eq:DYN_ldf_lap} 
    11741105  \left\{ 
    11751106    \begin{aligned} 
    11761107      D_u^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{1u} }\delta_{i+1/2} \left[ {A_T^{lm} 
    1177           \;\chi } \right]-\frac{1}{e_{2u} {\kern 1pt}e_{3u} }\delta_j \left[  
     1108          \;\chi } \right]-\frac{1}{e_{2u} {\kern 1pt}e_{3u} }\delta_j \left[ 
    11781109        {A_f^{lm} \;e_{3f} \zeta } \right] \\ \\ 
    11791110      D_v^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{2v} }\delta_{j+1/2} \left[ {A_T^{lm} 
    1180           \;\chi } \right]+\frac{1}{e_{1v} {\kern 1pt}e_{3v} }\delta_i \left[  
     1111          \;\chi } \right]+\frac{1}{e_{1v} {\kern 1pt}e_{3v} }\delta_i \left[ 
    11811112        {A_f^{lm} \;e_{3f} \zeta } \right] 
    11821113    \end{aligned} 
    11831114  \right. 
    1184 \end{equation}  
    1185  
    1186 As explained in \autoref{subsec:PE_ldf}, 
     1115\end{equation} 
     1116 
     1117As explained in \autoref{subsec:MB_ldf}, 
    11871118this formulation (as the gradient of a divergence and curl of the vorticity) preserves symmetry and 
    1188 ensures a complete separation between the vorticity and divergence parts of the momentum diffusion.  
    1189  
    1190 %-------------------------------------------------------------------------------------------------------------- 
    1191 %           Rotated laplacian operator 
    1192 %-------------------------------------------------------------------------------------------------------------- 
    1193 \subsection[Rotated laplacian (\forcode{ln_dynldf_iso = .true.})] 
    1194 {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})} 
    11951123\label{subsec:DYN_ldf_iso} 
    11961124 
    11971125A rotation of the lateral momentum diffusion operator is needed in several cases: 
    1198 for iso-neutral diffusion in the $z$-coordinate (\np{ln\_dynldf\_iso}\forcode{ = .true.}) and 
    1199 for either iso-neutral (\np{ln\_dynldf\_iso}\forcode{ = .true.}) or 
    1200 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. 
    12011129In the partial step case, coordinates are horizontal except at the deepest level and 
    1202 no rotation is performed when \np{ln\_dynldf\_hor}\forcode{ = .true.}. 
     1130no rotation is performed when \np[=.true.]{ln_dynldf_hor}{ln\_dynldf\_hor}. 
    12031131The diffusion operator is defined simply as the divergence of down gradient momentum fluxes on 
    12041132each momentum component. 
     
    12061134The resulting discrete representation is: 
    12071135\begin{equation} 
    1208   \label{eq:dyn_ldf_iso} 
     1136  \label{eq:DYN_ldf_iso} 
    12091137  \begin{split} 
    12101138    D_u^{l\textbf{U}} &= \frac{1}{e_{1u} \, e_{2u} \, e_{3u} } \\ 
     
    12301158                -e_{2f} \; r_{1f} \,\overline{\overline {\delta_{k+1/2}[v]}}^{\,i+1/2,\,k}} 
    12311159            \right)} \right]}    \right. \\ 
    1232     & \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} 
    12331161            }\,\delta_{j} [v] - e_{1t}\, r_{2t} 
    12341162            \,\overline{\overline {\delta_{k+1/2} [v]}} ^{\,j,\,k}} 
    12351163        \right)} \right] \\ 
    1236     & \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 
    12371165              {\delta_{i+1/2} [v]}}^{\,i+1/2,\,k+1/2} }\right.} \right. \\ 
    12381166    &  \ \qquad \qquad \qquad \quad\ 
    12391167    - e_{1v} \, r_{2vw} \,\overline{\overline {\delta_{j+1/2} [v]}} ^{\,j+1/2,\,k+1/2} \\ 
    1240     & \left. {\left. { \ \qquad \qquad \qquad \ \ \ \left. {\  
     1168    & \left. {\left. { \ \qquad \qquad \qquad \ \ \ \left. {\ 
    12411169                +\frac{e_{1v}\, e_{2v} }{e_{3vw} }\,\left( {r_{1vw}^2+r_{2vw}^2} 
    1242                 \right)\,\delta_{k+1/2} [v]} \right)} \right]\;\;\;} \right\}  
     1170                \right)\,\delta_{k+1/2} [v]} \right)} \right]\;\;\;} \right\} 
    12431171  \end{split} 
    12441172\end{equation} 
    12451173where $r_1$ and $r_2$ are the slopes between the surface along which the diffusion operator acts and 
    1246 the surface of computation ($z$- or $s$-surfaces).  
     1174the surface of computation ($z$- or $s$-surfaces). 
    12471175The way these slopes are evaluated is given in the lateral physics chapter (\autoref{chap:LDF}). 
    12481176 
    1249 %-------------------------------------------------------------------------------------------------------------- 
    1250 %           Iso-level bilaplacian operator 
    1251 %-------------------------------------------------------------------------------------------------------------- 
    1252 \subsection[Iso-level bilaplacian (\forcode{ln_dynldf_bilap = .true.})] 
    1253 {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})} 
    12541179\label{subsec:DYN_ldf_bilap} 
    12551180 
    1256 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. 
    12571182It requires an additional assumption on boundary conditions: 
    12581183the first derivative term normal to the coast depends on the free or no-slip lateral boundary conditions chosen, 
    12591184while the third derivative terms normal to the coast are set to zero (see \autoref{chap:LBC}). 
    1260 %%% 
    1261 \gmcomment{add a remark on the the change in the position of the coefficient} 
    1262 %%% 
    1263  
    1264 % ================================================================ 
    1265 %           Vertical diffusion term 
    1266 % ================================================================ 
    1267 \section[Vertical diffusion term (\textit{dynzdf.F90})] 
    1268 {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})} 
    12691189\label{sec:DYN_zdf} 
    1270 %----------------------------------------------namzdf------------------------------------------------------ 
    1271  
    1272 \nlst{namzdf}  
    1273 %------------------------------------------------------------------------------------------------------------- 
    1274  
    1275 Options are defined through the \ngn{namzdf} namelist variables. 
     1190 
     1191Options are defined through the \nam{zdf}{zdf} namelist variables. 
    12761192The 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. 
    12771193Two time stepping schemes can be used for the vertical diffusion term: 
    12781194$(a)$ a forward time differencing scheme 
    1279 (\np{ln\_zdfexp}\forcode{ = .true.}) using a time splitting technique (\np{nn\_zdfexp} $>$ 1) or 
    1280 $(b)$ a backward (or implicit) time differencing scheme (\np{ln\_zdfexp}\forcode{ = .false.}) 
    1281 (see \autoref{chap:STP}). 
    1282 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. 
    12831199 
    12841200The formulation of the vertical subgrid scale physics is the same whatever the vertical coordinate is. 
    1285 The vertical diffusion operators given by \autoref{eq:PE_zdf} take the following semi-discrete space form: 
    1286 \[ 
    1287   % \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} 
    12881204  \left\{ 
    12891205    \begin{aligned} 
     
    13031219the vertical turbulent momentum fluxes, 
    13041220\begin{equation} 
    1305   \label{eq:dynzdf_sbc} 
     1221  \label{eq:DYN_zdf_sbc} 
    13061222  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{z=1} 
    13071223  = \frac{1}{\rho_o} \binom{\tau_u}{\tau_v } 
     
    13091225where $\left( \tau_u ,\tau_v \right)$ are the two components of the wind stress vector in 
    13101226the (\textbf{i},\textbf{j}) coordinate system. 
    1311 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 
    13121228the vertical over the mixed layer depth. 
    13131229If the vertical mixing coefficient is small (when no mixed layer scheme is used) 
     
    13161232 
    13171233The turbulent flux of momentum at the bottom of the ocean is specified through a bottom friction parameterisation 
    1318 (see \autoref{sec:ZDF_bfr}) 
    1319  
    1320 % ================================================================ 
    1321 % External Forcing 
    1322 % ================================================================ 
     1234(see \autoref{sec:ZDF_drg}) 
     1235 
     1236%% ================================================================================================= 
    13231237\section{External forcings} 
    13241238\label{sec:DYN_forcing} 
     
    13261240Besides the surface and bottom stresses (see the above section) 
    13271241which are introduced as boundary conditions on the vertical mixing, 
    1328 three other forcings may enter the dynamical equations by affecting the surface pressure gradient.  
    1329  
    1330 (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}), 
    13311245the atmospheric pressure is taken into account when computing the surface pressure gradient. 
    13321246 
    1333 (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}), 
    13341248the tidal potential is taken into account when computing the surface pressure gradient. 
    13351249 
    1336 (3) When \np{nn\_ice\_embd}\forcode{ = 2} and LIM or CICE is used 
    1337 (\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), 
    13381252the snow-ice mass is taken into account when computing the surface pressure gradient. 
    13391253 
    1340  
    1341 \gmcomment{ missing : the lateral boundary condition !!!   another external forcing 
     1254\cmtgm{ missing : the lateral boundary condition !!!   another external forcing 
    13421255 } 
    13431256 
    1344 % ================================================================ 
    1345 % Wetting and drying  
    1346 % ================================================================ 
     1257%% ================================================================================================= 
    13471258\section{Wetting and drying } 
    13481259\label{sec:DYN_wetdry} 
     1260 
    13491261There are two main options for wetting and drying code (wd): 
    13501262(a) an iterative limiter (il) and (b) a directional limiter (dl). 
     
    13561268by setting $\mathrm{ln\_wd\_dl} = \mathrm{.true.}$ and $\mathrm{ln\_wd\_il} = \mathrm{.false.}$. 
    13571269 
    1358 \nlst{namwad} 
     1270\begin{listing} 
     1271  \nlst{namwad} 
     1272  \caption{\forcode{&namwad}} 
     1273  \label{lst:namwad} 
     1274\end{listing} 
    13591275 
    13601276The following terminology is used. The depth of the topography (positive downwards) 
    1361 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. 
    13621278The height of the free surface (positive upwards) is denoted by $ \mathrm{ssh}$. Given the sign 
    13631279conventions used, the water depth, $h$, is the height of the free surface plus the depth of the 
     
    13671283covered by water. They require the topography specified with a model 
    13681284configuration to have negative depths at points where the land is higher than the 
    1369 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 
    13701286initial state with zero sea surface height elevation. 
    13711287The user can choose to compute the vertical grid and heights in the model relative to 
     
    13861302All these configurations have used pure sigma coordinates. It is expected that 
    13871303the wetting and drying code will work in domains with more general s-coordinates provided 
    1388 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. 
    13891305 
    13901306The next sub-section descrbies the directional limiter and the following sub-section the iterative limiter. 
    13911307The final sub-section covers some additional considerations that are relevant to both schemes. 
    13921308 
    1393  
    1394 %----------------------------------------------------------------------------------------- 
    13951309%   Iterative limiters 
    1396 %----------------------------------------------------------------------------------------- 
    1397 \subsection[Directional limiter (\textit{wet\_dry.F90})] 
    1398 {Directional limiter (\mdl{wet\_dry})} 
     1310%% ================================================================================================= 
     1311\subsection[Directional limiter (\textit{wet\_dry.F90})]{Directional limiter (\mdl{wet\_dry})} 
    13991312\label{subsec:DYN_wd_directional_limiter} 
     1313 
    14001314The principal idea of the directional limiter is that 
    1401 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}). 
    14021316 
    14031317All the changes associated with this option are made to the barotropic solver for the non-linear 
     
    14091323 
    14101324The flux across each $u$-face of a tracer cell is multiplied by a factor zuwdmask (an array which depends on ji and jj). 
    1411 If the user sets ln\_wd\_dl\_ramp = .False. then zuwdmask is 1 when the 
    1412 flux is from a cell with water depth greater than rn\_wdmin1 and 0 otherwise. If the user sets 
    1413 ln\_wd\_dl\_ramp = .True. the flux across the face is ramped down as the water depth decreases 
    1414 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. 
    14151329 
    14161330At the point where the flux across a $u$-face is multiplied by zuwdmask , we have chosen 
     
    14221336treatment in the calculation of the flux of mass across the cell face. 
    14231337 
    1424  
    14251338\cite{warner.defne.ea_CG13} state that in their scheme the velocity masks at the cell faces for the baroclinic 
    14261339timesteps are set to 0 or 1 depending on whether the average of the masks over the barotropic sub-steps is respectively less than 
     
    14281341fields (tracers independent of $x$, $y$ and $z$). Our scheme conserves constant tracers because 
    14291342the velocities used at the tracer cell faces on the baroclinic timesteps are carefully calculated by dynspg\_ts 
    1430 to equal their mean value during the barotropic steps. If the user sets ln\_wd\_dl\_bc = .True., the 
    1431 baroclinic velocities are also multiplied by a suitably weighted average of zuwdmask.   
    1432  
    1433 %----------------------------------------------------------------------------------------- 
     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 
    14341346%   Iterative limiters 
    1435 %----------------------------------------------------------------------------------------- 
    1436  
    1437 \subsection[Iterative limiter (\textit{wet\_dry.F90})] 
    1438 {Iterative limiter (\mdl{wet\_dry})} 
     1347 
     1348%% ================================================================================================= 
     1349\subsection[Iterative limiter (\textit{wet\_dry.F90})]{Iterative limiter (\mdl{wet\_dry})} 
    14391350\label{subsec:DYN_wd_iterative_limiter} 
    14401351 
    1441 \subsubsection[Iterative flux limiter (\textit{wet\_dry.F90})] 
    1442 {Iterative flux limiter (\mdl{wet\_dry})} 
    1443 \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} 
    14441355 
    14451356The iterative limiter modifies the fluxes across the faces of cells that are either already ``dry'' 
     
    14491360 
    14501361The continuity equation for the total water depth in a column 
    1451 \begin{equation} \label{dyn_wd_continuity} 
    1452  \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 . 
    14531365\end{equation} 
    14541366can be written in discrete form  as 
    14551367 
    1456 \begin{align} \label{dyn_wd_continuity_2} 
    1457 \frac{e_1 e_2}{\Delta t} ( h_{i,j}(t_{n+1}) - h_{i,j}(t_e) )  
    1458 &= - ( \mathrm{flxu}_{i+1,j} - \mathrm{flxu}_{i,j}  + \mathrm{flxv}_{i,j+1} - \mathrm{flxv}_{i,j} ) \\ 
    1459 &= \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} . 
    14601373\end{align} 
    14611374 
     
    14701383(zzflxp) and fluxes that are into the cell (zzflxn).  Clearly 
    14711384 
    1472 \begin{equation} \label{dyn_wd_zzflx_p_n_1} 
    1473 \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} . 
    14741388\end{equation} 
    14751389 
     
    14821396$\mathrm{zcoef}_{i,j}^{(m)}$ such that: 
    14831397 
    1484 \begin{equation} \label{dyn_wd_continuity_coef} 
    1485 \begin{split} 
    1486 \mathrm{zzflxp}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxp}^{(0)}_{i,j} \\ 
    1487 \mathrm{zzflxn}^{(m)}_{i,j} =& \mathrm{zcoef}_{i,j}^{(m)} \mathrm{zzflxn}^{(0)}_{i,j} 
    1488 \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} 
    14891404\end{equation} 
    14901405 
     
    14941409The iteration is initialised by setting 
    14951410 
    1496 \begin{equation} \label{dyn_wd_zzflx_initial} 
    1497 \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} . 
    14981414\end{equation} 
    14991415 
    15001416The fluxes out of cell $(i,j)$ are updated at the $m+1$th iteration if the depth of the 
    15011417cell on timestep $t_e$, namely $h_{i,j}(t_e)$, is less than the total flux out of the cell 
    1502 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 
    15031419condition is 
    15041420 
    1505 \begin{equation} \label{dyn_wd_continuity_if} 
    1506 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} ) . 
    1507 \end{equation} 
    1508  
    1509 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 
    15101427outward flux that can be allowed and still maintain the minimum wet depth: 
    15111428 
    1512 \begin{equation} \label{dyn_wd_max_flux} 
    1513 \begin{split} 
    1514 \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{]} \\ 
    1515 \phantom{[} & -  \mathrm{zzflxn}^{(m)}_{i,j} \Big] 
    1516 \end{split} 
     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} 
    15171435\end{equation} 
    15181436 
    15191437Note a small tolerance ($\mathrm{rn\_wdmin2}$) has been introduced here {\itshape [Q: Why is 
    1520 this necessary/desirable?]}. Substituting from (\ref{dyn_wd_continuity_coef}) gives an 
     1438this necessary/desirable?]}. Substituting from (\autoref{eq:DYN_wd_continuity_coef}) gives an 
    15211439expression for the coefficient needed to multiply the outward flux at this cell in order 
    15221440to avoid drying. 
    15231441 
    1524 \begin{equation} \label{dyn_wd_continuity_nxtcoef} 
    1525 \begin{split} 
    1526 \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{]} \\ 
    1527 \phantom{[} & -  \mathrm{zzflxn}^{(m)}_{i,j} \Big] \frac{1}{ \mathrm{zzflxp}^{(0)}_{i,j} }  
    1528 \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} 
    15291448\end{equation} 
    15301449 
     
    15411460directional limiter does. 
    15421461 
    1543  
    1544 %---------------------------------------------------------------------------------------- 
    15451462%      Surface pressure gradients 
    1546 %---------------------------------------------------------------------------------------- 
    1547 \subsubsection[Modification of surface pressure gradients (\textit{dynhpg.F90})] 
    1548 {Modification of surface pressure gradients (\mdl{dynhpg})} 
    1549 \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} 
    15501466 
    15511467At ``dry'' points the water depth is usually close to $\mathrm{rn\_wdmin1}$. If the 
     
    15601476neighbouring $(i+1,j)$ and $(i,j)$ tracer points.  zcpx is calculated using two logicals 
    15611477variables, $\mathrm{ll\_tmp1}$ and $\mathrm{ll\_tmp2}$ which are evaluated for each grid 
    1562 column.  The three possible combinations are illustrated in figure \ref{Fig_WAD_dynhpg}. 
    1563  
    1564 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1565 \begin{figure}[!ht] \begin{center} 
    1566 \includegraphics[width=\textwidth]{Fig_WAD_dynhpg} 
    1567 \caption{ \label{Fig_WAD_dynhpg} 
    1568 Illustrations of the three possible combinations of the logical variables controlling the 
    1569 limiting of the horizontal pressure gradient in wetting and drying regimes} 
    1570 \end{center}\end{figure} 
    1571 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     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} 
    15721489 
    15731490The first logical, $\mathrm{ll\_tmp1}$, is set to true if and only if the water depth at 
     
    15761493of the topography at the two points: 
    15771494 
    1578 \begin{equation} \label{dyn_ll_tmp1} 
    1579 \begin{split} 
    1580 \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))} > \\ 
    15811499                     & \quad \mathrm{MAX(-ht\_wd(ji,jj), -ht\_wd(ji+1,jj))\  .and.} \\ 
    1582 & \mathrm{MAX(sshn(ji,jj) + ht\_wd(ji,jj),} \\ 
    1583 & \mathrm{\phantom{MAX(}sshn(ji+1,jj) + ht\_wd(ji+1,jj))} >\\ 
    1584 & \quad\quad\mathrm{rn\_wdmin1 + rn\_wdmin2 } 
    1585 \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} 
    15861504\end{equation} 
    15871505 
     
    15901508at the two points plus $\mathrm{rn\_wdmin1} + \mathrm{rn\_wdmin2}$ 
    15911509 
    1592 \begin{equation} \label{dyn_ll_tmp2} 
    1593 \begin{split} 
    1594 \mathrm{ ll\_tmp2 } = & \mathrm{( ABS( sshn(ji,jj) - sshn(ji+1,jj) ) > 1.E-12 )\ .AND.}\\ 
    1595 & \mathrm{( MAX(sshn(ji,jj), sshn(ji+1,jj)) > } \\ 
    1596 & \mathrm{\phantom{(} MAX(-ht\_wd(ji,jj), -ht\_wd(ji+1,jj)) + rn\_wdmin1 + rn\_wdmin2}) . 
    1597 \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} 
    15981517\end{equation} 
    15991518 
     
    16111530conditions. 
    16121531 
    1613 \subsubsection[Additional considerations (\textit{usrdef\_zgr.F90})] 
    1614 {Additional considerations (\mdl{usrdef\_zgr})} 
    1615 \label{subsubsec:WAD_additional} 
     1532%% ================================================================================================= 
     1533\subsubsection[Additional considerations (\textit{usrdef\_zgr.F90})]{Additional considerations (\mdl{usrdef\_zgr})} 
     1534\label{subsec:DYN_WAD_additional} 
    16161535 
    16171536In the very shallow water where wetting and drying occurs the parametrisation of 
     
    16231542in uncoupled integrations the net surface heat fluxes need to be appropriately limited. 
    16241543 
    1625 %---------------------------------------------------------------------------------------- 
    16261544%      The WAD test cases 
    1627 %---------------------------------------------------------------------------------------- 
    1628 \subsection[The WAD test cases (\textit{usrdef\_zgr.F90})] 
    1629 {The WAD test cases (\mdl{usrdef\_zgr})} 
    1630 \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} 
    16311548 
    16321549See the WAD tests MY\_DOC documention for details of the WAD test cases. 
    16331550 
    1634  
    1635  
    1636 % ================================================================ 
    1637 % Time evolution term  
    1638 % ================================================================ 
    1639 \section[Time evolution term (\textit{dynnxt.F90})] 
    1640 {Time evolution term (\protect\mdl{dynnxt})} 
     1551%% ================================================================================================= 
     1552\section[Time evolution term (\textit{dynnxt.F90})]{Time evolution term (\protect\mdl{dynnxt})} 
    16411553\label{sec:DYN_nxt} 
    16421554 
    1643 %----------------------------------------------namdom---------------------------------------------------- 
    1644  
    1645 \nlst{namdom}  
    1646 %------------------------------------------------------------------------------------------------------------- 
    1647  
    1648 Options are defined through the \ngn{namdom} namelist variables. 
     1555Options are defined through the \nam{dom}{dom} namelist variables. 
    16491556The general framework for dynamics time stepping is a leap-frog scheme, 
    1650 \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}). 
    16511558The scheme is applied to the velocity, except when 
    16521559using the flux form of momentum advection (cf. \autoref{sec:DYN_adv_cor_flux}) 
    1653 in the variable volume case (\key{vvl} defined), 
    1654 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}) 
    16551562 
    16561563$\bullet$ vector invariant form or linear free surface 
    1657 (\np{ln\_dynhpg\_vec}\forcode{ = .true.} ; \key{vvl} not defined): 
    1658 \[ 
    1659   % \label{eq:dynnxt_vec} 
     1564(\np[=.true.]{ln_dynhpg_vec}{ln\_dynhpg\_vec} ; \texttt{vvl?} not defined): 
     1565\[ 
     1566  % \label{eq:DYN_nxt_vec} 
    16601567  \left\{ 
    16611568    \begin{aligned} 
     
    16671574 
    16681575$\bullet$ flux form and nonlinear free surface 
    1669 (\np{ln\_dynhpg\_vec}\forcode{ = .false.} ; \key{vvl} defined): 
    1670 \[ 
    1671   % \label{eq:dynnxt_flux} 
     1576(\np[=.false.]{ln_dynhpg_vec}{ln\_dynhpg\_vec} ; \texttt{vvl?} defined): 
     1577\[ 
     1578  % \label{eq:DYN_nxt_flux} 
    16721579  \left\{ 
    16731580    \begin{aligned} 
     
    16801587where RHS is the right hand side of the momentum equation, 
    16811588the subscript $f$ denotes filtered values and $\gamma$ is the Asselin coefficient. 
    1682 $\gamma$ is initialized as \np{nn\_atfp} (namelist parameter). 
    1683 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}. 
    16841591In both cases, the modified Asselin filter is not applied since perfect conservation is not an issue for 
    16851592the momentum equations. 
     
    16891596and only array swapping and Asselin filtering is done in \mdl{dynnxt}. 
    16901597 
    1691 % ================================================================ 
    1692 \biblio 
    1693  
    1694 \pindex 
     1598\subinc{\input{../../global/epilogue}} 
    16951599 
    16961600\end{document} 
  • NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_LBC.tex

    r11179 r12149  
    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 (\texttt{rn\_shlat})] 
    20 {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})} 
    2131\label{sec:LBC_coast} 
    22 %--------------------------------------------nam_lbc------------------------------------------------------- 
    23  
    24 \nlst{namlbc}  
    25 %-------------------------------------------------------------------------------------------------------------- 
    26  
    27 %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}).  
    28  
    29 %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}. 
    30  
    31 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. 
    3255The discrete representation of a domain with complex boundaries (coastlines and bottom topography) leads to 
    3356arrays that include large portions where a computation is not required as the model variables remain at zero. 
     
    4164Since most of the boundary conditions consist of a zero flux across the solid boundaries, 
    4265they can be simply applied by multiplying variables by the correct mask arrays, 
    43 \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. 
    4467For example, the heat flux in the \textbf{i}-direction is evaluated at $u$-points. 
    4568Evaluating this quantity as, 
    4669 
    4770\[ 
    48   % \label{eq:lbc_aaaa} 
     71  % \label{eq:LBC_aaaa} 
    4972  \frac{A^{lT} }{e_1 }\frac{\partial T}{\partial i}\equiv \frac{A_u^{lT} 
    5073  }{e_{1u} } \; \delta_{i+1 / 2} \left[ T \right]\;\;mask_u 
     
    5275(where mask$_{u}$ is the mask array at a $u$-point) ensures that the heat flux is zero inside land and 
    5376at the boundaries, since mask$_{u}$ is zero at solid boundaries which in this case are defined at $u$-points 
    54 (normal velocity $u$ remains zero at the coast) (\autoref{fig:LBC_uv}).  
    55  
    56 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     77(normal velocity $u$ remains zero at the coast) (\autoref{fig:LBC_uv}). 
     78 
    5779\begin{figure}[!t] 
    58   \begin{center} 
    59     \includegraphics[width=\textwidth]{Fig_LBC_uv} 
    60     \caption{ 
    61       \protect\label{fig:LBC_uv} 
    62       Lateral boundary (thick line) at T-level. 
    63       The velocity normal to the boundary is set to zero. 
    64     } 
    65   \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} 
    6686\end{figure} 
    67 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    6887 
    6988For momentum the situation is a bit more complex as two boundary conditions must be provided along the coast 
     
    7998and is required in order to compute the vorticity at the coast. 
    8099Four different types of lateral boundary condition are available, 
    81 controlled by the value of the \np{rn\_shlat} namelist parameter 
     100controlled by the value of the \np{rn_shlat}{rn\_shlat} namelist parameter 
    82101(The value of the mask$_{f}$ array along the coastline is set equal to this parameter). 
    83102These are: 
    84103 
    85 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    86104\begin{figure}[!p] 
    87   \begin{center} 
    88     \includegraphics[width=\textwidth]{Fig_LBC_shlat} 
    89     \caption{ 
    90       \protect\label{fig:LBC_shlat} 
    91       lateral boundary condition 
    92       (a) free-slip ($rn\_shlat=0$); 
    93       (b) no-slip ($rn\_shlat=2$); 
    94       (c) "partial" free-slip ($0<rn\_shlat<2$) and 
    95       (d) "strong" no-slip ($2<rn\_shlat$). 
    96       Implied "ghost" velocity inside land area is display in grey. 
    97     } 
    98   \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} 
    99115\end{figure} 
    100 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    101116 
    102117\begin{description} 
    103118 
    104 \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 
    105120  the coastline is equal to the offshore velocity, 
    106   \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, 
    107122  so the vorticity: mask$_{f}$ array is set to zero inside the land and just at the coast 
    108123  (\autoref{fig:LBC_shlat}-a). 
    109124 
    110 \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. 
    111126  Assuming that the tangential velocity decreases linearly from 
    112127  the closest ocean velocity grid point to the coastline, 
     
    114129  the closest ocean velocity gridpoint were of the same magnitude but in the opposite direction 
    115130  (\autoref{fig:LBC_shlat}-b). 
    116   Therefore, the vorticity along the coastlines is given by:  
     131  Therefore, the vorticity along the coastlines is given by: 
    117132 
    118133  \[ 
     
    123138  the no-slip boundary condition, simply by multiplying it by the mask$_{f}$ : 
    124139  \[ 
    125     % \label{eq:lbc_bbbb} 
     140    % \label{eq:LBC_bbbb} 
    126141    \zeta \equiv \frac{1}{e_{1f} {\kern 1pt}e_{2f} }\left( {\delta_{i+1/2} 
    127142        \left[ {e_{2v} \,v} \right]-\delta_{j+1/2} \left[ {e_{1u} \,u} \right]} 
     
    129144  \] 
    130145 
    131 \item["partial" free-slip boundary condition (0$<$\np{rn\_shlat}$<$2):] the tangential velocity at 
    132   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 
    133148  not strong enough to make the tangential velocity at the coast vanish (\autoref{fig:LBC_shlat}-c). 
    134149  This can be selected by providing a value of mask$_{f}$ strictly inbetween $0$ and $2$. 
    135150 
    136 \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 
    137152  be smaller than half the grid size (\autoref{fig:LBC_shlat}-d). 
    138153  The friction is thus larger than in the no-slip case. 
     
    140155\end{description} 
    141156 
    142 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), 
    143158the lateral boundary condition on tangential velocity is of much less importance as 
    144159it is only applied next to the coast where the minimum water depth can be quite shallow. 
    145160 
    146  
    147 % ================================================================ 
    148 % Boundary Condition around the Model Domain 
    149 % ================================================================ 
    150 \section[Model domain boundary condition (\texttt{jperio})] 
    151 {Model domain boundary condition (\protect\np{jperio})} 
     161%% ================================================================================================= 
     162\section[Model domain boundary condition (\forcode{jperio})]{Model domain boundary condition (\protect\jp{jperio})} 
    152163\label{sec:LBC_jperio} 
    153164 
     
    155166closed, cyclic east-west, cyclic north-south, a north-fold, and combination closed-north fold or 
    156167bi-cyclic east-west and north-fold. 
    157 The north-fold boundary condition is associated with the 3-pole ORCA mesh.  
    158  
    159 % ------------------------------------------------------------------------------------------------------------- 
    160 %        Closed, cyclic (\np{jperio}\forcode{ = 0..2})  
    161 % ------------------------------------------------------------------------------------------------------------- 
    162 \subsection[Closed, cyclic (\forcode{jperio = [0127]})] 
    163 {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})} 
    164172\label{subsec:LBC_jperio012} 
    165173 
    166174The choice of closed or cyclic model domain boundary condition is made by 
    167 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}. 
    168176Each time such a boundary condition is needed, it is set by a call to routine \mdl{lbclnk}. 
    169177The computation of momentum and tracer trends proceeds from $i=2$ to $i=jpi-1$ and from $j=2$ to $j=jpj-1$, 
    170 \ie in the model interior. 
     178\ie\ in the model interior. 
    171179To choose a lateral model boundary condition is to specify the first and last rows and columns of 
    172 the model variables.  
     180the model variables. 
    173181 
    174182\begin{description} 
    175183 
    176 \item[For closed boundary (\np{jperio}\forcode{ = 0})], 
    177   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: 
    178185  first and last rows and columns are set to zero. 
    179186 
    180 \item[For cyclic east-west boundary (\np{jperio}\forcode{ = 1})], 
    181   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 
    182188  the value of the last-but-one column and the last column to the value of the second one 
    183189  (\autoref{fig:LBC_jperio}-a). 
    184190  Whatever flows out of the eastern (western) end of the basin enters the western (eastern) end. 
    185191 
    186 \item[For cyclic north-south boundary (\np{jperio}\forcode{ = 2})], 
    187   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 
    188193  the value of the last-but-one row and the last row to the value of the second one 
    189194  (\autoref{fig:LBC_jperio}-a). 
    190195  Whatever flows out of the northern (southern) end of the basin enters the southern (northern) end. 
    191196 
    192 \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. 
    193198 
    194199\end{description} 
    195200 
    196 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    197201\begin{figure}[!t] 
    198   \begin{center} 
    199     \includegraphics[width=\textwidth]{Fig_LBC_jperio} 
    200     \caption{ 
    201       \protect\label{fig:LBC_jperio} 
    202       setting of (a) east-west cyclic  (b) symmetric across the equator boundary conditions. 
    203     } 
    204   \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} 
    205207\end{figure} 
    206 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    207  
    208 % ------------------------------------------------------------------------------------------------------------- 
    209 %        North fold (\textit{jperio = 3 }to $6)$  
    210 % ------------------------------------------------------------------------------------------------------------- 
    211 \subsection[North-fold (\forcode{jperio = [3-6]})] 
    212 {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})} 
    213211\label{subsec:LBC_north_fold} 
    214212 
    215213The north fold boundary condition has been introduced in order to handle the north boundary of 
    216214a three-polar ORCA grid. 
    217 Such a grid has two poles in the northern hemisphere (\autoref{fig:MISC_ORCA_msh}, 
    218 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}. 
    219217Further information can be found in \mdl{lbcnfd} module which applies the north fold boundary condition. 
    220218 
    221 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    222219\begin{figure}[!t] 
    223   \begin{center} 
    224     \includegraphics[width=\textwidth]{Fig_North_Fold_T} 
    225     \caption{ 
    226       \protect\label{fig:North_Fold_T} 
    227       North fold boundary with a $T$-point pivot and cyclic east-west boundary condition ($jperio=4$), 
    228       as used in ORCA 2, 1/4, and 1/12. 
    229       Pink shaded area corresponds to the inner domain mask (see text). 
    230     } 
    231   \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} 
    232227\end{figure} 
    233 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    234  
    235 % ==================================================================== 
    236 % Exchange with neighbouring processors  
    237 % ==================================================================== 
    238 \section[Exchange with neighbouring processors (\textit{lbclnk.F90}, \textit{lib\_mpp.F90})] 
    239 {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})} 
    240231\label{sec:LBC_mpp} 
    241232 
     233\begin{listing} 
     234  \nlst{nammpp} 
     235  \caption{\forcode{&nammpp}} 
     236  \label{lst:nammpp} 
     237\end{listing} 
     238 
    242239For massively parallel processing (mpp), a domain decomposition method is used. 
    243 The basic idea of the method is to split the large computation domain of a numerical experiment into 
    244 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. 
    245242Each processor has its own local memory and computes the model equation over a subdomain of the whole model domain. 
    246 The subdomain boundary conditions are specified through communications between processors which 
    247 are organized by explicit statements (message passing method). 
    248  
    249 A big advantage is that the method does not need many modifications of the initial \fortran code. 
    250 From the modeller's point of view, each sub domain running on a processor is identical to the "mono-domain" code. 
    251 In addition, the programmer manages the communications between subdomains, 
    252 and the code is faster when the number of processors is increased. 
    253 The porting of OPA code on an iPSC860 was achieved during Guyon's PhD [Guyon et al. 1994, 1995] 
    254 in collaboration with CETIIS and ONERA. 
    255 The implementation in the operational context and the studies of performance on 
    256 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). 
    257245The present implementation is largely inspired by Guyon's work [Guyon 1995]. 
    258246 
     
    261249depend at the very most on one neighbouring point. 
    262250The only non-local computations concern the vertical physics 
    263 (implicit diffusion, turbulent closure scheme, ...) (delocalization over the whole water column), 
    264 and the solving of the elliptic equation associated with the surface pressure gradient computation 
    265 (delocalization over the whole horizontal domain). 
     251(implicit diffusion, turbulent closure scheme, ...). 
    266252Therefore, a pencil strategy is used for the data sub-structuration: 
    267253the 3D initial domain is laid out on local processor memories following a 2D horizontal topological splitting. 
     
    272258After a computation, a communication phase starts: 
    273259each processor sends to its neighbouring processors the update values of the points corresponding to 
    274 the interior overlapping area to its neighbouring sub-domain (\ie the innermost of the two overlapping rows). 
    275 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. 
    276265The data exchanges between processors are required at the very place where 
    277266lateral domain boundary conditions are set in the mono-domain computation: 
    278267the \rou{lbc\_lnk} routine (found in \mdl{lbclnk} module) which manages such conditions is interfaced with 
    279 routines found in \mdl{lib\_mpp} module when running on an MPP computer (\ie when \key{mpp\_mpi} defined). 
    280 It has to be pointed out that when using the MPP version of the model, 
    281 the east-west cyclic boundary condition is done implicitly, 
    282 whilst the south-symmetric boundary condition option is not available. 
    283  
    284 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     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 
    285272\begin{figure}[!t] 
    286   \begin{center} 
    287     \includegraphics[width=\textwidth]{Fig_mpp} 
    288     \caption{ 
    289       \protect\label{fig:mpp} 
    290       Positioning of a sub-domain when massively parallel processing is used. 
    291     } 
    292   \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} 
    293277\end{figure} 
    294 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    295  
    296 In the standard version of \NEMO, the splitting is regular and arithmetic. 
    297 The i-axis is divided by \jp{jpni} and 
    298 the j-axis by \jp{jpnj} for a number of processors \jp{jpnij} most often equal to $jpni \times jpnj$ 
    299 (parameters set in  \ngn{nammpp} namelist). 
    300 Each processor is independent and without message passing or synchronous process, 
    301 programs run alone and access just its own local memory. 
    302 For this reason, the main model dimensions are now the local dimensions of the subdomain (pencil) that 
    303 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}. 
    304290These dimensions include the internal domain and the overlapping rows. 
    305 The number of rows to exchange (known as the halo) is usually set to one (\jp{jpreci}=1, in \mdl{par\_oce}). 
    306 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}. 
    307294The 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: 
    308304\[ 
    309   jpi = ( jpiglo-2*jpreci + (jpni-1) ) / jpni + 2*jpreci 
    310   jpj = ( jpjglo-2*jprecj + (jpnj-1) ) / jpnj + 2*jprecj 
    311 \] 
    312 where \jp{jpni}, \jp{jpnj} are the number of processors following the i- and j-axis. 
    313  
    314 One also defines variables nldi and nlei which correspond to the internal domain bounds,  
    315 and the variables nimpp and njmpp which are the position of the (1,1) grid-point in the global domain.  
    316 An element of $T_{l}$, a local array (subdomain) corresponds to an element of $T_{g}$, 
    317 a global array (whole domain) by the relationship:  
    318 \[ 
    319   % \label{eq:lbc_nimpp} 
     305  % \label{eq:LBC_nimpp} 
    320306  T_{g} (i+nimpp-1,j+njmpp-1,k) = T_{l} (i,j,k), 
    321307\] 
    322 with  $1 \leq i \leq jpi$, $1  \leq j \leq jpj $ , and  $1  \leq k \leq jpk$. 
    323  
    324 Processors are numbered from 0 to $jpnij-1$, the number is saved in the variable nproc. 
    325 In the standard version, a processor has no more than 
    326 four neighbouring processors named nono (for north), noea (east), noso (south) and nowe (west) and 
    327 two variables, nbondi and nbondj, indicate the relative position of the processor: 
    328 \begin{itemize} 
    329 \item       nbondi = -1    an east neighbour, no west processor, 
    330 \item       nbondi =  0 an east neighbour, a west neighbour, 
    331 \item       nbondi =  1    no east processor, a west neighbour, 
    332 \item       nbondi =  2    no splitting following the i-axis. 
    333 \end{itemize} 
    334 During the simulation, processors exchange data with their neighbours. 
    335 If there is effectively a neighbour, the processor receives variables from this processor on its overlapping row, 
    336 and sends the data issued from internal domain corresponding to the overlapping row of the other processor. 
    337  
    338  
    339 The \NEMO model computes equation terms with the help of mask arrays (0 on land points and 1 on sea points). 
    340 It is easily readable and very efficient in the context of a computer with vectorial architecture. 
    341 However, in the case of a scalar processor, computations over the land regions become more expensive in 
    342 terms of CPU time.  
    343 It is worse when we use a complex configuration with a realistic bathymetry like the global ocean where 
    344 more than 50 \% of points are land points. 
    345 For this reason, a pre-processing tool can be used to choose the mpp domain decomposition with a maximum number of 
    346 only land points processors, which can then be eliminated (\autoref{fig:mppini2}) 
    347 (For example, the mpp\_optimiz tools, available from the DRAKKAR web site). 
    348 This optimisation is dependent on the specific bathymetry employed. 
    349 The user then chooses optimal parameters \jp{jpni}, \jp{jpnj} and \jp{jpnij} with $jpnij < jpni \times jpnj$, 
    350 leading to the elimination of $jpni \times jpnj - jpnij$ land processors. 
    351 When those parameters are specified in \ngn{nammpp} namelist, 
    352 the algorithm in the \rou{inimpp2} routine sets each processor's parameters (nbound, nono, noea,...) so that 
    353 the land-only processors are not taken into account. 
    354  
    355 \gmcomment{Note that the inimpp2 routine is general so that the original inimpp  
    356 routine should be suppressed from the code.} 
    357  
    358 When land processors are eliminated, 
    359 the value corresponding to these locations in the model output files is undefined. 
    360 Note that this is a problem for the meshmask file which requires to be defined over the whole domain. 
    361 Therefore, user should not eliminate land processors when creating a meshmask file 
    362 (\ie when setting a non-zero value to \np{nn\_msh}). 
    363  
    364 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     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 
    365325\begin{figure}[!ht] 
    366   \begin{center} 
    367     \includegraphics[width=\textwidth]{Fig_mppini2} 
    368     \caption { 
    369       \protect\label{fig:mppini2} 
    370       Example of Atlantic domain defined for the CLIPPER projet. 
    371       Initial grid is composed of 773 x 1236 horizontal points. 
    372       (a) the domain is split onto 9 \time 20 subdomains (jpni=9, jpnj=20). 
    373       52 subdomains are land areas. 
    374       (b) 52 subdomains are eliminated (white rectangles) and 
    375       the resulting number of processors really used during the computation is jpnij=128. 
    376     } 
    377   \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} 
    378336\end{figure} 
    379 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    380  
    381  
    382 % ==================================================================== 
    383 % Unstructured open boundaries BDY  
    384 % ==================================================================== 
     337 
     338%% ================================================================================================= 
    385339\section{Unstructured open boundary conditions (BDY)} 
    386340\label{sec:LBC_bdy} 
    387341 
    388 %-----------------------------------------nambdy-------------------------------------------- 
    389  
    390 \nlst{nambdy}  
    391 %----------------------------------------------------------------------------------------------- 
    392 %-----------------------------------------nambdy_dta-------------------------------------------- 
    393  
    394 \nlst{nambdy_dta}  
    395 %----------------------------------------------------------------------------------------------- 
    396  
    397 Options are defined through the \ngn{nambdy} \ngn{nambdy\_dta} namelist variables. 
    398 The BDY module is the core implementation of open boundary conditions for regional configurations on  
    399 temperature, salinity, barotropic and baroclinic velocities, as well as ice concentration, ice and snow thicknesses). 
    400  
    401 The BDY module was modelled on the OBC module (see NEMO 3.4) and shares many features and 
     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 
    402359a similar coding structure \citep{chanut_rpt05}. 
    403360The specification of the location of the open boundary is completely flexible and 
    404 allows for example the open boundary to follow an isobath or other irregular contour.  
    405 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. 
    406363See the section on the Input Boundary Data Files for details. 
    407364 
    408 %---------------------------------------------- 
     365%% ================================================================================================= 
    409366\subsection{Namelists} 
    410 \label{subsec:BDY_namelist} 
    411  
    412 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} . 
    413370It is possible to define more than one boundary ``set'' and apply different boundary conditions to each set. 
    414 The number of boundary sets is defined by \np{nb\_bdy}. 
    415 Each boundary set may be defined as a set of straight line segments in a namelist 
    416 (\np{ln\_coords\_file}\forcode{ = .false.}) or read in from a file (\np{ln\_coords\_file}\forcode{ = .true.}). 
    417 If the set is defined in a namelist, then the namelists \ngn{nambdy\_index} must be included separately, one for each set. 
    418 If the set is defined by a file, then a ``\ifile{coordinates.bdy}'' file must be provided. 
    419 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. 
    420375In the example above, there are two boundary sets, the first of which is defined via a file and 
    421 the second is defined in a namelist. 
    422 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}. 
    423378 
    424379For each boundary set a boundary condition has to be chosen for the barotropic solution 
    425 (``u2d'':sea-surface height and barotropic velocities), for the baroclinic velocities (``u3d''),  
    426 for the active tracers \footnote{The BDY module does not deal with passive tracers at this version} (``tra''), and sea-ice (``ice''). 
    427 For each set of variables there is a choice of algorithm and a choice for the data, 
    428 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).\\ 
    429383 
    430384The choice of algorithm is currently as follows: 
    431385 
    432386\begin{description} 
    433 \item[\forcode{'none'}:] No boundary condition applied. 
     387\item [\forcode{'none'}:] No boundary condition applied. 
    434388  So the solution will ``see'' the land points around the edge of the edge of the domain. 
    435 \item[\forcode{'specified'}:] Specified boundary condition applied (only available for baroclinic velocity and tracer variables). 
    436 \item[\forcode{'neumann'}:] Value at the boundary are duplicated (No gradient). Only available for baroclinic velocity and tracer variables. 
    437 \item[\forcode{'frs'}:] Flow Relaxation Scheme (FRS) available for all variables. 
    438 \item[\forcode{'Orlanski'}:] Orlanski radiation scheme (fully oblique) for barotropic, baroclinic and tracer variables.  
    439 \item[\forcode{'Orlanski_npo'}:] Orlanski radiation scheme for barotropic, baroclinic and tracer variables.  
    440 \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. 
    441395\end{description} 
    442396 
    443 The main choice for the boundary data is to use initial conditions as boundary data 
    444 (\np{nn\_tra\_dta}\forcode{ = 0}) or to use external data from a file (\np{nn\_tra\_dta}\forcode{ = 1}). 
    445 In case the 3d velocity data contain the total velocity (ie, baroclinic and barotropic velocity),  
    446 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} 
    447401For the barotropic solution there is also the option to use tidal harmonic forcing either by 
    448 itself (\np{nn\_dyn2d\_dta}\forcode{ = 2}) or in addition to other external data (\np{nn\_dyn2d\_dta}\forcode{ = 3}).\\ 
    449 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}.  
    450  
    451 If external boundary data is required then the \ngn{nambdy\_dta} namelist must be defined. 
    452 One \ngn{nambdy\_dta} namelist is required for each boundary set in the order in which 
    453 the boundary sets are defined in nambdy. 
    454 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  
    455 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). 
    456409The boundary data is read in using the fldread module, 
    457 so the \ngn{nambdy\_dta} namelist is in the format required for fldread. 
    458 For each variable required, the filename, the frequency of the files and 
    459 the frequency of the data in the files is given. 
    460 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'}.\\ 
    461415 
    462416There is currently an option to vertically interpolate the open boundary data onto the native grid at run-time. 
    463 If \np{nn\_bdy\_jpk} $< -1$, it is assumed that the lateral boundary data are already on the native grid.  
    464 However, if \np{nn\_bdy\_jpk} is set to the number of vertical levels present in the boundary data,  
    465 a bilinear interpolation onto the native grid will be triggered at runtime.  
    466 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.  
    467 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, 
    468422the latter used to make any adjustment to the velocity fields due to differences in the total water depths between the two vertical grids.\\ 
    469423 
    470 In the example namelists given, two boundary sets are defined. 
     424In the example of given namelists, two boundary sets are defined. 
    471425The first set is defined via a file and applies FRS conditions to temperature and salinity and 
    472426Flather conditions to the barotropic variables. No condition specified for the baroclinic velocity and sea-ice. 
     
    474428Tidal harmonic forcing is also used. 
    475429The second set is defined in a namelist. 
    476 FRS conditions are applied on temperature and salinity and climatological data is read from initial condition files.  
    477  
    478 %---------------------------------------------- 
     430FRS conditions are applied on temperature and salinity and climatological data is read from initial condition files. 
     431 
     432%% ================================================================================================= 
    479433\subsection{Flow relaxation scheme} 
    480 \label{subsec:BDY_FRS_scheme} 
     434\label{subsec:LBC_bdy_FRS_scheme} 
    481435 
    482436The Flow Relaxation Scheme (FRS) \citep{davies_QJRMS76,engedahl_T95}, 
     
    485439Given a model prognostic variable $\Phi$ 
    486440\[ 
    487   % \label{eq:bdy_frs1} 
     441  % \label{eq:LBC_bdy_frs1} 
    488442  \Phi(d) = \alpha(d)\Phi_{e}(d) + (1-\alpha(d))\Phi_{m}(d)\;\;\;\;\; d=1,N 
    489443\] 
     
    494448the prognostic equation for $\Phi$ of the form: 
    495449\[ 
    496   % \label{eq:bdy_frs2} 
     450  % \label{eq:LBC_bdy_frs2} 
    497451  -\frac{1}{\tau}\left(\Phi - \Phi_{e}\right) 
    498452\] 
    499453where the relaxation time scale $\tau$ is given by a function of $\alpha$ and the model time step $\Delta t$: 
    500454\[ 
    501   % \label{eq:bdy_frs3} 
     455  % \label{eq:LBC_bdy_frs3} 
    502456  \tau = \frac{1-\alpha}{\alpha}  \,\rdt 
    503457\] 
     
    505459is relaxed towards the external conditions over the rest of the FRS zone. 
    506460The application of a relaxation zone helps to prevent spurious reflection of 
    507 outgoing signals from the model boundary.  
     461outgoing signals from the model boundary. 
    508462 
    509463The function $\alpha$ is specified as a $tanh$ function: 
    510464\[ 
    511   % \label{eq:bdy_frs4} 
     465  % \label{eq:LBC_bdy_frs4} 
    512466  \alpha(d) = 1 - \tanh\left(\frac{d-1}{2}\right),       \quad d=1,N 
    513467\] 
    514 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}. 
    515469This is typically set to a value between 8 and 10. 
    516470 
    517 %---------------------------------------------- 
     471%% ================================================================================================= 
    518472\subsection{Flather radiation scheme} 
    519 \label{subsec:BDY_flather_scheme} 
     473\label{subsec:LBC_bdy_flather_scheme} 
    520474 
    521475The \citet{flather_JPO94} scheme is a radiation condition on the normal, 
    522476depth-mean transport across the open boundary. 
    523477It takes the form 
    524 \begin{equation}  \label{eq:bdy_fla1} 
    525 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), 
    526481\end{equation} 
    527482where $U$ is the depth-mean velocity normal to the boundary and $\eta$ is the sea surface height, 
     
    532487the external depth-mean normal velocity, 
    533488plus a correction term that allows gravity waves generated internally to exit the model boundary. 
    534 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, 
    535490so that $\eta_{e}$ is defined on the $T$ points with $nbr=1$ and $\eta$ is defined on the $T$ points with $nbr=2$. 
    536 $U$ and $U_{e}$ are defined on the $U$ or $V$ points with $nbr=1$, \ie between the two $T$ grid points. 
    537  
    538 %---------------------------------------------- 
     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%% ================================================================================================= 
    539494\subsection{Orlanski radiation scheme} 
    540 \label{subsec:BDY_orlanski_scheme} 
     495\label{subsec:LBC_bdy_orlanski_scheme} 
    541496 
    542497The Orlanski scheme is based on the algorithm described by \citep{marchesiello.mcwilliams.ea_OM01}, hereafter MMS. 
     
    544499The adaptive Orlanski condition solves a wave plus relaxation equation at the boundary: 
    545500\begin{equation} 
    546 \frac{\partial\phi}{\partial t} + c_x \frac{\partial\phi}{\partial x} + c_y \frac{\partial\phi}{\partial y} = 
    547                                                 -\frac{1}{\tau}(\phi - \phi^{ext}) 
    548 \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}) 
    549504\end{equation} 
    550505 
     
    552507velocities are diagnosed from the model fields as: 
    553508 
    554 \begin{equation} \label{eq:cx} 
    555 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} 
    556512\end{equation} 
    557513\begin{equation} 
    558 \label{eq:cy} 
    559 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} 
    560516\end{equation} 
    561517 
    562518(As noted by MMS, this is a circular diagnosis of the phase speeds which only makes sense on a discrete grid). 
    563 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$. 
    564520For $c_x$ outward, we have 
    565521 
     
    571527 
    572528\begin{equation} 
    573 \tau = \tau_{in}\,\,\,;\,\,\, c_x = c_y = 0 
    574 \label{eq:tau_in} 
     529  \label{eq:LBC_tau_in} 
     530  \tau = \tau_{in}\,\,\,;\,\,\, c_x = c_y = 0 
    575531\end{equation} 
    576532 
    577 Generally the relaxation time scale at inward propagation points \np{(rn\_time\_dmp}) is set much shorter than the time scale at outward propagation 
    578 points (\np{rn\_time\_dmp\_out}) so that the solution is constrained more strongly by the external data at inward propagation points. 
    579 See \autoref{subsec:BDY_relaxation} for detailed on the spatial shape of the scaling.\\  
    580 The ``normal propagation of oblique radiation'' or NPO approximation (called \forcode{'orlanski_npo'}) involves assuming  
    581 that $c_y$ is zero in equation (\autoref{eq:wave_continuous}), but including 
    582 this term in the denominator of equation (\autoref{eq:cx}). Both versions of the scheme are options in BDY. Equations 
    583 (\autoref{eq:wave_continuous}) - (\autoref{eq:tau_in}) correspond to equations (13) - (15) and (2) - (3) in MMS.\\ 
    584  
    585 %---------------------------------------------- 
     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%% ================================================================================================= 
    586542\subsection{Relaxation at the boundary} 
    587 \label{subsec:BDY_relaxation} 
    588  
    589 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.  
    590 It is control by the namelist parameter \np{ln\_tra\_dmp} and \np{ln\_dyn3d\_dmp} for each boundary set. 
    591  
    592 The relaxation time scale value (\np{rn\_time\_dmp} and \np{rn\_time\_dmp\_out}, $\tau$) are defined at the boundaries itself.  
    593 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$): 
    594550 
    595551\[ 
     
    597553\] 
    598554 
    599 The same scaling is applied in the Orlanski damping.  
    600  
    601 %---------------------------------------------- 
     555The same scaling is applied in the Orlanski damping. 
     556 
     557%% ================================================================================================= 
    602558\subsection{Boundary geometry} 
    603 \label{subsec:BDY_geometry} 
     559\label{subsec:LBC_bdy_geometry} 
    604560 
    605561Each open boundary set is defined as a list of points. 
    606562The information is stored in the arrays $nbi$, $nbj$, and $nbr$ in the $idx\_bdy$ structure. 
    607 The $nbi$ and $nbj$ arrays define the local $(i,j)$ indices of each point in the boundary zone and 
    608 the $nbr$ array defines the discrete distance from the boundary with $nbr=1$ meaning that 
    609 the point is next to the edge of the model domain and $nbr>1$ showing that 
    610 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. 
    611567A set of $nbi$, $nbj$, and $nbr$ arrays is defined for each of the $T$, $U$ and $V$ grids. 
    612 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. 
    613569 
    614570The boundary geometry for each set may be defined in a namelist nambdy\_index or 
    615571by reading in a ``\ifile{coordinates.bdy}'' file. 
    616572The nambdy\_index namelist defines a series of straight-line segments for north, east, south and west boundaries. 
    617 One nambdy\_index namelist bloc is needed for each boundary condition defined by indexes.  
    618 For the northern boundary, \np{nbdysegn} gives the number of segments, 
    619 \np{jpjnob} gives the $j$ index for each segment and \np{jpindt} and 
    620 \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. 
    621577These segments define a list of $T$ grid points along the outermost row of the boundary ($nbr\,=\, 1$). 
    622 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}. 
    623579 
    624580The boundary geometry may also be defined from a ``\ifile{coordinates.bdy}'' file. 
    625 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. 
    626582The file should contain the index arrays for each of the $T$, $U$ and $V$ grids. 
    627583The arrays must be in order of increasing $nbr$. 
     
    629585Typically this file will be used to generate external boundary data via interpolation and so 
    630586will also contain the latitudes and longitudes of each point as shown. 
    631 However, this is not necessary to run the model.  
     587However, this is not necessary to run the model. 
    632588 
    633589For some choices of irregular boundary the model domain may contain areas of ocean which 
    634590are not part of the computational domain. 
    635 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, 
    636592then the areas of ocean outside of this boundary will need to be masked out. 
    637 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. 
    638594Only one mask file is used even if multiple boundary sets are defined. 
    639595 
    640 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    641596\begin{figure}[!t] 
    642   \begin{center} 
    643     \includegraphics[width=\textwidth]{Fig_LBC_bdy_geom} 
    644     \caption { 
    645       \protect\label{fig:LBC_bdy_geom} 
    646       Example of geometry of unstructured open boundary 
    647     } 
    648   \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} 
    649601\end{figure} 
    650 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    651  
    652 %---------------------------------------------- 
     602 
     603%% ================================================================================================= 
    653604\subsection{Input boundary data files} 
    654 \label{subsec:BDY_data} 
     605\label{subsec:LBC_bdy_data} 
    655606 
    656607The data files contain the data arrays in the order in which the points are defined in the $nbi$ and $nbj$ arrays. 
     
    658609a time dimension; 
    659610$xb$ which is the index of the boundary data point in the horizontal; 
    660 and $yb$ which is a degenerate dimension of 1 to enable the file to be read by the standard NEMO I/O routines. 
    661 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. 
    662613 
    663614From Version 3.4 there are new restrictions on the order in which the boundary points are defined 
     
    670621\item All the data for a particular boundary set must be in the same order. 
    671622  (Prior to 3.4 it was possible to define barotropic data in a different order to 
    672   the data for tracers and baroclinic velocities).  
     623  the data for tracers and baroclinic velocities). 
    673624\end{enumerate} 
    674625 
    675626These restrictions mean that data files used with versions of the 
    676627model prior to Version 3.4 may not work with Version 3.4 onwards. 
    677 A \fortran utility {\itshape bdy\_reorder} exists in the TOOLS directory which 
     628A \fortran\ utility {\itshape bdy\_reorder} exists in the TOOLS directory which 
    678629will re-order the data in old BDY data files. 
    679630 
    680 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    681631\begin{figure}[!t] 
    682   \begin{center} 
    683     \includegraphics[width=\textwidth]{Fig_LBC_nc_header} 
    684     \caption { 
    685       \protect\label{fig:LBC_nc_header} 
    686       Example of the header for a \protect\ifile{coordinates.bdy} file 
    687     } 
    688   \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} 
    689637\end{figure} 
    690 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    691  
    692 %---------------------------------------------- 
     638 
     639%% ================================================================================================= 
    693640\subsection{Volume correction} 
    694 \label{subsec:BDY_vol_corr} 
     641\label{subsec:LBC_bdy_vol_corr} 
    695642 
    696643There is an option to force the total volume in the regional model to be constant. 
    697 This is controlled  by the \np{ln\_vol} parameter in the namelist. 
    698 A value of \np{ln\_vol}\forcode{ = .false.} indicates that this option is not used. 
    699 Two options to control the volume are available (\np{nn\_volctl}).  
    700 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 
    701648each timestep to ensure that the integrated volume flow through the boundary is zero. 
    702 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 
    703650the timestep includes the change due to the freshwater flux across the surface and 
    704651the correction velocity corrects for this as well. 
     
    707654applied to all boundaries at once. 
    708655 
    709 %---------------------------------------------- 
     656%% ================================================================================================= 
    710657\subsection{Tidal harmonic forcing} 
    711 \label{subsec:BDY_tides} 
    712  
    713 %-----------------------------------------nambdy_tide-------------------------------------------- 
    714  
    715 \nlst{nambdy_tide}  
    716 %----------------------------------------------------------------------------------------------- 
     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} 
    717665 
    718666Tidal forcing at open boundaries requires the activation of surface 
    719 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 
    720668\forcode{.true.} and the required constituents need to be activated by 
    721 including their names in the \np{cname} array; see 
     669including their names in the \np{clname}{clname} array; see 
    722670\autoref{sec:SBC_tide}). Specific options related to the reading in of 
    723671the complex harmonic amplitudes of elevation (SSH) and barotropic 
    724672velocity (u,v) at open boundaries are defined through the 
    725 \ngn{nambdy\_tide} namelist parameters.\\ 
     673\nam{bdy_tide}{bdy\_tide} namelist parameters.\\ 
    726674 
    727675The tidal harmonic data at open boundaries can be specified in two 
    728676different ways, either on a two-dimensional grid covering the entire 
    729677model domain or along open boundary segments; these two variants can 
    730 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 
    731679\forcode{.false.}, respectively. In either case, the real and 
    732680imaginary parts of SSH and the two barotropic velocity components for 
     
    734682separately: when two-dimensional data is used, variables 
    735683\textit{tcname\_z1} and \textit{tcname\_z2} for real and imaginary SSH, 
    736 respectively, are expected in input file \np{filtide} with suffix 
     684respectively, are expected in input file \np{filtide}{filtide} with suffix 
    737685\ifile{\_grid\_T}, variables \textit{tcname\_u1} and 
    738686\textit{tcname\_u2} for real and imaginary u, respectively, are 
    739 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 
    740688\textit{tcname\_v1} and \textit{tcname\_v2} for real and imaginary v, 
    741 respectively, are expected in input file \np{filtide} with suffix 
     689respectively, are expected in input file \np{filtide}{filtide} with suffix 
    742690\ifile{\_grid\_V}; when data along open boundary segments is used, 
    743691variables \textit{z1} and \textit{z2} (real and imaginary part of SSH) 
    744 are expected to be available from file \np{filtide} with suffix 
     692are expected to be available from file \np{filtide}{filtide} with suffix 
    745693\ifile{tcname\_grid\_T}, variables \textit{u1} and \textit{u2} (real 
    746694and imaginary part of u) are expected to be available from file 
    747 \np{filtide} with suffix \ifile{tcname\_grid\_U}, and variables 
     695\np{filtide}{filtide} with suffix \ifile{tcname\_grid\_U}, and variables 
    748696\textit{v1} and \textit{v2} (real and imaginary part of v) are 
    749 expected to be available from file \np{filtide} with suffix 
    750 \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 
    751699\forcode{.true.}, the data is expected to be in complex conjugate 
    752700form. 
     
    760708direction of rotation). %, e.g. anticlockwise or clockwise. 
    761709 
    762 \biblio 
    763  
    764 \pindex 
     710\subinc{\input{../../global/epilogue}} 
    765711 
    766712\end{document} 
  • NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_LDF.tex

    r11179 r12149  
    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 (\textit{ldfslp.F90})] 
    41 {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})} 
    4268\label{sec:LDF_slp} 
    4369 
    44 %%% 
    45 \gmcomment{ 
     70\cmtgm{ 
    4671  we should emphasize here that the implementation is a rather old one. 
    4772  Better work can be achieved by using \citet{griffies.gnanadesikan.ea_JPO98, griffies_bk04} iso-neutral scheme. 
     
    5075A direction for lateral mixing has to be defined when the desired operator does not act along the model levels. 
    5176This occurs when $(a)$ horizontal mixing is required on tracer or momentum 
    52 (\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, 
    5378and $(b)$ isoneutral mixing is required whatever the vertical coordinate is. 
    5479This direction of mixing is defined by its slopes in the \textbf{i}- and \textbf{j}-directions at the face of 
    5580the cell of the quantity to be diffused. 
    5681For a tracer, this leads to the following four slopes: 
    57 $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}), 
    5883while for momentum the slopes are  $r_{1t}$, $r_{1uw}$, $r_{2f}$, $r_{2uw}$ for $u$ and 
    59 $r_{1f}$, $r_{1vw}$, $r_{2t}$, $r_{2vw}$ for $v$.  
    60  
    61 %gm% add here afigure of the slope in i-direction 
    62  
     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%% ================================================================================================= 
    6389\subsection{Slopes for tracer geopotential mixing in the $s$-coordinate} 
    6490 
    65 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 
    6692the geopotential and computational surfaces. 
    67 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 
    6894the diffusive fluxes in the three directions are set to zero and $T$ is assumed to be horizontally uniform, 
    69 \ie a linear function of $z_T$, the depth of a $T$-point.  
    70 %gm { Steven : My version is obviously wrong since I'm left with an arbitrary constant which is the local vertical temperature gradient} 
    71  
    72 \begin{equation} 
    73   \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} 
    74101  \begin{aligned} 
    75102    r_{1u} &= \frac{e_{3u}}{ \left( e_{1u}\;\overline{\overline{e_{3w}}}^{\,i+1/2,\,k} \right)} 
     
    86113\end{equation} 
    87114 
    88 %gm%  caution I'm not sure the simplification was a good idea!  
    89  
    90 These slopes are computed once in \rou{ldfslp\_init} when \np{ln\_sco}\forcode{ = .true.}rue, 
    91 and either \np{ln\_traldf\_hor}\forcode{ = .true.} or \np{ln\_dynldf\_hor}\forcode{ = .true.}.  
    92  
     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%% ================================================================================================= 
    93121\subsection{Slopes for tracer iso-neutral mixing} 
    94122\label{subsec:LDF_slp_iso} 
     
    97125Their formulation does not depend on the vertical coordinate used. 
    98126Their discrete formulation is found using the fact that the diffusive fluxes of 
    99 locally referenced potential density (\ie $in situ$ density) vanish. 
    100 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 
    101129the three directions to zero leads to the following definition for the neutral slopes: 
    102130 
    103131\begin{equation} 
    104   \label{eq:ldfslp_iso} 
     132  \label{eq:LDF_slp_iso} 
    105133  \begin{split} 
    106134    r_{1u} &= \frac{e_{3u}}{e_{1u}}\; \frac{\delta_{i+1/2}[\rho]} 
     
    117145\end{equation} 
    118146 
    119 %gm% rewrite this as the explanation is not very clear !!! 
    120 %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.  
    121  
    122 %By definition, neutral surfaces are tangent to the local $in situ$ density \citep{mcdougall_JPO87}, therefore in \autoref{eq:ldfslp_iso}, all the derivatives have to be evaluated at the same local pressure (which in decibars is approximated by the depth in meters). 
    123  
    124 %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.  
    125  
    126 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 
    127155be evaluated at the same local pressure 
    128156(which, in decibars, is approximated by the depth in meters in the model). 
    129 Therefore \autoref{eq:ldfslp_iso} cannot be used as such, 
     157Therefore \autoref{eq:LDF_slp_iso} cannot be used as such, 
    130158but further transformation is needed depending on the vertical coordinate used: 
    131159 
    132160\begin{description} 
    133  
    134 \item[$z$-coordinate with full step: ] 
    135   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, 
    136162  thus the $in situ$ density can be used. 
    137163  This is not the case for the vertical derivatives: $\delta_{k+1/2}[\rho]$ is replaced by $-\rho N^2/g$, 
    138164  where $N^2$ is the local Brunt-Vais\"{a}l\"{a} frequency evaluated following \citet{mcdougall_JPO87} 
    139   (see \autoref{subsec:TRA_bn2}).  
    140  
    141 \item[$z$-coordinate with partial step: ] 
    142   this case is identical to the full step case except that at partial step level, 
     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, 
    143167  the \emph{horizontal} density gradient is evaluated as described in \autoref{sec:TRA_zpshde}. 
    144  
    145 \item[$s$- or hybrid $s$-$z$- coordinate: ] 
    146   in the current release of \NEMO, iso-neutral mixing is only employed for $s$-coordinates if 
    147   the Griffies scheme is used (\np{traldf\_grif}\forcode{ = .true.}; 
    148   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}). 
    149171  In other words, iso-neutral mixing will only be accurately represented with a linear equation of state 
    150   (\np{nn\_eos}\forcode{ = 1..2}). 
    151   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} 
    152174  will include a pressure dependent part, leading to the wrong evaluation of the neutral slopes. 
    153175 
    154 %gm%  
    155176  Note: The solution for $s$-coordinate passes trough the use of different (and better) expression for 
    156177  the constraint on iso-neutral fluxes. 
     
    161182    \alpha \ \textbf{F}(T) = \beta \ \textbf{F}(S) 
    162183  \] 
    163   % gm{  where vector F is ....} 
     184  \cmtgm{where vector F is ....} 
    164185 
    165186This constraint leads to the following definition for the slopes: 
    166187 
    167188\[ 
    168   % \label{eq:ldfslp_iso2} 
     189  % \label{eq:LDF_slp_iso2} 
    169190  \begin{split} 
    170191    r_{1u} &= \frac{e_{3u}}{e_{1u}}\; \frac 
     
    194215 
    195216Note that such a formulation could be also used in the $z$-coordinate and $z$-coordinate with partial steps cases. 
    196  
    197217\end{description} 
    198218 
    199219This implementation is a rather old one. 
    200 It is similar to the one proposed by Cox [1987], except for the background horizontal diffusion. 
    201 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 
    202222a minimum background horizontal diffusion for numerical stability reasons. 
    203223To overcome this problem, several techniques have been proposed in which the numerical schemes of 
    204224the ocean model are modified \citep{weaver.eby_JPO97, griffies.gnanadesikan.ea_JPO98}. 
    205 Griffies's scheme is now available in \NEMO if \np{traldf\_grif\_iso} is set true; see Appdx \autoref{apdx:triad}. 
     225Griffies's scheme is now available in \NEMO\ if \np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}; see \autoref{apdx:TRIADS}. 
    206226Here, another strategy is presented \citep{lazar_phd97}: 
    207227a local filtering of the iso-neutral slopes (made on 9 grid-points) prevents the development of 
     
    209229This allows an iso-neutral diffusion scheme without additional background horizontal mixing. 
    210230This technique can be viewed as a diffusion operator that acts along large-scale 
    211 (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. 
    212232The 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. 
    213233 
    214234Nevertheless, this iso-neutral operator does not ensure that variance cannot increase, 
    215 contrary to the \citet{griffies.gnanadesikan.ea_JPO98} operator which has that property.  
    216  
    217 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     235contrary to the \citet{griffies.gnanadesikan.ea_JPO98} operator which has that property. 
     236 
    218237\begin{figure}[!ht] 
    219   \begin{center} 
    220     \includegraphics[width=\textwidth]{Fig_LDF_ZDF1} 
    221     \caption { 
    222       \protect\label{fig:LDF_ZDF1} 
    223       averaging procedure for isopycnal slope computation. 
    224     } 
    225   \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} 
    226242\end{figure} 
    227 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    228  
    229 %There are three additional questions about the slope calculation.  
    230 %First the expression for the rotation tensor has been obtain assuming the "small slope" approximation, so a bound has to be imposed on slopes.  
    231 %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. 
    232247%Third, the question of boundary condition specified on slopes... 
    233248 
    234249%from griffies: chapter 13.1.... 
    235250 
    236  
    237  
    238 % In addition and also for numerical stability reasons \citep{cox_OM87, griffies_bk04},  
    239 % the slopes are bounded by $1/100$ everywhere. This limit is decreasing linearly  
    240 % 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 
    241254% surface motivates this flattening of isopycnals near the surface). 
    242255 
    243256For numerical stability reasons \citep{cox_OM87, griffies_bk04}, the slopes must also be bounded by 
    244 $1/100$ everywhere. 
     257the namelist scalar \np{rn_slpmax}{rn\_slpmax} (usually $1/100$) everywhere. 
    245258This constraint is applied in a piecewise linear fashion, increasing from zero at the surface to 
    246259$1/100$ at $70$ metres and thereafter decreasing to zero at the bottom of the ocean 
    247260(the fact that the eddies "feel" the surface motivates this flattening of isopycnals near the surface). 
    248  
    249 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     261\colorbox{yellow}{The way slopes are tapered has be checked. Not sure that this is still what is actually done.} 
     262 
    250263\begin{figure}[!ht] 
    251   \begin{center} 
    252     \includegraphics[width=\textwidth]{Fig_eiv_slp} 
    253     \caption{ 
    254       \protect\label{fig:eiv_slp} 
    255       Vertical profile of the slope used for lateral mixing in the mixed layer: 
    256       \textit{(a)} in the real ocean the slope is the iso-neutral slope in the ocean interior, 
    257       which has to be adjusted at the surface boundary 
    258       \ie it must tend to zero at the surface since there is no mixing across the air-sea interface: 
    259       wall boundary condition). 
    260       Nevertheless, the profile between the surface zero value and the interior iso-neutral one is unknown, 
    261       and especially the value at the base of the mixed layer; 
    262       \textit{(b)} profile of slope using a linear tapering of the slope near the surface and 
    263       imposing a maximum slope of 1/100; 
    264       \textit{(c)} profile of slope actually used in \NEMO: a linear decrease of the slope from 
    265       zero at the surface to its ocean interior value computed just below the mixed layer. 
    266       Note the huge change in the slope at the base of the mixed layer between \textit{(b)} and \textit{(c)}. 
    267     } 
    268   \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} 
    269283\end{figure} 
    270 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    271284 
    272285\colorbox{yellow}{add here a discussion about the flattening of the slopes, vs tapering the coefficient.} 
    273286 
     287%% ================================================================================================= 
    274288\subsection{Slopes for momentum iso-neutral mixing} 
    275289 
    276290The iso-neutral diffusion operator on momentum is the same as the one used on tracers but 
    277291applied to each component of the velocity separately 
    278 (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}). 
    279293The slopes between the surface along which the diffusion operator acts and the surface of computation 
    280294($z$- or $s$-surfaces) are defined at $T$-, $f$-, and \textit{uw}- points for the $u$-component, and $T$-, $f$- and 
    281295\textit{vw}- points for the $v$-component. 
    282296They are computed from the slopes used for tracer diffusion, 
    283 \ie \autoref{eq:ldfslp_geo} and \autoref{eq:ldfslp_iso}: 
     297\ie\ \autoref{eq:LDF_slp_geo} and \autoref{eq:LDF_slp_iso}: 
    284298 
    285299\[ 
    286   % \label{eq:ldfslp_dyn} 
     300  % \label{eq:LDF_slp_dyn} 
    287301  \begin{aligned} 
    288302    &r_{1t}\ \ = \overline{r_{1u}}^{\,i}       &&&    r_{1f}\ \ &= \overline{r_{1u}}^{\,i+1/2} \\ 
     
    295309The major issue remaining is in the specification of the boundary conditions. 
    296310The same boundary conditions are chosen as those used for lateral diffusion along model level surfaces, 
    297 \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 
    298312(see \autoref{sec:LBC_coast}). 
    299313 
    300  
    301 % ================================================================ 
    302 % Lateral Mixing Operator 
    303 % ================================================================ 
    304 \section[Lateral mixing operators (\textit{traldf.F90})] 
    305 {Lateral mixing operators (\protect\mdl{traldf}, \protect\mdl{traldf})} 
    306 \label{sec:LDF_op} 
    307  
    308  
    309     
    310 % ================================================================ 
    311 % Lateral Mixing Coefficients 
    312 % ================================================================ 
    313 \section[Lateral mixing coefficient (\textit{ldftra.F90}, \textit{ldfdyn.F90})] 
    314 {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})} 
    315316\label{sec:LDF_coef} 
    316317 
    317 Introducing a space variation in the lateral eddy mixing coefficients changes the model core memory requirement, 
    318 adding up to four extra three-dimensional arrays for the geopotential or isopycnal second order operator applied to  
    319 momentum. 
    320 Six CPP keys control the space variation of eddy coefficients: three for momentum and three for tracer. 
    321 The three choices allow: 
    322 a space variation in the three space directions (\key{traldf\_c3d},  \key{dynldf\_c3d}), 
    323 in the horizontal plane (\key{traldf\_c2d},  \key{dynldf\_c2d}), 
    324 or in the vertical only (\key{traldf\_c1d},  \key{dynldf\_c1d}). 
    325 The default option is a constant value over the whole ocean on both momentum and tracers.  
    326     
    327 The number of additional arrays that have to be defined and the gridpoint position at which 
    328 they are defined depend on both the space variation chosen and the type of operator used. 
    329 The resulting eddy viscosity and diffusivity coefficients can be a function of more than one variable. 
    330 Changes in the computer code when switching from one option to another have been minimized by 
    331 introducing the eddy coefficients as statement functions 
    332 (include file \textit{ldftra\_substitute.h90} and \textit{ldfdyn\_substitute.h90}). 
    333 The functions are replaced by their actual meaning during the preprocessing step (CPP). 
    334 The specification of the space variation of the coefficient is made in \mdl{ldftra} and \mdl{ldfdyn}, 
    335 or more precisely in include files \textit{traldf\_cNd.h90} and \textit{dynldf\_cNd.h90}, with N=1, 2 or 3. 
    336 The user can modify these include files as he/she wishes. 
    337 The way the mixing coefficient are set in the reference version can be briefly described as follows: 
    338  
    339 \subsubsection{Constant mixing coefficients (default option)} 
    340 When none of the \key{dynldf\_...} and \key{traldf\_...} keys are defined, 
    341 a constant value is used over the whole ocean for momentum and tracers, 
    342 which is specified through the \np{rn\_ahm0} and \np{rn\_aht0} namelist parameters. 
    343  
    344 \subsubsection[Vertically varying mixing coefficients (\texttt{\textbf{key\_traldf\_c1d}} and \texttt{\textbf{key\_dynldf\_c1d}})] 
    345 {Vertically varying mixing coefficients (\protect\key{traldf\_c1d} and \key{dynldf\_c1d})} 
    346 The 1D option is only available when using the $z$-coordinate with full step. 
    347 Indeed in all the other types of vertical coordinate, 
    348 the depth is a 3D function of (\textbf{i},\textbf{j},\textbf{k}) and therefore, 
    349 introducing depth-dependent mixing coefficients will require 3D arrays. 
    350 In the 1D option, a hyperbolic variation of the lateral mixing coefficient is introduced in which 
    351 the surface value is \np{rn\_aht0} (\np{rn\_ahm0}), the bottom value is 1/4 of the surface value, 
    352 and the transition takes place around z=300~m with a width of 300~m 
    353 (\ie both the depth and the width of the inflection point are set to 300~m). 
    354 This profile is hard coded in file \textit{traldf\_c1d.h90}, but can be easily modified by users. 
    355  
    356 \subsubsection[Horizontally varying mixing coefficients (\texttt{\textbf{key\_traldf\_c2d}} and \texttt{\textbf{key\_dynldf\_c2d}})] 
    357 {Horizontally varying mixing coefficients (\protect\key{traldf\_c2d} and \protect\key{dynldf\_c2d})} 
    358 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 
    359373the type of operator used: 
    360374\begin{equation} 
    361   \label{eq:title} 
     375  \label{eq:LDF_title} 
    362376  A_l = \left\{ 
    363377    \begin{aligned} 
    364       & \frac{\max(e_1,e_2)}{e_{max}} A_o^l           & \text{for laplacian operator } \\ 
    365       & \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 } 
    366380    \end{aligned} 
    367381  \right. 
    368382\end{equation} 
    369 where $e_{max}$ is the maximum of $e_1$ and $e_2$ taken over the whole masked ocean domain, 
    370 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}). 
    371384This variation is intended to reflect the lesser need for subgrid scale eddy mixing where 
    372385the grid size is smaller in the domain. 
    373386It was introduced in the context of the DYNAMO modelling project \citep{willebrand.barnier.ea_PO01}. 
    374 Note that such a grid scale dependance of mixing coefficients significantly increase the range of stability of 
    375 model configurations presenting large changes in grid pacing such as global ocean models. 
     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. 
    376389Indeed, in such a case, a constant mixing coefficient can lead to a blow up of the model due to 
    377 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}), 
    378391especially when using a bilaplacian operator. 
    379392 
    380 Other formulations can be introduced by the user for a given configuration. 
    381 For example, in the ORCA2 global ocean model (see Configurations), 
    382 the laplacian viscosity operator uses \np{rn\_ahm0}~= 4.10$^4$ m$^2$/s poleward of 20$^{\circ}$ north and south and 
    383 decreases linearly to \np{rn\_aht0}~= 2.10$^3$ m$^2$/s at the equator \citep{madec.delecluse.ea_JPO96, delecluse.madec_icol99}. 
    384 This modification can be found in routine \rou{ldf\_dyn\_c2d\_orca} defined in \mdl{ldfdyn\_c2d}. 
    385 Similar modified horizontal variations can be found with the Antarctic or Arctic sub-domain options of 
    386 ORCA2 and ORCA05 (see \&namcfg namelist). 
    387  
    388 \subsubsection[Space varying mixing coefficients (\texttt{\textbf{key\_traldf\_c3d}} and \texttt{\textbf{key\_dynldf\_c3d}})] 
    389 {Space varying mixing coefficients (\protect\key{traldf\_c3d} and \key{dynldf\_c3d})} 
    390  
    391 The 3D space variation of the mixing coefficient is simply the combination of the 1D and 2D cases, 
    392 \ie a hyperbolic tangent variation with depth associated with a grid size dependence of 
    393 the magnitude of the coefficient.  
    394  
    395 \subsubsection{Space and time varying mixing coefficients} 
    396  
    397 There is no default specification of space and time varying mixing coefficient.  
    398 The only case available is specific to the ORCA2 and ORCA05 global ocean configurations. 
    399 It provides only a tracer mixing coefficient for eddy induced velocity (ORCA2) or both iso-neutral and 
    400 eddy induced velocity (ORCA05) that depends on the local growth rate of baroclinic instability. 
    401 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} 
    402456 
    403457The following points are relevant when the eddy coefficient varies spatially: 
    404458 
    405459(1) the momentum diffusion operator acting along model level surfaces is written in terms of curl and 
    406 divergent components of the horizontal current (see \autoref{subsec:PE_ldf}). 
     460divergent components of the horizontal current (see \autoref{subsec:MB_ldf}). 
    407461Although the eddy coefficient could be set to different values in these two terms, 
    408 this option is not currently available.  
     462this option is not currently available. 
    409463 
    410464(2) with an horizontally varying viscosity, the quadratic integral constraints on enstrophy and on the square of 
    411465the horizontal divergence for operators acting along model-surfaces are no longer satisfied 
    412 (\autoref{sec:dynldf_properties}). 
    413  
    414 (3) for isopycnal diffusion on momentum or tracers, an additional purely horizontal background diffusion with 
    415 uniform coefficient can be added by setting a non zero value of \np{rn\_ahmb0} or \np{rn\_ahtb0}, 
    416 a background horizontal eddy viscosity or diffusivity coefficient 
    417 (namelist parameters whose default values are $0$). 
    418 However, the technique used to compute the isopycnal slopes is intended to get rid of such a background diffusion, 
    419 since it introduces spurious diapycnal diffusion (see \autoref{sec:LDF_slp}). 
    420  
    421 (4) when an eddy induced advection term is used (\key{traldf\_eiv}), 
    422 $A^{eiv}$, the eddy induced coefficient has to be defined. 
    423 Its space variations are controlled by the same CPP variable as for the eddy diffusivity coefficient 
    424 (\ie \key{traldf\_cNd}).  
    425  
    426 (5) the eddy coefficient associated with a biharmonic operator must be set to a \emph{negative} value. 
    427  
    428 (6) it is possible to use both the laplacian and biharmonic operators concurrently. 
    429  
    430 (7) it is possible to run without explicit lateral diffusion on momentum 
    431 (\np{ln\_dynldf\_lap}\forcode{ = .?.}\np{ln\_dynldf\_bilap}\forcode{ = .false.}). 
    432 This is recommended when using the UBS advection scheme on momentum (\np{ln\_dynadv\_ubs}\forcode{ = .true.}, 
    433 see \autoref{subsec:DYN_adv_ubs}) and can be useful for testing purposes. 
    434  
    435 % ================================================================ 
    436 % Eddy Induced Mixing 
    437 % ================================================================ 
    438 \section[Eddy induced velocity (\textit{traadv\_eiv.F90}, \textit{ldfeiv.F90})] 
    439 {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 
    440471\label{sec:LDF_eiv} 
    441472 
     473\begin{listing} 
     474  \nlst{namtra_eiv} 
     475  \caption{\forcode{&namtra_eiv}} 
     476  \label{lst:namtra_eiv} 
     477\end{listing} 
     478 
    442479%%gm  from Triad appendix  : to be incorporated.... 
    443 \gmcomment{ 
     480\cmtgm{ 
    444481  Values of iso-neutral diffusivity and GM coefficient are set as described in \autoref{sec:LDF_coef}. 
    445482  If none of the keys \key{traldf\_cNd}, N=1,2,3 is set (the default), spatially constant iso-neutral $A_l$ and 
    446   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}. 
    447484  If 2D-varying coefficients are set with \key{traldf\_c2d} then $A_l$ is reduced in proportion with horizontal 
    448485  scale factor according to \autoref{eq:title} 
     
    457494    In this case, $A_e$ at low latitudes $|\theta|<20^{\circ}$ is further reduced by a factor $|f/f_{20}|$, 
    458495    where $f_{20}$ is the value of $f$ at $20^{\circ}$~N 
    459   } (\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. 
    460497} 
    461498 
    462 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}), 
    463500an eddy induced tracer advection term is added, 
    464501the formulation of which depends on the slopes of iso-neutral surfaces. 
    465502Contrary to the case of iso-neutral mixing, the slopes used here are referenced to the geopotential surfaces, 
    466 \ie \autoref{eq:ldfslp_geo} is used in $z$-coordinates, 
    467 and the sum \autoref{eq:ldfslp_geo} + \autoref{eq:ldfslp_iso} in $s$-coordinates. 
    468 The eddy induced velocity is given by:  
    469 \begin{equation} 
    470   \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} 
    471509  \begin{split} 
    472510    u^* & = \frac{1}{e_{2u}e_{3u}}\; \delta_k \left[e_{2u} \, A_{uw}^{eiv} \; \overline{r_{1w}}^{\,i+1/2} \right]\\ 
     
    475513  \end{split} 
    476514\end{equation} 
    477 where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{rn\_aeiv}, 
    478 a \textit{nam\_traldf} namelist parameter. 
    479 The three components of the eddy induced velocity are computed and 
    480 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. 
    481518This has been preferred to a separate computation of the advective trends associated with the eiv velocity, 
    482519since it allows us to take advantage of all the advection schemes offered for the tracers 
     
    484521previous releases of OPA \citep{madec.delecluse.ea_NPM98}. 
    485522This is particularly useful for passive tracers where \emph{positivity} of the advection scheme is of 
    486 paramount importance.  
     523paramount importance. 
    487524 
    488525At the surface, lateral and bottom boundaries, the eddy induced velocity, 
    489 and thus the advective eddy fluxes of heat and salt, are set to zero.  
    490  
    491 \biblio 
    492  
    493 \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}} 
    494547 
    495548\end{document} 
  • NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_OBS.tex

    r11151 r12149  
    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 ${\mathrm P}$ with with longitude and latitude $({\lambda_{}}_{\mathrm P}, \phi_{\mathrm P})$ and 
     603Consider an observation point ${\mathrm P}$ with longitude and latitude (${\lambda_{}}_{\mathrm P}$, $\phi_{\mathrm P}$) and 
    576604the four nearest neighbouring model grid points ${\mathrm A}$, ${\mathrm B}$, ${\mathrm C}$ and ${\mathrm D}$ with 
    577605longitude and latitude ($\lambda_{\mathrm A}$, $\phi_{\mathrm A}$),($\lambda_{\mathrm B}$, $\phi_{\mathrm B}$) etc. 
    578 All horizontal interpolation methods implemented in NEMO estimate the value of a model variable $x$ at point $P$ as 
     606All horizontal interpolation methods implemented in \NEMO\ estimate the value of a model variable $x$ at point $P$ as 
    579607a 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_{}}_{\mathrm P} & \hspace{-2mm} = \hspace{-2mm} & 
    582                                                    \frac{1}{w} \left( {w_{}}_{\mathrm A} {x_{}}_{\mathrm A} + 
    583                                                    {w_{}}_{\mathrm B} {x_{}}_{\mathrm B} + 
    584                                                    {w_{}}_{\mathrm C} {x_{}}_{\mathrm C} + 
    585                                                    {w_{}}_{\mathrm D} {x_{}}_{\mathrm 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*} 
     616 
    587617where ${w_{}}_{\mathrm A}$, ${w_{}}_{\mathrm B}$ etc. are the respective weights for the model field at 
    588618points ${\mathrm A}$, ${\mathrm B}$ etc., and $w = {w_{}}_{\mathrm A} + {w_{}}_{\mathrm B} + {w_{}}_{\mathrm C} + {w_{}}_{\mathrm D}$. 
     
    591621 
    592622\begin{enumerate} 
    593  
    594 \item[1.] {\bfseries 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. 
    597626  For example, the weight given to the field ${x_{}}_{\mathrm A}$ is specified as the product of the distances 
    598627  from ${\mathrm P}$ to the other points: 
    599   \begin{align*} 
     628 
     629  \begin{alignat*}{2} 
    600630    {w_{}}_{\mathrm A} = s({\mathrm P}, {\mathrm B}) \, s({\mathrm P}, {\mathrm C}) \, s({\mathrm P}, {\mathrm D}) 
    601   \end{align*} 
    602   where  
    603   \begin{align*} 
    604     s\left ({\mathrm P}, {\mathrm M} \right )  
    605      & \hspace{-2mm} = \hspace{-2mm} &  
    606       \cos^{-1} \! \left\{  
     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\{ 
    607637               \sin {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm M} 
    608              + \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm M}  
    609                \cos ({\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P})  
     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( {\mathrm P}, {\mathrm 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_{}}_{\mathrm M} {a_{}}_{\mathrm P} + {b_{}}_{\mathrm M} {b_{}}_{\mathrm P} + {c_{}}_{\mathrm M} {c_{}}_{\mathrm P} 
    622    \end{align*} 
    623    and  
    624    \begin{align*} 
    625       {a_{}}_{\mathrm M} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\mathrm M}, \\ 
    626       {a_{}}_{\mathrm P} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\mathrm P}, \\ 
    627       {b_{}}_{\mathrm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\mathrm M} \cos {\phi_{}}_{\mathrm M}, \\ 
    628       {b_{}}_{\mathrm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm P}, \\ 
    629       {c_{}}_{\mathrm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\mathrm M} \sin {\phi_{}}_{\mathrm M}, \\ 
    630       {c_{}}_{\mathrm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm P}. 
    631   \end{align*} 
    632  
    633 \item[2.] {\bfseries 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*} 
     670  \begin{alignat*}{2} 
    636671    s\left( {\mathrm P}, {\mathrm M} \right) 
    637     & \hspace{-2mm} = \hspace{-2mm} & 
    638                                       \sqrt{ \left( {\phi_{}}_{\mathrm M} - {\phi_{}}_{\mathrm P} \right)^{2} 
     672    & = & \sqrt{ \left( {\phi_{}}_{\mathrm M} - {\phi_{}}_{\mathrm P} \right)^{2} 
    639673                                      + \left( {\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P} \right)^{2} 
    640674                                      \cos^{2} {\phi_{}}_{\mathrm M} } 
    641   \end{align*} 
     675  \end{alignat*} 
    642676  where $M$ corresponds to $A$, $B$, $C$ or $D$. 
    643677 
    644 \item[3.] {\bfseries 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.] {\bfseries 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). 
    650684  This method is based on the \href{https://github.com/SCRIP-Project/SCRIP}{SCRIP interpolation package}. 
    651    
     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=\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=\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. 
    712738Let ${\mathrm P}({\lambda_{}}_{\mathrm P} ,{\phi_{}}_{\mathrm P} )$ denote the observation point, 
    713739and let ${\mathrm A}({\lambda_{}}_{\mathrm A} ,{\phi_{}}_{\mathrm A} )$, ${\mathrm B}({\lambda_{}}_{\mathrm B} ,{\phi_{}}_{\mathrm B} )$, 
    714740${\mathrm C}({\lambda_{}}_{\mathrm C} ,{\phi_{}}_{\mathrm C} )$ and ${\mathrm D}({\lambda_{}}_{\mathrm D} ,{\phi_{}}_{\mathrm 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  
     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} 
     
    738764          ({\phi_{}}_{\mathrm D}  \;  - \; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\ 
    739765  \end{array} 
    740   % \label{eq:cross} 
     766  % \label{eq:OBS_cross} 
    741767\end{align*} 
    742768point in the opposite direction to the unit normal $\widehat{\mathbf k}$ 
    743 (\ie that the coefficients of $\widehat{\mathbf k}$ are negative), 
     769(\ie\ that the coefficients of $\widehat{\mathbf k}$ are negative), 
    744770where ${{\mathbf r}_{}}_{\mathrm PA}$, ${{\mathbf r}_{}}_{\mathrm PB}$, etc. correspond to 
    745771the vectors between points P and A, P and B, etc.. 
     
    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=\textwidth]{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=\textwidth]{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=\textwidth]{Fig_OBS_dataplot_main} 
    1373     \includegraphics[width=\textwidth]{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=\textwidth]{Fig_OBS_dataplot_prof} 
    1389     \includegraphics[width=\textwidth]{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/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_SBC.tex

    r11179 r12149  
    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 (\textit{fldread.F90})] 
    229 {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})} 
    230213\label{subsec:SBC_fldread} 
    231214 
    232215The structure associated with an input variable contains the following information: 
    233216\begin{forlines} 
    234 !  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 ! 
    235218!             !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      ! 
    236219\end{forlines} 
    237 where  
    238 \begin{description}   
    239 \item[File name]: 
    240   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. 
    241223  This stem will be completed automatically by the model, with the addition of a '.nc' at its end and 
    242224  by date information and possibly a prefix (when using AGRIF). 
    243   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 
    244226  whether it is a climatological file or not, and to the open/close frequency (see below for definition). 
    245  
    246 %--------------------------------------------------TABLE-------------------------------------------------- 
    247227  \begin{table}[htbp] 
    248     \begin{center} 
    249       \begin{tabular}{|l|c|c|c|} 
    250         \hline 
    251         & daily or weekLLL         & monthly                   &   yearly          \\   \hline 
    252         \np{clim}\forcode{ = .false.}  & fn\_yYYYYmMMdDD.nc  &   fn\_yYYYYmMM.nc   &   fn\_yYYYY.nc  \\   \hline 
    253         \np{clim}\forcode{ = .true.}         & not possible                  &  fn\_m??.nc             &   fn                \\   \hline 
    254       \end{tabular} 
    255     \end{center} 
    256     \caption{ 
    257       \protect\label{tab:fldread} 
    258       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. 
    259241      The stem name is assumed to be 'fn'. 
    260242      For weekly files, the 'LLL' corresponds to the first three letters of the first day of the week 
    261       (\ie 'sun','sat','fri','thu','wed','tue','mon'). 
    262       The 'YYYY', 'MM' and 'DD' should be replaced by the actual year/month/day, always coded with 4 or 2 digits. 
    263       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', 
    264248      where 'PPPP' is the process number coded with 4 digits; 
    265       (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. 
    266250    } 
     251    \label{tab:SBC_fldread} 
    267252  \end{table} 
    268 %-------------------------------------------------------------------------------------------------------------- 
    269    
    270  
    271 \item[Record frequency]: 
    272   the frequency of the records contained in the input file. 
     253\item [Record frequency]: the frequency of the records contained in the input file. 
    273254  Its unit is in hours if it is positive (for example 24 for daily forcing) or in months if negative 
    274255  (for example -1 for monthly forcing or -12 for annual forcing). 
    275   Note that this frequency must really be an integer and not a real. 
    276   On some computers, seting it to '24.' can be interpreted as 240! 
    277  
    278 \item[Variable name]: 
    279   the name of the variable to be read in the input NetCDF file. 
    280  
    281 \item[Time interpolation]: 
    282   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. 
    283260  If set to 'false', the forcing will have a steplike shape remaining constant during each forcing period. 
    284261  For example, when using a daily forcing without time interpolation, the forcing remaining constant from 
    285262  00h00'00'' to 23h59'59". 
    286263  If set to 'true', the forcing will have a broken line shape. 
    287   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. 
    288265  For example, when using a daily forcing with time interpolation, 
    289   linear interpolation will be performed between mid-day of two consecutive days.  
    290  
    291 \item[Climatological forcing]: 
    292   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, 
    293268  or an interannual forcing which will requires additional files if 
    294   the period covered by the simulation exceed the one of the file. 
    295   See the above the file naming strategy which impacts the expected name of the file to be opened.  
    296  
    297 \item[Open/close frequency]: 
    298   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. 
    299272  Four cases are coded: 
    300273  'daily', 'weekLLL' (with 'LLL' the first 3 letters of the first day of the week), 'monthly' and 'yearly' which 
     
    302275  Files are assumed to contain data from the beginning of the open/close period. 
    303276  For example, the first record of a yearly file containing daily data is Jan 1st even if 
    304   the experiment is not starting at the beginning of the year.  
    305  
    306 \item[Others]: 
    307   '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 
    308279  on-the-fly interpolation which is described in \autoref{subsec:SBC_iof}. 
    309  
    310280\end{description} 
    311281 
     
    315285the date of the records read in the input files. 
    316286Following \citet{leclair.madec_OM09}, the date of a time step is set at the middle of the time step. 
    317 For example, for an experiment starting at 0h00'00" with a one hour time-step, 
     287For example, for an experiment starting at 0h00'00" with a one-hour time-step, 
    318288a time interpolation will be performed at the following time: 0h30'00", 1h30'00", 2h30'00", etc. 
    319289However, for forcing data related to the surface module, 
    320 values are not needed at every time-step but at every \np{nn\_fsbc} time-step. 
    321 For example with \np{nn\_fsbc}\forcode{ = 3}, the surface module will be called at time-steps 1, 4, 7, etc. 
    322 The date used for the time interpolation is thus redefined to be at the middle of \np{nn\_fsbc} time-step period. 
    323 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. \\ 
    324294(2) For code readablility and maintenance issues, we don't take into account the NetCDF input file calendar. 
    325295The calendar associated with the forcing field is build according to the information provided by 
    326296user in the record frequency, the open/close frequency and the type of temporal interpolation. 
    327297For example, the first record of a yearly file containing daily data that will be interpolated in time is assumed to 
    328 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". \\ 
    329299(3) If a time interpolation is requested, the code will pick up the needed data in the previous (next) file when 
    330300interpolating data with the first (last) record of the open/close period. 
    331 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'', 
    332302the values given by the code between 00h00'00" and 11h59'59" on Jan 1st will be interpolated values between 
    333303Dec 31st 12h00'00" and Jan 1st 12h00'00". 
    334304If the forcing is climatological, Dec and Jan will be keep-up from the same year. 
    335305However, if the forcing is not climatological, at the end of 
    336 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. 
    337307Note that, if the experiment is starting (ending) at the beginning (end) of 
    338 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. 
    339309In this case, the time interpolation will be performed between two identical values. 
    340310For example, when starting an experiment on Jan 1st of year Y with yearly files and daily data to be interpolated, 
    341311we do accept that the file related to year Y-1 is not existing. 
    342312The value of Jan 1st will be used as the missing one for Dec 31st of year Y-1. 
    343 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. 
    344314Therefore, this file can contain only one record corresponding to Dec 31st, 
    345315a useful feature for user considering that it is too heavy to manipulate the complete file for year Y-1. 
    346316 
    347  
    348 % ------------------------------------------------------------------------------------------------------------- 
    349 % Interpolation on the Fly 
    350 % ------------------------------------------------------------------------------------------------------------- 
     317%% ================================================================================================= 
    351318\subsection{Interpolation on-the-fly} 
    352319\label{subsec:SBC_iof} 
     
    354321Interpolation on the Fly allows the user to supply input files required for the surface forcing on 
    355322grids other than the model grid. 
    356 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 
    357324interpolate from the data grid to the model grid. 
    358325The original development of this code used the SCRIP package 
    359326(freely available \href{http://climate.lanl.gov/Software/SCRIP}{here} under a copyright agreement). 
    360 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 
    361328the input weights file must have the same names and meanings as assumed by the model. 
    362 Two methods are currently available: bilinear and bicubic interpolation. 
     329Two methods are currently available: bilinear and bicubic interpolations. 
    363330Prior to the interpolation, providing a land/sea mask file, the user can decide to remove land points from 
    364331the input file and substitute the corresponding values with the average of the 8 neighbouring points in 
     
    366333Only "sea points" are considered for the averaging. 
    367334The land/sea mask file must be provided in the structure associated with the input variable. 
    368 The netcdf land/sea mask variable name must be 'LSM' it must have the same horizontal and vertical dimensions of 
    369 the associated variable and should be equal to 1 over land and 0 elsewhere. 
    370 The procedure can be recursively applied setting nn\_lsm > 1 in namsbc namelist. 
    371 Note that nn\_lsm=0 forces the code to not apply the procedure even if a file for land/sea mask is supplied. 
    372  
     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%% ================================================================================================= 
    373341\subsubsection{Bilinear interpolation} 
    374342\label{subsec:SBC_iof_bilinear} 
     
    376344The input weights file in this case has two sets of variables: 
    377345src01, src02, src03, src04 and wgt01, wgt02, wgt03, wgt04. 
    378 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. 
    379347Each src value is an integer corresponding to the index of a point in the input grid when 
    380348written as a one dimensional array. 
     
    392360and wgt(1) corresponds to variable "wgt01" for example. 
    393361 
     362%% ================================================================================================= 
    394363\subsubsection{Bicubic interpolation} 
    395364\label{subsec:SBC_iof_bicubic} 
    396365 
    397 Again there are two sets of variables: "src" and "wgt". 
    398 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. 
    399368The symbolic algorithm used to calculate values on the model grid is now: 
    400369 
     
    402371  \begin{split} 
    403372    f_{m}(i,j) =  f_{m}(i,j) +& \sum_{k=1}^{4} {wgt(k)f(idx(src(k)))} 
    404     +   \sum_{k=5}^{8} {wgt(k)\left.\frac{\partial f}{\partial i}\right| _{idx(src(k))} }    \\ 
    405     +& \sum_{k=9}^{12} {wgt(k)\left.\frac{\partial f}{\partial j}\right| _{idx(src(k))} } 
    406     +   \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))} } 
    407376  \end{split} 
    408377\] 
    409378The gradients here are taken with respect to the horizontal indices and not distances since 
    410 the spatial dependency has been absorbed into the weights. 
    411  
     379the spatial dependency has been included into the weights. 
     380 
     381%% ================================================================================================= 
    412382\subsubsection{Implementation} 
    413383\label{subsec:SBC_iof_imp} 
     
    421391inspecting a global attribute stored in the weights input file. 
    422392This attribute must be called "ew\_wrap" and be of integer type. 
    423 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. 
    424394If zero or greater, then the value represents the number of columns that overlap. 
    425395$E.g.$ if the input grid has columns at longitudes 0, 1, 2, .... , 359, then ew\_wrap should be set to 0; 
    426396if longitudes are 0.5, 2.5, .... , 358.5, 360.5, 362.5, ew\_wrap should be 2. 
    427397If the model does not find attribute ew\_wrap, then a value of -999 is assumed. 
    428 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 
    429399therefore the grid is assumed to be cyclic with no overlapping columns. 
    430 (In fact this only matters when bicubic interpolation is required.) 
     400(In fact, this only matters when bicubic interpolation is required.) 
    431401Note that no testing is done to check the validity in the model, 
    432402since there is no way of knowing the name used for the longitude variable, 
     
    445415or is a copy of one from the first few columns on the opposite side of the grid (cyclical case). 
    446416 
     417%% ================================================================================================= 
    447418\subsubsection{Limitations} 
    448419\label{subsec:SBC_iof_lim} 
    449420 
    450 \begin{enumerate}   
    451 \item 
    452   The case where input data grids are not logically rectangular has not been tested. 
    453 \item 
    454   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 
    455424  a bicubic interpolation method is used. 
    456 \item 
    457   The cyclic condition is only applied on left and right columns, and not to top and bottom rows. 
    458 \item 
    459   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 
    460427  the two columns involved are consistent with the weights used. 
    461 \item 
    462   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, 
    463429  but this has not been implemented.) 
    464430\end{enumerate} 
    465431 
     432%% ================================================================================================= 
    466433\subsubsection{Utilities} 
    467434\label{subsec:SBC_iof_util} 
     
    471438(see the directory NEMOGCM/TOOLS/WEIGHTS). 
    472439 
    473 % ------------------------------------------------------------------------------------------------------------- 
    474 % Standalone Surface Boundary Condition Scheme 
    475 % ------------------------------------------------------------------------------------------------------------- 
    476 \subsection{Standalone surface boundary condition scheme} 
    477 \label{subsec:SAS_iof} 
    478  
    479 %---------------------------------------namsbc_ana-------------------------------------------------- 
    480  
    481 \nlst{namsbc_sas} 
    482 %-------------------------------------------------------------------------------------------------------------- 
    483  
    484 In some circumstances it may be useful to avoid calculating the 3D temperature, 
    485 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. 
    486452For example: 
    487453 
    488454\begin{itemize} 
    489 \item 
    490   Multiple runs of the model are required in code development to 
     455\item Multiple runs of the model are required in code development to 
    491456  see the effect of different algorithms in the bulk formulae. 
    492 \item 
    493   The effect of different parameter sets in the ice model is to be examined. 
    494 \item 
    495   Development of sea-ice algorithms or parameterizations. 
    496 \item 
    497   Spinup of the iceberg floats 
    498 \item 
    499   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}) 
    500461\end{itemize} 
    501462 
    502 The StandAlone Surface scheme provides this utility. 
    503 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. 
    504465A new copy of the model has to be compiled with a configuration based on ORCA2\_SAS\_LIM. 
    505 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). 
    506467In this configuration, a few routines in the standard model are overriden by new versions. 
    507468Routines replaced are: 
    508469 
    509470\begin{itemize} 
    510 \item 
    511   \mdl{nemogcm}: 
    512   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}). 
    513472  Since the ocean state is not calculated all associated initialisations have been removed. 
    514 \item 
    515   \mdl{step}: 
    516   The main time stepping routine now only needs to call the sbc routine (and a few utility functions). 
    517 \item 
    518   \mdl{sbcmod}: 
    519   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. 
    520475  New surface modules that can function when only the surface level of the ocean state is defined can also be added 
    521   (\eg icebergs). 
    522 \item 
    523   \mdl{daymod}: 
    524   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), 
    525478  so calls to restart functions have been removed. 
    526479  This also means that the calendar cannot be controlled by time in a restart file, 
    527   so the user must make sure that nn{\_}date0 in the model namelist is correct for his or her purposes. 
    528 \item 
    529   \mdl{stpctl}: 
    530   Since there is no free surface solver, references to it have been removed from \rou{stp\_ctl} module. 
    531 \item 
    532   \mdl{diawri}: 
    533   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. 
    534483  The surface temperature, salinity and velocity components (which have been read in) are written along with 
    535484  relevant forcing and ice data. 
     
    539488 
    540489\begin{itemize} 
    541 \item 
    542   \mdl{sbcsas}: 
    543   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 
    544491  velocity arrays at the surface. 
    545   These filenames are supplied in namelist namsbc{\_}sas. 
    546   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, 
    547494  the full 3D fields from the mean files have to be read in and interpolated in time, 
    548495  before using just the top level. 
     
    550497\end{itemize} 
    551498 
    552  
    553 % Missing the description of the 2 following variables: 
    554 %   ln_3d_uve   = .true.    !  specify whether we are supplying a 3D u,v and e3 field 
    555 %   ln_read_frq = .false.    !  specify whether we must read frq or not 
    556  
    557  
    558  
    559 % ================================================================ 
    560 % Analytical formulation (sbcana module)  
    561 % ================================================================ 
    562 \section[Analytical formulation (\textit{sbcana.F90})] 
    563 {Analytical formulation (\protect\mdl{sbcana})} 
    564 \label{sec:SBC_ana} 
    565  
    566 %---------------------------------------namsbc_ana-------------------------------------------------- 
    567 % 
    568 %\nlst{namsbc_ana} 
    569 %-------------------------------------------------------------------------------------------------------------- 
    570  
    571 The analytical formulation of the surface boundary condition is the default scheme. 
    572 In this case, all the six fluxes needed by the ocean are assumed to be uniform in space. 
    573 They take constant values given in the namelist \ngn{namsbc{\_}ana} by 
    574 the variables \np{rn\_utau0}, \np{rn\_vtau0}, \np{rn\_qns0}, \np{rn\_qsr0}, and \np{rn\_emp0} 
    575 ($\textit{emp}=\textit{emp}_S$). 
    576 The runoff is set to zero. 
    577 In addition, the wind is allowed to reach its nominal value within a given number of time steps (\np{nn\_tau000}). 
    578  
    579 If a user wants to apply a different analytical forcing, 
    580 the \mdl{sbcana} module can be modified to use another scheme. 
    581 As an example, the \mdl{sbc\_ana\_gyre} routine provides the analytical forcing for the GYRE configuration 
    582 (see GYRE configuration manual, in preparation). 
    583  
    584  
    585 % ================================================================ 
    586 % Flux formulation  
    587 % ================================================================ 
    588 \section[Flux formulation (\textit{sbcflx.F90})] 
    589 {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})} 
    590504\label{sec:SBC_flx} 
    591 %------------------------------------------namsbc_flx---------------------------------------------------- 
    592  
    593 \nlst{namsbc_flx}  
    594 %------------------------------------------------------------------------------------------------------------- 
    595  
    596 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}), 
    597513the surface boundary condition fields are directly read from input files. 
    598 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, 
    599515the name of the variable read in the file, the time frequency at which it is given (in hours), 
    600516and a logical setting whether a time interpolation to the model time step is required for this field. 
     
    604520See \autoref{subsec:SBC_ssr} for its specification. 
    605521 
    606  
    607 % ================================================================ 
    608 % Bulk formulation 
    609 % ================================================================ 
    610 \section[Bulk formulation {(\textit{sbcblk\{\_core,\_clio\}.F90})}] 
    611 {Bulk formulation {(\protect\mdl{sbcblk\_core}, \protect\mdl{sbcblk\_clio})}} 
     522%% ================================================================================================= 
     523\section[Bulk formulation (\textit{sbcblk.F90})]{Bulk formulation (\protect\mdl{sbcblk})} 
    612524\label{sec:SBC_blk} 
    613525 
    614 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. 
    615534 
    616535The atmospheric fields used depend on the bulk formulae used. 
    617 Two bulk formulations are available: 
    618 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. 
    619541The choice is made by setting to true one of the following namelist variable: 
    620 \np{ln\_core} or \np{ln\_clio}. 
    621  
    622 Note: 
    623 in forced mode, when a sea-ice model is used, a bulk formulation (CLIO or CORE) have to be used. 
    624 Therefore the two bulk (CLIO and CORE) formulea include the computation of the fluxes over 
    625 both an ocean and an ice surface.  
    626  
    627 % ------------------------------------------------------------------------------------------------------------- 
    628 %        CORE Bulk formulea 
    629 % ------------------------------------------------------------------------------------------------------------- 
    630 \subsection[CORE formulea (\textit{sbcblk\_core.F90}, \forcode{ln_core = .true.})] 
    631 {CORE formulea (\protect\mdl{sbcblk\_core}, \protect\np{ln\_core}\forcode{ = .true.})} 
    632 \label{subsec:SBC_blk_core} 
    633 %------------------------------------------namsbc_core---------------------------------------------------- 
    634 % 
    635 %\nlst{namsbc_core} 
    636 %------------------------------------------------------------------------------------------------------------- 
    637  
    638 The CORE bulk formulae have been developed by \citet{large.yeager_rpt04}. 
    639 They have been designed to handle the CORE forcing, a mixture of NCEP reanalysis and satellite data. 
    640 They use an inertial dissipative method to compute the turbulent transfer coefficients 
    641 (momentum, sensible heat and evaporation) from the 10 metre wind speed, air temperature and specific humidity. 
    642 This \citet{large.yeager_rpt04} dataset is available through 
    643 the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/CORE.html}{GFDL web site}. 
    644  
    645 Note that substituting ERA40 to NCEP reanalysis fields does not require changes in the bulk formulea themself. 
    646 This is the so-called DRAKKAR Forcing Set (DFS) \citep{brodeau.barnier.ea_OM10}. 
    647  
    648 Options are defined through the  \ngn{namsbc\_core} namelist variables. 
    649 The required 8 input fields are: 
    650  
    651 %--------------------------------------------------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 
    652549\begin{table}[htbp] 
    653   \label{tab:CORE} 
    654   \begin{center} 
    655     \begin{tabular}{|l|c|c|c|} 
    656       \hline 
    657       Variable desciption              & Model variable  & Units   & point \\    \hline 
    658       i-component of the 10m air velocity & utau      & $m.s^{-1}$         & T  \\  \hline 
    659       j-component of the 10m air velocity & vtau      & $m.s^{-1}$         & T  \\  \hline 
    660       10m air temperature              & tair      & \r{}$K$            & T   \\ \hline 
    661       Specific humidity             & humi      & \%              & T \\      \hline 
    662       Incoming long wave radiation     & qlw    & $W.m^{-2}$         & T \\      \hline 
    663       Incoming short wave radiation    & qsr    & $W.m^{-2}$         & T \\      \hline 
    664       Total precipitation (liquid + solid)   & precip & $Kg.m^{-2}.s^{-1}$ & T \\   \hline 
    665       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 
    666573    \end{tabular} 
    667   \end{center} 
     574  \label{tab:SBC_BULK} 
    668575\end{table} 
    669 %-------------------------------------------------------------------------------------------------------------- 
    670576 
    671577Note that the air velocity is provided at a tracer ocean point, not at a velocity ocean point ($u$- and $v$-points). 
     
    673579the ocean grid size is the same or larger than the one of the input atmospheric fields. 
    674580 
    675 The \np{sn\_wndi}, \np{sn\_wndj}, \np{sn\_qsr}, \np{sn\_qlw}, \np{sn\_tair}, \np{sn\_humi}, \np{sn\_prec}, 
    676 \np{sn\_snow}, \np{sn\_tdif} parameters describe the fields and the way they have to be used 
    677 (spatial and temporal interpolations).  
    678  
    679 \np{cn\_dir} is the directory of location of bulk files 
    680 \np{ln\_taudif} is the flag to specify if we use Hight Frequency (HF) tau information (.true.) or not (.false.) 
    681 \np{rn\_zqt}: is the height of humidity and temperature measurements (m) 
    682 \np{rn\_zu}: is the height of wind measurements (m) 
    683  
    684 Three multiplicative factors are availables:  
    685 \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 
    686592increasing/reducing the precipitations (total and snow) and or evaporation, respectively. 
    687 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 
    688594the calculation of surface wind stress. 
    689 Its range should be between zero and one, and it is recommended to set it to 0. 
    690  
    691 % ------------------------------------------------------------------------------------------------------------- 
    692 %        CLIO Bulk formulea 
    693 % ------------------------------------------------------------------------------------------------------------- 
    694 \subsection[CLIO formulea (\textit{sbcblk\_clio.F90}, \forcode{ln_clio = .true.})] 
    695 {CLIO formulea (\protect\mdl{sbcblk\_clio}, \protect\np{ln\_clio}\forcode{ = .true.})} 
    696 \label{subsec:SBC_blk_clio} 
    697 %------------------------------------------namsbc_clio---------------------------------------------------- 
    698 % 
    699 %\nlst{namsbc_clio} 
    700 %------------------------------------------------------------------------------------------------------------- 
    701  
    702 The CLIO bulk formulae were developed several years ago for the Louvain-la-neuve coupled ice-ocean model 
    703 (CLIO, \cite{goosse.deleersnijder.ea_JGR99}).  
    704 They are simpler bulk formulae. 
    705 They assume the stress to be known and compute the radiative fluxes from a climatological cloud cover.  
    706  
    707 Options are defined through the  \ngn{namsbc\_clio} namelist variables. 
    708 The required 7 input fields are: 
    709  
    710 %--------------------------------------------------TABLE-------------------------------------------------- 
    711 \begin{table}[htbp] 
    712   \label{tab:CLIO} 
    713   \begin{center} 
    714     \begin{tabular}{|l|l|l|l|} 
    715       \hline 
    716       Variable desciption           & Model variable  & Units           & point \\  \hline 
    717       i-component of the ocean stress     & utau         & $N.m^{-2}$         & U \\   \hline 
    718       j-component of the ocean stress     & vtau         & $N.m^{-2}$         & V \\   \hline 
    719       Wind speed module             & vatm         & $m.s^{-1}$         & T \\   \hline 
    720       10m air temperature              & tair         & \r{}$K$            & T \\   \hline 
    721       Specific humidity                & humi         & \%              & T \\   \hline 
    722       Cloud cover                   &           & \%              & T \\   \hline 
    723       Total precipitation (liquid + solid)   & precip    & $Kg.m^{-2}.s^{-1}$ & T \\   \hline 
    724       Solid precipitation              & snow         & $Kg.m^{-2}.s^{-1}$ & T \\   \hline 
    725     \end{tabular} 
    726   \end{center} 
    727 \end{table} 
    728 %-------------------------------------------------------------------------------------------------------------- 
     595Its range must be between zero and one, and it is recommended to set it to 0 at low-resolution (ORCA2 configuration). 
    729596 
    730597As for the flux formulation, information about the input data required by the model is provided in 
    731 the namsbc\_blk\_core or namsbc\_blk\_clio namelist (see \autoref{subsec:SBC_fldread}).  
    732  
    733 % ================================================================ 
    734 % Coupled formulation 
    735 % ================================================================ 
    736 \section[Coupled formulation (\textit{sbccpl.F90})] 
    737 {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})} 
    738650\label{sec:SBC_cpl} 
    739 %------------------------------------------namsbc_cpl---------------------------------------------------- 
    740  
    741 \nlst{namsbc_cpl}  
    742 %------------------------------------------------------------------------------------------------------------- 
     651 
     652\begin{listing} 
     653  \nlst{namsbc_cpl} 
     654  \caption{\forcode{&namsbc_cpl}} 
     655  \label{lst:namsbc_cpl} 
     656\end{listing} 
    743657 
    744658In the coupled formulation of the surface boundary condition, 
    745 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, 
    746660while sea and ice surface temperature, ocean and ice albedo, and ocean currents are sent to 
    747661the atmospheric component. 
    748662 
    749663A generalised coupled interface has been developed. 
    750 It is currently interfaced with OASIS-3-MCT (\key{oasis3}). 
    751 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 
    752667(ARPEGE, ECHAM, ECMWF, HadAM, HadGAM, LMDz), as well as to \href{http://wrf-model.org/}{WRF} 
    753668(Weather Research and Forecasting Model). 
    754669 
    755 Note that in addition to the setting of \np{ln\_cpl} to true, the \key{coupled} have to be defined. 
    756 The CPP key is mainly used in sea-ice to ensure that the atmospheric fluxes are actually received by 
    757 the ice-ocean system (no calculation of ice sublimation in coupled mode). 
    758 When PISCES biogeochemical model (\key{top} and \key{pisces}) is also used in the coupled system,  
    759 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. 
    760672In this case, CO$_2$ fluxes will be exchanged between the atmosphere and the ice-ocean system 
    761 (and need to be activated in \ngn{namsbc{\_}cpl} ). 
     673(and need to be activated in \nam{sbc_cpl}{sbc\_cpl} ). 
    762674 
    763675The namelist above allows control of various aspects of the coupling fields (particularly for vectors) and 
    764676now allows for any coupling fields to have multiple sea ice categories (as required by LIM3 and CICE). 
    765 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 
    766678the number used in the sea ice model. 
    767 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 
    768680the sea ice model is running with multiple categories - 
    769 in this case the user should examine the code to be sure the assumptions made are satisfactory. 
    770 In cases where this is definitely not possible the model should abort with an error message. 
    771 The new code has been tested using ECHAM with LIM2, and HadGAM3 with CICE but 
    772 although it will compile with \key{lim3} additional minor code changes may be required to run using LIM3. 
    773  
    774  
    775 % ================================================================ 
    776 %        Atmospheric pressure 
    777 % ================================================================ 
    778 \section[Atmospheric pressure (\textit{sbcapr.F90})] 
    779 {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})} 
    780686\label{sec:SBC_apr} 
    781 %------------------------------------------namsbc_apr---------------------------------------------------- 
    782  
    783 \nlst{namsbc_apr}  
    784 %------------------------------------------------------------------------------------------------------------- 
     687 
     688\begin{listing} 
     689  \nlst{namsbc_apr} 
     690  \caption{\forcode{&namsbc_apr}} 
     691  \label{lst:namsbc_apr} 
     692\end{listing} 
    785693 
    786694The optional atmospheric pressure can be used to force ocean and ice dynamics 
    787 (\np{ln\_apr\_dyn}\forcode{ = .true.}, \textit{\ngn{namsbc}} namelist). 
    788 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) 
    789697can be interpolated in time to the model time step, and even in space when the interpolation on-the-fly is used. 
    790698When used to force the dynamics, the atmospheric pressure is further transformed into 
     
    795703\] 
    796704where $P_{atm}$ is the atmospheric pressure and $P_o$ a reference atmospheric pressure. 
    797 A value of $101,000~N/m^2$ is used unless \np{ln\_ref\_apr} is set to true. 
    798 In this case $P_o$ is set to the value of $P_{atm}$ averaged over the ocean domain, 
    799 \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. 
    800708 
    801709The gradient of $\eta_{ib}$ is added to the RHS of the ocean momentum equation (see \mdl{dynspg} for the ocean). 
    802710For sea-ice, the sea surface height, $\eta_m$, which is provided to the sea ice model is set to $\eta - \eta_{ib}$ 
    803711(see \mdl{sbcssr} module). 
    804 $\eta_{ib}$ can be set in the output. 
     712$\eta_{ib}$ can be written in the output. 
    805713This can simplify altimetry data and model comparison as 
    806714inverse barometer sea surface height is usually removed from these date prior to their distribution. 
    807715 
    808716When using time-splitting and BDY package for open boundaries conditions, 
    809 the equivalent inverse barometer sea surface height $\eta_{ib}$ can be added to BDY ssh data:  
    810 \np{ln\_apr\_obc}  might be set to true. 
    811  
    812 % ================================================================ 
    813 %        Surface Tides Forcing 
    814 % ================================================================ 
    815 \section[Surface tides (\textit{sbctide.F90})] 
    816 {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})} 
    817722\label{sec:SBC_tide} 
    818723 
    819 %------------------------------------------nam_tide--------------------------------------- 
    820  
    821 \nlst{nam_tide} 
    822 %----------------------------------------------------------------------------------------- 
     724\begin{listing} 
     725  \nlst{nam_tide} 
     726  \caption{\forcode{&nam_tide}} 
     727  \label{lst:nam_tide} 
     728\end{listing} 
    823729 
    824730The tidal forcing, generated by the gravity forces of the Earth-Moon and Earth-Sun sytems, 
    825 is activated if \np{ln\_tide} and \np{ln\_tide\_pot} are both set to \forcode{.true.} in \ngn{nam\_tide}. 
    826 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: 
    827733\[ 
    828   % \label{eq:PE_dyn_tides} 
     734  % \label{eq:SBC_PE_dyn_tides} 
    829735  \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= ... 
    830736  +g\nabla (\Pi_{eq} + \Pi_{sal}) 
     
    832738where $\Pi_{eq}$ stands for the equilibrium tidal forcing and 
    833739$\Pi_{sal}$ is a self-attraction and loading term (SAL). 
    834   
     740 
    835741The equilibrium tidal forcing is expressed as a sum over a subset of 
    836742constituents chosen from the set of available tidal constituents 
    837 defined in file \rou{SBC/tide.h90} (this comprises the tidal 
     743defined in file \hf{SBC/tide} (this comprises the tidal 
    838744constituents \textit{M2, N2, 2N2, S2, K2, K1, O1, Q1, P1, M4, Mf, Mm, 
    839745  Msqm, Mtm, S1, MU2, NU2, L2}, and \textit{T2}). Individual 
    840746constituents are selected by including their names in the array 
    841 \np{clname} in \ngn{nam\_tide} (e.g., \np{clname(1) = 'M2', 
    842   clname(2)='S2'} to select solely the tidal consituents \textit{M2} 
    843 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 
    844750\forcode{.true.}, the equilibrium tidal forcing can be ramped up 
    845 linearly from zero during the initial \np{rdttideramp} days of the 
     751linearly from zero during the initial \np{rdttideramp}{rdttideramp} days of the 
    846752model run. 
    847753 
     
    850756discussion about the practical implementation of this term). 
    851757Nevertheless, the complex calculations involved would make this 
    852 computationally too expensive.  Here, two options are available: 
     758computationally too expensive. Here, two options are available: 
    853759$\Pi_{sal}$ generated by an external model can be read in 
    854 (\np{ln\_read\_load=.true.}), or a ``scalar approximation'' can be 
    855 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 
    856762\[ 
    857763  \Pi_{sal} = \beta \eta, 
    858764\] 
    859 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 
    860766spatially constant scalar, often chosen to minimize tidal prediction 
    861 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 
    862768\forcode{.false.} removes the SAL contribution. 
    863769 
    864 % ================================================================ 
    865 %        River runoffs 
    866 % ================================================================ 
    867 \section[River runoffs (\textit{sbcrnf.F90})] 
    868 {River runoffs (\protect\mdl{sbcrnf})} 
     770%% ================================================================================================= 
     771\section[River runoffs (\textit{sbcrnf.F90})]{River runoffs (\protect\mdl{sbcrnf})} 
    869772\label{sec:SBC_rnf} 
    870 %------------------------------------------namsbc_rnf---------------------------------------------------- 
    871  
    872 \nlst{namsbc_rnf}  
    873 %------------------------------------------------------------------------------------------------------------- 
    874  
    875 %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. 
    876781%Many models, however, have traditionally inserted river runoff to the top model cell. 
    877 %This was the case in \NEMO prior to the version 3.3. The switch toward a input of runoff  
    878 %throughout a nonzero depth has been motivated by the numerical and physical problems  
    879 %that arise when the top grid cells are of the order of one meter. This situation is common in  
    880 %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 
    881786%\footnote{At least a top cells thickness of 1~meter and a 3 hours forcing frequency are 
    882787%required to properly represent the diurnal cycle \citep{bernie.woolnough.ea_JC05}. see also \autoref{fig:SBC_dcy}.}. 
    883788 
    884  
    885 %To do this we need to treat evaporation/precipitation fluxes and river runoff differently in the  
    886 %\mdl{tra\_sbc} module.  We decided to separate them throughout the code, so that the variable  
    887 %\textit{emp} represented solely evaporation minus precipitation fluxes, and a new 2d variable  
    888 %rnf was added which represents the volume flux of river runoff (in kg/m2s to remain consistent with  
    889 %emp).  This meant many uses of emp and emps needed to be changed, a list of all modules which use  
     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 
    890794%emp or emps and the changes made are below: 
    891  
    892795 
    893796%Rachel: 
    894797River runoff generally enters the ocean at a nonzero depth rather than through the surface. 
    895798Many models, however, have traditionally inserted river runoff to the top model cell. 
    896 This was the case in \NEMO prior to the version 3.3, 
     799This was the case in \NEMO\ prior to the version 3.3, 
    897800and was combined with an option to increase vertical mixing near the river mouth. 
    898801 
    899802However, with this method numerical and physical problems arise when the top grid cells are of the order of one meter. 
    900 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 
    901804\footnote{ 
    902805  At least a top cells thickness of 1~meter and a 3 hours forcing frequency are required to 
     
    909812along with the depth (in metres) which the river should be added to. 
    910813 
    911 Namelist variables in \ngn{namsbc\_rnf}, \np{ln\_rnf\_depth}, \np{ln\_rnf\_sal} and 
    912 \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. 
    913816If these are set as false the river is added to the surface box only, assumed to be fresh (0~psu), 
    914817and/or taken as surface temperature respectively. 
    915818 
    916 The runoff value and attributes are read in in sbcrnf.   
     819The runoff value and attributes are read in in sbcrnf. 
    917820For temperature -999 is taken as missing data and the river temperature is taken to 
    918821be the surface temperatue at the river point. 
    919 For the depth parameter a value of -1 means the river is added to the surface box only,  
    920 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. 
    921824After being read in the temperature and salinity variables are multiplied by the amount of runoff 
    922825(converted into m/s) to give the heat and salt content of the river runoff. 
    923826After the user specified depth is read ini, 
    924 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}. 
    925828The variable \textit{h\_dep} is then calculated to be the depth (in metres) of 
    926829the bottom of the lowest box the river water is being added to 
    927 (\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). 
    928831 
    929832The mass/volume addition due to the river runoff is, at each relevant depth level, added to 
     
    931834This increases the diffusion term in the vicinity of the river, thereby simulating a momentum flux. 
    932835The sea surface height is calculated using the sum of the horizontal divergence terms, 
    933 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. 
    934837 
    935838The \textit{hdivn} terms are used in the tracer advection modules to force vertical velocities. 
     
    944847As such the volume of water does not change, but the water is diluted. 
    945848 
    946 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. 
    947850Instead in the surface box (as well as water moving up from the boxes below) a volume of runoff water is added with 
    948851no corresponding heat and salt addition and so as happens in the lower boxes there is a dilution effect. 
     
    953856This is done in the same way for both vvl and non-vvl. 
    954857The temperature and salinity are increased through the specified depth according to 
    955 the heat and salt content of the river.  
     858the heat and salt content of the river. 
    956859 
    957860In the non-linear free surface case (vvl), 
     
    962865 
    963866It is also possible for runnoff to be specified as a negative value for modelling flow through straits, 
    964 \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. 
    965868When the flow is out of the domain there is no change in temperature and salinity, 
    966869regardless of the namelist options used, 
    967 as the ocean water leaving the domain removes heat and salt (at the same concentration) with it.  
    968  
    969  
    970 %\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 
    971873 
    972874%All river runoff and emp fluxes are assumed to be fresh water (zero salinity) and at the same temperature as the sea surface.} 
     
    978880%ENDIF 
    979881 
    980 %\gmcomment{  word doc of runoffs: 
    981 % 
    982 %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. 
    983 %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.   
    984  
    985 %The depth option makes it possible to have the river water affecting just the surface layer, throughout depth, or some specified point in between. 
    986  
    987 %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: 
    988  
    989 %} 
    990 % ================================================================ 
    991 %        Ice shelf melting 
    992 % ================================================================ 
    993 \section[Ice shelf melting (\textit{sbcisf.F90})] 
    994 {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})} 
    995910\label{sec:SBC_isf} 
    996 %------------------------------------------namsbc_isf---------------------------------------------------- 
    997  
    998 \nlst{namsbc_isf} 
    999 %-------------------------------------------------------------------------------------------------------- 
    1000 The namelist variable in \ngn{namsbc}, \np{nn\_isf}, controls the ice shelf representation. 
    1001 Description and result of sensitivity test to \np{nn\_isf} are presented in \citet{mathiot.jenkins.ea_GMD17}.  
     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}. 
    1002920The different options are illustrated in \autoref{fig:SBC_isf}. 
    1003921 
    1004922\begin{description} 
    1005 \item[\np{nn\_isf}\forcode{ = 1}]: 
    1006   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). 
    1007924  The fwf and heat flux are depending of the local water properties. 
     925 
    1008926  Two different bulk formulae are available: 
    1009927 
    1010    \begin{description} 
    1011    \item[\np{nn\_isfblk}\forcode{ = 1}]: 
    1012      The melt rate is based on a balance between the upward ocean heat flux and 
    1013      the latent heat flux at the ice shelf base. A complete description is available in \citet{hunter_rpt06}. 
    1014    \item[\np{nn\_isfblk}\forcode{ = 2}]: 
    1015      The melt rate and the heat flux are based on a 3 equations formulation 
    1016      (a heat flux budget at the ice base, a salt flux budget at the ice base and a linearised freezing point temperature equation).  
    1017      A complete description is available in \citet{jenkins_JGR91}. 
    1018    \end{description} 
    1019  
    1020      Temperature and salinity used to compute the melt are the average temperature in the top boundary layer \citet{losch_JGR08}.  
    1021      Its thickness is defined by \np{rn\_hisf\_tbl}. 
    1022      The fluxes and friction velocity are computed using the mean temperature, salinity and velocity in the the first \np{rn\_hisf\_tbl} m. 
    1023      Then, the fluxes are spread over the same thickness (ie over one or several cells). 
    1024      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. 
    1025      This can lead to super-cool temperature in the top cell under melting condition. 
    1026      If \np{rn\_hisf\_tbl} smaller than top $e_{3}t$, the top boundary layer thickness is set to the top cell thickness.\\ 
    1027  
    1028      Each melt bulk formula depends on a exchange coeficient ($\Gamma^{T,S}$) between the ocean and the ice.  
    1029      There are 3 different ways to compute the exchange coeficient: 
    1030    \begin{description} 
    1031         \item[\np{nn\_gammablk}\forcode{ = 0}]: 
    1032      The salt and heat exchange coefficients are constant and defined by \np{rn\_gammas0} and \np{rn\_gammat0}.  
    1033 \[ 
    1034   % \label{eq:sbc_isf_gamma_iso} 
    1035 \gamma^{T} = \np{rn\_gammat0} 
    1036 \] 
    1037 \[ 
    1038 \gamma^{S} = \np{rn\_gammas0} 
    1039 \] 
    1040      This is the recommended formulation for ISOMIP. 
    1041    \item[\np{nn\_gammablk}\forcode{ = 1}]: 
    1042      The salt and heat exchange coefficients are velocity dependent and defined as 
    1043 \[ 
    1044 \gamma^{T} = \np{rn\_gammat0} \times u_{*}  
    1045 \] 
    1046 \[ 
    1047 \gamma^{S} = \np{rn\_gammas0} \times u_{*} 
    1048 \] 
    1049      where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters). 
    1050      See \citet{jenkins.nicholls.ea_JPO10} for all the details on this formulation. It is the recommended formulation for realistic application. 
    1051    \item[\np{nn\_gammablk}\forcode{ = 2}]: 
    1052      The salt and heat exchange coefficients are velocity and stability dependent and defined as: 
    1053 \[ 
    1054 \gamma^{T,S} = \frac{u_{*}}{\Gamma_{Turb} + \Gamma^{T,S}_{Mole}}  
    1055 \] 
    1056      where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters), 
    1057      $\Gamma_{Turb}$ the contribution of the ocean stability and 
    1058      $\Gamma^{T,S}_{Mole}$ the contribution of the molecular diffusion. 
    1059      See \citet{holland.jenkins_JPO99} for all the details on this formulation.  
    1060      This formulation has not been extensively tested in NEMO (not recommended). 
    1061    \end{description} 
    1062  \item[\np{nn\_isf}\forcode{ = 2}]: 
    1063    The ice shelf cavity is not represented. 
    1064    The fwf and heat flux are computed using the \citet{beckmann.goosse_OM03} parameterisation of isf melting. 
    1065    The fluxes are distributed along the ice shelf edge between the depth of the average grounding line (GL) 
    1066    (\np{sn\_depmax\_isf}) and the base of the ice shelf along the calving front 
    1067    (\np{sn\_depmin\_isf}) as in (\np{nn\_isf}\forcode{ = 3}). 
    1068    The effective melting length (\np{sn\_Leff\_isf}) is read from a file. 
    1069  \item[\np{nn\_isf}\forcode{ = 3}]: 
    1070    The ice shelf cavity is not represented. 
    1071    The fwf (\np{sn\_rnfisf}) is prescribed and distributed along the ice shelf edge between 
    1072    the depth of the average grounding line (GL) (\np{sn\_depmax\_isf}) and 
    1073    the base of the ice shelf along the calving front (\np{sn\_depmin\_isf}). 
    1074    The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$. 
    1075  \item[\np{nn\_isf}\forcode{ = 4}]: 
    1076    The ice shelf cavity is opened (\np{ln\_isfcav}\forcode{ = .true.} needed). 
    1077    However, the fwf is not computed but specified from file \np{sn\_fwfisf}). 
    1078    The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$. 
    1079    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}) 
    1080986\end{description} 
    1081987 
    1082 $\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 
    1083989the water mass properties, ocean velocities and depth. 
    1084990This flux is thus highly dependent of the model resolution (horizontal and vertical), 
    1085991realism of the water masses onto the shelf ...\\ 
    1086992 
    1087 $\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. 
    1088994You have total control of the fwf forcing. 
    1089995This can be useful if the water masses on the shelf are not realistic or 
    1090996the resolution (horizontal/vertical) are too coarse to have realistic melting or 
    1091 for studies where you need to control your heat and fw input.\\  
     997for studies where you need to control your heat and fw input.\\ 
    1092998 
    1093999The ice shelf melt is implemented as a volume flux as for the runoff. 
     
    10961002See the runoff section \autoref{sec:SBC_rnf} for all the details about the divergence correction.\\ 
    10971003 
    1098 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    10991004\begin{figure}[!t] 
    1100   \begin{center} 
    1101     \includegraphics[width=\textwidth]{Fig_SBC_isf} 
    1102     \caption{ 
    1103       \protect\label{fig:SBC_isf} 
    1104       Illustration the location where the fwf is injected and whether or not the fwf is interactif or not depending of \np{nn\_isf}. 
    1105     } 
    1106   \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} 
    11071011\end{figure} 
    1108 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1109  
     1012 
     1013%% ================================================================================================= 
    11101014\section{Ice sheet coupling} 
    11111015\label{sec:SBC_iscpl} 
    1112 %------------------------------------------namsbc_iscpl---------------------------------------------------- 
    1113  
    1114 \nlst{namsbc_iscpl} 
    1115 %-------------------------------------------------------------------------------------------------------- 
     1016 
     1017\begin{listing} 
     1018  \nlst{namsbc_iscpl} 
     1019  \caption{\forcode{&namsbc_iscpl}} 
     1020  \label{lst:namsbc_iscpl} 
     1021\end{listing} 
     1022 
    11161023Ice sheet/ocean coupling is done through file exchange at the restart step. 
    11171024At each restart step: 
    1118 \begin{description} 
    1119 \item[Step 1]: the ice sheet model send a new bathymetry and ice shelf draft netcdf file. 
    1120 \item[Step 2]: a new domcfg.nc file is built using the DOMAINcfg tools. 
    1121 \item[Step 3]: NEMO run for a specific period and output the average melt rate over the period. 
    1122 \item[Step 4]: the ice sheet model run using the melt rate outputed in step 4. 
    1123 \item[Step 5]: go back to 1. 
    1124 \end{description} 
    1125  
    1126 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 
    11271035potentially some new wet/dry cells due to the ice sheet dynamics/thermodynamics. 
    11281036The wetting and drying scheme applied on the restart is very simple and described below for the 6 different possible cases: 
     1037 
    11291038\begin{description} 
    1130 \item[Thin a cell down]: 
    1131   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 
    11321040  ($bt_b=bt_n$). 
    1133 \item[Enlarge  a cell]: 
    1134   See case "Thin a cell down" 
    1135 \item[Dry a cell]: 
    1136   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. 
    11371043  Furthermore, U/V into the water column are modified to satisfy ($bt_b=bt_n$). 
    1138 \item[Wet a cell]:  
    1139   mask is set to 1, T/S is extrapolated from neighbours, $ssh_n = ssh_b$ and U/V set to 0. 
    1140   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. 
    11411046  If no neighbours along i,j and k (both previous test failed), T/S/U/V/ssh and mask are set to 0. 
    1142 \item[Dry a column]: 
    1143    mask, T/S, U/V are set to 0 everywhere in the column and ssh set to 0. 
    1144 \item[Wet a column]: 
    1145   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. 
    11461049  If no neighbour, T/S/U/V and mask set to 0. 
    11471050\end{description} 
     
    11501053the restart time step is prescribed to be an euler time step instead of a leap frog and $fields_b = fields_n$.\\ 
    11511054 
    1152 The horizontal extrapolation to fill new cell with realistic value is called \np{nn\_drown} times. 
    1153 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, 
    11541057the code will be unable to fill all the new wet cells properly. 
    11551058The default number is set up for the MISOMIP idealised experiments. 
    11561059This coupling procedure is able to take into account grounding line and calving front migration. 
    1157 However, it is a non-conservative processe.  
     1060However, it is a non-conservative processe. 
    11581061This could lead to a trend in heat/salt content and volume.\\ 
    11591062 
    11601063In order to remove the trend and keep the conservation level as close to 0 as possible, 
    1161 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}. 
    11621065The heat/salt/vol. gain/loss is diagnosed, as well as the location. 
    1163 A correction increment is computed and apply each time step during the next \np{rn\_fiscpl} time steps.  
    1164 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). 
    11651068The 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). 
    11661069 
    1167 % 
    1168 % ================================================================ 
    1169 %        Handling of icebergs 
    1170 % ================================================================ 
     1070%% ================================================================================================= 
    11711071\section{Handling of icebergs (ICB)} 
    1172 \label{sec:ICB_icebergs} 
    1173 %------------------------------------------namberg---------------------------------------------------- 
    1174  
    1175 \nlst{namberg} 
    1176 %------------------------------------------------------------------------------------------------------------- 
    1177  
    1178 Icebergs are modelled as lagrangian particles in NEMO \citep{marsh.ivchenko.ea_GMD15}. 
     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}. 
    11791081Their physical behaviour is controlled by equations as described in \citet{martin.adcroft_OM10} ). 
    1180 (Note that the authors kindly provided a copy of their code to act as a basis for implementation in NEMO). 
     1082(Note that the authors kindly provided a copy of their code to act as a basis for implementation in \NEMO). 
    11811083Icebergs are initially spawned into one of ten classes which have specific mass and thickness as 
    1182 described in the \ngn{namberg} namelist: \np{rn\_initial\_mass} and \np{rn\_initial\_thickness}. 
    1183 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}), 
    11841086which is an integer representing how many icebergs of this class are being described as one lagrangian point 
    11851087(this reduces the numerical problem of tracking every single iceberg). 
    1186 They are enabled by setting \np{ln\_icebergs}\forcode{ = .true.}. 
     1088They are enabled by setting \np[=.true.]{ln_icebergs}{ln\_icebergs}. 
    11871089 
    11881090Two initialisation schemes are possible. 
    11891091\begin{description} 
    1190 \item[\np{nn\_test\_icebergs}~$>$~0] 
    1191   In this scheme, the value of \np{nn\_test\_icebergs} represents the class of iceberg to generate 
    1192   (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 
    11931094  which an iceberg is generated at the beginning of the run. 
    1194   (Note that this happens each time the timestep equals \np{nn\_nit000}.) 
    1195   \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 
    11961097  the geographical box: lonmin,lonmax,latmin,latmax 
    1197 \item[\np{nn\_test\_icebergs}\forcode{ = -1}] 
    1198   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. 
    11991099  This should be a file with a field on the configuration grid (typically ORCA) 
    12001100  representing ice accumulation rate at each model point. 
     
    12041104  At each time step, a test is performed to see if there is enough ice mass to 
    12051105  calve an iceberg of each class in order (1 to 10). 
    1206   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). 
    12071107  If there is enough ice, a new iceberg is spawned and the total available ice reduced accordingly. 
    12081108\end{description} 
     
    12111111The latter act to disintegrate the iceberg. 
    12121112This is either all melted freshwater, 
    1213 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 
    12141114which are assumed to propagate with their larger parent and thus delay fluxing into the ocean. 
    1215 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. 
    12161116 
    12171117Extensive diagnostics can be produced. 
    12181118Separate output files are maintained for human-readable iceberg information. 
    1219 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}). 
    12201120The amount of information is controlled by two integer parameters: 
    12211121\begin{description} 
    1222 \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 
    12231123  represents an increasing number of points in the code at which variables are written, 
    12241124  and an increasing level of obscurity. 
    1225 \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 
    12261126\end{description} 
    12271127 
    1228 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. 
    12291129A non-zero value represents how many timesteps between writes of information into the output file. 
    12301130These output files are in NETCDF format. 
     
    12341134since its trajectory data may be spread across multiple files. 
    12351135 
    1236 % ------------------------------------------------------------------------------------------------------------- 
    1237 %        Interactions with waves (sbcwave.F90, ln_wave) 
    1238 % ------------------------------------------------------------------------------------------------------------- 
    1239 \section[Interactions with waves (\textit{sbcwave.F90}, \texttt{ln\_wave})] 
    1240 {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})} 
    12411138\label{sec:SBC_wave} 
    1242 %------------------------------------------namsbc_wave-------------------------------------------------------- 
    1243  
    1244 \nlst{namsbc_wave} 
    1245 %------------------------------------------------------------------------------------------------------------- 
    1246  
    1247 Ocean waves represent the interface between the ocean and the atmosphere, so NEMO is extended to incorporate  
    1248 physical processes related to ocean surface waves, namely the surface stress modified by growth and  
    1249 dissipation of the oceanic wave field, the Stokes-Coriolis force and the Stokes drift impact on mass and  
    1250 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 
    12511150the wind stress. 
    12521151 
    1253 Physical processes related to ocean surface waves can be accounted by setting the logical variable  
    1254 \np{ln\_wave}\forcode{= .true.} in \ngn{namsbc} namelist. In addition, specific flags accounting for  
    1255 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. 
    12561155 
    12571156Wave fields can be provided either in forced or coupled mode: 
    12581157\begin{description} 
    1259 \item[forced mode]: wave fields should be defined through the \ngn{namsbc\_wave} namelist  
    1260 for external data names, locations, frequency, interpolation and all the miscellanous options allowed by  
    1261 Input Data generic Interface (see \autoref{sec:SBC_input}).  
    1262 \item[coupled mode]: NEMO and an external wave model can be coupled by setting \np{ln\_cpl} \forcode{= .true.}  
    1263 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. 
    12641163\end{description} 
    12651164 
    1266  
    1267 % ================================================================ 
    1268 % Neutral drag coefficient from wave model (ln_cdgw) 
    1269  
    1270 % ================================================================ 
    1271 \subsection[Neutral drag coefficient from wave model (\texttt{ln\_cdgw})] 
    1272 {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})} 
    12731167\label{subsec:SBC_wave_cdgw} 
    12741168 
    1275 The neutral surface drag coefficient provided from an external data source (\ie a wave model),  
    1276 can be used by setting the logical variable \np{ln\_cdgw} \forcode{= .true.} in \ngn{namsbc} namelist.  
    1277 Then using the routine \rou{turb\_ncar} and starting from the neutral drag coefficent provided,  
    1278 the drag coefficient is computed according to the stable/unstable conditions of the  
    1279 air-sea interface following \citet{large.yeager_rpt04}.  
    1280  
    1281  
    1282 % ================================================================ 
    1283 % 3D Stokes Drift (ln_sdw, nn_sdrift) 
    1284 % ================================================================ 
    1285 \subsection[3D Stokes Drift (\texttt{ln\_sdw}, \texttt{nn\_sdrift})] 
    1286 {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})} 
    12871177\label{subsec:SBC_wave_sdw} 
    12881178 
    1289 The Stokes drift is a wave driven mechanism of mass and momentum transport \citep{stokes_ibk09}.  
    1290 It is defined as the difference between the average velocity of a fluid parcel (Lagrangian velocity)  
    1291 and the current measured at a fixed point (Eulerian velocity).  
    1292 As waves travel, the water particles that make up the waves travel in orbital motions but  
    1293 without a closed path. Their movement is enhanced at the top of the orbit and slowed slightly  
    1294 at the bottom so the result is a net forward motion of water particles, referred to as the Stokes drift.  
    1295 An accurate evaluation of the Stokes drift and the inclusion of related processes may lead to improved  
    1296 representation of surface physics in ocean general circulation models. 
    1297 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: 
    12981188 
    12991189\[ 
    1300   % \label{eq:sbc_wave_sdw} 
     1190  % \label{eq:SBC_wave_sdw} 
    13011191  \mathbf{U}_{st} = \frac{16{\pi^3}} {g} 
    13021192  \int_0^\infty \int_{-\pi}^{\pi} (cos{\theta},sin{\theta}) {f^3} 
     
    13041194\] 
    13051195 
    1306 where: ${\theta}$ is the wave direction, $f$ is the wave intrinsic frequency,  
    1307 $\mathrm{S}($f$,\theta)$ is the 2D frequency-direction spectrum,  
    1308 $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: 
    13091199$k=\frac{2\pi}{\lambda}$ (being $\lambda$ the wavelength). \\ 
    13101200 
    1311 In order to evaluate the Stokes drift in a realistic ocean wave field the wave spectral shape is required  
    1312 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. 
    13131203To simplify, it is customary to use approximations to the full Stokes profile. 
    1314 Three possible parameterizations for the calculation for the approximate Stokes drift velocity profile  
    1315 are included in the code through the \np{nn\_sdrift} parameter once provided the surface Stokes drift  
    1316 $\mathbf{U}_{st |_{z=0}}$ which is evaluated by an external wave model that accurately reproduces the wave spectra  
    1317 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 
    13181208realistic wave conditions: 
    13191209 
    13201210\begin{description} 
    1321 \item[\np{nn\_sdrift} = 0]: exponential integral profile parameterization proposed by  
     1211\item [{\np{nn_sdrift}{nn\_sdrift} = 0}]: exponential integral profile parameterization proposed by 
    13221212\citet{breivik.janssen.ea_JPO14}: 
    13231213 
    13241214\[ 
    1325   % \label{eq:sbc_wave_sdw_0a} 
    1326   \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} 
    13271217\] 
    13281218 
     
    13301220 
    13311221\[ 
    1332   % \label{eq:sbc_wave_sdw_0b} 
     1222  % \label{eq:SBC_wave_sdw_0b} 
    13331223  k_e = \frac{|\mathbf{U}_{\left.st\right|_{z=0}}|} {|T_{st}|} 
    13341224  \quad \text{and }\ 
    1335   T_{st} = \frac{1}{16} \bar{\omega} H_s^2  
     1225  T_{st} = \frac{1}{16} \bar{\omega} H_s^2 
    13361226\] 
    13371227 
    13381228where $H_s$ is the significant wave height and $\omega$ is the wave frequency. 
    13391229 
    1340 \item[\np{nn\_sdrift} = 1]: velocity profile based on the Phillips spectrum which is considered to be a  
    1341 reasonable estimate of the part of the spectrum most contributing to the Stokes drift velocity near the surface 
     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 
    13421232\citep{breivik.bidlot.ea_OM16}: 
    13431233 
    13441234\[ 
    1345   % \label{eq:sbc_wave_sdw_1} 
     1235  % \label{eq:SBC_wave_sdw_1} 
    13461236  \mathbf{U}_{st} \cong \mathbf{U}_{st |_{z=0}} \Big[exp(2k_pz)-\beta \sqrt{-2 \pi k_pz} 
    13471237  \textit{ erf } \Big(\sqrt{-2 k_pz}\Big)\Big] 
     
    13501240where $erf$ is the complementary error function and $k_p$ is the peak wavenumber. 
    13511241 
    1352 \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 
    13531243but using the wave frequency from a wave model. 
    13541244 
    13551245\end{description} 
    13561246 
    1357 The Stokes drift enters the wave-averaged momentum equation, as well as the tracer advection equations  
    1358 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: 
    13591249 
    13601250\[ 
    1361   % \label{eq:sbc_wave_eta_sdw} 
     1251  % \label{eq:SBC_wave_eta_sdw} 
    13621252  \frac{\partial{\eta}}{\partial{t}} = 
    13631253  -\nabla_h \int_{-H}^{\eta} (\mathbf{U} + \mathbf{U}_{st}) dz 
    13641254\] 
    13651255 
    1366 The tracer advection equation is also modified in order for Eulerian ocean models to properly account  
    1367 for unresolved wave effect. The divergence of the wave tracer flux equals the mean tracer advection  
    1368 that is induced by the three-dimensional Stokes velocity.  
    1369 The advective equation for a tracer $c$ combining the effects of the mean current and sea surface waves  
    1370 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: 
    13711261 
    13721262\[ 
    1373   % \label{eq:sbc_wave_tra_sdw} 
     1263  % \label{eq:SBC_wave_tra_sdw} 
    13741264  \frac{\partial{c}}{\partial{t}} = 
    13751265  - (\mathbf{U} + \mathbf{U}_{st}) \cdot \nabla{c} 
    13761266\] 
    13771267 
    1378  
    1379 % ================================================================ 
    1380 % Stokes-Coriolis term (ln_stcor) 
    1381 % ================================================================ 
    1382 \subsection[Stokes-Coriolis term (\texttt{ln\_stcor})] 
    1383 {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})} 
    13841270\label{subsec:SBC_wave_stcor} 
    13851271 
    1386 In a rotating ocean, waves exert a wave-induced stress on the mean ocean circulation which results  
    1387 in a force equal to $\mathbf{U}_{st}$×$f$, where $f$ is the Coriolis parameter.  
    1388 This additional force may have impact on the Ekman turning of the surface current.  
    1389 In order to include this term, once evaluated the Stokes drift (using one of the 3 possible  
    1390 approximations described in \autoref{subsec:SBC_wave_sdw}),  
    1391 \np{ln\_stcor}\forcode{ = .true.} has to be set. 
    1392  
    1393  
    1394 % ================================================================ 
    1395 % Waves modified stress (ln_tauwoc, ln_tauw) 
    1396 % ================================================================ 
    1397 \subsection[Wave modified sress (\texttt{ln\_tauwoc}, \texttt{ln\_tauw})] 
    1398 {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})} 
    13991281\label{subsec:SBC_wave_tauw} 
    14001282 
    1401 The surface stress felt by the ocean is the atmospheric stress minus the net stress going  
    1402 into the waves \citep{janssen.breivik.ea_rpt13}. Therefore, when waves are growing, momentum and energy is spent and is not  
    1403 available for forcing the mean circulation, while in the opposite case of a decaying sea  
    1404 state more momentum is available for forcing the ocean.  
    1405 Only when the sea state is in equilibrium the ocean is forced by the atmospheric stress,  
    1406 but in practice an equilibrium sea state is a fairly rare event.  
    1407 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: 
    14081290 
    14091291\[ 
    1410   % \label{eq:sbc_wave_tauoc} 
     1292  % \label{eq:SBC_wave_tauoc} 
    14111293  \tau_{oc,a} = \tau_a - \tau_w 
    14121294\] 
     
    14161298 
    14171299\[ 
    1418   % \label{eq:sbc_wave_tauw} 
     1300  % \label{eq:SBC_wave_tauw} 
    14191301  \tau_w = \rho g \int {\frac{dk}{c_p} (S_{in}+S_{nl}+S_{diss})} 
    14201302\] 
    14211303 
    14221304where: $c_p$ is the phase speed of the gravity waves, 
    1423 $S_{in}$, $S_{nl}$ and $S_{diss}$ are three source terms that represent  
    1424 the physics of ocean waves. The first one, $S_{in}$, describes the generation  
    1425 of ocean waves by wind and therefore represents the momentum and energy transfer  
    1426 from air to ocean waves; the second term $S_{nl}$ denotes  
    1427 the nonlinear transfer by resonant four-wave interactions; while the third term $S_{diss}$  
    1428 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 
    14291311eddy-induced damping. 
    14301312 
    1431 The wave stress derived from an external wave model can be provided either through the normalized  
    1432 wave stress into the ocean by setting \np{ln\_tauwoc}\forcode{ = .true.}, or through the zonal and  
    1433 meridional stress components by setting \np{ln\_tauw}\forcode{ = .true.}. 
    1434  
    1435  
    1436 % ================================================================ 
    1437 % Miscellanea options 
    1438 % ================================================================ 
     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%% ================================================================================================= 
    14391318\section{Miscellaneous options} 
    14401319\label{sec:SBC_misc} 
    14411320 
    1442 % ------------------------------------------------------------------------------------------------------------- 
    1443 %        Diurnal cycle 
    1444 % ------------------------------------------------------------------------------------------------------------- 
    1445 \subsection[Diurnal cycle (\textit{sbcdcy.F90})] 
    1446 {Diurnal cycle (\protect\mdl{sbcdcy})} 
     1321%% ================================================================================================= 
     1322\subsection[Diurnal cycle (\textit{sbcdcy.F90})]{Diurnal cycle (\protect\mdl{sbcdcy})} 
    14471323\label{subsec:SBC_dcy} 
    1448 %------------------------------------------namsbc_rnf---------------------------------------------------- 
    1449 % 
    1450 \nlst{namsbc}  
    1451 %------------------------------------------------------------------------------------------------------------- 
    1452  
    1453 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     1324 
    14541325\begin{figure}[!t] 
    1455   \begin{center} 
    1456     \includegraphics[width=\textwidth]{Fig_SBC_diurnal} 
    1457     \caption{ 
    1458       \protect\label{fig:SBC_diurnal} 
    1459       Example of recontruction of the diurnal cycle variation of short wave flux from daily mean values. 
    1460       The reconstructed diurnal cycle (black line) is chosen as 
    1461       the mean value of the analytical cycle (blue line) over a time step, 
    1462       not as the mid time step value of the analytically cycle (red square). 
    1463       From \citet{bernie.guilyardi.ea_CD07}. 
    1464     } 
    1465   \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} 
    14661336\end{figure} 
    1467 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    14681337 
    14691338\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. 
    1470 Unfortunately high frequency forcing fields are rare, not to say inexistent. 
    1471 Nevertheless, it is possible to obtain a reasonable diurnal cycle of the SST knowning only short wave flux (SWF) at 
    1472 high frequency \citep{bernie.guilyardi.ea_CD07}. 
     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}. 
    14731341Furthermore, only the knowledge of daily mean value of SWF is needed, 
    14741342as higher frequency variations can be reconstructed from them, 
    14751343assuming that the diurnal cycle of SWF is a scaling of the top of the atmosphere diurnal cycle of incident SWF. 
    1476 The \cite{bernie.guilyardi.ea_CD07} reconstruction algorithm is available in \NEMO by 
    1477 setting \np{ln\_dm2dc}\forcode{ = .true.} (a \textit{\ngn{namsbc}} namelist variable) when 
    1478 using CORE bulk formulea (\np{ln\_blk\_core}\forcode{ = .true.}) or 
    1479 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}). 
    14801348The reconstruction is performed in the \mdl{sbcdcy} module. 
    14811349The detail of the algoritm used can be found in the appendix~A of \cite{bernie.guilyardi.ea_CD07}. 
    1482 The algorithm preserve the daily mean incoming SWF as the reconstructed SWF at 
     1350The algorithm preserves the daily mean incoming SWF as the reconstructed SWF at 
    14831351a given time step is the mean value of the analytical cycle over this time step (\autoref{fig:SBC_diurnal}). 
    14841352The use of diurnal cycle reconstruction requires the input SWF to be daily 
    1485 (\ie a frequency of 24 and a time interpolation set to true in \np{sn\_qsr} namelist parameter). 
    1486 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, 
    14871355that is  $\rdt \ nn\_fsbc < 10,800~s = 3~h$. 
    14881356An example of recontructed SWF is given in \autoref{fig:SBC_dcy} for a 12 reconstructed diurnal cycle, 
    14891357one every 2~hours (from 1am to 11pm). 
    14901358 
    1491 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    14921359\begin{figure}[!t] 
    1493   \begin{center} 
    1494     \includegraphics[width=\textwidth]{Fig_SBC_dcy} 
    1495     \caption{ 
    1496       \protect\label{fig:SBC_dcy} 
    1497       Example of recontruction of the diurnal cycle variation of short wave flux from 
    1498       daily mean values on an ORCA2 grid with a time sampling of 2~hours (from 1am to 11pm). 
    1499       The display is on (i,j) plane. 
    1500     } 
    1501   \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} 
    15021367\end{figure} 
    1503 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    15041368 
    15051369Note also that the setting a diurnal cycle in SWF is highly recommended when 
     
    15071371an inconsistency between the scale of the vertical resolution and the forcing acting on that scale. 
    15081372 
    1509 % ------------------------------------------------------------------------------------------------------------- 
    1510 %        Rotation of vector pairs onto the model grid directions 
    1511 % ------------------------------------------------------------------------------------------------------------- 
     1373%% ================================================================================================= 
    15121374\subsection{Rotation of vector pairs onto the model grid directions} 
    15131375\label{subsec:SBC_rotation} 
    15141376 
    1515 When using a flux (\np{ln\_flx}\forcode{ = .true.}) or 
    1516 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, 
    15171378pairs of vector components can be rotated from east-north directions onto the local grid directions. 
    15181379This is particularly useful when interpolation on the fly is used since here any vectors are likely to 
    15191380be defined relative to a rectilinear grid. 
    1520 To activate this option a non-empty string is supplied in the rotation pair column of the relevant namelist. 
    1521 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". 
    15221383The remaining characters in the strings are used to identify which pair of components go together. 
    15231384So for example, strings "U1" and "V1" next to "utau" and "vtau" would pair the wind stress components together and 
     
    15271388The rot\_rep routine from the \mdl{geo2ocean} module is used to perform the rotation. 
    15281389 
    1529 % ------------------------------------------------------------------------------------------------------------- 
    1530 %        Surface restoring to observed SST and/or SSS 
    1531 % ------------------------------------------------------------------------------------------------------------- 
    1532 \subsection[Surface restoring to observed SST and/or SSS (\textit{sbcssr.F90})] 
    1533 {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})} 
    15341392\label{subsec:SBC_ssr} 
    1535 %------------------------------------------namsbc_ssr---------------------------------------------------- 
    1536  
    1537 \nlst{namsbc_ssr}  
    1538 %------------------------------------------------------------------------------------------------------------- 
    1539  
    1540 IOptions are defined through the \ngn{namsbc\_ssr} namelist variables. 
    1541 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}), 
    15421402a feedback term \emph{must} be added to the surface heat flux $Q_{ns}^o$: 
    15431403\[ 
    1544   % \label{eq:sbc_dmp_q} 
     1404  % \label{eq:SBC_dmp_q} 
    15451405  Q_{ns} = Q_{ns}^o + \frac{dQ}{dT} \left( \left. T \right|_{k=1} - SST_{Obs} \right) 
    15461406\] 
     
    15481408$T$ is the model surface layer temperature and 
    15491409$\frac{dQ}{dT}$ is a negative feedback coefficient usually taken equal to $-40~W/m^2/K$. 
    1550 For a $50~m$ mixed-layer depth, this value corresponds to a relaxation time scale of two months.  
    1551 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$. 
    15521412 
    15531413In the fresh water budget, a feedback term can also be added. 
     
    15551415 
    15561416\begin{equation} 
    1557   \label{eq:sbc_dmp_emp} 
     1417  \label{eq:SBC_dmp_emp} 
    15581418  \textit{emp} = \textit{emp}_o + \gamma_s^{-1} e_{3t}  \frac{  \left(\left.S\right|_{k=1}-SSS_{Obs}\right)} 
    15591419  {\left.S\right|_{k=1}} 
     
    15661426$\left.S\right|_{k=1}$ is the model surface layer salinity and 
    15671427$\gamma_s$ is a negative feedback coefficient which is provided as a namelist parameter. 
    1568 Unlike heat flux, there is no physical justification for the feedback term in \autoref{eq:sbc_dmp_emp} as 
     1428Unlike heat flux, there is no physical justification for the feedback term in \autoref{eq:SBC_dmp_emp} as 
    15691429the atmosphere does not care about ocean surface salinity \citep{madec.delecluse_IWN97}. 
    15701430The SSS restoring term should be viewed as a flux correction on freshwater fluxes to 
    15711431reduce the uncertainties we have on the observed freshwater budget. 
    15721432 
    1573 % ------------------------------------------------------------------------------------------------------------- 
    1574 %        Handling of ice-covered area 
    1575 % ------------------------------------------------------------------------------------------------------------- 
     1433%% ================================================================================================= 
    15761434\subsection{Handling of ice-covered area  (\textit{sbcice\_...})} 
    15771435\label{subsec:SBC_ice-cover} 
     
    15791437The presence at the sea surface of an ice covered area modifies all the fluxes transmitted to the ocean. 
    15801438There are several way to handle sea-ice in the system depending on 
    1581 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. 
    15821440\begin{description} 
    1583 \item[nn{\_}ice = 0] 
    1584   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. 
    15851442  This is a typical namelist value used for tropical ocean domain. 
    15861443  The surface fluxes are simply specified for an ice-free ocean. 
    15871444  No specific things is done for sea-ice. 
    1588 \item[nn{\_}ice = 1] 
    1589   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. 
    15901446  An observed ice covered area is read in a file. 
    15911447  Below this area, the SST is restored to the freezing point and 
     
    15951451  This prevents deep convection to occur when trying to reach the freezing point 
    15961452  (and so ice covered area condition) while the SSS is too large. 
    1597   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, 
    15981454  is usually referred as the \textit{ice-if} model. 
    1599   It can be found in the \mdl{sbcice{\_}if} module. 
    1600 \item[nn{\_}ice = 2 or more] 
    1601   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. 
    16021457  This model computes the ice-ocean fluxes, 
    16031458  that are combined with the air-sea fluxes using the ice fraction of each model cell to 
    1604   provide the surface ocean fluxes. 
    1605   Note that the activation of a sea-ice model is is done by defining a CPP key (\key{lim3} or \key{cice}). 
    1606   The activation automatically overwrites the read value of nn{\_}ice to its appropriate value 
    1607   (\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). 
    16081463\end{description} 
    16091464 
    16101465% {Description of Ice-ocean interface to be added here or in LIM 2 and 3 doc ?} 
    1611  
    1612 \subsection[Interface to CICE (\textit{sbcice\_cice.F90})] 
    1613 {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})} 
    16141470\label{subsec:SBC_cice} 
    16151471 
    1616 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) 
    16171473to the CICE sea-ice model by using \key{cice}. 
    16181474The CICE code can be obtained from \href{http://oceans11.lanl.gov/trac/CICE/}{LANL} and 
    16191475the additional 'hadgem3' drivers will be required, even with the latest code release. 
    1620 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, 
    16211477and CICE CPP keys \textbf{ORCA\_GRID}, \textbf{CICE\_IN\_NEMO} and \textbf{coupled} should be used 
    16221478(seek advice from UKMO if necessary). 
    1623 Currently the code is only designed to work when using the CORE forcing option for NEMO 
    1624 (with \textit{calc\_strair}\forcode{ = .true.} and \textit{calc\_Tsfc}\forcode{ = .true.} in the CICE name-list), 
    1625 or alternatively when NEMO is coupled to the HadGAM3 atmosphere model 
    1626 (with \textit{calc\_strair}\forcode{ = .false.} and \textit{calc\_Tsfc}\forcode{ = false}). 
    1627 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 
    16281484(although coupling ocean and ice less frequently should work, 
    16291485it is possible the calculation of some of the ocean-ice fluxes needs to be modified slightly - 
    16301486the user should check that results are not significantly different to the standard case). 
    16311487 
    1632 There are two options for the technical coupling between NEMO and CICE. 
     1488There are two options for the technical coupling between \NEMO\ and CICE. 
    16331489The standard version allows complete flexibility for the domain decompositions in the individual models, 
    16341490but this is at the expense of global gather and scatter operations in the coupling which 
    16351491become very expensive on larger numbers of processors. 
    1636 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 
    16371493the domain decomposition is identical in both models (provided domain parameters are set appropriately, 
    16381494and \textit{processor\_shape~=~square-ice} and \textit{distribution\_wght~=~block} in the CICE name-list) and 
     
    16411497there is no sea ice. 
    16421498 
    1643 % ------------------------------------------------------------------------------------------------------------- 
    1644 %        Freshwater budget control  
    1645 % ------------------------------------------------------------------------------------------------------------- 
    1646 \subsection[Freshwater budget control (\textit{sbcfwb.F90})] 
    1647 {Freshwater budget control (\protect\mdl{sbcfwb})} 
     1499%% ================================================================================================= 
     1500\subsection[Freshwater budget control (\textit{sbcfwb.F90})]{Freshwater budget control (\protect\mdl{sbcfwb})} 
    16481501\label{subsec:SBC_fwb} 
    16491502 
    1650 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 
    16511504prevent unrealistic drift of the sea surface height due to inaccuracy in the freshwater fluxes. 
    1652 In \NEMO, two way of controlling the the freshwater budget.  
     1505In \NEMO, two way of controlling the freshwater budget are proposed: 
     1506 
    16531507\begin{description} 
    1654 \item[\np{nn\_fwb}\forcode{ = 0}] 
    1655   no control at all. 
     1508\item [{\np[=0]{nn_fwb}{nn\_fwb}}] no control at all. 
    16561509  The mean sea level is free to drift, and will certainly do so. 
    1657 \item[\np{nn\_fwb}\forcode{ = 1}] 
    1658   global mean \textit{emp} set to zero at each model time step.  
    1659 %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).  
    1660 \item[\np{nn\_fwb}\forcode{ = 2}] 
    1661   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 
    16621514  is read in the \textit{EMPave\_old.dat} file. 
    16631515  As the model uses the Boussinesq approximation, the annual mean fresh water budget is simply evaluated from 
    1664   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. 
    16651517\end{description} 
    16661518 
    1667  
    1668  
    16691519% Griffies doc: 
    1670 % When running ocean-ice simulations, we are not explicitly representing land processes,  
    1671 % such as rivers, catchment areas, snow accumulation, etc. However, to reduce model drift,  
    1672 % it is important to balance the hydrological cycle in ocean-ice models.  
    1673 % We thus need to prescribe some form of global normalization to the precipitation minus evaporation plus river runoff.  
    1674 % The result of the normalization should be a global integrated zero net water input to the ocean-ice system over  
    1675 % a chosen time scale.  
    1676 %How often the normalization is done is a matter of choice. In mom4p1, we choose to do so at each model time step,  
    1677 % so that there is always a zero net input of water to the ocean-ice system.  
    1678 % Others choose to normalize over an annual cycle, in which case the net imbalance over an annual cycle is used  
    1679 % to alter the subsequent year�s water budget in an attempt to damp the annual water imbalance.  
    1680 % Note that the annual budget approach may be inappropriate with interannually varying precipitation forcing.  
    1681 % When running ocean-ice coupled models, it is incorrect to include the water transport between the ocean  
    1682 % and ice models when aiming to balance the hydrological cycle.  
    1683 % 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,  
    1684 % not the water in any one sub-component. As an extreme example to illustrate the issue,  
    1685 % consider an ocean-ice model with zero initial sea ice. As the ocean-ice model spins up,  
    1686 % there should be a net accumulation of water in the growing sea ice, and thus a net loss of water from the ocean.  
    1687 % The total water contained in the ocean plus ice system is constant, but there is an exchange of water between  
    1688 % the subcomponents. This exchange should not be part of the normalization used to balance the hydrological cycle  
    1689 % in ocean-ice models.  
    1690  
    1691 \biblio 
    1692  
    1693 \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}} 
    16941542 
    16951543\end{document} 
  • NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_STO.tex

    r11123 r12149  
    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_OM13} 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 
     62The generic approach here is to a new STO module, 
     63generating processes features with appropriate statistics to simulate these uncertainties in the model 
    4864(see \cite{brankart.candille.ea_GMD15} for more details). 
    4965 
    50 In practice, at every model grid point, 
     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/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_TRA.tex

    r11179 r12149  
    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 (\textit{traadv.F90})] 
    63 {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})} 
    6478\label{sec:TRA_adv} 
    65 %------------------------------------------namtra_adv----------------------------------------------------- 
    66  
    67 \nlst{namtra_adv} 
    68 %------------------------------------------------------------------------------------------------------------- 
    69  
    70 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.}), 
    7187the advection tendency of a tracer is expressed in flux form, 
    72 \ie as the divergence of the advective fluxes. 
    73 Its discrete expression is given by : 
    74 \begin{equation} 
    75   \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} 
    7692  ADV_\tau = - \frac{1}{b_t} \Big(   \delta_i [ e_{2u} \, e_{3u} \; u \; \tau_u] 
    7793                                   + \delta_j [ e_{1v} \, e_{3v} \; v \; \tau_v] \Big) 
     
    7995\end{equation} 
    8096where $\tau$ is either T or S, and $b_t = e_{1t} \, e_{2t} \, e_{3t}$ is the volume of $T$-cells. 
    81 The flux form in \autoref{eq:tra_adv} implicitly requires the use of the continuity equation. 
    82 Indeed, it is obtained by using the following equality: $\nabla \cdot (\vect U \, T) = \vect U \cdot \nabla T$ which 
    83 results from the use of the continuity equation, $\partial_t e_3 + e_3 \; \nabla \cdot \vect U = 0$ 
    84 (which reduces to $\nabla \cdot \vect U = 0$ in linear free surface, \ie \np{ln\_linssh}\forcode{ = .true.}). 
    85 Therefore it is of paramount importance to design the discrete analogue of the advection tendency so that 
    86 it is consistent with the continuity equation in order to enforce the conservation properties of 
    87 the continuous equations. 
    88 In other words, by setting $\tau = 1$ in (\autoref{eq:tra_adv}) we recover the discrete form of 
    89 the continuity equation which is used to calculate the vertical velocity. 
    90 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    91 \begin{figure}[!t] 
    92   \begin{center} 
    93     \includegraphics[width=\textwidth]{Fig_adv_scheme} 
    94     \caption{ 
    95       \protect\label{fig:adv_scheme} 
    96       Schematic representation of some ways used to evaluate the tracer value at $u$-point and 
    97       the amount of tracer exchanged between two neighbouring grid points. 
    98       Upsteam biased scheme (ups): 
    99       the upstream value is used and the black area is exchanged. 
    100       Piecewise parabolic method (ppm): 
    101       a parabolic interpolation is used and the black and dark grey areas are exchanged. 
    102       Monotonic upstream scheme for conservative laws (muscl): 
    103       a parabolic interpolation is used and black, dark grey and grey areas are exchanged. 
    104       Second order scheme (cen2): 
    105       the mean value is used and black, dark grey, grey and light grey areas are exchanged. 
    106       Note that this illustration does not include the flux limiter used in ppm and muscl schemes. 
    107     } 
    108   \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} 
    109126\end{figure} 
    110 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    111  
    112 The key difference between the advection schemes available in \NEMO is the choice made in space and 
    113 time interpolation to define the value of the tracer at the velocity points 
    114 (\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}). 
    115131 
    116132Along solid lateral and bottom boundaries a zero tracer flux is automatically specified, 
     
    119135 
    120136\begin{description} 
    121 \item[linear free surface:] 
    122   (\np{ln\_linssh}\forcode{ = .true.}) 
     137\item [linear free surface] (\np[=.true.]{ln_linssh}{ln\_linssh}) 
    123138  the first level thickness is constant in time: 
    124   the vertical boundary condition is applied at the fixed surface $z = 0$ rather than on 
    125   the moving surface $z = \eta$. 
    126   There is a non-zero advective flux which is set for all advection schemes as 
    127   $\tau_w|_{k = 1/2} = T_{k = 1}$, \ie the product of surface velocity (at $z = 0$) by 
    128   the first level tracer value. 
    129 \item[non-linear free surface:] 
    130   (\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}) 
    131145  convergence/divergence in the first ocean level moves the free surface up/down. 
    132   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. 
    133148\end{description} 
    134149 
    135150In all cases, this boundary condition retains local conservation of tracer. 
    136 Global conservation is obtained in non-linear free surface case, but \textit{not} in the linear free surface case. 
    137 Nevertheless, in the latter case, it is achieved to a good approximation since 
    138 the non-conservative term is the product of the time derivative of the tracer and the free surface height, 
    139 two quantities that are not correlated \citep{roullet.madec_JGR00, griffies.pacanowski.ea_MWR01, campin.adcroft.ea_OM04}. 
    140  
    141 The velocity field that appears in (\autoref{eq:tra_adv} and \autoref{eq:tra_adv_zco?}) is 
    142 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 
    143161(see \autoref{chap:DYN}) plus the eddy induced velocity (\textit{eiv}) and/or 
    144162the mixed layer eddy induced velocity (\textit{eiv}) when those parameterisations are used 
    145163(see \autoref{chap:LDF}). 
    146164 
    147 Several tracer advection scheme are proposed, namely a $2^{nd}$ or $4^{th}$ order centred schemes (CEN), 
    148 a $2^{nd}$ or $4^{th}$ order Flux Corrected Transport scheme (FCT), a Monotone Upstream Scheme for 
    149 Conservative Laws scheme (MUSCL), a $3^{rd}$ Upstream Biased Scheme (UBS, also often called UP3), 
    150 and a Quadratic Upstream Interpolation for Convective Kinematics with Estimated Streaming Terms scheme (QUICKEST). 
    151 The choice is made in the \ngn{namtra\_adv} namelist, by setting to \forcode{.true.} one of 
    152 the logicals \textit{ln\_traadv\_xxx}. 
    153 The corresponding code can be found in the \textit{traadv\_xxx.F90} module, where 
    154 \textit{xxx} is a 3 or 4 letter acronym corresponding to each scheme. 
    155 By default (\ie in the reference namelist, \textit{namelist\_ref}), all the logicals are set to \forcode{.false.}. 
    156 If the user does not select an advection scheme in the configuration namelist (\textit{namelist\_cfg}), 
    157 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! 
    158182 
    159183Details of the advection schemes are given below. 
    160 The choosing an advection scheme is a complex matter which depends on the model physics, model resolution, 
    161 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 
    162187 
    163188\begin{enumerate} 
    164 \item 
    165   CEN and FCT schemes require an explicit diffusion operator while the other schemes are diffusive enough so that 
    166   they do not necessarily need additional diffusion; 
    167 \item 
    168   CEN and UBS are not \textit{positive} schemes 
    169   \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}, 
    170193  implying that false extrema are permitted. 
    171194  Their use is not recommended on passive tracers; 
    172 \item 
    173   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. 
    174197\end{enumerate} 
    175198 
    176 Indeed, if a source or sink of a passive tracer depends on an active one, the difference of treatment of active and 
    177 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. 
    178202Nevertheless, most of our users set a different treatment on passive and active tracers, 
    179203that's the reason why this possibility is offered. 
    180 We strongly suggest them to perform a sensitivity experiment using a same treatment to assess the robustness of 
    181 their results. 
    182  
    183 % ------------------------------------------------------------------------------------------------------------- 
    184 %        2nd and 4th order centred schemes 
    185 % ------------------------------------------------------------------------------------------------------------- 
    186 \subsection[CEN: Centred scheme (\forcode{ln_traadv_cen = .true.})] 
    187 {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})} 
    188209\label{subsec:TRA_adv_cen} 
    189210 
    190 %        2nd order centred scheme   
    191  
    192 The centred advection scheme (CEN) is used when \np{ln\_traadv\_cen}\forcode{ = .true.}. 
    193 Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) and vertical direction by 
    194 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$. 
    195217CEN implementation can be found in the \mdl{traadv\_cen} module. 
    196218 
    197 In the $2^{nd}$ order centred formulation (CEN2), the tracer at velocity points is evaluated as the mean of 
    198 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. 
    199221For example, in the $i$-direction : 
    200222\begin{equation} 
    201   \label{eq:tra_adv_cen2} 
     223  \label{eq:TRA_adv_cen2} 
    202224  \tau_u^{cen2} = \overline T ^{i + 1/2} 
    203225\end{equation} 
    204226 
    205 CEN2 is non diffusive (\ie it conserves the tracer variance, $\tau^2$) but dispersive 
    206 (\ie it may create false extrema). 
    207 It is therefore notoriously noisy and must be used in conjunction with an explicit diffusion operator to 
    208 produce a sensible solution. 
    209 The associated time-stepping is performed using a leapfrog scheme in conjunction with an Asselin time-filter, 
    210 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. 
    211234 
    212235Note that using the CEN2, the overall tracer advection is of second order accuracy since 
    213 both (\autoref{eq:tra_adv}) and (\autoref{eq:tra_adv_cen2}) have this order of accuracy. 
    214  
    215 %        4nd order centred scheme   
    216  
    217 In the $4^{th}$ order formulation (CEN4), tracer values are evaluated at u- and v-points as 
    218 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. 
    219243For example, in the $i$-direction: 
    220244\begin{equation} 
    221   \label{eq:tra_adv_cen4} 
     245  \label{eq:TRA_adv_cen4} 
    222246  \tau_u^{cen4} = \overline{T - \frac{1}{6} \, \delta_i \Big[ \delta_{i + 1/2}[T] \, \Big]}^{\,i + 1/2} 
    223247\end{equation} 
    224 In the vertical direction (\np{nn\_cen\_v}\forcode{ = 4}), 
     248In the vertical direction (\np[=4]{nn_cen_v}{nn\_cen\_v}), 
    225249a $4^{th}$ COMPACT interpolation has been prefered \citep{demange_phd14}. 
    226 In the COMPACT scheme, both the field and its derivative are interpolated, which leads, after a matrix inversion, 
    227 spectral characteristics similar to schemes of higher order \citep{lele_JCP92}.  
     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}. 
    228253 
    229254Strictly speaking, the CEN4 scheme is not a $4^{th}$ order advection scheme but 
    230255a $4^{th}$ order evaluation of advective fluxes, 
    231 since the divergence of advective fluxes \autoref{eq:tra_adv} is kept at $2^{nd}$ order. 
    232 The expression \textit{$4^{th}$ order scheme} used in oceanographic literature is usually associated with 
    233 the scheme presented here. 
    234 Introducing a \forcode{.true.} $4^{th}$ order advection scheme is feasible but, for consistency reasons, 
    235 it requires changes in the discretisation of the tracer advection together with changes in the continuity equation, 
    236 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. 
    237262 
    238263A direct consequence of the pseudo-fourth order nature of the scheme is that it is not non-diffusive, 
    239 \ie the global variance of a tracer is not preserved using CEN4. 
    240 Furthermore, it must be used in conjunction with an explicit diffusion operator to produce a sensible solution. 
    241 As in CEN2 case, the time-stepping is performed using a leapfrog scheme in conjunction with an Asselin time-filter, 
    242 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. 
    243269 
    244270At a $T$-grid cell adjacent to a boundary (coastline, bottom and surface), 
     
    246272This hypothesis usually reduces the order of the scheme. 
    247273Here we choose to set the gradient of $T$ across the boundary to zero. 
    248 Alternative conditions can be specified, such as a reduction to a second order scheme for 
    249 these near boundary grid points. 
    250  
    251 % ------------------------------------------------------------------------------------------------------------- 
    252 %        FCT scheme   
    253 % ------------------------------------------------------------------------------------------------------------- 
    254 \subsection[FCT: Flux Corrected Transport scheme (\forcode{ln_traadv_fct = .true.})] 
    255 {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})} 
    256279\label{subsec:TRA_adv_tvd} 
    257280 
    258 The Flux Corrected Transport schemes (FCT) is used when \np{ln\_traadv\_fct}\forcode{ = .true.}. 
    259 Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) and vertical direction by 
    260 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$. 
    261286FCT implementation can be found in the \mdl{traadv\_fct} module. 
    262287 
    263 In FCT formulation, the tracer at velocity points is evaluated using a combination of an upstream and 
    264 a centred scheme. 
     288In FCT formulation, the tracer at velocity points is evaluated using 
     289a combination of an upstream and a centred scheme. 
    265290For example, in the $i$-direction : 
    266291\begin{equation} 
    267   \label{eq:tra_adv_fct} 
     292  \label{eq:TRA_adv_fct} 
    268293  \begin{split} 
    269294    \tau_u^{ups} &= 
     
    271296                     T_{i + 1} & \text{if~} u_{i + 1/2} <    0 \\ 
    272297                     T_i       & \text{if~} u_{i + 1/2} \geq 0 \\ 
    273     \end{cases} 
    274     \\ 
     298    \end{cases} \\ 
    275299    \tau_u^{fct} &= \tau_u^{ups} + c_u \, \big( \tau_u^{cen} - \tau_u^{ups} \big) 
    276300  \end{split} 
     
    278302where $c_u$ is a flux limiter function taking values between 0 and 1. 
    279303The FCT order is the one of the centred scheme used 
    280 (\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}). 
    281305There exist many ways to define $c_u$, each corresponding to a different FCT scheme. 
    282 The one chosen in \NEMO is described in \citet{zalesak_JCP79}. 
     306The one chosen in \NEMO\ is described in \citet{zalesak_JCP79}. 
    283307$c_u$ only departs from $1$ when the advective term produces a local extremum in the tracer field. 
    284308The resulting scheme is quite expensive but \textit{positive}. 
     
    286310A comparison of FCT-2 with MUSCL and a MPDATA scheme can be found in \citet{levy.estublier.ea_GRL01}. 
    287311 
    288 An additional option has been added controlled by \np{nn\_fct\_zts}. 
    289 By setting this integer to a value larger than zero, 
    290 a $2^{nd}$ order FCT scheme is used on both horizontal and vertical direction, but on the latter, 
    291 a split-explicit time stepping is used, with a number of sub-timestep equals to \np{nn\_fct\_zts}. 
    292 This option can be useful when the size of the timestep is limited by vertical advection \citep{lemarie.debreu.ea_OM15}. 
    293 Note that in this case, a similar split-explicit time stepping should be used on vertical advection of momentum to 
    294 insure a better stability (see \autoref{subsec:DYN_zad}). 
    295  
    296 For stability reasons (see \autoref{chap:STP}), 
    297 $\tau_u^{cen}$ is evaluated in (\autoref{eq:tra_adv_fct}) using the \textit{now} tracer while 
     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 
    298314$\tau_u^{ups}$ is evaluated using the \textit{before} tracer. 
    299 In other words, the advective part of the scheme is time stepped with a leap-frog scheme 
    300 while a forward scheme is used for the diffusive part. 
    301  
    302 % ------------------------------------------------------------------------------------------------------------- 
    303 %        MUSCL scheme   
    304 % ------------------------------------------------------------------------------------------------------------- 
    305 \subsection[MUSCL: Monotone Upstream Scheme for Conservative Laws (\forcode{ln_traadv_mus = .true.})] 
    306 {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})} 
    307320\label{subsec:TRA_adv_mus} 
    308321 
    309 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}. 
    310324MUSCL implementation can be found in the \mdl{traadv\_mus} module. 
    311325 
    312 MUSCL has been first implemented in \NEMO by \citet{levy.estublier.ea_GRL01}. 
    313 In its formulation, the tracer at velocity points is evaluated assuming a linear tracer variation between 
    314 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}). 
    315329For example, in the $i$-direction : 
    316 \begin{equation} 
    317   % \label{eq:tra_adv_mus} 
     330\[ 
     331  % \label{eq:TRA_adv_mus} 
    318332  \tau_u^{mus} = \lt\{ 
    319333  \begin{split} 
    320                        \tau_i         &+ \frac{1}{2} \lt( 1 - \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt) 
    321                        \widetilde{\partial_i         \tau} & \text{if~} u_{i + 1/2} \geqslant 0 \\ 
    322                        \tau_{i + 1/2} &+ \frac{1}{2} \lt( 1 + \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt) 
    323                        \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 
    324338  \end{split} 
    325339                                                                                                      \rt. 
    326 \end{equation} 
    327 where $\widetilde{\partial_i \tau}$ is the slope of the tracer on which a limitation is imposed to 
    328 ensure the \textit{positive} character of the scheme. 
    329  
    330 The time stepping is performed using a forward scheme, that is the \textit{before} tracer field is used to 
    331 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}$. 
    332346 
    333347For an ocean grid point adjacent to land and where the ocean velocity is directed toward land, 
    334348an upstream flux is used. 
    335349This choice ensure the \textit{positive} character of the scheme. 
    336 In addition, fluxes round a grid-point where a runoff is applied can optionally be computed using upstream fluxes 
    337 (\np{ln\_mus\_ups}\forcode{ = .true.}). 
    338  
    339 % ------------------------------------------------------------------------------------------------------------- 
    340 %        UBS scheme   
    341 % ------------------------------------------------------------------------------------------------------------- 
    342 \subsection[UBS a.k.a. UP3: Upstream-Biased Scheme (\forcode{ln_traadv_ubs = .true.})] 
    343 {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})} 
    344355\label{subsec:TRA_adv_ubs} 
    345356 
    346 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}. 
    347359UBS implementation can be found in the \mdl{traadv\_mus} module. 
    348360 
    349361The UBS scheme, often called UP3, is also known as the Cell Averaged QUICK scheme 
    350 (Quadratic Upstream Interpolation for Convective Kinematics). 
     362(\textbf{Q}uadratic \textbf{U}pstream \textbf{I}nterpolation for 
     363\textbf{C}onvective \textbf{K}inematics). 
    351364It is an upstream-biased third order scheme based on an upstream-biased parabolic interpolation. 
    352365For example, in the $i$-direction: 
    353366\begin{equation} 
    354   \label{eq:tra_adv_ubs} 
     367  \label{eq:TRA_adv_ubs} 
    355368  \tau_u^{ubs} = \overline T ^{i + 1/2} - \frac{1}{6} 
    356369    \begin{cases} 
    357                                                       \tau"_i       & \text{if~} u_{i + 1/2} \geqslant 0 \\ 
    358                                                       \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 
    359372    \end{cases} 
    360   \quad 
    361   \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] 
    362374\end{equation} 
    363375 
    364376This results in a dissipatively dominant (i.e. hyper-diffusive) truncation error 
    365377\citep{shchepetkin.mcwilliams_OM05}. 
    366 The overall performance of the advection scheme is similar to that reported in \cite{farrow.stevens_JPO95}. 
     378The overall performance of the advection scheme is similar to that reported in 
     379\cite{farrow.stevens_JPO95}. 
    367380It is a relatively good compromise between accuracy and smoothness. 
    368381Nevertheless the scheme is not \textit{positive}, meaning that false extrema are permitted, 
    369382but the amplitude of such are significantly reduced over the centred second or fourth order method. 
    370 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. 
    371385 
    372386The intrinsic diffusion of UBS makes its use risky in the vertical direction where 
    373387the control of artificial diapycnal fluxes is of paramount importance 
    374388\citep{shchepetkin.mcwilliams_OM05, demange_phd14}. 
    375 Therefore the vertical flux is evaluated using either a $2^nd$ order FCT scheme or a $4^th$ order COMPACT scheme 
    376 (\np{nn\_cen\_v}\forcode{ = 2 or 4}). 
    377  
    378 For stability reasons (see \autoref{chap:STP}), the first term  in \autoref{eq:tra_adv_ubs} 
    379 (which corresponds to a second order centred scheme) 
    380 is evaluated using the \textit{now} tracer (centred in time) while the second term 
    381 (which is the diffusive part of the scheme), 
     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), 
    382396is evaluated using the \textit{before} tracer (forward in time). 
    383 This choice is discussed by \citet{webb.de-cuevas.ea_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. 
    384399UBS and QUICK schemes only differ by one coefficient. 
    385 Replacing 1/6 with 1/8 in \autoref{eq:tra_adv_ubs} leads to the QUICK advection scheme \citep{webb.de-cuevas.ea_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}. 
    386402This option is not available through a namelist parameter, since the 1/6 coefficient is hard coded. 
    387 Nevertheless it is quite easy to make the substitution in the \mdl{traadv\_ubs} module and obtain a QUICK scheme. 
    388  
    389 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: 
    390407\begin{gather} 
    391   \label{eq:traadv_ubs2} 
     408  \label{eq:TRA_adv_ubs2} 
    392409  \tau_u^{ubs} = \tau_u^{cen4} + \frac{1}{12} 
    393410    \begin{cases} 
     
    396413    \end{cases} 
    397414  \intertext{or equivalently} 
    398   % \label{eq:traadv_ubs2b} 
     415  % \label{eq:TRA_adv_ubs2b} 
    399416  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} 
    400417                             - \frac{1}{2} |u|_{i + 1/2} \, \frac{1}{6} \, \delta_{i + 1/2} [\tau"_i] \nonumber 
    401418\end{gather} 
    402419 
    403 \autoref{eq:traadv_ubs2} has several advantages. 
     420\autoref{eq:TRA_adv_ubs2} has several advantages. 
    404421Firstly, it clearly reveals that the UBS scheme is based on the fourth order scheme to which 
    405422an upstream-biased diffusion term is added. 
    406 Secondly, this emphasises that the $4^{th}$ order part (as well as the $2^{nd}$ order part as stated above) has to 
    407 be evaluated at the \textit{now} time step using \autoref{eq:tra_adv_ubs}. 
    408 Thirdly, the diffusion term is in fact a biharmonic operator with an eddy coefficient which 
    409 is simply proportional to the velocity: $A_u^{lm} = \frac{1}{12} \, {e_{1u}}^3 \, |u|$. 
    410 Note the current version of NEMO uses the computationally more efficient formulation \autoref{eq:tra_adv_ubs}. 
    411  
    412 % ------------------------------------------------------------------------------------------------------------- 
    413 %        QCK scheme   
    414 % ------------------------------------------------------------------------------------------------------------- 
    415 \subsection[QCK: QuiCKest scheme (\forcode{ln_traadv_qck = .true.})] 
    416 {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})} 
    417433\label{subsec:TRA_adv_qck} 
    418434 
    419 The Quadratic Upstream Interpolation for Convective Kinematics with Estimated Streaming Terms (QUICKEST) scheme 
    420 proposed by \citet{leonard_CMAME79} 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}. 
    421439QUICKEST implementation can be found in the \mdl{traadv\_qck} module. 
    422440 
    423441QUICKEST is the third order Godunov scheme which is associated with the ULTIMATE QUICKEST limiter 
    424442\citep{leonard_CMAME91}. 
    425 It has been implemented in NEMO by G. Reffray (MERCATOR-ocean) and can be found in the \mdl{traadv\_qck} module. 
     443It has been implemented in \NEMO\ by G. Reffray (Mercator Ocean) and 
     444can be found in the \mdl{traadv\_qck} module. 
    426445The resulting scheme is quite expensive but \textit{positive}. 
    427446It can be used on both active and passive tracers. 
     
    430449Therefore the vertical flux is evaluated using the CEN2 scheme. 
    431450This no longer guarantees the positivity of the scheme. 
    432 The use of FCT in the vertical direction (as for the UBS case) should be implemented to restore this property. 
    433  
    434 %%%gmcomment   :  Cross term are missing in the current implementation.... 
    435  
    436 % ================================================================ 
    437 % Tracer Lateral Diffusion 
    438 % ================================================================ 
    439 \section[Tracer lateral diffusion (\textit{traldf.F90})] 
    440 {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})} 
    441458\label{sec:TRA_ldf} 
    442 %-----------------------------------------nam_traldf------------------------------------------------------ 
    443  
    444 \nlst{namtra_ldf} 
    445 %------------------------------------------------------------------------------------------------------------- 
    446   
    447 Options are defined through the \ngn{namtra\_ldf} namelist variables. 
    448 They are regrouped in four items, allowing to specify  
    449 $(i)$   the type of operator used (none, laplacian, bilaplacian), 
    450 $(ii)$  the direction along which the operator acts (iso-level, horizontal, iso-neutral), 
    451 $(iii)$ some specific options related to the rotated operators (\ie non-iso-level operator), and 
    452 $(iv)$  the specification of eddy diffusivity coefficient (either constant or variable in space and time). 
    453 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}. 
    454476The direction along which the operators act is defined through the slope between 
    455477this direction and the iso-level surfaces. 
     
    457479 
    458480The lateral diffusion of tracers is evaluated using a forward scheme, 
    459 \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, 
    460482except for the pure vertical component that appears when a rotation tensor is used. 
    461 This latter component is solved implicitly together with the vertical diffusion term (see \autoref{chap:STP}). 
    462 When \np{ln\_traldf\_msc}\forcode{ = .true.}, a Method of Stabilizing Correction is used in which 
    463 the pure vertical component is split into an explicit and an implicit part \citep{lemarie.debreu.ea_OM12}. 
    464  
    465 % ------------------------------------------------------------------------------------------------------------- 
    466 %        Type of operator 
    467 % ------------------------------------------------------------------------------------------------------------- 
    468 \subsection[Type of operator (\texttt{ln\_traldf}\{\texttt{\_NONE,\_lap,\_blp}\})] 
    469 {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})} 
    470491\label{subsec:TRA_ldf_op} 
    471492 
     
    473494 
    474495\begin{description} 
    475 \item[\np{ln\_traldf\_NONE}\forcode{ = .true.}:] 
    476   no operator selected, the lateral diffusive tendency will not be applied to the tracer equation. 
    477   This option can be used when the selected advection scheme is diffusive enough (MUSCL scheme for example). 
    478 \item[\np{ln\_traldf\_lap}\forcode{ = .true.}:] 
    479   a laplacian operator is selected. 
    480   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 $, 
    481503  where the gradient operates along the selected direction (see \autoref{subsec:TRA_ldf_dir}), 
    482504  and $A_{ht}$ is the eddy diffusivity coefficient expressed in $m^2/s$ (see \autoref{chap:LDF}). 
    483 \item[\np{ln\_traldf\_blp}\forcode{ = .true.}]: 
    484   a bilaplacian operator is selected. 
     505\item [{\np[=.true.]{ln_traldf_blp}{ln\_traldf\_blp}}] a bilaplacian operator is selected. 
    485506  This biharmonic operator takes the following expression: 
    486   $\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)$ 
    487508  where the gradient operats along the selected direction, 
    488   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}). 
    489511  In the code, the bilaplacian operator is obtained by calling the laplacian twice. 
    490512\end{description} 
     
    494516minimizing the impact on the larger scale features. 
    495517The main difference between the two operators is the scale selectiveness. 
    496 The bilaplacian damping time (\ie its spin down time) scales like $\lambda^{-4}$ for 
    497 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), 
    498521whereas the laplacian damping time scales only like $\lambda^{-2}$. 
    499522 
    500 % ------------------------------------------------------------------------------------------------------------- 
    501 %        Direction of action 
    502 % ------------------------------------------------------------------------------------------------------------- 
    503 \subsection[Action direction (\texttt{ln\_traldf}\{\texttt{\_lev,\_hor,\_iso,\_triad}\})] 
    504 {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})} 
    505525\label{subsec:TRA_ldf_dir} 
    506526 
    507527The choice of a direction of action determines the form of operator used. 
    508528The operator is a simple (re-entrant) laplacian acting in the (\textbf{i},\textbf{j}) plane when 
    509 iso-level option is used (\np{ln\_traldf\_lev}\forcode{ = .true.}) or 
    510 when a horizontal (\ie geopotential) operator is demanded in \textit{z}-coordinate 
    511 (\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}). 
    512532The associated code can be found in the \mdl{traldf\_lap\_blp} module. 
    513533The operator is a rotated (re-entrant) laplacian when 
    514534the direction along which it acts does not coincide with the iso-level surfaces, 
    515535that is when standard or triad iso-neutral option is used 
    516 (\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.}, 
    517537see \mdl{traldf\_iso} or \mdl{traldf\_triad} module, resp.), or 
    518 when a horizontal (\ie geopotential) operator is demanded in \textit{s}-coordinate 
    519 (\np{ln\_traldf\_hor} and \np{ln\_sco} equal \forcode{.true.}) 
    520 \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}. 
    521541In that case, a rotation is applied to the gradient(s) that appears in the operator so that 
    522542diffusive fluxes acts on the three spatial direction. 
     
    525545the next two sub-sections. 
    526546 
    527 % ------------------------------------------------------------------------------------------------------------- 
    528 %       iso-level operator 
    529 % ------------------------------------------------------------------------------------------------------------- 
    530 \subsection[Iso-level (bi-)laplacian operator (\texttt{ln\_traldf\_iso})] 
    531 {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})} 
    532549\label{subsec:TRA_ldf_lev} 
    533550 
    534 The laplacian diffusion operator acting along the model (\textit{i,j})-surfaces is given by:  
    535 \begin{equation} 
    536   \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} 
    537554  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] 
    538555                                  + \delta_{j} \lt[ A_v^{lT} \; \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [T] \rt] \Bigg) 
     
    541558where zero diffusive fluxes is assumed across solid boundaries, 
    542559first (and third in bilaplacian case) horizontal tracer derivative are masked. 
    543 It is implemented in the \rou{traldf\_lap} subroutine found in the \mdl{traldf\_lap} module. 
    544 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 
    545563compute the iso-level bilaplacian operator. 
    546564 
    547565It is a \textit{horizontal} operator (\ie acting along geopotential surfaces) in 
    548 the $z$-coordinate with or without partial steps, but is simply an iso-level operator in the $s$-coordinate. 
    549 It is thus used when, in addition to \np{ln\_traldf\_lap} or \np{ln\_traldf\_blp}\forcode{ = .true.}, 
    550 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}. 
    551572In both cases, it significantly contributes to diapycnal mixing. 
    552573It is therefore never recommended, even when using it in the bilaplacian case. 
    553574 
    554 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}), 
    555576tracers in horizontally adjacent cells are located at different depths in the vicinity of the bottom. 
    556 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. 
    557579They are calculated in the \mdl{zpshde} module, described in \autoref{sec:TRA_zpshde}. 
    558580 
    559 % ------------------------------------------------------------------------------------------------------------- 
    560 %         Rotated laplacian operator 
    561 % ------------------------------------------------------------------------------------------------------------- 
     581%% ================================================================================================= 
    562582\subsection{Standard and triad (bi-)laplacian operator} 
    563583\label{subsec:TRA_ldf_iso_triad} 
    564584 
    565 %&&    Standard rotated (bi-)laplacian operator 
    566 %&& ---------------------------------------------- 
    567 \subsubsection[Standard rotated (bi-)laplacian operator (\textit{traldf\_iso.F90})] 
    568 {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})} 
    569587\label{subsec:TRA_ldf_iso} 
    570 The general form of the second order lateral tracer subgrid scale physics (\autoref{eq:PE_zdf}) 
    571 takes the following semi -discrete space form in $z$- and $s$-coordinates: 
    572 \begin{equation} 
    573   \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} 
    574593  \begin{split} 
    575594    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] 
     
    584603where $b_t = e_{1t} \, e_{2t} \, e_{3t}$  is the volume of $T$-cells, 
    585604$r_1$ and $r_2$ are the slopes between the surface of computation ($z$- or $s$-surfaces) and 
    586 the surface along which the diffusion operator acts (\ie horizontal or iso-neutral surfaces). 
    587 It is thus used when, in addition to \np{ln\_traldf\_lap}\forcode{ = .true.}, 
    588 we have \np{ln\_traldf\_iso}\forcode{ = .true.}, 
    589 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}. 
    590609The way these slopes are evaluated is given in \autoref{sec:LDF_slp}. 
    591 At the surface, bottom and lateral boundaries, the turbulent fluxes of heat and salt are set to zero using 
    592 the mask technique (see \autoref{sec:LBC_coast}). 
    593  
    594 The operator in \autoref{eq:tra_ldf_iso} involves both lateral and vertical derivatives. 
    595 For numerical stability, the vertical second derivative must be solved using the same implicit time scheme as that 
    596 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}). 
    597617For computer efficiency reasons, this term is not computed in the \mdl{traldf\_iso} module, 
    598618but in the \mdl{trazdf} module where, if iso-neutral mixing is used, 
    599 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)$. 
    600621 
    601622This formulation conserves the tracer but does not ensure the decrease of the tracer variance. 
    602 Nevertheless the treatment performed on the slopes (see \autoref{chap:LDF}) allows the model to run safely without 
    603 any additional background horizontal diffusion \citep{guilyardi.madec.ea_CD01}. 
    604  
    605 Note that in the partial step $z$-coordinate (\np{ln\_zps}\forcode{ = .true.}), 
    606 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. 
    607629They are calculated in module zpshde, described in \autoref{sec:TRA_zpshde}. 
    608630 
    609 %&&     Triad rotated (bi-)laplacian operator 
    610 %&&  ------------------------------------------- 
    611 \subsubsection[Triad rotated (bi-)laplacian operator (\textit{ln\_traldf\_triad})] 
    612 {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})} 
    613633\label{subsec:TRA_ldf_triad} 
    614634 
    615 If the Griffies triad scheme is employed (\np{ln\_traldf\_triad}\forcode{ = .true.}; see \autoref{apdx:triad}) 
    616  
    617 An alternative scheme developed by \cite{griffies.gnanadesikan.ea_JPO98} which ensures tracer variance decreases 
    618 is also available in \NEMO (\np{ln\_traldf\_grif}\forcode{ = .true.}). 
    619 A complete description of the algorithm is given in \autoref{apdx:triad}. 
    620  
    621 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. 
    622642The operator requires an additional assumption on boundary conditions: 
    623643both first and third derivative terms normal to the coast are set to zero. 
    624644 
    625 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. 
    626647It requires an additional assumption on boundary conditions: 
    627648first and third derivative terms normal to the coast, 
    628649normal to the bottom and normal to the surface are set to zero. 
    629650 
    630 %&&    Option for the rotated operators 
    631 %&& ---------------------------------------------- 
     651%% ================================================================================================= 
    632652\subsubsection{Option for the rotated operators} 
    633653\label{subsec:TRA_ldf_options} 
    634654 
    635 \begin{itemize} 
    636 \item \np{ln\_traldf\_msc} = Method of Stabilizing Correction (both operators) 
    637 \item \np{rn\_slpmax} = slope limit (both operators) 
    638 \item \np{ln\_triad\_iso} = pure horizontal mixing in ML (triad only) 
    639 \item \np{rn\_sw\_triad} $= 1$ switching triad; $= 0$ all 4 triads used (triad only)  
    640 \item \np{ln\_botmix\_triad} = lateral mixing on bottom (triad only) 
    641 \end{itemize} 
    642  
    643 % ================================================================ 
    644 % Tracer Vertical Diffusion 
    645 % ================================================================ 
    646 \section[Tracer vertical diffusion (\textit{trazdf.F90})] 
    647 {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})} 
    648666\label{sec:TRA_zdf} 
    649 %--------------------------------------------namzdf--------------------------------------------------------- 
    650  
    651 \nlst{namzdf} 
    652 %-------------------------------------------------------------------------------------------------------------- 
    653  
    654 Options are defined through the \ngn{namzdf} namelist variables. 
    655 The formulation of the vertical subgrid scale tracer physics is the same for all the vertical coordinates, 
    656 and is based on a laplacian operator. 
    657 The vertical diffusion operator given by (\autoref{eq:PE_zdf}) takes the following semi -discrete space form: 
    658 \begin{gather*} 
    659   % \label{eq:tra_zdf} 
    660     D^{vT}_T = \frac{1}{e_{3t}} \, \delta_k \lt[ \, \frac{A^{vT}_w}{e_{3w}} \delta_{k + 1/2}[T] \, \rt] \\ 
    661     D^{vS}_T = \frac{1}{e_{3t}} \; \delta_k \lt[ \, \frac{A^{vS}_w}{e_{3w}} \delta_{k + 1/2}[S] \, \rt] 
    662 \end{gather*} 
    663 where $A_w^{vT}$ and $A_w^{vS}$ are the vertical eddy diffusivity coefficients on temperature and salinity, 
    664 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. 
    665680Generally, $A_w^{vT} = A_w^{vS}$ except when double diffusive mixing is parameterised 
    666 (\ie \key{zdfddm} is defined). 
     681(\ie\ \np[=.true.]{ln_zdfddm}{ln\_zdfddm},). 
    667682The way these coefficients are evaluated is given in \autoref{chap:ZDF} (ZDF). 
    668 Furthermore, when iso-neutral mixing is used, both mixing coefficients are increased by 
    669 $\frac{e_{1w} e_{2w}}{e_{3w} }({r_{1w}^2 + r_{2w}^2})$ to account for the vertical second derivative of 
    670 \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}. 
    671686 
    672687At the surface and bottom boundaries, the turbulent fluxes of heat and salt must be specified. 
     
    675690a geothermal flux forcing is prescribed as a bottom boundary condition (see \autoref{subsec:TRA_bbc}). 
    676691 
    677 The large eddy coefficient found in the mixed layer together with high vertical resolution implies that 
    678 in the case of explicit time stepping (\np{ln\_zdfexp}\forcode{ = .true.}) 
    679 there would be too restrictive a constraint on the time step. 
    680 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 
    681695it overcomes the stability constraint. 
    682 A forward time differencing scheme (\np{ln\_zdfexp}\forcode{ = .true.}) using 
    683 a time splitting technique (\np{nn\_zdfexp} $> 1$) is provided as an alternative. 
    684 Namelist variables \np{ln\_zdfexp} and \np{nn\_zdfexp} apply to both tracers and dynamics. 
    685  
    686 % ================================================================ 
    687 % External Forcing 
    688 % ================================================================ 
     696 
     697%% ================================================================================================= 
    689698\section{External forcing} 
    690699\label{sec:TRA_sbc_qsr_bbc} 
    691700 
    692 % ------------------------------------------------------------------------------------------------------------- 
    693 %        surface boundary condition 
    694 % ------------------------------------------------------------------------------------------------------------- 
    695 \subsection[Surface boundary condition (\textit{trasbc.F90})] 
    696 {Surface boundary condition (\protect\mdl{trasbc})} 
     701%% ================================================================================================= 
     702\subsection[Surface boundary condition (\textit{trasbc.F90})]{Surface boundary condition (\protect\mdl{trasbc})} 
    697703\label{subsec:TRA_sbc} 
    698704 
     
    704710 
    705711Due to interactions and mass exchange of water ($F_{mass}$) with other Earth system components 
    706 (\ie atmosphere, sea-ice, land), the change in the heat and salt content of the surface layer of the ocean is due 
    707 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 
    708715to the heat and salt content of the mass exchange. 
    709716They are both included directly in $Q_{ns}$, the surface heat flux, 
    710717and $F_{salt}$, the surface salt flux (see \autoref{chap:SBC} for further details). 
    711 By doing this, the forcing formulation is the same for any tracer (including temperature and salinity). 
    712  
    713 The surface module (\mdl{sbcmod}, see \autoref{chap:SBC}) provides the following forcing fields (used on tracers): 
    714  
    715 \begin{itemize} 
    716 \item 
    717   $Q_{ns}$, the non-solar part of the net surface heat flux that crosses the sea surface 
    718   (\ie the difference between the total surface heat flux and the fraction of the short wave flux that 
    719   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}) 
    720729  plus the heat content associated with of the mass exchange with the atmosphere and lands. 
    721 \item 
    722   $\textit{sfx}$, the salt flux resulting from ice-ocean mass exchange (freezing, melting, ridging...) 
    723 \item 
    724   \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 
    725733  possibly with the sea-ice and ice-shelves. 
    726 \item 
    727   \textit{rnf}, the mass flux associated with runoff 
     734\item [\textit{rnf}] The mass flux associated with runoff 
    728735  (see \autoref{sec:SBC_rnf} for further detail of how it acts on temperature and salinity tendencies) 
    729 \item 
    730   \textit{fwfisf}, the mass flux associated with ice shelf melt, 
     736\item [\textit{fwfisf}] The mass flux associated with ice shelf melt, 
    731737  (see \autoref{sec:SBC_isf} for further details on how the ice shelf melt is computed and applied). 
    732 \end{itemize} 
     738\end{labeling} 
    733739 
    734740The surface boundary condition on temperature and salinity is applied as follows: 
    735741\begin{equation} 
    736   \label{eq:tra_sbc} 
    737   \begin{alignedat}{2} 
    738     F^T &= \frac{1}{C_p} &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} &\overline{Q_{ns}      }^t \\ 
    739     F^S &=               &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} &\overline{\textit{sfx}}^t 
    740   \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 
    741745\end{equation} 
    742746where $\overline x^t$ means that $x$ is averaged over two consecutive time steps 
    743747($t - \rdt / 2$ and $t + \rdt / 2$). 
    744 Such time averaging prevents the divergence of odd and even time step (see \autoref{chap:STP}). 
    745  
    746 In the linear free surface case (\np{ln\_linssh}\forcode{ = .true.}), an additional term has to be added on 
    747 both temperature and salinity. 
    748 On temperature, this term remove the heat content associated with mass exchange that has been added to $Q_{ns}$. 
    749 On salinity, this term mimics the concentration/dilution effect that would have resulted from a change in 
    750 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. 
    751756The resulting surface boundary condition is applied as follows: 
    752757\begin{equation} 
    753   \label{eq:tra_sbc_lin} 
    754   \begin{alignedat}{2} 
    755     F^T &= \frac{1}{C_p} &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} 
    756           &\overline{(Q_{ns}       - C_p \, \textit{emp} \lt. T \rt|_{k = 1})}^t \\ 
    757     F^S &=               &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} 
    758           &\overline{(\textit{sfx} -        \textit{emp} \lt. S \rt|_{k = 1})}^t 
    759   \end{alignedat} 
    760 \end{equation}  
    761 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. 
    762766In the linear free surface case, there is a small imbalance. 
    763 The imbalance is larger than the imbalance associated with the Asselin time filter \citep{leclair.madec_OM09}. 
    764 This is the reason why the modified filter is not applied in the linear free surface case (see \autoref{chap:STP}). 
    765  
    766 % ------------------------------------------------------------------------------------------------------------- 
    767 %        Solar Radiation Penetration  
    768 % ------------------------------------------------------------------------------------------------------------- 
    769 \subsection[Solar radiation penetration (\textit{traqsr.F90})] 
    770 {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})} 
    771774\label{subsec:TRA_qsr} 
    772 %--------------------------------------------namqsr-------------------------------------------------------- 
    773  
    774 \nlst{namtra_qsr} 
    775 %-------------------------------------------------------------------------------------------------------------- 
    776  
    777 Options are defined through the \ngn{namtra\_qsr} namelist variables. 
    778 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}), 
    779784the solar radiation penetrates the top few tens of meters of the ocean. 
    780 If it is not used (\np{ln\_flxqsr}\forcode{ = .false.}) all the heat flux is absorbed in the first ocean level. 
    781 Thus, in the former case a term is added to the time evolution equation of temperature \autoref{eq:PE_tra_T} and 
    782 the surface boundary condition is modified to take into account only the non-penetrative part of the surface  
    783 heat flux: 
    784 \begin{equation} 
    785   \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} 
    786792  \begin{gathered} 
    787793    \pd[T]{t} = \ldots + \frac{1}{\rho_o \, C_p \, e_3} \; \pd[I]{k} \\ 
     
    789795  \end{gathered} 
    790796\end{equation} 
    791 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 
    792798$I$ is the downward irradiance ($\lt. I \rt|_{z = \eta} = Q_{sr}$). 
    793 The additional term in \autoref{eq:PE_qsr} is discretized as follows: 
    794 \begin{equation} 
    795   \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} 
    796802  \frac{1}{\rho_o \, C_p \, e_3} \, \pd[I]{k} \equiv \frac{1}{\rho_o \, C_p \, e_{3t}} \delta_k [I_w] 
    797803\end{equation} 
    798804 
    799805The shortwave radiation, $Q_{sr}$, consists of energy distributed across a wide spectral range. 
    800 The ocean is strongly absorbing for wavelengths longer than 700~nm and these wavelengths contribute to 
    801 heating the upper few tens of centimetres. 
    802 The fraction of $Q_{sr}$ that resides in these almost non-penetrative wavebands, $R$, is $\sim 58\%$ 
    803 (specified through namelist parameter \np{rn\_abs}). 
    804 It is assumed to penetrate the ocean with a decreasing exponential profile, with an e-folding depth scale, $\xi_0$, 
    805 of a few tens of centimetres (typically $\xi_0 = 0.35~m$ set as \np{rn\_si0} in the \ngn{namtra\_qsr} namelist). 
    806 For shorter wavelengths (400-700~nm), the ocean is more transparent, and solar energy propagates to 
    807 larger depths where it contributes to local heating. 
    808 The way this second part of the solar energy penetrates into the ocean depends on which formulation is chosen. 
    809 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}) 
    810818a chlorophyll-independent monochromatic formulation is chosen for the shorter wavelengths, 
    811819leading to the following expression \citep{paulson.simpson_JPO77}: 
    812820\[ 
    813   % \label{eq:traqsr_iradiance} 
     821  % \label{eq:TRA_qsr_iradiance} 
    814822  I(z) = Q_{sr} \lt[ Re^{- z / \xi_0} + (1 - R) e^{- z / \xi_1} \rt] 
    815823\] 
    816824where $\xi_1$ is the second extinction length scale associated with the shorter wavelengths. 
    817 It is usually chosen to be 23~m by setting the \np{rn\_si0} namelist parameter. 
    818 The set of default values ($\xi_0, \xi_1, R$) corresponds to a Type I water in Jerlov's (1968) classification 
    819 (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). 
    820828 
    821829Such assumptions have been shown to provide a very crude and simplistic representation of 
    822 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}). 
    823831Light absorption in the ocean depends on particle concentration and is spectrally selective. 
    824832\cite{morel_JGR88} has shown that an accurate representation of light penetration can be provided by 
    825833a 61 waveband formulation. 
    826834Unfortunately, such a model is very computationally expensive. 
    827 Thus, \cite{lengaigne.menkes.ea_CD07} have constructed a simplified version of this formulation in which 
    828 visible light is split into three wavebands: blue (400-500 nm), green (500-600 nm) and red (600-700nm). 
    829 For each wave-band, the chlorophyll-dependent attenuation coefficient is fitted to the coefficients computed from 
    830 the full spectral model of \cite{morel_JGR88} (as modified by \cite{morel.maritorena_JGR01}), 
    831 assuming the same power-law relationship. 
    832 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), 
    833843reproduces quite closely the light penetration profiles predicted by the full spectal model, 
    834844but with much greater computational efficiency. 
    835845The 2-bands formulation does not reproduce the full model very well. 
    836846 
    837 The RGB formulation is used when \np{ln\_qsr\_rgb}\forcode{ = .true.}. 
    838 The RGB attenuation coefficients (\ie the inverses of the extinction length scales) are tabulated over 
    839 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$ 
    840850(see the routine \rou{trc\_oce\_rgb} in \mdl{trc\_oce} module). 
    841851Four types of chlorophyll can be chosen in the RGB formulation: 
    842852 
    843853\begin{description} 
    844 \item[\np{nn\_chdta}\forcode{ = 0}] 
    845   a constant 0.05 g.Chl/L value everywhere ;  
    846 \item[\np{nn\_chdta}\forcode{ = 1}] 
    847   an observed time varying chlorophyll deduced from satellite surface ocean color measurement spread uniformly in 
    848   the vertical direction; 
    849 \item[\np{nn\_chdta}\forcode{ = 2}] 
    850   same as previous case except that a vertical profile of chlorophyl is used. 
    851   Following \cite{morel.berthon_LO89}, the profile is computed from the local surface chlorophyll value; 
    852 \item[\np{ln\_qsr\_bio}\forcode{ = .true.}] 
    853   simulated time varying chlorophyll by TOP biogeochemical model. 
    854   In this case, the RGB formulation is used to calculate both the phytoplankton light limitation in 
    855   PISCES or LOBSTER and the oceanic heating rate. 
    856 \end{description}  
    857  
    858 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 
    859868the temperature trend, and the surface heat flux is modified in routine \mdl{traqsr}. 
    860869 
     
    862871the depth of $w-$levels does not significantly vary with location. 
    863872The level at which the light has been totally absorbed 
    864 (\ie it is less than the computer precision) is computed once, 
     873(\ie\ it is less than the computer precision) is computed once, 
    865874and the trend associated with the penetration of the solar radiation is only added down to that level. 
    866 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. 
    867877In this case, we have chosen that all remaining radiation is absorbed in the last ocean level 
    868 (\ie $I$ is masked). 
    869  
    870 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    871 \begin{figure}[!t] 
    872   \begin{center} 
    873     \includegraphics[width=\textwidth]{Fig_TRA_Irradiance} 
    874     \caption{ 
    875       \protect\label{fig:traqsr_irradiance} 
    876       Penetration profile of the downward solar irradiance calculated by four models. 
    877       Two waveband chlorophyll-independent formulation (blue), 
    878       a chlorophyll-dependent monochromatic formulation (green), 
    879       4 waveband RGB formulation (red), 
    880       61 waveband Morel (1988) formulation (black) for a chlorophyll concentration of 
    881       (a) Chl=0.05 mg/m$^3$ and (b) Chl=0.5 mg/m$^3$. 
    882       From \citet{lengaigne.menkes.ea_CD07}. 
    883     } 
    884   \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} 
    885892\end{figure} 
    886 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    887  
    888 % ------------------------------------------------------------------------------------------------------------- 
    889 %        Bottom Boundary Condition 
    890 % ------------------------------------------------------------------------------------------------------------- 
    891 \subsection[Bottom boundary condition (\textit{trabbc.F90})] 
    892 {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})} 
    893896\label{subsec:TRA_bbc} 
    894 %--------------------------------------------nambbc-------------------------------------------------------- 
    895  
    896 \nlst{nambbc} 
    897 %-------------------------------------------------------------------------------------------------------------- 
    898 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    899 \begin{figure}[!t] 
    900   \begin{center} 
    901     \includegraphics[width=\textwidth]{Fig_TRA_geoth} 
    902     \caption{ 
    903       \protect\label{fig:geothermal} 
    904       Geothermal Heat flux (in $mW.m^{-2}$) used by \cite{emile-geay.madec_OS09}. 
    905       It is inferred from the age of the sea floor and the formulae of \citet{stein.stein_N92}. 
    906     } 
    907   \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} 
    908911\end{figure} 
    909 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    910912 
    911913Usually it is assumed that there is no exchange of heat or salt through the ocean bottom, 
    912 \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. 
    913915This is the default option in \NEMO, and it is implemented using the masking technique. 
    914 However, there is a non-zero heat flux across the seafloor that is associated with solid earth cooling. 
    915 This flux is weak compared to surface fluxes (a mean global value of $\sim 0.1 \, W/m^2$ \citep{stein.stein_N92}), 
     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}), 
    916920but it warms systematically the ocean and acts on the densest water masses. 
    917921Taking this flux into account in a global ocean model increases the deepest overturning cell 
    918 (\ie the one associated with the Antarctic Bottom Water) by a few Sverdrups \citep{emile-geay.madec_OS09}. 
    919  
    920 Options are defined through the  \ngn{namtra\_bbc} namelist variables. 
    921 The presence of geothermal heating is controlled by setting the namelist parameter \np{ln\_trabbc} to true. 
    922 Then, when \np{nn\_geoflx} is set to 1, a constant geothermal heating is introduced whose value is given by 
    923 the \np{nn\_geoflx\_cst}, which is also a namelist parameter. 
    924 When \np{nn\_geoflx} is set to 2, a spatially varying geothermal heat flux is introduced which is provided in 
    925 the \ifile{geothermal\_heating} NetCDF file (\autoref{fig:geothermal}) \citep{emile-geay.madec_OS09}. 
    926  
    927 % ================================================================ 
    928 % Bottom Boundary Layer 
    929 % ================================================================ 
    930 \section[Bottom boundary layer (\textit{trabbl.F90} - \texttt{\textbf{key\_trabbl}})] 
    931 {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})} 
    932937\label{sec:TRA_bbl} 
    933 %--------------------------------------------nambbl--------------------------------------------------------- 
    934  
    935 \nlst{nambbl} 
    936 %-------------------------------------------------------------------------------------------------------------- 
    937  
    938 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. 
    939946In a $z$-coordinate configuration, the bottom topography is represented by a series of discrete steps. 
    940947This is not adequate to represent gravity driven downslope flows. 
     
    942949where dense water formed in marginal seas flows into a basin filled with less dense water, 
    943950or along the continental slope when dense water masses are formed on a continental shelf. 
    944 The amount of entrainment that occurs in these gravity plumes is critical in determining the density and 
    945 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. 
    946954$z$-coordinate models tend to overestimate the entrainment, 
    947 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, 
    948957sometimes over a thickness much larger than the thickness of the observed gravity plume. 
    949 A similar problem occurs in the $s$-coordinate when the thickness of the bottom level varies rapidly downstream of 
    950 a sill \citep{willebrand.barnier.ea_PO01}, and the thickness of the plume is not resolved. 
    951  
    952 The idea of the bottom boundary layer (BBL) parameterisation, first introduced by \citet{beckmann.doscher_JPO97}, 
     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}, 
    953964is to allow a direct communication between two adjacent bottom cells at different levels, 
    954965whenever the densest water is located above the less dense water. 
    955 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. 
    956968In the current implementation of the BBL, only the tracers are modified, not the velocities. 
    957 Furthermore, it only connects ocean bottom cells, and therefore does not include all the improvements introduced by 
    958 \citet{campin.goosse_T99}. 
    959  
    960 % ------------------------------------------------------------------------------------------------------------- 
    961 %        Diffusive BBL 
    962 % ------------------------------------------------------------------------------------------------------------- 
    963 \subsection[Diffusive bottom boundary layer (\forcode{nn_bbl_ldf = 1})] 
    964 {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})} 
    965974\label{subsec:TRA_bbl_diff} 
    966975 
    967 When applying sigma-diffusion (\key{trabbl} defined and \np{nn\_bbl\_ldf} set to 1), 
    968 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 
    969979\[ 
    970   % \label{eq:tra_bbl_diff} 
     980  % \label{eq:TRA_bbl_diff} 
    971981  \vect F_\sigma = A_l^\sigma \, \nabla_\sigma T 
    972982\] 
    973 with $\nabla_\sigma$ the lateral gradient operator taken between bottom cells, and 
    974 $A_l^\sigma$ the lateral diffusivity in the BBL. 
     983with $\nabla_\sigma$ the lateral gradient operator taken between bottom cells, 
     984and $A_l^\sigma$ the lateral diffusivity in the BBL. 
    975985Following \citet{beckmann.doscher_JPO97}, the latter is prescribed with a spatial dependence, 
    976 \ie in the conditional form 
    977 \begin{equation} 
    978   \label{eq:tra_bbl_coef} 
     986\ie\ in the conditional form 
     987\begin{equation} 
     988  \label{eq:TRA_bbl_coef} 
    979989  A_l^\sigma (i,j,t) = 
    980990      \begin{cases} 
    981991        A_{bbl} & \text{if~} \nabla_\sigma \rho \cdot \nabla H < 0 \\ 
    982         \\ 
    983         0      & \text{otherwise} \\ 
     992        0      & \text{otherwise} 
    984993      \end{cases} 
    985994\end{equation} 
    986 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 
    987997usually set to a value much larger than the one used for lateral mixing in the open ocean. 
    988 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 
    989999the density above the sea floor, at the top of the slope, is larger than in the deeper ocean 
    990 (see green arrow in \autoref{fig:bbl}). 
     1000(see green arrow in \autoref{fig:TRA_bbl}). 
    9911001In practice, this constraint is applied separately in the two horizontal directions, 
    992 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: 
    9931003\[ 
    994   % \label{eq:tra_bbl_Drho} 
     1004  % \label{eq:TRA_bbl_Drho} 
    9951005  \nabla_\sigma \rho / \rho = \alpha \, \nabla_\sigma T + \beta \, \nabla_\sigma S 
    9961006\] 
    997 where $\rho$, $\alpha$ and $\beta$ are functions of $\overline T^\sigma$, $\overline S^\sigma$ and 
    998 $\overline H^\sigma$, the along bottom mean temperature, salinity and depth, respectively. 
    999  
    1000 % ------------------------------------------------------------------------------------------------------------- 
    1001 %        Advective BBL 
    1002 % ------------------------------------------------------------------------------------------------------------- 
    1003 \subsection[Advective bottom boundary layer (\forcode{nn_bbl_adv = [12]})] 
    1004 {Advective bottom boundary layer (\protect\np{nn\_bbl\_adv}\forcode{ = [12]})} 
     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})} 
    10051013\label{subsec:TRA_bbl_adv} 
    10061014 
     
    10101018%} 
    10111019 
    1012 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1013 \begin{figure}[!t] 
    1014   \begin{center} 
    1015     \includegraphics[width=\textwidth]{Fig_BBL_adv} 
    1016     \caption{ 
    1017       \protect\label{fig:bbl} 
    1018       Advective/diffusive Bottom Boundary Layer. 
    1019       The BBL parameterisation is activated when $\rho^i_{kup}$ is larger than $\rho^{i + 1}_{kdnw}$. 
    1020       Red arrows indicate the additional overturning circulation due to the advective BBL. 
    1021       The transport of the downslope flow is defined either as the transport of the bottom ocean cell (black arrow), 
    1022       or as a function of the along slope density gradient. 
    1023       The green arrow indicates the diffusive BBL flux directly connecting $kup$ and $kdwn$ ocean bottom cells. 
    1024     } 
    1025   \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} 
    10261033\end{figure} 
    1027 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    10281034 
    10291035%!!      nn_bbl_adv = 1   use of the ocean velocity as bbl velocity 
     
    10311037%!!        i.e. transport proportional to the along-slope density gradient 
    10321038 
    1033 %%%gmcomment   :  this section has to be really written 
    1034  
    1035 When applying an advective BBL (\np{nn\_bbl\_adv}\forcode{ = 1..2}), an overturning circulation is added which 
    1036 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. 
    10371044The density difference causes dense water to move down the slope. 
    10381045 
    1039 \np{nn\_bbl\_adv}\forcode{ = 1}: 
    1040 the downslope velocity is chosen to be the Eulerian ocean velocity just above the topographic step 
    1041 (see black arrow in \autoref{fig:bbl}) \citep{beckmann.doscher_JPO97}. 
    1042 It is a \textit{conditional advection}, that is, advection is allowed only 
    1043 if dense water overlies less dense water on the slope (\ie $\nabla_\sigma \rho \cdot \nabla H < 0$) and 
    1044 if the velocity is directed towards greater depth (\ie $\vect U \cdot \nabla H > 0$). 
    1045  
    1046 \np{nn\_bbl\_adv}\forcode{ = 2}: 
    1047 the downslope velocity is chosen to be proportional to $\Delta \rho$, 
    1048 the density difference between the higher cell and lower cell densities \citep{campin.goosse_T99}. 
    1049 The advection is allowed only  if dense water overlies less dense water on the slope 
    1050 (\ie $\nabla_\sigma \rho \cdot \nabla H < 0$). 
    1051 For example, the resulting transport of the downslope flow, here in the $i$-direction (\autoref{fig:bbl}), 
    1052 is simply given by the following expression: 
    1053 \[ 
    1054   % \label{eq:bbl_Utr} 
    1055   u^{tr}_{bbl} = \gamma g \frac{\Delta \rho}{\rho_o} e_{1u} \, min ({e_{3u}}_{kup},{e_{3u}}_{kdwn}) 
    1056 \] 
    1057 where $\gamma$, expressed in seconds, is the coefficient of proportionality provided as \np{rn\_gambbl}, 
    1058 a namelist parameter, and \textit{kup} and \textit{kdwn} are the vertical index of the higher and lower cells, 
    1059 respectively. 
    1060 The parameter $\gamma$ should take a different value for each bathymetric step, but for simplicity, 
    1061 and because no direct estimation of this parameter is available, a uniform value has been assumed. 
    1062 The possible values for $\gamma$ range between 1 and $10~s$ \citep{campin.goosse_T99}. 
    1063  
    1064 Scalar properties are advected by this additional transport $(u^{tr}_{bbl},v^{tr}_{bbl})$ using the upwind scheme. 
    1065 Such a diffusive advective scheme has been chosen to mimic the entrainment between the downslope plume and 
    1066 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. 
    10671077The entrainment is replaced by the vertical mixing implicit in the advection scheme. 
    1068 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 
    10691079the density at level $(i,kup)$ is larger than the one at level $(i,kdwn)$. 
    1070 The advective BBL scheme modifies the tracer time tendency of the ocean cells near the topographic step by 
    1071 the downslope flow \autoref{eq:bbl_dw}, the horizontal \autoref{eq:bbl_hor} and 
    1072 the upward \autoref{eq:bbl_up} return flows as follows:  
    1073 \begin{alignat}{3} 
    1074   \label{eq:bbl_dw} 
    1075   \partial_t T^{do}_{kdw} &\equiv \partial_t T^{do}_{kdw} 
    1076                                 &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{kdw}} &&\lt( T^{sh}_{kup} - T^{do}_{kdw} \rt) \\ 
    1077   \label{eq:bbl_hor} 
    1078   \partial_t T^{sh}_{kup} &\equiv \partial_t T^{sh}_{kup} 
    1079                                 &&+ \frac{u^{tr}_{bbl}}{{b_t}^{sh}_{kup}} &&\lt( T^{do}_{kup} - T^{sh}_{kup} \rt) \\ 
    1080   % 
    1081   \intertext{and for $k =kdw-1,\;..., \; kup$ :} 
    1082   % 
    1083   \label{eq:bbl_up} 
    1084   \partial_t T^{do}_{k} &\equiv \partial_t S^{do}_{k} 
    1085                                 &&+ \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) 
    10861091\end{alignat} 
    10871092where $b_t$ is the $T$-cell volume. 
     
    10901095It has to be used to compute the effective velocity as well as the effective overturning circulation. 
    10911096 
    1092 % ================================================================ 
    1093 % Tracer damping 
    1094 % ================================================================ 
    1095 \section[Tracer damping (\textit{tradmp.F90})] 
    1096 {Tracer damping (\protect\mdl{tradmp})} 
     1097%% ================================================================================================= 
     1098\section[Tracer damping (\textit{tradmp.F90})]{Tracer damping (\protect\mdl{tradmp})} 
    10971099\label{sec:TRA_dmp} 
    1098 %--------------------------------------------namtra_dmp------------------------------------------------- 
    1099  
    1100 \nlst{namtra_dmp} 
    1101 %-------------------------------------------------------------------------------------------------------------- 
    1102  
    1103 In some applications it can be useful to add a Newtonian damping term into the temperature and salinity equations: 
    1104 \begin{equation} 
    1105   \label{eq:tra_dmp} 
    1106   \begin{gathered} 
    1107     \pd[T]{t} = \cdots - \gamma (T - T_o) \\ 
    1108     \pd[S]{t} = \cdots - \gamma (S - S_o) 
    1109   \end{gathered} 
    1110 \end{equation}  
    1111 where $\gamma$ is the inverse of a time scale, and $T_o$ and $S_o$ are given temperature and salinity fields 
    1112 (usually a climatology). 
    1113 Options are defined through the  \ngn{namtra\_dmp} namelist variables. 
    1114 The restoring term is added when the namelist parameter \np{ln\_tradmp} is set to true. 
    1115 It also requires that both \np{ln\_tsd\_init} and \np{ln\_tsd\_tradmp} are set to true in 
    1116 \ngn{namtsd} namelist as well as \np{sn\_tem} and \np{sn\_sal} structures are correctly set 
    1117 (\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}, 
    11181121see \autoref{subsec:SBC_fldread}). 
    1119 The restoring coefficient $\gamma$ is a three-dimensional array read in during the \rou{tra\_dmp\_init} routine. 
    1120 The file name is specified by the namelist variable \np{cn\_resto}. 
    1121 The DMP\_TOOLS tool is provided to allow users to generate the netcdf file. 
    1122  
    1123 The two main cases in which \autoref{eq:tra_dmp} is used are 
    1124 \textit{(a)} the specification of the boundary conditions along artificial walls of a limited domain basin and 
    1125 \textit{(b)} the computation of the velocity field associated with a given $T$-$S$ field 
    1126 (for example to build the initial state of a prognostic simulation, 
    1127 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*} 
    11281135The first case applies to regional models that have artificial walls instead of open boundaries. 
    1129 In the vicinity of these walls, $\gamma$ takes large values (equivalent to a time scale of a few days) whereas 
    1130 it is zero in the interior of the model domain. 
     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. 
    11311138The second case corresponds to the use of the robust diagnostic method \citep{sarmiento.bryan_JGR82}. 
    11321139It allows us to find the velocity field consistent with the model dynamics whilst 
    11331140having a $T$, $S$ field close to a given climatological field ($T_o$, $S_o$). 
    11341141 
    1135 The robust diagnostic method is very efficient in preventing temperature drift in intermediate waters but 
    1136 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. 
    11371144It also has undesirable effects on the ocean convection. 
    1138 It tends to prevent deep convection and subsequent deep-water formation, by stabilising the water column too much. 
    1139  
    1140 The namelist parameter \np{nn\_zdmp} sets whether the damping should be applied in the whole water column or 
    1141 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). 
    11421150It is common to set the damping to zero in the mixed layer as the adjustment time scale is short here 
    11431151\citep{madec.delecluse.ea_JPO96}. 
    11441152 
    1145 For generating \ifile{resto}, see the documentation for the DMP tool provided with the source code under 
    1146 \path{./tools/DMP_TOOLS}. 
    1147  
    1148 % ================================================================ 
    1149 % Tracer time evolution 
    1150 % ================================================================ 
    1151 \section[Tracer time evolution (\textit{tranxt.F90})] 
    1152 {Tracer time evolution (\protect\mdl{tranxt})} 
     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})} 
    11531158\label{sec:TRA_nxt} 
    1154 %--------------------------------------------namdom----------------------------------------------------- 
    1155  
    1156 \nlst{namdom} 
    1157 %-------------------------------------------------------------------------------------------------------------- 
    1158  
    1159 Options are defined through the \ngn{namdom} namelist variables. 
    1160 The general framework for tracer time stepping is a modified leap-frog scheme \citep{leclair.madec_OM09}, 
    1161 \ie a three level centred time scheme associated with a Asselin time filter (cf. \autoref{sec:STP_mLF}): 
    1162 \begin{equation} 
    1163   \label{eq:tra_nxt} 
    1164   \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} 
    11651167    &(e_{3t}T)^{t + \rdt} &&= (e_{3t}T)_f^{t - \rdt} &&+ 2 \, \rdt \,e_{3t}^t \ \text{RHS}^t \\ 
    11661168    &(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] \\ 
    1167     &                     &&                         &&- \, \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] 
    11681170  \end{alignedat} 
    1169 \end{equation}  
    1170 where RHS is the right hand side of the temperature equation, the subscript $f$ denotes filtered values, 
    1171 $\gamma$ is the Asselin coefficient, and $S$ is the total forcing applied on $T$ 
    1172 (\ie fluxes plus content in mass exchanges). 
    1173 $\gamma$ is initialized as \np{rn\_atfp} (\textbf{namelist} parameter). 
    1174 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}. 
    11751176Note that the forcing correction term in the filter is not applied in linear free surface 
    1176 (\jp{lk\_vvl}\forcode{ = .false.}) (see \autoref{subsec:TRA_sbc}). 
    1177 Not also that in constant volume case, the time stepping is performed on $T$, not on its content, $e_{3t}T$. 
    1178  
    1179 When the vertical mixing is solved implicitly, the update of the \textit{next} tracer fields is done in 
    1180 \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. 
    11811183In this case only the swapping of arrays and the Asselin filtering is done in the \mdl{tranxt} module. 
    11821184 
    1183 In order to prepare for the computation of the \textit{next} time step, a swap of tracer arrays is performed: 
    1184 $T^{t - \rdt} = T^t$ and $T^t = T_f$. 
    1185  
    1186 % ================================================================ 
    1187 % Equation of State (eosbn2)  
    1188 % ================================================================ 
    1189 \section[Equation of state (\textit{eosbn2.F90})] 
    1190 {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})} 
    11911190\label{sec:TRA_eosbn2} 
    1192 %--------------------------------------------nameos----------------------------------------------------- 
    1193  
    1194 \nlst{nameos} 
    1195 %-------------------------------------------------------------------------------------------------------------- 
    1196  
    1197 % ------------------------------------------------------------------------------------------------------------- 
    1198 %        Equation of State 
    1199 % ------------------------------------------------------------------------------------------------------------- 
    1200 \subsection[Equation of seawater (\forcode{nn_eos = {-1,1}})] 
    1201 {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})} 
    12021200\label{subsec:TRA_eos} 
    12031201 
    1204 The Equation Of Seawater (EOS) is an empirical nonlinear thermodynamic relationship linking seawater density, 
    1205 $\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. 
    12061206Because density gradients control the pressure gradient force through the hydrostatic balance, 
    1207 the equation of state provides a fundamental bridge between the distribution of active tracers and 
    1208 the fluid dynamics. 
     1207the equation of state provides a fundamental bridge between 
     1208the distribution of active tracers and the fluid dynamics. 
    12091209Nonlinearities of the EOS are of major importance, in particular influencing the circulation through 
    12101210determination of the static stability below the mixed layer, 
    1211 thus controlling rates of exchange between the atmosphere and the ocean interior \citep{roquet.madec.ea_JPO15}. 
    1212 Therefore an accurate EOS based on either the 1980 equation of state (EOS-80, \cite{fofonoff.millard_bk83}) or 
    1213 TEOS-10 \citep{ioc.iapso_bk10} standards should be used anytime a simulation of the real ocean circulation is attempted 
     1211thus controlling rates of exchange between the atmosphere and the ocean interior 
    12141212\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}. 
    12151216The use of TEOS-10 is highly recommended because 
    1216 \textit{(i)}   it is the new official EOS, 
    1217 \textit{(ii)}  it is more accurate, being based on an updated database of laboratory measurements, and 
    1218 \textit{(iii)} it uses Conservative Temperature and Absolute Salinity (instead of potential temperature and 
    1219 practical salinity for EOS-980, both variables being more suitable for use as model variables 
    1220 \citep{ioc.iapso_bk10, graham.mcdougall_JPO13}. 
    1221 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. 
    12221226For process studies, it is often convenient to use an approximation of the EOS. 
    12231227To that purposed, a simplified EOS (S-EOS) inspired by \citet{vallis_bk06} is also available. 
    12241228 
    1225 In the computer code, a density anomaly, $d_a = \rho / \rho_o - 1$, is computed, with $\rho_o$ a reference density. 
    1226 Called \textit{rau0} in the code, $\rho_o$ is set in \mdl{phycst} to a value of $1,026~Kg/m^3$. 
    1227 This is a sensible choice for the reference density used in a Boussinesq ocean climate model, as, 
    1228 with the exception of only a small percentage of the ocean, 
    1229 density in the World Ocean varies by no more than 2$\%$ from that value \citep{gill_bk82}. 
    1230  
    1231 Options are defined through the \ngn{nameos} namelist variables, and in particular \np{nn\_eos} which 
    1232 controls the EOS used (\forcode{= -1} for TEOS10 ; \forcode{= 0} for EOS-80 ; \forcode{= 1} for S-EOS). 
     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. 
    12331238 
    12341239\begin{description} 
    1235 \item[\np{nn\_eos}\forcode{ = -1}] 
    1236   the polyTEOS10-bsq equation of seawater \citep{roquet.madec.ea_OM15} is used. 
     1240\item [{\np[=.true.]{ln_teos10}{ln\_teos10}}] the polyTEOS10-bsq equation of seawater 
     1241  \citep{roquet.madec.ea_OM15} is used. 
    12371242  The accuracy of this approximation is comparable to the TEOS-10 rational function approximation, 
    1238   but it is optimized for a boussinesq fluid and the polynomial expressions have simpler and 
    1239   more computationally efficient expressions for their derived quantities which make them more adapted for 
    1240   use in ocean models. 
    1241   Note that a slightly higher precision polynomial form is now used replacement of 
    1242   the TEOS-10 rational function approximation for hydrographic data analysis \citep{ioc.iapso_bk10}. 
     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}. 
    12431249  A key point is that conservative state variables are used: 
    1244   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$). 
    12451252  The pressure in decibars is approximated by the depth in meters. 
    12461253  With TEOS10, the specific heat capacity of sea water, $C_p$, is a constant. 
    1247   It is set to $C_p = 3991.86795711963~J\,Kg^{-1}\,^{\circ}K^{-1}$, according to \citet{ioc.iapso_bk10}. 
     1254  It is set to $C_p$ = 3991.86795711963 $J.Kg^{-1}.\deg{K}^{-1}$, 
     1255  according to \citet{ioc.iapso_bk10}. 
    12481256  Choosing polyTEOS10-bsq implies that the state variables used by the model are $\Theta$ and $S_A$. 
    1249   In particular, the initial state deined by the user have to be given as \textit{Conservative} Temperature and 
    1250   \textit{Absolute} Salinity. 
    1251   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 
    12521260  either computing the air-sea and ice-sea fluxes (forced mode) or 
    12531261  sending the SST field to the atmosphere (coupled mode). 
    1254 \item[\np{nn\_eos}\forcode{ = 0}] 
    1255   the polyEOS80-bsq equation of seawater is used. 
    1256   It takes the same polynomial form as the polyTEOS10, but the coefficients have been optimized to 
    1257   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.). 
    12581265  The state variables used in both the EOS80 and the ocean model are: 
    1259   the Practical Salinity ((unit: psu, notation: $S_p$)) and 
    1260   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$). 
    12611268  The pressure in decibars is approximated by the depth in meters. 
    1262   With thsi EOS, the specific heat capacity of sea water, $C_p$, is a function of temperature, salinity and 
    1263   pressure \citep{fofonoff.millard_bk83}. 
     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}. 
    12641271  Nevertheless, a severe assumption is made in order to have a heat content ($C_p T_p$) which 
    12651272  is conserved by the model: $C_p$ is set to a constant value, the TEOS10 value. 
    1266 \item[\np{nn\_eos}\forcode{ = 1}] 
    1267   a simplified EOS (S-EOS) inspired by \citet{vallis_bk06} is chosen, 
    1268   the coefficients of which has been optimized to fit the behavior of TEOS10 
    1269   (Roquet, personal comm.) (see also \citet{roquet.madec.ea_JPO15}). 
     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}). 
    12701277  It provides a simplistic linear representation of both cabbeling and thermobaricity effects which 
    12711278  is enough for a proper treatment of the EOS in theoretical studies \citep{roquet.madec.ea_JPO15}. 
    1272   With such an equation of state there is no longer a distinction between 
    1273   \textit{conservative} and \textit{potential} temperature, 
    1274   as well as between \textit{absolute} and \textit{practical} salinity. 
     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. 
    12751282  S-EOS takes the following expression: 
    12761283  \begin{gather*} 
    1277     % \label{eq:tra_S-EOS} 
    1278     \begin{alignedat}{2} 
    1279     &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. \\ 
    1280     &                                    &+ b_0 \; ( 1 - 0.5 \; \lambda_2 \; S_a - \mu_2 \; z ) * &S_a       \\   
    1281     &                              \big. &- \nu \;                           T_a                  &S_a \big] \\ 
    1282     \end{alignedat} 
    1283     \\ 
     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] \\ 
    12841288    \text{with~} T_a = T - 10 \, ; \, S_a = S - 35 \, ; \, \rho_o = 1026~Kg/m^3 
    12851289  \end{gather*} 
    1286   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}. 
    12871292  In fact, when choosing S-EOS, various approximation of EOS can be specified simply by 
    12881293  changing the associated coefficients. 
    1289   Setting to zero the two thermobaric coefficients $(\mu_1,\mu_2)$ remove thermobaric effect from S-EOS. 
    1290   setting to zero the three cabbeling coefficients $(\lambda_1,\lambda_2,\nu)$ remove cabbeling effect from 
    1291   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. 
    12921298  Keeping non-zero value to $a_0$ and $b_0$ provide a linear EOS function of T and S. 
    12931299\end{description} 
    12941300 
    1295 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1296 \begin{table}[!tb] 
    1297   \begin{center} 
    1298     \begin{tabular}{|l|l|l|l|} 
    1299       \hline 
    1300       coeff.      & computer name   & S-EOS           & description                      \\ 
    1301       \hline 
    1302       $a_0$       & \np{rn\_a0}     & $1.6550~10^{-1}$ & linear thermal expansion coeff. \\ 
    1303       \hline 
    1304       $b_0$       & \np{rn\_b0}     & $7.6554~10^{-1}$ & linear haline  expansion coeff. \\ 
    1305       \hline 
    1306       $\lambda_1$ & \np{rn\_lambda1}& $5.9520~10^{-2}$ & cabbeling coeff. in $T^2$       \\ 
    1307       \hline 
    1308       $\lambda_2$ & \np{rn\_lambda2}& $5.4914~10^{-4}$ & cabbeling coeff. in $S^2$       \\ 
    1309       \hline 
    1310       $\nu$       & \np{rn\_nu}     & $2.4341~10^{-3}$ & cabbeling coeff. in $T \, S$    \\ 
    1311       \hline 
    1312       $\mu_1$     & \np{rn\_mu1}    & $1.4970~10^{-4}$ & thermobaric coeff. in T         \\ 
    1313       \hline 
    1314       $\mu_2$     & \np{rn\_mu2}    & $1.1090~10^{-5}$ & thermobaric coeff. in S         \\ 
    1315       \hline 
    1316     \end{tabular} 
    1317     \caption{ 
    1318       \protect\label{tab:SEOS} 
    1319       Standard value of S-EOS coefficients. 
    1320     } 
    1321 \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} 
    13221324\end{table} 
    1323 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1324  
    1325 % ------------------------------------------------------------------------------------------------------------- 
    1326 %        Brunt-V\"{a}is\"{a}l\"{a} Frequency 
    1327 % ------------------------------------------------------------------------------------------------------------- 
    1328 \subsection[Brunt-V\"{a}is\"{a}l\"{a} frequency (\forcode{nn_eos = [0-2]})] 
    1329 {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} 
    13301328\label{subsec:TRA_bn2} 
    13311329 
    1332 An accurate computation of the ocean stability (i.e. of $N$, the brunt-V\"{a}is\"{a}l\"{a} frequency) is of 
    1333 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 
    13341332(namely TKE, GLS, Richardson number dependent vertical diffusion, enhanced vertical diffusion, 
    13351333non-penetrative convection, tidal mixing  parameterisation, iso-neutral diffusion). 
    13361334In particular, $N^2$ has to be computed at the local pressure 
    13371335(pressure in decibar being approximated by the depth in meters). 
    1338 The expression for $N^2$  is given by:  
     1336The expression for $N^2$  is given by: 
    13391337\[ 
    1340   % \label{eq:tra_bn2} 
     1338  % \label{eq:TRA_bn2} 
    13411339  N^2 = \frac{g}{e_{3w}} \lt( \beta \; \delta_{k + 1/2}[S] - \alpha \; \delta_{k + 1/2}[T] \rt) 
    13421340\] 
    13431341where $(T,S) = (\Theta,S_A)$ for TEOS10, $(\theta,S_p)$ for TEOS-80, or $(T,S)$ for S-EOS, and, 
    13441342$\alpha$ and $\beta$ are the thermal and haline expansion coefficients. 
    1345 The coefficients are a polynomial function of temperature, salinity and depth which expression depends on 
    1346 the chosen EOS. 
    1347 They are computed through \textit{eos\_rab}, a \fortran function that can be found in \mdl{eosbn2}. 
    1348  
    1349 % ------------------------------------------------------------------------------------------------------------- 
    1350 %        Freezing Point of Seawater 
    1351 % ------------------------------------------------------------------------------------------------------------- 
     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%% ================================================================================================= 
    13521348\subsection{Freezing point of seawater} 
    13531349\label{subsec:TRA_fzp} 
     
    13551351The freezing point of seawater is a function of salinity and pressure \citep{fofonoff.millard_bk83}: 
    13561352\begin{equation} 
    1357   \label{eq:tra_eos_fzp} 
    1358   \begin{split} 
    1359     &T_f (S,p) = \lt( a + b \, \sqrt{S} + c \, S \rt) \, S + d \, p \\ 
    1360     &\text{where~} a = -0.0575, \, b = 1.710523~10^{-3}, \, c = -2.154996~10^{-4} \\  
    1361     &\text{and~} d = -7.53~10^{-3} 
    1362     \end{split} 
    1363 \end{equation} 
    1364  
    1365 \autoref{eq:tra_eos_fzp} is only used to compute the potential freezing point of sea water 
    1366 (\ie referenced to the surface $p = 0$), 
    1367 thus the pressure dependent terms in \autoref{eq:tra_eos_fzp} (last term) have been dropped. 
     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. 
    13681363The freezing point is computed through \textit{eos\_fzp}, 
    1369 a \fortran function that can be found in \mdl{eosbn2}. 
    1370  
    1371 % ------------------------------------------------------------------------------------------------------------- 
    1372 %        Potential Energy      
    1373 % ------------------------------------------------------------------------------------------------------------- 
     1364a \fortran\ function that can be found in \mdl{eosbn2}. 
     1365 
     1366%% ================================================================================================= 
    13741367%\subsection{Potential Energy anomalies} 
    13751368%\label{subsec:TRA_bn2} 
    13761369 
    13771370%    =====>>>>> TO BE written 
    1378 % 
    1379  
    1380 % ================================================================ 
    1381 % Horizontal Derivative in zps-coordinate  
    1382 % ================================================================ 
    1383 \section[Horizontal derivative in \textit{zps}-coordinate (\textit{zpshde.F90})] 
    1384 {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})} 
    13851374\label{sec:TRA_zpshde} 
    13861375 
    1387 \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, 
    13881377I've changed "derivative" to "difference" and "mean" to "average"} 
    13891378 
    1390 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}), 
    13911381in general, tracers in horizontally adjacent cells live at different depths. 
    1392 Horizontal gradients of tracers are needed for horizontal diffusion (\mdl{traldf} module) and 
    1393 the hydrostatic pressure gradient calculations (\mdl{dynhpg} module). 
    1394 The partial cell properties at the top (\np{ln\_isfcav}\forcode{ = .true.}) are computed in the same way as 
    1395 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. 
    13961386So, only the bottom interpolation is explained below. 
    13971387 
    13981388Before taking horizontal gradients between the tracers next to the bottom, 
    13991389a linear interpolation in the vertical is used to approximate the deeper tracer as if 
    1400 it actually lived at the depth of the shallower tracer point (\autoref{fig:Partial_step_scheme}). 
    1401 For example, for temperature in the $i$-direction the needed interpolated temperature, $\widetilde T$, is: 
    1402  
    1403 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1404 \begin{figure}[!p] 
    1405   \begin{center} 
    1406     \includegraphics[width=\textwidth]{Fig_partial_step_scheme} 
    1407     \caption{ 
    1408       \protect\label{fig:Partial_step_scheme} 
    1409       Discretisation of the horizontal difference and average of tracers in the $z$-partial step coordinate 
    1410       (\protect\np{ln\_zps}\forcode{ = .true.}) in the case $(e3w_k^{i + 1} - e3w_k^i) > 0$. 
    1411       A linear interpolation is used to estimate $\widetilde T_k^{i + 1}$, 
    1412       the tracer value at the depth of the shallower tracer point of the two adjacent bottom $T$-points. 
    1413       The horizontal difference is then given by: $\delta_{i + 1/2} T_k = \widetilde T_k^{\, i + 1} -T_k^{\, i}$ and 
    1414       the average by: $\overline T_k^{\, i + 1/2} = (\widetilde T_k^{\, i + 1/2} - T_k^{\, i}) / 2$. 
    1415     } 
    1416   \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} 
    14171408\end{figure} 
    1418 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     1409 
    14191410\[ 
    14201411  \widetilde T = \lt\{ 
    14211412    \begin{alignedat}{2} 
    14221413      &T^{\, i + 1} &-\frac{ \lt( e_{3w}^{i + 1} -e_{3w}^i \rt) }{ e_{3w}^{i + 1} } \; \delta_k T^{i + 1} 
    1423       & \quad \text{if $e_{3w}^{i + 1} \geq e_{3w}^i$} \\ \\ 
     1414      & \quad \text{if $e_{3w}^{i + 1} \geq e_{3w}^i$} \\ 
    14241415      &T^{\, i}     &+\frac{ \lt( e_{3w}^{i + 1} -e_{3w}^i \rt )}{e_{3w}^i       } \; \delta_k T^{i + 1} 
    14251416      & \quad \text{if $e_{3w}^{i + 1} <    e_{3w}^i$} 
     
    14271418  \rt. 
    14281419\] 
    1429 and the resulting forms for the horizontal difference and the horizontal average value of $T$ at a $U$-point are:  
    1430 \begin{equation} 
    1431   \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} 
    14321424  \begin{split} 
    14331425    \delta_{i + 1/2} T       &= 
    14341426    \begin{cases} 
    1435                                 \widetilde T - T^i          & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\ 
    1436                                 \\ 
    1437                                 T^{\, i + 1} - \widetilde T & \text{if~} e_{3w}^{i + 1} <    e_{3w}^i 
    1438     \end{cases} 
    1439     \\ 
     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} \\ 
    14401430    \overline T^{\, i + 1/2} &= 
    14411431    \begin{cases} 
    1442                                 (\widetilde T - T^{\, i}   ) / 2 & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\ 
    1443                                 \\ 
    1444                                 (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 
    14451434    \end{cases} 
    14461435  \end{split} 
     
    14491438The computation of horizontal derivative of tracers as well as of density is performed once for all at 
    14501439each time step in \mdl{zpshde} module and stored in shared arrays to be used when needed. 
    1451 It has to be emphasized that the procedure used to compute the interpolated density, $\widetilde \rho$, 
    1452 is not the same as that used for $T$ and $S$. 
    1453 Instead of forming a linear approximation of density, we compute $\widetilde \rho$ from the interpolated values of 
    1454 $T$ and $S$, and the pressure at a $u$-point 
    1455 (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}): 
    14561446\[ 
    1457   % \label{eq:zps_hde_rho} 
     1447  % \label{eq:TRA_zps_hde_rho} 
    14581448  \widetilde \rho = \rho (\widetilde T,\widetilde S,z_u) \quad \text{where~} z_u = \min \lt( z_T^{i + 1},z_T^i \rt) 
    14591449\] 
    14601450 
    14611451This is a much better approximation as the variation of $\rho$ with depth (and thus pressure) 
    1462 is highly non-linear with a true equation of state and thus is badly approximated with a linear interpolation. 
    1463 This approximation is used to compute both the horizontal pressure gradient (\autoref{sec:DYN_hpg}) and 
    1464 the slopes of neutral surfaces (\autoref{sec:LDF_slp}). 
    1465  
    1466 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, 
    14671458both averaging and differencing operators appear. 
    1468 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: 
    14691460in contrast to diffusion and pressure gradient computations, 
    14701461no correction for partial steps is applied for advection. 
    14711462The main motivation is to preserve the domain averaged mean variance of the advected field when 
    14721463using the $2^{nd}$ order centred scheme. 
    1473 Sensitivity of the advection schemes to the way horizontal averages are performed in the vicinity of 
    1474 partial cells should be further investigated in the near future. 
    1475 %%% 
    1476 \gmcomment{gm :   this last remark has to be done} 
    1477 %%% 
    1478  
    1479 \biblio 
    1480  
    1481 \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}} 
    14821469 
    14831470\end{document} 
  • NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_ZDF.tex

    r11179 r12149  
    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 (\texttt{\textbf{key\_zdfcst}})] 
    49 {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})} 
    5068\label{subsec:ZDF_cst} 
    51 %--------------------------------------------namzdf--------------------------------------------------------- 
    52  
    53 \nlst{namzdf} 
    54 %-------------------------------------------------------------------------------------------------------------- 
    55  
    56 Options are defined through the \ngn{namzdf} namelist variables. 
    57 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 
    5872constant values over the whole ocean. 
    5973This is the crudest way to define the vertical ocean physics. 
    60 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. 
    6175Typical values used in this case are: 
    6276\begin{align*} 
     
    6579\end{align*} 
    6680 
    67 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. 
    6882In all cases, do not use values smaller that those associated with the molecular viscosity and diffusivity, 
    6983that is $\sim10^{-6}~m^2.s^{-1}$ for momentum, $\sim10^{-7}~m^2.s^{-1}$ for temperature and 
    7084$\sim10^{-9}~m^2.s^{-1}$ for salinity. 
    7185 
    72 % ------------------------------------------------------------------------------------------------------------- 
    73 %        Richardson Number Dependent 
    74 % ------------------------------------------------------------------------------------------------------------- 
    75 \subsection[Richardson number dependent (\texttt{\textbf{key\_zdfric}})] 
    76 {Richardson number dependent (\protect\key{zdfric})} 
     86%% ================================================================================================= 
     87\subsection[Richardson number dependent (\forcode{ln_zdfric})]{Richardson number dependent (\protect\np{ln_zdfric}{ln\_zdfric})} 
    7788\label{subsec:ZDF_ric} 
    7889 
    79 %--------------------------------------------namric--------------------------------------------------------- 
    80  
    81 \nlst{namzdf_ric} 
    82 %-------------------------------------------------------------------------------------------------------------- 
    83  
    84 When \key{zdfric} is defined, a local Richardson number dependent formulation for the vertical momentum and 
    85 tracer eddy coefficients is set through the \ngn{namzdf\_ric} namelist variables. 
    86 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. 
    8799\textit{In situ} measurements have been used to link vertical turbulent activity to large scale ocean structures. 
    88100The hypothesis of a mixing mainly maintained by the growth of Kelvin-Helmholtz like instabilities leads to 
    89101a dependency between the vertical eddy coefficients and the local Richardson number 
    90 (\ie the ratio of stratification to vertical shear). 
     102(\ie\ the ratio of stratification to vertical shear). 
    91103Following \citet{pacanowski.philander_JPO81}, the following formulation has been implemented: 
    92104\[ 
    93   % \label{eq:zdfric} 
     105  % \label{eq:ZDF_ric} 
    94106  \left\{ 
    95107    \begin{aligned} 
     
    100112\] 
    101113where $Ri = N^2 / \left(\partial_z \textbf{U}_h \right)^2$ is the local Richardson number, 
    102 $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}), 
    103115$A_b^{vT} $ and $A_b^{vm}$ are the constant background values set as in the constant case 
    104116(see \autoref{subsec:ZDF_cst}), and $A_{ric}^{vT} = 10^{-4}~m^2.s^{-1}$ is the maximum value that 
    105117can be reached by the coefficient when $Ri\leq 0$, $a=5$ and $n=2$. 
    106 The last three values can be modified by setting the \np{rn\_avmri}, \np{rn\_alp} and 
    107 \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. 
    108120 
    109121A simple mixing-layer model to transfer and dissipate the atmospheric forcings 
    110 (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. 
    111123 
    112124In this case, the local depth of turbulent wind-mixing or "Ekman depth" $h_{e}(x,y,t)$ is evaluated and 
     
    124136\] 
    125137is computed from the wind stress vector $|\tau|$ and the reference density $ \rho_o$. 
    126 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}. 
    127139Once $h_{e}$ is computed, the vertical eddy coefficients within $h_{e}$ are set to 
    128 the empirical values \np{rn\_wtmix} and \np{rn\_wvmix} \citep{lermusiaux_JMS01}. 
    129  
    130 % ------------------------------------------------------------------------------------------------------------- 
    131 %        TKE Turbulent Closure Scheme  
    132 % ------------------------------------------------------------------------------------------------------------- 
    133 \subsection[TKE turbulent closure scheme (\texttt{\textbf{key\_zdftke}})] 
    134 {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})} 
    135144\label{subsec:ZDF_tke} 
    136145 
    137 %--------------------------------------------namzdf_tke-------------------------------------------------- 
    138  
    139 \nlst{namzdf_tke} 
    140 %-------------------------------------------------------------------------------------------------------------- 
     146\begin{listing} 
     147  \nlst{namzdf_tke} 
     148  \caption{\forcode{&namzdf_tke}} 
     149  \label{lst:namzdf_tke} 
     150\end{listing} 
    141151 
    142152The vertical eddy viscosity and diffusivity coefficients are computed from a TKE turbulent closure model based on 
     
    144154and a closure assumption for the turbulent length scales. 
    145155This turbulent closure model has been developed by \citet{bougeault.lacarrere_MWR89} in the atmospheric case, 
    146 adapted by \citet{gaspar.gregoris.ea_JGR90} for the oceanic case, and embedded in OPA, the ancestor of NEMO, 
     156adapted by \citet{gaspar.gregoris.ea_JGR90} for the oceanic case, and embedded in OPA, the ancestor of \NEMO, 
    147157by \citet{blanke.delecluse_JPO93} for equatorial Atlantic simulations. 
    148158Since then, significant modifications have been introduced by \citet{madec.delecluse.ea_NPM98} in both the implementation and 
     
    151161its destruction through stratification, its vertical diffusion, and its dissipation of \citet{kolmogorov_IANS42} type: 
    152162\begin{equation} 
    153   \label{eq:zdftke_e} 
     163  \label{eq:ZDF_tke_e} 
    154164  \frac{\partial \bar{e}}{\partial t} = 
    155165  \frac{K_m}{{e_3}^2 }\;\left[ {\left( {\frac{\partial u}{\partial k}} \right)^2 
     
    161171\end{equation} 
    162172\[ 
    163   % \label{eq:zdftke_kz} 
     173  % \label{eq:ZDF_tke_kz} 
    164174  \begin{split} 
    165175    K_m &= C_k\  l_k\  \sqrt {\bar{e}\; }    \\ 
     
    167177  \end{split} 
    168178\] 
    169 where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}),  
    170 $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, 
    171181$P_{rt}$ is the Prandtl number, $K_m$ and $K_\rho$ are the vertical eddy viscosity and diffusivity coefficients. 
    172182The constants $C_k =  0.1$ and $C_\epsilon = \sqrt {2} /2$ $\approx 0.7$ are designed to deal with 
    173 vertical mixing at any depth \citep{gaspar.gregoris.ea_JGR90}.  
    174 They are set through namelist parameters \np{nn\_ediff} and \np{nn\_ediss}. 
     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}. 
    175185$P_{rt}$ can be set to unity or, following \citet{blanke.delecluse_JPO93}, be a function of the local Richardson number, $R_i$: 
    176186\begin{align*} 
    177   % \label{eq:prt} 
     187  % \label{eq:ZDF_prt} 
    178188  P_{rt} = 
    179189  \begin{cases} 
     
    183193  \end{cases} 
    184194\end{align*} 
    185 Options are defined through the  \ngn{namzdfy\_tke} namelist variables. 
    186 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. 
    187196 
    188197At the sea surface, the value of $\bar{e}$ is prescribed from the wind stress field as 
    189 $\bar{e}_o = e_{bb} |\tau| / \rho_o$, with $e_{bb}$ the \np{rn\_ebb} namelist parameter. 
     198$\bar{e}_o = e_{bb} |\tau| / \rho_o$, with $e_{bb}$ the \np{rn_ebb}{rn\_ebb} namelist parameter. 
    190199The default value of $e_{bb}$ is 3.75. \citep{gaspar.gregoris.ea_JGR90}), however a much larger value can be used when 
    191200taking into account the surface wave breaking (see below Eq. \autoref{eq:ZDF_Esbc}). 
     
    193202The time integration of the $\bar{e}$ equation may formally lead to negative values because 
    194203the numerical scheme does not ensure its positivity. 
    195 To overcome this problem, a cut-off in the minimum value of $\bar{e}$ is used (\np{rn\_emin} namelist parameter). 
     204To overcome this problem, a cut-off in the minimum value of $\bar{e}$ is used (\np{rn_emin}{rn\_emin} namelist parameter). 
    196205Following \citet{gaspar.gregoris.ea_JGR90}, the cut-off value is set to $\sqrt{2}/2~10^{-6}~m^2.s^{-2}$. 
    197206This allows the subsequent formulations to match that of \citet{gargett_JMR84} for the diffusion in 
     
    199208In addition, a cut-off is applied on $K_m$ and $K_\rho$ to avoid numerical instabilities associated with 
    200209too weak vertical diffusion. 
    201 They must be specified at least larger than the molecular values, and are set through \np{rn\_avm0} and 
    202 \np{rn\_avt0} (namzdf namelist, see \autoref{subsec:ZDF_cst}). 
    203  
     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%% ================================================================================================= 
    204214\subsubsection{Turbulent length scale} 
    205215 
    206216For computational efficiency, the original formulation of the turbulent length scales proposed by 
    207217\citet{gaspar.gregoris.ea_JGR90} has been simplified. 
    208 Four formulations are proposed, the choice of which is controlled by the \np{nn\_mxl} namelist parameter. 
     218Four formulations are proposed, the choice of which is controlled by the \np{nn_mxl}{nn\_mxl} namelist parameter. 
    209219The first two are based on the following first order approximation \citep{blanke.delecluse_JPO93}: 
    210220\begin{equation} 
    211   \label{eq:tke_mxl0_1} 
     221  \label{eq:ZDF_tke_mxl0_1} 
    212222  l_k = l_\epsilon = \sqrt {2 \bar{e}\; } / N 
    213223\end{equation} 
    214224which is valid in a stable stratified region with constant values of the Brunt-Vais\"{a}l\"{a} frequency. 
    215225The resulting length scale is bounded by the distance to the surface or to the bottom 
    216 (\np{nn\_mxl}\forcode{ = 0}) or by the local vertical scale factor (\np{nn\_mxl}\forcode{ = 1}). 
     226(\np[=0]{nn_mxl}{nn\_mxl}) or by the local vertical scale factor (\np[=1]{nn_mxl}{nn\_mxl}). 
    217227\citet{blanke.delecluse_JPO93} notice that this simplification has two major drawbacks: 
    218228it makes no sense for locally unstable stratification and the computation no longer uses all 
    219229the information contained in the vertical density profile. 
    220 To overcome these drawbacks, \citet{madec.delecluse.ea_NPM98} 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, 
    221231which add an extra assumption concerning the vertical gradient of the computed length scale. 
    222 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: 
    223233\begin{equation} 
    224   \label{eq:tke_mxl_constraint} 
     234  \label{eq:ZDF_tke_mxl_constraint} 
    225235  \frac{1}{e_3 }\left| {\frac{\partial l}{\partial k}} \right| \leq 1 
    226236  \qquad \text{with }\  l =  l_k = l_\epsilon 
    227237\end{equation} 
    228 \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 
    229239the variations of depth. 
    230 It provides a better approximation of the \citet{gaspar.gregoris.ea_JGR90} formulation while being much less  
     240It provides a better approximation of the \citet{gaspar.gregoris.ea_JGR90} formulation while being much less 
    231241time consuming. 
    232242In particular, it allows the length scale to be limited not only by the distance to the surface or 
    233243to the ocean bottom but also by the distance to a strongly stratified portion of the water column such as 
    234 the thermocline (\autoref{fig:mixing_length}). 
    235 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: 
    236246$l_{up}$ and $l_{dwn}$, the upward and downward length scales, and 
    237247evaluate the dissipation and mixing length scales as 
    238248(and note that here we use numerical indexing): 
    239 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    240249\begin{figure}[!t] 
    241   \begin{center} 
    242     \includegraphics[width=\textwidth]{Fig_mixing_length} 
    243     \caption{ 
    244       \protect\label{fig:mixing_length} 
    245       Illustration of the mixing length computation. 
    246     } 
    247   \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} 
    248254\end{figure} 
    249 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    250 \[ 
    251   % \label{eq:tke_mxl2} 
     255\[ 
     256  % \label{eq:ZDF_tke_mxl2} 
    252257  \begin{aligned} 
    253258    l_{up\ \ }^{(k)} &= \min \left(  l^{(k)} \ , \ l_{up}^{(k+1)} + e_{3t}^{(k)}\ \ \ \;  \right) 
     
    257262  \end{aligned} 
    258263\] 
    259 where $l^{(k)}$ is computed using \autoref{eq:tke_mxl0_1}, \ie $l^{(k)} = \sqrt {2 {\bar e}^{(k)} / {N^2}^{(k)} }$. 
    260  
    261 In the \np{nn\_mxl}\forcode{ = 2} case, the dissipation and mixing length scales take the same value: 
    262 $ l_k=  l_\epsilon = \min \left(\ l_{up} \;,\;  l_{dwn}\ \right)$, while in the \np{nn\_mxl}\forcode{ = 3} case, 
     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, 
    263268the dissipation and mixing turbulent length scales are give as in \citet{gaspar.gregoris.ea_JGR90}: 
    264269\[ 
    265   % \label{eq:tke_mxl_gaspar} 
     270  % \label{eq:ZDF_tke_mxl_gaspar} 
    266271  \begin{aligned} 
    267272    & l_k          = \sqrt{\  l_{up} \ \ l_{dwn}\ }   \\ 
     
    270275\] 
    271276 
    272 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. 
    273278Usually the surface scale is given by $l_o = \kappa \,z_o$ where $\kappa = 0.4$ is von Karman's constant and 
    274279$z_o$ the roughness parameter of the surface. 
    275 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}. 
    276281In the ocean interior a minimum length scale is set to recover the molecular viscosity when 
    277282$\bar{e}$ reach its minimum value ($1.10^{-6}= C_k\, l_{min} \,\sqrt{\bar{e}_{min}}$ ). 
    278283 
     284%% ================================================================================================= 
    279285\subsubsection{Surface wave breaking parameterization} 
    280 %-----------------------------------------------------------------------% 
    281286 
    282287Following \citet{mellor.blumberg_JPO04}, the TKE turbulence closure model has been modified to 
     
    284289This results in a reduction of summertime surface temperature when the mixed layer is relatively shallow. 
    285290The \citet{mellor.blumberg_JPO04} modifications acts on surface length scale and TKE values and 
    286 air-sea drag coefficient.  
    287 The latter concerns the bulk formulea and is not discussed here.  
     291air-sea drag coefficient. 
     292The latter concerns the bulk formulae and is not discussed here. 
    288293 
    289294Following \citet{craig.banner_JPO94}, the boundary condition on surface TKE value is : 
     
    293298\end{equation} 
    294299where $\alpha_{CB}$ is the \citet{craig.banner_JPO94} constant of proportionality which depends on the ''wave age'', 
    295 ranging from 57 for mature waves to 146 for younger waves \citep{mellor.blumberg_JPO04}.  
     300ranging from 57 for mature waves to 146 for younger waves \citep{mellor.blumberg_JPO04}. 
    296301The boundary condition on the turbulent length scale follows the Charnock's relation: 
    297302\begin{equation} 
     
    304309$\alpha_{CB} = 100$ the Craig and Banner's value. 
    305310As the surface boundary condition on TKE is prescribed through $\bar{e}_o = e_{bb} |\tau| / \rho_o$, 
    306 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 
    307312to $\alpha_{CB} = 100$. 
    308 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, 
    309314with $\beta$ hard coded to the Stacey's value. 
    310 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 
    311316surface $\bar{e}$ value. 
    312317 
     318%% ================================================================================================= 
    313319\subsubsection{Langmuir cells} 
    314 %--------------------------------------% 
    315320 
    316321Langmuir circulations (LC) can be described as ordered large-scale vertical motions in 
     
    320325The detailed physics behind LC is described in, for example, \citet{craik.leibovich_JFM76}. 
    321326The prevailing explanation is that LC arise from a nonlinear interaction between the Stokes drift and 
    322 wind drift currents.  
     327wind drift currents. 
    323328 
    324329Here we introduced in the TKE turbulent closure the simple parameterization of Langmuir circulations proposed by 
    325330\citep{axell_JGR02} for a $k-\epsilon$ turbulent closure. 
    326331The parameterization, tuned against large-eddy simulation, includes the whole effect of LC in 
    327 an extra source terms of TKE, $P_{LC}$. 
    328 The presence of $P_{LC}$ in \autoref{eq:zdftke_e}, the TKE equation, is controlled by setting \np{ln\_lc} to 
    329 \forcode{.true.} in the namtke namelist. 
    330   
     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 
    331336By making an analogy with the characteristic convective velocity scale (\eg, \citet{dalessio.abdella.ea_JPO98}), 
    332 $P_{LC}$ is assumed to be :  
     337$P_{LC}$ is assumed to be : 
    333338\[ 
    334339P_{LC}(z) = \frac{w_{LC}^3(z)}{H_{LC}} 
    335340\] 
    336341where $w_{LC}(z)$ is the vertical velocity profile of LC, and $H_{LC}$ is the LC depth. 
    337 With no information about the wave field, $w_{LC}$ is assumed to be proportional to  
    338 the Stokes drift $u_s = 0.377\,\,|\tau|^{1/2}$, where $|\tau|$ is the surface wind stress module  
     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 
    339344\footnote{Following \citet{li.garrett_JMR93}, the surface Stoke drift velocity may be expressed as 
    340345  $u_s =  0.016 \,|U_{10m}|$. 
     
    344349For the vertical variation, $w_{LC}$ is assumed to be zero at the surface as well as at 
    345350a finite depth $H_{LC}$ (which is often close to the mixed layer depth), 
    346 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). 
    347352The resulting expression for $w_{LC}$ is : 
    348353\[ 
     
    355360where $c_{LC} = 0.15$ has been chosen by \citep{axell_JGR02} as a good compromise to fit LES data. 
    356361The chosen value yields maximum vertical velocities $w_{LC}$ of the order of a few centimeters per second. 
    357 The value of $c_{LC}$ is set through the \np{rn\_lc} namelist parameter, 
    358 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}. 
    359364 
    360365The $H_{LC}$ is estimated in a similar way as the turbulent length scale of TKE equations: 
    361 $H_{LC}$ is depth to which a water parcel with kinetic energy due to Stoke drift can reach on its own by 
    362 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 
    363368\[ 
    364369- \int_{-H_{LC}}^0 { N^2\;z  \;dz} = \frac{1}{2} u_s^2 
    365370\] 
    366371 
     372%% ================================================================================================= 
    367373\subsubsection{Mixing just below the mixed layer} 
    368 %--------------------------------------------------------------% 
    369374 
    370375Vertical mixing parameterizations commonly used in ocean general circulation models tend to 
    371376produce mixed-layer depths that are too shallow during summer months and windy conditions. 
    372377This bias is particularly acute over the Southern Ocean. 
    373 To overcome this systematic bias, an ad hoc parameterization is introduced into the TKE scheme \cite{rodgers.aumont.ea_B14}.  
    374 The parameterization is an empirical one, \ie not derived from theoretical considerations, 
    375 but rather is meant to account for observed processes that affect the density structure of  
    376 the ocean’s planetary boundary layer that are not explicitly captured by default in the TKE scheme  
    377 (\ie near-inertial oscillations and ocean swells and waves). 
    378  
    379 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}), 
    380385the TKE input to the ocean ($S$) imposed by the winds in the form of near-inertial oscillations, 
    381386swell and waves is parameterized by \autoref{eq:ZDF_Esbc} the standard TKE surface boundary condition, 
     
    386391\end{equation} 
    387392where $z$ is the depth, $e_s$ is TKE surface boundary condition, $f_r$ is the fraction of the surface TKE that 
    388 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 
    389394the penetration, and $f_i$ is the ice concentration 
    390 (no penetration if $f_i=1$, that is if the ocean is entirely covered by sea-ice). 
    391 The value of $f_r$, usually a few percents, is specified through \np{rn\_efr} namelist parameter. 
    392 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 
    393398a latitude dependent value (varying from 0.5~m at the Equator to a maximum value of 30~m at high latitudes 
    394 (\np{nn\_etau}\forcode{ = 1}).  
    395  
    396 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}. 
    397402They correspond to applying \autoref{eq:ZDF_Ehtau} only at the base of the mixed layer, 
    398 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. 
    399404Those two options are obsolescent features introduced for test purposes. 
    400 They will be removed in the next release.  
    401  
    402 % from Burchard et al OM 2008 :  
    403 % the most critical process not reproduced by statistical turbulence models is the activity of  
    404 % internal waves and their interaction with turbulence. After the Reynolds decomposition,  
    405 % internal waves are in principle included in the RANS equations, but later partially  
    406 % excluded by the hydrostatic assumption and the model resolution.  
    407 % Thus far, the representation of internal wave mixing in ocean models has been relatively crude  
    408 % (\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. 
    409535 
    410536% ------------------------------------------------------------------------------------------------------------- 
    411 %        TKE discretization considerations 
     537%        OSM OSMOSIS BL Scheme 
    412538% ------------------------------------------------------------------------------------------------------------- 
    413 \subsection[TKE discretization considerations (\texttt{\textbf{key\_zdftke}})] 
    414 {TKE discretization considerations (\protect\key{zdftke})} 
    415 \label{subsec:ZDF_tke_ene} 
    416  
    417 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     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). 
    418644\begin{figure}[!t] 
    419645  \begin{center} 
    420     \includegraphics[width=\textwidth]{Fig_ZDF_TKE_time_scheme} 
     646    %\includegraphics[width=0.7\textwidth]{ZDF_OSM_structure_of_OSBL} 
    421647    \caption{ 
    422       \protect\label{fig:TKE_time_scheme} 
    423       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. 
    424650    } 
    425   \end{center}   
     651  \end{center} 
    426652\end{figure} 
    427 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     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} 
    428765 
    429766The production of turbulence by vertical shear (the first term of the right hand side of 
    430 \autoref{eq:zdftke_e}) should balance the loss of kinetic energy associated with the vertical momentum diffusion 
    431 (first line in \autoref{eq:PE_zdf}). 
    432 To do so a special care have to be taken for both the time and space discretization of 
    433 the TKE equation \citep{burchard_OM02,marsaleix.auclair.ea_OM08}. 
    434  
    435 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 
    436773the two-level Leap-Frog time stepping of the momentum and tracer equations interplays with 
    437 the one-level forward time stepping of TKE equation. 
     774the one-level forward time stepping of the equation for $\bar{e}$. 
    438775With this framework, the total loss of kinetic energy (in 1D for the demonstration) due to 
    439776the vertical momentum diffusion is obtained by multiplying this quantity by $u^t$ and 
    440 summing the result vertically:    
     777summing the result vertically: 
    441778\begin{equation} 
    442   \label{eq:energ1} 
     779  \label{eq:ZDF_energ1} 
    443780  \begin{split} 
    444781    \int_{-H}^{\eta}  u^t \,\partial_z &\left( {K_m}^t \,(\partial_z u)^{t+\rdt}  \right) \,dz   \\ 
     
    448785\end{equation} 
    449786Here, the vertical diffusion of momentum is discretized backward in time with a coefficient, $K_m$, 
    450 known at time $t$ (\autoref{fig:TKE_time_scheme}), as it is required when using the TKE scheme 
    451 (see \autoref{sec:STP_forward_imp}). 
    452 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 
    453790the surface (atmospheric forcing) and at the bottom (friction effect). 
    454791The second term is always negative. 
    455792It is the dissipation rate of kinetic energy, and thus minus the shear production rate of $\bar{e}$. 
    456 \autoref{eq:energ1} implies that, to be energetically consistent, 
     793\autoref{eq:ZDF_energ1} implies that, to be energetically consistent, 
    457794the production rate of $\bar{e}$ used to compute $(\bar{e})^t$ (and thus ${K_m}^t$) should be expressed as 
    458795${K_m}^{t-\rdt}\,(\partial_z u)^{t-\rdt} \,(\partial_z u)^t$ 
     
    460797 
    461798A similar consideration applies on the destruction rate of $\bar{e}$ due to stratification 
    462 (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}). 
    463800This term must balance the input of potential energy resulting from vertical mixing. 
    464 The rate of change of potential energy (in 1D for the demonstration) due vertical mixing is obtained by 
    465 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: 
    466803\begin{equation} 
    467   \label{eq:energ2} 
     804  \label{eq:ZDF_energ2} 
    468805  \begin{split} 
    469806    \int_{-H}^{\eta} g\,z\,\partial_z &\left( {K_\rho}^t \,(\partial_k \rho)^{t+\rdt}   \right) \,dz    \\ 
     
    474811  \end{split} 
    475812\end{equation} 
    476 where we use $N^2 = -g \,\partial_k \rho / (e_3 \rho)$.  
    477 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 
    478815there is no diffusive flux through the ocean surface and bottom). 
    479816The second term is minus the destruction rate of  $\bar{e}$ due to stratification. 
    480 Therefore \autoref{eq:energ1} implies that, to be energetically consistent, 
    481 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}. 
    482819 
    483820Let us now address the space discretization issue. 
    484821The vertical eddy coefficients are defined at $w$-point whereas the horizontal velocity components are in 
    485 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}). 
    486823A space averaging is thus required to obtain the shear TKE production term. 
    487 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 
    488825the shear at $t$ and $t-\rdt$ must be performed prior to the averaging. 
    489 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. 
    490827 
    491828The above energetic considerations leads to the following final discrete form for the TKE equation: 
    492829\begin{equation} 
    493   \label{eq:zdftke_ene} 
     830  \label{eq:ZDF_tke_ene} 
    494831  \begin{split} 
    495832    \frac { (\bar{e})^t - (\bar{e})^{t-\rdt} } {\rdt}  \equiv 
     
    508845  \end{split} 
    509846\end{equation} 
    510 where the last two terms in \autoref{eq:zdftke_ene} (vertical diffusion and Kolmogorov dissipation) 
    511 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}). 
    512849Note that the Kolmogorov term has been linearized in time in order to render the implicit computation possible. 
    513 The restart of the TKE scheme requires the storage of $\bar {e}$, $K_m$, $K_\rho$ and $l_\epsilon$ as 
    514 they all appear in the right hand side of \autoref{eq:zdftke_ene}. 
    515 For the latter, it is in fact the ratio $\sqrt{\bar{e}}/l_\epsilon$ which is stored.  
    516  
    517 % ------------------------------------------------------------------------------------------------------------- 
    518 %        GLS Generic Length Scale Scheme  
    519 % ------------------------------------------------------------------------------------------------------------- 
    520 \subsection[GLS: Generic Length Scale (\texttt{\textbf{key\_zdfgls}})] 
    521 {GLS: Generic Length Scale (\protect\key{zdfgls})} 
    522 \label{subsec:ZDF_gls} 
    523  
    524 %--------------------------------------------namzdf_gls--------------------------------------------------------- 
    525  
    526 \nlst{namzdf_gls} 
    527 %-------------------------------------------------------------------------------------------------------------- 
    528  
    529 The Generic Length Scale (GLS) scheme is a turbulent closure scheme based on two prognostic equations: 
    530 one for the turbulent kinetic energy $\bar {e}$, and another for the generic length scale, 
    531 $\psi$ \citep{umlauf.burchard_JMR03, umlauf.burchard_CSR05}. 
    532 This later variable is defined as: $\psi = {C_{0\mu}}^{p} \ {\bar{e}}^{m} \ l^{n}$,  
    533 where the triplet $(p, m, n)$ value given in Tab.\autoref{tab:GLS} allows to recover a number of 
    534 well-known turbulent closures ($k$-$kl$ \citep{mellor.yamada_RG82}, $k$-$\epsilon$ \citep{rodi_JGR87}, 
    535 $k$-$\omega$ \citep{wilcox_AJ88} among others \citep{umlauf.burchard_JMR03,kantha.carniel_JMR03}).  
    536 The GLS scheme is given by the following set of equations: 
    537 \begin{equation} 
    538   \label{eq:zdfgls_e} 
    539   \frac{\partial \bar{e}}{\partial t} = 
    540   \frac{K_m}{\sigma_e e_3 }\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 
    541       +\left( \frac{\partial v}{\partial k} \right)^2} \right] 
    542   -K_\rho \,N^2 
    543   +\frac{1}{e_3}\,\frac{\partial}{\partial k} \left[ \frac{K_m}{e_3}\,\frac{\partial \bar{e}}{\partial k} \right] 
    544   - \epsilon 
    545 \end{equation} 
    546  
    547 \[ 
    548   % \label{eq:zdfgls_psi} 
    549   \begin{split} 
    550     \frac{\partial \psi}{\partial t} =& \frac{\psi}{\bar{e}} \left\{ 
    551       \frac{C_1\,K_m}{\sigma_{\psi} {e_3}}\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 
    552           +\left( \frac{\partial v}{\partial k} \right)^2} \right] 
    553       - C_3 \,K_\rho\,N^2   - C_2 \,\epsilon \,Fw   \right\}             \\ 
    554     &+\frac{1}{e_3}  \;\frac{\partial }{\partial k}\left[ {\frac{K_m}{e_3 } 
    555         \;\frac{\partial \psi}{\partial k}} \right]\; 
    556   \end{split} 
    557 \] 
    558  
    559 \[ 
    560   % \label{eq:zdfgls_kz} 
    561   \begin{split} 
    562     K_m    &= C_{\mu} \ \sqrt {\bar{e}} \ l         \\ 
    563     K_\rho &= C_{\mu'}\ \sqrt {\bar{e}} \ l 
    564   \end{split} 
    565 \] 
    566  
    567 \[ 
    568   % \label{eq:zdfgls_eps} 
    569   {\epsilon} = C_{0\mu} \,\frac{\bar {e}^{3/2}}{l} \; 
    570 \] 
    571 where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}) and 
    572 $\epsilon$ the dissipation rate.  
    573 The constants $C_1$, $C_2$, $C_3$, ${\sigma_e}$, ${\sigma_{\psi}}$ and the wall function ($Fw$) depends of 
    574 the choice of the turbulence model. 
    575 Four different turbulent models are pre-defined (Tab.\autoref{tab:GLS}). 
    576 They are made available through the \np{nn\_clo} namelist parameter.  
    577  
    578 %--------------------------------------------------TABLE-------------------------------------------------- 
    579 \begin{table}[htbp] 
    580   \begin{center} 
    581     % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}c} 
    582     \begin{tabular}{ccccc} 
    583       &   $k-kl$   & $k-\epsilon$ & $k-\omega$ &   generic   \\ 
    584       % & \citep{mellor.yamada_RG82} &  \citep{rodi_JGR87}       & \citep{wilcox_AJ88} &                 \\ 
    585       \hline 
    586       \hline 
    587       \np{nn\_clo}     & \textbf{0} &   \textbf{1}  &   \textbf{2}   &    \textbf{3}   \\ 
    588       \hline 
    589       $( p , n , m )$          &   ( 0 , 1 , 1 )   & ( 3 , 1.5 , -1 )   & ( -1 , 0.5 , -1 )    &  ( 2 , 1 , -0.67 )  \\ 
    590       $\sigma_k$      &    2.44         &     1.              &      2.                &      0.8          \\ 
    591       $\sigma_\psi$  &    2.44         &     1.3            &      2.                 &       1.07       \\ 
    592       $C_1$              &      0.9         &     1.44          &      0.555          &       1.           \\ 
    593       $C_2$              &      0.5         &     1.92          &      0.833          &       1.22       \\ 
    594       $C_3$              &      1.           &     1.              &      1.                &       1.           \\ 
    595       $F_{wall}$        &      Yes        &       --             &     --                  &      --          \\ 
    596       \hline 
    597       \hline 
    598     \end{tabular} 
    599     \caption{ 
    600       \protect\label{tab:GLS} 
    601       Set of predefined GLS parameters, or equivalently predefined turbulence models available with 
    602       \protect\key{zdfgls} and controlled by the \protect\np{nn\_clos} namelist variable in \protect\ngn{namzdf\_gls}. 
    603     } 
    604   \end{center} 
    605 \end{table} 
    606 %-------------------------------------------------------------------------------------------------------------- 
    607  
    608 In the Mellor-Yamada model, the negativity of $n$ allows to use a wall function to force the convergence of 
    609 the mixing length towards $K z_b$ ($K$: Kappa and $z_b$: rugosity length) value near physical boundaries 
    610 (logarithmic boundary layer law). 
    611 $C_{\mu}$ and $C_{\mu'}$ are calculated from stability function proposed by \citet{galperin.kantha.ea_JAS88}, 
    612 or by \citet{kantha.clayson_JGR94} or one of the two functions suggested by \citet{canuto.howard.ea_JPO01} 
    613 (\np{nn\_stab\_func}\forcode{ = 0..3}, resp.).  
    614 The value of $C_{0\mu}$ depends of the choice of the stability function. 
    615  
    616 The surface and bottom boundary condition on both $\bar{e}$ and $\psi$ can be calculated thanks to Dirichlet or 
    617 Neumann condition through \np{nn\_tkebc\_surf} and \np{nn\_tkebc\_bot}, resp. 
    618 As for TKE closure, the wave effect on the mixing is considered when 
    619 \np{ln\_crban}\forcode{ = .true.} \citep{craig.banner_JPO94, mellor.blumberg_JPO04}. 
    620 The \np{rn\_crban} namelist parameter is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and 
    621 \np{rn\_charn} provides the value of $\beta$ in \autoref{eq:ZDF_Lsbc}.  
    622  
    623 The $\psi$ equation is known to fail in stably stratified flows, and for this reason 
    624 almost all authors apply a clipping of the length scale as an \textit{ad hoc} remedy. 
    625 With this clipping, the maximum permissible length scale is determined by $l_{max} = c_{lim} \sqrt{2\bar{e}}/ N$. 
    626 A value of $c_{lim} = 0.53$ is often used \citep{galperin.kantha.ea_JAS88}. 
    627 \cite{umlauf.burchard_CSR05} show that the value of the clipping factor is of crucial importance for 
    628 the entrainment depth predicted in stably stratified situations, 
    629 and that its value has to be chosen in accordance with the algebraic model for the turbulent fluxes. 
    630 The clipping is only activated if \np{ln\_length\_lim}\forcode{ = .true.}, 
    631 and the $c_{lim}$ is set to the \np{rn\_clim\_galp} value. 
    632  
    633 The time and space discretization of the GLS equations follows the same energetic consideration as for 
    634 the TKE case described in \autoref{subsec:ZDF_tke_ene} \citep{burchard_OM02}. 
    635 Examples of performance of the 4 turbulent closure scheme can be found in \citet{warner.sherwood.ea_OM05}. 
    636  
    637 % ------------------------------------------------------------------------------------------------------------- 
    638 %        OSM OSMOSIS BL Scheme  
    639 % ------------------------------------------------------------------------------------------------------------- 
    640 \subsection[OSM: OSMosis boundary layer scheme (\texttt{\textbf{key\_zdfosm}})] 
    641 {OSM: OSMosis boundary layer scheme (\protect\key{zdfosm})} 
    642 \label{subsec:ZDF_osm} 
    643  
    644 %--------------------------------------------namzdf_osm--------------------------------------------------------- 
    645  
    646 \nlst{namzdf_osm} 
    647 %-------------------------------------------------------------------------------------------------------------- 
    648  
    649 The OSMOSIS turbulent closure scheme is based on......   TBC 
    650  
    651 % ================================================================ 
    652 % Convection 
    653 % ================================================================ 
     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%% ================================================================================================= 
    654855\section{Convection} 
    655856\label{sec:ZDF_conv} 
    656857 
    657 %--------------------------------------------namzdf-------------------------------------------------------- 
    658  
    659 \nlst{namzdf} 
    660 %-------------------------------------------------------------------------------------------------------------- 
    661  
    662 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. 
    663859In nature, convective processes quickly re-establish the static stability of the water column. 
    664860These processes have been removed from the model via the hydrostatic assumption so they must be parameterized. 
     
    667863or/and the use of a turbulent closure scheme. 
    668864 
    669 % ------------------------------------------------------------------------------------------------------------- 
    670 %       Non-Penetrative Convective Adjustment  
    671 % ------------------------------------------------------------------------------------------------------------- 
    672 \subsection[Non-penetrative convective adjustment (\forcode{ln_tranpc = .true.})] 
    673 {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})} 
    674867\label{subsec:ZDF_npc} 
    675868 
    676 %--------------------------------------------namzdf-------------------------------------------------------- 
    677  
    678 \nlst{namzdf} 
    679 %-------------------------------------------------------------------------------------------------------------- 
    680  
    681 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    682869\begin{figure}[!htb] 
    683   \begin{center} 
    684     \includegraphics[width=\textwidth]{Fig_npc} 
    685     \caption{ 
    686       \protect\label{fig:npc} 
    687       Example of an unstable density profile treated by the non penetrative convective adjustment algorithm. 
    688       $1^{st}$ step: the initial profile is checked from the surface to the bottom. 
    689       It is found to be unstable between levels 3 and 4. 
    690       They are mixed. 
    691       The resulting $\rho$ is still larger than $\rho$(5): levels 3 to 5 are mixed. 
    692       The resulting $\rho$ is still larger than $\rho$(6): levels 3 to 6 are mixed. 
    693       The $1^{st}$ step ends since the density profile is then stable below the level 3. 
    694       $2^{nd}$ step: the new $\rho$ profile is checked following the same procedure as in $1^{st}$ step: 
    695       levels 2 to 5 are mixed. 
    696       The new density profile is checked. 
    697       It is found stable: end of algorithm. 
    698     } 
    699   \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} 
    700886\end{figure} 
    701 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    702  
    703 Options are defined through the \ngn{namzdf} namelist variables. 
    704 The non-penetrative convective adjustment is used when \np{ln\_zdfnpc}\forcode{ = .true.}. 
    705 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 
    706891the water column, but only until the density structure becomes neutrally stable 
    707 (\ie until the mixed portion of the water column has \textit{exactly} the density of the water just below) 
     892(\ie\ until the mixed portion of the water column has \textit{exactly} the density of the water just below) 
    708893\citep{madec.delecluse.ea_JPO91}. 
    709 The associated algorithm is an iterative process used in the following way (\autoref{fig:npc}): 
     894The associated algorithm is an iterative process used in the following way (\autoref{fig:ZDF_npc}): 
    710895starting from the top of the ocean, the first instability is found. 
    711896Assume in the following that the instability is located between levels $k$ and $k+1$. 
     
    722907This algorithm is significantly different from mixing statically unstable levels two by two. 
    723908The latter procedure cannot converge with a finite number of iterations for some vertical profiles while 
    724 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 
    725910the number of vertical levels. 
    726911This property is of paramount importance as pointed out by \citet{killworth_iprc89}: 
     
    732917(L. Brodeau, personnal communication). 
    733918Two main differences have been introduced compared to the original algorithm: 
    734 $(i)$ the stability is now checked using the Brunt-V\"{a}is\"{a}l\"{a} frequency  
    735 (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); 
    736921$(ii)$ when two levels are found unstable, their thermal and haline expansion coefficients are vertically mixed in 
    737922the same way their temperature and salinity has been mixed. 
     
    739924having to recompute the expansion coefficients at each mixing iteration. 
    740925 
    741 % ------------------------------------------------------------------------------------------------------------- 
    742 %       Enhanced Vertical Diffusion  
    743 % ------------------------------------------------------------------------------------------------------------- 
    744 \subsection[Enhanced vertical diffusion (\forcode{ln_zdfevd = .true.})] 
    745 {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})} 
    746928\label{subsec:ZDF_evd} 
    747929 
    748 %--------------------------------------------namzdf-------------------------------------------------------- 
    749  
    750 \nlst{namzdf} 
    751 %-------------------------------------------------------------------------------------------------------------- 
    752  
    753 Options are defined through the  \ngn{namzdf} namelist variables. 
    754 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}. 
    755932In this case, the vertical eddy mixing coefficients are assigned very large values 
    756 (a typical value is $10\;m^2s^{-1})$ in regions where the stratification is unstable 
    757 (\ie when $N^2$ the Brunt-Vais\"{a}l\"{a} frequency is negative) \citep{lazar_phd97, lazar.madec.ea_JPO99}. 
    758 This is done either on tracers only (\np{nn\_evdm}\forcode{ = 0}) or 
    759 on both momentum and tracers (\np{nn\_evdm}\forcode{ = 1}). 
    760  
    761 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}, 
    762939the four neighbouring $A_u^{vm} \;\mbox{and}\;A_v^{vm}$ values also, are set equal to 
    763 the namelist parameter \np{rn\_avevd}. 
     940the namelist parameter \np{rn_avevd}{rn\_avevd}. 
    764941A typical value for $rn\_avevd$ is between 1 and $100~m^2.s^{-1}$. 
    765942This parameterisation of convective processes is less time consuming than 
    766943the convective adjustment algorithm presented above when mixing both tracers and 
    767944momentum in the case of static instabilities. 
    768 It requires the use of an implicit time stepping on vertical diffusion terms 
    769 (\ie np{ln\_zdfexp}\forcode{ = .false.}). 
    770945 
    771946Note that the stability test is performed on both \textit{before} and \textit{now} values of $N^2$. 
    772947This removes a potential source of divergence of odd and even time step in 
    773 a leapfrog environment \citep{leclair_phd10} (see \autoref{sec:STP_mLF}). 
    774  
    775 % ------------------------------------------------------------------------------------------------------------- 
    776 %       Turbulent Closure Scheme  
    777 % ------------------------------------------------------------------------------------------------------------- 
    778 \subsection[Turbulent closure scheme (\texttt{\textbf{key\_zdf}}\texttt{\textbf{\{tke,gls,osm\}}})] 
    779 {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}})} 
    780952\label{subsec:ZDF_tcs} 
    781953 
    782 The turbulent closure scheme presented in \autoref{subsec:ZDF_tke} and \autoref{subsec:ZDF_gls} 
    783 (\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. 
    784957In such a case, the term corresponding to the destruction of turbulent kinetic energy through stratification in 
    785 \autoref{eq:zdftke_e} or \autoref{eq:zdfgls_e} becomes a source term, since $N^2$ is negative.  
    786 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}$ 
    787 (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}$). 
    788961These large values restore the static stability of the water column in a way similar to that of 
    789962the enhanced vertical diffusion parameterisation (\autoref{subsec:ZDF_evd}). 
     
    792965because the mixing length scale is bounded by the distance to the sea surface. 
    793966It can thus be useful to combine the enhanced vertical diffusion with the turbulent closure scheme, 
    794 \ie setting the \np{ln\_zdfnpc} namelist parameter to true and 
    795 defining the turbulent closure CPP key all together. 
    796  
    797 The KPP turbulent closure scheme already includes enhanced vertical diffusion in the case of convection, 
    798 as governed by the variables $bvsqcon$ and $difcon$ found in \mdl{zdfkpp}, 
    799 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. 
    800973% gm%  + one word on non local flux with KPP scheme trakpp.F90 module... 
    801974 
    802 % ================================================================ 
    803 % Double Diffusion Mixing 
    804 % ================================================================ 
    805 \section[Double diffusion mixing (\texttt{\textbf{key\_zdfddm}})] 
    806 {Double diffusion mixing (\protect\key{zdfddm})} 
    807 \label{sec:ZDF_ddm} 
    808  
    809 %-------------------------------------------namzdf_ddm------------------------------------------------- 
    810 % 
     975%% ================================================================================================= 
     976\section[Double diffusion mixing (\forcode{ln_zdfddm})]{Double diffusion mixing (\protect\np{ln_zdfddm}{ln\_zdfddm})} 
     977\label{subsec:ZDF_ddm} 
     978 
    811979%\nlst{namzdf_ddm} 
    812 %-------------------------------------------------------------------------------------------------------------- 
    813  
    814 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}. 
    815983Double diffusion occurs when relatively warm, salty water overlies cooler, fresher water, or vice versa. 
    816984The former condition leads to salt fingering and the latter to diffusive convection. 
    817985Double-diffusive phenomena contribute to diapycnal mixing in extensive regions of the ocean. 
    818 \citet{merryfield.holloway.ea_JPO99} 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 
    819987it leads to relatively minor changes in circulation but exerts significant regional influences on 
    820988temperature and salinity. 
    821 This parameterisation has been introduced in \mdl{zdfddm} module and is controlled by the \key{zdfddm} CPP key. 
    822  
    823 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 
    824991\begin{align*} 
    825   % \label{eq:zdfddm_Kz} 
     992  % \label{eq:ZDF_ddm_Kz} 
    826993  &A^{vT} = A_o^{vT}+A_f^{vT}+A_d^{vT} \\ 
    827994  &A^{vS} = A_o^{vS}+A_f^{vS}+A_d^{vS} 
     
    8351002(1981): 
    8361003\begin{align} 
    837   \label{eq:zdfddm_f} 
     1004  \label{eq:ZDF_ddm_f} 
    8381005  A_f^{vS} &= 
    8391006             \begin{cases} 
     
    8411008               0                              &\text{otherwise} 
    8421009             \end{cases} 
    843   \\         \label{eq:zdfddm_f_T} 
    844   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 
    8451012\end{align} 
    8461013 
    847 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    8481014\begin{figure}[!t] 
    849   \begin{center} 
    850     \includegraphics[width=\textwidth]{Fig_zdfddm} 
    851     \caption{ 
    852       \protect\label{fig:zdfddm} 
    853       From \citet{merryfield.holloway.ea_JPO99} : 
    854       (a) Diapycnal diffusivities $A_f^{vT}$ and $A_f^{vS}$ for temperature and salt in regions of salt fingering. 
    855       Heavy curves denote $A^{\ast v} = 10^{-3}~m^2.s^{-1}$ and thin curves $A^{\ast v} = 10^{-4}~m^2.s^{-1}$; 
    856       (b) diapycnal diffusivities $A_d^{vT}$ and $A_d^{vS}$ for temperature and salt in regions of 
    857       diffusive convection. 
    858       Heavy curves denote the Federov parameterisation and thin curves the Kelley parameterisation. 
    859       The latter is not implemented in \NEMO. 
    860     } 
    861   \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} 
    8621029\end{figure} 
    863 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    864  
    865 The factor 0.7 in \autoref{eq:zdfddm_f_T} reflects the measured ratio $\alpha F_T /\beta F_S \approx  0.7$ of 
     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 
    8661032buoyancy flux of heat to buoyancy flux of salt (\eg, \citet{mcdougall.taylor_JMR84}). 
    8671033Following  \citet{merryfield.holloway.ea_JPO99}, we adopt $R_c = 1.6$, $n = 6$, and $A^{\ast v} = 10^{-4}~m^2.s^{-1}$. 
    8681034 
    8691035To represent mixing of S and T by diffusive layering,  the diapycnal diffusivities suggested by 
    870 Federov (1988) is used:  
     1036Federov (1988) is used: 
    8711037\begin{align} 
    872   % \label{eq:zdfddm_d} 
     1038  % \label{eq:ZDF_ddm_d} 
    8731039  A_d^{vT} &= 
    8741040             \begin{cases} 
     
    8781044             \end{cases} 
    8791045                                       \nonumber \\ 
    880   \label{eq:zdfddm_d_S} 
     1046  \label{eq:ZDF_ddm_d_S} 
    8811047  A_d^{vS} &= 
    8821048             \begin{cases} 
     
    8871053\end{align} 
    8881054 
    889 The dependencies of \autoref{eq:zdfddm_f} to \autoref{eq:zdfddm_d_S} on $R_\rho$ are illustrated in 
    890 \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}. 
    8911057Implementing this requires computing $R_\rho$ at each grid point on every time step. 
    8921058This is done in \mdl{eosbn2} at the same time as $N^2$ is computed. 
    8931059This avoids duplication in the computation of $\alpha$ and $\beta$ (which is usually quite expensive). 
    8941060 
    895 % ================================================================ 
    896 % Bottom Friction 
    897 % ================================================================ 
    898 \section[Bottom and top friction (\textit{zdfbfr.F90})] 
    899 {Bottom and top friction (\protect\mdl{zdfbfr})} 
    900 \label{sec:ZDF_bfr} 
    901  
    902 %--------------------------------------------nambfr-------------------------------------------------------- 
    903 % 
    904 %\nlst{nambfr} 
    905 %-------------------------------------------------------------------------------------------------------------- 
    906  
    907 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. 
    9081082The bottom friction represents the friction generated by the bathymetry. 
    9091083The top friction represents the friction generated by the ice shelf/ocean interface. 
    910 As the friction processes at the top and bottom are treated in similar way, 
    911 only the bottom friction is described in detail below. 
    912  
     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. 
    9131086 
    9141087Both the surface momentum flux (wind stress) and the bottom momentum flux (bottom friction) enter the equations as 
    9151088a condition on the vertical diffusive flux. 
    9161089For the bottom boundary layer, one has: 
    917 \[ 
    918   % \label{eq:zdfbfr_flux} 
    919   A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U} 
    920 \] 
     1090 \[ 
     1091   % \label{eq:ZDF_bfr_flux} 
     1092   A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U} 
     1093 \] 
    9211094where ${\cal F}_h^{\textbf U}$ is represents the downward flux of horizontal momentum outside 
    9221095the logarithmic turbulent boundary layer (thickness of the order of 1~m in the ocean). 
     
    9261099one needs a vertical diffusion coefficient $A^{vm} = 0.125$~m$^2$s$^{-1}$ 
    9271100(for a Coriolis frequency $f = 10^{-4}$~m$^2$s$^{-1}$). 
    928 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. 
    9291102When the vertical mixing coefficient is this small, using a flux condition is equivalent to 
    9301103entering the viscous forces (either wind stress or bottom friction) as a body force over the depth of the top or 
     
    9321105To illustrate this, consider the equation for $u$ at $k$, the last ocean level: 
    9331106\begin{equation} 
    934   \label{eq:zdfbfr_flux2} 
     1107  \label{eq:ZDF_drg_flux2} 
    9351108  \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}} 
    9361109\end{equation} 
     
    9451118 
    9461119In the code, the bottom friction is imposed by adding the trend due to the bottom friction to 
    947 the general momentum trend in \mdl{dynbfr}. 
     1120 the general momentum trend in \mdl{dynzdf}. 
    9481121For the time-split surface pressure gradient algorithm, the momentum trend due to 
    9491122the barotropic component needs to be handled separately. 
    9501123For this purpose it is convenient to compute and store coefficients which can be simply combined with 
    9511124bottom velocities and geometric values to provide the momentum trend due to bottom friction. 
    952 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: 
    9531126\begin{equation} 
    954   \label{eq:zdfbfr_bdef} 
     1127  \label{eq:ZDF_bfr_bdef} 
    9551128  \frac{\partial {\textbf U_h}}{\partial t} = 
    9561129  - \frac{{\cal F}^{\textbf U}_{h}}{e_{3u}} = \frac{c_b^{\textbf U}}{e_{3u}} \;{\textbf U}_h^b 
    9571130\end{equation} 
    9581131where $\textbf{U}_h^b = (u_b\;,\;v_b)$ is the near-bottom, horizontal, ocean velocity. 
    959  
    960 % ------------------------------------------------------------------------------------------------------------- 
    961 %       Linear Bottom Friction 
    962 % ------------------------------------------------------------------------------------------------------------- 
    963 \subsection[Linear bottom friction (\forcode{nn_botfr = [01]})] 
    964 {Linear bottom friction (\protect\np{nn\_botfr}\forcode{ = [01])}} 
    965 \label{subsec:ZDF_bfr_linear} 
    966  
    967 The linear bottom friction parameterisation (including the special case of a free-slip condition) assumes that 
    968 the bottom friction is proportional to the interior velocity (\ie the velocity of the last model level): 
    969 \[ 
    970   % \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} 
    9711142  {\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3} \; \frac{\partial \textbf{U}_h}{\partial k} = r \; \textbf{U}_h^b 
    9721143\] 
    973 where $r$ is a friction coefficient expressed in ms$^{-1}$. 
    974 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, 
    9751146and setting $r = H / \tau$, where $H$ is the ocean depth. 
    9761147Commonly accepted values of $\tau$ are of the order of 100 to 200 days \citep{weatherly_JMR84}. 
     
    9811152and assuming an ocean depth $H = 4000$~m, the resulting friction coefficient is $r = 4\;10^{-4}$~m\;s$^{-1}$. 
    9821153This is the default value used in \NEMO. It corresponds to a decay time scale of 115~days. 
    983 It can be changed by specifying \np{rn\_bfri1} (namelist parameter). 
    984  
    985 For the linear friction case the coefficients defined in the general expression \autoref{eq:zdfbfr_bdef} are:  
    986 \[ 
    987   % \label{eq:zdfbfr_linbfr_b} 
    988   \begin{split} 
    989     c_b^u &= - r\\ 
    990     c_b^v &= - r\\ 
    991   \end{split} 
    992 \] 
    993 When \np{nn\_botfr}\forcode{ = 1}, the value of $r$ used is \np{rn\_bfri1}. 
    994 Setting \np{nn\_botfr}\forcode{ = 0} is equivalent to setting $r=0$ and 
    995 leads to a free-slip bottom boundary condition. 
    996 These values are assigned in \mdl{zdfbfr}. 
    997 From v3.2 onwards there is support for local enhancement of these values via an externally defined 2D mask array 
    998 (\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. 
    9991167The mask values should vary from 0 to 1. 
    10001168Locations with a non-zero mask value will have the friction coefficient increased by 
    1001 $mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri1}. 
    1002  
    1003 % ------------------------------------------------------------------------------------------------------------- 
    1004 %       Non-Linear Bottom Friction 
    1005 % ------------------------------------------------------------------------------------------------------------- 
    1006 \subsection[Non-linear bottom friction (\forcode{nn_botfr = 2})] 
    1007 {Non-linear bottom friction (\protect\np{nn\_botfr}\forcode{ = 2})} 
    1008 \label{subsec:ZDF_bfr_nonlinear} 
    1009  
    1010 The non-linear bottom friction parameterisation assumes that the bottom friction is quadratic:  
    1011 \[ 
    1012   % \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} 
    10131178  {\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3 }\frac{\partial \textbf {U}_h 
    10141179  }{\partial k}=C_D \;\sqrt {u_b ^2+v_b ^2+e_b } \;\; \textbf {U}_h^b 
    10151180\] 
    1016 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, 
    10171182internal waves breaking and other short time scale currents. 
    10181183A typical value of the drag coefficient is $C_D = 10^{-3} $. 
     
    10201185$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 
    10211186$e_b =2.5\;\;10^{-3}$m$^2$\;s$^{-2}$. 
    1022 The CME choices have been set as default values (\np{rn\_bfri2} and \np{rn\_bfeb2} namelist parameters). 
    1023  
    1024 As for the linear case, the bottom friction is imposed in the code by adding the trend due to 
    1025 the bottom friction to the general momentum trend in \mdl{dynbfr}. 
    1026 For the non-linear friction case the terms computed in \mdl{zdfbfr} are: 
    1027 \[ 
    1028   % \label{eq:zdfbfr_nonlinbfr} 
    1029   \begin{split} 
    1030     c_b^u &= - \; C_D\;\left[ u^2 + \left(\bar{\bar{v}}^{i+1,j}\right)^2 + e_b \right]^{1/2}\\ 
    1031     c_b^v &= - \; C_D\;\left[  \left(\bar{\bar{u}}^{i,j+1}\right)^2 + v^2 + e_b \right]^{1/2}\\ 
    1032   \end{split} 
    1033 \] 
    1034  
    1035 The coefficients that control the strength of the non-linear bottom friction are initialised as namelist parameters: 
    1036 $C_D$= \np{rn\_bfri2}, and $e_b$ =\np{rn\_bfeb2}. 
    1037 Note for applications which treat tides explicitly a low or even zero value of \np{rn\_bfeb2} is recommended. 
    1038 From v3.2 onwards a local enhancement of $C_D$ is possible via an externally defined 2D mask array 
    1039 (\np{ln\_bfr2d}\forcode{ = .true.}). 
    1040 This works in the same way as for the linear bottom friction case with non-zero masked locations increased by 
    1041 $mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri2}. 
    1042  
    1043 % ------------------------------------------------------------------------------------------------------------- 
    1044 %       Bottom Friction Log-layer 
    1045 % ------------------------------------------------------------------------------------------------------------- 
    1046 \subsection[Log-layer bottom friction enhancement (\forcode{nn_botfr = 2}, \forcode{ln_loglayer = .true.})] 
    1047 {Log-layer bottom friction enhancement (\protect\np{nn\_botfr}\forcode{ = 2}, \protect\np{ln\_loglayer}\forcode{ = .true.})} 
    1048 \label{subsec:ZDF_bfr_loglayer} 
    1049  
    1050 In the non-linear bottom friction case, the drag coefficient, $C_D$, can be optionally enhanced using 
    1051 a "law of the wall" scaling. 
    1052 If  \np{ln\_loglayer} = .true., $C_D$ is no longer constant but is related to the thickness of 
    1053 the last wet layer in each column by: 
    1054 \[ 
    1055   C_D = \left ( {\kappa \over {\mathrm log}\left ( 0.5e_{3t}/rn\_bfrz0 \right ) } \right )^2 
    1056 \] 
    1057  
    1058 \noindent where $\kappa$ is the von-Karman constant and \np{rn\_bfrz0} is a roughness length provided via 
    1059 the namelist. 
    1060  
    1061 For stability, the drag coefficient is bounded such that it is kept greater or equal to 
    1062 the base \np{rn\_bfri2} value and it is not allowed to exceed the value of an additional namelist parameter: 
    1063 \np{rn\_bfri2\_max}, \ie 
    1064 \[ 
    1065   rn\_bfri2 \leq C_D \leq rn\_bfri2\_max 
    1066 \] 
    1067  
    1068 \noindent Note also that a log-layer enhancement can also be applied to the top boundary friction if 
    1069 under ice-shelf cavities are in use (\np{ln\_isfcav}\forcode{ = .true.}). 
    1070 In this case, the relevant namelist parameters are \np{rn\_tfrz0}, \np{rn\_tfri2} and \np{rn\_tfri2\_max}. 
    1071  
    1072 % ------------------------------------------------------------------------------------------------------------- 
    1073 %       Bottom Friction stability 
    1074 % ------------------------------------------------------------------------------------------------------------- 
    1075 \subsection{Bottom friction stability considerations} 
    1076 \label{subsec:ZDF_bfr_stability} 
    1077  
    1078 Some care needs to exercised over the choice of parameters to ensure that the implementation of 
    1079 bottom friction does not induce numerical instability. 
    1080 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: 
    10811248\begin{equation} 
    1082   \label{eq:Eqn_bfrstab} 
     1249  \label{eq:ZDF_Eqn_drgstab} 
    10831250  \begin{split} 
    10841251    \Delta u &= -\frac{{{\cal F}_h}^u}{e_{3u}}\;2 \rdt    \\ 
     
    10861253  \end{split} 
    10871254\end{equation} 
    1088 \noindent where linear bottom friction and a leapfrog timestep have been assumed. 
    1089 To ensure that the bottom friction cannot reverse the direction of flow it is necessary to have: 
    1090 \[ 
    1091   |\Delta u| < \;|u|  
    1092 \] 
    1093 \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: 
    10941261\[ 
    10951262  r\frac{2\rdt}{e_{3u}} < 1 \qquad  \Rightarrow \qquad r < \frac{e_{3u}}{2\rdt}\\ 
     
    11041271For example, if $|u| = 1$ m.s$^{-1}$, $rdt = 1800$ s, $r = 10^{-3}$ then $e_{3u}$ should be greater than 3.6 m. 
    11051272For most applications, with physically sensible parameters these restrictions should not be of concern. 
    1106 But caution may be necessary if attempts are made to locally enhance the bottom friction parameters.  
    1107 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 
    11081275during initialisation and at each time step. 
    1109 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). 
    11101277The number of breaches of the stability criterion are reported as well as 
    11111278the minimum and maximum values that have been set. 
    1112 The criterion is also checked at each time step, using the actual velocity, in \mdl{dynbfr}. 
    1113 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; 
    11141281these changes are not reported. 
    11151282 
    1116 Limits on the bottom friction coefficient are not imposed if the user has elected to 
    1117 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}). 
    11181285The number of potential breaches of the explicit stability criterion are still reported for information purposes. 
    11191286 
    1120 % ------------------------------------------------------------------------------------------------------------- 
    1121 %       Implicit Bottom Friction 
    1122 % ------------------------------------------------------------------------------------------------------------- 
    1123 \subsection[Implicit bottom friction (\forcode{ln_bfrimp = .true.})] 
    1124 {Implicit bottom friction (\protect\np{ln\_bfrimp}\forcode{ = .true.})} 
    1125 \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} 
    11261290 
    11271291An optional implicit form of bottom friction has been implemented to improve model stability. 
    1128 We recommend this option for shelf sea and coastal ocean applications, especially for split-explicit time splitting. 
    1129 This option can be invoked by setting \np{ln\_bfrimp} to \forcode{.true.} in the \textit{nambfr} namelist. 
    1130 This option requires \np{ln\_zdfexp} to be \forcode{.false.} in the \textit{namzdf} namelist.  
    1131  
    1132 This implementation is realised in \mdl{dynzdf\_imp} and \mdl{dynspg\_ts}. In \mdl{dynzdf\_imp}, 
    1133 the bottom boundary condition is implemented implicitly. 
    1134  
    1135 \[ 
    1136   % \label{eq:dynzdf_bfr} 
    1137   \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{mbk} 
    1138   = \binom{c_{b}^{u}u^{n+1}_{mbk}}{c_{b}^{v}v^{n+1}_{mbk}} 
    1139 \] 
    1140  
    1141 where $mbk$ is the layer number of the bottom wet layer. 
    1142 Superscript $n+1$ means the velocity used in the friction formula is to be calculated, so, it is implicit. 
    1143  
    1144 If split-explicit time splitting is used, care must be taken to avoid the double counting of the bottom friction in 
    1145 the 2-D barotropic momentum equations. 
    1146 As NEMO only updates the barotropic pressure gradient and Coriolis' forcing terms in the 2-D barotropic calculation, 
    1147 we need to remove the bottom friction induced by these two terms which has been included in the 3-D momentum trend  
    1148 and update it with the latest value. 
    1149 On the other hand, the bottom friction contributed by the other terms 
    1150 (\eg the advection term, viscosity term) has been included in the 3-D momentum equations and 
    1151 should not be added in the 2-D barotropic mode. 
    1152  
    1153 The implementation of the implicit bottom friction in \mdl{dynspg\_ts} is done in two steps as the following: 
    1154  
    1155 \[ 
    1156   % \label{eq:dynspg_ts_bfr1} 
    1157   \frac{\textbf{U}_{med}-\textbf{U}^{m-1}}{2\Delta t}=-g\nabla\eta-f\textbf{k}\times\textbf{U}^{m}+c_{b} 
    1158   \left(\textbf{U}_{med}-\textbf{U}^{m-1}\right) 
    1159 \] 
    1160 \[ 
    1161   \frac{\textbf{U}^{m+1}-\textbf{U}_{med}}{2\Delta t}=\textbf{T}+ 
    1162   \left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{U}^{'}\right)- 
    1163   2\Delta t_{bc}c_{b}\left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{u}_{b}\right) 
    1164 \] 
    1165  
    1166 where $\textbf{T}$ is the vertical integrated 3-D momentum trend. 
    1167 We assume the leap-frog time-stepping is used here. 
    1168 $\Delta t$ is the barotropic mode time step and $\Delta t_{bc}$ is the baroclinic mode time step. 
    1169 $c_{b}$ is the friction coefficient. 
    1170 $\eta$ is the sea surface level calculated in the barotropic loops while $\eta^{'}$ is the sea surface level used in 
    1171 the 3-D baroclinic mode. 
    1172 $\textbf{u}_{b}$ is the bottom layer horizontal velocity. 
    1173  
    1174 % ------------------------------------------------------------------------------------------------------------- 
    1175 %       Bottom Friction with split-explicit time splitting 
    1176 % ------------------------------------------------------------------------------------------------------------- 
    1177 \subsection[Bottom friction with split-explicit time splitting (\texttt{ln\_bfrimp})] 
    1178 {Bottom friction with split-explicit time splitting (\protect\np{ln\_bfrimp})} 
    1179 \label{subsec:ZDF_bfr_ts} 
    1180  
    1181 When calculating the momentum trend due to bottom friction in \mdl{dynbfr}, 
    1182 the bottom velocity at the before time step is used. 
    1183 This velocity includes both the baroclinic and barotropic components which is appropriate when 
    1184 using either the explicit or filtered surface pressure gradient algorithms 
    1185 (\key{dynspg\_exp} or \key{dynspg\_flt}). 
    1186 Extra attention is required, however, when using split-explicit time stepping (\key{dynspg\_ts}). 
    1187 In this case the free surface equation is solved with a small time step \np{rn\_rdt}/\np{nn\_baro}, 
    1188 while the three dimensional prognostic variables are solved with the longer time step of \np{rn\_rdt} seconds. 
    1189 The trend in the barotropic momentum due to bottom friction appropriate to this method is that given by 
    1190 the selected parameterisation (\ie linear or non-linear bottom friction) computed with 
    1191 the evolving velocities at each barotropic timestep.  
    1192  
    1193 In the case of non-linear bottom friction, we have elected to partially linearise the problem by 
    1194 keeping the coefficients fixed throughout the barotropic time-stepping to those computed in 
    1195 \mdl{zdfbfr} using the now timestep. 
    1196 This decision allows an efficient use of the $c_b^{\vect{U}}$ coefficients to: 
    1197  
     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: 
    11981322\begin{enumerate} 
    1199 \item On entry to \rou{dyn\_spg\_ts}, remove the contribution of the before barotropic velocity to 
    1200   the bottom friction component of the vertically integrated momentum trend. 
    1201   Note the same stability check that is carried out on the bottom friction coefficient in \mdl{dynbfr} has to 
    1202   be applied here to ensure that the trend removed matches that which was added in \mdl{dynbfr}. 
    1203 \item At each barotropic step, compute the contribution of the current barotropic velocity to 
    1204   the trend due to bottom friction. 
    1205   Add this contribution to the vertically integrated momentum trend. 
    1206   This contribution is handled implicitly which eliminates the need to impose a stability criteria on 
    1207   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. 
    12081325\end{enumerate} 
    12091326 
    1210 Note that the use of an implicit formulation within the barotropic loop for the bottom friction trend means that 
    1211 any limiting of the bottom friction coefficient in \mdl{dynbfr} does not adversely affect the solution when 
    1212 using split-explicit time splitting. 
    1213 This is because the major contribution to bottom friction is likely to come from the barotropic component which 
    1214 uses the unrestricted value of the coefficient. 
    1215 However, if the limiting is thought to be having a major effect 
    1216 (a more likely prospect in coastal and shelf seas applications) then 
    1217 the fully implicit form of the bottom friction should be used (see \autoref{subsec:ZDF_bfr_imp}) 
    1218 which can be selected by setting \np{ln\_bfrimp} $=$ \forcode{.true.}. 
    1219  
    1220 Otherwise, the implicit formulation takes the form: 
    1221 \[ 
    1222   % \label{eq:zdfbfr_implicitts} 
    1223   \bar{U}^{t+ \rdt} = \; \left [ \bar{U}^{t-\rdt}\; + 2 \rdt\;RHS \right ] / \left [ 1 - 2 \rdt \;c_b^{u} / H_e \right ] 
    1224 \] 
    1225 where $\bar U$ is the barotropic velocity, $H_e$ is the full depth (including sea surface height),  
    1226 $c_b^u$ is the bottom friction coefficient as calculated in \rou{zdf\_bfr} and 
    1227 $RHS$ represents all the components to the vertically integrated momentum trend except for 
    1228 that due to bottom friction. 
    1229  
    1230 % ================================================================ 
    1231 % Tidal Mixing 
    1232 % ================================================================ 
    1233 \section[Tidal mixing (\texttt{\textbf{key\_zdftmx}})] 
    1234 {Tidal mixing (\protect\key{zdftmx})} 
    1235 \label{sec:ZDF_tmx} 
    1236  
    1237 %--------------------------------------------namzdf_tmx-------------------------------------------------- 
    1238 % 
    1239 %\nlst{namzdf_tmx} 
    1240 %-------------------------------------------------------------------------------------------------------------- 
    1241  
    1242  
    1243 % ------------------------------------------------------------------------------------------------------------- 
    1244 %        Bottom intensified tidal mixing  
    1245 % ------------------------------------------------------------------------------------------------------------- 
    1246 \subsection{Bottom intensified tidal mixing} 
    1247 \label{subsec:ZDF_tmx_bottom} 
    1248  
    1249 Options are defined through the  \ngn{namzdf\_tmx} namelist variables. 
    1250 The parameterization of tidal mixing follows the general formulation for the vertical eddy diffusivity proposed by 
    1251 \citet{st-laurent.simmons.ea_GRL02} and first introduced in an OGCM by \citep{simmons.jayne.ea_OM04}.  
    1252 In this formulation an additional vertical diffusivity resulting from internal tide breaking, 
    1253 $A^{vT}_{tides}$ is expressed as a function of $E(x,y)$, 
    1254 the energy transfer from barotropic tides to baroclinic tides: 
    1255 \begin{equation} 
    1256   \label{eq:Ktides} 
    1257   A^{vT}_{tides} =  q \,\Gamma \,\frac{ E(x,y) \, F(z) }{ \rho \, N^2 } 
    1258 \end{equation} 
    1259 where $\Gamma$ is the mixing efficiency, $N$ the Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}), 
    1260 $\rho$ the density, $q$ the tidal dissipation efficiency, and $F(z)$ the vertical structure function.  
    1261  
    1262 The mixing efficiency of turbulence is set by $\Gamma$ (\np{rn\_me} namelist parameter) and 
    1263 is usually taken to be the canonical value of $\Gamma = 0.2$ (Osborn 1980).  
    1264 The tidal dissipation efficiency is given by the parameter $q$ (\np{rn\_tfe} namelist parameter) 
    1265 represents the part of the internal wave energy flux $E(x, y)$ that is dissipated locally, 
    1266 with the remaining $1-q$ radiating away as low mode internal waves and 
    1267 contributing to the background internal wave field. 
    1268 A value of $q=1/3$ is typically used \citet{st-laurent.simmons.ea_GRL02}. 
    1269 The vertical structure function $F(z)$ models the distribution of the turbulent mixing in the vertical. 
    1270 It is implemented as a simple exponential decaying upward away from the bottom, 
    1271 with a vertical scale of $h_o$ (\np{rn\_htmx} namelist parameter, 
    1272 with a typical value of $500\,m$) \citep{st-laurent.nash_DSR04},  
    1273 \[ 
    1274   % \label{eq:Fz} 
    1275   F(i,j,k) = \frac{ e^{ -\frac{H+z}{h_o} } }{ h_o \left( 1- e^{ -\frac{H}{h_o} } \right) } 
    1276 \] 
    1277 and is normalized so that vertical integral over the water column is unity.  
    1278  
    1279 The associated vertical viscosity is calculated from the vertical diffusivity assuming a Prandtl number of 1, 
    1280 \ie $A^{vm}_{tides}=A^{vT}_{tides}$. 
    1281 In the limit of $N \rightarrow 0$ (or becoming negative), the vertical diffusivity is capped at $300\,cm^2/s$ and 
    1282 impose a lower limit on $N^2$ of \np{rn\_n2min} usually set to $10^{-8} s^{-2}$. 
    1283 These bounds are usually rarely encountered. 
    1284  
    1285 The internal wave energy map, $E(x, y)$ in \autoref{eq:Ktides}, is derived from a barotropic model of 
    1286 the tides utilizing a parameterization of the conversion of barotropic tidal energy into internal waves. 
    1287 The essential goal of the parameterization is to represent the momentum exchange between the barotropic tides and 
    1288 the unrepresented internal waves induced by the tidal flow over rough topography in a stratified ocean. 
    1289 In the current version of \NEMO, the map is built from the output of 
    1290 the barotropic global ocean tide model MOG2D-G \citep{carrere.lyard_GRL03}. 
    1291 This model provides the dissipation associated with internal wave energy for the M2 and K1 tides component 
    1292 (\autoref{fig:ZDF_M2_K1_tmx}). 
    1293 The S2 dissipation is simply approximated as being $1/4$ of the M2 one. 
    1294 The internal wave energy is thus : $E(x, y) = 1.25 E_{M2} + E_{K1}$. 
    1295 Its global mean value is $1.1$ TW, 
    1296 in agreement with independent estimates \citep{egbert.ray_N00, egbert.ray_JGR01}.  
    1297  
    1298 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1299 \begin{figure}[!t] 
    1300   \begin{center} 
    1301     \includegraphics[width=\textwidth]{Fig_ZDF_M2_K1_tmx} 
    1302     \caption{ 
    1303       \protect\label{fig:ZDF_M2_K1_tmx} 
    1304       (a) M2 and (b) K1 internal wave drag energy from \citet{carrere.lyard_GRL03} ($W/m^2$). 
    1305     } 
    1306   \end{center} 
    1307 \end{figure} 
    1308 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>  
    1309   
    1310 % ------------------------------------------------------------------------------------------------------------- 
    1311 %        Indonesian area specific treatment  
    1312 % ------------------------------------------------------------------------------------------------------------- 
    1313 \subsection[Indonesian area specific treatment (\texttt{ln\_zdftmx\_itf})] 
    1314 {Indonesian area specific treatment (\protect\np{ln\_zdftmx\_itf})} 
    1315 \label{subsec:ZDF_tmx_itf} 
    1316  
    1317 When the Indonesian Through Flow (ITF) area is included in the model domain, 
    1318 a specific treatment of tidal induced mixing in this area can be used. 
    1319 It is activated through the namelist logical \np{ln\_tmx\_itf}, and the user must provide an input NetCDF file, 
    1320 \ifile{mask\_itf}, which contains a mask array defining the ITF area where the specific treatment is applied. 
    1321  
    1322 When \np{ln\_tmx\_itf}\forcode{ = .true.}, the two key parameters $q$ and $F(z)$ are adjusted following 
    1323 the parameterisation developed by \citet{koch-larrouy.madec.ea_GRL07}: 
    1324  
    1325 First, the Indonesian archipelago is a complex geographic region with a series of 
    1326 large, deep, semi-enclosed basins connected via numerous narrow straits. 
    1327 Once generated, internal tides remain confined within this semi-enclosed area and hardly radiate away. 
    1328 Therefore all the internal tides energy is consumed within this area. 
    1329 So it is assumed that $q = 1$, \ie all the energy generated is available for mixing. 
    1330 Note that for test purposed, the ITF tidal dissipation efficiency is a namelist parameter (\np{rn\_tfe\_itf}). 
    1331 A value of $1$ or close to is this recommended for this parameter. 
    1332  
    1333 Second, the vertical structure function, $F(z)$, is no more associated with a bottom intensification of the mixing, 
    1334 but with a maximum of energy available within the thermocline. 
    1335 \citet{koch-larrouy.madec.ea_GRL07} have suggested that the vertical distribution of 
    1336 the energy dissipation proportional to $N^2$ below the core of the thermocline and to $N$ above.  
    1337 The resulting $F(z)$ is: 
    1338 \[ 
    1339   % \label{eq:Fz_itf} 
    1340   F(i,j,k) \sim     \left\{ 
    1341     \begin{aligned} 
    1342       \frac{q\,\Gamma E(i,j) } {\rho N \, \int N     dz}    \qquad \text{when $\partial_z N < 0$} \\ 
    1343       \frac{q\,\Gamma E(i,j) } {\rho     \, \int N^2 dz}    \qquad \text{when $\partial_z N > 0$} 
    1344     \end{aligned} 
    1345   \right. 
    1346 \] 
    1347  
    1348 Averaged over the ITF area, the resulting tidal mixing coefficient is $1.5\,cm^2/s$,  
    1349 which agrees with the independent estimates inferred from observations. 
    1350 Introduced in a regional OGCM, the parameterization improves the water mass characteristics in 
    1351 the different Indonesian seas, suggesting that the horizontal and vertical distributions of 
    1352 the mixing are adequately prescribed \citep{koch-larrouy.madec.ea_GRL07, koch-larrouy.madec.ea_OD08*a, koch-larrouy.madec.ea_OD08*b}. 
    1353 Note also that such a parameterisation has a significant impact on the behaviour of 
    1354 global coupled GCMs \citep{koch-larrouy.lengaigne.ea_CD10}. 
    1355  
    1356 % ================================================================ 
    1357 % Internal wave-driven mixing 
    1358 % ================================================================ 
    1359 \section[Internal wave-driven mixing (\texttt{\textbf{key\_zdftmx\_new}})] 
    1360 {Internal wave-driven mixing (\protect\key{zdftmx\_new})} 
    1361 \label{sec:ZDF_tmx_new} 
    1362  
    1363 %--------------------------------------------namzdf_tmx_new------------------------------------------ 
    1364 % 
    1365 %\nlst{namzdf_tmx_new} 
    1366 %-------------------------------------------------------------------------------------------------------------- 
     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} 
    13671338 
    13681339The parameterization of mixing induced by breaking internal waves is a generalization of 
    13691340the approach originally proposed by \citet{st-laurent.simmons.ea_GRL02}. 
    13701341A three-dimensional field of internal wave energy dissipation $\epsilon(x,y,z)$ is first constructed, 
    1371 and the resulting diffusivity is obtained as  
    1372 \[ 
    1373   % \label{eq:Kwave} 
     1342and the resulting diffusivity is obtained as 
     1343\[ 
     1344  % \label{eq:ZDF_Kwave} 
    13741345  A^{vT}_{wave} =  R_f \,\frac{ \epsilon }{ \rho \, N^2 } 
    13751346\] 
    13761347where $R_f$ is the mixing efficiency and $\epsilon$ is a specified three dimensional distribution of 
    13771348the energy available for mixing. 
    1378 If the \np{ln\_mevar} namelist parameter is set to false, the mixing efficiency is taken as constant and 
     1349If the \np{ln_mevar}{ln\_mevar} namelist parameter is set to \forcode{.false.}, the mixing efficiency is taken as constant and 
    13791350equal to 1/6 \citep{osborn_JPO80}. 
    13801351In the opposite (recommended) case, $R_f$ is instead a function of 
     
    13851356the mixing efficiency is constant. 
    13861357 
    1387 In addition to the mixing efficiency, the ratio of salt to heat diffusivities can chosen to vary  
    1388 as a function of $Re_b$ by setting the \np{ln\_tsdiff} parameter to true, a recommended choice.  
     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. 
    13891360This parameterization of differential mixing, due to \cite{jackson.rehmann_JPO14}, 
    13901361is implemented as in \cite{de-lavergne.madec.ea_JPO16}. 
     
    13921363The three-dimensional distribution of the energy available for mixing, $\epsilon(i,j,k)$, 
    13931364is constructed from three static maps of column-integrated internal wave energy dissipation, 
    1394 $E_{cri}(i,j)$, $E_{pyc}(i,j)$, and $E_{bot}(i,j)$, combined to three corresponding vertical structures 
    1395 (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 
    13961367\begin{align*} 
    13971368  F_{cri}(i,j,k) &\propto e^{-h_{ab} / h_{cri} }\\ 
    1398   F_{pyc}(i,j,k) &\propto N^{n\_p}\\ 
     1369  F_{pyc}(i,j,k) &\propto N^{n_p}\\ 
    13991370  F_{bot}(i,j,k) &\propto N^2 \, e^{- h_{wkb} / h_{bot} } 
    1400 \end{align*}  
     1371\end{align*} 
    14011372In the above formula, $h_{ab}$ denotes the height above bottom, 
    14021373$h_{wkb}$ denotes the WKB-stretched height above bottom, defined by 
     
    14041375  h_{wkb} = H \, \frac{ \int_{-H}^{z} N \, dz' } { \int_{-H}^{\eta} N \, dz'  } \; , 
    14051376\] 
    1406 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) 
    14071378controls the stratification-dependence of the pycnocline-intensified dissipation. 
    1408 It can take values of 1 (recommended) or 2. 
     1379It can take values of $1$ (recommended) or $2$. 
    14091380Finally, the vertical structures $F_{cri}$ and $F_{bot}$ require the specification of 
    14101381the decay scales $h_{cri}(i,j)$ and $h_{bot}(i,j)$, which are defined by two additional input maps. 
     
    14121383$h_{bot}$ is a function of the energy flux $E_{bot}$, the characteristic horizontal scale of 
    14131384the abyssal hill topography \citep{goff_JGR10} and the latitude. 
    1414  
    1415 % ================================================================ 
    1416  
    1417 \biblio 
    1418  
    1419 \pindex 
     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}} 
    14201646 
    14211647\end{document} 
  • NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_conservation.tex

    r11151 r12149  
    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. 
     
    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. 
     
    4156\citep{Marti1992?, Levy1996?, Levy1998?}. 
    4257 
    43 % ------------------------------------------------------------------------------------------------------------- 
    44 %       Conservation Properties on Ocean Dynamics 
    45 % ------------------------------------------------------------------------------------------------------------- 
     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 
    6780        \;{\mathrm {\mathbf k}}\times {\textbf {U}}_h } \right)\;dv} =0 
     
    6982 
    7083\[ 
    71   % \label{eq:vor_enstrophy} 
     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} 
     199  % \label{eq:CONS_dynldf_dyn} 
    191200  \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 
     
    195204 
    196205\[ 
    197   % \label{eq:dynldf_div} 
     206  % \label{eq:CONS_dynldf_div} 
    198207  \int\limits_D {\nabla _h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi } 
    199208        \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} 
     
    202211 
    203212\[ 
    204   % \label{eq:dynldf_curl} 
     213  % \label{eq:CONS_dynldf_curl} 
    205214  \int_D {{\mathrm {\mathbf U}}_h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi } 
    206215        \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} 
     
    209218 
    210219\[ 
    211   % \label{eq:dynldf_curl2} 
     220  % \label{eq:CONS_dynldf_curl2} 
    212221  \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 
     
    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( 
    222231          {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} \leqslant 0 
    223232\] 
    224  
    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} 
     268  % \label{eq:CONS_dynzdf_vor} 
    261269  \begin{aligned} 
    262270    & \int_D {\frac{1}{e_3 }{\mathrm {\mathbf k}}\cdot \nabla \times \left( {\frac{1}{e_3 
     
    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 
     
    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/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_misc.tex

    r11179 r12149  
    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=\textwidth]{Fig_Gibraltar} 
    66     \includegraphics[width=\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=\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 (\textit{closea.F90})] 
    105 {Closed seas (\protect\mdl{closea})} 
     124 
     125%% ================================================================================================= 
     126\section[Closed seas (\textit{closea.F90})]{Closed seas (\protect\mdl{closea})} 
    106127\label{sec:MISC_closea} 
    107128 
     
    117138to zero and put the residual flux into the ocean. 
    118139 
    119 Prior to NEMO 4 the locations of inland seas and lakes was set via 
    120 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 
    121142the inland seas and lakes are defined using mask fields in the 
    122143domain configuration file. The options are as follows. 
    123144 
    124145\begin{enumerate} 
    125 \item{{\bfseries No ``closea\_mask'' field is included in domain configuration 
     146\item {{\bfseries No ``closea\_mask'' field is included in domain configuration 
    126147  file.} In this case the closea module does nothing.} 
    127148 
    128 \item{{\bfseries A field called closea\_mask is included in the domain 
     149\item {{\bfseries A field called closea\_mask is included in the domain 
    129150configuration file and ln\_closea=.false. in namelist namcfg.} In this 
    130151case the inland seas defined by the closea\_mask field are filled in 
     
    132153closea\_mask that is nonzero is set to be a land point.} 
    133154 
    134 \item{{\bfseries A field called closea\_mask is included in the domain 
     155\item {{\bfseries A field called closea\_mask is included in the domain 
    135156configuration file and ln\_closea=.true. in namelist namcfg.} Each 
    136157inland sea or group of inland seas is set to a positive integer value 
    137 in the closea\_mask field (see Figure \ref{fig:closea_mask_example} 
     158in the closea\_mask field (see \autoref{fig:MISC_closea_mask_example} 
    138159for an example). The net surface flux over each inland sea or group of 
    139160inland seas is set to zero each timestep and the residual flux is 
     
    141162closea\_mask is zero).} 
    142163 
    143 \item{{\bfseries Fields called closea\_mask and closea\_mask\_rnf are 
     164\item {{\bfseries Fields called closea\_mask and closea\_mask\_rnf are 
    144165included in the domain configuration file and ln\_closea=.true. in 
    145166namelist namcfg.} This option works as for option 3, except that if 
     
    150171by the closea\_mask\_rnf field. Each mapping is defined by a positive 
    151172integer value for the inland sea(s) and the corresponding runoff 
    152 points. An example is given in Figure 
    153 \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 
    154175particular inland sea then the residual is spread over the global 
    155176ocean.} 
    156177 
    157 \item{{\bfseries Fields called closea\_mask and closea\_mask\_emp are 
     178\item {{\bfseries Fields called closea\_mask and closea\_mask\_emp are 
    158179included in the domain configuration file and ln\_closea=.true. in 
    159180namelist namcfg.} This option works the same as option 4 except that 
     
    165186 
    166187There is a python routine to create the closea\_mask fields and append 
    167 them to the domain configuration file in the utils/tools/DOMAINcfg directory.  
    168  
    169 % ================================================================ 
    170 % Sub-Domain Functionality  
    171 % ================================================================ 
     188them to the domain configuration file in the utils/tools/DOMAINcfg directory. 
     189 
     190%% ================================================================================================= 
    172191\section{Sub-domain functionality} 
    173192\label{sec:MISC_zoom} 
    174193 
     194%% ================================================================================================= 
    175195\subsection{Simple subsetting of input files via NetCDF attributes} 
    176196 
    177 The extended grids for use with the under-shelf ice cavities will result in redundant rows around Antarctica if 
    178 the ice cavities are not active. 
    179 A simple mechanism for subsetting input files associated with the extended domains has been implemented to 
    180 avoid the need to maintain different sets of input fields for use with or without active ice cavities. 
    181 The existing 'zoom' options are overly complex for this task and marked for deletion anyway. 
    182 This alternative subsetting operates for the j-direction only and works by optionally looking for and 
    183 using a global file attribute (named: \np{open\_ocean\_jstart}) to determine the starting j-row for input. 
    184 The use of this option is best explained with an example: 
    185 consider an ORCA1 configuration using the extended grid bathymetry and coordinate files: 
    186 \vspace{-10pt} 
    187 \ifile{eORCA1\_bathymetry\_v2} 
    188 \ifile{eORCA1\_coordinates} 
    189 \noindent These files define a horizontal domain of 362x332. 
    190 Assuming the first row with open ocean wet points in the non-isf bathymetry for this set is row 42 
    191 (\fortran indexing) then the formally correct setting for \np{open\_ocean\_jstart} is 41. 
    192 Using this value as the first row to be read will result in a 362x292 domain which is the same size as 
    193 the original ORCA1 domain. 
    194 Thus the extended coordinates and bathymetry files can be used with all the original input files for ORCA1 if 
    195 the ice cavities are not active (\np{ln\_isfcav = .false.}). 
    196 Full instructions for achieving this are: 
    197  
    198 \noindent Add the new attribute to any input files requiring a j-row offset, i.e: 
    199 \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: 
    200218\begin{cmds} 
    201 ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_coordinates.nc  
    202 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 
    203220\end{cmds} 
    204   
    205 \noindent Add the logical switch to \ngn{namcfg} in the configuration namelist and set true: 
    206 %--------------------------------------------namcfg-------------------------------------------------------- 
    207  
    208 \nlst{namcfg} 
    209 %-------------------------------------------------------------------------------------------------------------- 
    210  
    211 \noindent Note the j-size of the global domain is the (extended j-size minus \np{open\_ocean\_jstart} + 1 ) and 
    212 this must match the size of all datasets other than bathymetry and coordinates currently. 
    213 However the option can be extended to any global, 2D and 3D, netcdf, input field by adding the: 
    214 \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 
    215243\begin{forlines} 
    216244lrowattr=ln_use_jattr 
    217245\end{forlines} 
    218 optional argument to the appropriate \np{iom\_get} call and the \np{open\_ocean\_jstart} attribute to 
    219 the corresponding input files. 
    220 It remains the users responsibility to set \np{jpjdta} and \np{jpjglo} values in 
    221 the \np{namelist\_cfg} file according to their needs. 
    222  
    223 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    224 \begin{figure}[!ht] 
    225   \begin{center} 
    226     \includegraphics[width=\textwidth]{Fig_LBC_zoom} 
    227     \caption{ 
    228       \protect\label{fig:LBC_zoom} 
    229       Position of a model domain compared to the data input domain when the zoom functionality is used. 
    230     } 
    231   \end{center} 
    232 \end{figure} 
    233 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    234  
    235  
    236 % ================================================================ 
    237 % Accuracy and Reproducibility 
    238 % ================================================================ 
    239 \section[Accuracy and reproducibility (\textit{lib\_fortran.F90})] 
    240 {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})} 
    241257\label{sec:MISC_fortran} 
    242258 
    243 \subsection[Issues with intrinsinc SIGN function (\texttt{\textbf{key\_nosignedzero}})] 
    244 {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})} 
    245261\label{subsec:MISC_sign} 
    246262 
    247 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. 
    248264For example, SIGN(-3.0,2.0) has the value 3.0. 
    249265The problematic case is when the second argument is zero, because, on platforms that support IEEE arithmetic, 
     
    257273and the processor is capable of distinguishing between positive and negative zero, 
    258274and B is negative real zero. 
    259 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. 
    260276This change may be especially sensitive for the ice model, 
    261277so we overwrite the intrinsinc function with our own function simply performing :   \\ 
     
    267283some computers/compilers. 
    268284 
    269  
     285%% ================================================================================================= 
    270286\subsection{MPP reproducibility} 
    271287\label{subsec:MISC_glosum} 
    272288 
    273289The numerical reproducibility of simulations on distributed memory parallel computers is a critical issue. 
    274 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, 
    275291and their propagation and accumulation cause uncertainty in final simulation reproducibility on 
    276292different numbers of processors. 
    277293To avoid so, based on \citet{he.ding_JS01} review of different technics, 
    278294we use a so called self-compensated summation method. 
    279 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. 
    280296 
    281297Suppose we need to calculate $b = a_1 + a_2 + a_3$. 
     
    295311The self-compensated summation method should be used in all summation in i- and/or j-direction. 
    296312See \mdl{closea} module for an example. 
    297 Note also that this implementation may be sensitive to the optimization level.  
    298  
     313Note also that this implementation may be sensitive to the optimization level. 
     314 
     315%% ================================================================================================= 
    299316\subsection{MPP scalability} 
    300317\label{subsec:MISC_mppsca} 
     
    316333be set at all the locations actually required by each individual for the fold operation. 
    317334This alternative method should give identical results to the default \textsc{ALLGATHER} method and 
    318 is recommended for large values of \np{jpni}. 
    319 The new method is activated by setting \np{ln\_nnogather} to be true (\ngn{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}). 
    320337The reproducibility of results using the two methods should be confirmed for each new, 
    321338non-reference configuration. 
    322339 
    323 % ================================================================ 
    324 % Model optimisation, Control Print and Benchmark 
    325 % ================================================================ 
     340%% ================================================================================================= 
    326341\section{Model optimisation, control print and benchmark} 
    327342\label{sec:MISC_opt} 
    328 %--------------------------------------------namctl------------------------------------------------------- 
    329  
    330 \nlst{namctl}  
    331 %-------------------------------------------------------------------------------------------------------------- 
    332  
    333 Options are defined through the  \ngn{namctl} namelist variables. 
    334  
     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%% ================================================================================================= 
    335353\subsection{Vector optimisation} 
    336354 
     
    338356This is very a very efficient way to increase the length of vector calculations and thus 
    339357to speed up the model on vector computers. 
    340   
     358 
    341359% Add here also one word on NPROMA technique that has been found useless, since compiler have made significant progress during the last decade. 
    342   
     360 
    343361% Add also one word on NEC specific optimisation (Novercheck option for example) 
    344   
     362 
     363%% ================================================================================================= 
    345364\subsection{Control print} 
    346365 
    347 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: 
    348367 
    349368\begin{enumerate} 
    350 \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 
    351370ZDF modules. 
    352371This option is very helpful when diagnosing the origin of an undesired change in model results. } 
    353372 
    354 \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 
    355374mono and multi processor runs.} 
    356375\end{enumerate} 
    357376 
    358377However, in recent versions it has also been used to force all processors to assume the 
    359 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 
    360379of files such as: ocean.output, layout.dat, etc.  All such files, beyond the the normal 
    361380reporting processor (narea == 1), are named with a \_XXXX extension to their name, where 
     
    363382such as run.stat (and its netCDF counterpart: run.stat.nc) and tracer.stat contain global 
    364383information and are only ever produced by the reporting master (narea == 1). For version 
    365 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 
    366385a new control structure which allows finer control over which files are produced. This 
    367386feature is still evolving but it does already allow the user to: select individually the 
     
    389408at a suitably long interval. For example: 
    390409 
    391 \begin{verbatim}      
     410\begin{verbatim} 
    392411       sn_cfctl%ptimincr  = 25 
    393412\end{verbatim} 
    394413 
    395 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 
    396415increment also applies to the time.step file which is otherwise updated every timestep. 
    397416 
    398 % ================================================================ 
    399 \biblio 
    400  
    401 \pindex 
     417\subinc{\input{../../global/epilogue}} 
    402418 
    403419\end{document} 
  • NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_model_basics.tex

    r11151 r12149  
    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[width=\textwidth]{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, 
     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, 
    265275using a split-explicit method \citep{killworth.webb.ea_JPO91, zhang.endoh_JGR92} or 
    266 the implicit scheme \citep{dukowicz.smith_JGR94} 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 % ------------------------------------------------------------------------------------------------------------- 
     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. 
     
    293298A solution consists of introducing an appropriate coordinate transformation that 
    294299shifts 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. 
     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{eiseman.stone_SR80} 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[width=\textwidth]{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.smith.ea_JPO03} or 
    580 OPA (mixture of $z$-coordinate in vicinity the surface and steep topography areas and $\sigma$-coordinate elsewhere) 
    581 \citep{madec.delecluse.ea_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}. 
     564\autoref{eq:MB_s}. 
    594565This 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.burchard.ea_OM10}, 
    600 since the coordinate system is adapted in the course of the simulation. 
     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 
     575the latter step implicitly embedding the vertical advection 
    604576\citep{hirt.amsden.ea_JCP74, chassignet.smith.ea_JPO03, white.adcroft.ea_JCP09}. 
    605577Here we follow the \citep{kasahara_MWR74} strategy: 
    606 a regridding step (an update of the vertical coordinate) followed by an eulerian step with 
     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[width=\textwidth]{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 
     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 
    746700      (become popular as the \zstar-coordinate \citep{adcroft.campin_OM04}). 
    747     } 
    748   \end{center} 
     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{levier.treguier.ea_rpt07} 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 
     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 
    807762(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{haney_JPO91} and \citet{beckmann.haidvogel_JPO93} 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{gerdes_JGR93*a,gerdes_JGR93*b,madec.delecluse.ea_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.delecluse.ea_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.madec.ea_OM90,madec.delecluse.ea_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 
     967Observations show that 
     968lateral mixing induced by mesoscale turbulence tends to be along isopycnal surfaces 
    1007969(or more precisely neutral surfaces \cite{mcdougall_JPO87}) 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. 
     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{gent.mcwilliams_JPO90} 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, 
    10421009\citet{gent.mcwilliams_JPO90} parameterisation, and various slightly diffusive advection schemes. 
    1043 For momentum, the main ones are: Laplacian and bilaplacian operators acting along geopotential surfaces, 
     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{cox_OM87}. 
    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 
     
    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 
    11641142a geographical coordinate system \citep{lengaigne.madec.ea_JGR03}. 
    11651143 
    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 
     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/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex

    r11179 r12149  
    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{levier.treguier.ea_rpt07} 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 (\textit{dynspg.F90})] 
    76 {Surface pressure gradient and sea surface heigth (\protect\mdl{dynspg})} 
    77 \label{sec:DYN_hpg_spg} 
    78 %-----------------------------------------nam_dynspg---------------------------------------------------- 
    79  
    80 %\nlst{nam_dynspg}  
    81 %------------------------------------------------------------------------------------------------------------ 
    82 Options are defined through the \ngn{nam\_dynspg} namelist variables. 
    83 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}). 
    8489The main distinction is between the fixed volume case (linear free surface or rigid lid) and 
    8590the variable volume case (nonlinear free surface, \key{vvl} is active). 
    86 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}), 
    8792the vertical scale factors $e_{3}$ are fixed in time, 
    88 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. 
    8994With both linear and nonlinear free surface, external gravity waves are allowed in the equations, 
    9095which imposes a very small time step when an explicit time stepping is used. 
    9196Two methods are proposed to allow a longer time step for the three-dimensional equations: 
    92 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?}), 
    9398and the split-explicit free surface described below. 
    9499The extra term introduced in the filtered method is calculated implicitly, 
    95100so that the update of the next velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}. 
    96101 
    97 %------------------------------------------------------------- 
    98102% Explicit 
    99 %------------------------------------------------------------- 
    100 \subsubsection[Explicit (\texttt{\textbf{key\_dynspg\_exp}})] 
    101 {Explicit (\protect\key{dynspg\_exp})} 
    102 \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} 
    103106 
    104107In the explicit free surface formulation, the model time step is chosen small enough to 
     
    106109The sea surface height is given by: 
    107110\begin{equation} 
    108   \label{eq:dynspg_ssh} 
     111  \label{eq:MBZ_dynspg_ssh} 
    109112  \frac{\partial \eta }{\partial t}\equiv \frac{\text{EMP}}{\rho_w }+\frac{1}{e_{1T} 
    110113    e_{2T} }\sum\limits_k {\left( {\delta_i \left[ {e_{2u} e_{3u} u} 
     
    116119and $\rho_w =1,000\,Kg.m^{-3}$ is the volumic mass of pure water. 
    117120The sea-surface height is evaluated using a leapfrog scheme in combination with an Asselin time filter, 
    118 (\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). 
    119122 
    120123The surface pressure gradient, also evaluated using a leap-frog scheme, is then simply given by: 
    121124\begin{equation} 
    122   \label{eq:dynspg_exp} 
     125  \label{eq:MBZ_dynspg_exp} 
    123126  \left\{ 
    124127    \begin{aligned} 
     
    127130    \end{aligned} 
    128131  \right. 
    129 \end{equation}  
     132\end{equation} 
    130133 
    131134Consistent with the linearization, a $\left. \rho \right|_{k=1} / \rho_o$ factor is omitted in 
    132 (\autoref{eq:dynspg_exp}).  
    133  
    134 %------------------------------------------------------------- 
     135(\autoref{eq:DYN_spg_exp}). 
     136 
    135137% Split-explicit time-stepping 
    136 %------------------------------------------------------------- 
    137 \subsubsection[Split-explicit time-stepping (\texttt{\textbf{key\_dynspg\_ts}})] 
    138 {Split-explicit time-stepping (\protect\key{dynspg\_ts})} 
    139 \label{subsec:DYN_spg_ts} 
    140 %--------------------------------------------namdom---------------------------------------------------- 
    141  
    142 \nlst{namdom}  
    143 %-------------------------------------------------------------------------------------------------------------- 
     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 
    144142The split-explicit free surface formulation used in OPA follows the one proposed by \citet{Griffies2004?}. 
    145143The general idea is to solve the free surface equation with a small time step, 
    146144while the three dimensional prognostic variables are solved with a longer time step that 
    147 is a multiple of \np{rdtbt} in the \ngn{namdom} namelist (Figure III.3).  
    148  
    149 %>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   > 
     145is a multiple of \np{rdtbt}{rdtbt} in the \nam{dom}{dom} namelist (Figure III.3). 
     146 
    150147\begin{figure}[!t] 
    151   \begin{center} 
    152     \includegraphics[width=\textwidth]{Fig_DYN_dynspg_ts} 
    153     \caption{ 
    154       \protect\label{fig:DYN_dynspg_ts} 
    155       Schematic of the split-explicit time stepping scheme for the barotropic and baroclinic modes, 
    156       after \citet{Griffies2004?}. 
    157       Time increases to the right. 
    158       Baroclinic time steps are denoted by $t-\Delta t$, $t, t+\Delta t$, and $t+2\Delta t$. 
    159       The curved line represents a leap-frog time step, 
    160       and the smaller barotropic time steps $N \Delta t=2\Delta t$ are denoted by the zig-zag line. 
    161       The vertically integrated forcing \textbf{M}(t) computed at 
    162       baroclinic time step t represents the interaction between the barotropic and baroclinic motions. 
    163       While keeping the total depth, tracer, and freshwater forcing fields fixed, 
    164       a leap-frog integration carries the surface height and vertically integrated velocity from 
    165       t to $t+2 \Delta t$ using N barotropic time steps of length $\Delta t$. 
    166       Time averaging the barotropic fields over the N+1 time steps (endpoints included) 
    167       centers the vertically integrated velocity at the baroclinic timestep $t+\Delta t$. 
    168       A baroclinic leap-frog time step carries the surface height to $t+\Delta t$ using the convergence of 
    169       the time averaged vertically integrated velocity taken from baroclinic time step t. 
    170     } 
    171   \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} 
    172169\end{figure} 
    173 %>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   > 
    174170 
    175171The split-explicit formulation has a damping effect on external gravity waves, 
    176172which is weaker than the filtered free surface but still significant as shown by \citet{levier.treguier.ea_rpt07} in 
    177 the case of an analytical barotropic Kelvin wave.  
     173the case of an analytical barotropic Kelvin wave. 
    178174 
    179175%from griffies book: .....   copy past ! 
     
    186182We have 
    187183\[ 
    188   % \label{eq:DYN_spg_ts_eta} 
     184  % \label{eq:MBZ_dyn_spg_ts_eta} 
    189185  \eta^{(b)}(\tau,t_{n+1}) - \eta^{(b)}(\tau,t_{n+1}) (\tau,t_{n-1}) 
    190   = 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] 
    191187\] 
    192188\begin{multline*} 
    193   % \label{eq:DYN_spg_ts_u} 
     189  % \label{eq:MBZ_dyn_spg_ts_u} 
    194190  \textbf{U}^{(b)}(\tau,t_{n+1}) - \textbf{U}^{(b)}(\tau,t_{n-1})  \\ 
    195191  = 2\Delta t \left[ - f \textbf{k} \times \textbf{U}^{(b)}(\tau,t_{n}) 
     
    205201the freshwater flux $\text{EMP}_w(\tau)$, and total depth of the ocean $H(\tau)$ are held for 
    206202the duration of the barotropic time stepping over a single cycle. 
    207 This is also the time that sets the barotropic time steps via  
    208 \[ 
    209   % \label{eq:DYN_spg_ts_t} 
    210   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 
    211207\] 
    212208with $n$ an integer. 
    213 The density scaled surface pressure is evaluated via  
    214 \[ 
    215   % \label{eq:DYN_spg_ts_ps} 
     209The density scaled surface pressure is evaluated via 
     210\[ 
     211  % \label{eq:MBZ_dyn_spg_ts_ps} 
    216212  p_s^{(b)}(\tau,t_{n}) = 
    217213  \begin{cases} 
     
    220216  \end{cases} 
    221217\] 
    222 To get started, we assume the following initial conditions  
    223 \[ 
    224   % \label{eq:DYN_spg_ts_eta} 
     218To get started, we assume the following initial conditions 
     219\[ 
     220  % \label{eq:MBZ_dyn_spg_ts_eta} 
    225221  \begin{split} 
    226222    \eta^{(b)}(\tau,t_{n=0}) &= \overline{\eta^{(b)}(\tau)} \\ 
     
    228224  \end{split} 
    229225\] 
    230 with  
    231 \[ 
    232   % \label{eq:DYN_spg_ts_etaF} 
     226with 
     227\[ 
     228  % \label{eq:MBZ_dyn_spg_ts_etaF} 
    233229  \overline{\eta^{(b)}(\tau)} = \frac{1}{N+1} \sum\limits_{n=0}^N \eta^{(b)}(\tau-\Delta t,t_{n}) 
    234230\] 
     
    236232Likewise, 
    237233\[ 
    238   % \label{eq:DYN_spg_ts_u} 
     234  % \label{eq:MBZ_dyn_spg_ts_u} 
    239235  \textbf{U}^{(b)}(\tau,t_{n=0}) = \overline{\textbf{U}^{(b)}(\tau)} \\ \\ 
    240236  \textbf{U}(\tau,t_{n=1}) = \textbf{U}^{(b)}(\tau,t_{n=0}) + \Delta t \ \text{RHS}_{n=0} 
    241237\] 
    242 with  
    243 \[ 
    244   % \label{eq:DYN_spg_ts_u} 
     238with 
     239\[ 
     240  % \label{eq:MBZ_dyn_spg_ts_u} 
    245241  \overline{\textbf{U}^{(b)}(\tau)} = \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau-\Delta t,t_{n}) 
    246242\] 
    247243the time averaged vertically integrated transport. 
    248 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. 
    249245 
    250246Upon reaching $t_{n=N} = \tau + 2\Delta \tau$ , the vertically integrated velocity is time averaged to 
    251 produce the updated vertically integrated velocity at baroclinic time $\tau + \Delta \tau$  
    252 \[ 
    253   % \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} 
    254250  \textbf{U}(\tau+\Delta t) = \overline{\textbf{U}^{(b)}(\tau+\Delta t)} 
    255251  = \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau,t_{n}) 
    256252\] 
    257253The surface height on the new baroclinic time step is then determined via 
    258 a baroclinic leap-frog using the following form  
     254a baroclinic leap-frog using the following form 
    259255\begin{equation} 
    260   \label{eq:DYN_spg_ts_ssh} 
     256  \label{eq:MBZ_dyn_spg_ts_ssh} 
    261257  \eta(\tau+\Delta) - \eta^{F}(\tau-\Delta) = 2\Delta t \ \left[ - \nabla \cdot \textbf{U}(\tau) + \text{EMP}_w \right] 
    262258\end{equation} 
     
    264260The use of this "big-leap-frog" scheme for the surface height ensures compatibility between 
    265261the mass/volume budgets and the tracer budgets. 
    266 More discussion of this point is provided in Chapter 10 (see in particular Section 10.2).  
    267   
     262More discussion of this point is provided in Chapter 10 (see in particular Section 10.2). 
     263 
    268264In general, some form of time filter is needed to maintain integrity of the surface height field due to 
    269 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}. 
    270266We have tried various forms of such filtering, 
    271267with the following method discussed in Griffies et al. (2001) chosen due to its stability and 
    272 reasonably good maintenance of tracer conservation properties (see ??)  
     268reasonably good maintenance of tracer conservation properties (see ??) 
    273269 
    274270\begin{equation} 
    275   \label{eq:DYN_spg_ts_sshf} 
     271  \label{eq:MBZ_dyn_spg_ts_sshf} 
    276272  \eta^{F}(\tau-\Delta) =  \overline{\eta^{(b)}(\tau)} 
    277273\end{equation} 
    278 Another approach tried was  
    279  
    280 \[ 
    281   % \label{eq:DYN_spg_ts_sshf2} 
     274Another approach tried was 
     275 
     276\[ 
     277  % \label{eq:MBZ_dyn_spg_ts_sshf2} 
    282278  \eta^{F}(\tau-\Delta) = \eta(\tau) 
    283279  + (\alpha/2) \left[\overline{\eta^{(b)}}(\tau+\Delta t) 
     
    288284This isolation allows for an easy check that tracer conservation is exact when eliminating tracer and 
    289285surface height time filtering (see ?? for more complete discussion). 
    290 However, in the general case with a non-zero $\alpha$, the filter \autoref{eq:DYN_spg_ts_sshf} was found to 
    291 be more conservative, and so is recommended.  
    292  
    293 %------------------------------------------------------------- 
    294 % Filtered formulation  
    295 %------------------------------------------------------------- 
    296 \subsubsection[Filtered formulation (\texttt{\textbf{key\_dynspg\_flt}})] 
    297 {Filtered formulation (\protect\key{dynspg\_flt})} 
    298 \label{subsec:DYN_spg_flt} 
     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} 
    299293 
    300294The filtered formulation follows the \citet{Roullet2000?} implementation. 
    301295The extra term introduced in the equations (see {\S}I.2.2) is solved implicitly. 
    302296The elliptic solvers available in the code are documented in \autoref{chap:MISC}. 
    303 The amplitude of the extra term is given by the namelist variable \np{rnu}. 
     297The amplitude of the extra term is given by the namelist variable \np{rnu}{rnu}. 
    304298The default value is 1, as recommended by \citet{Roullet2000?} 
    305299 
    306 \colorbox{red}{\np{rnu}\forcode{ = 1} to be suppressed from namelist !} 
    307  
    308 %------------------------------------------------------------- 
    309 % Non-linear free surface formulation  
    310 %------------------------------------------------------------- 
    311 \subsection[Non-linear free surface formulation (\texttt{\textbf{key\_vvl}})] 
    312 {Non-linear free surface formulation (\protect\key{vvl})} 
    313 \label{subsec:DYN_spg_vvl} 
     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} 
    314306 
    315307In the non-linear free surface formulation, the variations of volume are fully taken into account. 
    316 This option is presented in a report \citep{levier.treguier.ea_rpt07} available on the NEMO web site. 
     308This option is presented in a report \citep{levier.treguier.ea_rpt07} available on the \NEMO\ web site. 
    317309The three time-stepping methods (explicit, split-explicit and filtered) are the same as in 
    318 \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. 
    319311In particular, this means that in filtered case, the matrix to be inverted has to be recomputed at each time-step. 
    320312 
    321 \biblio 
    322  
    323 \pindex 
     313\subinc{\input{../../global/epilogue}} 
    324314 
    325315\end{document} 
  • NEMO/branches/2019/ENHANCE-03_closea/doc/latex/NEMO/subfiles/chap_time_domain.tex

    r11184 r12149  
    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 and 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 stepping depending on the physics with which it is associated. 
     56Each term of the RHS is evaluated at a specific time stepping depending on 
     57the physics with which it is associated. 
    4358 
    4459The 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 The time stepping itself is performed once at each time step where implicit vertical diffusion is computed, \ie in the \mdl{trazdf} and \mdl{dynzdf} modules. 
    56  
    57 % ------------------------------------------------------------------------------------------------------------- 
    58 %        Non-Diffusive Part---Leapfrog Scheme 
    59 % ------------------------------------------------------------------------------------------------------------- 
     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%% ================================================================================================= 
    6076\section{Non-diffusive part --- Leapfrog scheme} 
    61 \label{sec:STP_leap_frog} 
    62  
    63 The time stepping used for processes other than diffusion is the well-known leapfrog scheme 
    64 \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}. 
    6581This scheme is widely used for advection processes in low-viscosity fluids. 
    66 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. 
    6784It may be used for momentum and tracer advection, pressure gradient, and Coriolis terms, 
    6885but not for diffusion terms. 
    6986It is an efficient method that achieves second-order accuracy with 
    7087just one right hand side evaluation per time step. 
    71 Moreover, it does not artificially damp linear oscillatory motion nor does it produce instability by 
    72 amplifying the oscillations. 
     88Moreover, it does not artificially damp linear oscillatory motion 
     89nor does it produce instability by amplifying the oscillations. 
    7390These advantages are somewhat diminished by the large phase-speed error of the leapfrog scheme, 
    74 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. 
    7593However, the scheme allows the coexistence of a numerical and a physical mode due to 
    7694its leading third order dispersive error. 
    7795In other words a divergence of odd and even time steps may occur. 
    78 To prevent it, the leapfrog scheme is often used in association with a Robert-Asselin time filter 
    79 (hereafter the LF-RA scheme). 
    80 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}, 
    81100is a kind of laplacian diffusion in time that mixes odd and even time steps: 
    82101\begin{equation} 
    83   \label{eq:STP_asselin} 
     102  \label{eq:TD_asselin} 
    84103  x_F^t = x^t + \gamma \, \lt[ x_F^{t - \rdt} - 2 x^t + x^{t + \rdt} \rt] 
    85104\end{equation} 
    86105where the subscript $F$ denotes filtered values and $\gamma$ is the Asselin coefficient. 
    87 $\gamma$ is initialized as \np{rn\_atfp} (namelist parameter). 
    88 Its default value is \np{rn\_atfp}\forcode{ = 10.e-3} (see \autoref{sec:STP_mLF}), 
     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}), 
    89108causing only a weak dissipation of high frequency motions (\citep{farge-coulombier_phd87}). 
    90109The addition of a time filter degrades the accuracy of the calculation from second to first order. 
    91110However, the second order truncation error is proportional to $\gamma$, which is small compared to 1. 
    92111Therefore, the LF-RA is a quasi second order accurate scheme. 
    93 The LF-RA scheme is preferred to other time differencing schemes such as predictor corrector or trapezoidal schemes, 
    94 because the user has an explicit and simple control of the magnitude of the time diffusion of the scheme.  
    95 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 
    96116the momentum and tracer equations, LF-RA avoids implicit numerical diffusion: 
    97 diffusion is set explicitly by the user through the Robert-Asselin  
    98 filter parameter and the viscosity and diffusion coefficients. 
    99  
    100 % ------------------------------------------------------------------------------------------------------------- 
    101 %        Diffusive Part---Forward or Backward Scheme 
    102 % ------------------------------------------------------------------------------------------------------------- 
     117diffusion is set explicitly by the user through the Robert-Asselin filter parameter and 
     118the viscosity and diffusion coefficients. 
     119 
     120%% ================================================================================================= 
    103121\section{Diffusive part --- Forward or backward scheme} 
    104 \label{sec:STP_forward_imp} 
    105  
    106 The leapfrog differencing scheme is unsuitable for the representation of diffusion and damping processes. 
     122\label{sec:TD_forward_imp} 
     123 
     124The leapfrog differencing scheme is unsuitable for 
     125the representation of diffusion and damping processes. 
    107126For a tendency $D_x$, representing a diffusion term or a restoring term to a tracer climatology 
    108127(when present, see \autoref{sec:TRA_dmp}), a forward time differencing scheme is used : 
    109128\[ 
    110   %\label{eq:STP_euler} 
     129  %\label{eq:TD_euler} 
    111130  x^{t + \rdt} = x^{t - \rdt} + 2 \, \rdt \ D_x^{t - \rdt} 
    112131\] 
    113132 
    114133This is diffusive in time and conditionally stable. 
    115 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}: 
    116136\begin{equation} 
    117   \label{eq:STP_euler_stability} 
     137  \label{eq:TD_euler_stability} 
    118138  A^h < 
    119139  \begin{cases} 
     
    122142  \end{cases} 
    123143\end{equation} 
    124 where $e$ is the smallest grid size in the two horizontal directions and $A^h$ is the mixing coefficient. 
    125 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. 
    126147If it is not satisfied, even mildly, then the model soon becomes wildly unstable. 
    127 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. 
    128150 
    129151For the vertical diffusion terms, a forward time differencing scheme can be used, 
    130 but usually the numerical stability condition imposes a strong constraint on the time step. To overcome the stability constraint, a  
    131 backward (or implicit) time differencing scheme is used. This scheme is unconditionally stable but diffusive and can be written as follows: 
     152but usually the numerical stability condition imposes a strong constraint on the time step. 
     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: 
    132155\begin{equation} 
    133   \label{eq:STP_imp} 
     156  \label{eq:TD_imp} 
    134157  x^{t + \rdt} = x^{t - \rdt} + 2 \, \rdt \ \text{RHS}_x^{t + \rdt} 
    135158\end{equation} 
    136159 
    137 %%gm 
    138 %%gm   UPDATE the next paragraphs with time varying thickness ... 
    139 %%gm 
    140  
    141 This scheme is rather time consuming since it requires a matrix inversion. For example, the finite difference approximation of the temperature equation is: 
     160\cmtgm{UPDATE the next paragraphs with time varying thickness ...} 
     161 
     162This scheme is rather time consuming since it requires a matrix inversion. 
     163For example, the finite difference approximation of the temperature equation is: 
    142164\[ 
    143   % \label{eq:STP_imp_zdf} 
     165  % \label{eq:TD_imp_zdf} 
    144166  \frac{T(k)^{t + 1} - T(k)^{t - 1}}{2 \; \rdt} 
    145167  \equiv 
     
    147169\] 
    148170where RHS is the right hand side of the equation except for the vertical diffusion term. 
    149 We rewrite \autoref{eq:STP_imp} as: 
     171We rewrite \autoref{eq:TD_imp} as: 
    150172\begin{equation} 
    151   \label{eq:STP_imp_mat} 
     173  \label{eq:TD_imp_mat} 
    152174  -c(k + 1) \; T^{t + 1}(k + 1) + d(k) \; T^{t + 1}(k) - \; c(k) \; T^{t + 1}(k - 1) \equiv b(k) 
    153175\end{equation} 
    154 where  
    155 \begin{align*}  
    156   c(k) &= A_w^{vT} (k) \, / \, e_{3w} (k)     \\ 
    157   d(k) &= e_{3t}   (k)       \, / \, (2 \rdt) + c_k + c_{k + 1}    \\ 
    158   b(k) &= e_{3t}   (k) \; \lt( T^{t - 1}(k) \, / \, (2 \rdt) + \text{RHS} \rt) 
    159 \end{align*} 
    160  
    161 \autoref{eq:STP_imp_mat} is a linear system of equations with an associated matrix which is tridiagonal. 
    162 Moreover, 
    163 $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, 
    164187therefore a special adaptation of the Gauss elimination procedure is used to find the solution 
    165188(see for example \citet{richtmyer.morton_bk67}). 
    166189 
    167 % ------------------------------------------------------------------------------------------------------------- 
    168 %        Surface Pressure gradient 
    169 % ------------------------------------------------------------------------------------------------------------- 
     190%% ================================================================================================= 
    170191\section{Surface pressure gradient} 
    171 \label{sec:STP_spg_ts} 
    172  
    173 The leapfrog environment supports a centred in time computation of the surface pressure, \ie evaluated  
    174 at \textit{now} time step. This refers to as the explicit free surface case in the code (\np{ln\_dynspg\_exp}\forcode{ = .true.}).  
    175 This choice however imposes a strong constraint on the time step which should be small enough to resolve the propagation  
    176 of external gravity waves. As a matter of fact, one rather use in a realistic setup, a split-explicit free surface  
    177 (\np{ln\_dynspg\_ts}\forcode{ = .true.}) in which barotropic and baroclinic dynamical equations are solved separately with ad-hoc  
    178 time steps. The use of the time-splitting (in combination with non-linear free surface) imposes some constraints on the design of  
    179 the overall flowchart, in particular to ensure exact tracer conservation (see \autoref{fig:TimeStep_flowchart}). 
    180  
    181 Compared to the former use of the filtered free surface in \NEMO v3.6 (\citet{roullet.madec_JGR00}), the use of a split-explicit free surface is advantageous  
    182 on massively parallel computers. Indeed, no global computations are anymore required by the elliptic solver which saves a substantial amount of communication  
    183 time. Fast barotropic motions (such as tides) are also simulated with a better accuracy.  
    184  
    185 %\gmcomment{  
    186 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    187 \begin{figure}[!t] 
    188   \begin{center} 
    189     \includegraphics[width=\textwidth]{Fig_TimeStepping_flowchart_v4} 
    190     \caption{ 
    191       \protect\label{fig:TimeStep_flowchart} 
    192       Sketch of the leapfrog time stepping sequence in \NEMO with split-explicit free surface. The latter combined 
    193        with non-linear free surface requires the dynamical tendency being updated prior tracers tendency to ensure  
    194        conservation. Note the use of time integrated fluxes issued from the barotropic loop  in subsequent calculations  
    195        of tracer advection and in the continuity equation. Details about the time-splitting scheme can be found  
    196        in \autoref{subsec:DYN_spg_ts}. 
    197     } 
    198   \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} 
    199225\end{figure} 
    200 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    201226%} 
    202227 
    203 % ------------------------------------------------------------------------------------------------------------- 
    204 %        The Modified Leapfrog -- Asselin Filter scheme 
    205 % ------------------------------------------------------------------------------------------------------------- 
    206 \section{Modified Leapfrog -- Asselin filter scheme} 
    207 \label{sec:STP_mLF} 
    208  
    209 Significant changes have been introduced by \cite{leclair.madec_OM09} in the LF-RA scheme in order to 
    210 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. 
    211235The modifications affect both the forcing and filtering treatments in the LF-RA scheme. 
    212236 
    213 In a classical LF-RA environment, the forcing term is centred in time, 
    214 \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: 
    215239$x^t = x^t + 2 \rdt Q^t$ where $Q$ is the forcing applied to $x$, 
    216 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. 
    217242In the modified LF-RA environment, these two formulations have been replaced by: 
    218243\begin{gather} 
    219   \label{eq:STP_forcing} 
     244  \label{eq:TD_forcing} 
    220245  x^{t + \rdt} = x^{t - \rdt} + \rdt \lt( Q^{t - \rdt / 2} + Q^{t + \rdt / 2} \rt)  \\ 
    221   \label{eq:STP_RA} 
     246  \label{eq:TD_RA} 
    222247  x_F^t       = x^t + \gamma \, \lt( x_F^{t - \rdt} - 2 x^t + x^{t + \rdt} \rt) 
    223248                    - \gamma \, \rdt \, \lt( Q^{t + \rdt / 2} - Q^{t - \rdt / 2} \rt) 
    224249\end{gather} 
    225 The change in the forcing formulation given by \autoref{eq:STP_forcing} (see \autoref{fig:MLF_forcing}) 
    226 has a significant effect: 
    227 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}. 
    228254% forcing seen by the model.... 
    229255This property improves the LF-RA scheme in two aspects. 
    230256First, the LF-RA can now ensure the local and global conservation of tracers. 
    231257Indeed, time filtering is no longer required on the forcing part. 
    232 The influence of the Asselin filter on the forcing is explicitly removed by adding a new term in the filter 
    233 (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}). 
    234260Since the filtering of the forcing was the source of non-conservation in the classical LF-RA scheme, 
    235261the modified formulation becomes conservative \citep{leclair.madec_OM09}. 
    236 Second, the LF-RA becomes a truly quasi -second order scheme. 
    237 Indeed, \autoref{eq:STP_forcing} used in combination with a careful treatment of static instability 
    238 (\autoref{subsec:ZDF_evd}) and of the TKE physics (\autoref{subsec:ZDF_tke_ene})  
     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}) 
    239265(the two other main sources of time step divergence), 
    240266allows a reduction by two orders of magnitude of the Asselin filter parameter. 
     
    242268Note that the forcing is now provided at the middle of a time step: 
    243269$Q^{t + \rdt / 2}$ is the forcing applied over the $[t,t + \rdt]$ time interval. 
    244 This and the change in the time filter, \autoref{eq:STP_RA}, 
     270This and the change in the time filter, \autoref{eq:TD_RA}, 
    245271allows for an exact evaluation of the contribution due to the forcing term between any two time steps, 
    246272even if separated by only $\rdt$ since the time filter is no longer applied to the forcing term. 
    247273 
    248 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    249 \begin{figure}[!t] 
    250   \begin{center} 
    251     \includegraphics[width=\textwidth]{Fig_MLF_forcing} 
    252     \caption{ 
    253       \protect\label{fig:MLF_forcing} 
    254       Illustration of forcing integration methods. 
    255       (top) ''Traditional'' formulation: 
    256       the forcing is defined at the same time as the variable to which it is applied 
    257       (integer value of the time step index) and it is applied over a $2 \rdt$ period. 
    258       (bottom)  modified formulation: 
    259       the forcing is defined in the middle of the time (integer and a half value of the time step index) and 
    260       the mean of two successive forcing values ($n - 1 / 2$, $n + 1 / 2$) is applied over a $2 \rdt$ period. 
    261     } 
    262   \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} 
    263288\end{figure} 
    264 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    265  
    266 % ------------------------------------------------------------------------------------------------------------- 
    267 %        Start/Restart strategy 
    268 % ------------------------------------------------------------------------------------------------------------- 
     289 
     290%% ================================================================================================= 
    269291\section{Start/Restart strategy} 
    270 \label{sec:STP_rst} 
    271  
    272 %--------------------------------------------namrun------------------------------------------- 
    273 \nlst{namrun} 
    274 %-------------------------------------------------------------------------------------------------------------- 
    275  
    276 The first time step of this three level scheme when starting from initial conditions is a forward step 
    277 (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): 
    278302\[ 
    279   % \label{eq:DOM_euler} 
     303  % \label{eq:TD_DOM_euler} 
    280304  x^1 = x^0 + \rdt \ \text{RHS}^0 
    281305\] 
    282 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 
    283308setting all $x^0$ (\textit{before}) and $x^1$ (\textit{now}) fields equal at the first time step and 
    284 using half the value of a leapfrog time step ($2 \rdt$).  
     309using half the value of a leapfrog time step ($2 \rdt$). 
    285310 
    286311It is also possible to restart from a previous computation, by using a restart file. 
     
    289314running the model for $2N$ time steps in one go, 
    290315or by performing two consecutive experiments of $N$ steps with a restart. 
    291 This requires saving two time levels and many auxiliary data in the restart files in machine precision. 
     316This requires saving two time levels and many auxiliary data in 
     317the restart files in machine precision. 
    292318 
    293319Note that the time step $\rdt$, is also saved in the restart file. 
    294 When restarting, if the time step has been changed, or one of the prognostic variables at \textit{before} time step  
    295 is missing, an Euler time stepping scheme is imposed. A forward initial step can still be enforced by the user by setting  
    296 the namelist variable \np{nn\_euler}\forcode{=0}. Other options to control the time integration of the model  
    297 are defined through the  \ngn{namrun} namelist variables. 
    298 %%% 
    299 \gmcomment{ 
     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{ 
    300329add here how to force the restart to contain only one time step for operational purposes 
    301330 
    302331add also the idea of writing several restart for seasonal forecast : how is it done ? 
    303332 
    304 verify that all namelist pararmeters are truly described  
     333verify that all namelist parameters are truly described 
    305334 
    306335a word on the check of restart  ..... 
    307336} 
    308 %%% 
    309  
    310 \gmcomment{       % add a subsection here   
    311  
    312 %------------------------------------------------------------------------------------------------------------- 
    313 %        Time Domain 
    314 % ------------------------------------------------------------------------------------------------------------- 
     337 
     338\cmtgm{       % add a subsection here 
     339 
     340%% ================================================================================================= 
    315341\subsection{Time domain} 
    316 \label{subsec:STP_time} 
    317 %--------------------------------------------namrun------------------------------------------- 
    318  
    319 \nlst{namdom}          
    320 %-------------------------------------------------------------------------------------------------------------- 
    321  
    322 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. 
    323345 \colorbox{yellow}{add here a few word on nit000 and nitend} 
    324346 
    325347 \colorbox{yellow}{Write documentation on the calendar and the key variable adatrj} 
    326348 
    327 add a description of daymod, and the model calandar (leap-year and co) 
    328  
    329 }        %% end add 
    330  
    331  
    332  
    333 %% 
    334 \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 
    335354 
    336355Implicit time stepping in case of variable volume thickness. 
     
    381400\end{flalign*} 
    382401 
    383 %% 
    384402} 
    385403 
    386 \biblio 
    387  
    388 \pindex 
     404\subinc{\input{../../global/epilogue}} 
    389405 
    390406\end{document} 
Note: See TracChangeset for help on using the changeset viewer.