--- manual/s_phys_pkgs/text/kpp.tex	2005/08/01 22:31:36	1.6
+++ manual/s_phys_pkgs/text/kpp.tex	2010/08/30 23:09:21	1.11
@@ -1,5 +1,5 @@
 \subsection{KPP: Nonlocal K-Profile Parameterization for 
-Diapycnal Mixing}
+Vertical Mixing}
 
 \label{sec:pkg:kpp}
 \begin{rawhtml}
@@ -11,9 +11,79 @@
 \subsubsection{Introduction
 \label{sec:pkg:kpp:intro}}
 
+The nonlocal K-Profile Parameterization (KPP) scheme
+of \cite{lar-eta:94} unifies the treatment of a variety of 
+unresolved processes involved in vertical mixing. 
+To consider it as one mixing scheme is, in the view of the authors,
+somewhat misleading since it consists of several entities
+to deal with distinct mixing processes in the ocean's surface 
+boundary layer, and the interior:
+%
+\begin{enumerate}
+%
+\item
+mixing in the interior is goverened by
+shear instability (modeled as function of the local gradient
+Richardson number), internal wave activity (assumed constant),
+and double-diffusion (not implemented here).
+%
+\item
+a boundary layer depth $h$ or \texttt{hbl} is determined
+at each grid point, based on a critical value of turbulent
+processes parameterized by a bulk Richardson number;
+%
+\item
+mixing is strongly enhanced in the boundary layer under the
+stabilizing or destabilizing influence of surface forcing 
+(buoyancy and momentum) enabling boundary layer properties
+to penetrate well into the thermocline; 
+mixing is represented through a polynomial profile whose 
+coefficients are determined subject to several contraints;
+%
+\item
+the boundary-layer profile is made to agree with similarity
+theory of turbulence and is matched, in the asymptotic sense
+(function and derivative agree at the boundary),
+to the interior thus fixing the polynomial coefficients; 
+matching allows for some fraction of the boundary layer mixing
+to affect the interior, and vice versa;
+%
+\item
+a ``non-local'' term $\hat{\gamma}$ or \texttt{ghat}
+which is independent of the vertical property gradient further 
+enhances mixing where the water column is unstable
+%
+\end{enumerate}
+%
+The scheme has been extensively compared to observations
+(see e.g. \cite{lar-eta:97}) and is now coomon in many
+ocean models.
+
+The current code originates in the NCAR NCOM 1-D code
+and was kindly provided by Bill Large and Jan Morzel.
+It has been adapted first to the MITgcm vector code and
+subsequently to the current parallel code.
+Adjustment were mainly in conjunction with WRAPPER requirements
+(domain decomposition and threading capability), to enable
+automatic differentiation of tangent linear and adjoint code
+via TAMC.
+
+The following sections will describe the KPP package
+configuration and compiling (\ref{sec:pkg:kpp:comp}),
+the settings and choices of runtime parameters
+(\ref{sec:pkg:kpp:runtime}),
+more detailed description of equations to which these
+parameters relate (\ref{sec:pkg:kpp:equations}),
+and key subroutines where they are used %(\ref{sec:pkg:kpp:subroutines}),
+(\ref{sec:pkg:kpp:flowchart}),
+and diagnostics output of KPP-derived diffusivities, viscosities
+and boundary-layer/mixed-layer depths 
+(\ref{sec:pkg:kpp:diagnostics}).
+
 %----------------------------------------------------------------------
 
-\subsubsection{KPP configuration and compiling}
+\subsubsection{KPP configuration and compiling
+\label{sec:pkg:kpp:comp}}
 
 As with all MITgcm packages, KPP can be turned on or off at compile time
 %
@@ -26,14 +96,23 @@
 or using \texttt{genmake2} adding
 \texttt{-enable=kpp} or \texttt{-disable=kpp} switches
 %
