Merge pull request #1077 from MPAS-Dev/develop

Merge develop into main for v1.13.0 release

Author: xylar

.github/pull_request_template.md

@@ -4,15 +4,15 @@ Please add a description of what is accomplished in the PR here at the top:
 -->
 
 <!--
-Below are a few things we ask you or your reviewers to kindly check. 
+Below are a few things we ask you or your reviewers to kindly check.
 ***Remove checks that are not relevant by deleting the line(s) below.***
 -->
 Checklist
 * [ ] User's Guide has been updated
 * [ ] If this PR adds a new analysis task, it has also been added to the user's guide
 * [ ] Developer's Guide has been updated
 * [ ] API documentation in the Developer's Guide (`api.rst`) has any new or modified class, method and/or functions listed
-* [ ] Documentation has been [built locally](https://mpas-dev.github.io/MPAS-Analysis/latest/users_guide/quick_start.html#generating-documentation) and changes look as expected
+* [ ] Documentation has been [built locally](https://mpas-dev.github.io/MPAS-Analysis/develop/users_guide/quick_start.html#generating-documentation) and changes look as expected
 * [ ] `Testing` comment in the PR documents testing used to verify the changes
 
 <!--

.github/workflows/build_workflow.yml

@@ -27,7 +27,8 @@ jobs:
         shell: bash -l {0}
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+      fail-fast: false
     steps:
       - id: skip_check
         uses: fkirc/skip-duplicate-actions@master
@@ -45,10 +46,10 @@ jobs:
           # Increase this value to reset cache if conda-dev-spec.template has not changed in the workflow
           CACHE_NUMBER: 0
         with:
-          path: ~/conda_pkgs_dir
+          path: ~/conda_pkgs_dir_py${{ matrix.python-version }}
           key:
             ${{ runner.os }}-${{ matrix.python-version }}-conda-${{ env.CACHE_NUMBER }}-${{
-            hashFiles('dev-spec.txt,setup.py') }}
+            hashFiles('dev-spec.txt,pyproject.toml') }}
 
       - if: ${{ steps.skip_check.outputs.should_skip != 'true' }}
         name: Set up Conda Environment
@@ -58,7 +59,7 @@ jobs:
           miniforge-version: latest
           channels: conda-forge
           channel-priority: strict
-          auto-update-conda: true
+          auto-update-conda: false
           python-version: ${{ matrix.python-version }}
 
       - if: ${{ steps.skip_check.outputs.should_skip != 'true' }}

.github/workflows/docs_workflow.yml

@@ -9,6 +9,9 @@ on:
   release:
     types: [published]
 
+env:
+  PYTHON_VERSION: "3.13"
+
 jobs:
   publish-docs:
     runs-on: ubuntu-latest
@@ -40,15 +43,15 @@ jobs:
           miniforge-version: latest
           channels: conda-forge
           channel-priority: strict
-          auto-update-conda: true
-          python-version: ${{ matrix.python-version }}
+          auto-update-conda: false
+          python-version: ${{ env.PYTHON_VERSION }}
 
       - if: ${{ steps.skip_check.outputs.should_skip != 'true' }}
         name: Install mpas_analysis
         run: |
           git config --global url."https://github.com/".insteadOf "[email protected]:"
           conda create -n mpas_analysis_dev --file dev-spec.txt \
-            python=${{ matrix.python-version }}
+            python=${{ env.PYTHON_VERSION }}
           conda activate mpas_analysis_dev
           python -m pip install -vv --no-deps --no-build-isolation -e .
 

MANIFEST.in

