chap_DYN.tex

baroclinic time $\tau + \rdt \tau$
\[
  % \label{eq:DYN_spg_ts_u}
  \textbf{U}(\tau+\rdt) = \overline{\textbf{U}^{(b)}(\tau+\rdt)} = \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau,t_{n})
\]
The surface height on the new baroclinic time step is then determined via a baroclinic leap-frog using
the following form

\begin{equation}
  \label{eq:DYN_spg_ts_ssh}
  \eta(\tau+\Delta) - \eta^{F}(\tau-\Delta) = 2\rdt \ \left[ - \nabla \cdot \textbf{U}(\tau) + \text{EMP}_w \right]
\end{equation}

The use of this "big-leap-frog" scheme for the surface height ensures compatibility between
the mass/volume budgets and the tracer budgets.
More discussion of this point is provided in Chapter 10 (see in particular Section 10.2).

In general, some form of time filter is needed to maintain integrity of the surface height field due to
the leap-frog splitting mode in equation \autoref{eq:DYN_spg_ts_ssh}.
We have tried various forms of such filtering,
with the following method discussed in \cite{griffies.pacanowski.ea_MWR01} chosen due to
its stability and reasonably good maintenance of tracer conservation properties (see ??).

\begin{equation}
  \label{eq:DYN_spg_ts_sshf}
  \eta^{F}(\tau-\Delta) =  \overline{\eta^{(b)}(\tau)}
\end{equation}
Another approach tried was

\[
  % \label{eq:DYN_spg_ts_sshf2}
  \eta^{F}(\tau-\Delta) = \eta(\tau)
  + (\alpha/2) \left[\overline{\eta^{(b)}}(\tau+\rdt)
    + \overline{\eta^{(b)}}(\tau-\rdt) -2 \;\eta(\tau) \right]
\]

which is useful since it isolates all the time filtering aspects into the term multiplied by $\alpha$.
This isolation allows for an easy check that tracer conservation is exact when
eliminating tracer and surface height time filtering (see ?? for more complete discussion).
However, in the general case with a non-zero $\alpha$,
the filter \autoref{eq:DYN_spg_ts_sshf} was found to be more conservative, and so is recommended.

}            %%end gm comment (copy of griffies book)

%% =================================================================================================
\section[Lateral diffusion term and operators (\textit{dynldf.F90})]{Lateral diffusion term and operators (\protect\mdl{dynldf})}
\label{sec:DYN_ldf}

\begin{listing}
  \nlst{namdyn_ldf}
  \caption{\forcode{&namdyn_ldf}}
  \label{lst:namdyn_ldf}
\end{listing}

Options are defined through the \nam{dyn_ldf}{dyn\_ldf} namelist variables.
The options available for lateral diffusion are to use either laplacian (rotated or not) or biharmonic operators.
The coefficients may be constant or spatially variable;
the description of the coefficients is found in the chapter on lateral physics (\autoref{chap:LDF}).
The lateral diffusion of momentum is evaluated using a forward scheme,
\ie\ the velocity appearing in its expression is the \textit{before} velocity in time,
except for the pure vertical component that appears when a tensor of rotation is used.
This latter term is solved implicitly together with the vertical diffusion term (see \autoref{chap:TD}).

At the lateral boundaries either free slip,
no slip or partial slip boundary conditions are applied according to the user's choice (see \autoref{chap:LBC}).

\cmtgm{
  Hyperviscous operators are frequently used in the simulation of turbulent flows to
  control the dissipation of unresolved small scale features.
  Their primary role is to provide strong dissipation at the smallest scale supported by
  the grid while minimizing the impact on the larger scale features.
  Hyperviscous operators are thus designed to be more scale selective than the traditional,
  physically motivated Laplace operator.
  In finite difference methods,
  the biharmonic operator is frequently the method of choice to achieve this scale selective dissipation since
  its damping time (\ie\ its spin down time) scale like $\lambda^{-4}$ for disturbances of wavelength $\lambda$
  (so that short waves damped more rapidelly than long ones),
  whereas the Laplace operator damping time scales only like $\lambda^{-2}$.
}

