From 6ed61023164c429547e9dc403741a6e514737bb8 Mon Sep 17 00:00:00 2001 From: "Lee T. Murray" Date: Mon, 6 May 2024 19:50:24 -0400 Subject: [PATCH 01/14] Purposely breaking GCClassic/HEMCO to try to get libraries to compile for GISS-GC. The goal is to try to get GISS-GC to run, so we can go back to before this commit, and imeplement a version that does not break GCClassic. Note, the "GISS_MODEL" mostly robust, it's just edits to where MODEL_CLASSIC lines that are wrong. --- src/Core/hco_config_mod.F90 | 6 ++++-- src/Core/hcoio_read_std_mod.F90 | 15 ++++++++------- src/Core/hcoio_write_std_mod.F90 | 3 ++- 3 files changed, 14 insertions(+), 10 deletions(-) diff --git a/src/Core/hco_config_mod.F90 b/src/Core/hco_config_mod.F90 index f1b27372..aaa11b6e 100644 --- a/src/Core/hco_config_mod.F90 +++ b/src/Core/hco_config_mod.F90 @@ -2106,6 +2106,7 @@ SUBROUTINE ReadSettings( HcoConfig, IU_HCO, EOF, RC ) #ifndef MODEL_GEOS #ifndef MODEL_WRF +#ifndef MODEL_GISS #ifndef MODEL_CESM #ifndef ESMF_ !======================================================================= @@ -2149,7 +2150,8 @@ SUBROUTINE ReadSettings( HcoConfig, IU_HCO, EOF, RC ) #endif #endif #endif - +#endif + !----------------------------------------------------------------------- ! Initialize error object if needed. ! Extract values to initialize error module and set some further @@ -2430,7 +2432,7 @@ SUBROUTINE RegisterPrepare( HcoState, RC ) ! ! Thus, the following fix needs to be applied for ESMF environments, ! skipping a lot of the calculations below. -#if defined ( ESMF_ ) || defined( MODEL_WRF ) || defined( MODEL_CESM ) +#if defined ( ESMF_ ) || defined( MODEL_WRF ) || defined( MODEL_CESM ) || defined( MODEL_GISS ) ThisCover = -1 #else ! Get mask edges diff --git a/src/Core/hcoio_read_std_mod.F90 b/src/Core/hcoio_read_std_mod.F90 index 76f35994..f0d65bd7 100644 --- a/src/Core/hcoio_read_std_mod.F90 +++ b/src/Core/hcoio_read_std_mod.F90 @@ -1,9 +1,10 @@ !BOC -#if defined ( MODEL_GCCLASSIC ) || defined( MODEL_WRF ) || defined( MODEL_CESM ) || defined( HEMCO_STANDALONE ) +#if defined ( MODEL_GCCLASSIC ) || defined( MODEL_WRF ) || defined( MODEL_CESM )|| defined( MODEL_GISS ) || defined( HEMCO_STANDALONE ) ! The 'standard' HEMCO I/O module is used for: ! - HEMCO Standalone (HEMCO_STANDALONE) ! - GEOS-Chem 'Classic' (MODEL_GCCLASSIC) ! - WRF-GC (MODEL_WRF) +! - GISS-GC (MODEL_GISS) ! - CESM-GC and CAM-Chem / HEMCO-CESM (MODEL_CESM) !EOC !------------------------------------------------------------------------------ @@ -61,7 +62,7 @@ MODULE HCOIO_Read_Mod ! Parameter used for difference testing of floating points REAL(dp), PRIVATE, PARAMETER :: EPSILON = 1.0e-5_dp -#if defined( MODEL_CESM ) || defined( MODEL_WRF ) +#if defined( MODEL_CESM ) || defined( MODEL_WRF ) || defined( MODEL_GISS ) REAL(hp), PRIVATE :: GC_72_EDGE_SIGMA(73) = (/ & 1.000000E+00, 9.849998E-01, 9.699136E-01, 9.548285E-01, 9.397434E-01, 9.246593E-01, & 9.095741E-01, 8.944900E-01, 8.794069E-01, 8.643237E-01, 8.492406E-01, 8.341584E-01, & @@ -695,7 +696,7 @@ SUBROUTINE HCOIO_Read( HcoState, Lct, RC ) ! going to 72 levels. Otherwise, use MESSy (nbalasus, 8/24/2023). IF ( Lct%Dct%Dta%Levels == 0 ) THEN -#if defined( MODEL_CESM ) || defined( MODEL_WRF ) +#if defined( MODEL_CESM ) || defined( MODEL_WRF ) || defined( MODEL_GISS ) ! In WRF/CESM, IsModelLevel has a different meaning of "GEOS-Chem levels" ! because the models in WRF and CESM are user-defined and thus fixed input @@ -1350,7 +1351,7 @@ SUBROUTINE HCOIO_Read( HcoState, Lct, RC ) UseMESSy = .TRUE. ENDIF -#if defined( MODEL_CESM ) || defined( MODEL_WRF ) +#if defined( MODEL_CESM ) || defined( MODEL_WRF ) || defined( MODEL_GISS ) ! If in WRF or the CESM environment, the vertical grid is arbitrary. ! MESSy regridding ALWAYS has to be used. IF ( nlev > 1 ) THEN @@ -1379,7 +1380,7 @@ SUBROUTINE HCOIO_Read( HcoState, Lct, RC ) CALL HCO_MSG(HcoState%Config%Err,MSG) ENDIF -#if !defined( MODEL_CESM ) && !defined( MODEL_WRF ) +#if !defined( MODEL_CESM ) && !defined( MODEL_WRF ) && !defined( MODEL_GISS ) ! If we do MESSy regridding, we can only do one time step ! at a time at the moment! IF ( tidx1 /= tidx2 ) THEN @@ -1394,7 +1395,7 @@ SUBROUTINE HCOIO_Read( HcoState, Lct, RC ) ! This has to be used for WRF-GC and CESM so ifdefd out #endif -#if defined( MODEL_WRF ) || defined( MODEL_CESM ) +#if defined( MODEL_WRF ) || defined( MODEL_CESM ) || defined( MODEL_GISS ) !-------------------------------------------------------------- ! Eventually get sigma levels ! For files that have hardcoded GEOS-Chem "index"-based levels, @@ -1487,7 +1488,7 @@ SUBROUTINE HCOIO_Read( HcoState, Lct, RC ) ENDIF ! nlev>1 -#if defined( MODEL_WRF ) || defined( MODEL_CESM ) +#if defined( MODEL_WRF ) || defined( MODEL_CESM ) || defined( MODEL_GISS ) ! Input data is "never" on model levels because model levels can change! (hplin, 5/29/20) IsModelLevel = .false. #endif diff --git a/src/Core/hcoio_write_std_mod.F90 b/src/Core/hcoio_write_std_mod.F90 index 14b7688f..3b88db57 100644 --- a/src/Core/hcoio_write_std_mod.F90 +++ b/src/Core/hcoio_write_std_mod.F90 @@ -1,9 +1,10 @@ !BOC -#if defined ( MODEL_GCCLASSIC ) || defined( MODEL_WRF ) || defined( MODEL_CESM ) || defined( HEMCO_STANDALONE ) +#if defined ( MODEL_GCCLASSIC ) || defined( MODEL_WRF ) || defined( MODEL_CESM )|| defined( MODEL_GISS ) || defined( HEMCO_STANDALONE ) ! The 'standard' HEMCO I/O module is used for: ! - HEMCO Standalone (HEMCO_STANDALONE) ! - GEOS-Chem 'Classic' (MODEL_GCCLASSIC) ! - WRF-GC (MODEL_WRF) +! - GISS-GC (MODEL_GISS) ! - CESM-GC and CAM-Chem / HEMCO-CESM (MODEL_CESM) !EOC !------------------------------------------------------------------------------ From ebd41774f5cd8717516fe4746056aea65f020be4 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Fri, 12 Jul 2024 16:51:54 -0400 Subject: [PATCH 02/14] Remove InvMEGAN manual diagnostics from hcox_megan_mod.F90 This commit addresses the issue in geoschem/HEMCO #281. src/Extensions/hcox_megan_mod.F90 - Removed the calls to Diagn_Create for InvMEGAN diagnostics. These can be activated by adding the proper entries to the HEMCO_Diagn.rc file. CHANGELOG.md - Updated accordingly Signed-off-by: Bob Yantosca --- CHANGELOG.md | 4 + src/Extensions/hcox_megan_mod.F90 | 243 ------------------------------ 2 files changed, 4 insertions(+), 243 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 59bd8676..c070e8d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file. 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 +### Removed +- Manual `InvMEGAN` diagnostics from `src/Extensions/hcox_megan_mod.F90`; Activate these with `HEMCO_Diagn.rc` instead + ## [3.9.1] - 2024-06-28 ### Fixed - Fixed formatting error in `.github/workflows/stale.yml` that caused the Mark Stale Issues action not to run diff --git a/src/Extensions/hcox_megan_mod.F90 b/src/Extensions/hcox_megan_mod.F90 index a3ade34e..708dd77d 100644 --- a/src/Extensions/hcox_megan_mod.F90 +++ b/src/Extensions/hcox_megan_mod.F90 @@ -4300,249 +4300,6 @@ SUBROUTINE HCOX_Megan_Init( HcoState, ExtName, ExtState, RC ) Inst%AEF_OCIM = 0.0_hp Inst%AEF_SABI = 0.0_hp - !================================================================= - ! Create manual diagnostics - !================================================================= - CALL Diagn_Create( HcoState = HcoState, & - cName = 'InvMEGAN_ACET_MBOX', & - ExtNr = ExtNr, & - Cat = -1, & - Hier = -1, & - HcoID = -1, & - SpaceDim = 2, & - OutUnit = 'kg/m2/s', & - AutoFill = 0, & - Trgt2D = Inst%FLUXACETmb, & - RC = RC ) - IF ( RC /= HCO_SUCCESS ) THEN - CALL HCO_ERROR( 'ERROR 45', RC, THISLOC=LOC ) - RETURN - ENDIF - - CALL Diagn_Create( HcoState = HcoState, & - cName = 'InvMEGAN_ACET_DIRECT',& - ExtNr = ExtNr, & - Cat = -1, & - Hier = -1, & - HcoID = -1, & - SpaceDim = 2, & - OutUnit = 'kg/m2/s', & - AutoFill = 0, & - Trgt2D = Inst%FLUXACETbg, & - RC = RC ) - IF ( RC /= HCO_SUCCESS ) THEN - CALL HCO_ERROR( 'ERROR 46', RC, THISLOC=LOC ) - RETURN - ENDIF - - CALL Diagn_Create( HcoState = HcoState, & - cName = 'InvMEGAN_APIN', & - ExtNr = ExtNr, & - Cat = -1, & - Hier = -1, & - HcoID = -1, & - SpaceDim = 2, & - OutUnit = 'kg/m2/s', & - AutoFill = 0, & - Trgt2D = Inst%FLUXAPIN, & - RC = RC ) - IF ( RC /= HCO_SUCCESS ) THEN - CALL HCO_ERROR( 'ERROR 47', RC, THISLOC=LOC ) - RETURN - ENDIF - - CALL Diagn_Create( HcoState = HcoState, & - cName = 'InvMEGAN_BPIN', & - ExtNr = ExtNr, & - Cat = -1, & - Hier = -1, & - HcoID = -1, & - SpaceDim = 2, & - OutUnit = 'kg/m2/s', & - AutoFill = 0, & - Trgt2D = Inst%FLUXBPIN, & - RC = RC ) - IF ( RC /= HCO_SUCCESS ) THEN - CALL HCO_ERROR( 'ERROR 48', RC, THISLOC=LOC ) - RETURN - ENDIF - - CALL Diagn_Create( HcoState = HcoState, & - cName = 'InvMEGAN_SABI', & - ExtNr = ExtNr, & - Cat = -1, & - Hier = -1, & - HcoID = -1, & - SpaceDim = 2, & - OutUnit = 'kg/m2/s', & - AutoFill = 0, & - Trgt2D = Inst%FLUXSABI, & - RC = RC ) - IF ( RC /= HCO_SUCCESS ) THEN - CALL HCO_ERROR( 'ERROR 49', RC, THISLOC=LOC ) - RETURN - ENDIF - - CALL Diagn_Create( HcoState = HcoState, & - cName = 'InvMEGAN_MYRC', & - ExtNr = ExtNr, & - Cat = -1, & - Hier = -1, & - HcoID = -1, & - SpaceDim = 2, & - OutUnit = 'kg/m2/s', & - AutoFill = 0, & - Trgt2D = Inst%FLUXMYRC, & - RC = RC ) - IF ( RC /= HCO_SUCCESS ) THEN - CALL HCO_ERROR( 'ERROR 50', RC, THISLOC=LOC ) - RETURN - ENDIF - - CALL Diagn_Create( HcoState = HcoState, & - cName = 'InvMEGAN_CARE', & - ExtNr = ExtNr, & - Cat = -1, & - Hier = -1, & - HcoID = -1, & - SpaceDim = 2, & - OutUnit = 'kg/m2/s', & - AutoFill = 0, & - Trgt2D = Inst%FLUXCARE, & - RC = RC ) - IF ( RC /= HCO_SUCCESS ) THEN - CALL HCO_ERROR( 'ERROR 51', RC, THISLOC=LOC ) - RETURN - ENDIF - - CALL Diagn_Create( HcoState = HcoState, & - cName = 'InvMEGAN_OCIM', & - ExtNr = ExtNr, & - Cat = -1, & - Hier = -1, & - HcoID = -1, & - SpaceDim = 2, & - OutUnit = 'kg/m2/s', & - AutoFill = 0, & - Trgt2D = Inst%FLUXOCIM, & - RC = RC ) - IF ( RC /= HCO_SUCCESS ) THEN - CALL HCO_ERROR( 'ERROR 52', RC, THISLOC=LOC ) - RETURN - ENDIF - - CALL Diagn_Create( HcoState = HcoState, & - cName = 'InvMEGAN_OMON', & - ExtNr = ExtNr, & - Cat = -1, & - Hier = -1, & - HcoID = -1, & - SpaceDim = 2, & - OutUnit = 'kg/m2/s', & - AutoFill = 0, & - Trgt2D = Inst%FLUXOMON, & - RC = RC ) - IF ( RC /= HCO_SUCCESS ) THEN - CALL HCO_ERROR( 'ERROR 53', RC, THISLOC=LOC ) - RETURN - ENDIF - - CALL Diagn_Create( HcoState = HcoState, & - cName = 'InvMEGAN_FARN', & - ExtNr = ExtNr, & - Cat = -1, & - Hier = -1, & - HcoID = -1, & - SpaceDim = 2, & - OutUnit = 'kg/m2/s', & - AutoFill = 0, & - Trgt2D = Inst%FLUXFARN, & - RC = RC ) - IF ( RC /= HCO_SUCCESS ) THEN - CALL HCO_ERROR( 'ERROR 54', RC, THISLOC=LOC ) - RETURN - ENDIF - - CALL Diagn_Create( HcoState = HcoState, & - cName = 'InvMEGAN_BCAR', & - ExtNr = ExtNr, & - Cat = -1, & - Hier = -1, & - HcoID = -1, & - SpaceDim = 2, & - OutUnit = 'kg/m2/s', & - AutoFill = 0, & - Trgt2D = Inst%FLUXBCAR, & - RC = RC ) - IF ( RC /= HCO_SUCCESS ) THEN - CALL HCO_ERROR( 'ERROR 55', RC, THISLOC=LOC ) - RETURN - ENDIF - - CALL Diagn_Create( HcoState = HcoState, & - cName = 'InvMEGAN_OSQT', & - ExtNr = ExtNr, & - Cat = -1, & - Hier = -1, & - HcoID = -1, & - SpaceDim = 2, & - OutUnit = 'kg/m2/s', & - AutoFill = 0, & - Trgt2D = Inst%FLUXOSQT, & - RC = RC ) - IF ( RC /= HCO_SUCCESS ) THEN - CALL HCO_ERROR( 'ERROR 56', RC, THISLOC=LOC ) - RETURN - ENDIF - - CALL Diagn_Create( HcoState = HcoState, & - cName = 'InvMEGAN_MBOX', & - ExtNr = ExtNr, & - Cat = -1, & - Hier = -1, & - HcoID = -1, & - SpaceDim = 2, & - OutUnit = 'kg/m2/s', & - AutoFill = 0, & - Trgt2D = Inst%FLUXMBOX, & - RC = RC ) - IF ( RC /= HCO_SUCCESS ) THEN - CALL HCO_ERROR( 'ERROR 57', RC, THISLOC=LOC ) - RETURN - ENDIF - - CALL Diagn_Create( HcoState = HcoState, & - cName = 'InvMEGAN_FAXX', & - ExtNr = ExtNr, & - Cat = -1, & - Hier = -1, & - HcoID = -1, & - SpaceDim = 2, & - OutUnit = 'kg/m2/s', & - AutoFill = 0, & - Trgt2D = Inst%FLUXFAXX, & - RC = RC ) - IF ( RC /= HCO_SUCCESS ) THEN - CALL HCO_ERROR( 'ERROR 58', RC, THISLOC=LOC ) - RETURN - ENDIF - - CALL Diagn_Create( HcoState = HcoState, & - cName = 'InvMEGAN_AAXX', & - ExtNr = ExtNr, & - Cat = -1, & - Hier = -1, & - HcoID = -1, & - SpaceDim = 2, & - OutUnit = 'kg/m2/s', & - AutoFill = 0, & - Trgt2D = Inst%FLUXAAXX, & - RC = RC ) - IF ( RC /= HCO_SUCCESS ) THEN - CALL HCO_ERROR( 'ERROR 59', RC, THISLOC=LOC ) - RETURN - ENDIF - !================================================================= ! Initialize internal diagnostics. These are the restart variables ! that can be used for a 'warm' start of MEGAN. From cc2e555f42a2e587ad85320afc1c6d08fa485fc1 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 15 Jul 2024 14:30:18 -0400 Subject: [PATCH 03/14] RTD update: Fix typos in hco-ref-guide/hemco-config.rst docs/source/hco-config - Fixed a few broken :literal: tags CHANGELOG.md - Updated accordingly Signed-off-by: Bob Yantosca --- CHANGELOG.md | 4 ++++ docs/source/hco-ref-guide/hemco-config.rst | 6 +++--- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 59bd8676..c4b5db4b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] - TBD +### Fixed +- Typos in RTD doc file `docs/source/hco_ref_guide/hemco-config.rst` + ## [3.9.1] - 2024-06-28 ### Fixed - Fixed formatting error in `.github/workflows/stale.yml` that caused the Mark Stale Issues action not to run diff --git a/docs/source/hco-ref-guide/hemco-config.rst b/docs/source/hco-ref-guide/hemco-config.rst index 876a9b02..4cda0293 100644 --- a/docs/source/hco-ref-guide/hemco-config.rst +++ b/docs/source/hco-ref-guide/hemco-config.rst @@ -971,7 +971,7 @@ are: Data interpolation also works between multiple files. For instance, if monthly data are stored in files - :literal`file_200501.nc`, :file:`file_200502.nc`, etc., a + :literal:`file_200501.nc`, :file:`file_200502.nc`, etc., a combination of source file name :file:`file_$YYYY$MM.nc` and :option:`sourceTime` attribute :literal:`2005-2007/1-12/1-31/0 :literal:I` will result in daily data interpolation between the two @@ -1008,7 +1008,7 @@ are: The :option:`SrcDim` attribute can also be used to indicate the level into which 2D data shall be released by setting the - vertical coordinate to `:literal:`LX```, with :literal:`X` being + vertical coordinate to :literal:`LX`, with :literal:`X` being the release level. For instance, to emit a 2D field into level 5, set :option:`SrcDim` to :literal:`xyL5`. @@ -1336,7 +1336,7 @@ switches. Only fields that are part of an enabled collection will be used by HEMCO. The beginning and end of a collection is indicated by an opening and -closing bracket, respectively: :literal:(((CollectionName` and +closing bracket, respectively: :literal:`(((CollectionName` and :literal:`)))CollectionName`. These brackets must be on individual lines immediately preceeding / following the first/last entry of a collection. The same collection bracket can be used as many times as needed. From 076884cd76d3a615fb446b8595133328ca3a9129 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 17 Jul 2024 19:24:03 -0400 Subject: [PATCH 04/14] RTD Updates: Convert several :option" tags to subsections In order to make the HEMCO documentation easier to navigate, we have done the following: 1. Converted several :option: tags to subsections, with named anchors. These will show up in the table of contents in the left nav bar. 2. Updated references to the new subsections accordingly. 3. Updated pages for clarity. In several locations, use tables instead of descriptive paragraph to describe options and the behaviors they toggle. 4. Fixed indentation and trimmed trailing whitespace. Signed-off-by: Bob Yantosca --- CHANGELOG.md | 3 + docs/source/hco-ref-guide/basic-examples.rst | 17 +- docs/source/hco-ref-guide/diagnostics.rst | 145 +- docs/source/hco-ref-guide/extensions.rst | 299 +-- docs/source/hco-ref-guide/hemco-config.rst | 1926 +++++++++-------- .../hco-ref-guide/input-file-format.rst | 87 +- docs/source/hco-ref-guide/known-bugs.rst | 6 +- docs/source/hco-ref-guide/more-examples.rst | 130 +- docs/source/hco-ref-guide/under-the-hood.rst | 20 +- docs/source/hco-ref-guide/units.rst | 56 +- docs/source/hco-sa-guide/config-sim.rst | 4 +- 11 files changed, 1449 insertions(+), 1244 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c4b5db4b..a35bda90 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] - TBD +### Changed +- RTD updates: Converted several `:option:` tags to subsections and updated references accordingly + ### Fixed - Typos in RTD doc file `docs/source/hco_ref_guide/hemco-config.rst` diff --git a/docs/source/hco-ref-guide/basic-examples.rst b/docs/source/hco-ref-guide/basic-examples.rst index 0f18ccc6..968b3737 100644 --- a/docs/source/hco-ref-guide/basic-examples.rst +++ b/docs/source/hco-ref-guide/basic-examples.rst @@ -187,9 +187,9 @@ changed since :ref:`the previous example `. Note the increased hierarchy (:literal:`2`) of the regional EMEP inventory compared to the global MACCity emissions (:literal:`1`) in -column :option:`Hier`. This will cause the EMEP emissions to replace -the MACCity emissions in the region where EMEP is defined, which is -specified by the MASK_EUROPE variable. +column :ref:`hco-cfg-base-hier`. This will cause the EMEP emissions to +replace the MACCity emissions in the region where EMEP is defined, +which is specified by the MASK_EUROPE variable. .. _edit-hco-cfg-ex3: @@ -232,9 +232,10 @@ modify the :ref:`configuration file ` accordingly: ### END SECTION BASE EMISSIONS ### -Note the change in the emission category (column :option:`Cat`) from -:literal:`1` to :literal:`2`. In this example, category 1 represents -anthropogenic emissions and category 2 represents aircraft emissions. +Note the change in the emission category (column +:ref:`hco-cfg-base-cat`) from :literal:`1` to :literal:`2`. In this +example, category 1 represents anthropogenic emissions and category 2 +represents aircraft emissions. .. _edit-hco-cfg-ex4: @@ -251,8 +252,8 @@ implemented as a HEMCO Extension, can be added to the simulation by: Emissions**. The extension number defined in the **Extension Switches** section -must match the corresponding :option:`ExtNr` entry in the Base -Emissions section (in this example, :literal:`111`). +must match the corresponding :ref:`hco-cfg-ext-switches-extnr` entry +in the Base Emissions section (in this example, :literal:`111`). .. code-block:: kconfig diff --git a/docs/source/hco-ref-guide/diagnostics.rst b/docs/source/hco-ref-guide/diagnostics.rst index b07302c0..6f067fb7 100644 --- a/docs/source/hco-ref-guide/diagnostics.rst +++ b/docs/source/hco-ref-guide/diagnostics.rst @@ -13,9 +13,9 @@ Overview HEMCO diagnostics are organized in **collections**, with each collection consisting of a dynamic number of diagnostic fields (aka **diagnostic containers**). Each collection has a fixed output -frequency (:option:`DiagnFreq`) assigned to it. All fields within a -collection are written out at the same interval: :option:`Hourly`, -:option:`Daily`, etc. +frequency (:ref:`hco-cfg-set-diagnfreq`) assigned to it. All fields +within a collection are written out at the same interval: +:literal:`Hourly`, :literal:`Daily`, etc. The contents of a collection (i.e. the diagnostics containers) are defined at the beginning of a simulation and become continuously updated @@ -39,21 +39,17 @@ averaging method. Currently supported averaging methods are: -.. option:: instantaneous - - Instantaneous values (recommended method). - -.. option:: mean - - Arithmetic mean over the diagnostic interval. - -.. option:: sum - - Total sum over the diagnostic interval. - -.. option:: cumulsum - - Cumulative sum since simulation start. ++-------------------+------------------------------------------------+ +| Value | What it does | ++===================+================================================+ +| ``instantaneous`` | Instantaneous values (recommended method). | ++-------------------+------------------------------------------------+ +| ``mean`` | Arithmetic mean over the diagnostic interval. | ++-------------------+------------------------------------------------+ +| ``sum`` | Total sum over the diagnostic interval. | ++-------------------+------------------------------------------------+ +| ``cumulsum`` | Cumulative sum since simulation start. | ++-------------------+------------------------------------------------+ Explicitly setting the averaging method will disable automatic unit conversion and the fields passed to this diagnostic will be stored as @@ -87,20 +83,19 @@ The Default collection The **Default** collection contains emission diagnostics intended to be written to disk, e.g. for analysis purposes. All fields of the default collection are written out at the frequency provided in -setting :option:`DiagnFreq` in the settings section of the HEMCO -configuration file. The name of the corresponding diagnostics files -can be specified via the :code:`DiagnPrefix` setting. The simulation -date at the time of output will be appended to the diagnostics prefix, -e.g. the diagnostics for Aug 1, 2008 will be written as -:file:`HEMCO_Diagnostics.200808010000.nc`. The datetime can denote -the beginning, middle, or end (default) of the time interval, as -specified by setting :option:`DiagnTimeStamp` (see below). - -Several :ref:`options for the default diagnostic collection -` can be specified at the top of the -:ref:`HEMCO configuration file ` file. Commonly-used options -are :option:`DiagnFile`, :option:`DiagnFreq`, and -:option:`DiagnPrefix`. +setting :ref:`hco-cfg-set-diagnfreq` in the settings section of the +HEMCO configuration file. The name of the corresponding diagnostics files +can be specified via the :ref:`hco-cfg-set-diagnprefix` setting. The +simulation date at the time of output will be appended to the +diagnostics prefix, e.g. the diagnostics for Aug 1, 2008 will be +written as :file:`HEMCO_Diagnostics.200808010000.nc`. The datetime +can denote the beginning, middle, or end (default) of the time +interval, as specified by setting ::ref:`hco-cfg-set-diagntimestamp`. + +Several options for the default diagnostic collection can be specified +at the top of the :ref:`HEMCO configuration file ` file. +Commonly-used options are :ref:`hco-cfg-set-diagnfile`, +:ref:`hco-cfg-set-diagnfreq`, and :ref:`hco-cfg-set-diagnprefix`. .. _hco-diag-configfile: @@ -108,7 +103,7 @@ Configuration file for the Default collection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You may specify the name of the Default diagnostics configuration file -with the :option:`DiagnFile` option in :ref:`the +with the :ref:`hco-cfg-set-diagnfile` option in :ref:`the HEMCO configuration file `. This file, which is customarily named :file:`HEMCO_Diagn.rc`, uses the following format: @@ -119,50 +114,34 @@ named :file:`HEMCO_Diagn.rc`, uses the following format: The columns of :file:`HEMCO_Diagn.rc` allow you to specify several options: -.. option:: Name - - netCDF variable name under which this diagnostic quantity will be - named in the HEMCO diagnostic output files. - -.. option:: Spec - - Species short name (same as in :ref:`the HEMCO configuration file - `) . - -.. option:: ExtNr - - Extension number (same as in :ref:`the HEMCO configuration file - `) . - - The :literal:`-1` value means to sum over all extensions. - -.. option:: Cat - - Category (same as in :ref:`the HEMCO configuration file - `). - - The :literal:`-1` value means to sum over all categories. - -.. option:: Hier - - Hierarchy (same as in :ref:`the HEMCO configuration file - `). - - The :literal:`-1` value means to sum over all categories. - -.. option:: Dim - - Number of dimensions that you wish this diagnostic to have: - - - :literal:`1`: Scalar - - :literal:`2`: Lat-lon or X-Y - - :literal:`3`: Lat-lon-lev or X-Y-Z - -.. option:: LongName - - A longer descriptive name for the diagnostic. This will be used to - define the netCDF :literal:`long_name` variable attribute in the - HEMCO diagnostic files. ++---------------+------------------------------------------------------------------+ +| Option | What it does | ++===============+==================================================================+ +| ``Name`` | netCDF variable name under which this diagnostic quantity will | +| | stored in the HEMCO diagnostic output files. | ++---------------+------------------------------------------------------------------+ +| ``Spec`` | :ref:`Species short name ` as listed in | +| | :ref:`the HEMCO configuration file `. | ++---------------+------------------------------------------------------------------+ +| ``ExtNr`` | :ref:`Extension number `. | +| | The :literal:`-1` value means to sum over all extensions. | ++---------------+------------------------------------------------------------------+ +| ``Cat`` | :ref:`Emission Category `. | +| | The :literal:`-1` value means to sum over all categories. | ++---------------+------------------------------------------------------------------+ +| ``Hier`` | :ref:`Emission Hierarchy `. | +| | The :literal:`-1` value means to sum over all hierarchies. | ++---------------+------------------------------------------------------------------+ +| ``Dim`` | Number of dimensions that you wish this diagnostic to have: | +| | | +| | - :literal:`1`: Scalar | +| | - :literal:`2`: Lat-lon or X-Y | +| | - :literal:`3`: Lat-lon-lev or X-Y-Z | ++---------------+------------------------------------------------------------------+ +| ``LongName`` | A longer descriptive name for the diagnostic. This will define | +| | the netCDF :literal:`long_name` variable attribute in the | +| | HEMCO diagnostic files. | ++---------------+------------------------------------------------------------------+ Here are a few examples. @@ -170,7 +149,7 @@ Here are a few examples. Adding these entries to :file:`HEMCO_Config.rc` will make HEMCO write out total NO and CO emissions, as well as GFED biomass burning CO - emissions (e.g. only emissions from :option:`ExtNr` 111): + emissions (e.g. only emissions from :ref:`hco-cfg-ext-switches-extnr` 111): .. code-block:: kconfig @@ -182,10 +161,10 @@ Here are a few examples. #. **Archive diagnostics for regional emissions** - To diagnose regional emissions, you must set :option:`ExtNr`, - :option:`Cat`, and :option:`Hier` accordingly. The example below - defines a diagnostic entry for CO emissions from the EPA16 USA - inventory: + To diagnose regional emissions, you must set + :ref:`hco-cfg-ext-switches-extnr`, :ref:`hco-cfg-base-cat`, and + :ref:`hco-cfg-base-hier` accordingly. The example below defines + a diagnostic entry for CO emissions from the EPA16 USA inventory: .. code-block:: kconfig @@ -262,7 +241,7 @@ Importing diagnostic content into an external model The content of the :ref:`Default collection ` can be specified through the HEMCO diagnostics definitions file (specified -by the :option:`DiagnFile` option). +by the :ref:`hco-cfg-set-diagnfile` option). The content of the :ref:`Manual ` and :ref:`Restart ` collections currently need to diff --git a/docs/source/hco-ref-guide/extensions.rst b/docs/source/hco-ref-guide/extensions.rst index be08701c..19e10875 100644 --- a/docs/source/hco-ref-guide/extensions.rst +++ b/docs/source/hco-ref-guide/extensions.rst @@ -28,143 +28,187 @@ selected individually in the :ref:`Extension Switches ` section of the :ref:`hco-cfg`, as can the species to be considered. -.. option:: DustAlk +.. _hco-ext-list-dustalk: - - **Species**: DSTAL1, DSTAL2, DSTAL3, DSTAL4 - - **Reference**: Fairlie et al (check) +DustAlk +------- -.. option:: DustDead +- **Species**: DSTAL1, DSTAL2, DSTAL3, DSTAL4 +- **Reference**: Fairlie et al (check) - Emissions of mineral dust from the DEAD dust mobilization model. +.. _hco-ext-list-dustdead: - - **Species**: DST1, DST2, DST3, DST4 - - **Reference**: :cite:t:`Zender_et_al._2003` +DustDead +-------- -.. option:: DustGinoux +Emissions of mineral dust from the DEAD dust mobilization model. - Emissions of mineral dust from the P. Ginoux dust mobilization model. +- **Species**: DST1, DST2, DST3, DST4 +- **Reference**: :cite:t:`Zender_et_al._2003` - - **Species**: DST1, DST2, DST3, DST4 - - **Reference**: :cite:t:`Ginoux_et_al._2001` +.. _hco-ext-list-dustginoux: -**Species**: DST1, DST2, DST3, DST4 - - **Reference**: :cite:t:`Ginoux_et_al._2001` +DustGinoux +---------- -.. option:: GC_Rn-Pb-Be +Emissions of mineral dust from the P. Ginoux dust mobilization model. - Emissions of radionuclide species as used in the `GEOS-Chem - `_ model. +- **Species**: DST1, DST2, DST3, DST4 +- **Reference**: :cite:t:`Ginoux_et_al._2001` - - **Species**: Rn222, Be7, Be7Strat, Be10, Be10Strat +.. _hco-ext-list-gcrnpbbe: - .. option:: ZHANG_Rn222 +GC_Rn-Pb-Be +----------- - If :option:`ZHANG_Rn222` is :literal:`on`, then Rn222 emissions - will be computed according to :cite:t:`Zhang_et_al._2021`. +Emissions of radionuclide species as used in the `GEOS-Chem +`_ model. - If :option:`ZHANG_Rn222` is :literal:`off`, then Rn222 emissions - will be computed according to :cite:t:`Jacob_et_al._1997`. +- **Species**: Rn222, Be7, Be7Strat, Be10, Be10Strat -.. option:: GFED +If :literal:`ZHANG_Rn222` is :literal:`on`, then Rn222 emissions + will be computed according to :cite:t:`Zhang_et_al._2021`. - Biomass burning emissions from the GFED model. +If :literal:`ZHANG_Rn222` is :literal:`off`, then Rn222 emissions +will be computed according to :cite:t:`Jacob_et_al._1997`. - - **Version**: GFED3 and GFED4 are available. - - **Species**: NO, CO, ALK4, ACET, MEK, ALD2, PRPE, C2H2, C2H4, C3H8, CH2O - C2H6, SO2, NH3, BCPO, BCPI, OCPO, OCPI, POG1, POG2, MTPA, BENZ, TOLU, XYLE - NAP, EOH, MOH, SOAP, and others - - :literal:`GFED_daily` option: Applies a daily scale factor to - emissions computed by GFED. - - :literal:`GFED_3hourly` option: Applies a consistent diurnal profile - for a given month (in 3-hr increments) to emissions computed by - GFED. This is the default setting. - - **Reference**: :cite:t:`van_der_Werf_et_al._2010` +.. _hco-ext-list-gfed: -.. option:: Inorg_Iodine +GFED +---- - - **Species**: HOI, I2 - - **Reference**: TBD +Biomass burning emissions from the GFED model. -.. option:: LightNOx +- **Version**: GFED3 and GFED4 are available. +- **Species**: NO, CO, ALK4, ACET, MEK, ALD2, PRPE, C2H2, C2H4, C3H8, CH2O + C2H6, SO2, NH3, BCPO, BCPI, OCPO, OCPI, POG1, POG2, MTPA, BENZ, TOLU, XYLE + NAP, EOH, MOH, SOAP, and others +- :literal:`GFED_daily` option: Applies a daily scale factor to + emissions computed by GFED. +- :literal:`GFED_3hourly` option: Applies a consistent diurnal profile + for a given month (in 3-hr increments) to emissions computed by + GFED. This is the default setting. +- **Reference**: :cite:t:`van_der_Werf_et_al._2010` - Emissions of NOx from lightning. +.. _hco-ext-list-finn: - - **Species**: NO - - **Species**: :cite:`Murray_et_al._2012` +FINN +---- -.. option:: MEGAN +Biomass burning from the FINN model (experimental). - Biogenic VOC emissions. +.. _hco-ext-list-inorg-iodine: - - **Version**: 2.1 - - **Species:** ISOP, ACET, PRPE, C2H4, ALD2, CO, OCPI, MONX, MTPA, MTPO, - LIMO, SESQ - - **Reference:** :cite:t:`Guenther_et_al._2012` +Inorg_Iodine +------------ -.. option:: PARANOx +- **Species**: HOI, I2 +- **Reference**: TBD - Plume model for ship emissions. +.. _hco-ext-list-lightnox: - - **Species**: NO, NO2, O3, HNO3 - - **Reference**: :cite:t:`Vinken_et_al._2011` +LightNOx +-------- -.. option:: SeaFlux +Emissions of NOx from lightning. - Air-sea exchange. +- **Species**: NO +- **Species**: :cite:`Murray_et_al._2012` - - Species: DMS, ACET, ALD2, MENO3, ETNO3, MOH - - References: :cite:t:`Johnson_2010`, :cite:t:`Nightingale_et_al._2000` +.. _hco-ext-list-megan: -.. option:: SeaSalt +MEGAN +----- - Sea salt aerosol emission. +Biogenic VOC emissions. - - **Species**: SALA, SALC, SALACL, SALCCL, SALAAL, SALCAL, BrSALA, - BrSALC, MOPO, MOPI - - **References**: :cite:t:`Jaegle_et_al._2011`, :cite:t:`Gong_2003` +- **Version**: 2.1 +- **Species:** ISOP, ACET, PRPE, C2H4, ALD2, CO, OCPI, MONX, MTPA, MTPO, + LIMO, SESQ +- **Reference:** :cite:t:`Guenther_et_al._2012` -.. option:: SoilNOx +.. _hco-ext-list-paranox: - Emissons of NOx from soils and fertilizers. +PARANOx +------- - - **Species**: NO - - **Reference**: :cite:t:`Hudman_et_al._2012` +Plume model for ship emissions. +- **Species**: NO, NO2, O3, HNO3 +- **Reference**: :cite:t:`Vinken_et_al._2011` -.. option:: Volcano +.. _hco-ext-list-seaflux: - Emissions of volcanic SO2 from AEROCOM. +SeaFlux +------- - - **Species**: SO2 - - **Reference**: +Air-sea exchange. +- Species: DMS, ACET, ALD2, MENO3, ETNO3, MOH +- References: :cite:t:`Johnson_2010`, :cite:t:`Nightingale_et_al._2000` -.. option:: TOMAS_Jeagle +.. _hco-ext-list-seasalt: - Size-resolved sea salt emissions for `TOMAS aerosol microphysics - `_ - simulations. +SeaSalt +------- - - **Species**: SS1, SS2, SS3, SS4, SS5, SS6, SS7, SS8, SS9, SS10, - SS11, SS12, SS13, SS14, SS15, SS16, SS17, SS18, SS19, SS20, SS21, - SS22, SS23, SS24, SS25, SS26, SS27, SS28, SS29, SS30, SS31, SS32, - SS33, SS34, SS35, SS36, SS37, SS38, SS39, SS40 - - **Reference**: :cite:t:`Jaegle_et_al._2011` +Sea salt aerosol emission. -.. option:: TOMAS_DustDead +- **Species**: SALA, SALC, SALACL, SALCCL, SALAAL, SALCAL, BrSALA, + BrSALC, MOPO, MOPI +- **References**: :cite:t:`Jaegle_et_al._2011`, :cite:t:`Gong_2003` - Size-resolved dust emissions for `TOMAS aerosol microphysics - `_ - simulations. +.. _hco-ext-list-soilnox: - - **Species**: DUST1, DUST2, DUST3, DUST4, DUST5, DUST6, DUST7, - DUST8, DUST9, DUST10, DUST11, DUST12, DUST13, DUST14, DUST15, - DUST16, DUST17, DUST18, DUST19, DUST20, DUST21, DUST22, DUST23, - DUST24, DUST25, DUST26, DUST27, DUST28, DUST29, DUST30, DUST31, - DUST32, DUST33, DUST34, DUST35, DUST36, DUST37, DUST38, DUST39, - DUST40 - - **Reference**: :cite:t:`Zender_et_al._2003` +SoilNOx +------- +Emissons of NOx from soils and fertilizers. + +- **Species**: NO +- **Reference**: :cite:t:`Hudman_et_al._2012` + +.. _hco-ext-list-tomas-jeagle: + +TOMAS_Jeagle +------------ + +Size-resolved sea salt emissions for `TOMAS aerosol microphysics +`_ +simulations. + +- **Species**: SS1, SS2, SS3, SS4, SS5, SS6, SS7, SS8, SS9, SS10, + SS11, SS12, SS13, SS14, SS15, SS16, SS17, SS18, SS19, SS20, SS21, + SS22, SS23, SS24, SS25, SS26, SS27, SS28, SS29, SS30, SS31, SS32, + SS33, SS34, SS35, SS36, SS37, SS38, SS39, SS40 +- **Reference**: :cite:t:`Jaegle_et_al._2011` + +.. _hco-ext-list-tomas-dustdead: + +TOMAS_DustDead +-------------- + +Size-resolved dust emissions for `TOMAS aerosol microphysics +`_ +simulations. + +- **Species**: DUST1, DUST2, DUST3, DUST4, DUST5, DUST6, DUST7, + DUST8, DUST9, DUST10, DUST11, DUST12, DUST13, DUST14, DUST15, + DUST16, DUST17, DUST18, DUST19, DUST20, DUST21, DUST22, DUST23, + DUST24, DUST25, DUST26, DUST27, DUST28, DUST29, DUST30, DUST31, + DUST32, DUST33, DUST34, DUST35, DUST36, DUST37, DUST38, DUST39, + DUST40 +- **Reference**: :cite:t:`Zender_et_al._2003` + +.. _hco-ext-list-volcano: + +Volcano +------- + +Emissions of volcanic SO2 from AEROCOM. + +- **Species**: SO2 +- **Reference**: .. _hco-ext-gridded-data: @@ -242,7 +286,7 @@ for use by the various extensions: - **Dim**: xyz - **Units**: kg - - **Used by**: :option:`GC_Rn-Pb-Be`, :option:`PARANOx` + - **Used by**: :ref:`hco-ext-list-gcrnpbbe`, :ref:`hco-ext-list-paranox` .. option:: AIRVOL @@ -250,7 +294,7 @@ for use by the various extensions: - **Dim**: xyz - **Units**: kg - - **Used by**: :option:`PARANOx` + - **Used by**: :ref:`hco-ext-list-paranox` .. option:: ALBD @@ -258,7 +302,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: unitless - - **Used by**: :option:`SoilNOx`, :option:`SeaFlux` + - **Used by**: :ref:`hco-ext-list-soilnox`, :ref:`hco-ext-list-seaflux` .. option:: CLDFRC @@ -266,7 +310,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: unitless - - **Used by**: :option:`MEGAN` + - **Used by**: :ref:`hco-ext-list-megan` .. option:: CNV_MFC @@ -274,7 +318,7 @@ for use by the various extensions: - **Dim**: xyz - **Units**: kg/m2/s - - **Used by**: :option:`LightNOx` + - **Used by**: :ref:`hco-ext-list-lightnox` .. option:: FRAC_OF_PBL @@ -282,7 +326,7 @@ for use by the various extensions: - **Dim**: xyz - **Units**: unitless - - **Used by**: :option:`PARANOx`, :option:`SeaFlux` + - **Used by**: :ref:`hco-ext-list-paranox`, :ref:`hco-ext-list-seaflux` .. option:: FRCLND @@ -290,7 +334,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: unitless - - **Used by**: :option:`GC_Rn-Pb-Be`, :option:`SeaFlux` + - **Used by**: :ref:`hco-ext-list-gcrnpbbe`, :ref:`hco-ext-list-seaflux` .. option:: GWETROOT @@ -299,7 +343,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: unitless - - **Used by**: :option:`MEGAN` + - **Used by**: :ref:`hco-ext-list-megan` .. option:: GWETTOP @@ -307,7 +351,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: unitless - - **Used by**: :option:`MEGAN` + - **Used by**: :ref:`hco-ext-list-megan` .. option:: HNO3 @@ -315,7 +359,7 @@ for use by the various extensions: - **Dim**: xyz - **Units**: kg - - **Used by**: :option:`PARANOx` + - **Used by**: :ref:`hco-ext-list-paranox` .. option:: JO1D @@ -323,7 +367,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: 1/s - - **Used by**: :option:`PARANOx` + - **Used by**: :ref:`hco-ext-list-paranox` .. option:: JNO2 @@ -331,7 +375,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: 1/s - - **Used by**: :option:`PARANOx` + - **Used by**: :ref:`hco-ext-list-paranox` .. option:: LAI @@ -339,7 +383,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: cm2 leaf/cm2 grid box - - **Used by**: :option:`MEGAN` + - **Used by**: :ref:`hco-ext-list-megan` .. option:: NO @@ -347,7 +391,7 @@ for use by the various extensions: - **Dim**: xyz - **Units**: kg - - **Used by**: :option:`PARANOx` + - **Used by**: :ref:`hco-ext-list-paranox` .. option:: NO2 @@ -355,7 +399,7 @@ for use by the various extensions: - **Dim**: xyz - **Units**: kg - - **Used by**: :option:`PARANOx` + - **Used by**: :ref:`hco-ext-list-paranox` .. option:: O3 @@ -363,7 +407,7 @@ for use by the various extensions: - **Dim**: xyz - **Units**: kg - - **Used by**: :option:`PARANOx` + - **Used by**: :ref:`hco-ext-list-paranox` .. option:: PARDF @@ -371,7 +415,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: W/m2 - - **Used by**: :option:`MEGAN` + - **Used by**: :ref:`hco-ext-list-megan` .. option:: PARDR @@ -379,7 +423,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: W/m2 - - **Used by**: :option:`MEGAN` + - **Used by**: :ref:`hco-ext-list-megan` .. option:: RADSWG @@ -387,7 +431,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: W/m2 - - **Used by**: :option:`SoilNOx` + - **Used by**: :ref:`hco-ext-list-soilnox` .. option:: SNOWHGT @@ -395,7 +439,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: kg H2O/m2 - - **Used by**: :option:`DustDead`, :option:`TOMAS_DustDead` + - **Used by**: :ref:`hco-ext-list-dustdead`, :ref:`hco-ext-list-tomas-dustdead` .. option:: SPHU @@ -403,8 +447,8 @@ for use by the various extensions: - **Dim**: xyz - **Units**: kg H2O/kg air - - **Used by**: :option:`DustDead`, :option:`PARANOx`, - :option:`TOMAS_DustDead` + - **Used by**: :ref:`hco-ext-list-dustdead`, :ref:`hco-ext-list-paranox`, + :ref:`hco-ext-list-tomas-dustdead` .. option:: SZAFACT @@ -412,7 +456,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: unitless - - **Used by**: :option:`MEGAN` + - **Used by**: :ref:`hco-ext-list-megan` .. option:: TK @@ -420,8 +464,8 @@ for use by the various extensions: - **Dim**: xyz - **Units**: K - - **Used by**: :option:`DustDead`, :option:`LightNOx`, - :option:`TOMAS_DustDead` + - **Used by**: :ref:`hco-ext-list-dustdead`, :ref:`hco-ext-list-lightnox`, + :ref:`hco-ext-list-tomas-dustdead` .. option:: TROPP @@ -429,7 +473,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: Pa - - **Used by**: :option:`GC_Rn-Pb-Be`, :option:`LightNOx` + - **Used by**: :ref:`hco-ext-list-gcrnpbbe`, :ref:`hco-ext-list-lightnox` .. option:: TSKIN @@ -437,7 +481,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: K - - **Used by**: :option:`SeaFlux`, :option:`SeaSalt` + - **Used by**: :ref:`hco-ext-list-seaflux`, :ref:`hco-ext-list-seasalt` .. option:: U10M @@ -445,10 +489,11 @@ for use by the various extensions: - **Dim**: xy - **Units**: m/s - - **Used by**: :option:`DustAlk`, :option:`DustDead`, - :option:`DustGinoux`, :option:`PARANOx`, :option:`SeaFlux`, - :option:`SeaSalt`, :option:`SoilNOx`, :option:`TOMAS_DustDead`, - :option:`TOMAS_Jeagle` + - **Used by**: :ref:`hco-ext-list-dustalk`, :ref:`hco-ext-list-dustdead`, + :ref:`hco-ext-list-dustginoux`, :ref:`hco-ext-list-paranox`, + :ref:`hco-ext-list-seaflux`, :ref:`hco-ext-list-seasalt`, + :ref:`hco-ext-list-soilnox`, :ref:`hco-ext-list-tomas-dustdead`, + :ref:`hco-ext-list-tomas-jeagle` .. option:: USTAR @@ -456,7 +501,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: m/s - - **Used by**: :option:`DustDead`, :option:`TOMAS_DustDead` + - **Used by**: :ref:`hco-ext-list-dustdead`, :ref:`hco-ext-list-tomas-dustdead` .. option:: V10M @@ -464,10 +509,11 @@ for use by the various extensions: - **Dim**: xy - **Units**: m/s - - **Used by**: :option:`DustAlk`, :option:`DustDead`, - :option:`DustGinoux`, :option:`PARANOx`, :option:`SeaFlux`, - :option:`SeaSalt`, :option:`SoilNOx`, :option:`TOMAS_DustDead`, - :option:`TOMAS_Jeagle` + - **Used by**: :ref:`hco-ext-list-dustalk`, + :ref:`hco-ext-list-dustdead`, :ref:`hco-ext-list-dustginoux`, + :ref:`hco-ext-list-paranox`, :ref:`hco-ext-list-seaflux`, + :ref:`hco-ext-list-seasalt`, :ref:`hco-ext-list-soilnox`, + :ref:`hco-ext-list-tomas-dustdead`, :ref:`hco-ext-list-tomas-jeagle` .. option:: WLI @@ -484,7 +530,7 @@ for use by the various extensions: - **Dim**: xy - **Units**: m - - **Used by**: :option:`DustDead`, :option:`TOMAS_DustDead` + - **Used by**: :ref:`hco-ext-list-dustdead`, :ref:`hco-ext-list-tomas-dustdead` .. _hco-ext-rst-vars: @@ -585,7 +631,8 @@ Extensions supporting built-in scaling/masking ============================================== The following extensions currently support the built-in scaling/masking -tools: :option:`SoilNOx`, :option:`GFED`, :option:`FINN`. +tools: :ref:`hco-ext-list-soilnox`, :ref:`hco-ext-list-gfed`, +:ref:`hco-ext-list-finn`. =========================== Adding new HEMCO extensions diff --git a/docs/source/hco-ref-guide/hemco-config.rst b/docs/source/hco-ref-guide/hemco-config.rst index 4cda0293..338499d7 100644 --- a/docs/source/hco-ref-guide/hemco-config.rst +++ b/docs/source/hco-ref-guide/hemco-config.rst @@ -9,7 +9,7 @@ The HEMCO configuration file ############################ The HEMCO Configuration file is composed of several sections: -:ref:`Settings `, +:ref:`Settings `, :ref:`Base Emissions `, :ref:`Scale Factors, `, and :ref:`Masks `. @@ -20,7 +20,7 @@ can be found in Figure 2 of :cite:t:`Lin_et_al._2021`: .. image:: ../_static/lin-et-al-2021-fig2.png :width: 600 -.. _hco-cfg-settings: +.. _hco-cfg-set: ======== Settings @@ -53,357 +53,418 @@ comment lines: ### END SECTION SETTINGS ### -The order within the settings section is irrelevant. Many of these -settings are optional, and default values will be used if not set. +The order within the settings section is irrelevant. Many of the +settings described below are optional, and default values will be used +if not explicitly set. + +.. _hco-cfg-set-diagnfile: + +DiagnFile +--------- + +Specifies the configuration file for the HEMCO default diagnostics +collection. This file is customarily named :file:`HEMCO_Diagn.rc`. +For more information, please see :ref:`Default +diagnostics collection ` section. + +.. _hco-cfg-set-diagnfreq: + +DiagnFreq +--------- + +This setting (located in the HEMCO configuration file) specifies +the output frequency of the :ref:`Default ` +collection. Allowable values are: + ++---------------------+------------------------------------------------+ +| Value | What it does | ++=====================+================================================+ +| ``Always`` | Archives diagnostics on each time step. | ++---------------------+------------------------------------------------+ +| ``Annually`` | Sets the diagnostic period to 1 year. | ++---------------------+------------------------------------------------+ +| ``Daily`` | Sets the diagnostic period to 1 day. | ++---------------------+------------------------------------------------+ +| ``End`` | Sets the diagnostic period so that output will | +| | only occur at the end of the simulation. | ++---------------------+------------------------------------------------+ +| ``Hourly`` | Sets the diagnostic period to 1 hour. | ++---------------------+------------------------------------------------+ +| ``Monthly`` | Sets the diagnostic period to 1 month | ++---------------------+------------------------------------------------+ +| ``YYYYMMDD hhmnss`` | Sets the diagnostic period to a 15-digit | +| | string (year-month-day hour-minute-second) | ++---------------------+------------------------------------------------+ + +Some examples of the :literal:`YYYMMDD hhmmss` option are: + +- :code:`00010000 000000` will generate diagnostic output once + per year. +- :code:`00000001 000000` will generate diagnostic output once + per day. +- :code:`00000000 020000` will generate diagnostic output every + 2 hours. +- etc. + +.. _hco-cfg-set-diagnolevdim: + +DiagNoLevDim +------------ + +This option must be explicity added to the HEMCO configuration +file. If omitted, the default behavior will be :code:`false`. + ++-----------+--------------------------------------------------------+ +| Value | What it does | ++===========+========================================================+ +| ``true`` | The :file:`HEMCO_diagnostics*.nc` files will be | +| | created with :literal:`(time,lat,lon)` dimensions. | +| | [#B]_ | ++-----------+--------------------------------------------------------+ +| ``false`` | The :file:`HEMCO_diagnostics*.nc` files will always | +| | be created with :literal:`(time,lev,lat,lon)` | +| | dimensions. | ++-----------+--------------------------------------------------------+ + +.. rubric:: Notes for DiagNoLevDim + +.. [#B] But if at least one of the diagnostic quantities has a + :literal:`lev` dimension, then the created files will have + :literal:`(time,lev,lat,lon)` dimensions. + +.. _hco-cfg-set-diagnprefix: + +DiagnPrefix +----------- + +Specifies the name of the diagnostic files to be created. For +example: -.. _hco-cfg-settings-general: - -General simulation settings ---------------------------- - -These settings control HEMCO simulation options. - - -.. option:: ROOT - - Root folder containing emissions inventories and other data to be - read by HEMCO. - -.. option:: METDIR - - Root folder of meteorology data files that are needed for HEMCO - extensions. Usually this is a subdirectory of :option:`ROOT`. - -.. option:: GCAPSCENARIO: - - Specifies the future scenario when using GCAP meteorology. - - Default value: :literal:`not used` - -.. option:: GCAPVERTRES - - Specifies the number of vertical levels for GCAP meteorology. - - Default value: :literal:`47` - -.. option:: MODEL - - If present, the :literal:`$MODEL` token will be set to the - value specified. - - If omitted, this value is determined based on compiler switches. - -.. option:: RES - - If present, the :literal:`$RES` token will be set to the value - specified. - - If omitted, this value is determined based on compiler switches. - -.. option:: LogFile - - Path and name of the output log file (which is typically named - :file:`HEMCO.log`). If set to the :option:`Wildcard` character, - all HEMCO output is written to **stdout** (i.e. the screen). - -.. option:: Unit tolerance - - Integer value denoting the tolerance against differences between - the units set in the :ref:`HEMCO configuration file ` - and data units found in the source file. Allowable values are" - - .. option:: 0 - - No tolerance. A units mismatch will halt a HEMCO simulation. - mismatch). - - .. option:: 1 - - Medium tolerance. A units mismatch will print a warning message - but not halt a HEMCO simulation. **(Default setting)** - - .. option:: 2 - - High tolerance. A units mismatch will be ignored. - -.. option:: Negative values - - Integer value that defines how negative values are handled. - - .. option:: 0 - - No negative values are allowed. **(Default setting)** - - .. option:: 1 - - All negative values are set to zero and a warning is given. - - .. option:: 2 - - Negative values are kept as they are. - -.. option:: Verbose - - Activates (:literal:`true`) or deactivates (:literal:`false`) - additional printout for debugging purposes. - - **Default setting**: :literal:`false` - -.. option:: VerboseOnCores - - Specifies whether :option:`Verbose` printout will be restricted to - the :literal:`root` core, or will be printed on :literal:`all` - cores. This facilitates running HEMCO in Earth System Models, - where the additional overhead of printing verbose output on every - core could negatively impact performance. - - **Default setting:** :literal:`root` +.. code-block:: kconfig -.. option:: Wildcard + DiagnPrefix: ./OutputDir/HEMCO_diagnostics - Wildcard character. On Unix/Linux, this should be set to :literal:`*`. +will create HEMCO diagnostics files in the :file:`OutputDir/` +subdirectory of the run directory, and all files will begin with +the text :file:`HEMCO_diagnostics`. -.. option:: Separator +.. _hco-cfg-set-diagnreftime: - Separator symbol. On Unix/4Linux systems, this should be set to - :literal:`/`. +DiagnRefTime +------------ -.. option:: Mask fractions +This option must be explicity added to the HEMCO configuration +file. - If :literal:`true`, the fractional mask values are taken - into account. This means that mask values can take any value - between 0.0 and 1.0. +By default, the value of the :literal:`time:units` attribute in the +:file:`HEMCO_diagnostics.*.nc` files will be - If :literal:`false`, masks are binary, and grid boxes are - 100% inside or outside of a mask region. +.. code-block:: kconfig - **Default setting:** :literal:`false` + hours since YYYY-MM-DD hh:mn:ss`, -.. option:: PBL dry deposition +where :literal:`YYYY-MM-DD hh:mn:ss` is the diagnostics datetime. +This default value can be overridden with: - If :literal:`true`, it is assumed that dry deposition occurs over - the entire boundary layer. In this case, extensions that include - loss terms (e.g. air-sea exchange) will calculate a loss term for - every grid box that is partly within the planetary boundary layer. +.. code-block:: console - If :literal:`false`, a loss term is calculated for the surface - layer only. + DiagnRefTime: hours since 1985-01-01 00:00:00 - **Default setting:** :literal:`false` +which will reset the :literal:`time:units` attribute in the +:file:`HEMCO_diagnostics*.nc` files accordingly. -.. _hco-cfg-settings-emissions: +.. _hco-cfg-set-diagntimestamp: -Emissions settings ------------------- +DiagnTimeStamp +-------------- -The following options can be used to hold emissions constant over a -year, month, day, or hour, and to scale emissions to a given value: +This option must be explicity added to the HEMCO configuration +file. If omitted, the default behavior will be :literal:`End`. -.. option:: Emission year ++-----------+--------------------------------------------------------+ +| Value | What it does | ++===========+========================================================+ +| ``Start`` | Uses the date and time at the start of the diagnostics | +| | period to timestamp diagnostic files. |br| | +| | |br| | +| | With this option, a 1-hour simulation from | +| | :code:`20220101 000000` to :code:`20220101 010000` | +| | will create a diagnostic file named | +| | :file:`HEMCO_Diagnostics.202201010000.nc`. | ++-----------+--------------------------------------------------------+ +| ``Mid`` | Uses the date and time at the midpoint of the | +| | diagnostics period to o timestamp diagnostic | +| | files. |br| | +| | |br| | +| | With this option, a 1-hour simulation from | +| | :code:`20220101 000000` to :code:`20220101 010000` | +| | will create a diagnostic file named | +| | :file:`HEMCO_Diagnostics.202201010030.nc`. | ++-----------+--------------------------------------------------------+ +| ``End`` | Uses the date and time at the end of the diagnostics | +| | period to timestamp diagnostic files. |br| | +| | |br| | +| | With this option, a 1-hour simulation from | +| | :code:`20220101 000000` to :code:`20220101 010000` | +| | will create a diagnostic file named | +| | :file:`HEMCO_Diagnostics.202201010100.nc`. | ++-----------+--------------------------------------------------------+ - If present, this emission year will be used regardless of the model - simulation year. +.. _hco-cfg-set-emission-day: - If omitted, the emission year will be set to the model simulation - year. +Emission day +------------ -.. option:: Emission month +If present, this emission day will be used regardless of the model +simulation day. If omitted, the emission day will be set to the model +simulation day. - If present, this emission month will be used regardless of the model - simulation month. +.. _hco-cfg-set-emission-hour: - If omitted, the emission month will be set to the model simulation - month. +Emission hour +------------- -.. option:: Emission day +If present, this emission month will be used regardless of the model +simulation hour. If omitted, the emisison month will be set to the +model simulation hour. - If present, this emission day will be used regardless of the model - simulation day. +.. _hco-cfg-set-emission-year: - If omitted, the emission day will be set to the model simulation - day. +Emission year +------------- -.. option:: Emission hour +If present, this emission year will be used regardless of the model +simulation year. If omitted, the emission year will be set to the +model simulation year. - If present, this emission month will be used regardless of the model - simulation hour. +.. _hco-cfg-set-emission-month: - If omitted, the emisison month will be set to the model simulation - hour. +Emission month +-------------- -.. option:: EmisScale_ +If present, this emission month will be used regardless of the model +simulation month. If omitted, the emission month will be set to the +model simulation month. - Optional argument to define a uniform scale factor that will be - applied across all inventories, categories, hierarchies, and - extensions. Can be set for every species individually, e.g. +.. _hco-cfg-set-emission-emisscale: - .. code-block:: kconfig +EmisScale_ +------------------------ - EmisScale_NO: 1.5 - EmisScale_CO: 2.0 +Optional argument to define a uniform scale factor that will be +applied across all inventories, categories, hierarchies, and +extensions. Examples: - Scales all NO emissions by 50% and doubles CO emissions. ++-----------------------+--------------------------------------+ +| Value | What it does | ++=======================+======================================+ +| ``EmisScale_NO: 1.5`` | Scales all NO emissions up by 50%. | ++-----------------------+--------------------------------------+ +| ``EmisScale_CO: 2.0`` | Scales all CO emissions up by 100%. | ++-----------------------+--------------------------------------+ -.. _hco-cfg-settings-diagnostics: +.. _hco-cfg-set-gcapscenario: -Diagnostics settings --------------------- +GCAPSCENARIO +------------ -The following options control archival of diagnostic quantities. For -more information about HEMCO diagnostics, please see the -:ref:`hco-diag` section. +Specifies the future scenario when using GCAP meteorology. Default +value: :literal:`not used` -.. option:: DiagnFile +.. _hco-cfg-set-gcapvertres: - Specifies the configuration file for the HEMCO default diagnostics - collection. This file is customarily named :file:`HEMCO_Diagn.rc`. - For more information, please see :ref:`Default - diagnostics collection ` section. +GCAPVERTRES +----------- -.. option:: DiagnFreq +Specifies the number of vertical levels for GCAP meteorology. Default +value: :literal:`47` - This setting (located in the HEMCO configuration file) specifies - the output frequency of the :ref:`Default ` - collection. Allowable values are: +.. _hco-cfg-set-gridfile: - .. option:: Always +GridFile +-------- - Archives diagnostics on each time step. +Path and name of the :ref:`HEMCO standalone ` grid +description file. This is usually named :file:`HEMCO_sa_Grid.rc`. - .. option:: Hourly +.. _hco-cfg-set-logfile: - Sets the diagnostic time period to 1 hour. +LogFile +------- - .. option:: Daily +Path and name of the output log file (which is typically named +:file:`HEMCO.log`). If set to the +:ref:`hco-cfg-set-wildcard` character, all HEMCO +output is written to **stdout** (i.e. the screen). - Sets the diagnostic time period to 1 day. +.. _hco-cfg-set-mask-fractions: - .. option:: Monthly +Mask fractions +-------------- - Sets the diagnostic time period to 1 hour. ++-----------+------------------------------------------------------+ +| Value | What it does | ++===========+======================================================+ +| ``true`` | Fractional mask values are taken into account. This | +| | means that mask values can take any value between | +| | 0.0 and 1.0. | ++-----------+------------------------------------------------------+ +| ``false`` | Masks are binary, and grid boxes are 100% inside or | +| | outside of a mask region. **(Default setting)** | ++-----------+------------------------------------------------------+ - .. option:: Annually +.. _hco-cfg-set-metdir: - Sets the diagnostic time period to 1 year. +METDIR +------ - .. option:: End +Root folder of meteorology data files that are needed for HEMCO +extensions. Usually this is a subdirectory of +:ref:`hco-cfg-set-root`. - Sets the diagnostic time period so that output will only happen - at the end of the simulation. +.. _hco-cfg-set-model: - .. option:: YYYYMMDD hhmnss +MODEL +----- - Sets the diagnostic time period to an interval specified by a - 15-digit string with year-month-day, hour-minute-second. For - example: +If present, the :literal:`$MODEL` token will be set to the +value specified. If omitted, this value is determined from compiler +switches. - - :code:`00010000 000000` will generate diagnostic output once - per year. - - :code:`00000001 000000` will generate diagnostic output once - per day. - - :code:`00000000 020000` will generate diagnostic output every - 2 hours. - - etc. +.. _hco-cfg-set-negative-values: -.. option:: DiagnPrefix +Negative values +--------------- - Specifies the name of the diagnostic files to be created. For - example: ++---------+-----------------------------------------------------------+ +| Value | What it does | ++=========+===========================================================+ +| ``0`` | No negative values are allowed **(Default setting)** | ++---------+-----------------------------------------------------------+ +| ``1`` | All negative values are set to zero and a warning | +| | message is printed. | ++---------+-----------------------------------------------------------+ +| ``2`` | Negative values are kept as they are. | ++---------+-----------------------------------------------------------+ - .. code-block:: +.. _hco-cfg-set-pbl-dry-deposition: - DiagnPrefix: ./OutputDir/HEMCO_diagnostics +PBL dry deposition +------------------ - will create HEMCO diagnostics files in the :file:`OutputDir/` - subdirectory of the run directory, and all files will begin with - the text :file:`HEMCO_diagnostics`. ++-----------+-----------------------------------------------------------+ +| Value | What it does | ++===========+===========================================================+ +| ``true`` | Assumes that dry deposition occurs over the entire | +| | planetary boundary layer (PBL). In this case, extensions | +| | that include loss terms (e.g. air-sea exchange) will | +| | calculate a loss term for every grid box that is partly | +| | within the PBL. | ++-----------+-----------------------------------------------------------+ +| ``false`` | A loss term is calculated for the surface layer only. | +| | **(Default setting)** | ++-----------+-----------------------------------------------------------+ -.. option:: DiagnRefTime +.. _hco-cfg-set-res: - This option must be explicity added to the HEMCO configuration - file. +RES +--- - By default, the value of the :literal:`time:units` attribute in the - :file:`HEMCO_diagnostics.*.nc` files will be :literal:`hours since - YYYY-MM-DD hh:mn:ss`, where :literal:`YYYY-MM-DD hh:mn:ss` is the - diagnostics datetime. This default value can be overridden and set - to a fixed datetime by setting :option:`DiagnRefTime` in the HEMCO - configuration file. For example: +If present, the :literal:`$RES` token will be set to the value +specified. If omitted, this value is determined from compiler +switches. - .. code-block:: console +.. _hco-cfg-set-root: - DiagnRefTime: hours since 1985-01-01 00:00:00 +ROOT +---- - will set the :literal:`time:units` attribute to :literal:`hours since - 1985-01-01 00:00:00`. +Root folder containing emissions inventories and other data to be +read by HEMCO. -.. option:: DiagNoLevDim +.. _hco-cfg-set-separator: - This option must be explicity added to the HEMCO configuration - file. If omitted, the default behavior will be :code:`false`. +Separator +--------- - If :literal:`true`, the created :file:`HEMCO_diagnostics*.nc` files - will contain dimensions :literal:`(time,lat,lon)`. But if at least - one of the diagnostic quantities has a :literal:`lev` dimension, - then the created files will have :literal:`(time,lev,lat,lon)` - dimensions. +Separator symbol. On Linux/MacOS systems, this should be set to +:literal:`/`. - If :literal:`false`, the :file:`HEMCO_diagnostics.*.nc` files will - always contain dimensions :literal:`(time,lev,lat,lon)`. +.. _hco-cfg-set-specfile: -.. option:: DiagnTimeStamp +SpecFile +-------- - This option must be explicity added to the HEMCO configuration - file. If omitted, the default behavior will be :option:`End`. +Path and name of the HEMCO standalone species description file. This +is usually named :file:`HEMCO_sa_Spec.rc`. - Allowable values are: +.. _hco-cfg-set-timefile: - .. option:: End +TimeFile +-------- - Uses the date and time at the end of the diagnostics time window - to timestamp diagnostic files. With this option, a 1-hour - simulation from :code:`20220101 000000` to :code:`20220101 - 010000` will create a diagnostic file named - :file:`HEMCO_Diagnostics.202201010100.nc`. +Path and name of the :ref:`HEMCO standalone ` time +description file. This is usually named :file:`HEMCO_sa_Time.rc`. - .. option:: Start +.. _hco-cfg-set-unit-tolerance: - Uses the date and time at the start of the diagnostics time - window to timestamp diagnostic files. With this option, a - 1-hour simulation from :code:`20220101 000000` to - :code:`20220101 010000` will create a diagnostic file named - :file:`HEMCO_Diagnostics.202201010000.nc`. +Unit tolerance +-------------- - .. option:: Mid +Integer value denoting the tolerance against differences between +the units set in the :ref:`HEMCO configuration file ` +and the netCDF :literal:`units` attribute found in the source file. - Uses the date and time at the midpoint of the diagnostics time - window to timestamp diagnostic files. With this option, a 1-hour - simulation from :code:`20220101 000000` to :code:`20220101 - 010000` will create a diagnostic file named - :file:`HEMCO_diagnostics.202201010030.nc`. ++---------+-----------------------------------------------------------+ +| Setting | What it does | ++=========+===========================================================+ +| ``0`` | **No tolerance**. A units mismatch will halt a HEMCO | +| | simulation. | ++---------+-----------------------------------------------------------+ +| ``1`` | **Medium tolerance**. A units mismatch will print a | +| | warning message, but will not halt a HEMCO simulation. | +| | **(Default setting)** | ++---------+-----------------------------------------------------------+ +| ``2`` | **High tolerance**. A units mismatch will be ignored. | ++---------+-----------------------------------------------------------+ -.. _hco-cfg-settings-standalone: +.. _hco-cfg-set-verbose: -HEMCO standalone simulation settings ------------------------------------- +Verbose +------- -In standalone mode, the three simulation description files also need be -specified: ++-----------+--------------------------------------------------------+ +| Value | What it does | ++===========+========================================================+ +| ``true`` | Activates additional printout for debugging purposes. | ++-----------+--------------------------------------------------------+ +| ``false`` | Deactivates additional printout. **(Default setting)** | ++-----------+--------------------------------------------------------+ -.. option:: GridFile +.. _hco-cfg-set-verboseoncores: - Path and name of the grid description file, which is usually named - :file:`HEMCO_sa_Grid.rc`. +VerboseOnCores +-------------- -.. option:: SpecFile ++----------+-----------------------------------------------------------+ +| Value | What it does | ++==========+===========================================================+ +| ``root`` | Restricts :ref:`hco-cfg-set-verbose` output to the | +| | root core. This facilitates running HEMCO in Earth | +| | System Models, where the additional overhead of printing | +| | verbose output on every core could negatively impact | +| | performance. **(Default setting)** | ++----------+-----------------------------------------------------------+ +| ``all`` | Prints :ref:`hco-cfg-set-verbose` output on all | +| | computational cores. | ++----------+-----------------------------------------------------------+ - Path and name of the species description file, which is usually named - :file:`HEMCO_sa_Spec.rc`. +.. _hco-cfg-set-wildcard: -.. option:: GridFile +Wildcard +-------- - Path and name of the time description file, which is usually named - :file:`HEMCO_sa_Time.rc`. +Wildcard character. On Linux/MacOS this should be set to :literal:`*`. .. _hco-cfg-settings-usrdef: @@ -426,9 +487,9 @@ tokens. .. important:: - User-defined token names must not contain numbers or - special characters such as :literal:`.`, :literal:`_`, - :literal:`-`, or :literal:`x`. + User-defined token names must not contain numbers or + special characters such as :literal:`.`, :literal:`_`, + :literal:`-`, or :literal:`x`. .. _hco-cfg-ext-switches: @@ -449,40 +510,56 @@ The first section of the configuration file lists all available extensions and whether they shall be used or not. For each extension, the following attributes need to be specified: -.. option:: ExtNr +.. _hco-cfg-ext-switches-extnr: + +ExtNr +----- + +Extension number associated with this field. All +:ref:`base emissions ` should have extension number +zero. The extension number` of the data listed in section +:ref:`hco-ext` data must match with the corresponding extension +number. - Extension number associated with this field. All - :ref:`base emissions ` should have extension number - zero. The extension number` of the data listed in section - :ref:`hco-ext` data must match with the corresponding extension - number. +The extension number can be set to the wildcard character. In that +case, the field is read by HEMCO (if the assigned species name +matches any of the HEMCO species, see :ref:`hco-cfg-base-species`) but +not used for emission calculation. This is particularly useful if +HEMCO is only used for data I/O but not for emission calculation. - The extension number can be set to the wildcard character. In that - case, the field is read by HEMCO (if the assigned species name - matches any of the HEMCO species, see :option:`Species` below) but - not used for emission calculation. This is particularly useful if - HEMCO is only used for data I/O but not for emission calculation. +.. _hco-cfg-ext-switches-extname: -.. option:: ExtName +ExtName +------- - Extension name. +Name of the HEMCO extension. -.. option:: Toggle +.. _hco-cfg-ext-switches-on-off: - If :literal:`on`, the extension will be used. +On/Off +------ - If :literal:`off`, the extension will not be used. ++---------+-----------------------------------+ +| Value | What it does | ++=========+===================================+ +| ``on`` | The extension will be used. | ++---------+-----------------------------------+ +| ``off`` | The extension will not be used. | ++---------+-----------------------------------+ -.. option:: Species +.. _hco-cfg-ext-switches-species: - List of species to be used by this extension. Multiple species are - separated by the :option:`Separator` symbol - (e.g. :literal:`/`). All listed species must be supported by the - given extension. +Species +------- - - For example, the soil NO emissions extension only supports one - species (NO). An error will be raised if additional species are - listed. +List of species to be used by this extension. Multiple species are +separated by the :ref:`hco-cfg-set-separator` symbol +(e.g. :literal:`/`). All listed species must be supported by the given +extension. + +- For example, the **SoilNOx** emissions extension only supports one + species (NO). An error will be raised if additional species are + listed. Additional extension-specific settings can also be specified in the 'Extensions Settings' section (see also an example in @@ -491,7 +568,7 @@ Additional extension-specific settings can also be specified in the extension definition. HEMCO expects an extension with extension number zero, denoted the -:ref:`base emisisons extension ` extension. All emission +:ref:`Base Emisisons extension ` extension. All emission fields linked to the base extension will be used for automatic emission calculation. Fields assigned to any other extension number will not be inlcuded in the base emissions calculation, but they are @@ -500,13 +577,14 @@ anywhere in the model code). These data are only read if the corresponding extension is enabled. All species to be used by HEMCO must be listed in column -:option:`Species` of the base extension switch. In particular, all -species used by any of the other extensions must also be listed as -base species, otherwise they will not be recognized. It is possible -(and recommended) to use the :option:`Wildcard` character, in which -case HEMCO automatically determines what species to use by matching -the atmospheric model species names with the species names assigned to -the base emission fields and/or any emission extension. +:ref:`hco-cfg-ext-switches-species` of the base extension switch. In +particular, all species used by any of the other extensions must also +be listed as base species, otherwise they will not be recognized. It +is possible (and recommended) to use the :ref:`hco-cfg-set-wildcard` +character, in which case HEMCO automatically determines what species +to use by matching the atmospheric model species names with the +species names assigned to the base emission fields and/or any emission +extension. The environmental fields (wind speed, temperature, etc.) required by the extensions are either passed from the atmospheric model or read through @@ -531,590 +609,641 @@ settings must be included between these comment lines: ### END SECTION BASE EMISSIONS ### -The :option:`ExtNr` field is defined in :ref:`hco-cfg-ext-switches`. - -Other attributes that need to be defined for each base emissions entry -are: - -.. option:: Name - - Descriptive field identification name. Two consecutive underscore - characters (:literal:`__`) can be used to attach a 'tag' to a - name. This is only of relevance if multiple base emission fields - share the same species, category, hierarchy, and scale factors. In - this case, emission calculation can be optimized by assigning field - names that onlydiffer by its tag to those fields - (e.g. :literal:`DATA__SECTOR1`, :literal:`DATA__SECTOR2`, etc.). - - For fields assigned to extensions other than the base extension - (:literal:`ExtNr = 0`), the field names are prescribed and must not - be modified because the data is identified by these extensions by - name. - -.. option:: sourceFile - - Path and name of the input file. - - Name tokens can be provided that become evaluated during - runtime. For example, to use the root directory specified in the - :ref:`Section settings section `, the - :literal:`$ROOT` token can be used. Similarly the token - :literal:`$CFDIR` refers to the location of the configuration - file. This allows users to reference data relative to the - location of the configuration file. For instance, if the - data is located in subfolder :literal:`data` of the same directory - as the configuration file, the file name can be set to - :literal:`$CFDIR/data/filename.nc`. - - Similarly, the **date tokens** :literal:`$YYYY`, :literal:`$MM`, - :literal:`$DD`, :literal:`$HH`, and :literal:`$MN` can be used to - refer to the the current valid year, month, day, hour, and - minute, respectively. These values are determined - from the current simulation datetime and the :option:`sourceTime` - specification for this entry. - - The tokens :literal:`$MODEL` and :literal:`$RES` refer to the - meteorological model (:option:`MODEL`) and resolution - (:option:`RES`). These tokens can be set explicitly in the settings - section. In `GEOS-Chem `_ they - are set to compiler-flag specific values if not set in the settings - section. Any token defined in the settings section can be used to - construct a part of the file name (see :ref:`hco-cfg-settings-usrdef`). - - As an alternative to an input file, **geospatial uniform values** - can directly be specified in the configuration file (see e.g. scale - factor :literal:`SO2toSO4` in :ref:`edit-hco-cfg`). If multiple - values are provided (separated by the separator character), they - are interpreted as different time slices. In this case, the - :option:`sourceTime` attribute can be used to specify the times - associated with the individual slices. If no time attribute is set, - HEMCO attempts to determine the time slices from the number of data - values: 7 values are interpreted as weekday (Sun, Mon, ..., Sat); 12 - values as month (Jan, ..., Dec); 24 values as hour-of-day (12am, - 1am, ..., 11pm). - - Uniform values can be combined with **mathematical expressions**, - e.g. to model a sine-wave emission source. Mathematical - expressions must be labeled :literal:`MATH:`, followed by - the expression, e.g. :literal:`MATH:2.0+sin(HH/12*PI)`. - - **Country-specific data** can be provided through an ASCII file - (:literal:`.txt`). In an ESMF environment you must specify the - absolute file path rather than use the $ROOT specifier. More - details on the country-specific data option are given in the - Input File Format section. - - If this entry is **left empty** (:literal:`-`), the filename from - the preceding entry is taken, and the next 5 attributes will be - ignored (see entry :literal:`MACCITY_SO4` in :ref:`edit-hco-cfg`. - -.. option:: sourceVar - - Source file variable of interest. Leave empty (:literal:`-`) if - values are directly set through the :option:`sourceFile` attribute - or if :option:`sourceFile` is empty. - -.. option:: sourceTime - - This attribute defines the time slices to be used and the data - refresh frequency. The format is - :literal:`year/month/day/hour`. Accepted are discrete dates for - time-independent data (e.g. :literal:`2000/1/1/0`) and time ranges - for temporally changing fields - (e.g. :literal:`1980-2007/1-12/1-31/0-23`). Data will automatically - become updated as soon as the simulation date enters a new time - interval. - - The provided time attribute determines the data refresh - frequency. It does not need to correspond to the datetimes of the - input file. - - - For example, if the input file contains daily data of - year 2005 and the time attribute is set to :literal:`2005/1/1/0`, - the file will be read just once (at the beginning of the - simulation) and the data of Jan 1, 2005 is used throughout the - simulation. |br| - |br| - - If the time attribute is set to :literal:`2005/1-12/1/0`, the - data is updated on every month, using the first day data of the - given month. For instance, if the simulation starts on July 15, - the data of July 1,2005 are used until August 1, at which point - the data will be refreshed to values from August 1, 2005. |br| - |br| - - A time attribute of :literal:`2005/1-12/1-31/0` will make - sure that the input data are refreshed daily to the current day's - data. |br| - |br| - - Finally, if the time attribute is set to - :literal:`2005/1-12/1-31/0-23`, the data file is read every - simulation hour, but the same daily data is used throughout the - day (since there are no hourly data in the file). Providing too - high update frequencies is not recommended unless the data - interpolation option is enabled (see below). - - If the provided time attributes do not match a datetime of the - input file, the **most likely** time slice is selected. The most - likely time slice is determined based on the specified source time - attribute, the datetimes available in the input file, and the - current simulation date. In most cases, this is just the closest - available time slice that lies in the past. - - - For example, if a file contains annual data from 2005 to 2010 and - the source time attribute is set to :literal:`2005-2010/1-12/1/0`, - the data of 2005 is used for all simulation months in 2005. |br| - |br| - - More complex datetime selections occur for files with - discontinuous time slices, e.g. a file with monthly data for - year 2005, 2010, 2020, and 2050. In this case, if the time - attribute is set to :literal:`2005-2020/1-12/1/0`, the monthly - values of 2005 are (re-)used for all years between 2005 and 2010, - the monthly values of 2010 are used for simulation years 2010 - - 2020, etc. - - It is possible to use tokens :literal:`$YYYY`, :literal:`$MM`, - :literal:`$DD`, and :literal:`$HH`, which will automatically be - replaced by the current simulation date. Weekly data (e.g. data - changing by the day of the week) can be indicated by setting the - day attribute to :literal:`WD` (the wildcard character will work, - too, but is not recommended). Weekly data needs to consist of at - least seven time slices - in increments of one day - representing - data for every weekday starting on Sunday. It is possible to store - multiple weekly data, e.g. for every month of a year: - :literal:`2000/1-12/WD/0`. These data must contain time slices for - the first seven days of every month, with the first day per month - representing Sunday data, then followed by Monday, - etc. (irrespective of the real weekdays of the given month). If the - wildcard character is used for the days, the data will be - interpreted if (and only if) there are exactly seven time - slices. See the Input File Format section for more details. Default - behavior is to interpret weekly data as 'local time', i.e. token - :literal:`WD` assumes that the provided values are in local - time. It is possible to use weekly data referenced to UTC time - using token :literal:`UTCWD`. - - Similar to the weekday option, there is an option to indicate - hourly data that represents local time: :literal:`LH`. If using - this flag, all hourly data of a given time interval (day, month, - year) are read into memory and the local hour is picked at every - location. A downside of this is that all hourly time slices in - memory are updated based on UTC time. For instance, if a file holds - local hourly data for every day of the year, the source time - attribute can be set to :literal:`2011/1-12/1-31/LH`. On every new - day (according to UTC time), this will read all 24 hourly time - slices of that UTC day and use those hourly data for the next 24 - hours. For the US, for instance, this results in the wrong daily - data being used for the last 6-9 hours of the day (when UTC time is - one day ahead of local US time). - - There is a difference between source time attributes - :literal:`2005-2008/$MM/1/0` and :literal:`2005-2008/1-12/1/0`. In - the first case, the file will be updated annually, while the update - frequency is monthly in the second case. The token :literal:`$MM` - simply indicates that the current simulation month shall be used - whenever the file is updated, but it doesn’t imply a refresh - interval. Thus, if the source time attribute is set to - :literal:`$YYYY/$MM/$DD/$HH`, the file will be read only once and - the data of the simulation start date is taken (and used throughout - the simulation). For uniform values directly set in the - configuration file, all time attributes but one must be fixed, - e.g. valid entries are :literal:`1990-2007/1/1/0` or - :literal:`2000/1-12/1/1`, but not :literal:`1990-2007/1-12/1/1`. - - .. note:: - - All data read from netCDF file are assumed to be in UTC time, - except for weekday data that are always assumed to be in local - time. Data read from the configuration file and/or from ASCII are - always assumed to be in local time. - - It is legal to keep different time slices in different files, - e.g. monthly data of multiple years can be stored in files - :file:`file_200501.nc`, :file:`file_200502.nc`, ..., - :file:`file_200712.nc`. By setting the source file attribute to - :file:`file_$YYYY$MM.nc` and the source time attribute to - :file:`2005-2007/1-12/1/0`, data of :file:`file_200501.nc` is used - for simulation dates of January 2005 (or any January of a previous - year), etc. The individual files can also contain only a subset of - the provided data range, e.g. all monthly files of a year can be - stored in one file: :file:`file_2005.nc`, :file:`file_2006.nc`, - :file:`file_2007.nc`. In this case, the source file name should be - set to :file:`file_$YYYY`, but the source time attribute should - still be :literal:`2005-2007/1-12/1/0` to indicate that the field - shall be updated monthly. - - This attribute can be set to the wildcard character (:literal:`*`), which - will force the file to be updated on every HEMCO time step. - - File reference time can be shifted by a fixed amount by adding an - optional fifth element to the time stamp attribute. For instance, - consider the case where 3-hourly averages are provided in - individual files with centered time stamps, e.g.: - :file:`file.yyyymmdd_0130z.nc`, :file:`file.yyyymmdd_0430z.nc`, - ..., :file:`file.yyymmdd_2230z.nc`. To read these files **at the - beginning of their time intervals**, the time stamp can be shifted by - 90 minutes: :literal:`2000-2016/1-12/1-31/0-23/+90minutes`. At - time 00z, HEMCO will then read file 0130z and keep using this file - until 03z, when it switches to file 0430z. Similarly, it is - possible to shift the file reference time by any number of years, - months, days, or hours. Time shifts can be forward or backward in - time (use :literal:`-` sign to shift backwards). - -.. option:: CRE - - Controls the time slice selection if the simulation date is outside - the range provided in attribute source time (see above). The - following options are available: - - .. option:: C - - **Cycling:** Data are interpreted asclimatology and recycled - once the end of the last time slice is reached. For instance, if - the input data contains monthly data of year 2000, and the - source time attribute is set to :literal:`2000/1-12/1/0 C`, the - same monthly data will be re-used every year. - - If the input data spans multiple years (e.g. monthly data from - 2000-2003), the closest available year will be used outside of - the available range (e.g. the monthly data of 2003 is used for - all simulation years after 2003). - - .. option:: CS - - **Cycling, Skip:** Data are interpreted as climatology and recycled - once the end of the last time slice is reached. Data that aren't - found are skipped. This is useful when certain fields aren't found - in a restart file and, in that case, those fields will be - initialized to default values. - - .. option:: CY - - **Cycling, Use Simulation Year:**, Same as :option:`C`, except - it does not allow :envvar:`Emission year` setting to override - the simulation year. - - .. option:: CYS - - **Cycling, Use Simulation Year, Skip:** Same as :option:`CS`, - except it does not allow :envvar:`Emission year` setting to - override the simulation year. - - .. option:: R - - **Range:** Data are only considered as long as the simulation - time is within the time range specified in attribute - :option:`sourceTime`. The provided range does not necessarily - need to match the time stamps of the input file. If it is - outside of the range of the netCDF time stamps, the closest - available date will be used. - - For instance, if a file contains data for years 2003 to 2010 and - the provided range is set to :literal:`2006-2010/1/1/0 R`, the - file will only be considered between simulation years - 2006-2010. For simulation years 2006 through 2009, the - corresponding field on the file is used. For all years beyond - 2009, data of year 2010 is used. If the simulation date is - outside the provided time range, the data is ignored but HEMCO - does not return an error---the field is simply treated as empty - (a corresponding warning is issued in the HEMCO log file). - - - Example: if the source time attribute is set to - :literal:`2000-2002/1-12/1/0 R`, the data will be used for - simulation years 2000 to 2002 and ignored for all other years. - - .. option:: RA - - **Range, Averaging Otherwise:** Combination of flags :option:`R` - and :option:`A`. As long as the simulation year is within the - specified year range, HEMCO will use just the data from that - particular year. As soon as the simulation year is outside the - specified year range, HEMCO will use the data averaged over the - specified years. - - - Consider the case where the emission file contains - monthly data for years 2005-2010. Setting the time attribute to - :literal:`2005-2010/1-12/1/0 R` will ensure that this data is - only used within simulation years 2005 to 2010 and ignored - outside of it. |br| - |br| +The :ref:`hco-cfg-ext-switches-extnr` field is defined in +:ref:`hco-cfg-ext-switches`. Other attributes that need to be defined +for each base emissions entry are: + +.. _hco-cfg-base-name: + +Name +---- + +Descriptive field identification name. Two consecutive underscore +characters (:literal:`__`) can be used to attach a 'tag' to a +name. This is only of relevance if multiple base emission fields +share the same species, category, hierarchy, and scale factors. In +this case, emission calculation can be optimized by assigning field +names that onlydiffer by its tag to those fields +(e.g. :literal:`DATA__SECTOR1`, :literal:`DATA__SECTOR2`, etc.). + +For fields assigned to extensions other than the base extension +(:literal:`ExtNr = 0`), the field names are prescribed and must not +be modified because the data is identified by these extensions by +name. + +.. _hco-cfg-base-sourcefile: + +sourceFile +---------- + +Specifies the path and name of the input file. You may include the +following **name tokens**, which will be evaluated at runtime. + ++------------+-----------------------------------------------------------------+ +| Value | What it does | ++============+=================================================================+ +| ``$CFDIR`` | Refers to the location of :ref:`hco-cfg`. | ++------------+-----------------------------------------------------------------+ +| ``$DD`` | Refers to the current simulation day (1-31). | ++------------+-----------------------------------------------------------------+ +| ``$HH`` | Refers to the current simulation hour (0-23). | ++------------+-----------------------------------------------------------------+ +| ``$MODEL`` | Refers to the :ref:`meteorological model `. | ++------------+-----------------------------------------------------------------+ +| ``$MM`` | Refers to the current simulation month (1-12). | ++------------+-----------------------------------------------------------------+ +| ``$MN`` | Refers to the current simulation minutes (0-59). | ++------------+-----------------------------------------------------------------+ +| ``$RES`` | Refers to the :ref:`model resolution `. | ++------------+-----------------------------------------------------------------+ +| ``$ROOT`` | Use the root directory specified in the | +| | :ref:`hco-cfg-set` section. | ++------------+-----------------------------------------------------------------+ +| ``$YYYY`` | Refers to the current simulation year. | ++------------+-----------------------------------------------------------------+ +| ``$WD`` | Refers to the current day of the week (1=Sun, 2=Mon .. -7=Sat). | ++------------+-----------------------------------------------------------------+ + +As an alternative to an input file, **geospatial uniform values** +can directly be specified in the configuration file (see e.g. scale +factor :literal:`SO2toSO4` in :ref:`edit-hco-cfg`). + +If multiple values are provided (separated by the :ref:`separator +character ` character), they are interpreted +as different time slices. In this case, the +:ref:`hco-cfg-base-sourcetime` attribute can be used to specify the +times associated with the individual slices. + +If no time attribute is set, HEMCO attempts to determine the time +slices from the number of data values: + ++-------------+---------------------------------+ +| # of values | Interpretation by HEMCO | ++=============+=================================+ +| 7 | Days of week (Sun, Mon .. Sat) | ++-------------+---------------------------------+ +| 12 | Months (Jan, Feb, .. Dec) | ++-------------+---------------------------------+ +| 24 | Hours of day (01, 02, .. 23) | ++-------------+---------------------------------+ + +Uniform values can be combined with **mathematical expressions**. For +example, to model a sine-wave emission source, enter - - When setting the time attribute to - :literal:`2005-2010/1-12/1/0 A`, HEMCO will always use the - 2005-2010 averaged monthly values, even for simulation years 2005 - to 2010. +.. code-block:: kconfig - - A time attribute of :literal:`2005-2010/1-12/1/0 RA` will make - sure that HEMCO uses the monthly data of the current year if - the simulation year is between 2005 and 2010, and the - 2005-2010 average for simulation years before and after 2005 - and 2010, respectively. + MATH:2.0+sin(HH/12*PI) + +**Country-specific data** can be provided through an ASCII file +(:literal:`.txt`). In an ESMF environment you must specify the +absolute file path rather than use the $ROOT specifier. More +details on the country-specific data option are given in the +Input File Format section. + +If this entry is **left empty** (:literal:`-`), the filename from +the preceding entry is taken, and the next 5 attributes will be +ignored (see entry :literal:`MACCITY_SO4` in :ref:`edit-hco-cfg`. + +.. _hco-cfg-base-sourcevar: + +sourceVar +--------- + +Source file variable of interest. Leave empty (:literal:`-`) if +values are directly set through the :ref:`hco-cfg-base-sourcefile` +attribute or if :ref:`hco-cfg-base-sourcefile` is empty. + +.. _hco-cfg-base-sourcetime: + +sourceTime +---------- + +This attribute defines the time slices to be used and the data +refresh frequency. The format is +:literal:`year/month/day/hour`. Accepted are discrete dates for +time-independent data (e.g. :literal:`2000/1/1/0`) and time ranges +for temporally changing fields +(e.g. :literal:`1980-2007/1-12/1-31/0-23`). Data will automatically +become updated as soon as the simulation date enters a new time +interval. + +The provided time attribute determines the data refresh +frequency. It does not need to correspond to the datetimes of the +input file. + +Examples: + +- If the input file contains daily data of + year 2005 and the time attribute is set to :literal:`2005/1/1/0`, + the file will be read just once (at the beginning of the + simulation) and the data of Jan 1, 2005 is used throughout the + simulation. |br| + |br| +- If the time attribute is set to :literal:`2005/1-12/1/0`, the + data is updated on every month, using the first day data of the + given month. For instance, if the simulation starts on July 15, + the data of July 1,2005 are used until August 1, at which point + the data will be refreshed to values from August 1, 2005. |br| + |br| +- A time attribute of :literal:`2005/1-12/1-31/0` will make + sure that the input data are refreshed daily to the current day's + data. |br| + |br| +- Finally, if the time attribute is set to + :literal:`2005/1-12/1-31/0-23`, the data file is read every + simulation hour, but the same daily data is used throughout the + day (since there are no hourly data in the file). Providing too + high update frequencies is not recommended unless the data + interpolation option is enabled (see below). + +If the provided time attributes do not match a datetime of the +input file, the **most likely** time slice is selected. The most +likely time slice is determined based on the specified source time +attribute, the datetimes available in the input file, and the +current simulation date. In most cases, this is just the closest +available time slice that lies in the past. + +- For example, if a file contains annual data from 2005 to 2010 and + the source time attribute is set to :literal:`2005-2010/1-12/1/0`, + the data of 2005 is used for all simulation months in 2005. |br| + |br| +- More complex datetime selections occur for files with + discontinuous time slices, e.g. a file with monthly data for + year 2005, 2010, 2020, and 2050. In this case, if the time + attribute is set to :literal:`2005-2020/1-12/1/0`, the monthly + values of 2005 are (re-)used for all years between 2005 and 2010, + the monthly values of 2010 are used for simulation years 2010 - + 2020, etc. + +It is possible to use tokens :literal:`$YYYY`, :literal:`$MM`, +:literal:`$DD`, and :literal:`$HH`, which will automatically be +replaced by the current simulation date. Weekly data (e.g. data +changing by the day of the week) can be indicated by setting the +day attribute to :literal:`WD` (the wildcard character will work, +too, but is not recommended). Weekly data needs to consist of at +least seven time slices - in increments of one day - representing +data for every weekday starting on Sunday. It is possible to store +multiple weekly data, e.g. for every month of a year: +:literal:`2000/1-12/WD/0`. These data must contain time slices for +the first seven days of every month, with the first day per month +representing Sunday data, then followed by Monday, +etc. (irrespective of the real weekdays of the given month). If the +wildcard character is used for the days, the data will be +interpreted if (and only if) there are exactly seven time +slices. See the Input File Format section for more details. Default +behavior is to interpret weekly data as 'local time', i.e. token +:literal:`WD` assumes that the provided values are in local +time. It is possible to use weekly data referenced to UTC time +using token :literal:`UTCWD`. + +Similar to the weekday option, there is an option to indicate +hourly data that represents local time: :literal:`LH`. If using +this flag, all hourly data of a given time interval (day, month, +year) are read into memory and the local hour is picked at every +location. A downside of this is that all hourly time slices in +memory are updated based on UTC time. For instance, if a file holds +local hourly data for every day of the year, the source time +attribute can be set to :literal:`2011/1-12/1-31/LH`. On every new +day (according to UTC time), this will read all 24 hourly time +slices of that UTC day and use those hourly data for the next 24 +hours. For the US, for instance, this results in the wrong daily +data being used for the last 6-9 hours of the day (when UTC time is +one day ahead of local US time). + +There is a difference between source time attributes +:literal:`2005-2008/$MM/1/0` and :literal:`2005-2008/1-12/1/0`. In +the first case, the file will be updated annually, while the update +frequency is monthly in the second case. The token :literal:`$MM` +simply indicates that the current simulation month shall be used +whenever the file is updated, but it doesn’t imply a refresh +interval. Thus, if the source time attribute is set to +:literal:`$YYYY/$MM/$DD/$HH`, the file will be read only once and +the data of the simulation start date is taken (and used throughout +the simulation). For uniform values directly set in the +configuration file, all time attributes but one must be fixed, +e.g. valid entries are :literal:`1990-2007/1/1/0` or +:literal:`2000/1-12/1/1`, but not :literal:`1990-2007/1-12/1/1`. - .. option:: RF +.. note:: - **Range, Forced:** Same as :option:`R`, but HEMCO stops with an - error if the simulation date is outside the provided range. + All data read from netCDF file are assumed to be in UTC time, + except for weekday data that are always assumed to be in local + time. Data read from the configuration file and/or from ASCII are + always assumed to be in local time. + +It is legal to keep different time slices in different files, +e.g. monthly data of multiple years can be stored in files +:file:`file_200501.nc`, :file:`file_200502.nc`, ..., +:file:`file_200712.nc`. By setting the source file attribute to +:file:`file_$YYYY$MM.nc` and the source time attribute to +:file:`2005-2007/1-12/1/0`, data of :file:`file_200501.nc` is used +for simulation dates of January 2005 (or any January of a previous +year), etc. The individual files can also contain only a subset of +the provided data range, e.g. all monthly files of a year can be +stored in one file: :file:`file_2005.nc`, :file:`file_2006.nc`, +:file:`file_2007.nc`. In this case, the source file name should be +set to :file:`file_$YYYY`, but the source time attribute should +still be :literal:`2005-2007/1-12/1/0` to indicate that the field +shall be updated monthly. + +This attribute can be set to the wildcard character (:literal:`*`), which +will force the file to be updated on every HEMCO time step. + +File reference time can be shifted by a fixed amount by adding an +optional fifth element to the time stamp attribute. For instance, +consider the case where 3-hourly averages are provided in +individual files with centered time stamps, e.g.: +:file:`file.yyyymmdd_0130z.nc`, :file:`file.yyyymmdd_0430z.nc`, +..., :file:`file.yyymmdd_2230z.nc`. To read these files **at the +beginning of their time intervals**, the time stamp can be shifted by +90 minutes: :literal:`2000-2016/1-12/1-31/0-23/+90minutes`. At +time 00z, HEMCO will then read file 0130z and keep using this file +until 03z, when it switches to file 0430z. Similarly, it is +possible to shift the file reference time by any number of years, +months, days, or hours. Time shifts can be forward or backward in +time (use :literal:`-` sign to shift backwards). + +.. _hco-cfg-base-cre: + +CRE +--- + +Controls the time slice selection if the simulation date is outside +the range provided in attribute source time (see above). The +following options are available: + +.. option:: C + + **Cycling:** Data are interpreted as climatology and recycled + once the end of the last time slice is reached. For instance, if + the input data contains monthly data of year 2000, and the + source time attribute is set to :literal:`2000/1-12/1/0 C`, the + same monthly data will be re-used every year. + + If the input data spans multiple years (e.g. monthly data from + 2000-2003), the closest available year will be used outside of + the available range (e.g. the monthly data of 2003 is used for + all simulation years after 2003). + +.. option:: CS + + **Cycling, Skip:** Data are interpreted as climatology and recycled + once the end of the last time slice is reached. Data that aren't + found are skipped. This is useful when certain fields aren't found + in a restart file and, in that case, those fields will be + initialized to default values. + +.. option:: CY + + **Cycling, Use Simulation Year:**, Same as :option:`C`, except + it does not allow :envvar:`Emission year` setting to override + the simulation year. + +.. option:: CYS + + **Cycling, Use Simulation Year, Skip:** Same as :option:`CS`, + except it does not allow :envvar:`Emission year` setting to + override the simulation year. + +.. option:: R + + **Range:** Data are only considered as long as the simulation + time is within the time range specified in attribute + :ref:`hco-cfg-base-sourcetime`. The provided range does not necessarily + need to match the time stamps of the input file. If it is + outside of the range of the netCDF time stamps, the closest + available date will be used. + + For instance, if a file contains data for years 2003 to 2010 and + the provided range is set to :literal:`2006-2010/1/1/0 R`, the + file will only be considered between simulation years + 2006-2010. For simulation years 2006 through 2009, the + corresponding field on the file is used. For all years beyond + 2009, data of year 2010 is used. If the simulation date is + outside the provided time range, the data is ignored but HEMCO + does not return an error---the field is simply treated as empty + (a corresponding warning is issued in the HEMCO log file). + + - Example: if the source time attribute is set to + :literal:`2000-2002/1-12/1/0 R`, the data will be used for + simulation years 2000 to 2002 and ignored for all other years. + +.. option:: RA + + **Range, Averaging Otherwise:** Combination of flags :option:`R` + and :option:`A`. As long as the simulation year is within the + specified year range, HEMCO will use just the data from that + particular year. As soon as the simulation year is outside the + specified year range, HEMCO will use the data averaged over the + specified years. Here are some examples: + + +---------------------------+--------------------------------------------------+ + | Setting | What this does | + +===========================+==================================================+ + | ``2015-2020/1-12/1/0 R`` | Uses monthly mean data only within simulation | + | | simulation years 2015-2020, and ignores the data | + | | outside of this time range. | + +---------------------------+--------------------------------------------------+ + | ``2015-2020/1-12/1/0 A`` | HEMCO will always use the 2015-2020 averaged | + | | monthly values, even for simulation years 2015 | + | | through 2020. | + +---------------------------+--------------------------------------------------+ + | ``2015-2020/1-12/1/0 RA`` | Uses the monthly data of the current year if the | + | | simulation year is within the range 2015-2020, | + | | and the 2015-2020 average for years before 2015 | + | | and after 2020, respectively. | + +---------------------------+--------------------------------------------------+ + +.. option:: RF + + **Range, Forced:** Same as :option:`R`, but HEMCO stops with an + error if the simulation date is outside the provided range. + +.. option:: RY + + **Range, Use Simulation Year:** Same as :option:`R`, except + it does not allow :envvar:`Emission year` to override the + simulation year. - .. option:: RY +.. option:: RFY - **Range, Use Simulation Year:** Same as :option:`R`, except - it does not allow :envvar:`Emission year` to override the - simulation year. + **Range, Forced, Use Simulation Year**. Same as :option:`RY`, + except it does not allow :envvar:`Emission year` to override the + simulation year. - .. option:: RFY +.. option:: RFY3 - **Range, Forced, Use Simulation Year**. Same as :option:`RY`, - except it does not allow :envvar:`Emission year` to override the - simulation year. + **Ranged, Forced, Use Simulation Year, 3-hourly data**: Same as + :option:`RFY`, but used with data that is read from disk every 3 + hours (e.g. meteorological data and related quantities). - .. option:: RFY3 +.. option:: E - **Ranged, Forced, Use Simulation Year, 3-hourly data**: Same as - :option:`RFY`, but used with data that is read from disk every 3 - hours (e.g. meteorological data and related quantities). + **Exact:** Fields are only used if the time stamp on the field + exactly matches the current simulation datetime. In all other + cases, data is ignored but HEMCO does not return an error. - .. option:: E + Example: - **Exact:** Fields are only used if the time stamp on the field - exactly matches the current simulation datetime. In all other - cases, data is ignored but HEMCO does not return an error. + - :ref:`hco-cfg-base-sourcetime` and :ref:`hco-cfg-base-cre`: + :literal:`2013-2023/1-12/1-31/0 E` - - For example, if :option:`sourceTime` is set to - :literal:`2000-2013/1-12/1-31/0 E`, every time the simulation - enters a new day HEMCO will attempt to find a data field for - the current simulation date. If no such field can be found on - the file, the data is ignored (and a warning is - prompted). This setting is particularly useful for data that - is highly sensitive to date and time, e.g. restart variables. + Every time the simulation enters a new day, HEMCO will attempt to + find a data field for the current simulation date. If no such + field can be found in the file, the data is ignored (and a + warning is prompted). This setting is particularly useful for + data that is highly sensitive to date and time, e.g. restart + variables. - .. option:: EF +.. option:: EF - **Exact, Forced:** Same as :option:`E`, but HEMCO stops with an - error if no data field can be found for the current simulation - date and time. + **Exact, Forced:** Same as :option:`E`, but HEMCO stops with an + error if no data field can be found for the current simulation + date and time. - .. option:: EC +.. option:: EC - **Exact, Read/Query Contiuously.**. + **Exact, Read/Query Contiuously.**. - .. option:: ECF +.. option:: ECF - **Exact, Read/Query Continuously, Forced.** + **Exact, Read/Query Continuously, Forced.** - .. option:: EFYO +.. option:: EFYO - **Exact, Forced, Simulation Year, Once**: Same as :option:`EF`, - with the following additions: + **Exact, Forced, Simulation Year, Once**: Same as :option:`EF`, + with the following additions: - - :envvar:`Y`: HEMCO will stop thie simulation if the simulation + - :envvar:`Y`: HEMCO will stop thie simulation if the simulation year does not match the year in the file timestamp. - - :envvar:`O`: HEMCO will only read the file once. - - This setting is typically only used for model restart files - (such as `GEOS-Chem Classic restart files - `_). - This ensures that the simulation will stop unless the restart - file timestamp matches the simulation start date and time. - - .. attention:: - - Consider changing the time cycle flag from :option:`EFYO` to - :option:`CYS` if you would like your simulation to read a - data file (such as a simulation restart file) whose file - timestamp differs from the simulaton start date and time. - - .. option:: EY - - **Exact, Use Smulation Year:** Same as :option:`E`, except it - does not allow :envvar:`Emission year` setting to override the - simulation year. - - .. option:: A - - **Averaging:** Tells HEMCO to average the data over the - specified range of years. - - - For instance, setting :option:`sourceTime` to - :literal:`1990-2010/1-12/1/0 A` will cause HEMCO to calculate - monthly means between 1990 to 2010 and use these regardless of - the current simulation date. - - The data from the different years can be spread out over multiple - files. For example, it is legal to use the averaging flag in - combination with files that use year tokens such as - :literal:`file_$YYYY.nc`. - - .. option:: I - - **Interpolation:** Data fields are interpolated in time. As an - example, let's assume a file contains annual data for years - 2005, 2010, 2020, and 2050. If :option:`sourceTime` is set to - :literal:`2005-2050/1/1/0 I`, data becomes interpolated between - the two closest years every time we enter a new simulation - year. If the simulation starts on January 2004, he value of 2005 - is used for years 2004 and 2005. At the beginning of 2006, the - used data is calculated as a weighted mean for the 2005 and 2010 - data, with 0.8 weight given to 2005 and 0.2 weight given to 2010 - values. Once the simulation year changes to 2007, the weights - hange to 0.6 for 2005 and 0.4 for 2010, etc. The interpolation - frequency is determined by :option:`sourceTime` the source time - attribute. - - For example, setting the source time attribute to - :literal:`2005-2050/1-12/1/0 I` would result in a recalculation - of the weights on every new simulation month. Interpolation - works in a very similar manner for discontinuous monthly,daily, - and hourly data. For instance if a file contains monthly data of - 2005, 2010, 2020, and 2050 and the source time attribute is set - to :literal:`2005-2050/1-12/1/0 I`, the field is recalculated - every month using the two bracketing fields of the given month: - July 2007 values are calculated from July 2005 and July 2010 - data (with weights of 0.6 and 0.4, respectively), etc. - - Data interpolation also works between multiple files. For - instance, if monthly data are stored in files - :literal:`file_200501.nc`, :file:`file_200502.nc`, etc., a - combination of source file name :file:`file_$YYYY$MM.nc` and - :option:`sourceTime` attribute :literal:`2005-2007/1-12/1-31/0 - :literal:I` will result in daily data interpolation between the two - bracketing files, e.g. if the simulation day is July 15, 2005, - the fields current values are calculated from files - :literal:`file_200507.nc` and :literal:`file_200508.nc`, - respectively. - - Data interpolation across multiple files also works if there are - file 'gaps', for example if there is a file only every three - hours: :file:`file_20120101_0000.nc`, - :file:`file_20120101_0300.nc`, etc. Hourly data interpolation - between those files can be achieved by setting source file to - :file:file_$YYYY$MM$DD_$HH00.nc`, and :option:`sourceTime` to - :literal:`2000-2015/1-12/1-31/0-23 I` (or whatever the covered - year range is). - -.. option:: SrcDim - - Spatial dimension of input data (:literal:`xy` for horizontal - data; :literal:`xyz` for 3-dimensional data). - - The :option:`SrcDim` attribute accepts an integer number as - vertical coordinate to indicate the number of vertical levels to - be read, as well as the direction of the vertical axis. For - example, to use the lowest 5 levels of the input data only, set - :option:`SrcDim` to :literal:`xy5`. This will place the lowest 5 - levels of the input data into HEMCO levels 1 to 5. To use the - topmost 5 levels of the input data, set :option:`SrcDim` to - :literal:`xy-5`. The minus sign will force the vertical axis to - be flipped, i.e. the 5 topmost levels will be placed into HEMCO - levels 1 to 5 (in reversed order, so that the topmost level of the - input data will be placed in HEMCO lev el 1, etc.). - - The :option:`SrcDim` attribute can also be used to indicate the - level into which 2D data shall be released by setting the - vertical coordinate to :literal:`LX`, with :literal:`X` being - the release level. For instance, to emit a 2D field into level 5, - set :option:`SrcDim` to :literal:`xyL5`. - - HEMCO can has two options to specify the emission injection - height: - - #. The vertical height can be given as model level (default) or in - meters, e.g. to emit a source at 2000m: - :literal:`xyL=2000m`. |br| - |br| - - #. For 2D fields it is legal to define a range of levels, in which - case the emissions are uniformly distributed across these - levels (maintaining the original total emissions). - Examples for this are: - - - :literal:`xyL=1:5`: Emit into levels 1-5; - - :literal:`xyL=2:5000m` Emit between model level 2 and 5000m; - - :literal:`xyL=1:PBL`: Emit from the surface up to the PBL top. - - HEMCO can also get the injection height information from an - external source (i.e. netCDF file). For now, these heights are - expected to be in meters. The injection height data must be - listed as a scale factor and can then be referenced in the - :option:`SrcDim` setting. - - HEMCO can read read netCDF files with an arbitrary additional - dimension. For these files, the name of the additional dimension - and the desired dimension index must be specified as part of the - :option:`SrcDim` attribute. - - - For example, to read a file that contains 3D ensemble data - (with the individual ensemble runs as additional dimension - :literal:`ensemble`), set :option:`SrcDim` to - :literal:`xyz+"ensemble=3` to indicate that you wish to read - the third ensemble member. You may also use a - :ref:`user-defined token ` for the - dimension index to be used, e.g. :literal:`xyz+"ensemble=$ENS"`. - - .. note:: - - Arbitrary additional dimensions are currently not supported in - a high-performance environment that uses the ESMF/MAPL - input/output libraries. - -.. option:: SrcUnit - - Units of the data. - -.. option:: Species - - HEMCO emission species name. Emissions will be added to this - species. All HEMCO emission species are defined at the beginning of - the simulation (see the Interfaces section) If the species name - does not match any of the HEMCO species, the field is ignored - altogether. - - The species name can be set to the wildcard character, in which - case the field is always read by HEMCO but no species is assigned - to it. This can be useful for extensions that import some - (species-independent) fields by name. - -The three entries below only take effect for fields that are assigned -to the base extension (:literal:`ExtNr = 0`), e.g. that are used for -automatic emission calculation. They are used by HEMCO to determine -how the final emission fields are assembled from all provided data fields. - -.. option:: ScalIDs - - Identification numbers of all scale factors and masks that shall be - applied to this base emission field. Multiple entries must be - separated by the separator character. The :option:`ScalIDs` must - correspond to the numbers provided in the :ref:`hco-cfg-scalefac` - and :ref:`hco-cfg-masks` sections. - -.. option:: Cat - - Emission category. Used to distinguish different, independent - emission sources. Emissions of different categories are always - added to each other. - - Up to three emission categories can be assigned to each entry - (separated by the separator character). Emissions are always - entirely written into the first listed category, while emissions of - zero are used for any other assigned category. - - In practice, the only time when more than one emissions category - needs to be specified is when an :ref:`inventory does not separate - between anthropogenic, biofuels, and/or trash emissions - ` - - For example, the CEDS inventory uses categories :literal:`1/2/12` - because CEDS lumps both biofuel emissions and trash emissions with - anthropogenic Because. The :literal:`1/2/12` category designation - means "Put everything into the first listed category - (1=anthropogenic), and set the other listed categories (2=biofuels, - 12=trash) to zero. - -.. option:: Hier - - Emission hierarchy. Used to prioritize emission fields within the - same emission category. Emissions of higher hierarchy overwrite - lower hierarchy data. Fields are only considered within their - defined domain, i.e. regional inventories are only considered - within their mask boundaries. + - :envvar:`O`: HEMCO will only read the file once. + + This setting is typically only used for model restart files + (such as `GEOS-Chem Classic restart files + `_). + This ensures that the simulation will stop unless the restart + file timestamp matches the simulation start date and time. + + .. attention:: + + Consider changing the time cycle flag from :option:`EFYO` to + :option:`CYS` if you would like your simulation to read a + data file (such as a simulation restart file) whose file + timestamp differs from the simulaton start date and time. + +.. option:: EY + + **Exact, Use Smulation Year:** Same as :option:`E`, except it + does not allow :envvar:`Emission year` setting to override the + simulation year. + +.. option:: A + + **Averaging:** Tells HEMCO to average the data over the + specified range of years. + + - For instance, setting :ref:`hco-cfg-base-sourcetime` to + :literal:`1990-2010/1-12/1/0 A` will cause HEMCO to calculate + monthly means between 1990 to 2010 and use these regardless of + the current simulation date. + + The data from the different years can be spread out over multiple + files. For example, it is legal to use the averaging flag in + combination with files that use year tokens such as + :literal:`file_$YYYY.nc`. + +.. option:: I + + **Interpolation:** Data fields are interpolated in time. As an + example, let's assume a file contains annual data for years + 2005, 2010, 2020, and 2050. If :ref:`hco-cfg-base-sourcetime` is set to + :literal:`2005-2050/1/1/0 I`, data becomes interpolated between + the two closest years every time we enter a new simulation + year. If the simulation starts on January 2004, he value of 2005 + is used for years 2004 and 2005. At the beginning of 2006, the + used data is calculated as a weighted mean for the 2005 and 2010 + data, with 0.8 weight given to 2005 and 0.2 weight given to 2010 + values. Once the simulation year changes to 2007, the weights + hange to 0.6 for 2005 and 0.4 for 2010, etc. The interpolation + frequency is determined by :ref:`hco-cfg-base-sourcetime` the source time + attribute. + + For example, setting the source time attribute to + :literal:`2005-2050/1-12/1/0 I` would result in a recalculation + of the weights on every new simulation month. Interpolation + works in a very similar manner for discontinuous monthly,daily, + and hourly data. For instance if a file contains monthly data of + 2005, 2010, 2020, and 2050 and the source time attribute is set + to :literal:`2005-2050/1-12/1/0 I`, the field is recalculated + every month using the two bracketing fields of the given month: + July 2007 values are calculated from July 2005 and July 2010 + data (with weights of 0.6 and 0.4, respectively), etc. + + Data interpolation also works between multiple files. For + instance, if monthly data are stored in files + :literal:`file_200501.nc`, :file:`file_200502.nc`, etc., a + combination of source file name :file:`file_$YYYY$MM.nc` and + :ref:`hco-cfg-base-sourcetime` attribute :literal:`2005-2007/1-12/1-31/0 + :literal:I` will result in daily data interpolation between the two + bracketing files, e.g. if the simulation day is July 15, 2005, + the fields current values are calculated from files + :literal:`file_200507.nc` and :literal:`file_200508.nc`, + respectively. + + Data interpolation across multiple files also works if there are + file 'gaps', for example if there is a file only every three + hours: :file:`file_20120101_0000.nc`, + :file:`file_20120101_0300.nc`, etc. Hourly data interpolation + between those files can be achieved by setting source file to + :file:file_$YYYY$MM$DD_$HH00.nc`, and :ref:`hco-cfg-base-sourcetime` to + :literal:`2000-2015/1-12/1-31/0-23 I` (or whatever the covered + year range is). + +.. _hco-cfg-base-srcdim: + +SrcDim +------ + +Specifies the spatial dimension of the input data and/or the +model levels into which emissions will be placed. Here are some +examples that illustrate its use. + ++------------------------+--------------------------------------------------+ +| SrcDim setting | What this does | ++========================+==================================================+ +| ``xy`` | Specifies 2-dimensional input data | ++------------------------+--------------------------------------------------+ +| ``xyz`` | Specifies 3-dimensional input data | ++------------------------+--------------------------------------------------+ +| ``xy5`` | Emits the lowest 5 levels of the input data | +| | into HEMCO levels 1 through 5. | ++------------------------+--------------------------------------------------+ +| ``xy-5`` | Emits the tompmost 5 levels of the input data | +| | into HEMCO levels 1 through 5 (i.e. in | +| | reversed order, so that the topmost level is | +| | placed into HEMCO level 1, etc.) | ++------------------------+--------------------------------------------------+ +| ``xyL=5`` | Emits a 2-D input data field into HEMCO | +| | level 5. | ++------------------------+--------------------------------------------------+ +| ``xyL=2000m`` | Emits a 2-D input data field into the model | +| | level corresponding to 2000m above the surface. | ++------------------------+--------------------------------------------------+ +| ``xyL=2:5000m`` | Emits between HEMCO level 2 and 5000m | ++------------------------+--------------------------------------------------+ +| ``xyL=1:PBL`` | Emits from the surface (HEMCO level 1) up to the | +| | HEMCO level containing the PBL top. | ++------------------------+--------------------------------------------------+ +| ``xyL=PBL:5500m`` | Emits from the PBL top level up to 5500m. | ++------------------------+--------------------------------------------------+ +| ``xyL*`` | Emit same value to all emission levels. A scale | +| | scale factor should be applied to distribute the | +| | emissions vertically. | ++------------------------+--------------------------------------------------+ +| ``xyL=1:scal300`` | Emit from the surface (HEMCO level 1) to the | +| | injection height that is listed under scale | +| | factor 300. This scale factor may be read from | +| | a netCDF file. | ++------------------------+--------------------------------------------------+ +| ``xyz+"ensemble=3"`` | Read a netCDF file containing ensemble data (xyz | +| | plus an additional dimension named | +| | ``ensemble``), using the 3rd ensemble member. | ++------------------------+--------------------------------------------------+ +| ``xyz+"ensemble=$EN"`` | Similar to the previous example, but using a | +| | :ref:`token ` to denote | +| | which ensemble member to use. [#A]_ | ++------------------------+--------------------------------------------------+ + +.. rubric:: Notes for SrcDim + +.. [#A] Arbitrary additional dimensions are currently not supported in + a high-performance environment that uses the ESMF/MAPL + input/output libraries. + +.. _hco-cfg-base-srcunit: + +SrcUnit +------- + +Units of the data. + +.. _hco-cfg-base-species: + +Species +------- + +HEMCO emission species name. Emissions will be added to this +species. All HEMCO emission species are defined at the beginning of +the simulation (see the Interfaces section) If the species name +does not match any of the HEMCO species, the field is ignored +altogether. + +The species name can be set to the wildcard character, in which +case the field is always read by HEMCO but no species is assigned +to it. This can be useful for extensions that import some +(species-independent) fields by name. + +.. _hco-cfg-base-scalids: + +ScalIDs +------- + +Identification numbers of all scale factors and masks that shall be +applied to this base emission field. Multiple entries must be +separated by the separator character. ScalIDs must csorrespond to the +numbers provided in the :ref:`hco-cfg-scalefac` and +.. note:: + + This option only takes effect for fields that are assigned to the + base extension (:literal:`ExtNr = 0`). + +.. _hco-cfg-base-cat: + +Cat +--- + +Emission category. Used to distinguish different, independent +emission sources. Emissions of different categories are always +added to each other. + +Up to three emission categories can be assigned to each entry +(separated by the separator character). Emissions are always +entirely written into the first listed category, while emissions of +zero are used for any other assigned category. + +In practice, the only time when more than one emissions category +needs to be specified is when an :ref:`inventory does not separate +between anthropogenic, biofuels, and/or trash emissions +` + +For example, the CEDS inventory uses categories :literal:`1/2/12` +because CEDS lumps both biofuel emissions and trash emissions with +anthropogenic Because. The :literal:`1/2/12` category designation +means "Put everything into the first listed category +(1=anthropogenic), and set the other listed categories (2=biofuels, +12=trash) to zero. + +.. note:: + + This option only takes effect for fields that are assigned to the + base extension (:literal:`ExtNr = 0`). + +.. _hco-cfg-base-hier: + +Hier +---- + +Emission hierarchy. Used to prioritize emission fields within the +same emission category. Emissions of higher hierarchy overwrite +lower hierarchy data. Fields are only considered within their +defined domain, i.e. regional inventories are only considered +within their mask boundaries. + +.. note:: + + This option only takes effect for fields that are assigned to the + base extension (:literal:`ExtNr = 0`). .. _hco-cfg-scalefac: @@ -1156,35 +1285,49 @@ values. ### END SECTION SCALE FACTORS ### -Options :option:`sourceFile`, :option:`sourceVar`, -:option:`sourceTime`, :option:`CRE`, :option:`SrcDim`, and -:option:`SrcUnit`, are described in :ref:`hco-cfg-base`. - -Other scale factor options not previously described are: +Options :ref:`hco-cfg-base-sourcefile`, :ref:`hco-cfg-base-sourcevar`, +:ref:`hco-cfg-base-sourcetime`, :ref:`hco-cfg-base-cre`, +:ref:`hco-cfg-base-srcdim`, and :ref:`hco-cfg-base-srcunit` are +described in :ref:`hco-cfg-base`. Scale factor options not previously described are: -.. option:: ScalID +.. _hco-cfg-base-scale-scalid: + +ScalID +------ + +Scale factor identification number. Used to link the scale factors +to the base emissions through the corresponding +:ref:`hco-cfg-base-scalids` attribute in :ref:`hco-cfg-base`. + +.. _hco-cfg-base-scale-oper: - Scale factor identification number. Used to link the scale factors - to the base emissions through the corresponding ScalIDs attribute - in the :ref`hco-cfg-base`. +Oper +---- -.. option:: Oper +Scale factor operator. Determines the operation performed on the +scale factor. Possible values are: - Scale factor operator. Determines the operation performed on the - scale factor. Possible values are: ++--------+--------------------------------------------+ +| Oper | What this does | ++========+============================================+ +| ``1`` | Multiplication (Emission = Base \* Scale) | ++--------+--------------------------------------------+ +| ``-1`` | Division (Emission = Base / Scale) | ++--------+--------------------------------------------+ +| ``2`` | Squared (Emission = Base \* Scale**2) | ++--------+--------------------------------------------+ - - 1 for multiplication (Emission = Base \* Scale); - - -1 for division (Emission = Base / Scale); - - 2 for squared (Emission = Base \* Scale**2). +.. _hco-cfg-base-scale-maskid: -.. option:: MaskID +MaskID +------ - Optional. ScalID of a mask field. This optional value can be used - if a scale factor shall only be used over a given region. The - provided MaskID must have a corresponding entry in the - :ref:`Masks section ` of the configuration file. +Optional. :ref:`hco-cfg-base-scale-scalid` of a mask field. This +optional value can be used if a scale factor shall only be used over a +given region. The provided MaskID must have a corresponding entry in +the :ref:`Masks section ` of the configuration file. .. note:: @@ -1230,21 +1373,24 @@ using): The required attributes for mask fields are described below: -Options :option:`ScalID` and :option:`Oper` are described in +Options :ref:`hco-cfg-base-scale-scalid` and +:ref:`hco-cfg-base-scale-oper` are described in :ref:`hco-cfg-scalefac`. -Options :option:`Name`, :option:`sourceFile`, :option:`sourceVar`, -:option:`sourceTime`, :option:`CRE`, :option:`SrcDim`, and -:option:`SrcUnit`, are described in :ref:`hco-cfg-base`. +Options :ref:`hco-cfg-base-sourcefile`, :ref:`hco-cfg-base-sourcevar`, +:ref:`hco-cfg-base-sourcetime`, :ref:`hco-cfg-base-cre`, +:ref:`hco-cfg-base-srcdim`, and :ref:`hco-cfg-base-srcunit` are +described in :ref:`hco-cfg-base`. The :envvar:`Box` option is deprecated. -Instead of specifying the :option:`sourceFile` and :option:`sourceVar` -fields, you can directly provide the lower left and upper right box -coordinates: :literal:`Lon1/Lat1/Lon2/Lat2` . Longitudes must be in -degrees east, latitudes in degrees north. Only grid boxes whose mid -points are within the specified mask boundaries. You may also specify -a single grid point (:literal:`Lon1/Lat1/Lon1/Lat1/`). +Instead of specifying the :ref:`hco-cfg-base-sourcefile` and +:ref:`hco-cfg-base-sourcevar` fields, you can directly provide the +lower left and upper right box coordinates: +:literal:`Lon1/Lat1/Lon2/Lat2` . Longitudes must be in degrees east, +latitudes in degrees north. Only grid boxes whose mid points +are within the specified mask boundaries. You may also +specify a single grid point (:literal:`Lon1/Lat1/Lon1/Lat1/`). .. _hco-cfg-masks-caveat: diff --git a/docs/source/hco-ref-guide/input-file-format.rst b/docs/source/hco-ref-guide/input-file-format.rst index 3a80a1e3..0993c34a 100644 --- a/docs/source/hco-ref-guide/input-file-format.rst +++ b/docs/source/hco-ref-guide/input-file-format.rst @@ -95,8 +95,8 @@ It is recommended to store data in one of the HEMCO standard units: (for instance, land types represented as integer values). HEMCO will attempt to convert all data to one of those units, unless -otherwise via the :option:`SrcUnit` attribute (see the :ref:`Base -Emissions `) section. +otherwise via the :ref:`hco-cfg-base-srcunit` attribute (see the +:ref:`hco-cfg-base` section). Mass conversion (e.g. from molecules to kg) is performed based on the properties (e.g. molecular weight) of the species assigned to the @@ -125,57 +125,66 @@ Arbitrary additional netCDF dimension HEMCO can read netCDF files with an additional, arbitrary dimension. The dimension name and dimension index to be read must be given explicitly in the HEMCO configuration file as part of the -:option:`SrcDim` file attribute). This feature is currently not -available in an ESMF environment. +:ref:`hco-cfg-base-srcdim` file attribute). This feature is currently +not available in an ESMF environment. -.. _hco-filefmt-regrid: - -========== -Regridding -========== .. _hco-filefmt-regrid-vert: +=================== Vertical regridding -------------------- - -HEMCO is able to perform some limited vertical interpolation. - -.. warning:: +=================== - **HEMCO assumes that the input data is on the same grid as the model grid if it has the same number (nz) of, or plus one (nz+1) vertical levels than the model.** - In the case of the same number of vertical levels, HEMCO assumes that the input data is already on the model grid - and no interpolation is performed. In the case of input data having nz+1 levels, - the data is interpreted as being on grid edges instead of grid midpoints. - -**Collapsing into various GEOS grids.** Additional vertical -regridding options are available for the various GEOS grids (e.g. to -regrid native GEOS-5 levels to reduced GEOS-5 levels, or to remap GEOS-5 -data onto the vertical GEOS-4 grid). These options are only available if -the corresponding compiler flags are set (this is the default case for -GEOS-Chem users). - -**Conservative vertical interpolation using MESSy.** If input data is -specified with vertical coordinates in :literal:`lev` attribute of the -netCDF file with units :literal:`atmosphere_hybrid_sigma_pressure_coordinate`, -HEMCO can perform vertical interpolation using MESSy to the model grid. - -**Regridding GEOS-Chem 3-D input data in other models.** In other models -where HEMCO is used for emissions, but do not necessarily use the GEOS -vertical grids (e.g., WRF-GC, GEOS-Chem within CESM, CAM-chem with HEMCO), -input data from GEOS-Chem files which have 72 levels will automatically -be regridded to the model levels, for compatibility. +HEMCO is able to perform some limited vertical interpolation. By default, HEMCO assumes that the vertical coordinate direction is upwards, i.e. the first level index corresponds to the surface layer. The vertical axis can be reversed by setting the srcDim attribute in -the HEMCO configuration file accordingly (e.g. xy-72 if the input -data has 72 levels on a reversed vertical axis). +the HEMCO configuration file accordingly (e.g. :literal:`xy-72` if the +input data has 72 levels on a reversed vertical axis). + +.. warning:: + + HEMCO assumes that the input data is on the same grid as the + model grid if it has the same number** (:literal:`NZ`) of, or plus + one (:literal:`NZ+1`) vertical levels than the model. + + In the case of the same number of vertical levels, HEMCO assumes + that the input data is already on the model grid and no + interpolation is performed. + + In the case of input data having :literal:`NZ+1` levels, the data is + interpreted as being on grid edges instead of grid midpoints. + +Collapsing into various GEOS grids +---------------------------------- + +Additional vertical regridding options are available for the various +GEOS grids. These options are only available if the corresponding +compiler flags are set (this is the default case for GEOS-Chem users). + +Conservative vertical interpolation using MESSy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If input data is specified with vertical coordinates in :literal:`lev` +attribute of the netCDF file with units +:literal:`atmosphere_hybrid_sigma_pressure_coordinate`, HEMCO can +perform vertical interpolation using MESSy to the model grid. + +Regridding GEOS-Chem 3-D input data in other models +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In other models where HEMCO is used for emissions, but do not +necessarily use the GEOS vertical grids (e.g., WRF-GC, GEOS-Chem +within CESM, CAM-chem with HEMCO), input data from GEOS-Chem files +which have 72 levels will automatically be regridded to the model +levels, for compatibility. .. _hco-filefmt-regrid-horz: +===================== Horizontal regridding ---------------------- +===================== In a non-ESMF environment, HEMCO can only regrid between rectilinear grids (e.g. lat-lon). diff --git a/docs/source/hco-ref-guide/known-bugs.rst b/docs/source/hco-ref-guide/known-bugs.rst index 89b549a3..1fe0fdf8 100644 --- a/docs/source/hco-ref-guide/known-bugs.rst +++ b/docs/source/hco-ref-guide/known-bugs.rst @@ -31,9 +31,9 @@ HEMCO may not recognize alternate spellings of units ==================================================== If a unit string (e.g. :literal:`kg/m2/s`) read from a netCDF -file matches the unit string listed under the :option:`SrcUnit` column -of :ref:`the HEMCO configuration file `, then no unit -conversion will happen. +file matches the unit string listed under the +:ref:`hco-cfg-base-srcunit` column of :ref:`the HEMCO configuration +file `, then no unit conversion will happen. But if the unit string in the file is e.g. :literal:`kg m-2 s-1` and the unit in the configuration file is :literal:`kg/m2/s`, then HEMCO diff --git a/docs/source/hco-ref-guide/more-examples.rst b/docs/source/hco-ref-guide/more-examples.rst index 78c4a3b1..03c5d7ae 100644 --- a/docs/source/hco-ref-guide/more-examples.rst +++ b/docs/source/hco-ref-guide/more-examples.rst @@ -144,14 +144,14 @@ Scale emissions by species You may define uniform scale factors for single species that apply across all emission inventories, sectors and extensions. These -scale factors can be set in the :ref:`Settings ` +scale factors can be set in the :ref:`Settings ` section of :ref:`the HEMCO configuration file `, using the :literal:`EmissScale_`, where :literal:`` denotes the name of a HEMCO species such as :literal:`CO`, :literal:`CH4`, :literal:`NO`, etc. For instance, to scale all NO emissions by 50% add the line -:literal:`EmisScale_NO` to the :ref:`Settings ` +:literal:`EmisScale_NO` to the :ref:`Settings ` section of the :ref:`the HEMCO configuration file `: .. code-block:: kconfig @@ -205,7 +205,7 @@ Scale extension emissions globally by species You may pass a global scale factor to the :ref:`hco-ext`. For example, to double soil NO emissions everywhere, add the -:literal:`Scaling_NO` to the section for the :option:`SoilNOx` +:literal:`Scaling_NO` to the section for the :ref:`hco-ext-list-soilnox` extension. This is located in the :ref:`Extension Switches ` section of :ref:`the HEMCO configuration file `, as shown below: @@ -222,13 +222,13 @@ Scale summertime soil NOx emisions over the US ---------------------------------------------- It is possible to pass uniform and/or spatiotemporal scale factors to -some of the extensions, including :option:`SoilNOx`. +some of the extensions, including :ref:`hco-ext-list-soilnox`. For instance, suppose you want to halve summertime soil NOx emissions over the continental US. You can do this by defining a scale field -(here, :literal:`SOILNOX_SCALE`) to the :option:`SoilNOx` emission -field in the :ref:`Extension Switches ` section -of :ref:`the HEMCO configuration file `: +(here, :literal:`SOILNOX_SCALE`) to the :ref:`hco-ext-list-soilnox` +emission field in the :ref:`Extension Switches ` +section of :ref:`the HEMCO configuration file `: .. code-block:: kconfig @@ -239,8 +239,8 @@ of :ref:`the HEMCO configuration file `: :literal:`SOILNOX_SCALE` is just a dummy scale factor with a global uniform value of 1.0. The actual temporal scaling over the US is done via scale factor :literal:`333` assigned to this -field. This approach ensures that all :option:`SoilNOx` emissions -outside of the US remain intact. +field. This approach ensures that all :ref:`hco-ext-list-soilnox` +emissions outside of the US remain intact. The next step is to define scale factor :literal:`333` (named :literal:`SOILNOX\_SCALE`) in the :ref:`Scale Factors @@ -286,8 +286,8 @@ Exercise care in defining mask regions In an effort to reduce I/O HEMCO ignores any emission entries that are deemed "irrelevant" because there is another (global) emission entry -for the same species and emission category (:option:`Cat`), but higher -hierarchy (:option:`Hier`). +for the same species and emission category (:ref:`hco-cfg-base-cat`), +but higher hierarchy (:ref:`hco-cfg-base-hier`). For instance, suppose you have the following two fields defined under :ref:`Base Emissions `: @@ -471,15 +471,15 @@ Fix MEGAN extension emissions to a specified year Question submitted by a HEMCO user: - Is it possible to fix :option:`MEGAN` emissions to a given year? I know - this works for many other :ref:`base emissions ` - inventories, but MEGAN emissions are dependent on environmental - variables. + Is it possible to fix :ref:`hco-ext-list-megan` emissions to a + given year? I know this works for many other :ref:`base emissions + ` inventories, but MEGAN emissions are dependent on + environmental variables. Your best option may be to run the HEMCO standalone and save out MEGAN emissions for the desired year. Then, in a subsequent run, you can read in the :ref:`HEMCO diagnostic output ` files -containing the archived :option:`MEGAN` emissions. +containing the archived :ref:`hco-ext-list-megan` emissions. #. Run the HEMCO standalone model. Make sure the following entries to your :file:`HEMCO_Diagn.rc` file: @@ -492,11 +492,12 @@ containing the archived :option:`MEGAN` emissions. # ... etc for other MEGAN species ... In the above entries, :literal:`108` tells HEMCO to get the - emissions from the :option:`MEGAN` extension, which is listed in - the :ref:`Extension Switches ` section of the - :ref:`configuration file ` with :option:`ExtNr` 108. + emissions from the :ref:`hco-ext-list` extension, which is listed + in the :ref:`Extension Switches ` section of + the :ref:`configuration file ` with + :ref:`hco-cfg-ext-switches-extnr` 108. -#. Add the following lines in the :ref:`Settings ` +#. Add the following lines in the :ref:`Settings ` section of :ref:`the HEMCO configuration file `: .. code-block:: kconfig @@ -505,11 +506,12 @@ containing the archived :option:`MEGAN` emissions. DiagnPrefix: HEMCO_diagnostics DiagnFreq: Monthly - For more information, see the sections on :option:`DiagnFile`, - :option:`DiagnPrefix`, :option:`DiagnFreq`. + For more information, see the sections on :ref:`hco-cfg-set-diagnfile`, + :ref:`hco-cfg-set-diagnprefix`, and :ref:`hco-cfg-set-diagnfreq`. -#. Turn off the MEGAN extension in the :ref:`Extension Switches - ` section of the configuration file. +#. Turn off the :ref:`hco-ext-list-megan` extension in the + :ref:`Extension Switches ` section of the + configuration file. .. code-block:: kconfig @@ -666,10 +668,10 @@ Mathematical expressions examples You may define mathematical expressions in :ref:`the HEMCO configuration file `. Similar to uniform values, these must -be placed in in the :option:`sourceFile` column. All expressions are -evaluated during run-time. They can be used e.g. to model an -oscillating emission source. All mathematical expressions must contain -at least one time-dependent variable that is evaluated +be placed in in the :ref:`hco-cfg-base-sourcefile` column. All +expressions are evaluated during run-time. They can be used e.g. to +model an oscillating emission source. All mathematical expressions +must contain at least one time-dependent variable that is evaluated on-the-fly. Mathematical expressions are specified by using the prefix :literal:`MATH:`, followed by the mathematical expression. The expression is a combination of variables, mathematical operations, and @@ -685,18 +687,32 @@ supported: **Variable names** -- :literal:`YYYY` (current year) -- :literal:`MM` (current month) -- :literal:`DD` (current day) -- :literal:`HH` (current hour) -- :literal:`NN` (current minute) -- :literal:`SS` (current second) -- :literal:`SS` (current second) -- :literal:`DOY` (day of year) -- :literal:`DOM` (days in current month) -- :literal:`WD` (Weekday: 0=Sun, 1=Mon .. 7=Sat) -- :literal:`LH` (hour in local time) -- :literal:`PI` (the constant PI) ++----------+-----------------------------------+ +| Variable | Description | ++==========+===================================+ +| ``YYYY`` | Current year | ++----------+-----------------------------------+ +| ``MM`` | Current month (1-12) | ++----------+-----------------------------------+ +| ``DD`` | Current day (1-31) | ++----------+-----------------------------------+ +| ``HH`` | Current hour (0-23) | ++----------+-----------------------------------+ +| ``NN`` | Current minute (0-59) | ++----------+-----------------------------------+ +| ``SS`` | Current second (0-59) | ++----------+-----------------------------------+ +| ``DOY`` | Current day of year (0-365) or | +| | (0-366 in leap years) | ++----------+-----------------------------------+ +| ``DOM`` | Days in current month | ++----------+-----------------------------------+ +| ``WD`` | Weekday: (1=Sun, 2=Mon, .. 7=Sat) | ++----------+-----------------------------------+ +| ``LH`` | Hour in local time | ++----------+-----------------------------------+ +| ``PI`` | The constant PI | ++----------+-----------------------------------+ **Basic mathematical operators:** + - / * ^ ( ) @@ -709,11 +725,11 @@ the equivalent Fortran functions. .. important:: When using mathematical expressions, we recommend setting the - :option:`sourceTime` attribute to :literal:`*`, especially if you - are using the short-term variables (:literal:`HH`, :literal:`NN`, - :literal:`SS`, :literal:`LH`). This will ensure that your - expression will get evaluated on every emission time step. - + :ref:`hco-cfg-base-sourcetime` attribute to :literal:`*`, + especially if you are using the short-term variables + (:literal:`HH`, :literal:`NN`, :literal:`SS`, :literal:`LH`). This + will ensure that your expression will get evaluated on every + emission time step. .. _cfg-ex-other-math-sine: @@ -724,22 +740,22 @@ To define a sine-wave emission source of NO with an oscillation frequency of 24 hours, add the following line to section :ref:`Base Emissions ` in :ref:`the HEMCO configuration file `. Place the mathematical expression under the -:option:`sourceFile` column (i.e. the 3rd column): +:ref:`hco-cfg-base-sourcefile` column (i.e. the 3rd column): .. code-block:: kconfig 0 SINE_NO MATH:sin(HH/12*PI) - * C xy kg/m2/s NO - 1 500 -This defines an emission category (:option:`Cat`) of :literal:`1` and -hierarchy (:option:`Hier`) of :literal:`500`. No scale factors are -applied. +This defines an emission category (:ref:`hco-cfg-base-cat`) of +:literal:`1` and hierarchy (:ref:`hco-cfg-base-hier`) of +:literal:`500`. No scale factors are applied. .. important:: Mathematical expressions can produce negative emissions, which by default cause HEMCO to stop with an error. Negative emissions can be enabled by setting :literal:`Negative values: 2` in the - :ref:`Settings ` section of :ref:`the HEMCO + :ref:`Settings ` section of :ref:`the HEMCO configuration file `. In order to avoid negative values, you may specify an offset, as is @@ -808,17 +824,17 @@ in the :ref:`diagnostics configuration file ` (aka # ... etc for additional species ... To activate these diagnostics, you must specify values for -:option:`DiagnFile` and :option:`DiagnFreq` in the :ref:`Settings -` section of :ref:`the HEMCO configuration file -`: +:ref:`hco-cfg-set-diagnfile` and :ref:`hco-cfg-set-diagnfreq` in the +:ref:`Settings ` section of :ref:`the HEMCO +configuration file `: .. code-block:: kconfig DiagnFile: HEMCO_Diagn.rc DiagnFreq: 00000000 003000 -The :option:`DiagnFile` option tells HEMCO to read the diagnostic -definitions in the file that you specify (the default is -:file:`HEMCO_Diagn.rc`). Use :option:`DiagnFreq` to specify the -diagnostic frequency (i.e. the interval at which diagnostics +The :ref:`hco-cfg-set-diagnfile` option tells HEMCO to read the +diagnostic definitions in the file that you specify (the default is +:file:`HEMCO_Diagn.rc`). Use :ref:`hco-cfg-set-diagnfreq` to specify +the diagnostic frequency (i.e. the interval at which diagnostics output will be created). diff --git a/docs/source/hco-ref-guide/under-the-hood.rst b/docs/source/hco-ref-guide/under-the-hood.rst index 2f5bb27b..b5bcb106 100644 --- a/docs/source/hco-ref-guide/under-the-hood.rst +++ b/docs/source/hco-ref-guide/under-the-hood.rst @@ -84,9 +84,9 @@ the intended purpose: |br| - Similarly, :code:`EmisList` sorts the data containers by model - species, emission category (:option:`Cat`) and hierarchy - (:option:`Hier`) . This allows an efficient emission calculation - since the EmisList has to be scanned only once. + species, emission category (:ref:`hco-cfg-base-cat`) and hierarchy + (:ref:`hco-cfg-base-hier`) . This allows an efficient emission + calculation since the EmisList has to be scanned only once. List containers and generic linked list routines are defined in :file:`src/Core/hco_datacont_mod.F90`. Specific routines for @@ -242,11 +242,11 @@ These subroutines invoke the corresponding calls of all (enabled) Extension settings (as specified in the configuration file, see also :ref:`hco-cfg-ext-switches`) areautomatically read by HEMCO. For any given extension, routines :code:`GetExtNr` and :code:`GetExtOpt` can -be used to obtain the extension number (:option:`ExtNr`) and desired -setting value, respectively (see -:file:`src/Core/HCO_ExtList_Mod.F90`). Routine :code:`HCO_GetExtHcoID` -should be used to extract the HEMCO species IDs of all species -registered for this extension. +be used to obtain the extension number +(:ref:`hco-cfg-ext-switches-ExtNr`) and desired setting value, +respectively (see :file:`src/Core/HCO_ExtList_Mod.F90`). Routine +:code:`HCO_GetExtHcoID` should be used to extract the HEMCO species +IDs of all species registered for this extension. Gridded data associated to an extension (i.e. listed in section extension data of the configuration file) is automatically added to @@ -305,8 +305,8 @@ Initialization: horizontal mid points and edges (all 2D fields), the hybrid sigma coordinate edges (3D), the grid box areas (2D), and the grid box heights. The latter is only used by some extensions - (:option:`DustDead`, :option:`LightNOx`') and may be left undefined - if those are not used. |br| + (:ref:`hco-ext-list-dustdead`, :ref:`hco-ext-list-lightnox`) and + may be left undefined if those are not used. |br| |br| - Define emission species. Species definitions are stored in vector diff --git a/docs/source/hco-ref-guide/units.rst b/docs/source/hco-ref-guide/units.rst index c7918252..8f067a13 100644 --- a/docs/source/hco-ref-guide/units.rst +++ b/docs/source/hco-ref-guide/units.rst @@ -24,13 +24,13 @@ emitted species/m3]` for concentrations. No unit conversion is performed on unitless data. The classification of a data field depends on the units attribute in the -netCDF file, the :option:`SrcUnit` attribute in :ref:`the HEMCO +netCDF file, the :ref:`hco-cfg-base-srcunit` attribute in :ref:`the HEMCO configuration file `, and the unit tolerance setting in the HEMCO configuration file (see below). In general, the original units of the input data is determined based on the units attribute on the netCDF file, and data is converted to HEMCO units accordingly. The mass conversion factor is determined based on the species assigned to -the given field throuh attribute :option:`Species` in the HEMCO +the given field throuh attribute :ref:`hco-cfg-base-species` in the HEMCO configuration file. It depends on the species molecular weight (MW), the MW of the emitted species, and the molecular ratio (molecules of emitted species per molecules of species). If the input data is found @@ -46,16 +46,17 @@ input data in standard units wherever possible. SrcUnit attribute ================= -The :option:`SrcUnit` attribute in :ref:`the HEMCO configuration file -` gives the user some control on unit conversion. +The :ref:`hco-cfg-base-srcunit` attribute in :ref:`the HEMCO +configuration file ` gives the user some control on unit +conversion. -If :option:`SrcUnit` is set to :literal:`1`, data are treated as +If :ref:`hco-cfg-base-srcunit` is set to :literal:`1`, data are treated as unitless irrespective of the units attribute on the file. This option works on all fields only if unit tolerance is relaxed to :literal:`2` (for unit tolerance of :literal:`1`, the input data must be in one of the units recognized by HEMCO as :literal:`unitless`). -If :option:`SrcUnit` is set to :literal:`count`, the input data is +If :ref:`hco-cfg-base-srcunit` is set to :literal:`count`, the input data is assumed to represent index-based scalar fields (e.g. land types). No unit conversion is performed on these data and regridding will preserve the absolute values. @@ -70,11 +71,11 @@ data to kg emitted species. If a species is emitted as adjusted based on the emitted MW, species MW, and the ratio emitted MW / species MW. Only input data that is already in :literal:`kgC/m2/s` will not be converted. This behavior can be -avoided by explicitly set the :option:`SrcUnit` to the same unit as on -the input file. In this case, HEMCO will not convert between species MW -and emitted MW. This is useful for cases where the input data does not -contain data of the actual species, e.g. if VOC emissions are calculated -by scaling CO emissions (see examples below). +avoided by explicitly set the :ref:`hco-cfg-base-srcunit` to the same +unit as on the input file. In this case, HEMCO will not convert +between species MW and emitted MW. This is useful for cases where the +input data does not contain data of the actual species, e.g. if VOC +emissions are calculated by scaling CO emissions (see examples below). .. _hco-units-unit-tolerance: @@ -82,20 +83,23 @@ by scaling CO emissions (see examples below). Unit tolerance setting ====================== -The unit tolerance setting (see the :ref:`Settings ` -section of :ref:`the HEMCO configuration file ` indicates the -tolerance of HEMCO if discrepancies are found between the units found in -the input file and attribute :option:`SrcUnit` of the configuration -file. - -- If the unit tolerance is set to :literal:`0`, HEMCO stops with an - error if the :option:`SrcUnit` attribute does not exactly match with the units - attribute found in the input data. - -- Unit tolerance of :literal:`1` enables the default behavior. - -- Unit tolerance of :literal:`2` will take the :option:`SrcUnit` - attribute as the data input unit, regardless netCDF units attribute. +:ref:`hco-cfg-set-unit-tolerance` determines how HEMCO will handle +discrepancies between the :literal:`units` variable attribute +(as read from the netCDF input data file) and the :ref:`hco-cfg-base-srcunit` +setting specified in :ref:`the HEMCO configuration file `. + ++---------+-----------------------------------------------------------+ +| Value | What it does | ++=========+===========================================================+ +| ``0`` | **No tolerance**. A units mismatch will halt a HEMCO | +| | simulation. | ++---------+-----------------------------------------------------------+ +| ``1`` | **Medium tolerance**. A units mismatch will print a | +| | warning message, but will not halt a HEMCO simulation. | +| | **(Default setting)** | ++---------+-----------------------------------------------------------+ +| ``2`` | **High tolerance**. A units mismatch will be ignored. | ++---------+-----------------------------------------------------------+ .. _hco-units-unitless: @@ -200,4 +204,4 @@ Tips for testing ================ The unit factor applied by HEMCO is written into the HEMCO log file if -:option:`Verbose` is set to 2 or higher. +:ref:`hco-cfg-set-verbose` is set to :literal:`true`. diff --git a/docs/source/hco-sa-guide/config-sim.rst b/docs/source/hco-sa-guide/config-sim.rst index 0d853b66..30ce1ec2 100644 --- a/docs/source/hco-sa-guide/config-sim.rst +++ b/docs/source/hco-sa-guide/config-sim.rst @@ -60,8 +60,8 @@ The following files can be modified to set up your HEMCO standalone simulation. Specifies which fields to save out to the HEMCO diagnostics file saved in :file:`OutputDir` by default. The frequency to save out - diagnostics is controlled by the :option:`DiagnFreq` setting in - :option:`HEMCO_sa_Config.rc` + diagnostics is controlled by the :ref:`hco-cfg-set-diagnfreq` + setting in :option:`HEMCO_sa_Config.rc` For more information, please see the chapter entitled :ref:`hco-diag-configfile`. From 65c569c3b52b8115b9e3aaee6a7be2bf8d4e041a Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 18 Jul 2024 16:43:59 -0400 Subject: [PATCH 05/14] Update CONTRIBUTING.md - Added checklists - Updated broken links - Added link to GitHub pull request doc Signed-off-by: Bob Yantosca --- CONTRIBUTING.md | 43 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 38 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d86f7cc8..da6a3707 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,12 +3,18 @@ Thank you for looking into contributing to HEMCO! HEMCO is a grass-roots model that relies on contributions from community members like you. Whether you're new to HEMCO or a longtime user, you're a valued member of the community, and we want you to feel empowered to contribute. ## We use GitHub and ReadTheDocs -We use GitHub to host the HEMCO source code, to track issues, user questions, and feature requests, and to accept pull requests: [https://github.com/geoschem/geos-chem](https://github.com/geoschem/HEMCO). Please help out as you can in response to issues and user questions. +We use GitHub to host the HEMCO source code, to track issues, user questions, and feature requests, and to accept pull requests: [https://github.com/geoschem/HEMCO](https://github.com/geoschem/HEMCO). Please help out as you can in response to issues and user questions. HEMCO documentation can be found at [hemco.readthedocs.io](https://hemco.readthedocs.io). +## When should I submit updates? + +Submit bug fixes right away, as these will be given the highest priority. Please see **[Support Guidelines](https://hemco.readthedocs.io/en/stable/reference/SUPPORT.html)** for more information. + +Submit updates (code and/or data) for mature model developments once you have submitted a paper on the topic. + ## How can I submit updates? -We use [GitHub Flow](https://guides.github.com/introduction/flow/index.html), so all changes happen through pull requests. This workflow is [described here](https://guides.github.com/introduction/flow/index.html). +We use [GitHub Flow](https://guides.github.com/introduction/flow/index.html), so all changes happen through [pull requests](https://help.github.com/articles/creating-a-pull-request/). This workflow is [described here](https://docs.github.com/en/get-started/using-github/github-flow). As the author you are responsible for: - Testing your changes @@ -16,12 +22,39 @@ As the author you are responsible for: - Supporting issues and questions related to your changes ### Coding conventions -The HEMCO codebase dates back several years and includes contributions from many people and multiple organizations. Therefore, some inconsistent conventions are inevitable, but we ask that you do your best to be consistent with nearby code. +The HEMCO codebase dates back several decades and includes contributions from many people and multiple organizations. Therefore, some inconsistent conventions are inevitable, but we ask that you do your best to be consistent with nearby +code. + +### Checklist for submitting code updates + + 1. Use Fortran-90 free format instead of Fortran-77 fixed format. + 2. Include thorough comments in all submitted code. + 3. Include full citations for references at the top of relevant source code modules. + 4. Check that you have updated the `CHANGELOG.md` file. + 5. Remove extraneous code updates (e.g. testing options, other science). + 6. Submit any related code or configuration files for [GCHP](https://gchp.readthedocs.io) along with code or configuration files for [GEOS-Chem Classic](https://geos-chem.readthedocs.io). + +### Checklist for submitting data files + + 1. Choose a final file naming convention before submitting data files for inclusion to GEOS-Chem. + 2. Make sure that all netCDF files [adhere to the COARDS conventions](https://geos-chem.readthedocs.io/en/latest/geos-chem-shared-docs/supplemental-guides/coards-guide.html). + 3. [Concatenate netCDF files](https://geos-chem.readthedocs.io/en/latest/geos-chem-shared-docs/supplemental-guides/netcdf-guide.html#concatenate-netcdf-files) to reduce the number of files that need to be opened. This results in more efficient I/O operations. + 4. [Chunk and deflate netCDF](https://geos-chem.readthedocs.io/en/latest/geos-chem-shared-docs/supplemental-guides/netcdf-guide.html#chunk-and-deflate-a-netcdf-file-to-improve-i-o) files in order to improve file I/O. + 5. Include an updated [HEMCO configuration file](https://hemco.readthedocs.io/en/latest/hco-ref-guide/hemco-config.html) corresponding to the new data. + 6. Include a README file detailing data source, contents, etc. + 7. Include script(s) used to process original data. + 8. Include a summary or description of the expected results (e.g. emission totals for each species). + +Also follow these additional steps to ensure that your data can be read by GCHP: + + 1. All netCDF data variables should be of type `float` (aka `REAL*4`) or `double` (aka `REAL*8`). + 2. Use a recent reference datetime (i.e. after `1900-01-01`) for the netCDF `time:units` attribute. + 3. The first time value in each file should be 0, corresponding with the reference datetime. ## How can I request a new feature? -We accept feature requests through issues on GitHub. To request a new feature, **[open a new issue](https://github.com/geoschem/hemco/issues/new/choose)** and select the feature request template. Please include your name, institution, motivation for the feature, and all other relevant information. +We accept feature requests through issues on GitHub. To request a new feature, **[open a new issue](https://github.com/geoschem/HEMCO/issues/new/choose)** and select the feature request template. Please include all the information that migth be relevant, including the motivation for the feature. -## How to report a bug +## How can I report a bug? Please see **[Support Guidelines](https://hemco.readthedocs.io/en/stable/reference/SUPPORT.html)**. ## Where can I ask for help? From 0a610d2dbfb01c55caf88479476efec34fcb453e Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 18 Jul 2024 16:52:05 -0400 Subject: [PATCH 06/14] Removed broken link to GitHub flow in CONTRIBUTING.md Signed-off-by: Bob Yantosca --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da6a3707..3d63fe50 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,7 +14,7 @@ Submit bug fixes right away, as these will be given the highest priority. Pleas Submit updates (code and/or data) for mature model developments once you have submitted a paper on the topic. ## How can I submit updates? -We use [GitHub Flow](https://guides.github.com/introduction/flow/index.html), so all changes happen through [pull requests](https://help.github.com/articles/creating-a-pull-request/). This workflow is [described here](https://docs.github.com/en/get-started/using-github/github-flow). +We use **GitHub Flow**, so all changes happen through [pull requests](https://help.github.com/articles/creating-a-pull-request/). This workflow is [described here](https://docs.github.com/en/get-started/using-github/github-flow). As the author you are responsible for: - Testing your changes From e68ebae6ed8286e09f3a18fd505873bce074edfa Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 24 Jul 2024 11:14:34 -0400 Subject: [PATCH 07/14] HEMCO 3.9.2 release Changed version numbers in: - CHANGELOG.md - CMakeLists.txt - docs/source/conf.py - src/Core/hco_error_mod.F90 See CHANGELOG.md for a list of updates in this version. Signed-off-by: Bob Yantosca --- CHANGELOG.md | 2 +- CMakeLists.txt | 2 +- docs/source/conf.py | 2 +- src/Core/hco_error_mod.F90 | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a26af68..cd4e7862 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file. 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 +## [3.9.2] - 2024-07-24 ### Changed - RTD updates: Converted several `:option:` tags to subsections and updated references accordingly diff --git a/CMakeLists.txt b/CMakeLists.txt index d4d139d8..42e1ed0f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,7 +1,7 @@ # HEMCO/CMakeLists.txt cmake_minimum_required(VERSION 3.5) -project(HEMCO VERSION 3.9.1 LANGUAGES Fortran) +project(HEMCO VERSION 3.9.2 LANGUAGES Fortran) # Reminder: Make sure to also update version in src/Core/hco_error_mod.F90 #----------------------------------------------------------------------------- diff --git a/docs/source/conf.py b/docs/source/conf.py index 02483613..d4d89a82 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 = '3.9.1' +release = '3.9.2' # -- General configuration --------------------------------------------------- diff --git a/src/Core/hco_error_mod.F90 b/src/Core/hco_error_mod.F90 index 197c45bc..a1ed51c5 100644 --- a/src/Core/hco_error_mod.F90 +++ b/src/Core/hco_error_mod.F90 @@ -105,7 +105,7 @@ MODULE HCO_Error_Mod #endif ! HEMCO version number. - CHARACTER(LEN=12), PARAMETER, PUBLIC :: HCO_VERSION = '3.9.1' + CHARACTER(LEN=12), PARAMETER, PUBLIC :: HCO_VERSION = '3.9.2' INTERFACE HCO_Error MODULE PROCEDURE HCO_ErrorNoErr From ef736e5a455d788e20a3425b7e6f8007c7f803b7 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Fri, 26 Jul 2024 14:53:18 -0400 Subject: [PATCH 08/14] Hotfix: Fix invalid YAML syntax in .github/workflows/stale.yml .github/workflows/stale.yml - Add brackets around the list for `exempt-issue-labels`. Verified this syntax with the YAML linter yamllint.com. CHANGELOG.md - Updated accordingly Signed-off-by: Bob Yantosca --- .github/workflows/stale.yml | 2 +- CHANGELOG.md | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index c4ba4f38..c5b8f3e1 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -22,7 +22,7 @@ jobs: with: repo-token: ${{ secrets.GITHUB_TOKEN }} stale-issue-label: 'stale' - exempt-issue-labels: 'category: Discussion','category: Feature Request','deferred','help needed: Open Research Problem','help needed: Request Input from Community','never stale','TODO: Documentation' + exempt-issue-labels: ['category: Discussion','category: Feature Request','deferred','help needed: Open Research Problem','help needed: Request Input from Community','never stale','TODO: Documentation'] days-before-issue-stale: 30 days-before-issue-close: 7 stale-issue-message: 'This issue has been automatically marked as stale because it has not had recent activity. If there are no updates within 7 days it will be closed. You can add the "never stale" tag to prevent the issue from closing this issue.' diff --git a/CHANGELOG.md b/CHANGELOG.md index cd4e7862..c15c7778 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] - TBD +### Fixed +- Added brackets around `exempt-issue-labels` list in `.github/workflows/stale.yml` + ## [3.9.2] - 2024-07-24 ### Changed - RTD updates: Converted several `:option:` tags to subsections and updated references accordingly From 916d6f69e78f595f44b0672579d60e9922e224b9 Mon Sep 17 00:00:00 2001 From: jwallwork23 Date: Wed, 7 Aug 2024 10:50:09 +0100 Subject: [PATCH 09/14] Apply -fixed compiler flag to F77 files if compiling with Intel --- src/Extensions/CMakeLists.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/Extensions/CMakeLists.txt b/src/Extensions/CMakeLists.txt index 4fb4c754..58178584 100755 --- a/src/Extensions/CMakeLists.txt +++ b/src/Extensions/CMakeLists.txt @@ -26,6 +26,13 @@ add_library(HCOX STATIC EXCLUDE_FROM_ALL hcox_volcano_mod.F90 ocean_toolbox_mod.F90 ) +if (CMAKE_Fortran_COMPILER_ID STREQUAL "Intel") + set_source_files_properties( + hcox_dustdead_mod.F + $<$:hcox_tomas_dustdead_mod.F> + PROPERTIES COMPILE_FLAGS "-fixed" + ) +endif() target_link_libraries(HCOX PUBLIC HCO ) From 41605bda8a89d96f441cb8eb90f3d3c8b21f2b71 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 13 Aug 2024 13:46:30 -0400 Subject: [PATCH 10/14] HEMCO 3.9.3 release Updated version numbers in: - CHANGELOG.md - CMakeLists.txt - docs/source/conf.py - src/Core/hco_error_mod.F90 Also updated .release/changeVersionNumbers.sh to echo that the version numbers were updated in the "CHANGELOG.md" file. Signed-off-by: Bob Yantosca --- .release/changeVersionNumbers.sh | 3 ++- CHANGELOG.md | 2 +- CMakeLists.txt | 2 +- docs/source/conf.py | 2 +- src/Core/hco_error_mod.F90 | 2 +- 5 files changed, 6 insertions(+), 5 deletions(-) diff --git a/.release/changeVersionNumbers.sh b/.release/changeVersionNumbers.sh index 82f5410a..a03cbd98 100755 --- a/.release/changeVersionNumbers.sh +++ b/.release/changeVersionNumbers.sh @@ -88,7 +88,8 @@ function main() { pattern='\[.*Unreleased.*\].*' date=$(date -Idate) replace "${pattern}" "\[${version}\] - ${date}" "CHANGELOG.md" - + echo "HEMCO version updated to ${version} in CHANGELOG.md" + # Return to the starting directory cd "${thisDir}" } diff --git a/CHANGELOG.md b/CHANGELOG.md index c15c7778..6513034f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file. 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 +## [3.9.3] - 2024-08-13 ### Fixed - Added brackets around `exempt-issue-labels` list in `.github/workflows/stale.yml` diff --git a/CMakeLists.txt b/CMakeLists.txt index 42e1ed0f..332aeee5 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,7 +1,7 @@ # HEMCO/CMakeLists.txt cmake_minimum_required(VERSION 3.5) -project(HEMCO VERSION 3.9.2 LANGUAGES Fortran) +project(HEMCO VERSION 3.9.3 LANGUAGES Fortran) # Reminder: Make sure to also update version in src/Core/hco_error_mod.F90 #----------------------------------------------------------------------------- diff --git a/docs/source/conf.py b/docs/source/conf.py index d4d89a82..792fe3e3 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 = '3.9.2' +release = '3.9.3' # -- General configuration --------------------------------------------------- diff --git a/src/Core/hco_error_mod.F90 b/src/Core/hco_error_mod.F90 index a1ed51c5..cc75c328 100644 --- a/src/Core/hco_error_mod.F90 +++ b/src/Core/hco_error_mod.F90 @@ -105,7 +105,7 @@ MODULE HCO_Error_Mod #endif ! HEMCO version number. - CHARACTER(LEN=12), PARAMETER, PUBLIC :: HCO_VERSION = '3.9.2' + CHARACTER(LEN=12), PARAMETER, PUBLIC :: HCO_VERSION = '3.9.3' INTERFACE HCO_Error MODULE PROCEDURE HCO_ErrorNoErr From ce7a79563d425a2c6c28b0a4953b54b1db6e5a6f Mon Sep 17 00:00:00 2001 From: Joe Wallwork Date: Thu, 15 Aug 2024 10:01:15 +0100 Subject: [PATCH 11/14] Formatting --- src/Core/hco_config_mod.F90 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Core/hco_config_mod.F90 b/src/Core/hco_config_mod.F90 index aaa11b6e..dc90469d 100644 --- a/src/Core/hco_config_mod.F90 +++ b/src/Core/hco_config_mod.F90 @@ -2151,7 +2151,7 @@ SUBROUTINE ReadSettings( HcoConfig, IU_HCO, EOF, RC ) #endif #endif #endif - + !----------------------------------------------------------------------- ! Initialize error object if needed. ! Extract values to initialize error module and set some further From 345ad91e29dfc65d7c6acbdcbae6fa21606ce91f Mon Sep 17 00:00:00 2001 From: "Lee T. Murray" Date: Mon, 6 May 2024 19:50:24 -0400 Subject: [PATCH 12/14] Purposely breaking GCClassic/HEMCO to try to get libraries to compile for GISS-GC. The goal is to try to get GISS-GC to run, so we can go back to before this commit, and imeplement a version that does not break GCClassic. Note, the "GISS_MODEL" mostly robust, it's just edits to where MODEL_CLASSIC lines that are wrong. --- src/Core/hco_config_mod.F90 | 6 ++++-- src/Core/hcoio_read_std_mod.F90 | 15 ++++++++------- src/Core/hcoio_write_std_mod.F90 | 3 ++- 3 files changed, 14 insertions(+), 10 deletions(-) diff --git a/src/Core/hco_config_mod.F90 b/src/Core/hco_config_mod.F90 index f1b27372..aaa11b6e 100644 --- a/src/Core/hco_config_mod.F90 +++ b/src/Core/hco_config_mod.F90 @@ -2106,6 +2106,7 @@ SUBROUTINE ReadSettings( HcoConfig, IU_HCO, EOF, RC ) #ifndef MODEL_GEOS #ifndef MODEL_WRF +#ifndef MODEL_GISS #ifndef MODEL_CESM #ifndef ESMF_ !======================================================================= @@ -2149,7 +2150,8 @@ SUBROUTINE ReadSettings( HcoConfig, IU_HCO, EOF, RC ) #endif #endif #endif - +#endif + !----------------------------------------------------------------------- ! Initialize error object if needed. ! Extract values to initialize error module and set some further @@ -2430,7 +2432,7 @@ SUBROUTINE RegisterPrepare( HcoState, RC ) ! ! Thus, the following fix needs to be applied for ESMF environments, ! skipping a lot of the calculations below. -#if defined ( ESMF_ ) || defined( MODEL_WRF ) || defined( MODEL_CESM ) +#if defined ( ESMF_ ) || defined( MODEL_WRF ) || defined( MODEL_CESM ) || defined( MODEL_GISS ) ThisCover = -1 #else ! Get mask edges diff --git a/src/Core/hcoio_read_std_mod.F90 b/src/Core/hcoio_read_std_mod.F90 index 76f35994..f0d65bd7 100644 --- a/src/Core/hcoio_read_std_mod.F90 +++ b/src/Core/hcoio_read_std_mod.F90 @@ -1,9 +1,10 @@ !BOC -#if defined ( MODEL_GCCLASSIC ) || defined( MODEL_WRF ) || defined( MODEL_CESM ) || defined( HEMCO_STANDALONE ) +#if defined ( MODEL_GCCLASSIC ) || defined( MODEL_WRF ) || defined( MODEL_CESM )|| defined( MODEL_GISS ) || defined( HEMCO_STANDALONE ) ! The 'standard' HEMCO I/O module is used for: ! - HEMCO Standalone (HEMCO_STANDALONE) ! - GEOS-Chem 'Classic' (MODEL_GCCLASSIC) ! - WRF-GC (MODEL_WRF) +! - GISS-GC (MODEL_GISS) ! - CESM-GC and CAM-Chem / HEMCO-CESM (MODEL_CESM) !EOC !------------------------------------------------------------------------------ @@ -61,7 +62,7 @@ MODULE HCOIO_Read_Mod ! Parameter used for difference testing of floating points REAL(dp), PRIVATE, PARAMETER :: EPSILON = 1.0e-5_dp -#if defined( MODEL_CESM ) || defined( MODEL_WRF ) +#if defined( MODEL_CESM ) || defined( MODEL_WRF ) || defined( MODEL_GISS ) REAL(hp), PRIVATE :: GC_72_EDGE_SIGMA(73) = (/ & 1.000000E+00, 9.849998E-01, 9.699136E-01, 9.548285E-01, 9.397434E-01, 9.246593E-01, & 9.095741E-01, 8.944900E-01, 8.794069E-01, 8.643237E-01, 8.492406E-01, 8.341584E-01, & @@ -695,7 +696,7 @@ SUBROUTINE HCOIO_Read( HcoState, Lct, RC ) ! going to 72 levels. Otherwise, use MESSy (nbalasus, 8/24/2023). IF ( Lct%Dct%Dta%Levels == 0 ) THEN -#if defined( MODEL_CESM ) || defined( MODEL_WRF ) +#if defined( MODEL_CESM ) || defined( MODEL_WRF ) || defined( MODEL_GISS ) ! In WRF/CESM, IsModelLevel has a different meaning of "GEOS-Chem levels" ! because the models in WRF and CESM are user-defined and thus fixed input @@ -1350,7 +1351,7 @@ SUBROUTINE HCOIO_Read( HcoState, Lct, RC ) UseMESSy = .TRUE. ENDIF -#if defined( MODEL_CESM ) || defined( MODEL_WRF ) +#if defined( MODEL_CESM ) || defined( MODEL_WRF ) || defined( MODEL_GISS ) ! If in WRF or the CESM environment, the vertical grid is arbitrary. ! MESSy regridding ALWAYS has to be used. IF ( nlev > 1 ) THEN @@ -1379,7 +1380,7 @@ SUBROUTINE HCOIO_Read( HcoState, Lct, RC ) CALL HCO_MSG(HcoState%Config%Err,MSG) ENDIF -#if !defined( MODEL_CESM ) && !defined( MODEL_WRF ) +#if !defined( MODEL_CESM ) && !defined( MODEL_WRF ) && !defined( MODEL_GISS ) ! If we do MESSy regridding, we can only do one time step ! at a time at the moment! IF ( tidx1 /= tidx2 ) THEN @@ -1394,7 +1395,7 @@ SUBROUTINE HCOIO_Read( HcoState, Lct, RC ) ! This has to be used for WRF-GC and CESM so ifdefd out #endif -#if defined( MODEL_WRF ) || defined( MODEL_CESM ) +#if defined( MODEL_WRF ) || defined( MODEL_CESM ) || defined( MODEL_GISS ) !-------------------------------------------------------------- ! Eventually get sigma levels ! For files that have hardcoded GEOS-Chem "index"-based levels, @@ -1487,7 +1488,7 @@ SUBROUTINE HCOIO_Read( HcoState, Lct, RC ) ENDIF ! nlev>1 -#if defined( MODEL_WRF ) || defined( MODEL_CESM ) +#if defined( MODEL_WRF ) || defined( MODEL_CESM ) || defined( MODEL_GISS ) ! Input data is "never" on model levels because model levels can change! (hplin, 5/29/20) IsModelLevel = .false. #endif diff --git a/src/Core/hcoio_write_std_mod.F90 b/src/Core/hcoio_write_std_mod.F90 index 14b7688f..3b88db57 100644 --- a/src/Core/hcoio_write_std_mod.F90 +++ b/src/Core/hcoio_write_std_mod.F90 @@ -1,9 +1,10 @@ !BOC -#if defined ( MODEL_GCCLASSIC ) || defined( MODEL_WRF ) || defined( MODEL_CESM ) || defined( HEMCO_STANDALONE ) +#if defined ( MODEL_GCCLASSIC ) || defined( MODEL_WRF ) || defined( MODEL_CESM )|| defined( MODEL_GISS ) || defined( HEMCO_STANDALONE ) ! The 'standard' HEMCO I/O module is used for: ! - HEMCO Standalone (HEMCO_STANDALONE) ! - GEOS-Chem 'Classic' (MODEL_GCCLASSIC) ! - WRF-GC (MODEL_WRF) +! - GISS-GC (MODEL_GISS) ! - CESM-GC and CAM-Chem / HEMCO-CESM (MODEL_CESM) !EOC !------------------------------------------------------------------------------ From 4324bdac24d1874eb4949b2dec0b5c98089ba6bd Mon Sep 17 00:00:00 2001 From: jwallwork23 Date: Wed, 7 Aug 2024 10:50:09 +0100 Subject: [PATCH 13/14] Apply -fixed compiler flag to F77 files if compiling with Intel --- src/Extensions/CMakeLists.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/Extensions/CMakeLists.txt b/src/Extensions/CMakeLists.txt index 4fb4c754..58178584 100755 --- a/src/Extensions/CMakeLists.txt +++ b/src/Extensions/CMakeLists.txt @@ -26,6 +26,13 @@ add_library(HCOX STATIC EXCLUDE_FROM_ALL hcox_volcano_mod.F90 ocean_toolbox_mod.F90 ) +if (CMAKE_Fortran_COMPILER_ID STREQUAL "Intel") + set_source_files_properties( + hcox_dustdead_mod.F + $<$:hcox_tomas_dustdead_mod.F> + PROPERTIES COMPILE_FLAGS "-fixed" + ) +endif() target_link_libraries(HCOX PUBLIC HCO ) From 3bd6dbe991d7b2d4f0b3899fe9d6f52535854540 Mon Sep 17 00:00:00 2001 From: Joe Wallwork Date: Thu, 15 Aug 2024 10:01:15 +0100 Subject: [PATCH 14/14] Formatting --- src/Core/hco_config_mod.F90 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Core/hco_config_mod.F90 b/src/Core/hco_config_mod.F90 index aaa11b6e..dc90469d 100644 --- a/src/Core/hco_config_mod.F90 +++ b/src/Core/hco_config_mod.F90 @@ -2151,7 +2151,7 @@ SUBROUTINE ReadSettings( HcoConfig, IU_HCO, EOF, RC ) #endif #endif #endif - + !----------------------------------------------------------------------- ! Initialize error object if needed. ! Extract values to initialize error module and set some further