From c5ca2f56c10ebf01413be403fa61926f87011336 Mon Sep 17 00:00:00 2001 From: Ann Almgren Date: Wed, 20 Nov 2024 12:32:11 -0800 Subject: [PATCH 1/4] more updates to docs --- Docs/sphinx_doc/BoundaryConditions.rst | 2 +- Docs/sphinx_doc/Inputs.rst | 7 +++++++ Docs/sphinx_doc/theory/Forcings.rst | 6 +++--- 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/Docs/sphinx_doc/BoundaryConditions.rst b/Docs/sphinx_doc/BoundaryConditions.rst index 3c7d6b4b2..3e4e08984 100644 --- a/Docs/sphinx_doc/BoundaryConditions.rst +++ b/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 ---------------------- diff --git a/Docs/sphinx_doc/Inputs.rst b/Docs/sphinx_doc/Inputs.rst index 20b31d201..d2412baf6 100644 --- a/Docs/sphinx_doc/Inputs.rst +++ b/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 calcluation. +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 diff --git a/Docs/sphinx_doc/theory/Forcings.rst b/Docs/sphinx_doc/theory/Forcings.rst index 1c55cb9dd..09260a5a6 100644 --- a/Docs/sphinx_doc/theory/Forcings.rst +++ b/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. @@ -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. From 8b54d94d5da9064bd3a77595fc8d2e102539066b Mon Sep 17 00:00:00 2001 From: Ann Almgren Date: Wed, 20 Nov 2024 12:44:19 -0800 Subject: [PATCH 2/4] 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 From c366a20018c5585631ed09df4c65413238356312 Mon Sep 17 00:00:00 2001 From: Ann Almgren Date: Wed, 20 Nov 2024 12:47:23 -0800 Subject: [PATCH 3/4] fix typo --- Docs/sphinx_doc/Inputs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Docs/sphinx_doc/Inputs.rst b/Docs/sphinx_doc/Inputs.rst index f84be6fa0..0148228c8 100644 --- a/Docs/sphinx_doc/Inputs.rst +++ b/Docs/sphinx_doc/Inputs.rst @@ -415,7 +415,7 @@ 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 calcluation. +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. From 7458acd172137d475f590376ddd3c53056fa7616 Mon Sep 17 00:00:00 2001 From: Ann Almgren Date: Wed, 20 Nov 2024 12:49:25 -0800 Subject: [PATCH 4/4] fix typo --- Docs/sphinx_doc/theory/Forcings.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Docs/sphinx_doc/theory/Forcings.rst b/Docs/sphinx_doc/theory/Forcings.rst index 09260a5a6..3e46a8439 100644 --- a/Docs/sphinx_doc/theory/Forcings.rst +++ b/Docs/sphinx_doc/theory/Forcings.rst @@ -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.