Difference between revisions of "HEMCO examples"

From Geos-chem
Jump to: navigation, search
(Zero emissions by country)
m (Add emissions into specific levels)
Line 405: Line 405:
:HEMCO can emit emissions into a layer other than the surface layer. For instance, in my example below
:HEMCO can emit emissions into a layer other than the surface layer. For instance, in my example below
     0 EMEP_CO $ROOT/EMEP.nc CO 2000-2014/1-12/1/0 C <span style="color:green">xyL</span>  kg/m2/s CO 1/1001 1 2
     0 EMEP_CO $ROOT/EMEP.nc CO 2000-2014/1-12/1/0 C <span style="color:green">xyL5</span>  kg/m2/s CO 1/1001 1 2
:the <tt>EMEP_CO</tt> emissions would be released into level 5 instead of level 1. Theoretically, you could create a separate HEMCO entry for every emission level and assign a fraction of the total emissions to each of these levels by adding an extra scale factor:
:the <tt>EMEP_CO</tt> emissions would be released into level 5 instead of level 1. Theoretically, you could create a separate HEMCO entry for every emission level and assign a fraction of the total emissions to each of these levels by adding an extra scale factor:

Revision as of 09:43, 19 April 2021

On this page we shall provide examples of how you can customize your settings for the HEMCO emissions component. Please also see the The HEMCO User's Guide for more information.

Scale factor examples

Scaling emissions to a particular year

NOTE: This example pertains to HEMCO base emissions (i.e. emissions that are read from a file). For more information about how to fix emissions to a particular year when using one of the HEMCO extensions, please see the HEMCO extensions examples section below.

Becky Alexander wrote:

I'm trying to figure out how to scale annual anthropogenic emissions to a particular year in HEMCO. My goal is to investigate the role of transport versus emissions changes in the Arctic ice core record of aerosols (mainly sulfate). I will be running the off-line aerosol version.
  1. I want to run for select years from 1979 - 2006 using annual anthropogenic scale factors that match the met field year (i.e., run with 1985 meteorology and with emissions scaled to 1985). this should be pretty standard.
  2. Then I want to run one particular year of met fields (e.g., 2000) repeatedly but using anthropogenic scale factors for various years (e.g., 1985-2006). In other words, the year of the met fields and scaling won't always match.

Christoph Keller replied:

If I understand you correctly, you want to do two things:
  1. Run a standard simulation from 1979 to 2006 with emission being scaled to the respective simulation year. This is the default behavior and you don’t need to change anything.
  2. Run a simulation for year 2000 with emissions being scaled to other years, say 1995. This can be done by fixing the annual scale factors to the year of interest. For example, if you want to have your emissions scaled to 1995, you could change the scale factors as follows:
       1  TOTFUEL_THISYR    $ROOT/AnnualScalar/v2014-07/AnnualScalar.geos.1x1.nc NOxscalar 1985-2010/1/1/0 C xy 1  1

       1  TOTFUEL_THISYR    $ROOT/AnnualScalar/v2014-07/AnnualScalar.geos.1x1.nc NOxscalar 1995/1/1/0 C xy 1  1
This tells HEMCO to use year 1995 for scale factor TOTFUEL_THISYR, no matter of the simulation year. You would need to do this for all annual scale factors.

Update in v1.1.006

As of HEMCO v1.1.006, the emission date can be set in the settings section of the HEMCO configuration file. For example, to fix emissions to year 1995 just add the following line to the settings section:

      Emission year         : 1995

The simulation month, day and hour can be set in the same manner. Any variable not set in the HEMCO configuration file is taken from the model simulation time.

--Bob Y. (talk) 15:15, 11 June 2015 (UTC)

Scale emissions by country

HEMCO has the ability to define country-specific scale factors. To utilize this feature, you must first specify a mask file in the HEMCO_Config.rc file, in the NON-EMISSIONS DATA section. 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

The mask file specified above was created from a shapefile obtained from the GADM database. The country mask netCDF file identifies countries by their ISO 3166-1 numeric code. Countries and their ISO3166-1-numeric codes are listed in the $ROOT/MASKS/v2014-07/country_codes.csv file.

The country-specific scale factors can be specified in a separate ASCII file ending with with the suffix '.txt.' The container name of the mask file (e.g. COUNTRY_MASK) must be given in the first line of the file. The following lines define the country-specific scale factors. ID 0 is reserved for the default values that are applied to all countries with no specific values listed. An example scalefactor.txt file is provided below:

# Country mask field name

# Country data
# Name   | ID  | Scale factor
DEFAULT    0     1.0
CHINA      156   0.95
INDIA      356   1.10

The scale factor(s) listed are interpreted by HEMCO the same way as other scale factors. Multiple values separated by / are interpreted as temporally changing values: 7 values = Sun, Mon, ..., Sat; 12 values = Jan, Feb, ..., Dec; 24 values = 12am, 1am, ..., 11pm (local time!).

The country-specific scale factors would then be defined in the HEMCO_Config.rc file as as:

501 SCALE_COUNTRY [PATH_TO_FILE]/scalefactor.txt  - - - xy unitless 1

The scale factors can the be applied to the emission field(s) that you wish to scale. For example:

0 MIX_NO_IND $ROOT/MIX/v2015-03/MIX_Asia_NO.generic.025x025.nc NO_INDUSTRY 2008-2010/1-12/1/0 C xy kg/m2/s NO  1/27/25/1006/501 1/2 45

These steps can also be used to scale emissions for different regions (e.g. provinces, states) by providing HEMCO with a mask file containing the regions to be scaled.

--Melissa Sulprizio (talk) 18:05, 27 June 2016 (UTC)

Scale emissions by species

In HEMCO v2.1.001 and higher it is possible to define uniform scale factors for single species that apply across all emission inventories, sectors and extensions. These scale factors can be set in section 'Settings' of HEMCO_Config.rc using the optional argument EmisScale_<SpeciesName>. For instance, to scale all NO emissions by 50% add line EmisScale_NO to your settings:

ROOT:                        /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/HEMCO
Logfile:                     HEMCO.log
DiagnPrefix:                 HEMCO_diagnostics
DiagnFile:                   HEMCO_Diagn.rc
DiagnFreq:                   00000000 060000
Wildcard:                    *
Separator:                   /
Unit tolerance:              1
Negative values:             0
Only unitless scale factors: false
Verbose:                     0
Warnings:                    1
EmisScale_NO:                1.5


Zero emissions of selected species

If you would like to zero out emissions of a given species (e.g. NO) from any inventory, then:

(1) Create your own scale factor and assign value 0.0 to it (this has to go into the section where all the other scale factors are listed):

400 ZERO  0.0 - - - xy 1 1

(2) Apply this scale factor to all of the emissions entries in HEMCO_Config.rc that you would like to zero out, e.g.:

0 MIX_NO_IND   $ROOT/MIX/v2015-03/MIX_Asia_NO.generic.025x025.nc   NO_INDUSTRY  2008-2010/1-12/1/0 C xy kg/m2/s  NO  1/27/25/400/1006      1/2 45

This can be a useful way to set the emissions of some species to zero for sensitivity study purposes.


--Bob Yantosca (talk) 21:44, 27 March 2019 (UTC)

Zero emissions by country

Jenny Fisher wrote:

We are using the scale emissions by country method to zero out anthropogenic emissions (by applying a scale factor of 0.0 to Australian boxes).

It works almost perfectly, except that when the country mask is regridded to 4x5, many of the coastal boxes (and all of Tasmania!) end up as "not-Australia". This is a problem for Australia, because nearly all the emissions are along the coast.

Is there a way to force HEMCO to regrid this file in a way that will force a box to be the given region (here 36 for Australia) is even a very small % of it has that code? If not, is there an easy way to offline regrid the current file to 2x2.5 and 4x5 and then manually edit the problem boxes?

Christoph Keller responded:

In cdo you can use remapnn to regrid using the nearest-neighbor method. This should conserve the discrete values. You could then use cdo setbox to manually edit boxes, but this may get somewhat cumbersome. If you just want to set all emissions over Australia to zero you can also create your own mask covering Australia (in the MASK section of the HEMCO configuration file):
    1010 MY_AUSTRALIA_MASK 105.0/-46.0/160.0/-10.0 - 2000/1/1/0 C xy 1 1 105.0/-46.0/160.0/–10.0
Here you directly provide the lower left and upper right corner of the (rectangular) mask instead of a netCDF file: lon_ll/lat_ll/lon_ur/lat_ur. You can then combine this mask with a scale factor of zero to eliminate any emissions over that area. For example, say you wanted to zero out HTAP emissions over Australia:
    0 HTAP_NO_IND $ROOT/HTAP/v2015-03/NO/EDGAR_HTAP_NO_INDUSTRY.generic.01x01.nc emi_no 2008-2010/1-12/1/0 C xy kg/m2/s NO 1/27/25/501 1/2 4
    501 SCALE_COUNTRY 0.0 - - - xy unitless 1 1010
    1010 MY_AUSTRALIA_MASK 105.0/-46.0/160.0/-10.0 – 2000/1/1/0 C xy 1 1 105.0/-46.0/160.0/-10.0

--Melissa Sulprizio (talk) 17:45, 3 February 2017 (UTC)

Scale summertime soil NOx emissions over the US

As of HEMCO v1.1.006, it is possible to pass uniform and/or spatiotemporal scale factors to some of the extensions, including soil NOx extension. For instance, suppose you want to cut summertime soil NOx emissions over the US by a factor of 2. This can be done by assigning a scale field (here, `SOILNOX_SCALE`) to the soilNOx NO emission field in section Extension Switches of your HEMCO configuration file:

104     SoilNOx           : on    NO
    --> Use fertilizer NOx:       true
    --> ScaleField_NO     :       SOILNOX_SCALE

