ReadTheDocs updates for HEMCO 3.10.0

CHANGELOG.md

@@ -5,6 +5,17 @@ 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).
 
+## [Unreleased] - TBD
+### Changed
+- 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
+- Now use `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`

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/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-sa-guide/login-env.rst

@@ -4,17 +4,18 @@
 Configure your login environment
 ################################
 
+.. tip::
+
+   You may :ref:`skip ahead <hco-sa-download>` if you will be using
+   :program:`GEOS-Chem Classic` on an Amazon EC2 cloud instance.
+   When you initialize the EC2 instance with one of the pre-configured Amazon
+   Machine Images  (AMIs) all of the required software libraries will be
+   automatically loaded.
+
 In this chapter, you will learn how to load the software packages that
 you have created into your computational environment.  This will need
 to be done each time you log in to your computer system.
 
-.. tip::
-
-   You may skip this section if you plan on using HEMCO standalone on
-   an Amazon EC2 cloud instance.  When you initialize the EC2 instance
-   with one of the pre-configured Amazon Machine Images (AMIs) all of
-   the required software libraries will be automatically loaded.
-
 An environment file does the following:
 
   1. Loads software libraries into your login environment.  This is
@@ -40,36 +41,64 @@ or :file:`~/.bash_aliases` startup scripts.
 .. _hco-sa-login-gnu:
 
 ================================================
-Sample environment file for GNU 10.2.0 compilers
+Sample environment file for GNU 12.2.0 compilers
 ================================================
 
-Below is a sample environment file from the Harvard Cannon computer
-cluster.  This file will load software libraries built with the GNU
-10.2.0 compilers.
+Below is a sample environment file (based on an enviroment file for
+the Harvard Cannon computer cluster).  This file will load software
+libraries built with the `GNU 12.2.0 compilers
+<https://gcc.gnu.org/onlinedocs/12.2.0/>`_.
+
+.. note::
+
+   This environment file shown below assumes that required software
+   packages for :program:`GEOS-Chem Classic` are available as
+   pre-built modules.  If your computer system does not have these
+   packages pre-installed, you can build them with Spack.  Please see
+   our :ref:`spackguide` supplemental guide for detailed instructions.
 
 Save the code below (with any appropriate modifications for your own
-computer system) to a file named :file:`~/gnu10.env`.
+computer system) to a file named :file:`~/gnu12.env`.
 
 .. code-block:: bash
 
+   ###############################################################################
+   #
+   # Environment file for HEMCO + GNU Compiler Collection 12.2.0
+   #
+   ###############################################################################
+
+   # Display message (if we are in a terminal window)
+   if [[ $- = *i* ]] ; then
+     echo "Loading modules for GEOS-Chem Classic, please wait ..."
+   fi
+
    #==============================================================================
-   # Load software packages (EDIT AS NEEDED)
+   # Unload all previously-unloaded software
    #==============================================================================
 
-   # Unload all modules first
+   # Unload packages loaded with "module load"
    module purge
 
-   # Load modules
-   module load gcc/10.2.0-fasrc01             # gcc / g++ / gfortran
-   module load openmpi/4.1.0-fasrc01          # MPI
-   module load netcdf-c/4.8.0-fasrc01         # netcdf-c
-   module load netcdf-fortran/4.5.3-fasrc01   # netcdf-fortran
+   #==============================================================================
+   # Load software packages for GNU 12.2.0
+   #==============================================================================
+   if [[ $- = *i* ]] ; then
+     echo "... Loading FASRC-built software, please wait ..."
+   fi
+
+   # Pre-built modules needed for HEMCO
+   # (NOTE: These may be named differently on your system)
+   module load gcc/12.2.0-fasrc01             # gcc / g++ / gfortran
+   module load openmpi/4.1.4-fasrc01          # MPI
+   module load netcdf-c/4.9.2-fasrc01         # netcdf-c
+   module load netcdf-fortran/4.6.0-fasrc02   # netcdf-fortran
    module load flex/2.6.4-fasrc01             # Flex lexer (needed for KPP)
    module load cmake/3.25.2-fasrc01           # CMake (needed to compile)
 
    #==============================================================================
    # Environment variables and related settings
-   # (NOTE: Lmod will define <module>_HOME variables for each loaded module
+   # (NOTE: Lmod will define <module>_HOME variables for each loaded module)
    #==============================================================================
 
    # Make all files world-readable by default
@@ -94,13 +123,13 @@ computer system) to a file named :file:`~/gnu10.env`.
 
    # netCDF
    if [[ "x${NETCDF_HOME}" == "x" ]]; then
-      export NETCDF_HOME="${NETCDF_C_HOME}"
+       export NETCDF_HOME="${NETCDF_C_HOME}"
    fi
    export NETCDF_C_ROOT="${NETCDF_HOME}"
-   export NETCDF_FORTRAN_ROOT="${NETCDF_FORTRAN_HOME}"
+   export NETCDF_FORTRAN_ROOT=${NETCDF_FORTRAN_HOME}
 
    # KPP 3.0.0+
-   export KPP_FLEX_LIB_DIR="${FLEX_HOME}/lib64"
+   export KPP_FLEX_LIB_DIR=${FLEX_HOME}/lib64
 
    #==============================================================================
    # Set limits
