Merge pull request #1510 from ESMG/esmg-docs

Esmg docs

docs/conf.py

@@ -159,7 +159,7 @@ def latexPassthru(name, rawtext, text, lineno, inliner, options={}, content=[]):
 
 # General information about the project.
 project = u'MOM6'
-copyright = u'2017-2020, MOM6 developers'
+copyright = u'2017-2021, MOM6 developers'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/parameterizations_vertical.rst

@@ -14,9 +14,13 @@ K-profile parameterization (KPP)
 Energetic Planetary Boundary Layer (ePBL)
   A energetically constrained boundary layer scheme following :cite:`reichl2018`. Implemented in MOM_energetic_PBL.
 
+   :ref:`EPBL`
+
 Bulk mixed layer (BML)
   A 2-layer bulk mixed layer used in pure-isopycnal model. Implemented in MOM_bulk_mixed_layer.
 
+   :ref:`BML`
+
 Interior and bottom-driven mixing
 ---------------------------------
 

docs/zotero.bib

@@ -2684,3 +2684,57 @@ @techreport{griffies2015a
 	pages = {98 pp},
 	institution = {NOAA GFDL}
 }
+
+@inbook{niiler1977,
+	author = {P. P. Niiler and E. B. Kraus},
+	chapter = {One-dimesional models of the upper ocean},
+	title = {Modelling and Prediction of the Upper Layers of the Ocean},
+	year = {1977},
+	editor = {E. B. Kraus},
+	publisher = {Pergamon Press}
+}
+
+@article{oberhuber1993,
+	doi = {10.1175/1520-0485(1993)023<0830:sotacw>2.0.co;2},
+	year = 1993,
+	publisher = {American Meteorological Society},
+	volume = {23},
+	number = {5},
+	pages = {830--845},
+	author = {J. M. Oberhuber},
+	title = {Simulation of the Atlantic Circulation with a Coupled Sea Ice-Mixed Layer-Isopycnal General Circulation Model. Part {II}: Model Experiment},
+	journal = {J. Phys. Oceanography}
+}
+
+@techreport{muller2003,
+	doi = {10.21236/ada618366},
+	year = 2003,
+	publisher = {Defense Technical Information Center},
+	author = {P. Muller},
+	institution = {School of Ocean and Earth Science and Technology},
+	title = {A{\textquotesingle}ha Huliko{\textquotesingle}a Workshop Series}
+}
+
+@article{wang2003,
+	doi = {10.1029/2003gl017869},
+	year = 2003,
+	publisher = {American Geophysical Union ({AGU})},
+	volume = {30},
+	number = {18},
+	author = {D. Wang},
+	title = {Entrainment laws and a bulk mixed layer model of rotating convection derived from large-eddy simulations},
+	journal = {Geophys. Res. Lett.}
+}
+
+@article{kraus1967,
+	doi = {10.3402/tellusa.v19i1.9753},
+	year = 1967,
+	publisher = {Informa {UK} Limited},
+	volume = {19},
+	number = {1},
+	pages = {98--106},
+	author = {E. B. Kraus and J. S. Turner},
+	title = {A one-dimensional model of the seasonal thermocline {II}. The general theory and its consequences},
+	journal = {Tellus}
+}
+

src/parameterizations/vertical/MOM_bulk_mixed_layer.F90

@@ -155,36 +155,8 @@ module MOM_bulk_mixed_layer
 
 contains
 
