--- manual/s_phys_pkgs/text/kpp.tex 2005/08/02 22:26:58 1.7 +++ manual/s_phys_pkgs/text/kpp.tex 2010/08/30 23:09:21 1.11 @@ -59,15 +59,26 @@ (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}), +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. +and boundary-layer/mixed-layer depths +(\ref{sec:pkg:kpp:diagnostics}). %---------------------------------------------------------------------- @@ -85,14 +96,22 @@ 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 @@ -167,7 +186,7 @@ runtime flags that are set in \texttt{data.pkg}, and their default values. -\begin{table}[h!] +\begin{table}[!ht] \centering \label{tab:pkg:kpp:runtime_flags} {\footnotesize @@ -271,14 +290,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 +368,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 +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 @@ -404,52 +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. -\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} @@ -485,13 +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!] -\centering -\label{tab:pkg:kpp:diagnostics} -{\footnotesize \begin{verbatim} ------------------------------------------------------ <-Name->|Levs|grid|<-- Units -->|<- Tile (max=80c) @@ -504,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} %---------------------------------------------------------------------- @@ -520,3 +533,9 @@ \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}