Fix ref

Docs/sphinx_doc/BoundaryConditions.rst

@@ -13,7 +13,7 @@ ERF also has the option to run precursor simulations, save planes of data at spe
 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. 
+Time-varying sea surface temperatures may also be employed in conjunction with MOST.
 
 Ideal Domain BCs
 ----------------------

Docs/sphinx_doc/Inputs.rst

@@ -413,6 +413,13 @@ the number of level-0 steps taken equals 1000, whichever comes first.
 Time Step
 =========
 
+The solver timestep can be fixed by the user or computed dynamically at each timestep based on the user-specified CFL
+number --- i.e., adaptive time stepping. For the compressible equations, the timestep calculation uses the acoustic CFL constraint.
+We note that when using implicit substepping, the vertical mesh spacing does not appear in the time step calculation.
+The number of acoustic sub-steps per timestep can also be specified by the user as a fixed value or by specifying the
+number of substeps per RK stage.  For the anelastic equations, the timestep calculation uses the advective CFL constraint,
+which means it is determined by the fluid speed rather than the sound speed and thus allows much larger timesteps.
+
 .. _list-of-parameters-6:
 
 List of Parameters
@@ -1261,7 +1268,7 @@ methods for defining how the terrain-fitted coordinates given the topography:
 
 - Basic Terrain Following (BTF):
     The influence of the terrain decreases linearly with height.
-- Smoothed Terrain Following (STF):
+-  Smoothed Terrain Following (STF):
     Small-scale terrain structures are progressively smoothed out of the coordinate system as height increases.
 - Sullivan Terrain Following (name TBD):
     The influence of the terrain decreases with the cube of height.

Docs/sphinx_doc/MapFactors.rst

@@ -2,7 +2,7 @@
  .. role:: cpp(code)
     :language: c++
 
-.. _MapFactors:
+.. _sec:MapFactors:
 
 Map Factors (Dry)
 =============================

Docs/sphinx_doc/MeshRefinement.rst

@@ -7,10 +7,22 @@
 Mesh Refinement
 ===============
 
-ERF allows both static and dynamic mesh refinement, as well as the choice of one-way or two-way coupling.
-Dynamic refinement is currently only allowed when terrain is not being used.
-
-The refinement ratio is specified by the user at runtime. Refinement is not allowed in the vertical.
+ERF also allows both dynamic and static mesh refinement with sub-cycling in time at finer levels of refinement.
+Arbitrary integer refinement ratios are allowed although typically ratios of 2, 3 or 4 are used; refinement can also be anisotropic,
+allowing refinement in one coordinate direction but not another.
+
+We utilize two-way coupling, in which the coarse solution is used to provide boundary conditions for the fine solution
+and the fine solution is averaged down onto the coarser level.  In addition, we reflux all advected scalars to ensure conservation.
+For coarse-to-fine communication we provide ``ghost cell'' data for cell-centered data and tangential momentum components to
+the fine level by interpolating in space and time outside the region covered by the fine level.
+We also interpolate the normal momentum from coarse to fine on the coarse-fine interface itself;
+this ensures mass conservation since the normal momentum is in fact the flux for the density field.
+In order to ensure that the fine momentum on the coarse-fine boundary stays consistent with the
+interpolated coarse values throughout a fine timestep, we also interpolate the source term for
+the normal momentum on the coarse-fine interface.
+When using the anelastic approximation, this ensures that the computation of the updates to the
+fine momentum do not use any values of the perturbational pressure from the coarser level since
+the perturbational pressure is not synchronized between levels.
 
 Note that any tagged region will be covered by one or more boxes.  The user may
 specify the refinement criteria and/or region to be covered, but not the decomposition of the region into
@@ -141,47 +153,3 @@ computed by dividing the variable named rhotheta by the variable named density.
           erf.advdiff.field_name = rhoadv_0
           erf.advdiff.start_time = 0.001
           erf.advdiff.end_time = 0.002