@@ -0,0 +1,12 @@
+include mpas_analysis/*.cfg
+include mpas_analysis/obs/analysis_input_files
+include mpas_analysis/obs/sose_10000km_input_files
+include mpas_analysis/obs/observational_datasets.xml
+
+include mpas_analysis/configuration/*.cfg
+include mpas_analysis/shared/html/templates/*
+include mpas_analysis/shared/plot/ScientificColourMaps7/*/*.xml
+include mpas_analysis/shared/plot/SciVisColorColormaps/*.xml
+include mpas_analysis/shared/plot/SciVisColorCustom/*.xml
+include mpas_analysis/test/test*/*
+include mpas_analysis/test/test*/*/*

ci/python3.13.yaml

@@ -0,0 +1,8 @@
+channel_sources:
+- conda-forge,defaults
+pin_run_as_build:
+  python:
+    min_pin: x.x
+    max_pin: x.x
+python:
+- 3.13.* *_cp313

ci/python3.9.yaml

@@ -0,0 +1,8 @@
+channel_sources:
+- conda-forge,defaults
+pin_run_as_build:
+  python:
+    min_pin: x.x
+    max_pin: x.x
+python:
+- 3.9.* *_cpython

ci/recipe/meta.yaml

@@ -1,5 +1,5 @@
 {% set name = "MPAS-Analysis" %}
-{% set version = "1.12.0" %}
+{% set version = "1.13.0" %}
 
 package:
   name: {{ name|lower }}
@@ -12,29 +12,27 @@ build:
     number: 0
     script: {{ PYTHON }} -m pip install --no-deps --no-build-isolation -vv .
     noarch: python
-    entry_points:
-        - mpas_analysis = mpas_analysis.__main__:main
-        - download_analysis_data = mpas_analysis.download_data:download_analysis_data
 
 requirements:
   host:
     - python >=3.9
     - pip
+    - setuptools
   run:
     - python >=3.9
     - cartopy >=0.18.0
     - cartopy_offlinedata
     - cmocean
     - dask
-    - esmf >=8.4.2,<8.7.0
+    - esmf >=8.4.2,<9.0.0
     - esmf=*=mpi_mpich_*
     - f90nml
-    - geometric_features >=1.4.0
+    - geometric_features >=1.6.1
     - gsw
     - lxml
     - mache >=1.11.0
     - matplotlib-base >=3.9.0
-    - mpas_tools >=0.34.0
+    - mpas_tools >=0.34.1,<1.0.0
     - nco >=4.8.1,!=5.2.6
     - netcdf4
     - numpy >=2.0,<3.0
@@ -61,6 +59,8 @@ test:
     - pip check
     - pytest --pyargs mpas_analysis
     - mpas_analysis --help
+    - mpas_analysis --list
+    - mpas_analysis --plot_colormaps
     - download_analysis_data --help
 
 about:

dev-spec.txt

@@ -7,15 +7,15 @@ cartopy >=0.18.0
 cartopy_offlinedata
 cmocean
 dask
-esmf >=8.4.2,<8.7.0
+esmf >=8.4.2,<9.0.0
 esmf=*=mpi_mpich_*
 f90nml
-geometric_features>=1.4.0
+geometric_features>=1.6.1
 gsw
 lxml
 mache >=1.11.0
 matplotlib-base>=3.9.0
-mpas_tools>=0.34.1
+mpas_tools>=0.34.1,<1.0.0
 nco>=4.8.1,!=5.2.6
 netcdf4
 numpy>=2.0,<3.0

docs/authors.rst

@@ -19,6 +19,7 @@ Contributors
 * Greg Streletz
 * Adrian Turner
 * Luke Van Roekel
+* Elizabeth Hunke
 
 For a list of all the contributions:
 https://github.com/MPAS-Dev/MPAS-Analysis/graphs/contributors

docs/conf.py

@@ -15,7 +15,7 @@
 import os
 import m2r2
 from glob import glob
-import mpas_analysis
+import mpas_analysis.version
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 if on_rtd:
     os.environ['PROJ_LIB'] = '{}/{}/share/proj'.format(
@@ -87,9 +87,9 @@
     release = version
 else:
     # The short X.Y.Z version.
-    version = mpas_analysis.__version__
+    version = mpas_analysis.version.__version__
     # The full version, including alpha/beta/rc tags.
-    release = mpas_analysis.__version__
+    release = mpas_analysis.version.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -187,9 +187,9 @@
     'numpy': ('http://docs.scipy.org/doc/numpy/', None),
     'xarray': ('http://xarray.pydata.org/en/stable/', None),
     'geometric_features':
-        ('http://mpas-dev.github.io/geometric_features/stable/', None),
+        ('http://mpas-dev.github.io/geometric_features/main/', None),
     'mpas_tools':
-        ('http://mpas-dev.github.io/MPAS-Tools/stable/', None)}
+        ('http://mpas-dev.github.io/MPAS-Tools/master/', None)}
 
 
 cwd = os.getcwd()

docs/developers_guide/api.rst

@@ -73,12 +73,16 @@ Ocean tasks
    ClimatologyMapAntarcticMelt
    ClimatologyMapSose
    ClimatologyMapVel
+   ClimatologyMapWoa
    ClimatologyMapArgoTemperature
    ClimatologyMapArgoSalinity
    ClimatologyMapWaves
    IndexNino34
    MeridionalHeatTransport
    OceanHistogram
+   OceanRegionalProfiles
+   RegionalTSDiagrams
+   SoseTransects
    StreamfunctionMOC
    TimeSeriesOHCAnomaly
    TimeSeriesTemperatureAnomaly
@@ -87,6 +91,11 @@ Ocean tasks
    TimeSeriesAntarcticMelt
    TimeSeriesOceanRegions
    TimeSeriesTransport
+   WoaTransects
+   WoceTransects
+
+Ocean subtasks
+--------------
 
 .. currentmodule:: mpas_analysis.ocean.compute_anomaly_subtask
 
@@ -110,6 +119,19 @@ Ocean tasks
    PlotHovmollerSubtask
 
 
+Ocean utilities
+---------------
+
+.. currentmodule:: mpas_analysis.ocean.utility
+
+.. autosummary::
+   :toctree: generated/
+
+   add_standard_regions_and_subset
+   get_standard_region_names
+   compute_zmid
+
+
 Sea ice tasks
 -------------
 
@@ -120,6 +142,19 @@ Sea ice tasks
 
    ClimatologyMapSeaIceConc
    ClimatologyMapSeaIceThick
+   ClimatologyMapSeaIceSnowDepth
+   ClimatologyMapSeaIceSnowiceFormation
+   ClimatologyMapSeaIceSnowMelt
+   ClimatologyMapSeaIcePondArea
+   ClimatologyMapSeaIceAreaFractionRidge
+   ClimatologyMapSeaIceVolumeRidge
+   ClimatologyMapSeaIceAlbedo
+   ClimatologyMapSeaIceProduction
+   ClimatologyMapSeaIceMelting
+   ClimatologyMapSeaIceAreaTendencyThermo
+   ClimatologyMapSeaIceAreaTendencyTransp
+   ClimatologyMapSeaIceVolumeTendencyThermo
+   ClimatologyMapSeaIceVolumeTendencyTransp
    TimeSeriesSeaIce
    ClimatologyMapIcebergConc
 

docs/tutorials/dev_add_task.rst

@@ -9,6 +9,12 @@ analysis task that is as close as possible to the new analysis, and to copy
 that existing task as a template for the new task.  That is the strategy we
 will demonstrate here.
 
+.. note::
+
+   The changes will not be broadly available until the next MPAS-Analysis
+   release and to the broader E3SM community after the next
+   `E3SM-Unified <https://github.com/E3SM-Project/e3sm-unified>`_ release.
+
 To provide a real example, we will show how we copy and modify an analysis
 task used to compute the anomaly in ocean heat content
 (:py:class:`~mpas_analysis.ocean.ClimatologyMapOHCAnomaly`) to instead compute
@@ -22,6 +28,22 @@ notebooks include hard-coded paths and are otherwise not easily applied to new
 simulations without considerable effort. This is the motivation for adapting
 the code to MPAS-Analysis.
 
+
+.. note::
+
+   If one just wishes to add a new field that already exists in MPAS-Ocean or
+   MPAS-Seaice output, only a few of the steps below are necessary:
+
+   1. Follow step 1 to set up an ```mpas_dev``` environment.
+   2. Copy an existing `ocean <https://github.com/MPAS-Dev/MPAS-Analysis/tree/develop/mpas_analysis/ocean>`_
+      or `sea_ice <https://github.com/MPAS-Dev/MPAS-Analysis/tree/develop/mpas_analysis/sea_ice>`_
+      python module to a new name and edit it as needed for the new fields.
+   3. Follow step 6 to add config options
+   4. Follow step 7 to add the task to the list of tasks known to
+      MPAS-Analysis
+   5. Follow step 8 to update Analysis Tasks in the user's guide and
+      ``api.rst`` in the developer's guide to include the new analysis task.
+
 1. Getting started
 ------------------
 
@@ -31,6 +53,14 @@ cloning it onto the machine(s) where you will do your development, making
 a worktree for the feature you will develop, creating a conda environment for
 testing your new MPAS-Analysis development, and running MPAS-Analysis.
 
+.. note::
+
+   Make sure you follow the tutorial for developers, not for users, since the
+   tutorial for users installs the latest release of MPAS-Analysis, which you
+   cannot modify. Similarly, changes must be tested in your own development
+   environment (often called ``mpas_dev``) rather than the in a shared
+   environment like `E3SM-Unified <https://github.com/E3SM-Project/e3sm-unified>`_.
+
 Then, please follow the :ref:`tutorial_understand_a_task`.  This will give
 you a tour of the :py:class:`~mpas_analysis.ocean.ClimatologyMapOHCAnomaly`
 analysis task that we will use as a starting point for developing a new task.
@@ -513,12 +543,12 @@ task to the new name:
     cd ../add_climatology_map_bsf
     cp mpas_analysis/ocean/climatology_map_ohc_anomaly.py mpas_analysis/ocean/climatology_map_bsf.py
 
-Then, I'll open this new worktree in PyCharm.  (You can, of course, use
+Then, I'll open this new worktree in VS Code.  (You can, of course, use
 whatever editor you like.)
 
 .. code-block:: bash
 
-    pycharm-community .
+    code .
 
 I'll create or recreate my ``mpas_dev`` environment as in
 :ref:`tutorial_dev_getting_started`, and then make sure to at least do:
@@ -528,6 +558,9 @@ I'll create or recreate my ``mpas_dev`` environment as in
     conda activate mpas_dev
     python -m pip install --no-deps --no-build-isolation -e .
 
+This last command installs the ``mpas_analysis`` package into the conda
+environment.
+
 4.1 ``ClimatologyMapBSF`` class
 -------------------------------
 
@@ -1092,7 +1125,32 @@ A quick way to check if the task has been added correctly is to run:
 You should see the new task in the list of tasks.
 
 
-8. The full code for posterity
+8. Adding documentation
+-----------------------
+
+You need to add the task to the documentation.  The easiest way to do this
+is to copy an existing task's documentation (the more similar, the better) in
+the `tasks <https://github.com/MPAS-Dev/MPAS-Analysis/tree/develop/docs/users_guide/tasks>`_
+directory and then modify it.
+
+You also need to add the tasks class and public methods to the
+`api.rst <https://github.com/MPAS-Dev/MPAS-Analysis/blob/develop/docs/developers_guide/api.rst>`_
+in the developer's guide.  Again, the easiest approach is to copy the section
+for a similar task and modify as needed.
+
+With the ``mpas_dev`` environment activated, you can run:
+
+.. code-block:: bash
+
+    cd docs
+    make clean html
+
+to build the docs locally in the ``_build/html`` subdirectory.  When generating
+documentation on HPC machines, you will want to copy the html output to the
+public web space to view it, or if the web portal is being cranky, scp it to
+your local machine.
+
+9. The full code for posterity
 ------------------------------
 
 Since the ``ClimatologyMapBSF`` analysis task is not in MPAS-Analysis yet and