HEMCO versions

From Geos-chem
Jump to: navigation, search

On this page we provide information about the HEMCO development history.

Contents

Overview

HEMCO is a stand-alone software component for computing emissions in (global) atmospheric models. It provides a highly customizable interface to calculate and diagnose emissions from different sources, regions and species on a user-specified grid through automatic combination, overlay, and update of a set of data inventories and scale factors specified by the user.

HEMCO was implemented into GEOS-Chem v10-01 and allowed for the removal of many obsolete, legacy emissions routines from GEOS-Chem. For a complete list of removed legacy emissions routines, please see our Removal of obsolete modules and files wiki post. Most users of GEOS-Chem will just need to learn how to tell HEMCO which emissions they would like to apply to their GEOS-Chem simulations. For more information, please see the The HEMCO User's Guide. We will be providing more detailed documentation prior to the release of GEOS-Chem v10-01.

HEMCO development history

Each HEMCO version (and its corresponding GEOS-Chem version number(s)) are listed in the table below.

Version Date released Features added Notes
v2.1.011 TBD
  1. Minor modifications to make the HEMCO standalone consistent with the FlexGrid met field entries in HEMCO_Config.rc
  2. Wrap remaining HEMCO extensions (GC_RnPbBe, GC_POPs, DustGinoux, and TOMAS_Jeagle) in instances for consistency with 12.1.009 updates
  3. HEMCO standalone now calls HCO_RUN in two phases
v2.1.010 05 Oct 2018
  1. Bug fix: Read data with the "E" cycle flag just once
  2. Add fix for collapsing model levels to reduced grid
  3. Fix unit conversion in HCO_UNIT_GetAreaScal
  4. Add "CS" cycle flag to skip fields that aren't found
v2.1.009 13 Sep 2018
  1. Wrap HEMCO extensions into instances
v2.1.008 08 Aug 2018
  1. Bug fix: now respect range/exact flag for 1D values set in HEMCO configuration file
v2.1.007 18 Jul 2018
  1. Fixed error in HEMCO "exact" cycling option
  2. Stop with error if multiple containers have the same name
  3. Bug fix for distributing emissions in the vertical dimension
  4. Add extra error checks in HEMCO standalone module
  5. Remove null string character from netCDF unit string
  6. Bug fix for HEMCO soil NOx with ifort 17
v2.1.006 10 Jun 2018
  1. Update for the CH4 specialty simulation
    • CH4 emissions from wetlands now uses category #1
    • CH4 emissions from rice now uses category #2
  2. Added mol/mol to list of unitless quantities.
v2.1.005 27 Jan 2018
  1. Add option to emit into layer height read from netCDF file
v2.1.004 30 Dec 2017
  1. Updates to remove possible issues / excessive print statements when operating in GEOS environment
  2. Fix possible tracer ID mismatch in sea salt extension
  3. Add option to normalize MEGAN LAI,HEMCO diagnostics
  4. Now write multiple time slices into one file
  5. Minor bug fixes
  6. Add an error trap in hcox_dustginoux_mod.F90 to avoid a segmentation fault
  7. Fix bug in HEMCO reference time code
Barron Henderson wrote:
On line 402 of HEMCO/Core/hcoio_write_std_mod.F90, the JULDATE is calculated from the reference time and a 1 is added. Note that there is no increment performed on the JD1985 variable when calculated from simulated day.
       JD1985= JULDAY(refYYYY, refMM, THISDAY ) + 1.0_dp
   
This has the effect of reducing the output time by 1 day. This is shown in the output file where the file name is correct and the time variable
      $ ncdump -v time -t HEMCO.201501010100.nc | grep "time = \""
       time = "2014-12-31 01" ;
Christoph Keller replied:
Thanks for pointing this out. This looks like a bug to me and I also think that we should get rid of the +1.0_dp.
v2.1.003 19 Jul 2017
  1. Normalize MEGAN LAI by PFT. This fix assumes the usage of updated LAI input data
v2.1.002 07 Jul 2017
  1. Enable tokens within math functions
