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

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
Changeset 11692 for NEMO/branches/2019/dev_r11514_HPC-02_single-core-extrahalo/doc/latex/NEMO/subfiles/chap_DOM.tex – NEMO

Ignore:
Timestamp:
2019-10-12T16:08:18+02:00 (5 years 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:
5 edited

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/NEMO

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

  • 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_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} 
Note: See TracChangeset for help on using the changeset viewer.