From a3b91379ba4687fddf7e92238b9d335c97a88a6d Mon Sep 17 00:00:00 2001 From: Ann Almgren Date: Thu, 19 Sep 2024 18:32:39 -0700 Subject: [PATCH] update docs (#1825) --- Docs/sphinx_doc/DerivedQuantities.rst | 11 +---- Docs/sphinx_doc/MOST.rst | 2 +- Docs/sphinx_doc/index.rst | 1 + Docs/sphinx_doc/theory/Anelastic.rst | 57 +++++++++++++++++++++++++ Docs/sphinx_doc/theory/DryEquations.rst | 36 +++------------- Docs/sphinx_doc/theory/WetEquations.rst | 2 +- 6 files changed, 69 insertions(+), 40 deletions(-) create mode 100644 Docs/sphinx_doc/theory/Anelastic.rst diff --git a/Docs/sphinx_doc/DerivedQuantities.rst b/Docs/sphinx_doc/DerivedQuantities.rst index 8295fbc6b..3cc31aaac 100644 --- a/Docs/sphinx_doc/DerivedQuantities.rst +++ b/Docs/sphinx_doc/DerivedQuantities.rst @@ -6,7 +6,7 @@ Derived Variables ================= -ERF has the ability to created new temporary variables derived from the state variables. +ERF has the ability to create new temporary variables derived from the state variables. Access to the derived variable is through one of two amrex:AmrLevel functions (which are inherited by ERF) @@ -31,11 +31,4 @@ Access to the derived variable is through one of two amrex:AmrLevel functions MultiFab& mf, int dcomp); -As an example, pert\_prs is a derived variable provided with IAMR, which -returns the perturbational pressure field. -A multifab filled with the perturbational pressure can be obtained via - -:: - - std::unique_ptr pert_pres; - pert_pres = derive(pert_pres, time, ngrow); +Derived quantities as well as state variables can be output in the plotfiles. diff --git a/Docs/sphinx_doc/MOST.rst b/Docs/sphinx_doc/MOST.rst index 4498fa57c..6747f2d42 100644 --- a/Docs/sphinx_doc/MOST.rst +++ b/Docs/sphinx_doc/MOST.rst @@ -214,7 +214,7 @@ In the above case, ``use_normal_vector`` utilizes the a local surface-normal vec Due to the form of the above integral, it is advantageous to consider :math:`\tau` as a multiple of the simulation time step :math:`\Delta t`, which is specified by ``erf.most.time_window``. As ``erf.most.time_window`` is reduced to 0, the exponential filter function tends to a Dirac delta function (prior averages are irrelevant). Increasing ``erf.most.time_window`` extends the tail of the exponential and more heavily weights prior averages. Low-speed corrections ---------------------- +~~~~~~~~~~~~~~~~~~~~~ The following options are available: :: diff --git a/Docs/sphinx_doc/index.rst b/Docs/sphinx_doc/index.rst index a7cf0034f..61db8e425 100644 --- a/Docs/sphinx_doc/index.rst +++ b/Docs/sphinx_doc/index.rst @@ -46,6 +46,7 @@ In addition to this documentation, there is API documentation for ERF generated :maxdepth: 1 theory/DryEquations.rst + theory/Anelastic.rst theory/WetEquations.rst theory/Initialization.rst theory/Buoyancy.rst diff --git a/Docs/sphinx_doc/theory/Anelastic.rst b/Docs/sphinx_doc/theory/Anelastic.rst new file mode 100644 index 000000000..47844b20b --- /dev/null +++ b/Docs/sphinx_doc/theory/Anelastic.rst @@ -0,0 +1,57 @@ + + .. role:: cpp(code) + :language: c++ + + .. role:: f(code) + :language: fortran + + +.. _DryEquations: + +Anelastic Equations (Dry) +============================= + +ERF can be run in two different modes: in the first, ERF solves the fully compressible fluid equations, +in the second, ERF solves a modified set of equations which approximates the density field with the +hydrostatic density and imposes the anelastic constraint on the velocity field. + +In anelastic mode, in the absence of moisture, ERF solves the following partial differential equations +expressing conservation of momentum, potential temperature, and scalars, as well the anelastic constraint +on the velocity. + +This option does not currently support terrain-fitted coordinates. + +.. math:: + \frac{\partial (\rho_0 \mathbf{u})}{\partial t} &= - \nabla \cdot (\rho_0 \mathbf{u} \mathbf{u}) - \nabla p^\prime + + \delta_{i,3}\mathbf{B} - \nabla \cdot \tau + \mathbf{F}, + + \frac{\partial (\rho_0 \theta)}{\partial t} &= - \nabla \cdot (\rho_0 \mathbf{u} \theta) + \nabla \cdot ( \rho_0 \alpha_{T}\ \nabla \theta) + F_{\rho_0 \theta}, + + \frac{\partial (\rho_0 C)}{\partial t} &= - \nabla \cdot (\rho_0 \mathbf{u} C) + \nabla \cdot (\rho_0 \alpha_{C}\ \nabla C) + +and + +.. math:: + \nabla \cdot \mathbf{u} = 0 + +where + +- :math:`\tau` is the viscous stress tensor, + + .. math:: + \tau_{ij} = -2\mu \sigma_{ij}, + +with :math:`\sigma_{ij} = S_{ij} -D_{ij}` being the deviatoric part of the strain rate, and + +.. math:: + 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{g} = (0,0,-g)` is the gravity vector, + +- the potential temperature :math:`\theta` is defined from temperature :math:`T` and hydrostatic pressure :math:`p_0` as + +.. math:: + + \theta = T \left( \frac{p_0}{p} \right)^{R_d / c_p}. diff --git a/Docs/sphinx_doc/theory/DryEquations.rst b/Docs/sphinx_doc/theory/DryEquations.rst index c1fd88d53..05195a1b4 100644 --- a/Docs/sphinx_doc/theory/DryEquations.rst +++ b/Docs/sphinx_doc/theory/DryEquations.rst @@ -8,11 +8,15 @@ .. _DryEquations: -Prognostic Equations (Dry) +Compressible Equations (Dry) ============================= -The following partial differential equations governing dry compressible flow -are solved in ERF for mass, momentum, potential temperature, and scalars: +ERF can be run in two different modes: in the first, ERF solves the fully compressible fluid equations, +in the second, ERF solves a modified set of equations which approximates the density field with the +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. .. math:: \frac{\partial \rho}{\partial t} &= - \nabla \cdot (\rho \mathbf{u}), @@ -94,29 +98,3 @@ 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. - - -Anelastic Alternative ---------------------- - -There is an anelastic option under development, in which ERF solves the same four equations for mass, -momentum, energy, and advected scalars, but accompanied by the anelastic constraint rather than the -equation of state as given in the Diagnostic Relationship section above. This option does not -currently support terrain-fitted coordinates. - -The anelastic constraint has the form - -.. math:: - \nabla \cdot (\overline{\rho} \mathbf{u}) = 0 - -We take a predictor-corrector approach to solving this system, in which we first advance -the velocity field to create a provisional velocity, :math:`\mathbf{u}^*` at the new time, -then impose the constraint by solving the pressure Poisson equation for :math:`p^\prime` - -.. math:: - \nabla \cdot ( \frac{\overline{\rho}}{\rho} \nabla p^\prime ) = \nabla \cdot ( \overline{\rho} \mathbf{u}^* ) - -then setting - -.. math:: - \mathbf{u}^{n+1} = \mathbf{u}^* - \frac{1}{\rho} \nabla p^\prime diff --git a/Docs/sphinx_doc/theory/WetEquations.rst b/Docs/sphinx_doc/theory/WetEquations.rst index 27e75e28f..83eb38af0 100644 --- a/Docs/sphinx_doc/theory/WetEquations.rst +++ b/Docs/sphinx_doc/theory/WetEquations.rst @@ -7,7 +7,7 @@ .. _WetEquations: -Prognostic Equations (Moist) +Compressible Equations (Moist) =============================== Model 1: Warm Moisture with no Precipitation