Input file format

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

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

  2. Scalar data directly specified in the HEMCO configuration file. Scalar values can be set in the HEMCO configuration file directly. If multiple values - separated by the separator sign (/) - are provided, they are interpreted as temporally changing values: 7 values = Sun, Mon, …, Sat; 12 values = Jan, Feb, …, Dec; 24 values = 12am, 1am, …, 11pm (local time!). Mask box boundaries can also be provided directly in the HEMCO configuration file. The entry must have exactly four values, interpreted as lower left and upper right mask box corners (lon1/lat1/lon2/lat2).

  3. Country-specific data specified in a separate ASCII file. This file must end with the suffix ‘.txt’. The first line must be the container name of a netCDF country mask file (e.g. COUNTRY_MASK). The rest of the file must contain the country-specific values listed by country name and ID. The IDs must correspond to the IDs of the netCDF mask file specified in the first line and must be integers. ID 0 is reserved for the default values that are applied to all countries with no specific values listed. The CountryValues are interpreted the same way as scalar values, except that they are applied to all grid boxes with the given country ID. Below are examples of file specifications and a country-specific data file. Note that in an ESMF environment you must use absolute path for the scale factors ASCII file rather than use $ROOT, and include the country mask but not the ASCII file in ExtData.rc.

#==============================================================================
# --- Country mask file ---
#==============================================================================
* COUNTRY_MASK $ROOT/MASKS/v2014-07/countrymask_0.1x0.1.nc CountryID 2000/1/1/0 C xy count * - 1 1

#==============================================================================
# --- Country scale factors ---
#==============================================================================
* COUNTRY_SCALE_FACTORS $ROOT/MASKS/country_scale_factors.txt - - - xy count 1
# 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

COARDS compatibility

Gridded input files are expected to be in the Network Common Data Form (netCDF) format and must adhere to the COARDS metadata conventions

For an in-depth description of the COARDS netCDF conventions, please see the Supplemental Guide entitled Prepare COARDS-compliant netCDF files. Also be aware of some additional considerations for the time and vertical level dimensions.

Units of data variables

It is recommended to store data in one of the HEMCO standard units:

  • kg/m2/s for fluxes;

  • kg/m3 for concentrations;

  • 1 for unitless data;

  • count for index-based data, i.e. discrete distributions (for instance, land types represented as integer values).

HEMCO will attempt to convert all data to one of those units, unless otherwise via the SrcUnit attribute (see the Base Emissions) section.

Mass conversion (e.g. from molecules to kg) is performed based on the properties (e.g. molecular weight) of the species assigned to the given data set. It is also possible to convert between species-based and molecule-based units (e.g. kg vs. kg(C)). This conversion is based on the emitted molecular weight and the molecular ratio of the given species (see the HEMCO-model Interface) section. More details on unit conversion are given in module src/Core/hco_unit_mod.F90.

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

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

Arbitrary additional netCDF dimension

HEMCO can read netCDF files with an additional, arbitrary dimension. The dimension name and dimension index to be read must be given explicitly in the HEMCO configuration file as part of the SrcDim file attribute). This feature is currently not available in an ESMF environment.

Regridding

Vertical regridding

HEMCO is able to perform some limited vertical interpolation.

Warning

HEMCO assumes that the input data is on the same grid as the model grid if it has the same number (nz) of, or plus one (nz+1) vertical levels than the model. In the case of the same number of vertical levels, HEMCO assumes that the input data is already on the model grid and no interpolation is performed. In the case of input data having nz+1 levels, the data is interpreted as being on grid edges instead of grid midpoints.

Collapsing into various GEOS grids. Additional vertical regridding options are available for the various GEOS grids (e.g. to regrid native GEOS-5 levels to reduced GEOS-5 levels, or to remap GEOS-5 data onto the vertical GEOS-4 grid). These options are only available if the corresponding compiler flags are set (this is the default case for GEOS-Chem users).

Conservative vertical interpolation using MESSy. If input data is specified with vertical coordinates in lev attribute of the netCDF file with units atmosphere_hybrid_sigma_pressure_coordinate, HEMCO can perform vertical interpolation using MESSy to the model grid.

Regridding GEOS-Chem 3-D input data in other models. In other models where HEMCO is used for emissions, but do not necessarily use the GEOS vertical grids (e.g., WRF-GC, GEOS-Chem within CESM, CAM-chem with HEMCO), input data from GEOS-Chem files which have 72 levels will automatically be regridded to the model levels, for compatibility.

By default, HEMCO assumes that the vertical coordinate direction is upwards, i.e. the first level index corresponds to the surface layer. The vertical axis can be reversed by setting the srcDim attribute in the HEMCO configuration file accordingly (e.g. xy-72 if the input data has 72 levels on a reversed vertical axis).

Horizontal regridding

In a non-ESMF environment, HEMCO can only regrid between rectilinear grids (e.g. lat-lon).

Nested HEMCO configuration files

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

>>>include HEMCO_Config_nested.rc

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

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