xP: some documentation

Author: knutaros

src/turbulence/dissipationeq.F90

@@ -17,11 +17,15 @@ subroutine dissipationeq(nlev,dt,u_taus,u_taub,z0s,z0b,h,NN,SS)
 !   =
 !   {\cal D}_\epsilon
 !   + \frac{\epsilon}{k} ( c_{\epsilon 1} P + c_{\epsilon 3} G
+!                        + c_{\epsilon x} P_x
+!                        + c_{\epsilon 4} P_s
 !                        - c_{\epsilon 2} \epsilon )
 !   \comma
 ! \end{equation}
 ! where $\dot{\epsilon}$ denotes the material derivative of $\epsilon$.
-! The production terms $P$ and $G$ follow from \eq{PandG} and
+! The production terms $P$ and $G$ follow from \eq{PandG}.
+! $P_s$ is Stokes shear production defined in \eq{computePs}
+! and $P_x$ accounts for extra turbulence production.
 ! ${\cal D}_\epsilon$ represents the sum of the viscous and turbulent
 ! transport terms.
 !

src/turbulence/genericeq.F90

@@ -43,12 +43,16 @@ subroutine genericeq(nlev,dt,u_taus,u_taub,z0s,z0b,h,NN,SS)
 !   \label{generic}
 !   \dot{\psi} = {\cal D}_\psi
 !   + \frac{\psi}{k} (  c_{\psi_1} P + c_{\psi_3} G
+!                     + c_{\psi x} P_x
+!                     + c_{\psi 4} P_s
 !    - c_{\psi 2} \epsilon )
 !   \comma
 ! \end{equation}
 ! where $\dot{\psi}$ denotes the material derivative of $\psi$,
 ! see \cite{UmlaufBurchard2003}.
 ! The production terms $P$ and $G$ follow from \eq{PandG}.
+! $P_s$ is Stokes shear production defined in \eq{computePs}
+! and $P_x$ accounts for extra turbulence production.
 ! ${\cal D}_\psi$ represents the sum of the viscous and turbulent
 ! transport terms. The rate of dissipation can computed by solving
 ! \eq{psi_l} for $l$ and inserting the result into \eq{epsilon}.

src/turbulence/lengthscaleeq.F90

@@ -14,11 +14,14 @@ subroutine lengthscaleeq(nlev,dt,depth,u_taus,u_taub,z0s,z0b,h,NN,SS)
 ! \begin{equation}
 !   \label{MY}
 !   \dot{\overline{q^2 l}}
-!   = {\cal D}_l + l ( E_1  P + E_3 G - E_2  F \epsilon )
+!   = {\cal D}_l + l ( E_1  P + E_3 G + E_x P_x + E_6 P_s - E_2  F \epsilon )
 !   \comma
 ! \end{equation}
 ! where $\dot{\overline{q^2 l}}$ denotes the material derivative of $q^2 l$.
-! The production terms $P$ and $G$ follow from \eq{PandG}, and $\epsilon$
+! The production terms $P$ and $G$ follow from \eq{PandG}.
+! $P_s$ is Stokes shear production defined in \eq{computePs}
+! and $P_x$ accounts for extra turbulence production.
+! $\epsilon$
 ! can be computed either directly from \eq{epsilonMY}, or from \eq{epsilon}
 ! with the help \eq{B1}.
 !

src/turbulence/omegaeq.F90

@@ -17,11 +17,15 @@ subroutine omegaeq(nlev,dt,u_taus,u_taub,z0s,z0b,h,NN,SS)
 !   =
 !   {\cal D}_\omega
 !   + \frac{\omega}{k} ( c_{\omega 1} P + c_{\omega 3} G
+!                        + c_{\omega x} P_x
+!                        + c_{\omega 4} P_s
 !                        - c_{\omega 2} \varepsilon )
 !   \comma
 ! \end{equation}
 ! where $\dot{\omega}$ denotes the material derivative of $\omega$.
