source: NEMO/trunk/doc/latex/NEMO/subfiles/annex_F.tex @ 11321

Last change on this file since 11321 was 11321, checked in by acc, 2 years ago

Introduce new appendix to hold material removed from chap_DOM.tex but which is still relevant to DOMAINcfg.

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