Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_ZDF.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_ZDF.tex	(revision 11614)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_ZDF.tex	(revision 11954)
@@ -28,5 +28,6 @@
 \clearpage
 
-%gm% Add here a small introduction to ZDF and naming of the different physics (similar to what have been written for TRA and DYN.
+\cmtgm{ Add here a small introduction to ZDF and naming of the different physics
+(similar to what have been written for TRA and DYN).}
 
 %% =================================================================================================
@@ -248,5 +249,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_mixing_length}
+  \includegraphics[width=0.66\textwidth]{ZDF_mixing_length}
   \caption[Mixing length computation]{Illustration of the mixing length computation}
   \label{fig:ZDF_mixing_length}
@@ -533,6 +534,9 @@
  in \citet{reffray.guillaume.ea_GMD15} for the \NEMO\ model.
 
-%% =================================================================================================
-\subsection[OSM: OSMosis boundary layer scheme (\forcode{ln_zdfosm})]{OSM: OSMosis boundary layer scheme (\protect\np{ln_zdfosm}{ln\_zdfosm})}
+% -------------------------------------------------------------------------------------------------------------
+%        OSM OSMOSIS BL Scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection[OSM: OSMOSIS boundary layer scheme (\forcode{ln_zdfosm = .true.})]
+{OSM: OSMOSIS boundary layer scheme (\protect\np{ln_zdfosm}{ln\_zdfosm})}
 \label{subsec:ZDF_osm}
 
@@ -543,5 +547,207 @@
 \end{listing}
 
