From 8eab7d2a2ff0e314b570208c1c825c283435bc31 Mon Sep 17 00:00:00 2001 From: "Aaron M. Lattanzi" <103702284+AMLattanzi@users.noreply.github.com> Date: Fri, 6 Dec 2024 12:25:05 -0800 Subject: [PATCH] make docs match paper. (#2006) --- Docs/sphinx_doc/theory/Buoyancy.rst | 2 +- Docs/sphinx_doc/theory/DryEquations.rst | 38 +++++++++--------- Docs/sphinx_doc/theory/Microphysics.rst | 25 +++++++++--- Docs/sphinx_doc/theory/WetEquations.rst | 52 +++++++++++-------------- 4 files changed, 62 insertions(+), 55 deletions(-) diff --git a/Docs/sphinx_doc/theory/Buoyancy.rst b/Docs/sphinx_doc/theory/Buoyancy.rst index 4d4b28ea7..1b287ffac 100644 --- a/Docs/sphinx_doc/theory/Buoyancy.rst +++ b/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. diff --git a/Docs/sphinx_doc/theory/DryEquations.rst b/Docs/sphinx_doc/theory/DryEquations.rst index 05195a1b4..35c7818b8 100644 --- a/Docs/sphinx_doc/theory/DryEquations.rst +++ b/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 `, - :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,8 +74,8 @@ 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 ` and :ref:`PBL schemes ` for more details. @@ -83,18 +83,18 @@ 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. diff --git a/Docs/sphinx_doc/theory/Microphysics.rst b/Docs/sphinx_doc/theory/Microphysics.rst index 644e70dd5..3ab536abf 100644 --- a/Docs/sphinx_doc/theory/Microphysics.rst +++ b/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 diff --git a/Docs/sphinx_doc/theory/WetEquations.rst b/Docs/sphinx_doc/theory/WetEquations.rst index e6fa977c8..da422005b 100644 --- a/Docs/sphinx_doc/theory/WetEquations.rst +++ b/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 `. -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 `. 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 `. +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 `.