Update the docs with new WOA23 initial condition

docs/developers_guide/command_line.rst

@@ -303,7 +303,7 @@ the step whose outputs should be cached:
 .. code-block:: bash
 
     compass cache -i ocean/global_ocean/QU240/mesh/mesh \
-        ocean/global_ocean/QU240/PHC/init/initial_state
+        ocean/global_ocean/QU240/WOA23/init/initial_state
 
 This will:
 
@@ -322,8 +322,8 @@ The resulting ``ocean_cached_files.json`` will look something like:
         "ocean/global_ocean/QU240/mesh/mesh/culled_mesh.nc": "global_ocean/QU240/mesh/mesh/culled_mesh.210803.nc",
         "ocean/global_ocean/QU240/mesh/mesh/culled_graph.info": "global_ocean/QU240/mesh/mesh/culled_graph.210803.info",
         "ocean/global_ocean/QU240/mesh/mesh/critical_passages_mask_final.nc": "global_ocean/QU240/mesh/mesh/critical_passages_mask_final.210803.nc",
-        "ocean/global_ocean/QU240/PHC/init/initial_state/initial_state.nc": "global_ocean/QU240/PHC/init/initial_state/initial_state.210803.nc",
-        "ocean/global_ocean/QU240/PHC/init/initial_state/init_mode_forcing_data.nc": "global_ocean/QU240/PHC/init/initial_state/init_mode_forcing_data.210803.nc"
+        "ocean/global_ocean/QU240/WOA23/init/initial_state/initial_state.nc": "global_ocean/QU240/WOA23/init/initial_state/initial_state.210803.nc",
+        "ocean/global_ocean/QU240/WOA23/init/initial_state/init_mode_forcing_data.nc": "global_ocean/QU240/WOA23/init/initial_state/init_mode_forcing_data.210803.nc"
     }
 
 An optional flag ``--date_string`` lets the developer set the date string to

docs/developers_guide/ocean/test_groups/global_ocean.rst

@@ -746,9 +746,9 @@ the mesh (e.g. metadata) by calling
 The test case includes 5 namelist replacement files and 3 streams files.
 ``namelist.init`` and ``streams.init`` modify the namelist options and set up
 the streams needed for the test case, regardless of the particular
-test group.  ``namelist.phc`` and ``namelist.en4_1900`` set namelist options
-specific to those two sets of input files.  ``namelist.wisc`` and
-``streams.wisc`` configure the test case for meshes that include
+test group.  ``namelist.woa23``, ``namelist.phc`` and ``namelist.en4_1900`` set
+namelist options specific to those 3 sets of input files.  ``namelist.wisc``
+and ``streams.wisc`` configure the test case for meshes that include
 :ref:`global_ocean_ice_shelf_cavities`, while ``namelist.bgc`` and
 ``streams.bgc`` are used to configure the test case when
 :ref:`global_ocean_bgc` is included.

docs/developers_guide/organization.rst

@@ -1658,7 +1658,7 @@ output, the following notation should be used:
 
     ocean/global_ocean/QU240/mesh
         cached
-    ocean/global_ocean/QU240/PHC/init
+    ocean/global_ocean/QU240/WOA23/init
         cached
 
 That is, the word ``cached`` should appear after the test case on its own line.
@@ -1672,7 +1672,7 @@ to be listed explicitly, as follows:
 
     ocean/global_ocean/QUwISC240/mesh
         cached: mesh
-    ocean/global_ocean/QUwISC240/PHC/init
+    ocean/global_ocean/QUwISC240/WOA23/init
         cached: initial_state ssh_adjustment
 
 The line can be indented for visual clarity, but must begin with ``cached:``,
@@ -1700,7 +1700,7 @@ own with the ``-t`` and ``--cached`` flags as follows:
 .. code-block:: none
 
     compass setup -t ocean/global_ocean/QU240/mesh --cached mesh ...
