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

Last change on this file since 14178 was 14178, checked in by nicolasmartin, 5 months ago

Complement of the previous commit

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