diff --git a/CHANGELOG.md b/CHANGELOG.md index 7fc2747..227f0a8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,14 +7,18 @@ This file documents all notable changes to the GEOS-Chem Classic wrapper reposit The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased] - TBD +## [14.5.0] - 2024-11-08 ### Changed - Updated GEOS-Chem to 14.5.0 - Updated HEMCO to 3.10.0 - Updated Cloud-J to 8.0.1 +- Updated `docs/source/geos-chem-shared-docs/spack/packages.yaml` to use GCC 12.2.0 compilers +- Updated documentation for version 14.5.0 +- Moved several doc files (not supplemental guides) that are used in both GCClassic and GCHP the to `geos-chem-shared-docs/doc` folder ### Fixed - Fixed formatting error in `.github/workflows/stale.yml` that caused the Mark Stale Issues action not to run +- Updated to Python package `jinja2==3.1.4` in `docs/requirements.txt` (fixes a security issue) ## [14.4.3] - 2024-08-13 ### Changed diff --git a/CMakeLists.txt b/CMakeLists.txt index c193cfd..0446acd 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -2,7 +2,7 @@ cmake_minimum_required (VERSION 3.13) project (geos-chem-classic - VERSION 14.4.3 + VERSION 14.5.0 LANGUAGES Fortran ) diff --git a/docs/requirements.txt b/docs/requirements.txt index 60b3987..71e269d 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -12,4 +12,4 @@ sphinxcontrib-bibtex==2.6.2 sphinx-autobuild==2021.3.14 recommonmark==0.7.1 docutils==0.20.1 -jinja2==3.1.3 +jinja2==3.1.4 diff --git a/docs/source/conf.py b/docs/source/conf.py index 1c46044..6457dec 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,7 +23,7 @@ author = 'GEOS-Chem Support Team' # The full version, including alpha/beta/rc tags -release = '14.4.3' +release = '14.5.0' # -- General configuration --------------------------------------------------- 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/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/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..d02bd2e 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: 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..14adeb4 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit ce3c86accdcd73d3c3a46e41be1fcc09775200dd +Subproject commit 14adeb4d8a9cfbdebd688033e4c22dd034ac105b 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..b2a9fba 100644 --- a/docs/source/getting-started/login-env-parallel.rst +++ b/docs/source/getting-started/login-env-parallel.rst @@ -24,8 +24,8 @@ shared-memory (aka serial) parallelization. `_ for more computationally-intensive simulations. -In the the sample environment files for :ref:`GNU ` and -:ref:`Intel `, we define the following **environment +In the the sample environment files for :ref:`GNU ` and +:ref:`Intel `, we define the following **environment varaiables** for OpenMP parallelization: .. option:: OMP_NUM_THREADS diff --git a/docs/source/getting-started/login-env.rst b/docs/source/getting-started/login-env.rst index 156345c..c463c78 100644 --- a/docs/source/getting-started/login-env.rst +++ b/docs/source/getting-started/login-env.rst @@ -12,6 +12,13 @@ Customize your login environment Machine Images (AMIs) all of the required software libraries will be automatically loaded. +.. tip:: + + If your computer system lacks the required software packages for + :program:`GEOS-Chem Classic`, you can build them with the Spack + package manager. For detailed instructions, please see our + :ref:`spackguide` supplemental guide. + Each time you log in to your computer system, you'll need to load the :ref:`software libraries ` needed by GEOS-Chem into your environment. You can do this with a script known 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..e8895ed 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -84,7 +84,6 @@ modifications to GEOS-Chem Classic source code. geos-chem-shared-docs/supplemental-guides/parallel-guide.rst supplemental-guides/nested-grid-guide.rst geos-chem-shared-docs/supplemental-guides/using-kpp-with-gc.rst - geos-chem-shared-docs/supplemental-guides/geos-chem-input-data-on-aws.rst geos-chem-shared-docs/supplemental-guides/related-docs.rst .. toctree:: 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: