source: trunk/DOC/BETA/Chapters/Chap_DOM.tex @ 781

Last change on this file since 781 was 781, checked in by smasson, 13 years ago

doc update, see ticket:1

  • Property svn:executable set to *
File size: 59.1 KB
Line 
1
2% ================================================================
3% Chapter 2 Ñ Space and Time Domain (DOM)
4% ================================================================
5\chapter{Space and Time Domain (DOM) }
6\label{DOM}
7\minitoc
8
9% Missing things:
10%  - istate: description of the initial state
11%  - daymod: definition of the time domain (nit000, nitend andd the calendar)
12%  -geo2ocean:  how to switch from geographic to mesh coordinate
13%  - domclo:  closed sea and lakes.... management of closea sea area : specific to global configuration, both forced and coupled
14
15
16
17
18
19Having defined the continuous equations in Chap.~\ref{PE}, we need to choose a discretization on a grid, and numerical algorithms. In the present chapter, we provide a general description of the staggered grid used in OPA, and other information relevant to the main directory routines (time stepping, main program) as well as the DOM (DOMain) directory.
20
21% ================================================================
22% Fundamentals of the Discretisation
23% ================================================================
24\section{Fundamentals of the Discretisation}
25\label{DOM_basics}
26
27% -------------------------------------------------------------------------------------------------------------
28%        Arrangement of Variables
29% -------------------------------------------------------------------------------------------------------------
30\subsection{Arrangement of Variables}
31\label{DOM_cell}
32
33%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
34\begin{figure}[!tb] \label{Fig_cell}  \begin{center}
35\includegraphics[width=0.90\textwidth]{./Figures/Fig_cell.pdf}
36\caption{Arrangement of variables. $T$ indicates scalar points where temperature, salinity, density, pressure and horizontal divergence are defined. ($u$,$v$,$w$) indicates vector points, and $f$ indicates vorticity points where both relative and planetary vorticities are defined}
37\end{center}   \end{figure}
38%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
39
40The numerical techniques used to solve the Primitive Equations in this model are based on the traditional, centred second-order finite difference approximation. Special attention has been given to the homogeneity of the solution in the three space directions. The arrangement of variables is the
41same in all directions. It consists in cells centred on scalar points ($T$, $S$, $p$, $\rho$) with vector points $(u, v, w)$ defined in the centre of each face of the cells (Fig. \ref{Fig_cell}). This is the generalisation to three dimensions of the well-known ``C'' grid in Arakawa's classification. The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge and the barotropic stream function $\psi$ is defined at horizontal points overlying the $\zeta$ and $f$-points.
42
43The ocean mesh ($i.e.$ the position of all the scalar and vector points) is defined by the transformation that gives ($\lambda$ ,$\varphi$ ,$z$) as a function of $(i,j,k)$. The grid-points are located at integer or integer and a half value of $(i,j,k)$ as indicated on Table \ref{Tab_cell}. In all the following, subscripts $u$, $v$, $w$, $f$, $uw$, $vw$ or $fw$ indicate the position of the grid-point where the scale factors are defined. Each scale factor is defined as the local analytical value provided by \eqref{Eq_scale_factors}. As a result, the mesh on which partial derivatives $\frac{\partial}{\partial \lambda}, \frac{\partial}{\partial \varphi}$, and $\frac{\partial}{\partial z} $ are evaluated is a uniform mesh with a grid size unity. Discrete partial derivatives are formulated by the traditional, centred second order finite difference approximation while the scale factors are chosen equal to their local analytical value. An important point here is that the partial derivative of the scale factors must be evaluated by centred finite difference approximation, not from their
44analytical expression. This preserves the symmetry of the discrete set of equations and therefore allows satisfying many of the continuous properties (see { \colorbox{yellow}{Annexe C}). A similar, related remark can be made about the domain size: when needed, an area, volume, or the total ocean depth must be evaluated as the sum of the relevant scale factors (see \eqref{DOM_bar}) in the next section).
45
46\begin{table}[!tb] \label{Tab_cell}
47\begin{center} \begin{tabular}{|p{46pt}|p{56pt}|p{56pt}|p{56pt}|}
48\hline
49&$i$     & $j$    & $k$     \\ \hline
50& $i+1/2$   & $j$    & $k$    \\ \hline
51& $i$    & $j+1/2$   & $k$    \\ \hline
52& $i$    & $j$    & $k+1/2$   \\ \hline
53& $i+1/2$   & $j+1/2$   & $k$    \\ \hline
54uw & $i+1/2$   & $j$    & $k+1/2$   \\ \hline
55vw & $i$    & $j+1/2$   & $k+1/2$   \\ \hline
56fw & $i+1/2$   & $j+1/2$   & $k+1/2$   \\ \hline
57\end{tabular}
58\caption{Location of grid-points as a function of integer or integer and a half value of the column, line or level. This indexation is only used for the writing of semi-discrete equation. In the code, the indexation use integer value only and has a reverse direction in the vertical (see \S\ref{DOM_Num_Index})}
59\end{center}
60\end{table}
61
62% -------------------------------------------------------------------------------------------------------------
63%        Vector Invariant Formulation
64% -------------------------------------------------------------------------------------------------------------
65\subsection{Discrete Operators}
66\label{DOM_operators}
67
68Given the values of a variable $q$ at adjacent points, the derivation and averaging operators at the midpoint between them are:
69\begin{subequations} \label{Eq_di_mi}
70\begin{align}
71 \delta _i [q]  &\  \    q(i+1/2)  - q(i-1/2)      \\
72 \overline q^i &= \left\{ q(i+1/2) + q(i-1/2) \right\} \; / \; 2
73\end{align}
74\end{subequations}
75
76Similar operators are defined with respect to $i+1/2$, $j$, $j+1/2$, $k$, and $k+1/2$. Following
77\eqref{Eq_PE_grad} and \eqref{Eq_PE_lap}, the gradient of a variable $q$ defined at $T$-point has its three components defined at $(u,v,w)$ while its Laplacien is defined at $T$-point. These operators have the following discrete forms in the curvilinear $s$-coordinate system:
78\begin{equation} \label{Eq_DOM_grad}
79\nabla q\equiv    \frac{1}{e_{1u} }\delta _{i+1/2} \left[ q \right]\;\,{\rm {\bf i}}
80         +  \frac{1}{e_{2v} }\delta _{j+1/2} \left[ q \right]\;\,{\rm {\bf j}}
81         +  \frac{1}{e_{3w} }\delta _{k+1/2} \left[ q \right]\;\,{\rm {\bf k}}
82\end{equation}
83\begin{multline} \label{Eq_DOM_lap}
84\Delta q\equiv \frac{1}{e_{1T} {\kern 1pt}e_{2T} {\kern 1pt}e_{3T} }\;\left(
85{\delta _i \left[ {\frac{e_{2u} e_{3u} }{e_{1u} }\;\delta _{i+1/2} 
86\left[ q \right]} \right]
87+\delta _j \left[ {\frac{e_{1v} e_{3v} }{e_{2v} 
88}\;\delta _{j+1/2} \left[ q \right]} \right]\;} \right)     \\
89+\frac{1}{e_{3T} }\delta _k \left[ {\frac{1}{e_{3w} }\;\delta _{k+1/2} 
90\left[ q \right]} \right]
91\end{multline}
92
93Following \eqref{Eq_PE_curl} and \eqref{Eq_PE_div}, a vector ${\rm {\bf A}}=\left( a_1,a_2,a_3\right)$ defined at vector points $(u,v,w)$ has its three curl components defined at $(vw,uw,f)$ and its divergence defined at $T$-points:
94\begin{equation} \label{Eq_DOM_curl}
95\begin{split}
96 \nabla \times {\rm {\bf A}}\equiv \frac{1}{e_{2v} {\kern 1pt}e_{3vw} 
97}{\kern 1pt}\,\;\left( {\delta _{j+1/2} \left[ {e_{3w} a_3 } \right]-\delta 
98_{k+1/2} \left[ {e_{2v} a_2 } \right]} \right&\;\;{\rm {\bf i}} \\ 
99 +\frac{1}{e_{2u} {\kern 1pt}e_{3uw} }\;\left( {\delta _{k+1/2} \left[ {e_{1u} a_1 } 
100\right]-\delta _{i+1/2} \left[ {e_{3w} a_3 } \right]} \right&\;\;{\rm{\bf j}} \\ 
101 +\frac{e_{3f} }{e_{1f} {\kern 1pt}e_{2f} }\,{\kern 1pt}\;\left( {\delta 
102_{i+1/2} \left[ {e_{2v} a_2 } \right]-\delta _{j+12} \left[ {e_{1u} a_1 } \right]} 
103\right&\;\;{\rm {\bf k}}
104 \end{split}
105\end{equation}
106\begin{equation} \label{Eq_DOM_div}
107\nabla \cdot {\rm {\bf A}}=\frac{1}{e_{1T} e_{2T} e_{3T} }\left( {\delta 
108_i \left[ {e_{2u} e_{3u} a_1 } \right]+\delta _j \left[ {e_{1v} e_{3v} a_2 } 
109\right]} \right)+\frac{1}{e_{3T} }\delta _k \left[ {a_3 } \right]
110\end{equation}
111
112In the special case of pure $z$-coordinates system, \eqref{Eq_DOM_lap} and \eqref{Eq_DOM_div} can be simplified. In this case, the vertical scale factor becomes a function of the single variable $k$ and thus does not depend on the horizontal location of a grid point. It can be simplified from outside and inside the $\delta _i$ and $\delta_j$ operators.
113
114The vertical average over the whole water column denoted by an overbar becomes for a quantity $q$ which is a masked field (i.e. equal to zero inside solid area):
115\begin{equation} \label{DOM_bar}
116\bar q   = \frac{1}{H}\int_{k^b}^{k^o} {q\;e_{3q} \,dk} 
117      \equiv \frac{1}{H_q }\sum\limits_k {q\;e_{3q} }
118\end{equation}
119where $H_q$  the ocean depth, is the masked sum of the vertical scale factors at q points, $k^b$ and $k^o$ are the bottom and surface $k$-index, and the symbol $k^o$ referring to a summation over all grid points of the same species in the direction indicated by the subscript (here $k$).
120
121In continuous, the following properties are satisfied:
122\begin{equation} \label{Eq_DOM_curl_grad}
123\nabla \times \nabla q ={\rm {\bf {0}}}
124\end{equation}
125\begin{equation} \label{Eq_DOM_div_curl}
126\nabla \cdot \left( {\nabla \times {\rm {\bf A}}} \right)=0
127\end{equation}
128
129It is straight forward to demonstrate that these properties are verified locally in discrete form as soon as the scalar $q$ is taken at $T$-points and the vector \textbf{A} has its components defined at vector points $(u,v,w)$.
130
131Let $a$ and $b$ be two fields defined on the ocean mesh, extended to zero inside continental area. By integration by part it can be shown that the derivation operators ($\delta_i$, $\delta_j$ and $\delta_k$) are anti-symmetric linear operators, and further that the averaging operators $\overline{\cdot}^i$, $\overline{\cdot}^j$ and $\overline{\cdot}^k$) are symmetric linear operators, i.e.,
132\begin{equation} \label{DOM_di_adj}
133\sum\limits_i {a_i \;\delta _i \left[ b \right]} \equiv -\sum\limits_i
134{\delta _{i+1/2} \left[ a \right]\;b_{i+1/2} }
135\end{equation}
136\begin{equation} \label{DOM_mi_adj}
137\sum\limits_i {a_i \;\overline b ^i} \equiv \sum\limits_i {\overline a ^{i+1/2}\;b_{i+1/2} } 
138\end{equation}
139
140In other words, the adjoint of the derivation and averaging operators are $\delta_i^*=\delta_{i+1/2}$ and $\overline{\cdot}^{i\,*}= \overline{\cdot}^{i+1/2}$, respectively. These two properties will be used extensively in the \colorbox{yellow} {Appendix C} to
141demonstrate integral conservative properties of the discrete formulation chosen.
142
143% -------------------------------------------------------------------------------------------------------------
144%        Numerical Indexation
145% -------------------------------------------------------------------------------------------------------------
146\subsection{Numerical Indexation}
147\label{DOM_Num_Index}
148
149%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
150\begin{figure}[!tb] \label{Fig_index_hor}  \begin{center}
151\includegraphics[width=0.90\textwidth]{./Figures/Fig_index_hor.pdf}
152\caption{Horizontal integer indexation used in the \textsc{Fortran} code. The dashed area indicates the cell in which variables contained in arrays have the same $i$- and $j$-indices}
153\end{center}   \end{figure}
154%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
155
156The array representation used in the \textsc{Fortran} code requires an integer indexation while the analytical definition of the mesh (see \S\ref{DOM_cell}) is associated with the use of integer values of $(i,j,k)$ for $T$-points whereas all the other points use both integer and integer and a half values of $(i,j,k)$. Therefore a specific integer indexation must be defined for the latter grid-points
157(i.e. velocity and vorticity grid-points). Furthermore, it has been chosen to change the direction of the vertical indexation so that the surface level is at $k=1$.
158
159% -----------------------------------
160%        Horizontal Indexation
161% -----------------------------------
162\subsubsection{Horizontal Indexation}
163\label{DOM_Num_Index_hor}
164
165The indexation in the horizontal plane has been chosen as shown in Fig.\ref{Fig_index_hor}. For an increasing $i$ index ($j$ index), the $T$-point and the eastward $u$-point (northward $v$-point) have the same index (see the dashed area in Fig.\ref{Fig_index_hor}). A $T$-point and its nearby northeast $f$-point have the same $i$-and $j$-indices.
166
167% -----------------------------------
168%        Vertical Indexation
169% -----------------------------------
170\subsubsection{Vertical Indexation}
171\label{DOM_Num_Index_vertical}
172
173In the vertical plane, the chosen indexation requires special attention since the $k$-axis is re-oriented downward in the \textsc{Fortran} code compared to the indexation used for the semi-discrete equations and given in \S\ref{DOM_cell}. The sea surface corresponds to the $w$-level $k=1$ like the $T-$level just below (Fig.\ref{Fig_index_vert}). The last $w$-level ($k=jpk$) is either the ocean bottom or inside the ocean floor while the last $T-$level is always inside the floor (Fig.\ref{Fig_index_vert}). Note that for an increasing $k$ index, a $w$-point and the $T$-point just below have the same $k$ index, in opposition to what is done in the horizontal plane where
174it is the $T-$point and the nearby velocity points in the direction of the horizontal axis that have the same $i$ or $j$ index (compare the dashed area in Fig.\ref{Fig_index_hor} and \ref{Fig_index_vert}). As the scale factors are chosen to be strictly positive, \emph{a minus sign appears in the \textsc{Fortran} code before all the vertical derivatives of the discrete equations given in this documentation}.
175
176%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
177\begin{figure}[!pt] \label{Fig_index_vert}  \begin{center}
178\includegraphics[width=.90\textwidth]{./Figures/Fig_index_vert.pdf}
179\caption{Vertical integer indexation used in the \textsc{Fortran } code. Note that the $k$-axis is oriented downward. The dashed area indicates the cell in which variables contained in arrays have the same $k$-index.}
180\end{center}   \end{figure}
181%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
182
183% -----------------------------------
184%        Vertical Indexation
185% -----------------------------------
186\subsubsection{Domain size}
187\label{DOM_size}
188
189The total size of the computational domain is set by the parameters \jp{jpiglo}, \jp{jpjglo} and \jp{jpk} in the $i$, $j$ and $k$ directions respectively. They are given as parameters in the \mdl{par\_oce} module (or additional files included in this module such as \textit{par\_ORCA\_R2.h90}, specific to a given configuration). The use of parameters rather than variables (together with dynamic allocation of arrays) was made because it ensured that the compiler would optimize the executable code efficiently, especially on vector machines (optimization may be less efficient when the problem size is unknown at the time of compilation). Nevertheless, it is possible to set up the code with full dynamical allocation by using the AGRIF packaged \colorbox{yellow}{(ref agrif!+ ref part of the doc)}. Note that are other parameters in \mdl{par\_oce} that refer to the domain size. The two parameters $jpidta$ and $jpjdta$, may be larger than $jpiglo$, $jpjglo$ when the user wants to use only a sub-region of a given configuration. This is the "zoom" capability described in \S\ref{MISC_zoom}. In most applications of the model, $jpidta=jpiglo$, $jpjdta=jpjglo$, and $jpizoom=jpjzoom=1$. Parameters $jpi$ and $jpj$ refer to the size of each processor subdomain when the code is run in parallel using domain decomposition (\key{mpp\_mpi} defined, see \S\ref{LBC_mpp}).
190
191% ================================================================
192% Domain: Horizontal Grid (mesh)
193% ================================================================
194\section{Domain: Horizontal Grid (mesh) (\mdl{domhgr} module)}
195\label{DOM_hgr}
196
197% -------------------------------------------------------------------------------------------------------------
198%        Coordinates and scale factors
199% -------------------------------------------------------------------------------------------------------------
200\subsection{Coordinates and scale factors}
201\label{DOM_hgr_coord_e}
202
203The ocean mesh (i.e. the position of all the scalar and vector points) is defined by the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. The grid-points are located at integer or integer and a half values of as indicated in Table~\ref{Tab_cell}. The associated scale factors are defined using the analytical first derivative of the transformation \eqref{Eq_scale_factors}. These definitions are done in two modules, \mdl{domhgr} and \mdl{domzgr}, which provide the horizontal and vertical meshes, respectively. This section deals with the horizontal mesh parameters.
204
205In a horizontal plane, the location of all the model grid points is defined from the analytical expressions of the latitude $\varphi$ and the longitude $\lambda$ as a function of  $(i,j)$. The horizontal scale factors are calculated using \eqref{Eq_scale_factors}. For example, when the latitude and longitude are function of a single value ($j$ and $i$, respectively) (geographical configuration of the mesh), the horizontal mesh definition reduces to define the wanted $\varphi(j)$, $\varphi'(j)$, $\lambda(i)$, and $\lambda'(i)$ in the \mdl{domhgr} module. The model computes the grid-point positions and scale factors in the horizontal plane as follows:
206\begin{flalign*}
207\lambda_T &\equiv \text{glamt} = \lambda(i)  &     \varphi_T &\equiv \text{gphit} = \varphi(j)\\
208\lambda_u &\equiv \text{glamu}= \lambda(i+1/2)&    \varphi_u &\equiv \text{gphiu}= \varphi(j)\\
209\lambda_v &\equiv \text{glamv}= \lambda(i)      &     \varphi_v &\equiv \text{gphiv} = \varphi(j+1/2)\\
210\lambda_f &\equiv \text{glamf }= \lambda(i+1/2)&      \varphi_f &\equiv \text{gphif }= \varphi(j+1/2)
211\end{flalign*}
212\begin{flalign*}
213e_{1T} &\equiv \text{e1t} = r_a |\lambda'(i)    \; \cos\varphi(j)  |&
214e_{2T} &\equiv \text{e2t} = r_a |\varphi'(j)|\\
215e_{1u} &\equiv \text{e1t} = r_a |\lambda'(i+1/2)   \; \cos\varphi(j)  |&
216e_{2u} &\equiv \text{e2t} = r_a |\varphi'(j)|\\
217e_{1v} &\equiv \text{e1t} = r_a |\lambda'(i)    \; \cos\varphi(j+1/2)  |&
218e_{2v} &\equiv \text{e2t} = r_a |\varphi'(j+1/2)|\\
219e_{1f} &\equiv \text{e1t} = r_a |\lambda'(i+1/2)\; \cos\varphi(j+1/2)  |&
220e_{2f} &\equiv \text{e2t} = r_a |\varphi'(j+1/2)|
221\end{flalign*}
222where the last letter of each computational name indicates the grid point considered and $r_a$ is the earth radius (defined in \mdl{phycst} along with all universal constants). Note that the horizontal position and scale factors of $w$-points are exactly equal to those of $T-$points, thus no specific arrays are defined at those grid-points.
223
224Note that the definition of the scale factors --- as the analytical first derivative of the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$ --- is specific to the OPA model \citep{Marti1992}. As an example, $e_{1T}$ is defined locally at a $T$-point, whereas many other models on a C grid choose to define such a scale factor as the distance between the $U$-points on each side of the $T$-point. Relying on an analytical transformation has two advantages: firstly, there is no ambiguity in the scale factors appearing in the discrete equations, since they are first introduced in the continuous equations; secondly, analytical transformations encourage good practice by the definition of smooth grids \citep{Treguier1996}. An example of the effect of such a choice is shown in Fig.~\ref{Fig_zgr_e3}.
225%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
226\begin{figure}[!t] \label{Fig_zgr_e3}  \begin{center}
227\includegraphics[width=0.90\textwidth]{./Figures/Fig_zgr_e3.pdf}
228\caption{(a) Traditional definition of grid-point position and grid-size in the vertical versus (b) analytically derived grid-point position and scale factors. For both grid here,a same $w$-point depth has been chosen but in (a) the $T$-points are set at the middle of $w$-points while in (b) they are defined from an analytical function: $z(k)=5\,(i-1/2)^3 - 45\,(i-1/2)^2 + 140\,(i-1/2) - 150$. Note the resulting difference between the value of the grid-size $\Delta_k$ and those of the scale factor $e_k$. }
229\end{center}   \end{figure}
230%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
231
232% -------------------------------------------------------------------------------------------------------------
233%        Choice of horizontal grids
234% -------------------------------------------------------------------------------------------------------------
235\subsection{Choice of horizontal grids}
236\label{DOM_hgr_msh_choice}
237
238The user has three options to define a horizontal grid, involving the parameter $jphgr\_mesh$ of the \mdl{par\_oce} module.
239\begin{enumerate}
240\item For the most general curvilinear orthogonal grids, the coordinates and their first derivatives with respect to $i$ and $j$ are provided in a file, read in \rou{hgr\_read} subroutine of the domhgr module: \jp{jphgr\_mesh}=0.
241\item A few simple analytical grids are provided as examples, that can be selected by setting \jp{jphgr\_mesh}=1 to 5 (see below)
242\item For other analytical grids, the \mdl{domhgr} module must be modified by the user.
243\end{enumerate}
244
245There are two simple cases of geographical grids on the sphere. With \jp{jphgr\_mesh}=1, the grid is regular in space, with grid sizes specified by parameters \pp{ppe1\_deg} and \pp{ppe2\_deg}, respectively. A geographical grid
246can be very anisotropic at high latitudes, because of the convergence of meridians (the zonal scale factors $e_1$ become much smaller than the meridional scale factors $e_2$). The Mercator grid (\jp{jphgr\_mesh}=4) avoids this anisotropy by refining the meridional scale factors in the same way as the zonal ones. In that case, meridional scale factors and latitudes are calculated analytically using the formulae appropriate for a Mercator projection, based on \pp{ppe1\_deg} which is a reference grid spacing at the equator (this applies even when the geographical equator is situated outside the model domain). In those two cases (\jp{jphgr\_mesh}=1 or 4), the grid position is defined by the longitude and latitude of the south-westhernmost point (\pp{ppglamt0} and \pp{ppgphi0}). Note that for the Mercator grid the user need only provide an approximate starting latitude: the real latitude will be recalculated analytically, so as to ensure that the equator corresponds to a $T$- and$ U$-point. 
247
248Rectangular grids ignoring the spherical geometry are defined with \jp{jphgr\_mesh} = 2, 3, 5. The domain is either a $f$-plane (\jp{jphgr\_mesh} = 2, Coriolis factor is constant) or a beta-plane (\jp{jphgr\_mesh} = 3, the Coriolis factor is linear in the $j$-direction). The grid size is uniform in each direction, and given in meters by the parameters \pp{ppe1\_m} and \pp{ppe2\_m} respectively. The zonal grid coordinate (glam. arrays) is in kilometers, starting at zero with the first T point. The meridional coordinate (gphi. arrays) is in kilometers, and the second $T$-point corresponds to coordinate gphit=0. The input parameter \pp{ppglam0} is ignored. \pp{ppgphi0} is used to set the reference latitude for computation of the Coriolis parameter. In the case of the beta plane, \pp{ppgphi0} corresponds to the center of the domain. Finally, the special case \jp{jphgr\_mesh}=5 corresponds to a beta plane in a rotated domain for the GYRE configuration representing a classical mid-latitude double gyre system. The rotation allows to maximize the jet length relative to the gyre areas (and the number of grid points).
249
250The choice of the grid must be consistent with the boundary conditions specified by the parameter \jp{jperio} (see {\S\ref{LBC}).
251
252% -------------------------------------------------------------------------------------------------------------
253%        Grid files
254% -------------------------------------------------------------------------------------------------------------
255\subsection{Grid files}
256\label{DOM_hgr_files}
257
258All the arrays related to a particular ocean model configuration (grid-point position, scale factors, masks) can be saved in files if $\np{nmsh} \not= 0$ (namelist parameter). This can be particularly useful for plots and off-line diagnostics. In some cases, the user may choose to make a local modification of a scale factor in the code. This is the case in global configurations when restricting the width of a specific strait (usually a one-grid-point strait that happens to be too wide due to the insufficient model resolution). On example is Lombok Strait in the ORCA2 configuration. When such modifications are done, the output grid written when $\np{nmsh} \not=0$ is not exactly equal to the input grid.
259
260% ================================================================
261% Domain: Vertical Grid (domzgr)
262% ================================================================
263\section{Domain: Vertical Grid (\mdl{domzgr} module)}
264\label{DOM_zgr}
265%-----------------------------------------nam_zgr & namdom-------------------------------------------
266\namdisplay{nam_zgr} 
267\namdisplay{namdom} 
268%-------------------------------------------------------------------------------------------------------------
269
270In the vertical, the model mesh is determined by four things: (1) the bathymetry given in meters ; (2) the number of levels of the model (\jp{jpk}) ; (3) the analytical transformation $z(i,j,k)$ and the vertical scale factors
271(derivatives of the transformation) ; and (4) the masking system, i.e. the number of wet model levels at each $(i,j)$.
272
273%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
274\begin{figure}[!tb] \label{Fig_z_zps_s_sps}  \begin{center}
275\includegraphics[width=1.0\textwidth]{./Figures/Fig_z_zps_s_sps.pdf}
276\caption{The ocean bottom as seen by the model: (a) $z$-coordinate with full step, (b) $z$-coordinate with partial step, (c) $s$-coordinate: terrain following representation, (d) hybrid $s-z$ coordinate, (e) hybrid $s-z$ coordinate with partial step, and (f) same as (e) but with variable volume level associated with the non-linear free surface. Note that the variable volume level (\key{vvl}) could be used with any of the 5 coordinates (a) to (e).}
277\end{center}   \end{figure}
278%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
279
280The choice of a vertical coordinate among all those offered in NEMO, even if it is made through a namelist parameter, must be done once of all at the beginning of an experiment. It is not intended as an option which can be
281enabled or disabled in the middle of an experiment. Three main choices are offered (Fig.~\ref{Fig_z_zps_s_sps}a to c): $z$-coordinate with full step bathymetry (\np{ln\_zco}=true), $z$-coordinate with partial step bathymetry (\np{ln\_zps}=true), or generalized, $s$-coordinate (\np{ln\_sco}=true). Hybridation of the three main
282coordinates are available: hybrid $s-z$ or $s-zps$ coordinate (Fig.~\ref{Fig_z_zps_s_sps}d and \ref{Fig_z_zps_s_sps}e). When using the variable volume option \key{vvl}), the coordinate follow the time-variation of the free surface so that the transformation is time dependent: $z(i,j,k,t)$ (Fig.~\ref{Fig_z_zps_s_sps}f). This option can be used with full step bathymetry or $s$-coordinates (hybride and partial step coordinates not yet implemented in NEMO v2.3).
283
284Contrary to the horizontal grid, the vertical grid is computed in the code and no provision is made for reading it from a file. The only input file is the bathymetry (in meters). After reading the bathymetry, the algorithm for vertical grid definition differs between the different options:
285\begin{description}
286\item[\textit{zco}] set a reference coordinate transformation $z_0 (k)$, and set $z(i,j,k,t)=z_0 (k)$.
287\item[\textit{zps}] set a reference coordinate transformation $z_0 (k)$, and
288calculate the height at the deepest levels using the bathymetry, to obtain the final three-dimensional depth and scale factor arrays.
289\item[\textit{sco}] Smooth the bathymetry to fullfill the hydrostatic consistency criteria and set the three-dimensional transformation.
290\item[\textit{s-z} and \textit{s-zps}] Smooth the bathymetry to fullfill the hydrostatic consistency criteria and set the three-dimensional transformation $z(i,j,k)$, and possibly introduce masking of extra land points to better fit the original bathymetry file
291\end{description}
292
293Generally, the arrays describing the grid point depths and vertical scale factors are three dimensional arrays $(i,j,k)$. In the special case of $z$-coordinates with full step bottom topography, it is possible to define
294those arrays as one-dimensional, in order to save memory. This is performed by defining the \key{zco} C-Pre-Processor (CPP) key. To improve the code readability while providing this flexibility, the vertical coordinates and scale factors are defined as functions of $(i,j,k)$ with "fs" as prefix (examples: \textit{fsdeptht, fse3t,} etc) that can be equal to three-dimensional arrays, or a one dimensional array when \key{zco} is defined. These functions are defined in the file
295\textit{domzgr\_substitute.h90} of the DOM directory. They are used through the code, and replaced by the corresponding arrays at the time of pre-processing (CPP capability).
296
297% -------------------------------------------------------------------------------------------------------------
298%        Meter Bathymetry
299% -------------------------------------------------------------------------------------------------------------
300\subsection{Meter Bathymetry}
301\label{DOM_bathy}
302
303Three options are possible for defining the bathymetry, according to the
304namelist variable \np{ntopo}:
305\begin{description}
306\item[\np{ntopo} = 0] a flat-bottom domain is defined. The total depth $z_w (jpk)$ is given by the coordinate transformation. The domain can either a closed basin or a periodic channel according to the parameter \jp{jperio}.
307\item[\np{ntopo} = -1] a domain with a bump of topography at the central latitude and 1/3 of the domain width. This is meant for the "EEL-R5" configuration, a periodic or open boundary channel with a seamount.
308\item[\np{ntopo} = 1] read a bathymetry. The bathymetry file (Netcdf format) provides the ocean depth (positive, in meters) at each grid point of the model grid. The bathymetry is usually built by interpolating a standard bathymetry product (e.g., ETOPO2) onto the horizontal ocean mesh. The bathymetry file defines the coastline: where the bathymetry is zero, no model levels are defined (all levels are masked).
309\end{description}
310
311When using the rigid lid approximation (\key{dynspg\_rl} defined) isolated land masses (islands) must be identified by negative integers in the input bathymetry file (see \S\ref{MISC_solisl}).
312
313When the ocean is coupled to an atmospheric model it is better to represent
314all large water bodies (e.g, great lakes, Caspian sea...) even if the model
315resolution does not allow to represent their communication with the rest of
316the ocean. This is unnecessary when the ocean is forced by fixed atmospheric
317conditions. A possibility is offered to the user to set to zero the
318bathymetry in rectangular regions covering those closed seas (see \S\ref{MISC_closea}), but the code has to be adapted to the user's configuration.
319
320% -------------------------------------------------------------------------------------------------------------
321%        z-coordinate  and reference coordinate transformation
322% -------------------------------------------------------------------------------------------------------------
323\subsection [$z$-coordinate (\np{ln\_zco}=T or \key{zco})]
324         {$z$-coordinate (\np{ln\_zco}=T or \key{zco}) and reference coordinate}
325\label{DOM_zco}
326
327%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
328\begin{figure}[!tb] \label{Fig_zgr}  \begin{center}
329\includegraphics[width=0.90\textwidth]{./Figures/Fig_zgr.pdf}
330\caption{Default vertical mesh for ORCA2-L30. Vertical level functions for (a) T-point depth and (b) the associated scale factor as computed from (III.2.1) in z-coordinates.}
331\end{center}   \end{figure}
332%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
333
334The reference coordinate transformation $z_0 (k)$ defines the arrays \textit{gdept0} and \textit{gdepw0} for $T$- and $w$-points, respectively. As indicated on Fig.\ref{Fig_index_vert} \jp{jpk} is the number of $w$-levels. $gdepw(1)$ being the ocean surface. There are at most \jp{jpk}-1 $T$-points in the ocean, the additional $T$-point at $jk=jpk$ is below the sea floor and is not used. The vertical location of $w$- and $T$-levels is defined from the analytic expression of the depth $z_0 (k)$ whose analytic derivative with respect to $k$ provides the vertical scale factors. The user must provide the analytical expression of both $z_0 $and its first derivative with respect to $k$. This is done in routine \mdl{domzgr} through statement functions, using parameters provided in the \textit{par\_oce.h90} file.
335
336It is possible to define a simple regular vertical grid by giving zero stretching (\pp{ppacr=0}). In that case, the parameters \jp{jpk} (number of $w$-levels) and \pp{pphmax} (total ocean depth in meters) fully define the grid.
337
338For climate-related studies it is often desirable to concentrate the vertical resolution near the ocean surface. The following function is proposed as a standard for $z$-coordinates and partial steps:
339\begin{equation} \label{DOM_zgr_ana}
340\begin{split}
341 z_0 (k)    &= h_{sur} -h_0 \;k-\;h_1 \;\log \left[ {\,\cosh \left( {{(k-h_{th} )} / {h_{cr} }} \right)\,} \right] \\ 
342 e_3^0 (k)  &= \left| -h_0 -h_1 \;\tanh \left( {{(k-h_{th} )} / {h_{cr} }} \right) \right|
343\end{split}
344\end{equation}
345where $k=1$ to \jp{jpk} for $w$-levels and $k=1$ to $k=1$ for $T-$levels. Such an expression allows us to define a nearly uniform vertical location of levels at the ocean top and bottom with a smooth hyperbolic tangent transition in between (Fig.~\ref{Fig_zgr}).
346
347The first grid defined for ORCA2 had $10~m$ ($500~m)$ resolution in the surface (bottom) layers and a depth which varies from 0 at the sea surface to a minimum of $-5000~m$. This leads to the following conditions:
348\begin{equation} \label{DOM_zgr_coef}
349\begin{split}
350 e_3 (1+1/2)      &=10. \\ 
351 e_3 (jpk-1/2) &=500. \\ 
352 z(1)       &=0. \\ 
353 z(jpk)        &=-5000. \\ 
354\end{split}
355\end{equation}
356
357With the choice of the stretching $h_{cr} =3$ and the number of levels \jp{jpk}=$31$, the four coefficients $h_{sur}$, $h_{0}$, $h_{1}$, and $h_{th}$ in \eqref{DOM_zgr_ana} have been determined such that \eqref{DOM_zgr_coef} is satisfied, through an optimisation procedure using a bisection method. For the first standard
358ORCA2 vertial grid this led to the following values: $h_{sur} =4762.96$, $h_0 =255.58, h_1 =245.5813$, and $h_{th} =21.43336$. The resulting depths and scale factors as a function of the model levels are shown in Fig.~\ref{Fig_zgr} and given in Table \ref{Tab_orca_zgr}. Those values correspond to the parameters \pp{ppsur}, \pp{ppa0}, \pp{ppa1}, \pp{ppkth} in the parameter file \mdl{par\_oce}.
359
360Rather than entering parameters $h_{sur}$, $h_{0}$, and $h_{1}$ directly, it is
361possible to recalculate them. In that case the user sets
362\pp{ppsur}=\pp{ppa0}=\pp{ppa1}=\pp{pp\_to\_be\_computed}, in \mdl{par\_oce}, and specifies instead the four following parameters:
363\begin{itemize}
364\item    \pp{ppacr}=$h_{cr} $: stretching factor (nondimensional). The larger \pp{ppacr}, the smaller the stretching. Values from $3$ to $10$ are usual.
365\item    \pp{ppkth}=$h_{th} $: is approximately the model level at which maximum stretching occurs (nondimensional, usually of order 1/2 or 2/3 of \jp{jpk})
366\item    \pp{ppdzmin}: minimum thickness for the top layer (in meters)
367\item    \pp{pphmax}: total depth of the ocean (meters).
368\end{itemize}
369As an example, for the $45$ layers used in DRAKKAR configuration those parameters are: \jp{jpk}=46, \pp{ppacr}=9, \pp{ppkth}=23.563, \pp{ppdzmin}=6m, \pp{pphmax}=5750m.
370
371%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
372\begin{table} \label{Tab_orca_zgr}
373\begin{center} \begin{tabular}{c||r|r|r|r}
374\hline
375\textbf{LEVEL}& \textbf{GDEPT}& \textbf{GDEPW}& \textbf{E3T }& \textbf{E3W  } \\ \hline
376&  \textbf{  5.00}   &       0.00 & \textbf{ 10.00} &  10.00 \\   \hline
377&  \textbf{15.00} &    10.00 &   \textbf{ 10.00} &  10.00 \\   \hline
378&  \textbf{25.00} &    20.00 &   \textbf{ 10.00} &     10.00 \\   \hline
379&  \textbf{35.01} &    30.00 &   \textbf{ 10.01} &     10.00 \\   \hline
380&  \textbf{45.01} &    40.01 &   \textbf{ 10.01} &  10.01 \\   \hline
381&  \textbf{55.03} &    50.02 &   \textbf{ 10.02} &     10.02 \\   \hline
382&  \textbf{65.06} &    60.04 &   \textbf{ 10.04} &  10.03 \\   \hline
383&  \textbf{75.13} &    70.09 &   \textbf{ 10.09} &  10.06 \\   \hline
384&  \textbf{85.25} &    80.18 &   \textbf{ 10.17} &  10.12 \\   \hline
38510 &  \textbf{95.49} &    90.35 &   \textbf{ 10.33} &  10.24 \\   \hline
38611 &  \textbf{105.97}   &   100.69 &   \textbf{ 10.65} &  10.47 \\   \hline
38712 &  \textbf{116.90}   &   111.36 &   \textbf{ 11.27} &  10.91 \\   \hline
38813 &  \textbf{128.70}   &   122.65 &   \textbf{ 12.47} &  11.77 \\   \hline
38914 &  \textbf{142.20}   &   135.16 &   \textbf{ 14.78} &  13.43 \\   \hline
39015 &  \textbf{158.96}   &   150.03 &   \textbf{ 19.23} &  16.65 \\   \hline
39116 &  \textbf{181.96}   &   169.42 &   \textbf{ 27.66} &  22.78 \\   \hline
39217 &  \textbf{216.65}   &   197.37 &   \textbf{ 43.26} &  34.30 \\ \hline
39318 &  \textbf{272.48}   &   241.13 &   \textbf{ 70.88} &  55.21 \\ \hline
39419 &  \textbf{364.30}   &   312.74 &   \textbf{116.11} &  90.99 \\ \hline
39520 &  \textbf{511.53}   &   429.72 &   \textbf{181.55} &    146.43 \\ \hline
39621 &  \textbf{732.20}   &   611.89 &   \textbf{261.03} &    220.35 \\ \hline
39722 &  \textbf{1033.22}&  872.87 &   \textbf{339.39} &    301.42 \\ \hline
39823 &  \textbf{1405.70}& 1211.59 &   \textbf{402.26} &    373.31 \\ \hline
39924 &  \textbf{1830.89}& 1612.98 &   \textbf{444.87} &    426.00 \\ \hline
40025 &  \textbf{2289.77}& 2057.13 &   \textbf{470.55} &    459.47 \\ \hline
40126 &  \textbf{2768.24}& 2527.22 &   \textbf{484.95} &    478.83 \\ \hline
40227 &  \textbf{3257.48}& 3011.90 &   \textbf{492.70} &    489.44 \\ \hline
40328 &  \textbf{3752.44}& 3504.46 &   \textbf{496.78} &    495.07 \\ \hline
40429 &  \textbf{4250.40}& 4001.16 &   \textbf{498.90} &    498.02 \\ \hline
40530 &  \textbf{4749.91}& 4500.02 &   \textbf{500.00} & 499.54 \\ \hline
40631 &  \textbf{5250.23}& 5000.00 &   \textbf{500.56} & 500.33 \\ \hline
407\end{tabular} \end{center} 
408\caption{Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration as computed from \eqref{DOM_zgr_ana} using the coefficients given in \eqref{DOM_zgr_coef}}
409\end{table}
410%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
411
412% -------------------------------------------------------------------------------------------------------------
413%        z-coordinate with partial step
414% -------------------------------------------------------------------------------------------------------------
415\subsection{z-coordinate with partial step (\np{ln\_zps}=T)}
416\label{DOM_zps}
417%--------------------------------------------namdom-----------------------------------------------------
418\namdisplay{namdom} 
419%--------------------------------------------------------------------------------------------------------------
420
421In that case, the depths of the model levels are still defined by the
422reference analytical function $z_0 (k)$ as described in the previous
423section, excepted in the bottom layer. The thickness of the bottom layer is
424allowed to vary as a function of geographical location $(\lambda,\varphi)$ to allow a
425better representation of the bathymetry, especially in the case of small
426slopes (where the bathymetry varies by less than one level thickness from
427one grid point to the next). The reference layer thicknesses $e_{3t}^0$ have been
428defined in the absence of bathymetry. With partial steps, layers from 1 to
429\jp{jpk}-2 can have a thickness smaller than $e_{3t}(jk)$. The model deepest layer (\jp{jpk}-1) is
430allowed to have either a smaller or larger thickness than $e_{3t}(jpk)$: the
431maximum thickness allowed is $2*e_{3t}(jpk-1)$. This has to be kept in mind when
432specifying the maximum depth \pp{pphmax} in partial steps: for example, with
433\pp{pphmax}$=5750~m$ for the DRAKKAR 45 layers grid, the maximum ocean depth allowed is actually $6000~m$ (the default thickness $e_{3t}(jpk-1)$ being $250~m$). Two
434variables in the namdom namelist are used to define the partial step
435vertical grid. The mimimum water thickness (in meters) allowed for a cell
436partially filled with bathymetry at level jk is the minimum of \np{e3zpsmin} 
437(thickness in meters, usually $20~m$) or $e_{3t}(jk)*\np{e3zps\_rat}$ (a fraction,
438usually 10\%, of the default thickness $e_{3t}(jk)$).
439
440 \colorbox{yellow}{Add a figure here of pstep especially at last ocean level }
441
442% -------------------------------------------------------------------------------------------------------------
443%        s-coordinate
444% -------------------------------------------------------------------------------------------------------------
445\subsection{$s$-coordinate (\np{ln\_sco}=T)}
446\label{DOM_sco}
447%--------------------------------------------nam_zgr_sco---------------------------------------------------
448\namdisplay{nam_zgr_sco} 
449%--------------------------------------------------------------------------------------------------------------
450In s-coordinate (\key{sco} defined), the depths of the model
451levels are defined from the product of a depth field and a stretching
452function and its derivative, respectively:
453\begin{equation} \label{DOM_sco_ana}
454\begin{split}
455 z(k)    &= h(i,j) \; z_0(k)  \\
456 e_3(k)  &= h(i,j) \; z_0'(k)
457\end{split}
458\end{equation}
459where $h$ is the depth of the last $w$-level ($z_0(k)$) defined at $T-$point location
460in the horizontal and $z_0 (k)$ is a function which varies from $0$ at the sea
461surface to $1$ at the ocean bottom. The depth field $h$ is not necessary the ocean
462depth as a mixed step-like and bottom following representation of the
463topography can be used (Fig.~\ref{Fig_z_zps_s_sps}d-e). In the example provided (\hf{zgr\_s} file) $h$ is a smooth envelope bathymetry and steps are used to represent sharp bathymetric gradients.
464
465A new flexible stretching function, modified from \citet{Song1994} is provided as an example:
466\begin{equation} \label{DOM_sco_function}
467\begin{split}
468&= h_c +( h-h_c)\;c s)  \\
469c(s)  &\frac{ \left[   \tanh{ \left( \theta \, (s+b) \right)} 
470               - \tanh{ \left\theta \, b      \right)}  \right]}
471            {2\;\sinh \left( \theta \right)}
472\end{split}
473\end{equation}
474where $h_c $is the thermocline depth and $\theta $ and $b$ are the surface and
475bottom control parameters such that $0\leqslant \theta \leqslant 20$, and
476$0\leqslant b\leqslant 1$. Examples of the stretching function applied to a seamount are given in Fig.~\ref{Fig_sco_function}.
477
478%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
479\begin{figure}[!tb] \label{Fig_sco_function}  \begin{center}
480\includegraphics[width=1.0\textwidth]{./Figures/Fig_sco_function.pdf}
481\caption{examples of the stretching function applied to a sea mont: from left to right, surface, surface and bottom, and bottom intensified resolution}
482\end{center}   \end{figure}
483%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
484
485% -------------------------------------------------------------------------------------------------------------
486%        z*- or s*-coordinate
487% -------------------------------------------------------------------------------------------------------------
488\subsection{$z^*$- or $s^*$-coordinate (add \key{vvl}) }
489\label{DOM_zgr_vvl}
490
491This option is described in the report by Levier \textit{et al.} (2007), available on the NEMO web site.
492
493%gm% key advantage: minimise the diffusion/dispertion associated with advection in response to high frequency surface disturbances
494
495% -------------------------------------------------------------------------------------------------------------
496%        level bathymetry and mask
497% -------------------------------------------------------------------------------------------------------------
498\subsection{level bathymetry and mask}
499\label{DOM_msk}
500
501Whatever the vertical coordinate used, the model offers the possibility of
502representing the bottom topography with steps that follow the face of the
503model cells (step like topography) \citep{Madec1996}. The distribution of
504the steps in the horizontal is defined in a 2D integer array, mbathy, which
505gives the number of ocean levels ($i.e.$ those that are not masked) at each
506$T$-point. mbathy is computed from the meter bathymetry using the definiton of
507gdept as the number of $T$-points which gdept $\leq$ bathy. Note that in version
508NEMO v2.3, the user still has to provide the "level" bathymetry in a NetCDF
509file when using the full step option (\np{ln\_zco}), rather than the bathymetry
510in meters: both will be allowed in future versions.
511
512Modifications of the model bathymetry are performed in the \textit{bat\_ctl} 
513routine (see \mdl{domzgr} module) after mbathy is computed. Isolated grid points that do not
514communicate with another ocean point at the same level are eliminated.
515
516In case of rigid-lid approximation and islands in the computational domain (\np{ln\_dynspg\_rl}=true and \key{island} defined), the \textit{mbathy} array must be provided and takes values from $-N$ to \jp{jpk}-1. It provides the
517following information: $mbathy(i,j) = -n, \ n \in \left] 0,N \right]$, $T-$points are land points of the $n^{th}$ island ; $mbathy(i,j) =0$, $T-$points are land points of the main land (continent) ; $mbathy(i,j) =k$, the first $k$ $T$- and $w$-points are ocean points, the others land points. This is used to compute the island barotropic stream function used in rigid lid computation (see \S\ref{MISC_solisl}).
518
519From the \textit{mbathy} array, the mask fields are defined as follows:
520\begin{align*}
521tmask(i,j,k) &= \begin{cases}   1&   \text{ if $k\leq mbathy(i,j)$  }    \\
522                                              0&   \text{ if $k\leq mbathy(i,j)$  }    \end{cases}     \\
523umask(i,j,k) &= \; tmask(i,j,k) \;.\; tmask(i+1,j,k)  \\
524umask(i,j,k) &= \; tmask(i,j,k) \;.\; tmask(i,j+1,k)  \\
525umask(i,j,k) &= \; tmask(i,j,k) \;.\; tmask(i+1,j,k)  \\
526                  & \quad . \; tmask(i,j,k) \;.\; tmask(i+1,j,k)
527\end{align*}
528
529Note that \textit{wmask} is not defined as it is exactly equal to \textit{tmask} with the numerical
530indexation used (\S~\ref{DOM_Num_Index}). Moreover, the specification of closed lateral
531boundaries requires that at least the first and last rows and columns of
532\textit{mbathy} array are set to zero. In the particular case of an east-west cyclic
533boundary condition, \textit{mbathy} has its last column equal to the second one and its
534first column equal to the last but one (and so the mask arrays) (see \S~\ref{LBC_jperio}).
535
536\colorbox{yellow}{Add one word on tricky trick !} mbathy in further modified in zdfbfr{\ldots}.
537
538% ================================================================
539% Time discretisation
540% ================================================================
541\section{Time Discretisation}
542\label{DOM_nxt}
543
544The time stepping used in OPA is a three level scheme that can be presented as follows:
545\begin{equation} \label{Eq_DOM_nxt}
546   x^{t+\Delta t} = x^{t-\Delta t} + 2 \, \Delta t \  \text{RHS}_x^{t-\Delta t,t,t+\Delta t}
547\end{equation} 
548where $x$ stand for $u$, $v$, $T$ or $S$, RHS is the Right-Hand-Side of the corresponding time
549evolution equation, $\Delta t$ is the time step and the overscripts indicate
550the time at which a quantity is evaluated. Each term of the RHS is evaluated at
551specific time step(s) depending on the physics to which it is associated.
552The choice of the time step used for this evaluation is discussed below as
553well as the implication in term of starting or restarting a model
554simulation. Note that the time stepping is generally performed in a one step
555operation. With such a complex and nonlinear system of equations it would be dangerous to let a prognostic variable evolve in time for each term successively.
556
557The three level scheme requires three arrays for the prognostic variables. For each variable $x$ there is $x_b$ (before) and $x_n$ (now). The third array, although referred to as $x_a$ (after) in the code, is usually not the variable $x_a$ at the next time step; rather, it is used to store the time derivative (RHS in \eqref{Eq_DOM_nxt}) prior to time-stepping the equation. Generally, the time stepping is performed once at each time step in \mdl{tranxt} and \mdl{dynnxt} modules, excepted for implicit vertical diffusion or sea surface height when time-splitting options are used.
558
559% -------------------------------------------------------------------------------------------------------------
560%        Non-Diffusive Part---Leapfrog Scheme
561% -------------------------------------------------------------------------------------------------------------
562\subsection{Non-Diffusive Part --- Leapfrog Scheme}
563\label{DOM_nxt_leap_frog}
564
565The time stepping used for non-diffusive processes is the well-known
566leapfrog scheme. It is a time centred scheme, i.e. the RHS are evaluated at
567time step $t$, the now time step. It is only used for non-diffusive terms,
568that is momentum and tracer advection, pressure gradient, and coriolis
569terms. This scheme is widely used for advective processes in low-viscosity
570fluids. It is an efficient method that achieves second-order accuracy with
571just one right hand side evaluation per time step. Moreover, it does not
572artificially damp linear oscillatory motion nor does it produce instability
573by amplifying the oscillations. These advantages are somewhat diminished by
574the large phase-speed error of the leapfrog scheme, and the unsuitability of
575leapfrog differencing for the representation of diffusive and Rayleigh
576damping processes. However, the most serious problem associated with the
577leapfrog scheme is a high-frequency computational noise called
578"time-splitting" \citep{Haltiner1980} that develops when the method
579is used to model non linear fluid dynamics: the even and odd time steps tend
580to diverge between a physical and a computational mode. Time splitting can
581be controlled through the use of an Asselin time filter (first designed by
582\citep{Robert1966} and more comprehensively studied by \citet{Asselin1972}) or by
583periodically reinitialising the leapfrog solution through a single
584integration step with a two-level scheme. In OPA we follow the first
585strategy:
586\begin{equation} \label{Eq_DOM_nxt_asselin}
587x_F^t  = x^t + \gamma \, \left[ x_f^{t-\Delta t} - 2 x^t + x^{t+\Delta t} \right]
588\end{equation} 
589where the subscript $f$ denotes filtered values and $\gamma$ is the asselin coefficient. $\gamma$ is initialized as \np{atfp} (namelist parameter). Its default value is \np{atfp}=0.1.  This default value causes a significant dissipation of high frequency motions. Recommanded values in idealized studies of shallow water turbulence are two order of magnitude lower (\citep{Farge1987}). Both strategies do, nevertheless, degrade the accuracy of the calculation from second to first order. The leapfrog scheme associated to a Robert-Asselin
590time filter has been preferred to other time differencing schemes such as
591predictor corrector or trapezoidal schemes because the user can better
592control the magnitude and the spatial structure of the time diffusion of the
593scheme. In association with the centred space discretisation of the
594advective terms in the momentum and tracer equations, it avoids implicit
595numerical diffusion in both the time and space discretisation of the
596advective term: they are both set explicitly by the user through the Robert-Asselin filter parameter and the viscous and diffusive coefficients.
597
598%gm - reflexion about leapfrog: ongoing work with Matthieu Leclair
599% to be updated latter with addition of new time stepping strategy
600\amtcomment{
601\colorbox{yellow}{Note}:
6021- There is no reason why one should apply a same value of $\gamma$ on both momentum and tracer equations. In climate applications, one could found useful to use a lower value on tracer (quantity that one wants to conserve) than on the dynamics. We never explore this possibility.
603The Robert-Asselin time filter slightly departs from a simple second order time diffusive operator computed with a forward time stepping due to the presence of $x_f^{t-\Delta t}$ in the right hand side of  \ref{Eq_DOM_nxt_asselin}. The original willing of Robert1966 and Asselin1972 was to design a time filter that allow much larger parameter than 0.5.   is due to computer saving consideration. In the original asselin filter, $x^{t-\Delta t}$ is used instead:
604 \begin{equation} \label{Eq_DOM_nxt_asselin_true}
605x_f^t  = x^t + \gamma \, \left[ x^{t-\Delta t} - 2 x^t + x^{t+\Delta t} \right]
606\end{equation} 
607Applying a "true" Asselin time filter is nothing more than adding a harmonic diffusive operator in time. Indeed, equations \ref{Eq_DOM_nxt} and \ref{Eq_DOM_nxt_asselin_true} can be rewritten together as:
608\begin{equation} \label{Eq_DOM_nxt2}
609\begin{split}
610  \frac{ x^{t+\Delta t} - x^{t-\Delta t} } { 2 \,\Delta t } 
611  &\text{RHS}_x^{t-\Delta t,t,t+\Delta t} + \frac{ x_f^t  - x^t }{2 \,\Delta t} \\
612  &\text{RHS}_x^{t-\Delta t,t,t+\Delta t} + \gamma\ \frac{  \, \left[ x^{t-\Delta t} - 2 x^t + x^{t+\Delta t} \right] }{2 \,\Delta t}  \\
613  &\text{RHS}_x^{t-\Delta t,t,t+\Delta t} 
614  + 2 \Delta t \ \gamma \ \frac{1}{{2 \Delta t}^2} 
615   \,\delta_{t-1}\,\left[ \delta_{t+1/2}\left[ x^t \right] \right]
616  \end{split}
617\end{equation} 
618expressing this again in a continuous form, one finds that the Asselin filter leads to :
619\begin{equation} \label{Eq_DOM_nxt3}
620  \frac{ \partial x} { \partial t } =  \text{RHS} + 2 \,\Delta t \ \gamma \ \frac{ {\partial}^2 x}{ \partial t ^2 }
621\end{equation} 
622
623Equations  \ref{Eq_DOM_nxt2} and \ref{Eq_DOM_nxt3} suggest several remarks. First the Asselin filter is definitively a second order time diffusive operator which is evaluated at centered time step. The magnitude of this diffusion is proportional to the time step (with $\gamma$ usually taken between $10^{-1}$ to $10^{-3}$) . Second, this term has to be taken into account in all budgets of the equations (mass, heat content, salt content, kinetic energy...). Nevertheless,we stress here that it is small and does not create systematic biases. Indeed let us evaluate how it contributes to the time evolution of $x$ between $t_o$ and $t_1$:
624\begin{equation} \label{Eq_DOM_nxt4}
625\begin{split}
626 t_1-t_o &= \int_{t_o}^{t_1} \frac{ \partial x} { \partial t } dt \\
627      &= \int_{t_o}^{t_1} \text{RHS} dt + 2 \,\Delta t \ \gamma \left(
628        \left. \frac{ \partial x}{ \partial t } \right|_1
629      - \left. \frac{ \partial x}{ \partial t } \right|_\right)
630 \end{split}
631\end{equation} 
632}
633
634Alternative time stepping schemes are currently under investigation.
635
636% -------------------------------------------------------------------------------------------------------------
637%        Diffusive Part---Forward or Backward Scheme
638% -------------------------------------------------------------------------------------------------------------
639\subsection{Diffusive Part --- Forward or Backward Scheme}
640\label{DOM_nxt_forward_imp}
641
642The leapfrog differencing is unsuitable for the representation of diffusive
643and damping processes. For $D$, a horizontal diffusive terms and/or the
644restoring terms to a tracer climatology (when they are present, see
645\S~\ref{TRA_dmp}), a forward time differencing scheme is used :
646\begin{equation} \label{Eq_DOM_nxt_euler}
647   x^{t+\Delta t} = x^{t-\Delta t} + 2 \, \Delta t \  \text{RHS}_x^{t-\Delta t}
648\end{equation} 
649
650This is diffusive in time and conditionally stable. For example, the
651condition of stability for a second and fourth order horizontal diffusions are \citep{Griffies2004}:
652\begin{equation} \label{Eq_DOM_nxt_euler_stability}
653A^h < \left\{
654\begin{aligned}
655                    &\frac{e^2}{  8 \; \Delta t }  &&\quad \text{laplacian diffusion}  \\
656                    &\frac{e^4}{64 \; \Delta t }   &&\quad \text{bilaplacian diffusion} 
657            \end{aligned}
658\right.
659\end{equation}
660where $e$ is the smallest grid size in the two horizontal direction and $A^h$ the mixing coefficient. The linear constraint \eqref{Eq_DOM_nxt_euler_stability} is a necessary condition, but not sufficient. If it is not satisfied, even mildly, then the model soon becomes wildly unstable. The instability can be removed by either reducing the time steps or reducing the mixing coefficient.
661
662For the vertical diffusion terms, a forward time differencing scheme can be
663used, but usually the numerical stability condition implies a strong
664constraint on the time step. Two solutions are available in OPA to overcome
665the stability constraint: $(a)$ a forward time differencing scheme using a
666time splitting technique (\np{ln\_zdfexp}=T) or $(b)$ a backward (or implicit)
667time differencing scheme by \np{ln\_zdfexp}=F). In $(a)$, the master
668time step $\Delta $t is cut into $N$ fractional time steps so that the
669stability criterion is reduced by a factor of $N$. The computation is done as
670follows:
671\begin{equation} \label{Eq_DOM_nxt_ts}
672\begin{split}
673& u_\ast ^{t-\Delta t} = u^{t-\Delta t}   \\
674& u_\ast ^{t-\Delta t+L\frac{2\Delta t}{N}}=u_\ast ^{t-\Delta t+\left( {L-1} 
675\right)\frac{2\Delta t}{N}}+\frac{2\Delta t}{N}\;\text{DF}^{t-\Delta t+\left( {L-1} \right)\frac{2\Delta t}{N}}
676        \quad \text{for $L=1$ to $N$}      \\
677& u^{t+\Delta t} = u_\ast^{t+\Delta t}
678\end{split}
679\end{equation}
680with DF a vertical diffusion term. The number of fractional time steps, $N$, is given by setting \np{n\_zdfexp}, (namelist parameter). The scheme $(b)$ is unconditionally stable but diffusive. It can be written as follows:
681\begin{equation} \label{Eq_DOM_nxt_imp}
682   x^{t+\Delta t} = x^{t-\Delta t} + 2 \, \Delta t \  \text{RHS}_x^{t+\Delta t}
683\end{equation} 
684
685This scheme is rather time consuming since it requires a matrix inversion,
686but it becomes attractive since a splitting factor of 3 or more is needed
687for the forward time differencing scheme. For example, the finite difference
688approximation of the temperature equation is:
689\begin{equation} \label{Eq_DOM_nxt_imp_zdf}
690\frac{T(k)^{t+1}-T(k)^{t-1}}{2\;\Delta t}\equiv \text{RHS}+\frac{1}{e_{3T} }\delta 
691_k \left[ {\frac{A_w^{vT} }{e_{3w} }\delta _{k+1/2} \left[ {T^{t+1}} \right]} 
692\right]
693\end{equation}
694where RHS is the right hand side of the equation except the vertical diffusion term. We rewrite \eqref{Eq_DOM_nxt_imp} as:
695\begin{equation} \label{Eq_DOM_nxt_imp_mat}
696-c(k+1)\;u^{t+1}(k+1)+d(k)\;u^{t+1}(k)-\;c(k)\;u^{t+1}(k-1) \equiv b(k)
697\end{equation}
698where
699\begin{align*} 
700 c(k) &= A_w^{vm} (k) \, / \, e_{3uw} (k)     \\
701 d(k) &= e_{3u} (k)       \, / \, (2\Delta t) + c_k + c_{k+1}    \\
702 b(k) &= e_{3u} (k) \; \left( u^{t-1}(k) \, / \, (2\Delta t) + \text{RHS} \right)   
703\end{align*}
704
705\eqref{Eq_DOM_nxt_imp_mat} is a linear system of equations. All the elements of the corresponding matrix vanish except those on the diagonals. Moreover, $c(k)$ and $d(k)$ are positive and the diagonal term is greater than the sum of the
706two extra-diagonal terms, therefore a special adaptation of the Gauss elimination procedure is used to find the solution (see for example \citet{Richtmyer1967}).
707
708% -------------------------------------------------------------------------------------------------------------
709%        Start/Restart strategy
710% -------------------------------------------------------------------------------------------------------------
711\subsection{Start/Restart strategy}
712\label{DOM_nxt_rst}
713%--------------------------------------------namrun-------------------------------------------
714\namdisplay{namrun}         
715%--------------------------------------------------------------------------------------------------------------
716The first time step of this three level scheme when starting from initial conditions is a forward step (Euler time integration): $x^1 = x^0 + \Delta t \ \text{RHS}^0$.
717
718It is also possible to restart from a previous computation, by using a
719restart file. The restart strategy is designed to ensure perfect
720restartability of the code: the user should obtain the same results to
721machine precision either by running the model for $2N$ time steps in one go,
722or by performing two consecutive experiments of $N$ steps with a restart. This
723requires saving two time levels and many auxiliary data in the restart files
724in double precision.
725
726
727%-------------------------------------------------------------------------------------------------------------
728%        Time Domain
729% -------------------------------------------------------------------------------------------------------------
730\subsection{Time domain}
731\label{DOM_nxt_time}
732
733 \colorbox{yellow}{add here a few word on nit000 and nitend}
734
735 \colorbox{yellow}{Write documentation on the calendar and the key variable adatrj}
736
737
738
Note: See TracBrowser for help on using the repository browser.