+\item
+\textit{Required packages and CPP options:} \\
+No additional packages are required, but the MITgcm kernel flag
+enabling the penetration of shortwave radiation below
+the surface layer needs to be set in \texttt{CPP\_OPTIONS.h} 
+as follows: \\
+\texttt{\#define SHORTWAVE\_HEATING}
+%
 \end{itemize}
-(see Section \ref{sect:buildingCode}).
+(see Section \ref{sec:buildingCode}).
 
 Parts of the KPP code can be enabled or disabled at compile time
 via CPP preprocessor flags. These options are set in
 \texttt{KPP\_OPTIONS.h}. Table \ref{tab:pkg:kpp:cpp} summarizes them.
 
-\begin{table}[h!]
+\begin{table}[!ht]
+\centering
   \label{tab:pkg:kpp:cpp}
   {\footnotesize
     \begin{tabular}{|l|l|}
@@ -69,7 +148,6 @@
 \end{table}
 
 
-
 %----------------------------------------------------------------------
 
 \subsubsection{Run-time parameters
@@ -104,7 +182,12 @@
 \paragraph{Package flags and parameters}
 ~ \\
 %
-\begin{table}[h!]
+Table \ref{tab:pkg:kpp:runtime_flags} summarizes the
+runtime flags that are set in \texttt{data.pkg}, and
+their default values.
+
+\begin{table}[!ht]
+\centering
   \label{tab:pkg:kpp:runtime_flags}
   {\footnotesize
     \begin{tabular}{|l|c|l|}
@@ -207,21 +290,112 @@
 
 %----------------------------------------------------------------------
 
-\subsubsection{Equations
+\subsubsection{Equations and key routines
 \label{sec:pkg:kpp:equations}}
 
-%----------------------------------------------------------------------
+We restrict ourselves to writing out only the essential equations
+that relate to main processes and parameters mentioned above.
+We closely follow the notation of \cite{lar-eta:94}.
 
-\subsubsection{Key subroutines
-\label{sec:pkg:kpp:subroutines}}
+\paragraph{KPP\_CALC:} Top-level routine. \\
+~
 
-\paragraph{kpp\_calc:} Top-level routine. \\
+\paragraph{KPP\_MIX:} Intermediate-level routine \\
 ~
 
-\paragraph{kpp\_mix:} Intermediate-level routine \\
+\paragraph{BLMIX: Mixing in the boundary layer} ~ \\
+%
 ~
 
-\paragraph{ri\_iwmix:} ~ \\
+The vertical fluxes $\overline{wx}$
+of momentum and tracer properties $X$
+is composed of a gradient-flux term (proportional to
+the vertical property divergence $\partial_z X$), and
+a ``nonlocal'' term $\gamma_x$ that enhances the
+gradient-flux mixing coefficient $K_x$
+%
+\begin{equation}
+\overline{wx}(d) \, = \, -K_x \left(
+\frac{\partial X}{\partial z} \, - \, \gamma_x \right)
+\end{equation}
+
+\begin{itemize}
+%
+\item
+\textit{Boundary layer mixing profile} \\
+%
+It is expressed as the product of the boundary layer depth $h$,
+a depth-dependent turbulent velocity scale $w_x(\sigma)$ and a
+non-dimensional shape function $G(\sigma)$
+%
+\begin{equation}
+K_x(\sigma) \, = \, h \, w_x(\sigma) \, G(\sigma)
+\end{equation}
+%
+with dimensionless vertical coordinate $\sigma = d/h$.
+For details of $ w_x(\sigma)$ and $G(\sigma)$ we refer to
+\cite{lar-eta:94}.
+
+%
+\item
+\textit{Nonlocal mixing term} \\
+%
+The nonlocal transport term $\gamma$ is nonzero only for
+tracers in unstable (convective) forcing conditions.
+Thus, depending on the  stability parameter $\zeta = d/L$ 
+(with depth $d$, Monin-Obukhov length scale $L$)
+it has the following form:
+%
+\begin{eqnarray}
+\begin{array}{cl}
+\gamma_x \, = \, 0 & \zeta \, \ge \, 0 \\
+~ & ~ \\
+\left.
+\begin{array}{c}
+\gamma_m \, = \, 0 \\
+ ~ \\
+\gamma_s \, = \, C_s 
+\frac{\overline{w s_0}}{w_s(\sigma) h} \\
+ ~ \\
+\gamma_{\theta} \, = \, C_s
+\frac{\overline{w \theta_0}+\overline{w \theta_R}}{w_s(\sigma) h} \\
+\end{array}
+\right\} 
+&
+\zeta \, < \, 0 \\
+\end{array}
+\end{eqnarray}
+
+\end{itemize}
+
+In practice, the routine peforms the following tasks:
+%
+\begin{enumerate}
+%
+\item
+compute velocity scales at hbl
+%
+\item
+find the interior viscosities and derivatives at hbl
+%
+\item
+compute turbulent velocity scales on the interfaces
+%
+\item
+compute the dimensionless shape functions at the interfaces
+%
+\item
+compute boundary layer diffusivities at the interfaces
+%
+\item
+compute nonlocal transport term
+%
+\item
+find diffusivities at kbl-1 grid level
+%
+\end{enumerate}
+
+\paragraph{RI\_IWMIX: Mixing in the interior} ~ \\
 %
 Compute interior viscosity and diffusivity coefficients due to
 %
@@ -234,12 +408,13 @@
 to background internal wave activity, and
 %
 \item
-to static instability (local Richardson number < 0).
+to static instability (local Richardson number $<$ 0).
 %
 \end{itemize}
 
+TO BE CONTINUED.
 
-\paragraph{bldepth:} ~ \\
+\paragraph{BLDEPTH: Boundary layer depth calculation:} ~ \\
 %
 The oceanic planetary boundary layer depth, \texttt{hbl}, is determined as
 the shallowest depth where the bulk Richardson number is
@@ -262,50 +437,40 @@
 to grid points (caseA), so that conditional branches can be
 avoided in later subroutines.
 
-\paragraph{blmix:} ~ \\
-%
-Compute boundary layer mixing coefficients.
-Mixing coefficients within boundary layer depend on surface
-forcing and the magnitude and gradient of interior mixing below
-the boundary layer ("matching").
-%
-\begin{enumerate}
-%
-\item
-compute velocity scales at hbl
-%
-\item
-find the interior viscosities and derivatives at hbl
-%
-\item
-compute turbulent velocity scales on the interfaces
-%
-\item
-compute the dimensionless shape functions at the interfaces
-%
-\item
-compute boundary layer diffusivities at the interfaces
-%
-\item
-compute nonlocal transport term
-%
-\item
-find diffusivities at kbl-1 grid level
-%
-\end{enumerate}
+TO BE CONTINUED.
 
-\paragraph{kpp\_calc\_diff\_t/s, kpp\_calc\_visc:} ~  \\
+\paragraph{KPP\_CALC\_DIFF\_T/\_S, KPP\_CALC\_VISC:} ~  \\
 %
 Add contribution to net diffusivity/viscosity from 
 KPP diffusivity/viscosity.
 
-\paragraph{kpp\_transport\_t/s/ptr:} ~ \\
+TO BE CONTINUED.
+
+\paragraph{KPP\_TRANSPORT\_T/\_S/\_PTR:} ~ \\
 %
 Add non local KPP transport term (ghat) to diffusive
 temperature/salinity/passive tracer flux.
 The nonlocal transport term is nonzero only for scalars
 in unstable (convective) forcing conditions. 
 
+TO BE CONTINUED.
+
+\paragraph{Implicit time integration} ~ \\
+%
+TO BE CONTINUED.
+
+
+\paragraph{Penetration of shortwave radiation} ~ \\
+%
+TO BE CONTINUED.
+
+
+%----------------------------------------------------------------------
+
+\subsubsection{Flow chart
+\label{sec:pkg:kpp:flowchart}}
+
+
 {\footnotesize
 \begin{verbatim}
 
@@ -341,12 +506,8 @@
 
 Diagnostics output is available via the diagnostics package
 (see Section \ref{sec:pkg:diagnostics}).
-Available output fields are summarized in 
-Table \ref{tab:pkg:kpp:diagnostics}.
+Available output fields are summarized here:
 
-\begin{table}[h!]
-\label{tab:pkg:kpp:diagnostics}
-{\footnotesize
 \begin{verbatim}
 ------------------------------------------------------
  <-Name->|Levs|grid|<--  Units   -->|<- Tile (max=80c)
@@ -359,9 +520,6 @@
  KPPmld  |  1 |SM  |m               |Mixed layer depth, dT=.8degC density criterion
  KPPfrac |  1 |SM  |                |Short-wave flux fraction penetrating mixing layer
 \end{verbatim}
-}
-\caption{~}
-\end{table}
 
 %----------------------------------------------------------------------
 
@@ -374,3 +532,10 @@
 %----------------------------------------------------------------------
 
 \subsubsection{References}
+
+\subsubsection{Experiments and tutorials that use kpp}
+\label{sec:pkg:kpp:experiments}
+
+\begin{itemize}
+\item{Labrador Sea experiment, in lab\_sea verification directory }
+\end{itemize}