-! The production terms $P$ and $G$ follow from \eq{PandG} and
+! The production terms $P$ and $G$ follow from \eq{PandG}.
+! $P_s$ is Stokes shear production defined in \eq{computePs}
+! and $P_x$ accounts for extra turbulence production.
 ! ${\cal D}_\omega$ represents the sum of the viscous and turbulent
 ! transport terms.
 !

src/turbulence/production.F90

@@ -9,20 +9,32 @@ subroutine production(nlev,NN,SS,xP, SSCSTK, SSSTK)
 !
 ! !DESCRIPTION:
 !  This subroutine calculates the production terms of turbulent kinetic
-!  energy as defined in \eq{PandG} and the production of buoayancy
+!  energy as defined in \eq{PandG} and the production of buoyancy
 !  variance as defined in \eq{Pbvertical}.
-!  The shear-production is computed according to
+!  The Eulerian shear-production is computed according to
 !  \begin{equation}
 !    \label{computeP}
-!     P = \nu_t (M^2 + \alpha_w N^2) + X_P
+!     P = \nu_t (M^2 + \alpha_w N^2) + \nu^S_t S_c^2
 !    \comma
 !  \end{equation}
 !  with the turbulent diffusivity of momentum, $\nu_t$, defined in
 !  \eq{nu}. The shear-frequency, $M$, is discretised as described
 !  in \sect{sec:shear}.
 !   The term multiplied by $\alpha_w$ traces back to
 !  a parameterisation of breaking internal waves suggested by
-!  \cite{Mellor89}. $X_P$ is an extra production term, connected for
+!  \cite{Mellor89}.
+!  The turbulent momentum fluxes due to Stokes velocities induce the
+!  Stokes-Eulerian cross-shear term
+!  $S_c^2 = \frac{\partial u}{\partial z}\frac{\partial u_s}{\partial z} + \frac{\partial v}{\partial z}\frac{\partial v_s}{\partial z}$
+!  with corresponding diffusivity $\nu^S_t$, and the additional
+!  Stokes shear-production
+!  \begin{equation}
+!    \label{computePs}
+!     P_s = \nu_t S_c^2 + \nu^S_t S_s^2
+!  \end{equation}
+!  with squared Stokes shear
+!  $S_s^2 = \frac{\partial u_s}{\partial z}^2 + \frac{\partial v_s}{\partial z}^2$.
+!  $X_P$ is an extra production term, connected for
 !  example with turbulence production caused by sea-grass, see
 !  \eq{sgProduction} in  \sect{sec:seagrass}. {\tt xP} is an {\tt optional}
 !  argument in the FORTRAN code.

src/turbulence/q2over2eq.F90

@@ -13,7 +13,7 @@ subroutine q2over2eq(nlev,dt,u_taus,u_taub,z0s,z0b,h,NN,SS)
 !   \label{tkeB}
 !   \dot{\overline{q^2/2}}
 !   =
-!   {\cal D}_q +  P + G  - \epsilon
+!   {\cal D}_q +  P + G + P_x + P_s - \epsilon
 !   \comma
 ! \end{equation}
 ! where $\dot{\overline{q^2/2}}$ denotes the material derivative of $q^2/2$.

src/turbulence/tkeeq.F90

@@ -16,12 +16,15 @@ subroutine tkeeq(nlev,dt,u_taus,u_taub,z0s,z0b,h,NN,SS)
 !   \label{tkeA}
 !   \dot{k}
 !   =
-!   {\cal D}_k +  P + G  - \epsilon
+!   {\cal D}_k +  P + G + P_x + P_s - \epsilon
 !   \comma
 ! \end{equation}
 ! where $\dot{k}$ denotes the material derivative of $k$. $P$ and $G$ are
 ! the production of $k$ by mean shear and buoyancy, respectively, and
-! $\epsilon$ the rate of dissipation. ${\cal D}_k$ represents the sum of
+! $\epsilon$ the rate of dissipation.
+! $P_s$ is Stokes shear production defined in \eq{computePs}
+! and $P_x$ accounts for extra turbulence production.
+! ${\cal D}_k$ represents the sum of
 ! the viscous and turbulent transport terms.
 ! For horizontally homogeneous flows, the transport term ${\cal D}_k$
 ! appearing in \eq{tkeA} is presently expressed by a simple