fetch4 · joewallwork · May 6, 2024 · Jul 12, 2024 · Jul 15, 2024 · Jul 16, 2024
diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml
@@ -22,7 +22,7 @@ jobs:
       with:
         repo-token: ${{ secrets.GITHUB_TOKEN }}
         stale-issue-label: 'stale'
-        exempt-issue-labels: 'category: Discussion','category: Feature Request','deferred','help needed: Open Research Problem','help needed: Request Input from Community','never stale','TODO: Documentation'
+        exempt-issue-labels: ['category: Discussion','category: Feature Request','deferred','help needed: Open Research Problem','help needed: Request Input from Community','never stale','TODO: Documentation']
         days-before-issue-stale: 30
         days-before-issue-close: 7
         stale-issue-message: 'This issue has been automatically marked as stale because it has not had recent activity. If there are no updates within 7 days it will be closed. You can add the "never stale" tag to prevent the issue from closing this issue.'

diff --git a/.release/changeVersionNumbers.sh b/.release/changeVersionNumbers.sh
@@ -88,7 +88,8 @@ function main() {
     pattern='\[.*Unreleased.*\].*'
     date=$(date -Idate)
     replace "${pattern}" "\[${version}\] - ${date}" "CHANGELOG.md"
-
+    echo "HEMCO version updated to ${version} in CHANGELOG.md"
+
     # Return to the starting directory
     cd "${thisDir}"
 }

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,20 @@ All notable changes to this project 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).
 
+## [3.9.3] - 2024-08-13
+### Fixed
+- Added brackets around `exempt-issue-labels` list in `.github/workflows/stale.yml`
+
+## [3.9.2] - 2024-07-24
+### Changed
+- RTD updates: Converted several `:option:` tags to subsections and updated references accordingly
+
+### Fixed
+- Typos in RTD doc file `docs/source/hco_ref_guide/hemco-config.rst`
+
+### Removed
+- Manual `InvMEGAN` diagnostics from `src/Extensions/hcox_megan_mod.F90`; Activate these with `HEMCO_Diagn.rc` instead
+
 ## [3.9.1] - 2024-06-28
 ### Fixed
 - Fixed formatting error in `.github/workflows/stale.yml` that caused the Mark Stale Issues action not to run

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,7 +1,7 @@
 # HEMCO/CMakeLists.txt
 
 cmake_minimum_required(VERSION 3.5)
-project(HEMCO VERSION 3.9.1 LANGUAGES Fortran)
+project(HEMCO VERSION 3.9.3 LANGUAGES Fortran)
 # Reminder: Make sure to also update version in src/Core/hco_error_mod.F90
 
 #-----------------------------------------------------------------------------

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -3,25 +3,58 @@
 Thank you for looking into contributing to HEMCO! HEMCO is a grass-roots model that relies on contributions from community members like you. Whether you're new to HEMCO 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 HEMCO source code, to track issues, user questions, and feature requests, and to accept pull requests: [https://github.com/geoschem/geos-chem](https://github.com/geoschem/HEMCO). Please help out as you can in response to issues and user questions.
