From 61f7cd4f5bddfddb22cfe315e84c662d88dc71b2 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Tue, 27 Feb 2024 15:15:36 -0600 Subject: [PATCH] Update docs --- docs/design_docs/cached_outputs.rst | 30 ++++++------ docs/design_docs/compass_package.rst | 2 +- docs/developers_guide/ocean/api.rst | 4 +- .../ocean/test_groups/global_ocean.rst | 45 +++++++++--------- docs/users_guide/config_files.rst | 2 +- .../ocean/test_groups/global_ocean.rst | 14 +++--- .../images/{wc14.png => narrm14.png} | Bin docs/users_guide/quick_start.rst | 4 +- docs/users_guide/test_suites.rst | 4 +- 9 files changed, 53 insertions(+), 52 deletions(-) rename docs/users_guide/ocean/test_groups/images/{wc14.png => narrm14.png} (100%) diff --git a/docs/design_docs/cached_outputs.rst b/docs/design_docs/cached_outputs.rst index 4548bd461c..8418fc9273 100644 --- a/docs/design_docs/cached_outputs.rst +++ b/docs/design_docs/cached_outputs.rst @@ -35,7 +35,7 @@ Contributors: Xylar Asay-Davis Each ``compass`` step defines its output files in the ``compass.Step.outputs`` attribute. For selected steps (see :ref:`req_select`), we require a mechanism to download cached files for each of these outputs and to use these cached -files for the outputs of the step instead of computing them. +files for the outputs of the step instead of computing them. .. _req_select: @@ -48,7 +48,7 @@ Contributors: Xylar Asay-Davis There needs to be a mechanism for developers and users to select which steps are run as normal and which use cached outputs. For this mechanism to be -practical, it should not be overly tedious or manual (e.g. manually setting a +practical, it should not be overly tedious or manual (e.g. manually setting a flag for each step). .. _req_update: @@ -72,11 +72,11 @@ Date last modified: 2021/07/30 Contributors: Xylar Asay-Davis -There should be a mechanism for giving each cached output file a unique -identifier (such as a date stamp). A given version (git hash or release) of +There should be a mechanism for giving each cached output file a unique +identifier (such as a date stamp). A given version (git hash or release) of ``compass`` should know which cached files to download. Older cached files should be retained so that older versions of ``compass`` can still be used -with these cached files. +with these cached files. .. note:: @@ -109,14 +109,14 @@ Date last modified: 2021/07/30 Contributors: Xylar Asay-Davis -``compass`` supports "databases" of input data files on the E3SM +``compass`` supports "databases" of input data files on the E3SM `LCRC server `_. -Files will be stored in a new ``compass_cache`` database within each MPAS +Files will be stored in a new ``compass_cache`` database within each MPAS core's space on that server. If the "cached" version of a step is selected -(see :ref:`des_select`), an appropriate "input" file will be added to the test +(see :ref:`des_select`), an appropriate "input" file will be added to the test case where the "target" is the file on the LCRC server to be cached locally for future use and the "filename" is the output file. ``compass`` will know which -files on the server correspond to which output files via a python dictionary, +files on the server correspond to which output files via a python dictionary, as described in :ref:`des_unique`. .. _des_select: @@ -403,9 +403,9 @@ The implementation leans heavily on the assumption that a given step will either be run with cached outputs or as normal, so that both versions are not available in the same work directory or as part of the same test suite. -Nevertheless, if a separate "cached" version of a step were desired, it would -be necessary to make symlinks from the cached files in the location of the -"uncached" version of the step to the location of the "cached" version. For +Nevertheless, if a separate "cached" version of a step were desired, it would +be necessary to make symlinks from the cached files in the location of the +"uncached" version of the step to the location of the "cached" version. For example, if the "uncached" step is .. code-block:: none @@ -422,7 +422,7 @@ symlinks could be created on the LCRC server, e.g. .. code-block:: none - /lcrc/group/e3sm/public_html/mpas_standalonedata/mpas-ocean/compass_cache/global_ocean/QU240/cached/mesh/mesh/culled_mesh.210803.nc + /lcrc/group/e3sm/public_html/mpas_standalonedata/mpas-ocean/compass_cache/global_ocean/QU240/cached/mesh/mesh/culled_mesh.210803.nc -> /lcrc/group/e3sm/public_html/mpas_standalonedata/mpas-ocean/compass_cache/global_ocean/QU240/mesh/mesh/culled_mesh.210803.nc and the ``cached`` attribute could be set to ``True`` in the constructor of the @@ -452,8 +452,8 @@ using test-case runs on Chrysalis. ocean/global_ocean/QUwISC240/PHC/init/ssh_adjustment/ ocean/global_ocean/EC30to60/mesh/mesh/ ocean/global_ocean/EC30to60/PHC/init/initial_state/ - ocean/global_ocean/WC14/mesh/mesh/ - ocean/global_ocean/WC14/PHC/init/initial_state/ + ocean/global_ocean/NARRM14/mesh/mesh/ + ocean/global_ocean/NARRM14/PHC/init/initial_state/ ocean/global_ocean/ECwISC30to60/mesh/mesh/ ocean/global_ocean/ECwISC30to60/PHC/init/initial_state/ ocean/global_ocean/ECwISC30to60/PHC/init/ssh_adjustment/ diff --git a/docs/design_docs/compass_package.rst b/docs/design_docs/compass_package.rst index b9a55cdb2e..824cee8bf5 100644 --- a/docs/design_docs/compass_package.rst +++ b/docs/design_docs/compass_package.rst @@ -1550,7 +1550,7 @@ metadata to include in the output files: forward_max_disk = 1000 ## metadata related to the mesh - # the prefix (e.g. QU, EC, WC, SO) + # the prefix (e.g. QU, EC, NARRM, SO) prefix = EC # a description of the mesh and initial condition mesh_description = MPAS Eddy Closure mesh for E3SM version ${e3sm_version} with diff --git a/docs/developers_guide/ocean/api.rst b/docs/developers_guide/ocean/api.rst index edb7822257..0074d2925a 100644 --- a/docs/developers_guide/ocean/api.rst +++ b/docs/developers_guide/ocean/api.rst @@ -239,8 +239,8 @@ test cases and steps mesh.so12to60.SO12to60BaseMesh mesh.so12to60.SO12to60BaseMesh.build_cell_width_lat_lon - mesh.wc14.WC14BaseMesh - mesh.wc14.WC14BaseMesh.build_cell_width_lat_lon + mesh.narrm14.NARRM14BaseMesh + mesh.narrm14.NARRM14BaseMesh.build_cell_width_lat_lon performance_test.PerformanceTest performance_test.PerformanceTest.configure diff --git a/docs/developers_guide/ocean/test_groups/global_ocean.rst b/docs/developers_guide/ocean/test_groups/global_ocean.rst index 387290e9d8..66937e9730 100644 --- a/docs/developers_guide/ocean/test_groups/global_ocean.rst +++ b/docs/developers_guide/ocean/test_groups/global_ocean.rst @@ -46,7 +46,7 @@ The values of some of the metadata are given in config options: ## metadata related to the mesh # whether to add metadata to output files add_metadata = True - # the prefix (e.g. QU, EC, WC, SO) + # the prefix (e.g. QU, EC, NARRM, SO) prefix = PREFIX # a description of the mesh mesh_description = <<>> @@ -87,7 +87,7 @@ defines: ... ## metadata related to the mesh - # the prefix (e.g. QU, EC, WC, SO) + # the prefix (e.g. QU, EC, NARRM, SO) prefix = EC # a description of the mesh and initial condition mesh_description = MPAS Eddy Closure mesh for E3SM version ${e3sm_version} with @@ -371,7 +371,7 @@ The default config options for these meshes are: approx_cell_count = 7400 ## metadata related to the mesh - # the prefix (e.g. QU, EC, WC, SO) + # the prefix (e.g. QU, EC, NARRM, SO) prefix = QU # a description of the mesh mesh_description = MPAS quasi-uniform mesh for E3SM version ${e3sm_version} at @@ -454,7 +454,7 @@ The default config options for these meshes are: [global_ocean] ## metadata related to the mesh - # the prefix (e.g. QU, EC, WC, SO) + # the prefix (e.g. QU, EC, NARRM, SO) prefix = QU # a description of the mesh @@ -486,7 +486,7 @@ corresponding QU config options above: [global_ocean] ## metadata related to the mesh - # the prefix (e.g. QU, EC, WC, SO) + # the prefix (e.g. QU, EC, NARRM, SO) prefix = Icos # a description of the mesh @@ -552,7 +552,7 @@ The default config options for these meshes are: approx_cell_count = 240000 ## metadata related to the mesh - # the prefix (e.g. QU, EC, WC, SO) + # the prefix (e.g. QU, EC, NARRM, SO) prefix = EC # a description of the mesh and initial condition mesh_description = MPAS Eddy Closure mesh for E3SM version ${e3sm_version} with @@ -612,7 +612,7 @@ module: [global_ocean] ## metadata related to the mesh - # the prefix (e.g. QU, EC, WC, SO, Kuroshio) + # the prefix (e.g. QU, EC, NARRM, SO, Kuroshio) prefix = Kuroshio # a description of the mesh and initial condition mesh_description = MPAS Kuroshio regionally refined mesh for E3SM version @@ -694,7 +694,7 @@ The default config options for these meshes are: approx_cell_count = 3700000 ## metadata related to the mesh - # the prefix (e.g. QU, EC, WC, SO) + # the prefix (e.g. QU, EC, NARRM, SO) prefix = RRS # a description of the mesh and initial condition mesh_description = MPAS Eddy Closure mesh for E3SM version ${e3sm_version} with @@ -820,7 +820,7 @@ The default config options for these meshes are: approx_cell_count = 570000 ## metadata related to the mesh - # the prefix (e.g. QU, EC, WC, SO) + # the prefix (e.g. QU, EC, NARRM, SO) prefix = SO # a description of the mesh and initial condition mesh_description = MPAS Southern Ocean regionally refined mesh for E3SM version @@ -855,19 +855,19 @@ The vertical grid is an ``index_tanh_dz`` profile (see :ref:`dev_ocean_framework_vertical`) with 64 vertical levels ranging in thickness from 10 to 250 m. -.. _dev_ocean_global_ocean_wc14: +.. _dev_ocean_global_ocean_narrm14: -WC14 and WCwISC14 -+++++++++++++++++ +NARRM14 and NARRMwISC14 ++++++++++++++++++++++++ -The ``WC14`` and ``WCwISC14`` meshes are the Water Cycle regionally refined -meshes for E3SM v3. They have higher resolution (~14-km) around the continental +The ``NARRM14`` and ``NARRMwISC14`` meshes are the North American Regionally Refined +Meshes for E3SM v3. They have higher resolution (~14-km) around the continental US, the Arctic Ocean, and a section of the North Atlantic containing the Gulf Stream. The resolution is uniformly about 30 km elsewhere. -The class :py:class:`compass.ocean.tests.global_ocean.mesh.wc14.WC14BaseMesh` +The class :py:class:`compass.ocean.tests.global_ocean.mesh.narrm14.NARRM14BaseMesh` defines the resolution for the meshes. The -``compass.ocean.tests.global_ocean.mesh.wc14`` module includes namelist options +``compass.ocean.tests.global_ocean.mesh.narrm14`` module includes namelist options appropriate for forward simulations with split-explicit (but not RK4) time integration on these meshes. These set the time step and default run duration for short runs with these meshes. @@ -906,12 +906,13 @@ The default config options for these meshes are: approx_cell_count = 410000 ## metadata related to the mesh - # the prefix (e.g. QU, EC, WC, SO) - prefix = WC + # the prefix (e.g. QU, EC, NARRM, SO) + prefix = NARRM # a description of the mesh and initial condition - mesh_description = MPAS North America and Arctic Focused Water Cycle mesh for E3SM version - ${e3sm_version}, with a focused ${min_res}-km resolution - around North America and <<>> vertical levels + mesh_description = MPAS North America and Arctic Regionally Refined Mesh for + E3SM version ${e3sm_version}, with ${min_res}-km resolution + in these regions, ${max_res} elsewhere and <<>> + vertical levels # E3SM version that the mesh is intended for e3sm_version = 3 @@ -923,7 +924,7 @@ The default config options for these meshes are: # the maximum (coarsest) resolution in the mesh, can be the same as min_res max_res = 30 # The URL of the pull request documenting the creation of the mesh - pull_request = https://github.com/MPAS-Dev/MPAS-Model/pull/780 + pull_request = https://github.com/MPAS-Dev/MPAS-Model/pull/782 # config options related to initial condition and diagnostics support files diff --git a/docs/users_guide/config_files.rst b/docs/users_guide/config_files.rst index a6e173db26..e91c06ce64 100644 --- a/docs/users_guide/config_files.rst +++ b/docs/users_guide/config_files.rst @@ -347,7 +347,7 @@ looks like: add_metadata = True ## metadata related to the mesh - # the prefix (e.g. QU, EC, WC, SO) + # the prefix (e.g. QU, EC, NARRM, SO) # source: /home/xylar/code/compass/customize_config_parser/compass/ocean/tests/global_ocean/mesh/qu240/qu240.cfg prefix = QU diff --git a/docs/users_guide/ocean/test_groups/global_ocean.rst b/docs/users_guide/ocean/test_groups/global_ocean.rst index 27b2f2d892..6c2bc859f1 100644 --- a/docs/users_guide/ocean/test_groups/global_ocean.rst +++ b/docs/users_guide/ocean/test_groups/global_ocean.rst @@ -102,7 +102,7 @@ Note that meshes and test cases may modify these options, as noted below. ## metadata related to the mesh # whether to add metadata to output files add_metadata = True - # the prefix (e.g. QU, EC, WC, SO) + # the prefix (e.g. QU, EC, NARRM, SO) prefix = PREFIX # a description of the mesh mesh_description = <<>> @@ -456,20 +456,20 @@ in the North Pacific, and 35 km in the Arctic. The mesh includes the :width: 500 px :align: center -.. _global_ocean_mesh_wc14: +.. _global_ocean_mesh_narrm14: -WC14 and WCwISC14 -^^^^^^^^^^^^^^^^^ +NARRM14 and NARRMwISC14 +^^^^^^^^^^^^^^^^^^^^^^^ -The Water Cycle 14- to 30-km mesh (WC14) is a regionally refined mesh for -several +The North American Regionally Refined 14- to 30-km Mesh (NARRM14) is a +mesh for several `E3SM v3 Science Campaigns `_. The mesh has 14 km resolution around the continental US, Arctic Ocean and parts of the North Atlantic, with 30 km uniform resolution elsewhere around the globe. -.. image:: images/wc14.png +.. image:: images/narrm14.png :width: 500 px :align: center diff --git a/docs/users_guide/ocean/test_groups/images/wc14.png b/docs/users_guide/ocean/test_groups/images/narrm14.png similarity index 100% rename from docs/users_guide/ocean/test_groups/images/wc14.png rename to docs/users_guide/ocean/test_groups/images/narrm14.png diff --git a/docs/users_guide/quick_start.rst b/docs/users_guide/quick_start.rst index 2f875ad713..18d4cc95f4 100644 --- a/docs/users_guide/quick_start.rst +++ b/docs/users_guide/quick_start.rst @@ -430,8 +430,8 @@ The output is: -c ocean -t quwisc240_for_e3sm -c ocean -t so12to60 -c ocean -t sowisc12to60 - -c ocean -t wc14 - -c ocean -t wcwisc14 + -c ocean -t narrm14 + -c ocean -t narrmwisc14 -c ocean -t wetdry You can set up a suite as follows: diff --git a/docs/users_guide/test_suites.rst b/docs/users_guide/test_suites.rst index bea5dd7582..f14ad6dc48 100644 --- a/docs/users_guide/test_suites.rst +++ b/docs/users_guide/test_suites.rst @@ -43,8 +43,8 @@ the current set of available test suites is: -c ocean -t quwisc240_for_e3sm -c ocean -t so12to60 -c ocean -t sowisc12to60 - -c ocean -t wc14 - -c ocean -t wcwisc14 + -c ocean -t narrm14 + -c ocean -t narrmwisc14 -c ocean -t wetdry As an example, the ocean ``nightly`` test suite includes the test cases used