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

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
chap_DOM.tex in branches/2017/dev_merge_2017/DOC/texfiles/chapters – NEMO

source: branches/2017/dev_merge_2017/DOC/texfiles/chapters/chap_DOM.tex @ 9373

Last change on this file since 9373 was 9373, checked in by nicolasmartin, 6 years ago

Global reorganisation of DOC directory: files/folders renaming

File size: 52.4 KB
RevLine 
[6997]1\documentclass[NEMO_book]{subfiles}
2\begin{document}
[707]3% ================================================================
[6140]4% Chapter 2 ——— Space and Time Domain (DOM)
[707]5% ================================================================
[2282]6\chapter{Space Domain (DOM) }
[707]7\label{DOM}
8\minitoc
9
10% Missing things:
[817]11%  - istate: description of the initial state   ==> this has to be put elsewhere..
12%                  perhaps in MISC ?  By the way the initialisation of T S and dynamics
13%                  should be put outside of DOM routine (better with TRC staff and off-line
14%                  tracers)
[707]15%  -geo2ocean:  how to switch from geographic to mesh coordinate
[2282]16%     - domclo:  closed sea and lakes.... management of closea sea area : specific to global configuration, both forced and coupled
[707]17
18
[817]19\newpage
[7705]20$\ $\newline    % force a new line
[707]21
[2282]22Having defined the continuous equations in Chap.~\ref{PE} and chosen a time
23discretization Chap.~\ref{STP}, we need to choose a discretization on a grid,
24and numerical algorithms. In the present chapter, we provide a general description
25of the staggered grid used in \NEMO, and other information relevant to the main
26directory routines as well as the DOM (DOMain) directory.
[707]27
[7705]28$\ $\newline    % force a new line
[707]29
30% ================================================================
31% Fundamentals of the Discretisation
32% ================================================================
33\section{Fundamentals of the Discretisation}
34\label{DOM_basics}
35
36% -------------------------------------------------------------------------------------------------------------
37%        Arrangement of Variables
38% -------------------------------------------------------------------------------------------------------------
39\subsection{Arrangement of Variables}
40\label{DOM_cell}
41
42%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
[2376]43\begin{figure}[!tb]    \begin{center}
[6997]44\includegraphics[width=0.90\textwidth]{Fig_cell}
[9363]45\caption{ \protect\label{Fig_cell}   
[2376]46Arrangement of variables. $t$ indicates scalar points where temperature,
[817]47salinity, density, pressure and horizontal divergence are defined. ($u$,$v$,$w$)
48indicates vector points, and $f$ indicates vorticity points where both relative and
49planetary vorticities are defined}
[707]50\end{center}   \end{figure}
51%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
52
[817]53The numerical techniques used to solve the Primitive Equations in this model are
54based on the traditional, centred second-order finite difference approximation.
55Special attention has been given to the homogeneity of the solution in the three
56space directions. The arrangement of variables is the same in all directions.
[2282]57It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with vector
[817]58points $(u, v, w)$ defined in the centre of each face of the cells (Fig. \ref{Fig_cell}).
59This is the generalisation to three dimensions of the well-known ``C'' grid in
60Arakawa's classification \citep{Mesinger_Arakawa_Bk76}. The relative and
61planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge
62and the barotropic stream function $\psi$ is defined at horizontal points overlying
63the $\zeta$ and $f$-points.
[707]64
[817]65The ocean mesh ($i.e.$ the position of all the scalar and vector points) is defined
66by the transformation that gives ($\lambda$ ,$\varphi$ ,$z$) as a function of $(i,j,k)$.
67The grid-points are located at integer or integer and a half value of $(i,j,k)$ as
68indicated on Table \ref{Tab_cell}. In all the following, subscripts $u$, $v$, $w$,
69$f$, $uw$, $vw$ or $fw$ indicate the position of the grid-point where the scale
70factors are defined. Each scale factor is defined as the local analytical value
71provided by \eqref{Eq_scale_factors}. As a result, the mesh on which partial
72derivatives $\frac{\partial}{\partial \lambda}, \frac{\partial}{\partial \varphi}$, and
[1224]73$\frac{\partial}{\partial z} $ are evaluated is a uniform mesh with a grid size of unity.
74Discrete partial derivatives are formulated by the traditional, centred second order
[817]75finite difference approximation while the scale factors are chosen equal to their
76local analytical value. An important point here is that the partial derivative of the
77scale factors must be evaluated by centred finite difference approximation, not
78from their analytical expression. This preserves the symmetry of the discrete set
79of equations and therefore satisfies many of the continuous properties (see
80Appendix~\ref{Apdx_C}). A similar, related remark can be made about the domain
81size: when needed, an area, volume, or the total ocean depth must be evaluated
82as the sum of the relevant scale factors (see \eqref{DOM_bar}) in the next section).
[707]83
[2376]84%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
[3294]85\begin{table}[!tb]
[707]86\begin{center} \begin{tabular}{|p{46pt}|p{56pt}|p{56pt}|p{56pt}|}
87\hline
88&$i$     & $j$    & $k$     \\ \hline
89& $i+1/2$   & $j$    & $k$    \\ \hline
90& $i$    & $j+1/2$   & $k$    \\ \hline
91& $i$    & $j$    & $k+1/2$   \\ \hline
92& $i+1/2$   & $j+1/2$   & $k$    \\ \hline
93uw & $i+1/2$   & $j$    & $k+1/2$   \\ \hline
94vw & $i$    & $j+1/2$   & $k+1/2$   \\ \hline
95fw & $i+1/2$   & $j+1/2$   & $k+1/2$   \\ \hline
96\end{tabular}
[9363]97\caption{ \protect\label{Tab_cell}
[2376]98Location of grid-points as a function of integer or integer and a half value of the column,
99line or level. This indexing is only used for the writing of the semi-discrete equation.
100In the code, the indexing uses integer values only and has a reverse direction
101in the vertical (see \S\ref{DOM_Num_Index})}
[707]102\end{center}
103\end{table}
[2376]104%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
[707]105
106% -------------------------------------------------------------------------------------------------------------
107%        Vector Invariant Formulation
108% -------------------------------------------------------------------------------------------------------------
109\subsection{Discrete Operators}
110\label{DOM_operators}
111
[817]112Given the values of a variable $q$ at adjacent points, the differencing and
113averaging operators at the midpoint between them are:
[707]114\begin{subequations} \label{Eq_di_mi}
115\begin{align}
[817]116 \delta _i [q]       &\  \    q(i+1/2)  - q(i-1/2)    \\
117 \overline q^{\,i} &= \left\{ q(i+1/2) + q(i-1/2) \right\} \; / \; 2
[707]118\end{align}
119\end{subequations}
120
[817]121Similar operators are defined with respect to $i+1/2$, $j$, $j+1/2$, $k$, and
122$k+1/2$. Following \eqref{Eq_PE_grad} and \eqref{Eq_PE_lap}, the gradient of a
[2282]123variable $q$ defined at a $t$-point has its three components defined at $u$-, $v$-
124and $w$-points while its Laplacien is defined at $t$-point. These operators have
[817]125the following discrete forms in the curvilinear $s$-coordinate system:
[707]126\begin{equation} \label{Eq_DOM_grad}
[3294]127\nabla q\equiv    \frac{1}{e_{1u} } \delta _{i+1/2 } [q] \;\,\mathbf{i}
128      +  \frac{1}{e_{2v} } \delta _{j+1/2 } [q] \;\,\mathbf{j}
129      +  \frac{1}{e_{3w}} \delta _{k+1/2} [q] \;\,\mathbf{k}
[707]130\end{equation}
131\begin{multline} \label{Eq_DOM_lap}
[3294]132\Delta q\equiv \frac{1}{e_{1t}\,e_{2t}\,e_{3t} }
[2282]133       \;\left(          \delta_\left[ \frac{e_{2u}\,e_{3u}} {e_{1u}} \;\delta_{i+1/2} [q] \right]
134+                        \delta_\left[ \frac{e_{1v}\,e_{3v}}  {e_{2v}} \;\delta_{j+1/2} [q] \right] \;  \right)      \\
135+\frac{1}{e_{3t}} \delta_k \left[ \frac{1}{e_{3w} }                     \;\delta_{k+1/2} [q] \right]
[707]136\end{multline}
137
[2282]138Following \eqref{Eq_PE_curl} and \eqref{Eq_PE_div}, a vector ${\rm {\bf A}}=\left( a_1,a_2,a_3\right)$ 
139defined at vector points $(u,v,w)$ has its three curl components defined at $vw$-, $uw$,
140and $f$-points, and its divergence defined at $t$-points:
141\begin{eqnarray}  \label{Eq_DOM_curl}
[6289]142 \nabla \times {\rm{\bf A}}\equiv &
[3294]143      \frac{1}{e_{2v}\,e_{3vw} } \ \left( \delta_{j +1/2} \left[e_{3w}\,a_3 \right] -\delta_{k+1/2} \left[e_{2v} \,a_2 \right] \right&\ \mathbf{i} \\ 
144 +& \frac{1}{e_{2u}\,e_{3uw}} \ \left( \delta_{k+1/2} \left[e_{1u}\,a_1  \right] -\delta_{i +1/2} \left[e_{3w}\,a_3 \right] \right&\ \mathbf{j} \\
145 +& \frac{1}{e_{1f} \,e_{2f}    } \ \left( \delta_{i +1/2} \left[e_{2v}\,a_2  \right] -\delta_{j +1/2} \left[e_{1u}\,a_1 \right] \right&\ \mathbf{k}
[2282]146 \end{eqnarray}
[6289]147\begin{eqnarray} \label{Eq_DOM_div}
148\nabla \cdot \rm{\bf A} \equiv 
149    \frac{1}{e_{1t}\,e_{2t}\,e_{3t}} \left( \delta_i \left[e_{2u}\,e_{3u}\,a_1 \right]
150                                           +\delta_j \left[e_{1v}\,e_{3v}\,a_2 \right] \right)+\frac{1}{e_{3t} }\delta_k \left[a_3 \right]
151\end{eqnarray}
[707]152
[817]153The vertical average over the whole water column denoted by an overbar becomes
154for a quantity $q$ which is a masked field (i.e. equal to zero inside solid area):
[707]155\begin{equation} \label{DOM_bar}
[2282]156\bar q   =         \frac{1}{H}    \int_{k^b}^{k^o} {q\;e_{3q} \,dk} 
[707]157      \equiv \frac{1}{H_q }\sum\limits_k {q\;e_{3q} }
158\end{equation}
[817]159where $H_q$  is the ocean depth, which is the masked sum of the vertical scale
160factors at $q$ points, $k^b$ and $k^o$ are the bottom and surface $k$-indices,
161and the symbol $k^o$ refers to a summation over all grid points of the same type
162in the direction indicated by the subscript (here $k$).
[707]163
[817]164In continuous form, the following properties are satisfied:
[707]165\begin{equation} \label{Eq_DOM_curl_grad}
166\nabla \times \nabla q ={\rm {\bf {0}}}
167\end{equation}
168\begin{equation} \label{Eq_DOM_div_curl}
169\nabla \cdot \left( {\nabla \times {\rm {\bf A}}} \right)=0
170\end{equation}
171
[817]172It is straightforward to demonstrate that these properties are verified locally in
[2282]173discrete form as soon as the scalar $q$ is taken at $t$-points and the vector
[817]174\textbf{A} has its components defined at vector points $(u,v,w)$.
[707]175
[817]176Let $a$ and $b$ be two fields defined on the mesh, with value zero inside
177continental area. Using integration by parts it can be shown that the differencing
[6289]178operators ($\delta_i$, $\delta_j$ and $\delta_k$) are skew-symmetric linear operators,
179and further that the averaging operators $\overline{\,\cdot\,}^{\,i}$,
[817]180$\overline{\,\cdot\,}^{\,k}$ and $\overline{\,\cdot\,}^{\,k}$) are symmetric linear
181operators, $i.e.$
182\begin{align} 
183\label{DOM_di_adj}
184\sum\limits_i { a_i \;\delta _i \left[ b \right]} 
185   &\equiv -\sum\limits_i {\delta _{i+1/2} \left[ a \right]\;b_{i+1/2} }      \\
186\label{DOM_mi_adj}
187\sum\limits_i { a_i \;\overline b^{\,i}} 
188   & \equiv \quad \sum\limits_i {\overline a ^{\,i+1/2}\;b_{i+1/2} } 
189\end{align}
[707]190
[817]191In other words, the adjoint of the differencing and averaging operators are
192$\delta_i^*=\delta_{i+1/2}$ and
193${(\overline{\,\cdot \,}^{\,i})}^*= \overline{\,\cdot\,}^{\,i+1/2}$, respectively.
194These two properties will be used extensively in the Appendix~\ref{Apdx_C} to
[707]195demonstrate integral conservative properties of the discrete formulation chosen.
196
197% -------------------------------------------------------------------------------------------------------------
[817]198%        Numerical Indexing
[707]199% -------------------------------------------------------------------------------------------------------------
[817]200\subsection{Numerical Indexing}
[707]201\label{DOM_Num_Index}
202
203%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
[2376]204\begin{figure}[!tb]  \begin{center}
[6997]205\includegraphics[width=0.90\textwidth]{Fig_index_hor}
[9363]206\caption{   \protect\label{Fig_index_hor}   
[2376]207Horizontal integer indexing used in the \textsc{Fortran} code. The dashed area indicates
208the cell in which variables contained in arrays have the same $i$- and $j$-indices}
[707]209\end{center}   \end{figure}
210%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
211
[817]212The array representation used in the \textsc{Fortran} code requires an integer
213indexing while the analytical definition of the mesh (see \S\ref{DOM_cell}) is
[2282]214associated with the use of integer values for $t$-points and both integer and
[817]215integer and a half values for all the other points. Therefore a specific integer
[2282]216indexing must be defined for points other than $t$-points ($i.e.$ velocity and
[817]217vorticity grid-points). Furthermore, the direction of the vertical indexing has
218been changed so that the surface level is at $k=1$.
[707]219
220% -----------------------------------
[817]221%        Horizontal Indexing
[707]222% -----------------------------------
[817]223\subsubsection{Horizontal Indexing}
[707]224\label{DOM_Num_Index_hor}
225
[2282]226The indexing in the horizontal plane has been chosen as shown in Fig.\ref{Fig_index_hor}.
227For an increasing $i$ index ($j$ index), the $t$-point and the eastward $u$-point
228(northward $v$-point) have the same index (see the dashed area in Fig.\ref{Fig_index_hor}).
229A $t$-point and its nearest northeast $f$-point have the same $i$-and $j$-indices.
[707]230
231% -----------------------------------
[817]232%        Vertical indexing
[707]233% -----------------------------------
[817]234\subsubsection{Vertical Indexing}
[707]235\label{DOM_Num_Index_vertical}
236
[817]237In the vertical, the chosen indexing requires special attention since the
238$k$-axis is re-orientated downward in the \textsc{Fortran} code compared
239to the indexing used in the semi-discrete equations and given in \S\ref{DOM_cell}.
240The sea surface corresponds to the $w$-level $k=1$ which is the same index
[2282]241as $t$-level just below (Fig.\ref{Fig_index_vert}). The last $w$-level ($k=jpk$)
[817]242either corresponds to the ocean floor or is inside the bathymetry while the last
[2282]243$t$-level is always inside the bathymetry (Fig.\ref{Fig_index_vert}). Note that
244for an increasing $k$ index, a $w$-point and the $t$-point just below have the
[817]245same $k$ index, in opposition to what is done in the horizontal plane where
[2282]246it is the $t$-point and the nearest velocity points in the direction of the horizontal
[1224]247axis that have the same $i$ or $j$ index (compare the dashed area in
248Fig.\ref{Fig_index_hor} and \ref{Fig_index_vert}). Since the scale factors are
249chosen to be strictly positive, a \emph{minus sign} appears in the \textsc{Fortran} 
250code \emph{before all the vertical derivatives} of the discrete equations given in
251this documentation.
[707]252
253%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
[2376]254\begin{figure}[!pt]    \begin{center}
[6997]255\includegraphics[width=.90\textwidth]{Fig_index_vert}
[9363]256\caption{ \protect\label{Fig_index_vert}     
[2376]257Vertical integer indexing used in the \textsc{Fortran } code. Note that
[817]258the $k$-axis is orientated downward. The dashed area indicates the cell in
259which variables contained in arrays have the same $k$-index.}
[707]260\end{center}   \end{figure}
261%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
262
263% -----------------------------------
[817]264%        Domain Size
[707]265% -----------------------------------
[817]266\subsubsection{Domain Size}
[707]267\label{DOM_size}
268
[4147]269The total size of the computational domain is set by the parameters \np{jpiglo},
[9019]270\np{jpjglo} and \np{jpkglo} in the $i$, $j$ and $k$ directions respectively.
[7705]271%%%
272%%%
273%%%
274Parameters $jpi$ and $jpj$ refer to the size of each processor subdomain when the code is
275run in parallel using domain decomposition (\key{mpp\_mpi} defined, see \S\ref{LBC_mpp}).
[4147]276
[707]277
[7705]278$\ $\newline    % force a new line
[2282]279
[707]280% ================================================================
[7705]281% Domain: List of fields needed
282% ================================================================
283\section  [Domain: Needed fields]
284      {Domain: Needed fields}
285\label{DOM_fields}
286The ocean mesh ($i.e.$ the position of all the scalar and vector points) is defined
287by the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$.
288The grid-points are located at integer or integer and a half values of as indicated
289in Table~\ref{Tab_cell}. The associated scale factors are defined using the 
[9019]290analytical first derivative of the transformation \eqref{Eq_scale_factors}.
291Necessary fields for configuration definition are: \\
292Geographic position :
[7705]293
294longitude : glamt , glamu , glamv and glamf  (at T, U, V and F point)
295
[9019]296latitude : gphit , gphiu , gphiv and gphif (at T, U, V and F point)\\
297Coriolis parameter (if domain not on the sphere):
[7705]298
[9019]299 ff\_f  and  ff\_t (at T and F point)\\
300Scale factors :
301 
302 e1t, e1u, e1v and e1f (on i direction),
[7705]303
[9019]304 e2t, e2u, e2v and e2f (on j direction)
[7705]305
[9019]306 and ie1e2u\_v, e1e2u , e1e2v   
307 
308e1e2u , e1e2v are u and v surfaces (if gridsize reduction in some straits)\\
309ie1e2u\_v is a flag to flag set u and  v surfaces are neither read nor computed.\\
310 
311These fields can be read in an domain input file which name is setted in \np{cn\_domcfg} parameter specified in \ngn{namcfg}.
312\namdisplay{namcfg}
313or they can be defined in an analytical way in MY\_SRC directory of the configuration.
314For Reference Configurations of NEMO input domain files are supplied by NEMO System Team. For analytical definition of input fields two routines are supplied: \mdl{userdef\_hgr} and \mdl{userdef\_zgr}. They are an example of GYRE configuration parameters, and they are available in NEMO/OPA\_SRC/USR directory, they provide the horizontal and vertical mesh.
[7705]315% -------------------------------------------------------------------------------------------------------------
316%        Needed fields
317% -------------------------------------------------------------------------------------------------------------
318%\subsection{List of needed fields to build DOMAIN}
319%\label{DOM_fields_list}
320
321
322% ================================================================
[707]323% Domain: Horizontal Grid (mesh)
324% ================================================================
[817]325\section  [Domain: Horizontal Grid (mesh) (\textit{domhgr})]               
[9363]326      {Domain: Horizontal Grid (mesh) \small{(\protect\mdl{domhgr} module)} }
[707]327\label{DOM_hgr}
328
329% -------------------------------------------------------------------------------------------------------------
330%        Coordinates and scale factors
331% -------------------------------------------------------------------------------------------------------------
332\subsection{Coordinates and scale factors}
333\label{DOM_hgr_coord_e}
334
[817]335The ocean mesh ($i.e.$ the position of all the scalar and vector points) is defined
336by the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$.
337The grid-points are located at integer or integer and a half values of as indicated
338in Table~\ref{Tab_cell}. The associated scale factors are defined using the
339analytical first derivative of the transformation \eqref{Eq_scale_factors}. These
340definitions are done in two modules, \mdl{domhgr} and \mdl{domzgr}, which
341provide the horizontal and vertical meshes, respectively. This section deals with
342the horizontal mesh parameters.
[707]343
[817]344In a horizontal plane, the location of all the model grid points is defined from the
345analytical expressions of the longitude $\lambda$ and  latitude $\varphi$ as a
346function of  $(i,j)$. The horizontal scale factors are calculated using
347\eqref{Eq_scale_factors}. For example, when the longitude and latitude are
348function of a single value ($i$ and $j$, respectively) (geographical configuration
349of the mesh), the horizontal mesh definition reduces to define the wanted
350$\lambda(i)$, $\varphi(j)$, and their derivatives $\lambda'(i)$ $\varphi'(j)$ in the
351\mdl{domhgr} module. The model computes the grid-point positions and scale
352factors in the horizontal plane as follows:
[707]353\begin{flalign*}
[2282]354\lambda_t &\equiv \text{glamt}= \lambda(i)     & \varphi_t &\equiv \text{gphit} = \varphi(j)\\
[817]355\lambda_u &\equiv \text{glamu}= \lambda(i+1/2)& \varphi_u &\equiv \text{gphiu}= \varphi(j)\\
356\lambda_v &\equiv \text{glamv}= \lambda(i)       & \varphi_v &\equiv \text{gphiv} = \varphi(j+1/2)\\
357\lambda_f &\equiv \text{glamf }= \lambda(i+1/2)& \varphi_f &\equiv \text{gphif }= \varphi(j+1/2)
[707]358\end{flalign*}
359\begin{flalign*}
[2282]360e_{1t} &\equiv \text{e1t} = r_a |\lambda'(i)    \; \cos\varphi(j)  |&
361e_{2t} &\equiv \text{e2t} = r_a |\varphi'(j)|  \\
[707]362e_{1u} &\equiv \text{e1t} = r_a |\lambda'(i+1/2)   \; \cos\varphi(j)  |&
363e_{2u} &\equiv \text{e2t} = r_a |\varphi'(j)|\\
364e_{1v} &\equiv \text{e1t} = r_a |\lambda'(i)    \; \cos\varphi(j+1/2)  |&
365e_{2v} &\equiv \text{e2t} = r_a |\varphi'(j+1/2)|\\
366e_{1f} &\equiv \text{e1t} = r_a |\lambda'(i+1/2)\; \cos\varphi(j+1/2)  |&
367e_{2f} &\equiv \text{e2t} = r_a |\varphi'(j+1/2)|
368\end{flalign*}
[817]369where the last letter of each computational name indicates the grid point
370considered and $r_a$ is the earth radius (defined in \mdl{phycst} along with
371all universal constants). Note that the horizontal position of and scale factors
[2282]372at $w$-points are exactly equal to those of $t$-points, thus no specific arrays
[817]373are defined at $w$-points.
[707]374
[817]375Note that the definition of the scale factors ($i.e.$ as the analytical first derivative
376of the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$) is
[2282]377specific to the \NEMO model \citep{Marti_al_JGR92}. As an example, $e_{1t}$ is defined
378locally at a $t$-point, whereas many other models on a C grid choose to define
[817]379such a scale factor as the distance between the $U$-points on each side of the
[2282]380$t$-point. Relying on an analytical transformation has two advantages: firstly, there
[817]381is no ambiguity in the scale factors appearing in the discrete equations, since they
382are first introduced in the continuous equations; secondly, analytical transformations
383encourage good practice by the definition of smoothly varying grids (rather than
384allowing the user to set arbitrary jumps in thickness between adjacent layers)
385\citep{Treguier1996}. An example of the effect of such a choice is shown in
386Fig.~\ref{Fig_zgr_e3}.
[707]387%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
[2376]388\begin{figure}[!t]     \begin{center}
[6997]389\includegraphics[width=0.90\textwidth]{Fig_zgr_e3}
[9363]390\caption{ \protect\label{Fig_zgr_e3}   
[2376]391Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical,
392and (b) analytically derived grid-point position and scale factors.
393For both grids here,  the same $w$-point depth has been chosen but in (a) the
[2282]394$t$-points are set half way between $w$-points while in (b) they are defined from
[6140]395an analytical function: $z(k)=5\,(k-1/2)^3 - 45\,(k-1/2)^2 + 140\,(k-1/2) - 150$.
[817]396Note the resulting difference between the value of the grid-size $\Delta_k$ and
397those of the scale factor $e_k$. }
[707]398\end{center}   \end{figure}
399%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
400
401% -------------------------------------------------------------------------------------------------------------
[817]402%        Choice of horizontal grid
[707]403% -------------------------------------------------------------------------------------------------------------
[817]404\subsection{Choice of horizontal grid}
[707]405\label{DOM_hgr_msh_choice}
406
407
408% -------------------------------------------------------------------------------------------------------------
409%        Grid files
410% -------------------------------------------------------------------------------------------------------------
[2282]411\subsection{Output Grid files}
[707]412\label{DOM_hgr_files}
413
[817]414All the arrays relating to a particular ocean model configuration (grid-point
[2282]415position, scale factors, masks) can be saved in files if $\np{nn\_msh} \not= 0$ 
[4147]416(namelist variable in \ngn{namdom}). This can be particularly useful for plots and off-line
[817]417diagnostics. In some cases, the user may choose to make a local modification
418of a scale factor in the code. This is the case in global configurations when
419restricting the width of a specific strait (usually a one-grid-point strait that
420happens to be too wide due to insufficient model resolution). An example
421is Gibraltar Strait in the ORCA2 configuration. When such modifications are done,
[2282]422the output grid written when $\np{nn\_msh} \not=0$ is no more equal to the input grid.
[707]423
[7705]424$\ $\newline    % force a new line
[2282]425
[707]426% ================================================================
427% Domain: Vertical Grid (domzgr)
428% ================================================================
[817]429\section  [Domain: Vertical Grid (\textit{domzgr})]
[9363]430      {Domain: Vertical Grid \small{(\protect\mdl{domzgr} module)} }
[707]431\label{DOM_zgr}
432%-----------------------------------------nam_zgr & namdom-------------------------------------------
[2282]433\namdisplay{namzgr} 
[707]434\namdisplay{namdom} 
435%-------------------------------------------------------------------------------------------------------------
436
[4147]437Variables are defined through the \ngn{namzgr} and \ngn{namdom} namelists.
[817]438In the vertical, the model mesh is determined by four things:
439(1) the bathymetry given in meters ;
440(2) the number of levels of the model (\jp{jpk}) ;
441(3) the analytical transformation $z(i,j,k)$ and the vertical scale factors
442(derivatives of the transformation) ;
443and (4) the masking system, $i.e.$ the number of wet model levels at each
444$(i,j)$ column of points.
[707]445
446%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
[2376]447\begin{figure}[!tb]    \begin{center}
[6997]448\includegraphics[width=1.0\textwidth]{Fig_z_zps_s_sps}
[9363]449\caption{  \protect\label{Fig_z_zps_s_sps}   
[2376]450The ocean bottom as seen by the model:
[817]451(a) $z$-coordinate with full step,
452(b) $z$-coordinate with partial step,
453(c) $s$-coordinate: terrain following representation,
454(d) hybrid $s-z$ coordinate,
455(e) hybrid $s-z$ coordinate with partial step, and
[9363]456(f) same as (e) but in the non-linear free surface (\protect\np{ln\_linssh}=false).
[6140]457Note that the non-linear free surface can be used with any of the
[817]4585 coordinates (a) to (e).}
[707]459\end{center}   \end{figure}
460%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
461
[6140]462The choice of a vertical coordinate, even if it is made through \ngn{namzgr} namelist parameters,
[817]463must be done once of all at the beginning of an experiment. It is not intended as an
464option which can be enabled or disabled in the middle of an experiment. Three main
465choices are offered (Fig.~\ref{Fig_z_zps_s_sps}a to c): $z$-coordinate with full step
[2349]466bathymetry (\np{ln\_zco}~=~true), $z$-coordinate with partial step bathymetry
467(\np{ln\_zps}~=~true), or generalized, $s$-coordinate (\np{ln\_sco}~=~true).
[817]468Hybridation of the three main coordinates are available: $s-z$ or $s-zps$ coordinate
[6140]469(Fig.~\ref{Fig_z_zps_s_sps}d and \ref{Fig_z_zps_s_sps}e). By default a non-linear free surface is used:
470the coordinate follow the time-variation of the free surface so that the transformation is time dependent:
471$z(i,j,k,t)$ (Fig.~\ref{Fig_z_zps_s_sps}f). When a linear free surface is assumed (\np{ln\_linssh}=true),
472the vertical coordinate are fixed in time, but the seawater can move up and down across the z=0 surface
473(in other words, the top of the ocean in not a rigid-lid).
474The last choice in terms of vertical coordinate concerns the presence (or not) in the model domain
475of ocean cavities beneath ice shelves. Setting \np{ln\_isfcav} to true allows to manage ocean cavities,
[6497]476otherwise they are filled in. This option is currently only available in $z$- or $zps$-coordinate,
477and partial step are also applied at the ocean/ice shelf interface.
[707]478
[817]479Contrary to the horizontal grid, the vertical grid is computed in the code and no
480provision is made for reading it from a file. The only input file is the bathymetry
[6140]481(in meters) (\ifile{bathy\_meter}).
[2282]482\footnote{N.B. in full step $z$-coordinate, a \ifile{bathy\_level} file can replace the
483\ifile{bathy\_meter} file, so that the computation of the number of wet ocean point
484in each water column is by-passed}.
[6140]485If \np{ln\_isfcav}~=~true, an extra file input file describing the ice shelf draft
[6320]486(in meters) (\ifile{isf\_draft\_meter}) is needed.
[6140]487
[2282]488After reading the bathymetry, the algorithm for vertical grid definition differs
489between the different options:
[707]490\begin{description}
491\item[\textit{zco}] set a reference coordinate transformation $z_0 (k)$, and set $z(i,j,k,t)=z_0 (k)$.
492\item[\textit{zps}] set a reference coordinate transformation $z_0 (k)$, and
[817]493calculate the thickness of the deepest level at each $(i,j)$ point using the
494bathymetry, to obtain the final three-dimensional depth and scale factor arrays.
495\item[\textit{sco}] smooth the bathymetry to fulfil the hydrostatic consistency
496criteria and set the three-dimensional transformation.
497\item[\textit{s-z} and \textit{s-zps}] smooth the bathymetry to fulfil the hydrostatic
498consistency criteria and set the three-dimensional transformation $z(i,j,k)$, and
499possibly introduce masking of extra land points to better fit the original bathymetry file
[707]500\end{description}
[817]501%%%
502\gmcomment{   add the description of the smoothing:  envelop topography...}
503%%%
[707]504
[6140]505Unless a linear free surface is used (\np{ln\_linssh}=false), the arrays describing
506the grid point depths and vertical scale factors are three set of three dimensional arrays $(i,j,k)$ 
507defined at \textit{before}, \textit{now} and \textit{after} time step. The time at which they are
508defined is indicated by a suffix:$\_b$, $\_n$, or $\_a$, respectively. They are updated at each model time step
509using a fixed reference coordinate system which computer names have a $\_0$ suffix.
510When the linear free surface option is used (\np{ln\_linssh}=true), \textit{before}, \textit{now} 
511and \textit{after} arrays are simply set one for all to their reference counterpart.
[707]512
[6140]513
[707]514% -------------------------------------------------------------------------------------------------------------
515%        Meter Bathymetry
516% -------------------------------------------------------------------------------------------------------------
517\subsection{Meter Bathymetry}
518\label{DOM_bathy}
519
520Three options are possible for defining the bathymetry, according to the
[6289]521namelist variable \np{nn\_bathy} (found in \ngn{namdom} namelist):
[707]522\begin{description}
[2282]523\item[\np{nn\_bathy} = 0] a flat-bottom domain is defined. The total depth $z_w (jpk)$ 
[817]524is given by the coordinate transformation. The domain can either be a closed
[4147]525basin or a periodic channel depending on the parameter \np{jperio}.
[2282]526\item[\np{nn\_bathy} = -1] a domain with a bump of topography one third of the
[817]527domain width at the central latitude. This is meant for the "EEL-R5" configuration,
528a periodic or open boundary channel with a seamount.
[6320]529\item[\np{nn\_bathy} = 1] read a bathymetry and ice shelf draft (if needed).
530 The \ifile{bathy\_meter} file (Netcdf format) provides the ocean depth (positive, in meters)
531 at each grid point of the model grid. The bathymetry is usually built by interpolating a standard bathymetry product
[817]532($e.g.$ ETOPO2) onto the horizontal ocean mesh. Defining the bathymetry also
533defines the coastline: where the bathymetry is zero, no model levels are defined
534(all levels are masked).
[6320]535
536The \ifile{isfdraft\_meter} file (Netcdf format) provides the ice shelf draft (positive, in meters)
537 at each grid point of the model grid. This file is only needed if \np{ln\_isfcav}~=~true.
538Defining the ice shelf draft will also define the ice shelf edge and the grounding line position.
[707]539\end{description}
540
[817]541When a global ocean is coupled to an atmospheric model it is better to represent
[707]542all large water bodies (e.g, great lakes, Caspian sea...) even if the model
[817]543resolution does not allow their communication with the rest of the ocean.
544This is unnecessary when the ocean is forced by fixed atmospheric conditions,
545so these seas can be removed from the ocean domain. The user has the option
546to set the bathymetry in closed seas to zero (see \S\ref{MISC_closea}), but the
547code has to be adapted to the user's configuration.
[707]548
549% -------------------------------------------------------------------------------------------------------------
550%        z-coordinate  and reference coordinate transformation
551% -------------------------------------------------------------------------------------------------------------
[9363]552\subsection[$z$-coordinate (\protect\np{ln\_zco}]
553        {$z$-coordinate (\protect\np{ln\_zco}=true) and reference coordinate}
[707]554\label{DOM_zco}
555
556%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
[2376]557\begin{figure}[!tb]    \begin{center}
[6997]558\includegraphics[width=0.90\textwidth]{Fig_zgr}
[9363]559\caption{ \protect\label{Fig_zgr}   
[2376]560Default vertical mesh for ORCA2: 30 ocean levels (L30). Vertical level functions for
561(a) T-point depth and (b) the associated scale factor as computed
[817]562from \eqref{DOM_zgr_ana} using \eqref{DOM_zgr_coef} in $z$-coordinate.}
[707]563\end{center}   \end{figure}
564%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
565
[817]566The reference coordinate transformation $z_0 (k)$ defines the arrays $gdept_0$ 
[2282]567and $gdepw_0$ for $t$- and $w$-points, respectively. As indicated on
[817]568Fig.\ref{Fig_index_vert} \jp{jpk} is the number of $w$-levels. $gdepw_0(1)$ is the
[2282]569ocean surface. There are at most \jp{jpk}-1 $t$-points inside the ocean, the
570additional $t$-point at $jk=jpk$ is below the sea floor and is not used.
571The vertical location of $w$- and $t$-levels is defined from the analytic expression
[817]572of the depth $z_0(k)$ whose analytical derivative with respect to $k$ provides the
573vertical scale factors. The user must provide the analytical expression of both
574$z_0$ and its first derivative with respect to $k$. This is done in routine \mdl{domzgr} 
[4147]575through statement functions, using parameters provided in the \ngn{namcfg} namelist.
[707]576
[4147]577It is possible to define a simple regular vertical grid by giving zero stretching (\np{ppacr=0}).
578In that case, the parameters \jp{jpk} (number of $w$-levels) and \np{pphmax} 
[1224]579(total ocean depth in meters) fully define the grid.
[707]580
[817]581For climate-related studies it is often desirable to concentrate the vertical resolution
[1224]582near the ocean surface. The following function is proposed as a standard for a
583$z$-coordinate (with either full or partial steps):
[707]584\begin{equation} \label{DOM_zgr_ana}
585\begin{split}
586 z_0 (k)    &= h_{sur} -h_0 \;k-\;h_1 \;\log \left[ {\,\cosh \left( {{(k-h_{th} )} / {h_{cr} }} \right)\,} \right] \\ 
587 e_3^0 (k)  &= \left| -h_0 -h_1 \;\tanh \left( {{(k-h_{th} )} / {h_{cr} }} \right) \right|
588\end{split}
589\end{equation}
[817]590where $k=1$ to \jp{jpk} for $w$-levels and $k=1$ to $k=1$ for $T-$levels. Such an
591expression allows us to define a nearly uniform vertical location of levels at the
592ocean top and bottom with a smooth hyperbolic tangent transition in between
593(Fig.~\ref{Fig_zgr}).
[707]594
[9019]595If the ice shelf cavities are opened (\np{ln\_isfcav}=~true~), the definition of $z_0$ is the same.
[6320]596However, definition of $e_3^0$ at $t$- and $w$-points is respectively changed to:
597\begin{equation} \label{DOM_zgr_ana}
598\begin{split}
599 e_3^T(k) &= z_W (k+1) - z_W (k)   \\
600 e_3^W(k) &= z_T (k)   - z_T (k-1) \\
601\end{split}
602\end{equation}
603This formulation decrease the self-generated circulation into the ice shelf cavity
604(which can, in extreme case, leads to blow up).\\
605
606 
[817]607The most used vertical grid for ORCA2 has $10~m$ ($500~m)$ resolution in the
608surface (bottom) layers and a depth which varies from 0 at the sea surface to a
609minimum of $-5000~m$. This leads to the following conditions:
[707]610\begin{equation} \label{DOM_zgr_coef}
611\begin{split}
612 e_3 (1+1/2)      &=10. \\ 
613 e_3 (jpk-1/2) &=500. \\ 
614 z(1)       &=0. \\ 
615 z(jpk)        &=-5000. \\ 
616\end{split}
617\end{equation}
618
[817]619With the choice of the stretching $h_{cr} =3$ and the number of levels
620\jp{jpk}=$31$, the four coefficients $h_{sur}$, $h_{0}$, $h_{1}$, and $h_{th}$ in
621\eqref{DOM_zgr_ana} have been determined such that \eqref{DOM_zgr_coef} is
622satisfied, through an optimisation procedure using a bisection method. For the first
623standard ORCA2 vertical grid this led to the following values: $h_{sur} =4762.96$,
624$h_0 =255.58, h_1 =245.5813$, and $h_{th} =21.43336$. The resulting depths and
625scale factors as a function of the model levels are shown in Fig.~\ref{Fig_zgr} and
626given in Table \ref{Tab_orca_zgr}. Those values correspond to the parameters
[4147]627\np{ppsur}, \np{ppa0}, \np{ppa1}, \np{ppkth} in \ngn{namcfg} namelist.
[707]628
629Rather than entering parameters $h_{sur}$, $h_{0}$, and $h_{1}$ directly, it is
630possible to recalculate them. In that case the user sets
[4147]631\np{ppsur}=\np{ppa0}=\np{ppa1}=999999., in \ngn{namcfg} namelist,
[817]632and specifies instead the four following parameters:
[707]633\begin{itemize}
[4147]634\item    \np{ppacr}=$h_{cr} $: stretching factor (nondimensional). The larger
635\np{ppacr}, the smaller the stretching. Values from $3$ to $10$ are usual.
636\item    \np{ppkth}=$h_{th} $: is approximately the model level at which maximum
[817]637stretching occurs (nondimensional, usually of order 1/2 or 2/3 of \jp{jpk})
[4147]638\item    \np{ppdzmin}: minimum thickness for the top layer (in meters)
639\item    \np{pphmax}: total depth of the ocean (meters).
[707]640\end{itemize}
[817]641As an example, for the $45$ layers used in the DRAKKAR configuration those
[4147]642parameters are: \jp{jpk}=46, \np{ppacr}=9, \np{ppkth}=23.563, \np{ppdzmin}=6m,
643\np{pphmax}=5750m.
[707]644
645%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
[2376]646\begin{table}     \begin{center} \begin{tabular}{c||r|r|r|r}
[707]647\hline
[9019]648\textbf{LEVEL}& \textbf{gdept\_1d}& \textbf{gdepw\_1d}& \textbf{e3t\_1d }& \textbf{e3w\_1d  } \\ \hline
[707]649&  \textbf{  5.00}   &       0.00 & \textbf{ 10.00} &  10.00 \\   \hline
650&  \textbf{15.00} &    10.00 &   \textbf{ 10.00} &  10.00 \\   \hline
651&  \textbf{25.00} &    20.00 &   \textbf{ 10.00} &     10.00 \\   \hline
652&  \textbf{35.01} &    30.00 &   \textbf{ 10.01} &     10.00 \\   \hline
653&  \textbf{45.01} &    40.01 &   \textbf{ 10.01} &  10.01 \\   \hline
654&  \textbf{55.03} &    50.02 &   \textbf{ 10.02} &     10.02 \\   \hline
655&  \textbf{65.06} &    60.04 &   \textbf{ 10.04} &  10.03 \\   \hline
656&  \textbf{75.13} &    70.09 &   \textbf{ 10.09} &  10.06 \\   \hline
657&  \textbf{85.25} &    80.18 &   \textbf{ 10.17} &  10.12 \\   \hline
65810 &  \textbf{95.49} &    90.35 &   \textbf{ 10.33} &  10.24 \\   \hline
65911 &  \textbf{105.97}   &   100.69 &   \textbf{ 10.65} &  10.47 \\   \hline
66012 &  \textbf{116.90}   &   111.36 &   \textbf{ 11.27} &  10.91 \\   \hline
66113 &  \textbf{128.70}   &   122.65 &   \textbf{ 12.47} &  11.77 \\   \hline
66214 &  \textbf{142.20}   &   135.16 &   \textbf{ 14.78} &  13.43 \\   \hline
66315 &  \textbf{158.96}   &   150.03 &   \textbf{ 19.23} &  16.65 \\   \hline
66416 &  \textbf{181.96}   &   169.42 &   \textbf{ 27.66} &  22.78 \\   \hline
66517 &  \textbf{216.65}   &   197.37 &   \textbf{ 43.26} &  34.30 \\ \hline
66618 &  \textbf{272.48}   &   241.13 &   \textbf{ 70.88} &  55.21 \\ \hline
66719 &  \textbf{364.30}   &   312.74 &   \textbf{116.11} &  90.99 \\ \hline
66820 &  \textbf{511.53}   &   429.72 &   \textbf{181.55} &    146.43 \\ \hline
66921 &  \textbf{732.20}   &   611.89 &   \textbf{261.03} &    220.35 \\ \hline
67022 &  \textbf{1033.22}&  872.87 &   \textbf{339.39} &    301.42 \\ \hline
[817]67123 &  \textbf{1405.70}& 1211.59 & \textbf{402.26} &   373.31 \\ \hline
67224 &  \textbf{1830.89}& 1612.98 & \textbf{444.87} &   426.00 \\ \hline
67325 &  \textbf{2289.77}& 2057.13 & \textbf{470.55} &   459.47 \\ \hline
67426 &  \textbf{2768.24}& 2527.22 & \textbf{484.95} &   478.83 \\ \hline
67527 &  \textbf{3257.48}& 3011.90 & \textbf{492.70} &   489.44 \\ \hline
67628 &  \textbf{3752.44}& 3504.46 & \textbf{496.78} &   495.07 \\ \hline
67729 &  \textbf{4250.40}& 4001.16 & \textbf{498.90} &   498.02 \\ \hline
67830 &  \textbf{4749.91}& 4500.02 & \textbf{500.00} &   499.54 \\ \hline
[707]67931 &  \textbf{5250.23}& 5000.00 &   \textbf{500.56} & 500.33 \\ \hline
680\end{tabular} \end{center} 
[9363]681\caption{ \protect\label{Tab_orca_zgr}   
[2376]682Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration as computed
683from \eqref{DOM_zgr_ana} using the coefficients given in \eqref{DOM_zgr_coef}}
[707]684\end{table}
685%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
686
687% -------------------------------------------------------------------------------------------------------------
688%        z-coordinate with partial step
689% -------------------------------------------------------------------------------------------------------------
[9363]690\subsection   [$z$-coordinate with partial step (\protect\np{ln\_zps})]
691         {$z$-coordinate with partial step (\protect\np{ln\_zps}=.true.)}
[707]692\label{DOM_zps}
[817]693%--------------------------------------------namdom-------------------------------------------------------
[707]694\namdisplay{namdom} 
695%--------------------------------------------------------------------------------------------------------------
696
[817]697In $z$-coordinate partial step, the depths of the model levels are defined by the
[707]698reference analytical function $z_0 (k)$ as described in the previous
[817]699section, \emph{except} in the bottom layer. The thickness of the bottom layer is
[707]700allowed to vary as a function of geographical location $(\lambda,\varphi)$ to allow a
701better representation of the bathymetry, especially in the case of small
702slopes (where the bathymetry varies by less than one level thickness from
703one grid point to the next). The reference layer thicknesses $e_{3t}^0$ have been
704defined in the absence of bathymetry. With partial steps, layers from 1 to
[1224]705\jp{jpk}-2 can have a thickness smaller than $e_{3t}(jk)$. The model deepest layer (\jp{jpk}-1)
706is allowed to have either a smaller or larger thickness than $e_{3t}(jpk)$: the
[707]707maximum thickness allowed is $2*e_{3t}(jpk-1)$. This has to be kept in mind when
[4147]708specifying values in \ngn{namdom} namelist, as the maximum depth \np{pphmax} 
709in partial steps: for example, with
710\np{pphmax}$=5750~m$ for the DRAKKAR 45 layer grid, the maximum ocean depth
[1224]711allowed is actually $6000~m$ (the default thickness $e_{3t}(jpk-1)$ being $250~m$).
712Two variables in the namdom namelist are used to define the partial step
[707]713vertical grid. The mimimum water thickness (in meters) allowed for a cell
[2282]714partially filled with bathymetry at level jk is the minimum of \np{rn\_e3zps\_min} 
715(thickness in meters, usually $20~m$) or $e_{3t}(jk)*\np{rn\_e3zps\_rat}$ (a fraction,
[707]716usually 10\%, of the default thickness $e_{3t}(jk)$).
717
[6289]718\gmcomment{ \colorbox{yellow}{Add a figure here of pstep especially at last ocean level }  }
[707]719
720% -------------------------------------------------------------------------------------------------------------
721%        s-coordinate
722% -------------------------------------------------------------------------------------------------------------
[9363]723\subsection   [$s$-coordinate (\protect\np{ln\_sco})]
724           {$s$-coordinate (\protect\np{ln\_sco}=true)}
[707]725\label{DOM_sco}
[817]726%------------------------------------------nam_zgr_sco---------------------------------------------------
[2282]727\namdisplay{namzgr_sco} 
[707]728%--------------------------------------------------------------------------------------------------------------
[4147]729Options are defined in \ngn{namzgr\_sco}.
[2349]730In $s$-coordinate (\np{ln\_sco}~=~true), the depth and thickness of the model
[817]731levels are defined from the product of a depth field and either a stretching
732function or its derivative, respectively:
[3680]733
[707]734\begin{equation} \label{DOM_sco_ana}
735\begin{split}
[817]736 z(k)       &= h(i,j) \; z_0(k)  \\
[707]737 e_3(k)  &= h(i,j) \; z_0'(k)
738\end{split}
739\end{equation}
[3680]740
[2282]741where $h$ is the depth of the last $w$-level ($z_0(k)$) defined at the $t$-point
[817]742location in the horizontal and $z_0(k)$ is a function which varies from $0$ at the sea
[707]743surface to $1$ at the ocean bottom. The depth field $h$ is not necessary the ocean
[817]744depth, since a mixed step-like and bottom-following representation of the
[3680]745topography can be used (Fig.~\ref{Fig_z_zps_s_sps}d-e) or an envelop bathymetry can be defined (Fig.~\ref{Fig_z_zps_s_sps}f).
[6289]746The namelist parameter \np{rn\_rmax} determines the slope at which the terrain-following coordinate intersects
747the sea bed and becomes a pseudo z-coordinate.
748The coordinate can also be hybridised by specifying \np{rn\_sbot\_min} and \np{rn\_sbot\_max} 
749as the minimum and maximum depths at which the terrain-following vertical coordinate is calculated.
[707]750
[6289]751Options for stretching the coordinate are provided as examples, but care must be taken to ensure
752that the vertical stretch used is appropriate for the application.
[3680]753
[6289]754The original default NEMO s-coordinate stretching is available if neither of the other options
755are specified as true (\np{ln\_s\_SH94}~=~false and \np{ln\_s\_SF12}~=~false).
756This uses a depth independent $\tanh$ function for the stretching \citep{Madec_al_JPO96}:
[3680]757
758\begin{equation}
759  z = s_{min}+C\left(s\right)\left(H-s_{min}\right)
760  \label{eq:SH94_1}
761\end{equation}
762
[6497]763where $s_{min}$ is the depth at which the $s$-coordinate stretching starts and
764allows a $z$-coordinate to placed on top of the stretched coordinate,
765and $z$ is the depth (negative down from the asea surface).
[3680]766
767\begin{equation}
768  s = -\frac{k}{n-1} \quad \text{ and } \quad 0 \leq k \leq n-1
769  \label{eq:s}
770\end{equation}
771
[707]772\begin{equation} \label{DOM_sco_function}
773\begin{split}
[3680]774C(s)  &\frac{ \left[   \tanh{ \left( \theta \, (s+b) \right)} 
[707]775               - \tanh{ \left\theta \, b      \right)}  \right]}
776            {2\;\sinh \left( \theta \right)}
777\end{split}
778\end{equation}
779
[6289]780A stretching function, modified from the commonly used \citet{Song_Haidvogel_JCP94} 
781stretching (\np{ln\_s\_SH94}~=~true), is also available and is more commonly used for shelf seas modelling:
[3680]782
783\begin{equation}
784  C\left(s\right) =   \left(1 - b \right)\frac{ \sinh\left( \theta s\right)}{\sinh\left(\theta\right)} +      \\
785  b\frac{ \tanh \left[ \theta \left(s + \frac{1}{2} \right)\right] - \tanh\left(\frac{\theta}{2}\right)}{ 2\tanh\left (\frac{\theta}{2}\right)}
786  \label{eq:SH94_2}
787\end{equation}
788
[707]789%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
[3680]790\begin{figure}[!ht]    \begin{center}
[6997]791\includegraphics[width=1.0\textwidth]{Fig_sco_function}
[9363]792\caption{  \protect\label{Fig_sco_function}   
[3680]793Examples of the stretching function applied to a seamount; from left to right:
[1224]794surface, surface and bottom, and bottom intensified resolutions}
[707]795\end{center}   \end{figure}
796%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
797
[6289]798where $H_c$ is the critical depth (\np{rn\_hc}) at which the coordinate transitions from
799pure $\sigma$ to the stretched coordinate,  and $\theta$ (\np{rn\_theta}) and $b$ (\np{rn\_bb})
800are the surface and bottom control parameters such that $0\leqslant \theta \leqslant 20$, and
[3680]801$0\leqslant b\leqslant 1$. $b$ has been designed to allow surface and/or bottom
802increase of the vertical resolution (Fig.~\ref{Fig_sco_function}).
803
[6289]804Another example has been provided at version 3.5 (\np{ln\_s\_SF12}) that allows
805a fixed surface resolution in an analytical terrain-following stretching \citet{Siddorn_Furner_OM12}.
806In this case the a stretching function $\gamma$ is defined such that:
[3680]807
808\begin{equation}
809z = -\gamma h \quad \text{ with } \quad 0 \leq \gamma \leq 1
810\label{eq:z}
811\end{equation}
812
813The function is defined with respect to $\sigma$, the unstretched terrain-following coordinate:
814
815\begin{equation} \label{DOM_gamma_deriv}
816\gamma= A\left(\sigma-\frac{1}{2}\left(\sigma^{2}+f\left(\sigma\right)\right)\right)+B\left(\sigma^{3}-f\left(\sigma\right)\right)+f\left(\sigma\right)
817\end{equation}
818
819Where:
820\begin{equation} \label{DOM_gamma}
821f\left(\sigma\right)=\left(\alpha+2\right)\sigma^{\alpha+1}-\left(\alpha+1\right)\sigma^{\alpha+2} \quad \text{ and } \quad \sigma = \frac{k}{n-1} 
822\end{equation}
823
[6289]824This gives an analytical stretching of $\sigma$ that is solvable in $A$ and $B$ as a function of
825the user prescribed stretching parameter $\alpha$ (\np{rn\_alpha}) that stretches towards
826the surface ($\alpha > 1.0$) or the bottom ($\alpha < 1.0$) and user prescribed surface (\np{rn\_zs})
827and bottom depths. The bottom cell depth in this example is given as a function of water depth:
[3680]828
829\begin{equation} \label{DOM_zb}
830Z_b= h a + b
831\end{equation}
832
833where the namelist parameters \np{rn\_zb\_a} and \np{rn\_zb\_b} are $a$ and $b$ respectively.
834
835%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
836\begin{figure}[!ht]
[6997]837   \includegraphics[width=1.0\textwidth]{FIG_DOM_compare_coordinates_surface}
[3680]838        \caption{A comparison of the \citet{Song_Haidvogel_JCP94} $S$-coordinate (solid lines), a 50 level $Z$-coordinate (contoured surfaces) and the \citet{Siddorn_Furner_OM12} $S$-coordinate (dashed lines) in the surface 100m for a idealised bathymetry that goes from 50m to 5500m depth. For clarity every third coordinate surface is shown.}
839    \label{fig_compare_coordinates_surface}
840\end{figure}
841%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
842
843This gives a smooth analytical stretching in computational space that is constrained to given specified surface and bottom grid cell thicknesses in real space. This is not to be confused with the hybrid schemes that superimpose geopotential coordinates on terrain following coordinates thus creating a non-analytical vertical coordinate that therefore may suffer from large gradients in the vertical resolutions. This stretching is less straightforward to implement than the \citet{Song_Haidvogel_JCP94} stretching, but has the advantage of resolving diurnal processes in deep water and has generally flatter slopes.
844
845As with the \citet{Song_Haidvogel_JCP94} stretching the stretch is only applied at depths greater than the critical depth $h_c$. In this example two options are available in depths shallower than $h_c$, with pure sigma being applied if the \np{ln\_sigcrit} is true and pure z-coordinates if it is false (the z-coordinate being equal to the depths of the stretched coordinate at $h_c$.
846
847Minimising the horizontal slope of the vertical coordinate is important in terrain-following systems as large slopes lead to hydrostatic consistency. A hydrostatic consistency parameter diagnostic following \citet{Haney1991} has been implemented, and is output as part of the model mesh file at the start of the run.
848
[707]849% -------------------------------------------------------------------------------------------------------------
850%        z*- or s*-coordinate
851% -------------------------------------------------------------------------------------------------------------
[9363]852\subsection{$z^*$- or $s^*$-coordinate (\protect\np{ln\_linssh}=false) }
[6140]853\label{DOM_zgr_star}
[707]854
[6289]855This option is described in the Report by Levier \textit{et al.} (2007), available on the \NEMO web site.
[707]856
857%gm% key advantage: minimise the diffusion/dispertion associated with advection in response to high frequency surface disturbances
858
859% -------------------------------------------------------------------------------------------------------------
860%        level bathymetry and mask
861% -------------------------------------------------------------------------------------------------------------
862\subsection{level bathymetry and mask}
863\label{DOM_msk}
864
865Whatever the vertical coordinate used, the model offers the possibility of
866representing the bottom topography with steps that follow the face of the
[2282]867model cells (step like topography) \citep{Madec_al_JPO96}. The distribution of
[707]868the steps in the horizontal is defined in a 2D integer array, mbathy, which
869gives the number of ocean levels ($i.e.$ those that are not masked) at each
[2282]870$t$-point. mbathy is computed from the meter bathymetry using the definiton of
[6320]871gdept as the number of $t$-points which gdept $\leq$ bathy.
[707]872
873Modifications of the model bathymetry are performed in the \textit{bat\_ctl} 
[817]874routine (see \mdl{domzgr} module) after mbathy is computed. Isolated grid points
875that do not communicate with another ocean point at the same level are eliminated.
[707]876
[6497]877As for the representation of bathymetry, a 2D integer array, misfdep, is created.
878misfdep defines the level of the first wet $t$-point. All the cells between $k=1$ and $misfdep(i,j)-1$ are masked.
879By default, misfdep(:,:)=1 and no cells are masked.
880
881In case of ice shelf cavities, modifications of the model bathymetry and ice shelf draft into
[6320]882the cavities are performed in the \textit{zgr\_isf} routine. The compatibility between ice shelf draft and bathymetry is checked.
883All the locations where the isf cavity is thinnest than \np{rn\_isfhmin} meters are grounded ($i.e.$ masked).
884If only one cell on the water column is opened at $t$-, $u$- or $v$-points, the bathymetry or the ice shelf draft is dug to fit this constrain.
885If the incompatibility is too strong (need to dig more than 1 cell), the cell is masked.\\ 
886
887From the \textit{mbathy} and \textit{misfdep} array, the mask fields are defined as follows:
[707]888\begin{align*}
[6320]889tmask(i,j,k) &= \begin{cases}   \; 0&   \text{ if $k < misfdep(i,j) $ } \\
890                                \; 1&   \text{ if $misfdep(i,j) \leq k\leq mbathy(i,j)$  }    \\
891                                \; 0&   \text{ if $k > mbathy(i,j)$  }    \end{cases}     \\
[817]892umask(i,j,k) &=         \; tmask(i,j,k) \ * \ tmask(i+1,j,k)   \\
[994]893vmask(i,j,k) &=         \; tmask(i,j,k) \ * \ tmask(i,j+1,k)   \\
894fmask(i,j,k) &=         \; tmask(i,j,k) \ * \ tmask(i+1,j,k)   \\
[6497]895             &    \ \ \, * tmask(i,j,k) \ * \ tmask(i+1,j,k) \\
[6320]896wmask(i,j,k) &=         \; tmask(i,j,k) \ * \ tmask(i,j,k-1) \text{ with } wmask(i,j,1) = tmask(i,j,1)
[707]897\end{align*}
898
[6497]899Note that, without ice shelves cavities, masks at $t-$ and $w-$points are identical with
900the numerical indexing used (\S~\ref{DOM_Num_Index}). Nevertheless, $wmask$ are required
901with oceean cavities to deal with the top boundary (ice shelf/ocean interface)
902exactly in the same way as for the bottom boundary.
[6320]903
904The specification of closed lateral boundaries requires that at least the first and last
[817]905rows and columns of the \textit{mbathy} array are set to zero. In the particular
906case of an east-west cyclical boundary condition, \textit{mbathy} has its last
907column equal to the second one and its first column equal to the last but one
908(and so too the mask arrays) (see \S~\ref{LBC_jperio}).
[707]909
[3294]910
911% ================================================================
912% Domain: Initial State (dtatsd & istate)
913% ================================================================
914\section  [Domain: Initial State (\textit{istate and dtatsd})]
[9363]915      {Domain: Initial State \small{(\protect\mdl{istate} and \protect\mdl{dtatsd} modules)} }
[3294]916\label{DTA_tsd}
917%-----------------------------------------namtsd-------------------------------------------
918\namdisplay{namtsd} 
919%------------------------------------------------------------------------------------------
920
[4147]921Options are defined in \ngn{namtsd}.
[3294]922By default, the ocean start from rest (the velocity field is set to zero) and the initialization of
923temperature and salinity fields is controlled through the \np{ln\_tsd\_ini} namelist parameter.
924\begin{description}
925\item[ln\_tsd\_init = .true.]  use a T and S input files that can be given on the model grid itself or
926on their native input data grid. In the latter case, the data will be interpolated on-the-fly both in the
927horizontal and the vertical to the model grid (see \S~\ref{SBC_iof}). The information relative to the
928input files are given in the \np{sn\_tem} and \np{sn\_sal} structures.
929The computation is done in the \mdl{dtatsd} module.
930\item[ln\_tsd\_init = .false.] use constant salinity value of 35.5 psu and an analytical profile of temperature
931(typical of the tropical ocean), see \rou{istate\_t\_s} subroutine called from \mdl{istate} module.
932\end{description}
[6997]933\end{document}
Note: See TracBrowser for help on using the repository browser.