update docs (#1825)

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<MultiFab> pert_pres;
-      pert_pres = derive(pert_pres, time, ngrow);
+Derived quantities as well as state variables can be output in the plotfiles.

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:
 
 ::

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

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}.

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

Docs/sphinx_doc/theory/WetEquations.rst

@@ -7,7 +7,7 @@
 
 .. _WetEquations:
 
-Prognostic Equations (Moist)
+Compressible Equations (Moist)
 ===============================
 
 Model 1: Warm Moisture with no Precipitation