Changeset 11353


Ignore:
Timestamp:
2019-07-25T16:55:58+02:00 (14 months ago)
Author:
smasson
Message:

dev_r10984_HPC-13 : merge with trunk@11352, see #2285

Location:
NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization
Files:
4 deleted
22 edited
6 copied

Legend:

Unmodified
Added
Removed
  • NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/main/appendices.tex

    r11263 r11353  
    44\subfile{../subfiles/annex_C}             %% Discrete invariants of the eqs. 
    55\subfile{../subfiles/annex_iso}            %% Isoneutral diffusion using triads 
    6 \subfile{../subfiles/annex_D}             %% Coding rules 
     6\subfile{../subfiles/annex_DOMAINcfg}     %% Brief notes on DOMAINcfg 
    77 
    88%% Not included 
  • NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/main/bibliography.bib

    r11263 r11353  
    188188} 
    189189 
     190@article{ beljaars_QJRMS95, 
     191title = "The parametrization of surface fluxes in large-scale models under free convection", 
     192pages = "255--270", 
     193journal = "Quarterly Journal of the Royal Meteorological Society", 
     194volume = "121", 
     195number = "522", 
     196author = "Beljaars, Anton C. M.", 
     197year = "1995", 
     198month = "jan", 
     199 publisher     = "Wiley", 
     200issn = "00359009", 
     201doi = "10.1002/qj.49712152203" 
     202} 
     203 
    190204@article{         bernie.guilyardi.ea_CD07, 
    191205  title         = "Impact of resolving the diurnal cycle in an 
     
    386400} 
    387401 
     402@article{         brodeau.barnier.ea_JPO16, 
     403  title         = "Climatologically Significant Effects of Some Approximations in the Bulk Parameterizations of Turbulent Air–Sea Fluxes", 
     404  pages         = "5--28", 
     405  journal       = "Journal of Physical Oceanography", 
     406  volume        = "47", 
     407  number        = "1", 
     408  author        = "Brodeau, Laurent and Barnier, Bernard and Gulev, Sergey K. and Woods, Cian", 
     409  year          = "2016", 
     410  month         = "jan", 
     411  publisher     = "American Meteorological Society", 
     412  issn          = "0022-3670", 
     413  doi           = "10.1175/jpo-d-16-0169.1", 
     414} 
     415 
    388416@article{         brown.campana_MWR78, 
    389417  title         = "An economical time-differencing system for numerical 
     
    745773} 
    746774 
     775@article{ edson.jampana.ea_JPO13, 
     776title = "On the Exchange of Momentum over the Open Ocean", 
     777pages = "1589--1610", 
     778journal = "Journal of Physical Oceanography", 
     779volume = "43", 
     780number = "8", 
     781author = "Edson, James B. and Jampana, Venkata and Weller, Robert A. and Bigorre, Sebastien P. and Plueddemann, Albert J. and Fairall, Christopher W. and Miller, Scott D. and Mahrt, Larry and Vickers, Dean and Hersbach, Hans", 
     782year = "2013", 
     783month = "aug", 
     784publisher = "American Meteorological Society", 
     785issn = "0022-3670", 
     786doi = "10.1175/JPO-D-12-0173.1" 
     787} 
     788 
    747789@article{         egbert.ray_JGR01, 
    748790  title         = "Estimates of {M2} tidal energy dissipation from 
     
    819861} 
    820862 
     863@article{ fairall.bradley.ea_JC03, 
     864title = "Bulk parameterization of air-sea fluxes: Updates and verification for the COARE algorithm", 
     865pages = "571--591", 
     866journal = "Journal of Climate", 
     867volume = "16", 
     868number = "4", 
     869author = "Fairall, C. W. and Bradley, E. F. and Hare, J. E. and Grachev, A. A. and Edson, J. B.", 
     870year = "2003", 
     871publisher = "American Meteorological Society", 
     872issn = "08948755", 
     873doi = "10.1175/1520-0442(2003)016<0571:BPOASF>2.0.CO;2" 
     874} 
     875 
    821876@phdthesis{       farge-coulombier_phd87, 
    822877  title         = "Dynamique non-lin\'{e}aire des ondes et des tourbillons 
     
    871926  publisher     = "UNESCO", 
    872927  url           = "https://unesdoc.unesco.org/ark:/48223/pf0000059832.locale=en" 
     928} 
     929 
     930@article{         foxkemper.ferrari_JPO08, 
     931  title         = "Parameterization of Mixed Layer Eddies. Part I: Theory and Diagnosis", 
     932  pages         = "1145--1165", 
     933  journal       = "Journal of Physical Oceanography", 
     934  volume        = "38", 
     935  number        = "6", 
     936  author        = "B. Fox-Kemper and R. Ferrari and B. Hallberg", 
     937  year          = "2008", 
     938  month         = "jun", 
     939  publisher     = "American Meteorological Society", 
     940  issn          = "1520-0485", 
     941  doi           = "10.1175/2007JPO3792.1" 
    873942} 
    874943 
     
    18391908  author        = "F. Lott and G. Madec and J. Verron", 
    18401909  year          = "1990" 
     1910} 
     1911 
     1912@article{     lupkes.gryanik.ea_JGR12, 
     1913  author    = "L{\"{u}}pkes, Christof and Gryanik, Vladimir M. and Hartmann, J{\"{o}}rg and Andreas, Edgar L.", 
     1914  doi       = "10.1029/2012JD017630", 
     1915  issn      = "01480227", 
     1916  journal   = "Journal of Geophysical Research Atmospheres", 
     1917  number    = "13", 
     1918  pages  = "1--18", 
     1919  title  = "A parametrization, based on sea ice morphology, of the neutral atmospheric drag coefficients for weather prediction and climate models", 
     1920  volume    = "117", 
     1921  year      = "2012" 
     1922} 
     1923 
     1924@article{     lupkes.gryanik_JGR15, 
     1925  author    = "L{\"{u}}pkes, Christof and Gryanik, Vladimir M.", 
     1926  doi       = "10.1002/2014JD022418", 
     1927  issn      = "21562202", 
     1928  journal   = "Journal of Geophysical Research", 
     1929  number    = "2", 
     1930  pages  = "552--581", 
     1931  title  = "A stability-dependent parametrization of transfer coefficients formomentum and heat over polar sea ice to be used in climate models", 
     1932  volume    = "120", 
     1933  year      = "2015" 
    18411934} 
    18421935 
     
    23062399} 
    23072400 
     2401@article{         qiao.yuan.ea_OD10, 
     2402  title         = "A three-dimensional surface wave–ocean circulation coupled  
     2403                  model and its initial testing", 
     2404  pages         = "1339--1335", 
     2405  journal       = "Ocean Dynamics", 
     2406  volume        = "60", 
     2407  number        = "5", 
     2408  author        = "F. Qiao and Y. Yuan and T. Ezer and C. Xia and  
     2409                   Y. Yang and X. Lu and Z. Song ", 
     2410  year          = "2010", 
     2411  month         = "oct", 
     2412  publisher     = "Springer-Verlag", 
     2413  issn          = "1616-7341", 
     2414  doi           = "10.1007/s10236-010-0326-y" 
     2415} 
     2416 
    23082417@article{         redi_JPO82, 
    23092418  title         = "Oceanic isopycnal mixing by coordinate rotation", 
     
    25442653} 
    25452654 
     2655@article{         smagorinsky_MW63, 
     2656  title         = "General circulation experiments with the primitive equations: I. The basic experiment ", 
     2657  pages         = "99--164", 
     2658  journal       = "Monthly Weather Review", 
     2659  volume        = "91", 
     2660  number        = "3", 
     2661  author        = "J. Smagorinsky", 
     2662  year          = "1963", 
     2663  month         = "mar", 
     2664  publisher     = "American Meteorological Society", 
     2665  issn          = "1520-0493", 
     2666  doi           = "10.1175/1520-0493(1963)091<0099:GCEWTP>2.3.CO;2" 
     2667} 
     2668 
    25462669@article{         song.haidvogel_JCP94, 
    25472670  title         = "A semi-implicit ocean circulation model using a 
     
    28963019} 
    28973020 
     3021@article{         white.hoskins.ea_QJRMS05, 
     3022  title         = "Consistent approximate models of the global atmosphere: shallow, deep, 
     3023                  hydrostatic, quasi-hydrostatic and non-hydrostatic", 
     3024  pages         = "2081--2107", 
     3025  journal       = "Quarterly Journal of the Royal Meteorological Society", 
     3026  volume        = "131", 
     3027  author        = "A. A. White and B. J. Hoskins and I. Roulstone and A. Staniforth", 
     3028  year          = "2005", 
     3029  doi           = "10.1256/qj.04.49" 
     3030} 
     3031 
    28983032@article{         white.adcroft.ea_JCP09, 
    28993033  title         = "High-order regridding-remapping schemes for continuous 
  • NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/annex_A.tex

    r11263 r11353  
    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% ================================================================ 
     
    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 {\mathrm {\mathbf 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, 
     
    361417  + \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} 
     
    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(   {{\mathrm {\mathbf 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} 
     
    494550    \frac{1}{e_3}\frac{\partial \left(  e_3\,v  \right) }{\partial t}= 
    495551    -  \nabla \cdot \left(   {{\mathrm {\mathbf U}}\,v}   \right) 
    496     +   \left\{ {f + \frac{1}{e_1 e_2 }\left(    v  \;\frac{\partial e_2 }{\partial i} 
     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/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/annex_B.tex

    r11263 r11353  
    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  } \\ 
     
    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{cox_OM87}: 
     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 
     
    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 {\mathrm {\mathbf 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/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_ASM.tex

    r11263 r11353  
    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. 
     
    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} 
     
    6674    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} 
     
    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 
     
    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/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_DIA.tex

    r11263 r11353  
    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 
     
    14941507\textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested. 
    14951508In particular, options associated with \np{ln\_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl} are not working, 
    1496 and none of the options have been tested with variable volume (\ie \key{vvl} defined). 
     1509and none of the options have been tested with variable volume (\ie \np{ln\_linssh}\forcode{ = .true.}). 
    14971510 
    14981511% ------------------------------------------------------------------------------------------------------------- 
     
    19301943   
    19311944Third, the discretisation of \autoref{eq:steric_Bq} depends on the type of free surface which is considered. 
    1932 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 
    19331946 
    19341947\[ 
     
    19691982where $S_o$ and $p_o$ are the initial salinity and pressure, respectively. 
    19701983 
    1971 Both steric and thermosteric sea level are computed in \mdl{diaar5} which needs the \key{diaar5} defined to 
    1972 be called. 
     1984Both steric and thermosteric sea level are computed in \mdl{diaar5}. 
    19731985 
    19741986% ------------------------------------------------------------------------------------------------------------- 
    19751987%       Other Diagnostics 
    19761988% ------------------------------------------------------------------------------------------------------------- 
    1977 \section[Other diagnostics (\texttt{\textbf{key\_diahth}}, \texttt{\textbf{key\_diaar5}})] 
    1978 {Other diagnostics (\protect\key{diahth}, \protect\key{diaar5})} 
     1989\section[Other diagnostics] 
     1990{Other diagnostics} 
    19791991\label{sec:DIA_diag_others} 
    19801992 
     
    19952007- the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth}) 
    19962008 
    1997 % ----------------------------------------------------------- 
    1998 %     Poleward heat and salt transports 
    1999 % ----------------------------------------------------------- 
    2000  
    2001 \subsection[Poleward heat and salt transports (\textit{diaptr.F90})] 
    2002 {Poleward heat and salt transports (\protect\mdl{diaptr})} 
    2003  
    2004 %------------------------------------------namptr----------------------------------------- 
    2005  
    2006 \nlst{namptr}  
    2007 %----------------------------------------------------------------------------------------- 
    2008  
    2009 The poleward heat and salt transports, their advective and diffusive component, 
    2010 and the meriodional stream function can be computed on-line in \mdl{diaptr} \np{ln\_diaptr} to true 
    2011 (see the \textit{\ngn{namptr} } namelist below). 
    2012 When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed for the Atlantic, Indian, 
    2013 Pacific and Indo-Pacific Oceans (defined north of 30\deg{S}) as well as for the World Ocean. 
    2014 The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains three 2D mask arrays, 
    2015 the Indo-Pacific mask been deduced from the sum of the Indian and Pacific mask (\autoref{fig:mask_subasins}). 
    20162009 
    20172010%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     
    20342027%       CMIP specific diagnostics  
    20352028% ----------------------------------------------------------- 
    2036 \subsection[CMIP specific diagnostics (\textit{diaar5.F90})] 
     2029\subsection[CMIP specific diagnostics (\textit{diaar5.F90}, \textit{diaptr.F90})] 
    20372030{CMIP specific diagnostics (\protect\mdl{diaar5})} 
    20382031 
    2039 A series of diagnostics has been added in the \mdl{diaar5}. 
    2040 They corresponds to outputs that are required for AR5 simulations (CMIP5) 
     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) 
    20412034(see also \autoref{sec:DIA_steric} for one of them). 
    2042 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%----------------------------------------------------------------------------------------- 
    20432048 
    20442049% ----------------------------------------------------------- 
  • NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_DOM.tex

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

    r11263 r11353  
    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% ================================================================ 
     
    88115%gm%  caution I'm not sure the simplification was a good idea!  
    89116 
    90 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.}, 
    91118and either \np{ln\_traldf\_hor}\forcode{ = .true.} or \np{ln\_dynldf\_hor}\forcode{ = .true.}.  
    92119 
     
    145172\item[$s$- or hybrid $s$-$z$- coordinate: ] 
    146173  in the current release of \NEMO, iso-neutral mixing is only employed for $s$-coordinates if 
    147   the Griffies scheme is used (\np{traldf\_grif}\forcode{ = .true.}; 
    148   see Appdx \autoref{apdx:triad}). 
     174  the Griffies scheme is used (\np{ln\_traldf\_triad}\forcode{ = .true.}; 
     175  see \autoref{apdx:triad}). 
    149176  In other words, iso-neutral mixing will only be accurately represented with a linear equation of state 
    150   (\np{nn\_eos}\forcode{ = 1..2}). 
     177  (\np{ln\_seos}\forcode{ = .true.}). 
    151178  In the case of a "true" equation of state, the evaluation of $i$ and $j$ derivatives in \autoref{eq:ldfslp_iso} 
    152179  will include a pressure dependent part, leading to the wrong evaluation of the neutral slopes. 
     
    198225 
    199226This implementation is a rather old one. 
    200 It is similar to the one proposed by Cox [1987], except for the background horizontal diffusion. 
    201 Indeed, the Cox implementation of isopycnal diffusion in GFDL-type models requires 
     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 
    202229a minimum background horizontal diffusion for numerical stability reasons. 
    203230To overcome this problem, several techniques have been proposed in which the numerical schemes of 
    204231the ocean model are modified \citep{weaver.eby_JPO97, griffies.gnanadesikan.ea_JPO98}. 
    205 Griffies's scheme is now available in \NEMO if \np{traldf\_grif\_iso} is set true; see Appdx \autoref{apdx:triad}. 
     232Griffies's scheme is now available in \NEMO if \np{ln\_traldf\_triad}=\forcode{= .true.}; see \autoref{apdx:triad}. 
    206233Here, another strategy is presented \citep{lazar_phd97}: 
    207234a local filtering of the iso-neutral slopes (made on 9 grid-points) prevents the development of 
     
    242269 
    243270For numerical stability reasons \citep{cox_OM87, griffies_bk04}, the slopes must also be bounded by 
    244 $1/100$ everywhere. 
     271the namelist scalar \np{rn\_slpmax} (usually $1/100$) everywhere. 
    245272This constraint is applied in a piecewise linear fashion, increasing from zero at the surface to 
    246273$1/100$ at $70$ metres and thereafter decreasing to zero at the bottom of the ocean 
    247274(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.} 
    248276 
    249277%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     
    298326(see \autoref{sec:LBC_coast}). 
    299327 
    300  
    301 % ================================================================ 
    302 % Lateral Mixing Operator 
    303 % ================================================================ 
    304 \section[Lateral mixing operators (\textit{traldf.F90})] 
    305 {Lateral mixing operators (\protect\mdl{traldf}, \protect\mdl{traldf})} 
    306 \label{sec:LDF_op} 
    307  
    308  
    309328    
    310329% ================================================================ 
    311330% Lateral Mixing Coefficients 
    312331% ================================================================ 
    313 \section[Lateral mixing coefficient (\textit{ldftra.F90}, \textit{ldfdyn.F90})] 
    314 {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})} 
    315334\label{sec:LDF_coef} 
    316335 
    317 Introducing a space variation in the lateral eddy mixing coefficients changes the model core memory requirement, 
    318 adding up to four extra three-dimensional arrays for the geopotential or isopycnal second order operator applied to  
    319 momentum. 
    320 Six CPP keys control the space variation of eddy coefficients: three for momentum and three for tracer. 
    321 The three choices allow: 
    322 a space variation in the three space directions (\key{traldf\_c3d},  \key{dynldf\_c3d}), 
    323 in the horizontal plane (\key{traldf\_c2d},  \key{dynldf\_c2d}), 
    324 or in the vertical only (\key{traldf\_c1d},  \key{dynldf\_c1d}). 
    325 The default option is a constant value over the whole ocean on both momentum and tracers.  
    326     
    327 The number of additional arrays that have to be defined and the gridpoint position at which 
    328 they are defined depend on both the space variation chosen and the type of operator used. 
    329 The resulting eddy viscosity and diffusivity coefficients can be a function of more than one variable. 
    330 Changes in the computer code when switching from one option to another have been minimized by 
    331 introducing the eddy coefficients as statement functions 
    332 (include file \textit{ldftra\_substitute.h90} and \textit{ldfdyn\_substitute.h90}). 
    333 The functions are replaced by their actual meaning during the preprocessing step (CPP). 
    334 The specification of the space variation of the coefficient is made in \mdl{ldftra} and \mdl{ldfdyn}, 
    335 or more precisely in include files \textit{traldf\_cNd.h90} and \textit{dynldf\_cNd.h90}, with N=1, 2 or 3. 
    336 The user can modify these include files as he/she wishes. 
    337 The way the mixing coefficient are set in the reference version can be briefly described as follows: 
    338  
    339 \subsubsection{Constant mixing coefficients (default option)} 
    340 When none of the \key{dynldf\_...} and \key{traldf\_...} keys are defined, 
    341 a constant value is used over the whole ocean for momentum and tracers, 
    342 which is specified through the \np{rn\_ahm0} and \np{rn\_aht0} namelist parameters. 
    343  
    344 \subsubsection[Vertically varying mixing coefficients (\texttt{\textbf{key\_traldf\_c1d}} and \texttt{\textbf{key\_dynldf\_c1d}})] 
    345 {Vertically varying mixing coefficients (\protect\key{traldf\_c1d} and \key{dynldf\_c1d})} 
    346 The 1D option is only available when using the $z$-coordinate with full step. 
    347 Indeed in all the other types of vertical coordinate, 
    348 the depth is a 3D function of (\textbf{i},\textbf{j},\textbf{k}) and therefore, 
    349 introducing depth-dependent mixing coefficients will require 3D arrays. 
    350 In the 1D option, a hyperbolic variation of the lateral mixing coefficient is introduced in which 
    351 the surface value is \np{rn\_aht0} (\np{rn\_ahm0}), the bottom value is 1/4 of the surface value, 
    352 and the transition takes place around z=300~m with a width of 300~m 
    353 (\ie both the depth and the width of the inflection point are set to 300~m). 
    354 This profile is hard coded in file \textit{traldf\_c1d.h90}, but can be easily modified by users. 
    355  
    356 \subsubsection[Horizontally varying mixing coefficients (\texttt{\textbf{key\_traldf\_c2d}} and \texttt{\textbf{key\_dynldf\_c2d}})] 
    357 {Horizontally varying mixing coefficients (\protect\key{traldf\_c2d} and \protect\key{dynldf\_c2d})} 
    358 By default the horizontal variation of the eddy coefficient depends on the local mesh size and 
     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 
    359396the type of operator used: 
    360397\begin{equation} 
     
    362399  A_l = \left\{ 
    363400    \begin{aligned} 
    364       & \frac{\max(e_1,e_2)}{e_{max}} A_o^l           & \text{for laplacian operator } \\ 
    365       & \frac{\max(e_1,e_2)^{3}}{e_{max}^{3}} A_o^l          & \text{for bilaplacian operator } 
     401      & \frac{\max(e_1,e_2)}{e_{ref}} A_o^l           & \text{for laplacian operator } \\ 
     402      & \frac{\max(e_1,e_2)^{3}}{e_{ref}^{3}} A_o^l          & \text{for bilaplacian operator } 
    366403    \end{aligned} 
    367404  \right. 
    368405\end{equation} 
    369 where $e_{max}$ is the maximum of $e_1$ and $e_2$ taken over the whole masked ocean domain, 
    370 and $A_o^l$ is the \np{rn\_ahm0} (momentum) or \np{rn\_aht0} (tracer) namelist parameter. 
     406where $e_{ref}$ is a reference grid size harcoded to a $1^{\circ}$ grid size (\ie $e_{ref}\approx 111 km$), 
     407and $A_o^l$ is the user defined mixing coefficient defined according to  \autoref{eq:constantah}. 
    371408This variation is intended to reflect the lesser need for subgrid scale eddy mixing where 
    372409the grid size is smaller in the domain. 
    373410It was introduced in the context of the DYNAMO modelling project \citep{willebrand.barnier.ea_PO01}. 
    374 Note that such a grid scale dependance of mixing coefficients significantly increase the range of stability of 
    375 model configurations presenting large changes in grid pacing such as global ocean models. 
     411Note that such a grid scale dependance of mixing coefficients significantly increases the range of stability of 
     412model configurations presenting large changes in grid spacing such as global ocean models. 
    376413Indeed, in such a case, a constant mixing coefficient can lead to a blow up of the model due to 
    377414large coefficient compare to the smallest grid size (see \autoref{sec:STP_forward_imp}), 
    378415especially when using a bilaplacian operator. 
    379416 
    380 Other formulations can be introduced by the user for a given configuration. 
    381 For example, in the ORCA2 global ocean model (see Configurations), 
    382 the laplacian viscosity operator uses \np{rn\_ahm0}~= 4.10$^4$ m$^2$/s poleward of 20$^{\circ}$ north and south and 
    383 decreases linearly to \np{rn\_aht0}~= 2.10$^3$ m$^2$/s at the equator \citep{madec.delecluse.ea_JPO96, delecluse.madec_icol99}. 
    384 This modification can be found in routine \rou{ldf\_dyn\_c2d\_orca} defined in \mdl{ldfdyn\_c2d}. 
    385 Similar modified horizontal variations can be found with the Antarctic or Arctic sub-domain options of 
    386 ORCA2 and ORCA05 (see \&namcfg namelist). 
    387  
    388 \subsubsection[Space varying mixing coefficients (\texttt{\textbf{key\_traldf\_c3d}} and \texttt{\textbf{key\_dynldf\_c3d}})] 
    389 {Space varying mixing coefficients (\protect\key{traldf\_c3d} and \key{dynldf\_c3d})} 
    390  
    391 The 3D space variation of the mixing coefficient is simply the combination of the 1D and 2D cases, 
     417\colorbox{yellow}{CASE \np{nn\_aht\_ijk\_t} = 21 to be added} 
     418 
     419\subsection[Mesh size and depth dependent mixing coefficients (\forcode{nn_aht_ijk_t = 30}, \forcode{nn_ahm_ijk_t = 30})] 
     420{Mesh size and depth dependent mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{ = 30}, \protect\np{nn\_ahm\_ijk\_t}\forcode{ = 30})} 
     421 
     422The 3D space variation of the mixing coefficient is simply the combination of the 1D and 2D cases above, 
    392423\ie a hyperbolic tangent variation with depth associated with a grid size dependence of 
    393424the magnitude of the coefficient.  
    394425 
    395 \subsubsection{Space and time varying mixing coefficients} 
    396  
    397 There is no default specification of space and time varying mixing coefficient.  
    398 The only case available is specific to the ORCA2 and ORCA05 global ocean configurations. 
    399 It provides only a tracer mixing coefficient for eddy induced velocity (ORCA2) or both iso-neutral and 
    400 eddy induced velocity (ORCA05) that depends on the local growth rate of baroclinic instability. 
    401 This specification is actually used when an ORCA key and both \key{traldf\_eiv} and \key{traldf\_c2d} are defined. 
     426\subsection[Velocity dependent mixing coefficients (\forcode{nn_aht_ijk_t = 31}, \forcode{nn_ahm_ijk_t = 31})] 
     427{Flow dependent mixing coefficients (\protect\np{nn\_aht\_ijk\_t}\forcode{ = 31}, \protect\np{nn\_ahm\_ijk\_t}\forcode{ = 31})} 
     428In 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$): 
     429\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 ?} 
     430 
     431\begin{equation} 
     432  \label{eq:flowah} 
     433  A_l = \left\{ 
     434    \begin{aligned} 
     435      & \frac{1}{12} \lvert U \rvert e          & \text{for laplacian operator } \\ 
     436      & \frac{1}{12} \lvert U \rvert e^3             & \text{for bilaplacian operator }  
     437    \end{aligned} 
     438  \right. 
     439\end{equation} 
     440 
     441\subsection[Deformation rate dependent viscosities (\forcode{nn_ahm_ijk_t = 32})] 
     442{Deformation rate dependent viscosities (\protect\np{nn\_ahm\_ijk\_t}\forcode{ = 32})} 
     443 
     444This option refers to the \citep{smagorinsky_MW63} scheme which is here implemented for momentum only. Smagorinsky chose as a  
     445characteristic time scale $T_{smag}$ the deformation rate and for the lengthscale $L_{smag}$ the maximum wavenumber possible on the horizontal grid, e.g.: 
     446 
     447\begin{equation} 
     448  \label{eq:smag1} 
     449  \begin{split} 
     450    T_{smag}^{-1} & = \sqrt{\left( \partial_x u - \partial_y v\right)^2 + \left( \partial_y u + \partial_x v\right)^2  } \\ 
     451    L_{smag} & = \frac{1}{\pi}\frac{e_1 e_2}{e_1 + e_2} 
     452  \end{split} 
     453\end{equation} 
     454 
     455Introducing a user defined constant $C$ (given in the namelist as \np{rn\_csmc}), one can deduce the mixing coefficients as follows: 
     456 
     457\begin{equation} 
     458  \label{eq:smag2} 
     459  A_{smag} = \left\{ 
     460    \begin{aligned} 
     461      & C^2  T_{smag}^{-1}  L_{smag}^2       & \text{for laplacian operator } \\ 
     462      & \frac{C^2}{8} T_{smag}^{-1} L_{smag}^4        & \text{for bilaplacian operator }  
     463    \end{aligned} 
     464  \right. 
     465\end{equation} 
     466 
     467For stability reasons, upper and lower limits are applied on the resulting coefficient (see \autoref{sec:STP_forward_imp}) so that: 
     468\begin{equation} 
     469  \label{eq:smag3} 
     470    \begin{aligned} 
     471      & C_{min} \frac{1}{2}   \lvert U \rvert  e    < A_{smag} < C_{max} \frac{e^2}{   8\rdt}                 & \text{for laplacian operator } \\ 
     472      & C_{min} \frac{1}{12} \lvert U \rvert  e^3 < A_{smag} < C_{max} \frac{e^4}{64 \rdt}                 & \text{for bilaplacian operator }  
     473    \end{aligned} 
     474\end{equation} 
     475 
     476where $C_{min}$ and $C_{max}$ are adimensional namelist parameters given by \np{rn\_minfac} and \np{rn\_maxfac} respectively. 
     477 
     478\subsection{About space and time varying mixing coefficients} 
    402479 
    403480The following points are relevant when the eddy coefficient varies spatially: 
     
    412489(\autoref{sec:dynldf_properties}). 
    413490 
    414 (3) for isopycnal diffusion on momentum or tracers, an additional purely horizontal background diffusion with 
    415 uniform coefficient can be added by setting a non zero value of \np{rn\_ahmb0} or \np{rn\_ahtb0}, 
    416 a background horizontal eddy viscosity or diffusivity coefficient 
    417 (namelist parameters whose default values are $0$). 
    418 However, the technique used to compute the isopycnal slopes is intended to get rid of such a background diffusion, 
    419 since it introduces spurious diapycnal diffusion (see \autoref{sec:LDF_slp}). 
    420  
    421 (4) when an eddy induced advection term is used (\key{traldf\_eiv}), 
    422 $A^{eiv}$, the eddy induced coefficient has to be defined. 
    423 Its space variations are controlled by the same CPP variable as for the eddy diffusivity coefficient 
    424 (\ie \key{traldf\_cNd}).  
    425  
    426 (5) the eddy coefficient associated with a biharmonic operator must be set to a \emph{negative} value. 
    427  
    428 (6) it is possible to use both the laplacian and biharmonic operators concurrently. 
    429  
    430 (7) it is possible to run without explicit lateral diffusion on momentum 
    431 (\np{ln\_dynldf\_lap}\forcode{ = .?.}\np{ln\_dynldf\_bilap}\forcode{ = .false.}). 
    432 This is recommended when using the UBS advection scheme on momentum (\np{ln\_dynadv\_ubs}\forcode{ = .true.}, 
    433 see \autoref{subsec:DYN_adv_ubs}) and can be useful for testing purposes. 
    434  
    435491% ================================================================ 
    436492% Eddy Induced Mixing 
    437493% ================================================================ 
    438 \section[Eddy induced velocity (\textit{traadv\_eiv.F90}, \textit{ldfeiv.F90})] 
    439 {Eddy induced velocity (\protect\mdl{traadv\_eiv}, \protect\mdl{ldfeiv})} 
     494\section[Eddy induced velocity (\forcode{ln_ldfeiv = .true.})] 
     495{Eddy induced velocity (\protect\np{ln\_ldfeiv}\forcode{ = .true.})} 
     496 
    440497\label{sec:LDF_eiv} 
     498 
     499%--------------------------------------------namtra_eiv--------------------------------------------------- 
     500 
     501\nlst{namtra_eiv} 
     502 
     503%-------------------------------------------------------------------------------------------------------------- 
     504 
    441505 
    442506%%gm  from Triad appendix  : to be incorporated.... 
     
    460524} 
    461525 
    462 When Gent and McWilliams [1990] diffusion is used (\key{traldf\_eiv} defined), 
     526When  \citet{gent.mcwilliams_JPO90} diffusion is used (\np{ln\_ldfeiv}\forcode{ = .true.}), 
    463527an eddy induced tracer advection term is added, 
    464528the formulation of which depends on the slopes of iso-neutral surfaces. 
     
    466530\ie \autoref{eq:ldfslp_geo} is used in $z$-coordinates, 
    467531and the sum \autoref{eq:ldfslp_geo} + \autoref{eq:ldfslp_iso} in $s$-coordinates. 
    468 The eddy induced velocity is given by:  
     532 
     533If isopycnal mixing is used in the standard way, \ie \np{ln\_traldf\_triad}\forcode{ = .false.}, the eddy induced velocity is given by:  
    469534\begin{equation} 
    470535  \label{eq:ldfeiv} 
     
    475540  \end{split} 
    476541\end{equation} 
    477 where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{rn\_aeiv}, 
    478 a \textit{nam\_traldf} namelist parameter. 
    479 The three components of the eddy induced velocity are computed and 
    480 add to the eulerian velocity in \mdl{traadv\_eiv}. 
     542where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set through \np{nn\_aei\_ijk\_t} \ngn{namtra\_eiv} namelist parameter.  
     543The three components of the eddy induced velocity are computed in \rou{ldf\_eiv\_trp} and 
     544added to the eulerian velocity in \rou{tra\_adv} where tracer advection is performed. 
    481545This has been preferred to a separate computation of the advective trends associated with the eiv velocity, 
    482546since it allows us to take advantage of all the advection schemes offered for the tracers 
     
    488552At the surface, lateral and bottom boundaries, the eddy induced velocity, 
    489553and thus the advective eddy fluxes of heat and salt, are set to zero.  
     554The 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).  
     555\colorbox{yellow}{CASE \np{nn\_aei\_ijk\_t} = 21 to be added} 
     556 
     557In 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}. 
     558 
     559% ================================================================ 
     560% Mixed layer eddies 
     561% ================================================================ 
     562\section[Mixed layer eddies (\forcode{ln_mle = .true.})] 
     563{Mixed layer eddies (\protect\np{ln\_mle}\forcode{ = .true.})} 
     564 
     565\label{sec:LDF_mle} 
     566 
     567%--------------------------------------------namtra_eiv--------------------------------------------------- 
     568 
     569\nlst{namtra_mle} 
     570 
     571%-------------------------------------------------------------------------------------------------------------- 
     572 
     573If  \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. 
     574 
     575\colorbox{yellow}{TBC} 
    490576 
    491577\biblio 
  • NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_OBS.tex

    r11263 r11353  
    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 ${\mathrm P}$ with with longitude and latitude $({\lambda_{}}_{\mathrm P}, \phi_{\mathrm P})$ and 
     587Consider an observation point ${\mathrm P}$ with longitude and latitude (${\lambda_{}}_{\mathrm P}$, $\phi_{\mathrm P}$) and 
    576588the four nearest neighbouring model grid points ${\mathrm A}$, ${\mathrm B}$, ${\mathrm C}$ and ${\mathrm D}$ with 
    577589longitude and latitude ($\lambda_{\mathrm A}$, $\phi_{\mathrm A}$),($\lambda_{\mathrm B}$, $\phi_{\mathrm B}$) etc. 
    578 All horizontal interpolation methods implemented in NEMO estimate the value of a model variable $x$ at point $P$ as 
     590All horizontal interpolation methods implemented in \NEMO estimate the value of a model variable $x$ at point $P$ as 
    579591a 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_{}}_{\mathrm P} & \hspace{-2mm} = \hspace{-2mm} & 
    582                                                    \frac{1}{w} \left( {w_{}}_{\mathrm A} {x_{}}_{\mathrm A} + 
    583                                                    {w_{}}_{\mathrm B} {x_{}}_{\mathrm B} + 
    584                                                    {w_{}}_{\mathrm C} {x_{}}_{\mathrm C} + 
    585                                                    {w_{}}_{\mathrm D} {x_{}}_{\mathrm D} \right) 
     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*} 
     600 
    587601where ${w_{}}_{\mathrm A}$, ${w_{}}_{\mathrm B}$ etc. are the respective weights for the model field at 
    588602points ${\mathrm A}$, ${\mathrm B}$ etc., and $w = {w_{}}_{\mathrm A} + {w_{}}_{\mathrm B} + {w_{}}_{\mathrm C} + {w_{}}_{\mathrm D}$. 
     
    597611  For example, the weight given to the field ${x_{}}_{\mathrm A}$ is specified as the product of the distances 
    598612  from ${\mathrm P}$ to the other points: 
    599   \begin{align*} 
     613 
     614  \begin{alignat*}{2} 
    600615    {w_{}}_{\mathrm A} = s({\mathrm P}, {\mathrm B}) \, s({\mathrm P}, {\mathrm C}) \, s({\mathrm P}, {\mathrm D}) 
    601   \end{align*} 
    602   where  
    603   \begin{align*} 
    604     s\left ({\mathrm P}, {\mathrm M} \right )  
    605      & \hspace{-2mm} = \hspace{-2mm} &  
    606       \cos^{-1} \! \left\{  
     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\{ 
    607622               \sin {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm M} 
    608              + \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm M}  
    609                \cos ({\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P})  
     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) 
    614630   involves the arcsine function (\eg see p.~101 of \citet{daley.barker_bk01}: 
    615    \begin{align*} 
    616      s\left( {\mathrm P}, {\mathrm M} \right) & \hspace{-2mm} = \hspace{-2mm} & \sin^{-1} \! \left\{ \sqrt{ 1 - x^2 } \right\} 
    617    \end{align*} 
     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_{}}_{\mathrm M} {a_{}}_{\mathrm P} + {b_{}}_{\mathrm M} {b_{}}_{\mathrm P} + {c_{}}_{\mathrm M} {c_{}}_{\mathrm P} 
    622    \end{align*} 
    623    and  
    624    \begin{align*} 
    625       {a_{}}_{\mathrm M} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\mathrm M}, \\ 
    626       {a_{}}_{\mathrm P} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\mathrm P}, \\ 
    627       {b_{}}_{\mathrm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\mathrm M} \cos {\phi_{}}_{\mathrm M}, \\ 
    628       {b_{}}_{\mathrm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\mathrm P} \cos {\phi_{}}_{\mathrm P}, \\ 
    629       {c_{}}_{\mathrm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\mathrm M} \sin {\phi_{}}_{\mathrm M}, \\ 
    630       {c_{}}_{\mathrm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\mathrm P} \sin {\phi_{}}_{\mathrm P}. 
    631   \end{align*} 
     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*} 
    632652 
    633653\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*} 
     655  \begin{alignat*}{2} 
    636656    s\left( {\mathrm P}, {\mathrm M} \right) 
    637     & \hspace{-2mm} = \hspace{-2mm} & 
    638                                       \sqrt{ \left( {\phi_{}}_{\mathrm M} - {\phi_{}}_{\mathrm P} \right)^{2} 
     657    & = & \sqrt{ \left( {\phi_{}}_{\mathrm M} - {\phi_{}}_{\mathrm P} \right)^{2} 
    639658                                      + \left( {\lambda_{}}_{\mathrm M} - {\lambda_{}}_{\mathrm P} \right)^{2} 
    640659                                      \cos^{2} {\phi_{}}_{\mathrm M} } 
    641   \end{align*} 
     660  \end{alignat*} 
    642661  where $M$ corresponds to $A$, $B$, $C$ or $D$. 
    643662 
     
    649668  a cell with coordinates (0,0), (1,0), (0,1) and (1,1). 
    650669  This method is based on the \href{https://github.com/SCRIP-Project/SCRIP}{SCRIP interpolation package}. 
    651    
     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%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
     
    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. 
    712730Let ${\mathrm P}({\lambda_{}}_{\mathrm P} ,{\phi_{}}_{\mathrm P} )$ denote the observation point, 
    713731and let ${\mathrm A}({\lambda_{}}_{\mathrm A} ,{\phi_{}}_{\mathrm A} )$, ${\mathrm B}({\lambda_{}}_{\mathrm B} ,{\phi_{}}_{\mathrm B} )$, 
    714732${\mathrm C}({\lambda_{}}_{\mathrm C} ,{\phi_{}}_{\mathrm C} )$ and ${\mathrm D}({\lambda_{}}_{\mathrm D} ,{\phi_{}}_{\mathrm D} )$ 
    715 denote the bottom left, bottom right, top left and top right corner points of the cell, respectively.  
    716 To determine if P is inside the cell, we verify that the cross-products  
     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} 
     
    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; 
     
    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. 
     
    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. 
  • NEMO/branches/2019/dev_r10984_HPC-13_IRRMANN_BDY_optimization/doc/latex/NEMO/subfiles/chap_SBC.tex

    r11263 r11353  
    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% ------------------------------------------------------------------------------------------------------------- 
     
    238262\begin{description}   
    239263\item[File name]: 
    240   the stem name of the NetCDF file to be open. 
     264  the stem name of the NetCDF file to be opened. 
    241265  This stem will be completed automatically by the model, with the addition of a '.nc' at its end and 
    242266  by date information and possibly a prefix (when using AGRIF). 
     
    249273      \begin{tabular}{|l|c|c|c|} 
    250274        \hline 
    251         & daily or weekLLL         & monthly                   &   yearly          \\   \hline 
    252         \np{clim}\forcode{ = .false.}  & fn\_yYYYYmMMdDD.nc  &   fn\_yYYYYmMM.nc   &   fn\_yYYYY.nc  \\   \hline 
    253         \np{clim}\forcode{ = .true.}         & not possible                  &  fn\_m??.nc             &   fn                \\   \hline 
     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 
    254278      \end{tabular} 
    255279    \end{center} 
    256280    \caption{ 
    257281      \protect\label{tab:fldread} 
    258       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. 
    259283      The stem name is assumed to be 'fn'. 
    260284      For weekly files, the 'LLL' corresponds to the first three letters of the first day of the week 
     
    263287      Note that (1) in mpp, if the file is split over each subdomain, the suffix '.nc' is replaced by '\_PPPP.nc', 
    264288      where 'PPPP' is the process number coded with 4 digits; 
    265       (2) when using AGRIF, the prefix '\_N' is added to files, where 'N'  is the child grid number. 
     289      (2) when using AGRIF, the prefix '\_N' is added to files, where 'N' is the child grid number. 
    266290    } 
    267291  \end{table} 
     
    273297  Its unit is in hours if it is positive (for example 24 for daily forcing) or in months if negative 
    274298  (for example -1 for monthly forcing or -12 for annual forcing). 
    275   Note that this frequency must really be an integer and not a real. 
    276   On some computers, seting it to '24.' can be interpreted as 240! 
     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! 
    277301 
    278302\item[Variable name]: 
     
    285309  00h00'00'' to 23h59'59". 
    286310  If set to 'true', the forcing will have a broken line shape. 
    287   Records are assumed to be dated the middle of the forcing period. 
     311  Records are assumed to be dated at the middle of the forcing period. 
    288312  For example, when using a daily forcing with time interpolation, 
    289313  linear interpolation will be performed between mid-day of two consecutive days.  
     
    292316  a logical to specify if a input file contains climatological forcing which can be cycle in time, 
    293317  or an interannual forcing which will requires additional files if 
    294   the period covered by the simulation exceed the one of the file. 
    295   See the above the file naming strategy which impacts the expected name of the file to be opened.  
     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.  
    296320 
    297321\item[Open/close frequency]: 
     
    302326  Files are assumed to contain data from the beginning of the open/close period. 
    303327  For example, the first record of a yearly file containing daily data is Jan 1st even if 
    304   the experiment is not starting at the beginning of the year.  
     328  the experiment is not starting at the beginning of the year. 
    305329 
    306330\item[Others]: 
     
    315339the date of the records read in the input files. 
    316340Following \citet{leclair.madec_OM09}, the date of a time step is set at the middle of the time step. 
    317 For example, for an experiment starting at 0h00'00" with a one hour time-step, 
     341For example, for an experiment starting at 0h00'00" with a one-hour time-step, 
    318342a time interpolation will be performed at the following time: 0h30'00", 1h30'00", 2h30'00", etc. 
    319343However, for forcing data related to the surface module, 
    320344values are not needed at every time-step but at every \np{nn\_fsbc} time-step. 
    321345For example with \np{nn\_fsbc}\forcode{ = 3}, the surface module will be called at time-steps 1, 4, 7, etc. 
    322 The date used for the time interpolation is thus redefined to be at the middle of \np{nn\_fsbc} time-step period. 
     346The date used for the time interpolation is thus redefined to the middle of \np{nn\_fsbc} time-step period. 
    323347In the previous example, this leads to: 1h30'00", 4h30'00", 7h30'00", etc. \\  
    324348(2) For code readablility and maintenance issues, we don't take into account the NetCDF input file calendar. 
     
    326350user in the record frequency, the open/close frequency and the type of temporal interpolation. 
    327351For example, the first record of a yearly file containing daily data that will be interpolated in time is assumed to 
    328 be start Jan 1st at 12h00'00" and end Dec 31st at 12h00'00". \\ 
     352start Jan 1st at 12h00'00" and end Dec 31st at 12h00'00". \\ 
    329353(3) If a time interpolation is requested, the code will pick up the needed data in the previous (next) file when 
    330354interpolating data with the first (last) record of the open/close period. 
     
    334358If the forcing is climatological, Dec and Jan will be keep-up from the same year. 
    335359However, if the forcing is not climatological, at the end of 
    336 the open/close period the code will automatically close the current file and open the next one. 
     360the open/close period, the code will automatically close the current file and open the next one. 
    337361Note that, if the experiment is starting (ending) at the beginning (end) of 
    338 an open/close period we do accept that the previous (next) file is not existing. 
     362an open/close period, we do accept that the previous (next) file is not existing. 
    339363In this case, the time interpolation will be performed between two identical values. 
    340364For example, when starting an experiment on Jan 1st of year Y with yearly files and daily data to be interpolated, 
     
    354378Interpolation on the Fly allows the user to supply input files required for the surface forcing on 
    355379grids other than the model grid. 
    356 To do this he or she must supply, in addition to the source data file, a file of weights to be used to 
     380To do this, he or she must supply, in addition to the source data file(s), a file of weights to be used to 
    357381interpolate from the data grid to the model grid. 
    358382The original development of this code used the SCRIP package 
    359383(freely available \href{http://climate.lanl.gov/Software/SCRIP}{here} under a copyright agreement). 
    360 In principle, any package can be used to generate the weights, but the variables in 
     384In principle, any package such as CDO can be used to generate the weights, but the variables in 
    361385the input weights file must have the same names and meanings as assumed by the model. 
    362 Two methods are currently available: bilinear and bicubic interpolation. 
     386Two methods are currently available: bilinear and bicubic interpolations. 
    363387Prior to the interpolation, providing a land/sea mask file, the user can decide to remove land points from 
    364388the input file and substitute the corresponding values with the average of the 8 neighbouring points in 
     
    366390Only "sea points" are considered for the averaging. 
    367391The land/sea mask file must be provided in the structure associated with the input variable. 
    368 The netcdf land/sea mask variable name must be 'LSM' it must have the same horizontal and vertical dimensions of 
    369 the associated variable and should be equal to 1 over land and 0 elsewhere. 
    370 The procedure can be recursively applied setting nn\_lsm > 1 in namsbc namelist. 
    371 Note that nn\_lsm=0 forces the code to not apply the procedure even if a file for land/sea mask is supplied. 
    372  
     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% ------------------------------------------------------------------------------------------------------------- 
    373401\subsubsection{Bilinear interpolation} 
    374402\label{subsec:SBC_iof_bilinear} 
     
    376404The input weights file in this case has two sets of variables: 
    377405src01, src02, src03, src04 and wgt01, wgt02, wgt03, wgt04. 
    378 The "src" variables correspond to the point in the input grid to which the weight "wgt" is to be applied. 
     406The "src" variables correspond to the point in the input grid to which the weight "wgt" is applied. 
    379407Each src value is an integer corresponding to the index of a point in the input grid when 
    380408written as a one dimensional array. 
     
    392420and wgt(1) corresponds to variable "wgt01" for example. 
    393421 
     422 
     423% ------------------------------------------------------------------------------------------------------------- 
     424% Bicubic interpolation 
     425% ------------------------------------------------------------------------------------------------------------- 
    394426\subsubsection{Bicubic interpolation} 
    395427\label{subsec:SBC_iof_bicubic} 
    396428 
    397 Again there are two sets of variables: "src" and "wgt". 
    398 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. 
    399431The symbolic algorithm used to calculate values on the model grid is now: 
    400432 
     
    402434  \begin{split} 
    403435    f_{m}(i,j) =  f_{m}(i,j) +& \sum_{k=1}^{4} {wgt(k)f(idx(src(k)))} 
    404     +   \sum_{k=5}^{8} {wgt(k)\left.\frac{\partial f}{\partial i}\right| _{idx(src(k))} }    \\ 
    405     +& \sum_{k=9}^{12} {wgt(k)\left.\frac{\partial f}{\partial j}\right| _{idx(src(k))} } 
    406     +   \sum_{k=13}^{16} {wgt(k)\left.\frac{\partial ^2 f}{\partial i \partial j}\right| _{idx(src(k))} } 
     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))} } 
    407439  \end{split} 
    408440\] 
    409441The gradients here are taken with respect to the horizontal indices and not distances since 
    410 the spatial dependency has been absorbed into the weights. 
    411  
     442the spatial dependency has been included into the weights. 
     443 
     444 
     445% ------------------------------------------------------------------------------------------------------------- 
     446% Implementation 
     447% ------------------------------------------------------------------------------------------------------------- 
    412448\subsubsection{Implementation} 
    413449\label{subsec:SBC_iof_imp} 
     
    421457inspecting a global attribute stored in the weights input file. 
    422458This attribute must be called "ew\_wrap" and be of integer type. 
    423 If it is negative, the input non-model grid is assumed not to be cyclic. 
     459If it is negative, the input non-model grid is assumed to be not cyclic. 
    424460If zero or greater, then the value represents the number of columns that overlap. 
    425461$E.g.$ if the input grid has columns at longitudes 0, 1, 2, .... , 359, then ew\_wrap should be set to 0; 
    426462if longitudes are 0.5, 2.5, .... , 358.5, 360.5, 362.5, ew\_wrap should be 2. 
    427463If the model does not find attribute ew\_wrap, then a value of -999 is assumed. 
    428 In this case the \rou{fld\_read} routine defaults ew\_wrap to value 0 and 
     464In this case, the \rou{fld\_read} routine defaults ew\_wrap to value 0 and 
    429465therefore the grid is assumed to be cyclic with no overlapping columns. 
    430 (In fact this only matters when bicubic interpolation is required.) 
     466(In fact, this only matters when bicubic interpolation is required.) 
    431467Note that no testing is done to check the validity in the model, 
    432468since there is no way of knowing the name used for the longitude variable, 
     
    445481or is a copy of one from the first few columns on the opposite side of the grid (cyclical case). 
    446482 
     483 
     484% ------------------------------------------------------------------------------------------------------------- 
     485% Limitations 
     486% ------------------------------------------------------------------------------------------------------------- 
    447487\subsubsection{Limitations} 
    448488\label{subsec:SBC_iof_lim} 
     
    450490\begin{enumerate}   
    451491\item 
    452   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. 
    453493\item 
    454494  This code is not guaranteed to produce positive definite answers from positive definite inputs when 
     
    471511(see the directory NEMOGCM/TOOLS/WEIGHTS). 
    472512 
     513 
    473514% ------------------------------------------------------------------------------------------------------------- 
    474515% Standalone Surface Boundary Condition Scheme 
    475516% ------------------------------------------------------------------------------------------------------------- 
    476 \subsection{Standalone surface boundary condition scheme} 
    477 \label{subsec:SAS_iof} 
    478  
    479 %---------------------------------------namsbc_ana-------------------------------------------------- 
     517\subsection{Standalone surface boundary condition scheme (SAS)} 
     518\label{subsec:SAS} 
     519 
     520%---------------------------------------namsbc_sas-------------------------------------------------- 
    480521 
    481522\nlst{namsbc_sas} 
    482523%-------------------------------------------------------------------------------------------------------------- 
    483524 
    484 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, 
    485526salinity and velocity fields and simply read them in from a previous run or receive them from OASIS.   
    486527For example: 
     
    497538  Spinup of the iceberg floats 
    498539\item 
    499   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.}) 
    500541\end{itemize} 
    501542 
    502 The StandAlone Surface scheme provides this utility. 
     543The Standalone Surface scheme provides this capacity. 
    503544Its options are defined through the \ngn{namsbc\_sas} namelist variables. 
    504545A new copy of the model has to be compiled with a configuration based on ORCA2\_SAS\_LIM. 
    505 However no namelist parameters need be changed from the settings of the previous run (except perhaps nn{\_}date0). 
     546However, no namelist parameters need be changed from the settings of the previous run (except perhaps nn{\_}date0). 
    506547In this configuration, a few routines in the standard model are overriden by new versions. 
    507548Routines replaced are: 
     
    525566  so calls to restart functions have been removed. 
    526567  This also means that the calendar cannot be controlled by time in a restart file, 
    527   so the user must make sure that nn{\_}date0 in the model namelist is correct for his or her purposes. 
     568  so the user must check that nn{\_}date0 in the model namelist is correct for his or her purposes. 
    528569\item 
    529570  \mdl{stpctl}: 
     
    544585  velocity arrays at the surface. 
    545586  These filenames are supplied in namelist namsbc{\_}sas. 
    546   Unfortunately because of limitations with the \mdl{iom} module, 
     587  Unfortunately, because of limitations with the \mdl{iom} module, 
    547588  the full 3D fields from the mean files have to be read in and interpolated in time, 
    548589  before using just the top level. 
     
    551592 
    552593 
    553 % Missing the description of the 2 following variables: 
    554 %   ln_3d_uve   = .true.    !  specify whether we are supplying a 3D u,v and e3 field 
    555 %   ln_read_frq = .false.    !  specify whether we must read frq or not 
    556  
    557  
    558  
    559 % ================================================================ 
    560 % Analytical formulation (sbcana module)  
    561 % ================================================================ 
    562 \section[Analytical formulation (\textit{sbcana.F90})] 
    563 {Analytical formulation (\protect\mdl{sbcana})} 
    564 \label{sec:SBC_ana} 
    565  
    566 %---------------------------------------namsbc_ana-------------------------------------------------- 
    567 % 
    568 %\nlst{namsbc_ana} 
    569 %-------------------------------------------------------------------------------------------------------------- 
    570  
    571 The analytical formulation of the surface boundary condition is the default scheme. 
    572 In this case, all the six fluxes needed by the ocean are assumed to be uniform in space. 
    573 They take constant values given in the namelist \ngn{namsbc{\_}ana} by 
    574 the variables \np{rn\_utau0}, \np{rn\_vtau0}, \np{rn\_qns0}, \np{rn\_qsr0}, and \np{rn\_emp0} 
    575 ($\textit{emp}=\textit{emp}_S$). 
    576 The runoff is set to zero. 
    577 In addition, the wind is allowed to reach its nominal value within a given number of time steps (\np{nn\_tau000}). 
    578  
    579 If a user wants to apply a different analytical forcing, 
    580 the \mdl{sbcana} module can be modified to use another scheme. 
    581 As an example, the \mdl{sbc\_ana\_gyre} routine provides the analytical forcing for the GYRE configuration 
    582 (see GYRE configuration manual, in preparation). 
     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 
    583597 
    584598 
     
    605619 
    606620 
     621 
    607622% ================================================================ 
    608623% Bulk formulation 
    609624% ================================================================ 
    610 \section[Bulk formulation {(\textit{sbcblk\{\_core,\_clio\}.F90})}] 
    611 {Bulk formulation {(\protect\mdl{sbcblk\_core}, \protect\mdl{sbcblk\_clio})}} 
     625\section[Bulk formulation (\textit{sbcblk.F90})] 
     626{Bulk formulation (\protect\mdl{sbcblk})} 
    612627\label{sec:SBC_blk} 
    613  
    614 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. 
    615635 
    616636The atmospheric fields used depend on the bulk formulae used. 
    617 Two bulk formulations are available: 
    618 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. 
    619642The choice is made by setting to true one of the following namelist variable: 
    620 \np{ln\_core} or \np{ln\_clio}. 
    621  
    622 Note: 
    623 in forced mode, when a sea-ice model is used, a bulk formulation (CLIO or CORE) have to be used. 
    624 Therefore the two bulk (CLIO and CORE) formulea include the computation of the fluxes over 
    625 both an ocean and an ice surface.  
    626  
    627 % ------------------------------------------------------------------------------------------------------------- 
    628 %        CORE Bulk formulea 
    629 % ------------------------------------------------------------------------------------------------------------- 
    630 \subsection[CORE formulea (\textit{sbcblk\_core.F90}, \forcode{ln_core = .true.})] 
    631 {CORE formulea (\protect\mdl{sbcblk\_core}, \protect\np{ln\_core}\forcode{ = .true.})} 
    632 \label{subsec:SBC_blk_core} 
    633 %------------------------------------------namsbc_core---------------------------------------------------- 
    634 % 
    635 %\nlst{namsbc_core} 
    636 %------------------------------------------------------------------------------------------------------------- 
    637  
    638 The CORE bulk formulae have been developed by \citet{large.yeager_rpt04}. 
    639 They have been designed to handle the CORE forcing, a mixture of NCEP reanalysis and satellite data. 
    640 They use an inertial dissipative method to compute the turbulent transfer coefficients 
    641 (momentum, sensible heat and evaporation) from the 10 metre wind speed, air temperature and specific humidity. 
    642 This \citet{large.yeager_rpt04} dataset is available through 
    643 the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/CORE.html}{GFDL web site}. 
    644  
    645 Note that substituting ERA40 to NCEP reanalysis fields does not require changes in the bulk formulea themself. 
    646 This is the so-called DRAKKAR Forcing Set (DFS) \citep{brodeau.barnier.ea_OM10}. 
    647  
    648 Options are defined through the  \ngn{namsbc\_core} namelist variables. 
    649 The required 8 input fields are: 
     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: 
    650649 
    651650%--------------------------------------------------TABLE-------------------------------------------------- 
    652651\begin{table}[htbp] 
    653   \label{tab:CORE} 
     652  \label{tab:BULK} 
    654653  \begin{center} 
    655654    \begin{tabular}{|l|c|c|c|} 
    656655      \hline 
    657       Variable desciption              & Model variable  & Units   & point \\    \hline 
    658       i-component of the 10m air velocity & utau      & $m.s^{-1}$         & T  \\  \hline 
    659       j-component of the 10m air velocity & vtau      & $m.s^{-1}$         & T  \\  \hline 
    660       10m air temperature              & tair      & \r{}$K$            & T   \\ \hline 
    661       Specific humidity             & humi      & \%              & T \\      \hline 
    662       Incoming long wave radiation     & qlw    & $W.m^{-2}$         & T \\      \hline 
    663       Incoming short wave radiation    & qsr    & $W.m^{-2}$         & T \\      \hline 
    664       Total precipitation (liquid + solid)   & precip & $Kg.m^{-2}.s^{-1}$ & T \\   \hline 
    665       Solid precipitation              & snow      & $Kg.m^{-2}.s^{-1}$ & T \\   \hline 
     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 
    666666    \end{tabular} 
    667667  \end{center} 
     
    682682\np{rn\_zu}: is the height of wind measurements (m) 
    683683 
    684 Three multiplicative factors are availables:  
    685 \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 
    686686increasing/reducing the precipitations (total and snow) and or evaporation, respectively. 
    687687The third one,\np{rn\_vfac}, control to which extend the ice/ocean velocities are taken into account in 
    688688the calculation of surface wind stress. 
    689 Its range should be between zero and one, and it is recommended to set it to 0. 
    690  
    691 % ------------------------------------------------------------------------------------------------------------- 
    692 %        CLIO Bulk formulea 
    693 % ------------------------------------------------------------------------------------------------------------- 
    694 \subsection[CLIO formulea (\textit{sbcblk\_clio.F90}, \forcode{ln_clio = .true.})] 
    695 {CLIO formulea (\protect\mdl{sbcblk\_clio}, \protect\np{ln\_clio}\forcode{ = .true.})} 
    696 \label{subsec:SBC_blk_clio} 
    697 %------------------------------------------namsbc_clio---------------------------------------------------- 
    698 % 
    699 %\nlst{namsbc_clio} 
    700 %------------------------------------------------------------------------------------------------------------- 
    701  
    702 The CLIO bulk formulae were developed several years ago for the Louvain-la-neuve coupled ice-ocean model 
    703 (CLIO, \cite{goosse.deleersnijder.ea_JGR99}).  
    704 They are simpler bulk formulae. 
    705 They assume the stress to be known and compute the radiative fluxes from a climatological cloud cover.  
    706  
    707 Options are defined through the  \ngn{namsbc\_clio} namelist variables. 
    708 The required 7 input fields are: 
    709  
    710 %--------------------------------------------------TABLE-------------------------------------------------- 
    711 \begin{table}[htbp] 
    712   \label{tab:CLIO} 
    713   \begin{center} 
    714     \begin{tabular}{|l|l|l|l|} 
    715       \hline 
    716       Variable desciption           & Model variable  & Units           & point \\  \hline 
    717       i-component of the ocean stress     & utau         & $N.m^{-2}$         & U \\   \hline 
    718       j-component of the ocean stress     & vtau         & $N.m^{-2}$         & V \\   \hline 
    719       Wind speed module             & vatm         & $m.s^{-1}$         & T \\   \hline 
    720       10m air temperature              & tair         & \r{}$K$            & T \\   \hline 
    721       Specific humidity                & humi         & \%              & T \\   \hline 
    722       Cloud cover                   &           & \%              & T \\   \hline 
    723       Total precipitation (liquid + solid)   & precip    & $Kg.m^{-2}.s^{-1}$ & T \\   \hline 
    724       Solid precipitation              & snow         & $Kg.m^{-2}.s^{-1}$ & T \\   \hline 
    725     \end{tabular} 
    726   \end{center} 
    727 \end{table} 
    728 %-------------------------------------------------------------------------------------------------------------- 
     689Its range must be between zero and one, and it is recommended to set it to 0 at low-resolution (ORCA2 configuration). 
    729690 
    730691As for the flux formulation, information about the input data required by the model is provided in 
    731 the namsbc\_blk\_core or namsbc\_blk\_clio namelist (see \autoref{subsec:SBC_fldread}).  
     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 
    732761 
    733762% ================================================================ 
     
    743772 
    744773In the coupled formulation of the surface boundary condition, 
    745 the fluxes are provided by the OASIS coupler at a frequency which is defined in the OASIS coupler, 
     774the fluxes are provided by the OASIS coupler at a frequency which is defined in the OASIS coupler namelist, 
    746775while sea and ice surface temperature, ocean and ice albedo, and ocean currents are sent to 
    747776the atmospheric component. 
    748777 
    749778A generalised coupled interface has been developed. 
    750 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. 
    751781It has been successfully used to interface \NEMO to most of the European atmospheric GCM 
    752782(ARPEGE, ECHAM, ECMWF, HadAM, HadGAM, LMDz), as well as to \href{http://wrf-model.org/}{WRF} 
    753783(Weather Research and Forecasting Model). 
    754784 
    755 Note that in addition to the setting of \np{ln\_cpl} to true, the \key{coupled} have to be defined. 
    756 The CPP key is mainly used in sea-ice to ensure that the atmospheric fluxes are actually received by 
    757 the ice-ocean system (no calculation of ice sublimation in coupled mode). 
    758 When PISCES biogeochemical model (\key{top} and \key{pisces}) is also used in the coupled system,  
    759 the whole carbon cycle is computed by defining \key{cpl\_carbon\_cycle}. 
     785When PISCES biogeochemical model (\key{top}) is also used in the coupled system,  
     786the whole carbon cycle is computed. 
    760787In this case, CO$_2$ fluxes will be exchanged between the atmosphere and the ice-ocean system 
    761788(and need to be activated in \ngn{namsbc{\_}cpl} ). 
     
    763790The namelist above allows control of various aspects of the coupling fields (particularly for vectors) and 
    764791now allows for any coupling fields to have multiple sea ice categories (as required by LIM3 and CICE). 
    765 When indicating a multi-category coupling field in namsbc{\_}cpl the number of categories will be determined by 
     792When indicating a multi-category coupling field in \ngn{namsbc{\_}cpl}, the number of categories will be determined by 
    766793the number used in the sea ice model. 
    767 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 
    768795the sea ice model is running with multiple categories - 
    769 in this case the user should examine the code to be sure the assumptions made are satisfactory. 
    770 In cases where this is definitely not possible the model should abort with an error message. 
    771 The new code has been tested using ECHAM with LIM2, and HadGAM3 with CICE but 
    772 although it will compile with \key{lim3} additional minor code changes may be required to run using LIM3. 
     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 
    773799 
    774800 
     
    785811 
    786812The optional atmospheric pressure can be used to force ocean and ice dynamics 
    787 (\np{ln\_apr\_dyn}\forcode{ = .true.}, \textit{\ngn{namsbc}} namelist). 
    788 The input atmospheric forcing defined via \np{sn\_apr} structure (\textit{namsbc\_apr} namelist) 
     813(\np{ln\_apr\_dyn}\forcode{ = .true.}, \ngn{namsbc} namelist). 
     814The input atmospheric forcing defined via \np{sn\_apr} structure (\ngn{namsbc\_apr} namelist) 
    789815can be interpolated in time to the model time step, and even in space when the interpolation on-the-fly is used. 
    790816When used to force the dynamics, the atmospheric pressure is further transformed into 
     
    796822where $P_{atm}$ is the atmospheric pressure and $P_o$ a reference atmospheric pressure. 
    797823A value of $101,000~N/m^2$ is used unless \np{ln\_ref\_apr} is set to true. 
    798 In this case $P_o$ is set to the value of $P_{atm}$ averaged over the ocean domain, 
    799 \ie the mean value of $\eta_{ib}$ is kept to zero at all time step. 
     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. 
    800826 
    801827The gradient of $\eta_{ib}$ is added to the RHS of the ocean momentum equation (see \mdl{dynspg} for the ocean). 
    802828For sea-ice, the sea surface height, $\eta_m$, which is provided to the sea ice model is set to $\eta - \eta_{ib}$ 
    803829(see \mdl{sbcssr} module). 
    804 $\eta_{ib}$ can be set in the output. 
     830$\eta_{ib}$ can be written in the output. 
    805831This can simplify altimetry data and model comparison as 
    806832inverse barometer sea surface height is usually removed from these date prior to their distribution. 
     
    809835the equivalent inverse barometer sea surface height $\eta_{ib}$ can be added to BDY ssh data:  
    810836\np{ln\_apr\_obc}  might be set to true. 
     837 
     838 
    811839 
    812840% ================================================================ 
     
    835863The equilibrium tidal forcing is expressed as a sum over a subset of 
    836864constituents chosen from the set of available tidal constituents 
    837 defined in file \rou{SBC/tide.h90} (this comprises the tidal 
     865defined in file \textit{SBC/tide.h90} (this comprises the tidal 
    838866constituents \textit{M2, N2, 2N2, S2, K2, K1, O1, Q1, P1, M4, Mf, Mm, 
    839867  Msqm, Mtm, S1, MU2, NU2, L2}, and \textit{T2}). Individual 
     
    850878discussion about the practical implementation of this term). 
    851879Nevertheless, the complex calculations involved would make this 
    852 computationally too expensive.  Here, two options are available: 
     880computationally too expensive. Here, two options are available: 
    853881$\Pi_{sal}$ generated by an external model can be read in 
    854882(\np{ln\_read\_load=.true.}), or a ``scalar approximation'' can be 
     
    861889errors. Setting both \np{ln\_read\_load} and \np{ln\_scal\_load} to 
    862890\forcode{.false.} removes the SAL contribution. 
     891 
     892 
    863893 
    864894% ================================================================ 
     
    944974As such the volume of water does not change, but the water is diluted. 
    945975 
    946 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. 
    947977Instead in the surface box (as well as water moving up from the boxes below) a volume of runoff water is added with 
    948978no corresponding heat and salt addition and so as happens in the lower boxes there is a dilution effect. 
     
    9871017%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: 
    9881018 
    989 %} 
     1019 
     1020 
    9901021% ================================================================ 
    9911022%        Ice shelf melting 
     
    9981029\nlst{namsbc_isf} 
    9991030%-------------------------------------------------------------------------------------------------------- 
     1031 
    10001032The namelist variable in \ngn{namsbc}, \np{nn\_isf}, controls the ice shelf representation. 
    10011033Description and result of sensitivity test to \np{nn\_isf} are presented in \citet{mathiot.jenkins.ea_GMD17}.  
     
    10031035 
    10041036\begin{description} 
    1005 \item[\np{nn\_isf}\forcode{ = 1}]: 
     1037 
     1038  \item[\np{nn\_isf}\forcode{ = 1}]: 
    10061039  The ice shelf cavity is represented (\np{ln\_isfcav}\forcode{ = .true.} needed). 
    10071040  The fwf and heat flux are depending of the local water properties. 
     1041   
    10081042  Two different bulk formulae are available: 
    10091043 
     
    10601094     This formulation has not been extensively tested in NEMO (not recommended). 
    10611095   \end{description} 
    1062  \item[\np{nn\_isf}\forcode{ = 2}]: 
     1096  \item[\np{nn\_isf}\forcode{ = 2}]: 
    10631097   The ice shelf cavity is not represented. 
    10641098   The fwf and heat flux are computed using the \citet{beckmann.goosse_OM03} parameterisation of isf melting. 
     
    10671101   (\np{sn\_depmin\_isf}) as in (\np{nn\_isf}\forcode{ = 3}). 
    10681102   The effective melting length (\np{sn\_Leff\_isf}) is read from a file. 
    1069  \item[\np{nn\_isf}\forcode{ = 3}]: 
     1103  \item[\np{nn\_isf}\forcode{ = 3}]: 
    10701104   The ice shelf cavity is not represented. 
    10711105   The fwf (\np{sn\_rnfisf}) is prescribed and distributed along the ice shelf edge between 
     
    10731107   the base of the ice shelf along the calving front (\np{sn\_depmin\_isf}). 
    10741108   The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$. 
    1075  \item[\np{nn\_isf}\forcode{ = 4}]: 
     1109  \item[\np{nn\_isf}\forcode{ = 4}]: 
    10761110   The ice shelf cavity is opened (\np{ln\_isfcav}\forcode{ = .true.} needed). 
    10771111   However, the fwf is not computed but specified from file \np{sn\_fwfisf}). 
     
    11081142%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
    11091143 
     1144 
     1145 
     1146% ================================================================ 
     1147%        Ice sheet coupling 
     1148% ================================================================ 
    11101149\section{Ice sheet coupling} 
    11111150\label{sec:SBC_iscpl} 
     
    11141153\nlst{namsbc_iscpl} 
    11151154%-------------------------------------------------------------------------------------------------------- 
     1155 
    11161156Ice sheet/ocean coupling is done through file exchange at the restart step. 
    11171157At each restart step: 
     1158 
    11181159\begin{description} 
    11191160\item[Step 1]: the ice sheet model send a new bathymetry and ice shelf draft netcdf file. 
     
    11271168potentially some new wet/dry cells due to the ice sheet dynamics/thermodynamics. 
    11281169The wetting and drying scheme applied on the restart is very simple and described below for the 6 different possible cases: 
     1170 
    11291171\begin{description} 
    11301172\item[Thin a cell down]: 
     
    11651207The 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). 
    11661208 
    1167 % 
     1209 
     1210 
    11681211% ================================================================ 
    11691212%        Handling of icebergs 
     
    11961239  the geographical box: lonmin,lonmax,latmin,latmax 
    11971240\item[\np{nn\_test\_icebergs}\forcode{ = -1}] 
    1198   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. 
    11991242  This should be a file with a field on the configuration grid (typically ORCA) 
    12001243  representing ice accumulation rate at each model point. 
     
    12341277since its trajectory data may be spread across multiple files. 
    12351278 
    1236 % ------------------------------------------------------------------------------------------------------------- 
     1279 
     1280 
     1281% ============================================================================================================= 
    12371282%        Interactions with waves (sbcwave.F90, ln_wave) 
    1238 % ------------------------------------------------------------------------------------------------------------- 
     1283% ============================================================================================================= 
    12391284\section[Interactions with waves (\textit{sbcwave.F90}, \texttt{ln\_wave})] 
    12401285{Interactions with waves (\protect\mdl{sbcwave}, \protect\np{ln\_wave})} 
     
    12521297 
    12531298Physical processes related to ocean surface waves can be accounted by setting the logical variable  
    1254 \np{ln\_wave}\forcode{= .true.} in \ngn{namsbc} namelist. In addition, specific flags accounting for  
    1255 different porcesses should be activated as explained in the following sections. 
     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. 
    12561301 
    12571302Wave fields can be provided either in forced or coupled mode: 
     
    12651310 
    12661311 
    1267 % ================================================================ 
     1312% ---------------------------------------------------------------- 
    12681313% Neutral drag coefficient from wave model (ln_cdgw) 
    12691314 
    1270 % ================================================================ 
     1315% ---------------------------------------------------------------- 
    12711316\subsection[Neutral drag coefficient from wave model (\texttt{ln\_cdgw})] 
    12721317{Neutral drag coefficient from wave model (\protect\np{ln\_cdgw})} 
     
    12751320The neutral surface drag coefficient provided from an external data source (\ie a wave model),  
    12761321can be used by setting the logical variable \np{ln\_cdgw} \forcode{= .true.} in \ngn{namsbc} namelist.  
    1277 Then using the routine \rou{turb\_ncar} and starting from the neutral drag coefficent provided,  
     1322Then using the routine \rou{sbcblk\_algo\_ncar} and starting from the neutral drag coefficent provided,  
    12781323the drag coefficient is computed according to the stable/unstable conditions of the  
    12791324air-sea interface following \citet{large.yeager_rpt04}.  
    12801325 
    12811326 
    1282 % ================================================================ 
     1327% ---------------------------------------------------------------- 
    12831328% 3D Stokes Drift (ln_sdw, nn_sdrift) 
    1284 % ================================================================ 
     1329% ---------------------------------------------------------------- 
    12851330\subsection[3D Stokes Drift (\texttt{ln\_sdw}, \texttt{nn\_sdrift})] 
    12861331{3D Stokes Drift (\protect\np{ln\_sdw, nn\_sdrift})} 
     
    12921337As waves travel, the water particles that make up the waves travel in orbital motions but  
    12931338without a closed path. Their movement is enhanced at the top of the orbit and slowed slightly  
    1294 at the bottom so the result is a net forward motion of water particles, referred to as the Stokes drift.  
     1339at the bottom, so the result is a net forward motion of water particles, referred to as the Stokes drift.  
    12951340An accurate evaluation of the Stokes drift and the inclusion of related processes may lead to improved  
    1296 representation of surface physics in ocean general circulation models. 
     1341representation of surface physics in ocean general circulation models. %GS: reference needed 
    12971342The Stokes drift velocity $\mathbf{U}_{st}$ in deep water can be computed from the wave spectrum and may be written as:  
    12981343 
     
    13091354$k=\frac{2\pi}{\lambda}$ (being $\lambda$ the wavelength). \\ 
    13101355 
    1311 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  
    13121357and its computation quickly becomes expensive as the 2D spectrum must be integrated for each vertical level.  
    13131358To simplify, it is customary to use approximations to the full Stokes profile. 
     
    13391384 
    13401385\item[\np{nn\_sdrift} = 1]: velocity profile based on the Phillips spectrum which is considered to be a  
    1341 reasonable estimate of the part of the spectrum most contributing to the Stokes drift velocity near the surface 
     1386reasonable estimate of the part of the spectrum mostly contributing to the Stokes drift velocity near the surface 
    13421387\citep{breivik.bidlot.ea_OM16}: 
    13431388 
     
    13771422 
    13781423 
    1379 % ================================================================ 
     1424% ---------------------------------------------------------------- 
    13801425% Stokes-Coriolis term (ln_stcor) 
    1381 % ================================================================ 
     1426% ---------------------------------------------------------------- 
    13821427\subsection[Stokes-Coriolis term (\texttt{ln\_stcor})] 
    13831428{Stokes-Coriolis term (\protect\np{ln\_stcor})} 
     
    13921437 
    13931438 
    1394 % ================================================================ 
     1439% ---------------------------------------------------------------- 
    13951440% Waves modified stress (ln_tauwoc, ln_tauw) 
    1396 % ================================================================ 
    1397 \subsection[Wave modified sress (\texttt{ln\_tauwoc}, \texttt{ln\_tauw})] 
     1441% ---------------------------------------------------------------- 
     1442\subsection[Wave modified stress (\texttt{ln\_tauwoc}, \texttt{ln\_tauw})] 
    13981443{Wave modified sress (\protect\np{ln\_tauwoc, ln\_tauw})} 
    13991444\label{subsec:SBC_wave_tauw} 
     
    14021447into the waves \citep{janssen.breivik.ea_rpt13}. Therefore, when waves are growing, momentum and energy is spent and is not  
    14031448available for forcing the mean circulation, while in the opposite case of a decaying sea  
    1404 state more momentum is available for forcing the ocean.  
    1405 Only when the sea state is in equilibrium the ocean is forced by the atmospheric stress,  
    1406 but in practice an equilibrium sea state is a fairly rare event.  
     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.  
    14071452So the atmospheric stress felt by the ocean circulation $\tau_{oc,a}$ can be expressed as:  
    14081453 
     
    14341479 
    14351480 
     1481 
    14361482% ================================================================ 
    14371483% Miscellanea options 
     
    14391485\section{Miscellaneous options} 
    14401486\label{sec:SBC_misc} 
     1487 
    14411488 
    14421489% ------------------------------------------------------------------------------------------------------------- 
     
    14461493{Diurnal cycle (\protect\mdl{sbcdcy})} 
    14471494\label{subsec:SBC_dcy} 
    1448 %------------------------------------------namsbc_rnf---------------------------------------------------- 
     1495%------------------------------------------namsbc------------------------------------------------------------- 
    14491496% 
    14501497\nlst{namsbc}  
     
    14681515 
    14691516\cite{bernie.woolnough.ea_JC05} have shown that to capture 90$\%$ of the diurnal variability of SST requires a vertical resolution in upper ocean of 1~m or better and a temporal resolution of the surface fluxes of 3~h or less. 
    1470 Unfortunately high frequency forcing fields are rare, not to say inexistent. 
    1471 Nevertheless, it is possible to obtain a reasonable diurnal cycle of the SST knowning only short wave flux (SWF) at 
    1472 high frequency \citep{bernie.guilyardi.ea_CD07}. 
     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}. 
    14731519Furthermore, only the knowledge of daily mean value of SWF is needed, 
    14741520as higher frequency variations can be reconstructed from them, 
     
    14761522The \cite{bernie.guilyardi.ea_CD07} reconstruction algorithm is available in \NEMO by 
    14771523setting \np{ln\_dm2dc}\forcode{ = .true.} (a \textit{\ngn{namsbc}} namelist variable) when 
    1478 using CORE bulk formulea (\np{ln\_blk\_core}\forcode{ = .true.}) or 
     1524using a bulk formulation (\np{ln\_blk}\forcode{ = .true.}) or 
    14791525the flux formulation (\np{ln\_flx}\forcode{ = .true.}). 
    14801526The reconstruction is performed in the \mdl{sbcdcy} module. 
    14811527The detail of the algoritm used can be found in the appendix~A of \cite{bernie.guilyardi.ea_CD07}. 
    1482 The algorithm preserve the daily mean incoming SWF as the reconstructed SWF at 
     1528The algorithm preserves the daily mean incoming SWF as the reconstructed SWF at 
    14831529a given time step is the mean value of the analytical cycle over this time step (\autoref{fig:SBC_diurnal}). 
    14841530The use of diurnal cycle reconstruction requires the input SWF to be daily 
    1485 (\ie a frequency of 24 and a time interpolation set to true in \np{sn\_qsr} namelist parameter). 
    1486 Furthermore, it is recommended to have a least 8 surface module time step per day, 
     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, 
    14871533that is  $\rdt \ nn\_fsbc < 10,800~s = 3~h$. 
    14881534An example of recontructed SWF is given in \autoref{fig:SBC_dcy} for a 12 reconstructed diurnal cycle, 
     
    15071553an inconsistency between the scale of the vertical resolution and the forcing acting on that scale. 
    15081554 
     1555 
    15091556% ------------------------------------------------------------------------------------------------------------- 
    15101557%        Rotation of vector pairs onto the model grid directions 
     
    15131560\label{subsec:SBC_rotation} 
    15141561 
    1515 When using a flux (\np{ln\_flx}\forcode{ = .true.}) or 
    1516 bulk (\np{ln\_clio}\forcode{ = .true.} or \np{ln\_core}\forcode{ = .true.}) formulation, 
     1562When using a flux (\np{ln\_flx}\forcode{ = .true.}) or bulk (\np{ln\_blk}\forcode{ = .true.}) formulation, 
    15171563pairs of vector components can be rotated from east-north directions onto the local grid directions. 
    15181564This is particularly useful when interpolation on the fly is used since here any vectors are likely to 
    15191565be defined relative to a rectilinear grid. 
    1520 To activate this option a non-empty string is supplied in the rotation pair column of the relevant namelist. 
     1566To activate this option, a non-empty string is supplied in the rotation pair column of the relevant namelist. 
    15211567The eastward component must start with "U" and the northward component with "V".   
    15221568The remaining characters in the strings are used to identify which pair of components go together. 
     
    15271573The rot\_rep routine from the \mdl{geo2ocean} module is used to perform the rotation. 
    15281574 
     1575 
    15291576% ------------------------------------------------------------------------------------------------------------- 
    15301577%        Surface restoring to observed SST and/or SSS 
     
    15381585%------------------------------------------------------------------------------------------------------------- 
    15391586 
    1540 IOptions are defined through the \ngn{namsbc\_ssr} namelist variables. 
     1587Options are defined through the \ngn{namsbc\_ssr} namelist variables. 
    15411588On forced mode using a flux formulation (\np{ln\_flx}\forcode{ = .true.}), 
    15421589a feedback term \emph{must} be added to the surface heat flux $Q_{ns}^o$: 
     
    15701617The SSS restoring term should be viewed as a flux correction on freshwater fluxes to 
    15711618reduce the uncertainties we have on the observed freshwater budget. 
     1619 
    15721620 
    15731621% ------------------------------------------------------------------------------------------------------------- 
     
    15951643  This prevents deep convection to occur when trying to reach the freezing point 
    15961644  (and so ice covered area condition) while the SSS is too large. 
    1597   This manner of managing sea-ice area, just by using si IF case, 
     1645  This manner of managing sea-ice area, just by using a IF case, 
    15981646  is usually referred as the \textit{ice-if} model. 
    15991647  It can be found in the \mdl{sbcice{\_}if} module. 
     
    16021650  This model computes the ice-ocean fluxes, 
    16031651  that are combined with the air-sea fluxes using the ice fraction of each model cell to 
    1604   provide the surface ocean fluxes. 
    1605   Note that the activation of a sea-ice model is is done by defining a CPP key (\key{lim3} or \key{cice}). 
     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}). 
    16061654  The activation automatically overwrites the read value of nn{\_}ice to its appropriate value 
    1607   (\ie $2$ for LIM-3 or $3$ for CICE). 
     1655  (\ie $2$ for SI3 or $3$ for CICE). 
    16081656\end{description} 
    16091657 
    16101658% {Description of Ice-ocean interface to be added here or in LIM 2 and 3 doc ?} 
    1611  
     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% ------------------------------------------------------------------------------------------------------------- 
    16121665\subsection[Interface to CICE (\textit{sbcice\_cice.F90})] 
    16131666{Interface to CICE (\protect\mdl{sbcice\_cice})} 
    16141667\label{subsec:SBC_cice} 
    16151668 
    1616 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)