The HEMCO User's Guide

From Geos-chem
Revision as of 08:22, 2 October 2020 by FeiYao-Edinburgh (Talk | contribs)

Jump to: navigation, search

HEMCO user guide by Christoph Keller (christoph.a.keller@nasa.gov)

last updated: Jan 16, 2019.

Contents

Overview

The Harvard-NASA Emissions Component (HEMCO) is a software component for computing atmospheric emissions from different sources, regions, and species on a user-defined grid. It can combine, overlay, and update a set of data inventories (base emissions) and scale factors, as specified by the user through the HEMCO configuration file. Emissions that depend on environmental variables and non-linear parameterizations are calculated in separate HEMCO extensions. HEMCO can be run in standalone mode or coupled to an atmospheric model. It is included in GEOS-Chem v10-01 and later versions. A more detailed description of HEMCO is given in Keller et al. (2014).

Download and installation

HEMCO is a collection of FORTRAN-90 routines that are freely available at http://wiki.geos-chem.org/HEMCO. Installation instructions are provided on the same page. Some basic knowledge of a Unix operating system is expected. To couple HEMCO to an atmospheric model, some working experience with FORTRAN is also required. HEMCO is already included in the standard distribution of GEOS-Chem v10-01 and later versions (http://wiki.geos-chem.org).

Example simulations

HEMCO includes a simple example of a HEMCO standalone simulation. It calculates emissions of carbon monoxide (CO) from the EDGAR inventory (Janssens-Maenhout et al., 2010) on January 1, 2008 on a global grid of 4x5 degrees.

The full suite of emission inventories and extensions used by the chemical transport model GEOS-Chem are described on our HEMCO data directories wiki page. On that page you will also find instructions on how to download these data to your disk server.

You will also want to look at our HEMCO examples wiki page, which contains examples on how you can customize HEMCO for your particular emission scenarios.

Getting started

All emission calculation settings are specified in the HEMCO configuration file. Modification of the HEMCO source code (and recompilation) is only required if new extensions are added, or to use HEMCO in a new model environent (see sections Behind the scenes of HEMCO and Interfaces).

Example 1: Adding MACCITY global anthropogenic emissions

Suppose monthly anthropogenic CO emissions from the MACCity inventory (Lamarque et al., 2010) are stored in file MACCity.nc as variable 'CO'. The following configuration file then simulates CO emissions with gridded hourly scale factors applied to it (the latter taken from variable 'factor' of file hourly.nc). The horizontal grid and simulation datetimes employed by HEMCO depends on the HEMCO-model interface. If HEMCO is coupled to GEOS-Chem, these values are taken from the chemistry model. If run standalone, the grid specification and desired datetimes need be specified as described in the Interfaces section.

###############################################################################
#### BEGIN SECTION SETTINGS
###############################################################################

ROOT            : /dir/to/data 
Logfile         : HEMCO.log
DiagnPrefix     : HEMCO_diagnostics
Wildcard        : *
Separator       : /
Unit tolerance  : 1
Negative values : 0
Verbose         : 0
Warnings        : 1
 
END SECTION SETTINGS

###############################################################################
### BEGIN SECTION EXTENSION SWITCHES
###############################################################################
# ExtNr ExtName           on/off  Species	
0       Base              : on    *
    --> MACCITY           :       true

END SECTION EXTENSION SWITCHES

###############################################################################
#### BEGIN SECTION BASE EMISSIONS
############################################################################### 
# ExtNr Name sourceFile sourceVar sourceTime C/R/E SrcDim SrcUnit Species ScalIDs Cat Hier

(((MACCITY
0 MACCITY_CO $ROOT/MACCity.nc  CO 1980-2014/1-12/1/0 C xy kg/m2/s CO 1 1 1
)))MACCITY 

END SECTION BASE EMISSIONS

###############################################################################
#### BEGIN SECTION SCALE FACTORS
###############################################################################
# ScalID Name srcFile srcVar srcTime CRE Dim Unit Oper			

1 HOURLY_SCALFACT $ROOT/hourly.nc factor 2000/1/1/0-23	C xy 1 1		

END SECTION SCALE FACTORS

###############################################################################
#### BEGIN SECTION MASKS
###############################################################################

END SECTION MASKS

The various attributes are explained in more detail in the Base Emissions and Scale Factors sections.

As described in the Data Collections section, all of the files contained between the brackets (((MACCITY and )))MACCITY will be read if you set the switch

--> MACCITY           :       true

These files will be ignored if you set

--> MACCITY           :       false

This is a quick way to shut off individual emissions inventories without having to manually comment out many lines of code. You can add a set of brackets, with a corresponding true/false switch, for each emissions inventory that you add to the configuration file.

Example 2: Overwriting MACCITY with EMEP regional anthropogenic emissions

To add regional monthly anthropogenic CO emissions from the EMEP inventory (Vestreng et al., 2009) (in EMEP.nc) to the simulation, the configuration file can be modified as follows (changes are highlighted in GREEN):

###############################################################################
#### BEGIN SECTION EXTENSION SWITCHES
###############################################################################				
# ExtNr ExtName           on/off  Species	
0       Base              : on    *
    --> MACCITY           :       true	
    --> EMEP              :       true

END SECTION EXTENSION SWITCHES

###############################################################################
#### BEGIN SECTION BASE EMISSIONS
###############################################################################
#ExtNr	Name srcFile srcVar srcTime CRE	Dim Unit Species ScalIDs Cat Hier

(((MACCITY
0 MACCITY_CO $ROOT/MACCity.nc CO 1980-2014/1-12/1/0 C xy kg/m2/s CO  1      1 1
)))MACCITY

(((EMEP
0 EMEP_CO    $ROOT/EMEP.nc    CO 2000-2014/1-12/1/0 C xy kg/m2/s CO  1/1001 1 2
)))EMEP

END SECTION BASE EMISSIONS

###############################################################################
#### BEGIN SECTION SCALE FACTORS
###############################################################################
#ScalID Name srcFile srcVar srcTime CRE Dim Unit Oper			

1 HOURLY_SCALFACT $ROOT/hourly.nc factor 2000/1/1/0-23 C xy 1 1			

END SECTION SCALE FACTORS

###############################################################################
#### BEGIN SECTION MASKS
###############################################################################
#ScalID Name srcFile srcVar srcTime CRE Dim Unit Oper Box		

1001 MASK_EUROPE $ROOT/mask_europe.nc MASK 2000/1/1/0 C xy 1 1 -30/30/45/70

END SECTION MASKS

For now, we have omitted the Settings section because nothing has changed since the previous example.

Note the increased hierarchy of the regional EMEP inventory compared to the global MACCITY emissions (column 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.

Example 3: Adding the AEIC aircraft emissions

To add aircraft emissions from the AEIC inventory (Stettler et al., 2011), available in file AEIC.nc, add the following lines in GREEN to the HEMCO configuration file:

###############################################################################
#### BEGIN SECTION EXTENSION SWITCHES
###############################################################################				
# ExtNr ExtName           on/off  Species	
0       Base              : on    *
    --> MACCITY           :       true	
    --> EMEP              :       true
    --> AEIC              :       true

END SECTION EXTENSION SWITCHES 

###############################################################################
#### BEGIN SECTION BASE EMISSIONS
###############################################################################
#ExtNr	Name srcFile srcVar srcTime CRE	Dim Unit Species ScalIDs Cat Hier

(((MACCITY
0 MACCITY_CO $ROOT/MACCity.nc CO 1980-2014/1-12/1/0 C xy  kg/m2/s CO 1      1 1
)))MACCITY

(((EMEP
0 EMEP_CO    $ROOT/EMEP.nc    CO 2000-2014/1-12/1/0 C xy  kg/m2/s CO 1/1001 1 2
)))EMEP

(((AEIC
0 AEIC_CO    $ROOT/AEIC.nc    CO 2005/1-12/1/0      C xyz kg/m2/s CO -      2 1
)))AEIC

END SECTION BASE EMISSIONS

Note the change in the emission category (column Cat). In this example, category 1 represents anthropogenic emissions and category 2 represents aircraft emissions.

Example 4: Adding biomass burning emissions

Biomass burning emissions calculated by GFED4 (Giglio et al, 2013) can be added by adding the corresponding extension to section Extension Switches, and adding all the input data needed by GFED4 to section Base Emissions. (These additions are highlighted in GREEN.) The extension number defined in the Extension Switches section must match the corresponding ExtNr entry in the Base Emissions section (in this example, 111).

###############################################################################
#### BEGIN SECTION EXTENSION SWITCHES
###############################################################################				
# ExtNr ExtName           on/off  Species	
0       Base              : on    *
    --> MACCITY           :       true	
    --> EMEP              :       true
    --> AEIC              :       true
#------------------------------------------------------------------------------
111     GFED              : on    CO
    --> GFED3             :       false
    --> GFED4             :       true
    --> GFED_daily        :       false
    --> GFED_3hourly      :       false
    --> Scaling_CO        :       1.05

END SECTION EXTENSION SWITCHES 

###############################################################################
#### BEGIN SECTION BASE EMISSIONS
###############################################################################
#ExtNr	Name srcFile srcVar srcTime CRE	Dim Unit Species ScalIDs Cat Hier

(((MACCITY
0 MACCITY_CO $ROOT/MACCity.nc	CO 1980-2014/1-12/1/0 C xy  kg/m2/s CO 1     1 1
)))MACCITY

(((EMEP
0 EMEP_CO    $ROOT/EMEP.nc     CO 2000-2014/1-12/1/0 C xy  kg/m2/s CO 1/1001 1 2
)))EMEP

(((AEIC
0 AEIC_CO    $ROOT/AEIC.nc     CO 2005/1-12/1/0      C xyz kg/m2/s CO -      2 1
)))AEIC
 
###############################################################################
#### BEGIN SECTION EXTENSION DATA (subsection of BASE EMISSIONS DATA
###############################################################################

# --- GFED biomass burning emissions (Extension 111)
111 GFED_HUMTROP    $ROOT/GFED3/v2014-10/GFED3_humtropmap.nc              humtrop           2000/1/1/0             C xy 1         * - 1 1

(((GFED3
111 GFED_WDL        $ROOT/GFED3/v2014-10/GFED3_gen.1x1.$YYYY.nc           GFED3_BB__WDL_DM  1997-2011/1-12/01/0    C xy kgDM/m2/s * - 1 1
111 GFED_AGW        $ROOT/GFED3/v2014-10/GFED3_gen.1x1.$YYYY.nc           GFED3_BB__AGW_DM  1997-2011/1-12/01/0    C xy kgDM/m2/s * - 1 1
111 GFED_DEF        $ROOT/GFED3/v2014-10/GFED3_gen.1x1.$YYYY.nc           GFED3_BB__DEF_DM  1997-2011/1-12/01/0    C xy kgDM/m2/s * - 1 1
111 GFED_FOR        $ROOT/GFED3/v2014-10/GFED3_gen.1x1.$YYYY.nc           GFED3_BB__FOR_DM  1997-2011/1-12/01/0    C xy kgDM/m2/s * - 1 1
111 GFED_PET        $ROOT/GFED3/v2014-10/GFED3_gen.1x1.$YYYY.nc           GFED3_BB__PET_DM  1997-2011/1-12/01/0    C xy kgDM/m2/s * - 1 1
111 GFED_SAV        $ROOT/GFED3/v2014-10/GFED3_gen.1x1.$YYYY.nc           GFED3_BB__SAV_DM  1997-2011/1-12/01/0    C xy kgDM/m2/s * - 1 1
)))GFED3

(((GFED4
111 GFED_WDL        $ROOT/GFED4/v2015-03/GFED4_gen.025x025.$YYYY.nc       WDL_DM            2000-2013/1-12/01/0    C xy kg/m2/s   * - 1 1
111 GFED_AGW        $ROOT/GFED4/v2015-03/GFED4_gen.025x025.$YYYY.nc       AGW_DM            2000-2013/1-12/01/0    C xy kg/m2/s   * - 1 1
111 GFED_DEF        $ROOT/GFED4/v2015-03/GFED4_gen.025x025.$YYYY.nc       DEF_DM            2000-2013/1-12/01/0    C xy kg/m2/s   * - 1 1
111 GFED_FOR        $ROOT/GFED4/v2015-03/GFED4_gen.025x025.$YYYY.nc       FOR_DM            2000-2013/1-12/01/0    C xy kg/m2/s   * - 1 1
111 GFED_PET        $ROOT/GFED4/v2015-03/GFED4_gen.025x025.$YYYY.nc       PET_DM            2000-2013/1-12/01/0    C xy kg/m2/s   * - 1 1
111 GFED_SAV        $ROOT/GFED4/v2015-03/GFED4_gen.025x025.$YYYY.nc       SAV_DM            2000-2013/1-12/01/0    C xy kg/m2/s   * - 1 1
)))GFED4

(((GFED_daily
111 GFED_FRAC_DAY   $ROOT/GFED3/v2014-10/GFED3_dailyfrac_gen.1x1.$YYYY.nc GFED3_BB__DAYFRAC 2002-2011/1-12/1-31/0  C xy 1         * - 1 1
)))GFED_daily

(((GFED_3hourly
111 GFED_FRAC_3HOUR $ROOT/GFED3/v2014-10/GFED3_3hrfrac_gen.1x1.$YYYY.nc   GFED3_BB__HRFRAC  2002-2011/1-12/01/0-23 C xy 1         * - 1 1
)))GFED_3hourly

END SECTION BASE EMISSIONS

As in the previous examples, the tags beginning with ((( and ))) denote options that can be toggled on or off in the Extension Switches section. For example, if you wanted to use GFED3 biomass emissions instead of GFED4, you would set the switch for GFED3 to true and the switch for GFED4 to false.

Scale factors and other extension options (e.g. Scaling_CO) can be specified in the Extension Switches section.

Example 5: Telling HEMCO to use additional species

The HEMCO configuration file can hold emission specifications of as many species as desired. For example, to add anthropogenic NO emissions from the MACCity inventory, add the following line in GREEN to the configuration file:

###############################################################################
#### BEGIN SECTION BASE EMISSIONS
###############################################################################
#ExtNr	Name srcFile srcVar srcTime CRE	Dim Unit Species ScalIDs Cat Hier

(((MACCITY
0 MACCITY_CO $ROOT/MACCity.nc CO 1980-2014/1-12/1/0 C xy kg/m2/s CO 1 1 1
0 MACCITY_NO $ROOT/MACCity.nc NO 1980-2014/1-12/1/0 C xy kg/m2/s NO 1 1 1
)))MACCITY

To include NO in GFED, we can just add NO to the list of species that GFED will process in the Extension Switches section.

###############################################################################
#### BEGIN SECTION EXTENSION SWITCHES
###############################################################################				
# ExtNr ExtName           on/off  Species	
0       Base              : on    *
    --> MACCITY           :       true	
    --> EMEP              :       true
    --> AEIC              :       true
#------------------------------------------------------------------------------
111     GFED              : on    CO/NO
    --> GFED3             :       false
    --> GFED4             :       true
    --> GFED_daily        :       false
    --> GFED_3hourly      :       false
    --> Scaling_CO        :       1.05


Finally, let's add sulfate emissions to the simulation. Emissions of SO4 are approximated from the MACCity SO2 data, assuming that SO4 constitutes 3.1% of the SO2 emissions. The final configuration file now looks like this (changes in GREEN).

###############################################################################
#### BEGIN SECTION SETTINGS
###############################################################################

ROOT            : /dir/to/data 
Logfile         : HEMCO.log
DiagnPrefix     : HEMCO_diagnostics
Wildcard        : *
Separator       : /
Unit tolerance  : 1
Negative values : 0
Verbose         : 0
Warnings        : 1
 
END SECTION SETTINGS

###############################################################################
#### BEGIN SECTION EXTENSION SWITCHES
###############################################################################				
# ExtNr ExtName           on/off  Species	
0       Base              : on    *
    --> MACCITY           :       true	
    --> EMEP              :       true
    --> AEIC              :       true
#------------------------------------------------------------------------------
111     GFED              : on    CO/NO/SO2
    --> GFED3             :       false
    --> GFED4             :       true
    --> GFED_daily        :       false
    --> GFED_3hourly      :       false
    --> Scaling_CO        :       1.05

END SECTION EXTENSION SWITCHES 

###############################################################################
#### BEGIN SECTION BASE EMISSIONS
###############################################################################
#ExtNr	Name srcFile srcVar srcTime CRE	Dim Unit Species ScalIDs Cat Hier

(((MACCITY
0 MACCITY_CO  $ROOT/MACCity.nc	CO  1980-2014/1-12/1/0 C xy kg/m2/s CO  1 1 1
0 MACCITY_NO  $ROOT/MACCity.nc NO  1980-2014/1-12/1/0 C xy kg/m2/s NO  1 1 1
0 MACCITY_SO2 $ROOT/MACCity.nc SO2 1980-2014/1-12/1/0 C xy kg/m2/s SO2 - 1 1
0 MACCITY_SO4 -                -   -                  - -  -       SO4 2 1 1
)))MACCITY

(((EMEP
0 EMEP_CO    $ROOT/EMEP.nc     CO 2000-2014/1-12/1/0 C xy kg/m2/s CO  1/1001 1 2
)))EMEP

(((AEIC
0 AEIC_CO $ROOT/AEIC.nc CO 2005/1-12/1/0 C xyz kg/m2/s CO - 2 1
)))AEIC
 
###############################################################################
#### BEGIN SECTION EXTENSION DATA (subsection of BASE EMISSIONS DATA
###############################################################################

# --- GFED biomass burning emissions (Extension 111)
111 GFED_HUMTROP    $ROOT/GFED3/v2014-10/GFED3_humtropmap.nc              humtrop           2000/1/1/0             C xy 1         * - 1 1

(((GFED3
111 GFED_WDL        $ROOT/GFED3/v2014-10/GFED3_gen.1x1.$YYYY.nc           GFED3_BB__WDL_DM  1997-2011/1-12/01/0    C xy kgDM/m2/s * - 1 1
111 GFED_AGW        $ROOT/GFED3/v2014-10/GFED3_gen.1x1.$YYYY.nc           GFED3_BB__AGW_DM  1997-2011/1-12/01/0    C xy kgDM/m2/s * - 1 1
111 GFED_DEF        $ROOT/GFED3/v2014-10/GFED3_gen.1x1.$YYYY.nc           GFED3_BB__DEF_DM  1997-2011/1-12/01/0    C xy kgDM/m2/s * - 1 1
111 GFED_FOR        $ROOT/GFED3/v2014-10/GFED3_gen.1x1.$YYYY.nc           GFED3_BB__FOR_DM  1997-2011/1-12/01/0    C xy kgDM/m2/s * - 1 1
111 GFED_PET        $ROOT/GFED3/v2014-10/GFED3_gen.1x1.$YYYY.nc           GFED3_BB__PET_DM  1997-2011/1-12/01/0    C xy kgDM/m2/s * - 1 1
111 GFED_SAV        $ROOT/GFED3/v2014-10/GFED3_gen.1x1.$YYYY.nc           GFED3_BB__SAV_DM  1997-2011/1-12/01/0    C xy kgDM/m2/s * - 1 1
)))GFED3

(((GFED4
111 GFED_WDL        $ROOT/GFED4/v2015-03/GFED4_gen.025x025.$YYYY.nc       WDL_DM            2000-2013/1-12/01/0    C xy kg/m2/s   * - 1 1
111 GFED_AGW        $ROOT/GFED4/v2015-03/GFED4_gen.025x025.$YYYY.nc       AGW_DM            2000-2013/1-12/01/0    C xy kg/m2/s   * - 1 1
111 GFED_DEF        $ROOT/GFED4/v2015-03/GFED4_gen.025x025.$YYYY.nc       DEF_DM            2000-2013/1-12/01/0    C xy kg/m2/s   * - 1 1
111 GFED_FOR        $ROOT/GFED4/v2015-03/GFED4_gen.025x025.$YYYY.nc       FOR_DM            2000-2013/1-12/01/0    C xy kg/m2/s   * - 1 1
111 GFED_PET        $ROOT/GFED4/v2015-03/GFED4_gen.025x025.$YYYY.nc       PET_DM            2000-2013/1-12/01/0    C xy kg/m2/s   * - 1 1
111 GFED_SAV        $ROOT/GFED4/v2015-03/GFED4_gen.025x025.$YYYY.nc       SAV_DM            2000-2013/1-12/01/0    C xy kg/m2/s   * - 1 1
)))GFED4

(((GFED_daily
111 GFED_FRAC_DAY   $ROOT/GFED3/v2014-10/GFED3_dailyfrac_gen.1x1.$YYYY.nc GFED3_BB__DAYFRAC 2002-2011/1-12/1-31/0  C xy 1         * - 1 1
)))GFED_daily

(((GFED_3hourly
111 GFED_FRAC_3HOUR $ROOT/GFED3/v2014-10/GFED3_3hrfrac_gen.1x1.$YYYY.nc   GFED3_BB__HRFRAC  2002-2011/1-12/01/0-23 C xy 1         * - 1 1
)))GFED_3hourly
 
END SECTION BASE EMISSIONS

###############################################################################
#### BEGIN SECTION SCALE FACTORS
###############################################################################
# ScalID Name srcFile srcVar srcTime CRE Dim Unit Oper			

1 HOURLY_SCALFACT $ROOT/hourly.nc factor  2000/1/1/0-23 C xy 1	1			
2 SO2toSO4        0.031           -       -             - -  1 1

END SECTION SCALE FACTORS

###############################################################################
#### BEGIN SECTION MASKS
###############################################################################
#ScalID Name srcFile srcVar srcTime CRE Dim Unit Oper Box		

1001 MASK_EUROPE $ROOT/mask_europe.nc MASK 2000/1/1/0 C xy 1 1 -30/30/45/70		

END SECTION MASKS

Example 6: Adding inventories that do not separate out biofuels and/or trash emissions

Several emissions inventories (e.g. CEDS and EDGAR) lump biofuels and/or and trash emissions together with anthropogenic emissions. For inventories such as these, HEMCO allows you to specify up to 3 multiple categories for each species listing in the HEMCO_Config.rc file. All of the emissions will go into the first listed category, and the other listed categories will be set to zero.

In this example, all NO emissions from the EDGAR inventory power sector will be placed into the the anthropogenic emissions category (Cat=1), while the biofuel emissions category (Cat=2) will be set to zero.

0 EDGAR_NO_POW  $ROOT/EDGARv43/v2016-11/EDGAR_v43.NOx.POW.0.1x0.1.nc emi_nox 1970-2010/1/1/0 C xy kg/m2/s NO 1201/25/115  1/2 2

In this example, all NO emissions from CEDS inventory agriculture sector will be placed into the the anthropogenic emissions category (Cat=1), while the biofuel emissions category (Cat=2) and trash emissions category (Cat=12) will be set to zero.

0 CEDS_NO_AGR  $ROOT/CEDS/v2018-08/$YYYY/NO-em-anthro_CMIP_CEDS_$YYYY.nc  NO_agr  1750-2014/1-12/1/0 C xy kg/m2/s NO  25 1/2/12 5

HEMCO settings

Section settings of the configuration file defines a number of parameter and variables used by HEMCO. They should be listed at the beginning of the HEMCO configuration file. The order within the settings section is irrelevant. Many of these settings are optional, and default values will be used if not set. The settings are:

Name Default value Description
ROOT Set when you create a GEOS-Chem or GCHP run directory Root folder of the GEOS-Chem shared data directories. All met fields and emissions read by HEMCO will be stored in sub-folders of $ROOT.
METDIR Set when you create a GEOS-Chem or GCHP run directory Root folder of the GEOS-Chem met fields. This is usually filled in when you create a GEOS-Chem run directory. For exmaple, when you create a GEOS-Chem run directory that uses 4x5 GEOS-FP, METDIR will automatically be set to $ROOT/GEOS_4x5/GEOS_FP, etc.
Logfile HEMCO.log Path and name of the output log file. If set to the wildcard character, all HEMCO output is written to standard output.
DiagnPrefix HEMCO_Diagnostics Path and prefix of the default HEMCO diagnostics output. All diagnostics will be written to {DiagnPrefix}_YYYYMMDDHH.nc. See the Diagnostics section for more details.
DiagnFreq Daily Output frequency of the default HEMCO diagnostics. See the Diagnostics section for more details.
DiagnTimeStamp End Time stamp location of the default HEMCO diagnostics (HEMCO v1.1.012 and higher). Can be set to Start, Mid, or End of the diagnostics window. See the Diagnostics section for more details.
DiagnFile File containing definitions of the content of the default HEMCO diagnostics. See the Diagnostics section for more details.
Wildcard * Wildcard character symbol.
Separator / Separator character symbol.
Unit tolerance 0 Integer value denoting the tolerance against differences between the units set in the configuration file and data units found in the source file (0 = no tolerance; 2 = high tolerance). See the Units in HEMCO section for details.
Negative values 0 Integer value defining how negative values are handled (0 = no negative values are allowed; 1 = all negative values are set to zero and a warning is prompted; 2 = negative values are kept as they are).
Verbose 3 Integer value setting the amount of HEMCO information printed to the log file (0 = no verbose; 3 = very verbose).
Warnings 3 Integer value setting the amount of warnings printed to the HEMCO log file (0 = no warnings; 1 = only severe warnings; 2 = most warnings; 3 = all warnings).
Mask fractions false If set to true, the fractional mask values are taken into account, e.g. mask values can take any value between 0.0 and 1.0. If false, masks are binary and grid boxes are 100% inside or outside a mask region.
PBL dry deposition false If set to 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. If this setting is set to false, a loss term is calculated for the surface layer only.
ROOT Must be specified The root directory. Must be used to specify the root directory of emissions data (see the Base emissions section).
MODEL Determined by compiler switch Can be used to set the $MODEL token (see the Base emissions section). If omitted, this value is determined based on compiler switches (e.g. MET=geosfp).
RES Determined by compiler switch Can be used to set the $RES token (see the Base emissions section). If omitted, this value is determined based on compiler switches (e.g. GRID=4x5).
Emission year Simulation year If set, this emission year will be used irrespective of the model simulation year.
(new in version v1.1.006)
Emission month Simulation month If set, this emission month will be used irrespective of the model simulation month.
(new in version v1.1.006)
Emission day Simulation day If set, this emission day will be used irrespective of the model simulation day.
(new in version v1.1.006)
Emission hour Simulation hour If set, this emission hour will be used irrespective of the model simulation hour.
(new in version v1.1.006)
EmisScale_<SpeciesName> Uniform scale factor 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. For example, set EmisScale_NO: 1.5 to scale all NO emissions by 50%.
(new in version v2.1.001)

In standalone mode, the three simulation description files also need be specified (see also the Interfaces section):

Name Default value Description
GridFile HEMCO_sa_Grid.rc Path and name of the grid description file.
SpecFile HEMCO_sa_Spec.rc Path and name of the species description file.
TimeFile HEMCO_sa_Time.rc Path and name of the time specification file.

User-defined token

As of v1.1.010, users can specify any additional token in the settings section. The token name/value pair must be separated by the colon (:) sign. For example, adding the following line to the settings section would register token $ENS (and assign value 3 to it):

ENS: 3

User-defined tokens can be used the same way as the built-in tokens ($ROOT, $RES, $YYYY, etc.). See sourceFile in the Base emissions section for more details about tokens.

IMPORTANT NOTE: User-defined token names must not contain numbers or special characters such as ., _, -, or x.

Extension switches

HEMCO performs automatic emission calculations using all fields that belong to the 'base' extension (see below). Additional emissions that depend on environmental parameter such as wind speed or air temperature - and/or that use non-linear parameterizations - are calculated through HEMCO extensions. A list of currently implemented extensions in HEMCO is given in Keller et al. (2014). To add new extensions to HEMCO, modifications of the source code are required, as described further in Behind the scenes of HEMCO.

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:

Extension Description
ExtNr Unique extension number.
ExtName Extension name.
on/off Extension toggle. Extension is only used if this attribute is set to 'on'.
Species List of species to be used by this extension. Multiple species are separated by the separator symbol (e.g. /). All listed species must be supported by the given extension. For example, the soil NO emissions extension only supports one species (NO) and an error will be prompted if additional species are added.

Additional extension-specific settings can also be specified in the 'Extensions Settings' section (see also an example in Getting Started and the definition of Data Collections). These settings must immediately follow the extension definition.

HEMCO expects an extension with extension number zero, denoted the 'base' 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 still read/regridded by HEMCO (and can be made available readily 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 '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 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 the HEMCO configuration file, as described in the Extensions section.

Base emissions

The base emission section lists all base emission fields and how they are linked to scale factors. For each base emissions, the following attributes need to be defined:

Attribute Description
ExtNr Extension number associated with this field. All base emissions should have extension number zero. The ExtNr of the data listed in section 'Extensions data' must match with the corresponding extension number (see the Extension Switches section). 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 '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.
Name Descriptive field identification name. Two consecutive underscore characters (__) 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 only differ by its tag to those fields (e.g. DATA__SECTOR1, DATA__SECTOR2, etc.).

For fields assigned to extensions other than the base extension (ExtNr = 0), the field names are prescribed and must not be modified because the data is identified by these extensions by name.

sourceFile Path and name of the input file. See the Input File Format section for more details on the input file format requirements.

Name tokens can be provided that become evaluated during runtime. For example, to use the root directory specified in the settings (see the HEMCO Settings section), the token $ROOT can be used. Similarly, the token $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 data of the same directory as the configuration file, the file name can be set to $CFDIR/data/filename.nc.

Similarly, the date tokens $YYYY, $MM, $DD, $HH, and $MN can be used to refer to the current valid year, month, day, hour, and minute, respectively. These values are determined from the current simulation datetime and the SrcTime specification for this entry (see below). The tokens $MODEL and $RES refer to the meteorological model and resolution. 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. As of v1.1.010, any token defined in the settings section can be used to construct a part of the file name (see the User-defined token section).

As an alternative to an input file, geospatial uniform values can directly be specified in the configuration file (see e.g. scale factor SO2toSO4 in Getting Started). If multiple values are provided (separated by the separator character), they are interpreted as different time slices. In this case, the 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).

As of v2.1.001 uniform values can be combined with mathematical expressions, e.g. to model a sine-wave emission source. Mathematical expressions must be labeled MATH:, followed by the expression, e.g. 'MATH:2.0+sin(HH/12*PI)'. See our HEMCO examples wiki page for more information and examples.

Country-specific data can be provided through an ASCII file (.txt). More details on this option are given in the Input File Format section.

If this entry is left empty (-), the filename from the preceding entry is taken, and the next 5 attributes will be ignored (see entry MACCITY_SO4 in Getting Started).

sourceVar Source file variable of interest. Leave empty (-) if values are directly set through the sourceFile attribute or if sourceFile is empty.
sourceTime This attribute defines the time slices to be used and the data refresh frequency. The format is year/month/day/hour. Accepted are discrete dates for time-independent data (e.g. 2000/1/1/0) and time ranges for temporally changing fields (e.g. 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 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. If the time attribute is set to 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. Only a time attribute of 2005/1-12/1-31/0 will make sure that the input data are refreshed daily to the current day's data. Finally, if the time attribute is set to 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 2005-2010/1-12/1/0, the data of 2005 is used for all simulation months in 2005. 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 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 $YYYY, $MM, $DD, and $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 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: 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 WD assumes that the provided values are in local time. As of HEMCO v2.0.005, it is possible to use weekly data referenced to UTC time using token UTCWD.

Similar to the weekday option, there is an option to indicate hourly data that represents local time: 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 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 2005-2008/$MM/1/0 and 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 $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 $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 1990-2007/1/1/0 or 2000/1-12/1/1, but not 1990-2007/1-12/1/1.

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_200501.nc, file_200502.nc, ..., file_200712.nc. By setting the source file attribute to file_$YYYY$MM.nc and the source time attribute to 2005-2007/1-12/1/0, data of 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_2005.nc, file_2006.nc, file_2007.nc. In this case, the source file name should be set to file_$YYYY, but the source time attribute should still be 2005-2007/1-12/1/0 to indicate that the field shall be updated monthly.

This attribute can be set to the wildcard character (*), which will force the file to be updated on every HEMCO time step.

As of HEMCO version 2 the 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.yyyymmdd_0130z.nc, file.yyyymmdd_0430z.nc, ..., file.yyymmdd_2230z.nc. To read these files at the beginning of their time intervals, the time stamp can be shifted by 90 minutes: 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 - sign to shift backwards).

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:
  • 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 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).
  • 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. (GEOS-Chem 12.1.0 and higher)
  • CY (cycling, use simulation year): Same as C, except don't allow Emission year setting to override year value.
  • CYS (cycling, skip, use simulation year): Same as CS, except don't allow Emission year setting to override year value.
  • R (range): Data are only considered as long as the simulation time is within the time range specified in attribute 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 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). For example, if the source time attribute is set to 2000-2002/1-12/1/0 R, the data will be used for simulation years 2000 to 2002 and ignored for all other years.
  • RA (range, averaging otherwise): combination of flags R and 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. For example, consider the case where the emission file contains monthly data for years 2005-2010. Setting the time attribute to 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. When setting the time attribute to 2005-2010/1-12/1/0 A, HEMCO will always use the 2005-2010 averaged monthly values, even for simulation years 2005 to 2010. A time attribute of 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. (v1.1.010 and higher)
  • RF (range, forced): same as R, but HEMCO stops with an error if the simulation date is outside the provided range. (v1.1.011 and higher)
  • RY (range, use simulation year): Same as R, except don't allow Emission year setting to override year value.
  • E (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. For example, if the source time attribute is set to 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.
  • EF (exact, forced): same as E, but HEMCO stops with an error if no data field can be found for the current simulation date and time. (v1.1.011 and higher)
  • EC (exact, read/query continuously)
  • ECF (exact, forced, read/query continuously)
  • EY (exact, use simulation year): Same as E, except don't allow Emission year setting to override year value.
  • A (averaging): tells HEMCO to average the data over the specified range of years. For instance, setting the time attribute to 1990-2010/1-12/1/0 A will cause HEMCO to calculate monthly means between 1990 to 2010 and use those irrespective of the current simulation date (v1.1.010 and higher). 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 file_$YYYY.nc (only v1.1.014 and higher).
  • 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 the source time attribute is set to 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, the 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 change to 0.6 for 2005 and 0.4 for 2010, etc. The interpolation frequency is determined by the source time attribute. In the given example, setting the source time attribute to 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 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 (only v1.1.014 and higher). For instance, if monthly data are stored in files file_200501.nc, file_200502.nc, etc., a combination of source file name file_$YYYY$MM.nc and source time attribute 2005-2007/1-12/1-31/0 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 file_200507.nc and 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_20120101_0000.nc, file_20120101_0300.nc, etc. Hourly data interpolation between those files can be achieved by setting source file to file_$YYYY$MM$DD_$HH00.nc, and source time to 2000-2015/1-12/1-31/0-23 I (or whatever the covered year range is).
SrcDim Spatial dimension of input data (xy for horizontal data; xyz for 3-dimensional data).

As of HEMCO v1.1.004, the 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 SrcDim to 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 SrcDim to 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 level 1, etc.).

In HEMCO v1.1.005 and higher, the SrcDim attribute can also be used to indicate the level into which 2D data shall be released by setting the vertical coordinate to LX, with X being the release level. For instance, to emit a 2D field into level 5, set srcDim to xyL5.

HEMCO v2 has two new options to specify the emission injection height: (a) the vertical height can be given as model level (default) or in meters, e.g. to emit a source at 2000m: xyL=2000m; (b) 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 xyL=1:5 (emit into levels 1-5) or xyL=2:5000m (emit between model level 2 and 5000m); (c) the vertical layer can also be set to the PBL height by using the character string PBL. For example, to emit a source uniformly between the surface and the PBL top, use xyL=1:PBL.

HEMCO v2.1.005 includes the option to use 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 SrcDim setting. For an example see our HEMCO examples wiki page.

As of v1.1.010, it is legal to 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 SrcDim attribute. For example, to read a file that contains 3D ensemble data (with the individual ensemble runs as additional dimension 'ensemble'), set srcDim to xyz+"ensemble=3" to indicate that you wish to read the third ensemble member. It is also legal to use a user-defined token for the dimension index to be used, e.g. xyz+"ensemble=$ENS".

Note that arbitrary additional dimensions are currently not supported in a high-performance environment that uses the ESMF/MAPL input/output libraries.

SrcUnit Data units. See the Units in HEMCO section.
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 (ExtNr = 0), e.g. that are used for automatic emission calculation. They are used by HEMCO to determine the priority of the emission fields, i.e. how the final emission fields are assembled from all provided data fields.
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 ScalIDs must correspond to the numbers provided in the Scale Factors and Masks sections.
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 inventory does not separate between anthropogenic, biofuels, and/or trash emissions.
  • For example, the CEDS inventory uses categories 1/2/12 because CEDS lumps both biofuel emissions and trash emissions with anthropogenic emissions. Because it is not possible to separate out biofuels and trash, the 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.
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.

Scale factors

The scale factors section of the configuration file lists all scale factors applied to the base emission field. Scale factors that are not used by any of the base emission fields are ignored. Scale factors can represent:

  1. Temporal emission variations including diurnal, seasonal, or interannual variability;
  2. Regional masks that restrict the applicability of the base inventory to a given region; or
  3. Species-specific scale factors, e.g., to split lumped organic compound emissions into individual species.

Most attributes in this section are very similar to the base emissions, except for attributes ScalID and Oper. The sample snippet of the HEMCO configuration file shows how scale factors can either be read from a netCDF file or listed as a set of values.

###############################################################################
#### BEGIN SECTION SCALE FACTORS
###############################################################################
# ScalID Name srcFile srcVar srcTime CRE Dim Unit Oper			

# %%% Hourly factors, read from disk %%%
1 HOURLY_SCALFACT $ROOT/hourly.nc                                factor 2000/1/1/0-23 C xy 1 1

# %%% Scaling SO2 to SO4 (molar ratio) %%%
2 SO2toSO4        0.031                                          -      -             - -  1 1

# %%% Daily scale factors, list 7 entries %%%
20 GEIA_DOW_NOX   0.784/1.0706/1.0706/1.0706/1.0706/1.0706/0.863 -      -             - xy 1 1

END SECTION SCALE FACTORS
Attribute Description
ScalID Scale factor identification number. Used to link the scale factors to the base emissions through the corresponding ScalIDs attribute in the base emissions section.
Name See the Base emissions section.
sourceFile See the Base emissions section.
sourceVar See the Base emissions section.
sourceTime See the Base emissions section.
CRE See the Base emissions section.
SrcDim See the Base emissions section.
SrcUnit As described in the Base emissions section, with the exception that scale factors are assumed to be unitless (aka 1) and no automatic unit conversion is performed.
Oper Scale factor operator. Determines the operation performed on the scale factor. Possible values are:
  • 1 for multiplication (Emission = Base * Scale);
  • -1 for division (E = B / S);
  • 2 for squared (E = B * S**2).
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 section Masks of the configuration file.

Masks

This section lists all masks used by HEMCO. Masks are binary scale factors (1 inside the mask region, 0 outside). If masks are regridded, the remapped mask values (1 and 0) are determined through regular rounding, i.e. a remapped mask value of 0.49 will be set to 0 while 0.5 will be set to 1.

The MASKS section in the HEMCO configuration file will look similar to this (it will vary depending on the type of GEOS-Chem simulation you are using):

###############################################################################
### BEGIN SECTION MASKS 
############################################################################### 

# ScalID Name sourceFile sourceVar sourceTime C/R/E SrcDim SrcUnit Oper Lon1/Lat1/Lon2/Lat2  

#==============================================================================
# Country/region masks
#==============================================================================
1000 EMEP_MASK   $ROOT/MASKS/v2014-07/EMEP_mask.geos.1x1.20151222.nc           MASK     2000/1/1/0 C xy unitless 1 -30/30/45/70
1002 CANADA_MASK $ROOT/MASKS/v2014-07/Canada_mask.geos.1x1.nc                  MASK     2000/1/1/0 C xy unitless 1 -141/40/-52/85
1003 SEASIA_MASK $ROOT/MASKS/v2014-07/SE_Asia_mask.generic.1x1.nc              MASK     2000/1/1/0 C xy unitless 1  60/-12/153/55
1004 NA_MASK     $ROOT/MASKS/v2014-07/NA_mask.geos.1x1.nc                      MASK     2000/1/1/0 C xy unitless 1 -165/10/-40/90
1005 USA_MASK    $ROOT/MASKS/v2014-07/usa.mask.nei2005.geos.1x1.nc             MASK     2000/1/1/0 C xy unitless 1 -165/10/-40/90
1006 ASIA_MASK   $ROOT/MASKS/v2014-07/MIX_Asia_mask.generic.025x025.nc         MASK     2000/1/1/0 C xy unitless 1 46/-12/180/82
1007 NEI11_MASK  $ROOT/MASKS/v2014-07/USA_LANDMASK_NEI2011_0.1x0.1.20160921.nc LANDMASK 2000/1/1/0 C xy 1        1 -140/20/-50/60
1008 USA_BOX     -129/25/-63/49                                                -        2000/1/1/0 C xy 1        1 -129/25/-63/49

### END SECTION MASKS ###

The required attributes for mask fields are described below:

Attribute Description
ScalID Mask identification number. See the Scale factors section.
Name See the Base emissions section.
sourceFile See the Base emissions section.

In HEMCO v1.1.013 (introduced in GEOS-Chem v11-01e) and newer versions, the following updates were made:

  1. Instead of specifying the sourceFile and sourceVar fields, you can directly provide the lower left and upper right box coordinates: 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 will be used as mask.
  2. You can use grid point masks, e.g. Lon2 is equal to Lon1 and Lat2 is equal to Lat1 (Lon1/Lat1/Lon1/Lat1). In this case, only the grid box that includes the specified grid point is used.
sourceVar See the Base emissions section.
sourceTime See the Base emissions section.
Cycle See the Base emissions section.
SrcDim See the Base emissions section.
SrcUnit See the Base emissions section.
Oper Data operator. As for scale factors, except that value 2 (squared) is not allowed. Instead, Oper can be set to 3, which will 'mirror' the mask, i.e. Y = 1-X, where Y and X are the new and original mask value, respectively.
Box the approximate mask region grid box edges (Lon1/Lat1/Lon2/Lat2; lower left and upper right). This is only of relevance for regional emission grids or in a parallel computing environment (to exclude fields that have no coverage on the area covered by this CPU or within the specified emission region).

NOTE: A future update will force HEMCO to handle masks on all CPUs, thus making this column redundant.

Data collections

The fields listed in the configuration file can be grouped into data collections. Collections can be enabled/disabled in section extension 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: (((CollectionName and )))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.

The collections are enabled/disabled in the Extension Switches section (see Extension Switches). Each collection name must be provided as an extension setting and can then be readily enabled/disabled:

###############################################################################
#### BEGIN SECTION EXTENSION SWITCHES
###############################################################################				
# ExtNr ExtName           on/off  Species	
0       Base              : on    *
    --> MACCITY           :       true
    --> EMEP              :       true
    --> AEIC              :       true
 
END SECTION EXTENSION SWITCHES 

###############################################################################
#### BEGIN SECTION BASE EMISSIONS
###############################################################################
#ExtNr	Name srcFile srcVar srcTime CRE	Dim Unit Species ScalIDs Cat Hier

(((MACCITY
0 MACCITY_CO $ROOT/MACCity.nc	CO 1980-2014/1-12/1/0 C xy  kg/m2/s CO 1     1 1
)))MACCITY

(((EMEP
0 EMEP_CO    $ROOT/EMEP.nc     CO 2000-2014/1-12/1/0 C xy  kg/m2/s CO 1/1001 1 2
)))EMEP

(((AEIC
0 AEIC_CO    $ROOT/AEIC.nc     CO 2005/1-12/1/0      C xyz kg/m2/s CO -      2 1
)))AEIC

END SECTION BASE EMISSIONS

###############################################################################
#### BEGIN SECTION SCALE FACTORS
###############################################################################
# ScalID Name srcFile srcVar srcTime CRE Dim Unit Oper			

1 HOURLY_SCALFACT $ROOT/hourly.nc factor  2000/1/1/0-23 C xy 1	1			
2 SO2toSO4        0.031           -       -             - -  1 1			

END SECTION SCALE FACTORS

###############################################################################
#### BEGIN SECTION MASKS
###############################################################################
#ScalID Name srcFile srcVar srcTime CRE Dim Unit Oper Box		

1001 MASK_EUROPE $ROOT/mask_europe.nc MASK 2000/1/1/0 C xy 1 1 -30/30/45/70		

END SECTION MASKS

Extension names

The collection brackets also work with extension names, e.g. data can be included/excluded based on extensions. This is particularly useful to include an emission inventory for standard emission calculation if (and only if) an extension is not being used (see example below).

Undefined collections

If, for a given collection, no corresponding entry is found in the extensions section, it will be ignored. Collections are also ignored if the collection is defined in an extension that is disabled. It is recommended to list all collections under the base extension.

Exclude collections

To use the opposite of a collection switch, .not. can be added in front of an existing collection name. For instance, to read file NOT_EMEP.nc only if EMEP is not being used:

(((.not.EMEP
0 NOT_EMEP_CO    $ROOT/NOT_EMEP.nc     CO 2000/1-12/1/0 C xy  kg/m2/s CO 1/1001 1 2
))).not.EMEP

Combine collections

Multiple collections can be combined so that they are evaluated together. This is achieved by linking collection names with .or.. For example, to use BOND biomass burning emissions only if both GFED and FINN are not being used:

(((.not.GFED.or.FINN
0 BOND_BM_BCPI   $ROOT/BCOC_BOND/v2014-07/Bond_biomass.nc BC   2000/1-12/1/0 C xy kg/m2/s BCPI 70 2 1
0 BOND_BM_BCPO   -                                        -    -             - -  -       BCPO 71 2 1
0 BOND_BM_OCPI   $ROOT/BCOC_BOND/v2014-07/Bond_biomass.nc OC   2000/1-12/1/0 C xy kg/m2/s OCPI 72 2 1
0 BOND_BM_OCPO   -                                        -    -             - -  -       OCPO 73 2 1
0 BOND_BM_POA1   -                                        -    -             - -  -       POA1 74 2 1
))).not.GFED.or.FINN

Units in HEMCO

Overview

HEMCO classifies all data fields as fluxes, concentrations, or unitless data. Data are internally stored in HEMCO standard units of [kg emitted species/m2/s] for fluxes, and [kg 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 srcUnit attribute in 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 through attribute 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 to be in non-standard units (e.g. L instead of m3, g instead of kg, etc.), HEMCO will attempt to convert to standard units. This feature is not fully tested yet, and it is recommended to provide input data in standard units wherever possible.

srcUnit attribute

The srcUnit attribute in the HEMCO configuration file gives the user some control on unit conversion: If set to '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 2 (for unit tolerance of 1, the input data must be in one of the units recognized by HEMCO as unitless). If srcUnit is set to '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.

Special attention needs to be paid to species that are emitted in quantities other than mass of species, e.g. kg carbon. For these species, the species MW differs from the emitted species MW, and the molecular ratio determines how many molecules are being emitted per molecule species. By default, HEMCO will attempt to convert all input data to kg emitted species. If a species is emitted as kgC/m2/s and the input data is in kg/m2/s, the mass will be adjusted based on the molecular ratio and the ratio of emitted MW / species MW. Only input data that is already in kgC/m2/s will not be converted. This behavior can be avoided by explicitly set the 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).

Unit tolerance setting

The unit tolerance setting (see the HEMCO Settings section) indicates the tolerance of HEMCO if discrepancies are found between the units found in the input file and attribute srcUnit of the HEMCO configuration file. If the unit tolerance is set to 0, HEMCO stops with an error if the srcUnit attribute does not exactly match with the units attribute found in the input data. Unit tolerance of 1 enables the default behavior, and unit tolerance of 2 will take the srcUnit attribute as the data input unit, irrespective of the netCDF units attribute.

Unitless data

The following units are currently recognized as 'unitless' by HEMCO: 1, count, unitless, fraction, factor, scale, hours, v/v, v/v/s, s-1, m2/m2, kg/kg, K, W/m2, pptv, ppt, ppbv, ppb, ppmv, ppm, ms-1, m, cm2cm-2, dobsons, dobsons/day, hPa, Pa.

Examples with units

File file1.nc contains field DATA in units of kg/m2/s. It shall be applied to species acetone (ACET), which is emitted as kg carbon. The species MW of ACET is 58, the emitted MW is 12, and the molecular ratio is 3 (3 molecules of carbon per molecule of acetone). The following entry in the HEMCO configuration file will interpret the input data as kg acetone/m2/s, and convert it to kg C/m2/s using a scale factor of 0.62 (12/58*3):

0 ACET     file1.nc DATA 2000/1/1/0 C xy kgC/m2/s ACET - 1 1  #--> data is converted from kg acetone/m2/s to kgC/m2/s

The following entry will avoid the unit conversion from kg to kgC:

0 ACET     file1.nc DATA 2000/1/1/0 C xy kg/m2/s  ACET - 1 1  #--> data is kept in kg species/m2/s

Note that the opposite does not work: If file2.nc contains data in units of kgC/m2/s, it is not possible to convert to kg species/m2/s and the following two entries have the same effect:

0 ACET     file2.nc DATA 2000/1/1/0 C xy kg/m2/s  ACET - 1 1  #--> data is converted from kgC/m2/s to kg emitted species/m2/s, which is also kgC/m2/s

0 ACET     file2.nc DATA 2000/1/1/0 C xy kgC/m2/s ACET - 1 1  #--> data is kept in kgC/m2/s

However, if one wants to use file2 for a species not emitted as kg carbon, say CO, the source unit attribute matters!

0 ACETasCO file2.nc DATA 2000/1/1/0 C xy kg/m2/s  CO   - 1 1  #--> data is converted from kgC/m2/s to kg CO/m2/s

0 ACETasCO file2.nc DATA 2000/1/1/0 C xy kgC/m2/s CO   - 1 1  #--> data is kept in kgC/m2/s

Tips for testing

The unit factor applied by HEMCO is written into the HEMCO log file if verbose mode is set to 2 or higher.

Extensions

Overview

Emission inventories sometimes include dynamic source types and nonlinear scale factors that have functional dependencies on local environmental variables such as wind speed or temperature, which are best calculated online during execution of the model. HEMCO includes a suite of additional modules (extensions) that perform online emission calculations for a variety of sources (see list below). Extensions are enabled in section Extension switches of the HEMCO configuration file.

List of extensions

The full list of available extensions is given below. Extensions can be selected individually in section Extension switches of the configuration file, as can the species to be considered.

