diff --git a/.ci-pipelines/build-matrix.yml b/.ci-pipelines/build-matrix.yml index b4e6104..9015c5e 100644 --- a/.ci-pipelines/build-matrix.yml +++ b/.ci-pipelines/build-matrix.yml @@ -46,7 +46,7 @@ container: $[ variables['containerImage'] ] # Try building GEOS-Chem (this is run for each "matrix" entry above) steps: - checkout: self - submodules: true + submodules: recursive - script: | . /opt/spack/share/spack/setup-env.sh export CC=gcc diff --git a/.ci-pipelines/quick-build.yml b/.ci-pipelines/quick-build.yml index 8adc7c3..cb62f66 100644 --- a/.ci-pipelines/quick-build.yml +++ b/.ci-pipelines/quick-build.yml @@ -31,7 +31,7 @@ container: geoschem/buildmatrix:netcdf-ubuntu # Try building GEOS-Chem steps: - checkout: self - submodules: true + submodules: recursive - script: | . /opt/spack/share/spack/setup-env.sh export CC=gcc diff --git a/.github/workflows/cloud-benchmarking-workflow.yml b/.github/workflows/cloud-benchmarking-workflow.yml index f658a61..932d6b9 100644 --- a/.github/workflows/cloud-benchmarking-workflow.yml +++ b/.github/workflows/cloud-benchmarking-workflow.yml @@ -33,6 +33,7 @@ jobs: - uses: actions/checkout@v3 with: fetch-depth: 0 + persist-credentials: false - name: Set Initial Variables # By default we use 1Hr benchmarks run: | @@ -43,8 +44,8 @@ jobs: # conditionally overwrite variables if a tag was the triggering event - name: Reset Initial Variables for pull request run: | - echo "GITHUB_SHA_SHORT=`echo ${{ github.event.pull_request.head.sha }} | cut -c1-7`" >> $GITHUB_ENV - echo "COMMIT_NAME=`echo ${{ github.event.pull_request.head.sha }} | cut -c1-7`" >> $GITHUB_ENV + echo "GITHUB_SHA_SHORT=${{ github.event.pull_request.head.sha | substr(0, 7) }}" >> $GITHUB_ENV + echo "COMMIT_NAME=${{ github.event.pull_request.head.sha | substr(0, 7) }}" >> $GITHUB_ENV if: github.event_name == 'pull_request' - name: Reset Variables For Tags # We do a 1Month benchmark for tags diff --git a/.github/workflows/gcclassic-compile-tests.yml b/.github/workflows/gcclassic-compile-tests.yml index 0c0a552..77940a3 100644 --- a/.github/workflows/gcclassic-compile-tests.yml +++ b/.github/workflows/gcclassic-compile-tests.yml @@ -19,6 +19,8 @@ jobs: steps: - name: Checkout code + with: + persist-credentials: false uses: actions/checkout@v4 - name: Install dependencies diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 0000000..80d2d43 --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,58 @@ +# Workflow to run linting checks on source +name: Lint + +# Controls when the workflow will run +on: + # Triggers the workflow on pushes to the "main" branch, i.e., PR merges + push: + branches: [ "main" ] + + # Triggers the workflow on pushes to open pull requests with code changes + pull_request: + paths: + - '.github/workflows/*.yml' + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Cancel jobs running if new commits are pushed +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +# Workflow run - one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "lint" + lint: + # The type of runner that the job will run on + runs-on: ubuntu-latest + strategy: + fail-fast: false + + # Steps represent a sequence of tasks that will be executed as part of the job + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - name: Checkout code + with: + persist-credentials: false + uses: actions/checkout@v4 + + - name: Install Python + uses: actions/setup-python@v5 + with: + python-version: '3.x' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m venv ci_venv + . ci_venv/bin/activate + pip install zizmor==0.9.2 + + # Apply GitHub Actions linter, zizmor + - name: zizmor + if: always() + run: | + cd ${{ github.workspace }} + . ci_venv/bin/activate + zizmor .github/workflows/*.yml diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index c5b8f3e..eb31154 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -7,7 +7,7 @@ name: Mark stale issues on: schedule: - - cron: '0 0 * * *' # Run every night at midnight + - cron: '0 0 * * *' # Run every night at midnight jobs: stale: @@ -22,7 +22,7 @@ jobs: with: repo-token: ${{ secrets.GITHUB_TOKEN }} stale-issue-label: 'stale' - exempt-issue-labels: ['category: Discussion','category: Feature Request','deferred','help needed: Open Research Problem','help needed: Request Input from Community','never stale','TODO: Documentation'] + exempt-issue-labels: 'category: Discussion,category: Feature Request,deferred,help needed: Open Research Problem,help needed: Request Input from Community,never stale,TODO: Documentation' days-before-issue-stale: 30 days-before-issue-close: 7 stale-issue-message: 'This issue has been automatically marked as stale because it has not had recent activity. If there are no updates within 7 days it will be closed. You can add the "never stale" tag to prevent the issue from closing this issue.' diff --git a/CHANGELOG.md b/CHANGELOG.md index 07725d7..1f9a337 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,57 @@ This file documents all notable changes to the GEOS-Chem Classic wrapper reposit - src/HEMCO/CHANGELOG.md - src/Cloud-J/CHANGELOG.md -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). +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). + +## [14.5.3] - 2025-03-05 +### Added +- Updated RTD docs to state that users wishing not to open AWS account can use AWS CLI commands with `--no-sign-request1` + +### Changed +- Updated GEOS-Chem submodule to 14.5.3 +- Updated HEMCO submodule to 3.10.2 + +### Fixed +- Fixed error with the `rubric` section in the RTD planeflight documentation + +## [14.5.2] - 2025-02-12 +### Added +- Added clarifying text about which types of data can use altitude coordinates for the Planeflight diagnostic in RTD documentation +- Added warning for users to preprocess ObsPack GLOBALVIEWplus CH4 data files before reading into GEOS-Chem in RTD documentation +- Added text to RTD stating that data download from `s3://geos-chem` is and `s3://gcgrid` is free + +### Changed +- Bumped `jinja2` to version 3.1.5 in `docs/requirements.txt` to fix a security issue +- Changed the build sequence so that the KPP-Standalone is only built when configuring with `-DKPPSA=y` +- Updated RTD documentation to state that older Intel compilers may cause unexpected results; Also updated to recommend GCC 10 and later. +- Updated RTD documentation for fullchem rundir creation, which now asks users if they wish to build KPP-Standalone + +## [14.5.1] - 2025-01-10 +### Added +- Added code to `src/CMakeLists.txt` to build & install the KPP standalone executable when `fullchem` or `custom` mechanisms are selected +- Added ReadTheDocs Supplemental Guide on using the KPP-Standalone Box Model and KPP-Standalone Interface in GEOS-Chem + +### Changed +- Changed `submodules: true` to `submodules: recursive` in `.ci-pipelines/*.yml` files, which will fetch all levels of submodules in Azure CI tests. + +### Fixed +- Fixed logic error in `src/CMakeLists.txt` that attempted to build the KPP standalone for the carbon simulation (see geoschem/GCClassic #78) +- Fixed broken links in ReadTheDocs documentation + +## [14.5.0] - 2024-11-08 +### Changed +- Updated GEOS-Chem to 14.5.0 +- Updated HEMCO to 3.10.0 +- Updated Cloud-J to 8.0.1 +- Updated `docs/source/geos-chem-shared-docs/spack/packages.yaml` to use GCC 12.2.0 compilers +- Updated documentation for version 14.5.0 +- Moved several doc files (not supplemental guides) that are used in both GCClassic and GCHP the to `geos-chem-shared-docs/doc` folder + +### Fixed +- Fixed formatting error in `.github/workflows/stale.yml` that caused the Mark Stale Issues action not to run +- Updated to Python package `jinja2==3.1.4` in `docs/requirements.txt` (fixes a security issue) ## [14.4.3] - 2024-08-13 ### Changed diff --git a/CMakeLists.txt b/CMakeLists.txt index c193cfd..fde0378 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -2,7 +2,7 @@ cmake_minimum_required (VERSION 3.13) project (geos-chem-classic - VERSION 14.4.3 + VERSION 14.5.3 LANGUAGES Fortran ) diff --git a/CMakeScripts/GC-ConfigureClassic.cmake b/CMakeScripts/GC-ConfigureClassic.cmake index eb311c0..f07e81d 100755 --- a/CMakeScripts/GC-ConfigureClassic.cmake +++ b/CMakeScripts/GC-ConfigureClassic.cmake @@ -175,6 +175,14 @@ function(configureGCClassic) ) gc_pretty_print(VARIABLE HCOSA IS_BOOLEAN) + #------------------------------------------------------------------------- + # Build the KPP-Standalone? + #------------------------------------------------------------------------- + set(KPPSA OFF CACHE BOOL + "Switch to build the KPP-Standalone Box Model" + ) + gc_pretty_print(VARIABLE KPPSA IS_BOOLEAN) + #------------------------------------------------------------------------- # Build Luo et al wetdep scheme? # (Currently a research option... turn OFF by default) @@ -208,7 +216,7 @@ function(configureGCClassic) INTERFACE FASTJX ) endif() - + #------------------------------------------------------------------------- # Export the following variables to GEOS-Chem directory's scope #------------------------------------------------------------------------- diff --git a/docs/requirements.txt b/docs/requirements.txt index 60b3987..c0752da 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.5 diff --git a/docs/source/conf.py b/docs/source/conf.py index 1c46044..15ec884 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,7 +23,7 @@ author = 'GEOS-Chem Support Team' # The full version, including alpha/beta/rc tags -release = '14.4.3' +release = '14.5.3' # -- General configuration --------------------------------------------------- diff --git a/docs/source/gcclassic-user-guide/compile-cmake.rst b/docs/source/gcclassic-user-guide/compile-cmake.rst index 16bea85..96a294f 100644 --- a/docs/source/gcclassic-user-guide/compile-cmake.rst +++ b/docs/source/gcclassic-user-guide/compile-cmake.rst @@ -433,17 +433,16 @@ Classic contains code from the various repositories: .. note:: - If you are cloning GEOS-Chem Classic between official releases, you - may the see :code:`Current status` reported like this: + If you are cloning GEOS-Chem Classic between official releases, you + may the see :code:`Current status` reported like this: - .. code-block:: console + .. code-block:: console - X.Y.Z-alpha.n-C-gabcd1234.dirty or + X.Y.Z-alpha.n-C-gabcd1234.dirty or - X.Y.Z.rc.n-C.gabcd1234.dirty + X.Y.Z.rc.n-C.gabcd1234.dirty - We will explain these formats below. |br| - |br| + We will explain these formats below. #. `HEMCO (Harmonized Emissions Component) submodule `_: diff --git a/docs/source/gcclassic-user-guide/config-overview.rst b/docs/source/gcclassic-user-guide/config-overview.rst index 1f4d7e7..320b29c 100644 --- a/docs/source/gcclassic-user-guide/config-overview.rst +++ b/docs/source/gcclassic-user-guide/config-overview.rst @@ -27,9 +27,9 @@ edit most (if not all) of these configuration files: .. toctree:: :maxdepth: 1 - geoschem-config.rst - hemco-config.rst - hemco-diagn.rst + ../geos-chem-shared-docs/doc/geoschem-config.rst + ../geos-chem-shared-docs/doc/hemco-config.rst + ../geos-chem-shared-docs/doc/hemco-diagn.rst history.rst All of the above-mentioned files are included in your :ref:`GEOS-Chem @@ -52,5 +52,5 @@ you'll need to edit these configuration files: .. toctree:: :maxdepth: 1 - spec-db.rst - phot-chem.rst + ../geos-chem-shared-docs/doc/spec-db.rst + ../geos-chem-shared-docs/doc/phot-chem.rst diff --git a/docs/source/gcclassic-user-guide/download-data.rst b/docs/source/gcclassic-user-guide/download-data.rst index 99e745b..df110f7 100644 --- a/docs/source/gcclassic-user-guide/download-data.rst +++ b/docs/source/gcclassic-user-guide/download-data.rst @@ -5,7 +5,7 @@ Download input data ################### In the following chapters, you will learn how to download input data -for your GEOS-Chem simulation: +for your GEOS-Chem simulation. .. note:: @@ -18,6 +18,7 @@ for your GEOS-Chem simulation: .. toctree:: :maxdepth: 2 - input-overview.rst + ../geos-chem-shared-docs/doc/gcid-portal-overview.rst + ../geos-chem-shared-docs/doc/gcid-special-portals.rst restart-files.rst dry-run.rst diff --git a/docs/source/gcclassic-user-guide/dry-run-download.rst b/docs/source/gcclassic-user-guide/dry-run-download.rst index f70fa07..e2f964a 100644 --- a/docs/source/gcclassic-user-guide/dry-run-download.rst +++ b/docs/source/gcclassic-user-guide/dry-run-download.rst @@ -1,3 +1,7 @@ +.. |br| raw:: html + +
+ .. _dry-run-download: ################################# @@ -7,8 +11,8 @@ Download data from dry-run output Once you have successfully executed a GEOS-Chem dry-run, you can use the output from the dry-run (contained in the :file:`log.dryrun` file) to download the data files that GEOS-Chem will need to perform the -corresponding "production" simulation. You may download from one of -several locations, which are described in the following sections. +corresponding "production" simulation. You may download from different +:ref:`data repositories `. .. important:: @@ -40,118 +44,141 @@ several locations, which are described in the following sections. Choose a data portal ==================== -You can :ref:`download input data ` from one of the following -locations: - -.. _dry-run-download-washu: - -The :file:`geoschemdata.wustl.edu` site (aka WashU) ---------------------------------------------------- - -If you are using GEOS-Chem on your institutional computer cluster, we -recommend that you **download data from the WashU (Washington -University in St. Louis) site** (`http://geoschemdata.wustl.edu -`_). This site, which is -maintained by Randall Martin's group at WashU, is the main data site -for GEOS-Chem. - -.. tip:: - - We have also set up a `Globus - `_ endpoint named **GEOS-Chem - data (WashU)** on the WashU site. If you need to - download many years of data, it may be faster to use Globus - (particularly if your home institution supports it). - -.. _dry-run-download-aws: - -The :file:`s3://gcgrid` bucket (aka Amazon) -------------------------------------------- - -If you are running GEOS-Chem Classic on the Amazon Web Services cloud, -you can quickly **download the necessary data for your GEOS-Chem -simulation from the** :file:`s3://gcgrid` **bucket** to the Elastic Block -Storage (EBS) volume attached to your cloud instance. - -Navigate to your GEOS-Chem Classic run directory and type: - -.. code-block:: console - - $ ./download data.py log.dryrun amazon - -This will start the data download process using the ``aws s3 cp`` -commands, which should execute much more quickly than if you were to -download the data from another location. It will also produce a -**log of unique data files**. - -.. note:: - - Downloading from the Amazon Data Portal will NOT incur any - egress charges. This is because the data is covered under the - `AWS Open Data Sponsorship Program - `_. - -.. _dry-run-download-rochester: - -The :file:`atmos.earth.rochester.edu` site (aka Rochester) ----------------------------------------------------------- - -The U. Rochester site (which is maintained by Lee Murray's (GitHub: -:literal:`@ltmurray`) research there) contains the GCAP 2.0 met field -data. This met field data is useful if you wish to perform -simulations stretching back into the preindustrial period, or running -into the future. - -To download data from the Rochester site, type: - -.. code-block:: console - - $ ./download data.py log.dryrun rochester - -.. _dry-run-download-data: +You can :ref:`download input data ` from any of the portals +listed below. + +.. list-table:: GEOS-Chem data portals and access methods + :header-rows: 1 + + * - Portal + - S3 Explorer + - AWS CLI + - HTTP + - Bashdatacatalog + - Globus + * - :ref:`GEOS-Chem Input Data ` |br| + (The main source of GEOS-Chem input data) + - Yes + - Yes + - Yes + - Yes + - Yes + * - :ref:`gcid-special-portals-nested` + - Yes + - Yes + - Yes + - No + - No + * - :ref:`gcid-special-portals-gcap2` + - No + - No + - Yes + - No + - No + +.. _dry-run-download-py: ============================================================== Run the :file:`download_data.py` script on the dryrun log file ============================================================== Navigate to your GEOS-Chem run directory where you executed the dry-run -and type: +and type. + +.. code-block:: console + + $ ./download_data.py log.dryrun PORTAL-NAME + +where: + +- :file:`download_data.py` is the dry-run data download program + (written in Python). It is included in each :ref:`GEOS-Chem Classic + run directory ` that you create. |br| + |br| + +- :file:`log.dryrun` is the log file from your GEOS-Chem dry-run + simulation. |br| + |br| + +- :literal:`PORTAL-NAME` specifies the data portal that you wish + to download from. Allowed values are: + + .. list-table:: Allowed values for the ``PORTAL-NAME`` argument + to ``download_data.py`` + :header-rows: 1 + :align: center + + * - Value + - Downloads from portal + - With this command + - Via this method + * - geoschem+aws + - :ref:`GEOS-Chem Input Data ` + - :command:`aws s3 cp` + - AWS CLI + * - geoschem+http + - :ref:`GEOS-Chem Input Data ` + - :command:`wget` + - HTTP + * - nested+aws + - :ref:`gcid-special-portals-nested` + - :command:`aws s3 cp` + - AWS CLI + * - nested+http + - :ref:`gcid-special-portals-nested` + - :command:`wget` + - HTTP + * - rochester + - :ref:`GCAP 2.0 met data @ Rochester ` + - :command:`wget` + - HTTP + +For example, to download data from the :ref:`GEOS-Chem Input Data +` portal using the AWS CLI download (which is faster than +HTTP download), use this command: .. code-block:: console - $ ./download_data.py log.dryrun washu + $ ./download_data.py log.dryrun geoschem+s3 + +.. note:: -The :file:`download_data.py` Python program is included in the -:ref:`GEOS-Chem run directory ` that you created. This Python -program creates and executes a temporary bash script containing the -appropriate :file:`wget` commands to download the data files. (We have -found that this is the fastest method.) + You must have the `AWS CLI (command-line interface) + `_ software installed on your system + before in order to use the :literal:`geoschem+aws` or + :literal:`nested+aws` options in the table listed above. -The :file:`download_data.py` program will also generate a **log of +The :file:`download_data.py` program will generate a **log of unique data files** (i.e. with all duplicate listings removed), which looks similar to this: .. code-block:: text - !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - !!! LIST OF (UNIQUE) FILES REQUIRED FOR THE SIMULATION - !!! Start Date : 20160701 000000 - !!! End Date : 20160701 010000 - !!! Simulation : standard - !!! Meteorology : GEOSFP - !!! Grid Resolution : 4.0x5.0 - !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - ./GEOSChem.Restart.20160701_0000z.nc4 --> /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/GEOSCHEM_RESTARTS/v2018-11/initial_GEOSChem_rst.4x5_standard.nc - ./HEMCO_Config.rc - ./HEMCO_Diagn.rc - ./HEMCO_restart.201607010000.nc - ./HISTORY.rc - ./input.geos - /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/FJX_j2j.dat - /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/FJX_spec.dat - /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/dust.dat - /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/h2so4.dat - /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/CHEM_INPUTS/FAST_JX/v2019-10/jv_spec_mie.dat + !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + !!! LIST OF (UNIQUE) FILES REQUIRED FOR THE SIMULATION + !!! Start Date : 20190701 000000 + !!! End Date : 20190701 010000 + !!! Simulation : fullchem + !!! Meteorology : MERRA2 + !!! Grid Resolution : 4.0x5.0 + !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + ./HEMCO_Config.rc + ./HEMCO_Config.rc.gmao_metfields + ./HEMCO_Diagn.rc + ./HISTORY.rc + ./Restarts/GEOSChem.Restart.20190701_0000z.nc4 --> /home/ubuntu/ExtData/GEOSCHEM_RESTARTS/GC_14.5.0/GEOSChem.Restart.fullchem.20190701_0000z.nc4 + ./Restarts/HEMCO_restart.201907010000.nc + ./geoschem_config.yml + /path/to/ExtData/CHEM_INPUTS/CLOUD_J/v2024-09/FJX_j2j.dat + /path/to/ExtData/CHEM_INPUTS/CLOUD_J/v2024-09/FJX_scat-aer.dat + /path/to/ExtData/CHEM_INPUTS/CLOUD_J/v2024-09/FJX_scat-cld.dat + /path/to/ExtData/CHEM_INPUTS/CLOUD_J/v2024-09/FJX_scat-ssa.dat + /path/to/ExtData/CHEM_INPUTS/CLOUD_J/v2024-09/FJX_spec.dat + /path/to/ExtData/CHEM_INPUTS/FastJ_201204/fastj.jv_atms_dat.nc + /path/to/ExtData/CHEM_INPUTS/Linoz_200910/Linoz_March2007.dat + /path/to/ExtData/CHEM_INPUTS/Olson_Land_Map_201203/Olson_2001_Drydep_Inputs.nc + /path/to/ExtData/CHEM_INPUTS/UCX_201403/NoonTime/Grid4x5/InitCFC_JN2O_01.dat + ... etc ... This name of this "unique" log file will be the same as the log file @@ -172,13 +199,13 @@ GEOS-Chem run directory: .. code-block:: console - $ ./download_data.py log.dryrun --skip-download + $ ./download_data.py log.dryrun skip-download or for short: .. code-block:: console - $ ./download_data.py log.dryrun --skip + $ ./download_data.py log.dryrun skip This can be useful if you already have the necessary data downloaded to your system but wish to create the log of unique files for documentation diff --git a/docs/source/gcclassic-user-guide/dry-run-run.rst b/docs/source/gcclassic-user-guide/dry-run-run.rst index 4a60732..3a39fa9 100644 --- a/docs/source/gcclassic-user-guide/dry-run-run.rst +++ b/docs/source/gcclassic-user-guide/dry-run-run.rst @@ -6,15 +6,6 @@ Execute a dry-run simulation Follow the steps below to perform a GEOS-Chem Classic dry-run simulation: -.. tip:: - - Also be sure to watch our video tutorial `Using the updated - dry-run capability in GEOS-Chem 13.2.1 and later versions - `_ - at our `GEOS-Chem Youtube Channel - `_, which will guide you - through these steps. - ========================== Complete preliminary setup ========================== @@ -32,9 +23,21 @@ files `: #. :option:`start_date`: Set the start date and time for your simulation. #. :option:`end_date`: Set the end date and time for your simulation. - #. :option:`met_field`: Check if the meteorology setting + #. :option:`met_field`: Check if the meteorology setting (:option:`GEOS-FP`, :option:`MERRA2`, :option:`GCAP2`) is correct for your simulation. + + .. 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. For this reason we recommend + using MERRA-2 instead of GEOS-FP if running a simulation + across June 1, 2020 to avoid unexpected + discontinuities. Additional information about the impact of + the convection change is at `geoschem/geos-chem#1409 + `_. + #. :option:`root_data_dir`: Make sure that the path to :file:`ExtData` is correct. @@ -57,7 +60,7 @@ files `: sets for your simulation have been switched on. .. tip:: - + You can reduce the amount of data that needs to be downloaded for your simulation by turning off inventories that you don't need. diff --git a/docs/source/gcclassic-user-guide/dry-run.rst b/docs/source/gcclassic-user-guide/dry-run.rst index 07bb573..535aae3 100644 --- a/docs/source/gcclassic-user-guide/dry-run.rst +++ b/docs/source/gcclassic-user-guide/dry-run.rst @@ -7,20 +7,20 @@ Download data with a dry-run simulation .. tip:: If you are located at an institution with many other GEOS-Chem - users, then the :ref:`necessary input data ` might - have already been downloaded and stored in a commmon directory on - your system. Ask your sysadmin or IT support staff. - - Please see our :ref:`input-overview` chapter for other ways in - which you can download the necessary input data for GEOS-Chem. - -A "dry-run" is a is a :program:`GEOS-Chem Classic` simulation that -steps through time, but does not perform computations or read data -files from disk. Instead, a dry-run simulation prints a list of all -data files that a regular GEOS-Chem simulation would have read. The -dry-run output also denotes whether each data file was found on disk, -or if it is missing. This output can be fed to a script which will -download the missing data files to your computer system. + users, then the necessary input data might have already been + downloaded and stored in a commmon directory on your system. Ask + your sysadmin or IT support staff. + + Please see our :ref:`data` chapter for other ways in which you can + download the necessary input data for GEOS-Chem. + +A :program:`dry-run` is a is a :program:`GEOS-Chem Classic` simulation +that steps through time, but does not perform computations or read +data files from disk. Instead, a dry-run simulation prints a list of +all data files that a regular GEOS-Chem simulation would have +read. The dry-run output also denotes whether each data file was found +on disk, or if it is missing. This output can be fed to a script which +will download the missing data files to your computer system. You may generate dry-run output for any of the GEOS-Chem Classic simulation types (:option:`fullchem`, :option:`carbon`, diff --git a/docs/source/gcclassic-user-guide/geoschem-config.rst b/docs/source/gcclassic-user-guide/geoschem-config.rst deleted file mode 100644 index 2e3d585..0000000 --- a/docs/source/gcclassic-user-guide/geoschem-config.rst +++ /dev/null @@ -1,1797 +0,0 @@ -.. _cfg-gc-yml: - -################### -geoschem_config.yml -################### - -Starting with GEOS-Chem 14.0.0, the :file:`input.geos` configuration -file (plain text) has been replaced with by the -:file:`geoschem_config.yml` file. This file is in `YAML -`_ format, which is a text-based markup syntax used -for representing dictionary-like data structures. - -.. note:: - - The :file:`geoschem_config.yml` file contains several sections. Only - the sections relevant to a given type of simulation are present. - For example, :option:`fullchem` simulation options (such as aerosol - settings and photolysis settings) are omitted from the - :file:`geoschem_config.yml` file for the :option:`CH4` simulation. - -.. _gc-yml-simulation: - -=================== -Simulation settings -=================== - -.. code-block:: yaml - - #============================================================================ - # Simulation settings - #============================================================================ - simulation: - name: fullchem - start_date: [20190701, 000000] - end_date: [20190801, 000000] - root_data_dir: /path/to/ExtData - met_field: MERRA2 - species_database_file: ./species_database.yml - species_metadata_output_file: OutputDir/geoschem_species_metadata.yml - verbose: - activate: false - on_cores: root # Allowed values: root all - use_gcclassic_timers: false - -The :literal:`simulation` section contains general simulation options: - -.. option:: name - - Specifies the type of GEOS-Chem simulation. Accepted - values are - - .. option:: fullchem - - Full-chemistry simulation. - - .. option:: aerosol - - `Aerosol-only simulation - `_. - - .. option:: carbon - - Coupled carbon gases simulation (CH4-CO-CO2-OCS), implemented as - a KPP mechanism (cf :cite:t:`Bukosa_et_al._2023`). - - You must :ref:`configure your build ` with - :literal:`-DMECH=carbon` in order to use this simulation. - - .. option:: CH4 - - `Methane simulation `_. - - This simulation will eventually be superseded by the - :option:`carbon` simulation. - - .. option:: CO2 - - `Carbon dioxide simulation `_. - - This simulation will eventually be superseded by the - :option:`carbon` simulation. - - .. option:: Hg - - `Mercury simulation `_. - - You must :ref:`configure your build ` with - :literal:`-DMECH=Hg` in order to use this simulation. - - .. option:: POPs - - `Persistent organic pollutants (aka POPs) simulation - `_. - - .. attention:: - - The POPs simulation is currently stale. We look to members - of the GEOS-Chem user community take the lead on updating - this simulation. - - .. option:: tagCH4 - - `Methane simulation - `_ with species - tagged by geographic region or other criteria. - - This simulation will eventually be superseded by the - :option:`carbon` simulation. - - .. option:: tagCO - - Carbon dioxide simulation, with species - tagged by geographic region and other criteria. - - This simulation will eventually be superseded by the - :option:`carbon` simulation. - - .. option:: tagO3 - - `Ozone simulation - `_ (using - specified production and loss rates), - with species tagged by geographical region. - - .. option:: TransportTracers - - `Transport Tracers simulation - `_, with - both radionuclide and passive_species. Useful for evaluating - model transport. - - .. option:: metals - - Trace metals simulation - -.. option:: start_date - - Specifies the starting date and time of the simulation in list - notation :literal:`[YYYYMMDD, hhmmss]`. - -.. option:: end_date - - Specifies the ending date and time of the simulation in list - notation :literal:`[YYYYMMDD, hhmmss]`. - -.. option:: root_data_dir - - Path to the root data directory. All of the data that GEOS-Chem - Classic reads must be located in subfolders of this directory. - -.. option:: met_field - - Name of the meteorology product that will be used to drive - GEOS-Chem Classic. Accepted values are: - - .. option:: MERRA2 - - The `MERRA-2 `_ meteorology - product from NASA/GMAO. MERRA-2 is a stable reanalysis product, - and extends from approximately 1980 to present. - **(Recommended option)** - - .. option:: GEOS-FP - - The `GEOS-FP `_ meteorology - product from NASA/GMAO. GEOS-FP is an operational data product - and, unlike MERRA-2, periodically receives science updates. - - .. option:: GCAP2 - - The GCAP-2 meteorology product, archived from the GISS-2 GCM. - GCAP-2 has hundreds of years of data available, making it useful - for simulations of historical climate. - -.. option:: species_database_file - - Path to the :ref:`GEOS-Chem Species Database ` file. This - is stored in the run directory file :file:`./species_database.yml`. - You should not have to edit this setting. - -.. option:: species_metadata_output_file - - Path to the :file:`geoschem-species-metadata.yml` file. This file - contains echoback of information from :ref:`species_database.yml - `, but only for species that are defined in this - simulation (instead of all possible species). This facilitates - interfacing GEOS-Chem with external models such as CESM. - -.. option:: verbose: - - Menu controlling verbose printout. Starting with GEOS-Chem 14.2.0 - and HEMCO 3.7.0, most informational printouts are now deactivated - by default. You may choose to activate them (e.g. for debugging - and/or testing) with the options below: - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - printing extra informational printout to the screen and/or log - file. - - .. option:: on_cores: - - Specify on which computational cores informational printout - should be done. - - .. option:: root - - Print extra informational output only on the root core. Use this - setting for GEOS-Chem Classic. - - .. option:: all - - Print extra informational output on all cores. Consider - using this when using GEOS-Chem as GCHP, or in MPI-based - external models (NASA GEOS, CESM, etc.). - -.. option:: use_gcclassic_timers - - Activates (:literal:`true`) or deactivates (:literal:`false`) - the GEOS-Chem Classic timers. If activated, information about how - long each component of GEOS-Chem took to execute will be printed to - the screen and/or :ref:`GEOS-Chem log file - `. The same information will also be written - in JSON format to a file named :ref:`gcclassic_timers.json - `. - - You can set this option to :literal:`false` unless you are running - benchmark or timing simulations. - -.. _cfg-gc-yml-grid: - -============= -Grid settings -============= - -.. code-block:: YAML - - #============================================================================ - # Grid settings - #============================================================================ - grid: - resolution: 4.0x5.0 - number_of_levels: 72 - longitude: - range: [-180.0, 180.0] - center_at_180: true - latitude: - range: [-90.0, 90.0] - half_size_polar_boxes: true - nested_grid_simulation: - activate: true - buffer_zone_NSEW: [0, 0, 0, 0] - -The :literal:`grid` section contains settings that define the grid used -by GEOS-Chem Classic: - -.. option:: resolution - - Specifies the horizontal resolution of the grid. Accepted values are: - - .. option:: 4.0x5.0 - - The global :math:`4^{\circ}{\times}5^{\circ}` GEOS-Chem Classic - grid. - - .. option:: 2.0x2.5 - - The global :math:`2.0^{\circ}{\times}2.5^{\circ}` GEOS-Chem Classic - grid. - - .. option:: 0.5x0.625 - - The global :math:`0.5^{\circ}{\times}0.625^{\circ}` GEOS-Chem Classic - grid (:option:`MERRA2` only). Can be used for global or nested - simulations. - - .. option:: 0.5x0.625 - - The global :math:`0.25^{\circ}{\times}0.3125^{\circ}` GEOS-Chem - Classic grid (:option:`GEOS-FP` and :option:`MERRA2`). Can be - used for global or nested simulations. - -.. option:: number_of_levels - - Number of vertical levels to use in the simulation. Accepted - values are: - - .. option:: 72 - - Use 72 vertical levels. This is the native vertical resolution - of :option:`MERRA2` and :option:`GEOS-FP`. - - .. option:: 47 - - Use 47 vertical levels (for :option:`MERRA2` and :option:`GEOS-FP`). - - .. option:: 40 - - Use 40 vertical levels (for :option:`GCAP2`). - -.. option:: longitude - - Settings that define the longitude dimension of the grid. There are - two sub-options: - - .. option:: range - - The minimum and maximum longitude values (grid box edges), - specified in list format. - - .. option:: center_at_180 - - If :literal:`true`, then westernmost grid boxes are centered - at :math:`-180^{\circ}` longitude (the International Date Line). - This is true for both :option:`MERRA2` and :option:`GEOS-FP`. - - If :literal:`false`, then the westernmost grid boxes have their - westernmost edges at :math:`-180^{\circ}` longitude. This is - true for the :option:`GCAP2` grid. - -.. option:: latitude - - Settings to define the latitude dimension of the grid. There are - two sub-options: - - .. option:: range - - The minimum and maximum latitude values (grid box edges), - specified in list format. - - .. option:: use_halfpolar_boxes - - If :literal:`true`, then the northernmost and southernmost grid - boxes will be :math:`\frac{1}{2}` the extent of other grid boxes. - This is true for both :option:`MERRA2` and :option:`GEOS-FP`. - - If :literal:`false`, then all grid boxes will have the same extent - in latitude. This is true for the :option:`GCAP2` grid. - -.. option:: nested_grid_simulation - - Settings for nested-grid simulations. There are two sub-options: - - .. option:: activate - - If :literal:`true`, this indicates that the simulation will use a - sub-window of the horizontal grid. - - If :literal:`false`, this indicates that the simulation will use - the entire global grid extent. - - .. option:: buffer_zone_NSEW - - Specifies the nested grid latitude offsets (# of grid boxes) in list - format :literal:`[N-offset, S-offset, E-offset, W-offset]`. These - offsets are used to define an inner window region in which - transport is actually done (aka the "transport window"). This - "transport window" is always smaller than the actual size of the - nested grid region in order to properly account for the boundary - conditions. - - - For global simulations, use: :literal:`[0, 0, 0, 0]`. - - For nested-grid simulations, we recommend using: :literal:`[3, 3, 3, 3]`. - -.. _cfg-gc-yml-timesteps: - -================== -Timesteps settings -================== - -.. code-block:: YAML - - #============================================================================ - # Timesteps settings - #============================================================================ - timesteps: - transport_timestep_in_s: 600 - chemistry_timestep_in_s: 1200 - radiation_timestep_in_s: 10800 - -The :literal:`timesteps` section specifies the frequency at which -various GEOS-Chem operations occur: - -.. option:: transport_timestep_in_s - - Specifies the "heartbeat" timestep of GEOS-Chem.. This is - the frequency at which transport, cloud convection, PBL mixing, and - wet deposition will be done. - - - Recommended value for global simulations: :literal:`600` - - Recommended value for nested simluations: :literal:`300` or smaller - -.. option:: chemistry_timestep_in_s - - Specifies the frequency at which chemistry and emissions will be - done. - - - Recommended value for global simulations :literal:`1200` - - Recommended value for nested simulations :literal:`600` or smaller - -.. option:: radiation_timestep_in_s - - Specifies the frequency at which the `RRTMG - `_ radiative - transfer model will be called (valid for :option:`fullchem` - simulations only). - -.. _cfg-gc-yml-operations: - -=================== -Operations settings -=================== - -This section of :file:`geoschem_config.yml` is included for all -simulations. However, some of the options listed below will be omitted for -simulations that do not require them. - -There are several sub-sections under :literal:`operations`: - -.. _cfg-gc-yml-operations-chemistry: - -Chemistry ----------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - chemistry: - activate: true - linear_chemistry_aloft: - activate: true - use_linoz_for_O3: true - active_strat_H2O: - activate: true - use_static_bnd_cond: true - gamma_HO2: 0.2 - autoreduce_solver: - activate: false - use_target_threshold: - activate: true - oh_tuning_factor: 0.00005 - no2_tuning_factor: 0.0001 - use_absolute_threshold: - scale_by_pressure: true - absolute_threshold: 100.0 - keep_halogens_active: false - append_in_internal_timestep: false - - # ... following sub-sections omitted ... - -The :literal:`operations:chemistry` section contains settings for chemistry: - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - chemistry in GEOS-Chem. - -.. option:: linear_chemistry_aloft - - Determines how linearized chemistry will be applied in the - stratosphere and/or mesosphere. (Only valid for :option:`fullchem` - simulations). - - There are two sub-options: - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - linearized stratospheric chemistry in the stratosphere and/or - mesosphere. - - .. option:: use_linoz_for_O3 - - If :literal:`true`, `Linoz stratospheric ozone chemistry - `_ - will be used. - - If :literal:`false`, Synoz (i.e. a synthetic flux of ozone across - the tropopause) will be used instead of Linoz. - -.. option:: active_strat_H2O - - Determines if water vapor as modeled by GEOS-Chem will be - allowed to influence humidity fields. (Only valid for - :option:`fullchem` simulations) - - There are two sub-options: - - .. option:: activate - - Allows (:literal:`true`) or disallows (:literal:`false` the H2O - species in GEOS-Chem to influence specific humidity and - relative humidity. - - .. option:: use_static_bnd_cond - - Allows (:literal:`true`) or diasallows (:literal:`false`) a - static boundary condition. - - **TODO** Clarify this - -.. option:: gamma_HO2 - - Specifies :math:`\gamma`, the uptake coefficient for :math:`HO_2` - heterogeneous chemistry. - - Recommended value: :literal:`0.2`. - -.. option:: autoreduce_solver - - Menu for controlling the adaptive mechanism auto-reduction feature, - which is available in `KPP - 3.0.0. `_ and later - versions. See :cite:t:`Lin_et_al._2023` for details. - - .. option:: activate - - If :literal:`true`, the mechanism will be integrated using the - Rosenbrock method with the adaptive auto-reduction feature. - - If :literal:`false`, the mechanism will be integrated using the - traditional Rosenbrock method. - - Default value: :literal:`false`. - - .. option:: use_target_threshold - - Contains options for defining :math:`\partial` (the partitioning - threshold between "fast" and "slow" species") by considering the - production and loss of key species (OH for daytime, NO2 for - nighttime). - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - using OH and NO2 to determine :math:`\partial`. - - Default value: :literal:`true`. - - .. option:: oh_tuning_factor - - Specifies :math:`{\alpha}_{OH}`, which is used to compute - :math:`\partial`. - - .. option:: no2 tuning factor - - Specifies :math:`{\alpha}_{NO2}`, which is used to compute - :math:`\partial`. - - .. option:: use_pressure_threshold - - Contains options for setting an absolute threshold - :math:`\partial` that may be weighted by pressure. - - .. option:: scale_by_pressure - - Activates (:literal:`true`) or deactivates (:literal:`false`) - using a pressure-dependent method to determine :math:`\partial`. - - .. option:: absolute_threshold - - The absolute partitioning threshold :math:`\partial`. - - If :option:`scale_by_pressure` is :literal:`true,` and - :option:`use_target_threshold:activate` is :literal:`false` , - the value for :math:`\partial` specified here will be scaled - by the ratio :math:`P / P_{sfc}`. where :math:`P` is the grid box - pressure and :math:`P_{sfc}` is the surface pressure for the - column. - - .. option:: keep_halogens_active - - If :literal:`true`, then all halogen species will be considered - "fast". This may be necessary in order to obtain realistic - results for ozone and other important species. - - If :literal:`false`, then halogen species will be determined as - "slow" or "fast" depending on the partitioning threshold - :math:`\partial`. - - Default value: :literal:`true` - - .. option:: append_in_internal_timestep - - If :literal:`true`, any "slow" species that later become "fast" - will be appended to the list of "fast" species. - - If :literal:`false`, any "slow" species that later become - "fast" will NOT be appended to the list of "fast" species. - - Default value: :literal:`false` - -.. _cfg-gc-yml-operations-convection: - -Convection ----------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - # .. preceding sub-sections omitted ... - - convection: - activate: true - - # ... following sub-sections omitted ... - -The :command:`operations:convection` section contains settings for -`cloud convection `_: - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - cloud convection in GEOS-Chem. - -.. _cfg-gc-yml-operations-drydep: - -Dry deposition --------------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - # .. preceding sub-sections omitted ... - - dry_deposition: - activate: true - CO2_effect: - activate: false - CO2_level: 600.0 - reference_CO2_level: 380.0 - diag_alt_above_sfc_in_m: 10 - - # ... following sub-sections omitted ... - -The :literal:`operations:dry_deposition` section contains settings that -for `dry deposition `_: - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - dry deposition. - -.. option:: CO2_effect - - This sub-section contains options for applying the - `simple parameterization for the CO2 effect on stomatal resistance - `_. - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) the CO2 - effect on stomatal resistance in dry deposition. - - Default value: :literal:`false`. - - .. option:: CO2_level - - Specifies the CO2 level (in ppb). - - .. option:: reference_CO2_level - - Specifies the reference CO2 level (in ppb). - -.. option:: diag_alt_above_sfc_in_m: - - Specifies the altitude above the surface (in m) to used with the - `ConcAboveSfc diagnostic collection `_. - -.. _cfg-gc-yml-operations-pblmix: - -PBL mixing ----------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - # .. preceding sub-sections omitted ... - - pbl_mixing: - activate: true - use_non_local_pbl: true - - # ... following sub-sections omitted ... - -The :literal:`operations:pbl_mixing` section contains settings that -for `planetary boundary layer (PBL) mixing -`_: - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - planetary boundary layer mixing in GEOS-Chem Classic. - -.. option:: use_non_local_pbl - - If :literal:`true`, then the `non-local PBL mixing scheme (VDIFF) - `_ will - be used. (Default option) - - If :literal:`false`, then the `full PBL mixing scheme (TURBDAY) - `_ will - be used. - -.. _cfg-gc-yml-operations-photolysis: - -Photolysis ----------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - # .. preceding sub-sections omitted ... - - photolysis: - activate: true - num_levs_with_cloud: 34 - input_directories: - fastjx_input_dir: /path/to/ExtData/CHEM_INPUTS/FAST_JX/v2024-05/ - cloudj_input_dir: /path/to/ExtData/CHEM_INPUTS/CLOUD_J/v2023-05/ - overhead_O3: - use_online_O3_from_model: true - use_column_O3_from_met: true - use_TOMS_SBUV_O3: false - photolyze_nitrate_aerosol: - activate: true - NITs_Jscale: 100.0 - NIT_Jscale: 100.0 - percent_channel_A_HONO: 66.667 - percent_channel_B_NO2: 33.333 - - # ... following sub-sections omitted ... - -The :literal:`operation:photolysis` section contains settings for photolysis. -This section only applies to fullchem, Hg, and aerosol-only simulations. - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - photolysis. - - .. attention:: - - You should always keep photolysis turned on in your - simulations. Disabling photolysis should only be done when - debugging. - -.. option:: num_levs_with_cloud - - Specifies the number of levels that can contain clouds, which is a - required input for the Cloud-J photolysis module. This value is - saved to the :code:`Input_Opt%NLevs_Phot_Cloud` field. - - .. attention:: - - The value of :option:`num_levs_with_cloud` will be set to the - proper value when you create a run directory. Its value depends - on the meteorology that is used to drive your GEOS-Chem - simulation. You should not change this value! - -.. option:: input_directories - - Specifies the location of directories containing photolysis - configuration files. - - .. option:: fastjx_input_dir - - Specifies the path to the legacy FAST_JX configuration files containing - information about species cross sections and quantum yields. - These are used to define several aerosol optical properties - even when FAST-JX is not used. - - Note that FAST-JX is off by default and Cloud-J is used - instead. You can use legacy FAST-JX instead of Cloud-J by - configuring with :literal:`-DFASTJX=y` during build. - - .. option:: cloudj_input_dir - - Specifies the path to the Cloud-J configuration files containing - information about species cross sections and quantum yields. - -.. option:: overhead_O3 - - This section contains settings that control which overhead ozone - sources are used for photolysis - - .. option:: use_online_O3_from_model - - Activates (:literal:`true`) or deactivates (:literal:`false`) using - online O3 from GEOS-Chem in the extinction calculations for photolysis. - - Recommended value: :literal:`true` - - .. option:: use_column_O3_from_met - - Activates (:literal:`true`) or deactivates (:literal:`false`) using - ozone columns (e.g. TO3) from the meteorology fields. - - Recommended value: :literal:`true`. - - .. option:: use_TOMS_SBUV_O3 - - Activates (:literal:`true`) or deactivates (:literal:`false`) using - ozone columns from the TOMS-SBUV archive will be used. - - Recommended value: :literal:`false`. - -.. option:: photolyze_nitrate_aerosol: - - This section contains settings that control options for nitrate - aerosol photolysis. - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - nitrate aerosol photolysis. - - Recommended value: :literal:`true`. - - .. option:: NITs_Jscale - - Scale factor (percent) for JNO3 that photolyzes NITs aerosol. - - .. option:: NIT_Jscale - - Scale factor (percent) for JHNO2 that photolyzes NIT aerosol. - - .. option:: percent_channel_A_HONO - - Fraction of JNITs/JNIT in channel A (HNO2) for NITs photolysis. - - .. option:: percent_channel_B_HO2 - - Fraction of JNITs/JNIT in channel B (NO2) for NITs photolysis. - -.. _cfg-gc-yml-rrtmg: - -RRTMG radiative transfer model ------------------------------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - # .. preceding sub-sections omitted ... - - rrtmg_rad_transfer_model: - activate: false - aod_wavelengths_in_nm: - - 550 - longwave_fluxes: false - shortwave_fluxes: false - clear_sky_flux: false - all_sky_flux: false - fixed_dyn_heating: false - seasonal_fdh: false - read_dyn_heating: false - co2_ppmv: 390.0 - - # .. following sub-sections omitted ... - -The :literal:`operations:rrtmg_rad_transfer_model` section contains -settings for the `RRTMG radiative transfer model -`_: - -This section only applies to :option:`fullchem` simultions. - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) the RRTMG - radiative transfer model. - - Default value: :literal:`false`. - -.. option:: aod_wavelengths_in_nm - - Specify wavelength(s) for the aerosol optical properties in nm - (in `YAML sequence format - `_) - Up to three wavelengths can be selected. The specified wavelengths - are used for the photolysis mechanism (either legacy FAST-JX or - Cloud-J) regardless of whether the RRTMG radiative transfer model is used. - -.. option:: longwave_fluxes - - Activates (:literal:`true`) or deactivates (:literal:`false`) - RRTMG longwave flux calculations. - - Default value: :literal:`false`. - -.. option:: shortwave_fluxes - - Activates (:literal:`true`) or deactivates (:literal:`false`) - RRTMG shortwave calculations. - - Default value: :literal:`false`. - -.. option:: clear_sky_flux - - Activates (:literal:`true`) or deactivates (:literal:`false`) - RRTMG clear-sky flux calculations. - - Default value: :literal:`false`. - -.. option:: all_sky_flux - - Activates (:literal:`true`) or deactivates (:literal:`false`) - RRTMG all-sky flux calculations. - - Default value: :literal:`false`. - -.. option:: fixed_dyn_heating - - Activates (:literal:`true`) or deactivates (:literal:`false`) - fixed dynamic heating (FDH) approximation as described by Forster *et al.* - [`1997 - `_]. - - Default value: :literal:`false`. - -.. option:: seasonal_fdh - - Activates (:literal:`true`) or deactivates (:literal:`false`) - seasonally-evolving fixed dynamic heating (SEFDH) approzimation as - described by Kiehl *et al.* [`1999 - `_]. - - .. attention:: - - This option has not been extensively tested, and is considered - experimental. - - Default value: :literal:`false`. - -.. option:: read_dyn_heating - - Activates (:literal:`true`) or deactivates (:literal:`false`) - reading previously-archived dynamical heating outputs from disk. - - Default value: :literal:`false`. - -.. option:: co2_ppmv - - Specify the value of CO2 [in parts per million by volume] to be - used in radiative forcing calculations. - - Default value: :literal:`390.0`. - - -.. _cfg-gc-yml-transport: - -Transport ---------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - # .. preceding sub-sections omitted ... - - transport: - gcclassic_tpcore: # GEOS-Chem Classic only - activate: true # GEOS-Chem Classic only - fill_negative_values: true # GEOS-Chem Classic only - iord_jord_kord: [3, 3, 7] # GEOS-Chem Classic only - transported_species: - - ACET - - ACTA - - AERI - # ... etc more transported species ... - - # .. following sub-sections omitted ... - -The :literal:`operations:transport` section contains -settings for `species transport -`_: - -.. option:: gcclassic_tpcore - - Contains options that control species transport in GEOS-Chem - Classic with the `TPCORE advection scheme - `_: - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) species - transport in GEOS-Chem Classic. - - Default value: :literal:`true`. - - .. option:: fill_negative_values - - If :literal:`true`, negative species concentrations will be - replaced with zeros. - - If :literal:`false`, no change will be made to species - concentrations. - - Default value: :literal:`true`. - - .. option:: iord_jord_kord - - Specifies advection options (in list format) for TPCORE in the - longitude, latitude, and vertical dimensions. The options are - listed below: - - #. 1st order upstream scheme (use for debugging only) - #. 2nd order van Leer (full monotonicity constraint) - #. Monotonic PPM - #. Semi-monotonic PPM (same as 3, but overshoots are allowed) - #. Positive-definite PPM - #. Un-constrained PPM (use when fields & winds are very smooth) - this option only when the fields and winds are very smooth. - #. Huynh/Van Leer/Lin full monotonicity constraint (KORD only) - - Default (and recommended) value: :literal:`[3, 3, 7]` - -.. option:: transported_species - - A list of species names (in `YAML sequence format - `_) - that will be transported by the TPCORE advection scheme. - -.. _cfg-gc-yml-wetdep: - -Wet deposition --------------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem operations - #============================================================================ - operations: - - # .. preceding sub-sections omitted ... - - wet_deposition: - activate: true - -The :literal:`operations:wet_deposition` section contains settings -for `wet deposition `_. - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - wet deposition in GEOS-Chem Classic. - -.. _gc-yml-aerosols: - -================= -Aerosols settings -================= - -This section of :file:`geoschem_config.yml` is included for -:option:`fullchem` and :option:`aerosol` simulations. - -There are several sub-sections under :literal:`aerosols`: - -.. _cfg-gc-yml-aerosol-carbon: - -Carbon aerosols ---------------- - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem aerosols - #============================================================================ - aerosols: - - carbon: - activate: true - brown_carbon: false - enhance_black_carbon_absorption: - activate: true - hydrophilic: 1.5 - hydrophobic: 1.0 - - # .. following sub-sections omitted ... - -The :literal:`aerosols:carbon` section contains settings for -`carbon aerosols -`_: - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) carbon - aerosols in GEOS-Chem. - - Default value: :literal:`true`. - -.. option:: brown_carbon - - Activates (:literal:`true`) or deactivates (:literal:`false`) brown - carbon aerosols in GEOS-Chem. - - Default value: :literal:`false`. - -.. option:: enhance_black_carbon_absorption - - Options for enhancing the absorption of black carbon aerosols - due to external coating. - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) black - carbon absorption enhancement. - - Default value: :literal:`true`. - - .. option:: hydrophilic - - Absorption enhancement factor for hydrophilic black carbon - aerosol (species name **BCPI**). - - Default value: :literal:`1.5` - - .. option:: hydrophobic - - Absorption enhancement factor for hydrophilic black carbon - aerosol (species name **BCPO**). - - Default value: :literal:`1.0` - -.. _cfg-gc-yml-aerosols-soa: - -Complex SOA ------------ -The :code:`aerosols:complex_SOA` section contains settings for -`the complex SOA scheme used in GEOS-Chem -`_. - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem aerosols - #============================================================================ - aerosols: - - # ... preceding sub-sections omitted ... - - complex_SOA: - activate: true - semivolatile_POA: false - - # ... following sub-sections omitted ... - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - complex SOA scheme. - - Default value: - - - :literal:`true` for the :option:`fullchem` benchmark simulation - - :literal:`false` for all other :option:`fullchem` simulations - -.. option:: semivolatile_POA - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - semi-volatile primary organic aerosol (POA) option. - - Default value: :literal:`false` - -.. _gc-yml-aerosols-dust: - -Mineral dust aerosols ---------------------- -The :literal:`aerosols:dust` section contains settings for -`mineral dust aerosols -`_. - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem aerosols - #============================================================================ - aerosols: - - # ... preceding sub-sections omitted ... - - dust: - activate: true - acid_uptake_on_dust: false - - # ... following sub-sections omitted ... - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) mineral - dust aerosols in GEOS-Chem. - - Default value: :literal:`true` - -.. option:: acid_uptake_on_dust - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - `acid uptake on dust option - `_, - which includes 12 additional species. - - Default value: :literal:`false` - -.. _cfg-gc-yml-aerosols-seasalt: - -Sea salt aerosols ------------------ -The :literal:`aerosols:sea_salt` section contains settings for `sea salt -aerosols -`_: - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem aerosols - #============================================================================ - aerosols: - - # ... preceding sub-sections omitted ... - - sea_salt: - activate: true - SALA_radius_bin_in_um: [0.01, 0.5] - SALC_radius_bin_in_um: [0.5, 8.0] - marine_organic_aerosols: false - - # ... following sub-sections omitted ... - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) sea salt - aerosols. - - Default value: :literal:`true` - -.. option:: SALA_radius_bin_in_um - - Specifies the upper and lower boundaries (in nm) for - accumulation-mode sea salt aerosol (aka **SALA**). - - Default value: :literal:`0.01 nm - 0.5 nm` - -.. option:: SALC_radius_bin_in_um - - Specifies the upper and lower boundaries (in nm) for - coarse-mode sea salt aerosol (aka **SALC**). - - Default value: :literal:`0.5 nm - 8.0 nm` - -.. option:: marine_organic_aerosols - - Activates (:literal:`true`) or deactivates (:literal:`false`) - `emission of marine primary organic aerosols - `_. - This option includes two extra species (**MOPO** and **MOPI**). - - Default value: :literal:`false` - -.. _cfg-gc-yml-aerosols-strat: - -Stratospheric aerosols ----------------------- -The :literal:`aerosols:sulfate` section contains settings for -stratopsheric aerosols. - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem aerosols - #============================================================================ - aerosols: - - # ... preceding sub-sections omitted ... - - stratosphere: - settle_strat_aerosol: true - polar_strat_clouds: - activate: true - het_chem: true - allow_homogeneous_NAT: false - NAT_supercooling_req_in_K: 3.0 - supersat_factor_req_for_ice_nucl: 1.2 - calc_strat_aod: true - - # ... following sub-sections omitted ... - - -.. option:: settle_strat_aerosol - - Activates (:literal:`true`) or deactivates (:literal:`false`) - gravitational settling of stratospheric solid particulate aerosols - (SPA, trapezoidal scheme) and stratospheric liquid aerosols (SLA, - corrected Stokes' Law). - - Default value: :literal:`true` - -.. option:: polar_strat_clouds - - Contains settings for how aerosols are handled in polar - stratospheric clouds (PSC): - - .. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) - formation of polar stratospheric clouds. - - Default value: :literal:`true` - - .. option:: het_chem - - Activates (:literal:`true`) or deactivates (:literal:`false`) - heterogeneous chemistry within polar stratospheric clouds. - - Default value: :literal:`true` - -.. option:: allow_homogeneous_NAT - - Activates (:literal:`true`) or deactivates (:literal:`false`) - heterogeneous formation of NAT from freezing of HNO3. - - Default value: :literal:`false` - -.. option:: NAT_supercooling_req_in_K - - Specifies the cooling (in K) required for homogeneous NAT nucleation. - - Default value: :literal:`3.0` - -.. option:: supersat_factor_req_for_ice_nucl - - Specifies the supersaturation factor required for ice nucleation. - - Recommended values: :literal:`1.2` for coarse grids; :literal:`1.5` for - fine grids. - -.. option:: calc_strat_aod - - Includes (:literal:`true`) or excludes (:literal:`false`) online - stratospheric aerosols in extinction calculations for photolysis. - - Default value: :literal:`true` - -.. _cfg-gc-yml-aerosols-sulfate: - -Sulfate aerosols ----------------- -The :literal:`aerosols:sulfate` section contains settings for `sulfate -aerosols `_: - -.. code-block:: YAML - - #============================================================================ - # Settings for GEOS-Chem aerosols - #============================================================================ - aerosols: - - # ... preceding sub-sections omitted ... - - sulfate: - activate: true - metal_cat_SO2_oxidation: true - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) sulfate aerosols. - - Default value: :literal:`true` - -.. option:: metal_cat_SO2_oxidation - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - `metal catalyzed oxidation of SO2 - `_. - - Default value: :literal:`true` - -.. _cfg-gc-yml-xdiag: - -================= -Extra diagnostics -================= - -The :literal:`extra_diagnostics` section contains settings for GEOS-Chem Classic -diagnostics that are not archived by :ref:`History -` or `HEMCO `_: - -.. _gc-yml-xdiag-obspack: - -Obspack diagnostic ------------------- - -The :literal:`extra_diagnostics:obspack` section contains settings for -the `Obspack diagnostic `_: - -.. code-block:: YAML - - #============================================================================ - # Settings for diagnostics (other than HISTORY and HEMCO) - #============================================================================ - extra_diagnostics: - - obspack: - activate: false - quiet_logfile_output: false - input_file: ./obspack_co2_1_OCO2MIP_2018-11-28.YYYYMMDD.nc - output_file: ./OutputDir/GEOSChem.ObsPack.YYYYMMDD_hhmmz.nc4 - output_species: - - CO - - 'NO' - - O3 - - # ... following sub-sections omitted ... - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) ObsPack - diagnostic output. - - Default value: :literal:`true` - -.. option:: quiet_logfile_output - - Deactivates (:literal:`true`) or activates (:literal:`false`) printing - informational output to :literal:`stdout` (i.e. the screen or log file). - - Default value: :literal:`false` - -.. option:: input_file - - Specifies the path to an ObsPack data file (in netCDF format). - -.. option:: output_file - - Specifies the path to the ObsPack diagnostic output file. This - will be a file that contains data at the same locations as - specified in :option:`input_file`. - -.. option:: output_species - - A list of GEOS-Chem species (as a YAML sequence) to archive to the - output file. - -.. _gc-yml-xdiag-plane: - -Planeflight diagnostic ------------------------ -The :literal:`extra_diagnostics:planeflight` section contains settings for -the `GEOS-Chem planeflight diagnostic -`_: - -.. code-block:: YAML - - #============================================================================ - # Settings for diagnostics (other than HISTORY and HEMCO) - #============================================================================ - extra_diagnostics: - - # ... preceding sub-sections omitted ... - - planeflight: - activate: false - flight_track_file: Planeflight.dat.YYYYMMDD - output_file: plane.log.YYYYMMDD - - # ... following sub-sections omitted ... - -.. option:: activate - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - Planeflight diagnostic output. - - Default value: :literal:`false` - -.. option:: flight_track_file - - Specifies the path to a flight track file. This file contains - the coordinates of the plane as a function of time, as well as the - requested quantities to archive. - -.. option:: output_file - - Specifies the path to the Planeflight output file. Requested - quantities will be archived from GEOS-Chem along the flight track - specified in :option:`flight_track_file`. - -.. _cfg-gc-yml-hg: - -===================== -Hg simulation options -===================== - -This section of :file:`geoschem_config.yml` is included for -the `mercury (Hg) simulation `_: - -.. _cfg-gc-yml-hg-src: - -Hg sources ----------- - -The :literal:`Hg_simulation_options:sources` section contains settings -for various mercury sources. - -.. code-block:: YAML - - #============================================================================ - # Settings specific to the Hg simulation - #============================================================================ - Hg_simulation_options: - - sources: - use_dynamic_ocean_Hg: false - use_preindustrial_Hg: false - use_arctic_river_Hg: true - - # ... following sub-sections omitted ... - -.. option:: use_dynamic_ocean_Hg - - Activates (:literal:`true`) or deactivates (:literal:`false`) the online - slab ocean mercury model. - - Default value: :literal:`false` - -.. option:: use_preindustrial_Hg - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - preindustrial mercury simulation. This will turn off all - anthropogenic emissions. - - Default value: :literal:`false` - -.. option:: use_arctic_river_Hg - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - source of mercury from arctic rivers. - - Default value: :literal:`true` - -.. _cfg-gc-yml-hg-chem: - -Hg chemistry ------------- - -The :literal:`Hg_simulation_options:chemistry` section contains settings -for mercury chemistry: - -.. code-block:: YAML - - #============================================================================ - # Settings specific to the Hg simulation - #============================================================================ - Hg_simulation_options: - - # ... preceding sub-sections omitted ... - - chemistry: - tie_HgIIaq_reduction_to_UVB: true - - # ... following sub-sections omitted ... - -.. option:: tie_HgIIaq_reduction_to_UVB - - Activates (:literal:`true`) or deactivates (:literal:`false`) linking the - reduction of aqueous oxidized mercury to UVB radiation. - A lifetime of -1 seconds indicates the species has an infinite lifetime. - - Default value: :literal:`true` - -.. _cfg-gc-yml-carbon: - -========================================= -Options for simulations with carbon gases -========================================= - -These sections of :file:`geoschem_config.yml` are included for -simulations with carbon gases (:option:`carbon`, :option:`CH4`, -:option:`CO2`, :option:`tagCO`, :option:`tagCH4`). - -.. _gc-yml-ch4_obsopt: - -CH4 observational operators ----------------------------- - -The :literal:`CH4_simulation_options:use_observational_operators` section -contains options for using satellite observational operators for CH4: - -.. code-block:: YAML - - #============================================================================ - # Settings specific to the CH4 simulation / Integrated Methane Inversion - #============================================================================ - CH4_simulation_options: - - use_observational_operators: - AIRS: false - GOSAT: false - TCCON: false - - # ... following sub-sections omitted ... - -.. option:: AIRS - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - AIRS observational operator. - - Default value: :literal:`false` - -.. option:: GOSAT - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - GOSAT observational operator. - - Default value: :literal:`false` - -.. option:: TCCON - - Activates (:literal:`true`) or deactivates (:literal:`false`) the - GOSAT observational operator. - - Default value: :literal:`false` - -.. _gc-yml-ch4_anopt: - -CH4 analytical inversion options ---------------------------------- - -The :literal:`ch4_simulation_options:analytical_inversion` section -contains options for analytical inversions with the `Integrated -Methane Inversion workflow (aka IMI) `_. -The IMI will automatically modify several of these options based on -the inversion parameters that you specify. - -.. code-block:: YAML - - #============================================================================ - # Settings specific to the CH4 simulation / Integrated Methane Inversion - #============================================================================ - CH4_simulation_options: - - # ... preceding sub-sections omitted ... - - analytical_inversion: - perturb_OH_boundary_conditions: false - CH4_boundary_condition_ppb_increase_NSEW: [0.0, 0.0, 0.0, 0.0] - -.. option:: perturb_CH4_boundary_conditions - - Activates (:literal:`true`) or deactivatees (:literal:`false`) - perturbation of CH4 nested-grid boundary conditions in analytical - inversions. - - Default value: :literal:`false` - -.. option:: CH4_boundary_condition_ppb_increase_NSEW - - Specifies the perturbation amount (in ppbv) to apply to the north, - south, east and west CH4 nested-grid boundary conditions. Used in - conjunction with the :option:`perturb_CH4_boundary_conditions` - option. - - Default value: :literal:`[0.0, 0.0, 0.0, 0.0]` (no perturbation) - -.. _cfg-gc-yml-co2: - -CO2 Sources ------------ - -The :literal:`CO2_simulation_options:sources` section contains toggles -for activating sources of :math:`CO_2`: - -.. code-block:: YAML - - #============================================================================ - # Settings specific to the CO2 simulation - #============================================================================ - CO2_simulation_options: - - sources: - 3D_chemical_oxidation_source: true - - # ... following sub-sections omitted ... - -.. option:: 3D_chemical_oxidation_source - - Activates (:literal:`true`) or deactivates (:literal:`false`) - :math:`CO_2` production by archived chemical oxidation, as read by - HEMCO. - - Default value: :literal:`true` - -.. _cfg-gc-yml-co2-tagspc: - -CO2 tagged species ------------------- - -The :literal:`CO2_simulation_options:tagged_species` section contains toggles -for activating tagged :math:`CO_2` species: - -.. attention:: - - Tagged :math:`CO_2` tracers should be customized by each user and - the present configuration will not work for resolutions other than - :math:`2.0^{\circ} {\times} 2.5^{\circ}`. - -.. code-block:: YAML - - #============================================================================ - # Settings specific to the CO2 simulation - #============================================================================ - CO2_simulation_options: - - # ... preceding sub-sections omitted ... - - tagged_species: - tag_bio_and_ocean_CO2: false - tag_land_fossil_fuel_CO2: false - - # .. following sub-sections omitted ... - -.. option:: tag_bio_and_ocean_CO2 - - Activates (:literal:`true`) or deactivates (:literal:`false`) tagging of - biosphere regions (28), ocean regions (11), and the rest of the - world (ROW) as specified in :file:`Regions_land.dat` and - :file:`Regions_ocean.dat` files. - -.. option:: tag_land_fossil_fuel_CO2: - - Activates (:literal:`true`) or deactivates (:literal:`false`) tagging of - land and ocean fossil fuel regions. - - -.. _cfg-gc-yml-co: - -CO chemical sources -------------------- - -The :literal:`tagged_CO_simulation_options` section contains settings -for the :option:`carbon` simulation and `tagged CO simulation -`_. - -.. code-block:: YAML - - #============================================================================ - # Settings specific to the tagged CO simulation - #============================================================================ - - tagged_CO_simulation_options: - use_fullchem_PCO_from_CH4: true - use_fullchem_PCO_from_NMVOC: true - -.. option:: use_fullchem_PCO_from_CH4 - - Activates (:literal:`true`) or deactivates (:literal:`false`) applying - the production of :math:`CO` from :math:`CH_4`. This field is - archived from a 1-year or 10-year :option:`fullchem` benchmark - simulation and is read from disk via HEMCO. - - Default value: :literal:`true` - -.. option:: use_fullchem_PCO_from_NMVOC - - Activates (:literal:`true`) or deactivates (:literal:`false`) applying - the production of :math:`CO` from non-methane volatile organic - compounds (VOCs). This field is archived from a 1-year or 10-year - :option:`fullchem` benchmark simulation and is read from disk via - HEMCO. - - Default value: :literal:`true` diff --git a/docs/source/gcclassic-user-guide/hemco-config.rst b/docs/source/gcclassic-user-guide/hemco-config.rst deleted file mode 100644 index f2fea57..0000000 --- a/docs/source/gcclassic-user-guide/hemco-config.rst +++ /dev/null @@ -1,225 +0,0 @@ -.. _cfg-hco-cfg: - -############### -HEMCO_Config.rc -############### - -GEOS-Chem Classic relies on the `Harmonized Emissions Component (aka -HEMCO) `_ for file I/O, regridding, and -computing emissions fluxes. Settings for HEMCO can be updated in the -`HEMCO configuration file -`_, -which is named :file:`HEMCO_Config.rc`. - -The HEMCO online manual at `hemco.readthedocs.io -`_ contains detailed instructions about -the structure and contents of :file:`HEMCO_Config.rc`, so we will not -replicate that content in this Guide. Instead, we will provide a -short summary with links to the relevant documentation. - -.. _cfg-hco-cfg-settings: - -====================== -General HEMCO settings -====================== - -Define general simulation parameters in the `Settings section -`_ -of :file:`HEMCO_Config.rc`. This includes data paths, global -diagnostic options, and verbose output options. - -.. code-block:: kconfig - - ############################################################################### - ### BEGIN SECTION SETTINGS - ############################################################################### - - ROOT: /path/to/hemco/data/dir - METDIR: /path/to/hemco/met/dir - GCAPSCENARIO: not_used - GCAPVERTRES: 47 - Logfile: * - DiagnFile: HEMCO_Diagn.rc - DiagnPrefix: ./OutputDir/HEMCO_diagnostics - DiagnFreq: 00000000 010000 - Wildcard: * - Separator: / - Unit tolerance: 1 - Negative values: 0 - Only unitless scale factors: false - Verbose: false - VerboseOnCores: root # Accepted values: root all - - ### END SECTION SETTINGS ### - -.. _cfg-hco-cfg-extswitches: - -================== -Extension switches -================== - -Turn individual emissions inventories on/off in the `Extension -Switches section -`_ -of :file:`HEMCO_Config.rc`. Emission inventories are -specified as either `Base Emissions -`_ -(i.e. read from files on disk) or `Extensions -`_ -(i.e. computed using meteorological inputs). - -.. code-block:: kconfig - - ############################################################################### - ### BEGIN SECTION EXTENSION SWITCHES - ############################################################################### - # ExtNr ExtName on/off Species Years avail. - 0 Base : on * - # ----- MAIN SWITCHES --------------------------------------------------------- - --> EMISSIONS : true - --> METEOROLOGY : true - --> CHEMISTRY_INPUT : true - # ----- RESTART FIELDS -------------------------------------------------------- - --> GC_RESTART : true - --> HEMCO_RESTART : true - # ----- NESTED GRID FIELDS ---------------------------------------------------- - --> GC_BCs : false - # ----- REGIONAL INVENTORIES -------------------------------------------------- - --> APEI : false # 1989-2014 - --> NEI2016_MONMEAN : false # 2002-2020 - --> DICE_Africa : false # 2013 - # ----- GLOBAL INVENTORIES ---------------------------------------------------- - --> CEDSv2 : true # 1750-2019 - --> CEDS_GBDMAPS : false # 1970-2017 - --> CEDS_GBDMAPS_byFuelType: false # 1970-2017 - - ... etc ... - - # ----------------------------------------------------------------------------- - 100 Custom : off - - 101 SeaFlux : on DMS/ACET/ALD2/MENO3/ETNO3/MOH - 102 ParaNOx : on NO/NO2/O3/HNO3 - --> LUT data format : nc - --> LUT source dir : $ROOT/PARANOX/v2015-02 - 103 LightNOx : on NO - --> CDF table : $ROOT/LIGHTNOX/v2014-07/light_dist.ott2010.dat - 104 SoilNOx : on NO - --> Use fertilizer NOx : true - - ... etc ... - - ### END SECTION EXTENSION SWITCHES ### - -.. _cfg-hco-base: - -============== -Base emissions -============== - -.. note:: - - You do not have to edit this section if you just wish to run - GEOS-Chem Classic with its default emissions configuration. - -Specify how emissions and other data sets will be read from disk in -the `Base Emissions section -`_ -of :file:`HEMCO_Config.rc`. - -.. code-block:: kconfig - - ############################################################################### - ### BEGIN SECTION BASE EMISSIONS - ############################################################################### - - # ExtNrName sourceFile sourceVar sourceTime C/R/E SrcDim SrcUnit Species ScalIDs Cat Hier - - (((EMISSIONS - - #============================================================================== - # --- APEI (Canada) --- - #============================================================================== - (((APEI - 0 APEI_NO $ROOT/APEI/v2016-11/APEI.0.1x0.1.nc NOx 1989-2014/1/1/0 RF xy kg/m2/s NO 25/1002/115 1 30 - 0 APEI_CO $ROOT/APEI/v2016-11/APEI.0.1x0.1.nc CO 1989-2014/1/1/0 RF xy kg/m2/s CO 26/52/1002 1 30 - 0 APEI_SOAP - - - - - - SOAP 26/52/1002/280 1 30 - 0 APEI_SO2 $ROOT/APEI/v2016-11/APEI.0.1x0.1.nc SOx 1989-2014/1/1/0 RF xy kg/m2/s SO2 60/1002 1 30 - 0 APEI_SO4 - - - - - - SO4 60/65/1002 1 30 - 0 APEI_pFe - - - ... etc ... - - ### END SECTION BASE EMISSIONS ### - -.. _cfg-hco-scalefac: - -============= -Scale factors -============= - -Define scale factors for emissions inventories and other data sets in -the `Scale Factors section -`_ -of :file:`HEMCO_Config.rc`. - -.. code-block:: kconfig - - #============================================================================== - # --- Scale factors used for species conversions --- - #============================================================================== - - # Units carbon to species conversions - # Factor = # carbon atoms * MW carbon) / MW species - 40 CtoACET MATH:58.09/(3.0*12.0) - - - xy unitless 1 - 41 CtoALD2 MATH:44.06/(2.0*12.0) - - - xy unitless 1 - 42 CtoALK4 MATH:58.12/(4.3*12.0) - - - xy unitless 1 - - ... etc ... - # VOC speciations - (((RCP_3PD.or.RCP_45.or.RCP_60.or.RCP_85 - 50 KET2MEK 0.25 - - - xy unitless 1 - 51 KET2ACET 0.75 - - - xy unitless 1 - )))RCP_3PD.or.RCP_45.or.RCP_60.or.RCP_85 - - ... etc ... - - ### END SECTION SCALE FACTORS ### - -.. _masks: - -===== -Masks -===== - -Define masks for emissions and other data sets in the `Masks section -`_ -of :file:`HEMCO_Config.rc` - -.. code-block:: kconfig - - ############################################################################### - ### BEGIN SECTION MASKS - ############################################################################### - - # ScalID Name sourceFile sourceVar sourceTime C/R/E SrcDim SrcUnit Oper Lon1/Lat1/Lon2/Lat2 - - (((EMISSIONS - - #============================================================================== - # Country/region masks - #============================================================================== - (((APEI - 1002 CANADA_MASK $ROOT/MASKS/v2018-09/Canada_mask.geos.1x1.nc MASK 2000/1/1/0 C xy 1 1 -141/40/-52/85 - )))APEI - - (((NEI2016_MONMEAN - 1007 CONUS_MASK $ROOT/MASKS/v2018-09/CONUS_Mask.01x01.nc MASK 2000/1/1/0 C xy 1 1 -140/20/-50/60 - )))NEI2016_MONMEAN - - ... etc ... - - )))EMISSIONS - - ### END SECTION MASKS ### - - ### END OF HEMCO INPUT FILE ### diff --git a/docs/source/gcclassic-user-guide/hemco-diagn.rst b/docs/source/gcclassic-user-guide/hemco-diagn.rst deleted file mode 100644 index aff1a92..0000000 --- a/docs/source/gcclassic-user-guide/hemco-diagn.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _cfg-hco-diagn: - -############## -HEMCO_Diagn.rc -############## - -In your run directory, you will find a copy of the `HEMCO diagnostic configuration file -`_ -(named :file:`HEMCO_Diagn.rc`) corresponding to the -:ref:`HEMCO_Config.rc ` file. You will only need to edit -this file if you wish to change the default diagnostic output configuration. - -A snippet of the :file:`HEMCO_Diagn.rc` for the :option:`fullchem` -simulation is shown below: - -.. code-block:: kconfig - - ############################################################################### - ##### ALD2 emissions ##### - ############################################################################### - EmisALD2_Total ALD2 -1 -1 -1 3 kg/m2/s ALD2_emission_flux_from_all_sectors - EmisALD2_Anthro ALD2 0 1 -1 3 kg/m2/s ALD2_emission_flux_from_anthropogenic - EmisALD2_BioBurn ALD2 111 -1 -1 2 kg/m2/s ALD2_emission_flux_from_biomass_burning - EmisALD2_Biogenic ALD2 0 4 -1 2 kg/m2/s ALD2_emission_flux_from_biogenic_sources - EmisALD2_Ocean ALD2 101 -1 -1 2 kg/m2/s ALD2_emission_flux_from_ocean - EmisALD2_PlantDecay ALD2 0 3 -1 2 kg/m2/s ALD2_emission_flux_from_decaying_plants - EmisALD2_Ship ALD2 0 10 -1 2 kg/m2/s ALD2_emission_flux_from_ships - - -Columns: - -#. netCDF variable name for the requested diagnostic quantity -#. Species name -#. Extension number (:literal:`-1` means sum over all extensions) -#. Category (:literal:`-1` means sum over all categories) -#. Hierarchy (:literal:`-1` means sum over all hierarchies) -#. Dimension of data (:literal:`1`: scalar, :literal:`2`: lon-lat, - :literal:`3`: lon-lat-lev) -#. Units -#. Value for the :literal:`long_name` netCDF variable attribute - -The prefix (e.g. :literal:`OutputDir/HEMCO_diagnostics`) for HEMCO diagnostics -output files are specified in the -`Settings section of the HEMCO_Config.rc file -`_. diff --git a/docs/source/gcclassic-user-guide/input-overview.rst b/docs/source/gcclassic-user-guide/input-overview.rst deleted file mode 100644 index 28352f3..0000000 --- a/docs/source/gcclassic-user-guide/input-overview.rst +++ /dev/null @@ -1,228 +0,0 @@ -.. _input-overview: - -################################ -Input data for GEOS-Chem Classic -################################ - -GEOS-Chem Classic reads (via `HEMCO `_) -several data files from disk during a simulation. These can be -grouped into the following categories: - -#. :ref:`init-cond` (aka :ref:`restart-files`) -#. :ref:`chem-inputs` -#. :ref:`emis-inputs` -#. :ref:`met` - -============ -Data portals -============ - -Input data files for GEOS-Chem can be downloaded from one of the -following portals: - -.. option:: WashU - - The primary data portal for GEOS-Chem, - `geoschemdata.wustl.edu `_ - - The WashU data portal may be unavailable at times due to - regularly-scheduled maintenance periods. Please check the - `WashU IT status page `_ for more - information. - -.. option:: Amazon - - GEOS-Chem data on the Amazon cloud, `s3://gcgrid - `_. You can - browse the contents of the data via the - `AWS S3 Explorer `_. - - .. note:: - - Downloading from the Amazon Data Portal will NOT incur any - egress charges. This is because the data is covered under the - `AWS Open Data Sponsorship Program - `_. - -.. option:: Rochester - - Portal for the GCAP 2.0 meteorological data files, - `atmos.earth.rochester.edu - `_ - -.. _init-cond: - -============================= -Initial conditions input data -============================= - -Initial conditions include: - -- Initial species concentrations (aka :ref:`restart-files`) used to - start a GEOS-Chem simulation. - -.. table:: - :align: center - - +--------------------------------------------------+---------------------+ - | Download method | From portals | - +==================================================+=====================+ - | :ref:`Dry run simulation ` | :option:`WashU` | - | | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Run :ref:`bashdatacatalog ` | :option:`WashU` | - | on the :file:`InitialConditions.csv` file [1]_ | | - +--------------------------------------------------+---------------------+ - | Direct data download (:program:`FTP` or | :option:`WashU` | - | :program:`wget`) | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Direct data download | :option:`Amazon` | - | (:program:`AWS S3 Explorer`) [2]_ | | - +--------------------------------------------------+---------------------+ - | Globus, use endpoint **GEOS-Chem data (WashU)** | :option:`WashU` | - +--------------------------------------------------+---------------------+ - -.. rubric:: Notes - -.. [1] We provide :file:`InitialConditions.csv` files (for each - GEOS-Chem version since 13.0.0) at our `input-data-catalogs - `_ Github repository. -.. [2] Direct link: `s3.amazonaws.com/gcgrid/index.html `_ - -.. _chem-inputs: - -==================== -Chemistry input data -==================== - -Chemistry input data includes: - -- Quantum yields and cross sections for photolysis using either ``Cloud-J`` or legacy ``FAST-JX`` -- Climatology data for :program:`Linoz` -- Boundary conditions for :program:`UCX` stratospheric chemistry routines - -.. table:: - :align: center - - +--------------------------------------------------+---------------------+ - | Download method | From portals | - +==================================================+=====================+ - | :ref:`Dry run simulation ` | :option:`WashU` | - | | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Run :ref:`bashdatacatalog ` | :option:`WashU` | - | on the | | - | :file:`ChemistryInputs.csv` [3]_ | | - +--------------------------------------------------+---------------------+ - | Direct data download (:program:`FTP` or | :option:`WashU` | - | :program:`wget`) | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Direct data download | :option:`Amazon` | - | (:program:`AWS S3 Explorer`) [2]_ | | - +--------------------------------------------------+---------------------+ - | Globus, use endpoint **GEOS-Chem data (WashU)** | :option:`WashU` | - +--------------------------------------------------+---------------------+ - -.. rubric:: Notes - -.. [3] We provide :file:`ChemistryInputs.csv` files (for each - GEOS-Chem version since 13.0.0) at our `input-data-catalogs - `_ Github repository. - -.. _emis-inputs: - -==================== -Emissions input data -==================== - -Emissions input data includes the following data: - -- Emissions inventories -- Input data for HEMCO Extensions -- Input data for GEOS-Chem specialty simulations -- Scale factors -- Mask definitions -- Surface boundary conditions -- Leaf area indices -- Land cover map - -.. table:: - :align: center - - +--------------------------------------------------+---------------------+ - | Download method | From portals | - +==================================================+=====================+ - | :ref:`Dry run simulation ` | :option:`WashU` | - | | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Run :ref:`bashdatacatalog ` | :option:`WashU` | - | on the :file:`EmissionsInputs.csv` file [4]_ | | - +--------------------------------------------------+---------------------+ - | Direct data download (:program:`FTP` or | :option:`WashU` | - | :program:`wget`) | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Direct data download | :option:`Amazon` | - | (:program:`AWS S3 Explorer`) [2]_ | | - +--------------------------------------------------+---------------------+ - | Globus, use endpoint **GEOS-Chem data (WashU)** | :option:`WashU` | - +--------------------------------------------------+---------------------+ - -.. rubric:: Notes - -.. [4] We provide :file:`EmissionsInputs.csv` files (for each - GEOS-Chem version since 13.0.0) at our `input-data-catalogs - `_ Github repository. - -.. _met: - -====================== -Meteorology input data -====================== - -:ref:`As described previously `, GEOS-Chem Classic -be driven by the following meteorology products: - -#. `MERRA-2 `_ -#. `GEOS-FP `_ -#. `GCAP 2.0 `_ - -.. attention:: - - We are still evaluating GEOS-Chem with the new NASA GEOS-IT - meterorology product. For the time being, you should use one of - the other meteorology options. - -.. table:: - :align: center - - +--------------------------------------------------+---------------------+ - | Download method | From portals | - +==================================================+=====================+ - | :ref:`Dry run simulation ` | :option:`WashU` | - | | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Run :ref:`bashdatacatalog ` | :option:`WashU` | - | on the :file:`MeteorologyInputs.csv` file [5]_ | | - +--------------------------------------------------+---------------------+ - | Direct data download (:program:`FTP` or | :option:`WashU` | - | :program:`wget`) | :option:`Amazon` | - | | :option:`Rochester` | - +--------------------------------------------------+---------------------+ - | Direct data download | :option:`Amazon` | - | (:program:`AWS S3 Explorer`) [2]_ | | - +--------------------------------------------------+---------------------+ - | Globus, use endpoint **GEOS-Chem data (WashU)** | :option:`WashU` | - +--------------------------------------------------+---------------------+ - -.. rubric:: Notes - -.. [5] We provide :file:`MeteorologyInputs.csv` files (for each - GEOS-Chem version since 13.0.0) at our `input-data-catalogs - `_ Github repository. diff --git a/docs/source/gcclassic-user-guide/obspack.rst b/docs/source/gcclassic-user-guide/obspack.rst index c8274f1..c46417e 100644 --- a/docs/source/gcclassic-user-guide/obspack.rst +++ b/docs/source/gcclassic-user-guide/obspack.rst @@ -11,6 +11,30 @@ measurements). This feature was written by Andy Jacobson of NOAA and Andrew Schuh of Colorado State University and implemented in GEOS-Chem 12.2.0. +.. attention:: + + The GEOS-Chem ObsPack diagnostic was originally developed for use + with the `ObsPack GLOBALVIEWplus CO2 product + `_. The + data files in this product contain a particular netCDF variable + named :literal:`CT_sampling_strategy` that GEOS-Chem uses to + quickly determine the time-averaging window for aggregating + observations. + + We have recently learned that the `ObsPack GLOBALVIEWplus CH4 data + product `_ + currently lacks the :literal:`CT_sampling_strategy` variable, and + thus is incompatible with GEOS-Chem. + + The best workaround for now is to preprocess ObsPack GLOBALVIEWplus + CH4 data files with one of the following Python tools before + attempting to read them into GEOS-Chem: + + - `process_obspack `_ + by James East + - `gcpy_campaigns `_ + by Jessica Haskins + .. _specifying_obspack_diagnostic_options: ===================================== @@ -47,9 +71,9 @@ YYYY/MM/DD date on which you would like to obtain ObsPack diagnostic output from GEOS-Chem. (The ObsPack diagnostic will skip over days on which it cannot find an input file.) -ObsPack input files can be downloaded from NOAA (see -`https://www.esrl.noaa.gov/gmd/ccgg/obspack/ -`_). +ObsPack input files can be downloaded the NOAA website: +`https://gml.noaa.gov/ccgg/obspack/ +`_. .. attention:: diff --git a/docs/source/gcclassic-user-guide/phot-chem.rst b/docs/source/gcclassic-user-guide/phot-chem.rst deleted file mode 100644 index 4e76caa..0000000 --- a/docs/source/gcclassic-user-guide/phot-chem.rst +++ /dev/null @@ -1,100 +0,0 @@ -.. _cfg-phot-chem: - -############################################ -Photolysis and chemistry configuration files -############################################ - -.. note:: - - You won't need to edit these configuration files unless you are - changing the photolysis and/or chemistry mechanisms used in your - GEOS-Chem Classic simulation. - -.. _cfg-phot-chm-phot: - -============================== -Photolysis configuration files -============================== - -Configuration files containing photolysis parameters (such as quantum -yields, cross sections, branching ratios, etc.) may be found in -subdirectories of :file:`ExtData/CHEM_INPUTS/CLOUD-J/` and -:file:`ExtData/CHEM_INPUTS/FAST-JX/`. See the :ref:`cfg-gc-yml` -file for the current file path specifications. - -GEOS-Chem versions 14.3.0 and later use the :program:`Cloud-J` -photolysis scheme by default. However, some aerosol properties -(e.g. relative humidity dependence) are still stored in files located -in the :file:`ExtData/CHEM_INPUTS/FAST_JX` directory tree. - -At present, the mercury (Hg) simulation still uses the legacy -:program:`FAST-JX` photolysis scheme. We look to the GEOS-Chem user -community to take the lead on creating configuration files for -:program:`Cloud-J`. - -.. _cfg-phot-chem-chem: - -====================================== -Chemical mechanism configuration files -====================================== - -GEOS-Chem Classic simulations use source code generated by `The -Kinetic PreProcessor `_. -If you need to update the default chemistry mechanism, you will need -to do the following steps: - -#. Modify the relevant KPP configuration files (described below); -#. Run KPP to generate updated source code for GEOS-Chem Classic; -#. :ref:`Compile GEOS-Chem Classic ` to create a new - executable; -#. Start your GEOS-Chem Classic simulation. - -Chemical mechanism configuration files are located in these folders: - -.. option:: KPP/fullchem - - Contains configuration files for the default "full-chemistry" - mechanism (NOx + Ox + aerosols + Br + Cl + I). - - - :file:`fullchem.kpp`: Main configuration file for the - **fullchem** mechanism. - - - :file:`fullchem.eqn`: List of species and reactions - for the **fullchem** mechanism. - -.. option:: KPP/carbon - - Contains configuration files for the carbon gases mechanism - (CH4-CO2-CO-OCS): - - - :file:`carbon.kpp`: Main configuration file for the **carbon** - mechanism. - - - :file:`carbon.eqn`: List of species and reactions for the **carbon** - mechanism. - -.. option:: KPP/custom - - Contains configuration files that you can edit if you need to - create a custom mechanism. We recommend that you create the - custom in this folder and leave :file:`KPP/fullchem` and - :file:`KPP/Hg` untouched. - - - :file:`custom.kpp`: Copy of :file:`fullchem.kpp` - - - :file:`custom.eqn`: Copy of :file:`fullchem.eqn`. - -.. option:: KPP/Hg - - Contains configuration files for the mercury chemistry mechanism: - - - :file:`Hg.kpp`: Main configuration file for the **Hg** - mechanism. - - - :file:`Hg.eqn`: List of species and reactions for the **Hg** - mechanism. - -Please see the following references for more information about KPP: - -#. The KPP user manual (`kpp.readthedocs.io `_) -#. Supplemental Guide: :ref:`kppguide` diff --git a/docs/source/gcclassic-user-guide/planeflight.rst b/docs/source/gcclassic-user-guide/planeflight.rst index 5d61999..57ac9f4 100644 --- a/docs/source/gcclassic-user-guide/planeflight.rst +++ b/docs/source/gcclassic-user-guide/planeflight.rst @@ -10,7 +10,7 @@ along flight tracks or at the position of ground observations. This can be more efficient in terms of storage than saving out 3-D data files via the :ref:`GEOS-Chem History diagnostics `. -.. attention:: +.. important:: Several diagnostic quantities were disabled when the SMVGEAR chemistry solver was replaced with the FlexChem implementation of @@ -214,34 +214,42 @@ you will specify the points that make up the flight track. .. table:: :align: center - +---------------+-----------------------------------------------+ - | Quantity | Description | - +===============+===============================================+ - | ``POINT`` | A sequential index of flight track points. | - +---------------+-----------------------------------------------+ - | ``TYPE`` | Identifier for the plane (or station) | - +---------------+-----------------------------------------------+ - | ``DD`` | Day of the observation | - +---------------+-----------------------------------------------+ - | ``MM`` | Month of the observation | - +---------------+-----------------------------------------------+ - | ``YYYY`` | Year of the observation | - +---------------+-----------------------------------------------+ - | ``HH`` | Hour of the observation (UTC) | - +---------------+-----------------------------------------------+ - | ``MM`` | Minute of the observation (UTC) | - +---------------+-----------------------------------------------+ - | ``LAT`` | Latitude (deg), range -90 to +90 | - +---------------+-----------------------------------------------+ - | ``LON`` | Longitude (deg), range -180 to +180 | - +---------------+-----------------------------------------------+ - | ``ALT/PRE`` | Altitude [m] or Pressure [hPa] of | - | | the observation | - +---------------+-----------------------------------------------+ - | ``OBS`` | Value of the observation (if known), | - | | used to compare to model output | - +---------------+-----------------------------------------------+ - + +--------------+-----------------------------------------------+ + | Quantity | Description | + +==============+===============================================+ + | ``POINT`` | A sequential index of flight track points. | + +--------------+-----------------------------------------------+ + | ``TYPE`` | Identifier for the plane (or station) | + +--------------+-----------------------------------------------+ + | ``DD`` | Day of the observation | + +--------------+-----------------------------------------------+ + | ``MM`` | Month of the observation | + +--------------+-----------------------------------------------+ + | ``YYYY`` | Year of the observation | + +--------------+-----------------------------------------------+ + | ``HH`` | Hour of the observation (UTC) | + +--------------+-----------------------------------------------+ + | ``MM`` | Minute of the observation (UTC) | + +--------------+-----------------------------------------------+ + | ``LAT`` | Latitude (deg), range -90 to +90 | + +--------------+-----------------------------------------------+ + | ``LON`` | Longitude (deg), range -180 to +180 | + +--------------+-----------------------------------------------+ + | ``ALT/PRE`` | Altitude [m] or Pressure [hPa] of | + | | the observation [#A]_ | + +--------------+-----------------------------------------------+ + | ``OBS`` | Value of the observation (if known), | + | | used to compare to model output | + +--------------+-----------------------------------------------+ + +.. rubric:: Notes + +.. [#A] Altitude is only supported for CCGG or tower data. All other + observations must specify pressure in hPa. This can be + obtained from the "static pressure" field as measured by the + aircraft. See this `code block in planeflight_mod.F90 + `_ + for details. .. important:: diff --git a/docs/source/gcclassic-user-guide/restart-files-gc.rst b/docs/source/gcclassic-user-guide/restart-files-gc.rst index c4e96ee..20a97fe 100644 --- a/docs/source/gcclassic-user-guide/restart-files-gc.rst +++ b/docs/source/gcclassic-user-guide/restart-files-gc.rst @@ -134,8 +134,7 @@ Where can I get a restart file for my simulation? GEOS-Chem Classic :ref:`run directories ` are configured to use sample GEOS-Chem restart files in :program:`netCDF` format. These -files are available for download at the :option:`WashU` and -:option:`Amazon` data portals. +files are available for download at the :ref:`gcid-data` portal. .. tip:: diff --git a/docs/source/gcclassic-user-guide/restart-files-what.rst b/docs/source/gcclassic-user-guide/restart-files-what.rst index 1a845a6..1569345 100644 --- a/docs/source/gcclassic-user-guide/restart-files-what.rst +++ b/docs/source/gcclassic-user-guide/restart-files-what.rst @@ -4,8 +4,9 @@ What is a restart file? ####################### -Restart files contain the initial conditions (cf. :ref:`init-cond`) -for a GEOS-Chem simulation. GEOS-Chem simulations need two restart files. +Restart files contain species concentrations, as well as other +quantities that are needed to initialize GEOS-Chem simulations. +GEOS-Chem simulations use two separate restart files. .. option:: GEOSChem.Restart.YYYYMMDD_hhmmz.nc4 @@ -31,7 +32,7 @@ for a GEOS-Chem simulation. GEOS-Chem simulations need two restart files. **Description:** The :ref:`HEMCO restart file `. HEMCO archives certain quantities (mostly pertaining to soil NOx - and biogenic emissions) in order to facilitate long GEOS-Chem + and biogenic emissions in order to facilitate long GEOS-Chem simulations with several run stages. HEMCO restart files are created in the :option:`Restarts/` diff --git a/docs/source/gcclassic-user-guide/run-checklist.rst b/docs/source/gcclassic-user-guide/run-checklist.rst index 3475d4f..8a9c639 100644 --- a/docs/source/gcclassic-user-guide/run-checklist.rst +++ b/docs/source/gcclassic-user-guide/run-checklist.rst @@ -55,14 +55,32 @@ Each-time setup .. attention:: - Prior to running with :option:`GEOS-FP` meteorology, be aware - that it is an operational (i.e. evolving) product - that is subject to assimilation system updates. + Be aware that GEOS-FP meteorology is an operational + (i.e. evolving) product that is subject to assimilation + system updates. - On the other hand, the :option:`MERRA-2` meterology is a 40+ + On the other hand, the MERRA-2 meteorology is a 40+ year reanalysis product performed with a "frozen" version of the - NASA GEOS assimilation system. Thus, :option:`MERRA-2` is - preferable for studies ranging over multiple years or decades. + NASA GEOS assimilation system. Thus, `MERRA-2 + `_ is preferable for studies + ranging over multiple years or decades. + + .. important:: + + The convection scheme used for GEOS-FP met generation changed + from RAS to Grell-Freitas with impact on GEOS-FP meteorology + files starting June 1, 2020, specifically enhanced vertical + transport. In addition, there is a bug in convective + precipitation flux following the switch where all values are + zero. While this bug is automatically fixed by computing fluxes + online for runs starting on or after June 1 2020, the fix + assumes meteorology year corresponds to simulation year. Due to + these issues we recommend splitting up GEOS-FP runs in time such + that a single simulation does not run across June + 1, 2020. Instead. set one run to stop on June 1 2020 and then + restart a new run from there. If you wish to use a GEOS-FP + meteorology year different from your simulation year please + create a GEOS-Chem GitHub issue for assistance. #. :ref:`Configure and build ` the source code into an executable file. |br| diff --git a/docs/source/gcclassic-user-guide/run-speedup.rst b/docs/source/gcclassic-user-guide/run-speedup.rst index e56ef67..9c41e9d 100644 --- a/docs/source/gcclassic-user-guide/run-speedup.rst +++ b/docs/source/gcclassic-user-guide/run-speedup.rst @@ -1,7 +1,3 @@ -.. |br| raw:: html - -
- .. _run-speedup: ########################## @@ -11,32 +7,77 @@ Speed up a slow simulation GEOS-Chem Classic performance is continuously monitored by the `GEOS-Chem Support Team `_ by means of -benchmark simulations and ad-hoc timing tests. It has been shown that -running GEOS-Chem with -`recommended timesteps -`_ -from :cite:t:`Philip_et_al._2016`. can increase run times by -approximately a factor of 2. To speed up GEOS-Chem Classic -simulations, users may choose to use any of the following options. - -.. _use-coarser-timesteps: - -===================== -Use coarser timesteps -===================== - -As :ref:`discussed previously `, the default -timesteps for GEOS-Chem Classic are 600 seconds for dynamics, and 1200 -seconds for chemistry and emissions. You can experiment with using -coarser timesteps (such as 1800 seconds for dynamics and 3600 seconds -for emissions & chemistry). - -.. attention:: - - For nested-grid simulations, you might not be able to use coarser - timesteps, or else the Courant limit in transport will be violated. - -.. _turn-off-diagnostics: +benchmark simulations and ad-hoc timing tests. In this chapter, we +provide some practical tips that you can use to speed up your +simulations. + +.. _run-speedup-coarse-timesteps: + +================================ +Use a coarser chemistry timestep +================================ + +The table below contains our recommended GEOS-Chem Classic timestep +settings. + ++----------------------------------------------+-------------+--------------+ +| GEOS-Chem Classic Resolution | Transport | Chemistry | ++==============================================+=============+==============+ +| :math:`4^{\circ}{\times}5^{\circ}` | 600s (10m) | 1200s (20m) | ++----------------------------------------------+-------------+--------------+ +| :math:`2^{\circ}{\times}2.5^{\circ}` | 600s (10m) | 1200s (20m) | ++----------------------------------------------+-------------+--------------+ +| :math:`0.5^{\circ}{\times}0.625^{\circ}` | 300s (5m) | 600s (10m) | ++----------------------------------------------+-------------+--------------+ +| :math:`0.25^{\circ}{\times}0.3125^{\circ}` | 300s (5m) | 600s (10m) | ++----------------------------------------------+-------------+--------------+ +| :math:`0.125^{\circ}{\times}0.15625^{\circ}` | 150s (2.5m) | 300s (5m) | ++----------------------------------------------+-------------+--------------+ + +The `Courant limit +`_ +on the latitude-longitude grid constrains the choice of transport +timestep for a given horizontal resolution. We choose a chemistry +timestep that is double the transport timestep (i.e. +`Strang operator splitting +`_). + +If you wish to speed up your simulation, try increasing the chemistry +timestep. Chemistry is the GEOS-Chem operation that takes the longest +to execute, so increasing the interval between calls to the chemistry +solver will reduce the run time accordingly. But you should also verify +that the increased chemistry timestep allows your simulation to +faithfully capture diurnal variations, etc. + +See :cite:t:`Philip_et_al._2016` for a comprehensive study on +GEOS-Chem timesteps. + +.. _run-speedup-autoreduce: + +============================================= +Use the Rosenbrock solver with auto-reduction +============================================= + +The GEOS-Chem full-chemistry mechanism uses the KPP Rosenbrock solver, +which has an `automatic mechanism reduction option +`_ +as described in :cite:t:`Lin_et_al._2023`. This automatic mechanism +reduction feature separates species into "fast" and "slow" +categories based on their chemical production or loss rates. "Fast" +species are integrated with the full Rosenbrock algorithm, while +"slow" species will have a simple 1st-order loss applied to +them. This approach has been shown to reduce the time spent in +chemistry by 20 to 30 percent. + +The automatic mechanism reduction option is disabled by default, but +can be enabled by toggiing this switch in :ref:`cfg-gc-yml`: + +.. code-block:: yaml + + autoreduce_solver: + activate: false # <=== set to true to activate auto-reduction + +.. _run-speedup-disable-diags: ============================= Turn off unwanted diagnostics @@ -48,7 +89,7 @@ are turned on, the more I/O operations need to be done, resulting in longer simulation execution times. Disabling diagnostics that you do not wish to archive can result in a faster simulation. -.. _disable-debug-options: +.. _run-speedup-disable-debug: ========================= Disable debugging options @@ -67,3 +108,53 @@ Classic simulation, but result in a much slower simulation. If you plan on running a long Classic simulation, make sure that you :ref:`configure and build GEOS-Chem Classic ` so that :option:`CMAKE_BUILD_TYPE` is set to :envvar:`Release`. + +.. _run-speedup-combine-files: + +=============================================== +Reduce the amount of files that need to be read +=============================================== + +If you are developing a new data set (such as an emissions inventory) +for GEOS-Chem, we recommend that you prepare data files with multiple +timestamps rather than one file per timestamp. For example, if your +data set has hourly time resolution, consider creating one file for +each day, with each file containing 24 hours of data, etc. + +The greatest amount of overhead in I/O occurs when new data files (in +netCDF format) are opened. This also usually involves decompression +of the file contents, which is computationally intensive. Reducing +the number of times that GEOS-Chem has to open and close netCDF files +can substantially improve performance. + +.. _run-speedup-nested: + +===================================================== +Speeding up GEOS-Chem Classic nested-grid simulations +===================================================== + +Use these tips to speed up your GEOS-Chem nested-grid simulations: + +.. _run-speedup-nested-crop: + +Crop nested-grid meteorology inputs +----------------------------------- + +Your simulation should not read global high-resolution +(:math:`0.5^{\circ}{\times}0.625^{\circ}` or finer) meteorology +fields. The overhead in reading and regridding these global fields +can significantly impact your simulation. Instead, consider cropping +high-resolution meteorology fields to the extent of your nested domain. +This can easily be done with the netCDF operators or the Climate Data +Operators; see our :ref:`ncguide` supplemental guide for more +information. + +.. _run-speedup-nested-buffer: + +Increase the size of the transport buffer zone +---------------------------------------------- + +By default, nested :option:`buffer_zone_NSEW` option is set to 3 boxes +in each cardinal direction. Increasing this number will reduce the +amount of grid boxes in which transport will be performed, which +should also reduce the overall run time. diff --git a/docs/source/gcclassic-user-guide/rundir-carbon.rst b/docs/source/gcclassic-user-guide/rundir-carbon.rst index 915e26b..199e73f 100644 --- a/docs/source/gcclassic-user-guide/rundir-carbon.rst +++ b/docs/source/gcclassic-user-guide/rundir-carbon.rst @@ -136,6 +136,17 @@ simulation. We'll use the carbon gases simulation as an example. followed by :command:`ENTER`. |br| |br| + .. important:: + + The convection scheme used for GEOS-FP met generation changed + from RAS to Grell-Freitas with impact on GEOS-FP meteorology + files starting June 1, 2020. For this reason we recommend + using MERRA-2 instead of GEOS-FP if running a simulation + across June 1, 2020 to avoid unexpected + discontinuities. Additional information about the impact of + the convection change is at `geoschem/geos-chem#1409 + `_. + #. The next menu will prompt you for the horizontal resolution that you wish to use: diff --git a/docs/source/gcclassic-user-guide/rundir-fullchem.rst b/docs/source/gcclassic-user-guide/rundir-fullchem.rst index 8896a84..0fe33bc 100644 --- a/docs/source/gcclassic-user-guide/rundir-fullchem.rst +++ b/docs/source/gcclassic-user-guide/rundir-fullchem.rst @@ -138,6 +138,17 @@ GEOS-Chem full-chemistry simulation. :command:`1` followed by :command:`ENTER`. |br| |br| + .. important:: + + The convection scheme used for GEOS-FP met generation changed + from RAS to Grell-Freitas with impact on GEOS-FP meteorology + files starting June 1, 2020. For this reason we recommend + using MERRA-2 instead of GEOS-FP if running a simulation + across June 1, 2020 to avoid unexpected + discontinuities. Additional information about the impact of + the convection change is at `geoschem/geos-chem#1409 + `_. + #. The next menu will prompt you for the horizontal resolution that you wish to use: @@ -252,7 +263,7 @@ GEOS-Chem full-chemistry simulation. |br| -#. The last menu will prompt you with: +#. The next menu will prompt you with: .. code-block:: console @@ -271,6 +282,35 @@ GEOS-Chem full-chemistry simulation. Initialized empty Git repository in /path/to/gc_4x5_merra2_fullchem/.git/ + |br| + +#. The next (and final) menu will ask you: + + .. code-block:: console + + ----------------------------------------------------------- + Do you want to build the KPP-Standalone Box Model? (y/n) + ----------------------------------------------------------- + >>> + + + Type :program:`y` and then :command:`ENTER` you wish to build the + :program:`KPP-Standalone Box Model`, or :program:`n` then + :program:`ENTER` to skip this step. If you choose to build + KPP-Standalone, you will be given this reminder: + + .. code-block:: console + + >>>> REMINDER: You must compile with options: -DKPPSA=y <<<< + + Please see the Supplemental Guide entitled :ref:`kppsa-guide` + for further usage instructions. + + Lastly, you will see a message to indicate that run directory + creation has completed successfully. + + .. code-block:: console + Created /path/to/gc_4x5_merra2_fullchem You may now navigate to this directory and start editing the :ref:`GEOS-Chem diff --git a/docs/source/gcclassic-user-guide/spec-db.rst b/docs/source/gcclassic-user-guide/spec-db.rst deleted file mode 100644 index 325f440..0000000 --- a/docs/source/gcclassic-user-guide/spec-db.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. _cfg-spec-db: - -#################### -species_database.yml -#################### - -.. note:: - - You will only need to edit :file:`species_database.yml` if you are - adding new species to a GEOS-Chem simulation. - -The :ref:`GEOS-Chem Species Database ` is a `YAML file -`_ that contains a listing of metadata for each -species used by GEOS-Chem. The Species Database is included in your -run directory as file :file:`species_database.yml`, a snippet of which -is shown below. - -.. code-block:: yaml - - # GEOS-Chem Species Database - # Core species only (neglecting microphysics) - # NOTE: Anchors must be defined before any variables that reference them. - A3O2: - Formula: CH3CH2CH2OO - FullName: Primary peroxy radical from C3H8 - Is_Gas: true - MW_g: 75.10 - ACET: - DD_F0: 1.0 - DD_Hstar: 1.0e+5 - Formula: CH3C(O)CH3 - FullName: Acetone - Henry_CR: 5500.0 - Henry_K0: 2.74e+1 - Is_Advected: true - Is_DryDep: true - Is_Gas: true - Is_Photolysis: true - MW_g: 58.09 - - ... etc ... - - AERI: - DD_DvzAerSnow: 0.03 - DD_DvzMinVal: [0.01, 0.01] - DD_F0: 0.0 - DD_Hstar: 0.0 - Formula: I - FullName: Iodine on aerosol - Is_Advected: true - Is_Aerosol: true - Is_DryDep: true - Is_WetDep: true - MW_g: 126.90 - WD_AerScavEff: 1.0 - WD_KcScaleFac: [1.0, 0.5, 1.0] - WD_RainoutEff: [1.0, 0.0, 1.0] - WD_RainoutEff_Luo: [0.4, 0.0, 1.0] - - ... etc ... - -.. important:: - - Species NO (nitrogen oxide) must be listed in - :file:`species_database.yml` as :code:`'NO':`. This will avoid - YAML readers mis-intepreting this as :literal:`no` (meaning - :literal:`false`). - - -Each species name begins in the first column of the file, followed by -a :literal:`:`. Underneath -the species name follows an indented block of :ref:`species properties -` in :literal:`Property: Value` format. - -Some properties listed above are only applicable to gas-phase species, -and others to aerosol species. But at the very least, each species -should have the following properties defined: - -- :literal:`Formula` -- :literal:`FullName` -- :literal:`MW_g` -- Either :literal:`Is_Gas` or :literal:`Is_Aerosol` - -For more information about species properties, please see -:ref:`spcguide` in the Supplemental Guides section. diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index ce3c86a..c769e00 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit ce3c86accdcd73d3c3a46e41be1fcc09775200dd +Subproject commit c769e0007cc02270016e68e738623ac97b1fbcb5 diff --git a/docs/source/getting-started/compilers.rst b/docs/source/getting-started/compilers.rst index eaf30dd..b9cf31d 100644 --- a/docs/source/getting-started/compilers.rst +++ b/docs/source/getting-started/compilers.rst @@ -27,19 +27,19 @@ The GCST has tested :program:`GEOS-Chem Classic` with these versions - 23.0.0 - 19.0.5.281 - 19.0.4 -- 18.0.5 -- 17.0.4 -- 15.0.0 -- 13.0.079 -- 11.1.069 + +Older compiler versions than these may either be incompatible with +GEOS-Chem, or may cause unexpected results. We hope to be able to +port GEOS-Chem to the latest Intel 2024 compiler suite (:literal:`icx` +for C, C++ and :literal:`ifx` for Fortran) in the near future. **Best way to install:** `Direct from Intel `_ -(may require purchase of a site license or a student license) +(Older versions may require purchase of a site license or a student license) .. tip:: - Intel 2021 may be obtained for free, or installed with a + Intel 2021 and later may be obtained for free, or installed with a package manager such as `Spack `_. .. _req-soft-compilers-gnu: @@ -69,6 +69,10 @@ The GCST has tested :program:`GEOS-Chem Classic` with these versions - 7.1.0 - 6.2.0 +We recommend using GCC 10 or later if possible. We have not +thoroughly tested GEOS-Chem with compiler versions more recent than +GCC 12 as of January 2025. + **Best way to install:** :ref:`With Spack `. @@ -81,7 +85,7 @@ Other compilers We currently have no plans to port GEOS-Chem to compilers other than :ref:`req-soft-compilers-intel` and :ref:`req-soft-compilers-gnu`. But when we interface -GEOS-Chem into external models (such as `CESM +GEOS-Chem into external models (such as `CESM `_); all compilers used by the parent model can successfully parse GEOS-Chem source code. diff --git a/docs/source/getting-started/disk-space.rst b/docs/source/getting-started/disk-space.rst index 74bb30c..faa9f5a 100644 --- a/docs/source/getting-started/disk-space.rst +++ b/docs/source/getting-started/disk-space.rst @@ -6,7 +6,7 @@ Disk space requirements The following sections will help you assess how much disk space you will need on your server to store GEOS-Chem Classic :ref:`input data -` and :ref:`output data `. +` and :ref:`output data `. .. _req-hard-disk-limits: @@ -24,8 +24,8 @@ information. Emissions input fields ---------------------- -Please see our :ref:`Emissions input data ` section for -more information. +Please see our :ref:`Emissions input data ` +section for more information. .. _req-hard-disk-met: @@ -101,7 +101,7 @@ sections. `_; #. Direct access from the `Amazon data portal using AWS S3 Explorer `_. -Also see our :ref:`input-overview` for more data download options. +Also see our :ref:`data` chapter for more data download options. .. _data-generated-by-geos-chem: diff --git a/docs/source/getting-started/login-env-compilers.rst b/docs/source/getting-started/login-env-compilers.rst index 6885a8e..e4f6c58 100644 --- a/docs/source/getting-started/login-env-compilers.rst +++ b/docs/source/getting-started/login-env-compilers.rst @@ -4,8 +4,8 @@ Set environment variables for compilers ####################################### -The sample :ref:`GNU ` and :ref:`Intel -` environment files set the **environment +The sample :ref:`GNU ` and :ref:`Intel +` environment files set the **environment variables** listed below in order to select the desired C, C++, and Fortran compilers: diff --git a/docs/source/getting-started/login-env-files-gnu.rst b/docs/source/getting-started/login-env-files-gnu.rst index e8c37bb..05e4e24 100644 --- a/docs/source/getting-started/login-env-files-gnu.rst +++ b/docs/source/getting-started/login-env-files-gnu.rst @@ -1,36 +1,64 @@ -.. _env-files-gnu10: +.. _env-files-gnu: ################################################ -Sample environment file for GNU 10.2.0 compilers +Sample environment file for GNU 12.2.0 compilers ################################################ Below is a sample environment file (based on an enviroment file for the Harvard Cannon computer cluster). This file will load software -libraries built with the GNU 10.2.0 compilers. +libraries built with the `GNU 12.2.0 compilers +`_. + +.. note:: + + This environment file shown below assumes that required software + packages for :program:`GEOS-Chem Classic` are available as + pre-built modules. If your computer system does not have these + packages pre-installed, you can build them with Spack. Please see + our :ref:`spackguide` supplemental guide for detailed instructions. Save the code below (with any appropriate modifications for your own -computer system) to a file named :file:`~/gcclassic.gnu10.env`. +computer system) to a file named :file:`~/gcclassic.gnu12.env`. .. code-block:: bash + ############################################################################### + # + # Environment file for GCClassic + GNU Compiler Collection 12.2.0 + # + ############################################################################### + + # Display message (if we are in a terminal window) + if [[ $- = *i* ]] ; then + echo "Loading modules for GEOS-Chem Classic, please wait ..." + fi + #============================================================================== - # Load software packages (EDIT AS NEEDED) + # Unload all previously-unloaded software #============================================================================== - # Unload all modules first + # Unload packages loaded with "module load" module purge - # Load modules - module load gcc/10.2.0-fasrc01 # gcc / g++ / gfortran - module load openmpi/4.1.0-fasrc01 # MPI - module load netcdf-c/4.8.0-fasrc01 # netcdf-c - module load netcdf-fortran/4.5.3-fasrc01 # netcdf-fortran + #============================================================================== + # Load software packages for GNU 12.2.0 + #============================================================================== + if [[ $- = *i* ]] ; then + echo "... Loading FASRC-built software, please wait ..." + fi + + # Pre-built modules needed for GEOS-Chem + # (NOTE: These may be named differently on your system) + module load gcc/12.2.0-fasrc01 # gcc / g++ / gfortran + module load openmpi/4.1.4-fasrc01 # MPI + module load netcdf-c/4.9.2-fasrc01 # netcdf-c + module load netcdf-fortran/4.6.0-fasrc02 # netcdf-fortran module load flex/2.6.4-fasrc01 # Flex lexer (needed for KPP) module load cmake/3.25.2-fasrc01 # CMake (needed to compile) #============================================================================== # Environment variables and related settings - # (NOTE: Lmod will define _HOME variables for each loaded module + # (NOTE: Lmod will define _HOME variables for each loaded module) #============================================================================== # Make all files world-readable by default @@ -55,13 +83,13 @@ computer system) to a file named :file:`~/gcclassic.gnu10.env`. # netCDF if [[ "x${NETCDF_HOME}" == "x" ]]; then - export NETCDF_HOME="${NETCDF_C_HOME}" + export NETCDF_HOME="${NETCDF_C_HOME}" fi export NETCDF_C_ROOT="${NETCDF_HOME}" - export NETCDF_FORTRAN_ROOT="${NETCDF_FORTRAN_HOME}" + export NETCDF_FORTRAN_ROOT=${NETCDF_FORTRAN_HOME} # KPP 3.0.0+ - export KPP_FLEX_LIB_DIR="${FLEX_HOME}/lib64" + export KPP_FLEX_LIB_DIR=${FLEX_HOME}/lib64 #============================================================================== # Set limits @@ -75,20 +103,28 @@ computer system) to a file named :file:`~/gcclassic.gnu10.env`. #============================================================================== # Print information #============================================================================== - module list - -.. tip:: - Ask your sysadmin how to load software libraries. If you are using - your institution's computer cluster, then chances are there will - be a software module system installed, with commands similar to - those listed above. + module list -Then you can activate these seetings from the command line by typing: + echo "" + echo "Environment:" + echo "" + echo "CC : ${CC}" + echo "CXX : ${CXX}" + echo "FC : ${FC}" + echo "KPP_FLEX_LIB_DIR : ${KPP_FLEX_LIB_DIR}" + echo "MPI_HOME : ${MPI_HOME}" + echo "NETCDF_HOME : ${NETCDF_HOME}" + echo "NETCDF_FORTRAN_HOME : ${NETCDF_FORTRAN_HOME}" + echo "OMP_NUM_THREADS : ${OMP_NUM_THREADS}" + echo "" + echo "Done sourcing ${BASH_SOURCE[0]}" + +To activate the settings contained in the environment file, type: .. code-block:: console - $ . ~/gcclassic.gnu10.env + $ . ~/gcclassic.gnu12.env You may also place the above command within your :ref:`GEOS-Chem run script `, which will be discussed in a subsequent chapter. diff --git a/docs/source/getting-started/login-env-files-intel.rst b/docs/source/getting-started/login-env-files-intel.rst index 4b0494f..d2f3c49 100644 --- a/docs/source/getting-started/login-env-files-intel.rst +++ b/docs/source/getting-started/login-env-files-intel.rst @@ -1,4 +1,4 @@ -.. _env-files-intel19: +.. _env-files-intel: ################################################ Sample environment file for Intel 2023 compilers @@ -8,14 +8,24 @@ Below is a sample environment file (based on an enviroment file for the Harvard Cannon computer cluster). This file will load software libraries built with the Intel 2023 compilers. +.. note:: + + This environment file shown below assumes that required software + packages for :program:`GEOS-Chem Classic` are available as + pre-built modules. If your computer system does not have these + packages pre-installed, you can build them with Spack. Please see + our :ref:`spackguide` supplemental guide for detailed instructions. + Add the code below (with the appropriate modifications for your system) into a file named :file:`~/gcclassic.intel23.env`. .. code-block:: bash - #============================================================================== - # Load software packages (EDIT AS NEEDED) - #============================================================================== + ############################################################################### + # + # Environment file for GCClassic + Intel 2023 compilers + # + ############################################################################### # Unload all modules first module purge @@ -77,14 +87,21 @@ system) into a file named :file:`~/gcclassic.intel23.env`. module list -.. tip:: - - Ask your sysadmin how to load software libraries. If you - are using your institution's computer cluster, then chances - are there will be a software module system installed, with - commands similar to those listed above. - -Then you can activate these settings from the command line by typing: + echo "" + echo "Environment:" + echo "" + echo "CC : ${CC}" + echo "CXX : ${CXX}" + echo "FC : ${FC}" + echo "KPP_FLEX_LIB_DIR : ${KPP_FLEX_LIB_DIR}" + echo "MPI_HOME : ${MPI_HOME}" + echo "NETCDF_HOME : ${NETCDF_HOME}" + echo "NETCDF_FORTRAN_HOME : ${NETCDF_FORTRAN_HOME}" + echo "OMP_NUM_THREADS : ${OMP_NUM_THREADS}" + echo "" + echo "Done sourcing ${BASH_SOURCE[0]}" + +To activate the settings contained in the environment file, type: .. code-block:: console diff --git a/docs/source/getting-started/login-env-files.rst b/docs/source/getting-started/login-env-files.rst index 3e76c85..3ef2e27 100644 --- a/docs/source/getting-started/login-env-files.rst +++ b/docs/source/getting-started/login-env-files.rst @@ -30,7 +30,7 @@ command such as: Keep a separate environment file for each combination of modules that you will use. Example environment files - for :ref:`GNU ` and :ref:`Intel ` + for :ref:`GNU ` and :ref:`Intel ` compilers and related software are provided in the following sections. For general information about how libraries are loaded, see diff --git a/docs/source/getting-started/login-env-parallel.rst b/docs/source/getting-started/login-env-parallel.rst index bd7bfaf..17701ba 100644 --- a/docs/source/getting-started/login-env-parallel.rst +++ b/docs/source/getting-started/login-env-parallel.rst @@ -24,8 +24,8 @@ shared-memory (aka serial) parallelization. `_ for more computationally-intensive simulations. -In the the sample environment files for :ref:`GNU ` and -:ref:`Intel `, we define the following **environment +In the the sample environment files for :ref:`GNU ` and +:ref:`Intel `, we define the following **environment varaiables** for OpenMP parallelization: .. option:: OMP_NUM_THREADS @@ -88,9 +88,7 @@ Be on the lookout for these errors: #. If :option:`OMP_STACKSIZE` environment variable is not included in your environment file (or if it is set to a very low value), - you might encounter a `segmentation fault error after the TPCORE - transport module is initialized - `_. - In this case, GEOS-Chem Classic "thinks" that it does - not have enough memory to perform the simulation, even though - sufficient memory may be present. + you might encounter a :ref:`errguide-segfault-tpcore` error. In + this case, GEOS-Chem Classic "thinks" that it does not have + enough memory to perform the simulation, even though sufficient + memory may be present. diff --git a/docs/source/getting-started/login-env.rst b/docs/source/getting-started/login-env.rst index 156345c..c463c78 100644 --- a/docs/source/getting-started/login-env.rst +++ b/docs/source/getting-started/login-env.rst @@ -12,6 +12,13 @@ Customize your login environment Machine Images (AMIs) all of the required software libraries will be automatically loaded. +.. tip:: + + If your computer system lacks the required software packages for + :program:`GEOS-Chem Classic`, you can build them with the Spack + package manager. For detailed instructions, please see our + :ref:`spackguide` supplemental guide. + Each time you log in to your computer system, you'll need to load the :ref:`software libraries ` needed by GEOS-Chem into your environment. You can do this with a script known diff --git a/docs/source/getting-started/quick-start.rst b/docs/source/getting-started/quick-start.rst index 6bc10b6..da46b40 100644 --- a/docs/source/getting-started/quick-start.rst +++ b/docs/source/getting-started/quick-start.rst @@ -1,3 +1,7 @@ +.. |br| raw:: html + +
+ .. _quick: ################ @@ -119,8 +123,25 @@ simulations follow the same pattern as the examples shown below. provide :ref:`registration information `. Please answer all of the questions, as it will help us to keep track of GEOS-Chem usage worldwide. We will also add your - information to the `GEOS-Chem People and Projects web page - `_. + information to the `GEOS-Chem Users web page + `_. + +.. important:: + + The convection scheme used for GEOS-FP met generation changed + from RAS to Grell-Freitas with impact on GEOS-FP meteorology + files starting June 1, 2020, specifically enhanced vertical + transport. In addition, there is a bug in convective + precipitation flux following the switch where all values are + zero. While this bug is automatically fixed by computing fluxes + online for runs starting on or after June 1 2020, the fix + assumes meteorology year corresponds to simulation year. Due to + these issues we recommend splitting up GEOS-FP runs in time such + that a single simulation does not run across June + 1, 2020. Instead. set one run to stop on June 1 2020 and then + restart a new run from there. If you wish to use a GEOS-FP + meteorology year different from your simulation year please + create a GEOS-Chem GitHub issue for assistance. .. _quick-load: @@ -209,8 +230,8 @@ where the error happened and why. $ cmake . -DCMAKE_BUILD_TYPE=Debug -See the :ref:`GEOS-Chem documentation ` for more -information on configuration options. +:ref:`Click here ` for more information on +configuration options. .. _quick-cmp-inst: @@ -226,7 +247,7 @@ with the :literal:`-j` flag from the :file:`build/` directory: .. code-block:: console - # cd /path/to/gc_4x5_merra2_fullchem/build # Skip if you are already here + $ cd /path/to/gc_4x5_merra2_fullchem/build # Skip if you are already here $ make -j Upon successful compilation, install the compiled executable to your @@ -278,7 +299,39 @@ You should review these files before starting a simulation: - :ref:`HEMCO_Config.rc ` - Controls which emissions inventories and other non-emissions data - will be read from disk (via `HEMCO `_). + will be read from disk (via `HEMCO + `_). + +.. attention:: + + If you wish to spin up a GEOS-Chem simulation with a restart file + that has (1) missing species or (2) a timestamp that does not + match the start date in :ref:`geoschem_config.yml `, + simply change the time cycle flag for the :literal:`SPC_` entry in + :ref:`HEMCO_Config.rc ` from + + .. code-block:: console + + * SPC_ ... $YYYY/$MM/$DD/$HH EFYO xyz 1 * - 1 1 + + to + + .. code-block:: console + + * SPC_ ... $YYYY/$MM/$DD/$HH CYS xyz 1 * - 1 1 + + This will direct HEMCO to read the closest date + available (:literal:`C`), to use the simulation year + (:literal:`Y`), and to skip any species (:literal:`S`) not found + in the restart file. + + Skipped species will be assigned the initial concentration + (units: :math:`mol\ mol^{-1}` w/r/t dry air) specified by its + :option:`BackgroundVV` entry in :ref:`species_database.yml + `. If the species does not have a + :option:`BackgroundVV` value specified, then its initial + concentration will be set to :math:`1.0{\times}10^{-20}` + instead. Please see our :ref:`customguide` Supplemental Guide to learn how you can customize your simulation by activating alternate science options @@ -293,16 +346,18 @@ in your simulations. Before you can run your GEOS-Chem Classic simulation, you must first :ref:`download the required input data `. These data include: -- Meteorological fields (e.g. GEOS-FP, MERRA-2, GEOS-IT, or GCAP2) -- Emissions inventories -- Inputs for GEOS-Chem modules (e.g. Cloud-J) +- :ref:`Meteorological fields ` (e.g. GEOS-FP, + MERRA-2, GEOS-IT, or GCAP2) +- :ref:`Emissions inventories ` +- :ref:`Inputs for GEOS-Chem modules (e.g. Cloud-J) ` +- :ref:`Initial conditions for starting GEOS-Chem simulations ` .. tip:: If your institution has several GEOS-Chem users, then someone may have already downloaded these data for you. If this is the case, you may :ref:`start running your your GEOS-Chem Classic simulation - `. + ` right away. The easiest way to download data is to perform a :ref:`dry-run simulation `. This is a GEOS-Chem Classic simulation that @@ -321,15 +376,7 @@ list of data files to be downloaded. Once the dry-run simulation has finished, use the :file:`download_data.py` file (included in your run directory) to -:ref:`download the required data `. Type: - -.. code-block:: console - - $ ./download_data.py log.dryrun --washu - -This will download data from the :option:`WashU` data portal. You -may also download from the :option:`Amazon` or :option:`Rochester` -data portals. +:ref:`download the required data `. .. note:: @@ -337,6 +384,33 @@ data portals. Mamba environment containing a version of Python before running the :file:`download.data.py` script. Ask your sysadmin. +To start the data download, type: + +.. code-block:: console + + $ ./download_data.py log.dryrun geoschem+http + +This will download data from the :ref:`GEOS-Chem Input Data ` +portal using the HTTP data transfer protocol. + +.. tip:: + + If you have `AWS CLI (command line interface) + `_ installed on your system, you + can use this command instead: + + .. code-block:: console + + $ ./download_data.py log.dryrun geoschem+aws + + This will use the AWS CLI data download protocol instead, which + should be faster than regular HTTP connections. This is the + command you should use if you are running GEOS-Chem Classic in an + AWS EC2 instance. + +We also maintain :ref:`separate data portals ` +for special nested-grid domains as well as the GCAP 2.0 meteorology. + For more information about dry-run simulations, please see our :ref:`dry-run` chapter. diff --git a/docs/source/help-and-reference/known-bugs.rst b/docs/source/help-and-reference/known-bugs.rst index 59debd7..2c228f6 100644 --- a/docs/source/help-and-reference/known-bugs.rst +++ b/docs/source/help-and-reference/known-bugs.rst @@ -23,8 +23,25 @@ are currently unresolved. We hope to fix these in future releases. diagnostic collection may not be working as expected. We are currently investigating. +.. important:: + + The convection scheme used for GEOS-FP met generation changed + from RAS to Grell-Freitas with impact on GEOS-FP meteorology + files starting June 1, 2020, specifically enhanced vertical + transport. In addition, there is a bug in convective + precipitation flux following the switch where all values are + zero. While this bug is automatically fixed by computing fluxes + online for runs starting on or after June 1 2020, the fix + assumes meteorology year corresponds to simulation year. Due to + these issues we recommend splitting up GEOS-FP runs in time such + that a single simulation does not run across June + 1, 2020. Instead. set one run to stop on June 1 2020 and then + restart a new run from there. If you wish to use a GEOS-FP + meteorology year different from your simulation year please + create a GEOS-Chem GitHub issue for assistance. + ============================ Bugs that have been resolved ============================ -These `bug reports (on GitHub) `_ have been resolved. +These `bugs (reported on GitHub) `_ have been resolved. diff --git a/docs/source/index.rst b/docs/source/index.rst index 7a95fae..fcaab7e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -84,7 +84,7 @@ modifications to GEOS-Chem Classic source code. geos-chem-shared-docs/supplemental-guides/parallel-guide.rst supplemental-guides/nested-grid-guide.rst geos-chem-shared-docs/supplemental-guides/using-kpp-with-gc.rst - geos-chem-shared-docs/supplemental-guides/geos-chem-input-data-on-aws.rst + geos-chem-shared-docs/supplemental-guides/using-kpp-standalone.rst geos-chem-shared-docs/supplemental-guides/related-docs.rst .. toctree:: diff --git a/docs/source/supplemental-guides/nested-grid-guide.rst b/docs/source/supplemental-guides/nested-grid-guide.rst index 2cd2fa8..b8524ce 100644 --- a/docs/source/supplemental-guides/nested-grid-guide.rst +++ b/docs/source/supplemental-guides/nested-grid-guide.rst @@ -238,11 +238,20 @@ simulations on different nested domains. How can I find which data are available for nested grid simulations? -------------------------------------------------------------------- -You will download meteorology and emissions data from one of the -:ref:`GEOS-Chem data portals `. You can browse the -WashU data portal (`http://geoschemdata.wustl.edu/ExtData -`_) to see if the data you need -are available. +You can browse the contents of the GEOS-Chem data portals by pointing +your browser to one of the following links: + +- :ref:`GEOS-Chem Input Data ` + + - https://geos-chem.s3.amazonaws.com/index.html + +- :ref:`GEOS-Chem Nested Input Data ` + + - https://gcgrid.s3.amazonaws.com/index.html + +- :ref:`GCAP 2.0 meteorology @ U. Rochester ` + + - http://atmos.earth.rochester.edu/input/gc/ExtData/ .. _nestgrid-faq-errors: diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 1dd29e8..576eec4 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -38,6 +38,45 @@ set_target_properties(${EXE_FILE_NAME} RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin ) +#----------------------------------------------------------------------------- +# If GEOS-Chem Classic has been configured with -DKPPSA=y, then: +# +# Define the KPP standalone executable: +# 1. Specify a cache variable with the default target name +# 2. Specify the location of the main program +# 3. Specify libraries that the main program depends on +# 4. Store the binary exectuable file in the bin folder (pre-install) +# 5. If not fullchem or custom mechanism, prevent executable from being built +# +# At present build KPP standalone only for fullchem or custom mechanisms. +# +# This should now fix the issue reported by @msulprizio in: +# https://github.com/geoschem/GCClassic/issues/78 +#----------------------------------------------------------------------------- +if (${KPPSA}) + set(KPPSA_FILE_NAME kpp_standalone CACHE STRING + "Default name for the KPP standalone executable file") + mark_as_advanced(KPPSA_FILE_NAME) + add_executable(${KPPSA_FILE_NAME} + GEOS-Chem/KPP/standalone/kpp_standalone.F90 + ) + if("${MECH}" STREQUAL fullchem OR "${MECH}" STREQUAL custom) + target_link_libraries(${KPPSA_FILE_NAME} + PUBLIC + KPPStandalone + ) + set_target_properties(${KPPSA_FILE_NAME} + PROPERTIES + RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin + ) + else() + set_target_properties(${KPPSA_FILE_NAME} + PROPERTIES + EXCLUDE_FROM_ALL TRUE + ) + endif() +endif() + #----------------------------------------------------------------------------- # When "make install" is run, copy the target to the destination folder # (which is typically one directory higher than the CMake build folder) @@ -71,6 +110,12 @@ foreach(INSTALL_PATH ${COMBINED_INSTALL_DIRS}) # Installation path is a GEOS-Chem run directory, # Therefore we will install the executable there. install(TARGETS ${EXE_FILE_NAME} RUNTIME DESTINATION ${INSTALL_PATH}) + + # Only install KPP standalone for fullchem/custom mechanisms. + # See: htps://github.com/geoschem/GCClassic/issues/78 + if("${MECH}" STREQUAL fullchem OR "${MECH}" STREQUAL custom) + install(TARGETS ${KPPSA_FILE_NAME} RUNTIME DESTINATION ${INSTALL_PATH}) + endif() endif() endforeach() diff --git a/src/Cloud-J b/src/Cloud-J index d20050f..f8a2b7f 160000 --- a/src/Cloud-J +++ b/src/Cloud-J @@ -1 +1 @@ -Subproject commit d20050f1ef9e3895d58f3041efd2da59ce1ed421 +Subproject commit f8a2b7f964bde1582fbc38c41d8872bc23a21735 diff --git a/src/GEOS-Chem b/src/GEOS-Chem index bef56c6..86cd586 160000 --- a/src/GEOS-Chem +++ b/src/GEOS-Chem @@ -1 +1 @@ -Subproject commit bef56c605e018eecbd91646a51ce82c7cd77f56a +Subproject commit 86cd586260e4f2a9db7efd06cea19a5fe0bdc9e8 diff --git a/src/HEMCO b/src/HEMCO index 41605bd..baa9ce5 160000 --- a/src/HEMCO +++ b/src/HEMCO @@ -1 +1 @@ -Subproject commit 41605bda8a89d96f441cb8eb90f3d3c8b21f2b71 +Subproject commit baa9ce52be6c959e0561d6567565045e7c286096