HEMCO 3.10.0 release

Updated version numbers in:
- CHANGELOG.md
- CMakeLists.txt
- docs/source/conf.py
- src/Core/hco_error_mod.F90

Please see the CHANGELOG.md for updates included in this version.

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

.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.'

CHANGELOG.md

@@ -5,9 +5,31 @@ 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.10.0] - 2024-11-07
+### Added
+- Added TSOIL1 field to `ExtState`
+- Added `download_data.py` and `download_data.yml` to the `run` folder.  These will be copied into HEMCO standalone rundirs
+- Added `run/cleanRunDir.sh` script to remove old output files & log files
+- Added documentation for the HEMCO 3.10.0 release, including HEMCO standalone dry-run documentation
+
+### Changed
+- Added emission factors for ALK6, C4H6, EBZ, STYR, TMB for GFED and FINN biomass burning extensions
+- Updated soil NOx extention to include the option to use soil temperature and parameterization based on Yi Wang et al. (ERL, 2021) instead of the temperature at 2 meters.
+- Updated HEMCO standalone to print the dry-run header to the HEMCO log file unit `HcoState%Config%Err%Lun` only if the file is opened
+- ReadTheDocs update: Now use GNU 12.2.0 compilers in environment file examples
+- Updated `runHEMCO.sh` standalone script: Change partitions, and pipe output to log file
+
+### Fixed
+- Fixed formatting error in `.github/workflows/stale.yml` that caused the Mark Stale Issues action not to run
+- Updated to `jinja2==3.1.4` in `docs/requirements.txt` (fixes a security issue)
+
+### Removed
+- Example "Scale (or zero) emissions with a rectangular mask" from ReadTheDocs. This is currently not working.
+
 ## [3.9.3] - 2024-08-13
 ### Fixed
 - Added brackets around `exempt-issue-labels` list in `.github/workflows/stale.yml`