-    compass setup -t ocean/global_ocean/QU240/PHC/init --cached initial_state ...
+    compass setup -t ocean/global_ocean/QU240/WOA23/init --cached initial_state ...
     ...
 
 Cache files should be generated by first running the test case as normal, then

docs/developers_guide/overview.rst

@@ -277,7 +277,7 @@ the same conceptual test (e.g. restart) can be defined:
 
   * with or without ice-shelf cavities
 
-  * with the PHC or EN4 1900 initial conditions
+  * with the WOA23, PHC or EN4 1900 initial conditions
 
   * with or without BGC support
 

docs/users_guide/ocean/suites.rst

@@ -3,9 +3,10 @@
 Test suites
 ===========
 
-The ocean core currently includes 5 :ref:`test_suites` that can be used to
+The ocean core currently includes 16 :ref:`test_suites` that can be used to
 run a series of ocean test cases and optionally compare them against a baseline
-run of the same tests.
+run of the same tests.  Several are described below but several are missing
+from the documentation and should be added.
 
 .. _ocean_suite_nightly:
 
@@ -14,7 +15,7 @@ nightly test suite
 
 .. code-block:: bash
 
-    compass suite -c ocean -t nightly ...
+    compass suite -s -c ocean -t nightly ...
 
 The ``nightly`` test suite includes the following test cases:
 
@@ -26,25 +27,26 @@ The ``nightly`` test suite includes the following test cases:
     ocean/baroclinic_channel/10km/restart_test
 
     ocean/global_ocean/QU240/mesh
-    ocean/global_ocean/QU240/PHC/init
-    ocean/global_ocean/QU240/PHC/performance_test
-    ocean/global_ocean/QU240/PHC/restart_test
-    ocean/global_ocean/QU240/PHC/decomp_test
-    ocean/global_ocean/QU240/PHC/threads_test
-    ocean/global_ocean/QU240/PHC/analysis_test
+    ocean/global_ocean/QU240/WOA23/init
+    ocean/global_ocean/QU240/WOA23/performance_test
+    ocean/global_ocean/QU240/WOA23/restart_test
+    ocean/global_ocean/QU240/WOA23/decomp_test
+    ocean/global_ocean/QU240/WOA23/threads_test
+    ocean/global_ocean/QU240/WOA23/analysis_test
+
+    ocean/global_ocean/QU240/WOA23/RK4/performance_test
+    ocean/global_ocean/QU240/WOA23/RK4/restart_test
+    ocean/global_ocean/QU240/WOA23/RK4/decomp_test
+    ocean/global_ocean/QU240/WOA23/RK4/threads_test
 
-    ocean/global_ocean/QU240/PHC/RK4/performance_test
-    ocean/global_ocean/QU240/PHC/RK4/restart_test
-    ocean/global_ocean/QU240/PHC/RK4/decomp_test
-    ocean/global_ocean/QU240/PHC/RK4/threads_test
-
-    ocean/global_ocean/QU240/EN4_1900/init
-    ocean/global_ocean/QU240/EN4_1900/performance_test
-
-    ocean/global_ocean/QU240/PHC_BGC/init
-    ocean/global_ocean/QU240/PHC_BGC/performance_test
+    ocean/global_ocean/QUwISC240/mesh
+      cached
+    ocean/global_ocean/QUwISC240/WOA23/init
+      cached
+    ocean/global_ocean/QUwISC240/WOA23/performance_test
 
-    ocean/ice_shelf_2d/5km/restart_test
+    ocean/ice_shelf_2d/5km/z-star/restart_test
+    ocean/ice_shelf_2d/5km/z-level/restart_test
 
     ocean/ziso/20km/default
     ocean/ziso/20km/with_frazil
@@ -84,25 +86,25 @@ quwisc240 test suite
 
 .. code-block:: bash
 
-    compass suite -c ocean -t quwisc240 ...
+    compass suite -s -c ocean -t quwisc240 ...
 
 .. code-block:: none
 
     ocean/global_ocean/QUwISC240/mesh
