GCPy 1.6.0 release

This is the release commit of GCPy 1.6.0.  Please see the CHANGELOG.md
for a list of updaes.  Documentation for GCPy 1.6.0 is now available
at gcpy.readthedocs.io.

Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

Author: yantosca

.github/workflows/codeql.yml

@@ -46,11 +46,11 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
+      uses: github/codeql-action/init@v3
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -64,7 +64,7 @@ jobs:
     # Autobuild attempts to build any compiled languages (C/C++, C#, Go, Java, or Swift).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v2
+      uses: github/codeql-action/autobuild@v3
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -77,6 +77,6 @@ jobs:
     #     ./location_of_script_within_repo/buildscript.sh
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2
+      uses: github/codeql-action/analyze@v3
       with:
         category: "/language:${{matrix.language}}"

.github/workflows/publish-python.yml

@@ -21,9 +21,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: '3.x'
     - name: Install dependencies

CHANGELOG.md

@@ -4,9 +4,42 @@ All notable changes to GCPy will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased] - TBD
+## [1.6.0] - 2025-01-29
+### Added
+- Added example script `gcpy/examples/hemco/make_hemco_sa_spec.py` (creates the HEMCO standalone configuration file `HEMCO_sa_Spec.rc`)
+- Added module `benchmark_gcclassic_stats.py` for scraping statistics from GEOS-Chem Classic cloud benchmarks
+- Added dry deposition velocity comparison plots in 1-month cloud benchmarks
+- Added `gcpy/benchmark/modules/benchmark_species_changes.py` to compute the table of species changes between versions
+- Added `gcpy/kpp/` folder containing scripts to plot output from the KPP-Standalone box model
+- Added ReadTheDocs documentation for plotting output from the KPP-Standalone box model
+
+### Changed
+- Changed format of `% diff` column from `12.3e` to `12.3f` in benchmark timing tables 
+- Updated `gcpy/benchmark/modules/emission_species.yml` file with emission species for GEOS-Chem 14.5.0
+- Updated `gcpy/benchmark/modules/benchmark_categories.yml` with the latest categories for GEOS-Chem 14.5.0
+- Updated `gcpy/benchmark/modules/lumped_species.yml` with speciations for GEOS-Chem 14.5.0
+- Add `DryDep` to list of collections included in benchmark summary table
+- Updated `checkout` GitHub action to v4
+- Updated `CodeQL` GitHub action to v3
+- Updated `publish-python` GitHub action to v5
+- In environment files `gcpy_environment.yml` and `gcpy_requirements.txt`:
+  - Update `python` to 3.12.0
+  - Update `xesmf` to 0.8.5
+  - Update `esmf` and `esmpy` to 8.6.1
+- In environment files `read_the_docs_environment.yml` and `read_the_docs_requirements.txt`
+  - Update `jinja` to 3.1.5 (fixes a security issue)
+- Update `gcpy/setup.py` with the new Python package version numbers
+- Updated code in `gcpy/benchmark/modules/` to replace whitespace in Ref and Dev labels with underscores
+
 ### Fixed
 - Fixed formatting error in `.github/workflows/stale.yml` that caused the Mark Stale Issues action not to run
+- Now flag differences greater than +/- 10% in benchmark timing table outputs
+- Fixed error in computation of dynamic ratio plot min & max values in `plot/six_plot.py`
+- Fixed erroneous species classification in `gcpy/benchmark/modules/benchmark_categories.yml`
+- Fixed type errors in `calc_rectilinear_lon_edge` and `calc_rectangular_lat_edge` by casting the length of the output   array from `float` to `int`
+
+### Removed
+- Removed `gcpy/benchmark/modules/species_database.yml` file and corresponding code pointing to this
 
 ## [1.5.0] - 2024-05-29
 ### Added
@@ -72,8 +105,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Import error in `gcpy/examples/diagnostics/compare_diags.py`
 - Added missing `n_cores` to `gcpy/examples/diagnostics/compare_diags.yml`
 - Added missing `plot_drydep` option to `gcpy/gcpy/benchmark/config/1yr_ch4_benchmark.yml`