+- Fixed incorrect pressure handling in HEMCO standalone (see issue #277)
 
 ## [3.9.2] - 2024-07-24
 ### Changed

CMakeLists.txt

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

docs/requirements.txt

@@ -12,4 +12,4 @@ 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.4

docs/source/conf.py

@@ -23,7 +23,7 @@
 author = 'GEOS-Chem Support Team'
 
 # The full version, including alpha/beta/rc tags
-release = '3.9.3'
+release = '3.10.0'
 
 # -- General configuration ---------------------------------------------------
 

docs/source/hco-ref-guide/known-bugs.rst

@@ -4,18 +4,15 @@
 Known bugs and issues
 #####################
 
-Please see our `HEMCO issue tracker on Github
-<https://github.com/geoschem/HEMCO/issues>`_ for a list of recent
-HEMCO bugs and fixes.
-
-===================
-Current bug reports
-===================
-
-These `bug reports (listed on the  HEMCO issue tracker)
-<https://github.com/geoschem/HEMCO/issues?q=is%3Aissue+is%3Aopen+label%3Abug>`_
-are currently unresolved.  We hope to fix these in
-future HEMCO releases.
+Please see our HEMCO issue tracker on Github for a list of recent
+HEMCO bugs and fixes:
+
+- `Bugs and issues that have not yet been resolved
+  <https://github.com/geoschem/HEMCO/issues?q=is%3Aissue+is%3Aopen+bug+label%3A%22category%3A+Bug%22>`_
+- `Bugs that have been resolved
+  <https://github.com/geoschem/HEMCO/issues?q=is%3Aissue+bug+is%3Aclosed+label%3A%22category%3A+Bug%22>`_
+
+Other known issues are listed below:
 
 =====================================
 Masks cannot be applied to extensions

docs/source/hco-ref-guide/more-examples.rst

@@ -90,53 +90,6 @@ These steps can also be used to scale emissions for different regions
 (e.g. provinces, states) by providing HEMCO with a mask file
 containing the regions to be scaled.
 
-
-.. _cfg-ex-scl-rec-mask:
-
-Scale (or zero) emissions with a rectangular mask
--------------------------------------------------
-
-.. important::
-
-   If you are using HEMCO versions prior to 3.5.0, you may encounter a
-   bug when trying to follow this example. See Github issue:
-   https://github.com/geoschem/HEMCO/issues/153 for a workaround.
-
-Another way to scale all emissions over a country (or set them to
-zero) is to apply a rectangular mask.
-
-For example, to set all emissions over Australia and surrounding
-islands to zero, add this line to the :ref:`hco-cfg-masks` section of
-:ref:`the HEMCO configuration file <hco-cfg>`:
-
-.. code-block:: kconfig
-
-    1010 AUS_MASK 105.0/-46.0/160.0/-10.0 - 2000/1/1/0 C xy 1 1 105/-46/160/–10
-
-Here you directly provide the lower left and upper right corner of the
-mask region mask instead of a netCDF file:
-:literal:`lon1/lat1/lon2/lat2` You can then combine this mask with
-a scale factor of zero to eliminate any emissions over that area.
-
-In :ref:`Base emissions <hco-cfg-base>`
-
-.. code-block:: kconfig
-
-    0 HTAP_NO_IND /path/to/HTAP_NO_INDUSTRY.generic.01x01.nc emi_no 2008-2010/1-12/1/0 C xy kg/m2/s NO 1/27/25/501 1/2 4
-
-In :ref:`Scale Factors <hco-cfg-scalefac>`:
-
-.. code-block:: kconfig
-
-   501 SCALE_AUS 0.0 - - - xy unitless 1 1010
-
-In :ref:`hco-cfg-masks`:
-
-.. code-block:: kconfig
-
-   # Defines a rectangular region that should cover AUS + surrounding islands
-   1010 AUS_MASK 105.0/-46.0/160.0/-10.0 – 2000/1/1/0 C xy 1 1 105.0/-46.0/160.0/-10.0
-
 .. _cfg-ex-scl-spc:
 
 Scale emissions by species

docs/source/hco-ref-guide/version-history.rst

@@ -4,6 +4,10 @@
 HEMCO version history
 #####################
 
-Please see the `CHANGELOG.md file the HEMCO GitHub repository
-<https://github.com/geoschem/HEMCO/blob/main/CHANGELOG.md>`_ for a
-list of updates by HEMCO version.
+For more information about HEMCO versions, please see:
+
+- `The CHANGELOG.md file
+  <https://github.com/geoschem/HEMCO/blob/main/CHANGELOG.md>`_
+
+- `The Releases page at github.com/geoschem/HEMCO
+  <https://github.com/geoschem/HEMCO/releases>`_

docs/source/hco-sa-guide/download-code.rst

@@ -11,15 +11,11 @@ default.
 
 .. code-block:: console
 
-   $ git clone https://github.com/geoschem/hemco.git HEMCO
+   $ git clone --recurse-submodules https://github.com/geoschem/hemco.git HEMCO
    $ cd HEMCO
 
-If you would like a different version of HEMCO you can check out a
-different branch.  For example, to check out the **dev** branch, type:
-
-.. code-block:: console
-
-  $ git checkout dev
+This will place you on the **main** branch, which contains the latest
+stable release of HEMCO.
 
 .. tip::
 

docs/source/hco-sa-guide/download-data.rst

@@ -8,16 +8,27 @@ Before starting a HEMCO standalone simulation, make sure that all of
 the relevant emissions and meteorology that you will need for your
 simulation are present on disk.
 
-If you are located at an institution where there are several other
-HEMCO and/or `GEOS-Chem <https://geos-chem.readthedocs.io>`_ users,
-then data for HEMCO standalone might already be located in a shared
-folder.  Ask your sysadmin or IT staff.
-
-If you are using HEMCO standalone on the Amazon Web Services EC2
-cloud computing platform, then you will have access to an S3 bucket
-(:file:`s3://gcgrid/`) with emissions inventories and meteorological data.
-
-If you still need to download data for your HEMCO standalone
-simulation, we recommend using the :program:`bashdatacatalog` tool.
-For more information, please see our Supplemental Guide entitled
-:ref:`bashdatacatalog`.
+.. tip::
+
+   If you are located at an institution where there are several other
+   HEMCO and/or `GEOS-Chem <https://geos-chem.readthedocs.io>`_ users,
+   then data for HEMCO standalone might already be located in a shared
+   folder.  Ask your sysadmin or IT staff.
+
+The :ref:`GEOS-Chem Input Data <gcid>` portal is the main source of
+emissions and meteorology simulations. This data, which is curated by
+the GEOS-Chem Support Team at Washington University in St. Louis, is stored an
+Amazon Web Services S3 bucket named `s3://geos-chem
+<https://geos-chem.s3.amazonaws.com/index.html>`_.  You can easily
+download the data from there to your computer cluster or AWS EC2 cloud
+instance.
+
+You can use a couple of different methods to download data.  Click on
+one of the links below for more information.
+
+.. toctree::
+   :maxdepth: 1
+
+   hco-sa-dry-run.rst
+   ../geos-chem-shared-docs/supplemental-guides/bashdatacatalog.rst
+   hco-sa-globus.rst

docs/source/hco-sa-guide/hardware.rst

@@ -1,3 +1,7 @@
+.. |br| raw:: html
+
+   <br />
+
 .. _hco-sa-hard:
 
 ############################
@@ -17,9 +21,8 @@ Computer system requirements
 Before you can run HEMCO standalone, you will need to have
 one the following items.
 
-#. A Unix/Linux based computer system, OR:
-#. An account on the `Amazon Web Services cloud computing platform
-   <http://geos-chem-cloud.readthedocs.io/>`_.
+#. A Linux based computer system, OR:
+#. An account on the Amazon Web Services cloud computing platform.
 
 If your institution has computational resources (e.g. a shared
 computer cluster with many cores, sufficient disk storage and memory),
@@ -32,16 +35,27 @@ should consider signing up for access to the Amazon Web Services
 cloud. Using the cloud has the following advantages:
 
 #. You can run HEMCO standalone without having to invest in
-   local hardware and maintenance personnel.
+   local hardware and maintenance personnel. |br|
+   |br|
+
 #. You won't have to download any meteorological fields or emissions
    data. All of the necessary data input for HEMCO standalone
-   will be available on the cloud.
+   will be available on the cloud. |br|
+   |br|
+
 #. You can initialize your computational environment with all of the
-   required software (e.g. compilers,libraries, utilities) that you
-   need for HEMCO standalone.
+   required software (e.g. compilers, libraries, utilities) that you
+   need for HEMCO standalone. |br|
+   |br|
+
 #. Your runs will be 100% reproducible, because you will initialize
-   your computational environment the same way every time.
-#. You will avoid compilation errors due to library incompatibilities.
+   your computational environment the same way every time. |br|
+   |br|
+
+#. You will avoid compilation errors due to library
+   incompatibilities. |br|
+   |br|
+
 #. You will be charged for the computational time that you use, and if
    you download data off the cloud.