From 8b54d94d5da9064bd3a77595fc8d2e102539066b Mon Sep 17 00:00:00 2001 From: Ann Almgren Date: Wed, 20 Nov 2024 12:44:19 -0800 Subject: [PATCH] more updates to docs --- Docs/sphinx_doc/ArakawaCGrid.rst | 21 ---------- Docs/sphinx_doc/Inputs.rst | 2 +- Docs/sphinx_doc/MapFactors.rst | 2 +- Docs/sphinx_doc/MeshRefinement.rst | 64 ++++++++---------------------- Docs/sphinx_doc/Meshing.rst | 40 +++++++++++++++++++ Docs/sphinx_doc/index.rst | 2 +- 6 files changed, 59 insertions(+), 72 deletions(-) delete mode 100644 Docs/sphinx_doc/ArakawaCGrid.rst create mode 100644 Docs/sphinx_doc/Meshing.rst diff --git a/Docs/sphinx_doc/ArakawaCGrid.rst b/Docs/sphinx_doc/ArakawaCGrid.rst deleted file mode 100644 index 6982d49be..000000000 --- a/Docs/sphinx_doc/ArakawaCGrid.rst +++ /dev/null @@ -1,21 +0,0 @@ - - .. role:: cpp(code) - :language: c++ - -.. _ArakawaCGrid: - -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 - diff --git a/Docs/sphinx_doc/Inputs.rst b/Docs/sphinx_doc/Inputs.rst index d2412baf6..f84be6fa0 100644 --- a/Docs/sphinx_doc/Inputs.rst +++ b/Docs/sphinx_doc/Inputs.rst @@ -1268,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. diff --git a/Docs/sphinx_doc/MapFactors.rst b/Docs/sphinx_doc/MapFactors.rst index 836089d35..bdbfbbd48 100644 --- a/Docs/sphinx_doc/MapFactors.rst +++ b/Docs/sphinx_doc/MapFactors.rst @@ -2,7 +2,7 @@ .. role:: cpp(code) :language: c++ -.. _MapFactors: +.. _sec:MapFactors: Map Factors (Dry) ============================= diff --git a/Docs/sphinx_doc/MeshRefinement.rst b/Docs/sphinx_doc/MeshRefinement.rst index efe1da1e5..b8ddd433a 100644 --- a/Docs/sphinx_doc/MeshRefinement.rst +++ b/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 = `` (yellow + blue) -and analogously the width of the interior specified (Dirichlet) region may be specified with -``erf.cf_set_width = `` (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. diff --git a/Docs/sphinx_doc/Meshing.rst b/Docs/sphinx_doc/Meshing.rst new file mode 100644 index 000000000..a88b93bae --- /dev/null +++ b/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 + diff --git a/Docs/sphinx_doc/index.rst b/Docs/sphinx_doc/index.rst index f15f931ee..1fd4a536c 100644 --- a/Docs/sphinx_doc/index.rst +++ b/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