Ignore:
Timestamp:
2019-10-12T16:08:18+02:00 (19 months ago)
Author:
francesca
Message:

Update branch to integrate the development starting from the current v4.01 ready trunk

Location:
NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc
Files:
29 deleted
72 edited
41 copied

Legend:

Unmodified
Added
Removed
  • NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc

    • Property svn:externals set to
      ^/utils/badges badges
      ^/utils/logos logos
  • NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex

    • Property svn:ignore deleted
  • NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/.svnignore

    r11187 r11692  
    88*.ilg 
    99*.ind 
    10 *.lof 
    11 *.log 
    12 *.lot 
     10*.lo* 
    1311*.maf 
    1412*.mtc* 
     
    1614*.pdf 
    1715*.toc 
     16*.xdv 
    1817_minted-* 
  • NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO

    • Property svn:externals set to
      ^/utils/figures/NEMO figures
  • NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/build

    • Property svn:ignore
      •  

        old new  
        1414*.pdf 
        1515*.toc 
         16*.xdv 
        1617_minted-* 
  • NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/main/appendices.tex

    r11330 r11692  
    11 
    2 \subfile{../subfiles/annex_A}             %% Generalised vertical coordinate 
    3 \subfile{../subfiles/annex_B}             %% Diffusive operator 
    4 \subfile{../subfiles/annex_C}             %% Discrete invariants of the eqs. 
    5 \subfile{../subfiles/annex_iso}            %% Isoneutral diffusion using triads 
    6 \subfile{../subfiles/annex_DOMAINcfg}     %% Brief notes on DOMAINcfg 
     2\subfile{../subfiles/apdx_s_coord}      %% A. Generalised vertical coordinate 
     3\subfile{../subfiles/apdx_diff_opers}   %% B. Diffusive operators 
     4\subfile{../subfiles/apdx_invariants}   %% C. Discrete invariants of the eqs. 
     5\subfile{../subfiles/apdx_triads}       %% D. Isoneutral diffusion using triads 
     6\subfile{../subfiles/apdx_DOMAINcfg}    %% E. Brief notes on DOMAINcfg 
    77 
    88%% Not included 
     
    1010%\subfile{../subfiles/chap_DIU} 
    1111%\subfile{../subfiles/chap_conservation} 
    12 %\subfile{../subfiles/annex_E}            %% Notes on some on going staff 
    13  
     12%\subfile{../subfiles/apdx_algos}   %% Notes on some on going staff 
  • NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/main/bibliography.bib

    r11336 r11692  
    16141614} 
    16151615 
     1616@article{         kraus.turner_tellus67, 
     1617  author = {Kraus, E.B. and Turner, J.}, 
     1618  journal = {Tellus}, 
     1619  pages = {98--106}, 
     1620  title = {A one dimensional model of the seasonal thermocline {II}. {T}he general theory and its consequences}, 
     1621  volume = {19}, 
     1622  year = {1967} 
     1623} 
     1624 
     1625@article{        large.ea_RG97, 
     1626  author        = "Large, W. G. and McWilliams, J. C. and Doney, S. C.", 
     1627  doi           = "10.1029/94RG01872", 
     1628  journal       = "Reviews of Geophysics", 
     1629  number        = {4}, 
     1630  pages         = {363--403}, 
     1631  publisher     = {AGU}, 
     1632  title         = "Oceanic vertical mixing: {A} review and a model with a nonlocal boundary layer parameterization", 
     1633  year          = "1994" 
     1634} 
     1635 
    16161636@techreport{      large.yeager_rpt04, 
    16171637  title         = "Diurnal to decadal global forcing for ocean and sea-ice 
     
    21842204} 
    21852205 
     2206@article{mcwilliams.ea_JFM97, 
     2207   author = {McWilliams, James C. and Sullivan, Peter P. and Moeng, Chin-Hoh}, 
     2208   doi = {10.1017/S0022112096004375}, 
     2209   journal = {Journal of Fluid Mechanics}, 
     2210   pages = {1--30}, 
     2211   title = {Langmuir turbulence in the ocean}, 
     2212   volume = {334}, 
     2213   year = {1997}, 
     2214} 
    21862215@article{         mellor.blumberg_JPO04, 
    21872216  title         = "Wave Breaking and Ocean Surface Layer Thermal Response", 
  • NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/main/chapters.tex

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

    • Property svn:ignore
      •  

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

    r11435 r11692  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter Assimilation increments (ASM) 
    6 % ================================================================ 
     4 
    75\chapter{Apply Assimilation Increments (ASM)} 
    86\label{chap:ASM} 
    97 
     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}  \\ 
     10 
     11\thispagestyle{plain} 
     12 
    1013\chaptertoc 
    1114 
    12 \vfill 
    13 \begin{figure}[b] 
    14 \subsubsection*{Changes record} 
    15 \begin{tabular}{l||l|m{0.65\linewidth}} 
    16     Release   & Author        & Modifications \\ 
    17     {\em 4.0} & {\em D. J. Lea} & {\em \NEMO\ 4.0 updates}  \\ 
    18     {\em 3.4} & {\em D. J. Lea, M. Martin, K. Mogensen, A. Weaver} & {\em Initial version}  \\ 
    19 \end{tabular} 
    20 \end{figure} 
     15\paragraph{Changes record} ~\\ 
    2116 
    22 \newpage 
     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 
    2329 
    2430The ASM code adds the functionality to apply increments to the model variables: temperature, salinity, 
     
    2632These are read into the model from a NetCDF file which may be produced by separate data assimilation code. 
    2733The code can also output model background fields which are used as an input to data assimilation code. 
    28 This is all controlled by the namelist \nam{\_asminc}. 
     34This is all controlled by the namelist \nam{_asminc}{\_asminc}. 
    2935There is a brief description of all the namelist options provided. 
    3036To build the ASM code \key{asminc} must be set. 
    3137 
    32 %=============================================================== 
    33  
     38%% ================================================================================================= 
    3439\section{Direct initialization} 
    3540\label{sec:ASM_DI} 
     
    3742Direct initialization (DI) refers to the instantaneous correction of the model background state using 
    3843the analysis increment. 
    39 DI is used when \np{ln\_asmdin} is set to true. 
     44DI is used when \np{ln_asmdin}{ln\_asmdin} is set to true. 
    4045 
     46%% ================================================================================================= 
    4147\section{Incremental analysis updates} 
    4248\label{sec:ASM_IAU} 
     
    4753This technique is referred to as Incremental Analysis Updates (IAU) \citep{bloom.takacs.ea_MWR96}. 
    4854IAU is a common technique used with 3D assimilation methods such as 3D-Var or OI. 
    49 IAU is used when \np{ln\_asmiau} is set to true. 
     55IAU is used when \np{ln_asmiau}{ln\_asmiau} is set to true. 
    5056 
    5157With IAU, the model state trajectory ${\mathbf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$) 
     
    5359additional tendency terms to the prognostic equations: 
    5460\begin{align*} 
    55   % \label{eq:wa_traj_iau} 
     61  % \label{eq:ASM_wa_traj_iau} 
    5662  {\mathbf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\mathbf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\mathbf x}^{a} 
    5763\end{align*} 
     
    6470Typically the increments are spread evenly over the full window. 
    6571In addition, two different weighting functions have been implemented. 
    66 The first function (namelist option \np{niaufn} = 0) employs constant weights, 
     72The first function (namelist option \np{niaufn}{niaufn}=0) employs constant weights, 
    6773\begin{align} 
    68   \label{eq:F1_i} 
     74  \label{eq:ASM_F1_i} 
    6975  F^{(1)}_{i} 
    7076  =\left\{ 
     
    7783\end{align} 
    7884where $M = m-n$. 
    79 The second function (namelist option \np{niaufn} = 1) employs peaked hat-like weights in order to give maximum weight in the centre of the sub-window, 
     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, 
    8086with the weighting reduced linearly to a small value at the window end-points: 
    8187\begin{align} 
    82   \label{eq:F2_i} 
     88  \label{eq:ASM_F2_i} 
    8389  F^{(2)}_{i} 
    8490  =\left\{ 
     
    9298\end{align} 
    9399where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even. 
    94 The weights described by \autoref{eq:F2_i} provide a smoother transition of the analysis trajectory from 
    95 one assimilation cycle to the next than that described by \autoref{eq:F1_i}. 
     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}. 
    96102 
    97 %========================================================================== 
    98 % Divergence damping description %%% 
     103%% ================================================================================================= 
    99104\section{Divergence damping initialisation} 
    100105\label{sec:ASM_div_dmp} 
     
    106111 
    107112\begin{equation} 
    108   \label{eq:asm_dmp} 
     113  \label{eq:ASM_dmp} 
    109114  \left\{ 
    110115    \begin{aligned} 
     
    120125 
    121126\[ 
    122   % \label{eq:asm_div} 
     127  % \label{eq:ASM_div} 
    123128  \chi^{n-1}_I = \frac{1}{e_{1t}\,e_{2t}\,e_{3t} } 
    124129  \left( {\delta_i \left[ {e_{2u}\,e_{3u}\,u^{n-1}_I} \right] 
     
    126131\] 
    127132 
    128 By the application of \autoref{eq:asm_dmp} the divergence is filtered in each iteration, 
     133By the application of \autoref{eq:ASM_dmp} the divergence is filtered in each iteration, 
    129134and the vorticity is left unchanged. 
    130135In the presence of coastal boundaries with zero velocity increments perpendicular to the coast 
     
    134139\citep{talagrand_JAS72, dobricic.pinardi.ea_OS07}. 
    135140Diffusion coefficients are defined as $A_D = \alpha e_{1t} e_{2t}$, where $\alpha = 0.2$. 
    136 The divergence damping is activated by assigning to \np{nn\_divdmp} in the \nam{\_asminc} namelist 
     141The divergence damping is activated by assigning to \np{nn_divdmp}{nn\_divdmp} in the \nam{_asminc}{\_asminc} namelist 
    137142a value greater than zero. 
    138143This 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. 
    139144 
    140  
    141 %========================================================================== 
    142  
     145%% ================================================================================================= 
    143146\section{Implementation details} 
    144147\label{sec:ASM_details} 
    145148 
    146 Here we show an example \nam{\_asminc} 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 
    147150the ORCA2 grid. 
    148151 
    149 %------------------------------------------nam_asminc----------------------------------------------------- 
    150 % 
    151 \nlst{nam_asminc} 
    152 %------------------------------------------------------------------------------------------------------------- 
     152\begin{listing} 
     153  \nlst{nam_asminc} 
     154  \caption{\forcode{&nam_asminc}} 
     155  \label{lst:nam_asminc} 
     156\end{listing} 
    153157 
    154158The header of an assimilation increments file produced using the NetCDF tool 
     
    190194\end{clines} 
    191195 
    192 \biblio 
    193  
    194 \pindex 
     196\onlyinsubfile{\input{../../global/epilogue}} 
    195197 
    196198\end{document} 
  • NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/subfiles/chap_DIA.tex

    r11435 r11692  
    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 
     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 
    1016\chaptertoc 
    1117 
    12 \vfill 
    13 \begin{figure}[b] 
    14 \subsubsection*{Changes record} 
    15 \begin{tabular}{l||l|m{0.65\linewidth}} 
    16     Release   & Author        & Modifications \\ 
    17     {\em 4.0} & {\em Mirek Andrejczuk, Massimiliano Drudi} & {\em }  \\ 
    18     {\em }      & {\em Dorotea Iovino, Nicolas Martin} & {\em }  \\ 
    19     {\em 3.6} & {\em Gurvan Madec, Sebastien Masson } & {\em }  \\ 
    20     {\em 3.4} & {\em Gurvan Madec, Rachid Benshila, Andrew Coward } & {\em }  \\ 
    21     {\em }      & {\em Christian Ethe, Sebastien Masson } & {\em }  \\ 
    22 \end{tabular} 
    23 \end{figure} 
    24  
    25 \newpage 
    26  
    27 % ================================================================ 
    28 %       Old Model Output 
    29 % ================================================================ 
     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%% ================================================================================================= 
    3034\section{Model output} 
    3135\label{sec:DIA_io_old} 
     
    5357%\gmcomment{                    % start of gmcomment 
    5458 
    55 % ================================================================ 
    56 % Diagnostics 
    57 % ================================================================ 
     59%% ================================================================================================= 
    5860\section{Standard model output (IOM)} 
    5961\label{sec:DIA_iom} 
     
    6466 
    6567\begin{enumerate} 
    66 \item 
    67   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 
    6869  the user from standard templates. 
    69 \item 
    70   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 
    7171  all diagnostic output related tasks to dedicated processes. 
    7272\end{enumerate} 
     
    7676 
    7777\begin{itemize} 
    78 \item 
    79   The choice of output frequencies that can be different for each file (including real months and years). 
    80 \item 
    81   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 
    8280  (the same data can be written in different files). 
    83 \item 
    84   The possibility to split output files at a chosen frequency. 
    85 \item 
    86   The possibility to extract a vertical or an horizontal subdomain. 
    87 \item 
    88   The choice of the temporal operation to perform, \eg: average, accumulate, instantaneous, min, max and once. 
    89 \item 
    90   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. 
    9185\end{itemize} 
    9286 
     
    122116even without a parallel-enabled NetCDF4 library, simply by employing only one dedicated I/O server. 
    123117 
     118%% ================================================================================================= 
    124119\subsection{XIOS: Reading and writing restart file} 
    125120 
    126121XIOS may be used to read single file restart produced by \NEMO. Currently only the variables written to 
    127 file \forcode{numror} can be handled by XIOS. To activate restart reading using XIOS, set \np{ln\_xios\_read}\forcode{ = .true. } 
     122file \forcode{numror} can be handled by XIOS. To activate restart reading using XIOS, set \np[=.true. ]{ln_xios_read}{ln\_xios\_read} 
    128123in \textit{namelist\_cfg}. This setting will be ignored when multiple restart files are present, and default \NEMO 
    129124functionality will be used for reading. There is no need to change iodef.xml file to use XIOS to read 
     
    140135dimension \forcode{z} defined in restart file must be renamed to \forcode{nav_lev}.\\ 
    141136 
    142 XIOS can also be used to write \NEMO\ restart. A namelist parameter \np{nn\_wxios} is used to determine the 
     137XIOS can also be used to write \NEMO\ restart. A namelist parameter \np{nn_wxios}{nn\_wxios} is used to determine the 
    143138type of restart \NEMO\ will write. If it is set to 0, default \NEMO\ functionality will be used - each 
    144139processor writes its own restart file; if it is set to 1 XIOS will write restart into a single file; 
    145 for \np{nn\_wxios}\forcode{ = 2} the restart will be written by XIOS into multiple files, one for each XIOS server. 
    146 Note, however, that \textbf{\NEMO\ will not read restart generated by XIOS when \np{nn\_wxios}\forcode{ = 2}}. The restart will 
     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 
    147142have to be rebuild before continuing the run. This option aims to reduce number of restart files generated by \NEMO\ only, 
    148143and may be useful when there is a need to change number of processors used to run simulation. 
    149144 
    150145If an additional variable must be written to a restart file, the following steps are needed: 
    151 \begin{description} 
    152    \item[step 1:] add variable name to a list of restart variables (in subroutine \rou{iom\_set\_rst\_vars,} \mdl{iom}) and 
     146\begin{enumerate} 
     147\item Add variable name to a list of restart variables (in subroutine \rou{iom\_set\_rst\_vars,} \mdl{iom}) and 
    153148define correct grid for the variable (\forcode{grid_N_3D} - 3D variable, \forcode{grid_N} - 2D variable, \forcode{grid_vector} - 
    1541491D variable, \forcode{grid_scalar} - scalar), 
    155    \item[step 2:] add variable to the list of fields written by restart.  This can be done either in subroutine 
     150\item Add variable to the list of fields written by restart.  This can be done either in subroutine 
    156151\rou{iom\_set\_rstw\_core} (\mdl{iom}) or by calling  \rou{iom\_set\_rstw\_active} (\mdl{iom}) with the name of a variable 
    157152as an argument. This convention follows approach for writing restart using iom, where variables are 
    158153written either by \rou{rst\_write} or by calling \rou{iom\_rstput} from individual routines. 
    159 \end{description} 
    160  
     154\end{enumerate} 
    161155 
    162156An older versions of XIOS do not support reading functionality. It's recommended to use at least XIOS2@1451. 
    163157 
    164  
     158%% ================================================================================================= 
    165159\subsection{XIOS: XML Inputs-Outputs Server} 
    166160 
     161%% ================================================================================================= 
    167162\subsubsection{Attached or detached mode?} 
    168163 
     
    174169\xmlline|<variable id="using_server" type="bool"></variable>| 
    175170 
    176 The {\ttfamily using\_server} setting determines whether or not the server will be used in \textit{attached mode} 
    177 (as a library) [{\ttfamily> false <}] or in \textit{detached mode} 
    178 (as an external executable on N additional, dedicated cpus) [{\ttfamily > true <}]. 
    179 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. 
    180177The type of each file can be either ''multiple\_file'' or ''one\_file''. 
    181178 
     
    197194The following subsection provides a typical example but the syntax will vary in different MPP environments. 
    198195 
     196%% ================================================================================================= 
    199197\subsubsection{Number of cpu used by XIOS in detached mode} 
    200198 
     
    211209\cmd|mpirun -np 62 ./nemo.exe : -np 2 ./xios_server.exe| 
    212210 
     211%% ================================================================================================= 
    213212\subsubsection{Control of XIOS: the context in iodef.xml} 
    214213 
     
    218217 
    219218\begin{table} 
    220   \scriptsize 
    221219  \begin{tabularx}{\textwidth}{|lXl|} 
    222220    \hline 
     
    257255\end{table} 
    258256 
     257%% ================================================================================================= 
    259258\subsection{Practical issues} 
    260259 
     260%% ================================================================================================= 
    261261\subsubsection{Installation} 
    262262 
     
    267267{Extract and install XIOS} guide provides an example illustration of how this can be achieved. 
    268268 
     269%% ================================================================================================= 
    269270\subsubsection{Add your own outputs} 
    270271 
     
    275276 
    276277\begin{enumerate} 
    277 \item[1.] 
    278   in \NEMO\ code, add a \forcode{CALL iom_put( 'identifier', array )} where you want to output a 2D or 3D array. 
    279 \item[2.] 
    280   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 
    281280  the upper part of your module. 
    282 \item[3.] 
    283   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 
    284282  (see subsequent sections for a details of the XML syntax and rules). 
    285283  For example: 
    286  
    287284\begin{xmllines} 
    288285<field_definition> 
     
    293290</field_definition> 
    294291\end{xmllines} 
    295  
    296292Note your definition must be added to the field\_group whose reference grid is consistent with the size of 
    297293the array passed to iomput. 
     
    300296(iom\_set\_domain\_attr and iom\_set\_axis\_attr in \mdl{iom}) or defined in the domain\_def.xml file. 
    301297\eg: 
    302  
    303298\begin{xmllines} 
    304299<grid id="grid_T_3D" domain_ref="grid_T" axis_ref="deptht"/> 
    305300\end{xmllines} 
    306  
    307 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, 
    308302add the field definition within the field\_group defined with the id "SBC": 
    309303\xmlcode{<field_group id="SBC" ...>} which has been defined with the correct frequency of operations 
    310304(iom\_set\_field\_attr in \mdl{iom}) 
    311 \item[4.] 
    312   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 
    313306  (again see subsequent sections for syntax and rules) 
    314  
    315307\begin{xmllines} 
    316308<file id="file1" .../> 
     
    320312</file> 
    321313\end{xmllines} 
    322  
    323314\end{enumerate} 
    324315 
     316%% ================================================================================================= 
    325317\subsection{XML fundamentals} 
    326318 
     319%% ================================================================================================= 
    327320\subsubsection{ XML basic rules} 
    328321 
     
    334327See \href{http://www.xmlnews.org/docs/xml-basics.html}{here} for more details. 
    335328 
     329%% ================================================================================================= 
    336330\subsubsection{Structure of the XML file used in \NEMO} 
    337331 
     
    341335 
    342336\begin{table} 
    343   \scriptsize 
    344337  \begin{tabular*}{\textwidth}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} 
    345338    \hline 
     
    373366 
    374367\begin{table} 
    375   \scriptsize 
    376368  \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} 
    377369    \hline 
     
    398390 
    399391\begin{table} 
    400   \scriptsize 
    401392  \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} 
    402393    \hline 
     
    418409 
    419410\begin{table} 
    420   \scriptsize 
    421411  \begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} 
    422412    \hline 
     
    443433\end{table} 
    444434 
     435%% ================================================================================================= 
    445436\subsubsection{Nesting XML files} 
    446437 
     
    459450\end{xmllines} 
    460451 
     452%% ================================================================================================= 
    461453\subsubsection{Use of inheritance} 
    462454 
     
    499491Inherit (and overwrite, if needed) the attributes of a tag you are refering to. 
    500492 
     493%% ================================================================================================= 
    501494\subsubsection{Use of groups} 
    502495 
     
    540533\end{xmllines} 
    541534 
     535%% ================================================================================================= 
    542536\subsection{Detailed functionalities} 
    543537 
     
    545539the new functionalities offered by the XML interface of XIOS. 
    546540 
     541%% ================================================================================================= 
    547542\subsubsection{Define horizontal subdomains} 
    548543 
     
    586581We are therefore advising to use the ''one\_file'' type in this case. 
    587582 
     583%% ================================================================================================= 
    588584\subsubsection{Define vertical zooms} 
    589585 
     
    609605\end{xmllines} 
    610606 
     607%% ================================================================================================= 
    611608\subsubsection{Control of the output file names} 
    612609 
     
    634631 
    635632\begin{table} 
    636   \scriptsize 
    637633  \begin{tabularx}{\textwidth}{|lX|} 
    638634    \hline 
     
    682678\noindent will give the following file name radical: \ifile{myfile\_ORCA2\_19891231\_freq1d} 
    683679 
     680%% ================================================================================================= 
    684681\subsubsection{Other controls of the XML attributes from \NEMO} 
    685682 
     
    695692 
    696693\begin{table} 
    697   \scriptsize 
    698   \begin{tabularx}{\textwidth}{|X|c|c|c|} 
     694  \begin{tabular}{|l|c|c|} 
    699695    \hline 
    700696    tag ids affected by automatic definition of some of their attributes & 
    701697    name attribute                                                       & 
    702     attribute value                      \\ 
     698    attribute value                                                      \\ 
    703699    \hline 
    704700    \hline 
    705701    field\_definition                                                    & 
    706702    freq\_op                                                             & 
    707     \np{rn\_rdt}                         \\ 
     703    \np{rn_rdt}{rn\_rdt}                                                         \\ 
    708704    \hline 
    709705    SBC                                                                  & 
    710706    freq\_op                                                             & 
    711     \np{rn\_rdt} $\times$ \np{nn\_fsbc}  \\ 
     707    \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_fsbc}{nn\_fsbc}                                  \\ 
    712708    \hline 
    713709    ptrc\_T                                                              & 
    714710    freq\_op                                                             & 
    715     \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ 
     711    \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_dttrc}{nn\_dttrc}                                \\ 
    716712    \hline 
    717713    diad\_T                                                              & 
    718714    freq\_op                                                             & 
    719     \np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ 
     715    \np{rn_rdt}{rn\_rdt} $\times$ \np{nn_dttrc}{nn\_dttrc}                                \\ 
    720716    \hline 
    721717    EqT, EqU, EqW                                                        & 
    722718    jbegin, ni,                                                          & 
    723     according to the grid                \\ 
    724     & 
     719    according to the grid                                                \\ 
     720                                                                         & 
    725721    name\_suffix                                                         & 
    726     \\ 
     722                                                                         \\ 
    727723    \hline 
    728724    TAO, RAMA and PIRATA moorings                                        & 
    729725    zoom\_ibegin, zoom\_jbegin,                                          & 
    730     according to the grid                \\ 
    731     & 
     726    according to the grid                                                \\ 
     727                                                                         & 
    732728    name\_suffix                                                         & 
    733     \\ 
    734     \hline 
    735   \end{tabularx} 
     729                                                                         \\ 
     730    \hline 
     731  \end{tabular} 
    736732\end{table} 
    737733 
     734%% ================================================================================================= 
    738735\subsubsection{Advanced use of XIOS functionalities} 
    739736 
     737%% ================================================================================================= 
    740738\subsection{XML reference tables} 
    741 \label{subsec:IOM_xmlref} 
     739\label{subsec:DIA_IOM_xmlref} 
    742740 
    743741\begin{enumerate} 
    744 \item 
    745   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. 
    746743 
    747744\begin{xmllines} 
     
    751748\end{xmllines} 
    752749 
    753 \item 
    754   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. 
    755751 
    756752in field\_definition: 
     
    769765sst2 won't be evaluated. 
    770766 
    771 \item 
    772   Change of variable precision: 
     767\item Change of variable precision: 
    773768 
    774769\begin{xmllines} 
     
    783778Forcing double precision outputs with prec="8" (for example in the field\_definition) will avoid this problem. 
    784779 
    785 \item 
    786   add user defined attributes: 
     780\item add user defined attributes: 
    787781 
    788782\begin{xmllines} 
     
    799793\end{xmllines} 
    800794 
    801 \item 
    802   use of the ``@'' function: example 1, weighted temporal average 
     795\item use of the ``@'' function: example 1, weighted temporal average 
    803796 
    804797 - define a new variable in field\_definition 
     
    828821Note that in this case, freq\_op must be equal to the file output\_freq. 
    829822 
    830 \item 
    831   use of the ``@'' function: example 2, monthly SSH standard deviation 
     823\item use of the ``@'' function: example 2, monthly SSH standard deviation 
    832824 
    833825 - define a new variable in field\_definition 
     
    859851Note that in this case, freq\_op must be equal to the file output\_freq. 
    860852 
    861 \item 
    862   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 
    863854 
    864855 - define 2 new variables in field\_definition 
     
    891882field\_ref="sst" means that attributes not explicitely defined, are inherited from sst field. 
    892883 
     884%% ================================================================================================= 
    893885\subsubsection{Tag list per family} 
    894886 
    895887\begin{table} 
    896   \scriptsize 
    897888  \begin{tabularx}{\textwidth}{|l|X|X|l|X|} 
    898889    \hline 
     
    917908    \hline 
    918909  \end{tabularx} 
    919   \caption{Context tags} 
     910  \caption{XIOS: context tags} 
    920911\end{table} 
    921912 
    922913\begin{table} 
    923   \scriptsize 
    924914  \begin{tabularx}{\textwidth}{|l|X|X|X|l|} 
    925915    \hline 
     
    952942    \hline 
    953943  \end{tabularx} 
    954   \caption{Field tags ("\ttfamily{field\_*}")} 
     944  \caption{XIOS: field tags ("\texttt{field\_*}")} 
    955945\end{table} 
    956946 
    957947\begin{table} 
    958   \scriptsize 
    959948  \begin{tabularx}{\textwidth}{|l|X|X|X|l|} 
    960949    \hline 
     
    988977    \hline 
    989978  \end{tabularx} 
    990   \caption{File tags ("\ttfamily{file\_*}")} 
     979  \caption{XIOS: file tags ("\texttt{file\_*}")} 
    991980\end{table} 
    992981 
    993982\begin{table} 
    994   \scriptsize 
    995983  \begin{tabularx}{\textwidth}{|l|X|X|X|X|} 
    996984    \hline 
     
    10211009    \hline 
    10221010  \end{tabularx} 
    1023   \caption{Axis tags ("\ttfamily{axis\_*}")} 
     1011  \caption{XIOS: axis tags ("\texttt{axis\_*}")} 
    10241012\end{table} 
    10251013 
    10261014\begin{table} 
    1027   \scriptsize 
    10281015  \begin{tabularx}{\textwidth}{|l|X|X|X|X|} 
    10291016    \hline 
     
    10541041    \hline 
    10551042  \end{tabularx} 
    1056   \caption{Domain tags ("\ttfamily{domain\_*)}"} 
     1043  \caption{XIOS: domain tags ("\texttt{domain\_*)}"} 
    10571044\end{table} 
    10581045 
    10591046\begin{table} 
    1060   \scriptsize 
    10611047  \begin{tabularx}{\textwidth}{|l|X|X|X|X|} 
    10621048    \hline 
     
    10871073    \hline 
    10881074  \end{tabularx} 
    1089   \caption{Grid tags ("\ttfamily{grid\_*}")} 
     1075  \caption{XIOS: grid tags ("\texttt{grid\_*}")} 
    10901076\end{table} 
    10911077 
     1078%% ================================================================================================= 
    10921079\subsubsection{Attributes list per family} 
    10931080 
    10941081\begin{table} 
    1095   \scriptsize 
    10961082  \begin{tabularx}{\textwidth}{|l|X|l|l|} 
    10971083    \hline 
     
    11281114    \hline 
    11291115  \end{tabularx} 
    1130   \caption{Reference attributes ("\ttfamily{*\_ref}")} 
     1116  \caption{XIOS: reference attributes ("\texttt{*\_ref}")} 
    11311117\end{table} 
    11321118 
    11331119\begin{table} 
    1134   \scriptsize 
    11351120  \begin{tabularx}{\textwidth}{|l|X|l|l|} 
    11361121    \hline 
     
    11641149    \hline 
    11651150  \end{tabularx} 
    1166   \caption{Domain attributes ("\ttfamily{zoom\_*}")} 
     1151  \caption{XIOS: domain attributes ("\texttt{zoom\_*}")} 
    11671152\end{table} 
    11681153 
    11691154\begin{table} 
    1170   \scriptsize 
    11711155  \begin{tabularx}{\textwidth}{|l|X|l|l|} 
    11721156    \hline 
     
    12191203    \hline 
    12201204  \end{tabularx} 
    1221   \caption{File attributes} 
     1205  \caption{XIOS: file attributes} 
    12221206\end{table} 
    12231207 
    12241208\begin{table} 
    1225   \scriptsize 
    12261209  \begin{tabularx}{\textwidth}{|l|X|l|l|} 
    12271210    \hline 
     
    12681251    \hline 
    12691252  \end{tabularx} 
    1270   \caption{Field attributes} 
     1253  \caption{XIOS: field attributes} 
    12711254\end{table} 
    12721255 
    12731256\begin{table} 
    1274   \scriptsize 
    12751257  \begin{tabularx}{\textwidth}{|l|X|X|X|} 
    12761258    \hline 
     
    13271309    \hline 
    13281310  \end{tabularx} 
    1329   \caption{Miscellaneous attributes} 
     1311  \caption{XIOS: miscellaneous attributes} 
    13301312\end{table} 
    13311313 
     1314%% ================================================================================================= 
    13321315\subsection{CF metadata standard compliance} 
    13331316 
     
    13361319the CF metadata standard. 
    13371320Therefore while a user may wish to add their own metadata to the output files (as demonstrated in example 4 of 
    1338 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. 
    13391322 
    13401323Some metadata that may significantly increase the file size (horizontal cell areas and vertices) are controlled by 
    1341 the namelist parameter \np{ln\_cfmeta} in the \nam{run} namelist. 
     1324the namelist parameter \np{ln_cfmeta}{ln\_cfmeta} in the \nam{run}{run} namelist. 
    13421325This must be set to true if these metadata are to be included in the output files. 
    13431326 
    1344  
    1345 % ================================================================ 
    1346 %       NetCDF4 support 
    1347 % ================================================================ 
    1348 \section[NetCDF4 support (\texttt{\textbf{key\_netcdf4}})] 
    1349 {NetCDF4 support (\protect\key{netcdf4})} 
     1327%% ================================================================================================= 
     1328\section[NetCDF4 support (\texttt{\textbf{key\_netcdf4}})]{NetCDF4 support (\protect\key{netcdf4})} 
    13501329\label{sec:DIA_nc4} 
    13511330 
     
    13621341most analysis codes can be relinked simply with the new libraries and will then read both NetCDF3 and NetCDF4 files. 
    13631342\NEMO\ executables linked with NetCDF4 libraries can be made to produce NetCDF3 files by 
    1364 setting the \np{ln\_nc4zip} logical to false in the \nam{nc4} namelist: 
    1365  
    1366 %------------------------------------------namnc4---------------------------------------------------- 
    1367  
    1368 \nlst{namnc4} 
    1369 %------------------------------------------------------------------------------------------------------------- 
     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} 
    13701350 
    13711351If \key{netcdf4} has not been defined, these namelist parameters are not read. 
    1372 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. 
    13731353These functions will not be used but need to be included so that compilation is possible with NetCDF3 libraries. 
    13741354 
     
    14041384\end{forlines} 
    14051385 
    1406 \noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\ttfamily 46x38x1} respectively in 
    1407 the mono-processor case (\ie\ global domain of {\small\ttfamily 182x149x31}). 
     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}). 
    14081388An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in 
    1409 table \autoref{tab:NC4} which compares the results of two short runs of the ORCA2\_LIM reference configuration with 
     1389table \autoref{tab:DIA_NC4} which compares the results of two short runs of the ORCA2\_LIM reference configuration with 
    14101390a 4x2 mpi partitioning. 
    14111391Note the variation in the compression ratio achieved which reflects chiefly the dry to wet volume ratio of 
    14121392each processing region. 
    14131393 
    1414 %------------------------------------------TABLE---------------------------------------------------- 
    14151394\begin{table} 
    1416   \scriptsize 
    14171395  \centering 
    14181396  \begin{tabular}{lrrr} 
     
    14461424    ORCA2\_2d\_grid\_W\_0007.nc & 4416    & 1368     & 70\%      \\ 
    14471425  \end{tabular} 
    1448   \caption{ 
    1449     \protect\label{tab:NC4} 
    1450     Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression 
    1451   } 
     1426  \caption{Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression} 
     1427  \label{tab:DIA_NC4} 
    14521428\end{table} 
    1453 %---------------------------------------------------------------------------------------------------- 
    14541429 
    14551430When \key{iomput} is activated with \key{netcdf4} chunking and compression parameters for fields produced via 
    1456 \rou{iom\_put} calls are set via an equivalent and identically named namelist to \nam{nc4} in 
     1431\rou{iom\_put} calls are set via an equivalent and identically named namelist to \nam{nc4}{nc4} in 
    14571432\textit{xmlio\_server.def}. 
    1458 Typically this namelist serves the mean files whilst the \nam{nc4} in the main namelist file continues to 
     1433Typically this namelist serves the mean files whilst the \nam{nc4}{nc4} in the main namelist file continues to 
    14591434serve the restart files. 
    14601435This duplication is unfortunate but appropriate since, if using io\_servers, the domain sizes of 
     
    14621437the invidual processing regions and different chunking choices may be desired. 
    14631438 
    1464 % ------------------------------------------------------------------------------------------------------------- 
    1465 %       Tracer/Dynamics Trends 
    1466 % ------------------------------------------------------------------------------------------------------------- 
    1467 \section[Tracer/Dynamics trends (\texttt{namtrd})] 
    1468 {Tracer/Dynamics trends (\protect\nam{trd})} 
     1439%% ================================================================================================= 
     1440\section[Tracer/Dynamics trends (\forcode{&namtrd})]{Tracer/Dynamics trends (\protect\nam{trd}{trd})} 
    14691441\label{sec:DIA_trd} 
    14701442 
    1471 %------------------------------------------namtrd---------------------------------------------------- 
    1472  
    1473 \nlst{namtrd} 
    1474 %------------------------------------------------------------------------------------------------------------- 
     1443\begin{listing} 
     1444  \nlst{namtrd} 
     1445  \caption{\forcode{&namtrd}} 
     1446  \label{lst:namtrd} 
     1447\end{listing} 
    14751448 
    14761449Each trend of the dynamics and/or temperature and salinity time evolution equations can be send to 
    14771450\mdl{trddyn} and/or \mdl{trdtra} modules (see TRD directory) just after their computation 
    14781451(\ie\ at the end of each \textit{dyn....F90} and/or \textit{tra....F90} routines). 
    1479 This capability is controlled by options offered in \nam{trd} namelist. 
     1452This capability is controlled by options offered in \nam{trd}{trd} namelist. 
    14801453Note that the output are done with XIOS, and therefore the \key{iomput} is required. 
    14811454 
    1482 What is done depends on the \nam{trd} logical set to \forcode{.true.}: 
     1455What is done depends on the \nam{trd}{trd} logical set to \forcode{.true.}: 
    14831456 
    14841457\begin{description} 
    1485 \item[\np{ln\_glo\_trd}]: 
    1486   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 
    14871459  the momentum and tracer equations is performed. 
    14881460  This also includes a check of $T^2$, $S^2$, $\tfrac{1}{2} (u^2+v2)$, 
    14891461  and potential energy time evolution equations properties; 
    1490 \item[\np{ln\_dyn\_trd}]: 
    1491   each 3D trend of the evolution of the two momentum components is output; 
    1492 \item[\np{ln\_dyn\_mxl}]: 
    1493   each 3D trend of the evolution of the two momentum components averaged over the mixed layer is output; 
    1494 \item[\np{ln\_vor\_trd}]: 
    1495   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, 
    14961465  then the curl is computed to obtain the barotropic vorticity tendencies which are output; 
    1497 \item[\np{ln\_KE\_trd}] : 
    1498   each 3D trend of the Kinetic Energy equation is output; 
    1499 \item[\np{ln\_tra\_trd}]: 
    1500   each 3D trend of the evolution of temperature and salinity is output; 
    1501 \item[\np{ln\_tra\_mxl}]: 
    1502   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; 
    15031469\end{description} 
    15041470 
     
    15071473 
    15081474\textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested. 
    1509 In particular, options associated with \np{ln\_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl} are not working, 
    1510 and none of the options have been tested with variable volume (\ie\ \np{ln\_linssh}\forcode{ = .true.}). 
    1511  
    1512 % ------------------------------------------------------------------------------------------------------------- 
    1513 %       On-line Floats trajectories 
    1514 % ------------------------------------------------------------------------------------------------------------- 
    1515 \section[FLO: On-Line Floats trajectories (\texttt{\textbf{key\_floats}})] 
    1516 {FLO: On-Line Floats trajectories (\protect\key{floats})} 
    1517 \label{sec:FLO} 
    1518 %--------------------------------------------namflo------------------------------------------------------- 
    1519  
    1520 \nlst{namflo} 
    1521 %-------------------------------------------------------------------------------------------------------------- 
     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} 
    15221487 
    15231488The on-line computation of floats advected either by the three dimensional velocity field or constraint to 
    15241489remain at a given depth ($w = 0$ in the computation) have been introduced in the system during the CLIPPER project. 
    1525 Options are defined by \nam{flo} namelist variables. 
     1490Options are defined by \nam{flo}{flo} namelist variables. 
    15261491The algorithm used is based either on the work of \cite{blanke.raynaud_JPO97} (default option), 
    1527 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}). 
    15281493Note that the \cite{blanke.raynaud_JPO97} algorithm have the advantage of providing trajectories which 
    15291494are consistent with the numeric of the code, so that the trajectories never intercept the bathymetry. 
    15301495 
     1496%% ================================================================================================= 
    15311497\subsubsection{Input data: initial coordinates} 
    15321498 
    15331499Initial coordinates can be given with Ariane Tools convention 
    1534 (IJK coordinates, (\np{ln\_ariane}\forcode{ = .true.}) ) or with longitude and latitude. 
     1500(IJK coordinates, (\np[=.true.]{ln_ariane}{ln\_ariane}) ) or with longitude and latitude. 
    15351501 
    15361502In case of Ariane convention, input filename is \textit{init\_float\_ariane}. 
    15371503Its format is: \\ 
    1538 {\scriptsize \texttt{I J K nisobfl itrash}} 
     1504{ \texttt{I J K nisobfl itrash}} 
    15391505 
    15401506\noindent with: 
     
    15481514\noindent Example: \\ 
    15491515\noindent 
    1550 {\scriptsize 
     1516{ 
    15511517  \texttt{ 
    15521518    100.00000  90.00000  -1.50000 1.00000   0.00000   \\ 
     
    15591525In the other case (longitude and latitude), input filename is init\_float. 
    15601526Its format is: \\ 
    1561 {\scriptsize \texttt{Long Lat depth nisobfl ngrpfl itrash}} 
     1527{ \texttt{Long Lat depth nisobfl ngrpfl itrash}} 
    15621528 
    15631529\noindent with: 
     
    15731539\noindent Example: \\ 
    15741540\noindent 
    1575 {\scriptsize 
     1541{ 
    15761542  \texttt{ 
    15771543    20.0 0.0 0.0 0 1 1    \\ 
     
    15821548} \\ 
    15831549 
    1584 \np{jpnfl} is the total number of floats during the run. 
    1585 When initial positions are read in a restart file (\np{ln\_rstflo}\forcode{ = .true.} ), 
    1586 \np{jpnflnewflo} can be added in the initialization file. 
    1587  
     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%% ================================================================================================= 
    15881555\subsubsection{Output data} 
    15891556 
    1590 \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 
    15911558creation of the float restart file. 
    15921559 
    1593 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}). 
    15941561In that case, output filename is trajec\_float. 
    15951562 
    1596 Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}) with 
     1563Another possiblity of writing format is Netcdf (\np[=.false.]{ln_flo_ascii}{ln\_flo\_ascii}) with 
    15971564\key{iomput} and outputs selected in iodef.xml. 
    15981565Here it is an example of specification to put in files description section: 
     
    16121579\end{xmllines} 
    16131580 
    1614  
    1615 % ------------------------------------------------------------------------------------------------------------- 
    1616 %       Harmonic analysis of tidal constituents 
    1617 % ------------------------------------------------------------------------------------------------------------- 
    1618 \section[Harmonic analysis of tidal constituents (\texttt{\textbf{key\_diaharm}})] 
    1619 {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})} 
    16201583\label{sec:DIA_diag_harm} 
    16211584 
    1622 %------------------------------------------nam_diaharm---------------------------------------------------- 
    1623 % 
    1624 \nlst{nam_diaharm} 
    1625 %---------------------------------------------------------------------------------------------------------- 
     1585\begin{listing} 
     1586  \nlst{nam_diaharm} 
     1587  \caption{\forcode{&nam_diaharm}} 
     1588  \label{lst:nam_diaharm} 
     1589\end{listing} 
    16261590 
    16271591A module is available to compute the amplitude and phase of tidal waves. 
    16281592This on-line Harmonic analysis is actived with \key{diaharm}. 
    16291593 
    1630 Some parameters are available in namelist \nam{\_diaharm}: 
    1631  
    1632  - \np{nit000\_han} is the first time step used for harmonic analysis 
    1633  
    1634  - \np{nitend\_han} is the  last time step used for harmonic analysis 
    1635  
    1636  - \np{nstep\_han}  is the  time step frequency for harmonic analysis 
    1637  
    1638 % - \np{nb\_ana}     is the number of harmonics to analyse 
    1639  
    1640  - \np{tname}       is an array with names of tidal constituents to analyse 
    1641  
    1642  \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. 
    16431607 The restart capability is not implemented. 
    16441608 
     
    16611625We obtain in output $C_{j}$ and $S_{j}$ for each tidal wave. 
    16621626 
    1663 % ------------------------------------------------------------------------------------------------------------- 
    1664 %       Sections transports 
    1665 % ------------------------------------------------------------------------------------------------------------- 
    1666 \section[Transports across sections (\texttt{\textbf{key\_diadct}})] 
    1667 {Transports across sections (\protect\key{diadct})} 
     1627%% ================================================================================================= 
     1628\section[Transports across sections (\texttt{\textbf{key\_diadct}})]{Transports across sections (\protect\key{diadct})} 
    16681629\label{sec:DIA_diag_dct} 
    16691630 
    1670 %------------------------------------------namdct---------------------------------------------------- 
    1671  
    1672 \nlst{namdct} 
    1673 %------------------------------------------------------------------------------------------------------------- 
     1631\begin{listing} 
     1632  \nlst{nam_diadct} 
     1633  \caption{\forcode{&nam_diadct}} 
     1634  \label{lst:nam_diadct} 
     1635\end{listing} 
    16741636 
    16751637A module is available to compute the transport of volume, heat and salt through sections. 
     
    16891651- \texttt{salt\_transport}   for   salt transports (unit: $10^{9}Kg s^{-1}$) \\ 
    16901652 
    1691 Namelist variables in \nam{dct} 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 
    16921654they are averaged, as well as the level of output for debugging: 
    1693 \np{nn\_dct}   : frequency of instantaneous transports computing 
    1694 \np{nn\_dctwri}: frequency of writing ( mean of instantaneous transports ) 
    1695 \np{nn\_debug} : debugging of the section 
    1696  
     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%% ================================================================================================= 
    16971660\subsubsection{Creating a binary file containing the pathway of each section} 
    16981661 
     
    17041667 
    17051668Each section is defined by: \\ 
    1706 \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}} \\ 
    17071670with: 
    17081671 
     
    17211684 
    17221685\noindent If nclass $\neq$ 0, the next lines contain the class type and the nclass bounds: \\ 
    1723 {\scriptsize 
     1686{ 
    17241687  \texttt{ 
    17251688    long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name \\ 
     
    17541717 and the ATL\_Cuba\_Florida with 4 temperature clases (5 class bounds), are shown: \\ 
    17551718 \noindent 
    1756  {\scriptsize 
     1719 { 
    17571720   \texttt{ 
    17581721     -68.    -54.5   -60.    -64.7  00 okstrpond noice ACC\_Drake\_Passage \\ 
     
    17661729 } 
    17671730 
     1731%% ================================================================================================= 
    17681732\subsubsection{To read the output files} 
    17691733 
    17701734The output format is: \\ 
    1771 {\scriptsize 
     1735{ 
    17721736  \texttt{ 
    17731737    date, time-step number, section number,                \\ 
     
    17911755 
    17921756\begin{table} 
    1793   \scriptsize 
    17941757  \begin{tabular}{|l|l|l|l|l|} 
    17951758    \hline 
     
    18051768\end{table} 
    18061769 
    1807 % ================================================================ 
    1808 % Steric effect in sea surface height 
    1809 % ================================================================ 
     1770%% ================================================================================================= 
    18101771\section{Diagnosing the steric effect in sea surface height} 
    18111772\label{sec:DIA_steric} 
    1812  
    18131773 
    18141774Changes in steric sea level are caused when changes in the density of the water column imply an expansion or 
     
    18471807    \mathcal{V} &=  \mathcal{A}  \;\bar{\eta} 
    18481808  \end{split} 
    1849   \label{eq:MV_nBq} 
     1809  \label{eq:DIA_MV_nBq} 
    18501810\end{equation} 
    18511811 
     
    18551815  \frac{1}{e_3} \partial_t ( e_3\,\rho) + \nabla( \rho \, \textbf{U} ) 
    18561816  = \left. \frac{\textit{emp}}{e_3}\right|_\textit{surface} 
    1857   \label{eq:Co_nBq} 
     1817  \label{eq:DIA_Co_nBq} 
    18581818\end{equation} 
    18591819 
     
    18641824\begin{equation} 
    18651825  \partial_t \mathcal{M} = \mathcal{A} \;\overline{\textit{emp}} 
    1866   \label{eq:Mass_nBq} 
     1826  \label{eq:DIA_Mass_nBq} 
    18671827\end{equation} 
    18681828 
    18691829where $\overline{\textit{emp}} = \int_S \textit{emp}\,ds$ is the net mass flux through the ocean surface. 
    1870 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 
    18711831the evolution equation of the mean sea level 
    18721832 
     
    18741834  \partial_t \bar{\eta} = \frac{\overline{\textit{emp}}}{ \bar{\rho}} 
    18751835  - \frac{\mathcal{V}}{\mathcal{A}} \;\frac{\partial_t \bar{\rho} }{\bar{\rho}} 
    1876   \label{eq:ssh_nBq} 
     1836  \label{eq:DIA_ssh_nBq} 
    18771837\end{equation} 
    18781838 
    1879 The first term in equation \autoref{eq:ssh_nBq} alters sea level by adding or subtracting mass from the ocean. 
     1839The first term in equation \autoref{eq:DIA_ssh_nBq} alters sea level by adding or subtracting mass from the ocean. 
    18801840The second term arises from temporal changes in the global mean density; \ie\ from steric effects. 
    18811841 
    18821842In a Boussinesq fluid, $\rho$ is replaced by $\rho_o$ in all the equation except when $\rho$ appears multiplied by 
    18831843the gravity (\ie\ in the hydrostatic balance of the primitive Equations). 
    1884 In particular, the mass conservation equation, \autoref{eq:Co_nBq}, degenerates into the incompressibility equation: 
     1844In particular, the mass conservation equation, \autoref{eq:DIA_Co_nBq}, degenerates into the incompressibility equation: 
    18851845 
    18861846\[ 
    18871847  \frac{1}{e_3} \partial_t ( e_3 ) + \nabla( \textbf{U} ) = \left. \frac{\textit{emp}}{\rho_o \,e_3}\right|_ \textit{surface} 
    1888   % \label{eq:Co_Bq} 
     1848  % \label{eq:DIA_Co_Bq} 
    18891849\] 
    18901850 
     
    18931853\[ 
    18941854  \partial_t \mathcal{V} = \mathcal{A} \;\frac{\overline{\textit{emp}}}{\rho_o} 
    1895   % \label{eq:V_Bq} 
     1855  % \label{eq:DIA_V_Bq} 
    18961856\] 
    18971857 
     
    19121872\begin{equation} 
    19131873  \mathcal{M}_o = \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A} 
    1914   \label{eq:M_Bq} 
     1874  \label{eq:DIA_M_Bq} 
    19151875\end{equation} 
    19161876 
     
    19191879Introducing the total density anomaly, $\mathcal{D}= \int_D d_a \,dv$, 
    19201880where $d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO\ (cf. \autoref{subsec:TRA_eos}) 
    1921 in \autoref{eq:M_Bq} leads to a very simple form for the steric height: 
     1881in \autoref{eq:DIA_M_Bq} leads to a very simple form for the steric height: 
    19221882 
    19231883\begin{equation} 
    19241884  \eta_s = - \frac{1}{\mathcal{A}} \mathcal{D} 
    1925   \label{eq:steric_Bq} 
     1885  \label{eq:DIA_steric_Bq} 
    19261886\end{equation} 
    19271887 
     
    19431903(wetting and drying of grid point is not allowed). 
    19441904 
    1945 Third, the discretisation of \autoref{eq:steric_Bq} depends on the type of free surface which is considered. 
    1946 In the non linear free surface case, \ie\ \np{ln\_linssh}\forcode{ = .true.}, it is given by 
     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 
    19471907 
    19481908\[ 
    19491909  \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} } 
    1950   % \label{eq:discrete_steric_Bq_nfs} 
     1910  % \label{eq:DIA_discrete_steric_Bq_nfs} 
    19511911\] 
    19521912 
     
    19581918  \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 } 
    19591919                  { \sum_{i,\,j,\,k}       e_{1t}e_{2t}e_{3t} + \sum_{i,\,j}       e_{1t}e_{2t} \eta } 
    1960   % \label{eq:discrete_steric_Bq_fs} 
     1920  % \label{eq:DIA_discrete_steric_Bq_fs} 
    19611921\] 
    19621922 
     
    19781938\[ 
    19791939  \eta_s = - \frac{1}{\mathcal{A}} \int_D d_a(T,S_o,p_o) \,dv 
    1980   % \label{eq:thermosteric_Bq} 
     1940  % \label{eq:DIA_thermosteric_Bq} 
    19811941\] 
    19821942 
     
    19851945Both steric and thermosteric sea level are computed in \mdl{diaar5}. 
    19861946 
    1987 % ------------------------------------------------------------------------------------------------------------- 
    1988 %       Other Diagnostics 
    1989 % ------------------------------------------------------------------------------------------------------------- 
    1990 \section[Other diagnostics] 
    1991 {Other diagnostics} 
     1947%% ================================================================================================= 
     1948\section{Other diagnostics} 
    19921949\label{sec:DIA_diag_others} 
    19931950 
     
    19951952The available ready-to-add diagnostics modules can be found in directory DIA. 
    19961953 
    1997 \subsection[Depth of various quantities (\textit{diahth.F90})] 
    1998 {Depth of various quantities (\protect\mdl{diahth})} 
     1954%% ================================================================================================= 
     1955\subsection[Depth of various quantities (\textit{diahth.F90})]{Depth of various quantities (\protect\mdl{diahth})} 
    19991956 
    20001957Among the available diagnostics the following ones are obtained when defining the \key{diahth} CPP key: 
     
    20081965- the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth}) 
    20091966 
    2010  
    2011 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    20121967\begin{figure}[!t] 
    2013   \begin{center} 
    2014     \includegraphics[width=\textwidth]{Fig_mask_subasins} 
    2015     \caption{ 
    2016       \protect\label{fig:mask_subasins} 
    2017       Decomposition of the World Ocean (here ORCA2) into sub-basin used in to 
    2018       compute the heat and salt transports as well as the meridional stream-function: 
    2019       Atlantic basin (red), Pacific basin (green), Indian basin (bleue), Indo-Pacific basin (bleue+green). 
    2020       Note that semi-enclosed seas (Red, Med and Baltic seas) as well as Hudson Bay are removed from the sub-basins. 
    2021       Note also that the Arctic Ocean has been split into Atlantic and Pacific basins along the North fold line. 
    2022     } 
    2023   \end{center} 
     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} 
    20241982\end{figure} 
    2025 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    2026  
    2027 % ----------------------------------------------------------- 
    2028 %       CMIP specific diagnostics 
    2029 % ----------------------------------------------------------- 
    2030 \subsection[CMIP specific diagnostics (\textit{diaar5.F90}, \textit{diaptr.F90})] 
    2031 {CMIP specific diagnostics (\protect\mdl{diaar5})} 
     1983 
     1984%% ================================================================================================= 
     1985\subsection[CMIP specific diagnostics (\textit{diaar5.F90}, \textit{diaptr.F90})]{CMIP specific diagnostics (\protect\mdl{diaar5})} 
    20321986 
    20331987A series of diagnostics has been added in the \mdl{diaar5} and \mdl{diaptr}. 
     
    20391993sea water pressure at sea floor (botpres), dynamic sea surface height (sshdyn). 
    20401994 
    2041 In \mdl{diaptr} when \np{ln\_diaptr}\forcode{ = .true.} 
    2042 (see the \nam{ptr} namelist below) can be computed on-line the poleward heat and salt transports, 
     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, 
    20431997their advective and diffusive component, and the meriodional stream function . 
    2044 When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed for the Atlantic, Indian, 
     1998When \np[=.true.]{ln_subbas}{ln\_subbas}, transports and stream function are computed for the Atlantic, Indian, 
    20451999Pacific and Indo-Pacific Oceans (defined north of 30\deg{S}) as well as for the World Ocean. 
    20462000The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains three 2D mask arrays, 
    2047 the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:mask_subasins}). 
    2048  
    2049 %------------------------------------------namptr----------------------------------------- 
    2050  
    2051 \nlst{namptr} 
    2052 %----------------------------------------------------------------------------------------- 
    2053  
    2054 % ----------------------------------------------------------- 
    2055 %       25 hour mean and hourly Surface, Mid and Bed 
    2056 % ----------------------------------------------------------- 
     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%% ================================================================================================= 
    20572010\subsection{25 hour mean output for tidal models} 
    20582011 
    2059 %------------------------------------------nam_dia25h------------------------------------- 
    2060  
    2061 \nlst{nam_dia25h} 
    2062 %----------------------------------------------------------------------------------------- 
     2012\begin{listing} 
     2013  \nlst{nam_dia25h} 
     2014  \caption{\forcode{&nam_dia25h}} 
     2015  \label{lst:nam_dia25h} 
     2016\end{listing} 
    20632017 
    20642018A module is available to compute a crudely detided M2 signal by obtaining a 25 hour mean. 
     
    20672021This diagnostic is actived with the logical $ln\_dia25h$. 
    20682022 
    2069 % ----------------------------------------------------------- 
    2070 %     Top Middle and Bed hourly output 
    2071 % ----------------------------------------------------------- 
     2023%% ================================================================================================= 
    20722024\subsection{Top middle and bed hourly output} 
    20732025 
    2074 %------------------------------------------nam_diatmb----------------------------------------------------- 
    2075  
    2076 \nlst{nam_diatmb} 
    2077 %---------------------------------------------------------------------------------------------------------- 
     2026\begin{listing} 
     2027  \nlst{nam_diatmb} 
     2028  \caption{\forcode{&nam_diatmb}} 
     2029  \label{lst:nam_diatmb} 
     2030\end{listing} 
    20782031 
    20792032A module is available to output the surface (top), mid water and bed diagnostics of a set of standard variables. 
     
    20832036This diagnostic is actived with the logical $ln\_diatmb$. 
    20842037 
    2085 % ----------------------------------------------------------- 
    2086 %     Courant numbers 
    2087 % ----------------------------------------------------------- 
     2038%% ================================================================================================= 
    20882039\subsection{Courant numbers} 
    20892040 
     
    20932044\[ 
    20942045  C_u = |u|\frac{\rdt}{e_{1u}}, \quad C_v = |v|\frac{\rdt}{e_{2v}}, \quad C_w = |w|\frac{\rdt}{e_{3w}} 
    2095   % \label{eq:CFL} 
     2046  % \label{eq:DIA_CFL} 
    20962047\] 
    20972048 
     
    21022053Values greater than 1 indicate that information is propagated across more than one grid cell in a single time step. 
    21032054 
    2104 The variables can be activated by setting the \np{nn\_diacfl} namelist parameter to 1 in the \nam{ctl} namelist. 
     2055The variables can be activated by setting the \np{nn_diacfl}{nn\_diacfl} namelist parameter to 1 in the \nam{ctl}{ctl} namelist. 
    21052056The diagnostics will be written out to an ascii file named cfl\_diagnostics.ascii. 
    21062057In this file the maximum value of $C_u$, $C_v$, and $C_w$ are printed at each timestep along with the coordinates of 
     
    21102061The maximum values from the run are also copied to the ocean.output file. 
    21112062 
    2112 % ================================================================ 
    2113  
    2114 \biblio 
    2115  
    2116 \pindex 
     2063\onlyinsubfile{\input{../../global/epilogue}} 
    21172064 
    21182065\end{document} 
  • NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/subfiles/chap_DIU.tex

    r11435 r11692  
    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 
     8\thispagestyle{plain} 
     9 
    1110\chaptertoc 
    1211 
     12\paragraph{Changes record} ~\\ 
    1313 
    14 \newpage 
    15 $\ $\newline % force a new line 
     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 
     
    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} 
     
    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 \nam{diu}: 
     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 
     
    5565The 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\onlyinsubfile{\input{../../global/epilogue}} 
    159163 
    160164\end{document} 
  • NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/subfiles/chap_DOM.tex

    r11435 r11692  
    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 %\chaptertoc 
    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 \vfill 
    21  
    22 \begin{table}[b] 
    23   \footnotesize 
    24   \caption*{Changes record} 
    25   \begin{tabularx}{\textwidth}{l||X|X} 
    26     Release & Author(s) & Modifications                                                          \\ 
    27     \hline 
    28     {\em 4.0} & {\em Simon M\"{u}ller \& Andrew Coward} & 
    29     {\em 
    30       Compatibility changes Major simplification has moved many of the options to external domain configuration tools. 
    31       (see \autoref{apdx:DOMAINcfg}) 
    32     }                                                                                            \\ 
    33     {\em 3.x} & {\em Rachid Benshila, Gurvan Madec \& S\'{e}bastien Masson} & 
    34     {\em First version}                                                                          \\ 
     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                                                                    } 
    3541  \end{tabularx} 
    36 \end{table} 
    37  
    38 \newpage 
    39  
    40 Having defined the continuous equations in \autoref{chap:PE} and chosen a time discretisation \autoref{chap:STP}, 
     42} 
     43 
     44\clearpage 
     45 
     46Having defined the continuous equations in \autoref{chap:MB} and 
     47chosen a time discretisation \autoref{chap:TD}, 
    4148we need to choose a grid for spatial discretisation and related numerical algorithms. 
    4249In the present chapter, we provide a general description of the staggered grid used in \NEMO, 
    4350and other relevant information about the DOM (DOMain) source code modules. 
    4451 
    45 % ================================================================ 
    46 % Fundamentals of the Discretisation 
    47 % ================================================================ 
     52%% ================================================================================================= 
    4853\section{Fundamentals of the discretisation} 
    4954\label{sec:DOM_basics} 
    5055 
    51 % ------------------------------------------------------------------------------------------------------------- 
    52 %        Arrangement of Variables 
    53 % ------------------------------------------------------------------------------------------------------------- 
     56%% ================================================================================================= 
    5457\subsection{Arrangement of variables} 
    5558\label{subsec:DOM_cell} 
    5659 
    57 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    58 \begin{figure}[!tb] 
    59   \begin{center} 
    60     \includegraphics[width=\textwidth]{Fig_cell} 
    61     \caption{ 
    62       \protect\label{fig:cell} 
    63       Arrangement of variables. 
    64       $t$ indicates scalar points where temperature, salinity, density, pressure and 
    65       horizontal divergence are defined. 
    66       $(u,v,w)$ indicates vector points, and $f$ indicates vorticity points where both relative and 
    67       planetary vorticities are defined. 
    68     } 
    69   \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} 
    7070\end{figure} 
    71 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    72  
    73 The numerical techniques used to solve the Primitive Equations in this model are based on the traditional, 
    74 centred second-order finite difference approximation. 
     71 
     72The numerical techniques used to solve the Primitive Equations in this model are based on 
     73the traditional, centred second-order finite difference approximation. 
    7574Special attention has been given to the homogeneity of the solution in the three spatial directions. 
    7675The arrangement of variables is the same in all directions. 
    77 It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with vector points $(u, v, w)$ defined in 
    78 the centre of each face of the cells (\autoref{fig:cell}). 
    79 This is the generalisation to three dimensions of the well-known ``C'' grid in Arakawa's classification 
    80 \citep{mesinger.arakawa_bk76}. 
    81 The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge and 
    82 the barotropic stream function $\psi$ is defined at horizontal points overlying the $\zeta$ and $f$-points. 
    83  
    84 The ocean mesh (\ie\ the position of all the scalar and vector points) is defined by the transformation that 
    85 gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 
    86 The grid-points are located at integer or integer and a half value of $(i,j,k)$ as indicated on \autoref{tab:cell}. 
    87 In all the following, subscripts $u$, $v$, $w$, $f$, $uw$, $vw$ or $fw$ indicate the position of 
    88 the grid-point where the scale factors are defined. 
    89 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}. 
    9092As a result, the mesh on which partial derivatives $\pd[]{\lambda}$, $\pd[]{\varphi}$ and 
    9193$\pd[]{z}$ are evaluated is a uniform mesh with a grid size of unity. 
    92 Discrete partial derivatives are formulated by the traditional, centred second order finite difference approximation 
    93 while the scale factors are chosen equal to their local analytical value. 
     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. 
    9497An important point here is that the partial derivative of the scale factors must be evaluated by 
    9598centred finite difference approximation, not from their analytical expression. 
    96 This preserves the symmetry of the discrete set of equations and therefore satisfies many of 
    97 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}). 
    98101A similar, related remark can be made about the domain size: 
    99 when needed, an area, volume, or the total ocean depth must be evaluated as the product or sum of the relevant scale factors 
    100 (see \autoref{eq:DOM_bar} in the next section). 
    101  
    102 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    103 \begin{table}[!tb] 
    104   \begin{center} 
    105     \begin{tabular}{|p{46pt}|p{56pt}|p{56pt}|p{56pt}|} 
    106       \hline 
    107       t  & $i      $ & $j      $ & $k      $ \\ 
    108       \hline 
    109       u  & $i + 1/2$ & $j      $ & $k      $ \\ 
    110       \hline 
    111       v  & $i      $ & $j + 1/2$ & $k      $ \\ 
    112       \hline 
    113       w  & $i      $ & $j      $ & $k + 1/2$ \\ 
    114       \hline 
    115       f  & $i + 1/2$ & $j + 1/2$ & $k      $ \\ 
    116       \hline 
    117       uw & $i + 1/2$ & $j      $ & $k + 1/2$ \\ 
    118       \hline 
    119       vw & $i      $ & $j + 1/2$ & $k + 1/2$ \\ 
    120       \hline 
    121       fw & $i + 1/2$ & $j + 1/2$ & $k + 1/2$ \\ 
    122       \hline 
    123     \end{tabular} 
    124     \caption{ 
    125       \protect\label{tab:cell} 
    126       Location of grid-points as a function of integer or integer and a half value of the column, line or level. 
    127       This indexing is only used for the writing of the semi -discrete equations. 
    128       In the code, the indexing uses integer values only and is positive downwards in the vertical with $k=1$ at the surface. 
    129       (see \autoref{subsec:DOM_Num_Index}) 
    130     } 
    131   \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} 
    132134\end{table} 
    133 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    134135 
    135136Note that the definition of the scale factors 
     
    143144firstly, there is no ambiguity in the scale factors appearing in the discrete equations, 
    144145since they are first introduced in the continuous equations; 
    145 secondly, analytical transformations encourage good practice by the definition of smoothly varying grids 
    146 (rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{treguier.dukowicz.ea_JGR96}. 
    147 An example of the effect of such a choice is shown in \autoref{fig:zgr_e3}. 
    148 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    149 \begin{figure}[!t] 
    150   \begin{center} 
    151     \includegraphics[width=\textwidth]{Fig_zgr_e3} 
    152     \caption{ 
    153       \protect\label{fig:zgr_e3} 
    154       Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical, 
    155       and (b) analytically derived grid-point position and scale factors. 
    156       For both grids here, the same $w$-point depth has been chosen but 
    157       in (a) the $t$-points are set half way between $w$-points while 
    158       in (b) they are defined from an analytical function: 
    159       $z(k) = 5 \, (k - 1/2)^3 - 45 \, (k - 1/2)^2 + 140 \, (k - 1/2) - 150$. 
    160       Note the resulting difference between the value of the grid-size $\Delta_k$ and 
    161       those of the scale factor $e_k$. 
    162     } 
    163   \end{center} 
     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} 
    164164\end{figure} 
    165 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    166  
    167 % ------------------------------------------------------------------------------------------------------------- 
    168 %        Vector Invariant Formulation 
    169 % ------------------------------------------------------------------------------------------------------------- 
     165 
     166%% ================================================================================================= 
    170167\subsection{Discrete operators} 
    171168\label{subsec:DOM_operators} 
    172169 
    173 Given the values of a variable $q$ at adjacent points, the differencing and averaging operators at 
    174 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: 
    175172\begin{alignat*}{2} 
    176   % \label{eq:di_mi} 
     173  % \label{eq:DOM_di_mi} 
    177174  \delta_i [q]      &= &       &q (i + 1/2) - q (i - 1/2) \\ 
    178175  \overline q^{\, i} &= &\big\{ &q (i + 1/2) + q (i - 1/2) \big\} / 2 
     
    180177 
    181178Similar operators are defined with respect to $i + 1/2$, $j$, $j + 1/2$, $k$, and $k + 1/2$. 
    182 Following \autoref{eq:PE_grad} and \autoref{eq:PE_lap}, the gradient of a variable $q$ defined at a $t$-point has 
    183 its three components defined at $u$-, $v$- and $w$-points while its Laplacian is defined at the $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. 
    184183These operators have the following discrete forms in the curvilinear $s$-coordinates system: 
    185 \[ 
     184\begin{gather*} 
    186185  % \label{eq:DOM_grad} 
    187186  \nabla q \equiv   \frac{1}{e_{1u}} \delta_{i + 1/2} [q] \; \, \vect i 
    188187                  + \frac{1}{e_{2v}} \delta_{j + 1/2} [q] \; \, \vect j 
    189                   + \frac{1}{e_{3w}} \delta_{k + 1/2} [q] \; \, \vect k 
    190 \] 
    191 \begin{multline*} 
     188                  + \frac{1}{e_{3w}} \delta_{k + 1/2} [q] \; \, \vect k \\ 
    192189  % \label{eq:DOM_lap} 
    193190  \Delta q \equiv   \frac{1}{e_{1t} \, e_{2t} \, e_{3t}} 
    194191                    \; \lt[   \delta_i \lt( \frac{e_{2u} \, e_{3u}}{e_{1u}} \; \delta_{i + 1/2} [q] \rt) 
    195                             + \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] 
    196193                  + \frac{1}{e_{3t}} 
    197194                              \delta_k \lt[ \frac{1              }{e_{3w}} \; \delta_{k + 1/2} [q] \rt] 
    198 \end{multline*} 
    199  
    200 Following \autoref{eq:PE_curl} and \autoref{eq:PE_div}, a vector $\vect A = (a_1,a_2,a_3)$ defined at 
    201 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 
    202200its divergence defined at $t$-points: 
    203 \begin{multline} 
     201\begin{multline*} 
    204202% \label{eq:DOM_curl} 
    205203  \nabla \times \vect A \equiv   \frac{1}{e_{2v} \, e_{3vw}} 
     
    212210                                 \Big[   \delta_{i + 1/2} (e_{2v} \, a_2) 
    213211                                       - \delta_{j + 1/2} (e_{1u} \, a_1) \Big] \vect k 
    214 \end{multline} 
    215 \begin{equation} 
     212\end{multline*} 
     213\[ 
    216214% \label{eq:DOM_div} 
    217215  \nabla \cdot \vect A \equiv   \frac{1}{e_{1t} \, e_{2t} \, e_{3t}} 
    218216                                \Big[ \delta_i (e_{2u} \, e_{3u} \, a_1) + \delta_j (e_{1v} \, e_{3v} \, a_2) \Big] 
    219217                              + \frac{1}{e_{3t}} \delta_k (a_3) 
    220 \end{equation} 
    221  
    222 The vertical average over the whole water column is denoted by an overbar and is for 
    223 a masked field $q$ (\ie\ a quantity that is equal to zero inside solid areas): 
     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): 
    224222\begin{equation} 
    225223  \label{eq:DOM_bar} 
     
    227225\end{equation} 
    228226where $H_q$  is the ocean depth, which is the masked sum of the vertical scale factors at $q$ points, 
    229 $k^b$ and $k^o$ are the bottom and surface $k$-indices, and the symbol $\sum \limits_k$ refers to a summation over 
    230 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$). 
    231230 
    232231In continuous form, the following properties are satisfied: 
     
    238237\end{gather} 
    239238 
    240 It is straightforward to demonstrate that these properties are verified locally in discrete form as soon as 
    241 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 
    242241vector points $(u,v,w)$. 
    243242 
    244243Let $a$ and $b$ be two fields defined on the mesh, with a value of zero inside continental areas. 
    245 It can be shown that the differencing operators ($\delta_i$, $\delta_j$ and $\delta_k$) 
    246 are skew-symmetric linear operators, and further that the averaging operators $\overline{\cdots}^{\, i}$, 
    247 $\overline{\cdots}^{\, j}$ and $\overline{\cdots}^{\, k}$) are symmetric linear operators, \ie 
    248 \begin{alignat}{4} 
     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} 
    249249  \label{eq:DOM_di_adj} 
    250250  &\sum \limits_i a_i \; \delta_i [b]      &\equiv &- &&\sum \limits_i \delta      _{   i + 1/2} [a] &b_{i + 1/2} \\ 
     
    253253\end{alignat} 
    254254 
    255 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 
    256257$(\overline{\cdots}^{\, i})^* = \overline{\cdots}^{\, i + 1/2}$, respectively. 
    257 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 
    258259demonstrate integral conservative properties of the discrete formulation chosen. 
    259260 
    260 % ------------------------------------------------------------------------------------------------------------- 
    261 %        Numerical Indexing 
    262 % ------------------------------------------------------------------------------------------------------------- 
     261%% ================================================================================================= 
    263262\subsection{Numerical indexing} 
    264263\label{subsec:DOM_Num_Index} 
    265264 
    266 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    267 \begin{figure}[!tb] 
    268   \begin{center} 
    269     \includegraphics[width=\textwidth]{Fig_index_hor} 
    270     \caption{ 
    271       \protect\label{fig:index_hor} 
    272       Horizontal integer indexing used in the \fortran code. 
    273       The dashed area indicates the cell in which variables contained in arrays have the same $i$- and $j$-indices 
    274     } 
    275   \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} 
    276273\end{figure} 
    277 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    278  
    279 The array representation used in the \fortran code requires an integer indexing. 
    280 However, the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with the use of 
    281 integer values for $t$-points only while all the other points involve integer and a half values. 
     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. 
    282279Therefore, a specific integer indexing has been defined for points other than $t$-points 
    283280(\ie\ velocity and vorticity grid-points). 
    284 Furthermore, the direction of the vertical indexing has been reversed and the surface level set at $k = 1$. 
    285  
    286 % ----------------------------------- 
    287 %        Horizontal Indexing 
    288 % ----------------------------------- 
     281Furthermore, the direction of the vertical indexing has been reversed and 
     282the surface level set at $k = 1$. 
     283 
     284%% ================================================================================================= 
    289285\subsubsection{Horizontal indexing} 
    290286\label{subsec:DOM_Num_Index_hor} 
    291287 
    292 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}. 
    293289For an increasing $i$ index ($j$ index), 
    294290the $t$-point and the eastward $u$-point (northward $v$-point) have the same index 
    295 (see the dashed area in \autoref{fig:index_hor}). 
     291(see the dashed area in \autoref{fig:DOM_index_hor}). 
    296292A $t$-point and its nearest north-east $f$-point have the same $i$-and $j$-indices. 
    297293 
    298 % ----------------------------------- 
    299 %        Vertical indexing 
    300 % ----------------------------------- 
     294%% ================================================================================================= 
    301295\subsubsection{Vertical indexing} 
    302296\label{subsec:DOM_Num_Index_vertical} 
    303297 
    304 In the vertical, the chosen indexing requires special attention since the direction of the $k$-axis in 
    305 the \fortran code is the reverse of that used in the semi -discrete equations and 
    306 given in \autoref{subsec:DOM_cell}. 
    307 The sea surface corresponds to the $w$-level $k = 1$, which is the same index as the $t$-level just below 
    308 (\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}). 
    309303The last $w$-level ($k = jpk$) either corresponds to or is below the ocean floor while 
    310 the last $t$-level is always outside the ocean domain (\autoref{fig:index_vert}). 
     304the last $t$-level is always outside the ocean domain (\autoref{fig:DOM_index_vert}). 
    311305Note that a $w$-point and the directly underlaying $t$-point have a common $k$ index 
    312306(\ie\ $t$-points and their nearest $w$-point neighbour in negative index direction), 
    313 in contrast to the indexing on the horizontal plane where the $t$-point has the same index as 
    314 the nearest velocity points in the positive direction of the respective horizontal axis index 
    315 (compare the dashed area in \autoref{fig:index_hor} and \autoref{fig:index_vert}). 
     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}). 
    316311Since the scale factors are chosen to be strictly positive, 
    317 a \textit{minus sign} is included in the \fortran implementations of 
     312a \textit{minus sign} is included in the \fortran\ implementations of 
    318313\textit{all the vertical derivatives} of the discrete equations given in this manual in order to 
    319314accommodate the opposing vertical index directions in implementation and documentation. 
    320315 
    321 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    322 \begin{figure}[!pt] 
    323   \begin{center} 
    324     \includegraphics[width=\textwidth]{Fig_index_vert} 
    325     \caption{ 
    326       \protect\label{fig:index_vert} 
    327       Vertical integer indexing used in the \fortran code. 
    328       Note that the $k$-axis is oriented downward. 
    329       The dashed area indicates the cell in which variables contained in arrays have a common $k$-index. 
    330     } 
    331   \end{center} 
     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} 
    332325\end{figure} 
    333 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    334  
    335 % ------------------------------------------------------------------------------------------------------------- 
    336 %        Domain configuration 
    337 % ------------------------------------------------------------------------------------------------------------- 
     326 
     327%% ================================================================================================= 
    338328\section{Spatial domain configuration} 
    339329\label{subsec:DOM_config} 
    340330 
    341 \nlst{namcfg} 
    342  
    343331Two typical methods are available to specify the spatial domain configuration; 
    344 they can be selected using parameter \np{ln\_read\_cfg} parameter in namelist \nam{cfg}. 
    345  
    346 If \np{ln\_read\_cfg} is set to \forcode{.true.}, 
    347 the domain-specific parameters and fields are read from a netCDF input file, 
    348 whose name (without its .nc suffix) can be specified as the value of the \np{cn\_domcfg} parameter in namelist \nam{cfg}. 
    349  
    350 If \np{ln\_read\_cfg} is set to \forcode{.false.}, 
     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.}, 
    351341the domain-specific parameters and fields can be provided (\eg\ analytically computed) by 
    352342subroutines \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}. 
    353343These subroutines can be supplied in the \path{MY_SRC} directory of the configuration, 
    354 and default versions that configure the spatial domain for the GYRE reference configuration are present in 
    355 the \path{./src/OCE/USR} directory. 
     344and default versions that configure the spatial domain for the GYRE reference configuration are 
     345present in the \path{./src/OCE/USR} directory. 
    356346 
    357347In version 4.0 there are no longer any options for reading complex bathymetries and 
     
    360350to run similar models with and without partial bottom boxes and/or sigma-coordinates, 
    361351supporting such choices leads to overly complex code. 
    362 Worse still is the difficulty of ensuring the model configurations intended to be identical are indeed so when 
    363 the model domain itself can be altered by runtime selections. 
    364 The code previously used to perform vertical discretisation has been incorporated into an external tool 
    365 (\path{./tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMAINcfg}. 
    366  
    367 The next subsections summarise the parameter and fields related to the configuration of the whole model domain. 
    368 These represent the minimum information that must be provided either via the \np{cn\_domcfg} file or set by code 
    369 inserted into user-supplied versions of the \texttt{usrdef\_*} subroutines. 
     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. 
    370362The requirements are presented in three sections: 
    371363the domain size (\autoref{subsec:DOM_size}), the horizontal mesh (\autoref{subsec:DOM_hgr}), 
    372364and the vertical grid (\autoref{subsec:DOM_zgr}). 
    373365 
    374 % ----------------------------------- 
    375 %        Domain Size 
    376 % ----------------------------------- 
     366%% ================================================================================================= 
    377367\subsection{Domain size} 
    378368\label{subsec:DOM_size} 
    379369 
    380 The total size of the computational domain is set by the parameters \jp{jpiglo}, \jp{jpjglo} and \jp{jpkglo} for 
    381 the $i$, $j$ and $k$ directions, respectively. 
    382 Note, that the variables \texttt{jpi} and \texttt{jpj} refer to the size of each processor subdomain when 
    383 the code is run in parallel using domain decomposition (\key{mpp\_mpi} defined, 
    384 see \autoref{sec:LBC_mpp}). 
    385  
    386 The name of the configuration is set through parameter \np{cn\_cfg}, 
    387 and the nominal resolution through parameter \np{nn\_cfg} 
     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} 
    388378(unless in the input file both of variables \texttt{ORCA} and \texttt{ORCA\_index} are present, 
    389 in which case \np{cn\_cfg} and \np{nn\_cfg} are set from these values accordingly). 
     379in which case \np{cn_cfg}{cn\_cfg} and \np{nn_cfg}{nn\_cfg} are set from these values accordingly). 
    390380 
    391381The global lateral boundary condition type is selected from 8 options using parameter \jp{jperio}. 
    392 See \autoref{sec:LBC_jperio} for details on the available options and the corresponding values for \jp{jperio}. 
    393  
    394 % ================================================================ 
    395 % Domain: Horizontal Grid (mesh) 
    396 % ================================================================ 
    397 \subsection{Horizontal grid mesh (\protect\mdl{domhgr})} 
     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})} 
    398387\label{subsec:DOM_hgr} 
    399388 
    400 % ================================================================ 
    401 % Domain: List of hgr-related fields needed 
    402 % ================================================================ 
     389%% ================================================================================================= 
    403390\subsubsection{Required fields} 
    404391\label{sec:DOM_hgr_fields} 
    405392 
    406 The explicit specification of a range of mesh-related fields are required for the definition of a configuration. 
     393The explicit specification of a range of mesh-related fields are required for 
     394the definition of a configuration. 
    407395These include: 
    408396 
    409397\begin{clines} 
    410 int    jpiglo, jpjglo, jpkglo            /* global domain sizes                                          */ 
    411 int    jperio                            /* lateral global domain b.c.                                   */ 
    412 double glamt, glamu, glamv, glamf        /* geographic longitude (t,u,v and f points respectively)      */ 
    413 double gphit, gphiu, gphiv, gphif        /* geographic latitude                                          */ 
    414 double e1t, e1u, e1v, e1f                /* horizontal scale factors                                     */ 
    415 double e2t, e2u, e2v, e2f                /* horizontal scale factors                                     */ 
     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                               */ 
    416404\end{clines} 
    417405 
    418406The values of the geographic longitude and latitude arrays at indices $i,j$ correspond to 
    419407the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$, 
    420 evaluated at the values as specified in \autoref{tab:cell} for the respective grid-point position. 
     408evaluated at the values as specified in \autoref{tab:DOM_cell} for the respective grid-point position. 
    421409The calculation of the values of the horizontal scale factor arrays in general additionally involves 
    422410partial derivatives of $\lambda$ and $\varphi$ with respect to $i$ and $j$, 
    423411evaluated for the same arguments as $\lambda$ and $\varphi$. 
    424412 
     413%% ================================================================================================= 
    425414\subsubsection{Optional fields} 
    426415 
    427416\begin{clines} 
    428                                          /* Optional:                                                    */ 
    429 int    ORCA, ORCA_index                  /* configuration name, configuration resolution                 */ 
    430 double e1e2u, e1e2v                      /* U and V surfaces (if grid size reduction in some straits)    */ 
    431 double ff_f, ff_t                        /* Coriolis parameter (if not on the sphere)                    */ 
     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)                 */ 
    432421\end{clines} 
    433422 
     
    436425This is particularly useful for locations such as Gibraltar or Indonesian Throughflow pinch-points 
    437426(see \autoref{sec:MISC_strait} for illustrated examples). 
    438 The key is to reduce the faces of $T$-cell (\ie\ change the value of the horizontal scale factors at $u$- or $v$-point) but 
     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 
    439429not the volume of the cells. 
    440430Doing otherwise can lead to numerical instability issues. 
    441431In normal operation the surface areas are computed from $e1u * e2u$ and $e1v * e2v$ but 
    442432in cases where a gridsize reduction is required, 
    443 the unaltered surface areas at $u$ and $v$ grid points (\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or 
    444 pre-computed in \mdl{usrdef\_hgr}. 
    445 If these arrays are present in the \np{cn\_domcfg} file they are read and the internal computation is suppressed. 
    446 Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{e1e2u} and \texttt{e1e2v} should set 
    447 the surface-area computation flag: 
     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: 
    448439\texttt{ie1e2u\_v} to a non-zero value to suppress their re-computation. 
    449440 
    450441\smallskip 
    451442Similar logic applies to the other optional fields: 
    452 \texttt{ff\_f} and \texttt{ff\_t} which can be used to provide the Coriolis parameter at F- and T-points respectively if 
    453 the mesh is not on a sphere. 
    454 If present these fields will be read and used and the normal calculation ($2 * \Omega * \sin(\varphi)$) suppressed. 
    455 Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{ff\_f} and \texttt{ff\_t} should set 
    456 the Coriolis computation flag: 
     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: 
    457449\texttt{iff} to a non-zero value to suppress their re-computation. 
    458450 
    459 Note that longitudes, latitudes, and scale factors at $w$ points are exactly equal to those of $t$ points, 
    460 thus no specific arrays are defined at $w$ points. 
    461  
    462  
    463 % ================================================================ 
    464 % Domain: Vertical Grid (domzgr) 
    465 % ================================================================ 
    466 \subsection[Vertical grid (\textit{domzgr.F90})] 
    467 {Vertical grid (\protect\mdl{domzgr})} 
     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})} 
    468456\label{subsec:DOM_zgr} 
    469 %-----------------------------------------namdom------------------------------------------- 
    470 \nlst{namdom} 
    471 %------------------------------------------------------------------------------------------------------------- 
     457 
     458\begin{listing} 
     459  \nlst{namdom} 
     460  \caption{\forcode{&namdom}} 
     461  \label{lst:namdom} 
     462\end{listing} 
    472463 
    473464In the vertical, the model mesh is determined by four things: 
    474465\begin{enumerate} 
    475   \item the bathymetry given in meters; 
    476   \item the number of levels of the model (\jp{jpk}); 
    477   \item the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and 
    478   \item the masking system, \ie\ the number of wet model levels at each 
    479 $(i,j)$ location of the horizontal grid. 
     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. 
    480472\end{enumerate} 
    481473 
    482 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    483 \begin{figure}[!tb] 
    484   \begin{center} 
    485     \includegraphics[width=\textwidth]{Fig_z_zps_s_sps} 
    486     \caption{ 
    487       \protect\label{fig:z_zps_s_sps} 
    488       The ocean bottom as seen by the model: 
    489       (a) $z$-coordinate with full step, 
    490       (b) $z$-coordinate with partial step, 
    491       (c) $s$-coordinate: terrain following representation, 
    492       (d) hybrid $s-z$ coordinate, 
    493       (e) hybrid $s-z$ coordinate with partial step, and 
    494       (f) same as (e) but in the non-linear free surface (\protect\np{ln\_linssh}\forcode{ = .false.}). 
    495       Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e). 
    496     } 
    497   \end{center} 
     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} 
    498490\end{figure} 
    499 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    500491 
    501492The choice of a vertical coordinate is made when setting up the configuration; 
    502493it is not intended to be an option which can be changed in the middle of an experiment. 
    503494The one exception to this statement being the choice of linear or non-linear free surface. 
    504 In v4.0 the linear free surface option is implemented as a special case of the non-linear free surface. 
     495In v4.0 the linear free surface option is implemented as 
     496a special case of the non-linear free surface. 
    505497This is computationally wasteful since it uses the structures for time-varying 3D metrics 
    506498for fields that (in the linear free surface case) are fixed. 
    507 However, the linear free-surface is rarely used and implementing it this way means 
    508 a single configuration file can support both options. 
    509  
    510 By default a non-linear free surface is used (\np{ln\_linssh} set to \forcode{ = .false.} in \nam{dom}): 
    511 the coordinate follow the time-variation of the free surface so that the transformation is time dependent: 
    512 $z(i,j,k,t)$ (\eg\ \autoref{fig:z_zps_s_sps}f). 
    513 When a linear free surface is assumed (\np{ln\_linssh} set to \forcode{ = .true.} in \nam{dom}), 
    514 the vertical coordinates are fixed in time, but the seawater can move up and down across the $z_0$ surface 
     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 
    515510(in other words, the top of the ocean in not a rigid lid). 
    516511 
    517512Note that settings: 
    518 \np{ln\_zco}, \np{ln\_zps}, \np{ln\_sco} and \np{ln\_isfcav} mentioned in the following sections 
    519 appear to be namelist options but they are no longer truly namelist options for \NEMO. 
     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. 
    520516Their value is written to and read from the domain configuration file and 
    521517they should be treated as fixed parameters for a particular configuration. 
    522 They are namelist options for the \texttt{DOMAINcfg} tool that can be used to build the configuration file and 
    523 serve both to provide a record of the choices made whilst building the configuration and 
    524 to trigger appropriate code blocks within \NEMO. 
    525 These values should not be altered in the \np{cn\_domcfg} file. 
     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. 
    526522 
    527523\medskip 
    528 The decision on these choices must be made when the \np{cn\_domcfg} file is constructed. 
    529 Three main choices are offered (\autoref{fig:z_zps_s_sps}a-c): 
     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): 
    530526 
    531527\begin{itemize} 
    532 \item $z$-coordinate with full step bathymetry (\np{ln\_zco}\forcode{ = .true.}), 
    533 \item $z$-coordinate with partial step ($zps$) bathymetry (\np{ln\_zps}\forcode{ = .true.}), 
    534 \item Generalized, $s$-coordinate (\np{ln\_sco}\forcode{ = .true.}). 
     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}). 
    535531\end{itemize} 
    536532 
    537533Additionally, hybrid combinations of the three main coordinates are available: 
    538 $s-z$ or $s-zps$ coordinate (\autoref{fig:z_zps_s_sps}d and \autoref{fig:z_zps_s_sps}e). 
     534$s-z$ or $s-zps$ coordinate (\autoref{fig:DOM_z_zps_s_sps}d and \autoref{fig:DOM_z_zps_s_sps}e). 
    539535 
    540536A further choice related to vertical coordinate concerns 
    541537the presence (or not) of ocean cavities beneath ice shelves within the model domain. 
    542 A setting of \np{ln\_isfcav} as \forcode{.true.} indicates that the domain contains ocean cavities, 
     538A setting of \np{ln_isfcav}{ln\_isfcav} as \forcode{.true.} indicates that 
     539the domain contains ocean cavities, 
    543540otherwise the top, wet layer of the ocean will always be at the ocean surface. 
    544541This option is currently only available for $z$- or $zps$-coordinates. 
    545542In the latter case, partial steps are also applied at the ocean/ice shelf interface. 
    546543 
    547 Within the model, the arrays describing the grid point depths and vertical scale factors are three set of 
    548 three dimensional arrays $(i,j,k)$ defined at \textit{before}, \textit{now} and \textit{after} time step. 
     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. 
    549548The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively. 
    550549They are updated at each model time step. 
    551550The initial fixed reference coordinate system is held in variable names with a $\_0$ suffix. 
    552 When the linear free surface option is used (\np{ln\_linssh}\forcode{ = .true.}), 
     551When the linear free surface option is used (\np[=.true.]{ln_linssh}{ln\_linssh}), 
    553552\textit{before}, \textit{now} and \textit{after} arrays are initially set to 
    554553their reference counterpart and remain fixed. 
    555554 
     555%% ================================================================================================= 
    556556\subsubsection{Required fields} 
    557557\label{sec:DOM_zgr_fields} 
     
    572572\end{clines} 
    573573 
    574 This set of vertical metrics is sufficient to describe the initial depth and thickness of every gridcell in 
    575 the model regardless of the choice of vertical coordinate. 
     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. 
    576576With constant z-levels, e3 metrics will be uniform across each horizontal level. 
    577577In the partial step case each e3 at the \jp{bottom\_level} 
     
    579579may vary from its horizontal neighbours. 
    580580And, in s-coordinates, variations can occur throughout the water column. 
    581 With the non-linear free-surface, all the coordinates behave more like the s-coordinate in 
    582 that variations occur throughout the water column with displacements related to the sea surface height. 
     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. 
    583583These variations are typically much smaller than those arising from bottom fitted coordinates. 
    584584The values for vertical metrics supplied in the domain configuration file can be considered as 
    585585those arising from a flat sea surface with zero elevation. 
    586586 
    587 The \jp{bottom\_level} and \jp{top\_level} 2D arrays define the \jp{bottom\_level} and top wet levels in each grid column. 
     587The \jp{bottom\_level} and \jp{top\_level} 2D arrays define 
     588the \jp{bottom\_level} and top wet levels in each grid column. 
    588589Without ice cavities, \jp{top\_level} is essentially a land mask (0 on land; 1 everywhere else). 
    589590With ice cavities, \jp{top\_level} determines the first wet point below the overlying ice shelf. 
    590591 
    591  
    592 % ------------------------------------------------------------------------------------------------------------- 
    593 %        level bathymetry and mask 
    594 % ------------------------------------------------------------------------------------------------------------- 
     592%% ================================================================================================= 
    595593\subsubsection{Level bathymetry and mask} 
    596594\label{subsec:DOM_msk} 
    597595 
    598  
    599596From \jp{top\_level} and \jp{bottom\_level} fields, the mask fields are defined as follows: 
    600 \begin{alignat*}{2} 
    601   tmask(i,j,k) &= &  & 
    602     \begin{cases} 
    603                   0 &\text{if $                  k  <    top\_level(i,j)$} \\ 
    604                   1 &\text{if $bottom\_level(i,j) \leq k \leq   top\_level(i,j)$} \\ 
    605                   0 &\text{if $                  k  >     bottom\_level(i,j)$} 
    606     \end{cases} 
    607   \\ 
    608   umask(i,j,k) &= &  &tmask(i,j,k) * tmask(i + 1,j,    k) \\ 
    609   vmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i    ,j + 1,k) \\ 
    610   fmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i + 1,j,    k) \\ 
    611                &  &* &tmask(i,j,k) * tmask(i + 1,j,    k) \\ 
    612   wmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i    ,j,k - 1) \\ 
    613   \text{with~} wmask(i,j,1) &= & &tmask(i,j,1) 
    614 \end{alignat*} 
     597\begin{align*} 
     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) 
     609\end{align*} 
    615610 
    616611Note that, without ice shelves cavities, 
    617 masks at $t-$ and $w-$points are identical with the numerical indexing used (\autoref{subsec:DOM_Num_Index}). 
    618 Nevertheless, $wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface) 
     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) 
    619616exactly in the same way as for the bottom boundary. 
    620617 
     
    625622%% (see \autoref{fig:LBC_jperio}). 
    626623 
    627  
    628 %------------------------------------------------------------------------------------------------- 
    629624%        Closed seas 
    630 %------------------------------------------------------------------------------------------------- 
    631 \subsection{Closed seas} \label{subsec:DOM_closea} 
    632  
    633 When a global ocean is coupled to an atmospheric model it is better to represent all large water bodies 
    634 (\eg\ Great Lakes, Caspian sea \dots) even if the model resolution does not allow their communication with 
    635 the rest of the ocean. 
     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. 
    636632This is unnecessary when the ocean is forced by fixed atmospheric conditions, 
    637633so these seas can be removed from the ocean domain. 
    638 The user has the option to set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}) and 
    639 to optionally decide on the fate of any freshwater imbalance over the area. 
    640 The options are explained in \autoref{sec:MISC_closea} but it should be noted here that 
    641 a successful use of these options requires appropriate mask fields to be present in the domain configuration file. 
     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. 
    642640Among the possibilities are: 
    643641 
    644642\begin{clines} 
    645 int    closea_mask          /* non-zero values in closed sea areas for optional masking                  */ 
    646 int    closea_mask_rnf      /* non-zero values in closed sea areas with runoff locations (precip only)  */ 
    647 int    closea_mask_emp      /* non-zero values in closed sea areas with runoff locations (total emp)     */ 
     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)   */ 
    648646\end{clines} 
    649647 
    650 % ------------------------------------------------------------------------------------------------------------- 
    651 %        Grid files 
    652 % ------------------------------------------------------------------------------------------------------------- 
     648%% ================================================================================================= 
    653649\subsection{Output grid files} 
    654650\label{subsec:DOM_meshmask} 
    655651 
    656 \nlst{namcfg} 
    657  
    658652Most of the arrays relating to a particular ocean model configuration discussed in this chapter 
    659 (grid-point position, scale factors) 
    660 can be saved in a file if 
    661 namelist parameter \np{ln\_write\_cfg} (namelist \nam{cfg}) is set to \forcode{.true.}; 
    662 the output filename is set through parameter \np{cn\_domcfg\_out}. 
     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}. 
    663657This is only really useful if 
    664658the fields are computed in subroutines \mdl{usrdef\_hgr} or \mdl{usrdef\_zgr} and 
    665659checking or confirmation is required. 
    666660 
    667 \nlst{namdom} 
    668  
    669661Alternatively, all the arrays relating to a particular ocean model configuration 
    670 (grid-point position, scale factors, depths and masks) 
    671 can be saved in a file called \texttt{mesh\_mask} if 
    672 namelist parameter \np{ln\_meshmask} (namelist \nam{dom}) is set to \forcode{.true.}. 
     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.}. 
    673666This file contains additional fields that can be useful for post-processing applications. 
    674667 
    675 % ================================================================ 
    676 % Domain: Initial State (dtatsd & istate) 
    677 % ================================================================ 
    678 \section[Initial state (\textit{istate.F90} and \textit{dtatsd.F90})] 
    679 {Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})} 
    680 \label{sec:DTA_tsd} 
    681 %-----------------------------------------namtsd------------------------------------------- 
    682 \nlst{namtsd} 
    683 %------------------------------------------------------------------------------------------ 
    684  
    685 Basic initial state options are defined in \nam{tsd}. 
     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}. 
    686679By default, the ocean starts from rest (the velocity field is set to zero) and 
    687 the initialization of temperature and salinity fields is controlled through the \np{ln\_tsd\_init} namelist parameter. 
     680the initialization of temperature and salinity fields is controlled through the \np{ln_tsd_init}{ln\_tsd\_init} namelist parameter. 
    688681 
    689682\begin{description} 
    690 \item[\np{ln\_tsd\_init}\forcode{= .true.}] 
    691   Use T and S input files that can be given on the model grid itself or on their native input data grids. 
    692   In the latter case, the data will be interpolated on-the-fly both in the horizontal and the vertical to the model 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. 
     685  In the latter case, 
     686  the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid 
    693687  (see \autoref{subsec:SBC_iof}). 
    694   The information relating to the input files are specified 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. 
    695690  The computation is done in the \mdl{dtatsd} module. 
    696 \item[\np{ln\_tsd\_init}\forcode{= .false.}] 
    697   Initial values for T and S are set via a user supplied \rou{usr\_def\_istate} routine contained in \mdl{userdef\_istate}. 
     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}. 
    698693  The default version sets horizontally uniform T and profiles as used in the GYRE configuration 
    699   (see \autoref{sec:CFG_gyre}). 
     694  (see \autoref{sec:CFGS_gyre}). 
    700695\end{description} 
    701696 
    702 \biblio 
    703  
    704 \pindex 
     697\onlyinsubfile{\input{../../global/epilogue}} 
    705698 
    706699\end{document} 
  • NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/subfiles/chap_DYN.tex

    r11435 r11692  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter ——— Ocean Dynamics (DYN) 
    6 % ================================================================ 
     4 
    75\chapter{Ocean Dynamics (DYN)} 
    86\label{chap:DYN} 
    97 
     8\thispagestyle{plain} 
     9 
    1010\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}, 
     
    5267Furthermore, the tendency terms associated with the 2D barotropic vorticity balance (when \texttt{trdvor?} is defined) 
    5368can be derived from the 3D terms. 
    54 %%% 
    5569\gmcomment{STEVEN: not quite sure I've got the sense of the last sentence. does 
    5670MISC correspond to "extracting tendency terms" or "vorticity balance"?} 
    5771 
    58 % ================================================================ 
    59 % Sea Surface Height evolution & Diagnostics variables 
    60 % ================================================================ 
     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 
    7180The vorticity is defined at an $f$-point (\ie\ corner point) as follows: 
    7281\begin{equation} 
    73   \label{eq:divcur_cur} 
     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) 
     
    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] 
     
    99108the nonlinear advection and of the vertical velocity respectively. 
    100109 
    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})} 
     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} 
     
    123129\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} 
     
    148154re-orientated downward. 
    149155\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. 
     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} 
     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} 
    160166(see \autoref{subsec:DOM_Num_Index_vertical}). 
    161167 
    162  
    163 % ================================================================ 
    164 % Coriolis and Advection terms: vector invariant form 
    165 % ================================================================ 
     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 
    174179applications of the \NEMO\ ocean model. 
    175180The flux form option (see next section) has been present since version $2$. 
    176 Options are defined through the \nam{dyn\_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, 
    178183\ie\ the velocity appearing in these expressions is centred in time (\textit{now} velocity). 
     
    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 \nam{dyn\_vor} namelist variables. 
    194 Four discretisations of the vorticity term (\texttt{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 
     
    216218It is given by: 
    217219\begin{equation} 
    218   \label{eq:dynvor_ens} 
     220  \label{eq:DYN_vor_ens} 
    219221  \left\{ 
    220222    \begin{aligned} 
     
    227229\end{equation} 
    228230 
    229 %------------------------------------------------------------- 
    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} 
     
    248248\end{equation} 
    249249 
    250 %------------------------------------------------------------- 
    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 
     
    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}). 
     295\citep{griffies.gnanadesikan.ea_JPO98} for the discretization of the iso-neutral diffusion operator (see \autoref{apdx:INVARIANTS}). 
    300296 
    301297The \citet{arakawa.hsu_MWR90} vorticity advection scheme for a single layer is modified 
     
    303299First consider the discrete expression of the potential vorticity, $q$, defined at an $f$-point: 
    304300\[ 
    305   % \label{eq:pot_vor} 
     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}), 
     304where the relative vorticity is defined by (\autoref{eq:DYN_divcur_cur}), 
    309305the Coriolis parameter is given by $f=2 \,\Omega \;\sin \varphi _f $ and the layer thickness at $f$-points is: 
    310306\begin{equation} 
    311   \label{eq:een_e3f} 
     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. 
     
    340332(\autoref{fig:DYN_een_triad}): 
    341333\begin{equation} 
    342   \label{eq:Q_triads} 
     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) 
     
    348340Finally, the vorticity terms are represented as: 
    349341\begin{equation} 
    350   \label{eq:dynvor_een} 
     342  \label{eq:DYN_vor_een} 
    351343  \left\{ { 
    352344      \begin{aligned} 
     
    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}. 
     
    368360leading to a larger topostrophy of the flow \citep{barnier.madec.ea_OD06, penduff.le-sommer.ea_OS07}. 
    369361 
    370 %-------------------------------------------------------------------------------------------------------------- 
    371 %           Kinetic Energy Gradient term 
    372 %-------------------------------------------------------------------------------------------------------------- 
    373 \subsection[Kinetic energy gradient term (\textit{dynkeg.F90})] 
    374 {Kinetic energy gradient term (\protect\mdl{dynkeg})} 
     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. 
    414400This 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 \nam{dyn\_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, 
     
    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 
     
    447422It 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] 
     
    453428\end{multline*} 
    454429 
    455 Any of the (\autoref{eq:dynvor_ens}), (\autoref{eq:dynvor_ene}) and (\autoref{eq:dynvor_een}) schemes can be used to 
     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. 
     432However, the energy-conserving scheme (\autoref{eq:DYN_vor_een}) has exclusively been used to date. 
    458433This term is evaluated using a leapfrog scheme, \ie\ the velocity is centred in time (\textit{now} velocity). 
    459434 
    460 %-------------------------------------------------------------------------------------------------------------- 
    461 %           Flux form Advection term 
    462 %-------------------------------------------------------------------------------------------------------------- 
    463 \subsection[Flux form advection term (\textit{dynadv.F90})] 
    464 {Flux form advection term (\protect\mdl{dynadv})} 
     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 
    491463$u$ and $v$ at the centre of each face of $u$- and $v$-cells, \ie\ at the $T$-, $f$-, 
    492464and $uw$-points for $u$ and at the $f$-, $T$- and $vw$-points for $v$. 
    493465 
    494 %------------------------------------------------------------- 
    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} 
     
    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} 
     
    542510But the amplitudes of the false extrema are significantly reduced over those in the centred second order method. 
    543511As 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.}), 
     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. 
    548516In 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. 
     517$u_{vw}^{ubs}$ in \autoref{eq:DYN_adv_cen2} are used. 
    550518UBS is diffusive and is associated with vertical mixing of momentum. \gmcomment{ 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 %%% 
    569536\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})} 
     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 \nam{dyn\_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, 
     
    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} 
     
    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} 
     
    633595\end{equation} 
    634596 
    635 Note that the $1/2$ factor in (\autoref{eq:dynhpg_zco_surf}) is adequate because of the definition of $e_{3w}$ as 
     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$). 
    637599Note also that in case of variable volume level (\texttt{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.})} 
     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 
     
    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} 
     
    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} 
     
    686643 
    687644Where the first term is the pressure gradient along coordinates, 
    688 computed as in \autoref{eq:dynhpg_zco_surf} - \autoref{eq:dynhpg_zco}, 
     645computed as in \autoref{eq:DYN_hpg_zco_surf} - \autoref{eq:DYN_hpg_zco}, 
    689646and $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}$). 
    691648 
    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.}) 
     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}) 
    696653 
    697654$\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 
     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 
    701658(\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 \texttt{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 
     683The pressure gradient due to ocean load is computed using the expression \autoref{eq:DYN_hpg_sco} described in 
    725684\autoref{subsec:DYN_hpg_sco}. 
    726685 
    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\}}.)} 
     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 
     
    745701rather than at the central time level $t$ only, as in the standard leapfrog scheme. 
    746702 
    747 $\bullet$ leapfrog scheme (\np{ln\_dynhpg\_imp}\forcode{ = .true.}): 
    748  
    749 \begin{equation} 
    750   \label{eq:dynhpg_lf} 
     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 \nam{dyn\_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 
    803758the variable volume case (nonlinear free surface, \texttt{vvl?} is defined). 
    804 In the linear free surface case (\autoref{subsec:PE_free_surface}) 
     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}). 
     761while they are time-dependent in the nonlinear case (\autoref{subsec:MB_free_surface}). 
    807762With 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. 
    809764Two 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?}), 
     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. 
    812767The 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; 
     
    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{ln\_dynspg\_exp}\forcode{ = .true.})] 
    832 {Explicit free surface (\protect\np{ln\_dynspg\_exp}\forcode{ = .true.})} 
     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 (\np{ln\_dynspg\_exp} set to true), 
     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). 
     
    839789is thus simply given by : 
    840790\begin{equation} 
    841   \label{eq:dynspg_exp} 
     791  \label{eq:DYN_spg_exp} 
    842792  \left\{ 
    843793    \begin{aligned} 
     
    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{ln\_dynspg\_ts}\forcode{ = .true.})] 
    859 {Split-explicit free surface (\protect\np{ln\_dynspg\_ts}\forcode{ = .true.})} 
     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\ (\np{ln\_dynspg\_ts} set to true), 
     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}. 
     
    901844(see their figure 12, lower left). 
    902845 
    903 %>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   > 
    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. 
     
    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, 
    967907\ie\ they are not re-initialized when starting a new sub-stepping sequence. 
     
    975915it is still significant as shown by \citet{levier.treguier.ea_rpt07} in the case of an analytical barotropic Kelvin wave. 
    976916 
    977 %>>>>>=============== 
    978917\gmcomment{               %%% copy from griffies Book 
    979918 
     
    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{dynspg\_flt?})] 
    1104 {Filtered free surface (\protect\texttt{dynspg\_flt?})} 
     1036%% ================================================================================================= 
     1037\subsection{Filtered free surface (\forcode{dynspg_flt?})} 
    11051038\label{subsec:DYN_spg_fltp} 
    11061039 
    11071040The 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. 
     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 
     
    11121045\gmcomment{               %%% 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}. 
     1055  non-linear and viscous terms in \autoref{eq:MB_dyn}. 
    11231056}   %end gmcomment 
    11241057 
     
    11271060It is computed once and for all and applies to all ocean time steps. 
    11281061 
    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})} 
     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 \nam{dyn\_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; 
     
    11451077\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, 
     
    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 
    11711102For lateral iso-level diffusion, the discrete operator is: 
    11721103\begin{equation} 
    1173   \label{eq:dynldf_lap} 
     1104  \label{eq:DYN_ldf_lap} 
    11741105  \left\{ 
    11751106    \begin{aligned} 
     
    11841115\end{equation} 
    11851116 
    1186 As explained in \autoref{subsec:PE_ldf}, 
     1117As explained in \autoref{subsec:MB_ldf}, 
    11871118this formulation (as the gradient of a divergence and curl of the vorticity) preserves symmetry and 
    11881119ensures a complete separation between the vorticity and divergence parts of the momentum diffusion. 
    11891120 
    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.})} 
     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} } \\ 
     
    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 %%% 
    12611185\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})} 
     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 \nam{zdf} 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 } 
     
    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} 
     
    13281242three other forcings may enter the dynamical equations by affecting the surface pressure gradient. 
    13291243 
    1330 (1) When \np{ln\_apr\_dyn}\forcode{ = .true.} (see \autoref{sec:SBC_apr}), 
     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 
     1250(3) When \np[=2]{nn_ice_embd}{nn\_ice\_embd} and LIM or CICE is used 
    13371251(\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  
    13411254\gmcomment{ 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) 
     
    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 \np{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 \np{ln\_wd\_dl\_ramp}\forcode{ = .false.} then zuwdmask is 1 when the 
    1412 flux is from a cell with water depth greater than \np{rn\_wdmin1} and 0 otherwise. If the user sets 
    1413 \np{ln\_wd\_dl\_ramp}\forcode{ = .true.} the flux across the face is ramped down as the water depth decreases 
    1414 from 2 * \np{rn\_wdmin1} to \np{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 \np{ln\_wd\_dl\_bc}\forcode{ = .true.}, the 
     1343to equal their mean value during the barotropic steps. If the user sets \np[=.true.]{ln_wd_dl_bc}{ln\_wd\_dl\_bc}, the 
    14311344baroclinic velocities are also multiplied by a suitably weighted average of zuwdmask. 
    14321345 
    1433 %----------------------------------------------------------------------------------------- 
    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 \nam{dom} 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}) 
    16531560in the variable volume case (\texttt{vvl?} defined), 
    1654 where it has to be applied to the thickness weighted velocity (see \autoref{sec:A_momentum}) 
     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.} ; \texttt{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.} ; \texttt{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\onlyinsubfile{\input{../../global/epilogue}} 
    16951599 
    16961600\end{document} 
  • NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/subfiles/chap_LBC.tex

    r11445 r11692  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter — Lateral Boundary Condition (LBC) 
    6 % ================================================================ 
     4 
    75\chapter{Lateral Boundary Condition (LBC)} 
    86\label{chap:LBC} 
    97 
     8\thispagestyle{plain} 
     9 
    1010\chaptertoc 
    1111 
    12 \newpage 
     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 
    1326 
    1427%gm% add here introduction to this chapter 
    1528 
    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})} 
     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 %-------------------------------------------------------------------------------------------------------------- 
     32 
     33\begin{listing} 
     34  \nlst{namlbc} 
     35  \caption{\forcode{&namlbc}} 
     36  \label{lst:namlbc} 
     37\end{listing} 
    2638 
    2739%The lateral ocean boundary conditions contiguous to coastlines are Neumann conditions for heat and salt 
     
    4052%The process of defining which areas are to be masked is described in \autoref{subsec:DOM_msk}. 
    4153 
    42 Options are defined through the \nam{lbc} namelist variables. 
     54Options are defined through the \nam{lbc}{lbc} namelist variables. 
    4355The discrete representation of a domain with complex boundaries (coastlines and bottom topography) leads to 
    4456arrays that include large portions where a computation is not required as the model variables remain at zero. 
     
    5769 
    5870\[ 
    59   % \label{eq:lbc_aaaa} 
     71  % \label{eq:LBC_aaaa} 
    6072  \frac{A^{lT} }{e_1 }\frac{\partial T}{\partial i}\equiv \frac{A_u^{lT} 
    6173  }{e_{1u} } \; \delta_{i+1 / 2} \left[ T \right]\;\;mask_u 
     
    6577(normal velocity $u$ remains zero at the coast) (\autoref{fig:LBC_uv}). 
    6678 
    67 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    6879\begin{figure}[!t] 
    69   \begin{center} 
    70     \includegraphics[width=\textwidth]{Fig_LBC_uv} 
    71     \caption{ 
    72       \protect\label{fig:LBC_uv} 
    73       Lateral boundary (thick line) at T-level. 
    74       The velocity normal to the boundary is set to zero. 
    75     } 
    76   \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} 
    7786\end{figure} 
    78 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    7987 
    8088For momentum the situation is a bit more complex as two boundary conditions must be provided along the coast 
     
    9098and is required in order to compute the vorticity at the coast. 
    9199Four different types of lateral boundary condition are available, 
    92 controlled by the value of the \np{rn\_shlat} namelist parameter 
     100controlled by the value of the \np{rn_shlat}{rn\_shlat} namelist parameter 
    93101(The value of the mask$_{f}$ array along the coastline is set equal to this parameter). 
    94102These are: 
    95103 
    96 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    97104\begin{figure}[!p] 
    98   \begin{center} 
    99     \includegraphics[width=\textwidth]{Fig_LBC_shlat} 
    100     \caption{ 
    101       \protect\label{fig:LBC_shlat} 
    102       lateral boundary condition 
    103       (a) free-slip ($rn\_shlat=0$); 
    104       (b) no-slip ($rn\_shlat=2$); 
    105       (c) "partial" free-slip ($0<rn\_shlat<2$) and 
    106       (d) "strong" no-slip ($2<rn\_shlat$). 
    107       Implied "ghost" velocity inside land area is display in grey. 
    108     } 
    109   \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} 
    110115\end{figure} 
    111 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    112116 
    113117\begin{description} 
    114118 
    115 \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 
    116120  the coastline is equal to the offshore velocity, 
    117121  \ie\ the normal derivative of the tangential velocity is zero at the coast, 
     
    119123  (\autoref{fig:LBC_shlat}-a). 
    120124 
    121 \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. 
    122126  Assuming that the tangential velocity decreases linearly from 
    123127  the closest ocean velocity grid point to the coastline, 
     
    134138  the no-slip boundary condition, simply by multiplying it by the mask$_{f}$ : 
    135139  \[ 
    136     % \label{eq:lbc_bbbb} 
     140    % \label{eq:LBC_bbbb} 
    137141    \zeta \equiv \frac{1}{e_{1f} {\kern 1pt}e_{2f} }\left( {\delta_{i+1/2} 
    138142        \left[ {e_{2v} \,v} \right]-\delta_{j+1/2} \left[ {e_{1u} \,u} \right]} 
     
    140144  \] 
    141145 
    142 \item["partial" free-slip boundary condition (0$<$\np{rn\_shlat}$<$2):] the tangential velocity at 
     146\item ["partial" free-slip boundary condition (0$<$\np{rn_shlat}{rn\_shlat}$<$2)] the tangential velocity at 
    143147  the coastline is smaller than the offshore velocity, \ie\ there is a lateral friction but 
    144148  not strong enough to make the tangential velocity at the coast vanish (\autoref{fig:LBC_shlat}-c). 
    145149  This can be selected by providing a value of mask$_{f}$ strictly inbetween $0$ and $2$. 
    146150 
    147 \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 
    148152  be smaller than half the grid size (\autoref{fig:LBC_shlat}-d). 
    149153  The friction is thus larger than in the no-slip case. 
     
    155159it is only applied next to the coast where the minimum water depth can be quite shallow. 
    156160 
    157  
    158 % ================================================================ 
    159 % Boundary Condition around the Model Domain 
    160 % ================================================================ 
    161 \section[Model domain boundary condition (\texttt{jperio})] 
    162 {Model domain boundary condition (\protect\jp{jperio})} 
     161%% ================================================================================================= 
     162\section[Model domain boundary condition (\forcode{jperio})]{Model domain boundary condition (\protect\jp{jperio})} 
    163163\label{sec:LBC_jperio} 
    164164 
     
    168168The north-fold boundary condition is associated with the 3-pole ORCA mesh. 
    169169 
    170 % ------------------------------------------------------------------------------------------------------------- 
    171 %        Closed, cyclic (\jp{jperio}\forcode{ = 0..2}) 
    172 % ------------------------------------------------------------------------------------------------------------- 
    173 \subsection[Closed, cyclic (\forcode{jperio = [0127]})] 
    174 {Closed, cyclic (\protect\jp{jperio}\forcode{ = [0127]})} 
     170%% ================================================================================================= 
     171\subsection[Closed, cyclic (\forcode{=0,1,2,7})]{Closed, cyclic (\protect\jp{jperio}\forcode{=0,1,2,7})} 
    175172\label{subsec:LBC_jperio012} 
    176173 
    177174The choice of closed or cyclic model domain boundary condition is made by 
    178 setting \jp{jperio} to 0, 1, 2 or 7 in namelist \nam{cfg}. 
     175setting \jp{jperio} to 0, 1, 2 or 7 in namelist \nam{cfg}{cfg}. 
    179176Each time such a boundary condition is needed, it is set by a call to routine \mdl{lbclnk}. 
    180177The computation of momentum and tracer trends proceeds from $i=2$ to $i=jpi-1$ and from $j=2$ to $j=jpj-1$, 
     
    185182\begin{description} 
    186183 
    187 \item[For closed boundary (\jp{jperio}\forcode{ = 0})], 
    188   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: 
    189185  first and last rows and columns are set to zero. 
    190186 
    191 \item[For cyclic east-west boundary (\jp{jperio}\forcode{ = 1})], 
    192   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 
    193188  the value of the last-but-one column and the last column to the value of the second one 
    194189  (\autoref{fig:LBC_jperio}-a). 
    195190  Whatever flows out of the eastern (western) end of the basin enters the western (eastern) end. 
    196191 
    197 \item[For cyclic north-south boundary (\jp{jperio}\forcode{ = 2})], 
    198   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 
    199193  the value of the last-but-one row and the last row to the value of the second one 
    200194  (\autoref{fig:LBC_jperio}-a). 
    201195  Whatever flows out of the northern (southern) end of the basin enters the southern (northern) end. 
    202196 
    203 \item[Bi-cyclic east-west and north-south boundary (\jp{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. 
    204198 
    205199\end{description} 
    206200 
    207 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    208201\begin{figure}[!t] 
    209   \begin{center} 
    210     \includegraphics[width=\textwidth]{Fig_LBC_jperio} 
    211     \caption{ 
    212       \protect\label{fig:LBC_jperio} 
    213       setting of (a) east-west cyclic  (b) symmetric across the equator boundary conditions. 
    214     } 
    215   \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} 
    216207\end{figure} 
    217 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    218  
    219 % ------------------------------------------------------------------------------------------------------------- 
    220 %        North fold (\textit{jperio = 3 }to $6)$ 
    221 % ------------------------------------------------------------------------------------------------------------- 
    222 \subsection[North-fold (\forcode{jperio = [3-6]})] 
    223 {North-fold (\protect\jp{jperio}\forcode{ = [3-6]})} 
     208 
     209%% ================================================================================================= 
     210\subsection[North-fold (\forcode{=3,6})]{North-fold (\protect\jp{jperio}\forcode{=3,6})} 
    224211\label{subsec:LBC_north_fold} 
    225212 
    226213The north fold boundary condition has been introduced in order to handle the north boundary of 
    227214a three-polar ORCA grid. 
    228 Such a grid has two poles in the northern hemisphere (\autoref{fig:MISC_ORCA_msh}, 
    229 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}. 
    230217Further information can be found in \mdl{lbcnfd} module which applies the north fold boundary condition. 
    231218 
    232 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    233219\begin{figure}[!t] 
    234   \begin{center} 
    235     \includegraphics[width=\textwidth]{Fig_North_Fold_T} 
    236     \caption{ 
    237       \protect\label{fig:North_Fold_T} 
    238       North fold boundary with a $T$-point pivot and cyclic east-west boundary condition ($jperio=4$), 
    239       as used in ORCA 2, 1/4, and 1/12. 
    240       Pink shaded area corresponds to the inner domain mask (see text). 
    241     } 
    242   \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} 
    243227\end{figure} 
    244 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    245  
    246 % ==================================================================== 
    247