Implementation of HEMCO in GEOS-Chem

From Geos-chem
Jump to: navigation, search

HEMCO was implemented and validated in GEOS-Chem v10-01e. It is included in the GEOS-Chem v10-01 public release, and all later versions.



HEMCO, the Harvard-NASA Emissions Component, has now been incorporated into GEOS-Chem v10-01. This has allowed us to remove many obsolete, legacy emissions routines from GEOS-Chem. For a complete list of removed legacy emissions routines, please see our Removal of obsolete modules and files wiki post.

Most users of GEOS-Chem will just need to learn how to tell HEMCO which emissions they would like to apply to their GEOS-Chem simulations. For more information, please see the The HEMCO User's Guide. We will be providing more detailed documentation prior to the release of GEOS-Chem v10-01.

For advanced users

If you are a GEOS-Chem developer who needs to implement an emissions inventory as a new HEMCO extension, then please see our Adding new HEMCO extensions into GEOS-Chem wiki post.

If you are one of the core HEMCO developers, and would like to be able to synchronize changes made to HEMCO in GEOS-Chem back to the offical HEMCO source code repository on, then please see our HEMCO is implemented into GEOS-Chem as a git subtree wiki post.

--Bob Y. 14:23, 12 January 2015 (EST)

GEOS-Chem simulations that are compatible with HEMCO

The following table provides information on the status of connecting GEOS-Chem simulations with HEMCO.

Simulation Status Version added
Full-chemistry Fully compatible with HEMCO v10-01e
SOA Fully compatible with HEMCO v10-01e
Aerosol-only simulation Fully compatible with HEMCO v10-01e
CH4 simulation Fully compatible with HEMCO v10-01e
CO2 simulation Fully compatible with HEMCO v10-01e
POPs simulation Fully compatible with HEMCO v10-01e
Rn-Pb-Be simulation Fully compatible with HEMCO v10-01e
Tagged O3 simulation Fully compatible with HEMCO v10-01e
Hg simulation Fully compatible with HEMCO v10-01i
Tagged CO simulation Fully compatible with HEMCO v10-01g
TOMAS aerosol microphysics Partially integrated TBD
APM aerosol microphysics Need to be completely re-integrated TBD

--Melissa Sulprizio (talk) 17:01, 27 June 2016 (UTC)

HEMCO data directories

In order to run with HEMCO in GEOS-Chem v10-01 and later versions, you will need to download the HEMCO data directories. HEMCO uses data files at their native resolution whenever possible, rather than having a different set of files for each GEOS-Chem resolution (2°x2.5°, 4°x5°, etc.). Most GEOS-Chem emission files have been converted from binary punch or ASCII files to COARDS-compliant netCDF files for use in HEMCO.

Please see our HEMCO data directory wiki page for a complete list of all of the emissions inventories and other relevant data sets that can be used with HEMCO. There you will also find instructions for downloading these data to your local disk server.

--Bob Y. 18:05, 13 February 2015 (EST)

Specifying emissions for use in GEOS-Chem

GEOS-Chem run directories created from the GEOS-Chem Unit Tester include a HEMCO configuration file (HEMCO_Config.rc) tailored for the desired simulation type. Here we describe how to modify that file for GEOS-Chem simulations. If you wish to add or modify emission inventories, please see the HEMCO User's Guide for detailed information.


Under the BEGIN SECTION SETTINGS header, you can customize the directory paths and other options for HEMCO. Each configurable input is described in the table below.

Option Description
ROOT Specifies the root directory on your disk server where the HEMCO data directories are stored.
Logfile Specifies the name of the HEMCO log file (default is HEMCO.log).
DiagnPrefix Specifies the name of the HEMCO diagnostic file (default is HEMCO_diagnostics). HEMCO emission diagnostics will be saved to a COARDS-compliant netCDF file with the name [DiagnPrefix]
DiagnFreq Specifies the frequency to save out HEMCO diagnostics. Options are Hourly, Daily, Monthly, Annually, End, or Manual.
Wildcard Specifies the wildcard character (default is *).
Separator Specifies the separator character (default is /).
Unit tolerance Specify the tolerance for emission units in HEMCO. Options are:
  • 0: No tolerance. The unit in the netCDF file must match the unit specified in HEMCO_Config.rc exactly.
  • 1: High tolerance. The unit in the netCDF file doesn't necessarily have to match the unit specified in HEMCO_Config.rc, but a warning will print to the HEMCO log file.
Negative values Specify how negative values are handled in HEMCO. Options are:
  • 0: No negative values are allowed (default).
  • 1: All negative values are set to zero and a warning is prompted.
  • 2: Negative values are allowed and remain unchanged.
Verbose Specify settings for printing to the HEMCO log file. Options are:
  • 0: No verbose
  • 1: Print some debug output
  • 2: Print most debug output
  • 3: Print all debug output
Warnings Specify settings for printing to the HEMCO log file. Options are:
  • 0: No warnings
  • 1: Print only severe warnings
  • 2: Print most warnings
  • 3: Print all warnings

For a complete list of possible setting options, see the HEMCO settings section of the HEMCO User's Guide.

--Melissa Sulprizio 16:45, 24 April 2015 (EDT)

Base emission switches