Field SOILNOX_SCALE needs to be defined in section base emissions of the configuration file. It makes most sense to add it to the fields used by the SoilNOx extension:

104 SOILNOX_ARID    $ROOT/SOILNOX/v2014-07/soilNOx.climate.generic.05x05.nc    ARID         2000/1/1/0        C xy unitless NO - 1 1
104 SOILNOX_NONARID $ROOT/SOILNOX/v2014-07/soilNOx.climate.generic.05x05.nc    NON_ARID     2000/1/1/0        C xy unitless NO - 1 1
104 SOILNOX_SCALE   1.0 - 2000/1/1/0 C xy unitless * 333 1 1

SOILNOX_SCALE is just a dummy scale factor with a global, uniform value of 1.0. The actual temporal scaling over the US is done via scale factor 333 assigned to this field. This approach ensures that all soil NOx emissions outside of the US remain intact.

The next step is to define scale factor Nr. 333 (named `SOILNOX_SCALE`) in the scale factor section of the configuration file:

# Scale factor to scale US soil NOx emissions by a factor of 0.5 in month June-August.
333 SOILNOX_SCALE 1.0/1.0/1.0/1.0/1.0/0.5/0.5/0.5/1.0/1.0/1.0/1.0 - 2000/1-12/1/0 - xy 1 1 5000

Scale factor SOILNOX_SCALE defines a monthly varying scale factor, with all scale factors being 1.0 except for months June-August, where the scale factor becomes 0.5. The last column of the SOILNOX_SCALE entry assigns mask Nr. 5000 to this scale factor. This ensures that the scale factor will only be applied over the region spanned by mask 5000. This musk mast be defined in section masks of the HEMCO configuration file:

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
5000 SOILNOX_MASK  -106.3/37.0/-93.8/49.0 - - - xy 1 1 -106.3/37.0/-93.8/49.0

In this example, mask 5000 is defined as the region between 106.3 - 93.8 degrees west and 37.0 - 49.0 degrees north. If you want to apply the soil NOx scaling over the entire US, you can also just refer to the existing USA mask, e.g.:

# Scale factor to scale US soil NOx emissions by a factor of 0.5 in month June-August.
333 SOILNOX_SCALE 1.0/1.0/1.0/1.0/1.0/0.5/0.5/0.5/1.0/1.0/1.0/1.0 - 2000/1-12/1/0 - xy 1 1 1005

Applying scale factors to non-emissions data

Jenny Fisher wrote:

We have a question about applying HEMCO scale factors to fields that are in the non-emissions data section of the HEMCO_Config.rc.

My student Neil (cc’d) is trying to perform two experiments with the Hg simulation:

  1. Zero soil emissions
  2. 3x bromine emissions
For #1, the soil emissions are calculated online in land_mercury_mod.F, but there is a step that multiplies whatever is calculated by the HG0_SOILDIST read from HEMCO, so it seemed like the cleanest way to zero these emissions would be to multiply that field by a scaling factor of zero in HEMCO:
     0 HG0_SOILDIST $ROOT/MERCURY/v2014-09/SOIL/soilHg.presentday.v11-01.geosfp.4x5.nc HG0_DIST 1985/1/1/0 C xy unitless * 55 1 1

     . . . 
     # --- Scale factors for anthropogenic, artisinal, and soil emissions ---
     55 ZEROSOIL       0.0   - - - xy 1 1
However, that doesn’t seem to have had any impact. Are we doing something wrong here, or are scaling factors not applied to this dataset for some reason? Can you suggest a better way to do this?

We tried to do something similar for #2 by setting a scaling factor of 3.0 for the BrOx_GC fields, but this also didn’t appear to work.

Christoph Keller wrote:

Please call HCO_EvalFld instead of HCO_GetPtr, as follows (subroutine MERCURY_READYR in GeosCore/mercury_mod.F, line 3236):
        ! Soil distribution
        CALL HCO_GetPtr( am_I_Root, HcoState, 'HG0_SOILDIST', Ptr2D, RC )
        IF ( RC /= HCO_SUCCESS ) THEN
           CALL ERROR_STOP ( 'Cannot get pointer to HG0_SOILDIST', LOC )
        EHg0_dist =  Ptr2D(:,:)
        Ptr2D     => NULL()
        USE HCO_CALC_MOD,          ONLY : HCO_EvalFld
        ! Soil distribution
        CALL HCO_EvalFld( am_I_Root, HcoState, 'HG0_SOILDIST', EHg0_dist, RC )
        IF ( RC /= HCO_SUCCESS ) THEN
           CALL ERROR_STOP ( 'Cannot evaluate HG0_SOILDIST', LOC )
Note that you don't pass the pointer to HCO_EvalFld but rather the allocated array. The difference between HCO_GetPtr and HCO_EvalFld is that HCO_GetPtr returns an array that points to the 'naked' HEMCO field associated with the given name, i.e. it ignores any scale factors. HCO_EvalFld evaluates and applies the scale factors associated with the given field name.
The content of the data pointer returned by HCO_GetPtr is dynamic, i.e. it can change during runtime if the underlying HEMCO field is updated, e.g. on an hourly basis. The field returned by HCO_EvalFld is static and does not change over time. Because of this, it's good practice to call HCO_EvalFld on every time step - in case that the underlying field and/or scale factors change over time.

