From 53a6ac891f1283e6ef75187572f17604cc8a2020 Mon Sep 17 00:00:00 2001 From: Ann Almgren Date: Wed, 2 Oct 2024 07:15:28 -0700 Subject: [PATCH] update docs (#1840) --- Docs/sphinx_doc/Inputs.rst | 18 ++++++++++++++++++ Docs/sphinx_doc/TimeAdvance.rst | 28 ++++++++++++++++++---------- Docs/sphinx_doc/building.rst | 15 ++++++++++++++- 3 files changed, 50 insertions(+), 11 deletions(-) diff --git a/Docs/sphinx_doc/Inputs.rst b/Docs/sphinx_doc/Inputs.rst index d3260ee1f..52938190e 100644 --- a/Docs/sphinx_doc/Inputs.rst +++ b/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**. diff --git a/Docs/sphinx_doc/TimeAdvance.rst b/Docs/sphinx_doc/TimeAdvance.rst index d63d17632..e6d12ef33 100644 --- a/Docs/sphinx_doc/TimeAdvance.rst +++ b/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:: diff --git a/Docs/sphinx_doc/building.rst b/Docs/sphinx_doc/building.rst index 1cea56ec6..039b0c313 100644 --- a/Docs/sphinx_doc/building.rst +++ b/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 ~~~~~~~~~~~~~~