more updates to docs (#1963)

Docs/sphinx_doc/AMReX.rst

@@ -16,13 +16,3 @@ In addition to portability across architectures, AMReX provides data structures
 Data is defined on disjoint logically rectangular regions of the domain known as patches (or grids or boxes); we note that unlike WRF, AMReX (and therefore ERF) does not require one patch per MPI rank, thus allowing much more general domain decomposition. Common operations, such as parallel communication and reduction operations, as well as interpolation and averaging operators between levels of refinement, are provided by the AMReX framework.
 
 Finally, ERF currently leverages, or plans to leverage, AMReX capabilities for effective load balancing, adaptive mesh refinement, memory management, asynchronous I/O, Lagrangian particles with particle-mesh interactions, and linear solvers.
-
-We note that ERF supports both a cmake and a gmake build system.
-
-
-Linear Solvers
-==============
-
-Evolving the anelastic equation set requires solution of a Poisson equation in which we solve for the update to the perturbational pressure at cell centers.   AMReX provides several solver options: geometric multigrid, Fast Fourier Transforms (FFTs) and preconditioned GMRES.  For simulations with no terrain or grid stretching, one of the FFT options is generally the fastest solver, followed by multigrid.  We note that the multigrid solver has the option to ``ignore'' a coordinate direction if the domain is only one cell wide in that direction; this allows for efficient solution of effectively 2D problems.  Multigrid can also be used when the union of grids at a level is not in itself rectangular; the FFT solvers do not work in that general case.
-
-For simulations using grid stretching in the vertical but flat terrain, we must use the hybrid FFT solver in which we perform 2D transforms only in the lateral directions and couple the solution in the vertical direction with a tridiagonal solve. In both these cases we use a 7-point stencil. To solve the Poisson equation on terrain-fitted coordinates with general terrain, we rely on the preconditioned GMRES solver since the stencil effectively has variable coefficients and requires 19 points.

Docs/sphinx_doc/BoundaryConditions.rst

@@ -7,6 +7,14 @@
 Domain Boundary Conditions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Lateral boundary conditions in ERF can be specified for idealized simulations as periodic, inflow, outflow, or open. More realistic conditions include the use of time-varying values read in from external files, such as the wrfbdy files generated by the WRF Preprocessing System (WPS).
+ERF also has the option to run precursor simulations, save planes of data at specified times, and later read boundary data from those files analogously to how data from the wrfbdy are used.
+
+The bottom surface boundary condition can be specified as a simple wall or by using Monin-Obukhov similarity theory (MOST).
+When utilizing MOST, the surface roughness, :math:`z_0`, may be specified as a constant, read from a file,
+or dynamically computed from the Charnock or shallow water formulation.
+Time-varying sea surface temperatures may also be employed in conjunction with MOST. 
+
 Ideal Domain BCs
 ----------------------
 
@@ -201,43 +209,6 @@ current RK stage, :math:`\psi^{BDY}` is temporal interpolation of the observatio
 is a constant that ensure the exponential blending function obtains a value of 0.01 at the last relaxation cell,
 and :math:`n` is the minimum number of grid points from a lateral boundary.
 
-Sponge zone domain BCs
-----------------------
-
-ERF provides the capability to apply sponge zones at the boundaries to prevent spurious reflections that otherwise occur at the domain boundaries if standard extrapolation boundary condition is used. The sponge zone is implemented as a source term in the governing equations, which are active in a volumteric region at the boundaries that is specified by the user in the inputs file. Currently the target condition to which the sponge zones should be forced towards is to be specified by the user in the inputs file.
-
-.. math::
-
-   \frac{dQ}{dt} = \mathrm{RHS} - A\xi^n(Q-Q_\mathrm{target})
-
-where RHS are the other right-hand side terms. The parameters to be set by the user are -- `A` is the sponge amplitude, `n` is the sponge strength and the :math:`Q_\mathrm{target}` -- the target solution in the sponge. :math:`\xi` is a linear coordinate that is 0 at the beginning of the sponge and 1 at the end. An example of the sponge inputs can be found in ``Exec/RegTests/Terrain2d_Cylinder`` and is given below. This list of inputs specifies sponge zones in the inlet and outlet of the domain in the x-direction and the outlet of the domain in the z-direction. The `start` and `end` parameters specify the starting and ending of the sponge zones. At the inlet, the sponge starts at :math:`x=0` and at the outlet the sponge ends at :math:`x=L` -- the end of the domain. The sponge amplitude `A` has to be adjust
-ed in a problem-specific manner. The density and the :math:`x, y, z` velocities to be used in the sponge zones have to be specified in the inputs list.
-
-::
-
-          erf.sponge_strength = 10000.0
-          erf.use_xlo_sponge_damping = true
-          erf.xlo_sponge_end = 4.0
-          erf.use_xhi_sponge_damping = true
-          erf.xhi_sponge_start = 26.0
-          erf.use_zhi_sponge_damping = true
-          erf.zhi_sponge_start = 8.0
-
-          erf.sponge_density = 1.2
-          erf.sponge_x_velocity = 10.0
-          erf.sponge_y_velocity = 0.0
-          erf.sponge_z_velocity = 0.0
-
-Another way of specifying sponge zones is by providing the sponge zone data as a text file input. This is currently implemented only for forcing :math:`x` and :math:`y` velocities in the sponge zones.
-The sponge data is input as a text file with 3 columns containing :math:`z, u, v` values. An example can be found in ``Exec/SpongeTest`` and a sample inputs list for using this feature is given below. This list specifies a sponge zone in the inlet in the x-direction. The :math:`u` and :math:`v` velocity forcing in the sponge zones will be read in from the text file -- `input_sponge_file.txt`.
-
-::
-
-          erf.sponge_type = "input_sponge"
-          erf.input_sponge_file = "input_sponge_file.txt"
-          erf.sponge_strength = 1000.0
-          erf.use_xlo_sponge_damping = true
-          erf.xlo_sponge_end = 4.0
 
 Inflow turbulence generation
 ---------------------------

Docs/sphinx_doc/Plotfiles.rst

@@ -16,7 +16,7 @@ Plotfiles can be written very efficiently in parallel in a native AMReX format.
 They can also be written in NetCDF. It is possible to output plotfiles in the
 same or separate formats at two distinct frequencies.
 
-The computational cost associated with reading and writing checkpoint files
+The computational cost associated with writing plotfiles
 in the AMReX native format is typically negligible relative to the overall cost of the simulation;
 in a recent performance study the cost of writing a plotfile was roughly a percent or two
 of the cost of a single timestep.

Docs/sphinx_doc/theory/Buoyancy.rst

@@ -5,7 +5,7 @@
  .. role:: f(code)
     :language: fortran
 
-.. _Buoyancy:
+.. _sec:Buoyancy:
 
 Buoyancy
 =========

Docs/sphinx_doc/theory/Forcings.rst

@@ -10,7 +10,16 @@
 Physical Forcings
 =================
 
-ERF includes the following forcing terms as options:
+Physical forcings available in ERF comprise the standard source terms for atmospheric modeling.
+These include Coriolis and geostrophic forcing; Rayleigh damping and sponge layer(s); subsidence;
+simplified radiative thermal sources; and solution nudging towards a prescribed input sounding.  
+
+ERF also supports models for wind farm parametrization in which the effects of wind turbines are represented
+by imposing a momentum sink on the mean flow and/or turbulent kinetic energy (TKE).
+Currently the Fitch model, Explicit Wake Parametrization (EWP) model, Simplified Actuator Disk model (SAD),
+and Generalized Actuator Disk model (GAD) are supported. See:ref:`sec:WindFarmModels` for more information. 
+
+Below is more detail on how to set the forcing terms.
 
 Buoyancy
 --------
@@ -21,11 +30,8 @@ If
 
       use_gravity == true
 
-then buoyancy is included in the momentum equations in the form
-
-.. math::
-
-  (0, 0, -\rho^\prime g)
+then buoyancy is included in the momentum equations.  See :ref:`sec:Buoyancy` for more detail
+about the possible formulations of the buoyancy term.
 
 Coriolis Forcing
 ----------------
@@ -45,6 +51,9 @@ then Coriolis forcing is included in the momentum equations, i.e. :
 where :math:`C_f = 4 \pi / P_{rot}` is the Coriolis factor with :math:`P_{rot}` the rotational
 period (measured in seconds), and :math:`\phi` the latitude.
 
+Values for ``erf.rotational_time_period``, ``erf.latitude``, and ``erf.coriolis_3d``; the first two are used
+to compute the Coriolis frequencey and the last of these determines whether to include the z-component in the Coriolis forcing.
+
 There is no dependence on the radial distance from the center of the earth, thus the curvature of the earth is neglected.
 
 Rayleigh Damping
@@ -79,11 +88,51 @@ defined as the initial horizontally homogeneous fields in idealized simulations,
 and :math:`\overline{\theta}` is the reference state potential temperature.
 As in the WRF model, the reference state vertical velocity is assumed to be zero.
 
+Sponge regions
+----------------------
+
+ERF provides the capability to apply sponge source terms near domain boundaries to prevent spurious reflections that otherwise occur
+at the domain boundaries if standard extrapolation boundary condition is used. The sponge zone is implemented as a source term 
+in the governing equations, which are active in a volumteric region at the boundaries that is specified by the user in the inputs file.
+Currently the target condition to which the sponge zones should be forced towards is to be specified by the user in the inputs file.
+
+.. math::
+
+   \frac{dQ}{dt} = \mathrm{RHS} - A\xi^n(Q-Q_\mathrm{target})
+
+where RHS are the other right-hand side terms. The parameters to be set by the user are -- `A` is the sponge amplitude, `n` is the sponge strength and the :math:`Q_\mathrm{target}` -- the target solution in the sponge. :math:`\xi` is a linear coordinate that is 0 at the beginning of the sponge and 1 at the end. An example of the sponge inputs can be found in ``Exec/RegTests/Terrain2d_Cylinder`` and is given below. This list of inputs specifies sponge zones in the inlet and outlet of the domain in the x-direction and the outlet of the domain in the z-direction. The `start` and `end` parameters specify the starting and ending of the sponge zones. At the inlet, the sponge starts at :math:`x=0` and at the outlet the sponge ends at :math:`x=L` -- the end of the domain. The sponge amplitude `A` has to be adjust
+ed in a problem-specific manner. The density and the :math:`x, y, z` velocities to be used in the sponge zones have to be specified in the inputs list.
+
+::
+
+          erf.sponge_strength = 10000.0
+          erf.use_xlo_sponge_damping = true
+          erf.xlo_sponge_end = 4.0
+          erf.use_xhi_sponge_damping = true
+          erf.xhi_sponge_start = 26.0
+          erf.use_zhi_sponge_damping = true
+          erf.zhi_sponge_start = 8.0
+
+          erf.sponge_density = 1.2
+          erf.sponge_x_velocity = 10.0
+          erf.sponge_y_velocity = 0.0
+          erf.sponge_z_velocity = 0.0
+
+Another way of specifying sponge zones is by providing the sponge zone data as a text file input. This is currently implemented only for forcing :math:`x` and :math:`y` velocities in the sponge zones.
+The sponge data is input as a text file with 3 columns containing :math:`z, u, v` values. An example can be found in ``Exec/SpongeTest`` and a sample inputs list for using this feature is given below. This list specifies a sponge zone in the inlet in the x-direction. The :math:`u` and :math:`v` velocity forcing in the sponge zones will be read in from the text file -- `input_sponge_file.txt`.
+
+::
+
+          erf.sponge_type = "input_sponge"
+          erf.input_sponge_file = "input_sponge_file.txt"
+          erf.sponge_strength = 1000.0
+          erf.use_xlo_sponge_damping = true
+          erf.xlo_sponge_end = 4.0
 
 Problem-Specific Forcing
 ========================
 
-There are two ways to specify background conditions to drive the simulation:
+The following two options can be used to specify external forcing terms.
 
 Pressure Gradient
 -----------------

Docs/sphinx_doc/theory/WetEquations.rst

@@ -48,7 +48,7 @@ The governing equations for this model are
   \frac{\partial (\rho_d q_c)}{\partial t} &= - \nabla \cdot (\rho_d \mathbf{u} q_c) + \nabla \cdot (\rho_d \alpha \nabla q_c) + f_{cond}
 
 Here :math:`L_v` is the latent heat of vaporization, :math:`\theta_d` is the (dry) potential temperature
-:math:`\mathbf{B}` is the buoyancy force, which is defined in :ref:`Buoyancy <Buoyancy>`.
+:math:`\mathbf{B}` is the buoyancy force, which is defined in :ref:`sec:Buoyancy <Buoyancy>`.
 
 The pressure perturbation is computed as
 
@@ -137,4 +137,4 @@ In this set of equations, the subgrid turbulent parameterization effects are inc
 :math:`F_\rho`, :math:`F_u`, :math:`F_C`, :math:`F_{\theta}`, :math:`F_{q_{T}}`, :math:`F_{q_{r}}`.
 :math:`\mathbf{F}` stands for the external force, and :math:`Q` and :math:`F_Q` represent the mass and energy transformation
 of water vapor to/from water through condensation/evaporation, which is determined by the microphysics parameterization processes.
-:math:`\mathbf{B}` is the buoyancy force, which is defined in :ref:`Buoyancy <Buoyancy>`.
+:math:`\mathbf{B}` is the buoyancy force, which is defined in :ref:`sec:Buoyancy <Buoyancy>`.

Docs/sphinx_doc/theory/WindFarmModels.rst

@@ -1,3 +1,6 @@
+
+.. _sec:WindFarmModels:
+
 Wind farm models
 ==================