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 11422 for NEMO/branches/2019/fix_vvl_ticket1791/doc – NEMO

Ignore:
Timestamp:
2019-08-08T15:40:47+02:00 (5 years ago)
Author:
jchanut
Message:

#1791, merge with trunk

Location:
NEMO/branches/2019/fix_vvl_ticket1791/doc
Files:
33 deleted
108 edited
32 copied

Legend:

Unmodified
Added
Removed
  • NEMO/branches/2019/fix_vvl_ticket1791/doc

    • Property svn:ignore deleted
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex

    • Property svn:ignore
      •  

        old new  
        1 *.aux 
        2 *.bbl 
        3 *.blg 
        4 *.dvi 
        5 *.fdb* 
        6 *.fls 
        7 *.idx 
        8 *.ilg 
        9 *.ind 
        10 *.log 
        11 *.maf 
        12 *.mtc* 
        13 *.out 
        14 *.pdf 
        15 *.toc 
        16 _minted-* 
         1figures 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/HTML_latex2html.sh

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

    • Property svn:ignore deleted
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/main

    • Property svn:ignore
      •  

        old new  
        1 *.aux 
        2 *.bbl 
        3 *.blg 
        4 *.dvi 
        5 *.fdb* 
        6 *.fls 
        7 *.idx 
        81*.ilg 
        92*.ind 
        10 *.log 
        11 *.maf 
        12 *.mtc* 
        13 *.out 
        14 *.pdf 
        15 *.toc 
        16 _minted-* 
    • Property svn:externals set to
      ^/utils/dev/bibtool.rsc bibtool.rsc
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_A.tex

    r10442 r11422  
    1010 
    1111\minitoc 
     12 
     13\vfill 
     14\begin{figure}[b] 
     15\subsubsection*{Changes record} 
     16\begin{tabular}{l||l|m{0.65\linewidth}} 
     17    Release   & Author        & Modifications \\ 
     18    {\em 4.0} & {\em Mike Bell} & {\em review}  \\ 
     19    {\em 3.x} & {\em Gurvan Madec} & {\em original}  \\ 
     20\end{tabular} 
     21\end{figure} 
     22 
    1223 
    1324\newpage 
     
    2940\begin{equation} 
    3041  \label{apdx:A_s_slope} 
    31   \sigma_1 =\frac{1}{e_1 }\;\left. {\frac{\partial z}{\partial i}} \right|_s 
     42  \sigma_1 =\frac{1}{e_1 } \; \left. {\frac{\partial z}{\partial i}} \right|_s 
    3243  \quad \text{and} \quad 
    33   \sigma_2 =\frac{1}{e_2 }\;\left. {\frac{\partial z}{\partial j}} \right|_s 
    34 \end{equation} 
    35  
    36 The chain rule to establish the model equations in the curvilinear $s-$coordinate system is: 
     44  \sigma_2 =\frac{1}{e_2 } \; \left. {\frac{\partial z}{\partial j}} \right|_s . 
     45\end{equation} 
     46 
     47The model fields (e.g. pressure $p$) can be viewed as functions of $(i,j,z,t)$ (e.g. $p(i,j,z,t)$) or as 
     48functions of $(i,j,s,t)$ (e.g. $p(i,j,s,t)$). The symbol $\bullet$ will be used to represent any one of  
     49these fields.  Any ``infinitesimal'' change in $\bullet$ can be written in two forms:  
     50\begin{equation} 
     51  \label{apdx:A_s_infin_changes} 
     52  \begin{aligned} 
     53    & \delta \bullet =  \delta i \left. \frac{ \partial \bullet }{\partial i} \right|_{j,s,t}  
     54                + \delta j \left. \frac{ \partial \bullet }{\partial i} \right|_{i,s,t}  
     55                + \delta s \left. \frac{ \partial \bullet }{\partial s} \right|_{i,j,t}  
     56                + \delta t \left. \frac{ \partial \bullet }{\partial t} \right|_{i,j,s} , \\ 
     57    & \delta \bullet =  \delta i \left. \frac{ \partial \bullet }{\partial i} \right|_{j,z,t}  
     58                + \delta j \left. \frac{ \partial \bullet }{\partial i} \right|_{i,z,t}  
     59                + \delta z \left. \frac{ \partial \bullet }{\partial z} \right|_{i,j,t}  
     60                + \delta t \left. \frac{ \partial \bullet }{\partial t} \right|_{i,j,z} . 
     61  \end{aligned} 
     62\end{equation} 
     63Using the first form and considering a change $\delta i$ with $j, z$ and $t$ held constant, shows that 
     64\begin{equation} 
     65  \label{apdx:A_s_chain_rule} 
     66      \left. {\frac{\partial \bullet }{\partial i}} \right|_{j,z,t}  = 
     67      \left. {\frac{\partial \bullet }{\partial i}} \right|_{j,s,t} 
     68    + \left. {\frac{\partial s       }{\partial i}} \right|_{j,z,t} \;  
     69      \left. {\frac{\partial \bullet }{\partial s}} \right|_{i,j,t} .     
     70\end{equation} 
     71The term $\left. \partial s / \partial i \right|_{j,z,t}$ can be related to the slope of constant $s$ surfaces,  
     72(\autoref{apdx:A_s_slope}), by applying the second of (\autoref{apdx:A_s_infin_changes}) with $\bullet$ set to  
     73$s$ and $j, t$ held constant 
     74\begin{equation} 
     75\label{apdx:a_delta_s} 
     76\delta s|_{j,t} =  
     77         \delta i \left. \frac{ \partial s }{\partial i} \right|_{j,z,t}  
     78       + \delta z \left. \frac{ \partial s }{\partial z} \right|_{i,j,t} . 
     79\end{equation} 
     80Choosing to look at a direction in the $(i,z)$ plane in which $\delta s = 0$ and using 
     81(\autoref{apdx:A_s_slope}) we obtain  
     82\begin{equation} 
     83\left. \frac{ \partial s }{\partial i} \right|_{j,z,t} =   
     84         -  \left. \frac{ \partial z }{\partial i} \right|_{j,s,t} \; 
     85            \left. \frac{ \partial s }{\partial z} \right|_{i,j,t} 
     86    = - \frac{e_1 }{e_3 }\sigma_1  . 
     87\label{apdx:a_ds_di_z} 
     88\end{equation} 
     89Another identity, similar in form to (\autoref{apdx:a_ds_di_z}), can be derived 
     90by choosing $\bullet$ to be $s$ and using the second form of (\autoref{apdx:A_s_infin_changes}) to consider 
     91changes in which $i , j$ and $s$ are constant. This shows that 
     92\begin{equation} 
     93\label{apdx:A_w_in_s} 
     94w_s = \left. \frac{ \partial z }{\partial t} \right|_{i,j,s} =   
     95- \left. \frac{ \partial z }{\partial s} \right|_{i,j,t} 
     96  \left. \frac{ \partial s }{\partial t} \right|_{i,j,z}  
     97  = - e_3 \left. \frac{ \partial s }{\partial t} \right|_{i,j,z} .  
     98\end{equation} 
     99 
     100In what follows, for brevity, indication of the constancy of the $i, j$ and $t$ indices is  
     101usually omitted. Using the arguments outlined above one can show that the chain rules needed to establish  
     102the model equations in the curvilinear $s-$coordinate system are: 
    37103\begin{equation} 
    38104  \label{apdx:A_s_chain_rule} 
    39105  \begin{aligned} 
    40106    &\left. {\frac{\partial \bullet }{\partial t}} \right|_z  = 
    41     \left. {\frac{\partial \bullet }{\partial t}} \right|_s 
    42     -\frac{\partial \bullet }{\partial s}\;\frac{\partial s}{\partial t} \\ 
     107    \left. {\frac{\partial \bullet }{\partial t}} \right|_s  
     108    + \frac{\partial \bullet }{\partial s}\; \frac{\partial s}{\partial t} , \\ 
    43109    &\left. {\frac{\partial \bullet }{\partial i}} \right|_z  = 
    44110    \left. {\frac{\partial \bullet }{\partial i}} \right|_s 
    45     -\frac{\partial \bullet }{\partial s}\;\frac{\partial s}{\partial i}= 
    46     \left. {\frac{\partial \bullet }{\partial i}} \right|_s 
    47     -\frac{e_1 }{e_3 }\sigma_1 \frac{\partial \bullet }{\partial s} \\ 
     111    +\frac{\partial \bullet }{\partial s}\; \frac{\partial s}{\partial i}= 
     112    \left. {\frac{\partial \bullet }{\partial i}} \right|_s  
     113    -\frac{e_1 }{e_3 }\sigma_1 \frac{\partial \bullet }{\partial s} , \\ 
    48114    &\left. {\frac{\partial \bullet }{\partial j}} \right|_z  = 
    49     \left. {\frac{\partial \bullet }{\partial j}} \right|_s 
    50     - \frac{\partial \bullet }{\partial s}\;\frac{\partial s}{\partial j}= 
    51     \left. {\frac{\partial \bullet }{\partial j}} \right|_s 
    52     - \frac{e_2 }{e_3 }\sigma_2 \frac{\partial \bullet }{\partial s} \\ 
    53     &\;\frac{\partial \bullet }{\partial z}  \;\; = \frac{1}{e_3 }\frac{\partial \bullet }{\partial s} 
     115    \left. {\frac{\partial \bullet }{\partial j}} \right|_s  
     116    + \frac{\partial \bullet }{\partial s}\;\frac{\partial s}{\partial j}= 
     117    \left. {\frac{\partial \bullet }{\partial j}} \right|_s  
     118    - \frac{e_2 }{e_3 }\sigma_2 \frac{\partial \bullet }{\partial s} , \\ 
     119    &\;\frac{\partial \bullet }{\partial z}  \;\; = \frac{1}{e_3 }\frac{\partial \bullet }{\partial s} . 
    54120  \end{aligned} 
    55121\end{equation} 
    56122 
    57 In particular applying the time derivative chain rule to $z$ provides the expression for $w_s$, 
    58 the vertical velocity of the $s-$surfaces referenced to a fix z-coordinate: 
    59 \begin{equation} 
    60   \label{apdx:A_w_in_s} 
    61   w_s   =  \left.   \frac{\partial z }{\partial t}   \right|_s 
    62   = \frac{\partial z}{\partial s} \; \frac{\partial s}{\partial t} 
    63   = e_3 \, \frac{\partial s}{\partial t} 
    64 \end{equation} 
    65123 
    66124% ================================================================ 
     
    79137    { 
    80138    \begin{array}{*{20}l} 
    81       \nabla \cdot {\rm {\bf U}} 
     139      \nabla \cdot {\mathrm {\mathbf U}} 
    82140      &= \frac{1}{e_1 \,e_2 }  \left[ \left. {\frac{\partial (e_2 \,u)}{\partial i}} \right|_z 
    83141        +\left. {\frac{\partial(e_1 \,v)}{\partial j}} \right|_z  \right] 
     
    115173      $, it becomes:} 
    116174    % 
    117       \nabla \cdot {\rm {\bf U}} 
     175      \nabla \cdot {\mathrm {\mathbf U}} 
    118176      & = \frac{1}{e_1 \,e_2 \,e_3 }  \left[ 
    119177        \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s 
     
    131189\end{subequations} 
    132190 
    133 Here, $w$ is the vertical velocity relative to the $z-$coordinate system. 
    134 Introducing the dia-surface velocity component, 
    135 $\omega $, defined as the volume flux across the moving $s$-surfaces per unit horizontal area: 
     191Here, $w$ is the vertical velocity relative to the $z-$coordinate system.  
     192Using the first form of (\autoref{apdx:A_s_infin_changes})  
     193and the definitions (\autoref{apdx:A_s_slope}) and (\autoref{apdx:A_w_in_s}) for $\sigma_1$, $\sigma_2$ and  $w_s$, 
     194one can show that the vertical velocity, $w_p$ of a point 
     195moving with the horizontal velocity of the fluid along an $s$ surface is given by  
     196\begin{equation} 
     197\label{apdx:A_w_p} 
     198\begin{split} 
     199w_p  = & \left. \frac{ \partial z }{\partial t} \right|_s 
     200     + \frac{u}{e_1} \left. \frac{ \partial z }{\partial i} \right|_s  
     201     + \frac{v}{e_2} \left. \frac{ \partial z }{\partial j} \right|_s \\ 
     202     = & w_s + u \sigma_1 + v \sigma_2 . 
     203\end{split}      
     204\end{equation} 
     205 The vertical velocity across this surface is denoted by 
    136206\begin{equation} 
    137207  \label{apdx:A_w_s} 
    138   \omega  = w - w_s - \sigma_1 \,u - \sigma_2 \,v    \\ 
    139 \end{equation} 
    140 with $w_s$ given by \autoref{apdx:A_w_in_s}, 
    141 we obtain the expression for the divergence of the velocity in the curvilinear $s-$coordinate system: 
    142 \begin{subequations} 
    143   \begin{align*} 
    144     { 
    145     \begin{array}{*{20}l} 
    146       \nabla \cdot {\rm {\bf U}} 
    147       &= \frac{1}{e_1 \,e_2 \,e_3 }    \left[ 
     208  \omega  = w - w_p = w - ( w_s + \sigma_1 \,u + \sigma_2 \,v )  .  
     209\end{equation} 
     210Hence  
     211\begin{equation} 
     212\frac{1}{e_3 } \frac{\partial}{\partial s}   \left[  w -  u\;\sigma_1  - v\;\sigma_2  \right] =  
     213\frac{1}{e_3 } \frac{\partial}{\partial s} \left[  \omega + w_s \right] =  
     214   \frac{1}{e_3 } \left[ \frac{\partial \omega}{\partial s}  
     215 + \left. \frac{ \partial }{\partial t} \right|_s \frac{\partial z}{\partial s} \right] =  
     216   \frac{1}{e_3 } \frac{\partial \omega}{\partial s} + \frac{1}{e_3 } \left. \frac{ \partial e_3}{\partial t} . \right|_s  
     217\end{equation} 
     218 
     219Using (\autoref{apdx:A_w_s}) in our expression for $\nabla \cdot {\mathrm {\mathbf U}}$ we obtain  
     220our final expression for the divergence of the velocity in the curvilinear $s-$coordinate system: 
     221\begin{equation} 
     222      \nabla \cdot {\mathrm {\mathbf U}} = 
     223         \frac{1}{e_1 \,e_2 \,e_3 }    \left[ 
    148224        \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s 
    149225        +\left.  \frac{\partial (e_1 \,e_3 \,v)}{\partial j} \right|_s        \right] 
    150226        + \frac{1}{e_3 } \frac{\partial \omega }{\partial s} 
    151         + \frac{1}{e_3 } \frac{\partial w_s       }{\partial s} \\ \\ 
    152       &= \frac{1}{e_1 \,e_2 \,e_3 }    \left[ 
    153         \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s 
    154         +\left.  \frac{\partial (e_1 \,e_3 \,v)}{\partial j} \right|_s        \right] 
    155         + \frac{1}{e_3 } \frac{\partial \omega }{\partial s} 
    156         + \frac{1}{e_3 } \frac{\partial}{\partial s}  \left(  e_3 \; \frac{\partial s}{\partial t}   \right) \\ \\ 
    157       &= \frac{1}{e_1 \,e_2 \,e_3 }    \left[ 
    158         \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s 
    159         +\left.  \frac{\partial (e_1 \,e_3 \,v)}{\partial j} \right|_s        \right] 
    160         + \frac{1}{e_3 } \frac{\partial \omega }{\partial s} 
    161         + \frac{\partial}{\partial s} \frac{\partial s}{\partial t} 
    162         + \frac{1}{e_3 } \frac{\partial s}{\partial t} \frac{\partial e_3}{\partial s} \\ \\ 
    163       &= \frac{1}{e_1 \,e_2 \,e_3 }    \left[ 
    164         \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s 
    165         +\left.  \frac{\partial (e_1 \,e_3 \,v)}{\partial j} \right|_s        \right] 
    166         + \frac{1}{e_3 } \frac{\partial \omega }{\partial s} 
    167         + \frac{1}{e_3 } \frac{\partial e_3}{\partial t} 
    168     \end{array} 
    169         } 
    170   \end{align*} 
    171 \end{subequations} 
     227        + \frac{1}{e_3 } \left. \frac{\partial e_3}{\partial t} \right|_s . 
     228\end{equation} 
    172229 
    173230As a result, the continuity equation \autoref{eq:PE_continuity} in the $s-$coordinates is: 
     
    178235    {\left. {\frac{\partial (e_2 \,e_3 \,u)}{\partial i}} \right|_s 
    179236      +  \left. {\frac{\partial (e_1 \,e_3 \,v)}{\partial j}} \right|_s } \right] 
    180   +\frac{1}{e_3 }\frac{\partial \omega }{\partial s} = 0 
    181 \end{equation} 
    182 A additional term has appeared that take into account 
     237  +\frac{1}{e_3 }\frac{\partial \omega }{\partial s} = 0 . 
     238\end{equation} 
     239An additional term has appeared that takes into account 
    183240the contribution of the time variation of the vertical coordinate to the volume budget. 
    184241 
     
    210267        + w \;\frac{\partial u}{\partial z} \\ \\ 
    211268      &= \left. {\frac{\partial u }{\partial t}} \right|_z 
    212         - \left. \zeta \right|_z v 
    213         +  \frac{1}{e_1 \,e_2 }\left[ { \left.{ \frac{\partial (e_2 \,v)}{\partial i} }\right|_z 
     269        -  \frac{1}{e_1 \,e_2 }\left[ { \left.{ \frac{\partial (e_2 \,v)}{\partial i} }\right|_z 
    214270        -\left.{ \frac{\partial (e_1 \,u)}{\partial j} }\right|_z } \right] \; v 
    215271        +  \frac{1}{2e_1} \left.{ \frac{\partial (u^2+v^2)}{\partial i} } \right|_z 
     
    230286        } \\ \\ 
    231287      &= \left. {\frac{\partial u }{\partial t}} \right|_z 
    232         + \left. \zeta \right|_s \;v 
     288        - \left. \zeta \right|_s \;v 
    233289        + \frac{1}{2\,e_1}\left. {\frac{\partial (u^2+v^2)}{\partial i}} \right|_s \\ 
    234290      &\qquad \qquad \qquad \quad 
    235291        + \frac{w}{e_3 } \;\frac{\partial u}{\partial s} 
    236         - \left[   {\frac{\sigma_1 }{e_3 }\frac{\partial v}{\partial s} 
     292        + \left[   {\frac{\sigma_1 }{e_3 }\frac{\partial v}{\partial s} 
    237293        - \frac{\sigma_2 }{e_3 }\frac{\partial u}{\partial s}}   \right]\;v 
    238294        - \frac{\sigma_1 }{2e_3 }\frac{\partial (u^2+v^2)}{\partial s} \\ \\ 
    239295      &= \left. {\frac{\partial u }{\partial t}} \right|_z 
    240         + \left. \zeta \right|_s \;v 
     296        - \left. \zeta \right|_s \;v 
    241297        + \frac{1}{2\,e_1}\left. {\frac{\partial (u^2+v^2)}{\partial i}} \right|_s \\ 
    242298      &\qquad \qquad \qquad \quad 
     
    245301        - \sigma_1 u\frac{\partial u}{\partial s} - \sigma_1 v\frac{\partial v}{\partial s}} \right] \\ \\ 
    246302      &= \left. {\frac{\partial u }{\partial t}} \right|_z 
    247         + \left. \zeta \right|_s \;v 
     303        - \left. \zeta \right|_s \;v 
    248304        + \frac{1}{2\,e_1}\left. {\frac{\partial (u^2+v^2)}{\partial i}} \right|_s 
    249305        + \frac{1}{e_3} \left[  w - \sigma_2 v - \sigma_1 u  \right] 
    250         \; \frac{\partial u}{\partial s}   \\ 
     306        \; \frac{\partial u}{\partial s} .  \\ 
    251307        % 
    252       \intertext{Introducing $\omega$, the dia-a-surface velocity given by (\autoref{apdx:A_w_s}) } 
     308      \intertext{Introducing $\omega$, the dia-s-surface velocity given by (\autoref{apdx:A_w_s}) } 
    253309      % 
    254310      &= \left. {\frac{\partial u }{\partial t}} \right|_z 
    255         + \left. \zeta \right|_s \;v 
     311        - \left. \zeta \right|_s \;v 
    256312        + \frac{1}{2\,e_1}\left. {\frac{\partial (u^2+v^2)}{\partial i}} \right|_s 
    257         + \frac{1}{e_3 } \left( \omega - w_s \right) \frac{\partial u}{\partial s}   \\ 
     313        + \frac{1}{e_3 } \left( \omega + w_s \right) \frac{\partial u}{\partial s}   \\ 
    258314    \end{array} 
    259315    } 
     
    266322  { 
    267323    \begin{array}{*{20}l} 
    268       w_s  \;\frac{\partial u}{\partial s} 
    269       = \frac{\partial s}{\partial t} \;  \frac{\partial u }{\partial s} 
    270       = \left. {\frac{\partial u }{\partial t}} \right|_s  - \left. {\frac{\partial u }{\partial t}} \right|_z \quad , 
     324      \frac{w_s}{e_3}  \;\frac{\partial u}{\partial s} 
     325      = - \left. \frac{\partial s}{\partial t} \right|_z \;  \frac{\partial u }{\partial s} 
     326      = \left. {\frac{\partial u }{\partial t}} \right|_s  - \left. {\frac{\partial u }{\partial t}} \right|_z \ . 
    271327    \end{array} 
    272328  } 
    273329\] 
    274 leads to the $s-$coordinate formulation of the total $z-$coordinate time derivative, 
     330This leads to the $s-$coordinate formulation of the total $z-$coordinate time derivative, 
    275331\ie the total $s-$coordinate time derivative : 
    276332\begin{align} 
     
    278334  \left. \frac{D u}{D t} \right|_s 
    279335  = \left. {\frac{\partial u }{\partial t}} \right|_s 
    280   + \left. \zeta \right|_s \;v 
     336  - \left. \zeta \right|_s \;v 
    281337  + \frac{1}{2\,e_1}\left. {\frac{\partial (u^2+v^2)}{\partial i}} \right|_s 
    282   + \frac{1}{e_3 } \omega \;\frac{\partial u}{\partial s} 
     338  + \frac{1}{e_3 } \omega \;\frac{\partial u}{\partial s} .  
    283339\end{align} 
    284340Therefore, the vector invariant form of the total time derivative has exactly the same mathematical form in 
     
    306362                                         + \frac{1}{e_3}        \frac{\partial \omega}{\partial s}                       \right] \\ \\ 
    307363                                      &&- \frac{v}{e_1 e_2 }\left(    v \;\frac{\partial e_2 }{\partial i} 
    308                                          -u  \;\frac{\partial e_1 }{\partial j}  \right) \\ 
     364                                         -u  \;\frac{\partial e_1 }{\partial j}  \right) . \\ 
    309365  \end{array} 
    310366  } 
     
    328384       -  e_2 u \;\frac{\partial e_3 }{\partial i} 
    329385       -  e_1 v \;\frac{\partial e_3 }{\partial j}   \right) 
    330        -\frac{1}{e_3}        \frac{\partial \omega}{\partial s}                       \right] \\ \\ 
     386       + \frac{1}{e_3}        \frac{\partial \omega}{\partial s}                       \right] \\ \\ 
    331387    && - \frac{v}{e_1 e_2 }\left(   v  \;\frac{\partial e_2 }{\partial i} 
    332388       -u  \;\frac{\partial e_1 }{\partial j}   \right) \\ \\ 
     
    337393    && - \,u \left[  \frac{1}{e_1 e_2 e_3} \left(   \frac{\partial(e_2 e_3 \, u)}{\partial i} 
    338394       + \frac{\partial(e_1 e_3 \, v)}{\partial j}  \right) 
    339        -\frac{1}{e_3}        \frac{\partial \omega}{\partial s}                       \right] 
     395       + \frac{1}{e_3}        \frac{\partial \omega}{\partial s}                       \right] 
    340396       - \frac{v}{e_1 e_2 }\left(   v   \;\frac{\partial e_2 }{\partial i} 
    341        -u   \;\frac{\partial e_1 }{\partial j}  \right)                  \\ 
     397       -u   \;\frac{\partial e_1 }{\partial j}  \right)     .             \\ 
    342398     % 
    343399    \intertext {Introducing a more compact form for the divergence of the momentum fluxes, 
     
    346402  % 
    347403    &= \left. {\frac{\partial u }{\partial t}} \right|_s 
    348     &+ \left.  \nabla \cdot \left(   {{\rm {\bf U}}\,u}   \right)    \right|_s 
     404    &+ \left.  \nabla \cdot \left(   {{\mathrm {\mathbf U}}\,u}   \right)    \right|_s 
    349405      + \,u \frac{1}{e_3 } \frac{\partial e_3}{\partial t} 
    350406      - \frac{v}{e_1 e_2 }\left(    v  \;\frac{\partial e_2 }{\partial i} 
     
    359415  \label{apdx:A_sco_Dt_flux} 
    360416  \left. \frac{D u}{D t} \right|_s   = \frac{1}{e_3}  \left. \frac{\partial ( e_3\,u)}{\partial t} \right|_s 
    361   + \left.  \nabla \cdot \left(   {{\rm {\bf U}}\,u}   \right)    \right|_s 
     417  + \left.  \nabla \cdot \left(   {{\mathrm {\mathbf U}}\,u}   \right)    \right|_s 
    362418  - \frac{v}{e_1 e_2 }\left(    v  \;\frac{\partial e_2 }{\partial i} 
    363     -u  \;\frac{\partial e_1 }{\partial j}            \right) 
     419    -u  \;\frac{\partial e_1 }{\partial j}            \right). 
    364420\end{flalign} 
    365421which is the total time derivative expressed in the curvilinear $s-$coordinate system. 
     
    377433    & =-\frac{1}{\rho_o e_1 }\left[ {\left. {\frac{\partial p}{\partial i}} \right|_s -\frac{e_1 }{e_3 }\sigma_1 \frac{\partial p}{\partial s}} \right] \\ 
    378434    & =-\frac{1}{\rho_o \,e_1 }\left. {\frac{\partial p}{\partial i}} \right|_s +\frac{\sigma_1 }{\rho_o \,e_3 }\left( {-g\;\rho \;e_3 } \right) \\ 
    379     &=-\frac{1}{\rho_o \,e_1 }\left. {\frac{\partial p}{\partial i}} \right|_s -\frac{g\;\rho }{\rho_o }\sigma_1 
     435    &=-\frac{1}{\rho_o \,e_1 }\left. {\frac{\partial p}{\partial i}} \right|_s -\frac{g\;\rho }{\rho_o }\sigma_1 . 
    380436  \end{split} 
    381437\] 
    382438Applying similar manipulation to the second component and 
    383 replacing $\sigma_1$ and $\sigma_2$ by their expression \autoref{apdx:A_s_slope}, it comes: 
     439replacing $\sigma_1$ and $\sigma_2$ by their expression \autoref{apdx:A_s_slope}, it becomes: 
    384440\begin{equation} 
    385441  \label{apdx:A_grad_p_1} 
     
    391447    -\frac{1}{\rho_o \, e_2 }\left. {\frac{\partial p}{\partial j}} \right|_z 
    392448    &=-\frac{1}{\rho_o \,e_2 } \left(    \left.               {\frac{\partial p}{\partial j}} \right|_s 
    393       + g\;\rho \;\left. {\frac{\partial z}{\partial j}} \right|_s   \right) \\ 
     449      + g\;\rho \;\left. {\frac{\partial z}{\partial j}} \right|_s   \right) . \\ 
    394450  \end{split} 
    395451\end{equation} 
     
    399455 
    400456As in $z$-coordinate, 
    401 the horizontal pressure gradient can be split in two parts following \citet{Marsaleix_al_OM08}. 
     457the horizontal pressure gradient can be split in two parts following \citet{marsaleix.auclair.ea_OM08}. 
    402458Let defined a density anomaly, $d$, by $d=(\rho - \rho_o)/ \rho_o$, 
    403459and a hydrostatic pressure anomaly, $p_h'$, by $p_h'= g \; \int_z^\eta d \; e_3 \; dk$. 
     
    405461\[ 
    406462  \begin{split} 
    407     p &= g\; \int_z^\eta \rho \; e_3 \; dk = g\; \int_z^\eta \left(  \rho_o \, d + 1 \right) \; e_3 \; dk   \\ 
    408     &= g \, \rho_o \; \int_z^\eta d \; e_3 \; dk + g \, \int_z^\eta e_3 \; dk 
     463    p &= g\; \int_z^\eta \rho \; e_3 \; dk = g\; \int_z^\eta \rho_o \left( d + 1 \right) \; e_3 \; dk   \\ 
     464    &= g \, \rho_o \; \int_z^\eta d \; e_3 \; dk + \rho_o g \, \int_z^\eta e_3 \; dk . 
    409465  \end{split} 
    410466\] 
     
    412468\begin{equation} 
    413469  \label{apdx:A_pressure} 
    414   p = \rho_o \; p_h' + g \, ( z + \eta ) 
     470  p = \rho_o \; p_h' + \rho_o \, g \, ( \eta - z ) 
    415471\end{equation} 
    416472and the hydrostatic pressure balance expressed in terms of $p_h'$ and $d$ is: 
    417473\[ 
    418   \frac{\partial p_h'}{\partial k} = - d \, g \, e_3 
     474  \frac{\partial p_h'}{\partial k} = - d \, g \, e_3 . 
    419475\] 
    420476 
    421477Substituing \autoref{apdx:A_pressure} in \autoref{apdx:A_grad_p_1} and 
    422 using the definition of the density anomaly it comes the expression in two parts: 
     478using the definition of the density anomaly it becomes an expression in two parts: 
    423479\begin{equation} 
    424480  \label{apdx:A_grad_p_2} 
     
    426482    -\frac{1}{\rho_o \, e_1 } \left. {\frac{\partial p}{\partial i}} \right|_z 
    427483    &=-\frac{1}{e_1 } \left(     \left.              {\frac{\partial p_h'}{\partial i}} \right|_s 
    428       + g\; d  \;\left. {\frac{\partial z}{\partial i}} \right|_s    \right)  - \frac{g}{e_1 } \frac{\partial \eta}{\partial i} \\ 
     484      + g\; d  \;\left. {\frac{\partial z}{\partial i}} \right|_s    \right)  - \frac{g}{e_1 } \frac{\partial \eta}{\partial i} \\ 
    429485             % 
    430486    -\frac{1}{\rho_o \, e_2 }\left. {\frac{\partial p}{\partial j}} \right|_z 
    431487    &=-\frac{1}{e_2 } \left(    \left.               {\frac{\partial p_h'}{\partial j}} \right|_s 
    432       + g\; d \;\left. {\frac{\partial z}{\partial j}} \right|_s   \right)  - \frac{g}{e_2 } \frac{\partial \eta}{\partial j}\\ 
     488      + g\; d \;\left. {\frac{\partial z}{\partial j}} \right|_s   \right)  - \frac{g}{e_2 } \frac{\partial \eta}{\partial j} . \\ 
    433489  \end{split} 
    434490\end{equation} 
     
    463519    -   \frac{1}{e_1 } \left(    \frac{\partial p_h'}{\partial i} + g\; d  \; \frac{\partial z}{\partial i}    \right) 
    464520    -   \frac{g}{e_1 } \frac{\partial \eta}{\partial i} 
    465     +   D_u^{\vect{U}}  +   F_u^{\vect{U}} 
     521    +   D_u^{\vect{U}}  +   F_u^{\vect{U}} , 
    466522  \end{multline} 
    467523  \begin{multline} 
     
    473529    -   \frac{1}{e_2 } \left(    \frac{\partial p_h'}{\partial j} + g\; d  \; \frac{\partial z}{\partial j}    \right) 
    474530    -   \frac{g}{e_2 } \frac{\partial \eta}{\partial j} 
    475     +  D_v^{\vect{U}}  +   F_v^{\vect{U}} 
     531    +  D_v^{\vect{U}}  +   F_v^{\vect{U}} . 
    476532  \end{multline} 
    477533\end{subequations} 
     
    483539    \label{apdx:A_PE_dyn_flux_u} 
    484540    \frac{1}{e_3} \frac{\partial \left(  e_3\,u  \right) }{\partial t} = 
    485     \nabla \cdot \left(   {{\rm {\bf U}}\,u}   \right) 
     541    - \nabla \cdot \left(   {{\mathrm {\mathbf U}}\,u}   \right) 
    486542    +   \left\{ {f + \frac{1}{e_1 e_2 }\left(    v  \;\frac{\partial e_2 }{\partial i} 
    487543          -u  \;\frac{\partial e_1 }{\partial j}            \right)} \right\} \,v     \\ 
    488544    -   \frac{1}{e_1 } \left(    \frac{\partial p_h'}{\partial i} + g\; d  \; \frac{\partial z}{\partial i}    \right) 
    489545    -   \frac{g}{e_1 } \frac{\partial \eta}{\partial i} 
    490     +   D_u^{\vect{U}}  +   F_u^{\vect{U}} 
     546    +   D_u^{\vect{U}}  +   F_u^{\vect{U}} , 
    491547  \end{multline} 
    492548  \begin{multline} 
    493549    \label{apdx:A_dyn_flux_v} 
    494550    \frac{1}{e_3}\frac{\partial \left(  e_3\,v  \right) }{\partial t}= 
    495     -  \nabla \cdot \left(   {{\rm {\bf U}}\,v}   \right) 
    496     +   \left\{ {f + \frac{1}{e_1 e_2 }\left(    v  \;\frac{\partial e_2 }{\partial i} 
     551    -  \nabla \cdot \left(   {{\mathrm {\mathbf U}}\,v}   \right) 
     552    -   \left\{ {f + \frac{1}{e_1 e_2 }\left(    v  \;\frac{\partial e_2 }{\partial i} 
    497553          -u  \;\frac{\partial e_1 }{\partial j}            \right)} \right\} \,u     \\ 
    498554    -   \frac{1}{e_2 } \left(    \frac{\partial p_h'}{\partial j} + g\; d  \; \frac{\partial z}{\partial j}    \right) 
    499555    -   \frac{g}{e_2 } \frac{\partial \eta}{\partial j} 
    500     +  D_v^{\vect{U}}  +   F_v^{\vect{U}} 
     556    +  D_v^{\vect{U}}  +   F_v^{\vect{U}} .  
    501557  \end{multline} 
    502558\end{subequations} 
     
    505561\begin{equation} 
    506562  \label{apdx:A_dyn_zph} 
    507   \frac{\partial p_h'}{\partial k} = - d \, g \, e_3 
     563  \frac{\partial p_h'}{\partial k} = - d \, g \, e_3 . 
    508564\end{equation} 
    509565 
     
    531587  \left[           \frac{\partial }{\partial i} \left( {e_2 \,e_3 \;Tu} \right) 
    532588    +   \frac{\partial }{\partial j} \left( {e_1 \,e_3 \;Tv} \right)               \right]       \\ 
    533   +  \frac{1}{e_3}  \frac{\partial }{\partial k} \left(                   Tw  \right) 
     589  -  \frac{1}{e_3}  \frac{\partial }{\partial k} \left(                   Tw  \right) 
    534590  +  D^{T} +F^{T} 
    535591\end{multline} 
    536592 
    537 The expression for the advection term is a straight consequence of (A.4), 
     593The expression for the advection term is a straight consequence of (\autoref{apdx:A_sco_Continuity}), 
    538594the expression of the 3D divergence in the $s-$coordinates established above.  
    539595 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_B.tex

    r10442 r11422  
    5353  { 
    5454  \begin{array}{*{20}l} 
    55     D^T=& \frac{1}{e_1\,e_2\,e_3 }\;\left[ {\ \ \ \ e_2\,e_3\,A^{lT} \;\left. 
    56           {\frac{\partial }{\partial i}\left( {\frac{1}{e_1}\;\left. {\frac{\partial T}{\partial i}} \right|_s -\frac{\sigma_1 }{e_3 }\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right.  \\ 
    57         &\qquad \quad \ \ \ +e_1\,e_3\,A^{lT} \;\left. {\frac{\partial }{\partial j}\left( {\frac{1}{e_2 }\;\left. {\frac{\partial T}{\partial j}} \right|_s -\frac{\sigma_2 }{e_3 }\;\frac{\partial T}{\partial s}} \right)} \right|_s \\ 
    58         &\qquad \quad \ \ \ + e_1\,e_2\,A^{lT} \;\frac{\partial }{\partial s}\left( {-\frac{\sigma_1 }{e_1 }\;\left. {\frac{\partial T}{\partial i}} \right|_s -\frac{\sigma_2 }{e_2 }\;\left. {\frac{\partial T}{\partial j}} \right|_s } \right. 
    59           \left. {\left. {+\left( {\varepsilon +\sigma_1^2+\sigma_2 ^2} \right)\;\frac{1}{e_3 }\;\frac{\partial T}{\partial s}} \right)\;\;} \right] 
     55    D^T= \frac{1}{e_1\,e_2\,e_3 } & \left\{ \quad \quad \frac{\partial }{\partial i}  \left. \left[  e_2\,e_3 \, A^{lT} 
     56                               \left( \  \frac{1}{e_1}\; \left. \frac{\partial T}{\partial i} \right|_s  
     57                                       -\frac{\sigma_1 }{e_3 } \; \frac{\partial T}{\partial s} \right) \right]  \right|_s  \right. \\ 
     58        &  \quad \  +   \            \left.   \frac{\partial }{\partial j}  \left. \left[  e_1\,e_3 \, A^{lT} 
     59                               \left( \ \frac{1}{e_2 }\; \left. \frac{\partial T}{\partial j} \right|_s  
     60                                       -\frac{\sigma_2 }{e_3 } \; \frac{\partial T}{\partial s} \right) \right]  \right|_s  \right. \\ 
     61        &  \quad \  +   \           \left.  e_1\,e_2\, \frac{\partial }{\partial s}  \left[ A^{lT} \; \left(  
     62                     -\frac{\sigma_1 }{e_1 } \; \left. \frac{\partial T}{\partial i} \right|_s  
     63                     -\frac{\sigma_2 }{e_2 } \; \left. \frac{\partial T}{\partial j} \right|_s  
     64                          +\left( \varepsilon +\sigma_1^2+\sigma_2 ^2 \right) \; \frac{1}{e_3 } \; \frac{\partial T}{\partial s} \right) \; \right] \;  \right\} . 
    6065  \end{array} 
    6166          } 
    6267\end{align*} 
    6368 
    64 Equation \autoref{apdx:B2} is obtained from \autoref{apdx:B1} without any additional assumption. 
     69\autoref{apdx:B2} is obtained from \autoref{apdx:B1} without any additional assumption. 
    6570Indeed, for the special case $k=z$ and thus $e_3 =1$, 
    6671we introduce an arbitrary vertical coordinate $s = s (i,j,z)$ as in \autoref{apdx:A} and 
     
    9095  { 
    9196  \begin{array}{*{20}l} 
    92     \intertext{Noting that $\frac{1}{e_1} \left. \frac{\partial e_3 }{\partial i} \right|_s = \frac{\partial \sigma_1 }{\partial s}$, it becomes:} 
     97    \intertext{Noting that $\frac{1}{e_1} \left. \frac{\partial e_3 }{\partial i} \right|_s = \frac{\partial \sigma_1 }{\partial s}$, this becomes:} 
    9398    % 
    94     & =\frac{1}{e_1\,e_2\,e_3 }\left[ {\left. {\;\;\;\frac{\partial }{\partial i}\left( {\frac{e_2\,e_3 }{e_1}\,A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right)} \right|_s \left. -\, {e_3 \frac{\partial }{\partial i}\left( {\frac{e_2 \,\sigma_1 }{e_3 }A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right. \\ 
     99    D^T & =\frac{1}{e_1\,e_2\,e_3 }\left[ {\left. {\;\;\;\frac{\partial }{\partial i}\left( {\frac{e_2\,e_3 }{e_1}\,A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right)} \right|_s \left. -\, {e_3 \frac{\partial }{\partial i}\left( {\frac{e_2 \,\sigma_1 }{e_3 }A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right. \\ 
    95100    & \qquad \qquad \quad -e_2 A^{lT}\;\frac{\partial \sigma_1 }{\partial s}\left. {\frac{\partial T}{\partial i}} \right|_s -e_1 \,\sigma_1 \frac{\partial }{\partial s}\left( {\frac{e_2 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right) \\ 
    96     & \qquad \qquad \quad\shoveright{ \left. { +e_1 \,\sigma_1 \frac{\partial }{\partial s}\left( {\frac{e_2 \,\sigma_1 }{e_3 }A^{lT}\;\frac{\partial T}{\partial s}} \right)+\frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 }{e_3 }A^{vT}\;\frac{\partial T}{\partial z}} \right)\;\;\;} \right] }\\ 
     101    & \qquad \qquad \quad\shoveright{ \left. { +e_1 \,\sigma_1 \frac{\partial }{\partial s}\left( {\frac{e_2 \,\sigma_1 }{e_3 }A^{lT}\;\frac{\partial T}{\partial s}} \right)+\frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 }{e_3 }A^{vT}\;\frac{\partial T}{\partial s}} \right)\;\;\;} \right] }\\ 
    97102    \\ 
    98103    &=\frac{1}{e_1 \,e_2 \,e_3 } \left[ {\left. {\;\;\;\frac{\partial }{\partial i} \left( {\frac{e_2 \,e_3 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right)} \right|_s \left. {-\frac{\partial }{\partial i}\left( {e_2 \,\sigma_1 A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right. \\ 
    99104    & \qquad \qquad \quad \left. {+\frac{e_2 \,\sigma_1 }{e_3}A^{lT}\;\frac{\partial T}{\partial s} \;\frac{\partial e_3 }{\partial i}}  \right|_s -e_2 A^{lT}\;\frac{\partial \sigma_1 }{\partial s}\left. {\frac{\partial T}{\partial i}} \right|_s \\ 
    100105    & \qquad \qquad \quad-e_2 \,\sigma_1 \frac{\partial}{\partial s}\left( {A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right)+\frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 \,\sigma_1 ^2}{e_3 }A^{lT}\;\frac{\partial T}{\partial s}} \right) \\ 
    101     & \qquad \qquad \quad\shoveright{ \left. {-\frac{\partial \left( {e_1 \,e_2 \,\sigma_1 } \right)}{\partial s} \left( {\frac{\sigma_1 }{e_3}A^{lT}\;\frac{\partial T}{\partial s}} \right) + \frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 }{e_3 }A^{vT}\;\frac{\partial T}{\partial s}} \right)\;\;\;} \right]} 
     106    & \qquad \qquad \quad\shoveright{ \left. {-\frac{\partial \left( {e_1 \,e_2 \,\sigma_1 } \right)}{\partial s} \left( {\frac{\sigma_1 }{e_3}A^{lT}\;\frac{\partial T}{\partial s}} \right) + \frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 }{e_3 }A^{vT}\;\frac{\partial T}{\partial s}} \right)\;\;\;} \right]} . 
    102107  \end{array} 
    103108      } \\ 
     
    105110  \begin{array}{*{20}l} 
    106111    % 
    107     \intertext{using the same remark as just above, it becomes:} 
     112    \intertext{Using the same remark as just above, $D^T$ becomes:} 
    108113    % 
    109     &= \frac{1}{e_1 \,e_2 \,e_3 } \left[ {\left. {\;\;\;\frac{\partial }{\partial i} \left( {\frac{e_2 \,e_3 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s -e_2 \,\sigma_1 A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right.\;\;\; \\ 
     114   D^T &= \frac{1}{e_1 \,e_2 \,e_3 } \left[ {\left. {\;\;\;\frac{\partial }{\partial i} \left( {\frac{e_2 \,e_3 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s -e_2 \,\sigma_1 A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right.\;\;\; \\ 
    110115    & \qquad \qquad \quad+\frac{e_1 \,e_2 \,\sigma_1 }{e_3 }A^{lT}\;\frac{\partial T}{\partial s}\;\frac{\partial \sigma_1 }{\partial s} - \frac {\sigma_1 }{e_3} A^{lT} \;\frac{\partial \left( {e_1 \,e_2 \,\sigma_1 } \right)}{\partial s}\;\frac{\partial T}{\partial s} \\ 
    111116    & \qquad \qquad \quad-e_2 \left( {A^{lT}\;\frac{\partial \sigma_1 }{\partial s}\left. {\frac{\partial T}{\partial i}} \right|_s +\frac{\partial }{\partial s}\left( {\sigma_1 A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right)-\frac{\partial \sigma_1 }{\partial s}\;A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right) \\ 
    112     & \qquad \qquad \quad\shoveright{\left. {+\frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 \,\sigma_1 ^2}{e_3 }A^{lT}\;\frac{\partial T}{\partial s}+\frac{e_1 \,e_2}{e_3 }A^{vT}\;\frac{\partial T}{\partial s}} \right)\;\;\;} \right] } 
     117    & \qquad \qquad \quad\shoveright{\left. {+\frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 \,\sigma_1 ^2}{e_3 }A^{lT}\;\frac{\partial T}{\partial s}+\frac{e_1 \,e_2}{e_3 }A^{vT}\;\frac{\partial T}{\partial s}} \right)\;\;\;} \right] . } 
    113118  \end{array} 
    114119      } \\ 
     
    117122    % 
    118123    \intertext{Since the horizontal scale factors do not depend on the vertical coordinate, 
    119     the last term of the first line and the first term of the last line cancel, while 
    120     the second line reduces to a single vertical derivative, so it becomes:} 
     124    the two terms on the second line cancel, while 
     125    the third line reduces to a single vertical derivative, so it becomes:} 
    121126  % 
    122     & =\frac{1}{e_1 \,e_2 \,e_3 }\left[ {\left. {\;\;\;\frac{\partial }{\partial i}\left( {\frac{e_2 \,e_3 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s -e_2 \,\sigma_1 \,A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right. \\ 
     127    D^T & =\frac{1}{e_1 \,e_2 \,e_3 }\left[ {\left. {\;\;\;\frac{\partial }{\partial i}\left( {\frac{e_2 \,e_3 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s -e_2 \,\sigma_1 \,A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right. \\ 
    123128    & \qquad \qquad \quad \shoveright{ \left. {+\frac{\partial }{\partial s}\left( {-e_2 \,\sigma_1 \,A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s +A^{lT}\frac{e_1 \,e_2 }{e_3 }\;\left( {\varepsilon +\sigma_1 ^2} \right)\frac{\partial T}{\partial s}} \right)\;\;\;} \right]} \\ 
    124129    % 
    125     \intertext{in other words, the horizontal/vertical Laplacian operator in the ($i$,$s$) plane takes the following form:} 
     130    \intertext{In other words, the horizontal/vertical Laplacian operator in the ($i$,$s$) plane takes the following form:} 
    126131  \end{array} 
    127132  } \\ 
     
    162167the ($i$,$j$,$k$) curvilinear coordinate system in which 
    163168the equations of the ocean circulation model are formulated, 
    164 takes the following form \citep{Redi_JPO82}: 
     169takes the following form \citep{redi_JPO82}: 
    165170 
    166171\begin{equation} 
     
    169174  \left[ {{ 
    170175        \begin{array}{*{20}c} 
    171           {1+a_1 ^2} \hfill & {-a_1 a_2 } \hfill & {-a_1 } \hfill \\ 
    172           {-a_1 a_2 } \hfill & {1+a_2 ^2} \hfill & {-a_2 } \hfill \\ 
    173           {-a_1 } \hfill & {-a_2 } \hfill & {\varepsilon +a_1 ^2+a_2 ^2} \hfill \\ 
     176          {1+a_2 ^2 +\varepsilon a_1 ^2} \hfill & {-a_1 a_2 (1-\varepsilon)} \hfill & {-a_1 (1-\varepsilon) } \hfill \\ 
     177          {-a_1 a_2 (1-\varepsilon) } \hfill & {1+a_1 ^2 +\varepsilon a_2 ^2} \hfill & {-a_2 (1-\varepsilon)} \hfill \\ 
     178          {-a_1 (1-\varepsilon)} \hfill & {-a_2 (1-\varepsilon)} \hfill & {\varepsilon +a_1 ^2+a_2 ^2} \hfill \\ 
    174179        \end{array} 
    175180      }} \right] 
    176181\end{equation} 
    177 where ($a_1$, $a_2$) are the isopycnal slopes in ($\textbf{i}$, $\textbf{j}$) directions, relative to geopotentials: 
     182where ($a_1$, $a_2$) are $(-1) \times$ the isopycnal slopes in 
     183($\textbf{i}$, $\textbf{j}$) directions, relative to geopotentials (or 
     184equivalently the slopes of the geopotential surfaces in the isopycnal 
     185coordinate framework): 
    178186\[ 
    179187  a_1 =\frac{e_3 }{e_1 }\left( {\frac{\partial \rho }{\partial i}} \right)\left( {\frac{\partial \rho }{\partial k}} \right)^{-1} 
     
    182190  \right)\left( {\frac{\partial \rho }{\partial k}} \right)^{-1} 
    183191\] 
    184  
    185 In practice, isopycnal slopes are generally less than $10^{-2}$ in the ocean, 
    186 so $\textbf {A}_{\textbf I}$ can be simplified appreciably \citep{Cox1987}: 
     192and, as before, $\epsilon = A^{vT} / A^{lT}$. 
     193 
     194In practice, $\epsilon$ is small and isopycnal slopes are generally less than $10^{-2}$ in the ocean, 
     195so $\textbf {A}_{\textbf I}$ can be simplified appreciably \citep{cox_OM87}. Keeping leading order terms\footnote{Apart from the (1,0)  
     196and (0,1) elements which are set to zero. See \citet{griffies_bk04}, section 14.1.4.1 for a discussion of this point.}: 
    187197\begin{subequations} 
    188198  \label{apdx:B4} 
     
    226236The isopycnal diffusion operator \autoref{apdx:B4}, 
    227237\autoref{apdx:B_ldfiso} conserves tracer quantity and dissipates its square. 
    228 The demonstration of the first property is trivial as \autoref{apdx:B4} is the divergence of fluxes. 
    229 Let us demonstrate the second one: 
     238As \autoref{apdx:B4} is the divergence of a flux, the demonstration of the first property is trivial, providing that the flux normal to the boundary is zero  
     239(as it is when $A_h$ is zero at the boundary). Let us demonstrate the second one: 
    230240\[ 
    231241  \iiint\limits_D T\;\nabla .\left( {\textbf{A}}_{\textbf{I}} \nabla T \right)\,dv 
     
    236246  { 
    237247  \begin{array}{*{20}l} 
    238     \nabla T\;.\left( {{\rm {\bf A}}_{\rm {\bf I}} \nabla T} 
     248    \nabla T\;.\left( {{\mathrm {\mathbf A}}_{\mathrm {\mathbf I}} \nabla T} 
    239249    \right)&=A^{lT}\left[ {\left( {\frac{\partial T}{\partial i}} \right)^2-2a_1 
    240250             \frac{\partial T}{\partial i}\frac{\partial T}{\partial k}+\left( 
     
    246256             j}-a_2 \frac{\partial T}{\partial k}} \right)^2} 
    247257             +\varepsilon \left(\frac{\partial T}{\partial k}\right) ^2\right]      \\ 
    248            & \geq 0 
     258           & \geq 0 .  
    249259  \end{array} 
    250260             } 
     
    275285\end{equation} 
    276286 
    277 where ($r_1$, $r_2$) are the isopycnal slopes in ($\textbf{i}$, $\textbf{j}$) directions, 
    278 relative to $s$-coordinate surfaces: 
     287where ($r_1$, $r_2$) are $(-1)\times$ the isopycnal slopes in ($\textbf{i}$, $\textbf{j}$) directions, 
     288relative to $s$-coordinate surfaces (or equivalently the slopes of the 
     289$s$-coordinate surfaces in the isopycnal coordinate framework): 
    279290\[ 
    280291  r_1 =\frac{e_3 }{e_1 }\left( {\frac{\partial \rho }{\partial i}} \right)\left( {\frac{\partial \rho }{\partial s}} \right)^{-1} 
     
    284295\] 
    285296 
    286 To prove \autoref{apdx:B5} by direct re-expression of \autoref{apdx:B_ldfiso} is straightforward, but laborious. 
     297To prove \autoref{apdx:B_ldfiso_s} by direct re-expression of \autoref{apdx:B_ldfiso} is straightforward, but laborious. 
    287298An easier way is first to note (by reversing the derivation of \autoref{sec:B_2} from \autoref{sec:B_1} ) that 
    288299the weak-slope operator may be \emph{exactly} reexpressed in non-orthogonal $i,j,\rho$-coordinates as 
     
    306317the (rotated,orthogonal) isoneutral axes to the non-orthogonal $i,j,\rho$-coordinates. 
    307318The further transformation into $i,j,s$-coordinates is exact, whatever the steepness of the $s$-surfaces, 
    308 in the same way as the transformation of horizontal/vertical Laplacian diffusion in $z$-coordinates, 
     319in the same way as the transformation of horizontal/vertical Laplacian diffusion in $z$-coordinates in 
    309320\autoref{sec:B_1} onto $s$-coordinates is exact, however steep the $s$-surfaces. 
    310321 
     
    316327\label{sec:B_3} 
    317328 
    318 The second order momentum diffusion operator (Laplacian) in the $z$-coordinate is found by 
     329The second order momentum diffusion operator (Laplacian) in $z$-coordinates is found by 
    319330applying \autoref{eq:PE_lap_vector}, the expression for the Laplacian of a vector, 
    320331to the horizontal velocity vector: 
     
    361372\end{align*} 
    362373Using \autoref{eq:PE_div}, the definition of the horizontal divergence, 
    363 the third componant of the second vector is obviously zero and thus : 
     374the third component of the second vector is obviously zero and thus : 
    364375\[ 
    365   \Delta {\textbf{U}}_h = \nabla _h \left( \chi \right) - \nabla _h \times \left( \zeta \right) + \frac {1}{e_3 } \frac {\partial }{\partial k} \left( {\frac {1}{e_3 } \frac{\partial {\textbf{ U}}_h }{\partial k}} \right) 
     376  \Delta {\textbf{U}}_h = \nabla _h \left( \chi \right) - \nabla _h \times \left( \zeta \textbf{k} \right) + \frac {1}{e_3 } \frac {\partial }{\partial k} \left( {\frac {1}{e_3 } \frac{\partial {\textbf{ U}}_h }{\partial k}} \right) .  
    366377\] 
    367378 
     
    379390  - \nabla _h \times \left( {A^{lm}\;\zeta \;{\textbf{k}}} \right) 
    380391  + \frac{1}{e_3 }\frac{\partial }{\partial k}\left( {\frac{A^{vm}\;}{e_3 } 
    381       \frac{\partial {\rm {\bf U}}_h }{\partial k}} \right) \\ 
     392      \frac{\partial {\mathrm {\mathbf U}}_h }{\partial k}} \right) , \\ 
    382393\end{equation} 
    383394that is, in expanded form: 
     
    386397  & = \frac{1}{e_1} \frac{\partial \left( {A^{lm}\chi   } \right)}{\partial i} 
    387398    -\frac{1}{e_2} \frac{\partial \left( {A^{lm}\zeta } \right)}{\partial j} 
    388     +\frac{1}{e_3} \frac{\partial u}{\partial k}      \\ 
     399    +\frac{1}{e_3} \frac{\partial }{\partial k} \left( \frac{A^{vm}}{e_3} \frac{\partial u}{\partial k} \right)   ,   \\ 
    389400  D^{\textbf{U}}_v 
    390401  & = \frac{1}{e_2 }\frac{\partial \left( {A^{lm}\chi   } \right)}{\partial j} 
    391402    +\frac{1}{e_1 }\frac{\partial \left( {A^{lm}\zeta } \right)}{\partial i} 
    392     +\frac{1}{e_3} \frac{\partial v}{\partial k} 
     403    +\frac{1}{e_3} \frac{\partial }{\partial k} \left( \frac{A^{vm}}{e_3} \frac{\partial v}{\partial k} \right) . 
    393404\end{align*} 
    394405 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_E.tex

    r10442 r11422  
    4949 
    5050This results in a dissipatively dominant (\ie hyper-diffusive) truncation error 
    51 \citep{Shchepetkin_McWilliams_OM05}. 
    52 The overall performance of the advection scheme is similar to that reported in \cite{Farrow1995}. 
     51\citep{shchepetkin.mcwilliams_OM05}. 
     52The overall performance of the advection scheme is similar to that reported in \cite{farrow.stevens_JPO95}. 
    5353It is a relatively good compromise between accuracy and smoothness. 
    5454It is not a \emph{positive} scheme meaning false extrema are permitted but 
     
    6565the second term which is the diffusive part of the scheme, is evaluated using the \textit{before} velocity 
    6666(forward in time). 
    67 This is discussed by \citet{Webb_al_JAOT98} in the context of the Quick advection scheme. 
     67This is discussed by \citet{webb.de-cuevas.ea_JAOT98} in the context of the Quick advection scheme. 
    6868UBS and QUICK schemes only differ by one coefficient. 
    69 Substituting 1/6 with 1/8 in (\autoref{eq:tra_adv_ubs}) leads to the QUICK advection scheme \citep{Webb_al_JAOT98}. 
     69Substituting 1/6 with 1/8 in (\autoref{eq:tra_adv_ubs}) leads to the QUICK advection scheme \citep{webb.de-cuevas.ea_JAOT98}. 
    7070This option is not available through a namelist parameter, since the 1/6 coefficient is hard coded. 
    7171Nevertheless it is quite easy to make the substitution in \mdl{traadv\_ubs} module and obtain a QUICK scheme. 
     
    8080$\tau_w^{ubs}$ will be evaluated using either \textit{(a)} a centered $2^{nd}$ order scheme, 
    8181or \textit{(b)} a TVD scheme, or \textit{(c)} an interpolation based on conservative parabolic splines following 
    82 \citet{Shchepetkin_McWilliams_OM05} implementation of UBS in ROMS, or \textit{(d)} an UBS. 
     82\citet{shchepetkin.mcwilliams_OM05} implementation of UBS in ROMS, or \textit{(d)} an UBS. 
    8383The $3^{rd}$ case has dispersion properties similar to an eight-order accurate conventional scheme. 
    8484 
     
    255255\subsection{Griffies iso-neutral diffusion operator} 
    256256 
    257 Let try to define a scheme that get its inspiration from the \citet{Griffies_al_JPO98} scheme, 
     257Let try to define a scheme that get its inspiration from the \citet{griffies.gnanadesikan.ea_JPO98} scheme, 
    258258but is formulated within the \NEMO framework 
    259259(\ie using scale factors rather than grid-size and having a position of $T$-points that 
     
    272272Nevertheless, this technique works fine for $T$ and $S$ as they are active tracers 
    273273(\ie they enter the computation of density), but it does not work for a passive tracer. 
    274 \citep{Griffies_al_JPO98} introduce a different way to discretise the off-diagonal terms that 
     274\citep{griffies.gnanadesikan.ea_JPO98} introduce a different way to discretise the off-diagonal terms that 
    275275nicely solve the problem. 
    276276The idea is to get rid of combinations of an averaged in one direction combined with 
     
    308308\begin{figure}[!ht] 
    309309  \begin{center} 
    310     \includegraphics[width=0.70\textwidth]{Fig_ISO_triad} 
     310    \includegraphics[width=\textwidth]{Fig_ISO_triad} 
    311311    \caption{ 
    312312      \protect\label{fig:ISO_triad} 
     
    508508\] 
    509509 
    510 \citep{Griffies_JPO98} introduces another way to implement the eddy induced advection, the so-called skew form. 
     510\citep{griffies_JPO98} introduces another way to implement the eddy induced advection, the so-called skew form. 
    511511It is based on a transformation of the advective fluxes using the non-divergent nature of the eddy induced velocity. 
    512512For example in the (\textbf{i},\textbf{k}) plane, the tracer advective fluxes can be transformed as follows: 
     
    574574The horizontal component reduces to the one use for an horizontal laplacian operator and 
    575575the vertical one keeps the same complexity, but not more. 
    576 This property has been used to reduce the computational time \citep{Griffies_JPO98}, 
     576This property has been used to reduce the computational time \citep{griffies_JPO98}, 
    577577but it is not of practical use as usually $A \neq A_e$. 
    578578Nevertheless this property can be used to choose a discret form of \autoref{eq:eiv_skew_continuous} which 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/annex_iso.tex

    r10442 r11422  
    44\newcommand{\rML}[1][i]{\ensuremath{_{\mathrm{ML}\,#1}}} 
    55\newcommand{\rMLt}[1][i]{\tilde{r}_{\mathrm{ML}\,#1}} 
    6 \newcommand{\triad}[6][]{\ensuremath{{}_{#2}^{#3}{\mathbb{#4}_{#1}}_{#5}^{\,#6}}} 
     6%% Move to ../../global/new_cmds.tex to avoid error with \listoffigures 
     7%\newcommand{\triad}[6][]{\ensuremath{{}_{#2}^{#3}{\mathbb{#4}_{#1}}_{#5}^{\,#6}} 
    78\newcommand{\triadd}[5]{\ensuremath{{}_{#1}^{#2}{\mathbb{#3}}_{#4}^{\,#5}}} 
    89\newcommand{\triadt}[5]{\ensuremath{{}_{#1}^{#2}{\tilde{\mathbb{#3}}}_{#4}^{\,#5}}} 
     
    5253  the vertical skew flux is further reduced to ensure no vertical buoyancy flux, 
    5354  giving an almost pure horizontal diffusive tracer flux within the mixed layer. 
    54   This is similar to the tapering suggested by \citet{Gerdes1991}. See \autoref{subsec:Gerdes-taper} 
     55  This is similar to the tapering suggested by \citet{gerdes.koberle.ea_CD91}. See \autoref{subsec:Gerdes-taper} 
    5556\item[\np{ln\_botmix\_triad}] 
    5657  See \autoref{sec:iso_bdry}.  
     
    7172\label{sec:iso} 
    7273 
    73 We have implemented into \NEMO a scheme inspired by \citet{Griffies_al_JPO98}, 
     74We have implemented into \NEMO a scheme inspired by \citet{griffies.gnanadesikan.ea_JPO98}, 
    7475but formulated within the \NEMO framework, using scale factors rather than grid-sizes. 
    7576 
     
    194195\subsection{Expression of the skew-flux in terms of triad slopes} 
    195196 
    196 \citep{Griffies_al_JPO98} introduce a different discretization of the off-diagonal terms that 
     197\citep{griffies.gnanadesikan.ea_JPO98} introduce a different discretization of the off-diagonal terms that 
    197198nicely solves the problem. 
    198199% Instead of multiplying the mean slope calculated at the $u$-point by 
     
    201202\begin{figure}[tb] 
    202203  \begin{center} 
    203     \includegraphics[width=1.05\textwidth]{Fig_GRIFF_triad_fluxes} 
     204    \includegraphics[width=\textwidth]{Fig_GRIFF_triad_fluxes} 
    204205    \caption{ 
    205206      \protect\label{fig:ISO_triad} 
     
    265266\begin{figure}[tb] 
    266267  \begin{center} 
    267     \includegraphics[width=0.80\textwidth]{Fig_GRIFF_qcells} 
     268    \includegraphics[width=\textwidth]{Fig_GRIFF_qcells} 
    268269    \caption{ 
    269270      \protect\label{fig:qcells} 
     
    473474 
    474475To complete the discretization we now need only specify the triad volumes $_i^k\mathbb{V}_{i_p}^{k_p}$. 
    475 \citet{Griffies_al_JPO98} identifies these $_i^k\mathbb{V}_{i_p}^{k_p}$ as the volumes of the quarter cells, 
     476\citet{griffies.gnanadesikan.ea_JPO98} identifies these $_i^k\mathbb{V}_{i_p}^{k_p}$ as the volumes of the quarter cells, 
    476477defined in terms of the distances between $T$, $u$,$f$ and $w$-points. 
    477478This is the natural discretization of \autoref{eq:cts-var}. 
     
    658659\begin{figure}[h] 
    659660  \begin{center} 
    660     \includegraphics[width=0.60\textwidth]{Fig_GRIFF_bdry_triads} 
     661    \includegraphics[width=\textwidth]{Fig_GRIFF_bdry_triads} 
    661662    \caption{ 
    662663      \protect\label{fig:bdry_triads} 
     
    685686As discussed in \autoref{subsec:LDF_slp_iso}, 
    686687iso-neutral slopes relative to geopotentials must be bounded everywhere, 
    687 both for consistency with the small-slope approximation and for numerical stability \citep{Cox1987, Griffies_Bk04}. 
     688both for consistency with the small-slope approximation and for numerical stability \citep{cox_OM87, griffies_bk04}. 
    688689The bound chosen in \NEMO is applied to each component of the slope separately and 
    689690has a value of $1/100$ in the ocean interior. 
     
    732733\[ 
    733734  % \label{eq:iso_tensor_ML} 
    734   D^{lT}=\nabla {\rm {\bf .}}\left( {A^{lT}\;\Re \;\nabla T} \right) \qquad 
     735  D^{lT}=\nabla {\mathrm {\mathbf .}}\left( {A^{lT}\;\Re \;\nabla T} \right) \qquad 
    735736  \mbox{with}\quad \;\;\Re =\left( {{ 
    736737        \begin{array}{*{20}c} 
     
    829830    (\eg the green triad $i_p=1/2,k_p=-1/2$) are tapered to the appropriate basal triad.} 
    830831  % } 
    831   \includegraphics[width=0.60\textwidth]{Fig_GRIFF_MLB_triads} 
     832  \includegraphics[width=\textwidth]{Fig_GRIFF_MLB_triads} 
    832833\end{figure} 
    833834% >>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     
    847848\[ 
    848849  % \label{eq:iso_tensor_ML2} 
    849   D^{lT}=\nabla {\rm {\bf .}}\left( {A^{lT}\;\Re \;\nabla T} \right) \qquad 
     850  D^{lT}=\nabla {\mathrm {\mathbf .}}\left( {A^{lT}\;\Re \;\nabla T} \right) \qquad 
    850851  \mbox{with}\quad \;\;\Re =\left( {{ 
    851852        \begin{array}{*{20}c} 
     
    859860\footnote{ 
    860861  To ensure good behaviour where horizontal density gradients are weak, 
    861   we in fact follow \citet{Gerdes1991} and 
     862  we in fact follow \citet{gerdes.koberle.ea_CD91} and 
    862863  set $\rML^*=\mathrm{sgn}(\tilde{r}_i)\min(|\rMLt^2/\tilde{r}_i|,|\tilde{r}_i|)-\sigma_i$. 
    863864} 
     
    865866This approach is similar to multiplying the iso-neutral diffusion coefficient by 
    866867$\tilde{r}_{\mathrm{max}}^{-2}\tilde{r}_i^{-2}$ for steep slopes, 
    867 as suggested by \citet{Gerdes1991} (see also \citet{Griffies_Bk04}). 
     868as suggested by \citet{gerdes.koberle.ea_CD91} (see also \citet{griffies_bk04}). 
    868869Again it is applied separately to each triad $_i^k\mathbb{R}_{i_p}^{k_p}$ 
    869870 
     
    925926 
    926927However, when \np{ln\_traldf\_triad} is set true, 
    927 \NEMO instead implements eddy induced advection according to the so-called skew form \citep{Griffies_JPO98}. 
     928\NEMO instead implements eddy induced advection according to the so-called skew form \citep{griffies_JPO98}. 
    928929It is based on a transformation of the advective fluxes using the non-divergent nature of the eddy induced velocity. 
    929930For example in the (\textbf{i},\textbf{k}) plane, 
     
    11391140it is equivalent to a horizontal eiv (eddy-induced velocity) that is uniform within the mixed layer 
    11401141\autoref{eq:eiv_v}. 
    1141 This ensures that the eiv velocities do not restratify the mixed layer \citep{Treguier1997,Danabasoglu_al_2008}. 
     1142This ensures that the eiv velocities do not restratify the mixed layer \citep{treguier.held.ea_JPO97,danabasoglu.ferrari.ea_JC08}. 
    11421143Equivantly, in terms of the skew-flux formulation we use here, 
    11431144the linear slope tapering within the mixed-layer gives a linearly varying vertical flux, 
     
    11531154$uw$ (integer +1/2 $i$, integer $j$, integer +1/2 $k$) and $vw$ (integer $i$, integer +1/2 $j$, integer +1/2 $k$) 
    11541155points (see Table \autoref{tab:cell}) respectively. 
    1155 We follow \citep{Griffies_Bk04} and calculate the streamfunction at a given $uw$-point from 
     1156We follow \citep{griffies_bk04} and calculate the streamfunction at a given $uw$-point from 
    11561157the surrounding four triads according to: 
    11571158\[ 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_ASM.tex

    r10442 r11422  
    88\label{chap:ASM} 
    99 
    10 Authors: D. Lea,  M. Martin, K. Mogensen, A. Weaver, ...   % do we keep 
     10\minitoc 
    1111 
    12 \minitoc 
     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} 
    1321 
    1422\newpage 
    1523 
    1624The ASM code adds the functionality to apply increments to the model variables: temperature, salinity, 
    17 sea surface height, velocity and sea ice concentration.  
     25sea surface height, velocity and sea ice concentration. 
    1826These are read into the model from a NetCDF file which may be produced by separate data assimilation code. 
    1927The code can also output model background fields which are used as an input to data assimilation code. 
     
    3745it may be preferable to introduce the increment gradually into the ocean model in order to 
    3846minimize spurious adjustment processes. 
    39 This technique is referred to as Incremental Analysis Updates (IAU) \citep{Bloom_al_MWR96}. 
     47This technique is referred to as Incremental Analysis Updates (IAU) \citep{bloom.takacs.ea_MWR96}. 
    4048IAU is a common technique used with 3D assimilation methods such as 3D-Var or OI. 
    4149IAU is used when \np{ln\_asmiau} is set to true. 
    4250 
    43 With IAU, the model state trajectory ${\bf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$) 
     51With IAU, the model state trajectory ${\mathbf x}$ in the assimilation window ($t_{0} \leq t_{i} \leq t_{N}$) 
    4452is corrected by adding the analysis increments for temperature, salinity, horizontal velocity and SSH as 
    4553additional tendency terms to the prognostic equations: 
    4654\begin{align*} 
    4755  % \label{eq:wa_traj_iau} 
    48   {\bf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\bf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\bf x}^{a} 
     56  {\mathbf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\mathbf x}^{b}(t_{0})] \; + \; F_{i} \delta \tilde{\mathbf x}^{a} 
    4957\end{align*} 
    50 where $F_{i}$ is a weighting function for applying the increments $\delta\tilde{\bf x}^{a}$ defined such that 
     58where $F_{i}$ is a weighting function for applying the increments $\delta\tilde{\mathbf x}^{a}$ defined such that 
    5159$\sum_{i=1}^{N} F_{i}=1$. 
    52 ${\bf x}^b$ denotes the model initial state and ${\bf x}^a$ is the model state after the increments are applied. 
     60${\mathbf x}^b$ denotes the model initial state and ${\mathbf x}^a$ is the model state after the increments are applied. 
    5361To control the adjustment time of the model to the increment, 
    5462the increment can be applied over an arbitrary sub-window, $t_{m} \leq t_{i} \leq t_{n}$, 
     
    5664Typically the increments are spread evenly over the full window. 
    5765In addition, two different weighting functions have been implemented. 
    58 The first function employs constant weights,  
     66The first function (namelist option \np{niaufn} = 0) employs constant weights, 
    5967\begin{align} 
    6068  \label{eq:F1_i} 
     
    6270  =\left\{ 
    6371  \begin{array}{ll} 
    64     0     &    {\rm if} \; \; \; t_{i} < t_{m}                \\ 
    65     1/M &    {\rm if} \; \; \; t_{m} < t_{i} \leq t_{n} \\ 
    66     0     &    {\rm if} \; \; \; t_{i} > t_{n} 
     72    0     &    {\mathrm if} \; \; \; t_{i} < t_{m}                \\ 
     73    1/M &    {\mathrm if} \; \; \; t_{m} < t_{i} \leq t_{n} \\ 
     74    0     &    {\mathrm if} \; \; \; t_{i} > t_{n} 
    6775  \end{array} 
    68             \right.  
     76            \right. 
    6977\end{align} 
    7078where $M = m-n$. 
    71 The second function employs peaked hat-like weights in order to give maximum weight in the centre of the sub-window, 
     79The 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, 
    7280with the weighting reduced linearly to a small value at the window end-points: 
    7381\begin{align} 
     
    7684  =\left\{ 
    7785  \begin{array}{ll} 
    78     0                           &    {\rm if} \; \; \; t_{i}       <     t_{m}                        \\ 
    79     \alpha \, i               &    {\rm if} \; \; \; t_{m}    \leq t_{i}    \leq   t_{M/2}   \\ 
    80     \alpha \, (M - i +1) &    {\rm if} \; \; \; t_{M/2}  <    t_{i}    \leq   t_{n}       \\ 
    81     0                            &   {\rm if} \; \; \; t_{i}        >    t_{n} 
     86    0                           &    {\mathrm if} \; \; \; t_{i}       <     t_{m}                        \\ 
     87    \alpha \, i               &    {\mathrm if} \; \; \; t_{m}    \leq t_{i}    \leq   t_{M/2}   \\ 
     88    \alpha \, (M - i +1) &    {\mathrm if} \; \; \; t_{M/2}  <    t_{i}    \leq   t_{n}       \\ 
     89    0                            &   {\mathrm if} \; \; \; t_{i}        >    t_{n} 
    8290  \end{array} 
    8391                                   \right. 
    8492\end{align} 
    85 where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even.  
     93where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even. 
    8694The weights described by \autoref{eq:F2_i} provide a smoother transition of the analysis trajectory from 
    8795one assimilation cycle to the next than that described by \autoref{eq:F1_i}. 
     
    92100\label{sec:ASM_div_dmp} 
    93101 
    94 The velocity increments may be initialized by the iterative application of a divergence damping operator. 
    95 In iteration step $n$ new estimates of velocity increments $u^{n}_I$ and $v^{n}_I$ are updated by: 
     102It is quite challenging for data assimilation systems to provide non-divergent velocity increments. 
     103Applying divergent velocity increments will likely cause spurious vertical velocities in the model. This section describes a method to take velocity increments provided to \NEMO ($u^0_I$ and $v^0_I$) and adjust them by the iterative application of a divergence damping operator. The method is also described in \citet{dobricic.pinardi.ea_OS07}. 
     104 
     105In iteration step $n$ (starting at $n=1$) new estimates of velocity increments $u^{n}_I$ and $v^{n}_I$ are updated by: 
     106 
    96107\begin{equation} 
    97108  \label{eq:asm_dmp} 
     
    105116  \right., 
    106117\end{equation} 
    107 where 
     118 
     119where the divergence is defined as 
     120 
    108121\[ 
    109122  % \label{eq:asm_div} 
     
    112125      +\delta_j \left[ {e_{1v}\,e_{3v}\,v^{n-1}_I} \right]} \right). 
    113126\] 
    114 By the application of \autoref{eq:asm_dmp} and \autoref{eq:asm_dmp} the divergence is filtered in each iteration, 
     127 
     128By the application of \autoref{eq:asm_dmp} the divergence is filtered in each iteration, 
    115129and the vorticity is left unchanged. 
    116130In the presence of coastal boundaries with zero velocity increments perpendicular to the coast 
     
    118132This type of the initialisation reduces the vertical velocity magnitude and 
    119133alleviates the problem of the excessive unphysical vertical mixing in the first steps of the model integration 
    120 \citep{Talagrand_JAS72, Dobricic_al_OS07}. 
     134\citep{talagrand_JAS72, dobricic.pinardi.ea_OS07}. 
    121135Diffusion coefficients are defined as $A_D = \alpha e_{1t} e_{2t}$, where $\alpha = 0.2$. 
    122136The divergence damping is activated by assigning to \np{nn\_divdmp} in the \textit{nam\_asminc} namelist 
    123137a value greater than zero. 
    124 By choosing this value to be of the order of 100 the increments in 
    125 the vertical velocity will be significantly reduced. 
     138This 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. 
    126139 
    127140 
     
    131144\label{sec:ASM_details} 
    132145 
    133 Here we show an example \ngn{namasm} namelist and the header of an example assimilation increments file on 
     146Here we show an example \ngn{nam\_asminc} namelist and the header of an example assimilation increments file on 
    134147the ORCA2 grid. 
    135148 
    136 %------------------------------------------namasm----------------------------------------------------- 
     149%------------------------------------------nam_asminc----------------------------------------------------- 
    137150% 
    138151\nlst{nam_asminc} 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_CONFIG.tex

    r10442 r11422  
    1818\label{sec:CFG_intro} 
    1919 
    20 The purpose of this part of the manual is to introduce the \NEMO reference configurations. 
     20The purpose of this part of the manual is to introduce the NEMO reference configurations. 
    2121These configurations are offered as means to explore various numerical and physical options, 
    2222thus allowing the user to verify that the code is performing in a manner consistent with that we are running. 
     
    2424The reference configurations also provide a sense for some of the options available in the code, 
    2525though by no means are all options exercised in the reference configurations. 
     26Configuration is defined manually through the \textit{namcfg} namelist variables. 
    2627 
    2728%------------------------------------------namcfg---------------------------------------------------- 
     
    3334% 1D model configuration 
    3435% ================================================================ 
    35 \section{C1D: 1D Water column model (\protect\key{c1d}) } 
     36\section[C1D: 1D Water column model (\texttt{\textbf{key\_c1d}})] 
     37{C1D: 1D Water column model (\protect\key{c1d})} 
    3638\label{sec:CFG_c1d} 
    3739 
    38 BE careful: to be re-written according to suppression of jpizoom and jpjzoom !!!! 
    39  
    40 The 1D model option simulates a stand alone water column within the 3D \NEMO system. 
     40The 1D model option simulates a stand alone water column within the 3D NEMO system. 
    4141It can be applied to the ocean alone or to the ocean-ice system and can include passive tracers or a biogeochemical model. 
    4242It is set up by defining the position of the 1D water column in the grid 
    43 (see \textit{CONFIG/SHARED/namelist\_ref} ).  
     43(see \textit{cfgs/SHARED/namelist\_ref}).  
    4444The 1D model is a very useful tool 
    4545\textit{(a)} to learn about the physics and numerical treatment of vertical mixing processes; 
     
    5050\textit{(d)} to produce extra diagnostics, without the large memory requirement of the full 3D model. 
    5151 
    52 The methodology is based on the use of the zoom functionality over the smallest possible domain: 
    53 a 3x3 domain centered on the grid point of interest, with some extra routines. 
    54 There is no need to define a new mesh, bathymetry, initial state or forcing, 
    55 since the 1D model will use those of the configuration it is a zoom of. 
    56 The chosen grid point is set in \textit{\ngn{namcfg}} namelist by 
    57 setting the \np{jpizoom} and \np{jpjzoom} parameters to the indices of the location of the chosen grid point. 
     52The methodology is based on the configuration of the smallest possible domain: 
     53a 3x3 domain with 75 vertical levels. 
    5854 
    5955The 1D model has some specifies. First, all the horizontal derivatives are assumed to be zero, 
    6056and second, the two components of the velocity are moved on a $T$-point.  
    61 Therefore, defining \key{c1d} changes five main things in the code behaviour:  
     57Therefore, defining \key{c1d} changes some things in the code behaviour:  
    6258\begin{description} 
    6359\item[(1)] 
    64   the lateral boundary condition routine (\rou{lbc\_lnk}) set the value of the central column of 
    65   the 3x3 domain is imposed over the whole domain; 
    66 \item[(3)] 
    67   a call to \rou{lbc\_lnk} is systematically done when reading input data (\ie in \mdl{iom}); 
    68 \item[(3)] 
    6960  a simplified \rou{stp} routine is used (\rou{stp\_c1d}, see \mdl{step\_c1d} module) in which 
    7061  both lateral tendancy terms and lateral physics are not called; 
    71 \item[(4)] 
     62\item[(2)] 
    7263  the vertical velocity is zero 
    7364  (so far, no attempt at introducing a Ekman pumping velocity has been made); 
    74 \item[(5)] 
     65\item[(3)] 
    7566  a simplified treatment of the Coriolis term is performed as $U$- and $V$-points are the same 
    7667  (see \mdl{dyncor\_c1d}). 
    7768\end{description} 
    78 All the relevant \textit{\_c1d} modules can be found in the NEMOGCM/NEMO/OPA\_SRC/C1D directory of 
    79 the \NEMO distribution. 
     69All the relevant \textit{\_c1d} modules can be found in the src/OCE/C1D directory of 
     70the NEMO distribution. 
    8071 
    8172% to be added:  a test case on the yearlong Ocean Weather Station (OWS) Papa dataset of Martin (1985) 
     
    8879 
    8980The ORCA family is a series of global ocean configurations that are run together with 
    90 the LIM sea-ice model (ORCA-LIM) and possibly with PISCES biogeochemical model (ORCA-LIM-PISCES), 
    91 using various resolutions. 
    92 An appropriate namelist is available in \path{CONFIG/ORCA2_LIM3_PISCES/EXP00/namelist_cfg} for ORCA2. 
     81the SI3 model (ORCA-ICE) and possibly with PISCES biogeochemical model (ORCA-ICE-PISCES). 
     82An appropriate namelist is available in \path{cfgs/ORCA2_ICE_PISCES/EXPREF/namelist_cfg} for ORCA2. 
    9383The domain of ORCA2 configuration is defined in \ifile{ORCA\_R2\_zps\_domcfg} file, 
    94 this file is available in tar file in the wiki of NEMO: \\ 
    95 https://forge.ipsl.jussieu.fr/nemo/wiki/Users/ReferenceConfigurations/ORCA2\_LIM3\_PISCES \\ 
     84this file is available in tar file on the NEMO community zenodo platform: \\ 
     85https://doi.org/10.5281/zenodo.2640723 
     86 
    9687In this namelist\_cfg the name of domain input file is set in \ngn{namcfg} block of namelist.  
    9788 
     
    9990\begin{figure}[!t] 
    10091  \begin{center} 
    101     \includegraphics[width=0.98\textwidth]{Fig_ORCA_NH_mesh} 
     92    \includegraphics[width=\textwidth]{Fig_ORCA_NH_mesh} 
    10293    \caption{ 
    10394      \protect\label{fig:MISC_ORCA_msh} 
     
    10697      The two "north pole" are the foci of a series of embedded ellipses (blue curves) which 
    10798      are determined analytically and form the i-lines of the ORCA mesh (pseudo latitudes). 
    108       Then, following \citet{Madec_Imbard_CD96}, the normal to the series of ellipses (red curves) is computed which 
     99      Then, following \citet{madec.imbard_CD96}, the normal to the series of ellipses (red curves) is computed which 
    109100      provides the j-lines of the mesh (pseudo longitudes). 
    110101    } 
     
    119110\label{subsec:CFG_orca_grid} 
    120111 
    121 The ORCA grid is a tripolar is based on the semi-analytical method of \citet{Madec_Imbard_CD96}. 
     112The ORCA grid is a tripolar grid based on the semi-analytical method of \citet{madec.imbard_CD96}. 
    122113It allows to construct a global orthogonal curvilinear ocean mesh which has no singularity point inside 
    123114the computational domain since two north mesh poles are introduced and placed on lands. 
     
    131122\begin{figure}[!tbp] 
    132123  \begin{center} 
    133     \includegraphics[width=1.0\textwidth]{Fig_ORCA_NH_msh05_e1_e2} 
    134     \includegraphics[width=0.80\textwidth]{Fig_ORCA_aniso} 
     124    \includegraphics[width=\textwidth]{Fig_ORCA_NH_msh05_e1_e2} 
     125    \includegraphics[width=\textwidth]{Fig_ORCA_aniso} 
    135126    \caption { 
    136127      \protect\label{fig:MISC_ORCA_e1e2} 
     
    158149 
    159150% ------------------------------------------------------------------------------------------------------------- 
    160 %       ORCA-LIM(-PISCES) configurations 
     151%       ORCA-ICE(-PISCES) configurations 
    161152% ------------------------------------------------------------------------------------------------------------- 
    162153\subsection{ORCA pre-defined resolution} 
     
    199190The ORCA\_R2 configuration has the following specificity: starting from a 2\deg~ORCA mesh, 
    200191local mesh refinements were applied to the Mediterranean, Red, Black and Caspian Seas, 
    201 so that the resolution is 1\deg \time 1\deg there. 
     192so that the resolution is 1\deg~ there. 
    202193A local transformation were also applied with in the Tropics in order to refine the meridional resolution up to 
    203 0.5\deg at the Equator. 
     1940.5\deg~ at the Equator. 
    204195 
    205196The ORCA\_R1 configuration has only a local tropical transformation to refine the meridional resolution up to 
     
    211202For ORCA\_R1 and R025, setting the configuration key to 75 allows to use 75 vertical levels, otherwise 46 are used. 
    212203In the other ORCA configurations, 31 levels are used 
    213 (see \autoref{tab:orca_zgr} %\sfcomment{HERE I need to put new table for ORCA2 values} and \autoref{fig:zgr}). 
    214  
    215 Only the ORCA\_R2 is provided with all its input files in the \NEMO distribution. 
    216 It is very similar to that used as part of the climate model developed at IPSL for the 4th IPCC assessment of 
    217 climate change (Marti et al., 2009). 
    218 It is also the basis for the \NEMO contribution to the Coordinate Ocean-ice Reference Experiments (COREs) 
    219 documented in \citet{Griffies_al_OM09}.  
     204(see \autoref{tab:orca_zgr}). %\sfcomment{HERE I need to put new table for ORCA2 values} and \autoref{fig:zgr}). 
     205 
     206Only the ORCA\_R2 is provided with all its input files in the NEMO distribution. 
     207%It is very similar to that used as part of the climate model developed at IPSL for the 4th IPCC assessment of 
     208%climate change (Marti et al., 2009). 
     209%It is also the basis for the \NEMO contribution to the Coordinate Ocean-ice Reference Experiments (COREs) 
     210%documented in \citet{griffies.biastoch.ea_OM09}.  
    220211 
    221212This version of ORCA\_R2 has 31 levels in the vertical, with the highest resolution (10m) in the upper 150m 
    222213(see \autoref{tab:orca_zgr} and \autoref{fig:zgr}).  
    223214The bottom topography and the coastlines are derived from the global atlas of Smith and Sandwell (1997).  
    224 The default forcing uses the boundary forcing from \citet{Large_Yeager_Rep04} (see \autoref{subsec:SBC_blk_core}),  
     215The default forcing uses the boundary forcing from \citet{large.yeager_rpt04} (see \autoref{subsec:SBC_blk_core}),  
    225216which was developed for the purpose of running global coupled ocean-ice simulations without 
    226217an interactive atmosphere. 
    227 This \citet{Large_Yeager_Rep04} dataset is available through 
     218This \citet{large.yeager_rpt04} dataset is available through 
    228219the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/CORE.html}{GFDL web site}. 
    229 The "normal year" of \citet{Large_Yeager_Rep04} has been chosen of the \NEMO distribution since release v3.3.  
    230  
    231 ORCA\_R2 pre-defined configuration can also be run with an AGRIF zoom over the Agulhas current area 
    232 (\key{agrif} defined) and, by setting the appropriate variables, see \path{CONFIG/SHARED/namelist_ref}. 
     220The "normal year" of \citet{large.yeager_rpt04} has been chosen of the NEMO distribution since release v3.3.  
     221 
     222ORCA\_R2 pre-defined configuration can also be run with multiply online nested zooms (\ie with AGRIF, \key{agrif} defined). This is available as the AGRIF\_DEMO configuration that can be found in the \path{cfgs/AGRIF_DEMO/} directory. 
     223 
    233224A regional Arctic or peri-Antarctic configuration is extracted from an ORCA\_R2 or R05 configurations using 
    234225sponge layers at open boundaries.  
     
    237228%       GYRE family: double gyre basin 
    238229% ------------------------------------------------------------------------------------------------------------- 
    239 \section{GYRE family: double gyre basin } 
     230\section{GYRE family: double gyre basin} 
    240231\label{sec:CFG_gyre} 
    241232 
    242 The GYRE configuration \citep{Levy_al_OM10} has been built to 
     233The GYRE configuration \citep{levy.klein.ea_OM10} has been built to 
    243234simulate the seasonal cycle of a double-gyre box model. 
    244 It consists in an idealized domain similar to that used in the studies of \citet{Drijfhout_JPO94} and 
    245 \citet{Hazeleger_Drijfhout_JPO98, Hazeleger_Drijfhout_JPO99, Hazeleger_Drijfhout_JGR00, Hazeleger_Drijfhout_JPO00}, 
     235It consists in an idealized domain similar to that used in the studies of \citet{drijfhout_JPO94} and 
     236\citet{hazeleger.drijfhout_JPO98, hazeleger.drijfhout_JPO99, hazeleger.drijfhout_JGR00, hazeleger.drijfhout_JPO00}, 
    246237over which an analytical seasonal forcing is applied. 
    247238This allows to investigate the spontaneous generation of a large number of interacting, transient mesoscale eddies  
    248239and their contribution to the large scale circulation.  
    249240 
     241The GYRE configuration run together with the PISCES biogeochemical model (GYRE-PISCES). 
    250242The domain geometry is a closed rectangular basin on the $\beta$-plane centred at $\sim$ 30\deg{N} and 
    251243rotated by 45\deg, 3180~km long, 2120~km wide and 4~km deep (\autoref{fig:MISC_strait_hand}). 
     
    253245The configuration is meant to represent an idealized North Atlantic or North Pacific basin. 
    254246The circulation is forced by analytical profiles of wind and buoyancy fluxes. 
    255 The applied forcings vary seasonally in a sinusoidal manner between winter and summer extrema \citep{Levy_al_OM10}.  
     247The applied forcings vary seasonally in a sinusoidal manner between winter and summer extrema \citep{levy.klein.ea_OM10}.  
    256248The wind stress is zonal and its curl changes sign at 22\deg{N} and 36\deg{N}. 
    257249It forces a subpolar gyre in the north, a subtropical gyre in the wider part of the domain and 
     
    266258The GYRE configuration is set like an analytical configuration. 
    267259Through \np{ln\_read\_cfg}\forcode{ = .false.} in \textit{namcfg} namelist defined in 
    268 the reference configuration \path{CONFIG/GYRE/EXP00/namelist_cfg} 
     260the reference configuration \path{cfgs/GYRE_PISCES/EXPREF/namelist_cfg} 
    269261analytical definition of grid in GYRE is done in usrdef\_hrg, usrdef\_zgr routines. 
    270262Its horizontal resolution (and thus the size of the domain) is determined by 
    271263setting \np{nn\_GYRE} in \ngn{namusr\_def}: \\ 
     264 
    272265\np{jpiglo} $= 30 \times$ \np{nn\_GYRE} + 2   \\ 
     266 
    273267\np{jpjglo} $= 20 \times$ \np{nn\_GYRE} + 2   \\ 
     268 
    274269Obviously, the namelist parameters have to be adjusted to the chosen resolution, 
    275 see the Configurations pages on the NEMO web site (Using NEMO\/Configurations). 
     270see the Configurations pages on the NEMO web site (NEMO Configurations). 
    276271In the vertical, GYRE uses the default 30 ocean levels (\jp{jpk}\forcode{ = 31}) (\autoref{fig:zgr}). 
    277272 
     
    281276even though the physical integrity of the solution can be compromised. 
    282277Benchmark is activate via \np{ln\_bench}\forcode{ = .true.} in \ngn{namusr\_def} in 
    283 namelist \path{CONFIG/GYRE/EXP00/namelist_cfg}. 
     278namelist \path{cfgs/GYRE_PISCES/EXPREF/namelist_cfg}. 
    284279 
    285280%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    286281\begin{figure}[!t] 
    287282  \begin{center} 
    288     \includegraphics[width=1.0\textwidth]{Fig_GYRE} 
     283    \includegraphics[width=\textwidth]{Fig_GYRE} 
    289284    \caption{ 
    290285      \protect\label{fig:GYRE} 
    291286      Snapshot of relative vorticity at the surface of the model domain in GYRE R9, R27 and R54. 
    292       From \citet{Levy_al_OM10}. 
     287      From \citet{levy.klein.ea_OM10}. 
    293288    } 
    294289  \end{center} 
     
    304299The AMM, Atlantic Margins Model, is a regional model covering the Northwest European Shelf domain on 
    305300a regular lat-lon grid at approximately 12km horizontal resolution. 
    306 The appropriate \textit{\&namcfg} namelist  is available in \textit{CONFIG/AMM12/EXP00/namelist\_cfg}. 
     301The appropriate \textit{\&namcfg} namelist  is available in \textit{cfgs/AMM12/EXPREF/namelist\_cfg}. 
    307302It is used to build the correct dimensions of the AMM domain. 
    308303 
    309304This configuration tests several features of NEMO functionality specific to the shelf seas. 
    310 In particular, the AMM uses $S$-coordinates in the vertical rather than $z$-coordinates and 
    311 is forced with tidal lateral boundary conditions using a flather boundary condition from the BDY module. 
    312 The AMM configuration uses the GLS (\key{zdfgls}) turbulence scheme, 
    313 the VVL non-linear free surface(\key{vvl}) and time-splitting (\key{dynspg\_ts}). 
     305In particular, the AMM uses $s$-coordinates in the vertical rather than $z$-coordinates and 
     306is forced with tidal lateral boundary conditions using a Flather boundary condition from the BDY module. 
     307Also specific to the AMM configuration is the use of the GLS turbulence scheme (\np{ln\_zdfgls} \forcode{= .true.}). 
    314308 
    315309In addition to the tidal boundary condition the model may also take open boundary conditions from 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DIA.tex

    r10509 r11422  
    1010\minitoc 
    1111 
     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 
    1225\newpage 
    1326 
     
    1528%       Old Model Output  
    1629% ================================================================ 
    17 \section{Old model output (default)} 
     30\section{Model output} 
    1831\label{sec:DIA_io_old} 
    1932 
     
    2538the same run performed in one step. 
    2639It should be noted that this requires that the restart file contains two consecutive time steps for 
    27 all the prognostic variables, and that it is saved in the same binary format as the one used by the computer that 
    28 is to read it (in particular, 32 bits binary IEEE format must not be used for this file). 
     40all the prognostic variables. 
    2941 
    3042The output listing and file(s) are predefined but should be checked and eventually adapted to the user's needs. 
     
    3850the writing work is distributed over the processors in massively parallel computing. 
    3951A complete description of the use of this I/O server is presented in the next section. 
    40  
    41 By default, \key{iomput} is not defined, 
    42 NEMO produces NetCDF with the old IOIPSL library which has been kept for compatibility and its easy installation. 
    43 However, the IOIPSL library is quite inefficient on parallel machines and, since version 3.2, 
    44 many diagnostic options have been added presuming the use of \key{iomput}. 
    45 The usefulness of the default IOIPSL-based option is expected to reduce with each new release. 
    46 If \key{iomput} is not defined, output files and content are defined in the \mdl{diawri} module and 
    47 contain mean (or instantaneous if \key{diainstant} is defined) values over a regular period of 
    48 nn\_write time-steps (namelist parameter).  
    4952 
    5053%\gmcomment{                    % start of gmcomment 
     
    9194in a very easy way. 
    9295All details of iomput functionalities are listed in the following subsections. 
    93 Examples of the XML files that control the outputs can be found in: \path{NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef.xml}, 
    94 \path{NEMOGCM/CONFIG/SHARED/field_def.xml} and \path{NEMOGCM/CONFIG/SHARED/domain_def.xml}. \\ 
     96Examples of the XML files that control the outputs can be found in:  
     97\path{cfgs/ORCA2_ICE_PISCES/EXPREF/iodef.xml}, 
     98\path{cfgs/SHARED/field_def_nemo-oce.xml}, 
     99\path{cfgs/SHARED/field_def_nemo-pisces.xml}, 
     100\path{cfgs/SHARED/field_def_nemo-ice.xml} and \path{cfgs/SHARED/domain_def_nemo.xml}. \\ 
    95101 
    96102The second functionality targets output performance when running in parallel (\key{mpp\_mpi}). 
     
    101107 
    102108In version 3.6, the iom\_put interface depends on 
    103 an external code called \href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/branchs/xios-1.0}{XIOS-1.0}  
     109an external code called \href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/branchs/xios-2.5}{XIOS-2.5}  
    104110(use of revision 618 or higher is required). 
    105111This new IO server can take advantage of the parallel I/O functionality of NetCDF4 to 
     
    168174\xmlline|<variable id="using_server" type="bool"></variable>| 
    169175 
    170 The {\tt using\_server} setting determines whether or not the server will be used in \textit{attached mode} 
    171 (as a library) [{\tt> false <}] or in \textit{detached mode} 
    172 (as an external executable on N additional, dedicated cpus) [{\tt > true <}]. 
     176The {\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 <}]. 
    173179The \textit{attached mode} is simpler to use but much less efficient for massively parallel applications. 
    174180The type of each file can be either ''multiple\_file'' or ''one\_file''. 
     
    207213\subsubsection{Control of XIOS: the context in iodef.xml} 
    208214 
    209 As well as the {\tt using\_server} flag, other controls on the use of XIOS are set in the XIOS context in iodef.xml. 
     215As well as the {\ttfamily using\_server} flag, other controls on the use of XIOS are set in the XIOS context in iodef.xml. 
    210216See the XML basics section below for more details on XML syntax and rules. 
    211217 
     
    257263See the installation guide on the \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS} wiki for help and guidance. 
    258264NEMO will need to link to the compiled XIOS library. 
    259 The \href{https://forge.ipsl.jussieu.fr/nemo/wiki/Users/ModelInterfacing/InputsOutputs#Inputs-OutputsusingXIOS} 
    260 {XIOS with NEMO} guide provides an example illustration of how this can be achieved. 
     265The \href{https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/guide/html/install.html#extract-and-install-xios} 
     266{Extract and install XIOS} guide provides an example illustration of how this can be achieved. 
    261267 
    262268\subsubsection{Add your own outputs} 
     
    269275\begin{enumerate} 
    270276\item[1.] 
    271   in NEMO code, add a \forcode{CALL iom\_put( 'identifier', array )} where you want to output a 2D or 3D array. 
     277  in NEMO code, add a \forcode{CALL iom_put( 'identifier', array )} where you want to output a 2D or 3D array. 
    272278\item[2.] 
    273279  If necessary, add \forcode{USE iom ! I/O manager library} to the list of used modules in 
     
    442448\xmlline|<context src="./nemo_def.xml" />| 
    443449  
    444 \noindent In NEMO, by default, the field and domain definition is done in 2 separate files: 
    445 \path{NEMOGCM/CONFIG/SHARED/field_def.xml} and \path{NEMOGCM/CONFIG/SHARED/domain_def.xml} that 
     450\noindent In NEMO, by default, the field definition is done in 3 separate files ( 
     451\path{cfgs/SHARED/field_def_nemo-oce.xml}, 
     452\path{cfgs/SHARED/field_def_nemo-pisces.xml} and 
     453\path{cfgs/SHARED/field_def_nemo-ice.xml} ) and the  domain definition is done in another file ( \path{cfgs/SHARED/domain_def_nemo.xml} ) 
     454that 
    446455are included in the main iodef.xml file through the following commands: 
    447456\begin{xmllines} 
    448 <field_definition src="./field_def.xml" /> 
    449 <domain_definition src="./domain_def.xml" /> 
     457<context id="nemo" src="./context_nemo.xml"/>  
    450458\end{xmllines} 
    451459 
     
    508516 
    509517Secondly, the group can be used to replace a list of elements. 
    510 Several examples of groups of fields are proposed at the end of the file \path{CONFIG/SHARED/field_def.xml}. 
     518Several examples of groups of fields are proposed at the end of the XML field files ( 
     519\path{cfgs/SHARED/field_def_nemo-oce.xml}, 
     520\path{cfgs/SHARED/field_def_nemo-pisces.xml} and 
     521\path{cfgs/SHARED/field_def_nemo-ice.xml} ) . 
    511522For example, a short list of the usual variables related to the U grid: 
    512523 
     
    514525<field_group id="groupU" > 
    515526   <field field_ref="uoce"  /> 
    516    <field field_ref="suoce" /> 
     527   <field field_ref="ssu" /> 
    517528   <field field_ref="utau"  /> 
    518529</field_group> 
     
    538549the tag family domain. 
    539550It must therefore be done in the domain part of the XML file.  
    540 For example, in \path{CONFIG/SHARED/domain_def.xml}, we provide the following example of a definition of  
     551For example, in \path{cfgs/SHARED/domain_def.xml}, we provide the following example of a definition of  
    541552a 5 by 5 box with the bottom left corner at point (10,10). 
    542553 
    543554\begin{xmllines} 
    544 <domain_group id="grid_T"> 
    545    <domain id="myzoom" zoom_ibegin="10" zoom_jbegin="10" zoom_ni="5" zoom_nj="5" /> 
     555<domain id="myzoomT" domain_ref="grid_T"> 
     556   <zoom_domain ibegin="10" jbegin="10" ni="5" nj="5" /> 
    546557\end{xmllines} 
    547558 
     
    551562\begin{xmllines} 
    552563<file id="myfile_vzoom" output_freq="1d" > 
    553    <field field_ref="toce" domain_ref="myzoom"/> 
     564   <field field_ref="toce" domain_ref="myzoomT"/> 
    554565</file> 
    555566\end{xmllines} 
     
    576587\subsubsection{Define vertical zooms} 
    577588 
    578 Vertical zooms are defined through the attributs zoom\_begin and zoom\_end of the tag family axis. 
     589Vertical zooms are defined through the attributs zoom\_begin and zoom\_n of the tag family axis. 
    579590It must therefore be done in the axis part of the XML file. 
    580 For example, in \path{NEMOGCM/CONFIG/ORCA2_LIM/iodef_demo.xml}, we provide the following example: 
    581  
    582 \begin{xmllines} 
    583 <axis_group id="deptht" long_name="Vertical T levels" unit="m" positive="down" > 
    584    <axis id="deptht" /> 
    585    <axis id="deptht_myzoom" zoom_begin="1" zoom_end="10" /> 
     591For example, in \path{cfgs/ORCA2_ICE_PISCES/EXPREF/iodef_demo.xml}, we provide the following example: 
     592 
     593\begin{xmllines} 
     594<axis_definition> 
     595   <axis id="deptht" long_name="Vertical T levels" unit="m" positive="down" /> 
     596   <axis id="deptht_zoom" azix_ref="deptht" > 
     597      <zoom_axis zoom_begin="1" zoom_n="10" /> 
     598   </axis> 
    586599\end{xmllines} 
    587600 
     
    765778\end{xmllines} 
    766779 
    767 Note that, then the code is crashing, writting real4 variables forces a numerical convection from  
     780Note that, then the code is crashing, writting real4 variables forces a numerical conversion from  
    768781real8 to real4 which will create an internal error in NetCDF and will avoid the creation of the output files. 
    769782Forcing double precision outputs with prec="8" (for example in the field\_definition) will avoid this problem. 
     
    938951    \hline 
    939952  \end{tabularx} 
    940   \caption{Field tags ("\tt{field\_*}")} 
     953  \caption{Field tags ("\ttfamily{field\_*}")} 
    941954\end{table} 
    942955 
     
    974987    \hline 
    975988  \end{tabularx} 
    976   \caption{File tags ("\tt{file\_*}")} 
     989  \caption{File tags ("\ttfamily{file\_*}")} 
    977990\end{table} 
    978991 
     
    10071020    \hline 
    10081021  \end{tabularx} 
    1009   \caption{Axis tags ("\tt{axis\_*}")} 
     1022  \caption{Axis tags ("\ttfamily{axis\_*}")} 
    10101023\end{table} 
    10111024 
     
    10401053    \hline 
    10411054  \end{tabularx} 
    1042   \caption{Domain tags ("\tt{domain\_*)}"} 
     1055  \caption{Domain tags ("\ttfamily{domain\_*)}"} 
    10431056\end{table} 
    10441057 
     
    10731086    \hline 
    10741087  \end{tabularx} 
    1075   \caption{Grid tags ("\tt{grid\_*}")} 
     1088  \caption{Grid tags ("\ttfamily{grid\_*}")} 
    10761089\end{table} 
    10771090 
     
    11141127    \hline 
    11151128  \end{tabularx} 
    1116   \caption{Reference attributes ("\tt{*\_ref}")} 
     1129  \caption{Reference attributes ("\ttfamily{*\_ref}")} 
    11171130\end{table} 
    11181131 
     
    11501163    \hline 
    11511164  \end{tabularx} 
    1152   \caption{Domain attributes ("\tt{zoom\_*}")} 
     1165  \caption{Domain attributes ("\ttfamily{zoom\_*}")} 
    11531166\end{table} 
    11541167 
     
    13181331\subsection{CF metadata standard compliance} 
    13191332 
    1320 Output from the XIOS-1.0 IO server is compliant with  
     1333Output from the XIOS IO server is compliant with  
    13211334\href{http://cfconventions.org/Data/cf-conventions/cf-conventions-1.5/build/cf-conventions.html}{version 1.5} of 
    13221335the CF metadata standard.  
     
    13321345%       NetCDF4 support 
    13331346% ================================================================ 
    1334 \section{NetCDF4 support (\protect\key{netcdf4})} 
     1347\section[NetCDF4 support (\texttt{\textbf{key\_netcdf4}})] 
     1348{NetCDF4 support (\protect\key{netcdf4})} 
    13351349\label{sec:DIA_nc4} 
    13361350 
     
    13401354Chunking and compression can lead to significant reductions in file sizes for a small runtime overhead. 
    13411355For a fuller discussion on chunking and other performance issues the reader is referred to 
    1342 the NetCDF4 documentation found \href{http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Chunking}{here}. 
     1356the NetCDF4 documentation found \href{https://www.unidata.ucar.edu/software/netcdf/docs/netcdf_perf_chunking.html}{here}. 
    13431357 
    13441358The new features are only available when the code has been linked with a NetCDF4 library 
     
    13891403\end{forlines} 
    13901404 
    1391 \noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\tt 46x38x1} respectively in 
    1392 the mono-processor case (\ie global domain of {\small\tt 182x149x31}). 
     1405\noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\ttfamily 46x38x1} respectively in 
     1406the mono-processor case (\ie global domain of {\small\ttfamily 182x149x31}). 
    13931407An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in  
    13941408table \autoref{tab:NC4} which compares the results of two short runs of the ORCA2\_LIM reference configuration with 
     
    14501464%       Tracer/Dynamics Trends 
    14511465% ------------------------------------------------------------------------------------------------------------- 
    1452 \section{Tracer/Dynamics trends  (\protect\ngn{namtrd})} 
     1466\section[Tracer/Dynamics trends (\texttt{namtrd})] 
     1467{Tracer/Dynamics trends (\protect\ngn{namtrd})} 
    14531468\label{sec:DIA_trd} 
    14541469 
     
    14621477(\ie at the end of each $dyn\cdots.F90$ and/or $tra\cdots.F90$ routines). 
    14631478This capability is controlled by options offered in \ngn{namtrd} namelist. 
    1464 Note that the output are done with xIOS, and therefore the \key{IOM} is required. 
     1479Note that the output are done with XIOS, and therefore the \key{iomput} is required. 
    14651480 
    14661481What is done depends on the \ngn{namtrd} logical set to \forcode{.true.}: 
     
    14881503 
    14891504Note that the mixed layer tendency diagnostic can also be used on biogeochemical models via  
    1490 the \key{trdtrc} and \key{trdmld\_trc} CPP keys. 
     1505the \key{trdtrc} and \key{trdmxl\_trc} CPP keys. 
    14911506 
    14921507\textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested. 
    14931508In particular, options associated with \np{ln\_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl} are not working, 
    1494 and none of the options have been tested with variable volume (\ie \key{vvl} defined). 
     1509and none of the options have been tested with variable volume (\ie \np{ln\_linssh}\forcode{ = .true.}). 
    14951510 
    14961511% ------------------------------------------------------------------------------------------------------------- 
    14971512%       On-line Floats trajectories 
    14981513% ------------------------------------------------------------------------------------------------------------- 
    1499 \section{FLO: On-Line Floats trajectories (\protect\key{floats})} 
     1514\section[FLO: On-Line Floats trajectories (\texttt{\textbf{key\_floats}})] 
     1515{FLO: On-Line Floats trajectories (\protect\key{floats})} 
    15001516\label{sec:FLO} 
    15011517%--------------------------------------------namflo------------------------------------------------------- 
     
    15061522The on-line computation of floats advected either by the three dimensional velocity field or constraint to 
    15071523remain at a given depth ($w = 0$ in the computation) have been introduced in the system during the CLIPPER project. 
    1508 Options are defined by \ngn{namflo} namelis variables. 
    1509 The algorithm used is based either on the work of \cite{Blanke_Raynaud_JPO97} (default option), 
     1524Options are defined by \ngn{namflo} namelist variables. 
     1525The algorithm used is based either on the work of \cite{blanke.raynaud_JPO97} (default option), 
    15101526or on a $4^th$ Runge-Hutta algorithm (\np{ln\_flork4}\forcode{ = .true.}). 
    1511 Note that the \cite{Blanke_Raynaud_JPO97} algorithm have the advantage of providing trajectories which 
     1527Note that the \cite{blanke.raynaud_JPO97} algorithm have the advantage of providing trajectories which 
    15121528are consistent with the numeric of the code, so that the trajectories never intercept the bathymetry. 
    15131529 
     
    15191535In case of Ariane convention, input filename is \np{init\_float\_ariane}. 
    15201536Its format is: \\ 
    1521 {\scriptsize \texttt{I J K nisobfl itrash itrash}} 
     1537{\scriptsize \texttt{I J K nisobfl itrash}} 
    15221538 
    15231539\noindent with: 
     
    15771593In that case, output filename is trajec\_float. 
    15781594 
    1579 Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}). 
    1580 There are 2 possibilities: 
    1581  
    1582 - if (\key{iomput}) is used, outputs are selected in  iodef.xml. 
     1595Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}) with 
     1596\key{iomput} and outputs selected in iodef.xml. 
    15831597Here it is an example of specification to put in files description section: 
    15841598 
     
    15971611\end{xmllines} 
    15981612 
    1599  -  if (\key{iomput}) is not used, a file called \ifile{trajec\_float} will be created by IOIPSL library. 
    1600  
    1601  See also \href{http://stockage.univ-brest.fr/~grima/Ariane/}{here} the web site describing the off-line use of 
    1602  this marvellous diagnostic tool. 
    16031613 
    16041614% ------------------------------------------------------------------------------------------------------------- 
    16051615%       Harmonic analysis of tidal constituents 
    16061616% ------------------------------------------------------------------------------------------------------------- 
    1607 \section{Harmonic analysis of tidal constituents (\protect\key{diaharm}) } 
     1617\section[Harmonic analysis of tidal constituents (\texttt{\textbf{key\_diaharm}})] 
     1618{Harmonic analysis of tidal constituents (\protect\key{diaharm})} 
    16081619\label{sec:DIA_diag_harm} 
    16091620 
    1610 %------------------------------------------namdia_harm---------------------------------------------------- 
     1621%------------------------------------------nam_diaharm---------------------------------------------------- 
    16111622% 
    16121623\nlst{nam_diaharm} 
     
    16161627This on-line Harmonic analysis is actived with \key{diaharm}. 
    16171628 
    1618 Some parameters are available in namelist \ngn{namdia\_harm}: 
     1629Some parameters are available in namelist \ngn{nam\_diaharm}: 
    16191630 
    16201631 - \np{nit000\_han} is the first time step used for harmonic analysis 
     
    16521663%       Sections transports 
    16531664% ------------------------------------------------------------------------------------------------------------- 
    1654 \section{Transports across sections (\protect\key{diadct}) } 
     1665\section[Transports across sections (\texttt{\textbf{key\_diadct}})] 
     1666{Transports across sections (\protect\key{diadct})} 
    16551667\label{sec:DIA_diag_dct} 
    16561668 
     
    16641676 
    16651677Each section is defined by the coordinates of its 2 extremities. 
    1666 The pathways between them are contructed using tools which can be found in \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT} 
    1667 and are written in a binary file \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is later read in by 
     1678The pathways between them are contructed using tools which can be found in \texttt{tools/SECTIONS\_DIADCT} 
     1679and are written in a binary file \texttt{section\_ijglobal.diadct} which is later read in by 
    16681680NEMO to compute on-line transports. 
    16691681 
     
    16841696\subsubsection{Creating a binary file containing the pathway of each section} 
    16851697 
    1686 In \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT/run}, 
     1698In \texttt{tools/SECTIONS\_DIADCT/run}, 
    16871699the file \textit{ {list\_sections.ascii\_global}} contains a list of all the sections that are to be computed 
    16881700(this list of sections is based on MERSEA project metrics). 
     
    17331745   
    17341746 The script \texttt{job.ksh} computes the pathway for each section and creates a binary file 
    1735  \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is read by NEMO. \\ 
     1747 \texttt{section\_ijglobal.diadct} which is read by NEMO. \\ 
    17361748 
    17371749 It is possible to use this tools for new configuations: \texttt{job.ksh} has to be updated with 
     
    18091821The steric effect is therefore not explicitely represented. 
    18101822This approximation does not represent a serious error with respect to the flow field calculated by the model 
    1811 \citep{Greatbatch_JGR94}, but extra attention is required when investigating sea level, 
     1823\citep{greatbatch_JGR94}, but extra attention is required when investigating sea level, 
    18121824as steric changes are an important contribution to local changes in sea level on seasonal and climatic time scales. 
    18131825This is especially true for investigation into sea level rise due to global warming. 
    18141826 
    18151827Fortunately, the steric contribution to the sea level consists of a spatially uniform component that 
    1816 can be diagnosed by considering the mass budget of the world ocean \citep{Greatbatch_JGR94}. 
     1828can be diagnosed by considering the mass budget of the world ocean \citep{greatbatch_JGR94}. 
    18171829In order to better understand how global mean sea level evolves and thus how the steric sea level can be diagnosed, 
    18181830we compare, in the following, the non-Boussinesq and Boussinesq cases. 
     
    18881900the ocean surface, not by changes in mean mass of the ocean: the steric effect is missing in a Boussinesq fluid. 
    18891901 
    1890 Nevertheless, following \citep{Greatbatch_JGR94}, the steric effect on the volume can be diagnosed by 
     1902Nevertheless, following \citep{greatbatch_JGR94}, the steric effect on the volume can be diagnosed by 
    18911903considering the mass budget of the ocean.  
    18921904The apparent changes in $\mathcal{M}$, mass of the ocean, which are not induced by surface mass flux 
    18931905must be compensated by a spatially uniform change in the mean sea level due to expansion/contraction of the ocean 
    1894 \citep{Greatbatch_JGR94}. 
     1906\citep{greatbatch_JGR94}. 
    18951907In others words, the Boussinesq mass, $\mathcal{M}_o$, can be related to $\mathcal{M}$, 
    18961908the total mass of the ocean seen by the Boussinesq model, via the steric contribution to the sea level, 
     
    19241936This value is a sensible choice for the reference density used in a Boussinesq ocean climate model since, 
    19251937with the exception of only a small percentage of the ocean, density in the World Ocean varies by no more than 
    1926 2$\%$ from this value (\cite{Gill1982}, page 47). 
     19382$\%$ from this value (\cite{gill_bk82}, page 47). 
    19271939 
    19281940Second, we have assumed here that the total ocean surface, $\mathcal{A}$, 
     
    19311943   
    19321944Third, the discretisation of \autoref{eq:steric_Bq} depends on the type of free surface which is considered. 
    1933 In the non linear free surface case, \ie \key{vvl} defined, it is given by 
     1945In the non linear free surface case, \ie \np{ln\_linssh}\forcode{ = .true.}, it is given by 
    19341946 
    19351947\[ 
     
    19541966so that there are no associated ocean currents. 
    19551967Hence, the dynamically relevant sea level is the effective sea level, 
    1956 \ie the sea level as if sea ice (and snow) were converted to liquid seawater \citep{Campin_al_OM08}. 
     1968\ie the sea level as if sea ice (and snow) were converted to liquid seawater \citep{campin.marshall.ea_OM08}. 
    19571969However, in the current version of \NEMO the sea-ice is levitating above the ocean without mass exchanges between 
    19581970ice and ocean. 
     
    19701982where $S_o$ and $p_o$ are the initial salinity and pressure, respectively. 
    19711983 
    1972 Both steric and thermosteric sea level are computed in \mdl{diaar5} which needs the \key{diaar5} defined to 
    1973 be called. 
     1984Both steric and thermosteric sea level are computed in \mdl{diaar5}. 
    19741985 
    19751986% ------------------------------------------------------------------------------------------------------------- 
    19761987%       Other Diagnostics 
    19771988% ------------------------------------------------------------------------------------------------------------- 
    1978 \section{Other diagnostics (\protect\key{diahth}, \protect\key{diaar5})} 
     1989\section[Other diagnostics] 
     1990{Other diagnostics} 
    19791991\label{sec:DIA_diag_others} 
    19801992 
     
    19821994The available ready-to-add diagnostics modules can be found in directory DIA. 
    19831995 
    1984 \subsection{Depth of various quantities (\protect\mdl{diahth})} 
     1996\subsection[Depth of various quantities (\textit{diahth.F90})] 
     1997{Depth of various quantities (\protect\mdl{diahth})} 
    19851998 
    19861999Among the available diagnostics the following ones are obtained when defining the \key{diahth} CPP key: 
    19872000 
    1988 - the mixed layer depth (based on a density criterion \citep{de_Boyer_Montegut_al_JGR04}) (\mdl{diahth}) 
     2001- the mixed layer depth (based on a density criterion \citep{de-boyer-montegut.madec.ea_JGR04}) (\mdl{diahth}) 
    19892002 
    19902003- the turbocline depth (based on a turbulent mixing coefficient criterion) (\mdl{diahth}) 
     
    19942007- the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth}) 
    19952008 
    1996 % ----------------------------------------------------------- 
    1997 %     Poleward heat and salt transports 
    1998 % ----------------------------------------------------------- 
    1999  
    2000 \subsection{Poleward heat and salt transports (\protect\mdl{diaptr})} 
    2001  
    2002 %------------------------------------------namptr----------------------------------------- 
    2003  
    2004 \nlst{namptr}  
    2005 %----------------------------------------------------------------------------------------- 
    2006  
    2007 The poleward heat and salt transports, their advective and diffusive component, 
    2008 and the meriodional stream function can be computed on-line in \mdl{diaptr} \np{ln\_diaptr} to true 
    2009 (see the \textit{\ngn{namptr} } namelist below). 
    2010 When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed for the Atlantic, Indian, 
    2011 Pacific and Indo-Pacific Oceans (defined north of 30\deg{S}) as well as for the World Ocean. 
    2012 The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains three 2D mask arrays, 
    2013 the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:mask_subasins}). 
    20142009 
    20152010%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    20162011\begin{figure}[!t] 
    20172012  \begin{center} 
    2018     \includegraphics[width=1.0\textwidth]{Fig_mask_subasins} 
     2013    \includegraphics[width=\textwidth]{Fig_mask_subasins} 
    20192014    \caption{ 
    20202015      \protect\label{fig:mask_subasins} 
     
    20322027%       CMIP specific diagnostics  
    20332028% ----------------------------------------------------------- 
    2034 \subsection{CMIP specific diagnostics (\protect\mdl{diaar5})} 
    2035  
    2036 A series of diagnostics has been added in the \mdl{diaar5}. 
    2037 They corresponds to outputs that are required for AR5 simulations (CMIP5) 
     2029\subsection[CMIP specific diagnostics (\textit{diaar5.F90}, \textit{diaptr.F90})] 
     2030{CMIP specific diagnostics (\protect\mdl{diaar5})} 
     2031 
     2032A series of diagnostics has been added in the \mdl{diaar5} and \mdl{diaptr}. 
     2033In \mdl{diaar5} they correspond to outputs that are required for AR5 simulations (CMIP5) 
    20382034(see also \autoref{sec:DIA_steric} for one of them). 
    2039 Activating those outputs requires to define the \key{diaar5} CPP key. 
     2035The module \mdl{diaar5} is active when one of the following outputs is required : global total volume (voltot), global mean ssh (sshtot), global total mass (masstot), global mean temperature (temptot), global mean ssh steric (sshsteric), global mean ssh thermosteric (sshthster), global mean salinity (saltot), sea water pressure at sea floor (botpres), dynamic sea surface height (sshdyn). 
     2036 
     2037In \mdl{diaptr} when \np{ln\_diaptr}\forcode{ = .true.}  
     2038(see the \textit{\ngn{namptr} } namelist below) can be computed on-line the poleward heat and salt transports, their advective and diffusive component, and the meriodional stream function . 
     2039When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed for the Atlantic, Indian, 
     2040Pacific and Indo-Pacific Oceans (defined north of 30\deg{S}) as well as for the World Ocean. 
     2041The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains three 2D mask arrays, 
     2042the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:mask_subasins}). 
     2043 
     2044%------------------------------------------namptr----------------------------------------- 
     2045 
     2046\nlst{namptr}  
     2047%----------------------------------------------------------------------------------------- 
    20402048 
    20412049% ----------------------------------------------------------- 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DIU.tex

    r10442 r11422  
    3333(\ie from the temperature of the top few model levels) or from some other source.   
    3434It must be noted that both the cool skin and warm layer models produce estimates of the change in temperature 
    35 ($\Delta T_{\rm{cs}}$ and $\Delta T_{\rm{wl}}$) and 
     35($\Delta T_{\mathrm{cs}}$ and $\Delta T_{\mathrm{wl}}$) and 
    3636both must be added to a foundation SST to obtain the true skin temperature. 
    3737 
     
    6060%=============================================================== 
    6161 
    62 The warm layer is calculated using the model of \citet{Takaya_al_JGR10} (TAKAYA10 model hereafter). 
     62The warm layer is calculated using the model of \citet{takaya.bidlot.ea_JGR10} (TAKAYA10 model hereafter). 
    6363This is a simple flux based model that is defined by the equations 
    6464\begin{align} 
    65 \frac{\partial{\Delta T_{\rm{wl}}}}{\partial{t}}&=&\frac{Q(\nu+1)}{D_T\rho_w c_p 
     65\frac{\partial{\Delta T_{\mathrm{wl}}}}{\partial{t}}&=&\frac{Q(\nu+1)}{D_T\rho_w c_p 
    6666\nu}-\frac{(\nu+1)ku^*_{w}f(L_a)\Delta T}{D_T\Phi\!\left(\frac{D_T}{L}\right)} \mbox{,} 
    6767\label{eq:ecmwf1} \\ 
    6868L&=&\frac{\rho_w c_p u^{*^3}_{w}}{\kappa g \alpha_w Q }\mbox{,}\label{eq:ecmwf2} 
    6969\end{align} 
    70 where $\Delta T_{\rm{wl}}$ is the temperature difference between the top of the warm layer and the depth $D_T=3$\,m at which there is assumed to be no diurnal signal. 
     70where $\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. 
    7171In equation (\autoref{eq:ecmwf1}) $\alpha_w=2\times10^{-4}$ is the thermal expansion coefficient of water, 
    7272$\kappa=0.4$ is von K\'{a}rm\'{a}n's constant, $c_p$ is the heat capacity at constant pressure of sea water, 
    7373$\rho_w$ is the water density, and $L$ is the Monin-Obukhov length. 
    7474The tunable variable $\nu$ is a shape parameter that defines the expected subskin temperature profile via 
    75 $T(z) = T(0) - \left( \frac{z}{D_T} \right)^\nu \Delta T_{\rm{wl}}$, 
     75$T(z) = T(0) - \left( \frac{z}{D_T} \right)^\nu \Delta T_{\mathrm{wl}}$, 
    7676where $T$ is the absolute temperature and $z\le D_T$ is the depth below the top of the warm layer. 
    7777The influence of wind on TAKAYA10 comes through the magnitude of the friction velocity of the water $u^*_{w}$, 
     
    8282the diurnal layer, \ie 
    8383\[ 
    84   Q = Q_{\rm{sol}} + Q_{\rm{lw}} + Q_{\rm{h}}\mbox{,} 
     84  Q = Q_{\mathrm{sol}} + Q_{\mathrm{lw}} + Q_{\mathrm{h}}\mbox{,} 
    8585  % \label{eq:e_flux_eqn} 
    8686\] 
    87 where $Q_{\rm{h}}$ is the sensible and latent heat flux, $Q_{\rm{lw}}$ is the long wave flux, 
    88 and $Q_{\rm{sol}}$ is the solar flux absorbed within the diurnal warm layer. 
    89 For $Q_{\rm{sol}}$ the 9 term representation of \citet{Gentemann_al_JGR09} is used. 
     87where $Q_{\mathrm{h}}$ is the sensible and latent heat flux, $Q_{\mathrm{lw}}$ is the long wave flux, 
     88and $Q_{\mathrm{sol}}$ is the solar flux absorbed within the diurnal warm layer. 
     89For $Q_{\mathrm{sol}}$ the 9 term representation of \citet{gentemann.minnett.ea_JGR09} is used. 
    9090In equation \autoref{eq:ecmwf1} the function $f(L_a)=\max(1,L_a^{\frac{2}{3}})$, 
    9191where $L_a=0.3$\footnote{ 
     
    118118%=============================================================== 
    119119 
    120 The cool skin is modelled using the framework of \citet{Saunders_JAS82} who used a formulation of the near surface temperature difference based upon the heat flux and the friction velocity $u^*_{w}$. 
    121 As the cool skin is so thin (~1\,mm) we ignore the solar flux component to the heat flux and the Saunders equation for the cool skin temperature difference $\Delta T_{\rm{cs}}$ becomes 
     120The 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}$. 
     121As 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 
    122122\[ 
    123123  % \label{eq:sunders_eqn} 
    124   \Delta T_{\rm{cs}}=\frac{Q_{\rm{ns}}\delta}{k_t} \mbox{,} 
     124  \Delta T_{\mathrm{cs}}=\frac{Q_{\mathrm{ns}}\delta}{k_t} \mbox{,} 
    125125\] 
    126 where $Q_{\rm{ns}}$ is the, usually negative, non-solar heat flux into the ocean and 
     126where $Q_{\mathrm{ns}}$ is the, usually negative, non-solar heat flux into the ocean and 
    127127$k_t$ is the thermal conductivity of sea water. 
    128128$\delta$ is the thickness of the skin layer and is given by 
     
    132132\end{equation} 
    133133where $\mu$ is the kinematic viscosity of sea water and $\lambda$ is a constant of proportionality which 
    134 \citet{Saunders_JAS82} suggested varied between 5 and 10. 
     134\citet{saunders_JAS67} suggested varied between 5 and 10. 
    135135 
    136 The value of $\lambda$ used in equation (\autoref{eq:sunders_thick_eqn}) is that of \citet{Artale_al_JGR02}, 
    137 which is shown in \citet{Tu_Tsuang_GRL05} to outperform a number of other parametrisations at 
     136The value of $\lambda$ used in equation (\autoref{eq:sunders_thick_eqn}) is that of \citet{artale.iudicone.ea_JGR02}, 
     137which is shown in \citet{tu.tsuang_GRL05} to outperform a number of other parametrisations at 
    138138both low and high wind speeds. 
    139139Specifically, 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DOM.tex

    r10502 r11422  
    1818%     - domclo:  closed sea and lakes.... management of closea sea area : specific to global configuration, both forced and coupled 
    1919 
     20\vfill 
     21\begin{figure}[b] 
     22\subsubsection*{Changes record} 
     23\begin{tabular}{m{0.08\linewidth}||m{0.32\linewidth}|m{0.6\linewidth}} 
     24    Release   & Author(s)     & Modifications \\ 
     25\hline 
     26    {\em 4.0} & {\em Simon M{\"u}ller \& Andrew Coward} & {\em Compatibility changes for v4.0. Major simplication has moved many of the options to external domain configuration tools. For now this information has been retained in \autoref{apdx:DOMAINcfg} }  \\ 
     27    {\em 3.x} & {\em Sebastien Masson, Gurvan Madec \& Rashid Benshila } & {\em }  \\ 
     28\end{tabular} 
     29\end{figure} 
     30 
    2031\newpage 
    2132 
    2233Having defined the continuous equations in \autoref{chap:PE} and chosen a time discretization \autoref{chap:STP}, 
    23 we need to choose a discretization on a grid, and numerical algorithms. 
     34we need to choose a grid for spatial discretization and related numerical algorithms. 
    2435In the present chapter, we provide a general description of the staggered grid used in \NEMO, 
    25 and other information relevant to the main directory routines as well as the DOM (DOMain) directory. 
     36and other relevant information about the DOM (DOMain) source-code modules . 
    2637 
    2738% ================================================================ 
     
    4051\begin{figure}[!tb] 
    4152  \begin{center} 
    42     \includegraphics[]{Fig_cell} 
     53    \includegraphics[width=\textwidth]{Fig_cell} 
    4354    \caption{ 
    4455      \protect\label{fig:cell} 
     
    5566The numerical techniques used to solve the Primitive Equations in this model are based on the traditional, 
    5667centred second-order finite difference approximation. 
    57 Special attention has been given to the homogeneity of the solution in the three space directions. 
     68Special attention has been given to the homogeneity of the solution in the three spatial directions. 
    5869The arrangement of variables is the same in all directions. 
    5970It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with vector points $(u, v, w)$ defined in 
    6071the centre of each face of the cells (\autoref{fig:cell}). 
    6172This is the generalisation to three dimensions of the well-known ``C'' grid in Arakawa's classification 
    62 \citep{Mesinger_Arakawa_Bk76}. 
     73\citep{mesinger.arakawa_bk76}. 
    6374The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge and 
    6475the barotropic stream function $\psi$ is defined at horizontal points overlying the $\zeta$ and $f$-points. 
     
    7182Each scale factor is defined as the local analytical value provided by \autoref{eq:scale_factors}. 
    7283As a result, the mesh on which partial derivatives $\pd[]{\lambda}$, $\pd[]{\varphi}$ and 
    73 $\pd[]{z}$ are evaluated in a uniform mesh with a grid size of unity. 
     84$\pd[]{z}$ are evaluated is a uniform mesh with a grid size of unity. 
    7485Discrete partial derivatives are formulated by the traditional, centred second order finite difference approximation 
    7586while the scale factors are chosen equal to their local analytical value. 
     
    7990the continuous properties (see \autoref{apdx:C}). 
    8091A similar, related remark can be made about the domain size: 
    81 when needed, an area, volume, or the total ocean depth must be evaluated as the sum of the relevant scale factors 
     92when needed, an area, volume, or the total ocean depth must be evaluated as the product or sum of the relevant scale factors 
    8293(see \autoref{eq:DOM_bar} in the next section). 
    8394 
     
    8798    \begin{tabular}{|p{46pt}|p{56pt}|p{56pt}|p{56pt}|} 
    8899      \hline 
    89       T  & $i      $ & $j      $ & $k      $ \\ 
     100      t  & $i      $ & $j      $ & $k      $ \\ 
    90101      \hline 
    91102      u  & $i + 1/2$ & $j      $ & $k      $ \\ 
     
    107118      \protect\label{tab:cell} 
    108119      Location of grid-points as a function of integer or integer and a half value of the column, line or level. 
    109       This indexing is only used for the writing of the semi -discrete equation. 
    110       In the code, the indexing uses integer values only and has a reverse direction in the vertical 
     120      This indexing is only used for the writing of the semi -discrete equations. 
     121      In the code, the indexing uses integer values only and is positive downwards in the vertical with $k=1$ at the surface. 
    111122      (see \autoref{subsec:DOM_Num_Index}) 
    112123    } 
    113124  \end{center} 
    114125\end{table} 
     126%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     127 
     128Note that the definition of the scale factors 
     129(\ie as the analytical first derivative of the transformation that 
     130results in $(\lambda,\varphi,z)$ as a function of $(i,j,k)$) 
     131is specific to the \NEMO model \citep{marti.madec.ea_JGR92}. 
     132As an example, a scale factor in the $i$ direction is defined locally at a $t$-point, 
     133whereas many other models on a C grid choose to define such a scale factor as 
     134the distance between the $u$-points on each side of the $t$-point. 
     135Relying on an analytical transformation has two advantages: 
     136firstly, there is no ambiguity in the scale factors appearing in the discrete equations, 
     137since they are first introduced in the continuous equations; 
     138secondly, analytical transformations encourage good practice by the definition of smoothly varying grids 
     139(rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{treguier.dukowicz.ea_JGR96}. 
     140An example of the effect of such a choice is shown in \autoref{fig:zgr_e3}. 
     141%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     142\begin{figure}[!t] 
     143  \begin{center} 
     144    \includegraphics[width=\textwidth]{Fig_zgr_e3} 
     145    \caption{ 
     146      \protect\label{fig:zgr_e3} 
     147      Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical, 
     148      and (b) analytically derived grid-point position and scale factors. 
     149      For both grids here, the same $w$-point depth has been chosen but 
     150      in (a) the $t$-points are set half way between $w$-points while 
     151      in (b) they are defined from an analytical function: 
     152      $z(k) = 5 \, (k - 1/2)^3 - 45 \, (k - 1/2)^2 + 140 \, (k - 1/2) - 150$. 
     153      Note the resulting difference between the value of the grid-size $\Delta_k$ and 
     154      those of the scale factor $e_k$. 
     155    } 
     156  \end{center} 
     157\end{figure} 
    115158%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    116159 
     
    132175Following \autoref{eq:PE_grad} and \autoref{eq:PE_lap}, the gradient of a variable $q$ defined at 
    133176a $t$-point has its three components defined at $u$-, $v$- and $w$-points while 
    134 its Laplacian is defined at $t$-point. 
     177its Laplacian is defined at the $t$-point. 
    135178These operators have the following discrete forms in the curvilinear $s$-coordinates system: 
    136179\[ 
     
    171214\end{equation} 
    172215 
    173 The vertical average over the whole water column denoted by an overbar becomes for a quantity $q$ which 
    174 is a masked field (i.e. equal to zero inside solid area): 
     216The vertical average over the whole water column is denoted by an overbar and is for 
     217a masked field $q$ (\ie a quantity that is equal to zero inside solid areas): 
    175218\begin{equation} 
    176219  \label{eq:DOM_bar} 
     
    178221\end{equation} 
    179222where $H_q$  is the ocean depth, which is the masked sum of the vertical scale factors at $q$ points, 
    180 $k^b$ and $k^o$ are the bottom and surface $k$-indices, and the symbol $k^o$ refers to a summation over 
     223$k^b$ and $k^o$ are the bottom and surface $k$-indices, and the symbol $\sum \limits_k$ refers to a summation over 
    181224all grid points of the same type in the direction indicated by the subscript (here $k$). 
    182225 
     
    193236vector points $(u,v,w)$. 
    194237 
    195 Let $a$ and $b$ be two fields defined on the mesh, with value zero inside continental area. 
    196 Using integration by parts it can be shown that the differencing operators ($\delta_i$, $\delta_j$ and $\delta_k$) 
     238Let $a$ and $b$ be two fields defined on the mesh, with a value of zero inside continental areas. 
     239It can be shown that the differencing operators ($\delta_i$, $\delta_j$ and $\delta_k$) 
    197240are skew-symmetric linear operators, and further that the averaging operators $\overline{\cdots}^{\, i}$, 
    198241$\overline{\cdots}^{\, j}$ and $\overline{\cdots}^{\, k}$) are symmetric linear operators, \ie 
     
    218261\begin{figure}[!tb] 
    219262  \begin{center} 
    220     \includegraphics[]{Fig_index_hor} 
     263    \includegraphics[width=\textwidth]{Fig_index_hor} 
    221264    \caption{ 
    222265      \protect\label{fig:index_hor} 
     
    228271%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    229272 
    230 The array representation used in the \fortran code requires an integer indexing while 
    231 the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with the use of 
    232 integer values for $t$-points and both integer and integer and a half values for all the other points. 
    233 Therefore a specific integer indexing must be defined for points other than $t$-points 
     273The array representation used in the \fortran code requires an integer indexing. 
     274However, the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with the use of 
     275integer values for $t$-points only while all the other points involve integer and a half values. 
     276Therefore, a specific integer indexing has been defined for points other than $t$-points 
    234277(\ie velocity and vorticity grid-points). 
    235 Furthermore, the direction of the vertical indexing has been changed so that the surface level is at $k = 1$. 
     278Furthermore, the direction of the vertical indexing has been reversed and the surface level set at $k = 1$. 
    236279 
    237280% ----------------------------------- 
     
    253296\label{subsec:DOM_Num_Index_vertical} 
    254297 
    255 In the vertical, the chosen indexing requires special attention since the $k$-axis is re-orientated downward in 
    256 the \fortran code compared to the indexing used in the semi -discrete equations and 
     298In the vertical, the chosen indexing requires special attention since the direction of the $k$-axis in 
     299the \fortran code is the reverse of that used in the semi -discrete equations and 
    257300given in \autoref{subsec:DOM_cell}. 
    258 The sea surface corresponds to the $w$-level $k = 1$ which is the same index as $t$-level just below 
     301The sea surface corresponds to the $w$-level $k = 1$, which is the same index as the $t$-level just below 
    259302(\autoref{fig:index_vert}). 
    260 The last $w$-level ($k = jpk$) either corresponds to the ocean floor or is inside the bathymetry while 
    261 the last $t$-level is always inside the bathymetry (\autoref{fig:index_vert}). 
    262 Note that for an increasing $k$ index, a $w$-point and the $t$-point just below have the same $k$ index, 
    263 in opposition to what is done in the horizontal plane where 
    264 it is the $t$-point and the nearest velocity points in the direction of the horizontal axis that 
    265 have the same $i$ or $j$ index 
     303The last $w$-level ($k = jpk$) either corresponds to or is below the ocean floor while 
     304the last $t$-level is always outside the ocean domain (\autoref{fig:index_vert}). 
     305Note that a $w$-point and the directly underlaying $t$-point have a common $k$ index (\ie $t$-points and their 
     306nearest $w$-point neighbour in negative index direction), in contrast to the indexing on the horizontal plane where 
     307the $t$-point has the same index as the nearest velocity points in the positive direction of the respective horizontal axis index 
    266308(compare the dashed area in \autoref{fig:index_hor} and \autoref{fig:index_vert}). 
    267309Since the scale factors are chosen to be strictly positive, 
    268 a \textit{minus sign} appears in the \fortran code \textit{before all the vertical derivatives} of 
    269 the discrete equations given in this documentation. 
     310a \textit{minus sign} is included in the \fortran implementations of \textit{all the vertical derivatives} of 
     311the discrete equations given in this manual in order to accommodate the opposing vertical index directions in implementation and documentation. 
    270312 
    271313%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    272314\begin{figure}[!pt] 
    273315  \begin{center} 
    274     \includegraphics[]{Fig_index_vert} 
     316    \includegraphics[width=\textwidth]{Fig_index_vert} 
    275317    \caption{ 
    276318      \protect\label{fig:index_vert} 
    277319      Vertical integer indexing used in the \fortran code. 
    278       Note that the $k$-axis is orientated downward. 
    279       The dashed area indicates the cell in which variables contained in arrays have the same $k$-index. 
     320      Note that the $k$-axis is oriented downward. 
     321      The dashed area indicates the cell in which variables contained in arrays have a common $k$-index. 
    280322    } 
    281323  \end{center} 
     
    283325%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    284326 
     327% ------------------------------------------------------------------------------------------------------------- 
     328%        Domain configuration 
     329% ------------------------------------------------------------------------------------------------------------- 
     330\section{Spatial domain configuration} 
     331\label{subsec:DOM_config} 
     332 
     333\nlst{namcfg} 
     334 
     335Two typical methods are available to specify the spatial domain 
     336configuration; they can be selected using parameter \np{ln\_read\_cfg} 
     337parameter in namelist \ngn{namcfg}.  
     338 
     339If \np{ln\_read\_cfg} is set to \forcode{.true.}, the domain-specific parameters 
     340and fields are read from a netCDF input file, whose name (without its .nc 
     341suffix) can be specified as the value of the \np{cn\_domcfg} parameter in 
     342namelist \ngn{namcfg}. 
     343 
     344If \np{ln\_read\_cfg} is set to \forcode{.false.}, the domain-specific 
     345parameters and fields can be provided (\eg analytically computed) by subroutines 
     346\mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}. These subroutines can be supplied in 
     347the \path{MY_SRC} directory of the configuration, and default versions that 
     348configure the spatial domain for the GYRE reference configuration are present in 
     349the \path{src/OCE/USR} directory. 
     350 
     351In version 4.0 there are no longer any options for reading complex bathmetries and  
     352performing a vertical discretization at run-time. Whilst it is occasionally convenient 
     353to have a common bathymetry file and, for example, to run similar models with and 
     354without partial bottom boxes and/or sigma-coordinates, supporting such choices leads to 
     355overly complex code. Worse still is the difficulty of ensuring the model configurations  
     356intended to be identical are indeed so when the model domain itself can be altered by runtime 
     357selections. The code previously used to perform vertical discretization has be incorporated  
     358into an external tool (\path{tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMAINcfg}. 
     359 
     360The next subsections summarise the parameter and fields related to the 
     361configuration of the whole model domain. These represent the minimum information 
     362that must be provided either via the \np{cn\_domcfg} file or set by code 
     363inserted into user-supplied versions of the \mdl{usrdef\_*} subroutines. The 
     364requirements are presented in three sections: the domain size 
     365(\autoref{subsec:DOM_size}), the horizontal mesh 
     366(\autoref{subsec:DOM_hgr}), and the vertical grid 
     367(\autoref{subsec:DOM_zgr}). 
     368 
    285369% ----------------------------------- 
    286370%        Domain Size 
    287371% ----------------------------------- 
    288 \subsubsection{Domain size} 
     372\subsection{Domain size} 
    289373\label{subsec:DOM_size} 
    290374 
    291 The total size of the computational domain is set by the parameters \np{jpiglo}, 
    292 \np{jpjglo} and \np{jpkglo} in the $i$, $j$ and $k$ directions respectively. 
    293 Parameters $jpi$ and $jpj$ refer to the size of each processor subdomain when 
    294 the code is run in parallel using domain decomposition (\key{mpp\_mpi} defined, 
    295 see \autoref{sec:LBC_mpp}). 
    296  
    297 % ================================================================ 
    298 % Domain: List of fields needed 
    299 % ================================================================ 
    300 \section{Needed fields} 
    301 \label{sec:DOM_fields} 
    302 The ocean mesh (\ie the position of all the scalar and vector points) is defined by the transformation that 
    303 gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 
    304 The grid-points are located at integer or integer and a half values of as indicated in \autoref{tab:cell}. 
    305 The associated scale factors are defined using the analytical first derivative of the transformation 
    306 \autoref{eq:scale_factors}. 
    307 Necessary fields for configuration definition are: 
    308  
    309 \begin{itemize} 
    310 \item 
    311   Geographic position: 
    312   longitude with \texttt{glamt}, \texttt{glamu}, \texttt{glamv}, \texttt{glamf} and 
    313   latitude  with \texttt{gphit}, \texttt{gphiu}, \texttt{gphiv}, \texttt{gphif} 
    314   (all respectively at T, U, V and F point) 
    315 \item 
    316   Coriolis parameter (if domain not on the sphere): \texttt{ff\_f} and \texttt{ff\_t} 
    317   (at T and F point) 
    318 \item 
    319   Scale factors: 
    320   \texttt{e1t}, \texttt{e1u}, \texttt{e1v} and \texttt{e1f} (on i direction), 
    321   \texttt{e2t}, \texttt{e2u}, \texttt{e2v} and \texttt{e2f} (on j direction) and 
    322   \texttt{ie1e2u\_v}, \texttt{e1e2u}, \texttt{e1e2v}. \\ 
    323   \texttt{e1e2u}, \texttt{e1e2v} are u and v surfaces (if gridsize reduction in some straits),  
    324   \texttt{ie1e2u\_v} is to flag set u and v surfaces are neither read nor computed. 
    325 \end{itemize} 
    326   
    327 These fields can be read in an domain input file which name is setted in \np{cn\_domcfg} parameter specified in 
    328 \ngn{namcfg}. 
    329  
    330 \nlst{namcfg} 
    331  
    332 Or they can be defined in an analytical way in \path{MY_SRC} directory of the configuration. 
    333 For Reference Configurations of NEMO input domain files are supplied by NEMO System Team. 
    334 For analytical definition of input fields two routines are supplied: \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}. 
    335 They are an example of GYRE configuration parameters, and they are available in \path{src/OCE/USR} directory, 
    336 they provide the horizontal and vertical mesh. 
    337 % ------------------------------------------------------------------------------------------------------------- 
    338 %        Needed fields  
    339 % ------------------------------------------------------------------------------------------------------------- 
    340 %\subsection{List of needed fields to build DOMAIN} 
    341 %\label{subsec:DOM_fields_list} 
    342  
     375The total size of the computational domain is set by the parameters 
     376\np{jpiglo}, \np{jpjglo} and \np{jpkglo} for the $i$, $j$ and $k$ 
     377directions, respectively. Note, that the variables \forcode{jpi} and \forcode{jpj} 
     378refer to the size of each processor subdomain when the code is run in 
     379parallel using domain decomposition (\key{mpp\_mpi} defined, see 
     380\autoref{sec:LBC_mpp}). 
     381 
     382The name of the configuration is set through parameter \np{cn\_cfg}, 
     383and the nominal resolution through parameter \np{nn\_cfg} (unless in 
     384the input file both of variables \forcode{ORCA} and \forcode{ORCA_index} 
     385are present, in which case \np{cn\_cfg} and \np{nn\_cfg} are set from these 
     386values accordingly). 
     387 
     388The global lateral boundary condition type is selected from 8 options 
     389using parameter \np{jperio}. See \autoref{sec:LBC_jperio} for 
     390details on the available options and the corresponding values for 
     391\np{jperio}. 
    343392 
    344393% ================================================================ 
    345394% Domain: Horizontal Grid (mesh)  
    346395% ================================================================ 
    347 \section{Horizontal grid mesh (\protect\mdl{domhgr})} 
    348 \label{sec:DOM_hgr} 
    349  
    350 % ------------------------------------------------------------------------------------------------------------- 
    351 %        Coordinates and scale factors  
    352 % ------------------------------------------------------------------------------------------------------------- 
    353 \subsection{Coordinates and scale factors} 
    354 \label{subsec:DOM_hgr_coord_e} 
    355  
    356 The ocean mesh (\ie the position of all the scalar and vector points) is defined by 
    357 the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 
    358 The grid-points are located at integer or integer and a half values of as indicated in \autoref{tab:cell}. 
    359 The associated scale factors are defined using the analytical first derivative of the transformation 
    360 \autoref{eq:scale_factors}. 
    361 These definitions are done in two modules, \mdl{domhgr} and \mdl{domzgr}, 
    362 which provide the horizontal and vertical meshes, respectively. 
    363 This section deals with the horizontal mesh parameters. 
    364  
    365 In a horizontal plane, the location of all the model grid points is defined from 
    366 the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$. 
    367 The horizontal scale factors are calculated using \autoref{eq:scale_factors}. 
    368 For example, when the longitude and latitude are function of a single value 
    369 ($i$ and $j$, respectively) (geographical configuration of the mesh), 
    370 the horizontal mesh definition reduces to define the wanted $\lambda(i)$, $\varphi(j)$, 
    371 and their derivatives $\lambda'(i) \ \varphi'(j)$ in the \mdl{domhgr} module. 
    372 The model computes the grid-point positions and scale factors in the horizontal plane as follows: 
    373 \begin{align*} 
    374    \lambda_t &\equiv \text{glamt} =      \lambda (i      ) 
    375   &\varphi_t &\equiv \text{gphit} =      \varphi (j      ) \\ 
    376    \lambda_u &\equiv \text{glamu} =      \lambda (i + 1/2) 
    377   &\varphi_u &\equiv \text{gphiu} =      \varphi (j      ) \\ 
    378    \lambda_v &\equiv \text{glamv} =      \lambda (i      ) 
    379   &\varphi_v &\equiv \text{gphiv} =      \varphi (j + 1/2) \\ 
    380    \lambda_f &\equiv \text{glamf} =      \lambda (i + 1/2) 
    381   &\varphi_f &\equiv \text{gphif} =      \varphi (j + 1/2) \\ 
    382    e_{1t}    &\equiv \text{e1t}   = r_a |\lambda'(i      ) \; \cos\varphi(j      ) | 
    383   &e_{2t}    &\equiv \text{e2t}   = r_a |\varphi'(j      )                         | \\ 
    384    e_{1u}    &\equiv \text{e1t}   = r_a |\lambda'(i + 1/2) \; \cos\varphi(j      ) | 
    385   &e_{2u}    &\equiv \text{e2t}   = r_a |\varphi'(j      )                         | \\ 
    386    e_{1v}    &\equiv \text{e1t}   = r_a |\lambda'(i      ) \; \cos\varphi(j + 1/2) | 
    387   &e_{2v}    &\equiv \text{e2t}   = r_a |\varphi'(j + 1/2)                         | \\ 
    388    e_{1f}    &\equiv \text{e1t}   = r_a |\lambda'(i + 1/2) \; \cos\varphi(j + 1/2) | 
    389   &e_{2f}    &\equiv \text{e2t}   = r_a |\varphi'(j + 1/2)                         | 
    390 \end{align*} 
    391 where the last letter of each computational name indicates the grid point considered and 
    392 $r_a$ is the earth radius (defined in \mdl{phycst} along with all universal constants). 
    393 Note that the horizontal position of and scale factors at $w$-points are exactly equal to those of $t$-points, 
    394 thus no specific arrays are defined at $w$-points. 
    395  
    396 Note that the definition of the scale factors 
    397 (\ie as the analytical first derivative of the transformation that 
    398 gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$) 
    399 is specific to the \NEMO model \citep{Marti_al_JGR92}. 
    400 As an example, $e_{1t}$ is defined locally at a $t$-point, 
    401 whereas many other models on a C grid choose to define such a scale factor as 
    402 the distance between the $U$-points on each side of the $t$-point. 
    403 Relying on an analytical transformation has two advantages: 
    404 firstly, there is no ambiguity in the scale factors appearing in the discrete equations, 
    405 since they are first introduced in the continuous equations; 
    406 secondly, analytical transformations encourage good practice by the definition of smoothly varying grids 
    407 (rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{Treguier1996}. 
    408 An example of the effect of such a choice is shown in \autoref{fig:zgr_e3}. 
    409 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    410 \begin{figure}[!t] 
    411   \begin{center} 
    412     \includegraphics[]{Fig_zgr_e3} 
    413     \caption{ 
    414       \protect\label{fig:zgr_e3} 
    415       Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical, 
    416       and (b) analytically derived grid-point position and scale factors. 
    417       For both grids here, the same $w$-point depth has been chosen but 
    418       in (a) the $t$-points are set half way between $w$-points while 
    419       in (b) they are defined from an analytical function: 
    420       $z(k) = 5 \, (k - 1/2)^3 - 45 \, (k - 1/2)^2 + 140 \, (k - 1/2) - 150$. 
    421       Note the resulting difference between the value of the grid-size $\Delta_k$ and 
    422       those of the scale factor $e_k$. 
    423     } 
    424   \end{center} 
    425 \end{figure} 
    426 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    427  
    428 % ------------------------------------------------------------------------------------------------------------- 
    429 %        Choice of horizontal grid 
    430 % ------------------------------------------------------------------------------------------------------------- 
    431 \subsection{Choice of horizontal grid} 
    432 \label{subsec:DOM_hgr_msh_choice} 
    433  
    434 % ------------------------------------------------------------------------------------------------------------- 
    435 %        Grid files 
    436 % ------------------------------------------------------------------------------------------------------------- 
    437 \subsection{Output grid files} 
    438 \label{subsec:DOM_hgr_files} 
    439  
    440 All the arrays relating to a particular ocean model configuration (grid-point position, scale factors, masks) 
    441 can be saved in files if \np{nn\_msh} $\not = 0$ (namelist variable in \ngn{namdom}). 
    442 This can be particularly useful for plots and off-line diagnostics. 
    443 In some cases, the user may choose to make a local modification of a scale factor in the code. 
    444 This is the case in global configurations when restricting the width of a specific strait 
    445 (usually a one-grid-point strait that happens to be too wide due to insufficient model resolution). 
    446 An example is Gibraltar Strait in the ORCA2 configuration. 
    447 When such modifications are done, 
    448 the output grid written when \np{nn\_msh} $\not = 0$ is no more equal to the input grid. 
     396\subsection{Horizontal grid mesh (\protect\mdl{domhgr})} 
     397\label{subsec:DOM_hgr} 
     398 
     399% ================================================================ 
     400% Domain: List of hgr-related fields needed 
     401% ================================================================ 
     402\subsubsection{Required fields} 
     403\label{sec:DOM_hgr_fields} 
     404The explicit specification of a range of mesh-related fields are required for the definition of a configuration. These include: 
     405 
     406\begin{Verbatim}[fontsize=\tiny] 
     407int    jpiglo, jpjglo, jpkglo            /* global domain sizes                                          */ 
     408int    jperio                            /* lateral global domain b.c.                                   */ 
     409double glamt, glamu, glamv, glamf        /* geographic longitude (t,u,v and f points respectively)       */ 
     410double gphit, gphiu, gphiv, gphif        /* geographic latitude                                          */ 
     411double e1t, e1u, e1v, e1f                /* horizontal scale factors                                     */ 
     412double e2t, e2u, e2v, e2f                /* horizontal scale factors                                     */ 
     413\end{Verbatim} 
     414 
     415The values of the geographic longitude and latitude arrays at indices $i,j$ correspond to the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$, evaluated at the values as specified in Table \autoref{tab:cell} for the respective grid-point position. The calculation of the values of the horizontal scale factor arrays in general additionally involves partial derivatives of $\lambda$ and $\varphi$ with respect to $i$ and $j$, evaluated for the same arguments as $\lambda$ and $\varphi$. 
     416 
     417\subsubsection{Optional fields} 
     418\begin{Verbatim}[fontsize=\tiny] 
     419                                         /* Optional:                                                    */ 
     420int    ORCA, ORCA_index                  /* configuration name, configuration resolution                 */ 
     421double e1e2u, e1e2v                      /* U and V surfaces (if grid size reduction in some straits)    */ 
     422double ff_f, ff_t                        /* Coriolis parameter (if not on the sphere)                    */ 
     423\end{Verbatim} 
     424 
     425NEMO can support the local reduction of key strait widths by altering individual values of 
     426e2u or e1v at the appropriate locations. This is particularly useful for locations such as 
     427Gibraltar or Indonesian Throughflow pinch-points (see \autoref{sec:MISC_strait} for 
     428illustrated examples). The key is to reduce the faces of $T$-cell (\ie change the value of 
     429the horizontal scale factors at $u$- or $v$-point) but not the volume of the cells. Doing 
     430otherwise can lead to numerical instability issues.  In normal operation the surface areas 
     431are computed from $\texttt{e1u} * \texttt{e2u}$ and $\texttt{e1v} * \texttt{e2v}$ but in 
     432cases where a gridsize reduction is required, the unaltered surface areas at $u$ and $v$ 
     433grid points (\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or pre-computed 
     434in \mdl{usrdef\_hgr}. If these arrays are present in the \np{cn\_domcfg} file they are 
     435read and the internal computation is suppressed. Versions of \mdl{usrdef\_hgr} which set 
     436their own values of \texttt{e1e2u} and \texttt{e1e2v} should set the surface-area 
     437computation flag: \texttt{ie1e2u\_v} to a non-zero value to suppress their re-computation. 
     438 
     439\smallskip 
     440Similar logic applies to the other optional fields: \texttt{ff\_f} and \texttt{ff\_t} 
     441which can be used to provide the Coriolis parameter at F- and T-points respectively if the 
     442mesh is not on a sphere. If present these fields will be read and used and the normal 
     443calculation ($2*\Omega*\sin(\varphi)$) suppressed. Versions of \mdl{usrdef\_hgr} which set 
     444their own values of \texttt{ff\_f} and \texttt{ff\_t} should set the Coriolis computation 
     445flag: \texttt{iff} to a non-zero value to suppress their re-computation. 
     446 
     447Note that longitudes, latitudes, and scale factors at $w$ points are exactly 
     448equal to those of $t$ points, thus no specific arrays are defined at $w$ points. 
     449 
    449450 
    450451% ================================================================ 
    451452% Domain: Vertical Grid (domzgr) 
    452453% ================================================================ 
    453 \section{Vertical grid (\protect\mdl{domzgr})} 
    454 \label{sec:DOM_zgr} 
    455 %-----------------------------------------nam_zgr & namdom------------------------------------------- 
    456 % 
    457 %\nlst{namzgr}  
    458  
    459 \nlst{namdom}  
     454\subsection[Vertical grid (\textit{domzgr.F90})] 
     455{Vertical grid (\protect\mdl{domzgr})} 
     456\label{subsec:DOM_zgr} 
     457%-----------------------------------------namdom------------------------------------------- 
     458\nlst{namdom} 
    460459%------------------------------------------------------------------------------------------------------------- 
    461460 
    462 Variables are defined through the \ngn{namzgr} and \ngn{namdom} namelists. 
    463461In the vertical, the model mesh is determined by four things:  
    464 (1) the bathymetry given in meters;  
    465 (2) the number of levels of the model (\jp{jpk});  
    466 (3) the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and 
    467 (4) the masking system, \ie the number of wet model levels at each  
    468 $(i,j)$ column of points. 
     462\begin{enumerate} 
     463  \item the bathymetry given in meters;  
     464  \item the number of levels of the model (\jp{jpk});  
     465  \item the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and 
     466  \item the masking system, \ie the number of wet model levels at each  
     467$(i,j)$ location of the horizontal grid. 
     468\end{enumerate} 
    469469 
    470470%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    471471\begin{figure}[!tb] 
    472472  \begin{center} 
    473     \includegraphics[]{Fig_z_zps_s_sps} 
     473    \includegraphics[width=\textwidth]{Fig_z_zps_s_sps} 
    474474    \caption{ 
    475475      \protect\label{fig:z_zps_s_sps} 
     
    480480      (d) hybrid $s-z$ coordinate, 
    481481      (e) hybrid $s-z$ coordinate with partial step, and 
    482       (f) same as (e) but in the non-linear free surface (\protect\np{ln\_linssh}~\forcode{= .false.}). 
     482      (f) same as (e) but in the non-linear free surface (\protect\np{ln\_linssh}\forcode{ = .false.}). 
    483483      Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e). 
    484484    } 
     
    487487%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    488488 
    489 The choice of a vertical coordinate, even if it is made through \ngn{namzgr} namelist parameters,  
    490 must be done once of all at the beginning of an experiment. 
    491 It is not intended as an option which can be enabled or disabled in the middle of an experiment. 
    492 Three main choices are offered (\autoref{fig:z_zps_s_sps}): 
    493 $z$-coordinate with full step bathymetry (\np{ln\_zco}~\forcode{= .true.}), 
    494 $z$-coordinate with partial step bathymetry (\np{ln\_zps}~\forcode{= .true.}), 
    495 or generalized, $s$-coordinate (\np{ln\_sco}~\forcode{= .true.}). 
    496 Hybridation of the three main coordinates are available: 
    497 $s-z$ or $s-zps$ coordinate (\autoref{fig:z_zps_s_sps} and \autoref{fig:z_zps_s_sps}). 
    498 By default a non-linear free surface is used: the coordinate follow the time-variation of the free surface so that 
    499 the transformation is time dependent: $z(i,j,k,t)$ (\autoref{fig:z_zps_s_sps}). 
    500 When a linear free surface is assumed (\np{ln\_linssh}~\forcode{= .true.}), 
    501 the vertical coordinate are fixed in time, but the seawater can move up and down across the $z_0$ surface 
    502 (in other words, the top of the ocean in not a rigid-lid). 
    503 The last choice in terms of vertical coordinate concerns the presence (or not) in 
    504 the model domain of ocean cavities beneath ice shelves. 
    505 Setting \np{ln\_isfcav} to true allows to manage ocean cavities, otherwise they are filled in. 
    506 This option is currently only available in $z$- or $zps$-coordinate, 
    507 and partial step are also applied at the ocean/ice shelf interface. 
    508  
    509 Contrary to the horizontal grid, the vertical grid is computed in the code and no provision is made for 
    510 reading it from a file. 
    511 The only input file is the bathymetry (in meters) (\ifile{bathy\_meter}) 
    512 \footnote{ 
    513   N.B. in full step $z$-coordinate, a \ifile{bathy\_level} file can replace the \ifile{bathy\_meter} file, 
    514   so that the computation of the number of wet ocean point in each water column is by-passed}. 
    515 If \np{ln\_isfcav}~\forcode{= .true.}, an extra file input file (\ifile{isf\_draft\_meter}) describing 
    516 the ice shelf draft (in meters) is needed. 
    517  
    518 After reading the bathymetry, the algorithm for vertical grid definition differs between the different options: 
    519 \begin{description} 
    520 \item[\textit{zco}] 
    521   set a reference coordinate transformation $z_0(k)$, and set $z(i,j,k,t) = z_0(k)$. 
    522 \item[\textit{zps}] 
    523   set a reference coordinate transformation $z_0(k)$, and calculate the thickness of the deepest level at 
    524   each $(i,j)$ point using the bathymetry, to obtain the final three-dimensional depth and scale factor arrays. 
    525 \item[\textit{sco}] 
    526   smooth the bathymetry to fulfill the hydrostatic consistency criteria and 
    527   set the three-dimensional transformation. 
    528 \item[\textit{s-z} and \textit{s-zps}] 
    529   smooth the bathymetry to fulfill the hydrostatic consistency criteria and 
    530   set the three-dimensional transformation $z(i,j,k)$, 
    531   and possibly introduce masking of extra land points to better fit the original bathymetry file. 
    532 \end{description} 
    533 %%% 
    534 \gmcomment{   add the description of the smoothing:  envelop topography...} 
    535 %%% 
    536  
    537 Unless a linear free surface is used (\np{ln\_linssh}~\forcode{= .false.}), 
    538 the arrays describing the grid point depths and vertical scale factors are three set of 
    539 three dimensional arrays $(i,j,k)$ defined at \textit{before}, \textit{now} and \textit{after} time step. 
    540 The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively. 
    541 They are updated at each model time step using a fixed reference coordinate system which 
    542 computer names have a $\_0$ suffix. 
    543 When the linear free surface option is used (\np{ln\_linssh}~\forcode{= .true.}), \textit{before}, 
    544 \textit{now} and \textit{after} arrays are simply set one for all to their reference counterpart. 
    545  
    546 % ------------------------------------------------------------------------------------------------------------- 
    547 %        Meter Bathymetry 
    548 % ------------------------------------------------------------------------------------------------------------- 
    549 \subsection{Meter bathymetry} 
    550 \label{subsec:DOM_bathy} 
    551  
    552 Three options are possible for defining the bathymetry, according to the namelist variable \np{nn\_bathy} 
    553 (found in \ngn{namdom} namelist):  
    554 \begin{description} 
    555 \item[\np{nn\_bathy}~\forcode{= 0}]: 
    556   a flat-bottom domain is defined. 
    557   The total depth $z_w (jpk)$ is given by the coordinate transformation. 
    558   The domain can either be a closed basin or a periodic channel depending on the parameter \np{jperio}. 
    559 \item[\np{nn\_bathy}~\forcode{= -1}]: 
    560   a domain with a bump of topography one third of the domain width at the central latitude. 
    561   This is meant for the "EEL-R5" configuration, a periodic or open boundary channel with a seamount. 
    562 \item[\np{nn\_bathy}~\forcode{= 1}]: 
    563   read a bathymetry and ice shelf draft (if needed). 
    564   The \ifile{bathy\_meter} file (Netcdf format) provides the ocean depth (positive, in meters) at 
    565   each grid point of the model grid. 
    566   The bathymetry is usually built by interpolating a standard bathymetry product (\eg ETOPO2) onto 
    567   the horizontal ocean mesh. 
    568   Defining the bathymetry also defines the coastline: where the bathymetry is zero, 
    569   no model levels are defined (all levels are masked). 
    570  
    571   The \ifile{isfdraft\_meter} file (Netcdf format) provides the ice shelf draft (positive, in meters) at 
    572   each grid point of the model grid. 
    573   This file is only needed if \np{ln\_isfcav}~\forcode{= .true.}. 
    574   Defining the ice shelf draft will also define the ice shelf edge and the grounding line position. 
    575 \end{description} 
    576  
    577 When a global ocean is coupled to an atmospheric model it is better to represent all large water bodies 
    578 (\eg great lakes, Caspian sea...) even if the model resolution does not allow their communication with 
    579 the rest of the ocean. 
    580 This is unnecessary when the ocean is forced by fixed atmospheric conditions, 
    581 so these seas can be removed from the ocean domain. 
    582 The user has the option to set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}), 
    583 but the code has to be adapted to the user's configuration. 
    584  
    585 % ------------------------------------------------------------------------------------------------------------- 
    586 %        z-coordinate  and reference coordinate transformation 
    587 % ------------------------------------------------------------------------------------------------------------- 
    588 \subsection[$Z$-coordinate (\protect\np{ln\_zco}~\forcode{= .true.}) and ref. coordinate] 
    589             {$Z$-coordinate (\protect\np{ln\_zco}~\forcode{= .true.}) and reference coordinate} 
    590 \label{subsec:DOM_zco} 
    591  
    592 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    593 \begin{figure}[!tb] 
    594   \begin{center} 
    595     \includegraphics[]{Fig_zgr} 
    596     \caption{ 
    597       \protect\label{fig:zgr} 
    598       Default vertical mesh for ORCA2: 30 ocean levels (L30). 
    599       Vertical level functions for (a) T-point depth and (b) the associated scale factor as computed from 
    600       \autoref{eq:DOM_zgr_ana_1} using \autoref{eq:DOM_zgr_coef} in $z$-coordinate. 
    601     } 
    602   \end{center} 
    603 \end{figure} 
    604 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    605  
    606 The reference coordinate transformation $z_0(k)$ defines the arrays $gdept_0$ and $gdepw_0$ for $t$- and $w$-points, 
    607 respectively. 
    608 As indicated on \autoref{fig:index_vert} \jp{jpk} is the number of $w$-levels. 
    609 $gdepw_0(1)$ is the ocean surface. 
    610 There are at most \jp{jpk}-1 $t$-points inside the ocean, 
    611 the additional $t$-point at $jk = jpk$ is below the sea floor and is not used. 
    612 The vertical location of $w$- and $t$-levels is defined from the analytic expression of the depth $z_0(k)$ whose 
    613 analytical derivative with respect to $k$ provides the vertical scale factors. 
    614 The user must provide the analytical expression of both $z_0$ and its first derivative with respect to $k$. 
    615 This is done in routine \mdl{domzgr} through statement functions, 
    616 using parameters provided in the \ngn{namcfg} namelist. 
    617  
    618 It is possible to define a simple regular vertical grid by giving zero stretching (\np{ppacr}~\forcode{= 0}). 
    619 In that case, the parameters \jp{jpk} (number of $w$-levels) and 
    620 \np{pphmax} (total ocean depth in meters) fully define the grid. 
    621  
    622 For climate-related studies it is often desirable to concentrate the vertical resolution near the ocean surface. 
    623 The following function is proposed as a standard for a $z$-coordinate (with either full or partial steps):  
    624 \begin{gather} 
    625   \label{eq:DOM_zgr_ana_1} 
    626     z_0  (k) = h_{sur} - h_0 \; k - \; h_1 \; \log  \big[ \cosh ((k - h_{th}) / h_{cr}) \big] \\ 
    627     e_3^0(k) = \lt|    - h_0      -    h_1 \; \tanh \big[        (k - h_{th}) / h_{cr}  \big] \rt| 
    628 \end{gather} 
    629 where $k = 1$ to \jp{jpk} for $w$-levels and $k = 1$ to $k = 1$ for $T-$levels. 
    630 Such an expression allows us to define a nearly uniform vertical location of levels at the ocean top and bottom with 
    631 a smooth hyperbolic tangent transition in between (\autoref{fig:zgr}). 
    632  
    633 If the ice shelf cavities are opened (\np{ln\_isfcav}~\forcode{= .true.}), the definition of $z_0$ is the same. 
    634 However, definition of $e_3^0$ at $t$- and $w$-points is respectively changed to: 
    635 \begin{equation} 
    636   \label{eq:DOM_zgr_ana_2} 
    637   \begin{split} 
    638     e_3^T(k) &= z_W (k + 1) - z_W (k    ) \\ 
    639     e_3^W(k) &= z_T (k    ) - z_T (k - 1) 
    640   \end{split} 
    641 \end{equation} 
    642 This formulation decrease the self-generated circulation into the ice shelf cavity  
    643 (which can, in extreme case, leads to blow up).\\ 
    644   
    645 The most used vertical grid for ORCA2 has $10~m$ ($500~m$) resolution in the surface (bottom) layers and 
    646 a depth which varies from 0 at the sea surface to a minimum of $-5000~m$. 
    647 This leads to the following conditions: 
    648 \begin{equation} 
    649   \label{eq:DOM_zgr_coef} 
    650   \begin{array}{ll} 
    651     e_3 (1   + 1/2) =  10. & z(1  ) =     0. \\ 
    652     e_3 (jpk - 1/2) = 500. & z(jpk) = -5000. 
    653   \end{array} 
    654 \end{equation} 
    655  
    656 With the choice of the stretching $h_{cr} = 3$ and the number of levels \jp{jpk}~$= 31$, 
    657 the four coefficients $h_{sur}$, $h_0$, $h_1$, and $h_{th}$ in 
    658 \autoref{eq:DOM_zgr_ana_2} have been determined such that 
    659 \autoref{eq:DOM_zgr_coef} is satisfied, through an optimisation procedure using a bisection method. 
    660 For the first standard ORCA2 vertical grid this led to the following values: 
    661 $h_{sur} = 4762.96$, $h_0 = 255.58, h_1 = 245.5813$, and $h_{th} = 21.43336$. 
    662 The resulting depths and scale factors as a function of the model levels are shown in 
    663 \autoref{fig:zgr} and given in \autoref{tab:orca_zgr}. 
    664 Those values correspond to the parameters \np{ppsur}, \np{ppa0}, \np{ppa1}, \np{ppkth} in \ngn{namcfg} namelist. 
    665  
    666 Rather than entering parameters $h_{sur}$, $h_0$, and $h_1$ directly, it is possible to recalculate them. 
    667 In that case the user sets \np{ppsur}~$=$~\np{ppa0}~$=$~\np{ppa1}~$= 999999$., 
    668 in \ngn{namcfg} namelist, and specifies instead the four following parameters: 
     489The choice of a vertical coordinate is made when setting up the configuration; 
     490it is not intended to be an option which can be changed in the middle of an 
     491experiment. The one exception to this statement being the choice of linear or 
     492non-linear free surface. In v4.0 the linear free surface option is implemented 
     493as a special case of the non-linear free surface. This is computationally 
     494wasteful since it uses the structures for time-varying 3D metrics for fields 
     495that (in the linear free surface case) are fixed. However, the linear 
     496free-surface is rarely used and implementing it this way means a single configuration 
     497file can support both options. 
     498 
     499By default a non-linear free surface is used (\np{ln\_linssh} set to \forcode{ = 
     500.false.} in \ngn{namdom}): the coordinate follow the time-variation of the free 
     501surface so that the transformation is time dependent: $z(i,j,k,t)$ 
     502(\eg \autoref{fig:z_zps_s_sps}f).  When a linear free surface is assumed 
     503(\np{ln\_linssh} set to \forcode{ = .true.} in \ngn{namdom}), the vertical 
     504coordinates are fixed in time, but the seawater can move up and down across the 
     505$z_0$ surface (in other words, the top of the ocean in not a rigid lid). 
     506 
     507Note that settings: \np{ln\_zco}, \np{ln\_zps}, \np{ln\_sco} and \np{ln\_isfcav} mentioned 
     508in the following sections appear to be namelist options but they are no longer truly 
     509namelist options for NEMO. Their value is written to and read from the domain configuration file 
     510and they should be treated as fixed parameters for a particular configuration. They are 
     511namelist options for the \forcode{DOMAINcfg} tool that can be used to build the 
     512configuration file and serve both to provide a record of the choices made whilst building the 
     513configuration and to trigger appropriate code blocks within NEMO. 
     514These values should not be altered in the \np{cn\_domcfg} file. 
     515 
     516\medskip 
     517The decision on these choices must be made when the \np{cn\_domcfg} file is constructed. 
     518Three main choices are offered (\autoref{fig:z_zps_s_sps}a-c): 
     519 
    669520\begin{itemize} 
    670 \item 
    671   \np{ppacr}~$= h_{cr}$: stretching factor (nondimensional). 
    672   The larger \np{ppacr}, the smaller the stretching. 
    673   Values from $3$ to $10$ are usual. 
    674 \item 
    675   \np{ppkth}~$= h_{th}$: is approximately the model level at which maximum stretching occurs 
    676   (nondimensional, usually of order 1/2 or 2/3 of \jp{jpk}) 
    677 \item 
    678   \np{ppdzmin}: minimum thickness for the top layer (in meters). 
    679 \item 
    680   \np{pphmax}: total depth of the ocean (meters). 
     521\item $z$-coordinate with full step bathymetry (\np{ln\_zco}\forcode{ = .true.}), 
     522\item $z$-coordinate with partial step ($zps$) bathymetry (\np{ln\_zps}\forcode{ = .true.}), 
     523\item Generalized, $s$-coordinate (\np{ln\_sco}\forcode{ = .true.}). 
    681524\end{itemize} 
    682 As an example, for the $45$ layers used in the DRAKKAR configuration those parameters are: 
    683 \jp{jpk}~$= 46$, \np{ppacr}~$= 9$, \np{ppkth}~$= 23.563$, \np{ppdzmin}~$= 6~m$, \np{pphmax}~$= 5750~m$. 
    684  
    685 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    686 \begin{table} 
    687   \begin{center} 
    688     \begin{tabular}{c||r|r|r|r} 
    689       \hline 
    690       \textbf{LEVEL} & \textbf{gdept\_1d} & \textbf{gdepw\_1d} & \textbf{e3t\_1d } & \textbf{e3w\_1d} \\ 
    691       \hline 
    692       1              & \textbf{     5.00} &               0.00 & \textbf{   10.00} &            10.00 \\ 
    693       \hline 
    694       2              & \textbf{    15.00} &              10.00 & \textbf{   10.00} &            10.00 \\ 
    695       \hline 
    696       3              & \textbf{    25.00} &              20.00 & \textbf{   10.00} &            10.00 \\ 
    697       \hline 
    698       4              & \textbf{    35.01} &              30.00 & \textbf{   10.01} &            10.00 \\ 
    699       \hline 
    700       5              & \textbf{    45.01} &              40.01 & \textbf{   10.01} &            10.01 \\ 
    701       \hline 
    702       6              & \textbf{    55.03} &              50.02 & \textbf{   10.02} &            10.02 \\ 
    703       \hline 
    704       7              & \textbf{    65.06} &              60.04 & \textbf{   10.04} &            10.03 \\ 
    705       \hline 
    706       8              & \textbf{    75.13} &              70.09 & \textbf{   10.09} &            10.06 \\ 
    707       \hline 
    708       9              & \textbf{    85.25} &              80.18 & \textbf{   10.17} &            10.12 \\ 
    709       \hline 
    710       10             & \textbf{    95.49} &              90.35 & \textbf{   10.33} &            10.24 \\ 
    711       \hline 
    712       11             & \textbf{   105.97} &             100.69 & \textbf{   10.65} &            10.47 \\ 
    713       \hline 
    714       12             & \textbf{   116.90} &             111.36 & \textbf{   11.27} &            10.91 \\ 
    715       \hline 
    716       13             & \textbf{   128.70} &             122.65 & \textbf{   12.47} &            11.77 \\ 
    717       \hline 
    718       14             & \textbf{   142.20} &             135.16 & \textbf{   14.78} &            13.43 \\ 
    719       \hline 
    720       15             & \textbf{   158.96} &             150.03 & \textbf{   19.23} &            16.65 \\ 
    721       \hline 
    722       16             & \textbf{   181.96} &             169.42 & \textbf{   27.66} &            22.78 \\ 
    723       \hline 
    724       17             & \textbf{   216.65} &             197.37 & \textbf{   43.26} &            34.30 \\ 
    725       \hline 
    726       18             & \textbf{   272.48} &             241.13 & \textbf{   70.88} &            55.21 \\ 
    727       \hline 
    728       19             & \textbf{   364.30} &             312.74 & \textbf{  116.11} &            90.99 \\ 
    729       \hline 
    730       20             & \textbf{   511.53} &             429.72 & \textbf{  181.55} &           146.43 \\ 
    731       \hline 
    732       21             & \textbf{   732.20} &             611.89 & \textbf{  261.03} &           220.35 \\ 
    733       \hline 
    734       22             & \textbf{  1033.22} &             872.87 & \textbf{  339.39} &           301.42 \\ 
    735       \hline 
    736       23             & \textbf{  1405.70} &            1211.59 & \textbf{  402.26} &           373.31 \\ 
    737       \hline 
    738       24             & \textbf{  1830.89} &            1612.98 & \textbf{  444.87} &           426.00 \\ 
    739       \hline 
    740       25             & \textbf{  2289.77} &            2057.13 & \textbf{  470.55} &           459.47 \\ 
    741       \hline 
    742       26             & \textbf{  2768.24} &            2527.22 & \textbf{  484.95} &           478.83 \\ 
    743       \hline 
    744       27             & \textbf{  3257.48} &            3011.90 & \textbf{  492.70} &           489.44 \\ 
    745       \hline 
    746       28             & \textbf{  3752.44} &            3504.46 & \textbf{  496.78} &           495.07 \\ 
    747       \hline 
    748       29             & \textbf{  4250.40} &            4001.16 & \textbf{  498.90} &           498.02 \\ 
    749       \hline 
    750       30             & \textbf{  4749.91} &            4500.02 & \textbf{  500.00} &           499.54 \\ 
    751       \hline 
    752       31             & \textbf{  5250.23} &            5000.00 & \textbf{  500.56} &           500.33 \\ 
    753       \hline 
    754     \end{tabular} 
    755   \end{center} 
    756   \caption{ 
    757     \protect\label{tab:orca_zgr} 
    758     Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration as computed from 
    759     \autoref{eq:DOM_zgr_ana_2} using the coefficients given in \autoref{eq:DOM_zgr_coef} 
    760   } 
    761 \end{table} 
    762 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    763  
    764 % ------------------------------------------------------------------------------------------------------------- 
    765 %        z-coordinate with partial step 
    766 % ------------------------------------------------------------------------------------------------------------- 
    767 \subsection{$Z$-coordinate with partial step (\protect\np{ln\_zps}~\forcode{= .true.})} 
    768 \label{subsec:DOM_zps} 
    769 %--------------------------------------------namdom------------------------------------------------------- 
    770  
    771 \nlst{namdom}  
    772 %-------------------------------------------------------------------------------------------------------------- 
    773  
    774 In $z$-coordinate partial step, 
    775 the depths of the model levels are defined by the reference analytical function $z_0(k)$ as described in 
    776 the previous section, \textit{except} in the bottom layer. 
    777 The thickness of the bottom layer is allowed to vary as a function of geographical location $(\lambda,\varphi)$ to 
    778 allow a better representation of the bathymetry, especially in the case of small slopes 
    779 (where the bathymetry varies by less than one level thickness from one grid point to the next). 
    780 The reference layer thicknesses $e_{3t}^0$ have been defined in the absence of bathymetry. 
    781 With partial steps, layers from 1 to \jp{jpk}-2 can have a thickness smaller than $e_{3t}(jk)$. 
    782 The model deepest layer (\jp{jpk}-1) is allowed to have either a smaller or larger thickness than $e_{3t}(jpk)$: 
    783 the maximum thickness allowed is $2*e_{3t}(jpk - 1)$. 
    784 This has to be kept in mind when specifying values in \ngn{namdom} namelist, 
    785 as the maximum depth \np{pphmax} in partial steps: 
    786 for example, with \np{pphmax}~$= 5750~m$ for the DRAKKAR 45 layer grid, 
    787 the maximum ocean depth allowed is actually $6000~m$ (the default thickness $e_{3t}(jpk - 1)$ being $250~m$). 
    788 Two variables in the namdom namelist are used to define the partial step vertical grid. 
    789 The mimimum water thickness (in meters) allowed for a cell partially filled with bathymetry at level jk is 
    790 the minimum of \np{rn\_e3zps\_min} (thickness in meters, usually $20~m$) or $e_{3t}(jk)*$\np{rn\_e3zps\_rat} 
    791 (a fraction, usually 10\%, of the default thickness $e_{3t}(jk)$). 
    792  
    793 \gmcomment{ \colorbox{yellow}{Add a figure here of pstep especially at last ocean level }  } 
    794  
    795 % ------------------------------------------------------------------------------------------------------------- 
    796 %        s-coordinate 
    797 % ------------------------------------------------------------------------------------------------------------- 
    798 \subsection{$S$-coordinate (\protect\np{ln\_sco}~\forcode{= .true.})} 
    799 \label{subsec:DOM_sco} 
    800 %------------------------------------------nam_zgr_sco--------------------------------------------------- 
    801 % 
    802 %\nlst{namzgr_sco}  
    803 %-------------------------------------------------------------------------------------------------------------- 
    804 Options are defined in \ngn{namzgr\_sco}. 
    805 In $s$-coordinate (\np{ln\_sco}~\forcode{= .true.}), the depth and thickness of the model levels are defined from 
    806 the product of a depth field and either a stretching function or its derivative, respectively: 
    807  
    808 \begin{align*} 
    809   % \label{eq:DOM_sco_ana} 
    810   z(k)   &= h(i,j) \; z_0 (k) \\ 
    811   e_3(k) &= h(i,j) \; z_0'(k) 
    812 \end{align*} 
    813  
    814 where $h$ is the depth of the last $w$-level ($z_0(k)$) defined at the $t$-point location in the horizontal and 
    815 $z_0(k)$ is a function which varies from $0$ at the sea surface to $1$ at the ocean bottom. 
    816 The depth field $h$ is not necessary the ocean depth, 
    817 since a mixed step-like and bottom-following representation of the topography can be used 
    818 (\autoref{fig:z_zps_s_sps}) or an envelop bathymetry can be defined (\autoref{fig:z_zps_s_sps}). 
    819 The namelist parameter \np{rn\_rmax} determines the slope at which 
    820 the terrain-following coordinate intersects the sea bed and becomes a pseudo z-coordinate. 
    821 The coordinate can also be hybridised by specifying \np{rn\_sbot\_min} and \np{rn\_sbot\_max} as 
    822 the minimum and maximum depths at which the terrain-following vertical coordinate is calculated. 
    823  
    824 Options for stretching the coordinate are provided as examples, 
    825 but care must be taken to ensure that the vertical stretch used is appropriate for the application. 
    826  
    827 The original default NEMO s-coordinate stretching is available if neither of the other options are specified as true 
    828 (\np{ln\_s\_SH94}~\forcode{= .false.} and \np{ln\_s\_SF12}~\forcode{= .false.}). 
    829 This uses a depth independent $\tanh$ function for the stretching \citep{Madec_al_JPO96}: 
    830  
    831 \[ 
    832   z = s_{min} + C (s) (H - s_{min}) 
    833   % \label{eq:SH94_1} 
    834 \] 
    835  
    836 where $s_{min}$ is the depth at which the $s$-coordinate stretching starts and 
    837 allows a $z$-coordinate to placed on top of the stretched coordinate, 
    838 and $z$ is the depth (negative down from the asea surface). 
    839 \begin{gather*} 
    840   s = - \frac{k}{n - 1} \quad \text{and} \quad 0 \leq k \leq n - 1 
    841   % \label{eq:DOM_s} 
    842  \\ 
    843   % \label{eq:DOM_sco_function} 
    844   C(s) = \frac{[\tanh(\theta \, (s + b)) - \tanh(\theta \, b)]}{2 \; \sinh(\theta)} 
    845 \end{gather*} 
    846  
    847 A stretching function, 
    848 modified from the commonly used \citet{Song_Haidvogel_JCP94} stretching (\np{ln\_s\_SH94}~\forcode{= .true.}), 
    849 is also available and is more commonly used for shelf seas modelling: 
    850  
    851 \[ 
    852   C(s) =   (1 - b) \frac{\sinh(\theta s)}{\sinh(\theta)} 
    853          + b       \frac{\tanh \lt[ \theta \lt(s + \frac{1}{2} \rt) \rt] -   \tanh \lt( \frac{\theta}{2} \rt)} 
    854                         {                                                  2 \tanh \lt( \frac{\theta}{2} \rt)} 
    855   % \label{eq:SH94_2} 
    856 \] 
    857  
    858 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    859 \begin{figure}[!ht] 
    860   \begin{center} 
    861     \includegraphics[]{Fig_sco_function} 
    862     \caption{ 
    863       \protect\label{fig:sco_function} 
    864       Examples of the stretching function applied to a seamount; 
    865       from left to right: surface, surface and bottom, and bottom intensified resolutions 
    866     } 
    867   \end{center} 
    868 \end{figure} 
    869 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    870  
    871 where $H_c$ is the critical depth (\np{rn\_hc}) at which the coordinate transitions from pure $\sigma$ to 
    872 the stretched coordinate, and $\theta$ (\np{rn\_theta}) and $b$ (\np{rn\_bb}) are the surface and 
    873 bottom control parameters such that $0 \leqslant \theta \leqslant 20$, and $0 \leqslant b \leqslant 1$. 
    874 $b$ has been designed to allow surface and/or bottom increase of the vertical resolution 
    875 (\autoref{fig:sco_function}). 
    876  
    877 Another example has been provided at version 3.5 (\np{ln\_s\_SF12}) that allows a fixed surface resolution in 
    878 an analytical terrain-following stretching \citet{Siddorn_Furner_OM12}. 
    879 In this case the a stretching function $\gamma$ is defined such that: 
    880  
    881 \begin{equation} 
    882   z = - \gamma h \quad \text{with} \quad 0 \leq \gamma \leq 1 
    883   % \label{eq:z} 
    884 \end{equation} 
    885  
    886 The function is defined with respect to $\sigma$, the unstretched terrain-following coordinate: 
    887  
    888 \begin{gather*} 
    889   % \label{eq:DOM_gamma_deriv} 
    890   \gamma =   A \lt( \sigma   - \frac{1}{2} (\sigma^2     + f (\sigma)) \rt) 
    891            + B \lt( \sigma^3 - f           (\sigma) \rt) + f (\sigma)       \\ 
    892   \intertext{Where:} 
    893   % \label{eq:DOM_gamma} 
    894   f(\sigma) = (\alpha + 2) \sigma^{\alpha + 1} - (\alpha + 1) \sigma^{\alpha + 2} 
    895   \quad \text{and} \quad \sigma = \frac{k}{n - 1} 
    896 \end{gather*} 
    897  
    898 This gives an analytical stretching of $\sigma$ that is solvable in $A$ and $B$ as a function of 
    899 the user prescribed stretching parameter $\alpha$ (\np{rn\_alpha}) that stretches towards 
    900 the surface ($\alpha > 1.0$) or the bottom ($\alpha < 1.0$) and 
    901 user prescribed surface (\np{rn\_zs}) and bottom depths. 
    902 The bottom cell depth in this example is given as a function of water depth: 
    903  
    904 \[ 
    905   % \label{eq:DOM_zb} 
    906   Z_b = h a + b 
    907 \] 
    908  
    909 where the namelist parameters \np{rn\_zb\_a} and \np{rn\_zb\_b} are $a$ and $b$ respectively. 
    910  
    911 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    912 \begin{figure}[!ht] 
    913   \includegraphics[]{Fig_DOM_compare_coordinates_surface} 
    914   \caption{ 
    915     A comparison of the \citet{Song_Haidvogel_JCP94} $S$-coordinate (solid lines), 
    916     a 50 level $Z$-coordinate (contoured surfaces) and 
    917     the \citet{Siddorn_Furner_OM12} $S$-coordinate (dashed lines) in the surface $100~m$ for 
    918     a idealised bathymetry that goes from $50~m$ to $5500~m$ depth. 
    919     For clarity every third coordinate surface is shown. 
    920   } 
    921   \label{fig:fig_compare_coordinates_surface} 
    922 \end{figure} 
    923  % >>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    924  
    925 This gives a smooth analytical stretching in computational space that is constrained to 
    926 given specified surface and bottom grid cell thicknesses in real space. 
    927 This is not to be confused with the hybrid schemes that 
    928 superimpose geopotential coordinates on terrain following coordinates thus 
    929 creating a non-analytical vertical coordinate that 
    930 therefore may suffer from large gradients in the vertical resolutions. 
    931 This stretching is less straightforward to implement than the \citet{Song_Haidvogel_JCP94} stretching, 
    932 but has the advantage of resolving diurnal processes in deep water and has generally flatter slopes. 
    933  
    934 As with the \citet{Song_Haidvogel_JCP94} stretching the stretch is only applied at depths greater than 
    935 the critical depth $h_c$. 
    936 In this example two options are available in depths shallower than $h_c$, 
    937 with pure sigma being applied if the \np{ln\_sigcrit} is true and pure z-coordinates if it is false 
    938 (the z-coordinate being equal to the depths of the stretched coordinate at $h_c$). 
    939  
    940 Minimising the horizontal slope of the vertical coordinate is important in terrain-following systems as 
    941 large slopes lead to hydrostatic consistency. 
    942 A hydrostatic consistency parameter diagnostic following \citet{Haney1991} has been implemented, 
    943 and is output as part of the model mesh file at the start of the run. 
    944  
    945 % ------------------------------------------------------------------------------------------------------------- 
    946 %        z*- or s*-coordinate 
    947 % ------------------------------------------------------------------------------------------------------------- 
    948 \subsection{\zstar- or \sstar-coordinate (\protect\np{ln\_linssh}~\forcode{= .false.})} 
    949 \label{subsec:DOM_zgr_star} 
    950  
    951 This option is described in the Report by Levier \textit{et al.} (2007), available on the \NEMO web site. 
    952  
    953 %gm% key advantage: minimise the diffusion/dispertion associated with advection in response to high frequency surface disturbances 
     525 
     526Additionally, hybrid combinations of the three main coordinates are available: 
     527$s-z$ or $s-zps$ coordinate (\autoref{fig:z_zps_s_sps}d and \autoref{fig:z_zps_s_sps}e). 
     528 
     529A further choice related to vertical coordinate concerns the presence (or not) of ocean 
     530cavities beneath ice shelves within the model domain.  A setting of \np{ln\_isfcav} as 
     531\forcode{.true.} indicates that the domain contains  ocean cavities, otherwise the top, 
     532wet layer of the ocean will always be at the ocean surface.  This option is currently only 
     533available for $z$- or $zps$-coordinates. In the latter case, partial steps are also applied 
     534at the ocean/ice shelf interface. 
     535 
     536Within the model, the arrays describing the grid point depths and vertical scale factors 
     537are three set of three dimensional arrays $(i,j,k)$ defined at \textit{before}, 
     538\textit{now} and \textit{after} time step.  The time at which they are defined is 
     539indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively.  They are updated at each 
     540model time step. The initial fixed reference coordinate system is held in variable names 
     541with a $\_0$ suffix.  When the linear free surface option is used 
     542(\np{ln\_linssh}\forcode{ = .true.}), \textit{before}, \textit{now} and \textit{after} 
     543arrays are initially set to their reference counterpart and remain fixed. 
     544 
     545\subsubsection{Required fields} 
     546\label{sec:DOM_zgr_fields} 
     547The explicit specification of a range of fields related to the vertical grid are required for the definition of a configuration. These include: 
     548 
     549\begin{Verbatim}[fontsize=\tiny] 
     550int    ln_zco, ln_zps, ln_sco            /* flags for z-coord, z-coord with partial steps and s-coord    */ 
     551int    ln_isfcav                         /* flag  for ice shelf cavities                                 */ 
     552double e3t_1d, e3w_1d                    /* reference vertical scale factors at T and W points           */ 
     553double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0 /* vertical scale factors 3D coordinate at T,U,V,F and W points */ 
     554double e3uw_0, e3vw_0                    /* vertical scale factors 3D coordinate at UW and VW points     */ 
     555int    bottom_level, top_level           /* last wet T-points, 1st wet T-points (for ice shelf cavities) */ 
     556                                         /* For reference:                                               */ 
     557float  bathy_metry                       /* bathymetry used in setting top and bottom levels             */ 
     558\end{Verbatim} 
     559 
     560This set of vertical metrics is sufficient to describe the initial depth and thickness of 
     561every gridcell in the model regardless of the choice of vertical coordinate. With constant 
     562z-levels, e3 metrics will be uniform across each horizontal level. In the partial step 
     563case each e3 at the \np{bottom\_level} (and, possibly, \np{top\_level} if ice cavities are 
     564present) may vary from its horizontal neighbours. And, in s-coordinates, variations can 
     565occur throughout the water column. With the non-linear free-surface, all the coordinates 
     566behave more like the s-coordinate in that variations occurr throughout the water column 
     567with displacements related to the sea surface height. These variations are typically much 
     568smaller than those arising from bottom fitted coordinates. The values for vertical metrics 
     569supplied in the domain configuration file can be considered as those arising from a flat 
     570sea surface with zero elevation. 
     571 
     572The \np{bottom\_level} and \np{top\_level} 2D arrays define the \np{bottom\_level} and top 
     573wet levels in each grid column. Without ice cavities, \np{top\_level} is essentially a land 
     574mask (0 on land; 1 everywhere else). With ice cavities, \np{top\_level} determines the 
     575first wet point below the overlying ice shelf. 
     576 
     577 
    954578 
    955579% ------------------------------------------------------------------------------------------------------------- 
    956580%        level bathymetry and mask  
    957581% ------------------------------------------------------------------------------------------------------------- 
    958 \subsection{Level bathymetry and mask} 
     582\subsubsection{Level bathymetry and mask} 
    959583\label{subsec:DOM_msk} 
    960584 
    961 Whatever the vertical coordinate used, the model offers the possibility of representing the bottom topography with 
    962 steps that follow the face of the model cells (step like topography) \citep{Madec_al_JPO96}. 
    963 The distribution of the steps in the horizontal is defined in a 2D integer array, mbathy, which 
    964 gives the number of ocean levels (\ie those that are not masked) at each $t$-point. 
    965 mbathy is computed from the meter bathymetry using the definiton of gdept as the number of $t$-points which 
    966 gdept $\leq$ bathy. 
    967  
    968 Modifications of the model bathymetry are performed in the \textit{bat\_ctl} routine (see \mdl{domzgr} module) after 
    969 mbathy is computed. 
    970 Isolated grid points that do not communicate with another ocean point at the same level are eliminated. 
    971  
    972 As for the representation of bathymetry, a 2D integer array, misfdep, is created. 
    973 misfdep defines the level of the first wet $t$-point. 
    974 All the cells between $k = 1$ and $misfdep(i,j) - 1$ are masked. 
    975 By default, $misfdep(:,:) = 1$ and no cells are masked. 
    976  
    977 In case of ice shelf cavities, modifications of the model bathymetry and ice shelf draft into  
    978 the cavities are performed in the \textit{zgr\_isf} routine. 
    979 The compatibility between ice shelf draft and bathymetry is checked. 
    980 All the locations where the isf cavity is thinnest than \np{rn\_isfhmin} meters are grounded (\ie masked). 
    981 If only one cell on the water column is opened at $t$-, $u$- or $v$-points, 
    982 the bathymetry or the ice shelf draft is dug to fit this constrain. 
    983 If the incompatibility is too strong (need to dig more than 1 cell), the cell is masked. 
    984  
    985 From the \textit{mbathy} and \textit{misfdep} array, the mask fields are defined as follows: 
     585 
     586From \np{top\_level} and \np{bottom\_level} fields, the mask fields are defined as follows: 
    986587\begin{alignat*}{2} 
    987588  tmask(i,j,k) &= &  & 
    988589    \begin{cases} 
    989                   0 &\text{if $                  k  <    misfdep(i,j)$} \\ 
    990                   1 &\text{if $misfdep(i,j) \leq k \leq   mbathy(i,j)$} \\ 
    991                   0 &\text{if $                  k  >     mbathy(i,j)$} 
     590                  0 &\text{if $                  k  <    top\_level(i,j)$} \\ 
     591                  1 &\text{if $bottom\_level(i,j) \leq k \leq   top\_level(i,j)$} \\ 
     592                  0 &\text{if $                  k  >     bottom\_level(i,j)$} 
    992593    \end{cases} 
    993594  \\ 
     
    1005606exactly in the same way as for the bottom boundary. 
    1006607 
    1007 The specification of closed lateral boundaries requires that at least 
    1008 the first and last rows and columns of the \textit{mbathy} array are set to zero. 
    1009 In the particular case of an east-west cyclical boundary condition, \textit{mbathy} has its last column equal to 
    1010 the second one and its first column equal to the last but one (and so too the mask arrays) 
    1011 (see \autoref{fig:LBC_jperio}). 
     608%% The specification of closed lateral boundaries requires that at least 
     609%% the first and last rows and columns of the \textit{mbathy} array are set to zero. 
     610%% In the particular case of an east-west cyclical boundary condition, \textit{mbathy} has its last column equal to 
     611%% the second one and its first column equal to the last but one (and so too the mask arrays) 
     612%% (see \autoref{fig:LBC_jperio}). 
     613 
     614 
     615%------------------------------------------------------------------------------------------------- 
     616%        Closed seas  
     617%------------------------------------------------------------------------------------------------- 
     618\subsection{Closed seas} \label{subsec:DOM_closea}  
     619 
     620When a global ocean is coupled to an atmospheric model it is better to represent all large 
     621water bodies (\eg great lakes, Caspian sea...) even if the model resolution does not allow 
     622their communication with the rest of the ocean.  This is unnecessary when the ocean is 
     623forced by fixed atmospheric conditions, so these seas can be removed from the ocean 
     624domain.  The user has the option to set the bathymetry in closed seas to zero (see 
     625\autoref{sec:MISC_closea}) and to optionally decide on the fate of any freshwater 
     626imbalance over the area. The options are explained in \autoref{sec:MISC_closea} but it 
     627should be noted here that a successful use of these options requires appropriate mask 
     628fields to be present in the domain configuration file. Among the possibilities are: 
     629 
     630\begin{Verbatim}[fontsize=\tiny] 
     631int    closea_mask          /* non-zero values in closed sea areas for optional masking                  */ 
     632int    closea_mask_rnf      /* non-zero values in closed sea areas with runoff locations (precip only)   */ 
     633int    closea_mask_emp      /* non-zero values in closed sea areas with runoff locations (total emp)     */ 
     634\end{Verbatim} 
     635 
     636% ------------------------------------------------------------------------------------------------------------- 
     637%        Grid files 
     638% ------------------------------------------------------------------------------------------------------------- 
     639\subsection{Output grid files} 
     640\label{subsec:DOM_meshmask} 
     641 
     642\nlst{namcfg} 
     643 
     644Most of the arrays relating to a particular ocean model configuration dicussed in this 
     645chapter (grid-point position, scale factors) can be saved in a file if namelist parameter 
     646\np{ln\_write\_cfg} (namelist \ngn{namcfg}) is set to \forcode{.true.}; the output 
     647filename is set thorugh parameter \np{cn\_domcfg\_out}. This is only really useful 
     648if the fields are computed in subroutines \mdl{usrdef\_hgr} or \mdl{usrdef\_zgr} and 
     649checking or confirmation is required. 
     650 
     651\nlst{namdom} 
     652 
     653Alternatively, all the arrays relating to a particular ocean model configuration 
     654(grid-point position, scale factors, depths and masks) can be saved in a file called 
     655\texttt{mesh\_mask} if namelist parameter \np{ln\_meshmask} (namelist \ngn{namdom}) is set 
     656to \forcode{.true.}. This file contains additional fields that can be useful for 
     657post-processing applications 
    1012658 
    1013659% ================================================================ 
    1014660% Domain: Initial State (dtatsd & istate) 
    1015661% ================================================================ 
    1016 \section{Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})} 
     662\section[Initial state (\textit{istate.F90} and \textit{dtatsd.F90})] 
     663{Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})} 
    1017664\label{sec:DTA_tsd} 
    1018665%-----------------------------------------namtsd------------------------------------------- 
    1019  
    1020666\nlst{namtsd}  
    1021667%------------------------------------------------------------------------------------------ 
    1022668 
    1023 Options are defined in \ngn{namtsd}. 
    1024 By default, the ocean start from rest (the velocity field is set to zero) and the initialization of temperature and 
    1025 salinity fields is controlled through the \np{ln\_tsd\_ini} namelist parameter. 
     669Basic initial state options are defined in \ngn{namtsd}.  By default, the ocean starts 
     670from rest (the velocity field is set to zero) and the initialization of temperature and 
     671salinity fields is controlled through the \np{ln\_tsd\_init} namelist parameter. 
     672 
    1026673\begin{description} 
    1027 \item[\np{ln\_tsd\_init}~\forcode{= .true.}] 
    1028   use a T and S input files that can be given on the model grid itself or on their native input data grid. 
    1029   In the latter case, 
    1030   the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid 
    1031   (see \autoref{subsec:SBC_iof}). 
    1032   The information relative to the input files are given in the \np{sn\_tem} and \np{sn\_sal} structures. 
    1033   The computation is done in the \mdl{dtatsd} module. 
    1034 \item[\np{ln\_tsd\_init}~\forcode{= .false.}] 
    1035   use constant salinity value of $35.5~psu$ and an analytical profile of temperature 
    1036   (typical of the tropical ocean), see \rou{istate\_t\_s} subroutine called from \mdl{istate} module. 
     674\item[\np{ln\_tsd\_init}\forcode{= .true.}] 
     675  Use T and S input files that can be given on the model grid itself or on their native 
     676  input data grids.  In the latter case, the data will be interpolated on-the-fly both in 
     677  the horizontal and the vertical to the model grid (see \autoref{subsec:SBC_iof}).  The 
     678  information relating to the input files are specified in the \np{sn\_tem} and 
     679  \np{sn\_sal} structures.  The computation is done in the \mdl{dtatsd} module. 
     680\item[\np{ln\_tsd\_init}\forcode{= .false.}] 
     681  Initial values for T and S are set via a user supplied \rou{usr\_def\_istate} routine 
     682  contained in \mdl{userdef\_istate}. The default version sets horizontally uniform T and 
     683  profiles as used in the  GYRE configuration (see \autoref{sec:CFG_gyre}). 
    1037684\end{description} 
    1038685 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_DYN.tex

    r10499 r11422  
    6565%           Horizontal divergence and relative vorticity 
    6666%-------------------------------------------------------------------------------------------------------------- 
    67 \subsection{Horizontal divergence and relative vorticity (\protect\mdl{divcur})} 
     67\subsection[Horizontal divergence and relative vorticity (\textit{divcur.F90})] 
     68{Horizontal divergence and relative vorticity (\protect\mdl{divcur})} 
    6869\label{subsec:DYN_divcur} 
    6970 
     
    101102%           Sea Surface Height evolution 
    102103%-------------------------------------------------------------------------------------------------------------- 
    103 \subsection{Horizontal divergence and relative vorticity (\protect\mdl{sshwzv})} 
     104\subsection[Horizontal divergence and relative vorticity (\textit{sshwzv.F90})] 
     105{Horizontal divergence and relative vorticity (\protect\mdl{sshwzv})} 
    104106\label{subsec:DYN_sshwzv} 
    105107 
     
    127129Replacing $T$ by the number $1$ in the tracer equation and summing over the water column must lead to 
    128130the sea surface height equation otherwise tracer content will not be conserved 
    129 \citep{Griffies_al_MWR01, Leclair_Madec_OM09}. 
     131\citep{griffies.pacanowski.ea_MWR01, leclair.madec_OM09}. 
    130132 
    131133The vertical velocity is computed by an upward integration of the horizontal divergence starting at the bottom, 
     
    181183%        Vorticity term  
    182184% ------------------------------------------------------------------------------------------------------------- 
    183 \subsection{Vorticity term (\protect\mdl{dynvor})} 
     185\subsection[Vorticity term (\textit{dynvor.F90})] 
     186{Vorticity term (\protect\mdl{dynvor})} 
    184187\label{subsec:DYN_vor} 
    185188%------------------------------------------nam_dynvor---------------------------------------------------- 
     
    203206%                 enstrophy conserving scheme 
    204207%------------------------------------------------------------- 
    205 \subsubsection{Enstrophy conserving scheme (\protect\np{ln\_dynvor\_ens}\forcode{ = .true.})} 
     208\subsubsection[Enstrophy conserving scheme (\forcode{ln_dynvor_ens = .true.})] 
     209{Enstrophy conserving scheme (\protect\np{ln\_dynvor\_ens}\forcode{ = .true.})} 
    206210\label{subsec:DYN_vor_ens} 
    207211 
     
    226230%                 energy conserving scheme 
    227231%------------------------------------------------------------- 
    228 \subsubsection{Energy conserving scheme (\protect\np{ln\_dynvor\_ene}\forcode{ = .true.})} 
     232\subsubsection[Energy conserving scheme (\forcode{ln_dynvor_ene = .true.})] 
     233{Energy conserving scheme (\protect\np{ln\_dynvor\_ene}\forcode{ = .true.})} 
    229234\label{subsec:DYN_vor_ene} 
    230235 
     
    246251%                 mix energy/enstrophy conserving scheme 
    247252%------------------------------------------------------------- 
    248 \subsubsection{Mixed energy/enstrophy conserving scheme (\protect\np{ln\_dynvor\_mix}\forcode{ = .true.}) } 
     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.})} 
    249255\label{subsec:DYN_vor_mix} 
    250256 
     
    271277%                 energy and enstrophy conserving scheme 
    272278%------------------------------------------------------------- 
    273 \subsubsection{Energy and enstrophy conserving scheme (\protect\np{ln\_dynvor\_een}\forcode{ = .true.}) } 
     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.})} 
    274281\label{subsec:DYN_vor_een} 
    275282 
     
    287294Nevertheless, this technique strongly distort the phase and group velocity of Rossby waves....} 
    288295 
    289 A very nice solution to the problem of double averaging was proposed by \citet{Arakawa_Hsu_MWR90}. 
     296A very nice solution to the problem of double averaging was proposed by \citet{arakawa.hsu_MWR90}. 
    290297The idea is to get rid of the double averaging by considering triad combinations of vorticity. 
    291298It is noteworthy that this solution is conceptually quite similar to the one proposed by 
    292 \citep{Griffies_al_JPO98} for the discretization of the iso-neutral diffusion operator (see \autoref{apdx:C}). 
    293  
    294 The \citet{Arakawa_Hsu_MWR90} vorticity advection scheme for a single layer is modified  
    295 for spherical coordinates as described by \citet{Arakawa_Lamb_MWR81} to obtain the EEN scheme.  
     299\citep{griffies.gnanadesikan.ea_JPO98} for the discretization of the iso-neutral diffusion operator (see \autoref{apdx:C}). 
     300 
     301The \citet{arakawa.hsu_MWR90} vorticity advection scheme for a single layer is modified  
     302for spherical coordinates as described by \citet{arakawa.lamb_MWR81} to obtain the EEN scheme.  
    296303First consider the discrete expression of the potential vorticity, $q$, defined at an $f$-point:  
    297304\[ 
     
    309316\begin{figure}[!ht] 
    310317  \begin{center} 
    311     \includegraphics[width=0.70\textwidth]{Fig_DYN_een_triad} 
     318    \includegraphics[width=\textwidth]{Fig_DYN_een_triad} 
    312319    \caption{ 
    313320      \protect\label{fig:DYN_een_triad} 
     
    327334(with a systematic reduction of $e_{3f}$ when a model level intercept the bathymetry) 
    328335that tends to reinforce the topostrophy of the flow 
    329 (\ie the tendency of the flow to follow the isobaths) \citep{Penduff_al_OS07}.  
     336(\ie the tendency of the flow to follow the isobaths) \citep{penduff.le-sommer.ea_OS07}.  
    330337 
    331338Next, the vorticity triads, $ {^i_j}\mathbb{Q}^{i_p}_{j_p}$ can be defined at a $T$-point as 
     
    356363(\ie $\chi$=$0$) (see \autoref{subsec:C_vorEEN}).  
    357364Applied to a realistic ocean configuration, it has been shown that it leads to a significant reduction of 
    358 the noise in the vertical velocity field \citep{Le_Sommer_al_OM09}. 
     365the noise in the vertical velocity field \citep{le-sommer.penduff.ea_OM09}. 
    359366Furthermore, used in combination with a partial steps representation of bottom topography, 
    360367it improves the interaction between current and topography, 
    361 leading to a larger topostrophy of the flow \citep{Barnier_al_OD06, Penduff_al_OS07}.  
     368leading to a larger topostrophy of the flow \citep{barnier.madec.ea_OD06, penduff.le-sommer.ea_OS07}.  
    362369 
    363370%-------------------------------------------------------------------------------------------------------------- 
    364371%           Kinetic Energy Gradient term 
    365372%-------------------------------------------------------------------------------------------------------------- 
    366 \subsection{Kinetic energy gradient term (\protect\mdl{dynkeg})} 
     373\subsection[Kinetic energy gradient term (\textit{dynkeg.F90})] 
     374{Kinetic energy gradient term (\protect\mdl{dynkeg})} 
    367375\label{subsec:DYN_keg} 
    368376 
     
    384392%           Vertical advection term 
    385393%-------------------------------------------------------------------------------------------------------------- 
    386 \subsection{Vertical advection term (\protect\mdl{dynzad}) } 
     394\subsection[Vertical advection term (\textit{dynzad.F90})] 
     395{Vertical advection term (\protect\mdl{dynzad})} 
    387396\label{subsec:DYN_zad} 
    388397 
     
    403412When \np{ln\_dynzad\_zts}\forcode{ = .true.}, 
    404413a split-explicit time stepping with 5 sub-timesteps is used on the vertical advection term. 
    405 This option can be useful when the value of the timestep is limited by vertical advection \citep{Lemarie_OM2015}.  
     414This option can be useful when the value of the timestep is limited by vertical advection \citep{lemarie.debreu.ea_OM15}.  
    406415Note that in this case, 
    407416a similar split-explicit time stepping should be used on vertical advection of tracer to ensure a better stability, 
     
    430439%           Coriolis plus curvature metric terms 
    431440%-------------------------------------------------------------------------------------------------------------- 
    432 \subsection{Coriolis plus curvature metric terms (\protect\mdl{dynvor}) } 
     441\subsection[Coriolis plus curvature metric terms (\textit{dynvor.F90})] 
     442{Coriolis plus curvature metric terms (\protect\mdl{dynvor})} 
    433443\label{subsec:DYN_cor_flux} 
    434444 
     
    451461%           Flux form Advection term 
    452462%-------------------------------------------------------------------------------------------------------------- 
    453 \subsection{Flux form advection term (\protect\mdl{dynadv}) } 
     463\subsection[Flux form advection term (\textit{dynadv.F90})] 
     464{Flux form advection term (\protect\mdl{dynadv})} 
    454465\label{subsec:DYN_adv_flux} 
    455466 
     
    475486a $2^{nd}$ order centered finite difference scheme, CEN2, 
    476487or a $3^{rd}$ order upstream biased scheme, UBS. 
    477 The latter is described in \citet{Shchepetkin_McWilliams_OM05}. 
     488The latter is described in \citet{shchepetkin.mcwilliams_OM05}. 
    478489The schemes are selected using the namelist logicals \np{ln\_dynadv\_cen2} and \np{ln\_dynadv\_ubs}.  
    479490In flux form, the schemes differ by the choice of a space and time interpolation to define the value of 
     
    484495%                 2nd order centred scheme 
    485496%------------------------------------------------------------- 
    486 \subsubsection{CEN2: $2^{nd}$ order centred scheme (\protect\np{ln\_dynadv\_cen2}\forcode{ = .true.})} 
     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.})} 
    487499\label{subsec:DYN_adv_cen2} 
    488500 
     
    507519%                 UBS scheme 
    508520%------------------------------------------------------------- 
    509 \subsubsection{UBS: Upstream Biased Scheme (\protect\np{ln\_dynadv\_ubs}\forcode{ = .true.})} 
     521\subsubsection[UBS: Upstream Biased Scheme (\forcode{ln_dynadv_ubs = .true.})] 
     522{UBS: Upstream Biased Scheme (\protect\np{ln\_dynadv\_ubs}\forcode{ = .true.})} 
    510523\label{subsec:DYN_adv_ubs} 
    511524 
     
    523536where $u"_{i+1/2} =\delta_{i+1/2} \left[ {\delta_i \left[ u \right]} \right]$. 
    524537This results in a dissipatively dominant (\ie hyper-diffusive) truncation error 
    525 \citep{Shchepetkin_McWilliams_OM05}. 
    526 The overall performance of the advection scheme is similar to that reported in \citet{Farrow1995}. 
     538\citep{shchepetkin.mcwilliams_OM05}. 
     539The overall performance of the advection scheme is similar to that reported in \citet{farrow.stevens_JPO95}. 
    527540It is a relatively good compromise between accuracy and smoothness. 
    528541It is not a \emph{positive} scheme, meaning that false extrema are permitted. 
     
    542555while the second term, which is the diffusion part of the scheme, 
    543556is evaluated using the \textit{before} velocity (forward in time). 
    544 This is discussed by \citet{Webb_al_JAOT98} in the context of the Quick advection scheme. 
     557This is discussed by \citet{webb.de-cuevas.ea_JAOT98} in the context of the Quick advection scheme. 
    545558 
    546559Note that the UBS and QUICK (Quadratic Upstream Interpolation for Convective Kinematics) schemes only differ by 
    547560one coefficient. 
    548 Replacing $1/6$ by $1/8$ in (\autoref{eq:dynadv_ubs}) leads to the QUICK advection scheme \citep{Webb_al_JAOT98}. 
     561Replacing $1/6$ by $1/8$ in (\autoref{eq:dynadv_ubs}) leads to the QUICK advection scheme \citep{webb.de-cuevas.ea_JAOT98}. 
    549562This option is not available through a namelist parameter, since the $1/6$ coefficient is hard coded. 
    550563Nevertheless it is quite easy to make the substitution in the \mdl{dynadv\_ubs} module and obtain a QUICK scheme. 
     
    560573%           Hydrostatic pressure gradient term 
    561574% ================================================================ 
    562 \section{Hydrostatic pressure gradient (\protect\mdl{dynhpg})} 
     575\section[Hydrostatic pressure gradient (\textit{dynhpg.F90})] 
     576{Hydrostatic pressure gradient (\protect\mdl{dynhpg})} 
    563577\label{sec:DYN_hpg} 
    564578%------------------------------------------nam_dynhpg--------------------------------------------------- 
     
    582596%           z-coordinate with full step 
    583597%-------------------------------------------------------------------------------------------------------------- 
    584 \subsection{Full step $Z$-coordinate (\protect\np{ln\_dynhpg\_zco}\forcode{ = .true.})} 
     598\subsection[Full step $Z$-coordinate (\forcode{ln_dynhpg_zco = .true.})] 
     599{Full step $Z$-coordinate (\protect\np{ln\_dynhpg\_zco}\forcode{ = .true.})} 
    585600\label{subsec:DYN_hpg_zco} 
    586601 
     
    627642%           z-coordinate with partial step 
    628643%-------------------------------------------------------------------------------------------------------------- 
    629 \subsection{Partial step $Z$-coordinate (\protect\np{ln\_dynhpg\_zps}\forcode{ = .true.})} 
     644\subsection[Partial step $Z$-coordinate (\forcode{ln_dynhpg_zps = .true.})] 
     645{Partial step $Z$-coordinate (\protect\np{ln\_dynhpg\_zps}\forcode{ = .true.})} 
    630646\label{subsec:DYN_hpg_zps} 
    631647 
     
    652668 
    653669Pressure gradient formulations in an $s$-coordinate have been the subject of a vast number of papers 
    654 (\eg, \citet{Song1998, Shchepetkin_McWilliams_OM05}).  
     670(\eg, \citet{song_MWR98, shchepetkin.mcwilliams_OM05}).  
    655671A number of different pressure gradient options are coded but the ROMS-like, 
    656672density Jacobian with cubic polynomial method is currently disabled whilst known bugs are under investigation. 
    657673 
    658 $\bullet$ Traditional coding (see for example \citet{Madec_al_JPO96}: (\np{ln\_dynhpg\_sco}\forcode{ = .true.}) 
     674$\bullet$ Traditional coding (see for example \citet{madec.delecluse.ea_JPO96}: (\np{ln\_dynhpg\_sco}\forcode{ = .true.}) 
    659675\begin{equation} 
    660676  \label{eq:dynhpg_sco} 
     
    679695$\bullet$ Pressure Jacobian scheme (prj) (a research paper in preparation) (\np{ln\_dynhpg\_prj}\forcode{ = .true.}) 
    680696 
    681 $\bullet$ Density Jacobian with cubic polynomial scheme (DJC) \citep{Shchepetkin_McWilliams_OM05}  
     697$\bullet$ Density Jacobian with cubic polynomial scheme (DJC) \citep{shchepetkin.mcwilliams_OM05}  
    682698(\np{ln\_dynhpg\_djc}\forcode{ = .true.}) (currently disabled; under development) 
    683699 
    684700Note that expression \autoref{eq:dynhpg_sco} is commonly used when the variable volume formulation is activated 
    685701(\key{vvl}) because in that case, even with a flat bottom, 
    686 the coordinate surfaces are not horizontal but follow the free surface \citep{Levier2007}. 
     702the coordinate surfaces are not horizontal but follow the free surface \citep{levier.treguier.ea_rpt07}. 
    687703The pressure jacobian scheme (\np{ln\_dynhpg\_prj}\forcode{ = .true.}) is available as 
    688704an improved option to \np{ln\_dynhpg\_sco}\forcode{ = .true.} when \key{vvl} is active. 
     
    704720corresponds to the water replaced by the ice shelf. 
    705721This top pressure is constant over time. 
    706 A detailed description of this method is described in \citet{Losch2008}.\\ 
     722A detailed description of this method is described in \citet{losch_JGR08}.\\ 
    707723 
    708724The pressure gradient due to ocean load is computed using the expression \autoref{eq:dynhpg_sco} described in 
     
    712728%           Time-scheme 
    713729%-------------------------------------------------------------------------------------------------------------- 
    714 \subsection{Time-scheme (\protect\np{ln\_dynhpg\_imp}\forcode{ = .true./.false.})} 
     730\subsection[Time-scheme (\forcode{ln_dynhpg_imp = .{true,false}.})] 
     731{Time-scheme (\protect\np{ln\_dynhpg\_imp}\forcode{ = .\{true,false\}}.)} 
    715732\label{subsec:DYN_hpg_imp} 
    716733 
     
    722739the physical phenomenon that controls the time-step is internal gravity waves (IGWs). 
    723740A semi-implicit scheme for doubling the stability limit associated with IGWs can be used 
    724 \citep{Brown_Campana_MWR78, Maltrud1998}. 
     741\citep{brown.campana_MWR78, maltrud.smith.ea_JGR98}. 
    725742It involves the evaluation of the hydrostatic pressure gradient as 
    726743an average over the three time levels $t-\rdt$, $t$, and $t+\rdt$ 
     
    773790% Surface Pressure Gradient 
    774791% ================================================================ 
    775 \section{Surface pressure gradient (\protect\mdl{dynspg})} 
     792\section[Surface pressure gradient (\textit{dynspg.F90})] 
     793{Surface pressure gradient (\protect\mdl{dynspg})} 
    776794\label{sec:DYN_spg} 
    777795%-----------------------------------------nam_dynspg---------------------------------------------------- 
     
    790808which imposes a very small time step when an explicit time stepping is used. 
    791809Two methods are proposed to allow a longer time step for the three-dimensional equations:  
    792 the filtered free surface, which is a modification of the continuous equations (see \autoref{eq:PE_flt}),  
     810the filtered free surface, which is a modification of the continuous equations (see \autoref{eq:PE_flt?}),  
    793811and the split-explicit free surface described below. 
    794812The extra term introduced in the filtered method is calculated implicitly,  
     
    811829% Explicit free surface formulation 
    812830%-------------------------------------------------------------------------------------------------------------- 
    813 \subsection{Explicit free surface (\protect\key{dynspg\_exp})} 
     831\subsection[Explicit free surface (\texttt{\textbf{key\_dynspg\_exp}})] 
     832{Explicit free surface (\protect\key{dynspg\_exp})} 
    814833\label{subsec:DYN_spg_exp} 
    815834 
     
    837856% Split-explict free surface formulation 
    838857%-------------------------------------------------------------------------------------------------------------- 
    839 \subsection{Split-explicit free surface (\protect\key{dynspg\_ts})} 
     858\subsection[Split-explicit free surface (\texttt{\textbf{key\_dynspg\_ts}})] 
     859{Split-explicit free surface (\protect\key{dynspg\_ts})} 
    840860\label{subsec:DYN_spg_ts} 
    841861%------------------------------------------namsplit----------------------------------------------------------- 
     
    845865 
    846866The split-explicit free surface formulation used in \NEMO (\key{dynspg\_ts} defined), 
    847 also called the time-splitting formulation, follows the one proposed by \citet{Shchepetkin_McWilliams_OM05}. 
     867also called the time-splitting formulation, follows the one proposed by \citet{shchepetkin.mcwilliams_OM05}. 
    848868The general idea is to solve the free surface equation and the associated barotropic velocity equations with 
    849869a smaller time step than $\rdt$, the time step used for the three dimensional prognostic variables 
     
    862882\begin{equation} 
    863883  \label{eq:BT_dyn} 
    864   \frac{\partial {\rm \overline{{\bf U}}_h} }{\partial t}= 
    865   -f\;{\rm {\bf k}}\times {\rm \overline{{\bf U}}_h} 
    866   -g\nabla _h \eta -\frac{c_b^{\textbf U}}{H+\eta} \rm {\overline{{\bf U}}_h} + \rm {\overline{\bf G}} 
     884  \frac{\partial {\mathrm \overline{{\mathbf U}}_h} }{\partial t}= 
     885  -f\;{\mathrm {\mathbf k}}\times {\mathrm \overline{{\mathbf U}}_h} 
     886  -g\nabla _h \eta -\frac{c_b^{\textbf U}}{H+\eta} \mathrm {\overline{{\mathbf U}}_h} + \mathrm {\overline{\mathbf G}} 
    867887\end{equation} 
    868888\[ 
    869889  % \label{eq:BT_ssh} 
    870   \frac{\partial \eta }{\partial t}=-\nabla \cdot \left[ {\left( {H+\eta } \right) \; {\rm{\bf \overline{U}}}_h \,} \right]+P-E 
     890  \frac{\partial \eta }{\partial t}=-\nabla \cdot \left[ {\left( {H+\eta } \right) \; {\mathrm{\mathbf \overline{U}}}_h \,} \right]+P-E 
    871891\] 
    872892% \end{subequations} 
    873 where $\rm {\overline{\bf G}}$ is a forcing term held constant, containing coupling term between modes, 
     893where $\mathrm {\overline{\mathbf G}}$ is a forcing term held constant, containing coupling term between modes, 
    874894surface atmospheric forcing as well as slowly varying barotropic terms not explicitly computed to gain efficiency. 
    875895The third term on the right hand side of \autoref{eq:BT_dyn} represents the bottom stress 
    876896(see section \autoref{sec:ZDF_bfr}), explicitly accounted for at each barotropic iteration. 
    877897Temporal discretization of the system above follows a three-time step Generalized Forward Backward algorithm 
    878 detailed in \citet{Shchepetkin_McWilliams_OM05}. 
     898detailed in \citet{shchepetkin.mcwilliams_OM05}. 
    879899AB3-AM4 coefficients used in \NEMO follow the second-order accurate, 
    880 "multi-purpose" stability compromise as defined in \citet{Shchepetkin_McWilliams_Bk08} 
     900"multi-purpose" stability compromise as defined in \citet{shchepetkin.mcwilliams_ibk09} 
    881901(see their figure 12, lower left).  
    882902 
     
    884904\begin{figure}[!t] 
    885905  \begin{center} 
    886     \includegraphics[width=0.7\textwidth]{Fig_DYN_dynspg_ts} 
     906    \includegraphics[width=\textwidth]{Fig_DYN_dynspg_ts} 
    887907    \caption{ 
    888908      \protect\label{fig:DYN_dynspg_ts} 
     
    936956and time splitting not compatible. 
    937957Advective barotropic velocities are obtained by using a secondary set of filtering weights, 
    938 uniquely defined from the filter coefficients used for the time averaging (\citet{Shchepetkin_McWilliams_OM05}). 
     958uniquely defined from the filter coefficients used for the time averaging (\citet{shchepetkin.mcwilliams_OM05}). 
    939959Consistency between the time averaged continuity equation and the time stepping of tracers is here the key to 
    940960obtain exact conservation. 
     
    953973external gravity waves in idealized or weakly non-linear cases. 
    954974Although the damping is lower than for the filtered free surface, 
    955 it is still significant as shown by \citet{Levier2007} in the case of an analytical barotropic Kelvin wave. 
     975it is still significant as shown by \citet{levier.treguier.ea_rpt07} in the case of an analytical barotropic Kelvin wave. 
    956976 
    957977%>>>>>=============== 
     
    10511071the leap-frog splitting mode in equation \autoref{eq:DYN_spg_ts_ssh}. 
    10521072We have tried various forms of such filtering, 
    1053 with the following method discussed in \cite{Griffies_al_MWR01} chosen due to 
     1073with the following method discussed in \cite{griffies.pacanowski.ea_MWR01} chosen due to 
    10541074its stability and reasonably good maintenance of tracer conservation properties (see ??). 
    10551075 
     
    10811101% Filtered free surface formulation 
    10821102%-------------------------------------------------------------------------------------------------------------- 
    1083 \subsection{Filtered free surface (\protect\key{dynspg\_flt})} 
     1103\subsection[Filtered free surface (\texttt{\textbf{key\_dynspg\_flt}})] 
     1104{Filtered free surface (\protect\key{dynspg\_flt})} 
    10841105\label{subsec:DYN_spg_fltp} 
    10851106 
    1086 The filtered formulation follows the \citet{Roullet_Madec_JGR00} implementation.  
     1107The filtered formulation follows the \citet{roullet.madec_JGR00} implementation.  
    10871108The extra term introduced in the equations (see \autoref{subsec:PE_free_surface}) is solved implicitly.  
    10881109The elliptic solvers available in the code are documented in \autoref{chap:MISC}. 
     
    10921113  \[ 
    10931114    % \label{eq:spg_flt} 
    1094     \frac{\partial {\rm {\bf U}}_h }{\partial t}= {\rm {\bf M}} 
     1115    \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= {\mathrm {\mathbf M}} 
    10951116    - g \nabla \left( \tilde{\rho} \ \eta \right) 
    10961117    - g \ T_c \nabla \left( \widetilde{\rho} \ \partial_t \eta \right) 
     
    10981119  where $T_c$, is a parameter with dimensions of time which characterizes the force, 
    10991120  $\widetilde{\rho} = \rho / \rho_o$ is the dimensionless density, 
    1100   and $\rm {\bf M}$ represents the collected contributions of the Coriolis, hydrostatic pressure gradient, 
     1121  and $\mathrm {\mathbf M}$ represents the collected contributions of the Coriolis, hydrostatic pressure gradient, 
    11011122  non-linear and viscous terms in \autoref{eq:PE_dyn}. 
    11021123}   %end gmcomment 
     
    11091130% Lateral diffusion term 
    11101131% ================================================================ 
    1111 \section{Lateral diffusion term and operators (\protect\mdl{dynldf})} 
     1132\section[Lateral diffusion term and operators (\textit{dynldf.F90})] 
     1133{Lateral diffusion term and operators (\protect\mdl{dynldf})} 
    11121134\label{sec:DYN_ldf} 
    11131135%------------------------------------------nam_dynldf---------------------------------------------------- 
     
    11431165 
    11441166% ================================================================ 
    1145 \subsection[Iso-level laplacian (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})] 
    1146             {Iso-level laplacian operator (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})} 
     1167\subsection[Iso-level laplacian (\forcode{ln_dynldf_lap = .true.})] 
     1168{Iso-level laplacian operator (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})} 
    11471169\label{subsec:DYN_ldf_lap} 
    11481170 
     
    11521174  \left\{ 
    11531175    \begin{aligned} 
    1154       D_u^{l{\rm {\bf U}}} =\frac{1}{e_{1u} }\delta_{i+1/2} \left[ {A_T^{lm} 
     1176      D_u^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{1u} }\delta_{i+1/2} \left[ {A_T^{lm} 
    11551177          \;\chi } \right]-\frac{1}{e_{2u} {\kern 1pt}e_{3u} }\delta_j \left[  
    11561178        {A_f^{lm} \;e_{3f} \zeta } \right] \\ \\ 
    1157       D_v^{l{\rm {\bf U}}} =\frac{1}{e_{2v} }\delta_{j+1/2} \left[ {A_T^{lm} 
     1179      D_v^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{2v} }\delta_{j+1/2} \left[ {A_T^{lm} 
    11581180          \;\chi } \right]+\frac{1}{e_{1v} {\kern 1pt}e_{3v} }\delta_i \left[  
    11591181        {A_f^{lm} \;e_{3f} \zeta } \right] 
     
    11691191%           Rotated laplacian operator 
    11701192%-------------------------------------------------------------------------------------------------------------- 
    1171 \subsection[Rotated laplacian (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})] 
    1172             {Rotated laplacian operator (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})} 
     1193\subsection[Rotated laplacian (\forcode{ln_dynldf_iso = .true.})] 
     1194{Rotated laplacian operator (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})} 
    11731195\label{subsec:DYN_ldf_iso} 
    11741196 
     
    12281250%           Iso-level bilaplacian operator 
    12291251%-------------------------------------------------------------------------------------------------------------- 
    1230 \subsection[Iso-level bilaplacian (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})] 
    1231             {Iso-level bilaplacian operator (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})} 
     1252\subsection[Iso-level bilaplacian (\forcode{ln_dynldf_bilap = .true.})] 
     1253{Iso-level bilaplacian operator (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})} 
    12321254\label{subsec:DYN_ldf_bilap} 
    12331255 
     
    12431265%           Vertical diffusion term 
    12441266% ================================================================ 
    1245 \section{Vertical diffusion term (\protect\mdl{dynzdf})} 
     1267\section[Vertical diffusion term (\textit{dynzdf.F90})] 
     1268{Vertical diffusion term (\protect\mdl{dynzdf})} 
    12461269\label{sec:DYN_zdf} 
    12471270%----------------------------------------------namzdf------------------------------------------------------ 
     
    13261349There are two main options for wetting and drying code (wd): 
    13271350(a) an iterative limiter (il) and (b) a directional limiter (dl). 
    1328 The directional limiter is based on the scheme developed by \cite{WarnerEtal13} for RO 
     1351The directional limiter is based on the scheme developed by \cite{warner.defne.ea_CG13} for RO 
    13291352MS 
    1330 which was in turn based on ideas developed for POM by \cite{Oey06}. The iterative 
     1353which was in turn based on ideas developed for POM by \cite{oey_OM06}. The iterative 
    13311354limiter is a new scheme.  The iterative limiter is activated by setting $\mathrm{ln\_wd\_il} = \mathrm{.true.}$ 
    13321355and $\mathrm{ln\_wd\_dl} = \mathrm{.false.}$. The directional limiter is activated 
     
    13721395%   Iterative limiters 
    13731396%----------------------------------------------------------------------------------------- 
    1374 \subsection   [Directional limiter (\textit{wet\_dry})] 
    1375          {Directional limiter (\mdl{wet\_dry})} 
     1397\subsection[Directional limiter (\textit{wet\_dry.F90})] 
     1398{Directional limiter (\mdl{wet\_dry})} 
    13761399\label{subsec:DYN_wd_directional_limiter} 
    13771400The principal idea of the directional limiter is that 
     
    14001423 
    14011424 
    1402 \cite{WarnerEtal13} state that in their scheme the velocity masks at the cell faces for the baroclinic 
     1425\cite{warner.defne.ea_CG13} state that in their scheme the velocity masks at the cell faces for the baroclinic 
    14031426timesteps are set to 0 or 1 depending on whether the average of the masks over the barotropic sub-steps is respectively less than 
    14041427or greater than 0.5. That scheme does not conserve tracers in integrations started from constant tracer 
     
    14121435%----------------------------------------------------------------------------------------- 
    14131436 
    1414 \subsection   [Iterative limiter (\textit{wet\_dry})] 
    1415          {Iterative limiter (\mdl{wet\_dry})} 
     1437\subsection[Iterative limiter (\textit{wet\_dry.F90})] 
     1438{Iterative limiter (\mdl{wet\_dry})} 
    14161439\label{subsec:DYN_wd_iterative_limiter} 
    14171440 
    1418 \subsubsection [Iterative flux limiter (\textit{wet\_dry})] 
    1419          {Iterative flux limiter (\mdl{wet\_dry})} 
     1441\subsubsection[Iterative flux limiter (\textit{wet\_dry.F90})] 
     1442{Iterative flux limiter (\mdl{wet\_dry})} 
    14201443\label{subsubsec:DYN_wd_il_spg_limiter} 
    14211444 
     
    14941517\end{equation} 
    14951518 
    1496 Note a small tolerance ($\mathrm{rn\_wdmin2}$) has been introduced here {\it [Q: Why is 
     1519Note a small tolerance ($\mathrm{rn\_wdmin2}$) has been introduced here {\itshape [Q: Why is 
    14971520this necessary/desirable?]}. Substituting from (\ref{dyn_wd_continuity_coef}) gives an 
    14981521expression for the coefficient needed to multiply the outward flux at this cell in order 
     
    15221545%      Surface pressure gradients 
    15231546%---------------------------------------------------------------------------------------- 
    1524 \subsubsection   [Modification of surface pressure gradients (\textit{dynhpg})] 
    1525          {Modification of surface pressure gradients (\mdl{dynhpg})} 
     1547\subsubsection[Modification of surface pressure gradients (\textit{dynhpg.F90})] 
     1548{Modification of surface pressure gradients (\mdl{dynhpg})} 
    15261549\label{subsubsec:DYN_wd_il_spg} 
    15271550 
     
    15411564%>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    15421565\begin{figure}[!ht] \begin{center} 
    1543 \includegraphics[width=0.8\textwidth]{Fig_WAD_dynhpg} 
     1566\includegraphics[width=\textwidth]{Fig_WAD_dynhpg} 
    15441567\caption{ \label{Fig_WAD_dynhpg} 
    15451568Illustrations of the three possible combinations of the logical variables controlling the 
     
    15881611conditions. 
    15891612 
    1590 \subsubsection   [Additional considerations (\textit{usrdef\_zgr})] 
    1591          {Additional considerations (\mdl{usrdef\_zgr})} 
     1613\subsubsection[Additional considerations (\textit{usrdef\_zgr.F90})] 
     1614{Additional considerations (\mdl{usrdef\_zgr})} 
    15921615\label{subsubsec:WAD_additional} 
    15931616 
     
    16031626%      The WAD test cases 
    16041627%---------------------------------------------------------------------------------------- 
    1605 \subsection   [The WAD test cases (\textit{usrdef\_zgr})] 
    1606          {The WAD test cases (\mdl{usrdef\_zgr})} 
     1628\subsection[The WAD test cases (\textit{usrdef\_zgr.F90})] 
     1629{The WAD test cases (\mdl{usrdef\_zgr})} 
    16071630\label{WAD_test_cases} 
    16081631 
     
    16141637% Time evolution term  
    16151638% ================================================================ 
    1616 \section{Time evolution term (\protect\mdl{dynnxt})} 
     1639\section[Time evolution term (\textit{dynnxt.F90})] 
     1640{Time evolution term (\protect\mdl{dynnxt})} 
    16171641\label{sec:DYN_nxt} 
    16181642 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_LBC.tex

    r10614 r11422  
    1717% Boundary Condition at the Coast 
    1818% ================================================================ 
    19 \section{Boundary condition at the coast (\protect\np{rn\_shlat})} 
     19\section[Boundary condition at the coast (\texttt{rn\_shlat})] 
     20{Boundary condition at the coast (\protect\np{rn\_shlat})} 
    2021\label{sec:LBC_coast} 
    2122%--------------------------------------------nam_lbc------------------------------------------------------- 
     
    5657\begin{figure}[!t] 
    5758  \begin{center} 
    58     \includegraphics[width=0.90\textwidth]{Fig_LBC_uv} 
     59    \includegraphics[width=\textwidth]{Fig_LBC_uv} 
    5960    \caption{ 
    6061      \protect\label{fig:LBC_uv} 
     
    8586\begin{figure}[!p] 
    8687  \begin{center} 
    87     \includegraphics[width=0.90\textwidth]{Fig_LBC_shlat} 
     88    \includegraphics[width=\textwidth]{Fig_LBC_shlat} 
    8889    \caption{ 
    8990      \protect\label{fig:LBC_shlat} 
     
    147148% Boundary Condition around the Model Domain 
    148149% ================================================================ 
    149 \section{Model domain boundary condition (\protect\np{jperio})} 
     150\section[Model domain boundary condition (\texttt{jperio})] 
     151{Model domain boundary condition (\protect\np{jperio})} 
    150152\label{sec:LBC_jperio} 
    151153 
     
    158160%        Closed, cyclic (\np{jperio}\forcode{ = 0..2})  
    159161% ------------------------------------------------------------------------------------------------------------- 
    160 \subsection{Closed, cyclic (\protect\np{jperio}\forcode{= [0127]})} 
     162\subsection[Closed, cyclic (\forcode{jperio = [0127]})] 
     163{Closed, cyclic (\protect\np{jperio}\forcode{ = [0127]})} 
    161164\label{subsec:LBC_jperio012} 
    162165 
     
    194197\begin{figure}[!t] 
    195198  \begin{center} 
    196     \includegraphics[width=1.0\textwidth]{Fig_LBC_jperio} 
     199    \includegraphics[width=\textwidth]{Fig_LBC_jperio} 
    197200    \caption{ 
    198201      \protect\label{fig:LBC_jperio} 
     
    206209%        North fold (\textit{jperio = 3 }to $6)$  
    207210% ------------------------------------------------------------------------------------------------------------- 
    208 \subsection{North-fold (\protect\np{jperio}\forcode{ = 3..6})} 
     211\subsection[North-fold (\forcode{jperio = [3-6]})] 
     212{North-fold (\protect\np{jperio}\forcode{ = [3-6]})} 
    209213\label{subsec:LBC_north_fold} 
    210214 
     
    218222\begin{figure}[!t] 
    219223  \begin{center} 
    220     \includegraphics[width=0.90\textwidth]{Fig_North_Fold_T} 
     224    \includegraphics[width=\textwidth]{Fig_North_Fold_T} 
    221225    \caption{ 
    222226      \protect\label{fig:North_Fold_T} 
     
    232236% Exchange with neighbouring processors  
    233237% ==================================================================== 
    234 \section{Exchange with neighbouring processors (\protect\mdl{lbclnk}, \protect\mdl{lib\_mpp})} 
     238\section[Exchange with neighbouring processors (\textit{lbclnk.F90}, \textit{lib\_mpp.F90})] 
     239{Exchange with neighbouring processors (\protect\mdl{lbclnk}, \protect\mdl{lib\_mpp})} 
    235240\label{sec:LBC_mpp} 
    236241 
     
    280285\begin{figure}[!t] 
    281286  \begin{center} 
    282     \includegraphics[width=0.90\textwidth]{Fig_mpp} 
     287    \includegraphics[width=\textwidth]{Fig_mpp} 
    283288    \caption{ 
    284289      \protect\label{fig:mpp} 
     
    360365\begin{figure}[!ht] 
    361366  \begin{center} 
    362     \includegraphics[width=0.90\textwidth]{Fig_mppini2} 
     367    \includegraphics[width=\textwidth]{Fig_mppini2} 
    363368    \caption { 
    364369      \protect\label{fig:mppini2} 
     
    395400 
    396401The BDY module was modelled on the OBC module (see NEMO 3.4) and shares many features and 
    397 a similar coding structure \citep{Chanut2005}. 
     402a similar coding structure \citep{chanut_rpt05}. 
    398403The specification of the location of the open boundary is completely flexible and 
    399404allows for example the open boundary to follow an isobath or other irregular contour.  
     
    475480\label{subsec:BDY_FRS_scheme} 
    476481 
    477 The Flow Relaxation Scheme (FRS) \citep{Davies_QJRMS76,Engerdahl_Tel95}, 
     482The Flow Relaxation Scheme (FRS) \citep{davies_QJRMS76,engedahl_T95}, 
    478483applies a simple relaxation of the model fields to externally-specified values over 
    479484a zone next to the edge of the model domain. 
     
    514519\label{subsec:BDY_flather_scheme} 
    515520 
    516 The \citet{Flather_JPO94} scheme is a radiation condition on the normal, 
     521The \citet{flather_JPO94} scheme is a radiation condition on the normal, 
    517522depth-mean transport across the open boundary. 
    518523It takes the form 
     
    535540\label{subsec:BDY_orlanski_scheme} 
    536541 
    537 The Orlanski scheme is based on the algorithm described by \citep{Marchesiello2001}, hereafter MMS. 
     542The Orlanski scheme is based on the algorithm described by \citep{marchesiello.mcwilliams.ea_OM01}, hereafter MMS. 
    538543 
    539544The adaptive Orlanski condition solves a wave plus relaxation equation at the boundary: 
     
    636641\begin{figure}[!t] 
    637642  \begin{center} 
    638     \includegraphics[width=1.0\textwidth]{Fig_LBC_bdy_geom} 
     643    \includegraphics[width=\textwidth]{Fig_LBC_bdy_geom} 
    639644    \caption { 
    640645      \protect\label{fig:LBC_bdy_geom} 
     
    670675These restrictions mean that data files used with versions of the 
    671676model prior to Version 3.4 may not work with Version 3.4 onwards. 
    672 A \fortran utility {\it bdy\_reorder} exists in the TOOLS directory which 
     677A \fortran utility {\itshape bdy\_reorder} exists in the TOOLS directory which 
    673678will re-order the data in old BDY data files. 
    674679 
     
    676681\begin{figure}[!t] 
    677682  \begin{center} 
    678     \includegraphics[width=1.0\textwidth]{Fig_LBC_nc_header} 
     683    \includegraphics[width=\textwidth]{Fig_LBC_nc_header} 
    679684    \caption { 
    680685      \protect\label{fig:LBC_nc_header} 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_LDF.tex

    r10442 r11422  
    2323These three aspects of the lateral diffusion are set through namelist parameters 
    2424(see the \ngn{nam\_traldf} and \ngn{nam\_dynldf} below). 
    25 Note that this chapter describes the standard implementation of iso-neutral tracer mixing, 
    26 and Griffies's implementation, which is used if \np{traldf\_grif}\forcode{ = .true.}, 
    27 is described in Appdx\autoref{apdx:triad} 
    28  
    29 %-----------------------------------nam_traldf - nam_dynldf-------------------------------------------- 
     25Note that this chapter describes the standard implementation of iso-neutral tracer mixing.  
     26Griffies's implementation, which is used if \np{ln\_traldf\_triad}\forcode{ = .true.}, 
     27is described in \autoref{apdx:triad} 
     28 
     29%-----------------------------------namtra_ldf - namdyn_ldf-------------------------------------------- 
    3030 
    3131\nlst{namtra_ldf}  
     
    3434%-------------------------------------------------------------------------------------------------------------- 
    3535 
     36% ================================================================ 
     37% Lateral Mixing Operator 
     38% ================================================================ 
     39\section[Lateral mixing operators] 
     40{Lateral mixing operators} 
     41\label{sec:LDF_op} 
     42We remind here the different lateral mixing operators that can be used. Further details can be found in \autoref{subsec:TRA_ldf_op} and  \autoref{sec:DYN_ldf}. 
     43 
     44\subsection[No lateral mixing (\forcode{ln_traldf_OFF}, \forcode{ln_dynldf_OFF})] 
     45{No lateral mixing (\protect\np{ln\_traldf\_OFF}, \protect\np{ln\_dynldf\_OFF})} 
     46 
     47It is possible to run without explicit lateral diffusion on tracers (\protect\np{ln\_traldf\_OFF}\forcode{ = .true.}) and/or  
     48momentum (\protect\np{ln\_dynldf\_OFF}\forcode{ = .true.}). The latter option is even recommended if using the  
     49UBS advection scheme on momentum (\np{ln\_dynadv\_ubs}\forcode{ = .true.}, 
     50see \autoref{subsec:DYN_adv_ubs}) and can be useful for testing purposes. 
     51 
     52\subsection[Laplacian mixing (\forcode{ln_traldf_lap}, \forcode{ln_dynldf_lap})] 
     53{Laplacian mixing (\protect\np{ln\_traldf\_lap}, \protect\np{ln\_dynldf\_lap})} 
     54Setting \protect\np{ln\_traldf\_lap}\forcode{ = .true.} and/or \protect\np{ln\_dynldf\_lap}\forcode{ = .true.} enables  
     55a second order diffusion on tracers and momentum respectively. Note that in \NEMO 4, one can not combine  
     56Laplacian and Bilaplacian operators for the same variable. 
     57 
     58\subsection[Bilaplacian mixing (\forcode{ln_traldf_blp}, \forcode{ln_dynldf_blp})] 
     59{Bilaplacian mixing (\protect\np{ln\_traldf\_blp}, \protect\np{ln\_dynldf\_blp})} 
     60Setting \protect\np{ln\_traldf\_blp}\forcode{ = .true.} and/or \protect\np{ln\_dynldf\_blp}\forcode{ = .true.} enables  
     61a fourth order diffusion on tracers and momentum respectively. It is implemented by calling the above Laplacian operator twice.  
     62We stress again that from \NEMO 4, the simultaneous use Laplacian and Bilaplacian operators is not allowed. 
    3663 
    3764% ================================================================ 
    3865% Direction of lateral Mixing 
    3966% ================================================================ 
    40 \section{Direction of lateral mixing (\protect\mdl{ldfslp})} 
     67\section[Direction of lateral mixing (\textit{ldfslp.F90})] 
     68{Direction of lateral mixing (\protect\mdl{ldfslp})} 
    4169\label{sec:LDF_slp} 
    4270 
     
    4472\gmcomment{ 
    4573  we should emphasize here that the implementation is a rather old one. 
    46   Better work can be achieved by using \citet{Griffies_al_JPO98, Griffies_Bk04} iso-neutral scheme. 
     74  Better work can be achieved by using \citet{griffies.gnanadesikan.ea_JPO98, griffies_bk04} iso-neutral scheme. 
    4775} 
    4876 
     
    87115%gm%  caution I'm not sure the simplification was a good idea!  
    88116 
    89 These slopes are computed once in \rou{ldfslp\_init} when \np{ln\_sco}\forcode{ = .true.}rue, 
     117These slopes are computed once in \rou{ldf\_slp\_init} when \np{ln\_sco}\forcode{ = .true.}, 
    90118and either \np{ln\_traldf\_hor}\forcode{ = .true.} or \np{ln\_dynldf\_hor}\forcode{ = .true.}.  
    91119 
     
    119147%In practice, \autoref{eq:ldfslp_iso} is of little help in evaluating the neutral surface slopes. Indeed, for an unsimplified equation of state, the density has a strong dependancy on pressure (here approximated as the depth), therefore applying \autoref{eq:ldfslp_iso} using the $in situ$ density, $\rho$, computed at T-points leads to a flattening of slopes as the depth increases. This is due to the strong increase of the $in situ$ density with depth.  
    120148 
    121 %By definition, neutral surfaces are tangent to the local $in situ$ density \citep{McDougall1987}, therefore in \autoref{eq:ldfslp_iso}, all the derivatives have to be evaluated at the same local pressure (which in decibars is approximated by the depth in meters). 
     149%By definition, neutral surfaces are tangent to the local $in situ$ density \citep{mcdougall_JPO87}, therefore in \autoref{eq:ldfslp_iso}, all the derivatives have to be evaluated at the same local pressure (which in decibars is approximated by the depth in meters). 
    122150 
    123151%In the $z$-coordinate, the derivative of the  \autoref{eq:ldfslp_iso} numerator is evaluated at the same depth \nocite{as what?} ($T$-level, which is the same as the $u$- and $v$-levels), so  the $in situ$ density can be used for its evaluation.  
     
    135163  thus the $in situ$ density can be used. 
    136164  This is not the case for the vertical derivatives: $\delta_{k+1/2}[\rho]$ is replaced by $-\rho N^2/g$, 
    137   where $N^2$ is the local Brunt-Vais\"{a}l\"{a} frequency evaluated following \citet{McDougall1987} 
     165  where $N^2$ is the local Brunt-Vais\"{a}l\"{a} frequency evaluated following \citet{mcdougall_JPO87} 
    138166  (see \autoref{subsec:TRA_bn2}).  
    139167 
     
    144172\item[$s$- or hybrid $s$-$z$- coordinate: ] 
    145173  in the current release of \NEMO, iso-neutral mixing is only employed for $s$-coordinates if 
    146   the Griffies scheme is used (\np{traldf\_grif}\forcode{ = .true.}; 
    147   see Appdx \autoref{apdx:triad}). 
     174  the Griffies scheme is used (\np{ln\_traldf\_triad}\forcode{ = .true.}; 
     175  see \autoref{apdx:triad}). 
    148176  In other words, iso-neutral mixing will only be accurately represented with a linear equation of state 
    149   (\np{nn\_eos}\forcode{ = 1..2}). 
     177  (\np{ln\_seos}\forcode{ = .true.}). 
    150178  In the case of a "true" equation of state, the evaluation of $i$ and $j$ derivatives in \autoref{eq:ldfslp_iso} 
    151179  will include a pressure dependent part, leading to the wrong evaluation of the neutral slopes. 
     
    154182  Note: The solution for $s$-coordinate passes trough the use of different (and better) expression for 
    155183  the constraint on iso-neutral fluxes. 
    156   Following \citet{Griffies_Bk04}, instead of specifying directly that there is a zero neutral diffusive flux of 
     184  Following \citet{griffies_bk04}, instead of specifying directly that there is a zero neutral diffusive flux of 
    157185  locally referenced potential density, we stay in the $T$-$S$ plane and consider the balance between 
    158186  the neutral direction diffusive fluxes of potential temperature and salinity: 
     
    197225 
    198226This implementation is a rather old one. 
    199 It is similar to the one proposed by Cox [1987], except for the background horizontal diffusion. 
    200 Indeed, the Cox implementation of isopycnal diffusion in GFDL-type models requires 
     227It is similar to the one proposed by \citet{cox_OM87}, except for the background horizontal diffusion. 
     228Indeed, the \citet{cox_OM87} implementation of isopycnal diffusion in GFDL-type models requires 
    201229a minimum background horizontal diffusion for numerical stability reasons. 
    202230To overcome this problem, several techniques have been proposed in which the numerical schemes of 
    203 the ocean model are modified \citep{Weaver_Eby_JPO97, Griffies_al_JPO98}. 
    204 Griffies's scheme is now available in \NEMO if \np{traldf\_grif\_iso} is set true; see Appdx \autoref{apdx:triad}. 
    205 Here, another strategy is presented \citep{Lazar_PhD97}: 
     231the ocean model are modified \citep{weaver.eby_JPO97, griffies.gnanadesikan.ea_JPO98}. 
     232Griffies's scheme is now available in \NEMO if \np{ln\_traldf\_triad}=\forcode{= .true.}; see \autoref{apdx:triad}. 
     233Here, another strategy is presented \citep{lazar_phd97}: 
    206234a local filtering of the iso-neutral slopes (made on 9 grid-points) prevents the development of 
    207235grid point noise generated by the iso-neutral diffusion operator (\autoref{fig:LDF_ZDF1}). 
     
    212240 
    213241Nevertheless, this iso-neutral operator does not ensure that variance cannot increase, 
    214 contrary to the \citet{Griffies_al_JPO98} operator which has that property.  
     242contrary to the \citet{griffies.gnanadesikan.ea_JPO98} operator which has that property.  
    215243 
    216244%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    217245\begin{figure}[!ht] 
    218246  \begin{center} 
    219     \includegraphics[width=0.70\textwidth]{Fig_LDF_ZDF1} 
     247    \includegraphics[width=\textwidth]{Fig_LDF_ZDF1} 
    220248    \caption { 
    221249      \protect\label{fig:LDF_ZDF1} 
     
    235263 
    236264 
    237 % In addition and also for numerical stability reasons \citep{Cox1987, Griffies_Bk04},  
     265% In addition and also for numerical stability reasons \citep{cox_OM87, griffies_bk04},  
    238266% the slopes are bounded by $1/100$ everywhere. This limit is decreasing linearly  
    239267% to zero fom $70$ meters depth and the surface (the fact that the eddies "feel" the  
    240268% surface motivates this flattening of isopycnals near the surface). 
    241269 
    242 For numerical stability reasons \citep{Cox1987, Griffies_Bk04}, the slopes must also be bounded by 
    243 $1/100$ everywhere. 
     270For numerical stability reasons \citep{cox_OM87, griffies_bk04}, the slopes must also be bounded by 
     271the namelist scalar \np{rn\_slpmax} (usually $1/100$) everywhere. 
    244272This constraint is applied in a piecewise linear fashion, increasing from zero at the surface to 
    245273$1/100$ at $70$ metres and thereafter decreasing to zero at the bottom of the ocean 
    246274(the fact that the eddies "feel" the surface motivates this flattening of isopycnals near the surface). 
     275\colorbox{yellow}{The way slopes are tapered has be checked. Not sure that this is still what is actually done.} 
    247276 
    248277%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    249278\begin{figure}[!ht] 
    250279  \begin{center} 
    251     \includegraphics[width=0.70\textwidth]{Fig_eiv_slp} 
     280    \includegraphics[width=\textwidth]{Fig_eiv_slp} 
    252281    \caption{ 
    253282      \protect\label{fig:eiv_slp} 
     
    297326(see \autoref{sec:LBC_coast}). 
    298327 
    299  
    300 % ================================================================ 
    301 % Lateral Mixing Operator 
    302 % ================================================================ 
    303 \section{Lateral mixing operators (\protect\mdl{traldf}, \protect\mdl{traldf}) } 
    304 \label{sec:LDF_op} 
    305  
    306  
    307328    
    308329% ================================================================ 
    309330% Lateral Mixing Coefficients 
    310331% ================================================================ 
    311 \section{Lateral mixing coefficient (\protect\mdl{ldftra}, \protect\mdl{ldfdyn}) } 
     332\section[Lateral mixing coefficient (\forcode{nn_aht_ijk_t}, \forcode{nn_ahm_ijk_t})] 
     333{Lateral mixing coefficient (\protect\np{nn\_aht\_ijk\_t}, \protect\np{nn\_ahm\_ijk\_t})} 
    312334\label{sec:LDF_coef} 
    313335 
    314 Introducing a space variation in the lateral eddy mixing coefficients changes the model core memory requirement, 
    315 adding up to four extra three-dimensional arrays for the geopotential or isopycnal second order operator applied to  
    316 momentum. 
    317 Six CPP keys control the space variation of eddy coefficients: three for momentum and three for tracer. 
    318 The three choices allow: 
    319 a space variation in the three space directions (\key{traldf\_c3d},  \key{dynldf\_c3d}), 
    320 in the horizontal plane (\key{traldf\_c2d},  \key{dynldf\_c2d}), 
    321 or in the vertical only (\key{traldf\_c1d},  \key{dynldf\_c1d}). 
    322 The default option is a constant value over the whole ocean on both momentum and tracers.  
    323     
    324 The number of additional arrays that have to be defined and the gridpoint position at which 
    325 they are defined depend on both the space variation chosen and the type of operator used. 
    326 The resulting eddy viscosity and diffusivity coefficients can be a function of more than one variable. 
    327 Changes in the computer code when switching from one option to another have been minimized by 
    328 introducing the eddy coefficients as statement functions 
    329 (include file \textit{ldftra\_substitute.h90} and \textit{ldfdyn\_substitute.h90}). 
    330 The functions are replaced by their actual meaning during the preprocessing step (CPP). 
    331 The specification of the space variation of the coefficient is made in \mdl{ldftra} and \mdl{ldfdyn}, 
    332 or more precisely in include files \textit{traldf\_cNd.h90} and \textit{dynldf\_cNd.h90}, with N=1, 2 or 3. 
    333 The user can modify these include files as he/she wishes. 
    334 The way the mixing coefficient are set in the reference version can be briefly described as follows: 
    335  
    336 \subsubsection{Constant mixing coefficients (default option)} 
    337 When none of the \key{dynldf\_...} and \key{traldf\_...} keys are defined, 
    338 a constant value is used over the whole ocean for momentum and tracers, 
    339 which is specified through the \np{rn\_ahm0} and \np{rn\_aht0} namelist parameters. 
    340  
    341 \subsubsection{Vertically varying mixing coefficients (\protect\key{traldf\_c1d} and \key{dynldf\_c1d})}  
    342 The 1D option is only available when using the $z$-coordinate with full step. 
    343 Indeed in all the other types of vertical coordinate, 
    344 the depth is a 3D function of (\textbf{i},\textbf{j},\textbf{k}) and therefore, 
    345 introducing depth-dependent mixing coefficients will require 3D arrays. 
    346 In the 1D option, a hyperbolic variation of the lateral mixing coefficient is introduced in which 
    347 the surface value is \np{rn\_aht0} (\np{rn\_ahm0}), the bottom value is 1/4 of the surface value, 
    348 and the transition takes place around z=300~m with a width of 300~m 
    349 (\ie both the depth and the width of the inflection point are set to 300~m). 
    350 This profile is hard coded in file \textit{traldf\_c1d.h90}, but can be easily modified by users. 
    351  
    352 \subsubsection{Horizontally varying mixing coefficients (\protect\key{traldf\_c2d} and \protect\key{dynldf\_c2d})} 
    353 By default the horizontal variation of the eddy coefficient depends on the local mesh size and 
     336The specification of the space variation of the coefficient is made in modules \mdl{ldftra} and \mdl{ldfdyn}.  
     337The way the mixing coefficients are set in the reference version can be described as follows: 
     338 
     339\subsection[Mixing coefficients read from file (\forcode{nn_aht_ijk_t = -20, -30}, \forcode{nn_ahm_ijk_t = -20,-30})] 
     340{ Mixing coefficients read from file (\protect\np{nn\_aht\_ijk\_t}\forcode{ = -20, -30}, \protect\np{nn\_ahm\_ijk\_t}\forcode{ = -20, -30})} 
     341 
     342Mixing coefficients can be read from file if a particular geographical variation is needed. For example, in the ORCA2 global ocean model,  
     343the laplacian viscosity operator uses $A^l$~= 4.10$^4$ m$^2$/s poleward of 20$^{\circ}$ north and south and 
     344decreases linearly to $A^l$~= 2.10$^3$ m$^2$/s at the equator \citep{madec.delecluse.ea_JPO96, delecluse.madec_icol99}.  
     345Similar modified horizontal variations can be found with the Antarctic or Arctic sub-domain options of ORCA2 and ORCA05.  
     346The provided fields can either be 2d (\np{nn\_aht\_ijk\_t}\forcode{ = -20}, \np{nn\_ahm\_ijk\_t}\forcode{ = -20}) or 3d (\np{nn\_aht\_ijk\_t}\forcode{ = -30},  \np{nn\_ahm\_ijk\_t}\forcode{ = -30}). They must be given at U, V points for tracers and T, F points for momentum (see \autoref{tab:LDF_files}). 
     347 
     348%-------------------------------------------------TABLE--------------------------------------------------- 
     349\begin{table}[htb] 
     350  \begin{center} 
     351    \begin{tabular}{|l|l|l|l|} 
     352      \hline 
     353      Namelist parameter                        & Input filename                               & dimensions & variable names                      \\  \hline 
     354      \np{nn\_ahm\_ijk\_t}\forcode{ = -20}       & \forcode{eddy_viscosity_2D.nc }            &     $(i,j)$         & \forcode{ahmt_2d, ahmf_2d}  \\  \hline 
     355      \np{nn\_aht\_ijk\_t}\forcode{ = -20}           & \forcode{eddy_diffusivity_2D.nc }           &     $(i,j)$          & \forcode{ahtu_2d, ahtv_2d}    \\   \hline 
     356      \np{nn\_ahm\_ijk\_t}\forcode{ = -30}       & \forcode{eddy_viscosity_3D.nc }            &     $(i,j,k)$          & \forcode{ahmt_3d, ahmf_3d}  \\  \hline 
     357      \np{nn\_aht\_ijk\_t}\forcode{ = -30}       & \forcode{eddy_diffusivity_3D.nc }           &     $(i,j,k)$         & \forcode{ahtu_3d, ahtv_3d}    \\   \hline 
     358    \end{tabular} 
     359    \caption{ 
     360      \protect\label{tab:LDF_files} 
     361      Description of expected input files if mixing coefficients are read from NetCDF files. 
     362    } 
     363  \end{center} 
     364\end{table} 
     365%-------------------------------------------------------------------------------------------------------------- 
     366 
     367\subsection[Constant mixing coefficients (\forcode{nn_aht_ijk_t = 0}, \forcode{nn_ahm_ijk_t = 0})] 
     368{ Constant mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{ = 0}, \protect\np{nn\_ahm\_ijk\_t}\forcode{ = 0})} 
     369 
     370If constant, mixing coefficients are set thanks to a velocity and a length scales ($U_{scl}$, $L_{scl}$) such that: 
     371 
     372\begin{equation} 
     373  \label{eq:constantah} 
     374  A_o^l = \left\{ 
     375    \begin{aligned} 
     376      & \frac{1}{2} U_{scl} L_{scl}            & \text{for laplacian operator } \\ 
     377      & \frac{1}{12} U_{scl} L_{scl}^3                    & \text{for bilaplacian operator } 
     378    \end{aligned} 
     379  \right. 
     380\end{equation} 
     381 
     382 $U_{scl}$ and $L_{scl}$ are given by the namelist parameters \np{rn\_Ud}, \np{rn\_Uv}, \np{rn\_Ld} and \np{rn\_Lv}. 
     383 
     384\subsection[Vertically varying mixing coefficients (\forcode{nn_aht_ijk_t = 10}, \forcode{nn_ahm_ijk_t = 10})] 
     385{Vertically varying mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{ = 10}, \protect\np{nn\_ahm\_ijk\_t}\forcode{ = 10})} 
     386 
     387In the vertically varying case, a hyperbolic variation of the lateral mixing coefficient is introduced in which 
     388the surface value is given by \autoref{eq:constantah}, the bottom value is 1/4 of the surface value, 
     389and the transition takes place around z=500~m with a width of 200~m. 
     390This profile is hard coded in module \mdl{ldfc1d\_c2d}, but can be easily modified by users. 
     391 
     392\subsection[Mesh size dependent mixing coefficients (\forcode{nn_aht_ijk_t = 20}, \forcode{nn_ahm_ijk_t = 20})] 
     393{Mesh size dependent mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{ = 20}, \protect\np{nn\_ahm\_ijk\_t}\forcode{ = 20})} 
     394 
     395In that case, the horizontal variation of the eddy coefficient depends on the local mesh size and 
    354396the type of operator used: 
    355397\begin{equation} 
     
    357399  A_l = \left\{ 
    358400    \begin{aligned} 
    359       & \frac{\max(e_1,e_2)}{e_{max}} A_o^l           & \text{for laplacian operator } \\ 
    360       & \frac{\max(e_1,e_2)^{3}}{e_{max}^{3}} A_o^l          & \text{for bilaplacian operator } 
     401      & \frac{1}{2} U_{scl}  \max(e_1,e_2)         & \text{for laplacian operator } \\ 
     402      & \frac{1}{12} U_{scl}  \max(e_1,e_2)^{3}             & \text{for bilaplacian operator } 
    361403    \end{aligned} 
    362404  \right. 
    363405\end{equation} 
    364 where $e_{max}$ is the maximum of $e_1$ and $e_2$ taken over the whole masked ocean domain, 
    365 and $A_o^l$ is the \np{rn\_ahm0} (momentum) or \np{rn\_aht0} (tracer) namelist parameter. 
     406where $U_{scl}$ is a user defined velocity scale (\np{rn\_Ud}, \np{rn\_Uv}). 
    366407This variation is intended to reflect the lesser need for subgrid scale eddy mixing where 
    367408the grid size is smaller in the domain. 
    368 It was introduced in the context of the DYNAMO modelling project \citep{Willebrand_al_PO01}. 
    369 Note that such a grid scale dependance of mixing coefficients significantly increase the range of stability of 
    370 model configurations presenting large changes in grid pacing such as global ocean models. 
     409It was introduced in the context of the DYNAMO modelling project \citep{willebrand.barnier.ea_PO01}. 
     410Note that such a grid scale dependance of mixing coefficients significantly increases the range of stability of 
     411model configurations presenting large changes in grid spacing such as global ocean models. 
    371412Indeed, in such a case, a constant mixing coefficient can lead to a blow up of the model due to 
    372413large coefficient compare to the smallest grid size (see \autoref{sec:STP_forward_imp}), 
    373414especially when using a bilaplacian operator. 
    374415 
    375 Other formulations can be introduced by the user for a given configuration. 
    376 For example, in the ORCA2 global ocean model (see Configurations), 
    377 the laplacian viscosity operator uses \np{rn\_ahm0}~= 4.10$^4$ m$^2$/s poleward of 20$^{\circ}$ north and south and 
    378 decreases linearly to \np{rn\_aht0}~= 2.10$^3$ m$^2$/s at the equator \citep{Madec_al_JPO96, Delecluse_Madec_Bk00}. 
    379 This modification can be found in routine \rou{ldf\_dyn\_c2d\_orca} defined in \mdl{ldfdyn\_c2d}. 
    380 Similar modified horizontal variations can be found with the Antarctic or Arctic sub-domain options of 
    381 ORCA2 and ORCA05 (see \&namcfg namelist). 
    382  
    383 \subsubsection{Space varying mixing coefficients (\protect\key{traldf\_c3d} and \key{dynldf\_c3d})} 
    384  
    385 The 3D space variation of the mixing coefficient is simply the combination of the 1D and 2D cases, 
     416\colorbox{yellow}{CASE \np{nn\_aht\_ijk\_t} = 21 to be added} 
     417 
     418\subsection[Mesh size and depth dependent mixing coefficients (\forcode{nn_aht_ijk_t = 30}, \forcode{nn_ahm_ijk_t = 30})] 
     419{Mesh size and depth dependent mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{ = 30}, \protect\np{nn\_ahm\_ijk\_t}\forcode{ = 30})} 
     420 
     421The 3D space variation of the mixing coefficient is simply the combination of the 1D and 2D cases above, 
    386422\ie a hyperbolic tangent variation with depth associated with a grid size dependence of 
    387423the magnitude of the coefficient.  
    388424 
    389 \subsubsection{Space and time varying mixing coefficients} 
    390  
    391 There is no default specification of space and time varying mixing coefficient.  
    392 The only case available is specific to the ORCA2 and ORCA05 global ocean configurations. 
    393 It provides only a tracer mixing coefficient for eddy induced velocity (ORCA2) or both iso-neutral and 
    394 eddy induced velocity (ORCA05) that depends on the local growth rate of baroclinic instability. 
    395 This specification is actually used when an ORCA key and both \key{traldf\_eiv} and \key{traldf\_c2d} are defined. 
     425\subsection[Velocity dependent mixing coefficients (\forcode{nn_aht_ijk_t = 31}, \forcode{nn_ahm_ijk_t = 31})] 
     426{Flow dependent mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{ = 31}, \protect\np{nn\_ahm\_ijk\_t}\forcode{ = 31})} 
     427In that case, the eddy coefficient is proportional to the local velocity magnitude so that the Reynolds number $Re =  \lvert U \rvert  e / A_l$ is constant (and here hardcoded to $12$): 
     428\colorbox{yellow}{JC comment: The Reynolds is effectively set to 12 in the code for both operators but shouldn't it be 2 for Laplacian ?} 
     429 
     430\begin{equation} 
     431  \label{eq:flowah} 
     432  A_l = \left\{ 
     433    \begin{aligned} 
     434      & \frac{1}{12} \lvert U \rvert e          & \text{for laplacian operator } \\ 
     435      & \frac{1}{12} \lvert U \rvert e^3             & \text{for bilaplacian operator }  
     436    \end{aligned} 
     437  \right. 
     438\end{equation} 
     439 
     440\subsection[Deformation rate dependent viscosities (\forcode{nn_ahm_ijk_t = 32})] 
     441{Deformation rate dependent viscosities (\protect\np{nn\_ahm\_ijk\_t}\forcode{ = 32})} 
     442 
     443This option refers to the \citep{smagorinsky_MW63} scheme which is here implemented for momentum only. Smagorinsky chose as a  
     444characteristic time scale $T_{smag}$ the deformation rate and for the lengthscale $L_{smag}$ the maximum wavenumber possible on the horizontal grid, e.g.: 
     445 
     446\begin{equation} 
     447  \label{eq:smag1} 
     448  \begin{split} 
     449    T_{smag}^{-1} & = \sqrt{\left( \partial_x u - \partial_y v\right)^2 + \left( \partial_y u + \partial_x v\right)^2  } \\ 
     450    L_{smag} & = \frac{1}{\pi}\frac{e_1 e_2}{e_1 + e_2} 
     451  \end{split} 
     452\end{equation} 
     453 
     454Introducing a user defined constant $C$ (given in the namelist as \np{rn\_csmc}), one can deduce the mixing coefficients as follows: 
     455 
     456\begin{equation} 
     457  \label{eq:smag2} 
     458  A_{smag} = \left\{ 
     459    \begin{aligned} 
     460      & C^2  T_{smag}^{-1}  L_{smag}^2       & \text{for laplacian operator } \\ 
     461      & \frac{C^2}{8} T_{smag}^{-1} L_{smag}^4        & \text{for bilaplacian operator }  
     462    \end{aligned} 
     463  \right. 
     464\end{equation} 
     465 
     466For stability reasons, upper and lower limits are applied on the resulting coefficient (see \autoref{sec:STP_forward_imp}) so that: 
     467\begin{equation} 
     468  \label{eq:smag3} 
     469    \begin{aligned} 
     470      & C_{min} \frac{1}{2}   \lvert U \rvert  e    < A_{smag} < C_{max} \frac{e^2}{   8\rdt}                 & \text{for laplacian operator } \\ 
     471      & C_{min} \frac{1}{12} \lvert U \rvert  e^3 < A_{smag} < C_{max} \frac{e^4}{64 \rdt}                 & \text{for bilaplacian operator }  
     472    \end{aligned} 
     473\end{equation} 
     474 
     475where $C_{min}$ and $C_{max}$ are adimensional namelist parameters given by \np{rn\_minfac} and \np{rn\_maxfac} respectively. 
     476 
     477\subsection{About space and time varying mixing coefficients} 
    396478 
    397479The following points are relevant when the eddy coefficient varies spatially: 
     
    406488(\autoref{sec:dynldf_properties}). 
    407489 
    408 (3) for isopycnal diffusion on momentum or tracers, an additional purely horizontal background diffusion with 
    409 uniform coefficient can be added by setting a non zero value of \np{rn\_ahmb0} or \np{rn\_ahtb0}, 
    410 a background horizontal eddy viscosity or diffusivity coefficient 
    411 (namelist parameters whose default values are $0$). 
    412 However, the technique used to compute the isopycnal slopes is intended to get rid of such a background diffusion, 
    413 since it introduces spurious diapycnal diffusion (see \autoref{sec:LDF_slp}). 
    414  
    415 (4) when an eddy induced advection term is used (\key{traldf\_eiv}), 
    416 $A^{eiv}$, the eddy induced coefficient has to be defined. 
    417 Its space variations are controlled by the same CPP variable as for the eddy diffusivity coefficient 
    418 (\ie \key{traldf\_cNd}).  
    419  
    420 (5) the eddy coefficient associated with a biharmonic operator must be set to a \emph{negative} value. 
    421  
    422 (6) it is possible to use both the laplacian and biharmonic operators concurrently. 
    423  
    424 (7) it is possible to run without explicit lateral diffusion on momentum 
    425 (\np{ln\_dynldf\_lap}\forcode{ = .?.}\np{ln\_dynldf\_bilap}\forcode{ = .false.}). 
    426 This is recommended when using the UBS advection scheme on momentum (\np{ln\_dynadv\_ubs}\forcode{ = .true.}, 
    427 see \autoref{subsec:DYN_adv_ubs}) and can be useful for testing purposes. 
    428  
    429490% ================================================================ 
    430491% Eddy Induced Mixing 
    431492% ================================================================ 
    432 \section{Eddy induced velocity (\protect\mdl{traadv\_eiv}, \protect\mdl{ldfeiv})} 
     493\section[Eddy induced velocity (\forcode{ln_ldfeiv = .true.})] 
     494{Eddy induced velocity (\protect\np{ln\_ldfeiv}\forcode{ = .true.})} 
     495 
    433496\label{sec:LDF_eiv} 
     497 
     498%--------------------------------------------namtra_eiv--------------------------------------------------- 
     499 
     500\nlst{namtra_eiv} 
     501 
     502%-------------------------------------------------------------------------------------------------------------- 
     503 
    434504 
    435505%%gm  from Triad appendix  : to be incorporated.... 
     
    453523} 
    454524 
    455 When Gent and McWilliams [1990] diffusion is used (\key{traldf\_eiv} defined), 
     525When  \citet{gent.mcwilliams_JPO90} diffusion is used (\np{ln\_ldfeiv}\forcode{ = .true.}), 
    456526an eddy induced tracer advection term is added, 
    457527the formulation of which depends on the slopes of iso-neutral surfaces. 
     
    459529\ie \autoref{eq:ldfslp_geo} is used in $z$-coordinates, 
    460530and the sum \autoref{eq:ldfslp_geo} + \autoref{eq:ldfslp_iso} in $s$-coordinates. 
    461 The eddy induced velocity is given by:  
     531 
     532If isopycnal mixing is used in the standard way, \ie \np{ln\_traldf\_triad}\forcode{ = .false.}, the eddy induced velocity is given by:  
    462533\begin{equation} 
    463534  \label{eq:ldfeiv} 
     
    468539  \end{split} 
    469540\end{equation} 
    470 where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{rn\_aeiv}, 
    471 a \textit{nam\_traldf} namelist parameter. 
    472 The three components of the eddy induced velocity are computed and 
    473 add to the eulerian velocity in \mdl{traadv\_eiv}. 
     541where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{nn\_aei\_ijk\_t} \ngn{namtra\_eiv} namelist parameter.  
     542The three components of the eddy induced velocity are computed in \rou{ldf\_eiv\_trp} and 
     543added to the eulerian velocity in \rou{tra\_adv} where tracer advection is performed. 
    474544This has been preferred to a separate computation of the advective trends associated with the eiv velocity, 
    475545since it allows us to take advantage of all the advection schemes offered for the tracers 
    476546(see \autoref{sec:TRA_adv}) and not just the $2^{nd}$ order advection scheme as in 
    477 previous releases of OPA \citep{Madec1998}. 
     547previous releases of OPA \citep{madec.delecluse.ea_NPM98}. 
    478548This is particularly useful for passive tracers where \emph{positivity} of the advection scheme is of 
    479549paramount importance.  
     
    481551At the surface, lateral and bottom boundaries, the eddy induced velocity, 
    482552and thus the advective eddy fluxes of heat and salt, are set to zero.  
     553The value of the eddy induced mixing coefficient and its space variation is controlled in a similar way as for lateral mixing coefficient described in the preceding subsection (\np{nn\_aei\_ijk\_t}, \np{rn\_Ue}, \np{rn\_Le} namelist parameters).  
     554\colorbox{yellow}{CASE \np{nn\_aei\_ijk\_t} = 21 to be added} 
     555 
     556In case of setting \np{ln\_traldf\_triad}\forcode{ = .true.}, a skew form of the eddy induced advective fluxes is used, which is described in \autoref{apdx:triad}. 
     557 
     558% ================================================================ 
     559% Mixed layer eddies 
     560% ================================================================ 
     561\section[Mixed layer eddies (\forcode{ln_mle = .true.})] 
     562{Mixed layer eddies (\protect\np{ln\_mle}\forcode{ = .true.})} 
     563 
     564\label{sec:LDF_mle} 
     565 
     566%--------------------------------------------namtra_eiv--------------------------------------------------- 
     567 
     568\nlst{namtra_mle} 
     569 
     570%-------------------------------------------------------------------------------------------------------------- 
     571 
     572If  \np{ln\_mle}\forcode{ = .true.} in \ngn{namtra\_mle} namelist, a parameterization of the mixing due to unresolved mixed layer instabilities is activated (\citet{foxkemper.ferrari_JPO08}). Additional transport is computed in \rou{ldf\_mle\_trp} and added to the eulerian transport in \rou{tra\_adv} as done for eddy induced advection. 
     573 
     574\colorbox{yellow}{TBC} 
    483575 
    484576\biblio 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_OBS.tex

    r10442 r11422  
    88\label{chap:OBS} 
    99 
    10 Authors: D. Lea, M. Martin, K. Mogensen, A. Vidard, A. Weaver, A. Ryan, ...   % do we keep that ? 
    11  
    1210\minitoc 
    1311 
     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.6} & {\em M. Martin, A. Ryan} & {\em Add averaging operator, standalone obs oper} \\ 
     19    {\em 3.4} & {\em D. J. Lea, M. Martin, ...} & {\em Initial version}  \\ 
     20    {\em --\texttt{"}--} & {\em ... K. Mogensen, A. Vidard, A. Weaver} & {\em ---\texttt{"}---}  \\ 
     21\end{tabular} 
     22\end{figure} 
     23 
    1424\newpage 
    1525 
    16 The observation and model comparison code (OBS) reads in observation files 
    17 (profile temperature and salinity, sea surface temperature, sea level anomaly, sea ice concentration, and velocity) and calculates an interpolated model equivalent value at the observation location and nearest model timestep. 
     26The observation and model comparison code, the observation operator (OBS), reads in observation files 
     27(profile temperature and salinity, sea surface temperature, sea level anomaly, sea ice concentration, and velocity) and calculates an interpolated model equivalent value at the observation location and nearest model time step. 
    1828The resulting data are saved in a ``feedback'' file (or files). 
    1929The code was originally developed for use with the NEMOVAR data assimilation code, 
    2030but can be used for validation or verification of the model or with any other data assimilation system. 
    2131 
    22 The OBS code is called from \mdl{nemogcm} for model initialisation and to calculate the model equivalent values for observations on the 0th timestep. 
    23 The code is then called again after each timestep from \mdl{step}. 
    24 The code is only activated if the namelist logical \np{ln\_diaobs} is set to true. 
     32The OBS code is called from \mdl{nemogcm} for model initialisation and to calculate the model equivalent values for observations on the 0th time step. 
     33The code is then called again after each time step from \mdl{step}. 
     34The code is only activated if the \ngn{namobs} namelist logical \np{ln\_diaobs} is set to true. 
    2535 
    2636For all data types a 2D horizontal interpolator or averager is needed to 
     
    2838For {\em in situ} profiles, a 1D vertical interpolator is needed in addition to 
    2939provide model fields at the observation depths. 
    30 This now works in a generalised vertical coordinate system.  
     40This now works in a generalised vertical coordinate system. 
    3141 
    3242Some profile observation types (\eg tropical moored buoys) are made available as daily averaged quantities. 
     
    3646the observation operator code can calculate equivalent night-time average model SST fields by 
    3747setting the namelist value \np{ln\_sstnight} to true. 
    38 Otherwise the model value from the nearest timestep to the observation time is used. 
    39  
    40 The code is controlled by the namelist \textit{namobs}. 
     48Otherwise (by default) the model value from the nearest time step to the observation time is used. 
     49 
     50The code is controlled by the namelist \ngn{namobs}. 
    4151See the following sections for more details on setting up the namelist. 
    4252 
    43 \autoref{sec:OBS_example} introduces a test example of the observation operator code including 
     53In \autoref{sec:OBS_example} a test example of the observation operator code is introduced, including 
    4454where to obtain data and how to setup the namelist. 
    45 \autoref{sec:OBS_details} introduces some more technical details of the different observation types used and 
    46 also shows a more complete namelist. 
    47 \autoref{sec:OBS_theory} introduces some of the theoretical aspects of the observation operator including 
     55In \autoref{sec:OBS_details} some more technical details of the different observation types used are introduced, and we 
     56also show a more complete namelist. 
     57In \autoref{sec:OBS_theory} some of the theoretical aspects of the observation operator are described including 
    4858interpolation methods and running on multiple processors. 
    49 \autoref{sec:OBS_ooo} describes the offline observation operator code. 
    50 \autoref{sec:OBS_obsutils} introduces some utilities to help working with the files produced by the OBS code. 
     59In \autoref{sec:OBS_sao} the standalone observation operator code is described. 
     60In \autoref{sec:OBS_obsutils} we describe some utilities to help work with the files produced by the OBS code. 
    5161 
    5262% ================================================================ 
     
    5666\label{sec:OBS_example} 
    5767 
    58 This section describes an example of running the observation operator code using 
    59 profile data which can be freely downloaded. 
    60 It shows how to adapt an existing run and build of NEMO to run the observation operator. 
     68In this section an example of running the observation operator code is described using 
     69profile observation data which can be freely downloaded. 
     70It shows how to adapt an existing run and build of \NEMO to run the observation operator. Note also the observation operator and the assimilation increments code are run in the \np{ORCA2\_ICE\_OBS} SETTE test. 
    6171 
    6272\begin{enumerate} 
     
    6575\item Download some EN4 data from \href{http://www.metoffice.gov.uk/hadobs}{www.metoffice.gov.uk/hadobs}. 
    6676  Choose observations which are valid for the period of your test run because 
    67   the observation operator compares the model and observations for a matching date and time.  
    68  
    69 \item Compile the OBSTOOLS code using:  
     77  the observation operator compares the model and observations for a matching date and time. 
     78 
     79\item Compile the OBSTOOLS code in the \np{tools} directory using: 
    7080\begin{cmds} 
    71 ./maketools -n OBSTOOLS -m [ARCH]. 
     81./maketools -n OBSTOOLS -m [ARCH] 
    7282\end{cmds} 
    7383 
    74 \item Convert the EN4 data into feedback format:  
     84replacing \np{[ARCH]} with the build architecture file for your machine. Note the tools are checked out from a separate repository under \np{utils/tools}. 
     85 
     86\item Convert the EN4 data into feedback format: 
    7587\begin{cmds} 
    7688enact2fb.exe profiles_01.nc EN.4.1.1.f.profiles.g10.YYYYMM.nc 
    7789\end{cmds} 
    7890 
    79 \item Include the following in the NEMO namelist to run the observation operator on this data: 
     91\item Include the following in the \NEMO namelist to run the observation operator on this data: 
    8092\end{enumerate} 
    8193 
     
    8799This can be expensive, particularly for large numbers of observations, 
    88100setting \np{ln\_grid\_search\_lookup} allows the use of a lookup table which 
    89 is saved into an ``xypos`` file (or files). 
     101is saved into an \np{cn\_gridsearch} file (or files). 
    90102This will need to be generated the first time if it does not exist in the run directory. 
    91103However, once produced it will significantly speed up future grid searches. 
    92104Setting \np{ln\_grid\_global} means that the code distributes the observations evenly between processors. 
    93105Alternatively each processor will work with observations located within the model subdomain 
    94 (see section~\autoref{subsec:OBS_parallel}). 
     106(see \autoref{subsec:OBS_parallel}). 
    95107 
    96108A number of utilities are now provided to plot the feedback files, convert and recombine the files. 
    97 These are explained in more detail in section~\autoref{sec:OBS_obsutils}. 
    98 Utilites to convert other input data formats into the feedback format are also described in 
    99 section~\autoref{sec:OBS_obsutils}. 
     109These are explained in more detail in \autoref{sec:OBS_obsutils}. 
     110Utilities to convert other input data formats into the feedback format are also described in 
     111\autoref{sec:OBS_obsutils}. 
    100112 
    101113\section{Technical details (feedback type observation file headers)} 
     
    110122%------------------------------------------------------------------------------------------------------------- 
    111123 
    112 The observation operator code uses the "feedback" observation file format for all data types. 
     124The observation operator code uses the feedback observation file format for all data types. 
    113125All the observation files must be in NetCDF format. 
    114126Some example headers (produced using \mbox{\textit{ncdump~-h}}) for profile data, sea level anomaly and 
    115127sea surface temperature are in the following subsections. 
    116128 
    117 \subsection{Profile feedback} 
     129\subsection{Profile feedback file} 
    118130 
    119131\begin{clines} 
     
    271283\end{clines} 
    272284 
    273 \subsection{Sea level anomaly feedback} 
     285\subsection{Sea level anomaly feedback file} 
    274286 
    275287\begin{clines} 
     
    395407\end{clines} 
    396408 
    397 The mean dynamic topography (MDT) must be provided in a separate file defined on 
     409To use Sea Level Anomaly (SLA) data the mean dynamic topography (MDT) must be provided in a separate file defined on 
    398410the model grid called \ifile{slaReferenceLevel}. 
    399411The MDT is required in order to produce the model equivalent sea level anomaly from the model sea surface height. 
     
    417429\end{clines} 
    418430 
    419 \subsection{Sea surface temperature feedback} 
     431\subsection{Sea surface temperature feedback file} 
    420432 
    421433\begin{clines} 
     
    546558In those cases the model counterpart should be calculated by averaging the model grid points over 
    547559the same size as the footprint. 
    548 NEMO therefore has the capability to specify either an interpolation or an averaging 
    549 (for surface observation types only).  
     560\NEMO therefore has the capability to specify either an interpolation or an averaging 
     561(for surface observation types only). 
    550562 
    551563The main namelist option associated with the interpolation/averaging is \np{nn\_2dint}. 
     
    559571\item \np{nn\_2dint}\forcode{ = 4}: Polynomial interpolation 
    560572\item \np{nn\_2dint}\forcode{ = 5}: Radial footprint averaging with diameter specified in the namelist as 
    561   \np{rn\_???\_avglamscl} in degrees or metres (set using \np{ln\_???\_fp\_indegs}) 
     573  \np{rn\_[var]\_avglamscl} in degrees or metres (set using \np{ln\_[var]\_fp\_indegs}) 
    562574\item \np{nn\_2dint}\forcode{ = 6}: Rectangular footprint averaging with E/W and N/S size specified in 
    563   the namelist as \np{rn\_???\_avglamscl} and \np{rn\_???\_avgphiscl} in degrees or metres 
    564   (set using \np{ln\_???\_fp\_indegs}) 
     575  the namelist as \np{rn\_[var]\_avglamscl} and \np{rn\_[var]\_avgphiscl} in degrees or metres 
     576  (set using \np{ln\_[var]\_fp\_indegs}) 
    565577\end{itemize} 
    566 The ??? in the last two options indicate these options should be specified for each observation type for 
     578Replace \np{[var]} in the last two options with the observation type (sla, sst, sss or sic) for 
    567579which the averaging is to be performed (see namelist example above). 
    568580The \np{nn\_2dint} default option can be overridden for surface observation types using 
    569 namelist values \np{nn\_2dint\_???} where ??? is one of sla,sst,sss,sic. 
     581namelist values \np{nn\_2dint\_[var]} where \np{[var]} is the observation type. 
    570582 
    571583Below is some more detail on the various options for interpolation and averaging available in NEMO. 
     
    573585\subsubsection{Horizontal interpolation} 
    574586 
    575 Consider an observation point ${\rm P}$ with with longitude and latitude $({\lambda_{}}_{\rm P}, \phi_{\rm P})$ and 
    576 the four nearest neighbouring model grid points ${\rm A}$, ${\rm B}$, ${\rm C}$ and ${\rm D}$ with 
    577 longitude and latitude ($\lambda_{\rm A}$, $\phi_{\rm A}$),($\lambda_{\rm B}$, $\phi_{\rm B}$) etc. 
    578 All horizontal interpolation methods implemented in NEMO estimate the value of a model variable $x$ at point $P$ as 
    579 a weighted linear combination of the values of the model variables at the grid points ${\rm A}$, ${\rm B}$ etc.: 
     587Consider an observation point ${\mathrm P}$ with longitude and latitude (${\lambda_{}}_{\mathrm P}$, $\phi_{\mathrm P}$) and 
     588the four nearest neighbouring model grid points ${\mathrm A}$, ${\mathrm B}$, ${\mathrm C}$ and ${\mathrm D}$ with 
     589longitude and latitude ($\lambda_{\mathrm A}$, $\phi_{\mathrm A}$),($\lambda_{\mathrm B}$, $\phi_{\mathrm B}$) etc. 
     590All horizontal interpolation methods implemented in \NEMO estimate the value of a model variable $x$ at point $P$ as 
     591a weighted linear combination of the values of the model variables at the grid points ${\mathrm A}$, ${\mathrm B}$ etc.: 
     592 
    580593\begin{align*} 
    581   {x_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & 
    582                                                    \frac{1}{w} \left( {w_{}}_{\rm A} {x_{}}_{\rm A} + 
    583                                                    {w_{}}_{\rm B} {x_{}}_{\rm B} + 
    584                                                    {w_{}}_{\rm C} {x_{}}_{\rm C} + 
    585                                                    {w_{}}_{\rm D} {x_{}}_{\rm D} \right) 
     594  {x_{}}_{\mathrm P} = 
     595\frac{1}{w} \left( {w_{}}_{\mathrm A} {x_{}}_{\mathrm A} + 
     596{w_{}}_{\mathrm B} {x_{}}_{\mathrm B} + 
     597{w_{}}_{\mathrm C} {x_{}}_{\mathrm C} + 
     598{w_{}}_{\mathrm D} {x_{}}_{\mathrm D} \right) 
    586599\end{align*} 
    587 where ${w_{}}_{\rm A}$, ${w_{}}_{\rm B}$ etc. are the respective weights for the model field at 
    588 points ${\rm A}$, ${\rm B}$ etc., and $w = {w_{}}_{\rm A} + {w_{}}_{\rm B} + {w_{}}_{\rm C} + {w_{}}_{\rm D}$. 
     600 
     601where ${w_{}}_{\mathrm A}$, ${w_{}}_{\mathrm B}$ etc. are the respective weights for the model field at 
     602points ${\mathrm A}$, ${\mathrm B}$ etc., and $w = {w_{}}_{\mathrm A} + {w_{}}_{\mathrm B} + {w_{}}_{\mathrm C} + {w_{}}_{\mathrm D}$. 
    589603 
    590604Four different possibilities are available for computing the weights. 
     
    592606\begin{enumerate} 
    593607 
    594 \item[1.] {\bf Great-Circle distance-weighted interpolation.} 
     608\item[1.] {\bfseries Great-Circle distance-weighted interpolation.} 
    595609  The weights are computed as a function of the great-circle distance $s(P, \cdot)$ between $P$ and 
    596610  the model grid points $A$, $B$ etc. 
    597   For example, the weight given to the field ${x_{}}_{\rm A}$ is specified as the product of the distances 
    598   from ${\rm P}$ to the other points: 
    599   \begin{align*} 
    600     {w_{}}_{\rm A} = s({\rm P}, {\rm B}) \, s({\rm P}, {\rm C}) \, s({\rm P}, {\rm D}) 
    601   \end{align*} 
    602   where  
    603   \begin{align*} 
    604     s\left ({\rm P}, {\rm M} \right )  
    605      & \hspace{-2mm} = \hspace{-2mm} &  
    606       \cos^{-1} \! \left\{  
    607                \sin {\phi_{}}_{\rm P} \sin {\phi_{}}_{\rm M} 
    608              + \cos {\phi_{}}_{\rm P} \cos {\phi_{}}_{\rm M}  
    609                \cos ({\lambda_{}}_{\rm M} - {\lambda_{}}_{\rm P})  
     611  For example, the weight given to the field ${x_{}}_{\mathrm A}$ is specified as the product of the distances 
     612  from ${\mathrm P}$ to the other points: 
     613 
     614  \begin{alignat*}{2} 
     615    {w_{}}_{\mathrm A} = s({\mathrm P}, {\mathrm B}) \, s({\mathrm P}, {\mathrm C}) \, s({\mathrm P}, {\mathrm D}) 
     616  \end{alignat*} 
     617 
     618  where 
     619 
     620  \begin{alignat*}{2} 
     621    s\left({\mathrm P}, {\mathrm M} \right) & = & \hspace{0.25em} \cos^{-1} \! \left\{ 
     622               \sin {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm M} 
     623             + \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm M} 
     624               \cos ({\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P}) 
    610625                   \right\} 
    611    \end{align*} 
     626   \end{alignat*} 
     627 
    612628   and $M$ corresponds to $B$, $C$ or $D$. 
    613629   A more stable form of the great-circle distance formula for small distances ($x$ near 1) 
    614    involves the arcsine function (\eg see p.~101 of \citet{Daley_Barker_Bk01}: 
    615    \begin{align*} 
    616      s\left( {\rm P}, {\rm M} \right) & \hspace{-2mm} = \hspace{-2mm} & \sin^{-1} \! \left\{ \sqrt{ 1 - x^2 } \right\} 
    617    \end{align*} 
     630   involves the arcsine function (\eg see p.~101 of \citet{daley.barker_bk01}: 
     631 
     632   \begin{alignat*}{2} 
     633     s\left( {\mathrm P}, {\mathrm M} \right) = \sin^{-1} \! \left\{ \sqrt{ 1 - x^2 } \right\} 
     634   \end{alignat*} 
     635 
    618636   where 
    619    \begin{align*} 
    620      x & \hspace{-2mm} = \hspace{-2mm} & 
    621                                          {a_{}}_{\rm M} {a_{}}_{\rm P} + {b_{}}_{\rm M} {b_{}}_{\rm P} + {c_{}}_{\rm M} {c_{}}_{\rm P} 
    622    \end{align*} 
    623    and  
    624    \begin{align*} 
    625       {a_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\rm M}, \\ 
    626       {a_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\rm P}, \\ 
    627       {b_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm M} \cos {\phi_{}}_{\rm M}, \\ 
    628       {b_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm P} \cos {\phi_{}}_{\rm P}, \\ 
    629       {c_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm M} \sin {\phi_{}}_{\rm M}, \\ 
    630       {c_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm P} \sin {\phi_{}}_{\rm P}. 
    631   \end{align*} 
    632  
    633 \item[2.] {\bf Great-Circle distance-weighted interpolation with small angle approximation.} 
     637 
     638   \begin{alignat*}{2} 
     639     x = {a_{}}_{\mathrm M} {a_{}}_{\mathrm P} + {b_{}}_{\mathrm M} {b_{}}_{\mathrm P} + {c_{}}_{\mathrm M} {c_{}}_{\mathrm P} 
     640   \end{alignat*} 
     641 
     642   and 
     643 
     644   \begin{alignat*}{3} 
     645   & {a_{}}_{\mathrm M} & = && \quad \sin {\phi_{}}_{\mathrm M}, \\ 
     646   & {a_{}}_{\mathrm P} & = && \quad \sin {\phi_{}}_{\mathrm P}, \\ 
     647   & {b_{}}_{\mathrm M} & = && \quad \cos {\phi_{}}_{\mathrm M} \cos {\phi_{}}_{\mathrm M}, \\ 
     648   & {b_{}}_{\mathrm P} & = && \quad \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm P}, \\ 
     649   & {c_{}}_{\mathrm M} & = && \quad \cos {\phi_{}}_{\mathrm M} \sin {\phi_{}}_{\mathrm M}, \\ 
     650   & {c_{}}_{\mathrm P} & = && \quad \cos {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm P}. 
     651   \end{alignat*} 
     652 
     653\item[2.] {\bfseries Great-Circle distance-weighted interpolation with small angle approximation.} 
    634654  Similar to the previous interpolation but with the distance $s$ computed as 
    635   \begin{align*} 
    636     s\left( {\rm P}, {\rm M} \right) 
    637     & \hspace{-2mm} = \hspace{-2mm} & 
    638                                       \sqrt{ \left( {\phi_{}}_{\rm M} - {\phi_{}}_{\rm P} \right)^{2} 
    639                                       + \left( {\lambda_{}}_{\rm M} - {\lambda_{}}_{\rm P} \right)^{2} 
    640                                       \cos^{2} {\phi_{}}_{\rm M} } 
    641   \end{align*} 
     655  \begin{alignat*}{2} 
     656    s\left( {\mathrm P}, {\mathrm M} \right) 
     657    & = & \sqrt{ \left( {\phi_{}}_{\mathrm M} - {\phi_{}}_{\mathrm P} \right)^{2} 
     658                                      + \left( {\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P} \right)^{2} 
     659                                      \cos^{2} {\phi_{}}_{\mathrm M} } 
     660  \end{alignat*} 
    642661  where $M$ corresponds to $A$, $B$, $C$ or $D$. 
    643662 
    644 \item[3.] {\bf Bilinear interpolation for a regular spaced grid.} 
     663\item[3.] {\bfseries Bilinear interpolation for a regular spaced grid.} 
    645664  The interpolation is split into two 1D interpolations in the longitude and latitude directions, respectively. 
    646665 
    647 \item[4.] {\bf Bilinear remapping interpolation for a general grid.} 
     666\item[4.] {\bfseries Bilinear remapping interpolation for a general grid.} 
    648667  An iterative scheme that involves first mapping a quadrilateral cell into 
    649668  a cell with coordinates (0,0), (1,0), (0,1) and (1,1). 
    650   This method is based on the SCRIP interpolation package \citep{Jones_1998}. 
    651    
     669  This method is based on the \href{https://github.com/SCRIP-Project/SCRIP}{SCRIP interpolation package}. 
     670 
    652671\end{enumerate} 
    653672 
     
    658677\item The standard grid-searching code is used to find the nearest model grid point to the observation location 
    659678  (see next subsection). 
    660 \item The maximum number of grid points is calculated in the local grid domain for which 
    661   the averaging is likely need to cover. 
    662 \item The lats/longs of the grid points surrounding the nearest model grid box are extracted using 
    663   existing mpi routines. 
     679\item The maximum number of grid points required for that observation in each local grid domain is calculated. Some of these points may later turn out to have zero weight depending on the shape of the footprint. 
     680\item The longitudes and latitudes of the grid points surrounding the nearest model grid box are extracted using 
     681  existing MPI routines. 
    664682\item The weights for each grid point associated with each observation are calculated, 
    665683  either for radial or rectangular footprints. 
     
    673691 
    674692Examples of the weights calculated for an observation with rectangular and radial footprints are shown in 
    675 Figs.~\autoref{fig:obsavgrec} and~\autoref{fig:obsavgrad}. 
     693\autoref{fig:obsavgrec} and~\autoref{fig:obsavgrad}. 
    676694 
    677695%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    678696\begin{figure} 
    679697  \begin{center} 
    680     \includegraphics[width=0.90\textwidth]{Fig_OBS_avg_rec} 
     698    \includegraphics[width=\textwidth]{Fig_OBS_avg_rec} 
    681699    \caption{ 
    682700      \protect\label{fig:obsavgrec} 
     
    691709\begin{figure} 
    692710  \begin{center} 
    693     \includegraphics[width=0.90\textwidth]{Fig_OBS_avg_rad} 
     711    \includegraphics[width=\textwidth]{Fig_OBS_avg_rad} 
    694712    \caption{ 
    695713      \protect\label{fig:obsavgrad} 
    696714      Weights associated with each model grid box (blue lines and numbers) 
    697715      for an observation at -170.5\deg{E}, 56.0\deg{N} with a radial footprint with diameter 1\deg. 
    698     }  
     716    } 
    699717  \end{center} 
    700718\end{figure} 
     
    704722\subsection{Grid search} 
    705723 
    706 For many grids used by the NEMO model, such as the ORCA family, the horizontal grid coordinates $i$ and $j$ are not simple functions of latitude and longitude. 
     724For many grids used by the \NEMO model, such as the ORCA family, the horizontal grid coordinates $i$ and $j$ are not simple functions of latitude and longitude. 
    707725Therefore, it is not always straightforward to determine the grid points surrounding any given observational position. 
    708 Before the interpolation can be performed, a search algorithm is then required to determine the corner points of  
     726Before the interpolation can be performed, a search algorithm is then required to determine the corner points of 
    709727the quadrilateral cell in which the observation is located. 
    710 This is the most difficult and time consuming part of the 2D interpolation procedure.  
     728This is the most difficult and time consuming part of the 2D interpolation procedure. 
    711729A robust test for determining if an observation falls within a given quadrilateral cell is as follows. 
    712 Let ${\rm P}({\lambda_{}}_{\rm P} ,{\phi_{}}_{\rm P} )$ denote the observation point, 
    713 and let ${\rm A}({\lambda_{}}_{\rm A} ,{\phi_{}}_{\rm A} )$, ${\rm B}({\lambda_{}}_{\rm B} ,{\phi_{}}_{\rm B} )$, 
    714 ${\rm C}({\lambda_{}}_{\rm C} ,{\phi_{}}_{\rm C} )$ and ${\rm D}({\lambda_{}}_{\rm D} ,{\phi_{}}_{\rm D} )$ 
    715 denote the bottom left, bottom right, top left and top right corner points of the cell, respectively.  
    716 To determine if P is inside the cell, we verify that the cross-products  
     730Let ${\mathrm P}({\lambda_{}}_{\mathrm P} ,{\phi_{}}_{\mathrm P} )$ denote the observation point, 
     731and let ${\mathrm A}({\lambda_{}}_{\mathrm A} ,{\phi_{}}_{\mathrm A} )$, ${\mathrm B}({\lambda_{}}_{\mathrm B} ,{\phi_{}}_{\mathrm B} )$, 
     732${\mathrm C}({\lambda_{}}_{\mathrm C} ,{\phi_{}}_{\mathrm C} )$ and ${\mathrm D}({\lambda_{}}_{\mathrm D} ,{\phi_{}}_{\mathrm D} )$ 
     733denote the bottom left, bottom right, top left and top right corner points of the cell, respectively. 
     734To determine if P is inside the cell, we verify that the cross-products 
    717735\begin{align*} 
    718736  \begin{array}{lllll} 
    719     {{\bf r}_{}}_{\rm PA} \times {{\bf r}_{}}_{\rm PC} 
    720     & = & [({\lambda_{}}_{\rm A}\; -\; {\lambda_{}}_{\rm P} ) 
    721           ({\phi_{}}_{\rm C}   \; -\; {\phi_{}}_{\rm P} ) 
    722           - ({\lambda_{}}_{\rm C}\; -\; {\lambda_{}}_{\rm P} ) 
    723           ({\phi_{}}_{\rm A}   \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\ 
    724     {{\bf r}_{}}_{\rm PB} \times {{\bf r}_{}}_{\rm PA} 
    725     & = & [({\lambda_{}}_{\rm B}\; -\; {\lambda_{}}_{\rm P} ) 
    726           ({\phi_{}}_{\rm A}   \; -\; {\phi_{}}_{\rm P} ) 
    727           - ({\lambda_{}}_{\rm A}\; -\; {\lambda_{}}_{\rm P} ) 
    728           ({\phi_{}}_{\rm B}   \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\ 
    729     {{\bf r}_{}}_{\rm PC} \times {{\bf r}_{}}_{\rm PD} 
    730     & = & [({\lambda_{}}_{\rm C}\; -\; {\lambda_{}}_{\rm P} ) 
    731           ({\phi_{}}_{\rm D}   \; -\; {\phi_{}}_{\rm P} ) 
    732           - ({\lambda_{}}_{\rm D}\; -\; {\lambda_{}}_{\rm P} ) 
    733           ({\phi_{}}_{\rm C}   \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\ 
    734     {{\bf r}_{}}_{\rm PD} \times {{\bf r}_{}}_{\rm PB} 
    735     & = & [({\lambda_{}}_{\rm D}\; -\; {\lambda_{}}_{\rm P} ) 
    736           ({\phi_{}}_{\rm B}   \; -\; {\phi_{}}_{\rm P} ) 
    737           - ({\lambda_{}}_{\rm B}\; -\; {\lambda_{}}_{\rm P} ) 
    738           ({\phi_{}}_{\rm D}  \;  - \; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\ 
     737    {{\mathbf r}_{}}_{\mathrm PA} \times {{\mathbf r}_{}}_{\mathrm PC} 
     738    & = & [({\lambda_{}}_{\mathrm A}\; -\; {\lambda_{}}_{\mathrm P} ) 
     739          ({\phi_{}}_{\mathrm C}   \; -\; {\phi_{}}_{\mathrm P} ) 
     740          - ({\lambda_{}}_{\mathrm C}\; -\; {\lambda_{}}_{\mathrm P} ) 
     741          ({\phi_{}}_{\mathrm A}   \; -\; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\ 
     742    {{\mathbf r}_{}}_{\mathrm PB} \times {{\mathbf r}_{}}_{\mathrm PA} 
     743    & = & [({\lambda_{}}_{\mathrm B}\; -\; {\lambda_{}}_{\mathrm P} ) 
     744          ({\phi_{}}_{\mathrm A}   \; -\; {\phi_{}}_{\mathrm P} ) 
     745          - ({\lambda_{}}_{\mathrm A}\; -\; {\lambda_{}}_{\mathrm P} ) 
     746          ({\phi_{}}_{\mathrm B}   \; -\; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\ 
     747    {{\mathbf r}_{}}_{\mathrm PC} \times {{\mathbf r}_{}}_{\mathrm PD} 
     748    & = & [({\lambda_{}}_{\mathrm C}\; -\; {\lambda_{}}_{\mathrm P} ) 
     749          ({\phi_{}}_{\mathrm D}   \; -\; {\phi_{}}_{\mathrm P} ) 
     750          - ({\lambda_{}}_{\mathrm D}\; -\; {\lambda_{}}_{\mathrm P} ) 
     751          ({\phi_{}}_{\mathrm C}   \; -\; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\ 
     752    {{\mathbf r}_{}}_{\mathrm PD} \times {{\mathbf r}_{}}_{\mathrm PB} 
     753    & = & [({\lambda_{}}_{\mathrm D}\; -\; {\lambda_{}}_{\mathrm P} ) 
     754          ({\phi_{}}_{\mathrm B}   \; -\; {\phi_{}}_{\mathrm P} ) 
     755          - ({\lambda_{}}_{\mathrm B}\; -\; {\lambda_{}}_{\mathrm P} ) 
     756          ({\phi_{}}_{\mathrm D}  \;  - \; {\phi_{}}_{\mathrm P} )] \; \widehat{\mathbf k} \\ 
    739757  \end{array} 
    740758  % \label{eq:cross} 
    741759\end{align*} 
    742 point in the opposite direction to the unit normal $\widehat{\bf k}$ 
    743 (\ie that the coefficients of $\widehat{\bf k}$ are negative), 
    744 where ${{\bf r}_{}}_{\rm PA}$, ${{\bf r}_{}}_{\rm PB}$, etc. correspond to 
     760point in the opposite direction to the unit normal $\widehat{\mathbf k}$ 
     761(\ie that the coefficients of $\widehat{\mathbf k}$ are negative), 
     762where ${{\mathbf r}_{}}_{\mathrm PA}$, ${{\mathbf r}_{}}_{\mathrm PB}$, etc. correspond to 
    745763the vectors between points P and A, P and B, etc.. 
    746 The method used is similar to the method used in the SCRIP interpolation package \citep{Jones_1998}. 
     764The method used is similar to the method used in the \href{https://github.com/SCRIP-Project/SCRIP}{SCRIP interpolation package}. 
    747765 
    748766In order to speed up the grid search, there is the possibility to construct a lookup table for a user specified resolution. 
     
    750768be searched for on a regular grid. 
    751769For each observation position, the closest point on the regular grid of this position is computed and 
    752 the $i$ and $j$ ranges of this point searched to determine the precise four points surrounding the observation.  
     770the $i$ and $j$ ranges of this point searched to determine the precise four points surrounding the observation. 
    753771 
    754772\subsection{Parallel aspects of horizontal interpolation} 
     
    757775For horizontal interpolation, there is the basic problem that 
    758776the observations are unevenly distributed on the globe. 
    759 In numerical models, it is common to divide the model grid into subgrids (or domains) where 
     777In \NEMO the model grid is divided into subgrids (or domains) where 
    760778each subgrid is executed on a single processing element with explicit message passing for 
    761779exchange of information along the domain boundaries when running on a massively parallel processor (MPP) system. 
    762 This approach is used by \NEMO. 
    763  
    764 For observations there is no natural distribution since the observations are not equally distributed on the globe.  
     780 
     781For observations there is no natural distribution since the observations are not equally distributed on the globe. 
    765782Two options have been made available: 
    7667831) geographical distribution; 
     
    772789\begin{figure} 
    773790  \begin{center} 
    774     \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_ASM_obsdist_local} 
     791    \includegraphics[width=\textwidth]{Fig_ASM_obsdist_local} 
    775792    \caption{ 
    776793      \protect\label{fig:obslocal} 
     
    784801the domain of the grid-point parallelization. 
    785802\autoref{fig:obslocal} shows an example of the distribution of the {\em in situ} data on processors with 
    786 a different colour for each observation on a given processor for a 4 $\times$ 2 decomposition with ORCA2.  
     803a different colour for each observation on a given processor for a 4 $\times$ 2 decomposition with ORCA2. 
    787804The grid-point domain decomposition is clearly visible on the plot. 
    788805 
    789806The advantage of this approach is that all information needed for horizontal interpolation is available without 
    790807any MPP communication. 
    791 Of course, this is under the assumption that we are only using a $2 \times 2$ grid-point stencil for 
     808This is under the assumption that we are dealing with point observations and only using a $2 \times 2$ grid-point stencil for 
    792809the interpolation (\eg bilinear interpolation). 
    793810For higher order interpolation schemes this is no longer valid. 
     
    801818\begin{figure} 
    802819  \begin{center} 
    803     \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_ASM_obsdist_global} 
     820    \includegraphics[width=\textwidth]{Fig_ASM_obsdist_global} 
    804821    \caption{ 
    805822      \protect\label{fig:obsglobal} 
     
    827844At the bottom boundary, this is done using the land-ocean mask. 
    828845 
     846For profile observation types we do both vertical and horizontal interpolation. \NEMO has a generalised vertical coordinate system this means the vertical level depths can vary with location. Therefore, it is necessary first to perform vertical interpolation of the model value to the observation depths for each of the four surrounding grid points. After this the model values, at these points, at the observation depth, are horizontally interpolated to the observation location. 
     847 
    829848\newpage 
    830849 
    831850% ================================================================ 
    832 % Offline observation operator documentation 
     851% Standalone observation operator documentation 
    833852% ================================================================ 
    834853 
    835854%\usepackage{framed} 
    836855 
    837 \section{Offline observation operator} 
    838 \label{sec:OBS_ooo} 
     856\section{Standalone observation operator} 
     857\label{sec:OBS_sao} 
    839858 
    840859\subsection{Concept} 
    841860 
    842 The obs oper maps model variables to observation space. 
    843 It is possible to apply this mapping without running the model. 
    844 The software which performs this functionality is known as the \textbf{offline obs oper}. 
    845 The obs oper is divided into three stages. 
    846 An initialisation phase, an interpolation phase and an output phase. 
    847 The implementation of which is outlined in the previous sections. 
    848 During the interpolation phase the offline obs oper populates the model arrays by 
    849 reading saved model fields from disk. 
    850  
    851 There are two ways of exploiting this offline capacity. 
     861The observation operator maps model variables to observation space. This is normally done while the model is running, i.e. online, it is possible to apply this mapping offline without running the model with the \textbf{standalone observation operator} (SAO). The process is divided into an initialisation phase, an interpolation phase and an output phase. 
     862During the interpolation phase the SAO populates the model arrays by 
     863reading saved model fields from disk. The interpolation and the output phases use the same OBS code described in the preceding sections. 
     864 
     865There are two ways of exploiting the standalone capacity. 
    852866The first is to mimic the behaviour of the online system by supplying model fields at 
    853867regular intervals between the start and the end of the run. 
    854868This approach results in a single model counterpart per observation. 
    855 This kind of usage produces feedback files the same file format as the online obs oper. 
    856 The second is to take advantage of the offline setting in which 
    857 multiple model counterparts can be calculated per observation. 
     869This kind of usage produces feedback files the same file format as the online observation operator. 
     870The second is to take advantage of the ability to run offline by calculating 
     871multiple model counterparts for each observation. 
    858872In this case it is possible to consider all forecasts verifying at the same time. 
    859 By forecast, I mean any method which produces an estimate of physical reality which is not an observed value. 
    860 In the case of class 4 files this means forecasts, analyses, persisted analyses and 
    861 climatological values verifying at the same time. 
    862 Although the class 4 file format doesn't account for multiple ensemble members or 
    863 multiple experiments per observation, it is possible to include these components in the same or multiple files. 
     873By forecast, we mean any method which produces an estimate of physical reality which is not an observed value. 
    864874 
    865875%-------------------------------------------------------------------------------------------------------- 
    866 % offline_oper.exe  
     876% sao.exe 
    867877%-------------------------------------------------------------------------------------------------------- 
    868878 
    869 \subsection{Using the offline observation operator} 
     879\subsection{Using the standalone observation operator} 
    870880 
    871881\subsubsection{Building} 
    872882 
    873 In addition to \emph{OPA\_SRC} the offline obs oper requires the inclusion of the \emph{OOO\_SRC} directory. 
    874 \emph{OOO\_SRC} contains a replacement \mdl{nemo} and \mdl{nemogcm} which 
     883In addition to \emph{OPA\_SRC} the SAO requires the inclusion of the \emph{SAO\_SRC} directory. 
     884\emph{SAO\_SRC} contains a replacement \mdl{nemo} and \mdl{nemogcm} which 
    875885overwrites the resultant \textbf{nemo.exe}. 
    876 This is the approach taken by \emph{SAS\_SRC} and \emph{OFF\_SRC}. 
     886Note this a similar approach to that taken by the standalone surface scheme \emph{SAS\_SRC} and the offline TOP model \emph{OFF\_SRC}. 
    877887 
    878888%-------------------------------------------------------------------------------------------------------- 
    879 % Running  
     889% Running 
    880890%-------------------------------------------------------------------------------------------------------- 
    881891\subsubsection{Running} 
    882892 
    883 The simplest way to use the executable is to edit and append the \textbf{ooo.nml} namelist to 
    884 a full NEMO namelist and then to run the executable as if it were nemo.exe.  
    885  
    886 \subsubsection{Quick script} 
    887  
    888 A useful Python utility to control the namelist options can be found in \textbf{OBSTOOLS/OOO}. 
    889 The functions which locate model fields and observation files can be manually specified. 
    890 The package can be installed by appropriate use of the included setup.py script. 
    891  
    892 Documentation can be auto-generated by Sphinx by running \emph{make html} in the \textbf{doc} directory. 
     893The simplest way to use the executable is to edit and append the \textbf{sao.nml} namelist to 
     894a full \NEMO namelist and then to run the executable as if it were nemo.exe. 
    893895 
    894896%-------------------------------------------------------------------------------------------------------- 
    895897% Configuration section 
    896898%-------------------------------------------------------------------------------------------------------- 
    897 \subsection{Configuring the offline observation operator} 
    898 The observation files and settings understood by \textbf{namobs} have been outlined in the online obs oper section. 
    899 In addition there are two further namelists wich control the operation of the offline obs oper. 
    900 \textbf{namooo} which controls the input model fields and \textbf{namcl4} which 
    901 controls the production of class 4 files.  
     899\subsection{Configuring the standalone observation operator} 
     900The observation files and settings understood by \ngn{namobs} have been outlined in the online observation operator section. 
     901In addition is a further namelist \ngn{namsao} which used to set the input model fields for the SAO 
    902902 
    903903\subsubsection{Single field} 
    904904 
    905 In offline mode model arrays are populated at appropriate time steps via input files. 
    906 At present, \textbf{tsn} and \textbf{sshn} are populated by the default read routines.  
     905In the SAO the model arrays are populated at appropriate time steps via input files. 
     906At present, \textbf{tsn} and \textbf{sshn} are populated by the default read routines. 
    907907These routines will be expanded upon in future versions to allow the specification of any model variable. 
    908908As such, input files must be global versions of the model domain with 
    909909\textbf{votemper}, \textbf{vosaline} and optionally \textbf{sshn} present. 
    910910 
    911 For each field read there must be an entry in the \textbf{namooo} namelist specifying 
     911For each field read there must be an entry in the \ngn{namsao} namelist specifying 
    912912the name of the file to read and the index along the \emph{time\_counter}. 
    913913For example, to read the second time counter from a single file the namelist would be. 
     
    915915\begin{forlines} 
    916916!---------------------------------------------------------------------- 
    917 !       namooo Offline obs_oper namelist 
     917!       namsao Standalone obs_oper namelist 
    918918!---------------------------------------------------------------------- 
    919 !   ooo_files    specifies the files containing the model counterpart 
    920 !   nn_ooo_idx   specifies the time_counter index within the model file 
    921 &namooo 
    922    ooo_files = "foo.nc" 
    923    nn_ooo_idx = 2 
     919!   sao_files    specifies the files containing the model counterpart 
     920!   nn_sao_idx   specifies the time_counter index within the model file 
     921&namsao 
     922   sao_files = "foo.nc" 
     923   nn_sao_idx = 2 
    924924/ 
    925925\end{forlines} 
     
    927927\subsubsection{Multiple fields per run} 
    928928 
    929 Model field iteration is controlled via \textbf{nn\_ooo\_freq} which 
     929Model field iteration is controlled via \textbf{nn\_sao\_freq} which 
    930930specifies the number of model steps at which the next field gets read. 
    931931For example, if 12 hourly fields are to be interpolated in a setup where 288 steps equals 24 hours. 
     
    933933\begin{forlines} 
    934934!---------------------------------------------------------------------- 
    935 !       namooo Offline obs_oper namelist 
     935!       namsao Standalone obs_oper namelist 
    936936!---------------------------------------------------------------------- 
    937 !   ooo_files    specifies the files containing the model counterpart 
    938 !   nn_ooo_idx   specifies the time_counter index within the model file 
    939 !   nn_ooo_freq  specifies number of time steps between read operations 
    940 &namooo 
    941    ooo_files = "foo.nc" "foo.nc" 
    942    nn_ooo_idx = 1 2 
    943    nn_ooo_freq = 144 
     937!   sao_files    specifies the files containing the model counterpart 
     938!   nn_sao_idx   specifies the time_counter index within the model file 
     939!   nn_sao_freq  specifies number of time steps between read operations 
     940&namsao 
     941   sao_files = "foo.nc" "foo.nc" 
     942   nn_sao_idx = 1 2 
     943   nn_sao_freq = 144 
    944944/ 
    945945\end{forlines} 
     
    952952%\end{framed} 
    953953 
    954 It is easy to see how a collection of fields taken fron a number of files at different indices can be combined at 
     954A collection of fields taken from a number of files at different indices can be combined at 
    955955a particular frequency in time to generate a pseudo model evolution. 
    956 As long as all that is needed is a single model counterpart at a regular interval then 
    957 namooo is all that needs to be edited. 
    958 However, a far more interesting approach can be taken in which multiple forecasts, analyses, persisted analyses and 
    959 climatologies are considered against the same set of observations. 
    960 For this a slightly more complicated approach is needed. 
    961 It is referred to as \emph{Class 4} since it is the fourth metric defined by the GODAE intercomparison project. 
    962  
    963 %-------------------------------------------------------------------------------------------------------- 
    964 % Class 4 file section 
    965 %-------------------------------------------------------------------------------------------------------- 
    966 \subsubsection{Multiple model counterparts per observation a.k.a Class 4} 
    967  
    968 A generalisation of feedback files to allow multiple model components per observation. 
    969 For a single observation, as well as previous forecasts verifying at the same time 
    970 there are also analyses, persisted analyses and climatologies.  
    971  
    972  
    973 The above namelist performs two basic functions. 
    974 It organises the fields given in \textbf{namooo} into groups so that observations can be matched up multiple times. 
    975 It also controls the metadata and the output variable of the class 4 file when a write routine is called. 
    976  
    977 %\begin{framed} 
    978 \textbf{Note: ln\_cl4} must be set to \forcode{.true.} in \textbf{namobs} to use class 4 outputs. 
    979 %\end{framed} 
    980  
    981 \subsubsection{Class 4 naming convention} 
    982  
    983 The standard class 4 file naming convention is as follows. 
    984  
    985 \noindent 
    986 \linebreak 
    987 \textbf{\$\{prefix\}\_\$\{yyyymmdd\}\_\$\{sys\}\_\$\{cfg\}\_\$\{vn\}\_\$\{kind\}\_\$\{nproc\}}.nc 
    988  
    989 \noindent 
    990 \linebreak 
    991 Much of the namelist is devoted to specifying this convention. 
    992 The following namelist settings control the elements of the output file names. 
    993 Each should be specified as a single string of character data. 
    994  
    995 \begin{description} 
    996 \item[cl4\_prefix] 
    997   Prefix for class 4 files \eg class4 
    998 \item[cl4\_date] 
    999   YYYYMMDD validity date 
    1000 \item[cl4\_sys] 
    1001   The name of the class 4 model system \eg FOAM 
    1002 \item[cl4\_cfg] 
    1003   The name of the class 4 model configuration \eg orca025 
    1004 \item[cl4\_vn] 
    1005   The name of the class 4 model version \eg 12.0 
    1006 \end{description} 
    1007  
    1008 \noindent 
    1009 The kind is specified by the observation type internally to the obs oper. 
    1010 The processor number is specified internally in NEMO.  
    1011  
    1012 \subsubsection{Class 4 file global attributes} 
    1013  
    1014 Global attributes necessary to fulfill the class 4 file definition. 
    1015 These are also useful pieces of information when collaborating with external partners. 
    1016  
    1017 \begin{description} 
    1018 \item[cl4\_contact] 
    1019   Contact email for class 4 files. 
    1020 \item[cl4\_inst] 
    1021   The name of the producers institution. 
    1022 \item[cl4\_cfg] 
    1023   The name of the class 4 model configuration \eg orca025 
    1024 \item[cl4\_vn] 
    1025   The name of the class 4 model version \eg 12.0 
    1026 \end{description} 
    1027  
    1028 \noindent 
    1029 The obs\_type, creation date and validity time are specified internally to the obs oper. 
    1030  
    1031 \subsubsection{Class 4 model counterpart configuration} 
    1032  
    1033 As seen previously it is possible to perform a single sweep of the obs oper and 
    1034 specify a collection of model fields equally spaced along that sweep. 
    1035 In the class 4 case the single sweep is replaced with multiple sweeps and 
    1036 a certain ammount of book keeping is needed to ensure each model counterpart makes its way to 
    1037 the correct piece of memory in the output files. 
    1038  
    1039 \noindent 
    1040 \linebreak 
    1041 In terms of book keeping, the offline obs oper needs to know how many full sweeps need to be performed. 
    1042 This is specified via the \textbf{cl4\_match\_len} variable and 
    1043 is the total number of model counterparts per observation. 
    1044 For example, a 3 forecasts plus 3 persistence fields plus an analysis field would be 7 counterparts per observation. 
    1045  
    1046 \begin{forlines} 
    1047    cl4_match_len = 7 
    1048 \end{forlines} 
    1049  
    1050 Then to correctly allocate a class 4 file the forecast axis must be defined. 
    1051 This is controlled via \textbf{cl4\_fcst\_len}, which in out above example would be 3. 
    1052  
    1053 \begin{forlines} 
    1054    cl4_fcst_len = 3 
    1055 \end{forlines} 
    1056  
    1057 Then for each model field it is necessary to designate what class 4 variable and index along 
    1058 the forecast dimension the model counterpart should be stored in the output file. 
    1059 As well as a value for that lead time in hours, this will be useful when interpreting the data afterwards.  
    1060  
    1061 \begin{forlines} 
    1062    cl4_vars = "forecast" "forecast" "forecast" "persistence" "persistence" 
    1063               "persistence" "best_estimate" 
    1064    cl4_fcst_idx = 1 2 3 1 2 3 1 
    1065    cl4_leadtime = 12 36 60  
    1066 \end{forlines} 
    1067  
    1068 In terms of files and indices of fields inside each file the class 4 approach makes use of 
    1069 the \textbf{namooo} namelist. 
    1070 If our fields are in separate files with a single field per file our example inputs will be specified. 
    1071  
    1072 \begin{forlines} 
    1073    ooo_files = "F.1.nc" "F.2.nc" "F.3.nc" "P.1.nc" "P.2.nc" "P.3.nc" "A.1.nc" 
    1074    nn_ooo_idx = 1 1 1 1 1 1 1 
    1075 \end{forlines} 
    1076  
    1077 When we combine all of the naming conventions, global attributes and i/o instructions the class 4 namelist becomes. 
    1078  
    1079 \begin{forlines} 
    1080 !---------------------------------------------------------------------- 
    1081 !       namooo Offline obs_oper namelist 
    1082 !---------------------------------------------------------------------- 
    1083 !   ooo_files    specifies the files containing the model counterpart 
    1084 !   nn_ooo_idx   specifies the time_counter index within the model file 
    1085 !   nn_ooo_freq  specifies number of time steps between read operations 
    1086 &namooo 
    1087    ooo_files = "F.1.nc" "F.2.nc" "F.3.nc" "P.1.nc" "P.2.nc" "P.3.nc" "A.1.nc" 
    1088    nn_ooo_idx = 1 1 1 1 1 1 1 
    1089 / 
    1090 !---------------------------------------------------------------------- 
    1091 !       namcl4 Offline obs_oper class 4 namelist 
    1092 !---------------------------------------------------------------------- 
    1093 ! 
    1094 !  Naming convention 
    1095 !  ----------------- 
    1096 !  cl4_prefix    specifies the output file prefix 
    1097 !  cl4_date      specifies the output file validity date 
    1098 !  cl4_sys       specifies the model counterpart system 
    1099 !  cl4_cfg       specifies the model counterpart configuration 
    1100 !  cl4_vn        specifies the model counterpart version 
    1101 !  cl4_inst      specifies the model counterpart institute 
    1102 !  cl4_contact   specifies the file producers contact details 
    1103 ! 
    1104 !  I/O specification 
    1105 !  ----------------- 
    1106 !  cl4_vars      specifies the names of the output file netcdf variable 
    1107 !  cl4_fcst_idx  specifies output file forecast index 
    1108 !  cl4_fcst_len  specifies forecast axis length 
    1109 !  cl4_match_len specifies number of unique matches per observation 
    1110 !  cl4_leadtime  specifies the forecast axis lead time  
    1111 ! 
    1112 &namcl4 
    1113    cl4_match_len = 7 
    1114    cl4_fcst_len = 3 
    1115    cl4_fcst_idx = 1 2 3 1 2 3 1 
    1116    cl4_vars = "forecast" "forecast" "forecast" "persistence" "persistence" 
    1117               "persistence" "best_estimate" 
    1118    cl4_leadtime = 12 36 60 
    1119    cl4_prefix = "class4" 
    1120    cl4_date = "20130101" 
    1121    cl4_vn = "12.0" 
    1122    cl4_sys = "FOAM" 
    1123    cl4_cfg = "AMM7" 
    1124    cl4_contact = "example@example.com" 
    1125    cl4_inst = "UK Met Office" 
    1126 / 
    1127 \end{forlines} 
    1128  
    1129 \subsubsection{Climatology interpolation} 
    1130  
    1131 The climatological counterpart is generated at the start of the run by 
    1132 restarting the model from climatology through appropriate use of \textbf{namtsd}. 
    1133 To override the offline observation operator read routine and to take advantage of the restart settings, 
    1134 specify the first entry in \textbf{cl4\_vars} as "climatology". 
    1135 This will then pipe the restart from climatology into the output class 4 file. 
    1136 As in every other class 4 matchup the input file, input index and output index must be specified. 
    1137 These can be replaced with dummy data since they are not used but 
    1138 they must be present to cycle through the matchups correctly.  
    1139  
    1140 \subsection{Advanced usage} 
    1141  
    1142 In certain cases it may be desirable to include both multiple model fields per observation window with 
    1143 multiple match ups per observation. 
    1144 This can be achieved by specifying \textbf{nn\_ooo\_freq} as well as the class 4 settings. 
    1145 Care must be taken in generating the ooo\_files list such that the files are arranged into 
    1146 consecutive blocks of single match ups. 
    1147 For example, 2 forecast fields of 12 hourly data would result in 4 separate read operations but 
    1148 only 2 write operations, 1 per forecast. 
    1149  
    1150 \begin{forlines} 
    1151    ooo_files = "F1.nc" "F1.nc" "F2.nc" "F2.nc" 
    1152 ... 
    1153    cl4_fcst_idx = 1 2 
    1154 \end{forlines} 
    1155  
    1156 The above notation reveals the internal split between match up iterators and file iterators. 
    1157 This technique has not been used before so experimentation is needed before results can be trusted. 
     956If all that is needed is a single model counterpart at a regular interval then 
     957the standard SAO is all that is required. 
     958However, just to note, it is possible to extend this approach by comparing multiple forecasts, analyses, persisted analyses and 
     959climatologies with the same set of observations. 
     960This approach is referred to as \emph{Class 4} since it is the fourth metric defined by the GODAE intercomparison project. This requires multiple runs of the SAO and running an additional utility (not currently in the \NEMO repository) to combine the feedback files into one class 4 file. 
    1158961 
    1159962\newpage 
     
    1162965\label{sec:OBS_obsutils} 
    1163966 
    1164 Some tools for viewing and processing of observation and feedback files are provided in 
    1165 the NEMO repository for convenience. 
    1166 These include OBSTOOLS which are a collection of \fortran programs which are helpful to deal with feedback files. 
     967For convenience some tools for viewing and processing of observation and feedback files are provided in 
     968the \NEMO repository. 
     969These tools include OBSTOOLS which are a collection of \fortran programs which are helpful to deal with feedback files. 
    1167970They do such tasks as observation file conversion, printing of file contents, 
    1168971some basic statistical analysis of feedback files. 
    1169 The other tool is an IDL program called dataplot which uses a graphical interface to 
     972The other main tool is an IDL program called dataplot which uses a graphical interface to 
    1170973visualise observations and feedback files. 
    1171974OBSTOOLS and dataplot are described in more detail below. 
     
    1173976\subsection{Obstools} 
    1174977 
    1175 A series of \fortran utilities is provided with NEMO called OBSTOOLS. 
    1176 This are helpful in handling observation files and the feedback file output from the NEMO observation operator. 
    1177 The utilities are as follows 
    1178  
    1179 \subsubsection{c4comb} 
    1180  
    1181 The program c4comb combines multiple class 4 files produced by individual processors in 
    1182 an MPI run of NEMO offline obs\_oper into a single class 4 file. 
    1183 The program is called in the following way: 
    1184  
    1185  
    1186 \footnotesize 
    1187 \begin{cmds} 
    1188 c4comb.exe outputfile inputfile1 inputfile2 ... 
    1189 \end{cmds} 
     978A series of \fortran utilities is provided with \NEMO called OBSTOOLS. 
     979This are helpful in handling observation files and the feedback file output from the observation operator. A brief description of some of the utilities follows 
    1190980 
    1191981\subsubsection{corio2fb} 
    1192982 
    1193983The program corio2fb converts profile observation files from the Coriolis format to the standard feedback format. 
    1194 The program is called in the following way: 
    1195  
    1196 \footnotesize 
     984It is called in the following way: 
     985 
    1197986\begin{cmds} 
    1198987corio2fb.exe outputfile inputfile1 inputfile2 ... 
     
    1202991 
    1203992The program enact2fb converts profile observation files from the ENACT format to the standard feedback format. 
    1204 The program is called in the following way: 
    1205  
    1206 \footnotesize 
     993It is called in the following way: 
     994 
    1207995\begin{cmds} 
    1208996enact2fb.exe outputfile inputfile1 inputfile2 ... 
     
    12121000 
    12131001The program fbcomb combines multiple feedback files produced by individual processors in 
    1214 an MPI run of NEMO into a single feedback file. 
    1215 The program is called in the following way: 
    1216  
    1217 \footnotesize 
     1002an MPI run of \NEMO into a single feedback file. 
     1003It is called in the following way: 
     1004 
    12181005\begin{cmds} 
    12191006fbcomb.exe outputfile inputfile1 inputfile2 ... 
     
    12231010 
    12241011The program fbmatchup will match observations from two feedback files. 
    1225 The program is called in the following way: 
    1226  
    1227 \footnotesize 
     1012It is called in the following way: 
     1013 
    12281014\begin{cmds} 
    12291015fbmatchup.exe outputfile inputfile1 varname1 inputfile2 varname2 ... 
     
    12341020The program fbprint will print the contents of a feedback file or files to standard output. 
    12351021Selected information can be output using optional arguments. 
    1236 The program is called in the following way: 
    1237  
    1238 \footnotesize 
     1022It is called in the following way: 
     1023 
    12391024\begin{cmds} 
    12401025fbprint.exe [options] inputfile 
     
    12461031     -B            Select observations based on QC flags 
    12471032     -u            unsorted 
    1248      -s ID         select station ID   
     1033     -s ID         select station ID 
    12491034     -t TYPE       select observation type 
    1250      -v NUM1-NUM2  select variable range to print by number  
     1035     -v NUM1-NUM2  select variable range to print by number 
    12511036                      (default all) 
    1252      -a NUM1-NUM2  select additional variable range to print by number  
     1037     -a NUM1-NUM2  select additional variable range to print by number 
    12531038                      (default all) 
    1254      -e NUM1-NUM2  select extra variable range to print by number  
     1039     -e NUM1-NUM2  select extra variable range to print by number 
    12551040                      (default all) 
    12561041     -d            output date range 
     
    12621047 
    12631048The program fbsel will select or subsample observations. 
    1264 The program is called in the following way: 
    1265  
    1266 \footnotesize 
     1049It is called in the following way: 
     1050 
    12671051\begin{cmds} 
    12681052fbsel.exe <input filename> <output filename> 
     
    12721056 
    12731057The program fbstat will output summary statistics in different global areas into a number of files. 
    1274 The program is called in the following way: 
    1275  
    1276 \footnotesize 
     1058It is called in the following way: 
     1059 
    12771060\begin{cmds} 
    12781061fbstat.exe [-nmlev] <filenames> 
     
    12831066The program fbthin will thin the data to 1 degree resolution. 
    12841067The code could easily be modified to thin to a different resolution. 
    1285 The program is called in the following way: 
    1286  
    1287 \footnotesize 
     1068It is called in the following way: 
     1069 
    12881070\begin{cmds} 
    12891071fbthin.exe inputfile outputfile 
     
    12931075 
    12941076The program sla2fb will convert an AVISO SLA format file to feedback format. 
    1295 The program is called in the following way: 
    1296  
    1297 \footnotesize 
     1077It is called in the following way: 
     1078 
    12981079\begin{cmds} 
    12991080sla2fb.exe [-s type] outputfile inputfile1 inputfile2 ... 
     
    13061087 
    13071088The program vel2fb will convert TAO/PIRATA/RAMA currents files to feedback format. 
    1308 The program is called in the following way: 
    1309  
    1310 \footnotesize 
     1089It is called in the following way: 
     1090 
    13111091\begin{cmds} 
    13121092vel2fb.exe outputfile inputfile1 inputfile2 ... 
     
    13201100 
    13211101An IDL program called dataplot is included which uses a graphical interface to 
    1322 visualise observations and feedback files. 
     1102visualise observations and feedback files. Note a similar package has recently developed in python (also called dataplot) which does some of the same things that the IDL dataplot does. Please contact the authors of the this chapter if you are interested in this. 
     1103 
    13231104It is possible to zoom in, plot individual profiles and calculate some basic statistics. 
    13241105To plot some data run IDL and then: 
    1325 \footnotesize 
     1106 
    13261107\begin{minted}{idl} 
    13271108IDL> dataplot, "filename" 
     
    13311112for example multiple feedback files from different processors or from different days, 
    13321113the easiest method is to use the spawn command to generate a list of files which can then be passed to dataplot. 
    1333 \footnotesize 
     1114 
    13341115\begin{minted}{idl} 
    13351116IDL> spawn, 'ls profb*.nc', files 
     
    13501131The plotting colour range can be changed by clicking on the colour bar. 
    13511132The title of the plot gives some basic information about the date range and depth range shown, 
    1352 the extreme values, and the mean and rms values. 
     1133the extreme values, and the mean and RMS values. 
    13531134It is possible to zoom in using a drag-box. 
    13541135You may also zoom in or out using the mouse wheel. 
     
    13621143observation minus background value. 
    13631144The next group of radio buttons selects the map projection. 
    1364 This can either be regular latitude longitude grid, or north or south polar stereographic. 
     1145This can either be regular longitude latitude grid, or north or south polar stereographic. 
    13651146The next group of radio buttons will plot bad observations, switch to salinity and 
    13661147plot density for profile observations. 
     
    13701151\begin{figure} 
    13711152  \begin{center} 
    1372     % \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_OBS_dataplot_main} 
    1373     \includegraphics[width=9cm,angle=-90.]{Fig_OBS_dataplot_main} 
     1153    % \includegraphics[width=\textwidth]{Fig_OBS_dataplot_main} 
     1154    \includegraphics[width=\textwidth]{Fig_OBS_dataplot_main} 
    13741155    \caption{ 
    13751156      \protect\label{fig:obsdataplotmain} 
     
    13861167\begin{figure} 
    13871168  \begin{center} 
    1388     % \includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_OBS_dataplot_prof} 
    1389     \includegraphics[width=7cm,angle=-90.]{Fig_OBS_dataplot_prof} 
     1169    % \includegraphics[width=\textwidth]{Fig_OBS_dataplot_prof} 
     1170    \includegraphics[width=\textwidth]{Fig_OBS_dataplot_prof} 
    13901171    \caption{ 
    13911172      \protect\label{fig:obsdataplotprofile} 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_SBC.tex

    r10614 r11422  
    22 
    33\begin{document} 
    4 % ================================================================ 
    5 % Chapter —— Surface Boundary Condition (SBC, ISF, ICB)  
    6 % ================================================================ 
    7 \chapter{Surface Boundary Condition (SBC, ISF, ICB) } 
     4 
     5% ================================================================ 
     6% Chapter —— Surface Boundary Condition (SBC, SAS, ISF, ICB)  
     7% ================================================================ 
     8\chapter{Surface Boundary Condition (SBC, SAS, ISF, ICB)} 
    89\label{chap:SBC} 
    910\minitoc 
     
    1617%-------------------------------------------------------------------------------------------------------------- 
    1718 
    18 The ocean needs six fields as surface boundary condition: 
     19The ocean needs seven fields as surface boundary condition: 
     20 
    1921\begin{itemize} 
    2022\item 
     
    2628\item 
    2729  the surface salt flux associated with freezing/melting of seawater $\left( {\textit{sfx}} \right)$ 
     30\item 
     31  the atmospheric pressure at the ocean surface $\left( p_a \right)$ 
    2832\end{itemize} 
    29 plus an optional field: 
     33 
     34Four different ways are available to provide the seven fields to the ocean. They are controlled by 
     35namelist \ngn{namsbc} variables: 
     36 
    3037\begin{itemize} 
    31    \item the atmospheric pressure at the ocean surface $\left( p_a \right)$ 
     38\item 
     39  a bulk formulation (\np{ln\_blk}\forcode{ = .true.} with four possible bulk algorithms), 
     40\item 
     41  a flux formulation (\np{ln\_flx}\forcode{ = .true.}), 
     42\item 
     43  a coupled or mixed forced/coupled formulation (exchanges with a atmospheric model via the OASIS coupler), 
     44(\np{ln\_cpl} or \np{ln\_mixcpl}\forcode{ = .true.}), 
     45\item 
     46  a user defined formulation (\np{ln\_usr}\forcode{ = .true.}). 
    3247\end{itemize} 
    3348 
    34 Four different ways to provide the first six fields to the ocean are available which are controlled by 
    35 namelist \ngn{namsbc} variables: 
    36 an analytical formulation (\np{ln\_ana}\forcode{ = .true.}), 
    37 a flux formulation (\np{ln\_flx}\forcode{ = .true.}), 
    38 a bulk formulae formulation (CORE (\np{ln\_blk\_core}\forcode{ = .true.}), 
    39 CLIO (\np{ln\_blk\_clio}\forcode{ = .true.}) bulk formulae) and 
    40 a coupled or mixed forced/coupled formulation (exchanges with a atmospheric model via the OASIS coupler) 
    41 (\np{ln\_cpl} or \np{ln\_mixcpl}\forcode{ = .true.}).  
    42 When used (\ie \np{ln\_apr\_dyn}\forcode{ = .true.}), 
    43 the atmospheric pressure forces both ocean and ice dynamics. 
    4449 
    4550The frequency at which the forcing fields have to be updated is given by the \np{nn\_fsbc} namelist parameter. 
    46 When the fields are supplied from data files (flux and bulk formulations), 
    47 the input fields need not be supplied on the model grid. 
    48 Instead a file of coordinates and weights can be supplied which maps the data from the supplied grid to 
     51 
     52When the fields are supplied from data files (bulk, flux and mixed formulations), 
     53the input fields do not need to be supplied on the model grid. 
     54Instead, a file of coordinates and weights can be supplied to map the data from the input fields grid to 
    4955the model points (so called "Interpolation on the Fly", see \autoref{subsec:SBC_iof}). 
    50 If the Interpolation on the Fly option is used, input data belonging to land points (in the native grid), 
    51 can be masked to avoid spurious results in proximity of the coasts as 
     56If the "Interpolation on the Fly" option is used, input data belonging to land points (in the native grid) 
     57should be masked or filled to avoid spurious results in proximity of the coasts, as 
    5258large sea-land gradients characterize most of the atmospheric variables. 
    5359 
    5460In addition, the resulting fields can be further modified using several namelist options. 
    55 These options control  
     61These options control: 
     62 
    5663\begin{itemize} 
    5764\item 
    5865  the rotation of vector components supplied relative to an east-north coordinate system onto 
    59   the local grid directions in the model; 
    60 \item 
    61   the addition of a surface restoring term to observed SST and/or SSS (\np{ln\_ssr}\forcode{ = .true.}); 
    62 \item 
    63   the modification of fluxes below ice-covered areas (using observed ice-cover or a sea-ice model) 
    64   (\np{nn\_ice}\forcode{ = 0..3}); 
    65 \item 
    66   the addition of river runoffs as surface freshwater fluxes or lateral inflow (\np{ln\_rnf}\forcode{ = .true.}); 
    67 \item 
    68   the addition of isf melting as lateral inflow (parameterisation) or 
    69   as fluxes applied at the land-ice ocean interface (\np{ln\_isf}) ;  
     66  the local grid directions in the model, 
     67\item 
     68  the use of a land/sea mask for input fields (\np{nn\_lsm}\forcode{ = .true.}), 
     69\item 
     70  the addition of a surface restoring term to observed SST and/or SSS (\np{ln\_ssr}\forcode{ = .true.}), 
     71\item 
     72  the modification of fluxes below ice-covered areas (using climatological ice-cover or a sea-ice model) 
     73  (\np{nn\_ice}\forcode{ = 0..3}), 
     74\item 
     75  the addition of river runoffs as surface freshwater fluxes or lateral inflow (\np{ln\_rnf}\forcode{ = .true.}), 
     76\item 
     77  the addition of ice-shelf melting as lateral inflow (parameterisation) or 
     78  as fluxes applied at the land-ice ocean interface (\np{ln\_isf}\forcode{ = .true.}), 
    7079\item 
    7180  the addition of a freshwater flux adjustment in order to avoid a mean sea-level drift 
    72   (\np{nn\_fwb}\forcode{ = 0..2}); 
    73 \item 
    74   the transformation of the solar radiation (if provided as daily mean) into a diurnal cycle 
    75   (\np{ln\_dm2dc}\forcode{ = .true.}); 
    76 \item 
    77   a neutral drag coefficient can be read from an external wave model (\np{ln\_cdgw}\forcode{ = .true.}); 
    78 \item 
    79   the Stokes drift rom an external wave model can be accounted (\np{ln\_sdw}\forcode{ = .true.});  
    80 \item 
    81   the Stokes-Coriolis term can be included (\np{ln\_stcor}\forcode{ = .true.}); 
    82 \item 
    83   the surface stress felt by the ocean can be modified by surface waves (\np{ln\_tauwoc}\forcode{ = .true.}). 
     81  (\np{nn\_fwb}\forcode{ = 0..2}), 
     82\item 
     83  the transformation of the solar radiation (if provided as daily mean) into an analytical diurnal cycle 
     84  (\np{ln\_dm2dc}\forcode{ = .true.}), 
     85\item 
     86  the activation of wave effects from an external wave model  (\np{ln\_wave}\forcode{ = .true.}), 
     87\item 
     88  a neutral drag coefficient is read from an external wave model (\np{ln\_cdgw}\forcode{ = .true.}), 
     89\item 
     90  the Stokes drift from an external wave model is accounted for (\np{ln\_sdw}\forcode{ = .true.}),  
     91\item 
     92  the choice of the Stokes drift profile parameterization (\np{nn\_sdrift}\forcode{ = 0..2}),  
     93\item 
     94  the surface stress given to the ocean is modified by surface waves (\np{ln\_tauwoc}\forcode{ = .true.}), 
     95\item 
     96  the surface stress given to the ocean is read from an external wave model (\np{ln\_tauw}\forcode{ = .true.}), 
     97\item 
     98  the Stokes-Coriolis term is included (\np{ln\_stcor}\forcode{ = .true.}), 
     99\item 
     100  the light penetration in the ocean (\np{ln\_traqsr}\forcode{ = .true.} with namelist \ngn{namtra\_qsr}), 
     101\item 
     102  the atmospheric surface pressure gradient effect on ocean and ice dynamics (\np{ln\_apr\_dyn}\forcode{ = .true.} with namelist \ngn{namsbc\_apr}), 
     103\item 
     104  the effect of sea-ice pressure on the ocean (\np{ln\_ice\_embd}\forcode{ = .true.}). 
    84105\end{itemize} 
    85106 
    86 In this chapter, we first discuss where the surface boundary condition appears in the model equations. 
    87 Then we present the five ways of providing the surface boundary condition,  
     107In this chapter, we first discuss where the surface boundary conditions appear in the model equations. 
     108Then we present the three ways of providing the surface boundary conditions,  
    88109followed by the description of the atmospheric pressure and the river runoff.  
    89 Next the scheme for interpolation on the fly is described. 
     110Next, the scheme for interpolation on the fly is described. 
    90111Finally, the different options that further modify the fluxes applied to the ocean are discussed. 
    91112One of these is modification by icebergs (see \autoref{sec:ICB_icebergs}), 
     
    95116 
    96117 
     118 
    97119% ================================================================ 
    98120% Surface boundary condition for the ocean 
    99121% ================================================================ 
    100122\section{Surface boundary condition for the ocean} 
    101 \label{sec:SBC_general} 
     123\label{sec:SBC_ocean} 
    102124 
    103125The surface ocean stress is the stress exerted by the wind and the sea-ice on the ocean. 
     
    111133The former is the non penetrative part of the heat flux 
    112134(\ie the sum of sensible, latent and long wave heat fluxes plus 
    113 the heat content of the mass exchange with the atmosphere and sea-ice). 
     135the heat content of the mass exchange between the ocean and sea-ice). 
    114136It is applied in \mdl{trasbc} module as a surface boundary condition trend of 
    115137the first level temperature time evolution equation 
    116 (see \autoref{eq:tra_sbc} and \autoref{eq:tra_sbc_lin} in \autoref{subsec:TRA_sbc}).  
     138(see \autoref{eq:tra_sbc} and \autoref{eq:tra_sbc_lin} in \autoref{subsec:TRA_sbc}). 
    117139The latter is the penetrative part of the heat flux. 
    118 It is applied as a 3D trends of the temperature equation (\mdl{traqsr} module) when 
     140It is applied as a 3D trend of the temperature equation (\mdl{traqsr} module) when 
    119141\np{ln\_traqsr}\forcode{ = .true.}. 
    120142The way the light penetrates inside the water column is generally a sum of decreasing exponentials 
     
    124146It represents the mass flux exchanged with the atmosphere (evaporation minus precipitation) and 
    125147possibly with the sea-ice and ice shelves (freezing minus melting of ice). 
    126 It affects both the ocean in two different ways: 
    127 $(i)$  it changes the volume of the ocean and therefore appears in the sea surface height equation as 
     148It affects the ocean in two different ways: 
     149$(i)$  it changes the volume of the ocean, and therefore appears in the sea surface height equation as      %GS: autoref ssh equation to be added 
    128150a volume flux, and  
    129151$(ii)$ it changes the surface temperature and salinity through the heat and salt contents of 
    130 the mass exchanged with the atmosphere, the sea-ice and the ice shelves.  
     152the mass exchanged with atmosphere, sea-ice and ice shelves. 
    131153 
    132154 
     
    157179the surface currents, temperature and salinity.   
    158180These variables are averaged over \np{nn\_fsbc} time-step (\autoref{tab:ssm}), and 
    159 it is these averaged fields which are used to computes the surface fluxes at a frequency of \np{nn\_fsbc} time-step. 
     181these averaged fields are used to compute the surface fluxes at the frequency of \np{nn\_fsbc} time-steps. 
    160182 
    161183 
     
    165187    \begin{tabular}{|l|l|l|l|} 
    166188      \hline 
    167       Variable description             & Model variable  & Units  & point \\  \hline 
    168       i-component of the surface current  & ssu\_m & $m.s^{-1}$   & U \\   \hline 
    169       j-component of the surface current  & ssv\_m & $m.s^{-1}$   & V \\   \hline 
    170       Sea surface temperature          & sst\_m & \r{}$K$      & T \\   \hline 
    171       Sea surface salinty              & sss\_m & $psu$        & T \\   \hline 
     189      Variable description                         & Model variable  & Units  & point                 \\\hline 
     190      i-component of the surface current  & ssu\_m               & $m.s^{-1}$     & U     \\\hline 
     191      j-component of the surface current  & ssv\_m               & $m.s^{-1}$     & V    \\ \hline 
     192      Sea surface temperature                & sst\_m               & \r{}$K$              & T     \\\hline 
     193      Sea surface salinty                          & sss\_m               & $psu$              & T    \\   \hline 
    172194    \end{tabular} 
    173195    \caption{ 
    174196      \protect\label{tab:ssm} 
    175197      Ocean variables provided by the ocean to the surface module (SBC). 
    176       The variable are averaged over nn{\_}fsbc time step, 
     198      The variable are averaged over \np{nn\_fsbc} time-step, 
    177199      \ie the frequency of computation of surface fluxes. 
    178200    } 
     
    184206 
    185207 
     208 
    186209% ================================================================ 
    187210%       Input Data  
     
    191214 
    192215A generic interface has been introduced to manage the way input data 
    193 (2D or 3D fields, like surface forcing or ocean T and S) are specify in \NEMO. 
    194 This task is archieved by \mdl{fldread}. 
    195 The module was design with four main objectives in mind:  
     216(2D or 3D fields, like surface forcing or ocean T and S) are specified in \NEMO. 
     217This task is achieved by \mdl{fldread}. 
     218The module is designed with four main objectives in mind:  
    196219\begin{enumerate} 
    197220\item 
    198   optionally provide a time interpolation of the input data at model time-step, whatever their input frequency is, 
     221  optionally provide a time interpolation of the input data every specified model time-step, whatever their input frequency is, 
    199222  and according to the different calendars available in the model. 
    200223\item 
     
    204227\item 
    205228  provide a simple user interface and a rather simple developer interface by 
    206   limiting the number of prerequisite information.  
    207 \end{enumerate}   
    208  
    209 As a results the user have only to fill in for each variable a structure in the namelist file to 
     229  limiting the number of prerequisite informations.  
     230\end{enumerate} 
     231 
     232As a result, the user has only to fill in for each variable a structure in the namelist file to 
    210233define the input data file and variable names, the frequency of the data (in hours or months), 
    211234whether its is climatological data or not, the period covered by the input file (one year, month, week or day), 
    212 and three additional parameters for on-the-fly interpolation. 
     235and three additional parameters for the on-the-fly interpolation. 
    213236When adding a new input variable, the developer has to add the associated structure in the namelist, 
    214237read this information by mirroring the namelist read in \rou{sbc\_blk\_init} for example, 
     
    220243 
    221244Note that when an input data is archived on a disc which is accessible directly from the workspace where 
    222 the code is executed, then the use can set the \np{cn\_dir} to the pathway leading to the data. 
    223 By default, the data are assumed to have been copied so that cn\_dir='./'. 
     245the code is executed, then the user can set the \np{cn\_dir} to the pathway leading to the data. 
     246By default, the data are assumed to be in the same directory as the executable, so that cn\_dir='./'. 
     247 
    224248 
    225249% ------------------------------------------------------------------------------------------------------------- 
    226250% Input Data specification (\mdl{fldread}) 
    227251% ------------------------------------------------------------------------------------------------------------- 
    228 \subsection{Input data specification (\protect\mdl{fldread})} 
     252\subsection[Input data specification (\textit{fldread.F90})] 
     253{Input data specification (\protect\mdl{fldread})} 
    229254\label{subsec:SBC_fldread} 
    230255 
     
    237262\begin{description}   
    238263\item[File name]: 
    239   the stem name of the NetCDF file to be open. 
     264  the stem name of the NetCDF file to be opened. 
    240265  This stem will be completed automatically by the model, with the addition of a '.nc' at its end and 
    241266  by date information and possibly a prefix (when using AGRIF). 
     
    248273      \begin{tabular}{|l|c|c|c|} 
    249274        \hline 
    250         & daily or weekLLL         & monthly                   &   yearly          \\   \hline 
    251         \np{clim}\forcode{ = .false.}  & fn\_yYYYYmMMdDD.nc  &   fn\_yYYYYmMM.nc   &   fn\_yYYYY.nc  \\   \hline 
    252         \np{clim}\forcode{ = .true.}         & not possible                  &  fn\_m??.nc             &   fn                \\   \hline 
     275                                        &  daily or weekLL     &  monthly           &  yearly        \\   \hline 
     276        \np{clim}\forcode{ = .false.}  &  fn\_yYYYYmMMdDD.nc  &  fn\_yYYYYmMM.nc   &  fn\_yYYYY.nc  \\   \hline 
     277        \np{clim}\forcode{ = .true.}   &  not possible        &  fn\_m??.nc        &  fn            \\   \hline 
    253278      \end{tabular} 
    254279    \end{center} 
    255280    \caption{ 
    256281      \protect\label{tab:fldread} 
    257       naming nomenclature for climatological or interannual input file, as a function of the Open/close frequency. 
     282      naming nomenclature for climatological or interannual input file(s), as a function of the open/close frequency. 
    258283      The stem name is assumed to be 'fn'. 
    259284      For weekly files, the 'LLL' corresponds to the first three letters of the first day of the week 
     
    262287      Note that (1) in mpp, if the file is split over each subdomain, the suffix '.nc' is replaced by '\_PPPP.nc', 
    263288      where 'PPPP' is the process number coded with 4 digits; 
    264       (2) when using AGRIF, the prefix '\_N' is added to files, where 'N'  is the child grid number. 
     289      (2) when using AGRIF, the prefix '\_N' is added to files, where 'N' is the child grid number. 
    265290    } 
    266291  \end{table} 
     
    272297  Its unit is in hours if it is positive (for example 24 for daily forcing) or in months if negative 
    273298  (for example -1 for monthly forcing or -12 for annual forcing). 
    274   Note that this frequency must really be an integer and not a real. 
    275   On some computers, seting it to '24.' can be interpreted as 240! 
     299  Note that this frequency must REALLY be an integer and not a real. 
     300  On some computers, setting it to '24.' can be interpreted as 240! 
    276301 
    277302\item[Variable name]: 
     
    284309  00h00'00'' to 23h59'59". 
    285310  If set to 'true', the forcing will have a broken line shape. 
    286   Records are assumed to be dated the middle of the forcing period. 
     311  Records are assumed to be dated at the middle of the forcing period. 
    287312  For example, when using a daily forcing with time interpolation, 
    288313  linear interpolation will be performed between mid-day of two consecutive days.  
     
    291316  a logical to specify if a input file contains climatological forcing which can be cycle in time, 
    292317  or an interannual forcing which will requires additional files if 
    293   the period covered by the simulation exceed the one of the file. 
    294   See the above the file naming strategy which impacts the expected name of the file to be opened.  
     318  the period covered by the simulation exceeds the one of the file. 
     319  See the above file naming strategy which impacts the expected name of the file to be opened.  
    295320 
    296321\item[Open/close frequency]: 
     
    301326  Files are assumed to contain data from the beginning of the open/close period. 
    302327  For example, the first record of a yearly file containing daily data is Jan 1st even if 
    303   the experiment is not starting at the beginning of the year.  
     328  the experiment is not starting at the beginning of the year. 
    304329 
    305330\item[Others]: 
     
    313338The only tricky point is therefore to specify the date at which we need to do the interpolation and 
    314339the date of the records read in the input files. 
    315 Following \citet{Leclair_Madec_OM09}, the date of a time step is set at the middle of the time step. 
    316 For example, for an experiment starting at 0h00'00" with a one hour time-step, 
     340Following \citet{leclair.madec_OM09}, the date of a time step is set at the middle of the time step. 
     341For example, for an experiment starting at 0h00'00" with a one-hour time-step, 
    317342a time interpolation will be performed at the following time: 0h30'00", 1h30'00", 2h30'00", etc. 
    318343However, for forcing data related to the surface module, 
    319344values are not needed at every time-step but at every \np{nn\_fsbc} time-step. 
    320345For example with \np{nn\_fsbc}\forcode{ = 3}, the surface module will be called at time-steps 1, 4, 7, etc. 
    321 The date used for the time interpolation is thus redefined to be at the middle of \np{nn\_fsbc} time-step period. 
     346The date used for the time interpolation is thus redefined to the middle of \np{nn\_fsbc} time-step period. 
    322347In the previous example, this leads to: 1h30'00", 4h30'00", 7h30'00", etc. \\  
    323348(2) For code readablility and maintenance issues, we don't take into account the NetCDF input file calendar. 
     
    325350user in the record frequency, the open/close frequency and the type of temporal interpolation. 
    326351For example, the first record of a yearly file containing daily data that will be interpolated in time is assumed to 
    327 be start Jan 1st at 12h00'00" and end Dec 31st at 12h00'00". \\ 
     352start Jan 1st at 12h00'00" and end Dec 31st at 12h00'00". \\ 
    328353(3) If a time interpolation is requested, the code will pick up the needed data in the previous (next) file when 
    329354interpolating data with the first (last) record of the open/close period. 
     
    333358If the forcing is climatological, Dec and Jan will be keep-up from the same year. 
    334359However, if the forcing is not climatological, at the end of 
    335 the open/close period the code will automatically close the current file and open the next one. 
     360the open/close period, the code will automatically close the current file and open the next one. 
    336361Note that, if the experiment is starting (ending) at the beginning (end) of 
    337 an open/close period we do accept that the previous (next) file is not existing. 
     362an open/close period, we do accept that the previous (next) file is not existing. 
    338363In this case, the time interpolation will be performed between two identical values. 
    339364For example, when starting an experiment on Jan 1st of year Y with yearly files and daily data to be interpolated, 
     
    353378Interpolation on the Fly allows the user to supply input files required for the surface forcing on 
    354379grids other than the model grid. 
    355 To do this he or she must supply, in addition to the source data file, a file of weights to be used to 
     380To do this, he or she must supply, in addition to the source data file(s), a file of weights to be used to 
    356381interpolate from the data grid to the model grid. 
    357382The original development of this code used the SCRIP package 
    358383(freely available \href{http://climate.lanl.gov/Software/SCRIP}{here} under a copyright agreement). 
    359 In principle, any package can be used to generate the weights, but the variables in 
     384In principle, any package such as CDO can be used to generate the weights, but the variables in 
    360385the input weights file must have the same names and meanings as assumed by the model. 
    361 Two methods are currently available: bilinear and bicubic interpolation. 
     386Two methods are currently available: bilinear and bicubic interpolations. 
    362387Prior to the interpolation, providing a land/sea mask file, the user can decide to remove land points from 
    363388the input file and substitute the corresponding values with the average of the 8 neighbouring points in 
     
    365390Only "sea points" are considered for the averaging. 
    366391The land/sea mask file must be provided in the structure associated with the input variable. 
    367 The netcdf land/sea mask variable name must be 'LSM' it must have the same horizontal and vertical dimensions of 
    368 the associated variable and should be equal to 1 over land and 0 elsewhere. 
    369 The procedure can be recursively applied setting nn\_lsm > 1 in namsbc namelist. 
    370 Note that nn\_lsm=0 forces the code to not apply the procedure even if a file for land/sea mask is supplied. 
    371  
     392The netcdf land/sea mask variable name must be 'LSM' and must have the same horizontal and vertical dimensions as 
     393the associated variables and should be equal to 1 over land and 0 elsewhere. 
     394The procedure can be recursively applied by setting nn\_lsm > 1 in namsbc namelist. 
     395Note that nn\_lsm=0 forces the code to not apply the procedure, even if a land/sea mask file is supplied. 
     396 
     397 
     398% ------------------------------------------------------------------------------------------------------------- 
     399% Bilinear interpolation 
     400% ------------------------------------------------------------------------------------------------------------- 
    372401\subsubsection{Bilinear interpolation} 
    373402\label{subsec:SBC_iof_bilinear} 
     
    375404The input weights file in this case has two sets of variables: 
    376405src01, src02, src03, src04 and wgt01, wgt02, wgt03, wgt04. 
    377 The "src" variables correspond to the point in the input grid to which the weight "wgt" is to be applied. 
     406The "src" variables correspond to the point in the input grid to which the weight "wgt" is applied. 
    378407Each src value is an integer corresponding to the index of a point in the input grid when 
    379408written as a one dimensional array. 
     
    391420and wgt(1) corresponds to variable "wgt01" for example. 
    392421 
     422 
     423% ------------------------------------------------------------------------------------------------------------- 
     424% Bicubic interpolation 
     425% ------------------------------------------------------------------------------------------------------------- 
    393426\subsubsection{Bicubic interpolation} 
    394427\label{subsec:SBC_iof_bicubic} 
    395428 
    396 Again there are two sets of variables: "src" and "wgt". 
    397 But in this case there are 16 of each. 
     429Again, there are two sets of variables: "src" and "wgt". 
     430But in this case, there are 16 of each. 
    398431The symbolic algorithm used to calculate values on the model grid is now: 
    399432 
     
    401434  \begin{split} 
    402435    f_{m}(i,j) =  f_{m}(i,j) +& \sum_{k=1}^{4} {wgt(k)f(idx(src(k)))} 
    403     +   \sum_{k=5}^{8} {wgt(k)\left.\frac{\partial f}{\partial i}\right| _{idx(src(k))} }    \\ 
    404     +& \sum_{k=9}^{12} {wgt(k)\left.\frac{\partial f}{\partial j}\right| _{idx(src(k))} } 
    405     +   \sum_{k=13}^{16} {wgt(k)\left.\frac{\partial ^2 f}{\partial i \partial j}\right| _{idx(src(k))} } 
     436    +  \sum_{k=5 }^{8 } {wgt(k)\left.\frac{\partial f}{\partial i}\right| _{idx(src(k))} }    \\ 
     437    +& \sum_{k=9 }^{12} {wgt(k)\left.\frac{\partial f}{\partial j}\right| _{idx(src(k))} } 
     438    +  \sum_{k=13}^{16} {wgt(k)\left.\frac{\partial ^2 f}{\partial i \partial j}\right| _{idx(src(k))} } 
    406439  \end{split} 
    407440\] 
    408441The gradients here are taken with respect to the horizontal indices and not distances since 
    409 the spatial dependency has been absorbed into the weights. 
    410  
     442the spatial dependency has been included into the weights. 
     443 
     444 
     445% ------------------------------------------------------------------------------------------------------------- 
     446% Implementation 
     447% ------------------------------------------------------------------------------------------------------------- 
    411448\subsubsection{Implementation} 
    412449\label{subsec:SBC_iof_imp} 
     
    420457inspecting a global attribute stored in the weights input file. 
    421458This attribute must be called "ew\_wrap" and be of integer type. 
    422 If it is negative, the input non-model grid is assumed not to be cyclic. 
     459If it is negative, the input non-model grid is assumed to be not cyclic. 
    423460If zero or greater, then the value represents the number of columns that overlap. 
    424461$E.g.$ if the input grid has columns at longitudes 0, 1, 2, .... , 359, then ew\_wrap should be set to 0; 
    425462if longitudes are 0.5, 2.5, .... , 358.5, 360.5, 362.5, ew\_wrap should be 2. 
    426463If the model does not find attribute ew\_wrap, then a value of -999 is assumed. 
    427 In this case the \rou{fld\_read} routine defaults ew\_wrap to value 0 and 
     464In this case, the \rou{fld\_read} routine defaults ew\_wrap to value 0 and 
    428465therefore the grid is assumed to be cyclic with no overlapping columns. 
    429 (In fact this only matters when bicubic interpolation is required.) 
     466(In fact, this only matters when bicubic interpolation is required.) 
    430467Note that no testing is done to check the validity in the model, 
    431468since there is no way of knowing the name used for the longitude variable, 
     
    444481or is a copy of one from the first few columns on the opposite side of the grid (cyclical case). 
    445482 
     483 
     484% ------------------------------------------------------------------------------------------------------------- 
     485% Limitations 
     486% ------------------------------------------------------------------------------------------------------------- 
    446487\subsubsection{Limitations} 
    447488\label{subsec:SBC_iof_lim} 
     
    449490\begin{enumerate}   
    450491\item 
    451   The case where input data grids are not logically rectangular has not been tested. 
     492  The case where input data grids are not logically rectangular (irregular grid case) has not been tested. 
    452493\item 
    453494  This code is not guaranteed to produce positive definite answers from positive definite inputs when 
     
    470511(see the directory NEMOGCM/TOOLS/WEIGHTS). 
    471512 
     513 
    472514% ------------------------------------------------------------------------------------------------------------- 
    473515% Standalone Surface Boundary Condition Scheme 
    474516% ------------------------------------------------------------------------------------------------------------- 
    475 \subsection{Standalone surface boundary condition scheme} 
    476 \label{subsec:SAS_iof} 
    477  
    478 %---------------------------------------namsbc_ana-------------------------------------------------- 
     517\subsection{Standalone surface boundary condition scheme (SAS)} 
     518\label{subsec:SAS} 
     519 
     520%---------------------------------------namsbc_sas-------------------------------------------------- 
    479521 
    480522\nlst{namsbc_sas} 
    481523%-------------------------------------------------------------------------------------------------------------- 
    482524 
    483 In some circumstances it may be useful to avoid calculating the 3D temperature, 
     525In some circumstances, it may be useful to avoid calculating the 3D temperature, 
    484526salinity and velocity fields and simply read them in from a previous run or receive them from OASIS.   
    485527For example: 
     
    496538  Spinup of the iceberg floats 
    497539\item 
    498   Ocean/sea-ice simulation with both media running in parallel (\np{ln\_mixcpl}\forcode{ = .true.}) 
     540  Ocean/sea-ice simulation with both models running in parallel (\np{ln\_mixcpl}\forcode{ = .true.}) 
    499541\end{itemize} 
    500542 
    501 The StandAlone Surface scheme provides this utility. 
     543The Standalone Surface scheme provides this capacity. 
    502544Its options are defined through the \ngn{namsbc\_sas} namelist variables. 
    503545A new copy of the model has to be compiled with a configuration based on ORCA2\_SAS\_LIM. 
    504 However no namelist parameters need be changed from the settings of the previous run (except perhaps nn{\_}date0). 
     546However, no namelist parameters need be changed from the settings of the previous run (except perhaps nn{\_}date0). 
    505547In this configuration, a few routines in the standard model are overriden by new versions. 
    506548Routines replaced are: 
     
    524566  so calls to restart functions have been removed. 
    525567  This also means that the calendar cannot be controlled by time in a restart file, 
    526   so the user must make sure that nn{\_}date0 in the model namelist is correct for his or her purposes. 
     568  so the user must check that nn{\_}date0 in the model namelist is correct for his or her purposes. 
    527569\item 
    528570  \mdl{stpctl}: 
     
    543585  velocity arrays at the surface. 
    544586  These filenames are supplied in namelist namsbc{\_}sas. 
    545   Unfortunately because of limitations with the \mdl{iom} module, 
     587  Unfortunately, because of limitations with the \mdl{iom} module, 
    546588  the full 3D fields from the mean files have to be read in and interpolated in time, 
    547589  before using just the top level. 
     
    550592 
    551593 
    552 % Missing the description of the 2 following variables: 
    553 %   ln_3d_uve   = .true.    !  specify whether we are supplying a 3D u,v and e3 field 
    554 %   ln_read_frq = .false.    !  specify whether we must read frq or not 
    555  
    556  
    557  
    558 % ================================================================ 
    559 % Analytical formulation (sbcana module)  
    560 % ================================================================ 
    561 \section{Analytical formulation (\protect\mdl{sbcana})} 
    562 \label{sec:SBC_ana} 
    563  
    564 %---------------------------------------namsbc_ana-------------------------------------------------- 
    565 % 
    566 %\nlst{namsbc_ana} 
    567 %-------------------------------------------------------------------------------------------------------------- 
    568  
    569 The analytical formulation of the surface boundary condition is the default scheme. 
    570 In this case, all the six fluxes needed by the ocean are assumed to be uniform in space. 
    571 They take constant values given in the namelist \ngn{namsbc{\_}ana} by 
    572 the variables \np{rn\_utau0}, \np{rn\_vtau0}, \np{rn\_qns0}, \np{rn\_qsr0}, and \np{rn\_emp0} 
    573 ($\textit{emp}=\textit{emp}_S$). 
    574 The runoff is set to zero. 
    575 In addition, the wind is allowed to reach its nominal value within a given number of time steps (\np{nn\_tau000}). 
    576  
    577 If a user wants to apply a different analytical forcing, 
    578 the \mdl{sbcana} module can be modified to use another scheme. 
    579 As an example, the \mdl{sbc\_ana\_gyre} routine provides the analytical forcing for the GYRE configuration 
    580 (see GYRE configuration manual, in preparation). 
     594The user can also choose in the \ngn{namsbc\_sas} namelist to read the mean (nn\_fsbc time-step) fraction of solar net radiation absorbed in the 1st T level using 
     595 (\np{ln\_flx}\forcode{ = .true.}) and to provide 3D oceanic velocities instead of 2D ones (\np{ln\_flx}\forcode{ = .true.}). In that last case, only the 1st level will be read in. 
     596 
    581597 
    582598 
     
    584600% Flux formulation  
    585601% ================================================================ 
    586 \section{Flux formulation (\protect\mdl{sbcflx})} 
     602\section[Flux formulation (\textit{sbcflx.F90})] 
     603{Flux formulation (\protect\mdl{sbcflx})} 
    587604\label{sec:SBC_flx} 
    588605%------------------------------------------namsbc_flx---------------------------------------------------- 
     
    602619 
    603620 
     621 
    604622% ================================================================ 
    605623% Bulk formulation 
    606624% ================================================================ 
    607 \section[Bulk formulation {(\textit{sbcblk\{\_core,\_clio\}.F90})}] 
    608                         {Bulk formulation {(\protect\mdl{sbcblk\_core}, \protect\mdl{sbcblk\_clio})}} 
     625\section[Bulk formulation (\textit{sbcblk.F90})] 
     626{Bulk formulation (\protect\mdl{sbcblk})} 
    609627\label{sec:SBC_blk} 
    610  
    611 In the bulk formulation, the surface boundary condition fields are computed using bulk formulae and atmospheric fields and ocean (and ice) variables. 
     628%---------------------------------------namsbc_blk-------------------------------------------------- 
     629 
     630\nlst{namsbc_blk} 
     631%-------------------------------------------------------------------------------------------------------------- 
     632 
     633In the bulk formulation, the surface boundary condition fields are computed with bulk formulae using atmospheric fields  
     634and ocean (and sea-ice) variables averaged over \np{nn\_fsbc} time-step. 
    612635 
    613636The atmospheric fields used depend on the bulk formulae used. 
    614 Two bulk formulations are available: 
    615 the CORE and the CLIO bulk formulea. 
     637In forced mode, when a sea-ice model is used, a specific bulk formulation is used. 
     638Therefore, different bulk formulae are used for the turbulent fluxes computation 
     639over the ocean and over sea-ice surface.  
     640For the ocean, four bulk formulations are available thanks to the \href{https://brodeau.github.io/aerobulk/}{Aerobulk} package (\citet{brodeau.barnier.ea_JPO16}):  
     641the NCAR (formerly named CORE), COARE 3.0, COARE 3.5 and ECMWF bulk formulae. 
    616642The choice is made by setting to true one of the following namelist variable: 
    617 \np{ln\_core} or \np{ln\_clio}. 
    618  
    619 Note: 
    620 in forced mode, when a sea-ice model is used, a bulk formulation (CLIO or CORE) have to be used. 
    621 Therefore the two bulk (CLIO and CORE) formulea include the computation of the fluxes over 
    622 both an ocean and an ice surface.  
    623  
    624 % ------------------------------------------------------------------------------------------------------------- 
    625 %        CORE Bulk formulea 
    626 % ------------------------------------------------------------------------------------------------------------- 
    627 \subsection{CORE formulea (\protect\mdl{sbcblk\_core}, \protect\np{ln\_core}\forcode{ = .true.})} 
    628 \label{subsec:SBC_blk_core} 
    629 %------------------------------------------namsbc_core---------------------------------------------------- 
    630 % 
    631 %\nlst{namsbc_core} 
    632 %------------------------------------------------------------------------------------------------------------- 
    633  
    634 The CORE bulk formulae have been developed by \citet{Large_Yeager_Rep04}. 
    635 They have been designed to handle the CORE forcing, a mixture of NCEP reanalysis and satellite data. 
    636 They use an inertial dissipative method to compute the turbulent transfer coefficients 
    637 (momentum, sensible heat and evaporation) from the 10 metre wind speed, air temperature and specific humidity. 
    638 This \citet{Large_Yeager_Rep04} dataset is available through 
    639 the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/CORE.html}{GFDL web site}. 
    640  
    641 Note that substituting ERA40 to NCEP reanalysis fields does not require changes in the bulk formulea themself. 
    642 This is the so-called DRAKKAR Forcing Set (DFS) \citep{Brodeau_al_OM09}. 
    643  
    644 Options are defined through the  \ngn{namsbc\_core} namelist variables. 
    645 The required 8 input fields are: 
     643 \np{ln\_NCAR}, \np{ln\_COARE\_3p0},  \np{ln\_COARE\_3p5} and  \np{ln\_ECMWF}. 
     644For sea-ice, three possibilities can be selected: 
     645a constant transfer coefficient (1.4e-3; default value), \citet{lupkes.gryanik.ea_JGR12} (\np{ln\_Cd\_L12}), and \citet{lupkes.gryanik_JGR15} (\np{ln\_Cd\_L15}) parameterizations 
     646 
     647Common options are defined through the \ngn{namsbc\_blk} namelist variables. 
     648The required 9 input fields are: 
    646649 
    647650%--------------------------------------------------TABLE-------------------------------------------------- 
    648651\begin{table}[htbp] 
    649   \label{tab:CORE} 
     652  \label{tab:BULK} 
    650653  \begin{center} 
    651654    \begin{tabular}{|l|c|c|c|} 
    652655      \hline 
    653       Variable desciption              & Model variable  & Units   & point \\    \hline 
    654       i-component of the 10m air velocity & utau      & $m.s^{-1}$         & T  \\  \hline 
    655       j-component of the 10m air velocity & vtau      & $m.s^{-1}$         & T  \\  \hline 
    656       10m air temperature              & tair      & \r{}$K$            & T   \\ \hline 
    657       Specific humidity             & humi      & \%              & T \\      \hline 
    658       Incoming long wave radiation     & qlw    & $W.m^{-2}$         & T \\      \hline 
    659       Incoming short wave radiation    & qsr    & $W.m^{-2}$         & T \\      \hline 
    660       Total precipitation (liquid + solid)   & precip & $Kg.m^{-2}.s^{-1}$ & T \\   \hline 
    661       Solid precipitation              & snow      & $Kg.m^{-2}.s^{-1}$ & T \\   \hline 
     656      Variable description                           & Model variable   & Units                         & point \\   \hline 
     657      i-component of the 10m air velocity   & utau                   & $m.s^{-1}$                   & T         \\   \hline 
     658      j-component of the 10m air velocity   & vtau                & $m.s^{-1}$                   & T         \\   \hline 
     659      10m air temperature                      & tair                & \r{}$K$                        & T       \\   \hline 
     660      Specific humidity                        & humi           & \%                             & T      \\   \hline 
     661      Incoming long wave radiation          & qlw                & $W.m^{-2}$            & T        \\   \hline 
     662      Incoming short wave radiation          & qsr               & $W.m^{-2}$            & T        \\   \hline 
     663      Total precipitation (liquid + solid)         & precip            & $Kg.m^{-2}.s^{-1}$      & T      \\   \hline 
     664      Solid precipitation                           & snow               & $Kg.m^{-2}.s^{-1}$       & T      \\   \hline 
     665      Mean sea-level pressure                     & slp                     & $hPa$                          & T       \\ \hline 
    662666    \end{tabular} 
    663667  \end{center} 
     
    678682\np{rn\_zu}: is the height of wind measurements (m) 
    679683 
    680 Three multiplicative factors are availables:  
    681 \np{rn\_pfac} and \np{rn\_efac} allows to adjust (if necessary) the global freshwater budget by 
     684Three multiplicative factors are available:  
     685\np{rn\_pfac} and \np{rn\_efac} allow to adjust (if necessary) the global freshwater budget by 
    682686increasing/reducing the precipitations (total and snow) and or evaporation, respectively. 
    683687The third one,\np{rn\_vfac}, control to which extend the ice/ocean velocities are taken into account in 
    684688the calculation of surface wind stress. 
    685 Its range should be between zero and one, and it is recommended to set it to 0. 
    686  
    687 % ------------------------------------------------------------------------------------------------------------- 
    688 %        CLIO Bulk formulea 
    689 % ------------------------------------------------------------------------------------------------------------- 
    690 \subsection{CLIO formulea (\protect\mdl{sbcblk\_clio}, \protect\np{ln\_clio}\forcode{ = .true.})} 
    691 \label{subsec:SBC_blk_clio} 
    692 %------------------------------------------namsbc_clio---------------------------------------------------- 
    693 % 
    694 %\nlst{namsbc_clio} 
    695 %------------------------------------------------------------------------------------------------------------- 
    696  
    697 The CLIO bulk formulae were developed several years ago for the Louvain-la-neuve coupled ice-ocean model 
    698 (CLIO, \cite{Goosse_al_JGR99}).  
    699 They are simpler bulk formulae. 
    700 They assume the stress to be known and compute the radiative fluxes from a climatological cloud cover.  
    701  
    702 Options are defined through the  \ngn{namsbc\_clio} namelist variables. 
    703 The required 7 input fields are: 
    704  
    705 %--------------------------------------------------TABLE-------------------------------------------------- 
    706 \begin{table}[htbp] 
    707   \label{tab:CLIO} 
    708   \begin{center} 
    709     \begin{tabular}{|l|l|l|l|} 
    710       \hline 
    711       Variable desciption           & Model variable  & Units           & point \\  \hline 
    712       i-component of the ocean stress     & utau         & $N.m^{-2}$         & U \\   \hline 
    713       j-component of the ocean stress     & vtau         & $N.m^{-2}$         & V \\   \hline 
    714       Wind speed module             & vatm         & $m.s^{-1}$         & T \\   \hline 
    715       10m air temperature              & tair         & \r{}$K$            & T \\   \hline 
    716       Specific humidity                & humi         & \%              & T \\   \hline 
    717       Cloud cover                   &           & \%              & T \\   \hline 
    718       Total precipitation (liquid + solid)   & precip    & $Kg.m^{-2}.s^{-1}$ & T \\   \hline 
    719       Solid precipitation              & snow         & $Kg.m^{-2}.s^{-1}$ & T \\   \hline 
    720     \end{tabular} 
    721   \end{center} 
    722 \end{table} 
    723 %-------------------------------------------------------------------------------------------------------------- 
     689Its range must be between zero and one, and it is recommended to set it to 0 at low-resolution (ORCA2 configuration). 
    724690 
    725691As for the flux formulation, information about the input data required by the model is provided in 
    726 the namsbc\_blk\_core or namsbc\_blk\_clio namelist (see \autoref{subsec:SBC_fldread}).  
     692the namsbc\_blk namelist (see \autoref{subsec:SBC_fldread}).  
     693 
     694 
     695% ------------------------------------------------------------------------------------------------------------- 
     696%        Ocean-Atmosphere Bulk formulae 
     697% ------------------------------------------------------------------------------------------------------------- 
     698\subsection{Ocean-Atmosphere Bulk formulae} 
     699%\subsection[Ocean-Atmosphere Bulk formulae (\textit{sbcblk_algo\{\_ncar,\_coare,\_coare3p5,\_ecmwf}.F90})] 
     700\label{subsec:SBC_blk_ocean} 
     701 
     702Four different bulk algorithms are available to compute surface turbulent momentum and heat fluxes over the ocean. 
     703COARE 3.0, COARE 3.5 and ECMWF schemes mainly differ by their roughness lenghts computation and consequently  
     704their neutral transfer coefficients relationships with neutral wind. 
     705\begin{itemize} 
     706\item 
     707  NCAR (\np{ln\_NCAR}\forcode{ = .true.}): 
     708  The NCAR bulk formulae have been developed by \citet{large.yeager_rpt04}. 
     709  They have been designed to handle the NCAR forcing, a mixture of NCEP reanalysis and satellite data. 
     710  They use an inertial dissipative method to compute the turbulent transfer coefficients 
     711  (momentum, sensible heat and evaporation) from the 10m wind speed, air temperature and specific humidity. 
     712  This \citet{large.yeager_rpt04} dataset is available through 
     713  the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/NCAR.html}{GFDL web site}. 
     714  Note that substituting ERA40 to NCEP reanalysis fields does not require changes in the bulk formulea themself. 
     715  This is the so-called DRAKKAR Forcing Set (DFS) \citep{brodeau.barnier.ea_OM10}. 
     716\item 
     717  COARE 3.0 (\np{ln\_COARE\_3p0}\forcode{ = .true.}):  
     718  See \citet{fairall.bradley.ea_JC03} for more details 
     719\item 
     720  COARE 3.5 (\np{ln\_COARE\_3p5}\forcode{ = .true.}):  
     721  See \citet{edson.jampana.ea_JPO13} for more details 
     722\item 
     723  ECMWF (\np{ln\_ECMWF}\forcode{ = .true.}):  
     724  Based on \href{https://www.ecmwf.int/node/9221}{IFS (Cy31)} implementation and documentation. 
     725  Surface roughness lengths needed for the Obukhov length are computed following \citet{beljaars_QJRMS95}. 
     726\end{itemize} 
     727 
     728 
     729% ------------------------------------------------------------------------------------------------------------- 
     730%        Ice-Atmosphere Bulk formulae 
     731% ------------------------------------------------------------------------------------------------------------- 
     732\subsection{ Ice-Atmosphere Bulk formulae } 
     733\label{subsec:SBC_blk_ice} 
     734 
     735Surface turbulent fluxes between sea-ice and the atmosphere can be computed in three different ways: 
     736 
     737\begin{itemize} 
     738\item 
     739  Constant value (\np{constant\ value}\forcode{ Cd_ice = 1.4e-3 }): 
     740  default constant value used for momentum and heat neutral transfer coefficients 
     741\item 
     742  \citet{lupkes.gryanik.ea_JGR12} (\np{ln\_Cd\_L12}\forcode{ = .true.}): 
     743  This scheme adds a dependency on edges at leads, melt ponds and flows 
     744  of the constant neutral air-ice drag. After some approximations,  
     745  this can be resumed to a dependency on ice concentration (A). 
     746  This drag coefficient has a parabolic shape (as a function of ice concentration) 
     747  starting at 1.5e-3 for A=0, reaching 1.97e-3 for A=0.5 and going down 1.4e-3 for A=1. 
     748  It is theoretically applicable to all ice conditions (not only MIZ). 
     749\item 
     750  \citet{lupkes.gryanik_JGR15} (\np{ln\_Cd\_L15}\forcode{ = .true.}): 
     751  Alternative turbulent transfer coefficients formulation between sea-ice  
     752  and atmosphere with distinct momentum and heat coefficients depending  
     753  on sea-ice concentration and atmospheric stability (no melt-ponds effect for now). 
     754  The parameterization is adapted from ECHAM6 atmospheric model. 
     755  Compared to Lupkes2012 scheme, it considers specific skin and form drags 
     756  to compute neutral transfer coefficients for both heat and momentum fluxes. 
     757  Atmospheric stability effect on transfer coefficient is also taken into account. 
     758\end{itemize} 
     759 
     760 
    727761 
    728762% ================================================================ 
    729763% Coupled formulation 
    730764% ================================================================ 
    731 \section{Coupled formulation (\protect\mdl{sbccpl})} 
     765\section[Coupled formulation (\textit{sbccpl.F90})] 
     766{Coupled formulation (\protect\mdl{sbccpl})} 
    732767\label{sec:SBC_cpl} 
    733768%------------------------------------------namsbc_cpl---------------------------------------------------- 
     
    737772 
    738773In the coupled formulation of the surface boundary condition, 
    739 the fluxes are provided by the OASIS coupler at a frequency which is defined in the OASIS coupler, 
     774the fluxes are provided by the OASIS coupler at a frequency which is defined in the OASIS coupler namelist, 
    740775while sea and ice surface temperature, ocean and ice albedo, and ocean currents are sent to 
    741776the atmospheric component. 
    742777 
    743778A generalised coupled interface has been developed. 
    744 It is currently interfaced with OASIS-3-MCT (\key{oasis3}). 
     779It is currently interfaced with OASIS-3-MCT versions 1 to 4 (\key{oasis3}). 
     780An additional specific CPP key (\key{oa3mct\_v1v2}) is needed for OASIS-3-MCT versions 1 and 2. 
    745781It has been successfully used to interface \NEMO to most of the European atmospheric GCM 
    746782(ARPEGE, ECHAM, ECMWF, HadAM, HadGAM, LMDz), as well as to \href{http://wrf-model.org/}{WRF} 
    747783(Weather Research and Forecasting Model). 
    748784 
    749 Note that in addition to the setting of \np{ln\_cpl} to true, the \key{coupled} have to be defined. 
    750 The CPP key is mainly used in sea-ice to ensure that the atmospheric fluxes are actually received by 
    751 the ice-ocean system (no calculation of ice sublimation in coupled mode). 
    752 When PISCES biogeochemical model (\key{top} and \key{pisces}) is also used in the coupled system,  
    753 the whole carbon cycle is computed by defining \key{cpl\_carbon\_cycle}. 
     785When PISCES biogeochemical model (\key{top}) is also used in the coupled system,  
     786the whole carbon cycle is computed. 
    754787In this case, CO$_2$ fluxes will be exchanged between the atmosphere and the ice-ocean system 
    755788(and need to be activated in \ngn{namsbc{\_}cpl} ). 
     
    757790The namelist above allows control of various aspects of the coupling fields (particularly for vectors) and 
    758791now allows for any coupling fields to have multiple sea ice categories (as required by LIM3 and CICE). 
    759 When indicating a multi-category coupling field in namsbc{\_}cpl the number of categories will be determined by 
     792When indicating a multi-category coupling field in \ngn{namsbc{\_}cpl}, the number of categories will be determined by 
    760793the number used in the sea ice model. 
    761 In some limited cases it may be possible to specify single category coupling fields even when 
     794In some limited cases, it may be possible to specify single category coupling fields even when 
    762795the sea ice model is running with multiple categories - 
    763 in this case the user should examine the code to be sure the assumptions made are satisfactory. 
    764 In cases where this is definitely not possible the model should abort with an error message. 
    765 The new code has been tested using ECHAM with LIM2, and HadGAM3 with CICE but 
    766 although it will compile with \key{lim3} additional minor code changes may be required to run using LIM3. 
     796in this case, the user should examine the code to be sure the assumptions made are satisfactory. 
     797In cases where this is definitely not possible, the model should abort with an error message. 
     798 
    767799 
    768800 
     
    770802%        Atmospheric pressure 
    771803% ================================================================ 
    772 \section{Atmospheric pressure (\protect\mdl{sbcapr})} 
     804\section[Atmospheric pressure (\textit{sbcapr.F90})] 
     805{Atmospheric pressure (\protect\mdl{sbcapr})} 
    773806\label{sec:SBC_apr} 
    774807%------------------------------------------namsbc_apr---------------------------------------------------- 
     
    778811 
    779812The optional atmospheric pressure can be used to force ocean and ice dynamics 
    780 (\np{ln\_apr\_dyn}\forcode{ = .true.}, \textit{\ngn{namsbc}} namelist). 
    781 The input atmospheric forcing defined via \np{sn\_apr} structure (\textit{namsbc\_apr} namelist) 
     813(\np{ln\_apr\_dyn}\forcode{ = .true.}, \ngn{namsbc} namelist). 
     814The input atmospheric forcing defined via \np{sn\_apr} structure (\ngn{namsbc\_apr} namelist) 
    782815can be interpolated in time to the model time step, and even in space when the interpolation on-the-fly is used. 
    783816When used to force the dynamics, the atmospheric pressure is further transformed into 
     
    789822where $P_{atm}$ is the atmospheric pressure and $P_o$ a reference atmospheric pressure. 
    790823A value of $101,000~N/m^2$ is used unless \np{ln\_ref\_apr} is set to true. 
    791 In this case $P_o$ is set to the value of $P_{atm}$ averaged over the ocean domain, 
    792 \ie the mean value of $\eta_{ib}$ is kept to zero at all time step. 
     824In this case, $P_o$ is set to the value of $P_{atm}$ averaged over the ocean domain, 
     825\ie the mean value of $\eta_{ib}$ is kept to zero at all time steps. 
    793826 
    794827The gradient of $\eta_{ib}$ is added to the RHS of the ocean momentum equation (see \mdl{dynspg} for the ocean). 
    795828For sea-ice, the sea surface height, $\eta_m$, which is provided to the sea ice model is set to $\eta - \eta_{ib}$ 
    796829(see \mdl{sbcssr} module). 
    797 $\eta_{ib}$ can be set in the output. 
     830$\eta_{ib}$ can be written in the output. 
    798831This can simplify altimetry data and model comparison as 
    799832inverse barometer sea surface height is usually removed from these date prior to their distribution. 
     
    803836\np{ln\_apr\_obc}  might be set to true. 
    804837 
     838 
     839 
    805840% ================================================================ 
    806841%        Surface Tides Forcing 
    807842% ================================================================ 
    808 \section{Surface tides (\protect\mdl{sbctide})} 
     843\section[Surface tides (\textit{sbctide.F90})] 
     844{Surface tides (\protect\mdl{sbctide})} 
    809845\label{sec:SBC_tide} 
    810846 
     
    819855\[ 
    820856  % \label{eq:PE_dyn_tides} 
    821   \frac{\partial {\rm {\bf U}}_h }{\partial t}= ... 
     857  \frac{\partial {\mathrm {\mathbf U}}_h }{\partial t}= ... 
    822858  +g\nabla (\Pi_{eq} + \Pi_{sal}) 
    823859\] 
     
    827863The equilibrium tidal forcing is expressed as a sum over a subset of 
    828864constituents chosen from the set of available tidal constituents 
    829 defined in file \rou{SBC/tide.h90} (this comprises the tidal 
     865defined in file \textit{SBC/tide.h90} (this comprises the tidal 
    830866constituents \textit{M2, N2, 2N2, S2, K2, K1, O1, Q1, P1, M4, Mf, Mm, 
    831867  Msqm, Mtm, S1, MU2, NU2, L2}, and \textit{T2}). Individual 
     
    839875 
    840876The SAL term should in principle be computed online as it depends on 
    841 the model tidal prediction itself (see \citet{Arbic2004} for a 
     877the model tidal prediction itself (see \citet{arbic.garner.ea_DSR04} for a 
    842878discussion about the practical implementation of this term). 
    843879Nevertheless, the complex calculations involved would make this 
    844 computationally too expensive.  Here, two options are available: 
     880computationally too expensive. Here, two options are available: 
    845881$\Pi_{sal}$ generated by an external model can be read in 
    846882(\np{ln\_read\_load=.true.}), or a ``scalar approximation'' can be 
     
    854890\forcode{.false.} removes the SAL contribution. 
    855891 
     892 
     893 
    856894% ================================================================ 
    857895%        River runoffs 
    858896% ================================================================ 
    859 \section{River runoffs (\protect\mdl{sbcrnf})} 
     897\section[River runoffs (\textit{sbcrnf.F90})] 
     898{River runoffs (\protect\mdl{sbcrnf})} 
    860899\label{sec:SBC_rnf} 
    861900%------------------------------------------namsbc_rnf---------------------------------------------------- 
     
    871910%coastal modelling and becomes more and more often open ocean and climate modelling  
    872911%\footnote{At least a top cells thickness of 1~meter and a 3 hours forcing frequency are 
    873 %required to properly represent the diurnal cycle \citep{Bernie_al_JC05}. see also \autoref{fig:SBC_dcy}.}. 
     912%required to properly represent the diurnal cycle \citep{bernie.woolnough.ea_JC05}. see also \autoref{fig:SBC_dcy}.}. 
    874913 
    875914 
     
    892931\footnote{ 
    893932  At least a top cells thickness of 1~meter and a 3 hours forcing frequency are required to 
    894   properly represent the diurnal cycle \citep{Bernie_al_JC05}. 
     933  properly represent the diurnal cycle \citep{bernie.woolnough.ea_JC05}. 
    895934  see also \autoref{fig:SBC_dcy}.}. 
    896935 
     
    935974As such the volume of water does not change, but the water is diluted. 
    936975 
    937 For the non-linear free surface case (\key{vvl}), no flux is allowed through the surface. 
     976For the non-linear free surface case, no flux is allowed through the surface. 
    938977Instead in the surface box (as well as water moving up from the boxes below) a volume of runoff water is added with 
    939978no corresponding heat and salt addition and so as happens in the lower boxes there is a dilution effect. 
     
    9781017%To do this we need to treat evaporation/precipitation fluxes and river runoff differently in the tra_sbc module.  We decided to separate them throughout the code, so that the variable emp represented solely evaporation minus precipitation fluxes, and a new 2d variable rnf was added which represents the volume flux of river runoff (in kg/m2s to remain consistent with emp).  This meant many uses of emp and emps needed to be changed, a list of all modules which use emp or emps and the changes made are below: 
    9791018 
    980 %} 
     1019 
     1020 
    9811021% ================================================================ 
    9821022%        Ice shelf melting 
    9831023% ================================================================ 
    984 \section{Ice shelf melting (\protect\mdl{sbcisf})} 
     1024\section[Ice shelf melting (\textit{sbcisf.F90})] 
     1025{Ice shelf melting (\protect\mdl{sbcisf})} 
    9851026\label{sec:SBC_isf} 
    9861027%------------------------------------------namsbc_isf---------------------------------------------------- 
     
    9881029\nlst{namsbc_isf} 
    9891030%-------------------------------------------------------------------------------------------------------- 
     1031 
    9901032The namelist variable in \ngn{namsbc}, \np{nn\_isf}, controls the ice shelf representation. 
    991 Description and result of sensitivity test to \np{nn\_isf} are presented in \citet{Mathiot2017}.  
     1033Description and result of sensitivity test to \np{nn\_isf} are presented in \citet{mathiot.jenkins.ea_GMD17}.  
    9921034The different options are illustrated in \autoref{fig:SBC_isf}. 
    9931035 
    9941036\begin{description} 
    995 \item[\np{nn\_isf}\forcode{ = 1}]: 
     1037 
     1038  \item[\np{nn\_isf}\forcode{ = 1}]: 
    9961039  The ice shelf cavity is represented (\np{ln\_isfcav}\forcode{ = .true.} needed). 
    9971040  The fwf and heat flux are depending of the local water properties. 
     1041   
    9981042  Two different bulk formulae are available: 
    9991043 
     
    10011045   \item[\np{nn\_isfblk}\forcode{ = 1}]: 
    10021046     The melt rate is based on a balance between the upward ocean heat flux and 
    1003      the latent heat flux at the ice shelf base. A complete description is available in \citet{Hunter2006}. 
     1047     the latent heat flux at the ice shelf base. A complete description is available in \citet{hunter_rpt06}. 
    10041048   \item[\np{nn\_isfblk}\forcode{ = 2}]: 
    10051049     The melt rate and the heat flux are based on a 3 equations formulation 
    10061050     (a heat flux budget at the ice base, a salt flux budget at the ice base and a linearised freezing point temperature equation).  
    1007      A complete description is available in \citet{Jenkins1991}. 
     1051     A complete description is available in \citet{jenkins_JGR91}. 
    10081052   \end{description} 
    10091053 
    1010      Temperature and salinity used to compute the melt are the average temperature in the top boundary layer \citet{Losch2008}.  
     1054     Temperature and salinity used to compute the melt are the average temperature in the top boundary layer \citet{losch_JGR08}.  
    10111055     Its thickness is defined by \np{rn\_hisf\_tbl}. 
    10121056     The fluxes and friction velocity are computed using the mean temperature, salinity and velocity in the the first \np{rn\_hisf\_tbl} m. 
     
    10381082\] 
    10391083     where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters). 
    1040      See \citet{Jenkins2010} for all the details on this formulation. It is the recommended formulation for realistic application. 
     1084     See \citet{jenkins.nicholls.ea_JPO10} for all the details on this formulation. It is the recommended formulation for realistic application. 
    10411085   \item[\np{nn\_gammablk}\forcode{ = 2}]: 
    10421086     The salt and heat exchange coefficients are velocity and stability dependent and defined as: 
     
    10471091     $\Gamma_{Turb}$ the contribution of the ocean stability and 
    10481092     $\Gamma^{T,S}_{Mole}$ the contribution of the molecular diffusion. 
    1049      See \citet{Holland1999} for all the details on this formulation.  
     1093     See \citet{holland.jenkins_JPO99} for all the details on this formulation.  
    10501094     This formulation has not been extensively tested in NEMO (not recommended). 
    10511095   \end{description} 
    1052  \item[\np{nn\_isf}\forcode{ = 2}]: 
     1096  \item[\np{nn\_isf}\forcode{ = 2}]: 
    10531097   The ice shelf cavity is not represented. 
    1054    The fwf and heat flux are computed using the \citet{Beckmann2003} parameterisation of isf melting. 
     1098   The fwf and heat flux are computed using the \citet{beckmann.goosse_OM03} parameterisation of isf melting. 
    10551099   The fluxes are distributed along the ice shelf edge between the depth of the average grounding line (GL) 
    10561100   (\np{sn\_depmax\_isf}) and the base of the ice shelf along the calving front 
    10571101   (\np{sn\_depmin\_isf}) as in (\np{nn\_isf}\forcode{ = 3}). 
    10581102   The effective melting length (\np{sn\_Leff\_isf}) is read from a file. 
    1059  \item[\np{nn\_isf}\forcode{ = 3}]: 
     1103  \item[\np{nn\_isf}\forcode{ = 3}]: 
    10601104   The ice shelf cavity is not represented. 
    10611105   The fwf (\np{sn\_rnfisf}) is prescribed and distributed along the ice shelf edge between 
     
    10631107   the base of the ice shelf along the calving front (\np{sn\_depmin\_isf}). 
    10641108   The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$. 
    1065  \item[\np{nn\_isf}\forcode{ = 4}]: 
     1109  \item[\np{nn\_isf}\forcode{ = 4}]: 
    10661110   The ice shelf cavity is opened (\np{ln\_isfcav}\forcode{ = .true.} needed). 
    10671111   However, the fwf is not computed but specified from file \np{sn\_fwfisf}). 
     
    10891133\begin{figure}[!t] 
    10901134  \begin{center} 
    1091     \includegraphics[width=0.8\textwidth]{Fig_SBC_isf} 
     1135    \includegraphics[width=\textwidth]{Fig_SBC_isf} 
    10921136    \caption{ 
    10931137      \protect\label{fig:SBC_isf} 
     
    10981142%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    10991143 
     1144 
     1145 
     1146% ================================================================ 
     1147%        Ice sheet coupling 
     1148% ================================================================ 
    11001149\section{Ice sheet coupling} 
    11011150\label{sec:SBC_iscpl} 
     
    11041153\nlst{namsbc_iscpl} 
    11051154%-------------------------------------------------------------------------------------------------------- 
     1155 
    11061156Ice sheet/ocean coupling is done through file exchange at the restart step. 
    11071157At each restart step: 
     1158 
    11081159\begin{description} 
    11091160\item[Step 1]: the ice sheet model send a new bathymetry and ice shelf draft netcdf file. 
     
    11171168potentially some new wet/dry cells due to the ice sheet dynamics/thermodynamics. 
    11181169The wetting and drying scheme applied on the restart is very simple and described below for the 6 different possible cases: 
     1170 
    11191171\begin{description} 
    11201172\item[Thin a cell down]: 
     
    11551207The corrective increment is apply into the cell itself (if it is a wet cell), the neigbouring cells or the closest wet cell (if the cell is now dry). 
    11561208 
    1157 % 
     1209 
     1210 
    11581211% ================================================================ 
    11591212%        Handling of icebergs 
     
    11661219%------------------------------------------------------------------------------------------------------------- 
    11671220 
    1168 Icebergs are modelled as lagrangian particles in NEMO \citep{Marsh_GMD2015}. 
    1169 Their physical behaviour is controlled by equations as described in \citet{Martin_Adcroft_OM10} ). 
     1221Icebergs are modelled as lagrangian particles in NEMO \citep{marsh.ivchenko.ea_GMD15}. 
     1222Their physical behaviour is controlled by equations as described in \citet{martin.adcroft_OM10} ). 
    11701223(Note that the authors kindly provided a copy of their code to act as a basis for implementation in NEMO). 
    11711224Icebergs are initially spawned into one of ten classes which have specific mass and thickness as 
     
    11861239  the geographical box: lonmin,lonmax,latmin,latmax 
    11871240\item[\np{nn\_test\_icebergs}\forcode{ = -1}] 
    1188   In this scheme the model reads a calving file supplied in the \np{sn\_icb} parameter. 
     1241  In this scheme, the model reads a calving file supplied in the \np{sn\_icb} parameter. 
    11891242  This should be a file with a field on the configuration grid (typically ORCA) 
    11901243  representing ice accumulation rate at each model point. 
     
    12241277since its trajectory data may be spread across multiple files. 
    12251278 
    1226 % ------------------------------------------------------------------------------------------------------------- 
     1279 
     1280 
     1281% ============================================================================================================= 
    12271282%        Interactions with waves (sbcwave.F90, ln_wave) 
    1228 % ------------------------------------------------------------------------------------------------------------- 
    1229 \section{Interactions with waves (\protect\mdl{sbcwave}, \protect\np{ln\_wave})} 
     1283% ============================================================================================================= 
     1284\section[Interactions with waves (\textit{sbcwave.F90}, \texttt{ln\_wave})] 
     1285{Interactions with waves (\protect\mdl{sbcwave}, \protect\np{ln\_wave})} 
    12301286\label{sec:SBC_wave} 
    12311287%------------------------------------------namsbc_wave-------------------------------------------------------- 
     
    12411297 
    12421298Physical processes related to ocean surface waves can be accounted by setting the logical variable  
    1243 \np{ln\_wave}\forcode{= .true.} in \ngn{namsbc} namelist. In addition, specific flags accounting for  
    1244 different porcesses should be activated as explained in the following sections. 
     1299\np{ln\_wave} \forcode{= .true.} in \ngn{namsbc} namelist. In addition, specific flags accounting for  
     1300different processes should be activated as explained in the following sections. 
    12451301 
    12461302Wave fields can be provided either in forced or coupled mode: 
     
    12541310 
    12551311 
    1256 % ================================================================ 
     1312% ---------------------------------------------------------------- 
    12571313% Neutral drag coefficient from wave model (ln_cdgw) 
    12581314 
    1259 % ================================================================ 
    1260 \subsection{Neutral drag coefficient from wave model (\protect\np{ln\_cdgw})} 
     1315% ---------------------------------------------------------------- 
     1316\subsection[Neutral drag coefficient from wave model (\texttt{ln\_cdgw})] 
     1317{Neutral drag coefficient from wave model (\protect\np{ln\_cdgw})} 
    12611318\label{subsec:SBC_wave_cdgw} 
    12621319 
    12631320The neutral surface drag coefficient provided from an external data source (\ie a wave model),  
    12641321can be used by setting the logical variable \np{ln\_cdgw} \forcode{= .true.} in \ngn{namsbc} namelist.  
    1265 Then using the routine \rou{turb\_ncar} and starting from the neutral drag coefficent provided,  
     1322Then using the routine \rou{sbcblk\_algo\_ncar} and starting from the neutral drag coefficent provided,  
    12661323the drag coefficient is computed according to the stable/unstable conditions of the  
    1267 air-sea interface following \citet{Large_Yeager_Rep04}.  
    1268  
    1269  
    1270 % ================================================================ 
     1324air-sea interface following \citet{large.yeager_rpt04}.  
     1325 
     1326 
     1327% ---------------------------------------------------------------- 
    12711328% 3D Stokes Drift (ln_sdw, nn_sdrift) 
    1272 % ================================================================ 
    1273 \subsection{3D Stokes Drift (\protect\np{ln\_sdw, nn\_sdrift})} 
     1329% ---------------------------------------------------------------- 
     1330\subsection[3D Stokes Drift (\texttt{ln\_sdw}, \texttt{nn\_sdrift})] 
     1331{3D Stokes Drift (\protect\np{ln\_sdw, nn\_sdrift})} 
    12741332\label{subsec:SBC_wave_sdw} 
    12751333 
    1276 The Stokes drift is a wave driven mechanism of mass and momentum transport \citep{Stokes_1847}.  
     1334The Stokes drift is a wave driven mechanism of mass and momentum transport \citep{stokes_ibk09}.  
    12771335It is defined as the difference between the average velocity of a fluid parcel (Lagrangian velocity)  
    12781336and the current measured at a fixed point (Eulerian velocity).  
    12791337As waves travel, the water particles that make up the waves travel in orbital motions but  
    12801338without a closed path. Their movement is enhanced at the top of the orbit and slowed slightly  
    1281 at the bottom so the result is a net forward motion of water particles, referred to as the Stokes drift.  
     1339at the bottom, so the result is a net forward motion of water particles, referred to as the Stokes drift.  
    12821340An accurate evaluation of the Stokes drift and the inclusion of related processes may lead to improved  
    1283 representation of surface physics in ocean general circulation models. 
     1341representation of surface physics in ocean general circulation models. %GS: reference needed 
    12841342The Stokes drift velocity $\mathbf{U}_{st}$ in deep water can be computed from the wave spectrum and may be written as:  
    12851343 
     
    12961354$k=\frac{2\pi}{\lambda}$ (being $\lambda$ the wavelength). \\ 
    12971355 
    1298 In order to evaluate the Stokes drift in a realistic ocean wave field the wave spectral shape is required  
     1356In order to evaluate the Stokes drift in a realistic ocean wave field, the wave spectral shape is required  
    12991357and its computation quickly becomes expensive as the 2D spectrum must be integrated for each vertical level.  
    13001358To simplify, it is customary to use approximations to the full Stokes profile. 
     
    13071365\begin{description} 
    13081366\item[\np{nn\_sdrift} = 0]: exponential integral profile parameterization proposed by  
    1309 \citet{Breivik_al_JPO2014}: 
     1367\citet{breivik.janssen.ea_JPO14}: 
    13101368 
    13111369\[ 
     
    13261384 
    13271385\item[\np{nn\_sdrift} = 1]: velocity profile based on the Phillips spectrum which is considered to be a  
    1328 reasonable estimate of the part of the spectrum most contributing to the Stokes drift velocity near the surface 
    1329 \citep{Breivik_al_OM2016}: 
     1386reasonable estimate of the part of the spectrum mostly contributing to the Stokes drift velocity near the surface 
     1387\citep{breivik.bidlot.ea_OM16}: 
    13301388 
    13311389\[ 
     
    13641422 
    13651423 
    1366 % ================================================================ 
     1424% ---------------------------------------------------------------- 
    13671425% Stokes-Coriolis term (ln_stcor) 
    1368 % ================================================================ 
    1369 \subsection{Stokes-Coriolis term (\protect\np{ln\_stcor})} 
     1426% ---------------------------------------------------------------- 
     1427\subsection[Stokes-Coriolis term (\texttt{ln\_stcor})] 
     1428{Stokes-Coriolis term (\protect\np{ln\_stcor})} 
    13701429\label{subsec:SBC_wave_stcor} 
    13711430 
     
    13781437 
    13791438 
    1380 % ================================================================ 
     1439% ---------------------------------------------------------------- 
    13811440% Waves modified stress (ln_tauwoc, ln_tauw) 
    1382 % ================================================================ 
    1383 \subsection{Wave modified sress (\protect\np{ln\_tauwoc, ln\_tauw})}  
     1441% ---------------------------------------------------------------- 
     1442\subsection[Wave modified stress (\texttt{ln\_tauwoc}, \texttt{ln\_tauw})] 
     1443{Wave modified sress (\protect\np{ln\_tauwoc, ln\_tauw})} 
    13841444\label{subsec:SBC_wave_tauw} 
    13851445 
    13861446The surface stress felt by the ocean is the atmospheric stress minus the net stress going  
    1387 into the waves \citep{Janssen_al_TM13}. Therefore, when waves are growing, momentum and energy is spent and is not  
     1447into the waves \citep{janssen.breivik.ea_rpt13}. Therefore, when waves are growing, momentum and energy is spent and is not  
    13881448available for forcing the mean circulation, while in the opposite case of a decaying sea  
    1389 state more momentum is available for forcing the ocean.  
    1390 Only when the sea state is in equilibrium the ocean is forced by the atmospheric stress,  
    1391 but in practice an equilibrium sea state is a fairly rare event.  
     1449state, more momentum is available for forcing the ocean.  
     1450Only when the sea state is in equilibrium, the ocean is forced by the atmospheric stress,  
     1451but in practice, an equilibrium sea state is a fairly rare event.  
    13921452So the atmospheric stress felt by the ocean circulation $\tau_{oc,a}$ can be expressed as:  
    13931453 
     
    14191479 
    14201480 
     1481 
    14211482% ================================================================ 
    14221483% Miscellanea options 
     
    14251486\label{sec:SBC_misc} 
    14261487 
     1488 
    14271489% ------------------------------------------------------------------------------------------------------------- 
    14281490%        Diurnal cycle 
    14291491% ------------------------------------------------------------------------------------------------------------- 
    1430 \subsection{Diurnal cycle (\protect\mdl{sbcdcy})} 
     1492\subsection[Diurnal cycle (\textit{sbcdcy.F90})] 
     1493{Diurnal cycle (\protect\mdl{sbcdcy})} 
    14311494\label{subsec:SBC_dcy} 
    1432 %------------------------------------------namsbc_rnf---------------------------------------------------- 
     1495%------------------------------------------namsbc------------------------------------------------------------- 
    14331496% 
    14341497\nlst{namsbc}  
     
    14381501\begin{figure}[!t] 
    14391502  \begin{center} 
    1440     \includegraphics[width=0.8\textwidth]{Fig_SBC_diurnal} 
     1503    \includegraphics[width=\textwidth]{Fig_SBC_diurnal} 
    14411504    \caption{ 
    14421505      \protect\label{fig:SBC_diurnal} 
     
    14451508      the mean value of the analytical cycle (blue line) over a time step, 
    14461509      not as the mid time step value of the analytically cycle (red square). 
    1447       From \citet{Bernie_al_CD07}. 
     1510      From \citet{bernie.guilyardi.ea_CD07}. 
    14481511    } 
    14491512  \end{center} 
     
    14511514%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    14521515 
    1453 \cite{Bernie_al_JC05} have shown that to capture 90$\%$ of the diurnal variability of SST requires a vertical resolution in upper ocean of 1~m or better and a temporal resolution of the surface fluxes of 3~h or less. 
    1454 Unfortunately high frequency forcing fields are rare, not to say inexistent. 
    1455 Nevertheless, it is possible to obtain a reasonable diurnal cycle of the SST knowning only short wave flux (SWF) at 
    1456 high frequency \citep{Bernie_al_CD07}. 
     1516\cite{bernie.woolnough.ea_JC05} have shown that to capture 90$\%$ of the diurnal variability of SST requires a vertical resolution in upper ocean of 1~m or better and a temporal resolution of the surface fluxes of 3~h or less. 
     1517%Unfortunately high frequency forcing fields are rare, not to say inexistent. GS: not true anymore ! 
     1518Nevertheless, it is possible to obtain a reasonable diurnal cycle of the SST knowning only short wave flux (SWF) at high frequency \citep{bernie.guilyardi.ea_CD07}. 
    14571519Furthermore, only the knowledge of daily mean value of SWF is needed, 
    14581520as higher frequency variations can be reconstructed from them, 
    14591521assuming that the diurnal cycle of SWF is a scaling of the top of the atmosphere diurnal cycle of incident SWF. 
    1460 The \cite{Bernie_al_CD07} reconstruction algorithm is available in \NEMO by 
     1522The \cite{bernie.guilyardi.ea_CD07} reconstruction algorithm is available in \NEMO by 
    14611523setting \np{ln\_dm2dc}\forcode{ = .true.} (a \textit{\ngn{namsbc}} namelist variable) when 
    1462 using CORE bulk formulea (\np{ln\_blk\_core}\forcode{ = .true.}) or 
     1524using a bulk formulation (\np{ln\_blk}\forcode{ = .true.}) or 
    14631525the flux formulation (\np{ln\_flx}\forcode{ = .true.}). 
    14641526The reconstruction is performed in the \mdl{sbcdcy} module. 
    1465 The detail of the algoritm used can be found in the appendix~A of \cite{Bernie_al_CD07}. 
    1466 The algorithm preserve the daily mean incoming SWF as the reconstructed SWF at 
     1527The detail of the algoritm used can be found in the appendix~A of \cite{bernie.guilyardi.ea_CD07}. 
     1528The algorithm preserves the daily mean incoming SWF as the reconstructed SWF at 
    14671529a given time step is the mean value of the analytical cycle over this time step (\autoref{fig:SBC_diurnal}). 
    14681530The use of diurnal cycle reconstruction requires the input SWF to be daily 
    1469 (\ie a frequency of 24 and a time interpolation set to true in \np{sn\_qsr} namelist parameter). 
    1470 Furthermore, it is recommended to have a least 8 surface module time step per day, 
     1531(\ie a frequency of 24 hours and a time interpolation set to true in \np{sn\_qsr} namelist parameter). 
     1532Furthermore, it is recommended to have a least 8 surface module time steps per day, 
    14711533that is  $\rdt \ nn\_fsbc < 10,800~s = 3~h$. 
    14721534An example of recontructed SWF is given in \autoref{fig:SBC_dcy} for a 12 reconstructed diurnal cycle, 
     
    14761538\begin{figure}[!t] 
    14771539  \begin{center} 
    1478     \includegraphics[width=0.7\textwidth]{Fig_SBC_dcy} 
     1540    \includegraphics[width=\textwidth]{Fig_SBC_dcy} 
    14791541    \caption{ 
    14801542      \protect\label{fig:SBC_dcy} 
     
    14911553an inconsistency between the scale of the vertical resolution and the forcing acting on that scale. 
    14921554 
     1555 
    14931556% ------------------------------------------------------------------------------------------------------------- 
    14941557%        Rotation of vector pairs onto the model grid directions 
     
    14971560\label{subsec:SBC_rotation} 
    14981561 
    1499 When using a flux (\np{ln\_flx}\forcode{ = .true.}) or 
    1500 bulk (\np{ln\_clio}\forcode{ = .true.} or \np{ln\_core}\forcode{ = .true.}) formulation, 
     1562When using a flux (\np{ln\_flx}\forcode{ = .true.}) or bulk (\np{ln\_blk}\forcode{ = .true.}) formulation, 
    15011563pairs of vector components can be rotated from east-north directions onto the local grid directions. 
    15021564This is particularly useful when interpolation on the fly is used since here any vectors are likely to 
    15031565be defined relative to a rectilinear grid. 
    1504 To activate this option a non-empty string is supplied in the rotation pair column of the relevant namelist. 
     1566To activate this option, a non-empty string is supplied in the rotation pair column of the relevant namelist. 
    15051567The eastward component must start with "U" and the northward component with "V".   
    15061568The remaining characters in the strings are used to identify which pair of components go together. 
     
    15111573The rot\_rep routine from the \mdl{geo2ocean} module is used to perform the rotation. 
    15121574 
     1575 
    15131576% ------------------------------------------------------------------------------------------------------------- 
    15141577%        Surface restoring to observed SST and/or SSS 
    15151578% ------------------------------------------------------------------------------------------------------------- 
    1516 \subsection{Surface restoring to observed SST and/or SSS (\protect\mdl{sbcssr})} 
     1579\subsection[Surface restoring to observed SST and/or SSS (\textit{sbcssr.F90})] 
     1580{Surface restoring to observed SST and/or SSS (\protect\mdl{sbcssr})} 
    15171581\label{subsec:SBC_ssr} 
    15181582%------------------------------------------namsbc_ssr---------------------------------------------------- 
     
    15211585%------------------------------------------------------------------------------------------------------------- 
    15221586 
    1523 IOptions are defined through the \ngn{namsbc\_ssr} namelist variables. 
     1587Options are defined through the \ngn{namsbc\_ssr} namelist variables. 
    15241588On forced mode using a flux formulation (\np{ln\_flx}\forcode{ = .true.}), 
    15251589a feedback term \emph{must} be added to the surface heat flux $Q_{ns}^o$: 
     
    15461610(observed, climatological or an atmospheric model product), 
    15471611\textit{SSS}$_{Obs}$ is a sea surface salinity 
    1548 (usually a time interpolation of the monthly mean Polar Hydrographic Climatology \citep{Steele2001}), 
     1612(usually a time interpolation of the monthly mean Polar Hydrographic Climatology \citep{steele.morley.ea_JC01}), 
    15491613$\left.S\right|_{k=1}$ is the model surface layer salinity and 
    15501614$\gamma_s$ is a negative feedback coefficient which is provided as a namelist parameter. 
    15511615Unlike heat flux, there is no physical justification for the feedback term in \autoref{eq:sbc_dmp_emp} as 
    1552 the atmosphere does not care about ocean surface salinity \citep{Madec1997}. 
     1616the atmosphere does not care about ocean surface salinity \citep{madec.delecluse_IWN97}. 
    15531617The SSS restoring term should be viewed as a flux correction on freshwater fluxes to 
    15541618reduce the uncertainties we have on the observed freshwater budget. 
     1619 
    15551620 
    15561621% ------------------------------------------------------------------------------------------------------------- 
     
    15781643  This prevents deep convection to occur when trying to reach the freezing point 
    15791644  (and so ice covered area condition) while the SSS is too large. 
    1580   This manner of managing sea-ice area, just by using si IF case, 
     1645  This manner of managing sea-ice area, just by using a IF case, 
    15811646  is usually referred as the \textit{ice-if} model. 
    15821647  It can be found in the \mdl{sbcice{\_}if} module. 
     
    15851650  This model computes the ice-ocean fluxes, 
    15861651  that are combined with the air-sea fluxes using the ice fraction of each model cell to 
    1587   provide the surface ocean fluxes. 
    1588   Note that the activation of a sea-ice model is is done by defining a CPP key (\key{lim3} or \key{cice}). 
     1652  provide the surface averaged ocean fluxes. 
     1653  Note that the activation of a sea-ice model is done by defining a CPP key (\key{si3} or \key{cice}). 
    15891654  The activation automatically overwrites the read value of nn{\_}ice to its appropriate value 
    1590   (\ie $2$ for LIM-3 or $3$ for CICE). 
     1655  (\ie $2$ for SI3 or $3$ for CICE). 
    15911656\end{description} 
    15921657 
    15931658% {Description of Ice-ocean interface to be added here or in LIM 2 and 3 doc ?} 
    1594  
    1595 \subsection{Interface to CICE (\protect\mdl{sbcice\_cice})} 
     1659%GS: ocean-ice (SI3) interface is not located in SBC directory anymore, so it should be included in SI3 doc 
     1660 
     1661 
     1662% ------------------------------------------------------------------------------------------------------------- 
     1663%        CICE-ocean Interface 
     1664% ------------------------------------------------------------------------------------------------------------- 
     1665\subsection[Interface to CICE (\textit{sbcice\_cice.F90})] 
     1666{Interface to CICE (\protect\mdl{sbcice\_cice})} 
    15961667\label{subsec:SBC_cice} 
    15971668 
    1598 It is now possible to couple a regional or global NEMO configuration (without AGRIF) 
     1669It is possible to couple a regional or global NEMO configuration (without AGRIF) 
    15991670to the CICE sea-ice model by using \key{cice}. 
    16001671The CICE code can be obtained from \href{http://oceans11.lanl.gov/trac/CICE/}{LANL} and 
     
    16031674and CICE CPP keys \textbf{ORCA\_GRID}, \textbf{CICE\_IN\_NEMO} and \textbf{coupled} should be used 
    16041675(seek advice from UKMO if necessary). 
    1605 Currently the code is only designed to work when using the CORE forcing option for NEMO 
     1676Currently, the code is only designed to work when using the NCAR forcing option for NEMO %GS: still true ? 
    16061677(with \textit{calc\_strair}\forcode{ = .true.} and \textit{calc\_Tsfc}\forcode{ = .true.} in the CICE name-list), 
    16071678or alternatively when NEMO is coupled to the HadGAM3 atmosphere model 
     
    16231694there is no sea ice. 
    16241695 
     1696 
    16251697% ------------------------------------------------------------------------------------------------------------- 
    16261698%        Freshwater budget control  
    16271699% ------------------------------------------------------------------------------------------------------------- 
    1628 \subsection{Freshwater budget control (\protect\mdl{sbcfwb})} 
     1700\subsection[Freshwater budget control (\textit{sbcfwb.F90})] 
     1701{Freshwater budget control (\protect\mdl{sbcfwb})} 
    16291702\label{subsec:SBC_fwb} 
    16301703 
    1631 For global ocean simulation it can be useful to introduce a control of the mean sea level in order to 
     1704For global ocean simulation, it can be useful to introduce a control of the mean sea level in order to 
    16321705prevent unrealistic drift of the sea surface height due to inaccuracy in the freshwater fluxes. 
    1633 In \NEMO, two way of controlling the the freshwater budget.  
     1706In \NEMO, two way of controlling the freshwater budget are proposed: 
     1707  
    16341708\begin{description} 
    16351709\item[\np{nn\_fwb}\forcode{ = 0}] 
     
    16381712\item[\np{nn\_fwb}\forcode{ = 1}] 
    16391713  global mean \textit{emp} set to zero at each model time step.  
    1640 %Note that with a sea-ice model, this technique only control the mean sea level with linear free surface (\key{vvl} not defined) and no mass flux between ocean and ice (as it is implemented in the current ice-ocean coupling).  
     1714  %GS: comment below still relevant ? 
     1715  %Note that with a sea-ice model, this technique only controls the mean sea level with linear free surface and no mass flux between ocean and ice (as it is implemented in the current ice-ocean coupling).  
    16411716\item[\np{nn\_fwb}\forcode{ = 2}] 
    16421717  freshwater budget is adjusted from the previous year annual mean budget which 
     
    16451720  the change in the mean sea level at January the first and saved in the \textit{EMPav.dat} file.  
    16461721\end{description} 
    1647  
    1648  
    16491722 
    16501723% Griffies doc: 
     
    16551728% The result of the normalization should be a global integrated zero net water input to the ocean-ice system over  
    16561729% a chosen time scale.  
    1657 %How often the normalization is done is a matter of choice. In mom4p1, we choose to do so at each model time step,  
     1730% How often the normalization is done is a matter of choice. In mom4p1, we choose to do so at each model time step,  
    16581731% so that there is always a zero net input of water to the ocean-ice system.  
    16591732% Others choose to normalize over an annual cycle, in which case the net imbalance over an annual cycle is used  
     
    16701743% in ocean-ice models.  
    16711744 
     1745 
    16721746\biblio 
    16731747 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_STO.tex

    r10442 r11422  
    88\label{chap:STO} 
    99 
    10 Authors: P.-A. Bouttier 
     10\minitoc 
    1111 
    12 \minitoc 
     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.1} & {\em C. Levy} & {\em 4.0.1 update}  \\ 
     18%    {\em 3.6} & {\em P.-A. Bouttier} & {\em initial version}  \\ 
     19% \end{tabular} 
     20% \end{figure} 
     21 
     22Authors: \\ 
     23C. Levy release 4.0.1 update \\ 
     24P.-A. Bouttier release 3.6 inital version 
    1325 
    1426\newpage 
    1527 
    16 The stochastic parametrization module aims to explicitly simulate uncertainties in the model. 
    17 More particularly, \cite{Brankart_OM2013} has shown that, 
    18 because of the nonlinearity of the seawater equation of state, unresolved scales represent a major source of 
    19 uncertainties in the computation of the large scale horizontal density gradient (from T/S large scale fields), 
    20 and that the impact of these uncertainties can be simulated by 
    21 random processes representing unresolved T/S fluctuations. 
     28As a result of the nonlinearity of the seawater equation of state, unresolved scales represent a major source of uncertainties in the computation of the large-scale horizontal density gradient from the large-scale temperature and salinity fields. Following  \cite{brankart_OM13}, the impact of these uncertainties can be simulated by random processes representing unresolved T/S fluctuations. The Stochastic Parametrization of EOS (STO) module implements this parametrization. 
    2229 
    23 The stochastic formulation of the equation of state can be written as: 
     30As detailed in \cite{brankart_OM13}, the stochastic formulation of the equation of state can be written as: 
    2431\begin{equation} 
    2532  \label{eq:eos_sto} 
     
    2734\end{equation} 
    2835where $p_o(z)$ is the reference pressure depending on the depth and, 
    29 $\Delta T_i$ and $\Delta S_i$ are a set of T/S perturbations defined as 
     36$\Delta T_i$ and $\Delta S_i$ (i=1,m) is a set of T/S perturbations defined as 
    3037the scalar product of the respective local T/S gradients with random walks $\mathbf{\xi}$: 
    3138\begin{equation} 
     
    3340  \Delta T_i = \mathbf{\xi}_i \cdot \nabla T \qquad \hbox{and} \qquad \Delta S_i = \mathbf{\xi}_i \cdot \nabla S 
    3441\end{equation} 
    35 $\mathbf{\xi}_i$ are produced by a first-order autoregressive processes (AR-1) with 
     42$\mathbf{\xi}_i$ are produced by a first-order autoregressive process (AR-1) with 
    3643a parametrized decorrelation time scale, and horizontal and vertical standard deviations $\sigma_s$. 
    3744$\mathbf{\xi}$ are uncorrelated over the horizontal and fully correlated along the vertical. 
     
    4148\label{sec:STO_the_details} 
    4249 
    43 The starting point of our implementation of stochastic parameterizations in NEMO is to observe that 
    44 many existing parameterizations are based on autoregressive processes, 
     50There are many existing parameterizations based on autoregressive processes, 
    4551which are used as a basic source of randomness to transform a deterministic model into a probabilistic model. 
    46 A generic approach is thus to add one single new module in NEMO, 
    47 generating processes with appropriate statistics to simulate each kind of uncertainty in the model 
    48 (see \cite{Brankart_al_GMD2015} for more details). 
     52The generic approach here is to a new STO module, 
     53generating processes features with appropriate statistics to simulate these uncertainties in the model 
     54(see \cite{brankart.candille.ea_GMD15} for more details). 
    4955 
    50 In practice, at every model grid point, 
     56In practice, at each model grid point, 
    5157independent Gaussian autoregressive processes~$\xi^{(i)},\,i=1,\ldots,m$ are first generated using 
    5258the same basic equation: 
     
    101107\noindent 
    102108In this way, higher order processes can be easily generated recursively using the same piece of code implementing 
    103 (\autoref{eq:autoreg}), and using succesively processes from order $0$ to~$n-1$ as~$w^{(i)}$. 
    104 The parameters in (\autoref{eq:ord2}) are computed so that this recursive application of 
    105 (\autoref{eq:autoreg}) leads to processes with the required standard deviation and correlation timescale, 
     109\autoref{eq:autoreg}, and using successive processes from order $0$ to~$n-1$ as~$w^{(i)}$. 
     110The parameters in \autoref{eq:ord2} are computed so that this recursive application of 
     111\autoref{eq:autoreg} leads to processes with the required standard deviation and correlation timescale, 
    106112with the additional condition that the $n-1$ first derivatives of the autocorrelation function are equal to 
    107 zero at~$t=0$, so that the resulting processes become smoother and smoother as $n$ is increased. 
     113zero at~$t=0$, so that the resulting processes become smoother and smoother as $n$ increases. 
    108114 
    109115Overall, this method provides quite a simple and generic way of generating a wide class of stochastic processes. 
    110116However, this also means that new model parameters are needed to specify each of these stochastic processes. 
    111 As in any parameterization of lacking physics, a very important issues then to tune these new parameters using 
     117As in any parameterization, the main issue is to tune the parameters using 
    112118either first principles, model simulations, or real-world observations. 
     119The parameters are set by default as described in \cite{brankart_OM13}, which has been shown in the paper 
     120to give good results for a global low resolution (2°) NEMO configuration. where this parametrization produces a major effect on the average large-scale circulation, especilally in regions of intense mesoscale activity. 
     121The set of parameters will need further investigation to find appropriate values 
     122for any other configuration or resolution of the model. 
    113123 
    114124\section{Implementation details} 
    115125\label{sec:STO_thech_details} 
    116126 
    117 %---------------------------------------namsbc-------------------------------------------------- 
    118127 
    119 \nlst{namsto} 
    120 %-------------------------------------------------------------------------------------------------------------- 
     128The code implementing stochastic parametrisation is located in the src/OCE/STO directory. 
     129It contains three modules :  
     130% \begin{description} 
    121131 
    122 The computer code implementing stochastic parametrisations can be found in the STO directory. 
    123 It involves three modules :  
    124 \begin{description} 
    125 \item[\mdl{stopar}:] 
    126   define the Stochastic parameters and their time evolution. 
    127 \item[\mdl{storng}:] 
    128   a random number generator based on (and includes) the 64-bit KISS (Keep It Simple Stupid) random number generator 
    129   distributed by George Marsaglia 
    130   (see \href{https://groups.google.com/forum/#!searchin/comp.lang.fortran/64-bit$20KISS$20RNGs}{here}) 
    131 \item[\mdl{stopts}:] 
    132   stochastic parametrisation associated with the non-linearity of the equation of seawater, 
    133   implementing \autoref{eq:sto_pert} and specific piece of code in 
    134   the equation of state implementing \autoref{eq:eos_sto}. 
    135 \end{description} 
     132\mdl{stopar} : define the Stochastic parameters and their time evolution 
    136133 
    137 The \mdl{stopar} module has 3 public routines to be called by the model (in our case, NEMO): 
     134\mdl{storng} : random number generator based on and including the 64-bit KISS (Keep It Simple Stupid) random number generator distributed by George Marsaglia 
    138135 
    139 The first routine (\rou{sto\_par}) is a direct implementation of (\autoref{eq:autoreg}), 
     136\mdl{stopts} : stochastic parametrisation associated with the non-linearity of the equation of 
     137 seawater, implementing \autoref{eq:sto_pert} so as specifics in the equation of state 
     138 implementing \autoref{eq:eos_sto}. 
     139% \end{description} 
     140 
     141The \mdl{stopar} module includes three public routines called in the model: 
     142 
     143(\rou{sto\_par}) is a direct implementation of \autoref{eq:autoreg}, 
    140144applied at each model grid point (in 2D or 3D), and called at each model time step ($k$) to 
    141145update every autoregressive process ($i=1,\ldots,m$). 
     
    143147to introduce a spatial correlation between the stochastic processes. 
    144148 
    145 The second routine (\rou{sto\_par\_init}) is an initialization routine mainly dedicated to 
    146 the computation of parameters $a^{(i)}, b^{(i)}, c^{(i)}$ for each autoregressive process, 
     149(\rou{sto\_par\_init}) is the initialization routine computing 
     150the values $a^{(i)}, b^{(i)}, c^{(i)}$ for each autoregressive process, 
    147151as a function of the statistical properties required by the model user 
    148152(mean, standard deviation, time correlation, order of the process,\ldots).  
     153This routine also includes the initialization (seeding) of the random number generator. 
    149154 
    150 Parameters for the processes can be specified through the following \ngn{namsto} namelist parameters: 
     155(\rou{sto\_rst\_write}) writes a restart file 
     156(which suffix name is given by \np{cn\_storst\_out} namelist parameter) containing the current value of 
     157all autoregressive processes to allow creating the file needed for a restart. 
     158This restart file also contains the current state of the random number generator. 
     159When \np{ln\_rststo} is set to \forcode{.true.}), 
     160the restart file (which suffix name is given by \np{cn\_storst\_in} namelist parameter) is read by 
     161the initialization routine (\rou{sto\_par\_init}). 
     162The simulation will continue exactly as if it was not interrupted only 
     163when \np{ln\_rstseed} is set to \forcode{.true.}, 
     164\ie when the state of the random number generator is read in the restart file.\\ 
     165 
     166The implementation includes the basics for a few possible stochastic parametrisations including equation of state, lateral diffusion, horizontal pressure gradient, ice strength, trend, tracers dynamics. As for this release, only the stochastic parametrisation of equation of state is fully available and tested. \\  
     167 
     168Options and parameters \\ 
     169 
     170The \np{ln\_sto\_eos} namelist variable activates stochastic parametrisation of equation of state. By default it set to \forcode{.false.}) and not active. 
     171The set of parameters is available in \ngn{namsto} namelist(only the subset for equation of state stochastic parametrisation is listed below): 
     172%---------------------------------------namsto-------------------------------------------------- 
     173 
     174\nlst{namsto} 
     175%-------------------------------------------------------------------------------------------------------------- 
     176 
     177The variables of stochastic paramtetrisation itself (based on the global 2° experiments as in \cite{brankart_OM13} are: 
    151178\begin{description} 
    152179\item[\np{nn\_sto\_eos}:]   number of independent random walks 
    153 \item[\np{rn\_eos\_stdxy}:] random walk horz. standard deviation (in grid points) 
    154 \item[\np{rn\_eos\_stdz}:]  random walk vert. standard deviation (in grid points) 
     180\item[\np{rn\_eos\_stdxy}:] random walk horizontal standard deviation (in grid points) 
     181\item[\np{rn\_eos\_stdz}:]  random walk vertical standard deviation (in grid points) 
    155182\item[\np{rn\_eos\_tcor}:]  random walk time correlation (in timesteps) 
    156183\item[\np{nn\_eos\_ord}:]   order of autoregressive processes 
     
    158185\item[\np{rn\_eos\_lim}:]   limitation factor (default = 3.0) 
    159186\end{description} 
    160 This routine also includes the initialization (seeding) of the random number generator. 
    161187 
    162 The third routine (\rou{sto\_rst\_write}) writes a restart file 
    163 (which suffix name is given by \np{cn\_storst\_out} namelist parameter) containing the current value of 
    164 all autoregressive processes to allow restarting a simulation from where it has been interrupted. 
    165 This file also contains the current state of the random number generator. 
    166 When \np{ln\_rststo} is set to \forcode{.true.}), 
    167 the restart file (which suffix name is given by \np{cn\_storst\_in} namelist parameter) is read by 
    168 the initialization routine (\rou{sto\_par\_init}). 
    169 The simulation will continue exactly as if it was not interrupted only 
    170 when \np{ln\_rstseed} is set to \forcode{.true.}, 
    171 \ie when the state of the random number generator is read in the restart file. 
    172  
     188The first four parameters define the stochastic part of equation of state. 
    173189\biblio 
    174190 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_TRA.tex

    r10544 r11422  
    5555 
    5656The user has the option of extracting each tendency term on the RHS of the tracer equation for output 
    57 (\np{ln\_tra\_trd} or \np{ln\_tra\_mxl}~\forcode{= .true.}), as described in \autoref{chap:DIA}. 
     57(\np{ln\_tra\_trd} or \np{ln\_tra\_mxl}\forcode{ = .true.}), as described in \autoref{chap:DIA}. 
    5858 
    5959% ================================================================ 
    6060% Tracer Advection 
    6161% ================================================================ 
    62 \section{Tracer advection (\protect\mdl{traadv})} 
     62\section[Tracer advection (\textit{traadv.F90})] 
     63{Tracer advection (\protect\mdl{traadv})} 
    6364\label{sec:TRA_adv} 
    6465%------------------------------------------namtra_adv----------------------------------------------------- 
     
    8182Indeed, it is obtained by using the following equality: $\nabla \cdot (\vect U \, T) = \vect U \cdot \nabla T$ which 
    8283results from the use of the continuity equation, $\partial_t e_3 + e_3 \; \nabla \cdot \vect U = 0$ 
    83 (which reduces to $\nabla \cdot \vect U = 0$ in linear free surface, \ie \np{ln\_linssh}~\forcode{= .true.}). 
     84(which reduces to $\nabla \cdot \vect U = 0$ in linear free surface, \ie \np{ln\_linssh}\forcode{ = .true.}). 
    8485Therefore it is of paramount importance to design the discrete analogue of the advection tendency so that 
    8586it is consistent with the continuity equation in order to enforce the conservation properties of 
     
    9091\begin{figure}[!t] 
    9192  \begin{center} 
    92     \includegraphics[]{Fig_adv_scheme} 
     93    \includegraphics[width=\textwidth]{Fig_adv_scheme} 
    9394    \caption{ 
    9495      \protect\label{fig:adv_scheme} 
     
    119120\begin{description} 
    120121\item[linear free surface:] 
    121   (\np{ln\_linssh}~\forcode{= .true.}) 
     122  (\np{ln\_linssh}\forcode{ = .true.}) 
    122123  the first level thickness is constant in time: 
    123124  the vertical boundary condition is applied at the fixed surface $z = 0$ rather than on 
     
    127128  the first level tracer value. 
    128129\item[non-linear free surface:] 
    129   (\np{ln\_linssh}~\forcode{= .false.}) 
     130  (\np{ln\_linssh}\forcode{ = .false.}) 
    130131  convergence/divergence in the first ocean level moves the free surface up/down. 
    131132  There is no tracer advection through it so that the advective fluxes through the surface are also zero. 
     
    136137Nevertheless, in the latter case, it is achieved to a good approximation since 
    137138the non-conservative term is the product of the time derivative of the tracer and the free surface height, 
    138 two quantities that are not correlated \citep{Roullet_Madec_JGR00, Griffies_al_MWR01, Campin2004}. 
    139  
    140 The velocity field that appears in (\autoref{eq:tra_adv} and \autoref{eq:tra_adv_zco}) is 
     139two quantities that are not correlated \citep{roullet.madec_JGR00, griffies.pacanowski.ea_MWR01, campin.adcroft.ea_OM04}. 
     140 
     141The velocity field that appears in (\autoref{eq:tra_adv} and \autoref{eq:tra_adv_zco?}) is 
    141142the centred (\textit{now}) \textit{effective} ocean velocity, \ie the \textit{eulerian} velocity 
    142143(see \autoref{chap:DYN}) plus the eddy induced velocity (\textit{eiv}) and/or 
     
    183184%        2nd and 4th order centred schemes 
    184185% ------------------------------------------------------------------------------------------------------------- 
    185 \subsection{CEN: Centred scheme (\protect\np{ln\_traadv\_cen}~\forcode{= .true.})} 
     186\subsection[CEN: Centred scheme (\forcode{ln_traadv_cen = .true.})] 
     187{CEN: Centred scheme (\protect\np{ln\_traadv\_cen}\forcode{ = .true.})} 
    186188\label{subsec:TRA_adv_cen} 
    187189 
    188190%        2nd order centred scheme   
    189191 
    190 The centred advection scheme (CEN) is used when \np{ln\_traadv\_cen}~\forcode{= .true.}. 
     192The centred advection scheme (CEN) is used when \np{ln\_traadv\_cen}\forcode{ = .true.}. 
    191193Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) and vertical direction by 
    192194setting \np{nn\_cen\_h} and \np{nn\_cen\_v} to $2$ or $4$. 
     
    220222  \tau_u^{cen4} = \overline{T - \frac{1}{6} \, \delta_i \Big[ \delta_{i + 1/2}[T] \, \Big]}^{\,i + 1/2} 
    221223\end{equation} 
    222 In the vertical direction (\np{nn\_cen\_v}~\forcode{= 4}), 
    223 a $4^{th}$ COMPACT interpolation has been prefered \citep{Demange_PhD2014}. 
     224In the vertical direction (\np{nn\_cen\_v}\forcode{ = 4}), 
     225a $4^{th}$ COMPACT interpolation has been prefered \citep{demange_phd14}. 
    224226In the COMPACT scheme, both the field and its derivative are interpolated, which leads, after a matrix inversion, 
    225 spectral characteristics similar to schemes of higher order \citep{Lele_JCP1992}.  
     227spectral characteristics similar to schemes of higher order \citep{lele_JCP92}.  
    226228 
    227229Strictly speaking, the CEN4 scheme is not a $4^{th}$ order advection scheme but 
     
    250252%        FCT scheme   
    251253% ------------------------------------------------------------------------------------------------------------- 
    252 \subsection{FCT: Flux Corrected Transport scheme (\protect\np{ln\_traadv\_fct}~\forcode{= .true.})} 
     254\subsection[FCT: Flux Corrected Transport scheme (\forcode{ln_traadv_fct = .true.})] 
     255{FCT: Flux Corrected Transport scheme (\protect\np{ln\_traadv\_fct}\forcode{ = .true.})} 
    253256\label{subsec:TRA_adv_tvd} 
    254257 
    255 The Flux Corrected Transport schemes (FCT) is used when \np{ln\_traadv\_fct}~\forcode{= .true.}. 
     258The Flux Corrected Transport schemes (FCT) is used when \np{ln\_traadv\_fct}\forcode{ = .true.}. 
    256259Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) and vertical direction by 
    257260setting \np{nn\_fct\_h} and \np{nn\_fct\_v} to $2$ or $4$. 
     
    277280(\ie it depends on the setting of \np{nn\_fct\_h} and \np{nn\_fct\_v}). 
    278281There exist many ways to define $c_u$, each corresponding to a different FCT scheme. 
    279 The one chosen in \NEMO is described in \citet{Zalesak_JCP79}. 
     282The one chosen in \NEMO is described in \citet{zalesak_JCP79}. 
    280283$c_u$ only departs from $1$ when the advective term produces a local extremum in the tracer field. 
    281284The resulting scheme is quite expensive but \textit{positive}. 
    282285It can be used on both active and passive tracers. 
    283 A comparison of FCT-2 with MUSCL and a MPDATA scheme can be found in \citet{Levy_al_GRL01}. 
     286A comparison of FCT-2 with MUSCL and a MPDATA scheme can be found in \citet{levy.estublier.ea_GRL01}. 
    284287 
    285288An additional option has been added controlled by \np{nn\_fct\_zts}. 
     
    287290a $2^{nd}$ order FCT scheme is used on both horizontal and vertical direction, but on the latter, 
    288291a split-explicit time stepping is used, with a number of sub-timestep equals to \np{nn\_fct\_zts}. 
    289 This option can be useful when the size of the timestep is limited by vertical advection \citep{Lemarie_OM2015}. 
     292This option can be useful when the size of the timestep is limited by vertical advection \citep{lemarie.debreu.ea_OM15}. 
    290293Note that in this case, a similar split-explicit time stepping should be used on vertical advection of momentum to 
    291294insure a better stability (see \autoref{subsec:DYN_zad}). 
     
    300303%        MUSCL scheme   
    301304% ------------------------------------------------------------------------------------------------------------- 
    302 \subsection{MUSCL: Monotone Upstream Scheme for Conservative Laws (\protect\np{ln\_traadv\_mus}~\forcode{= .true.})} 
     305\subsection[MUSCL: Monotone Upstream Scheme for Conservative Laws (\forcode{ln_traadv_mus = .true.})] 
     306{MUSCL: Monotone Upstream Scheme for Conservative Laws (\protect\np{ln\_traadv\_mus}\forcode{ = .true.})} 
    303307\label{subsec:TRA_adv_mus} 
    304308 
    305 The Monotone Upstream Scheme for Conservative Laws (MUSCL) is used when \np{ln\_traadv\_mus}~\forcode{= .true.}. 
     309The Monotone Upstream Scheme for Conservative Laws (MUSCL) is used when \np{ln\_traadv\_mus}\forcode{ = .true.}. 
    306310MUSCL implementation can be found in the \mdl{traadv\_mus} module. 
    307311 
    308 MUSCL has been first implemented in \NEMO by \citet{Levy_al_GRL01}. 
     312MUSCL has been first implemented in \NEMO by \citet{levy.estublier.ea_GRL01}. 
    309313In its formulation, the tracer at velocity points is evaluated assuming a linear tracer variation between 
    310314two $T$-points (\autoref{fig:adv_scheme}). 
     
    331335This choice ensure the \textit{positive} character of the scheme. 
    332336In addition, fluxes round a grid-point where a runoff is applied can optionally be computed using upstream fluxes 
    333 (\np{ln\_mus\_ups}~\forcode{= .true.}). 
     337(\np{ln\_mus\_ups}\forcode{ = .true.}). 
    334338 
    335339% ------------------------------------------------------------------------------------------------------------- 
    336340%        UBS scheme   
    337341% ------------------------------------------------------------------------------------------------------------- 
    338 \subsection{UBS a.k.a. UP3: Upstream-Biased Scheme (\protect\np{ln\_traadv\_ubs}~\forcode{= .true.})} 
     342\subsection[UBS a.k.a. UP3: Upstream-Biased Scheme (\forcode{ln_traadv_ubs = .true.})] 
     343{UBS a.k.a. UP3: Upstream-Biased Scheme (\protect\np{ln\_traadv\_ubs}\forcode{ = .true.})} 
    339344\label{subsec:TRA_adv_ubs} 
    340345 
    341 The Upstream-Biased Scheme (UBS) is used when \np{ln\_traadv\_ubs}~\forcode{= .true.}. 
     346The Upstream-Biased Scheme (UBS) is used when \np{ln\_traadv\_ubs}\forcode{ = .true.}. 
    342347UBS implementation can be found in the \mdl{traadv\_mus} module. 
    343348 
     
    358363 
    359364This results in a dissipatively dominant (i.e. hyper-diffusive) truncation error 
    360 \citep{Shchepetkin_McWilliams_OM05}. 
    361 The overall performance of the advection scheme is similar to that reported in \cite{Farrow1995}. 
     365\citep{shchepetkin.mcwilliams_OM05}. 
     366The overall performance of the advection scheme is similar to that reported in \cite{farrow.stevens_JPO95}. 
    362367It is a relatively good compromise between accuracy and smoothness. 
    363368Nevertheless the scheme is not \textit{positive}, meaning that false extrema are permitted, 
     
    367372The intrinsic diffusion of UBS makes its use risky in the vertical direction where 
    368373the control of artificial diapycnal fluxes is of paramount importance 
    369 \citep{Shchepetkin_McWilliams_OM05, Demange_PhD2014}. 
     374\citep{shchepetkin.mcwilliams_OM05, demange_phd14}. 
    370375Therefore the vertical flux is evaluated using either a $2^nd$ order FCT scheme or a $4^th$ order COMPACT scheme 
    371 (\np{nn\_cen\_v}~\forcode{= 2 or 4}). 
     376(\np{nn\_cen\_v}\forcode{ = 2 or 4}). 
    372377 
    373378For stability reasons (see \autoref{chap:STP}), the first term  in \autoref{eq:tra_adv_ubs} 
     
    376381(which is the diffusive part of the scheme), 
    377382is evaluated using the \textit{before} tracer (forward in time). 
    378 This choice is discussed by \citet{Webb_al_JAOT98} in the context of the QUICK advection scheme. 
     383This choice is discussed by \citet{webb.de-cuevas.ea_JAOT98} in the context of the QUICK advection scheme. 
    379384UBS and QUICK schemes only differ by one coefficient. 
    380 Replacing 1/6 with 1/8 in \autoref{eq:tra_adv_ubs} leads to the QUICK advection scheme \citep{Webb_al_JAOT98}. 
     385Replacing 1/6 with 1/8 in \autoref{eq:tra_adv_ubs} leads to the QUICK advection scheme \citep{webb.de-cuevas.ea_JAOT98}. 
    381386This option is not available through a namelist parameter, since the 1/6 coefficient is hard coded. 
    382387Nevertheless it is quite easy to make the substitution in the \mdl{traadv\_ubs} module and obtain a QUICK scheme. 
     
    408413%        QCK scheme   
    409414% ------------------------------------------------------------------------------------------------------------- 
    410 \subsection{QCK: QuiCKest scheme (\protect\np{ln\_traadv\_qck}~\forcode{= .true.})} 
     415\subsection[QCK: QuiCKest scheme (\forcode{ln_traadv_qck = .true.})] 
     416{QCK: QuiCKest scheme (\protect\np{ln\_traadv\_qck}\forcode{ = .true.})} 
    411417\label{subsec:TRA_adv_qck} 
    412418 
    413419The Quadratic Upstream Interpolation for Convective Kinematics with Estimated Streaming Terms (QUICKEST) scheme 
    414 proposed by \citet{Leonard1979} is used when \np{ln\_traadv\_qck}~\forcode{= .true.}. 
     420proposed by \citet{leonard_CMAME79} is used when \np{ln\_traadv\_qck}\forcode{ = .true.}. 
    415421QUICKEST implementation can be found in the \mdl{traadv\_qck} module. 
    416422 
    417423QUICKEST is the third order Godunov scheme which is associated with the ULTIMATE QUICKEST limiter 
    418 \citep{Leonard1991}. 
     424\citep{leonard_CMAME91}. 
    419425It has been implemented in NEMO by G. Reffray (MERCATOR-ocean) and can be found in the \mdl{traadv\_qck} module. 
    420426The resulting scheme is quite expensive but \textit{positive}. 
     
    431437% Tracer Lateral Diffusion 
    432438% ================================================================ 
    433 \section{Tracer lateral diffusion (\protect\mdl{traldf})} 
     439\section[Tracer lateral diffusion (\textit{traldf.F90})] 
     440{Tracer lateral diffusion (\protect\mdl{traldf})} 
    434441\label{sec:TRA_ldf} 
    435442%-----------------------------------------nam_traldf------------------------------------------------------ 
     
    453460except for the pure vertical component that appears when a rotation tensor is used. 
    454461This latter component is solved implicitly together with the vertical diffusion term (see \autoref{chap:STP}). 
    455 When \np{ln\_traldf\_msc}~\forcode{= .true.}, a Method of Stabilizing Correction is used in which 
    456 the pure vertical component is split into an explicit and an implicit part \citep{Lemarie_OM2012}. 
     462When \np{ln\_traldf\_msc}\forcode{ = .true.}, a Method of Stabilizing Correction is used in which 
     463the pure vertical component is split into an explicit and an implicit part \citep{lemarie.debreu.ea_OM12}. 
    457464 
    458465% ------------------------------------------------------------------------------------------------------------- 
    459466%        Type of operator 
    460467% ------------------------------------------------------------------------------------------------------------- 
    461 \subsection[Type of operator (\protect\np{ln\_traldf}\{\_NONE,\_lap,\_blp\}\})]{Type of operator (\protect\np{ln\_traldf\_NONE}, \protect\np{ln\_traldf\_lap}, or \protect\np{ln\_traldf\_blp}) }  
     468\subsection[Type of operator (\texttt{ln\_traldf}\{\texttt{\_NONE,\_lap,\_blp}\})] 
     469{Type of operator (\protect\np{ln\_traldf\_NONE}, \protect\np{ln\_traldf\_lap}, or \protect\np{ln\_traldf\_blp}) }  
    462470\label{subsec:TRA_ldf_op} 
    463471 
     
    465473 
    466474\begin{description} 
    467 \item[\np{ln\_traldf\_NONE}~\forcode{= .true.}:] 
     475\item[\np{ln\_traldf\_NONE}\forcode{ = .true.}:] 
    468476  no operator selected, the lateral diffusive tendency will not be applied to the tracer equation. 
    469477  This option can be used when the selected advection scheme is diffusive enough (MUSCL scheme for example). 
    470 \item[\np{ln\_traldf\_lap}~\forcode{= .true.}:] 
     478\item[\np{ln\_traldf\_lap}\forcode{ = .true.}:] 
    471479  a laplacian operator is selected. 
    472480  This harmonic operator takes the following expression:  $\mathpzc{L}(T) = \nabla \cdot A_{ht} \; \nabla T $, 
    473481  where the gradient operates along the selected direction (see \autoref{subsec:TRA_ldf_dir}), 
    474482  and $A_{ht}$ is the eddy diffusivity coefficient expressed in $m^2/s$ (see \autoref{chap:LDF}). 
    475 \item[\np{ln\_traldf\_blp}~\forcode{= .true.}]: 
     483\item[\np{ln\_traldf\_blp}\forcode{ = .true.}]: 
    476484  a bilaplacian operator is selected. 
    477485  This biharmonic operator takes the following expression: 
     
    493501%        Direction of action 
    494502% ------------------------------------------------------------------------------------------------------------- 
    495 \subsection[Action direction (\protect\np{ln\_traldf}\{\_lev,\_hor,\_iso,\_triad\})]{Direction of action (\protect\np{ln\_traldf\_lev}, \protect\np{ln\_traldf\_hor}, \protect\np{ln\_traldf\_iso}, or \protect\np{ln\_traldf\_triad}) }  
     503\subsection[Action direction (\texttt{ln\_traldf}\{\texttt{\_lev,\_hor,\_iso,\_triad}\})] 
     504{Direction of action (\protect\np{ln\_traldf\_lev}, \protect\np{ln\_traldf\_hor}, \protect\np{ln\_traldf\_iso}, or \protect\np{ln\_traldf\_triad}) }  
    496505\label{subsec:TRA_ldf_dir} 
    497506 
    498507The choice of a direction of action determines the form of operator used. 
    499508The operator is a simple (re-entrant) laplacian acting in the (\textbf{i},\textbf{j}) plane when 
    500 iso-level option is used (\np{ln\_traldf\_lev}~\forcode{= .true.}) or 
     509iso-level option is used (\np{ln\_traldf\_lev}\forcode{ = .true.}) or 
    501510when a horizontal (\ie geopotential) operator is demanded in \textit{z}-coordinate 
    502511(\np{ln\_traldf\_hor} and \np{ln\_zco} equal \forcode{.true.}). 
     
    519528%       iso-level operator 
    520529% ------------------------------------------------------------------------------------------------------------- 
    521 \subsection{Iso-level (bi -)laplacian operator ( \protect\np{ln\_traldf\_iso}) } 
     530\subsection[Iso-level (bi-)laplacian operator (\texttt{ln\_traldf\_iso})] 
     531{Iso-level (bi-)laplacian operator ( \protect\np{ln\_traldf\_iso})} 
    522532\label{subsec:TRA_ldf_lev} 
    523533 
     
    537547It is a \textit{horizontal} operator (\ie acting along geopotential surfaces) in 
    538548the $z$-coordinate with or without partial steps, but is simply an iso-level operator in the $s$-coordinate. 
    539 It is thus used when, in addition to \np{ln\_traldf\_lap} or \np{ln\_traldf\_blp}~\forcode{= .true.}, 
    540 we have \np{ln\_traldf\_lev}~\forcode{= .true.} or \np{ln\_traldf\_hor}~=~\np{ln\_zco}~\forcode{= .true.}. 
     549It is thus used when, in addition to \np{ln\_traldf\_lap} or \np{ln\_traldf\_blp}\forcode{ = .true.}, 
     550we have \np{ln\_traldf\_lev}\forcode{ = .true.} or \np{ln\_traldf\_hor}~=~\np{ln\_zco}\forcode{ = .true.}. 
    541551In both cases, it significantly contributes to diapycnal mixing. 
    542552It is therefore never recommended, even when using it in the bilaplacian case. 
    543553 
    544 Note that in the partial step $z$-coordinate (\np{ln\_zps}~\forcode{= .true.}), 
     554Note that in the partial step $z$-coordinate (\np{ln\_zps}\forcode{ = .true.}), 
    545555tracers in horizontally adjacent cells are located at different depths in the vicinity of the bottom. 
    546556In this case, horizontal derivatives in (\autoref{eq:tra_ldf_lap}) at the bottom level require a specific treatment. 
     
    550560%         Rotated laplacian operator 
    551561% ------------------------------------------------------------------------------------------------------------- 
    552 \subsection{Standard and triad (bi -)laplacian operator} 
     562\subsection{Standard and triad (bi-)laplacian operator} 
    553563\label{subsec:TRA_ldf_iso_triad} 
    554564 
    555 %&&    Standard rotated (bi -)laplacian operator 
     565%&&    Standard rotated (bi-)laplacian operator 
    556566%&& ---------------------------------------------- 
    557 \subsubsection{Standard rotated (bi -)laplacian operator (\protect\mdl{traldf\_iso})} 
     567\subsubsection[Standard rotated (bi-)laplacian operator (\textit{traldf\_iso.F90})] 
     568{Standard rotated (bi-)laplacian operator (\protect\mdl{traldf\_iso})} 
    558569\label{subsec:TRA_ldf_iso} 
    559570The general form of the second order lateral tracer subgrid scale physics (\autoref{eq:PE_zdf}) 
     
    574585$r_1$ and $r_2$ are the slopes between the surface of computation ($z$- or $s$-surfaces) and 
    575586the surface along which the diffusion operator acts (\ie horizontal or iso-neutral surfaces). 
    576 It is thus used when, in addition to \np{ln\_traldf\_lap}~\forcode{= .true.}, 
    577 we have \np{ln\_traldf\_iso}~\forcode{= .true.}, 
    578 or both \np{ln\_traldf\_hor}~\forcode{= .true.} and \np{ln\_zco}~\forcode{= .true.}. 
     587It is thus used when, in addition to \np{ln\_traldf\_lap}\forcode{ = .true.}, 
     588we have \np{ln\_traldf\_iso}\forcode{ = .true.}, 
     589or both \np{ln\_traldf\_hor}\forcode{ = .true.} and \np{ln\_zco}\forcode{ = .true.}. 
    579590The way these slopes are evaluated is given in \autoref{sec:LDF_slp}. 
    580591At the surface, bottom and lateral boundaries, the turbulent fluxes of heat and salt are set to zero using 
     
    590601This formulation conserves the tracer but does not ensure the decrease of the tracer variance. 
    591602Nevertheless the treatment performed on the slopes (see \autoref{chap:LDF}) allows the model to run safely without 
    592 any additional background horizontal diffusion \citep{Guilyardi_al_CD01}. 
    593  
    594 Note that in the partial step $z$-coordinate (\np{ln\_zps}~\forcode{= .true.}), 
     603any additional background horizontal diffusion \citep{guilyardi.madec.ea_CD01}. 
     604 
     605Note that in the partial step $z$-coordinate (\np{ln\_zps}\forcode{ = .true.}), 
    595606the horizontal derivatives at the bottom level in \autoref{eq:tra_ldf_iso} require a specific treatment. 
    596607They are calculated in module zpshde, described in \autoref{sec:TRA_zpshde}. 
    597608 
    598 %&&     Triad rotated (bi -)laplacian operator 
     609%&&     Triad rotated (bi-)laplacian operator 
    599610%&&  ------------------------------------------- 
    600 \subsubsection{Triad rotated (bi -)laplacian operator (\protect\np{ln\_traldf\_triad})} 
     611\subsubsection[Triad rotated (bi-)laplacian operator (\textit{ln\_traldf\_triad})] 
     612{Triad rotated (bi-)laplacian operator (\protect\np{ln\_traldf\_triad})} 
    601613\label{subsec:TRA_ldf_triad} 
    602614 
    603 If the Griffies triad scheme is employed (\np{ln\_traldf\_triad}~\forcode{= .true.}; see \autoref{apdx:triad}) 
    604  
    605 An alternative scheme developed by \cite{Griffies_al_JPO98} which ensures tracer variance decreases 
    606 is also available in \NEMO (\np{ln\_traldf\_grif}~\forcode{= .true.}). 
     615If the Griffies triad scheme is employed (\np{ln\_traldf\_triad}\forcode{ = .true.}; see \autoref{apdx:triad}) 
     616 
     617An alternative scheme developed by \cite{griffies.gnanadesikan.ea_JPO98} which ensures tracer variance decreases 
     618is also available in \NEMO (\np{ln\_traldf\_grif}\forcode{ = .true.}). 
    607619A complete description of the algorithm is given in \autoref{apdx:triad}. 
    608620 
     
    632644% Tracer Vertical Diffusion 
    633645% ================================================================ 
    634 \section{Tracer vertical diffusion (\protect\mdl{trazdf})} 
     646\section[Tracer vertical diffusion (\textit{trazdf.F90})] 
     647{Tracer vertical diffusion (\protect\mdl{trazdf})} 
    635648\label{sec:TRA_zdf} 
    636649%--------------------------------------------namzdf--------------------------------------------------------- 
     
    663676 
    664677The large eddy coefficient found in the mixed layer together with high vertical resolution implies that 
    665 in the case of explicit time stepping (\np{ln\_zdfexp}~\forcode{= .true.}) 
     678in the case of explicit time stepping (\np{ln\_zdfexp}\forcode{ = .true.}) 
    666679there would be too restrictive a constraint on the time step. 
    667680Therefore, the default implicit time stepping is preferred for the vertical diffusion since 
    668681it overcomes the stability constraint. 
    669 A forward time differencing scheme (\np{ln\_zdfexp}~\forcode{= .true.}) using 
     682A forward time differencing scheme (\np{ln\_zdfexp}\forcode{ = .true.}) using 
    670683a time splitting technique (\np{nn\_zdfexp} $> 1$) is provided as an alternative. 
    671684Namelist variables \np{ln\_zdfexp} and \np{nn\_zdfexp} apply to both tracers and dynamics. 
     
    680693%        surface boundary condition 
    681694% ------------------------------------------------------------------------------------------------------------- 
    682 \subsection{Surface boundary condition (\protect\mdl{trasbc})} 
     695\subsection[Surface boundary condition (\textit{trasbc.F90})] 
     696{Surface boundary condition (\protect\mdl{trasbc})} 
    683697\label{subsec:TRA_sbc} 
    684698 
     
    730744Such time averaging prevents the divergence of odd and even time step (see \autoref{chap:STP}). 
    731745 
    732 In the linear free surface case (\np{ln\_linssh}~\forcode{= .true.}), an additional term has to be added on 
     746In the linear free surface case (\np{ln\_linssh}\forcode{ = .true.}), an additional term has to be added on 
    733747both temperature and salinity. 
    734748On temperature, this term remove the heat content associated with mass exchange that has been added to $Q_{ns}$. 
     
    747761Note that an exact conservation of heat and salt content is only achieved with non-linear free surface. 
    748762In the linear free surface case, there is a small imbalance. 
    749 The imbalance is larger than the imbalance associated with the Asselin time filter \citep{Leclair_Madec_OM09}. 
     763The imbalance is larger than the imbalance associated with the Asselin time filter \citep{leclair.madec_OM09}. 
    750764This is the reason why the modified filter is not applied in the linear free surface case (see \autoref{chap:STP}). 
    751765 
     
    753767%        Solar Radiation Penetration  
    754768% ------------------------------------------------------------------------------------------------------------- 
    755 \subsection{Solar radiation penetration (\protect\mdl{traqsr})} 
     769\subsection[Solar radiation penetration (\textit{traqsr.F90})] 
     770{Solar radiation penetration (\protect\mdl{traqsr})} 
    756771\label{subsec:TRA_qsr} 
    757772%--------------------------------------------namqsr-------------------------------------------------------- 
     
    761776 
    762777Options are defined through the \ngn{namtra\_qsr} namelist variables. 
    763 When the penetrative solar radiation option is used (\np{ln\_flxqsr}~\forcode{= .true.}), 
     778When the penetrative solar radiation option is used (\np{ln\_flxqsr}\forcode{ = .true.}), 
    764779the solar radiation penetrates the top few tens of meters of the ocean. 
    765 If it is not used (\np{ln\_flxqsr}~\forcode{= .false.}) all the heat flux is absorbed in the first ocean level. 
     780If it is not used (\np{ln\_flxqsr}\forcode{ = .false.}) all the heat flux is absorbed in the first ocean level. 
    766781Thus, in the former case a term is added to the time evolution equation of temperature \autoref{eq:PE_tra_T} and 
    767782the surface boundary condition is modified to take into account only the non-penetrative part of the surface  
     
    792807larger depths where it contributes to local heating. 
    793808The way this second part of the solar energy penetrates into the ocean depends on which formulation is chosen. 
    794 In the simple 2-waveband light penetration scheme (\np{ln\_qsr\_2bd}~\forcode{= .true.}) 
     809In the simple 2-waveband light penetration scheme (\np{ln\_qsr\_2bd}\forcode{ = .true.}) 
    795810a chlorophyll-independent monochromatic formulation is chosen for the shorter wavelengths, 
    796 leading to the following expression \citep{Paulson1977}: 
     811leading to the following expression \citep{paulson.simpson_JPO77}: 
    797812\[ 
    798813  % \label{eq:traqsr_iradiance} 
     
    805820 
    806821Such assumptions have been shown to provide a very crude and simplistic representation of 
    807 observed light penetration profiles (\cite{Morel_JGR88}, see also \autoref{fig:traqsr_irradiance}). 
     822observed light penetration profiles (\cite{morel_JGR88}, see also \autoref{fig:traqsr_irradiance}). 
    808823Light absorption in the ocean depends on particle concentration and is spectrally selective. 
    809 \cite{Morel_JGR88} has shown that an accurate representation of light penetration can be provided by 
     824\cite{morel_JGR88} has shown that an accurate representation of light penetration can be provided by 
    810825a 61 waveband formulation. 
    811826Unfortunately, such a model is very computationally expensive. 
    812 Thus, \cite{Lengaigne_al_CD07} have constructed a simplified version of this formulation in which 
     827Thus, \cite{lengaigne.menkes.ea_CD07} have constructed a simplified version of this formulation in which 
    813828visible light is split into three wavebands: blue (400-500 nm), green (500-600 nm) and red (600-700nm). 
    814829For each wave-band, the chlorophyll-dependent attenuation coefficient is fitted to the coefficients computed from 
    815 the full spectral model of \cite{Morel_JGR88} (as modified by \cite{Morel_Maritorena_JGR01}), 
     830the full spectral model of \cite{morel_JGR88} (as modified by \cite{morel.maritorena_JGR01}), 
    816831assuming the same power-law relationship. 
    817832As shown in \autoref{fig:traqsr_irradiance}, this formulation, called RGB (Red-Green-Blue), 
     
    820835The 2-bands formulation does not reproduce the full model very well. 
    821836 
    822 The RGB formulation is used when \np{ln\_qsr\_rgb}~\forcode{= .true.}. 
     837The RGB formulation is used when \np{ln\_qsr\_rgb}\forcode{ = .true.}. 
    823838The RGB attenuation coefficients (\ie the inverses of the extinction length scales) are tabulated over 
    82483961 nonuniform chlorophyll classes ranging from 0.01 to 10 g.Chl/L 
     
    827842 
    828843\begin{description} 
    829 \item[\np{nn\_chdta}~\forcode{= 0}] 
     844\item[\np{nn\_chdta}\forcode{ = 0}] 
    830845  a constant 0.05 g.Chl/L value everywhere ;  
    831 \item[\np{nn\_chdta}~\forcode{= 1}] 
     846\item[\np{nn\_chdta}\forcode{ = 1}] 
    832847  an observed time varying chlorophyll deduced from satellite surface ocean color measurement spread uniformly in 
    833848  the vertical direction; 
    834 \item[\np{nn\_chdta}~\forcode{= 2}] 
     849\item[\np{nn\_chdta}\forcode{ = 2}] 
    835850  same as previous case except that a vertical profile of chlorophyl is used. 
    836   Following \cite{Morel_Berthon_LO89}, the profile is computed from the local surface chlorophyll value; 
    837 \item[\np{ln\_qsr\_bio}~\forcode{= .true.}] 
     851  Following \cite{morel.berthon_LO89}, the profile is computed from the local surface chlorophyll value; 
     852\item[\np{ln\_qsr\_bio}\forcode{ = .true.}] 
    838853  simulated time varying chlorophyll by TOP biogeochemical model. 
    839854  In this case, the RGB formulation is used to calculate both the phytoplankton light limitation in 
     
    856871\begin{figure}[!t] 
    857872  \begin{center} 
    858     \includegraphics[]{Fig_TRA_Irradiance} 
     873    \includegraphics[width=\textwidth]{Fig_TRA_Irradiance} 
    859874    \caption{ 
    860875      \protect\label{fig:traqsr_irradiance} 
     
    865880      61 waveband Morel (1988) formulation (black) for a chlorophyll concentration of 
    866881      (a) Chl=0.05 mg/m$^3$ and (b) Chl=0.5 mg/m$^3$. 
    867       From \citet{Lengaigne_al_CD07}. 
     882      From \citet{lengaigne.menkes.ea_CD07}. 
    868883    } 
    869884  \end{center} 
     
    874889%        Bottom Boundary Condition 
    875890% ------------------------------------------------------------------------------------------------------------- 
    876 \subsection{Bottom boundary condition (\protect\mdl{trabbc})} 
     891\subsection[Bottom boundary condition (\textit{trabbc.F90})] 
     892{Bottom boundary condition (\protect\mdl{trabbc})} 
    877893\label{subsec:TRA_bbc} 
    878894%--------------------------------------------nambbc-------------------------------------------------------- 
     
    883899\begin{figure}[!t] 
    884900  \begin{center} 
    885     \includegraphics[]{Fig_TRA_geoth} 
     901    \includegraphics[width=\textwidth]{Fig_TRA_geoth} 
    886902    \caption{ 
    887903      \protect\label{fig:geothermal} 
    888       Geothermal Heat flux (in $mW.m^{-2}$) used by \cite{Emile-Geay_Madec_OS09}. 
    889       It is inferred from the age of the sea floor and the formulae of \citet{Stein_Stein_Nat92}. 
     904      Geothermal Heat flux (in $mW.m^{-2}$) used by \cite{emile-geay.madec_OS09}. 
     905      It is inferred from the age of the sea floor and the formulae of \citet{stein.stein_N92}. 
    890906    } 
    891907  \end{center} 
     
    897913This is the default option in \NEMO, and it is implemented using the masking technique. 
    898914However, there is a non-zero heat flux across the seafloor that is associated with solid earth cooling. 
    899 This flux is weak compared to surface fluxes (a mean global value of $\sim 0.1 \, W/m^2$ \citep{Stein_Stein_Nat92}), 
     915This flux is weak compared to surface fluxes (a mean global value of $\sim 0.1 \, W/m^2$ \citep{stein.stein_N92}), 
    900916but it warms systematically the ocean and acts on the densest water masses. 
    901917Taking this flux into account in a global ocean model increases the deepest overturning cell 
    902 (\ie the one associated with the Antarctic Bottom Water) by a few Sverdrups \citep{Emile-Geay_Madec_OS09}. 
     918(\ie the one associated with the Antarctic Bottom Water) by a few Sverdrups \citep{emile-geay.madec_OS09}. 
    903919 
    904920Options are defined through the  \ngn{namtra\_bbc} namelist variables. 
     
    907923the \np{nn\_geoflx\_cst}, which is also a namelist parameter. 
    908924When \np{nn\_geoflx} is set to 2, a spatially varying geothermal heat flux is introduced which is provided in 
    909 the \ifile{geothermal\_heating} NetCDF file (\autoref{fig:geothermal}) \citep{Emile-Geay_Madec_OS09}. 
     925the \ifile{geothermal\_heating} NetCDF file (\autoref{fig:geothermal}) \citep{emile-geay.madec_OS09}. 
    910926 
    911927% ================================================================ 
    912928% Bottom Boundary Layer 
    913929% ================================================================ 
    914 \section{Bottom boundary layer (\protect\mdl{trabbl} - \protect\key{trabbl})} 
     930\section[Bottom boundary layer (\textit{trabbl.F90} - \texttt{\textbf{key\_trabbl}})] 
     931{Bottom boundary layer (\protect\mdl{trabbl} - \protect\key{trabbl})} 
    915932\label{sec:TRA_bbl} 
    916933%--------------------------------------------nambbl--------------------------------------------------------- 
     
    931948sometimes over a thickness much larger than the thickness of the observed gravity plume. 
    932949A similar problem occurs in the $s$-coordinate when the thickness of the bottom level varies rapidly downstream of 
    933 a sill \citep{Willebrand_al_PO01}, and the thickness of the plume is not resolved. 
    934  
    935 The idea of the bottom boundary layer (BBL) parameterisation, first introduced by \citet{Beckmann_Doscher1997}, 
     950a sill \citep{willebrand.barnier.ea_PO01}, and the thickness of the plume is not resolved. 
     951 
     952The idea of the bottom boundary layer (BBL) parameterisation, first introduced by \citet{beckmann.doscher_JPO97}, 
    936953is to allow a direct communication between two adjacent bottom cells at different levels, 
    937954whenever the densest water is located above the less dense water. 
     
    939956In the current implementation of the BBL, only the tracers are modified, not the velocities. 
    940957Furthermore, it only connects ocean bottom cells, and therefore does not include all the improvements introduced by 
    941 \citet{Campin_Goosse_Tel99}. 
     958\citet{campin.goosse_T99}. 
    942959 
    943960% ------------------------------------------------------------------------------------------------------------- 
    944961%        Diffusive BBL 
    945962% ------------------------------------------------------------------------------------------------------------- 
    946 \subsection{Diffusive bottom boundary layer (\protect\np{nn\_bbl\_ldf}~\forcode{= 1})} 
     963\subsection[Diffusive bottom boundary layer (\forcode{nn_bbl_ldf = 1})] 
     964{Diffusive bottom boundary layer (\protect\np{nn\_bbl\_ldf}\forcode{ = 1})} 
    947965\label{subsec:TRA_bbl_diff} 
    948966 
     
    955973with $\nabla_\sigma$ the lateral gradient operator taken between bottom cells, and 
    956974$A_l^\sigma$ the lateral diffusivity in the BBL. 
    957 Following \citet{Beckmann_Doscher1997}, the latter is prescribed with a spatial dependence, 
     975Following \citet{beckmann.doscher_JPO97}, the latter is prescribed with a spatial dependence, 
    958976\ie in the conditional form 
    959977\begin{equation} 
     
    9831001%        Advective BBL 
    9841002% ------------------------------------------------------------------------------------------------------------- 
    985 \subsection{Advective bottom boundary layer  (\protect\np{nn\_bbl\_adv}~\forcode{= 1..2})} 
     1003\subsection[Advective bottom boundary layer (\forcode{nn_bbl_adv = [12]})] 
     1004{Advective bottom boundary layer (\protect\np{nn\_bbl\_adv}\forcode{ = [12]})} 
    9861005\label{subsec:TRA_bbl_adv} 
    9871006 
     
    9941013\begin{figure}[!t] 
    9951014  \begin{center} 
    996     \includegraphics[]{Fig_BBL_adv} 
     1015    \includegraphics[width=\textwidth]{Fig_BBL_adv} 
    9971016    \caption{ 
    9981017      \protect\label{fig:bbl} 
     
    10141033%%%gmcomment   :  this section has to be really written 
    10151034 
    1016 When applying an advective BBL (\np{nn\_bbl\_adv}~\forcode{= 1..2}), an overturning circulation is added which 
     1035When applying an advective BBL (\np{nn\_bbl\_adv}\forcode{ = 1..2}), an overturning circulation is added which 
    10171036connects two adjacent bottom grid-points only if dense water overlies less dense water on the slope. 
    10181037The density difference causes dense water to move down the slope. 
    10191038 
    1020 \np{nn\_bbl\_adv}~\forcode{= 1}: 
     1039\np{nn\_bbl\_adv}\forcode{ = 1}: 
    10211040the downslope velocity is chosen to be the Eulerian ocean velocity just above the topographic step 
    1022 (see black arrow in \autoref{fig:bbl}) \citep{Beckmann_Doscher1997}. 
     1041(see black arrow in \autoref{fig:bbl}) \citep{beckmann.doscher_JPO97}. 
    10231042It is a \textit{conditional advection}, that is, advection is allowed only 
    10241043if dense water overlies less dense water on the slope (\ie $\nabla_\sigma \rho \cdot \nabla H < 0$) and 
    10251044if the velocity is directed towards greater depth (\ie $\vect U \cdot \nabla H > 0$). 
    10261045 
    1027 \np{nn\_bbl\_adv}~\forcode{= 2}: 
     1046\np{nn\_bbl\_adv}\forcode{ = 2}: 
    10281047the downslope velocity is chosen to be proportional to $\Delta \rho$, 
    1029 the density difference between the higher cell and lower cell densities \citep{Campin_Goosse_Tel99}. 
     1048the density difference between the higher cell and lower cell densities \citep{campin.goosse_T99}. 
    10301049The advection is allowed only  if dense water overlies less dense water on the slope 
    10311050(\ie $\nabla_\sigma \rho \cdot \nabla H < 0$). 
     
    10411060The parameter $\gamma$ should take a different value for each bathymetric step, but for simplicity, 
    10421061and because no direct estimation of this parameter is available, a uniform value has been assumed. 
    1043 The possible values for $\gamma$ range between 1 and $10~s$ \citep{Campin_Goosse_Tel99}. 
     1062The possible values for $\gamma$ range between 1 and $10~s$ \citep{campin.goosse_T99}. 
    10441063 
    10451064Scalar properties are advected by this additional transport $(u^{tr}_{bbl},v^{tr}_{bbl})$ using the upwind scheme. 
     
    10741093% Tracer damping 
    10751094% ================================================================ 
    1076 \section{Tracer damping (\protect\mdl{tradmp})} 
     1095\section[Tracer damping (\textit{tradmp.F90})] 
     1096{Tracer damping (\protect\mdl{tradmp})} 
    10771097\label{sec:TRA_dmp} 
    10781098%--------------------------------------------namtra_dmp------------------------------------------------- 
     
    11091129In the vicinity of these walls, $\gamma$ takes large values (equivalent to a time scale of a few days) whereas 
    11101130it is zero in the interior of the model domain. 
    1111 The second case corresponds to the use of the robust diagnostic method \citep{Sarmiento1982}. 
     1131The second case corresponds to the use of the robust diagnostic method \citep{sarmiento.bryan_JGR82}. 
    11121132It allows us to find the velocity field consistent with the model dynamics whilst 
    11131133having a $T$, $S$ field close to a given climatological field ($T_o$, $S_o$). 
     
    11211141only below the mixed layer (defined either on a density or $S_o$ criterion). 
    11221142It is common to set the damping to zero in the mixed layer as the adjustment time scale is short here 
    1123 \citep{Madec_al_JPO96}. 
     1143\citep{madec.delecluse.ea_JPO96}. 
    11241144 
    11251145For generating \ifile{resto}, see the documentation for the DMP tool provided with the source code under 
     
    11291149% Tracer time evolution 
    11301150% ================================================================ 
    1131 \section{Tracer time evolution (\protect\mdl{tranxt})} 
     1151\section[Tracer time evolution (\textit{tranxt.F90})] 
     1152{Tracer time evolution (\protect\mdl{tranxt})} 
    11321153\label{sec:TRA_nxt} 
    11331154%--------------------------------------------namdom----------------------------------------------------- 
     
    11371158 
    11381159Options are defined through the \ngn{namdom} namelist variables. 
    1139 The general framework for tracer time stepping is a modified leap-frog scheme \citep{Leclair_Madec_OM09}, 
     1160The general framework for tracer time stepping is a modified leap-frog scheme \citep{leclair.madec_OM09}, 
    11401161\ie a three level centred time scheme associated with a Asselin time filter (cf. \autoref{sec:STP_mLF}): 
    11411162\begin{equation} 
     
    11511172(\ie fluxes plus content in mass exchanges). 
    11521173$\gamma$ is initialized as \np{rn\_atfp} (\textbf{namelist} parameter). 
    1153 Its default value is \np{rn\_atfp}~\forcode{= 10.e-3}. 
     1174Its default value is \np{rn\_atfp}\forcode{ = 10.e-3}. 
    11541175Note that the forcing correction term in the filter is not applied in linear free surface 
    1155 (\jp{lk\_vvl}~\forcode{= .false.}) (see \autoref{subsec:TRA_sbc}). 
     1176(\jp{lk\_vvl}\forcode{ = .false.}) (see \autoref{subsec:TRA_sbc}). 
    11561177Not also that in constant volume case, the time stepping is performed on $T$, not on its content, $e_{3t}T$. 
    11571178 
     
    11661187% Equation of State (eosbn2)  
    11671188% ================================================================ 
    1168 \section{Equation of state (\protect\mdl{eosbn2}) } 
     1189\section[Equation of state (\textit{eosbn2.F90})] 
     1190{Equation of state (\protect\mdl{eosbn2})} 
    11691191\label{sec:TRA_eosbn2} 
    11701192%--------------------------------------------nameos----------------------------------------------------- 
     
    11761198%        Equation of State 
    11771199% ------------------------------------------------------------------------------------------------------------- 
    1178 \subsection{Equation of seawater (\protect\np{nn\_eos}~\forcode{= -1..1})} 
     1200\subsection[Equation of seawater (\forcode{nn_eos = {-1,1}})] 
     1201{Equation of seawater (\protect\np{nn\_eos}\forcode{ = {-1,1}})} 
    11791202\label{subsec:TRA_eos} 
    11801203 
     
    11861209Nonlinearities of the EOS are of major importance, in particular influencing the circulation through 
    11871210determination of the static stability below the mixed layer, 
    1188 thus controlling rates of exchange between the atmosphere and the ocean interior \citep{Roquet_JPO2015}. 
    1189 Therefore an accurate EOS based on either the 1980 equation of state (EOS-80, \cite{UNESCO1983}) or 
    1190 TEOS-10 \citep{TEOS10} standards should be used anytime a simulation of the real ocean circulation is attempted 
    1191 \citep{Roquet_JPO2015}. 
     1211thus controlling rates of exchange between the atmosphere and the ocean interior \citep{roquet.madec.ea_JPO15}. 
     1212Therefore an accurate EOS based on either the 1980 equation of state (EOS-80, \cite{fofonoff.millard_bk83}) or 
     1213TEOS-10 \citep{ioc.iapso_bk10} standards should be used anytime a simulation of the real ocean circulation is attempted 
     1214\citep{roquet.madec.ea_JPO15}. 
    11921215The use of TEOS-10 is highly recommended because 
    11931216\textit{(i)}   it is the new official EOS, 
     
    11951218\textit{(iii)} it uses Conservative Temperature and Absolute Salinity (instead of potential temperature and 
    11961219practical salinity for EOS-980, both variables being more suitable for use as model variables 
    1197 \citep{TEOS10, Graham_McDougall_JPO13}. 
     1220\citep{ioc.iapso_bk10, graham.mcdougall_JPO13}. 
    11981221EOS-80 is an obsolescent feature of the NEMO system, kept only for backward compatibility. 
    11991222For process studies, it is often convenient to use an approximation of the EOS. 
    1200 To that purposed, a simplified EOS (S-EOS) inspired by \citet{Vallis06} is also available. 
     1223To that purposed, a simplified EOS (S-EOS) inspired by \citet{vallis_bk06} is also available. 
    12011224 
    12021225In the computer code, a density anomaly, $d_a = \rho / \rho_o - 1$, is computed, with $\rho_o$ a reference density. 
     
    12041227This is a sensible choice for the reference density used in a Boussinesq ocean climate model, as, 
    12051228with the exception of only a small percentage of the ocean, 
    1206 density in the World Ocean varies by no more than 2$\%$ from that value \citep{Gill1982}. 
     1229density in the World Ocean varies by no more than 2$\%$ from that value \citep{gill_bk82}. 
    12071230 
    12081231Options are defined through the \ngn{nameos} namelist variables, and in particular \np{nn\_eos} which 
     
    12101233 
    12111234\begin{description} 
    1212 \item[\np{nn\_eos}~\forcode{= -1}] 
    1213   the polyTEOS10-bsq equation of seawater \citep{Roquet_OM2015} is used. 
     1235\item[\np{nn\_eos}\forcode{ = -1}] 
     1236  the polyTEOS10-bsq equation of seawater \citep{roquet.madec.ea_OM15} is used. 
    12141237  The accuracy of this approximation is comparable to the TEOS-10 rational function approximation, 
    12151238  but it is optimized for a boussinesq fluid and the polynomial expressions have simpler and 
     
    12171240  use in ocean models. 
    12181241  Note that a slightly higher precision polynomial form is now used replacement of 
    1219   the TEOS-10 rational function approximation for hydrographic data analysis \citep{TEOS10}. 
     1242  the TEOS-10 rational function approximation for hydrographic data analysis \citep{ioc.iapso_bk10}. 
    12201243  A key point is that conservative state variables are used: 
    12211244  Absolute Salinity (unit: g/kg, notation: $S_A$) and Conservative Temperature (unit: \deg{C}, notation: $\Theta$). 
    12221245  The pressure in decibars is approximated by the depth in meters. 
    12231246  With TEOS10, the specific heat capacity of sea water, $C_p$, is a constant. 
    1224   It is set to $C_p = 3991.86795711963~J\,Kg^{-1}\,^{\circ}K^{-1}$, according to \citet{TEOS10}. 
     1247  It is set to $C_p = 3991.86795711963~J\,Kg^{-1}\,^{\circ}K^{-1}$, according to \citet{ioc.iapso_bk10}. 
    12251248  Choosing polyTEOS10-bsq implies that the state variables used by the model are $\Theta$ and $S_A$. 
    12261249  In particular, the initial state deined by the user have to be given as \textit{Conservative} Temperature and 
     
    12291252  either computing the air-sea and ice-sea fluxes (forced mode) or 
    12301253  sending the SST field to the atmosphere (coupled mode). 
    1231 \item[\np{nn\_eos}~\forcode{= 0}] 
     1254\item[\np{nn\_eos}\forcode{ = 0}] 
    12321255  the polyEOS80-bsq equation of seawater is used. 
    12331256  It takes the same polynomial form as the polyTEOS10, but the coefficients have been optimized to 
     
    12381261  The pressure in decibars is approximated by the depth in meters. 
    12391262  With thsi EOS, the specific heat capacity of sea water, $C_p$, is a function of temperature, salinity and 
    1240   pressure \citep{UNESCO1983}. 
     1263  pressure \citep{fofonoff.millard_bk83}. 
    12411264  Nevertheless, a severe assumption is made in order to have a heat content ($C_p T_p$) which 
    12421265  is conserved by the model: $C_p$ is set to a constant value, the TEOS10 value. 
    1243 \item[\np{nn\_eos}~\forcode{= 1}] 
    1244   a simplified EOS (S-EOS) inspired by \citet{Vallis06} is chosen, 
     1266\item[\np{nn\_eos}\forcode{ = 1}] 
     1267  a simplified EOS (S-EOS) inspired by \citet{vallis_bk06} is chosen, 
    12451268  the coefficients of which has been optimized to fit the behavior of TEOS10 
    1246   (Roquet, personal comm.) (see also \citet{Roquet_JPO2015}). 
     1269  (Roquet, personal comm.) (see also \citet{roquet.madec.ea_JPO15}). 
    12471270  It provides a simplistic linear representation of both cabbeling and thermobaricity effects which 
    1248   is enough for a proper treatment of the EOS in theoretical studies \citep{Roquet_JPO2015}. 
     1271  is enough for a proper treatment of the EOS in theoretical studies \citep{roquet.madec.ea_JPO15}. 
    12491272  With such an equation of state there is no longer a distinction between 
    12501273  \textit{conservative} and \textit{potential} temperature, 
     
    13031326%        Brunt-V\"{a}is\"{a}l\"{a} Frequency 
    13041327% ------------------------------------------------------------------------------------------------------------- 
    1305 \subsection{Brunt-V\"{a}is\"{a}l\"{a} frequency (\protect\np{nn\_eos}~\forcode{= 0..2})} 
     1328\subsection[Brunt-V\"{a}is\"{a}l\"{a} frequency (\forcode{nn_eos = [0-2]})] 
     1329{Brunt-V\"{a}is\"{a}l\"{a} frequency (\protect\np{nn\_eos}\forcode{ = [0-2]})} 
    13061330\label{subsec:TRA_bn2} 
    13071331 
     
    13291353\label{subsec:TRA_fzp} 
    13301354 
    1331 The freezing point of seawater is a function of salinity and pressure \citep{UNESCO1983}: 
     1355The freezing point of seawater is a function of salinity and pressure \citep{fofonoff.millard_bk83}: 
    13321356\begin{equation} 
    13331357  \label{eq:tra_eos_fzp} 
     
    13571381% Horizontal Derivative in zps-coordinate  
    13581382% ================================================================ 
    1359 \section{Horizontal derivative in \textit{zps}-coordinate (\protect\mdl{zpshde})} 
     1383\section[Horizontal derivative in \textit{zps}-coordinate (\textit{zpshde.F90})] 
     1384{Horizontal derivative in \textit{zps}-coordinate (\protect\mdl{zpshde})} 
    13601385\label{sec:TRA_zpshde} 
    13611386 
     
    13631388I've changed "derivative" to "difference" and "mean" to "average"} 
    13641389 
    1365 With partial cells (\np{ln\_zps}~\forcode{= .true.}) at bottom and top (\np{ln\_isfcav}~\forcode{= .true.}), 
     1390With partial cells (\np{ln\_zps}\forcode{ = .true.}) at bottom and top (\np{ln\_isfcav}\forcode{ = .true.}), 
    13661391in general, tracers in horizontally adjacent cells live at different depths. 
    13671392Horizontal gradients of tracers are needed for horizontal diffusion (\mdl{traldf} module) and 
    13681393the hydrostatic pressure gradient calculations (\mdl{dynhpg} module). 
    1369 The partial cell properties at the top (\np{ln\_isfcav}~\forcode{= .true.}) are computed in the same way as 
     1394The partial cell properties at the top (\np{ln\_isfcav}\forcode{ = .true.}) are computed in the same way as 
    13701395for the bottom. 
    13711396So, only the bottom interpolation is explained below. 
     
    13791404\begin{figure}[!p] 
    13801405  \begin{center} 
    1381     \includegraphics[]{Fig_partial_step_scheme} 
     1406    \includegraphics[width=\textwidth]{Fig_partial_step_scheme} 
    13821407    \caption{ 
    13831408      \protect\label{fig:Partial_step_scheme} 
    13841409      Discretisation of the horizontal difference and average of tracers in the $z$-partial step coordinate 
    1385       (\protect\np{ln\_zps}~\forcode{= .true.}) in the case $(e3w_k^{i + 1} - e3w_k^i) > 0$. 
     1410      (\protect\np{ln\_zps}\forcode{ = .true.}) in the case $(e3w_k^{i + 1} - e3w_k^i) > 0$. 
    13861411      A linear interpolation is used to estimate $\widetilde T_k^{i + 1}$, 
    13871412      the tracer value at the depth of the shallower tracer point of the two adjacent bottom $T$-points. 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_ZDF.tex

    r10442 r11422  
    2525At the surface they are prescribed from the surface forcing (see \autoref{chap:SBC}), 
    2626while at the bottom they are set to zero for heat and salt, 
    27 unless a geothermal flux forcing is prescribed as a bottom boundary condition (\ie \key{trabbl} defined, 
     27unless a geothermal flux forcing is prescribed as a bottom boundary condition (\ie \np{ln\_trabbc} defined, 
    2828see \autoref{subsec:TRA_bbc}), and specified through a bottom friction parameterisation for momentum 
    29 (see \autoref{sec:ZDF_bfr}). 
     29(see \autoref{sec:ZDF_drg}).  
    3030 
    3131In this section we briefly discuss the various choices offered to compute the vertical eddy viscosity and 
     
    3333respectively (see \autoref{sec:TRA_zdf} and \autoref{sec:DYN_zdf}). 
    3434These coefficients can be assumed to be either constant, or a function of the local Richardson number, 
    35 or computed from a turbulent closure model (either TKE or GLS formulation). 
    36 The computation of these coefficients is initialized in the \mdl{zdfini} module and performed in 
    37 the \mdl{zdfric}, \mdl{zdftke} or \mdl{zdfgls} modules. 
     35or computed from a turbulent closure model (either TKE or GLS or OSMOSIS formulation). 
     36The computation of these coefficients is initialized in the \mdl{zdfphy} module and performed in 
     37the \mdl{zdfric}, \mdl{zdftke} or \mdl{zdfgls} or \mdl{zdfosm} modules. 
    3838The trends due to the vertical momentum and tracer diffusion, including the surface forcing, 
    3939are computed and added to the general trend in the \mdl{dynzdf} and \mdl{trazdf} modules, respectively.  
    40 These trends can be computed using either a forward time stepping scheme 
    41 (namelist parameter \np{ln\_zdfexp}\forcode{ = .true.}) or a backward time stepping scheme 
    42 (\np{ln\_zdfexp}\forcode{ = .false.}) depending on the magnitude of the mixing coefficients, 
    43 and thus of the formulation used (see \autoref{chap:STP}). 
    44  
    45 % ------------------------------------------------------------------------------------------------------------- 
    46 %        Constant  
    47 % ------------------------------------------------------------------------------------------------------------- 
    48 \subsection{Constant (\protect\key{zdfcst})} 
    49 \label{subsec:ZDF_cst} 
    50 %--------------------------------------------namzdf--------------------------------------------------------- 
     40%These trends can be computed using either a forward time stepping scheme 
     41%(namelist parameter \np{ln\_zdfexp}\forcode{ = .true.}) or a backward time stepping scheme 
     42%(\np{ln\_zdfexp}\forcode{ = .false.}) depending on the magnitude of the mixing coefficients, 
     43%and thus of the formulation used (see \autoref{chap:STP}). 
     44 
     45%--------------------------------------------namzdf-------------------------------------------------------- 
    5146 
    5247\nlst{namzdf} 
    5348%-------------------------------------------------------------------------------------------------------------- 
    5449 
     50% ------------------------------------------------------------------------------------------------------------- 
     51%        Constant  
     52% ------------------------------------------------------------------------------------------------------------- 
     53\subsection[Constant (\forcode{ln_zdfcst = .true.})] 
     54{Constant (\protect\np{ln\_zdfcst}\forcode{ = .true.})} 
     55\label{subsec:ZDF_cst} 
     56 
    5557Options are defined through the \ngn{namzdf} namelist variables. 
    56 When \key{zdfcst} is defined, the momentum and tracer vertical eddy coefficients are set to 
     58When \np{ln\_zdfcst} is defined, the momentum and tracer vertical eddy coefficients are set to 
    5759constant values over the whole ocean. 
    5860This is the crudest way to define the vertical ocean physics. 
    59 It is recommended that this option is only used in process studies, not in basin scale simulations. 
     61It is recommended to use this option only in process studies, not in basin scale simulations. 
    6062Typical values used in this case are: 
    6163\begin{align*} 
     
    7274%        Richardson Number Dependent 
    7375% ------------------------------------------------------------------------------------------------------------- 
    74 \subsection{Richardson number dependent (\protect\key{zdfric})} 
     76\subsection[Richardson number dependent (\forcode{ln_zdfric = .true.})] 
     77{Richardson number dependent (\protect\np{ln\_zdfric}\forcode{ = .true.})} 
    7578\label{subsec:ZDF_ric} 
    7679 
     
    8083%-------------------------------------------------------------------------------------------------------------- 
    8184 
    82 When \key{zdfric} is defined, a local Richardson number dependent formulation for the vertical momentum and 
     85When \np{ln\_zdfric}\forcode{ = .true.}, a local Richardson number dependent formulation for the vertical momentum and 
    8386tracer eddy coefficients is set through the \ngn{namzdf\_ric} namelist variables. 
    8487The vertical mixing coefficients are diagnosed from the large scale variables computed by the model.  
     
    8790a dependency between the vertical eddy coefficients and the local Richardson number 
    8891(\ie the ratio of stratification to vertical shear). 
    89 Following \citet{Pacanowski_Philander_JPO81}, the following formulation has been implemented: 
     92Following \citet{pacanowski.philander_JPO81}, the following formulation has been implemented: 
    9093\[ 
    9194  % \label{eq:zdfric} 
     
    124127The final $h_{e}$ is further constrained by the adjustable bounds \np{rn\_mldmin} and \np{rn\_mldmax}. 
    125128Once $h_{e}$ is computed, the vertical eddy coefficients within $h_{e}$ are set to 
    126 the empirical values \np{rn\_wtmix} and \np{rn\_wvmix} \citep{Lermusiaux2001}. 
     129the empirical values \np{rn\_wtmix} and \np{rn\_wvmix} \citep{lermusiaux_JMS01}. 
    127130 
    128131% ------------------------------------------------------------------------------------------------------------- 
    129132%        TKE Turbulent Closure Scheme  
    130133% ------------------------------------------------------------------------------------------------------------- 
    131 \subsection{TKE turbulent closure scheme (\protect\key{zdftke})} 
     134\subsection[TKE turbulent closure scheme (\forcode{ln_zdftke = .true.})] 
     135{TKE turbulent closure scheme (\protect\np{ln\_zdftke}\forcode{ = .true.})} 
    132136\label{subsec:ZDF_tke} 
    133  
    134137%--------------------------------------------namzdf_tke-------------------------------------------------- 
    135138 
     
    140143a prognostic equation for $\bar{e}$, the turbulent kinetic energy, 
    141144and a closure assumption for the turbulent length scales. 
    142 This turbulent closure model has been developed by \citet{Bougeault1989} in the atmospheric case, 
    143 adapted by \citet{Gaspar1990} for the oceanic case, and embedded in OPA, the ancestor of NEMO, 
    144 by \citet{Blanke1993} for equatorial Atlantic simulations. 
    145 Since then, significant modifications have been introduced by \citet{Madec1998} in both the implementation and 
     145This turbulent closure model has been developed by \citet{bougeault.lacarrere_MWR89} in the atmospheric case, 
     146adapted by \citet{gaspar.gregoris.ea_JGR90} for the oceanic case, and embedded in OPA, the ancestor of NEMO, 
     147by \citet{blanke.delecluse_JPO93} for equatorial Atlantic simulations. 
     148Since then, significant modifications have been introduced by \citet{madec.delecluse.ea_NPM98} in both the implementation and 
    146149the formulation of the mixing length scale. 
    147150The time evolution of $\bar{e}$ is the result of the production of $\bar{e}$ through vertical shear, 
    148 its destruction through stratification, its vertical diffusion, and its dissipation of \citet{Kolmogorov1942} type: 
     151its destruction through stratification, its vertical diffusion, and its dissipation of \citet{kolmogorov_IANS42} type: 
    149152\begin{equation} 
    150153  \label{eq:zdftke_e} 
     
    168171$P_{rt}$ is the Prandtl number, $K_m$ and $K_\rho$ are the vertical eddy viscosity and diffusivity coefficients. 
    169172The constants $C_k =  0.1$ and $C_\epsilon = \sqrt {2} /2$ $\approx 0.7$ are designed to deal with 
    170 vertical mixing at any depth \citep{Gaspar1990}.  
     173vertical mixing at any depth \citep{gaspar.gregoris.ea_JGR90}.  
    171174They are set through namelist parameters \np{nn\_ediff} and \np{nn\_ediss}. 
    172 $P_{rt}$ can be set to unity or, following \citet{Blanke1993}, be a function of the local Richardson number, $R_i$: 
     175$P_{rt}$ can be set to unity or, following \citet{blanke.delecluse_JPO93}, be a function of the local Richardson number, $R_i$: 
    173176\begin{align*} 
    174177  % \label{eq:prt} 
     
    180183  \end{cases} 
    181184\end{align*} 
    182 Options are defined through the  \ngn{namzdfy\_tke} namelist variables. 
    183185The choice of $P_{rt}$ is controlled by the \np{nn\_pdl} namelist variable. 
    184186 
    185187At the sea surface, the value of $\bar{e}$ is prescribed from the wind stress field as 
    186188$\bar{e}_o = e_{bb} |\tau| / \rho_o$, with $e_{bb}$ the \np{rn\_ebb} namelist parameter. 
    187 The default value of $e_{bb}$ is 3.75. \citep{Gaspar1990}), however a much larger value can be used when 
     189The default value of $e_{bb}$ is 3.75. \citep{gaspar.gregoris.ea_JGR90}), however a much larger value can be used when 
    188190taking into account the surface wave breaking (see below Eq. \autoref{eq:ZDF_Esbc}). 
    189191The bottom value of TKE is assumed to be equal to the value of the level just above. 
     
    191193the numerical scheme does not ensure its positivity. 
    192194To overcome this problem, a cut-off in the minimum value of $\bar{e}$ is used (\np{rn\_emin} namelist parameter). 
    193 Following \citet{Gaspar1990}, the cut-off value is set to $\sqrt{2}/2~10^{-6}~m^2.s^{-2}$. 
    194 This allows the subsequent formulations to match that of \citet{Gargett1984} for the diffusion in 
     195Following \citet{gaspar.gregoris.ea_JGR90}, the cut-off value is set to $\sqrt{2}/2~10^{-6}~m^2.s^{-2}$. 
     196This allows the subsequent formulations to match that of \citet{gargett_JMR84} for the diffusion in 
    195197the thermocline and deep ocean :  $K_\rho = 10^{-3} / N$. 
    196198In addition, a cut-off is applied on $K_m$ and $K_\rho$ to avoid numerical instabilities associated with 
    197199too weak vertical diffusion. 
    198200They must be specified at least larger than the molecular values, and are set through \np{rn\_avm0} and 
    199 \np{rn\_avt0} (namzdf namelist, see \autoref{subsec:ZDF_cst}). 
     201\np{rn\_avt0} (\ngn{namzdf} namelist, see \autoref{subsec:ZDF_cst}). 
    200202 
    201203\subsubsection{Turbulent length scale} 
    202204 
    203205For computational efficiency, the original formulation of the turbulent length scales proposed by 
    204 \citet{Gaspar1990} has been simplified. 
     206\citet{gaspar.gregoris.ea_JGR90} has been simplified. 
    205207Four formulations are proposed, the choice of which is controlled by the \np{nn\_mxl} namelist parameter. 
    206 The first two are based on the following first order approximation \citep{Blanke1993}: 
     208The first two are based on the following first order approximation \citep{blanke.delecluse_JPO93}: 
    207209\begin{equation} 
    208210  \label{eq:tke_mxl0_1} 
     
    212214The resulting length scale is bounded by the distance to the surface or to the bottom 
    213215(\np{nn\_mxl}\forcode{ = 0}) or by the local vertical scale factor (\np{nn\_mxl}\forcode{ = 1}). 
    214 \citet{Blanke1993} notice that this simplification has two major drawbacks: 
     216\citet{blanke.delecluse_JPO93} notice that this simplification has two major drawbacks: 
    215217it makes no sense for locally unstable stratification and the computation no longer uses all 
    216218the information contained in the vertical density profile. 
    217 To overcome these drawbacks, \citet{Madec1998} introduces the \np{nn\_mxl}\forcode{ = 2..3} cases, 
     219To overcome these drawbacks, \citet{madec.delecluse.ea_NPM98} introduces the \np{nn\_mxl}\forcode{ = 2, 3} cases, 
    218220which add an extra assumption concerning the vertical gradient of the computed length scale. 
    219221So, the length scales are first evaluated as in \autoref{eq:tke_mxl0_1} and then bounded such that: 
     
    225227\autoref{eq:tke_mxl_constraint} means that the vertical variations of the length scale cannot be larger than 
    226228the variations of depth. 
    227 It provides a better approximation of the \citet{Gaspar1990} formulation while being much less  
     229It provides a better approximation of the \citet{gaspar.gregoris.ea_JGR90} formulation while being much less  
    228230time consuming. 
    229231In particular, it allows the length scale to be limited not only by the distance to the surface or 
     
    237239\begin{figure}[!t] 
    238240  \begin{center} 
    239     \includegraphics[width=1.00\textwidth]{Fig_mixing_length} 
     241    \includegraphics[width=\textwidth]{Fig_mixing_length} 
    240242    \caption{ 
    241243      \protect\label{fig:mixing_length} 
     
    258260In the \np{nn\_mxl}\forcode{ = 2} case, the dissipation and mixing length scales take the same value: 
    259261$ l_k=  l_\epsilon = \min \left(\ l_{up} \;,\;  l_{dwn}\ \right)$, while in the \np{nn\_mxl}\forcode{ = 3} case, 
    260 the dissipation and mixing turbulent length scales are give as in \citet{Gaspar1990}: 
     262the dissipation and mixing turbulent length scales are give as in \citet{gaspar.gregoris.ea_JGR90}: 
    261263\[ 
    262264  % \label{eq:tke_mxl_gaspar} 
     
    270272Usually the surface scale is given by $l_o = \kappa \,z_o$ where $\kappa = 0.4$ is von Karman's constant and 
    271273$z_o$ the roughness parameter of the surface. 
    272 Assuming $z_o=0.1$~m \citep{Craig_Banner_JPO94} leads to a 0.04~m, the default value of \np{rn\_mxl0}. 
     274Assuming $z_o=0.1$~m \citep{craig.banner_JPO94} leads to a 0.04~m, the default value of \np{rn\_mxl0}. 
    273275In the ocean interior a minimum length scale is set to recover the molecular viscosity when 
    274276$\bar{e}$ reach its minimum value ($1.10^{-6}= C_k\, l_{min} \,\sqrt{\bar{e}_{min}}$ ). 
     
    277279%-----------------------------------------------------------------------% 
    278280 
    279 Following \citet{Mellor_Blumberg_JPO04}, the TKE turbulence closure model has been modified to 
     281Following \citet{mellor.blumberg_JPO04}, the TKE turbulence closure model has been modified to 
    280282include the effect of surface wave breaking energetics. 
    281283This results in a reduction of summertime surface temperature when the mixed layer is relatively shallow. 
    282 The \citet{Mellor_Blumberg_JPO04} modifications acts on surface length scale and TKE values and 
     284The \citet{mellor.blumberg_JPO04} modifications acts on surface length scale and TKE values and 
    283285air-sea drag coefficient.  
    284 The latter concerns the bulk formulea and is not discussed here.  
    285  
    286 Following \citet{Craig_Banner_JPO94}, the boundary condition on surface TKE value is : 
     286The latter concerns the bulk formulae and is not discussed here.  
     287 
     288Following \citet{craig.banner_JPO94}, the boundary condition on surface TKE value is : 
    287289\begin{equation} 
    288290  \label{eq:ZDF_Esbc} 
    289291  \bar{e}_o = \frac{1}{2}\,\left(  15.8\,\alpha_{CB} \right)^{2/3} \,\frac{|\tau|}{\rho_o} 
    290292\end{equation} 
    291 where $\alpha_{CB}$ is the \citet{Craig_Banner_JPO94} constant of proportionality which depends on the ''wave age'', 
    292 ranging from 57 for mature waves to 146 for younger waves \citep{Mellor_Blumberg_JPO04}.  
     293where $\alpha_{CB}$ is the \citet{craig.banner_JPO94} constant of proportionality which depends on the ''wave age'', 
     294ranging from 57 for mature waves to 146 for younger waves \citep{mellor.blumberg_JPO04}.  
    293295The boundary condition on the turbulent length scale follows the Charnock's relation: 
    294296\begin{equation} 
     
    297299\end{equation} 
    298300where $\kappa=0.40$ is the von Karman constant, and $\beta$ is the Charnock's constant. 
    299 \citet{Mellor_Blumberg_JPO04} suggest $\beta = 2.10^{5}$ the value chosen by 
    300 \citet{Stacey_JPO99} citing observation evidence, and 
     301\citet{mellor.blumberg_JPO04} suggest $\beta = 2.10^{5}$ the value chosen by 
     302\citet{stacey_JPO99} citing observation evidence, and 
    301303$\alpha_{CB} = 100$ the Craig and Banner's value. 
    302304As the surface boundary condition on TKE is prescribed through $\bar{e}_o = e_{bb} |\tau| / \rho_o$, 
    303305with $e_{bb}$ the \np{rn\_ebb} namelist parameter, setting \np{rn\_ebb}\forcode{ = 67.83} corresponds  
    304306to $\alpha_{CB} = 100$. 
    305 Further setting  \np{ln\_mxl0} to true applies \autoref{eq:ZDF_Lsbc} as surface boundary condition on length scale, 
     307Further setting  \np{ln\_mxl0=.true.},  applies \autoref{eq:ZDF_Lsbc} as the surface boundary condition on the length scale, 
    306308with $\beta$ hard coded to the Stacey's value. 
    307 Note that a minimal threshold of \np{rn\_emin0}$=10^{-4}~m^2.s^{-2}$ (namelist parameters) is applied on 
     309Note that a minimal threshold of \np{rn\_emin0}$=10^{-4}~m^2.s^{-2}$ (namelist parameters) is applied on the  
    308310surface $\bar{e}$ value. 
    309311 
     
    315317Although LC have nothing to do with convection, the circulation pattern is rather similar to 
    316318so-called convective rolls in the atmospheric boundary layer. 
    317 The detailed physics behind LC is described in, for example, \citet{Craik_Leibovich_JFM76}. 
     319The detailed physics behind LC is described in, for example, \citet{craik.leibovich_JFM76}. 
    318320The prevailing explanation is that LC arise from a nonlinear interaction between the Stokes drift and 
    319321wind drift currents.  
    320322 
    321323Here we introduced in the TKE turbulent closure the simple parameterization of Langmuir circulations proposed by 
    322 \citep{Axell_JGR02} for a $k-\epsilon$ turbulent closure. 
     324\citep{axell_JGR02} for a $k-\epsilon$ turbulent closure. 
    323325The parameterization, tuned against large-eddy simulation, includes the whole effect of LC in 
    324 an extra source terms of TKE, $P_{LC}$. 
     326an extra source term of TKE, $P_{LC}$. 
    325327The presence of $P_{LC}$ in \autoref{eq:zdftke_e}, the TKE equation, is controlled by setting \np{ln\_lc} to 
    326 \forcode{.true.} in the namtke namelist. 
     328\forcode{.true.} in the \ngn{namzdf\_tke} namelist. 
    327329  
    328 By making an analogy with the characteristic convective velocity scale (\eg, \citet{D'Alessio_al_JPO98}), 
     330By making an analogy with the characteristic convective velocity scale (\eg, \citet{dalessio.abdella.ea_JPO98}), 
    329331$P_{LC}$ is assumed to be :  
    330332\[ 
     
    334336With no information about the wave field, $w_{LC}$ is assumed to be proportional to  
    335337the Stokes drift $u_s = 0.377\,\,|\tau|^{1/2}$, where $|\tau|$ is the surface wind stress module  
    336 \footnote{Following \citet{Li_Garrett_JMR93}, the surface Stoke drift velocity may be expressed as 
     338\footnote{Following \citet{li.garrett_JMR93}, the surface Stoke drift velocity may be expressed as 
    337339  $u_s =  0.016 \,|U_{10m}|$. 
    338340  Assuming an air density of $\rho_a=1.22 \,Kg/m^3$ and a drag coefficient of 
     
    350352  \end{cases} 
    351353\] 
    352 where $c_{LC} = 0.15$ has been chosen by \citep{Axell_JGR02} as a good compromise to fit LES data. 
     354where $c_{LC} = 0.15$ has been chosen by \citep{axell_JGR02} as a good compromise to fit LES data. 
    353355The chosen value yields maximum vertical velocities $w_{LC}$ of the order of a few centimeters per second. 
    354356The value of $c_{LC}$ is set through the \np{rn\_lc} namelist parameter, 
    355 having in mind that it should stay between 0.15 and 0.54 \citep{Axell_JGR02}.  
     357having in mind that it should stay between 0.15 and 0.54 \citep{axell_JGR02}.  
    356358 
    357359The $H_{LC}$ is estimated in a similar way as the turbulent length scale of TKE equations: 
    358 $H_{LC}$ is depth to which a water parcel with kinetic energy due to Stoke drift can reach on its own by 
     360$H_{LC}$ is the depth to which a water parcel with kinetic energy due to Stoke drift can reach on its own by 
    359361converting its kinetic energy to potential energy, according to  
    360362\[ 
     
    368370produce mixed-layer depths that are too shallow during summer months and windy conditions. 
    369371This bias is particularly acute over the Southern Ocean. 
    370 To overcome this systematic bias, an ad hoc parameterization is introduced into the TKE scheme \cite{Rodgers_2014}.  
     372To overcome this systematic bias, an ad hoc parameterization is introduced into the TKE scheme \cite{rodgers.aumont.ea_B14}.  
    371373The parameterization is an empirical one, \ie not derived from theoretical considerations, 
    372374but rather is meant to account for observed processes that affect the density structure of  
     
    383385\end{equation} 
    384386where $z$ is the depth, $e_s$ is TKE surface boundary condition, $f_r$ is the fraction of the surface TKE that 
    385 penetrate in the ocean, $h_\tau$ is a vertical mixing length scale that controls exponential shape of 
     387penetrates in the ocean, $h_\tau$ is a vertical mixing length scale that controls exponential shape of 
    386388the penetration, and $f_i$ is the ice concentration 
    387 (no penetration if $f_i=1$, that is if the ocean is entirely covered by sea-ice). 
     389(no penetration if $f_i=1$, \ie if the ocean is entirely covered by sea-ice). 
    388390The value of $f_r$, usually a few percents, is specified through \np{rn\_efr} namelist parameter. 
    389391The vertical mixing length scale, $h_\tau$, can be set as a 10~m uniform value (\np{nn\_etau}\forcode{ = 0}) or 
     
    391393(\np{nn\_etau}\forcode{ = 1}).  
    392394 
    393 Note that two other option existe, \np{nn\_etau}\forcode{ = 2..3}. 
     395Note that two other option exist, \np{nn\_etau}\forcode{ = 2, 3}. 
    394396They correspond to applying \autoref{eq:ZDF_Ehtau} only at the base of the mixed layer, 
    395 or to using the high frequency part of the stress to evaluate the fraction of TKE that penetrate the ocean.  
     397or to using the high frequency part of the stress to evaluate the fraction of TKE that penetrates the ocean.  
    396398Those two options are obsolescent features introduced for test purposes. 
    397399They will be removed in the next release.  
     400 
     401% This should be explain better below what this rn_eice parameter is meant for: 
     402In presence of Sea Ice, the value of this mixing can be modulated by the \np{rn\_eice} namelist parameter. 
     403This parameter varies from \forcode{0} for no effect to \forcode{4} to suppress the TKE input into the ocean when Sea Ice concentration 
     404is greater than 25\%.  
    398405 
    399406% from Burchard et al OM 2008 :  
     
    406413 
    407414% ------------------------------------------------------------------------------------------------------------- 
    408 %        TKE discretization considerations 
    409 % ------------------------------------------------------------------------------------------------------------- 
    410 \subsection{TKE discretization considerations (\protect\key{zdftke})} 
     415%        GLS Generic Length Scale Scheme  
     416% ------------------------------------------------------------------------------------------------------------- 
     417\subsection[GLS: Generic Length Scale (\forcode{ln_zdfgls = .true.})] 
     418{GLS: Generic Length Scale (\protect\np{ln\_zdfgls}\forcode{ = .true.})} 
     419\label{subsec:ZDF_gls} 
     420 
     421%--------------------------------------------namzdf_gls--------------------------------------------------------- 
     422 
     423\nlst{namzdf_gls} 
     424%-------------------------------------------------------------------------------------------------------------- 
     425 
     426The Generic Length Scale (GLS) scheme is a turbulent closure scheme based on two prognostic equations: 
     427one for the turbulent kinetic energy $\bar {e}$, and another for the generic length scale, 
     428$\psi$ \citep{umlauf.burchard_JMR03, umlauf.burchard_CSR05}. 
     429This later variable is defined as: $\psi = {C_{0\mu}}^{p} \ {\bar{e}}^{m} \ l^{n}$,  
     430where the triplet $(p, m, n)$ value given in Tab.\autoref{tab:GLS} allows to recover a number of 
     431well-known turbulent closures ($k$-$kl$ \citep{mellor.yamada_RG82}, $k$-$\epsilon$ \citep{rodi_JGR87}, 
     432$k$-$\omega$ \citep{wilcox_AJ88} among others \citep{umlauf.burchard_JMR03,kantha.carniel_JMR03}).  
     433The GLS scheme is given by the following set of equations: 
     434\begin{equation} 
     435  \label{eq:zdfgls_e} 
     436  \frac{\partial \bar{e}}{\partial t} = 
     437  \frac{K_m}{\sigma_e e_3 }\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 
     438      +\left( \frac{\partial v}{\partial k} \right)^2} \right] 
     439  -K_\rho \,N^2 
     440  +\frac{1}{e_3}\,\frac{\partial}{\partial k} \left[ \frac{K_m}{e_3}\,\frac{\partial \bar{e}}{\partial k} \right] 
     441  - \epsilon 
     442\end{equation} 
     443 
     444\[ 
     445  % \label{eq:zdfgls_psi} 
     446  \begin{split} 
     447    \frac{\partial \psi}{\partial t} =& \frac{\psi}{\bar{e}} \left\{ 
     448      \frac{C_1\,K_m}{\sigma_{\psi} {e_3}}\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 
     449          +\left( \frac{\partial v}{\partial k} \right)^2} \right] 
     450      - C_3 \,K_\rho\,N^2   - C_2 \,\epsilon \,Fw   \right\}             \\ 
     451    &+\frac{1}{e_3}  \;\frac{\partial }{\partial k}\left[ {\frac{K_m}{e_3 } 
     452        \;\frac{\partial \psi}{\partial k}} \right]\; 
     453  \end{split} 
     454\] 
     455 
     456\[ 
     457  % \label{eq:zdfgls_kz} 
     458  \begin{split} 
     459    K_m    &= C_{\mu} \ \sqrt {\bar{e}} \ l         \\ 
     460    K_\rho &= C_{\mu'}\ \sqrt {\bar{e}} \ l 
     461  \end{split} 
     462\] 
     463 
     464\[ 
     465  % \label{eq:zdfgls_eps} 
     466  {\epsilon} = C_{0\mu} \,\frac{\bar {e}^{3/2}}{l} \; 
     467\] 
     468where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}) and 
     469$\epsilon$ the dissipation rate.  
     470The constants $C_1$, $C_2$, $C_3$, ${\sigma_e}$, ${\sigma_{\psi}}$ and the wall function ($Fw$) depends of 
     471the choice of the turbulence model. 
     472Four different turbulent models are pre-defined (\autoref{tab:GLS}). 
     473They are made available through the \np{nn\_clo} namelist parameter.  
     474 
     475%--------------------------------------------------TABLE-------------------------------------------------- 
     476\begin{table}[htbp] 
     477  \begin{center} 
     478    % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}c} 
     479    \begin{tabular}{ccccc} 
     480      &   $k-kl$   & $k-\epsilon$ & $k-\omega$ &   generic   \\ 
     481      % & \citep{mellor.yamada_RG82} &  \citep{rodi_JGR87}       & \citep{wilcox_AJ88} &                 \\ 
     482      \hline 
     483      \hline 
     484      \np{nn\_clo}     & \textbf{0} &   \textbf{1}  &   \textbf{2}   &    \textbf{3}   \\ 
     485      \hline 
     486      $( p , n , m )$          &   ( 0 , 1 , 1 )   & ( 3 , 1.5 , -1 )   & ( -1 , 0.5 , -1 )    &  ( 2 , 1 , -0.67 )  \\ 
     487      $\sigma_k$      &    2.44         &     1.              &      2.                &      0.8          \\ 
     488      $\sigma_\psi$  &    2.44         &     1.3            &      2.                 &       1.07       \\ 
     489      $C_1$              &      0.9         &     1.44          &      0.555          &       1.           \\ 
     490      $C_2$              &      0.5         &     1.92          &      0.833          &       1.22       \\ 
     491      $C_3$              &      1.           &     1.              &      1.                &       1.           \\ 
     492      $F_{wall}$        &      Yes        &       --             &     --                  &      --          \\ 
     493      \hline 
     494      \hline 
     495    \end{tabular} 
     496    \caption{ 
     497      \protect\label{tab:GLS} 
     498      Set of predefined GLS parameters, or equivalently predefined turbulence models available with 
     499      \protect\np{ln\_zdfgls}\forcode{ = .true.} and controlled by the \protect\np{nn\_clos} namelist variable in \protect\ngn{namzdf\_gls}. 
     500    } 
     501  \end{center} 
     502\end{table} 
     503%-------------------------------------------------------------------------------------------------------------- 
     504 
     505In the Mellor-Yamada model, the negativity of $n$ allows to use a wall function to force the convergence of 
     506the mixing length towards $\kappa z_b$ ($\kappa$ is the Von Karman constant and $z_b$ the rugosity length scale) value near physical boundaries 
     507(logarithmic boundary layer law). 
     508$C_{\mu}$ and $C_{\mu'}$ are calculated from stability function proposed by \citet{galperin.kantha.ea_JAS88}, 
     509or by \citet{kantha.clayson_JGR94} or one of the two functions suggested by \citet{canuto.howard.ea_JPO01} 
     510(\np{nn\_stab\_func}\forcode{ = 0, 3}, resp.).   
     511The value of $C_{0\mu}$ depends on the choice of the stability function. 
     512 
     513The surface and bottom boundary condition on both $\bar{e}$ and $\psi$ can be calculated thanks to Dirichlet or 
     514Neumann condition through \np{nn\_bc\_surf} and \np{nn\_bc\_bot}, resp. 
     515As for TKE closure, the wave effect on the mixing is considered when 
     516\np{rn\_crban}\forcode{ > 0.} \citep{craig.banner_JPO94, mellor.blumberg_JPO04}. 
     517The \np{rn\_crban} namelist parameter is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and 
     518\np{rn\_charn} provides the value of $\beta$ in \autoref{eq:ZDF_Lsbc}.  
     519 
     520The $\psi$ equation is known to fail in stably stratified flows, and for this reason 
     521almost all authors apply a clipping of the length scale as an \textit{ad hoc} remedy. 
     522With this clipping, the maximum permissible length scale is determined by $l_{max} = c_{lim} \sqrt{2\bar{e}}/ N$. 
     523A value of $c_{lim} = 0.53$ is often used \citep{galperin.kantha.ea_JAS88}. 
     524\cite{umlauf.burchard_CSR05} show that the value of the clipping factor is of crucial importance for 
     525the entrainment depth predicted in stably stratified situations, 
     526and that its value has to be chosen in accordance with the algebraic model for the turbulent fluxes. 
     527The clipping is only activated if \np{ln\_length\_lim}\forcode{ = .true.}, 
     528and the $c_{lim}$ is set to the \np{rn\_clim\_galp} value. 
     529 
     530The time and space discretization of the GLS equations follows the same energetic consideration as for 
     531the TKE case described in \autoref{subsec:ZDF_tke_ene} \citep{burchard_OM02}. 
     532Evaluation of the 4 GLS turbulent closure schemes can be found in \citet{warner.sherwood.ea_OM05} in ROMS model and 
     533 in \citet{reffray.guillaume.ea_GMD15} for the \NEMO model. 
     534 
     535 
     536% ------------------------------------------------------------------------------------------------------------- 
     537%        OSM OSMOSIS BL Scheme  
     538% ------------------------------------------------------------------------------------------------------------- 
     539\subsection[OSM: OSMosis boundary layer scheme (\forcode{ln_zdfosm = .true.})] 
     540{OSM: OSMosis boundary layer scheme (\protect\np{ln\_zdfosm}\forcode{ = .true.})} 
     541\label{subsec:ZDF_osm} 
     542%--------------------------------------------namzdf_osm--------------------------------------------------------- 
     543 
     544\nlst{namzdf_osm} 
     545%-------------------------------------------------------------------------------------------------------------- 
     546 
     547The OSMOSIS turbulent closure scheme is based on......   TBC 
     548 
     549% ------------------------------------------------------------------------------------------------------------- 
     550%        TKE and GLS discretization considerations 
     551% ------------------------------------------------------------------------------------------------------------- 
     552\subsection[ Discrete energy conservation for TKE and GLS schemes] 
     553{Discrete energy conservation for TKE and GLS schemes} 
    411554\label{subsec:ZDF_tke_ene} 
    412555 
     
    414557\begin{figure}[!t] 
    415558  \begin{center} 
    416     \includegraphics[width=1.00\textwidth]{Fig_ZDF_TKE_time_scheme} 
     559    \includegraphics[width=\textwidth]{Fig_ZDF_TKE_time_scheme} 
    417560    \caption{ 
    418561      \protect\label{fig:TKE_time_scheme} 
    419       Illustration of the TKE time integration and its links to the momentum and tracer time integration. 
     562      Illustration of the subgrid kinetic energy integration in GLS and TKE schemes and its links to the momentum and tracer time integration. 
    420563    } 
    421564  \end{center}   
     
    424567 
    425568The production of turbulence by vertical shear (the first term of the right hand side of 
    426 \autoref{eq:zdftke_e}) should balance the loss of kinetic energy associated with the vertical momentum diffusion 
     569\autoref{eq:zdftke_e}) and  \autoref{eq:zdfgls_e}) should balance the loss of kinetic energy associated with the vertical momentum diffusion 
    427570(first line in \autoref{eq:PE_zdf}). 
    428 To do so a special care have to be taken for both the time and space discretization of 
    429 the TKE equation \citep{Burchard_OM02,Marsaleix_al_OM08}. 
     571To do so a special care has to be taken for both the time and space discretization of 
     572the kinetic energy equation \citep{burchard_OM02,marsaleix.auclair.ea_OM08}. 
    430573 
    431574Let us first address the time stepping issue. \autoref{fig:TKE_time_scheme} shows how 
    432575the two-level Leap-Frog time stepping of the momentum and tracer equations interplays with 
    433 the one-level forward time stepping of TKE equation. 
     576the one-level forward time stepping of the equation for $\bar{e}$. 
    434577With this framework, the total loss of kinetic energy (in 1D for the demonstration) due to 
    435578the vertical momentum diffusion is obtained by multiplying this quantity by $u^t$ and 
     
    456599 
    457600A similar consideration applies on the destruction rate of $\bar{e}$ due to stratification 
    458 (second term of the right hand side of \autoref{eq:zdftke_e}). 
     601(second term of the right hand side of \autoref{eq:zdftke_e} and \autoref{eq:zdfgls_e}). 
    459602This term must balance the input of potential energy resulting from vertical mixing. 
    460 The rate of change of potential energy (in 1D for the demonstration) due vertical mixing is obtained by 
    461 multiplying vertical density diffusion tendency by $g\,z$ and and summing the result vertically: 
     603The rate of change of potential energy (in 1D for the demonstration) due to vertical mixing is obtained by 
     604multiplying the vertical density diffusion tendency by $g\,z$ and and summing the result vertically: 
    462605\begin{equation} 
    463606  \label{eq:energ2} 
     
    475618The second term is minus the destruction rate of  $\bar{e}$ due to stratification. 
    476619Therefore \autoref{eq:energ1} implies that, to be energetically consistent, 
    477 the product ${K_\rho}^{t-\rdt}\,(N^2)^t$ should be used in \autoref{eq:zdftke_e}, the TKE equation. 
     620the product ${K_\rho}^{t-\rdt}\,(N^2)^t$ should be used in \autoref{eq:zdftke_e} and  \autoref{eq:zdfgls_e}. 
    478621 
    479622Let us now address the space discretization issue. 
     
    483626By redoing the \autoref{eq:energ1} in the 3D case, it can be shown that the product of eddy coefficient by 
    484627the shear at $t$ and $t-\rdt$ must be performed prior to the averaging. 
    485 Furthermore, the possible time variation of $e_3$ (\key{vvl} case) have to be taken into account. 
     628Furthermore, the time variation of $e_3$ has be taken into account. 
    486629 
    487630The above energetic considerations leads to the following final discrete form for the TKE equation: 
     
    507650are time stepped using a backward scheme (see\autoref{sec:STP_forward_imp}). 
    508651Note that the Kolmogorov term has been linearized in time in order to render the implicit computation possible. 
    509 The restart of the TKE scheme requires the storage of $\bar {e}$, $K_m$, $K_\rho$ and $l_\epsilon$ as 
    510 they all appear in the right hand side of \autoref{eq:zdftke_ene}. 
    511 For the latter, it is in fact the ratio $\sqrt{\bar{e}}/l_\epsilon$ which is stored.  
    512  
    513 % ------------------------------------------------------------------------------------------------------------- 
    514 %        GLS Generic Length Scale Scheme  
    515 % ------------------------------------------------------------------------------------------------------------- 
    516 \subsection{GLS: Generic Length Scale (\protect\key{zdfgls})} 
    517 \label{subsec:ZDF_gls} 
    518  
    519 %--------------------------------------------namzdf_gls--------------------------------------------------------- 
    520  
    521 \nlst{namzdf_gls} 
    522 %-------------------------------------------------------------------------------------------------------------- 
    523  
    524 The Generic Length Scale (GLS) scheme is a turbulent closure scheme based on two prognostic equations: 
    525 one for the turbulent kinetic energy $\bar {e}$, and another for the generic length scale, 
    526 $\psi$ \citep{Umlauf_Burchard_JMS03, Umlauf_Burchard_CSR05}. 
    527 This later variable is defined as: $\psi = {C_{0\mu}}^{p} \ {\bar{e}}^{m} \ l^{n}$,  
    528 where the triplet $(p, m, n)$ value given in Tab.\autoref{tab:GLS} allows to recover a number of 
    529 well-known turbulent closures ($k$-$kl$ \citep{Mellor_Yamada_1982}, $k$-$\epsilon$ \citep{Rodi_1987}, 
    530 $k$-$\omega$ \citep{Wilcox_1988} among others \citep{Umlauf_Burchard_JMS03,Kantha_Carniel_CSR05}).  
    531 The GLS scheme is given by the following set of equations: 
    532 \begin{equation} 
    533   \label{eq:zdfgls_e} 
    534   \frac{\partial \bar{e}}{\partial t} = 
    535   \frac{K_m}{\sigma_e e_3 }\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 
    536       +\left( \frac{\partial v}{\partial k} \right)^2} \right] 
    537   -K_\rho \,N^2 
    538   +\frac{1}{e_3}\,\frac{\partial}{\partial k} \left[ \frac{K_m}{e_3}\,\frac{\partial \bar{e}}{\partial k} \right] 
    539   - \epsilon 
    540 \end{equation} 
    541  
    542 \[ 
    543   % \label{eq:zdfgls_psi} 
    544   \begin{split} 
    545     \frac{\partial \psi}{\partial t} =& \frac{\psi}{\bar{e}} \left\{ 
    546       \frac{C_1\,K_m}{\sigma_{\psi} {e_3}}\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2 
    547           +\left( \frac{\partial v}{\partial k} \right)^2} \right] 
    548       - C_3 \,K_\rho\,N^2   - C_2 \,\epsilon \,Fw   \right\}             \\ 
    549     &+\frac{1}{e_3}  \;\frac{\partial }{\partial k}\left[ {\frac{K_m}{e_3 } 
    550         \;\frac{\partial \psi}{\partial k}} \right]\; 
    551   \end{split} 
    552 \] 
    553  
    554 \[ 
    555   % \label{eq:zdfgls_kz} 
    556   \begin{split} 
    557     K_m    &= C_{\mu} \ \sqrt {\bar{e}} \ l         \\ 
    558     K_\rho &= C_{\mu'}\ \sqrt {\bar{e}} \ l 
    559   \end{split} 
    560 \] 
    561  
    562 \[ 
    563   % \label{eq:zdfgls_eps} 
    564   {\epsilon} = C_{0\mu} \,\frac{\bar {e}^{3/2}}{l} \; 
    565 \] 
    566 where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}) and 
    567 $\epsilon$ the dissipation rate.  
    568 The constants $C_1$, $C_2$, $C_3$, ${\sigma_e}$, ${\sigma_{\psi}}$ and the wall function ($Fw$) depends of 
    569 the choice of the turbulence model. 
    570 Four different turbulent models are pre-defined (Tab.\autoref{tab:GLS}). 
    571 They are made available through the \np{nn\_clo} namelist parameter.  
    572  
    573 %--------------------------------------------------TABLE-------------------------------------------------- 
    574 \begin{table}[htbp] 
    575   \begin{center} 
    576     % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}c} 
    577     \begin{tabular}{ccccc} 
    578       &   $k-kl$   & $k-\epsilon$ & $k-\omega$ &   generic   \\ 
    579       % & \citep{Mellor_Yamada_1982} &  \citep{Rodi_1987}       & \citep{Wilcox_1988} &                 \\ 
    580       \hline 
    581       \hline 
    582       \np{nn\_clo}     & \textbf{0} &   \textbf{1}  &   \textbf{2}   &    \textbf{3}   \\ 
    583       \hline 
    584       $( p , n , m )$          &   ( 0 , 1 , 1 )   & ( 3 , 1.5 , -1 )   & ( -1 , 0.5 , -1 )    &  ( 2 , 1 , -0.67 )  \\ 
    585       $\sigma_k$      &    2.44         &     1.              &      2.                &      0.8          \\ 
    586       $\sigma_\psi$  &    2.44         &     1.3            &      2.                 &       1.07       \\ 
    587       $C_1$              &      0.9         &     1.44          &      0.555          &       1.           \\ 
    588       $C_2$              &      0.5         &     1.92          &      0.833          &       1.22       \\ 
    589       $C_3$              &      1.           &     1.              &      1.                &       1.           \\ 
    590       $F_{wall}$        &      Yes        &       --             &     --                  &      --          \\ 
    591       \hline 
    592       \hline 
    593     \end{tabular} 
    594     \caption{ 
    595       \protect\label{tab:GLS} 
    596       Set of predefined GLS parameters, or equivalently predefined turbulence models available with 
    597       \protect\key{zdfgls} and controlled by the \protect\np{nn\_clos} namelist variable in \protect\ngn{namzdf\_gls}. 
    598     } 
    599   \end{center} 
    600 \end{table} 
    601 %-------------------------------------------------------------------------------------------------------------- 
    602  
    603 In the Mellor-Yamada model, the negativity of $n$ allows to use a wall function to force the convergence of 
    604 the mixing length towards $K z_b$ ($K$: Kappa and $z_b$: rugosity length) value near physical boundaries 
    605 (logarithmic boundary layer law). 
    606 $C_{\mu}$ and $C_{\mu'}$ are calculated from stability function proposed by \citet{Galperin_al_JAS88}, 
    607 or by \citet{Kantha_Clayson_1994} or one of the two functions suggested by \citet{Canuto_2001} 
    608 (\np{nn\_stab\_func}\forcode{ = 0..3}, resp.).  
    609 The value of $C_{0\mu}$ depends of the choice of the stability function. 
    610  
    611 The surface and bottom boundary condition on both $\bar{e}$ and $\psi$ can be calculated thanks to Dirichlet or 
    612 Neumann condition through \np{nn\_tkebc\_surf} and \np{nn\_tkebc\_bot}, resp. 
    613 As for TKE closure, the wave effect on the mixing is considered when 
    614 \np{ln\_crban}\forcode{ = .true.} \citep{Craig_Banner_JPO94, Mellor_Blumberg_JPO04}. 
    615 The \np{rn\_crban} namelist parameter is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and 
    616 \np{rn\_charn} provides the value of $\beta$ in \autoref{eq:ZDF_Lsbc}.  
    617  
    618 The $\psi$ equation is known to fail in stably stratified flows, and for this reason 
    619 almost all authors apply a clipping of the length scale as an \textit{ad hoc} remedy. 
    620 With this clipping, the maximum permissible length scale is determined by $l_{max} = c_{lim} \sqrt{2\bar{e}}/ N$. 
    621 A value of $c_{lim} = 0.53$ is often used \citep{Galperin_al_JAS88}. 
    622 \cite{Umlauf_Burchard_CSR05} show that the value of the clipping factor is of crucial importance for 
    623 the entrainment depth predicted in stably stratified situations, 
    624 and that its value has to be chosen in accordance with the algebraic model for the turbulent fluxes. 
    625 The clipping is only activated if \np{ln\_length\_lim}\forcode{ = .true.}, 
    626 and the $c_{lim}$ is set to the \np{rn\_clim\_galp} value. 
    627  
    628 The time and space discretization of the GLS equations follows the same energetic consideration as for 
    629 the TKE case described in \autoref{subsec:ZDF_tke_ene} \citep{Burchard_OM02}. 
    630 Examples of performance of the 4 turbulent closure scheme can be found in \citet{Warner_al_OM05}. 
    631  
    632 % ------------------------------------------------------------------------------------------------------------- 
    633 %        OSM OSMOSIS BL Scheme  
    634 % ------------------------------------------------------------------------------------------------------------- 
    635 \subsection{OSM: OSMOSIS boundary layer scheme (\protect\key{zdfosm})} 
    636 \label{subsec:ZDF_osm} 
    637  
    638 %--------------------------------------------namzdf_osm--------------------------------------------------------- 
    639  
    640 \nlst{namzdf_osm} 
    641 %-------------------------------------------------------------------------------------------------------------- 
    642  
    643 The OSMOSIS turbulent closure scheme is based on......   TBC 
     652%The restart of the TKE scheme requires the storage of $\bar {e}$, $K_m$, $K_\rho$ and $l_\epsilon$ as 
     653%they all appear in the right hand side of \autoref{eq:zdftke_ene}. 
     654%For the latter, it is in fact the ratio $\sqrt{\bar{e}}/l_\epsilon$ which is stored.  
    644655 
    645656% ================================================================ 
     
    648659\section{Convection} 
    649660\label{sec:ZDF_conv} 
    650  
    651 %--------------------------------------------namzdf-------------------------------------------------------- 
    652  
    653 \nlst{namzdf} 
    654 %-------------------------------------------------------------------------------------------------------------- 
    655661 
    656662Static instabilities (\ie light potential densities under heavy ones) may occur at particular ocean grid points. 
     
    664670%       Non-Penetrative Convective Adjustment  
    665671% ------------------------------------------------------------------------------------------------------------- 
    666 \subsection[Non-penetrative convective adjmt (\protect\np{ln\_tranpc}\forcode{ = .true.})] 
    667             {Non-penetrative convective adjustment (\protect\np{ln\_tranpc}\forcode{ = .true.})} 
     672\subsection[Non-penetrative convective adjustment (\forcode{ln_tranpc = .true.})] 
     673{Non-penetrative convective adjustment (\protect\np{ln\_tranpc}\forcode{ = .true.})} 
    668674\label{subsec:ZDF_npc} 
    669  
    670 %--------------------------------------------namzdf-------------------------------------------------------- 
    671  
    672 \nlst{namzdf} 
    673 %-------------------------------------------------------------------------------------------------------------- 
    674675 
    675676%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    676677\begin{figure}[!htb] 
    677678  \begin{center} 
    678     \includegraphics[width=0.90\textwidth]{Fig_npc} 
     679    \includegraphics[width=\textwidth]{Fig_npc} 
    679680    \caption{ 
    680681      \protect\label{fig:npc} 
     
    700701the water column, but only until the density structure becomes neutrally stable 
    701702(\ie until the mixed portion of the water column has \textit{exactly} the density of the water just below) 
    702 \citep{Madec_al_JPO91}. 
     703\citep{madec.delecluse.ea_JPO91}. 
    703704The associated algorithm is an iterative process used in the following way (\autoref{fig:npc}): 
    704705starting from the top of the ocean, the first instability is found. 
     
    718719the algorithm used in \NEMO converges for any profile in a number of iterations which is less than 
    719720the number of vertical levels. 
    720 This property is of paramount importance as pointed out by \citet{Killworth1989}: 
     721This property is of paramount importance as pointed out by \citet{killworth_iprc89}: 
    721722it avoids the existence of permanent and unrealistic static instabilities at the sea surface. 
    722723This non-penetrative convective algorithm has been proved successful in studies of the deep water formation in 
    723 the north-western Mediterranean Sea \citep{Madec_al_JPO91, Madec_al_DAO91, Madec_Crepon_Bk91}. 
     724the north-western Mediterranean Sea \citep{madec.delecluse.ea_JPO91, madec.chartier.ea_DAO91, madec.crepon_iprc91}. 
    724725 
    725726The current implementation has been modified in order to deal with any non linear equation of seawater 
     
    727728Two main differences have been introduced compared to the original algorithm: 
    728729$(i)$ the stability is now checked using the Brunt-V\"{a}is\"{a}l\"{a} frequency  
    729 (not the the difference in potential density);  
     730(not the difference in potential density);  
    730731$(ii)$ when two levels are found unstable, their thermal and haline expansion coefficients are vertically mixed in 
    731732the same way their temperature and salinity has been mixed. 
     
    736737%       Enhanced Vertical Diffusion  
    737738% ------------------------------------------------------------------------------------------------------------- 
    738 \subsection{Enhanced vertical diffusion (\protect\np{ln\_zdfevd}\forcode{ = .true.})} 
     739\subsection[Enhanced vertical diffusion (\forcode{ln_zdfevd = .true.})] 
     740{Enhanced vertical diffusion (\protect\np{ln\_zdfevd}\forcode{ = .true.})} 
    739741\label{subsec:ZDF_evd} 
    740  
    741 %--------------------------------------------namzdf-------------------------------------------------------- 
    742  
    743 \nlst{namzdf} 
    744 %-------------------------------------------------------------------------------------------------------------- 
    745742 
    746743Options are defined through the  \ngn{namzdf} namelist variables. 
    747744The enhanced vertical diffusion parameterisation is used when \np{ln\_zdfevd}\forcode{ = .true.}. 
    748 In this case, the vertical eddy mixing coefficients are assigned very large values 
    749 (a typical value is $10\;m^2s^{-1})$ in regions where the stratification is unstable 
    750 (\ie when $N^2$ the Brunt-Vais\"{a}l\"{a} frequency is negative) \citep{Lazar_PhD97, Lazar_al_JPO99}. 
     745In this case, the vertical eddy mixing coefficients are assigned very large values  
     746in regions where the stratification is unstable 
     747(\ie when $N^2$ the Brunt-Vais\"{a}l\"{a} frequency is negative) \citep{lazar_phd97, lazar.madec.ea_JPO99}. 
    751748This is done either on tracers only (\np{nn\_evdm}\forcode{ = 0}) or 
    752749on both momentum and tracers (\np{nn\_evdm}\forcode{ = 1}). 
     
    759756the convective adjustment algorithm presented above when mixing both tracers and 
    760757momentum in the case of static instabilities. 
    761 It requires the use of an implicit time stepping on vertical diffusion terms 
    762 (\ie np{ln\_zdfexp}\forcode{ = .false.}). 
    763758 
    764759Note that the stability test is performed on both \textit{before} and \textit{now} values of $N^2$. 
    765760This removes a potential source of divergence of odd and even time step in 
    766 a leapfrog environment \citep{Leclair_PhD2010} (see \autoref{sec:STP_mLF}). 
     761a leapfrog environment \citep{leclair_phd10} (see \autoref{sec:STP_mLF}). 
    767762 
    768763% ------------------------------------------------------------------------------------------------------------- 
    769764%       Turbulent Closure Scheme  
    770765% ------------------------------------------------------------------------------------------------------------- 
    771 \subsection[Turbulent closure scheme (\protect\key{zdf}\{tke,gls,osm\})]{Turbulent Closure Scheme (\protect\key{zdftke}, \protect\key{zdfgls} or \protect\key{zdfosm})} 
     766\subsection[Handling convection with turbulent closure schemes (\forcode{ln_zdf/tke/gls/osm = .true.})] 
     767{Handling convection with turbulent closure schemes (\protect\np{ln\_zdf/tke/gls/osm}\forcode{ = .true.})} 
    772768\label{subsec:ZDF_tcs} 
    773769 
    774 The turbulent closure scheme presented in \autoref{subsec:ZDF_tke} and \autoref{subsec:ZDF_gls} 
    775 (\key{zdftke} or \key{zdftke} is defined) in theory solves the problem of statically unstable density profiles. 
     770 
     771The turbulent closure schemes presented in \autoref{subsec:ZDF_tke}, \autoref{subsec:ZDF_gls} and 
     772\autoref{subsec:ZDF_osm} (\ie \np{ln\_zdftke} or \np{ln\_zdfgls} or \np{ln\_zdfosm} defined) deal, in theory,  
     773with statically unstable density profiles. 
    776774In such a case, the term corresponding to the destruction of turbulent kinetic energy through stratification in 
    777775\autoref{eq:zdftke_e} or \autoref{eq:zdfgls_e} becomes a source term, since $N^2$ is negative.  
    778 It results in large values of $A_T^{vT}$ and  $A_T^{vT}$, and also the four neighbouring $A_u^{vm} {and}\;A_v^{vm}$ 
    779 (up to $1\;m^2s^{-1}$). 
     776It results in large values of $A_T^{vT}$ and  $A_T^{vT}$, and also of the four neighboring values at  
     777velocity points $A_u^{vm} {and}\;A_v^{vm}$ (up to $1\;m^2s^{-1}$). 
    780778These large values restore the static stability of the water column in a way similar to that of 
    781779the enhanced vertical diffusion parameterisation (\autoref{subsec:ZDF_evd}). 
     
    785783It can thus be useful to combine the enhanced vertical diffusion with the turbulent closure scheme, 
    786784\ie setting the \np{ln\_zdfnpc} namelist parameter to true and 
    787 defining the turbulent closure CPP key all together. 
    788  
    789 The KPP turbulent closure scheme already includes enhanced vertical diffusion in the case of convection, 
    790 as governed by the variables $bvsqcon$ and $difcon$ found in \mdl{zdfkpp}, 
    791 therefore \np{ln\_zdfevd}\forcode{ = .false.} should be used with the KPP scheme. 
     785defining the turbulent closure (\np{ln\_zdftke} or \np{ln\_zdfgls} = \forcode{.true.}) all together. 
     786 
     787The OSMOSIS turbulent closure scheme already includes enhanced vertical diffusion in the case of convection, 
     788%as governed by the variables $bvsqcon$ and $difcon$ found in \mdl{zdfkpp}, 
     789therefore \np{ln\_zdfevd}\forcode{ = .false.} should be used with the OSMOSIS scheme. 
    792790% gm%  + one word on non local flux with KPP scheme trakpp.F90 module... 
    793791 
     
    795793% Double Diffusion Mixing 
    796794% ================================================================ 
    797 \section{Double diffusion mixing (\protect\key{zdfddm})} 
    798 \label{sec:ZDF_ddm} 
     795\section[Double diffusion mixing (\forcode{ln_zdfddm = .true.})] 
     796{Double diffusion mixing (\protect\np{ln\_zdfddm}\forcode{ = .true.})} 
     797\label{subsec:ZDF_ddm} 
     798 
    799799 
    800800%-------------------------------------------namzdf_ddm------------------------------------------------- 
     
    803803%-------------------------------------------------------------------------------------------------------------- 
    804804 
    805 Options are defined through the  \ngn{namzdf\_ddm} namelist variables. 
     805This parameterisation has been introduced in \mdl{zdfddm} module and is controlled by the namelist parameter 
     806\np{ln\_zdfddm} in \ngn{namzdf}. 
    806807Double diffusion occurs when relatively warm, salty water overlies cooler, fresher water, or vice versa. 
    807808The former condition leads to salt fingering and the latter to diffusive convection. 
    808809Double-diffusive phenomena contribute to diapycnal mixing in extensive regions of the ocean. 
    809 \citet{Merryfield1999} include a parameterisation of such phenomena in a global ocean model and show that  
     810\citet{merryfield.holloway.ea_JPO99} include a parameterisation of such phenomena in a global ocean model and show that  
    810811it leads to relatively minor changes in circulation but exerts significant regional influences on 
    811812temperature and salinity. 
    812 This parameterisation has been introduced in \mdl{zdfddm} module and is controlled by the \key{zdfddm} CPP key. 
     813 
    813814 
    814815Diapycnal mixing of S and T are described by diapycnal diffusion coefficients  
     
    839840\begin{figure}[!t] 
    840841  \begin{center} 
    841     \includegraphics[width=0.99\textwidth]{Fig_zdfddm} 
     842    \includegraphics[width=\textwidth]{Fig_zdfddm} 
    842843    \caption{ 
    843844      \protect\label{fig:zdfddm} 
    844       From \citet{Merryfield1999} : 
     845      From \citet{merryfield.holloway.ea_JPO99} : 
    845846      (a) Diapycnal diffusivities $A_f^{vT}$ and $A_f^{vS}$ for temperature and salt in regions of salt fingering. 
    846847      Heavy curves denote $A^{\ast v} = 10^{-3}~m^2.s^{-1}$ and thin curves $A^{\ast v} = 10^{-4}~m^2.s^{-1}$; 
     
    855856 
    856857The factor 0.7 in \autoref{eq:zdfddm_f_T} reflects the measured ratio $\alpha F_T /\beta F_S \approx  0.7$ of 
    857 buoyancy flux of heat to buoyancy flux of salt (\eg, \citet{McDougall_Taylor_JMR84}). 
    858 Following  \citet{Merryfield1999}, we adopt $R_c = 1.6$, $n = 6$, and $A^{\ast v} = 10^{-4}~m^2.s^{-1}$. 
     858buoyancy flux of heat to buoyancy flux of salt (\eg, \citet{mcdougall.taylor_JMR84}). 
     859Following  \citet{merryfield.holloway.ea_JPO99}, we adopt $R_c = 1.6$, $n = 6$, and $A^{\ast v} = 10^{-4}~m^2.s^{-1}$. 
    859860 
    860861To represent mixing of S and T by diffusive layering,  the diapycnal diffusivities suggested by 
     
    887888% Bottom Friction 
    888889% ================================================================ 
    889 \section{Bottom and top friction (\protect\mdl{zdfbfr})} 
    890 \label{sec:ZDF_bfr} 
     890 \section[Bottom and top friction (\textit{zdfdrg.F90})] 
     891 {Bottom and top friction (\protect\mdl{zdfdrg})} 
     892 \label{sec:ZDF_drg} 
    891893 
    892894%--------------------------------------------nambfr-------------------------------------------------------- 
    893895% 
    894 %\nlst{nambfr} 
     896\nlst{namdrg} 
     897\nlst{namdrg_top} 
     898\nlst{namdrg_bot} 
     899 
    895900%-------------------------------------------------------------------------------------------------------------- 
    896901 
    897 Options to define the top and bottom friction are defined through the \ngn{nambfr} namelist variables. 
     902Options to define the top and bottom friction are defined through the \ngn{namdrg} namelist variables. 
    898903The bottom friction represents the friction generated by the bathymetry. 
    899904The top friction represents the friction generated by the ice shelf/ocean interface. 
    900 As the friction processes at the top and bottom are treated in similar way, 
    901 only the bottom friction is described in detail below. 
     905As the friction processes at the top and the bottom are treated in and identical way,  
     906the description below considers mostly the bottom friction case, if not stated otherwise. 
    902907 
    903908 
     
    905910a condition on the vertical diffusive flux. 
    906911For the bottom boundary layer, one has: 
    907 \[ 
    908   % \label{eq:zdfbfr_flux} 
    909   A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U} 
    910 \] 
     912 \[ 
     913   % \label{eq:zdfbfr_flux} 
     914   A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U} 
     915 \] 
    911916where ${\cal F}_h^{\textbf U}$ is represents the downward flux of horizontal momentum outside 
    912917the logarithmic turbulent boundary layer (thickness of the order of 1~m in the ocean). 
     
    922927To illustrate this, consider the equation for $u$ at $k$, the last ocean level: 
    923928\begin{equation} 
    924   \label{eq:zdfbfr_flux2} 
     929  \label{eq:zdfdrg_flux2} 
    925930  \frac{\partial u_k}{\partial t} = \frac{1}{e_{3u}} \left[ \frac{A_{uw}^{vm}}{e_{3uw}} \delta_{k+1/2}\;[u] - {\cal F}^u_h \right] \approx - \frac{{\cal F}^u_{h}}{e_{3u}} 
    926931\end{equation} 
     
    935940 
    936941In the code, the bottom friction is imposed by adding the trend due to the bottom friction to 
    937 the general momentum trend in \mdl{dynbfr}. 
     942 the general momentum trend in \mdl{dynzdf}. 
    938943For the time-split surface pressure gradient algorithm, the momentum trend due to 
    939944the barotropic component needs to be handled separately. 
    940945For this purpose it is convenient to compute and store coefficients which can be simply combined with 
    941946bottom velocities and geometric values to provide the momentum trend due to bottom friction. 
    942 These coefficients are computed in \mdl{zdfbfr} and generally take the form $c_b^{\textbf U}$ where: 
     947 These coefficients are computed in \mdl{zdfdrg} and generally take the form $c_b^{\textbf U}$ where: 
    943948\begin{equation} 
    944949  \label{eq:zdfbfr_bdef} 
     
    946951  - \frac{{\cal F}^{\textbf U}_{h}}{e_{3u}} = \frac{c_b^{\textbf U}}{e_{3u}} \;{\textbf U}_h^b 
    947952\end{equation} 
    948 where $\textbf{U}_h^b = (u_b\;,\;v_b)$ is the near-bottom, horizontal, ocean velocity. 
     953where $\textbf{U}_h^b = (u_b\;,\;v_b)$ is the near-bottom, horizontal, ocean velocity.  
     954Note than from \NEMO 4.0, drag coefficients are only computed at cell centers (\ie at T-points) and refer to as $c_b^T$ in the following. These are then linearly interpolated in space to get $c_b^\textbf{U}$ at velocity points. 
    949955 
    950956% ------------------------------------------------------------------------------------------------------------- 
    951957%       Linear Bottom Friction 
    952958% ------------------------------------------------------------------------------------------------------------- 
    953 \subsection{Linear bottom friction (\protect\np{nn\_botfr}\forcode{ = 0..1})} 
    954 \label{subsec:ZDF_bfr_linear} 
    955  
    956 The linear bottom friction parameterisation (including the special case of a free-slip condition) assumes that 
    957 the bottom friction is proportional to the interior velocity (\ie the velocity of the last model level): 
     959 \subsection[Linear top/bottom friction (\forcode{ln_lin = .true.})] 
     960 {Linear top/bottom friction (\protect\np{ln\_lin}\forcode{ = .true.)}} 
     961 \label{subsec:ZDF_drg_linear} 
     962 
     963The linear friction parameterisation (including the special case of a free-slip condition) assumes that 
     964the friction is proportional to the interior velocity (\ie the velocity of the first/last model level): 
    958965\[ 
    959966  % \label{eq:zdfbfr_linear} 
    960967  {\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3} \; \frac{\partial \textbf{U}_h}{\partial k} = r \; \textbf{U}_h^b 
    961968\] 
    962 where $r$ is a friction coefficient expressed in ms$^{-1}$. 
     969where $r$ is a friction coefficient expressed in $m s^{-1}$. 
    963970This coefficient is generally estimated by setting a typical decay time $\tau$ in the deep ocean,  
    964971and setting $r = H / \tau$, where $H$ is the ocean depth. 
    965 Commonly accepted values of $\tau$ are of the order of 100 to 200 days \citep{Weatherly_JMR84}. 
     972Commonly accepted values of $\tau$ are of the order of 100 to 200 days \citep{weatherly_JMR84}. 
    966973A value $\tau^{-1} = 10^{-7}$~s$^{-1}$ equivalent to 115 days, is usually used in quasi-geostrophic models. 
    967974One may consider the linear friction as an approximation of quadratic friction, $r \approx 2\;C_D\;U_{av}$ 
    968 (\citet{Gill1982}, Eq. 9.6.6). 
     975(\citet{gill_bk82}, Eq. 9.6.6). 
    969976For example, with a drag coefficient $C_D = 0.002$, a typical speed of tidal currents of $U_{av} =0.1$~m\;s$^{-1}$, 
    970977and assuming an ocean depth $H = 4000$~m, the resulting friction coefficient is $r = 4\;10^{-4}$~m\;s$^{-1}$. 
    971978This is the default value used in \NEMO. It corresponds to a decay time scale of 115~days. 
    972 It can be changed by specifying \np{rn\_bfri1} (namelist parameter). 
    973  
    974 For the linear friction case the coefficients defined in the general expression \autoref{eq:zdfbfr_bdef} are:  
     979It can be changed by specifying \np{rn\_Uc0} (namelist parameter). 
     980 
     981 For the linear friction case the drag coefficient used in the general expression \autoref{eq:zdfbfr_bdef} is:  
    975982\[ 
    976983  % \label{eq:zdfbfr_linbfr_b} 
    977   \begin{split} 
    978     c_b^u &= - r\\ 
    979     c_b^v &= - r\\ 
    980   \end{split} 
    981 \] 
    982 When \np{nn\_botfr}\forcode{ = 1}, the value of $r$ used is \np{rn\_bfri1}. 
    983 Setting \np{nn\_botfr}\forcode{ = 0} is equivalent to setting $r=0$ and 
    984 leads to a free-slip bottom boundary condition. 
    985 These values are assigned in \mdl{zdfbfr}. 
    986 From v3.2 onwards there is support for local enhancement of these values via an externally defined 2D mask array 
    987 (\np{ln\_bfr2d}\forcode{ = .true.}) given in the \ifile{bfr\_coef} input NetCDF file. 
     984    c_b^T = - r 
     985\] 
     986When \np{ln\_lin} \forcode{= .true.}, the value of $r$ used is \np{rn\_Uc0}*\np{rn\_Cd0}. 
     987Setting \np{ln\_OFF} \forcode{= .true.} (and \forcode{ln_lin = .true.}) is equivalent to setting $r=0$ and leads to a free-slip boundary condition. 
     988 
     989These values are assigned in \mdl{zdfdrg}. 
     990Note that there is support for local enhancement of these values via an externally defined 2D mask array 
     991(\np{ln\_boost}\forcode{ = .true.}) given in the \ifile{bfr\_coef} input NetCDF file. 
    988992The mask values should vary from 0 to 1. 
    989993Locations with a non-zero mask value will have the friction coefficient increased by 
    990 $mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri1}. 
     994$mask\_value$ * \np{rn\_boost} * \np{rn\_Cd0}. 
    991995 
    992996% ------------------------------------------------------------------------------------------------------------- 
    993997%       Non-Linear Bottom Friction 
    994998% ------------------------------------------------------------------------------------------------------------- 
    995 \subsection{Non-linear bottom friction (\protect\np{nn\_botfr}\forcode{ = 2})} 
    996 \label{subsec:ZDF_bfr_nonlinear} 
    997  
    998 The non-linear bottom friction parameterisation assumes that the bottom friction is quadratic:  
    999 \[ 
    1000   % \label{eq:zdfbfr_nonlinear} 
     999 \subsection[Non-linear top/bottom friction (\forcode{ln_non_lin = .true.})] 
     1000 {Non-linear top/bottom friction (\protect\np{ln\_non\_lin}\forcode{ = .true.})} 
     1001 \label{subsec:ZDF_drg_nonlinear} 
     1002 
     1003The non-linear bottom friction parameterisation assumes that the top/bottom friction is quadratic:  
     1004\[ 
     1005  % \label{eq:zdfdrg_nonlinear} 
    10011006  {\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3 }\frac{\partial \textbf {U}_h 
    10021007  }{\partial k}=C_D \;\sqrt {u_b ^2+v_b ^2+e_b } \;\; \textbf {U}_h^b 
    10031008\] 
    1004 where $C_D$ is a drag coefficient, and $e_b $ a bottom turbulent kinetic energy due to tides, 
     1009where $C_D$ is a drag coefficient, and $e_b $ a top/bottom turbulent kinetic energy due to tides, 
    10051010internal waves breaking and other short time scale currents. 
    10061011A typical value of the drag coefficient is $C_D = 10^{-3} $. 
    1007 As an example, the CME experiment \citep{Treguier_JGR92} uses $C_D = 10^{-3}$ and 
    1008 $e_b = 2.5\;10^{-3}$m$^2$\;s$^{-2}$, while the FRAM experiment \citep{Killworth1992} uses $C_D = 1.4\;10^{-3}$ and 
     1012As an example, the CME experiment \citep{treguier_JGR92} uses $C_D = 10^{-3}$ and 
     1013$e_b = 2.5\;10^{-3}$m$^2$\;s$^{-2}$, while the FRAM experiment \citep{killworth_JPO92} uses $C_D = 1.4\;10^{-3}$ and 
    10091014$e_b =2.5\;\;10^{-3}$m$^2$\;s$^{-2}$. 
    1010 The CME choices have been set as default values (\np{rn\_bfri2} and \np{rn\_bfeb2} namelist parameters). 
    1011  
    1012 As for the linear case, the bottom friction is imposed in the code by adding the trend due to 
    1013 the bottom friction to the general momentum trend in \mdl{dynbfr}. 
    1014 For the non-linear friction case the terms computed in \mdl{zdfbfr} are: 
    1015 \[ 
    1016   % \label{eq:zdfbfr_nonlinbfr} 
    1017   \begin{split} 
    1018     c_b^u &= - \; C_D\;\left[ u^2 + \left(\bar{\bar{v}}^{i+1,j}\right)^2 + e_b \right]^{1/2}\\ 
    1019     c_b^v &= - \; C_D\;\left[  \left(\bar{\bar{u}}^{i,j+1}\right)^2 + v^2 + e_b \right]^{1/2}\\ 
    1020   \end{split} 
    1021 \] 
    1022  
    1023 The coefficients that control the strength of the non-linear bottom friction are initialised as namelist parameters: 
    1024 $C_D$= \np{rn\_bfri2}, and $e_b$ =\np{rn\_bfeb2}. 
    1025 Note for applications which treat tides explicitly a low or even zero value of \np{rn\_bfeb2} is recommended. 
    1026 From v3.2 onwards a local enhancement of $C_D$ is possible via an externally defined 2D mask array 
    1027 (\np{ln\_bfr2d}\forcode{ = .true.}). 
    1028 This works in the same way as for the linear bottom friction case with non-zero masked locations increased by 
    1029 $mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri2}. 
     1015The CME choices have been set as default values (\np{rn\_Cd0} and \np{rn\_ke0} namelist parameters). 
     1016 
     1017As for the linear case, the friction is imposed in the code by adding the trend due to 
     1018the friction to the general momentum trend in \mdl{dynzdf}. 
     1019For the non-linear friction case the term computed in \mdl{zdfdrg} is: 
     1020\[ 
     1021  % \label{eq:zdfdrg_nonlinbfr} 
     1022    c_b^T = - \; C_D\;\left[ \left(\bar{u_b}^{i}\right)^2 + \left(\bar{v_b}^{j}\right)^2 + e_b \right]^{1/2} 
     1023\] 
     1024 
     1025The coefficients that control the strength of the non-linear friction are initialised as namelist parameters: 
     1026$C_D$= \np{rn\_Cd0}, and $e_b$ =\np{rn\_bfeb2}. 
     1027Note that for applications which consider tides explicitly, a low or even zero value of \np{rn\_bfeb2} is recommended. A local enhancement of $C_D$ is again possible via an externally defined 2D mask array 
     1028(\np{ln\_boost}\forcode{ = .true.}). 
     1029This works in the same way as for the linear friction case with non-zero masked locations increased by 
     1030$mask\_value$ * \np{rn\_boost} * \np{rn\_Cd0}. 
    10301031 
    10311032% ------------------------------------------------------------------------------------------------------------- 
    10321033%       Bottom Friction Log-layer 
    10331034% ------------------------------------------------------------------------------------------------------------- 
    1034 \subsection[Log-layer btm frict enhncmnt (\protect\np{nn\_botfr}\forcode{ = 2}, \protect\np{ln\_loglayer}\forcode{ = .true.})] 
    1035             {Log-layer bottom friction enhancement (\protect\np{nn\_botfr}\forcode{ = 2}, \protect\np{ln\_loglayer}\forcode{ = .true.})} 
    1036 \label{subsec:ZDF_bfr_loglayer} 
    1037  
    1038 In the non-linear bottom friction case, the drag coefficient, $C_D$, can be optionally enhanced using 
    1039 a "law of the wall" scaling. 
    1040 If  \np{ln\_loglayer} = .true., $C_D$ is no longer constant but is related to the thickness of 
    1041 the last wet layer in each column by: 
    1042 \[ 
    1043   C_D = \left ( {\kappa \over {\rm log}\left ( 0.5e_{3t}/rn\_bfrz0 \right ) } \right )^2 
    1044 \] 
    1045  
    1046 \noindent where $\kappa$ is the von-Karman constant and \np{rn\_bfrz0} is a roughness length provided via 
    1047 the namelist. 
    1048  
    1049 For stability, the drag coefficient is bounded such that it is kept greater or equal to 
    1050 the base \np{rn\_bfri2} value and it is not allowed to exceed the value of an additional namelist parameter: 
    1051 \np{rn\_bfri2\_max}, \ie 
    1052 \[ 
    1053   rn\_bfri2 \leq C_D \leq rn\_bfri2\_max 
    1054 \] 
    1055  
    1056 \noindent Note also that a log-layer enhancement can also be applied to the top boundary friction if 
    1057 under ice-shelf cavities are in use (\np{ln\_isfcav}\forcode{ = .true.}). 
    1058 In this case, the relevant namelist parameters are \np{rn\_tfrz0}, \np{rn\_tfri2} and \np{rn\_tfri2\_max}. 
    1059  
    1060 % ------------------------------------------------------------------------------------------------------------- 
    1061 %       Bottom Friction stability 
    1062 % ------------------------------------------------------------------------------------------------------------- 
    1063 \subsection{Bottom friction stability considerations} 
    1064 \label{subsec:ZDF_bfr_stability} 
    1065  
    1066 Some care needs to exercised over the choice of parameters to ensure that the implementation of 
    1067 bottom friction does not induce numerical instability. 
    1068 For the purposes of stability analysis, an approximation to \autoref{eq:zdfbfr_flux2} is: 
     1035 \subsection[Log-layer top/bottom friction (\forcode{ln_loglayer = .true.})] 
     1036 {Log-layer top/bottom friction (\protect\np{ln\_loglayer}\forcode{ = .true.})} 
     1037 \label{subsec:ZDF_drg_loglayer} 
     1038 
     1039In the non-linear friction case, the drag coefficient, $C_D$, can be optionally enhanced using 
     1040a "law of the wall" scaling. This assumes that the model vertical resolution can capture the logarithmic layer which typically occur for layers thinner than 1 m or so. 
     1041If  \np{ln\_loglayer} \forcode{= .true.}, $C_D$ is no longer constant but is related to the distance to the wall (or equivalently to the half of the top/bottom layer thickness): 
     1042\[ 
     1043  C_D = \left ( {\kappa \over {\mathrm log}\left ( 0.5 \; e_{3b} / rn\_{z0} \right ) } \right )^2 
     1044\] 
     1045 
     1046\noindent where $\kappa$ is the von-Karman constant and \np{rn\_z0} is a roughness length provided via the namelist. 
     1047 
     1048The drag coefficient is bounded such that it is kept greater or equal to 
     1049the base \np{rn\_Cd0} value which occurs where layer thicknesses become large and presumably logarithmic layers are not resolved at all. For stability reason, it is also not allowed to exceed the value of an additional namelist parameter: 
     1050\np{rn\_Cdmax}, \ie 
     1051\[ 
     1052  rn\_Cd0 \leq C_D \leq rn\_Cdmax 
     1053\] 
     1054 
     1055\noindent The log-layer enhancement can also be applied to the top boundary friction if 
     1056under ice-shelf cavities are activated (\np{ln\_isfcav}\forcode{ = .true.}). 
     1057%In this case, the relevant namelist parameters are \np{rn\_tfrz0}, \np{rn\_tfri2} and \np{rn\_tfri2\_max}. 
     1058 
     1059% ------------------------------------------------------------------------------------------------------------- 
     1060%       Explicit bottom Friction 
     1061% ------------------------------------------------------------------------------------------------------------- 
     1062 \subsection{Explicit top/bottom friction (\forcode{ln_drgimp = .false.})} 
     1063 \label{subsec:ZDF_drg_stability} 
     1064 
     1065Setting \np{ln\_drgimp} \forcode{= .false.} means that bottom friction is treated explicitly in time, which has the advantage of simplifying the interaction with the split-explicit free surface (see \autoref{subsec:ZDF_drg_ts}). The latter does indeed require the knowledge of bottom stresses in the course of the barotropic sub-iteration, which becomes less straightforward in the implicit case. In the explicit case, top/bottom stresses can be computed using \textit{before} velocities and inserted in the overall momentum tendency budget. This reads: 
     1066 
     1067At the top (below an ice shelf cavity): 
     1068\[ 
     1069  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{t} 
     1070  = c_{t}^{\textbf{U}}\textbf{u}^{n-1}_{t} 
     1071\] 
     1072 
     1073At the bottom (above the sea floor): 
     1074\[ 
     1075  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{b} 
     1076  = c_{b}^{\textbf{U}}\textbf{u}^{n-1}_{b} 
     1077\] 
     1078 
     1079Since this is conditionally stable, some care needs to exercised over the choice of parameters to ensure that the implementation of explicit top/bottom friction does not induce numerical instability. 
     1080For the purposes of stability analysis, an approximation to \autoref{eq:zdfdrg_flux2} is: 
    10691081\begin{equation} 
    1070   \label{eq:Eqn_bfrstab} 
     1082  \label{eq:Eqn_drgstab} 
    10711083  \begin{split} 
    10721084    \Delta u &= -\frac{{{\cal F}_h}^u}{e_{3u}}\;2 \rdt    \\ 
     
    10741086  \end{split} 
    10751087\end{equation} 
    1076 \noindent where linear bottom friction and a leapfrog timestep have been assumed. 
    1077 To ensure that the bottom friction cannot reverse the direction of flow it is necessary to have: 
     1088\noindent where linear friction and a leapfrog timestep have been assumed. 
     1089To ensure that the friction cannot reverse the direction of flow it is necessary to have: 
    10781090\[ 
    10791091  |\Delta u| < \;|u|  
    10801092\] 
    1081 \noindent which, using \autoref{eq:Eqn_bfrstab}, gives: 
     1093\noindent which, using \autoref{eq:Eqn_drgstab}, gives: 
    10821094\[ 
    10831095  r\frac{2\rdt}{e_{3u}} < 1 \qquad  \Rightarrow \qquad r < \frac{e_{3u}}{2\rdt}\\ 
     
    10931105For most applications, with physically sensible parameters these restrictions should not be of concern. 
    10941106But caution may be necessary if attempts are made to locally enhance the bottom friction parameters.  
    1095 To ensure stability limits are imposed on the bottom friction coefficients both 
     1107To ensure stability limits are imposed on the top/bottom friction coefficients both 
    10961108during initialisation and at each time step. 
    1097 Checks at initialisation are made in \mdl{zdfbfr} (assuming a 1 m.s$^{-1}$ velocity in the non-linear case). 
     1109Checks at initialisation are made in \mdl{zdfdrg} (assuming a 1 m.s$^{-1}$ velocity in the non-linear case). 
    10981110The number of breaches of the stability criterion are reported as well as 
    10991111the minimum and maximum values that have been set. 
    1100 The criterion is also checked at each time step, using the actual velocity, in \mdl{dynbfr}. 
    1101 Values of the bottom friction coefficient are reduced as necessary to ensure stability; 
     1112The criterion is also checked at each time step, using the actual velocity, in \mdl{dynzdf}. 
     1113Values of the friction coefficient are reduced as necessary to ensure stability; 
    11021114these changes are not reported. 
    11031115 
    1104 Limits on the bottom friction coefficient are not imposed if the user has elected to 
    1105 handle the bottom friction implicitly (see \autoref{subsec:ZDF_bfr_imp}). 
     1116Limits on the top/bottom friction coefficient are not imposed if the user has elected to 
     1117handle the friction implicitly (see \autoref{subsec:ZDF_drg_imp}). 
    11061118The number of potential breaches of the explicit stability criterion are still reported for information purposes. 
    11071119 
     
    11091121%       Implicit Bottom Friction 
    11101122% ------------------------------------------------------------------------------------------------------------- 
    1111 \subsection{Implicit bottom friction (\protect\np{ln\_bfrimp}\forcode{ = .true.})} 
    1112 \label{subsec:ZDF_bfr_imp} 
     1123 \subsection[Implicit top/bottom friction (\forcode{ln_drgimp = .true.})] 
     1124 {Implicit top/bottom friction (\protect\np{ln\_drgimp}\forcode{ = .true.})} 
     1125 \label{subsec:ZDF_drg_imp} 
    11131126 
    11141127An optional implicit form of bottom friction has been implemented to improve model stability. 
    1115 We recommend this option for shelf sea and coastal ocean applications, especially for split-explicit time splitting. 
    1116 This option can be invoked by setting \np{ln\_bfrimp} to \forcode{.true.} in the \textit{nambfr} namelist. 
    1117 This option requires \np{ln\_zdfexp} to be \forcode{.false.} in the \textit{namzdf} namelist.  
    1118  
    1119 This implementation is realised in \mdl{dynzdf\_imp} and \mdl{dynspg\_ts}. In \mdl{dynzdf\_imp}, 
    1120 the bottom boundary condition is implemented implicitly. 
    1121  
    1122 \[ 
    1123   % \label{eq:dynzdf_bfr} 
    1124   \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{mbk} 
    1125   = \binom{c_{b}^{u}u^{n+1}_{mbk}}{c_{b}^{v}v^{n+1}_{mbk}} 
    1126 \] 
    1127  
    1128 where $mbk$ is the layer number of the bottom wet layer. 
    1129 Superscript $n+1$ means the velocity used in the friction formula is to be calculated, so, it is implicit. 
    1130  
    1131 If split-explicit time splitting is used, care must be taken to avoid the double counting of the bottom friction in 
    1132 the 2-D barotropic momentum equations. 
    1133 As NEMO only updates the barotropic pressure gradient and Coriolis' forcing terms in the 2-D barotropic calculation, 
    1134 we need to remove the bottom friction induced by these two terms which has been included in the 3-D momentum trend  
    1135 and update it with the latest value. 
    1136 On the other hand, the bottom friction contributed by the other terms 
    1137 (\eg the advection term, viscosity term) has been included in the 3-D momentum equations and 
    1138 should not be added in the 2-D barotropic mode. 
    1139  
    1140 The implementation of the implicit bottom friction in \mdl{dynspg\_ts} is done in two steps as the following: 
    1141  
    1142 \[ 
    1143   % \label{eq:dynspg_ts_bfr1} 
    1144   \frac{\textbf{U}_{med}-\textbf{U}^{m-1}}{2\Delta t}=-g\nabla\eta-f\textbf{k}\times\textbf{U}^{m}+c_{b} 
    1145   \left(\textbf{U}_{med}-\textbf{U}^{m-1}\right) 
    1146 \] 
    1147 \[ 
    1148   \frac{\textbf{U}^{m+1}-\textbf{U}_{med}}{2\Delta t}=\textbf{T}+ 
    1149   \left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{U}^{'}\right)- 
    1150   2\Delta t_{bc}c_{b}\left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{u}_{b}\right) 
    1151 \] 
    1152  
    1153 where $\textbf{T}$ is the vertical integrated 3-D momentum trend. 
    1154 We assume the leap-frog time-stepping is used here. 
    1155 $\Delta t$ is the barotropic mode time step and $\Delta t_{bc}$ is the baroclinic mode time step. 
    1156 $c_{b}$ is the friction coefficient. 
    1157 $\eta$ is the sea surface level calculated in the barotropic loops while $\eta^{'}$ is the sea surface level used in 
    1158 the 3-D baroclinic mode. 
    1159 $\textbf{u}_{b}$ is the bottom layer horizontal velocity. 
    1160  
    1161 % ------------------------------------------------------------------------------------------------------------- 
    1162 %       Bottom Friction with split-explicit time splitting 
    1163 % ------------------------------------------------------------------------------------------------------------- 
    1164 \subsection[Bottom friction w/ split-explicit time splitting (\protect\np{ln\_bfrimp})] 
    1165             {Bottom friction with split-explicit time splitting (\protect\np{ln\_bfrimp})} 
    1166 \label{subsec:ZDF_bfr_ts} 
    1167  
    1168 When calculating the momentum trend due to bottom friction in \mdl{dynbfr}, 
    1169 the bottom velocity at the before time step is used. 
    1170 This velocity includes both the baroclinic and barotropic components which is appropriate when 
    1171 using either the explicit or filtered surface pressure gradient algorithms 
    1172 (\key{dynspg\_exp} or \key{dynspg\_flt}). 
    1173 Extra attention is required, however, when using split-explicit time stepping (\key{dynspg\_ts}). 
    1174 In this case the free surface equation is solved with a small time step \np{rn\_rdt}/\np{nn\_baro}, 
    1175 while the three dimensional prognostic variables are solved with the longer time step of \np{rn\_rdt} seconds. 
    1176 The trend in the barotropic momentum due to bottom friction appropriate to this method is that given by 
    1177 the selected parameterisation (\ie linear or non-linear bottom friction) computed with 
    1178 the evolving velocities at each barotropic timestep.  
    1179  
    1180 In the case of non-linear bottom friction, we have elected to partially linearise the problem by 
    1181 keeping the coefficients fixed throughout the barotropic time-stepping to those computed in 
    1182 \mdl{zdfbfr} using the now timestep. 
    1183 This decision allows an efficient use of the $c_b^{\vect{U}}$ coefficients to: 
    1184  
     1128We recommend this option for shelf sea and coastal ocean applications. %, especially for split-explicit time splitting. 
     1129This option can be invoked by setting \np{ln\_drgimp} to \forcode{.true.} in the \textit{namdrg} namelist. 
     1130%This option requires \np{ln\_zdfexp} to be \forcode{.false.} in the \textit{namzdf} namelist.  
     1131 
     1132This implementation is performed in \mdl{dynzdf} where the following boundary conditions are set while solving the fully implicit diffusion step:  
     1133 
     1134At the top (below an ice shelf cavity): 
     1135\[ 
     1136  % \label{eq:dynzdf_drg_top} 
     1137  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{t} 
     1138  = c_{t}^{\textbf{U}}\textbf{u}^{n+1}_{t} 
     1139\] 
     1140 
     1141At the bottom (above the sea floor): 
     1142\[ 
     1143  % \label{eq:dynzdf_drg_bot} 
     1144  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{b} 
     1145  = c_{b}^{\textbf{U}}\textbf{u}^{n+1}_{b} 
     1146\] 
     1147 
     1148where $t$ and $b$ refers to top and bottom layers respectively.  
     1149Superscript $n+1$ means the velocity used in the friction formula is to be calculated, so it is implicit. 
     1150 
     1151% ------------------------------------------------------------------------------------------------------------- 
     1152%       Bottom Friction with split-explicit free surface 
     1153% ------------------------------------------------------------------------------------------------------------- 
     1154 \subsection[Bottom friction with split-explicit free surface] 
     1155 {Bottom friction with split-explicit free surface} 
     1156 \label{subsec:ZDF_drg_ts} 
     1157 
     1158With split-explicit free surface, the sub-stepping of barotropic equations needs the knowledge of top/bottom stresses. An obvious way to satisfy this is to take them as constant over the course of the barotropic integration and equal to the value used to update the baroclinic momentum trend. Provided \np{ln\_drgimp}\forcode{= .false.} and a centred or \textit{leap-frog} like integration of barotropic equations is used (\ie \forcode{ln_bt_fw = .false.}, cf \autoref{subsec:DYN_spg_ts}), this does ensure that barotropic and baroclinic dynamics feel the same stresses during one leapfrog time step. However, if \np{ln\_drgimp}\forcode{= .true.},  stresses depend on the \textit{after} value of the velocities which themselves depend on the barotropic iteration result. This cyclic dependency makes difficult obtaining consistent stresses in 2d and 3d dynamics. Part of this mismatch is then removed when setting the final barotropic component of 3d velocities to the time splitting estimate. This last step can be seen as a necessary evil but should be minimized since it interferes with the adjustment to the boundary conditions.  
     1159 
     1160The strategy to handle top/bottom stresses with split-explicit free surface in \NEMO is as follows: 
    11851161\begin{enumerate} 
    1186 \item On entry to \rou{dyn\_spg\_ts}, remove the contribution of the before barotropic velocity to 
    1187   the bottom friction component of the vertically integrated momentum trend. 
    1188   Note the same stability check that is carried out on the bottom friction coefficient in \mdl{dynbfr} has to 
    1189   be applied here to ensure that the trend removed matches that which was added in \mdl{dynbfr}. 
    1190 \item At each barotropic step, compute the contribution of the current barotropic velocity to 
    1191   the trend due to bottom friction. 
    1192   Add this contribution to the vertically integrated momentum trend. 
    1193   This contribution is handled implicitly which eliminates the need to impose a stability criteria on 
    1194   the values of the bottom friction coefficient within the barotropic loop.  
    1195 \end{enumerate} 
    1196  
    1197 Note that the use of an implicit formulation within the barotropic loop for the bottom friction trend means that 
    1198 any limiting of the bottom friction coefficient in \mdl{dynbfr} does not adversely affect the solution when 
    1199 using split-explicit time splitting. 
    1200 This is because the major contribution to bottom friction is likely to come from the barotropic component which 
    1201 uses the unrestricted value of the coefficient. 
    1202 However, if the limiting is thought to be having a major effect 
    1203 (a more likely prospect in coastal and shelf seas applications) then 
    1204 the fully implicit form of the bottom friction should be used (see \autoref{subsec:ZDF_bfr_imp}) 
    1205 which can be selected by setting \np{ln\_bfrimp} $=$ \forcode{.true.}. 
    1206  
    1207 Otherwise, the implicit formulation takes the form: 
    1208 \[ 
    1209   % \label{eq:zdfbfr_implicitts} 
    1210   \bar{U}^{t+ \rdt} = \; \left [ \bar{U}^{t-\rdt}\; + 2 \rdt\;RHS \right ] / \left [ 1 - 2 \rdt \;c_b^{u} / H_e \right ] 
    1211 \] 
    1212 where $\bar U$ is the barotropic velocity, $H_e$ is the full depth (including sea surface height),  
    1213 $c_b^u$ is the bottom friction coefficient as calculated in \rou{zdf\_bfr} and 
    1214 $RHS$ represents all the components to the vertically integrated momentum trend except for 
    1215 that due to bottom friction. 
    1216  
    1217 % ================================================================ 
    1218 % Tidal Mixing 
    1219 % ================================================================ 
    1220 \section{Tidal mixing (\protect\key{zdftmx})} 
    1221 \label{sec:ZDF_tmx} 
    1222  
    1223 %--------------------------------------------namzdf_tmx-------------------------------------------------- 
     1162\item To extend the stability of the barotropic sub-stepping, bottom stresses are refreshed at each sub-iteration. The baroclinic part of the flow entering the stresses is frozen at the initial time of the barotropic iteration. In case of non-linear friction, the drag coefficient is also constant. 
     1163\item In case of an implicit drag, specific computations are performed in \mdl{dynzdf} which renders the overall scheme mixed explicit/implicit: the barotropic components of 3d velocities are removed before seeking for the implicit vertical diffusion result. Top/bottom stresses due to the barotropic components are explicitly accounted for thanks to the updated values of barotropic velocities. Then the implicit solution of 3d velocities is obtained. Lastly, the residual barotropic component is replaced by the time split estimate. 
     1164\end{enumerate}  
     1165 
     1166Note that other strategies are possible, like considering vertical diffusion step in advance, \ie prior barotropic integration.   
     1167 
     1168 
     1169% ================================================================ 
     1170% Internal wave-driven mixing 
     1171% ================================================================ 
     1172\section[Internal wave-driven mixing (\forcode{ln_zdfiwm = .true.})] 
     1173{Internal wave-driven mixing (\protect\np{ln\_zdfiwm}\forcode{ = .true.})} 
     1174\label{subsec:ZDF_tmx_new} 
     1175 
     1176%--------------------------------------------namzdf_iwm------------------------------------------ 
    12241177% 
    1225 %\nlst{namzdf_tmx} 
     1178\nlst{namzdf_iwm} 
    12261179%-------------------------------------------------------------------------------------------------------------- 
    12271180 
    1228  
    1229 % ------------------------------------------------------------------------------------------------------------- 
    1230 %        Bottom intensified tidal mixing  
    1231 % ------------------------------------------------------------------------------------------------------------- 
    1232 \subsection{Bottom intensified tidal mixing} 
    1233 \label{subsec:ZDF_tmx_bottom} 
    1234  
    1235 Options are defined through the  \ngn{namzdf\_tmx} namelist variables. 
    1236 The parameterization of tidal mixing follows the general formulation for the vertical eddy diffusivity proposed by 
    1237 \citet{St_Laurent_al_GRL02} and first introduced in an OGCM by \citep{Simmons_al_OM04}.  
    1238 In this formulation an additional vertical diffusivity resulting from internal tide breaking, 
    1239 $A^{vT}_{tides}$ is expressed as a function of $E(x,y)$, 
    1240 the energy transfer from barotropic tides to baroclinic tides: 
    1241 \begin{equation} 
    1242   \label{eq:Ktides} 
    1243   A^{vT}_{tides} =  q \,\Gamma \,\frac{ E(x,y) \, F(z) }{ \rho \, N^2 } 
    1244 \end{equation} 
    1245 where $\Gamma$ is the mixing efficiency, $N$ the Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}), 
    1246 $\rho$ the density, $q$ the tidal dissipation efficiency, and $F(z)$ the vertical structure function.  
    1247  
    1248 The mixing efficiency of turbulence is set by $\Gamma$ (\np{rn\_me} namelist parameter) and 
    1249 is usually taken to be the canonical value of $\Gamma = 0.2$ (Osborn 1980).  
    1250 The tidal dissipation efficiency is given by the parameter $q$ (\np{rn\_tfe} namelist parameter) 
    1251 represents the part of the internal wave energy flux $E(x, y)$ that is dissipated locally, 
    1252 with the remaining $1-q$ radiating away as low mode internal waves and 
    1253 contributing to the background internal wave field. 
    1254 A value of $q=1/3$ is typically used \citet{St_Laurent_al_GRL02}. 
    1255 The vertical structure function $F(z)$ models the distribution of the turbulent mixing in the vertical. 
    1256 It is implemented as a simple exponential decaying upward away from the bottom, 
    1257 with a vertical scale of $h_o$ (\np{rn\_htmx} namelist parameter, 
    1258 with a typical value of $500\,m$) \citep{St_Laurent_Nash_DSR04},  
    1259 \[ 
    1260   % \label{eq:Fz} 
    1261   F(i,j,k) = \frac{ e^{ -\frac{H+z}{h_o} } }{ h_o \left( 1- e^{ -\frac{H}{h_o} } \right) } 
    1262 \] 
    1263 and is normalized so that vertical integral over the water column is unity.  
    1264  
    1265 The associated vertical viscosity is calculated from the vertical diffusivity assuming a Prandtl number of 1, 
    1266 \ie $A^{vm}_{tides}=A^{vT}_{tides}$. 
    1267 In the limit of $N \rightarrow 0$ (or becoming negative), the vertical diffusivity is capped at $300\,cm^2/s$ and 
    1268 impose a lower limit on $N^2$ of \np{rn\_n2min} usually set to $10^{-8} s^{-2}$. 
    1269 These bounds are usually rarely encountered. 
    1270  
    1271 The internal wave energy map, $E(x, y)$ in \autoref{eq:Ktides}, is derived from a barotropic model of 
    1272 the tides utilizing a parameterization of the conversion of barotropic tidal energy into internal waves. 
    1273 The essential goal of the parameterization is to represent the momentum exchange between the barotropic tides and 
    1274 the unrepresented internal waves induced by the tidal flow over rough topography in a stratified ocean. 
    1275 In the current version of \NEMO, the map is built from the output of 
    1276 the barotropic global ocean tide model MOG2D-G \citep{Carrere_Lyard_GRL03}. 
    1277 This model provides the dissipation associated with internal wave energy for the M2 and K1 tides component 
    1278 (\autoref{fig:ZDF_M2_K1_tmx}). 
    1279 The S2 dissipation is simply approximated as being $1/4$ of the M2 one. 
    1280 The internal wave energy is thus : $E(x, y) = 1.25 E_{M2} + E_{K1}$. 
    1281 Its global mean value is $1.1$ TW, 
    1282 in agreement with independent estimates \citep{Egbert_Ray_Nat00, Egbert_Ray_JGR01}.  
    1283  
    1284 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    1285 \begin{figure}[!t] 
    1286   \begin{center} 
    1287     \includegraphics[width=0.90\textwidth]{Fig_ZDF_M2_K1_tmx} 
    1288     \caption{ 
    1289       \protect\label{fig:ZDF_M2_K1_tmx} 
    1290       (a) M2 and (b) K1 internal wave drag energy from \citet{Carrere_Lyard_GRL03} ($W/m^2$). 
    1291     } 
    1292   \end{center} 
    1293 \end{figure} 
    1294 %>>>>>>>>>>>>>>>>>>>>>>>>>>>>  
    1295   
    1296 % ------------------------------------------------------------------------------------------------------------- 
    1297 %        Indonesian area specific treatment  
    1298 % ------------------------------------------------------------------------------------------------------------- 
    1299 \subsection{Indonesian area specific treatment (\protect\np{ln\_zdftmx\_itf})} 
    1300 \label{subsec:ZDF_tmx_itf} 
    1301  
    1302 When the Indonesian Through Flow (ITF) area is included in the model domain, 
    1303 a specific treatment of tidal induced mixing in this area can be used. 
    1304 It is activated through the namelist logical \np{ln\_tmx\_itf}, and the user must provide an input NetCDF file, 
    1305 \ifile{mask\_itf}, which contains a mask array defining the ITF area where the specific treatment is applied. 
    1306  
    1307 When \np{ln\_tmx\_itf}\forcode{ = .true.}, the two key parameters $q$ and $F(z)$ are adjusted following 
    1308 the parameterisation developed by \citet{Koch-Larrouy_al_GRL07}: 
    1309  
    1310 First, the Indonesian archipelago is a complex geographic region with a series of 
    1311 large, deep, semi-enclosed basins connected via numerous narrow straits. 
    1312 Once generated, internal tides remain confined within this semi-enclosed area and hardly radiate away. 
    1313 Therefore all the internal tides energy is consumed within this area. 
    1314 So it is assumed that $q = 1$, \ie all the energy generated is available for mixing. 
    1315 Note that for test purposed, the ITF tidal dissipation efficiency is a namelist parameter (\np{rn\_tfe\_itf}). 
    1316 A value of $1$ or close to is this recommended for this parameter. 
    1317  
    1318 Second, the vertical structure function, $F(z)$, is no more associated with a bottom intensification of the mixing, 
    1319 but with a maximum of energy available within the thermocline. 
    1320 \citet{Koch-Larrouy_al_GRL07} have suggested that the vertical distribution of 
    1321 the energy dissipation proportional to $N^2$ below the core of the thermocline and to $N$ above.  
    1322 The resulting $F(z)$ is: 
    1323 \[ 
    1324   % \label{eq:Fz_itf} 
    1325   F(i,j,k) \sim     \left\{ 
    1326     \begin{aligned} 
    1327       \frac{q\,\Gamma E(i,j) } {\rho N \, \int N     dz}    \qquad \text{when $\partial_z N < 0$} \\ 
    1328       \frac{q\,\Gamma E(i,j) } {\rho     \, \int N^2 dz}    \qquad \text{when $\partial_z N > 0$} 
    1329     \end{aligned} 
    1330   \right. 
    1331 \] 
    1332  
    1333 Averaged over the ITF area, the resulting tidal mixing coefficient is $1.5\,cm^2/s$,  
    1334 which agrees with the independent estimates inferred from observations. 
    1335 Introduced in a regional OGCM, the parameterization improves the water mass characteristics in 
    1336 the different Indonesian seas, suggesting that the horizontal and vertical distributions of 
    1337 the mixing are adequately prescribed \citep{Koch-Larrouy_al_GRL07, Koch-Larrouy_al_OD08a, Koch-Larrouy_al_OD08b}. 
    1338 Note also that such a parameterisation has a significant impact on the behaviour of 
    1339 global coupled GCMs \citep{Koch-Larrouy_al_CD10}. 
    1340  
    1341 % ================================================================ 
    1342 % Internal wave-driven mixing 
    1343 % ================================================================ 
    1344 \section{Internal wave-driven mixing (\protect\key{zdftmx\_new})} 
    1345 \label{sec:ZDF_tmx_new} 
    1346  
    1347 %--------------------------------------------namzdf_tmx_new------------------------------------------ 
    1348 % 
    1349 %\nlst{namzdf_tmx_new} 
    1350 %-------------------------------------------------------------------------------------------------------------- 
    1351  
    13521181The parameterization of mixing induced by breaking internal waves is a generalization of 
    1353 the approach originally proposed by \citet{St_Laurent_al_GRL02}. 
     1182the approach originally proposed by \citet{st-laurent.simmons.ea_GRL02}. 
    13541183A three-dimensional field of internal wave energy dissipation $\epsilon(x,y,z)$ is first constructed, 
    13551184and the resulting diffusivity is obtained as  
     
    13601189where $R_f$ is the mixing efficiency and $\epsilon$ is a specified three dimensional distribution of 
    13611190the energy available for mixing. 
    1362 If the \np{ln\_mevar} namelist parameter is set to false, the mixing efficiency is taken as constant and 
    1363 equal to 1/6 \citep{Osborn_JPO80}. 
     1191If the \np{ln\_mevar} namelist parameter is set to \forcode{.false.}, the mixing efficiency is taken as constant and 
     1192equal to 1/6 \citep{osborn_JPO80}. 
    13641193In the opposite (recommended) case, $R_f$ is instead a function of 
    13651194the turbulence intensity parameter $Re_b = \frac{ \epsilon}{\nu \, N^2}$, 
    1366 with $\nu$ the molecular viscosity of seawater, following the model of \cite{Bouffard_Boegman_DAO2013} and 
    1367 the implementation of \cite{de_lavergne_JPO2016_efficiency}. 
     1195with $\nu$ the molecular viscosity of seawater, following the model of \cite{bouffard.boegman_DAO13} and 
     1196the implementation of \cite{de-lavergne.madec.ea_JPO16}. 
    13681197Note that $A^{vT}_{wave}$ is bounded by $10^{-2}\,m^2/s$, a limit that is often reached when 
    13691198the mixing efficiency is constant. 
    13701199 
    13711200In addition to the mixing efficiency, the ratio of salt to heat diffusivities can chosen to vary  
    1372 as a function of $Re_b$ by setting the \np{ln\_tsdiff} parameter to true, a recommended choice.  
    1373 This parameterization of differential mixing, due to \cite{Jackson_Rehmann_JPO2014}, 
    1374 is implemented as in \cite{de_lavergne_JPO2016_efficiency}. 
     1201as a function of $Re_b$ by setting the \np{ln\_tsdiff} parameter to \forcode{.true.}, a recommended choice.  
     1202This parameterization of differential mixing, due to \cite{jackson.rehmann_JPO14}, 
     1203is implemented as in \cite{de-lavergne.madec.ea_JPO16}. 
    13751204 
    13761205The three-dimensional distribution of the energy available for mixing, $\epsilon(i,j,k)$, 
    13771206is constructed from three static maps of column-integrated internal wave energy dissipation, 
    1378 $E_{cri}(i,j)$, $E_{pyc}(i,j)$, and $E_{bot}(i,j)$, combined to three corresponding vertical structures 
    1379 (de Lavergne et al., in prep): 
     1207$E_{cri}(i,j)$, $E_{pyc}(i,j)$, and $E_{bot}(i,j)$, combined to three corresponding vertical structures: 
     1208 
    13801209\begin{align*} 
    13811210  F_{cri}(i,j,k) &\propto e^{-h_{ab} / h_{cri} }\\ 
    1382   F_{pyc}(i,j,k) &\propto N^{n\_p}\\ 
     1211  F_{pyc}(i,j,k) &\propto N^{n_p}\\ 
    13831212  F_{bot}(i,j,k) &\propto N^2 \, e^{- h_{wkb} / h_{bot} } 
    13841213\end{align*}  
     
    13881217  h_{wkb} = H \, \frac{ \int_{-H}^{z} N \, dz' } { \int_{-H}^{\eta} N \, dz'  } \; , 
    13891218\] 
    1390 The $n_p$ parameter (given by \np{nn\_zpyc} in \ngn{namzdf\_tmx\_new} namelist) 
     1219The $n_p$ parameter (given by \np{nn\_zpyc} in \ngn{namzdf\_iwm} namelist) 
    13911220controls the stratification-dependence of the pycnocline-intensified dissipation. 
    1392 It can take values of 1 (recommended) or 2. 
     1221It can take values of $1$ (recommended) or $2$. 
    13931222Finally, the vertical structures $F_{cri}$ and $F_{bot}$ require the specification of 
    13941223the decay scales $h_{cri}(i,j)$ and $h_{bot}(i,j)$, which are defined by two additional input maps. 
    13951224$h_{cri}$ is related to the large-scale topography of the ocean (etopo2) and 
    13961225$h_{bot}$ is a function of the energy flux $E_{bot}$, the characteristic horizontal scale of 
    1397 the abyssal hill topography \citep{Goff_JGR2010} and the latitude. 
     1226the abyssal hill topography \citep{goff_JGR10} and the latitude. 
     1227% 
     1228% Jc: input files names ? 
     1229 
     1230% ================================================================ 
     1231% surface wave-induced mixing  
     1232% ================================================================ 
     1233\section[Surface wave-induced mixing (\forcode{ln_zdfswm = .true.})] 
     1234{Surface wave-induced mixing (\protect\np{ln\_zdfswm}\forcode{ = .true.})} 
     1235\label{subsec:ZDF_swm} 
     1236 
     1237Surface waves produce an enhanced mixing through wave-turbulence interaction. 
     1238In addition to breaking waves induced turbulence (\autoref{subsec:ZDF_tke}), 
     1239the influence of non-breaking waves can be accounted introducing  
     1240wave-induced viscosity and diffusivity as a function of the wave number spectrum. 
     1241Following \citet{qiao.yuan.ea_OD10}, a formulation of wave-induced mixing coefficient 
     1242is provided  as a function of wave amplitude, Stokes Drift and wave-number: 
     1243 
     1244\begin{equation} 
     1245  \label{eq:Bv} 
     1246  B_{v} = \alpha {A} {U}_{st} {exp(3kz)} 
     1247\end{equation} 
     1248 
     1249Where $B_{v}$ is the wave-induced mixing coefficient, $A$ is the wave amplitude,  
     1250${U}_{st}$ is the Stokes Drift velocity, $k$ is the wave number and $\alpha$  
     1251is a constant which should be determined by observations or  
     1252numerical experiments and is set to be 1. 
     1253 
     1254The coefficient $B_{v}$ is then directly added to the vertical viscosity  
     1255and diffusivity coefficients. 
     1256 
     1257In order to account for this contribution set: \forcode{ln_zdfswm = .true.}, 
     1258then wave interaction has to be activated through \forcode{ln_wave = .true.}, 
     1259the Stokes Drift can be evaluated by setting \forcode{ln_sdw = .true.}  
     1260(see \autoref{subsec:SBC_wave_sdw}) 
     1261and the needed wave fields can be provided either in forcing or coupled mode 
     1262(for more information on wave parameters and settings see \autoref{sec:SBC_wave}) 
     1263 
     1264% ================================================================ 
     1265% Adaptive-implicit vertical advection 
     1266% ================================================================ 
     1267\section[Adaptive-implicit vertical advection (\forcode{ln_zad_Aimp = .true.})] 
     1268{Adaptive-implicit vertical advection(\protect\np{ln\_zad\_Aimp}\forcode{ = .true.})} 
     1269\label{subsec:ZDF_aimp} 
     1270 
     1271The adaptive-implicit vertical advection option in NEMO is based on the work of 
     1272\citep{shchepetkin_OM15}.  In common with most ocean models, the timestep used with NEMO 
     1273needs to satisfy multiple criteria associated with different physical processes in order 
     1274to maintain numerical stability. \citep{shchepetkin_OM15} pointed out that the vertical 
     1275CFL criterion is commonly the most limiting. \citep{lemarie.debreu.ea_OM15} examined the 
     1276constraints for a range of time and space discretizations and provide the CFL stability 
     1277criteria for a range of advection schemes. The values for the Leap-Frog with Robert 
     1278asselin filter time-stepping (as used in NEMO) are reproduced in 
     1279\autoref{tab:zad_Aimp_CFLcrit}. Treating the vertical advection implicitly can avoid these 
     1280restrictions but at the cost of large dispersive errors and, possibly, large numerical 
     1281viscosity. The adaptive-implicit vertical advection option provides a targetted use of the 
     1282implicit scheme only when and where potential breaches of the vertical CFL condition 
     1283occur. In many practical applications these events may occur remote from the main area of 
     1284interest or due to short-lived conditions such that the extra numerical diffusion or 
     1285viscosity does not greatly affect the overall solution. With such applications, setting: 
     1286\forcode{ln_zad_Aimp = .true.} should allow much longer model timesteps to be used whilst 
     1287retaining the accuracy of the high order explicit schemes over most of the domain. 
     1288 
     1289\begin{table}[htbp] 
     1290  \begin{center} 
     1291    % \begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}} 
     1292    \begin{tabular}{r|ccc} 
     1293      \hline 
     1294      spatial discretization &   2nd order centered   & 3rd order upwind & 4th order compact  \\ 
     1295      advective CFL criterion     & 0.904 &   0.472  &   0.522    \\ 
     1296      \hline 
     1297    \end{tabular} 
     1298    \caption{ 
     1299      \protect\label{tab:zad_Aimp_CFLcrit} 
     1300      The advective CFL criteria for a range of spatial discretizations for the Leap-Frog with Robert Asselin filter time-stepping 
     1301      ($\nu=0.1$) as given in \citep{lemarie.debreu.ea_OM15}. 
     1302    } 
     1303  \end{center} 
     1304\end{table} 
     1305 
     1306In particular, the advection scheme remains explicit everywhere except where and when 
     1307local vertical velocities exceed a threshold set just below the explicit stability limit. 
     1308Once the threshold is reached a tapered transition towards an implicit scheme is used by 
     1309partitioning the vertical velocity into a part that can be treated explicitly and any 
     1310excess that must be treated implicitly. The partitioning is achieved via a Courant-number 
     1311dependent weighting algorithm as described in \citep{shchepetkin_OM15}. 
     1312 
     1313The local cell Courant number ($Cu$) used for this partitioning is: 
     1314 
     1315\begin{equation} 
     1316  \label{eq:Eqn_zad_Aimp_Courant} 
     1317  \begin{split} 
     1318    Cu &= {2 \rdt \over e^n_{3t_{ijk}}} \bigg (\big [ \texttt{Max}(w^n_{ijk},0.0) - \texttt{Min}(w^n_{ijk+1},0.0) \big ]    \\ 
     1319       &\phantom{=} +\big [ \texttt{Max}(e_{{2_u}ij}e^n_{{3_{u}}ijk}u^n_{ijk},0.0) - \texttt{Min}(e_{{2_u}i-1j}e^n_{{3_{u}}i-1jk}u^n_{i-1jk},0.0) \big ] 
     1320                     \big / e_{{1_t}ij}e_{{2_t}ij}            \\ 
     1321       &\phantom{=} +\big [ \texttt{Max}(e_{{1_v}ij}e^n_{{3_{v}}ijk}v^n_{ijk},0.0) - \texttt{Min}(e_{{1_v}ij-1}e^n_{{3_{v}}ij-1k}v^n_{ij-1k},0.0) \big ] 
     1322                     \big / e_{{1_t}ij}e_{{2_t}ij} \bigg )    \\ 
     1323  \end{split} 
     1324\end{equation} 
     1325 
     1326\noindent and the tapering algorithm follows \citep{shchepetkin_OM15} as: 
     1327 
     1328\begin{align} 
     1329  \label{eq:Eqn_zad_Aimp_partition} 
     1330Cu_{min} &= 0.15 \nonumber \\ 
     1331Cu_{max} &= 0.3  \nonumber \\ 
     1332Cu_{cut} &= 2Cu_{max} - Cu_{min} \nonumber \\ 
     1333Fcu    &= 4Cu_{max}*(Cu_{max}-Cu_{min}) \nonumber \\ 
     1334C\kern-0.14em f &= 
     1335     \begin{cases} 
     1336        0.0                                                        &\text{if $Cu \leq Cu_{min}$} \\ 
     1337        (Cu - Cu_{min})^2 / (Fcu +  (Cu - Cu_{min})^2)             &\text{else if $Cu < Cu_{cut}$} \\ 
     1338        (Cu - Cu_{max}) / Cu                                       &\text{else} 
     1339     \end{cases} 
     1340\end{align} 
     1341 
     1342\begin{figure}[!t] 
     1343  \begin{center} 
     1344    \includegraphics[width=\textwidth]{Fig_ZDF_zad_Aimp_coeff} 
     1345    \caption{ 
     1346      \protect\label{fig:zad_Aimp_coeff} 
     1347      The value of the partitioning coefficient ($C\kern-0.14em f$) used to partition vertical velocities into parts to 
     1348      be treated implicitly and explicitly for a range of typical Courant numbers (\forcode{ln_zad_Aimp=.true.}) 
     1349    } 
     1350  \end{center} 
     1351\end{figure} 
     1352 
     1353\noindent The partitioning coefficient is used to determine the part of the vertical 
     1354velocity that must be handled implicitly ($w_i$) and to subtract this from the total 
     1355vertical velocity ($w_n$) to leave that which can continue to be handled explicitly: 
     1356 
     1357\begin{align} 
     1358  \label{eq:Eqn_zad_Aimp_partition2} 
     1359    w_{i_{ijk}} &= C\kern-0.14em f_{ijk} w_{n_{ijk}}     \nonumber \\ 
     1360    w_{n_{ijk}} &= (1-C\kern-0.14em f_{ijk}) w_{n_{ijk}}            
     1361\end{align} 
     1362 
     1363\noindent Note that the coefficient is such that the treatment is never fully implicit; 
     1364the three cases from \autoref{eq:Eqn_zad_Aimp_partition} can be considered as: 
     1365fully-explicit; mixed explicit/implicit and mostly-implicit.  With the settings shown the 
     1366coefficient ($C\kern-0.14em f$) varies as shown in \autoref{fig:zad_Aimp_coeff}. Note with these values 
     1367the $Cu_{cut}$ boundary between the mixed implicit-explicit treatment and 'mostly 
     1368implicit' is 0.45 which is just below the stability limited given in 
     1369\autoref{tab:zad_Aimp_CFLcrit}  for a 3rd order scheme. 
     1370 
     1371The $w_i$ component is added to the implicit solvers for the vertical mixing in 
     1372\mdl{dynzdf} and \mdl{trazdf} in a similar way to \citep{shchepetkin_OM15}.  This is 
     1373sufficient for the flux-limited advection scheme (\forcode{ln_traadv_mus}) but further 
     1374intervention is required when using the flux-corrected scheme (\forcode{ln_traadv_fct}). 
     1375For these schemes the implicit upstream fluxes must be added to both the monotonic guess 
     1376and to the higher order solution when calculating the antidiffusive fluxes. The implicit 
     1377vertical fluxes are then removed since they are added by the implicit solver later on. 
     1378 
     1379The adaptive-implicit vertical advection option is new to NEMO at v4.0 and has yet to be  
     1380used in a wide range of simulations. The following test simulation, however, does illustrate 
     1381the potential benefits and will hopefully encourage further testing and feedback from users: 
     1382 
     1383\begin{figure}[!t] 
     1384  \begin{center} 
     1385    \includegraphics[width=\textwidth]{Fig_ZDF_zad_Aimp_overflow_frames} 
     1386    \caption{ 
     1387      \protect\label{fig:zad_Aimp_overflow_frames} 
     1388      A time-series of temperature vertical cross-sections for the OVERFLOW test case. These results are for the default 
     1389      settings with \forcode{nn_rdt=10.0} and without adaptive implicit vertical advection (\forcode{ln_zad_Aimp=.false.}). 
     1390    } 
     1391  \end{center} 
     1392\end{figure} 
     1393 
     1394\subsection{Adaptive-implicit vertical advection in the OVERFLOW test-case} 
     1395The \href{https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/guide/html/test\_cases.html\#overflow}{OVERFLOW test case} 
     1396provides a simple illustration of the adaptive-implicit advection in action. The example here differs from the basic test case 
     1397by only a few extra physics choices namely: 
     1398 
     1399\begin{verbatim} 
     1400     ln_dynldf_OFF = .false. 
     1401     ln_dynldf_lap = .true. 
     1402     ln_dynldf_hor = .true. 
     1403     ln_zdfnpc     = .true. 
     1404     ln_traadv_fct = .true. 
     1405        nn_fct_h   =  2 
     1406        nn_fct_v   =  2 
     1407\end{verbatim} 
     1408 
     1409\noindent which were chosen to provide a slightly more stable and less noisy solution. The 
     1410result when using the default value of \forcode{nn_rdt = 10.} without adaptive-implicit 
     1411vertical velocity is illustrated in \autoref{fig:zad_Aimp_overflow_frames}. The mass of 
     1412cold water, initially sitting on the shelf, moves down the slope and forms a 
     1413bottom-trapped, dense plume. Even with these extra physics choices the model is close to 
     1414stability limits and attempts with \forcode{nn_rdt = 30.} will fail after about 5.5 hours 
     1415with excessively high horizontal velocities. This time-scale corresponds with the time the 
     1416plume reaches the steepest part of the topography and, although detected as a horizontal 
     1417CFL breach, the instability originates from a breach of the vertical CFL limit. This is a good 
     1418candidate, therefore, for use of the adaptive-implicit vertical advection scheme. 
     1419 
     1420The results with \forcode{ln_zad_Aimp=.true.} and a variety of model timesteps 
     1421are shown in \autoref{fig:zad_Aimp_overflow_all_rdt} (together with the equivalent 
     1422frames from the base run).  In this simple example the use of the adaptive-implicit 
     1423vertcal advection scheme has enabled a 12x increase in the model timestep without 
     1424significantly altering the solution (although at this extreme the plume is more diffuse 
     1425and has not travelled so far).  Notably, the solution with and without the scheme is 
     1426slightly different even with \forcode{nn_rdt = 10.}; suggesting that the base run was 
     1427close enough to instability to trigger the scheme despite completing successfully. 
     1428To assist in diagnosing how active the scheme is, in both location and time, the 3D 
     1429implicit and explicit components of the vertical velocity are available via XIOS as 
     1430\texttt{wimp} and \texttt{wexp} respectively.  Likewise, the partitioning coefficient 
     1431($C\kern-0.14em f$) is also available as \texttt{wi\_cff}. For a quick oversight of 
     1432the schemes activity the global maximum values of the absolute implicit component 
     1433of the vertical velocity and the partitioning coefficient are written to the netCDF 
     1434version of the run statistics file (\texttt{run.stat.nc}) if this is active (see 
     1435\autoref{sec:MISC_opt} for activation details). 
     1436 
     1437\autoref{fig:zad_Aimp_maxCf} shows examples of the maximum partitioning coefficient for 
     1438the various overflow tests.  Note that the adaptive-implicit vertical advection scheme is 
     1439active even in the base run with \forcode{nn_rdt=10.0s} adding to the evidence that the 
     1440test case is close to stability limits even with this value. At the larger timesteps, the 
     1441vertical velocity is treated mostly implicitly at some location throughout the run. The 
     1442oscillatory nature of this measure appears to be linked to the progress of the plume front 
     1443as each cusp is associated with the location of the maximum shifting to the adjacent cell. 
     1444This is illustrated in \autoref{fig:zad_Aimp_maxCf_loc} where the i- and k- locations of the 
     1445maximum have been overlaid for the base run case. 
     1446 
     1447\medskip 
     1448\noindent Only limited tests have been performed in more realistic configurations. In the 
     1449ORCA2\_ICE\_PISCES reference configuration the scheme does activate and passes 
     1450restartability and reproducibility tests but it is unable to improve the model's stability 
     1451enough to allow an increase in the model time-step. A view of the time-series of maximum 
     1452partitioning coefficient (not shown here)  suggests that the default time-step of 5400s is 
     1453already pushing at stability limits, especially in the initial start-up phase. The 
     1454time-series does not, however, exhibit any of the 'cuspiness' found with the overflow 
     1455tests. 
     1456 
     1457\medskip 
     1458\noindent A short test with an eORCA1 configuration promises more since a test using a 
     1459time-step of 3600s remains stable with \forcode{ln_zad_Aimp=.true.} whereas the 
     1460time-step is limited to 2700s without. 
     1461 
     1462\begin{figure}[!t] 
     1463  \begin{center} 
     1464    \includegraphics[width=\textwidth]{Fig_ZDF_zad_Aimp_overflow_all_rdt} 
     1465    \caption{ 
     1466      \protect\label{fig:zad_Aimp_overflow_all_rdt} 
     1467      Sample temperature vertical cross-sections from mid- and end-run using different values for \forcode{nn_rdt}  
     1468      and with or without adaptive implicit vertical advection. Without the adaptive implicit vertical advection only 
     1469      the run with the shortest timestep is able to run to completion. Note also that the colour-scale has been 
     1470      chosen to confirm that temperatures remain within the original range of 10$^o$ to 20$^o$. 
     1471    } 
     1472  \end{center} 
     1473\end{figure} 
     1474 
     1475\begin{figure}[!t] 
     1476  \begin{center} 
     1477    \includegraphics[width=\textwidth]{Fig_ZDF_zad_Aimp_maxCf} 
     1478    \caption{ 
     1479      \protect\label{fig:zad_Aimp_maxCf} 
     1480      The maximum partitioning coefficient during a series of test runs with increasing model timestep length. 
     1481      At the larger timesteps, the vertical velocity is treated mostly implicitly at some location throughout  
     1482      the run. 
     1483    } 
     1484  \end{center} 
     1485\end{figure} 
     1486 
     1487\begin{figure}[!t] 
     1488  \begin{center} 
     1489    \includegraphics[width=\textwidth]{Fig_ZDF_zad_Aimp_maxCf_loc} 
     1490    \caption{ 
     1491      \protect\label{fig:zad_Aimp_maxCf_loc} 
     1492      The maximum partitioning coefficient for the  \forcode{nn_rdt=10.0s} case overlaid with  information on the gridcell i- and k- 
     1493      locations of the maximum value.  
     1494    } 
     1495  \end{center} 
     1496\end{figure} 
    13981497 
    13991498% ================================================================ 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_conservation.tex

    r10442 r11422  
    2121horizontal kinetic energy and/or potential enstrophy of horizontally non-divergent flow, 
    2222and variance of temperature and salinity will be conserved in the absence of dissipative effects and forcing. 
    23 \citet{Arakawa1966} has first pointed out the advantage of this approach. 
     23\citet{arakawa_JCP66} has first pointed out the advantage of this approach. 
    2424He showed that if integral constraints on energy are maintained, 
    2525the computation will be free of the troublesome "non linear" instability originally pointed out by 
    26 \citet{Phillips1959}. 
     26\citet{phillips_TAMS59}. 
    2727A consistent formulation of the energetic properties is also extremely important in carrying out 
    2828long-term numerical simulations for an oceanographic model. 
    29 Such a formulation avoids systematic errors that accumulate with time \citep{Bryan1997}. 
     29Such a formulation avoids systematic errors that accumulate with time \citep{bryan_JCP97}. 
    3030 
    3131The general philosophy of OPA which has led to the discrete formulation presented in {\S}II.2 and II.3 is to 
     
    3939Note that in some very specific cases as passive tracer studies, the positivity of the advective scheme is required. 
    4040In that case, and in that case only, the advective scheme used for passive tracer is a flux correction scheme 
    41 \citep{Marti1992, Levy1996, Levy1998}. 
     41\citep{Marti1992?, Levy1996?, Levy1998?}. 
    4242 
    4343% ------------------------------------------------------------------------------------------------------------- 
     
    6565  % \label{eq:vor_vorticity} 
    6666  \int_D {{\textbf {k}}\cdot \frac{1}{e_3 }\nabla \times \left( {\varsigma 
    67         \;{\rm {\bf k}}\times {\textbf {U}}_h } \right)\;dv} =0 
     67        \;{\mathrm {\mathbf k}}\times {\textbf {U}}_h } \right)\;dv} =0 
    6868\] 
    6969 
     
    189189\[ 
    190190  % \label{eq:dynldf_dyn} 
    191   \int\limits_D {\frac{1}{e_3 }{\rm {\bf k}}\cdot \nabla \times \left[ {\nabla 
     191  \int\limits_D {\frac{1}{e_3 }{\mathrm {\mathbf k}}\cdot \nabla \times \left[ {\nabla 
    192192        _h \left( {A^{lm}\;\chi } \right)-\nabla _h \times \left( {A^{lm}\;\zeta 
    193             \;{\rm {\bf k}}} \right)} \right]\;dv} =0 
     193            \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} =0 
    194194\] 
    195195 
     
    197197  % \label{eq:dynldf_div} 
    198198  \int\limits_D {\nabla _h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi } 
    199         \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} 
     199        \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} 
    200200    \right]\;dv} =0 
    201201\] 
     
    203203\[ 
    204204  % \label{eq:dynldf_curl} 
    205   \int_D {{\rm {\bf U}}_h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi } 
    206         \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} 
     205  \int_D {{\mathrm {\mathbf U}}_h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi } 
     206        \right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} 
    207207    \right]\;dv} \leqslant 0 
    208208\] 
     
    210210\[ 
    211211  % \label{eq:dynldf_curl2} 
    212   \mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\zeta \;{\rm {\bf k}}\cdot 
     212  \mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\zeta \;{\mathrm {\mathbf k}}\cdot 
    213213    \nabla \times \left[ {\nabla _h \left( {A^{lm}\;\chi } \right)-\nabla _h 
    214         \times \left( {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} \right]\;dv} 
     214        \times \left( {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} 
    215215  \leqslant 0 
    216216\] 
     
    220220  \mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\chi \;\nabla _h \cdot \left[ 
    221221      {\nabla _h \left( {A^{lm}\;\chi } \right)-\nabla _h \times \left( 
    222           {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} \right]\;dv} \leqslant 0 
     222          {A^{lm}\;\zeta \;{\mathrm {\mathbf k}}} \right)} \right]\;dv} \leqslant 0 
    223223\] 
    224224 
     
    260260  % \label{eq:dynzdf_vor} 
    261261  \begin{aligned} 
    262     & \int_D {\frac{1}{e_3 }{\rm {\bf k}}\cdot \nabla \times \left( {\frac{1}{e_3 
    263           }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm 
    264                   {\bf U}}_h }{\partial k}} \right)} \right)\;dv} =0 \\ 
    265     & \int_D {\zeta \,{\rm {\bf k}}\cdot \nabla \times \left( {\frac{1}{e_3 
    266           }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm 
    267                   {\bf U}}_h }{\partial k}} \right)} \right)\;dv} \leq 0 \\ 
     262    & \int_D {\frac{1}{e_3 }{\mathrm {\mathbf k}}\cdot \nabla \times \left( {\frac{1}{e_3 
     263          }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm 
     264                  {\mathbf U}}_h }{\partial k}} \right)} \right)\;dv} =0 \\ 
     265    & \int_D {\zeta \,{\mathrm {\mathbf k}}\cdot \nabla \times \left( {\frac{1}{e_3 
     266          }\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm 
     267                  {\mathbf U}}_h }{\partial k}} \right)} \right)\;dv} \leq 0 \\ 
    268268  \end{aligned} 
    269269\] 
     
    273273  \begin{aligned} 
    274274    &\int_D {\nabla \cdot \left( {\frac{1}{e_3 }\frac{\partial }{\partial 
    275             k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm {\bf U}}_h }{\partial k}} 
     275            k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm {\mathbf U}}_h }{\partial k}} 
    276276          \right)} \right)\;dv} =0 \\ 
    277277    & \int_D {\chi \;\nabla \cdot \left( {\frac{1}{e_3 }\frac{\partial }{\partial 
    278             k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm {\bf U}}_h }{\partial k}} 
     278            k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\mathrm {\mathbf U}}_h }{\partial k}} 
    279279          \right)} \right)\;dv} \leq 0 \\ 
    280280  \end{aligned} 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_misc.tex

    r10601 r11422  
    3030are much narrow than even a single ocean grid-point. 
    3131 
    32 We describe briefly here the three methods that can be used in \NEMO to handle such improperly resolved straits. 
    33 The first two consist of opening the strait by hand while ensuring that the mass exchanges through 
    34 the strait are not too large by either artificially reducing the surface of the strait grid-cells or, 
    35 locally increasing the lateral friction. 
    36 In the third one, the strait is closed but exchanges of mass, heat and salt across the land are allowed. 
    37 Note that such modifications are so specific to a given configuration that no attempt has been made to 
    38 set them in a generic way. 
    39 However, examples of how they can be set up is given in the ORCA 2\deg and 0.5\deg configurations. 
    40 For example, for details of implementation in ORCA2, search: \texttt{IF( cp\_cfg == "orca" .AND. jp\_cfg == 2 )} 
     32We describe briefly here the two methods that can be used in \NEMO to handle such 
     33improperly resolved straits. The methods consist of opening the strait while ensuring 
     34that the mass exchanges through the strait are not too large by either artificially 
     35reducing the cross-sectional area of the strait grid-cells or, locally increasing the 
     36lateral friction. 
    4137 
    4238% ------------------------------------------------------------------------------------------------------------- 
     
    4642\label{subsec:MISC_strait_hand} 
    4743 
    48 $\bullet$ reduced scale factor in the cross-strait direction to a value in better agreement with 
    49 the true mean width of the strait (\autoref{fig:MISC_strait_hand}). 
    50 This technique is sometime called "partially open face" or "partially closed cells". 
    51 The key issue here is only to reduce the faces of $T$-cell 
    52 (\ie change the value of the horizontal scale factors at $u$- or $v$-point) but not the volume of the $T$-cell. 
    53 Indeed, reducing the volume of strait $T$-cell can easily produce a numerical instability at 
    54 that grid point that would require a reduction of the model time step. 
    55 The changes associated with strait management are done in \mdl{domhgr}, 
    56 just after the definition or reading of the horizontal scale factors.  
    57  
    58 $\bullet$ increase of the viscous boundary layer thickness by local increase of the fmask value at the coast 
    59 (\autoref{fig:MISC_strait_hand}). 
    60 This is done in \mdl{dommsk} together with the setting of the coastal value of fmask (see  \autoref{sec:LBC_coast}). 
     44The first method involves reducing the scale factor in the cross-strait direction to a 
     45value in better agreement with the true mean width of the strait 
     46(\autoref{fig:MISC_strait_hand}).  This technique is sometime called "partially open face" 
     47or "partially closed cells".  The key issue here is only to reduce the faces of $T$-cell 
     48(\ie change the value of the horizontal scale factors at $u$- or $v$-point) but not the 
     49volume of the $T$-cell.  Indeed, reducing the volume of strait $T$-cell can easily produce 
     50a numerical instability at that grid point which would require a reduction of the model 
     51time step.  Thus to instigate a local change in the width of a Strait requires two steps: 
     52 
     53\begin{itemize} 
     54 
     55\item Add \texttt{e1e2u} and \texttt{e1e2v} arrays to the \np{cn\_domcfg} file. These 2D 
     56arrays should contain the products of the unaltered values of: $\texttt{e1u}*\texttt{e2u}$ 
     57and $\texttt{e1u}*\texttt{e2v}$ respectively. That is the original surface areas of $u$- 
     58and $v$- cells respectively.  These areas are usually defined by the corresponding product 
     59within the \NEMO code but the presence of \texttt{e1e2u} and \texttt{e1e2v} in the 
     60\np{cn\_domcfg} file will suppress this calculation and use the supplied fields instead. 
     61If the model domain is provided by user-supplied code in \mdl{usrdef\_hgr}, then this 
     62routine should also return \texttt{e1e2u} and \texttt{e1e2v} and set the integer return 
     63argument \texttt{ie1e2u\_v} to a non-zero value. Values other than 0 for this argument 
     64will suppress the calculation of the areas. 
     65 
     66\item Change values of \texttt{e2u} or \texttt{e1v} (either in the \np{cn\_domcfg} file or 
     67via code in  \mdl{usrdef\_hgr}), whereever a Strait reduction is required. The choice of 
     68whether to alter \texttt{e2u} or \texttt{e1v} depends. respectively,  on whether the 
     69Strait in question is North-South orientated (\eg Gibraltar) or East-West orientated (\eg 
     70Lombok). 
     71 
     72\end{itemize} 
     73 
     74 
     75The second method is to increase the viscous boundary layer thickness by a local increase 
     76of the fmask value at the coast. This method can also be effective in wider passages.  The 
     77concept is illustarted in the second part of  \autoref{fig:MISC_strait_hand} and changes 
     78to specific locations can be coded in \mdl{usrdef\_fmask}. The \forcode{usr_def_fmask} 
     79routine is always called after \texttt{fmask} has been defined according to the choice of 
     80lateral boundary condition as discussed in \autoref{sec:LBC_coast}. The default version of 
     81\mdl{usrdef\_fmask} contains settings specific to ORCA2 and ORCA1 configurations. These are 
     82meant as examples only; it is up to the user to verify settings and provide alternatives 
     83for their own configurations. The default \forcode{usr_def_fmask} makes no changes to 
     84\texttt{fmask} for any other configuration. 
    6185 
    6286%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    6387\begin{figure}[!tbp] 
    6488  \begin{center} 
    65     \includegraphics[width=0.80\textwidth]{Fig_Gibraltar} 
    66     \includegraphics[width=0.80\textwidth]{Fig_Gibraltar2} 
     89    \includegraphics[width=\textwidth]{Fig_Gibraltar} 
     90    \includegraphics[width=\textwidth]{Fig_Gibraltar2} 
    6791    \caption{ 
    6892      \protect\label{fig:MISC_strait_hand} 
     
    84108\begin{figure}[!tbp] 
    85109  \begin{center} 
    86     \includegraphics[width=1.0\textwidth]{Fig_closea_mask_example} 
     110    \includegraphics[width=\textwidth]{Fig_closea_mask_example} 
    87111    \caption{ 
    88112      \protect\label{fig:closea_mask_example} 
     
    102126% Closed seas 
    103127% ================================================================ 
    104 \section{Closed seas (\protect\mdl{closea})} 
     128\section[Closed seas (\textit{closea.F90})] 
     129{Closed seas (\protect\mdl{closea})} 
    105130\label{sec:MISC_closea} 
    106131 
     
    122147 
    123148\begin{enumerate} 
    124 \item{{\bf No ``closea\_mask'' field is included in domain configuration 
     149\item{{\bfseries No ``closea\_mask'' field is included in domain configuration 
    125150  file.} In this case the closea module does nothing.} 
    126151 
    127 \item{{\bf A field called closea\_mask is included in the domain 
     152\item{{\bfseries A field called closea\_mask is included in the domain 
    128153configuration file and ln\_closea=.false. in namelist namcfg.} In this 
    129154case the inland seas defined by the closea\_mask field are filled in 
     
    131156closea\_mask that is nonzero is set to be a land point.} 
    132157 
    133 \item{{\bf A field called closea\_mask is included in the domain 
     158\item{{\bfseries A field called closea\_mask is included in the domain 
    134159configuration file and ln\_closea=.true. in namelist namcfg.} Each 
    135160inland sea or group of inland seas is set to a positive integer value 
     
    140165closea\_mask is zero).} 
    141166 
    142 \item{{\bf Fields called closea\_mask and closea\_mask\_rnf are 
     167\item{{\bfseries Fields called closea\_mask and closea\_mask\_rnf are 
    143168included in the domain configuration file and ln\_closea=.true. in 
    144169namelist namcfg.} This option works as for option 3, except that if 
     
    154179ocean.} 
    155180 
    156 \item{{\bf Fields called closea\_mask and closea\_mask\_emp are 
     181\item{{\bfseries Fields called closea\_mask and closea\_mask\_emp are 
    157182included in the domain configuration file and ln\_closea=.true. in 
    158183namelist namcfg.} This option works the same as option 4 except that 
     
    174199\subsection{Simple subsetting of input files via NetCDF attributes} 
    175200 
    176 The extended grids for use with the under-shelf ice cavities will result in redundant rows around Antarctica if 
    177 the ice cavities are not active. 
    178 A simple mechanism for subsetting input files associated with the extended domains has been implemented to 
    179 avoid the need to maintain different sets of input fields for use with or without active ice cavities. 
    180 The existing 'zoom' options are overly complex for this task and marked for deletion anyway. 
    181 This alternative subsetting operates for the j-direction only and works by optionally looking for and 
    182 using a global file attribute (named: \np{open\_ocean\_jstart}) to determine the starting j-row for input. 
    183 The use of this option is best explained with an example: 
    184 consider an ORCA1 configuration using the extended grid bathymetry and coordinate files: 
    185 \vspace{-10pt} 
    186 \ifile{eORCA1\_bathymetry\_v2} 
    187 \ifile{eORCA1\_coordinates} 
    188 \noindent These files define a horizontal domain of 362x332. 
    189 Assuming the first row with open ocean wet points in the non-isf bathymetry for this set is row 42 
    190 (\fortran indexing) then the formally correct setting for \np{open\_ocean\_jstart} is 41. 
    191 Using this value as the first row to be read will result in a 362x292 domain which is the same size as 
    192 the original ORCA1 domain. 
    193 Thus the extended coordinates and bathymetry files can be used with all the original input files for ORCA1 if 
    194 the ice cavities are not active (\np{ln\_isfcav = .false.}). 
    195 Full instructions for achieving this are: 
    196  
    197 \noindent Add the new attribute to any input files requiring a j-row offset, i.e: 
    198 \vspace{-10pt} 
     201The extended grids for use with the under-shelf ice cavities will result in redundant rows 
     202around Antarctica if the ice cavities are not active.  A simple mechanism for subsetting 
     203input files associated with the extended domains has been implemented to avoid the need to 
     204maintain different sets of input fields for use with or without active ice cavities.  This 
     205subsetting operates for the j-direction only and works by optionally looking for and using 
     206a global file attribute (named: \np{open\_ocean\_jstart}) to determine the starting j-row 
     207for input.  The use of this option is best explained with an example:  
     208\medskip 
     209 
     210\noindent Consider an ORCA1 
     211configuration using the extended grid domain configuration file: \ifile{eORCA1\_domcfg.nc} 
     212This file define a horizontal domain of 362x332.  The first row with 
     213open ocean wet points in the non-isf bathymetry for this set is row 42 (\fortran indexing) 
     214then the formally correct setting for \np{open\_ocean\_jstart} is 41.  Using this value as 
     215the first row to be read will result in a 362x292 domain which is the same size as the 
     216original ORCA1 domain.  Thus the extended domain configuration file can be used with all 
     217the original input files for ORCA1 if the ice cavities are not active (\np{ln\_isfcav = 
     218.false.}).  Full instructions for achieving this are: 
     219 
     220\begin{itemize} 
     221\item  Add the new attribute to any input files requiring a j-row offset, i.e: 
     222\begin{cmds}  
     223ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_domcfg.nc  
     224\end{cmds} 
     225 
     226\item Add the logical switch \np{ln\_use\_jattr} to \ngn{namcfg} in the configuration 
     227namelist (if it is not already there) and set \np{.true.} 
     228\end{itemize} 
     229 
     230\noindent Note that with this option, the j-size of the global domain is (extended 
     231j-size minus \np{open\_ocean\_jstart} + 1 ) and this must match the \texttt{jpjglo} value 
     232for the configuration. This means an alternative version of \ifile{eORCA1\_domcfg.nc} must 
     233be created for when \np{ln\_use\_jattr} is active. The \texttt{ncap2} tool provides a 
     234convenient way of achieving this: 
     235 
    199236\begin{cmds} 
    200 ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_coordinates.nc  
    201 ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_bathymetry_v2.nc 
     237ncap2 -s 'jpjglo=292' eORCA1_domcfg.nc nORCA1_domcfg.nc 
    202238\end{cmds} 
    203   
    204 \noindent Add the logical switch to \ngn{namcfg} in the configuration namelist and set true: 
    205 %--------------------------------------------namcfg-------------------------------------------------------- 
    206  
    207 \nlst{namcfg} 
    208 %-------------------------------------------------------------------------------------------------------------- 
    209  
    210 \noindent Note the j-size of the global domain is the (extended j-size minus \np{open\_ocean\_jstart} + 1 ) and 
    211 this must match the size of all datasets other than bathymetry and coordinates currently. 
    212 However the option can be extended to any global, 2D and 3D, netcdf, input field by adding the: 
    213 \vspace{-10pt} 
     239 
     240The domain configuration file is unique in this respect since it also contains the value 
     241of \texttt{jpjglo} that is read and used by the model. Any other global, 2D and 3D, 
     242netcdf, input field can be prepared for use in a reduced domain by adding the 
     243\texttt{open\_ocean\_jstart} attribute to the file's  global attributes. In particular 
     244this is true for any field that is read by \NEMO using the following optional argument to 
     245the appropriate call to \np{iom\_get}. 
    214246\begin{forlines} 
    215247lrowattr=ln_use_jattr 
    216248\end{forlines} 
    217 optional argument to the appropriate \np{iom\_get} call and the \np{open\_ocean\_jstart} attribute to 
    218 the corresponding input files. 
    219 It remains the users responsibility to set \np{jpjdta} and \np{jpjglo} values in 
    220 the \np{namelist\_cfg} file according to their needs. 
    221  
    222 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    223 \begin{figure}[!ht] 
    224   \begin{center} 
    225     \includegraphics[width=0.90\textwidth]{Fig_LBC_zoom} 
    226     \caption{ 
    227       \protect\label{fig:LBC_zoom} 
    228       Position of a model domain compared to the data input domain when the zoom functionality is used. 
    229     } 
    230   \end{center} 
    231 \end{figure} 
    232 %>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    233  
     249 
     250Currently, only the domain configuration variables make use of this optional argument so 
     251this facility is of little practical use except for tests where no other external input 
     252files are needed or you wish to use an extended domain configuration with inputs from 
     253earlier, non-extended configurations. Alternatively, it should be possible to exclude 
     254empty rows for extended domain, forced ocean runs using interpolation on the fly, by 
     255adding the optional argument to \texttt{iom\_get} calls for the weights and initial 
     256conditions. Experimenting with this remains an exercise for the user. 
    234257 
    235258% ================================================================ 
    236259% Accuracy and Reproducibility 
    237260% ================================================================ 
    238 \section{Accuracy and reproducibility (\protect\mdl{lib\_fortran})} 
     261\section[Accuracy and reproducibility (\textit{lib\_fortran.F90})] 
     262{Accuracy and reproducibility (\protect\mdl{lib\_fortran})} 
    239263\label{sec:MISC_fortran} 
    240264 
    241 \subsection{Issues with intrinsinc SIGN function (\protect\key{nosignedzero})} 
     265\subsection[Issues with intrinsinc SIGN function (\texttt{\textbf{key\_nosignedzero}})] 
     266{Issues with intrinsinc SIGN function (\protect\key{nosignedzero})} 
    242267\label{subsec:MISC_sign} 
    243268 
     
    272297and their propagation and accumulation cause uncertainty in final simulation reproducibility on 
    273298different numbers of processors. 
    274 To avoid so, based on \citet{He_Ding_JSC01} review of different technics, 
     299To avoid so, based on \citet{he.ding_JS01} review of different technics, 
    275300we use a so called self-compensated summation method. 
    276301The idea is to estimate the roundoff error, store it in a buffer, and then add it back in the next addition.  
     
    314339This alternative method should give identical results to the default \textsc{ALLGATHER} method and 
    315340is recommended for large values of \np{jpni}. 
    316 The new method is activated by setting \np{ln\_nnogather} to be true ({\bf nammpp}). 
     341The new method is activated by setting \np{ln\_nnogather} to be true (\ngn{nammpp}). 
    317342The reproducibility of results using the two methods should be confirmed for each new, 
    318343non-reference configuration. 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_model_basics.tex

    r10544 r11422  
    3232\begin{enumerate} 
    3333\item 
    34   \textit{spherical earth approximation}: the geopotential surfaces are assumed to be spheres so that 
    35   gravity (local vertical) is parallel to the earth's radius 
     34  \textit{spherical Earth approximation}: the geopotential surfaces are assumed to be oblate spheriods 
     35  that follow the Earth's bulge; these spheroids are approximated by spheres with 
     36  gravity locally vertical (parallel to the Earth's radius) and independent of latitude  
     37  \citep[][section 2]{white.hoskins.ea_QJRMS05}.    
    3638\item 
    3739  \textit{thin-shell approximation}: the ocean depth is neglected compared to the earth's radius 
     
    6365    \nabla \cdot \vect U = 0 
    6466  \end{equation} 
     67 \item  
     68  \textit{Neglect of additional Coriolis terms}: the Coriolis terms that vary with the cosine of latitude are neglected.  
     69  These terms may be non-negligible where the Brunt-Vaisala frequency $N$ is small, either in the deep ocean or 
     70  in the sub-mesoscale motions of the mixed layer, or near the equator \citep[][section 1]{white.hoskins.ea_QJRMS05}.  
     71  They can be consistently included as part of the ocean dynamics \citep[][section 3(d)]{white.hoskins.ea_QJRMS05} and are  
     72  retained in the MIT ocean model.      
    6573\end{enumerate} 
    6674 
    6775Because the gravitational force is so dominant in the equations of large-scale motions, 
    68 it is useful to choose an orthogonal set of unit vectors $(i,j,k)$ linked to the earth such that 
     76it is useful to choose an orthogonal set of unit vectors $(i,j,k)$ linked to the Earth such that 
    6977$k$ is the local upward vector and $(i,j)$ are two vectors orthogonal to $k$, 
    7078\ie tangent to the geopotential surfaces. 
     
    107115an air-sea or ice-sea interface at its top. 
    108116These boundaries can be defined by two surfaces, $z = - H(i,j)$ and $z = \eta(i,j,k,t)$, 
    109 where $H$ is the depth of the ocean bottom and $\eta$ is the height of the sea surface. 
    110 Both $H$ and $\eta$ are usually referenced to a given surface, $z = 0$, chosen as a mean sea surface 
     117where $H$ is the depth of the ocean bottom and $\eta$ is the height of the sea surface  
     118(discretisation can introduce additional artificial ``side-wall'' boundaries).  
     119Both $H$ and $\eta$ are referenced to a surface of constant geopotential (\ie a mean sea surface height) on which $z = 0$.  
    111120(\autoref{fig:ocean_bc}). 
    112121Through these two boundaries, the ocean can exchange fluxes of heat, fresh water, salt, and momentum with 
     
    120129\begin{figure}[!ht] 
    121130  \begin{center} 
    122     \includegraphics[]{Fig_I_ocean_bc} 
     131    \includegraphics[width=\textwidth]{Fig_I_ocean_bc} 
    123132    \caption{ 
    124133      \protect\label{fig:ocean_bc} 
     
    210219The flow is barotropic and the surface moves up and down with gravity as the restoring force. 
    211220The phase speed of such waves is high (some hundreds of metres per second) so that 
    212 the time step would have to be very short if they were present in the model. 
     221the time step has to be very short when they are present in the model. 
    213222The latter strategy filters out these waves since the rigid lid approximation implies $\eta = 0$, 
    214223\ie the sea surface is the surface $z = 0$. 
     
    217226The rigid-lid hypothesis is an obsolescent feature in modern OGCMs. 
    218227It has been available until the release 3.1 of \NEMO, and it has been removed in release 3.2 and followings. 
    219 Only the free surface formulation is now described in the this document (see the next sub-section). 
     228Only the free surface formulation is now described in this document (see the next sub-section). 
    220229 
    221230% ------------------------------------------------------------------------------------------------------------- 
     
    237246Allowing the air-sea interface to move introduces the external gravity waves (EGWs) as 
    238247a class of solution of the primitive equations. 
    239 These waves are barotropic because of hydrostatic assumption, and their phase speed is quite high. 
     248These waves are barotropic (\ie nearly independent of depth) and their phase speed is quite high. 
    240249Their time scale is short with respect to the other processes described by the primitive equations. 
    241250 
     
    258267If further, an approximative conservation of heat and salt contents is sufficient for the problem solved, 
    259268then it is sufficient to solve a linearized version of \autoref{eq:PE_ssh}, 
    260 which still allows to take into account freshwater fluxes applied at the ocean surface \citep{Roullet_Madec_JGR00}. 
     269which still allows to take into account freshwater fluxes applied at the ocean surface \citep{roullet.madec_JGR00}. 
    261270Nevertheless, with the linearization, an exact conservation of heat and salt contents is lost. 
    262271 
    263272The filtering of EGWs in models with a free surface is usually a matter of discretisation of 
    264273the temporal derivatives, 
    265 using a split-explicit method \citep{Killworth_al_JPO91, Zhang_Endoh_JGR92} or 
    266 the implicit scheme \citep{Dukowicz1994} or 
    267 the addition of a filtering force in the momentum equation \citep{Roullet_Madec_JGR00}. 
    268 With the present release, \NEMO offers the choice between 
     274using a split-explicit method \citep{killworth.webb.ea_JPO91, zhang.endoh_JGR92} or 
     275the implicit scheme \citep{dukowicz.smith_JGR94} or 
     276the addition of a filtering force in the momentum equation \citep{roullet.madec_JGR00}. 
     277With the present release, \NEMO  offers the choice between 
    269278an explicit free surface (see \autoref{subsec:DYN_spg_exp}) or 
    270 a split-explicit scheme strongly inspired the one proposed by \citet{Shchepetkin_McWilliams_OM05} 
     279a split-explicit scheme strongly inspired the one proposed by \citet{shchepetkin.mcwilliams_OM05} 
    271280(see \autoref{subsec:DYN_spg_ts}). 
    272281 
     
    292301cannot be easily treated in a global model without filtering. 
    293302A solution consists of introducing an appropriate coordinate transformation that 
    294 shifts the singular point onto land \citep{Madec_Imbard_CD96, Murray_JCP96}. 
     303shifts the singular point onto land \citep{madec.imbard_CD96, murray_JCP96}. 
    295304As a consequence, it is important to solve the primitive equations in various curvilinear coordinate systems. 
    296305An efficient way of introducing an appropriate coordinate transform can be found when using a tensorial formalism. 
     
    298307Ocean modellers mainly use three-dimensional orthogonal grids on the sphere (spherical earth approximation), 
    299308with preservation of the local vertical. Here we give the simplified equations for this particular case. 
    300 The general case is detailed by \citet{Eiseman1980} in their survey of the conservation laws of fluid dynamics. 
     309The general case is detailed by \citet{eiseman.stone_SR80} in their survey of the conservation laws of fluid dynamics. 
    301310 
    302311Let $(i,j,k)$ be a set of orthogonal curvilinear coordinates on 
     
    323332\begin{figure}[!tb] 
    324333  \begin{center} 
    325     \includegraphics[]{Fig_I_earth_referential} 
     334    \includegraphics[width=\textwidth]{Fig_I_earth_referential} 
    326335    \caption{ 
    327336      \protect\label{fig:referential} 
     
    338347the vertical scale factor is a single function of $k$ as $k$ is parallel to $z$. 
    339348The scalar and vector operators that appear in the primitive equations 
    340 (\autoref{eq:PE_dyn} to \autoref{eq:PE_eos}) can be written in the tensorial form, 
     349(\autoref{eq:PE_dyn} to \autoref{eq:PE_eos}) can then be written in the tensorial form, 
    341350invariant in any orthogonal horizontal curvilinear coordinate system transformation: 
    342351\begin{subequations} 
     
    384393\end{gather} 
    385394 
    386 Using the fact that the horizontal scale factors $e_1$ and $e_2$ are independent of $k$ and that 
     395Using again the fact that the horizontal scale factors $e_1$ and $e_2$ are independent of $k$ and that 
    387396$e_3$  is a function of the single variable $k$, 
    388397$NLT$ the nonlinear term of \autoref{eq:PE_dyn} can be transformed as follows: 
     
    456465  &      &= &\nabla \cdot (\vect U \, u) - (\nabla \cdot \vect U) \ u 
    457466            + \frac{1}{e_1 e_2} \lt( -v^2 \pd[e_2]{i} + u v \, \pd[e_1]{j} \rt) \\ 
    458   \intertext{as $\nabla \cdot {\vect U} \; = 0$ (incompressibility) it comes:} 
     467  \intertext{as $\nabla \cdot {\vect U} \; = 0$ (incompressibility) it becomes:} 
    459468  &      &= &\, \nabla \cdot (\vect U \, u) + \frac{1}{e_1 e_2} \lt( v \; \pd[e_2]{i} - u \; \pd[e_1]{j} \rt) (-v) 
    460469\end{alignat*} 
     
    516525    % \label{eq:PE_dyn_flux_v} 
    517526    \pd[v]{t} = - \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, u \\ 
    518                 + \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, v)]{i} + \pd[(e_1 \, v \, v)]{j} \rt) \\ 
     527                - \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, v)]{i} + \pd[(e_1 \, v \, v)]{j} \rt) \\ 
    519528                - \frac{1}{e_3} \pd[(w \, v)]{k} - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) 
    520529                + D_v^{\vect U} + F_v^{\vect U} 
     
    526535    p_s = \rho \,g \, \eta 
    527536  \] 
    528   with $\eta$ is solution of \autoref{eq:PE_ssh}. 
     537  and $\eta$ is the solution of \autoref{eq:PE_ssh}. 
    529538 
    530539  The vertical velocity and the hydrostatic pressure are diagnosed from the following equations: 
     
    536545  \] 
    537546  where the divergence of the horizontal velocity, $\chi$ is given by \autoref{eq:PE_div_Uh}. 
    538 \item \textit{tracer equations}: 
    539   \[ 
    540     %\label{eq:S} 
    541     \pd[T]{t} = - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 T \, u)]{i} + \pd[(e_1 T \, v)]{j} \rt] 
     547 
     548\item  
     549  \textbf{tracer equations}: 
     550  \begin{equation} 
     551  \begin{split} 
     552    \pd[T]{t} = & - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 T \, u)]{i} + \pd[(e_1 T \, v)]{j} \rt] 
    542553                - \frac{1}{e_3} \pd[(T \, w)]{k} + D^T + F^T \\ 
    543     %\label{eq:T} 
    544     \pd[S]{t} = - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 S \, u)]{i} + \pd[(e_1 S \, v)]{j} \rt] 
    545                 - \frac{1}{e_3} \pd[(S \, w)]{k} + D^S + F^S 
    546     %\label{eq:rho} 
    547     \rho = \rho \big( T,S,z(k) \big) 
    548   \] 
     554    \pd[S]{t} = & - \frac{1}{e_1 e_2} \lt[ \pd[(e_2 S \, u)]{i} + \pd[(e_1 S \, v)]{j} \rt] 
     555                - \frac{1}{e_3} \pd[(S \, w)]{k} + D^S + F^S \\ 
     556    \rho = & \rho \big( T,S,z(k) \big) 
     557  \end{split} 
     558  \end{equation} 
    549559\end{itemize} 
    550560 
     
    575585follows the isopycnal surfaces, \eg an isopycnic coordinate. 
    576586 
    577 In order to satisfy two or more constrains one can even be tempted to mixed these coordinate systems, as in 
     587In order to satisfy two or more constraints one can even be tempted to mixed these coordinate systems, as in 
    578588HYCOM (mixture of $z$-coordinate at the surface, isopycnic coordinate in the ocean interior and $\sigma$ at 
    579 the ocean bottom) \citep{Chassignet_al_JPO03} or 
     589the ocean bottom) \citep{chassignet.smith.ea_JPO03} or 
    580590OPA (mixture of $z$-coordinate in vicinity the surface and steep topography areas and $\sigma$-coordinate elsewhere) 
    581 \citep{Madec_al_JPO96} among others. 
     591\citep{madec.delecluse.ea_JPO96} among others. 
    582592 
    583593In fact one is totally free to choose any space and time vertical coordinate by 
     
    592602the $(i,j,s,t)$ generalised coordinate system with $s$ depending on the other three variables through 
    593603\autoref{eq:PE_s}. 
    594 This so-called \textit{generalised vertical coordinate} \citep{Kasahara_MWR74} is in fact 
     604This so-called \textit{generalised vertical coordinate} \citep{kasahara_MWR74} is in fact 
    595605an Arbitrary Lagrangian--Eulerian (ALE) coordinate. 
    596 Indeed, choosing an expression for $s$ is an arbitrary choice that determines 
     606Indeed, one has a great deal of freedom in the choice of expression for $s$. The choice determines 
    597607which part of the vertical velocity (defined from a fixed referential) will cross the levels (Eulerian part) and 
    598608which part will be used to move them (Lagrangian part). 
    599 The coordinate is also sometime referenced as an adaptive coordinate \citep{Hofmeister_al_OM09}, 
     609The coordinate is also sometime referenced as an adaptive coordinate \citep{hofmeister.burchard.ea_OM10}, 
    600610since the coordinate system is adapted in the course of the simulation. 
    601611Its most often used implementation is via an ALE algorithm, 
    602612in which a pure lagrangian step is followed by regridding and remapping steps, 
    603 the later step implicitly embedding the vertical advection 
    604 \citep{Hirt_al_JCP74, Chassignet_al_JPO03, White_al_JCP09}. 
    605 Here we follow the \citep{Kasahara_MWR74} strategy: 
    606 a regridding step (an update of the vertical coordinate) followed by an eulerian step with 
     613the latter step implicitly embedding the vertical advection 
     614\citep{hirt.amsden.ea_JCP74, chassignet.smith.ea_JPO03, white.adcroft.ea_JCP09}. 
     615Here we follow the \citep{kasahara_MWR74} strategy: 
     616a regridding step (an update of the vertical coordinate) followed by an Eulerian step with 
    607617an explicit computation of vertical advection relative to the moving s-surfaces. 
    608618 
    609619%\gmcomment{ 
    610620%A key point here is that the $s$-coordinate depends on $(i,j)$ ==> horizontal pressure gradient... 
    611 the generalized vertical coordinates used in ocean modelling are not orthogonal, 
     621The generalized vertical coordinates used in ocean modelling are not orthogonal, 
    612622which contrasts with many other applications in mathematical physics. 
    613623Hence, it is useful to keep in mind the following properties that may seem odd on initial encounter. 
     
    615625The horizontal velocity in ocean models measures motions in the horizontal plane, 
    616626perpendicular to the local gravitational field. 
    617 That is, horizontal velocity is mathematically the same regardless the vertical coordinate, be it geopotential, 
     627That is, horizontal velocity is mathematically the same regardless of the vertical coordinate, be it geopotential, 
    618628isopycnal, pressure, or terrain following. 
    619629The key motivation for maintaining the same horizontal velocity component is that 
     
    660670\[ 
    661671  % \label{eq:PE_sco_w} 
    662   \omega = w - e_3 \, \pd[s]{t} - \sigma_1 \, u - \sigma_2 \, v 
     672  \omega = w -  \, \lt. \pd[z]{t} \rt|_s - \sigma_1 \, u - \sigma_2 \, v 
    663673\] 
    664674 
     
    671681  % \label{eq:PE_sco_u_vector} 
    672682    \pd[u]{t} = + (\zeta + f) \, v - \frac{1}{2 \, e_1} \pd[]{i} (u^2 + v^2) - \frac{1}{e_3} \omega \pd[u]{k} \\ 
    673                 - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) + g \frac{\rho}{\rho_o} \sigma_1 
     683                - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) - g \frac{\rho}{\rho_o} \sigma_1 
    674684                + D_u^{\vect U} + F_u^{\vect U} 
    675685  \end{multline*} 
     
    677687  % \label{eq:PE_sco_v_vector} 
    678688    \pd[v]{t} = - (\zeta + f) \, u - \frac{1}{2 \, e_2} \pd[]{j}(u^2 + v^2) - \frac{1}{e_3} \omega \pd[v]{k} \\ 
    679                 - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) + g \frac{\rho}{\rho_o} \sigma_2 
     689                - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) - g \frac{\rho}{\rho_o} \sigma_2 
    680690                + D_v^{\vect U} + F_v^{\vect U} 
    681691  \end{multline*} 
     
    687697                                       - \frac{1}{e_3} \pd[(\omega \, u)]{k} 
    688698                                       - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) 
    689                                        + g \frac{\rho}{\rho_o} \sigma_1 + D_u^{\vect U} + F_u^{\vect U} 
     699                                       - g \frac{\rho}{\rho_o} \sigma_1 + D_u^{\vect U} + F_u^{\vect U} 
    690700  \end{multline*} 
    691701  \begin{multline*} 
     
    695705                                       - \frac{1}{e_3} \pd[(\omega \, v)]{k} 
    696706                                       - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) 
    697                                        + g \frac{\rho}{\rho_o}\sigma_2 + D_v^{\vect U} + F_v^{\vect U} 
     707                                       - g \frac{\rho}{\rho_o}\sigma_2 + D_v^{\vect U} + F_v^{\vect U} 
    698708  \end{multline*} 
    699709  where the relative vorticity, $\zeta$, the surface pressure gradient, 
     
    738748\begin{figure}[!b] 
    739749  \begin{center} 
    740     \includegraphics[]{Fig_z_zstar} 
     750    \includegraphics[width=\textwidth]{Fig_z_zstar} 
    741751    \caption{ 
    742752      \protect\label{fig:z_zstar} 
     
    744754      (b) $z$-coordinate in non-linear free surface case ; 
    745755      (c) re-scaled height coordinate 
    746       (become popular as the \zstar-coordinate \citep{Adcroft_Campin_OM04}). 
     756      (become popular as the \zstar-coordinate \citep{adcroft.campin_OM04}). 
    747757    } 
    748758  \end{center} 
     
    750760%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    751761 
    752 In that case, the free surface equation is nonlinear, and the variations of volume are fully taken into account. 
    753 These coordinates systems is presented in a report \citep{Levier2007} available on the \NEMO web site. 
     762In this case, the free surface equation is nonlinear, and the variations of volume are fully taken into account. 
     763These coordinates systems is presented in a report \citep{levier.treguier.ea_rpt07} available on the \NEMO web site. 
    754764 
    755765The \zstar coordinate approach is an unapproximated, non-linear free surface implementation which allows one to 
    756 deal with large amplitude free-surface variations relative to the vertical resolution \citep{Adcroft_Campin_OM04}. 
     766deal with large amplitude free-surface variations relative to the vertical resolution \citep{adcroft.campin_OM04}. 
    757767In the \zstar formulation, 
    758768the variation of the column thickness due to sea-surface undulations is not concentrated in the surface level, 
     
    766776The position (\zstar) and vertical discretization (\zstar) are expressed as: 
    767777\[ 
    768   % \label{eq:z-star} 
     778  % \label{eq:PE_z-star} 
    769779  H + \zstar = (H + z)  / r \quad \text{and}  \quad \delta \zstar 
    770780              = \delta z / r \quad \text{with} \quad r 
    771               = \frac{H + \eta}{H} 
     781              = \frac{H + \eta}{H} . 
     782\] 
     783Simple re-organisation of the above expressions gives 
     784\[ 
     785  % \label{eq:PE_zstar_2} 
     786  \zstar = H \lt( \frac{z - \eta}{H + \eta} \rt) .  
    772787\] 
    773788Since the vertical displacement of the free surface is incorporated in the vertical coordinate \zstar, 
     
    776791Also the divergence of the flow field is no longer zero as shown by the continuity equation: 
    777792\[ 
    778   \pd[r]{t} = \nabla_{\zstar} \cdot \lt( r \; \vect U_h \rt) (r \; w *) = 0 
     793  \pd[r]{t} = \nabla_{\zstar} \cdot \lt( r \; \vect U_h \rt) + \pd[r \; w^*]{\zstar} = 0 . 
    779794\] 
    780  
    781 % from MOM4p1 documentation 
    782 To overcome problems with vanishing surface and/or bottom cells, we consider the zstar coordinate  
    783 \[ 
    784   % \label{eq:PE_} 
    785   \zstar = H \lt( \frac{z - \eta}{H + \eta} \rt) 
    786 \] 
    787  
    788 This coordinate is closely related to the "eta" coordinate used in many atmospheric models 
     795This \zstar coordinate is closely related to the "eta" coordinate used in many atmospheric models 
    789796(see Black (1994) for a review of eta coordinate atmospheric models). 
    790797It was originally used in ocean models by Stacey et al. (1995) for studies of tides next to shelves, 
     
    798805These properties greatly reduce difficulties of computing the horizontal pressure gradient relative to 
    799806terrain following sigma models discussed in \autoref{subsec:PE_sco}. 
    800 Additionally, since \zstar when $\eta = 0$, 
     807Additionally, since $\zstar = z$ when $\eta = 0$, 
    801808no flow is spontaneously generated in an unforced ocean starting from rest, regardless the bottom topography. 
    802809This behaviour is in contrast to the case with "s"-models, where pressure gradient errors in the presence of 
     
    804811depending on the sophistication of the pressure gradient solver. 
    805812The quasi -horizontal nature of the coordinate surfaces also facilitates the implementation of 
    806 neutral physics parameterizations in \zstar models using the same techniques as in $z$-models 
    807 (see Chapters 13-16 of \cite{Griffies_Bk04}) for a discussion of neutral physics in $z$-models, 
     813neutral physics parameterizations in \zstar  models using the same techniques as in $z$-models 
     814(see Chapters 13-16 of \cite{griffies_bk04}) for a discussion of neutral physics in $z$-models, 
    808815as well as \autoref{sec:LDF_slp} in this document for treatment in \NEMO). 
    809816 
    810 The range over which \zstar varies is time independent $-H \leq \zstar \leq 0$. 
    811 Hence, all cells remain nonvanishing, so long as the surface height maintains $\eta > ?H$. 
     817The range over which \zstar  varies is time independent $-H \leq \zstar \leq 0$. 
     818Hence, all cells remain nonvanishing, so long as the surface height maintains $\eta > -H$. 
    812819This is a minor constraint relative to that encountered on the surface height when using $s = z$ or $s = z - \eta$. 
    813820 
    814 Because \zstar has a time independent range, all grid cells have static increments ds, 
    815 and the sum of the ver tical increments yields the time independent ocean depth. %k ds = H. 
     821Because \zstar  has a time independent range, all grid cells have static increments ds, 
     822and the sum of the vertical increments yields the time independent ocean depth. %k ds = H. 
    816823The \zstar coordinate is therefore invisible to undulations of the free surface, 
    817824since it moves along with the free surface. 
    818 This proper ty means that no spurious vertical transport is induced across surfaces of constant \zstar by 
     825This property means that no spurious vertical transport is induced across surfaces of constant \zstar by 
    819826the motion of external gravity waves. 
    820 Such spurious transpor t can be a problem in z-models, especially those with tidal forcing. 
    821 Quite generally, the time independent range for the \zstar coordinate is a very convenient property that 
    822 allows for a nearly arbitrary ver tical resolution even in the presence of large amplitude fluctuations of 
     827Such spurious transport can be a problem in z-models, especially those with tidal forcing. 
     828Quite generally, the time independent range for the \zstar  coordinate is a very convenient property that 
     829allows for a nearly arbitrary vertical resolution even in the presence of large amplitude fluctuations of 
    823830the surface height, again so long as $\eta > -H$. 
    824831%end MOM doc %%% 
     
    849856The response to such a velocity field often leads to numerical dispersion effects. 
    850857One solution to strongly reduce this error is to use a partial step representation of bottom topography instead of 
    851 a full step one \cite{Pacanowski_Gnanadesikan_MWR98}. 
     858a full step one \cite{pacanowski.gnanadesikan_MWR98}. 
    852859Another solution is to introduce a terrain-following coordinate system (hereafter $s$-coordinate). 
    853860 
     
    870877\begin{equation} 
    871878  \label{eq:PE_p_sco} 
    872   \nabla p |_z = \nabla p |_s - \pd[p]{s} \nabla z |_s 
     879  \nabla p |_z = \nabla p |_s - \frac{1}{e_3} \pd[p]{s} \nabla z |_s 
    873880\end{equation} 
    874881 
    875882The second term in \autoref{eq:PE_p_sco} depends on the tilt of the coordinate surface and 
    876 introduces a truncation error that is not present in a $z$-model. 
     883leads to a truncation error that is not present in a $z$-model. 
    877884In the special case of a $\sigma$-coordinate (i.e. a depth-normalised coordinate system $\sigma = z/H$), 
    878 \citet{Haney1991} and \citet{Beckmann1993} have given estimates of the magnitude of this truncation error. 
     885\citet{haney_JPO91} and \citet{beckmann.haidvogel_JPO93} have given estimates of the magnitude of this truncation error. 
    879886It depends on topographic slope, stratification, horizontal and vertical resolution, the equation of state, 
    880887and the finite difference scheme. 
     
    884891The large-scale slopes require high horizontal resolution, and the computational cost becomes prohibitive. 
    885892This problem can be at least partially overcome by mixing $s$-coordinate and 
    886 step-like representation of bottom topography \citep{Gerdes1993a,Gerdes1993b,Madec_al_JPO96}. 
     893step-like representation of bottom topography \citep{gerdes_JGR93*a,gerdes_JGR93*b,madec.delecluse.ea_JPO96}. 
    887894However, the definition of the model domain vertical coordinate becomes then a non-trivial thing for 
    888895a realistic bottom topography: 
    889 a envelope topography is defined in $s$-coordinate on which a full or 
     896an envelope topography is defined in $s$-coordinate on which a full or 
    890897partial step bottom topography is then applied in order to adjust the model depth to the observed one 
    891898(see \autoref{sec:DOM_zgr}. 
     
    904911In contrast, the ocean will stay at rest in a $z$-model. 
    905912As for the truncation error, the problem can be reduced by introducing the terrain-following coordinate below 
    906 the strongly stratified portion of the water column (\ie the main thermocline) \citep{Madec_al_JPO96}. 
     913the strongly stratified portion of the water column (\ie the main thermocline) \citep{madec.delecluse.ea_JPO96}. 
    907914An alternate solution consists of rotating the lateral diffusive tensor to geopotential or to isoneutral surfaces 
    908915(see \autoref{subsec:PE_ldf}). 
     
    910917strongly exceeding the stability limit of such a operator when it is discretized (see \autoref{chap:LDF}). 
    911918 
    912 The $s$-coordinates introduced here \citep{Lott_al_OM90,Madec_al_JPO96} differ mainly in two aspects from 
     919The $s$-coordinates introduced here \citep{lott.madec.ea_OM90,madec.delecluse.ea_JPO96} differ mainly in two aspects from 
    913920similar models: 
    914921it allows a representation of bottom topography with mixed full or partial step-like/terrain following topography; 
     
    921928\label{subsec:PE_zco_tilde} 
    922929 
    923 The \ztilde -coordinate has been developed by \citet{Leclair_Madec_OM11}. 
    924 It is available in \NEMO since the version 3.4. 
     930The \ztilde -coordinate has been developed by \citet{leclair.madec_OM11}. 
     931It is available in \NEMO since the version 3.4 and is more robust in version 4.0 than previously.  
    925932Nevertheless, it is currently not robust enough to be used in all possible configurations. 
    926933Its use is therefore not recommended. 
     
    934941\label{sec:PE_zdf_ldf} 
    935942 
    936 The primitive equations describe the behaviour of a geophysical fluid at space and time scales larger than 
     943The hydrostatic primitive equations describe the behaviour of a geophysical fluid at space and time scales larger than 
    937944a few kilometres in the horizontal, a few meters in the vertical and a few minutes. 
    938945They are usually solved at larger scales: the specified grid spacing and time step of the numerical model. 
     
    984991All the vertical physics is embedded in the specification of the eddy coefficients. 
    985992They can be assumed to be either constant, or function of the local fluid properties 
    986 (\eg Richardson number, Brunt-Vais\"{a}l\"{a} frequency...), 
     993(\eg Richardson number, Brunt-Vais\"{a}l\"{a} frequency, distance from the boundary ...), 
    987994or computed from a turbulent closure model. 
    988995The choices available in \NEMO are discussed in \autoref{chap:ZDF}). 
     
    10051012The resulting lateral diffusive and dissipative operators are of second order. 
    10061013Observations show that lateral mixing induced by mesoscale turbulence tends to be along isopycnal surfaces 
    1007 (or more precisely neutral surfaces \cite{McDougall1987}) rather than across them. 
     1014(or more precisely neutral surfaces \cite{mcdougall_JPO87}) rather than across them. 
    10081015As the slope of neutral surfaces is small in the ocean, a common approximation is to assume that 
    10091016the `lateral' direction is the horizontal, \ie the lateral mixing is performed along geopotential surfaces. 
     
    10161023both horizontal and isoneutral operators have no effect on mean (\ie large scale) potential energy whereas 
    10171024potential energy is a main source of turbulence (through baroclinic instabilities). 
    1018 \citet{Gent1990} have proposed a parameterisation of mesoscale eddy-induced turbulence which 
     1025\citet{gent.mcwilliams_JPO90} proposed a parameterisation of mesoscale eddy-induced turbulence which 
    10191026associates an eddy-induced velocity to the isoneutral diffusion. 
    10201027Its mean effect is to reduce the mean potential energy of the ocean. 
     
    10331040Another approach is becoming more and more popular: 
    10341041instead of specifying explicitly a sub-grid scale term in the momentum and tracer time evolution equations, 
    1035 one uses a advective scheme which is diffusive enough to maintain the model stability. 
     1042one uses an advective scheme which is diffusive enough to maintain the model stability. 
    10361043It must be emphasised that then, all the sub-grid scale physics is included in the formulation of 
    10371044the advection scheme. 
    10381045 
    10391046All these parameterisations of subgrid scale physics have advantages and drawbacks. 
    1040 There are not all available in \NEMO. For active tracers (temperature and salinity) the main ones are: 
     1047They are not all available in \NEMO. For active tracers (temperature and salinity) the main ones are: 
    10411048Laplacian and bilaplacian operators acting along geopotential or iso-neutral surfaces, 
    1042 \citet{Gent1990} parameterisation, and various slightly diffusive advection schemes. 
     1049\citet{gent.mcwilliams_JPO90} parameterisation, and various slightly diffusive advection schemes. 
    10431050For momentum, the main ones are: Laplacian and bilaplacian operators acting along geopotential surfaces, 
    10441051and UBS advection schemes when flux form is chosen for the momentum advection. 
     
    10621069the rotation between geopotential and $s$-surfaces, 
    10631070while it is only an approximation for the rotation between isoneutral and $z$- or $s$-surfaces. 
    1064 Indeed, in the latter case, two assumptions are made to simplify \autoref{eq:PE_iso_tensor} \citep{Cox1987}. 
     1071Indeed, in the latter case, two assumptions are made to simplify \autoref{eq:PE_iso_tensor} \citep{cox_OM87}. 
    10651072First, the horizontal contribution of the dianeutral mixing is neglected since the ratio between iso and 
    10661073dia-neutral diffusive coefficients is known to be several orders of magnitude smaller than unity. 
     
    10871094\subsubsection{Eddy induced velocity} 
    10881095 
    1089 When the \textit{eddy induced velocity} parametrisation (eiv) \citep{Gent1990} is used, 
     1096When the \textit{eddy induced velocity} parametrisation (eiv) \citep{gent.mcwilliams_JPO90} is used, 
    10901097an additional tracer advection is introduced in combination with the isoneutral diffusion of tracers: 
    10911098\[ 
     
    11411148                         - \nabla_h \times \big( A^{lm} \, \zeta \; \vect k \big) \\ 
    11421149                      &= \lt(   \frac{1}{e_1}     \pd[ \lt( A^{lm}    \chi      \rt) ]{i} \rt. 
    1143                               - \frac{1}{e_2 e_3} \pd[ \lt( A^{lm} \; e_3 \zeta \rt) ]{j} 
     1150                              - \frac{1}{e_2 e_3} \pd[ \lt( A^{lm} \; e_3 \zeta \rt) ]{j} ,  
    11441151                                \frac{1}{e_2}     \pd[ \lt( A^{lm}    \chi      \rt) ]{j} 
    11451152                         \lt. + \frac{1}{e_1 e_3} \pd[ \lt( A^{lm} \; e_3 \zeta \rt) ]{i} \rt) 
     
    11621169\ie on a $f$- or $\beta$-plane, not on the sphere. 
    11631170It is also a very good approximation in vicinity of the Equator in 
    1164 a geographical coordinate system \citep{Lengaigne_al_JGR03}. 
    1165  
    1166 \subsubsection{lateral bilaplacian momentum diffusive operator} 
     1171a geographical coordinate system \citep{lengaigne.madec.ea_JGR03}. 
     1172 
     1173\subsubsection{Lateral bilaplacian momentum diffusive operator} 
    11671174 
    11681175As for tracers, the bilaplacian order momentum diffusive operator is a re-entering Laplacian operator with 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex

    r10544 r11422  
    1818 
    1919In that case, the free surface equation is nonlinear, and the variations of volume are fully taken into account. 
    20 These coordinates systems is presented in a report \citep{Levier2007} available on the \NEMO web site.  
     20These coordinates systems is presented in a report \citep{levier.treguier.ea_rpt07} available on the \NEMO web site.  
    2121 
    2222\colorbox{yellow}{  end of to be updated} 
     
    7373% Surface Pressure Gradient and Sea Surface Height 
    7474% ================================================================ 
    75 \section{Surface pressure gradient and sea surface heigth (\protect\mdl{dynspg})} 
     75\section[Surface pressure gradient and sea surface heigth (\textit{dynspg.F90})] 
     76{Surface pressure gradient and sea surface heigth (\protect\mdl{dynspg})} 
    7677\label{sec:DYN_hpg_spg} 
    7778%-----------------------------------------nam_dynspg---------------------------------------------------- 
     
    8990which imposes a very small time step when an explicit time stepping is used. 
    9091Two methods are proposed to allow a longer time step for the three-dimensional equations: 
    91 the filtered free surface, which is a modification of the continuous equations %(see \autoref{eq:PE_flt}), 
     92the filtered free surface, which is a modification of the continuous equations %(see \autoref{eq:PE_flt?}), 
    9293and the split-explicit free surface described below. 
    9394The extra term introduced in the filtered method is calculated implicitly, 
     
    9798% Explicit 
    9899%------------------------------------------------------------- 
    99 \subsubsection{Explicit (\protect\key{dynspg\_exp})} 
     100\subsubsection[Explicit (\texttt{\textbf{key\_dynspg\_exp}})] 
     101{Explicit (\protect\key{dynspg\_exp})} 
    100102\label{subsec:DYN_spg_exp} 
    101103 
     
    133135% Split-explicit time-stepping 
    134136%------------------------------------------------------------- 
    135 \subsubsection{Split-explicit time-stepping (\protect\key{dynspg\_ts})} 
     137\subsubsection[Split-explicit time-stepping (\texttt{\textbf{key\_dynspg\_ts}})] 
     138{Split-explicit time-stepping (\protect\key{dynspg\_ts})} 
    136139\label{subsec:DYN_spg_ts} 
    137140%--------------------------------------------namdom---------------------------------------------------- 
     
    139142\nlst{namdom}  
    140143%-------------------------------------------------------------------------------------------------------------- 
    141 The split-explicit free surface formulation used in OPA follows the one proposed by \citet{Griffies2004}. 
     144The split-explicit free surface formulation used in OPA follows the one proposed by \citet{Griffies2004?}. 
    142145The general idea is to solve the free surface equation with a small time step, 
    143146while the three dimensional prognostic variables are solved with a longer time step that 
     
    147150\begin{figure}[!t] 
    148151  \begin{center} 
    149     \includegraphics[width=0.90\textwidth]{Fig_DYN_dynspg_ts} 
     152    \includegraphics[width=\textwidth]{Fig_DYN_dynspg_ts} 
    150153    \caption{ 
    151154      \protect\label{fig:DYN_dynspg_ts} 
    152155      Schematic of the split-explicit time stepping scheme for the barotropic and baroclinic modes, 
    153       after \citet{Griffies2004}. 
     156      after \citet{Griffies2004?}. 
    154157      Time increases to the right. 
    155158      Baroclinic time steps are denoted by $t-\Delta t$, $t, t+\Delta t$, and $t+2\Delta t$. 
     
    171174 
    172175The split-explicit formulation has a damping effect on external gravity waves, 
    173 which is weaker than the filtered free surface but still significant as shown by \citet{Levier2007} in 
     176which is weaker than the filtered free surface but still significant as shown by \citet{levier.treguier.ea_rpt07} in 
    174177the case of an analytical barotropic Kelvin wave.  
    175178 
     
    291294% Filtered formulation  
    292295%------------------------------------------------------------- 
    293 \subsubsection{Filtered formulation (\protect\key{dynspg\_flt})} 
     296\subsubsection[Filtered formulation (\texttt{\textbf{key\_dynspg\_flt}})] 
     297{Filtered formulation (\protect\key{dynspg\_flt})} 
    294298\label{subsec:DYN_spg_flt} 
    295299 
    296 The filtered formulation follows the \citet{Roullet2000} implementation. 
     300The filtered formulation follows the \citet{Roullet2000?} implementation. 
    297301The extra term introduced in the equations (see {\S}I.2.2) is solved implicitly. 
    298302The elliptic solvers available in the code are documented in \autoref{chap:MISC}. 
    299303The amplitude of the extra term is given by the namelist variable \np{rnu}. 
    300 The default value is 1, as recommended by \citet{Roullet2000} 
     304The default value is 1, as recommended by \citet{Roullet2000?} 
    301305 
    302306\colorbox{red}{\np{rnu}\forcode{ = 1} to be suppressed from namelist !} 
     
    305309% Non-linear free surface formulation  
    306310%------------------------------------------------------------- 
    307 \subsection{Non-linear free surface formulation (\protect\key{vvl})} 
     311\subsection[Non-linear free surface formulation (\texttt{\textbf{key\_vvl}})] 
     312{Non-linear free surface formulation (\protect\key{vvl})} 
    308313\label{subsec:DYN_spg_vvl} 
    309314 
    310315In the non-linear free surface formulation, the variations of volume are fully taken into account. 
    311 This option is presented in a report \citep{Levier2007} available on the NEMO web site. 
     316This option is presented in a report \citep{levier.treguier.ea_rpt07} available on the NEMO web site. 
    312317The three time-stepping methods (explicit, split-explicit and filtered) are the same as in 
    313318\autoref{DYN_spg_linear} except that the ocean depth is now time-dependent. 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/chap_time_domain.tex

    r10501 r11422  
    1111 
    1212% Missing things: 
    13 %  - daymod: definition of the time domain (nit000, nitend andd the calendar) 
     13%  - daymod: definition of the time domain (nit000, nitend and the calendar) 
    1414 
    1515\gmcomment{STEVEN :maybe a picture of the directory structure in the introduction which could be referred to here, 
     
    2222a key feature of an ocean model as it exerts a strong influence on the structure of the computer code 
    2323(\ie on its flowchart). 
    24 In the present chapter, we provide a general description of the \NEMO time stepping strategy and 
     24In the present chapter, we provide a general description of the \NEMO  time stepping strategy and 
    2525the consequences for the order in which the equations are solved. 
    2626 
     
    4040$\rdt$ is the time step; 
    4141and the superscripts indicate the time at which a quantity is evaluated. 
    42 Each term of the RHS is evaluated at a specific time step depending on the physics with which it is associated. 
    43  
    44 The choice of the time step used for this evaluation is discussed below as well as 
     42Each term of the RHS is evaluated at a specific time stepping depending on the physics with which it is associated. 
     43 
     44The choice of the time stepping used for this evaluation is discussed below as well as 
    4545the implications for starting or restarting a model simulation. 
    4646Note that the time stepping calculation is generally performed in a single operation. 
     
    5353is usually not the variable at the after time step; 
    5454but rather it is used to store the time derivative (RHS in \autoref{eq:STP}) prior to time-stepping the equation. 
    55 Generally, the time stepping is performed once at each time step in the \mdl{tranxt} and \mdl{dynnxt} modules, 
    56 except when using implicit vertical diffusion or calculating sea surface height in which 
    57 case time-splitting options are used. 
     55The time stepping itself is performed once at each time step where implicit vertical diffusion is computed, \ie in the \mdl{trazdf} and \mdl{dynzdf} modules. 
    5856 
    5957% ------------------------------------------------------------------------------------------------------------- 
     
    6462 
    6563The time stepping used for processes other than diffusion is the well-known leapfrog scheme 
    66 \citep{Mesinger_Arakawa_Bk76}. 
     64\citep{mesinger.arakawa_bk76}. 
    6765This scheme is widely used for advection processes in low-viscosity fluids. 
    6866It is a time centred scheme, \ie the RHS in \autoref{eq:STP} is evaluated at time step $t$, the now time step. 
     
    8078To prevent it, the leapfrog scheme is often used in association with a Robert-Asselin time filter 
    8179(hereafter the LF-RA scheme). 
    82 This filter, first designed by \citet{Robert_JMSJ66} and more comprehensively studied by \citet{Asselin_MWR72}, 
     80This filter, first designed by \citet{robert_JMSJ66} and more comprehensively studied by \citet{asselin_MWR72}, 
    8381is a kind of laplacian diffusion in time that mixes odd and even time steps: 
    8482\begin{equation} 
     
    8886where the subscript $F$ denotes filtered values and $\gamma$ is the Asselin coefficient. 
    8987$\gamma$ is initialized as \np{rn\_atfp} (namelist parameter). 
    90 Its default value is \np{rn\_atfp}~\forcode{= 10.e-3} (see \autoref{sec:STP_mLF}), 
    91 causing only a weak dissipation of high frequency motions (\citep{Farge1987}). 
     88Its default value is \np{rn\_atfp}\forcode{ = 10.e-3} (see \autoref{sec:STP_mLF}), 
     89causing only a weak dissipation of high frequency motions (\citep{farge-coulombier_phd87}). 
    9290The addition of a time filter degrades the accuracy of the calculation from second to first order. 
    9391However, the second order truncation error is proportional to $\gamma$, which is small compared to 1. 
    9492Therefore, the LF-RA is a quasi second order accurate scheme. 
    9593The LF-RA scheme is preferred to other time differencing schemes such as predictor corrector or trapezoidal schemes, 
    96 because the user has an explicit and simple control of the magnitude of the time diffusion of the scheme. 
     94because the user has an explicit and simple control of the magnitude of the time diffusion of the scheme.  
    9795When used with the 2nd order space centred discretisation of the advection terms in 
    9896the momentum and tracer equations, LF-RA avoids implicit numerical diffusion: 
     
    107105 
    108106The leapfrog differencing scheme is unsuitable for the representation of diffusion and damping processes. 
    109 For a tendancy $D_x$, representing a diffusion term or a restoring term to a tracer climatology 
     107For a tendency $D_x$, representing a diffusion term or a restoring term to a tracer climatology 
    110108(when present, see \autoref{sec:TRA_dmp}), a forward time differencing scheme is used : 
    111109\[ 
     
    115113 
    116114This is diffusive in time and conditionally stable. 
    117 The conditions for stability of second and fourth order horizontal diffusion schemes are \citep{Griffies_Bk04}: 
     115The conditions for stability of second and fourth order horizontal diffusion schemes are \citep{griffies_bk04}: 
    118116\begin{equation} 
    119117  \label{eq:STP_euler_stability} 
     
    130128 
    131129For the vertical diffusion terms, a forward time differencing scheme can be used, 
    132 but usually the numerical stability condition imposes a strong constraint on the time step. 
    133 Two solutions are available in \NEMO to overcome the stability constraint: 
    134 $(a)$ a forward time differencing scheme using a time splitting technique (\np{ln\_zdfexp}~\forcode{= .true.}) or 
    135 $(b)$ a backward (or implicit) time differencing scheme                   (\np{ln\_zdfexp}~\forcode{= .false.}). 
    136 In $(a)$, the master time step $\Delta$t is cut into $N$ fractional time steps so that 
    137 the stability criterion is reduced by a factor of $N$. 
    138 The computation is performed as follows: 
    139 \begin{alignat*}{2} 
    140   % \label{eq:STP_ts} 
    141   &x_\ast^{t - \rdt}                      &= &x^{t - \rdt} \\ 
    142   &x_\ast^{t - \rdt + L \frac{2 \rdt}{N}} &=   &x_\ast ^{t - \rdt + (L - 1) \frac{2 \rdt}{N}} 
    143                                              + \frac{2 \rdt}{N} \; DF^{t - \rdt + (L - 1) \frac{2 \rdt}{N}} 
    144   \quad \text{for $L = 1$ to $N$} \\ 
    145   &x^{t + \rdt}                           &= &x_\ast^{t + \rdt} 
    146 \end{alignat*} 
    147 with DF a vertical diffusion term. 
    148 The number of fractional time steps, $N$, is given by setting \np{nn\_zdfexp}, (namelist parameter). 
    149 The scheme $(b)$ is unconditionally stable but diffusive. It can be written as follows: 
     130but usually the numerical stability condition imposes a strong constraint on the time step. To overcome the stability constraint, a  
     131backward (or implicit) time differencing scheme is used. This scheme is unconditionally stable but diffusive and can be written as follows: 
    150132\begin{equation} 
    151133  \label{eq:STP_imp} 
     
    157139%%gm 
    158140 
    159 This scheme is rather time consuming since it requires a matrix inversion, 
    160 but it becomes attractive since a value of 3 or more is needed for N in the forward time differencing scheme. 
    161 For example, the finite difference approximation of the temperature equation is: 
     141This scheme is rather time consuming since it requires a matrix inversion. For example, the finite difference approximation of the temperature equation is: 
    162142\[ 
    163143  % \label{eq:STP_imp_zdf} 
     
    183163$c(k)$ and $d(k)$ are positive and the diagonal term is greater than the sum of the two extra-diagonal terms, 
    184164therefore a special adaptation of the Gauss elimination procedure is used to find the solution 
    185 (see for example \citet{Richtmyer1967}). 
     165(see for example \citet{richtmyer.morton_bk67}). 
    186166 
    187167% ------------------------------------------------------------------------------------------------------------- 
     
    191171\label{sec:STP_spg_ts} 
    192172 
    193 ===>>>>  TO BE written....  :-) 
     173The leapfrog environment supports a centred in time computation of the surface pressure, \ie evaluated  
     174at \textit{now} time step. This refers to as the explicit free surface case in the code (\np{ln\_dynspg\_exp}\forcode{ = .true.}).  
     175This choice however imposes a strong constraint on the time step which should be small enough to resolve the propagation  
     176of external gravity waves. As a matter of fact, one rather use in a realistic setup, a split-explicit free surface  
     177(\np{ln\_dynspg\_ts}\forcode{ = .true.}) in which barotropic and baroclinic dynamical equations are solved separately with ad-hoc  
     178time steps. The use of the time-splitting (in combination with non-linear free surface) imposes some constraints on the design of  
     179the overall flowchart, in particular to ensure exact tracer conservation (see \autoref{fig:TimeStep_flowchart}). 
     180 
     181Compared to the former use of the filtered free surface in \NEMO v3.6 (\citet{roullet.madec_JGR00}), the use of a split-explicit free surface is advantageous  
     182on massively parallel computers. Indeed, no global computations are anymore required by the elliptic solver which saves a substantial amount of communication  
     183time. Fast barotropic motions (such as tides) are also simulated with a better accuracy.  
    194184 
    195185%\gmcomment{  
     
    197187\begin{figure}[!t] 
    198188  \begin{center} 
    199     \includegraphics[]{Fig_TimeStepping_flowchart} 
     189    \includegraphics[width=\textwidth]{Fig_TimeStepping_flowchart_v4} 
    200190    \caption{ 
    201191      \protect\label{fig:TimeStep_flowchart} 
    202       Sketch of the leapfrog time stepping sequence in \NEMO from \citet{Leclair_Madec_OM09}. 
    203       The use of a semi -implicit computation of the hydrostatic pressure gradient requires the tracer equation to 
    204       be stepped forward prior to the momentum equation. 
    205       The need for knowledge of the vertical scale factor (here denoted as $h$) requires the sea surface height and 
    206       the continuity equation to be stepped forward prior to the computation of the tracer equation. 
    207       Note that the method for the evaluation of the surface pressure gradient $\nabla p_s$ is not presented here 
    208       (see \autoref{sec:DYN_spg}). 
     192      Sketch of the leapfrog time stepping sequence in \NEMO with split-explicit free surface. The latter combined 
     193       with non-linear free surface requires the dynamical tendency being updated prior tracers tendency to ensure  
     194       conservation. Note the use of time integrated fluxes issued from the barotropic loop  in subsequent calculations  
     195       of tracer advection and in the continuity equation. Details about the time-splitting scheme can be found  
     196       in \autoref{subsec:DYN_spg_ts}. 
    209197    } 
    210198  \end{center} 
     
    219207\label{sec:STP_mLF} 
    220208 
    221 Significant changes have been introduced by \cite{Leclair_Madec_OM09} in the LF-RA scheme in order to 
     209Significant changes have been introduced by \cite{leclair.madec_OM09} in the LF-RA scheme in order to 
    222210ensure tracer conservation and to allow the use of a much smaller value of the Asselin filter parameter. 
    223211The modifications affect both the forcing and filtering treatments in the LF-RA scheme. 
     
    237225The change in the forcing formulation given by \autoref{eq:STP_forcing} (see \autoref{fig:MLF_forcing}) 
    238226has a significant effect: 
    239 the forcing term no longer excites the divergence of odd and even time steps \citep{Leclair_Madec_OM09}. 
     227the forcing term no longer excites the divergence of odd and even time steps \citep{leclair.madec_OM09}. 
    240228% forcing seen by the model.... 
    241 This property improves the LF-RA scheme in two respects. 
     229This property improves the LF-RA scheme in two aspects. 
    242230First, the LF-RA can now ensure the local and global conservation of tracers. 
    243231Indeed, time filtering is no longer required on the forcing part. 
    244 The influence of the Asselin filter on the forcing is be removed by adding a new term in the filter 
     232The influence of the Asselin filter on the forcing is explicitly removed by adding a new term in the filter 
    245233(last term in \autoref{eq:STP_RA} compared to \autoref{eq:STP_asselin}). 
    246234Since the filtering of the forcing was the source of non-conservation in the classical LF-RA scheme, 
    247 the modified formulation becomes conservative \citep{Leclair_Madec_OM09}. 
     235the modified formulation becomes conservative \citep{leclair.madec_OM09}. 
    248236Second, the LF-RA becomes a truly quasi -second order scheme. 
    249237Indeed, \autoref{eq:STP_forcing} used in combination with a careful treatment of static instability 
    250 (\autoref{subsec:ZDF_evd}) and of the TKE physics (\autoref{subsec:ZDF_tke_ene}), 
    251 the two other main sources of time step divergence, 
     238(\autoref{subsec:ZDF_evd}) and of the TKE physics (\autoref{subsec:ZDF_tke_ene})  
     239(the two other main sources of time step divergence), 
    252240allows a reduction by two orders of magnitude of the Asselin filter parameter. 
    253241 
     
    255243$Q^{t + \rdt / 2}$ is the forcing applied over the $[t,t + \rdt]$ time interval. 
    256244This and the change in the time filter, \autoref{eq:STP_RA}, 
    257 allows an exact evaluation of the contribution due to the forcing term between any two time steps, 
     245allows for an exact evaluation of the contribution due to the forcing term between any two time steps, 
    258246even if separated by only $\rdt$ since the time filter is no longer applied to the forcing term. 
    259247 
     
    261249\begin{figure}[!t] 
    262250  \begin{center} 
    263     \includegraphics[]{Fig_MLF_forcing} 
     251    \includegraphics[width=\textwidth]{Fig_MLF_forcing} 
    264252    \caption{ 
    265253      \protect\label{fig:MLF_forcing} 
     
    294282This is done simply by keeping the leapfrog environment (\ie the \autoref{eq:STP} three level time stepping) but 
    295283setting all $x^0$ (\textit{before}) and $x^1$ (\textit{now}) fields equal at the first time step and 
    296 using half the value of $\rdt$. 
     284using half the value of a leapfrog time step ($2 \rdt$).  
    297285 
    298286It is also possible to restart from a previous computation, by using a restart file. 
     
    303291This requires saving two time levels and many auxiliary data in the restart files in machine precision. 
    304292 
    305 Note that when a semi -implicit scheme is used to evaluate the hydrostatic pressure gradient 
    306 (see \autoref{subsec:DYN_hpg_imp}), an extra three-dimensional field has to 
    307 be added to the restart file to ensure an exact restartability. 
    308 This is done optionally via the  \np{nn\_dynhpg\_rst} namelist parameter, 
    309 so that the size of the restart file can be reduced when restartability is not a key issue 
    310 (operational oceanography or in ensemble simulations for seasonal forecasting). 
    311  
    312 Note the size of the time step used, $\rdt$, is also saved in the restart file. 
    313 When restarting, if the the time step has been changed, a restart using an Euler time stepping scheme is imposed. 
    314 Options are defined through the  \ngn{namrun} namelist variables. 
     293Note that the time step $\rdt$, is also saved in the restart file. 
     294When restarting, if the time step has been changed, or one of the prognostic variables at \textit{before} time step  
     295is missing, an Euler time stepping scheme is imposed. A forward initial step can still be enforced by the user by setting  
     296the namelist variable \np{nn\_euler}\forcode{=0}. Other options to control the time integration of the model  
     297are defined through the  \ngn{namrun} namelist variables. 
    315298%%% 
    316299\gmcomment{ 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/NEMO/subfiles/introduction.tex

    r10544 r11422  
    2727 
    2828The ocean component of \NEMO has been developed from the legacy of the OPA model, release 8.2,  
    29 described in \citet{Madec1998}. 
     29described in \citet{madec.delecluse.ea_NPM98}. 
    3030This model has been used for a wide range of applications, both regional or global, as a forced ocean model and  
    3131as a model coupled with the sea-ice and/or the atmosphere. 
     
    6767Within the \NEMO system the ocean model is interactively coupled with a sea ice model (SI$^3$) and 
    6868a biogeochemistry model (PISCES). 
    69 Interactive coupling to Atmospheric models is possible via the OASIS coupler \citep{OASIS2006}. 
     69Interactive coupling to Atmospheric models is possible via the \href{https://portal.enes.org/oasis}{OASIS coupler}. 
    7070Two-way nesting is also available through an interface to the AGRIF package 
    71 (Adaptative Grid Refinement in \fortran) \citep{Debreu_al_CG2008}. 
     71(Adaptative Grid Refinement in \fortran) \citep{debreu.vouland.ea_CG08}. 
    7272% Needs to be reviewed 
    7373%The interface code for coupling to an alternative sea ice model (CICE, \citet{Hunke2008}) has now been upgraded so 
     
    8383The lateral Laplacian and biharmonic viscosity and diffusion can be rotated following 
    8484a geopotential or neutral direction. 
    85 There is an optional eddy induced velocity \citep{Gent1990} with a space and time variable coefficient 
    86 \citet{Treguier1997}. 
     85There is an optional eddy induced velocity \citep{gent.mcwilliams_JPO90} with a space and time variable coefficient 
     86\citet{treguier.held.ea_JPO97}. 
    8787The model has vertical harmonic viscosity and diffusion with a space and time variable coefficient, 
    88 with options to compute the coefficients with \citet{Blanke1993}, \citet{Pacanowski_Philander_JPO81}, or  
    89 \citet{Umlauf_Burchard_JMS03} mixing schemes. 
     88with options to compute the coefficients with \citet{blanke.delecluse_JPO93}, \citet{pacanowski.philander_JPO81}, or  
     89\citet{umlauf.burchard_JMR03} mixing schemes. 
    9090  
    9191%%gm    To be put somewhere else .... 
     
    151151The coding rules for OPA include conventions for naming variables, 
    152152with different starting letters for different types of variables (real, integer, parameter\ldots). 
    153 Those rules are briefly presented in \autoref{apdx:D} and a more complete document is available . 
     153Those rules are briefly presented in \autoref{apdx:coding} and a more complete document is available . 
    154154 
    155155The model is organized with a high internal modularity based on physics. 
     
    158158To make it easier for the user to find his way around the code, the module names follow a three-letter rule. 
    159159For example, \mdl{traldf} is a module related to the TRAcers equation, computing the Lateral DiFfussion. 
    160 %The complete list of module names is presented in \autoref{apdx:D}.      %====>>>> to be done ! 
     160%The complete list of module names is presented in \autoref{apdx:coding}.      %====>>>> to be done ! 
    161161Furthermore, modules are organized in a few directories that correspond to their category, 
    162162as indicated by the first three letters of their name (\autoref{tab:chapters}). 
     
    213213NEMO/OPA, like all research tools, is in perpetual evolution. 
    214214The present document describes the OPA version include in the release 3.4 of NEMO. 
    215 This release differs significantly from version 8, documented in \citet{Madec1998}. \\ 
     215This release differs significantly from version 8, documented in \citet{madec.delecluse.ea_NPM98}. \\ 
    216216 
    217217The main modifications from OPA v8 and NEMO/OPA v3.2 are : 
     
    222222\item 
    223223  introduction of partial step representation of bottom topography 
    224   \citep{Barnier_al_OD06, Le_Sommer_al_OM09, Penduff_al_OS07}; 
     224  \citep{barnier.madec.ea_OD06, le-sommer.penduff.ea_OM09, penduff.le-sommer.ea_OS07}; 
    225225\item 
    226226  partial reactivation of a terrain-following vertical coordinate ($s$- and hybrid $s$-$z$) with 
     
    242242  additional advection schemes for tracers; 
    243243\item 
    244   implementation of the AGRIF package (Adaptative Grid Refinement in \fortran) \citep{Debreu_al_CG2008}; 
     244  implementation of the AGRIF package (Adaptative Grid Refinement in \fortran) \citep{debreu.vouland.ea_CG08}; 
    245245\item 
    246246  online diagnostics : tracers trend in the mixed layer and vorticity balance; 
     
    255255  RGB light penetration and optional use of ocean color  
    256256\item 
    257   major changes in the TKE schemes: it now includes a Langmuir cell parameterization \citep{Axell_JGR02}, 
    258   the \citet{Mellor_Blumberg_JPO04} surface wave breaking parameterization, and has a time discretization which 
    259   is energetically consistent with the ocean model equations \citep{Burchard_OM02, Marsaleix_al_OM08}; 
     257  major changes in the TKE schemes: it now includes a Langmuir cell parameterization \citep{axell_JGR02}, 
     258  the \citet{mellor.blumberg_JPO04} surface wave breaking parameterization, and has a time discretization which 
     259  is energetically consistent with the ocean model equations \citep{burchard_OM02, marsaleix.auclair.ea_OM08}; 
    260260\item 
    261261  tidal mixing parametrisation (bottom intensification) + Indonesian specific tidal mixing 
    262   \citep{Koch-Larrouy_al_GRL07}; 
     262  \citep{koch-larrouy.madec.ea_GRL07}; 
    263263\item 
    264264  introduction of LIM-3, the new Louvain-la-Neuve sea-ice model 
    265265  (C-grid rheology and new thermodynamics including bulk ice salinity) 
    266   \citep{Vancoppenolle_al_OM09a, Vancoppenolle_al_OM09b} 
     266  \citep{vancoppenolle.fichefet.ea_OM09*a, vancoppenolle.fichefet.ea_OM09*b} 
    267267\end{itemize} 
    268268 
     
    272272\item 
    273273  introduction of a modified leapfrog-Asselin filter time stepping scheme 
    274   \citep{Leclair_Madec_OM09};  
    275 \item 
    276   additional scheme for iso-neutral mixing \citep{Griffies_al_JPO98}, although it is still a "work in progress"; 
    277 \item 
    278   a rewriting of the bottom boundary layer scheme, following \citet{Campin_Goosse_Tel99}; 
    279 \item 
    280   addition of a Generic Length Scale vertical mixing scheme, following \citet{Umlauf_Burchard_JMS03}; 
     274  \citep{leclair.madec_OM09};  
     275\item 
     276  additional scheme for iso-neutral mixing \citep{griffies.gnanadesikan.ea_JPO98}, although it is still a "work in progress"; 
     277\item 
     278  a rewriting of the bottom boundary layer scheme, following \citet{campin.goosse_T99}; 
     279\item 
     280  addition of a Generic Length Scale vertical mixing scheme, following \citet{umlauf.burchard_JMR03}; 
    281281\item 
    282282  addition of the atmospheric pressure as an external forcing on both ocean and sea-ice dynamics; 
    283283\item 
    284   addition of a diurnal cycle on solar radiation \citep{Bernie_al_CD07}; 
     284  addition of a diurnal cycle on solar radiation \citep{bernie.guilyardi.ea_CD07}; 
    285285\item 
    286286  river runoffs added through a non-zero depth, and having its own temperature and salinity; 
     
    296296  coupling interface adjusted for WRF atmospheric model; 
    297297\item 
    298   C-grid ice rheology now available fro both LIM-2 and LIM-3 \citep{Bouillon_al_OM09}; 
     298  C-grid ice rheology now available fro both LIM-2 and LIM-3 \citep{bouillon.maqueda.ea_OM09}; 
    299299\item 
    300300  LIM-3 ice-ocean momentum coupling applied to LIM-2; 
     
    318318 
    319319\begin{itemize} 
    320 \item finalisation of above iso-neutral mixing \citep{Griffies_al_JPO98}"; 
     320\item finalisation of above iso-neutral mixing \citep{griffies.gnanadesikan.ea_JPO98}"; 
    321321\item "Neptune effect" parametrisation; 
    322322\item horizontal pressure gradient suitable for s-coordinate; 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3

    • Property svn:ignore deleted
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists

    • Property svn:ignore deleted
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/SI3/namelists/namdyn_adv

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/latex/TOP

    • Property svn:ignore deleted
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namage

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namalb

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nambdy

    r10530 r11422  
    33!----------------------------------------------------------------------- 
    44   ln_bdy         = .false.   !  Use unstructured open boundaries 
    5    nb_bdy         = 2         !  number of open boundary sets 
    6    ln_coords_file = .true. , .false.    !  =T : read bdy coordinates from file 
     5   nb_bdy         = 0         !  number of open boundary sets 
     6   ln_coords_file = .true.    !  =T : read bdy coordinates from file 
    77      cn_coords_file = 'coordinates.bdy.nc'  !  bdy coordinates files 
    88   ln_mask_file   = .false.   !  =T : read mask from file 
    9       cn_mask_file = ''       !  name of mask file (if ln_mask_file=.TRUE.) 
    10    cn_dyn2d    = 'flather', 'none'       ! 
    11    nn_dyn2d_dta   =  3 , 0    !  = 0, bdy data are equal to the initial state 
     9      cn_mask_file = ''        !  name of mask file (if ln_mask_file=.TRUE.) 
     10   cn_dyn2d    = 'none'       ! 
     11   nn_dyn2d_dta   =  0        !  = 0, bdy data are equal to the initial state 
    1212      !                       !  = 1, bdy data are read in 'bdydata   .nc' files 
    1313      !                       !  = 2, use tidal harmonic forcing data from files 
    1414      !                       !  = 3, use external data AND tidal harmonic forcing 
    15    cn_dyn3d      =  'none' , 'none' 
    16    nn_dyn3d_dta  =  0 , 0     !  = 0, bdy data are equal to the initial state 
     15   cn_dyn3d      =  'none'    ! 
     16   nn_dyn3d_dta  =  0         !  = 0, bdy data are equal to the initial state 
    1717   !                          !  = 1, bdy data are read in 'bdydata   .nc' files 
    18    cn_tra        =  'frs' , 'frs' 
    19    nn_tra_dta    =  1 , 0     !  = 0, bdy data are equal to the initial state 
     18   cn_tra        =  'none'    ! 
     19   nn_tra_dta    =  0         !  = 0, bdy data are equal to the initial state 
    2020   !                          !  = 1, bdy data are read in 'bdydata   .nc' files 
    21    cn_ice        =  'none' , 'none' 
    22    nn_ice_dta    =  0, 0      !  = 0, bdy data are equal to the initial state 
     21   cn_ice        =  'none'    ! 
     22   nn_ice_dta    =  0         !  = 0, bdy data are equal to the initial state 
    2323   !                          !  = 1, bdy data are read in 'bdydata   .nc' files 
    24    rn_ice_tem    = 270., 270. !  si3 only: arbitrary temperature of incoming sea ice 
    25    rn_ice_sal    = 10. ,  10. !  si3 only:      --   salinity           -- 
    26    rn_ice_age    = 30. ,  30. !  si3 only:      --   age                -- 
     24   rn_ice_tem    = 270.      !  si3 only: arbitrary temperature of incoming sea ice 
     25   rn_ice_sal    = 10.       !  si3 only:      --   salinity           -- 
     26   rn_ice_age    = 30.       !  si3 only:      --   age                -- 
    2727   ! 
    28    ln_tra_dmp    =.false., .false.  !  open boudaries conditions for tracers 
    29    ln_dyn3d_dmp  =.false., .false.  !  open boundary condition for baroclinic velocities 
    30    rn_time_dmp   =  1., 1.    !  Damping time scale in days 
    31    rn_time_dmp_out = 1., 1.    !  Outflow damping time scale 
    32    nn_rimwidth   = 10, 5      !  width of the relaxation zone 
     28   ln_tra_dmp    =.false.     !  open boudaries conditions for tracers 
     29   ln_dyn3d_dmp  =.false.     !  open boundary condition for baroclinic velocities 
     30   rn_time_dmp   =  1.        !  Damping time scale in days 
     31   rn_time_dmp_out = 1.        !  Outflow damping time scale 
     32   nn_rimwidth   = 10         !  width of the relaxation zone 
    3333   ln_vol        = .false.    !  total volume correction (see nn_volctl parameter) 
    3434   nn_volctl     =  1         !  = 0, the total water flux across open boundaries is zero 
    3535   nb_jpk_bdy    = -1         ! number of levels in the bdy data (set < 0 if consistent with planned run) 
    3636/ 
    37 !----------------------------------------------------------------------- 
    38 &nambdy_index     ! index definition of bdy 
    39 !----------------------------------------------------------------------- 
    40     ctypebdy = 'S' 
    41     nbdyind  =  2 
    42     nbdybeg  = 2 
    43     nbdyend  = 273 
    44 / 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namberg

    r10075 r11422  
    55   ! 
    66   !                          ! diagnostics: 
    7    ln_bergdia        = .true.       ! Calculate budgets 
    8    nn_verbose_level  = 1            ! Turn on more verbose output if level > 0 
    9    nn_verbose_write  = 15           ! Timesteps between verbose messages 
    10    nn_sample_rate    = 1            ! Timesteps between sampling for trajectory storage 
     7   ln_bergdia        = .true.        ! Calculate budgets 
     8   nn_verbose_level  = 0             ! Turn on more verbose output if level > 0 
     9   nn_verbose_write  = 15            ! Timesteps between verbose messages 
     10   nn_sample_rate    = 1             ! Timesteps between sampling for trajectory storage 
    1111   ! 
    1212   !                          ! iceberg setting: 
    13    !                                ! Initial mass required for an iceberg of each class 
     13   !                                 ! Initial mass required for an iceberg of each class 
    1414   rn_initial_mass   = 8.8e7, 4.1e8, 3.3e9, 1.8e10, 3.8e10, 7.5e10, 1.2e11, 2.2e11, 3.9e11, 7.4e11 
    15    !                                ! Proportion of calving mass to apportion to each class 
     15   !                                 ! Proportion of calving mass to apportion to each class 
    1616   rn_distribution   = 0.24, 0.12, 0.15, 0.18, 0.12, 0.07, 0.03, 0.03, 0.03, 0.02 
    17    !                                ! Ratio between effective and real iceberg mass (non-dim) 
    18    !                                ! i.e. number of icebergs represented at a point 
    19    rn_mass_scaling   = 2000, 200, 50, 20, 10, 5, 2, 1, 1, 1 
    20                                     ! thickness of newly calved bergs (m) 
     17   !                                 ! Ratio between effective and real iceberg mass (non-dim) 
     18   !                                 ! i.e. number of icebergs represented at a point 
     19   rn_mass_scaling   = 2000., 200., 50., 20., 10., 5., 2., 1., 1., 1. 
     20                                     ! thickness of newly calved bergs (m) 
    2121   rn_initial_thickness     = 40., 67., 133., 175., 250., 250., 250., 250., 250., 250. 
    2222   ! 
    23    rn_rho_bergs            = 850.   ! Density of icebergs 
    24    rn_LoW_ratio            = 1.5    ! Initial ratio L/W for newly calved icebergs 
    25    ln_operator_splitting   = .true. ! Use first order operator splitting for thermodynamics 
    26    rn_bits_erosion_fraction = 0.    ! Fraction of erosion melt flux to divert to bergy bits 
    27    rn_sicn_shift           = 0.     ! Shift of sea-ice concn in erosion flux (0<sicn_shift<1) 
    28    ln_passive_mode         = .false.! iceberg - ocean decoupling 
    29    nn_test_icebergs        =  10    ! Create test icebergs of this class (-1 = no) 
    30    !                                ! Put a test iceberg at each gridpoint in box (lon1,lon2,lat1,lat2) 
     23   rn_rho_bergs            = 850.    ! Density of icebergs 
     24   rn_LoW_ratio            = 1.5     ! Initial ratio L/W for newly calved icebergs 
     25   ln_operator_splitting   = .true.  ! Use first order operator splitting for thermodynamics 
     26   rn_bits_erosion_fraction = 0.     ! Fraction of erosion melt flux to divert to bergy bits 
     27   rn_sicn_shift           = 0.      ! Shift of sea-ice concn in erosion flux (0<sicn_shift<1) 
     28   ln_passive_mode         = .false. ! iceberg - ocean decoupling 
     29   nn_test_icebergs        =  10     ! Create test icebergs of this class (-1 = no) 
     30   !                                 ! Put a test iceberg at each gridpoint in box (lon1,lon2,lat1,lat2) 
    3131   rn_test_box             = 108.0,  116.0, -66.0, -58.0 
    32    ln_use_calving          = .false.! Use calving data even when nn_test_icebergs > 0 
    33    rn_speed_limit          = 0.     ! CFL speed limit for a berg 
     32   ln_use_calving          = .false. ! Use calving data even when nn_test_icebergs > 0 
     33   rn_speed_limit          = 0.      ! CFL speed limit for a berg 
    3434 
    3535   cn_dir      = './'      !  root directory for the calving data location 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namc14_fcg

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namc14_sbc

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namc14_typ

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namcfc

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdia

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdom

    r10075 r11422  
    55   rn_isfhmin  =    1.00   !  treshold [m] to discriminate grounding ice from floating ice 
    66   ! 
    7    rn_rdt      = 5760.     !  time step for the dynamics and tracer 
     7   rn_rdt      = 5400.     !  time step for the dynamics and tracer 
    88   rn_atfp     =    0.1    !  asselin time filter parameter 
    99   ! 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdta_dyn

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdyn

    • Property svn:mime-type set to text/x-fortran
    r10445 r11422  
    1717                                      !          recommended range: ?? L16=15 - home=10 
    1818      rn_lfrelax    =   1.e-5         !        relaxation time scale to reach static friction [s-1] 
    19       rn_tensile    =   0.2           !        isotropic tensile strength 
     19      rn_tensile    =   0.2           !        ln_landfast_L16: isotropic tensile strength 
    2020/ 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdyn_rdgrft

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdyn_rhg

    • Property svn:mime-type set to text/x-fortran
    r10201 r11422  
    33!------------------------------------------------------------------------------ 
    44   ln_rhg_EVP       = .true.          !  EVP rheology 
    5       ln_aEVP       = .true.          !     adaptive rheology (Kimmritz et al. 2016 & 2017) 
     5      ln_aEVP       = .false.         !     adaptive rheology (Kimmritz et al. 2016 & 2017) 
    66      rn_creepl     =   2.0e-9        !     creep limit [1/s] 
    77      rn_ecc        =   2.0           !     eccentricity of the elliptical yield curve           
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namdyn_vor

    r10075 r11422  
    88   ln_dynvor_eeT = .false. !  energy conserving scheme (een using e3t) 
    99   ln_dynvor_een = .false. !  energy & enstrophy scheme 
    10       nn_een_e3f = 1          ! =0  e3f = mi(mj(e3t))/4  
     10      nn_een_e3f = 0          ! =0  e3f = mi(mj(e3t))/4  
    1111      !                       ! =1  e3f = mi(mj(e3t))/mi(mj( tmask)) 
    1212   ln_dynvor_msk = .false. !  vorticity multiplied by fmask (=T)        ==>>> PLEASE DO NOT ACTIVATE 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namini

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namitd

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namlobdet

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namlobdom

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namlobnut

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namlobopt

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namlobphy

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namlobrat

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namlobsed

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namlobzoo

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namobs

    r10445 r11422  
    88   ln_sla      = .false.             ! Logical switch for SLA observations 
    99   ln_sst      = .false.             ! Logical switch for SST observations 
    10    ln_sss      = .false.             ! Logical swithc for SSS observations 
     10   ln_sss      = .false.             ! Logical switch for SSS observations 
    1111   ln_sic      = .false.             ! Logical switch for Sea Ice observations 
    1212   ln_vel3d    = .false.             ! Logical switch for velocity observations 
     
    1919   ln_s_at_t   = .false.             ! Logical switch for computing model S at T obs if not there 
    2020   ln_sstnight = .false.             ! Logical switch for calculating night-time average for SST obs 
     21   ln_bound_reject  = .false.        ! Logical to remove obs near boundaries in LAMs. 
    2122   ln_sla_fp_indegs = .true.         ! Logical for SLA: T=> averaging footprint is in degrees, F=> in metres 
    2223   ln_sst_fp_indegs = .true.         ! Logical for SST: T=> averaging footprint is in degrees, F=> in metres 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namp4zlim

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namp4zmes

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namp4zmort

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namp4zprod

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namp4zzoo

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namp5zlim

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namp5zmes

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namp5zmort

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namp5zprod

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namp5zquota

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namp5zzoo

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampar

    • Property svn:mime-type set to text/x-fortran
    r10201 r11422  
    55   nlay_i           =   2             !  number of ice  layers 
    66   nlay_s           =   1             !  number of snow layers (only 1 is working) 
    7    nn_virtual_itd   =   0             !  virtual ITD mono-category parameterizations (1-3 => jpl = 1 only) or not (0) 
    8                                       !     2: activate enhanced thermal conductivity only --- temporary option 
    9                                       !     3: activate virtual thin ice melting only      ---  temporary option 
     7   ln_virtual_itd   =   .false.       !  virtual ITD mono-category parameterization (jpl=1 only) 
     8                                      !     i.e. enhanced thermal conductivity & virtual thin ice melting 
    109   ln_icedyn        = .true.          !  ice dynamics (T) or not (F) 
    1110   ln_icethd        = .true.          !  ice thermo   (T) or not (F) 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampisatm

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampisbio

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampiscal

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampisdmp

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampisext

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampisfer

    • Property svn:mime-type set to text/x-fortran
    r10445 r11422  
    22&nampisfer     !   parameters for iron chemistry 
    33!----------------------------------------------------------------------- 
    4    ln_ligvar =  .true.    ! variable ligand concentration 
     4   ln_ligvar =  .false.    ! variable ligand concentration 
    55   xlam1     =  0.005     ! scavenging rate of Iron 
    66   xlamdust  =  150.0     ! Scavenging rate of dust 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampisice

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampislig

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampismass

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampismod

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampisopt

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampispoc

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampisrem

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/nampissbc

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namrun

    r10445 r11422  
    55   cn_exp      =  "ORCA2"  !  experience name 
    66   nn_it000    =       1   !  first time step 
    7    nn_itend    =    5475   !  last  time step (std 5475) 
     7   nn_itend    =    5840   !  last  time step (std 5840) 
    88   nn_date0    =  010101   !  date at nit_0000 (format yyyymmdd) used if ln_rstart=F or (ln_rstart=T and nn_rstctl=0 or 1) 
    99   nn_time0    =       0   !  initial time of day in hhmm 
     
    2222   nn_istate   =       0   !  output the initial state (1) or not (0) 
    2323   ln_rst_list = .false.   !  output restarts at list of times using nn_stocklist (T) or at set frequency with nn_stock (F) 
    24    nn_stock    =    5475   !  frequency of creation of a restart file (modulo referenced to 1) 
     24   nn_stock    =    5840   !  frequency of creation of a restart file (modulo referenced to 1) 
    2525   nn_stocklist = 0,0,0,0,0,0,0,0,0,0 ! List of timesteps when a restart file is to be written 
    26    nn_write    =    5475   !  frequency of write in the output file   (modulo referenced to nn_it000) 
     26   nn_write    =    5840   !  frequency of write in the output file   (modulo referenced to nn_it000) 
    2727   ln_mskland  = .false.   !  mask land points in NetCDF outputs (costly: + ~15%) 
    2828   ln_cfmeta   = .false.   !  output additional data to netCDF files required for compliance with the CF metadata standard 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namsbc

    r10075 r11422  
    22&namsbc        !   Surface Boundary Condition manager                   (default: NO selection) 
    33!----------------------------------------------------------------------- 
    4    nn_fsbc     = 5         !  frequency of SBC module call 
     4   nn_fsbc     = 2         !  frequency of SBC module call 
    55      !                    !  (control sea-ice & iceberg model call) 
    66                     ! Type of air-sea fluxes  
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namsbc_iif

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namthd

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namthd_da

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namthd_do

    • Property svn:mime-type set to text/x-fortran
    r10201 r11422  
    22&namthd_do      !   Ice growth in open water 
    33!------------------------------------------------------------------------------ 
    4    rn_hinew         =   0.1           !  thickness for new ice formation in open water (m), must be larger than rn_hnewice 
     4   rn_hinew         =   0.1           !  thickness for new ice formation in open water (m), must be larger than rn_himin 
    55   ln_frazil        = .false.         !  Frazil ice parameterization (ice collection as a function of wind) 
    66      rn_maxfraz    =   1.0           !     maximum fraction of frazil ice collecting at the ice base 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namthd_pnd

    • Property svn:mime-type set to text/x-fortran
    r10201 r11422  
    33!------------------------------------------------------------------------------ 
    44   ln_pnd_H12       = .false.         !  activate evolutive melt ponds (from Holland et al 2012) 
    5       ln_pnd_fwb    = .false.         !     melt ponds store freshwater or not 
    6    ln_pnd_CST       = .false.         !  activate constant melt ponds 
    7       rn_apnd       =   0.2           !     prescribed pond fraction, at Tsu=0 
    8       rn_hpnd       =   0.05          !     prescribed pond depth, at Tsu=0 
     5   ln_pnd_CST       = .false.         !  activate constant  melt ponds 
     6      rn_apnd       =   0.2           !     prescribed pond fraction, at Tsu=0 degC 
     7      rn_hpnd       =   0.05          !     prescribed pond depth,    at Tsu=0 degC 
    98   ln_pnd_alb       = .false.         !  melt ponds affect albedo or not 
    109/ 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namthd_sal

    • Property svn:mime-type set to text/x-fortran
    r10201 r11422  
    55                                      !     1: constant ice salinity (S=rn_icesal) 
    66                                      !     2: varying salinity parameterization S(z,t) 
    7                                       !     3: prescribed salinity profile S(z), Schwarzacher, 1959 
    8    rn_icesal        =   4.            !    (nn_icesal=1) ice salinity (g/kg) 
    9    rn_sal_gd        =   5.            !  restoring ice salinity, gravity drainage (g/kg) 
    10    rn_time_gd       =   1.73e+6       !  restoring time scale, gravity drainage  (s) 
    11    rn_sal_fl        =   2.            !  restoring ice salinity, flushing (g/kg) 
    12    rn_time_fl       =   8.64e+5       !  restoring time scale, flushing (s) 
     7                                      !     3: prescribed salinity profile S(z) (Schwarzacher 1959) 
     8   rn_icesal        =   4.            !      (nn_icesal=1) ice salinity (g/kg) 
     9   rn_sal_gd        =   5.            !      (nn_icesal=2) restoring ice salinity, gravity drainage (g/kg) 
     10   rn_time_gd       =   1.73e+6       !      (nn_icesal=2) restoring time scale,  gravity drainage  (s) 
     11   rn_sal_fl        =   2.            !      (nn_icesal=2) restoring ice salinity, flushing (g/kg) 
     12   rn_time_fl       =   8.64e+5       !      (nn_icesal=2) restoring time scale,  flushing (s) 
    1313   rn_simax         =  20.            !  maximum tolerated ice salinity (g/kg) 
    1414   rn_simin         =   0.1           !  minimum tolerated ice salinity (g/kg) 
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namthd_zdf

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namtra_eiv

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namtra_mle

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namtrc

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namtrc_adv

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namtrc_bc

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namtrc_bdy

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namtrc_dmp

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namtrc_dta

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namtrc_ice

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namtrc_ldf

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namtrc_rad

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namtrc_run

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namtrc_snk

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namtrc_trd

    • Property svn:mime-type set to text/x-fortran
  • NEMO/branches/2019/fix_vvl_ticket1791/doc/namelists/namwad

    r10499 r11422  
    11!----------------------------------------------------------------------- 
    2 &namwad  !   Wetting and drying 
     2&namwad        !   Wetting and Drying (WaD)                             (default: OFF) 
    33!----------------------------------------------------------------------- 
    4    ln_wd_il          = .false   ! T/F activation of iterative limiter for  wetting and drying scheme 
    5    ln_wd_dl          = .true.   ! T/F activation of directional llimiter for wetting drying scheme 
    6    ln_wd_dl_bc       = .true.   ! T/F Directional limiteer Baroclinic option 
    7    ln_wd_dl_rmp      = .true.   ! T/F Turn on directional limiter ramp 
    8    rn_wdmin0         =  0.30    ! dpoth at which wetting/drying starts 
    9    rn_wdmin1         =  0.2     ! Minimum wet depth on dried cells 
    10    rn_wdmin2         =  0.0001  ! Tolerance of min wet depth on dried cells 
    11    rn_wdld           =  2.5     ! Land elevation below which wetting/drying is allowed 
    12    nn_wdit           =   20     ! Max iterations for W/D limiter 
    13    rn_wd_sbcdep      =  5.0     ! Depth at which to taper sbc fluxes 
    14    rn_wd_sbcfra      =  0.999   ! Fraction of SBC fluxes at taper depth (Must be <1) 
     4   ln_wd_il    = .false.   !  T/F activation of iterative   limiter 
     5   ln_wd_dl    = .false.   !  T/F activation of directional limiter 
     6   ln_wd_dl_bc = .false.   ! T/F Directional limiteer Baroclinic option 
     7   ln_wd_dl_rmp = .false.  ! T/F Turn on directional limiter ramp 
     8   rn_wdmin0   =  0.30     !  depth at which WaD starts 
     9   rn_wdmin1   =  0.2      ! Minimum wet depth on dried cells 
     10   rn_wdmin2   =  0.0001   ! Tolerance of min wet depth on dried cells 
     11   rn_wdld     =  2.5      !  Land elevation below which WaD is allowed 
     12   nn_wdit     =   20      !  Max iterations for WaD limiter 
     13   rn_wd_sbcdep =  5.0     ! Depth at which to taper sbc fluxes 
     14   rn_wd_sbcfra =  0.999   ! Fraction of SBC fluxes at taper depth (Must be <1) 
    1515/ 
Note: See TracChangeset for help on using the changeset viewer.