%% =================================================================================================
\subsection[Iso-level laplacian (\forcode{ln_dynldf_lap})]{Iso-level laplacian operator (\protect\np{ln_dynldf_lap}{ln\_dynldf\_lap})}
\label{subsec:DYN_ldf_lap}

For lateral iso-level diffusion, the discrete operator is:
\begin{equation}
  \label{eq:DYN_ldf_lap}
  \left\{
    \begin{aligned}
      D_u^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{1u} }\delta_{i+1/2} \left[ {A_T^{lm}
          \;\chi } \right]-\frac{1}{e_{2u} {\kern 1pt}e_{3u} }\delta_j \left[
        {A_f^{lm} \;e_{3f} \zeta } \right] \\ \\
      D_v^{l{\mathrm {\mathbf U}}} =\frac{1}{e_{2v} }\delta_{j+1/2} \left[ {A_T^{lm}
          \;\chi } \right]+\frac{1}{e_{1v} {\kern 1pt}e_{3v} }\delta_i \left[
        {A_f^{lm} \;e_{3f} \zeta } \right]
    \end{aligned}
  \right.
\end{equation}

As explained in \autoref{subsec:MB_ldf},
this formulation (as the gradient of a divergence and curl of the vorticity) preserves symmetry and
ensures a complete separation between the vorticity and divergence parts of the momentum diffusion.

