update docs

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