E3SM-Project · tomvothecoder · Jan 28, 2025 · Jan 28, 2025 · Jan 28, 2025 · Jan 28, 2025
diff --git a/Makefile b/Makefile
@@ -88,6 +88,13 @@ docs: ## generate Sphinx HTML documentation, including API docs
 	$(MAKE) -C docs html
 	$(BROWSER) docs/_build/html/index.html
 
+docs-versioned: ## generate verisoned Sphinx HTML documentation, including API docs
+	rm -rf docs/generated
+	cd docs && sphinx-multiversion source _build/html
+	$(MAKE) -C docs clean
+	$(MAKE) -C docs html
+	$(BROWSER) docs/_build/html/index.html
+
 # Build
 # ----------------------
 install: clean ## install the package to the active Python's site-packages

diff --git a/README.md b/README.md
@@ -46,6 +46,17 @@ This diagnostics package is constructed for supporting the diagnostics task of D
 
 E3SM Diags is modeled after the National Center for Atmospheric Research (NCAR) Atmosphere Model Working Group (AMWG) diagnostics package. In its version 1 release, E3SM Diags included a set of core essential diagnostics to evaluate the mean physical climate from model simulations. As of version 2, more process-oriented and phenomenon-based evaluation diagnostics have been implemented, as listed below:
 
+### Major refactor with v3 development
+
+v3.0.0 marks a major milestone after nearly two years of work by the core development
+team. This release introduces a completely new back-end, replacing CDAT with Xarray and
+xCDAT. Due to the significant scale of code changes, this has been incremented as a
+major release. The user-facing API for running E3SM Diagnostics remains backward-compatible between v2 and v3.
+
+The modernization improves performance, usability, and maintainability, paving the way
+for future enhancements to E3SM development. The refactored codebase is now more robust
+and extensively covered by unit tests, setting a solid foundation for ongoing testing and development.
+
 ### New Feature added during v2 development
 
 | Feature name <br />(set name)                                       | Brief Introduction                                                                                                                                                                                     | Developers Contributors\*                                                                                                                                             | Released version |

diff --git a/conda-env/ci.yml b/conda-env/ci.yml
@@ -36,3 +36,4 @@ dependencies:
   - sphinx
   - sphinx_rtd_theme
   - sphinx-multiversion
+  - sphinx-copybutton
diff --git a/conda-env/dev.yml b/conda-env/dev.yml
@@ -34,6 +34,7 @@ dependencies:
   - sphinx
   - sphinx_rtd_theme
   - sphinx-multiversion