-    ocean/global_ocean/QUwISC240/PHC/init
-    ocean/global_ocean/QUwISC240/PHC/performance_test
-    ocean/global_ocean/QUwISC240/PHC/restart_test
-    ocean/global_ocean/QUwISC240/PHC/decomp_test
-    ocean/global_ocean/QUwISC240/PHC/threads_test
-    ocean/global_ocean/QUwISC240/PHC/analysis_test
-    ocean/global_ocean/QUwISC240/PHC/RK4/performance_test
-    ocean/global_ocean/QUwISC240/PHC/RK4/restart_test
-    ocean/global_ocean/QUwISC240/PHC/RK4/decomp_test
-    ocean/global_ocean/QUwISC240/PHC/RK4/threads_test
+    ocean/global_ocean/QUwISC240/WOA23/init
+    ocean/global_ocean/QUwISC240/WOA23/performance_test
+    ocean/global_ocean/QUwISC240/WOA23/restart_test
+    ocean/global_ocean/QUwISC240/WOA23/decomp_test
+    ocean/global_ocean/QUwISC240/WOA23/threads_test
+    ocean/global_ocean/QUwISC240/WOA23/analysis_test
+    ocean/global_ocean/QUwISC240/WOA23/RK4/performance_test
+    ocean/global_ocean/QUwISC240/WOA23/RK4/restart_test
+    ocean/global_ocean/QUwISC240/WOA23/RK4/decomp_test
+    ocean/global_ocean/QUwISC240/WOA23/RK4/threads_test
     ocean/global_ocean/QUwISC240/EN4_1900/init
     ocean/global_ocean/QUwISC240/EN4_1900/performance_test
-    ocean/global_ocean/QUwISC240/PHC_BGC/init
-    ocean/global_ocean/QUwISC240/PHC_BGC/performance_test
+    ocean/global_ocean/QUwISC240/WOA23_BGC/init
+    ocean/global_ocean/QUwISC240/WOA23_BGC/performance_test
 
 This test suite performs exactly the same set of tests for the QUwISC240 mesh
 that are performed on the QU240 mesh in the :ref:`ocean_suite_nightly`.  Since
@@ -112,6 +114,79 @@ equilibrate (see :ref:`ocean_ssh_adjustment`), it is not included in the
 on a regular basis to ensure no unexpected changes to MPAS-Ocean and E3SM
 configurations with ice-shelf cavities.
 
