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

Last change on this file since 11577 was 11577, checked in by nicolasmartin, 13 months ago

New LaTeX commands \nam and \np to mention namelist content
(Partial commit to serve as a backup before other large edits)
In order to benefit of the syntax highlighting and to have a simpler syntax for
citing namelist block (\nam) and parameter (\np) with an optional variable assignment (\forcode{…}),
at this time the only viable solution I found is to require a double marker for
what it looks like the same item:

  1. Marker with the real name: 'tra_adv' block or 'ln_flx' parameter
  2. Marker with underscore character escaping: 'tra\_adv' block or 'ln\_flx' parameter

Despite many searches and attempts, I did not find a workaround to edit on-the-fly one or
the other marker.
In fact, the problem is on one side that the LaTeX index interprets '_' as a switch for lowering like
in math mode while on the other hand the backslash is considered for Pygments as a typo in Fortran
(red box).

For instance, \nam and \np have as of now the aforementioned 2 mandatory arguments in
the previous order (between braces) + an optional argument for \np when the parameter is defined
(between brackets at the first position):

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