Merge pull request #933 from MPAS-Dev/develop

Merge develop into master

Author: xylar

.gitignore

@@ -1,6 +1,6 @@
 # User defined config files
 /config.*
-!/config.default
+/*.cfg
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

README.md

@@ -28,7 +28,7 @@ used those components.
 
 ## Documentation
 
-[https://mpas-dev.github.io/MPAS-Analysis/stable/](https://mpas-dev.github.io/MPAS-Analysis/stable/)
+[https://mpas-dev.github.io/MPAS-Analysis/latest/](https://mpas-dev.github.io/MPAS-Analysis/latest/)
 
 ## Installation for users
 
@@ -116,7 +116,7 @@ for more details.
 
 ## Running the analysis
 
-  1. Create and empty config file (say `config.myrun`), copy `config.example`,
+  1. Create and empty config file (say `myrun.cfg`), copy `example.cfg`,
      or copy one of the example files in the `configs` directory (if using a
      git repo) or download one from the
      [example configs directory](https://github.com/MPAS-Dev/MPAS-Analysis/tree/develop/configs).
@@ -125,9 +125,9 @@ for more details.
      from GitHub:
      [default.cfg](https://github.com/MPAS-Dev/MPAS-Analysis/tree/develop/mpas_analysis/default.cfg).
   3. If you installed the `mpas-analysis` package, run:
-     `mpas_analysis config.myrun`.  This will read the configuration
+     `mpas_analysis myrun.cfg`.  This will read the configuration
      first from `mpas_analysis/default.cfg` and then replace that
-     configuraiton with any changes from from `config.myrun`
+     configuraiton with any changes from from `myrun.cfg`
   4. If you want to run a subset of the analysis, you can either set the
      `generate` option under `[output]` in your config file or use the
      `--generate` flag on the command line.  See the comments in
@@ -290,16 +290,15 @@ to be generated and is set up properly.
 
 ## Generating Documentation
 
+Create a development environment as described above in "Installation for 
+developers".  Then run:
 To generate the `sphinx` documentation, run:
 ```
-conda config --add channels conda-forge
-conda remove -y --all -n mpas-analysis-docs
-conda env create -f docs/environment.yml
-conda install -y -n mpas-analysis-docs mock pillow sphinx sphinx_rtd_theme
-conda activate mpas-analysis-docs
-pip install .
-rm -rf build dist mpas_analysis.egg-info
 cd docs
 make clean
 make html
 ```
+The results can be viewed in your web browser by opening:
+```
+_build/html/index.html
+```

azure-pipelines.yml

@@ -21,52 +21,61 @@ jobs:
     vmImage: 'ubuntu-latest'
   strategy:
     matrix:
-      Python38:
-        python.version: '3.8'
       Python39:
         python.version: '3.9'
       Python310:
         python.version: '3.10'
+      Python311:
+        python.version: '3.11'
 
   steps:
   - bash: echo "##vso[task.prependpath]$CONDA/bin"
     displayName: Add conda to PATH
 
   - bash: |
+      set -e
+      eval "$(conda shell.bash hook)"
       conda config --add channels conda-forge
       conda config --set channel_priority strict
-      conda create --yes --quiet --name build python=$PYTHON_VERSION conda conda-build
-    displayName: Create Anaconda build environment
+      conda install --yes "conda<22.11.0" conda-build mamba boa
+    displayName: Update conda base environment
 
   - bash: |
+      set -e
       eval "$(conda shell.bash hook)"
-      conda activate build
-      conda build -m "ci/python${PYTHON_VERSION}.yaml" "ci/recipe"
+      conda activate
+      # workaround based on recent failures
+      rm /usr/share/miniconda/pkgs/cache/*.json
+      conda mambabuild -m "ci/python${PYTHON_VERSION}.yaml" "ci/recipe"
     displayName: Build MPAS-Analysis
 
   - bash: |
+      set -e
       eval "$(conda shell.bash hook)"
-      conda activate build
-      conda create --yes --quiet --name test -c ${CONDA_PREFIX}/conda-bld/ \
+      conda activate
+      mamba create --yes --quiet --name mpas -c ${CONDA_PREFIX}/conda-bld/ \
           python=$PYTHON_VERSION mpas-analysis pytest
-    displayName: Create Anaconda test environment
+    displayName: Create Anaconda mpas environment
 
   - bash: |
+      set -e
       eval "$(conda shell.bash hook)"
-      conda activate test
+      conda activate mpas
       pytest --pyargs mpas_analysis
     displayName: pytest
 
   - bash: |
+      set -e
       eval "$(conda shell.bash hook)"
-      conda activate build
-      conda create --yes --quiet --name docs -c ${CONDA_PREFIX}/conda-bld/ \
+      conda activate
+      mamba create --yes --quiet --name docs -c ${CONDA_PREFIX}/conda-bld/ \
           python=$PYTHON_VERSION mpas-analysis sphinx mock sphinx_rtd_theme \
           tabulate m2r2 "mistune<2"
-    condition: eq(variables['python.version'], '3.9')
+    condition: eq(variables['python.version'], '3.10')
     displayName: Create Anaconda docs environment
 
   - bash: |
+      set -e
       eval "$(conda shell.bash hook)"
       conda activate docs
 
@@ -128,7 +137,7 @@ jobs:
         fi
         popd || exit 1
       fi
-    condition: eq(variables['python.version'], '3.9')
+    condition: eq(variables['python.version'], '3.10')
     displayName: build and deploy docs
 
 - job:
@@ -137,38 +146,45 @@ jobs:
     vmImage: 'ubuntu-latest'
   strategy:
     matrix:
-      Python39:
-        python.version: '3.9'
+      Python310:
+        python.version: '3.10'
 
   steps:
   - bash: echo "##vso[task.prependpath]$CONDA/bin"
     displayName: Add conda to PATH
 
   - bash: |
+      set -e
+      eval "$(conda shell.bash hook)"
       conda config --add channels conda-forge
       conda config --set channel_priority strict
-      conda create --yes --quiet --name build python=$PYTHON_VERSION conda conda-build
-    displayName: Create Anaconda build environment
+      conda install --yes python=$PYTHON_VERSION "conda<22.11.0" conda-build mamba boa
+    displayName: Update conda base environment
 
   - bash: |
+      set -e
       eval "$(conda shell.bash hook)"
-      conda activate build
-      conda build -m "ci/python${PYTHON_VERSION}.yaml" "ci/recipe"
+      conda activate
+      # workaround based on recent failures
+      rm /usr/share/miniconda/pkgs/cache/*.json
+      conda mambabuild -m "ci/python${PYTHON_VERSION}.yaml" "ci/recipe"
     displayName: Build MPAS-Analysis
 
   - bash: |
+      set -e
       eval "$(conda shell.bash hook)"
-      conda activate build
-      conda create --yes --quiet --name test -c ${CONDA_PREFIX}/conda-bld/ \
+      conda activate
+      mamba create --yes --quiet --name mpas -c ${CONDA_PREFIX}/conda-bld/ \
            python=$PYTHON_VERSION mpas-analysis pytest
-      conda activate test
+      conda activate mpas
       pip install git+https://github.com/pydata/xarray.git
 
-    displayName: Create Anaconda test environment
+    displayName: Create Anaconda mpas environment
 
   - bash: |
+      set -e
       eval "$(conda shell.bash hook)"
-      conda activate test
+      conda activate mpas
       pytest --pyargs mpas_analysis
     displayName: pytest
 
@@ -178,12 +194,12 @@ jobs:
     vmImage: 'macOS-latest'
   strategy:
     matrix:
-      Python38:
-        python.version: '3.8'
       Python39:
         python.version: '3.9'
       Python310:
         python.version: '3.10'
+      Python311:
+        python.version: '3.11'
 
   steps:
   - bash: echo "##vso[task.prependpath]$CONDA/bin"
@@ -193,26 +209,31 @@ jobs:
     displayName: Fix permissions
 
   - bash: |
+      set -e
+      eval "$(conda shell.bash hook)"
       conda config --add channels conda-forge
       conda config --set channel_priority strict
-      conda create --yes --quiet --name build python=$PYTHON_VERSION conda conda-build
-    displayName: Create Anaconda build environment
+      conda install --yes "conda<22.11.0" conda-build mamba boa
+    displayName: Update conda base environment
 
   - bash: |
+      set -e
       eval "$(conda shell.bash hook)"
-      conda activate build
-      conda build -m "ci/python${PYTHON_VERSION}.yaml" "ci/recipe"
+      conda activate
+      conda mambabuild -m "ci/python${PYTHON_VERSION}.yaml" "ci/recipe"
     displayName: Build MPAS-Analysis
 
   - bash: |
+      set -e
       eval "$(conda shell.bash hook)"
-      conda activate build
-      conda create --yes --quiet --name test -c ${CONDA_PREFIX}/conda-bld/ \
+      conda activate
+      mamba create --yes --quiet --name mpas -c ${CONDA_PREFIX}/conda-bld/ \
           python=$PYTHON_VERSION mpas-analysis pytest
-    displayName: Create Anaconda test environment
+    displayName: Create Anaconda mpas environment
 
   - bash: |
+      set -e
       eval "$(conda shell.bash hook)"
-      conda activate test
+      conda activate mpas
       pytest --pyargs mpas_analysis
     displayName: pytest

ci/python3.8.yaml renamed to ci/python3.11.yaml

@@ -5,4 +5,4 @@ pin_run_as_build:
     min_pin: x.x
     max_pin: x.x
 python:
-- 3.8.* *_cpython
+- 3.11.* *_cpython

ci/recipe/meta.yaml

@@ -1,5 +1,5 @@
 {% set name = "MPAS-Analysis" %}
-{% set version = "1.7.2" %}
+{% set version = "1.8.0" %}
 
 package:
   name: {{ name|lower }}
@@ -27,6 +27,7 @@ requirements:
     - cartopy_offlinedata
     - cmocean
     - dask
+    - esmf >=8.0.0,<8.3.0
     - esmf=*=nompi_*
     - f90nml
     - geometric_features >=0.5.0

dev-spec.txt

@@ -8,6 +8,7 @@ cartopy >=0.18.0
 cartopy_offlinedata
 cmocean
 dask
+esmf >=8.0.0,<8.3.0
 esmf=*=nompi_*
 f90nml
 geometric_features>=0.5.0

docs/developers_guide/api.rst

@@ -90,14 +90,6 @@ Ocean tasks
 
    ComputeAnomalySubtask
 
-.. currentmodule:: mpas_analysis.ocean.plot_climatology_map_subtask
-
-.. autosummary::
-   :toctree: generated/
-
-   PlotClimatologyMapSubtask
-   PlotClimatologyMapSubtask.set_plot_info
-
 .. currentmodule:: mpas_analysis.ocean.plot_depth_integrated_time_series_subtask
 
 .. autosummary::
@@ -126,14 +118,6 @@ Sea ice tasks
    TimeSeriesSeaIce
    ClimatologyMapIcebergConc
 
-.. currentmodule:: mpas_analysis.sea_ice.plot_climatology_map_subtask
-
-.. autosummary::
-   :toctree: generated/
-
-   PlotClimatologyMapSubtask
-   PlotClimatologyMapSubtask.set_plot_info
-
 
 Shared modules
 ==============
@@ -267,6 +251,10 @@ Plotting
    ticks.plot_xtick_format
    add_inset
 
+   PlotClimatologyMapSubtask
+   PlotClimatologyMapSubtask.set_plot_info
+
+
 
 Projection
 ----------

docs/users_guide/analysis_tasks.rst

@@ -35,11 +35,17 @@ Analysis Tasks
    tasks/geojsonTransects
    tasks/oceanRegionalProfiles
    tasks/regionalTSDiagrams
+   tasks/oceanHistogram
 
    tasks/climatologyMapSeaIceConcNH
    tasks/climatologyMapSeaIceThickNH
    tasks/climatologyMapSeaIceConcSH
    tasks/climatologyMapSeaIceThickSH
    tasks/timeSeriesSeaIceAreaVol
 
+   tasks/climatologyMapSeaIceProductionNH
+   tasks/climatologyMapSeaIceMeltingNH
+   tasks/climatologyMapSeaIceProductionSH
+   tasks/climatologyMapSeaIceMeltingSH
+
    tasks/climatologyMapIcebergConcSH

docs/users_guide/config/output.rst

@@ -151,10 +151,10 @@ Finally, we note that the ``generate`` option in the configuration file can
 be overridden by specifying the ``--generate`` option on the command line::
 
   mpas_analysis --generate=all_publicObs,no_index,no_climatologyMapSST \
-      config.my_run
+      my_run.cfg
 
 This example would override whatever ``generate`` option was specified in
-``config.my_run`` with a directive to generate only tasks that support the
+``my_run.cfg`` with a directive to generate only tasks that support the
 publicly available observations, skipping those using climate indices (e.g.
 El Ni |n~| o 3.4) and also skipping ``climatologyMapSST``.
 

docs/users_guide/config/regions.rst

@@ -35,17 +35,17 @@ web page.
 Region Groups
 -------------
 
-Currently, seven analysis tasks (:ref:`task_climatologyMapAntarcticMelt`,
+Currently, eight analysis tasks (:ref:`task_climatologyMapAntarcticMelt`,
 :ref:`task_hovmollerOceanRegions`, :ref:`task_oceanRegionalProfiles`,
 :ref:`task_regionalTSDiagrams`, :ref:`task_streamfunctionMOC`,
-:ref:`task_timeSeriesAntarcticMelt`, and :ref:`task_timeSeriesOceanRegions`)
-use masks that define regions in an MPAS mesh as part of their analysis.  Most
-of these region group are defined in
+:ref:`task_oceanHistogram`, :ref:`task_timeSeriesAntarcticMelt`, and
+:ref:`task_timeSeriesOceanRegions`) use masks that define regions in an MPAS
+mesh as part of their analysis.  Most of these region group are defined in
 :py:func:`geometric_features.aggregation.get_aggregator_by_name()`.
-Several tasks (:ref:`task_hovmollerOceanRegions`,
+Several tasks (:ref:`task_hovmollerOceanRegions`, :ref:`task_oceanHistogram`,
 :ref:`task_oceanRegionalProfiles`, :ref:`task_regionalTSDiagrams`, and
 :ref:`task_timeSeriesOceanRegions`) can use any of the defined region groups.
-Currently, available region groups are: ``Antarctic Regions``,
+Currently, available region groups are: ``Artic Ocean Regions``, ``Antarctic Regions``,
 ``Ocean Basins``, ``Ice Shelves``, and ``Ocean Subbasins``.
 
 The option ``regionMaskSubdirectory`` in the ``[diagnostics]`` section specifies