PBL Scheme Doc Update (#1254)

* add useful references for PBL

* ignore broken link that actually works

* update pbl docs to merge

Docs/sphinx_doc/conf.py

@@ -328,6 +328,7 @@
     'https://link.springer.com/article/10.1007/BF00240838',
     'https://onlinelibrary.wiley.com/doi/10.1029/2021MS002904',
     'https://link.springer.com/article/10.1023/B:BOUN.0000020164.04146.98',
+    'https://doi.org/10.1029/RG020i004p00851'
 ]
 
 

Docs/sphinx_doc/theory/PBLschemes.rst

@@ -13,22 +13,32 @@ PBL Schemes
 Planetary Boundary Layer (PBL) schemes are used to model unresolved transport
 in the vertical direction within the planetary boundary layer when mesh
 resolutions are too coarse to resolve any of the turbulent eddies responsible
-for this transport (1 km grid resolution or larger). The PBL scheme is used to
+for this transport (~1 km grid resolution or larger). The PBL scheme is used to
 provide closure for vertical turbulent fluxes
 (i.e., :math:`\widetilde{w'\phi'} = \widetilde{w\phi} - \widetilde{w}\widetilde{\phi}`,
 for any quantity :math:`\phi`). PBL schemes may be used in
 conjunction with an LES model that specifies horizontal turbulent transport, in
 which case the vertical component of the LES model is ignored.
 
-Right now, the only PBL scheme supported in ERF is the
-Mellor-Yamada-Nakanishi-Niino Level 2.5 model.
+Right now, the only PBL scheme supported in ERF is the Mellor-Yamada-Nakanishi-Niino
+Level 2.5 model, largely matching the original forumulation proposed by Nakanishi and
+Niino in a series of papers from 2001 to 2009.
+
+.. _MYNN25:
 
 MYNN Level 2.5 PBL Model
 ------------------------
 In this model, the vertical turbulent diffusivities are computed in a local
-manner based on a transported turbulent kinetic energy value. The model was
-proposed by `Nakanishi and Niino <https://link.springer.com/article/10.1023/B:BOUN.0000020164.04146.98>`_,
-building on the work of `Mellor and Yamada <https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/RG020i004p00851>`_
+manner based on a gradient diffusion approach with coefficients computed based on
+a transported turbulent kinetic energy value. The implementation and description
+here largely follows `Nakanishi and Niino, Journal of Meteorological Society of Japan, 2009
+<https://doi.org/10.2151/jmsj.87.895>`_, but has also been influenced by the full series
+of papers that led to the development of this model and by a few documents published since then,
+as listed in the :ref:`Useful References<MYNNReferences>` section below.
+
+..
+  A key difference is conservative form
+
 
 The prognostic equation
 for :math:`q^2 = \widetilde{u_i u_i} - \widetilde{u}_i\widetilde{u}_i` is
@@ -61,3 +71,61 @@ and lengthscale depend on the Obukhov length and surface heat flux, which are
 obtained from the :ref:`MOST module<MostBoundary>`. Further detail on these
 computations can be found in the cited works. Several model coefficients are
 required, with default values in ERF taken from the work of Nakanishi and Niino.
+
+.. _MYNNReferences:
+
+Useful References
+~~~~~~~~~~~~~~~~~
+
+The following references have informed the implementation of the MYNN PBL model in ERF:
+
+.. _Mellor73: https://doi.org/10.1175/1520-0469(1973)030<1061:APOTPO>2.0.CO;2
+
+.. _MY74: https://doi.org/10.1175/1520-0469(1974)031<1791:AHOTCM>2.0.CO;2
+
+- `Mellor, Journal of the Atmospheric Sciences, 1973 <Mellor73_>`_: Introduces a PBL model based on :math:`q^2`
+
+- `Mellor and Yamada, Journal of the Atmospheric Sciences, 1974 <MY74_>`_: Introduces PBL Model Hierarchy (Levels 1-4)
+
+- `Mellor and Yamada, Reviews of Geophysics and Space Physics, 1982 <https://doi.org/10.1029/RG020i004p00851>`_:
+  Introduces Level 2.5 Model
+
+- `Nakanishi, Boundary-Layer Meteorology, 2001 <https://doi.org/10.1023/A:1018915827400>`_: Fits new model
+  coefficients and proposes new diagnostic equation for the length scale
+
+- `Nakanishi and Niino, Boundary-Layer Meteorology, 2004 <https://doi.org/10.1023/B:BOUN.0000020164.04146.98>`_:
+  Extends the MYNN PBL modeling framework for moist conditions
+
+- `Nakanishi and Niino, Boundary-Layer Meteorology, 2006 <https://doi.org/10.1007/s10546-005-9030-8>`_:
+  Numerical stability improvements for the MYNN PBL modeling framework
+
+- `Nakanishi and Niino, Journal of the Meteorological Society of Japan, 2009 <https://doi.org/10.2151/jmsj.87.895>`_:
+  Summary of MYNN model development,
+  re-evaluation of coefficients, and additional demonstration cases
+
+- `Skamarock et al., A Description of the Advanced Research WRF Model Version 4, 2021 <http://dx.doi.org/10.5065/1dfh-6p97>`_:
+  Description of the models implemented in WRF
+
+- `Olson et al., A Description of the MYNN-EDMF Scheme and the Coupling to Other Components in WRF–ARW, 2019
+  <https://doi.org/10.25923/n9wm-be49>`_:
+  Description of more recent advancements upon the MYNN model
+
+- `Juliano et al., Monthly Weather Review, 2022 <https://doi.org/10.1175/MWR-D-21-0164.1>`_:
+  Description of a 3D generalization Mellor-Yamada PBL models
+
+Discussions with Branko Kosovic (NCAR) and Joseph B. Olson (NOAA) have also played a major role in informing
+the implementation of MYNN PBL models in ERF.
+
+.. _MYNNEDMF:
+
+MYNN-EDMF Level 2.5 PBL Model
+-----------------------------
+
+More recent advancements that add significant complexity to the MYNN scheme have been incorporated into WRF, as described in Olson et al. 2019. These advancements are not included in ERF, but may be in the future.
+
+.. _YSUPBL:
+
+YSU PBL Model
+-------------
+
+The Yonsei University (YSU) PBL model is another commonly use scheme in WRF. It is not yet supported in ERF, but is under development.