/[MITgcm]/manual/s_algorithm/text/time_stepping.tex

Diff of /manual/s_algorithm/text/time_stepping.tex

Parent Directory | Revision Log | View Revision Graph Revision Graph | View Patch Patch

-revision 1.10 by adcroft,
Tue Nov  6 15:07:32 2001 UTC
+revision 1.34 by jmc,
Mon Sep 25 18:11:06 2017 UTC
 Line 1
  % $Header$
  % $Name$
+ This chapter lays out the numerical schemes that are
+ employed in the core MITgcm algorithm. Whenever possible
+ links are made to actual program code in the MITgcm implementation.
+ The chapter begins with a discussion of the temporal discretization
+ used in MITgcm. This discussion is followed by sections that
+ describe the spatial discretization. The schemes employed for momentum
+ terms are described first, afterwards the schemes that apply to
+ passive and dynamically active tracers are described.
+ \input{s_algorithm/text/notation}
+ \section{Time-stepping}
+ \label{sec:time_stepping}
+ \begin{rawhtml}
+ <!-- CMIREDIR:time-stepping: -->
+ \end{rawhtml}
  The equations of motion integrated by the model involve four
  prognostic equations for flow, $u$ and $v$, temperature, $\theta$, and
  salt/moisture, $S$, and three diagnostic equations for vertical flow,
-Line 34 
 evaluated explicitly in time. Since the
+Line 51 
 evaluated explicitly in time. Since the
  independent of the particular time-stepping scheme chosen we will
  describe first the over-arching algorithm, known as the pressure
  method, with a rigid-lid model in section
- \ref{sect:pressure-method-rigid-lid}. This algorithm is essentially
+ \ref{sec:pressure-method-rigid-lid}. This algorithm is essentially
  unchanged, apart for some coefficients, when the rigid lid assumption
  is replaced with a linearized implicit free-surface, described in
- section \ref{sect:pressure-method-linear-backward}. These two flavors
+ section \ref{sec:pressure-method-linear-backward}. These two flavors
  of the pressure-method encompass all formulations of the model as it
  exists today. The integration of explicit in time terms is out-lined
- in section \ref{sect:adams-bashforth} and put into the context of the
+ in section \ref{sec:adams-bashforth} and put into the context of the
- overall algorithm in sections \ref{sect:adams-bashforth-sync} and
+ overall algorithm in sections \ref{sec:adams-bashforth-sync} and
- \ref{sect:adams-bashforth-staggered}. Inclusion of non-hydrostatic
+ \ref{sec:adams-bashforth-staggered}. Inclusion of non-hydrostatic
  terms requires applying the pressure method in three dimensions
  instead of two and this algorithm modification is described in section
- \ref{sect:non-hydrostatic}. Finally, the free-surface equation may be
+ \ref{sec:non-hydrostatic}. Finally, the free-surface equation may be
  treated more exactly, including non-linear terms, and this is
- described in section \ref{sect:nonlinear-freesurface}.
+ described in section \ref{sec:nonlinear-freesurface}.
- \section{Pressure method with rigid-lid} \label{sect:pressure-method-rigid-lid}
+ \section{Pressure method with rigid-lid}
+ \label{sec:pressure-method-rigid-lid}
+ \begin{rawhtml}
+ <!-- CMIREDIR:pressure_method_rigid_lid: -->
+ \end{rawhtml}
  \begin{figure}
  \begin{center}
- \resizebox{4.0in}{!}{\includegraphics{part2/pressure-method-rigid-lid.eps}}
+ \resizebox{4.0in}{!}{\includegraphics{s_algorithm/figs/pressure-method-rigid-lid.eps}}
  \end{center}
  \caption{
  A schematic of the evolution in time of the pressure method
-Line 69 
 temporary.}
