View source for HEMCO versions

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

== 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 [[Derived_type_objects_used_by_GEOS-Chem#Removal_of_obsolete_modules_and_files|''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.

{| border=1 cellspacing=0 cellpadding=5
|-valign="top" bgcolor="#cccccc"
!width="100px"|Version
!width="100px"|Date released
!width="400px"|Features added
!width="250px"|Notes

|-valign="top"
|3.0.0
|08 Jan 2021
|
#Split off HEMCO into its own Git repository and use as submodule in GEOS-Chem (and other models)
#The source code has been reorganized
##A script for creating HEMCO standalone run directories can now be found in the run/ subdirectory
##Several driver programs have been added to the src/Interfaces/ subdirectory for using HEMCO in other models
#CMake is the default build system; Support for GNU Make has been retired
#Carbon based units for VOC species have been removed
#CEDS GDB-MAPS is now the default anthropogenic emissions inventory
#See the [https://github.com/geoschem/HEMCO/milestone/1 HEMCO 3.0.0 milestone]
|
*Added in [[GEOS-Chem 13.0.0]]

|-valign="top"
|2.2.0
|03 Feb 2020
|
#[https://github.com/geoschem/geos-chem/pull/122 Implement dry run option.]
#[https://github.com/geoschem/geos-chem/issues/52 Add fixes to properly interpolate data with irregular timesteps.] 
#[https://github.com/geoschem/geos-chem-unittest/commit/56f5be31bbcc3a2393ce5574b08d5b29b9598fc0 Add logical switches for all inventories and datasets in HEMCO_Config.rc. Also added master switches for emissions data, meteorology fields, and chemistry input so fields will only be read when corresponding option is enabled in input.geos.]
#[https://github.com/geoschem/geos-chem/issues/140 Restore reading CHLR fields for marine POA simulations. These fields are now read in and processed by the sea salt extension when the marine POA option is enabled.]
#[https://github.com/geoschem/geos-chem/commit/453246b1c646274582212c351c3e004ed4d70583 Add fixes to HEMCO's time shift capability to properly accommodate units of year, month, day, hour, minute, and second and add checks to adjust date and timestamps so they fall within physical ranges.]
#[https://github.com/geoschem/geos-chem/commit/02677b3d6cc21c452705fdcd642d4557847c084b Add check to avoid running HEMCO for the end timestep of a simulation. This will avoid unnecessary file reads for the next timestamp.]
#[https://github.com/geoschem/geos-chem/commit/02677b3d6cc21c452705fdcd642d4557847c084b Add check to avoid running HEMCO twice on the first timestep. This will avoid duplicate file reads.]
#[https://github.com/geoschem/geos-chem/commit/99bfbc3e906f80e9330a07101d187640ad9c305d Read met fields daily instead of hourly to improve file I/O. The correct timestamp is selected in flexgrid_read_mod.F90.]
#[https://github.com/geoschem/geos-chem/commit/e8b9593a30743810bfdbae97c6244028320ac847 Add <tt>RFY3</tt> time cycle option to indicate data should be read every 3 hours at 0, 3, 6, 9, 12, 15, 18, and 21 UTC] (used for [[Grid-independent_emissions#Lightning_NOx_emissions|offline lightning fields]]).
#Switch to same [[GEOS-Chem_version_numbering_system#Numeric_versioning_system|version numbering scheme used in GEOS-Chem.]]
|
*Added in in [[GEOS-Chem 12#12.7.0|GEOS-Chem 12.7.0]]<br>(released 03 Feb 2020)

|-valign="top"
|v2.1.012
|01 Apr 2019
|
#[[#Bug fixes for HEMCO interpolation algorithm|Bug fixes for HEMCO interpolation algorithm]]
#[[#Updates from the NASA GEOS development branch|Updates from the NASA GEOS development branch]]
#[[#Add option to always use simulation year for specified fields|Add option to always use simulation year for specified fields]]
#[[#Prevent zero emissions for MEGAN_Mono extension species|Prevent zero emissions for MEGAN_Mono extension species]]
#[[#Updates to the volcanic emissions extension|Updates to the volcanic emissions extension]]
|
*Added in [[GEOS-Chem 12#12.3.0|GEOS-Chem 12.3.0]]

|-valign="top"
|v2.1.011
|19 Feb 2019
|
#[[#Update HEMCO standalone for compatibility with FlexGrid|Minor modifications to make the HEMCO standalone consistent with the FlexGrid met field entries in <tt>HEMCO_Config.rc</tt>]]
#[[#Wrap remaining HEMCO extensions in instances|Wrap remaining HEMCO extensions (GC_RnPbBe, GC_POPs, DustGinoux, and TOMAS_Jeagle) in instances for consistency with 12.1.009 updates]]
#[[#HEMCO standalone now calls HCO_RUN in two phases|HEMCO standalone now calls HCO_RUN in two phases]]
|
*Added in [[GEOS-Chem 12#12.2.0|GEOS-Chem 12.2.0]]

|-valign="top"
|v2.1.010
|05 Oct 2018
|
#[[#Bug fix: Read data with the "E" cycle flag just once|Bug fix: Read data with the "E" cycle flag just once]]
#[[#Add_fix_for_collapsing_model_levels_to_reduced_grid|Add fix for collapsing model levels to reduced grid]]
#[[#Fix_unit_conversion_in_HCO_UNIT_GetAreaScal|Fix unit conversion in HCO_UNIT_GetAreaScal]]
#[[GEOS-Chem_Output_Files#Read_restart_file_via_HEMCO|Add "CS" cycle flag to skip fields that aren't found]]
|
*Added in [[GEOS-Chem 12#12.1.0|GEOS-Chem 12.1.0]]

|-valign="top"
|v2.1.009
|13 Sep 2018
|
#Wrap HEMCO extensions into instances
|
*Added in [[GEOS-Chem 12#12.1.0|GEOS-Chem 12.1.0]]

|-valign="top"
|v2.1.008
|08 Aug 2018
|
#Bug fix: now respect range/exact flag for 1D values set in HEMCO configuration file
|
*Added in [[GEOS-Chem 12#12.1.0|GEOS-Chem 12.0.0]]

|-valign="top"
|v2.1.007
|18 Jul 2018
|
#[[#Fixed_error_in_HEMCO_.22exact.22_time_option|Fixed error in HEMCO "exact" cycling option]]
#[[#Stop with error if multiple containers have the same name|Stop with error if multiple containers have the same name]]
#[[#Bug fix for distributing emissions in the vertical dimension|Bug fix for distributing emissions in the vertical dimension]]
#[[#Add extra error checks in HEMCO standalone module|Add extra error checks in HEMCO standalone module]]
#[[#Remove null string character from netCDF unit string|Remove null string character from netCDF unit string]]
#[[#Bug_fix_for_HEMCO_soil_NOx_error_with_ifort_17|Bug fix for HEMCO soil NOx with ifort 17]]
|
*Added in [[GEOS-Chem 12#12.0.0|GEOS-Chem 12.0.0]]

|-valign="top"
|v2.1.006
|10 Jun 2018
|
#Update for the [[CH4 simulation|CH4 specialty simulation]]
#*CH4 emissions from wetlands now uses category #1
#*CH4 emissions from rice now uses category #2
#Added mol/mol to list of unitless quantities.
|
*Added in [[GEOS-Chem 12#12.0.0|GEOS-Chem 12.0.0]]

|-valign="top"
|v2.1.005
|27 Jan 2018
|
#Add option to emit into layer height read from netCDF file
|
*Added in [[GEOS-Chem v11-02#v11-02f|GEOS-Chem v11-02f]]

|-valign="top"
|v2.1.004
|30 Dec 2017
|
#Updates to remove possible issues / excessive print statements when operating in GEOS environment
#Fix possible tracer ID mismatch in sea salt extension
#Add option to normalize MEGAN LAI,HEMCO diagnostics
#Now write multiple time slices into one file
#Minor bug fixes
#[[#Avoid_segmentation_fault_in_DustGinoux_extension|Add an error trap in <tt>hcox_dustginoux_mod.F90</tt> to avoid a segmentation fault]]
#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.
|
*The dust extension fix was added in [[GEOS-Chem v11-02#v11-02c|GEOS-Chem v11-02c]]
*The fix for HEMCO reference time was added in [[GEOS-Chem v11-02#v11-02e|GEOS-Chem v11-02e]]
*The rest of the HEMCO updates were added in [[GEOS-Chem v11-02#v11-02f|GEOS-Chem v11-02f]]

|-valign="top"
|v2.1.003
|19 Jul 2017
|
#Normalize MEGAN LAI by PFT. This fix assumes the usage of [[MODIS_leaf_area_indices#0.25x0.25_MODIS_LAI_data|updated LAI input data]]
|
*Added in [[GEOS-Chem v11-02#v11-02f|GEOS-Chem v11-02f]]

|-valign="top"
|v2.1.002
|07 Jul 2017
|
#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.
|
*Added in [[GEOS-Chem v11-02#v11-02f|GEOS- Chem v11-02f]]

|-valign="top"
|v2.1.001
|16 May 2017
|
#[[GEOS-Chem_Output_Files#Enable_compression_in_netCDF-4_output_files|Enable data compression in netCDF-4 output files]]
#[[#Fixed_bug_in_computation_of_local_time_in_HCO_GetSuncos|Fix bug in computation of local time in routine <tt>HCO_GetSuncos</tt>]]
#[[#HEMCO diagnostic and restart files now have an unlimited time dimension|HEMCO diagnostic and restart files now have an unlimited time dimension]]
#[[#Now use YYYYMMDDhhmm format for time stamp values|All internal timestamp variables are now <tt>REAL*8</tt>, in order to be able to read netCDF time slices in <tt>YYYYMMDDhhmm</tt> format]].
#The option to defined species-specific scale factors that are applied across all inventories, categories, hierarchies, and extensions; 
#The option to use mathematical expressions (such as <tt>2.0 + sin(HH)</tt>), but none of them are used in the standard setup. 
#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.
#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).
#A corresponding feature has also been added in the [[GEOS-Chem Unit Tester]]:
##We have added a run directory for the [[The_HEMCO_User%27s_Guide#Stand-alone_interface|HEMCO standalone model]] to the [[GEOS-Chem Unit Tester]] in v11-02c and newer versions.  GEOS-Chem users can drop their <tt>HEMCO_Config.rc</tt> 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.
|
*Fixes #1-3 were added in [[GEOS-Chem v11-02#v11-02a|GEOS-Chem v11-02a]]
*The rest of the updates were added in [[GEOS-Chem v11-02#v11-02c|GEOS-Chem v11-02c]]

|-valign="top"
|v2.0.004
|26 Jan 2017
|
#Added a shadow variable for optional input argument in update_mixing_ratio in subroutine <tt>AIRQNT</tt> in <tt>dao_mod.F</tt>
#Added the passive tracer module
#[[GEOS-Chem_Output_Files#Improve_write_speed_of_netCDF_output_files|Improve write speed of netCDF output files]] (added to GEOS-Chem in [[GEOS-Chem_v11-01#v11-01_public_release|v11-01 public release]])
|
*Added in [[GEOS-Chem v11-02#v11-02a|GEOS-Chem v11-02a]]

|-valign="top"
|v2.0.003
|14 Oct 2016
|
#Added option <tt>DiagnRefTime</tt> to explicitly specify output diagnostics reference time unit. 
#[[#Fix missing pointer in call to HCO_CalcVertGrid|Fix missing pointer in call to HCO_CalcVertGrid]]
#[[#Fix_bug_preventing_HEMCO_from_writing_restart_files_more_than_once_per_run|Fix bug preventing HEMCO from writing restart files more than once per run]]
#Bug fix in <tt>hcox_paranox_mod.F90</tt> (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.
#The timezones mask file should be updated to file <tt>HEMCO/TIMEZONES/v2015-02/timezones_1x1.edit.nc</tt>
#: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.
#:<span style="color:green">'''''NOTE: [[#Ocean_grid_boxes_now_use_the_timezone_of_the_nearest_land_mass_for_computing_emissions|An improved method of assigning timezones to ocean grid boxes]] was implemented in the [[GEOS-Chem v11-01#v11-01 public release|v11-01 public release]].'''''</span>
#HEMCO v2.0.003 now accepts scale factors for extension fields. For example, to uniformly scale GFED_TEMP by a factor of 2:
#:<code>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 * <span style="color:red">1234</span> 1 1<br>... <br><span style="color:red">1234 GFED_TEMP_SCALE 2.0 - - - xy 1 1</span></code>
#: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).
#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:
#:<code>0 NO_MULTILEVELS 1.0 - - <span style="color:red">xyL=1:5</span> kg/m2/s NO – 1 1</code>
#: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 <tt>PBL</tt> for the planetary boundary layer. For example, the following are all legal:
#:<code>0 NO_MULTILEVELS 1.0 - - <span style="color:red">xyL=1:2500m</span>     kg/m2/s NO – 1 1  —> emits from surface level to 2500m<br>0 NO_MULTILEVELS 1.0 - - <span style="color:red">xyL=1000m:5000m</span> kg/m2/s NO – 1 1  —> emits from 1000m to 5000m<br>0 NO_MULTILEVELS 1.0 - - <span style="color:red">xyL=500m:17</span>     kg/m2/s NO – 1 1  —> emits from 500m to level 17<br>0 NO_MULTILEVELS 1.0 - - <span style="color:red">xyL=1:PBL</span>       kg/m2/s NO – 1 1  —> emits from surface level to PBL top</code>
#From a coding perspective the HEMCO state object (<tt>HcoState</tt>) now has to be passed to each routine. <tt>HcoState</tt> 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.
#Updated the [[HEMCO_examples#Passive_species|passive tracer code]] so that it works with the new species database.
|
*Fix #1 was added in [[GEOS-Chem v11-01#v11-01f|GEOS-Chem v11-01f]]
*Fixes #2-3 were added in [[GEOS-Chem v11-01#v11-01g|GEOS-Chem v11-01g]]
*The rest of the updates were added in [[GEOS-Chem v11-01 benchmark history#v11-01j|GEOS-Chem v11-01j]]

|-valign="top"
|v1.1.016
|14 Dec 2015
|
#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 (<tt>HEMCO_sa_Config.rc</tt>) 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:
#::<code>>>>include HEMCO_Config.rc</code>
#:This way, <tt>HEMCO_sa_Config.rc</tt> 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:
#::<code>./hemco_exe_gc.x HEMCO_sa_Config.rc</code>
#:where <tt>hemco_exe_gc.x</tt> 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 <tt>HEMCO_sa_Config.rc</tt> and <tt>HEMCO_Config.rc</tt>, HEMCO will use the one from <tt>HEMCO_sa_Config.rc</tt>. 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 <tt>HEMCO_sa_Config.rc</tt>):
#::<code>0    Base    : on *<br> --> NEI2011 : false</code>
#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):
#::<code>./hemco_exe_sa.x HEMCO_sa_Config.rc</code>
#: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:
#::<code>make -j4 EXTRA_FLAGS='–DGEOS_FP -DGRID4x5'</code>
|
*Added in [[GEOS-Chem v11-01 benchmark history#v11-01e|GEOS-Chem v11-01e]]

|-valign="top"
|v1.1.015
|07 Dec 2015
|
#Bug fix in GEOS5 -> GEOS-4 regridding
#Fixed a bug in syncing the MEGAN LAI_PREVDAY variable
|
*Added in [[GEOS-Chem v11-01 benchmark history#v11-01e|GEOS-Chem v11-01e]]

|-valign="top:
|v1.1.014
|23 Nov 2015
|
#Bug fix when interpolating/averaging between multiple files.
|
*Added in [[GEOS-Chem v11-01 benchmark history#v11-01e|GEOS-Chem v11-01e]]

|-valign="top"
|v1.1.013
|19 Nov 2015
|
#Allow mask grid points.
|
*Added in [[GEOS-Chem v11-01 benchmark history#v11-01e|GEOS-Chem v11-01e]]

|-valign="top"
|v1.1.012
|06 Nov 2015
|
#Treat MEGAN restart variables (historic surface temperature and radiation) as running averages
#Bug fix to make sure that sea salt aerosol calculations work on curvilinear grids
#Added DiagnTimeStamp to control diagnostics time stamp location
#Seaflux uses HEMCO landtypes instead of land fraction
#Bug fix: restrict day to last day of month when searching for file names.
|
*Added in [[GEOS-Chem v11-01 benchmark history#v11-01e|GEOS-Chem v11-01e]]

|-valign="top"
|v1.1.011
|14 Oct 2015
|
#Allow horizontal coordinates 'longitude' and 'latitude'
#Added time flags 'EF' and 'RF' to force exit if field not found for current simulation datetime
#Bug fix in seaflux extension: pull variables out of parallel loop.
|
*Added in [[GEOS-Chem v11-01 benchmark history#v11-01e|GEOS-Chem v11-01e]]

|-valign="top"
|v1.1.010
|22 Sep 2015
|
#HEMCO can now read any additional (arbitrary) dimension. The dimension index to be used has to be specified in the HEMCO configuration file.
|
*Added in [[GEOS-Chem v11-01 benchmark history#v11-01e|GEOS-Chem v11-01e]]

|-valign="top"
|v1.1.009
|10 Sep 2015
|
#Several bug fixes to allow specifying flexible diagnostics output frequencies.
|
*Added in [[GEOS-Chem v11-01 benchmark history#v11-01e|GEOS-Chem v11-01e]]

|-valign="top"
|v1.1.008
|13 Jul 2015
|
#Now make sure that Input_Opt%IDEP is of lenght NVEGTYPE and properly used in drydep_mod.F
#Bug fix in hcoi_standalone_mod: make sure that current date < simulation end date is properly calculated
#Make sure that negative emissions are correctly passed to hierarchy level diagnostics
#When reading a data field, check if diagnostics container with the same name exist and write data into it.
|
*Added in [[GEOS-Chem v11-01 benchmark history#v11-01e|GEOS-Chem v11-01e]]

|-valign="top"
|v1.1.007
|06 Jul 2015
|
#Grid edges can now be explicitly given in HEMCO standalone model
|
*Added in [[GEOS-Chem v11-01 benchmark history#v11-01e|GEOS-Chem v11-01e]]

|-valign="top"
|v1.1.006
|01 Jul 2015
|
#Aerocom, CH4, FINN, GFED, and soil NOx extensions now accept scale fields
#Bug fix: diagnostics update can now span multiple diagnostics levels
|
*Added in [[GEOS-Chem v11-01 benchmark history#v11-01e|GEOS-Chem v11-01e]]

|-valign="top"
|v1.1.005
|09 Jun 2015
|
#Now also build HEMCO standalone executable
#:The compilation of GEOS-Chem now also produces an executable for the HEMCO standalone code, located in <tt>HEMCO/Interfaces/hemco_standalone.x</tt>. 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.
#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.
#Add an extension (<tt>HEMCO/Extensions/hcox_aerocom_mod.F90</tt>) 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.
#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:
#:<code>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 xy<span style="color:green">'''L5'''</span> kg/m2/s NO  1/40/25/30  1 2</code>
#HEMCO will now recognize the unit strings <tt>%</tt> and <tt>percent</tt> 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:
#:<code>#==============================================================================<br># --- UV albedo, for photolysis (cf Hermann & Celarier, 1997) ---<br>#==============================================================================<br>(((+UValbedo+<br>* UV_ALBEDO $ROOT/UVALBEDO/v2015-03/uvalbedo.geos.2x25.nc UVALBD 1985/1-12/1/0 C xy <span style="color:green">'''percent'''</span> * - 1 1<br>)))+UValbedo</code>
# [[MEGAN_v2.1_plus_Guenther_2012_biogenic_emissions#Minor_bug_fix_in_MEGAN_Mono_extension|Bug fix to avoid out-of-bounds errors when the <tt>MEGAN_mono</tt> extension is turned off]]
# [[MEGAN_v2.1_plus_Guenther_2012_biogenic_emissions#Restore_missing_BIOGENIC_CO_diagnostics|Bug fix to restore archiving biogenic CO emissions from monoterpenes into the <tt>BIOGENIC_CO</tt> diagnostic]]
|
*Added in [[GEOS-Chem_v10-01_benchmark_history#v10-01-public-release|GEOS-Chem v10-01 public release]]

|-valign="top"
|v1.1.004
|20 May 2015
|
#The HEMCO standalone now works over nested domains.
#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.
#Base emissions can now have a dynamic number of scale factors (used to be limited to a fixed number).
#Fix bug in <tt>HCO_EmisAdd</tt> that prevented the FINN [biomass] diagnostics from being written. The problem only occurred when you passed a <tt>CAT=-1</tt> and <tt>HIER=-1</tt> to <tt>HCO_EmisAdd</tt>. I think that was only the case in FINN. This is now fixed.
#Add more flexibility to the definition of the vertical dimension in the HEMCO configuration file (attribute SrcDim). For example, you can use
#:*<tt>xy1</tt> to read only the first level of the input data
#:*<tt>xy25</tt> to read levels 1-25
#:*<tt>xy-1</tt> 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)
#:*<tt>xy-25</tt> 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!
#Update to the PARANOX code that gets rid of the PARANOX restart fields, and is more stable during run time. Both <tt>SUNCOS</tt> and <tt>SUNCOS - 5</tt> 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.:
#:<code>ncks –xv PARANOX_SUNCOS1,PARANOX_SUNCOS2,PARANOX_SUNCOS3,PARANOX_SUNCOS4,PARANOX_SUNCOS5 HEMCO_restart.201307010000.nc tmp.nc<br>mv tmp.nc HEMCO_restart.201307010000.nc</code>
#:Finally, the <tt>PARANOX_SUNCOS</tt> entries in <tt>HEMCO_Config.rc</tt> are not needed any more, and can be deleted:
#:<code><span style="color:red"># --- PARANOx restart variables<br>102 PARANOX_SUNCOS1 HEMCO_restart.$YYYY$MM$DD$HH00.nc PARANOX_SUNCOS1 $YYYY/$MM/$DD/$HH E xy 1 * - 1 1<br>102 PARANOX_SUNCOS2 HEMCO_restart.$YYYY$MM$DD$HH00.nc PARANOX_SUNCOS2 $YYYY/$MM/$DD/$HH E xy 1 * - 1 1<br>102 PARANOX_SUNCOS3 HEMCO_restart.$YYYY$MM$DD$HH00.nc PARANOX_SUNCOS3 $YYYY/$MM/$DD/$HH E xy 1 * - 1 1<br>102 PARANOX_SUNCOS4 HEMCO_restart.$YYYY$MM$DD$HH00.nc PARANOX_SUNCOS4 $YYYY/$MM/$DD/$HH E xy 1 * - 1 1<br>102 PARANOX_SUNCOS5 HEMCO_restart.$YYYY$MM$DD$HH00.nc PARANOX_SUNCOS5 $YYYY/$MM/$DD/$HH E xy 1 * - 1 1</span></code>
#:This update will create some differences compared to the previous code because all HEMCO <tt>SUNCOS</tt> values are now at the emission time step and not at the chemistry mid-point, e.g. HEMCO now consistently uses <tt>SUNCOS</tt> instead of a mix of <tt>SUNCOS</tt> and <tt>SUNCOSmid</tt>.  The latter has caused some confusion and could cause problems at high resolutions.

|
*Added in [[GEOS-Chem_v10-01_benchmark_history#v10-01-public-release|GEOS-Chem v10-01 public release]]

|-valign="top"
|v1.1
|16 Apr 2015
|
#Various updates to PARANOX:
##Bug fix in calculation of H2O ambient air concentration and the calculation of the current date SZA; 
##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); 
##Restored the ND63 diagnostics. For more information, see our [[Ship_emissions#Bug_fixes_for_the_PARANOX_HEMCO_extension|''Ship emissions'' wiki page]].
##The SUNCOS values for the previous 5 hours are now saved out to the HEMCO restart file.
#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.
#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.
#Masks update: Masks can now be treated as fractions (instead of binary values).
#Environmental fields update: Environmental fields used by HEMCO (stored in the <tt>ExtState</tt> 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.).
#Various updates to the HEMCO standalone code
#Modifications to on/off switches in the HEMCO configuration file
#*It is now possible to use extension names for the switches, e.g.:
#:<code>(((.not.ParaNOx<br>... etc...<br>))).not.ParaNOx</code>
#* You can now combine multiple switches by the word <tt>.or.</tt>, e.g.:
#:<code>(((.not.GFED.or.FINN<br>... etc ...<br>))).not.GFED.or.FINN</code>
|
*Added in [[GEOS-Chem_v10-01_benchmark_history#v10-01i|GEOS-Chem v10-01i]]

|-valign="top"
|v1.0
|07 Nov 2014
|
#Initial HEMCO release
#[[#Now_treat_OCPI.2C_OCPO.2C_BCPI.2C_and_BCPO_separately_in_HEMCO|Treat OCPI, OCPO, BCPI, and BCPO separately]]
#[[#Fix_for_segmentation_fault_when_emissions_are_turned_off|Fix segmentation fault when emissions are turned off]]
#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.
#:<code>ALK(I,J,L) = SSA(I,J) * AREA(I,J) * EMIS_TS</code>
#: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:
#:<code>ALK(I,J,L) = FRAC_OF_PBL(I,J,L) * SSA(I,J) * AREA(I,J) * EMIS_TS</code>
#:where <tt>FRAC_OF_PBL(I,J,L)</tt> makes sure that the total emitted SSA are distributed uniformly within the PBL.
#:This fix will affect the concentrations of SO4s and NITs.
#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).
#PARANOx now includes [[Ship_emissions#Updates_to_ship_NOx_chemistry|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 <tt>FracNOx table</tt> and <tt>IntOPE table</tt>):
#:<code>102     ParaNOx           : on    NO/NO2/O3/HNO3<br>--> LUT data format   :       nc<br>--> LUT source dir    :       $ROOT/PARANOX/v2015-02</code>
#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 <tt>GMI_LOSS_XXX</tt> and <tt>GMI_PROD_XXX</tt> fields. 
#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 <tt>TIMEZONES</tt> 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). 
#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 <tt>TIMEZONES</tt>).
#Non-emissions data update: It is now legal to set the extension number (<tt>ExtNr</tt>) in the configuration file to the wildcard character (<tt>*</tt>). 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.
#Horizontal regridding of index-based (e.g discrete) data is now done with the [[Regridding_in_GEOS-Chem#The_MAP_A2A_algorithm|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.
#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 <tt>WD</tt> time attribute should always be used for weekly data, e.g. the time stamp in the HEMCO configuration file should be set something like <tt>2000/1/WD/0</tt>, <tt>2005/1-12/WD/0</tt>, etc.
#Time indexing update: If you set the C/R/E flag in the configuration file to <tt>R</tt> (= range), the corresponding data will be used as long as the simulation date is within the time range provided via attribute <tt>sourceTime</tt> - 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:
#:<code>123 THIS_SCALE /path/to/file/file.nc VARIABLE 2007-2100/1/1/0 R xy 1 1</code>
#: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!). 
#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:
#:<code># ExtNr ExtName           on/off  Species<br>0       Base              : on    *<br>--> AEIC              :       true<br>--> BIOFUEL           :       true<br>--> BOND              :       true<br>etc.</code>
#: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: <tt>(((CollectionName</tt> to open a collection, <tt>)))CollectionName</tt> to close it. e.g.:
#:<code>(((AEIC<br>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<br>)))AEIC</code>
#:It is also possible to nest collections.
#It is now possible to assign multiple emission categories to one emission field, e.g. <tt>EMEP_NO</tt> 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).
#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.
#GEOS-Chem interface update: Slight updates to <tt>hcoi_gc_main_mod.F90</tt> so that it now contains a routine to perform some input data error checks (<tt>CheckSettings</tt>). 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 <tt>SHIPNO_BASE</tt> that should only be turned on if <tt>PARANOx</tt> is turned off. Likewise, I added a switch <tt>BOND_BIOMASS</tt> that must not be enabled if <tt>GFED3</tt> or <tt>FINN</tt> is being used.
#Emissions and dry deposition removal are now applied in one module: <tt>GeosCore/mixing_mod.F90</tt>. If [[Boundary_layer_mixing#VDIFF|the non-local PBL mixing is used]], mixing within the PBL is done in <tt>GeosCore/vdiff_mod.F90</tt> (called from within <tt>GeosCore/mixing_mod.F90</tt>), and all emissions above the PBL become added to the tracer array afterwards. If [[Boundary_layer_mixing#VDIFF|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 <tt>GeosCore/pbl_mix_mod.F90</tt>. Any emissions / dry deposition removals previously done in other parts of the code (<tt>GeosCore/calcrate.F</tt>, <tt>GeosCore/dust_mod.F</tt>, <tt>GeosCore/carbon_mod.F</tt>, etc.) are deactivated. The process flow in GEOS-Chem now looks like this (same for the non-local PBL and full-mixing scheme):
##Calculate PBL heights
##Convection
##Calculate dry deposition rates
##Calculate emissions rates
##Turbulence: this will apply emissions and dry deposition, plus non-local PBL mixing or full mixing.
##Chemistry
##Wet deposition
#:<span style="color:red">IMPORTANT NOTE: As a result of these updates, the ND44 dry deposition flux diagnostic (i.e. GAMAP category <tt>DRYD-FLX</tt>) is now archived in units of <tt>molec/cm2/s</tt> for all GEOS-Chem simulations.  In prior GEOS-Chem versions, some simulations such as [[Rn-Pb-Be simulation|the Rn-Pb-Be simulation]], the ND44 drydep fluxes were archived in units of <tt>kg/s</tt>.  '''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 <tt>molec/cm2/s</tt>.'''</span>
#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.
#Some bug fixes have been added to make sure that GEOS-Chem / HEMCO runs properly if emissions are disabled.
#Diagnostics updates:
##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.
##Similar to ND44, the emission fluxes added to GEOS-Chem are now written into a diagnostics. They are defined in <tt>GeosCore/diagnostics_mod.F90</tt> and filled in <tt>GeosCore/mixing_mod.F90</tt> and <tt>GeosCore/vdiff_mod.F90</tt>. This is for the DEVEL flag only.
#The Hermann & Celarier (1997) UV Albedo data&mdash;required by the [[FAST-JX v7.0 photolysis mechanism]]&mdash;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:
#:<code>#==============================================================================<br># --- UV albedo, for photolysis (cf Hermann & Celarier, 1997) ---<br>#==============================================================================<br>(((+UValbedo+<br>* UV_ALBEDO $ROOT/UVALBEDO/v2015-03/uvalbedo.geos.2x25.nc UVALBD 1985/1-12/1/0 C xy 1 * - 1 1<br>)))+UValbedo</code>
#:These data will be read for full-chemistry simulations or aerosol-only simulations in which chemistry is activated.  The <tt>+UValbedo</tt> collection will activated automatically by GEOS-Chem for these simulations.
#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. 
#It is now possible to include entire configuration files in the master HEMCO configuration file (<tt>HEMCO_Config.rc</tt>). This way, we can keep the HEMCO master configuration file more clear. Configuration files can be included with the statement:
#:<code>>>>include /path/to/ConfigFile/ConfigFile.rc</code>
#:I haven’t added yet any include statements to the master HEMCO configuration file <tt>HEMCO_Config.rc</tt>. I leave it up to you if we want to use that feature and which files to 'outsource' from <tt>HEMCO_Config.rc</tt>, but I think candidates include the StratChem files and the RCP data.
#It is now possible to use the token <tt>$CFDIR</tt> 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 <tt>/home/ckeller/HEMCO/emis/BROMINE/HEMCO_Config_BromoCarb.rc</tt> and contains an entry for file <tt>$CFDIR/Bromocarb_Liang2010.nc</tt>, the file path will be evaluated as <tt>/home/ckeller/HEMCO/emis/BROMINE/Bromocarb_Liang.2010.nc</tt>. This provides us with a possibility to store and exchange data along with the corresponding HEMCO configuration file snippets. 
#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 <tt>.not.</tt> in front of the collection name, e.g. <tt>.not.FINN_daily</tt>. This is useful to denote data that shall only be used if another collection is not enabled.
#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. <tt>hcox_soilnox_mod.F90</tt>. The module <tt>hco_restart_mod.F90</tt> contains the restart subroutines, and examples on how to use them can be found in <tt>hcox_soilnox_mod.F90</tt> or <tt>hcox_megan_mod.F</tt>.
#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. 
#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.
#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.
#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.
#All other changes are mostly low-level stuff or added functionality that shouldn’t really affect the benchmarks. These are:
##The HEMCO MEGAN extension is now in flexible precision.
##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. 
##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.
##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 [[Reading_binary_files_in_IDL#.22Big_Endian.22_vs._.22Little_Endian.22_byte_ordering|little endian / big endian binary file issues]].
##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. 

|
*Original HEMCO implementation added in [[GEOS-Chem_v10-01_benchmark_history#v10-01e|GEOS-Chem v10-01e]]
*Additional fixes added in [[GEOS-Chem_v10-01_benchmark_history#v10-01f|GEOS-Chem v10-01f]] and [[GEOS-Chem_v10-01_benchmark_history#v10-01h|GEOS-Chem v10-01h]]

|}

== Known issues ==

=== Issues in automatic unit conversion ===

The following issues are present in the current version of HEMCO.  We will take action to resolve these issues in future versions.

==== Issues caused by HEMCO not recognizing variations of the same unit strings ====

Xin Chen (U. Minnessota) reported unexpected HEMCO unit conversion behavior.  Lizzie Lundgren traced this to HEMCO not recognizing variations of kg/m2/s strings as the same.  

*If the unit strings in the netCDF file and in the <tt>HEMCO_Config.rc</tt> file are both the same (e.g. <tt>kg/m2/s</tt>, then no unit conversion is supposed to happen.  
*But if the unit string in the file is e.g. <tt>kg m-2 s-1</tt> and the unit in the <tt>HEMCO_Config.rc</tt> file is e.g. <tt>kg/m2/s</tt>, then HEMCO detects this as a difference in units, and will try to apply an automatic unit conversion that is really unnecessary.

This problem underscores the need to address the HEMCO automatic unit conversions ASAP.

==== Issues in unit conversions between kg and kgC ====

'''''Christoph Keller wrote:'''''

<blockquote>So the kg vs. kgC issue is indeed confusing and we are going to remove the auto-conversion in future versions. For now, HEMCO internally keeps everything in units of kg emitted species m-2 s-1.  For the seaflux extension, this is kg (DMS) m-2 s-1 for DMS, and kg (C) m-2 s-1 for ACET and ALD2.

When reading the emissions / surface concentrations from netCDF, HEMCO will try to convert all ACET/ALD2 emissions (or concentrations) to kg(C). If the emissions in the input file are already in kg(C), this should be specified in the HEMCO configuration file so that HEMCO won’t do the unit conversion anymore:</blockquote>

      101 ACET_SEAWATER   $ROOT/ACET/v2014-07/ACET_seawater.generic.1x1.nc ACET 2005/1/1/0    C xy kgC/m3 ACET - 1 1  (No unit conversion)

<blockquote>If, on the other hand, the input data is in kg/m3, then this should be specified accordingly in the configuration file and HEMCO will automatically convert it to kgC:</blockquote>

      101 ALD2_SEAWATER   $ROOT/ALD2/v2017-03/ALD2_seawater.geos.2x25.nc   ALD2 1985/1-12/1/0 C xy kg/m3  ALD2 - 1 1 (Will do unit conversion)

<blockquote>The same principles applies to the HEMCO diagnostics: the unit specified in the HEMCO diagnostics file (HEMCO_Diagn.rc) determines whether the diagnostics are converted from kgC to kg or not, i.e.:</blockquote>

      EMIS_ACET_OC_kg  ACET  101  -1 -1 2 kg/m2/s   (diagnostics is in kg(ACET) m-2 s-1)
      EMIS_ACET_OC_kgC ACET  101  -1 -1 2 kgC/m2/s  (diagnostics is in kg(C) m-2 s-1)

<blockquote>In general, I recommend avoiding any ‘automatic’ unit conversions and provide all inputs/outputs in kg(C) where possible and specify the units in the HEMCO configuration file accordingly. This will also ensure full compatibility with future versions of HEMCO.</blockquote>

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:59, 19 April 2019 (UTC)

=== Error when distributing emissions in the vertical ===

'''''Sally Wang wrote'''''

<blockquote>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 [[HEMCO_examples#Add_emissions_into_specific_levels|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:</blockquote>

      0 INJF_FLUX_FT  1.0e-10 - - - <span style="color:red">xyL=PBL:47</span> kg/m2/s INJF 258/1008 1 1
      0 INJF_FLUX_PBL 1.0e-10 - - - <span style="color:green">xyL=1:PBL</span>  kg/m2/s INJF 259/1008 1 1

<blockquote>The model failed to finish simulation and gave me this error message in HEMCO.log:</blockquote>

      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)

<blockquote>I have no idea why negative emission would show up.</blockquote>

'''''[[User:Bmy|Bob Yantosca]] replied:'''''

<blockquote>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.</blockquote>

<blockquote>I used the "out-of-the-box" settings the Rn-Pb-Be-Passive species simulation in my <tt>input.geos</tt> file.  I added these two lines (similar to yours) in my <tt>HEMCO_Config.rc</tt> to specify the passive species emissions flux:</blockquote>

      0 PASV_FLUX_1 1.0e-10 - - - <span style="color:green">xyL=1:PBL</span>  kg/m2/s PASV - 1 1
      0 PASV_FLUX_2 1.0e-10 - - - <span style="color:red">xyL=PBL:47</span> 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

<blockquote>I’ve traced the error to this parallel loop at approx. line 838 of <tt>HEMCO/Core/hco_calc_mod.F90</tt>.   A parallelization error (probably caused by variables that should be held <tt>PRIVATE</tt> but weren't) is causing the <tt>LowLL</tt> variable to not be set properly.  <tt>LowLL</tt> gets returned as -1, then this value is used as the level index for the <tt>BXHEIGHT_M</tt> field lower down in the module.</blockquote>

<blockquote>The quickest solution that I have is for you to disable the parallel loop at ~ line 838 of <tt>HEMCO/Core/hco_calc_mod.F90</tt>.  Add an extra comment character (<span style="color:green">!</span>) in front of each of the <tt>!$OMP</tt> statements there.</blockquote>

      <span style="color:green">!</span>!$OMP PARALLEL DO                                                      &
      <span style="color:green">!</span>!$OMP DEFAULT( SHARED )                                                &
      <span style="color:green">!</span>!$OMP PRIVATE( I, J, L, tIdx, TMPVAL, DilFact, LowLL, UppLL          ) & 
      <span style="color:green">!</span>!$OMP SCHEDULE( DYNAMIC )
      . . .
      <span style="color:green">!</span>!$OMP END PARALLEL DO                                                  

<blockquote>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.</blockquote>

<blockquote>We are looking into this issue and hope to have a fix shortly.</blockquote>

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|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]].

{| border=1 cellspacing=0 cellpadding=5 
|-bgcolor="#CCCCCC"
!width="175px"|Compiler
!width="375px"|Issue
!width="450px"|Status

|-valign="top"
|[[Intel Fortran Compiler]] v15
|Segmentation fault occurs when compiling with flags:<br><tt>-check bounds -O2</tt> 
|
*This is a known compiler bug in IFORT 15.  
*See [[HEMCO#IFORT_15_error_when_using_array-out-of-bounds_error_checking|this post on our ''HEMCO'' wiki page]] for more information.

|-valign="top"
|[[Intel Fortran Compiler]] v13<br>[[Intel Fortran Compiler]] v14
|Segmentation fault in HEMCO I/O module 
|
*We believe this is caused by a compiler bug in IFORT 12, IFORT 13, and IFORT 14.
*See [[HEMCO#IFORT_13.2FIFORT_14_segmentation_fault_error|this post on our ''HEMCO'' wiki page]] for more information.

|}

--[[User:Bmy|Bob Y.]] ([[User talk:Bmy|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-01 benchmark history#v10-01e|GEOS-Chem v10-01e]].  All of these issues have since been resolved.

=== Updates to the volcanic emissions extension ===

<span style="color:green">'''''This update (Git ID: [https://github.com/geoschem/geos-chem/commit/07c103190221e1d77feaa97dfdd71749767c248a 07c10319]) was added to HEMCO v2.1.012, which was included in [[GEOS-Chem 12#12.3.0|GEOS-Chem 12.3.0]] (release date 01 Apr 2019).'''''</span>

We have made the following updates to the extension that handles volcanic emissions:

#<p>We have renamed <tt>HEMCO/Extensions/hcox_aerocom_mod.F90</tt> to <tt>HEMCO/Extensions/hcox_volcano_mod.F90</tt>.  We now have the option of using either AeroCom or OMI volcano emissions data, so we have changed the name of the module accordingly.  Hopefully this should prevent confusion.</p>
#<p>Module routines within <tt>HEMCO/Extensions/hcox_volcano_mod.F90</tt> have likewise been renamed from <tt>HCOX_AeroCom_*</tt> to <tt>HCOX_Volcano_*</tt>.</p>
#<p>In <tt>HEMCO/Extensions/hcox_state_mod.F90</tt>, we have renamed the flag <tt>ExtState%Aerocom</tt> to <tt>ExtState%Volcano</tt>, to be consistent with the new name of the volcano extension.</p>
#<p>We have also fixed a bug: We now remove the <tt>MinDiagLev=2</tt> parameter from being passed to routine <tt>HCO_EmisAdd</tt>.  This was causing the degassing  and eruptive emissions to both be zero (because it was ignoring the category values).</p>
#<p>The <tt>--> Aerocom_Table</tt> setting in the <tt>HEMCO_Config.rc</tt> was renamed to <tt>--> Volcano_Table</tt>.</p>
#<p>One final fix: We corrected a typo in <tt>HEMCO/Extensions/hcox_paranox_mod.F90</tt>, where the flag <tt>ExtState%AeroCom</tt> was referenced.  This of course should have been <tt>ExtState%ParaNOx</tt>.  There should be no references to the Volcano extension from the ParaNOx extension.</p>

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:31, 21 March 2019 (UTC)

=== Prevent zero emissions for MEGAN_Mono extension species ===

<span style="color:green">'''''This update (Git ID: [https://github.com/geoschem/geos-chem/commit/af86c4ddc10e240662a572d8542292b2d30f5cc7 af86c4dd]) was added to HEMCO v2.1.012, which was included in [[GEOS-Chem 12#12.3.0|GEOS-Chem 12.3.0]] (release date 01 Apr 2019).'''''</span>

'''''[[User:Bmy|Bob Yantosca]] wrote:'''''

<blockquote>I have just discovered a bug in the <tt>HEMCO/Extensions/hcox_megan_mod.F</tt> module.  As it so happens, the biogenic emissions for the MEGAN monoterpene extensions were being computed with the wrong extension number.  I needed to replace the lines of code in <span style="color:red">RED</span> to with the lines of code in <span style="color:green">GREEN</span> in hcox_megan_mod.F:</blockquote>

         ! Add flux to emission array
         CALL HCO_EmisAdd( am_I_Root, HcoState, FLUXCO, Inst%IDTCO, 
     <span style="color:red">&                     RC,        ExtNr=Inst%ExtNr )</span>
     <span style="color:green">&                     RC,        ExtNr=Inst%ExtNrMono )</span>

and in similar locations where CO, LIMO, MTPA, MTPO, and SESQ emissions fluxes are added to the HEMCO state (via routine <tt>HCO_EmisAdd</tt>).

The image below shows biogenic emissions of CO from monoterpenes, before ("Ref") and after ("Dev") the fix was applied.  As you can see, before the fix, CO (and all the other MEGAN_Mono emitted species, omitted here) had zero biogenic emissions.  This has now been corrected.

[[Image:CO_Monoterp.png]]

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 20:33, 19 March 2019 (UTC)

=== Add option to always use simulation year for specified fields ===

<span style="color:green">'''''This update (Git ID: [https://github.com/geoschem/geos-chem-unittest/commit/23189032720058b34d7b8140aac52989cfe4c1ee 23189032]) was added to HEMCO v2.1.012, which was included in [[GEOS-Chem 12#12.3.0|GEOS-Chem 12.3.0]] (release date 01 Apr 2019).'''''</span>

This error is known to occur with [[GEOS-Chem 12#12.1.0|GEOS-Chem 12.1.0]] and higher versions.

'''''Anthony Y.H. Wong wrote:'''''

<blockquote>I use the v12.1.0 to run tropchem simulations that have to fix emission year. I used</blockquote>

      Emission year: 2016

<blockquote>in my <tt>HEMCO_Config.rc</tt> file.  The error message in HEMCO reads:</blockquote>
 
[[Image:Hemco_restart_error_fixed_emission_year_gc12.png]]
 
<blockquote>Once I deleted the line in HEMCO_Config.rc that specifies emission year, the model runs normally. That "1713" is apparently the source of the problem. Perhaps when GC restart files is read from HEMCO, somehow the emission time confuses the real time steps. Is there any solution to this problem?</blockquote>

'''''[[User:Melissa Payer|Melissa Sulprizio]] wrote:'''''

<blockquote>I think I may have found the problem. As you indicated, you have set a fixed emissions year in your HEMCO configuration file.  This will change the year for any file read in via HEMCO to the specified year. However, your restart file and the met fields that you want to use for your simulation are for July 2016. 

As a temporary fix, you can remove the <tt>$YYYY</tt> tokens from the <tt>GC_RESTART</tt> entries and the met field entries in <tt>HEMCO_Config.rc</tt> and manually set it to the year of your restart file (which is 2016). </blockquote>

'''''Christoph Keller wrote:'''''

<blockquote>The year used in HEMCO is handled by the HcoClock object. It carries three year values: <tt>Clock%ThisYear</tt> is the current 'emission year', <tt>Clock%PrevYear</tt> is the emission year of the previous time step, and <tt>Clock%SimYear</tt> is the current simulation year. <tt>Clock%SimYear</tt> and <tt>Clock%ThisYear</tt> are always identical except for cases where the emission year is fixed (via HEMCO_Config.rc). When reading a file, HEMCO always uses <tt>Clock%ThisYear</tt> as the reference year. But it sounds like for some files, we would want to use <tt>Clock%SimYear</tt> instead. This would have to happen in routine HCO_GetPrefTimeAttr (in hco_tidx_mod.F90) when the current year is obtained:</blockquote>

    ! Get current time
    CALL HcoClock_Get( am_I_Root, HcoState%Clock,                   &
                       cYYYY    = cYr, cMM = cMt, cDD = cDy,        &
                       cWEEKDAY = cWd, cH  = cHr, cM  = cMn, RC = RC )
    IF ( RC /= HCO_SUCCESS ) RETURN

<blockquote>Change to:</blockquote>

    ! Get current time
    CALL HcoClock_Get( am_I_Root, HcoState%Clock,                   &
                       cYYYY    = cYr, cMM = cMt, cDD = cDy,        &
                       cWEEKDAY = cWd, cH  = cHr, cM  = cMn, sYYYY = sYr, RC = RC )
    IF ( RC /= HCO_SUCCESS ) RETURN
 
    IF ( SOMETHING ) cYr = sYr

<blockquote>The question is what the determination for this switch should be (which I just called 'SOMETHING' above)? A more complicated, but more robust approach would be to specifically mark these files in HEMCO_Config.rc (e.g. by adding an attribute to the time flag) and then add a corresponding flag to the FileData derived type (let's say 'AlwaysUseSimYear'), which already contains a bunch of meta-data that goes with each input file. This flag would then determine whether to use cYr or sYr:</blockquote>

    IF ( Lct%Dct%Dta%AlwaysUseSimYear) cYr = sYr

As a permanent fix, we have added the `Y` option to the time cycle flag in HEMCO_Config.rc. Including this option will set `UseSimYear` to True in hco_config_mod.F90 which will in turn set <code>cYr = sYr</code> as suggested above. This option is now used for GC_RESTART, HEMCO_RESTART, and meteorology fields in HEMCO_Config.rc.

--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 20:18, 10 March 2019 (UTC)

=== Updates from the NASA GEOS development branch ===

<span style="color:green">'''''This update (Git ID: [https://github.com/geoschem/geos-chem/commit/fb093d61b8321834d5f1d9565760e2828138b321 fb093d61] ) was added to HEMCO v2.1.012, which was included in [[GEOS-Chem 12#12.3.0|GEOS-Chem 12.3.0]] (release date 01 Apr 2019).'''''</span>

'''''[[User:Lizzie Lundgren|Lizzie Lundgren]] wrote:'''''

<blockquote>There are updates to HEMCO within the GEOS branch that [[User:Christoph Keller|Christoph Keller]] gave the go ahead to put into the standard model. These are summarized as follows:

#The readlist counter now makes sure that HEMCO establishes all pointers before calculating the emissions for the first time. With the update to GEOS-Chem 12.0 there were some clock mismatches that would leave a bunch of HEMCO fields unassigned when running GEOS-Chem within GEOS. The readlist counter variable is a more robust way to determine the status of these fields.
#The second update is the ‘Cap time shift’ flag (to be set in HEMCO_Config settings, defaults to false). This fixes an issue that Andrew Schuh reported when he tried applying a 90 minute offset (2000-2016/1-12/1-31/0-23/+90minutes) to 3-hourly data, with the 8 fields from one day (0z,3z,…,21z) stored in the same netCDF file. Without the TimeShiftCap flag there was the issue that HEMCO would jump back to the 0z slice after 22.30z. The TimeShiftCap flag makes sure that HEMCO doesn’t jump across midnight.</blockquote>

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 21:26, 7 March 2019 (UTC)

=== Bug fixes for HEMCO interpolation algorithm ===

<span style="color:green">'''''This issue (Git ID: [https://github.com/geoschem/geos-chem/commit/e947fc8027b75eaa4ff5e22b65f046728b5ee7fb e947fc80]) was added to HEMCO v2.1.012, which was included in [[GEOS-Chem 12#12.3.0|GEOS-Chem 12.3.0]] (release date 01 Apr 2019).'''''</span>

A couple of bugs for the HEMCO interpolation algorithm have been corrected:

<u><strong>Issue #1:</strong></u>

'''''[[User:bmy|Bob Yantosca]] wrote:'''''

<blockquote>I am digging into the issue of how to make HEMCO’s time interpolation in GEOS-Chem "Classic" match the behavior the MAPL ExtData component in GCHP.  This came up during the implementation the MODIS LAI for GC 12.3.0.  ExtData interpolates accordingly:</blockquote>

      >> >> >>   Interpolated field XLAIMULTI between 20151215 000000 and 20160115 000000 (  0.548387 fraction)

<blockquote>(NOTE: The MODIS LAI data are tiemestamped on the 15th of the month.)  But if I use this type of entry in the GEOS-Chem "Classic" HEMCO_Config.rc file file:</blockquote>

      * XLAI00 MODIS_XLAI.025x025.$YYYY$MM.nc XLAI00 2005-2011/1-12/1-31/0 I xy cm2/cm2 * - 1 1

<blockquote>Then we get this output:</blockquote>

      Reading variable XLAI00
      HEMCO: Entering GET_TIMEIDX (hco_read_std_mod.F90) ( 6)
               # time slices found:              1
               # time slice range:  201102150000. 201102150000.
               preferred datetime:  201101010000.
                   selected tidx1:              1
          corresponding datetime 1:  201102150000.
              assigned delta t [h]:              0
          local time?  F
      HEMCO: Leaving GET_TIMEIDX (hco_read_std_mod.F90) ( 6)
      Interpolated data between two files:
      <span style="color:red">- File 1: MODIS_XLAI.025x025.201101.nc
        Time stamp used:    201101150000.000
        Applied weight:    1.000000
      - File 2: MODIS_XLAI.025x025.201102.nc
        Time stamp used:    201102150000.000
        Applied weight:   0.0000000E+00</span>

<blockquote>As you can see, HEMCO in GEOS-Chem "Classic" is trying to interpolate between Jan and Feb, but should instead be trying to interpolate between Dec and Jan.  Furthermore, it is giving all the weight to Jan.  This results in a mismatch when we compare the LAI data in GEOS-Chem "Classic" vs. GCHP.</blockquote>

'''''[[User:Christoph Keller|Christoph Keller]] replied:'''''

<blockquote>I think I figured this one out. There were two (independent) bugs in the interpolation procedure. One was related to how the weights were assigned to two given time stamps (subroutine <tt>GetWeights</tt> in <tt>HEMCO/Core/hcoio_read_std_mod.F90</tt>), and the other one was that interpolation would only work into the future, i.e. if the timestamp read from the first file was in the past (in your example the interpolation should go into the future). I added two fixes for this...and now it does this:</blockquote>

               # time slices found:              1
                # time slice range:  200707150000. 200707150000.
                preferred datetime:  200708010000.
                    selected tidx1:              1
          corresponding datetime 1:  200707150000.
              assigned delta t [h]:              0
      local time?  F
      HEMCO: Leaving GET_TIMEIDX (hco_read_std_mod.F90) ( 6)
      Interpolated data between two files:
      <span style="color:green">- File 1: MODIS_XLAI.025x025.200708.nc
          Time stamp used:    200708150000.000
          Applied weight:   0.5483871
      - File 2: MODIS_XLAI.025x025.200707.nc
          Time stamp used:    200707150000.000
          Applied weight:   0.4516129</span>

<u><strong>Issue #2:</strong></u>

'''''[[User:bmy|Bob Yantosca]] wrote:'''''

<blockquote>Running HEMCO past the leap year day 2016/02/29 gives this error, when reading the new Yuan et al 2011 LAI data:</blockquote>

      HEMCO: Opening /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/GEOS_4x5/GEOS_FP/2016/03/GEOSFP.20160301.I3.4x5.nc
      - Found all A1 met fields for 2016/02/29 23:30
      At line 2393 of file hcoio_read_std_mod.F90
      Fortran runtime error: Index '47' of dimension 1 of array 'availymdhm' above upper bound of 46

<blockquote>Adding this fix to routine <tt>GetIndex2Interp</tt> in <tt>HEMCO/Core/hcoio_read_std_mod.F90</tt> seems to fix the out-of-bounds error:</blockquote>

         ! If all of those tests failed, simply get the next time
         ! slice. 
         IF ( tidx2 < 0 ) THEN
            tidx2 = tidx1 + 1
 
            <span style="color:green">! Make sure that tidx2 does not exceed nTime, which is
            ! the number of time slices in the file. This can cause
            ! an out-of-bounds error. (bmy, 3/7/19)
            IF ( tidx2 > nTime ) tidx2 = nTime</span>
            ... etc ...

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 17:47, 25 February 2019 (UTC)

=== HEMCO standalone now calls HCO_RUN in two phases ===

<span style="color:green">'''''This update was included in [[GEOS-Chem 12#12.2.0|GEOS-Chem 12.2.0]], which was released on 19 Feb 2019.'''''</span>

In routine <tt>HCOI_Sa_Run</tt> (located in module in <tt>HEMCO/Interfaces/hcoi_standalone_mod.F90</tt>), we must now call <tt>HCO_Run</tt> 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.

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 13:05, 30 January 2019 (UTC)

=== Wrap remaining HEMCO extensions in instances ===

<span style="color:green">'''''This update was included in [[GEOS-Chem 12#12.2.0|GEOS-Chem 12.2.0]], which was released on 19 Feb 2019.'''''</span>

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.

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:47, 28 January 2019 (UTC)

=== Update HEMCO standalone for compatibility with FlexGrid ===

<span style="color:green">'''''This update was included in [[GEOS-Chem 12#12.2.0|GEOS-Chem 12.2.0]], which was released on 19 Feb 2019.'''''</span>

In HEMCO v2.1.011 (which will be introduced in [[GEOS-Chem 12#12.2.0|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 <tt>HEMCO/Interfaces/hcoi_standalone_mod.F90</tt> in order to be consistent with the FlexGrid met field definitions in the <tt>HEMCO_Config.rc</tt> configuration file.

NOTE: The HEMCO standalone in [[GEOS-Chem 12#12.1.0|GEOS-Chem 12.1.0]] and [[GEOS-Chem 12#12.1.1|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.

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 18:12, 22 January 2019 (UTC)

=== Fix unit conversion in HCO_UNIT_GetAreaScal ===

<span style="color:green">'''''This update (Git ID: [https://github.com/geoschem/geos-chem/commit/7dfd99da3d750046dc08478978b3f2cbd0a31018 7dfd99da]) was included in [[GEOS-Chem 12#12.1.0|GEOS-Chem 12.1.0]], which was released on 26 Nov 2018.'''''</span>

'''''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.

--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 12:05, 31 October 2018 (UTC)<br>--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:08, 26 November 2018 (UTC)

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

<span style="color:green">'''''This update (Git ID: [https://github.com/geoschem/geos-chem/commit/3f62e74954136cbbabda166a453cbd3811689ac4 3f62e749]) was included in [[GEOS-Chem 12#12.1.0|GEOS-Chem 12.1.0]], which was released on 26 Nov 2018.'''''</span>

This update does the following:

*If a file has the time cycle flag <tt>E</tt>, 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 <tt>E</tt> 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 <tt>TIMERS=1</tt> 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:

{| border=1 cellspacing=0 cellpadding=5 
|-bgcolor="#CCCCCC"
!width="100px"|Cycle Flag
!width="200px"|Name
!width="700px"|Description

|-valign="top"
|<tt>E</tt> || Exact || Fields are only used on the exact timestamp as requested in the <tt>HEMCO_Config.rc</tt> file.  The file will not be read again once it is found.
    
|-valign="top"
|<tt>EF</tt> || Exact / Forced || Same behavior as CycleFlag = <tt>E</tt>, but will stop the simulation with an error if the file is not found.

|-valign="top"
|<tt>EC</tt> || Exact / Continuous ||  Fields are only used on the exact timestep as requested in the <tt>HEMCO_Config.rc</tt>file.  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.

|-valign="top"
|<tt>ECF</tt> || Exact / Continuous / Forced || Same behavior as CycleFlag = <tt>EC</tt>, but will halt the simulation with an error if the file is not found.

|}

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:07, 26 November 2018 (UTC)

=== Add fix for collapsing model levels to reduced grid ===

<span style="color:green">'''''This update (Git ID: [https://github.com/geoschem/geos-chem/commit/820b8d7d9b25a50f79cf6688a359c9dcc91d8c2b 820b8d7d]) was included in [[GEOS-Chem 12#12.1.0|GEOS-Chem 12.1.0]], which was released on 26 Nov 2018.'''''</span>

There is a bug in the way HEMCO does the vertical interpolation for model levels. In routine <tt>ModelLev_Interpolate</tt> (in <tt>HEMCO/Core/hco_interp_mod.F90</tt>), 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 <tt>COLLAPSE</tt>, 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 <tt>ModelLev_Interpolate</tt> 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 <tt>G5_EDGE_NATIVE</tt> 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 + <span style="color:green">( NLEV-1 )</span>
 
   ! Thickness of output level
   THICK = EDG(1) - EDG(<span style="color:green">NLEV</span>)
 
   ! Get level weights
   ALLOCATE(WGT(NLEV))
   WGT = 0.0
   DO I = 1, <span style="color:green">NLEV-1</span>
      WGT(I) = ( EDG(I) - EDG(I+1) ) / THICK
   ENDDO

--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 16:53, 27 September 2018 (UTC)<br>--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:07, 26 November 2018 (UTC)

=== Fixed error in HEMCO "exact" time option ===

<span style="color:green">'''''This fix was included in [[GEOS-Chem 12#12.0.0|GEOS-Chem 12.0.0]].'''''</span>

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 <tt>HEMCO_Config.rc</tt> file:

 0 PASV_PLUME_FLUX 1.0 - <span style="color:red">2016/1/1/0 E</span> xyL=3000m kg/m2/s PASV 1000 1 1
 
 . . .
 
 1000 MASK_PLUME1 110/40/116/45 - <span style="color:red">2016/1/1/0 E</span> 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.

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:19, 9 August 2018 (UTC)

=== Stop with error if multiple containers have the same name ===

<span style="color:green">'''''This fix was included in [[GEOS-Chem 12#12.0.0|GEOS-Chem 12.0.0]].'''''</span>

HEMCO now stops with an error if multiple containers in <tt>HEMCO_Config.rc</tt> 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 HP|GEOS-Chem with the High-Performance option (aka GCHP)]].

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:37, 20 July 2018 (UTC)

=== Bug fix for distributing emissions in the vertical dimension ===

<span style="color:green">'''''This fix was included in [[GEOS-Chem 12#12.0.0|GEOS-Chem 12.0.0]].'''''</span>

'''''[[User:Christoph Keller|Christoph Keller]] wrote:'''''

<blockquote>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).</blockquote>

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 18:13, 19 July 2018 (UTC)

=== Add extra error checks in HEMCO standalone module ===

<span style="color:green">'''''This fix was included in [[GEOS-Chem 12#12.0.0|GEOS-Chem 12.0.0]].'''''</span>

When running a HEMCO standalone simulation, we discovered that that if the species number ID's are mis-indexed (in <tt>HEMCO_sa_Spec.rc</tt>), 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&mdash;especially for those species that involve unit conversions.
    
We have added several fixes to <tt>HEMCO/Interfaces/hco_standalone_mod.F90</tt> to avoid this situation.  We improve the algorithm for parsing the HEMCO standalone species file.  In addition, we now throw errors when

#The ID# of the first species read from the HEMCO species file is not 1; and
#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.

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 20:57, 18 July 2018 (UTC)

=== Remove null string character from netCDF unit string ===

<span style="color:green">'''''This fix was included in [[GEOS-Chem 12#12.0.0|GEOS-Chem 12.0.0]].'''''</span>

We have discovered a minor issue when HEMCO reads data into GEOS-Chem "Classic" (via module <tt>NcdfUtil/hcoio_read_std_mod.F90</tt>). Depending on now the netCDF file was written, the ASCII “NULL” character (<tt>\0</tt>, 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: <span style="color:red">g/m2/yr^@</span> vs. <span style="color:green">g/m2/yr</span>. File: .../HEMCO/DICE_Africa/v2016-10/DICE-Africa-cars-2013-v01-4Oct2016.nc                                                                  
 ### ThisUnit |<span style="color:red">g/m2/yr^@</span>|
 ### OrigUnit |<span style="color:green">g/m2/yr</span>|

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

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

(1) In routine <tt>NC_READ_VAR_CORE</tt>:

     ! 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     )
 
        <span style="color:green">! 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 (<nowiki>''</nowiki>). (bmy, 7/17/18)
        I = LEN_TRIM( VarUnit )
        IF ( ICHAR( VarUnit(I:I) ) == 0 ) THEN
           VarUnit(I:I) = <nowiki>''</nowiki>
        ENDIF</span>
     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)
 
        <span style="color:green">! 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 (<nowiki>''</nowiki>). (bmy, 7/17/18)
        I = LEN_TRIM( VarUnit )
        IF ( ICHAR( VarUnit(I:I) ) == 0 ) THEN
           VarUnit(I:I) = <nowiki>''</nowiki>
        ENDIF</span>
     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<span style="color:red">^@</span>|
 #### NC_READ_ARR last char before |<span style="color:red">^@</span>|
 #### 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.

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:15, 17 July 2018 (UTC)

=== Bug fix for HEMCO soil NOx error with ifort 17 ===

<span style="color:green">'''''This fix was included in [[GEOS-Chem 12#12.0.0|GEOS-Chem 12.0.0]].'''''</span>

'''''[[User:Jaf|Jenny Fisher]] wrote:'''''

<blockquote>I am having a really bizarre HEMCO error running [[GEOS-Chem v11-02#v11-02f|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 <tt>HEMCO.log</tt> file:</blockquote>

      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
 
<blockquote>So soil NOx is not being defined properly. I traced this through the HEMCO code and discovered that the issue is arising in <tt>HCO_GetExtHcoID</tt> in <tt>HEMCO/Core/hco_state_mod.F90</tt>. I’ve printed virtually everything here, and all looks good until this loop:</blockquote>

      ! Extract species information
      DO I = 1, nSpc
         SpcNames(I) = TRIM(SUBSTR(I))
         HcoIDs(I)   = HCO_GetHcoID( TRIM(SpcNames(I)), HcoState )
      ENDDO
 
<blockquote>If I print <tt>SUBSTR(I)</tt> in that loop, all looks good – it prints NO as expected.  However, if I print <tt>SpcNames(I)</tt> it comes up blank.  I even tried as a test manually assigning <tt>SpcNames(1)</tt> to be NO by adding the following before the HcoIDs line:</tt></blockquote>

      IF (ExtNr == 104) print*,'soil nox'
      IF (ExtNr == 104) SpcNames(1) = 'NO'
      print*,trim(spcnames(I))
      call flush(6)
 
<blockquote>My "soil nox" message gets printed, but <tt>SpcNames(I)</tt> still prints an empty string.
 
Note that none of the other species being read by HEMCO have any problem. I am compiling with <tt>DEBUG=yes BOUNDS=yes TRACEBACK=yes</tt>, 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 <tt>Inst%IDTNO = 1</tt> in <tt>hcox_soilnox_mod.F90</tt> – but this is clearly not an appropriate solution.</blockquote>

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:04, 26 June 2018 (UTC)

'''''[[User:bmy|Bob Yantosca]] replied:'''''

<blockquote>We have rewritten the offending DO loop in <tt>hco_state_mod.F90</tt> to hopefully be more friendly to compiler versions that exhibit some quirkiness when it comes to parsing strings:</blockquote>

   !
   ! !LOCAL VARIABLES:
   !
       INTEGER             :: I,      AS
       CHARACTER(LEN=255)  :: MSG,    LOC
       CHARACTER(LEN=2047) :: SpcStr, SUBSTR(255)
       <span style="color:green">CHARACTER(LEN=2047) :: TmpStr</span>
 
       . . .
 
       ! Extract species information
       DO I = 1, nSpc
          <span style="color:red">!---------------------------------------------------------------------
          ! 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 )
          !---------------------------------------------------------------------</span>
 
          <span style="color:green">! 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 )</span>
       ENDDO

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 13:52, 27 June 2018 (UTC)

=== Avoid segmentation fault in DustGinoux extension ===

<span style="color:green">'''''This update was included in [[GEOS-Chem v11-02#v11-02c|v11-02c]] and approved on 21 Sep 2017.'''''</span>

'''''Paolo Tuccella (L'Aquila) wrote:'''''

<blockquote>I have an issue running GEOS-Chem V11-01. When I run the model (<tt>merra2_2x25_soa</tt> configuration) with the <tt>DustGinoux</tt> dust emission scheme turned on in <tt>HEMCO_Config.rc</tt>, GEOS-Chem crashes with this message error:</blockquote>

      Program received signal SIGSEGV: Segmentation fault - invalid memory reference.

<blockquote>The error is occuring at line 395 of <tt>HEMCO/Extensions/hcox_dustginoux_mod.F90</tt>, where the emissions flux of alkalinity dust is updated. So, turning on <tt>DustAlk</tt> in <tt>HEMCO_Config.rc</tt>, the model run without errors.</blockquote>

'''''[[User:Bmy|Bob Yantosca]] replied:'''''

<blockquote>I’ve figured out the error.  So the <tt>DustGinoux</tt> extension is usually turned off by default in the standard simulations, which is why we didn’t find this earlier.  In the module the <tt>HEMCO/Extensions/hcox_dustginoux_mod.F</tt>, an error trap is lacking.  So we need to add the code in <span style="color:green">GREEN</span> to the existing IF statement at line 395:</blockquote>

       <span style="color:green">IF ( ExtNrAlk > 0 ) THEN</span>
          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
      <span style="color:green">ENDIF</span>

<blockquote>If the <tt>DustAlk</tt> extension is turned off, then the <tt>HcoIDsAlk</tt> array will be unallocated.  Therefore, to avoid [[Common_GEOS-Chem_error_messages#Segmentation_faults|a segmentation fault]], we need to avoid executing this block of code whenever <tt>DustAlk</tt> is turned off.</blockquote>

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 20:38, 7 July 2017 (UTC)

=== Now use YYYYMMDDhhmm format for time stamp values ===

<span style="color:green">'''''This update was included in [[GEOS-Chem v11-02#v11-02c|v11-02c]] and approved on 21 Sep 2017.'''''</span>

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

'''''Andy Jacobson (NOAA) wrote:'''''

<blockquote>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 </blockquote>

'''''[[User:Bmy|Bob Yantosca]] replied:'''''

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

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

*<tt>NcdfUtil/ncdf_mod.F90</tt>
*<tt>HEMCO/Core/hcoio_read_std_mod.F90</tt>

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

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 14:34, 12 April 2017 (UTC)

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

<span style="color:green">'''''This fix was included in [[GEOS-Chem v11-02#v11-02a|v11-02a]] and approved on 12 May 2017.'''''</span>

'''''Brian Boys wrote:'''''

<blockquote>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, <tt>DEP_RESERVOIR</tt>, 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.</blockquote>

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 <tt>4x5_standard</tt>) 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. 

'''''[[User:Christoph Keller|Christoph Keller]] wrote:'''''

<blockquote>We could add the default <tt>DEP_RESERVOIR</tt> field to the HEMCO configuration file and call it <tt>DEP_RESERVOIR_DEFAULT</tt>:</blockquote>

     104 DEP_RESERVOIR_DEFAULT    DepReservoirDefault.nc    DEP_RESERVOIR   2013/7/1/0 C xy kg/m3 NO – 1 1

<blockquote>And then read this file first and use it as default field when obtaining the soil NOx restart data (<tt>hcox_soilnox_run</tt> in <tt>hcox_soilnox_mod.F90</tt>):</blockquote>

     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 )

<blockquote>and then delete the <code>IF ( .NOT. FOUND )</code> statement right afterwards.

For <tt>DepReservoirDefault.nc</tt> we can simply extract <tt>DEP_RESERVOIR</tt> from the HEMCO restart file used for the benchmark simulation (using <tt>cdo selvar</tt>).</blockquote>

A file <tt>DepReservoirDefault.nc</tt> can now be found at

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

--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 13:58, 28 March 2017 (UTC)

=== Make anthropogenic emissions diagnostics 3D ===

<span style="color:green">'''''These fixes were included in [[GEOS-Chem v11-02#v11-02a|v11-02a]] and approved on 12 May 2017.'''''</span>

'''''[[User:Jaf|Jenny Fisher]] wrote:'''''

<blockquote>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 <tt>Diagn_Create()</tt> for ND36 in <tt>hcoi_gc_diagn_mod.F90</tt>, you do so with <tt>SpaceDim = 2</tt>. Is that correct? Is this perhaps a behaviour that should be changed in future as NEI11 is standard in v11-01?<br>

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?</blockquote>

--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 19:17, 22 March 2017 (UTC)

=== HEMCO diagnostic and restart files now have an unlimited time dimension ===

<span style="color:green">'''''This update was included in [[GEOS-Chem v11-02#v11-02a|v11-02a]] and approved on 12 May 2017.'''''</span>

'''''Andy Jacobson (NOAA) wrote:'''''

<blockquote>It would be convenient and [[Preparing data files for use with HEMCO|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 <tt>ncrcat</tt> 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 <tt>HEMCO/Core/hcoio_write_std_mod.F90</tt>:</blockquote>

<blockquote>(1) Add this line after the list of USE statements at the top of routine <tt>HCOIO_WRITE_STD</tt>:</blockquote>

      # include "netcdf.inc"

<blockquote>(2) Substitute <tt>NF_UNLIMITED</tt> for nTime in the calls to <tt>NC_CREATE</tt>.  Comment out the line in <span style="color:red">RED</span> and add the line in <span style="color:green">GREEN</span>:</blockquote>
                                                                             
      ! 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
 <span style="color:red">       !CALL NC_CREATE( ncFile, title, nLon,  nLat,  -1,     nTime,         &</span>
 <span style="color:green">        CALL NC_CREATE( ncFile, title, nLon,  nLat,  -1,     NF_UNLIMITED,  &</span>
                         fId,    lonId, latId, levId, timeId, VarCt,         &
                         CREATE_NC4=.TRUE. )
      ELSE
        <span style="color:red">!CALL NC_CREATE( ncFile, title, nLon,  nLat,  nLev,   nTime,         &</span>
        <span style="color:green"> CALL NC_CREATE( ncFile, title, nLon,  nLat,  nLev,   NF_UNLIMITED,  &</span>
                         fId,    lonId, latId, levId, timeId, VarCt,         &
                         CREATE_NC4=.TRUE. )
      ENDIF

<blockquote>Note that <code>nTime</code> was hard-coded to 1 already in this routine.  The <code>#include</code> is there only to get the symbol <code>NF_UNLIMITED</code>.  

It looks like this routine also writes the <tt>HEMCO_diagnostics.*.nc</tt> 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.</blockquote>

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 22:15, 8 March 2017 (UTC)

=== Fixed bug in computation of local time in HCO_GetSuncos ===

<span style="color:green">'''''This fix was included in [[GEOS-Chem v11-02#v11-02a|v11-02a]] and approved on 12 May 2017.'''''</span>

'''''[[User:Sebastian D. Eastham|Seb Eastham]] wrote:'''''

<blockquote>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 <tt>HCO_GetSUNCOS</tt> in <tt>HEMCO/Core/hco_geotools_mod.F90</tt>, HEMCO uses the local time to calculate the solar zenith angle <tt>SUNCOS</tt>. However, this has two issues:

#If no timezones are defined, then <tt>SUNCOS</tt> is artificially forced into 15 degree bands
#If timezones ARE defined, the <tt>SUNCOS</tt> becomes defined by political boundaries (see plot below, generated by pulling values directly from GEOS-Chem "Classic" with the new Voronoi timezones):

[[Image:HEMCO SUNCOS Error.PNG]]

It would be better to remove the call to <tt>HcoClock_GetLocal</tt> in routine <tt>HEMCO_GetSUNCOS</tt>.  This fix involves deactivating the code in <span style="color:red">RED</span> and activating the code in <span style="color:green">GREEN</span> as shown below:</blockquote>

      <span style="color:red">!-----------------------------------------------------------------------------
      ! 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
      !----------------------------------------------------------------------------</span>
 
               <span style="color:green">! Compute local time as UTC + longitude/15 (bmy, 3/2/17)
               LHR = HOUR + ( HcoState%Grid%XMid%Val(I,J) / 15.0_hp )</span>
               IF ( LHR <   0.0_hp ) LHR = LHR + 24.0_hp
               IF ( LHR >= 24.0_hp ) LHR = LHR - 24.0_hp

<blockquote>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.</blockquote>

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 17:20, 2 March 2017 (UTC)

=== Fixed bug in time interpolation in ncdf_mod.F90 ===

<span style="color:green">'''''This update was included in [[GEOS-Chem v11-01#v11-01 public release|GEOS-Chem v11-01 public release]]'''''</span>

'''''[[User:Sebastian D. Eastham|Seb Eastham]] wrote:

<blockquote>While doing final checks on base emissions sets in [[GEOS-Chem HP|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 <tt>I</tt>, 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 <tt>I</tt> to <tt>C</tt> 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 <tt>I</tt>, I found that the NOx emissions were about 50% lower than when using the option <tt>C</tt>.  Is this a known bug, or did I miss something?</blockquote>

'''''[[User:Christoph Keller|Christoph Keller]] replied:'''''
    
<blockquote>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 <tt>NcdfUtil/ncdf_mod.F90</tt>.</blockquote>

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 17:45, 10 January 2017 (UTC)

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

<span style="color:green">'''''This update was included in [[GEOS-Chem v11-01#v11-01 public release|GEOS-Chem v11-01 public release]]'''''</span>

'''''[[User:Sebastian D. Eastham|Seb Eastham]] wrote:'''''

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

[[Image: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:

<blockquote>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 <tt>_FillValues</tt> that become zero within HEMCO. As a quick fix I updated the timezones file [to <tt>HEMCO/TIMEZONES/v2015-02/timezones_1x1.edit.nc</tt> in [[#Features_added_in_v11-01j|v11-01j]]] to use a value of <tt>–5000</tt> in all ocean cells, which then forces HEMCO to determine the time zone based on longitude in those cells.</blockquote>

Please find a "nearest-cell" version of the HEMCO "timezones" file (<tt>HEMCO/TIMEZONES/v2015-02/timezones_voronoi_1x1.nc</tt>).  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:

[[Image:Timezones Voronoi.png]]
</blockquote>

The Voronoi timezones will be made the default HEMCO timezones in the [[GEOS-Chem v11-01#v11-01 public release|v11-01 public release]]. In the meantime, GEOS-Chem users may select this option by updating this entry in the <tt>HEMCO_Config.rc</tt> file.  Change the text in <span style="color:red">RED</span> 

 * TIMEZONES $ROOT/TIMEZONES/v2015-02/<span style="color:red">timezones_1x1.edit.nc</span> UTC_OFFSET 2000/1/1/0 C xy count * - 1 1

to the text in <span style="color:green">GREEN</span>:

 * TIMEZONES $ROOT/TIMEZONES/v2015-02/<span style="color:green">timezones_voronoi_1x1.nc</span> UTC_OFFSET 2000/1/1/0 C xy count * - 1 1

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 19:00, 4 January 2017 (UTC)

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

<span style="color:green">'''''NOTE: This update was included in [[GEOS-Chem v11-01#v11-01g|v11-01g]] (approved 28 Sep 2016).'''''</span>

'''''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 <tt>HEMCO/Core/hcoio_diagn_mod.F90</tt>:
    
       ! Only write diagnostics if this is the first Diagn_Get call for
       ! this container and time step.
       <span style="color:red">IF ( ThisDiagn%nnGetCalls > 1 ) CYCLE</span>
    
       ! 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.

--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 16:30, 30 August 2016 (UTC)

=== Fix missing pointer in call to HCO_CalcVertGrid ===

<span style="color:green">'''''NOTE: This update was included in [[GEOS-Chem v11-01#v11-01g|v11-01g]] (approved 28 Sep 2016).'''''</span>

We have found and fixed an error in routine <code>GridEdge_Set</code> (located in module <code>GeosCore/hcoi_gc_main_mod.F</code>), 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, <span style="color:red">PEDGE</span>, 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, <code>PEDGE</code> is never defined, but is nevertheless passed to <code>Hco_CalcVertGrid</code>, which is contained in module <code>HEMCO/Core/hco_geotools_mod.F90</code>. 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
 <span style="color:red">!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 HEMCO ERROR:  Wrong PEDGE array size:          255  -783173889  1988815368; should be:           
 72          46          48
 ERROR LOCATION: HCO_CalcVertGrid (hco_geotools_mod.F90)
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!</span>

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

To fix these issues, we have rewritten routine <code>GridEdge_Set</code> as follows.  Our new code is displayed in <span style="color:green">GREEN</span>.

 !
 ! LOCAL VARIABLES:
 !
     <span style="color:green">! Strings
     CHARACTER(LEN=80) :: MSG, LOC</span>
 
     ! 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
     !=======================================================================
 
     <span style="color:green">! 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)</span>
 
    ! 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                  )
 
    <span style="color:green">! 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</span>
 
    ! Nullify local pointers
    ZSFC     => NULL()
    BXHEIGHT => NULL()
    TK       => NULL()
    <span style="color:green">PSFC     => NULL()
 
    ! Deallocate and nullify PEDGE
    IF ( ASSOCIATED( PEDGE ) ) DEALLOCATE( PEDGE )
    PEDGE    => NULL()</span>
 
    ! Return w/ success
    RC       = HCO_SUCCESS

Therefore we now:

#Allocate an array to store pressure edge values (<code>PEDGE</code>), converted from hPa to Pa, and
#Add error traps to stop execution if
#*<code>PEDGE</code> cannot be allocated, or
#*<code>Hco_CalcVertGrid</code> exits abnormally.

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

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 14:44, 7 June 2016 (UTC)

=== Enable emissions in the stratosphere for specialty simulations ===

<span style="color:green">'''''This update was validated with [[GEOS-Chem_v11-01_benchmark_history#v11-01f|1-month benchmark simulation v11-01f]] and [[GEOS-Chem_v11-01_benchmark_history#v11-01f-geosfp-Run0|1-year benchmark simulation v11-01f-geosfp-Run0]]. This version was approved on 16 Apr 2016.'''''</span>

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.

--[[User:Lizzie Lundgren|Lizzie Lundgren]] ([[User talk:Lizzie Lundgren|talk]]) 15:15, 22 March 2016 (UTC)<br>--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:32, 30 March 2016 (UTC)

=== Fix for segmentation fault when emissions are turned off ===

In [[GEOS-Chem v10-01 benchmark history#v10-01g|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 <tt>input.geos</tt> file.

'''''[[User:Bmy|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 <span style="color:red">'''RED'''</span> line of code in routine <tt>GetHcoVal</tt> (in module file <tt>GeosCore/hcoi_gc_main_mod.F90</tt>):

     !=================================================================
     ! 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
 
     <span style="color:red">'''! HEMCO species ID corresponding to this GEOS-Chem tracer'''
     '''IF ( tID > 0 ) HcoID = M2HID(tID)%ID ID'''</span>

:The issue is that if you turn off HEMCO, then the <tt>M2HID</tt> 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. 

'''''[[User:Christoph Keller|Christoph Keller]] wrote:'''''

:I’ve updated my code so that HEMCO can be used with <tt>LEMIS = F</tt>. The changes are:
 
::1. In main.F, the HEMCO routines are now always called, even if <tt>LEMIS</tt> is set to <tt>FALSE</tt>. This ensures that HEMCO can still be used to read non-emission data such as the stratospheric Bry fields.
 
::2. In <tt>hcoi_gc_main_mod.F90</tt>, there are now two checks for the <tt>LEMIS</tt> flag: If <tt>LEMIS</tt> 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 (<tt>—> CALL SetExtNr(… )</tt>.
 
::3. Because all extensions are now automatically ignored when <tt>LEMIS</tt> 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 (<tt>GMI_StratChem</tt>) itself. If you prefer having the strat Bry fields listed in the extensions section, we can update the <tt>SetExtNr</tt> routine so that it doesn’t reset the extension number associated with <tt>GMI_StratChem</tt>. Just let me know if you’d prefer that solution.
 
::4. With <tt>LEMIS</tt> set to <tt>FALSE</tt>, 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 <tt>diag3.F</tt>, etc.).

--[[User:Bmy|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 [[GEOS-Chem_v10-01_benchmark_history#v10-01e|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:'''

'''''[[User:Jeff_Pierce|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 [http://ftp.as.harvard.edu/gcgrid/geos-chem/1mo_benchmarks/v10-01/v10-01e/v10-01e_trop/v10-01e_trop.ratios.pdf 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.

'''''[[User:Christoph Keller|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.

'''''[[User:Christoph Keller|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.

'''[[User:Jeff_Pierce|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.  

--[[User:Melissa Payer|Melissa Sulprizio]] 13:49, 20 November 2014 (EST)