HEMCO can now read and evaluate a mathematical expression. Mathematical expressions can combine time-stamps with mathematical functions, e.g. to yield the sine of current simulation hour. Mathematical expressions must start with the identifier 'MATH:', followed by the actual expression. Each expression must include at least one variable (evaluated at runtime). The following variables are currently supported: YYYY (year), MM (month), DD (day), HH (hour), LH (local hour), NN (minute), SS (second), WD (weekday), LWD (local weekday), DOY (day of year). In addition, the following variables can be used: PI (3.141...), DOM (# of days of current month). For example, the following expression would yield a continuous sine curve as function of hour of day: 'MATH:sin(HH/24*PI*2)'. For a full list of valid mathematical expressions, see module HEMCO/Core/interpreter.F90.
v2.1.001 16 May 2017
  1. Enable data compression in netCDF-4 output files
  2. Fix bug in computation of local time in routine HCO_GetSuncos
  3. HEMCO diagnostic and restart files now have an unlimited time dimension
  4. All internal timestamp variables are now REAL*8, in order to be able to read netCDF time slices in YYYYMMDDhhmm format.
  5. The option to defined species-specific scale factors that are applied across all inventories, categories, hierarchies, and extensions;
  6. The option to use mathematical expressions (such as 2.0 + sin(HH)), but none of them are used in the standard setup.
  7. An update was added to the regridding routines (regrid_a2a_mod.F90) to support non-global grids as well as regridding of missing values. Grid boxes with missing values are now ignored. The old code did not support missing values and would assign a value of 0.0 to all grid boxes with no input value. For regional emission inventories, this meant that all values outside of the domain were treated as zero's and the regridding did essentially dilute the emissions at the grid boundaries. The new code now ignores the grid boxes outside of the boundaries.
  8. The changes in the benchmarks should be small (there were some bug fixes & updates related to I/O and regridding that may create non zero-diff results).
  9. A corresponding feature has also been added in the GEOS-Chem Unit Tester:
    1. We have added a run directory for the HEMCO standalone model to the GEOS-Chem Unit Tester in v11-02c and newer versions. GEOS-Chem users can drop their HEMCO_Config.rc into that directory and test their emission setup right away. This will also allow us to add HEMCO standalone runs to our standard benchmarking procedures.
v2.0.004 26 Jan 2017
  1. Added a shadow variable for optional input argument in update_mixing_ratio in subroutine AIRQNT in dao_mod.F
  2. Added the passive tracer module
  3. Improve write speed of netCDF output files (added to GEOS-Chem in v11-01 public release)
v2.0.003 14 Oct 2016
  1. Added option DiagnRefTime to explicitly specify output diagnostics reference time unit.
  2. Fix missing pointer in call to HCO_CalcVertGrid
  3. Fix bug preventing HEMCO from writing restart files more than once per run
  4. Bug fix in hcox_paranox_mod.F90 (line 632): The deposition flux is now archived as absolute (i.e. positive) number. Without this fix, the merged code should give zero-diff to v11-01h.
  5. The timezones mask file should be updated to file HEMCO/TIMEZONES/v2015-02/timezones_1x1.edit.nc
    The current timezones mask file does not work properly in grid cells with large ocean overlap. The problem is that the ocean values are netCDF _FillValues that become zero within HEMCO. As a quick fix I updated the timezones file to use a value of –5000 in all ocean cells, which then forces HEMCO to determine the time zone based on longitude in those cells.
    NOTE: An improved method of assigning timezones to ocean grid boxes was implemented in the v11-01 public release.
  6. HEMCO v2.0.003 now accepts scale factors for extension fields. For example, to uniformly scale GFED_TEMP by a factor of 2:
    111 GFED_TEMP $ROOT/GFED4/v2015-10/$YYYY/GFED4_gen.025x025.$YYYY$MM.nc DM_TEMP 1997-2014/1-12/01/0 C xy kgDM/m2/s * 1234 1 1
    ...
    1234 GFED_TEMP_SCALE 2.0 - - - xy 1 1
    This update requires that all HEMCO extension fields are evaluated on every emission time step. I don’t expect this to have a notable impact on run time (and it didn’t in my short test runs). However, if you find that it does slow down the benchmark simulation let me know and we can revert to version v2.0.002 (which does not include this update).
  7. HEMCO v2 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
  8. From a coding perspective the HEMCO state object (HcoState) now has to be passed to each routine. HcoState contains all HEMCO related information (such as callback information for error messages). This update was needed to enable the execution of multiple HEMCO instances at the same time. This won’t affect you unless you have to touch HEMCO related code.
  9. Updated the passive tracer code so that it works with the new species database.
v1.1.016 14 Dec 2015
  1. HEMCO standalone run directory (for testing, sensitivities, etc.)
    The HEMCO standalone run directory is set up in such a way that you can directly use the HEMCO executable produced by GEOS-Chem (or the one generated by the HEMCO standalone code) as well as the original GEOS-Chem HEMCO configuration files without any modifications to it.
    The trick is to use a ‘master’ HEMCO configuration file (HEMCO_sa_Config.rc) that defines all information specific to the HEMCO standalone code, such as grid information file, species definitions, met fields needed by emission parameterizations, etc. Everything else is taken from the regular HEMCO_Config.rc by ‘linking’ down to it using the include syntax:
    >>>include HEMCO_Config.rc
    This way, HEMCO_sa_Config.rc only needs to contain the stuff that is specific to HEMCO standalone but all the "real" emission information is obtained straight from the regular HEMCO configuration file. You can then run the HEMCO standalone code by referring to the master configuration file:
    ./hemco_exe_gc.x HEMCO_sa_Config.rc
    where hemco_exe_gc.x is the executable created during compilation of GEOS-Chem.
    Note that the entries in the HEMCO master 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. I used this to disable ParaNOx and SoilNOx (both of them would need to read species concentration fields that I do not have available). You could also disable e.g. NEI2011 by setting it to false in the master file (i.e. In HEMCO_sa_Config.rc):
    0 Base  : on *
    --> NEI2011 : false
  2. Running with the HEMCO standalone code (instead of the executable created when compiling GEOS-Chem)
    This works the same way with the HEMCO standalone code (the code that ships without GEOS-Chem):
    ./hemco_exe_sa.x HEMCO_sa_Config.rc
    However, in order to get the vertical regridding right the HEMCO standalone code needs to be compiled with the GEOS_FP flag. This can be done via compiler option ‘EXTRA_FLAGS’. The compilation sequence for the HEMCO standalone code should look as follows:
    make -j4 EXTRA_FLAGS='–DGEOS_FP -DGRID4x5'
v1.1.015 07 Dec 2015
  1. Bug fix in GEOS5 -> GEOS-4 regridding
  2. Fixed a bug in syncing the MEGAN LAI_PREVDAY variable
v1.1.014 23 Nov 2015
  1. Bug fix when interpolating/averaging between multiple files.
v1.1.013 19 Nov 2015
  1. Allow mask grid points.
v1.1.012 06 Nov 2015
  1. Treat MEGAN restart variables (historic surface temperature and radiation) as running averages
  2. Bug fix to make sure that sea salt aerosol calculations work on curvilinear grids
  3. Added DiagnTimeStamp to control diagnostics time stamp location
  4. Seaflux uses HEMCO landtypes instead of land fraction
  5. Bug fix: restrict day to last day of month when searching for file names.
v1.1.011 14 Oct 2015
  1. Allow horizontal coordinates 'longitude' and 'latitude'
  2. Added time flags 'EF' and 'RF' to force exit if field not found for current simulation datetime
  3. Bug fix in seaflux extension: pull variables out of parallel loop.
v1.1.010 22 Sep 2015
  1. HEMCO can now read any additional (arbitrary) dimension. The dimension index to be used has to be specified in the HEMCO configuration file.
v1.1.009 10 Sep 2015
  1. Several bug fixes to allow specifying flexible diagnostics output frequencies.
v1.1.008 13 Jul 2015
  1. Now make sure that Input_Opt%IDEP is of lenght NVEGTYPE and properly used in drydep_mod.F
  2. Bug fix in hcoi_standalone_mod: make sure that current date < simulation end date is properly calculated
  3. Make sure that negative emissions are correctly passed to hierarchy level diagnostics
  4. When reading a data field, check if diagnostics container with the same name exist and write data into it.
v1.1.007 06 Jul 2015
  1. Grid edges can now be explicitly given in HEMCO standalone model
v1.1.006 01 Jul 2015
  1. Aerocom, CH4, FINN, GFED, and soil NOx extensions now accept scale fields
  2. Bug fix: diagnostics update can now span multiple diagnostics levels
v1.1.005 09 Jun 2015
  1. Now also build HEMCO standalone executable
    The compilation of GEOS-Chem now also produces an executable for the HEMCO standalone code, located in HEMCO/Interfaces/hemco_standalone.x. I think this is pretty useful if people want to test emission updates or only run emissions. Up to now, people needed to download the full HEMCO standalone code, which is the same code used in GEOS-Chem plus an example directory.
    For now, the GEOS-Chem compilation just produces the HEMCO standalone executable, but no example data and/or HEMCO standalone run directory is provided. We will add a sample run directory shortly, perhaps to the GEOS-Chem unit tester.
  2. Make sure that all longitude values are in the range of –180.0 to +180.0 degrees East. GEOS-5 internally uses 0 to 360 degrees East, which causes some problems in longitude look-ups.
  3. Add an extension (HEMCO/Extensions/hcox_aerocom_mod.F90) to read volcanic data from daily ascii tables. This is what we are going to use in the GEOS-5 very high resolution simulation. At the moment, this extension will not work in standard GEOS-Chem because I haven't copied the AeroCom ascii tables onto the Harvard servers. I can do this if there is interest.
  4. You can now emit 2D data into levels other than the surface level by specifying this via attribute srcDim in the HEMCO configuration file. For example, to emit EDGAR No 1A1a data into GEOS-Chem level 5:
    0 EDGAR_NO_1A1a $ROOT/EDGARv42/v2015-02/NO/EDGAR_v42_NO_IPCC_1A1a.generic.01x01.nc emi_no 1970-2008/1/1/0 C xyL5 kg/m2/s NO 1/40/25/30 1 2
  5. HEMCO will now recognize the unit strings % and percent as unitless quantities (i.e. they will not be treated as fluxes). This allows you to more accurately specify the units of certain types of data, such as the UV Albedo data:
    #==============================================================================
    # --- UV albedo, for photolysis (cf Hermann & Celarier, 1997) ---
    #==============================================================================
    (((+UValbedo+
    * UV_ALBEDO $ROOT/UVALBEDO/v2015-03/uvalbedo.geos.2x25.nc UVALBD 1985/1-12/1/0 C xy percent * - 1 1
    )))+UValbedo
  6. Bug fix to avoid out-of-bounds errors when the MEGAN_mono extension is turned off
  7. Bug fix to restore archiving biogenic CO emissions from monoterpenes into the BIOGENIC_CO diagnostic
v1.1.004 20 May 2015
  1. The HEMCO standalone now works over nested domains.
  2. It is now possible to apply scale factors to met fields that are read through the HEMCO configuration file. This is really useful for sensitivity studies, e.g. to scale wind speed by 10% and see what the response of the emissions to that would be.
  3. Base emissions can now have a dynamic number of scale factors (used to be limited to a fixed number).
  4. Fix bug in HCO_EmisAdd that prevented the FINN [biomass] diagnostics from being written. The problem only occurred when you passed a CAT=-1 and HIER=-1 to HCO_EmisAdd. I think that was only the case in FINN. This is now fixed.
  5. Add more flexibility to the definition of the vertical dimension in the HEMCO configuration file (attribute SrcDim). For example, you can use
    • xy1 to read only the first level of the input data
    • xy25 to read levels 1-25
    • xy-1 to read one level but in reversed order (e.g. the top level of the input data is read and put into HEMCO level 1)
    • xy-25 to read the top 25 levels of the input data but add them to HEMCO levels 1-25 (in reversed order)…
    This update shouldn’t affect the standard code!
  6. Update to the PARANOX code that gets rid of the PARANOX restart fields, and is more stable during run time. Both SUNCOS and SUNCOS - 5 hours used by HEMCO are now calculated from within HEMCO. Also, the PARANOx restart variables in the HEMCO restart file are not needed anymore and can thus be removed, e.g.:
    ncks –xv PARANOX_SUNCOS1,PARANOX_SUNCOS2,PARANOX_SUNCOS3,PARANOX_SUNCOS4,PARANOX_SUNCOS5 HEMCO_restart.201307010000.nc tmp.nc
    mv tmp.nc HEMCO_restart.201307010000.nc
    Finally, the PARANOX_SUNCOS entries in HEMCO_Config.rc are not needed any more, and can be deleted:
    # --- PARANOx restart variables
    102 PARANOX_SUNCOS1 HEMCO_restart.$YYYY$MM$DD$HH00.nc PARANOX_SUNCOS1 $YYYY/$MM/$DD/$HH E xy 1 * - 1 1
    102 PARANOX_SUNCOS2 HEMCO_restart.$YYYY$MM$DD$HH00.nc PARANOX_SUNCOS2 $YYYY/$MM/$DD/$HH E xy 1 * - 1 1
    102 PARANOX_SUNCOS3 HEMCO_restart.$YYYY$MM$DD$HH00.nc PARANOX_SUNCOS3 $YYYY/$MM/$DD/$HH E xy 1 * - 1 1
    102 PARANOX_SUNCOS4 HEMCO_restart.$YYYY$MM$DD$HH00.nc PARANOX_SUNCOS4 $YYYY/$MM/$DD/$HH E xy 1 * - 1 1
    102 PARANOX_SUNCOS5 HEMCO_restart.$YYYY$MM$DD$HH00.nc PARANOX_SUNCOS5 $YYYY/$MM/$DD/$HH E xy 1 * - 1 1
    This update will create some differences compared to the previous code because all HEMCO SUNCOS values are now at the emission time step and not at the chemistry mid-point, e.g. HEMCO now consistently uses SUNCOS instead of a mix of SUNCOS and SUNCOSmid. The latter has caused some confusion and could cause problems at high resolutions.
v1.1 16 Apr 2015
  1. Various updates to PARANOX:
    1. Bug fix in calculation of H2O ambient air concentration and the calculation of the current date SZA;
    2. The loss fluxes of O3 and HNO3 are now passed in kg/m2/s via the HEMCO diagnostics instead of converting them to a deposition velocity (and then recalculating a flux from this value);
    3. Restored the ND63 diagnostics. For more information, see our Ship emissions wiki page.
    4. The SUNCOS values for the previous 5 hours are now saved out to the HEMCO restart file.
  2. Diagnostics update: Collections are now organized in a linked list. This allows the user to define as many collections as desired. The output frequency is now assigned to the collection, not the individual fields, e.g all fields of a collection have now the same output frequency. The output frequency of the default HEMCO diagnostics collection, as well as fields to be added to this collection, can now be defined through the HEMCO configuration file (optional). The HEMCO restart collection is now written out alongside with the regular GEOS-Chem restart fields.
  3. HEMCO has now two run phases: Phase 1 reads the HEMCO list, phase 2 calculates emissions. This allows us to correctly update fields and handle diagnostics that are not related to emissions.
  4. Masks update: Masks can now be treated as fractions (instead of binary values).
  5. Environmental fields update: Environmental fields used by HEMCO (stored in the ExtState object) can now be provided via the HEMCO I/O infrastructure, e.g by reading them directly from disk. This is particularly useful for the standalone version, but can also be very helpful for sensitivity studies (e.g. to use other wind fields, etc.).
  6. Various updates to the HEMCO standalone code
  7. Modifications to on/off switches in the HEMCO configuration file
    • It is now possible to use extension names for the switches, e.g.:
    (((.not.ParaNOx
    ... etc...
    ))).not.ParaNOx
    • You can now combine multiple switches by the word .or., e.g.:
    (((.not.GFED.or.FINN
    ... etc ...
    ))).not.GFED.or.FINN
v1.0 07 Nov 2014
  1. Initial HEMCO release
  2. Treat OCPI, OCPO, BCPI, and BCPO separately
  3. Fix segmentation fault when emissions are turned off
  4. Fix for how alkalinity is computed:
    The alkalinity (and number density) are still directly obtained from the SSA emission flux. The problem is that in any given grid box, the alkalinity (in kg) at a given level is set to the total SSA flux for that grid box, e.g.
    ALK(I,J,L) = SSA(I,J) * AREA(I,J) * EMIS_TS
    So the total column alkalinity for any given I,J location is much higher than the total SSA emissions at this location. I think it should be:
    ALK(I,J,L) = FRAC_OF_PBL(I,J,L) * SSA(I,J) * AREA(I,J) * EMIS_TS
    where FRAC_OF_PBL(I,J,L) makes sure that the total emitted SSA are distributed uniformly within the PBL.
    This fix will affect the concentrations of SO4s and NITs.
  5. Fixes for the BIOGENIC_OCPI diagnostic. This diagnostic was not being computed properly in the v10-01e 1-month benchmark and returned all zeroes. This has now been corrected. However, this diagnostic is disabled in all SOA simulations (it will return all zeros).
  6. PARANOx now includes the latest patch provided by Chris Holmes: The look-up-table data can be read from netCDF or from txt file (the later is useful for ESMF!), the parameterization now takes into account wind speed, and N dry deposition is included via loss of HNO3. In addition, the total tropospheric column mass is now used to calculate the dry deposition frequencies (s-1), instead of the surface grid box mass only (following the suggestion of Chris Holmes).
    The input data format and source directory need to be specified in the HEMCO configuration file (this replaces entries FracNOx table and IntOPE table):
    102 ParaNOx  : on NO/NO2/O3/HNO3
    --> LUT data format  : nc
    --> LUT source dir  : $ROOT/PARANOX/v2015-02
  7. The stratospheric production and loss data is now read through HEMCO. I had to slightly modify the original netCDF files. It also requires an update of the HEMCO configuration file. Look for all the GMI_LOSS_XXX and GMI_PROD_XXX fields.
  8. Local times can now be calculated based on a time zone map provided through the HEMCO configuration file. This file is expected to be named TIMEZONES and must contain the UTC offsets (in hours) for each grid box. These offsets will then be used when calculating the local times. If no such file is provided - or an invalid value is encountered in a given grid box (e.g. -999) - local times are calculated with the previous method, e.g. as a function of longitude (assuming each time zone spans 15 degrees in longitudinal direction).
  9. A time zone file at 1x1 degrees is stored in:
    ftp://ftp.as.harvard.edu/gcgrid/data/ExtData/HEMCO/TIMEZONES/v2015-02/timezones_1x1.nc
    The corresponding entry can also be found in the HEMCO configuration file listed above (field TIMEZONES).
  10. Non-emissions data update: It is now legal to set the extension number (ExtNr) in the configuration file to the wildcard character (*). This is useful for data that shall be read/regridded by HEMCO but that is not used for emission calculation, such as the stratospheric data. Note that these data will only be read if the corresponding species name is a valid GEOS-Chem tracer.
  11. Horizontal regridding of index-based (e.g discrete) data is now done with the map_a2a algorithm. There were some problems with the original implementation of the index-based regridding (using the MESSy regridding tool NCREGRID), so I switched back to map_a2a. Index based regridding does not interpolate between grid boxes but picks the value with the highest contribution in a given grid box. This should only be applied to data with (few) discrete values, e.g. land types or time zones. As previously, the unit attribute in the configuration file must be set to ‘count’ to denote index-based data.
  12. CO2 simulation update: Some minor fixes in the treatment of weekly data. I made these changes mostly for Ray Nassar and the CO2 simulation. In general, the WD time attribute should always be used for weekly data, e.g. the time stamp in the HEMCO configuration file should be set something like 2000/1/WD/0, 2005/1-12/WD/0, etc.
  13. Time indexing update: If you set the C/R/E flag in the configuration file to R (= range), the corresponding data will be used as long as the simulation date is within the time range provided via attribute sourceTime - even if the netCDF data does not cover that range completely. For example, assume you have a scale factor file that contains data from 2003 to 2010, and the corresponding entry in the configuration file looks like this:
    123 THIS_SCALE /path/to/file/file.nc VARIABLE 2007-2100/1/1/0 R xy 1 1
    The scale factor is then considered for any simulation year between 2007 and 2100. For simulation years 2007-2010, the corresponding netCDF data is used. For all years afterwards, the closest available time slice (e.g. year 2010) is used. For simulation dates outside of 2007-2100, the scale factor is ignored altogether (even though the netCDF contains data for years 2003-2006!).
  14. The entries in the configuration file can now be grouped into 'collections' that can be enabled/disabled at the beginning of the HEMCO configuration file. I moved section 'extension switches' almost to the top of the HEMCO configuration file and added an entry for the 'base' extension. A collection can then be defined as a setting of that extension:
    # ExtNr ExtName on/off Species
    0 Base  : on *
    --> AEIC  : true
    --> BIOFUEL  : true
    --> BOND  : true
    etc.
    All entries that are within a collection bracket are only used if the corresponding collection is enabled. The brackets must be on a separate line: (((CollectionName to open a collection, )))CollectionName to close it. e.g.:
    (((AEIC
    0 AEIC_NO $ROOT/AEIC/v2014-10/aeic_2005.geos.1x1.47L.nc NO 2005/1-12/1/0 C xyz kg/m2/s NO 110/115 20 1
    )))AEIC
    It is also possible to nest collections.
  15. It is now possible to assign multiple emission categories to one emission field, e.g. EMEP_NO can cover 2 categories (e.g. anthropogenic + biofuel). For these fields, all emissions are written into the first listed category, and emissions of the 2nd category become zero (but they may cancel out other emissions with lower hierarchy in that region, e.g. EDGAR biofuel emissions).
  16. Modified the HEMCO configuration file. In particular, moved the section 'extension switches' to the beginning and removed section 'extension data'. These are now included in section 'base emissions'. I also modified some of the base emission entries, e.g. by assigning category 2 to all biofuel data, etc. Also uncommented some VOC biofuel inventories that are not included in RETRO (HAC, GLYC) and added the strat-chem prod/loss files and the time zone file.
  17. GEOS-Chem interface update: Slight updates to hcoi_gc_main_mod.F90 so that it now contains a routine to perform some input data error checks (CheckSettings). It mainly makes sure that the switches defined in section 'extension switches' of the HEMCO configuration file are sane. For example, I added a switch SHIPNO_BASE that should only be turned on if PARANOx is turned off. Likewise, I added a switch BOND_BIOMASS that must not be enabled if GFED3 or FINN is being used.
  18. Emissions and dry deposition removal are now applied in one module: GeosCore/mixing_mod.F90. If the non-local PBL mixing is used, mixing within the PBL is done in GeosCore/vdiff_mod.F90 (called from within GeosCore/mixing_mod.F90), and all emissions above the PBL become added to the tracer array afterwards. If the full-mixing scheme is used, dry deposition and emissions are applied to the tracer array, and tracer concentrations are evenly mixed within the PBL afterwards via module GeosCore/pbl_mix_mod.F90. Any emissions / dry deposition removals previously done in other parts of the code (GeosCore/calcrate.F, GeosCore/dust_mod.F, GeosCore/carbon_mod.F, etc.) are deactivated. The process flow in GEOS-Chem now looks like this (same for the non-local PBL and full-mixing scheme):
    1. Calculate PBL heights
    2. Convection
    3. Calculate dry deposition rates
    4. Calculate emissions rates
    5. Turbulence: this will apply emissions and dry deposition, plus non-local PBL mixing or full mixing.
    6. Chemistry
    7. Wet deposition
    IMPORTANT NOTE: As a result of these updates, the ND44 dry deposition flux diagnostic (i.e. GAMAP category DRYD-FLX) is now archived in units of molec/cm2/s for all GEOS-Chem simulations. In prior GEOS-Chem versions, some simulations such as the Rn-Pb-Be simulation, the ND44 drydep fluxes were archived in units of kg/s. Therefore, when you are analyzing GEOS-Chem model output from GEOS-Chem v10-01, please make sure to modify your data processing codes to expect drydep fluxes in molec/cm2/s.
  19. All GEOS-Chem species are now registered as potential HEMCO species (plus some more if needed, e.g. SESQ for MEGAN). This simplifies module hcoi_gc_main_mod.F90.
  20. Some bug fixes have been added to make sure that GEOS-Chem / HEMCO runs properly if emissions are disabled.
  21. Diagnostics updates:
    1. The container ID can now be specified by the user when creating a diagnostics, instead of having it set by HEMCO. This allows identification of HEMCO diagnostics via its ID’s instead of the container name.
    2. Similar to ND44, the emission fluxes added to GEOS-Chem are now written into a diagnostics. They are defined in GeosCore/diagnostics_mod.F90 and filled in GeosCore/mixing_mod.F90 and GeosCore/vdiff_mod.F90. This is for the DEVEL flag only.
  22. The Hermann & Celarier (1997) UV Albedo data—required by the FAST-JX v7.0 photolysis mechanism—are now read from netCDF files via HEMCO. (These data were previously read from bpch files.) We have added these lines to the HEMCO configuration file:
    #==============================================================================
    # --- UV albedo, for photolysis (cf Hermann & Celarier, 1997) ---
    #==============================================================================
    (((+UValbedo+
    * UV_ALBEDO $ROOT/UVALBEDO/v2015-03/uvalbedo.geos.2x25.nc UVALBD 1985/1-12/1/0 C xy 1 * - 1 1
    )))+UValbedo
    These data will be read for full-chemistry simulations or aerosol-only simulations in which chemistry is activated. The +UValbedo collection will activated automatically by GEOS-Chem for these simulations.
  23. GFED-4 biomass burning is now included. GFED-4 is basically the same as GFED-3, so I’m using exactly the same HEMCO extension and simply adjust the input data.
  24. It is now possible to include entire configuration files in the master HEMCO configuration file (HEMCO_Config.rc). This way, we can keep the HEMCO master configuration file more clear. Configuration files can be included with the statement:
    >>>include /path/to/ConfigFile/ConfigFile.rc
    I haven’t added yet any include statements to the master HEMCO configuration file HEMCO_Config.rc. I leave it up to you if we want to use that feature and which files to 'outsource' from HEMCO_Config.rc, but I think candidates include the StratChem files and the RCP data.
  25. It is now possible to use the token $CFDIR to refer to the directory of the HEMCO configuration file. This is useful if the input data is located in the same directory as (or a subdirectory of) the configuration file. For example, if the configuration file is in /home/ckeller/HEMCO/emis/BROMINE/HEMCO_Config_BromoCarb.rc and contains an entry for file $CFDIR/Bromocarb_Liang2010.nc, the file path will be evaluated as /home/ckeller/HEMCO/emis/BROMINE/Bromocarb_Liang.2010.nc. This provides us with a possibility to store and exchange data along with the corresponding HEMCO configuration file snippets.
  26. Added the option to define configuration file data collections that shall be excluded if a given collection name is enabled. This can be done by adding .not. in front of the collection name, e.g. .not.FINN_daily. This is useful to denote data that shall only be used if another collection is not enabled.
  27. Added a restart module that let's you quickly define and obtain HEMCO restart variables. These variables will be automatically written to the HEMCO log-file and can then be used for a 'warm' restart. Several extensions currently use restart variables, e.g. hcox_soilnox_mod.F90. The module hco_restart_mod.F90 contains the restart subroutines, and examples on how to use them can be found in hcox_soilnox_mod.F90 or hcox_megan_mod.F.
  28. The verbose parameter is not a logical switch any more but a number between 0 (no verbose) and 3 (very verbose). There is still some need to clean up the HEMCO log file, but this is a first step.
  29. In DEVEL-mode, the monthly emission totals are now written into the GEOS-Chem logfile. The code snippet that does that is in diagnostics_mod.F90. This is a first attempt to restore some of the emission print statements that were in the old code.
  30. Strat Bry fields that are now read through HEMCO. Br2 concentrations are obtained from BrCl data by preserving Br, e.g. by dividing molecular BrCl by a factor of 2. This is different to the old code, where 1 mol BrCl lead to 1 mol Br2.
  31. HEMCO can now map between native and reduced GEOS grids. For now, this only works within the same model version, e.g. native GEOS-5 onto reduced GEOS-5. I’m about to bring in some additional code that allows us to remap GEOS-5 fields onto GEOS-4 levels.
  32. All other changes are mostly low-level stuff or added functionality that shouldn’t really affect the benchmarks. These are:
    1. The HEMCO MEGAN extension is now in flexible precision.
    2. The historical meteorological data (10-day temperature averages, previous day's LAI, etc.) used in MEGAN can now be read from restart instead of doing a ‘cold’ start.
    3. Masks can now be applied to individual scale factors, e.g. it is possible to enable a scale factor only over a particular region. This was implemented upon request of a number of people, but is currently not used in any of the (benchmark) simulations.
    4. The PARANOx look-up-tables can now be provided in ASCII format. This allows us to run PARANOx in GEOS-5 without having to deal with the netCDF input files and/or the little endian / big endian binary file issues.
    5. HEMCO can now read index-sorted data from an ASCII file and then map these data based on their indices onto the simulation grid. This allows us to define e.g. country-specific scale factors. This is currently not used in any of the benchmark simulations. More information about this option can be found in the HEMCO manual.

Known issues

Error when distributing emissions in the vertical

Sally Wang wrote

Right now I am trying to specify 45% of passive tracer emitted above PBL while 55% of tracer emitted with PBL in tag CO run but I have some difficulties. I followed this wiki page and combine the ideas to implement emission fraction of passive tracer in my run: So in my HEMCO_Config file, I specified the emission rate of this tracer and emitted layer in this way:
     0 INJF_FLUX_FT  1.0e-10 - - - xyL=PBL:47 kg/m2/s INJF 258/1008 1 1
     0 INJF_FLUX_PBL 1.0e-10 - - - xyL=1:PBL  kg/m2/s INJF 259/1008 1 1
The model failed to finish simulation and gave me this error message in HEMCO.log:
     HEMCO ERROR: Negative emissions in: INJF_FLUX. To allow negatives, edit settings in the configuration file.
     ERROR LOCATION: HCO_CalcEmis (HCO_CALC_MOD.F90)
     ERROR LOCATION: HCO_RUN (hco_driver_mod.F90)
I have no idea why negative emission would show up.

Bob Yantosca replied:

I was able to replicate your issue in a Rn-Pb-Be-Passive species simulation with the v11-02d code (in development). I believe that this error is being caused by a parallelization bug in HEMCO, in the module where emissions are distributed in the vertical.
I used the "out-of-the-box" settings the Rn-Pb-Be-Passive species simulation in my input.geos file. I added these two lines (similar to yours) in my HEMCO_Config.rc to specify the passive species emissions flux:
     0 PASV_FLUX_1 1.0e-10 - - - xyL=1:PBL  kg/m2/s PASV - 1 1
     0 PASV_FLUX_2 1.0e-10 - - - xyL=PBL:47 kg/m2/s PASV - 1 1

Running the code gives me this error:

     forrtl: severe (408): fort: (3): Subscript #3 of the array VAL has value -1 which is less than the lower bound of 1
I’ve traced the error to this parallel loop at approx. line 838 of HEMCO/Core/hco_calc_mod.F90. A parallelization error (probably caused by variables that should be held PRIVATE but weren't) is causing the LowLL variable to not be set properly. LowLL gets returned as -1, then this value is used as the level index for the BXHEIGHT_M field lower down in the module.
The quickest solution that I have is for you to disable the parallel loop at ~ line 838 of HEMCO/Core/hco_calc_mod.F90. Add an extra comment character (!) in front of each of the !$OMP statements there.
     !!$OMP PARALLEL DO                                                      &
     !!$OMP DEFAULT( SHARED )                                                &
     !!$OMP PRIVATE( I, J, L, tIdx, TMPVAL, DilFact, LowLL, UppLL          ) & 
     !!$OMP SCHEDULE( DYNAMIC )
     . . .
     !!$OMP END PARALLEL DO                                                  
When I commented out this particular loop, I was able to get the model to pass a Rn-Pb-Be-Passive Speccies simulation unit test. Making this DO loop single processor eliminates the error.
We are looking into this issue and hope to have a fix shortly.

--Bob Yantosca (talk) 20:44, 17 October 2017 (UTC)

HEMCO errors apparently caused by bugs in Intel Fortran Compiler

Some users have reported technical issues with HEMCO that appear to be caused by bugs in the Intel Fortran Compiler.

Compiler Issue Status
Intel Fortran Compiler v15 Segmentation fault occurs when compiling with flags:
-check bounds -O2
Intel Fortran Compiler v13
Intel Fortran Compiler v14
Segmentation fault in HEMCO I/O module

--Bob Y. (talk) 20:30, 25 August 2015 (UTC)

Previous issues that are now resolved

In this section we describe errors and other software issues caused by HEMCO dating back to GEOS-Chem v10-01e. All of these issues have since been resolved.

HEMCO standalone now calls HCO_RUN in two phases

This update was included in GEOS-Chem 12.2.0, which was released on 19 Feb 2019.

In routine HCOI_Sa_Run (located in module in HEMCO/Interfaces/hcoi_standalone_mod.F90), we must now call HCO_Run twice, once with Phase=1 and once more with Phase=2. An update for FlexGrid in GEOS-Chem 12.1.0 added an IF block where emissions are computed only when Phase=2. Therefore, until this fix was made, base emissions were not being computed by the HEMCO standalone.

This update was added to HEMCO version 2.1.011.

--Bob Yantosca (talk) 13:05, 30 January 2019 (UTC)

Wrap remaining HEMCO extensions in instances

This update was included in GEOS-Chem 12.2.0, which was released on 19 Feb 2019.

In HEMCO 2.1.009, several extensions were wrapped in instances. An instance allows the HEMCO extension to run independently on multiple nodes when running in a HPC environment. This is necessary when running GEOS-Chem as GCHP, or when coupled to external models like NASA/GEOS, WRF, etc.

As it so happened, the GC_RnPbBe extension was not updated. This resulted in zero emissions for Rn and Be when using any version of IFORT. When using gfortran, Rn and Be emissions seemed to be fine. This is now fixed by wrapping the GC_RnPbBe extension in instances.

The following extensions are now also wrapped in instances: GC_POPs, DustGinoux, and TOMAS_Jeagle. This update was made to HEMCO version 2.1.011.

--Bob Yantosca (talk) 15:47, 28 January 2019 (UTC)

Update HEMCO standalone for compatibility with FlexGrid

This update was included in GEOS-Chem 12.2.0, which was released on 19 Feb 2019.

In HEMCO v2.1.011 (which will be introduced in GEOS-Chem 12.2.0), the HEMCO standalone was made compatible with the met field updates that were introduced for FlexGrid. Several of the met field names (which are used as inputs to the various HEMCO extensions) needed to be changed in HEMCO/Interfaces/hcoi_standalone_mod.F90 in order to be consistent with the FlexGrid met field definitions in the HEMCO_Config.rc configuration file.

NOTE: The HEMCO standalone in GEOS-Chem 12.1.0 and GEOS-Chem 12.1.1 will not work, as the expected met field names are incorrect. Upgrading to GEOS-Chem 12.2.0 or later will fix this issue.

--Bob Yantosca (talk) 18:12, 22 January 2019 (UTC)

Fix unit conversion in HCO_UNIT_GetAreaScal

This update was included in GEOS-Chem 12.1.0, which was released on 26 Nov 2018.

Erin McDuffie wrote:

I would like to report a unit conversion error in the hco_unit_mod.F90 file, within the HCO_UNIT_GetAreaScal routine (HEMCO v2.1.008).
The error occurs when HEMCO uses an incorrect ‘Scal’ factor when converting from km2 (but not cm2) to m2 and from cm3, dm3, and L to m3. For example, a factor of 1e-6 is used to convert cm-3 to m-3, when I believe this factor should be 1/1e-6.
For example, for O3 in original units of molec/cm3/s (in $ROOT/HEMCO/UCX/v2018-02/UCX_ProdLoss.v11-02d.4x5.72L.nc):
1 molec/cm3/s * mol/6.022e23 molec.*48 g/mol * 1 kg/1e3 g gives a mass scale factor of 7.9e-26 kg/cm3/s.
Multiplying 7.9e-26 kg/cm3/s by an area scale factor of 1e-6 gives 7.9e-32, which is the factor reported in the HEMCO.log file below.
Here is the log file output of the variable PORL_L_S__PO3:
  Reading variable PORL_L_S__PO3
  Unit conversion settings:
  - Species MW         :    48.0000000000000
  - emitted compound MW:    48.0000000000000
  - molecular ratio    :    1.00000000000000
  - keep input species :  T
  - Year, month        :         2013           7
  Data was in units of molec/cm3/s - converted to HEMCO units by applying scale factor   7.970587394050387E-032
  HEMCO WARNING: Data converted from kg/m3/s to kg/m3: UCX_PROD_O3: molec/cm3/s
However, unless I am mistaken, 7.9e-26 kg/cm3/s should actually be multiplied by 1 cm3/1e-6 m3 to result in a scale factor of 7.9e-20 kg/m3/s.

--Melissa Sulprizio (talk) 12:05, 31 October 2018 (UTC)
--Bob Yantosca (talk) 16:08, 26 November 2018 (UTC)

Bug fix: Read data with the "E" cycle flag just once

This update was included in GEOS-Chem 12.1.0, which was released on 26 Nov 2018.

This update does the following:

  • If a file has the time cycle flag E, then that file will be read just once.
  • Also, the HEMCO MEGAN extension will read data from restart files into module variables only once if we are using GEOS-Chem "Classic".
  • Updates the HEMCO version number to 2.1.010.

Prior to this commit, HEMCO would have repeatedly attempted to read any file with the E time cycle flag. This fix had implications for restart files in HEMCO extensions, particularly MEGAN. Since approx. GEOS-Chem 12.0.0, certain MEGAN module variables that only should have been initialized once were getting overwritten on every emissions timestep.)

Also note: this fix should reduce the amount of time spent reading data from disk (as evidenced by the GEOS-Chem "Input" timer, when you compile with the TIMERS=1 option. This is because HEMCO no longer attempts to read files that have already been read. Tests have shown that this fix reduces the time spent in "Input" by approximately 1000 seconds for a 1-month geosfp_4x5_benchmark simulation.

The following time cycle flags are now used:

Cycle Flag Name Description
E Exact Fields are only used on the exact timestamp as requested in the HEMCO_Config.rc file. The file will not be read again once it is found.
EF Exact / Forced Same behavior as CycleFlag = E, but will stop the simulation with an error if the file is not found.
EC Exact / Continuous Fields are only used on the exact timestep as requested in the HEMCO_Config.rcfile. But HEMCO will continue to read or query the file on all timesteps. (NOTE: This is needed when running in the ESMF environment, as variables need to be filled from the ESMF Export State on each emissions timestep.
ECF Exact / Continuous / Forced Same behavior as CycleFlag = EC, but will halt the simulation with an error if the file is not found.

--Bob Yantosca (talk) 16:07, 26 November 2018 (UTC)

Add fix for collapsing model levels to reduced grid

This update was included in GEOS-Chem 12.1.0, which was released on 26 Nov 2018.

There is a bug in the way HEMCO does the vertical interpolation for model levels. In routine ModelLev_Interpolate (in HEMCO/Core/hco_interp_mod.F90), we have:

            ! If needed, collapse from native GEOS-5 onto reduced GEOS-5
            IF ( nlev == 72 .OR. nlev == 73 ) THEN

               ! Add one level offset if these are edges
               IF ( nlev == 73 ) THEN
                  OS = 1
               ELSE
                  OS = 0
               ENDIF

               ! Collapse two levels (e.g. levels 39-40 into level 38):
               CALL COLLAPSE( Lct, REGR_4D, 37+OS, 37+OS, 2, T, 5 )
               CALL COLLAPSE( Lct, REGR_4D, 38+OS, 39+OS, 2, T, 5 )
               CALL COLLAPSE( Lct, REGR_4D, 39+OS, 41+OS, 2, T, 5 )
               CALL COLLAPSE( Lct, REGR_4D, 40+OS, 43+OS, 2, T, 5 )
               ! Collapse four levels:
               CALL COLLAPSE( Lct, REGR_4D, 41+OS, 45+OS, 4, T, 5 )
               CALL COLLAPSE( Lct, REGR_4D, 42+OS, 49+OS, 4, T, 5 )
               CALL COLLAPSE( Lct, REGR_4D, 43+OS, 53+OS, 4, T, 5 )
               CALL COLLAPSE( Lct, REGR_4D, 44+OS, 57+OS, 4, T, 5 )
               CALL COLLAPSE( Lct, REGR_4D, 45+OS, 61+OS, 4, T, 5 )
               CALL COLLAPSE( Lct, REGR_4D, 46+OS, 65+OS, 4, T, 5 )
               CALL COLLAPSE( Lct, REGR_4D, 47+OS, 69+OS, 4, T, 5 )

then in COLLAPSE, we have:

SUBROUTINE COLLAPSE ( Lct, REGR_4D, OutLev, InLev1, NLEV, T, MET )

  ...

  ! Get maximum level to be used for pressure thickness calculations.
  ! This is one more than the number of levels to be used.
  TOPLEV = InLev1 + NLEV

  ! Get pointer to grid edges on the native input grid
  EDG => G5_EDGE_NATIVE(InLev1:TOPLEV)

  ! Thickness of output level
  THICK = EDG(1) - EDG(NLEV)

  ! Get level weights
  ALLOCATE(WGT(NLEV))
  WGT = 0.0
  DO I = 1, NLEV-1
     WGT(I) = ( EDG(I) - EDG(I+1) ) / THICK
  ENDDO

Where the comments in ModelLev_Interpolate says it's lumping two (four) levels, the code is actually lumping three (five) levels. This was leading to an array-out-of-bounds error for G5_EDGE_NATIVE when attempting to collapse fields on level edges from 73 levels to 78 levels. To resolve the issue, we should use:

  ! Get maximum level to be used for pressure thickness calculations.
  TOPLEV = InLev1 + ( NLEV-1 )

  ! Thickness of output level
  THICK = EDG(1) - EDG(NLEV)

  ! Get level weights
  ALLOCATE(WGT(NLEV))
  WGT = 0.0
  DO I = 1, NLEV-1
     WGT(I) = ( EDG(I) - EDG(I+1) ) / THICK
  ENDDO

--Melissa Sulprizio (talk) 16:53, 27 September 2018 (UTC)
--Bob Yantosca (talk) 16:07, 26 November 2018 (UTC)

Fixed error in HEMCO "exact" time option

This fix was included in GEOS-Chem 12.0.0.

We discovered that the HEMCO "Exact" cycling option was not working as intended. We found this error when trying to set up a pulse plume with a passive species. The plume was supposed to be only emitted as a "puff" precisely at 2016/01/01 @ 00:00 GMT, according to these entries in the HEMCO_Config.rc file:

0 PASV_PLUME_FLUX 1.0 - 2016/1/1/0 E xyL=3000m kg/m2/s PASV 1000 1 1

. . .

1000 MASK_PLUME1 110/40/116/45 - 2016/1/1/0 E xy 1 1 110/40/116/45

But it was found that the plume continued to be emitted well past 2016/01/01 @ 00:00 GMT.

Christoph Keller has since submitted a fix for this issue and we have included it in the GEOS-Chem 12.0.0 release.

--Bob Yantosca (talk) 15:19, 9 August 2018 (UTC)

Stop with error if multiple containers have the same name

This fix was included in GEOS-Chem 12.0.0.

HEMCO now stops with an error if multiple containers in HEMCO_Config.rc have the same name. For example, the entries listed below:

#  Cars 
0 DICE_CO    $ROOT/DICE_Africa/v2016-10/DICE-Africa-cars-2013-v01-4Oct2016.nc  CO  2013/1/1/0 C xy g/m2/yr  CO 26/1008 1 60
 
# Motorcycles 
0 DICE_CO    $ROOT/DICE_Africa/v2016-10/DICE-Africa-motorcycles-2013-v01-4Oct2016.nc  CO  2013/1/1/0 C xy g/m2/yr  CO 26/1008 1 60

will now trigger the following error:

HEMCO ERROR: Error: HEMCO field already exists:DICE_CO

We added this update to prevent errors when using HEMCO in GEOS-Chem with the High-Performance option (aka GCHP).

--Bob Yantosca (talk) 15:37, 20 July 2018 (UTC)

Bug fix for distributing emissions in the vertical dimension

This fix was included in GEOS-Chem 12.0.0.

Christoph Keller wrote:

I discovered a bug in HEMCO that affects the vertical distribution of emissions. We now compute the fractions of the lowest and highest level correctly, and get PBL height in meters if needed. I'm fairly confident that it does not matter for the reference simulation because we don't distribute 2D emissions across multiple levels (where the bug fix has an impact).

--Bob Yantosca (talk) 18:13, 19 July 2018 (UTC)

Add extra error checks in HEMCO standalone module

This fix was included in GEOS-Chem 12.0.0.

When running a HEMCO standalone simulation, we discovered that that if the species number ID's are mis-indexed (in HEMCO_sa_Spec.rc), such as:

# ID NAME   MW    MWEMIS MOLECRATIO  K0     CR     PKA
1    CO     28.0   28.0   1.0        0.0    0.0    0.0
3    SOAP  150.0  150.0   1.0        0.0    0.0    0.0
4    NO     30.0   30.0   1.0        0.0    0.0    0.0
   

that this error is not trapped. Instead, an out-of-bounds error can overwrite species metadata such as molecular weights, leading to incorrect results—especially for those species that involve unit conversions.

We have added several fixes to HEMCO/Interfaces/hco_standalone_mod.F90 to avoid this situation. We improve the algorithm for parsing the HEMCO standalone species file. In addition, we now throw errors when

  1. The ID# of the first species read from the HEMCO species file is not 1; and
  2. The ID# of the last species read from the HEMCO species file does not match the total number of species read in.

This should prevent any typos in the HEMCO standalone species file from creating undetected errors.

--Bob Yantosca (talk) 20:57, 18 July 2018 (UTC)

Remove null string character from netCDF unit string

This fix was included in GEOS-Chem 12.0.0.

We have discovered a minor issue when HEMCO reads data into GEOS-Chem "Classic" (via module NcdfUtil/hcoio_read_std_mod.F90). Depending on now the netCDF file was written, the ASCII “NULL” character (\0, with ASCII value = 0) can be appended to the end of strings in the netCDF file. The null character is used in C and similar languages to denote end-of-string. But apparently the Fortran compiler can interpret the null character as a text character instead of a character to be skipped.

Adding debug printout to the HEMCO.log file which illustrates the issue

File units do not match: g/m2/yr^@ vs. g/m2/yr. File: .../HEMCO/DICE_Africa/v2016-10/DICE-Africa-cars-2013-v01-4Oct2016.nc                                                                  
### ThisUnit |g/m2/yr^@|
### OrigUnit |g/m2/yr|

When you trim the string with command TRIM( ThisUnit ), the null character (which prints out in Fortran as ^@) is visible as part of the string. So the compiler thinks that variable ThisUnit (which is the unit string from the netCDF file) has 8 characters instead of 7. This causes the ThisUnit variable not to match the OrigUnit variable (which is the unit string read from HEMCO_Config.rc). For most HEMCO runs, which use Unit Tolerance = 1, this won’t cause a fatal error, but it will print a bunch of annoying File units do not match warning messages to the HEMCO.log file.

The fix is simple. We just need to test the last character of the VarUnit variable to see if it’s the ASCII null character. If it is, we replace it with a Fortran null character (''). This needs to be done in 2 places in NcdfUtil/hcoio_read_std_mod.F90:

(1) In routine NC_READ_VAR_CORE:

    ! Read units attribute. If unit attribute does not exist, return
    ! empty string (dimensionless vertical coordinates do not require
    ! a units attribute).
    a_name  = "units"
    hasVar  = Ncdoes_Attr_Exist ( fId, TRIM(v_name), TRIM(a_name), a_type )
    IF ( .NOT. hasVar ) THEN
       varUnit = 
    ELSE 
       CALL NcGet_Var_Attributes( fID,          TRIM(v_name), &
                                  TRIM(a_name), varUnit     )

       ! Check if the last character of VarUnit is the ASCII null character
       ! ("\0", ASCII value = 0), which is used to denote the end of a string.
       ! The ASCII null character may be introduced if the netCDF file was
       ! written using a language other than Fortran.  The compiler might
       ! interpret the null character as part of the string instead of as
       ! an empty space.  If the null space is there, then replace it with
       ! a Fortran empty string value (''). (bmy, 7/17/18)
       I = LEN_TRIM( VarUnit )
       IF ( ICHAR( VarUnit(I:I) ) == 0 ) THEN
          VarUnit(I:I) = ''
       ENDIF
    ENDIF

(2) And also in routine NC_READ_ARR:

    ! ----------------------------
    ! Read optional arguments
    ! ----------------------------

    ! Read units
    IF ( PRESENT(VarUnit) )THEN
       a_name = "units"
       CALL NcGet_Var_Attributes(fId,TRIM(v_name),TRIM(a_name),a_val)
       VarUnit = TRIM(a_val)

       ! Check if the last character of VarUnit is the ASCII null character
       ! ("\0", ASCII value = 0), which is used to denote the end of a string.
       ! The ASCII null character may be introduced if the netCDF file was
       ! written using a language other than Fortran.  The compiler might
       ! interpret the null character as part of the string instead of as
       ! an empty space.  If the null space is there, then replace it with
       ! a Fortran empty string value (''). (bmy, 7/17/18)
       I = LEN_TRIM( VarUnit )
       IF ( ICHAR( VarUnit(I:I) ) == 0 ) THEN
          VarUnit(I:I) = ''
       ENDIF
    ENDIF

Adding debug output verifies that these fixes indeed strip out the unwanted NULL character:

- Reading from existing stream: .../HEMCO/DICE_Africa/v2016-10/DICE-Africa-cars-2013-v01-4Oct2016.nc
#### NC_READ_ARR VarUnit   before |g/m2/yr^@|
#### NC_READ_ARR last char before |^@|
#### NC_READ_ARR last char after  | |
#### NC_READ_ARR VarUnit   after  |g/m2/yr|

This issue only affects GEOS-Chem "Classic" simulations. For GCHP simulations, HEMCO relies on the MAPL "ExtData" I/O component, which ignores all input unit strings.

--Bob Yantosca (talk) 15:15, 17 July 2018 (UTC)

Bug fix for HEMCO soil NOx error with ifort 17

This fix was included in GEOS-Chem 12.0.0.

Jenny Fisher wrote:

I am having a really bizarre HEMCO error running GEOS-Chem v11-02f (with modifications to use the Australian nested grid, but nothing that would affect HEMCO), tropchem. The following is appearing in my HEMCO.log file:
     Use soil NOx emissions (extension module)
     
     - NOx species            : |  ?(v;+^@^@^B^@^@^@^G^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@          -1  
     - NOx scale factor       :    1.000000
     - NOx scale field        : none
     - Use fertilizer NOx     :  T
     - Fertilizer scale factor:   6.800000090152025E-003

So soil NOx is not being defined properly. I traced this through the HEMCO code and discovered that the issue is arising in HCO_GetExtHcoID in HEMCO/Core/hco_state_mod.F90. I’ve printed virtually everything here, and all looks good until this loop:
     ! Extract species information
     DO I = 1, nSpc
        SpcNames(I) = TRIM(SUBSTR(I))
        HcoIDs(I)   = HCO_GetHcoID( TRIM(SpcNames(I)), HcoState )
     ENDDO

If I print SUBSTR(I) in that loop, all looks good – it prints NO as expected. However, if I print SpcNames(I) it comes up blank. I even tried as a test manually assigning SpcNames(1) to be NO by adding the following before the HcoIDs line:</tt>
     IF (ExtNr == 104) print*,'soil nox'
     IF (ExtNr == 104) SpcNames(1) = 'NO'
     print*,trim(spcnames(I))
     call flush(6)

My "soil nox" message gets printed, but SpcNames(I) still prints an empty string.

Note that none of the other species being read by HEMCO have any problem. I am compiling with DEBUG=yes BOUNDS=yes TRACEBACK=yes, and have tried two different versions of the ifort compiler (17.0.1 and 17.0.4) – all to no avail.

Do you have any idea what is going on here or how to fix it?? For now I am putting in a kludge to manually set Inst%IDTNO = 1 in hcox_soilnox_mod.F90 – but this is clearly not an appropriate solution.

--Bob Yantosca (talk) 15:04, 26 June 2018 (UTC)

Bob Yantosca replied:

We have rewritten the offending DO loop in hco_state_mod.F90 to hopefully be more friendly to compiler versions that exhibit some quirkiness when it comes to parsing strings:
  !
  ! !LOCAL VARIABLES:
  !
      INTEGER             :: I,      AS
      CHARACTER(LEN=255)  :: MSG,    LOC
      CHARACTER(LEN=2047) :: SpcStr, SUBSTR(255)
      CHARACTER(LEN=2047) :: TmpStr

      . . .

      ! Extract species information
      DO I = 1, nSpc
         !---------------------------------------------------------------------
         ! Prior to 6/26/18:
         ! This code can cause issues with certain compiler versions,
         ! so let's rewrite it slightly (bmy, 6/26/18)
         !SpcNames(I) = SUBSTR(I)
         !HcoIDs(I)   = HCO_GetHcoID( TRIM(SpcNames(I)), HcoState )
         !---------------------------------------------------------------------

         ! Rewrite this code to be a little more friendly to compilers with 
         ! strict string-parsing syntax, such as ifort 17. ALSO NOTE: We don't 
         ! necessarily have to do the TRIM in the call to HCO_GetHcoID, because
         ! the species name will be TRIMmed internally.  We have noticed that 
         ! some compilers don't like taking the TRIM of an array element as
         ! an argument to a function call. (bmy, 6/26/18)
         TmpStr      = SubStr(I)
         SpcNames(I) = TRIM( TmpStr )
         HcoIDs(I)   = HCO_GetHcoID( TmpStr, HcoState )
      ENDDO

--Bob Yantosca (talk) 13:52, 27 June 2018 (UTC)

Avoid segmentation fault in DustGinoux extension

This update was included in v11-02c and approved on 21 Sep 2017.

Paolo Tuccella (L'Aquila) wrote:

I have an issue running GEOS-Chem V11-01. When I run the model (merra2_2x25_soa configuration) with the DustGinoux dust emission scheme turned on in HEMCO_Config.rc, GEOS-Chem crashes with this message error:
     Program received signal SIGSEGV: Segmentation fault - invalid memory reference.
The error is occuring at line 395 of HEMCO/Extensions/hcox_dustginoux_mod.F90, where the emissions flux of alkalinity dust is updated. So, turning on DustAlk in HEMCO_Config.rc, the model run without errors.

Bob Yantosca replied:

I’ve figured out the error. So the DustGinoux extension is usually turned off by default in the standard simulations, which is why we didn’t find this earlier. In the module the HEMCO/Extensions/hcox_dustginoux_mod.F, an error trap is lacking. So we need to add the code in GREEN to the existing IF statement at line 395:
      IF ( ExtNrAlk > 0 ) THEN
         IF ( HcoIDsAlk(N) > 0 ) THEN

            ! Add flux to emission array
            CALL HCO_EmisAdd( am_I_Root,    HcoState, FLUX_Alk(:,:,N), & 
                              HcoIDsAlk(N), RC,       ExtNr=ExtNrAlk   )
             IF ( RC /= HCO_SUCCESS ) THEN
                WRITE(MSG,*) 'HCO_EmisAdd error: dust alkalinity bin ', N
                CALL HCO_ERROR(HcoState%Config%Err,MSG, RC )
                RETURN 
             ENDIF

         ENDIF
     ENDIF
If the DustAlk extension is turned off, then the HcoIDsAlk array will be unallocated. Therefore, to avoid a segmentation fault, we need to avoid executing this block of code whenever DustAlk is turned off.

--Bob Yantosca (talk) 20:38, 7 July 2017 (UTC)

Now use YYYYMMDDhhmm format for time stamp values

This update was included in v11-02c and approved on 21 Sep 2017.

This issue affects only GEOS-Chem "Classic" simulations (i.e. running GEOS-Chem without the ESMF and MPI libraries).

Andy Jacobson (NOAA) wrote:

Christoph Keller recently helped me discover a limitation of the netCDF routines used in HEMCO (i.e. for GEOS-Chem "Classic" simulations only), namely that the time coordinate variables are assumed to be integer types. In common situations such as the CarbonTracker netCDF files, the time is encoded as a float with units of "days since". This is silently misinterpreted by HEMCO because of limitations of the underlying netCDF routines. This results in incorrect time slices being chosen for HEMCO emissions, and

Bob Yantosca replied:

Long story short: The HEMCO module HEMCO/Core/hcoio_read_std_mod.F90 only assumed that the time stamps that would be read from netCDF files would only be in YYYYMMDDhh format. As Andy pointed out, it was picking out incorrect time slices for data with YYYYMMDDhhmm timestamps (such as the NOAA Carbon Tracker data).

I’ve gone through and made a bunch of changes in the followng modules:

  • NcdfUtil/ncdf_mod.F90
  • HEMCO/Core/hcoio_read_std_mod.F90
Variables that hold time stamps in hcoio_read_std_mod.F90 are now declared REAL*8, so that they will be large enough to hold a value in YYYYMMDDhhmm format (e.g. floating point value of order 1012). I’ve also adjusted the formulas where we extract e.g. YYYY, MM, DD etc. info from the YYYYMMDDhhmm timestamp accordingly. Also the function NC_READ_TIME_YYYYMMDDhh in ncdf_mod.F90 has now been renamed to NC_READ_TIME_YYYYMMDDhhmm to reflect the fact that it will return timestamps in the YYYYMMDDhhmm format.

--Bob Yantosca (talk) 14:34, 12 April 2017 (UTC)

Read default DEP_RESERVOIR fields from file when not found in HEMCO restart file

This fix was included in v11-02a and approved on 12 May 2017.

Brian Boys wrote:

The HEMCO_Config file that ships out with GC has the date tolerance throughout set as exact (E) for the HEMCO_RESTART file inputs, and so if the HEMCO_RESTART file that is fed in at the beginning of the run isn't exactly the correct hour, the file is not read and default values are used. The concerning part is that one of the restart variables, DEP_RESERVOIR, used by the soilNOx extension has a long e-folding lifetime (4-6 months I think), and the default value(s?) that are used in the absence of a HEMCO_restart file are quite low (I estimate more than a factor of 3 over the E. U.S.). Would it make sense to change the date tolerance to 'C' for the soilNOx extension part of the file that is shipped from Harvard? The seasonal variability appears to be much less than a factor of 3.

The issue with the above solution is that it assumes a HEMCO restart file is included in the run directory. In fact, in GEOS-Chem v11-01 run directories created by the GEOS-Chem unit tester (except those created from 4x5_standard) do not include a HEMCO restart file because it is assumed that it's better to initialize a simulation with the default value than to use a HEMCO restart file for the wrong date.

Christoph Keller wrote:

We could add the default DEP_RESERVOIR field to the HEMCO configuration file and call it DEP_RESERVOIR_DEFAULT:
    104 DEP_RESERVOIR_DEFAULT    DepReservoirDefault.nc    DEP_RESERVOIR   2013/7/1/0 C xy kg/m3 NO – 1 1
And then read this file first and use it as default field when obtaining the soil NOx restart data (hcox_soilnox_run in hcox_soilnox_mod.F90):
    REAL(hp), TARGET :: Tmp2D(HcoState%NX, HcoState%NY)
    REAL(sp)         :: Def2D(HcoState%NX, HcoState%NY)
    ...
    ! DEP_RESERVOIR. Read in kg NO/m3
    CALL HCO_EvalFld( am_I_Root, HcoState, 'DEP_RESERVOIR_DEFAULT', Tmp2D, RC, FOUND=FOUND )
    IF ( FOUND ) THEN
       Def2D = Tmp2D
    ELSE
       Def2D = 1.0e-4_sp
    ENDIF
    CALL HCO_RestartGet( am_I_Root, HcoState, 'DEP_RESERVOIR', &
                         Inst%DEP_RESERVOIR, RC, Def2D=Def2D )
and then delete the IF ( .NOT. FOUND ) statement right afterwards. For DepReservoirDefault.nc we can simply extract DEP_RESERVOIR from the HEMCO restart file used for the benchmark simulation (using cdo selvar).

A file DepReservoirDefault.nc can now be found at

http://ftp.as.harvard.edu/gcgrid/data/ExtData/HEMCO/SOILNOX/v2014-07/DepReservoirDefault.nc

--Melissa Sulprizio (talk) 13:58, 28 March 2017 (UTC)

Make anthropogenic emissions diagnostics 3D

These fixes were included in v11-02a and approved on 12 May 2017.

Jenny Fisher wrote:

Some of the anthropogenic emissions are now 3D (mine, but also NEI2011) - but even if I specify in input.geos that I want to save e.g. ND36 (anthro emissions) over N levels where N>1, the trac_avg file that is created only has surface level ND36. I did some digging, and I assume that is because when you call Diagn_Create() for ND36 in hcoi_gc_diagn_mod.F90, you do so with SpaceDim = 2. Is that correct? Is this perhaps a behaviour that should be changed in future as NEI11 is standard in v11-01?
I also assume the hard-coding in the routine mentioned above is the reason I can’t specify "extra" tracers to be included in ND36 – for example, NO2 (which again shows up with anthro emissions in my files and also in NEI11). Should we perhaps broaden the list of allowable ND36 tracers to match NEI11 species?

--Melissa Sulprizio (talk) 19:17, 22 March 2017 (UTC)

HEMCO diagnostic and restart files now have an unlimited time dimension

This update was included in v11-02a and approved on 12 May 2017.

Andy Jacobson (NOAA) wrote:

It would be convenient and COARDS/CF-compliant to convert the time dimension to an "unlimited" or "record" dimension in the restart files. That way, one can use NCO tools like ncrcat to concatenate them, and thereby have a file with the time evolution of the species. It's trivial to do this, requiring only 2 small changes in HEMCO/Core/hcoio_write_std_mod.F90:
(1) Add this line after the list of USE statements at the top of routine HCOIO_WRITE_STD:
     # include "netcdf.inc"
(2) Substitute NF_UNLIMITED for nTime in the calls to NC_CREATE. Comment out the line in RED and add the line in GREEN:
     ! Create output file 
     ! Pass CREATE_NC4 to make file format netCDF-4 (mps, 3/3/16                                                       
     ! Now create netCDF file with time dimension as UNLIMITED (bmy, 3/8/17)
     IF ( NoLevDim ) THEN
       !CALL NC_CREATE( ncFile, title, nLon,  nLat,  -1,     nTime,         &
        CALL NC_CREATE( ncFile, title, nLon,  nLat,  -1,     NF_UNLIMITED,  &
                        fId,    lonId, latId, levId, timeId, VarCt,         &
                        CREATE_NC4=.TRUE. )
     ELSE
       !CALL NC_CREATE( ncFile, title, nLon,  nLat,  nLev,   nTime,         &
        CALL NC_CREATE( ncFile, title, nLon,  nLat,  nLev,   NF_UNLIMITED,  &
                        fId,    lonId, latId, levId, timeId, VarCt,         &
                        CREATE_NC4=.TRUE. )
     ENDIF
Note that nTime was hard-coded to 1 already in this routine. The #include is there only to get the symbol NF_UNLIMITED.

It looks like this routine also writes the HEMCO_diagnostics.*.nc files, and it makes sense to have time as the record dimension there, too.

I've tested this in the v11-01 public release w/ patches, and it works fine.

--Bob Yantosca (talk) 22:15, 8 March 2017 (UTC)

Fixed bug in computation of local time in HCO_GetSuncos

This fix was included in v11-02a and approved on 12 May 2017.

Seb Eastham wrote:

I just came across an interesting glitch with HEMCO which affects any extension using the HEMCO built-in SUNCOS calculation, including MEGAN. In the routine HCO_GetSUNCOS in HEMCO/Core/hco_geotools_mod.F90, HEMCO uses the local time to calculate the solar zenith angle SUNCOS. However, this has two issues:
  1. If no timezones are defined, then SUNCOS is artificially forced into 15 degree bands
  2. If timezones ARE defined, the SUNCOS becomes defined by political boundaries (see plot below, generated by pulling values directly from GEOS-Chem "Classic" with the new Voronoi timezones):

HEMCO SUNCOS Error.PNG

It would be better to remove the call to HcoClock_GetLocal in routine HEMCO_GetSUNCOS. This fix involves deactivating the code in RED and activating the code in GREEN as shown below:
     !-----------------------------------------------------------------------------
     ! Prior to 3/2/17:
     ! Seb Eastham suggested to comment out the call to HcoClock_GetLocal.  If
     ! the Voronoi or classic timezones are used, this will compute the timezones 
     ! on political boundaries and not strictly on longitude.  This will cause funny
     ! results.  Replace this with a strict longitudinal local time. (bmy, 3/27/17)
     !         ! Local time [hours] at box (I,J) at the midpt of the chem timestep
     !         CALL HcoClock_GetLocal ( HcoState, I, J, cH=LHR, RC=RC )
     !
     !         IF ( RC /= HCO_SUCCESS ) THEN
     !            ERR = .TRUE.
     !            EXIT
     !         ENDIF
     !-----------------------------------------------------------------------------
     ! Prior to 3/2/17:
     ! Seb Eastham says that HOUR (in the new formula below) already contains DT.
     ! so we need to comment this out and just use HOUR + LONGITUDE/15.
     ! (bmy, 3/2/17)
     !         ! Adjust for time shift
     !         LHR = LHR + DT
     !----------------------------------------------------------------------------

              ! Compute local time as UTC + longitude/15 (bmy, 3/2/17)
              LHR = HOUR + ( HcoState%Grid%XMid%Val(I,J) / 15.0_hp )
              IF ( LHR <   0.0_hp ) LHR = LHR + 24.0_hp
              IF ( LHR >= 24.0_hp ) LHR = LHR - 24.0_hp
The idea is to change the calculation so it’s purely a function of physical latitude, not timezone. I've checked with Christoph (cc'd), and this is a genuine bug. It'll be fixed in the next version of HEMCO but I thought it would be worth putting a patch into GC now, given that the code change is minimal and the impact could be significant.

--Bob Yantosca (talk) 17:20, 2 March 2017 (UTC)

Fixed bug in time interpolation in ncdf_mod.F90

This update was included in GEOS-Chem v11-01 public release

Seb Eastham wrote:

While doing final checks on base emissions sets in GCHP, I noticed that the RCP emissions seemed to be about 2x greater in GCHP than in GEOS-Chem "Classic". On further investigation, this appears to be because of a bug in HEMCO; when the interpolation option is set to I, it looks like the interpolation might be using zeros for one of the slices, resulting in 50% of the expect emissions. I tested this by changing the RCP 4.5 interpolation setting from I to C for NOx, and running the year 2013. The two time slices between which interpolation is conducted are 2010 and 2020, between which there is a ~5% decrease in global NOx emissions (based on the original input file); however, when using the option I, I found that the NOx emissions were about 50% lower than when using the option C. Is this a known bug, or did I miss something?

Christoph Keller replied:

There was a bug in the netCDF reading routine that would overwrite the first time slice with the second one, and the interpolation then occurred between the second time slice (the right time window) and an array full of zeros. So no wonder that the results looked wrong. I added a fix for this to NcdfUtil/ncdf_mod.F90.

--Bob Yantosca (talk) 17:45, 10 January 2017 (UTC)

Ocean grid boxes now use the timezone of the nearest land mass for computing emissions

This update was included in GEOS-Chem v11-01 public release

Seb Eastham wrote:

Here are the HEMCO timezones used by default in GEOS-Chem v10-01. These are read from the netCDF file HEMCO/TIMEZONES/v2015-02/timezones_1x1.nc.

Timezones V11-01 Default.png

Note that the timezones of the ocean cells in the above file are not computed robustly. As Christoph Keller points out:

The current timezones mask file does not work properly in grid cells with large ocean overlap. The problem is that the ocean values are netCDF _FillValues that become zero within HEMCO. As a quick fix I updated the timezones file [to HEMCO/TIMEZONES/v2015-02/timezones_1x1.edit.nc in v11-01j] to use a value of –5000 in all ocean cells, which then forces HEMCO to determine the time zone based on longitude in those cells.

Please find a "nearest-cell" version of the HEMCO "timezones" file (HEMCO/TIMEZONES/v2015-02/timezones_voronoi_1x1.nc). I'd like to suggest that this replace the default HEMCO timezones file shown above. The new ("Voronoi") approach sets the timezone in every ocean cell to match that of the closest valid land cell by great circle distance. Without the update, some coastal areas will use the wrong timezone, resulting in incorrect diurnal scalings. Here is a plot of the Voronoi timezones:

Timezones Voronoi.png

The Voronoi timezones will be made the default HEMCO timezones in the v11-01 public release. In the meantime, GEOS-Chem users may select this option by updating this entry in the HEMCO_Config.rc file. Change the text in RED

* TIMEZONES $ROOT/TIMEZONES/v2015-02/timezones_1x1.edit.nc UTC_OFFSET 2000/1/1/0 C xy count * - 1 1

to the text in GREEN:

* TIMEZONES $ROOT/TIMEZONES/v2015-02/timezones_voronoi_1x1.nc UTC_OFFSET 2000/1/1/0 C xy count * - 1 1

--Bob Yantosca (talk) 19:00, 4 January 2017 (UTC)

Fix bug preventing HEMCO from writing restart files more than once per run

NOTE: This update was included in v11-01g (approved 28 Sep 2016).

Christoph Keller wrote:

There is a merge error in the code that shortcuts the diagnostics writing after the first call. This is the current code in HEMCO/Core/hcoio_diagn_mod.F90:
      ! Only write diagnostics if this is the first Diagn_Get call for
      ! this container and time step.
      IF ( ThisDiagn%nnGetCalls > 1 ) CYCLE
   
      ! NOTE: This may have been left over by a Git merge (bmy, 3/5/15)
      ! this container and time step.
      IF ( PRESENT( OnlyIfFirst ) ) THEN
         IF ( OnlyIfFirst .AND. ThisDiagn%nnGetCalls > 1 ) CYCLE
      ENDIF
   
Please remove/comment the highlighted line and recompile.

--Melissa Sulprizio (talk) 16:30, 30 August 2016 (UTC)

Fix missing pointer in call to HCO_CalcVertGrid

NOTE: This update was included in v11-01g (approved 28 Sep 2016).

We have found and fixed an error in routine GridEdge_Set (located in module GeosCore/hcoi_gc_main_mod.F), where we have this code:

!
! LOCAL VARIABLES:
!
    REAL(hp), POINTER   :: PSFC    (:,:  )
    REAL(hp), POINTER   :: ZSFC    (:,:  )
    REAL(hp), POINTER   :: TK      (:,:,:)
    REAL(hp), POINTER   :: BXHEIGHT(:,:,:)
    REAL(hp), POINTER   :: PEDGE   (:,:,:)

    !=================================================================
    ! GridEdge_Set begins here
    !=================================================================

    ! Pointers to fields 
    ZSFC     => State_Met%PHIS
    BXHEIGHT => State_Met%BXHEIGHT
    TK       => State_Met%T

    ! surface pressure in Pa
    ALLOCATE(PSFC(IIPAR,JJPAR))
    PSFC(:,:) = State_Met%PEDGE(:,:,1) * 100.0_hp

    ! Calculate missing quantities
    CALL HCO_CalcVertGrid( am_I_Root, HcoState, PSFC,    &
                           ZSFC,  TK, BXHEIGHT, PEDGE, RC )

    ! Nullify local pointers
    ZSFC     => NULL()
    BXHEIGHT => NULL()
    TK       => NULL()
    IF ( ASSOCIATED(PSFC) ) DEALLOCATE(PSFC) 
    PSFC     => NULL()

   ! Return w/ success
   RC = HCO_SUCCESS

As you can see, PEDGE is never defined, but is nevertheless passed to Hco_CalcVertGrid, which is contained in module HEMCO/Core/hco_geotools_mod.F90. This was producing the following error message in the HEMCO log file:

-------------------------------------------------------------------------------
Details about vertical grid calculations (only shown on first time step):
                                                                               
1. Input data availability:
  - Temperature field TK obtained from model interface (min,max):    179.394287109375        312.010620117188
  - Surface pressure PSFC [Pa] obtained from model interface (min, max):    54482.8735351562        103645.007324219
  - Surface geopotential height ZSFC [m] obtained from model interface (min, max):   -17.0556747924240        5115.05386332234
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
HEMCO ERROR:  Wrong PEDGE array size:          255  -783173889  1988815368; should be:           
72          46          48
ERROR LOCATION: HCO_CalcVertGrid (hco_geotools_mod.F90)
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Because routine GridEdge_Set lacked an error trap to test if Hco_CalcVertGrid exited abnormally, there was no way to stop program execution at this point.

To fix these issues, we have rewritten routine GridEdge_Set as follows. Our new code is displayed in GREEN.

!
! LOCAL VARIABLES:
!
    ! Strings
    CHARACTER(LEN=80) :: MSG, LOC

    ! Pointers
    REAL(hp), POINTER :: BXHEIGHT(:,:,:)    ! Grid box height      [m ]
    REAL(hp), POINTER :: PEDGE   (:,:,:)    ! Pressure @ lvl edges [Pa]
    REAL(hp), POINTER :: PSFC    (:,:  )    ! Surface pressure     [Pa]
    REAL(hp), POINTER :: TK      (:,:,:)    ! Temperature          [K ]
    REAL(hp), POINTER :: ZSFC    (:,:  )    ! Surface geopotential [m ]

    !=======================================================================
    ! GridEdge_Set begins here
    !=======================================================================

    ! Assume success
    RC       =  HCO_SUCCESS

    ! Allocate the PEDGE array, which holds level edge pressures [Pa]
    ! NOTE: Hco_CalcVertGrid expects pointer-based arguments, so we must
    ! make PEDGE be a pointer and allocate/deallocate it on each call.
    ALLOCATE( PEDGE( IIPAR, JJPAR, LLPAR+1 ), STAT=RC )
    IF ( RC /= HCO_SUCCESS ) THEN
       MSG = 'ERROR allocating the PEDGE pointer-based array!'
       LOC = 'GridEdge_Set (GeosCore/hcoi_gc_main_mod.F90)'
       CALL ERROR_STOP( MSG, LOC )
    ENDIF

   ! Edge and surface pressures [Pa]
   PEDGE    =  State_Met%PEDGE * 100.0_hp  ! Convert hPa -> Pa
   PSFC     => PEDGE(:,:,1)

   ! Point to other fields of State_Met
   ZSFC     => State_Met%PHIS               
   BXHEIGHT => State_Met%BXHEIGHT           
   TK       => State_Met%T                  

   ! Calculate missing quantities
   CALL HCO_CalcVertGrid( am_I_Root, HcoState, PSFC,      &
                          ZSFC,      TK,       BXHEIGHT,  &
                          PEDGE,     RC                  )

   ! Stop with an error if the vertical grid was not computed properly
   IF ( RC /= HCO_SUCCESS ) THEN
      MSG = 'ERROR returning from HCO_CalcVertGrid!'
      LOC = 'GridEdge_Set (GeosCore/hcoi_gc_main_mod.F90)'
      CALL ERROR_STOP( MSG, LOC )
   ENDIF

   ! Nullify local pointers
   ZSFC     => NULL()
   BXHEIGHT => NULL()
   TK       => NULL()
   PSFC     => NULL()

   ! Deallocate and nullify PEDGE
   IF ( ASSOCIATED( PEDGE ) ) DEALLOCATE( PEDGE )
   PEDGE    => NULL()

   ! Return w/ success
   RC       = HCO_SUCCESS

Therefore we now:

  1. Allocate an array to store pressure edge values (PEDGE), converted from hPa to Pa, and
  2. Add error traps to stop execution if
    • PEDGE cannot be allocated, or
    • Hco_CalcVertGrid exits abnormally.

Bob Yantosca validated these changes with a unit test on 06 Jun 2016. These updates will be included in GEOS-Chem v11-01g. This fix will also be brought into HEMCO v2.0.

--Bob Yantosca (talk) 14:44, 7 June 2016 (UTC)

Enable emissions in the stratosphere for specialty simulations

This update was validated with 1-month benchmark simulation v11-01f and 1-year benchmark simulation v11-01f-geosfp-Run0. This version was approved on 16 Apr 2016.

Emissions in the stratosphere were disabled in a HEMCO June 2015 update to prevent build-up of stratospheric concentrations due to aircraft emissions (mainly VOCs). The HEMCO update was merged into GEOS-Chem v11-01e. This resulted in very low statospheric Be7 sources to the troposphere and imbalanced Be7 trop+strat sources and sinks in the v11-01f 1-year RnPbBe benchmark. Christoph Keller recommended maintaining disabled emissions in the stratosphere for at least the full-chemistry simulation.

To correct this bug, we now only restrict emissions in the stratosphere if performing a full-chemistry simulation and UCX is turned off. Emissions in the stratosphere are enabled for all specialty simulations. This fix was added to v11-01f prior to final benchmark approval.

--Lizzie Lundgren (talk) 15:15, 22 March 2016 (UTC)
--Bob Yantosca (talk) 15:32, 30 March 2016 (UTC)

Fix for segmentation fault when emissions are turned off

In GEOS-Chem v10-01g, we fixed a bug in HEMCO that caused simulations to die with a segmentation fault when emissions were turned off in the input.geos file.

Bob Yantosca wrote:

If you have these settings in input.geos:
   %%% EMISSIONS MENU %%%  :
   Turn on emissions?      : F
   Emiss timestep (min)    : 60
   HEMCO Input file        : HEMCO_Config.rc
   Etc..
Then you get a seg fault on the RED line of code in routine GetHcoVal (in module file GeosCore/hcoi_gc_main_mod.F90):
    !=================================================================
    ! GetHcoVal begins here
    !=================================================================

    ! Init
    FOUND = .FALSE.
    IF ( PRESENT(Emis) ) Emis = 0.0_hp
    IF ( PRESENT(Dep ) ) Dep  = 0.0_hp

    ! Define tracer ID to be used. This is only different from the
    ! passed tracer ID if some species mapping occurs at this level.
    tID = TrcID

    ! HEMCO species ID corresponding to this GEOS-Chem tracer
    IF ( tID > 0 ) HcoID = M2HID(tID)%ID ID
The issue is that if you turn off HEMCO, then the M2HID pointer never gets initialized. Turning off emissions in will also give us this error in the strat chem module:
   HEMCO ERROR: Container not found: GEOSCCM_Br2_DAY
   ERROR LOCATION: HCO_GetPtr_3D (hco_emislist_mod.F90)

   ===============================================================================
   GEOS-CHEM ERROR: Cannot get pointer from HEMCO! Stratospheric Bry data is 
   expected to be listed in the HEMCO configuration file and the GMI_StratChem
   extension must be enabled. This error occured when trying to get field 
   GEOSCCM_Br2_DAY STOP at Set_BryPointers (start_chem_mod.F90)
   ===============================================================================
        - CLEANUP: deallocating arrays now...
Which is probably to be expected now that HEMCO handles the strat Bry emissions.

Christoph Keller wrote:

I’ve updated my code so that HEMCO can be used with LEMIS = F. The changes are:
1. In main.F, the HEMCO routines are now always called, even if LEMIS is set to FALSE. This ensures that HEMCO can still be used to read non-emission data such as the stratospheric Bry fields.
2. In hcoi_gc_main_mod.F90, there are now two checks for the LEMIS flag: If LEMIS is disabled, no HEMCO species are defined in subroutine Get_nHcoSpc, and as a result HEMCO will not calculate any emissions. Similarly, all HEMCO extensions will be deactivated by forcing all extension numbers to invalid values (—> CALL SetExtNr(… ).
3. Because all extensions are now automatically ignored when LEMIS is set to FALSE, I recommend moving the Strat Bry fields from the extension section into the ‘regular’ base emissions section. This way, these fields are always considered. So you'll need to add the following lines to the end of the BASE EMISSIONS section in the HEMCO configuration file:
     # --- Stratospheric Bry data ---
     0 GEOSCCM_Br_DAY      $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$MM.day.nc   BR     2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_Br2_DAY     $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$MM.day.nc   BRCL   2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_BrO_DAY     $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$MM.day.nc   BRO    2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_BrNO3_DAY   $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$MM.day.nc   BRONO2 2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_HBr_DAY     $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$MM.day.nc   HBR    2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_HOBr_DAY    $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$MM.day.nc   HOBR   2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_Br_NIGHT    $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$MM.night.nc BR     2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_Br2_NIGHT   $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$MM.night.nc BRCL   2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_BrO_NIGHT   $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$MM.night.nc BRO    2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_BrNO3_NIGHT $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$MM.night.nc BRONO2 2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_HBr_NIGHT   $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$MM.night.nc HBR    2007/$MM/1/0 C xyz pptv * - 60 1
     0 GEOSCCM_HOBr_NIGHT  $ROOT/HEMCO/STRAT/v2015-01/Bry/GEOSCCM_Bry.2007$MM.night.nc HOBR   2007/$MM/1/0 C xyz pptv * - 60 1
 
     END SECTION BASE EMISSIONS
You should also remove the corresponding entries in the extensions section, including the extension toggle (GMI_StratChem) itself. If you prefer having the strat Bry fields listed in the extensions section, we can update the SetExtNr routine so that it doesn’t reset the extension number associated with GMI_StratChem. Just let me know if you’d prefer that solution.
4. With LEMIS set to FALSE, my code currently stops with an error because some of the emission diagnostics don’t work any more. I assume it’s expected that user disable the corresponding diagnostics in input.geos (which I didn’t), so I didn’t bother to account for that (e.g. in diag3.F, etc.).

--Bob Y. 14:08, 12 January 2015 (EST)

Now treat OCPI, OCPO, BCPI, and BCPO separately in HEMCO

The original implementation of HEMCO in GEOS-Chem treated carbon aerosols as black carbon (BC) and organic carbon (OC). The speciation into hydrophillic and hydrophobic carbon was done when passing HEMCO emissions to GEOS-Chem. Plots from 1-month benchmark v10-01e revealed large differences in OCPO and OCPI. To resolve these differences, we revert to splitting OC and BC into OCPI, OCPO, BCPI, and BCPO.

Comments from 1-month benchmark v10-01e:

Jeff Pierce wrote:

The HEMCO emissions should be essentially the same as the previous emissions, right? I'm curious as to why the OCPO (hydrophobic OC aerosol from combustion sources) increased so much (see the ratios). There is more than a doubling in many high-OCPO regions.
Even odder to me, OCPO has a fixed "aging" time to OCPI (hydrophilic), but the OCPI trends don't match up (as they should if transport/deposition/aging are held fixed between the two simulations). In some ways, it looks like the aging changed, but I think it's supposed to be fixed at 1.2 days.

Christoph Keller responded:

HEMCO simply includes OC and BC, and the partitioning into hydrophilic and hydrophobic parts is done outside of HEMCO. This way, the fractions (0.5/0.5 for OC and 0.8/0.2 for BC) only need to be defined and applied at one place in the code. In v10-01d, biogenic emissions (and also AEIC aircraft emissions) were just emitted as OCPI, whereas those now become separated into OCPI and OCPO. This explains the increase in OCPO and the simultaneous decrease in OCPI.
If there are concerns about this procedure, we can change the code so that HEMCO explicitly includes OCPI, OCPO, BCPI, and BCPO.

Christoph Keller wrote:

The old code included a biogenic contribution, calculated from the MEGAN terpene emissions (assuming an OC yield of 0.1). These emissions were attributed to OCPI only. In the new version, they are split into OCPI and OCPO. That’s just the way it's implemented. If there is a good (scientific) reason to change it, it can be done quite easily.

Jeff Pierce responded:

Right, this 0.1*monoterpenes is to represent biogenic SOA. It should be considered all hydrophilic organic carbon since SOA has a hygroscopicity (kappa) of around 0.1-0.2 while the hydrophobic OC has kappas much closer to zero. This should be reverted back to being all OCIL as it was before.

--Melissa Sulprizio 13:49, 20 November 2014 (EST)