--- manual/s_phys_pkgs/text/kpp.tex 2005/07/18 20:45:27 1.5 +++ manual/s_phys_pkgs/text/kpp.tex 2005/08/01 22:31:36 1.6 @@ -1,7 +1,376 @@ -\subsection{KPP Package: Ocean vertical mixing -- -the nonlocal K-profile parameterization scheme} +\subsection{KPP: Nonlocal K-Profile Parameterization for +Diapycnal Mixing} \label{sec:pkg:kpp} \begin{rawhtml} \end{rawhtml} + +Authors: Dimitris Menemenlis and Patrick Heimbach + +\subsubsection{Introduction +\label{sec:pkg:kpp:intro}} + +%---------------------------------------------------------------------- + +\subsubsection{KPP configuration and compiling} + +As with all MITgcm packages, KPP can be turned on or off at compile time +% +\begin{itemize} +% +\item +using the \texttt{packages.conf} file by adding \texttt{kpp} to it, +% +\item +or using \texttt{genmake2} adding +\texttt{-enable=kpp} or \texttt{-disable=kpp} switches +% +\end{itemize} +(see Section \ref{sect: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!] + \label{tab:pkg:kpp:cpp} + {\footnotesize + \begin{tabular}{|l|l|} + \hline + \textbf{CPP option} & \textbf{Description} \\ + \hline \hline + \texttt{\_KPP\_RL} & + ~ \\ + \texttt{FRUGAL\_KPP} & + ~ \\ + \texttt{KPP\_SMOOTH\_SHSQ} & + ~ \\ + \texttt{KPP\_SMOOTH\_DVSQ} & + ~ \\ + \texttt{KPP\_SMOOTH\_DENS} & + ~ \\ + \texttt{KPP\_SMOOTH\_VISC} & + ~ \\ + \texttt{KPP\_SMOOTH\_DIFF} & + ~ \\ + \texttt{KPP\_ESTIMATE\_UREF} & + ~ \\ + \texttt{INCLUDE\_DIAGNOSTICS\_INTERFACE\_CODE} & + ~ \\ + \texttt{KPP\_GHAT} & + ~ \\ + \texttt{EXCLUDE\_KPP\_SHEAR\_MIX} & + ~ \\ + \hline + \end{tabular} + } + \caption{~} +\end{table} + + + +%---------------------------------------------------------------------- + +\subsubsection{Run-time parameters +\label{sec:pkg:kpp:runtime}} + +Run-time parameters are set in files +\texttt{data.pkg} and \texttt{data.kpp} +which are read in \texttt{kpp\_readparms.F}. +Run-time parameters may be broken into 3 categories: +(i) switching on/off the package at runtime, +(ii) required MITgcm flags, +(iii) package flags and parameters. + +\paragraph{Enabling the package} +~ \\ +% +The KPP package is switched on at runtime by setting +\texttt{useKPP = .TRUE.} in \texttt{data.pkg}. + +\paragraph{Required MITgcm flags} +~ \\ +% +The following flags/parameters of the MITgcm dynamical +kernel need to be set in conjunction with KPP: + +\begin{tabular}{ll} +\texttt{implicitViscosity = .TRUE.} & enable implicit vertical viscosity \\ +\texttt{implicitDiffusion = .TRUE.} & enable implicit vertical diffusion \\ +\end{tabular} + + +\paragraph{Package flags and parameters} +~ \\ +% +\begin{table}[h!] + \label{tab:pkg:kpp:runtime_flags} + {\footnotesize + \begin{tabular}{|l|c|l|} + \hline + \textbf{Flag/parameter} & \textbf{default} & \textbf{Description} \\ + \hline \hline + \multicolumn{3}{|c|}{\textit{I/O related parameters} } \\ + \hline + kpp\_freq & \texttt{deltaTClock} & + Recomputation frequency for KPP fields \\ + kpp\_dumpFreq & \texttt{dumpFreq} & + Dump frequency of KPP field snapshots \\ + kpp\_taveFreq & \texttt{taveFreq} & + Averaging and dump frequency of KPP fields \\ + KPPmixingMaps & \texttt{.FALSE.} & + include KPP diagnostic maps in STDOUT \\ + KPPwriteState & \texttt{.FALSE.} & + write KPP state to file \\ + KPP\_ghatUseTotalDiffus & \texttt{.FALSE.} & + if \texttt{.T.} compute non-local term using total vertical diffusivity \\ + ~ & ~ & + if \texttt{.F.} use KPP vertical diffusivity \\ + \hline + \multicolumn{3}{|c|}{\textit{Genral KPP parameters} } \\ + \hline + minKPPhbl & \texttt{delRc(1)} & + Minimum boundary layer depth \\ + epsilon & 0.1 & + nondimensional extent of the surface layer \\ + vonk & 0.4 & + von Karman constant \\ + dB\_dz & 5.2E-5 1/s$^2$ & + maximum dB/dz in mixed layer hMix \\ + concs & 98.96 & + ~ \\ + concv & 1.8 & + ~ \\ + \hline + \multicolumn{3}{|c|}{\textit{Boundary layer parameters (S/R \texttt{bldepth})} } \\ + \hline + Ricr & 0.3 & + critical bulk Richardson number \\ + cekman & 0.7 & + coefficient for Ekman depth \\ + cmonob & 1.0 & + coefficient for Monin-Obukhov depth \\ + concv & 1.8 & + ratio of interior to entrainment depth buoyancy frequency \\ + hbf & 1.0 & + fraction of depth to which absorbed solar radiation contributes \\ + ~ & ~ & + to surface buoyancy forcing \\ + Vtc & \texttt{~} & + non-dim. coeff. for velocity scale of turbulant velocity shear \\ + ~ & ~ & + ( = function of concv,concs,epsilon,vonk,Ricr) \\ + \hline + \multicolumn{3}{|c|}{\textit{Boundary layer mixing parameters (S/R \texttt{blmix})} } \\ + \hline + cstar & 10. & + proportionality coefficient for nonlocal transport \\ + cg & ~ & + non-dimensional coefficient for counter-gradient term \\ + ~ & ~ & + ( = function of cstar,vonk,concs,epsilon) \\ + \hline + \multicolumn{3}{|c|}{\textit{Interior mixing parameters (S/R \texttt{Ri\_iwmix})} } \\ + \hline + Riinfty & 0.7 & + gradient Richardson number limit for shear instability \\ + BVDQcon & -0.2E-4 1/s$^2$ & + Brunt-V\"ai\"sal\"a squared \\ + difm0 & 0.005 m$^2$/s & + viscosity max. due to shear instability \\ + difs0 & 0.005 m$^2$/s & + tracer diffusivity max. due to shear instability \\ + dift0 & 0.005 m$^2$/s & + heat diffusivity max. due to shear instability \\ + difmcon & 0.1 & + viscosity due to convective instability \\ + difscon & 0.1 & + tracer diffusivity due to convective instability \\ + diftcon & 0.1 & + heat diffusivity due to convective instability \\ + \hline + \multicolumn{3}{|c|}{\textit{Double-diffusive mixing parameters (S/R \texttt{ddmix})} } \\ + \hline + Rrho0 & not used & + limit for double diffusive density ratio \\ + dsfmax & not used & + maximum diffusivity in case of salt fingering \\ + \hline + \hline + \end{tabular} + } + \caption{~} +\end{table} + + + +%---------------------------------------------------------------------- + +\subsubsection{Equations +\label{sec:pkg:kpp:equations}} + +%---------------------------------------------------------------------- + +\subsubsection{Key subroutines +\label{sec:pkg:kpp:subroutines}} + +\paragraph{kpp\_calc:} Top-level routine. \\ +~ + +\paragraph{kpp\_mix:} Intermediate-level routine \\ +~ + +\paragraph{ri\_iwmix:} ~ \\ +% +Compute interior viscosity and diffusivity coefficients due to +% +\begin{itemize} +% +\item +shear instability (dependent on a local gradient Richardson number), +% +\item +to background internal wave activity, and +% +\item +to static instability (local Richardson number < 0). +% +\end{itemize} + + +\paragraph{bldepth:} ~ \\ +% +The oceanic planetary boundary layer depth, \texttt{hbl}, is determined as +the shallowest depth where the bulk Richardson number is +equal to the critical value, \texttt{Ricr}. + +Bulk Richardson numbers are evaluated by computing velocity and +buoyancy differences between values at zgrid(kl) < 0 and surface +reference values. +In this configuration, the reference values are equal to the +values in the surface layer. +When using a very fine vertical grid, these values should be +computed as the vertical average of velocity and buoyancy from +the surface down to epsilon*zgrid(kl). + +When the bulk Richardson number at k exceeds Ricr, hbl is +linearly interpolated between grid levels zgrid(k) and zgrid(k-1). + +The water column and the surface forcing are diagnosed for +stable/ustable forcing conditions, and where hbl is relative +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} + +\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:} ~ \\ +% +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. + +{\footnotesize +\begin{verbatim} + +C !CALLING SEQUENCE: +c ... +c kpp_calc (TOP LEVEL ROUTINE) +c | +c |-- statekpp: o compute all EOS/density-related arrays +c | o uses S/R FIND_ALPHA, FIND_BETA, FIND_RHO +c | +c |-- kppmix +c | |--- ri_iwmix (compute interior mixing coefficients due to constant +c | | internal wave activity, static instability, +c | | and local shear instability). +c | | +c | |--- bldepth (diagnose boundary layer depth) +c | | +c | |--- blmix (compute boundary layer diffusivities) +c | | +c | |--- enhance (enhance diffusivity at interface kbl - 1) +c | o +c | +c |-- swfrac +c o + +\end{verbatim} +} + +%---------------------------------------------------------------------- + +\subsubsection{KPP diagnostics +\label{sec:pkg:kpp:diagnostics}} + +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}. + +\begin{table}[h!] +\label{tab:pkg:kpp:diagnostics} +{\footnotesize +\begin{verbatim} +------------------------------------------------------ + <-Name->|Levs|grid|<-- Units -->|<- Tile (max=80c) +------------------------------------------------------ + KPPviscA| 23 |SM |m^2/s |KPP vertical eddy viscosity coefficient + KPPdiffS| 23 |SM |m^2/s |Vertical diffusion coefficient for salt & tracers + KPPdiffT| 23 |SM |m^2/s |Vertical diffusion coefficient for heat + KPPghat | 23 |SM |s/m^2 |Nonlocal transport coefficient + KPPhbl | 1 |SM |m |KPP boundary layer depth, bulk Ri criterion + 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} + +%---------------------------------------------------------------------- + +\subsubsection{Reference experiments} + +lab\_sea: + +natl\_box: + +%---------------------------------------------------------------------- + +\subsubsection{References}