From 8edf33af551afeb3e9afef25092ad01d8692e075 Mon Sep 17 00:00:00 2001 From: Hannah Klion Date: Wed, 18 Dec 2024 10:45:47 -0800 Subject: [PATCH] add readmes to problems and tweak docs --- Docs/sphinx_doc/GettingStarted.rst | 2 -- Docs/sphinx_doc/Verification.rst | 24 +++++++++--------------- Docs/sphinx_doc/index.rst | 2 +- Exec/Advection/README | 6 ++++++ Exec/Channel_Test/README | 3 +++ Exec/DoubleGyre/README | 2 ++ Exec/DoublyPeriodic/README | 6 ++++++ Exec/IdealMiniGrid/README.rst | 13 +++++++++++++ Exec/ParticlesOverSeaMount/README | 1 + Exec/Seamount/README.rst | 9 +++++++++ Exec/Upwelling/README.rst | 3 +++ 11 files changed, 53 insertions(+), 18 deletions(-) create mode 100644 Exec/Advection/README create mode 100644 Exec/Channel_Test/README create mode 100644 Exec/DoubleGyre/README create mode 100644 Exec/DoublyPeriodic/README create mode 100644 Exec/IdealMiniGrid/README.rst create mode 100644 Exec/ParticlesOverSeaMount/README create mode 100644 Exec/Seamount/README.rst create mode 100644 Exec/Upwelling/README.rst diff --git a/Docs/sphinx_doc/GettingStarted.rst b/Docs/sphinx_doc/GettingStarted.rst index 9f1396c3..fbf8c9ca 100644 --- a/Docs/sphinx_doc/GettingStarted.rst +++ b/Docs/sphinx_doc/GettingStarted.rst @@ -29,5 +29,3 @@ type: .. include:: building.rst .. include:: InputFiles.rst - -.. include:: testing.rst diff --git a/Docs/sphinx_doc/Verification.rst b/Docs/sphinx_doc/Verification.rst index c358d4da..aabe0ab9 100644 --- a/Docs/sphinx_doc/Verification.rst +++ b/Docs/sphinx_doc/Verification.rst @@ -6,15 +6,14 @@ Verification ============ -The following test are used to verify the correct behavior of REMORA. Every problem below has a script ``test.sh`` +The following test are used to verify the correct behavior of REMORA. Each problem below has a subdirectory in ``Exec``, which contains a sample ``inputs`` file and a ``README``, the contents of which are reproduced below: .. _advection: Advection --------- -The ``Advection`` problem tests scalar advection on a doubly-periodic domain with -flat bathymetry. +.. include:: ../../Exec/Advection/README .. _channeltest: @@ -22,51 +21,46 @@ flat bathymetry. 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. - +.. include:: ../../Exec/Channel_Test/README .. _doublegyre: Double Gyre ----------- -This reproduces the classic wind-driven double gyre problem, similar to the ROMS test problem by the same name. - +.. include:: ../../Exec/DoubleGyre/README .. _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. +.. include:: ../../Exec/DoublyPeriodic/README .. _idealminigrid: Ideal Mini Grid --------------- -This small idealized grid is used to test netCDF-provided initial and boundary conditions. The ocean is initialized 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 `_ repository under the ``IdealMiniGrid`` directory. +.. include:: ../../Exec/IdealMiniGrid/README.rst .. _particlesseamount: Particles Over Seamount ----------------------- -This problem tests advection of tracer particles on a flat domain. +.. include:: ../../Exec/ParticlesOverSeaMount/README .. _seamount-desc: Seamount -------- -The `Seamount `_ 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. - +.. include:: ../../Exec/Seamount/README.rst .. _upwelling-desc: Upwelling --------- -The `Upwelling `_ demonstrates wind-driven upwelling over a perioidc channel. It closely matches the test problem by the same name in ROMS. +.. include:: ../../Exec/Upwelling/README.rst diff --git a/Docs/sphinx_doc/index.rst b/Docs/sphinx_doc/index.rst index bef6a9a6..22899e4b 100644 --- a/Docs/sphinx_doc/index.rst +++ b/Docs/sphinx_doc/index.rst @@ -3,7 +3,7 @@ REMORA ------ -REMORA is currently under development as a next-generation version of the Regional Ocean Modeling System (ROMS). +REMORA is currently under development as a next-generation version of the Regional Ocean Modeling System (ROMS). The source code repository is hosted on `Github `_. Questions and issues with the code can be directed to the developers by opening an Issue on the Github page. See our `Contributing `_ page for how to contribute code to the repository. REMORA is built on `AMReX `_, an adaptive mesh refinement software framework, which provides the underlying software infrastructure for diff --git a/Exec/Advection/README b/Exec/Advection/README new file mode 100644 index 00000000..a54a6fd0 --- /dev/null +++ b/Exec/Advection/README @@ -0,0 +1,6 @@ +The Advection problem tests scalar advection of a gaussian concentration +distribution on a doubly-periodic domain with flat bathymetry. + +The file called inputs contains the single-level version of this test. The +file called inputs_ml runs the problem with adaptive mesh refinement, refining +where the scalar has a value greater than 0.5. diff --git a/Exec/Channel_Test/README b/Exec/Channel_Test/README new file mode 100644 index 00000000..c9f613cd --- /dev/null +++ b/Exec/Channel_Test/README @@ -0,0 +1,3 @@ +This problem reproduces the reentrant channel test case from []. It tests +the development of turbulence and the GLS mixing scheme. The mean surface +kinetic energy agrees with that from ROMS. diff --git a/Exec/DoubleGyre/README b/Exec/DoubleGyre/README new file mode 100644 index 00000000..a668527c --- /dev/null +++ b/Exec/DoubleGyre/README @@ -0,0 +1,2 @@ +The DoubleGyre problem reproduces the classic wind-driven double gyre problem, +similar to the ROMS test problem by the same name. diff --git a/Exec/DoublyPeriodic/README b/Exec/DoublyPeriodic/README new file mode 100644 index 00000000..2b4b5520 --- /dev/null +++ b/Exec/DoublyPeriodic/README @@ -0,0 +1,6 @@ +The basic version of the DoublyPerioidic 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. + diff --git a/Exec/IdealMiniGrid/README.rst b/Exec/IdealMiniGrid/README.rst new file mode 100644 index 00000000..e6c8e99f --- /dev/null +++ b/Exec/IdealMiniGrid/README.rst @@ -0,0 +1,13 @@ +This small idealized grid is used to test netCDF-provided initial and boundary +conditions. The ocean is initialized 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 `_ +repository under the ``IdealMiniGrid`` directory. + diff --git a/Exec/ParticlesOverSeaMount/README b/Exec/ParticlesOverSeaMount/README new file mode 100644 index 00000000..2a44a022 --- /dev/null +++ b/Exec/ParticlesOverSeaMount/README @@ -0,0 +1 @@ +This problem tests advection of tracer particles on a flat domain. diff --git a/Exec/Seamount/README.rst b/Exec/Seamount/README.rst new file mode 100644 index 00000000..179aa544 --- /dev/null +++ b/Exec/Seamount/README.rst @@ -0,0 +1,9 @@ +The Seamount problem is a standard test in +`ROMS `_. +The 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. + diff --git a/Exec/Upwelling/README.rst b/Exec/Upwelling/README.rst new file mode 100644 index 00000000..4ac95ee7 --- /dev/null +++ b/Exec/Upwelling/README.rst @@ -0,0 +1,3 @@ +The Upwelling problem is set up as in +`ROMS `_. It demonstrates +wind-driven upwelling over a perioidc channel.