@@ -114,20 +143,38 @@ computer system) to a file named :file:`~/gnu10.env`.
    #==============================================================================
    # Print information
    #==============================================================================
+
    module list
 
+   echo ""
+   echo "Environment:"
+   echo ""
+   echo "CC                  : ${CC}"
+   echo "CXX                 : ${CXX}"
+   echo "FC                  : ${FC}"
+   echo "KPP_FLEX_LIB_DIR    : ${KPP_FLEX_LIB_DIR}"
+   echo "MPI_HOME            : ${MPI_HOME}"
+   echo "NETCDF_HOME         : ${NETCDF_HOME}"
+   echo "NETCDF_FORTRAN_HOME : ${NETCDF_FORTRAN_HOME}"
+   echo "OMP_NUM_THREADS     : ${OMP_NUM_THREADS}"
+   echo ""
+   echo "Done sourcing ${BASH_SOURCE[0]}"
+
 .. tip::
 
    Ask your sysadmin how to load software libraries.  If you are using
    your institution's computer cluster, then chances are there will
    be a software module system installed, with commands similar to
    those listed above.
 
-Then you can activate these seetings from the command line by typing:
+You may also place the above command within your HEMCO standalone run
+script, which will be discussed in a subsequent chapter.
+
+To activate the settings contained in the environment file, type:
 
 .. code-block:: console
 
-   $ source ~/gnu10.env
+   $ . ~/gnu12.env
 
 .. _hco-sa-login-intel:
 
@@ -144,9 +191,11 @@ system) into a file named :file:`~/intel23.env`.
 
 .. code-block:: bash
 
-   #==============================================================================
-   # Load software packages (EDIT AS NEEDED)
-   #==============================================================================
+   ###############################################################################
+   #
+   # Environment file for HEMCO + GNU Compiler Collection 12.2.0
+   #
+   ###############################################################################
 
    # Unload all modules first
    module purge
@@ -208,18 +257,33 @@ system) into a file named :file:`~/intel23.env`.
 
    module list
 
+   echo ""
+   echo "Environment:"
+   echo ""
+   echo "CC                  : ${CC}"
+   echo "CXX                 : ${CXX}"
+   echo "FC                  : ${FC}"
+   echo "KPP_FLEX_LIB_DIR    : ${KPP_FLEX_LIB_DIR}"
+   echo "MPI_HOME            : ${MPI_HOME}"
+   echo "NETCDF_HOME         : ${NETCDF_HOME}"
+   echo "NETCDF_FORTRAN_HOME : ${NETCDF_FORTRAN_HOME}"
+   echo "OMP_NUM_THREADS     : ${OMP_NUM_THREADS}"
+   echo ""
+   echo "Done sourcing ${BASH_SOURCE[0]}"
+
+
 .. tip::
 
    Ask your sysadmin how to load software libraries.  If you
    are using your institution's computer cluster, then chances
    are there will be a software module system installed, with
    commands similar to those listed above.
 
-Then you can activate these seetings from the command line by typing:
+To activate the settings contained in the environment file, type:
 
 .. code-block:: console
 
-   $ source intel23.env
+   $ . intel23.env
 
 .. tip::
 
@@ -253,7 +317,7 @@ These environment variables should be defined in your
 
 .. note::
 
-   HEMCOc only requires the Fortran compiler.  But you will
+   HEMCO only requires the Fortran compiler.  But you will
    also need the C and C++ compilers if you plan to build other
    software packages or :ref:`install libraries manually <spackguide>`.
 
@@ -310,8 +374,8 @@ control the OpenMP parallelization settings:
       ulimit -s unlimited
       export OMP_STACKSIZE=500m
 
-   The :command:`ulimit -s unlimited` will tell the bash shell to use the
-   maximum amount of stack memory that is available.
+   The :command:`ulimit -s unlimited` command will tell the bash shell
+   to use the maximum amount of stack memory that is available.
 
    The environment variable :envvar:`OMP_STACKSIZE` must also be set to a very
    large number. In this example, we are nominally requesting 500 MB of

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

@@ -18,7 +18,8 @@ installed on your system in order to use :program:`HEMCO standalone`.
 
 - If you plan to run HEMCO standalone on the Amazon Web services
   cloud, then all of these libraries will be included with the Amazon
-  Machine Image (AMI) that you will use to start your cloud instance. |br|
+  Machine Image (AMI) that you will use to start your cloud instance.
+  You may skip ahead to the :ref:`hco-sa-download` chapter. |br|
   |br|
 
 - If your computer cluster has none of these libraries installed, then

run/runHEMCO.sh

@@ -3,7 +3,7 @@
 #SBATCH -c 8
 #SBATCH -N 1
 #SBATCH -t 0-12:00
-#SBATCH -p huce_intel
+#SBATCH -p sapphire,huce_cascade,seas_compute,shared
 #SBATCH --mem=15000
 #SBATCH --mail-type=END
 
@@ -12,7 +12,7 @@ export OMP_NUM_THREADS=$SLURM_CPUS_PER_TASK
 
 # Run GEOS_Chem.  The "time" command will return CPU and wall times.
 # Stdout and stderr will be directed to the log files specified above.
-time ./hemco_standalone -c HEMCO_sa_Config.rc
+time ./hemco_standalone -c HEMCO_sa_Config.rc > HEMCO_sa.log 2>&1
 
 # Exit normally
 exit 0