# source:NEMO/trunk/doc/latex/NEMO/subfiles/chap_DOM.tex@11543

Last change on this file since 11543 was 11543, checked in by nicolasmartin, 23 months ago

Implementation of convention for labelling references + files renaming
Now each reference is supposed to have the information of the chapter in its name
to identify quickly which file contains the reference (\label{$prefix:$chap_...)

Rename the appendices from 'annex_' to 'apdx_' to conform with the prefix used in labels (apdx:...)
Suppress the letter numbering

File size: 37.4 KB
Line
1\documentclass[../main/NEMO_manual]{subfiles}
2
3\begin{document}
4% ================================================================
5% Chapter 2 ——— Space and Time Domain (DOM)
6% ================================================================
7\chapter{Space Domain (DOM)}
8\label{chap:DOM}
9
10%\chaptertoc
11
12% Missing things:
13%  - istate: description of the initial state   ==> this has to be put elsewhere..
14%                  perhaps in MISC ?  By the way the initialisation of T S and dynamics
15%                  should be put outside of DOM routine (better with TRC staff and off-line
16%                  tracers)
17%  -geo2ocean:  how to switch from geographic to mesh coordinate
18%     - domclo:  closed sea and lakes.... management of closea sea area : specific to global configuration, both forced and coupled
19
20\vfill
21
22\begin{table}[b]
23  \footnotesize
24  \caption*{Changes record}
25  \begin{tabularx}{\textwidth}{l||X|X}
26    Release & Author(s) & Modifications                                                          \\
27    \hline
28    {\em 4.0} & {\em Simon M\"{u}ller \& Andrew Coward} &
29    {\em
30      Compatibility changes Major simplification has moved many of the options to external domain configuration tools.
31      (see \autoref{apdx:DOMCFG})
32    }                                                                                            \\
33    {\em 3.x} & {\em Rachid Benshila, Gurvan Madec \& S\'{e}bastien Masson} &
34    {\em First version}                                                                          \\
35  \end{tabularx}
36\end{table}
37
38\newpage
39
40Having defined the continuous equations in \autoref{chap:MB} and chosen a time discretisation \autoref{chap:TD},
41we need to choose a grid for spatial discretisation and related numerical algorithms.
42In the present chapter, we provide a general description of the staggered grid used in \NEMO,
43and other relevant information about the DOM (DOMain) source code modules.
44
45% ================================================================
46% Fundamentals of the Discretisation
47% ================================================================
48\section{Fundamentals of the discretisation}
49\label{sec:DOM_basics}
50
51% -------------------------------------------------------------------------------------------------------------
52%        Arrangement of Variables
53% -------------------------------------------------------------------------------------------------------------
54\subsection{Arrangement of variables}
55\label{subsec:DOM_cell}
56
57%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
58\begin{figure}[!tb]
59  \begin{center}
60    \includegraphics[width=\textwidth]{Fig_cell}
61    \caption{
62      \protect\label{fig:DOM_cell}
63      Arrangement of variables.
64      $t$ indicates scalar points where temperature, salinity, density, pressure and
65      horizontal divergence are defined.
66      $(u,v,w)$ indicates vector points, and $f$ indicates vorticity points where both relative and
67      planetary vorticities are defined.
68    }
69  \end{center}
70\end{figure}
71%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
72
73The numerical techniques used to solve the Primitive Equations in this model are based on the traditional,
74centred second-order finite difference approximation.
75Special attention has been given to the homogeneity of the solution in the three spatial directions.
76The arrangement of variables is the same in all directions.
77It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with vector points $(u, v, w)$ defined in
78the centre of each face of the cells (\autoref{fig:DOM_cell}).
79This is the generalisation to three dimensions of the well-known C'' grid in Arakawa's classification
80\citep{mesinger.arakawa_bk76}.
81The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge and
82the barotropic stream function $\psi$ is defined at horizontal points overlying the $\zeta$ and $f$-points.
83
84The ocean mesh (\ie\ the position of all the scalar and vector points) is defined by the transformation that
85gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$.
86The grid-points are located at integer or integer and a half value of $(i,j,k)$ as indicated on \autoref{tab:DOM_cell}.
87In all the following, subscripts $u$, $v$, $w$, $f$, $uw$, $vw$ or $fw$ indicate the position of
88the grid-point where the scale factors are defined.
89Each scale factor is defined as the local analytical value provided by \autoref{eq:MB_scale_factors}.
90As a result, the mesh on which partial derivatives $\pd[]{\lambda}$, $\pd[]{\varphi}$ and
91$\pd[]{z}$ are evaluated is a uniform mesh with a grid size of unity.
92Discrete partial derivatives are formulated by the traditional, centred second order finite difference approximation
93while the scale factors are chosen equal to their local analytical value.
94An important point here is that the partial derivative of the scale factors must be evaluated by
95centred finite difference approximation, not from their analytical expression.
96This preserves the symmetry of the discrete set of equations and therefore satisfies many of
97the continuous properties (see \autoref{apdx:INVARIANTS}).
99when needed, an area, volume, or the total ocean depth must be evaluated as the product or sum of the relevant scale factors
100(see \autoref{eq:DOM_bar} in the next section).
101
102%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
103\begin{table}[!tb]
104  \begin{center}
105    \begin{tabular}{|p{46pt}|p{56pt}|p{56pt}|p{56pt}|}
106      \hline
107      t  & $i$ & $j$ & $k$ \\
108      \hline
109      u  & $i + 1/2$ & $j$ & $k$ \\
110      \hline
111      v  & $i$ & $j + 1/2$ & $k$ \\
112      \hline
113      w  & $i$ & $j$ & $k + 1/2$ \\
114      \hline
115      f  & $i + 1/2$ & $j + 1/2$ & $k$ \\
116      \hline
117      uw & $i + 1/2$ & $j$ & $k + 1/2$ \\
118      \hline
119      vw & $i$ & $j + 1/2$ & $k + 1/2$ \\
120      \hline
121      fw & $i + 1/2$ & $j + 1/2$ & $k + 1/2$ \\
122      \hline
123    \end{tabular}
124    \caption{
125      \protect\label{tab:DOM_cell}
126      Location of grid-points as a function of integer or integer and a half value of the column, line or level.
127      This indexing is only used for the writing of the semi -discrete equations.
128      In the code, the indexing uses integer values only and is positive downwards in the vertical with $k=1$ at the surface.
129      (see \autoref{subsec:DOM_Num_Index})
130    }
131  \end{center}
132\end{table}
133%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
134
135Note that the definition of the scale factors
136(\ie\ as the analytical first derivative of the transformation that
137results in $(\lambda,\varphi,z)$ as a function of $(i,j,k)$)
138is specific to the \NEMO\ model \citep{marti.madec.ea_JGR92}.
139As an example, a scale factor in the $i$ direction is defined locally at a $t$-point,
140whereas many other models on a C grid choose to define such a scale factor as
141the distance between the $u$-points on each side of the $t$-point.
142Relying on an analytical transformation has two advantages:
143firstly, there is no ambiguity in the scale factors appearing in the discrete equations,
144since they are first introduced in the continuous equations;
145secondly, analytical transformations encourage good practice by the definition of smoothly varying grids
146(rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{treguier.dukowicz.ea_JGR96}.
147An example of the effect of such a choice is shown in \autoref{fig:DOM_zgr_e3}.
148%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
149\begin{figure}[!t]
150  \begin{center}
151    \includegraphics[width=\textwidth]{Fig_zgr_e3}
152    \caption{
153      \protect\label{fig:DOM_zgr_e3}
154      Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical,
155      and (b) analytically derived grid-point position and scale factors.
156      For both grids here, the same $w$-point depth has been chosen but
157      in (a) the $t$-points are set half way between $w$-points while
158      in (b) they are defined from an analytical function:
159      $z(k) = 5 \, (k - 1/2)^3 - 45 \, (k - 1/2)^2 + 140 \, (k - 1/2) - 150$.
160      Note the resulting difference between the value of the grid-size $\Delta_k$ and
161      those of the scale factor $e_k$.
162    }
163  \end{center}
164\end{figure}
165%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
166
167% -------------------------------------------------------------------------------------------------------------
168%        Vector Invariant Formulation
169% -------------------------------------------------------------------------------------------------------------
170\subsection{Discrete operators}
171\label{subsec:DOM_operators}
172
173Given the values of a variable $q$ at adjacent points, the differencing and averaging operators at
174the midpoint between them are:
175\begin{alignat*}{2}
176  % \label{eq:DOM_di_mi}
177  \delta_i [q]      &= &       &q (i + 1/2) - q (i - 1/2) \\
178  \overline q^{\, i} &= &\big\{ &q (i + 1/2) + q (i - 1/2) \big\} / 2
179\end{alignat*}
180
181Similar operators are defined with respect to $i + 1/2$, $j$, $j + 1/2$, $k$, and $k + 1/2$.
182Following \autoref{eq:MB_grad} and \autoref{eq:MB_lap}, the gradient of a variable $q$ defined at a $t$-point has
183its three components defined at $u$-, $v$- and $w$-points while its Laplacian is defined at the $t$-point.
184These operators have the following discrete forms in the curvilinear $s$-coordinates system:
185$186 % \label{eq:DOM_grad} 187 \nabla q \equiv \frac{1}{e_{1u}} \delta_{i + 1/2} [q] \; \, \vect i 188 + \frac{1}{e_{2v}} \delta_{j + 1/2} [q] \; \, \vect j 189 + \frac{1}{e_{3w}} \delta_{k + 1/2} [q] \; \, \vect k 190$
191\begin{multline*}
192  % \label{eq:DOM_lap}
193  \Delta q \equiv   \frac{1}{e_{1t} \, e_{2t} \, e_{3t}}
194                    \; \lt[   \delta_i \lt( \frac{e_{2u} \, e_{3u}}{e_{1u}} \; \delta_{i + 1/2} [q] \rt)
195                            + \delta_j \lt( \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [q] \rt) \; \rt] \\
196                  + \frac{1}{e_{3t}}
197                              \delta_k \lt[ \frac{1              }{e_{3w}} \; \delta_{k + 1/2} [q] \rt]
198\end{multline*}
199
200Following \autoref{eq:MB_curl} and \autoref{eq:MB_div}, a vector $\vect A = (a_1,a_2,a_3)$ defined at
201vector points $(u,v,w)$ has its three curl components defined at $vw$-, $uw$, and $f$-points, and
202its divergence defined at $t$-points:
203\begin{multline}
204% \label{eq:DOM_curl}
205  \nabla \times \vect A \equiv   \frac{1}{e_{2v} \, e_{3vw}}
206                                 \Big[   \delta_{j + 1/2} (e_{3w} \, a_3)
207                                       - \delta_{k + 1/2} (e_{2v} \, a_2) \Big] \vect i \\
208                               + \frac{1}{e_{2u} \, e_{3uw}}
209                                 \Big[   \delta_{k + 1/2} (e_{1u} \, a_1)
210                                       - \delta_{i + 1/2} (e_{3w} \, a_3) \Big] \vect j \\
211                               + \frac{1}{e_{1f} \, e_{2f}}
212                                 \Big[   \delta_{i + 1/2} (e_{2v} \, a_2)
213                                       - \delta_{j + 1/2} (e_{1u} \, a_1) \Big] \vect k
214\end{multline}
215\begin{equation}
216% \label{eq:DOM_div}
217  \nabla \cdot \vect A \equiv   \frac{1}{e_{1t} \, e_{2t} \, e_{3t}}
218                                \Big[ \delta_i (e_{2u} \, e_{3u} \, a_1) + \delta_j (e_{1v} \, e_{3v} \, a_2) \Big]
219                              + \frac{1}{e_{3t}} \delta_k (a_3)
220\end{equation}
221
222The vertical average over the whole water column is denoted by an overbar and is for
223a masked field $q$ (\ie\ a quantity that is equal to zero inside solid areas):
224\begin{equation}
225  \label{eq:DOM_bar}
226  \bar q = \frac{1}{H} \int_{k^b}^{k^o} q \; e_{3q} \, dk \equiv \frac{1}{H_q} \sum \limits_k q \; e_{3q}
227\end{equation}
228where $H_q$  is the ocean depth, which is the masked sum of the vertical scale factors at $q$ points,
229$k^b$ and $k^o$ are the bottom and surface $k$-indices, and the symbol $\sum \limits_k$ refers to a summation over
230all grid points of the same type in the direction indicated by the subscript (here $k$).
231
232In continuous form, the following properties are satisfied:
233\begin{gather}
235  \nabla \times \nabla q = \vect 0 \\
236  \label{eq:DOM_div_curl}
237  \nabla \cdot (\nabla \times \vect A) = 0
238\end{gather}
239
240It is straightforward to demonstrate that these properties are verified locally in discrete form as soon as
241the scalar $q$ is taken at $t$-points and the vector $\vect A$ has its components defined at
242vector points $(u,v,w)$.
243
244Let $a$ and $b$ be two fields defined on the mesh, with a value of zero inside continental areas.
245It can be shown that the differencing operators ($\delta_i$, $\delta_j$ and $\delta_k$)
246are skew-symmetric linear operators, and further that the averaging operators $\overline{\cdots}^{\, i}$,
247$\overline{\cdots}^{\, j}$ and $\overline{\cdots}^{\, k}$) are symmetric linear operators, \ie
248\begin{alignat}{4}
250  &\sum \limits_i a_i \; \delta_i [b]      &\equiv &- &&\sum \limits_i \delta      _{   i + 1/2} [a] &b_{i + 1/2} \\
252  &\sum \limits_i a_i \; \overline b^{\, i} &\equiv &  &&\sum \limits_i \overline a ^{\, i + 1/2}     &b_{i + 1/2}
253\end{alignat}
254
255In other words, the adjoint of the differencing and averaging operators are $\delta_i^* = \delta_{i + 1/2}$ and
256$(\overline{\cdots}^{\, i})^* = \overline{\cdots}^{\, i + 1/2}$, respectively.
257These two properties will be used extensively in the \autoref{apdx:INVARIANTS} to
258demonstrate integral conservative properties of the discrete formulation chosen.
259
260% -------------------------------------------------------------------------------------------------------------
261%        Numerical Indexing
262% -------------------------------------------------------------------------------------------------------------
263\subsection{Numerical indexing}
264\label{subsec:DOM_Num_Index}
265
266%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
267\begin{figure}[!tb]
268  \begin{center}
269    \includegraphics[width=\textwidth]{Fig_index_hor}
270    \caption{
271      \protect\label{fig:DOM_index_hor}
272      Horizontal integer indexing used in the \fortran code.
273      The dashed area indicates the cell in which variables contained in arrays have the same $i$- and $j$-indices
274    }
275  \end{center}
276\end{figure}
277%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
278
279The array representation used in the \fortran code requires an integer indexing.
280However, the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with the use of
281integer values for $t$-points only while all the other points involve integer and a half values.
282Therefore, a specific integer indexing has been defined for points other than $t$-points
283(\ie\ velocity and vorticity grid-points).
284Furthermore, the direction of the vertical indexing has been reversed and the surface level set at $k = 1$.
285
286% -----------------------------------
287%        Horizontal Indexing
288% -----------------------------------
289\subsubsection{Horizontal indexing}
290\label{subsec:DOM_Num_Index_hor}
291
292The indexing in the horizontal plane has been chosen as shown in \autoref{fig:DOM_index_hor}.
293For an increasing $i$ index ($j$ index),
294the $t$-point and the eastward $u$-point (northward $v$-point) have the same index
295(see the dashed area in \autoref{fig:DOM_index_hor}).
296A $t$-point and its nearest north-east $f$-point have the same $i$-and $j$-indices.
297
298% -----------------------------------
299%        Vertical indexing
300% -----------------------------------
301\subsubsection{Vertical indexing}
302\label{subsec:DOM_Num_Index_vertical}
303
304In the vertical, the chosen indexing requires special attention since the direction of the $k$-axis in
305the \fortran code is the reverse of that used in the semi -discrete equations and
306given in \autoref{subsec:DOM_cell}.
307The sea surface corresponds to the $w$-level $k = 1$, which is the same index as the $t$-level just below
308(\autoref{fig:DOM_index_vert}).
309The last $w$-level ($k = jpk$) either corresponds to or is below the ocean floor while
310the last $t$-level is always outside the ocean domain (\autoref{fig:DOM_index_vert}).
311Note that a $w$-point and the directly underlaying $t$-point have a common $k$ index
312(\ie\ $t$-points and their nearest $w$-point neighbour in negative index direction),
313in contrast to the indexing on the horizontal plane where the $t$-point has the same index as
314the nearest velocity points in the positive direction of the respective horizontal axis index
315(compare the dashed area in \autoref{fig:DOM_index_hor} and \autoref{fig:DOM_index_vert}).
316Since the scale factors are chosen to be strictly positive,
317a \textit{minus sign} is included in the \fortran implementations of
318\textit{all the vertical derivatives} of the discrete equations given in this manual in order to
319accommodate the opposing vertical index directions in implementation and documentation.
320
321%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
322\begin{figure}[!pt]
323  \begin{center}
324    \includegraphics[width=\textwidth]{Fig_index_vert}
325    \caption{
326      \protect\label{fig:DOM_index_vert}
327      Vertical integer indexing used in the \fortran code.
328      Note that the $k$-axis is oriented downward.
329      The dashed area indicates the cell in which variables contained in arrays have a common $k$-index.
330    }
331  \end{center}
332\end{figure}
333%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
334
335% -------------------------------------------------------------------------------------------------------------
336%        Domain configuration
337% -------------------------------------------------------------------------------------------------------------
338\section{Spatial domain configuration}
339\label{subsec:DOM_config}
340
341\nlst{namcfg}
342
343Two typical methods are available to specify the spatial domain configuration;
344they can be selected using parameter \np{ln\_read\_cfg} parameter in namelist \nam{cfg}.
345
346If \np{ln\_read\_cfg} is set to \forcode{.true.},
347the domain-specific parameters and fields are read from a netCDF input file,
348whose name (without its .nc suffix) can be specified as the value of the \np{cn\_domcfg} parameter in namelist \nam{cfg}.
349
350If \np{ln\_read\_cfg} is set to \forcode{.false.},
351the domain-specific parameters and fields can be provided (\eg\ analytically computed) by
352subroutines \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}.
353These subroutines can be supplied in the \path{MY_SRC} directory of the configuration,
354and default versions that configure the spatial domain for the GYRE reference configuration are present in
355the \path{./src/OCE/USR} directory.
356
357In version 4.0 there are no longer any options for reading complex bathymetries and
358performing a vertical discretisation at run-time.
359Whilst it is occasionally convenient to have a common bathymetry file and, for example,
360to run similar models with and without partial bottom boxes and/or sigma-coordinates,
361supporting such choices leads to overly complex code.
362Worse still is the difficulty of ensuring the model configurations intended to be identical are indeed so when
363the model domain itself can be altered by runtime selections.
364The code previously used to perform vertical discretisation has been incorporated into an external tool
365(\path{./tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMCFG}.
366
367The next subsections summarise the parameter and fields related to the configuration of the whole model domain.
368These represent the minimum information that must be provided either via the \np{cn\_domcfg} file or set by code
369inserted into user-supplied versions of the \texttt{usrdef\_*} subroutines.
370The requirements are presented in three sections:
371the domain size (\autoref{subsec:DOM_size}), the horizontal mesh (\autoref{subsec:DOM_hgr}),
372and the vertical grid (\autoref{subsec:DOM_zgr}).
373
374% -----------------------------------
375%        Domain Size
376% -----------------------------------
377\subsection{Domain size}
378\label{subsec:DOM_size}
379
380The total size of the computational domain is set by the parameters \jp{jpiglo}, \jp{jpjglo} and \jp{jpkglo} for
381the $i$, $j$ and $k$ directions, respectively.
382Note, that the variables \texttt{jpi} and \texttt{jpj} refer to the size of each processor subdomain when
383the code is run in parallel using domain decomposition (\key{mpp\_mpi} defined,
384see \autoref{sec:LBC_mpp}).
385
386The name of the configuration is set through parameter \np{cn\_cfg},
387and the nominal resolution through parameter \np{nn\_cfg}
388(unless in the input file both of variables \texttt{ORCA} and \texttt{ORCA\_index} are present,
389in which case \np{cn\_cfg} and \np{nn\_cfg} are set from these values accordingly).
390
391The global lateral boundary condition type is selected from 8 options using parameter \jp{jperio}.
392See \autoref{sec:LBC_jperio} for details on the available options and the corresponding values for \jp{jperio}.
393
394% ================================================================
395% Domain: Horizontal Grid (mesh)
396% ================================================================
397\subsection{Horizontal grid mesh (\protect\mdl{domhgr})}
398\label{subsec:DOM_hgr}
399
400% ================================================================
401% Domain: List of hgr-related fields needed
402% ================================================================
404\label{sec:DOM_hgr_fields}
405
406The explicit specification of a range of mesh-related fields are required for the definition of a configuration.
407These include:
408
409\begin{clines}
410int    jpiglo, jpjglo, jpkglo            /* global domain sizes                                          */
411int    jperio                            /* lateral global domain b.c.                                   */
412double glamt, glamu, glamv, glamf        /* geographic longitude (t,u,v and f points respectively)       */
413double gphit, gphiu, gphiv, gphif        /* geographic latitude                                          */
414double e1t, e1u, e1v, e1f                /* horizontal scale factors                                     */
415double e2t, e2u, e2v, e2f                /* horizontal scale factors                                     */
416\end{clines}
417
418The values of the geographic longitude and latitude arrays at indices $i,j$ correspond to
419the analytical expressions of the longitude $\lambda$ and latitude $\varphi$ as a function of $(i,j)$,
420evaluated at the values as specified in \autoref{tab:DOM_cell} for the respective grid-point position.
421The calculation of the values of the horizontal scale factor arrays in general additionally involves
422partial derivatives of $\lambda$ and $\varphi$ with respect to $i$ and $j$,
423evaluated for the same arguments as $\lambda$ and $\varphi$.
424
425\subsubsection{Optional fields}
426
427\begin{clines}
428                                         /* Optional:                                                    */
429int    ORCA, ORCA_index                  /* configuration name, configuration resolution                 */
430double e1e2u, e1e2v                      /* U and V surfaces (if grid size reduction in some straits)    */
431double ff_f, ff_t                        /* Coriolis parameter (if not on the sphere)                    */
432\end{clines}
433
434\NEMO\ can support the local reduction of key strait widths by
435altering individual values of e2u or e1v at the appropriate locations.
436This is particularly useful for locations such as Gibraltar or Indonesian Throughflow pinch-points
437(see \autoref{sec:MISC_strait} for illustrated examples).
438The key is to reduce the faces of $T$-cell (\ie\ change the value of the horizontal scale factors at $u$- or $v$-point) but
439not the volume of the cells.
440Doing otherwise can lead to numerical instability issues.
441In normal operation the surface areas are computed from $e1u * e2u$ and $e1v * e2v$ but
442in cases where a gridsize reduction is required,
443the unaltered surface areas at $u$ and $v$ grid points (\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or
444pre-computed in \mdl{usrdef\_hgr}.
445If these arrays are present in the \np{cn\_domcfg} file they are read and the internal computation is suppressed.
446Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{e1e2u} and \texttt{e1e2v} should set
447the surface-area computation flag:
448\texttt{ie1e2u\_v} to a non-zero value to suppress their re-computation.
449
450\smallskip
451Similar logic applies to the other optional fields:
452\texttt{ff\_f} and \texttt{ff\_t} which can be used to provide the Coriolis parameter at F- and T-points respectively if
453the mesh is not on a sphere.
454If present these fields will be read and used and the normal calculation ($2 * \Omega * \sin(\varphi)$) suppressed.
455Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{ff\_f} and \texttt{ff\_t} should set
456the Coriolis computation flag:
457\texttt{iff} to a non-zero value to suppress their re-computation.
458
459Note that longitudes, latitudes, and scale factors at $w$ points are exactly equal to those of $t$ points,
460thus no specific arrays are defined at $w$ points.
461
462
463% ================================================================
464% Domain: Vertical Grid (domzgr)
465% ================================================================
466\subsection[Vertical grid (\textit{domzgr.F90})]
467{Vertical grid (\protect\mdl{domzgr})}
468\label{subsec:DOM_zgr}
469%-----------------------------------------namdom-------------------------------------------
470\nlst{namdom}
471%-------------------------------------------------------------------------------------------------------------
472
473In the vertical, the model mesh is determined by four things:
474\begin{enumerate}
475  \item the bathymetry given in meters;
476  \item the number of levels of the model (\jp{jpk});
477  \item the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and
478  \item the masking system, \ie\ the number of wet model levels at each
479$(i,j)$ location of the horizontal grid.
480\end{enumerate}
481
482%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
483\begin{figure}[!tb]
484  \begin{center}
485    \includegraphics[width=\textwidth]{Fig_z_zps_s_sps}
486    \caption{
487      \protect\label{fig:DOM_z_zps_s_sps}
488      The ocean bottom as seen by the model:
489      (a) $z$-coordinate with full step,
490      (b) $z$-coordinate with partial step,
491      (c) $s$-coordinate: terrain following representation,
492      (d) hybrid $s-z$ coordinate,
493      (e) hybrid $s-z$ coordinate with partial step, and
494      (f) same as (e) but in the non-linear free surface (\protect\np{ln\_linssh}\forcode{=.false.}).
495      Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e).
496    }
497  \end{center}
498\end{figure}
499%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
500
501The choice of a vertical coordinate is made when setting up the configuration;
502it is not intended to be an option which can be changed in the middle of an experiment.
503The one exception to this statement being the choice of linear or non-linear free surface.
504In v4.0 the linear free surface option is implemented as a special case of the non-linear free surface.
505This is computationally wasteful since it uses the structures for time-varying 3D metrics
506for fields that (in the linear free surface case) are fixed.
507However, the linear free-surface is rarely used and implementing it this way means
508a single configuration file can support both options.
509
510By default a non-linear free surface is used (\np{ln\_linssh} set to \forcode{=.false.} in \nam{dom}):
511the coordinate follow the time-variation of the free surface so that the transformation is time dependent:
512$z(i,j,k,t)$ (\eg\ \autoref{fig:DOM_z_zps_s_sps}f).
513When a linear free surface is assumed (\np{ln\_linssh} set to \forcode{=.true.} in \nam{dom}),
514the vertical coordinates are fixed in time, but the seawater can move up and down across the $z_0$ surface
515(in other words, the top of the ocean in not a rigid lid).
516
517Note that settings:
518\np{ln\_zco}, \np{ln\_zps}, \np{ln\_sco} and \np{ln\_isfcav} mentioned in the following sections
519appear to be namelist options but they are no longer truly namelist options for \NEMO.
520Their value is written to and read from the domain configuration file and
521they should be treated as fixed parameters for a particular configuration.
522They are namelist options for the \texttt{DOMAINcfg} tool that can be used to build the configuration file and
523serve both to provide a record of the choices made whilst building the configuration and
524to trigger appropriate code blocks within \NEMO.
525These values should not be altered in the \np{cn\_domcfg} file.
526
527\medskip
528The decision on these choices must be made when the \np{cn\_domcfg} file is constructed.
529Three main choices are offered (\autoref{fig:DOM_z_zps_s_sps}a-c):
530
531\begin{itemize}
532\item $z$-coordinate with full step bathymetry (\np{ln\_zco}\forcode{=.true.}),
533\item $z$-coordinate with partial step ($zps$) bathymetry (\np{ln\_zps}\forcode{=.true.}),
534\item Generalized, $s$-coordinate (\np{ln\_sco}\forcode{=.true.}).
535\end{itemize}
536
537Additionally, hybrid combinations of the three main coordinates are available:
538$s-z$ or $s-zps$ coordinate (\autoref{fig:DOM_z_zps_s_sps}d and \autoref{fig:DOM_z_zps_s_sps}e).
539
540A further choice related to vertical coordinate concerns
541the presence (or not) of ocean cavities beneath ice shelves within the model domain.
542A setting of \np{ln\_isfcav} as \forcode{.true.} indicates that the domain contains ocean cavities,
543otherwise the top, wet layer of the ocean will always be at the ocean surface.
544This option is currently only available for $z$- or $zps$-coordinates.
545In the latter case, partial steps are also applied at the ocean/ice shelf interface.
546
547Within the model, the arrays describing the grid point depths and vertical scale factors are three set of
548three dimensional arrays $(i,j,k)$ defined at \textit{before}, \textit{now} and \textit{after} time step.
549The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively.
550They are updated at each model time step.
551The initial fixed reference coordinate system is held in variable names with a $\_0$ suffix.
552When the linear free surface option is used (\np{ln\_linssh}\forcode{=.true.}),
553\textit{before}, \textit{now} and \textit{after} arrays are initially set to
554their reference counterpart and remain fixed.
555
557\label{sec:DOM_zgr_fields}
558
559The explicit specification of a range of fields related to the vertical grid are required for
560the definition of a configuration.
561These include:
562
563\begin{clines}
564int    ln_zco, ln_zps, ln_sco            /* flags for z-coord, z-coord with partial steps and s-coord    */
565int    ln_isfcav                         /* flag  for ice shelf cavities                                 */
566double e3t_1d, e3w_1d                    /* reference vertical scale factors at T and W points           */
567double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0 /* vertical scale factors 3D coordinate at T,U,V,F and W points */
568double e3uw_0, e3vw_0                    /* vertical scale factors 3D coordinate at UW and VW points     */
569int    bottom_level, top_level           /* last wet T-points, 1st wet T-points (for ice shelf cavities) */
570                                         /* For reference:                                               */
571float  bathy_metry                       /* bathymetry used in setting top and bottom levels             */
572\end{clines}
573
574This set of vertical metrics is sufficient to describe the initial depth and thickness of every gridcell in
575the model regardless of the choice of vertical coordinate.
576With constant z-levels, e3 metrics will be uniform across each horizontal level.
577In the partial step case each e3 at the \jp{bottom\_level}
578(and, possibly, \jp{top\_level} if ice cavities are present)
579may vary from its horizontal neighbours.
580And, in s-coordinates, variations can occur throughout the water column.
581With the non-linear free-surface, all the coordinates behave more like the s-coordinate in
582that variations occur throughout the water column with displacements related to the sea surface height.
583These variations are typically much smaller than those arising from bottom fitted coordinates.
584The values for vertical metrics supplied in the domain configuration file can be considered as
585those arising from a flat sea surface with zero elevation.
586
587The \jp{bottom\_level} and \jp{top\_level} 2D arrays define the \jp{bottom\_level} and top wet levels in each grid column.
588Without ice cavities, \jp{top\_level} is essentially a land mask (0 on land; 1 everywhere else).
589With ice cavities, \jp{top\_level} determines the first wet point below the overlying ice shelf.
590
591
592% -------------------------------------------------------------------------------------------------------------
594% -------------------------------------------------------------------------------------------------------------
596\label{subsec:DOM_msk}
597
598
599From \jp{top\_level} and \jp{bottom\_level} fields, the mask fields are defined as follows:
600\begin{alignat*}{2}
602    \begin{cases}
603                  0 &\text{if $k < top\_level(i,j)$} \\
604                  1 &\text{if $bottom\_level(i,j) \leq k \leq top\_level(i,j)$} \\
605                  0 &\text{if $k > bottom\_level(i,j)$}
606    \end{cases}
607  \\
614\end{alignat*}
615
616Note that, without ice shelves cavities,
617masks at $t-$ and $w-$points are identical with the numerical indexing used (\autoref{subsec:DOM_Num_Index}).
618Nevertheless, $wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface)
619exactly in the same way as for the bottom boundary.
620
621%% The specification of closed lateral boundaries requires that at least
622%% the first and last rows and columns of the \textit{mbathy} array are set to zero.
623%% In the particular case of an east-west cyclical boundary condition, \textit{mbathy} has its last column equal to
624%% the second one and its first column equal to the last but one (and so too the mask arrays)
625%% (see \autoref{fig:LBC_jperio}).
626
627
628%-------------------------------------------------------------------------------------------------
629%        Closed seas
630%-------------------------------------------------------------------------------------------------
631\subsection{Closed seas} \label{subsec:DOM_closea}
632
633When a global ocean is coupled to an atmospheric model it is better to represent all large water bodies
634(\eg\ Great Lakes, Caspian sea \dots) even if the model resolution does not allow their communication with
635the rest of the ocean.
636This is unnecessary when the ocean is forced by fixed atmospheric conditions,
637so these seas can be removed from the ocean domain.
638The user has the option to set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}) and
639to optionally decide on the fate of any freshwater imbalance over the area.
640The options are explained in \autoref{sec:MISC_closea} but it should be noted here that
641a successful use of these options requires appropriate mask fields to be present in the domain configuration file.
642Among the possibilities are:
643
644\begin{clines}
645int    closea_mask          /* non-zero values in closed sea areas for optional masking                  */
646int    closea_mask_rnf      /* non-zero values in closed sea areas with runoff locations (precip only)   */
647int    closea_mask_emp      /* non-zero values in closed sea areas with runoff locations (total emp)     */
648\end{clines}
649
650% -------------------------------------------------------------------------------------------------------------
651%        Grid files
652% -------------------------------------------------------------------------------------------------------------
653\subsection{Output grid files}
655
656\nlst{namcfg}
657
658Most of the arrays relating to a particular ocean model configuration discussed in this chapter
659(grid-point position, scale factors)
660can be saved in a file if
661namelist parameter \np{ln\_write\_cfg} (namelist \nam{cfg}) is set to \forcode{.true.};
662the output filename is set through parameter \np{cn\_domcfg\_out}.
663This is only really useful if
664the fields are computed in subroutines \mdl{usrdef\_hgr} or \mdl{usrdef\_zgr} and
665checking or confirmation is required.
666
667\nlst{namdom}
668
669Alternatively, all the arrays relating to a particular ocean model configuration
670(grid-point position, scale factors, depths and masks)
671can be saved in a file called \texttt{mesh\_mask} if
672namelist parameter \np{ln\_meshmask} (namelist \nam{dom}) is set to \forcode{.true.}.
673This file contains additional fields that can be useful for post-processing applications.
674
675% ================================================================
676% Domain: Initial State (dtatsd & istate)
677% ================================================================
678\section[Initial state (\textit{istate.F90} and \textit{dtatsd.F90})]
679{Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})}
680\label{sec:DOM_DTA_tsd}
681%-----------------------------------------namtsd-------------------------------------------
682\nlst{namtsd}
683%------------------------------------------------------------------------------------------
684
685Basic initial state options are defined in \nam{tsd}.
686By default, the ocean starts from rest (the velocity field is set to zero) and
687the initialization of temperature and salinity fields is controlled through the \np{ln\_tsd\_init} namelist parameter.
688
689\begin{description}
690\item[\np{ln\_tsd\_init}\forcode{= .true.}]
691  Use T and S input files that can be given on the model grid itself or on their native input data grids.
692  In the latter case, the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid
693  (see \autoref{subsec:SBC_iof}).
694  The information relating to the input files are specified in the \np{sn\_tem} and \np{sn\_sal} structures.
695  The computation is done in the \mdl{dtatsd} module.
696\item[\np{ln\_tsd\_init}\forcode{= .false.}]
697  Initial values for T and S are set via a user supplied \rou{usr\_def\_istate} routine contained in \mdl{userdef\_istate}.
698  The default version sets horizontally uniform T and profiles as used in the GYRE configuration
699  (see \autoref{sec:CFGS_gyre}).
700\end{description}
701
702\biblio
703
704\pindex
705
706\end{document}
Note: See TracBrowser for help on using the repository browser.