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

Last change on this file since 14257 was 14257, checked in by nicolasmartin, 4 months ago

Overall review of LaTeX sources (not tested completely as of now):

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