+  - sphinx-copybutton
   # Quality Assurance Tools
   # =======================
   # Run `pre-commit autoupdate` to get the latest pinned versions of 'rev' in

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -33,6 +33,7 @@
 extensions = [
     "sphinx_rtd_theme",
     "sphinx_multiversion",
+    "sphinx_copybutton"
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -88,7 +89,6 @@
 #
 
 html_theme = "sphinx_rtd_theme"
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 html_sidebars = {
     "**": [
         "versions.html",

diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -131,7 +131,7 @@ Use the code below to run the diagnostics.
     .. code::
 
         # Allocate a node to run an interactive session on. You can also use a batch job.
-        salloc --nodes=1 --partition=regular --time=01:00:00 -C haswell
+        salloc --nodes 1 --qos interactive --time 01:00:00 --constraint cpu --account=e3sm
         # Enter the E3SM Unified environment. For Cori, the command to do this is:
         source /global/common/software/e3sm/anaconda_envs/load_latest_e3sm_unified_cori-haswell.sh
         # Running Ex.1. For examples 4,5,7 append ``-d diags.cfg``.

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -6,18 +6,13 @@
 .. _index-label:
 
 ***************************
-E3SM Diagnostics Package v2
+E3SM Diagnostics Package v3
 ***************************
 Welcome to the E3SM Diagnostics Package documentation hub.
 
 To change the documentation version, use the version selector in the bottom left-hand corner.
 Please note, documentation for versions ``v2.5.0`` are not available in the version selector.
 
-.. warning::
-    As of ``v2.6.0``, ``e3sm_diags`` should be used as the module name instead of
-    ``acme_diags``. Instances of ``acme_diags`` in the Python import statements should
-    be replaced accordingly.
-
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
@@ -54,14 +49,21 @@ that:
 -  is flexible for user-specified diagnostics and configuration for
    use by other climate models.
 
-Current State (v2 release)
---------------------------
+Current State
+-------------
 
 Algorithm and visualization codes for **latitude-longitude contour maps**,
-**polar contour maps**, the accompanying **summarizing table** and **Taylor diagram plots**,  **pressure-latitude zonal mean contour plots**,
-**zonal mean line plots**, **pressure-longitude meridional mean contour plots**, **area mean time series plots**, and **Cloud Top Height-Tau** joint histograms
-from COSP cloud simulator output. Plots can be created for annual
-and seasonal climatologies, and monthly mean time series. In additional to the core sets being released in v1, **ENSO diags**, **QBO diags**, **Diurnal cycle phase plot**, **Streamflow evaluation**, **ARM diags**, and **TC analysis** are implemented in v2 release.
+**polar contour maps**, the accompanying **summarizing table** and
+**Taylor diagram plots**,  **pressure-latitude zonal mean contour plots**,
+**zonal mean line plots**, **pressure-longitude meridional mean contour plots**,
+**area mean time series plots**, and **Cloud Top Height-Tau** joint histograms from
+COSP cloud simulator output. Plots can be created for annual and seasonal climatologies,
+and monthly mean time series. In additional to the core sets being released in v1,
+**ENSO diags**, **QBO diags**, **Diurnal cycle phase plot**, **Streamflow evaluation**,
+**ARM diags**, and **TC analysis** are implemented in v2 release. v3 introduces a
+completely new back-end, replacing CDAT with Xarray and xCDAT. Due to the significant
+scale of code changes, this has been incremented as a major release. The user-facing
+API for running E3SM Diagnostics remains backward-compatible between v2 and v3.
 
 The package also supports custom user diagnostics, by specifying
 plot type, desired region (global, ocean, land, etc.),

diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -5,7 +5,7 @@ The installation procedure depends on what version you'd like to install.
 
 Activate **e3sm_unified** environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-If you have an account on one of the E3SM supported machines (NERSC, Compy, Acme1, LCRC, Cooley, Rhea), you
+If you have an account on one of the E3SM supported machines (NERSC, Compy, LCRC, Cooley, Rhea), you
 can access ``e3sm_diags`` by activating ``e3sm_unified``, which is a conda environment that pulls together Python
 and other E3SM analysis tools such as ``e3sm_diags``, ``mpas-analysis``, ``NCO``, and ``processflow``.
 
@@ -34,14 +34,6 @@ The paths to ``e3sm_unified`` activation scripts are machine dependent:
      source /lus/theta-fs0/projects/ccsm/acme/tools/e3sm-unified/load_latest_e3sm_unified_cooley.sh
 
 
-**acme1**
-    ::
-
-     source /usr/local/e3sm_unified/envs/load_latest_e3sm_unified_acme1.sh
-
-
-
-
 Change ``.sh`` to ``.csh`` for csh shells.
 Note that ``e3sm_unified``'s development cycle is not in phase with ``e3sm_diags``,
 therefore the version of ``e3sm_diags`` included may not be the latest.
@@ -77,41 +69,30 @@ NERSC
 Others/Local
 ~~~~~~~~~~~~
 
-If the system doesn't come with conda pre-installed, follow these instructions:
+If the system doesn't come with conda pre-installed, follow these instructions for
+Unix-like platforms (macOS & Linux)
 
-1. Download Mambaforge
+1. Download Miniforge
 
-    Linux
-        ::
-
-            wget https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-Linux-x86_64.sh
-
-    MacOS x86_64
-        ::
-
-            wget https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-MacOSX-x86_64.sh
-
-2. Install Mambaforge
+    ::
 
-    Linux
-        ::
+        wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
 
-            bash ./Mambaforge-Linux-x86_64.sh
+2. Install Miniforge
 
-    MacOS x86_64
-        ::
+    ::
 
-            bash ./Mambaforge-MacOSX-x86_64.sh
+        bash Miniforge3-$(uname)-$(uname -m).sh
 
     When you see: ::
 
         by running conda init? [yes|no]
         [no] >>> yes
 
-    respond with ``yes`` so ``conda`` and ``mamba`` commands are available on
+    respond with ``yes`` so ``conda`` commands are available on
     initializing a new bash terminal.
 
-3. If you are working on a machine/network that intercepts SSL communications (such as acme1), you will get
+3. If you are working on a machine/network that intercepts SSL communications, you will get
 an SSL error unless you disable the SSL verification:
 
     ::
@@ -120,55 +101,39 @@ an SSL error unless you disable the SSL verification:
         binstar config --set ssl_verify False
 
 
-4. Once conda and mamba are properly working, you can install the **(a) Latest Stable Release** or
+4. Once conda are properly working, you can install the **(a) Latest Stable Release** or
 create a **(b) Development Environment**.
 
 .. _install_latest:
 
 (a) Latest Stable Release
 -------------------------
 
-1. Follow :ref:`"Others/Local" <conda_environment_others>` section for installing Conda.
-
-2. Get the yml file to create an environment.
-
-    ::
-
-        wget https://raw.githubusercontent.com/E3SM-Project/e3sm_diags/main/conda-env/prod.yml
-
-
-3. Change ``prefix`` in that file to be your conda prefix. Typically, this will be ``~/miniconda3/envs/e3sm_diags_env``.
+1. Follow :ref:`"Others/Local" <conda_environment_others>` section for installing conda.
 
-4. Remove any cached conda packages. This will ensure that you always get the latest packages
+Create a new conda environment with ``e3sm_diags`` installed and activate it:
 
     ::
 
-        mamba clean --all
-
-5. Use conda to create a new environment with E3SM Diags (``e3sm_diags``) included.
-These steps should not be necessary if you installed Mambaforge as suggested
-above but may be needed if you have previously installed Miniconda3 instead: ::
-
-   conda install -y -n base mamba
-   conda config --add channels conda-forge
-   conda config --set channel_priority strict
-
-Create a new conda environment with ``e3sm_diags`` installed and activate it: ::
-
-        mamba env create -f conda-env/prod.yml # Tip: Add the flag ``-n <name_of_env>`` to customize the name of the environment  
+        # Tip: Add the flag ``-n <name_of_env>`` to customize the name of the environment
+        conda create -n e3sm_diags_env e3sm_diags
         conda activate e3sm_diags_env
 
 .. _dev-env:
 
 (b) Development Environment
 ---------------------------
 
-Unlike the latest stable release (i.e., the user environment), the development environment does not include E3SM Diags (``e3sm-diags``).
-Instead, the developer will ``pip install .`` to build ``e3sm-diags`` with changes (see step 6 below).
+Unlike the latest stable release (i.e., the user environment), the development
+environment does not include E3SM Diags (``e3sm-diags``). Instead, the developer will
+``make install`` (or ``python -m pip install .``) to build ``e3sm-diags`` with changes
+(see step 6 below).
 
 .. note::
-    The dev environment includes quality assurance (QA) tools such as code formatters, linters, and ``pre-commit``.
-    **You must use the dev environment for all contributions** because these QA tools are enforced using ``pre-commit`` checks in the continuous integration/continuous deployment build.
+    The dev environment includes quality assurance (QA) tools such as code formatters,
+    linters, and ``pre-commit``. **You will need to use the dev environment for all
+    contributions** because these QA tools are enforced using ``pre-commit`` checks in
+    the continuous integration/continuous deployment build.
 
 1. Follow :ref:`"Others/Local" <conda_environment_others>` section for installing conda.
 
@@ -222,7 +187,7 @@ Instead, the developer will ``pip install .`` to build ``e3sm-diags`` with chang
 
     ::
 
-        mamba clean --all
+        conda clean --all
 
 4. Enter the fork directory.
 
@@ -236,7 +201,7 @@ Instead, the developer will ``pip install .`` to build ``e3sm-diags`` with chang
 
     ::
 
-        mamba env create -f conda-env/dev.yml
+        conda env create -f conda-env/dev.yml
         conda activate e3sm_diags_env_dev
 
 6. Install ``pre-commit``.
@@ -249,7 +214,7 @@ Instead, the developer will ``pip install .`` to build ``e3sm-diags`` with chang
 
     ::
 
-        pip install .
+        make install # or python -m pip install .
 
 8. Check that tests pass: ``./tests/test.sh``. This takes about 4 minutes.
 

diff --git a/docs/source/quickguides/generate_quick_guides.py b/docs/source/quickguides/generate_quick_guides.py
@@ -2,14 +2,6 @@
 import subprocess
 
 EXPANSIONS = {
-    'acme1': {
-        'machine_name': 'Acme1',
-        'activation_path': '/usr/local/e3sm_unified/envs/load_latest_e3sm_unified_acme1.sh',
-        'obs_path': '/p/user_pub/e3sm/diagnostics/observations/Atm/',
-        'test_data_path': '/p/user_pub/e3sm/e3sm_diags_data/test_model_data_for_acme_diags/',
-        'html_path': '/var/www/acme/acme-diags/<username>/',
-        'web_address': 'https://acme-viewer.llnl.gov/<username>/',
-    },
     'anvil': {
         'machine_name': 'Anvil',
         'activation_path': '/lcrc/soft/climate/e3sm-unified/load_latest_e3sm_unified_anvil.sh',
@@ -78,7 +70,7 @@ def generate_quick_guides():
                     else:
                         expansion = EXPANSIONS[machine_name][expansion_name]
                         new_line = line.replace(expansion_indicator, expansion)
-                if multiprocessing and machine_name != 'acme1':
+                if multiprocessing:
                     multiprocessing_file = '{d}quick-guide-multiprocessing-{m}.rst'.format(
                         d=quick_guides_dir, m=machine_name)
                     with open(multiprocessing_file, 'r') as mpf:

diff --git a/docs/source/quickguides/index.rst b/docs/source/quickguides/index.rst
@@ -6,7 +6,6 @@ Quick Guides
    :maxdepth: 2
 
    quick-guide-general
-   quick-guide-acme1
    quick-guide-anvil
    quick-guide-chrysalis
    quick-guide-compy

diff --git a/docs/source/quickguides/old/index.rst b/docs/source/quickguides/old/index.rst