-- Add `docs/requirements.txt` symbolic link to `docs/environment_files/read_the_docs_requirements.txt` for RTD builds 
+- Added `docs/requirements.txt` symbolic link to `docs/environment_files/read_the_docs_requirements.txt` for RTD builds
 - `gcpy/file_regrid.py` now tests if `lon_bnds`, `lat_bnds` are in the dataset before trying to drop them
+- Ensured that the header line in the aerosol burden table is written to file
 
 ### Removed
 - Example script `gcpy/examples/plotting/mda8_o3_timeseries.py`

CONTRIBUTING.md

@@ -1,20 +1,22 @@
 # Contributing Guidelines
 
-Thank you for looking into contributing to GCPy! GEOS-Chem is a grass-roots model that relies on contributions from community members like you. Whether you're new to GEOS-Chem or a longtime user, you're a valued member of the community, and we want you to feel empowered to contribute.
+Thank you for looking into contributing to GCPy! GCPy is a grass-roots package that relies on contributions from community members like you. Whether you're new to GCPy or a longtime user, you're a valued member of the community, and we want you to feel empowered to contribute.
 
 ## We use GitHub and ReadTheDocs
+
 We use GitHub to host the GCPy source code, to track issues, user questions, and feature requests, and to accept pull requests: [https://github.com/geoschem/gcpy](https://github.com/geoschem/gcpy). Please help out as you can in response to issues and user questions.
 
 GCPy documentation can be found at [gcpy.readthedocs.io](https://gcpy.readthedocs.io).
 
 ## When should I submit updates?
 
-Submit bug fixes right away, as these will be given the highest priority.  Please see "Support Guidelines" for more information.
+Submit bug fixes right away, as these will be given the highest priority.  Please see **[Support Guidelines](https://gcpy.readthedocs.io/en/stable/reference/SUPPORT.html)** for more information.
 
 The practical aspects of submitting code updates are listed below.
 
 ## How can I submit updates?
-We use [GitHub Flow](https://guides.github.com/introduction/flow/index.html), so all changes happen through pull requests. This workflow is [described here](https://guides.github.com/introduction/flow/index.html).
+
+We use **GitHub Flow**, so all changes happen through [pull requests](https://help.github.com/articles/creating-a-pull-request/). This workflow is [described here](https://docs.github.com/en/get-started/using-github/github-flow).
 
 As the author you are responsible for:
 - Testing your changes
@@ -25,28 +27,35 @@ As the author you are responsible for:
 
   1. Create or log into your [GitHub](https://github.com/) account.
   2. [Fork the GCPy repository](https://help.github.com/articles/fork-a-repo/) into your Github account.
-  5. Clone your fork of the GCPy repositories to your computer system.
-  6. Add your modifications into a [new branch](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) off the **main** branch.
-  7. Test your update thoroughly and make sure that it works.
-  8. Review the coding conventions and checklists for code and data updates listed below.
-  9. Create a [pull request in GitHub](https://help.github.com/articles/creating-a-pull-request/).
-  10. The [GEOS-Chem Support Team](https://wiki.geos-chem.org/GEOS-Chem_Support_Team) will add your updates into the development branch for an upcoming GCPy version.
-  11. If the benchmark simulations reveal a problem with your update, the GCST will request that you take further corrective action.
+  3. Clone your fork of the GCPy repositories to your computer system.
+  4. Add your modifications into a [new branch](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) off the **main** branch.
+  5. Add a sentence to the `CHANGELOG.md` file describing your update.
+  6. Test your update thoroughly and make sure that it works.
+  7. Review the coding conventions and checklists for code and data updates listed below.
+  8. Create a [pull request in GitHub](https://help.github.com/articles/creating-a-pull-request/).
+  9. The [GEOS-Chem Support Team](https://wiki.geos-chem.org/GEOS-Chem_Support_Team) will add your updates into the development branch for an upcoming GCPy version.
+  10. If the benchmark simulations reveal a problem with your update, the GCST will request that you take further corrective action.
 
 ### Coding conventions
-GCPy includes contributions from many people and multiple organizations. Therefore, some inconsistent conventions are inevitable, but we ask that you do your best to be consistent with nearby code.
+
+We recommend that GCPy developers adhere to the [PEP-8 Python style guide](https://peps.python.org/pep-0008/).  You can run `pylint` on all source code files that you modify to ensure adherence to PEP-8 style conventions.
 
 ### Checklist for submitting code updates
 
   1. Include thorough comments in all submitted code.
   2. Include full citations for references at the top of relevant source code modules.
   3. Remove extraneous code updates (e.g. testing options, other science).
+  4. Check that you have updated the `CHANGELOG.md` file.
+  5. Run `pylint` on each source code file that you have modified to check for bugs and conformance to the PEP-8 style conventions.
 
 ## How can I request a new feature?
+
 We accept feature requests through issues on GitHub. To request a new feature, **[open a new issue](https://github.com/geoschem/gcpy/issues/new/choose)** and select the feature request template. Please include all the information that migth be relevant, including the motivation for the feature.
 
 ## How can I report a bug?
+
 Please see **[Support Guidelines](https://gcpy.readthedocs.io/en/stable/reference/SUPPORT.html)**.
 
 ## Where can I ask for help?
+
 Please see **[Support Guidelines](https://gcpy.readthedocs.io/en/stable/reference/SUPPORT.html)**

docs/environment_files/gcpy_environment.yml

@@ -7,37 +7,38 @@
 #
 # $ mamba env create -n gcpy_env --file=/path/to/gcpy/environment.yml
 #
-# These package versions have been proven to work together.
-# See: https://github.com/geoschem/gcpy/issues/284
+# Now updated to use Python 12 and esmf/esmpy 8.6.1 so as to allow
+# installation of GCPy from the Python Package Index (PyPI).
+# See: https://github.com/geoschem/gcpy/issues/326
 # =====================================================================
 name: gcpy_env
 channels:
   - conda-forge
   - nodefaults
 dependencies:
-  - cartopy==0.22.0                 # Geospatial data processing
-  - cf_xarray==0.8.4                # CF conventions for xarray
-  - dask==2023.9.2                  # Parallel library; backend for xarray
+  - cartopy==0.23.0                 # Geospatial data processing
+  - cf_xarray==0.9.1                # CF conventions for xarray
+  - dask==2024.5.2                  # Parallel library; backend for xarray
+  - esmf==8.6.1                     # Earth system modeling framework
+  - esmpy==8.6.1                    # Python wrapper for ESMF
   - gridspec==0.1.0                 # Define Earth System Model grids
-  - ipython==8.15.0                 # Interactive Python (used by Jupyter)
-  - joblib==1.3.2                   # Parallelize python code
+  - ipython==8.25.0                 # Interactive Python (used by Jupyter)
+  - joblib==1.4.2                   # Parallelize python code
   - jupyter==1.0.0                  # Jupyter Notebook
-  - matplotlib==3.8.0               # Creates plots and visualizations
-  - netcdf4==1.6.0                  # Python wrapper for netCDF
-  - netcdf-fortran==4.5.4           # Python wrapper for netCDF-Fortran
-  - numpy==1.26.0                   # Optimized mathematical functions
-  - pandas==2.1.1                   # Tables/timeseries manipulation
-  - pip==23.3                       # Install packages from PyPi
-  - pylint==2.17.5                  # Python linter
+  - matplotlib==3.8.4               # Creates plots and visualizations
+  - netcdf4==1.6.5                  # Python wrapper for netCDF
+  - netcdf-fortran==4.6.1           # Python wrapper for netCDF-Fortran
+  - numpy==1.26.4                   # Optimized mathematical functions
+  - pandas==2.2.2                   # Tables/timeseries manipulation
+  - pip==24.0                       # Install packages from PyPi
+  - pylint==3.2.2                   # Python linter
   - pyproj==3.6.1                   # Python map projections library
-  - python==3.9.18                  # Python language
-  - pypdf==3.17.0                   # PDF utilities (bookmarks, etc.)
-  - requests==2.31.0                # HTTP library
-  - scipy==1.11.2                   # Scientific python package
+  - python==3.12.0                  # Python language
+  - pypdf==4.2.0                    # PDF utilities (bookmarks, etc.)
+  - requests==2.32.3                # HTTP library
+  - scipy==1.13.1                   # Scientific python package
   - sparselt==0.1.3                 # Regridding earth system model data
   - tabulate==0.9.0                 # Pretty-printing for column data
-  - tk==8.6.12                      # Tcl/tk library
-  - xarray==2023.8.0                # Read data from netCDF etc files
-  - esmf==8.1.1                     # Earth system modeling framework
-  - esmpy==8.1.1                    # Python wrapper for ESMF
-  - xesmf==0.5.1                    # Universal regridder
+  - tk==8.6.13                      # Tcl/tk library
+  - xarray==2024.5.0                # Read data from netCDF etc files
+  - xesmf==0.8.5                    # Universal regridder

docs/environment_files/gcpy_requirements.txt

@@ -8,29 +8,29 @@
 # These package versions have been proven to work together.
 # See: https://github.com/geoschem/gcpy/issues/284
 # ======================================================================
-cartopy==0.22.0                 # Geospatial data processing
-cf_xarray==0.8.4                # CF conventions for xarray
-dask==2023.9.2                  # Parallel library; backend for xarray
+cartopy==0.23.0                 # Geospatial data processing
+cf_xarray==0.9.1                # CF conventions for xarray
+dask==2024.5.2                  # Parallel library; backend for xarray
+esmf==8.6.1                     # Earth system modeling framework
+esmpy==8.6.1                    # Python wrapper for ESMF
 gridspec==0.1.0                 # Define Earth System Model grids
-ipython==8.15.0                 # Interactive Python (used by Jupyter)
-joblib==1.3.2                   # Parallelize python code
+ipython==8.25.0                 # Interactive Python (used by Jupyter)
+joblib==1.4.2                   # Parallelize python code
 jupyter==1.0.0                  # Jupyter Notebook
-matplotlib==3.8.0               # Creates plots and visualizations
-netcdf4==1.6.0                  # Python wrapper for netCDF
-netcdf-fortran==4.5.4           # Python wrapper for netCDF-Fortran
-numpy==1.26.0                   # Optimized mathematical functions
-pandas==2.1.1                   # Tables/timeseries manipulation
-pip==23.3                       # Install packages from PyPi
-pylint==2.17.5                  # Python linter
+matplotlib==3.8.4               # Creates plots and visualizations
+netcdf4==1.6.5                  # Python wrapper for netCDF
+netcdf-fortran==4.6.1           # Python wrapper for netCDF-Fortran
+numpy==1.26.4                   # Optimized mathematical functions
+pandas==2.2.2                   # Tables/timeseries manipulation
+pip==24.0                       # Install packages from PyPi
+pylint==3.2.2                   # Python linter
 pyproj==3.6.1                   # Python map projections library
-python==3.9.18                  # Python language
-pypdf==3.17.0                   # PDF utilities (bookmarks, etc.)
-requests==2.32.2                # HTTP library
-scipy==1.11.2                   # Scientific python package
+python==3.12.0                  # Python language
+pypdf==4.2.0                    # PDF utilities (bookmarks, etc.)
+requests==2.32.3                # HTTP library
+scipy==1.13.1                   # Scientific python package
 sparselt==0.1.3                 # Regridding earth system model data
 tabulate==0.9.0                 # Pretty-printing for column data
-tk==8.6.12                      # Tcl/tk library
-xarray==2023.8.0                # Read data from netCDF etc files
-esmf==8.1.1                     # Earth system modeling framework
-esmpy==8.1.1                    # Python wrapper for ESMF
-xesmf==0.5.1                    # Universal regridder
+tk==8.6.13                      # Tcl/tk library
+xarray==2024.5.0                # Read data from netCDF etc files
+xesmf==0.8.5                    # Universal regridder

docs/environment_files/read_the_docs_environment.yml

@@ -19,6 +19,6 @@ dependencies:
   - sphinx-autobuild==2021.3.14
   - recommonmark==0.7.1
   - docutils==0.20.1
-  - jinja2==3.1.3
+  - jinja2==3.1.5
 
 

docs/environment_files/read_the_docs_requirements.txt

@@ -12,6 +12,6 @@ sphinxcontrib-bibtex==2.6.2
 sphinx-autobuild==2021.3.14
 recommonmark==0.7.1
 docutils==0.20.1
-jinja2==3.1.3
+jinja2==3.1.5