update docs

seahorce-scidac · Dec 4, 2024 · 3b0271e · 3b0271e
1 parent 8d956c5
commit 3b0271e
Show file tree

Hide file tree

Showing 7 changed files with 220 additions and 588 deletions.
diff --git a/Docs/sphinx_doc/MeshRefinement.rst b/Docs/sphinx_doc/MeshRefinement.rst
@@ -157,14 +157,14 @@ does not account for loss of conservation due to diffusive or source terms.
 .. _sec:fillghost:
 
 Filling Ghost Values
-====================
+--------------------
 
 REMORA uses an operation called ``FillPatch`` to fill the ghost cells/faces for each grid of data.
 The data is filled outside the valid region with a combination of three operations: interpolation
 from coarser level, copy from same level, and enforcement of physical boundary conditions.
 
 Interpolation from Coarser level
---------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Interpolation is controlled by which interpolater we choose to use. The default is
 conservative interpolation for cell-centered quantities, and analogous for faces.
@@ -174,7 +174,7 @@ boundary conditions from the coarser level; all faces outside the valid region a
 similarly filled, while fine faces inside the valid region are not over-written.
 
 Copy from other grids at same level (includes periodic boundaries)
-------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This is part of the ``FillPatch`` operation, but can also be applied independently,
 e.g. by the call

diff --git a/Docs/sphinx_doc/Plotfiles.rst b/Docs/sphinx_doc/Plotfiles.rst
@@ -12,8 +12,7 @@ Plotfiles
 Controlling PlotFile Generation
 ===============================
 
-"Plotfiles" can be written very efficiently in parallel in a native AMReX format
-or in HDF5.  They can also be written in NetCDF.
+"Plotfiles" can be written very efficiently in parallel in a native AMReX format or NetCDF (via PnetCDF).
 
 The following options in the inputs file control the generation of plotfiles.
 
@@ -35,7 +34,7 @@ List of Parameters
 |                                | or one file for  |                       |            |
 |                                | all timesteps?   |                       |            |
 +--------------------------------+------------------+-----------------------+------------+