HEMCO automatically calculates emissions for all fields belonging to the Base extension. Individual global and regional emission inventories (aka "collections) may be turned on and off via the true/false toggle. All entries that are within a collection bracket (e.g. (((AEIC ... )))AEIC) are only used if the corresponding collection is enabled. The default base emission settings for the geosfp_4x5_fullchem simulation are provided below as an example:

# ExtNr ExtName           on/off  Species
0       Base              : on    *
    --> AEIC              :       true
    --> BIOFUEL           :       true
    --> BOND              :       true
    --> BRAVO             :       true
    --> CAC               :       true
    --> C2H6              :       true
    --> EDGAR             :       true
    --> HTAP              :       false
    --> EMEP              :       true
    --> GEIA              :       true
    --> LIANG_BROMOCARB   :       true
    --> NEI2005           :       false
    --> NEI2011           :       true
    --> RETRO             :       true 
    --> SHIP              :       true
    --> NEI2011_SHIP      :       false
    --> MIX               :       true
    --> STREETS           :       false
    --> VOLCANO           :       true
    --> RCP_3PD           :       false 
    --> RCP_45            :       false
    --> RCP_60            :       false
    --> RCP_85            :       false

For detailed information on HEMCO base emissions, see the Base emissions section of the HEMCO User's guide.

--Melissa Sulprizio 16:45, 24 April 2015 (EDT)

Extension switches

Some emissions may depend on meteorology fields (e.g. lightning NOx, MEGAN) or non-linear parameterizations (e.g. PARANOX), so they are calculated through HEMCO extensions. HEMCO extensions can be specified using the on/off extension toggle. The species listed after the on/off toggle tell HEMCO what species are used by this extension (leave this as-is). Additional extension-specific settings may also be specified in this section. The default extension settings for the geosfp_4x5_fullchem simulation are provided below as an example:

100     Custom            : off   - 
101     SeaFlux           : on    DMS/ACET
102     ParaNOx           : on    NO/NO2/O3/HNO3
    --> LUT data format   :       nc
    --> LUT source dir    :       $ROOT/PARANOX/v2015-02
103     LightNOx          : on    NO
    --> OTD-LIS factors   :       true
    --> CDF table         :       $ROOT/LIGHTNOX/v2014-07/light_dist.ott2010.dat
104     SoilNOx           : on    NO 
    --> Use fertilizer NOx:       true
105     DustDead          : on    DST1/DST2/DST3/DST4 
106     DustGinoux        : off   DST1/DST2/DST3/DST4
107     SeaSalt           : on    SALA/SALC/Br2
    --> SALA lower radius :       0.01 
    --> SALA upper radius :       0.5
    --> SALC lower radius :       0.5
    --> SALC upper radius :       8.0
    --> Emit Br2          :       true  
    --> Br2 scaling       :       1.0 
108     MEGAN             : on    ISOP/ACET/PRPE/C2H4/ALD2
    --> Isoprene scaling  :       1.0 
109     MEGAN_Mono        : on    CO/OCPI/MONX
110     MEGAN_SOA         : off   MTPA/MTPO/LIMO/SESQ
    --> GFED3             :       false 
    --> GFED4             :       true
    --> GFED_daily        :       false
    --> GFED_3hourly      :       false
    --> CO scale factor   :       1.05
    --> POA scale factor  :       1.27
    --> NAP scale factor  :       2.75e-4
    --> hydrophilic BC    :       0.2
    --> hydrophilic OC    :       0.5
    --> FINN_daily        :       false
    --> CO scale factor   :       1.0
    --> hydrophilic BC    :       0.2
    --> hydrophilic OC    :       0.5

For detailed information on specifying HEMCO extensions, see the Extension switches section of the HEMCO User's guide.

--Melissa Sulprizio 16:45, 24 April 2015 (EDT)

Advanced settings

You typically won't need to update the sections labeled SECTION BASE EMISSIONS, SECTION SCALE FACTORS, or SECTION MASKS unless you are updating an existing emission inventory or adding a new emission inventory. In that case, we highly recommend reading the following documentation:

--Melissa Sulprizio 16:45, 24 April 2015 (EDT)

New Features Per Version

In this section we describe new features added into HEMCO and the GEOS-Chem version in which each feature became available.

--Bob Y. 14:15, 12 January 2015 (EST)

Now treat OCPI, OCPO, BCPI, and BCPO separately in HEMCO

The original implementation of HEMCO in GEOS-Chem treated carbon aerosols as black carbon (BC) and organic carbon (OC). The speciation into hydrophillic and hydrophobic carbon was done when passing HEMCO emissions to GEOS-Chem. Plots from 1-month benchmark v10-01e revealed large differences in OCPO and OCPI. To resolve these differences, we revert to splitting OC and BC into OCPI, OCPO, BCPI, and BCPO.

Comments from 1-month benchmark v10-01e:

Jeff Pierce wrote:

The HEMCO emissions should be essentially the same as the previous emissions, right? I'm curious as to why the OCPO (hydrophobic OC aerosol from combustion sources) increased so much (see the ratios). There is more than a doubling in many high-OCPO regions.
Even odder to me, OCPO has a fixed "aging" time to OCPI (hydrophilic), but the OCPI trends don't match up (as they should if transport/deposition/aging are held fixed between the two simulations). In some ways, it looks like the aging changed, but I think it's supposed to be fixed at 1.2 days.

Christoph Keller responded:

HEMCO simply includes OC and BC, and the partitioning into hydrophilic and hydrophobic parts is done outside of HEMCO. This way, the fractions (0.5/0.5 for OC and 0.8/0.2 for BC) only need to be defined and applied at one place in the code. In v10-01d, biogenic emissions (and also AEIC aircraft emissions) were just emitted as OCPI, whereas those now become separated into OCPI and OCPO. This explains the increase in OCPO and the simultaneous decrease in OCPI.
If there are concerns about this procedure, we can change the code so that HEMCO explicitly includes OCPI, OCPO, BCPI, and BCPO.

Christoph Keller wrote:

The old code included a biogenic contribution, calculated from the MEGAN terpene emissions (assuming an OC yield of 0.1). These emissions were attributed to OCPI only. In the new version, they are split into OCPI and OCPO. That’s just the way it's implemented. If there is a good (scientific) reason to change it, it can be done quite easily.

Jeff Pierce responded:

Right, this 0.1*monoterpenes is to represent biogenic SOA. It should be considered all hydrophilic organic carbon since SOA has a hygroscopicity (kappa) of around 0.1-0.2 while the hydrophobic OC has kappas much closer to zero. This should be reverted back to being all OCIL as it was before.

--Melissa Sulprizio 13:49, 20 November 2014 (EST)

Features added prior to the v10-01e 1-year benchmark

We added these updates to HEMCO in order to correct issues identified by the v10-01e 1-month benchmark. These updates are present in the v10-01e 1-year benchmark and in all higher versions, but not in the v10-01e 1-month benchmark.

1. Fix for how alkalinity is computed:
Christoph Keller wrote:
The alkalinity (and number density) are still directly obtained from the SSA emission flux. The problem is that in any given grid box, the alkalinity (in kg) at a given level is set to the total SSA flux for that grid box, e.g.
         ALK(I,J,L) = SSA(I,J) * AREA(I,J) * EMIS_TS
So the total column alkalinity for any given I,J location is much higher than the total SSA emissions at this location. I think it should be:
         ALK(I,J,L) = FRAC_OF_PBL(I,J,L) * SSA(I,J) * AREA(I,J) * EMIS_TS
where FRAC_OF_PBL(I,J,L) makes sure that the total emitted SSA are distributed uniformly within the PBL.
This fix will affect the concentrations of SO4s and NITs.
2. Fixes in the HEMCO PARANOX module:
Christoph Keller wrote:
I found the problem with PARANOx: I didn’t take into account the molecular weights when converting NO fluxes to HNO3 and O3. This resulted in very large differences in O3 and HNO3 w/r/t prior versions. I also a added more thorough division-by-zero check when calculating the ozone dry deposition rate from PARANOX.
3. Now treat OCPI, OCPO, BCPI, and BCPO separately in HEMCO .
4. Fixes for the BIOGENIC_OCPI diagnostic. This diagnostic was not being computed properly in the v10-01e 1-month benchmark and returned all zeroes. This has now been corrected. However, this diagnostic is disabled in all SOA simulations (it will return all zeros).

--Bob Y. 15:41, 8 January 2015 (EST)

Features added in v10-01f

As described in the previous section, a few minor updates were added to HEMCO just prior to the GEOS-Chem v10-01e 1-year benchmark.

In addition to these updates, the following modifications were added to HEMCO in GEOS-Chem v10-01f:

Christoph Keller wrote:

The main updates since the v10-01e 1-year benchmark are:
  1. Strat Bry fields that are now read through HEMCO. Br2 concentrations are obtained from BrCl data by preserving Br, e.g. by dividing molecular BrCl by a factor of 2. This is different to the old code, where 1 mol BrCl lead to 1 mol Br2.
  2. HEMCO can now map between native and reduced GEOS grids. For now, this only works within the same model version, e.g. native GEOS-5 onto reduced GEOS-5. I’m about to bring in some additional code that allows us to remap GEOS-5 fields onto GEOS-4 levels.
All other changes are mostly low-level stuff or added functionality that shouldn’t really affect the benchmarks. These are:
  1. The HEMCO MEGAN extension is now in flexible precision.
  2. The historical meteorological data (10-day temperature averages, previous day's LAI, etc.) used in MEGAN can now be read from restart instead of doing a ‘cold’ start.
  3. Masks can now be applied to individual scale factors, e.g. it is possible to enable a scale factor only over a particular region. This was implemented upon request of a number of people, but is currently not used in any of the (benchmark) simulations.
  4. The PARANOx look-up-tables can now be provided in ASCII format. This allows us to run PARANOx in GEOS-5 without having to deal with the netCDF input files and/or the little endian / big endian binary file issues.
  5. HEMCO can now read index-sorted data from an ASCII file and then map these data based on their indices onto the simulation grid. This allows us to define e.g. country-specific scale factors. This is currently not used in any of the benchmark simulations. More information about this option can be found in the HEMCO manual.

--Melissa Sulprizio 16:04, 7 January 2015 (EST)

Fix for segmentation fault when emissions are turned off

In GEOS-Chem v10-01g, we fixed a bug in HEMCO that caused simulations to die with a segmentation fault when emissions were turned off in the input.geos file.

Bob Yantosca wrote:

If you have these settings in input.geos:
   %%% EMISSIONS MENU %%%  :
   Turn on emissions?      : F
   Emiss timestep (min)    : 60
   HEMCO Input file        : HEMCO_Config.rc
Then you get a seg fault on the RED line of code in routine GetHcoVal (in module file GeosCore/hcoi_gc_main_mod.F90):
    ! GetHcoVal begins here

    ! Init
    IF ( PRESENT(Emis) ) Emis = 0.0_hp
    IF ( PRESENT(Dep ) ) Dep  = 0.0_hp

    ! Define tracer ID to be used. This is only different from the
    ! passed tracer ID if some species mapping occurs at this level.
    tID = TrcID

    ! HEMCO species ID corresponding to this GEOS-Chem tracer
    IF ( tID > 0 ) HcoID = M2HID(tID)%ID ID
The issue is that if you turn off HEMCO, then the M2HID pointer never gets initialized. Turning off emissions in will also give us this error in the strat chem module:
   HEMCO ERROR: Container not found: GEOSCCM_Br2_DAY
   ERROR LOCATION: HCO_GetPtr_3D (hco_emislist_mod.F90)

   GEOS-CHEM ERROR: Cannot get pointer from HEMCO! Stratospheric Bry data is 
   expected to be listed in the HEMCO configuration file and the GMI_StratChem
   extension must be enabled. This error occured when trying to get field 
   GEOSCCM_Br2_DAY STOP at Set_BryPointers (start_chem_mod.F90)
        - CLEANUP: deallocating arrays now...
Which is probably to be expected now that HEMCO handles the strat Bry emissions.

Christoph Keller wrote:

I’ve updated my code so that HEMCO can be used with LEMIS = F. The changes are:
1. In main.F, the HEMCO routines are now always called, even if LEMIS is set to FALSE. This ensures that HEMCO can still be used to read non-emission data such as the stratospheric Bry fields.
2. In hcoi_gc_main_mod.F90, there are now two checks for the LEMIS flag: If LEMIS is disabled, no HEMCO species are defined in subroutine Get_nHcoSpc, and as a result HEMCO will not calculate any emissions. Similarly, all HEMCO extensions will be deactivated by forcing all extension numbers to invalid values (—> CALL SetExtNr(… ).
3. Because all extensions are now automatically ignored when LEMIS is set to FALSE, I recommend moving the Strat Bry fields from the extension section into the ‘regular’ base emissions section. This way, these fields are always considered. So you'll need to add the following lines to the end of the BASE EMISSIONS section in the HEMCO configuration file:
     # --- Stratospheric Bry data ---
     0 GEOSCCM_Br_DAY      $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$   BR     2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_Br2_DAY     $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$   BRCL   2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_BrO_DAY     $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$   BRO    2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_BrNO3_DAY   $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$   BRONO2 2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_HBr_DAY     $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$   HBR    2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_HOBr_DAY    $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$   HOBR   2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_Br_NIGHT    $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$ BR     2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_Br2_NIGHT   $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$ BRCL   2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_BrO_NIGHT   $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$ BRO    2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_BrNO3_NIGHT $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$ BRONO2 2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_HBr_NIGHT   $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$ HBR    2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_HOBr_NIGHT  $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$ HOBR   2007/$MM/1/0 C xyz pptv * - 60 1
You should also remove the corresponding entries in the extensions section, including the extension toggle (GMI_StratChem) itself. If you prefer having the strat Bry fields listed in the extensions section, we can update the SetExtNr routine so that it doesn’t reset the extension number associated with GMI_StratChem. Just let me know if you’d prefer that solution.
4. With LEMIS set to FALSE, my code currently stops with an error because some of the emission diagnostics don’t work any more. I assume it’s expected that user disable the corresponding diagnostics in input.geos (which I didn’t), so I didn’t bother to account for that (e.g. in diag3.F, etc.).

--Bob Y. 14:08, 12 January 2015 (EST)

Features added in v10-01h

The following modifications were added to HEMCO in GEOS-Chem v10-01h.

Christoph Keller wrote:

1. PARANOX update: PARANOx now includes the latest patch provided by Chris Holmes: The look-up-table data can be read from netCDF or from txt file (the later is useful for ESMF!), the parameterization now takes into account wind speed, and N dry deposition is included via loss of HNO3. In addition, the total tropospheric column mass is now used to calculate the dry deposition frequencies (s-1), instead of the surface grid box mass only (following the suggestion of Chris Holmes).
The input data format and source directory need to be specified in the HEMCO configuration file (this replaces entries FracNOx table and IntOPE table):
   102     ParaNOx           : on    NO/NO2/O3/HNO3
       --> LUT data format   :       nc
       --> LUT source dir    :       $ROOT/PARANOX/v2015-02
2. Strat prod/loss update: The stratospheric production and loss data is now read through HEMCO. I had to slightly modify the original netCDF files. It also requires an update of the HEMCO configuration file. Look for all the GMI_LOSS_XXX and GMI_PROD_XXX fields.
3. Local time computation update: Local times can now be calculated based on a time zone map provided through the HEMCO configuration file. This file is expected to be named TIMEZONES and must contain the UTC offsets (in hours) for each grid box. These offsets will then be used when calculating the local times. If no such file is provided - or an invalid value is encountered in a given grid box (e.g. -999) - local times are calculated with the previous method, e.g. as a function of longitude (assuming each time zone spans 15 degrees in longitudinal direction).
A time zone file at 1x1 degrees is stored in:
The corresponding entry can also be found in the HEMCO configuration file listed above (field TIMEZONES).
4. Non-emissions data update: It is now legal to set the extension number (ExtNr) in the configuration file to the wildcard character (*). This is useful for data that shall be read/regridded by HEMCO but that is not used for emission calculation, such as the stratospheric data. Note that these data will only be read if the corresponding species name is a valid GEOS-Chem tracer.
5. Regridding update: Horizontal regridding of index-based (e.g discrete) data is now done with the map_a2a algorithm. There were some problems with the original implementation of the index-based regridding (using the MESSy regridding tool NCREGRID), so I switched back to map_a2a. Index based regridding does not interpolate between grid boxes but picks the value with the highest contribution in a given grid box. This should only be applied to data with (few) discrete values, e.g. land types or time zones. As previously, the unit attribute in the configuration file must be set to ‘count’ to denote index-based data.
6. CO2 simulation update: Some minor fixes in the treatment of weekly data. I made these changes mostly for Ray Nassar and the CO2 simulation. In general, the WD time attribute should always be used for weekly data, e.g. the time stamp in the HEMCO configuration file should be set something like 2000/1/WD/0, 2005/1-12/WD/0, etc.
7. Time indexing update: If you set the C/R/E flag in the configuration file to R (= range), the corresponding data will be used as long as the simulation date is within the time range provided via attribute sourceTime - even if the netCDF data does not cover that range completely. For example, assume you have a scale factor file that contains data from 2003 to 2010, and the corresponding entry in the configuration file looks like this:
   123 THIS_SCALE /path/to/file/ VARIABLE 2007-2100/1/1/0 R xy 1 1
The scale factor is then considered for any simulation year between 2007 and 2100. For simulation years 2007-2010, the corresponding netCDF data is used. For all years afterwards, the closest available time slice (e.g. year 2010) is used. For simulation dates outside of 2007-2100, the scale factor is ignored altogether (even though the netCDF contains data for years 2003-2006!).
8. Configuration file update #1: The entries in the configuration file can now be grouped into 'collections' that can be enabled/disabled at the beginning of the HEMCO configuration file. I moved section 'extension switches' almost to the top of the HEMCO configuration file and added an entry for the 'base' extension. A collection can then be defined as a setting of that extension:
   # ExtNr ExtName           on/off  Species
   0       Base              : on    *
       --> AEIC              :       true
       --> BIOFUEL           :       true
       --> BOND              :       true
All entries that are within a collection bracket are only used if the corresponding collection is enabled. The brackets must be on a separate line: (((CollectionName to open a collection, )))CollectionName to close it. e.g.:
   0 AEIC_NO   $ROOT/AEIC/v2014-10/  NO       2005/1-12/1/0 C xyz kg/m2/s NO   110/115 20 1
It is also possible to nest collections.
9. Configuration file update #2: It is now possible to assign multiple emission categories to one emission field, e.g. EMEP_NO can cover 2 categories (e.g. anthropogenic + biofuel). For these fields, all emissions are written into the first listed category, and emissions of the 2nd category become zero (but they may cancel out other emissions with lower hierarchy in that region, e.g. EDGAR biofuel emissions).
10. Configuration file update #3: I modified the HEMCO configuration file quite a bit. In particular, I moved section 'extension switches' to the beginning and removed section 'extension data'. These are now included in section 'base emissions'. I also modified some of the base emission entries, e.g. by assigning category 2 to all biofuel data, etc. I also uncommented some VOC biofuel inventories that are not included in RETRO (HAC, GLYC) and added the strat-chem prod/loss files and the time zone file.
11. GEOS-Chem interface update: I made some slight updates to hcoi_gc_main_mod.F90 so that it now contains a routine to perform some input data error checks (CheckSettings). It mainly makes sure that the switches defined in section 'extension switches' of the HEMCO configuration file are sane. For example, I added a switch SHIPNO_BASE that should only be turned on if PARANOx is turned off. Likewise, I added a switch BOND_BIOMASS that must not be enabled if GFED3 or FINN is being used.
12. Emissions and dry deposition updates: Emissions and dry deposition removal are now applied in one module: GeosCore/mixing_mod.F90. If the non-local PBL mixing is used, mixing within the PBL is done in GeosCore/vdiff_mod.F90 (called from within GeosCore/mixing_mod.F90), and all emissions above the PBL become added to the tracer array afterwards. If the full-mixing scheme is used, dry deposition and emissions are applied to the tracer array, and tracer concentrations are evenly mixed within the PBL afterwards via module GeosCore/pbl_mix_mod.F90. Any emissions / dry deposition removals previously done in other parts of the code (GeosCore/calcrate.F, GeosCore/dust_mod.F, GeosCore/carbon_mod.F, etc.) are deactivated. The process flow in GEOS-Chem now looks like this (same for the non-local PBL and full-mixing scheme):
  1. Calculate PBL heights
  2. Convection
  3. Calculate dry deposition rates
  4. Calculate emissions rates
  5. Turbulence: this will apply emissions and dry deposition, plus non-local PBL mixing or full mixing.
  6. Chemistry
  7. Wet deposition
IMPORTANT NOTE: As a result of these updates, the ND44 dry deposition flux diagnostic (i.e. GAMAP category DRYD-FLX) is now archived in units of molec/cm2/s for all GEOS-Chem simulations. In prior GEOS-Chem versions, some simulations such as the Rn-Pb-Be simulation, the ND44 drydep fluxes were archived in units of kg/s. Therefore, when you are analyzing GEOS-Chem model output from GEOS-Chem v10-01, please make sure to modify your data processing codes to expect drydep fluxes in molec/cm2/s.
13. HEMCO updates:
  1. All GEOS-Chem species are now registered as potential HEMCO species (plus some more if needed, e.g. SESQ for MEGAN). This simplifies module hcoi_gc_main_mod.F90.
  2. Some bug fixes have been added to make sure that GEOS-Chem / HEMCO runs properly if emissions are disabled.
14. Diagnostics updates:
  1. The container ID can now be specified by the user when creating a diagnostics, instead of having it set by HEMCO. This allows identification of HEMCO diagnostics via its ID’s instead of the container name.
  2. Similar to ND44, the emission fluxes added to GEOS-Chem are now written into a diagnostics. They are defined in GeosCore/diagnostics_mod.F90 and filled in GeosCore/mixing_mod.F90 and GeosCore/vdiff_mod.F90. This is for the DEVEL flag only.
15. Configuration file update #4: The Hermann & Celarier (1997) UV Albedo data—required by the FAST-JX v7.0 photolysis mechanism—are now read from netCDF files via HEMCO. (These data were previously read from bpch files.) We have added these lines to the HEMCO configuration file:
   # --- UV albedo, for photolysis (cf Hermann & Celarier, 1997) ---
   * UV_ALBEDO $ROOT/UVALBEDO/v2015-03/ UVALBD 1985/1-12/1/0 C xy 1 * - 1 1
These data will be read for full-chemistry simulations or aerosol-only simulations in which chemistry is activated. The +UValbedo collection will activated automatically by GEOS-Chem for these simulations.
16. GFED4: GFED-4 biomass burning is now included. GFED-4 is basically the same as GFED-3, so I’m using exactly the same HEMCO extension and simply adjust the input data.
17. Include statement for configuration file: It is now possible to include entire configuration files in the master HEMCO configuration file (HEMCO_Config.rc). This way, we can keep the HEMCO master configuration file more clear. Configuration files can be included with the statement:
   >>>include /path/to/ConfigFile/ConfigFile.rc
I haven’t added yet any include statements to the master HEMCO configuration file HEMCO_Config.rc. I leave it up to you if we want to use that feature and which files to 'outsource' from HEMCO_Config.rc, but I think candidates include the StratChem files and the RCP data.
18. Token $CFDIR: It is now possible to use the token $CFDIR to refer to the directory of the HEMCO configuration file. This is useful if the input data is located in the same directory as (or a subdirectory of) the configuration file. For example, if the configuration file is in /home/ckeller/HEMCO/emis/BROMINE/HEMCO_Config_BromoCarb.rc and contains an entry for file </tt>$CFDIR/</tt>, the file path will be evaluated as </tt>/home/ckeller/HEMCO/emis/BROMINE/</tt>. This provides us with a possibility to store and exchange data along with the corresponding HEMCO configuration file snippets.
19. Exclude brackets: .not.CollectionName: I added the option to define configuration file data collections that shall be excluded if a given collection name is enabled. This can be done by adding .not. in front of the collection name, e.g. .not.FINN_daily. This is useful to denote data that shall only be used if another collection is not enabled.
20. HEMCO Restart variables: I added a restart module that let's you quickly define and obtain restart variables. These variables will be automatically written to the HEMCO log-file and can then be used for a 'warm' restart. Several extensions currently use restart variables, e.g. hcox_soilnox_mod.F90. The module hco_restart_mod.F90 contains the restart subroutines, and examples on how to use them can be found in hcox_soilnox_mod.F90 or hcox_megan_mod.F.
21. Verbose mode: 0-3: The verbose parameter is not a logical switch any more but a number between 0 (no verbose) and 3 (very verbose). There is still some need to clean up the HEMCO log file, but this is a first step.
22. Monthly emission totals written to GEOS-Chem log file: In DEVEL-mode, the monthly emission totals are now written into the GEOS-Chem logfile. The code snippet that does that is in diagnostics_mod.F90. This is a first attempt to restore some of the emission print statements that were in the old code.

--Bob Y. 14:41, 10 March 2015 (EDT)
--Melissa Sulprizio 13:36, 19 March 2015 (EDT)

Features added in v10-01i

The following modifications were added to HEMCO in GEOS-Chem v10-01i.

Christoph Keller wrote:

This tag includes the following updates:
1. Various updates to PARANOX:
  • Bug fix in calculation of H2O ambient air concentration and the calculation of the current date SZA;
  • The loss fluxes of O3 and HNO3 are now passed in kg/m2/s via the HEMCO diagnostics instead of converting them to a deposition velocity (and then recalculating a flux from this value);
  • Restored the ND63 diagnostics. For more information, see our Ship emissions wiki page.
  • The SUNCOS values for the previous 5 hours are now saved out to the HEMCO restart file.
2. Diagnostics update: Collections are now organized in a linked list. This allows the user to define as many collections as desired. The output frequency is now assigned to the collection, not the individual fields, e.g all fields of a collection have now the same output frequency. The output frequency of the default HEMCO diagnostics collection, as well as fields to be added to this collection, can now be defined through the HEMCO configuration file (optional). The HEMCO restart collection is now written out alongside with the regular GEOS-Chem restart fields.
3. HEMCO has now two run phases: Phase 1 reads the HEMCO list, phase 2 calculates emissions. This allows us to correctly update fields and handle diagnostics that are not related to emissions.
4. Masks update: Masks can now be treated as fractions (instead of binary values).
5. Environmental fields update: Environmental fields used by HEMCO (stored in the ExtState object) can now be provided via the HEMCO I/O infrastructure, e.g by reading them directly from disk. This is particularly useful for the standalone version, but can also be very helpful for sensitivity studies (e.g. to use other wind fields, etc.).
6. Various updates to the HEMCO standalone code
7. Modifications to on/off switches in the HEMCO configuration file
  • It is now possible to use extension names for the switches, e.g.:
     ... etc...
  • You can now combine multiple switches by the word .or., e.g.:
     ... etc ...

--Melissa Sulprizio 17:44, 20 April 2015 (EDT)
--Bob Y. 15:01, 21 April 2015 (EDT)

Features added as last-minute fixes to v10-01

The following updates to HEMCO were added as last-minute fixes to GEOS-Chem v10-01. These were discovered after the last v10-01 benchmarks had been submitted.

  1. Bug fix to avoid out-of-bounds errors when the MEGAN_mono extension is turned off
  2. Bug fix to restore archiving biogenic CO emissions from monoterpenes into the BIOGENIC_CO diagnostic

--Bob Y. 12:15, 29 April 2015 (EDT)

Features added during the public comment period prior to v10-01 release

The following updates were added immediately prior to the GEOS-Chem v10-01 release, during the Period of public comment.

Updates for HEMCO standalone

Christoph Keller wrote:

[I added] ... some minor fixes and a couple of updates that are primarily important for the HEMCO standalone application:
  1. The HEMCO standalone now works over nested domains.
  2. It is now possible to apply scale factors to met fields that are read through the HEMCO configuration file. This is really useful for sensitivity studies, e.g. to scale wind speed by 10% and see what the response of the emissions to that would be.
  3. Base emissions can now have a dynamic number of scale factors (used to be limited to a fixed number).

Updates for FINN and vertical indexing

Christoph Keller wrote:

There was a bug in HCO_EmisAdd that prevented the FINN [biomass] diagnostics from being written. The problem only occurred when you passed a CAT=-1 and HIER=-1 to HCO_EmisAdd. I think that was only the case in FINN. This is now fixed.
There are a couple [more] updates....Those are adding more flexibility to the definition of the vertical dimension in the HEMCO configuration file (attribute SrcDim). For example, you can use
  • xy1 to read only the first level of the input data
  • xy25 to read levels 1-25
  • xy-1 to read one level but in reversed order (e.g. the top level of the input data is read and put into HEMCO level 1)
  • xy-25 to read the top 25 levels of the input data but add them to HEMCO levels 1-25 (in reversed order)…
This update shouldn’t affect the standard code!

--Bob Y. (talk) 20:29, 21 May 2015 (UTC)

Updates to fix an issue in PARANOX

Christoph Keller wrote:

I have added an update to the PARANOX code that gets rid of the PARANOX restart fields, and is more stable during run time. Both SUNCOS and SUNCOS - 5 hours used by HEMCO are now calculated from within HEMCO. Also, the PARANOx restart variables in the HEMCO restart file are not needed anymore and can thus be removed, e.g.:
Finally, the PARANOX_SUNCOS entries in HEMCO_Config.rc are not needed any more, and can be deleted:
   # --- PARANOx restart variables
This update will create some differences compared to the previous code because all HEMCO SUNCOS values are now at the emission time step and not at the chemistry mid-point, e.g. HEMCO now consistently uses SUNCOS instead of a mix of SUNCOS and SUNCOSmid. The latter has caused some confusion and could cause problems at high resolutions.

--Bob Y. (talk) 20:43, 27 May 2015 (UTC)

The HEMCO standalone executable is now built with GEOS-Chem

Christoph Keller wrote:

The compilation of GEOS-Chem now also produces an executable for the HEMCO standalone code, located in HEMCO/Interfaces/hemco_standalone.x. I think this is pretty useful if people want to test emission updates or only run emissions. Up to now, people needed to download the full HEMCO standalone code, which is the same code used in GEOS-Chem plus an example directory.
For now, the GEOS-Chem compilation just produces the HEMCO standalone executable, but no example data and/or HEMCO standalone run directory is provided. We will add a sample run directory shortly, perhaps to the GEOS-Chem unit tester.

--Bob Y. (talk) 15:21, 10 June 2015 (UTC)

Updates to facilitate running in HPC environments

Christoph Keller wrote:

There are a few other updates that are mostly important for runs within GEOS-5 and should not affect the standard code:
  1. Make sure that all longitude values are in the range of –180.0 to +180.0 degrees East. GEOS-5 internally uses 0 to 360 degrees East, which causes some problems in longitude look-ups.
  2. I added an extension (HEMCO/Extensions/hcox_aerocom_mod.F90) to read volcanic data from daily ascii tables. This is what we are going to use in the GEOS-5 very high resolution simulation. At the moment, this extension will not work in standard GEOS-Chem because I haven't copied the AeroCom ascii tables onto the Harvard servers. I can do this if there is interest.
  3. You can now emit 2D data into levels other than the surface level by specifying this via attribute srcDim in the HEMCO configuration file. For example, to emit EDGAR No 1A1a data into GEOS-Chem level 5:
     0 EDGAR_NO_1A1a  $ROOT/EDGARv42/v2015-02/NO/ emi_no 1970-2008/1/1/0 C xyL5 kg/m2/s NO  1/40/25/30  1 2

--Bob Y. (talk) 15:21, 10 June 2015 (UTC)

Miscellaneous updates

HEMCO will now recognize the unit strings % and percent as unitless quantities (i.e. they will not be treated as fluxes). This allows you to more accurately specify the units of certain types of data, such as the UV Albedo data:
   # --- UV albedo, for photolysis (cf Hermann & Celarier, 1997) ---
   * UV_ALBEDO $ROOT/UVALBEDO/v2015-03/ UVALBD 1985/1-12/1/0 C xy percent * - 1 1

--Bob Y. (talk) 17:57, 16 June 2015 (UTC)

Features added in v11-01e

The base version of HEMCO was updated to v1.1.016 in GEOS-Chem v11-01e (approved 04 Jan 2016).

The table below describes the new HEMCO features that are contained in v11-01e, and the HEMCO version in which they were first introduced.

HEMCO version Description
06 Oct 2015
Christoph Keller wrote:

I have made several updates to HEMCO that fix some bugs but also add a number of new features. The most recent version number is v1.1.011.

In short, the new version of HEMCO allows a more flexible diagnostics output interval (e.g. every two hours, every three hours, etc.), supports any token set by the user in the settings section, can calculate time-averaged fields, and accepts netCDF files with an arbitrary additional dimension (e.g. netCDF files that contain a record dimension). The HEMCO users guide is up to date and all updates should be described in more detail there.

The averaging flag might be particularly useful for emission fields with a large inter-annual variability, i.e. when it may be better to use an average of all available years rather than simply use the latest available year (e.g. GFED or volcano emissions). So it might be a good idea to update the default HEMCO configuration file accordingly, but this is probably something that the emissions group should decide upon?

This update also includes some changes to the netCDF I/O routines in the NcdfUtil/ directory.

In addition to the HEMCO updates, this code also includes a tendencies module (tendencies_mod.F90). The idea is that this module automatically calculates species tendencies (v/v/s) of various processes (transport, chemistry, convection, etc.) and writes them to netCDF. This is still very experimental and all settings have to be set manually within tendencies_mod.F90. But it works and it could be a very useful tool, I think.

06 Nov 2015
  • Treat MEGAN restart variables (historic surface temperature and radiation) as running averages;
  • Bug fix to make sure that sea salt aerosol calculations work on curvilinear grids;
  • Added DiagnTimeStamp to control diagnostics time stamp location;
  • Seaflux uses HEMCO landtypes instead of land fraction;
  • Bug fix: restrict day to last day of month when searching for file names.
19 Nov 2015
  • Allow mask grid points.
23 Nov 2015
  • Bug fix when interpolating/averaging between multiple files.
07 Dec 2015
  • Bug fix in GEOS5 -> GEOS-4 regridding
  • Fixed a bug in syncing the MEGAN LAI_PREVDAY variable
14 Dec 2015
Christoph Keller wrote:

I added a few more updates to HEMCO (now v1.1.016) and put together a HEMCO standalone run directory that you might find useful for testing, e.g. if you implement new inventories or want to quickly run 1 year of emissions:

HEMCO standalone run directory (for testing, sensitivities, etc.)

The HEMCO standalone run directory is set up in such a way that you can directly use the HEMCO executable produced by GEOS-Chem (or the one generated by the HEMCO standalone code) as well as the original GEOS-Chem HEMCO configuration files without any modifications to it.

The trick is to use a ‘master’ HEMCO configuration file (HEMCO_sa_Config.rc) that defines all information specific to the HEMCO standalone code, such as grid information file, species definitions, met fields needed by emission parameterizations, etc. Everything else is taken from the regular HEMCO_Config.rc by ‘linking’ down to it using the include syntax:

      >>>include HEMCO_Config.rc

This way, HEMCO_sa_Config.rc only needs to contain the stuff that is specific to HEMCO standalone but all the "real" emission information is obtained straight from the regular HEMCO configuration file. You can then run the HEMCO standalone code by referring to the master configuration file:

      ./hemco_exe_gc.x HEMCO_sa_Config.rc</tt>

where hemco_exe_gc.x is the executable created during compilation of GEOS-Chem.

Note that the entries in the HEMCO master configuration file take precedence over the ones in the linked configuration files. Thus, if the same setting or option is defined in both HEMCO_sa_Config.rc and HEMCO_Config.rc, HEMCO will use the one from HEMCO_sa_Config.rc. I used this to disable ParaNOx and SoilNOx (both of them would need to read species concentration fields that I do not have available). You could also disable e.g. NEI2011 by setting it to false in the master file (i.e. In HEMCO_sa_Config.rc):

      0    Base    : on *
        —> NEI2011 : false

Running with the HEMCO standalone code (instead of the executable created when compiling GEOS-Chem)

This works the same way with the HEMCO standalone code (the code that ships without GEOS-Chem):

      ./hemco_exe_sa.x HEMCO_sa_Config.rc

However, in order to get the vertical regridding right the HEMCO standalone code needs to be compiled with the GEOS_FP flag. This can be done via compiler option ‘EXTRA_FLAGS’. The compilation sequence for the HEMCO standalone code should look as follows:

      make -j4 EXTRA_FLAGS='–DGEOS_FP -DGRID4x5'

--Bob Yantosca (talk) 18:48, 4 January 2016 (UTC)

Features added in v11-01f

The table below describes the new HEMCO features that are contained in v11-01f, and the HEMCO version in which they were first introduced.

HEMCO version Description
19 Jan 2015
  • Added option DiagnRefTime to explicitly specify output diagnostics reference time unit.

--Bob Yantosca (talk) 21:34, 19 January 2016 (UTC)

Features added in v11-01g

The table below describes the new HEMCO features that are contained in GEOS-Chem v11-01g and the HEMCO version in which they were first introduced.

HEMCO version Description
30 Aug 2016

--Melissa Sulprizio (talk) 16:34, 30 August 2016 (UTC)

Features added in v11-01j

These updates was validated with the 1-month benchmark simulation v11-01j and approved on 03 Dec 2016

The table below describes the new HEMCO features that are contained in GEOS-Chem v11-01j and the HEMCO version in which they were first introduced.

HEMCO version Description
14 Oct 2016
Christoph Keller wrote:

The updates in HEMCO v2 are mostly structural. The most important changes are:

1. Bug fix in hcox_paranox_mod.F90 (line 632): The deposition flux is now archived as absolute (i.e. positive) number. Without this fix, the merged code should give zero-diff to v11-01h.

2. The timezones mask file should be updated to file HEMCO/TIMEZONES/v2015-02/

The current timezones mask file does not work properly in grid cells with large ocean overlap. The problem is that the ocean values are netCDF _FillValues that become zero within HEMCO. As a quick fix I updated the timezones file to use a value of –5000 in all ocean cells, which then forces HEMCO to determine the time zone based on longitude in those cells.

3. HEMCO v2.0.003 now accepts scale factors for extension fields. For example, to uniformly scale GFED_TEMP by a factor of 2:

   111 GFED_TEMP $ROOT/GFED4/v2015-10/$YYYY/GFED4_gen.025x025.$YYYY$ DM_TEMP 1997-2014/1-12/01/0 C xy kgDM/m2/s * 1234 1 1
   1234 GFED_TEMP_SCALE 2.0 - - - xy 1 1

This update requires that all HEMCO extension fields are evaluated on every emission time step. I don’t expect this to have a notable impact on run time (and it didn’t in my short test runs). However, if you find that it does slow down the benchmark simulation let me know and we can revert to version v2.0.002 (which does not include this update).

4. HEMCO v2 contains additional options to emit 2D fields across multiple vertical levels. For instance, to release 1.0 kg/m2/s of NO into levels 1-5, you can use:

   0 NO_MULTILEVELS 1.0 - - xyL=1:5 kg/m2/s NO – 1 1

The emissions are then spread across the lowest 5 model levels based upon the model level thicknesses. Instead of specifying the model levels it is also possible to specify the altitude in meters or use PBL for the planetary boundary layer. For example, the following are all legal:

   0 NO_MULTILEVELS 1.0 - - xyL=1:2500m     kg/m2/s NO – 1 1  —> emits from surface level to 2500m
   0 NO_MULTILEVELS 1.0 - - xyL=1000m:5000m kg/m2/s NO – 1 1  —> emits from 1000m to 5000m
   0 NO_MULTILEVELS 1.0 - - xyL=500m:17     kg/m2/s NO – 1 1  —> emits from 500m to level 17
   0 NO_MULTILEVELS 1.0 - - xyL=1:PBL       kg/m2/s NO – 1 1  —> emits from surface level to PBL top

5. From a coding perspective the HEMCO state object (HcoState) now has to be passed to each routine. HcoState contains all HEMCO related information (such as callback information for error messages). This update was needed to enable the execution of multiple HEMCO instances at the same time. This won’t affect you unless you have to touch HEMCO related code.

6. I have updated the passive tracer code so that it works with the new species database.

--Melissa Sulprizio (talk) 21:22, 20 October 2016 (UTC)

Features added in v11-02a

These updates were included in v11-02a and approved on 12 May 2017.

The table below describes the new HEMCO features that are contained in GEOS-Chem v11-02a and the HEMCO version in which they were first introduced.

HEMCO version Description
26 Jan 2017
  1. Added a shadow variable for optional input argument in update_mixing_ratio in subroutine AIRQNT in dao_mod.F
  2. Added the passive tracer module
  3. Improve write speed of netCDF output files (added to GEOS-Chem in v11-01 public release)
Patches These will eventually be standardized in the next HEMCO version:
  1. Enable data compression in netCDF-4 output files
  2. Fix bug in computation of local time in routine HCO_GetSuncos
  3. HEMCO diagnostic and restart files now have an unlimited time dimension

--Melissa Sulprizio (talk) 20:57, 27 January 2017 (UTC)
--Bob Yantosca (talk) 21:57, 8 March 2017 (UTC)

Features added in v11-02c

These updates are slated for inclusion in v11-02c

The table below describes the new HEMCO features that are contained in v11-02c and the HEMCO version in which they were first introduced.

HEMCO version Description
16 May 2017
HEMCO v2.1 includes these new features:
  1. All internal timestamp variables are now REAL*8, in order to be able to read netCDF time slices in YYYYMMDDhhmm format.
  2. The option to defined species-specific scale factors that are applied across all inventories, categories, hierarchies, and extensions;
  3. The option to use mathematical expressions (such as 2.0 + sin(HH)), but none of them are used in the standard setup.
  4. An update was added to the regridding routines (regrid_a2a_mod.F90) to support non-global grids as well as regridding of missing values. Grid boxes with missing values are now ignored. The old code did not support missing values and would assign a value of 0.0 to all grid boxes with no input value. For regional emission inventories, this meant that all values outside of the domain were treated as zero's and the regridding did essentially dilute the emissions at the grid boundaries. The new code now ignores the grid boxes outside of the boundaries.
  5. The changes in the benchmarks should be small (there were some bug fixes & updates related to I/O and regridding that may create non zero-diff results).

And a corresponding feature in the GEOS-Chem Unit Tester:

  1. We have added a run directory for the HEMCO standalone model to the GEOS-Chem Unit Tester in v11-02c and newer versions. GEOS-Chem users can drop their HEMCO_Config.rc into that directory and test their emission setup right away. This will also allow us to add HEMCO standalone runs to our standard benchmarking procedures.
Patches These will eventually be standardized in the next HEMCO version:
  1. Add an error trap in hcox_dustginoux_mod.F90 to avoid a segmentation fault

--Bob Yantosca (talk) 20:47, 7 July 2017 (UTC)

Features slated for inclusion in v11-02

These updates are slated for inclusion in v11-02

The table below describes the new HEMCO features that are contained in v11-02 and the HEMCO version in which they were first introduced.

HEMCO version Description
19 Jul 2017
HEMCO v2.1 includes new features:
  1. Enable tokens within math functions
  2. Normalize MEGAN LAI by PFT. This fix assumes the usage of updated LAI input data

--Melissa Sulprizio (talk) 15:37, 19 July 2017 (UTC)

Previous issues that are now resolved

In this section we describe errors and other software issues caused by HEMCO dating back to GEOS-Chem v10-01e. All of these issues have since been resolved.

Avoid segmentation fault in DustGinoux extension

This fix will be included in v11-02c.

Paolo Tuccella (L'Aquila) wrote:

I have an issue running GEOS-Chem V11-01. When I run the model (merra2_2x25_soa configuration) with the DustGinoux dust emission scheme turned on in HEMCO_Config.rc, GEOS-Chem crashes with this message error:
     Program received signal SIGSEGV: Segmentation fault - invalid memory reference.
The error is occuring at line 395 of HEMCO/Extensions/hcox_dustginoux_mod.F90, where the emissions flux of alkalinity dust is updated. So, turning on DustAlk in HEMCO_Config.rc, the model run without errors.

Bob Yantosca replied:

I’ve figured out the error. So the DustGinoux extension is usually turned off by default in the standard simulations, which is why we didn’t find this earlier. In the module the HEMCO/Extensions/hcox_dustginoux_mod.F, an error trap is lacking. So we need to add the code in GREEN to the existing IF statement at line 395:
      IF ( ExtNrAlk > 0 ) THEN
         IF ( HcoIDsAlk(N) > 0 ) THEN

            ! Add flux to emission array
            CALL HCO_EmisAdd( am_I_Root,    HcoState, FLUX_Alk(:,:,N), & 
                              HcoIDsAlk(N), RC,       ExtNr=ExtNrAlk   )
             IF ( RC /= HCO_SUCCESS ) THEN
                WRITE(MSG,*) 'HCO_EmisAdd error: dust alkalinity bin ', N
                CALL HCO_ERROR(HcoState%Config%Err,MSG, RC )

If the DustAlk extension is turned off, then the HcoIDsAlk array will be unallocated. Therefore, to avoid a segmentation fault, we need to avoid executing this block of code whenever DustAlk is turned off.

--Bob Yantosca (talk) 20:38, 7 July 2017 (UTC)

Now use YYYYMMDDhhmm format for time stamp values

These fixes will be included in v11-02c.

This issue affects only GEOS-Chem "Classic" simulations (i.e. running GEOS-Chem without the ESMF and MPI libraries).

Andy Jacobson (NOAA) wrote:

Christoph Keller recently helped me discover a limitation of the netCDF routines used in HEMCO (i.e. for GEOS-Chem "Classic" simulations only), namely that the time coordinate variables are assumed to be integer types. In common situations such as the CarbonTracker netCDF files, the time is encoded as a float with units of "days since". This is silently misinterpreted by HEMCO because of limitations of the underlying netCDF routines. This results in incorrect time slices being chosen for HEMCO emissions, and

Bob Yantosca replied:

Long story short: The HEMCO module HEMCO/Core/hcoio_read_std_mod.F90 only assumed that the time stamps that would be read from netCDF files would only be in YYYYMMDDhh format. As Andy pointed out, it was picking out incorrect time slices for data with YYYYMMDDhhmm timestamps (such as the NOAA Carbon Tracker data).

I’ve gone through and made a bunch of changes in the followng modules:

  • NcdfUtil/ncdf_mod.F90
  • HEMCO/Core/hcoio_read_std_mod.F90
Variables that hold time stamps in hcoio_read_std_mod.F90 are now declared REAL*8, so that they will be large enough to hold a value in YYYYMMDDhhmm format (e.g. floating point value of order 1012). I’ve also adjusted the formulas where we extract e.g. YYYY, MM, DD etc. info from the YYYYMMDDhhmm timestamp accordingly. Also the function NC_READ_TIME_YYYYMMDDhh in ncdf_mod.F90 has now been renamed to NC_READ_TIME_YYYYMMDDhhmm to reflect the fact that it will return timestamps in the YYYYMMDDhhmm format.

--Bob Yantosca (talk) 14:34, 12 April 2017 (UTC)

Read default DEP_RESERVOIR fields from file when not found in HEMCO restart file

This fix was included in v11-02a and approved on 12 May 2017.

Brian Boys wrote:

The HEMCO_Config file that ships out with GC has the date tolerance throughout set as exact (E) for the HEMCO_RESTART file inputs, and so if the HEMCO_RESTART file that is fed in at the beginning of the run isn't exactly the correct hour, the file is not read and default values are used. The concerning part is that one of the restart variables, DEP_RESERVOIR, used by the soilNOx extension has a long e-folding lifetime (4-6 months I think), and the default value(s?) that are used in the absence of a HEMCO_restart file are quite low (I estimate more than a factor of 3 over the E. U.S.). Would it make sense to change the date tolerance to 'C' for the soilNOx extension part of the file that is shipped from Harvard? The seasonal variability appears to be much less than a factor of 3.

The issue with the above solution is that it assumes a HEMCO restart file is included in the run directory. In fact, in GEOS-Chem v11-01 run directories created by the GEOS-Chem unit tester (except those created from 4x5_standard) do not include a HEMCO restart file because it is assumed that it's better to initialize a simulation with the default value than to use a HEMCO restart file for the wrong date.

Christoph Keller wrote:

We could add the default DEP_RESERVOIR field to the HEMCO configuration file and call it DEP_RESERVOIR_DEFAULT:
    104 DEP_RESERVOIR_DEFAULT    DEP_RESERVOIR   2013/7/1/0 C xy kg/m3 NO – 1 1
And then read this file first and use it as default field when obtaining the soil NOx restart data (hcox_soilnox_run in hcox_soilnox_mod.F90):
    REAL(hp), TARGET :: Tmp2D(HcoState%NX, HcoState%NY)
    REAL(sp)         :: Def2D(HcoState%NX, HcoState%NY)
    ! DEP_RESERVOIR. Read in kg NO/m3
    CALL HCO_EvalFld( am_I_Root, HcoState, 'DEP_RESERVOIR_DEFAULT', Tmp2D, RC, FOUND=FOUND )
       Def2D = Tmp2D
       Def2D = 1.0e-4_sp
    CALL HCO_RestartGet( am_I_Root, HcoState, 'DEP_RESERVOIR', &
                         Inst%DEP_RESERVOIR, RC, Def2D=Def2D )
and then delete the IF ( .NOT. FOUND ) statement right afterwards. For we can simply extract DEP_RESERVOIR from the HEMCO restart file used for the benchmark simulation (using cdo selvar).

A file can now be found at

--Melissa Sulprizio (talk) 13:58, 28 March 2017 (UTC)

Make anthropogenic emissions diagnostics 3D

These fixes were included in v11-02a and approved on 12 May 2017.

Jenny Fisher wrote:

Some of the anthropogenic emissions are now 3D (mine, but also NEI2011) - but even if I specify in input.geos that I want to save e.g. ND36 (anthro emissions) over N levels where N>1, the trac_avg file that is created only has surface level ND36. I did some digging, and I assume that is because when you call Diagn_Create() for ND36 in hcoi_gc_diagn_mod.F90, you do so with SpaceDim = 2. Is that correct? Is this perhaps a behaviour that should be changed in future as NEI11 is standard in v11-01?
I also assume the hard-coding in the routine mentioned above is the reason I can’t specify "extra" tracers to be included in ND36 – for example, NO2 (which again shows up with anthro emissions in my files and also in NEI11). Should we perhaps broaden the list of allowable ND36 tracers to match NEI11 species?

--Melissa Sulprizio (talk) 19:17, 22 March 2017 (UTC)

HEMCO diagnostic and restart files now have an unlimited time dimension

This update was included in v11-02a and approved on 12 May 2017.

Andy Jacobson (NOAA) wrote:

It would be convenient and COARDS/CF-compliant to convert the time dimension to an "unlimited" or "record" dimension in the restart files. That way, one can use NCO tools like ncrcat to concatenate them, and thereby have a file with the time evolution of the species. It's trivial to do this, requiring only 2 small changes in HEMCO/Core/hcoio_write_std_mod.F90:
(1) Add this line after the list of USE statements at the top of routine HCOIO_WRITE_STD:
     # include ""
(2) Substitute NF_UNLIMITED for nTime in the calls to NC_CREATE. Comment out the line in RED and add the line in GREEN:
     ! Create output file 
     ! Pass CREATE_NC4 to make file format netCDF-4 (mps, 3/3/16                                                       
     ! Now create netCDF file with time dimension as UNLIMITED (bmy, 3/8/17)
     IF ( NoLevDim ) THEN
       !CALL NC_CREATE( ncFile, title, nLon,  nLat,  -1,     nTime,         &
        CALL NC_CREATE( ncFile, title, nLon,  nLat,  -1,     NF_UNLIMITED,  &
                        fId,    lonId, latId, levId, timeId, VarCt,         &
                        CREATE_NC4=.TRUE. )
       !CALL NC_CREATE( ncFile, title, nLon,  nLat,  nLev,   nTime,         &
        CALL NC_CREATE( ncFile, title, nLon,  nLat,  nLev,   NF_UNLIMITED,  &
                        fId,    lonId, latId, levId, timeId, VarCt,         &
                        CREATE_NC4=.TRUE. )
Note that nTime was hard-coded to 1 already in this routine. The #include is there only to get the symbol NF_UNLIMITED.

It looks like this routine also writes the HEMCO_diagnostics.*.nc files, and it makes sense to have time as the record dimension there, too.

I've tested this in the v11-01 public release w/ patches, and it works fine.

--Bob Yantosca (talk) 22:15, 8 March 2017 (UTC)

Fixed bug in computation of local time in HCO_GetSuncos

This fix was included in v11-02a and approved on 12 May 2017.

Seb Eastham wrote:

I just came across an interesting glitch with HEMCO which affects any extension using the HEMCO built-in SUNCOS calculation, including MEGAN. In the routine HCO_GetSUNCOS in HEMCO/Core/hco_geotools_mod.F90, HEMCO uses the local time to calculate the solar zenith angle SUNCOS. However, this has two issues:
  1. If no timezones are defined, then SUNCOS is artificially forced into 15 degree bands
  2. If timezones ARE defined, the SUNCOS becomes defined by political boundaries (see plot below, generated by pulling values directly from GEOS-Chem "Classic" with the new Voronoi timezones):


It would be better to remove the call to HcoClock_GetLocal in routine HEMCO_GetSUNCOS. This fix involves deactivating the code in RED and activating the code in GREEN as shown below:
     ! Prior to 3/2/17:
     ! Seb Eastham suggested to comment out the call to HcoClock_GetLocal.  If
     ! the Voronoi or classic timezones are used, this will compute the timezones 
     ! on political boundaries and not strictly on longitude.  This will cause funny
     ! results.  Replace this with a strict longitudinal local time. (bmy, 3/27/17)
     !         ! Local time [hours] at box (I,J) at the midpt of the chem timestep
     !         CALL HcoClock_GetLocal ( HcoState, I, J, cH=LHR, RC=RC )
     !         IF ( RC /= HCO_SUCCESS ) THEN
     !            ERR = .TRUE.
     !            EXIT
     !         ENDIF
     ! Prior to 3/2/17:
     ! Seb Eastham says that HOUR (in the new formula below) already contains DT.
     ! so we need to comment this out and just use HOUR + LONGITUDE/15.
     ! (bmy, 3/2/17)
     !         ! Adjust for time shift
     !         LHR = LHR + DT

              ! Compute local time as UTC + longitude/15 (bmy, 3/2/17)
              LHR = HOUR + ( HcoState%Grid%XMid%Val(I,J) / 15.0_hp )
              IF ( LHR <   0.0_hp ) LHR = LHR + 24.0_hp
              IF ( LHR >= 24.0_hp ) LHR = LHR - 24.0_hp
The idea is to change the calculation so it’s purely a function of physical latitude, not timezone. I've checked with Christoph (cc'd), and this is a genuine bug. It'll be fixed in the next version of HEMCO but I thought it would be worth putting a patch into GC now, given that the code change is minimal and the impact could be significant.

--Bob Yantosca (talk) 17:20, 2 March 2017 (UTC)

Fixed bug in time interpolation in ncdf_mod.F90

This update was included in GEOS-Chem v11-01 public release

Seb Eastham wrote:

While doing final checks on base emissions sets in GCHP, I noticed that the RCP emissions seemed to be about 2x greater in GCHP than in GEOS-Chem "Classic". On further investigation, this appears to be because of a bug in HEMCO; when the interpolation option is set to I, it looks like the interpolation might be using zeros for one of the slices, resulting in 50% of the expect emissions. I tested this by changing the RCP 4.5 interpolation setting from I to C for NOx, and running the year 2013. The two time slices between which interpolation is conducted are 2010 and 2020, between which there is a ~5% decrease in global NOx emissions (based on the original input file); however, when using the option I, I found that the NOx emissions were about 50% lower than when using the option C. Is this a known bug, or did I miss something?

Christoph Keller replied:

There was a bug in the netCDF reading routine that would overwrite the first time slice with the second one, and the interpolation then occurred between the second time slice (the right time window) and an array full of zeros. So no wonder that the results looked wrong. I added a fix for this to NcdfUtil/ncdf_mod.F90.

--Bob Yantosca (talk) 17:45, 10 January 2017 (UTC)

Ocean grid boxes now use the timezone of the nearest land mass for computing emissions

This update was included in GEOS-Chem v11-01 public release

Seb Eastham wrote:

Here are the HEMCO timezones used by default in GEOS-Chem v10-01. These are read from the netCDF file HEMCO/TIMEZONES/v2015-02/

Timezones V11-01 Default.png

Note that the timezones of the ocean cells in the above file are not computed robustly. As Christoph Keller points out:

The current timezones mask file does not work properly in grid cells with large ocean overlap. The problem is that the ocean values are netCDF _FillValues that become zero within HEMCO. As a quick fix I updated the timezones file [to HEMCO/TIMEZONES/v2015-02/ in v11-01j] to use a value of –5000 in all ocean cells, which then forces HEMCO to determine the time zone based on longitude in those cells.

Please find a "nearest-cell" version of the HEMCO "timezones" file (HEMCO/TIMEZONES/v2015-02/ I'd like to suggest that this replace the default HEMCO timezones file shown above. The new ("Voronoi") approach sets the timezone in every ocean cell to match that of the closest valid land cell by great circle distance. Without the update, some coastal areas will use the wrong timezone, resulting in incorrect diurnal scalings. Here is a plot of the Voronoi timezones:

Timezones Voronoi.png

The Voronoi timezones will be made the default HEMCO timezones in the v11-01 public release. In the meantime, GEOS-Chem users may select this option by updating this entry in the HEMCO_Config.rc file. Change the text in RED

* TIMEZONES $ROOT/TIMEZONES/v2015-02/ UTC_OFFSET 2000/1/1/0 C xy count * - 1 1

to the text in GREEN:

* TIMEZONES $ROOT/TIMEZONES/v2015-02/ UTC_OFFSET 2000/1/1/0 C xy count * - 1 1

--Bob Yantosca (talk) 19:00, 4 January 2017 (UTC)

Fix bug preventing HEMCO from writing restart files more than once per run

NOTE: This update was included in v11-01g (approved 28 Sep 2016).

Christoph Keller wrote:

There is a merge error in the code that shortcuts the diagnostics writing after the first call. This is the current code in HEMCO/Core/hcoio_diagn_mod.F90:
      ! Only write diagnostics if this is the first Diagn_Get call for
      ! this container and time step.
      IF ( ThisDiagn%nnGetCalls > 1 ) CYCLE
      ! NOTE: This may have been left over by a Git merge (bmy, 3/5/15)
      ! this container and time step.
      IF ( PRESENT( OnlyIfFirst ) ) THEN
         IF ( OnlyIfFirst .AND. ThisDiagn%nnGetCalls > 1 ) CYCLE
Please remove/comment the highlighted line and recompile.

--Melissa Sulprizio (talk) 16:30, 30 August 2016 (UTC)

Fix missing pointer in call to HCO_CalcVertGrid

NOTE: This update was included in v11-01g (approved 28 Sep 2016).

We have found and fixed an error in routine GridEdge_Set (located in module GeosCore/hcoi_gc_main_mod.F), where we have this code:

    REAL(hp), POINTER   :: PSFC    (:,:  )
    REAL(hp), POINTER   :: ZSFC    (:,:  )
    REAL(hp), POINTER   :: TK      (:,:,:)
    REAL(hp), POINTER   :: BXHEIGHT(:,:,:)
    REAL(hp), POINTER   :: PEDGE   (:,:,:)

    ! GridEdge_Set begins here

    ! Pointers to fields 
    ZSFC     => State_Met%PHIS
    TK       => State_Met%T

    ! surface pressure in Pa
    PSFC(:,:) = State_Met%PEDGE(:,:,1) * 100.0_hp

    ! Calculate missing quantities
    CALL HCO_CalcVertGrid( am_I_Root, HcoState, PSFC,    &
                           ZSFC,  TK, BXHEIGHT, PEDGE, RC )

    ! Nullify local pointers
    ZSFC     => NULL()
    TK       => NULL()
    PSFC     => NULL()

   ! Return w/ success

As you can see, PEDGE is never defined, but is nevertheless passed to Hco_CalcVertGrid, which is contained in module HEMCO/Core/hco_geotools_mod.F90. This was producing the following error message in the HEMCO log file:

Details about vertical grid calculations (only shown on first time step):
1. Input data availability:
  - Temperature field TK obtained from model interface (min,max):    179.394287109375        312.010620117188
  - Surface pressure PSFC [Pa] obtained from model interface (min, max):    54482.8735351562        103645.007324219
  - Surface geopotential height ZSFC [m] obtained from model interface (min, max):   -17.0556747924240        5115.05386332234
HEMCO ERROR:  Wrong PEDGE array size:          255  -783173889  1988815368; should be:           
72          46          48
ERROR LOCATION: HCO_CalcVertGrid (hco_geotools_mod.F90)

Because routine GridEdge_Set lacked an error trap to test if Hco_CalcVertGrid exited abnormally, there was no way to stop program execution at this point.

To fix these issues, we have rewritten routine GridEdge_Set as follows. Our new code is displayed in GREEN.

    ! Strings

    ! Pointers
    REAL(hp), POINTER :: BXHEIGHT(:,:,:)    ! Grid box height      [m ]
    REAL(hp), POINTER :: PEDGE   (:,:,:)    ! Pressure @ lvl edges [Pa]
    REAL(hp), POINTER :: PSFC    (:,:  )    ! Surface pressure     [Pa]
    REAL(hp), POINTER :: TK      (:,:,:)    ! Temperature          [K ]
    REAL(hp), POINTER :: ZSFC    (:,:  )    ! Surface geopotential [m ]

    ! GridEdge_Set begins here

    ! Assume success
    RC       =  HCO_SUCCESS

    ! Allocate the PEDGE array, which holds level edge pressures [Pa]
    ! NOTE: Hco_CalcVertGrid expects pointer-based arguments, so we must
    ! make PEDGE be a pointer and allocate/deallocate it on each call.
       MSG = 'ERROR allocating the PEDGE pointer-based array!'
       LOC = 'GridEdge_Set (GeosCore/hcoi_gc_main_mod.F90)'

   ! Edge and surface pressures [Pa]
   PEDGE    =  State_Met%PEDGE * 100.0_hp  ! Convert hPa -> Pa
   PSFC     => PEDGE(:,:,1)

   ! Point to other fields of State_Met
   ZSFC     => State_Met%PHIS               
   BXHEIGHT => State_Met%BXHEIGHT           
   TK       => State_Met%T                  

   ! Calculate missing quantities
   CALL HCO_CalcVertGrid( am_I_Root, HcoState, PSFC,      &
                          ZSFC,      TK,       BXHEIGHT,  &
                          PEDGE,     RC                  )

   ! Stop with an error if the vertical grid was not computed properly
      MSG = 'ERROR returning from HCO_CalcVertGrid!'
      LOC = 'GridEdge_Set (GeosCore/hcoi_gc_main_mod.F90)'

   ! Nullify local pointers
   ZSFC     => NULL()
   TK       => NULL()
   PSFC     => NULL()

   ! Deallocate and nullify PEDGE
   PEDGE    => NULL()

   ! Return w/ success
   RC       = HCO_SUCCESS

Therefore we now:

  1. Allocate an array to store pressure edge values (PEDGE), converted from hPa to Pa, and
  2. Add error traps to stop execution if
    • PEDGE cannot be allocated, or
    • Hco_CalcVertGrid exits abnormally.

Bob Yantosca validated these changes with a unit test on 06 Jun 2016. These updates will be included in GEOS-Chem v11-01g. This fix will also be brought into HEMCO v2.0.

--Bob Yantosca (talk) 14:44, 7 June 2016 (UTC)

Enable emissions in the stratosphere for specialty simulations

This update was validated with 1-month benchmark simulation v11-01f and 1-year benchmark simulation v11-01f-geosfp-Run0. This version was approved on 16 Apr 2016.

Emissions in the stratosphere were disabled in a HEMCO June 2015 update to prevent build-up of stratospheric concentrations due to aircraft emissions (mainly VOCs). The HEMCO update was merged into GEOS-Chem v11-01e. This resulted in very low statospheric Be7 sources to the troposphere and imbalanced Be7 trop+strat sources and sinks in the v11-01f 1-year RnPbBe benchmark. Christoph Keller recommended maintaining disabled emissions in the stratosphere for at least the full-chemistry simulation.

To correct this bug, we now only restrict emissions in the stratosphere if performing a full-chemistry simulation and UCX is turned off. Emissions in the stratosphere are enabled for all specialty simulations. This fix was added to v11-01f prior to final benchmark approval.

--Lizzie Lundgren (talk) 15:15, 22 March 2016 (UTC)
--Bob Yantosca (talk) 15:32, 30 March 2016 (UTC)

Known issues

HEMCO errors apparently caused by bugs in Intel Fortran Compiler

Some users have reported technical issues with HEMCO that appear to be caused by bugs in the Intel Fortran Compiler.

Compiler Issue Status
Intel Fortran Compiler v15 Segmentation fault occurs when compiling with flags:
-check bounds -O2
Intel Fortran Compiler v13
Intel Fortran Compiler v14
Segmentation fault in HEMCO I/O module

--Bob Y. (talk) 20:30, 25 August 2015 (UTC)