--Bob Yantosca (talk) 21:24, 23 June 2017 (UTC)

Mask file examples

Applying regional inventories in nested-grid simulations

Eric Leibensperger wrote:

I've been working to make a smaller nested domain for the New York CH4 project. I changed the bounds from the normal NA domain to -90 to -70 and 30 to 55.
Everything looks good except GEPA. It appears that there is a mask issue in this smaller domain, but I can't figure out how/why. Emissions as shipped in UT: EDGAR, GEPA, CanMex, QFED, JPL_WETCHARTS, SEEPS, FUNG.
With everything on, emissions over Canada and the coastal region are being overlooked compared to the standard NA simulation.
Without GEPA, the emissions in the smaller domain simulation perfectly match those from the standard NA simulation.
With just GEPA on, there is some land/water issues along the coast, but otherwise a match.

Christoph Keller wrote:

In an effort to reduce I/O HEMCO ignores any emission entries that are deemed 'irrelevant' because there is another (global) emission entry for the same species and emission category, but higher hierarchy. For instance, suppose you have the following two fields:
    0 TEST_1 file.nc var 2000/1/1/0 C xy 1 1 CO - 1 1
    0 TEST_2 file.nc var 2000/1/1/0 C xy 1 1 CO - 1 2
In this case, during initialization HEMCO determines that TEST_1 is obsolete because it will always be overwritten by TEST_2 (because of the higher hierarchy). If there is a mask assigned to an emission inventory, HEMCO uses the provided mask domain to determine whether this inventory has to be treated as 'global' or not. I'll try to explain this better with an example. Going back to the example above, let's add a mask to the second field:
    0 TEST_1 file.nc var 2000/1/1/0 C xy 1 1 CO -       1 1
    0 TEST_2 file.nc var 2000/1/1/0 C xy 1 1 CO 1000 1 2
    1000 TEST_MASK mask.nc var 2000/1/1/0 C xy 1 1 -180/180/-90/90
HEMCO uses the highlighted mask range to define the extension of this mask. If that range covers the entire HEMCO grid domain, it considers every emission inventory linked with this mask as 'global'. In our example, TEST_2 would still be considered global because the mask extends over the entire globe, and TEST_1 is thus ignored by HEMCO. However, changing the mask domain to something smaller will tell HEMCO that TEST_2 is not global, and that it cannot drop TEST_1 because of that:
    1000 TEST_MASK mask.nc var 2000/1/1/0 C xy 1 1 -90/180/-45/45
So if you set the mask range to a domain that is somewhat smaller than your simulation window, things work just fine. But if you set the range to something bigger, HEMCO will start ignoring emission files.

--Melissa Sulprizio (talk) 11:57, 13 August 2018 (UTC)

Preserving fractional values when masking emissions

Kelsey Bilsback wrote:

I am setting up a 4x5 simulation coupled with 0.25x0.3125 regional emissions mask that is then used to scale emissions in a small region to zero.

In The HEMCO User's Guide I see that when the mask files are regridded they are remapped to 0 or 1 via regular rounding. Unfortunately, this method will not work well for my application, because the region I am trying to zero out is a small region inside the 4x5 grid cell and thus the current mask will not change the emissions on a 4x5 scale.

I was wondering whether it would be possible/straightforward to modify the mask regridding method such that 4x5 emissions scale will scale with the fraction of the gird cell that is masked (e.g., if a quarter of the grid cells in one of the 4x5 grid are masked, the emissions will scale down by 25%).

Melissa Sulprizio replied:

You may be able to achieve what you want by defining your mask file in the scale factors section of HEMCO_Config.rc. By defining a mask file in SECTION MASKS, HEMCO identifies the data container type as MASK and treats the data as binary (in your example, a regridded value of 0.25 is less than 0.5 so the 4x5 grid box value would be set to MASK=0).
     ... your mask file is currently defined here ...
     ### END SECTION MASKS ###
If you instead move that line to the SECTION SCALE FACTORS then HEMCO will treat the mask as type SCAL. I believe that would preserve the regridded value (in your example 0.25) and apply that to the emissions in a 4x5 grid box.
     ... put your mask file here instead ...

--Bob Yantosca (talk) 19:34, 16 January 2019 (UTC)

Using masks to create emissions for geographically tagged tracers

Doug Finch wrote:

I was planning on making a sort of 'tagged' CH4 run. I know the model already allows for tagging of emissions from different emissions types (wetland etc) but is there a way to do this geographically? I was planning on doing something similar to the tagged CO run but after a quick look at the code it looks like it won't be that simple. Do you have any advice for setting this up?

Bob Yantosca replied:

