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

Last change on this file since 14303 was 14303, checked in by mathiot, 13 months ago

ticket #2444: update doc (isf, clo, icb)

File size: 44.5 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   next}& {\em Pierre Mathiot} & {\em add ice shelf and closed sea option description } \\
19    {\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 }  \\
20    {\em   3.6} & {\em ...} & {\em ...} \\
21    {\em   3.4} & {\em ...} & {\em ...} \\
22    {\em <=3.4} & {\em ...} & {\em ...}
23  \end{tabularx}
24}
25
26\clearpage
27
28This appendix briefly describes some of the options available in the
29\forcode{DOMAINcfg} tool mentioned in \autoref{chap:DOM}.
30
31This tool will evolve into an independent utility with its own documentation but its
32current manifestation is mostly a wrapper for \NEMO\ \forcode{DOM} modules more aligned to
33those in the previous versions of \NEMO. These versions allowed the user to define some
34horizontal and vertical grids through additional namelist parameters. Explanations of
35these parameters are retained here for reference pending better documentation for
36\forcode{DOMAINcfg}. Please note that the namelist blocks named in this appendix refer to
37those read by \forcode{DOMAINcfg} via its own \forcode{namelist_ref} and
38\forcode{namelist_cfg} files. Although, due to their origins, these namelists share names
39with those used by \NEMO, they are not interchangeable and should be considered independent
40of those described elsewhere in this manual.
41
42%% =================================================================================================
43\section{Choice of horizontal grid}
44\label{sec:DOMCFG_hor}
45
46\begin{listing}
47%  \nlst{namdom_domcfg}
48  \begin{forlines}
49!-----------------------------------------------------------------------
50&namdom        !   space and time domain (bathymetry, mesh, timestep)
51!-----------------------------------------------------------------------
52   nn_bathy    =    1      !  compute analyticaly (=0) or read (=1) the bathymetry file
53                           !  or compute (2) from external bathymetry
54   nn_interp   =    1                          ! type of interpolation (nn_bathy =2)                       
55   cn_topo     =  'bathymetry_ORCA12_V3.3.nc'  ! external topo file (nn_bathy =2)
56   cn_bath     =  'Bathymetry'                 ! topo name in file  (nn_bathy =2)
57   cn_lon      =  'nav_lon'                    ! lon  name in file  (nn_bathy =2)
58   cn_lat      =  'nav_lat'                    ! lat  name in file  (nn_bathy =2)
59   rn_scale    = 1
60   rn_bathy    =    0.     !  value of the bathymetry. if (=0) bottom flat at jpkm1
61   jphgr_msh   =       0               !  type of horizontal mesh
62   ppglam0     =  999999.0             !  longitude of first raw and column T-point (jphgr_msh = 1)
63   ppgphi0     =  999999.0             ! latitude  of first raw and column T-point (jphgr_msh = 1)
64   ppe1_deg    =  999999.0             !  zonal      grid-spacing (degrees)
65   ppe2_deg    =  999999.0             !  meridional grid-spacing (degrees)
66   ppe1_m      =  999999.0             !  zonal      grid-spacing (degrees)
67   ppe2_m      =  999999.0             !  meridional grid-spacing (degrees)
68   ppsur       =   -4762.96143546300   !  ORCA r4, r2 and r05 coefficients
69   ppa0        =     255.58049070440   ! (default coefficients)
70   ppa1        =     245.58132232490   !
71   ppkth       =      21.43336197938   !
72   ppacr       =       3.0             !
73   ppdzmin     =  999999.              !  Minimum vertical spacing
74   pphmax      =  999999.              !  Maximum depth
75   ldbletanh   =  .FALSE.              !  Use/do not use double tanf function for vertical coordinates
76   ppa2        =  999999.              !  Double tanh function parameters
77   ppkth2      =  999999.              !
78   ppacr2      =  999999.              !
79/
80  \end{forlines}
81  \caption{\forcode{&namdom_domcfg}}
82  \label{lst:namdom_domcfg}
83\end{listing}
84
85The user has three options available in defining a horizontal grid, which involve the
86namelist variable \np{jphgr_mesh}{jphgr\_mesh} of the \nam{dom}{dom} (\texttt{DOMAINcfg} variant only)
87namelist.
88
89\begin{description}
90 \item [{\np{jphgr_mesh}{jphgr\_mesh}=0}]  The most general curvilinear orthogonal grids.
91  The coordinates and their first derivatives with respect to $i$ and $j$ are provided
92  in a input file (\textit{coordinates.nc}), read in \rou{hgr\_read} subroutine of the domhgr module.
93  This is now the only option available within \NEMO\ itself from v4.0 onwards.
94\item [{\np{jphgr_mesh}{jphgr\_mesh}=1 to 5}] A few simple analytical grids are provided (see below).
95  For other analytical grids, the \mdl{domhgr} module (\texttt{DOMAINcfg} variant) must be
96  modified by the user. In most cases, modifying the \mdl{usrdef\_hgr} module of \NEMO\ is
97  a better alternative since this is designed to allow simple analytical domains to be
98  configured and used without the need for external data files.
99\end{description}
100
101There are two simple cases of geographical grids on the sphere. With
102\np{jphgr_mesh}{jphgr\_mesh}=1, the grid (expressed in degrees) is regular in space,
103with grid sizes specified by parameters \np{ppe1_deg}{ppe1\_deg} and \np{ppe2_deg}{ppe2\_deg},
104respectively. Such a geographical grid can be very anisotropic at high latitudes
105because of the convergence of meridians (the zonal scale factors $e_1$
106become much smaller than the meridional scale factors $e_2$). The Mercator
107grid (\np{jphgr_mesh}{jphgr\_mesh}=4) avoids this anisotropy by refining the meridional scale
108factors in the same way as the zonal ones. In this case, meridional scale factors
109and latitudes are calculated analytically using the formulae appropriate for
110a Mercator projection, based on \np{ppe1_deg}{ppe1\_deg} which is a reference grid spacing
111at the equator (this applies even when the geographical equator is situated outside
112the model domain).
113
114In these two cases (\np{jphgr_mesh}{jphgr\_mesh}=1 or 4), the grid position is defined by the
115longitude and latitude of the south-westernmost point (\np{ppglamt0}
116and \np{ppgphi0}{ppgphi0}). Note that for the Mercator grid the user need only provide
117an approximate starting latitude: the real latitude will be recalculated analytically,
118in order to ensure that the equator corresponds to line passing through $t$-
119and $u$-points.
120
121Rectangular grids ignoring the spherical geometry are defined with
122\np{jphgr_mesh}{jphgr\_mesh} = 2, 3, 5. The domain is either an $f$-plane (\np{jphgr_mesh}{jphgr\_mesh} = 2,
123Coriolis factor is constant) or a beta-plane (\np{jphgr_mesh}{jphgr\_mesh} = 3, the Coriolis factor
124is linear in the $j$-direction). The grid size is uniform in meter in each direction,
125and given by the parameters \np{ppe1_m}{ppe1\_m} and \np{ppe2_m}{ppe2\_m} respectively.
126The zonal grid coordinate (\textit{glam} arrays) is in kilometers, starting at zero
127with the first $t$-point. The meridional coordinate (gphi. arrays) is in kilometers,
128and the second $t$-point corresponds to coordinate $gphit=0$. The input
129variable \np{ppglam0}{ppglam0} is ignored. \np{ppgphi0}{ppgphi0} is used to set the reference
130latitude for computation of the Coriolis parameter. In the case of the beta plane,
131\np{ppgphi0}{ppgphi0} corresponds to the center of the domain. Finally, the special case
132\np{jphgr_mesh}{jphgr\_mesh}=5 corresponds to a beta plane in a rotated domain for the
133GYRE configuration, representing a classical mid-latitude double gyre system.
134The rotation allows us to maximize the jet length relative to the gyre areas
135(and the number of grid points).
136
137%% =================================================================================================
138\section{Vertical grid}
139\label{sec:DOMCFG_vert}
140
141%% =================================================================================================
142\subsection{Vertical reference coordinate}
143\label{sec:DOMCFG_zref}
144
145\begin{figure}[!tb]
146  \centering
147  \includegraphics[width=0.66\textwidth]{DOMCFG_zgr}
148  \caption[DOMAINcfg: default vertical mesh for ORCA2]{
149    Default vertical mesh for ORCA2: 30 ocean levels (L30).
150    Vertical level functions for (a) T-point depth and (b) the associated scale factor for
151    the $z$-coordinate case.}
152  \label{fig:DOMCFG_zgr}
153\end{figure}
154
155The reference coordinate transformation $z_0(k)$ defines the arrays $gdept_0$ and
156$gdepw_0$ for $t$- and $w$-points, respectively. See \autoref{sec:DOMCFG_sco} for the
157S-coordinate options.  As indicated on \autoref{fig:DOM_index_vert} \texttt{jpk} is the number of
158$w$-levels.  $gdepw_0(1)$ is the ocean surface.  There are at most \texttt{jpk}-1 $t$-points
159inside the ocean, the additional $t$-point at $jk = jpk$ is below the sea floor and is not
160used.  The vertical location of $w$- and $t$-levels is defined from the analytic
161expression of the depth $z_0(k)$ whose analytical derivative with respect to $k$ provides
162the vertical scale factors.  The user must provide the analytical expression of both $z_0$
163and its first derivative with respect to $k$.  This is done in routine \mdl{domzgr}
164through statement functions, using parameters provided in the \nam{dom}{dom} namelist
165(\texttt{DOMAINcfg} variant).
166
167It is possible to define a simple regular vertical grid by giving zero stretching
168(\np[=0]{ppacr}{ppacr}).  In that case, the parameters \texttt{jpk} (number of $w$-levels)
169and \np{pphmax}{pphmax} (total ocean depth in meters) fully define the grid.
170
171For climate-related studies it is often desirable to concentrate the vertical resolution
172near the ocean surface.  The following function is proposed as a standard for a
173$z$-coordinate (with either full or partial steps):
174\begin{gather}
175  \label{eq:DOMCFG_zgr_ana_1}
176    z_0  (k) = h_{sur} - h_0 \; k - \; h_1 \; \log  \big[ \cosh ((k - h_{th}) / h_{cr}) \big] \\
177    e_3^0(k) = \lt|    - h_0      -    h_1 \; \tanh \big[        (k - h_{th}) / h_{cr}  \big] \rt|
178\end{gather}
179
180where $k = 1$ to \texttt{jpk} for $w$-levels and $k = 1$ to $k = 1$ for $t-$levels.  Such an
181expression allows us to define a nearly uniform vertical location of levels at the ocean
182top and bottom with a smooth hyperbolic tangent transition in between (\autoref{fig:DOMCFG_zgr}).
183
184A double hyperbolic tangent version (\np[=.true.]{ldbletanh}{ldbletanh}) is also available
185which permits finer control and is used, typically, to obtain a well resolved upper ocean
186without compromising on resolution at depth using a moderate number of levels.
187
188\begin{gather}
189  \label{eq:DOMCFG_zgr_ana_1b}
190    \begin{split}
191    z_0  (k) = h_{sur} - h_0 \; k &- \; h_1 \; \log  \big[ \cosh ((k - h_{th}) / h_{cr}) \big] \\
192                             \;   &- \; h2_1 \; \log  \big[ \cosh ((k - h2_{th}) / h2_{cr}) \big]
193    \end{split}
194\end{gather}
195\begin{gather}
196    \begin{split}
197    e_3^0(k) = \big|    - h_0    &-   h_1 \; \tanh \big[       (k - h_{th})  / h_{cr}   \big]  \\
198                                 &-  h2_1 \; \tanh \big[       (k - h2_{th}) / h2_{cr}  \big] \big|
199    \end{split}
200\end{gather}
201
202If the ice shelf cavities are opened (\np[=.true.]{ln_isfcav}{ln\_isfcav}), the definition
203of $z_0$ is the same.  However, definition of $e_3^0$ at $t$- and $w$-points is
204respectively changed to:
205\begin{equation}
206  \label{eq:DOMCFG_zgr_ana_2}
207  \begin{split}
208    e_3^T(k) &= z_W (k + 1) - z_W (k    ) \\
209    e_3^W(k) &= z_T (k    ) - z_T (k - 1)
210  \end{split}
211\end{equation}
212
213This formulation decreases the self-generated circulation into the ice shelf cavity
214(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.
215
216The most used vertical grid for ORCA2 has $10~m$ ($500~m$) resolution in the surface
217(bottom) layers and a depth which varies from 0 at the sea surface to a minimum of
218$-5000~m$.  This leads to the following conditions:
219
220\begin{equation}
221  \label{eq:DOMCFG_zgr_coef}
222  \begin{array}{ll}
223    e_3 (1   + 1/2) =  10. & z(1  ) =     0. \\
224    e_3 (jpk - 1/2) = 500. & z(jpk) = -5000.
225  \end{array}
226\end{equation}
227
228With the choice of the stretching $h_{cr} = 3$ and the number of levels \texttt{jpk}~$= 31$,
229the four coefficients $h_{sur}$, $h_0$, $h_1$, and $h_{th}$ in
230\autoref{eq:DOMCFG_zgr_ana_2} have been determined such that \autoref{eq:DOMCFG_zgr_coef}
231is satisfied, through an optimisation procedure using a bisection method.
232For the first standard ORCA2 vertical grid this led to the following values:
233$h_{sur} = 4762.96$, $h_0 = 255.58, h_1 = 245.5813$, and $h_{th} = 21.43336$.
234The resulting depths and scale factors as a function of the model levels are shown in
235\autoref{fig:DOMCFG_zgr} and given in \autoref{tab:DOMCFG_orca_zgr}.
236Those values correspond to the parameters \np{ppsur}{ppsur}, \np{ppa0}{ppa0}, \np{ppa1}{ppa1}, \np{ppkth}{ppkth} in \nam{cfg}{cfg} namelist.
237
238Rather than entering parameters $h_{sur}$, $h_0$, and $h_1$ directly, it is possible to
239recalculate them.  In that case the user sets \np{ppsur}{ppsur}~$=$~\np{ppa0}{ppa0}~$=$~\np{ppa1}{ppa1}~$=
240999999$., in \nam{cfg}{cfg} namelist, and specifies instead the four following parameters:
241\begin{itemize}
242\item \np{ppacr}{ppacr}~$= h_{cr}$: stretching factor (nondimensional).
243  The larger \np{ppacr}{ppacr}, the smaller the stretching.
244  Values from $3$ to $10$ are usual.
245\item \np{ppkth}{ppkth}~$= h_{th}$: is approximately the model level at which maximum stretching occurs
246  (nondimensional, usually of order 1/2 or 2/3 of \texttt{jpk})
247\item \np{ppdzmin}{ppdzmin}: minimum thickness for the top layer (in meters).
248\item \np{pphmax}{pphmax}: total depth of the ocean (meters).
249\end{itemize}
250
251As an example, for the $45$ layers used in the DRAKKAR configuration those parameters are:
252\texttt{jpk}~$= 46$, \np{ppacr}{ppacr}~$= 9$, \np{ppkth}{ppkth}~$= 23.563$, \np{ppdzmin}{ppdzmin}~$= 6~m$,
253\np{pphmax}{pphmax}~$= 5750~m$.
254
255\begin{table}
256  \centering
257  \begin{tabular}{c||r|r|r|r}
258    \hline
259    \textbf{LEVEL} & \textbf{gdept\_1d} & \textbf{gdepw\_1d} & \textbf{e3t\_1d } & \textbf{e3w\_1d} \\
260    \hline
261    1              & \textbf{     5.00} &               0.00 & \textbf{   10.00} &            10.00 \\
262    \hline
263    2              & \textbf{    15.00} &              10.00 & \textbf{   10.00} &            10.00 \\
264    \hline
265    3              & \textbf{    25.00} &              20.00 & \textbf{   10.00} &            10.00 \\
266    \hline
267    4              & \textbf{    35.01} &              30.00 & \textbf{   10.01} &            10.00 \\
268    \hline
269    5              & \textbf{    45.01} &              40.01 & \textbf{   10.01} &            10.01 \\
270    \hline
271    6              & \textbf{    55.03} &              50.02 & \textbf{   10.02} &            10.02 \\
272    \hline
273    7              & \textbf{    65.06} &              60.04 & \textbf{   10.04} &            10.03 \\
274    \hline
275    8              & \textbf{    75.13} &              70.09 & \textbf{   10.09} &            10.06 \\
276    \hline
277    9              & \textbf{    85.25} &              80.18 & \textbf{   10.17} &            10.12 \\
278    \hline
279    10             & \textbf{    95.49} &              90.35 & \textbf{   10.33} &            10.24 \\
280    \hline
281    11             & \textbf{   105.97} &             100.69 & \textbf{   10.65} &            10.47 \\
282    \hline
283    12             & \textbf{   116.90} &             111.36 & \textbf{   11.27} &            10.91 \\
284    \hline
285    13             & \textbf{   128.70} &             122.65 & \textbf{   12.47} &            11.77 \\
286    \hline
287    14             & \textbf{   142.20} &             135.16 & \textbf{   14.78} &            13.43 \\
288    \hline
289    15             & \textbf{   158.96} &             150.03 & \textbf{   19.23} &            16.65 \\
290    \hline
291    16             & \textbf{   181.96} &             169.42 & \textbf{   27.66} &            22.78 \\
292    \hline
293    17             & \textbf{   216.65} &             197.37 & \textbf{   43.26} &            34.30 \\
294    \hline
295    18             & \textbf{   272.48} &             241.13 & \textbf{   70.88} &            55.21 \\
296    \hline
297    19             & \textbf{   364.30} &             312.74 & \textbf{  116.11} &            90.99 \\
298    \hline
299    20             & \textbf{   511.53} &             429.72 & \textbf{  181.55} &           146.43 \\
300    \hline
301    21             & \textbf{   732.20} &             611.89 & \textbf{  261.03} &           220.35 \\
302    \hline
303    22             & \textbf{  1033.22} &             872.87 & \textbf{  339.39} &           301.42 \\
304    \hline
305    23             & \textbf{  1405.70} &            1211.59 & \textbf{  402.26} &           373.31 \\
306    \hline
307    24             & \textbf{  1830.89} &            1612.98 & \textbf{  444.87} &           426.00 \\
308    \hline
309    25             & \textbf{  2289.77} &            2057.13 & \textbf{  470.55} &           459.47 \\
310    \hline
311    26             & \textbf{  2768.24} &            2527.22 & \textbf{  484.95} &           478.83 \\
312    \hline
313    27             & \textbf{  3257.48} &            3011.90 & \textbf{  492.70} &           489.44 \\
314    \hline
315    28             & \textbf{  3752.44} &            3504.46 & \textbf{  496.78} &           495.07 \\
316    \hline
317    29             & \textbf{  4250.40} &            4001.16 & \textbf{  498.90} &           498.02 \\
318    \hline
319    30             & \textbf{  4749.91} &            4500.02 & \textbf{  500.00} &           499.54 \\
320    \hline
321    31             & \textbf{  5250.23} &            5000.00 & \textbf{  500.56} &           500.33 \\
322    \hline
323  \end{tabular}
324  \caption[Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration]{
325    Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration as
326    computed from \autoref{eq:DOMCFG_zgr_ana_2} using
327    the coefficients given in \autoref{eq:DOMCFG_zgr_coef}}
328  \label{tab:DOMCFG_orca_zgr}
329\end{table}
330%%%YY
331%% % -------------------------------------------------------------------------------------------------------------
332%% %        Meter Bathymetry
333%% % -------------------------------------------------------------------------------------------------------------
334%% =================================================================================================
335\subsection{Model bathymetry}
336\label{subsec:DOMCFG_bathy}
337
338Three options are possible for defining the bathymetry, according to the namelist variable
339\np{nn_bathy}{nn\_bathy} (found in \nam{dom}{dom} namelist (\texttt{DOMAINCFG} variant) ):
340\begin{description}
341\item [{\np[=0]{nn_bathy}{nn\_bathy}}]: a flat-bottom domain is defined.
342  The total depth $z_w (jpk)$ is given by the coordinate transformation.
343  The domain can either be a closed basin or a periodic channel depending on the parameter \np{jperio}{jperio}.
344\item [{\np[=-1]{nn_bathy}{nn\_bathy}}]: a domain with a bump of topography one third of the domain width at the central latitude.
345  This is meant for the "EEL-R5" configuration, a periodic or open boundary channel with a seamount.
346\item [{\np[=1]{nn_bathy}{nn\_bathy}}]: read a bathymetry and ice shelf draft (if needed).
347  The \textit{bathy\_meter.nc} file (Netcdf format) provides the ocean depth (positive, in meters) at
348  each grid point of the model grid.
349  The bathymetry is usually built by interpolating a standard bathymetry product (\eg\ ETOPO2) onto
350  the horizontal ocean mesh.
351  Defining the bathymetry also defines the coastline: where the bathymetry is zero,
352  no wet levels are defined (all levels are masked).
353\end{description}
354
355%% =================================================================================================
356\subsection{Choice of vertical grid}
357\label{sec:DOMCFG_vgrd}
358
359After reading the bathymetry, the algorithm for vertical grid definition differs between the different options:
360\begin{description}
361\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)$.
362\item [\forcode{ln_zps = .true.}] set a reference coordinate transformation $z_0(k)$, and calculate the thickness of the deepest level at
363  each $(i,j)$ point using the bathymetry, to obtain the final three-dimensional depth and scale factor arrays.
364\item [\forcode{ln_sco = .true.}] smooth the bathymetry to fulfill the hydrostatic consistency criteria and
365  set the three-dimensional transformation.
366\item [\forcode{s-z and s-zps}] smooth the bathymetry to fulfill the hydrostatic consistency criteria and
367  set the three-dimensional transformation $z(i,j,k)$,
368  and possibly introduce masking of extra land points to better fit the original bathymetry file.
369\end{description}
370
371%% =================================================================================================
372\subsubsection[$Z$-coordinate with uniform thickness levels (\forcode{ln_zco})]{$Z$-coordinate with uniform thickness levels (\protect\np{ln_zco}{ln\_zco})}
373\label{subsec:DOMCFG_zco}
374
375With this option the model topography can be fully described by the reference vertical
376coordinate and a 2D integer field giving the number of wet levels at each location
377(\forcode{bathy_level}). The resulting match to the real topography is likely to be poor
378though (especially with thick, deep levels) and slopes poorly represented. This option is
379rarely used in modern simulations but it can be useful for testing purposes.
380
381%% =================================================================================================
382\subsubsection[$Z$-coordinate with partial step (\forcode{ln_zps})]{$Z$-coordinate with partial step (\protect\np{ln_zps}{ln\_zps})}
383\label{subsec:DOMCFG_zps}
384
385In $z$-coordinate partial step, the depths of the model levels are defined by the
386reference analytical function $z_0(k)$ as described in \autoref{sec:DOMCFG_zref},
387\textit{except} in the bottom layer.  The thickness of the bottom layer is allowed to vary
388as a function of geographical location $(\lambda,\varphi)$ to allow a better
389representation of the bathymetry, especially in the case of small slopes (where the
390bathymetry varies by less than one level thickness from one grid point to the next).  The
391reference layer thicknesses $e_{3t}^0$ have been defined in the absence of bathymetry.
392With partial steps, layers from 1 to \texttt{jpk-2} can have a thickness smaller than
393$e_{3t}(jk)$.
394
395The model deepest layer (\texttt{jpk-1}) is allowed to have either a smaller or larger
396thickness than $e_{3t}(jpk)$: the maximum thickness allowed is $2*e_{3t}(jpk - 1)$.
397
398This has to be kept in mind when specifying values in \nam{dom}{dom} namelist
399(\texttt{DOMAINCFG} variant), such as the maximum depth \np{pphmax}{pphmax} in partial steps.
400
401For example, with \np{pphmax}{pphmax}~$= 5750~m$ for the DRAKKAR 45 layer grid, the maximum ocean
402depth allowed is actually $6000~m$ (the default thickness $e_{3t}(jpk - 1)$ being
403$250~m$).  Two variables in the namdom namelist are used to define the partial step
404vertical grid.  The mimimum water thickness (in meters) allowed for a cell partially
405filled with bathymetry at level jk is the minimum of \np{rn_e3zps_min}{rn\_e3zps\_min} (thickness in
406meters, usually $20~m$) or $e_{3t}(jk)*$\np{rn_e3zps_rat}{rn\_e3zps\_rat} (a fraction, usually 10\%, of
407the default thickness $e_{3t}(jk)$).
408
409%% =================================================================================================
410\subsubsection[$S$-coordinate (\forcode{ln_sco})]{$S$-coordinate (\protect\np{ln_sco}{ln\_sco})}
411\label{sec:DOMCFG_sco}
412
413\begin{listing}
414%  \nlst{namzgr_sco_domcfg}
415  \caption{\forcode{&namzgr_sco_domcfg}}
416  \label{lst:namzgr_sco_domcfg}
417  \begin{forlines}
418!-----------------------------------------------------------------------
419&namzgr_sco    !   s-coordinate or hybrid z-s-coordinate                (default: OFF)
420!-----------------------------------------------------------------------
421   ln_s_sh94   = .false.    !  Song & Haidvogel 1994 hybrid S-sigma   (T)|
422   ln_s_sf12   = .false.   !  Siddorn & Furner 2012 hybrid S-z-sigma (T)| if both are false the NEMO tanh stretching is applied
423   ln_sigcrit  = .false.   !  use sigma coordinates below critical depth (T) or Z coordinates (F) for Siddorn & Furner stretch
424                           !  stretching coefficients for all functions
425   rn_sbot_min =   10.0    !  minimum depth of s-bottom surface (>0) (m)
426   rn_sbot_max = 7000.0    !  maximum depth of s-bottom surface (= ocean depth) (>0) (m)
427   rn_hc       =  150.0    !  critical depth for transition to stretched coordinates
428                        !!!!!!!  Envelop bathymetry
429   rn_rmax     =    0.3    !  maximum cut-off r-value allowed (0<r_max<1)
430                        !!!!!!!  SH94 stretching coefficients  (ln_s_sh94 = .true.)
431   rn_theta    =    6.0    !  surface control parameter (0<=theta<=20)
432   rn_bb       =    0.8    !  stretching with SH94 s-sigma
433                        !!!!!!!  SF12 stretching coefficient  (ln_s_sf12 = .true.)
434   rn_alpha    =    4.4    !  stretching with SF12 s-sigma
435   rn_efold    =    0.0    !  efold length scale for transition to stretched coord
436   rn_zs       =    1.0    !  depth of surface grid box
437                           !  bottom cell depth (Zb) is a linear function of water depth Zb = H*a + b
438   rn_zb_a     =    0.024  !  bathymetry scaling factor for calculating Zb
439   rn_zb_b     =   -0.2    !  offset for calculating Zb
440                        !!!!!!!! Other stretching (not SH94 or SF12) [also uses rn_theta above]
441   rn_thetb    =    1.0    !  bottom control parameter  (0<=thetb<= 1)
442/
443  \end{forlines}
444\end{listing}
445
446Options are defined in \forcode{&zgr_sco} (\texttt{DOMAINcfg} only).
447In $s$-coordinate (\np[=.true.]{ln_sco}{ln\_sco}), the depth and thickness of the model levels are defined from
448the product of a depth field and either a stretching function or its derivative, respectively:
449
450\begin{align*}
451  % \label{eq:DOMCFG_sco_ana}
452  z(k)   &= h(i,j) \; z_0 (k) \\
453  e_3(k) &= h(i,j) \; z_0'(k)
454\end{align*}
455
456where $h$ is the depth of the last $w$-level ($z_0(k)$) defined at the $t$-point location in the horizontal and
457$z_0(k)$ is a function which varies from $0$ at the sea surface to $1$ at the ocean bottom.
458The depth field $h$ is not necessary the ocean depth,
459since a mixed step-like and bottom-following representation of the topography can be used
460(\autoref{fig:DOM_z_zps_s_sps}) or an envelop bathymetry can be defined (\autoref{fig:DOM_z_zps_s_sps}).
461The namelist parameter \np{rn_rmax}{rn\_rmax} determines the slope at which
462the terrain-following coordinate intersects the sea bed and becomes a pseudo z-coordinate.
463The coordinate can also be hybridised by specifying \np{rn_sbot_min}{rn\_sbot\_min} and \np{rn_sbot_max}{rn\_sbot\_max} as
464the minimum and maximum depths at which the terrain-following vertical coordinate is calculated.
465
466Options for stretching the coordinate are provided as examples,
467but care must be taken to ensure that the vertical stretch used is appropriate for the application.
468
469The original default \NEMO\ s-coordinate stretching is available if neither of the other options are specified as true
470(\np[=.false.]{ln_s_SH94}{ln\_s\_SH94} and \np[=.false.]{ln_s_SF12}{ln\_s\_SF12}).
471This uses a depth independent $\tanh$ function for the stretching \citep{madec.delecluse.ea_JPO96}:
472
473\[
474  z = s_{min} + C (s) (H - s_{min})
475  % \label{eq:DOMCFG_SH94_1}
476\]
477
478where $s_{min}$ is the depth at which the $s$-coordinate stretching starts and
479allows a $z$-coordinate to placed on top of the stretched coordinate,
480and $z$ is the depth (negative down from the asea surface).
481\begin{gather*}
482  s = - \frac{k}{n - 1} \quad \text{and} \quad 0 \leq k \leq n - 1
483  % \label{eq:DOMCFG_s}
484 \\
485 \label{eq:DOMCFG_sco_function}
486  C(s) = \frac{[\tanh(\theta \, (s + b)) - \tanh(\theta \, b)]}{2 \; \sinh(\theta)}
487\end{gather*}
488
489A stretching function,
490modified from the commonly used \citet{song.haidvogel_JCP94} stretching (\np[=.true.]{ln_s_SH94}{ln\_s\_SH94}),
491is also available and is more commonly used for shelf seas modelling:
492
493\[
494  C(s) =   (1 - b) \frac{\sinh(\theta s)}{\sinh(\theta)}
495         + b       \frac{\tanh \lt[ \theta \lt(s + \frac{1}{2} \rt) \rt] -   \tanh \lt( \frac{\theta}{2} \rt)}
496                        {                                                  2 \tanh \lt( \frac{\theta}{2} \rt)}
497 \label{eq:DOMCFG_SH94_2}
498\]
499
500\begin{figure}[!ht]
501  \centering
502  \includegraphics[width=0.66\textwidth]{DOMCFG_sco_function}
503  \caption[DOMAINcfg: examples of the stretching function applied to a seamount]{
504    Examples of the stretching function applied to a seamount;
505    from left to right: surface, surface and bottom, and bottom intensified resolutions}
506  \label{fig:DOMCFG_sco_function}
507\end{figure}
508
509where $H_c$ is the critical depth (\np{rn_hc}{rn\_hc}) at which the coordinate transitions from pure $\sigma$ to
510the stretched coordinate, and $\theta$ (\np{rn_theta}{rn\_theta}) and $b$ (\np{rn_bb}{rn\_bb}) are the surface and
511bottom control parameters such that $0 \leqslant \theta \leqslant 20$, and $0 \leqslant b \leqslant 1$.
512$b$ has been designed to allow surface and/or bottom increase of the vertical resolution
513(\autoref{fig:DOMCFG_sco_function}).
514
515Another example has been provided at version 3.5 (\np{ln_s_SF12}{ln\_s\_SF12}) that allows a fixed surface resolution in
516an analytical terrain-following stretching \citet{siddorn.furner_OM13}.
517In this case the a stretching function $\gamma$ is defined such that:
518
519\begin{equation}
520  z = - \gamma h \quad \text{with} \quad 0 \leq \gamma \leq 1
521  % \label{eq:DOMCFG_z}
522\end{equation}
523
524The function is defined with respect to $\sigma$, the unstretched terrain-following coordinate:
525
526\begin{gather*}
527  % \label{eq:DOMCFG_gamma_deriv}
528  \gamma =   A \lt( \sigma   - \frac{1}{2} (\sigma^2     + f (\sigma)) \rt)
529           + B \lt( \sigma^3 - f           (\sigma) \rt) + f (\sigma)       \\
530  \intertext{Where:}
531 \label{eq:DOMCFG_gamma}
532  f(\sigma) = (\alpha + 2) \sigma^{\alpha + 1} - (\alpha + 1) \sigma^{\alpha + 2}
533  \quad \text{and} \quad \sigma = \frac{k}{n - 1}
534\end{gather*}
535
536This gives an analytical stretching of $\sigma$ that is solvable in $A$ and $B$ as a function of
537the user prescribed stretching parameter $\alpha$ (\np{rn_alpha}{rn\_alpha}) that stretches towards
538the surface ($\alpha > 1.0$) or the bottom ($\alpha < 1.0$) and
539user prescribed surface (\np{rn_zs}{rn\_zs}) and bottom depths.
540The bottom cell depth in this example is given as a function of water depth:
541
542\[
543  % \label{eq:DOMCFG_zb}
544  Z_b = h a + b
545\]
546
547where the namelist parameters \np{rn_zb_a}{rn\_zb\_a} and \np{rn_zb_b}{rn\_zb\_b} are $a$ and $b$ respectively.
548
549\begin{figure}[!ht]
550  \centering
551  \includegraphics[width=0.66\textwidth]{DOMCFG_compare_coordinates_surface}
552  \caption[DOMAINcfg: comparison of $s$- and $z$-coordinate]{
553    A comparison of the \citet{song.haidvogel_JCP94} $S$-coordinate (solid lines),
554    a 50 level $Z$-coordinate (contoured surfaces) and
555    the \citet{siddorn.furner_OM13} $S$-coordinate (dashed lines) in the surface $100~m$ for
556    a idealised bathymetry that goes from $50~m$ to $5500~m$ depth.
557    For clarity every third coordinate surface is shown.}
558  \label{fig:DOMCFG_fig_compare_coordinates_surface}
559\end{figure}
560 % >>>>>>>>>>>>>>>>>>>>>>>>>>>>
561
562This gives a smooth analytical stretching in computational space that is constrained to
563given specified surface and bottom grid cell thicknesses in real space.
564This is not to be confused with the hybrid schemes that
565superimpose geopotential coordinates on terrain following coordinates thus
566creating a non-analytical vertical coordinate that
567therefore may suffer from large gradients in the vertical resolutions.
568This stretching is less straightforward to implement than the \citet{song.haidvogel_JCP94} stretching,
569but has the advantage of resolving diurnal processes in deep water and has generally flatter slopes.
570
571As with the \citet{song.haidvogel_JCP94} stretching the stretch is only applied at depths greater than
572the critical depth $h_c$.
573In this example two options are available in depths shallower than $h_c$,
574with pure sigma being applied if the \np{ln_sigcrit}{ln\_sigcrit} is true and pure z-coordinates if it is false
575(the z-coordinate being equal to the depths of the stretched coordinate at $h_c$).
576
577Minimising the horizontal slope of the vertical coordinate is important in terrain-following systems as
578large slopes lead to hydrostatic consistency.
579A hydrostatic consistency parameter diagnostic following \citet{haney_JPO91} has been implemented,
580and is output as part of the model mesh file at the start of the run.
581
582%% =================================================================================================
583\subsubsection[\zstar- or \sstar-coordinate (\forcode{ln_linssh})]{\zstar- or \sstar-coordinate (\protect\np{ln_linssh}{ln\_linssh})}
584\label{subsec:DOMCFG_zgr_star}
585
586This option is described in the Report by Levier \textit{et al.} (2007), available on the \NEMO\ web site.
587
588\section{Ice shelf cavity definition}
589\label{subsec:zgrisf}
590
591  If the under ice shelf seas are opened (\np{ln_isfcav}{ln\_isfcav}), the depth of the ice shelf/ocean interface has to be include in
592  the \textit{isfdraft\_meter} file (Netcdf format). This file need to include the \textit{isf\_draft} variable.
593  A positive value will mean ice shelf/ocean or ice shelf bedrock interface below the reference 0m ssh.
594  The exact shape of the ice shelf cavity (grounding line position and minimum thickness of the water column under an ice shelf, ...) can be specify in \nam{zgr_isf}{zgr_isf}.
595
596\begin{listing}
597  \caption{\forcode{&namzgr_isf}}
598  \label{lst:namzgr_isf}
599  \begin{forlines}
600!-----------------------------------------------------------------------
601&namzgr_isf    !   isf cavity geometry definition                       (default: OFF)
602!-----------------------------------------------------------------------
603   rn_isfdep_min    = 10.         ! minimum isf draft tickness (if lower, isf draft set to this value)
604   rn_glhw_min      = 1.e-3       ! minimum water column thickness to define the grounding line
605   rn_isfhw_min     = 10          ! minimum water column thickness in the cavity once the grounding line defined.
606   ln_isfchannel    = .false.     ! remove channel (based on 2d mask build from isfdraft-bathy)
607   ln_isfconnect    = .false.     ! force connection under the ice shelf (based on 2d mask build from isfdraft-bathy)
608      nn_kisfmax       = 999         ! limiter in level on the previous condition. (if change larger than this number, get back to value before we enforce the connection)
609      rn_zisfmax       = 7000.       ! limiter in m     on the previous condition. (if change larger than this number, get back to value before we enforce the connection)
610   ln_isfcheminey   = .false.     ! close cheminey
611   ln_isfsubgl      = .false.     ! remove subglacial lake created by the remapping process
612      rn_isfsubgllon   =    0.0      !  longitude of the seed to determine the open ocean
613      rn_isfsubgllat   =    0.0      !  latitude  of the seed to determine the open ocean
614/
615  \end{forlines}
616\end{listing}
617
618   The options available to define the shape of the under ice shelf cavities are listed in \nam{zgr_isf}{zgr_isf} (\texttt{DOMAINcfg} only, \autoref{lst:namzgr_isf}).
619
620   \subsection{Model ice shelf draft definition}
621   \label{subsec:zgrisf_isfd}
622
623   First of all, the tool make sure, the ice shelf draft ($h_{isf}$) is sensible and compatible with the bathymetry.
624   There are 3 compulsory steps to achieve this:
625
626   \begin{description}
627   \item{\np{rn_isfdep_min}{rn\_isfdep\_min}:} this is the minimum ice shelf draft. This is to make sure there is no ridiculous thin ice shelf. If \np{rn_isfdep_min}{rn\_isfdep\_min} is smaller than the surface level, \np{rn_isfdep_min}{rn\_isfdep\_min} is set to $e3t\_1d(1)$.
628   Where $h_{isf} < MAX(e3t\_1d(1),\np{rn_isfdep_min}{rn\_isfdep\_min}$), $h_{isf}$ is set to \np{rn_isfdep_min}{rn\_isfdep\_min}.
629
630   \item{\np{rn_glhw_min}{rn\_glhw\_min}:} This parameter is used to define the grounding line position.
631   Where the difference between the bathymetry and the ice shelf draft is smaller than \np{rn_glhw_min}{rn\_glhw\_min}, the cell are grounded (ie masked).
632   This step is needed to take into account possible small mismatch between ice shelf draft value and bathymetry value (sources are coming from different grid, different data processes, rounding error, ...).
633
634   \item{\np{rn_isfhw_min}{rn\_isfhw\_min}:} This parameter is the minimum water column thickness in the cavity.
635   Where the water column thickness is lower than \np{rn_isfhw_min}{rn\_isfhw\_min}, the ice shelf draft is adjusted to match this criterion.
636   If for any reason, this adjustement break the minimum ice shelf draft allowed (\np{rn_isfdep_min}{rn\_isfdep\_min}), the cell is masked.
637   \end{description}
638
639   Once all these adjustements are made, if the water column thickness contains one cell wide channels, these channels can be closed using \np{ln_isfchannel}{ln\_isfchannel}
640 
641   \subsection{Model top level definition}
642   After the definition of the ice shelf draft, the tool defines the top level.
643   The compulsory criterion is that the water column needs at least 2 wet cells in the water column at U- and V-points.
644   To do so, if there one cell wide water column, the tools adjust the ice shelf draft to fillful the requierement.\\
645
646   The process is the following:
647   \begin{description}
648   \item{step 1:} The top level is defined in the same way as the bottom level is defined.
649   \item{step 2:} The isolated grid point in the bathymetry are filled (as it is done in a domain without ice shelf)
650   \item{step 3:} The tools make sure, the top level is above or equal to the bottom level
651   \item{step 4:} If the water column at a U- or V- point is one wet cell wide, the ice shelf draft is adjusted. So the actual top cell become fully open and the new
652   top cell thickness is set to the minimum cell thickness allowed (following the same logic as for the bottom partial cell). This step is iterated 4 times to ensure the condition is fullfill along the 4 sides of the cell.
653   \end{description}
654
655   In case of steep slope and shallow water column, it likely that 2 cells are disconnected (bathymetry above its neigbourging ice shelf draft).
656   The option \np{ln_isfconnect}{ln\_isfconnect} allow the tool to force the connection between these 2 cells.
657   Some limiters in meter or levels on the digging allowed by the tool are available (respectively, \np{rn_zisfmax}{rn\_zisfmax} or \np{rn_kisfmax}{rn\_kisfmax}).
658   This will prevent the formation of subglacial lakes at the expense of long vertical pipe to connect cells at very different levels.
659
660   \subsection{Subglacial lakes}
661   Despite careful setting of your ice shelf draft and bathymetry input file as well as setting described in \autoref{subsec:zgrisf_isfd}, some situation are unavoidable.
662   For exemple if you setup your ice shelf draft and bathymetry to do ocean/ice sheet coupling,
663   you may decide to fill the whole antarctic with a bathymetry and an ice shelf draft value (ice/bedrock interface depth when grounded).
664   If you do so, the subglacial lakes will show up (Vostock for example). An other possibility is with coarse vertical resolution, some ice shelves could be cut in 2 parts:
665   one connected to the main ocean and an other one closed which can be considered as a subglacial sea be the model.\\
666
667   The namelist option \np{ln_isfsubgl}{ln\_isfsubgl} allow you to remove theses subglacial lakes.
668   This may be useful for esthetical reason or for stability reasons:
669
670   \begin{description}
671   \item $\bullet$ In a subglacial lakes, in case of very weak circulation (often the case), the only heat flux is the conductive heat flux through the ice sheet.
672         This will lead to constant freezing until water reaches -20C.
673         This is one of the defitiency of the 3 equation melt formulation (for details on this formulation, see: \autoref{sec:isf}).
674   \item $\bullet$ In case of coupling with an ice sheet model,
675         the ssh in the subglacial lakes and the main ocean could be very different (ssh initial adjustement for example),
676         and so if for any reason both a connected at some point, the model is likely to fall over.\\
677   \end{description}
678
679\section{Closed sea definition}
680\label{sec:clocfg}
681
682\begin{listing}
683  \caption{\forcode{&namclo}}
684  \label{lst:namdom_clo}
685  \begin{forlines}
686!-----------------------------------------------------------------------
687&namclo ! (closed sea : need ln_domclo = .true. in namcfg)
688!-----------------------------------------------------------------------
689   rn_lon_opnsea = -2.0     ! longitude seed of open ocean
690   rn_lat_opnsea = -2.0     ! latitude  seed of open ocean
691   nn_closea = 8           ! number of closed seas ( = 0; only the open_sea mask will be computed)
692   !                name   ! lon_src ! lat_src ! lon_trg ! lat_trg ! river mouth area   ! net evap/precip correction scheme ! radius tgt   ! id trg
693   !                       ! (degree)! (degree)! (degree)! (degree)! local/coast/global ! (glo/rnf/emp)                     !     (m)      !
694   ! North American lakes
695   sn_lake(1) = 'superior' ,  -86.57 ,  47.30  , -66.49  , 50.45   , 'local'            , 'rnf'                             ,   550000.0 , 2   
696   sn_lake(2) = 'michigan' ,  -87.06 ,  42.74  , -66.49  , 50.45   , 'local'            , 'rnf'                             ,   550000.0 , 2   
697   sn_lake(3) = 'huron'    ,  -82.51 ,  44.74  , -66.49  , 50.45   , 'local'            , 'rnf'                             ,   550000.0 , 2   
698   sn_lake(4) = 'erie'     ,  -81.13 ,  42.25  , -66.49  , 50.45   , 'local'            , 'rnf'                             ,   550000.0 , 2   
699   sn_lake(5) = 'ontario'  ,  -77.72 ,  43.62  , -66.49  , 50.45   , 'local'            , 'rnf'                             ,   550000.0 , 2   
700   ! African Lake
701   sn_lake(6) = 'victoria' ,   32.93 ,  -1.08  ,  30.44  , 31.37   , 'coast'            , 'emp'                             ,   100000.0 , 3   
702   ! Asian Lakes
703   sn_lake(7) = 'caspian'  ,   50.0  ,  44.0   ,   0.0   ,  0.0    , 'global'           , 'glo'                             ,        0.0 , 1     
704   sn_lake(8) = 'aral'     ,   60.0  ,  45.0   ,   0.0   ,  0.0    , 'global'           , 'glo'                             ,        0.0 , 1   
705/
706   \end{forlines}
707\end{listing}
708
709The options available to define the closed seas and how closed sea net fresh water input will be redistributed by NEMO are listed in \nam{clo}{dom_clo} (\texttt{DOMAINcfg} only).
710The individual definition of each closed sea is managed by \np{sn_lake}{sn\_lake}. In this fields the user needs to define:\\
711   \begin{description}
712   \item $\bullet$    the name of the closed sea (print output purposes).
713   \item $\bullet$    the seed location to define the area of the closed sea (if seed on land because not present in this configuration, this closed sea will be ignored).\\
714   \item $\bullet$    the seed location for the target area.
715   \item $\bullet$    the type of target area ('local','coast' or 'global'). See point 6 for definition of these cases.
716   \item $\bullet$    the type of redistribution scheme for the net fresh water flux over the closed sea (as a runoff in a target area, as emp in a target area, as emp globally). For the runoff case, if the net fwf is negative, it will be redistribut globally.
717   \item $\bullet$    the radius of the target area (not used for the 'global' case). So the target defined by a 'local' target area of a radius of 100km, for example, correspond to all the wet points within this radius. The coastal case will return only the coastal point within the specifid radius.
718   \item $\bullet$    the target id. This target id is used to group multiple lakes into the same river ouflow (Great Lakes for example).
719   \end{description}
720
721The closed sea module defines a number of masks in the \textit{domain\_cfg} output:
722   \begin{description}
723   \item[\textit{mask\_opensea}:] a mask of the main ocean without all the closed seas closed. This mask is defined by a flood filling algorithm with an initial seed (localisation defined by \np{rn_lon_opnsea}{rn\_lon\_opnsea} and \np{rn_lat_opnsea}{rn\_lat\_opnsea}).
724   \item[\textit{mask\_csglo}, \textit{mask\_csrnf}, \textit{mask\_csemp}:] a mask of all the closed seas defined in the namelist by \np{sn_lake}{sn\_lake} for each redistribution scheme. The total number of defined closed seas has to be defined in \np{nn_closea}{nn\_closea}.
725   \item[\textit{mask\_csgrpglo}, \textit{mask\_csgrprnf}, \textit{mask\_csgrpemp}:] a mask of all the closed seas and targets grouped by target id for each type of redistribution scheme.
726   \item[\textit{mask\_csundef}:] a mask of all the closed sea not defined in \np{sn_lake}{sn\_lake}. This will allows NEMO to mask them if needed or to inform the user of potential minor issues in its bathymetry.
727   \end{description}
728   
729\subinc{\input{../../global/epilogue}}
730
731\end{document}
Note: See TracBrowser for help on using the repository browser.