--- manual/s_phys_pkgs/text/kpp.tex	2005/08/02 22:26:58	1.7
+++ manual/s_phys_pkgs/text/kpp.tex	2005/08/03 04:00:31	1.8
@@ -59,6 +59,15 @@
 (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
@@ -85,6 +94,14 @@
 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}).
 
@@ -271,14 +288,20 @@
 
 %----------------------------------------------------------------------
 
-\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}.
 
-\paragraph{Mixing in the boundary layer} ~ \\
+\paragraph{KPP\_CALC:} Top-level routine. \\
+~
+
+\paragraph{KPP\_MIX:} Intermediate-level routine \\
+~
+
+\paragraph{BLMIX: Mixing in the boundary layer} ~ \\
 %
 ~
 
@@ -343,27 +366,34 @@
 
 \end{itemize}
 
-
-\paragraph{Mixing in the interior} ~ \\
+In practice, the routine peforms the following tasks:
 %
-~
-
-\paragraph{Implicit time integration} ~ \\
+\begin{enumerate}
 %
-~
-
-%----------------------------------------------------------------------
-
-\subsubsection{Key subroutines
-\label{sec:pkg:kpp:subroutines}}
-
-\paragraph{kpp\_calc:} Top-level routine. \\
-~
-
-\paragraph{kpp\_mix:} Intermediate-level routine \\
-~
+\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:} ~ \\
+\paragraph{RI\_IWMIX: Mixing in the interior} ~ \\
 %
 Compute interior viscosity and diffusivity coefficients due to
 %
@@ -376,12 +406,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
@@ -404,52 +435,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. 
 
-\paragraph{Flow chart:} ~ \\
+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}