+.. _ocean_suite_pr:
+
+pr test suite
+-------------
+
+.. code-block:: bash
+
+    compass suite -s -c ocean -t pr ...
+
+The ``nightly`` test suite includes the following test cases:
+
+.. code-block:: none
+
+
+    ocean/baroclinic_channel/10km/default
+    ocean/baroclinic_channel/10km/threads_test
+    ocean/baroclinic_channel/10km/decomp_test
+    ocean/baroclinic_channel/10km/restart_test
+
+    ocean/internal_wave/default
+    ocean/internal_wave/vlr/default
+
+    ocean/global_convergence/qu/cosine_bell
+      cached: QU60_mesh QU60_init QU90_mesh QU90_init QU120_mesh QU120_init
+      cached: QU150_mesh QU150_init QU180_mesh QU180_init QU210_mesh QU210_init
+      cached: QU240_mesh QU240_init
+
+    ocean/global_ocean/QU240/mesh
+    ocean/global_ocean/QU240/WOA23/init
+    ocean/global_ocean/QU240/WOA23/performance_test
+    ocean/global_ocean/QU240/WOA23/restart_test
+    ocean/global_ocean/QU240/WOA23/decomp_test
+    ocean/global_ocean/QU240/WOA23/threads_test
+    ocean/global_ocean/QU240/WOA23/analysis_test
+    ocean/global_ocean/QU240/WOA23/dynamic_adjustment
+
+    ocean/global_ocean/QU240/WOA23/RK4/performance_test
+    ocean/global_ocean/QU240/WOA23/RK4/restart_test
+    ocean/global_ocean/QU240/WOA23/RK4/decomp_test
+    ocean/global_ocean/QU240/WOA23/RK4/threads_test
+
+    ocean/global_ocean/QUwISC240/mesh
+      cached
+    ocean/global_ocean/QUwISC240/WOA23/init
+      cached
+    ocean/global_ocean/QUwISC240/WOA23/performance_test
+
+    ocean/global_ocean/EC30to60/mesh
+      cached
+    ocean/global_ocean/EC30to60/WOA23/init
+      cached
+    ocean/global_ocean/EC30to60/WOA23/performance_test
+
+    ocean/global_ocean/ECwISC30to60/mesh
+      cached
+    ocean/global_ocean/ECwISC30to60/WOA23/init
+      cached
+    ocean/global_ocean/ECwISC30to60/WOA23/performance_test
+
+    ocean/ice_shelf_2d/5km/z-star/restart_test
+    ocean/ice_shelf_2d/5km/z-level/restart_test
+
+    ocean/isomip_plus/planar/2km/z-star/Ocean0
+
+    ocean/ziso/20km/default
+    ocean/ziso/20km/with_frazil
+
+These are all meant to be slightly more comprehensive tests than `nightly`,
+to be compared to a baseline before a compass or MPAS-Ocean PR gest merged.
+They cover additional features such as convergence, higher resolution meshes,
+and vertical lagrangian remapping.
+
+
 .. _ocean_suite_qu240_for_e3sm:
 
 qu240_for_e3sm test suite
@@ -124,9 +199,9 @@ qu240_for_e3sm test suite
 .. code-block:: none
 
     ocean/global_ocean/QU240/mesh
-    ocean/global_ocean/QU240/PHC/init
-    ocean/global_ocean/QU240/PHC/dynamic_adjustment
-    ocean/global_ocean/QU240/PHC/files_for_e3sm
+    ocean/global_ocean/QU240/WOA23/init
+    ocean/global_ocean/QU240/WOA23/dynamic_adjustment
+    ocean/global_ocean/QU240/WOA23/files_for_e3sm
 
 This suite includes all the tests needed to spin up an initial condition for
 E3SM on the QU240 mesh.
@@ -143,9 +218,9 @@ quwisc240_for_e3sm test suite
 .. code-block:: none
 
     ocean/global_ocean/QUwISC240/mesh
-    ocean/global_ocean/QUwISC240/PHC/init
-    ocean/global_ocean/QUwISC240/PHC/dynamic_adjustment
-    ocean/global_ocean/QUwISC240/PHC/files_for_e3sm
+    ocean/global_ocean/QUwISC240/WOA23/init
+    ocean/global_ocean/QUwISC240/WOA23/dynamic_adjustment
+    ocean/global_ocean/QUwISC240/WOA23/files_for_e3sm
 
 This suite includes all the tests needed to spin up an initial condition for
 E3SM on the QUwISC240 mesh.
@@ -162,10 +237,10 @@ ec30to60 test suite
 .. code-block:: none
 
     ocean/global_ocean/EC30to60/mesh
-    ocean/global_ocean/EC30to60/PHC/init
-    ocean/global_ocean/EC30to60/PHC/performance_test
-    ocean/global_ocean/EC30to60/PHC/dynamic_adjustment
-    ocean/global_ocean/EC30to60/PHC/files_for_e3sm
+    ocean/global_ocean/EC30to60/WOA23/init
+    ocean/global_ocean/EC30to60/WOA23/performance_test
+    ocean/global_ocean/EC30to60/WOA23/dynamic_adjustment
+    ocean/global_ocean/EC30to60/WOA23/files_for_e3sm
 
 This suite is included for convenience so all the tests needed to spin up an
 initial condition for E3SM on the EC30to60 mesh can be run with a single