In v5.0 a symetrical lateral iso-level operator has been introduced : 
\begin{equation}
  \label{eq:DYN_ldf_lap_sym}
  \left\{
    \begin{aligned}
      D_u^{l{\mathrm {\mathbf U}}} &= \frac{1}{e_{1u}\,e_{2u}\,e_{3u} } \left( 
      \frac{1}{e_{2u}} \delta_{i+1/2} \left[ e_{2t}\,e_{2t}\,e_{3t}\, A_T^{lm} \,\vartheta \right] 
      - \frac{1}{e_{1u}} \delta_{j+1/2} \left[ e_{1f}\,e_{1f}\,e_{3f}\,A_F^{lm} \psi \right] \right) \\ \\
      D_v^{l{\mathrm {\mathbf U}}} &= \frac{1}{e_{1v}\,e_{2v}\,e_{3v} } \left( 
      \frac{1}{e_{2v}} \delta_{j+1/2} \left[ e_{2f}\,e_{2f}\,e_{3f}\, A_F^{lm} \,\psi \right] 
      - \frac{1}{e_{1v}} \delta_{i+1/2} \left[ e_{1t}\,e_{1t}\,e_{3t}\,A_T^{lm} \vartheta \right] \right)
    \end{aligned}
  \right.
\end{equation}

Where $\psi$ and $\vartheta$ are respectively the shearing stress component (F-point) and the 
tension stress component (T-point)  defined as : 
\begin{equation}
  \label{eq:DYN_ldf_lap_sheten}
  \left\{
    \begin{aligned}
      \psi &= \frac{e_{1f}}{e_{2f}} \delta_{j+1/2} \left[ \frac{u}{e_{1u}} \right] + \frac{e_{2f}}{e_{1f}} \delta_{i+1/2} \left[
        \frac{v}{e_{2v}} \right] \\ \\
      \vartheta &= \frac{e_{2t}}{e_{1t}} \delta_{i} \left[ \frac{u}{e_{2u}} \right] - \frac{e_{1t}}{e_{2t}} \delta_j \left[
        \frac{v}{e_{1v}} \right]
    \end{aligned}
  \right.
\end{equation}

%% =================================================================================================
\subsection[Rotated laplacian (\forcode{ln_dynldf_iso})]{Rotated laplacian operator (\protect\np{ln_dynldf_iso}{ln\_dynldf\_iso})}
\label{subsec:DYN_ldf_iso}

A rotation of the lateral momentum diffusion operator is needed in several cases:
for iso-neutral diffusion in the $z$-coordinate (\np[=.true.]{ln_dynldf_iso}{ln\_dynldf\_iso}) and
for either iso-neutral (\np[=.true.]{ln_dynldf_iso}{ln\_dynldf\_iso}) or
geopotential (\np[=.true.]{ln_dynldf_hor}{ln\_dynldf\_hor}) diffusion in the $s$-coordinate.
In the partial step case, coordinates are horizontal except at the deepest level and
no rotation is performed when \np[=.true.]{ln_dynldf_hor}{ln\_dynldf\_hor}.
The diffusion operator is defined simply as the divergence of down gradient momentum fluxes on
each momentum component.
It must be emphasized that this formulation ignores constraints on the stress tensor such as symmetry.
The resulting discrete representation is:
\begin{equation}
  \label{eq:DYN_ldf_iso}
  \begin{split}
    D_u^{l\textbf{U}} &= \frac{1}{e_{1u} \, e_{2u} \, e_{3u} }	\\
    &  \left\{\quad  {\delta_{i+1/2} \left[ {A_T^{lm}  \left(
              {\frac{e_{2t} \; e_{3t} }{e_{1t} } \,\delta_{i}[u]
                -e_{2t} \; r_{1t} \,\overline{\overline {\delta_{k+1/2}[u]}}^{\,i,\,k}}
            \right)} \right]} 	\right. \\
    & \qquad +\ \delta_j \left[ {A_f^{lm} \left( {\frac{e_{1f}\,e_{3f} }{e_{2f}
            }\,\delta_{j+1/2} [u] - e_{1f}\, r_{2f}
            \,\overline{\overline {\delta_{k+1/2} [u]}} ^{\,j+1/2,\,k}}
        \right)} \right] \\
    &\qquad +\ \delta_k \left[ {A_{uw}^{lm} \left( {-e_{2u} \, r_{1uw} \,\overline{\overline
              {\delta_{i+1/2} [u]}}^{\,i+1/2,\,k+1/2} }
        \right.} \right. \\
    &  \ \qquad \qquad \qquad \quad\
    - e_{1u} \, r_{2uw} \,\overline{\overline {\delta_{j+1/2} [u]}} ^{\,j,\,k+1/2} \\
    & \left. {\left. { \ \qquad \qquad \qquad \ \ \ \left. {\
                +\frac{e_{1u}\, e_{2u} }{e_{3uw} }\,\left( {r_{1uw}^2+r_{2uw}^2}
                \right)\,\delta_{k+1/2} [u]} \right)} \right]\;\;\;} \right\} \\ \\
    D_v^{l\textbf{V}} &= \frac{1}{e_{1v} \, e_{2v} \, e_{3v} } \\
    &  \left\{\quad  {\delta_{i+1/2} \left[ {A_f^{lm}  \left(
              {\frac{e_{2f} \; e_{3f} }{e_{1f} } \,\delta_{i+1/2}[v]
                -e_{2f} \; r_{1f} \,\overline{\overline {\delta_{k+1/2}[v]}}^{\,i+1/2,\,k}}
            \right)} \right]} 	\right. \\
    & \qquad +\ \delta_j \left[ {A_T^{lm} \left( {\frac{e_{1t}\,e_{3t} }{e_{2t}
            }\,\delta_{j} [v] - e_{1t}\, r_{2t}
            \,\overline{\overline {\delta_{k+1/2} [v]}} ^{\,j,\,k}}
        \right)} \right] \\
    & \qquad +\ \delta_k \left[ {A_{vw}^{lm} \left( {-e_{2v} \, r_{1vw} \,\overline{\overline
              {\delta_{i+1/2} [v]}}^{\,i+1/2,\,k+1/2} }\right.} \right. \\
    &  \ \qquad \qquad \qquad \quad\
    - e_{1v} \, r_{2vw} \,\overline{\overline {\delta_{j+1/2} [v]}} ^{\,j+1/2,\,k+1/2} \\
    & \left. {\left. { \ \qquad \qquad \qquad \ \ \ \left. {\
                +\frac{e_{1v}\, e_{2v} }{e_{3vw} }\,\left( {r_{1vw}^2+r_{2vw}^2}
                \right)\,\delta_{k+1/2} [v]} \right)} \right]\;\;\;} \right\}
  \end{split}
\end{equation}
where $r_1$ and $r_2$ are the slopes between the surface along which the diffusion operator acts and
the surface of computation ($z$- or $s$-surfaces).
The way these slopes are evaluated is given in the lateral physics chapter (\autoref{chap:LDF}).

%% =================================================================================================
\subsection[Iso-level bilaplacian (\forcode{ln_dynldf_bilap})]{Iso-level bilaplacian operator (\protect\np{ln_dynldf_bilap}{ln\_dynldf\_bilap})}
\label{subsec:DYN_ldf_bilap}

The lateral fourth order operator formulation on momentum is obtained by applying \autoref{eq:DYN_ldf_lap} twice.
It requires an additional assumption on boundary conditions:
the first derivative term normal to the coast depends on the free or no-slip lateral boundary conditions chosen,
while the third derivative terms normal to the coast are set to zero (see \autoref{chap:LBC}).
\cmtgm{add a remark on the the change in the position of the coefficient}

%% =================================================================================================
\section[Vertical diffusion term (\textit{dynzdf.F90})]{Vertical diffusion term (\protect\mdl{dynzdf})}
\label{sec:DYN_zdf}

Options are defined through the \nam{zdf}{zdf} namelist variables.
The large vertical diffusion coefficient found in the surface mixed layer together with high vertical resolution implies that in the case of explicit time stepping there would be too restrictive a constraint on the time step.
In v5.0 only a backward (or implicit) time differencing scheme can be used for the vertical diffusion term.
(see \autoref{chap:TD}).

The formulation of the vertical subgrid scale physics is the same whatever the vertical coordinate is.
The vertical diffusion operators given by \autoref{eq:MB_zdf} take the following semi-discrete space form:
\[
  % \label{eq:DYN_zdf}
  \left\{
    \begin{aligned}
      D_u^{vm} &\equiv \frac{1}{e_{3u}} \ \delta_k \left[ \frac{A_{uw}^{vm} }{e_{3uw} }
        \ \delta_{k+1/2} [\,u\,]         \right]     \\
      \\
      D_v^{vm} &\equiv \frac{1}{e_{3v}} \ \delta_k \left[ \frac{A_{vw}^{vm} }{e_{3vw} }
        \ \delta_{k+1/2} [\,v\,]         \right]
    \end{aligned}
  \right.
\]
where $A_{uw}^{vm} $ and $A_{vw}^{vm} $ are the vertical eddy viscosity and diffusivity coefficients.
The way these coefficients are evaluated depends on the vertical physics used (see \autoref{chap:ZDF}).

The surface boundary condition on momentum is the stress exerted by the wind.
At the surface, the momentum fluxes are prescribed as the boundary condition on
the vertical turbulent momentum fluxes,
\begin{equation}
  \label{eq:DYN_zdf_sbc}
  \left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{z=1}
  = \frac{1}{\rho_o} \binom{\tau_u}{\tau_v }
\end{equation}
where $\left( \tau_u ,\tau_v \right)$ are the two components of the wind stress vector in
the (\textbf{i},\textbf{j}) coordinate system.
The high mixing coefficients in the surface mixed layer ensure that the surface wind stress is distributed in
the vertical over the mixed layer depth.
If the vertical mixing coefficient is small (when no mixed layer scheme is used)
the surface stress enters only the top model level, as a body force.
The surface wind stress is calculated in the surface module routines (SBC, see \autoref{chap:SBC}).

The turbulent flux of momentum at the bottom of the ocean is specified through a bottom friction parameterisation
(see \autoref{sec:ZDF_drg})

When activated (\np[=.true.]{ln_zad_Aimp}{ln\_zad\_Aimp}) vertical advection of momentum 
can be done partly implicitely.
Variables appearing in these expressions are implicit in time (\textit{after}) 
and vertical derivatives are done with an $1^{st}$ order upstream scheme.

In vector form case
\begin{equation}
  \label{eq:DYN_zimp_vec}
  \left\{
    \begin{aligned}
      &\frac{1}{e_{3uw}}\; \delta_{k} \left[ \overline{\overline{ e_{1t}\,e_{2t}\,w_i }}^{\,i+1/2,k+1/2} u \right] \\ \\
      &\frac{1}{e_{3vw}}\; \delta_{k} \left[ \overline{\overline{ e_{1t}\,e_{2t}\,w_i }}^{\,j+1/2,k+1/2} v \right]
    \end{aligned}
  \right.
\end{equation}

In flux form case
\begin{equation}
  \label{eq:DYN_zimp_flu}
  \left\{
    \begin{aligned}
      &\frac{1}{e_{1u}\,e_{2u}\,e_{3u}}\; \delta_{k} \left[ \overline{ e_{1t}\,e_{2t}\,w_i }^{\,i+1/2} \, u \right] \\ \\
      &\frac{1}{e_{1v}\,e_{2v}\,e_{3v}}\; \delta_{k} \left[ \overline{ e_{1t}\,e_{2t}\,w_i }^{\,j+1/2} \, v \right]
    \end{aligned}
  \right.
\end{equation}


%% =================================================================================================
\section{External forcings}
\label{sec:DYN_forcing}

Besides the surface and bottom stresses (see the above section)
which are introduced as boundary conditions on the vertical mixing,
three other forcings may enter the dynamical equations by affecting the surface pressure gradient.

(1) When \np[=.true.]{ln_apr_dyn}{ln\_apr\_dyn} (see \autoref{sec:SBC_apr}),
the atmospheric pressure is taken into account when computing the surface pressure gradient.

(2) When \np[=.true.]{ln_tide_pot}{ln\_tide\_pot} and \np[=.true.]{ln_tide}{ln\_tide} (see \autoref{sec:SBC_TDE}),
the tidal potential is taken into account when computing the surface pressure gradient.

(3) When \np[=2]{nn_ice_embd}{nn\_ice\_embd} and SI3 is used
(\ie\ when the sea-ice is embedded in the ocean),
the snow-ice mass is taken into account when computing the surface pressure gradient.

\cmtgm{ missing : the lateral boundary condition !!!   another external forcing
 }

%% =================================================================================================
\section{Wetting and drying }
\label{sec:DYN_wetdry}

There is currently only one choice of limiter for the wetting and drying code
(wd): a directional limiter (dl). Previous versions also provided an iterative
limiter (il) but this has been removed due to performance and robustness issues.
The framework for providing alternatives has been retained in case of future
interest so the directional limiter has to be exlicitly selected despite being
the only choice.

The directional limiter is based on the scheme developed by \cite{warner.defne.ea_CG13}
for ROMS which was in turn based on ideas developed for POM by \cite{oey_OM06}.  The
directional limiter is activated by setting $\mathrm{ln\_wd\_dl} = \mathrm{.true.}$.

\begin{listing}
  \nlst{namwad}
  \caption{\forcode{&namwad}}
  \label{lst:namwad}
\end{listing}

The following terminology is used. The depth of the topography (positive downwards)
at each $(i,j)$ point is the quantity stored in array $\mathrm{ht\_wd}$ in the \NEMO\ code.
The height of the free surface (positive upwards) is denoted by $ \mathrm{ssh}$. Given the sign
conventions used, the water depth, $h$, is the height of the free surface plus the depth of the
topography (i.e. $\mathrm{ssh} + \mathrm{ht\_wd}$).

Wetting and Drying schemes take all points in the domain below a land elevation of
$\mathrm{rn\_wdld}$ to be covered by water. The topography specified with a model
configuration is required to have negative depths at points where the land is higher than
the topography's reference sea-level. The vertical grid in \NEMO\ is normally computed
relative to an initial state with zero sea surface height elevation.  The user can choose
to compute the vertical grid and heights in the model relative to a non-zero reference
height for the free surface. This choice affects the calculation of the metrics and depths
(i.e. the $\mathrm{e3t\_0, ht\_0}$ etc. arrays).

Points where the water depth is less than $\mathrm{rn\_wdmin1}$ are interpreted as ``dry''.
$\mathrm{rn\_wdmin1}$ is usually chosen to be of order $0.05$m but extreme topographies
with very steep slopes require larger values for normal choices of time-step. 

Surface fluxes are switched off for dry cells to prevent freezing, boiling etc. of
very thin water layers.  The fluxes are tappered down using a $\mathrm{tanh}$ weighting
function to no flux as the dry limit $\mathrm{rn\_wdmin1}$ is approached. Even wet cells
can be very shallow and may need their surface fluxes reduced.  The depth at which to
start tapering is controlled by the user by setting $\mathrm{rn\_wd\_sbcdep}$.  The
fraction $(<1)$ of sufrace fluxes to use at this depth is set by
$\mathrm{rn\_wd\_sbcfra}$.

The code has been tested in six test cases provided in the WAD\_TEST\_CASES configuration
and in ``realistic'' configurations covering parts of the north-west European shelf.
All these configurations have used pure sigma coordinates. It is expected that
the wetting and drying code will work in domains with more general s-coordinates provided
the coordinates are pure sigma in the region where wetting and drying actually occurs.

The next sub-section describes the directional limiter.  The final sub-section covers some
additional considerations that are relevant to all possible limiting schemes.

\subsection[Directional limiter (\textit{wet\_dry.F90})]{Directional limiter (\mdl{wet\_dry})}
\label{subsec:DYN_wd_directional_limiter}

The principal idea of the directional limiter is that water should not be allowed to flow
out of a dry tracer cell (i.e. one whose water depth is less than
\np{rn_wdmin1}{rn\_wdmin1}).

All the changes associated with this option are made to the barotropic solver for the
non-linear free surface code within $\mathrm{dynspg\_ts}$.  On each barotropic sub-step
the scheme determines the direction of the flow across each face of all the tracer cells
and sets the flux across the face to zero when the flux is from a dry tracer cell. This
prevents cells whose depth is $\mathrm{rn\_wdmin1}$ or less from drying out further. The
scheme does not force $h$ (the water depth) at tracer cells to be at least the minimum
depth and hence is able to conserve mass / volume.

The flux across each $u$-face of a tracer cell is multiplied by a factor
$\mathrm{zuwdmask}$ (an array which depends on ji and jj).  If the user sets
\np[=.false.]{ln_wd_dl_ramp}{ln\_wd\_dl\_ramp} then $\mathrm{zuwdmask}$ is 1 when the flux
is from a cell with water depth greater than \np{rn_wdmin1}{rn\_wdmin1} and 0 otherwise.
If the user sets \np[=.true.]{ln_wd_dl_ramp}{ln\_wd\_dl\_ramp} the flux across the face is
ramped down as the water depth decreases from 2 * \np{rn_wdmin1}{rn\_wdmin1} to
\np{rn_wdmin1}{rn\_wdmin1}. The use of this ramp reduced grid-scale noise in idealised
test cases.

At the point where the flux across a $u$-face is multiplied by $\mathrm{zuwdmask}$ , we
have chosen also to multiply the corresponding velocity on the ``now'' step at that face
by $\mathrm{zuwdmask}$. We could have chosen not to do that and to allow fairly large
velocities to occur in these ``dry'' cells.  The rationale for setting the velocity to
zero is that it is the momentum equations that are being solved and the total momentum of
the upstream cell (treating it as a finite volume) should be considered to be its depth
times its velocity. This depth is considered to be zero at ``dry'' $u$-points consistent
with its treatment in the calculation of the flux of mass across the cell face.

\cite{warner.defne.ea_CG13} state that in their scheme the velocity masks at the cell
faces for the baroclinic timesteps are set to 0 or 1 depending on whether the average of
the masks over the barotropic sub-steps is respectively less than or greater than 0.5.
That scheme does not conserve tracers in integrations started from constant tracer fields
(tracers independent of $x$, $y$ and $z$). Our scheme conserves constant tracers because
the velocities used at the tracer cell faces on the baroclinic timesteps are carefully
calculated by $\mathrm{dynspg\_ts}$ to equal their mean value during the barotropic steps.
If the user sets \np[=.true.]{ln_wd_dl_bc}{ln\_wd\_dl\_bc}, the baroclinic velocities are
also multiplied by a suitably weighted average of $\mathrm{zuwdmask}$.

%% =================================================================================================
\subsubsection[Additional considerations (\textit{usrdef\_zgr.F90})]{Additional considerations (\mdl{usrdef\_zgr})}
\label{subsec:DYN_WAD_additional}

In the very shallow water where wetting and drying occurs the parametrisation of
bottom drag is clearly very important. In order to promote stability
it is sometimes useful to calculate the bottom drag using an implicit time-stepping approach.

Suitable specifcation of the surface heat flux in wetting and drying domains in forced and
coupled simulations needs further consideration. In order to prevent freezing or boiling
in uncoupled integrations the net surface heat fluxes need to be appropriately limited.

%      The WAD test cases
%% =================================================================================================
\subsection[The WAD test cases (\textit{usrdef\_zgr.F90})]{The WAD test cases (\mdl{usrdef\_zgr})}
\label{subsec:DYN_WAD_test_cases}

See the WAD tests MY\_DOC documention for details of the WAD test cases.

%% =================================================================================================
\section[Time evolution term (\textit{dynnxt.F90})]{Time evolution term (\protect\mdl{dynnxt})}
\label{sec:DYN_nxt}

Options are defined through the \nam{dom}{dom} namelist variables.
The general framework for dynamics time stepping is a leap-frog scheme,
\ie\ a three level centred time scheme associated with an Asselin time filter (cf. \autoref{chap:TD}).
The scheme is applied to the velocity, except when
using the flux form of momentum advection (cf. \autoref{sec:DYN_adv_cor_flux})
in the variable volume case (\np[=.false.]{ln_linssh}{ln\_linssh}),
where it has to be applied to the thickness weighted velocity (see \autoref{sec:SCOORD_momentum})

$\bullet$ vector invariant form or linear free surface
(\np[=.true.]{ln_dynhpg_vec}{ln\_dynhpg\_vec} or \np[=.true.]{ln_linssh}{ln\_linssh}):
\[
  % \label{eq:DYN_nxt_vec}
  \left\{
    \begin{aligned}
      &u^{t+\rdt} = u_f^{t-\rdt} + 2\rdt  \ \text{RHS}_u^t  	\\
      &u_f^t \;\quad = u^t+\gamma \,\left[ {u_f^{t-\rdt} -2u^t+u^{t+\rdt}} \right]
    \end{aligned}
  \right.
\]

$\bullet$ flux form and nonlinear free surface
(\np[=.false.]{ln_dynhpg_vec}{ln\_dynhpg\_vec} and \np[=.false.]{ln_linssh}{ln\_linssh}):
\[
  % \label{eq:DYN_nxt_flux}
  \left\{
    \begin{aligned}
      &\left(e_{3u}\,u\right)^{t+\rdt} = \left(e_{3u}\,u\right)_f^{t-\rdt} + 2\rdt \; e_{3u} \;\text{RHS}_u^t  	\\
      &\left(e_{3u}\,u\right)_f^t \;\quad = \left(e_{3u}\,u\right)^t
      +\gamma \,\left[ {\left(e_{3u}\,u\right)_f^{t-\rdt} -2\left(e_{3u}\,u\right)^t+\left(e_{3u}\,u\right)^{t+\rdt}} \right]
    \end{aligned}
  \right.
\]
where RHS is the right hand side of the momentum equation,
the subscript $f$ denotes filtered values and $\gamma$ is the Asselin coefficient.
$\gamma$ is initialized as \np{nn_atfp}{nn\_atfp} (namelist parameter).
Its default value is \np[=10.e-3]{nn_atfp}{nn\_atfp}.
In both cases, the modified Asselin filter is not applied since perfect conservation is not an issue for
the momentum equations.

\subinc{\input{../../global/epilogue}}

\end{document}