HEMCO diagnostics¶
Overview¶
HEMCO diagnostics are organized in collections, with each
collection consisting of a dynamic number of diagnostic fields (aka
diagnostic containers). Each collection has a fixed output
frequency (DiagnFreq
) assigned to it. 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 diagnostic 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.
TODO: Find out where these get defined
Currently supported averaging methods are:
-
instantaneous
¶
Instantaneous values (recommended method).
-
mean
¶
Arithmetic mean over the diagnostic interval.
-
sum
¶
Total sum over the diagnostic interval.
-
cumulsum
¶
Cumulative sum since simulation start.
Explicitly setting the averaging method will disable automatic unit conversion and the fields passed to this diagnostic will be stored as is. The optional unit conversion factor can be set to perform a unit conversion before returning the field for output.
Note
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 (Default, Restart, and Manual) 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).
The Default collection¶
The Default collection contains emission diagnostics intended to
be written to disk, e.g. for analysis purposes. All fields of the
default collection are written out at the frequency provided in
setting DiagnFreq
in the settings section of the HEMCO
configuration file. The name of the corresponding diagnostics files
can be specified via the DiagnPrefix
setting. The simulation
date at the time of output will be appended to the diagnostics prefix,
e.g. the diagnostics for Aug 1, 2008 will be written as
HEMCO_Diagnostics.200808010000.nc
. The datetime can denote
the beginning, middle, or end (default) of the time interval, as
specified by setting DiagnTimeStamp
(see below).
Several options for the default diagnostic collection can be specified at the top of the
HEMCO configuration file file. Commonly-used options
are DiagnFile
, DiagnFreq
, and
DiagnPrefix
.
Configuration file for the Default collection¶
Adding the following entries to the diagnostic configuration file
(i.e. the same file specified by DiagnFreq
, commonly called
HEMCO_Diagn.rc
) 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 EPA16 emissions for CO over the USA, then add this line:
#Name Spec ExtNr Cat Hier Dim Unit Longname EmisCO_EPA16 CO 0 1 50 2 kg/m2/s CO_emission_flux_from_EPA16_inventory
It is important that you define valid values for all attributes up
to the hierarchy. As soon as you set an attribute to default
(-1
), HEMCO will take the sum up to this attribute. For
example, the following diagnostics would simply return total base
emissions:
#Name Spec ExtNr Cat Hier Dim Unit Longname EmisCO_EPA16 CO 0 -1 50 2 kg/m2/s CO_emission_flux_from_EPA16_inventory
Restart¶
The output frequency of the Restart collection is End
,
meaning that its content is only written out at the end of a
simulation. The HEMCO Restart collection primarily consists of a suite
of fields needed by some of the HEMCO extensions for a “warm” HEMCO
restart (e.g. the 10-day running mean temperature, etc.). These fields
are automatically added to the HEMCO restart collection and filled
within the respective extensions. Once archived, fields can be made
available to an extension via the HEMCO configuration file.
Manual¶
Fields in the Manual collection do not become written out to disk. Rather, they provide a tool to exchange data files within and outside of HEMCO, e.g. to pass sector-specific emission fluxes from HEMCO to the atmospheric model.
Some HEMCO extensions automatically create and fill a number of manual
diagnostics. For example, the PARANOX extension (used in GEOS-Chem) stores the O3 and HNO3 loss
fluxes in the manual diagnostics PARANOX_O3_DEPOSITION_FLUX
and PARANOX_HNO3_DEPOSITION_FLUX
, respectively.
Importing diagnostic content into an external model¶
The content of the Default collection can
be specified through the HEMCO diagnostics definitions file (specified
by the DiagnFile
option).
The content of the Manual and Restart collections currently need to be defined within the model code (e.g. it is hard-coded). This should be done in high-level routines (at the HEMCO-to-model interface level).
Module hco_diagn_mod.F90
(found in HEMCO/src/Core/
)
provides a suite of routines to define, fill, obtain, etc. diagnostic
fields. Similarly, hco_restart_mod.F90
(also found in
HEMCO/src/Core/
) provides routines for managing HEMCO restart
variables.