make docs match paper. (#2006)

Docs/sphinx_doc/theory/Buoyancy.rst

@@ -5,7 +5,7 @@
  .. role:: f(code)
     :language: fortran
 
-.. _sec:Buoyancy:
+.. _Buoyancy:
 
 ERF has several options for how to define the buoyancy force.
 

Docs/sphinx_doc/theory/DryEquations.rst

@@ -16,21 +16,20 @@ in the second, ERF solves a modified set of equations which approximates the den
 hydrostatic density and imposes the anelastic constraint on the velocity field.
 
 In compressible mode, in the absence of moisture, ERF solves the following partial differential equations
-expressing conservation of mass, momentum, potential temperature, and scalars.
+expressing conservation of mass :math:`(\rho)`, momentum :math:`(\rho \mathbf{u})`, potential temperature :math:`(\rho \theta_{d})`, and scalars :math:`(\rho \mathbf{\phi})`:
 
 .. math::
-  \frac{\partial \rho}{\partial t} &= - \nabla \cdot (\rho \mathbf{u}),
+   \frac{\partial \rho_d}{\partial t} = - \nabla \cdot (\rho_d \mathbf{u}),
 
-  \frac{\partial (\rho \mathbf{u})}{\partial t} &= - \nabla \cdot (\rho \mathbf{u} \mathbf{u}) - \nabla p^\prime
-        + \delta_{i,3}\mathbf{B} - \nabla \cdot \tau + \mathbf{F},
+   \frac{\partial (\rho_d \mathbf{u})}{\partial t} = - \nabla \cdot (\rho_d \mathbf{u} \mathbf{u}) - \frac{1}{1 + q_v + q_c} ( \nabla p^\prime  - \delta_{i,3}\mathbf{B} ) - \nabla \cdot \boldsymbol{\tau} + \mathbf{F}_{u},
 
-  \frac{\partial (\rho \theta)}{\partial t} &= - \nabla \cdot (\rho \mathbf{u} \theta) + \nabla \cdot ( \rho \alpha_{T}\ \nabla \theta) + F_{\rho \theta},
+   \frac{\partial (\rho_d \theta_d)}{\partial t} = - \nabla \cdot (\rho_d \mathbf{u} \theta_d) + \nabla \cdot ( \rho_d \alpha_{\theta}\ \nabla \theta_d) + F_{\theta},
 
-  \frac{\partial (\rho C)}{\partial t} &= - \nabla \cdot (\rho \mathbf{u} C) + \nabla \cdot (\rho \alpha_{C}\ \nabla C)
+   \frac{\partial (\rho_d \boldsymbol{\phi})}{\partial t} &= - \nabla \cdot (\rho_d \mathbf{u} \boldsymbol{\phi}) + \nabla \cdot ( \rho_d \alpha_{\phi}\ \nabla \boldsymbol{\phi}) + \mathbf{F}_{\phi}.
 
 where
 
-- :math:`\tau` is the viscous stress tensor,
+- :math:`\boldsymbol{\tau}` is the viscous stress tensor,
 
   .. math::
      \tau_{ij} = -2\mu \sigma_{ij},
@@ -41,24 +40,25 @@ with :math:`\sigma_{ij} = S_{ij} -D_{ij}` being the deviatoric part of the strai
    S_{ij} = \frac{1}{2} \left(  \frac{\partial u_i}{\partial x_j} + \frac{\partial u_j}{\partial x_i}   \right), \hspace{24pt}
    D_{ij} = \frac{1}{3}  S_{kk} \delta_{ij} = \frac{1}{3} (\nabla \cdot \mathbf{u}) \delta_{ij},
 
-- :math:`\mathbf{F}` and :math:`F_{\rho \theta}` are the forcing terms described in :ref:`Forcings`,
+- :math:`\mathbf{F}_{u}` and :math:`F_{\theta_d}` are the forcing terms described in :ref:`Forcings`,
+- :math:`\mathbf{B} = -(\rho - \rho_{0})\mathbf{g}` is the buoyancy term described in :ref:`sec:Buoyancy <Buoyancy>`,
 - :math:`\mathbf{g} = (0,0,-g)` is the gravity vector,
-- the potential temperature :math:`\theta` is defined from temperature :math:`T` and pressure :math:`p` as
+- the dry potential temperature :math:`\theta_d` is defined from temperature :math:`T`, pressure :math:`p`, and reference pressure :math:`P_{00} = 10^{5}` Pa as
 
 .. math::
 
-  \theta = T \left( \frac{p_0}{p} \right)^{R_d / c_p}.
+  \theta_d = T \left( \frac{P_{00}}{p} \right)^{R_d / c_p}.
 
 - pressure and density are defined as perturbations from a hydrostatically stratified background state, i.e.
 .. math::
 
-  p = \overline{p}(z) + p^\prime  \hspace{24pt} \rho = \overline{\rho}(z) + \rho^\prime
+  p = p_{0}(z) + p^\prime  \hspace{24pt} \rho = \rho_{0}(z) + \rho^\prime
 
 with
 
 .. math::
 
-  \frac{d \overline{p}}{d z} = - \overline{\rho} g
+  \frac{d p_{0}}{d z} = - \rho_{0} g
 
 We note that there is an alternative option under development in ERF that solves the governing
 equations with an anelastic constraint rather than the fully compressible equations.  The equation set is described below.
@@ -74,27 +74,27 @@ The assumptions involved in deriving these equations from first principles are:
 - Viscous heating is negligible
 - No chemical reactions, second order diffusive processes or radiative heat transfer
 - Newtonian viscous stress with no bulk viscosity contribution (i.e., :math:`\kappa S_{kk} \delta_{ij}`)
-- Depending on the simulation mode, the transport coefficients :math:`\mu`, :math:`\rho\alpha_C`, and
-  :math:`\rho\alpha_T` may correspond to the molecular transport coefficients, turbulent transport
+- Depending on the simulation mode, the transport coefficients :math:`\mu`, :math:`\rho\alpha_{\phi}`, and
+  :math:`\rho\alpha_{\theta}` may correspond to the molecular transport coefficients, turbulent transport
   coefficients computed from an LES or PBL model, or a combination. See the sections on :ref:`DNS vs. LES modes <DNSvsLES>`
   and :ref:`PBL schemes <PBLschemes>` for more details.
 
 Diagnostic Relationships
 ------------------------
 
 In order to close the above prognostic equations, a relationship between the pressure and the other state variables
-must be specified. This is obtained by re-expressing the ideal gas equation of state in terms of :math:`\theta`:
+must be specified. This is obtained by re-expressing the ideal gas equation of state in terms of :math:`\theta_{d}`:
 
 .. math::
-   p = \left( \frac{\rho R_d \theta}{p_0^{R_d / c_p}} \right)^\gamma = p_0 \left( \frac{\rho R_d \theta}{p_0} \right)^\gamma
+   p = \left( \frac{\rho R_d \theta_{d}}{P_{00}^{R_d / c_p}} \right)^\gamma = P_{00} \left( \frac{\rho R_d \theta_{d}}{P_{00}} \right)^\gamma
 
 Nomenclature
 ------------
-Here :math:`\rho, T, \theta`, and :math:`p` are the density, temperature, potential temperature and pressure, respectively;
+Here :math:`\rho, T, \theta_{d}`, and :math:`p` are the density, temperature, dry potential temperature and pressure, respectively;
 these variables are all defined at cell centers.
-:math:`C` is an advected quantity, i.e., a tracer, also defined at cell centers.
+:math:`\phi` is an advected scalar, also defined at cell centers.
 :math:`\mathbf{u}` and :math:`(\rho \mathbf{u})` are the velocity and momentum, respectively,
 and are defined on faces.
 
 :math:`R_d` and :math:`c_p` are the gas constant and specific heat capacity for dry air respectively,
-and :math:`\gamma = c_p / (c_p - R_d)` .  :math:`p_0` is a reference value for pressure.
+and :math:`\gamma = c_p / (c_p - R_d)` .  :math:`P_{00}` is a reference value for pressure.

Docs/sphinx_doc/theory/Microphysics.rst

@@ -20,15 +20,28 @@ Governing equations for the microphysical quantities for Kessler microphysics fr
 .. math::
     \frac{\partial q_c}{\partial t} = C_c - E_c - (A_c + K_c)
 .. math::
-    \frac{\partial q_p}{\partial t} =  \frac{1}{\overline{\rho}}\frac{\partial}{\partial z}(\overline{\rho}Vq_p) + (A_c + K_c) - E_r
+    \frac{\partial q_p}{\partial t} =  \frac{1}{\rho_{d}}\frac{\partial}{\partial z}(\rho_{d} w_{t} q_p) + (A_c + K_c) - E_r
 .. math::
     \frac{\partial q_t}{\partial t} = \frac{\partial q_v}{\partial t} + \frac{\partial q_c}{\partial t}
                                     =  E_r - (A_c + K_c)
 
 where :math:`C_c` is the rate of condensation of water vapor to cloud water, :math:`E_c` is the rate of evaporation of cloud water to water vapor,
 :math:`A_c` is the autoconversion of cloud water to rain, :math:`K_c` is the accretion of cloud water to rain drops, :math:`E_r` is the evaporation of
-rain to water vapor and :math:`F_r` is the sedimentation of rain. The parametrization used is given in `klemp1978simulation`_, and is given
-below. Note that in all the equations, :math:`p` is specified in millibars and :math:`\overline{\rho}` is specified in g cm :math:`^{-3}`. The parametrization
+rain to water vapor and :math:`F_r = \rho_{d} w_{t} q_p` is the sedimentation flux. The source terms that enter into the governing equations are then given by:
+
+.. math::
+   \mathbf{F_{n}} \equiv [F_{q_v}, F_{q_c}] = \left[ -C_c, \;\; C_c \right],
+
+   \mathbf{G_{p}} = \left[ E_r, \;\; -A_c - K_c \right],
+
+   H_{n} = \rho_d \frac{L_v}{c_p} \frac{\theta_d}{T} C_c,
+
+   F_{p} = A_c + K_c - E_c,
+
+   H_{p} = -\rho_d \frac{L_v}{c_p} \frac{\theta_d}{T} E_r.
+
+The parametrizations provided in `klemp1978simulation`_ are given below for each term.
+Note that in all the equations, :math:`p` is specified in millibars and :math:`\overline{\rho}` is specified in g cm :math:`^{-3}`. The parametrization
 of the source terms are given below.
 
 .. _`gabervsek2012dry`: https://journals.ametsoc.org/view/journals/mwre/140/10/mwr-d-11-00144.1.xml
@@ -47,12 +60,12 @@ From `klemp1978simulation`_, we have the following expressions.
 If the air is not saturated, i.e. :math:`q_v > q_{vs}`
 
 .. math::
-    C_c = \frac{q_v - q_{vs}}{1 + \cfrac{q_{vs}^*4093L}{C_p(T-36)^2}}
+    C_c = \frac{q_v - q_{vs}}{1 + \cfrac{q_{vs}^*4093L}{c_p(T-36)^2}}
 
 If the air is not saturated, i.e. :math:`q_v < q_{vs}`, then cloud water evaporates to water vapor at the rate
 
 .. math::
-    E_c = \frac{q_{vs} - q_v}{1 + \cfrac{q_{vs}^*4093L}{C_p(T-36)^2}}
+    E_c = \frac{q_{vs} - q_v}{1 + \cfrac{q_{vs}^*4093L}{c_p(T-36)^2}}
 
 Rate of autoconversion of cloud water into rain
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -90,7 +103,7 @@ Terminal fall velocity of rain
 The terminal fall velocity of rain is given by
 
 .. math::
-    V = 3634(\overline{\rho}q_r)^{0.1346}\Bigg(\cfrac{\overline{\rho}}{\rho_0}\Bigg)^{-\frac{1}{2}}~\text{[cm/s]}
+    w_{t} = 3634(\overline{\rho}q_r)^{0.1346}\Bigg(\cfrac{\overline{\rho}}{\rho_0}\Bigg)^{-\frac{1}{2}}~\text{[cm/s]}
 
 .. raw:: latex
 

Docs/sphinx_doc/theory/WetEquations.rst

@@ -16,7 +16,7 @@ Model 1: Warm Moisture with no Precipitation
 With this model, which is analogous to that in FASTEddy, we
 consider a mixture of dry air :math:`\rho_d` and nonprecipitating water vapor :math:`\rho_v`,
 assumed to be a perfect ideal gas with constant heat capacities
-:math:`C_{vd}`, :math:`C_{vv}`, :math:`C_{pd}`, :math:`C_{pv}`, and
+:math:`c_{vd}`, :math:`c_{vv}`, :math:`c_{pd}`, :math:`c_{pv}`, and
 (non-precipitating) cloud water :math:`\rho_c`.
 
 Neglecting the volume occupied by all water not in vapor form, we have
@@ -32,30 +32,28 @@ relative to the density of dry air, i.e. :math:`q_s = \frac{\rho_s}{\rho_d}`.
 
 Governing Equations
 -------------------
-The governing equations for this model are
+The governing equations without precipitating moisture variables are
 
 .. math::
-  \frac{\partial \rho_d}{\partial t} &= - \nabla \cdot (\rho_d \mathbf{u})
+   \frac{\partial \rho_d}{\partial t} = - \nabla \cdot (\rho_d \mathbf{u}),
 
-  \frac{\partial (\rho_d \mathbf{u})}{\partial t} &= - \nabla \cdot (\rho_d \mathbf{u} \mathbf{u}) -
-          \frac{1}{1 + q_v + q_c} ( \nabla p^\prime  + \delta_{i,3}\mathbf{B} ) - \nabla \cdot \tau + \mathbf{F}
+   \frac{\partial (\rho_d \mathbf{u})}{\partial t} = - \nabla \cdot (\rho_d \mathbf{u} \mathbf{u}) - \frac{1}{1 + q_v + q_c} ( \nabla p^{\prime}  - \delta_{i,3}\mathbf{B} ) - \nabla \cdot \boldsymbol{\tau} + \mathbf{F}_{u},
 
-  \frac{\partial (\rho_d \theta_d)}{\partial t} &= - \nabla \cdot (\rho_d \mathbf{u} \theta_d)
-                + \nabla \cdot ( \rho_d \alpha_{T}\ \nabla \theta_d) + \frac{\theta_d L_v}{T_d C_{pd}} f_{cond}
+   \frac{\partial (\rho_d \theta_d)}{\partial t} = - \nabla \cdot (\rho_d \mathbf{u} \theta_d) + \nabla \cdot ( \rho_d \alpha_{\theta}\ \nabla \theta_d) + F_{\theta} + H_{n},
 
-  \frac{\partial (\rho_d q_v)}{\partial t} &= - \nabla \cdot (\rho_d \mathbf{u} q_vi) + \nabla \cdot (\rho_d \alpha \nabla q_v) - f_{cond}
+   \frac{\partial (\rho_d \boldsymbol{\phi})}{\partial t} = - \nabla \cdot (\rho_d \mathbf{u} \boldsymbol{\phi}) + \nabla \cdot ( \rho_d \alpha_{\phi}\ \nabla \boldsymbol{\phi}) + \mathbf{F}_{\phi},
 
-  \frac{\partial (\rho_d q_c)}{\partial t} &= - \nabla \cdot (\rho_d \mathbf{u} q_c) + \nabla \cdot (\rho_d \alpha \nabla q_c) + f_{cond}
+   \frac{\partial (\rho_d \mathbf{q_{n}})}{\partial t} = - \nabla \cdot (\rho_d \mathbf{u} \mathbf{q_{n}}) + \nabla \cdot (\rho_d \alpha_{q} \nabla \mathbf{q_{n}}) + \mathbf{F_{n}},
+
+the non-precipitating water mixing ratio vector :math:`\mathbf{q_{n}} = \left[ q_v \;\; q_c \;\; q_i \right]` includes water vapor, :math:`q_v`, cloud water, :math:`q_c`, and cloud ice, :math:`q_i`, although some models may not include cloud ice. The source terms for moisture variables, :math:`\mathbf{F_{n}}`, and their corresponding impact on potential temperature, :math:`H_{n}` are specific to the employed model. For the Kessler microphysics scheme, these terms are detailed in :ref:`sec:Kessler Microphysics model <Microphysics>`.
 
-Here :math:`L_v` is the latent heat of vaporization, :math:`\theta_d` is the (dry) potential temperature
-:math:`\mathbf{B}` is the buoyancy force, which is defined in :ref:`sec:Buoyancy <Buoyancy>`.
 
 The pressure perturbation is computed as
 
 .. math::
-  p^\prime = p_0 \left( \frac{R_d \rho_d \theta_m}{p_0} \right)^\gamma - p_0
+  p^\prime = P_{00} \left( \frac{R_d \rho_d \theta_m}{P_{00}} \right)^\gamma - p_{0}
 
-where :math:`\gamma = C_{pd} / C_{vd}` and
+where :math:`\gamma = c_{p} / (c_{p} - R_{d})` and
 
 .. math::
   \theta_m = \theta_d (1 + \frac{R_v}{R_d} q_v)
@@ -67,7 +65,7 @@ Model 2: Full Moisture Including Precipitation
 
 With this model, in addition to dry air :math:`\rho_d` and nonprecipitating water vapor :math:`\rho_v`,
 assumed to be a perfect ideal gas with constant heat capacities
-:math:`C_{vd}`, :math:`C_{vv}`, :math:`C_{pd}`, :math:`C_{pv}`,
+:math:`c_{vd}`, :math:`c_{vv}`, :math:`c_{pd}`, :math:`C_{pv}`,
 we include
 non-precipitating condensates :math:`\rho_c + \rho_i`,
 and precipitating condensates :math:`\rho_p = \rho_{rain} + \rho_{snow} + \rho_{graupel}`.
@@ -102,9 +100,9 @@ and write the EOS as
 or
 
 .. math::
-   p = p_0 (\frac{\Pi}{C_p^\star})^{\frac{C_p^\star}{R^\star}}
+   p = P_{00} (\frac{\Pi}{c_p^\star})^{\frac{c_p^\star}{R^\star}}
 
-where :math:`p_0` is the reference pressure. and
+where :math:`P_{00}` is the reference pressure. and
 
 .. math::
   \Pi = C_p^\star (\frac{p}{\alpha p_0})^\frac{R^\star}{C_p^\star}
@@ -118,23 +116,19 @@ water vapor, cloud ice, and precipitating condensates, respectively.
 
 Governing Equations
 -------------------
-We assume that all species have same average speed,
-Then the governing equations become
+The governing equations with precipitating moisture components are
 
 .. math::
-  \frac{\partial \rho_d}{\partial t} &= - \nabla \cdot (\rho_d \mathbf{u} + \mathbf{F}_\rho)
+   \frac{\partial \rho_d}{\partial t} = - \nabla \cdot (\rho_d \mathbf{u}),
+
+   \frac{\partial (\rho_d \mathbf{u})}{\partial t} = - \nabla \cdot (\rho_d \mathbf{u} \mathbf{u}) - \frac{1}{1 + q_v + q_c} ( \nabla p^{\prime}  - \delta_{i,3}\mathbf{B} ) - \nabla \cdot \boldsymbol{\tau} + \mathbf{F}_{u},
 
-  \frac{\partial (\rho_d \mathbf{u})}{\partial t} &= - \nabla \cdot (\rho_d \mathbf{u} \mathbf{u} + \mathbf{F}_u) -
-          \frac{1}{1 + q_T + q_p}  \nabla p^\prime - \nabla \cdot \tau + \mathbf{F} + \delta_{i,3}\mathbf{B}
+   \frac{\partial (\rho_d \theta_d)}{\partial t} = - \nabla \cdot (\rho_d \mathbf{u}        \theta_d) + \nabla \cdot ( \rho_d \alpha_{\theta}\ \nabla \theta_d) + F_{\theta} + H_{n} + H_{p},
 
-  \frac{\partial (\rho_d \theta)}{\partial t} &= - \nabla \cdot (\rho_d \mathbf{u} \theta + F_{\theta}) + \nabla \cdot ( \rho_d \alpha_{T}\ \nabla \theta) + F_Q
+   \frac{\partial (\rho_d \boldsymbol{\phi})}{\partial t} = - \nabla \cdot (\rho_d \mathbf{u} \boldsymbol{\phi}) + \nabla \cdot ( \rho_d \alpha_{\phi}\ \nabla \boldsymbol{\phi}) + \mathbf{F}_{\phi},
 
-  \frac{\partial (\rho_d q_T)}{\partial t} &= - \nabla \cdot (\rho_d \mathbf{u} q_T +F_{q_{T}}) - Q
+   \frac{\partial (\rho_d \mathbf{q_{n}})}{\partial t} = - \nabla \cdot (\rho_d \mathbf{u} \mathbf{q_{n}}) + \nabla \cdot (\rho_d \alpha_{q} \nabla \mathbf{q_{n}}) + \mathbf{F_{n}} + \mathbf{G_{p}},
 
-  \frac{\partial (\rho_d q_p)}{\partial t} &= - \nabla \cdot (\rho_d \mathbf{u} q_p + F_{q_{p}}) + Q
+   \frac{\partial (\rho_d \mathbf{q_{p}})}{\partial t} = - \nabla \cdot (\rho_d \mathbf{u} \mathbf{q_{p}}) + \partial_{z} \left( \rho_d \mathbf{w_{t}} \mathbf{q_{p}} \right) + \mathbf{F_{p}}.
 
-In this set of equations, the subgrid turbulent parameterization effects are included with fluxes
-:math:`F_\rho`, :math:`F_u`, :math:`F_C`, :math:`F_{\theta}`, :math:`F_{q_{T}}`, :math:`F_{q_{r}}`.
-:math:`\mathbf{F}` stands for the external force, and :math:`Q` and :math:`F_Q` represent the mass and energy transformation
-of water vapor to/from water through condensation/evaporation, which is determined by the microphysics parameterization processes.
-:math:`\mathbf{B}` is the buoyancy force, which is defined in :ref:`sec:Buoyancy <Buoyancy>`.
+the non-precipitating water mixing ratio vector :math:`\mathbf{q_{n}} = \left[ q_v \;\; q_c \;\; q_i \right]` includes water vapor, :math:`q_v`, cloud water, :math:`q_c`, and cloud ice, :math:`q_i`, although some models may not include cloud ice; similarly, the precipitating water mixing ratio vector :math:`\mathbf{q_{p}} = \left[ q_r \;\; q_s \;\; q_g \right]` involves rain, :math:`q_r`, snow, :math:`q_s`, and graupel, :math:`q_g`, though some models may not include these terms. The source terms for moisture variables, :math:`\mathbf{F_{p}}`, :math:`\mathbf{F_{n}}`, :math:`\mathbf{G_{p}}`, and their corresponding impact on potential temperature, :math:`H_{n}` and :math:`H_{p}`, and the terminal velocity, :math:`\mathbf{w_{t}}` are specific to the employed model. For the Kessler microphysics scheme, these terms are detailed in :ref:`sec:Kessler Microphysics model <Microphysics>`.