+We use GitHub to host the HEMCO source code, to track issues, user questions, and feature requests, and to accept pull requests: [https://github.com/geoschem/HEMCO](https://github.com/geoschem/HEMCO). Please help out as you can in response to issues and user questions.
 
 HEMCO documentation can be found at [hemco.readthedocs.io](https://hemco.readthedocs.io).
 
+## When should I submit updates?
+
+Submit bug fixes right away, as these will be given the highest priority.  Please see **[Support Guidelines](https://hemco.readthedocs.io/en/stable/reference/SUPPORT.html)** for more information.
+
+Submit updates (code and/or data) for mature model developments once you have submitted a paper on the topic.
+
 ## 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
 - Updating the user documentation (if applicable)
 - Supporting issues and questions related to your changes
 
 ### Coding conventions
-The HEMCO codebase dates back several years and 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.
+The HEMCO codebase dates back several decades and 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.
+
+### Checklist for submitting code updates
+
+  1. Use Fortran-90 free format instead of Fortran-77 fixed format.
+  2. Include thorough comments in all submitted code.
+  3. Include full citations for references at the top of relevant source code modules.
+  4. Check that you have updated the `CHANGELOG.md` file.
+  5. Remove extraneous code updates (e.g. testing options, other science).
+  6. Submit any related code or configuration files for [GCHP](https://gchp.readthedocs.io) along with code or configuration files for [GEOS-Chem Classic](https://geos-chem.readthedocs.io).
+
+### Checklist for submitting data files
+
+  1. Choose a final file naming convention before submitting data files for inclusion to GEOS-Chem.
+  2. Make sure that all netCDF files [adhere to the COARDS conventions](https://geos-chem.readthedocs.io/en/latest/geos-chem-shared-docs/supplemental-guides/coards-guide.html).
+  3. [Concatenate netCDF files](https://geos-chem.readthedocs.io/en/latest/geos-chem-shared-docs/supplemental-guides/netcdf-guide.html#concatenate-netcdf-files)  to reduce the number of files that need to be opened.  This results in more efficient I/O operations.
+  4. [Chunk and deflate netCDF](https://geos-chem.readthedocs.io/en/latest/geos-chem-shared-docs/supplemental-guides/netcdf-guide.html#chunk-and-deflate-a-netcdf-file-to-improve-i-o) files in order to improve file I/O.
+  5. Include an updated [HEMCO configuration file](https://hemco.readthedocs.io/en/latest/hco-ref-guide/hemco-config.html) corresponding to the new data.
+  6. Include a README file detailing data source, contents, etc.
+  7. Include script(s) used to process original data.
+  8. Include a summary or description of the expected results (e.g. emission totals for each species).
+
+Also follow these additional steps to ensure that your data can be read by GCHP:
+
+  1. All netCDF data variables should be of type `float` (aka `REAL*4`) or `double` (aka `REAL*8`).
+  2. Use a recent reference datetime (i.e. after `1900-01-01`) for the netCDF `time:units` attribute.
+  3. The first time value in each file should be 0, corresponding with the reference datetime.
 
 ## 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/hemco/issues/new/choose)** and select the feature request template. Please include your name, institution, motivation for the feature, and all other relevant information.
+We accept feature requests through issues on GitHub. To request a new feature, **[open a new issue](https://github.com/geoschem/HEMCO/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 to report a bug
+## How can I report a bug?
 Please see **[Support Guidelines](https://hemco.readthedocs.io/en/stable/reference/SUPPORT.html)**.
 
 ## Where can I ask for help?

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -23,7 +23,7 @@
 author = 'GEOS-Chem Support Team'
 
 # The full version, including alpha/beta/rc tags
-release = '3.9.1'
+release = '3.9.3'
 
 # -- General configuration ---------------------------------------------------
 

diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs
diff --git a/docs/source/hco-ref-guide/basic-examples.rst b/docs/source/hco-ref-guide/basic-examples.rst
@@ -187,9 +187,9 @@ changed since :ref:`the previous example <edit-hco-cfg-ex1>`.
 
 Note the increased hierarchy (:literal:`2`) of the regional EMEP
 inventory compared to the global MACCity emissions (:literal:`1`) in
-column :option:`Hier`. This will cause the EMEP emissions to replace
-the MACCity emissions in the region where EMEP is defined, which is
-specified by the MASK_EUROPE variable.
+column :ref:`hco-cfg-base-hier`. This will cause the EMEP emissions to
+replace the MACCity emissions in the region where EMEP is defined,
+which is specified by the MASK_EUROPE variable.
 
 .. _edit-hco-cfg-ex3:
 
@@ -232,9 +232,10 @@ modify the :ref:`configuration file <hco-cfg>` accordingly:
 
    ### END SECTION BASE EMISSIONS ###
 
-Note the change in the emission category (column :option:`Cat`) from
-:literal:`1` to :literal:`2`.  In this example, category 1 represents
-anthropogenic emissions and category 2 represents aircraft emissions.
+Note the change in the emission category (column
+:ref:`hco-cfg-base-cat`) from :literal:`1` to :literal:`2`.  In this
+example, category 1 represents anthropogenic emissions and category 2
+represents aircraft emissions.
 
 .. _edit-hco-cfg-ex4:
 
@@ -251,8 +252,8 @@ implemented as a HEMCO Extension, can be added to the simulation by:
    Emissions**.
 
 The extension number defined in the **Extension Switches** section
-must match the corresponding :option:`ExtNr` entry in the Base
-Emissions section (in this example, :literal:`111`).
+must match the corresponding :ref:`hco-cfg-ext-switches-extnr` entry
+in the Base Emissions section (in this example, :literal:`111`).
 
 .. code-block:: kconfig
 

diff --git a/docs/source/hco-ref-guide/diagnostics.rst b/docs/source/hco-ref-guide/diagnostics.rst
@@ -13,9 +13,9 @@ Overview
 HEMCO diagnostics are organized in **collections**, with each
 collection consisting of a dynamic number of diagnostic fields (aka
 **diagnostic containers**). Each collection has a fixed output
-frequency (:option:`DiagnFreq`) assigned to it.  All fields within a
-collection are written out at the same interval: :option:`Hourly`,
-:option:`Daily`, etc.
+frequency (:ref:`hco-cfg-set-diagnfreq`) assigned to it.  All fields
+within a collection are written out at the same interval:
+:literal:`Hourly`, :literal:`Daily`, etc.
 
 The contents of a collection (i.e. the diagnostics containers) are
 defined at the beginning of a simulation and become continuously updated
@@ -39,21 +39,17 @@ averaging method.
 
 Currently supported averaging methods are:
 
-.. option:: instantaneous
-
-   Instantaneous values (recommended method).
-
-.. option:: mean
-
-   Arithmetic mean over the diagnostic interval.
-
-.. option:: sum
-
-   Total sum over the diagnostic interval.
-
-.. option:: cumulsum
-
-   Cumulative sum since simulation start.
++-------------------+------------------------------------------------+
+| Value             | What it does                                   |
++===================+================================================+
+| ``instantaneous`` | Instantaneous values (recommended method).     |
++-------------------+------------------------------------------------+
+| ``mean``          | Arithmetic mean over the diagnostic interval.  |
++-------------------+------------------------------------------------+
+| ``sum``           | Total sum over the diagnostic interval.        |
++-------------------+------------------------------------------------+
+| ``cumulsum``      | Cumulative sum since simulation start.         |
++-------------------+------------------------------------------------+
 
 Explicitly setting the averaging method will disable automatic unit
 conversion and the fields passed to this diagnostic will be stored as
@@ -87,28 +83,27 @@ The Default collection
 The **Default** collection contains emission diagnostics intended to
 be written to disk, e.g. for analysis purposes. All fields of the
 default collection are written out at the frequency provided in
-setting :option:`DiagnFreq` in the settings section of the HEMCO
-configuration file. The name of the corresponding diagnostics files
-can be specified via the :code:`DiagnPrefix` setting. The simulation
-date at the time of output will be appended to the diagnostics prefix,
-e.g. the diagnostics for Aug 1, 2008 will be written as
-:file:`HEMCO_Diagnostics.200808010000.nc`. The  datetime can denote
-the beginning, middle, or end (default) of the time interval, as
-specified by setting :option:`DiagnTimeStamp` (see below).
-
-Several :ref:`options for the default diagnostic collection
-<hco-cfg-settings-diagnostics>` can be specified at the top of the
-:ref:`HEMCO configuration file <hco-cfg>` file.  Commonly-used options
-are :option:`DiagnFile`, :option:`DiagnFreq`, and
-:option:`DiagnPrefix`.
+setting :ref:`hco-cfg-set-diagnfreq` in the settings section of the
+HEMCO configuration file. The name of the corresponding diagnostics files
+can be specified via the :ref:`hco-cfg-set-diagnprefix` setting. The
+simulation date at the time of output will be appended to the
+diagnostics prefix, e.g. the diagnostics for Aug 1, 2008 will be
+written as :file:`HEMCO_Diagnostics.200808010000.nc`. The datetime
+can denote the beginning, middle, or end (default) of the time
+interval, as specified by setting ::ref:`hco-cfg-set-diagntimestamp`.
+
+Several options for the default diagnostic collection can be specified
+at the top of the :ref:`HEMCO configuration file <hco-cfg>` file.
+Commonly-used options are :ref:`hco-cfg-set-diagnfile`,
+:ref:`hco-cfg-set-diagnfreq`, and :ref:`hco-cfg-set-diagnprefix`.
 
 .. _hco-diag-configfile:
 
 Configuration file for the Default collection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You may specify the name of the Default diagnostics configuration file
-with the :option:`DiagnFile` option in :ref:`the
+with the :ref:`hco-cfg-set-diagnfile` option in :ref:`the
 HEMCO configuration file <hco-cfg>`. This file, which is customarily
 named :file:`HEMCO_Diagn.rc`, uses the following format:
 
@@ -119,58 +114,42 @@ named :file:`HEMCO_Diagn.rc`, uses the following format:
 
 The columns of :file:`HEMCO_Diagn.rc` allow you to specify several options:
 
-.. option:: Name
-
-   netCDF variable name under which this diagnostic quantity will be
-   named in the HEMCO diagnostic output files.
-
-.. option:: Spec
-
-   Species short name (same as in :ref:`the HEMCO configuration file
-   <hco-cfg>`) .
-
-.. option:: ExtNr
-
-   Extension number  (same as in :ref:`the HEMCO configuration file
-   <hco-cfg>`) .
-
-   The :literal:`-1` value means to sum over all extensions.
-
-.. option:: Cat
-
-   Category (same as in :ref:`the HEMCO configuration file
-   <hco-cfg>`).
-
-   The :literal:`-1` value means to sum over all categories.
-
-.. option:: Hier
-
-   Hierarchy (same as in :ref:`the HEMCO configuration file
-   <hco-cfg>`).
-
-   The :literal:`-1` value means to sum over all categories.
-
-.. option:: Dim
-
-   Number of dimensions that you wish this diagnostic to have:
-
-   - :literal:`1`: Scalar
-   - :literal:`2`: Lat-lon or X-Y
-   - :literal:`3`: Lat-lon-lev or X-Y-Z
-
-.. option:: LongName
-
-   A longer descriptive name for the diagnostic.  This will be used to
-   define the netCDF :literal:`long_name` variable attribute in the
-   HEMCO diagnostic files.
++---------------+------------------------------------------------------------------+
+| Option        | What it does                                                     |
++===============+==================================================================+
+| ``Name``      | netCDF variable name under which this diagnostic quantity will   |
+|               | stored in the HEMCO diagnostic output files.                     |
++---------------+------------------------------------------------------------------+
+| ``Spec``      | :ref:`Species short name <hco-cfg-base-species>` as listed in    |
+|               | :ref:`the HEMCO configuration file <hco-cfg>`.                   |
++---------------+------------------------------------------------------------------+
+| ``ExtNr``     | :ref:`Extension number <hco-cfg-ext-switches-extnr>`.            |
+|               | The :literal:`-1` value means to sum over all extensions.        |
++---------------+------------------------------------------------------------------+
+| ``Cat``       | :ref:`Emission Category <hco-cfg-base-cat>`.                     |
+|               | The :literal:`-1` value means to sum over all categories.        |
++---------------+------------------------------------------------------------------+
+| ``Hier``      | :ref:`Emission Hierarchy <hco-cfg-base-hier>`.                   |
+|               | The :literal:`-1` value means to sum over all hierarchies.       |
++---------------+------------------------------------------------------------------+
+| ``Dim``       | Number of dimensions that you wish this diagnostic to have:      |
+|               |                                                                  |
+|               | - :literal:`1`: Scalar                                           |
+|               | - :literal:`2`: Lat-lon or X-Y                                   |
+|               | - :literal:`3`: Lat-lon-lev or X-Y-Z                             |
++---------------+------------------------------------------------------------------+
+| ``LongName``  | A longer descriptive name for the diagnostic.  This will define  |
+|               | the netCDF :literal:`long_name` variable attribute in the        |
+|               | HEMCO diagnostic files.                                          |
++---------------+------------------------------------------------------------------+
 
 Here are a few examples.
 
 #. **Basic usage**
 
    Adding these entries to :file:`HEMCO_Config.rc` will make HEMCO write
    out total NO and CO emissions, as well as GFED biomass burning CO
-   emissions (e.g. only emissions from :option:`ExtNr` 111):
+   emissions (e.g. only emissions from :ref:`hco-cfg-ext-switches-extnr` 111):
 
    .. code-block:: kconfig
 
@@ -182,10 +161,10 @@ Here are a few examples.
 
 #. **Archive diagnostics for regional emissions**
 
-   To diagnose regional emissions, you must set :option:`ExtNr`,
-   :option:`Cat`, and :option:`Hier` accordingly.  The example below
-   defines a diagnostic entry for CO emissions from the EPA16 USA
-   inventory:
+   To diagnose regional emissions, you must set
+   :ref:`hco-cfg-ext-switches-extnr`, :ref:`hco-cfg-base-cat`, and
+   :ref:`hco-cfg-base-hier` accordingly. The example below defines
+   a diagnostic entry for CO emissions from the EPA16 USA inventory:
 
    .. code-block:: kconfig
 
@@ -262,7 +241,7 @@ Importing diagnostic content into an external model
 
 The content of the :ref:`Default collection <hco-diag-default>` can
 be specified through the HEMCO diagnostics definitions file (specified
-by the :option:`DiagnFile` option).
+by the :ref:`hco-cfg-set-diagnfile` option).
 
 The content of the :ref:`Manual <hco-diag-manual>` and
 :ref:`Restart <hco-diag-restart>` collections currently need to
+132 −0		supplemental-guides/data-on-aws.rst
+25 −0		supplemental-guides/geos-chem-input-data-on-aws.rst
+90 −0		supplemental-guides/getting-started-aws.rst
+14 −14		supplemental-guides/related-docs.rst
+5 −3		supplemental-guides/using-kpp-with-gc.rst
+21 −0		supplemental-guides/why-on-cloud.rst