-!>    This subroutine partially steps the bulk mixed layer model.
-!!  The following processes are executed, in the order listed.
-!!    1. Undergo convective adjustment into mixed layer.
-!!    2. Apply surface heating and cooling.
-!!    3. Starting from the top, entrain whatever fluid the TKE budget
-!!       permits.  Penetrating shortwave radiation is also applied at
-!!      this point.
-!!    4. If there is any unentrained fluid that was formerly in the
-!!      mixed layer, detrain this fluid into the buffer layer.  This
-!!     is equivalent to the mixed layer detraining to the Monin-
-!!       Obukhov depth.
-!!    5. Divide the fluid in the mixed layer evenly into CS%nkml pieces.
-!!    6. Split the buffer layer if appropriate.
-!! Layers 1 to nkml are the mixed layer, nkml+1 to nkml+nkbl are the
-!! buffer layers. The results of this subroutine are mathematically
-!! identical if there are multiple pieces of the mixed layer with
-!! the same density or if there is just a single layer. There is no
-!! stability limit on the time step.
-!!
-!!   The key parameters for the mixed layer are found in the control structure.
-!! These include mstar, nstar, nstar2, pen_SW_frac, pen_SW_scale, and TKE_decay.
-!!   For the Oberhuber (1993) mixed layer, the values of these are:
-!!      pen_SW_frac = 0.42, pen_SW_scale = 15.0 m, mstar = 1.25,
-!!      nstar = 1, TKE_decay = 2.5, conv_decay = 0.5
-!!  TKE_decay is 1/kappa in eq. 28 of Oberhuber (1993), while conv_decay is 1/mu.
-!!  Conv_decay has been eliminated in favor of the well-calibrated form for the
-!!  efficiency of penetrating convection from Wang (2003).
-!!    For a traditional Kraus-Turner mixed layer, the values are:
-!!      pen_SW_frac = 0.0, pen_SW_scale = 0.0 m, mstar = 1.25,
-!!      nstar = 0.4, TKE_decay = 0.0, conv_decay = 0.0
+!> This subroutine partially steps the bulk mixed layer model.
+!! See \ref BML for more details.
 subroutine bulkmixedlayer(h_3d, u_3d, v_3d, tv, fluxes, dt, ea, eb, G, GV, US, CS, &
                           optics, Hml, aggregate_FW_forcing, dt_diag, last_call)
   type(ocean_grid_type),      intent(inout) :: G      !< The ocean's grid structure.
@@ -3708,16 +3680,15 @@ end function EF4
 !!
 !!   This file contains the subroutine (bulkmixedlayer) that
 !! implements a Kraus-Turner-like bulk mixed layer, based on the work