-The OSMOSIS turbulent closure scheme is based on......   TBC
+%--------------------------------------------------------------------------------------------------------------
+\paragraph{Namelist choices}
+Most of the namelist options refer to how to specify the Stokes
+surface drift and penetration depth. There are three options:
+\begin{description}
+  \item \protect\np[=0]{nn_osm_wave}{nn\_osm\_wave} Default value in \texttt{namelist\_ref}. In this case the Stokes drift is
+      assumed to be parallel to the surface wind stress, with
+      magnitude consistent with a constant turbulent Langmuir number
+    $\mathrm{La}_t=$ \protect\np{rn_m_la} {rn\_m\_la} i.e.\
+    $u_{s0}=\tau/(\mathrm{La}_t^2\rho_0)$.  Default value of
+    \protect\np{rn_m_la}{rn\_m\_la} is 0.3. The Stokes penetration
+      depth $\delta = $ \protect\np{rn_osm_dstokes}{rn\_osm\_dstokes}; this has default value
+      of 5~m.
+
+  \item \protect\np[=1]{nn_osm_wave}{nn\_osm\_wave} In this case the Stokes drift is
+      assumed to be parallel to the surface wind stress, with
+      magnitude as in the classical Pierson-Moskowitz wind-sea
+      spectrum.  Significant wave height and
+      wave-mean period taken from this spectrum are used to calculate the Stokes penetration
+      depth, following the approach set out in  \citet{breivik.janssen.ea_JPO14}.
+
+    \item \protect\np[=2]{nn_osm_wave}{nn\_osm\_wave} In this case the Stokes drift is
+      taken from  ECMWF wave model output, though only the component parallel
+      to the wind stress is retained. Significant wave height and
+      wave-mean period from ECMWF wave model output are used to calculate the Stokes penetration
+      depth, again following \citet{breivik.janssen.ea_JPO14}.
+
+    \end{description}
+
+    Others refer to the treatment of diffusion and viscosity beneath
+    the surface boundary layer:
+\begin{description}
+   \item \protect\np{ln_kpprimix} {ln\_kpprimix}  Default is \np{.true.}. Switches on KPP-style Ri \#-dependent
+     mixing below the surface boundary layer. If this is set
+     \texttt{.true.}  the following variable settings are honoured:
+    \item \protect\np{rn_riinfty}{rn\_riinfty} Critical value of local Ri \# below which
+      shear instability increases vertical mixing from background value.
+    \item \protect\np{rn_difri} {rn\_difri} Maximum value of Ri \#-dependent mixing at $\mathrm{Ri}=0$.
+    \item \protect\np{ln_convmix}{ln\_convmix} If \texttt{.true.} then, where water column is unstable, specify
+       diffusivity equal to \protect\np{rn_dif_conv}{rn\_dif\_conv} (default value is 1 m~s$^{-2}$).
+ \end{description}
+ Diagnostic output is controlled by:
+  \begin{description}
+    \item \protect\np{ln_dia_osm}{ln\_dia\_osm} Default is \np{.false.}; allows XIOS output of OSMOSIS internal fields.
+  \end{description}
+Obsolete namelist parameters include:
+\begin{description}
+   \item \protect\np{ln_use_osm_la}\np{ln\_use\_osm\_la} With \protect\np[=0]{nn_osm_wave}{nn\_osm\_wave},
+      \protect\np{rn_osm_dstokes} {rn\_osm\_dstokes} is always used to specify the Stokes
+      penetration depth.
+   \item \protect\np{nn_ave} {nn\_ave} Choice of averaging method for KPP-style Ri \#
+      mixing. Not taken account of.
+   \item \protect\np{rn_osm_hbl0} {rn\_osm\_hbl0} Depth of initial boundary layer is now set
+     by a density criterion similar to that used in calculating \emph{hmlp} (output as \texttt{mldr10\_1}) in \mdl{zdfmxl}.
+\end{description}
+
+\subsubsection{Summary}
+Much of the time the turbulent motions in the ocean surface boundary
+layer (OSBL) are not given by
+classical shear turbulence. Instead they are in a regime known as
+`Langmuir turbulence',  dominated by an
+interaction between the currents and the Stokes drift of the surface waves \citep[e.g.][]{mcwilliams.ea_JFM97}.
+This regime is characterised by strong vertical turbulent motion, and appears when the surface Stokes drift $u_{s0}$ is much greater than the friction velocity $u_{\ast}$. More specifically Langmuir turbulence is thought to be crucial where the turbulent Langmuir number $\mathrm{La}_{t}=(u_{\ast}/u_{s0}) > 0.4$.
+
+The OSMOSIS model is fundamentally based on results of Large Eddy
+Simulations (LES) of Langmuir turbulence and aims to fully describe
+this Langmuir regime. The description in this section is of necessity incomplete and further details are available in Grant. A (2019); in prep.
+
+The OSMOSIS turbulent closure scheme is a similarity-scale scheme in
+the same spirit as the K-profile
+parameterization (KPP) scheme of \citet{large.ea_RG97}.
+A specified shape of diffusivity, scaled by the (OSBL) depth
+$h_{\mathrm{BL}}$ and a turbulent velocity scale, is imposed throughout the
+boundary layer
+$-h_{\mathrm{BL}}<z<\eta$. The turbulent closure model
+also includes fluxes of tracers and momentum that are``non-local'' (independent of the local property gradient).
+
+Rather than the OSBL
+depth being diagnosed in terms of a bulk Richardson number criterion,
+as in KPP, it is set by a prognostic equation that is informed by
+energy budget considerations reminiscent of the classical mixed layer
+models of \citet{kraus.turner_tellus67}.
+The model also includes an explicit parametrization of the structure
+of the pycnocline (the stratified region at the bottom of the OSBL).
+
+Presently, mixing below the OSBL is handled by the Richardson
+number-dependent mixing scheme used in \citet{large.ea_RG97}.
+
+Convective parameterizations such as described in \ref{sec:ZDF_conv}
+below should not be used with the OSMOSIS-OBL model: instabilities
+within the OSBL are part of the model, while instabilities below the
+ML are handled by the Ri \# dependent scheme.
+
+\subsubsection{Depth and velocity scales}
+The model supposes a boundary layer of thickness $h_{\mathrm{bl}}$ enclosing a well-mixed layer of thickness $h_{\mathrm{ml}}$ and a relatively thin pycnocline at the base of thickness $\Delta h$; Fig.~\ref{fig: OSBL_structure} shows typical (a) buoyancy structure and (b) turbulent buoyancy flux profile for the unstable boundary layer (losing buoyancy at the surface; e.g.\ cooling).
+\begin{figure}[!t]
+  \begin{center}
+    %\includegraphics[width=0.7\textwidth]{ZDF_OSM_structure_of_OSBL}
+    \caption{
+      \protect\label{fig: OSBL_structure}
+     The structure of the entraining  boundary layer. (a) Mean buoyancy profile. (b) Profile of the buoyancy flux.
+    }
+  \end{center}
+\end{figure}
+The pycnocline in the OSMOSIS scheme is assumed to have a finite thickness, and may include a number of model levels. This means that the OSMOSIS scheme must parametrize both the thickness of the pycnocline, and the turbulent fluxes within the pycnocline.
+
+Consideration of the power input by wind acting on the Stokes drift suggests that the Langmuir turbulence has velocity scale:
+\begin{equation}\label{eq:w_La}
+w_{*L}= \left(u_*^2 u_{s\,0}\right)^{1/3};
+\end{equation}
+but at times the Stokes drift may be weak due to e.g.\ ice cover, short fetch, misalignment with the surface stress, etc.\ so  a composite velocity scale is assumed for the stable (warming) boundary layer:
+\begin{equation}\label{eq:composite-nu}
+  \nu_{\ast}= \left\{ u_*^3 \left[1-\exp(-.5 \mathrm{La}_t^2)\right]+w_{*L}^3\right\}^{1/3}.
+\end{equation}
+For the unstable boundary layer this is merged with the standard convective velocity scale $w_{*C}=\left(\overline{w^\prime b^\prime}_0 \,h_\mathrm{ml}\right)^{1/3}$, where $\overline{w^\prime b^\prime}_0$ is the upwards surface buoyancy flux, to give:
+\begin{equation}\label{eq:vel-scale-unstable}
+\omega_* = \left(\nu_*^3 + 0.5 w_{*C}^3\right)^{1/3}.
+\end{equation}
+
+\subsubsection{The flux gradient model}
+The flux-gradient relationships used in the OSMOSIS scheme take the form:
+%
+\begin{equation}\label{eq:flux-grad-gen}
+\overline{w^\prime\chi^\prime}=-K\frac{\partial\overline{\chi}}{\partial z} + N_{\chi,s} +N_{\chi,b} +N_{\chi,t},
+\end{equation}
+%
+where $\chi$ is a general variable and $N_{\chi,s}, N_{\chi,b} \mathrm{and} N_{\chi,t}$  are the non-gradient terms, and represent the effects of the different terms in the turbulent flux-budget on the transport of $\chi$. $N_{\chi,s}$ represents the effects that the Stokes shear has on the transport of $\chi$, $N_{\chi,b}$  the effect of buoyancy, and $N_{\chi,t}$ the effect of the turbulent transport.  The same general form for the flux-gradient relationship is used to parametrize the transports of momentum, heat and salinity.
+
+In terms of the non-dimensionalized depth variables
+%
+\begin{equation}\label{eq:sigma}
+\sigma_{\mathrm{ml}}= -z/h_{\mathrm{ml}}; \;\sigma_{\mathrm{bl}}= -z/h_{\mathrm{bl}},
+\end{equation}
+%
+in unstable conditions the eddy diffusivity ($K_d$) and eddy viscosity ($K_\nu$) profiles are parametrized as:
+%
+\begin{align}\label{eq:diff-unstable}
+K_d=&0.8\, \omega_*\, h_{\mathrm{ml}} \, \sigma_{\mathrm{ml}} \left(1-\beta_d \sigma_{\mathrm{ml}}\right)^{3/2}
+\\\label{eq:visc-unstable}
+K_\nu =& 0.3\, \omega_* \,h_{\mathrm{ml}}\, \sigma_{\mathrm{ml}} \left(1-\beta_\nu \sigma_{\mathrm{ml}}\right)\left(1-\tfrac{1}{2}\sigma_{\mathrm{ml}}^2\right)
+\end{align}
+%
+where $\beta_d$ and $\beta_\nu$ are parameters that are determined by matching Eqs \ref{eq:diff-unstable} and \ref{eq:visc-unstable} to the eddy diffusivity and viscosity at the base of the well-mixed layer, given by
+%
+\begin{equation}\label{eq:diff-wml-base}
+K_{d,\mathrm{ml}}=K_{\nu,\mathrm{ml}}=\,0.16\,\omega_* \Delta h.
+\end{equation}
+%
+For stable conditions the eddy diffusivity/viscosity profiles are given by:
+%
+\begin{align}\label{diff-stable}
+K_d= & 0.75\,\, \nu_*\, h_{\mathrm{ml}}\,\,  \exp\left[-2.8 \left(h_{\mathrm{bl}}/L_L\right)^2\right]\sigma_{\mathrm{ml}} \left(1-\sigma_{\mathrm{ml}}\right)^{3/2} \\\label{eq:visc-stable}
+K_\nu = & 0.375\,\,  \nu_*\, h_{\mathrm{ml}} \,\, \exp\left[-2.8 \left(h_{\mathrm{bl}}/L_L\right)^2\right] \sigma_{\mathrm{ml}} \left(1-\sigma_{\mathrm{ml}}\right)\left(1-\tfrac{1}{2}\sigma_{\mathrm{ml}}^2\right).
+\end{align}
+%
+The shape of the eddy viscosity and diffusivity profiles is the same as the shape in the unstable OSBL. The eddy diffusivity/viscosity depends on the stability parameter $h_{\mathrm{bl}}/{L_L}$ where $ L_L$ is analogous to the Obukhov length, but for Langmuir turbulence:
+\begin{equation}\label{eq:L_L}
+  L_L=-w_{*L}^3/\left<\overline{w^\prime b^\prime}\right>_L,
+\end{equation}
+with the mean turbulent buoyancy flux averaged over the boundary layer given in terms of its surface value $\overline{w^\prime b^\prime}_0$ and (downwards) )solar irradiance $I(z)$ by
+\begin{equation} \label{eq:stable-av-buoy-flux}
+\left<\overline{w^\prime b^\prime}\right>_L = \tfrac{1}{2} {\overline{w^\prime b^\prime}}_0-g\alpha_E\left[\tfrac{1}{2}(I(0)+I(-h))-\left<I\right>\right].
+\end{equation}
+%
+In unstable conditions the eddy diffusivity and viscosity depend on stability through the velocity scale $\omega_*$, which depends on the two velocity scales $\nu_*$ and $w_{*C}$.
+
+Details of the non-gradient terms in \eqref{eq:flux-grad-gen} and of the fluxes within the pycnocline $-h_{\mathrm{bl}}<z<h_{\mathrm{ml}}$ can be found in Grant (2019).
+
+\subsubsection{Evolution of the boundary layer depth}
+
+The prognostic equation for the depth of the neutral/unstable boundary layer is given by \citep{grant+etal18},
+
+\begin{equation} \label{eq:dhdt-unstable}
+%\frac{\partial h_\mathrm{bl}}{\partial t} + \mathbf{U}_b\cdot\nabla h_\mathrm{bl}= W_b - \frac{{\overline{w^\prime b^\prime}}_\mathrm{ent}}{\Delta B_\mathrm{bl}}
+\frac{\partial h_\mathrm{bl}}{\partial t} = W_b - \frac{{\overline{w^\prime b^\prime}}_\mathrm{ent}}{\Delta B_\mathrm{bl}}
+\end{equation}
+where $h_\mathrm{bl}$ is the horizontally-varying depth of the OSBL,
+$\mathbf{U}_b$ and $W_b$ are the mean horizontal and vertical
+velocities at the base of the OSBL, ${\overline{w^\prime
+    b^\prime}}_\mathrm{ent}$ is the buoyancy flux due to entrainment
+and $\Delta B_\mathrm{bl}$ is the difference between the buoyancy
+averaged over the depth of the OSBL (i.e.\ including the ML and
+pycnocline) and the buoyancy just below the base of the OSBL. This
+equation for the case when the pycnocline has a finite thickness,
+based on the potential energy budget of the OSBL, is the leading term
+\citep{grant+etal18} of a generalization of that used in mixed-layer
+models e.g.\ \citet{kraus.turner_tellus67}, in which the thickness of the pycnocline is taken to be zero.
+
+The entrainment flux for the combination of convective and Langmuir turbulence is given by
+\begin{equation} \label{eq:entrain-flux}
+  {\overline{w^\prime b^\prime}}_\mathrm{ent} = -\alpha_{\mathrm{B}} {\overline{w^\prime b^\prime}}_0 - \alpha_{\mathrm{S}} \frac{u_*^3}{h_{\mathrm{ml}}}
+  + G\left(\delta/h_{\mathrm{ml}} \right)\left[\alpha_{\mathrm{S}}e^{-1.5\, \mathrm{La}_t}-\alpha_{\mathrm{L}} \frac{w_{\mathrm{*L}}^3}{h_{\mathrm{ml}}}\right]
+\end{equation}
+where the factor $G\equiv 1 - \mathrm{e}^ {-25\delta/h_{\mathrm{bl}}}(1-4\delta/h_{\mathrm{bl}})$ models the lesser efficiency of Langmuir mixing when the boundary-layer depth is much greater than the Stokes depth, and $\alpha_{\mathrm{B}}$, $\alpha_{S}$  and $\alpha_{\mathrm{L}}$ depend on the ratio of the appropriate eddy turnover time to the inertial timescale $f^{-1}$. Results from the LES suggest $\alpha_{\mathrm{B}}=0.18 F(fh_{\mathrm{bl}}/w_{*C})$, $\alpha_{S}=0.15 F(fh_{\mathrm{bl}}/u_*$  and $\alpha_{\mathrm{L}}=0.035 F(fh_{\mathrm{bl}}/u_{*L})$, where $F(x)\equiv\tanh(x^{-1})^{0.69}$.
+
+For the stable boundary layer, the equation for the depth of the OSBL is:
+
+\begin{equation}\label{eq:dhdt-stable}
+\max\left(\Delta B_{bl},\frac{w_{*L}^2}{h_\mathrm{bl}}\right)\frac{\partial h_\mathrm{bl}}{\partial t} = \left(0.06 + 0.52\,\frac{ h_\mathrm{bl}}{L_L}\right) \frac{w_{*L}^3}{h_\mathrm{bl}} +\left<\overline{w^\prime b^\prime}\right>_L.
+\end{equation}
+
+Equation. \ref{eq:dhdt-unstable} always leads to the depth of the entraining OSBL increasing (ignoring the effect of the mean vertical motion), but the change in the thickness of the stable OSBL given by Eq. \ref{eq:dhdt-stable} can be positive or negative, depending on the magnitudes of $\left<\overline{w^\prime b^\prime}\right>_L$ and $h_\mathrm{bl}/L_L$. The rate at which the depth of the OSBL can decrease is limited by choosing an effective buoyancy $w_{*L}^2/h_\mathrm{bl}$, in place of $\Delta B_{bl}$ which will be $\approx 0$ for the collapsing OSBL.
+
 
 %% =================================================================================================
@@ -551,5 +757,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ZDF_TKE_time_scheme}
+  \includegraphics[width=0.66\textwidth]{ZDF_TKE_time_scheme}
   \caption[Subgrid kinetic energy integration in GLS and TKE schemes]{
     Illustration of the subgrid kinetic energy integration in GLS and TKE schemes and
@@ -663,5 +869,5 @@
 \begin{figure}[!htb]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_npc}
+  \includegraphics[width=0.66\textwidth]{ZDF_npc}
   \caption[Unstable density profile treated by the non penetrative convective adjustment algorithm]{
     Example of an unstable density profile treated by
@@ -808,5 +1014,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_zdfddm}
+  \includegraphics[width=0.66\textwidth]{ZDF_ddm}
   \caption[Diapycnal diffusivities for temperature and salt in regions of salt fingering and
   diffusive convection]{
@@ -1286,5 +1492,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ZDF_zad_Aimp_coeff}
+  \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_coeff}
   \caption[Partitioning coefficient used to partition vertical velocities into parts]{
     The value of the partitioning coefficient (\cf) used to partition vertical velocities into
@@ -1326,5 +1532,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ZDF_zad_Aimp_overflow_frames}
+  \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_overflow_frames}
   \caption[OVERFLOW: time-series of temperature vertical cross-sections]{
     A time-series of temperature vertical cross-sections for the OVERFLOW test case.
@@ -1406,5 +1612,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ZDF_zad_Aimp_overflow_all_rdt}
+  \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_overflow_all_rdt}
   \caption[OVERFLOW: sample temperature vertical cross-sections from mid- and end-run]{
     Sample temperature vertical cross-sections from mid- and end-run using
@@ -1419,5 +1625,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ZDF_zad_Aimp_maxCf}
+  \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_maxCf}
   \caption[OVERFLOW: maximum partitioning coefficient during a series of test runs]{
     The maximum partitioning coefficient during a series of test runs with
@@ -1430,5 +1636,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ZDF_zad_Aimp_maxCf_loc}
+  \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_maxCf_loc}
   \caption[OVERFLOW: maximum partitioning coefficient for the case overlaid]{
     The maximum partitioning coefficient for the \forcode{nn_rdt=10.0} case overlaid with
@@ -1437,5 +1643,5 @@
 \end{figure}
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
