Updated ReadTheDocs documentation for the 14.5.0 release

CHANGELOG.md CMakeLists.txt docs/source/conf.py src/GEOS-Chem/CHANGELOG.md src/GEOS-Chem/KPP/fullchem/CHANGELOG_fullchem.md - Updated version numbers from 14.4.3 to 14.5.0 docs/requirements.txt - Update Python package jinja2 needed for ReadTheDocs from 3.1.3 to 3.1.4 (fixes a security issue) docs/source/gcclassic-user-guide/*.rst docs/source/getting-started/*.rst docs/source/geos-chem-shared-docs - Updated documentation for 14.5.0. Includes: - New documentation for the GEOS-Chem Input Data portal on AWS - Corresponding updates to the dry-run simulation docs - Moved doc common to GCClassic, GCHP, HEMCO to geos-chem-shared-docs - Added warnings in doc about GEOS-FP convection update on 6/1/20 - Updated links and references src/GEOS-Chem - Submodule update (updated version numbers to 14.5.0) Signed-off-by: Bob Yantosca <[email protected]>
geoschem · Nov 8, 2024 · bef8b4b · bef8b4b
2 parents 2d8b6e0 + 09b6822
commit bef8b4b
Show file tree

Hide file tree

Showing 34 changed files with 581 additions and 2,737 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,14 +7,18 @@ This file documents all notable changes to the GEOS-Chem Classic wrapper reposit
 
 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
+## [14.5.0] - 2024-11-08
 ### Changed
 - Updated GEOS-Chem to 14.5.0
 - Updated HEMCO to 3.10.0
 - Updated Cloud-J to 8.0.1
+- Updated `docs/source/geos-chem-shared-docs/spack/packages.yaml` to use GCC 12.2.0 compilers
+- Updated documentation for version 14.5.0
+- Moved several doc files (not supplemental guides) that are used in both GCClassic and GCHP the to `geos-chem-shared-docs/doc` folder
 
 ### Fixed
 - Fixed formatting error in `.github/workflows/stale.yml` that caused the Mark Stale Issues action not to run
+- Updated to Python package `jinja2==3.1.4` in `docs/requirements.txt` (fixes a security issue)
 
 ## [14.4.3] - 2024-08-13
 ### Changed

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -2,7 +2,7 @@
 
 cmake_minimum_required (VERSION 3.13)
 project (geos-chem-classic
-  VERSION 14.4.3
+  VERSION 14.5.0
   LANGUAGES Fortran
 )
 

diff --git a/docs/requirements.txt b/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
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 = '14.4.3'
+release = '14.5.0'
 
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/source/gcclassic-user-guide/compile-cmake.rst b/docs/source/gcclassic-user-guide/compile-cmake.rst
@@ -433,17 +433,16 @@ Classic contains code from the various repositories:
 
    .. note::
 
-   If you are cloning GEOS-Chem Classic between official releases, you
-   may the see :code:`Current status` reported like this:
+      If you are cloning GEOS-Chem Classic between official releases, you
+      may the see :code:`Current status` reported like this:
 
-   .. code-block:: console
+      .. code-block:: console
 		      
-      X.Y.Z-alpha.n-C-gabcd1234.dirty  or
+         X.Y.Z-alpha.n-C-gabcd1234.dirty  or
 
-      X.Y.Z.rc.n-C.gabcd1234.dirty
+         X.Y.Z.rc.n-C.gabcd1234.dirty
 
-   We will explain these formats below. |br|
-   |br|
+      We will explain these formats below.
 
 #. `HEMCO (Harmonized Emissions Component) submodule <https://github.com/geoschem/hemco.git>`_:
 

diff --git a/docs/source/gcclassic-user-guide/config-overview.rst b/docs/source/gcclassic-user-guide/config-overview.rst
@@ -27,9 +27,9 @@ edit most (if not all) of these configuration files:
 .. toctree::
    :maxdepth: 1
 
-   geoschem-config.rst
-   hemco-config.rst
-   hemco-diagn.rst
+   ../geos-chem-shared-docs/doc/geoschem-config.rst
+   ../geos-chem-shared-docs/doc/hemco-config.rst
+   ../geos-chem-shared-docs/doc/hemco-diagn.rst
    history.rst
 
 All of the above-mentioned files are included in your :ref:`GEOS-Chem
@@ -52,5 +52,5 @@ you'll need to edit these configuration files:
 .. toctree::
    :maxdepth: 1
 
-   spec-db.rst
-   phot-chem.rst
+   ../geos-chem-shared-docs/doc/spec-db.rst
+   ../geos-chem-shared-docs/doc/phot-chem.rst
diff --git a/docs/source/gcclassic-user-guide/download-data.rst b/docs/source/gcclassic-user-guide/download-data.rst
@@ -5,7 +5,7 @@ Download input data
 ###################
 
 In the following chapters, you will learn how to download input data
-for your GEOS-Chem simulation:
+for your GEOS-Chem simulation.
 
 .. note::
 
@@ -18,6 +18,7 @@ for your GEOS-Chem simulation:
 .. toctree::
    :maxdepth: 2
 
-   input-overview.rst
+   ../geos-chem-shared-docs/doc/gcid-portal-overview.rst
+   ../geos-chem-shared-docs/doc/gcid-special-portals.rst
    restart-files.rst
    dry-run.rst
diff --git a/docs/source/gcclassic-user-guide/dry-run-download.rst b/docs/source/gcclassic-user-guide/dry-run-download.rst
@@ -1,3 +1,7 @@
+.. |br| raw:: html
+
+   <br />
+
 .. _dry-run-download:
 
 #################################
@@ -7,8 +11,8 @@ Download data from dry-run output
 Once you have successfully executed a GEOS-Chem dry-run, you
 can use the output from the dry-run (contained in the :file:`log.dryrun` file)
 to download the data files that GEOS-Chem will need to perform the
-corresponding "production" simulation. You may download from one of
-several locations, which are described in the following sections.
+corresponding "production" simulation. You may download from different
+:ref:`data repositories <dry-run-data-download-portal>`.
 
 .. important::
 
@@ -40,118 +44,141 @@ several locations, which are described in the following sections.
 Choose a data portal
 ====================
 
-You can :ref:`download input data <data>` from one of the following
-locations:
-
-.. _dry-run-download-washu:
-
-The :file:`geoschemdata.wustl.edu` site (aka WashU)
----------------------------------------------------
-
-If you are using GEOS-Chem on your institutional computer cluster, we
-recommend that you **download data from the WashU (Washington
-University in St. Louis) site** (`http://geoschemdata.wustl.edu
-<http://geoschemdata.wustl.edu>`_).  This site, which is
-maintained by Randall Martin's group at WashU, is the main data site
-for GEOS-Chem.
-
-.. tip::
-
-   We have also set up a `Globus
-   <https://www.globus.org/data-transfer>`_ endpoint named **GEOS-Chem
-   data (WashU)** on the WashU site.  If you need to
-   download many years of data, it may be faster to use	 Globus
-   (particularly if your home institution supports it).
-
-.. _dry-run-download-aws:
-
-The :file:`s3://gcgrid` bucket (aka Amazon)
--------------------------------------------
-
-If you are running GEOS-Chem Classic on the Amazon Web Services cloud,
-you can quickly **download the necessary data for your GEOS-Chem
-simulation from the** :file:`s3://gcgrid` **bucket** to the Elastic Block
-Storage (EBS) volume attached to your cloud instance.
-
-Navigate to your GEOS-Chem Classic run directory and type:
-
-.. code-block:: console
-
-    $ ./download data.py log.dryrun amazon
-
-This will start the data download process using the ``aws s3 cp``
-commands, which should execute much more quickly than if you were to
-download the data from another location. It will also produce a
-**log of unique data files**.
-
-.. note::
-
-   Downloading from the Amazon Data Portal will NOT incur any
-   egress charges.  This is because the data is covered under the
-   `AWS Open Data Sponsorship Program
-   <https://aws.amazon.com/opendata/?wwps-cards.sort-by=item.additionalFields.sortDate&wwps-cards.sort-order=desc>`_.
-
-.. _dry-run-download-rochester:
-
-The :file:`atmos.earth.rochester.edu` site (aka Rochester)
-----------------------------------------------------------
-
-The U. Rochester site (which is maintained by Lee Murray's (GitHub:
-:literal:`@ltmurray`) research there) contains the GCAP 2.0 met field
-data.  This met field data is useful if you wish to perform
-simulations stretching back into the preindustrial period, or running
-into the future. 
-
-To download data from the Rochester site, type:
-
-.. code-block:: console
-
-    $ ./download data.py log.dryrun rochester
-
-.. _dry-run-download-data:
+You can :ref:`download input data <data>` from any of the portals
+listed below.
+
+.. list-table:: GEOS-Chem data portals and access methods
+   :header-rows: 1
+
+   * - Portal
+     - S3 Explorer
+     - AWS CLI
+     - HTTP
+     - Bashdatacatalog
+     - Globus
+   * - :ref:`GEOS-Chem Input Data <gcid-data>` |br|
+       (The main source of GEOS-Chem input data)
+     - Yes
+     - Yes
+     - Yes
+     - Yes
+     - Yes
+   * - :ref:`gcid-special-portals-nested`
+     - Yes
+     - Yes
+     - Yes
+     - No
+     - No
+   * - :ref:`gcid-special-portals-gcap2`
+     - No
+     - No
+     - Yes
+     - No
+     - No
+
+.. _dry-run-download-py:
 
 ==============================================================
 Run the :file:`download_data.py` script on the dryrun log file
 ==============================================================
 
 Navigate to your GEOS-Chem run directory where you executed the dry-run
-and type:
+and type.
+
+.. code-block:: console
+
+   $ ./download_data.py log.dryrun PORTAL-NAME
+
+where:
+
+- :file:`download_data.py` is the dry-run data download program
+  (written in Python).  It is included in each :ref:`GEOS-Chem Classic
+  run directory <rundir>` that you create. |br|
+  |br|
+
+- :file:`log.dryrun` is the log file from your GEOS-Chem dry-run
+  simulation. |br|
+  |br|
+
+- :literal:`PORTAL-NAME` specifies the data portal that you wish
+  to download from.  Allowed values are:
+
+  .. list-table:: Allowed values for the ``PORTAL-NAME`` argument
+		  to ``download_data.py``
+     :header-rows: 1
+     :align: center
+
+     * - Value
+       - Downloads from portal
+       - With this command
+       - Via this method
+     * - geoschem+aws
+       - :ref:`GEOS-Chem Input Data <gcid-data>`
+       - :command:`aws s3 cp`
+       - AWS CLI
+     * - geoschem+http
+       - :ref:`GEOS-Chem Input Data <gcid-data>`
+       - :command:`wget`
+       - HTTP
+     * - nested+aws
+       - :ref:`gcid-special-portals-nested`
+       - :command:`aws s3 cp`
+       - AWS CLI
+     * - nested+http
+       - :ref:`gcid-special-portals-nested`
+       - :command:`wget`
+       - HTTP
+     * - rochester
+       - :ref:`GCAP 2.0 met data @ Rochester <gcid-special-portals-gcap2>`
+       - :command:`wget`
+       - HTTP
+
+For example, to download data from the :ref:`GEOS-Chem Input Data
+<gcid-data>` portal using the AWS CLI download (which is faster than
+HTTP download), use this command:
 
 .. code-block:: console
 
-   $ ./download_data.py log.dryrun washu
+   $ ./download_data.py log.dryrun geoschem+s3
+
+.. note::
 
-The :file:`download_data.py` Python program is included in the
-:ref:`GEOS-Chem run directory <rundir>` that you created. This Python
-program creates and executes a temporary bash script containing the
-appropriate :file:`wget` commands to download the data files. (We have
-found that this is the fastest method.)
+   You must have the `AWS CLI (command-line interface)
+   <https://aws.amazon.com/cli/>`_ software installed on your system
+   before in order to use the :literal:`geoschem+aws` or
+   :literal:`nested+aws` options in the table listed above.
 
-The :file:`download_data.py` program will also generate a **log of
+The :file:`download_data.py` program will generate a **log of
 unique data files** (i.e. with all duplicate listings removed), which
 looks similar to this:
 
 .. code-block:: text
 
-    !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-    !!! LIST OF (UNIQUE) FILES REQUIRED FOR THE SIMULATION
-    !!! Start Date       : 20160701 000000
-    !!! End Date         : 20160701 010000
-    !!! Simulation       : standard
-    !!! Meteorology      : GEOSFP
-    !!! Grid Resolution  : 4.0x5.0
-    !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-    ./GEOSChem.Restart.20160701_0000z.nc4 --> /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/GEOSCHEM_RESTARTS/v2018-11/initial_GEOSChem_rst.4x5_standard.nc
-    ./HEMCO_Config.rc
-    ./HEMCO_Diagn.rc
-    ./HEMCO_restart.201607010000.nc
-    ./HISTORY.rc
-    ./input.geos
-    /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/FJX_j2j.dat
-    /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/FJX_spec.dat
-    /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/dust.dat
-    /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/h2so4.dat
-    /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/jv_spec_mie.dat
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !!! LIST OF (UNIQUE) FILES REQUIRED FOR THE SIMULATION
+   !!! Start Date       : 20190701 000000
+   !!! End Date         : 20190701 010000
+   !!! Simulation       : fullchem
+   !!! Meteorology      : MERRA2
+   !!! Grid Resolution  : 4.0x5.0
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   ./HEMCO_Config.rc
+   ./HEMCO_Config.rc.gmao_metfields
+   ./HEMCO_Diagn.rc
+   ./HISTORY.rc
+   ./Restarts/GEOSChem.Restart.20190701_0000z.nc4 --> /home/ubuntu/ExtData/GEOSCHEM_RESTARTS/GC_14.5.0/GEOSChem.Restart.fullchem.20190701_0000z.nc4
+   ./Restarts/HEMCO_restart.201907010000.nc
+   ./geoschem_config.yml
+   /path/to/ExtData/CHEM_INPUTS/CLOUD_J/v2024-09/FJX_j2j.dat
+   /path/to/ExtData/CHEM_INPUTS/CLOUD_J/v2024-09/FJX_scat-aer.dat
+   /path/to/ExtData/CHEM_INPUTS/CLOUD_J/v2024-09/FJX_scat-cld.dat
+   /path/to/ExtData/CHEM_INPUTS/CLOUD_J/v2024-09/FJX_scat-ssa.dat
+   /path/to/ExtData/CHEM_INPUTS/CLOUD_J/v2024-09/FJX_spec.dat
+   /path/to/ExtData/CHEM_INPUTS/FastJ_201204/fastj.jv_atms_dat.nc
+   /path/to/ExtData/CHEM_INPUTS/Linoz_200910/Linoz_March2007.dat
+   /path/to/ExtData/CHEM_INPUTS/Olson_Land_Map_201203/Olson_2001_Drydep_Inputs.nc
+   /path/to/ExtData/CHEM_INPUTS/UCX_201403/NoonTime/Grid4x5/InitCFC_JN2O_01.dat
+
     ... etc ...
 
 This name of this "unique" log file will be the same as the log file
@@ -172,13 +199,13 @@ GEOS-Chem run directory:
 
 .. code-block:: console
 
-   $ ./download_data.py log.dryrun --skip-download
+   $ ./download_data.py log.dryrun skip-download
 
 or for short:
 
 .. code-block:: console
 
-  $ ./download_data.py log.dryrun --skip
+  $ ./download_data.py log.dryrun skip
 
 This can be useful if you already have the necessary data downloaded to
 your system but wish to create the log of unique files for documentation