+Line 90 
 temporary.}
  \begin{figure}
  \begin{center} \fbox{ \begin{minipage}{4.5in} \begin{tabbing}
  aaa \= aaa \= aaa \= aaa \= aaa \= aaa \kill
- FORWARD\_STEP \\
+ \filelink{FORWARD\_STEP}{model-src-forward_step.F} \\
  \> DYNAMICS \\
  \>\> TIMESTEP \` $u^*$,$v^*$ (\ref{eq:ustar-rigid-lid},\ref{eq:vstar-rigid-lid}) \\
  \> SOLVE\_FOR\_PRESSURE \\
  \>\> CALC\_DIV\_GHAT \` $H\widehat{u^*}$,$H\widehat{v^*}$ (\ref{eq:elliptic}) \\
  \>\> CG2D \` $\eta^{n+1}$ (\ref{eq:elliptic}) \\
- \> THE\_CORRECTION\_STEP  \\
+ \> MOMENTUM\_CORRECTION\_STEP  \\
  \>\> CALC\_GRAD\_PHI\_SURF \` $\nabla \eta^{n+1}$ \\
  \>\> CORRECTION\_STEP \` $u^{n+1}$,$v^{n+1}$ (\ref{eq:un+1-rigid-lid},\ref{eq:vn+1-rigid-lid})
  \end{tabbing} \end{minipage} } \end{center}
- \caption{Calling tree for the pressure method algorihtm}
+ \caption{Calling tree for the pressure method algorithm
+   (\filelink{FORWARD\_STEP}{model-src-forward_step.F})}
  \label{fig:call-tree-pressure-method}
  \end{figure}
-Line 162 
 The correspondence to the code is as fol
+Line 184 
 The correspondence to the code is as fol
  \item
  the prognostic phase, equations \ref{eq:ustar-rigid-lid} and \ref{eq:vstar-rigid-lid},
  stepping forward $u^n$ and $v^n$ to $u^{*}$ and $v^{*}$ is coded in
- {\em TIMESTEP.F}
+ \filelink{TIMESTEP()}{model-src-timestep.F}
  \item
  the vertical integration, $H \widehat{u^*}$ and $H
  \widehat{v^*}$, divergence and inversion of the elliptic operator in
- equation \ref{eq:elliptic} is coded in {\em
+ equation \ref{eq:elliptic} is coded in
- SOLVE\_FOR\_PRESSURE.F}
+ \filelink{SOLVE\_FOR\_PRESSURE()}{model-src-solve_for_pressure.F}
  \item
  finally, the new flow field at time level $n+1$ given by equations
- \ref{eq:un+1-rigid-lid} and \ref{eq:vn+1-rigid-lid} is calculated in {\em CORRECTION\_STEP.F}.
+ \ref{eq:un+1-rigid-lid} and \ref{eq:vn+1-rigid-lid} is calculated in
+ \filelink{CORRECTION\_STEP()}{model-src-correction_step.F}.
  \end{itemize}
  The calling tree for these routines is given in
  Fig.~\ref{fig:call-tree-pressure-method}.
+ %\paragraph{Need to discuss implicit viscosity somewhere:}
- \paragraph{Need to discuss implicit viscosity somewhere:}
+ In general, the horizontal momentum time-stepping can contain some terms
+ that are treated implicitly in time,
+ such as the vertical viscosity when using the backward time-stepping scheme
+ (\varlink{implicitViscosity}{implicitViscosity} {\it =.TRUE.}).
+ The method used to solve those implicit terms is provided in
+ section \ref{sec:implicit-backward-stepping}, and modifies
+ equations \ref{eq:discrete-time-u} and \ref{eq:discrete-time-v} to
+ give:
  \begin{eqnarray}
- \frac{1}{\Delta t} u^{n+1} - \partial_z A_v \partial_z u^{n+1}
+ u^{n+1} - \Delta t \partial_z A_v \partial_z u^{n+1}
- + g \partial_x \eta^{n+1} & = & \frac{1}{\Delta t} u^{n} +
+ + \Delta t g \partial_x \eta^{n+1} & = & u^{n} + \Delta t G_u^{(n+1/2)}
- G_u^{(n+1/2)}
  \\
- \frac{1}{\Delta t} v^{n+1} - \partial_z A_v \partial_z v^{n+1}
+ v^{n+1} - \Delta t \partial_z A_v \partial_z v^{n+1}
- + g \partial_y \eta^{n+1} & = & \frac{1}{\Delta t} v^{n} + G_v^{(n+1/2)}
+ + \Delta t g \partial_y \eta^{n+1} & = & v^{n} + \Delta t G_v^{(n+1/2)}
  \end{eqnarray}
  \section{Pressure method with implicit linear free-surface}
- \label{sect:pressure-method-linear-backward}
+ \label{sec:pressure-method-linear-backward}
+ \begin{rawhtml}
+ <!-- CMIREDIR:pressure_method_linear_backward: -->
+ \end{rawhtml}
  The rigid-lid approximation filters out external gravity waves
  subsequently modifying the dispersion relation of barotropic Rossby
-Line 201 
 The rigid-lid approximation can be easil
+Line 233 
 The rigid-lid approximation can be easil
  of the free-surface equation which can be written:
  \begin{equation}
  \partial_t \eta + \partial_x H \widehat{u} + \partial_y H \widehat{v} = P-E+R
- \label{eq:linear-free-surface=P-E+R}
+ \label{eq:linear-free-surface=P-E}
  \end{equation}
  which differs from the depth integrated continuity equation with
  rigid-lid (\ref{eq:rigid-lid-continuity}) by the time-dependent term
-Line 209 
 and fresh-water source term.
+Line 241 
 and fresh-water source term.
  Equation \ref{eq:discrete-time-cont-rigid-lid} in the rigid-lid
  pressure method is then replaced by the time discretization of
- \ref{eq:linear-free-surface=P-E+R} which is:
+ \ref{eq:linear-free-surface=P-E} which is:
  \begin{equation}
  \eta^{n+1}
  + \Delta t \partial_x H \widehat{u^{n+1}}
  + \Delta t \partial_y H \widehat{v^{n+1}}
  =
  \eta^{n}
- + \Delta t ( P - E + R )
+ + \Delta t ( P - E )
  \label{eq:discrete-time-backward-free-surface}
  \end{equation}
  where the use of flow at time level $n+1$ makes the method implicit
- and backward in time. The is the preferred scheme since it still
+ and backward in time. This is the preferred scheme since it still
  filters the fast unresolved wave motions by damping them. A centered
- scheme, such as Crank-Nicholson, would alias the energy of the fast
+ scheme, such as Crank-Nicholson (see section \ref{sec:freesurf-CrankNick}),
- modes onto slower modes of motion.
+ would alias the energy of the fast modes onto slower modes of motion.
  As for the rigid-lid pressure method, equations
  \ref{eq:discrete-time-u}, \ref{eq:discrete-time-v} and
-Line 231 
 As for the rigid-lid pressure method, eq
+Line 263 
 As for the rigid-lid pressure method, eq
  \begin{eqnarray}
  u^{*} & = & u^{n} + \Delta t G_u^{(n+1/2)} \label{eq:ustar-backward-free-surface} \\
  v^{*} & = & v^{n} + \Delta t G_v^{(n+1/2)} \label{eq:vstar-backward-free-surface} \\
- \eta^* & = & \epsilon_{fs} \left( \eta^{n} +P-E+R \right)- \Delta t
+ \eta^* & = & \epsilon_{fs} \left( \eta^{n} + \Delta t (P-E) \right)
-   \partial_x H \widehat{u^{*}}
+          - \Delta t \left( \partial_x H \widehat{u^{*}}
- + \partial_y H \widehat{v^{*}}
+                          + \partial_y H \widehat{v^{*}} \right)
  \\
    \partial_x g H \partial_x \eta^{n+1}
- + \partial_y g H \partial_y \eta^{n+1}
+ & + & \partial_y g H \partial_y \eta^{n+1}
- - \frac{\epsilon_{fs} \eta^{n+1}}{\Delta t^2}
+  - \frac{\epsilon_{fs} \eta^{n+1}}{\Delta t^2}
- & = &
+  =
  - \frac{\eta^*}{\Delta t^2}
  \label{eq:elliptic-backward-free-surface}
  \\
-Line 254 
 recovered. However, the implicit treatme
+Line 286 
 recovered. However, the implicit treatme
  the flow to be divergent and for the surface pressure/elevation to
  respond on a finite time-scale (as opposed to instantly). To recover
  the rigid-lid formulation, we introduced a switch-like parameter,
- $\epsilon_{fs}$, which selects between the free-surface and rigid-lid;
+ $\epsilon_{fs}$ (\varlink{freesurfFac}{freesurfFac}),
+ which selects between the free-surface and rigid-lid;
  $\epsilon_{fs}=1$ allows the free-surface to evolve; $\epsilon_{fs}=0$
  imposes the rigid-lid. The evolution in time and location of variables
  is exactly as it was for the rigid-lid model so that
-Line 265 
 pressure-method.
+Line 298 
 pressure-method.
  \section{Explicit time-stepping: Adams-Bashforth}
- \label{sect:adams-bashforth}
+ \label{sec:adams-bashforth}
+ \begin{rawhtml}
+ <!-- CMIREDIR:adams_bashforth: -->
+ \end{rawhtml}
  In describing the the pressure method above we deferred describing the
  time discretization of the explicit terms. We have historically used
  the quasi-second order Adams-Bashforth method for all explicit terms
  in both the momentum and tracer equations. This is still the default
  mode of operation but it is now possible to use alternate schemes for
- tracers (see section \ref{sect:tracer-advection}).
+ tracers (see section \ref{sec:tracer-advection}).
  \begin{figure}
  \begin{center} \fbox{ \begin{minipage}{4.5in} \begin{tabbing}
  aaa \= aaa \= aaa \= aaa \= aaa \= aaa \kill
  FORWARD\_STEP \\
  \> THERMODYNAMICS \\
  \>\> CALC\_GT \\
  \>\>\> GAD\_CALC\_RHS \` $G_\theta^n = G_\theta( u, \theta^n )$ \\
- \>\>\> EXTERNAL\_FORCING \` $G_\theta^n = G_\theta^n + {\cal Q}$ \\
+ \>either\>\> EXTERNAL\_FORCING \` $G_\theta^n = G_\theta^n + {\cal Q}$ \\
  \>\>\> ADAMS\_BASHFORTH2 \` $G_\theta^{(n+1/2)}$ (\ref{eq:adams-bashforth2}) \\
+ \>or\>\> EXTERNAL\_FORCING \` $G_\theta^{(n+1/2)} = G_\theta^{(n+1/2)} + {\cal Q}$ \\
  \>\> TIMESTEP\_TRACER \` $\tau^*$ (\ref{eq:taustar}) \\
  \>\> IMPLDIFF \` $\tau^{(n+1)}$ (\ref{eq:tau-n+1-implicit})
  \end{tabbing} \end{minipage} } \end{center}
  \caption{
  Calling tree for the Adams-Bashforth time-stepping of temperature with
- implicit diffusion.}
+ implicit diffusion.
+   (\filelink{THERMODYNAMICS}{model-src-thermodynamics.F},
+    \filelink{ADAMS\_BASHFORTH2}{model-src-adams_bashforth2.F})}
  \label{fig:call-tree-adams-bashforth}
  \end{figure}
-Line 319 
 simpler to include these terms and this
+Line 358 
 simpler to include these terms and this
  and forcing evolves smoothly. Problems can, and do, arise when forcing
  or motions are high frequency and this corresponds to a reduced
  stability compared to a simple forward time-stepping of such terms.
+ The model offers the possibility to leave the tracer and momentum
+ forcing terms and the dissipation terms outside the
+ Adams-Bashforth extrapolation, by turning off the logical flags
+ \varlink{forcing\_In\_AB}{forcing_In_AB}
+ (parameter file {\em data}, namelist {\em PARM01}, default value = True).
+ (\varlink{tracForcingOutAB}{tracForcingOutAB}, default=0,
+ \varlink{momForcingOutAB}{momForcingOutAB}, default=0)
+ and \varlink{momDissip\_In\_AB}{momDissip_In_AB}
+ (parameter file {\em data}, namelist {\em PARM01}, default value = True).
+ respectively.
  A stability analysis for an oscillation equation should be given at this point.
  \marginpar{AJA needs to find his notes on this...}
-Line 326 
 A stability analysis for an oscillation
+Line 375 
 A stability analysis for an oscillation
  A stability analysis for a relaxation equation should be given at this point.
  \marginpar{...and for this too.}
+ \begin{figure}
+ \begin{center}
+ \resizebox{5.5in}{!}{\includegraphics{s_algorithm/figs/oscil+damp_AB2.eps}}
+ \end{center}
+ \caption{
+ Oscillatory and damping response of
+ quasi-second order Adams-Bashforth scheme for different values
+ of the $\epsilon_{AB}$ parameter (0., 0.1, 0.25, from top to bottom)
+ The analytical solution (in black), the physical mode (in blue)
+ and the numerical mode (in red) are represented with a CFL
+ step of 0.1.
+ The left column represents the oscillatory response
+ on the complex plane for CFL ranging from 0.1 up to 0.9.
+ The right column represents the damping response amplitude
+ (y-axis) function of the CFL (x-axis).
+ }
+ \label{fig:adams-bashforth-respons}
+ \end{figure}
  \section{Implicit time-stepping: backward method}
+ \label{sec:implicit-backward-stepping}
+ \begin{rawhtml}
+ <!-- CMIREDIR:implicit_time-stepping_backward: -->
+ \end{rawhtml}
  Vertical diffusion and viscosity can be treated implicitly in time
- using the backward method which is an intrinsic scheme. For tracers,
+ using the backward method which is an intrinsic scheme.
+ Recently, the option to treat the vertical advection
+ implicitly has been added, but not yet tested; therefore,
+ the description hereafter is limited to diffusion and viscosity.
+ For tracers,
  the time discretized equation is:
  \begin{equation}
  \tau^{n+1} - \Delta t \partial_r \kappa_v \partial_r \tau^{n+1} =
-Line 348 
 using the Adams-Bashforth method as desc
+Line 425 
 using the Adams-Bashforth method as desc
  \end{eqnarray}
  where ${\cal L}_\tau^{-1}$ is the inverse of the operator
  \begin{equation}
- {\cal L} = \left[ 1 + \Delta t \partial_r \kappa_v \partial_r \right]
+ {\cal L}_\tau = \left[ 1 + \Delta t \partial_r \kappa_v \partial_r \right]
  \end{equation}
  Equation \ref{eq:taustar-implicit} looks exactly as \ref{eq:taustar}
  while \ref{eq:tau-n+1-implicit} involves an operator or matrix
-Line 361 
 Fig.~\ref{fig:call-tree-adams-bashforth}
+Line 438 
 Fig.~\ref{fig:call-tree-adams-bashforth}
  stepping forward a tracer variable such as temperature.
  In order to fit within the pressure method, the implicit viscosity
- must not alter the barotropic flow. In other words, it can on ly
+ must not alter the barotropic flow. In other words, it can only
  redistribute momentum in the vertical. The upshot of this is that
  although vertical viscosity may be backward implicit and
  unconditionally stable, no-slip boundary conditions may not be made
  implicit and are thus cast as a an explicit drag term.
  \section{Synchronous time-stepping: variables co-located in time}
- \label{sect:adams-bashforth-sync}
+ \label{sec:adams-bashforth-sync}
+ \begin{rawhtml}
+ <!-- CMIREDIR:adams_bashforth_sync: -->
+ \end{rawhtml}
  \begin{figure}
  \begin{center}
- \resizebox{5.0in}{!}{\includegraphics{part2/adams-bashforth-sync.eps}}
+ \resizebox{5.0in}{!}{\includegraphics{s_algorithm/figs/adams-bashforth-sync.eps}}
  \end{center}
  \caption{
  A schematic of the explicit Adams-Bashforth and implicit time-stepping
-Line 389 
 is solved to yield the state variables a
+Line 469 
 is solved to yield the state variables a
  \end{figure}
  \begin{figure}
- \begin{center} \fbox{ \begin{minipage}{4.5in} \begin{tabbing}
+ \begin{center} \fbox{ \begin{minipage}{4.7in} \begin{tabbing}
  aaa \= aaa \= aaa \= aaa \= aaa \= aaa \kill
  FORWARD\_STEP \\
+ \>\> EXTERNAL\_FIELDS\_LOAD\\
+ \>\> DO\_ATMOSPHERIC\_PHYS \\
+ \>\> DO\_OCEANIC\_PHYS \\
  \> THERMODYNAMICS \\
  \>\> CALC\_GT \\
  \>\>\> GAD\_CALC\_RHS \` $G_\theta^n = G_\theta( u, \theta^n )$ (\ref{eq:Gt-n-sync})\\
  \>\>\> EXTERNAL\_FORCING \` $G_\theta^n = G_\theta^n + {\cal Q}$ \\
  \>\>\> ADAMS\_BASHFORTH2 \` $G_\theta^{(n+1/2)}$ (\ref{eq:Gt-n+5-sync}) \\
- \>\> TIMESTEP\_TRACER \` $\tau^*$ (\ref{eq:tstar-sync}) \\
+ \>\> TIMESTEP\_TRACER \` $\theta^*$ (\ref{eq:tstar-sync}) \\
- \>\> IMPLDIFF \` $\tau^{(n+1)}$ (\ref{eq:t-n+1-sync}) \\
+ \>\> IMPLDIFF \` $\theta^{(n+1)}$ (\ref{eq:t-n+1-sync}) \\
  \> DYNAMICS \\
  \>\> CALC\_PHI\_HYD \` $\phi_{hyd}^n$ (\ref{eq:phi-hyd-sync}) \\
  \>\> MOM\_FLUXFORM or MOM\_VECINV \` $G_{\vec{\bf v}}^n$ (\ref{eq:Gv-n-sync})\\
  \>\> TIMESTEP \` $\vec{\bf v}^*$ (\ref{eq:Gv-n+5-sync}, \ref{eq:vstar-sync}) \\
  \>\> IMPLDIFF \` $\vec{\bf v}^{**}$ (\ref{eq:vstarstar-sync}) \\
+ \> UPDATE\_R\_STAR or UPDATE\_SURF\_DR \` (NonLin-FS only)\\
  \> SOLVE\_FOR\_PRESSURE \\
  \>\> CALC\_DIV\_GHAT \` $\eta^*$ (\ref{eq:nstar-sync}) \\
  \>\> CG2D \` $\eta^{n+1}$ (\ref{eq:elliptic-sync}) \\
- \> THE\_CORRECTION\_STEP  \\
+ \> MOMENTUM\_CORRECTION\_STEP  \\
  \>\> CALC\_GRAD\_PHI\_SURF \` $\nabla \eta^{n+1}$ \\
- \>\> CORRECTION\_STEP \` $u^{n+1}$,$v^{n+1}$ (\ref{eq:v-n+1-sync})
+ \>\> CORRECTION\_STEP \` $u^{n+1}$,$v^{n+1}$ (\ref{eq:v-n+1-sync})\\
+ \> TRACERS\_CORRECTION\_STEP  \\
+ \>\> CYCLE\_TRACER \` $\theta^{n+1}$ \\
+ \>\> FILTER \` Shapiro Filter, Zonal Filter (FFT) \\
+ \>\> CONVECTIVE\_ADJUSTMENT \` \\
  \end{tabbing} \end{minipage} } \end{center}
  \caption{
  Calling tree for the overall synchronous algorithm using
- Adams-Bashforth time-stepping.}
+ Adams-Bashforth time-stepping.
+ The place where the model geometry
+ ({\bf hFac} factors) is updated is added here but is only relevant
+ for the non-linear free-surface algorithm.
+ For completeness, the external forcing,
+ ocean and atmospheric physics have been added, although they are mainly
+ optional}
  \label{fig:call-tree-adams-bashforth-sync}
  \end{figure}
-Line 442 
 G_{\theta,S}^{(n+1/2)} & = & (3/2+\epsil
+Line 536 
 G_{\theta,S}^{(n+1/2)} & = & (3/2+\epsil
  \label{eq:vstar-sync} \\
  \vec{\bf v}^{**} & = & {\cal L}_{\vec{\bf v}}^{-1} ( \vec{\bf v}^* )
  \label{eq:vstarstar-sync} \\
- \eta^* & = & \epsilon_{fs} \left( \eta^{n} +P-E+R \right)- \Delta t
+ \eta^* & = & \epsilon_{fs} \left( \eta^{n} + \Delta t (P-E) \right)- \Delta t
    \nabla \cdot H \widehat{ \vec{\bf v}^{**} }
  \label{eq:nstar-sync} \\
- \nabla \cdot g H \nabla \eta^{n+1} - \frac{\epsilon_{fs} \eta^{n+1}}{\Delta t^2}
+ \nabla \cdot g H \nabla \eta^{n+1} & - & \frac{\epsilon_{fs} \eta^{n+1}}{\Delta t^2}
- & = & - \frac{\eta^*}{\Delta t^2}
+ ~ = ~ - \frac{\eta^*}{\Delta t^2}
  \label{eq:elliptic-sync} \\
- \vec{\bf v}^{n+1} & = & \vec{\bf v}^{*} - \Delta t g \nabla \eta^{n+1}
+ \vec{\bf v}^{n+1} & = & \vec{\bf v}^{**} - \Delta t g \nabla \eta^{n+1}
  \label{eq:v-n+1-sync}
  \end{eqnarray}
  Fig.~\ref{fig:adams-bashforth-sync} illustrates the location of
-Line 465 
 accelerations, stepping forward and solv
+Line 559 
 accelerations, stepping forward and solv
  surface pressure gradient terms, corresponding to equations
  \ref{eq:Gv-n-sync} to \ref{eq:v-n+1-sync}.
  These operations are carried out in subroutines {\em DYNAMCIS}, {\em
- SOLVE\_FOR\_PRESSURE} and {\em THE\_CORRECTION\_STEP}. This, then,
+ SOLVE\_FOR\_PRESSURE} and {\em MOMENTUM\_CORRECTION\_STEP}. This, then,
  represents an entire algorithm for stepping forward the model one
  time-step. The corresponding calling tree is given in
  \ref{fig:call-tree-adams-bashforth-sync}.
  \section{Staggered baroclinic time-stepping}
- \label{sect:adams-bashforth-staggered}
+ \label{sec:adams-bashforth-staggered}
+ \begin{rawhtml}
+ <!-- CMIREDIR:adams_bashforth_staggered: -->
+ \end{rawhtml}
  \begin{figure}
  \begin{center}
- \resizebox{5.5in}{!}{\includegraphics{part2/adams-bashforth-staggered.eps}}
+ \resizebox{5.5in}{!}{\includegraphics{s_algorithm/figs/adams-bashforth-staggered.eps}}
  \end{center}
  \caption{
  A schematic of the explicit Adams-Bashforth and implicit time-stepping
  phases of the algorithm but with staggering in time of thermodynamic
- variables with the flow. Explicit thermodynamics tendencies are
+ variables with the flow.
- evaluated at time level $n-1/2$ as a function of the thermodynamics
+ Explicit momentum tendencies are evaluated at time level $n-1/2$ as a
- state at that time level $n$ and flow at time $n$ (dotted arrow). The
+ function of the flow field at that time level $n-1/2$.
- explicit tendency from the previous time level, $n-3/2$, is used to
+ The explicit tendency from the previous time level, $n-3/2$, is used to
- extrapolate tendencies to $n$ (dashed arrow). This extrapolated
+ extrapolate tendencies to $n$ (dashed arrow).
- tendency allows thermo-dynamics variables to be stably integrated
+ The hydrostatic pressure/geo-potential $\phi_{hyd}$ is evaluated directly
- forward-in-time to render an estimate ($*$-variables) at the $n+1/2$
+ at time level $n$ (vertical arrows) and used with the extrapolated tendencies
- time level (solid arc-arrow). The implicit-in-time operator ${\cal
+ to step forward the flow variables from $n-1/2$ to $n+1/2$ (solid arc-arrow).
- L_{\theta,S}}$ is solved to yield the thermodynamic variables at time
+ The implicit-in-time operator ${\cal L}_{\bf u,v}$ (vertical arrows) is
- level $n+1/2$. These are then used to calculate the hydrostatic
+ then applied to the previous estimation of the the flow field ($*$-variables)
- pressure/geo-potential, $\phi_{hyd}$ (vertical arrows). The
+ and yields to the two velocity components $u,v$ at time level $n+1/2$.
- hydrostatic pressure gradient is evaluated directly an time level
+ These are then used to calculate the advection term (dashed arc-arrow)
- $n+1/2$ in stepping forward the flow variables from $n$ to $n+1$
+ of the thermo-dynamics tendencies at time step $n$.
- (solid arc-arrow). }
+ The extrapolated thermodynamics tendency, from time level $n-1$ and $n$
+ to $n+1/2$, allows thermodynamic variables to be stably integrated
+ forward-in-time (solid arc-arrow) up to time level $n+1$.
+ }
  \label{fig:adams-bashforth-staggered}
  \end{figure}
-Line 503 
 circumstance, it is more efficient to st
+Line 603 
 circumstance, it is more efficient to st
  thermodynamic variables with the flow
  variables. Fig.~\ref{fig:adams-bashforth-staggered} illustrates the
  staggering and algorithm. The key difference between this and
- Fig.~\ref{fig:adams-bashforth-sync} is that the new thermodynamics
+ Fig.~\ref{fig:adams-bashforth-sync} is that the thermodynamic variables
- fields are used to compute the hydrostatic pressure at time level
+ are solved after the dynamics, using the recently updated flow field.
- $n+1/2$. The essentially allows the gravity wave terms to leap-frog in
+ This essentially allows the gravity wave terms to leap-frog in
  time giving second order accuracy and more stability.
- The essential change in the staggered algorithm is the calculation of
+ The essential change in the staggered algorithm is that the
- hydrostatic pressure which, in the context of the synchronous
+ thermodynamics solver is delayed from half a time step,
- algorithm involves replacing equation \ref{eq:phi-hyd-sync} with
+ allowing the use of the most recent velocities to compute
- \begin{displaymath}
+ the advection terms. Once the thermodynamics fields are
- \phi_{hyd}^n = \int b(\theta^{n+1},S^{n+1}) dr
+ updated, the hydrostatic pressure is computed
- \end{displaymath}
+ to step forward the dynamics.
- but the pressure gradient must also be taken out of the
+ Note that the pressure gradient must also be taken out of the
  Adams-Bashforth extrapolation. Also, retaining the integer time-levels,
  $n$ and $n+1$, does not give a user the sense of where variables are
  located in time.  Instead, we re-write the entire algorithm,
  \ref{eq:Gt-n-sync} to \ref{eq:v-n+1-sync}, annotating the
  position in time of variables appropriately:
  \begin{eqnarray}
- G_{\theta,S}^{n-1/2} & = & G_{\theta,S} ( u^n, \theta^{n-1/2}, S^{n-1/2} )
+ \phi^{n}_{hyd} & = & \int b(\theta^{n},S^{n}) dr
- \label{eq:Gt-n-staggered} \\
- G_{\theta,S}^{(n)} & = & (3/2+\epsilon_{AB}) G_{\theta,S}^{n-1/2}-(1/2+\epsilon_{AB}) G_{\theta,S}^{n-3/2}
- \label{eq:Gt-n+5-staggered} \\
- (\theta^*,S^*) & = & (\theta^{n},S^{n}) + \Delta t G_{\theta,S}^{(n)}
- \label{eq:tstar-staggered} \\
- (\theta^{n+1/2},S^{n+1/2}) & = & {\cal L}^{-1}_{\theta,S} (\theta^*,S^*)
- \label{eq:t-n+1-staggered} \\
- \phi^{n+1/2}_{hyd} & = & \int b(\theta^{n+1/2},S^{n+1/2}) dr
  \label{eq:phi-hyd-staggered} \\
- \vec{\bf G}_{\vec{\bf v}}^{n} & = & \vec{\bf G}_{\vec{\bf v}} ( \vec{\bf v}^n )
+ \vec{\bf G}_{\vec{\bf v}}^{n-1/2} & = & \vec{\bf G}_{\vec{\bf v}} ( \vec{\bf v}^{n-1/2} )
  \label{eq:Gv-n-staggered} \\
- \vec{\bf G}_{\vec{\bf v}}^{(n+1/2)} & = & (3/2 + \epsilon_{AB} ) \vec{\bf G}_{\vec{\bf v}}^{n} - (1/2 + \epsilon_{AB} ) \vec{\bf G}_{\vec{\bf v}}^{n-1}
+ \vec{\bf G}_{\vec{\bf v}}^{(n)} & = & (3/2 + \epsilon_{AB} ) \vec{\bf G}_{\vec{\bf v}}^{n-1/2} - (1/2 + \epsilon_{AB} ) \vec{\bf G}_{\vec{\bf v}}^{n-3/2}
  \label{eq:Gv-n+5-staggered} \\
- \vec{\bf v}^{*} & = & \vec{\bf v}^{n} + \Delta t \left( \vec{\bf G}_{\vec{\bf v}}^{(n+1/2)} - \nabla \phi_{hyd}^{n+1/2} \right)
+ \vec{\bf v}^{*} & = & \vec{\bf v}^{n-1/2} + \Delta t \left( \vec{\bf G}_{\vec{\bf v}}^{(n)} - \nabla \phi_{hyd}^{n} \right)
  \label{eq:vstar-staggered} \\
  \vec{\bf v}^{**} & = & {\cal L}_{\vec{\bf v}}^{-1} ( \vec{\bf v}^* )
  \label{eq:vstarstar-staggered} \\
- \eta^* & = & \epsilon_{fs} \left( \eta^{n} +P-E+R \right)- \Delta t
+ \eta^* & = & \epsilon_{fs} \left( \eta^{n-1/2} + \Delta t (P-E)^n \right)- \Delta t
    \nabla \cdot H \widehat{ \vec{\bf v}^{**} }
  \label{eq:nstar-staggered} \\
- \nabla \cdot g H \nabla \eta^{n+1} - \frac{\epsilon_{fs} \eta^{n+1}}{\Delta t^2}
+ \nabla \cdot g H \nabla \eta^{n+1/2} & - & \frac{\epsilon_{fs} \eta^{n+1/2}}{\Delta t^2}
- & = & - \frac{\eta^*}{\Delta t^2}
+ ~ = ~ - \frac{\eta^*}{\Delta t^2}
  \label{eq:elliptic-staggered} \\
- \vec{\bf v}^{n+1} & = & \vec{\bf v}^{*} - \Delta t g \nabla \eta^{n+1}
+ \vec{\bf v}^{n+1/2} & = & \vec{\bf v}^{**} - \Delta t g \nabla \eta^{n+1/2}
- \label{eq:v-n+1-staggered}
+ \label{eq:v-n+1-staggered} \\
+ G_{\theta,S}^{n} & = & G_{\theta,S} ( u^{n+1/2}, \theta^{n}, S^{n} )
+ \label{eq:Gt-n-staggered} \\
+ G_{\theta,S}^{(n+1/2)} & = & (3/2+\epsilon_{AB}) G_{\theta,S}^{n}-(1/2+\epsilon_{AB}) G_{\theta,S}^{n-1}
+ \label{eq:Gt-n+5-staggered} \\
+ (\theta^*,S^*) & = & (\theta^{n},S^{n}) + \Delta t G_{\theta,S}^{(n+1/2)}
+ \label{eq:tstar-staggered} \\
+ (\theta^{n+1},S^{n+1}) & = & {\cal L}^{-1}_{\theta,S} (\theta^*,S^*)
+ \label{eq:t-n+1-staggered}
  \end{eqnarray}
- The calling sequence is unchanged from
+ The corresponding calling tree is given in
- Fig.~\ref{fig:call-tree-adams-bashforth-sync}. The staggered algorithm
+ \ref{fig:call-tree-adams-bashforth-staggered}.
- is activated with the run-time flag {\bf staggerTimeStep=.TRUE.} in
+ The staggered algorithm is activated with the run-time flag
- {\em PARM01} of {\em data}.
+ {\bf staggerTimeStep}{\em=.TRUE.} in parameter file {\em data},
+ namelist {\em PARM01}.
+ \begin{figure}
+ \begin{center} \fbox{ \begin{minipage}{4.7in} \begin{tabbing}
+ aaa \= aaa \= aaa \= aaa \= aaa \= aaa \kill
+ FORWARD\_STEP \\
+ \>\> EXTERNAL\_FIELDS\_LOAD\\
+ \>\> DO\_ATMOSPHERIC\_PHYS \\
+ \>\> DO\_OCEANIC\_PHYS \\
+ \> DYNAMICS \\
+ \>\> CALC\_PHI\_HYD \` $\phi_{hyd}^n$ (\ref{eq:phi-hyd-staggered}) \\
+ \>\> MOM\_FLUXFORM or MOM\_VECINV \` $G_{\vec{\bf v}}^{n-1/2}$
+     (\ref{eq:Gv-n-staggered})\\
+ \>\> TIMESTEP \` $\vec{\bf v}^*$ (\ref{eq:Gv-n+5-staggered},
+                                   \ref{eq:vstar-staggered}) \\
+ \>\> IMPLDIFF \` $\vec{\bf v}^{**}$ (\ref{eq:vstarstar-staggered}) \\
+ \> UPDATE\_R\_STAR or UPDATE\_SURF\_DR \` (NonLin-FS only)\\
+ \> SOLVE\_FOR\_PRESSURE \\
+ \>\> CALC\_DIV\_GHAT \` $\eta^*$ (\ref{eq:nstar-staggered}) \\
+ \>\> CG2D \` $\eta^{n+1/2}$ (\ref{eq:elliptic-staggered}) \\
+ \> MOMENTUM\_CORRECTION\_STEP  \\
+ \>\> CALC\_GRAD\_PHI\_SURF \` $\nabla \eta^{n+1/2}$ \\
+ \>\> CORRECTION\_STEP \` $u^{n+1/2}$,$v^{n+1/2}$ (\ref{eq:v-n+1-staggered})\\
+ \> THERMODYNAMICS \\
+ \>\> CALC\_GT \\
+ \>\>\> GAD\_CALC\_RHS \` $G_\theta^n = G_\theta( u, \theta^n )$
+      (\ref{eq:Gt-n-staggered})\\
+ \>\>\> EXTERNAL\_FORCING \` $G_\theta^n = G_\theta^n + {\cal Q}$ \\
+ \>\>\> ADAMS\_BASHFORTH2 \` $G_\theta^{(n+1/2)}$ (\ref{eq:Gt-n+5-staggered}) \\
+ \>\> TIMESTEP\_TRACER \` $\theta^*$ (\ref{eq:tstar-staggered}) \\
+ \>\> IMPLDIFF \` $\theta^{(n+1)}$ (\ref{eq:t-n+1-staggered}) \\
+ \> TRACERS\_CORRECTION\_STEP  \\
+ \>\> CYCLE\_TRACER \` $\theta^{n+1}$ \\
+ \>\> FILTER \` Shapiro Filter, Zonal Filter (FFT) \\
+ \>\> CONVECTIVE\_ADJUSTMENT \` \\
+ \end{tabbing} \end{minipage} } \end{center}
+ \caption{
+ Calling tree for the overall staggered algorithm using
+ Adams-Bashforth time-stepping.
+ The place where the model geometry
+ ({\bf hFac} factors) is updated is added here but is only relevant
+ for the non-linear free-surface algorithm.
+ }
+ \label{fig:call-tree-adams-bashforth-staggered}
+ \end{figure}
  The only difficulty with this approach is apparent in equation
- $\ref{eq:Gt-n-staggered}$ and illustrated by the dotted arrow
+ \ref{eq:Gt-n-staggered} and illustrated by the dotted arrow
- connecting $u,v^n$ with $G_\theta^{n-1/2}$. The flow used to advect
+ connecting $u,v^{n+1/2}$ with $G_\theta^{n}$. The flow used to advect
  tracers around is not naturally located in time. This could be avoided
  by applying the Adams-Bashforth extrapolation to the tracer field
- itself and advection that around but this is not yet available. We're
+ itself and advecting that around but this approach is not yet
- not aware of any detrimental effect of this feature. The difficulty
+ available. We're not aware of any detrimental effect of this
- lies mainly in interpretation of what time-level variables and terms
+ feature. The difficulty lies mainly in interpretation of what
- correspond to.
+ time-level variables and terms correspond to.
  \section{Non-hydrostatic formulation}
- \label{sect:non-hydrostatic}
+ \label{sec:non-hydrostatic}
+ \begin{rawhtml}
- [to be written...]
+ <!-- CMIREDIR:non-hydrostatic_formulation: -->
+ \end{rawhtml}
+ The non-hydrostatic formulation re-introduces the full vertical
+ momentum equation and requires the solution of a 3-D elliptic
+ equations for non-hydrostatic pressure perturbation. We still
+ integrate vertically for the hydrostatic pressure and solve a 2-D
+ elliptic equation for the surface pressure/elevation for this reduces
+ the amount of work needed to solve for the non-hydrostatic pressure.
+ The momentum equations are discretized in time as follows:
+ \begin{eqnarray}
+ \frac{1}{\Delta t} u^{n+1} + g \partial_x \eta^{n+1} + \partial_x \phi_{nh}^{n+1}
+ & = & \frac{1}{\Delta t} u^{n} + G_u^{(n+1/2)} \label{eq:discrete-time-u-nh} \\
+ \frac{1}{\Delta t} v^{n+1} + g \partial_y \eta^{n+1} + \partial_y \phi_{nh}^{n+1}
+ & = & \frac{1}{\Delta t} v^{n} + G_v^{(n+1/2)} \label{eq:discrete-time-v-nh} \\
+ \frac{1}{\Delta t} w^{n+1} + \partial_r \phi_{nh}^{n+1}
+ & = & \frac{1}{\Delta t} w^{n} + G_w^{(n+1/2)} \label{eq:discrete-time-w-nh}
+ \end{eqnarray}
+ which must satisfy the discrete-in-time depth integrated continuity,
+ equation~\ref{eq:discrete-time-backward-free-surface} and the local continuity equation
+ \begin{equation}
+ \partial_x u^{n+1} + \partial_y v^{n+1} + \partial_r w^{n+1} = 0
+ \label{eq:non-divergence-nh}
+ \end{equation}
+ As before, the explicit predictions for momentum are consolidated as:
+ \begin{eqnarray*}
+ u^* & = & u^n + \Delta t G_u^{(n+1/2)} \\
+ v^* & = & v^n + \Delta t G_v^{(n+1/2)} \\
+ w^* & = & w^n + \Delta t G_w^{(n+1/2)}
+ \end{eqnarray*}
+ but this time we introduce an intermediate step by splitting the
+ tendancy of the flow as follows:
+ \begin{eqnarray}
+ u^{n+1} = u^{**} - \Delta t \partial_x \phi_{nh}^{n+1}
+ & &
+ u^{**} = u^{*} - \Delta t g \partial_x \eta^{n+1} \\
+ v^{n+1} = v^{**} - \Delta t \partial_y \phi_{nh}^{n+1}
+ & &
+ v^{**} = v^{*} - \Delta t g \partial_y \eta^{n+1}
+ \end{eqnarray}
+ Substituting into the depth integrated continuity
+ (equation~\ref{eq:discrete-time-backward-free-surface}) gives
+ \begin{equation}
+ \partial_x H \partial_x \left( g \eta^{n+1} + \widehat{\phi}_{nh}^{n+1} \right)
+ +
+ \partial_y H \partial_y \left( g \eta^{n+1} + \widehat{\phi}_{nh}^{n+1} \right)
+  - \frac{\epsilon_{fs}\eta^{n+1}}{\Delta t^2}
+ = - \frac{\eta^*}{\Delta t^2}
+ \end{equation}
+ which is approximated by equation
+ \ref{eq:elliptic-backward-free-surface} on the basis that i)
+ $\phi_{nh}^{n+1}$ is not yet known and ii) $\nabla \widehat{\phi}_{nh}
+ << g \nabla \eta$. If \ref{eq:elliptic-backward-free-surface} is
+ solved accurately then the implication is that $\widehat{\phi}_{nh}
+ \approx 0$ so that the non-hydrostatic pressure field does not drive
+ barotropic motion.
+ The flow must satisfy non-divergence
+ (equation~\ref{eq:non-divergence-nh}) locally, as well as depth
+ integrated, and this constraint is used to form a 3-D elliptic
+ equations for $\phi_{nh}^{n+1}$:
+ \begin{equation}
+ \partial_{xx} \phi_{nh}^{n+1} + \partial_{yy} \phi_{nh}^{n+1} +
+ \partial_{rr} \phi_{nh}^{n+1} = \left(
+ \partial_x u^{**} + \partial_y v^{**} + \partial_r w^{*}
+ \right) / \Delta t
+ \end{equation}
+ The entire algorithm can be summarized as the sequential solution of
+ the following equations:
+ \begin{eqnarray}
+ u^{*} & = & u^{n} + \Delta t G_u^{(n+1/2)} \label{eq:ustar-nh} \\
+ v^{*} & = & v^{n} + \Delta t G_v^{(n+1/2)} \label{eq:vstar-nh} \\
+ w^{*} & = & w^{n} + \Delta t G_w^{(n+1/2)} \label{eq:wstar-nh} \\
+ \eta^* ~ = ~ \epsilon_{fs} \left( \eta^{n} + \Delta t (P-E) \right)
+ & - & \Delta t \left( \partial_x H \widehat{u^{*}}
+                     + \partial_y H \widehat{v^{*}} \right)
+ \\
+   \partial_x g H \partial_x \eta^{n+1}
+ + \partial_y g H \partial_y \eta^{n+1}
+ & - & \frac{\epsilon_{fs} \eta^{n+1}}{\Delta t^2}
+ ~ = ~
+ - \frac{\eta^*}{\Delta t^2}
+ \label{eq:elliptic-nh}
+ \\
+ u^{**} & = & u^{*} - \Delta t g \partial_x \eta^{n+1} \label{eq:unx-nh}\\
+ v^{**} & = & v^{*} - \Delta t g \partial_y \eta^{n+1} \label{eq:vnx-nh}\\
+ \partial_{xx} \phi_{nh}^{n+1} + \partial_{yy} \phi_{nh}^{n+1} +
+ \partial_{rr} \phi_{nh}^{n+1} & = & \left(
+ \partial_x u^{**} + \partial_y v^{**} + \partial_r w^{*}
+ \right) / \Delta t  \label{eq:phi-nh}\\
+ u^{n+1} & = & u^{**} - \Delta t \partial_x \phi_{nh}^{n+1} \label{eq:un+1-nh}\\
+ v^{n+1} & = & v^{**} - \Delta t \partial_y \phi_{nh}^{n+1} \label{eq:vn+1-nh}\\
+ \partial_r w^{n+1} & = & - \partial_x u^{n+1} - \partial_y v^{n+1}
+ \end{eqnarray}
+ where the last equation is solved by vertically integrating for
+ $w^{n+1}$.
  \section{Variants on the Free Surface}
+ \label{sec:free-surface}
  We now describe the various formulations of the free-surface that
  include non-linear forms, implicit in time using Crank-Nicholson,
-Line 592 
 where
+Line 832 
 where
  \begin{eqnarray}
  {\eta}^* = \epsilon_{fs} \: {\eta}^{n} -
  \Delta t {\bf \nabla}_h \cdot \int_{R_{fixed}}^{R_o} \vec{\bf v}^* dr
- \: + \: \epsilon_{fw} \Delta_t (P-E)^{n}
+ \: + \: \epsilon_{fw} \Delta t (P-E)^{n}
  \label{eq-solve2D_rhs}
  \end{eqnarray}
  \fbox{ \begin{minipage}{4.75in}
  {\em S/R SOLVE\_FOR\_PRESSURE} ({\em solve\_for\_pressure.F})
- $u^*$: {\bf GuNm1} ({\em DYNVARS.h})
+ $u^*$: {\bf gU} ({\em DYNVARS.h})
- $v^*$: {\bf GvNm1} ({\em DYNVARS.h})
+ $v^*$: {\bf gV} ({\em DYNVARS.h})
  $\eta^*$: {\bf cg2d\_b} (\em SOLVE\_FOR\_PRESSURE.h)
-Line 611 
 $\eta^{n+1}$: {\bf etaN} (\em DYNVARS.h)
+Line 851 
 $\eta^{n+1}$: {\bf etaN} (\em DYNVARS.h)
  Once ${\eta}^{n+1}$ has been found, substituting into
- \ref{eq-tDsC-Hmom} yields $\vec{\bf v}^{n+1}$ if the model is
+ \ref{eq:discrete-time-u}, \ref{eq:discrete-time-v} yields $\vec{\bf v}^{n+1}$
- hydrostatic ($\epsilon_{nh}=0$):
+ if the model is hydrostatic ($\epsilon_{nh}=0$):
  $$
  \vec{\bf v}^{n+1} = \vec{\bf v}^{*}
  - \Delta t {\bf \nabla}_h b_s {\eta}^{n+1}
-Line 621 
 $$
+Line 861 
 $$
  This is known as the correction step. However, when the model is
  non-hydrostatic ($\epsilon_{nh}=1$) we need an additional step and an
  additional equation for $\phi'_{nh}$. This is obtained by substituting
- \ref{eq-tDsC-Hmom} and \ref{eq-tDsC-Vmom} into
+ \ref{eq:discrete-time-u-nh}, \ref{eq:discrete-time-v-nh} and \ref{eq:discrete-time-w-nh}
- \ref{eq-tDsC-cont}:
+ into continuity:
  \begin{equation}
  \left[ {\bf \nabla}_h^2 + \partial_{rr} \right] {\phi'_{nh}}^{n+1}
  = \frac{1}{\Delta t} \left(
-Line 634 
 where
+Line 874 
 where
  \end{displaymath}
  Note that $\eta^{n+1}$ is also used to update the second RHS term
  $\partial_r \dot{r}^* $ since
  the vertical velocity at the surface ($\dot{r}_{surf}$)
  is evaluated as $(\eta^{n+1} - \eta^n) / \Delta t$.
  Finally, the horizontal velocities at the new time level are found by:
-Line 653 
 without any consequence on the solution.
+Line 893 
 without any consequence on the solution.
  $\eta^{n+1}$: {\bf etaN} (\em DYNVARS.h)
- $\phi_{nh}^{n+1}$: {\bf phi\_nh} (\em DYNVARS.h)
+ $\phi_{nh}^{n+1}$: {\bf phi\_nh} (\em NH\_VARS.h)
- $u^*$: {\bf GuNm1} ({\em DYNVARS.h})
+ $u^*$: {\bf gU} ({\em DYNVARS.h})
- $v^*$: {\bf GvNm1} ({\em DYNVARS.h})
+ $v^*$: {\bf gV} ({\em DYNVARS.h})
  $u^{n+1}$: {\bf uVel} ({\em DYNVARS.h})
-Line 684 
 at the same point in the code.
+Line 924 
 at the same point in the code.
- \subsection{Crank-Nickelson barotropic time stepping}
+ \subsection{Crank-Nicolson barotropic time stepping}
+ \label{sec:freesurf-CrankNick}
  The full implicit time stepping described previously is
  unconditionally stable but damps the fast gravity waves, resulting in
-Line 695 
 for the barotropic flow divergence ($\ga
+Line 936 
 for the barotropic flow divergence ($\ga
  \\
  For instance, $\beta=\gamma=1$ is the previous fully implicit scheme;
  $\beta=\gamma=1/2$ is the non damping (energy conserving), unconditionally
- stable, Crank-Nickelson scheme; $(\beta,\gamma)=(1,0)$ or $=(0,1)$
+ stable, Crank-Nicolson scheme; $(\beta,\gamma)=(1,0)$ or $=(0,1)$
  corresponds to the forward - backward scheme that conserves energy but is
  only stable for small time steps.\\
  In the code, $\beta,\gamma$ are defined as parameters, respectively
- {\it implicSurfPress}, {\it implicDiv2DFlow}. They are read from
+ {\bf implicSurfPress}, {\bf implicDiv2DFlow}. They are read from
- the main data file "{\it data}" and are set by default to 1,1.
+ the main parameter file "{\em data}" (namelist {\em PARM01})
+ and are set by default to 1,1.
- Equations \ref{eq-tDsC-Hmom} and \ref{eq-tDsC-eta} are modified as follows:
+ Equations \ref{eq:ustar-backward-free-surface} --
- $$
+ \ref{eq:vn+1-backward-free-surface} are modified as follows:
+ \begin{eqnarray*}
  \frac{ \vec{\bf v}^{n+1} }{ \Delta t }
  + {\bf \nabla}_h b_s [ \beta {\eta}^{n+1} + (1-\beta) {\eta}^{n} ]
  + \epsilon_{nh} {\bf \nabla}_h {\phi'_{nh}}^{n+1}
-  = \frac{ \vec{\bf v}^* }{ \Delta t }
+  = \frac{ \vec{\bf v}^{n} }{ \Delta t }
- $$
+  + \vec{\bf G}_{\vec{\bf v}} ^{(n+1/2)}
- $$
+  + {\bf \nabla}_h {\phi'_{hyd}}^{(n+1/2)}
+ \end{eqnarray*}
+ \begin{eqnarray}
  \epsilon_{fs} \frac{ {\eta}^{n+1} - {\eta}^{n} }{ \Delta t}
  + {\bf \nabla}_h \cdot \int_{R_{fixed}}^{R_o}
  [ \gamma \vec{\bf v}^{n+1} + (1-\gamma) \vec{\bf v}^{n}] dr
  = \epsilon_{fw} (P-E)
- $$
+ \label{eq:eta-n+1-CrankNick}
- where:
+ \end{eqnarray}
+ We set
  \begin{eqnarray*}
  \vec{\bf v}^* & = &
  \vec{\bf v} ^{n} + \Delta t \vec{\bf G}_{\vec{\bf v}} ^{(n+1/2)}
-Line 723 
 where:
+Line 969 
 where:
  + \Delta t {\bf \nabla}_h {\phi'_{hyd}}^{(n+1/2)}
  \\
  {\eta}^* & = &
  \epsilon_{fs} {\eta}^{n} + \epsilon_{fw} \Delta t (P-E)
  - \Delta t {\bf \nabla}_h \cdot \int_{R_{fixed}}^{R_o}
  [ \gamma \vec{\bf v}^* + (1-\gamma) \vec{\bf v}^{n}] dr
  \end{eqnarray*}
  \\
-Line 735 
 $$
+Line 981 
 $$
  {\bf \nabla}_h \cdot \beta\gamma \Delta t^2 b_s (R_o - R_{fixed})
  {\bf \nabla}_h {\eta}^{n+1}
  = {\eta}^*
  $$
- and then to compute (correction step):
+ and then to compute ({\em CORRECTION\_STEP}):
  $$
  \vec{\bf v}^{n+1} = \vec{\bf v}^{*}
  - \beta \Delta t {\bf \nabla}_h b_s {\eta}^{n+1}
  $$
- The non-hydrostatic part is solved as described previously.
+ %The non-hydrostatic part is solved as described previously.
- Note that:
+ \noindent
+ Notes:
  \begin{enumerate}
- \item The non-hydrostatic part of the code has not yet been
+ \item The RHS term of equation \ref{eq:eta-n+1-CrankNick}
- updated, so that this option cannot be used with $(\beta,\gamma) \neq (1,1)$.
+ corresponds the contribution of fresh water flux (P-E)
- \item The stability criteria with Crank-Nickelson time stepping
+ to the free-surface variations ($\epsilon_{fw}=1$,
+ {\bf useRealFreshWater}{\em=TRUE} in parameter file {\em data}).
+ In order to remain consistent with the tracer equation, specially in
+ the non-linear free-surface formulation, this term is also
+ affected by the Crank-Nicolson time stepping. The RHS reads:
+ $\epsilon_{fw} ( \gamma (P-E)^{n+1/2} + (1-\gamma) (P-E)^{n-1/2} )$
+ %\item The non-hydrostatic part of the code has not yet been
+ %updated, and therefore cannot be used with $(\beta,\gamma) \neq (1,1)$.
+ \item The stability criteria with Crank-Nicolson time stepping
  for the pure linear gravity wave problem in cartesian coordinates is:
  \begin{itemize}
  \item $\beta + \gamma < 1$ : unstable
  \item $\beta \geq 1/2$ and $ \gamma \geq 1/2$ : stable
  \item $\beta + \gamma \geq 1$ : stable if
  $$
  c_{max}^2 (\beta - 1/2)(\gamma - 1/2) + 1 \geq 0
  $$
  $$
  \mbox{with }~
  %c^2 = 2 g H {\Delta t}^2
  %(\frac{1-cos 2 \pi / k}{\Delta x^2}
  %+\frac{1-cos 2 \pi / l}{\Delta y^2})
  %$$
  %Practically, the most stringent condition is obtained with $k=l=2$ :
  %$$
  c_{max} =  2 \Delta t \: \sqrt{g H} \:
  \sqrt{ \frac{1}{\Delta x^2} + \frac{1}{\Delta y^2} }
  $$
  \end{itemize}
+ \item A similar mixed forward/backward time-stepping is also available for
+ the non-hydrostatic algorithm,
+ with a fraction $\beta_{nh}$ ($ 0 < \beta_{nh} \leq 1$)
+ of the non-hydrostatic pressure gradient being evaluated at time step $n+1$
+ (backward in time) and the remaining part ($1 - \beta_{nh}$) being evaluated
+ at time step $n$ (forward in time).
+ The run-time parameter {\bf implicitNHPress} corresponding to the implicit
+ fraction $\beta_{nh}$ of the non-hydrostatic pressure is set by default to
+ the implicit fraction $\beta$ of surface pressure ({\bf implicSurfPress}),
+ but can also be specified independently (in main parameter file {\em data},
+ namelist {\em PARM01}).
  \end{enumerate}

 Legend:



Removed from v.1.10
 


changed lines


 
Added in v.1.34
 Legend:



Removed from v.1.10
 


changed lines


 
Added in v.1.34
-Removed from v.1.10
+Added in v.1.34

	ViewVC Help
Powered by ViewVC 1.1.22