-!! of various people, as described in the review paper by Niiler and
-!! Kraus (1979), with particular attention to the form proposed by
-!! Oberhuber (JPO, 1993, 808-829), with an extension to a refied bulk
-!! mixed layer as described in Hallberg (Aha Huliko'a, 2003).  The
-!! physical processes portrayed in this subroutine include convective
-!! adjustment and mixed layer entrainment and detrainment.
-!! Penetrating shortwave radiation and an exponential decay of TKE
-!! fluxes are also supported by this subroutine.  Several constants
+!! of various people, as described in the review paper by \cite Niiler1977,
+!! with particular attention to the form proposed by \cite Oberhuber1993,
+!! with an extension to a refined bulk mixed layer as described in
+!! Hallberg (\cite muller2003). The physical processes portrayed in
+!! this subroutine include convective adjustment and mixed layer entrainment
+!! and detrainment. Penetrating shortwave radiation and an exponential decay
+!! of TKE fluxes are also supported by this subroutine.  Several constants
 !! can alternately be set to give a traditional Kraus-Turner mixed
 !! layer scheme, although that is not the preferred option.  The
-!! physical processes and arguments are described in detail below.
+!! physical processes and arguments are described in detail in \ref BML.
 
 end module MOM_bulk_mixed_layer

src/parameterizations/vertical/MOM_energetic_PBL.F90

@@ -1030,7 +1030,7 @@ subroutine ePBL_column(h, u, v, T0, S0, dSV_dT, dSV_dS, TKE_forcing, B_flux, abs
         dt_h = (GV%Z_to_H**2*dt) / max(0.5*(h(k-1)+h(k)), 1e-15*h_sum)
 
         !   This tests whether the layers above and below this interface are in
-        ! a convetively stable configuration, without considering any effects of
+        ! a convectively stable configuration, without considering any effects of
         ! mixing at higher interfaces.  It is an approximation to the more
         ! complete test dPEc_dKd_Kd0 >= 0.0, that would include the effects of
         ! mixing across interface K-1.  The dT_to_dColHt here are effectively
@@ -2079,7 +2079,7 @@ subroutine energetic_PBL_init(Time, G, GV, US, param_file, diag, CS)
   call log_param(param_file, mdl, "EPBL_MSTAR_SCHEME", tmpstr, &
                  "EPBL_MSTAR_SCHEME selects the method for setting mstar.  Valid values are: \n"//&
                  "\t CONSTANT   - Use a fixed mstar given by MSTAR \n"//&
-                 "\t OM4        - Use L_Ekman/L_Obukhov in the sabilizing limit, as in OM4 \n"//&
+                 "\t OM4        - Use L_Ekman/L_Obukhov in the stabilizing limit, as in OM4 \n"//&
                  "\t REICHL_H18 - Use the scheme documented in Reichl & Hallberg, 2018.", &
                  default=CONSTANT_STRING)
   tmpstr = uppercase(tmpstr)
@@ -2468,10 +2468,10 @@ end subroutine energetic_PBL_end
 !! simple enough that it requires only a single vertical pass to
 !! determine the diffusivity. The development of bulk mixed layer
 !! models stems from the work of various people, as described in the
-!! review paper by Niiler and Kraus (1979). The work here draws in
-!! with particular on the form for TKE decay proposed by Oberhuber
-!! (JPO, 1993, 808-829), with an extension to a refined bulk mixed
-!! layer as described in Hallberg (Aha Huliko'a, 2003).  The physical
+!! review paper by \cite niiler1977. The work here draws in
+!! with particular on the form for TKE decay proposed by
+!! \cite oberhuber1993, with an extension to a refined bulk mixed
+!! layer as described in Hallberg (\cite muller2003).  The physical
 !! processes portrayed in this subroutine include convectively driven
 !! mixing and mechanically driven mixing.  Unlike boundary-layer
 !! mixing, stratified shear mixing is not a one-directional turbulent

src/parameterizations/vertical/_BML.dox

@@ -0,0 +1,49 @@
+/*! \page BML Bulk Surface Mixed Layer
+
+This bulk surface mixed layer scheme was designed to be used with a
+purely isopycnal model. Following \cite niiler1977, \cite oberhuber1993,
+and Hallberg (\cite muller2003) the TKE budget is used to construct a
+time-evolving homogeneous mixed layer. A buffer layer sits between
+the mixed layer and the interior ocean to mediate between the two.
+
+ The following processes are executed, in the order listed.
+
+\li 1. Undergo convective adjustment into mixed layer.
+\li 2. Apply surface heating and cooling.
+\li 3. Starting from the top, entrain whatever fluid the TKE budget
+      permits.  Penetrating shortwave radiation is also applied at
+     this point.
+\li 4. If there is any unentrained fluid that was formerly in the
+     mixed layer, detrain this fluid into the buffer layer.  This
+    is equivalent to the mixed layer detraining to the Monin-
+      Obukhov depth.
+\li 5. Divide the fluid in the mixed layer evenly into CS\%nkml pieces.
+\li 6. Split the buffer layer if appropriate.
+
+Layers 1 to nkml are the mixed layer, nkml+1 to nkml+nkbl are the
+buffer layers. The results of this subroutine are mathematically
+identical if there are multiple pieces of the mixed layer with
+the same density or if there is just a single layer. There is no
+stability limit on the time step.
+
+The key parameters for the mixed layer are found in the control structure.
+These include mstar, nstar, nstar2, pen\_SW\_frac, pen\_SW\_scale, and TKE\_decay.
+For the \cite oberhuber1993 and \cite kraus1967 mixed layers, the values of these are:
+
+<table>
+<caption id="table_symbols_bml">Model variables used in the bulk mixed layer</caption>
+<tr><th>Symbol <th>Value in Oberhuber (1993) <th>Value in Kraus-Turner (1967)
+<tr><td>pen\_SW\_frac    <td> 0.42   <td> 0.0
+<tr><td>pen\_SW\_scale   <td> 15.0 m <td> 0.0 m
+<tr><td>mstar            <td> 1.25   <td> 1.25
+<tr><td>nstar            <td> 1      <td> 0.4
+<tr><td>TKE\_decay       <td> 2.5    <td> 0.0
+<tr><td>conv\_decay      <td> 0.5    <td> 0.0
+</table>
+
+TKE\_decay is \f$1/\kappa\f$ in eq. 28 of \cite oberhuber1993, while
+conv\_decay is \f$1/\mu\f$. Conv\_decay has been eliminated in favor of
+the well-calibrated form for the efficiency of penetrating convection
+from \cite wang2003.
+
+*/