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

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

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

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

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

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

  • \nam: LaTeX code in the \nam{tra_adv}{tra\_adv} → PDF ' in the &namtra_adv (namelist X.X) ' with syntax highlighting, the hyperlink and the index entry
  • \np: LaTeX code \np[=.true.]{ln_flx}{ln\_flx} → PDF ln_flux=.true. with syntax highlighting for the whole string and the entry in the 'parameters' index
File size: 16.5 KB
Line 
1\documentclass[../main/NEMO_manual]{subfiles}
2
3\begin{document}
4% ================================================================
5% Chapter 1 Model Basics
6% ================================================================
7% ================================================================
8% Curvilinear \zstar- \sstar-coordinate System
9% ================================================================
10\chapter{ essai \zstar \sstar}
11\section{Curvilinear \zstar- or \sstar coordinate system}
12
13% -------------------------------------------------------------------------------------------------------------
14% ????
15% -------------------------------------------------------------------------------------------------------------
16
17\colorbox{yellow}{ to be updated }
18
19In that case, the free surface equation is nonlinear, and the variations of volume are fully taken into account.
20These coordinates systems is presented in a report \citep{levier.treguier.ea_rpt07} available on the \NEMO\ web site.
21
22\colorbox{yellow}{  end of to be updated}
23
24% from MOM4p1 documentation
25
26To overcome problems with vanishing surface and/or bottom cells, we consider the zstar coordinate
27\[
28  % \label{eq:MBZ_PE_}
29  z^\star = H \left( \frac{z-\eta}{H+\eta} \right)
30\]
31
32This coordinate is closely related to the "eta" coordinate used in many atmospheric models
33(see Black (1994) for a review of eta coordinate atmospheric models).
34It was originally used in ocean models by Stacey et al. (1995) for studies of tides next to shelves,
35and it has been recently promoted by Adcroft and Campin (2004) for global climate modelling.
36
37The surfaces of constant $z^\star$ are quasi-horizontal.
38Indeed, the $z^\star$ coordinate reduces to $z$ when $\eta$ is zero.
39In general, when noting the large differences between undulations of the bottom topography versus undulations in
40the surface height, it is clear that surfaces constant $z^\star$ are very similar to the depth surfaces.
41These properties greatly reduce difficulties of computing the horizontal pressure gradient relative to
42terrain following sigma models discussed in \autoref{subsec:MB_sco}.
43Additionally, since $z^\star$ when $\eta = 0$, no flow is spontaneously generated in
44an unforced ocean starting from rest, regardless the bottom topography.
45This behaviour is in contrast to the case with "s"-models, where pressure gradient errors in the presence of
46nontrivial topographic variations can generate nontrivial spontaneous flow from a resting state,
47depending on the sophistication of the pressure gradient solver.
48The quasi-horizontal nature of the coordinate surfaces also facilitates the implementation of
49neutral physics parameterizations in $z^\star$ models using the same techniques as in $z$-models
50(see Chapters 13-16 of Griffies (2004) for a discussion of neutral physics in $z$-models,
51as well as  \autoref{sec:LDF_slp} in this document for treatment in \NEMO).
52
53The range over which $z^\star$ varies is time independent $-H \leq z^\star \leq 0$.
54Hence, all cells remain nonvanishing, so long as the surface height maintains $\eta > ?H$.
55This is a minor constraint relative to that encountered on the surface height when using $s = z$ or $s = z - \eta$.
56
57Because $z^\star$ has a time independent range, all grid cells have static increments ds,
58and the sum of the ver tical increments yields the time independent ocean depth %�k ds = H.
59The $z^\star$ coordinate is therefore invisible to undulations of the free surface,
60since it moves along with the free surface.
61This proper ty means that no spurious ver tical transpor t is induced across surfaces of
62constant $z^\star$ by the motion of external gravity waves.
63Such spurious transpor t can be a problem in z-models, especially those with tidal forcing.
64Quite generally, the time independent range for the $z^\star$ coordinate is a very convenient property that
65allows for a nearly arbitrary vertical resolution even in the presence of large amplitude fluctuations of
66the surface height, again so long as $\eta > -H$.
67
68%%%
69%  essai update time splitting...
70%%%
71
72% ================================================================
73% Surface Pressure Gradient and Sea Surface Height
74% ================================================================
75\section[Surface pressure gradient and sea surface heigth (\textit{dynspg.F90})]{Surface pressure gradient and sea surface heigth (\protect\mdl{dynspg})}
76\label{sec:MBZ_dyn_hpg_spg}
77%-----------------------------------------nam_dynspg----------------------------------------------------
78
79%\nlst{nam_dynspg}
80%------------------------------------------------------------------------------------------------------------
81Options are defined through the \nam{_dynspg}{\_dynspg} namelist variables.
82The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:MB_hor_pg}).
83The main distinction is between the fixed volume case (linear free surface or rigid lid) and
84the variable volume case (nonlinear free surface, \key{vvl} is active).
85In the linear free surface case (\autoref{subsec:MB_free_surface}) and rigid lid (\autoref{PE_rigid_lid}),
86the vertical scale factors $e_{3}$ are fixed in time,
87while in the nonlinear case (\autoref{subsec:MB_free_surface}) they are time-dependent.
88With both linear and nonlinear free surface, external gravity waves are allowed in the equations,
89which imposes a very small time step when an explicit time stepping is used.
90Two methods are proposed to allow a longer time step for the three-dimensional equations:
91the filtered free surface, which is a modification of the continuous equations %(see \autoref{eq:MB_flt?}),
92and the split-explicit free surface described below.
93The extra term introduced in the filtered method is calculated implicitly,
94so that the update of the next velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}.
95
96%-------------------------------------------------------------
97% Explicit
98%-------------------------------------------------------------
99\subsubsection[Explicit (\texttt{\textbf{key\_dynspg\_exp}})]{Explicit (\protect\key{dynspg\_exp})}
100\label{subsec:MBZ_dyn_spg_exp}
101
102In the explicit free surface formulation, the model time step is chosen small enough to
103describe the external gravity waves (typically a few ten seconds).
104The sea surface height is given by:
105\begin{equation}
106  \label{eq:MBZ_dynspg_ssh}
107  \frac{\partial \eta }{\partial t}\equiv \frac{\text{EMP}}{\rho_w }+\frac{1}{e_{1T}
108    e_{2T} }\sum\limits_k {\left( {\delta_i \left[ {e_{2u} e_{3u} u}
109        \right]+\delta_j \left[ {e_{1v} e_{3v} v} \right]} \right)}
110\end{equation}
111
112where EMP is the surface freshwater budget (evaporation minus precipitation, and minus river runoffs
113(if the later are introduced as a surface freshwater flux, see \autoref{chap:SBC}) expressed in $Kg.m^{-2}.s^{-1}$,
114and $\rho_w =1,000\,Kg.m^{-3}$ is the volumic mass of pure water.
115The sea-surface height is evaluated using a leapfrog scheme in combination with an Asselin time filter,
116(\ie\ the velocity appearing in (\autoref{eq:DYN_spg_ssh}) is centred in time (\textit{now} velocity).
117
118The surface pressure gradient, also evaluated using a leap-frog scheme, is then simply given by:
119\begin{equation}
120  \label{eq:MBZ_dynspg_exp}
121  \left\{
122    \begin{aligned}
123      - \frac{1}                    {e_{1u}} \; \delta_{i+1/2} \left[  \,\eta\,  \right] \\ \\
124      - \frac{1}                    {e_{2v}} \; \delta_{j+1/2} \left[  \,\eta\,  \right]
125    \end{aligned}
126  \right.
127\end{equation}
128
129Consistent with the linearization, a $\left. \rho \right|_{k=1} / \rho_o$ factor is omitted in
130(\autoref{eq:DYN_spg_exp}).
131
132%-------------------------------------------------------------
133% Split-explicit time-stepping
134%-------------------------------------------------------------
135\subsubsection[Split-explicit time-stepping (\texttt{\textbf{key\_dynspg\_ts}})]{Split-explicit time-stepping (\protect\key{dynspg\_ts})}
136\label{subsec:MBZ_dyn_spg_ts}
137%--------------------------------------------namdom----------------------------------------------------
138
139%--------------------------------------------------------------------------------------------------------------
140The split-explicit free surface formulation used in OPA follows the one proposed by \citet{Griffies2004?}.
141The general idea is to solve the free surface equation with a small time step,
142while the three dimensional prognostic variables are solved with a longer time step that
143is a multiple of \np{rdtbt} in the \nam{dom} namelist (Figure III.3).
144
145%>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >
146\begin{figure}[!t]
147  \centering
148  \includegraphics[width=0.66\textwidth]{Fig_DYN_dynspg_ts}
149  \caption[Schematic of the split-explicit time stepping scheme for
150  the barotropic and baroclinic modes, after \citet{Griffies2004?}]{
151    Schematic of the split-explicit time stepping scheme for the barotropic and baroclinic modes,
152    after \citet{Griffies2004?}.
153    Time increases to the right.
154    Baroclinic time steps are denoted by $t-\Delta t$, $t, t+\Delta t$, and $t+2\Delta t$.
155    The curved line represents a leap-frog time step,
156    and the smaller barotropic time steps $N \Delta t=2\Delta t$ are denoted by the zig-zag line.
157    The vertically integrated forcing \textbf{M}(t) computed at
158    baroclinic time step t represents the interaction between the barotropic and baroclinic motions.
159    While keeping the total depth, tracer, and freshwater forcing fields fixed,
160    a leap-frog integration carries the surface height and vertically integrated velocity from
161    t to $t+2 \Delta t$ using N barotropic time steps of length $\Delta t$.
162    Time averaging the barotropic fields over the N+1 time steps (endpoints included)
163    centers the vertically integrated velocity at the baroclinic timestep $t+\Delta t$.
164    A baroclinic leap-frog time step carries the surface height to $t+\Delta t$ using
165    the convergence of the time averaged vertically integrated velocity taken from
166    baroclinic time step t.}
167  \label{fig:MBZ_dyn_dynspg_ts}
168\end{figure}
169%>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >
170
171The split-explicit formulation has a damping effect on external gravity waves,
172which is weaker than the filtered free surface but still significant as shown by \citet{levier.treguier.ea_rpt07} in
173the case of an analytical barotropic Kelvin wave.
174
175%from griffies book: .....   copy past !
176
177\textbf{title: Time stepping the barotropic system }
178
179Assume knowledge of the full velocity and tracer fields at baroclinic time $\tau$.
180Hence, we can update the surface height and vertically integrated velocity with a leap-frog scheme using
181the small barotropic time step $\Delta t$.
182We have
183\[
184  % \label{eq:MBZ_dyn_spg_ts_eta}
185  \eta^{(b)}(\tau,t_{n+1}) - \eta^{(b)}(\tau,t_{n+1}) (\tau,t_{n-1})
186  = 2 \Delta t \left[-\nabla \cdot \textbf{U}^{(b)}(\tau,t_n) + \text{EMP}_w(\tau) \right]
187\]
188\begin{multline*}
189  % \label{eq:MBZ_dyn_spg_ts_u}
190  \textbf{U}^{(b)}(\tau,t_{n+1}) - \textbf{U}^{(b)}(\tau,t_{n-1}\\
191  = 2\Delta t \left[ - f \textbf{k} \times \textbf{U}^{(b)}(\tau,t_{n})
192    - H(\tau) \nabla p_s^{(b)}(\tau,t_{n}) +\textbf{M}(\tau) \right]
193\end{multline*}
194\
195
196In these equations, araised (b) denotes values of surface height and
197vertically integrated velocity updated with the barotropic time steps.
198The $\tau$ time label on $\eta^{(b)}$ and $U^{(b)}$ denotes the baroclinic time at which
199the vertically integrated forcing $\textbf{M}(\tau)$
200(note that this forcing includes the surface freshwater forcing), the tracer fields,
201the freshwater flux $\text{EMP}_w(\tau)$, and total depth of the ocean $H(\tau)$ are held for
202the duration of the barotropic time stepping over a single cycle.
203This is also the time that sets the barotropic time steps via
204\[
205  % \label{eq:MBZ_dyn_spg_ts_t}
206  t_n=\tau+n\Delta t
207\]
208with $n$ an integer.
209The density scaled surface pressure is evaluated via
210\[
211  % \label{eq:MBZ_dyn_spg_ts_ps}
212  p_s^{(b)}(\tau,t_{n}) =
213  \begin{cases}
214    g \;\eta_s^{(b)}(\tau,t_{n}) \;\rho(\tau)_{k=1}) / \rho_o  &      \text{non-linear case} \\
215    g \;\eta_s^{(b)}(\tau,t_{n})  &      \text{linear case}
216  \end{cases}
217\]
218To get started, we assume the following initial conditions
219\[
220  % \label{eq:MBZ_dyn_spg_ts_eta}
221  \begin{split}
222    \eta^{(b)}(\tau,t_{n=0}) &= \overline{\eta^{(b)}(\tau)} \\
223    \eta^{(b)}(\tau,t_{n=1}) &= \eta^{(b)}(\tau,t_{n=0}) + \Delta t \ \text{RHS}_{n=0}
224  \end{split}
225\]
226with
227\[
228  % \label{eq:MBZ_dyn_spg_ts_etaF}
229  \overline{\eta^{(b)}(\tau)} = \frac{1}{N+1} \sum\limits_{n=0}^N \eta^{(b)}(\tau-\Delta t,t_{n})
230\]
231the time averaged surface height taken from the previous barotropic cycle.
232Likewise,
233\[
234  % \label{eq:MBZ_dyn_spg_ts_u}
235  \textbf{U}^{(b)}(\tau,t_{n=0}) = \overline{\textbf{U}^{(b)}(\tau)} \\ \\
236  \textbf{U}(\tau,t_{n=1}) = \textbf{U}^{(b)}(\tau,t_{n=0}) + \Delta t \ \text{RHS}_{n=0}
237\]
238with
239\[
240  % \label{eq:MBZ_dyn_spg_ts_u}
241  \overline{\textbf{U}^{(b)}(\tau)} = \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau-\Delta t,t_{n})
242\]
243the time averaged vertically integrated transport.
244Notably, there is no Robert-Asselin time filter used in the barotropic portion of the integration.
245
246Upon reaching $t_{n=N} = \tau + 2\Delta \tau$ , the vertically integrated velocity is time averaged to
247produce the updated vertically integrated velocity at baroclinic time $\tau + \Delta \tau$
248\[
249  % \label{eq:MBZ_dyn_spg_ts_u}
250  \textbf{U}(\tau+\Delta t) = \overline{\textbf{U}^{(b)}(\tau+\Delta t)}
251  = \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau,t_{n})
252\]
253The surface height on the new baroclinic time step is then determined via
254a baroclinic leap-frog using the following form
255\begin{equation}
256  \label{eq:MBZ_dyn_spg_ts_ssh}
257  \eta(\tau+\Delta) - \eta^{F}(\tau-\Delta) = 2\Delta t \ \left[ - \nabla \cdot \textbf{U}(\tau) + \text{EMP}_w \right]
258\end{equation}
259
260The use of this "big-leap-frog" scheme for the surface height ensures compatibility between
261the mass/volume budgets and the tracer budgets.
262More discussion of this point is provided in Chapter 10 (see in particular Section 10.2).
263
264In general, some form of time filter is needed to maintain integrity of the surface height field due to
265the leap-frog splitting mode in equation \autoref{eq:MBZ_dyn_spg_ts_ssh}.
266We have tried various forms of such filtering,
267with the following method discussed in Griffies et al. (2001) chosen due to its stability and
268reasonably good maintenance of tracer conservation properties (see ??)
269
270\begin{equation}
271  \label{eq:MBZ_dyn_spg_ts_sshf}
272  \eta^{F}(\tau-\Delta) =  \overline{\eta^{(b)}(\tau)}
273\end{equation}
274Another approach tried was
275
276\[
277  % \label{eq:MBZ_dyn_spg_ts_sshf2}
278  \eta^{F}(\tau-\Delta) = \eta(\tau)
279  + (\alpha/2) \left[\overline{\eta^{(b)}}(\tau+\Delta t)
280    + \overline{\eta^{(b)}}(\tau-\Delta t) -2 \;\eta(\tau) \right]
281\]
282
283which is useful since it isolates all the time filtering aspects into the term multiplied by $\alpha$.
284This isolation allows for an easy check that tracer conservation is exact when eliminating tracer and
285surface height time filtering (see ?? for more complete discussion).
286However, in the general case with a non-zero $\alpha$, the filter \autoref{eq:MBZ_dyn_spg_ts_sshf} was found to
287be more conservative, and so is recommended.
288
289%-------------------------------------------------------------
290% Filtered formulation
291%-------------------------------------------------------------
292\subsubsection[Filtered formulation (\texttt{\textbf{key\_dynspg\_flt}})]{Filtered formulation (\protect\key{dynspg\_flt})}
293\label{subsec:MBZ_dyn_spg_flt}
294
295The filtered formulation follows the \citet{Roullet2000?} implementation.
296The extra term introduced in the equations (see {\S}I.2.2) is solved implicitly.
297The elliptic solvers available in the code are documented in \autoref{chap:MISC}.
298The amplitude of the extra term is given by the namelist variable \np{rnu}.
299The default value is 1, as recommended by \citet{Roullet2000?}
300
301\colorbox{red}{\np{rnu}\forcode{=1} to be suppressed from namelist !}
302
303%-------------------------------------------------------------
304% Non-linear free surface formulation
305%-------------------------------------------------------------
306\subsection[Non-linear free surface formulation (\texttt{\textbf{key\_vvl}})]{Non-linear free surface formulation (\protect\key{vvl})}
307\label{subsec:MBZ_dyn_spg_vvl}
308
309In the non-linear free surface formulation, the variations of volume are fully taken into account.
310This option is presented in a report \citep{levier.treguier.ea_rpt07} available on the \NEMO\ web site.
311The three time-stepping methods (explicit, split-explicit and filtered) are the same as in
312\autoref{?:DYN_spg_linear?} except that the ocean depth is now time-dependent.
313In particular, this means that in filtered case, the matrix to be inverted has to be recomputed at each time-step.
314
315\biblio
316
317\pindex
318
319\end{document}
Note: See TracBrowser for help on using the repository browser.