-| **remora.plot_file**           | prefix for       | String                | “*plt_*”   |
+| **remora.plot_file**           | prefix for       | String                | “*plt”     |
 |                                | plotfiles        |                       |            |
 +--------------------------------+------------------+-----------------------+------------+
 | **remora.plot_int**            | how often (by    | Integer               | -1         |

diff --git a/Docs/sphinx_doc/RegressionTests.rst b/Docs/sphinx_doc/RegressionTests.rst
diff --git a/Docs/sphinx_doc/Verification.rst b/Docs/sphinx_doc/Verification.rst
@@ -6,4 +6,67 @@
 Verification
 ============
 
-This section is a work in progress ... stay tuned
+The following test are used to verify the correct behavior of REMORA. Every problem below has a script ``test.sh``
+
+.. _advection:
+
+Advection
+---------
+
+The ``Advection`` problem tests scalar advection on a doubly-periodic domain with
+flat bathymetry.
+
+
+.. _channeltest:
+
+Channel Test
+------------
+
+The reentrant channel test of [paper] is reproduced. This problem tests the development of turbulence and GLS mixing scheme. The [quantity] agrees with that from ROMS.
+
+
+.. _doublegyre:
+
+Double Gyre
+-----------
+
+This reproduces the classic wind-driven double gyre problem, similar to the ROMS test problem by the same name.
+
+
+.. _doublyperiodic:
+
+Doubly Periodic
+---------------
+
+The basic version of this test simulates a flow with a depth-dependent horizontal velocity and temperature profile in a doubly-periodic domain with flat bathymetry. When non-flat bathymetry is used, the depth profile is the same as in the ROMS (and REMORA) Upwelling problem.
+
+.. _idealminigrid:
+
+Ideal Mini Grid
+---------------
+
+This small idealized grid is used to test netCDF-provided initial and boundary conditions. The ocean is initializaed with zero velocity and a constant temperature and salinity. Time-varying boundary conditions are then applied for velocity, temperature, or salinity (provided by netCDF file). The default is to used a clamped boundary condition for all quantities, but options for Chapman-Flather and radiation conditions are available. This test also verifies correct behavior with land-sea masking when using the ``_masked`` grid file.
+
+The netCDF files needed to run these tests can be found in the `remora-data`<https://github.com/seahorce-scidac/remora-data` repository under the ``IdealMiniGrid`` directory.
+
+.. _particlesseamount:
+
+Particles Over Seamount
+-----------------------
+
+This problem tests advection of tracer particles on a flat domain.
+
+.. _seamount:
+
+Seamount
+--------
+
+The `Seamount<https://www.myroms.org/wiki/SEAMOUNT_CASE>` problem involves an (analytically) stably stratified fluid at rest over a seamount. In the absence of numerical errors, the fluid will remain at rest. However, this may not occur due to numerical errors in the calculation of the horizontal pressure gradient when the vertical coordinates are misaligned with the geopotential surfaces, as is the case in problems with spatially-varying bathymetry in ROMS/REMORA.
+
+
+.. _upwelling:
+
+Upwelling
+---------
+
+The `Upwelling<https://www.myroms.org/wiki/UPWELLING_CASE>` demonstrates wind-driven upwelling over a perioidc channel. It closely matches the test problem by the same name in ROMS.
diff --git a/Docs/sphinx_doc/building.rst b/Docs/sphinx_doc/building.rst
@@ -23,13 +23,7 @@ Paradigm
 REMORA uses the paradigm that different executables are built in different subdirectories within the ``Exec`` directory.  When
 using gmake (see below), the user/developer should build in the directory of the selected problem.  When using
 cmake (see below), separate executables are built for all of the problem directories listed in ``Exec/CMakeLists.txt``.
-The problem directories within ``Exec`` include ``Upwelling`` a test case demonstrating a periodic channel with shelves on each side.
-#1) science-relevant setups, such as ``ABL`` for modeling the atmospheric
-#boundary layer or ``DensityCurrent`` for running the standard density current test case, etc, 2) regression tests in
-#``Exec/RegTests`` that are used for testing specific known aspects of the code functionality, such as boundary conditions or
-#Rayleigh damping, and 3) tests for features under development in ``Exec/DevTests``, such as moving terrain.  There is a
-#README in each problem directory that describes the purpose/role of that problem.
-
+The problem directories within ``Exec`` include a number of problems, which are also used for ::.
 
 NetCDF (Optional)
 ~~~~~~~~~~~~~~~~~
@@ -183,3 +177,4 @@ An example CMake configure command to build REMORA with MPI, PnetCDF, and partic
 
 Note that CMake is able to generate makefiles for the Ninja build system as well which will allow for faster building of the executable(s).
 
+.. include:: perlmutter.rst
diff --git a/Docs/sphinx_doc/index.rst b/Docs/sphinx_doc/index.rst
@@ -25,7 +25,7 @@ In addition to this documentation, there is API documentation for REMORA generat
    div#userguide.section,
    div#theory.section,
    div#implementation.section,
-   div#goals.section,
+   div#testing.section,
    </style>
 
 .. toctree::
@@ -39,13 +39,7 @@ In addition to this documentation, there is API documentation for REMORA generat
    :hidden:
 
    GettingStarted.rst
-   perlmutter.rst
    Inputs.rst
-   BoundaryConditions.rst
-   MeshRefinement.rst
-   Checkpoint.rst
-   Plotfiles.rst
-   Visualization.rst
    ProblemSetup.rst
 
 .. toctree::
@@ -56,24 +50,28 @@ In addition to this documentation, there is API documentation for REMORA generat
    theory/Variables.rst
    theory/Equations.rst
    theory/VerticalMixing.rst
-   Particles.rst
 
 .. toctree::
    :caption: IMPLEMENTATION
    :maxdepth: 1
    :hidden:
 
    ArakawaCGrid.rst
+   BoundaryConditions.rst
+   Checkpoint.rst
+   MeshRefinement.rst
    Numerical_Solution_Technique.rst
+   Particles.rst
+   Plotfiles.rst
    Time_Stepping.rst
    VerticalSCoord.rst
-..   Discretizations.rst
-..   BoundaryConditions.rst
+   Visualization.rst
 
 .. toctree::
    :caption: TESTING
    :maxdepth: 1
+   :hidden:
 
-   Verification.rst
    Performance.rst
    RegressionTests.rst
+   Verification.rst
diff --git a/Docs/sphinx_doc/perlmutter.rst b/Docs/sphinx_doc/perlmutter.rst
@@ -24,7 +24,7 @@ Then build REMORA as, for example (specify your own path to the AMReX submodule
 
 ::
 
-   make -j 4 COMP=gnu USE_MPI=TRUE USE_OMP=FALSE USE_CUDA=TRUE AMREX_HOME=/global/u2/d/dwillcox/dev-remora.REMORA/Submodules/AMReX
+   make -j 4 COMP=gnu USE_MPI=TRUE USE_OMP=FALSE USE_CUDA=TRUE AMREX_HOME=$HOME/dev-remora.REMORA/Submodules/AMReX
 
 Finally, you can prepare your SLURM job script, using the following as a guide:
 
@@ -74,7 +74,7 @@ Then build REMORA as, for example (specify your own path to the AMReX submodule
 
 ::
 
-   make -j 4 COMP=gnu USE_MPI=TRUE USE_OMP=TRUE USE_CUDA=FALSE AMREX_HOME=/global/u2/d/dwillcox/dev-remora.REMORA/Submodules/AMReX
+   make -j 4 COMP=gnu USE_MPI=TRUE USE_OMP=TRUE USE_CUDA=FALSE AMREX_HOME=$HOME/dev-remora.REMORA/Submodules/AMReX
 
 Finally, you can prepare your SLURM job script, using the following as a guide: