Difference between revisions of "The HEMCO User's Guide"

From Geos-chem
Jump to: navigation, search
m (Add a missing - to ALBD example)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
HEMCO user guide by Christoph Keller (christoph.a.keller@nasa.gov)
+
This content has been migrated to [https://hemco.readthedocs.io <tt>hemco.readthedocs.io</tt>].
 
+
last updated: Jan 16, 2019.
+
 
+
== 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 [[#References|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 ([[#References|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 [[HEMCO data directories|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 [[HEMCO examples|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|''Behind the scenes of HEMCO'']] and [[#Interfaces|''Interfaces'']]).
+
 
+
=== Example 1: Adding MACCITY global anthropogenic emissions ===
+
 
+
Suppose monthly anthropogenic CO emissions from the MACCity inventory ([[#References|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 [[#Interfaces|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|''Base Emissions'']] and [[#Scale factors|''Scale Factors'']] sections.
+
 
+
As described in [[#Data collections|the ''Data Collections'' section]], all of the files contained between the brackets <tt>(((MACCITY</tt> and <tt>)))MACCITY</tt> 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 ([[#References|Vestreng et al., 2009]]) (in EMEP.nc) to the simulation, the configuration file can be modified as follows (changes are highlighted in <span style="color:green">GREEN</span>):
+
 
+
###############################################################################
+
#### BEGIN SECTION EXTENSION SWITCHES
+
###############################################################################
+
# ExtNr ExtName          on/off  Species
+
0      Base              : on    *
+
    --> MACCITY          :      true
+
    <span style="color:green">--> EMEP              :      true</span>
+
+
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
+
+
<span style="color:green">(((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</span>
+
+
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
+
+
<span style="color:green">1001 MASK_EUROPE $ROOT/mask_europe.nc MASK 2000/1/1/0 C xy 1 1 -30/30/45/70</span>
+
+
END SECTION MASKS
+
 
+
For now, we have omitted the Settings section because nothing has changed since [[#Example_1:_Adding_MACCITY_global_anthropogenic_emissions|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 ([[#References|Stettler et al., 2011]]), available in file AEIC.nc, add the following <span style="color:green">lines in GREEN</span> to the HEMCO configuration file:
+
 
+
###############################################################################
+
#### BEGIN SECTION EXTENSION SWITCHES
+
###############################################################################
+
# ExtNr ExtName          on/off  Species
+
0      Base              : on    *
+
    --> MACCITY          :      true
+
    --> EMEP              :      true
+
    <span style="color:green">--> AEIC              :      true</span>
+
+
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
+
+
<span style="color:green">(((AEIC
+
0 AEIC_CO    $ROOT/AEIC.nc    CO 2005/1-12/1/0      C xyz kg/m2/s CO -      2 1
+
)))AEIC</span>
+
+
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 ([[#References|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 <span style="color:green">GREEN</span>.)  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'''
+
#------------------------------------------------------------------------------
+
<span style="color:green">111    GFED              : on    CO
+
    --> GFED3            :      false
+
    --> GFED4            :      true
+
    --> GFED_daily        :      false
+
    --> GFED_3hourly      :      false
+
    --> Scaling_CO        :      1.05</span>
+
+
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
+
###############################################################################
+
+
<span style="color:green">'''# --- 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</span>
+
+
END SECTION BASE EMISSIONS
+
 
+
As in the previous examples, the tags beginning with <tt>(((</tt> and <tt>)))</tt> 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. <tt>Scaling_CO</tt>) 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 <span style="color:green">line in GREEN</span> 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
+
<span style="color:green">0 MACCITY_NO $ROOT/MACCity.nc NO 1980-2014/1-12/1/0 C xy kg/m2/s NO 1 1 1</span>
+
)))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/<span style="color:green">NO</span>
+
    --> 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 <span style="color:green">GREEN</span>).
+
 
+
###############################################################################
+
#### 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/<span style="color:green">SO2</span>
+
    --> 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
+
<span style="color:green">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</span>
+
)))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
+
<span style="color:green">2 SO2toSO4        0.031          -      -            - -  1 1</span>
+
+
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 <tt>HEMCO_Config.rc</tt> 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 <span style="color:green">the anthropogenic emissions category (Cat=1)</span>, while the <span style="color:red">biofuel emissions category (Cat=2)</span> 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  <span style="color:green">1</span>/<span style="color:red">2</span> 2
+
 
+
In this example, all NO emissions from CEDS inventory agriculture sector will be placed into the <span style="color:green">the anthropogenic emissions category (Cat=1)</span>, while the <span style="color:red">biofuel emissions category (Cat=2)</span> and <span style="color:red">trash emissions category (Cat=12)</span> 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 <span style="color:green">1</span>/<span style="color:red">2/12</span> 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:
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="200px"|Name
+
!width="150px"|Default value
+
!width="650px"|Description
+
 
+
|-valign="top"
+
|<tt>ROOT</tt>
+
|Set when you create a GEOS-Chem or GCHP run directory
+
|Root folder of the [[Downloading_GEOS-Chem_data_directories|GEOS-Chem shared data directories]].  All met fields and emissions read by HEMCO will be stored in sub-folders of $ROOT.
+
 
+
|-valign="top"
+
|<tt>METDIR</tt>
+
|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 [[Creating GEOS-Chem run directories|create a GEOS-Chem run directory]].  For exmaple, when you create a GEOS-Chem run directory that uses 4x5 GEOS-FP, <tt>METDIR</tt> will automatically be set to <tt>$ROOT/GEOS_4x5/GEOS_FP</tt>, etc.
+
 
+
|-valign="top"
+
|<tt>Logfile</tt>
+
|<tt>HEMCO.log</tt>
+
|Path and name of the output log file. If set to the wildcard character, all HEMCO output is written to standard output.
+
 
+
|-valign="top"
+
|<tt>DiagnPrefix</tt>
+
|<tt>HEMCO_Diagnostics</tt>
+
|Path and prefix of the default HEMCO diagnostics output. All diagnostics will be written to <tt>{DiagnPrefix}_YYYYMMDDHH.nc</tt>. See [[#Diagnostics|the ''Diagnostics'' section]] for more details.
+
 
+
|-valign="top"
+
|<tt>DiagnFreq</tt>
+
|<tt>Daily</tt>
+
|Output frequency of the default HEMCO diagnostics. See [[#Diagnostics|the ''Diagnostics'' section]] for more details.
+
 
+
|-valign="top"
+
|<tt>DiagnTimeStamp</tt>
+
|<tt>End</tt>
+
|Time stamp location of the default HEMCO diagnostics (HEMCO v1.1.012 and higher). Can be set to <tt>Start</tt>, <tt>Mid</tt>, or <tt>End</tt> of the diagnostics window. See [[#Diagnostics|the ''Diagnostics'' section]] for more details.
+
 
+
|-valign="top"
+
|<tt>DiagnFile</tt>
+
|
+
|File containing definitions of the content of the default HEMCO diagnostics. See [[#Diagnostics|the ''Diagnostics'' section]] for more details.
+
 
+
|-valign="top"
+
|<tt>Wildcard</tt>
+
|<tt>*</tt>
+
|Wildcard character symbol.
+
 
+
|-valign="top"
+
|<tt>Separator</tt>
+
|<tt>/</tt>
+
|Separator character symbol.
+
 
+
|-valign="top"
+
|<tt>Unit tolerance</tt>
+
|<tt>0</tt>
+
|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 [[#Units in HEMCO|the ''Units in HEMCO'' section]] for details.
+
 
+
|-valign="top"
+
|<tt>Negative values</tt>
+
|<tt>0</tt>
+
|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).
+
 
+
|-valign="top"
+
|<tt>Verbose</tt>
+
|<tt>3</tt>
+
|Integer value setting the amount of HEMCO information printed to the log file (0 = no verbose; 3 = very verbose).
+
 
+
|-valign="top"
+
|<tt>Warnings</tt>
+
|<tt>3</tt>
+
|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).
+
 
+
|-valign="top"
+
|<tt>Mask fractions</tt>
+
|<tt>false</tt>
+
|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.
+
 
+
|-valign="top"
+
|<tt>PBL dry deposition</tt>
+
|<tt>false</tt>
+
|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.
+
 
+
|-valign="top"
+
|<tt>ROOT</tt>
+
|Must be specified
+
|The root directory. Must be used to specify the root directory of emissions data (see [[#Base emissions|the ''Base emissions'' section]]).
+
 
+
|-valign="top"
+
|<tt>MODEL</tt>
+
|Determined by compiler switch
+
|Can be used to set the <tt>$MODEL</tt> token (see [[#Base emissions|the ''Base emissions'' section]]). If omitted, this value is determined based on compiler switches (e.g. <tt>MET=geosfp</tt>).
+
 
+
|-valign="top"
+
|<tt>RES</tt>
+
|Determined by compiler switch
+
|Can be used to set the <tt>$RES</tt> token (see [[#Base emissions|the ''Base emissions'' section]]). If omitted, this value is determined based on compiler switches (e.g. <tt>GRID=4x5</tt>).
+
 
+
|-valign="top"
+
|<tt>Emission year</tt>
+
|Simulation year
+
|If set, this emission year will be used irrespective of the model simulation year.<br>'''(new in version v1.1.006)'''
+
 
+
|-valign="top"
+
|<tt>Emission month</tt>
+
|Simulation month
+
|If set, this emission month will be used irrespective of the model simulation month.<br>'''(new in version v1.1.006)'''
+
 
+
|-valign="top"
+
|<tt>Emission day</tt>
+
|Simulation day
+
|If set, this emission day will be used irrespective of the model simulation day.<br>'''(new in version v1.1.006)'''
+
 
+
|-valign="top"
+
|<tt>Emission hour</tt>
+
|Simulation hour
+
|If set, this emission hour will be used irrespective of the model simulation hour.<br>'''(new in version v1.1.006)'''
+
 
+
|-valign="top"
+
|<tt>EmisScale_<SpeciesName></tt>
+
|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%.<br>'''(new in version v2.1.001)'''
+
 
+
|}
+
 
+
In standalone mode, the three simulation description files also need be specified (see also [[#Interfaces|the ''Interfaces'' section]]):
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="200px"|Name
+
!width="150px"|Default value
+
!width="650px"|Description
+
 
+
|-valign="top"
+
|<tt>GridFile</tt>
+
|<tt>HEMCO_sa_Grid.rc</tt>
+
|Path and name of the grid description file.
+
 
+
|-valign="top"
+
|<tt>SpecFile</tt>
+
|<tt>HEMCO_sa_Spec.rc</tt>
+
|Path and name of the species description file.
+
 
+
|-valign="top"
+
|<tt>TimeFile</tt>
+
|<tt>HEMCO_sa_Time.rc</tt>
+
|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 <tt>$ENS</tt> (and assign value 3 to it):
+
ENS: 3
+
User-defined tokens can be used the same way as the built-in tokens (<tt>$ROOT</tt>, <tt>$RES</tt>, <tt>$YYYY</tt>, etc.). See [[#Base emissions|<tt>sourceFile</tt> 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 <tt>.</tt>, <tt>_</tt>, <tt>-</tt>, or <tt>x</tt>.
+
 
+
== 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 [[#References|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|''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:
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="150px"|Extension
+
!width="850px"|Description
+
 
+
|-valign="top"
+
|<tt>ExtNr</tt>
+
|Unique extension number.
+
 
+
|-valign="top"
+
|<tt>ExtName</tt>
+
|Extension name.
+
 
+
|-valign="top"
+
|<tt>on/off</tt>
+
|Extension toggle. Extension is only used if this attribute is set to 'on'.
+
 
+
|-valign="top"
+
|<tt>Species</tt>
+
|List of species to be used by this extension. Multiple species are separated by the separator symbol (e.g. <tt>/</tt>). 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|''Getting Started'']] and the definition of [[#Data collections|''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 [[#Extensions|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:
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="150px"|Attribute
+
!width="850px"|Description
+
 
+
|-valign="top"
+
|<tt>ExtNr</tt>
+
|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 [[#Extension switches|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.
+
 
+
|-valign="top"
+
|<tt>Name</tt>
+
|Descriptive field identification name. Two consecutive underscore characters (<tt>__</tt>) 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. <tt>DATA__SECTOR1</tt>, <tt>DATA__SECTOR2</tt>, 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.
+
 
+
|-valign="top"
+
|<tt>sourceFile</tt>
+
|Path and name of the input file. See [[#Input file format|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 [[#HEMCO Settings|the ''HEMCO Settings'' section]]), the token <tt>$ROOT</tt> can be used. Similarly, the token <tt>$CFDIR</tt> 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 <tt>data</tt> of the same directory as the configuration file, the file name can be set to <tt>$CFDIR/data/filename.nc</tt>.
+
 
+
Similarly, the '''date tokens''' <tt>$YYYY</tt>, <tt>$MM</tt>, <tt>$DD</tt>, <tt>$HH</tt>, and <tt>$MN</tt> 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 <tt>SrcTime</tt> specification for this entry (see below). The tokens <tt>$MODEL</tt> and <tt>$RES</tt> 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 [[#User-defined token|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 <tt>SO2toSO4</tt> in [[#Getting Started|''Getting Started'']]). If multiple values are provided (separated by the separator character), they are interpreted as different time slices. In this case, the <tt>sourceTime</tt> 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 <tt>MATH:</tt>, followed by the expression, e.g. 'MATH:2.0+sin(HH/12*PI)'. See [[HEMCO examples|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 [[#Input file format|the ''Input File Format'' section]].
+
 
+
If this entry is '''left empty''' (<tt>-</tt>), the filename from the preceding entry is taken, and the next 5 attributes will be ignored (see entry <tt>MACCITY_SO4</tt> in [[#Getting Started|''Getting Started'']]).
+
 
+
|-valign="top"
+
|<tt>sourceVar</tt>
+
|Source file variable of interest. Leave empty (<tt>-</tt>) if values are directly set through the <tt>sourceFile</tt> attribute or if <tt>sourceFile</tt> is empty.
+
 
+
|-valign="top"
+
|<tt>sourceTime</tt>
+
|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. <tt>2000/1/1/0</tt>) and time ranges for temporally changing fields (e.g. <tt>1980-2007/1-12/1-31/0-23</tt>). 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 <tt>2005/1/1/0</tt>, 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 <tt>2005/1-12/1/0</tt>, 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 <tt>2005/1-12/1-31/0</tt> will make sure that the input data are refreshed daily to the current day's data. Finally, if the time attribute is set to <tt>2005/1-12/1-31/0-23</tt>, 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 <tt>2005-2010/1-12/1/0</tt>, 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 <tt>2005-2020/1-12/1/0</tt>, 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 <tt>$YYYY</tt>, <tt>$MM</tt>, <tt>$DD</tt>, and <tt>$HH</tt>, 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 <tt>WD</tt> (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: <tt>2000/1-12/WD/0</tt>. 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 [[#Input file format|the ''Input File Format'' section]] for more details. Default behavior is to interpret weekly data as 'local time', i.e. token <tt>WD</tt> 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 <tt>UTCWD</tt>.
+
 
+
Similar to the weekday option, there is an option to indicate hourly data that represents local time: <tt>LH</tt>. 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 <tt>2011/1-12/1-31/LH</tt>. 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 <tt>2005-2008/$MM/1/0</tt> and <tt>2005-2008/1-12/1/0</tt>. In the first case, the file will be updated annually, while the update frequency is monthly in the second case. The token <tt>$MM</tt> 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 <tt>$YYYY/$MM/$DD/$HH</tt>, 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 <tt>1990-2007/1/1/0</tt> or <tt>2000/1-12/1/1</tt>, but not <tt>1990-2007/1-12/1/1</tt>.
+
 
+
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 <tt>file_$YYYY$MM.nc</tt> and the source time attribute to <tt>2005-2007/1-12/1/0</tt>, 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 <tt>file_$YYYY</tt>, but the source time attribute should still be <tt>2005-2007/1-12/1/0</tt> to indicate that the field shall be updated monthly.
+
 
+
This attribute can be set to the wildcard character (<tt>*</tt>), 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 <tt>at the beginning</tt> of their time intervals, the time stamp can be shifted by 90 minutes: <tt>2000-2016/1-12/1-31/0-23/'''+90minutes'''</tt>. 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).
+
 
+
|-valign="top"
+
|<tt>CRE</tt>
+
|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:
+
 
+
* '''<tt>C</tt>''' (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 <tt>2000/1-12/1/0 C</tt>, 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).
+
* '''<tt>CS</tt>''' (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#12.1.0|GEOS-Chem 12.1.0]] and higher)'''
+
* '''<tt>CY</tt>''' (cycling, use simulation year): Same as <tt>C</tt>, except don't allow <tt>Emission year</tt> setting to override year value.
+
* '''<tt>CYS</tt>''' (cycling, skip, use simulation year): Same as <tt>CS</tt>, except don't allow <tt>Emission year</tt> setting to override year value.
+
* '''<tt>R</tt>''' (range): Data are only considered as long as the simulation time is within the time range specified in attribute <tt>sourceTime</tt>. 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 <tt>2006-2010/1/1/0 R</tt>, 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 <tt>2000-2002/1-12/1/0 R</tt>, the data will be used for simulation years 2000 to 2002 and ignored for all other years.
+
* '''<tt>RA</tt>''' (range, averaging otherwise): combination of flags <tt>R</tt> and <tt>A</tt>. 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 <tt>2005-2010/1-12/1/0 R</tt> 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 <tt>2005-2010/1-12/1/0 A</tt>, HEMCO will always use the 2005-2010 averaged monthly values, even for simulation years 2005 to 2010. A time attribute of <tt>2005-2010/1-12/1/0 RA</tt> 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)'''
+
* '''<tt>RF</tt>''' (range, forced): same as <tt>R</tt>, but HEMCO stops with an error if the simulation date is outside the provided range. '''(v1.1.011 and higher)'''
+
* '''<tt>RY</tt>''' (range, use simulation year): Same as <tt>R</tt>, except don't allow <tt>Emission year</tt> setting to override year value.
+
* '''<tt>E</tt>''' (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 <tt>2000-2013/1-12/1-31/0 E</tt>, 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.
+
* '''<tt>EF</tt>''' (exact, forced): same as <tt>E</tt>, 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)'''
+
* '''<tt>EC</tt>''' (exact, read/query continuously)
+
* '''<tt>ECF</tt>''' (exact, forced, read/query continuously)
+
* '''<tt>EY</tt>''' (exact, use simulation year): Same as <tt>E</tt>, except don't allow <tt>Emission year</tt> setting to override year value.
+
* '''<tt>A</tt>''' (averaging): tells HEMCO to average the data over the specified range of years. For instance, setting the time attribute to <tt>1990-2010/1-12/1/0 A</tt> 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 <tt>file_$YYYY.nc</tt> '''(only v1.1.014 and higher)'''.
+
* '''<tt>I</tt>''' (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 <tt>2005-2050/1/1/0 I</tt>, 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 <tt>2005-2050/1-12/1/0 I</tt> 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 <tt>2005-2050/1-12/1/0 I</tt>, 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 <tt>file_$YYYY$MM.nc</tt> and source time attribute <tt>2005-2007/1-12/1-31/0 I</tt> 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 <tt>file_$YYYY$MM$DD_$HH00.nc</tt>, and source time to <tt>2000-2015/1-12/1-31/0-23 I</tt> (or whatever the covered year range is).
+
 
+
|-valign="top"
+
|<tt>SrcDim</tt>
+
|Spatial dimension of input data (<tt>xy</tt> for horizontal data; <tt>xyz</tt> for 3-dimensional data).
+
 
+
As of HEMCO v1.1.004, the <tt>SrcDim</tt> 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 <tt>SrcDim</tt> to <tt>xy5</tt>. 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 <tt>SrcDim</tt> to <tt>xy-5</tt>. 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 <tt>SrcDim</tt> attribute can also be used to indicate the level into which 2D data shall be released by setting the vertical coordinate to <tt>LX</tt>, with X being the release level. For instance, to emit a 2D field into level 5, set <tt>srcDim</tt> to <tt>xyL5</tt>.
+
 
+
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: <tt>xyL=2000m</tt>; (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 <tt>xyL=1:5</tt> (emit into levels 1-5) or <tt> xyL=2:5000m</tt> (emit between model level 2 and 5000m); (c) the vertical layer can also be set to the PBL height by using the character string <tt>PBL</tt>. For example, to emit a source uniformly between the surface and the PBL top, use <tt>xyL=1:PBL</tt>.
+
 
+
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 [[HEMCO examples|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 <tt>SrcDim</tt> attribute. For example, to read a file that contains 3D ensemble data (with the individual ensemble runs as additional dimension 'ensemble'), set <tt>srcDim</tt> to <tt>xyz+"ensemble=3"</tt> 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. <tt>xyz+"ensemble=$ENS"</tt>.
+
 
+
Note that arbitrary additional dimensions are currently not supported in a high-performance environment that uses the ESMF/MAPL input/output libraries.
+
 
+
|-valign="top"
+
|<tt>SrcUnit</tt>
+
|Data units. See [[#Units in HEMCO|the ''Units in HEMCO'' section]].
+
 
+
|-valign="top"
+
|<tt>Species</tt>
+
|HEMCO emission species name. Emissions will be added to this species. All HEMCO emission species are defined at the beginning of the simulation (see [[#Interfaces|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.
+
 
+
|-valign="top"
+
|
+
|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.
+
 
+
|-valign="top"
+
|<tt>ScalIDs</tt>
+
|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 <tt>ScalIDs</tt> must correspond to the numbers provided in the [[#Scale factors|''Scale Factors'']] and [[#Masks|''Masks'']] sections.
+
 
+
|-valign="top"
+
|<tt>Cat</tt>
+
|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.
+
 
+
|-valign="top"
+
|<tt>Hier</tt>
+
|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:
+
 
+
#Temporal emission variations including diurnal, seasonal, or interannual variability;
+
#Regional masks that restrict the applicability of the base inventory to a given region; or
+
#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 <tt>ScalID</tt> and <tt>Oper</tt>.  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
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="150px"|Attribute
+
!width="850px"|Description
+
 
+
|-valign="top"
+
|<tt>ScalID</tt>
+
|Scale factor identification number. Used to link the scale factors to the base emissions through the corresponding ScalIDs attribute in the base emissions section.
+
 
+
|-valign="top"
+
|<tt>Name</tt>
+
|See [[#Base emissions|the ''Base emissions'' section]].
+
 
+
|-valign="top"
+
|<tt>sourceFile</tt>
+
|See [[#Base emissions|the ''Base emissions'' section]].
+
 
+
|-valign="top"
+
|<tt>sourceVar</tt>
+
|See [[#Base emissions|the ''Base emissions'' section]].
+
 
+
|-valign="top"
+
|<tt>sourceTime</tt>
+
|See [[#Base emissions|the ''Base emissions'' section]].
+
 
+
|-valign="top"
+
|<tt>CRE</tt>
+
|See [[#Base emissions|the ''Base emissions'' section]].
+
 
+
|-valign="top"
+
|<tt>SrcDim</tt>
+
|See [[#Base emissions|the ''Base emissions'' section]].
+
 
+
|-valign="top"
+
|<tt>SrcUnit</tt>
+
|As described in [[#Base emissions|the ''Base emissions'' section]], with the exception that scale factors are assumed to be unitless (aka <tt>1</tt>) and no automatic unit conversion is performed.
+
 
+
|-valign="top"
+
|<tt>Oper</tt>
+
|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).
+
 
+
|-valign="top"
+
|<tt>MaskID</tt> (optional)
+
|<tt>ScalID</tt> of a mask field. This optional value can be used if a scale factor shall only be used over a given region. The provided <tt>MaskID</tt> 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 CRE 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    <span style="color:red">-129/25/-63/49                                                -</span>        2000/1/1/0 C xy 1        1 -129/25/-63/49
+
+
### END SECTION MASKS ###
+
 
+
The required attributes for mask fields are described below:
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="150px"|Attribute
+
!width="850px"|Description
+
 
+
|-valign="top"
+
|<tt>ScalID</tt>
+
|Mask identification number. See [[#Scale factors|the ''Scale factors'' section]].
+
 
+
|-valign="top"
+
|<tt>Name</tt>
+
|See [[#Base emissions|the ''Base emissions'' section]].
+
 
+
|-valign="top"
+
|<tt>sourceFile</tt>
+
|See [[#Base emissions|the ''Base emissions'' section]].
+
 
+
In HEMCO v1.1.013 (introduced in [[GEOS-Chem v11-01#v11-01e|GEOS-Chem v11-01e]]) and newer versions, the following updates were made:
+
 
+
#Instead of specifying the <tt>sourceFile</tt> and <tt>sourceVar</tt> fields, you can directly provide <span style="color:red">the lower left and upper right box coordinates: '''Lon1/Lat1/Lon2/Lat2'''</span>. 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.
+
#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.
+
 
+
|-valign="top"
+
|<tt>sourceVar</tt>
+
|See [[#Base emissions|the ''Base emissions'' section]].
+
 
+
|-valign="top"
+
|<tt>sourceTime</tt>
+
|See [[#Base emissions|the ''Base emissions'' section]].
+
 
+
|-valign="top"
+
|<tt>CRE</tt>
+
|See [[#Base emissions|the ''Base emissions'' section]].
+
 
+
|-valign="top"
+
|<tt>SrcDim</tt>
+
|See [[#Base emissions|the ''Base emissions'' section]].
+
 
+
|-valign="top"
+
|<tt>SrcUnit</tt>
+
|See [[#Base emissions|the ''Base emissions'' section]].
+
 
+
|-valign="top"
+
|<tt>Oper</tt>
+
|Data operator. As for scale factors, except that value 2 (squared) is not allowed. Instead, <tt>Oper</tt> 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.
+
 
+
|-valign="top"
+
|<tt>Box</tt>
+
|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: <tt>(((CollectionName</tt> and <tt>)))CollectionName</tt>. 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|''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    *
+
    <span style="color:red">--> MACCITY          :      true</span>
+
    <span style="color:green">--> EMEP              :      true</span>
+
    <span style="color:blue">--> AEIC              :      true</span>
+
 
+
END SECTION EXTENSION SWITCHES
+
+
###############################################################################
+
#### BEGIN SECTION BASE EMISSIONS
+
###############################################################################
+
#ExtNr Name srcFile srcVar srcTime CRE Dim Unit Species ScalIDs Cat Hier
+
+
<span style="color:red">(((MACCITY</span>
+
0 MACCITY_CO $ROOT/MACCity.nc CO 1980-2014/1-12/1/0 C xy  kg/m2/s CO 1    1 1
+
<span style="color:red">)))MACCITY</span>
+
+
<span style="color:green">(((EMEP</span>
+
0 EMEP_CO    $ROOT/EMEP.nc    CO 2000-2014/1-12/1/0 C xy  kg/m2/s CO 1/1001 1 2
+
<span style="color:green">)))EMEP'''</span>
+
+
<span style="color:blue">(((AEIC</span>
+
0 AEIC_CO    $ROOT/AEIC.nc    CO 2005/1-12/1/0      C xyz kg/m2/s CO -      2 1
+
<span style="color:blue">)))AEIC</span>
+
+
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, <tt>.not.</tt> 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:
+
 
+
<span style="color:green">(((.not.EMEP</span>
+
0 NOT_EMEP_CO    $ROOT/NOT_EMEP.nc    CO 2000/1-12/1/0 C xy  kg/m2/s CO 1/1001 1 2
+
<span style="color:green">))).not.EMEP</span>
+
 
+
==== Combine collections ====
+
Multiple collections can be combined so that they are evaluated together. This is achieved by linking collection names with <tt>.or.</tt>. For example, to use BOND biomass burning emissions only if both GFED and FINN are not being used:
+
 
+
<span style="color:purple">(((.not.GFED.or.FINN</span>
+
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
+
<span style="color:purple">))).not.GFED.or.FINN</span>
+
 
+
== 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 <tt>srcUnit</tt> 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 <tt>Species</tt> 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 <tt>srcUnit</tt> 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 <tt>srcUnit</tt> 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 emitted MW, species MW, 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 <tt>srcUnit</tt> 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_User's_Guide#HEMCO_settings|the ''HEMCO Settings'' section]]) indicates the tolerance of HEMCO if discrepancies are found between the units found in the input file and attribute <tt>srcUnit</tt> of the HEMCO configuration file. If the unit tolerance is set to 0, HEMCO stops with an error if the <tt>srcUnit</tt> 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 <tt>srcUnit</tt> 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 (carbon), 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 <span style="color:green">kgC/m2/s</span> 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 <span style="color:red">kg/m2/s</span>  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 <span style="color:green">kgC/m2/s</span>, 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 <span style="color:red">kg/m2/s</span>  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 <span style="color:green">kgC/m2/s</span> 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 <span style="color:red">kg/m2/s</span>  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 <span style="color:green">kgC/m2/s</span> 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|''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|''Extension switches'']] of the configuration file, as can the species to be considered.
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="200px"|Description
+
!width="400px"|Supported species
+
!width="350px"|References
+
 
+
|-valign="top"
+
|Biogenic VOCs
+
|ISOP, ACET, PRPE, C2H4, ALD2, CO, OCPI, MONX, MTPA, MTPO, LIMO, SESQ
+
|MEGAN v2.1 ([[#References|Guenther et al., 2014)]]).
+
 
+
|-valign="top"
+
|Air-sea exchange
+
|DMS, ACET, CH3I (more species can be added easily)
+
|[[#References|Johnson (2010), Nightingale et al. (2000)]]
+
 
+
|-valign="top"
+
|Ship emissions
+
|NO, NO2, O3, HNO3
+
|PARANOx ([[#References|Vinken et al., 2011]]).
+
 
+
|-valign="top"
+
|Lightning NOx
+
|NO
+
|[[#References|Murray et al., 2012]].
+
 
+
|-valign="top"
+
|Soil and fertilizer NOx
+
|NO
+
|[[#References|Hudman et al., 2012]].
+
 
+
|-valign="top"
+
|DEAD dust emissions
+
|DST1, DST2, DST3, DST4
+
|[[#References|Zender et al. (2003)]].
+
 
+
|-valign="top"
+
|Ginoux dust emissions
+
|DST1, DST2, DST3, DST4
+
|[[#References|Ginoux et al. (2001)]].
+
 
+
|-valign="top"
+
|Sea salt aerosols
+
|SALA, SALC, Br2
+
|[[#References|Jaegle et al. (2011), Gong (2003)]].
+
 
+
|-valign="top"
+
|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 ([[#References|van der Werf et al. (2010)]].
+
 
+
|-valign="top"
+
|FINN biomass burning
+
|NO, CO, ALK4, ACET, MEK, ALD2, PRPE, C3H8, CH2O, C2H6, SO2, NH3, BCPO, BCPI, OCPO, OCPI, GLYC, HAC
+
|FINN v1 ([[#References|Wiedinmyer et al. (2014)]]).
+
 
+
|-valign="top"
+
|CH4 wetland and rice emissions
+
|CH4 and any kind of tagged CH4 tracers
+
|[[#References|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 the base emissions section 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 the base emissions section 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 ===
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="100px"|Name
+
!width="50px" |Dim
+
!width="150px"|Unit
+
!width="250px"|Description
+
!width="450px"|Used by
+
 
+
|-valign="top"
+
|<tt>U10M</tt>
+
|<tt>xy</tt>
+
|<tt>m/s</tt>
+
|E/W 10m wind speed
+
|Air-sea exchange, dust emissions, PARANOx, sea salt aerosols, soil NO
+
 
+
|-valign="top"
+
|<tt>V10M</tt>
+
|<tt>xy</tt>
+
|<tt>m/s</tt>
+
|N/S 10m wind speed
+
|Air-sea exchange, DEAD dust, Ginoux dust, PARANOx, sea salt aerosols, soil NO
+
 
+
|-valign="top"
+
|<tt>ALBD</tt>
+
|<tt>xy</tt>
+
|<tt>unitless</tt>
+
|Surface albedo
+
|Air-sea exchange, DEAD dust, lightning NOx, sea salt aerosols, soil NO
+
 
+
|-valign="top"
+
|<tt>WLI</tt>
+
|<tt>xy</tt>
+
|<tt>unitless</tt>
+
|0=water, 1=land, 2=ice
+
|CH4 wetlands, DEAD dust, lightning NOx, sea salt aerosols
+
 
+
|-valign="top"
+
|<tt>T2M</tt>
+
|<tt>xy</tt>
+
|<tt>K</tt>
+
|2m surface temperature
+
|DEAD dust, Rn222, MEGAN, PARANOx, soil NO
+
 
+
|-valign="top"
+
|<tt>TSKIN</tt>
+
|<tt>xy</tt>
+
|<tt>K</tt>
+
|Surface skin temperature
+
|Air-sea exchange, CH4 wetlands, sea salt aerosols
+
 
+
|-valign="top"
+
|<tt>GWETROOT</tt>
+
|<tt>xy</tt>
+
|<tt>unitless</tt>
+
|Root soil wetness
+
|MEGAN
+
 
+
|-valign="top"
+
|<tt>GWETTOP</tt>
+
|<tt>xy</tt>
+
|<tt>unitless</tt>
+
|Top soil moisture
+
|CH4 wetlands, DEAD dust, Ginoux dust, soil NO
+
 
+
|-valign="top"
+
|<tt>SNOWHGT</tt>
+
|<tt>xy</tt>
+
|<tt>kg H2O/m2 (mm H2O)</tt>
+
|Snow height
+
|DEAD dust
+
 
+
|-valign="top"
+
|<tt>SNODP</tt>
+
|<tt>xy</tt>
+
|<tt>m</tt>
+
|Snow depth
+
|CH4 wetlands
+
 
+
|-valign="top"
+
|<tt>USTAR</tt>
+
|<tt>xy</tt>
+
|<tt>m/s</tt>
+
|Friction velocity
+
|DEAD dust
+
 
+
|-valign="top"
+
|<tt>Z0</tt>
+
|<tt>xy</tt>
+
|<tt>m</tt>
+
|Surface roughness height
+
|DEAD dust
+
 
+
|-valign="top"
+
|<tt>TROPP</tt>
+
|<tt>xy</tt>
+
|<tt>Pa</tt>
+
|Tropopause pressure
+
|Rn222, lightning NO
+
 
+
|-valign="top"
+
|<tt>SZAFACT</tt>
+
|<tt>xy</tt>
+
|<tt>unitless</tt>
+
|Current SZA / daily total SZA
+
|MEGAN
+
 
+
|-valign="top"
+
|<tt>PARDR</tt>
+
|<tt>xy</tt>
+
|<tt>W/m2</tt>
+
|Direct photosynthetic active radiation
+
|MEGAN
+
 
+
|-valign="top"
+
|<tt>PARDF</tt>
+
|<tt>xy</tt>
+
|<tt>W/m2</tt>
+
|Diffuse photosynthetic active radiation
+
|MEGAN
+
 
+
|-valign="top"
+
|<tt>RADSWG</tt>
+
|<tt>xy</tt>
+
|<tt>W/m2</tt>
+
|Short-wave surface radiation
+
|Soil NO
+
 
+
|-valign="top"
+
|<tt>FRCLND</tt>
+
|<tt>xy</tt>
+
|<tt>unitless</tt>
+
|Olson land fraction
+
|Air-sea exchange, Rn222
+
 
+
|-valign="top"
+
|<tt>FRLAND</tt>
+
|<tt>xy</tt>
+
|<tt>unitless</tt>
+
|Land fraction
+
|CH4 wetlands
+
 
+
|-valign="top"
+
|<tt>FROCEAN</tt>
+
|<tt>xy</tt>
+
|<tt>unitless</tt>
+
|Ocean fraction
+
|CH4 wetlands
+
 
+
|-valign="top"
+
|<tt>FRLAKE</tt>
+
|<tt>xy</tt>
+
|<tt>unitless</tt>
+
|Lake fraction
+
|CH4 wetlands
+
 
+
|-valign="top"
+
|<tt>FRLANDIC</tt>
+
|<tt>xy</tt>
+
|<tt>unitless</tt>
+
|Land ice fraction
+
|CH4 wetlands
+
 
+
|-valign="top"
+
|<tt>CLDFRC</tt>
+
|<tt>xy</tt>
+
|<tt>unitless</tt>
+
|Cloud fraction
+
|Soil NO
+
 
+
|-valign="top"
+
|<tt>JNO2</tt>
+
|<tt>xy</tt>
+
|<tt>1/s</tt>
+
|J-value for NO2
+
|PARANOx
+
 
+
|-valign="top"
+
|<tt>JO1D</tt>
+
|<tt>xy</tt>
+
|<tt>1/s</tt>
+
|J-value for O1D
+
|PARANOx
+
 
+
|-valign="top"
+
|<tt>LAI</tt>
+
|<tt>xy</tt>
+
|<tt>cm2/cm2</tt>
+
|Daily leaf area index
+
|MEGAN, soil NO
+
 
+
|-valign="top"
+
|<tt>CNV_MFC</tt>
+
|<tt>xyz</tt>
+
|<tt>kg/m2/s</tt>
+
|Convective mass flux
+
|Lightning NO
+
 
+
|-valign="top"
+
|<tt>FRAC_OF_PBL</tt>
+
|<tt>xyz</tt>
+
|<tt>unitless</tt>
+
|Fraction of grid box in PBL
+
|Air-sea exchange, ParaNOx, POPs (Only needed if dry deposition occurs over entire PBL)
+
 
+
|-valign="top"
+
|<tt>SPHU</tt>
+
|<tt>xyz</tt>
+
|<tt>kg H2O/kg air</tt>
+
|Specific humidity
+
|DEAD dust, ParaNOx
+
 
+
|-valign="top"
+
|<tt>TK</tt>
+
|<tt>xyz</tt>
+
|<tt>K</tt>
+
|Air temperature
+
|DEAD dust, lightning NOx, POPs
+
 
+
|-valign="top"
+
|<tt>AIR</tt>
+
|<tt>xyz</tt>
+
|<tt>kg</tt>
+
|Air mass
+
|Rn222, PARANOx
+
 
+
|-valign="top"
+
|<tt>AIRVOL</tt>
+
|<tt>xyz</tt>
+
|<tt>m3</tt>
+
|Air volume
+
|PARANOx, POPs
+
 
+
|-valign="top"
+
|<tt>O3</tt>
+
|<tt>xyz</tt>
+
|<tt>kg</tt>
+
|O3 mass
+
|PARANOx
+
 
+
|-valign="top"
+
|<tt>NO</tt>
+
|<tt>xyz</tt>
+
|<tt>kg</tt>
+
|NO mass
+
|PARANOx
+
 
+
|-valign="top"
+
|<tt>NO2</tt>
+
|<tt>xyz</tt>
+
|<tt>kg</tt>
+
|NO2 mass
+
|PARANOx
+
 
+
|-valign="top"
+
|<tt>HNO3</tt>
+
|<tt>xyz</tt>
+
|<tt>kg</tt>
+
|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 (<tt>HEMCO_restart.YYYYMMDDhhmmss.nc</tt>) 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 <tt>E</tt> to ensure that only data is read that exactly matches the simulation start date (also see [[#Base emissions|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|''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 <span style="color:green">GREEN</span>):
+
 
+
111    GFED              : on    CO/NO/ACET/ALK4
+
    --> GFED3            :      false
+
    --> GFED4            :      true
+
    --> GFED_daily        :      false
+
    --> GFED_3hourly      :      false
+
    <span style="color:green">--> Scaling_CO        :      1.05
+
    --> Scaling_NO        :      1.20</span>
+
 
+
Similarly, a spatiotemporal field to be applied to the species of interest can be defined via setting <span style="color:red"><tt>ScaleField_<SpecName></tt></span>, 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
+
    <span style="color:red">--> ScaleField_NO    :      GFED_SCALEFIELD_NO</span>
+
 
+
The corresponding scale field needs be defined in section [[#Base emissions|''Base emissions'']]. A simple example would be a monthly varying scale factor for GFED NO emissions:
+
 
+
<span style="color:red">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</span>
+
 
+
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 [[HEMCO examples|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 [[#Diagnostics|the ''Diagnostics'' section]]). See our [[HEMCO_standalone|''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|''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: <tt>mean</tt> (arithmetic mean), <tt>instantaneous</tt> (always use the instantaneous value), <tt>sum</tt> (total sum over the output interval), <tt>cumulsum</tt> (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 <tt>DiagnFreq</tt> in the settings section of the HEMCO configuration file. The name of the corresponding diagnostics files can be specified via the <tt>DiagnPrefix</tt> 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 <tt>HEMCO_Diagnostics.200808010000.nc</tt>. The datetime can denote the beginning, middle, or end (default) of the time interval, as specified by setting <tt>DiagnTimeStamp</tt> (see below).
+
 
+
===== Diagnostics output frequency (setting DiagnFreq) =====
+
Setting <tt>DiagnFreq</tt> of the HEMCO configuration file determines the output frequency of the default HEMCO diagnostics. It can be set to one of the following values: <tt>Always</tt>, <tt>Hourly</tt>, <tt>Daily</tt>, <tt>Monthly</tt>, <tt>Annually</tt>, <tt>End</tt>.
+
 
+
As of version 1.1.009, more advanced output intervals can be provided as an 15 digit integer string of format <tt>YYYYMMDD HHMMSS</tt> denoting the year-month-day and hour-minute-second output frequency, respectively. For example, to write out the diagnostics every day <tt>DiagnFreq</tt> can be set to <tt>00000001 000000</tt>. Similarly, to write out the diagnostics every 2 hours <tt>DiagnFreq</tt> can be set to <tt>00000000 020000</tt>.
+
 
+
===== 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 <tt>HEMCO_Diagnostics.200808010100.nc</tt> 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 <tt>DiagnTimeStamp</tt>. By setting <tt>DiagnTimeStamp</tt> to <tt>Start</tt>, 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 <tt>HEMCO_Diagnostics.200808010000.nc</tt>. Similarly, setting <tt>DiagnTimeStamp</tt> to <tt>Mid</tt> will use the mid-point of the diagnostics window, e.g. the aforementioned diagnostics would be written as <tt>HEMCO_Diagnostics.200808010030.nc</tt>. The default setting for <tt>DiagnTimeStamp</tt> is <tt>End</tt>.
+
 
+
===== 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 <tt>DiagnRefTime</tt>. 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 <tt>DiagnNoLevDim</tt>. 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 <tt>DiagnFile</tt>. Each line of the diagnostics definition file represents a diagnostics container. It expects the following 7 entries (all on the same line):
+
 
+
#Container name (character)
+
#HEMCO species (character)
+
#Extension number (integer)
+
#Emission category (integer)
+
#Emission hierarchy (integer)
+
#Space dimension (2 or 3)
+
#Output unit (character)
+
#OPTIONAL: Long name of diagnostic, for the netCDF <tt>long_name</tt> 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 <tt>HEMCO.log</tt> 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 (<tt>-1</tt>), 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 <tt>End</tt>, 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 <tt>PARANOX_O3_DEPOSITION_FLUX</tt> and <tt>PARANOX_HNO3_DEPOSITION_FLUX</tt>, 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 <tt>hco_diagn_mod.F90</tt> (found in <tt>HEMCO/Core/</tt>) provides a suite of routines to define, fill, obtain, etc. diagnostic fields. Similarly, <tt>hco_restart_mod.F90</tt> (also found in <tt>HEMCO/Core/</tt>) 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 (<tt>/</tt>) - 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. <tt>COUNTRY_MASK</tt>) 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 <tt>CountryValues</tt> 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:
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="150px"|Attribute
+
!width="850px"|Description
+
 
+
|-valign="top"
+
|<tt>Latitude and Longitude dimension</tt>
+
|The longitude and latitude variables must be given in the netCDF file as variables <tt>lon</tt> and <tt>lat</tt>, respectively. As of version 1.1.011, variables <tt>longitude</tt>, <tt>Longitude</tt>, <tt>latitude</tt>, and <tt>Latitude</tt> are also supported. The variable name must be identical to the corresponding dimension name, e.g. if the longitude variable name is <tt>Longitude</tt> the longitude dimension must also be named <tt>Longitude</tt>.
+
 
+
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|''Behind the scenes of HEMCO'']] for more details).
+
 
+
|-valign="top"
+
|<tt>Vertical dimension</tt>
+
|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 [[#Vertical regridding|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 <tt>level</tt> variable must contain the attributes <tt>standard_name</tt> and <tt>formula_terms</tt> (the attribute <tt>positive</tt> 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.
+
 
+
|-valign="top"
+
|<tt>Time</tt>
+
|Times should be given as relative times, e.g. relative to a specified reference date. Accepted are <tt>days since yyyy-mm-dd</tt>, <tt>hours since yyyy-mm-dd hh:mm:ss</tt>, and <tt>minutes since yyyy-mm-dd hh:mm:ss</tt>. 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.
+
 
+
|-valign="top"
+
|<tt>Data units</tt>
+
|It is recommended to store data in one of the HEMCO standard units: <tt>kg/m2/s</tt> and <tt>kg(C)/m2/s</tt> for fluxes; <tt>kg/m3</tt> and <tt>kg(C)/m3</tt> for concentrations; <tt>1</tt> for unitless data; and <tt>count</tt> 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 <tt>srcUnit</tt> attribute (see [[#Base emissions|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 [[#Interfaces 2|the ''HEMCO-model Interface'' section]]). More details on unit conversion are given in module <tt>hco_unit_mod.F90</tt> (found in <tt>HEMCO/Core/</tt>).
+
 
+
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 [[Preparing data files for use with HEMCO|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 <tt>SrcDim</tt> file attribute (see [[#Base emissions|<tt>srcDim</tt> 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 <tt>srcDim</tt> attribute in the HEMCO configuration file accordingly (e.g. <tt>xy-72</tt> 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 <tt>include</tt> statement to the master HEMCO configuration file (HEMCO_Config.rc), e.g.:
+
 
+
>>>include HEMCO_Config_nested.rc
+
 
+
The emission information contained in <tt>HEMCO_Config_nested.rc</tt> will then be used along with the emission configuration specified in <tt>HEMCO_Config.rc</tt>. 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 (<tt>hcoio_dataread_mod.F90</tt> found in <tt>HEMCO/Core/</tt>). 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 <tt>FileData</tt> derived type object (defined in <tt>hco_filedata_mod.F90</tt>). 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 <tt>hco_arr_mod.F90</tt>.
+
 
+
Data containers (and as such, emissions data) are accessed through three different linked lists: <tt>ConfigList</tt>, <tt>ReadList</tt>, <tt>EmisList</tt>. 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, <tt>ReadList</tt> 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, <tt>EmisList</tt> sorts the data containers by model species, emission category and hierarchy. This allows an efficient emission calculation since the <tt>EmisList</tt> has to be scanned only once. List containers and generic linked list routines are defined in <tt>hco_datacont_mod.F90</tt>. Specific routines for <tt>ConfigList</tt>, <tt>ReadList</tt> and <tt>EmisList</tt> are defined in <tt>hco_config_mod.F90</tt>, <tt>hco_readlist_mod.F90</tt>, and <tt>hco_emislist_mod.F90</tt>, 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 <tt>hco_driver_mod.F90</tt>: <tt>HCO_INIT</tt>, <tt>HCO_RUN</tt>, <tt>HCO_FINAL</tt>). These are also the routines that are called at the interface level (see [[#Interfaces 2|the ''HEMCO-model interface'' section]]). Each HEMCO simulation is defined by its state object <tt>HcoState</tt>, 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 <tt>hco_state_mod.F90</tt>. <tt>HcoState</tt> is defined at the interface level and then passed down to all HEMCO routines (see also [[#Interfaces 2|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:
+
 
+
# Read the HEMCO configuration file (subroutine <tt>Config_ReadFile</tt> in <tt>hco_config_mod.F90</tt>). 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.
+
# Initialize <tt>HcoState</tt>.
+
# Call <tt>HCO_INIT</tt>, passing <tt>HcoState</tt> to it. This initializes the HEMCO clock object (see <tt>hco_clock_mod.F90</tt>) and creates the <tt>ReadList</tt> (<tt>hco_readlist_mod.F90</tt>). The <tt>ReadList</tt> links to the data containers in <tt>ConfigList</tt>, 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 <tt>EmisList</tt> linked list is only created in the run call.
+
 
+
Note that steps 1 and 2 occur at the interface level (see [[#Interfaces 2|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 <tt>HcoClock_Set</tt> in <tt>hco_clock_mod.F90</tt>). <tt>HCO_RUN</tt> performs the following steps:
+
 
+
# 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 <tt>hco_tidx_mod.F90</tt> organizes how to properly access these fields.
+
# Read/update the content of the data containers (<tt>ReadList_Read</tt>). 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 [[#Interfaces 2|the ''HEMCO-model interface'' section]]).
+
# Creates/updates the <tt>EmisList</tt> object. Similar to <tt>ReadList</tt>, <tt>EmisList</tt> points to the data containers in <tt>ConfigList</tt>, but sorted according to species, emission hierarchy, emissions category. To optimize emission calculations, <tt>EmisList</tt> already combines base emission fields that share the same species, category, hierarchy, scale factors, and field name (without the field name tag, see [[#Base emissions|the ''Base emissions'' section]]).
+
# Calculate core emissions for the current simulation time. This is performed by subroutine <tt>hco_calcemis</tt>  in <tt>hco_calc_mod.F90</tt>. This routine walks through <tt>EmisList</tt> 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 <tt>ScalIDs</tt>. A container ID index list is used to efficiently retrieve a pointer to each of those containers (see <tt>cIDList</tt> in <tt>hco_datacont_mod.F90</tt>).
+
 
+
==== 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 <tt>HCO_Emis_Add</tt> in <tt>HCO_FluxArr_mod.F90</tt>.
+
 
+
Meteorological input data is passed to the individual extension routines through the extension state object <tt>ExtState</tt>, which provides a pointer slot for all met fields used by any of the extension (see <tt>hcox_state_mod.F90</tt>). These pointers must be assigned at the interface level (see [[#Interfaces 2|the ''HEMCO-model interface'' section]]).
+
 
+
In analogy to the core module, the three main routines for the extensions are (in <tt>hcox_driver_mod.F90</tt>):
+
 
+
* 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 [[#Extension Switches|the ''Extension Switches'' section]]) are automatically read by HEMCO. For any given extension, routines <tt>GetExtNr</tt> and <tt>GetExtOpt</tt> can be used to obtain the extension number and desired setting value, respectively (see <tt>HCO_ExtList_Mod.F90</tt>). Routine <tt>HCO_GetExtHcoID</tt> 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 <tt>EmisList</tt>, but ignored by the HEMCO core module during emissions calculation. Pointers to these data arrays can be obtained through routine <tt>EmisList_GetDataArr</tt> in <tt>HCO_EmisList_Mod.F90</tt>. 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 (<tt>hcoi_standalone_mod.F90</tt>). The HEMCO-GEOS-Chem model interface is included in the GEOS-Chem source code (<tt>hcoi_gc_main_mod.F90</tt> in <tt>GeosCore</tt>). 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 (<tt>Config_ReadFile</tt> in <tt>hco_config_mod.F90</tt>).
+
* Initialize HcoState object (<tt>HcoState_Init</tt> in <tt>hco_state_mod.F90</tt>).
+
* Define the emission grid. Grid definitions are stored in <tt>HcoState%Grid</tt>. 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 <tt>HcoState%Spc(:)</tt> (one entry per species). For each species, the following parameter are required:
+
*# HEMCO species ID: unique integer index for species identification. For internal use only.
+
*# Model species ID: the integer index assigned to this species by the employed model.
+
*# Species name
+
*# Species molecular weight in g/mol.
+
*# 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).
+
*# Molecular ratio: molecules of emitted species per molecules of species. For example, if C3H8 is emitted as kg C, the molecular ratio becomes 3.
+
*# K0: Liquid over gas Henry constant in M/atm.
+
*# CR: Temperature dependency of K0 in K.
+
*# 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 (<tt>HCO_Init</tt> in <tt>hco_driver_mod.F90</tt>)
+
* Initialize HEMCO extensions (<tt>HCOX_Init</tt> in <tt>hcox_driver_mod.F90</tt>)
+
 
+
Run:
+
 
+
* Set current time (<tt>HcoClock_Set</tt> in <tt>hco_clock_mod.F90</tt>)
+
* Reset all emission and deposition values (<tt>HCO_FluxArrReset</tt> in <tt>hco_fluxarr_mod.F90</tt>)
+
* Run HEMCO core to calculate emissions (<tt>HCO_Run</tt> in <tt>hco_driver_mod.F90</tt>)
+
* Link the used meteorology field objects of <tt>ExtState</tt> to desired data arrays (this step may also be done during initialization)
+
* Run HEMCO extensions to add extensions emissions (<tt>HCOX_Run</tt> in <tt>hcox_driver_mod.F90</tt>)
+
* Export HEMCO emissions into desired environment
+
 
+
Finalization:
+
 
+
* Finalize HEMCO extensions and extension state object <tt>ExtState</tt> (<tt>HCOX_Final</tt> in <tt>hcox_driver_mod.F90</tt>).
+
* Finalize HEMCO core (<tt>HCO_Final</tt> in <tt>hco_driver_mod.F90</tt>).
+
* Clean up HEMCO state object <tt>HcoState</tt> (<tt>HcoState_Final</tt> in <tt>hco_state_mod.F90</tt>).
+
 
+
==== Data interface (reading and regridding) ====
+
 
+
The data interface (<tt>hcoi_dataread_mod.F90</tt>) organizes reading, unit conversion, and remapping of data from source files. Its public routine <tt>HCOI_DataRead</tt> is only called by subroutine <tt>ReadList_Fill</tt> in <tt>hco_readlist_mod.F90</tt>.
+
Data processing is performed in three steps:
+
 
+
# Read data from file using the source file information (file name, source variable, desired time stamp) provided in the configuration file.
+
# Convert unit to HEMCO units based on the unit attribute read from disk and the <tt>srcUnit</tt> attribute set in the configuration file. See [[#Input file format|the ''Input file format'' section]] for more information.
+
# 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 [[#References|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 <tt>HCO_State</tt> derived type object (defined in Core/hco_state_mod.F90). Similarly, all emission extension information is included in an <tt>Ext_State</tt> 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.:
+
 
+
  <tt>CALL HCO_Run( am_I_Root, HcoState, Phase, RC )</tt>
+
  ...
+
  <tt>CALL HCOX_Run( am_I_Root, HcoState, ExtState, RC )</tt>
+
 
+
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.:
+
 
+
  <tt>CALL HCO_Run( am_I_Root, HcoStateA, Phase, RC )</tt>
+
  <tt>CALL HCO_Run( am_I_Root, HcoStateB, Phase, RC )</tt>
+
  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 <tt>hco_interface_mod.F90</tt> (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 ==
+
#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'', <u>J. Geophys. Res.</u>, '''106''', D17, 20'255-20'273, 2001.
+
#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)'', <u>J. Geophys. Res, Biogeosciences.</u>, '''118''', Issue 1, 317-328, March 2013. [http://onlinelibrary.wiley.com/doi/10.1002/jgrg.20042/abstract (Article)]
+
#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.
+
#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.
+
#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.
+
#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.
+
#Joeckel P: , Technical note: Recursive rediscretisation of geo-scientific data in the Modular Earth Submodel System (MESSy), Atmos. Chem. Phys., 6, 3557–3562, 2006.
+
#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.
+
#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.
+
#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. [http://www.geosci-model-dev.net/7/1409/2014/gmd-7-1409-2014.html (Article)]
+
#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.
+
#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.
+
#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.
+
#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.
+
#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.
+
#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.
+
#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.
+
#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.
+
#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.
+
#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.
+
 
+
--[[User:Bmy|Bob Y.]] 14:55, 30 March 2015 (EDT)
+
 
+
== More examples ==
+
 
+
Please see [[HEMCO examples|our ''HEMCO examples'' wiki page]] for more examples about using HEMCO.
+
 
+
== Changelog ==
+
 
+
The HEMCO version number is defined in module <tt>hco_error_mod.F90</tt>. It is printed into the HEMCO log-file at the beginning of a simulation.
+
 
+
We have now moved the HEMCO version history to [[HEMCO versions|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:
+
 
+
#[[HEMCO versions#Known issues|Currently unresolved issues]]
+
#[[HEMCO_versions#Previous_issues_that_are_now_resolved|HEMCO issues that have now been resolved]]
+

Latest revision as of 20:21, 4 August 2022

This content has been migrated to hemco.readthedocs.io.