For the tagged CH4 run, it should be pretty easy to set up. You can just use masks that are defined in the HEMCO config file. If the masks are square regions you can just define them in the HEMCO file like this, in the MASKS section:
   # Country/region masks
   1001 MASK_1     -30/30/45/70   - 2000/1/1/0 C xy 1 1 -30/30/45/70
   1002 MASK_2     -118/17/-95/33 - 2000/1/1/0 C xy 1 1 -118/17/-95/33
   . . . etc. for other regions . . .

If the masks are not square regions, you can create a netCDF file with the various areas.
And then in the BASE EMISSIONS SECTION, for each line of emissions, you need to add extra lines for the tagged tracers so that the masks will get applied. For example, in the HEMCO_Config.rc for CH4, you would add:
   # --- EDGAR v4.2 emissions, various sectors ---
   ### Gas and oil ###
   0 CH4_GAS__1B2a    $ROOT/CH4/v2014-09/v42_CH4.0.1x0.1.nc  ch4_1B2a  2004-2008/1/1/0 C xy kg/m2/s CH4   -    1 1
   0 CH4_GAS__1b2a_1  -                                      -         -               - -  -       CH4_1 1001 1 1
   0 CH4_GAS__1b2a_2  -                                      -         -               - -  -       CH4_2 1002 1 1
   ... etc ... 

   ### Coal mines ###
   CH4_COAL__1B1      $ROOT/CH4/v2014-09/v42_CH4.0.1x0.1.nc  ch4_1B1   2004-2008/1/1/0 C xy kg/m2/s CH4   -    2 1
   0 CH4_COAL__1B1_1  -                                      -         -               - -  -       CH4_1 1001 2 1
   0 CH4_COAL__1B1_2  -                                      -         -               - -  -       CH4_2 1002 2 1
   ... etc ...

