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

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
apdx_DOMAINcfg.tex in NEMO/trunk/doc/latex/NEMO/subfiles – NEMO

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

Last change on this file since 11543 was 11543, checked in by nicolasmartin, 5 years 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: 29.4 KB
Line 
1\documentclass[../main/NEMO_manual]{subfiles}
2
3\begin{document}
4% ================================================================
5% Appendix DOMAINcfg : A brief guide to the DOMAINcfg tool
6% ================================================================
7\chapter{A brief guide to the DOMAINcfg tool}
8\label{apdx:DOMCFG}
9
10\chaptertoc
11\vfill
12\begin{figure}[b]
13\subsubsection*{Changes record}
14\begin{tabular}{m{0.08\linewidth}||m{0.32\linewidth}|m{0.6\linewidth}}
15    Release   & Author(s)     & Modifications \\
16\hline
17    {\em 4.0} & {\em Andrew Coward} & {\em Created at v4.0 from materials removed from chap\_DOM that are still relevant to the \forcode{DOMAINcfg} tool and which illustrate and explain the choices to be made by the user when setting up new domains }  \\
18\end{tabular}
19\end{figure}
20
21\newpage
22
23This appendix briefly describes some of the options available in the
24\forcode{DOMAINcfg} tool mentioned in \autoref{chap:DOM}.
25
26This tool will evolve into an independent utility with its own documentation but its
27current manifestation is mostly a wrapper for \NEMO\ \forcode{DOM} modules more aligned to
28those in the previous versions of \NEMO. These versions allowed the user to define some
29horizontal and vertical grids through additional namelist parameters. Explanations of
30these parameters are retained here for reference pending better documentation for
31\forcode{DOMAINcfg}. Please note that the namelist blocks named in this appendix refer to
32those read by \forcode{DOMAINcfg} via its own \forcode{namelist_ref} and
33\forcode{namelist_cfg} files. Although, due to their origins, these namelists share names
34with those used by \NEMO, they are not interchangeable and should be considered independent
35of those described elsewhere in this manual.
36
37% -------------------------------------------------------------------------------------------------------------
38%        Choice of horizontal grid
39% -------------------------------------------------------------------------------------------------------------
40\section{Choice of horizontal grid}
41\label{sec:DOMCFG_hor}
42
43%--------------------------------------------namdom-------------------------------------------------------
44
45\nlst{namdom_domcfg}
46%--------------------------------------------------------------------------------------------------------------
47
48The user has three options available in defining a horizontal grid, which involve the
49namelist variable \np{jphgr\_mesh} of the \nam{dom} (\texttt{DOMAINcfg} variant only)
50namelist.
51
52\begin{description}
53 \item[\np{jphgr\_mesh}=0]  The most general curvilinear orthogonal grids.
54  The coordinates and their first derivatives with respect to $i$ and $j$ are provided
55  in a input file (\ifile{coordinates}), read in \rou{hgr\_read} subroutine of the domhgr module.
56  This is now the only option available within \NEMO\ itself from v4.0 onwards.
57\item[\np{jphgr\_mesh}=1 to 5] A few simple analytical grids are provided (see below).
58  For other analytical grids, the \mdl{domhgr} module (\texttt{DOMAINcfg} variant) must be
59  modified by the user. In most cases, modifying the \mdl{usrdef\_hgr} module of \NEMO\ is
60  a better alternative since this is designed to allow simple analytical domains to be
61  configured and used without the need for external data files.
62\end{description}
63
64There are two simple cases of geographical grids on the sphere. With
65\np{jphgr\_mesh}=1, the grid (expressed in degrees) is regular in space,
66with grid sizes specified by parameters \np{ppe1\_deg} and \np{ppe2\_deg},
67respectively. Such a geographical grid can be very anisotropic at high latitudes
68because of the convergence of meridians (the zonal scale factors $e_1$
69become much smaller than the meridional scale factors $e_2$). The Mercator
70grid (\np{jphgr\_mesh}=4) avoids this anisotropy by refining the meridional scale
71factors in the same way as the zonal ones. In this case, meridional scale factors
72and latitudes are calculated analytically using the formulae appropriate for
73a Mercator projection, based on \np{ppe1\_deg} which is a reference grid spacing
74at the equator (this applies even when the geographical equator is situated outside
75the model domain).
76
77In these two cases (\np{jphgr\_mesh}=1 or 4), the grid position is defined by the
78longitude and latitude of the south-westernmost point (\np{ppglamt0}
79and \np{ppgphi0}). Note that for the Mercator grid the user need only provide
80an approximate starting latitude: the real latitude will be recalculated analytically,
81in order to ensure that the equator corresponds to line passing through $t$-
82and $u$-points.
83
84Rectangular grids ignoring the spherical geometry are defined with
85\np{jphgr\_mesh} = 2, 3, 5. The domain is either an $f$-plane (\np{jphgr\_mesh} = 2,
86Coriolis factor is constant) or a beta-plane (\np{jphgr\_mesh} = 3, the Coriolis factor
87is linear in the $j$-direction). The grid size is uniform in meter in each direction,
88and given by the parameters \np{ppe1\_m} and \np{ppe2\_m} respectively.
89The zonal grid coordinate (\textit{glam} arrays) is in kilometers, starting at zero
90with the first $t$-point. The meridional coordinate (gphi. arrays) is in kilometers,
91and the second $t$-point corresponds to coordinate $gphit=0$. The input
92variable \np{ppglam0} is ignored. \np{ppgphi0} is used to set the reference
93latitude for computation of the Coriolis parameter. In the case of the beta plane,
94\np{ppgphi0} corresponds to the center of the domain. Finally, the special case
95\np{jphgr\_mesh}=5 corresponds to a beta plane in a rotated domain for the
96GYRE configuration, representing a classical mid-latitude double gyre system.
97The rotation allows us to maximize the jet length relative to the gyre areas
98(and the number of grid points).
99
100% -------------------------------------------------------------------------------------------------------------
101%        vertical reference coordinate transformation
102% -------------------------------------------------------------------------------------------------------------
103\section{Vertical grid}
104\label{sec:DOMCFG_vert}
105\subsection{Vertical reference coordinate}
106\label{sec:DOMCFG_zref}
107
108%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
109\begin{figure}[!tb]
110  \begin{center}
111    \includegraphics[width=\textwidth]{Fig_zgr}
112    \caption{
113      \protect\label{fig:DOMCFG_zgr}
114      Default vertical mesh for ORCA2: 30 ocean levels (L30).
115      Vertical level functions for (a) T-point depth and (b) the associated scale factor for the $z$-coordinate case.
116    }
117  \end{center}
118\end{figure}
119%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
120
121The reference coordinate transformation $z_0(k)$ defines the arrays $gdept_0$ and
122$gdepw_0$ for $t$- and $w$-points, respectively. See \autoref{sec:DOMCFG_sco} for the
123S-coordinate options.  As indicated on \autoref{fig:DOM_index_vert} \jp{jpk} is the number of
124$w$-levels.  $gdepw_0(1)$ is the ocean surface.  There are at most \jp{jpk}-1 $t$-points
125inside the ocean, the additional $t$-point at $jk = jpk$ is below the sea floor and is not
126used.  The vertical location of $w$- and $t$-levels is defined from the analytic
127expression of the depth $z_0(k)$ whose analytical derivative with respect to $k$ provides
128the vertical scale factors.  The user must provide the analytical expression of both $z_0$
129and its first derivative with respect to $k$.  This is done in routine \mdl{domzgr}
130through statement functions, using parameters provided in the \nam{dom} namelist
131(\texttt{DOMAINcfg} variant).
132
133It is possible to define a simple regular vertical grid by giving zero stretching
134(\np{ppacr}\forcode{ = 0}).  In that case, the parameters \jp{jpk} (number of $w$-levels)
135and \np{pphmax} (total ocean depth in meters) fully define the grid.
136
137For climate-related studies it is often desirable to concentrate the vertical resolution
138near the ocean surface.  The following function is proposed as a standard for a
139$z$-coordinate (with either full or partial steps):
140\begin{gather}
141  \label{eq:DOMCFG_zgr_ana_1}
142    z_0  (k) = h_{sur} - h_0 \; k - \; h_1 \; \log  \big[ \cosh ((k - h_{th}) / h_{cr}) \big] \\
143    e_3^0(k) = \lt|    - h_0      -    h_1 \; \tanh \big[        (k - h_{th}) / h_{cr}  \big] \rt|
144\end{gather}
145
146where $k = 1$ to \jp{jpk} for $w$-levels and $k = 1$ to $k = 1$ for $t-$levels.  Such an
147expression allows us to define a nearly uniform vertical location of levels at the ocean
148top and bottom with a smooth hyperbolic tangent transition in between (\autoref{fig:DOMCFG_zgr}).
149
150A double hyperbolic tangent version (\np{ldbletanh}\forcode{ = .true.}) is also available
151which permits finer control and is used, typically, to obtain a well resolved upper ocean
152without compromising on resolution at depth using a moderate number of levels.
153
154\begin{gather}
155  \label{eq:DOMCFG_zgr_ana_1b}
156    \begin{split}
157    z_0  (k) = h_{sur} - h_0 \; k &- \; h_1 \; \log  \big[ \cosh ((k - h_{th}) / h_{cr}) \big] \\
158                             \;   &- \; h2_1 \; \log  \big[ \cosh ((k - h2_{th}) / h2_{cr}) \big]
159    \end{split}
160\end{gather}
161\begin{gather}
162    \begin{split}
163    e_3^0(k) = \big|    - h_0    &-   h_1 \; \tanh \big[       (k - h_{th})  / h_{cr}   \big]  \\
164                                 &-  h2_1 \; \tanh \big[       (k - h2_{th}) / h2_{cr}  \big] \big|
165    \end{split}
166\end{gather}
167
168If the ice shelf cavities are opened (\np{ln\_isfcav}\forcode{ = .true.}), the definition
169of $z_0$ is the same.  However, definition of $e_3^0$ at $t$- and $w$-points is
170respectively changed to:
171\begin{equation}
172  \label{eq:DOMCFG_zgr_ana_2}
173  \begin{split}
174    e_3^T(k) &= z_W (k + 1) - z_W (k    ) \\
175    e_3^W(k) &= z_T (k    ) - z_T (k - 1)
176  \end{split}
177\end{equation}
178
179This formulation decreases the self-generated circulation into the ice shelf cavity
180(which can, in extreme case, leads to numerical instability). This is now the recommended formulation for all configurations using v4.0 onwards. The analytical derivation of thicknesses is maintained for backwards compatibility.
181
182The most used vertical grid for ORCA2 has $10~m$ ($500~m$) resolution in the surface
183(bottom) layers and a depth which varies from 0 at the sea surface to a minimum of
184$-5000~m$.  This leads to the following conditions:
185
186\begin{equation}
187  \label{eq:DOMCFG_zgr_coef}
188  \begin{array}{ll}
189    e_3 (1   + 1/2) =  10. & z(1  ) =     0. \\
190    e_3 (jpk - 1/2) = 500. & z(jpk) = -5000.
191  \end{array}
192\end{equation}
193
194With the choice of the stretching $h_{cr} = 3$ and the number of levels \jp{jpk}~$= 31$,
195the four coefficients $h_{sur}$, $h_0$, $h_1$, and $h_{th}$ in
196\autoref{eq:DOMCFG_zgr_ana_2} have been determined such that \autoref{eq:DOMCFG_zgr_coef}
197is satisfied, through an optimisation procedure using a bisection method.
198For the first standard ORCA2 vertical grid this led to the following values:
199$h_{sur} = 4762.96$, $h_0 = 255.58, h_1 = 245.5813$, and $h_{th} = 21.43336$.
200The resulting depths and scale factors as a function of the model levels are shown in
201\autoref{fig:DOMCFG_zgr} and given in \autoref{tab:DOMCFG_orca_zgr}.
202Those values correspond to the parameters \np{ppsur}, \np{ppa0}, \np{ppa1}, \np{ppkth} in \nam{cfg} namelist.
203
204Rather than entering parameters $h_{sur}$, $h_0$, and $h_1$ directly, it is possible to
205recalculate them.  In that case the user sets \np{ppsur}~$=$~\np{ppa0}~$=$~\np{ppa1}~$=
206999999$., in \nam{cfg} namelist, and specifies instead the four following parameters:
207\begin{itemize}
208\item
209  \np{ppacr}~$= h_{cr}$: stretching factor (nondimensional).
210  The larger \np{ppacr}, the smaller the stretching.
211  Values from $3$ to $10$ are usual.
212\item
213  \np{ppkth}~$= h_{th}$: is approximately the model level at which maximum stretching occurs
214  (nondimensional, usually of order 1/2 or 2/3 of \jp{jpk})
215\item
216  \np{ppdzmin}: minimum thickness for the top layer (in meters).
217\item
218  \np{pphmax}: total depth of the ocean (meters).
219\end{itemize}
220
221As an example, for the $45$ layers used in the DRAKKAR configuration those parameters are:
222\jp{jpk}~$= 46$, \np{ppacr}~$= 9$, \np{ppkth}~$= 23.563$, \np{ppdzmin}~$= 6~m$,
223\np{pphmax}~$= 5750~m$.
224
225%% %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
226\begin{table}
227  \begin{center}
228    \begin{tabular}{c||r|r|r|r}
229      \hline
230      \textbf{LEVEL} & \textbf{gdept\_1d} & \textbf{gdepw\_1d} & \textbf{e3t\_1d } & \textbf{e3w\_1d} \\
231   \hline
232      1              & \textbf{     5.00} &               0.00 & \textbf{   10.00} &            10.00 \\
233      \hline
234      2              & \textbf{    15.00} &              10.00 & \textbf{   10.00} &            10.00 \\
235      \hline
236      3              & \textbf{    25.00} &              20.00 & \textbf{   10.00} &            10.00 \\
237      \hline
238      4              & \textbf{    35.01} &              30.00 & \textbf{   10.01} &            10.00 \\
239      \hline
240      5              & \textbf{    45.01} &              40.01 & \textbf{   10.01} &            10.01 \\
241      \hline
242      6              & \textbf{    55.03} &              50.02 & \textbf{   10.02} &            10.02 \\
243      \hline
244      7              & \textbf{    65.06} &              60.04 & \textbf{   10.04} &            10.03 \\
245      \hline
246      8              & \textbf{    75.13} &              70.09 & \textbf{   10.09} &            10.06 \\
247      \hline
248      9              & \textbf{    85.25} &              80.18 & \textbf{   10.17} &            10.12 \\
249      \hline
250      10             & \textbf{    95.49} &              90.35 & \textbf{   10.33} &            10.24 \\
251      \hline
252      11             & \textbf{   105.97} &             100.69 & \textbf{   10.65} &            10.47 \\
253      \hline
254      12             & \textbf{   116.90} &             111.36 & \textbf{   11.27} &            10.91 \\
255      \hline
256      13             & \textbf{   128.70} &             122.65 & \textbf{   12.47} &            11.77 \\
257      \hline
258      14             & \textbf{   142.20} &             135.16 & \textbf{   14.78} &            13.43 \\
259      \hline
260      15             & \textbf{   158.96} &             150.03 & \textbf{   19.23} &            16.65 \\
261      \hline
262      16             & \textbf{   181.96} &             169.42 & \textbf{   27.66} &            22.78 \\
263      \hline
264      17             & \textbf{   216.65} &             197.37 & \textbf{   43.26} &            34.30 \\
265      \hline
266      18             & \textbf{   272.48} &             241.13 & \textbf{   70.88} &            55.21 \\
267      \hline
268      19             & \textbf{   364.30} &             312.74 & \textbf{  116.11} &            90.99 \\
269      \hline
270      20             & \textbf{   511.53} &             429.72 & \textbf{  181.55} &           146.43 \\
271      \hline
272      21             & \textbf{   732.20} &             611.89 & \textbf{  261.03} &           220.35 \\
273      \hline
274      22             & \textbf{  1033.22} &             872.87 & \textbf{  339.39} &           301.42 \\
275      \hline
276      23             & \textbf{  1405.70} &            1211.59 & \textbf{  402.26} &           373.31 \\
277      \hline
278      24             & \textbf{  1830.89} &            1612.98 & \textbf{  444.87} &           426.00 \\
279      \hline
280      25             & \textbf{  2289.77} &            2057.13 & \textbf{  470.55} &           459.47 \\
281      \hline
282      26             & \textbf{  2768.24} &            2527.22 & \textbf{  484.95} &           478.83 \\
283      \hline
284      27             & \textbf{  3257.48} &            3011.90 & \textbf{  492.70} &           489.44 \\
285      \hline
286      28             & \textbf{  3752.44} &            3504.46 & \textbf{  496.78} &           495.07 \\
287      \hline
288      29             & \textbf{  4250.40} &            4001.16 & \textbf{  498.90} &           498.02 \\
289      \hline
290      30             & \textbf{  4749.91} &            4500.02 & \textbf{  500.00} &           499.54 \\
291      \hline
292      31             & \textbf{  5250.23} &            5000.00 & \textbf{  500.56} &           500.33 \\
293      \hline
294    \end{tabular}
295  \end{center}
296  \caption{
297    \protect\label{tab:DOMCFG_orca_zgr}
298    Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration as computed from
299    \autoref{eq:DOMCFG_zgr_ana_2} using the coefficients given in \autoref{eq:DOMCFG_zgr_coef}
300  }
301\end{table}
302%%%YY
303%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
304%% % -------------------------------------------------------------------------------------------------------------
305%% %        Meter Bathymetry
306%% % -------------------------------------------------------------------------------------------------------------
307\subsection{Model bathymetry}
308\label{subsec:DOMCFG_bathy}
309
310Three options are possible for defining the bathymetry, according to the namelist variable
311\np{nn\_bathy} (found in \nam{dom} namelist (\texttt{DOMAINCFG} variant) ):
312\begin{description}
313\item[\np{nn\_bathy}\forcode{ = 0}]:
314  a flat-bottom domain is defined.
315  The total depth $z_w (jpk)$ is given by the coordinate transformation.
316  The domain can either be a closed basin or a periodic channel depending on the parameter \np{jperio}.
317\item[\np{nn\_bathy}\forcode{ = -1}]:
318  a domain with a bump of topography one third of the domain width at the central latitude.
319  This is meant for the "EEL-R5" configuration, a periodic or open boundary channel with a seamount.
320\item[\np{nn\_bathy}\forcode{ = 1}]:
321  read a bathymetry and ice shelf draft (if needed).
322  The \ifile{bathy\_meter} file (Netcdf format) provides the ocean depth (positive, in meters) at
323  each grid point of the model grid.
324  The bathymetry is usually built by interpolating a standard bathymetry product (\eg\ ETOPO2) onto
325  the horizontal ocean mesh.
326  Defining the bathymetry also defines the coastline: where the bathymetry is zero,
327  no wet levels are defined (all levels are masked).
328
329  The \ifile{isfdraft\_meter} file (Netcdf format) provides the ice shelf draft (positive, in meters) at
330  each grid point of the model grid.
331  This file is only needed if \np{ln\_isfcav}\forcode{ = .true.}.
332  Defining the ice shelf draft will also define the ice shelf edge and the grounding line position.
333\end{description}
334
335\subsection{Choice of vertical grid}
336\label{sec:DOMCFG_vgrd}
337
338After reading the bathymetry, the algorithm for vertical grid definition differs between the different options:
339\begin{description}
340\item[\forcode{ln_zco = .true.}]
341  set a reference coordinate transformation $z_0(k)$, and set $z(i,j,k,t) = z_0(k)$ where $z_0(k)$ is the closest match to the depth at $(i,j)$.
342\item[\forcode{ln_zps = .true.}]
343  set a reference coordinate transformation $z_0(k)$, and calculate the thickness of the deepest level at
344  each $(i,j)$ point using the bathymetry, to obtain the final three-dimensional depth and scale factor arrays.
345\item[\forcode{ln_sco = .true.}]
346  smooth the bathymetry to fulfill the hydrostatic consistency criteria and
347  set the three-dimensional transformation.
348\item[\forcode{s-z and s-zps}]
349  smooth the bathymetry to fulfill the hydrostatic consistency criteria and
350  set the three-dimensional transformation $z(i,j,k)$,
351  and possibly introduce masking of extra land points to better fit the original bathymetry file.
352\end{description}
353%%%
354
355% -------------------------------------------------------------------------------------------------------------
356%        z-coordinate with constant thickness
357% -------------------------------------------------------------------------------------------------------------
358\subsubsection[$Z$-coordinate with uniform thickness levels (\forcode{ln_zco = .true.})]
359{$Z$-coordinate with uniform thickness levels (\protect\np{ln\_zco}\forcode{ = .true.})}
360\label{subsec:DOMCFG_zco}
361
362With this option the model topography can be fully described by the reference vertical
363coordinate and a 2D integer field giving the number of wet levels at each location
364(\forcode{bathy_level}). The resulting match to the real topography is likely to be poor
365though (especially with thick, deep levels) and slopes poorly represented. This option is
366rarely used in modern simulations but it can be useful for testing purposes.
367
368% -------------------------------------------------------------------------------------------------------------
369%        z-coordinate with partial step
370% -------------------------------------------------------------------------------------------------------------
371\subsubsection[$Z$-coordinate with partial step (\forcode{ln_zps = .true.})]
372{$Z$-coordinate with partial step (\protect\np{ln\_zps}\forcode{ = .true.})}
373\label{subsec:DOMCFG_zps}
374
375In $z$-coordinate partial step, the depths of the model levels are defined by the
376reference analytical function $z_0(k)$ as described in \autoref{sec:DOMCFG_zref},
377\textit{except} in the bottom layer.  The thickness of the bottom layer is allowed to vary
378as a function of geographical location $(\lambda,\varphi)$ to allow a better
379representation of the bathymetry, especially in the case of small slopes (where the
380bathymetry varies by less than one level thickness from one grid point to the next).  The
381reference layer thicknesses $e_{3t}^0$ have been defined in the absence of bathymetry.
382With partial steps, layers from 1 to \jp{jpk}-2 can have a thickness smaller than
383$e_{3t}(jk)$.
384
385The model deepest layer (\jp{jpk}-1) is allowed to have either a smaller or larger
386thickness than $e_{3t}(jpk)$: the maximum thickness allowed is $2*e_{3t}(jpk - 1)$.
387
388This has to be kept in mind when specifying values in \nam{dom} namelist
389(\texttt{DOMAINCFG} variant), such as the maximum depth \np{pphmax} in partial steps.
390
391For example, with \np{pphmax}~$= 5750~m$ for the DRAKKAR 45 layer grid, the maximum ocean
392depth allowed is actually $6000~m$ (the default thickness $e_{3t}(jpk - 1)$ being
393$250~m$).  Two variables in the namdom namelist are used to define the partial step
394vertical grid.  The mimimum water thickness (in meters) allowed for a cell partially
395filled with bathymetry at level jk is the minimum of \np{rn\_e3zps\_min} (thickness in
396meters, usually $20~m$) or $e_{3t}(jk)*$\np{rn\_e3zps\_rat} (a fraction, usually 10\%, of
397the default thickness $e_{3t}(jk)$).
398
399% -------------------------------------------------------------------------------------------------------------
400%        s-coordinate
401% -------------------------------------------------------------------------------------------------------------
402\subsubsection[$S$-coordinate (\forcode{ln_sco = .true.})]
403{$S$-coordinate (\protect\np{ln\_sco}\forcode{ = .true.})}
404\label{sec:DOMCFG_sco}
405%------------------------------------------nam_zgr_sco---------------------------------------------------
406%
407\nlst{namzgr_sco_domcfg}
408%--------------------------------------------------------------------------------------------------------------
409Options are defined in \nam{zgr\_sco} (\texttt{DOMAINcfg} only).
410In $s$-coordinate (\np{ln\_sco}\forcode{ = .true.}), the depth and thickness of the model levels are defined from
411the product of a depth field and either a stretching function or its derivative, respectively:
412
413\begin{align*}
414  % \label{eq:DOMCFG_sco_ana}
415  z(k)   &= h(i,j) \; z_0 (k) \\
416  e_3(k) &= h(i,j) \; z_0'(k)
417\end{align*}
418
419where $h$ is the depth of the last $w$-level ($z_0(k)$) defined at the $t$-point location in the horizontal and
420$z_0(k)$ is a function which varies from $0$ at the sea surface to $1$ at the ocean bottom.
421The depth field $h$ is not necessary the ocean depth,
422since a mixed step-like and bottom-following representation of the topography can be used
423(\autoref{fig:DOM_z_zps_s_sps}) or an envelop bathymetry can be defined (\autoref{fig:DOM_z_zps_s_sps}).
424The namelist parameter \np{rn\_rmax} determines the slope at which
425the terrain-following coordinate intersects the sea bed and becomes a pseudo z-coordinate.
426The coordinate can also be hybridised by specifying \np{rn\_sbot\_min} and \np{rn\_sbot\_max} as
427the minimum and maximum depths at which the terrain-following vertical coordinate is calculated.
428
429Options for stretching the coordinate are provided as examples,
430but care must be taken to ensure that the vertical stretch used is appropriate for the application.
431
432The original default \NEMO\ s-coordinate stretching is available if neither of the other options are specified as true
433(\np{ln\_s\_SH94}\forcode{ = .false.} and \np{ln\_s\_SF12}\forcode{ = .false.}).
434This uses a depth independent $\tanh$ function for the stretching \citep{madec.delecluse.ea_JPO96}:
435
436\[
437  z = s_{min} + C (s) (H - s_{min})
438  % \label{eq:DOMCFG_SH94_1}
439\]
440
441where $s_{min}$ is the depth at which the $s$-coordinate stretching starts and
442allows a $z$-coordinate to placed on top of the stretched coordinate,
443and $z$ is the depth (negative down from the asea surface).
444\begin{gather*}
445  s = - \frac{k}{n - 1} \quad \text{and} \quad 0 \leq k \leq n - 1
446  % \label{eq:DOMCFG_s}
447 \\
448 \label{eq:DOMCFG_sco_function}
449  C(s) = \frac{[\tanh(\theta \, (s + b)) - \tanh(\theta \, b)]}{2 \; \sinh(\theta)}
450\end{gather*}
451
452A stretching function,
453modified from the commonly used \citet{song.haidvogel_JCP94} stretching (\np{ln\_s\_SH94}\forcode{ = .true.}),
454is also available and is more commonly used for shelf seas modelling:
455
456\[
457  C(s) =   (1 - b) \frac{\sinh(\theta s)}{\sinh(\theta)}
458         + b       \frac{\tanh \lt[ \theta \lt(s + \frac{1}{2} \rt) \rt] -   \tanh \lt( \frac{\theta}{2} \rt)}
459                        {                                                  2 \tanh \lt( \frac{\theta}{2} \rt)}
460 \label{eq:DOMCFG_SH94_2}
461\]
462
463%% %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
464\begin{figure}[!ht]
465  \begin{center}
466    \includegraphics[width=\textwidth]{Fig_sco_function}
467    \caption{
468      \protect\label{fig:DOMCFG_sco_function}
469      Examples of the stretching function applied to a seamount;
470      from left to right: surface, surface and bottom, and bottom intensified resolutions
471    }
472  \end{center}
473\end{figure}
474%% %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
475
476where $H_c$ is the critical depth (\np{rn\_hc}) at which the coordinate transitions from pure $\sigma$ to
477the stretched coordinate, and $\theta$ (\np{rn\_theta}) and $b$ (\np{rn\_bb}) are the surface and
478bottom control parameters such that $0 \leqslant \theta \leqslant 20$, and $0 \leqslant b \leqslant 1$.
479$b$ has been designed to allow surface and/or bottom increase of the vertical resolution
480(\autoref{fig:DOMCFG_sco_function}).
481
482Another example has been provided at version 3.5 (\np{ln\_s\_SF12}) that allows a fixed surface resolution in
483an analytical terrain-following stretching \citet{siddorn.furner_OM13}.
484In this case the a stretching function $\gamma$ is defined such that:
485
486\begin{equation}
487  z = - \gamma h \quad \text{with} \quad 0 \leq \gamma \leq 1
488  % \label{eq:DOMCFG_z}
489\end{equation}
490
491The function is defined with respect to $\sigma$, the unstretched terrain-following coordinate:
492
493\begin{gather*}
494  % \label{eq:DOMCFG_gamma_deriv}
495  \gamma =   A \lt( \sigma   - \frac{1}{2} (\sigma^2     + f (\sigma)) \rt)
496           + B \lt( \sigma^3 - f           (\sigma) \rt) + f (\sigma)       \\
497  \intertext{Where:}
498 \label{eq:DOMCFG_gamma}
499  f(\sigma) = (\alpha + 2) \sigma^{\alpha + 1} - (\alpha + 1) \sigma^{\alpha + 2}
500  \quad \text{and} \quad \sigma = \frac{k}{n - 1}
501\end{gather*}
502
503This gives an analytical stretching of $\sigma$ that is solvable in $A$ and $B$ as a function of
504the user prescribed stretching parameter $\alpha$ (\np{rn\_alpha}) that stretches towards
505the surface ($\alpha > 1.0$) or the bottom ($\alpha < 1.0$) and
506user prescribed surface (\np{rn\_zs}) and bottom depths.
507The bottom cell depth in this example is given as a function of water depth:
508
509\[
510  % \label{eq:DOMCFG_zb}
511  Z_b = h a + b
512\]
513
514where the namelist parameters \np{rn\_zb\_a} and \np{rn\_zb\_b} are $a$ and $b$ respectively.
515
516%% %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
517\begin{figure}[!ht]
518  \includegraphics[width=\textwidth]{Fig_DOM_compare_coordinates_surface}
519  \caption{
520    A comparison of the \citet{song.haidvogel_JCP94} $S$-coordinate (solid lines),
521    a 50 level $Z$-coordinate (contoured surfaces) and
522    the \citet{siddorn.furner_OM13} $S$-coordinate (dashed lines) in the surface $100~m$ for
523    a idealised bathymetry that goes from $50~m$ to $5500~m$ depth.
524    For clarity every third coordinate surface is shown.
525  }
526  \label{fig:DOMCFG_fig_compare_coordinates_surface}
527\end{figure}
528 % >>>>>>>>>>>>>>>>>>>>>>>>>>>>
529
530This gives a smooth analytical stretching in computational space that is constrained to
531given specified surface and bottom grid cell thicknesses in real space.
532This is not to be confused with the hybrid schemes that
533superimpose geopotential coordinates on terrain following coordinates thus
534creating a non-analytical vertical coordinate that
535therefore may suffer from large gradients in the vertical resolutions.
536This stretching is less straightforward to implement than the \citet{song.haidvogel_JCP94} stretching,
537but has the advantage of resolving diurnal processes in deep water and has generally flatter slopes.
538
539As with the \citet{song.haidvogel_JCP94} stretching the stretch is only applied at depths greater than
540the critical depth $h_c$.
541In this example two options are available in depths shallower than $h_c$,
542with pure sigma being applied if the \np{ln\_sigcrit} is true and pure z-coordinates if it is false
543(the z-coordinate being equal to the depths of the stretched coordinate at $h_c$).
544
545Minimising the horizontal slope of the vertical coordinate is important in terrain-following systems as
546large slopes lead to hydrostatic consistency.
547A hydrostatic consistency parameter diagnostic following \citet{haney_JPO91} has been implemented,
548and is output as part of the model mesh file at the start of the run.
549
550% -------------------------------------------------------------------------------------------------------------
551%        z*- or s*-coordinate
552% -------------------------------------------------------------------------------------------------------------
553\subsubsection[\zstar- or \sstar-coordinate (\forcode{ln_linssh = .false.})]
554{\zstar- or \sstar-coordinate (\protect\np{ln\_linssh}\forcode{ = .false.})}
555\label{subsec:DOMCFG_zgr_star}
556
557This option is described in the Report by Levier \textit{et al.} (2007), available on the \NEMO\ web site.
558
559\biblio
560
561\pindex
562
563\end{document}
Note: See TracBrowser for help on using the repository browser.