@@ -183,10 +258,10 @@ ecwisc30to60 test suite
 .. code-block:: none
 
     ocean/global_ocean/ECwISC30to60/mesh
-    ocean/global_ocean/ECwISC30to60/PHC/init
-    ocean/global_ocean/ECwISC30to60/PHC/performance_test
-    ocean/global_ocean/ECwISC30to60/PHC/dynamic_adjustment
-    ocean/global_ocean/ECwISC30to60/PHC/files_for_e3sm
+    ocean/global_ocean/ECwISC30to60/WOA23/init
+    ocean/global_ocean/ECwISC30to60/WOA23/performance_test
+    ocean/global_ocean/ECwISC30to60/WOA23/dynamic_adjustment
+    ocean/global_ocean/ECwISC30to60/WOA23/files_for_e3sm
 
 Similarly to the previous 3 suites, this suite is included for convenience so
 all the tests needed to spin up an initial condition for E3SM on the

docs/users_guide/ocean/test_groups/global_ocean.rst

@@ -504,34 +504,30 @@ in :ref:`global_ocean_meshes`.  Possible grid types are described in
 :ref:`ocean_vertical` and include ``uniform``, ``tanh_dz``, ``index_tanh_dz``,
 ``60layerPHC``, ``80layerE3SMv1``, and ``100layerE3SMv1``.
 
-compass supports two different types of initial conditions.  One is derived
+compass supports 3 different types of initial conditions.  One is the
+World Ocean Atlas 2023
+(`WOA23 <https://www.ncei.noaa.gov/products/world-ocean-atlas>`_)
+climatology from 1991-2020. The second is derived
 from the Polar science center Hydrographic Climatology
 (`PHC <http://psc.apl.washington.edu/nonwp_projects/PHC/Climatology.html>`_).
-The other is the UK MetOffice's EN4 estimated climatology for the year 1900
+The last is the UK MetOffice's EN4 estimated climatology for the year 1900
 (`EN4_1900 <https://www.metoffice.gov.uk/hadobs/en4/download-en4-2-0.html>`_).
 
-Either initial condition can also be combined with ecosystem tracers used in
-simulations with active :ref:`global_ocean_bgc` if ocean biogeochemsitry is
-enabled.  This dataset is from <<<need some help here!!!>>>.
+All subsequent tests (:ref:`global_ocean_performance_test`,
+:ref:`global_ocean_restart_test`, etc.) could potentially start from any of
+these initial conditions, meaning that a performance test starting from WOA23
+should be thought of as a different test from one starting from PHC.
+Therefore, it is convenient to house the ``init`` test case and all subsequent
+test cases that depend on it within a subdirectory with the name of the initial
+condition.  The relative paths associate with each initial condition for a
+given ``<mesh>`` are:
 
-Thus, there are 4 combinations of initial conditions, ``PHC``, ``PHC_BGC``,
-``EN4_1900`` and ``EN4_1900_BGC``.  All subsequent tests
-(:ref:`global_ocean_performance_test`, :ref:`global_ocean_restart_test`, etc.)
-could potentially start from any of these initial conditions, meaning that
-a performance test starting from PHC should be thought of as a different test
-from one starting from EN4_1900.  Therefore, it is convenient to house both
-the ``init`` test case and all subsequent test cases that depend on it within
-a subdirectory with the name of the initial condition.  The relative paths
-associate with each initial condition for a given ``<mesh>`` are:
+* ``ocean/global_ocean/<mesh>/WOA23/init``
 
 * ``ocean/global_ocean/<mesh>/PHC/init``
 
-* ``ocean/global_ocean/<mesh>/PHC_BGC/init``
-
 * ``ocean/global_ocean/<mesh>/EN4_1900/init``
 
-* ``ocean/global_ocean/<mesh>/EN4_1900_BGC/init``
-
 .. _global_ocean_performance_test:
 
 performance_test test case