This will put the total emissions into your CH4 tracer (tracer #1). It will then also apply the regional masks to the total emissions and then store them into tagged tracers CH4_1 and CH4_2 (or whatever you have them called). These tagged tracers CH4_1, CH4_2, etc. have to be defined in your input.geos and also in your tracer restart file.
Long story short: all of the complexity of putting emissions into tagged tracers is now handled in the HEMCO_Config.rc input file instead of having to hardwire it in the code.

Christoph Keller replied:

Regarding your HEMCO configuration file, we need to be careful about the extensions. Those are much more hardcoded than the "base" emissions and they will only calculate emissions for the species you attach to each extension (in section settings). For instance, your setting for CH4_WETLANDS is:
   121     CH4_WETLANDS      : on    CH4
This means that the CH4_WETLANDS extension will only calculate emissions for CH4, but not for any of the tagged tracers. If you wanted to calculate emissions for those, you need to list them all as extension species:
   121     CH4_WETLANDS      : on    CH4/CH4_1/CH4_2/...    <—> WON’T WORK!!!
However, as I said the extensions are more hardcoded (because they scale fields by temperature, etc.), so the line above won’t work at the moment because CH4_WETLANDS expect only one species. In the future we may try to extend these extensions to accept tagged tracers

--Bob Y. (talk) 15:26, 11 June 2015 (UTC)

HEMCO extensions examples

Fixing emissions to a current year in MEGAN

Lu Shen wrote:

Is it possible to fix MEGAN emissions in one year? I know this works for many other emission inventories, but MEGAN emissions are dependent on environmental variables.

Melissa Sulprizio replied:

[The best] option may be to run the HEMCO standalone and save out MEGAN emissions for a year, then use the HEMCO diagnostic output saved to netCDF as input for your MEGAN emissions instead of using the MEGAN extension.
(1) Run the HEMCO standalone model. Make sure the following entries to your HEMCO_Diagn.rc file:
     EmisISOP_Biogenic  ISOP   108    -1  -1   2   kg/m2/s  ISOP_emissions_from_biogenic_sources
     EmisISOP_Biogenic  ISOP   108    -1  -1   2   kg/m2/s  ISOP_emissions_from_biogenic_sources
     EmisALD2_Biogenic  ALD2   108    -1  -1   2   kg/m2/s  ALD2_emissions_from_biogenic_sources
In the above entries 108 tells HEMCO to get the emissions from the MEGAN extension (HEMCO extension #108) for the specfied species. You can change the units the emissions are saved out as -- typically we save the biogenic emissions out in atomsC/cm2/s, but for this purpose it may make sense to save out the emissions in HEMCO's preferred unit kg/m2/s. See the HEMCO users guide for more instructions on the HEMCO diagnostics. You'll also want to make sure you have the following lines near the top of your HEMCO_Config.rc to enable saving out the HEMCO diagnostics.For example, for monthly HEMCO output:
     DiagnFile:                   HEMCO_Diagn.rc
     DiagnPrefix:                 HEMCO_diagnostics
     DiagnFreq:                   Monthly
(2) Run GEOS-Chem with the following settings:
(a) Turn the MEGAN extension off in HEMCO_Config.rc
(b) Add entries for reading the the fixed MEGAN emissions saved out in step 1 to the base emissions section. For example:
     0 MEGAN_ISOP YOURPATH/HEMCO_diagnostic.2016$MM010000.nc EmisISOP_Biogenic 2016/1-12/1/1/0 C xy kg/m2/s ISOP - 4 1
Note: HEMCO cat=4 is reserved for biogenic emissions.
I think that should do it. You can run a short simulation and check the biogenic emissions output to make sure it worked as expected.

--Bob Yantosca (talk) 20:04, 16 January 2019 (UTC)

Other examples

Add emissions into specific levels

Christoph Keller wrote:

HEMCO can emit emissions into a layer other than the surface layer. For instance, in my example below
    0 EMEP_CO $ROOT/EMEP.nc CO 2000-2014/1-12/1/0 C xyL5  kg/m2/s CO 1/1001 1 2
the EMEP_CO emissions would be released into level 5 instead of level 1. Theoretically, you could create a separate HEMCO entry for every emission level and assign a fraction of the total emissions to each of these levels by adding an extra scale factor:
    0 EMEP_COL1 $ROOT/EMEP.nc CO 2000-2014/1-12/1/0 C xyL1  kg/m2/s CO 1/150/1001 1 2
    0 EMEP_COL2 $ROOT/EMEP.nc CO 2000-2014/1-12/1/0 C xyL2  kg/m2/s CO 1/151/1001 1 2
    0 EMEP_COL3 $ROOT/EMEP.nc CO 2000-2014/1-12/1/0 C xyL3  kg/m2/s CO 1/152/1001 1 2
Where scale factors 150, 151, 152 are the fractions of EMEP to be emitted into level 1, level 2, etc.
    151 EMEP_LEV1_FRAC 0.5 - - - xy 1 1
    152 EMEP_LEV2_FRAC 0.1 - - - xy 1 1
    153 EMEP_LEV3_FRAC 0.1 - - - xy 1 1
But this is somewhat cumbersome. Also, this won’t give you the possibility to specifically emit a fraction above the PBL given that the PBL height is variable over time.
HEMCO v2 (included in GEOS-Chem v11-01) contains additional options to emit 2D fields across multiple vertical levels. For instance, to release 1.0 kg/m2/s of NO into levels 1-5, you can use:
    0 NO_MULTILEVELS 1.0 - - xyL=1:5         kg/m2/s NO – 1 1
The emissions are then spread across the lowest 5 model levels based upon the model level thicknesses. Instead of specifying the model levels it is also possible to specify the altitude in meters or use PBL for the planetary boundary layer. For example, the following are all legal:
    0 NO_MULTILEVELS 1.0 - - xyL=1:2500m     kg/m2/s NO – 1 1   —> emits from surface level to 2500m
    0 NO_MULTILEVELS 1.0 - - xyL=1000m:5000m kg/m2/s NO – 1 1   —> emits from 1000m to 5000m
    0 NO_MULTILEVELS 1.0 - - xyL=500m:17     kg/m2/s NO – 1 1   —> emits from 500m to level 17
    0 NO_MULTILEVELS 1.0 - - xyL=1:PBL       kg/m2/s NO – 1 1   —> emits from surface level to PBL top
In HEMCO v2.1.005 it is legal to read the emission level from an external source (i.e. netCDF file) listed as a scale factor. This field can then be referred to using its scale factor ID. As an example, let's assume daily varying emission heights are archived in file emis_heights.nc, variable emish (in units of m, available for years 2009 to 2010). We can then define a scale factor (in the scale factors section) with a user-defined scale factor ID (300 in this example):
    300 EMIT_HEIGHT emis_heights.nc emish 2009-2010/1-12/1-31/0 C xy m 1

and refer to this scale factor as the upper bound of the injection height:

    0 GFAS_CO GFAS_201606.nc cofire 2009-2010/1-12/1-31/0 C xyL=1:scal300 kg/m2/s CO - 5 3

It should be noted that HEMCO always regrids the fields to the model grid before doing any data operations. If the emission height file is very spotty and contains a lot of zeros the averaged injection heights may be too low. In this case it may be required to set all zeros to missing values (which are ignored by HEMCO) to achieve the desired result.

--Melissa Sulprizio (talk) 18:40, 1 March 2017 (UTC)

Passive species

The passive species module allows you to run a suite of passive species alongside any simulation, i.e. it works with all simulation types. To use the passive species follow these steps:

1. Include passive species in the advected species menu in input.geos. For example, to add passive species to the TransportTracers (formerly Rn-Pb-Be) simulation:

Type of simulation      : 1
Species Entries ------->: Name
Species name            : Rn222
Species name            : Pb210
... etc ...
Species name            : PASV1
Species name            : PASV2
Species name            : PASV3
... etc ...

2. Create a PASSIVE SPECIES MENU in input.geos where you define the basic properties of the passive species. The passive species menu can be added anywhere in input.geos.

For each passive species you must define the following quantities (each of which is color-coded for reference below):

Quantity Units Description
Name - Name of the species. Each species name listed in the PASSIVE SPECIES MENU must exactly match the corresponding species name in the ADVECTED SPECIES MENU. If the two menus aren't consistent, you will get a species database error.
Molecular weight g mol-1 Molecular weight of the species
Atmospheric lifetime s Atmospheric lifetime of the species. A value of -1 denotes that the species never decays (i.e. it has an infinite lifetime).
Default initial atmospheric concentration mol mol-1 The default initial background concentration. GEOS-Chem will use this value if the passive species concentration cannot be found in the GEOS-Chem restart file. If the passive species is included in the restart file, GEOS-Chem will use the concentrations from the restart file instead of the default initial concentrations. The passive species concentration field is automatically written to restart files created at the end of a GEOS-Chem simulation.

In other words, the default initial concentrations set in input.geos are only used to "coldstart" a passive species.

Species long name - An optional string for the long name of the species. This will be used to define the long_name variable attribute when archiving the species to netCDF diagnostic output.

NOTE: This field is only available in GEOS-Chem 12.2.0 and later versions.

The following PASSIVE SPECIES MENU example (for GEOS-Chem 12.2.0 and later versions) defines 3 species with the following properties:

  1. MW = 50 g/mol; atmospheric lifetime = 1 hour; default initial concentration = 1 ppt
  2. MW = 250 g/mol; atmospheric lifetime = 3.8 days; default initial concentration = 1 ppb
  3. Same as species #2, but with an infinite lifetime (never decays)
Passive species #1      : PASV1 50.0  3600.0   1.0e-12 Passive_Species_1
Passive species #2      : PASV2 250.0 328320.0 1.0e-09 Passive_Species_2
Passive species #3      : PASV3 250.0 -1       1.0e-09 Passive_Species_3
... etc ...

NOTE: If you are using a GEOS-Chem version prior to GEOS-Chem 12.2.0, then you must also specify the number of passive species as the first line of the PASSIVE SPECIES MENU (e.g. Number of passive spec. : 3). This value was formerly stored in Input_Opt%N_PASSIVE. Also note that the optional species long name field is not present. Thus for versions prior to 12.2.0, you would set up the PASSIVE SPECIES MENU as follows:

Number of passive spec. : 3
Passive species #1      : PASV1 50.0  3600.0   1.0e-12
Passive species #2      : PASV2 250.0 328320.0 1.0e-09
Passive species #3      : PASV3 250.0 -1       1.0e-09
... etc ...

3. Assign emissions to passive species in HEMCO_Config.rc. You can omit this step in which case there will be no sources for your passive species. For instance, to define a uniform flux of 1e-3 and 1e-9 kg/m2/s for PASV1 and PASV2, respectively, add the following two lines to the base emissions section (in HEMCO_Config.rc):

     0 PASV1_Flux 1.0e-3  - - - xy kg/m2/s PASV1 - 1 1
     0 PASV2_Flux 1.0e-9  - - - xy kg/m2/s PASV2 - 1 1
     ... etc ...
NOTE: If you would like to define passive species that are geographically tagged, then make sure to supply the number of the corresponding mask(s) in the third-to-last column. For example:
     0 PASV1_Flux 1.0e-3  - - - xy kg/m2/s PASV1 1000 1 1
     0 PASV2_Flux 1.0e-9  - - - xy kg/m2/s PASV2 1001 1 1
     ... etc ...
Here, 1000 and 1001 refer to mask definitions in the MASKS section of the HEMCO configuration file. Please also see the following section.

4. Request HEMCO diagnostic output. There is no default diagnostics for these emissions but you can easily define a HEMCO diagnostics for each passive species by creating a corresponding entry in the HEMCO diagnostics file (HEMCO_diagn.rc):

# Name       Spec  ExtNr Cat Hier Dim Unit
PASV1_TOTAL  PASV1 -1    -1  -1   2   kg/m2/s
PASV2_TOTAL  PASV2 -1    -1  -1   2   kg/m2/s
PASV3_TOTAL  PASV3 -1    -1  -1   2   kg/m2/s

To activate these diagnostics you need to link to the HEMCO diagnostics file in HEMCO_Config.rc, as well as define the diagnostics output frequency (in the settings section of the HEMCO configuration file). For example to write the diagnostics at 30-minute intervals:

DiagnFile:                 HEMCO_Diagn.rc
DiagnFreq:                 00000000 003000

--Bob Yantosca (talk) 17:56, 27 February 2019 (UTC)

Using the HEMCO built-in diagnostics framework


The HEMCO diagnostics framework lets user define customized diagnostics. All diagnostic definitions need be provided in an external diagnostics definition file, typically called DiagnFile.rc. The diagnostics file name is defined in the settings section of the HEMCO configuration file, together with the diagnostics file name and the diagnostics output frequency. For instance, the following entry tells HEMCO to read diagnostics definitions from file MyDiagnFile.rc and write hourly diagnostics into files Diagnostics.YYYYMMDDhhmmss.nc (the date will be appended to the diagnostics prefix by HEMCO:

      DiagnFile            : MyDiagnFile.rc
      DiagnPrefix          : Diagnostics
      DiagnFreq            : Hourly

All emissions to be written into the diagnostics can now be defined in file MyDiagnFile.rc. For example, the following entries would tell HEMCO to write out total vertical integrated NO emissions (into field NO_TOTAL), 3D field of lightning NO emissions (extension Nr 103, into field NO_LIGHTNING), 2D field of soil NO emissions in kg per grid box (extension 104, into NO_SOIL), total anthropogenic NO emissions (emission category 1, into NO_ANTHRO), and anthropogenic NO emissions from NEI11 (category 1, hierarchy 50, into NO_NEI11):

# Name       Spec ExtNr Cat Hier Dim OutUnit
NO_TOTAL     NO   -1    -1  -1   2   kg/m2/s
NO_LIGHTNING NO   103   -1  -1   3   kg/m2/s
NO_SOIL      NO   104   -1  -1   2   kg
NO_ANTHRO    NO   0      1  -1   2   kg/m2/s
NO_NEI11     NO   0      1  50   2   kg/m2/s

Compute emission totals

Create a DiagnFile.rc with the emission categories or inventories for which you want to compute totals. For example, to compare total NO emissions from different anthropogenic inventories:

# Name          Spec ExtNr Cat Hier Dim OutUnit
EDGAR_NO        NO   0      1  2    2   kg
EMEP_NO         NO   0      1  10   2   kg
BRAVO_NO        NO   0      1  20   2   kg
CAC_NO          NO   0      1  30   2   kg
NEI11_NO        NO   0      1  50   2   kg
MIX_NO          NO   0      1  45   2   kg

Make sure your HEMCO configuration points to DiagnFile.rc:

DiagnPrefix: HEMCO_Diagnostics
DiagnFreq: Monthly
DiagnFile: DiagnFile.rc

If you run for one month, it makes sense to set the diagnostics output frequency (DiagnFreq) to Monthly, then you will get the monthly mean value. You can set the output unit to kg instead of kg/m2/s to get the total flux per grid box.

Once you have the diagnostics, you can easily calculate the emission totals using CDO, NCO, NCL, etc. For example, if you write out the fluxes in kg instead of kg/m2/s, it’s as easy as:

cdo fldsum HEMCO_Diagnostics.201308010000.nc totals.nc

And then

% ncdump totals.nc 
  netcdf totals {
       lon = 1 ;
       lat = 1 ;
       time = UNLIMITED ; // (1 currently)

  2.827249e+09 ;

 NEI11_NO =
  8.113327e+08 ;

  7.514479e+07 ;

  5.152818e+07 ;


  4.196484e+09 ;

--Melissa Sulprizio (talk) 16:41, 24 May 2017 (UTC)

Use of mathematical expressions

HEMCO v2.1.001 supports the use of mathematical expressions in the HEMCO configuration file. Similar to uniform values, these are placed in column 'sourceFile'. All expressions are evaluated during run-time. They can be used e.g. to model an oscillating emission source. All mathematical expressions must contain at least one time-dependent variable that is evaluated on-the-fly. Mathematical expressions are specified by using the prefix MATH:, followed by the mathematical expression. The expression is a combination of variables, mathematical operations, and constants, e.g. 5.0+2.5*sin(HH).

Supported variables & operators

The following variable names and mathematical operations are currently supported:

Variable names: YYYY (current year), MM (month), DD (day), HH (hour), NN (minute), SS (second), DOY (day of year), DOM (# of days of current month), WD (weekday: 0=Sun, 1=Mon, ..., 6=Sat), LWD (weekday in local time), LH (hour in local time), PI (number PI).

Basic mathematical operators: + - * / ^ ( )

Advanced mathematical functions: sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, sind, cosd, tand, log, log10, nint, anint, aint, exp, sqrt, abs, floor. The names refer to the equivalent Fortran functions.


1. To define a sine-wave emission source of NO with an oscillation frequency of 24 hours, add the following line to section 'Base Emissions' in HEMCO_Config.rc:

# ExtNr Name sourceFile sourceVar sourceTime C/R/E SrcDim SrcUnit Species ScalIDs Cat Hier
0 SINE_NO MATH:sin(HH/12*PI) - * C xy kg/m2/s NO - 1 500

We assign an emission category of 1 and a hierarchy of 500 to this field. No scale factors are applied. This emission source will produce negative emissions, which may cause an HEMCO error (depending on your settings, see remarks below). To avoid this, add an offset of 2.0:

0 SINE_NO MATH:2.0+sin(HH/12*PI) - * C xy kg/m2/s NO - 1 500


1. For mathematical expressions it is recommended to set the sourceTime attribute to '*', in particular if the mathematical expression uses some of the short-term variables (HH, NN, SS, LH). This ensures that the expression is evaluated on every emission time step.

2. Mathematical expressions can produce negative emissions, which by default cause HEMCO to stop with an error. Negative emissions can be enabled by setting Negative values to 2 in the HEMCO configuration file.