more updates to docs (#1307)

Docs/sphinx_doc/BoundaryConditions.rst

@@ -4,9 +4,12 @@
 
 .. _sec:LateralBoundaryConditions:
 
-Ideal Domain Boundary Conditions
+Domain Boundary Conditions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Ideal Domain BCs
+----------------------
+
 There are two primary types of physical/domain boundary conditions: those which rely only on the
 data in the valid regions, and those which rely on externally specified values.
 
@@ -136,8 +139,8 @@ It is important to note that external Dirichlet boundary data should be specifie
 as the value on the face of the cell bounding the domain, even for cell-centered
 state data.
 
-Specified Domain Boundary Conditions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Specified Domain BCs
+----------------------
 
 When we use specified lateral boundary conditions, we read time-dependent Dirichlet data
 from a file.  The user may specify (in the inputs file)
@@ -184,8 +187,8 @@ coarse data, and :math:`n` is the minimum number of grid points from a lateral b
 relaxation regions are applied to all dycore variables :math:`\left[\rho \; \rho\Theta \; U\; V\; W \right]`
 on the fine mesh.
 
-Sponge zone boundary conditions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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 specifed by the user in the inputs file.
 
@@ -196,15 +199,16 @@ ERF provides the capability to apply sponge zones at the boundaries to prevent s
 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 `Q_\mathrm{target}` - the target solution in the sponge. `\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``.
 
 ::
-    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
+
+          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

Docs/sphinx_doc/MOST.rst

@@ -193,28 +193,3 @@ In the above case, ``use_normal_vector`` utilizes the a local surface-normal vec
    \frac{1}{\tau} \int_{-\infty}^{0} \exp{\left(t/\tau\right)} \, f(t) \; \rm{d}t.
 
 Due to the form of the above integral, it is advantageous to consider :math:`\tau` as a multiple of the simulation time step :math:`\Delta t`, which is specified by ``erf.most.time_window``. As ``erf.most.time_window`` is reduced to 0, the exponential filter function tends to a Dirac delta function (prior averages are irrelevant). Increasing ``erf.most.time_window`` extends the tail of the exponential and more heavily weights prior averages.
-
-Sponge zone boundary conditions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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 specifed 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 `Q_\mathrm{target}` - the target solution in the sponge. `\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``.
-
-::
-    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

Docs/sphinx_doc/MeshRefinement.rst

@@ -131,27 +131,31 @@ ERF supports one-way, two-way, and "mixed" coupling between levels; this is a ru
       erf.coupling_type = "OneWay" or "TwoWay" or "Mixed"
 
 By one-way coupling, we mean that between each pair of refinement levels,
-the coarse mesh communicates data to the fine mesh to serve as boundary conditions
-for the time advance of the fine solution . For cell-centered quantities,
+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 mesh. 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. More specifically, similarly to how the lateral boundaries are treated,
-a user may specify the total width of the interior Dirichlet and relaxation region with
+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 Dirichlet region may be specified with
+and analogously the width of the interior specified (Dirichlet) region may be specified with
 ``erf.cf_set_width = <Int>`` (yellow).
 
-See :ref:`sec:BoundaryConditions` for the details of how the relaxation works; when
-used in the contect of mesh refinement we interpolate the specified values from the
-coarser level rather than reading them from the external file.
+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:
 
-By two-way coupling, we mean that in additional to specifying ghost cell data (outside of the valid fine region),
-the fine mesh communicates data back to the coarse mesh in two ways:
+- The fine cell-centered data are conservatively averaged onto the coarse mesh covered by fine mesh.
 
-- The fine cell-centered data is 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.
+- 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 define "mixed" coupling as using the two-way coupling algorithm for all cell-centered quantities except for
 :math:`\rho` and :math:`\rho \theta.`