HEMCO standalone

From Geos-chem
Jump to: navigation, search

On this page we describe how to set up and run HEMCO as a stand-alone model.

Overview

HEMCO can be employed as stand-alone model, in which case all simulation information is read from separate input files through the stand-alone interface. The calculated emissions are written to netCDF file via the HEMCO diagnostics, as specified through the diagnostics definition file (see the Diagnostics section of the HEMCO User's Guide).

For HEMCO standalone applications, all extensions input data has to be provided through input files, e.g. all required environmental data (wind speed, radiation, etc.) must be read from disk. These input files should be listed in the base emissions section of the configuration file, as described below and in the Extensions section of the HEMCO User's Guide.

The HEMCO standalone executable can be generated from the HEMCO standalone source code, as described below. For GEOS-Chem users, hemco_standalone.x is automatically generated upon compilation of the GEOS-Chem model and can be found in the bin/ directory along with the GEOS-Chem executable, geos.

Download HEMCO source code

See our HEMCO installation guide for complete instructions on downloading and installing the HEMCO source code or use the quick links below. If you have already set up the Unix environment variables for GEOS-Chem, then you should be able to skip to step 3.

  1. Check for and/or install the netCDF libraries
  2. Set environment variables for HEMCO
  3. Download and build the HEMCO standalone
  4. Set additional environment variables for HEMCO

Obtain HEMCO standalone run directory

For GEOS-Chem v11-02c and later, you can create a HEMCO standalone run directory using the GEOS-Chem Unit Tester by following these instructions. To copy the hemco_standalone run directory, make sure you have the following lines in your CopyRunDirs.input file:

#--------|-----------|------|-----------------|------------|------------|---------|
# MET    | GRID      | NEST | SIMULATION      | START DATE | END DATE   | EXTRA?  |
#--------|-----------|------|-----------------|------------|------------|---------|
  geosfp   4x5         -      hemco_standalone  2013070100   2013080100   -

Then run:

./gcCopyRunDirs CopyRunDirs.input

In the HEMCO standalone run directory, you will see the following files

File Description
HEMCO_Config.rc The "original" HEMCO configuration file as used by GEOS-Chem
HEMCO_sa_Config.rc The "master" HEMCO configuration file for the HEMCO standalone model. This file defines all information specific to the HEMCO standalone code, such as grid information file, species definitions, and met fields needed by emission extensions. The rest of the emissions settings are taken from the standard HEMCO_Config.rc by linking down to it using:
>>>include HEMCO_Config.rc

Note that the entries in the master HEMCO configuration file take precedence over the ones in the linked configuration files. Thus, if the same setting or option is defined in both HEMCO_sa_Config.rc and HEMCO_Config.rc, HEMCO will use the one from HEMCO_sa_Config.rc.

NOTE: In the sample HEMCO_sa_Confic.rc shipped with the HEMCO standalone run directory, PARANOx, soil NOx, and MEGAN SOA are turned off because they require some fields that are closely linked to GEOS-Chem (NOx concentrations, N deposition, etc.).

HEMCO_sa_Grid.4x5.rc File containing the grid definition of the HEMCO standalone model. See this section for more details.
HEMCO_sa_Spec.rc File containing the species definitions for the HEMCO standalone model. See this section for more details.
HEMCO_sa_Time.rc File containing the time and emissions time step for the HEMCO standalone model. See this section for more details.
HEMCO_sa_Diagn.rc Diagnostics input file for HEMCO. See this post for more details.

Grid definition

The grid definition for the HEMCO standalone version needs be provided in a grid definition file. The location and name of the grid definition file must be given in section settings of the HEMCO configuration file:

GridFile:                    HEMCO_sa_Grid.rc

The grid definition file must contain the longitude and latitude range (deg E and deg N, respectively), as well as the number of grid boxes in longitude, latitude, and vertical direction. Based on these information, HEMCO will define a horizontally equally spaced grid.

# XMIN, XMAX: longitude range (edges)
# YMIN, YMAX: latitude range (edges)
XMIN: -180
XMAX:  180
YMIN: -90
YMAX:  90

# NX = number of longitude grid boxes
# NY = number of latitude  grid boxes
# NZ = number of levels
NX: 360
NY: 180
NZ: 33

The latitude values must fall within the range of -90.0 to 90.0 deg N. The lower longitude bound may be less than -180.0 deg E, e.g. for dateline centered grids.

As of version 1.1.007, the longitude and/or latitude grid edges can be explicitly given in the HEMCO grid definition file as optional arguments XEDGE and YEDGE, respectively. All grid edge values must be provided (all on the same line, separated by whitespace only). For instance, the following entry would define the full GMAO 4x5 grid (dateline centered, half-sized polar boxes):

XMIN: -182.5
XMAX:  177.5
YMIN: -90.0
YMAX:  90.0
NX: 72
NY: 47
NZ: 47
YEDGE: -90.0 -88.0 -84.0 -80.0 -76.0 -72.0 -68.0 -64.0 -60.0 -56.0 -52.0 -48.0 -44.0 -40.0 -36.0 -32.0 -28.0 -24.0 
-20.0 -16.0 -12.0 -8.0 -4.0 0.0 4.0 8.0 12.0 16.0 20.0 24.0 28.0 32.0 36.0 40.0 44.0 48.0 52.0 56.0 60.0 64.0 68.0 
72.0 74.0 78.0 82.0 86.0 88.0 90.0

The number of longitude and latitude grid edges must be consistent with attributes NX and NY, respectively.

As of v1.1.009, it is also possible to provide explicit grid midpoints (XMID and/or YMID). These can be provided in addition to the edges or instead of it. If both the mid points and the edges are provided these values are taken without doing any further tests, e.g. it is assumed that these values are consistent with each other. If only the midpoints are provided, the grid edge is calculated from these points (assuming that the edges lie in the middle of adjacent midpoints. Likewise, if only the edges are provided the midpoints are assumed to be in the middle of neighboring grid edges.

Enhanced vertical grid options are available as of v1.1.010. In particular, the Ap and Bp values of a hybrid sigma-pressure coordinate system can be provided in analogy to XEDGE, YEDGE, etc. These entries must be denoted AP and BP respectively. Ap values are expected to be in units of Pa while Bp values are unitless. If no Ap and Bp values are given, HEMCO will assume that the vertical levels are on the GEOS vertical grid (if the number of vertical levels is less than the GEOS levels, only a subset of the GEOS Ap/Bp values will be used). The internal usage of Ap and Bp coordinates allows HEMCO to calculate physical quantities such as pressure edges if those are not provided through the HEMCO configuration file (see A note on vertical grid quantities below).

Species definition

Species definitions are provided in the species input file. The location and name of the species definition file must be given in section settings of the HEMCO configuration file:

SpecFile:                    HEMCO_sa_Spec.rc

Emissions will only be calculated for the species listed in the species file. For every species, the name, species molecular weight (g/mol), emitted species molecular weight (g/mol), molecular ration (molecules emitted species per molecule of species, unitless), Henry coefficient (liquid over gas, M/atm], temperature dependency of the Henry coefficient (-d ln(kH) / d(1/T)), and the pKa value. The latter three entries are only of importance for the air-sea exchange module (and thus for species with air-sea fluxes):

# List species below
# ID NAME MW EMISMW MOLECRATIO K0 CR PKA
1  NO    30.0  30.0 1.0 0.0 0.0 0.0
2  ISOP  68.1  12.0 5.0 0.0 0.0 0.0

Time settings

Simulation time and emission time step is provided in the time configuration file. The location and name of the time configuration file must be given in section settings of the HEMCO configuration file:

TimeFile:                    HEMCO_sa_Time.rc

The time configuration file contains the simulation start and end date (YYYY-MM-DD HH:MM:SS), as well as the emission time step (seconds):

# List here simulation start, end and emission time step
START:   2014-07-01 00:00:00
END:     2014-07-15 02:00:00
TS_EMIS: 3600.0

A note on vertical grid quantities

In v1.1.010 and higher, HEMCO attempts to calculate vertical grid quantities such as pressure edges (PEDGE) and grid box heights (BXHEIGHT_M) if the respective fields are not provided in the HEMCO configuration file. Calculation of the pressure edges is based upon surface pressure values and the Ap/Bp hybrid sigma-pressure coordinates. The pressure values can be provided as field PSFC in the HEMCO configuration file (in units of Pa). If missing, HEMCO will use a uniform value of 101325.0 Pa. Grid box heights are determined via the hydrostatic equation using the grid box edges and air temperature. The latter must be provided in the HEMCO configuration file as field TK (in units of Kelvin). If field TK is not given in the HEMCO configuration file, the grid box heights will not be calculated. This may cause errors for some extensions that need grid box heights.

Provide meteorological data for extensions

When running the HEMCO standalone model, the meteorological fields needed by some of the HEMCO extensions need be provided through the HEMCO configuration file. For example, to read all met fields needed by the sea salt aerosol emissions extension from the GEOS-FP meteorological fields, the following lines need be added to section base emissions of the HEMCO configuration file:

# Met fields for stand-alone use
* WLI   /GEOS_FP/$YYYY/$MM/GEOSFP.$YYYY$MM$DD.A1.2x25.nc LWI    2011-2014/1-12/1-31/0-23 C xy  count * - 1 1
* ALBD  /GEOS_FP/$YYYY/$MM/GEOSFP.$YYYY$MM$DD.A1.2x25.nc ALBEDO 2011-2014/1-12/1-31/0-23 C xy  1     * - 1 1
* TSKIN /GEOS_FP/$YYYY/$MM/GEOSFP.$YYYY$MM$DD.A1.2x25.nc TS     2011-2014/1-12/1-31/0-23 C xy  1     * - 1 1
* U10M  /GEOS_FP/$YYYY/$MM/GEOSFP.$YYYY$MM$DD.A1.2x25.nc U10M   2011-2014/1-12/1-31/0-23 C xy  1     * - 1 1
* V10M  /GEOS_FP/$YYYY/$MM/GEOSFP.$YYYY$MM$DD.A1.2x25.nc V10M   2011-2014/1-12/1-31/0-23 C xy  1     * - 1 1

where /GEOS_FP/$YYYY/$MM/GEOSFP.$YYYY$MM$DD.A1.2x25.nc is the path and filename of the GEOS-FP file.

The met field variables listed in the HEMCO configuration file can also be scaled by user-specific scale factors. For example, to test the sensitivity of sea salt aerosol emissions on an increase of horizontal wind speed (U10M) by a factor of 2.0, a corresponding scale factor can be applied to field U10M:

* U10M  /GEOS_FP/$YYYY/$MM/GEOSFP.$YYYY$MM$DD.A1.2x25.nc U10M   2011-2014/1-12/1-31/0-23 C xy  1     * 1 1 1
...
 
###############################################################################
### BEGIN SECTION SCALE FACTORS
###############################################################################
# ScalID Name sourceFile sourceVar sourceTime C/R/E SrcDim SrcUnit Oper
1 U10M_SCALE 2.0 - - - - 1 1

This will then apply a factor of 2.0 to field U10M. It is further possible to add a mask to the scale factor field, so that the given scale factor is only evaluated over the mask region. For example, to apply the scale factor of 2.0 only over a region spanning 170W – 130W and 20N to 50N, a corresponding mask can be applied to scale factor U10M_SCALE:

1 U10M_SCALE 2.0 - - - - 1 1 1002
 
###############################################################################
### BEGIN SECTION MASKS
###############################################################################
#
# ScalID Name sourceFile sourceVar sourceTime C/R/E SrcDim SrcUnit Oper Lon1/Lat1/Lon2/Lat2
1002 U10M_SCALE_MASK   -170/20/-130/50 - - - - 1 1 -170/20/-130/50

This would then tell HEMCO to use scale factor U10M_SCALE only over the given mask region (unscaled values will be used everywhere else).

Run the HEMCO standalone model

Copy the HEMCO executable hemco_standalone.x to your run directory. The HEMCO standalone model can be executed from the command line by calling the HEMCO standalone executable (hemco_standalone.x) together with the HEMCO configuration file of interest, e.g.:

./hemco_standalone.x HEMCO_sa_Config.rc

HEMCO diagnostic output in netCDF format will be saved to the output/ subdirectory in your HEMCO standalone run directory (as specified by the DiagnPrefix setting in HEMCO_sa_Config.rc). See GEOS-Chem output files wiki page for more information on viewing and manipulating netCDF files.