From 09c8fad179e6557fa3c2592440e3119315b661eb Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 3 Jul 2024 15:37:02 -0400 Subject: [PATCH 01/44] GEOS-Chem submod update: Merge PR #2359 (Per-species KPP error tol.) This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: 4288f0d1d Merge PR #2359 (Set KPP dummy species to large ATOL value) This PR adds structural updates to allow per-species setting of the KPP absolute & relative tolerances. This now allows us to assign a large absolute tolerance (1e25) to KPP dummy species, which excludes them from the error norm computations. This results in a faster simulation at the cost of numerical noise. Signed-off-by: Bob Yantosca --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index dd859ee..4288f0d 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit dd859ee45494af71d29f0877f359ff571f697b67 +Subproject commit 4288f0d1d89d6d4c42f71bc0c90280812aa4cfd8 From 600ce53615fc98616c6e203de03169e563138938 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 8 Jul 2024 13:46:07 -0400 Subject: [PATCH 02/44] GEOS-Chem submod update: Merge hotfix from PR #2363 atop PR #2359 This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: e61a51064 Merge GCHP hotfix from PR #2363 on top of PR #2359 This PR implements a hotfix for an issue that had caused GCHP cloud benchmarks to fail. Signed-off-by: Bob Yantosca --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index 4288f0d..e61a510 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit 4288f0d1d89d6d4c42f71bc0c90280812aa4cfd8 +Subproject commit e61a51064a94246698d7a844239617b1b802ec8f From 6c039818406006936420614900595d948b51f9d7 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 16 Jul 2024 12:30:47 -0400 Subject: [PATCH 03/44] GEOS-Chem submod update: Merge PR #2315 (complexSOA bug fixes) This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: ef2ea60e7 Merge PR #2315 (Fix bugs in PDER, OCPISOA, and TotalOC) This PR fixes several minor bugs in the complex SOA scheme. Signed-off-by: Bob Yantosca --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index e61a510..ef2ea60 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit e61a51064a94246698d7a844239617b1b802ec8f +Subproject commit ef2ea60e7caab0784ba139f8e5083f2f77982a6c From 96e3b6b288c28f8a741c2531141ad11158e59867 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 24 Jul 2024 16:17:58 -0400 Subject: [PATCH 04/44] Hotfix: Point to dev/14.5.0 + 14.4.2 in src/GEOS-Chem This hotfix now updates the submodule hash so that it points to commit 0a172283 in src/GEOS-Chem. This is where the 14.4.2 release has been merged into the the dev/14.5.0 branch. Signed-off-by: Bob Yantosca --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index ef2ea60..0a17228 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit ef2ea60e7caab0784ba139f8e5083f2f77982a6c +Subproject commit 0a172283d089111e17fc45c0dd0a57da563b7bdc From 6f2224053cd83819c55b2f644f2abe1c5eae527c Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Fri, 26 Jul 2024 09:47:54 -0400 Subject: [PATCH 05/44] GEOS-Chem submod update: Merge PR #2398 (Uncomment cations for HETP) This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: e29a4c928 Merge PR #2398 (Pass non-zero Ca2, Mg, and K cations to HETP) PR #2398 uncomments setting Ca2+, K+, and Mg+ cation values passed to HETP. Previously these values were zero due to an issue in ISORROPIA. With the update to HETP we can enable these cations. Signed-off-by: Bob Yantosca --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index 0a17228..e29a4c9 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit 0a172283d089111e17fc45c0dd0a57da563b7bdc +Subproject commit e29a4c9289b01482f9d1c22528eac76b73023c43 From a6ad1c5b685c0aa3632a6dbb5b002e6927793bf8 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 1 Aug 2024 14:26:21 -0400 Subject: [PATCH 06/44] GEOS-Chem submod update: Merge PR #2352 (ALK4/R4N2 fixes from J. Brewer) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: 0a392d465 Merge PR #2352 (Fixes for ALK4 and R4N2 chemistry from J. Brewer) R4N2 was a common product of alkane, isoprene, and monoterpene oxidation and produced organonitrate SOA but we don’t want ALK4 to produce organonitrate SOA as discusses in #1625. A fix from Jared Brewer is included in this PR. Signed-off-by: Bob Yantosca --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index e29a4c9..0a392d4 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit e29a4c9289b01482f9d1c22528eac76b73023c43 +Subproject commit 0a392d465fd194135806f1a120c05697d60cf382 From 0c22a3a5ce10645cc302c36fd3e7315bc8dec9e9 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 5 Aug 2024 15:46:35 -0400 Subject: [PATCH 07/44] GEOS-Chem submod update: PR #2352 post-merge fix (rebuild KPP files) This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: acd335486 PR #2352 post-merge fix: Rebuild fullchem solver files This PR restores the updated KPP solver files for PR #2352 (ALK4 and R4N2 chemistry updates, by @JFBrewer). Signed-off-by: Bob Yantosca --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index 0a392d4..acd3354 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit 0a392d465fd194135806f1a120c05697d60cf382 +Subproject commit acd3354861ce7c7b1c2d34833361e57dc39f8ff9 From 8da455b7713a536a7ab1e518bff9ef927a8b6641 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 15 Aug 2024 11:58:33 -0400 Subject: [PATCH 08/44] GEOS-Chem submod update: PR #2425 post-merge fix (CHANGELOG.md update_ This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: 8f0a16767 PR #2425 post-merge fix: Move 14.4.3 entry to top of CHANGELOG.md This PR moves a CHANGELOG.md entry for 14.4.3 to its proper place. Signed-off-by: Bob Yantosca --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index 000205c..8f0a167 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit 000205c86ade5f906f17a628856d8620736111b9 +Subproject commit 8f0a1676789f001d8a1d888905a734cf88f0eb13 From edaa239ad070022c7fb887b753bd71669c21f5f4 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 20 Aug 2024 11:54:58 -0400 Subject: [PATCH 09/44] GEOS-Chem & HEMCO updates: Merge PR #2318, PR #284, PR #285 This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: 586260f10 PR #2318 post-merge fix: Use less drydep fields for the alldiags test f240c993f PR #2318 post-merge fix: Remove duplicate EmisHCOOH_Total entry 53f9b2e82 PR #2318 post-merge fix: Add missing species to geoschem_config.yml dd7ba9a9c Merge PR #2318 (Chemistry for RCOOH, ANs, PNs) and the geoschem/HEMCO repository: d0d5fca PR #285 post-merge fix: Update CHANGELOG.md 1c6356d Merge PR #285 (Add em. factors for ALK6, C4H6, EBZ, STYR, TMB) 253b0fc Merge HEMCO 3.9.3 back into the 3.10.0 development stream f2b6ae4 Merge PR #284 (Fix inconsistent pressure units in HEMCO standalone) These PRs implement new chemistry (from @ktravis213), emissions (from @kelvinhb), and a bug fix for the HEMCO standalone. Signed-off-by: Bob Yantosca --- src/GEOS-Chem | 2 +- src/HEMCO | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index 8f0a167..586260f 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit 8f0a1676789f001d8a1d888905a734cf88f0eb13 +Subproject commit 586260f101557396c49590931a5838a2374b4528 diff --git a/src/HEMCO b/src/HEMCO index 41605bd..d0d5fca 160000 --- a/src/HEMCO +++ b/src/HEMCO @@ -1 +1 @@ -Subproject commit 41605bda8a89d96f441cb8eb90f3d3c8b21f2b71 +Subproject commit d0d5fca8ceab6f59aa98d6e65952dcfc9f3aef6e From 153a355ee604a1325ed4845ad0b58081c4a24c0a Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 28 Aug 2024 11:06:39 -0400 Subject: [PATCH 10/44] GEOS-Chem submod update: Merge PR #2428 (vdiff) and PR #2144 (drydep) This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: 3073aff2e Merge PR #2428 (Fix mass non-conservation in VDIFF) c7332ed7a Merge PR #2144 (Restore drydep output in fullchem benchmarks) This PR does the following: 1. Adds the DryDep collection to all fullchem_benchmark runs 2. Implements a mass conservation fix in VDIFF PBL mixing by @nicholasbalasus. See issue #2409 for details/ Signed-off-by: Bob Yantosca --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index 586260f..3073aff 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit 586260f101557396c49590931a5838a2374b4528 +Subproject commit 3073aff2e63d1073f7e63acaa9dba293dbc0553a From 750151fa98667a33de9027c995c38eb4d763e6af Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 28 Aug 2024 17:40:28 -0400 Subject: [PATCH 11/44] geos-chem-shared-docs update: Update packages.yaml to GCC 12.2.0 Signed-off-by: Bob Yantosca --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 07725d7..2f6603f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ 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 +### Changed +- Updated `docs/source/geos-chem-shared-docs/spack/packages.yaml` to use GCC 12.2.0 compilers + ## [14.4.3] - 2024-08-13 ### Changed - Updated GEOS-Chem (science codebase) to 14.4.3 From e7efd491d99811c557256e0ff6ca19ce1f9204cd Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 29 Aug 2024 12:46:38 -0400 Subject: [PATCH 12/44] Update env files from GNU 10.2.0 to 12.2.0 + related updates docs/source/geos-chem-shared-docs - Fixed broken links in supplemental-guides/spack-guide.rst docs/source/getting-started/login-env-files-gnu.rst - Changed label from env-files-gnu10 to env-files-gnu - Added tip box to build software with Spack if necessary docs/source/getting-started/login-env-files-intel.rst - Changed label from _env-files-intel19 to _env-files-intel - Added tip box to build software with Spack if necessary docs/source/getting-started/login-env-compilers.rst docs/source/getting-started/login-env-parallel.rst - Updated references accordingly docs/source/getting-started/login-env.rst - Updated references accordingly - Added tip box to build software with Spack if necessary Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- .../getting-started/login-env-compilers.rst | 4 +- .../getting-started/login-env-files-gnu.rst | 84 +++++++++++++------ .../getting-started/login-env-files-intel.rst | 41 ++++++--- .../getting-started/login-env-files.rst | 2 +- .../getting-started/login-env-parallel.rst | 4 +- docs/source/getting-started/login-env.rst | 7 ++ 7 files changed, 102 insertions(+), 42 deletions(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index ce3c86a..47cb22b 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit ce3c86accdcd73d3c3a46e41be1fcc09775200dd +Subproject commit 47cb22bf9a93dd5c54a597062b41ef4ab1db4ce9 diff --git a/docs/source/getting-started/login-env-compilers.rst b/docs/source/getting-started/login-env-compilers.rst index 6885a8e..e4f6c58 100644 --- a/docs/source/getting-started/login-env-compilers.rst +++ b/docs/source/getting-started/login-env-compilers.rst @@ -4,8 +4,8 @@ Set environment variables for compilers ####################################### -The sample :ref:`GNU ` and :ref:`Intel -` environment files set the **environment +The sample :ref:`GNU ` and :ref:`Intel +` environment files set the **environment variables** listed below in order to select the desired C, C++, and Fortran compilers: diff --git a/docs/source/getting-started/login-env-files-gnu.rst b/docs/source/getting-started/login-env-files-gnu.rst index e8c37bb..05e4e24 100644 --- a/docs/source/getting-started/login-env-files-gnu.rst +++ b/docs/source/getting-started/login-env-files-gnu.rst @@ -1,36 +1,64 @@ -.. _env-files-gnu10: +.. _env-files-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 (based on an enviroment file for the Harvard Cannon computer cluster). This file will load software -libraries built with the GNU 10.2.0 compilers. +libraries built with the `GNU 12.2.0 compilers +`_. + +.. 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:`~/gcclassic.gnu10.env`. +computer system) to a file named :file:`~/gcclassic.gnu12.env`. .. code-block:: bash + ############################################################################### + # + # Environment file for GCClassic + 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 GEOS-Chem + # (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 _HOME variables for each loaded module + # (NOTE: Lmod will define _HOME variables for each loaded module) #============================================================================== # Make all files world-readable by default @@ -55,13 +83,13 @@ computer system) to a file named :file:`~/gcclassic.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 @@ -75,20 +103,28 @@ computer system) to a file named :file:`~/gcclassic.gnu10.env`. #============================================================================== # Print information #============================================================================== - module list - -.. 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. + module list -Then you can activate these seetings from the command line by typing: + 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]}" + +To activate the settings contained in the environment file, type: .. code-block:: console - $ . ~/gcclassic.gnu10.env + $ . ~/gcclassic.gnu12.env You may also place the above command within your :ref:`GEOS-Chem run script `, which will be discussed in a subsequent chapter. diff --git a/docs/source/getting-started/login-env-files-intel.rst b/docs/source/getting-started/login-env-files-intel.rst index 4b0494f..d2f3c49 100644 --- a/docs/source/getting-started/login-env-files-intel.rst +++ b/docs/source/getting-started/login-env-files-intel.rst @@ -1,4 +1,4 @@ -.. _env-files-intel19: +.. _env-files-intel: ################################################ Sample environment file for Intel 2023 compilers @@ -8,14 +8,24 @@ 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 Intel 2023 compilers. +.. 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. + Add the code below (with the appropriate modifications for your system) into a file named :file:`~/gcclassic.intel23.env`. .. code-block:: bash - #============================================================================== - # Load software packages (EDIT AS NEEDED) - #============================================================================== + ############################################################################### + # + # Environment file for GCClassic + Intel 2023 compilers + # + ############################################################################### # Unload all modules first module purge @@ -77,14 +87,21 @@ system) into a file named :file:`~/gcclassic.intel23.env`. module list -.. 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 settings from the command line by typing: + 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]}" + +To activate the settings contained in the environment file, type: .. code-block:: console diff --git a/docs/source/getting-started/login-env-files.rst b/docs/source/getting-started/login-env-files.rst index 3e76c85..3ef2e27 100644 --- a/docs/source/getting-started/login-env-files.rst +++ b/docs/source/getting-started/login-env-files.rst @@ -30,7 +30,7 @@ command such as: Keep a separate environment file for each combination of modules that you will use. Example environment files - for :ref:`GNU ` and :ref:`Intel ` + for :ref:`GNU ` and :ref:`Intel ` compilers and related software are provided in the following sections. For general information about how libraries are loaded, see diff --git a/docs/source/getting-started/login-env-parallel.rst b/docs/source/getting-started/login-env-parallel.rst index bd7bfaf..b2a9fba 100644 --- a/docs/source/getting-started/login-env-parallel.rst +++ b/docs/source/getting-started/login-env-parallel.rst @@ -24,8 +24,8 @@ shared-memory (aka serial) parallelization. `_ for more computationally-intensive simulations. -In the the sample environment files for :ref:`GNU ` and -:ref:`Intel `, we define the following **environment +In the the sample environment files for :ref:`GNU ` and +:ref:`Intel `, we define the following **environment varaiables** for OpenMP parallelization: .. option:: OMP_NUM_THREADS diff --git a/docs/source/getting-started/login-env.rst b/docs/source/getting-started/login-env.rst index 156345c..c463c78 100644 --- a/docs/source/getting-started/login-env.rst +++ b/docs/source/getting-started/login-env.rst @@ -12,6 +12,13 @@ Customize your login environment Machine Images (AMIs) all of the required software libraries will be automatically loaded. +.. tip:: + + If your computer system lacks the required software packages for + :program:`GEOS-Chem Classic`, you can build them with the Spack + package manager. For detailed instructions, please see our + :ref:`spackguide` supplemental guide. + Each time you log in to your computer system, you'll need to load the :ref:`software libraries ` needed by GEOS-Chem into your environment. You can do this with a script known From 03ae9d847054163eb3635c630c67c4079a1fc713 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 29 Aug 2024 13:59:53 -0400 Subject: [PATCH 13/44] geos-chem-shared-docs update: Use gcc@12.2.0 in load-libraries-guide.rst This commit informs the GCClassic superproject about the following commits pushed to the geos-chem-shared-docs submodule: a68981b Update gcc@10.2.0 -> gcc@12.2.0 in load-libraries-guide.rst This updates the GCC compiler version from 10.2.0 to 12.2.0 in the various documentation pages. Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index 47cb22b..a68981b 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit 47cb22bf9a93dd5c54a597062b41ef4ab1db4ce9 +Subproject commit a68981bec91028c8165f220fef683650cb79afe4 From 930deb9fc19e56e8ff9aee12f3f6bb2949437ffe Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 29 Aug 2024 14:25:23 -0400 Subject: [PATCH 14/44] GEOS-Chem submod update: Merge PR #2436, #2439, #2371 (PPN Phot etc.) This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: 602b660c1 PR #2436 post-merge update: Fix typo in ExtData.rc.fullchem d34c567a4 Merge PR #2436 (Update GFED4 climatology for 2010-2023) d4c47babf Merge PR #2439 (Update run scripts and env files for Discover) 43d0e9083 Merge PR #2371 (Adding PPN photolysis) This implements photolysis for the PPN species. Also, two other no-diff-to-benchmark updates have been added, namely updating run scripts for NASA discover and updating the GFED4 climatology file. Signed-off-by: Bob Yantosca --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index 3073aff..602b660 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit 3073aff2e63d1073f7e63acaa9dba293dbc0553a +Subproject commit 602b660c13182a43b5620fad0eaf402d7a18696a From 49908a8ada48a6ef23ca0f56bf4e7859a83a0bff Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 3 Sep 2024 13:19:02 -0400 Subject: [PATCH 15/44] GEOS-Chem submod update: Merge PR #2424, PR #2426, Cloud-J PR #24 This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: 1951ea96e Declare PPN as photolyzing in the species database 40a078514 Merge PR #2424 (Support for Cloud-J_v8.0.0) 647c9f579 Merge PR #2426 (Store aerosol-specific optics files in new directory) and to the geoschem/Cloud-J repository: 291a161 Update Cloud-J standalone settings to use UV absorption by H2O by default 6a027b1 Merge pull request #24 from geoschem/feature/cloudj_v8 These PRs move aerosol optics configuration files to a separate folder (out of the CHEM_INPUTS/FAST-JX folder structure) and update Cloud-J to version 8.0.0. Signed-off-by: Bob Yantosca --- src/Cloud-J | 2 +- src/GEOS-Chem | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Cloud-J b/src/Cloud-J index d20050f..291a161 160000 --- a/src/Cloud-J +++ b/src/Cloud-J @@ -1 +1 @@ -Subproject commit d20050f1ef9e3895d58f3041efd2da59ce1ed421 +Subproject commit 291a1612cb30f09fd56e761bdd27a095ab1d9815 diff --git a/src/GEOS-Chem b/src/GEOS-Chem index 602b660..1951ea9 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit 602b660c13182a43b5620fad0eaf402d7a18696a +Subproject commit 1951ea96ef14e01c08a1df7da254109050e78c79 From 25bb8331349054b55747e49d03f6cc5fe9496c57 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 4 Sep 2024 10:09:12 -0400 Subject: [PATCH 16/44] Update jinja2 to 3.1.4 in docs/requirements.txt docs/requirements.txt - Use jinja 3.1.4 as there is a dependabot security warning for the previous version 3.1.3. CHANGELOG.md - Updated accordingly Signed-off-by: Bob Yantosca --- CHANGELOG.md | 3 +++ docs/requirements.txt | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2f6603f..de3ddff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), ### Changed - Updated `docs/source/geos-chem-shared-docs/spack/packages.yaml` to use GCC 12.2.0 compilers +### Fixed +- Now use `jinja2==3.1.4` in `docs/requirements.txt` (fixes a security issue) + ## [14.4.3] - 2024-08-13 ### Changed - Updated GEOS-Chem (science codebase) to 14.4.3 diff --git a/docs/requirements.txt b/docs/requirements.txt index 60b3987..71e269d 100644 --- 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 From 615cf45885ca6881791cc6d4f286c4d10d721da0 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 5 Sep 2024 13:48:32 -0400 Subject: [PATCH 17/44] Cloud-J submod update: Merge PR #26 (Define max J-values rather than exact) This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: 6bf4a36 Merge pull request #26 from geoschem/feature/define_max_rather_than_exact_num_jvalues This PR fixes an issue where Cloud-J will stop reading entries from FJX_j2j.dat before the "9999" end-of-file marker. Signed-off-by: Bob Yantosca --- src/Cloud-J | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Cloud-J b/src/Cloud-J index 291a161..6bf4a36 160000 --- a/src/Cloud-J +++ b/src/Cloud-J @@ -1 +1 @@ -Subproject commit 291a1612cb30f09fd56e761bdd27a095ab1d9815 +Subproject commit 6bf4a36d11039783c0b29befc48e93cdff7f6ecb From b577abe96cda9fe5652d4ad21c72b4ea09c7771e Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Fri, 6 Sep 2024 09:56:16 -0400 Subject: [PATCH 18/44] GEOS-Chem submod update: Merge PR #2452 (Reorder photo rxns for PNs, ANs) This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: a5fba9c88 Merge PR #2452 (Reorder photo rxns for PNs and ANs) This PR reorders the photo rxns of the PN and AN species added by @ktravis213 in PR #2318, so that they now follow PPN in the FJX_j2j.dat configuration file for Cloud-J. Signed-off-by: Bob Yantosca --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index 1951ea9..a5fba9c 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit 1951ea96ef14e01c08a1df7da254109050e78c79 +Subproject commit a5fba9c88ad279095026be17c31a40bb84802eda From 5e00d7e08a3cb88cf88b1e43e7de6d08094262b9 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Fri, 13 Sep 2024 10:04:44 -0400 Subject: [PATCH 19/44] GEOS-Chem update: Merge PR #2457 (Update Is_Photolysis tags) This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: cd0366015 Merge PR #2457 (Update Is_Photolysis tags in species_database.yml) This PR ensures that photolyzing species (as listed in the KPP fullchem.eqn and FJX_j2j.dat files) have "Is_Photolysis.true" tags in the species_database.yml file. Non-photolyzing species have had these tags removed. Also the JValues collection in the GCHP HISTORY.rc.fullchem file has been updated. Signed-off-by: Bob Yantosca --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index a5fba9c..cd03660 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit a5fba9c88ad279095026be17c31a40bb84802eda +Subproject commit cd03660155e86b8cea3681c7a9554e5e783511d6 From 0e075b75204ca49009225950c3fc69e6b5ff681f Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 16 Sep 2024 16:19:55 -0400 Subject: [PATCH 20/44] GEOS-Chem & HEMCO updates: Merge PR #2462, PR #2430, PR #287 This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: c0aeff427 Merge PR #2462 (Bug fix: ALK6 in HEMCO_Config.rc should be ALK7) 5c31c3470 Merge PR #2430 (Updated Y. Wang soil NOx scheme as an option) and the geos-chem/HEMCO repository c6a9d46 Merge PR #287 (Updated Y. Wang soil NOx scheme as an option) This PR does the following: 1. Implements the U. Iowa soil NOx scheme as an option. This is currently switched off by default. 2. Adds a bug fix in HEMCO configuration files: ALK6 should be called ALK7. Signed-off-by: Bob Yantosca --- src/GEOS-Chem | 2 +- src/HEMCO | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index cd03660..c0aeff4 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit cd03660155e86b8cea3681c7a9554e5e783511d6 +Subproject commit c0aeff427c45a25bc85fe18b5baf2a489dfac863 diff --git a/src/HEMCO b/src/HEMCO index d0d5fca..c6a9d46 160000 --- a/src/HEMCO +++ b/src/HEMCO @@ -1 +1 @@ -Subproject commit d0d5fca8ceab6f59aa98d6e65952dcfc9f3aef6e +Subproject commit c6a9d4668ee54af64f785f6c1113a2bc659efc70 From af1ced6d43d0d48a81dd4b19829af47ef3da30c1 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Thu, 19 Sep 2024 16:59:48 -0400 Subject: [PATCH 21/44] GEOS-Chem submodupdate: Merge PR #2464 (remove zero J-value diagnostics) Signed-off-by: Melissa Sulprizio --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index c0aeff4..dd8cce6 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit c0aeff427c45a25bc85fe18b5baf2a489dfac863 +Subproject commit dd8cce62da7fbb77fd535e9df7207fe5bf883114 From 61606327cd5974f0a51353ea3c7d22620c6a00c7 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Fri, 20 Sep 2024 17:00:52 -0400 Subject: [PATCH 22/44] GEOS-Chem submod update: Merge PR #1467 (Fix dry mass fraction of seasalt in aerosol thermodynamics) Signed-off-by: Melissa Sulprizio --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index dd8cce6..875a159 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit dd8cce62da7fbb77fd535e9df7207fe5bf883114 +Subproject commit 875a1593f065a345d05b2243ed2c1150ff68d1d2 From 5e45d73f6918d049f369a5f05bbca7d4482a9969 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Tue, 24 Sep 2024 12:37:54 -0400 Subject: [PATCH 23/44] Bugfix: Restore stale workflow functionality The stale workflows are currently failing with the error: Invalid workflow file: .github/workflows/stale.yml#L26 The workflow is not valid. .github/workflows/stale.yml (Line: 26, Col: 11): A sequence was not expected To fix this, the list of exempt-issues-labels in .github/workflows/stale.yml must be a comma separated list. A single quote is placed around the list to allow for use of colons in label names. Signed-off-by: Melissa Sulprizio --- .github/workflows/stale.yml | 2 +- CHANGELOG.md | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index c5b8f3e..4635a44 100644 --- 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/CHANGELOG.md b/CHANGELOG.md index 07725d7..5575ae0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ 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 +### Fixed +- Fixed formatting error in `.github/workflows/stale.yml` that caused the Mark Stale Issues action not to run + ## [14.4.3] - 2024-08-13 ### Changed - Updated GEOS-Chem (science codebase) to 14.4.3 From bb056b30d1f7ef3e28d680f7470b9e288b6cfedf Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Fri, 27 Sep 2024 08:44:23 -0400 Subject: [PATCH 24/44] GEOS-Chem submod update: Merge PR #2477 (Fix for double counting CH4 ag burning emissions) Signed-off-by: Melissa Sulprizio --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index 875a159..580c4e0 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit 875a1593f065a345d05b2243ed2c1150ff68d1d2 +Subproject commit 580c4e095b4fe3001e4224f431fa3525a668f520 From dfd1f6f6d5e22fe0ccd493ce6f9d95dc4539037a Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Fri, 27 Sep 2024 13:42:32 -0400 Subject: [PATCH 25/44] GEOS-Chem submodule update: Merge PR #2473 (seasonality of CH4 reservoir emissions) Signed-off-by: Melissa Sulprizio --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index 580c4e0..4f11ef0 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit 580c4e095b4fe3001e4224f431fa3525a668f520 +Subproject commit 4f11ef074c0cafae977ff17637985502e3620354 From 347686f48dd72b5f80feede3ab8e29b11e0a6620 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Fri, 27 Sep 2024 14:08:06 -0400 Subject: [PATCH 26/44] GEOS-Chem and HEMCO submodule updates: Add fixes for stale issue Github workflow Signed-off-by: Melissa Sulprizio --- src/GEOS-Chem | 2 +- src/HEMCO | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index 4f11ef0..7ffdb5b 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit 4f11ef074c0cafae977ff17637985502e3620354 +Subproject commit 7ffdb5b64f2ab2a2cdb6030addbeb0fae6b61104 diff --git a/src/HEMCO b/src/HEMCO index c6a9d46..a3d0c9a 160000 --- a/src/HEMCO +++ b/src/HEMCO @@ -1 +1 @@ -Subproject commit c6a9d4668ee54af64f785f6c1113a2bc659efc70 +Subproject commit a3d0c9a280672ac1c40e3f322651f23b8196fa4c From 3daf9fceadd58818867f4a8753ac41488d1a250c Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 30 Sep 2024 12:15:04 -0400 Subject: [PATCH 27/44] Moved config file doc to geos-chem-shared-docs docs/source/gcclassic-user-guide/geoschem-config.rst docs/source/gcclassic-user-guide/hemco-config.rst docs/source/gcclassic-user-guide/hemco-diagn.rst docs/source/gcclassic-user-guide/phot-chem.rst docs/source/gcclassic-user-guide/spec-db.rst - Moved to geos-chem-shared-docs/doc docs/source/gcclassic-user-guide/config-overview.rst - Now points to relocated files docs/source/geos-chem-shared-docs - Submodule update to CHANGELOG.md - Updated accordingly --- CHANGELOG.md | 2 + .../gcclassic-user-guide/config-overview.rst | 10 +- .../gcclassic-user-guide/geoschem-config.rst | 1797 ----------------- .../gcclassic-user-guide/hemco-config.rst | 225 --- .../gcclassic-user-guide/hemco-diagn.rst | 45 - .../source/gcclassic-user-guide/phot-chem.rst | 100 - docs/source/gcclassic-user-guide/spec-db.rst | 85 - docs/source/geos-chem-shared-docs | 2 +- 8 files changed, 8 insertions(+), 2258 deletions(-) delete mode 100644 docs/source/gcclassic-user-guide/geoschem-config.rst delete mode 100644 docs/source/gcclassic-user-guide/hemco-config.rst delete mode 100644 docs/source/gcclassic-user-guide/hemco-diagn.rst delete mode 100644 docs/source/gcclassic-user-guide/phot-chem.rst delete mode 100644 docs/source/gcclassic-user-guide/spec-db.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index de3ddff..476753b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), ## [Unreleased] - TBD ### Changed - 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 - Now use `jinja2==3.1.4` in `docs/requirements.txt` (fixes a security issue) diff --git a/docs/source/gcclassic-user-guide/config-overview.rst b/docs/source/gcclassic-user-guide/config-overview.rst index 1f4d7e7..320b29c 100644 --- 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/geoschem-config.rst b/docs/source/gcclassic-user-guide/geoschem-config.rst deleted file mode 100644 index 2e3d585..0000000 --- a/docs/source/gcclassic-user-guide/geoschem-config.rst +++ /dev/null @@ -1,1797 +0,0 @@ -.. _cfg-gc-yml: - -################### -geoschem_config.yml -################### - -Starting with GEOS-Chem 14.0.0, the :file:`input.geos` configuration -file (plain text) has been replaced with by the -:file:`geoschem_config.yml` file. This file is in `YAML -`_ format, which is a text-based markup syntax used -for representing dictionary-like data structures. - -.. note:: - - The :file:`geoschem_config.yml` file contains several sections. Only - the sections relevant to a given type of simulation are present. - For example, :option:`fullchem` simulation options (such as aerosol - settings and photolysis settings) are omitted from the - :file:`geoschem_config.yml` file for the :option:`CH4` simulation. - -.. _gc-yml-simulation: - -=================== -Simulation settings -=================== - -.. code-block:: yaml - - #============================================================================ - # Simulation settings - #============================================================================ - simulation: - name: fullchem - start_date: [20190701, 000000] - end_date: [20190801, 000000] - root_data_dir: /path/to/ExtData - met_field: MERRA2 - species_database_file: ./species_database.yml - species_metadata_output_file: OutputDir/geoschem_species_metadata.yml - verbose: - activate: false - on_cores: root # Allowed values: root all - use_gcclassic_timers: false - -The :literal:`simulation` section contains general simulation options: - -.. option:: name - - Specifies the type of GEOS-Chem simulation. Accepted - values are - - .. option:: fullchem - - Full-chemistry simulation. - - .. option:: aerosol - - `Aerosol-only simulation - `_. - - .. option:: carbon - - Coupled carbon gases simulation (CH4-CO-CO2-OCS), implemented as - a KPP mechanism (cf :cite:t:`Bukosa_et_al._2023`). - - You must :ref:`configure your build ` with - :literal:`-DMECH=carbon` in order to use this simulation. - - .. option:: CH4 - - `Methane simulation `_. - - This simulation will eventually be superseded by the - :option:`carbon` simulation. - - .. option:: CO2 - - `Carbon dioxide simulation `_. - - This simulation will eventually be superseded by the - :option:`carbon` simulation. - - .. option:: Hg - - `Mercury simulation `_. - - You must :ref:`configure your build ` with - :literal:`-DMECH=Hg` in order to use this simulation. - - .. option:: POPs - - `Persistent organic pollutants (aka POPs) simulation - `_. - - .. attention:: - - The POPs simulation is currently stale. We look to members - of the GEOS-Chem user community take the lead on updating - this simulation. - - .. option:: tagCH4 - - `Methane simulation - `_ with species - tagged by geographic region or other criteria. - - This simulation will eventually be superseded by the - :option:`carbon` simulation. - - .. option:: tagCO - - Carbon dioxide simulation, with species - tagged by geographic region and other criteria. - - This simulation will eventually be superseded by the - :option:`carbon` simulation. - - .. option:: tagO3 - - `Ozone simulation - `_ (using - specified production and loss rates), - with species tagged by geographical region. - - .. option:: TransportTracers - - `Transport Tracers simulation - `_, with - both radionuclide and passive_species. Useful for evaluating - model transport. - - .. option:: metals - - Trace metals simulation - -.. option:: start_date - - Specifies the starting date and time of the simulation in list - notation :literal:`[YYYYMMDD, hhmmss]`. - -.. option:: end_date - - Specifies the ending date and time of the simulation in list - notation :literal:`[YYYYMMDD, hhmmss]`. - -.. option:: root_data_dir - - Path to the root data directory. All of the data that GEOS-Chem - Classic reads must be located in subfolders of this directory. - -.. option:: met_field - - Name of the meteorology product that will be used to drive - GEOS-Chem Classic. Accepted values are: - - .. option:: MERRA2 - - The `MERRA-2 `_ meteorology - product from NASA/GMAO. MERRA-2 is a stable reanalysis product, - and extends from approximately 1980 to present. - **(Recommended option)** - - .. option:: GEOS-FP - - The `GEOS-FP `_ meteorology - product from NASA/GMAO. GEOS-FP is an operational data product - and, unlike MERRA-2, periodically receives science updates. - - .. option:: GCAP2 - - The GCAP-2 meteorology product, archived from the GISS-2 GCM. - GCAP-2 has hundreds of years of data available, making it useful - for simulations of historical climate. - -.. option:: species_database_file - - Path to the :ref:`GEOS-Chem Species Database ` file. This - is stored in the run directory file :file:`./species_database.yml`. - You should not have to edit this setting. - -.. option:: species_metadata_output_file - - Path to the :file:`geoschem-species-metadata.yml` file. This file - contains echoback of information from :ref:`species_database.yml - `, but only for species that are defined in this - simulation (instead of all possible species). This facilitates - interfacing GEOS-Chem with external models such as CESM. - -.. option:: verbose: - - Menu controlling verbose printout. Starting with GEOS-Chem 14.2.0 - and HEMCO 3.7.0, most informational printouts are now deactivated - by default. You may choose to activate them (e.g. for debugging - and/or testing) with the options below: - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - printing extra informational printout to the screen and/or log - file. - - .. option:: on_cores: - - Specify on which computational cores informational printout - should be done. - - .. option:: root - - Print extra informational output only on the root core. Use this - setting for GEOS-Chem Classic. - - .. option:: all - - Print extra informational output on all cores. Consider - using this when using GEOS-Chem as GCHP, or in MPI-based - external models (NASA GEOS, CESM, etc.). - -.. option:: use_gcclassic_timers - - Activates (:literal:`true`) or deactivates (:literal:`false`) - the GEOS-Chem Classic timers. If activated, information about how - long each component of GEOS-Chem took to execute will be printed to - the screen and/or :ref:`GEOS-Chem log file - `. The same information will also be written - in JSON format to a file named :ref:`gcclassic_timers.json - `. - - You can set this option to :literal:`false` unless you are running - benchmark or timing simulations. - -.. _cfg-gc-yml-grid: - -============= -Grid settings -============= - -.. code-block:: YAML - - #============================================================================ - # Grid settings - #============================================================================ - grid: - resolution: 4.0x5.0 - number_of_levels: 72 - longitude: - range: [-180.0, 180.0] - center_at_180: true - latitude: - range: [-90.0, 90.0] - half_size_polar_boxes: true - nested_grid_simulation: - activate: true - buffer_zone_NSEW: [0, 0, 0, 0] - -The :literal:`grid` section contains settings that define the grid used -by GEOS-Chem Classic: - -.. option:: resolution - - Specifies the horizontal resolution of the grid. Accepted values are: - - .. option:: 4.0x5.0 - - The global :math:`4^{\circ}{\times}5^{\circ}` GEOS-Chem Classic - grid. - - .. option:: 2.0x2.5 - - The global :math:`2.0^{\circ}{\times}2.5^{\circ}` GEOS-Chem Classic - grid. - - .. option:: 0.5x0.625 - - The global :math:`0.5^{\circ}{\times}0.625^{\circ}` GEOS-Chem Classic - grid (:option:`MERRA2` only). Can be used for global or nested - simulations. - - .. option:: 0.5x0.625 - - The global :math:`0.25^{\circ}{\times}0.3125^{\circ}` GEOS-Chem - Classic grid (:option:`GEOS-FP` and :option:`MERRA2`). Can be - used for global or nested simulations. - -.. option:: number_of_levels - - Number of vertical levels to use in the simulation. Accepted - values are: - - .. option:: 72 - - Use 72 vertical levels. This is the native vertical resolution - of :option:`MERRA2` and :option:`GEOS-FP`. - - .. option:: 47 - - Use 47 vertical levels (for :option:`MERRA2` and :option:`GEOS-FP`). - - .. option:: 40 - - Use 40 vertical levels (for :option:`GCAP2`). - -.. option:: longitude - - Settings that define the longitude dimension of the grid. There are - two sub-options: - - .. option:: range - - The minimum and maximum longitude values (grid box edges), - specified in list format. - - .. option:: center_at_180 - - If :literal:`true`, then westernmost grid boxes are centered - at :math:`-180^{\circ}` longitude (the International Date Line). - This is true for both :option:`MERRA2` and :option:`GEOS-FP`. - - If :literal:`false`, then the westernmost grid boxes have their - westernmost edges at :math:`-180^{\circ}` longitude. This is - true for the :option:`GCAP2` grid. - -.. option:: latitude - - Settings to define the latitude dimension of the grid. There are - two sub-options: - - .. option:: range - - The minimum and maximum latitude values (grid box edges), - specified in list format. - - .. option:: use_halfpolar_boxes - - If :literal:`true`, then the northernmost and southernmost grid - boxes will be :math:`\frac{1}{2}` the extent of other grid boxes. - This is true for both :option:`MERRA2` and :option:`GEOS-FP`. - - If :literal:`false`, then all grid boxes will have the same extent - in latitude. This is true for the :option:`GCAP2` grid. - -.. option:: nested_grid_simulation - - Settings for nested-grid simulations. There are two sub-options: - - .. option:: activate - - If :literal:`true`, this indicates that the simulation will use a - sub-window of the horizontal grid. - - If :literal:`false`, this indicates that the simulation will use - the entire global grid extent. - - .. option:: buffer_zone_NSEW - - Specifies the nested grid latitude offsets (# of grid boxes) in list - format :literal:`[N-offset, S-offset, E-offset, W-offset]`. These - offsets are used to define an inner window region in which - transport is actually done (aka the "transport window"). This - "transport window" is always smaller than the actual size of the - nested grid region in order to properly account for the boundary - conditions. - - - For global simulations, use: :literal:`[0, 0, 0, 0]`. - - For nested-grid simulations, we recommend using: :literal:`[3, 3, 3, 3]`. - -.. _cfg-gc-yml-timesteps: - -================== -Timesteps settings -================== - -.. code-block:: YAML - - #============================================================================ - # Timesteps settings - #============================================================================ - timesteps: - transport_timestep_in_s: 600 - chemistry_timestep_in_s: 1200 - radiation_timestep_in_s: 10800 - -The :literal:`timesteps` section specifies the frequency at which -various GEOS-Chem operations occur: - -.. option:: transport_timestep_in_s - - Specifies the "heartbeat" timestep of GEOS-Chem.. This is - the frequency at which transport, cloud convection, PBL mixing, and - wet deposition will be done. - - - Recommended value for global simulations: :literal:`600` - - Recommended value for nested simluations: :literal:`300` or smaller - -.. option:: chemistry_timestep_in_s - - Specifies the frequency at which chemistry and emissions will be - done. - - - Recommended value for global simulations :literal:`1200` - - Recommended value for nested simulations :literal:`600` or smaller - -.. option:: radiation_timestep_in_s - - Specifies the frequency at which the `RRTMG - `_ radiative - transfer model will be called (valid for :option:`fullchem` - simulations only). - -.. _cfg-gc-yml-operations: - -=================== -Operations settings -=================== - -This section of :file:`geoschem_config.yml` is included for all -simulations. However, some of the options listed below will be omitted for -simulations that do not require them. - -There are several sub-sections under :literal:`operations`: - -.. _cfg-gc-yml-operations-chemistry: - -Chemistry ----------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - chemistry: - activate: true - linear_chemistry_aloft: - activate: true - use_linoz_for_O3: true - active_strat_H2O: - activate: true - use_static_bnd_cond: true - gamma_HO2: 0.2 - autoreduce_solver: - activate: false - use_target_threshold: - activate: true - oh_tuning_factor: 0.00005 - no2_tuning_factor: 0.0001 - use_absolute_threshold: - scale_by_pressure: true - absolute_threshold: 100.0 - keep_halogens_active: false - append_in_internal_timestep: false - - # ... following sub-sections omitted ... - -The :literal:`operations:chemistry` section contains settings for chemistry: - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - chemistry in GEOS-Chem. - -.. option:: linear_chemistry_aloft - - Determines how linearized chemistry will be applied in the - stratosphere and/or mesosphere. (Only valid for :option:`fullchem` - simulations). - - There are two sub-options: - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - linearized stratospheric chemistry in the stratosphere and/or - mesosphere. - - .. option:: use_linoz_for_O3 - - If :literal:`true`, `Linoz stratospheric ozone chemistry - `_ - will be used. - - If :literal:`false`, Synoz (i.e. a synthetic flux of ozone across - the tropopause) will be used instead of Linoz. - -.. option:: active_strat_H2O - - Determines if water vapor as modeled by GEOS-Chem will be - allowed to influence humidity fields. (Only valid for - :option:`fullchem` simulations) - - There are two sub-options: - - .. option:: activate - - Allows (:literal:`true`) or disallows (:literal:`false` the H2O - species in GEOS-Chem to influence specific humidity and - relative humidity. - - .. option:: use_static_bnd_cond - - Allows (:literal:`true`) or diasallows (:literal:`false`) a - static boundary condition. - - **TODO** Clarify this - -.. option:: gamma_HO2 - - Specifies :math:`\gamma`, the uptake coefficient for :math:`HO_2` - heterogeneous chemistry. - - Recommended value: :literal:`0.2`. - -.. option:: autoreduce_solver - - Menu for controlling the adaptive mechanism auto-reduction feature, - which is available in `KPP - 3.0.0. `_ and later - versions. See :cite:t:`Lin_et_al._2023` for details. - - .. option:: activate - - If :literal:`true`, the mechanism will be integrated using the - Rosenbrock method with the adaptive auto-reduction feature. - - If :literal:`false`, the mechanism will be integrated using the - traditional Rosenbrock method. - - Default value: :literal:`false`. - - .. option:: use_target_threshold - - Contains options for defining :math:`\partial` (the partitioning - threshold between "fast" and "slow" species") by considering the - production and loss of key species (OH for daytime, NO2 for - nighttime). - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - using OH and NO2 to determine :math:`\partial`. - - Default value: :literal:`true`. - - .. option:: oh_tuning_factor - - Specifies :math:`{\alpha}_{OH}`, which is used to compute - :math:`\partial`. - - .. option:: no2 tuning factor - - Specifies :math:`{\alpha}_{NO2}`, which is used to compute - :math:`\partial`. - - .. option:: use_pressure_threshold - - Contains options for setting an absolute threshold - :math:`\partial` that may be weighted by pressure. - - .. option:: scale_by_pressure - - Activates (:literal:`true`) or deactivates (:literal:`false`) - using a pressure-dependent method to determine :math:`\partial`. - - .. option:: absolute_threshold - - The absolute partitioning threshold :math:`\partial`. - - If :option:`scale_by_pressure` is :literal:`true,` and - :option:`use_target_threshold:activate` is :literal:`false` , - the value for :math:`\partial` specified here will be scaled - by the ratio :math:`P / P_{sfc}`. where :math:`P` is the grid box - pressure and :math:`P_{sfc}` is the surface pressure for the - column. - - .. option:: keep_halogens_active - - If :literal:`true`, then all halogen species will be considered - "fast". This may be necessary in order to obtain realistic - results for ozone and other important species. - - If :literal:`false`, then halogen species will be determined as - "slow" or "fast" depending on the partitioning threshold - :math:`\partial`. - - Default value: :literal:`true` - - .. option:: append_in_internal_timestep - - If :literal:`true`, any "slow" species that later become "fast" - will be appended to the list of "fast" species. - - If :literal:`false`, any "slow" species that later become - "fast" will NOT be appended to the list of "fast" species. - - Default value: :literal:`false` - -.. _cfg-gc-yml-operations-convection: - -Convection ----------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - # .. preceding sub-sections omitted ... - - convection: - activate: true - - # ... following sub-sections omitted ... - -The :command:`operations:convection` section contains settings for -`cloud convection `_: - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - cloud convection in GEOS-Chem. - -.. _cfg-gc-yml-operations-drydep: - -Dry deposition --------------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - # .. preceding sub-sections omitted ... - - dry_deposition: - activate: true - CO2_effect: - activate: false - CO2_level: 600.0 - reference_CO2_level: 380.0 - diag_alt_above_sfc_in_m: 10 - - # ... following sub-sections omitted ... - -The :literal:`operations:dry_deposition` section contains settings that -for `dry deposition `_: - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - dry deposition. - -.. option:: CO2_effect - - This sub-section contains options for applying the - `simple parameterization for the CO2 effect on stomatal resistance - `_. - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) the CO2 - effect on stomatal resistance in dry deposition. - - Default value: :literal:`false`. - - .. option:: CO2_level - - Specifies the CO2 level (in ppb). - - .. option:: reference_CO2_level - - Specifies the reference CO2 level (in ppb). - -.. option:: diag_alt_above_sfc_in_m: - - Specifies the altitude above the surface (in m) to used with the - `ConcAboveSfc diagnostic collection `_. - -.. _cfg-gc-yml-operations-pblmix: - -PBL mixing ----------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - # .. preceding sub-sections omitted ... - - pbl_mixing: - activate: true - use_non_local_pbl: true - - # ... following sub-sections omitted ... - -The :literal:`operations:pbl_mixing` section contains settings that -for `planetary boundary layer (PBL) mixing -`_: - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - planetary boundary layer mixing in GEOS-Chem Classic. - -.. option:: use_non_local_pbl - - If :literal:`true`, then the `non-local PBL mixing scheme (VDIFF) - `_ will - be used. (Default option) - - If :literal:`false`, then the `full PBL mixing scheme (TURBDAY) - `_ will - be used. - -.. _cfg-gc-yml-operations-photolysis: - -Photolysis ----------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - # .. preceding sub-sections omitted ... - - photolysis: - activate: true - num_levs_with_cloud: 34 - input_directories: - fastjx_input_dir: /path/to/ExtData/CHEM_INPUTS/FAST_JX/v2024-05/ - cloudj_input_dir: /path/to/ExtData/CHEM_INPUTS/CLOUD_J/v2023-05/ - overhead_O3: - use_online_O3_from_model: true - use_column_O3_from_met: true - use_TOMS_SBUV_O3: false - photolyze_nitrate_aerosol: - activate: true - NITs_Jscale: 100.0 - NIT_Jscale: 100.0 - percent_channel_A_HONO: 66.667 - percent_channel_B_NO2: 33.333 - - # ... following sub-sections omitted ... - -The :literal:`operation:photolysis` section contains settings for photolysis. -This section only applies to fullchem, Hg, and aerosol-only simulations. - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - photolysis. - - .. attention:: - - You should always keep photolysis turned on in your - simulations. Disabling photolysis should only be done when - debugging. - -.. option:: num_levs_with_cloud - - Specifies the number of levels that can contain clouds, which is a - required input for the Cloud-J photolysis module. This value is - saved to the :code:`Input_Opt%NLevs_Phot_Cloud` field. - - .. attention:: - - The value of :option:`num_levs_with_cloud` will be set to the - proper value when you create a run directory. Its value depends - on the meteorology that is used to drive your GEOS-Chem - simulation. You should not change this value! - -.. option:: input_directories - - Specifies the location of directories containing photolysis - configuration files. - - .. option:: fastjx_input_dir - - Specifies the path to the legacy FAST_JX configuration files containing - information about species cross sections and quantum yields. - These are used to define several aerosol optical properties - even when FAST-JX is not used. - - Note that FAST-JX is off by default and Cloud-J is used - instead. You can use legacy FAST-JX instead of Cloud-J by - configuring with :literal:`-DFASTJX=y` during build. - - .. option:: cloudj_input_dir - - Specifies the path to the Cloud-J configuration files containing - information about species cross sections and quantum yields. - -.. option:: overhead_O3 - - This section contains settings that control which overhead ozone - sources are used for photolysis - - .. option:: use_online_O3_from_model - - Activates (:literal:`true`) or deactivates (:literal:`false`) using - online O3 from GEOS-Chem in the extinction calculations for photolysis. - - Recommended value: :literal:`true` - - .. option:: use_column_O3_from_met - - Activates (:literal:`true`) or deactivates (:literal:`false`) using - ozone columns (e.g. TO3) from the meteorology fields. - - Recommended value: :literal:`true`. - - .. option:: use_TOMS_SBUV_O3 - - Activates (:literal:`true`) or deactivates (:literal:`false`) using - ozone columns from the TOMS-SBUV archive will be used. - - Recommended value: :literal:`false`. - -.. option:: photolyze_nitrate_aerosol: - - This section contains settings that control options for nitrate - aerosol photolysis. - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - nitrate aerosol photolysis. - - Recommended value: :literal:`true`. - - .. option:: NITs_Jscale - - Scale factor (percent) for JNO3 that photolyzes NITs aerosol. - - .. option:: NIT_Jscale - - Scale factor (percent) for JHNO2 that photolyzes NIT aerosol. - - .. option:: percent_channel_A_HONO - - Fraction of JNITs/JNIT in channel A (HNO2) for NITs photolysis. - - .. option:: percent_channel_B_HO2 - - Fraction of JNITs/JNIT in channel B (NO2) for NITs photolysis. - -.. _cfg-gc-yml-rrtmg: - -RRTMG radiative transfer model ------------------------------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - # .. preceding sub-sections omitted ... - - rrtmg_rad_transfer_model: - activate: false - aod_wavelengths_in_nm: - - 550 - longwave_fluxes: false - shortwave_fluxes: false - clear_sky_flux: false - all_sky_flux: false - fixed_dyn_heating: false - seasonal_fdh: false - read_dyn_heating: false - co2_ppmv: 390.0 - - # .. following sub-sections omitted ... - -The :literal:`operations:rrtmg_rad_transfer_model` section contains -settings for the `RRTMG radiative transfer model -`_: - -This section only applies to :option:`fullchem` simultions. - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) the RRTMG - radiative transfer model. - - Default value: :literal:`false`. - -.. option:: aod_wavelengths_in_nm - - Specify wavelength(s) for the aerosol optical properties in nm - (in `YAML sequence format - `_) - Up to three wavelengths can be selected. The specified wavelengths - are used for the photolysis mechanism (either legacy FAST-JX or - Cloud-J) regardless of whether the RRTMG radiative transfer model is used. - -.. option:: longwave_fluxes - - Activates (:literal:`true`) or deactivates (:literal:`false`) - RRTMG longwave flux calculations. - - Default value: :literal:`false`. - -.. option:: shortwave_fluxes - - Activates (:literal:`true`) or deactivates (:literal:`false`) - RRTMG shortwave calculations. - - Default value: :literal:`false`. - -.. option:: clear_sky_flux - - Activates (:literal:`true`) or deactivates (:literal:`false`) - RRTMG clear-sky flux calculations. - - Default value: :literal:`false`. - -.. option:: all_sky_flux - - Activates (:literal:`true`) or deactivates (:literal:`false`) - RRTMG all-sky flux calculations. - - Default value: :literal:`false`. - -.. option:: fixed_dyn_heating - - Activates (:literal:`true`) or deactivates (:literal:`false`) - fixed dynamic heating (FDH) approximation as described by Forster *et al.* - [`1997 - `_]. - - Default value: :literal:`false`. - -.. option:: seasonal_fdh - - Activates (:literal:`true`) or deactivates (:literal:`false`) - seasonally-evolving fixed dynamic heating (SEFDH) approzimation as - described by Kiehl *et al.* [`1999 - `_]. - - .. attention:: - - This option has not been extensively tested, and is considered - experimental. - - Default value: :literal:`false`. - -.. option:: read_dyn_heating - - Activates (:literal:`true`) or deactivates (:literal:`false`) - reading previously-archived dynamical heating outputs from disk. - - Default value: :literal:`false`. - -.. option:: co2_ppmv - - Specify the value of CO2 [in parts per million by volume] to be - used in radiative forcing calculations. - - Default value: :literal:`390.0`. - - -.. _cfg-gc-yml-transport: - -Transport ---------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - # .. preceding sub-sections omitted ... - - transport: - gcclassic_tpcore: # GEOS-Chem Classic only - activate: true # GEOS-Chem Classic only - fill_negative_values: true # GEOS-Chem Classic only - iord_jord_kord: [3, 3, 7] # GEOS-Chem Classic only - transported_species: - - ACET - - ACTA - - AERI - # ... etc more transported species ... - - # .. following sub-sections omitted ... - -The :literal:`operations:transport` section contains -settings for `species transport -`_: - -.. option:: gcclassic_tpcore - - Contains options that control species transport in GEOS-Chem - Classic with the `TPCORE advection scheme - `_: - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) species - transport in GEOS-Chem Classic. - - Default value: :literal:`true`. - - .. option:: fill_negative_values - - If :literal:`true`, negative species concentrations will be - replaced with zeros. - - If :literal:`false`, no change will be made to species - concentrations. - - Default value: :literal:`true`. - - .. option:: iord_jord_kord - - Specifies advection options (in list format) for TPCORE in the - longitude, latitude, and vertical dimensions. The options are - listed below: - - #. 1st order upstream scheme (use for debugging only) - #. 2nd order van Leer (full monotonicity constraint) - #. Monotonic PPM - #. Semi-monotonic PPM (same as 3, but overshoots are allowed) - #. Positive-definite PPM - #. Un-constrained PPM (use when fields & winds are very smooth) - this option only when the fields and winds are very smooth. - #. Huynh/Van Leer/Lin full monotonicity constraint (KORD only) - - Default (and recommended) value: :literal:`[3, 3, 7]` - -.. option:: transported_species - - A list of species names (in `YAML sequence format - `_) - that will be transported by the TPCORE advection scheme. - -.. _cfg-gc-yml-wetdep: - -Wet deposition --------------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - # .. preceding sub-sections omitted ... - - wet_deposition: - activate: true - -The :literal:`operations:wet_deposition` section contains settings -for `wet deposition `_. - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - wet deposition in GEOS-Chem Classic. - -.. _gc-yml-aerosols: - -================= -Aerosols settings -================= - -This section of :file:`geoschem_config.yml` is included for -:option:`fullchem` and :option:`aerosol` simulations. - -There are several sub-sections under :literal:`aerosols`: - -.. _cfg-gc-yml-aerosol-carbon: - -Carbon aerosols ---------------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem aerosols - #============================================================================ - aerosols: - - carbon: - activate: true - brown_carbon: false - enhance_black_carbon_absorption: - activate: true - hydrophilic: 1.5 - hydrophobic: 1.0 - - # .. following sub-sections omitted ... - -The :literal:`aerosols:carbon` section contains settings for -`carbon aerosols -`_: - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) carbon - aerosols in GEOS-Chem. - - Default value: :literal:`true`. - -.. option:: brown_carbon - - Activates (:literal:`true`) or deactivates (:literal:`false`) brown - carbon aerosols in GEOS-Chem. - - Default value: :literal:`false`. - -.. option:: enhance_black_carbon_absorption - - Options for enhancing the absorption of black carbon aerosols - due to external coating. - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) black - carbon absorption enhancement. - - Default value: :literal:`true`. - - .. option:: hydrophilic - - Absorption enhancement factor for hydrophilic black carbon - aerosol (species name **BCPI**). - - Default value: :literal:`1.5` - - .. option:: hydrophobic - - Absorption enhancement factor for hydrophilic black carbon - aerosol (species name **BCPO**). - - Default value: :literal:`1.0` - -.. _cfg-gc-yml-aerosols-soa: - -Complex SOA ------------ -The :code:`aerosols:complex_SOA` section contains settings for -`the complex SOA scheme used in GEOS-Chem -`_. - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem aerosols - #============================================================================ - aerosols: - - # ... preceding sub-sections omitted ... - - complex_SOA: - activate: true - semivolatile_POA: false - - # ... following sub-sections omitted ... - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - complex SOA scheme. - - Default value: - - - :literal:`true` for the :option:`fullchem` benchmark simulation - - :literal:`false` for all other :option:`fullchem` simulations - -.. option:: semivolatile_POA - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - semi-volatile primary organic aerosol (POA) option. - - Default value: :literal:`false` - -.. _gc-yml-aerosols-dust: - -Mineral dust aerosols ---------------------- -The :literal:`aerosols:dust` section contains settings for -`mineral dust aerosols -`_. - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem aerosols - #============================================================================ - aerosols: - - # ... preceding sub-sections omitted ... - - dust: - activate: true - acid_uptake_on_dust: false - - # ... following sub-sections omitted ... - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) mineral - dust aerosols in GEOS-Chem. - - Default value: :literal:`true` - -.. option:: acid_uptake_on_dust - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - `acid uptake on dust option - `_, - which includes 12 additional species. - - Default value: :literal:`false` - -.. _cfg-gc-yml-aerosols-seasalt: - -Sea salt aerosols ------------------ -The :literal:`aerosols:sea_salt` section contains settings for `sea salt -aerosols -`_: - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem aerosols - #============================================================================ - aerosols: - - # ... preceding sub-sections omitted ... - - sea_salt: - activate: true - SALA_radius_bin_in_um: [0.01, 0.5] - SALC_radius_bin_in_um: [0.5, 8.0] - marine_organic_aerosols: false - - # ... following sub-sections omitted ... - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) sea salt - aerosols. - - Default value: :literal:`true` - -.. option:: SALA_radius_bin_in_um - - Specifies the upper and lower boundaries (in nm) for - accumulation-mode sea salt aerosol (aka **SALA**). - - Default value: :literal:`0.01 nm - 0.5 nm` - -.. option:: SALC_radius_bin_in_um - - Specifies the upper and lower boundaries (in nm) for - coarse-mode sea salt aerosol (aka **SALC**). - - Default value: :literal:`0.5 nm - 8.0 nm` - -.. option:: marine_organic_aerosols - - Activates (:literal:`true`) or deactivates (:literal:`false`) - `emission of marine primary organic aerosols - `_. - This option includes two extra species (**MOPO** and **MOPI**). - - Default value: :literal:`false` - -.. _cfg-gc-yml-aerosols-strat: - -Stratospheric aerosols ----------------------- -The :literal:`aerosols:sulfate` section contains settings for -stratopsheric aerosols. - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem aerosols - #============================================================================ - aerosols: - - # ... preceding sub-sections omitted ... - - stratosphere: - settle_strat_aerosol: true - polar_strat_clouds: - activate: true - het_chem: true - allow_homogeneous_NAT: false - NAT_supercooling_req_in_K: 3.0 - supersat_factor_req_for_ice_nucl: 1.2 - calc_strat_aod: true - - # ... following sub-sections omitted ... - - -.. option:: settle_strat_aerosol - - Activates (:literal:`true`) or deactivates (:literal:`false`) - gravitational settling of stratospheric solid particulate aerosols - (SPA, trapezoidal scheme) and stratospheric liquid aerosols (SLA, - corrected Stokes' Law). - - Default value: :literal:`true` - -.. option:: polar_strat_clouds - - Contains settings for how aerosols are handled in polar - stratospheric clouds (PSC): - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - formation of polar stratospheric clouds. - - Default value: :literal:`true` - - .. option:: het_chem - - Activates (:literal:`true`) or deactivates (:literal:`false`) - heterogeneous chemistry within polar stratospheric clouds. - - Default value: :literal:`true` - -.. option:: allow_homogeneous_NAT - - Activates (:literal:`true`) or deactivates (:literal:`false`) - heterogeneous formation of NAT from freezing of HNO3. - - Default value: :literal:`false` - -.. option:: NAT_supercooling_req_in_K - - Specifies the cooling (in K) required for homogeneous NAT nucleation. - - Default value: :literal:`3.0` - -.. option:: supersat_factor_req_for_ice_nucl - - Specifies the supersaturation factor required for ice nucleation. - - Recommended values: :literal:`1.2` for coarse grids; :literal:`1.5` for - fine grids. - -.. option:: calc_strat_aod - - Includes (:literal:`true`) or excludes (:literal:`false`) online - stratospheric aerosols in extinction calculations for photolysis. - - Default value: :literal:`true` - -.. _cfg-gc-yml-aerosols-sulfate: - -Sulfate aerosols ----------------- -The :literal:`aerosols:sulfate` section contains settings for `sulfate -aerosols `_: - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem aerosols - #============================================================================ - aerosols: - - # ... preceding sub-sections omitted ... - - sulfate: - activate: true - metal_cat_SO2_oxidation: true - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) sulfate aerosols. - - Default value: :literal:`true` - -.. option:: metal_cat_SO2_oxidation - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - `metal catalyzed oxidation of SO2 - `_. - - Default value: :literal:`true` - -.. _cfg-gc-yml-xdiag: - -================= -Extra diagnostics -================= - -The :literal:`extra_diagnostics` section contains settings for GEOS-Chem Classic -diagnostics that are not archived by :ref:`History -` or `HEMCO `_: - -.. _gc-yml-xdiag-obspack: - -Obspack diagnostic ------------------- - -The :literal:`extra_diagnostics:obspack` section contains settings for -the `Obspack diagnostic `_: - -.. code-block:: YAML - - #============================================================================ - # Settings for diagnostics (other than HISTORY and HEMCO) - #============================================================================ - extra_diagnostics: - - obspack: - activate: false - quiet_logfile_output: false - input_file: ./obspack_co2_1_OCO2MIP_2018-11-28.YYYYMMDD.nc - output_file: ./OutputDir/GEOSChem.ObsPack.YYYYMMDD_hhmmz.nc4 - output_species: - - CO - - 'NO' - - O3 - - # ... following sub-sections omitted ... - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) ObsPack - diagnostic output. - - Default value: :literal:`true` - -.. option:: quiet_logfile_output - - Deactivates (:literal:`true`) or activates (:literal:`false`) printing - informational output to :literal:`stdout` (i.e. the screen or log file). - - Default value: :literal:`false` - -.. option:: input_file - - Specifies the path to an ObsPack data file (in netCDF format). - -.. option:: output_file - - Specifies the path to the ObsPack diagnostic output file. This - will be a file that contains data at the same locations as - specified in :option:`input_file`. - -.. option:: output_species - - A list of GEOS-Chem species (as a YAML sequence) to archive to the - output file. - -.. _gc-yml-xdiag-plane: - -Planeflight diagnostic ------------------------ -The :literal:`extra_diagnostics:planeflight` section contains settings for -the `GEOS-Chem planeflight diagnostic -`_: - -.. code-block:: YAML - - #============================================================================ - # Settings for diagnostics (other than HISTORY and HEMCO) - #============================================================================ - extra_diagnostics: - - # ... preceding sub-sections omitted ... - - planeflight: - activate: false - flight_track_file: Planeflight.dat.YYYYMMDD - output_file: plane.log.YYYYMMDD - - # ... following sub-sections omitted ... - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - Planeflight diagnostic output. - - Default value: :literal:`false` - -.. option:: flight_track_file - - Specifies the path to a flight track file. This file contains - the coordinates of the plane as a function of time, as well as the - requested quantities to archive. - -.. option:: output_file - - Specifies the path to the Planeflight output file. Requested - quantities will be archived from GEOS-Chem along the flight track - specified in :option:`flight_track_file`. - -.. _cfg-gc-yml-hg: - -===================== -Hg simulation options -===================== - -This section of :file:`geoschem_config.yml` is included for -the `mercury (Hg) simulation `_: - -.. _cfg-gc-yml-hg-src: - -Hg sources ----------- - -The :literal:`Hg_simulation_options:sources` section contains settings -for various mercury sources. - -.. code-block:: YAML - - #============================================================================ - # Settings specific to the Hg simulation - #============================================================================ - Hg_simulation_options: - - sources: - use_dynamic_ocean_Hg: false - use_preindustrial_Hg: false - use_arctic_river_Hg: true - - # ... following sub-sections omitted ... - -.. option:: use_dynamic_ocean_Hg - - Activates (:literal:`true`) or deactivates (:literal:`false`) the online - slab ocean mercury model. - - Default value: :literal:`false` - -.. option:: use_preindustrial_Hg - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - preindustrial mercury simulation. This will turn off all - anthropogenic emissions. - - Default value: :literal:`false` - -.. option:: use_arctic_river_Hg - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - source of mercury from arctic rivers. - - Default value: :literal:`true` - -.. _cfg-gc-yml-hg-chem: - -Hg chemistry ------------- - -The :literal:`Hg_simulation_options:chemistry` section contains settings -for mercury chemistry: - -.. code-block:: YAML - - #============================================================================ - # Settings specific to the Hg simulation - #============================================================================ - Hg_simulation_options: - - # ... preceding sub-sections omitted ... - - chemistry: - tie_HgIIaq_reduction_to_UVB: true - - # ... following sub-sections omitted ... - -.. option:: tie_HgIIaq_reduction_to_UVB - - Activates (:literal:`true`) or deactivates (:literal:`false`) linking the - reduction of aqueous oxidized mercury to UVB radiation. - A lifetime of -1 seconds indicates the species has an infinite lifetime. - - Default value: :literal:`true` - -.. _cfg-gc-yml-carbon: - -========================================= -Options for simulations with carbon gases -========================================= - -These sections of :file:`geoschem_config.yml` are included for -simulations with carbon gases (:option:`carbon`, :option:`CH4`, -:option:`CO2`, :option:`tagCO`, :option:`tagCH4`). - -.. _gc-yml-ch4_obsopt: - -CH4 observational operators ----------------------------- - -The :literal:`CH4_simulation_options:use_observational_operators` section -contains options for using satellite observational operators for CH4: - -.. code-block:: YAML - - #============================================================================ - # Settings specific to the CH4 simulation / Integrated Methane Inversion - #============================================================================ - CH4_simulation_options: - - use_observational_operators: - AIRS: false - GOSAT: false - TCCON: false - - # ... following sub-sections omitted ... - -.. option:: AIRS - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - AIRS observational operator. - - Default value: :literal:`false` - -.. option:: GOSAT - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - GOSAT observational operator. - - Default value: :literal:`false` - -.. option:: TCCON - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - GOSAT observational operator. - - Default value: :literal:`false` - -.. _gc-yml-ch4_anopt: - -CH4 analytical inversion options ---------------------------------- - -The :literal:`ch4_simulation_options:analytical_inversion` section -contains options for analytical inversions with the `Integrated -Methane Inversion workflow (aka IMI) `_. -The IMI will automatically modify several of these options based on -the inversion parameters that you specify. - -.. code-block:: YAML - - #============================================================================ - # Settings specific to the CH4 simulation / Integrated Methane Inversion - #============================================================================ - CH4_simulation_options: - - # ... preceding sub-sections omitted ... - - analytical_inversion: - perturb_OH_boundary_conditions: false - CH4_boundary_condition_ppb_increase_NSEW: [0.0, 0.0, 0.0, 0.0] - -.. option:: perturb_CH4_boundary_conditions - - Activates (:literal:`true`) or deactivatees (:literal:`false`) - perturbation of CH4 nested-grid boundary conditions in analytical - inversions. - - Default value: :literal:`false` - -.. option:: CH4_boundary_condition_ppb_increase_NSEW - - Specifies the perturbation amount (in ppbv) to apply to the north, - south, east and west CH4 nested-grid boundary conditions. Used in - conjunction with the :option:`perturb_CH4_boundary_conditions` - option. - - Default value: :literal:`[0.0, 0.0, 0.0, 0.0]` (no perturbation) - -.. _cfg-gc-yml-co2: - -CO2 Sources ------------ - -The :literal:`CO2_simulation_options:sources` section contains toggles -for activating sources of :math:`CO_2`: - -.. code-block:: YAML - - #============================================================================ - # Settings specific to the CO2 simulation - #============================================================================ - CO2_simulation_options: - - sources: - 3D_chemical_oxidation_source: true - - # ... following sub-sections omitted ... - -.. option:: 3D_chemical_oxidation_source - - Activates (:literal:`true`) or deactivates (:literal:`false`) - :math:`CO_2` production by archived chemical oxidation, as read by - HEMCO. - - Default value: :literal:`true` - -.. _cfg-gc-yml-co2-tagspc: - -CO2 tagged species ------------------- - -The :literal:`CO2_simulation_options:tagged_species` section contains toggles -for activating tagged :math:`CO_2` species: - -.. attention:: - - Tagged :math:`CO_2` tracers should be customized by each user and - the present configuration will not work for resolutions other than - :math:`2.0^{\circ} {\times} 2.5^{\circ}`. - -.. code-block:: YAML - - #============================================================================ - # Settings specific to the CO2 simulation - #============================================================================ - CO2_simulation_options: - - # ... preceding sub-sections omitted ... - - tagged_species: - tag_bio_and_ocean_CO2: false - tag_land_fossil_fuel_CO2: false - - # .. following sub-sections omitted ... - -.. option:: tag_bio_and_ocean_CO2 - - Activates (:literal:`true`) or deactivates (:literal:`false`) tagging of - biosphere regions (28), ocean regions (11), and the rest of the - world (ROW) as specified in :file:`Regions_land.dat` and - :file:`Regions_ocean.dat` files. - -.. option:: tag_land_fossil_fuel_CO2: - - Activates (:literal:`true`) or deactivates (:literal:`false`) tagging of - land and ocean fossil fuel regions. - - -.. _cfg-gc-yml-co: - -CO chemical sources -------------------- - -The :literal:`tagged_CO_simulation_options` section contains settings -for the :option:`carbon` simulation and `tagged CO simulation -`_. - -.. code-block:: YAML - - #============================================================================ - # Settings specific to the tagged CO simulation - #============================================================================ - - tagged_CO_simulation_options: - use_fullchem_PCO_from_CH4: true - use_fullchem_PCO_from_NMVOC: true - -.. option:: use_fullchem_PCO_from_CH4 - - Activates (:literal:`true`) or deactivates (:literal:`false`) applying - the production of :math:`CO` from :math:`CH_4`. This field is - archived from a 1-year or 10-year :option:`fullchem` benchmark - simulation and is read from disk via HEMCO. - - Default value: :literal:`true` - -.. option:: use_fullchem_PCO_from_NMVOC - - Activates (:literal:`true`) or deactivates (:literal:`false`) applying - the production of :math:`CO` from non-methane volatile organic - compounds (VOCs). This field is archived from a 1-year or 10-year - :option:`fullchem` benchmark simulation and is read from disk via - HEMCO. - - Default value: :literal:`true` diff --git a/docs/source/gcclassic-user-guide/hemco-config.rst b/docs/source/gcclassic-user-guide/hemco-config.rst deleted file mode 100644 index f2fea57..0000000 --- a/docs/source/gcclassic-user-guide/hemco-config.rst +++ /dev/null @@ -1,225 +0,0 @@ -.. _cfg-hco-cfg: - -############### -HEMCO_Config.rc -############### - -GEOS-Chem Classic relies on the `Harmonized Emissions Component (aka -HEMCO) `_ for file I/O, regridding, and -computing emissions fluxes. Settings for HEMCO can be updated in the -`HEMCO configuration file -`_, -which is named :file:`HEMCO_Config.rc`. - -The HEMCO online manual at `hemco.readthedocs.io -`_ contains detailed instructions about -the structure and contents of :file:`HEMCO_Config.rc`, so we will not -replicate that content in this Guide. Instead, we will provide a -short summary with links to the relevant documentation. - -.. _cfg-hco-cfg-settings: - -====================== -General HEMCO settings -====================== - -Define general simulation parameters in the `Settings section -`_ -of :file:`HEMCO_Config.rc`. This includes data paths, global -diagnostic options, and verbose output options. - -.. code-block:: kconfig - - ############################################################################### - ### BEGIN SECTION SETTINGS - ############################################################################### - - ROOT: /path/to/hemco/data/dir - METDIR: /path/to/hemco/met/dir - GCAPSCENARIO: not_used - GCAPVERTRES: 47 - Logfile: * - DiagnFile: HEMCO_Diagn.rc - DiagnPrefix: ./OutputDir/HEMCO_diagnostics - DiagnFreq: 00000000 010000 - Wildcard: * - Separator: / - Unit tolerance: 1 - Negative values: 0 - Only unitless scale factors: false - Verbose: false - VerboseOnCores: root # Accepted values: root all - - ### END SECTION SETTINGS ### - -.. _cfg-hco-cfg-extswitches: - -================== -Extension switches -================== - -Turn individual emissions inventories on/off in the `Extension -Switches section -`_ -of :file:`HEMCO_Config.rc`. Emission inventories are -specified as either `Base Emissions -`_ -(i.e. read from files on disk) or `Extensions -`_ -(i.e. computed using meteorological inputs). - -.. code-block:: kconfig - - ############################################################################### - ### BEGIN SECTION EXTENSION SWITCHES - ############################################################################### - # ExtNr ExtName on/off Species Years avail. - 0 Base : on * - # ----- MAIN SWITCHES --------------------------------------------------------- - --> EMISSIONS : true - --> METEOROLOGY : true - --> CHEMISTRY_INPUT : true - # ----- RESTART FIELDS -------------------------------------------------------- - --> GC_RESTART : true - --> HEMCO_RESTART : true - # ----- NESTED GRID FIELDS ---------------------------------------------------- - --> GC_BCs : false - # ----- REGIONAL INVENTORIES -------------------------------------------------- - --> APEI : false # 1989-2014 - --> NEI2016_MONMEAN : false # 2002-2020 - --> DICE_Africa : false # 2013 - # ----- GLOBAL INVENTORIES ---------------------------------------------------- - --> CEDSv2 : true # 1750-2019 - --> CEDS_GBDMAPS : false # 1970-2017 - --> CEDS_GBDMAPS_byFuelType: false # 1970-2017 - - ... etc ... - - # ----------------------------------------------------------------------------- - 100 Custom : off - - 101 SeaFlux : on DMS/ACET/ALD2/MENO3/ETNO3/MOH - 102 ParaNOx : on NO/NO2/O3/HNO3 - --> LUT data format : nc - --> LUT source dir : $ROOT/PARANOX/v2015-02 - 103 LightNOx : on NO - --> CDF table : $ROOT/LIGHTNOX/v2014-07/light_dist.ott2010.dat - 104 SoilNOx : on NO - --> Use fertilizer NOx : true - - ... etc ... - - ### END SECTION EXTENSION SWITCHES ### - -.. _cfg-hco-base: - -============== -Base emissions -============== - -.. note:: - - You do not have to edit this section if you just wish to run - GEOS-Chem Classic with its default emissions configuration. - -Specify how emissions and other data sets will be read from disk in -the `Base Emissions section -`_ -of :file:`HEMCO_Config.rc`. - -.. code-block:: kconfig - - ############################################################################### - ### BEGIN SECTION BASE EMISSIONS - ############################################################################### - - # ExtNrName sourceFile sourceVar sourceTime C/R/E SrcDim SrcUnit Species ScalIDs Cat Hier - - (((EMISSIONS - - #============================================================================== - # --- APEI (Canada) --- - #============================================================================== - (((APEI - 0 APEI_NO $ROOT/APEI/v2016-11/APEI.0.1x0.1.nc NOx 1989-2014/1/1/0 RF xy kg/m2/s NO 25/1002/115 1 30 - 0 APEI_CO $ROOT/APEI/v2016-11/APEI.0.1x0.1.nc CO 1989-2014/1/1/0 RF xy kg/m2/s CO 26/52/1002 1 30 - 0 APEI_SOAP - - - - - - SOAP 26/52/1002/280 1 30 - 0 APEI_SO2 $ROOT/APEI/v2016-11/APEI.0.1x0.1.nc SOx 1989-2014/1/1/0 RF xy kg/m2/s SO2 60/1002 1 30 - 0 APEI_SO4 - - - - - - SO4 60/65/1002 1 30 - 0 APEI_pFe - - - ... etc ... - - ### END SECTION BASE EMISSIONS ### - -.. _cfg-hco-scalefac: - -============= -Scale factors -============= - -Define scale factors for emissions inventories and other data sets in -the `Scale Factors section -`_ -of :file:`HEMCO_Config.rc`. - -.. code-block:: kconfig - - #============================================================================== - # --- Scale factors used for species conversions --- - #============================================================================== - - # Units carbon to species conversions - # Factor = # carbon atoms * MW carbon) / MW species - 40 CtoACET MATH:58.09/(3.0*12.0) - - - xy unitless 1 - 41 CtoALD2 MATH:44.06/(2.0*12.0) - - - xy unitless 1 - 42 CtoALK4 MATH:58.12/(4.3*12.0) - - - xy unitless 1 - - ... etc ... - # VOC speciations - (((RCP_3PD.or.RCP_45.or.RCP_60.or.RCP_85 - 50 KET2MEK 0.25 - - - xy unitless 1 - 51 KET2ACET 0.75 - - - xy unitless 1 - )))RCP_3PD.or.RCP_45.or.RCP_60.or.RCP_85 - - ... etc ... - - ### END SECTION SCALE FACTORS ### - -.. _masks: - -===== -Masks -===== - -Define masks for emissions and other data sets in the `Masks section -`_ -of :file:`HEMCO_Config.rc` - -.. code-block:: kconfig - - ############################################################################### - ### BEGIN SECTION MASKS - ############################################################################### - - # ScalID Name sourceFile sourceVar sourceTime C/R/E SrcDim SrcUnit Oper Lon1/Lat1/Lon2/Lat2 - - (((EMISSIONS - - #============================================================================== - # Country/region masks - #============================================================================== - (((APEI - 1002 CANADA_MASK $ROOT/MASKS/v2018-09/Canada_mask.geos.1x1.nc MASK 2000/1/1/0 C xy 1 1 -141/40/-52/85 - )))APEI - - (((NEI2016_MONMEAN - 1007 CONUS_MASK $ROOT/MASKS/v2018-09/CONUS_Mask.01x01.nc MASK 2000/1/1/0 C xy 1 1 -140/20/-50/60 - )))NEI2016_MONMEAN - - ... etc ... - - )))EMISSIONS - - ### END SECTION MASKS ### - - ### END OF HEMCO INPUT FILE ### diff --git a/docs/source/gcclassic-user-guide/hemco-diagn.rst b/docs/source/gcclassic-user-guide/hemco-diagn.rst deleted file mode 100644 index aff1a92..0000000 --- a/docs/source/gcclassic-user-guide/hemco-diagn.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _cfg-hco-diagn: - -############## -HEMCO_Diagn.rc -############## - -In your run directory, you will find a copy of the `HEMCO diagnostic configuration file -`_ -(named :file:`HEMCO_Diagn.rc`) corresponding to the -:ref:`HEMCO_Config.rc ` file. You will only need to edit -this file if you wish to change the default diagnostic output configuration. - -A snippet of the :file:`HEMCO_Diagn.rc` for the :option:`fullchem` -simulation is shown below: - -.. code-block:: kconfig - - ############################################################################### - ##### ALD2 emissions ##### - ############################################################################### - EmisALD2_Total ALD2 -1 -1 -1 3 kg/m2/s ALD2_emission_flux_from_all_sectors - EmisALD2_Anthro ALD2 0 1 -1 3 kg/m2/s ALD2_emission_flux_from_anthropogenic - EmisALD2_BioBurn ALD2 111 -1 -1 2 kg/m2/s ALD2_emission_flux_from_biomass_burning - EmisALD2_Biogenic ALD2 0 4 -1 2 kg/m2/s ALD2_emission_flux_from_biogenic_sources - EmisALD2_Ocean ALD2 101 -1 -1 2 kg/m2/s ALD2_emission_flux_from_ocean - EmisALD2_PlantDecay ALD2 0 3 -1 2 kg/m2/s ALD2_emission_flux_from_decaying_plants - EmisALD2_Ship ALD2 0 10 -1 2 kg/m2/s ALD2_emission_flux_from_ships - - -Columns: - -#. netCDF variable name for the requested diagnostic quantity -#. Species name -#. Extension number (:literal:`-1` means sum over all extensions) -#. Category (:literal:`-1` means sum over all categories) -#. Hierarchy (:literal:`-1` means sum over all hierarchies) -#. Dimension of data (:literal:`1`: scalar, :literal:`2`: lon-lat, - :literal:`3`: lon-lat-lev) -#. Units -#. Value for the :literal:`long_name` netCDF variable attribute - -The prefix (e.g. :literal:`OutputDir/HEMCO_diagnostics`) for HEMCO diagnostics -output files are specified in the -`Settings section of the HEMCO_Config.rc file -`_. diff --git a/docs/source/gcclassic-user-guide/phot-chem.rst b/docs/source/gcclassic-user-guide/phot-chem.rst deleted file mode 100644 index 4e76caa..0000000 --- a/docs/source/gcclassic-user-guide/phot-chem.rst +++ /dev/null @@ -1,100 +0,0 @@ -.. _cfg-phot-chem: - -############################################ -Photolysis and chemistry configuration files -############################################ - -.. note:: - - You won't need to edit these configuration files unless you are - changing the photolysis and/or chemistry mechanisms used in your - GEOS-Chem Classic simulation. - -.. _cfg-phot-chm-phot: - -============================== -Photolysis configuration files -============================== - -Configuration files containing photolysis parameters (such as quantum -yields, cross sections, branching ratios, etc.) may be found in -subdirectories of :file:`ExtData/CHEM_INPUTS/CLOUD-J/` and -:file:`ExtData/CHEM_INPUTS/FAST-JX/`. See the :ref:`cfg-gc-yml` -file for the current file path specifications. - -GEOS-Chem versions 14.3.0 and later use the :program:`Cloud-J` -photolysis scheme by default. However, some aerosol properties -(e.g. relative humidity dependence) are still stored in files located -in the :file:`ExtData/CHEM_INPUTS/FAST_JX` directory tree. - -At present, the mercury (Hg) simulation still uses the legacy -:program:`FAST-JX` photolysis scheme. We look to the GEOS-Chem user -community to take the lead on creating configuration files for -:program:`Cloud-J`. - -.. _cfg-phot-chem-chem: - -====================================== -Chemical mechanism configuration files -====================================== - -GEOS-Chem Classic simulations use source code generated by `The -Kinetic PreProcessor `_. -If you need to update the default chemistry mechanism, you will need -to do the following steps: - -#. Modify the relevant KPP configuration files (described below); -#. Run KPP to generate updated source code for GEOS-Chem Classic; -#. :ref:`Compile GEOS-Chem Classic ` to create a new - executable; -#. Start your GEOS-Chem Classic simulation. - -Chemical mechanism configuration files are located in these folders: - -.. option:: KPP/fullchem - - Contains configuration files for the default "full-chemistry" - mechanism (NOx + Ox + aerosols + Br + Cl + I). - - - :file:`fullchem.kpp`: Main configuration file for the - **fullchem** mechanism. - - - :file:`fullchem.eqn`: List of species and reactions - for the **fullchem** mechanism. - -.. option:: KPP/carbon - - Contains configuration files for the carbon gases mechanism - (CH4-CO2-CO-OCS): - - - :file:`carbon.kpp`: Main configuration file for the **carbon** - mechanism. - - - :file:`carbon.eqn`: List of species and reactions for the **carbon** - mechanism. - -.. option:: KPP/custom - - Contains configuration files that you can edit if you need to - create a custom mechanism. We recommend that you create the - custom in this folder and leave :file:`KPP/fullchem` and - :file:`KPP/Hg` untouched. - - - :file:`custom.kpp`: Copy of :file:`fullchem.kpp` - - - :file:`custom.eqn`: Copy of :file:`fullchem.eqn`. - -.. option:: KPP/Hg - - Contains configuration files for the mercury chemistry mechanism: - - - :file:`Hg.kpp`: Main configuration file for the **Hg** - mechanism. - - - :file:`Hg.eqn`: List of species and reactions for the **Hg** - mechanism. - -Please see the following references for more information about KPP: - -#. The KPP user manual (`kpp.readthedocs.io `_) -#. Supplemental Guide: :ref:`kppguide` diff --git a/docs/source/gcclassic-user-guide/spec-db.rst b/docs/source/gcclassic-user-guide/spec-db.rst deleted file mode 100644 index 325f440..0000000 --- a/docs/source/gcclassic-user-guide/spec-db.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. _cfg-spec-db: - -#################### -species_database.yml -#################### - -.. note:: - - You will only need to edit :file:`species_database.yml` if you are - adding new species to a GEOS-Chem simulation. - -The :ref:`GEOS-Chem Species Database ` is a `YAML file -`_ that contains a listing of metadata for each -species used by GEOS-Chem. The Species Database is included in your -run directory as file :file:`species_database.yml`, a snippet of which -is shown below. - -.. code-block:: yaml - - # GEOS-Chem Species Database - # Core species only (neglecting microphysics) - # NOTE: Anchors must be defined before any variables that reference them. - A3O2: - Formula: CH3CH2CH2OO - FullName: Primary peroxy radical from C3H8 - Is_Gas: true - MW_g: 75.10 - ACET: - DD_F0: 1.0 - DD_Hstar: 1.0e+5 - Formula: CH3C(O)CH3 - FullName: Acetone - Henry_CR: 5500.0 - Henry_K0: 2.74e+1 - Is_Advected: true - Is_DryDep: true - Is_Gas: true - Is_Photolysis: true - MW_g: 58.09 - - ... etc ... - - AERI: - DD_DvzAerSnow: 0.03 - DD_DvzMinVal: [0.01, 0.01] - DD_F0: 0.0 - DD_Hstar: 0.0 - Formula: I - FullName: Iodine on aerosol - Is_Advected: true - Is_Aerosol: true - Is_DryDep: true - Is_WetDep: true - MW_g: 126.90 - WD_AerScavEff: 1.0 - WD_KcScaleFac: [1.0, 0.5, 1.0] - WD_RainoutEff: [1.0, 0.0, 1.0] - WD_RainoutEff_Luo: [0.4, 0.0, 1.0] - - ... etc ... - -.. important:: - - Species NO (nitrogen oxide) must be listed in - :file:`species_database.yml` as :code:`'NO':`. This will avoid - YAML readers mis-intepreting this as :literal:`no` (meaning - :literal:`false`). - - -Each species name begins in the first column of the file, followed by -a :literal:`:`. Underneath -the species name follows an indented block of :ref:`species properties -` in :literal:`Property: Value` format. - -Some properties listed above are only applicable to gas-phase species, -and others to aerosol species. But at the very least, each species -should have the following properties defined: - -- :literal:`Formula` -- :literal:`FullName` -- :literal:`MW_g` -- Either :literal:`Is_Gas` or :literal:`Is_Aerosol` - -For more information about species properties, please see -:ref:`spcguide` in the Supplemental Guides section. diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index a68981b..7a3e9db 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit a68981bec91028c8165f220fef683650cb79afe4 +Subproject commit 7a3e9db6ed96e5edf66060734f479389fe40a2f5 From 08cccffc9491a64077b73503a315fc3f6e8036f8 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Mon, 30 Sep 2024 16:08:06 -0400 Subject: [PATCH 28/44] GEOS-Chem submodule update: Merge PR #2489 (fix for coarse-mode seasalt Ca, Mg, K) Signed-off-by: Melissa Sulprizio --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index 7ffdb5b..ced6447 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit 7ffdb5b64f2ab2a2cdb6030addbeb0fae6b61104 +Subproject commit ced6447def626729f69a301dca98bf605f91057f From f13ea9c1f17dd4e40b35244fa37cbaa6733269e3 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 30 Sep 2024 18:27:18 -0400 Subject: [PATCH 29/44] Updated "Speeding up a slow GEOS-Chem simulation" chapter docs/source/gcclassic-user-guide/run-speedup.rst - Changed "Use coarser timesteps" to "Use a coarser chemistry timestep" - Added table of recommended GEOS-Chem Classic timesteps - Cite Philip et al. 2016 - Added section "Use the Rosenbrock solver w/ auto-reduction" - Added section "Reduce the amount of files that need to be read" - Added section "Speeding up GEOS-Chem Classic nested-grid simulations" - Added subsection "Crop nested-grid meteorology inputs" - Added subsection "Increase the size of the transport buffer zone" Signed-off-by: Bob Yantosca --- .../gcclassic-user-guide/run-speedup.rst | 153 ++++++++++++++---- docs/source/geos-chem-shared-docs | 2 +- 2 files changed, 123 insertions(+), 32 deletions(-) diff --git a/docs/source/gcclassic-user-guide/run-speedup.rst b/docs/source/gcclassic-user-guide/run-speedup.rst index e56ef67..caaf9d1 100644 --- a/docs/source/gcclassic-user-guide/run-speedup.rst +++ b/docs/source/gcclassic-user-guide/run-speedup.rst @@ -1,7 +1,3 @@ -.. |br| raw:: html - -
- .. _run-speedup: ########################## @@ -11,32 +7,77 @@ Speed up a slow simulation GEOS-Chem Classic performance is continuously monitored by the `GEOS-Chem Support Team `_ by means of -benchmark simulations and ad-hoc timing tests. It has been shown that -running GEOS-Chem with -`recommended timesteps -`_ -from :cite:t:`Philip_et_al._2016`. can increase run times by -approximately a factor of 2. To speed up GEOS-Chem Classic -simulations, users may choose to use any of the following options. - -.. _use-coarser-timesteps: - -===================== -Use coarser timesteps -===================== - -As :ref:`discussed previously `, the default -timesteps for GEOS-Chem Classic are 600 seconds for dynamics, and 1200 -seconds for chemistry and emissions. You can experiment with using -coarser timesteps (such as 1800 seconds for dynamics and 3600 seconds -for emissions & chemistry). - -.. attention:: - - For nested-grid simulations, you might not be able to use coarser - timesteps, or else the Courant limit in transport will be violated. - -.. _turn-off-diagnostics: +benchmark simulations and ad-hoc timing tests. In this chapter, we +provide some practical tips that you can use to speed up your +simulations. + +.. _run-speedup-coarse-timesteps: + +================================ +Use a coarser chemistry timestep +================================ + +The table below contains our recommended GEOS-Chem Classic timestep +settings. + ++----------------------------------------------+-------------+--------------+ +| GEOS-Chem Classic Resolution | Transport | Chemistry | ++==============================================+=============+==============+ +| :math:`4^{\circ}{\times}5^{\circ}` | 600s (10m) | 1200s (20m) | ++----------------------------------------------+-------------+--------------+ +| :math:`2^{\circ}{\times}2.5^{\circ}` | 600s (10m) | 1200s (20m) | ++----------------------------------------------+-------------+--------------+ +| :math:`0.5^{\circ}{\times}0.625^{\circ}` | 300s (5m) | 600s (10m) | ++----------------------------------------------+-------------+--------------+ +| :math:`0.25^{\circ}{\times}0.3125^{\circ}` | 300s (5m) | 600s (10m) | ++----------------------------------------------+-------------+--------------+ +| :math:`0.125^{\circ}{\times}0.15625^{\circ}` | 150s (2.5m) | 300s (5m) | ++----------------------------------------------+-------------+--------------+ + +The `Courant limit +`_ +on the latitude-longitude grid constrains the choice of transport +timestep for a given horizontal resolution. We choose a chemistry +timestep that is double the transport timestep (i.e. +`Strang operator splitting +`_). + +If you wish to speed up your simulation, try increasing the chemistry +timestep. Chemistry is the GEOS-Chem operation that takes the longest +to execute, so increasing the interval between calls to the chemistry +solver will reduce the run time accordingly. But you should also verify +that the increased chemistry timestep allows your simulation to +faithfully capture diurnal variations, etc. + +See :cite:t:`Philip_et_al._2016` for a comprehensive study on +GEOS-Chem timesteps. + +.. _run-speedup-autoreduce: + +============================================= +Use the Rosenbrock solver with auto-reduction +============================================= + +The GEOS-Chem full-chemistry mechanism uses the KPP Rosenbrock solver, +which has an `automatic mechanism reduction option +`_ +as described in :cite:t:`Lin_et_al._2023`. This automatic mechanism +reduction feature separates species into "fast" and "slow" +categories based on their chemical production or loss rates. "Fast" +species are integrated with the full Rosenbrock algorithm, while +"slow" species will have a simple 1st-order loss applied to +them. This approach has been shown to reduce the time spent in +chemistry by 20 to 30 percent. + +The automatic mechanism reduction option is disabled by default, but +can be enabled by toggiing this switch in :ref:`cfg-gc-yml`: + +.. code-block:: yaml + + autoreduce_solver: + activate: false # <=== set to true to activate auto-reduction + +.. _run-speedup-disable-diags: ============================= Turn off unwanted diagnostics @@ -48,7 +89,7 @@ are turned on, the more I/O operations need to be done, resulting in longer simulation execution times. Disabling diagnostics that you do not wish to archive can result in a faster simulation. -.. _disable-debug-options: +.. _run-speedup-disable-debug: ========================= Disable debugging options @@ -67,3 +108,53 @@ Classic simulation, but result in a much slower simulation. If you plan on running a long Classic simulation, make sure that you :ref:`configure and build GEOS-Chem Classic ` so that :option:`CMAKE_BUILD_TYPE` is set to :envvar:`Release`. + +.. _run-speedup-combine-files: + +=============================================== +Reduce the amount of files that need to be read +=============================================== + +If you are developing a new data set (such as an emissions inventory) +for GEOS-Chem, we recommend that you prepare data files with multiple +timestamps rather than one file per timestamp. For example, if your +data set has hourly time resolution, consider creating one file for +each day, with each file containing 24 hours of data, etc. + +The greatest amount of overhead in I/O occurs when new data files (in +netCDF format) are opened. This also usually involves decompression +of the file contents, which is computationally intensive. Reducing +the number of times that GEOS-Chem has to open and close netCDF files +can substantially improve performance. + +.. _run-speedup-nested: + +===================================================== +Speeding up GEOS-Chem Classic nested-grid simulations +===================================================== + +Use these tips to speed up your GEOS-Chem nested-grid simulations: + +.. _run-speedup-nested-crop: + +Crop nested-grid meteorology inputs +----------------------------------- + +Your simulation should not read global high-resolution +(:math:`0.5^{\circ}{\times}0.625^{\circ}` or finer) meteorology +fields. The overhead in reading and regridding these global fields +can significantly impact your simulation. Instead, consider cropping +high-resolution meteorology fields to the extent of your nested domain. +This can easily be done with the netCDF operators or the Climate Data +Operators; see our :ref:`netcdf-guide` supplemental guide for more +information. + +.. _run-speedup-nested-buffer: + +Increase the size of the transport buffer zone +---------------------------------------------- + +By default, nested :option:`buffer_zone_NSEW` option is set to 3 boxes +in each cardinal direction. Increasing this number will reduce the +amount of grid boxes in which transport will be performed, which +should also reduce the overall run time. diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index 7a3e9db..679cf4c 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit 7a3e9db6ed96e5edf66060734f479389fe40a2f5 +Subproject commit 679cf4c150c0f084ecbb63a1d3b0f9af3df14e8c From 1c6c0adb0d4854983e68b14f3297c003d0271d3a Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Tue, 1 Oct 2024 09:45:37 -0400 Subject: [PATCH 30/44] GEOS-Chem submodule update: Merge PR #2490 (clean up CHANGELOG.md) Signed-off-by: Melissa Sulprizio --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index ced6447..c7a6ae6 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit ced6447def626729f69a301dca98bf605f91057f +Subproject commit c7a6ae6277a173aa67b903af3af659ebbd2b36d2 From 2734825426a1e1f512e55df7c114158ecc5df126 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Tue, 1 Oct 2024 13:36:43 -0400 Subject: [PATCH 31/44] Cloud-J submodule update for 8.0.1 release Signed-off-by: Melissa Sulprizio --- CHANGELOG.md | 5 +++++ src/Cloud-J | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5575ae0..7fc2747 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,11 @@ 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 +### Changed +- Updated GEOS-Chem to 14.5.0 +- Updated HEMCO to 3.10.0 +- Updated Cloud-J to 8.0.1 + ### Fixed - Fixed formatting error in `.github/workflows/stale.yml` that caused the Mark Stale Issues action not to run diff --git a/src/Cloud-J b/src/Cloud-J index 6bf4a36..f8a2b7f 160000 --- a/src/Cloud-J +++ b/src/Cloud-J @@ -1 +1 @@ -Subproject commit 6bf4a36d11039783c0b29befc48e93cdff7f6ecb +Subproject commit f8a2b7f964bde1582fbc38c41d8872bc23a21735 From 440b4d65d3cd4c643b72ded2ca757faf85fc0b6b Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 1 Oct 2024 16:24:20 -0400 Subject: [PATCH 32/44] geos-chem-shared-docs update: Add doc about diffs btw GCHP & GCC docs/source/geos-chem-shared-docs: - Added documentation to doc/geoschem-config.rst and doc/hemco-config.rst to make the differences between GCHP and GCClassic more explicit. Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index 679cf4c..b5420bb 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit 679cf4c150c0f084ecbb63a1d3b0f9af3df14e8c +Subproject commit b5420bbb77f9fea9b26cc36785c441883295b029 From f19794e97b56d720827536f404e57115afc8481f Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 2 Oct 2024 11:01:31 -0400 Subject: [PATCH 33/44] geos-chem-shared-doc update: Fixed typo; Added GCHP vs. GCC diffs docs/source/geos-chem-shared-docs - Fixed typo in doc/geoschem-config.rst - Added GCHP vs. GCC usage difference section in the documentation for HEMCO_Diagn.rc Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index b5420bb..8ed145c 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit b5420bbb77f9fea9b26cc36785c441883295b029 +Subproject commit 8ed145c6c813b325c6101392f7ff6e203f851d9b From 9545c59f381e41db15f2f9e163f9ac63ed690613 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Thu, 3 Oct 2024 09:29:13 -0400 Subject: [PATCH 34/44] GEOS-Chem submodule update: Merge PR #2493 (rename ALK7 to ALK6) Signed-off-by: Melissa Sulprizio --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index c7a6ae6..57cf0df 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit c7a6ae6277a173aa67b903af3af659ebbd2b36d2 +Subproject commit 57cf0dfcdae0d4abbc6094fc119b94f5f5826373 From 347c3a2964194e85d66266d1798fb5128a6359bc Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Thu, 3 Oct 2024 10:58:34 -0400 Subject: [PATCH 35/44] GEOS-Chem submodule update: Merge PR #2492 (fixes for GCHP carbon sim) Signed-off-by: Melissa Sulprizio --- src/GEOS-Chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index 57cf0df..51d306d 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit 57cf0dfcdae0d4abbc6094fc119b94f5f5826373 +Subproject commit 51d306dade21a6c36e5537224b7c533b5489667c From 29b8615096e159253009bc3bcd52da32e5777101 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 15 Oct 2024 14:37:53 -0400 Subject: [PATCH 36/44] geos-chem-shared-docs update: GC input data; GCHP History guide This commit informs the GCClassic superproject about the following commits that were pushed to the geos-chem-shared-docs repository: 65b2a35 Merge "docs/update_guides_for_gchp" into "main" 7f0cfbb Merge PR #3 (Add doc/tutorial for GEOS-Chem input data on AWS) These are documentation updates for the 14.5.0 release. Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index 8ed145c..65b2a35 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit 8ed145c6c813b325c6101392f7ff6e203f851d9b +Subproject commit 65b2a350db689d858e547228f9b3a261db1bd86e From a6973ae06859a1c703600b63f8c2e42cb6a3d014 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Fri, 1 Nov 2024 20:07:32 -0400 Subject: [PATCH 37/44] RTD Updates: Additional updates for GC Input Data repository docs/source/gcclassic-user-guide/download-data.rst - Removed input-overview.rst from toctree - Added gcid-repository-overview.rst to toctree - Added gcid-special-repos.rst to toctree docs/source/gcclassic-user-guide/dry-run-download.rst - Add references to pages in geos-chem-shared-docs/doc folder pertaining to the GEOS-Chem input data - Renamed "Choose a data portal" section to "Choose a data repository", and updated the data repository descriptions docs/source/gcclassic-user-guide/gcid-special-repos.rst - New page describing GEOS-Chem Nested Input Data and GCAP 2.0 @ Rochester repositories docs/source/geos-chem-shared-docs - Updated submodule hash to commit 09a2f03 Signed-off-by: Bob Yantosca --- .../gcclassic-user-guide/download-data.rst | 5 +- .../gcclassic-user-guide/dry-run-download.rst | 192 ++++++++++++------ .../gcid-special-repos.rst | 84 ++++++++ docs/source/geos-chem-shared-docs | 2 +- 4 files changed, 219 insertions(+), 64 deletions(-) create mode 100644 docs/source/gcclassic-user-guide/gcid-special-repos.rst diff --git a/docs/source/gcclassic-user-guide/download-data.rst b/docs/source/gcclassic-user-guide/download-data.rst index 99e745b..6bbf6ed 100644 --- 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-repository-overview.rst + gcid-special-repos.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 index f70fa07..01e2c08 100644 --- 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 + +
+ .. _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 `. .. important:: @@ -34,79 +38,93 @@ several locations, which are described in the following sections. more information, please see `gcpy.readthedocs.io `_. -.. _dry-run-data-download-portal: +.. _dry-run-data-download-repo: -==================== -Choose a data portal -==================== +======================== +Choose a data repository +======================== You can :ref:`download input data ` from one of the following -locations: +repositories: -.. _dry-run-download-washu: +.. _dry-run-download-repo-gc: -The :file:`geoschemdata.wustl.edu` site (aka WashU) ---------------------------------------------------- +GEOS-Chem Input Data +-------------------- -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 -`_). This site, which is -maintained by Randall Martin's group at WashU, is the main data site -for GEOS-Chem. +The :ref:`GEOS-Chem Input Data ` repository is the main source +of input data (emissions, meteorology, chemistry inputs, restart +files) for GEOS-Chem. We recommend that you download data from this +repository unless otherwise necessary. + +This repository is curated by the GEOS-Chem Support Team at Washington +University in St. Louis, and is hosted on the AWS S3 bucket +:file:`s3://geos-chem`. .. tip:: - We have also set up a `Globus - `_ 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). + We have set up a `Globus `_ + endpoint named **GEOS-Chem data (WashU)**, which links to the + GEOS-Chem Input Data repository. If you need to download many + years of data, you may find that using Globus is much faster than + downloading data with a dry-run simulation. Ask your IT support + staff if Globus is supported at your institution. -.. _dry-run-download-aws: +Supported download methods: -The :file:`s3://gcgrid` bucket (aka Amazon) -------------------------------------------- +- AWS CLI (command-line interface) +- HTTP download (e.g via :program:`wget`) +- Globus -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. +Repository browser: -Navigate to your GEOS-Chem Classic run directory and type: +- AWS S3 Explorer (https://geos-chem.s3.amazonaws.com/index.html) -.. code-block:: console +.. _dry-run-download-repo-nest: - $ ./download data.py log.dryrun amazon +GEOS-Chem Nested Input Data +--------------------------- -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**. +The :ref:`gcid-special-repos-nested` repository contains cropped +GEOS-FP and MERRA-2 meteorological inputs for several nested domains. +These data can be used to perform high-resolution inversions using the +`Integrated Methane Inversion (IMI) `_ +workflow. -.. note:: +This repository is curated by the GEOS-Chem Support Team at +Harvard University and is hosted at the AWS S3 bucket +:file:`s3://gcgrid`. - 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 - `_. +Supported download methods: -.. _dry-run-download-rochester: +- AWS CLI (command-line interface) +- HTTP download (e.g via :program:`wget`) -The :file:`atmos.earth.rochester.edu` site (aka Rochester) ----------------------------------------------------------- +Repository browser: -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. +- AWS S3 Explorer (https://gcgrid.s3.amazonaws.com/index.html) -To download data from the Rochester site, type: +.. _dry-run-download-repo-ur: -.. code-block:: console +GCAP 2.0 meteorology at University of Rochester +----------------------------------------------- + +The `atmos.earth.rochester.edu +`_ repository +contains the GCAP 2.0 meteorology inputs for GEOS-Chem. GCAP 2.0 +meteorology is useful if you wish to perform simulations stretching +back into the preindustrial period, or running into the future. + +This repository is curated by Lee Murray (GitHub: +:literal:`@ltmurray`) at the University of Rochester. - $ ./download data.py log.dryrun rochester +Supported download methods: + +- HTTP download (e.g via :program:`wget`) + +Repository browser: + +- HTTP site (http://atmos.earth.rochester.edu/input/gc/ExtData) .. _dry-run-download-data: @@ -115,19 +133,71 @@ 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 REPOSITORY-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 ` that you create. |br| + |br| + +- :file:`log.dryrun` is the log file from your GEOS-Chem dry-run + simulation. |br| + |br| + +- :literal:`REPOSITORY-NAME` specifies the data repository that you wish + to download from. Allowed values are: + + .. list-table:: Allowed values for the ``REPOSITORY-NAME`` argument + to ``download_data.py`` + :header-rows: 1 + + * - Value + - Downloads from repository + - Command used + - Method + * - geoschem-s3 + - :ref:`dry-run-download-repo-gc` + - :command:`aws s3 cp` + - AWS CLI + * - geoschem-wget + - :ref:`dry-run-download-repo-gc` + - :command:`wget` + - HTTP + * - nested-s3 + - :ref:`dry-run-download-repo-nest` + - :command:`aws s3 cp` + - AWS CLI + * - nested-wget + - :ref:`dry-run-download-repo-nest` + - :command:`wget` + - HTTP + * - rochester + - :ref:`GCAP 2.0 met data @ Rochester ` + - :command:`wget` + - HTTP + +For example, to download data from the :ref:`dry-run-download-repo-gc` +repository 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 ` 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) + `_ software installed on your system + before in order to use the :literal:`geoschem-s3` or + :literal:`nested-s3` 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: @@ -172,13 +242,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 diff --git a/docs/source/gcclassic-user-guide/gcid-special-repos.rst b/docs/source/gcclassic-user-guide/gcid-special-repos.rst new file mode 100644 index 0000000..126ef34 --- /dev/null +++ b/docs/source/gcclassic-user-guide/gcid-special-repos.rst @@ -0,0 +1,84 @@ +.. |br| raw:: html + +
+ +.. _gcid-special-repos: + +######################################## +Additional meteorology data repositories +######################################## + +As discussed in the previous chapter, the :ref:`GEOS-Chem Input +Data ` repository is the main source of input data for +:program:`GEOS-Chem Classic`, :program:`GCHP`, and the :program:`HEMCO +standalone model`. This repository contains the entire catalog +of emissions inventories, chemical inputs, initial conditions, and +most years of `GEOS-FP `_, +`MERRA-2 `_, and GEOS-IT meteorology. + +We also maintain two additional data repositories for special data sets. + +.. _gcid-special-repos-nested: + +=========================== +GEOS-Chem Nested Input Data +=========================== + +.. attention:: + + We are still adding data to the GEOS-Chem Nested Input Data + repository. As of this writing (November 2024), not all data may + have been uploaded yet. We thank you for your patience. + +The `GEOS-Chem Nested Input data +`_ +repository stores GEOS-FP and MERRA-2 meteorology fields that have +been cropped to several nested domains. These data can be used to +perform high-resolution inversions with the `Integrated Methane +Inversion (IMI) `_ workflow. + +.. table:: Available nested-grid meteorology (2018 to present day) + :align: center + + +---------+--------------------------+-------------------------------+ + | Product | Horizontal resolution | Nested-grid domains | + +=========+==========================+===============================+ + | GEOS-FP | :math:`0.125^{\circ} | AF (Africa) |br| | + | | {\times}0.15625^{\circ}` | AS (Asia) |br| | + | | | EU (Europe) |br| | + | | | ME (Middle East) |br| | + | | | NA (North America) |br| | + | | | OC (Oceania) |br| | + | | | RU (Russia) |br| | + | | | SA (South America) | + +---------+--------------------------+-------------------------------+ + | MERRA-2 | :math:`0.5^{\circ} | AS (Asia) |br| | + | | {\times}0.625^{\circ}` | EU (Europe) |br| | + | | | NA (North America) |br| | + +---------+--------------------------+-------------------------------+ + +The data can be accessed by: + +- AWS S3 Explorer (https://s3.amazonaws.com/gcgrid/index.html) +- Direct HTTP or wget download +- :ref:`Dry-run simulation ` + +The GEOS-Chem Nested Input Data repository is also part of the `AWS +Open Data Sponsorship Program +`_. + +.. _gcid-special-repos-gcap2: + +======================================== +GCAP2 meteorology hosted at U. Rochester +======================================== + +The `atmos.earth.rochester.edu +`_ repository +(maintained by Lee Murray at the University of Rochester) contains the +GCAP 2.0 meteorological data inputs for use with GEOS-Chem simulations. + +The data can be accessed by: + +- Direct HTTP or wget download (http://atmos.earth.rochester.edu/input/gc/ExtData/) +- :ref:`Dry run simulation ` diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index 65b2a35..09a2f03 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit 65b2a350db689d858e547228f9b3a261db1bd86e +Subproject commit 09a2f03cd85a36f60b7333a0d744810116ce0820 From a10e19b239e35ae05f9c0eaf96c621a876466252 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 4 Nov 2024 11:22:05 -0500 Subject: [PATCH 38/44] RTD update: GC data portal doc updates + fixes broken links docs/source/gcclassic-user-guide/download-data.rst - Updated toctree docs/source/gcclassic-user-guide/dry-run-download.rst - Terminology change: "repository" -> "portal" - Simplified "Choose a data portal" section with table docs/source/gcclassic-user-guide/dry-run.rst - Removed tip box - Text formatting update docs/source/gcclassic-user-guide/gcid-special-repos.rst -> renamed to docs/source/gcclassic-user-guide/gcid-special-portals.rst docs/source/gcclassic-user-guide/input-overview.rst - Removed (now obsolete) docs/source/gcclassic-user-guide/restart-files-gc.rst docs/source/gcclassic-user-guide/restart-files-what.rst docs/source/gcclassic-user-guide/run-checklist.rst docs/source/getting-started/disk-space.rst - Fixed broken links & references - Text formatting updates docs/source/getting-started/quick-start.rst - Fixed broken links & references - Text formatting updates - Added attention box for resetting the time cycle flag for SPC_ in HEMCO_Config.rc docs/source/geos-chem-shared-docs - Submodule update with further updates for GEOS-Chem data portals Signed-off-by: Bob Yantosca --- .../gcclassic-user-guide/download-data.rst | 4 +- .../gcclassic-user-guide/dry-run-download.rst | 170 +++++-------- .../gcclassic-user-guide/dry-run-run.rst | 13 +- docs/source/gcclassic-user-guide/dry-run.rst | 28 +-- ...ial-repos.rst => gcid-special-portals.rst} | 44 ++-- .../gcclassic-user-guide/input-overview.rst | 228 ------------------ .../gcclassic-user-guide/restart-files-gc.rst | 3 +- .../restart-files-what.rst | 7 +- .../gcclassic-user-guide/run-checklist.rst | 9 +- .../gcclassic-user-guide/run-speedup.rst | 2 +- docs/source/geos-chem-shared-docs | 2 +- docs/source/getting-started/disk-space.rst | 8 +- docs/source/getting-started/quick-start.rst | 95 ++++++-- .../supplemental-guides/nested-grid-guide.rst | 19 +- 14 files changed, 206 insertions(+), 426 deletions(-) rename docs/source/gcclassic-user-guide/{gcid-special-repos.rst => gcid-special-portals.rst} (67%) delete mode 100644 docs/source/gcclassic-user-guide/input-overview.rst diff --git a/docs/source/gcclassic-user-guide/download-data.rst b/docs/source/gcclassic-user-guide/download-data.rst index 6bbf6ed..bac52ca 100644 --- a/docs/source/gcclassic-user-guide/download-data.rst +++ b/docs/source/gcclassic-user-guide/download-data.rst @@ -18,7 +18,7 @@ for your GEOS-Chem simulation. .. toctree:: :maxdepth: 2 - ../geos-chem-shared-docs/doc/gcid-repository-overview.rst - gcid-special-repos.rst + ../geos-chem-shared-docs/doc/gcid-portal-overview.rst + 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 index 01e2c08..c818d63 100644 --- a/docs/source/gcclassic-user-guide/dry-run-download.rst +++ b/docs/source/gcclassic-user-guide/dry-run-download.rst @@ -12,7 +12,7 @@ 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 different -:ref:`data repositories `. +:ref:`data repositories `. .. important:: @@ -38,95 +38,42 @@ corresponding "production" simulation. You may download from different more information, please see `gcpy.readthedocs.io `_. -.. _dry-run-data-download-repo: +.. _dry-run-data-download-portal: -======================== -Choose a data repository -======================== +==================== +Choose a data portal +==================== -You can :ref:`download input data ` from one of the following -repositories: +You can :ref:`download input data ` from any of the portals +listed below. -.. _dry-run-download-repo-gc: - -GEOS-Chem Input Data --------------------- - -The :ref:`GEOS-Chem Input Data ` repository is the main source -of input data (emissions, meteorology, chemistry inputs, restart -files) for GEOS-Chem. We recommend that you download data from this -repository unless otherwise necessary. - -This repository is curated by the GEOS-Chem Support Team at Washington -University in St. Louis, and is hosted on the AWS S3 bucket -:file:`s3://geos-chem`. - -.. tip:: - - We have set up a `Globus `_ - endpoint named **GEOS-Chem data (WashU)**, which links to the - GEOS-Chem Input Data repository. If you need to download many - years of data, you may find that using Globus is much faster than - downloading data with a dry-run simulation. Ask your IT support - staff if Globus is supported at your institution. - -Supported download methods: - -- AWS CLI (command-line interface) -- HTTP download (e.g via :program:`wget`) -- Globus - -Repository browser: - -- AWS S3 Explorer (https://geos-chem.s3.amazonaws.com/index.html) - -.. _dry-run-download-repo-nest: - -GEOS-Chem Nested Input Data ---------------------------- - -The :ref:`gcid-special-repos-nested` repository contains cropped -GEOS-FP and MERRA-2 meteorological inputs for several nested domains. -These data can be used to perform high-resolution inversions using the -`Integrated Methane Inversion (IMI) `_ -workflow. - -This repository is curated by the GEOS-Chem Support Team at -Harvard University and is hosted at the AWS S3 bucket -:file:`s3://gcgrid`. - -Supported download methods: - -- AWS CLI (command-line interface) -- HTTP download (e.g via :program:`wget`) - -Repository browser: - -- AWS S3 Explorer (https://gcgrid.s3.amazonaws.com/index.html) - -.. _dry-run-download-repo-ur: - -GCAP 2.0 meteorology at University of Rochester ------------------------------------------------ - -The `atmos.earth.rochester.edu -`_ repository -contains the GCAP 2.0 meteorology inputs for GEOS-Chem. GCAP 2.0 -meteorology is useful if you wish to perform simulations stretching -back into the preindustrial period, or running into the future. - -This repository is curated by Lee Murray (GitHub: -:literal:`@ltmurray`) at the University of Rochester. - -Supported download methods: - -- HTTP download (e.g via :program:`wget`) - -Repository browser: - -- HTTP site (http://atmos.earth.rochester.edu/input/gc/ExtData) + .. list-table:: GEOS-Chem data portals and access methods + :header-rows: 1 + :align: center -.. _dry-run-download-data: + * - Portal + - S3 Explorer + - AWS CLI + - HTTP + - Globus + * - :ref:`GEOS-Chem Input Data ` |br| + (The main source of GEOS-Chem input data) + - Yes + - Yes + - Yes + - Yes + * - :ref:`gcid-special-portals-nested` + - Yes + - Yes + - Yes + - No + * - :ref:`gcid-special-portals-gcap2` + - No + - No + - Yes + - No + +.. _dry-run-download-py: ============================================================== Run the :file:`download_data.py` script on the dryrun log file @@ -137,7 +84,7 @@ and type. .. code-block:: console - $ ./download_data.py log.dryrun REPOSITORY-NAME + $ ./download_data.py log.dryrun PORTAL-NAME where: @@ -150,40 +97,41 @@ where: simulation. |br| |br| -- :literal:`REPOSITORY-NAME` specifies the data repository that you wish +- :literal:`PORTAL-NAME` specifies the data portal that you wish to download from. Allowed values are: - .. list-table:: Allowed values for the ``REPOSITORY-NAME`` argument + .. list-table:: Allowed values for the ``PORTAL-NAME`` argument to ``download_data.py`` :header-rows: 1 + :align: center * - Value - - Downloads from repository - - Command used - - Method - * - geoschem-s3 - - :ref:`dry-run-download-repo-gc` + - Downloads from portal + - With this command + - Via this method + * - geoschem+aws + - :ref:`GEOS-Chem Input Data ` - :command:`aws s3 cp` - AWS CLI - * - geoschem-wget - - :ref:`dry-run-download-repo-gc` + * - geoschem+http + - :ref:`GEOS-Chem Input Data ` - :command:`wget` - HTTP - * - nested-s3 - - :ref:`dry-run-download-repo-nest` + * - nested+aws + - :ref:`gcid-special-portals-nested` - :command:`aws s3 cp` - AWS CLI - * - nested-wget - - :ref:`dry-run-download-repo-nest` + * - nested+http + - :ref:`gcid-special-portals-nested` - :command:`wget` - HTTP * - rochester - - :ref:`GCAP 2.0 met data @ Rochester ` + - :ref:`GCAP 2.0 met data @ Rochester ` - :command:`wget` - HTTP -For example, to download data from the :ref:`dry-run-download-repo-gc` -repository using the AWS CLI download (which is faster than HTTP +For example, to download data from the :ref:`dry-run-download-portal-gc` +portal using the AWS CLI download (which is faster than HTTP download), use this command: .. code-block:: console @@ -194,8 +142,8 @@ download), use this command: You must have the `AWS CLI (command-line interface) `_ software installed on your system - before in order to use the :literal:`geoschem-s3` or - :literal:`nested-s3` options in the table listed above. + 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 generate a **log of unique data files** (i.e. with all duplicate listings removed), which @@ -211,17 +159,17 @@ looks similar to this: !!! 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 + ./GEOSChem.Restart.20160701_0000z.nc4 --> /path/to/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 + /path/to/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/FJX_j2j.dat + /path/to/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/FJX_spec.dat + /path/to/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/dust.dat + /path/to/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/h2so4.dat + /path/to/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/jv_spec_mie.dat ... etc ... This name of this "unique" log file will be the same as the log file diff --git a/docs/source/gcclassic-user-guide/dry-run-run.rst b/docs/source/gcclassic-user-guide/dry-run-run.rst index 4a60732..b8ad155 100644 --- a/docs/source/gcclassic-user-guide/dry-run-run.rst +++ b/docs/source/gcclassic-user-guide/dry-run-run.rst @@ -6,15 +6,6 @@ Execute a dry-run simulation Follow the steps below to perform a GEOS-Chem Classic dry-run simulation: -.. tip:: - - Also be sure to watch our video tutorial `Using the updated - dry-run capability in GEOS-Chem 13.2.1 and later versions - `_ - at our `GEOS-Chem Youtube Channel - `_, which will guide you - through these steps. - ========================== Complete preliminary setup ========================== @@ -32,7 +23,7 @@ files `: #. :option:`start_date`: Set the start date and time for your simulation. #. :option:`end_date`: Set the end date and time for your simulation. - #. :option:`met_field`: Check if the meteorology setting + #. :option:`met_field`: Check if the meteorology setting (:option:`GEOS-FP`, :option:`MERRA2`, :option:`GCAP2`) is correct for your simulation. #. :option:`root_data_dir`: Make sure that the path to @@ -57,7 +48,7 @@ files `: sets for your simulation have been switched on. .. tip:: - + You can reduce the amount of data that needs to be downloaded for your simulation by turning off inventories that you don't need. diff --git a/docs/source/gcclassic-user-guide/dry-run.rst b/docs/source/gcclassic-user-guide/dry-run.rst index 07bb573..535aae3 100644 --- a/docs/source/gcclassic-user-guide/dry-run.rst +++ b/docs/source/gcclassic-user-guide/dry-run.rst @@ -7,20 +7,20 @@ Download data with a dry-run simulation .. tip:: If you are located at an institution with many other GEOS-Chem - users, then the :ref:`necessary input data ` might - have already been downloaded and stored in a commmon directory on - your system. Ask your sysadmin or IT support staff. - - Please see our :ref:`input-overview` chapter for other ways in - which you can download the necessary input data for GEOS-Chem. - -A "dry-run" is a is a :program:`GEOS-Chem Classic` simulation that -steps through time, but does not perform computations or read data -files from disk. Instead, a dry-run simulation prints a list of all -data files that a regular GEOS-Chem simulation would have read. The -dry-run output also denotes whether each data file was found on disk, -or if it is missing. This output can be fed to a script which will -download the missing data files to your computer system. + users, then the necessary input data might have already been + downloaded and stored in a commmon directory on your system. Ask + your sysadmin or IT support staff. + + Please see our :ref:`data` chapter for other ways in which you can + download the necessary input data for GEOS-Chem. + +A :program:`dry-run` is a is a :program:`GEOS-Chem Classic` simulation +that steps through time, but does not perform computations or read +data files from disk. Instead, a dry-run simulation prints a list of +all data files that a regular GEOS-Chem simulation would have +read. The dry-run output also denotes whether each data file was found +on disk, or if it is missing. This output can be fed to a script which +will download the missing data files to your computer system. You may generate dry-run output for any of the GEOS-Chem Classic simulation types (:option:`fullchem`, :option:`carbon`, diff --git a/docs/source/gcclassic-user-guide/gcid-special-repos.rst b/docs/source/gcclassic-user-guide/gcid-special-portals.rst similarity index 67% rename from docs/source/gcclassic-user-guide/gcid-special-repos.rst rename to docs/source/gcclassic-user-guide/gcid-special-portals.rst index 126ef34..49e62b9 100644 --- a/docs/source/gcclassic-user-guide/gcid-special-repos.rst +++ b/docs/source/gcclassic-user-guide/gcid-special-portals.rst @@ -2,23 +2,23 @@
-.. _gcid-special-repos: +.. _gcid-special-portals: -######################################## -Additional meteorology data repositories -######################################## +####################################### +Additional portals for meteorology data +####################################### As discussed in the previous chapter, the :ref:`GEOS-Chem Input -Data ` repository is the main source of input data for +Data ` portal is the main source of input data for :program:`GEOS-Chem Classic`, :program:`GCHP`, and the :program:`HEMCO -standalone model`. This repository contains the entire catalog +standalone model`. This portal contains the entire catalog of emissions inventories, chemical inputs, initial conditions, and most years of `GEOS-FP `_, `MERRA-2 `_, and GEOS-IT meteorology. -We also maintain two additional data repositories for special data sets. +We also maintain two additional data portals for special data sets. -.. _gcid-special-repos-nested: +.. _gcid-special-portals-nested: =========================== GEOS-Chem Nested Input Data @@ -27,15 +27,16 @@ GEOS-Chem Nested Input Data .. attention:: We are still adding data to the GEOS-Chem Nested Input Data - repository. As of this writing (November 2024), not all data may + portal. As of this writing (November 2024), not all data may have been uploaded yet. We thank you for your patience. The `GEOS-Chem Nested Input data `_ -repository stores GEOS-FP and MERRA-2 meteorology fields that have -been cropped to several nested domains. These data can be used to -perform high-resolution inversions with the `Integrated Methane -Inversion (IMI) `_ workflow. +portal stores GEOS-FP and MERRA-2 meteorology fields that have +been cropped to specific :ref:`nested-grid ` domains. +These data can be used to perform high-resolution inversions with the +`Integrated Methane Inversion (IMI) `_ +workflow. .. table:: Available nested-grid meteorology (2018 to present day) :align: center @@ -63,20 +64,21 @@ The data can be accessed by: - Direct HTTP or wget download - :ref:`Dry-run simulation ` -The GEOS-Chem Nested Input Data repository is also part of the `AWS +The GEOS-Chem Nested Input Data portal is also part of the `AWS Open Data Sponsorship Program `_. -.. _gcid-special-repos-gcap2: +.. _gcid-special-portals-gcap2: -======================================== -GCAP2 meteorology hosted at U. Rochester -======================================== +=========================================== +GCAP 2.0 meteorology hosted at U. Rochester +=========================================== The `atmos.earth.rochester.edu -`_ repository -(maintained by Lee Murray at the University of Rochester) contains the -GCAP 2.0 meteorological data inputs for use with GEOS-Chem simulations. +`_ portal +(curated by Lee Murray at the University of Rochester) contains the +GCAP 2.0 meteorological data inputs for use with GEOS-Chem +simulations. The data can be accessed by: diff --git a/docs/source/gcclassic-user-guide/input-overview.rst b/docs/source/gcclassic-user-guide/input-overview.rst deleted file mode 100644 index 28352f3..0000000 --- a/docs/source/gcclassic-user-guide/input-overview.rst +++ /dev/null @@ -1,228 +0,0 @@ -.. _input-overview: - -################################ -Input data for GEOS-Chem Classic -################################ - -GEOS-Chem Classic reads (via `HEMCO `_) -several data files from disk during a simulation. These can be -grouped into the following categories: - -#. :ref:`init-cond` (aka :ref:`restart-files`) -#. :ref:`chem-inputs` -#. :ref:`emis-inputs` -#. :ref:`met` - -============ -Data portals -============ - -Input data files for GEOS-Chem can be downloaded from one of the -following portals: - -.. option:: WashU - - The primary data portal for GEOS-Chem, - `geoschemdata.wustl.edu `_ - - The WashU data portal may be unavailable at times due to - regularly-scheduled maintenance periods. Please check the - `WashU IT status page `_ for more - information. - -.. option:: Amazon - - GEOS-Chem data on the Amazon cloud, `s3://gcgrid - `_. You can - browse the contents of the data via the - `AWS S3 Explorer `_. - - .. 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 - `_. - -.. option:: Rochester - - Portal for the GCAP 2.0 meteorological data files, - `atmos.earth.rochester.edu - `_ - -.. _init-cond: - -============================= -Initial conditions input data -============================= - -Initial conditions include: - -- Initial species concentrations (aka :ref:`restart-files`) used to - start a GEOS-Chem simulation. - -.. table:: - :align: center - - +--------------------------------------------------+---------------------+ - | Download method | From portals | - +==================================================+=====================+ - | :ref:`Dry run simulation ` | :option:`WashU` | - | | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Run :ref:`bashdatacatalog ` | :option:`WashU` | - | on the :file:`InitialConditions.csv` file [1]_ | | - +--------------------------------------------------+---------------------+ - | Direct data download (:program:`FTP` or | :option:`WashU` | - | :program:`wget`) | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Direct data download | :option:`Amazon` | - | (:program:`AWS S3 Explorer`) [2]_ | | - +--------------------------------------------------+---------------------+ - | Globus, use endpoint **GEOS-Chem data (WashU)** | :option:`WashU` | - +--------------------------------------------------+---------------------+ - -.. rubric:: Notes - -.. [1] We provide :file:`InitialConditions.csv` files (for each - GEOS-Chem version since 13.0.0) at our `input-data-catalogs - `_ Github repository. -.. [2] Direct link: `s3.amazonaws.com/gcgrid/index.html `_ - -.. _chem-inputs: - -==================== -Chemistry input data -==================== - -Chemistry input data includes: - -- Quantum yields and cross sections for photolysis using either ``Cloud-J`` or legacy ``FAST-JX`` -- Climatology data for :program:`Linoz` -- Boundary conditions for :program:`UCX` stratospheric chemistry routines - -.. table:: - :align: center - - +--------------------------------------------------+---------------------+ - | Download method | From portals | - +==================================================+=====================+ - | :ref:`Dry run simulation ` | :option:`WashU` | - | | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Run :ref:`bashdatacatalog ` | :option:`WashU` | - | on the | | - | :file:`ChemistryInputs.csv` [3]_ | | - +--------------------------------------------------+---------------------+ - | Direct data download (:program:`FTP` or | :option:`WashU` | - | :program:`wget`) | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Direct data download | :option:`Amazon` | - | (:program:`AWS S3 Explorer`) [2]_ | | - +--------------------------------------------------+---------------------+ - | Globus, use endpoint **GEOS-Chem data (WashU)** | :option:`WashU` | - +--------------------------------------------------+---------------------+ - -.. rubric:: Notes - -.. [3] We provide :file:`ChemistryInputs.csv` files (for each - GEOS-Chem version since 13.0.0) at our `input-data-catalogs - `_ Github repository. - -.. _emis-inputs: - -==================== -Emissions input data -==================== - -Emissions input data includes the following data: - -- Emissions inventories -- Input data for HEMCO Extensions -- Input data for GEOS-Chem specialty simulations -- Scale factors -- Mask definitions -- Surface boundary conditions -- Leaf area indices -- Land cover map - -.. table:: - :align: center - - +--------------------------------------------------+---------------------+ - | Download method | From portals | - +==================================================+=====================+ - | :ref:`Dry run simulation ` | :option:`WashU` | - | | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Run :ref:`bashdatacatalog ` | :option:`WashU` | - | on the :file:`EmissionsInputs.csv` file [4]_ | | - +--------------------------------------------------+---------------------+ - | Direct data download (:program:`FTP` or | :option:`WashU` | - | :program:`wget`) | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Direct data download | :option:`Amazon` | - | (:program:`AWS S3 Explorer`) [2]_ | | - +--------------------------------------------------+---------------------+ - | Globus, use endpoint **GEOS-Chem data (WashU)** | :option:`WashU` | - +--------------------------------------------------+---------------------+ - -.. rubric:: Notes - -.. [4] We provide :file:`EmissionsInputs.csv` files (for each - GEOS-Chem version since 13.0.0) at our `input-data-catalogs - `_ Github repository. - -.. _met: - -====================== -Meteorology input data -====================== - -:ref:`As described previously `, GEOS-Chem Classic -be driven by the following meteorology products: - -#. `MERRA-2 `_ -#. `GEOS-FP `_ -#. `GCAP 2.0 `_ - -.. attention:: - - We are still evaluating GEOS-Chem with the new NASA GEOS-IT - meterorology product. For the time being, you should use one of - the other meteorology options. - -.. table:: - :align: center - - +--------------------------------------------------+---------------------+ - | Download method | From portals | - +==================================================+=====================+ - | :ref:`Dry run simulation ` | :option:`WashU` | - | | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Run :ref:`bashdatacatalog ` | :option:`WashU` | - | on the :file:`MeteorologyInputs.csv` file [5]_ | | - +--------------------------------------------------+---------------------+ - | Direct data download (:program:`FTP` or | :option:`WashU` | - | :program:`wget`) | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Direct data download | :option:`Amazon` | - | (:program:`AWS S3 Explorer`) [2]_ | | - +--------------------------------------------------+---------------------+ - | Globus, use endpoint **GEOS-Chem data (WashU)** | :option:`WashU` | - +--------------------------------------------------+---------------------+ - -.. rubric:: Notes - -.. [5] We provide :file:`MeteorologyInputs.csv` files (for each - GEOS-Chem version since 13.0.0) at our `input-data-catalogs - `_ Github repository. diff --git a/docs/source/gcclassic-user-guide/restart-files-gc.rst b/docs/source/gcclassic-user-guide/restart-files-gc.rst index c4e96ee..20a97fe 100644 --- a/docs/source/gcclassic-user-guide/restart-files-gc.rst +++ b/docs/source/gcclassic-user-guide/restart-files-gc.rst @@ -134,8 +134,7 @@ Where can I get a restart file for my simulation? GEOS-Chem Classic :ref:`run directories ` are configured to use sample GEOS-Chem restart files in :program:`netCDF` format. These -files are available for download at the :option:`WashU` and -:option:`Amazon` data portals. +files are available for download at the :ref:`gcid-data` portal. .. tip:: diff --git a/docs/source/gcclassic-user-guide/restart-files-what.rst b/docs/source/gcclassic-user-guide/restart-files-what.rst index 1a845a6..1569345 100644 --- a/docs/source/gcclassic-user-guide/restart-files-what.rst +++ b/docs/source/gcclassic-user-guide/restart-files-what.rst @@ -4,8 +4,9 @@ What is a restart file? ####################### -Restart files contain the initial conditions (cf. :ref:`init-cond`) -for a GEOS-Chem simulation. GEOS-Chem simulations need two restart files. +Restart files contain species concentrations, as well as other +quantities that are needed to initialize GEOS-Chem simulations. +GEOS-Chem simulations use two separate restart files. .. option:: GEOSChem.Restart.YYYYMMDD_hhmmz.nc4 @@ -31,7 +32,7 @@ for a GEOS-Chem simulation. GEOS-Chem simulations need two restart files. **Description:** The :ref:`HEMCO restart file `. HEMCO archives certain quantities (mostly pertaining to soil NOx - and biogenic emissions) in order to facilitate long GEOS-Chem + and biogenic emissions in order to facilitate long GEOS-Chem simulations with several run stages. HEMCO restart files are created in the :option:`Restarts/` diff --git a/docs/source/gcclassic-user-guide/run-checklist.rst b/docs/source/gcclassic-user-guide/run-checklist.rst index 3475d4f..e55712c 100644 --- a/docs/source/gcclassic-user-guide/run-checklist.rst +++ b/docs/source/gcclassic-user-guide/run-checklist.rst @@ -55,14 +55,15 @@ Each-time setup .. attention:: - Prior to running with :option:`GEOS-FP` meteorology, be aware + Prior to running with GEOS-FP meteorology, be aware that it is an operational (i.e. evolving) product that is subject to assimilation system updates. - On the other hand, the :option:`MERRA-2` meterology is a 40+ + On the other hand, the MERRA-2 meterology is a 40+ year reanalysis product performed with a "frozen" version of the - NASA GEOS assimilation system. Thus, :option:`MERRA-2` is - preferable for studies ranging over multiple years or decades. + NASA GEOS assimilation system. Thus, `MERRA-2 + `_ is preferable for studies + ranging over multiple years or decades. #. :ref:`Configure and build ` the source code into an executable file. |br| diff --git a/docs/source/gcclassic-user-guide/run-speedup.rst b/docs/source/gcclassic-user-guide/run-speedup.rst index caaf9d1..9c41e9d 100644 --- a/docs/source/gcclassic-user-guide/run-speedup.rst +++ b/docs/source/gcclassic-user-guide/run-speedup.rst @@ -146,7 +146,7 @@ fields. The overhead in reading and regridding these global fields can significantly impact your simulation. Instead, consider cropping high-resolution meteorology fields to the extent of your nested domain. This can easily be done with the netCDF operators or the Climate Data -Operators; see our :ref:`netcdf-guide` supplemental guide for more +Operators; see our :ref:`ncguide` supplemental guide for more information. .. _run-speedup-nested-buffer: diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index 09a2f03..b5229c8 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit 09a2f03cd85a36f60b7333a0d744810116ce0820 +Subproject commit b5229c83cac0bfa7e128fdd2315492cafb973d0a diff --git a/docs/source/getting-started/disk-space.rst b/docs/source/getting-started/disk-space.rst index 74bb30c..faa9f5a 100644 --- a/docs/source/getting-started/disk-space.rst +++ b/docs/source/getting-started/disk-space.rst @@ -6,7 +6,7 @@ Disk space requirements The following sections will help you assess how much disk space you will need on your server to store GEOS-Chem Classic :ref:`input data -` and :ref:`output data `. +` and :ref:`output data `. .. _req-hard-disk-limits: @@ -24,8 +24,8 @@ information. Emissions input fields ---------------------- -Please see our :ref:`Emissions input data ` section for -more information. +Please see our :ref:`Emissions input data ` +section for more information. .. _req-hard-disk-met: @@ -101,7 +101,7 @@ sections. `_; #. Direct access from the `Amazon data portal using AWS S3 Explorer `_. -Also see our :ref:`input-overview` for more data download options. +Also see our :ref:`data` chapter for more data download options. .. _data-generated-by-geos-chem: diff --git a/docs/source/getting-started/quick-start.rst b/docs/source/getting-started/quick-start.rst index 6bc10b6..2fd219a 100644 --- a/docs/source/getting-started/quick-start.rst +++ b/docs/source/getting-started/quick-start.rst @@ -1,3 +1,7 @@ +.. |br| raw:: html + +
+ .. _quick: ################ @@ -119,8 +123,8 @@ simulations follow the same pattern as the examples shown below. provide :ref:`registration information `. Please answer all of the questions, as it will help us to keep track of GEOS-Chem usage worldwide. We will also add your - information to the `GEOS-Chem People and Projects web page - `_. + information to the `GEOS-Chem Users web page + `_. .. _quick-load: @@ -209,8 +213,8 @@ where the error happened and why. $ cmake . -DCMAKE_BUILD_TYPE=Debug -See the :ref:`GEOS-Chem documentation ` for more -information on configuration options. +:ref:`Click here ` for more information on +configuration options. .. _quick-cmp-inst: @@ -226,7 +230,7 @@ with the :literal:`-j` flag from the :file:`build/` directory: .. code-block:: console - # cd /path/to/gc_4x5_merra2_fullchem/build # Skip if you are already here + $ cd /path/to/gc_4x5_merra2_fullchem/build # Skip if you are already here $ make -j Upon successful compilation, install the compiled executable to your @@ -278,7 +282,39 @@ You should review these files before starting a simulation: - :ref:`HEMCO_Config.rc ` - Controls which emissions inventories and other non-emissions data - will be read from disk (via `HEMCO `_). + will be read from disk (via `HEMCO + `_). + +.. attention:: + + If you wish to spin up a GEOS-Chem simulation with a restart file + that has (1) missing species or (2) a timestamp that does not + match the start date in :ref:`geoschem_config.yml `, + simply change the time cycle flag for the :literal:`SPC_` entry in + :ref:`HEMCO_Config.rc ` from + + .. code-block:: console + + * SPC_ ... $YYYY/$MM/$DD/$HH EFYO xyz 1 * - 1 1 + + to + + .. code-block:: console + + * SPC_ ... $YYYY/$MM/$DD/$HH CYS xyz 1 * - 1 1 + + This will direct HEMCO to read the closest date + available (:literal:`C`), to use the simulation year + (:literal:`Y`), and to skip any species (:literal:`S`) not found + in the restart file. + + Skipped species will be assigned the initial concentration + (units: :math:`mol\ mol^{-1}` w/r/t dry air) specified by its + :option:`BackgroundVV` entry in :ref:`species_database.yml + `. If the species does not have a + :option:`BackgroundVV` value specified, then its initial + concentration will be set to :math:`1.0{\times}10^{-20}` + instead. Please see our :ref:`customguide` Supplemental Guide to learn how you can customize your simulation by activating alternate science options @@ -293,16 +329,18 @@ in your simulations. Before you can run your GEOS-Chem Classic simulation, you must first :ref:`download the required input data `. These data include: -- Meteorological fields (e.g. GEOS-FP, MERRA-2, GEOS-IT, or GCAP2) -- Emissions inventories -- Inputs for GEOS-Chem modules (e.g. Cloud-J) +- :ref:`Meteorological fields ` (e.g. GEOS-FP, + MERRA-2, GEOS-IT, or GCAP2) +- :ref:`Emissions inventories ` +- :ref:`Inputs for GEOS-Chem modules (e.g. Cloud-J) ` +- :ref:`Initial conditions for starting GEOS-Chem simulations ` .. tip:: If your institution has several GEOS-Chem users, then someone may have already downloaded these data for you. If this is the case, you may :ref:`start running your your GEOS-Chem Classic simulation - `. + ` right away. The easiest way to download data is to perform a :ref:`dry-run simulation `. This is a GEOS-Chem Classic simulation that @@ -321,15 +359,7 @@ list of data files to be downloaded. Once the dry-run simulation has finished, use the :file:`download_data.py` file (included in your run directory) to -:ref:`download the required data `. Type: - -.. code-block:: console - - $ ./download_data.py log.dryrun --washu - -This will download data from the :option:`WashU` data portal. You -may also download from the :option:`Amazon` or :option:`Rochester` -data portals. +:ref:`download the required data `. .. note:: @@ -337,6 +367,33 @@ data portals. Mamba environment containing a version of Python before running the :file:`download.data.py` script. Ask your sysadmin. +To start the data download, type: + +.. code-block:: console + + $ ./download_data.py log.dryrun geoschem+http + +This will download data from the :ref:`GEOS-Chem Input Data ` +portal using the HTTP data transfer protocol. + +.. tip:: + + If you have `AWS CLI (command line interface) + `_ installed on your system, you + can use this command instead: + + .. code-block:: console + + $ ./download_data.py log.dryrun geoschem+aws + + This will use the AWS CLI data download protocol instead, which + should be faster than regular HTTP connections. This is the + command you should use if you are running GEOS-Chem Classic in an + AWS EC2 instance. + +We also maintain :ref:`separate data portals ` +for special nested-grid domains as well as the GCAP 2.0 meteorology. + For more information about dry-run simulations, please see our :ref:`dry-run` chapter. diff --git a/docs/source/supplemental-guides/nested-grid-guide.rst b/docs/source/supplemental-guides/nested-grid-guide.rst index 2cd2fa8..b8524ce 100644 --- a/docs/source/supplemental-guides/nested-grid-guide.rst +++ b/docs/source/supplemental-guides/nested-grid-guide.rst @@ -238,11 +238,20 @@ simulations on different nested domains. How can I find which data are available for nested grid simulations? -------------------------------------------------------------------- -You will download meteorology and emissions data from one of the -:ref:`GEOS-Chem data portals `. You can browse the -WashU data portal (`http://geoschemdata.wustl.edu/ExtData -`_) to see if the data you need -are available. +You can browse the contents of the GEOS-Chem data portals by pointing +your browser to one of the following links: + +- :ref:`GEOS-Chem Input Data ` + + - https://geos-chem.s3.amazonaws.com/index.html + +- :ref:`GEOS-Chem Nested Input Data ` + + - https://gcgrid.s3.amazonaws.com/index.html + +- :ref:`GCAP 2.0 meteorology @ U. Rochester ` + + - http://atmos.earth.rochester.edu/input/gc/ExtData/ .. _nestgrid-faq-errors: From 09a5db3ec202fac6c32fb0ae2760c47594242c40 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 5 Nov 2024 12:11:37 -0500 Subject: [PATCH 39/44] Update dry-run download; Add warnings about GEOS-FP docs/source/gcclassic-user-guide/dry-run-download.rst - Reduce indentation for GEOS-Chem data portals & access methods - Update log.dryrun.unique output to remove obsolete file listings docs/source/gcclassic-user-guide/run-checklist.rst docs/source/help-and-reference/known-bugs.rst - Add "important" box with warning about GEOS-FP convection switch Signed-off-by: Bob Yantosca --- .../gcclassic-user-guide/dry-run-download.rst | 97 ++++++++++--------- .../gcclassic-user-guide/run-checklist.rst | 25 ++++- docs/source/help-and-reference/known-bugs.rst | 17 ++++ 3 files changed, 91 insertions(+), 48 deletions(-) diff --git a/docs/source/gcclassic-user-guide/dry-run-download.rst b/docs/source/gcclassic-user-guide/dry-run-download.rst index c818d63..ff93dee 100644 --- a/docs/source/gcclassic-user-guide/dry-run-download.rst +++ b/docs/source/gcclassic-user-guide/dry-run-download.rst @@ -47,31 +47,34 @@ Choose a data portal You can :ref:`download input data ` from any of the portals listed below. - .. list-table:: GEOS-Chem data portals and access methods - :header-rows: 1 - :align: center - - * - Portal - - S3 Explorer - - AWS CLI - - HTTP - - Globus - * - :ref:`GEOS-Chem Input Data ` |br| - (The main source of GEOS-Chem input data) - - Yes - - Yes - - Yes - - Yes - * - :ref:`gcid-special-portals-nested` - - Yes - - Yes - - Yes - - No - * - :ref:`gcid-special-portals-gcap2` - - No - - No - - Yes - - No +.. 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 ` |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: @@ -151,25 +154,31 @@ 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 --> /path/to/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 - /path/to/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/FJX_j2j.dat - /path/to/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/FJX_spec.dat - /path/to/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/dust.dat - /path/to/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/h2so4.dat - /path/to/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 diff --git a/docs/source/gcclassic-user-guide/run-checklist.rst b/docs/source/gcclassic-user-guide/run-checklist.rst index e55712c..8a9c639 100644 --- a/docs/source/gcclassic-user-guide/run-checklist.rst +++ b/docs/source/gcclassic-user-guide/run-checklist.rst @@ -55,16 +55,33 @@ Each-time setup .. attention:: - Prior to running with GEOS-FP meteorology, be aware - that it is an operational (i.e. evolving) product - that is subject to assimilation system updates. + Be aware that GEOS-FP meteorology is an operational + (i.e. evolving) product that is subject to assimilation + system updates. - On the other hand, the MERRA-2 meterology is a 40+ + On the other hand, the MERRA-2 meteorology is a 40+ year reanalysis product performed with a "frozen" version of the NASA GEOS assimilation system. Thus, `MERRA-2 `_ is preferable for studies ranging over multiple years or decades. + .. important:: + + The convection scheme used for GEOS-FP met generation changed + from RAS to Grell-Freitas with impact on GEOS-FP meteorology + files starting June 1, 2020, specifically enhanced vertical + transport. In addition, there is a bug in convective + precipitation flux following the switch where all values are + zero. While this bug is automatically fixed by computing fluxes + online for runs starting on or after June 1 2020, the fix + assumes meteorology year corresponds to simulation year. Due to + these issues we recommend splitting up GEOS-FP runs in time such + that a single simulation does not run across June + 1, 2020. Instead. set one run to stop on June 1 2020 and then + restart a new run from there. If you wish to use a GEOS-FP + meteorology year different from your simulation year please + create a GEOS-Chem GitHub issue for assistance. + #. :ref:`Configure and build ` the source code into an executable file. |br| |br| diff --git a/docs/source/help-and-reference/known-bugs.rst b/docs/source/help-and-reference/known-bugs.rst index 59debd7..e60eeeb 100644 --- a/docs/source/help-and-reference/known-bugs.rst +++ b/docs/source/help-and-reference/known-bugs.rst @@ -23,6 +23,23 @@ are currently unresolved. We hope to fix these in future releases. diagnostic collection may not be working as expected. We are currently investigating. +.. important:: + + The convection scheme used for GEOS-FP met generation changed + from RAS to Grell-Freitas with impact on GEOS-FP meteorology + files starting June 1, 2020, specifically enhanced vertical + transport. In addition, there is a bug in convective + precipitation flux following the switch where all values are + zero. While this bug is automatically fixed by computing fluxes + online for runs starting on or after June 1 2020, the fix + assumes meteorology year corresponds to simulation year. Due to + these issues we recommend splitting up GEOS-FP runs in time such + that a single simulation does not run across June + 1, 2020. Instead. set one run to stop on June 1 2020 and then + restart a new run from there. If you wish to use a GEOS-FP + meteorology year different from your simulation year please + create a GEOS-Chem GitHub issue for assistance. + ============================ Bugs that have been resolved ============================ From 765987a078c2d3714fdf33e43e9ab51bd00dd406 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 5 Nov 2024 12:30:49 -0500 Subject: [PATCH 40/44] Moved gcid-special-portals.rst to geos-chem-shared-docs/doc docs/source/gcclassic-user-guide/gcid-special-portals.rst - Moved to geos-chem-shared-docs/doc/gcid-special-portals.rst docs/source/gcclassic-user-guide/download-data.rst - Toctree now points to geoschem-shared-docs/doc/gcid-special-portals.rst docs/source/gcclassic/dry-run-run.rst - Add warning box about GEOS-FP convection switch docs/source/geos-chem-shared-docs - Submodule update to 54890ed Signed-off-by: Bob Yantosca --- .../gcclassic-user-guide/download-data.rst | 2 +- .../gcclassic-user-guide/dry-run-run.rst | 18 ++++ .../gcid-special-portals.rst | 86 ------------------- docs/source/geos-chem-shared-docs | 2 +- 4 files changed, 20 insertions(+), 88 deletions(-) delete mode 100644 docs/source/gcclassic-user-guide/gcid-special-portals.rst diff --git a/docs/source/gcclassic-user-guide/download-data.rst b/docs/source/gcclassic-user-guide/download-data.rst index bac52ca..df110f7 100644 --- a/docs/source/gcclassic-user-guide/download-data.rst +++ b/docs/source/gcclassic-user-guide/download-data.rst @@ -19,6 +19,6 @@ for your GEOS-Chem simulation. :maxdepth: 2 ../geos-chem-shared-docs/doc/gcid-portal-overview.rst - gcid-special-portals.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-run.rst b/docs/source/gcclassic-user-guide/dry-run-run.rst index b8ad155..8299112 100644 --- a/docs/source/gcclassic-user-guide/dry-run-run.rst +++ b/docs/source/gcclassic-user-guide/dry-run-run.rst @@ -26,6 +26,24 @@ files `: #. :option:`met_field`: Check if the meteorology setting (:option:`GEOS-FP`, :option:`MERRA2`, :option:`GCAP2`) is correct for your simulation. + + .. important:: + + The convection scheme used for GEOS-FP met generation changed + from RAS to Grell-Freitas with impact on GEOS-FP meteorology + files starting June 1, 2020, specifically enhanced vertical + transport. In addition, there is a bug in convective + precipitation flux following the switch where all values are + zero. While this bug is automatically fixed by computing fluxes + online for runs starting on or after June 1 2020, the fix + assumes meteorology year corresponds to simulation year. Due to + these issues we recommend splitting up GEOS-FP runs in time such + that a single simulation does not run across June + 1, 2020. Instead. set one run to stop on June 1 2020 and then + restart a new run from there. If you wish to use a GEOS-FP + meteorology year different from your simulation year please + create a GEOS-Chem GitHub issue for assistance. + #. :option:`root_data_dir`: Make sure that the path to :file:`ExtData` is correct. diff --git a/docs/source/gcclassic-user-guide/gcid-special-portals.rst b/docs/source/gcclassic-user-guide/gcid-special-portals.rst deleted file mode 100644 index 49e62b9..0000000 --- a/docs/source/gcclassic-user-guide/gcid-special-portals.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. |br| raw:: html - -
- -.. _gcid-special-portals: - -####################################### -Additional portals for meteorology data -####################################### - -As discussed in the previous chapter, the :ref:`GEOS-Chem Input -Data ` portal is the main source of input data for -:program:`GEOS-Chem Classic`, :program:`GCHP`, and the :program:`HEMCO -standalone model`. This portal contains the entire catalog -of emissions inventories, chemical inputs, initial conditions, and -most years of `GEOS-FP `_, -`MERRA-2 `_, and GEOS-IT meteorology. - -We also maintain two additional data portals for special data sets. - -.. _gcid-special-portals-nested: - -=========================== -GEOS-Chem Nested Input Data -=========================== - -.. attention:: - - We are still adding data to the GEOS-Chem Nested Input Data - portal. As of this writing (November 2024), not all data may - have been uploaded yet. We thank you for your patience. - -The `GEOS-Chem Nested Input data -`_ -portal stores GEOS-FP and MERRA-2 meteorology fields that have -been cropped to specific :ref:`nested-grid ` domains. -These data can be used to perform high-resolution inversions with the -`Integrated Methane Inversion (IMI) `_ -workflow. - -.. table:: Available nested-grid meteorology (2018 to present day) - :align: center - - +---------+--------------------------+-------------------------------+ - | Product | Horizontal resolution | Nested-grid domains | - +=========+==========================+===============================+ - | GEOS-FP | :math:`0.125^{\circ} | AF (Africa) |br| | - | | {\times}0.15625^{\circ}` | AS (Asia) |br| | - | | | EU (Europe) |br| | - | | | ME (Middle East) |br| | - | | | NA (North America) |br| | - | | | OC (Oceania) |br| | - | | | RU (Russia) |br| | - | | | SA (South America) | - +---------+--------------------------+-------------------------------+ - | MERRA-2 | :math:`0.5^{\circ} | AS (Asia) |br| | - | | {\times}0.625^{\circ}` | EU (Europe) |br| | - | | | NA (North America) |br| | - +---------+--------------------------+-------------------------------+ - -The data can be accessed by: - -- AWS S3 Explorer (https://s3.amazonaws.com/gcgrid/index.html) -- Direct HTTP or wget download -- :ref:`Dry-run simulation ` - -The GEOS-Chem Nested Input Data portal is also part of the `AWS -Open Data Sponsorship Program -`_. - -.. _gcid-special-portals-gcap2: - -=========================================== -GCAP 2.0 meteorology hosted at U. Rochester -=========================================== - -The `atmos.earth.rochester.edu -`_ portal -(curated by Lee Murray at the University of Rochester) contains the -GCAP 2.0 meteorological data inputs for use with GEOS-Chem -simulations. - -The data can be accessed by: - -- Direct HTTP or wget download (http://atmos.earth.rochester.edu/input/gc/ExtData/) -- :ref:`Dry run simulation ` diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index b5229c8..54890ed 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit b5229c83cac0bfa7e128fdd2315492cafb973d0a +Subproject commit 54890ed71c0cab6f82b2ace84516267bc96eb10c From b81423c86cc7165843a8d4c8761d7c21d8ca4f6c Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 5 Nov 2024 16:09:43 -0500 Subject: [PATCH 41/44] RTD update: Fixed more links/refs and text formatting issues docs/source/gcclassic-user-guide/compile-cmake.rst - Add proper indentation to a ".. note::" block docs/source/gcclassic-user-guide/rundir-carbon.rst docs/source/gcclassic-user-guide/rundir-fullchem.rst docs/source/getting-started/quick-start.rst - Add "important" box about GEOS-FP convection issue - Trimmed trailing whitespace docs/source/gcclassic-user-guide/dry-run-download.rst - Fixed incorrect portal name "geoschem-s3" -> "geoschem+s3" docs/source/geos-chem-shared-docs - Submodule update to cd0f4ad (fix broken links & refs) docs/source/help-and-reference/known-bugs.rst - Renamed link text to avoid a "duplicate link" warning docs/source/index.rst - Removed geos-chem-input-data-on-aws.rst from toctree, as this is now moved to geos-chem-shared-docs/doc/gcid-portal-overview.rst Signed-off-by: Bob Yantosca --- .../gcclassic-user-guide/compile-cmake.rst | 13 ++++++------- .../gcclassic-user-guide/dry-run-download.rst | 8 ++++---- .../gcclassic-user-guide/rundir-carbon.rst | 17 +++++++++++++++++ .../gcclassic-user-guide/rundir-fullchem.rst | 17 +++++++++++++++++ docs/source/geos-chem-shared-docs | 2 +- docs/source/getting-started/quick-start.rst | 17 +++++++++++++++++ docs/source/help-and-reference/known-bugs.rst | 2 +- docs/source/index.rst | 1 - 8 files changed, 63 insertions(+), 14 deletions(-) diff --git a/docs/source/gcclassic-user-guide/compile-cmake.rst b/docs/source/gcclassic-user-guide/compile-cmake.rst index 16bea85..96a294f 100644 --- 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 `_: diff --git a/docs/source/gcclassic-user-guide/dry-run-download.rst b/docs/source/gcclassic-user-guide/dry-run-download.rst index ff93dee..e2f964a 100644 --- a/docs/source/gcclassic-user-guide/dry-run-download.rst +++ b/docs/source/gcclassic-user-guide/dry-run-download.rst @@ -133,13 +133,13 @@ where: - :command:`wget` - HTTP -For example, to download data from the :ref:`dry-run-download-portal-gc` -portal using the AWS CLI download (which is faster than HTTP -download), use this command: +For example, to download data from the :ref:`GEOS-Chem Input Data +` portal using the AWS CLI download (which is faster than +HTTP download), use this command: .. code-block:: console - $ ./download_data.py log.dryrun geoschem-s3 + $ ./download_data.py log.dryrun geoschem+s3 .. note:: diff --git a/docs/source/gcclassic-user-guide/rundir-carbon.rst b/docs/source/gcclassic-user-guide/rundir-carbon.rst index 915e26b..7652873 100644 --- a/docs/source/gcclassic-user-guide/rundir-carbon.rst +++ b/docs/source/gcclassic-user-guide/rundir-carbon.rst @@ -136,6 +136,23 @@ simulation. We'll use the carbon gases simulation as an example. followed by :command:`ENTER`. |br| |br| + .. important:: + + The convection scheme used for GEOS-FP met generation changed + from RAS to Grell-Freitas with impact on GEOS-FP meteorology + files starting June 1, 2020, specifically enhanced vertical + transport. In addition, there is a bug in convective + precipitation flux following the switch where all values are + zero. While this bug is automatically fixed by computing fluxes + online for runs starting on or after June 1 2020, the fix + assumes meteorology year corresponds to simulation year. Due to + these issues we recommend splitting up GEOS-FP runs in time such + that a single simulation does not run across June + 1, 2020. Instead. set one run to stop on June 1 2020 and then + restart a new run from there. If you wish to use a GEOS-FP + meteorology year different from your simulation year please + create a GEOS-Chem GitHub issue for assistance. + #. The next menu will prompt you for the horizontal resolution that you wish to use: diff --git a/docs/source/gcclassic-user-guide/rundir-fullchem.rst b/docs/source/gcclassic-user-guide/rundir-fullchem.rst index 8896a84..b5b0ebb 100644 --- a/docs/source/gcclassic-user-guide/rundir-fullchem.rst +++ b/docs/source/gcclassic-user-guide/rundir-fullchem.rst @@ -138,6 +138,23 @@ GEOS-Chem full-chemistry simulation. :command:`1` followed by :command:`ENTER`. |br| |br| + .. important:: + + The convection scheme used for GEOS-FP met generation changed + from RAS to Grell-Freitas with impact on GEOS-FP meteorology + files starting June 1, 2020, specifically enhanced vertical + transport. In addition, there is a bug in convective + precipitation flux following the switch where all values are + zero. While this bug is automatically fixed by computing fluxes + online for runs starting on or after June 1 2020, the fix + assumes meteorology year corresponds to simulation year. Due to + these issues we recommend splitting up GEOS-FP runs in time such + that a single simulation does not run across June + 1, 2020. Instead. set one run to stop on June 1 2020 and then + restart a new run from there. If you wish to use a GEOS-FP + meteorology year different from your simulation year please + create a GEOS-Chem GitHub issue for assistance. + #. The next menu will prompt you for the horizontal resolution that you wish to use: diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index 54890ed..cd0f4ad 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit 54890ed71c0cab6f82b2ace84516267bc96eb10c +Subproject commit cd0f4ad1dd13648c3fe9bf8bb13c7bf5ef517125 diff --git a/docs/source/getting-started/quick-start.rst b/docs/source/getting-started/quick-start.rst index 2fd219a..da46b40 100644 --- a/docs/source/getting-started/quick-start.rst +++ b/docs/source/getting-started/quick-start.rst @@ -126,6 +126,23 @@ simulations follow the same pattern as the examples shown below. information to the `GEOS-Chem Users web page `_. +.. important:: + + The convection scheme used for GEOS-FP met generation changed + from RAS to Grell-Freitas with impact on GEOS-FP meteorology + files starting June 1, 2020, specifically enhanced vertical + transport. In addition, there is a bug in convective + precipitation flux following the switch where all values are + zero. While this bug is automatically fixed by computing fluxes + online for runs starting on or after June 1 2020, the fix + assumes meteorology year corresponds to simulation year. Due to + these issues we recommend splitting up GEOS-FP runs in time such + that a single simulation does not run across June + 1, 2020. Instead. set one run to stop on June 1 2020 and then + restart a new run from there. If you wish to use a GEOS-FP + meteorology year different from your simulation year please + create a GEOS-Chem GitHub issue for assistance. + .. _quick-load: ======================== diff --git a/docs/source/help-and-reference/known-bugs.rst b/docs/source/help-and-reference/known-bugs.rst index e60eeeb..2c228f6 100644 --- a/docs/source/help-and-reference/known-bugs.rst +++ b/docs/source/help-and-reference/known-bugs.rst @@ -44,4 +44,4 @@ are currently unresolved. We hope to fix these in future releases. Bugs that have been resolved ============================ -These `bug reports (on GitHub) `_ have been resolved. +These `bugs (reported on GitHub) `_ have been resolved. diff --git a/docs/source/index.rst b/docs/source/index.rst index 7a95fae..e8895ed 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -84,7 +84,6 @@ modifications to GEOS-Chem Classic source code. geos-chem-shared-docs/supplemental-guides/parallel-guide.rst supplemental-guides/nested-grid-guide.rst geos-chem-shared-docs/supplemental-guides/using-kpp-with-gc.rst - geos-chem-shared-docs/supplemental-guides/geos-chem-input-data-on-aws.rst geos-chem-shared-docs/supplemental-guides/related-docs.rst .. toctree:: From 694e24ffa1e864fda0a203748f42f7ce96da0606 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 6 Nov 2024 16:44:31 -0500 Subject: [PATCH 42/44] Update warning boxes about GEOS-FP in dry-run & rundir doc docs/source/gcclassic-user-guide/dry-run-run.rst docs/source/gcclassic-user-guide/rundir-carbon.rst docs/source/gcclassic-user-guide/rundir-fullchem.rst - Edit the "important" box with the warning about GEOS-FP convection to make it more clear that the user should choose MERRA-2 to avoid discontinuities across June 1, 2020. docs/source/geos-chem-shared-docs - Submodule update, now link to GCClassic & HEMCO dry-run-instructions from the GEOS-Chem Input Data portal documentation --- .../gcclassic-user-guide/dry-run-run.rst | 22 +++++++------------ .../gcclassic-user-guide/rundir-carbon.rst | 18 +++++---------- .../gcclassic-user-guide/rundir-fullchem.rst | 18 +++++---------- docs/source/geos-chem-shared-docs | 2 +- 4 files changed, 21 insertions(+), 39 deletions(-) diff --git a/docs/source/gcclassic-user-guide/dry-run-run.rst b/docs/source/gcclassic-user-guide/dry-run-run.rst index 8299112..3a39fa9 100644 --- a/docs/source/gcclassic-user-guide/dry-run-run.rst +++ b/docs/source/gcclassic-user-guide/dry-run-run.rst @@ -29,20 +29,14 @@ files `: .. important:: - The convection scheme used for GEOS-FP met generation changed - from RAS to Grell-Freitas with impact on GEOS-FP meteorology - files starting June 1, 2020, specifically enhanced vertical - transport. In addition, there is a bug in convective - precipitation flux following the switch where all values are - zero. While this bug is automatically fixed by computing fluxes - online for runs starting on or after June 1 2020, the fix - assumes meteorology year corresponds to simulation year. Due to - these issues we recommend splitting up GEOS-FP runs in time such - that a single simulation does not run across June - 1, 2020. Instead. set one run to stop on June 1 2020 and then - restart a new run from there. If you wish to use a GEOS-FP - meteorology year different from your simulation year please - create a GEOS-Chem GitHub issue for assistance. + The convection scheme used for GEOS-FP met generation changed + from RAS to Grell-Freitas with impact on GEOS-FP meteorology + files starting June 1, 2020. For this reason we recommend + using MERRA-2 instead of GEOS-FP if running a simulation + across June 1, 2020 to avoid unexpected + discontinuities. Additional information about the impact of + the convection change is at `geoschem/geos-chem#1409 + `_. #. :option:`root_data_dir`: Make sure that the path to :file:`ExtData` is correct. diff --git a/docs/source/gcclassic-user-guide/rundir-carbon.rst b/docs/source/gcclassic-user-guide/rundir-carbon.rst index 7652873..199e73f 100644 --- a/docs/source/gcclassic-user-guide/rundir-carbon.rst +++ b/docs/source/gcclassic-user-guide/rundir-carbon.rst @@ -140,18 +140,12 @@ simulation. We'll use the carbon gases simulation as an example. The convection scheme used for GEOS-FP met generation changed from RAS to Grell-Freitas with impact on GEOS-FP meteorology - files starting June 1, 2020, specifically enhanced vertical - transport. In addition, there is a bug in convective - precipitation flux following the switch where all values are - zero. While this bug is automatically fixed by computing fluxes - online for runs starting on or after June 1 2020, the fix - assumes meteorology year corresponds to simulation year. Due to - these issues we recommend splitting up GEOS-FP runs in time such - that a single simulation does not run across June - 1, 2020. Instead. set one run to stop on June 1 2020 and then - restart a new run from there. If you wish to use a GEOS-FP - meteorology year different from your simulation year please - create a GEOS-Chem GitHub issue for assistance. + files starting June 1, 2020. For this reason we recommend + using MERRA-2 instead of GEOS-FP if running a simulation + across June 1, 2020 to avoid unexpected + discontinuities. Additional information about the impact of + the convection change is at `geoschem/geos-chem#1409 + `_. #. The next menu will prompt you for the horizontal resolution that you wish to use: diff --git a/docs/source/gcclassic-user-guide/rundir-fullchem.rst b/docs/source/gcclassic-user-guide/rundir-fullchem.rst index b5b0ebb..d02bd2e 100644 --- a/docs/source/gcclassic-user-guide/rundir-fullchem.rst +++ b/docs/source/gcclassic-user-guide/rundir-fullchem.rst @@ -142,18 +142,12 @@ GEOS-Chem full-chemistry simulation. The convection scheme used for GEOS-FP met generation changed from RAS to Grell-Freitas with impact on GEOS-FP meteorology - files starting June 1, 2020, specifically enhanced vertical - transport. In addition, there is a bug in convective - precipitation flux following the switch where all values are - zero. While this bug is automatically fixed by computing fluxes - online for runs starting on or after June 1 2020, the fix - assumes meteorology year corresponds to simulation year. Due to - these issues we recommend splitting up GEOS-FP runs in time such - that a single simulation does not run across June - 1, 2020. Instead. set one run to stop on June 1 2020 and then - restart a new run from there. If you wish to use a GEOS-FP - meteorology year different from your simulation year please - create a GEOS-Chem GitHub issue for assistance. + files starting June 1, 2020. For this reason we recommend + using MERRA-2 instead of GEOS-FP if running a simulation + across June 1, 2020 to avoid unexpected + discontinuities. Additional information about the impact of + the convection change is at `geoschem/geos-chem#1409 + `_. #. The next menu will prompt you for the horizontal resolution that you wish to use: diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index cd0f4ad..14adeb4 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit cd0f4ad1dd13648c3fe9bf8bb13c7bf5ef517125 +Subproject commit 14adeb4d8a9cfbdebd688033e4c22dd034ac105b From 2d8b6e06b29a4f6aba2ab42e69f6d27fd53c72da Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 7 Nov 2024 11:25:31 -0500 Subject: [PATCH 43/44] Submod update: Merge GC PR #2555 & HEMCO PR #295 (14.5.0 dry run) This commit informs the GCClassic superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: a8bb552d1 Merge PR #2555 (Dry run updates for GEOS-Chem Classic 14.5.0) e9d951f Merge PR #295 (Add HEMCO-standalone dry run scripts) This PR updates the subroutine hashes to GEOS-Chem and HEMCO submodules, which now have updates for the GEOS-Chem 14.5.0 and HEMCO 3.10.0 dry run simulations. Signed-off-by: Bob Yantosca --- src/GEOS-Chem | 2 +- src/HEMCO | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/GEOS-Chem b/src/GEOS-Chem index 51d306d..a8bb552 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit 51d306dade21a6c36e5537224b7c533b5489667c +Subproject commit a8bb552d138b6d1fa684a2fa187e3a9a754caf2e diff --git a/src/HEMCO b/src/HEMCO index a3d0c9a..e9d951f 160000 --- a/src/HEMCO +++ b/src/HEMCO @@ -1 +1 @@ -Subproject commit a3d0c9a280672ac1c40e3f322651f23b8196fa4c +Subproject commit e9d951fd702a82d76ba2a73653b74e7b1eae8e4c From 09b682209bb24da7328b508f77204f67353ced9c Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 7 Nov 2024 15:15:55 -0500 Subject: [PATCH 44/44] Update version numbers to 14.5.0 CHANGELOG.md CMakeLists.txt docs/source/conf.py - Updated version number to 14.5.0, in anticipation of the GEOS-Chem Classic 14.5.0 release Signed-off-by: Bob Yantosca --- CHANGELOG.md | 2 +- CMakeLists.txt | 2 +- docs/source/conf.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 476753b..2c59ac8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,7 @@ 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-07 ### Changed - Updated `docs/source/geos-chem-shared-docs/spack/packages.yaml` to use GCC 12.2.0 compilers - Updated documentation for version 14.5.0 diff --git a/CMakeLists.txt b/CMakeLists.txt index c193cfd..0446acd 100644 --- 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/source/conf.py b/docs/source/conf.py index 1c46044..6457dec 100644 --- 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 ---------------------------------------------------