From 3dee2ff6e6c5f771ec017306e2df81e62d2d3d91 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 3 Jul 2024 15:39:31 -0400 Subject: [PATCH 01/41] GEOS-Chem submod update: Merge PR #2359 (Per-species KPP error tol.) This commit informs the GCHP 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/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index dd859ee45..4288f0d1d 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit dd859ee45494af71d29f0877f359ff571f697b67 +Subproject commit 4288f0d1d89d6d4c42f71bc0c90280812aa4cfd8 From 7065c1caceec054d84c016c95776ee668262bc66 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 8 Jul 2024 13:58:57 -0400 Subject: [PATCH 02/41] GEOS-Chem submod update: Merge hotfix from PR #2363 atop PR #2359 This commit informs the GCHP 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/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 4288f0d1d..e61a51064 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 4288f0d1d89d6d4c42f71bc0c90280812aa4cfd8 +Subproject commit e61a51064a94246698d7a844239617b1b802ec8f From dfbd38dcaf71c74be3035b886838ae86e9132f5c Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 16 Jul 2024 12:33:09 -0400 Subject: [PATCH 03/41] GEOS-Chem submod update: Merge PR #2315 (complexSOA bug fixes) This commit informs the GCHP 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/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index e61a51064..ef2ea60e7 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit e61a51064a94246698d7a844239617b1b802ec8f +Subproject commit ef2ea60e7caab0784ba139f8e5083f2f77982a6c From 136fa7051c2a874af74341a6e8d27da373b5c61e Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Fri, 26 Jul 2024 09:50:29 -0400 Subject: [PATCH 04/41] GEOS-Chem submod update: Merge PR #2398 (Uncomment cations for HETP) This commit informs the GCHP 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/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 0a172283d..e29a4c928 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 0a172283d089111e17fc45c0dd0a57da563b7bdc +Subproject commit e29a4c9289b01482f9d1c22528eac76b73023c43 From 976ff70e6b89d3e6abae443ccf2e8dab8639f3dd Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 1 Aug 2024 14:28:57 -0400 Subject: [PATCH 05/41] 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 GCHP 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/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index e29a4c928..0a392d465 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit e29a4c9289b01482f9d1c22528eac76b73023c43 +Subproject commit 0a392d465fd194135806f1a120c05697d60cf382 From 548c753228301a819b5bbe6eaf743f5eff23bca9 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 5 Aug 2024 15:50:45 -0400 Subject: [PATCH 06/41] 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/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 0a392d465..acd335486 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 0a392d465fd194135806f1a120c05697d60cf382 +Subproject commit acd3354861ce7c7b1c2d34833361e57dc39f8ff9 From 8588f5e7a13f8160247edda11a798d95bbf0ce3a Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 15 Aug 2024 10:31:57 -0400 Subject: [PATCH 07/41] GEOS-Chem submod update: PR #2425 post-merge fix (CHANGELOG.md update_ This commit informs the GCHP 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/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 000205c86..8f0a16767 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 000205c86ade5f906f17a628856d8620736111b9 +Subproject commit 8f0a1676789f001d8a1d888905a734cf88f0eb13 From 86bcfa964f80f1c72242638a5a36dbe092f7e6e6 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 20 Aug 2024 11:59:40 -0400 Subject: [PATCH 08/41] GEOS-Chem & HEMCO updates: Merge PR #2318, PR #284, PR #285 This commit informs the GCHP 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/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO | 2 +- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO b/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO index 41605bda8..d0d5fca8c 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO +++ b/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO @@ -1 +1 @@ -Subproject commit 41605bda8a89d96f441cb8eb90f3d3c8b21f2b71 +Subproject commit d0d5fca8ceab6f59aa98d6e65952dcfc9f3aef6e diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 8f0a16767..586260f10 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 8f0a1676789f001d8a1d888905a734cf88f0eb13 +Subproject commit 586260f101557396c49590931a5838a2374b4528 From da8ea127b860dd1a279c2e6373fd14f242a613ad Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 28 Aug 2024 11:13:02 -0400 Subject: [PATCH 09/41] GEOS-Chem submod update: Merge PR #2428 (vdiff) and PR #2144 (drydep) This commit informs the GCHP 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/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 586260f10..3073aff2e 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 586260f101557396c49590931a5838a2374b4528 +Subproject commit 3073aff2e63d1073f7e63acaa9dba293dbc0553a From c3bfc98758f6b52ef77031527a66f22899698fcc Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 29 Aug 2024 14:17:52 -0400 Subject: [PATCH 10/41] RTD update: Update compiler to 12.2.0; Update page formatting docs/source/geos-chem-shared-docs - Changed compiler from gcc@10.2.0 to gcc@12.2.0 in guides docs/source/user-configuration-files.rst docs/source/user-guide/rundir-init.rst docs/source/user-guide/running.rst - Updated formatting and fixed issues flagged by Sphinx Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- .../source/user-guide/configuration-files.rst | 134 ++++++----- docs/source/user-guide/rundir-init.rst | 91 +++++--- docs/source/user-guide/running.rst | 217 ++++++++++++------ 4 files changed, 277 insertions(+), 167 deletions(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index ce3c86acc..a68981bec 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit ce3c86accdcd73d3c3a46e41be1fcc09775200dd +Subproject commit a68981bec91028c8165f220fef683650cb79afe4 diff --git a/docs/source/user-guide/configuration-files.rst b/docs/source/user-guide/configuration-files.rst index e3d23ad97..c0c3490ba 100644 --- a/docs/source/user-guide/configuration-files.rst +++ b/docs/source/user-guide/configuration-files.rst @@ -1,31 +1,36 @@ - - +################### Configuration files -=================== +################### -All GCHP run directories have default simulation-specific run-time settings that are set in the configuration files. This section gives an high-level overview of all run directory configuration files used at run-time in GCHP, as well as links to detailed descriptions if you wish to learn more. +All GCHP run directories have default simulation-specific run-time +settings that are set in the configuration files. This section gives +an high-level overview of all run directory configuration files used +at run-time in GCHP, as well as links to detailed descriptions if you +wish to learn more. .. note:: - The many configuration files in GCHP can be overwhelming. However, you should be able to accomplish most if not all of what you wish to configure from one place in :file:`setCommonRunSettings.sh`. That file is a bash script used to configure settings in other files from one place. - Please get very familiar with the options in :file:`setCommonRunSettings.sh` by reading through the configuration - section of the file. - Be conscientious about not updating the same setting elsewhere. - -------------------------------------------- -Configuration files -------------------- - -Detailed information about most of GCHP's configuration file can be found in the following pages. -You can also reach these pages by continuing with the "next" button in this user guide. -See further down on this page for a high-level summary of all configuration files. + The many configuration files in GCHP can be overwhelming. However, + you should be able to accomplish most if not all of what you wish + to configure from one place in + :file:`setCommonRunSettings.sh`. That file is a bash script used to + configure settings in other files from one place. Please get + very familiar with the options in :file:`setCommonRunSettings.sh` + by reading through the configuration section of the file. + Be conscientious about not updating the same setting elsewhere. -.. tip:: +================================ +List of GCHP configuration files +================================ +Detailed information about most of GCHP's configuration file can be +found in the following pages. You can also reach these pages by +continuing with the "next" button in this user guide. See further down +on this page for a high-level summary of all configuration files. .. toctree:: :maxdepth: 1 - + config-files/setCommonRunSettings_sh.rst config-files/GCHP_rc.rst config-files/CAP_rc.rst @@ -37,70 +42,83 @@ See further down on this page for a high-level summary of all configuration file config-files/HISTORY_rc.rst config-files/HEMCO_Diagn_rc.rst -------------------------------------------- - +================== High-level summary ------------------- +================== -This high-level summary of GCHP configuration files gives a short description of each file. +This high-level summary of GCHP configuration files gives a short description of each file. :file:`CAP.rc` - Controls parameters used by the highest level gridded component (CAP). - This includes simulation run time information, name of the Root gridded component (GCHP), - config filenames for Root and History, and toggles for certain MAPL logging utilities - (timers, memory, and import/export name printing). Values are automatically set from - settings in :file:`setCommonRunSetting.sh`. + Controls parameters used by the highest level gridded component (CAP). + This includes simulation run time information, name of the Root + gridded component (GCHP), config filenames for Root and History, + and toggles for certain MAPL logging utilities + (timers, memory, and import/export name printing). Values are + automatically set from settings in :file:`setCommonRunSetting.sh`. :file:`ESMF.rc` - Controls the logging level of ESMF. - By default this file specifies no log output for ESMF. See the file for available options you can set at run-time. + Controls the logging level of ESMF. By default this file specifies + no log output for ESMF. See the file for available options you can + set at run-time. :file:`ExtData.rc` - Config file for the MAPL ExtData component. - Specifies input variable information, including name, regridding method, read frequency, offset, scaling, and file path. - All GCHP imports must be specified in this file. - Toggles at the top of the file enable MAPL ExtData debug prints and using most recent year if current year of data is unavailable. - Default values may be used by specifying file path :file:`/dev/null`. + Config file for the MAPL ExtData component. Specifies input + variable information, including name, regridding method, read + frequency, offset, scaling, and file path. All GCHP imports must be + specified in this file. Toggles at the top of the file enable MAPL + ExtData debug prints and using most recent year if current year of + data is unavailable. Default values may be used by specifying file + path :file:`/dev/null`. :file:`GCHP.rc` - Controls high-level aspects of the simulation, including grid type and resolution, core distribution, - stretched-grid parameters, timesteps, and restart filename. Values are automatically set from + Controls high-level aspects of the simulation, including grid type + and resolution, core distribution, stretched-grid parameters, + timesteps, and restart filename. Values are automatically set from settings in :file:`setCommonRunSettings.sh`. :file:`geoschem_config.yml` - Primary config file for GEOS-Chem. Same file format as in GEOS-Chem Classic but containing only options relevant to GCHP. - Some fields are automatically updated from settings in :file:`setCommonRunSettings.sh`. + Primary config file for GEOS-Chem. Same file format as in GEOS-Chem + Classic but containing only options relevant to GCHP. Some fields + are automatically updated from settings in + :file:`setCommonRunSettings.sh`. :file:`HEMCO_Config.rc` - Contains emissions information used by HEMCO. - Same function as in GEOS-Chem Classic except only HEMCO name, species, scale IDs, category, and hierarchy are used. + Contains emissions information used by HEMCO. + Same function as in GEOS-Chem Classic except only HEMCO name, species, scale IDs, category, and hierarchy are used. Diagnostic frequency, file path, read frequency, and units are ignored, and are instead stored in - GCHP config file :file:`ExtData.rc`. + GCHP config file :file:`ExtData.rc`. All HEMCO variables listed in :file:`HEMCO_Config.rc` for enabled emissions must also have an entry in :file:`ExtData.rc`. :file:`HEMCO_Diagn.rc` - Contains information mapping :file:`HISTORY.rc` diagnostic names to HEMCO containers. - Same function as in GEOS-Chem Classic except that not all items in :file:`HEMCO_Diagn.rc` will be output; only - emissions listed in :file:`HISTORY.rc` will be included in diagnostics. - All GCHP diagnostics listed in :file:`HISTORY.rc` that start with Emis, Hco, or Inv must have a corresponding entry in :file:`HEMCO_Diagn.rc`. + Contains information mapping :file:`HISTORY.rc` diagnostic names to + HEMCO containers. Same function as in GEOS-Chem Classic except + that not all items in :file:`HEMCO_Diagn.rc` will be output; only + emissions listed in :file:`HISTORY.rc` will be included in + diagnostics. All GCHP diagnostics listed in :file:`HISTORY.rc` + that start with Emis, Hco, or Inv must have a corresponding entry + in :file:`HEMCO_Diagn.rc`. :file:`HISTORY.rc` - Config file for the MAPL History component. - It configures diagnostic output from GCHP. There is an option in :file:`setCommonRunSettings.sh` to auto-update this - file based on settings configured there, including duration, frequency, and which collections to update. + Config file for the MAPL History component. It configures + diagnostic output from GCHP. There is an option in + :file:`setCommonRunSettings.sh` to auto-update this file based on + settings configured there, including duration, frequency, and + which collections to update. :file:`input.nml` - Namelist used in advection for domain stack size and stretched grid parameters. Users should not need to update this. + Namelist used in advection for domain stack size and stretched grid + parameters. Users should not need to update this. :file:`logging.yml` - Config file for the NASA MAPL logger package included in GCHP for logging. - This package uses a hierarchy of loggers, such as info, warnings, error, and debug, to extract non-GEOS-Chem information about GCHP runs and print it to log file :file:`allPEs.log`. Use this file to debug problems with data inputs. + Config file for the NASA MAPL logger package included in GCHP for + logging. This package uses a hierarchy of loggers, such as info, warnings, + error, and debug, to extract non-GEOS-Chem information about GCHP + runs and print it to log file :file:`allPEs.log`. Use this file to + debug problems with data inputs. :file:`setCommonRunSettings.sh` - This file is a bash script where you can set commonly changed run settings. - It auto-updates other configuration files when it is sourced. - It makes it easier to manage configuring GCHP since settings can be changed from one file rather than across multiple configuration files. - - - - + This file is a bash script where you can set commonly changed run + settings. It auto-updates other configuration files when it is + sourced. It makes it easier to manage configuring GCHP since + settings can be changed from one file rather than across multiple + configuration files. diff --git a/docs/source/user-guide/rundir-init.rst b/docs/source/user-guide/rundir-init.rst index 8a7689b13..9bde9935e 100644 --- a/docs/source/user-guide/rundir-init.rst +++ b/docs/source/user-guide/rundir-init.rst @@ -1,44 +1,53 @@ .. _creating_a_run_directory: +###################### Create a Run Directory -====================== +###################### -Run directories are created with the :file:`createRunDir.sh` script in the :file:`run/` subdirectory of the source code. -Run directories are version-specific, so you need to create new run directories for every GEOS-Chem version. -The gist of creating a run directory is simple: navigate to the :file:`run/` subdirectory, run :file:`./createRunDir.sh`, -and answer the prompts: +Run directories are created with the :file:`createRunDir.sh` script in +the :file:`run/` subdirectory of the source code. Run directories are +version-specific, so you need to create new run directories for every +GEOS-Chem version. The gist of creating a run directory is simple: +navigate to the :file:`run/` subdirectory, run +:file:`./createRunDir.sh`, and answer the prompts: .. code-block:: console gcuser:~$ cd GCHP/run gcuser:~/GCHP/run$ ./createRunDir.sh ... ... - + .. important:: Use :term:`absolute paths ` when responding to prompts. -If you are unsure what a prompt is asking, see their explanations below, or ask a question +If you are unsure what a prompt is asking, see their explanations below, or ask a question on GitHub. After following all prompts a run directory should be created for you with a confirmation message, and, you can move on to the next section. -------------------------------------------------------------------------------------------- - .. _create_rundir_prompts: +======================= Explanations of Prompts ------------------------ +======================= Below are detailed explanations of the prompts in :file:`./createRunDir.sh`. Enter ExtData path -^^^^^^^^^^^^^^^^^^ - -The first time you create a GCHP run directory on your system you will be prompted to register as a GEOS-Chem user. Please provide this information so that we can track GEOS-Chem user groups around the world and get to know what GEOS-Chem is used for. - -Following registration you will be prompted for a path to GEOS-Chem shared data directories. -The path should include the name of your :file:`ExtData/` directory and should not contain symbolic links. -The path you enter will be stored in file :file:`.geoschem/config` in your home directory as environment variable :envvar:`GC_DATA_ROOT`. -If that file does not already exist it will be created for you. -When creating additional run directories you will only be prompted again if the file is missing or if the path within it is not valid. +------------------ + +The first time you create a GCHP run directory on your system you will +be prompted to register as a GEOS-Chem user. Please provide this +information so that we can track GEOS-Chem user groups around the +world and get to know what GEOS-Chem is used for. + +Following registration you will be prompted for a path to GEOS-Chem +shared data directories. The path should include the name of your +:file:`ExtData/` directory and should not contain symbolic links. The +path you enter will be stored in file :file:`.geoschem/config` +in your home directory as environment variable +:envvar:`GC_DATA_ROOT`. If that file does not already exist it will +be created for you. When creating additional run directories you will +only be prompted again if the file is missing or if the path within it +is not valid. .. code-block:: none @@ -47,7 +56,7 @@ When creating additional run directories you will only be prompted again if the ----------------------------------------------------------- Choose a simulation type -^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------ Enter the integer number that is next to the simulation type you want to use. @@ -63,7 +72,9 @@ Enter the integer number that is next to the simulation type you want to use. 5. Carbon >>> -If creating a full chemistry run directory you will be given additional options. Enter the integer number that is next to the simulation option you want to run. +If creating a full chemistry run directory you will be given +additional options. Enter the integer number that is next to the +simulation option you want to run. .. code-block:: none @@ -81,9 +92,12 @@ If creating a full chemistry run directory you will be given additional options. >>> Choose meteorology source -^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------- -Enter the integer number that is next to the input meteorology source you would like to use. Note that choosing GEOS-FP or GEOS-IT will result in additional questions to refine the meteorology inputs you would like to use from the dataset. +Enter the integer number that is next to the input meteorology source +you would like to use. Note that choosing GEOS-FP or GEOS-IT will +result in additional questions to refine the meteorology inputs you +would like to use from the dataset. .. code-block:: none @@ -96,9 +110,10 @@ Enter the integer number that is next to the input meteorology source you would >>> Enter run directory path -^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------ -Enter the target path where the run directory will be stored. You will be prompted to enter a new path if the one you enter does not exist. +Enter the target path where the run directory will be stored. You will +be prompted to enter a new path if the one you enter does not exist. .. code-block:: none @@ -108,9 +123,11 @@ Enter the target path where the run directory will be stored. You will be prompt >>> Enter run directory name -^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------ -Enter the run directory name, or accept the default. You will be prompted for a new name if a run directory of the same name already exists at the target path. +Enter the run directory name, or accept the default. You will be +prompted for a new name if a run directory of the same name already +exists at the target path. .. code-block:: none @@ -122,11 +139,13 @@ Enter the run directory name, or accept the default. You will be prompted for a >>> Enable version control (optional) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------------- -Enter whether you would like your run directory tracked with git version control. -With version control you can keep track of exactly what you changed relative to the original settings. -This is useful for trouble-shooting as well as tracking run directory feature changes you wish to migrate back to the standard model. +Enter whether you would like your run directory tracked with git +version control. With version control you can keep track of exactly +what you changed relative to the original settings. This is useful for +trouble-shooting as well as tracking run directory feature changes you +wish to migrate back to the standard model. .. code-block:: none @@ -135,15 +154,17 @@ This is useful for trouble-shooting as well as tracking run directory feature ch ----------------------------------------------------------- >>> -You will then see a message printed to screen about the run directory created and brief instructions for us. For example: +You will then see a message printed to screen about the run directory +created and brief instructions for us. For example: .. code-block:: none + Initialized empty Git repository in /n/home/gchp_merra2_fullchem/.git/ - - + + ----------------------------------------------------------- Created /n/home/gchp_merra2_fullchem - + -- This run directory is set up for simulation start date 20190701 -- Restart files for this date at different grid resolutions are in the Restarts subdirectory diff --git a/docs/source/user-guide/running.rst b/docs/source/user-guide/running.rst index 93c9e035b..7c702328b 100644 --- a/docs/source/user-guide/running.rst +++ b/docs/source/user-guide/running.rst @@ -1,16 +1,20 @@ - .. _running_gchp: +############# Run the model -============= +############# -This page presents the basic information needed to run GCHP as well as how to verify a successful run and reuse a run directory. -A pre-run checklist is included here for easy reference. Please read the rest of this page to understand these steps. +This page presents the basic information needed to run GCHP as well as +how to verify a successful run and reuse a run directory. A pre-run +checklist is included here for easy reference. Please read the rest of +this page to understand these steps. +================= Pre-run checklist ------------------ +================= -Prior to running GCHP, always run through the following checklist to ensure everything is set up properly. +Prior to running GCHP, always run through the following checklist to +ensure everything is set up properly. 1. Start date is set in :file:`cap_restart` 2. Executable :file:`gchp` is present. @@ -23,26 +27,34 @@ Prior to running GCHP, always run through the following checklist to ensure ever How to run GCHP --------------- -You can run GCHP locally from within your run directory ("interactively") or by submitting your run to a job scheduler if one is available. -Either way, it is useful to put run commands into a reusable script we call the run script. -Executing the script will either run GCHP or submit a job that will run GCHP. +You can run GCHP locally from within your run directory +("interactively") or by submitting your run to a job scheduler if one +is available. Either way, it is useful to put run commands into a +reusable script we call the run script. Executing the script will +either run GCHP or submit a job that will run GCHP. -There is a symbolic link in the GCHP run directory called :file:`runScriptSamples` that points to a directory in the source code containing example run scripts. -Each file includes extra commands that make the run process easier and less prone to user error. -These commands include: +There is a symbolic link in the GCHP run directory called :file:`runScriptSamples` that points to a directory in the source code containing example run scripts. +Each file includes extra commands that make the run process easier and +less prone to user error. These commands include: -1. Define a GCHP log file that includes start date configured in :file:`cap_restart` in its name +1. Define a GCHP log file that includes start date configured in + :file:`cap_restart` in its name 2. Source environment file symbolic link :file:`gchp.env` -3. Source config file :file:`setCommonRunSettings.sh` to update commonly changed run settings -4. Set restart file symbolic link :file:`gchp_restart.nc4` to target file in :file:`Restarts` subdirectory for configured start date and grid resolution +3. Source config file :file:`setCommonRunSettings.sh` to update + commonly changed run settings +4. Set restart file symbolic link :file:`gchp_restart.nc4` to target + file in :file:`Restarts` subdirectory for configured start date and + grid resolution 5. Check that :file:`cap_restart` now contains end date of your run -6. Rename the output restart file to include run start date and grid resolution (format :literal:`GEOSChem.Restarts.YYYYMMDD_HHmmz.cN.nc4`) +6. Rename the output restart file to include run start date and grid + resolution (format + :literal:`GEOSChem.Restarts.YYYYMMDD_HHmmz.cN.nc4`) Run interactively -^^^^^^^^^^^^^^^^^ +----------------- -Copy or adapt example run script :file:`gchp.local.run` to run GCHP locally on your machine. -Before running, make sure the total number of cores configured in :file:`setCommonRunSettings.sh` is available locally. +Copy or adapt example run script :file:`gchp.local.run` to run GCHP locally on your machine. +Before running, make sure the total number of cores configured in :file:`setCommonRunSettings.sh` is available locally. It must be at least 6. To run, type the following at the command prompt: @@ -51,24 +63,35 @@ To run, type the following at the command prompt: $ ./gchp.local.run -Standard output will be displayed on your screen in addition to being sent to a log file with filename format :literal:`gchp.YYYYMMDD_HHmmSSz.log`. The HEMCO log output is also included in this file. +Standard output will be displayed on your screen in addition to being +sent to a log file with filename format +:literal:`gchp.YYYYMMDD_HHmmSSz.log`. The HEMCO log output is also +included in this file. Run as batch job -^^^^^^^^^^^^^^^^ +---------------- -Batch job run scripts will vary based on what job scheduler you have available. -We offer a template batch job run script in the :file:`runScriptSamples` subdirectory called :file:`gchp.batch_job.sh`. This file contains examples for 3 types of job scheduler: SLURM, LSF, and PBS. +Batch job run scripts will vary based on what job scheduler you have available. +We offer a template batch job run script in the +:file:`runScriptSamples` subdirectory called +:file:`gchp.batch_job.sh`. This file contains examples for 3 +types of job scheduler: SLURM, LSF, and PBS. You may copy and adapt this file for your system and preferences as needed. -At the top of all batch job scripts are configurable run settings. -Most critically are requested # cores, # nodes, time, and memory. -Figuring out the optimal values for your run can take some trial and error. -See :ref:`hardware requirements ` for guidance on what to choose. -The more cores you request the faster GCHP will run given the same grid resolution. -Configurable job scheduler settings and acceptable formats are often accessible from the command line. -For example, type :command:`man sbatch` to scroll through configurable options for SLURM, including various ways of specifying number of cores, time and memory requested. - -To submit a batch job using a run script called :file:`gchp.run` and the SLURM job scheduler: +At the top of all batch job scripts are configurable run +settings. Most critically are requested # cores, # nodes, time, and +memory. Figuring out the optimal values for your run can take some +trial and error. See :ref:`hardware requirements +` for guidance on what to choose. The more +cores you request the faster GCHP will run given the same grid +resolution. Configurable job scheduler settings and acceptable +formats are often accessible from the command line. For example, type +:command:`man sbatch` to scroll through configurable options for +SLURM, including various ways of specifying number of cores, +time and memory requested. + +To submit a batch job using a run script called :file:`gchp.run` and +the SLURM job scheduler: .. code-block:: console @@ -80,72 +103,120 @@ To submit using Grid Engine instead of SLURM: $ qsub gchp.run -If your computational cluster uses a different job scheduler, check with your IT staff or search the internet for how to configure and submit batch jobs on your system. +If your computational cluster uses a different job scheduler, check +with your IT staff or search the internet for how to configure and +submit batch jobs on your system. Verify a successful run ----------------------- -GEOS-Chem standard output and standard error will be sent to a file specific to your scheduler, e.g. :file:`slurm-jobid.out`, unless you configured your run script to send it to a different log file. Variable :literal:`log` is defined in the template run script as :file:`gchp.YYYYMMDD_HHmmSSz.log` if you wish to use it. The date string in the log filename is the start date of your simulation as configured in :file:`cap_restart`. This log is automatically used if you execute the interactive run script example :file:`gchp.local.run`. GCHP produces another output log file called :file:`allPEs.log` which is produced by the MAPL library logger for debugging purposes. Several other logs are output for informational purposes only but generally are not useful for debugging. - -There are several ways to verify that your run was successful. Here are just a few: - -1. The GCHP log file shows every timestep (search for :literal:`AGCM Date`) and ends with timing information. +GEOS-Chem standard output and standard error will be sent to a file +specific to your scheduler, e.g. :file:`slurm-jobid.out`, unless you +configured your run script to send it to a different log +file. Variable :literal:`log` is defined in the template run script as +:file:`gchp.YYYYMMDD_HHmmSSz.log` if you wish to use it. The date +string in the log filename is the start date of your simulation +as configured in :file:`cap_restart`. This log is automatically +used if you execute the interactive run script example +:file:`gchp.local.run`. GCHP produces another output log file +called :file:`allPEs.log` which is produced by the MAPL +library logger for debugging purposes. Several other logs +are output for informational purposes only but generally +are not useful for debugging. + +There are several ways to verify that your run was successful. Here +are just a few: + +1. The GCHP log file shows every timestep (search for :literal:`AGCM + Date`) and ends with timing information. 2. NetCDF files are present in the :file:`OutputDir/` subdirectory. -3. There is a restart file corresponding to your end date in the :file:`Restarts` subdirectory. -4. The start date in :file:`cap_restart` has been updated to your run end date. +3. There is a restart file corresponding to your end date in the + :file:`Restarts` subdirectory. +4. The start date in :file:`cap_restart` has been updated to your run + end date. 5. The job scheduler log does not contain any error messages. -6. Output file :file:`allPEs.log` does not contain any error messages. - -If it looks like something went wrong, scan through the log files to determine where there may have been an error. There are several debug strategies depending on what you find. Below is a summary of steps to take to debug GCHP runs. See also :ref:`debugging ` for additional guidance. - -* Find the first error message in the GCHP log file to see if it tells you what is wrong. -* Find the first line of the traceback for the error and find the file and line number listed to see if it gives a hint about what is wrong. -* Review all of your configuration files to ensure you have proper setup, especially :file:`setCommonRunSettings.sh`. -* "MAPL_Cap" or "CAP" errors in the run log typically indicate an error with your start time and/or duration. Check :file:`cap_restart` and :file:`setCommonRunSettings.sh`. -* "MAPL_ExtData" or "ExtData" errors in the run log indicate an error with your input files. Check :file:`HEMCO_Config.rc` and :file:`ExtData.rc` for errors.. -* "MAPL_HistoryGridComp" or "History" errors in the run log are related to your configured diagnostics. Check :file:`HISTORY.rc`. -* If the problem is a segmentation fault then rebuild the model with cmake option :literal:`-DCMAKE_BUILD_TYPE=Debug` and rerun. -* If the problem appears to be in HEMCO then change the warnings and verbose options in :file:`HEMCO_Config.rc` to true and rerun -* If the problem appears to be in GEOS-Chem then change the verbose activate option in :file:`geoschem_config.yml` to true and rerun -* If the problem appears to be in MAPL ExtData then change the :literal:`root_level` settings for :literal:`CAP.ExtData` in :file:`logging.yml` to :literal:`DEBUG` and rerun - -If you still cannot figure out where the problem is then please create a GCHP GitHub issue and include all config and log files for your run. - +6. Output file :file:`allPEs.log` does not contain any error + messages. + +If it looks like something went wrong, scan through the log files to +determine where there may have been an error. There are several debug +strategies depending on what you find. Below is a summary of steps to +take to debug GCHP runs. See also :ref:`debugging ` for +additional guidance. + +* Find the first error message in the GCHP log file to see if it tells + you what is wrong. +* Find the first line of the traceback for the error and find the file + and line number listed to see if it gives a hint about what is + wrong. +* Review all of your configuration files to ensure you have proper + setup, especially :file:`setCommonRunSettings.sh`. +* "MAPL_Cap" or "CAP" errors in the run log typically indicate an + error with your start time and/or duration. Check + :file:`cap_restart` and :file:`setCommonRunSettings.sh`. +* "MAPL_ExtData" or "ExtData" errors in the run log indicate an error with your input files. Check :file:`HEMCO_Config.rc` and :file:`ExtData.rc` for errors. +* "MAPL_HistoryGridComp" or "History" errors in the run log are + related to your configured diagnostics. Check :file:`HISTORY.rc`. +* If the problem is a segmentation fault then rebuild the model with + cmake option :literal:`-DCMAKE_BUILD_TYPE=Debug` and rerun. +* If the problem appears to be in HEMCO then change the warnings and + verbose options in :file:`HEMCO_Config.rc` to true and rerun +* If the problem appears to be in GEOS-Chem then change the verbose + activate option in :file:`geoschem_config.yml` to true and rerun +* If the problem appears to be in MAPL ExtData then change the + :literal:`root_level` settings for :literal:`CAP.ExtData` in + :file:`logging.yml` to :literal:`DEBUG` and rerun + +If you still cannot figure out where the problem is then please create +a GCHP GitHub issue and include all config and log files for your +run. + +===================== Reuse a run directory ---------------------- +===================== Archive run output -^^^^^^^^^^^^^^^^^^ -Reusing a GCHP run directory comes with the perils of losing your old work. -To mitigate this issue there is utility shell script :file:`archiveRun.sh`. -This script archives data output and configuration files to a subdirectory that will not be deleted if you clean your run directory. +------------------ +Reusing a GCHP run directory comes with the perils of losing your old work. +To mitigate this issue there is utility shell script :file:`archiveRun.sh`. +This script archives data output and configuration files to a +subdirectory that will not be deleted if you clean your run +directory. Archiving runs is useful for other reasons as well, including: * Save all settings and logs for later reference after a run crashes -* Generate data from the same executable using different run-time settings for comparison, e.g. c48 versus c180 +* Generate data from the same executable using different run-time + settings for comparison, e.g. c48 versus c180 * Run short runs to compare for debugging -To archive a run, pass the archive script a descriptive subdirectory name where data will be archived. For example: +To archive a run, pass the archive script a descriptive subdirectory +name where data will be archived. For example: .. code-block:: console $ ./archiveRun.sh 1mo_c24_24hrdiag -Which files are copied and to where will be displayed on the screen. -Diagnostic files in the :file:`OutputDir/` directory will be moved rather than copied so as not to duplicate large files. -Restart files will not be archived. If you would like include restart files in the archive you must manually copy or move them. +Which files are copied and to where will be displayed on the +screen. Diagnostic files in the :file:`OutputDir/` directory will be +moved rather than copied so as not to duplicate large files. Restart +files will not be archived. If you would like include restart files in +the archive you must manually copy or move them. Clean a run directory -^^^^^^^^^^^^^^^^^^^^^ +--------------------- -It is good practice to clean your run directory prior to your next run if starting on the same date. -This avoids confusion about what output was generated when and with what settings. -To make run directory cleaning simple we provide utility shell script :file:`cleanRunDir.sh`. To clean the run directory simply execute this script. +It is good practice to clean your run directory prior to your next run +if starting on the same date. This avoids confusion about what output +was generated when and with what settings. To make run directory +cleaning simple we provide utility shell script +:file:`cleanRunDir.sh`. To clean the run directory simply execute this +script. .. code-block:: console $ ./cleanRunDir.sh -All GCHP output diagnostic files and logs, including NetCDF files in :file:`OutputDir/`, will be deleted. -Restart files in the :file:`Restarts` subdirectory will not be deleted. +All GCHP output diagnostic files and logs, including NetCDF files in +:file:`OutputDir/`, will be deleted. Restart files in the +:file:`Restarts` subdirectory will not be deleted. From 6d817f8d5b802b7f2d5ed592ccbdb88c48cfb801 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 29 Aug 2024 14:29:24 -0400 Subject: [PATCH 11/41] GEOS-Chem submod update: Merge PR #2436, #2439, #2371 (PPN Phot etc.) This commit informs the GCHP 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/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 3073aff2e..602b660c1 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 3073aff2e63d1073f7e63acaa9dba293dbc0553a +Subproject commit 602b660c13182a43b5620fad0eaf402d7a18696a From 3fb63d5ed917d837ff23c665cea433981ba2f292 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 3 Sep 2024 13:22:18 -0400 Subject: [PATCH 12/41] GEOS-Chem submod update: Merge PR #2424, PR #2426, Cloud-J PR #24 This commit informs the GCHP 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/GCHP_GridComp/GEOSChem_GridComp/Cloud-J | 2 +- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/Cloud-J b/src/GCHP_GridComp/GEOSChem_GridComp/Cloud-J index d20050f1e..291a1612c 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/Cloud-J +++ b/src/GCHP_GridComp/GEOSChem_GridComp/Cloud-J @@ -1 +1 @@ -Subproject commit d20050f1ef9e3895d58f3041efd2da59ce1ed421 +Subproject commit 291a1612cb30f09fd56e761bdd27a095ab1d9815 diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 602b660c1..1951ea96e 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 602b660c13182a43b5620fad0eaf402d7a18696a +Subproject commit 1951ea96ef14e01c08a1df7da254109050e78c79 From 629483c650d2f2a0499811895cb354ca547365a4 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 4 Sep 2024 10:14:55 -0400 Subject: [PATCH 13/41] 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 | 4 ++++ docs/requirements.txt | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8ddf1aa5f..c790d3902 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,10 @@ This file documents all notable changes to the GCHP wrapper repository starting 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 +- Updated `docs/requirements.txt` to use `jinja2==3.1.4` (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 30d24ccef..8c874e35e 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 cea4c2434741ca91a7c3fcbacc7b855cbc591ea6 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 5 Sep 2024 13:51:44 -0400 Subject: [PATCH 14/41] Cloud-J submod update: Merge PR #26 (Define max J-values rather than exact) This commit informs the GCHP 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/GCHP_GridComp/GEOSChem_GridComp/Cloud-J | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/Cloud-J b/src/GCHP_GridComp/GEOSChem_GridComp/Cloud-J index 291a1612c..6bf4a36d1 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/Cloud-J +++ b/src/GCHP_GridComp/GEOSChem_GridComp/Cloud-J @@ -1 +1 @@ -Subproject commit 291a1612cb30f09fd56e761bdd27a095ab1d9815 +Subproject commit 6bf4a36d11039783c0b29befc48e93cdff7f6ecb From 97670682f9b004eef501c4fae8050730a8c44f93 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Fri, 6 Sep 2024 11:07:42 -0400 Subject: [PATCH 15/41] GEOS-Chem submod update: Merge PR #2452 (Reorder photo rxns for PNs, ANs) This commit informs the GCHPsuperproject 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/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 1951ea96e..a5fba9c88 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 1951ea96ef14e01c08a1df7da254109050e78c79 +Subproject commit a5fba9c88ad279095026be17c31a40bb84802eda From 984823f95feb5b13f8575b83696f668afe31a681 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Fri, 13 Sep 2024 10:12:16 -0400 Subject: [PATCH 16/41] GEOS-Chem update: Merge PR #2457 (Update Is_Photolysis tags) This commit informs the GCHP 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/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index a5fba9c88..cd0366015 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit a5fba9c88ad279095026be17c31a40bb84802eda +Subproject commit cd03660155e86b8cea3681c7a9554e5e783511d6 From 06190b0166236bac680566e20ad52453fd339a10 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 16 Sep 2024 16:43:08 -0400 Subject: [PATCH 17/41] GEOS-Chem & HEMCO updates: Merge PR #2462, PR #2430, PR #287 This commit informs the GCHP 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/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO | 2 +- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO b/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO index d0d5fca8c..c6a9d4668 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO +++ b/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO @@ -1 +1 @@ -Subproject commit d0d5fca8ceab6f59aa98d6e65952dcfc9f3aef6e +Subproject commit c6a9d4668ee54af64f785f6c1113a2bc659efc70 diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index cd0366015..c0aeff427 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit cd03660155e86b8cea3681c7a9554e5e783511d6 +Subproject commit c0aeff427c45a25bc85fe18b5baf2a489dfac863 From 2982d99d70ed8e2dadec046ddca8a13fee9f5439 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Thu, 19 Sep 2024 17:06:24 -0400 Subject: [PATCH 18/41] GEOS-Chem submodupdate: Merge PR #2464 (remove zero J-value diagnostics) Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index c0aeff427..dd8cce62d 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit c0aeff427c45a25bc85fe18b5baf2a489dfac863 +Subproject commit dd8cce62da7fbb77fd535e9df7207fe5bf883114 From 2b51a5c9ead7872339a61e5cb5b725426331ebd8 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Fri, 20 Sep 2024 17:00:50 -0400 Subject: [PATCH 19/41] GEOS-Chem submod update: Merge PR #1467 (Fix dry mass fraction of seasalt in aerosol thermodynamics) Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index dd8cce62d..875a1593f 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit dd8cce62da7fbb77fd535e9df7207fe5bf883114 +Subproject commit 875a1593f065a345d05b2243ed2c1150ff68d1d2 From 18814f50aa953478fe5c633d83a6e09d4a2af3a9 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Tue, 24 Sep 2024 12:40:23 -0400 Subject: [PATCH 20/41] 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 c5b8f3e1e..4635a4419 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 8ddf1aa5f..f62b45dbd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,10 @@ This file documents all notable changes to the GCHP wrapper repository starting 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 f0a8809159a4d8702f0c90cfc75faa09a39571ec Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Fri, 27 Sep 2024 10:46:29 -0400 Subject: [PATCH 21/41] GEOS-Chem submod update: Merge PR #2477 (Fix for double counting CH4 ag burning emissions) Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 875a1593f..580c4e095 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 875a1593f065a345d05b2243ed2c1150ff68d1d2 +Subproject commit 580c4e095b4fe3001e4224f431fa3525a668f520 From 59be5f45130864b6ea729da0b736726ac4ac8e1f Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Fri, 27 Sep 2024 13:42:40 -0400 Subject: [PATCH 22/41] GEOS-Chem submodule update: Merge PR #2473 (seasonality of CH4 reservoir emissions) Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 580c4e095..4f11ef074 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 580c4e095b4fe3001e4224f431fa3525a668f520 +Subproject commit 4f11ef074c0cafae977ff17637985502e3620354 From 352d18a093a2da5ec3fe84ed34198250dca18eb1 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Fri, 27 Sep 2024 14:08:08 -0400 Subject: [PATCH 23/41] GEOS-Chem and HEMCO submodule updates: Add fixes for stale issue Github workflow Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO | 2 +- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO b/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO index c6a9d4668..a3d0c9a28 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO +++ b/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO @@ -1 +1 @@ -Subproject commit c6a9d4668ee54af64f785f6c1113a2bc659efc70 +Subproject commit a3d0c9a280672ac1c40e3f322651f23b8196fa4c diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 4f11ef074..7ffdb5b64 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 4f11ef074c0cafae977ff17637985502e3620354 +Subproject commit 7ffdb5b64f2ab2a2cdb6030addbeb0fae6b61104 From 21f11f6e89a73ebcbd46a13d7be676807ca8fcde Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Mon, 30 Sep 2024 16:08:10 -0400 Subject: [PATCH 24/41] GEOS-Chem submodule update: Merge PR #2489 (fix for coarse-mode seasalt Ca, Mg, K) Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 7ffdb5b64..ced6447de 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 7ffdb5b64f2ab2a2cdb6030addbeb0fae6b61104 +Subproject commit ced6447def626729f69a301dca98bf605f91057f From a4b7eb8b662e828f76711cdb836fc00e6988f772 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Tue, 1 Oct 2024 09:45:35 -0400 Subject: [PATCH 25/41] GEOS-Chem submodule update: Merge PR #2490 (clean up CHANGELOG.md) Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index ced6447de..c7a6ae627 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit ced6447def626729f69a301dca98bf605f91057f +Subproject commit c7a6ae6277a173aa67b903af3af659ebbd2b36d2 From 0f0aa597dda9791d4f4c129fee63600012e41c98 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Tue, 1 Oct 2024 13:36:51 -0400 Subject: [PATCH 26/41] Cloud-J submodule update for 8.0.1 release Signed-off-by: Melissa Sulprizio --- CHANGELOG.md | 5 +++++ src/GCHP_GridComp/GEOSChem_GridComp/Cloud-J | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f62b45dbd..ccef69d20 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,11 @@ This file documents all notable changes to the GCHP wrapper repository starting 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/GCHP_GridComp/GEOSChem_GridComp/Cloud-J b/src/GCHP_GridComp/GEOSChem_GridComp/Cloud-J index 6bf4a36d1..f8a2b7f96 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/Cloud-J +++ b/src/GCHP_GridComp/GEOSChem_GridComp/Cloud-J @@ -1 +1 @@ -Subproject commit 6bf4a36d11039783c0b29befc48e93cdff7f6ecb +Subproject commit f8a2b7f964bde1582fbc38c41d8872bc23a21735 From 0cd75fadc6c1a9ca11b1255daeaa126bcbe4a71c Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 1 Oct 2024 16:22:25 -0400 Subject: [PATCH 27/41] Update GCHP configuration file documentation - Now point to geoschem_config.yml, HEMCO_Config.rc, and HEMCO_Diagn.rc, species_database.yml, and aerosol/chem/photolysis configuration files in the documentation in geos-chem-shared-docs/doc folder - Updated the configuration file overview page accordingly - Now use ".. option::" tags for easier searching of items - Reformatted text using ReST best practices - Trimmed trailing whitespace Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- .../source/user-guide/config-files/CAP_rc.rst | 114 +++-- .../user-guide/config-files/ExtData_rc.rst | 195 +++++-- .../user-guide/config-files/GCHP_rc.rst | 481 +++++++++++++----- .../user-guide/config-files/HISTORY_rc.rst | 358 +++++++++---- .../user-guide/config-files/cap_restart.rst | 35 ++ .../config-files/geoschem_config_yml.rst | 14 - .../user-guide/config-files/input_nml.rst | 74 ++- .../user-guide/config-files/logging_yml.rst | 66 ++- .../config-files/setCommonRunSettings_sh.rst | 63 ++- .../source/user-guide/configuration-files.rst | 106 ++-- 11 files changed, 1107 insertions(+), 401 deletions(-) create mode 100644 docs/source/user-guide/config-files/cap_restart.rst delete mode 100644 docs/source/user-guide/config-files/geoschem_config_yml.rst diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index a68981bec..b5420bbb7 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit a68981bec91028c8165f220fef683650cb79afe4 +Subproject commit b5420bbb77f9fea9b26cc36785c441883295b029 diff --git a/docs/source/user-guide/config-files/CAP_rc.rst b/docs/source/user-guide/config-files/CAP_rc.rst index 4529ed7a9..e0ad73e65 100644 --- a/docs/source/user-guide/config-files/CAP_rc.rst +++ b/docs/source/user-guide/config-files/CAP_rc.rst @@ -1,51 +1,95 @@ +.. _cap-rc: + +###### CAP.rc -====== +###### + +:ref:`cap-rc` is the configuration file for the top-level gridded +component called :program:`CAP`. This gridded component can be +thought of as the primary driver of GCHP. Its config file handles +general runtime settings for GCHP including time parameters, +performance profiling routines, and system-wide timestep (hearbeat). +Combined with output file :ref:`cap-restart`, :ref:`cap-rc` +configures the exact dates for the next GCHP run. + +.. option:: ROOT_NAME + + Sets the name MAPL uses to initialize the :program:`ROOT` child + gridded component component within :program:`CAP`. :program:`CAP` + uses this name in all operations when querying and interacting with + :program:`ROOT`. It is set to :literal:`GCHP`. + +.. option:: ROOT_CF + + Resource configuration file for the :program:`ROOT` component. It + is set to :ref:`gchp-rc`. + +.. option:: HIST_CF + + Resource configuration file for the MAPL :program:`HISTORY` gridded + component (another child gridded component of :program:`CAP`). It + is set to :ref:`history-rc`. -:file:`CAP.rc` is the configuration file for the top-level gridded component called CAP. -This gridded component can be thought of as the primary driver of GCHP. -Its config file handles general runtime settings for GCHP including time parameters, performance profiling routines, and system-wide timestep (hearbeat). -Combined with output file :file:`cap_restart`, :file:`CAP.rc` configures the exact dates for the next GCHP run. +.. option:: BEG_DATE -ROOT_NAME - Sets the name MAPL uses to initialize the ROOT child gridded component component within CAP. CAP uses this name in all operations when querying and interacting with ROOT. It is set to GCHP. + Simulation begin date in format YYYYMMDD hhmmss. This parameter is + overrided in the presence of output file :ref:`cap-restart` + containing a different start date. -ROOT_CF - Resource configuration file for the ROOT component. It is set to :file:`GCHP.rc`. +.. option:: END_DATE -HIST_CF - Resource configuration file for the MAPL HISTORY gridded component (another child gridded component of CAP). It is set to :file:`HISTORY.rc`. + Simulation end date in format :literal:`YYYYMMDD hhmmss`. If + :option:`BEG_DATE` plus duration (:option:`JOB_SGMT`) is before + :option:`END_DATE` then simulation will end at + :option:`BEG_DATE` + :option:`JOB_SGMT`. If it is after then + simulation will end at :option:`END_DATE`. -BEG_DATE - Simulation begin date in format YYYYMMDD hhmmss. This parameter is overrided in the presence of output file :file:`cap_restart` containing a different start date. +.. option:: JOB_SGMT -END_DATE - Simulation end date in format YYYYMMDD hhmmss. If BEG_DATE plus duration (JOB_SGMT) is before END_DATE then simulation will end at BEG_DATE + JOB_SGMT. If it is after then simulation will end at END_DATE. + Simulation duration in format :literal:`YYYYMMDD hhmmss`. The + duration must be less than or equal to the difference between + :option:`BEG_DATE` and :option:`END_DATE` or the model will crash. -JOB_SGMT - Simulation duration in format YYYYMMDD hhmmss. The duration must be less than or equal to the difference between start and end date or the model will crash. +.. option:: HEARTBEAT_DT -HEARTBEAT_DT - The timestep of the ESMF/MAPL internal clock, in seconds. All other timesteps in GCHP must be a multiple of HEARTBEAT_DT. ESMF queries all components at each heartbeat to determine if computation is needed. The result is based upon individual component timesteps defined in :file:`GCHP.rc`. + The timestep of the ESMF/MAPL internal clock, in seconds. All other + timesteps in GCHP must be a multiple of :option:`HEARTBEAT_DT`. + ESMF queries all components at each heartbeat to determine if + computation is needed. The result is based upon individual + component timesteps defined in :ref:`gchp-rc`. -MAPL_ENABLE_TIMERS - Toggles printed output of runtime MAPL timing profilers. This is set to YES. Timing profiles are output at the end of every GCHP run. +.. option:: MAPL_ENABLE_TIMERS -MAPL_ENABLE_MEMUTILS - Enables runtime output of the programs' memory usage. This is set to YES. + Toggles printed output of runtime MAPL timing profilers. This is + set to :literal:`YES`. Timing profiles are output at the end of + every GCHP run. -PRINTSPEC - Allows an abbreviated model run limited to initializat and print of Import and Export state variable names. Options include: - - * 0 (default): Off - * 1: Imports and Exports only - * 2: Imports only - * 3: Exports only +.. option:: MAPL_ENABLE_MEMUTILS + + Enables runtime output of the program's memory usage. This is set + to :literal:`YES`. + +.. option:: PRINTSPEC + + Allows an abbreviated model run limited to initialize and print of + Import and Export state variable names. Options include: + + * :literal:`0`: Off (default value) + * :literal:`1`: Imports and Exports only + * :literal:`2`: Imports only + * :literal:`3`: Exports only + +.. option:: USE_SHMEM -USE_SHMEM This setting is deprecated but still has an entry in the file. -REVERSE_TIME - Enables running time backwards in CAP. Default is 0 (off). +.. option:: REVERSE_TIME + + Enables running time backwards in :program:`CAP`. Default is 0 + (off). + +.. option:: USE_EXTDATA2G -USE_EXTDATA2G - Enables using the next generation of MAPL ExtData (input component) which uses a yaml-format configuration file. Default is .FALSE. (off). + Enables using the next generation of MAPL :program:`ExtData` (input + component) which uses a yaml-format configuration file. Default is + :literal:`.FALSE.` (off). diff --git a/docs/source/user-guide/config-files/ExtData_rc.rst b/docs/source/user-guide/config-files/ExtData_rc.rst index 88f9bbaca..2afc82b3c 100644 --- a/docs/source/user-guide/config-files/ExtData_rc.rst +++ b/docs/source/user-guide/config-files/ExtData_rc.rst @@ -1,57 +1,164 @@ +.. |br| raw:: html + +
+ +.. _extdata-rc: + +########## ExtData.rc -========== +########## -:file:`ExtData.rc` contains input variable and file read information for GCHP. -Explanatory information about the file is located at the top of the configuration file in all run directories. -The file format is the same as that used in the GEOS model, and GMAO/NASA documentation for it can be found at the ExtData component page on the GEOS-5 wiki. -Note that this file will be retired in GCHP v15.0 when MAPL version 3 is integrated into GCHP. It will be replaced with a YAML format file with a -simplified and easier to understand interface. +:file:`ExtData.rc` contains input variable and file read information +for GCHP. Explanatory information about the file is located at the top +of the configuration file in all run directories. The file format is +the same as that used in the GEOS model, and GMAO/NASA documentation +for it can be found at the ExtData component page on the GEOS-5 +wiki. Note that this file will be retired in GCHP v15.0 when MAPL +version 3 is integrated into GCHP. It will be replaced with a YAML +format file with a simplified and easier to understand interface. -The ins and outs of :file:`ExtData.rc` can be hard to grasp, particular with regards to variable data -updating, time interpolation, and file read. Reach out on the GCHP GitHub Issues page if you need help. See also the GCHP ReadTheDocs page on enabling -ExtData prints for debugging. Enabling ExtData debug prints is the best way to determine what MAPL is doing for file I/O per import. +The ins and outs of :file:`ExtData.rc` can be hard to grasp, +particular with regards to variable data updating, time interpolation, +and file read. Reach out on the GCHP GitHub Issues page if you need +help. See also the GCHP ReadTheDocs page on enabling ExtData prints +for debugging. Enabling ExtData debug prints is the best way to +determine what MAPL is doing for file I/O per import. The following +parameter is set at the top of the file: -The following parameter is set at the top of the file: +.. option:: Ext_AllowExtrap -Ext_AllowExtrap - Logical toggle to use data from nearest year available, including meteorology if files for the simulation year are not found. This is set to true for GCHP. Note that GEOS-Chem Classic accomplishes the same effect but with more flexibility in :file:`HEMCO_Config.rc`, and the entries of :file:`HEMCO_Config.rc` which do this are ignored in GCHP. + Logical toggle to use data from nearest year available, including + meteorology if files for the simulation year are not found. This is + set to true for GCHP. Note that GEOS-Chem Classic accomplishes the + same effect but with more flexibility in :ref:`cfg-hco-cfg`, + and the entries of :file:`cfg-hco-cfg` which do this are ignored + in GCHP. -The rest of the file contains whitespace-delimited lines. Each line describes one data variable imported to the model from an external file. -Columns are as follows in order from left to right: +The rest of the file contains whitespace-delimited lines. Each line +describes one data variable imported to the model from an external +file. Columns are as follows in order from left to right: -Name - Name of the field stored in the MAPL Imports container. This is independent of the name of the data field in the input file. For the case of entries that also appear in :file:`HEMCO_Config.rc` it is also the name of the HEMCO emissions container (left-most column in that file). For those fields it is used to match scaling and masking information in :file:`HEMCO_Config.rc` with file I/O information in :file:`ExtData.rc`. All file I/O information :file:`HEMCO_Config.rc`, including filename, units, dimensions, regridding, and read frequency are ignored by GCHP. +.. option:: Name + + Name of the field stored in the MAPL Imports container. This is + independent of the name of the data field in the input file. For + the case of entries that also appear in :file:`HEMCO_Config.rc` it + is also the name of the HEMCO emissions container (left-most column + in that file). For those fields it is used to match scaling and + masking information in :file:`HEMCO_Config.rc` with file I/O + information in :file:`ExtData.rc`. All file I/O information + :ref:`cfg-hco-cfg`, including filename, units, dimensions, + regridding, and read frequency are ignored by GCHP. + +.. option:: Units -Units Unit string of the import. This entry is informational only. -Clim - Whether the data is climatology. Enter :file:`Y` if the data is a 12 month climatology, enter year if the data is daily climatology (i.e. :file:`2019`), :file:`D` if the file is monthly day-of-week scale factors (7 values for each of 12 months), or :file:`N` for all other cases. If you specify monthly climatology then the data must be stored in either 1 or 12 files. - -Conservative - Method to regrid the input data to the simulation grid. Enter :file:`Y` to use mass conserving regridding, :literal:`F;{VALUE}` for fractional regridding, or :file:`N` to use non-conervative bilinear regridding. - -Refresh - Time template for updating data. This tells MAPL when to look for new data values. It stores previous and next time data in what are called left and right brackets. There are several options for specifying refresh: - - * :file:`-` : Update variable data only once. Use this if the data is constant in time. - * :file:`0` : Update variable data at every timestep using linear interpolation. For example, if the data is hourly then MAPL will linearly interpolate between the previous and next hour's data for every timestep. - * :file:`0:003000` (or other HHMMSS specification for hours, minutes, seconds) : Use specified time offset (i.e. 30 minutes in this example) for setting previous and next time, and interpolate every timestep between the two. This is useful if, for example, you have time-averaged hourly data and you want the previous and next times to update half-way between the hour. This format is used for meteorology fields that are interpolated every timestep, specifically temperature and surface pressure. - * :file:`F0:003000` (or other HHMMSS specification for hours, minutes, seconds) : Like the previous option except there is no time interpolation. This format is used for meteorology fields that are not time-interpolated, such as cloud fraction. - * :file:`%y4-%m2-%h2T%h2:%n2:00` (or other combination of time tokens) : Update variable data when time tokens change. Interpreting this entry gets a little tricky. The data will be updated when the time tokens change, not the hard-coded times. For example, a template in the form :file:`%y4-%m2-%d2T12:00:00` changes at the start of each day because that is when the evaluation of :file:`%y4-%m2-%d2` changes. While the variable will be updated at the start of a new day (e.g. at time 2019-01-02 00:00:00), the time used for reading and interpolation is hour 12 of that day. You can similar hard-code year, month, day, or hour if you always want to use a constant value for that field. - * :file:`F%y4-%m2-%h2T%h2:%n2:00` (or other combination of time tokens) : Like the previous option except that there is no time interpolation. - -Offset Factor - Value the data will be shifted by upon read. Use :file:`none` for no shifting. - -Scale Factor - Value the data will be scaled by upon read. This is useful if you want to convert units upon read, such as from :file:`Pa` to :file:`hPa`. Use :file:`none` for no scaling. - -External File Variable +.. option:: Clim + + Whether the data is climatology. Enter :file:`Y` if the data is a + 12 month climatology, enter year if the data is daily climatology + (i.e. :file:`2019`), :file:`D` if the file is monthly day-of-week + scale factors (7 values for each of 12 months), or :file:`N` for + all other cases. If you specify monthly climatology then the data + must be stored in either 1 or 12 files. + +.. option:: Conservative + + Method to regrid the input data to the simulation grid. Enter + :file:`Y` to use mass conserving regridding, :literal:`F;{VALUE}` + for fractional regridding, or :file:`N` to use + non-conervative bilinear regridding. + +.. option:: Refresh + + Time template for updating data. This tells MAPL when to look for + new data values. It stores previous and next time data in what are + called left and right brackets. There are several options for + specifying refresh: + + * :file:`-` : Update variable data only once. Use this if the data + is constant in time. |br| + |br| + + * :file:`0` : Update variable data at every timestep using linear + interpolation. For example, if the data is hourly then MAPL will + linearly interpolate between the previous and next hour's data + for every timestep. |br| + |br| + + * :file:`0:003000` (or other HHMMSS specification for hours, + minutes, seconds) : Use specified time offset (i.e. 30 minutes in + this example) for setting previous and next time, and interpolate + every timestep between the two. This is useful if, for example, + you have time-averaged hourly data and you want the previous and + next times to update half-way between the hour. This format is + used for meteorology fields that are interpolated every timestep, + specifically temperature and surface pressure. |br| + |br| + + * :file:`F0:003000` (or other HHMMSS specification for hours, + minutes, seconds) : Like the previous option except there is no + time interpolation. This format is used for meteorology fields + that are not time-interpolated, such as cloud fraction. |br| + |br| + + * :file:`%y4-%m2-%h2T%h2:%n2:00` (or other combination of time + tokens) : Update variable data when time tokens + change. Interpreting this entry gets a little tricky. The data + will be updated when the time tokens change, not the hard-coded + times. For example, a template in the form + :file:`%y4-%m2-%d2T12:00:00` changes at the start of each day + because that is when the evaluation of :file:`%y4-%m2-%d2` + changes. While the variable will be updated at the start of + a new day (e.g. at time 2019-01-02 00:00:00), the time used + for reading and interpolation is hour 12 of that day. You + can similar hard-code year, month, day, or hour if you + always want to use a constant value for that field. |br| + |br| + + * :file:`F%y4-%m2-%h2T%h2:%n2:00` (or other combination of time + tokens) : Like the previous option except that there is no time + interpolation. + +.. option:: Offset Factor + + Value the data will be shifted by upon read. Use :file:`none` for + no shifting. + +.. option:: Scale Factor + + Value the data will be scaled by upon read. This is useful if you + want to convert units upon read, such as from :file:`Pa` to + :file:`hPa`. Use :file:`none` for no scaling. + +.. option:: External File Variable + Name of the variable to read in the netCDF data file. -External File Template - Path to the netCDF data file, including time tokens as needed (:file:`%y4` for year, :file:`%m2` for month, :file:`%d2` for day, :file:`%h2` for hour, :file:`%n2` for minutes). If there are no time tokens in the template name then ExtData will assume that all the data is in one file. If you wish to ignore an entry in :file:`ExtData.rc` (i.e. not read the data at all since you will not use it) then put :file:`/dev/null`. This will save processing time. +.. option:: External File Template + + Path to the netCDF data file, including time tokens as needed + (:file:`%y4` for year, :file:`%m2` for month, :file:`%d2` for + day,:file:`%h2` for hour, :file:`%n2` for minutes). If there are no + time tokens in the template name then ExtData will assume that all + the data is in one file. If you wish to ignore an entry in + :file:`ExtData.rc` (i.e. not read the data at all since you will + not use it) then put :file:`/dev/null`. This will save processing + time. + +.. option:: Reference Time and Period -Reference Time and Period (optional) - Period of data with reference time. This optional entry is useful if you have data frequency that is offset from midnight. For example, 3-hourly data available for times 1:30, 4:30, 7:30, etc. The reference time could be specified as :file:`2000-01-01T01:30:00P03:00`. The first part (before :file:`P`) is the reference date (must be on or before your simulation start), and the second part (after :file:`P`) is the period of data availability (in this case 3 hours). This can be used in combination with the file template containing hours and minutes. It tells MAPL to only read the file at times that are regular 3 hr intervals from the reference date and time. Not including this would cause MAPL to read the file every minute if the file template contains the :file:`n2` time token. + **OPTIONAL**. Period of data with reference time. This optional + entry is useful if you have data frequency that is offset from + midnight. For example, 3-hourly data available for times 1:30, + 4:30, 7:30, etc. The reference time could be specified as + :file:`2000-01-01T01:30:00P03:00`. The first part (before + :file:`P`) is the reference date (must be on or before your + simulation start), and the second part (after :file:`P`) is the + period of data availability (in this case 3 hours). This can be + used in combination with the file template containing hours and + minutes. It tells MAPL to only read the file at times that are + regular 3 hr intervals from the reference date and time. Not + including this would cause MAPL to read the file every minute if + the file template contains the :file:`n2` time token. diff --git a/docs/source/user-guide/config-files/GCHP_rc.rst b/docs/source/user-guide/config-files/GCHP_rc.rst index af6bba95a..0a9d54ce9 100644 --- a/docs/source/user-guide/config-files/GCHP_rc.rst +++ b/docs/source/user-guide/config-files/GCHP_rc.rst @@ -1,187 +1,414 @@ +.. _gchp-rc: + +####### GCHP.rc -======= +####### + +:file:`GCHP.rc` is the resource configuration file for the +:program:`ROOT` component within GCHP. The :program:`ROOT` gridded +component includes three children gridded components, +including one each for GEOS-Chem (:program:`GCHPchem`), FV3 advection +(:program:`DYNAMICS`), and the data utility environment needed to +support them (:program:`GCHPctmEnv`). + +.. option:: NX +.. option:: NY + + Number of grid cells in the two MPI sub-domain dimensions. Each + face of the cubed-sphere grid is divided into :literal:`NX * NY/6` + subdomains. :literal:`NX * NY` must equal the number of CPUs and + :literal:`NY` must be a multiple of 6. These values are set + automatically by :ref:`set-common-run-settings-sh`. + + .. attention:: + + If you are running GCHP using input mass fluxes then there are + additional constraints on :literal:`NX` and :literal:`NY` due to + MAPL constraints on horizontal regridding of + fluxes. :literal:`NX` and :literal:`NY/6` must evenly divide + into (1) the source resolution :literal:`N` + (e.g. :literal:`N=180` if input mass flux resolution is + C180), and (2) the target resolution :literal:`N'` + (e.g. :literal:`N'=90` if run resolution is C90). This + limits the total number of cores you can use when running GCHP + with input mass fluxes. + +.. option:: GCHP.GRID_TYPE + + Type of grid GCHP will be run at. This should always be set to + :literal:`Cubed-Sphere`. + +.. option:: GCHP.GRIDNAME + + Descriptive horizontal grid label for the simulation. The default + grid name format is :literal:`PE{N}x{N*6}-CF` where :literal:`N` is + the number of grid cells per cubed-sphere face side, + e.g. :literal:`24` for :literal:`C24`. The grid name also includes + how the pole is treated and whether it is a cubed-sphere grid or + lat/lon (for GCHP it must always be cubed-sphere). For example, the + name :literal:`PE24x144-CF` indicates polar edge (PE), 24 cells + along one face side, 144 for 24*6, and a cubed-sphere grid + (:literal:`CF`). This setting is updated automatically by + :ref:`set-common-run-settings-sh`. + +.. option:: GCHP.NF + + Number of cubed-sphere faces. This must always be set to 6. -:file:`GCHP.rc` is the resource configuration file for the ROOT component within GCHP. -The ROOT gridded component includes three children gridded components, including one each for GEOS-Chem (GCHPchem), FV3 advection (DYNAMICS), and the data utility environment needed to support them (GCHPctmEnv). +.. option:: GCHP.IM_WORLD -NX, NY - Number of grid cells in the two MPI sub-domain dimensions. Each face of the cubed-sphere grid is divided into NX x NY/6 subdomains. NX * NY must equal the number of CPUs and NY must be a multiple of 6. These values are set automatically by setCommonRunSettings.sh. + Number of grid cells on the side of a single cubed sphere + face. This is set automatically by + :ref:`set-common-run-settings-sh` for your configured run + resolution. -If you are running GCHP using input mass fluxes then there are additional constraints on NX and NY due to MAPL constraints on horizontal regridding of fluxes. NX and NY/6 must evenly divide into (1) the source resolution N (e.g. N=180 if input mass flux resolution is c180), and (2) the target resolution N' (e.g. N'=90 if run resoltion is c90). This limits the total number of cores you can use when running GCHP with input mass fluxes. +.. option:: GCHP.IM -GCHP.GRID_TYPE - Type of grid GCHP will be run at. This should always be set to Cubed-Sphere. + Number of grid cells on the side of a single cubed sphere + face. This is set automatically by + :ref:`set-common-run-settings-sh` for your configured run + resolution. -GCHP.GRIDNAME - Descriptive horizontal grid label for the simulation. The default grid name format is PE{N}x{N*6}-CF where N is the number of grid cells per cubed-sphere face side, e.g. 24 for C24. The grid name also includes how the pole is treated and whether it is a cubed-sphere grid or lat/lon (for GCHP it must always be cubed-sphere). For example, the name PE24x144-CF indicates polar edge (PE), 24 cells along one face side, 144 for 24*6, and a cubed-sphere grid (CF). This setting is updated automatically by setCommonRunSettings.sh. +.. option:: GCHP.JM -GCHP.NF - Number of cubed-sphere faces. This must always be set to 6. + Number of grid cells on one side of a cubed sphere face, + times 6. This represents a second dimension if all six faces are + stacked in a 2-dimensional array. Must be equal to + :literal:`IM*6`. This is set automatically by + :ref:`set-common-run-settings-sh` for your configured run + resolution. + +.. option:: GCHP.LM + + Number of vertical grid cells. This must be equal to the vertical + resolution of the offline meteorological fields since MAPL cannot + regrid vertically. It is set to 72 by default. + +.. option:: GCHP.STRETCH_FACTOR + + Ratio of configured global resolution to resolution of targeted + high resolution region if using stretched grid. This is set + automatically by :ref:`set-common-run-settings-sh` based on + configured stretched grid settings in that file. + +.. option:: GCHP.TARGET_LON + + Target longitude for high resolution region if using stretched + grid. This is set automatically by + :ref:`set-common-run-settings-sh` based on configured stretched + grid settings in that file. Negative values are acceptable for + longitude. + +.. option:: GCHP.TARGET_LAT + + Target latitude for high resolution region if using stretched + grid. This is set automatically by + :ref:`set-common-run-settings-sh` based on configured stretched + grid settings in that file. + +.. option:: IM + + Same as :option:`GCHP.IM` and :option:`GCHP.IM_WORLD`. This is set + automatically by :ref:`set-common-run-settings-sh` for your + configured run resolution. + +.. option:: JM + + Same as :option:`GCHP.JM`. This is set automatically by + :ref:`set-common-run-settings-sh` for your configured run + resolution. + +.. option:: LM + + Same as :option:`GCHP.LM`. This setting is set automatically by + setCommonRunSettings.sh. + +.. option:: GEOChem_CTM + + If set to :literal:`1`, tells FVdycore that it is operating as a + transport model rather than a prognostic model. + +.. option:: METEOROLOGY_VERTICAL_INDEX_IS_TOP_DOWN + + If set to :literal:`.true.` then GCHP assumes all input met-fields + have level 1 corresponding to top-of-atmosphere. This field is set + automatically when creating a run directory based on whether you + choose to use processed or raw met-fields. Raw met-fields are + top-down, while processed met-fields are not (level 1 = surface). + +.. option:: IMPORT_MASS_FLUX_FROM_EXTDATA + + If set to :literal:`.true.` then input mass fluxes will be used in + advection. If .false. mass flux will be derived online from input + winds. This setting is automatically set during run directory + creation. + +.. option:: USE_TOTAL_AIR_PRESSURE_IN_ADVECTION + + If set to :literal:`0` then dry pressure will be used in advection + (default). Using total air pressure in advection is currently + experimental. + +.. option:: CORRECT_MASS_FLUX_FOR_HUMIDITY + + If set to :literal:`1` then mass fluxes will be converted to dry + air for use in advection. This switch is not used if using GMAO + winds for advection. + +.. option:: AdvCore_Advection + + Toggles offline advection. :literal:`0` is off, and :literal:`1` is + on. This field is automatically updated by + :ref:`set-common-run-settings-sh` based on whether you turn + advection on or off in that file. + +.. option:: DYCORE + + Should either be set to :literal:`OFF` (default) or + :literal:`ON`. This value does nothing, but MAPL will crash if it + is not declared. + +.. option:: HEARTBEAT_DT + + The timestep in seconds that the DYCORE Component should be + called. This must be a multiple of HEARTBEAT_DT in + :ref:`cap-rc`. Note that this and all other timesteps are + automatically set from :ref:`set-common-run-settings-sh` based + on the configured grid resolution in that file. + +.. option:: SOLAR_DT + + The timestep in seconds that the :program:`SOLAR` Component should + be called. This must be a multiple of :option:`HEARTBEAT_DT` in + :ref:`cap-rc`. GCHP does not have a :program:`SOLAR` component and + this entry is therefore not used. + +.. option:: IRRAD_DT + + The timestep in seconds that the :program:`IRRAD` Component should + be called. ESMF checks this value during its timestep check. This + must be a multiple of :option:`HEARTBEAT_DT` in :ref:`cap-rc`. GCHP + does not have an :program:`IRRAD` component and this entry is + therefore not used. + +.. option:: RUN_DT + + The timestep in seconds that the :program:`RUN` Component should be + called. This setting is set automatically by + :ref:`set-common-run-settings-sh`. + +.. option:: GCHPchem_DT + + The timestep in seconds that the :program:`GCHPchem` Component + should be called. This must be a multiple of :option:`HEARTBEAT_DT` + in :ref:`cap-rc`. This setting is set automatically by + :ref:`set-common-run-settings-sh`. + +.. option:: RRTMG_DT + + The timestep in seconds that :program:`RRTMG` should be + called. This must be a multiple of :option:`HEARTBEAT_DT` in + :ref:`cap-rc`. This setting is set automatically by + :ref:`set-common-run-settings-sh`. + +.. option:: DYNAMICS_DT + + The timestep in seconds that the :program:`FV3 advection Component` + should be called. This must be a multiple of :option:`HEARTBEAT_DT` in + :ref:`cap-rc`. This setting is set automatically by + :ref:`set-common-run-settings-sh`. + +.. option:: SOLARAvrg + + Default is :literal:`0`. + +.. option:: IRRADAvrg + + Default is :literal:`0`. + +.. option:: GCHPchem_REFERENCE_TIME + + :literal:`HHMMSS` reference time used for GCHPchem MAPL alarms + which coordinate when subcomponents with different + timesteps are executed, e.g. chemistry and dynamics. It is + automatically set from :ref:`set-common-run-settings-sh` + to be equal to the dynamic timestep. + +.. option:: PRINTRC -GCHP.IM_WORLD - Number of grid cells on the side of a single cubed sphere face. This is set automatically by :file:`setCommonRunSettings.sh` for your configured run resolution. + Specifies which resource values to print. Options include + :literal:`0`: non-default values, and :literal:`1`: all + values. Default setting is :literal:`0`. -GCHP.IM - Number of grid cells on the side of a single cubed sphere face. This is set automatically by :file:`setCommonRunSettings.sh` for your configured run resolution. +.. option:: PARALLEL_READFORCING -GCHP.JM - Number of grid cells on one side of a cubed sphere face, times 6. This represents a second dimension if all six faces are stacked in a 2-dimensional array. Must be equal to IM*6. This is set automatically by :file:`setCommonRunSettings.sh` for your configured run resolution. + Enables or disables parallel I/O processes. Default value is + :literal:`0` (disabled). This option does not impact reading or + writing restart files and should be left as is. -GCHP.LM - Number of vertical grid cells. This must be equal to the vertical resolution of the offline meteorological fields since MAPL cannot regrid vertically. It is set to 72 by default. +.. option:: NUM_READERS -GCHP.STRETCH_FACTOR - Ratio of configured global resolution to resolution of targeted high resolution region if using stretched grid. This is set automatically by :file:`setCommonRunSettings.sh` based on configured stretched grid settings in that file.. + Number of simultaneous readers for reading restart files. Default + value is :literal:`1`. Try increasing this to anywhere from 6 to 24 + to improve restart read time. Whether this helps to reduce restart + file I/O time depends on your file system and MPI stack. -GCHP.TARGET_LON - Target longitude for high resolution region if using stretched grid. This is set automatically by :file:`setCommonRunSettings.sh` based on configured stretched grid settings in that file. Negative values are acceptable for longitude. +.. option:: NUM_WRITERS -GCHP.TARGET_LAT - Target latitude for high resolution region if using stretched grid. This is set automatically by :file:`setCommonRunSettings.sh` based on configured stretched grid settings in that file.. + Number of simultaneous writers for writing restart files. Default + value is :literal:`1`. Increasing it to anywhere from 6 to 24 may + increase restart write speed depending on your file system and MPI + stack. -IM - Same as GCHP.IM and GCHP.IM_WORLD. This is set automatically by :file:`setCommonRunSettings.sh` for your configured run resolution. +.. option:: BKG_FREQUENCY -JM - Same as GCHP.JM. This is set automatically by :file:`setCommonRunSettings.sh` for your configured run resolution. + Active observer when desired. Default value is :literal:`0`. This + option is not used in GCHP. -LM - Same as GCHP.LM. This setting is set automatically by setCommonRunSettings.sh. +.. option:: MAPL_ENABLE_BOOTSTRAP -GEOChem_CTM - If set to 1, tells FVdycore that it is operating as a transport model rather than a prognostic model. + When set to :literal:`YES` MAPL will initialize all entries of the + internal state not in the restart file with zero values. Note that + missing species will later be set to the background value in the + species database if this is allowed + (see :option:`INITIAL_RESTART_SPECIES_REQUIRED`). -METEOROLOGY_VERTICAL_INDEX_IS_TOP_DOWN - If set to .true. then GCHP assumes all input met-fields have level 1 corresponding to top-of-atmosphere. - This field is set automatically when creating a run directory based on whether you choose to use - processed or raw met-fields. Raw met-fields are top-down, while processed met-fields are not (level 1 = sfc). +.. option:: INITIAL_RESTART_SPECIES_REQUIRED -IMPORT_MASS_FLUX_FROM_EXTDATA - If set to .true. then input mass fluxes will be used in advection. If .false. mass flux will be derived - online from input winds. This setting is automatically set during run directory creation. + If set to :literal:`0` then the GCHP run will fail if any species + is missing from the restart file. Set to :literal:`1` to allow + missing species. Note that this is different from GC-Classic which + requires updates to :ref:`cfg-hco-cfg` to allow missing + species. That part of :ref:`cfg-hco-cfg` is ignored in GCHP. -USE_TOTAL_AIR_PRESSURE_IN_ADVECTION - If set to 0 then dry pressure will be used in advection (default). Using total air pressure in advection - is currently experimental. +.. option:: RECORD_FREQUENCY -CORRECT_MASS_FLUX_FOR_HUMIDITY - If set to 1 then mass fluxes will be converted to dry air for use in advection. - This switch is not used if using GMAO winds for advection. + Frequency of periodic restart file write in format + :literal:`HHMMSS`. This is set automatically by + :ref:`set-common-run-settings-sh` based on mid-run + checkpoint settings configured in that file. -AdvCore_Advection - Toggles offline advection. 0 is off, and 1 is on. This field is automatically updated by :file:`setCommonRunSettings.sh` based on whether you turn advection on or off in that file. +.. option:: RECORD_REF_DATE -DYCORE - Should either be set to OFF (default) or ON. This value does nothing, but MAPL will crash if it is not declared. + Reference date(s) used to determine when to write periodic restart + files. This is set automatically by + :ref:`set-common-run-settings-sh` + based on mid-run checkpoint settings configured in that file. -HEARTBEAT_DT - The timestep in seconds that the DYCORE Component should be called. This must be a multiple of HEARTBEAT_DT in :file:`CAP.rc`. Note that this and all other timesteps are automatically set from :file:`setCommonRunSetting.sh` based on the configured grid resolution in that file. +.. option:: RECORD_REF_TIME -SOLAR_DT - The timestep in seconds that the SOLAR Component should be called. This must be a multiple of HEARTBEAT_DT in :file:`CAP.rc`. GCHP does not have a SOLAR component and this entry is therefore not used. + Reference time(s) used to determine when to write periodic restart + files. This is set automatically by + :ref:`set-common-run-settings-sh` based on mid-run checkpoint + settings configured in that file. -IRRAD_DT - The timestep in seconds that the IRRAD Component should be called. ESMF checks this value during its timestep check. This must be a multiple of HEARTBEAT_DT in :file:`CAP.rc`. GCHP does not have an IRRAD component and this entry is therefore not used. +.. option:: GCHPchem_INTERNAL_RESTART_FILE -RUN_DT - The timestep in seconds that the RUN Component should be called. This setting is set automatically by setCommonRunSettings.sh. + The filename of the internal restart file to be written. For GCHP + we always use the name of the symbolic link in the run directory + that points to the restart file. Use a sample run script to get the + functionality of setting the symbolic link based on run start + date. Note that the restart file includes all variables stored in + the MAPL internal state. -GCHPchem_DT - The timestep in seconds that the GCHPchem Component should be called. This must be a multiple of HEARTBEAT_DT in :file:`CAP.rc`. This setting is set automatically by setCommonRunSettings.sh. +.. option:: GCHPchem_INTERNAL_RESTART_TYPE -RRTMG_DT - The timestep in seconds that RRTMG should be called. This must be a multiple of HEARTBEAT_DT in :file:`CAP.rc`. This setting is set automatically by setCommonRunSettings.sh. + The format of the internal restart file. Valid types include + :literal:`pbinary` and :literal:`pnc4`. Only use :literal:`pnc4` with GCHP. -DYNAMICS_DT - The timestep in seconds that the FV3 advection Component should be called. This must be a multiple of HEARTBEAT_DT in :file:`CAP.rc`. This setting is set automatically by setCommonRunSettings.sh. +.. option:: GCHPchem_INTERNAL_CHECKPOINT_FILE -SOLARAvrg, IRRADAvrg - Default is 0. + The filename of the internal checkpoint file to be written. By + default this does not include date-time. Use a sample GCHP run + script to get the functionality to rename it to include date and + time post-run. -GCHPchem_REFERENCE_TIME - HHMMSS reference time used for GCHPchem MAPL alarms which coordinate when subcomponents with different timesteps are executed, e.g. chemistry and dynamics. It is automatically set from :file:`setCommonRunSettings.sh` to be equal to the dynamic timestep. +.. option:: GCHPchem_INTERNAL_CHECKPOINT_TYPE -PRINTRC - Specifies which resource values to print. Options include 0: non-default values, and 1: all values. Default setting is 0. + The format of the internal checkstart file. Valid types include + :literal:`pbinary` and :literal:`pnc4`. Only use pnc4 with GCHP. -PARALLEL_READFORCING - Enables or disables parallel I/O processes. Default value is 0 (disabled). This option does not impact reading or writing restart files and should be left as is. +.. option:: GCHPchem_INTERNAL_HEADER -NUM_READERS - Number of simultaneous readers for reading restart files. Default value is 1. Try increasing this to anywhere from 6 to 24 to improve restart read time. Whether this helps wit dependent on your file system and MPI stack. + Only needed when the file type is set to + :literal:`pbinary`. Specifies if a binary file is + self-describing. This feature is not used in GCHP. -NUM_WRITERS - Number of simultaneous writers for writing restart files. Default value is 1. Increasing it to anywhere from 6 to 24 may increase restart write speed depending on your file system and MPI stack. +.. option:: DYN_INTERNAL_RESTART_FILE -BKG_FREQUENCY - Active observer when desired. Default value is 0. This option is not used in GCHP. + The filename of the :program:`DYNAMICS` internal restart file to be + written. Please note that FV3 is not configured in GCHP to use an + internal state and therefore will not have a restart file. -MAPL_ENABLE_BOOTSTRAP - When set to YES MAPL will initialize all entries of the internal state not in the restart file with zero values. - Note that missing species will later be set to the background value in the species database if this is allowed - (see next entry) +.. option:: DYN_INTERNAL_RESTART_TYPE -INITIAL_RESTART_SPECIES_REQUIRED - If set to 0 then the GCHP run will fail if any species is missing from the restart file. Set to 1 to allow - missing species. Note that this is different from GC-Classic which requires updates to :file:`HEMCO_Config.rc` - to allow missing species. That part of :file:`HEMCO_Config.rc` is ignored in GCHP. + The format of the :program:`DYNAMICS` internal restart file. Valid + types include pbinary and pnc4. Please note that FV3 is not + configured in GCHP to use an internal state and therefore will not + have a restart file. -RECORD_FREQUENCY - Frequency of periodic restart file write in format HHMMSS. This is set automatically by :file:`setCommonRunSettings.sh` based on mid-run checkpoint settings configured in that file. +.. option:: DYN_INTERNAL_CHECKPOINT_FILE -RECORD_REF_DATE - Reference date(s) used to determine when to write periodic restart files. This is set automatically by :file:`setCommonRunSettings.sh` based on mid-run checkpoint settings configured in that file. + The filename of the :program:`DYNAMICS` internal checkpoint file to + be written. Please note that FV3 is not configured in GCHP to use + an internal state and therefore will not have a restart file. -RECORD_REF_TIME - Reference time(s) used to determine when to write periodic restart files. This is set automatically by :file:`setCommonRunSettings.sh` based on mid-run checkpoint settings configured in that file. +.. option:: DYN_INTERNAL_CHECKPOINT_TYPE -GCHPchem_INTERNAL_RESTART_FILE - The filename of the internal restart file to be written. For GCHP we always use the name of the symbolic link in the run directory that points to the restart file. Use a sample run script to get the functionality of setting the symbolic link based on run start date. Note that the restart file includes all variables stored in the MAPL internal state. + The format of the :program:`DYNAMICS` internal checkpoint + file. Valid types include pbinary and pnc4. Please note that FV3 is + not configured in GCHP to use an internal state and therefore will + not have a restart file. -GCHPchem_INTERNAL_RESTART_TYPE - The format of the internal restart file. Valid types include pbinary and pnc4. Only use pnc4 with GCHP. +.. option:: DYN_INTERNAL_HEADER -GCHPchem_INTERNAL_CHECKPOINT_FILE - The filename of the internal checkpoint file to be written. By default this does not include date-time. Use a sample GCHP run script to get the functionality to rename it to include date and time post-run. + Only needed when the file type is set to + :literal:`pbinary`. Specifies if a binary file is self-describing. -GCHPchem_INTERNAL_CHECKPOINT_TYPE - The format of the internal checkstart file. Valid types include pbinary and pnc4. Only use pnc4 with GCHP. +.. option:: RUN_PHASES -GCHPchem_INTERNAL_HEADER - Only needed when the file type is set to pbinary. Specifies if a binary file is self-describing. This feature is not used in GCHP. + GCHP uses only one run phase. The GCHP gridded component for + chemistry, however, has the capability of two. The two-phase + feature is used only in GEOS. -DYN_INTERNAL_RESTART_FILE - The filename of the DYNAMICS internal restart file to be written. Please note that FV3 is not configured in GCHP to use an internal state and therefore will not have a restart file. +.. option:: HEMCO_CONFIG -DYN_INTERNAL_RESTART_TYPE - The format of the DYNAMICS internal restart file. Valid types include pbinary and pnc4. Please note that FV3 is not configured in GCHP to use an internal state and therefore will not have a restart file. + Name of the HEMCO configuration file. Default is :ref:`cfg-hco-cfg` in GCHP. -DYN_INTERNAL_CHECKPOINT_FILE - The filename of the DYNAMICS internal checkpoint file to be written. Please note that FV3 is not configured in GCHP to use an internal state and therefore will not have a restart file. +.. option:: STDOUT_LOGFILE -DYN_INTERNAL_CHECKPOINT_TYPE - The format of the DYNAMICS internal checkpoint file. Valid types include pbinary and pnc4. Please note that FV3 is not configured in GCHP to use an internal state and therefore will not have a restart file. + Log filename template. Default is + :file:`PET%%%%%.GEOSCHEMchem.log`. This file is not actually used + for primary standard output and not helpful for debugging. You may + ignore it. -DYN_INTERNAL_HEADER - Only needed when the file type is set to pbinary. Specifies if a binary file is self-describing. +.. option:: STDOUT_LOGLUN -RUN_PHASES - GCHP uses only one run phase. The GCHP gridded component for chemistry, however, has the capability of two. The two-phase feature is used only in GEOS. + Logical unit number for stdout. Default value is :literal:`700`. -HEMCO_CONFIG - Name of the HEMCO configuration file. Default is :file:`HEMCO_Config.rc` in GCHP. +.. option:: MEMORY_DEBUG_LEVEL -STDOUT_LOGFILE - Log filename template. Default is :file:`PET%%%%%.GEOSCHEMchem.log`. This file is not actually used for primary standard output and not helpful for debugging. You may ignore it. + Toggle for memory debugging. Default is :literal:`0` + (off). Changing to :literal:`1` will print memory usage between + each GCHP gridcomp run (:program:`advection`, + :program:`GCHPctmEnv`, and :program:`GEOS-Chem`) as well as between + major GEOS-Chem components. Using the default will result + in memory usage print once per timestep only. -STDOUT_LOGLUN - Logical unit number for stdout. Default value is 700. +.. option:: WRITE_RESTART_BY_OSERVER -MEMORY_DEBUG_LEVEL - Toggle for memory debugging. Default is 0 (off). Changing to 1 will print memory usage between each GCHP gridcomp run (advection, GCHPctmEnv, and GEOS-Chem) as well as between major GEOS-Chem components. Using the default will result in memory usage print once per timestep only. + Determines whether MAPL restart write should use a dedicated node + (:program:`O-server`). For some MPI stacks we find that this must + be set to YES for high core count (>1000) runs to avoid hanging + during file write. It is NO by default. If you run into problems + with writing restart files with the O-server off you can try to + switch this setting to on. In previous versions we have + automatically turned this on for core counts but we no longer do + this because whether it works varies with your system. -WRITE_RESTART_BY_OSERVER - Determines whether MAPL restart write should use a dedicated node (O-server). For some MPI stacks we find that this must be set to YES for high core count (>1000) runs to avoid hanging during file write. It is NO by default. If you run into problems with writing restart files with the O-server off you can try to switch this setting to on. In previous versions we have automatically turned this on for core counts but we no longer do this because whether it works varies with your system. +.. option:: MODEL_PHASE -MODEL_PHASE - Use FORWARD for the forward model. ADJOINT is used for adjoint runs (experimental). Other entries in this section that are commented out are reserved for adjoint development and testing. + Use :literal:`FORWARD` for the forward model. :literal:`ADJOINT` is + used for adjoint runs (experimental). Other entries in this section + that are commented out are reserved for adjoint development and + testing. diff --git a/docs/source/user-guide/config-files/HISTORY_rc.rst b/docs/source/user-guide/config-files/HISTORY_rc.rst index 538a65b04..11f464a3a 100644 --- a/docs/source/user-guide/config-files/HISTORY_rc.rst +++ b/docs/source/user-guide/config-files/HISTORY_rc.rst @@ -1,7 +1,15 @@ +.. |br| raw:: html + +
+ +.. _history-rc: + +########## HISTORY.rc -========== +########## -:file:`HISTORY.rc` is the file that configures GCHP's output. It has the following format +:file:`HISTORY.rc` is the file that configures GCHP's output. It has +the following format. .. code-block:: none @@ -17,40 +25,70 @@ HISTORY.rc -:EXPID: - This is the file prefix for all collections. :code:`OutputDir/GCHP` means that collections will be written to directory :file:`OutputDir/` with filename prefix :literal:`GCHP`. +.. option:: EXPID -:CoresPerNode: - The number of cores per node for your GCHP simulation. If using the auto-update diagnostics feature in :file:`setCommonRunSettings.sh` then this will automatically get updated based on settings in that file. + This is the file prefix for all collections. :literal:`OutputDir/GCHP` + means that collections will be written to directory + :file:`OutputDir/` with filename prefix :literal:`GCHP`. + +.. option:: EXPDSC -:EXPDSC: Optional description of your run to be included in output metadata. -:VERSION: - Optional version number of to be included in output metadata. +.. option:: CoresPerNode -The format and description of :ref:`\ `, -:ref:`\ `, and -and :ref:`\ ` sections are given below. + The number of cores per node for your GCHP simulation. If using the + auto-update diagnostics feature in :ref:`set-common-run-settings-sh` + then this will automatically get updated based on settings in that + file. +.. option:: VERSION + + Optional version number of to be included in output metadata. + + The format and description of :ref:`\ + `, :ref:`\ + `, and and :ref:`\ ` sections are given below. .. _defining-grid-labels: +==================== Defining Grid Labels --------------------- +==================== -You can specify custom grids for your output. For example, a regional 0.05°x0.05° grid covering North America. This way your collections are regridded online. There are two advantages to doing this: +You can specify custom grids for your output. For example, a regional +0.05°x0.05° grid covering North America. This way your collections are +regridded online. There are two advantages to doing this: -#. It eliminates the need to regrid your simulation data in a post-processing step. +#. It eliminates the need to regrid your simulation data in a + post-processing step. #. It saves disk space if you are interested in regional output. -Beware that outputting data on a different grid assumes the data is independent of horizontal cell size. The regridding routines are area-conserving and thus regridded values will only make sense for data that is area-independent. Examples of data units that are area-independent are mixing ratios (e.g. kg/kg or mol/mol) and emissions rates per area (e.g. kg/m2/s). Examples of data units that are NOT area-independent are kg/s and m2, or any other unit that implicitly is per grid cell area. This sort of unit is most common in the meteorology diagnostics, such as Met_AREAM2 and Met_AD. The values of these arrays will be incorrect in non-native grid output. - -You can define as many grids as you want. However, you should comment out all grid labels in the :literal:`GRID_LABELS` list that you do not intend to use. This is because MAPL creates all grids listed regardless of whether they are used which increases the memory requirement for the mode. - -A collection can define :code:`grid_label` to select a custom grid. If a collection does not define :code:`grid_label` the simulation's grid is assumed. - -Below is the format for the :code:`` section in :file:`HISTORY.rc`. +Beware that outputting data on a different grid assumes the data is +independent of horizontal cell size. The regridding routines are +area-conserving and thus regridded values will only make sense for +data that is area-independent. Examples of data units that are +area-independent are mixing ratios (e.g. kg/kg or mol/mol) and +emissions rates per area (e.g. kg/m2/s). Examples of data units that +are NOT area-independent are kg/s and m2, or any other unit that +implicitly is per grid cell area. This sort of unit is most common in +the meteorology diagnostics, such as :literal:`Met_AREAM2` and +:literal:`Met_AD`. The values of these arrays will be incorrect in +non-native grid output. + +You can define as many grids as you want. However, you should comment +out all grid labels in the :literal:`GRID_LABELS` list that you do not +intend to use. This is because MAPL creates all grids listed +regardless of whether they are used which increases the memory +requirement for the mode. + +A collection can define :option:`grid_label` to select a custom grid. If +a collection does not define :option:`grid_label` the simulation's grid +is assumed. + +Below is the format for the :literal:`` section in +:file:`HISTORY.rc`. .. code-block:: none @@ -78,44 +116,74 @@ Below is the format for the :code:`` section in :file:`HISTO SPEC NAMES -:GRID_TYPE: - The type of grid. Valid options are :code:`Cubed-Sphere` or :code:`LatLon`. +.. option:: GRID_TYPE + + The type of grid. Valid options are :literal:`Cubed-Sphere` or + :literal:`LatLon`. + +.. option:: IM_WORLD + + The number of grid boxes in the i-dimension. For a :literal:`LatLon` + grid this is the number of longitude grid-boxes. For a + :literal:`Cubed-Sphere` grid this is the cubed-sphere size (e.g., 48 + for C48). + +.. option:: JM_WORLD -:IM_WORLD: - The number of grid boxes in the i-dimension. For a :code:`LatLon` grid this is the number of longitude grid-boxes. For a :code:`Cubed-Sphere` grid this is the cubed-sphere size (e.g., 48 for C48). + The number of grid boxes in the j-dimension. For a + :literal:`LatLon` grid this is the number of latitude + grid-boxes. For a :literal:`Cubed-Sphere` grid this is six + times the cubed-sphere size (e.g., 288 for C48). -:JM_WORLD: - The number of grid boxes in the j-dimension. For a :code:`LatLon` grid this is the number of latitude grid-boxes. For a :code:`Cubed-Sphere` grid this is six times the cubed-sphere size (e.g., 288 for C48). +.. option:: POLE -:POLE: - Required if the grid type is :code:`LatLon`. :code:`POLE` defines the latitude coordinates of the grid. For global lat-lon grids the valid options are :code:`PC` (pole-centered) or :code:`PE` (polar-edge). Here, "center" or "edge" refers to whether the grid has boxes that are centered on the poles, or whether the grid has boxes with edges at the poles. For regional grids :code:`POLE` should be set to :code:`XY` and the grid will have boxes with edges at the regional boundaries. + Required if the grid type is :literal:`LatLon`. :literal:`POLE` defines + the latitude coordinates of the grid. For global lat-lon grids the + valid options are :literal:`PC` (pole-centered) or :literal:`PE` + (polar-edge). Here, "center" or "edge" refers to whether the grid + has boxes that are centered on the poles, or whether the grid has + boxes with edges at the poles. For regional grids :literal:`POLE` + should be set to :literal:`XY` and the grid will have boxes with edges + at the regional boundaries. -:DATELINE: - Required if the grid type is :code:`LatLon`. :code:`DATELINE` defines the longitude coordinates of the grid. For global - lat-lon grids the valid options are :code:`DC` (dateline-centered), :code:`DE` (dateline-edge), :code:`GC` (grenwich-centered), - or :code:`GE` (grenwich-edge). If :code:`DC` or :code:`DE`, then the longitude coordinates will span (-180°, 180°). If - :code:`GC` or :code:`GE`, then the longitude coordinates will span (0°, 360°). Similar to :code:`POLE`, "center" or "edge" - refer to whether the grid has boxes that are centered at -180° or 0°, or whether the grid has boxes with - edges at -180° or 0°. For regional grids :code:`DATELINE` should be set to `XY` and the grid will have boxes with - edges at the regional boundaries. +.. option:: DATELINE -:LON_RANGE: - Required for regional :code:`LatLon` grids. :code:`LON_RANGE` defines the longitude bounds of the regional grid. + Required if the grid type is :literal:`LatLon`. :literal:`DATELINE` + defines the longitude coordinates of the grid. For global lat-lon + grids the valid options are :literal:`DC` (dateline-centered), + :literal:`DE` (dateline-edge), :literal:`GC` (grenwich-centered), or + :literal:`GE` (Greenwich-edge). If :literal:`DC` or :literal:`DE`, + then the longitude coordinates will span (-180°, 180°). If + :literal:`GC` or :literal:`GE`, then the longitude coordinates will + span (0°, 360°). Similar to :literal:`POLE`, "center" or "edge" + refer to whether the grid has boxes that are centered at -180° or + 0°, or whether the grid has boxes with edges at -180° or 0°. For + regional grids :literal:`DATELINE` should be set to :literal:`XY` + and the grid will have boxes with edges at the regional + boundaries. -:LAT_RANGE: - Required for regional :code:`LatLon` grids. :code:`LAT_RANGE` defines the latitude bounds of the regional grid. +.. option:: LON_RANGE + Required for regional :literal:`LatLon` grids. :option:`LON_RANGE` + defines the longitude bounds of the regional grid. + +.. option:: LAT_RANGE + + Required for regional :literal:`LatLon` grids. :option:`LAT_RANGE` + defines the latitude bounds of the regional grid. .. _defining-active-collections: +=========================== Defining Active Collections ---------------------------- +=========================== -Collections are activated by defining them in the :code:`COLLECTIONS` list. For instructions on defining collections, see -:ref:`defining-collections`. +Collections are activated by defining them in the +:literal:`COLLECTIONS` list. For instructions on defining collections, +see :ref:`defining-collections`. - -Below is the format for the :code:`` section of :file:`HISTORY.rc`. +Below is the format for the :literal:`` +section of :file:`HISTORY.rc`. .. code-block:: none @@ -123,14 +191,16 @@ Below is the format for the :code:`` section of :file 'MyCollection2', :: -This example activates collections named "MyCollection1" and "MyCollection2". +This example activates collections named :literal:`MyCollection1` and +:literal:`MyCollection2`. .. _defining-collections: +==================== Defining Collections --------------------- +==================== -A collection is +A collection is .. code-block:: none @@ -149,83 +219,175 @@ A collection is -**Output file configuration** -:template: - This is the file name suffix for the collection. The path to the collection's files - is obtained by concatenating :code:`EXPID` with the collection name and the value of - :code:`template`. +Output file configuration +------------------------- + +.. option:: template -:format: - Defines the file format of the collection. Valid values are :code:`'CFIO'` for CF - compliant NetCDF (recommended), or :code:`'flat'` for GrADS style flat files. + This is the file name suffix for the collection. The path to the + collection's files is obtained by concatenating :option:`EXPID` + with the collection name and the value of :literal:`template`. -:duration: - Defines the frequency at which files are generated. The format is :code:`HHMMSS`. For example, :code:`1680000` means that a file is generated every 168 hours (7 days). +.. option:: format -:frequency: - Defines the time frequency of collection's data. Said another way, this defines the time separation (time step) of the time coordinate for the collection. The format is :code:`HHMMSS`. For example, :code:`010000` means that the collection's time coordinate will have a 1-hour time step. If :code:`frequency` is less than :code:`duration` multiple time steps are written to each file. + Defines the file format of the collection. Valid values are + :literal:`'CFIO'` for CF compliant NetCDF (recommended), or + :literal:`'flat'` for GrADS style flat files. -:monthly: *[optional]* - Set to :code:`1` for monthly output. One file per month is generated. If :code:`mode` is :code:`time-averaged`, the variables in the collection are 1-month time averages. Note that :code:`duration` and :code:`frequency` are not required if :code:`monthly: 1`. +.. option:: duration -:timeStampStart: *[optional]* - Only used if :code:`mode` is :code:`'time-averaged'`. If :code:`.true.` the file is timestamped according to the start of the accumulation interval (which depends on :code:`frequency`, :code:`ref_date`, and :code:`ref_time`). If :code:`.false.` the file is timestamped according to the middle of the accumulation interval. If :code:`timeStampStart` is not set then the default value is false. + Defines the frequency at which files are generated. The format is + :literal:`HHMMSS`. For example, :literal:`1680000` means that a + file is generated every 168 hours (7 days). -**Sampling configuration** +.. option:: frequency -:mode: - Defines the sampling method. Valid values are :code:`'time-averaged'` or :code:`'instantaneous'`. + Defines the time frequency of collection's data. Said another way, + this defines the time separation (time step) of the time coordinate + for the collection. The format is :literal:`HHMMSS`. For example, + :literal:`010000` means that the collection's time coordinate will + have a 1-hour time step. If :literal:`frequency` is less + than :option:`duration` multiple time steps are written + to each file. -:acc_interval: *[optional]* - Only valid if :code:`mode` is :code:`'time-averaged'`. This specifies the length of the time average. By default it is equal to :code:`frequency`. +.. option:: monthly -:ref_date: *[optional]* - The reference date from which the frequency is based. The format is :code:`YYYYMMDD`. For example, a frequency of :code:`1680000` (7 days) with a reference date of `20210101` means that the time coordinate will be weeks since 2021-01-01. The default value is the simulation's start date. + **OPTIONAL**. Set to :literal:`1` for monthly output. One file per + month is generated. If :literal:`mode` is :literal:`time-averaged`, + the variables in the collection are 1-month time averages. Note + that :option:`duration` and :option:`frequency` are not required + if :option:`monthly` is set to :literal:`1`. -:ref_time: *[optional]* - The reference time from which the frequency is based. The format is :code:`HHMMSS`. The default value is :code:`000000`. See :code:`ref_date`. +.. option:: timeStampStart -:fields: - Defines the list of fields that this collection should use. The format (per-field) is :code:`'FieldName', 'GridCompName',`. For example, :code:`'SpeciesConc_O3', 'GCHPchem',` specifies that this collection should include the `SpeciesConc_O3` field from the `GCHPchem` gridded component. + **OPTIONAL**. Only used if :option:`mode` is + :literal:`'time-averaged'`. If :literal:`.true.` the file is + timestamped according to the start of the accumulation interval + (which depends on :option:`frequency`, :option:`ref_date`, and + :option:`ref_time`). If :literal:`.false.` the file is timestamped + according to the middle of the accumulation interval. If + :option:`timeStampStart` is not set then the default value is false. - Fields from multiple gridded components can be included in the same collection. However, a collection must not mix fields that are defined at the center of vertical levels and the edges of vertical levels (e.g., `Met_PMID` and `Met_PEDGE` cannot be included in the same collection). +Sampling configuration +-------------------------- - Variables can be renamed in the output by adding :code:`'your_custom_name',` at the end. For example, :code:`'SpeciesConc_O3', 'GCHPchem', 'ozone_concentration',` would rename the SpeciesConc_O3 field to "ozone_concentration" in the output file. +.. option:: mode -**Output grid configuration** + Defines the sampling method. Valid values are + :literal:`'time-averaged'` or :literal:`'instantaneous'`. -:grid_label: *[optional]* - Defines the grid that this collection should be output on. The lable must match on of the grid labels defined in :ref:`\ `. If :code:`grid_label` isn't set then the collection uses the simulation's horizontal grid. +.. option:: acc_interval -:conservative: *[optional]* - Defines whether or not regridding to the output grid should use ESMF's first-order conservative method. Valid values are :code:`0` or :code:`1`. It is recommended you set this to :code:`1` if you are using :code:`grid_label`. The default value is :code:`0`. + **OPTIONAL**. Only valid if :literal:`mode` is + :literal:`'time-averaged'`. This specifies the length of the time + average. By default it is equal to :literal:`frequency`. -:levels: *[optional]* - Defines the model levels that this collection should use (i.e., a subset of the simulation levels). The format is a space-separated list of values. The lowest layer is 1 and the highest layer is 72. For example, :code:`1 2 5` would select the first, second, and fifth level of the simulation. +.. option:: ref_date: -:track_file: *[optional]* - Defines the path to a 1D track file along which the collection is sampled. See :ref:`output-along-a-track` for more info. + **OPTIONAL**. The reference date from which the frequency is + based. The format is :literal:`YYYYMMDD`. For example, a frequency + of :literal:`1680000` (7 days) with a reference date of `20210101` + means that the time coordinate will be weeks since 2021-01-01. The + default value is the simulation's start date. -:recycle_track: *[optional]* - Only valid if a :code:`track_file` is defined. Specifies that the track file should be reused every day. If :code:`.true.` the dates in the track file are automatically forced to the simulation's current date. The default value is false. +.. option:: ref_time -**Other configuration** + **OPTIONAL**. The reference time from which the frequency is + based. The format is :literal:`HHMMSS`. The default value is + :literal:`000000`. See :literal:`ref_date`. -:end_date: *[optional]* - A date at which the collection is deactivated (turned off). By default there is no end date. +.. option:: fields -:end_time: *[optional]* - Time at which the collection is deactivated (turned off) on the :code:`end_date`. + Defines the list of fields that this collection should use. The + format (per-field) is :literal:`'FieldName', 'GridCompName',`. For + example, :literal:`'SpeciesConcVV_O3', 'GCHPchem',` specifies that + this collection should include the :literal:`SpeciesConcVV_O3` + field from the `GCHPchem` gridded component. + Fields from multiple gridded components can be included in the same + collection. However, a collection must not mix fields that are + defined at the center of vertical levels and the edges of vertical + levels (e.g., :literal:`Met_PMID` and :literal:`Met_PEDGE` cannot + be included in the same collection). + Variables can be renamed in the output by adding + :literal:`'your_custom_name',` at the end. For example, + :literal:`'SpeciesConc_O3', 'GCHPchem', + 'ozone_concentration',` would rename the :literal:`SpeciesConc_O3` + field to "ozone_concentration" in the output file. + + +Output grid configuration +------------------------- + +.. option:: grid_label + + **OPTIONAL**. Defines the grid that this collection should be + output on. The lable must match on of the grid labels defined in + :ref:`\ `. If + :option:`grid_label` isn't set then the collection uses the + simulation's horizontal grid. + +.. option:: conservative + + **OPTIONAL**. Defines whether or not regridding to the output grid + should use ESMF's first-order conservative method. Valid values are + :literal:`0` or :literal:`1`. It is recommended you set this to + :literal:`1` if you are using :option:`grid_label`. The default + value is :literal:`0`. + +.. option:: levels: + + **OPTIONAL**. Defines the model levels that this collection should + use (i.e., a subset of the simulation levels). The format is a + space-separated list of values. The lowest layer is 1 and the + highest layer is 72. For example, :literal:`1 2 5` would select the + first, second, and fifth level of the simulation. + +.. option:: track_file + + **OPTIONAL**. Defines the path to a 1D track file along which the + collection is sampled. See :ref:`output-along-a-track` for more + info. + +.. option:: recycle_track + + **OPTIONAL**. Only valid if a :option:`track_file` is + defined. Specifies that the track file should be reused every + day. If :literal:`.true.` the dates in the track file are + automatically forced to the simulation's current date. The default + value is false. + +Other configuration +------------------- + +.. option:: end_date + + **OPTIONAL**. A date at which the collection is deactivated (turned + off). By default there is no end date. + +.. option:: end_time + + **OPTIONAL**. Time at which the collection is deactivated (turned + off) on the :literal:`end_date`. + +======================================== Example :file:`HISTORY.rc` configuration ----------------------------------------- +======================================== Below is an example :file:`HISTORY.rc` that configures two output collection -1. 30-min instantaneous concentrations of O3, NO, NO2, and some meteorological parameters for the lowest 10 model levels on a 0.1°x0.1° covering the US. Each file contains one day of data. -2. 24-hour time averages of O3, NO, and NO2 concentrations, NO emissions, and some meteorological parameters. The horizontal grid is the simulation's grid. All vertical levels are use. Each file contains one week worth of data, and files are generated relative to 2017-01-01. +#. 30-min instantaneous concentrations of O3, NO, NO2, and some + meteorological parameters for the lowest 10 model levels on a + 0.1°x0.1° covering the US. Each file contains one day of data. |br| + |br| + +#. 24-hour time averages of O3, NO, and NO2 concentrations, NO + emissions, and some meteorological parameters. The horizontal grid + is the simulation's grid. All vertical levels are use. Each file + contains one week worth of data, and files are generated relative + to 2017-01-01. .. code-block:: none diff --git a/docs/source/user-guide/config-files/cap_restart.rst b/docs/source/user-guide/config-files/cap_restart.rst new file mode 100644 index 000000000..4230ba18b --- /dev/null +++ b/docs/source/user-guide/config-files/cap_restart.rst @@ -0,0 +1,35 @@ +.. _cap-restart: + +########### +cap_restart +########### + +This file contains a single datetime in :literal:`YYYYMMDD hhmmss` +format. The datetime specifies the restart file that will be read +from disk at the start of the GCHP simulation. + +Let's consider an example. Say you are going to run a 1-day GCHP +simulation starting at 00 GMT on 2019-07-01. The +:ref:`set-common-run-settings.sh` script---when run manually, or +called your GCHP run script---will set the datetime in +:file:`cap_restart` to: + +.. code-block:: none + + 20190701 000000 + +as this is the starting datetime for the simulation. + +GCHP will update the :file:`cap_restart` file upon sucessful +completion so that it now contains the date when the restart file was +last written: + +.. code-block:: none + + 20190702 000000 + +This assumes that the next job segment will start on date 2019-07-02. + +If you wish to re-run for 2019-07-01, you must change the datetime in +:file:`cap_restart` back to :literal:`20190701 000000`. Otherwise it +will read the restart file for 2019-07-02. diff --git a/docs/source/user-guide/config-files/geoschem_config_yml.rst b/docs/source/user-guide/config-files/geoschem_config_yml.rst deleted file mode 100644 index 1308f9d95..000000000 --- a/docs/source/user-guide/config-files/geoschem_config_yml.rst +++ /dev/null @@ -1,14 +0,0 @@ -geoschem_config.yml -=================== - -Information about the :file:`geoschem_config.yml` file is the same as for GEOS-Chem Classic with a few exceptions. -See the `GEOS-Chem ReadTheDocs page for this file `_ for a detailed description of the file.. - -The :file:`geoschem_config.yml` file used in GCHP is different in the following ways: - -* Start/End datetimes are excluded. Start time is section :file:`cap_restart` and duration is set in :file:`setCommonRunSettings.sh`. -* Root data directory is excluded. All data paths are specified in :file:`ExtData.rc` instead with the exception of the photolysis data directory which is still listed (and used) in :file:`geoschem_config.yml`. -* Met field is excluded. Met field source is described in file paths in :file:`ExtData.rc`. -* GC classic timers setting is excluded. GEOS-Chem Classic timers code is not compiled when building GCHP. MAPL handles timers in GCHP. - -Other parts of the GEOS-Chem Classic :file:`geoschem_config.yml` file that are not relevant to GCHP are simply not included in the file that is copied to the GCHP run directory. Everything you see in the file handled the same as in GEOS-Chem Classic. diff --git a/docs/source/user-guide/config-files/input_nml.rst b/docs/source/user-guide/config-files/input_nml.rst index e8b4d6198..84d08ff03 100644 --- a/docs/source/user-guide/config-files/input_nml.rst +++ b/docs/source/user-guide/config-files/input_nml.rst @@ -1,28 +1,66 @@ +.. _input-nml: + +######### input.nml -========= +######### + +:file:`input.nml` controls specific aspects of the FV3 dynamical core +used for advection. Entries in input.nml are described below. + +.. option:: &fms_nml + + Header for the FMS namelist which includes all variables directly + below the header. + +.. option:: print_memory_usage + + Toggles memory usage prints to log. However, in practice turning it + on or off does not have any effect. + +.. option:: domain_stack_size + + Domain stack size in bytes. This is set to :literal:`20000000` in + GCHP to be large enough to use very few cores in a high resolution + run. If the domain size is too small then you will get an + + .. code-block:: none + + mpp domain stack size overflow error + + in advection. If this happens, try increasing the domain stack size + in this file. + +.. option:: &fv_core_nml -input.nml controls specific aspects of the FV3 dynamical core used for advection. Entries in input.nml are described below. + Header for the finite-volume dynamical core namelist. This is + commented out by default unless running on a stretched grid. Due to + the way the file is read, commenting out the header declaration + requires an additional comment character within the string, + e.g. :literal:`#&fv#_core_nml`. -&fms_nml - Header for the FMS namelist which includes all variables directly below the header. +.. option:: do_schmidt -print_memory_usage - Toggles memory usage prints to log. However, in practice turning it on or off does not have any effect. + Logical for whether to use Schmidt advection. Set to :literal:`.true.` if + using stretched grid; otherwise this entry is commented out. -domain_stack_size - Domain stack size in bytes. This is set to 20000000 in GCHP to be large enough to use very few cores in a high resolution run. If the domain size is too small then you will get an "mpp domain stack size overflow error" in advection. If this happens, try increasing the domain stack size in this file. +.. option:: stretch_fac -&fv_core_nml - Header for the finite-volume dynamical core namelist. This is commented out by default unless running on a stretched grid. Due to the way the file is read, commenting out the header declaration requires an additional comment character within the string, e.g. :literal:`#&fv#_core_nml`. + Stretched grid factor, equal to the ratio of grid resolution in + targeted high resolution region to the configured run + resolution. This is commented out if not using stretched grid. It + is automatically updated based on settings in + :ref:`set-common-run-settings-sh`. -do_schmidt - Logical for whether to use Schmidt advection. Set to .true. if using stretched grid; otherwise this entry is commented out. +.. option:: target_lat -stretch_fac - Stretched grid factor, equal to the ratio of grid resolution in targeted high resolution region to the configured run resolution. This is commented out if not using stretched grid. It is automatically updated based on settings in :file:`setCommonRunSettings.sh`. + Target latitude of high resolution region if using stretched + grid. This is commented out if not using stretched grid. It is + automatically updated based on settings in + :ref:`set-common-run-settings-sh`. -target_lat - Target latitude of high resolution region if using stretched grid. This is commented out if not using stretched grid. It is automatically updated based on settings in :file:`setCommonRunSettings.sh`. +.. option:: target_lon -target_lon - Target longitude of high resolution region if using stretched grid. This is commented out if not using stretched grid. It is automatically updated based on settings in :file:`setCommonRunSettings.sh`. + Target longitude of high resolution region if using stretched + grid. This is commented out if not using stretched grid. It is + automatically updated based on settings in + :ref:`set-common-run-settings-sh`. diff --git a/docs/source/user-guide/config-files/logging_yml.rst b/docs/source/user-guide/config-files/logging_yml.rst index 4b2305bfc..139ae1644 100644 --- a/docs/source/user-guide/config-files/logging_yml.rst +++ b/docs/source/user-guide/config-files/logging_yml.rst @@ -1,11 +1,27 @@ +.. _logging-yml: + +########### logging.yml -=========== +########### -The :file:`logging.yml` file is the configuration file for the pFlogger logging package used in GCHP. This package is a Fortran logger written and maintained by NASA Goddard. The pFlogger package is based on python logging and contains functions and classes that enable flexible event logging within GCHP components, including MAPL ExtData which handles input read. +The :file:`logging.yml` file is the configuration file for the +pFlogger logging package used in GCHP. This package is a Fortran +logger written and maintained by NASA Goddard. The pFlogger package is +based on python logging and contains functions and classes that enable +flexible event logging within GCHP components, including MAPL ExtData +which handles input read. -GCHP logging is not the same as GEOS-Chem and HEMCO prints that go to the main GCHP log. It is hierarchical based on the severity of the event, with the level of severity per component used as criteria to print to the log file. The logging messages are sent to a separate file from the main GCHP log. The filename is specified in :file:`logging.yml` as :file:`allPEs.log` by default in the definition of the :literal:`mpi_shared` file handler. +GCHP logging is not the same as GEOS-Chem and HEMCO prints that go to +the main GCHP log. It is hierarchical based on the severity of the +event, with the level of severity per component used as criteria to +print to the log file. The logging messages are sent to a separate +file from the main GCHP log. The filename is specified in +:file:`logging.yml` as :file:`allPEs.log` by default in the definition +of the :literal:`mpi_shared` file handler. -Like the python logger, there are five levels of severity used to trigger messages. These are as follows, in order of most to least severe: +Like the python logger, there are five levels of severity used to +trigger messages. These are as follows, in order of most to least +severe: #. CRITICAL #. ERROR @@ -13,13 +29,43 @@ Like the python logger, there are five levels of severity used to trigger messag #. INFO #. DEBUG -These levels are hierarchical, meaning each level triggers writing messages for all events with greater or equal severity. For example, if you specify :file:`CRITICAL` you will get only messages triggered with that criteria since it is the most severe level. If you instead specify :literal:`WARNING` then you will trigger all events categorized as :literal:`WARNING`, :literal:`ERROR`, and :literal:`CRITICAL`. - -Different GCHP components can have different levels of severity. These components are listed in the :literal:`loggers` section of the file. This helps hone in on problems you are experiencing in a specific component by allowing you to increase logger messages for one component only. This is particularly useful for debugging the component called :literal:`CAP.EXTDATA` in :file:`logging.yml` which corresponds to the MAPL component that handles reading and regridding input files. When you experience a problem reading input files we recommend that you set the logger level for this component to :file:`DEBUG`. +These levels are hierarchical, meaning each level triggers writing +messages for all events with greater or equal severity. For example, +if you specify :file:`CRITICAL` you will get only messages triggered +with that criteria since it is the most severe level. If you instead +specify :literal:`WARNING` then you will trigger all events +categorized as :literal:`WARNING`, :literal:`ERROR`, and +:literal:`CRITICAL`. -In addition to setting severity level per component you can also specify severity level based on processor. There are two options: root thread only and all threads. The root thread only option is :file:`root_level` in the configuration file and will only trigger messages if the event is executed by the root processor. Using this option keeps the log file size down and can make reading the file easier. We recommend setting this option to :literal:`DEBUG` when investigating problems with input files. +Different GCHP components can have different levels of severity. These +components are listed in the :literal:`loggers` section of the +file. This helps hone in on problems you are experiencing in a +specific component by allowing you to increase logger messages for one +component only. This is particularly useful for debugging the +component called :literal:`CAP.EXTDATA` in :file:`logging.yml` which +corresponds to the MAPL component that handles reading and regridding +input files. When you experience a problem reading input files we +recommend that you set the logger level for this component to +:file:`DEBUG`. -The all threads option will log events for all processors. Each message will be prefixed by the processor number, e.g. :literal:`0000` for the root thread, :literal:`0001` for the next, and so on. Using this option can make the file size very large and difficult to read. However, you can grep the file for a processor number to isolate events of just one thread of interest, such as the one that appears in error message traceback. +In addition to setting severity level per component you can also +specify severity level based on processor. There are two options: root +thread only and all threads. The root thread only option is +:file:`root_level` in the configuration file and will only trigger +messages if the event is executed by the root processor. Using +this option keeps the log file size down and can make reading +the file easier. We recommend setting this option to +:literal:`DEBUG` when investigating problems with input files. -For more information on the GCHP logger, including more advanced features, see documentation at `https://github.com/Goddard-Fortran-Ecosystem/pFlogger/ `_. +The all threads option will log events for all processors. Each +message will be prefixed by the processor number, e.g. :literal:`0000` +for the root thread, :literal:`0001` for the next, and so on. Using +this option can make the file size very large and difficult to +read. However, you can grep the file for a processor number to isolate +events of just one thread of interest, such as the one that appears in +error message traceback. +For more information on the GCHP logger, including more advanced +features, see documentation at +`https://github.com/Goddard-Fortran-Ecosystem/pFlogger/ +`_. diff --git a/docs/source/user-guide/config-files/setCommonRunSettings_sh.rst b/docs/source/user-guide/config-files/setCommonRunSettings_sh.rst index fe968affe..09944458c 100644 --- a/docs/source/user-guide/config-files/setCommonRunSettings_sh.rst +++ b/docs/source/user-guide/config-files/setCommonRunSettings_sh.rst @@ -1,9 +1,23 @@ +.. _set-common-run-settings-sh: + +####################### setCommonRunSettings.sh -======================= +####################### + +This file is a bash script to specify run-time values for commonly +changed settings and update other configuration files that set +them. This is intended as a helper script to make configuring GCHP +runs easier. There are four sections of the file: -This file is a bash script to specify run-time values for commonly changed settings and update other configuration files that set them. This is intended as a helper script to make configuring GCHP runs easier. There are four sections of the file: (1) configuration, (2) error checks, (3) helper functions, and (4) update files. +#. Configuration; +#. Error checks +#. Helper functions +#. Update files -The commonly changed settings section at the very top of the file is usually the only part you need to look at and change. The configuration section itself is divided into two parts. The first part contains the most frequently changed settings. Categories are: +The commonly changed settings section at the very top of the file is +usually the only part you need to look at and change. The +configuration section itself is divided into two parts. The first part +contains the most frequently changed settings. Categories are: * Compute resources * Grid resolution @@ -13,22 +27,49 @@ The commonly changed settings section at the very top of the file is usually the * Diagnostics * Mid-run checkpoint files * Requiring all species in the initial restart file - -The second part contains settings that are less frequently changed but that are still convenient to update from one place. These include: + +The second part contains settings that are less frequently changed but +that are still convenient to update from one place. These include: * Model phase (e.g. adjoint vs forward model) * Timesteps * Online dust mass tuning factor * Domain decomposition -The entire configuration section contains many comments with instructions on how to change the settings and what the options are. Please see that file for more information. +The entire configuration section contains many comments with +instructions on how to change the settings and what the options +are. Please see that file for more information. -The error checks section checks to make sure the run directory settings make sense and will not cause an early crash due to a simple mistake, such as a core count that is not divisible by 6 or a subdomain size that is less than the minimum 4x4 required by FV3 advection. +The error checks section checks to make sure the run directory +settings make sense and will not cause an early crash due to a simple +mistake, such as a core count that is not divisible by 6 or a +subdomain size that is less than the minimum 4x4 required by FV3 +advection. -The helper functions section contains several functions to simplify updating configuration files based on the settings you specified in the configurations section earlier in the script. Some of the functions are general, such as printing a message during file update based on if the script was passed optional argument :literal:`--verbose`. Other functions are specialized, such as replacing met-field read frequency in :file:`ExtData.rc` based on the model timestep. +The helper functions section contains several functions to simplify +updating configuration files based on the settings you specified in +the configurations section earlier in the script. Some of the +functions are general, such as printing a message during file update +based on if the script was passed optional argument +:literal:`--verbose`. Other functions are specialized, such as +replacing met-field read frequency in :ref:`extdata` +based on the model timestep. -The update files section changes settings in other configuration files based on what you set in the configurables section. You can browse this section to see exactly what files are changed. You can also view this information by running the script with the :literal:`--verbose` option. +The update files section changes settings in other configuration files +based on what you set in the configurables section. You can browse +this section to see exactly what files are changed. You can also view +this information by running the script with the :literal:`--verbose` +option. -Using the :file:`setCommonRunSettings.sh` script is technically optional to run GCHP. However, we highly recommend using it to avoid mistakes in your run directory setup. Knowing which configuration files need to be changed for which run-time settings and then changing them all manually is cumbersome and error-prone. We hope that using this file will make it easier to use GCHP without making mistakes. It is included in all GCHP run scripts provided within the :file:`runScriptSamples` subdirectory that comes with the GCHP run directory. +Using the :file:`setCommonRunSettings.sh` script is technically +optional to run GCHP. However, we highly recommend using it to avoid +mistakes in your run directory setup. Knowing which configuration +files need to be changed for which run-time settings and then changing +them all manually is cumbersome and error-prone. We hope that using +this file will make it easier to use GCHP without making mistakes. It +is included in all GCHP run scripts provided within the +:file:`runScriptSamples` subdirectory that comes with the GCHP run +directory. -For details about how to change settings please read the comments included within the file. +For details about how to change settings please read the comments +included within the file. diff --git a/docs/source/user-guide/configuration-files.rst b/docs/source/user-guide/configuration-files.rst index c0c3490ba..849f2361f 100644 --- a/docs/source/user-guide/configuration-files.rst +++ b/docs/source/user-guide/configuration-files.rst @@ -34,13 +34,16 @@ on this page for a high-level summary of all configuration files. config-files/setCommonRunSettings_sh.rst config-files/GCHP_rc.rst config-files/CAP_rc.rst + config-files/cap_restart.rst config-files/ExtData_rc.rst - config-files/geoschem_config_yml.rst - config-files/HEMCO_Config_rc.rst + ../../geos-chem-shared-docs/doc/geoschem-config.rst + ../../geos-chem-shared-docs/doc/hemco-config.rst config-files/input_nml.rst config-files/logging_yml.rst config-files/HISTORY_rc.rst - config-files/HEMCO_Diagn_rc.rst + ../../geos-chem-shared-docs/doc/hemco-diagn.rst + ../../geos-chem-shared-docs/doc/spec-db.rst + ../../geos-chem-shared-docs/doc/phot-chem.rst ================== High-level summary @@ -48,21 +51,26 @@ High-level summary This high-level summary of GCHP configuration files gives a short description of each file. -:file:`CAP.rc` - Controls parameters used by the highest level gridded component (CAP). - This includes simulation run time information, name of the Root - gridded component (GCHP), config filenames for Root and History, - and toggles for certain MAPL logging utilities - (timers, memory, and import/export name printing). Values are - automatically set from settings in :file:`setCommonRunSetting.sh`. +:ref:`cap-rc` + Controls parameters used by the highest level gridded component + (:program:`CAP`). This includes simulation run time information, + name of the Root gridded component (:program:`GCHP`), config + filenames for :program:`ROOT` and :program:`HISTORY`, and toggles + for certain MAPL logging utilities (timers, memory, and + import/export name printing). Values are automatically set from + settings in :ref:`set-common-run-settings-sh`. + +:ref:`cap-restart` + Contains the datetime (in :literal:`YYYYMMDD hhmmss` format) of the + restart file that will be read by GCHP at simulation startup. :file:`ESMF.rc` Controls the logging level of ESMF. By default this file specifies no log output for ESMF. See the file for available options you can set at run-time. -:file:`ExtData.rc` - Config file for the MAPL ExtData component. Specifies input +:ref:`extdata-rc` + Config file for the MAPL :program:`ExtData` component. Specifies input variable information, including name, regridding method, read frequency, offset, scaling, and file path. All GCHP imports must be specified in this file. Toggles at the top of the file enable MAPL @@ -70,55 +78,67 @@ This high-level summary of GCHP configuration files gives a short description of data is unavailable. Default values may be used by specifying file path :file:`/dev/null`. -:file:`GCHP.rc` +:ref:`gchp-rc` Controls high-level aspects of the simulation, including grid type and resolution, core distribution, stretched-grid parameters, timesteps, and restart filename. Values are automatically set from - settings in :file:`setCommonRunSettings.sh`. + settings in :ref:`set-common-run-settings-sh`. -:file:`geoschem_config.yml` +:ref:`cfg-gc-yml` Primary config file for GEOS-Chem. Same file format as in GEOS-Chem Classic but containing only options relevant to GCHP. Some fields are automatically updated from settings in - :file:`setCommonRunSettings.sh`. - -:file:`HEMCO_Config.rc` - Contains emissions information used by HEMCO. - Same function as in GEOS-Chem Classic except only HEMCO name, species, scale IDs, category, and hierarchy are used. - Diagnostic frequency, file path, read frequency, and units are ignored, and are instead stored in - GCHP config file :file:`ExtData.rc`. - All HEMCO variables listed in :file:`HEMCO_Config.rc` for enabled emissions must also have an entry in :file:`ExtData.rc`. - -:file:`HEMCO_Diagn.rc` - Contains information mapping :file:`HISTORY.rc` diagnostic names to + :ref:`set-common-run-settings-sh`. + +:ref:`cfg-hco-cfg` + Contains emissions information used by `HEMCO + `_. Same function as in `GEOS-Chem + Classic `_ except only HEMCO + name, species, scale IDs, category, and hierarchy are + used. Diagnostic frequency, file path, read frequency, and units + are ignored, and are instead stored in GCHP config file + :ref:`extdata-rc`. All HEMCO variables listed in + :file:`cfg-hco-cfg` for enabled emissions must also have an entry + in :file:`extdata-rc`. + +:ref:`cfg-hco-diagn` + Contains information mapping :ref:`history-rc` diagnostic names to HEMCO containers. Same function as in GEOS-Chem Classic except - that not all items in :file:`HEMCO_Diagn.rc` will be output; only - emissions listed in :file:`HISTORY.rc` will be included in - diagnostics. All GCHP diagnostics listed in :file:`HISTORY.rc` - that start with Emis, Hco, or Inv must have a corresponding entry - in :file:`HEMCO_Diagn.rc`. - -:file:`HISTORY.rc` - Config file for the MAPL History component. It configures - diagnostic output from GCHP. There is an option in - :file:`setCommonRunSettings.sh` to auto-update this file based on + that not all items in :ref:`cfg-hco-cfg` will be output; + only emissions listed in :ref:`history-rc` will be included in + diagnostics. All GCHP diagnostics listed in :ref:`history-rc` that + start with :literal:`Emis`, :literal:`Hco`, or :literal:`Inv` must + have a corresponding entry in :ref:`cfg-hco-diagn`. + +:ref:`history-rc` + Config file for the MAPL :program:`HISTORY` component. It + configures diagnostic output from GCHP. There is an option in + :ref:`set-common-run-settings-sh` to auto-update this file based on settings configured there, including duration, frequency, and which collections to update. -:file:`input.nml` + Please see our :ref:`history-diag-guide` supplemental guide for a + list of GEOS-Chem diagnostic collections. + +:ref:`input-nml` Namelist used in advection for domain stack size and stretched grid parameters. Users should not need to update this. -:file:`logging.yml` +:ref:`logging-yml` Config file for the NASA MAPL logger package included in GCHP for - logging. This package uses a hierarchy of loggers, such as info, warnings, - error, and debug, to extract non-GEOS-Chem information about GCHP - runs and print it to log file :file:`allPEs.log`. Use this file to - debug problems with data inputs. + logging. This package uses a hierarchy of loggers, such as info, + warnings, error, and debug, to extract non-GEOS-Chem information + about GCHP runs and print it to log file :file:`allPEs.log`. Use + this file to debug problems with data inputs. -:file:`setCommonRunSettings.sh` +:ref:`set-common-run-settings-sh` This file is a bash script where you can set commonly changed run settings. It auto-updates other configuration files when it is sourced. It makes it easier to manage configuring GCHP since settings can be changed from one file rather than across multiple configuration files. + +:ref:`cfg-spec-db` + The GEOS-Chem Species Database, a YAML file containing species + metadata. You will not need to modify this unless you add or + remove species from one of the GEOS-Chem chemistry mechanisms. From 074639b9ab48fec2e9c731f38d6be3e6b417cb5d Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 1 Oct 2024 16:36:43 -0400 Subject: [PATCH 28/41] RTD Update: Fix typo in cap_restart doc page docs/source/user-guide/config-files/cap_restart - Fixed typo ":ref:`set-common-run-settings.sh`" -> ":ref:`set-common-run-settings-sh`". Signed-off-by: Bob Yantosca --- docs/source/user-guide/config-files/cap_restart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/user-guide/config-files/cap_restart.rst b/docs/source/user-guide/config-files/cap_restart.rst index 4230ba18b..5ce798b97 100644 --- a/docs/source/user-guide/config-files/cap_restart.rst +++ b/docs/source/user-guide/config-files/cap_restart.rst @@ -10,7 +10,7 @@ from disk at the start of the GCHP simulation. Let's consider an example. Say you are going to run a 1-day GCHP simulation starting at 00 GMT on 2019-07-01. The -:ref:`set-common-run-settings.sh` script---when run manually, or +:ref:`set-common-run-settings-sh` script---when run manually, or called your GCHP run script---will set the datetime in :file:`cap_restart` to: From 37f37d2e217a54d1bbfe56b51410ca52a9c95557 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 1 Oct 2024 16:43:56 -0400 Subject: [PATCH 29/41] Update text in cap_restart for clarity docs/source/user-guide/config-files/cap_restart - Updated the text so that it flows better and is less awkward Signed-off-by: Bob Yantosca --- .../user-guide/config-files/cap_restart.rst | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/source/user-guide/config-files/cap_restart.rst b/docs/source/user-guide/config-files/cap_restart.rst index 5ce798b97..4cd499cdb 100644 --- a/docs/source/user-guide/config-files/cap_restart.rst +++ b/docs/source/user-guide/config-files/cap_restart.rst @@ -6,12 +6,12 @@ cap_restart This file contains a single datetime in :literal:`YYYYMMDD hhmmss` format. The datetime specifies the restart file that will be read -from disk at the start of the GCHP simulation. +from disk at the start of the GCHP simulation. It also overrides the +value of :option:`BEG_DATE` specified in :ref:`cap-rc`. Let's consider an example. Say you are going to run a 1-day GCHP simulation starting at 00 GMT on 2019-07-01. The -:ref:`set-common-run-settings-sh` script---when run manually, or -called your GCHP run script---will set the datetime in +:ref:`set-common-run-settings-sh` script will set the datetime in :file:`cap_restart` to: .. code-block:: none @@ -20,16 +20,16 @@ called your GCHP run script---will set the datetime in as this is the starting datetime for the simulation. -GCHP will update the :file:`cap_restart` file upon sucessful -completion so that it now contains the date when the restart file was -last written: +Upon successful completion of the GCHP simulation, the +:file:`cap_restart` file is updated to contains the date when the +restart was last written (which is the same as the end date of the +previous simulation): .. code-block:: none 20190702 000000 -This assumes that the next job segment will start on date 2019-07-02. - If you wish to re-run for 2019-07-01, you must change the datetime in -:file:`cap_restart` back to :literal:`20190701 000000`. Otherwise it -will read the restart file for 2019-07-02. +:file:`cap_restart` back to :literal:`20190701 000000`. Otherwise, +GCHP will read the restart file for 2019-07-02 once the next +simulation starts. From 9b5b6296dca13b2b171493a22e8fe7d00d32358c Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 2 Oct 2024 10:53:26 -0400 Subject: [PATCH 30/41] Minor updates in config file doc; Update geos-chem-shared-docs docs/source/geos-chem-shared-docs - Added GCHP vs. GCC usage differences section in HEMCO_Diagn.rc doc docs/source/user-guide/configuration-files.rst - Now use reference links to the setCommonRunSettings.sh doc in the NOTE at the top of the page - Now split the configuration files into "Commonly-updated configuration files" and "Less commonly-updated configuration files" to make it clear that some config files don't normally need to be updated except under certain circumstances. - Trimmed whitespace Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- .../source/user-guide/configuration-files.rst | 34 ++++++++++++++----- 2 files changed, 27 insertions(+), 9 deletions(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index b5420bbb7..9c7903d51 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit b5420bbb77f9fea9b26cc36785c441883295b029 +Subproject commit 9c7903d5135e82f939b53ae152db2357a23cb274 diff --git a/docs/source/user-guide/configuration-files.rst b/docs/source/user-guide/configuration-files.rst index 849f2361f..3474f4b78 100644 --- a/docs/source/user-guide/configuration-files.rst +++ b/docs/source/user-guide/configuration-files.rst @@ -13,9 +13,9 @@ wish to learn more. The many configuration files in GCHP can be overwhelming. However, you should be able to accomplish most if not all of what you wish to configure from one place in - :file:`setCommonRunSettings.sh`. That file is a bash script used to - configure settings in other files from one place. Please get - very familiar with the options in :file:`setCommonRunSettings.sh` + :ref:`set-common-run-settings-sh`. That file is a bash script used + to configure settings in other files from one place. Please get + very familiar with the options in :ref:`set-common-run-settings-sh` by reading through the configuration section of the file. Be conscientious about not updating the same setting elsewhere. @@ -28,6 +28,14 @@ found in the following pages. You can also reach these pages by continuing with the "next" button in this user guide. See further down on this page for a high-level summary of all configuration files. +Commonly-updated configuration files +------------------------------------ + +Here is a list of the configuration files containing the various input +options for your GCHP simulation. You can specify most of the +relevant settings in the :ref:`set-common-run-settings-sh` script, +which will edit the other configuration files accordingly. + .. toctree:: :maxdepth: 1 @@ -38,10 +46,20 @@ on this page for a high-level summary of all configuration files. config-files/ExtData_rc.rst ../../geos-chem-shared-docs/doc/geoschem-config.rst ../../geos-chem-shared-docs/doc/hemco-config.rst - config-files/input_nml.rst - config-files/logging_yml.rst - config-files/HISTORY_rc.rst ../../geos-chem-shared-docs/doc/hemco-diagn.rst + config-files/HISTORY_rc.rst + config-files/logging_yml.rst + +Less-commonly-updated configuration files +----------------------------------------- + +You will not typically need to modify these files unless you are +adding new species or modifying chemistry reactions, etc. + +.. toctree:: + :maxdepth: 1 + + config-files/input_nml.rst ../../geos-chem-shared-docs/doc/spec-db.rst ../../geos-chem-shared-docs/doc/phot-chem.rst @@ -117,8 +135,8 @@ This high-level summary of GCHP configuration files gives a short description of settings configured there, including duration, frequency, and which collections to update. - Please see our :ref:`history-diag-guide` supplemental guide for a - list of GEOS-Chem diagnostic collections. + Please see our :ref:`histguide` supplemental guide for a list of + GEOS-Chem diagnostic collections. :ref:`input-nml` Namelist used in advection for domain stack size and stretched grid From 9cf02efba9ca080494c1f88389a091d8d72b4176 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 2 Oct 2024 10:59:21 -0400 Subject: [PATCH 31/41] geos-chem-shared-docs update: Fixed typo in geoschem_config.yml doc docs/source/geos-chem-shared-docs: - Fixed typo ":ref:`ExtData.rc`" -> ":file:`ExtData.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 9c7903d51..8ed145c6c 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit 9c7903d5135e82f939b53ae152db2357a23cb274 +Subproject commit 8ed145c6c813b325c6101392f7ff6e203f851d9b From 07aea1ec4e6d5d5e1e9bcf4d4914b5a03a7d10d5 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 2 Oct 2024 17:10:30 -0400 Subject: [PATCH 32/41] ReadTheDocs update: Update formatting & links in more files docs/source/user-guide/compiling.rst docs/source/user-guide/getting-input-data.rst docs/source/user-guide/running.rst - Updated formatting using ReST best practices - Link to pages with references where expedient - Trim trailing whitespace Signed-off-by: Bob Yantosca --- docs/source/user-guide/compiling.rst | 449 +++++++++++------- docs/source/user-guide/getting-input-data.rst | 110 +++-- docs/source/user-guide/running.rst | 235 ++++++--- 3 files changed, 505 insertions(+), 289 deletions(-) diff --git a/docs/source/user-guide/compiling.rst b/docs/source/user-guide/compiling.rst index 64518f604..242ba028e 100644 --- a/docs/source/user-guide/compiling.rst +++ b/docs/source/user-guide/compiling.rst @@ -1,50 +1,75 @@ -.. note:: - Compiling GCHP and creating a run directory are independent steps, and their order doesn't matter. A small exception - is the :ref:`RUNDIR ` build option, which controls the behaviour of :command:`make install` which copies the GCHP executable to the run directory; - however, this setting can be reconfigured at any time (e.g., after compiling and creating a run directory). - - Here in the User Guide we describe compiling GCHP before we describe creating a run directory. This is - so that conceptually the instructions have a linear flow. The Quickstart Guide, on the other hand, shows how to make a run directory prior to compiling. +.. _building_gchp: + +####### +Compile +####### .. note:: - Another resource for GCHP build instructions is our `YouTube tutorial `_. It is for version 13 but the build information is still applicable. -.. _building_gchp: + Compiling GCHP and creating a run directory are independent steps, + and their order doesn't matter. A small exception is the + :ref:`RUNDIR ` build option, which controls + the behaviour of :command:`make install` which copies the GCHP + executable to the run directory; however, this setting can be + reconfigured at any time (e.g., after compiling and creating a run + directory). -Compile -======= + Here in the User Guide we describe compiling GCHP before we + describe creating a run directory. This is so that conceptually the + instructions have a linear flow. The Quickstart Guide, on the other + hand, shows how to make a run directory prior to compiling. -There are three steps to building GCHP. The first is configuring your build, which is done with :program:`cmake`; -the second step is compiling, which is done with :program:`make`. The third step is install, which is also done with :program:`make`. +.. note:: -In the first step (build configuration), :program:`cmake` finds GCHP's :ref:`software dependencies ` -on your system, and you can set :ref:`build options ` like -enabling/disabling components (such as RRTMG), setting paths to run directories, picking between debug or speed-optimizing compiler -flags, etc. The second step (running :program:`make`) compiles GCHP according your build configuration. The third step copies GCHP executable to an appropriate location, such as one or more run directories if you specify them. + Another resource for GCHP build instructions is our `YouTube + tutorial `_. It is for + version 13 but the build information is still applicable. + + +There are three steps to building GCHP. The first is configuring your +build, which is done with :program:`cmake`; the second step is +compiling, which is done with :program:`make`. The third step is +install, which is also done with :program:`make`. In the first step +(build configuration), :program:`cmake` finds GCHP's :ref:`software +dependencies ` on your system, and you can set +:ref:`build options ` like enabling/disabling +components (such as RRTMG), setting paths to run directories, +picking between debug or speed-optimizing compiler flags, etc. The +second step (running :program:`make`) compiles GCHP according your +build configuration. The third step copies GCHP executable to an +appropriate location, such as one or more run directories if you +specify them. .. important:: - These instructions assume you have loaded a computing environment that satisfies - :ref:`GCHP's software requirements ` You can find instructions for building GCHP's - dependencies yourself in the `Spack instructions <../supplement/spack.html>`__. + These instructions assume you have loaded a computing environment + that satisfies :ref:`GCHP's software requirements + ` You can find instructions for building + GCHP's dependencies yourself in the `Spack instructions + <../supplement/spack.html>`__. + +======================== Create a build directory ------------------------- +======================== -A build directory is the working directory for a "build". Conceptually, a "build" is a case/instance of -you compiling GCHP. A build directory stores configuration files and intermediate files related to the build. -These files and generated and used by CMake, Make, and compilers. You can think a -build directory like the blueprints for a construction project. +A build directory is the working directory for a +"build". Conceptually, a "build" is a case/instance of you compiling +GCHP. A build directory stores configuration files and intermediate +files related to the build. These files and generated and used by +CMake, Make, and compilers. You can think a build directory like the +blueprints for a construction project. Create a new directory and initialize it as a build directory by running CMake. -When you initialize a build directory, the path to the source code is a required -argument: +When you initialize a build directory, the path to the source code is +a required argument: .. code-block:: console - - gcuser:~$ cd ~/Code.GCHP - gcuser:~/Code.GCHP$ mkdir build # create a new directory - gcuser:~/Code.GCHP$ cd build - gcuser:~/Code.GCHP/build$ cmake ~/Code.GCHP # initialize the current dir as a build dir + + $ cd ~/Code.GCHP # Navigate to the GCHP source code folder + $ mkdir build # Create a new directory + $ cd build # Navigate to the new directory + $ cmake ~/Code.GCHP # Initialize the current dir as a build dir + -- The Fortran compiler identification is GNU 9.2.1 -- The CXX compiler identification is GNU 9.2.1 -- The C compiler identification is GNU 9.2.1 @@ -54,121 +79,158 @@ argument: -- Configuring done -- Generating done -- Build files have been written to: /src/build - gcuser:~/Code.GCHP/build$ -If your :program:`cmake` output is similar to the snippet above, and it says configuring & -generating done, then your configuration was successful and you can move on to :ref:`compiling -` or :ref:`modifying build settings `. If you got an error, -don't worry, that just means the automatic configuration failed. To fix the error you might need -to tweak settings with more :program:`cmake` commands, or you might need to modify your -environment and run :program:`cmake` again to retry the automatic configuration. +If your :program:`cmake` output is similar to the snippet above, and +it says configuring & generating done, then your configuration was +successful and you can move on to :ref:`compiling ` or +:ref:`modifying build settings `. If you got an +error, don't worry, that just means the automatic configuration +failed. To fix the error you might need to tweak settings with more +:program:`cmake` commands, or you might need to modify your +environment and run :program:`cmake` again to retry the +automatic configuration. -If you want to restart configuring your build from scratch, delete your build directory. -Note that the name and location of your build directory doesn't matter, but a good -name is :file:`build/`, and a good place for it is the top-level of your source code. +If you want to restart configuring your build from scratch, delete +your build directory. Note that the name and location of your build +directory doesn't matter, but a good name is :file:`build/`, and a +good place for it is the top-level of your source code. +=============================== Resolving initialization errors -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +=============================== -If your last step was successful, :ref:`skip this section `. +If your last step was successful, :ref:`skip to this section +`. -Even if you got a :program:`cmake` error, your build directory was initialized. This means -from now on, you can check if the configuration is fixed by running +Even if you got a :program:`cmake` error, your build directory was +initialized. This means from now on, you can check if the +configuration is fixed by running .. code-block:: console - - gcuser:~/Code.GCHP/build$ cmake . # "." because the cwd is the build dir -To resolve your errors, you might need to modify your environment (e.g., load different software modules), -or give CMake a hint about where some software is installed. Once you identify the problem and make -the appropriate update, run :program:`cmake .` to see if the error is fixed. + $ cd ~/Code.GCHP/build # Navigate to the build/ folder in the GCHP code dir + $ cmake . # "." because the current dir is the build dir + +To resolve your errors, you might need to modify your environment +(e.g., load different software modules), or give CMake a hint about +where some software is installed. Once you identify the problem and +make the appropriate update, run :program:`cmake .` to see if the +error is fixed. -To start troubleshooting, read the :program:`cmake` output in full. It is human-readable, and -includes important information about how the build was set up on your system, and specifically what -error is preventing a successful configuration (e.g., a dependency that wasn't found, or a compiler -that is broken). To begin troubleshooting you should check that: +To start troubleshooting, read the :program:`cmake` output in full. It +is human-readable, and includes important information about how the +build was set up on your system, and specifically what error is +preventing a successful configuration (e.g., a dependency that wasn't +found, or a compiler that is broken). To begin troubleshooting you +should: -* check that the compilers are what you expect (e.g., GNU 9.2, Intel 19.1, etc.) -* check that dependencies like MPI, HDF5, NetCDF, and ESMF were found -* check for obvious errors/incompatibilities in the paths to "Found" dependencies +* Check that the compilers are what you expect (e.g., GNU 9.2, Intel + 19.1, etc.) +* Check that dependencies like MPI, HDF5, NetCDF, and ESMF were found +* Check for obvious errors/incompatibilities in the paths to "Found" + dependencies .. note:: - F2PY and ImageMagick are not required. You can safely ignore warnings about them not being - found. + F2PY and ImageMagick are not required. You can safely ignore + warnings about them not being found. Most errors are caused by one or more of the following issues: -* The wrong compilers were chosen. Fix this by explicitly setting the compilers. +* The wrong compilers were chosen. Fix this by explicitly setting the + compilers. * The compiler's version is too old. Fix this by using newer compilers. -* A software dependency is missing. Fix this by loading the appropriate software. Some hints: +* A software dependency is missing. Fix this by loading the + appropriate software. Some hints: - * If HDF5 is missing, does :program:`h5cc -show` or :program:`h5pcc -show` work? - * If NetCDF is missing, do :program:`nc-config --all` and :program:`nf-config --all` work? + * If HDF5 is missing, does :program:`h5cc -show` or :program:`h5pcc + -show` work? + * If NetCDF is missing, do :program:`nc-config --all` and + :program:`nf-config --all` work? * If MPI is missing, does :program:`mpiexec --help` work? - -* A software dependency is loaded but it wasn't found automatically. Fix this by pointing CMake to the - missing software/files with :program:`cmake . -DCMAKE_PREFIX_PATH=/path/to/missing/files`. - * If ESMF is missing, point CMake to your ESMF install with :option:`-DCMAKE_PREFIX_PATH` +* A software dependency is loaded but it wasn't found + automatically. Fix this by pointing CMake to the missing + software/files with + + .. code-block:: console -* Software modules that are not compatible. Fix this by loading compatible modules/dependencies/compilers. Some hints: - - * This often shows as an error message saying a compiler is "broken" or "doesn't work" - * E.g. incompatibility #1: you're using GNU compilers but HDF5 is built for Intel compilers - * E.g. incompatibility #2: ESMF was compiled for a different compiler, MPI, or HDF5 + $ cmake . -DCMAKE_PREFIX_PATH=/path/to/missing/files -If you are stumped, don't hesitate to open an issue on GitHub. Your system administrators might -also be able to help. Be sure to include :file:`CMakeCache.txt` from your build directory, as it contains + * If ESMF is missing, point CMake to your ESMF install with + :option:`-DCMAKE_PREFIX_PATH` + +* Software modules that are not compatible. Fix this by loading + compatible modules/dependencies/compilers. Some hints: + + * This often shows as an error message saying a compiler is + "broken" or "doesn't work" + * E.g. incompatibility #1: you're using GNU compilers but HDF5 is + built for Intel compilers + * E.g. incompatibility #2: ESMF was compiled for a different + compiler, MPI, or HDF5 + +If you are stumped, don't hesitate to open an issue on GitHub. Your +system administrators might also be able to help. Be sure to include +:file:`CMakeCache.txt` from your build directory, as it contains useful information for troubleshooting. -.. note:: - If you get a CMake error saying "Could not find XXXX" (where XXXX is a dependency like - ESMF, NetCDF, HDF5, etc.), the problem is that CMake can't automatically find where that library - is installed. You can add custom paths to CMake's default search list by setting the +.. note:: + + If you get a CMake error saying "Could not find XXXX" (where XXXX + is a dependency like ESMF, NetCDF, HDF5, etc.), the problem is that + CMake can't automatically find where that library is installed. You + can add custom paths to CMake's default search list by setting the :literal:`CMAKE_PREFIX_PATH` variable. - For example, if you got an error saying "Could not find ESMF", and ESMF is installed - to :file:`/software/ESMF`, you would do + For example, if you got an error saying "Could not find ESMF", and + ESMF is installedto :file:`/software/ESMF`, you would do .. code-block:: console - - gcuser:~/Code.GCHP/build$ cmake . -DCMAKE_PREFIX_PATH=/software/ESMF + + $ cd ~/Code.GCHP/build # Skip if you are already in the build/ folder + + $ cmake . -DCMAKE_PREFIX_PATH=/software/ESMF ... -- Found ESMF: /software/ESMF/include (found version "8.1.0") ... -- Configuring done -- Generating done -- Build files have been written to: /src/build - gcuser:~/Code.GCHP/build$ - - See the next section for details on setting variables like :literal:`CMAKE_PREFIX_PATH`. + + + See the next section for details on setting variables like + :literal:`CMAKE_PREFIX_PATH`. .. note:: - You can explicitly specify compilers by setting the :envvar:`CC`, :envvar:`CXX`, and :envvar:`FC` environment - variables. If the auto-selected compilers are the wrong ones, create a brand new build directory, - and set these variables before you initialize it. E.g.: + + You can explicitly specify compilers by setting the :envvar:`CC`, + :envvar:`CXX`, and :envvar:`FC` environment variables. If the + auto-selected compilers are the wrong ones, create a brand + new build directory, and set these variables before you initialize + it. E.g.: .. code-block:: console - - gcuser:~/Code.GCHP/build$ cd .. - gcuser:~/Code.GCHP$ rm -rf build # build dir initialized with wrong compilers - gcuser:~/Code.GCHP$ mkdir build # make a new build directory - gcuser:~/Code.GCHP$ cd build - gcuser:~/Code.GCHP/build$ export CC=icc # select "icc" as C compiler - gcuser:~/Code.GCHP/build$ export CXX=icpc # select "icpc" as C++ compiler - gcuser:~/Code.GCHP/build$ export FC=icc # select "ifort" as Fortran compiler - gcuser:~/Code.GCHP/build$ cmake ~/Code.GCHP # initialize new build dir + + $ cd ~/Code.GCHP # Navigate to top-level source code folder + $ rm -rf build # build dir initialized with wrong compilers + $ mkdir build # Make a new build directory + $ cd build # ... and navigate to it + $ export CC=icc # select "icc" as C compiler + $ export CXX=icpc # select "icpc" as C++ compiler + $ export FC=icc # select "ifort" as Fortran compiler + $ cmake ~/Code.GCHP # initialize new build dir -- The Fortran compiler identification is Intel 19.1.0.20191121 -- The CXX compiler identification is Intel 19.1.0.20191121 -- The C compiler identification is Intel 19.1.0.20191121 ... -.. _modify_build_settings: +.. _modify_build_settings: +==================== Configure your build --------------------- +==================== Build settings are controlled by :program:`cmake` commands like: @@ -177,87 +239,102 @@ Build settings are controlled by :program:`cmake` commands like: $ cmake . -D="" where :literal:`` is the name of the setting, and :literal:`` is the -value you are assigning it. These settings are persistent and saved in your build directory. -You can set multiple variables in the same command, and you can run :program:`cmake` as many times -as needed to configure your desired settings. +value you are assigning it. These settings are persistent and saved in +your build directory. You can set multiple variables in the same +command, and you can run :program:`cmake` as many times as needed to +configure your desired settings. + +.. note:: -.. note:: - The :literal:`.` argument is important. It is the path to your build directory which - is :literal:`.` here. + The :literal:`.` argument is important. It is the path to your + build directory which is :literal:`.` here. -No build settings are required. You can find the complete list of :ref:`GCHP's build settings here `. -The most common setting is :literal:`RUNDIR`, which lets you specify one or more run directories -to install GCHP to. Here, "install" refers to copying the compiled executable, and some supplemental files -with build settings, to your run directory/directories. +No build settings are required. You can find the complete list of +:ref:`GCHP's build settings here `. The most +common setting is :literal:`RUNDIR`, which lets you specify one +or more run directories to install GCHP to. Here, "install" refers to +copying the compiled executable, and some supplemental files with +build settings, to your run directory/directories. .. note:: - You can update build settings after you compile GCHP. Simply rerun :program:`make` and - (optionally) :program:`make install`, and the build system will automatically figure out - what needs to be recompiled. -Since there are no required build settings, so here, we will stick with the default settings. + You can update build settings after you compile GCHP. Simply rerun + :program:`make` and (optionally) :program:`make install`, and the + build system will automatically figure out what needs to be recompiled. + +Since there are no required build settings, so here, we will stick +with the default settings. You should notice that when you run :program:`cmake` it ends with: .. code-block:: console - + ... -- Configuring done -- Generating done -- Build files have been written to: /src/build -This tells you that the configuration was successful, and that you are ready to compile. +This tells you that the configuration was successful, and that you are +ready to compile. .. _compiling_gchp: +============ Compile GCHP ------------- +============ You compile GCHP with: .. code-block:: console - - gcuser:~/Code.GCHP/build$ make -j # -j enables compiling in parallel + + $ cd ~/Code.GCHP/build # Skip if you are already in the build/ folder + $ make -j # -j enables compiling in parallel .. note:: + You can add :literal:`VERBOSE=1` to see all the compiler commands. .. note:: - If you run out of memory while compiling, restrict the number of processes that can - run concurrently (e.g., use :option:`-j20` to restrict to 20 processes) -Compiling GCHP creates :file:`./bin/gchp` (the GCHP executable). You can copy -this executable to your run directory manually, or if you set the :ref:`RUNDIR ` build option, -you can do + If you run out of memory while compiling, restrict the number of + processes that can run concurrently (e.g., use :option:`-j20` to + restrict to 20 processes). + +Compiling GCHP creates :file:`./bin/gchp` (the GCHP executable). You +can copy this executable to your run directory manually, or if you set the +:ref:`RUNDIR ` build option, you can do .. code-block:: console - - gcuser:~/Code.GCHP/build$ make install # Requires that RUNDIR build option is set + + $ cd ~/Code.GCHP/build # Skip if you are already in the build/ folder + $ make install # Requires that RUNDIR build option is set to copy the executable (and supplemental files) to your run directories. Now you have compiled GCHP! You can move on to creating a run directory! ------------- - +=========== Recompiling ------------ +=========== -You need to recompile GCHP if you update a build setting or modify the source code. -With CMake, you do not need to clean before recompiling. The build system automatically -figures out which files need to be recompiled (it's usually a small subset). This is known as incremental compiling. +You need to recompile GCHP if you update a build setting or modify the +source code. With CMake, you do not need to clean before +recompiling. The build system automatically figures out which files +need to be recompiled (it's usually a small subset). This is known as +incremental compiling. -To recompile GCHP, simply do +To recompile GCHP, simply do .. code-block:: console - - gcuser:~/Code.GCHP/build$ make -j # -j enables compiling in parallel + + $ cd ~/Code.GCHP/build # Skip if you are already in the build/ folder + $ make -j # -j enables compiling in parallel and then optionally, :command:`make install`. .. note:: GNU compilers recompile GCHP faster than Intel compilers. This is because of how :program:`gfortran` - formats Fortran modules files (:file:`*.mod` files). Therefore, if you want to be able to recompile quickly, consider + formats Fortran modules files (:file:`*.mod` files). Therefore, if you want to be able to recompile quickly, consider using GNU compilers. ------------ @@ -267,56 +344,84 @@ and then optionally, :command:`make install`. GCHP build options ------------------ -These are persistent build setting that are set with :program:`cmake` commands -like +These are persistent build setting that are set with :program:`cmake` +commands like .. code-block:: none $ cmake . -D="" -where :literal:`` is the name of the build setting, and :literal:`` is the value you -are assigning it. Below is the list of build settings for GCHP. +where :literal:`` is the name of the build setting, and +:literal:`` is the value you are assigning it. Below is the +list of build settings for GCHP. + +.. _build_setting_rundir: -.. _build_setting_rundir: +.. option:: RUNDIR -RUNDIR - Paths to run directories where :command:`make install` installs GCHP. Multiple - run directories can be specified by a semicolon separated list. A warning is - issues if one of these directories does not look like a run directory. + Paths to run directories where :command:`make install` installs + GCHP. Multiple run directories can be specified by a semicolon + separated list. A warning is issues if one of these directories + does not look like a run directory. - These paths can be relative paths or absolute paths. Relative paths are interpreted as relative to your build directory. + These paths can be relative paths or absolute paths. Relative paths + are interpreted as relative to your build directory. -CMAKE_BUILD_TYPE - The build type. Valid values are :literal:`Release`, :literal:`Debug`, and :literal:`RelWithDebInfo`. - Set this to :literal:`Debug` if you want to build in debug mode. +.. option:: CMAKE_BUILD_TYPE -CMAKE_PREFIX_PATH - Extra directories that CMake will search when it's looking for dependencies. Directories in - :literal:`CMAKE_PREFIX_PATH` have the highest precedence when CMake is searching for dependencies. - Multiple directories can be specified with a semicolon-separated list. + The build type. Valid values are :literal:`Release`, + :literal:`Debug`, and :literal:`RelWithDebInfo`. Set this to + :literal:`Debug` if you want to build in debug mode. -GEOSChem_Fortran_FLAGS_ - Compiler options for GEOS-Chem for all build types. Valid values for :literal:`` are :literal:`GNU` and - :literal:`Intel`. - -GEOSChem_Fortran_FLAGS__ - Additional compiler options for GEOS-Chem for build type :literal:``. +.. option:: CMAKE_PREFIX_PATH -HEMCO_Fortran_FLAGS_ - Same as :literal:`GEOSChem_Fortran_FLAGS_`, but for HEMCO. - -HEMCO_Fortran_FLAGS__ - Same as :literal:`GEOSChem_Fortran_FLAGS__`, but for HEMCO. + Extra directories that CMake will search when it's looking for + dependencies. Directories in :literal:`CMAKE_PREFIX_PATH` have + the highest precedence when CMake is searching for dependencies. + Multiple directories can be specified with a semicolon-separated list. -RRTMG - Switch to enable the RRTMG component. Set value to :literal:`y` to turn on. +.. option:: GEOSChem_Fortran_FLAGS_ -FASTJX - Switch to enable the legacy FAST-JX v7.0 photolysis mechanism. Set value :literal:`y` to turn on FAST-JX and turn off Cloud-J. If FASTJX is not set then Cloud-J will be to compute photolysis rates. + Compiler options for GEOS-Chem for all build types. Valid values + for :literal:`` are :literal:`GNU` and + :literal:`Intel`. -OMP - Switch to enable/disable OpenMP multithreading. As is standard in CMake (see `if documentation `_) valid values are :literal:`ON`, :literal:`YES`, :literal:`Y`, :literal:`TRUE`, or :literal:`1` (case-insensitive) and valid +.. option:: GEOSChem_Fortran_FLAGS__ + + Additional compiler options for GEOS-Chem for build type + :literal:``. + +.. option:: HEMCO_Fortran_FLAGS_ + + Same as :literal:`GEOSChem_Fortran_FLAGS_`, but for HEMCO. + +.. option:: HEMCO_Fortran_FLAGS__ + + Same as + :literal:`GEOSChem_Fortran_FLAGS__`, + but for HEMCO. + +.. option:: RRTMG + + Switch to enable the RRTMG component. Set value to :literal:`y` to turn on. + +.. option:: FASTJX + + Switch to enable the legacy FAST-JX v7.0 photolysis mechanism. Set + value :literal:`y` to turn on FAST-JX and turn off Cloud-J. If + FASTJX is not set then Cloud-J will be to compute photolysis + rates. + +.. option:: OMP + + Switch to enable/disable OpenMP multithreading. As is standard in + CMake (see `if documentation + `_) valid + values are :literal:`ON`, :literal:`YES`, :literal:`Y`, + :literal:`TRUE`, or :literal:`1` (case-insensitive) and valid false values are their opposites. -INSTALLCOPY - Similar to :literal:`RUNDIR`, except the directories do not need to be run directories. +.. option:: INSTALLCOPY + + Similar to :literal:`RUNDIR`, except the directories do not need + to be run directories. diff --git a/docs/source/user-guide/getting-input-data.rst b/docs/source/user-guide/getting-input-data.rst index 3ea3d6f85..3d853478c 100644 --- a/docs/source/user-guide/getting-input-data.rst +++ b/docs/source/user-guide/getting-input-data.rst @@ -1,22 +1,28 @@ .. _downloading_input_data: +################### Download Input Data -=================== +################### -Input data for GEOS-Chem is available at http://geoschemdata.wustl.edu/ExtData/. +Input data for GEOS-Chem is available at +http://geoschemdata.wustl.edu/ExtData/. -The bashdatacatalog is the recommended for downloading and managing your GEOS-Chem input data. Refer to -the bashdatacatalog's `Instructions for GEOS-Chem Users `_. -Below is a brief summary of using the bashdatacatalog for aquiring GCHP input data. +The bashdatacatalog is the recommended for downloading and managing +your GEOS-Chem input data. Refer to the bashdatacatalog's +`Instructions for GEOS-Chem Users +`_. Below +is a brief summary of using the bashdatacatalog for aquiring GCHP +input data. Install the bashdatacatalog --------------------------- -Install the bashdatacatalog with the following command. Follow the prompts and restart your console. +Install the bashdatacatalog with the following command. Follow the +prompts and restart your console. .. code-block:: console - gcuser:~$ bash <(curl -s https://raw.githubusercontent.com/geoschem/bashdatacatalog/main/install.sh) + $ bash <(curl -s https://raw.githubusercontent.com/geoschem/bashdatacatalog/main/install.sh) .. note:: You can rerun this command to upgrade to the latest version. @@ -27,75 +33,95 @@ Catalog files can be downloaded from http://geoschemdata.wustl.edu/ExtData/DataC The catalog files define the input data collections that GEOS-Chem needs. There are four catalogs files: -* MeteorologicalInputs.csv -- Meteorological input data collections -* ChemistryInputs.csv -- Chemistry input data collections -* EmissionsInputs.csv -- Emissions input data collections -* InitialConditions.csv -- Initial conditions input data collections (restart files) +* :file:`MeteorologicalInputs.csv` -- Meteorological input data collections +* :file:`ChemistryInputs.csv` -- Chemistry input data collections +* :file:`EmissionsInputs.csv` -- Emissions input data collections +* :file:`InitialConditions.csv` -- Initial conditions input data + collections (restart files) -The latter 3 are version specific, so you need to download the catalogs for the version you intend to use (you can have catalogs -for multiple versions at the same time). +The latter 3 are version specific, so you need to download the +catalogs for the version you intend to use (you can have catalogs for +multiple versions at the same time). -Create a directory to house your catalog files in the top-level of your GEOS-Chem input data directory (commonly known as "ExtData"). +Create a directory to house your catalog files in the top-level of +your GEOS-Chem input data directory (commonly known as :file:`ExtData`). You should create subdirectories for version-specific catalog files. .. code-block:: console - gcuser:~$ cd /ExtData # navigate to GEOS-Chem data - gcuser:/ExtData$ mkdir InputDataCatalogs # new directory for catalog files - gcuser:/ExtData$ mkdir InputDataCatalogs/13.3 # " for 13.3-specific catalogs (example) + $ cd /ExtData # navigate to GEOS-Chem data + $ mkdir InputDataCatalogs # new directory for catalog files + $ mkdir InputDataCatalogs/14.4 # for 14.4-*-specific catalogs (example) Next, download the catalog for the appropriate version: .. code-block:: console - gcuser:/ExtData$ cd InputDataCatalogs - gcuser:/ExtData/InputDataCatalogs$ wget http://geoschemdata.wustl.edu/ExtData/DataCatalogs/MeteorologicalInputs.csv - gcuser:/ExtData/InputDataCatalogs$ cd 13.3 - gcuser:/ExtData/InputDataCatalogs/13.3$ wget http://geoschemdata.wustl.edu/ExtData/DataCatalogs/13.3/ChemistryInputs.csv - gcuser:/ExtData/InputDataCatalogs/13.3$ wget http://geoschemdata.wustl.edu/ExtData/DataCatalogs/13.3/EmissionsInputs.csv - gcuser:/ExtData/InputDataCatalogs/13.3$ wget http://geoschemdata.wustl.edu/ExtData/DataCatalogs/13.3/InitialConditions.csv + $ cd InputDataCatalogs + $ wget http://geoschemdata.wustl.edu/ExtData/DataCatalogs/MeteorologicalInputs.csv + $ cd 14.4 + $ wget http://geoschemdata.wustl.edu/ExtData/DataCatalogs/14.4/ChemistryInputs.csv + $ wget http://geoschemdata.wustl.edu/ExtData/DataCatalogs/14.4/EmissionsInputs.csv + $ wget http://geoschemdata.wustl.edu/ExtData/DataCatalogs/14.4/InitialConditions.csv Fetching Metadata and Downloading Input Data -------------------------------------------- -.. important:: You should always run bashdatacatalog commands from the top-level of your GEOS-Chem data directory (the directory with ``HEMCO/``, ``CHEM_INPUTS/``, etc.). +.. important:: -Before you can run ``bashdatacatalog-list`` commands, you need to fetch the metadata of each collection. -This is done with the command ``bashdatacatalog-fetch`` whose arguments are catalog files: + You should always run bashdatacatalog commands from the + top-level of your GEOS-Chem data directory (the + directory with :file:`HEMCO/`, :file:`CHEM_INPUTS/`, etc.). + +Before you can run :command:`bashdatacatalog-list` commands, you need to +fetch the metadata of each collection. This is done with the command +:command:`bashdatacatalog-fetch` whose arguments are catalog files: .. code-block:: console - gcuser:~$ cd /ExtData # IMPORTANT: navigate to top-level of GEOS-Chem input data - gcuser:/ExtData$ bashdatacatalog-fetch InputDataCatalogs/*.csv InputDataCatalogs/**/*.csv + $ cd /ExtData # IMPORTANT: navigate to top-level of GEOS-Chem input data -Fetching downloads the latest metadata for every active collection in your catalogs. -You should run ``bashdatacatalog-fetch`` whenever you add or modify a catalog, as well as periodically so you get updates to your collections -(e.g., new meteorological data that is processed and added to the meteorological collections). + $ bashdatacatalog-fetch InputDataCatalogs/*.csv InputDataCatalogs/**/*.csv -Now that you have fetched, you can run ``bashdatacatalog-list`` commands. You can tailor this command the generate various types of file lists using its command-line arguments. -See ``bashdatacatalog-list -h`` for details. A common use case is generating a list of required input files that missing in your local file system. +Fetching downloads the latest metadata for every active collection in +your catalogs. You should run :command:`bashdatacatalog-fetch` +whenever you add or modify a catalog, as well as periodically so you +get updates to your collections (e.g., new meteorological data that is +processed and added to the meteorological collections). +Now that you have fetched, you can run :command:`bashdatacatalog-list` +commands. You can tailor this command the generate various types of +file lists using its command-line arguments. +See :command:`bashdatacatalog-list -h` for details. A common use case +is generating a list of required input files that missing in your +local file system. .. code-block:: console - gcuser:/ExtData$ bashdatacatalog-list -am -r 2018-06-30,2018-08-01 InputDataCatalogs/*.csv InputDataCatalogs/**/*.csv + $ bashdatacatalog-list -am -r 2018-06-30,2018-08-01 InputDataCatalogs/*.csv InputDataCatalogs/**/*.csv -Here, ``-a`` means "all" files (temporal files and static files), ``-m`` means "missing" (list files that are absent locally), ``-r START,END`` is the date-range of your simulation -(you should add an extra day before/after your simulation), and the remaining arguments are the paths to your catalog files. +Here, :literal:`-a` means "all" files (temporal files and static +files), :literal:`-m` means "missing" (list files that are absent +locally), :literal:`-r START,END` is the date-range of your simulation +(you should add an extra day before/after your simulation), and the +remaining arguments are the paths to your catalog files. -The command can be easily modified so that it generates a list of missing files that is compatible with xargs curl to download all the files you are missing: +The command can be easily modified so that it generates a list of +missing files that is compatible with xargs curl to download all the +files you are missing: .. code-block:: console - gcuser:/ExtData$ bashdatacatalog-list -am -r 2018-06-30,2018-08-01 -f xargs-curl InputDataCatalogs/*.csv InputDataCatalogs/**/*.csv | xargs curl + $ bashdatacatalog-list -am -r 2018-06-30,2018-08-01 -f xargs-curl InputDataCatalogs/*.csv InputDataCatalogs/**/*.csv | xargs curl -Here, ``-f xargs-curl`` means the output file list should be formatted for piping into xargs curl. +Here, :literal:`-f xargs-curl` means the output file list should be +formatted for piping into xargs curl. See Also -------- -* `bashdatacatalog - Instructions for GEOS-Chem Users `_ -* `bashdatacatalog - List of useful commands `_ -* `GEOS-Chem Input Data Catalogs `_ +- `bashdatacatalog - Instructions for GEOS-Chem Users `_ +- `bashdatacatalog - List of useful commands `_ +- `GEOS-Chem Input Data Catalogs `_ diff --git a/docs/source/user-guide/running.rst b/docs/source/user-guide/running.rst index 7c702328b..d2252b688 100644 --- a/docs/source/user-guide/running.rst +++ b/docs/source/user-guide/running.rst @@ -1,3 +1,7 @@ +.. |br| raw:: html + +
+ .. _running_gchp: ############# @@ -16,16 +20,36 @@ Pre-run checklist Prior to running GCHP, always run through the following checklist to ensure everything is set up properly. -1. Start date is set in :file:`cap_restart` -2. Executable :file:`gchp` is present. -3. All symbolic links are valid (no broken links) -4. Settings are correct in :file:`setCommonRunSettings.sh` -5. :file:`setRestartLink.sh` runs without error (ensures restart file is available for date in :file:`cap_restart`) -6. If running via a job scheduler, totals cores are the same in :file:`setCommonRunSettings.sh` and the run script -7. If running interactively, you have available locally the total cores in :file:`setCommonRunSettings.sh` +#. Check that the date is set in :ref:`cap-restart`. |br| + |br| + +#. Check that the executable :file:`gchp` is present. |br| + |br| + +#. Check that all symbolic links are valid (no broken links). |br| + |br| + +#. Check that all simulation settings are correct in + :ref:`set-common-run-settings-sh`. |br| + |br| +#. Check that :file:`setRestartLink.sh` runs without error. (This + ensures that the restart file is available for the date specified + in :ref:`cap-restart`.) |br| + |br| + +#. If :ref:`running via a job scheduler `, check + that the total cores in :ref:`set-common-run-settings-sh` matches the + total cores requested in the run script. |br| + |br| + +#. If :ref:`running interactively `, check if you + have available locally the total cores in + :ref:`set-common-run-settings-sh`. + +=============== How to run GCHP ---------------- +=============== You can run GCHP locally from within your run directory ("interactively") or by submitting your run to a job scheduler if one @@ -33,29 +57,50 @@ is available. Either way, it is useful to put run commands into a reusable script we call the run script. Executing the script will either run GCHP or submit a job that will run GCHP. -There is a symbolic link in the GCHP run directory called :file:`runScriptSamples` that points to a directory in the source code containing example run scripts. +There is a symbolic link in the GCHP run directory called +:file:`runScriptSamples` that points to a directory in the source code +containing example run scripts. Each file includes extra commands that make the run process easier and less prone to user error. These commands include: -1. Define a GCHP log file that includes start date configured in - :file:`cap_restart` in its name -2. Source environment file symbolic link :file:`gchp.env` -3. Source config file :file:`setCommonRunSettings.sh` to update - commonly changed run settings -4. Set restart file symbolic link :file:`gchp_restart.nc4` to target +#. Define a GCHP log file that includes start date configured in + :ref:`cap-restart` in its name. |br| + |br| + +#. Load the software environment: + + .. code-block:: console + + $ source gchp.env + +#. Update commonly changed run settings: + + .. code-block:: console + + $ source setCommonRunSettings.sh + +#. Set restart file symbolic link :file:`gchp_restart.nc4` to target file in :file:`Restarts` subdirectory for configured start date and - grid resolution -5. Check that :file:`cap_restart` now contains end date of your run -6. Rename the output restart file to include run start date and grid + grid resolution. |br| + |br| + +#. Check that :file:`cap_restart` now contains the end date of your + run. |br| + |br| + +#. Rename the output restart file to include run start date and grid resolution (format - :literal:`GEOSChem.Restarts.YYYYMMDD_HHmmz.cN.nc4`) + :literal:`GEOSChem.Restarts.YYYYMMDD_HHmmz.cN.nc4`). + +.. _running_gchp_int: Run interactively ----------------- -Copy or adapt example run script :file:`gchp.local.run` to run GCHP locally on your machine. -Before running, make sure the total number of cores configured in :file:`setCommonRunSettings.sh` is available locally. -It must be at least 6. +Copy or adapt example run script :file:`gchp.local.run` to run GCHP +locally on your machine. Before running, make sure the total number of +cores configured in :ref:`set-common-run-settings-sh` is available +locally. It must be at least 6. To run, type the following at the command prompt: @@ -68,15 +113,17 @@ sent to a log file with filename format :literal:`gchp.YYYYMMDD_HHmmSSz.log`. The HEMCO log output is also included in this file. +.. _running_gchp_batch: + Run as batch job ---------------- -Batch job run scripts will vary based on what job scheduler you have available. -We offer a template batch job run script in the +Batch job run scripts will vary based on what job scheduler you have +available. We offer a template batch job run script in the :file:`runScriptSamples` subdirectory called -:file:`gchp.batch_job.sh`. This file contains examples for 3 -types of job scheduler: SLURM, LSF, and PBS. -You may copy and adapt this file for your system and preferences as needed. +:file:`gchp.batch_job.sh`. This file contains examples for 3 types of +job scheduler: SLURM, LSF, and PBS. You may copy and adapt this file +for your system and preferences as needed. At the top of all batch job scripts are configurable run settings. Most critically are requested # cores, # nodes, time, and @@ -86,9 +133,13 @@ trial and error. See :ref:`hardware requirements cores you request the faster GCHP will run given the same grid resolution. Configurable job scheduler settings and acceptable formats are often accessible from the command line. For example, type -:command:`man sbatch` to scroll through configurable options for -SLURM, including various ways of specifying number of cores, -time and memory requested. + +.. code-block:: console + + $ man sbatch + +to scroll through configurable options for SLURM, including various +ways of specifying number of cores, time and memory requested. To submit a batch job using a run script called :file:`gchp.run` and the SLURM job scheduler: @@ -107,35 +158,46 @@ If your computational cluster uses a different job scheduler, check with your IT staff or search the internet for how to configure and submit batch jobs on your system. +======================= Verify a successful run ------------------------ +======================= GEOS-Chem standard output and standard error will be sent to a file specific to your scheduler, e.g. :file:`slurm-jobid.out`, unless you configured your run script to send it to a different log file. Variable :literal:`log` is defined in the template run script as :file:`gchp.YYYYMMDD_HHmmSSz.log` if you wish to use it. The date -string in the log filename is the start date of your simulation -as configured in :file:`cap_restart`. This log is automatically -used if you execute the interactive run script example -:file:`gchp.local.run`. GCHP produces another output log file -called :file:`allPEs.log` which is produced by the MAPL -library logger for debugging purposes. Several other logs -are output for informational purposes only but generally -are not useful for debugging. +string in the log filename is the start date of your simulation as +configured in :ref:`cap-restart`. This log is automatically used if +you execute the interactive run script example +:file:`gchp.local.run`. GCHP produces another output log file called +:file:`allPEs.log` which is produced by the MAPL library logger for +debugging purposes. Several other logs are output for informational +purposes only but generally are not useful for debugging. There are several ways to verify that your run was successful. Here are just a few: -1. The GCHP log file shows every timestep (search for :literal:`AGCM - Date`) and ends with timing information. -2. NetCDF files are present in the :file:`OutputDir/` subdirectory. -3. There is a restart file corresponding to your end date in the - :file:`Restarts` subdirectory. -4. The start date in :file:`cap_restart` has been updated to your run - end date. -5. The job scheduler log does not contain any error messages. -6. Output file :file:`allPEs.log` does not contain any error +#. The GCHP log file shows every timestep (search for :literal:`AGCM + Date`) and ends with timing information. |br| + |br| + +#. NetCDF files are present in the :file:`OutputDir/` + subdirectory. |br| + |br| + +#. There is a restart file corresponding to your end date in the + :file:`Restarts` subdirectory. |br| + |br| + +#. The start date in :ref:`cap-restart` has been updated to your run + end date. |br| + |br| + +#. The job scheduler log does not contain any error messages. |br| + |br| + +#. Output file :file:`allPEs.log` does not contain any error messages. If it looks like something went wrong, scan through the log files to @@ -144,28 +206,50 @@ strategies depending on what you find. Below is a summary of steps to take to debug GCHP runs. See also :ref:`debugging ` for additional guidance. -* Find the first error message in the GCHP log file to see if it tells - you what is wrong. -* Find the first line of the traceback for the error and find the file - and line number listed to see if it gives a hint about what is - wrong. -* Review all of your configuration files to ensure you have proper - setup, especially :file:`setCommonRunSettings.sh`. -* "MAPL_Cap" or "CAP" errors in the run log typically indicate an - error with your start time and/or duration. Check - :file:`cap_restart` and :file:`setCommonRunSettings.sh`. -* "MAPL_ExtData" or "ExtData" errors in the run log indicate an error with your input files. Check :file:`HEMCO_Config.rc` and :file:`ExtData.rc` for errors. -* "MAPL_HistoryGridComp" or "History" errors in the run log are - related to your configured diagnostics. Check :file:`HISTORY.rc`. -* If the problem is a segmentation fault then rebuild the model with - cmake option :literal:`-DCMAKE_BUILD_TYPE=Debug` and rerun. -* If the problem appears to be in HEMCO then change the warnings and - verbose options in :file:`HEMCO_Config.rc` to true and rerun -* If the problem appears to be in GEOS-Chem then change the verbose - activate option in :file:`geoschem_config.yml` to true and rerun -* If the problem appears to be in MAPL ExtData then change the - :literal:`root_level` settings for :literal:`CAP.ExtData` in - :file:`logging.yml` to :literal:`DEBUG` and rerun +#. Find the first error message in the GCHP log file to see if it tells + you what is wrong. |br| + |br| + +#. Find the first line of the traceback for the error and find the file + and line number listed to see if it gives a hint about what is + wrong. |br| + |br| + +#. Review all of your configuration files to ensure you have proper + setup, especially :ref:`set-common-run-settings-sh`. |br| + |br| + +#. :literal:`MAPL_Cap` or :literal:`CAP` errors in the run log + typically indicate an error with your start time and/or duration. Check + :ref:`cap-restart` and :ref:`set-common-run-settings-sh`. |br| + |br| + +#. :literal:`MAPL_ExtData` or :literal:`ExtData` errors in the run log + indicate an error with your input files. Check + :ref:`cfg-hco-cfg` and :ref:`extdata-rc` for errors. |br| + |br| + +#. :literal:`MAPL_HistoryGridComp` or :literal:`History` errors in the + run log are related to your configured diagnostics. Check + :ref:`history-rc` file. |br| + |br| + +#. If the problem is a segmentation fault then rebuild the model with + cmake option :literal:`-DCMAKE_BUILD_TYPE=Debug` and rerun. |br| + |br| + +#. If the problem appears to be in HEMCO then change the warnings and + verbose options in :ref:`cfg-hco-cfg` to true and rerun. |br| + |br| + +#. If the problem appears to be in GEOS-Chem then change the verbose + activate option in :ref:`cfg-gc-yml` to :literal:`true` + and rerun. |br| + |br| + +#. If the problem appears to be in MAPL ExtData then change the + :literal:`root_level` settings for :literal:`CAP.ExtData` in + :ref:`logging-yml` to :literal:`DEBUG` and rerun. If you still cannot figure out where the problem is then please create a GCHP GitHub issue and include all config and log files for your @@ -177,11 +261,12 @@ Reuse a run directory Archive run output ------------------ -Reusing a GCHP run directory comes with the perils of losing your old work. -To mitigate this issue there is utility shell script :file:`archiveRun.sh`. -This script archives data output and configuration files to a -subdirectory that will not be deleted if you clean your run -directory. + +Reusing a GCHP run directory comes with the perils of losing your old +work. To mitigate this issue there is utility shell script +:file:`archiveRun.sh`. This script archives data output and +configuration files to a subdirectory that will not be deleted +if you clean your run directory. Archiving runs is useful for other reasons as well, including: From f6d51c15868b14cfb0d0b817d698734337a5b62b Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Thu, 3 Oct 2024 09:29:22 -0400 Subject: [PATCH 33/41] GEOS-Chem submodule update: Merge PR #2493 (rename ALK7 to ALK6) Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index c7a6ae627..57cf0dfcd 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit c7a6ae6277a173aa67b903af3af659ebbd2b36d2 +Subproject commit 57cf0dfcdae0d4abbc6094fc119b94f5f5826373 From 5b6a872bd10e3b72f51d04da20786d4fd2ca5fa2 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Thu, 3 Oct 2024 10:58:05 -0400 Subject: [PATCH 34/41] GEOS-Chem and MAPL submodule updates: Merge fixes for GCHP carbon simulation - geos-chem: Merge PR #2492 fixes for GCHP carbon simulation - MAPL: Merge PR #37 conatining fix to vertically flip imports with dimensionless pressure proxy lev coordinates Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- src/MAPL | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 57cf0dfcd..51d306dad 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 57cf0dfcdae0d4abbc6094fc119b94f5f5826373 +Subproject commit 51d306dade21a6c36e5537224b7c533b5489667c diff --git a/src/MAPL b/src/MAPL index 231d53cc0..9ad63aefc 160000 --- a/src/MAPL +++ b/src/MAPL @@ -1 +1 @@ -Subproject commit 231d53cc0b14dc3275cac2867ddb9e15adbc8877 +Subproject commit 9ad63aefc00da1502f79afb5e81211da25677c82 From 66503b00237ab46e96ded8e14c48c7ae78395585 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 15 Oct 2024 14:41:23 -0400 Subject: [PATCH 35/41] geos-chem-shared-docs update: GC input data; GCHP History guide This commit informs the GCHP 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 8ed145c6c..65b2a350d 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit 8ed145c6c813b325c6101392f7ff6e203f851d9b +Subproject commit 65b2a350db689d858e547228f9b3a261db1bd86e From e3222b54882780fdd3b78b2112bcb5e955e4d98f Mon Sep 17 00:00:00 2001 From: Lizzie Lundgren Date: Tue, 5 Nov 2024 10:08:59 -0500 Subject: [PATCH 36/41] Specify upper limit on gfortran supported in GCHP Current MAPL does not reliably build with GCC 13. Signed-off-by: Lizzie Lundgren --- docs/source/getting-started/requirements.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/getting-started/requirements.rst b/docs/source/getting-started/requirements.rst index d5d2a7a4b..745d13ef1 100644 --- a/docs/source/getting-started/requirements.rst +++ b/docs/source/getting-started/requirements.rst @@ -19,7 +19,7 @@ following software: * Compilers (C, C++, and Fortran): * Intel compilers versions 2019-2021, or - * GNU compilers version ≥ 10 + * GNU compilers versions ≥ 10 and < 13 * MPI (Message Passing Interface) From 43e169bb7da9cd6a711d1042c2d858277ff19064 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 5 Nov 2024 15:54:43 -0500 Subject: [PATCH 37/41] RTD update: Fix broken links/refs; Improve text formatting etc. docs/source/geos-chem-shared-docs - Submodule update to cd0f4ad, w/ recent doc updates for 14.5.0 docs/source/getting-started/quick-start.rst - Add "Important" box for GEOS-FP convection - Now use consistent $ prompt in examples docs/source/index.rst - Update toctree link to the GEOS-Chem Input Data on AWS, which was renamed to geos-chem-shared-docs/doc/gcid-portal-overview.rst docs/HEMCO_Config.rc docs/HEMCO_Diagn.rc - Removed; Documentation for these is in geos-chem-shared-docs now docs/source/user-guide/config-files/HISTORY.rc - Fixed incorrect option name: "ref_date:" -> "ref_date" docs/source/user-guide/config-files/setCommonRunSettings.sh - Fixed incorrect option name: "extdata" -> "extdata-rc" docs/source/user-guide/debugging.rst - Added |br| break definition - Fixed links to the debug-guide and error-guide in geos-chem-shared-docs - Updated code formatting to fit w/in 80 cols (mostly) - Trimmed trailing whitespace docs/source/user-guide/getting-input-data.rst - Add text and link to new GEOS-Chem Input Data portal doc - Updated code formatting to fit w/in 80 cols (mostly) - Trimmed trailing whitespace docs/source/user-guide/rundir-config.rst - Removed "-----" breaks - Updated code formatting to fit w/in 80 cols (mostly) - Now use proper heading section delimiters - Trimmed trailing whitespace docs/source/user-guide/rundir-init.rst - Add "Important" box for GEOS-FP convection Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- docs/source/getting-started/quick-start.rst | 60 +- docs/source/index.rst | 2 +- .../config-files/HEMCO_Config_rc.rst | 32 - .../config-files/HEMCO_Diagn_rc.rst | 5 - .../user-guide/config-files/HISTORY_rc.rst | 2 +- .../config-files/setCommonRunSettings_sh.rst | 2 +- docs/source/user-guide/debugging.rst | 354 +++++----- docs/source/user-guide/getting-input-data.rst | 17 +- docs/source/user-guide/rundir-config.rst | 609 ++++++++++++------ docs/source/user-guide/rundir-init.rst | 17 + 11 files changed, 671 insertions(+), 431 deletions(-) delete mode 100644 docs/source/user-guide/config-files/HEMCO_Config_rc.rst delete mode 100644 docs/source/user-guide/config-files/HEMCO_Diagn_rc.rst diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index 65b2a350d..cd0f4ad1d 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit 65b2a350db689d858e547228f9b3a261db1bd86e +Subproject commit cd0f4ad1dd13648c3fe9bf8bb13c7bf5ef517125 diff --git a/docs/source/getting-started/quick-start.rst b/docs/source/getting-started/quick-start.rst index d9441e261..41571c523 100644 --- a/docs/source/getting-started/quick-start.rst +++ b/docs/source/getting-started/quick-start.rst @@ -24,14 +24,14 @@ will automatically initialize and update all the submodules: .. code-block:: console - gcuser:~$ git clone --recurse-submodules https://github.com/geoschem/GCHP.git ~/GCHP - gcuser:~$ cd ~/GCHP + $ git clone --recurse-submodules https://github.com/geoschem/GCHP.git ~/GCHP + $ cd ~/GCHP Upon download you will have the most recently released version. You can check what this is by printing the last commit in the git log and scanning the output for tag. .. code-block:: console - gcuser:~/GCHP$ git log -n 1 + $ git log -n 1 .. tip:: @@ -40,17 +40,17 @@ Upon download you will have the most recently released version. You can check wh .. code-block:: console - gcuser:~/GCHP$ git checkout tags/14.0.0 # Points HEAD to the tag "14.0.0" - gcuser:~/GCHP$ git branch version_14.0.0 # Creates a new branch at tag "14.0.0" - gcuser:~/GCHP$ git checkout version_14.0.0 # Checks out the version_14.0.0 branch - gcuser:~/GCHP$ git submodule update --init --recursive # Reverts submodules to the "14.0.0" tag + $ git checkout tags/14.0.0 # Points HEAD to the tag "14.0.0" + $ git branch version_14.0.0 # Creates a new branch at tag "14.0.0" + $ git checkout version_14.0.0 # Checks out the version_14.0.0 branch + $ git submodule update --init --recursive # Reverts submodules to the "14.0.0" tag You can do this for any tag in the version history. For a list of all tags, type: .. code-block:: console - gcuser:~/GCHP$ git tag + $ git tag If you have any unsaved changes, make sure you commit those to a branch prior to updating versions. @@ -65,8 +65,25 @@ the prompts: .. code-block:: console - gcuser:~/GCHP$ cd run/ - gcuser:~/GCHP$ ./createRunDir.sh + $ cd run/ + $ ./createRunDir.sh + +.. 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. ======================= 3. Configure your build @@ -83,15 +100,15 @@ guide we will do both, starting with building from the source code. .. code-block:: console - gcuser:~/GCHP$ mkdir ~/GCHP/build - gcuser:~/GCHP$ cd ~/GCHP/build + $ mkdir ~/GCHP/build + $ cd ~/GCHP/build Initialize your build directory by running :program:`cmake`, passing it the path to your source code. Make sure you have loaded all libraries required for GCHP prior to this step. .. code-block:: console - gcuser:~/GCHP/build$ cmake ~/GCHP + $ cmake ~/GCHP Now you can configure :ref:`build options `. These are persistent settings that are saved to your build directory. @@ -103,7 +120,7 @@ the run directory you created in Step 2. .. code-block:: console - gcuser:~/GCHP/build$ cmake . -DRUNDIR="/path/to/your/run/directory" + $ cmake . -DRUNDIR="/path/to/your/run/directory" .. note:: The :literal:`.` in the :program:`cmake` command above is @@ -116,15 +133,15 @@ symbolic link in the run directory: .. code-block:: console - gcuser:/path/to/your/run/directory/$ cd build - gcuser:/path/to/your/run/directory/build$ cmake ../CodeDir -DRUNDIR=.. + $ cd /path/to/your/run/directory/build + $ cmake ../CodeDir -DRUNDIR=.. GEOS-Chem has a number of optional compiler flags you can add here. For example, to compile with RRTMG: .. code-block:: console - gcuser:/path/to/your/run/directory/build$ cmake ../CodeDir -DRUNDIR=.. -DRRTMG=y + $ cmake ../CodeDir -DRUNDIR=.. -DRRTMG=y A useful compiler option is to build in debug mode. Doing this is a good idea if you encountered a segmentation fault in a previous run @@ -132,7 +149,7 @@ and need more information about where the error happened and why. .. code-block:: console - gcuser:/path/to/your/run/directory/build$ cmake ../CodeDir -DRUNDIR=.. -DCMAKE_BUILD_TYPE=Debug + $ cmake ../CodeDir -DRUNDIR=.. -DCMAKE_BUILD_TYPE=Debug See the GEOS-Chem documentation for more information on compiler flags. @@ -147,14 +164,15 @@ available. Do this with the :literal:`-j` flag: .. code-block:: console - gcuser:~/GCHP/build$ make -j + $ cd ~/GCHP/build # Skip if you are already here + $ make -j Upon successful compilation, install the compiled executable to your run directory (or directories): .. code-block:: console - gcuser:~/GCHP/build$ make install + $ make install This copies :file:`bin/gchp` and supplemental files to your run directory. @@ -180,7 +198,7 @@ Now, navigate to your run directory: .. code-block:: console - $ cd path/to/your/run/directory + $ cd /path/to/your/run/directory Commonly changed simulation settings, such as grid resolution, run duration, and number of cores, are set in diff --git a/docs/source/index.rst b/docs/source/index.rst index 5af027817..ebd8af75d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -77,12 +77,12 @@ use Spack to install GCHP's dependencies if needed. geos-chem-shared-docs/supplemental-guides/load-libraries-guide.rst geos-chem-shared-docs/supplemental-guides/spack-guide.rst - geos-chem-shared-docs/supplemental-guides/geos-chem-input-data-on-aws.rst supplement/setting-up-aws-parallelcluster.rst supplement/caching-input-data.rst supplement/containers.rst supplement/stretched-grid.rst supplement/satellite-overpass.rst + geos-chem-shared-docs/doc/gcid-portal-overview.rst geos-chem-shared-docs/supplemental-guides/bashdatacatalog.rst geos-chem-shared-docs/supplemental-guides/history-diag-guide.rst geos-chem-shared-docs/supplemental-guides/netcdf-guide.rst diff --git a/docs/source/user-guide/config-files/HEMCO_Config_rc.rst b/docs/source/user-guide/config-files/HEMCO_Config_rc.rst deleted file mode 100644 index 880fde5fc..000000000 --- a/docs/source/user-guide/config-files/HEMCO_Config_rc.rst +++ /dev/null @@ -1,32 +0,0 @@ - -HEMCO_Config.rc -=============== - -:file:`HEMCO_Config.rc` is used in GCHP for masking and scaling within HEMCO. The input file and read frequency information is not used because MAPL ExtData handles file input rather than HEMCO in GCHP. Items at the top of the file that are ignored include: - -* ROOT data directory path -* METDIR path -* DiagnPrefix -* DiagnFreq -* Wildcard - -The ROOT data directory and METDIR paths are instead specified by the symbolic links in the run directory. Diagnostic filename and frequency information are specified in :file:`HISTORY.rc`. Emissions diagnostics in GCHP are output in the same way and with the same file format as other diagnostic collections in GCHP. Please note, however, that all emissions diagnostics are vertically flipped relative to other diagnostics, with level 1 corresponding to top-of-atmosphere. - -In the BASE EMISSIONS section and beyond, columns that are ignored include: - -* sourceFile -* sourceVar -* sourceTime -* C/R/E -* SrcDim -* SrcUnit - -Because GCHP uses NASA MAPL code to read and regrid input files the file path, variable name, and data frequency are specified in GCHP config file :file:`ExtData.rc`. Input data dimensions and units are not needed since they are taken directly from the file during read. - -Note that some GEOS-Chem simulations require that all species be present in the restart file. For GEOS-Chem Classic you can get around this by updating the :literal:`C/R/E` flags in :file:`HEMCO_Config.rc`. In GCHP that part of :file:`HEMCO_Config.rc` is not used. To configure your run to allow missing species in the restart file you instead need to flip a switch in config file :file:`setCommonRunSettings.sh`. Search for string :literal:`Require_Species_in_Restart` in the file. If set to 1 it will require species, and if set to 0 it will not. - -Also beware that one entry in :file:`HEMCO_Config.rc` is changed when script :file:`setCommonRunSettings.sh` is executed in the run script prior to running GCHP. The online dust mass tuning factor gets replaced by a value specific to your configured grid resolution. - -One entry also gets propagated to another configuration file by :file:`setCommonRunSettings.sh`. Lightning entries in :file:`ExtData.rc` get commented or uncommented depending on whether lightning climatology is turned on in :file:`HEMCO_Config.rc`. - -Refer to the `GEOS-Chem ReadTheDocs page for this file `_ for more detailed information about this file. diff --git a/docs/source/user-guide/config-files/HEMCO_Diagn_rc.rst b/docs/source/user-guide/config-files/HEMCO_Diagn_rc.rst deleted file mode 100644 index de7a48b9f..000000000 --- a/docs/source/user-guide/config-files/HEMCO_Diagn_rc.rst +++ /dev/null @@ -1,5 +0,0 @@ - -HEMCO_Diagn.rc -============== - -Like in GEOS-Chem Classic, the :file:`HEMCO_Diagn.rc` file is used to map between HEMCO containers and output file diagnostic names. Unlike in GEOS-Chem Classic, only HEMCO diagnostics also listed in :file:`HISTORY.rc` will be output. See the `GEOS-Chem ReadTheDocs page on this file `_ for more information about :file:`HEMCO_Diagn.rc`. diff --git a/docs/source/user-guide/config-files/HISTORY_rc.rst b/docs/source/user-guide/config-files/HISTORY_rc.rst index 11f464a3a..60bb072ae 100644 --- a/docs/source/user-guide/config-files/HISTORY_rc.rst +++ b/docs/source/user-guide/config-files/HISTORY_rc.rst @@ -283,7 +283,7 @@ Sampling configuration :literal:`'time-averaged'`. This specifies the length of the time average. By default it is equal to :literal:`frequency`. -.. option:: ref_date: +.. option:: ref_date **OPTIONAL**. The reference date from which the frequency is based. The format is :literal:`YYYYMMDD`. For example, a frequency diff --git a/docs/source/user-guide/config-files/setCommonRunSettings_sh.rst b/docs/source/user-guide/config-files/setCommonRunSettings_sh.rst index 09944458c..02ee00a8f 100644 --- a/docs/source/user-guide/config-files/setCommonRunSettings_sh.rst +++ b/docs/source/user-guide/config-files/setCommonRunSettings_sh.rst @@ -52,7 +52,7 @@ the configurations section earlier in the script. Some of the functions are general, such as printing a message during file update based on if the script was passed optional argument :literal:`--verbose`. Other functions are specialized, such as -replacing met-field read frequency in :ref:`extdata` +replacing met-field read frequency in :ref:`extdata-rc` based on the model timestep. The update files section changes settings in other configuration files diff --git a/docs/source/user-guide/debugging.rst b/docs/source/user-guide/debugging.rst index 983d2d5d5..d70771597 100644 --- a/docs/source/user-guide/debugging.rst +++ b/docs/source/user-guide/debugging.rst @@ -1,16 +1,21 @@ +.. |br| raw:: html + +
+ .. _debugging: ######### Debugging ######### -This page provides strategies for investigating errors encountered while using GCHP. -See also the GEOS-Chem ReadTheDocs pages on -`debugging `_ -and -`understanding what error messages mean `_ which are also linked to in the Supplementary Guides section -of the GCHP ReadTheDocs. Note that those pages, unlike this one, also describe GEOS-Chem Classic and thus -not all examples are applicable to GCHP. +This page provides strategies for investigating errors encountered +while using GCHP. We invite you to also read these Supplemental Guides: + +- :ref:`debug-guide` +- :ref:`errguide` + +Note that those pages, unlike this one, also describe GEOS-Chem +Classic and HEMCO and thus not all examples are applicable to GCHP. ================ Configure errors @@ -19,116 +24,145 @@ Configure errors Configuration using CMake occurs right before compiling the model. A common problem that results in configuration errors is if you forget to run :literal:`git submodule update --init --recursive` after cloning -the GCHP repository. Check that you did this correctly by looking to see if -all subdirectories contain files, e.g. src/MAPL. - -Other configuration problems usually have to do with your environment and libraries. -Check that you have libraries loaded and that they meet the requirements for GCHP. -Also check the logs printed to the build directory, in particular :file:`CMakeCache.txt`. -That file lists the directories of the libraries that are used. -Check that these paths are what you intend. Sometimes on compute clusters -there can be multiple instances of the same library loaded, such as when using a spack-built -library when your compute cluster already has a different version of the same library set -by default. Check the library paths carefully to look for inconsistencies. - -If you create a GitHub issue for a configuration error please include the :file:`CMakeCache.txt` -file in your help request as well as the output sent to screen. +the GCHP repository. Check that you did this correctly by looking to +see if all subdirectories contain files, e.g. src/MAPL. + +Other configuration problems usually have to do with your environment +and libraries. Check that you have libraries loaded and that they meet +the requirements for GCHP. Also check the logs printed to the build +directory, in particular :file:`CMakeCache.txt`. That file lists the +directories of the libraries that are used. Check that these paths are +what you intend. Sometimes on compute clusters +there can be multiple instances of the same library loaded, such as +when using a spack-built library when your compute cluster already has +a different version of the same library set by default. Check the +library paths carefully to look for inconsistencies. + +If you create a GitHub issue for a configuration error please include +the :file:`CMakeCache.txt` file in your help request as well as the +output sent to screen. ============== Compile errors ============== -Usually build-time errors are self-explanatory, with an error message indicating the file, line number, and reason -for the error. However, you may need to do some digging to find the error message. +Usually build-time errors are self-explanatory, with an error message +indicating the file, line number, and reason for the error. However, +you may need to do some digging to find the error message . + +If the build error is occuring with an unaltered GCHP version then the +issue is likely related to libraries. Check that your libraries meet +the requirements of GCHP as specified on ReadTheDocs. Also check your +ESMF version and make sure you built ESMF using the same libraries +with which you are building GCHP. -If the build error is occuring with an unaltered GCHP version then the issue is likely related -to libraries. Check that your libraries meet the requirements of GCHP as specified on -ReadTheDocs. Also check your ESMF version and make sure you built ESMF using the same libraries with which you -are building GCHP. +If you encounter a build error and cannot figure it out from what is +printed to the terminal, rebuild with verbose on and send standard +output and errors to a log. You can do this with -If you encounter a build error and cannot figure it out from what is printed to the terminal, -rebuild with verbose on and send standard output and errors to a log. You can do this with -:literal:`make -j VERBOSE=1 2>&1 | build.log`. -Search the log for string :literal:`error`, first with a space in front of and after the word, and then only -in front. This usually hones in on where the error message occurs. -You want to find the very first occurrence of this in the log. +.. code-block:: console -Read the error message carefully and then find the file and line number specified. -If it is not clear what the error is even from the error message then you can try doing a string search -on the GCHP GitHub issues page, or on the web in general, for the generic error message you get. + $ make -j VERBOSE=1 2>&1 | build.log -If you still have problems then please create an issue on GitHub containing the GCHP version, your -:file:`CMakeCache.txt` file, and your build log. +Search the log for string :literal:`error`, first with a space in +front of and after the word, and then only in front. This usually +hones in on where the error message occurs. You want to find the very +first occurrence of this in the log. + +Read the error message carefully and then find the file and line +number specified. If it is not clear what the error is even from the +error message then you can try doing a string search on the GCHP +GitHub issues page, or on the web in general, for the generic error +message you get. + +If you still have problems then please create an issue on GitHub +containing the GCHP version, your :file:`CMakeCache.txt` file, and +your build log. ======================================= Run-time errors that occur early in run ======================================= -The first step in debugging run-time errors is always to look at the logs. There are three main logs to look at, assuming standard error and standard output are sent to different files. +The first step in debugging run-time errors is always to look at the +logs. There are three main logs to look at, assuming standard error +and standard output are sent to different files. :file:`gchp.YYYYMMDD_hhmmz.log` - This is the log file defined in the run script and contains all GEOS-Chem and HEMCO standard output. - Look at this log to see how far the run got. It is possible the error was trapped by HEMCO or GEOS-Chem - in which case there will be error messages explaining the problem. + This is the log file defined in the run script and contains all + GEOS-Chem and HEMCO standard output. Look at this log to see how + far the run got. It is possible the error was trapped by HEMCO or + GEOS-Chem in which case there will be error messages explaining the problem. :file:`slurm*.out` (or other scheduler log) - If running on a job scheduler this would be a separate file from the main GCHP log file assuming you are - using one of the example run scripts. The error in this file will include a traceback of the error, - meaning filenames and line numbers where the error occurred, moving up the call stack from deepest to highest. - Go to the very first file listed and find the line number. Also read the error message in the traceback. - Try to determine if the error is in GEOS-Chem, HEMCO, MAPL ExtData, MAPL History, MAPL Cap, or somewhere else. + If running on a job scheduler this would be a separate file from + the main GCHP log file assuming you are using one of the example + run scripts. The error in this file will include a traceback of the + error, meaning filenames and line numbers where the error occurred, + moving up the call stack from deepest to highest. Go to the very + first file listed and find the line number. Also read the error + message in the traceback. Try to determine if the error is in + GEOS-Chem, HEMCO, MAPL ExtData, MAPL History, MAPL Cap, or + somewhere else. :file:`allPEs.log` - This log is output by the logger used in MAPL. By default it provides basic information on the MAPL run - including general GCHP infrastructure setup as well as model I/O. You can configure the model to output more - to this file. See the section on errors in MAPL below. - -Choose next steps based on what you see in the logs. The following sections go into detail about the different -approaches you can take to debugging based on the error. Read through all the topics to choose which approach -seems most appropriate. - -For all strategies we recommend doing a short run at low resolution and with few cores -to make your debug runs fast and lightweight. -You should also always do a web search of the issue to see if there is an existing GitHub issue about it. -The `GCHP GitHub Issues page `_ includes a search bar. -Depending on the issue, you might also find the problem -already discussed on the `GEOS-Chem `_ or -`HEMCO `_ GitHub issues pages. + This log is output by the logger used in MAPL. By default it + provides basic information on the MAPL run including general GCHP + infrastructure setup as well as model I/O. You can configure the + model to output more to this file. See the section on errors in MAPL below. + +Choose next steps based on what you see in the logs. The following +sections go into detail about the different approaches you can take to +debugging based on the error. Read through all the topics to choose +which approach seems most appropriate. + +For all strategies we recommend doing a short run at low resolution +and with few cores to make your debug runs fast and lightweight. You +should also always do a web search of the issue to see if there is an +existing GitHub issue about it. The `GCHP GitHub Issues page +`_ includes a search +bar. Depending on the issue, you might also find the problem already +discussed on the `GEOS-Chem +`_ or `HEMCO +`_ GitHub issues pages. Segmentation faults ------------------- -If you are running into a segmentation fault then you should rebuild with debug flags turned on. -Do this by setting :literal:`-DCMAKE_BUILD_TYPE=Debug` during the configure step. -See compiling GCHP for more guidance on how to do this. -Once you rebuild and run there may be more information in the logs if the problem is an -out-of-bounds error or floating point exception. -Once the error is fixed remember to rebuild without debug flags on. Running the model after building -with debug flags will make the model run very slow. +If you are running into a segmentation fault then you should rebuild +with debug flags turned on. Do this by setting +:literal:`-DCMAKE_BUILD_TYPE=Debug` during the configure step. See +compiling GCHP for more guidance on how to do this. Once you rebuild +and run there may be more information in the logs if the problem is an +out-of-bounds error or floating point exception. Once the error is +fixed remember to rebuild without debug flags on. Running the model +after building with debug flags will make the model run very slow. Read the traceback ------------------ -If the problem is not a segmentation fault and the GCHP log messages are not helpful then you should -follow the error traceback to the source code where the problem occurs. Always search for the first -file listed along with the line number. You can find the location of -files in GCHP by using the unix find command from the top-level source code directory, -e.g. :literal:`find . -name aerosol_mod.F90`. -Once you find the file and the line where the model fails you can read the code above it to try -to get a sense of the context of where it crashed. This will give clues as to -why it had a problem and may give you ideas of what to do to try to fix it. +If the problem is not a segmentation fault and the GCHP log messages +are not helpful then you should follow the error traceback to the +source code where the problem occurs. Always search for the first file +listed along with the line number. You can find the location of files +in GCHP by using the unix find command from the top-level source code +directory, e.g. :literal:`find . -name aerosol_mod.F90`. +Once you find the file and the line where the model fails you can read +the code above it to try to get a sense of the context of where it +crashed. This will give clues as to why it had a problem and may give +you ideas of what to do to try to fix it. Errors in GEOS-Chem and HEMCO ----------------------------- -Sometimes enabling built-in debug prints from GEOS-Chem and HEMCO can help find the error. -You can enable additional prints to the main GCHP log within configuration files -:literal:`geoschem_config.yml` and :literal:`HEMCO_Config.rc`. +Sometimes enabling built-in debug prints from GEOS-Chem and HEMCO can +help find the error. You can enable additional prints to the main GCHP +log within configuration files :literal:`geoschem_config.yml` and +:literal:`HEMCO_Config.rc`. #. Activate GEOS-Chem verbose output by editing :file:`geoschem_config.yml` as shown below. This will tell - GEOS-Chem to send extra printout to the :file:`gchp.YYYYMMDD_hhmmz.log` - file. + GEOS-Chem to send extra printout to the + :file:`gchp.YYYYMMDD_hhmmz.log` file. .. code-block:: yaml @@ -141,10 +175,9 @@ You can enable additional prints to the main GCHP log within configuration files activate: false <=== Change this to true on_cores: root # Allowed values: root all -#. Activate HEMCO verbose output by editing - :file:`HEMCO_Config.rc` as shown below. This will tell - HEMCO to send extra printout to the :file:`gchp.YYYYMMDD_hhmmz.log` - file. +#. Activate HEMCO verbose output by editing :file:`HEMCO_Config.rc` as + shown below. This will tell HEMCO to send extra printout to the + :file:`gchp.YYYYMMDD_hhmmz.log` file. .. code-block:: kconfig @@ -159,101 +192,123 @@ You can enable additional prints to the main GCHP log within configuration files MAPL ExtData errors (data inputs) --------------------------------- -If you see :literal:`ExtData` in the error traceback then the problem has to do with input files and you should check -log file :file:`allPEs.log`. If there is not enough information in :literal:`allPEs.log` to determine what the -input file problem is then you should enable additional MAPL prints and rerun. This is mostly recommended for input -file issues because MAPL ExtData is where most of the debug logging statements are currently implemented. +If you see :literal:`ExtData` in the error traceback then the problem +has to do with input files and you should check log file +:file:`allPEs.log`. If there is not enough information in +:literal:`allPEs.log` to determine what the +input file problem is then you should enable additional MAPL prints +and rerun. This is mostly recommended for input file issues because +MAPL ExtData is where most of the debug logging statements are +currently implemented. -Activate the :literal:`CAP.EXTDATA` and :literal:`MAPL` debug loggers by -editing the :file:`logging.yml` configuration file as shown below. -This will send all MAPL debug-level logging prints to the :file:`allPEs.log` file. +Activate the :literal:`CAP.EXTDATA` and :literal:`MAPL` debug loggers +by editing the :file:`logging.yml` configuration file as shown below. +This will send all MAPL debug-level logging prints to the +:file:`allPEs.log` file. .. code-block:: yaml loggers: - + # ... etc not shown ... - + MAPL: handlers: [mpi_shared] level: WARNING root_level: INFO <=== Change this to DEBUG - + CAP.EXTDATA: handlers: [mpi_shared] level: WARNING root_level: INFO <=== Change this to DEBUG -See `logging.yml `__ for more information on the MAPL logger config file. -Contact the GEOS-Chem Support Team if you need help deciphering the resulting log output. +See `logging.yml `__ for more +information on the MAPL logger config file. Contact the GEOS-Chem +Support Team if you need help deciphering the resulting log output. -If needed, you can also turn off certain emissions in :file:`HEMCO_Config.rc` to verify which inventory -is causing problems. This can sometimes help hone in the sections of the configuration files to -look for typos. +If needed, you can also turn off certain emissions in +:file:`HEMCO_Config.rc` to verify which inventory is causing +problems. This can sometimes help hone in the sections of the +configuration files to look for typos. -If the problem is due to adding new input files then you may have an issue in either the configuration -files or with the file itself. It is common to run into these sorts of errors when adding new input -files because of strict rules for import files within MAPL and the need to follow a specific format +If the problem is due to adding new input files then you may have an +issue in either the configuration files or with the file itself. It is +common to run into these sorts of errors when adding new input files because of strict rules for import files within MAPL and the need to follow a specific format for input data in configuration files. Make sure that you read the ReadTheDocs -pages on `HEMCO_Config.rc `__ and `ExtData.rc `__. -Also see NASA wiki page on -`supported ExtData input files `_. +pages on `HEMCO_Config.rc `__ and +`ExtData.rc `__. +Also see NASA wiki page on `supported ExtData input files +`_. Diagnostic errors ----------------- -If :file:`MAPL_HistoryGridCompMod.F90` appears in the error traceback then the issue has to do with diagnostics -in MAPL. This is usually due to a typo in `HISTORY.rc `__. Try to comment -out different collections in your :file:`HISTORY.rc` file to see if you can get past the issue. -If you isolate it to one or more collections then look closely at the file to try to find a typo. -Following the traceback to the MAPL History code is also very useful since it may tell you which entry in -the config file is causing the problem. - -There can be other problems with GCHP diagnostics that do not have to do with MAPL History. -If your log has error messages from GEOS-Chem about not being able to find an entry in the Registry, -or if the error traceback includes file :file:`gchp_historyexports_mod.F90`, then the issue is likely -in GEOS-Chem. You can print out more diagnostic information to the GCHP log by enabling verbose prints -in GEOS-Chem (see earlier section on this page). - -You can print out even more information by manually -uncommenting :literal:`CALL Print_DiagList`, :literal:`CALL Print_TaggedDiagList`, and -:literal:`CALL Print_HistoryExportsList` within +If :file:`MAPL_HistoryGridCompMod.F90` appears in the error traceback +then the issue has to do with diagnostics in MAPL. This is usually due +to a typo in `HISTORY.rc `__. Try to +comment out different collections in your :file:`HISTORY.rc` file to see if +you can get past the issue. If you isolate it to one or more +collections then look closely at the file to try to find a +typo. Following the traceback to the MAPL History code is also very +useful since it may tell you which entry in the config file is causing +the problem. + +There can be other problems with GCHP diagnostics that do not have to +do with MAPL History. If your log has error messages from GEOS-Chem +about not being able to find an entry in the Registry, or if the error +traceback includes file :file:`gchp_historyexports_mod.F90`, then the +issue is likely in GEOS-Chem. You can print out more diagnostic +information to the GCHP log by enabling verbose prints in GEOS-Chem +(see earlier section on this page). + +You can print out even more information by manually uncommenting +:literal:`CALL Print_DiagList`, :literal:`CALL Print_TaggedDiagList`, +and :literal:`CALL Print_HistoryExportsList` within :literal:`src/GCHP_GridComp/GEOSChem_GridComp/geos-chem/Interfaces/GCHP/gchp_historyexports_mod.F90`. -Then rebuild and rerun. This will show you what diagnostics GEOS-Chem "registers", meaning how it -interprets :file:`HISTORY.rc`, as well as what diagnostics MAPL makes into imports. Any mismatch in these -lists will result in a run error. Note that MAPL creates imports for all fields in collections that are -turned on using the name that appears in :file:`HISTORY.rc`. GEOS-Chem's registry of fields is more -complicated because it uses the field names to determine which arrays the data are located in. Mismatches are -thus usually because of a problem in GEOS-Chem's parsing of the configuration file. +Then rebuild and rerun. This will show you what diagnostics GEOS-Chem +"registers", meaning how it interprets :file:`HISTORY.rc`, as well as +what diagnostics MAPL makes into imports. Any mismatch in these lists +will result in a run error. Note that MAPL creates imports for all +fields in collections that are turned on using the name that appears +in :file:`HISTORY.rc`. GEOS-Chem's registry of fields is more +complicated because it uses the field names to determine which arrays +the data are located in. Mismatches are thus usually because of a +problem in GEOS-Chem's parsing of the configuration file. Other MAPL errors ----------------- -If the error is in MAPL but is not in ExtData or History then you should still enable -additional MAPL prints to log and rerun. -See the section above on ExtData errors for how to do that. Currently most logging messages are in ExtData -but there are a few others that might be useful. You can also add your own within MAPL. See the next section for -how to do that. - -If the error is in MAPL and the traceback leads you to a call to ESMF then you should enable ESMF error -log files in GCHP and rerun. Look for file :literal:`ESMF.rc` in your run directory. Open it and -set the :literal:`logKindFlag` parameter to :literal:`ESMF_LOGKIND_MULTI_ON_ERROR` and run again. You should then get -ESMF error log files upon rerun. There will be one log file per processor and each file will start with :literal:`PET`. +If the error is in MAPL but is not in ExtData or History then you +should still enable additional MAPL prints to log and rerun. See the +section above on ExtData errors for how to do that. Currently most +logging messages are in ExtData but there are a few others that might +be useful. You can also add your own within MAPL. See the next section +for how to do that. + +If the error is in MAPL and the traceback leads you to a call to ESMF +then you should enable ESMF error log files in GCHP and rerun. Look +for file :literal:`ESMF.rc` in your run directory. Open it and set the +:literal:`logKindFlag` parameter to +:literal:`ESMF_LOGKIND_MULTI_ON_ERROR` and run again. You +should then get ESMF error log files upon rerun. There will be one log +file per processor and each file will start with :literal:`PET`. More often than not the ESMF error message will appear in every file. Add your own prints ------------------- -Sometimes the best way to find the problem is to add print commands to the source code, rebuild, and rerun. -This is particularly true if you know it is failing in a loop reading data files or parsing a -configuration file. -You can find examples in GEOS-Chem and HEMCO on printing messages from within nearly all files. -For MAPL you can use the logger. Search MAPL for :literal:`lgr%debug` to find examples. +Sometimes the best way to find the problem is to add print commands to +the source code, rebuild, and rerun. This is particularly true if you +know it is failing in a loop reading data files or parsing a +configuration file. You can find examples in GEOS-Chem and HEMCO on +printing messages from within nearly all files. For MAPL you can use +the logger. Search MAPL for :literal:`lgr%debug` to find examples. ====================================== Run-time errors that occur late in run ====================================== +To be added ================== Performance issues @@ -276,11 +331,14 @@ after run methods for gridded components GCHPctmEnv, FV3 advection, and GEOS-Chem. Within GEOS-Chem, total and swap memory will also be printed before and after subroutines to run GEOS-Chem, perform chemistry, and apply emissions. For more information about inspecting -memory see the :literal:`Memory` section of the `output files page `__. +memory see the :literal:`Memory` section of the `output files page +`__. Inspecting timing ----------------- -Model timing information is printed out at the end of each GCHP run. Check the end of the GCHP log for a breakdown -of component timing. See the :literal:`Timing` section of the `output files page `__ for instructions on how to read the timing information printed to log. - +Model timing information is printed out at the end of each GCHP +run. Check the end of the GCHP log for a breakdown of component +timing. See the :literal:`Timing` section of the `output files page +`__ for instructions on how to read the timing +information printed to log. diff --git a/docs/source/user-guide/getting-input-data.rst b/docs/source/user-guide/getting-input-data.rst index 3d853478c..6f2025beb 100644 --- a/docs/source/user-guide/getting-input-data.rst +++ b/docs/source/user-guide/getting-input-data.rst @@ -4,18 +4,20 @@ Download Input Data ################### -Input data for GEOS-Chem is available at -http://geoschemdata.wustl.edu/ExtData/. +Input data for GEOS-Chem is available at the :ref:`GEOS-Chem Input +Data ` portal. You may browse the contents of the data at this +link: https://geos-chem.s3.amazonaws.com/index.html -The bashdatacatalog is the recommended for downloading and managing -your GEOS-Chem input data. Refer to the bashdatacatalog's +The bashdatacatalog is the recommended method for downloading and +managing your GEOS-Chem input data. Refer to the bashdatacatalog's `Instructions for GEOS-Chem Users `_. Below is a brief summary of using the bashdatacatalog for aquiring GCHP input data. +=========================== Install the bashdatacatalog ---------------------------- +=========================== Install the bashdatacatalog with the following command. Follow the prompts and restart your console. @@ -26,8 +28,9 @@ prompts and restart your console. .. note:: You can rerun this command to upgrade to the latest version. +====================== Download Data Catalogs ----------------------- +====================== Catalog files can be downloaded from http://geoschemdata.wustl.edu/ExtData/DataCatalogs/. @@ -124,4 +127,4 @@ See Also - `bashdatacatalog - Instructions for GEOS-Chem Users `_ - `bashdatacatalog - List of useful commands `_ -- `GEOS-Chem Input Data Catalogs `_ +- `GEOS-Chem Input Data Catalogs `_ diff --git a/docs/source/user-guide/rundir-config.rst b/docs/source/user-guide/rundir-config.rst index 48c24b61c..0e32224ef 100644 --- a/docs/source/user-guide/rundir-config.rst +++ b/docs/source/user-guide/rundir-config.rst @@ -1,288 +1,469 @@ +.. |br| raw:: html + +
+ +############### Configure a run -=============== +############### -As noted earlier, the many configuration files in GCHP can be overwhelming but you should be able to accomplish most if not all of what you wish to configure from one place in :file:`setCommonRunSettings.sh`. Use this section to learn what to change in the run directory based on what you would like to do. +As noted earlier, the many configuration files in GCHP can be +overwhelming but you should be able to accomplish most if not all of +what you wish to configure from one place in +:file:`setCommonRunSettings.sh`. Use this section to learn what to +change in the run directory based on what you would like to do. .. contents:: Table of contents :depth: 4 ---------------------------------------------------------------------------------------------------- - .. note:: - If there is topic not covered on this page that you would like to see added please create an issue on the `GCHP issues page `_ with your request. + If there is topic not covered on this page that you would like to + see added please create an issue on the `GCHP issues page + `_ with your request. +================= Compute resources ------------------ +================= Set number of nodes and cores -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To change the number of nodes and cores for your run you must update settings in -two places: (1) :file:`setCommonRunSettings.sh`, and (2) your run script. -The :file:`setCommonRunSettings.sh` file contains detailed instructions on how -to set resource parameter options and what they mean. -Look for the Compute Resources section in the script. -Update your resource request in your run script to match the resources set -in :file:`setCommonRunSettings.sh`. - -It is important to be smart about your resource allocation. -To do this it is useful to understand how GCHP works with respect to distribution of -nodes and cores across the grid. -At least one unique core is assigned to each face on the cubed sphere, resulting in -a constraint of at least six cores to run GCHP. -The same number of cores must be assigned to each face, resulting in another -constraint of total number of cores being a multiple of six. -There is also an upper limit on total number of cores for any given grid resolution. -Advection also requires that each core cover a domain size of at least 4x4 grid cells. -For C24 this means there needs to be at least 36 cores per face because a 24x24 face -can be broken into 36 4x4 regions. This translates into a maximum of 216 cores for C24, -864 cores for C48, 3174 cores for C90, 12150 cores for C180, and so on. - -Communication between the cores occurs only during transport processes and -you will typically start to see negative effects due to -excessive communication if a core is handling less than around one hundred grid cells. -You can determine -approximately how many grid cells are handled per core by analyzing your grid resolution and -resource allocation. Total number of grid cells is equal to N*N*6 for grid resolution CN, -e.g. 24*24*6 for C24. Number of grid cells handled per core is then N*N*6 divided by -total number of cores. This number is approximate since number of grid cells per core can -vary across each face, such as if you run C48 with 360 cores. - -Excessive communication may also occur if the grid cell region of a core is not -approximately square. Run-time parameters :literal:`NX` and :literal:`NY` quantify how -each face will be decomposed and can be set to maximize squareness. The product of these -parameters is equal to the total number of cores and each face will be -divided into :literal:`NX` x :literal:`NY/6` regions. Setting :literal:`NX` and -:literal:`NY/6` as close as possible in value will therefore ensure optimal communication. -Maximizing squareness of -grid cells per core is done automatically for you within :file:`setCommonRunSettings.sh`. -You may disable that feature by changing variable :samp:`AutoUpdate_NXNY` to :samp:`OFF` -in the "DOMAIN DECOMPOSITON" section of the file. Beware that disabling it will require you -to set :literal:`NX` and :literal:`NY` yourself in the file. - -If using mass flux input data then there is an additional constraint that the model grid -divides evenly across cores. In other words NX and NY/6 must divide evenly into N where -the run grid resolution is CN. For example, a C30 run can have each face split into -6x6 regions but not 4x4 regions. The former gives a 5x5 grid cell region per core while -the latter gives 7.5x7.5 which is non-integer. This has implications for total number of -cores you can run with when using mass flux inputs since a given total number of cores can -evenly divide every possible grid resolution. +----------------------------- + +To change the number of nodes and cores for your run you must update +settings in two places: (1) :file:`setCommonRunSettings.sh`, and (2) +your run script. +The :file:`setCommonRunSettings.sh` file contains detailed +instructions on how to set resource parameter options and what they +mean. Look for the Compute Resources section in the script. +Update your resource request in your run script to match the resources +set in :file:`setCommonRunSettings.sh`. + +It is important to be smart about your resource allocation. To do this +it is useful to understand how GCHP works with respect to distribution +of nodes and cores across the grid. At least one unique core is +assigned to each face on the cubed sphere, resulting in a constraint +of at least six cores to run GCHP. The same number of cores must be +assigned to each face, resulting in another constraint of total number +of cores being a multiple of six. There is also an upper limit on +total number of cores for any given grid resolution. Advection also +requires that each core cover a domain size of at least 4x4 grid +cells. For C24 this means there needs to be at least 36 cores per face +because a 24x24 face can be broken into 36 4x4 regions. This +translates into a maximum of 216 cores for C24, 864 cores for C48, +3174 cores for C90, 12150 cores for C180, and so on. + +Communication between the cores occurs only during transport processes +and you will typically start to see negative effects due to excessive +communication if a core is handling less than around one hundred grid +cells. You can determine approximately how many grid cells are handled +per core by analyzing your grid resolution and resource +allocation. Total number of grid cells is equal to N*N*6 for grid +resolution CN, e.g. 24*24*6 for C24. Number of grid cells handled per +core is then N*N*6 divided by total number of cores. This number is +approximate since number of grid cells per core can vary across each +face, such as if you run C48 with 360 cores. + +Excessive communication may also occur if the grid cell region of a +core is not approximately square. Run-time parameters :literal:`NX` +and :literal:`NY` quantify how each face will be decomposed and can be +set to maximize squareness. The product of these parameters is equal +to the total number of cores and each face will be divided into +:literal:`NX` x :literal:`NY/6` regions. Setting :literal:`NX` and +:literal:`NY/6` as close as possible in value will therefore ensure +optimal communication. Maximizing squareness of grid cells per core +is done automatically for you within +:file:`setCommonRunSettings.sh`. You may disable that feature by +changing variable :samp:`AutoUpdate_NXNY` to :samp:`OFF` in the +"DOMAIN DECOMPOSITON" section of the file. Beware that disabling it +will require you to set :literal:`NX` and :literal:`NY` yourself in +the file. + +If using mass flux input data then there is an additional constraint +that the model grid divides evenly across cores. In other words NX and +NY/6 must divide evenly into N where the run grid resolution is +CN. For example, a C30 run can have each face split into 6x6 regions +but not 4x4 regions. The former gives a 5x5 grid cell region per core +while the latter gives 7.5x7.5 which is non-integer. This has +implications for total number of cores you can run with when using +mass flux inputs since a given total number of cores can evenly divide +every possible grid resolution. Change domain stack size -^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------ -For runs at very high resolution or small number of processors you may run into a domains stack size error. -This is caused by exceeding the domains stack size memory limit set at run-time. The error will be apparent from the message in your log file. -If this occurs you can increase the domains stack size in file :file:`input.nml`. +For runs at very high resolution or small number of processors you may +run into a domains stack size error. This is caused by exceeding the +domains stack size memory limit set at run-time. The error will be +apparent from the message in your log file. If this occurs you can +increase the domains stack size in file :file:`input.nml`. Considerations for very high core counts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------------------- -GCHP has the capability of running on tens of thousands of cores. If running at very -high grid resolution and you have access to this level of compute power then there are a few -things to consider prior to submitting your run. +GCHP has the capability of running on tens of thousands of cores. If +running at very high grid resolution and you have access to this level +of compute power then there are a few things to consider prior to +submitting your run. -First, very high resolution runs make -model I/O more challenging. Restart files will be very large and reading and writing them -will be intensive. Second, MPI configuration, file system, and compute hardware can make or -break your run at this scale. This often comes back to challenges with I/O. -For example, we have found that using OpenMPI on certain -compute clusters requires turning on the MAPL O-server for checkpoint write to prevent -the model from hanging. +First, very high resolution runs make model I/O more +challenging. Restart files will be very large and reading and writing +them will be intensive. Second, MPI configuration, file system, and +compute hardware can make or break your run at this scale. This often +comes back to challenges with I/O. For example, we have found that +using OpenMPI on certain compute clusters requires turning on the MAPL +O-server for checkpoint write to prevent the model from hanging. There are a few settings in configuration file :literal:`GCHP.rc` that -you can play with to try to improve performance in this area. -:literal:`NUM_READERS` parallelizes -restart read and setting it to values between 6 and 24 may yield improvement. -:literal:`WRITE_RESTART_BY_OSERVER` assigns restart write to extra nodes by running what -is called the O-server. The O-server is off by default but can be toggled on manually. -:literal:`NUM_WRITERS` affects how many processes to write with. You can try -anywhere from 6 to 24 to see if it makes a differences. -Note that none of these settings are dependable ways -to speed up or fix a run because they are dependent on file system and MPI stack. - -Lastly, your specific grid resolution will impact how -performance scales with more cores. FV3 advection has a point of diminishing returns due -to excessive communication if core count gets too high for a given run resolution. See -earlier section on setting number of nodes and cores. - ---------------------------------------------------------------------------------------------------- - +you can play with to try to improve performance in this area. +:literal:`NUM_READERS` parallelizes restart read and setting it to +values between 6 and 24 may yield +improvement. :literal:`WRITE_RESTART_BY_OSERVER` assigns restart write +to extra nodes by running what is called the O-server. The O-server is +off by default but can be toggled on manually. :literal:`NUM_WRITERS` +affects how many processes to write with. You can try anywhere from 6 +to 24 to see if it makes a differences. Note that none of these +settings are dependable ways to speed up or fix a run because they are +dependent on file system and MPI stack. + +Lastly, your specific grid resolution will impact how performance +scales with more cores. FV3 advection has a point of diminishing +returns due to excessive communication if core count gets too high for +a given run resolution. See earlier section on setting number of nodes +and cores. + +================== Basic run settings ------------------- +================== Set cubed-sphere grid resolution -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -GCHP uses a cubed sphere grid rather than the traditional lat-lon grid used in GEOS-Chem Classic. -While regular lat-lon grids are typically designated as ΔLat ⨉ ΔLon (e.g. 4⨉5), cubed sphere grids are designated by the side-length of the cube. -In GCHP we specify this as CX (e.g. C24 or C180). -The simple rule of thumb for determining the roughly equivalent lat-lon resolution for a given cubed sphere resolution is to divide the side length by 90. -Using this rule you can quickly match C24 with about 4x5, C90 with 1 degree, C360 with quarter degree, and so on. - -To change your grid resolution in the run directory edit :literal:`CS_RES` in the "GRID RESOLUTION" section of :file:`setCommonRunSettings.sh`. The paramter should be an integer value of the cube side length you wish to use. -To use a uniform global grid resolution make sure :literal:`STRETCH_GRID` is set to :literal:`OFF` in the "STRETCHED GRID" section of the file. To use a stretched grid rather than a globally uniform grid see the section on this page for setting stretched grid parameters. +-------------------------------- + +GCHP uses a cubed sphere grid rather than the traditional lat-lon grid +used in GEOS-Chem Classic. While regular lat-lon grids are typically +designated as ΔLat ⨉ ΔLon (e.g. 4⨉5), cubed sphere grids are +designated by the side-length of the cube. In GCHP we specify this as +CX (e.g. C24 or C180). The simple rule of thumb for determining the +roughly equivalent lat-lon resolution for a given cubed sphere +resolution is to divide the side length by 90. Using this rule you +can quickly match C24 with about 4x5, C90 with 1 degree, C360 with +quarter degree, and so on. + +To change your grid resolution in the run directory edit +:literal:`CS_RES` in the "GRID RESOLUTION" section of +:file:`setCommonRunSettings.sh`. The paramter should be an +integer value of the cube side length you wish to use. +To use a uniform global grid resolution make sure +:literal:`STRETCH_GRID` is set to :literal:`OFF` in the "STRETCHED +GRID" section of the file. To use a stretched grid rather +han a globally uniform grid see the section on this page for +setting stretched grid parameters. Set stretched grid parameters -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------------------------- -GCHP has the capability to run with a stretched grid, meaning one portion of the globe is stretched to fine resolution. -Set stretched grid parameter in :file:`setCommonRunSettings.sh` section "STRETCHED GRID". -See instructions in that section of the file. For more detailed information see the stretched grid section of the Supplemental Guides section of the GCHP ReadTheDocs. +GCHP has the capability to run with a stretched grid, meaning one +portion of the globe is stretched to fine resolution. Set stretched +grid parameter in :file:`setCommonRunSettings.sh` section "STRETCHED +GRID". See instructions in that section of the file. For more +detailed information see the stretched grid section of the +Supplemental Guides section of the GCHP ReadTheDocs. Turn on/off model components -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------- -You can toggle most primary GEOS-Chem components that are set in :file:`geoschem_config.yml` from the "GEOS-CHEM COMPONENTS" section of :file:`setCommonRunSettings.sh`. The settings in that file will update :file:`geoschem_config.yml` automatically so be sure to check that the settings there are as you intend. For emissions you should directly edit :file:`HEMCO_Config.rc`. +You can toggle most primary GEOS-Chem components that are set in +:file:`geoschem_config.yml` from the "GEOS-CHEM COMPONENTS" section of +:file:`setCommonRunSettings.sh`. The settings in that file will +update :file:`geoschem_config.yml` automatically so be +sure to check that the settings there are as you +intend. For emissions you should directly edit +:file:`HEMCO_Config.rc`. Change model timesteps -^^^^^^^^^^^^^^^^^^^^^^ +---------------------- -Model timesteps, including chemistry, dynamic, and RRTMG, are configured within the "TIMESTEPS" section of :file:`setCommonRunSettings.sh`. -By default, the RRTMG timestep is set to 3 hours. All other GCHP timesteps are automatically set based on grid resolution. Chemistry and dynamic timesteps are 20 and 10 minutes respectively for grid resolutions coarser than C180, and 10 and 5 minutes for C180 and higher. Meteorology read frequency for PS2, SPHU2, and TMPU2 are automatically updated in :file:`ExtData.rc` accordingly. To change the default timesteps settings edit the "TIMESTEPS" section of :file:`setCommonRunSettings.sh`. +Model timesteps, including chemistry, dynamic, and RRTMG, are +configured within the "TIMESTEPS" section of +:file:`setCommonRunSettings.sh`. By default, the RRTMG timestep is set +to 3 hours. All other GCHP timesteps are automatically set based +on grid resolution. Chemistry and dynamic timesteps are 20 and +10 minutes respectively for grid resolutions coarser than C180, +and 10 and 5 minutes for C180 and higher. Meteorology read +frequency for PS2, SPHU2, and TMPU2 are automatically updated in +:file:`ExtData.rc` accordingly. To change the default timesteps +settings edit the "TIMESTEPS" section of +:file:`setCommonRunSettings.sh`. Set simulation start date and duration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Unlike GEOS-Chem Classic, GCHP uses a start date and run duration rather than start and end dates. Set simulation start date in :file:`cap_restart` using string format :literal:`YYYYMMDD HHmmSS`. Set simulation duration in section "SIMULATION DURATION" in :file:`setCommonRunSettings.sh` using the same format as start date. For example, a 1-year run starting 15 January 2019 would have :literal:`20190115 000000` in :file:`cap_restart` and :literal:`00010000 000000` in :file:`setCommonRunSettings.sh`. - -Under the hood :file:`cap_restart` is used directly by the MAPL software in GCHP, and :file:`setCommonRunSettings.sh` auto-updates the run duration in GCHP config file :file:`CAP.rc`. Please be aware that MAPL overwrites :file:`cap_restart` at the end of the simulation to contain the new start date (end of last run) so be sure to check it every time you run GCHP. - -If you poke around the GCHP configuration files you may notice that file :file:`CAP.rc` contains entries for :literal:`BEG_DATE` and :literal:`END_DATE`. You can ignore these fields for most cases. :file:`BEG_DATE` is not used for start date if :file:`cap_restart` is present. However, it must be prior to your start date for use in GEOS-Chem's "ELAPSED_TIME" variable. We set it to year 1960 to be safe. :file:`BEG_DATE` can also be ignored as long as it is the same as or later than your start date plus run duration. For safety we set it to year 2200. The only time you would need to adjust these settings is for simulations way in the past or way into the future. - ---------------------------------------------------------------------------------------------------- - +-------------------------------------- + +Unlike GEOS-Chem Classic, GCHP uses a start date and run duration +rather than start and end dates. Set simulation start date in +:file:`cap_restart` using string format :literal:`YYYYMMDD +HHmmSS`. Set simulation duration in section "SIMULATION +DURATION" in :file:`setCommonRunSettings.sh` using the same +format as start date. For example, a 1-year run starting 15 +January 2019 would have :literal:`20190115 000000` in +:file:`cap_restart` and :literal:`00010000 000000` in +:file:`setCommonRunSettings.sh`. + +Under the hood :file:`cap_restart` is used directly by the MAPL +software in GCHP, and :file:`setCommonRunSettings.sh` auto-updates the +run duration in GCHP config file :file:`CAP.rc`. Please be aware that +MAPL overwrites :file:`cap_restart` at the end of the simulation to +contain the new start date (end of last run) so be sure to check it +every time you run GCHP. + +If you poke around the GCHP configuration files you may notice that +file :file:`CAP.rc` contains entries for :literal:`BEG_DATE` and +:literal:`END_DATE`. You can ignore these fields for most +cases. :file:`BEG_DATE` is not used for start date if +:file:`cap_restart` is present. However, it must be prior to your +start date for use in GEOS-Chem's "ELAPSED_TIME" variable. We set it +to year 1960 to be safe. :file:`BEG_DATE` can also be ignored as long +as it is the same as or later than your start date plus run +duration. For safety we set it to year 2200. The only time you would +need to adjust these settings is for simulations way in the past or +way into the future. + +====== Inputs ------- +====== Change restart file -^^^^^^^^^^^^^^^^^^^ - -All GCHP run directories come with symbolic links to initial restart files for commonly used cubed sphere resolutions. These are located in the :file:`Restarts` directory in the run directory. All initial restart files contain start date and grid resolution in the filename using the start date in :file:`cap_restart`. Prior to running GCHP, either you or your run script will execute :file:`setRestartLink.sh` to create a symbolic link :file:`gchp_restart.nc4` to point to the appropriate restart file given configured start date and grid resolution. :file:`gchp_restart.nc4` will always be used as the restart file for all runs since it is specified as the restart file in :file:`GCHP.rc`. - -If you want to change the restart file then you should put the restart file you want to use in the :file:`Restarts` directory using the expected filename format with the start date you configure in :file:`cap_restart` and the grid resolution you configure in :file:`setCommonRunSettings.sh`. The expected format is :literal:`GEOSChem.Restarts.YYYYMMDD_HHmmz.cN.nc4`. Running :file:`setRestartLink.sh` will update :file:`gchp_restart.nc4` to use it. - -If you do not want to rename your restart file then you can create a symbolic link in the :file:`Restarts` folder that points to it. - -Please note that unlike GC-Classic, GCHP does not use a separate HEMCO restart file. All HEMCO restart variables are included in the main GCHP restart. +------------------- + +All GCHP run directories come with symbolic links to initial restart +files for commonly used cubed sphere resolutions. These are located in +the :file:`Restarts` directory in the run directory. All initial +restart files contain start date and grid resolution in the filename +using the start date in :file:`cap_restart`. Prior to running GCHP, +either you or your run script will execute :file:`setRestartLink.sh` +to create a symbolic link :file:`gchp_restart.nc4` to point to the +appropriate restart file given configured start date and grid +resolution. :file:`gchp_restart.nc4` will always be used as the +restart file for all runs since it is specified as the restart file in +:file:`GCHP.rc`. + +If you want to change the restart file then you should put the restart +file you want to use in the :file:`Restarts` directory using the +expected filename format with the start date you configure in +:file:`cap_restart` and the grid resolution you configure in +:file:`setCommonRunSettings.sh`. The expected format is +:literal:`GEOSChem.Restarts.YYYYMMDD_HHmmz.cN.nc4`. Running +:file:`setRestartLink.sh` will update +:file:`gchp_restart.nc4` to use it. + +If you do not want to rename your restart file then you can create a +symbolic link in the :file:`Restarts` folder that points to it. + +Please note that unlike GC-Classic, GCHP does not use a separate HEMCO +restart file. All HEMCO restart variables are included in the main +GCHP restart. Enable restart file to have missing species -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------------------- -Most simulations by default do not allow missing species in the restart file. -The model will exit with an error if species are not found. -However, there is a switch in :file:`setCommonRunSetting.sh` to disable this behavior. -This toggle is located in the section on infrequently changed settings under the header :file:`REQUIRE ALL SPECIES IN INITIAL RESTART FILE`. -Setting the switch to :file:`NO` will use background values set in :file:`species_database.yml` as initial values for species that are missing. +Most simulations by default do not allow missing species in the +restart file. The model will exit with an error if species are not +found. However, there is a switch in :file:`setCommonRunSetting.sh` to +disable this behavior. This toggle is located in the section on +infrequently changed settings under the header :file:`REQUIRE ALL +SPECIES IN INITIAL RESTART FILE`. Setting the switch to :file:`NO` +will use background values set in :file:`species_database.yml` as +initial values for species that are missing. Turn on/off emissions inventories -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Because file I/O impacts GCHP performance it is a good idea to turn off file read of emissions that you do not need. -You can turn individual emissions inventories on or off the same way you would in GEOS-Chem Classic, by setting the inventories to true or false at the top of configuration file :file:`HEMCO_Config.rc`. -All emissions that are turned off in this way will be ignored when GCHP uses :file:`ExtData.rc` to read files, thereby speeding up the model. - -For emissions that do not have an on/off toggle at the top of the file, you can prevent GCHP from reading them by commenting them out in :file:`HEMCO_Config.rc`. -No updates to :file:`ExtData.rc` would be necessary. -If you alternatively comment out the emissions in :file:`ExtData.rc` but not :file:`HEMCO_Config.rc` then GCHP will fail with an error when looking for the file information. - -Another option to skip file read for certain files is to replace the file path in :file:`ExtData.rc` with :literal:`/dev/null`. -However, if you want to turn these inputs back on at a later time you should preserve the original path by commenting out the original line. +--------------------------------- + +Because file I/O impacts GCHP performance it is a good idea to turn +off file read of emissions that you do not need. You can turn +individual emissions inventories on or off the same way you would in +GEOS-Chem Classic, by setting the inventories to true or false at the +top of configuration file :file:`HEMCO_Config.rc`. All emissions that +are turned off in this way will be ignored when GCHP uses +:file:`ExtData.rc` to read files, thereby speeding up the model. + +For emissions that do not have an on/off toggle at the top of the +file, you can prevent GCHP from reading them by commenting them out in +:file:`HEMCO_Config.rc`. No updates to :file:`ExtData.rc` would be +necessary. If you alternatively comment out the emissions in +:file:`ExtData.rc` but not :file:`HEMCO_Config.rc` then GCHP will fail +with an error when looking for the file information. + +Another option to skip file read for certain files is to replace the +file path in :file:`ExtData.rc` with :literal:`/dev/null`. However, +if you want to turn these inputs back on at a later time you should +preserve the original path by commenting out the original line. Change input meteorology -^^^^^^^^^^^^^^^^^^^^^^^^ - -Input meteorology source and grid resolution are set in config file :file:`ExtData.rc` during run directory creation. You will be prompted to choose between MERRA2 and GEOS-FP, and grid resolution is automatically set to the native grid lat-lon resolution. If you would like to change the meteorology inputs, for example using a different grid resolution, then you would need to change the met-field entries in run directory file :file:`ExtData.rc` after creating a run directory. Simply open the file, search for the meteorology section, and edit file paths as needed. Please note that while MAPL will automatically regrid met-fields to the run resolution you specify in :file:`setCommonRunSettings.sh`, you will achieve best performance using native resolution inputs. +------------------------ + +Input meteorology source and grid resolution are set in config file +:file:`ExtData.rc` during run directory creation. You will be prompted +to choose between MERRA2 and GEOS-FP, and grid resolution is +automatically set to the native grid lat-lon resolution. If you +would like to change the meteorology inputs, for example using a +different grid resolution, then you would need to change the +met-field entries in run directory file :file:`ExtData.rc` after +creating a run directory. Simply open the file, search for the +meteorology section, and edit file paths as needed. Please note +that while MAPL will automatically regrid met-fields to the run +resolution you specify in :file:`setCommonRunSettings.sh`, you +will achieve best performance using native resolution inputs. Add new emissions files -^^^^^^^^^^^^^^^^^^^^^^^ - -There are two steps for adding new emissions inventories to GCHP. They are (1) add the inventory information to :file:`HEMCO_Config.rc`, and (2) add the inventory information to :file:`ExtData.rc`. - -To add inventory information to :file:`HEMCO_Config.rc`, follow the same rules as you would for adding a new emission inventory to GEOS-Chem Classic. -Note that not all information in :file:`HEMCO_Config.rc` is used by GCHP. -This is because HEMCO is only used by GCHP to handle emissions after they are read, e.g. scaling and applying hierarchy. -All functions related to HEMCO file read are skipped. -This means that you could put garbage for the file path and units in :file:`HEMCO_Config.rc` without running into problems with GCHP, as long as the syntax is what HEMCO expects. -However, we recommend that you fill in :file:`HEMCO_Config.rc` in the same way you would for GEOS-Chem Classic for consistency and also to avoid potential format check errors. - -To add inventory information to :file:`ExtData.rc` follow the guidelines listed at the top of the file and use existing inventories as examples. -Make sure that you stay consistent with the information you put into :file:`HEMCO_Config.rc`. -You can ignore all entries in :file:`HEMCO_Config.rc` that are copies of another entry (i.e. mostly filled with dashes). Putting these in :file:`ExtData.rc` would result in reading the same variable in the same file twice. +----------------------- + +There are two steps for adding new emissions inventories to GCHP. They +are (1) add the inventory information to :file:`HEMCO_Config.rc`, +and (2) add the inventory information to :file:`ExtData.rc`. + +To add inventory information to :file:`HEMCO_Config.rc`, follow the +same rules as you would for adding a new emission inventory to +GEOS-Chem Classic. Note that not all information in +:file:`HEMCO_Config.rc` is used by GCHP. This is because HEMCO is +only used by GCHP to handle emissions after they are read, +e.g. scaling and applying hierarchy. All functions related to HEMCO +file read are skipped. This means that you could put garbage for the +file path and units in :file:`HEMCO_Config.rc` without running into +problems with GCHP, as long as the syntax is what HEMCO expects. +However, we recommend that you fill in :file:`HEMCO_Config.rc` in the +same way you would for GEOS-Chem Classic for consistency and also to +avoid potential format check errors. + +To add inventory information to :file:`ExtData.rc` follow the +guidelines listed at the top of the file and use existing inventories +as examples. Make sure that you stay consistent with the information +you put into :file:`HEMCO_Config.rc`. You can ignore all entries in +:file:`HEMCO_Config.rc` that are copies of another entry (i.e. mostly +filled with dashes). Putting these in :file:`ExtData.rc` would +result in reading the same variable in the same file twice. A few common errors encountered when adding new input emissions files to GCHP are: -1. Your input file contains integer values. - Beware that the MAPL I/O component in GCHP does not read or write integers. - If your data contains integers then you should reprocess the file to contain floating point values instead. -2. Your data latitude and longitude dimensions are in the wrong order. - Lat must always come before lon in your inputs arrays, a requirement true for both GCHP and GEOS-Chem Classic. -3. Your 3D input data are mapped to the wrong levels in GEOS-Chem (silent error). - If you read in 3D data and assign the resulting import to a GEOS-Chem state variable such as :literal:`State_Chm` or :literal:`State_Met`, then you must flip the vertical axis during the assignment. - See files :file:`Includes_Before_Run.H` and setting :literal:`State_Chm%Species` in :file:`Chem_GridCompMod.F90` for examples. -4. You have a typo in either :file:`HEMCO_Config.rc` or :file:`ExtData.rc`. Errors in :file:`HEMCO_Config.rc` typically result in the model crashing right away. - Errors in :file:`ExtData.rc` typically result in a problem later on during ExtData read. - Always try a short run with all debug prints enabled when first implementing new emissions. - See the debugging section of the user manual for more information. - Another useful strategy is to find config file entries for similar input files and compare them against the entry for your new file. - Directly comparing the file metadata may also lead to insights into the problem. - ---------------------------------------------------------------------------------------------------- - +#. Your input file contains integer values. Beware that the MAPL I/O + component in GCHP does not read or write integers. If your data + contains integers then you should reprocess the file to contain + floating point values instead. |br| + |br| + +#. Your data latitude and longitude dimensions are in the wrong + order. Lat must always come before lon in your inputs arrays, a + requirement true for both GCHP and GEOS-Chem Classic. |br| + |br| + +#. Your 3D input data are mapped to the wrong levels in GEOS-Chem + (silent error). If you read in 3D data and assign the resulting + import to a GEOS-Chem state variable such as :literal:`State_Chm` + or :literal:`State_Met`, then you must flip the vertical axis + during the assignment. See files :file:`Includes_Before_Run.H` + and setting :literal:`State_Chm%Species` in + :file:`Chem_GridCompMod.F90` for examples. |br| + |br| + +#. You have a typo in either :file:`HEMCO_Config.rc` or + :file:`ExtData.rc`. Errors in :file:`HEMCO_Config.rc` typically + result in the model crashing right away. Errors in + :file:`ExtData.rc` typically result in a problem later on during + ExtData read. Always try a short run with all debug prints + enabled when first implementing new emissions. See the debugging + section of the user manual for more information. Another useful + strategy is to find config file entries for similar input files and + compare them against the entry for your new file. Directly + comparing the file metadata may also lead to insights into the + problem. + +======= Outputs -------- +======= Output diagnostics data on a lat-lon grid -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------------------------------------- -See documentation in the :file:`HISTORY.rc` config file for instructions on how to output diagnostic collection on lat-lon grids, as well as the configuration files section at the top of this page for more information on that file. If outputting on a lat-lon grid you may also output regional data instead of global. Make sure that whatever grid you choose is listed under :file:`GRID_LABELS` and is not commented out in :file:`HISTORY.rc`. +See documentation in the :file:`HISTORY.rc` config file for +instructions on how to output diagnostic collection on lat-lon grids, +as well as the configuration files section at the top of this page for +more information on that file. If outputting on a lat-lon grid you may +also output regional data instead of global. Make sure that whatever +grid you choose is listed under :file:`GRID_LABELS` and is not +commented out in :file:`HISTORY.rc`. Output restart files at regular frequency -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------------------------------------- + +The MAPL component in GCHP has the option to output restart files +(also called checkpoint files) prior to run end. These periodic +restart files are output to the main level of the run directory with +filename :literal:`gcchem_internal_checkpoint.YYYYMMDD_HHssz.nc4`. -The MAPL component in GCHP has the option to output restart files (also called checkpoint files) prior to run end. These periodic restart files are output to the main level of the run directory with filename :literal:`gcchem_internal_checkpoint.YYYYMMDD_HHssz.nc4`. +Outputting restart files beyond the end of the run is a good idea if +you plan on doing a long simulation and you are not splitting your run +into multiple jobs. -Outputting restart files beyond the end of the run is a good idea if you plan on doing a long simulation and you are not splitting your run into multiple jobs. -If the run crashes unexpectedly then you can restart mid-run rather than start over from the beginning. -Update settings for checkpoint restart outputs in :file:`setCommonRunSettings.sh` section "MID-RUN CHECKPOINT FILES". -Instructions for configuring restart frequency are included in the file. +If the run crashes unexpectedly then you can restart mid-run rather +than start over from the beginning. Update settings for checkpoint +restart outputs in :file:`setCommonRunSettings.sh` section "MID-RUN +CHECKPOINT FILES". Instructions for configuring restart frequency are +included in the file. Turn on/off diagnostics -^^^^^^^^^^^^^^^^^^^^^^^ +----------------------- -To turn diagnostic collections on or off, comment ("#") collection names in the "COLLECTIONS" list at the top of file :file:`HISTORY.rc`. -Collections cannot be turned on/off from :file:`setCommonRunSettings.sh`. +To turn diagnostic collections on or off, comment ("#") collection +names in the "COLLECTIONS" list at the top of file +:file:`HISTORY.rc`. Collections cannot be turned on/off from +:file:`setCommonRunSettings.sh`. Set diagnostic frequency, duration, and mode -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -All diagnostic collections that come with the run directory have frequency and duration auto-set within :file:`setCommonRunSettings.sh`. -The file contains a list of time-averaged collections and instantaneous collections, and allows setting a frequency and duration to apply to all collections listed for each. Time-avraged collections also have a monthly mean option (see separate section on this page about monthly mean). -To avoid auto-update of a certain collection, remove it from the list in :file:`setCommonRunSettings.sh`, or set "AutUpdate_Diagnostics" to :literal:`OFF`. -See section "DIAGNOSTICS" within :file:`setCommonRunSettings.sh` for examples. +-------------------------------------------- + +All diagnostic collections that come with the run directory have +frequency and duration auto-set within +:file:`setCommonRunSettings.sh`. The file contains a list of +time-averaged collections and instantaneous collections, and +allows setting a frequency and duration to apply to all +collections listed for each. Time-avraged collections also have +a monthly mean option (see separate section on this page about +monthly mean). To avoid auto-update of a certain collection, remove +it from the list in :file:`setCommonRunSettings.sh`, or set +"AutUpdate_Diagnostics" to :literal:`OFF`. See section "DIAGNOSTICS" +within :file:`setCommonRunSettings.sh` for examples. Add a new diagnostics collection -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Adding a new diagnostics collection in GCHP is the same as for GEOS-Chem Classic netcdf diagnostics. -You must add your collection to the collection list in :file:`HISTORY.rc` and then define it further down in the file. -Any 2D or 3D arrays that are stored within GEOS-Chem objects :literal:`State_Met`, :literal:`State_Chm`, or :literal:`State_Diag`, may be included as fields in a collection. -:literal:`State_Met` variables must be preceded by "Met\_", :literal:`State_Chm` variables must be preceded by "Chem\_", and :literal:`State_Diag` variables should not have a prefix. -Collections may have a combination of 2D and 3D variables, but all 3D variables must have the same number of levels. -See the :file:`HISTORY.rc` file for examples. +-------------------------------- + +Adding a new diagnostics collection in GCHP is the same as for +GEOS-Chem Classic netcdf diagnostics. You must add your collection to +the collection list in :file:`HISTORY.rc` and then define it further +down in the file. Any 2D or 3D arrays that are stored within +GEOS-Chem objects :literal:`State_Met`, :literal:`State_Chm`, or +:literal:`State_Diag`, may be included as fields in a collection. +:literal:`State_Met` variables must be preceded by "Met\_", +:literal:`State_Chm` variables must be preceded by "Chem\_", and +:literal:`State_Diag` variables should not have a prefix. Collections +may have a combination of 2D and 3D variables, but all 3D variables +must have the same number of levels. See the :file:`HISTORY.rc` file +for examples. Generate monthly mean diagnostics -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------------- -You can toggle monthly mean diagnostics on/off from within :file:`setCommonRunSettings.sh` in the "DIAGNOSTICS" section if you also set auto-update of diagnostics it that file to on. All time-averaged diagnostic collections will then automatically be configured to compute monthly mean. Alternatively, you can edit :file:`HISTORY.rc` directly and set the "monthly" field to value 1 for each collection you wish to output monthly diagnostics for. +You can toggle monthly mean diagnostics on/off from within +:file:`setCommonRunSettings.sh` in the "DIAGNOSTICS" section if you +also set auto-update of diagnostics it that file to on. All +time-averaged diagnostic collections will then automatically be +configured to compute monthly mean. Alternatively, you can edit +:file:`HISTORY.rc` directly and set the "monthly" field to value +1 for each collection you wish to output monthly diagnostics for. Prevent overwriting diagnostic files -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By default all GCHP run directories are configured to allow overwriting diagnostics files present in :file:`OutputDir` over the course a simulation. -You may disable this feature by setting :file:`Allow_Overwrite=.false.` at the top of configuration file :file:`HISTORY.rc`. - +------------------------------------ +By default all GCHP run directories are configured to allow +overwriting diagnostics files present in :file:`OutputDir` over the +course a simulation. You may disable this feature by setting +:file:`Allow_Overwrite=.false.` at the top of configuration file +:file:`HISTORY.rc`. diff --git a/docs/source/user-guide/rundir-init.rst b/docs/source/user-guide/rundir-init.rst index 9bde9935e..c588ff543 100644 --- a/docs/source/user-guide/rundir-init.rst +++ b/docs/source/user-guide/rundir-init.rst @@ -109,6 +109,23 @@ would like to use from the dataset. 3. GEOS-IT (Beta release) >>> +.. 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. + Enter run directory path ------------------------ From 210a48953b239e16716486ea078c902670f7cdd0 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 6 Nov 2024 16:50:06 -0500 Subject: [PATCH 38/41] geos-chem-shared-docs update: Link to dry-run doc from GC Input Data doc docs/source/geos-chem-shared-docs - RTD update: Link to dy-run instructions from GC Input Data doc 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 cd0f4ad1d..14adeb4d8 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit cd0f4ad1dd13648c3fe9bf8bb13c7bf5ef517125 +Subproject commit 14adeb4d8a9cfbdebd688033e4c22dd034ac105b From 9761e0c8eafe67335da97e3eca266a71b92a179d Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 7 Nov 2024 11:27:14 -0500 Subject: [PATCH 39/41] 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/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO | 2 +- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO b/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO index a3d0c9a28..e9d951fd7 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO +++ b/src/GCHP_GridComp/GEOSChem_GridComp/HEMCO/HEMCO @@ -1 +1 @@ -Subproject commit a3d0c9a280672ac1c40e3f322651f23b8196fa4c +Subproject commit e9d951fd702a82d76ba2a73653b74e7b1eae8e4c diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 51d306dad..a8bb552d1 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 51d306dade21a6c36e5537224b7c533b5489667c +Subproject commit a8bb552d138b6d1fa684a2fa187e3a9a754caf2e From d929c28fce3f185fe5c5b478e496d14333cb56e6 Mon Sep 17 00:00:00 2001 From: Lizzie Lundgren Date: Fri, 8 Nov 2024 10:39:09 -0500 Subject: [PATCH 40/41] Update changelog, add ExtData docs link, and minor fixes/edits Signed-off-by: Lizzie Lundgren --- CHANGELOG.md | 7 +++++++ docs/source/getting-started/quick-start.rst | 14 +++----------- docs/source/user-guide/compiling.rst | 2 +- docs/source/user-guide/config-files/ExtData_rc.rst | 4 ++-- 4 files changed, 13 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c790d3902..35545124f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,13 @@ This file documents all notable changes to the GCHP wrapper repository starting 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 compiler requirements to specify max GNU version is 12 +- Updated documentation for version 14.5.0 + +### Added +- Added documentation about GEOS convection change affecting meteorology starting June 1, 2020 + ### Fixed - Updated `docs/requirements.txt` to use `jinja2==3.1.4` (fixes a security issue) diff --git a/docs/source/getting-started/quick-start.rst b/docs/source/getting-started/quick-start.rst index 41571c523..9a788267b 100644 --- a/docs/source/getting-started/quick-start.rst +++ b/docs/source/getting-started/quick-start.rst @@ -73,17 +73,9 @@ the prompts: 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. + transport. If you plan to do simulations across this boundary + consider using MERRA2 instead. For more information see + `GEOS-Chem GitHub issue #1409`_. ======================= 3. Configure your build diff --git a/docs/source/user-guide/compiling.rst b/docs/source/user-guide/compiling.rst index 242ba028e..2204bd649 100644 --- a/docs/source/user-guide/compiling.rst +++ b/docs/source/user-guide/compiling.rst @@ -185,7 +185,7 @@ useful information for troubleshooting. :literal:`CMAKE_PREFIX_PATH` variable. For example, if you got an error saying "Could not find ESMF", and - ESMF is installedto :file:`/software/ESMF`, you would do + ESMF is installed to :file:`/software/ESMF`, you would do .. code-block:: console diff --git a/docs/source/user-guide/config-files/ExtData_rc.rst b/docs/source/user-guide/config-files/ExtData_rc.rst index 2afc82b3c..bf7543809 100644 --- a/docs/source/user-guide/config-files/ExtData_rc.rst +++ b/docs/source/user-guide/config-files/ExtData_rc.rst @@ -12,8 +12,8 @@ ExtData.rc for GCHP. Explanatory information about the file is located at the top of the configuration file in all run directories. The file format is the same as that used in the GEOS model, and GMAO/NASA documentation -for it can be found at the ExtData component page on the GEOS-5 -wiki. Note that this file will be retired in GCHP v15.0 when MAPL +for it can be found at the 'ExtData component page on the GEOS-5 +wiki `_. Note that this file will be retired in GCHP v15.0 when MAPL version 3 is integrated into GCHP. It will be replaced with a YAML format file with a simplified and easier to understand interface. From 103ebc60b21c1c9d6fef5cb20854388903c2961a Mon Sep 17 00:00:00 2001 From: Lizzie Lundgren Date: Fri, 8 Nov 2024 10:45:43 -0500 Subject: [PATCH 41/41] Fix typos in links Signed-off-by: Lizzie Lundgren --- docs/source/getting-started/quick-start.rst | 2 +- docs/source/user-guide/config-files/ExtData_rc.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/getting-started/quick-start.rst b/docs/source/getting-started/quick-start.rst index 9a788267b..b750cbc2d 100644 --- a/docs/source/getting-started/quick-start.rst +++ b/docs/source/getting-started/quick-start.rst @@ -75,7 +75,7 @@ the prompts: files starting June 1, 2020, specifically enhanced vertical transport. If you plan to do simulations across this boundary consider using MERRA2 instead. For more information see - `GEOS-Chem GitHub issue #1409`_. + `GEOS-Chem GitHub issue #1409 `__. ======================= 3. Configure your build diff --git a/docs/source/user-guide/config-files/ExtData_rc.rst b/docs/source/user-guide/config-files/ExtData_rc.rst index bf7543809..5ad06b5cc 100644 --- a/docs/source/user-guide/config-files/ExtData_rc.rst +++ b/docs/source/user-guide/config-files/ExtData_rc.rst @@ -12,8 +12,8 @@ ExtData.rc for GCHP. Explanatory information about the file is located at the top of the configuration file in all run directories. The file format is the same as that used in the GEOS model, and GMAO/NASA documentation -for it can be found at the 'ExtData component page on the GEOS-5 -wiki `_. Note that this file will be retired in GCHP v15.0 when MAPL +for it can be found at the `ExtData component page on the GEOS-5 +wiki `__. Note that this file will be retired in GCHP v15.0 when MAPL version 3 is integrated into GCHP. It will be replaced with a YAML format file with a simplified and easier to understand interface.