-
-Coupling Types
---------------
-
-ERF supports one-way and two-way coupling between levels; this is a run-time input
-
-::
-
-      erf.coupling_type = "OneWay" or "TwoWay"
-
-By one-way coupling, we mean that between each pair of refinement levels,
-the coarse level communicates data to the fine level to serve as boundary conditions
-for the time advance of the fine solution. For cell-centered quantities,
-and face-baced normal momenta on the coarse-fine interface, the coarse data is conservatively
-interpolated to the fine level.
-
-The interpolated data is utilized to specify ghost cell data (outside of the valid fine region)
-as well as specified data inside the lateral boundaries of the fine region.
-See :ref:`sec:LateralBoundaryConditions` for the details of how the relaxation works; when
-used in the context of mesh refinement we fill the specified values by interpolation from the
-coarser level rather than reading from the external file. For coarse/fine boundaries,
-a user may specify the total width of the interior specified (Dirichlet) and relaxation region with
-``erf.cf_width = <Int>`` (yellow + blue)
-and analogously the width of the interior specified (Dirichlet) region may be specified with
-``erf.cf_set_width = <Int>`` (yellow).
-
-Setting ``erf.cf_set_width = 0`` designates that we interpolate the momenta
-at faces only on the coarse-fine boundary itself; no interior cell-centered data, or momenta
-inside the fine region, are filled from the coarser level.
-
-By two-way coupling, we mean that in additional to interpolating data from the coarser level
-to supply boundary conditions for the fine regions,
-the fine level also communicates data back to the coarse level in two ways:
-
-- The fine cell-centered data are conservatively averaged onto the coarse mesh covered by fine mesh.
-
-- The fine momenta are conservatively averaged onto the coarse faces covered by fine mesh.
-
-- A "reflux" operation is performed for all cell-centered data; this updates values on the coarser
-  level outside of regions covered by the finer level.
-
-We note that when one-way coupling is used, quantities which are advanced in conservation form
-potentially violate global conservation.  Two-way coupling ensures conservation of mass, and of the advective contribution
-to all scalar updates, but does not account for loss of conservation due to diffusive or source terms.

Docs/sphinx_doc/Meshing.rst

@@ -0,0 +1,40 @@
+
+ .. role:: cpp(code)
+    :language: c++
+
+.. _sec:Meshing:
+
+Meshing
+==============
+
+The spatial discretization in ERF uses the classic Arakawa C-grid with
+scalar quantities at cell centers and normal velocities at cell faces.
+Simulations over complex topography use a terrain-following, height-based vertical coordinate.
+When terrain-following coordinates are used, the surface topography at nodes (cell corners)
+is specified either analytically or through parsing a text file; all metric terms derive from this quantity.
+
+As in many atmospheric modeling codes, variable mesh spacing in the vertical direction is allowed with or without terrain.
+The heights of each level can be parsed from a text file as ``z levels'' (as in WRF), or calculated at run-time given an
+initial mesh spacing at the bottom surface and a specified growth rate.  In the presence of non-flat terrain, the mesh is
+modified so that it fits the specified terrain at the bottom of the computational domain, and relaxes to flat at the top of the domain.
+Three approaches to this are offered in ERF: Basic Terrain Following (BTF), in which the influence of the terrain decreases
+linearly with height;  Smoothed Terrain Following (STF), in which small-scale terrain structures are progressively smoothed out
+of the coordinate system as height increases; or Sullivan Terrain Following (Sullivan), in which the influence of the terrain
+decreases with the cube of height.  Additionally, ERF includes the capability to apply several common
+isotropic map projections (e.g., Lambert Conformal, Mercator); see :ref:`sec:MapFactors` for more details.
+
+Arakawa C-Grid
+==============
+Variables are located on Arakawa C-grid as pictured in the images below.
+
+.. image:: figures/grid_discretization/Arakawa_1.png
+  :width: 400
+.. image:: figures/grid_discretization/Arakawa_2.png
+  :width: 400
+.. image:: figures/grid_discretization/Arakawa_3.png
+  :width: 400
+.. image:: figures/grid_discretization/Arakawa_4.png
+  :width: 400
+.. image:: figures/grid_discretization/Arakawa_5.png
+  :width: 400
+

Docs/sphinx_doc/index.rst

@@ -63,7 +63,7 @@ In addition to this documentation, there is API documentation for ERF generated
    :maxdepth: 1
 
    AMReX.rst
-   ArakawaCGrid.rst
+   Meshing.rst
    MapFactors.rst
    TimeAdvance.rst
    Discretizations.rst

Docs/sphinx_doc/theory/Forcings.rst

@@ -12,12 +12,12 @@ Physical Forcings
 
 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.  
+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. 
+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.
 
@@ -52,7 +52,7 @@ where :math:`C_f = 4 \pi / P_{rot}` is the Coriolis factor with :math:`P_{rot}`
 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.
+to compute the Coriolis frequency 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.
 
@@ -92,7 +92,7 @@ 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 
+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.