Description Supported species References
Biogenic VOCs ISOP, ACET, PRPE, C2H4, ALD2, CO, OCPI, MONX, MTPA, MTPO, LIMO, SESQ MEGAN v2.1 (Guenther et al., 2014)).
Air-sea exchange DMS, ACET, CH3I (more species can be added easily) Johnson (2010), Nightingale et al. (2000)
Ship emissions NO, NO2, O3, HNO3 PARANOx (Vinken et al., 2011).
Lightning NOx NO Murray et al., 2012.
Soil and fertilizer NOx NO Hudman et al., 2012.
DEAD dust emissions DST1, DST2, DST3, DST4 Zender et al. (2003).
Ginoux dust emissions DST1, DST2, DST3, DST4 Ginoux et al. (2001).
Sea salt aerosols SALA, SALC, Br2 Jaegle et al. (2011), Gong (2003).
GFED biomass burning NO, CO, ALK4, ACET, MEK, ALD2, PRPE, C3H8, CH2O, C2H6, SO2, NH3, BCPO, BCPI, OCPO, OCPI, POG1, POG2, NAP GFED-3, GFED-4 (van der Werf et al. (2010).
FINN biomass burning NO, CO, ALK4, ACET, MEK, ALD2, PRPE, C3H8, CH2O, C2H6, SO2, NH3, BCPO, BCPI, OCPO, OCPI, GLYC, HAC FINN v1 (Wiedinmyer et al. (2014)).
CH4 wetland and rice emissions CH4 and any kind of tagged CH4 tracers Pickett-Heaps et al. (2011).

Gridded data

HEMCO can host all environmentally independent data sets (e.g. source functions) used by the extensions. The environmental variables are either provided by the atmospheric model or directly read from file through the HEMCO configuration file. Entries in the HEMCO configuration file are given priority over fields passed down from the atmospheric model, i.e. if the HEMCO configuration file contains an entry for a given environmental variable, this field will be used instead of the field provided by the atmospheric model. The field name provided in the HEMCO configuration file must exactly match the name of the HEMCO environmental parameter.

To use the NCEP reanalysis monthly surface wind fields (http://www.esrl.noaa.gov/psd/data/gridded/data.ncep.reanalysis.derived.surface.html) in all HEMCO extensions, add the following two lines to section base emissions of the HEMCO configuration file:

* U10M /path/to/uwnd.mon.mean.nc uwnd 1948-2014/1-12/1/0 C xy m/s * - 1 1 
* V10M /path/to/vwnd.mon.mean.nc vwnd 1948-2014/1-12/1/0 C xy m/s * - 1 1 

This will use these wind fields for all emission calculations, even if the atmospheric model uses a different set of wind fields.

It is legal to assign scale factors (and masks) to the environmental variables read through the HEMCO configuration file. This is particularly attractive for sensitivity studies. For example, a scale factor of 1.1 can be assigned to the NCEP surface wind fields to study the sensitivity of emissions on a 10% increase in wind speed:

In the base emissions section:

* U10M /path/to/uwnd.mon.mean.nc uwnd 1948-2014/1-12/1/0 C xy m/s * 123 1 1 
* V10M /path/to/vwnd.mon.mean.nc vwnd 1948-2014/1-12/1/0 C xy m/s * 123 1 1

In the scale factor section:

123 SURFWIND_SCALE 1.1 - - xy 1 1


As for any other entry in the HEMCO configuration file, spatially uniform values can be set directly in the HEMCO configuration file. For example, a spatially uniform, but monthly varying surface albedo can be specified by adding the following entry to section base emissions of the HEMCO configuration file:

* ALBD 0.7/0.65/0.6/0.5/0.5/0.4/0.45/0.5/0.55/0.6/0.6/0.7 2000/1-12/1/0 C xy 1 * - 1 1

Environmental fields used by HEMCO

Name Dim Unit Description Used by
U10M xy m/s E/W 10m wind speed Air-sea exchange, dust emissions, PARANOx, sea salt aerosols, soil NO
V10M xy m/s N/S 10m wind speed Air-sea exchange, DEAD dust, Ginoux dust, PARANOx, sea salt aerosols, soil NO
ALBD xy unitless Surface albedo Air-sea exchange, DEAD dust, lightning NOx, sea salt aerosols, soil NO
WLI xy unitless 0=water, 1=land, 2=ice CH4 wetlands, DEAD dust, lightning NOx, sea salt aerosols
T2M xy K 2m surface temperature DEAD dust, Rn222, MEGAN, PARANOx, soil NO
TSKIN xy K Surface skin temperature Air-sea exchange, CH4 wetlands, sea salt aerosols
GWETROOT xy unitless Root soil wetness MEGAN
GWETTOP xy unitless Top soil moisture CH4 wetlands, DEAD dust, Ginoux dust, soil NO
SNOWHGT xy kg H2O/m2 (mm H2O) Snow height DEAD dust
SNODP xy m Snow depth CH4 wetlands
USTAR xy m/s Friction velocity DEAD dust
Z0 xy m Surface roughness height DEAD dust
TROPP xy Pa Tropopause pressure Rn222, lightning NO
SZAFACT xy unitless Current SZA / daily total SZA MEGAN
PARDR xy W/m2 Direct photosynthetic active radiation MEGAN
PARDF xy W/m2 Diffuse photosynthetic active radiation MEGAN
RADSWG xy W/m2 Short-wave surface radiation Soil NO
FRCLND xy unitless Olson land fraction Air-sea exchange, Rn222
FRLAND xy unitless Land fraction CH4 wetlands
FROCEAN xy unitless Ocean fraction CH4 wetlands
FRLAKE xy unitless Lake fraction CH4 wetlands
FRLANDIC xy unitless Land ice fraction CH4 wetlands
CLDFRC xy unitless Cloud fraction Soil NO
JNO2 xy 1/s J-value for NO2 PARANOx
JO1D xy 1/s J-value for O1D PARANOx
LAI xy cm2/cm2 Daily leaf area index MEGAN, soil NO
CNV_MFC xyz kg/m2/s Convective mass flux Lightning NO
FRAC_OF_PBL xyz unitless Fraction of grid box in PBL Air-sea exchange, ParaNOx, POPs (Only needed if dry deposition occurs over entire PBL)
SPHU xyz kg H2O/kg air Specific humidity DEAD dust, ParaNOx
TK xyz K Air temperature DEAD dust, lightning NOx, POPs
AIR xyz kg Air mass Rn222, PARANOx
AIRVOL xyz m3 Air volume PARANOx, POPs
O3 xyz kg O3 mass PARANOx
NO xyz kg NO mass PARANOx
NO2 xyz kg NO2 mass PARANOx
HNO3 xyz kg HNO3 mass PARANOx

Restart variables

Some extensions rely on restart variables, i.e. variables that are highly dependent on historical information such as previous-day leaf area index or soil NOx pulsing factor. During a simulation run, the extensions continuously archive all necessary information and update restart variables accordingly. The updated variables become automatically written into the HEMCO restart file (HEMCO_restart.YYYYMMDDhhmmss.nc) at the end of a simulation. The fields from this file can then be read through the HEMCO configuration file to resume the simulation at this date ('warm' restart). For example, the soil NOx restart variables can be made available to the soil NOx extension by adding the following lines to section base emissions of the HEMCO configuration file:

104 PFACTOR         ./HEMCO_restart.$YYYY$MM$DD$HH00.nc  PFACTOR       $YYYY/$MM/$DD/$HH E xy  unitless NO - 1 1
104 DRYPERIOD       ./HEMCO_restart.$YYYY$MM$DD$HH00.nc  DRYPERIOD     $YYYY/$MM/$DD/$HH E xy  unitless NO - 1 1
104 GWET_PREV       ./HEMCO_restart.$YYYY$MM$DD$HH00.nc  GWET_PREV     $YYYY/$MM/$DD/$HH E xy  unitless NO - 1 1
104 DEP_RESERVOIR   ./HEMCO_restart.$YYYY$MM$DD$HH00.nc  DEP_RESERVOIR $YYYY/$MM/$DD/$HH E xy  unitless NO - 1 1

Many restart variables are very time and date-dependent. It is therefore recommended to set the time slice selection flag to E to ensure that only data is read that exactly matches the simulation start date (also see the Base emissions section). HEMCO will perform a 'cold start' if no restart field can be found for a given simulation start date, e.g. default values will be used for those restart variables.

Built-in tools for scaling/masking

HEMCO has built-in tools to facilitate the application of both uniform and spatiotemporal scale factors to emissions calculated by the extensions. At this point, not all extensions take advantage of these tools yet. A list of extensions that support the built-in scaling tools are given below.

For extensions that support the built-in scaling tools, you can specify the uniform and/or spatiotemporal scale factors to be applied to the extension species of interest in section Extension switches of the HEMCO configuration file. For example, to uniformly scale GFED CO by a factor of 1.05 and GFED NO emissions by a factor of 1.2, add the following two lines to the HEMCO configuration file (highlighted in GREEN):

111     GFED              : on    CO/NO/ACET/ALK4
    --> GFED3             :       false
    --> GFED4             :       true
    --> GFED_daily        :       false
    --> GFED_3hourly      :       false
    --> Scaling_CO        :       1.05
    --> Scaling_NO        :       1.20

Similarly, a spatiotemporal field to be applied to the species of interest can be defined via setting ScaleField_<SpecName>, e.g.:

111     GFED              : on    CO/NO/ACET/ALK4
    --> GFED3             :       false
    --> GFED4             :       true
    --> GFED_daily        :       false
    --> GFED_3hourly      :       false
    --> Scaling_CO        :       1.05
    --> Scaling_NO        :       1.20
    --> ScaleField_NO     :       GFED_SCALEFIELD_NO

The corresponding scale field needs be defined in section Base emissions. A simple example would be a monthly varying scale factor for GFED NO emissions:

111 GFED_SCALEFIELD_NO   0.9/1.1/1.3/1.4/1.6/1.7/1.7/1.8/1.5/1.3/0.9/0.8 - 2000/1-12/1/0 C xy unitless * - 1 1

It is legal to apply scale factors and/or masks to the extension scale fields (in the same way as the 'regular' base emission fields). A more sophisticated example on how to scale soil NOx emissions is given on the HEMCO examples wiki page.

Extensions supporting built-in scaling/masking

The following extensions currently support the built-in scaling/masking tools:

  • Soil NOx
  • Methane emissions from rice and wetlands
  • GFED biomass burning
  • FINN biomass burning

Interfaces

In order to perform an emission simulation, information on the simulation grid, species, dates and times must be provided to HEMCO. These information can be passed from an atmospheric model (e.g. GEOS-Chem) or from a suite of configuration files (for stand-alone applications). The emission fields calculated by HEMCO are either returned to the atmospheric model or written to disk.

Stand-alone interface

HEMCO can be employed as stand-alone model, in which case all simulation information is read from separate input files through the stand-alone interface. The calculated emissions are written to netCDF file via the HEMCO diagnostics, as specified through the diagnostics definition file (see the Diagnostics section). See our HEMCO standalone wiki page for more information on downloading, building, and running the HEMCO standalone model.

Interfaces to atmospheric models

HEMCO can be coupled to an atmospheric model and all simulation specifications are obtained from that model through a model-specific interface. Currently, HEMCO is implemented in the NASA Goddard Earth Observing System (GEOS-5) Earth system model and the GEOS-Chem chemical transport model. The GEOS-5 interface is based on the Earth System Modeling Framework (ESMF) software environment and thus easily adoptable to other ESMF applications.

The HEMCO-model interface provides the link between the atmospheric model and HEMCO. It invokes the calls to the HEMCO driver routines (see Behind the scenes of HEMCO).

Diagnostics

Overview

HEMCO diagnostics are organized in ‘collections’, with each collection consisting of a dynamic number of diagnostic fields ('diagnostic containers'). Each collection has a fixed output frequency assigned to it, e.g. all fields within a collection are written out at the same interval (hourly, daily, etc.).

The contents of a collection (i.e. the diagnostics containers) are defined at the beginning of a simulation and become continuously updated and written out during the simulation. A number of attributes attached to each diagnostics define the properties of a given field and how to perform field operations such as time averaging, unit conversion, etc. These attributes include the field name (this will also be the netCDF variable name), the designated field output units, the averaging method, and an explicit unit conversion factor. The latter three determine how data is internally stored and returned for output. The data returned for output is not necessarily in the same units as it is internally stored. By default, HEMCO assumes the passed fields are in kg/m2/s, stores them in kg/m2, and returns the average flux over the designated output interval in the units assigned to this field (default is kg/m2/s). This behavior can be avoided by explicitly setting the averaging method. The currently supported averaging methods are: mean (arithmetic mean), instantaneous (always use the instantaneous value), sum (total sum over the output interval), cumulsum (cumulative sum since simulation start). Explicitly setting the averaging method will disable automatic unit conversion and the fields passed to this diagnostics will be stored as is. The optional unit conversion factor can be set to perform a unit conversion before returning the field for output. It is highly recommended to explicitly set the averaging method for all fields that are not in kg/m2/s.

Built-in diagnostic collections

HEMCO has three built-in diagnostic collections that are automatically created on every HEMCO run. These collections are used by HEMCO for internal data exchange and to write out restart variables. These collections are 'open', i.e. the user can add additional diagnostic fields to them if needed. The user can also define new collections (see below).

Default

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 DiagnFreq in the settings section of the HEMCO configuration file. The name of the corresponding diagnostics files can be specified via the 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 HEMCO_Diagnostics.200808010000.nc. The datetime can denote the beginning, middle, or end (default) of the time interval, as specified by setting DiagnTimeStamp (see below).

Diagnostics output frequency (setting DiagnFreq)

Setting DiagnFreq of the HEMCO configuration file determines the output frequency of the default HEMCO diagnostics. It can be set to one of the following values: Always, Hourly, Daily, Monthly, Annually, End.

As of version 1.1.009, more advanced output intervals can be provided as an 15 digit integer string of format YYYYMMDD HHMMSS denoting the year-month-day and hour-minute-second output frequency, respectively. For example, to write out the diagnostics every day DiagnFreq can be set to 00000001 000000. Similarly, to write out the diagnostics every 2 hours DiagnFreq can be set to 00000000 020000.

Diagnostics output time stamp

By default, the time stamp on the diagnostics output file denotes the end of the diagnostic time window. For instance, if the output frequency is one hour, file HEMCO_Diagnostics.200808010100.nc contains the diagnostics collected during the time period Aug 1, 2008, 0000z to Aug 1, 2008, 0100z. As of HEMCO v1.1.012, this behavior can be changed via setting DiagnTimeStamp. By setting DiagnTimeStamp to Start, the output files will use the time stamp at the beginning of the diagnostics window, e.g. the diagnostics between time period Aug 1, 2008, 0000z to Aug 1, 2008, 0100z will be written as HEMCO_Diagnostics.200808010000.nc. Similarly, setting DiagnTimeStamp to Mid will use the mid-point of the diagnostics window, e.g. the aforementioned diagnostics would be written as HEMCO_Diagnostics.200808010030.nc. The default setting for DiagnTimeStamp is End.

Diagnostics reference time

The time unit of the HEMCO diagnostics is always given in 'time since reference datetime'. Prior to HEMCO v1.1.017, a fixed reference datetime is used: 'hours since 1985-01-01 00:00:00 GMT'. As of v1.1.017, the default unit is 'hours since YYYY-MM-DD hh:mn:ss GMT', where YYYY-MM-DD hh:mn:ss is the diagnostics datetime. For example, diagnostics for Aug 8 2008, 0am will have time units of 'hours since 2008-08-01 00:00:00 GMT', diagnostics written an hour later will be in units of 'hours since 2008-08-01 01:00:00 GMT', etc. A fixed reference time can be explicitly provided in setting DiagnRefTime. For example, to restore the time units used prior to v1.1.017, add the following setting to the options section in the HEMCO configuration file:

DiagnRefTime   : hours since 1985-01-01 00:00:00 GMT
Dimensions of diagnostics

By default, the created netCDF diagnostics file contains the definition of the time dimension and all three space dimensions (lon,lat,lev), even if all output diagnostics are only 2D, i.e. the level dimension is not needed. This can be suppressed by enabling the optional setting DiagnNoLevDim. If this option is set to 'True', the level dimension is only defined in the netCDF file if at least one of the output diagnostics is 3D.

Diagnostics input file

Fields to be added to the default collection can be listed in the diagnostics definitions input file. The name of this file is specified in setting DiagnFile. Each line of the diagnostics definition file represents a diagnostics container. It expects the following 7 entries (all on the same line):

  1. Container name (character)
  2. HEMCO species (character)
  3. Extension number (integer)
  4. Emission category (integer)
  5. Emission hierarchy (integer)
  6. Space dimension (2 or 3)
  7. Output unit (character)
  8. OPTIONAL: Long name of diagnostic, for the netCDF long_name variable attribute (character)

NOTE: If you are not sure what the container name, extension number, category, and hierarchy are for a given diagnostic, you can set VERBOSE to 3 in the HEMCO configuration file, and run a very short simulation (a couple of model hours). Then you can look at the output in the HEMCO.log file to determine what these values should be.

ALSO NOTE: The long name can be omitted when using GEOS-Chem in "Classic" mode, but may be needed when using GEOS-Chem in HP mode (aka GCHP).

For example, the following entries will make HEMCO write out total NO and CO emissions, as well as GFED biomass burning CO emissions (e.g. only emissions from extension 111):

# Name         Spec ExtNr  Cat Hier Dim Unit     LongName
EmisNO_Total   NO   -1     -1  -1   2   kg/m2/s  NO_emission_flux_from_all_sectors
EmisCO_Total   CO   -1     -1  -1   2   kg/m2/s  CO_emission_flux_from_all_sectors
EmisCO_GFED    CO   111    -1  -1   2   kg/m2/s  CO_emission_flux_from_biomass_burning

If you want to just diagnose regional emissions, then you need to set the diagnostics extension number, category and hierarchy accordingly. For example, if you want NEI2005 emissions for CO over the USA, then add this line:

#Name          Spec ExtNr  Cat Hier Dim Unit     Longname
EmisCO_NEI2011 CO   0      1   50   2   kg/m2/s  CO_emission_flux_from_NEI2011_inventory

It is important that you define valid values for all attributes up to the hierarchy. As soon as you set an attribute to default (-1), HEMCO will take the sum up to this attribute. For example, the following diagnostics would simply return total base emissions:

#Name          Spec ExtNr  Cat Hier Dim Unit     Longname
EmisCO_NEI2011 CO   0      -1  50   2   kg/m2/s  CO_emission_flux_from_NEI2011_inventory

Restart

The output frequency of the restart diagnostics is End, meaning that its content is only written out at the end of a simulation. The HEMCO restart collection primarily consists of a suite of fields needed by some of the HEMCO extensions for a 'warm' HEMCO restart (e.g. the 10-day running mean temperature, etc.). These fields are automatically added to the HEMCO restart collection and filled within the respective extensions. Once archived, fields can be made available to an extension via the HEMCO configuration file.

Manual

Fields in the manual collection do not become written out to disk. Rather, they provide a tool to exchange data files within and outside of HEMCO, e.g. to pass sector-specific emission fluxes from HEMCO to the atmospheric model. Some HEMCO extensions automatically create and fill a number of manual diagnostics. For example, the PARANOX extension stores the O3 and HNO3 loss fluxes in the manual diagnostics PARANOX_O3_DEPOSITION_FLUX and PARANOX_HNO3_DEPOSITION_FLUX, respectively.

Adding new collections or diagnostics fields, and importing its content into the model environment

The content of the default collection can be specified through the HEMCO diagnostics definitions input file. The content of the manual and/or restart collection currently needs to be defined within the model code (e.g. it is hard-coded). This should be done in high-level routines, i.e. at the HEMCO - model interface level.

Module hco_diagn_mod.F90 (found in HEMCO/Core/) provides a suite of routines to define, fill, obtain, etc. diagnostic fields. Similarly, hco_restart_mod.F90 (also found in HEMCO/Core/) provides routines for managing HEMCO restart variables.

Input file format

Currently, HEMCO can read data from the following data sources:

  • Gridded data from netCDF file. More detail on the netCDF file are given below. In an ESMF environment, the MAPL/ESMF generic I/O routines are used to read/remap the data. In a non-ESMF environment, the HEMCO generic reading and remapping algorithms are used. Those support vertical regridding, unit conversion, and more (see below).
  • Scalar data directly specified in the HEMCO configuration file. Scalar values can be set in the HEMCO configuration file directly. If multiple values - separated by the separator sign (/) - are provided, they are interpreted as temporally changing values: 7 values = Sun, Mon, ..., Sat; 12 values = Jan, Feb, ..., Dec; 24 values = 12am, 1am, ..., 11pm (local time!). Mask box boundaries can also be provided directly in the HEMCO configuration file. The entry must have exactly four values, interpreted as lower left and upper right mask box corners (lon1/lat1/lon2/lat2).
  • Country-specific data specified in a separate ASCII file. This file must end with the suffix '.txt' and hold the country specific values listed by country ID. The IDs must correspond to the IDs of a corresponding (netCDF) mask file. The mask file must be listed in the HEMCO configuration file. For example:
  #==============================================================================
  # --- Country mask file ---
  #==============================================================================
  * COUNTRY_MASK $ROOT/MASKS/v2014-07/countrymask_0.1x0.1.nc CountryID 2000/1/1/0 C xy count * - 1 1
In the .txt file containing the country-specific scale factors, the container name of this mask file (e.g. COUNTRY_MASK) must be given in the first line of the file. In that file, ID 0 is reserved for the default values that are applied to all countries with no specific values listed. The .txt file must be structured as follows:
  # Country mask field name
  COUNTRY_MASK

  # CountryName CountryID CountryValues
  DEFAULT 0 1.0/2.0/3.0/4.0/5.0/6.0/7.0

The CountryValues are interpreted the same way as scalar values, except that they are applied to all grid boxes with the given country ID.

Gridded input files are expected to be in the Network Common Data Form (netCDF) format (http://www.unidata.ucar.edu/software/netcdf/) and must adhere to the COARDS metadata conventions (http://ferret.wrc.noaa.gov/noaa_coop/coop_cdf_profile.html). In particular, the following points must be fulfilled:

Attribute Description
Latitude and Longitude dimension The longitude and latitude variables must be given in the netCDF file as variables lon and lat, respectively. As of version 1.1.011, variables longitude, Longitude, latitude, and Latitude are also supported. The variable name must be identical to the corresponding dimension name, e.g. if the longitude variable name is Longitude the longitude dimension must also be named Longitude.

At this stage of development, only rectilinear (lon-lat) grids are supported. The data is automatically regridded onto the simulation grid (see Behind the scenes of HEMCO for more details).

Vertical dimension In a non-ESMF environment, 3D data is interpolated onto the simulation levels if the input data is on vertical levels other than the HEMCO model levels (see the Vertical regridding section). Data on non-model levels must be on a hybrid sigma pressure coordinate system. In order to properly determine the vertical pressure levels of the input data, the file must contain the surface pressure values and the hybrid coefficients (a, b) of the coordinate system. Further, the level variable must contain the attributes standard_name and formula_terms (the attribute positive is recommended but not required). A header excerpt of a valid netCDF file is shown below:
float lev(lev) ;
    lev:standard_name = ”atmosphere_hybrid_sigma_pressure_coordinate” ;
    lev:units = ”level” ;
    lev:positive = ”down” ;
    lev:formula_terms = ”ap: hyam b: hybm ps: PS” ;
float hyam(nhym) ;
    hyam:long_name = ”hybrid A coefficient at layer midpoints” ;
    hyam:units = ”hPa” ;
float hybm(nhym) ;
    hybm:long_name = ”hybrid B coefficient at layer midpoints” ;
    hybm:units = ”1” ;
float time(time) ;
    time:standard_name = ”time” ;
    time:units = ”days since 2000-01-01 00:00:00” ;
    time:calendar = ”standard” ;
float PS(time, lat, lon) ;
    PS:long_name = ”surface pressure” ;
    PS:units = ”hPa” ;
float EMIS(time, lev, lat, lon) ;
    EMIS:long_name = ”emissions” ;
    EMIS:units = ”kg m-2 s-1” ;

Vertical regridding is currently not supported in an ESMF environment.

Time Times should be given as relative times, e.g. relative to a specified reference date. Accepted are days since yyyy-mm-dd, hours since yyyy-mm-dd hh:mm:ss, and minutes since yyyy-mm-dd hh:mm:ss. There have been problems with some netCDF files with reference dates prior to 1901 (e.g. days since 1900-1-1) so reference years after 1900 should be used if possible.

Weekly data must contain seven time slices in increments of one day. The first entry must represent Sunday data, irrespective of the real weekday of the assigned datetime. It is possible to store weekly data for more than one time interval, in which case the first weekday (i.e. Sunday) must hold the starting date for the given set of (seven) time slices. For instance, weekly data for every month of a year can be stored as 12 sets of 7 time slices. The datetime of the first entry of each set must fall on the first day of every month, and the following six entries must be increments of one day. Currently, weekly data from netCDF files is not correctly read in an ESMF environment.

Data units It is recommended to store data in one of the HEMCO standard units: kg/m2/s and kg(C)/m2/s for fluxes; kg/m3 and kg(C)/m3 for concentrations; 1 for unitless data; and count for index-based data, i.e. discrete distributions (for instance, land types represented as integer values between 1 and 28). HEMCO will attempt to convert all data to one of those units, unless otherwise specified via the srcUnit attribute (see the Base emissions 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 given data set. It is also possible to convert between species-based and molecule-based units (e.g. kg vs. kg(C)). This conversion is based on the emitted molecular weight and the molecular ratio of the given species (see the HEMCO-model Interface section). More details on unit conversion are given in module hco_unit_mod.F90 (found in HEMCO/Core/).

Index-based data is regridded in such a manner that every grid box on the new grid represents the index with the largest relative contribution from the overlapping boxes of the original grid. All other data are regridded as 'concentration' quantities, i.e. conserving the global weighted average.

For more information, we invite you to read our Preparing data files for use with HEMCO wiki page.

Arbitrary additional netCDF dimension

As of v1.1.010, 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 SrcDim file attribute (see srcDim in the Base emissions section). This feature is currently not available in an ESMF environment.

Vertical regridding

In a non-ESMF environment, HEMCO is able to perform some limited vertical interpolation. In the simplest case, the input data has the same number of vertical levels as the HEMCO vertical grid (nz). In this case, HEMCO explicitly assumes that the input data is already on model levels and no interpolation is performed. The same is true if the input data has nz+1 vertical levels, in which case the data is interpreted as being on grid edges instead of grid midpoints. 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).

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).

Nested HEMCO configuration files

HEMCO configuration files can be nested by adding an include statement to the master HEMCO configuration file (HEMCO_Config.rc), e.g.:

>>>include HEMCO_Config_nested.rc

The emission information contained in HEMCO_Config_nested.rc will then be used along with the emission configuration specified in HEMCO_Config.rc. Information in the master configuration file take precedence over the information in the nested files. If the same setting or extension switch/option is defined in both the master and the nested configuration file, HEMCO will use the one from the master file.

Include statements can be placed anywhere in the HEMCO configuration file. It is legal to nest multiple files (up to 5 levels deep).

pyHEMCO GUI

To facilitate the creation and modification of a HEMCO configuration file, a Graphical User Interface (GUI) is currently being developed. The GUI contains the following features:

  • Modification of existing configuration files.
  • Creation of new configuration files, either from scratch or starting from an existing file.
  • Direct execution of the stand-alone version of HEMCO
  • Preview of emissions from individual inventories, extensions, or any combination of it.

The pyHEMCO GUI is written in Python and linked to the pyGC visualization and data analysis package developed for GEOS-Chem. The developer version of the pyHEMCO GUI can be found at https://github.com/christophkeller. This version is still under development and not yet operational.

Behind the scenes of HEMCO

Overview

This section provides a short description of the main principles of HEMCO. More details are provided in the source code, and references to the corresponding modules is given where appropriate. The HEMCO code can be broken up into three parts: core code, extensions, interfaces. The core code consists of all core modules that are essential for every HEMCO simulation. The extensions are a collection of emission parameterizations that can be optionally selected (e.g. dust emissions, air-sea exchange, etc.). Most of the extensions require meteorological variables (2D or 3D fields) passed from an atmospheric model or an external input file to HEMCO. The interfaces are top-level routines that are only required in a given model environment (e.g. in stand-alone mode or under an ESMF framework). The HEMCO-model interface routines are located outside of the HEMCO code structure, calling down to the HEMCO driver routines for both the HEMCO core and extensions. HEMCO stores all emission data (base emissions, scale factors, masks) in a generic data structure (a 'HEMCO data container'). Input data read from disk is translated into this data structure by the HEMCO input/output module (hcoio_dataread_mod.F90 found in HEMCO/Core/). This step includes unit conversion and regridding.

HEMCO data objects

All emission data (base emissions, scale factors, masks) are internally stored in a data container. For each data element of the HEMCO configuration file, a separate data container object is created when reading the configuration file at the beginning of the simulation. The data container object is a FORTRAN derived type that holds information of one entry of the configuration file. All file data information such as filename, file variable, time slice options, etc. are stored in a FileData derived type object (defined in hco_filedata_mod.F90). This object also holds a pointer to the data itself. All data is stored as 2 or 3 dimensional data arrays. HEMCO can keep multiple time slices in memory simultaneously, e.g. for diurnal scale factors, in which case a vector of data arrays is created. Data arrays are defined in module hco_arr_mod.F90.

Data containers (and as such, emissions data) are accessed through three different linked lists: ConfigList, ReadList, EmisList. These lists all point to the same content (i.e. the same containers) but ordered in a manner that is most efficient for the intended purpose: for example, ReadList contains sub-lists of all containers that need to be updated annually, monthly, daily, hourly, or never. Thus, if a new month is entered, only a few lists (monthly, daily and hourly) have to be scanned and updated instead of going through the whole list of data containers. Similarly, EmisList sorts the data containers by model species, emission category and hierarchy. 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 hco_datacont_mod.F90. Specific routines for ConfigList, ReadList and EmisList are defined in hco_config_mod.F90, hco_readlist_mod.F90, and hco_emislist_mod.F90, respectively.

Core

HEMCO core consists of all routines and variables required to read, store, and update data used for emissions calculation. The driver routines to execute (initialize, run and finalize) a HEMCO core simulation are (see hco_driver_mod.F90: HCO_INIT, HCO_RUN, HCO_FINAL). These are also the routines that are called at the interface level (see the HEMCO-model interface section). Each HEMCO simulation is defined by its state object HcoState, which is a derived type that holds all simulation information, including a list of the defined HEMCO species, emission grid information, configuration file name, and additional run options. More details on the HEMCO state object can be found in hco_state_mod.F90. HcoState is defined at the interface level and then passed down to all HEMCO routines (see also the HEMCO-model interface section).

Initialize: HCO_INIT

Before running HEMCO, all variables and objects have to be initialized properly. The initialization of HEMCO occurs in three steps:

  1. Read the HEMCO configuration file (subroutine Config_ReadFile in hco_config_mod.F90). This writes the content of the entire configuration file into buffer, and creates a data container for each data item (base emission, scale factor, mask) in ConfigList.
  2. Initialize HcoState.
  3. Call HCO_INIT, passing HcoState to it. This initializes the HEMCO clock object (see hco_clock_mod.F90) and creates the ReadList (hco_readlist_mod.F90). The ReadList links to the data containers in ConfigList, but sorted by data update frequency. Data that is not used at all (e.g. scale factors that are not used by any base emission, or regional emissions that are outside of the emission grid). The EmisList linked list is only created in the run call.

Note that steps 1 and 2 occur at the interface level (see the HEMCO-model interface section).

Run: HCO_RUN

This is the main function to run HEMCO. It can be repeated as often as necessary. Before calling this routine, the internal clock object has to be updated to the current simulation time (subroutine HcoClock_Set in hco_clock_mod.F90). HCO_RUN performs the following steps:

  1. Updates the time slice index pointers. This is to make sure that the correct time slices are used for every data container. For example, hourly scale factors can be stored in a data container holding 24 individual 2D fields. Module hco_tidx_mod.F90 organizes how to properly access these fields.
  2. Read/update the content of the data containers (ReadList_Read). Checks if there are any fields that need to be read/updated (e.g. if this is a new month compared to the previous time step) and updates these fields if so by calling the data interface (see the HEMCO-model interface section).
  3. Creates/updates the EmisList object. Similar to ReadList, EmisList points to the data containers in ConfigList, but sorted according to species, emission hierarchy, emissions category. To optimize emission calculations, EmisList already combines base emission fields that share the same species, category, hierarchy, scale factors, and field name (without the field name tag, see the Base emissions section).
  4. Calculate core emissions for the current simulation time. This is performed by subroutine hco_calcemis in hco_calc_mod.F90. This routine walks through EmisList and calculates the emissions for every base emission field by applying the assigned scale factors to it. The (up to 10) container IDs of all scale factors connected to the given base emission field (as set in the HEMCO configuration file) are stored in the data container variable ScalIDs. A container ID index list is used to efficiently retrieve a pointer to each of those containers (see cIDList in hco_datacont_mod.F90).

Finalize: HCO_FINAL

This routine cleans up all internal lists, variables, and objects. This does not clean up the HEMCO state object, which is removed at the interface level.

Extensions

HEMCO extensions are used to calculate emissions based on meteorological input variables and/or non-linear parameterizations. Each extension is provided in a separate FORTRAN module. Each module must contain a public subroutine to initialize, run and finalize the extension. Emissions calculated in the extensions are added to the HEMCO emission array using subroutine HCO_Emis_Add in HCO_FluxArr_mod.F90.

Meteorological input data is passed to the individual extension routines through the extension state object ExtState, which provides a pointer slot for all met fields used by any of the extension (see hcox_state_mod.F90). These pointers must be assigned at the interface level (see the HEMCO-model interface section).

In analogy to the core module, the three main routines for the extensions are (in hcox_driver_mod.F90):

  • HCOX_INIT
  • HCOX_RUN
  • HCOX_FINAL

These subroutines invoke the corresponding calls of all (enabled) extensions and must be called at the interface level (after the core routines).

Extension settings (as specified in the configuration file, see also the Extension Switches section) are automatically read by HEMCO. For any given extension, routines GetExtNr and GetExtOpt can be used to obtain the extension number and desired setting value, respectively (see HCO_ExtList_Mod.F90). Routine 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 the EmisList, but ignored by the HEMCO core module during emissions calculation. Pointers to these data arrays can be obtained through routine EmisList_GetDataArr in HCO_EmisList_Mod.F90. Note that this routine identifies the array based on its container name. It is therefore important that the container name set in the configuration file matches the names used by this routine!

Interfaces

HEMCO - model interface

The interface provides the link between HEMCO and the model environment. This may be a sophisticated Earth System model or a simple environment that allows the user to run HEMCO in standalone mode. The standalone interface is provided along with the HEMCO distribution (hcoi_standalone_mod.F90). The HEMCO-GEOS-Chem model interface is included in the GEOS-Chem source code (hcoi_gc_main_mod.F90 in GeosCore). HEMCO has also been successfully employed as a stand-alone gridded component within an ESMF environment. Please contact Christoph Keller for more information on the ESMF implementation.

The interface routines provide HEMCO with all the necessary information to perform the emission calculation. This includes the following tasks:

Initialization:

  • Read the configuration file (Config_ReadFile in hco_config_mod.F90).
  • Initialize HcoState object (HcoState_Init in hco_state_mod.F90).
  • Define the emission grid. Grid definitions are stored in HcoState%Grid. The emission grid is defined by its 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 (DEAD dust emissions and lightning NOx) and may be left undefined if those are not used.
  • Define emission species. Species definitions are stored in vector HcoState%Spc(:) (one entry per species). For each species, the following parameter are required:
    1. HEMCO species ID: unique integer index for species identification. For internal use only.
    2. Model species ID: the integer index assigned to this species by the employed model.
    3. Species name
    4. Species molecular weight in g/mol.
    5. Emitted species molecular weight in g/mol. This value can be different to the species molecular weight if species are emitted on a molecular basis, e.g. in mass carbon (in which case the emitted molecular weight becomes 12 g/mol).
    6. Molecular ratio: molecules of emitted species per molecules of species. For example, if C3H8 is emitted as kg C, the molecular ratio becomes 3.
    7. K0: Liquid over gas Henry constant in M/atm.
    8. CR: Temperature dependency of K0 in K.
    9. pKa: The species pKa, used for correction of the Henry constant.

The molecular weight - together with the molecular ratio - determine the mass scaling factors used for unit conversion in hco_unit_mod.F90. The Henry coefficients are only used by the air-sea exchange extension (and only for the specified species) and may be left undefined for other species and/or if the extension is not used.

  • Define simulation time steps. The emission, chemical and dynamic time steps can be defined separately.
  • Initialize HEMCO core (HCO_Init in hco_driver_mod.F90)
  • Initialize HEMCO extensions (HCOX_Init in hcox_driver_mod.F90)

Run:

  • Set current time (HcoClock_Set in hco_clock_mod.F90)
  • Reset all emission and deposition values (HCO_FluxArrReset in hco_fluxarr_mod.F90)
  • Run HEMCO core to calculate emissions (HCO_Run in hco_driver_mod.F90)
  • Link the used meteorology field objects of ExtState to desired data arrays (this step may also be done during initialization)
  • Run HEMCO extensions to add extensions emissions (HCOX_Run in hcox_driver_mod.F90)
  • Export HEMCO emissions into desired environment

Finalization:

  • Finalize HEMCO extensions and extension state object ExtState (HCOX_Final in hcox_driver_mod.F90).
  • Finalize HEMCO core (HCO_Final in hco_driver_mod.F90).
  • Clean up HEMCO state object HcoState (HcoState_Final in hco_state_mod.F90).

Data interface (reading and regridding)

The data interface (hcoi_dataread_mod.F90) organizes reading, unit conversion, and remapping of data from source files. Its public routine HCOI_DataRead is only called by subroutine ReadList_Fill in hco_readlist_mod.F90. Data processing is performed in three steps:

  1. Read data from file using the source file information (file name, source variable, desired time stamp) provided in the configuration file.
  2. Convert unit to HEMCO units based on the unit attribute read from disk and the srcUnit attribute set in the configuration file. See the Input file format section for more information.
  3. Remap original data onto the HEMCO emission grid. The grid dimensions of the input field are determined from the source file. If only horizontal regridding is required, e.g. for 2D data or if the number of vertical levels of the input data is equal to the number of vertical levels of the HEMCO grid, the horizontal interpolation routine used by GEOS-Chem is invoked. If vertical regridding is required or to interpolate index-based values (e.g. discrete integer values), the NcRegrid tool described in Joeckel (2006) is used.

Run multiple instances of HEMCO

Since version 2 of HEMCO, it is possible to run multiple instances of HEMCO at the same time. These instances can operate on different grids, use different configuration files, etc. This is made possible by wrapping all information of a HEMCO simulation into a HCO_State derived type object (defined in Core/hco_state_mod.F90). Similarly, all emission extension information is included in an Ext_State derived type (in Extensions/hcox_state_mod.F90). These two objects together fully define the HEMCO setup and are being passed to the top level HEMCO routines (INIT/RUN/FINALIZE), e.g.:

 CALL HCO_Run( am_I_Root, HcoState, Phase, RC )
 ...
 CALL HCOX_Run( am_I_Root, HcoState, ExtState, RC )

To run more than one HEMCO instance in parallel, one need to define multiple HcoState instances and then call each of these separately, e.g.:

 CALL HCO_Run( am_I_Root, HcoStateA, Phase, RC )
 CALL HCO_Run( am_I_Root, HcoStateB, Phase, RC )
 etc.

The HEMCO state objects also carry the 3D emission arrays, and when using multiple instances one needs to ensure that these arrays are properly connected to the 'emission end user', e.g. PBL mixing routine, etc. In the GEOS-Chem implementation of HEMCO, the module hco_interface_mod.F90 (in GeosCore) provides the interface between HEMCO and GEOS-Chem: it is the owner of the HcoState and ExtState object, and contains a number of wrapper routines to exchange information between HEMCO and GEOS-Chem. In the GEOS model, the standalone HEMCO component uses a linked list that can carry a dynamic number of HEMCO instances, and then loops over the linked list to perform all model operations (init,run,finalize) on all members of the linked list.

IMPORTANT NOTE: Most HEMCO extensions still use global arrays and currently cannot be used in multi-instance simulations. As of 8/29/2018, the following extensions are likely to cause problems in multi-instance simulations: Ginoux dust emissions, FINN biomass burning, GFED biomass burning, Iodine emissions, PARANOx ship emissions, sea flux emissions, sea salt emissions.

References

  1. Ginoux, P., M. Chin, I. Tegen, J. Prospero, B. Hoben, O. Dubovik, and S.-J. Lin, Sources and distributions of dust aerosols simulated with the GOCART model, J. Geophys. Res., 106, D17, 20'255-20'273, 2001.
  2. Giglio, L., J. T. Randerson, and G. R. van der Werf, Analysis of daily, monthly, and annual burned area using the fourth-generation global fire emissions database (GFED4), J. Geophys. Res, Biogeosciences., 118, Issue 1, 317-328, March 2013. (Article)
  3. Gong, S. L.: A parameterization of sea-salt aerosol source function for sub- and super-micron particles, Global Biogeochem. Cy., 17, 1097, doi:10.1029/2003GB002079, 2003.
  4. Guenther, A. B., Jiang, X., Heald, C. L., Sakulyanontvittaya, T., Duhl, T., Emmons, L. K., and Wang, X.: The Model of Emissions of Gases and Aerosols from Nature version 2.1 (MEGAN2.1): an extended and updated framework for modeling biogenic emis- sions, Geosci. Model Dev., 5, 1471–1492, doi:10.5194/gmd-5- 1471-2012, 2012.
  5. Hudman, R. C., Moore, N. E., Mebust, A. K., Martin, R. V., Russell, A. R., Valin, L. C., and Cohen, R. C.: Steps towards a mechanistic model of global soil nitric oxide emissions: implementation and space based-constraints, Atmos. Chem. Phys., 12, 7779–7795, doi:10.5194/acp-12-7779-2012, 2012.
  6. Janssens-Maenhout, A., Petrescu, A., Muntean, M., and Blujdea, V.: Verifying Greenhouse Gas Emissions: Methods to Support International Climate Agreements, The National Academies Press, Washington, DC., 2010.
  7. Joeckel P: , Technical note: Recursive rediscretisation of geo-scientific data in the Modular Earth Submodel System (MESSy), Atmos. Chem. Phys., 6, 3557–3562, 2006.
  8. Jaeglé, L., Quinn, P. K., Bates, T. S., Alexander, B., and Lin, J.-T.: Global distribution of sea salt aerosols: new constraints from in situ and remote sensing observations, Atmos. Chem. Phys., 11, 3137–3157, doi:10.5194/acp-11-3137-2011, 2011.
  9. Johnson, M. T.: A numerical scheme to calculate temperature and salinity dependent air-water transfer velocities for any gas, Ocean Sci., 6, 913–932, doi:10.5194/os-6-913-2010, 2010.
  10. Keller, C. A., Long, M. S., Yantosca, R. M., Da Silva, A. M., Pawson, S., and Jacob D. J.: , HEMCO v1.0: a versatile, ESMF-compliant component for calculating emissions in atmospheric models, Geosci. Model Dev., 7, 1409–1417, 2014. (Article)
  11. Lamarque, J.-F., Bond, T. C., Eyring, V., Granier, C., Heil, A., Klimont, Z., Lee, D., Liousse, C., Mieville, A., Owen, B., Schultz, M. G., Shindell, D., Smith, S. J., Stehfest, E., Van Aardenne, J., Cooper, O. R., Kainuma, M., Mahowald, N., McConnell, J. R., Naik, V., Riahi, K., and van Vuuren, D. P.: Historical (1850–2000) gridded anthropogenic and biomass burning emissions of reactive gases and aerosols: methodology and application, Atmospheric Chemistry and Physics, 10, 7017–7039, 2010.
  12. Murray, L. T., Jacob, D. J., Logan, J. A., Hudman, R. C., and Koshak, W. J.: Optimized regional and interannual variability of lightning in a global chemical transport model constrained by LIS/OTD satellite data, J. Geophys. Res.-Atmos., 117, D20307, doi:10.1029/2012JD017934, 2012.
  13. Nightingale, P. D., Malin, G., Law, C. S., Watson, A. J., Liss, P. S., Liddicoat, M. I., Boutin, J., and Upstill-Goddard, R. C.: In situ evaluation of air-sea gas exchange parameterizations using novel conservative and volatile tracers, Global Biogeochem. Cy., 14, 373–387, doi:10.1029/1999GB900091, 2000.
  14. Pickett-Heaps C.A., Jacob D.J., Wecht K.J., et al.: Magnitude and seasonality of wetland methane emissions from the Hudson Bay Lowlands (Canada). ACP, 11, 3773-3779, 2011.
  15. Stettler, M., Eastham, S., and Barrett, S.: Air quality and public health impacts of UK airports. Part I: Emissions, Atmospheric Environment, 45, 5415 – 5424, 2011.
  16. Vestreng, V., Ntziachristos, L., Semb, A., Reis, S., Isaksen, I. S. A., and Tarrasón, L.: Evolution of NOx emissions in Europe with focus on road transport control measures, Atmospheric Chemistry and Physics, 9, 1503–1520, 2009.
  17. van der Werf, G. R., Randerson, J. T., Giglio, L., Collatz, G. J., Mu, M., Kasibhatla, P. S., Morton, D. C., DeFries, R. S., Jin, Y., and van Leeuwen, T. T.: Global fire emissions and the contribution of deforestation, savanna, forest, agricultural, and peat fires (1997–2009), Atmospheric Chemistry and Physics, 10, 11 707–11 735, 2010.
  18. Vinken, G. C. M., Boersma, K. F., Jacob, D. J., and Meijer, E. W.: Accounting for non-linear chemistry of ship plumes in the GEOS-Chem global chemistry transport model, Atmos. Chem. Phys., 11, 11707–11722, doi:10.5194/acp-11-11707-2011, 2011.
  19. Wiedinmyer, C., Yokelson, R. J., and Gullett, B. K.: Global Emissions of Trace Gases, Particulate Matter, and Hazardous Air Pollutants from Open Burning of Domestic Waste, Environmental Science & Technology, 16, 9523–9530, 2014.
  20. Zender, C. S., Bian, H., and Newman, D.: Mineral Dust En- trainment and Deposition (DEAD) model: Description and 1990s dust climatology, J. Geophys. Res.-Atmos., 108, 4416, doi:10.1029/2002JD002775, 2003.

--Bob Y. 14:55, 30 March 2015 (EDT)

More examples

Please see our HEMCO examples wiki page for more examples about using HEMCO.

Changelog

The HEMCO version number is defined in module hco_error_mod.F90. It is printed into the HEMCO log-file at the beginning of a simulation.

We have now moved the HEMCO version history to our HEMCO versions wiki page.

Known and resolved issues

Please visit the following links for a list of known issues in HEMCO, plus issues that have since been resolved:

  1. Currently unresolved issues
  2. HEMCO issues that have now been resolved