update docs (erf-model#1840)

Docs/sphinx_doc/Inputs.rst

@@ -13,6 +13,22 @@ The ERF executable reads run-time information from an inputs file which you name
 This section describes the inputs which can be specified either in the inputs file or on the command line.
 A value specified on the command line will override a value specified in the inputs file.
 
+Governing Equations
+===================
++--------------------------+-----------------------------+---------------+-------------+
+| Parameter                | Definition                  | Acceptable    | Default     |
+|                          |                             | Values        |             |
++==========================+=============================+===============+=============+
+| **erf.anelastic**        | solve the anelastic         | true / false  | false       |
+|                          | equations (instead of       |               |             |
+|                          | the compressible equations) |               |             |
++--------------------------+-----------------------------+---------------+-------------+
+
+.. note::
+
+   To solve the anelastic equations, you must set ERF_USE_POISSON_SOLVE = TRUE if using
+   gmake or ERF_ENABLE_POISSON_SOLVE if using cmake.
+
 Problem Geometry
 ================
 
@@ -433,6 +449,8 @@ List of Parameters
 Notes
 -----------------
 
+-  | If **erf.anelastic** is true then **no_substepping** is internally set to 1.
+
 -  | The time step controls work somewhat differently depending on whether one is using
      acoustic substepping in time; this is determined by the value of **no_substepping**.
 

Docs/sphinx_doc/TimeAdvance.rst

@@ -7,18 +7,25 @@
 Time Advance
 ============
 
-To advance the fully compressible solution in time, ERF uses a 3rd order Runge-Kutta method with acoustic sub-stepping
-in each Runge-Kutta stage, following the approach of `Klemp, Skamarock and Dudhia (2007)`_
+Compressible Advance
+---------------------
+
+To advance the fully compressible solution in time, ERF uses a 3rd order Runge-Kutta method.
+By default, acoustic substepping which solves the perturbational equations
+implicitly in the vertical direction is used in each Runge-Kutta stage,
+following the approach of `Klemp, Skamarock and Dudhia (2007)`_
+However, there is a run-time option to turn off the substepping completely,
+or to use an explicit rather than implicit solve in the substepping.
 
 .. _`Klemp, Skamarock and Dudhia (2007)`: https://journals.ametsoc.org/view/journals/mwre/135/8/mwr3440.1.xml
 
-Specifically, for
+Specifically, the 3rd order Runge-Kutta method solves
 
 .. math::
 
   \frac{d \mathbf{S}}{dt} = f(\mathbf{S})
 
-where :math:`\mathbf{S}` is the solution vector, we solve
+where :math:`\mathbf{S}` is the solution vector, in the following three steps:
 
 .. math::
 
@@ -30,18 +37,19 @@ where :math:`\mathbf{S}` is the solution vector, we solve
 
 .. _AnelasticTimeAdvance:
 
-Anelastic Option
+Anelastic Advance
 ---------------------
 
-When solving the anelastic rather than fully compressible equations, ERF uses a 2nd order Runge-Kutta method:
+When solving the anelastic rather than fully compressible equations, ERF uses a 2nd order Runge-Kutta method
+(with no substepping):
 
-Specifically, for
+Specifically, the 2nd order Runge-Kutta method solves
 
 .. math::
 
   \frac{d \mathbf{S}}{dt} = f(\mathbf{S})
 
-where :math:`\mathbf{S}` is the solution vector, we solve
+where :math:`\mathbf{S}` is the solution vector, in the following two steps:
 
 .. math::
 
@@ -54,9 +62,9 @@ where :math:`\mathbf{S}` is the solution vector, we solve
 Acoustic Sub-stepping
 ---------------------
 
-When solving the fully compressible equation set, we sub-step the acoustic modes within each Runge-Kutta stage.
+When solving the fully compressible equation set, by default we substep the acoustic modes within each Runge-Kutta stage.
 
-We first recall the equations in the following form,
+Recall the equations in the following form,
 here defining :math:`\mathbf{R}` for each equation to include all additional terms that contribute to the time evolution.
 
 .. math::

Docs/sphinx_doc/building.rst

@@ -96,6 +96,8 @@ or if using tcsh,
    +--------------------+------------------------------+------------------+-------------+
    | USE_PARTICLES      | Whether to enable particles  | TRUE / FALSE     | FALSE       |
    +--------------------+------------------------------+------------------+-------------+
+   | USE_POISSON_SOLVE  | Whether to enable anelastic  | TRUE / FALSE     | FALSE       |
+   +--------------------+------------------------------+------------------+-------------+
    | USE_WARM_NO_PRECIP | Whether to use warm moisture | TRUE / FALSE     | FALSE       |
    +--------------------+------------------------------+------------------+-------------+
    | USE_MULTIBLOCK     | Whether to enable multiblock | TRUE / FALSE     | FALSE       |
@@ -112,7 +114,10 @@ or if using tcsh,
    +--------------------+------------------------------+------------------+-------------+
 
    .. note::
-      **Do not set both USE_OMP and USE_CUDA to true.**
+      **To run with the anelastic option, USE_POISSON_SOLVE must be set to TRUE.**
+
+   .. note::
+      **At most one of USE_OMP, USE_CUDA, USE_HIP, USE_SYCL should be set to true.**
 
    Information on using other compilers can be found in the AMReX documentation at
    https://amrex-codes.github.io/amrex/docs_html/BuildingAMReX.html .
@@ -187,6 +192,8 @@ Analogous to GNU Make, the list of cmake directives is as follows:
    +---------------------------+------------------------------+------------------+-------------+
    | ERF_ENABLE_PARTICLES      | Whether to enable particles  | TRUE / FALSE     | FALSE       |
    +---------------------------+------------------------------+------------------+-------------+
+   | ERF_ENABLE_POISSON_SOVLE  | Whether to enable anelastic  | TRUE / FALSE     | FALSE       |
+   +---------------------------+------------------------------+------------------+-------------+
    | ERF_ENABLE_WARM_NO_PRECIP | Whether to use warm moisture | TRUE / FALSE     | FALSE       |
    +---------------------------+------------------------------+------------------+-------------+
    | ERF_ENABLE_MULTIBLOCK     | Whether to enable multiblock | TRUE / FALSE     | FALSE       |
@@ -198,6 +205,12 @@ Analogous to GNU Make, the list of cmake directives is as follows:
    | ERF_ENABLE_FCOMPARE       | Whether to enable fcompare   | TRUE / FALSE     | FALSE       |
    +---------------------------+------------------------------+------------------+-------------+
 
+   .. note::
+      **To run with the anelastic option, ERF_ENABLE_POISSON_SOLVE must be set to TRUE.**
+
+   .. note::
+      **At most one of ERF_ENABLE_OMP, ERF_ENABLE_CUDA, ERF_ENABLE_HIP and ERF_ENABLE_SYCL should be set to true.**
+
 
 Mac with CMake
 ~~~~~~~~~~~~~~