Difference between revisions of "HEMCO"

From Geos-chem
Jump to: navigation, search
(Documentation: Add hEMCO 3.0 paper reference)
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Welcome to the Harmonized Emissions Component (HEMCO) homepage!
+
This content has been migrated to [https://hemco.readthedocs.io <tt>hemco.readthedocs.io</tt>].
 
+
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 has been implemented in GEOS-Chem, providing an ESMF-compatible interface for the emission inventories / extensions listed at the end of this page. Additional emission inventories and extensions can be readily added by individual users.
+
+
Please contact [http://www.ckeller.ch Christoph Keller] if you have any questions or would like to couple HEMCO to another model and/or ESMF environment.
+
 
+
== Description of HEMCO ==
+
 
+
=== Documentation ===
+
* Description paper: [http://www.geosci-model-dev.net/7/1409/2014/gmd-7-1409-2014.html Keller et al. (2014)]
+
* HEMCO 3.0.0+ description paper, with summary of previous HEMCO implementations and implementations into other models: [https://gmd.copernicus.org/articles/14/5487/2021/gmd-14-5487-2021.html Lin et al. (2021)]
+
* [https://hemco.readthedocs.io The HEMCO User's Guide] (HEMCO 3.0.0+, GEOS-Chem 13.0.0+)
+
* [[The HEMCO User's Guide]] (HEMCO 2.2.0 and earlier)
+
* [[HEMCO versions]]
+
 
+
=== Code availability / installation ===
+
The HEMCO source code is available as a free download from GitHub.com. Please see our [[HEMCO installation guide|''HEMCO installation guide'' wiki page]] for complete instructions on how to download and compile the HEMCO routines on your computer.
+
 
+
=== Frequently asked questions (FAQ) ===
+
 
+
*Can I use bpch data in HEMCO?
+
:Yes, if you convert it to netCDF format beforehand, e.g. using the GAMAP routine <tt>BPCH2COARDS</tt>. See our [[Preparing_data_files_for_use_with_HEMCO#Step_1:_Use_GAMAP_routine_BPCH2COARDS|''Preparing data files for use with HEMCO'' wiki page]] for more details.
+
 
+
=== Known Problems ===
+
Please report any problems to the HEMCO development team.
+
 
+
=== Contact ===
+
Do you have questions? Did you find a bug? Or do you have suggestions for improvement? Please get in touch with us:
+
 
+
*[[GEOS-Chem Support Team]]
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 19:56, 21 February 2020 (UTC)
+
 
+
== HEMCO in GEOS-Chem ==
+
 
+
Please see the following wiki pages for more information about the implementation of HEMCO in the GEOS-Chem model:
+
 
+
'''All GEOS-Chem users''' should read these documents:
+
#'''''[[The HEMCO User's Guide]]'''''.  This is the official technical reference document for HEMCO.
+
#'''''[[HEMCO data directories]]'''''.  This page contains a list of emissions inventories and other relevant atmospheric data sets for use with HEMCO.  It also contains instructions on how you can download these data to your server.
+
#'''''[[HEMCO examples]]'''''.  On this page we provide examples of how you can customize HEMCO for your particular emissions scenario.
+
#'''''[http://www.geosci-model-dev.net/7/1409/2014/gmd-7-1409-2014.html Keller et al 2014, GMD]'''''.  This article, published in ''Geoscience Model Development'', is the reference paper for HEMCO.
+
#'''''[[HEMCO versions]]'''''.  This wiki page contains basic information about HEMCO development history, and includes the GEOS-Chem version in which developments were added .
+
#'''''[[Removal of obsolete modules from GEOS-Chem]]'''''.  This wiki post lists all of the routines of GEOS-Chem's legacy emissions code that have been replaced by HEMCO.
+
 
+
'''Advanced GEOS-Chem users and core HEMCO developers''' should also read:
+
#'''''[[Interfacing HEMCO into GEOS-Chem]]'''''.  This wiki page contains information about:
+
#*How to [[Interfacing HEMCO into GEOS-Chem#Adding new HEMCO extensions into GEOS-Chem|create new HEMCO extensions for additional emissions inventories]]
+
#*How to [[Interfacing HEMCO into GEOS-Chem#HEMCO is implemented into GEOS-Chem as a git subtree|synchronize modifications]] made to HEMCO within GEOS-Chem back to the master HEMCO source code repository on Github.com.
+
#'''''[[Preparing data files for use with HEMCO]]'''''.  This wiki page contains information about
+
#*Creating data files for emissions and other data sets that adhere to the [http://ferret.wrc.noaa.gov/noaa_coop/coop_cdf_profile.html COARDS netCDF standard].
+
#*Converting data files from [http://acmg.seas.harvard.edu/gamap/doc/Chapter_6.html#6.2 binary punch format] to COARDS-compliant netCDF format.
+
 
+
--[[User:Bmy|Bob Y.]] ([[User talk:Bmy|talk]]) 15:30, 11 June 2015 (UTC)
+
 
+
== HEMCO as a standalone component ==
+
 
+
You can also run HEMCO independently of GEOS-Chem.  This is most often done to check if the scheduled emissions have been computed correctly before including them in a long GEOS-Chem simulation.  You can run HEMCO to compute emissions for several months or years in much less time than if you were to run a full GEOS-Chem simulation.
+
 
+
In [[GEOS-Chem v11-02]] and newer versions, a HEMCO standalone run directory will be added to the [[GEOS-Chem Unit Tester]].  Furthermore, the standard GEOS-Chem benchmarking procedure will include a long HEMCO standalone simulation to validate the emissions.
+
 
+
For more information, please see [[HEMCO_standalone|our ''HEMCO standalone'' wiki page]].
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 17:32, 22 May 2017 (UTC)
+
 
+
== Currently available emission inventories and extensions ==
+
 
+
Please see our [[HEMCO data directories|''HEMCO data directory'' wiki page]] for a complete list of all of the emissions inventories and other relevant data sets that can be used with HEMCO.  There you will also find [[HEMCO_data_directories#Downloading_the_HEMCO_data_directories|instructions for downloading these data to your local disk server]].
+
 
+
--[[User:Bmy|Bob Y.]] 17:31, 13 February 2015 (EST)
+
 
+
== Known issues ==
+
 
+
=== IFORT 15 error when using array-out-of-bounds error checking ===
+
 
+
<span style="color:red">'''''NOTE: This error also appears to occur with Intel Fortran Compiler 16.'''''</span>
+
 
+
If you compile HEMCO with the Intel Fortran Compiler version 15 (aka IFORT 15) with [[Common_GEOS-Chem_error_messages#Array-out-of-bounds_error|array-out-of-bounds]] error checking turned on (i.e. <tt>-check bounds</tt>), then you may encounter this error:
+
 
+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
%%%%%              HEMCO: Harmonized Emissions Component              %%%%%
+
%%%%%              You are using HEMCO version v1.1.005                  %%%%%
+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
HEMCO: Opening /mnt/gcgrid/data/ExtData/HEMCO/BIOFUEL/v2014-07/biofuel.geos.4x5.nc
+
HEMCO: Opening /mnt/gcgrid/data/ExtData/HEMCO/XIAO/v2014-09/C3H8_C2H6_ngas.geos.1x1.nc
+
<span style="color:red">forrtl: severe (408): fort: (2): Subscript #1 of the array LON2 has value 1 which is greater than the upper bound of -1</span>
+
 
+
Image              PC                Routine            Line        Source           
+
libifcoremt.so.5  00002B9EFA2188D3  Unknown              Unknown  Unknown
+
<span style="color:red">geos.mp            00000000011FCE35  regrid_a2a_mod_mp        1914  regrid_a2a_mod.F90</span>
+
libiomp5.so        00002B9EFB70A8A3  Unknown              Unknown  Unknown
+
 
+
The error happens in routine <tt>XMAP_R4R4</tt>, at line 1914 of module <tt>GeosUtil/regrid_a2a_mod.F90</tt>, which is highlighted in <span style="color:red">RED</span>.  HEMCO uses this module to regrid data (unless you are using the ESMF regridding capabilities).
+
+
! Reduce output grid
+
   
+
    lon2 => ilon2(n1:n2)
+
   
+
    ... several lines deleted for clarity ...
+
+
    !$OMP PARALLEL DO                                &
+
    !$OMP DEFAULT( SHARED                          ) &
+
    !$OMP PRIVATE( J, QTMP, I, I0, M, QSUM, MM, DX )
+
    do 1000 j=1,jm
+
     
+
        ... several lines deleted for clarity ...
+
+
        do 555 i=1,in
+
        do 100 m=i0,i2-1
+
 
+
          !=============================================================
+
          ! locate the western edge: lon2(i)
+
          !=============================================================
+
          <span style="color:red">if(lon2(i) .ge. x1(m) .and. lon2(i) .le. x1(m+1)) then</span>
+
+
When this code is compiled with IFORT 15 with the options <tt>-check bounds -O2</tt>, then for some unknown reason, the <tt>LON2</tt> pointer becomes undefined within the OpenMP parallel loop.  This causes the segmentation fault described above.  This behavior is due to a known bug in the optimizer in Intel Fortran Compiler version 15, and possibly also version 16.  Bob Yantosca has submitted an [https://software.intel.com/en-us/forums/topic/585242 official bug report to Intel Customer Service].
+
+
Therefore, if you are using IFORT15, you should turn off optimization if you are also using the array-out-of-bounds error check.  In other words, instead of using these compiler flags:
+
 
+
-check bounds -O2
+
 
+
then you should use these:
+
 
+
-check bounds -O0
+
 
+
For those of you who use HEMCO within GEOS-Chem, you can set the correct flags to avoid this issue with these Makefile options:
+
 
+
BOUNDS=y DEBUG=y
+
 
+
--[[User:Bmy|Bob Y.]] ([[User talk:Bmy|talk]]) 19:41, 25 August 2015 (UTC)
+
 
+
=== IFORT 13/IFORT 14 segmentation fault error ===
+
 
+
<span style="color:green">'''''The workaround suggested by Seb Eastham was included in [[GEOS-Chem v11-01#v11-01g|v11-01g]] (approved 28 Sep 2016).'''''</span>
+
 
+
<span style="color:red">'''''NOTE: The fix below applies to HEMCO version 1 (i.e. prior to [[GEOS-Chem#v11-01j|GEOS-Chem v11-01j]].  The [[HEMCO#Update:_Preventing_seg_fault_in_HEMCO_v2.0_caused_by_compiler_bug|following section]] contains information about how this issue was resolved for the latest HEMCO version 2.'''''</span>
+
 
+
<span style="color:darkorange">'''''NOTE: We have confirmed that this issue occurs when using Intel Fortran Compiler versions 12, 13, and 14.  Versions 15 and higher do not seem to be affected by this issue.'''''</span>
+
 
+
[[User:Jaf|Jenny Fisher]] reported a problem with HEMCO that may be caused by a compiler bug in the Intel Fortran Compiler, version 14 (aka IFORT 14).  She writes:
+
 
+
:I have been trying to compile/run v10 Hg simulation (GEOS-FP, 4x5) and running into seg faults. I thought this was the same problem we identified previously with the IFORT 15 compiler.  But...I saw that the above issue shouldn’t arise with IFORT 14 (which is what I’m using) so [I thought] it must be something else.
+
 
+
:I ran with traceback on but bounds off (i.e. <tt>TRACEBACK=y BOUNDS=n</tt>) and found the segfault is occurring in module <tt>HEMCO/Core/hcoio_dataread_mod.F90</tt> (see end of log file below).
+
 
+
:I turned on HEMCO verbose [in the <tt>HEMCO_Config</tt> file], but didn’t get any more information (last line was the same last file being read as seen in the log file).
+
 
+
:I add a print statement to the offending subroutine, and found that the problem is encountered when reading the ARTISANAL scaling factor. I don’t know enough about HEMCO’s set-up to get further, but here is what's in the config file (straight from the unit test directory):
+
 
+
    # --- Scale factors for artisanal and soil emissions ---
+
    1 ARTISANALSCALE 0.75 - - - xy 1 1
+
    2 SOILSCALE      0.5  - - - xy 1 1
+
    ### END SECTION SCALE FACTORS ###
+
 
+
:Log file output:
+
    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
    %%%%%              HEMCO: Harmonized Emissions Component              %%%%%
+
    %%%%%              You are using HEMCO version v1.1.005                  %%%%%
+
    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
    ...
+
    HEMCO: Opening /hpc/data/chemistry/CAC/GEOS_Chem/ExtData/HEMCO/MERCURY/v2014-09/NEI2005/CFPP_NEI2005_NPRI2005_Hg2.geos5.2x25.2005.nc
+
    forrtl: severe (174): SIGSEGV, segmentation fault occurred
+
    Image              PC                Routine            Line        Source           
+
    ...
+
    <span style="color:red">geos              0000000000ADDCF4  hcoio_dataread_mo        2810  hcoio_dataread_mod.F90</span>
+
    geos              0000000000AD84DE  hcoio_dataread_mo        2499  hcoio_dataread_mod.F90
+
    geos              0000000000AB8971  hco_readlist_mod_        438  hco_readlist_mod.F90
+
    geos              0000000000AB8398  hco_readlist_mod_        267  hco_readlist_mod.F90
+
    geos              0000000000AA99A6  hco_driver_mod_mp        138  hco_driver_mod.F90
+
    geos              0000000000844C07  hcoi_gc_main_mod_        546  hcoi_gc_main_mod.F90
+
    geos              0000000000801A2E  emissions_mod_mp_        172  emissions_mod.F90
+
    geos              00000000006720B7  MAIN__                    834  main.F
+
    ...
+
 
+
[[User:Sebastian_D._Eastham|Seb Eastham]] found that this error can occur with IFORT 13 too. He writes:
+
 
+
:I've found that this error can be reproduced with IFORT 13, as well. This was in a bleeding-edge clone of GC. I have no idea why it happens, given that it seems to happen on initiation of a DO loop with completely valid variables. I did a little bit of debugging before I found your entry, so I discovered that the bug goes away with either some extra compiler flags (e.g. <tt>DEBUG=yes FPE=yes BOUNDS=yes</tt>); alternatively, doing almost anything to modify the loop seems to prevent the compiler from getting upset. For example, I added the second line shown here in <span style="color:green">GREEN</span>:
+
 
+
      DO I = 1, NT
+
        <span style="color:green">WRITE( 6, '(a)', ADVANCE='no' ) <nowiki>''</nowiki></span>
+
        Lct%Dct%Dta%V2(I)%Val(1,1) = Vals(I)
+
      ENDDO
+
 
+
:and the segfault went away. I have no idea if this is a reliable fix, but it is at the very least completely benign. I also found that setting I=1 and performing the first entry in the loop manually, as follows:
+
 
+
      I=1
+
      Lct%Dct%Dta%V2(I)%Val(1,1) = Vals(I)
+
      DO I = 1, NT
+
          Lct%Dct%Dta%V2(I)%Val(1,1) = Vals(I)
+
      ENDDO
+
 
+
:seems to fix the problem without the noise but less benignly.
+
 
+
The GEOS-Chem Support Team believes that this error may be due to a compiler bug in IFORT13 and IFORT 14.  GCST has confirmed that this error does not occur when using older compiler versions (e.g. IFORT 11).
+
 
+
--[[User:Bmy|Bob Y.]] ([[User talk:Bmy|talk]]) 20:10, 25 August 2015 (UTC)<br>
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 16:24, 8 April 2016 (UTC)
+
 
+
==== Update: Preventing seg fault in HEMCO v2.0 caused by compiler bug ====
+
 
+
<span style="color:green">'''''This update was included in [[GEOS-Chem v11-01#v11-01 public release|GEOS-Chem v11-01 public release]]'''''</span>
+
 
+
When [[Implementation_of_HEMCO_in_GEOS-Chem#Features_added_in_v11-01j|HEMCO v2.0.003]] was introduced in [[GEOS-Chem v11-01#v11-01j|GEOS-Chem v11-01j]], the [[#IFORT_13.2FIFORT_14_segmentation_fault_error|workaround discussed in the above section]] was lost.
+
 
+
We have re-confirmed that an apparent optimization issue (probably caused by a compiler bug) in some versions of the [[Intel Fortran Compiler]] (such as ifort 12, 13, and 14), causes a segmentation fault in HEMCO that halts causes GEOS-Chem execution.  But the [[GNU Fortran compiler]] and [[PGI Fortran compiler]], as well as Intel Fortran 15 and higher, do not appear to be be affected by this issue.
+
 
+
The quick way to fix this issue is to insert a non-advancing <code>WRITE</code> statement, which somehow gets past the error.  We have added the <span style="color:green">code in GREEN</span> to line 3400 of module <tt>HEMCO/Core/hcoio_read_std_mod.F90</tt>:
+
 
+
    ! For base emissions and scale factors, interpret data as scalar
+
    ! values with a time dimension.
+
    ELSE
+
+
        CALL FileData_ArrCheck( HcoState%Config, Lct%Dct%Dta, 1, 1, NT, RC )
+
        IF ( RC /= HCO_SUCCESS ) RETURN
+
        DO I = 1, NT
+
          Lct%Dct%Dta%V2(I)%Val(1,1) = Vals(I)
+
<span style="color:green">!==============================================================================
+
! KLUDGE BY BOB YANTOSCA (05 Jan 2016)
+
!
+
! This WRITE statement avoids a seg fault in some Intel Fortran Compiler
+
! versions, such as ifort 12 and ifort 13.  The ADVANCE="no" prevents
+
! carriage returns from being added to the log file, and the <nowiki>''</nowiki> character
+
! will prevent text from creeping across the screen.
+
!
+
! NOTE: This section only gets executed during the initialization phase,
+
! when we save data not read from netCDF files into the HEMCO data structure.
+
! This type of data includes scale factors and mask data specified as vectors
+
! in the HEMCO configuration file.  Therefore, this section will only get
+
! executed at startup, so the WRITE statment should not add significant
+
! overhead to the simulation.
+
!
+
! The root issue seems to be an optimization bug in the compiler.
+
!==============================================================================
+
#if defined( LINUX_IFORT )
+
          WRITE( 6, '(a)', ADVANCE='no' ) <nowiki>''</nowiki>
+
#endif
+
 
+
Unlike the previous workaround, this <code>WRITE</code> statement is only activated when compiling GEOS-Chem with the [[Intel Fortran Compiler]].  Also, the <code>WRITE</code> statement will not add any unsightly lines to the screen or logfile output.
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 18:07, 5 January 2017 (UTC)
+
 
+
== References ==
+
 
+
#C. A. Keller, M. S. Long, R. M. Yantosca, A. M. Da Silva, S. Pawson, and D. J. Jacob, ''HEMCO v1.0: A versatile, ESMF-compliant component for calculating emissions in atmospheric models'', <u>Geosci. Model Devel. </u>, '''7''', 1409-1417, 2014. [http://www.geosci-model-dev.net/7/1409/2014/gmd-7-1409-2014.html (Article)]
+
#[[The HEMCO User's Guide]]
+
 
+
--[[User:Christoph Keller|C. Keller]] 08:17, 14 July 2014 (EST)
+
 
+
== Related wiki pages ==
+
 
+
We invite you to visit the following related wiki pages:
+
#[[GEOS-Chem HP]]
+
#[[Programming techniques for HPC environments]]
+
#[[Derived type objects used by GEOS-Chem]]
+
#[[HEMCO data directories]]
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 22:09, 6 January 2017 (UTC)
+

Latest revision as of 20:19, 4 August 2022

This content has been migrated to hemco.readthedocs.io.