HEMCO installation guide

From Geos-chem
Jump to: navigation, search

This wiki page is directed towards those of you who wish incorporate HEMCO into an atmospheric model other than GEOS-Chem, or who wish use HEMCO in standalone mode. The HEMCO source code is included as part of GEOS-Chem v10-01 and higher versions, and the HEMCO standalone executable is created along with the GEOS-Chem executable. If you are a GEOS-Chem user you will NOT need to download HEMCO separately.

Whether you use HEMCO as part of GEOS-Chem or not, you (or someone else at your institution) will need to download the HEMCO data directories to your local disk server.

— Bob Yantosca, 18 February 2015

On this page we provide instructions for downloading and installing the Harvard-NASA Emissions Component (HEMCO) source code.

Overview

Before you can use HEMCO, you must make sure that the following libraries and data directories are installed on your system:

Package Type Description
Git Version control
  • Git is used to download the HEMCO and NcdfUtilities packages.
  • A version of typicallly comes pre-installed on all builds of the the Linux, Ubuntu, Fedora, CentOS, etc. operating systems.
  • If your system doesn't have Git, ask your sysadmin or IT staff to install it for you. Git is free and open-source software.
GNU Make Building and installing code
  • A version of GNU Make ypically comes pre-installed all builds of the Linux, Ubuntu, Fedora, CentOS, etc. operating systems. You probably won't have to install this yourself.
Perl Scripting language
  • A version of Perl typically comes pre-installed on all builds of the Linux, Ubuntu, Fedora, Centos, etc. operating systems. You probably won't have to install this yourself.
Fortran Compiling source code
  • HEMCO currently supports the following compilers:
    • Intel Fortran Compiler (ifort), preferred
    • Portland Group Compiler (pgf90).
      • NOTE: There still may be issues with the Portland Group compiler. We are investigating.
netCDF I/O library
  • HEMCO reads data files in the netCDF format, and as such, needs to have a version of the netCDF libraries installed on your system.
  • netCDF-4 is preferred, but the older netCDF "classic" versions are OK too.
  • Check with your sysadmin to see if your system already has the netCDF library installed.
    • NOTE: If you need to install the netCDF libraries yourself, then you will also need to have C and C++ compilers on your system. Most versions of the Linux, Ubuntu, etc. operating systems will have the GNU C compilers gcc and g++ already pre-installed. See the Installing the netCDF libraries section below for more details.
HDF5 I/O library
  • All versions of netCDF-4.0 and higher require the HDF5 libraries.
  • But you do not need HDF5 if you are using earlier versions of netCDF.
  • Your system may already have a version of HDF5 pre-installed. Ask your sysadmin or IT staff to be sure.
NcdfUtilities I/O utility routines
  • This package contains Fortran utility routines for netCDF I/O.
  • It will be downloaded and installed as part of the HEMCO installation process.
HEMCO Emissions
  • This will be downloaded and installed as part of the HEMCO installation process.
HEMCO data directories Data files
  • This is the directory structure containing the various emissions data and scale factor files that HEMCO will read.
  • You can download these via anonymous FTP. See the Downloading the HEMCO emissions data section below.


The following sections discuss the HEMCO installation process in more detail.

--Bob Y. 16:52, 31 July 2014 (EDT)

Installing the netCDF libraries

This section describes how to install the netCDF library, which is required by HEMCO. But on many systems someone else may have already gone to the trouble of installing netCDF for you, thus sparing you the effort.

Check if your system already has netCDF installed

You can always ask your sysadmin or IT staff if netCDF has been installed on your system. But if your system uses the module command to load software packages, you can load a specific build of netCDF into your login environment. Follow these steps:

(1) First check to see if a netCDF library has already been loaded into your login environment. Type

module list

and you will get the list of all software modules that you are currently using. It should look something like this:

Currently Loaded Modulefiles:
  1) rocks/default-manpath     4) null                      7) compilers/pgi/7.0-7
  2) rocks/core                5) rocks/sge                 8) compilers/gcc/4.3.3
  3) seas/software             6) compilers/intel/11.1      9) mpi/openmpi/1.2.8/intel

As you can see from this example, your login environment isn't using a netCDF library installation. But this doesn't mean that netCDF is not installed on your system; all it means is that you haven't loaded it yet.

(2) To view a list of all of the available software packages on your system, type:

module avail

at the Unix prompt. Focus on the libraries section of the list. You should see several entries such as:

libraries/esmf/2.2.0rp1
libraries/ffmpeg/1.0
libraries/hdf5/1.8.6
libraries/libav/0.8.4
libraries/libvpx/1.1.0
libraries/mkl/10.0
libraries/mkl/11.0
libraries/mkl/11.1
libraries/netcdf/4.1.1

From this example, you see that the package libraries/netcdf/4.1.1—which is version 4.1.1 of the netCDF library—has already been installed and is available to use.

NOTE: All versions of netCDF version 4.0 and higher also require an HDF5 library installation. From the list above you can see that package libraries/hdf5/1.8.6 indicates that HDF5 version 1.8.6 is also available to use.

(3) Once you know that netCDF version 4.1.1 and HDF5 version 1.8.6 are available on your system, you can load them into your login environment. Type:

module load libraries/netcdf/4.1.1
module load libraries/hdf5/1.8.6
module list

and your list of loaded modules will now look like this:

Currently Loaded Modulefiles:
  1) rocks/default-manpath     5) rocks/sge                 9) mpi/openmpi/1.2.8/intel
  2) rocks/core                6) compilers/intel/11.1     10) libraries/netcdf/4.1.1
  3) seas/software             7) compilers/pgi/7.0-7      11) libraries/hdf5/1.8.6
  4) null                      8) compilers/gcc/4.3.3

You may also want to add the module load commands shown above into your .cshrc or .bashrc file, so that the netCDF library will be loaded automatically each time you log in to your system.

(4) Now that you have loaded the netCDF library into your login environment, you will need to know in which directory the library and include files live. Type:

printenv | grep NETCDF

and you will see the root directory path

NETCDFDIR=/software/linux/x86_64/netcdf-4.1.1

If you then type

ls $NETCDFDIR

you will see the following directory structure:

bin/  include/  lib/  share/

Which is arranged as follows:

  • The netCDF library files (libnetcdf.a, etc) are stored in $NETCDFDIR/lib
  • The netCDF include and module files (netcdf.inc, netcdf.mod) are stored in NETCDFDIR/include
  • The netCDF programs (nc-config, nf-config, ncdump, ncgen) are stored in NETCDFDIR/bin.

(5) In this example, because we are using netCDF-4, we also need to know where the HDF5 directory and library files are located. Type:

printenv | grep HDF5

and you will see the root directory path

 HDF5DIR=/software/linux/x86_64/hdf5-1.8.6

if you then type

ls $HDF5DIR

you will see the following directory structure:

bin/  include/  lib/  share/

Which is arranged as follows:

  • The HDF5 library files (libhdf5_hl.a libhdf5.a, etc) are stored in $HDF5DIR/lib
  • The HDF5 include and module files (*.h/tt>, <tt>*.mod) are stored in HDF5DIR/include
  • The HDF5 programs are stored in HDF5DIR/bin.

Now that you know where the netCDF (and also HDF5, if applicable) libraries are installed on your system, you can skip ahead to the Downloading the HEMCO emissions data section.

--Bob Y. 11:55, 18 July 2014 (EDT)

If you don't have already have netCDF, use the GEOS-Chem-Libraries installer

If your system does not have a version of the netCDF libraries installed, then you will have to install netCDF yourself. To simplify this process, we recommend using the GEOS-Chem-Libraries installation package. The GEOS-Chem-libraries package will download and install netCDF and its required libraries (HDF5, zlib, etc.) in one process. You can choose to install either netCDF-4.2 or the netCDF "classic" versions.

For complete instructions on how to use the GEOS-Chem-Libraries installer, please see our Installing libraries for GEOS-Chem wiki page.

NOTE: The GEOS-Chem-Libraries installer will place the netCDF and HDF library files into the same directory structure. We will need to keep this in mind when we set environment variables for HEMCO.

--Bob Y. 12:23, 18 July 2014 (EDT)

Setting environment variables for HEMCO installation

Once you have either loaded or built a version of netCDF, you must then set a few environment variables. These environment variables tell HEMCO where to look for the netCDF (and HDF5, if you are using netCDF-4) library files.

If netCDF and HDF5 were already installed on your system

Following the examples in the previous section, let's assume that netCDF and HDF5 has been installed into this directory:

/software/linux/x86_64/netcdf-4.1.1
/software/linux/x86_64/hdf5-1.8.6

(Your actual installation paths may differ, depending on the setup that your sysadmin or IT staff have implemented.)

For csh or tcsh

If your login environment uses the csh or tcsh Unix shells, then add these lines to your ~/.cshrc file:

setenv BIN_NETCDF /software/linux/x86_64/netcdf-4.1.1/bin
setenv INC_NETCDF /software/linux/x86_64/netcdf-4.1.1/include
setenv LIB_NETCDF /software/linux/x86_64/netcdf-4.1.1/lib
setenv BIN_HDF5   /software/linux/x86_64/hdf5-1.8.6/bin
setenv INC_HDF5   /software/linux/x86_64/hdf5-1.8.6/include
setenv LIB_HDF5   /software/linux/x86_64/hdf5-1.8.6/lib

and then type

source ~/.cshrc

to accept the changes.

--Bob Y. 10:30, 1 August 2014 (EDT)

For bash

If, on the other hand, your login environment uses the bash Unix shell, then add these lines to your .bashrc file:

export BIN_NETCDF=/software/linux/x86_64/netcdf-4.1.1/bin
export INC_NETCDF=/software/linux/x86_64/netcdf-4.1.1/include
export LIB_NETCDF=/software/linux/x86_64/netcdf-4.1.1/lib
export BIN_HDF5=/software/linux/x86_64/hdf5-1.8.6/bin
export INC_HDF5=/software/linux/x86_64/hdf5-1.8.6/include
export LIB_HDF5=/software/linux/x86_64/hdf5-1.8.6/lib

and type

source ~/.bashrc

to accept the changes.

--Bob Y. 16:53, 31 July 2014 (EDT)

If you used the GEOS-Chem-Libraries installer to build netCDF and HDF5

If you used the GEOS-Chem-Libraries installer to build the netCDF and HDF5 libraries, you were directed to set the GC_BIN, GC_INCLUDE, and GC_LIB environment variables in your .cshrc or .bashrc file as described here. You can use these settings to define the environment variables for HEMCO.

For csh or tcsh

If your login environment uses the csh or tcsh Unix shells, then add these lines to your ~/.cshrc file:

setenv BIN_NETCDF $GC_BIN
setenv INC_NETCDF $GC_INCLUDE
setenv LIB_NETCDF $GC_LIB
setenv BIN_HDF5   $GC_BIN
setenv INC_HDF5   $GC_INCLUDE
setenv LIB_HDF5   $GC_LIB

and then type

source ~/.cshrc

to accept the changes.

--Bob Y. 10:30, 1 August 2014 (EDT)

For bash

If your login environment uses the bash Unix shell, then add these lines to your ~/.bashrc file:

export BIN_NETCDF=$GC_BIN
export INC_NETCDF=$GC_INCLUDE
export LIB_NETCDF=$GC_LIB
export BIN_HDF5=$GC_BIN
export INC_HDF5=$GC_INCLUDE
export LIB_HDF5=$GC_LIB
export HEMCO_DATA_ROOT=/data/emissions/HEMCO

and then type

source ~/.bashrc

to accept the changes.

--Bob Y. 12:38, 18 July 2014 (EDT)

Installing HEMCO and the NcdfUtilities packages

Once you have installed the netCDF (and HDF5, if necessary) library files and defined the necessary environment variables, you may install the HEMCO source code.

Get the HEMCO installer

The first step is to download the HEMCO installer. Type the following at the Unix prompt:

git clone https://github.com/christophkeller/hemco_standalone_full

This will download a directory named hemco_standalone_full. If you then type:

cd hemco_standalone_full
ls

You will see the following contents:

 Makefile  README

The Makefile governs the entire build process. By default, the installer will build NcdfUtilities and HEMCO in subdirectories of hemco_install/. You can also copy or move the Makefile to another directory if you wish to build HEMCO and NcdfUtilities in a different location.

--Bob Y. 10:31, 1 August 2014 (EDT)

Build NcdfUtilities and HEMCO

To build both NcdfUtilities and HEMCO in one fell swoop, type:

make all >& log

This starts the following processes:

  1. Compiles the NcdfUtilities source code into libraries
  2. Creates the NcdfUtilities Reference Guide in PDF format
  3. Runs a short test to ensure the NcdfUtilities were installed properly
  4. Compiles the HEMCO source code into libraries
  5. Creates the HEMCO Reference Guide in PDF format
  6. Runs a short simulation (1 day, with a few species) to test that HEMCO was installed properly

and sends the output to a log file.

You can also choose to install NcdfUtilities and HEMCO in two separate steps, by typing:

make all_ncu >& log
make all_hemco >>&log

In either case, if the installation was successful, you should see the following output near the end of the log file:

cd ./example1; ./hemco_standalone.x "HEMCO_sa_Config.rc"
 
Reading part 1+2 of HEMCO configuration file: HEMCO_sa_Config.rc
Calculate emissions at 2008-01-01 00:00:00
HEMCO: Opening ./data/v42_CO_2008_TOT.0.1x0.1.nc
HEMCO: Opening ./data/EMEP_mask.geos.1x1.nc
HEMCO: Opening ./data/EMEP.generic.1x1.nc
 Calculate emissions at 2008-01-01 01:00:00
 Calculate emissions at 2008-01-01 02:00:00
 Calculate emissions at 2008-01-01 03:00:00
 Calculate emissions at 2008-01-01 04:00:00
 Calculate emissions at 2008-01-01 05:00:00
 Calculate emissions at 2008-01-01 06:00:00
 Calculate emissions at 2008-01-01 07:00:00
 Calculate emissions at 2008-01-01 08:00:00
 Calculate emissions at 2008-01-01 09:00:00
 Calculate emissions at 2008-01-01 10:00:00
 Calculate emissions at 2008-01-01 11:00:00
 Calculate emissions at 2008-01-01 12:00:00
 Calculate emissions at 2008-01-01 13:00:00
 Calculate emissions at 2008-01-01 14:00:00
 Calculate emissions at 2008-01-01 15:00:00
 Calculate emissions at 2008-01-01 16:00:00
 Calculate emissions at 2008-01-01 17:00:00
 Calculate emissions at 2008-01-01 18:00:00
 Calculate emissions at 2008-01-01 19:00:00
 Calculate emissions at 2008-01-01 20:00:00
 Calculate emissions at 2008-01-01 21:00:00
 Calculate emissions at 2008-01-01 22:00:00
 Calculate emissions at 2008-01-01 23:00:00
 HEMCO_STANDALONE FINISHED!

This output indicates that the installation process was able to build HEMCO properly and to run a short test simulation. The output of the test simulation is stored in the file HEMCO/examples/example1/HEMCO_sa.diagnostics.201307010000.nc. You can view the contents of this file with any netCDF reader (ncview, panoply, etc.).

--Bob Y. 15:20, 18 July 2014 (EDT)

Compile with additional compiler flags

Default behavior of the HEMCO standalone code is to compile with no user-defined compiler flags. This is good enough for most applications. However, users who want to use GEOS input data (e.g. GEOS-FP meteorological fields for lightning NOx calculation) may wish to add the GEOS_FP compiler flag to enable enhanced vertical regridding capabilities (e.g. regridding from the full 72 levels onto 47 reduced vertical levels). This can be done by passing GEOS_FP as an extra flag to the make command:

make all EXTRA_FLAGS=-DGEOS_FP >& log

You may need to clean your build first

make realclean

Note: this feature is only available in HEMCO v1.1.010 and higher.

Where did everything get installed?

NcdfUtilities directory structure:

Directory Contents
NcdfUtil/ Root directory for the NcdfUtilities package.
NcdfUtil/Code Contains the NcdfUtilities source code.
NcdfUtil/bin Contains the TestNcdfUtilities.x executable file. This will be built when you type make check.
NcdfUtil/doc Contains scripts that are used to create the NcdfUtilities Reference Guide (in PDF format).
NcdfUtil/lib Contains the NcdfUtilities library file (libNcUtils.a), which is created by the Fortran compiler.
NcdfUtil/mod Contains module files (*.mod), which are created by the Fortran compiler will be sent here.
NcdfUtil/perl Contains Perl scripts that can be used to write Fortran calls to the NcdfUtilities routines. (Not used for HEMCO.)


HEMCO directory structure:

Directory Contents
HEMCO/ Root directory for the HEMCO package.
HEMCO/bin Contains the executable file (hemco_standalone.x). This gets sent here when you type make check.
HEMCO/doc Contains makefiles and scripts used to build the HEMCO Reference guide in PDF format.
HEMCO/examples/example1 Contains output from the example simulation that validates the HEMCO installation.
HEMCO/ext Contains extra utiltity routines that HEMCO relies upon., including
  • String-handling functions
  • Time-and-date functions
  • Regridding functions
HEMCO/help Contains the Makefile for the HEMCO help screen. This is displayed when you type make help from the main HEMCO/ directory.
HEMCO/lib Contains the HEMCO library files (libHCO*.a), which are created by the Fortran compiler.
HEMCO/mod Contains the HEMCO module files (*.mod), which are created by the Fortran compiler.
HEMCO/run Contains the hemco_standalone.F90 program. When you type make check, this program is compiled into the executable file hemco_standalone.x. A short HEMCO simulation is then done to ensure that the HEMCO code was built properly.
HEMCO/src/ Contains subdirectories for HEMCO source code routines.
HEMCO/src/Core Contains source code for the "HEMCO core" functions. These handle data I/O, timing, and regridding.
HEMCO/src/Extensions Contains source code for "HEMCO extensions". HEMCO extensions are used for emissions that rely on physical parameters, such as meteorological data or other specialized inputs.
HEMCO/src/Interfaces Contains source code for "HEMCO interfaces". These are "bridges" that connect HEMCO to different atmospheric models (such as GEOS-Chem). There is also a "bridge" to allow HEMCO to run in a standalone mode, independent of any atmospheric model.

--Bob Y. 10:35, 1 August 2014 (EDT)

Setting additional environment variables after the HEMCO installation finishes

The HEMCO installation process will display the following text at the very end of the log file:

###########################################################
###       Environment Variable Settings for HEMCO       ###
###########################################################

If your login environment uses csh or tcsh:
-------------------------------------------
setenv BIN_NETCDF /opt/GEOS-Chem-Libraries/ifort/nc4/bin
setenv INC_NETCDF /opt/GEOS-Chem-Libraries/ifort/nc4/include
setenv LIB_NETCDF /opt/GEOS-Chem-Libraries/ifort/nc4/lib
setenv BIN_HDF5   /opt/GEOS-Chem-Libraries/ifort/nc4/bin
setenv INC_HDF5   /opt/GEOS-Chem-Libraries/ifort/nc4/include
setenv LIB_HDF5   /opt/GEOS-Chem-Libraries/ifort/nc4/lib
setenv NCU_BIN    /home/bmy/S/hemco_install/NcdfUtil/bin
setenv NCU_LIB    /home/bmy/S/hemco_install/NcdfUtil/lib
setenv NCU_MOD    /home/bmy/S/hemco_install/NcdfUtil/mod
setenv HCO_BIN    /home/bmy/S/hemco_install/HEMCO/bin
setenv HCO_LIB    /home/bmy/S/hemco_install/HEMCO/lib
setenv HCO_MOD    /home/bmy/S/hemco_install/HEMCO/mod

If your login environment uses bash:
-------------------------------------------
export BIN_NETCDF=/opt/GEOS-Chem-Libraries/ifort/nc4/bin
export INC_NETCDF=/opt/GEOS-Chem-Libraries/ifort/nc4/include
export LIB_NETCDF=/opt/GEOS-Chem-Libraries/ifort/nc4/lib
export BIN_HDF5=/opt/GEOS-Chem-Libraries/ifort/nc4/bin
export INC_HDF5=/opt/GEOS-Chem-Libraries/ifort/nc4/include
export LIB_HDF5=/opt/GEOS-Chem-Libraries/ifort/nc4/lib
export NCU_BIN=/home/bmy/S/hemco_install/NcdfUtil/bin
export NCU_LIB=/home/bmy/S/hemco_install/NcdfUtil/lib
export NCU_MOD=/home/bmy/S/hemco_install/NcdfUtil/mod
export HCO_BIN=/home/bmy/S/hemco_install/HEMCO/bin
export HCO_LIB=/home/bmy/S/hemco_install/HEMCO/lib
export HCO_MOD=/home/bmy/S/hemco_install/HEMCO/mod
make[1]: Leaving directory `/home/bmy/S/hemco_install'

This is a list of important environment variables that you can use to help HEMCO (or software that relies on HEMCO) to find the proper include or library files. In a previous section, you were directed to add these to your ~/.cshrc or ~/.bashrc file:

BIN_NETCDF  --> Points to the bin/     subdirectory of the netCDF library installation
INC_NETCDF  --> Points to the include/ subdirectory of the netCDF library installation
LIB_NETCDF  --> Points to the lib/     subdirectory of the netCDF library installation
BIN_HDF5    --> Points to the bin/     subdirectory of the HDF5   library installation
INC_HDF5    --> Points to the include/ subdirectory of the HDF5   library installation
LIB_HDF5    --> Points to the lib/     subdirectory of the HDF5   library installation

Because HEMCO relies on the NcdfUtilities package, it will need to be told where it can find the NcdfUtilities library and module files. These are specified with the following environment variables:

NCU_BIN     --> Points to the NcdfUtil/bin/ directory
NCU_LIB     --> Points to the NcdfUtil/lib/ directory
NCU_MOD     --> Points to the NcdfUtil/mod/ directory

Also, any software that you write that relies on HEMCO will need to know where to find the HEMCO library and module files. These are specified with the following environment variables:

HCO_BIN     --> Points to the HEMCO/bin/ directory
HCO_LIB     --> Points to the HEMCO/lib/ directory
HCO_MOD     --> Points to the HEMCO/mod/ directory

We recommend that you define NCU_BIN, NCU_LIB, NCU_MOD, HCO_BIN, HCO_LIB, and HCO_MOD in either your ~/.cshrc or ~/.bashrc file.

--Bob Y. 15:15, 18 July 2014 (EDT)

Where can I get more emissions data for use with HEMCO?

NOTE: If you are one of several HEMCO users at your institution, check first to see if someone has already downloaded the HEMCO data directory tree to your system.

We have collated data files (in COARDS-compliant netCDF format) from several emissions inventories and other atmospheric data sets that you may download. HEMCO uses data files at their native resolution whenever possible, rather than having a different set of files for several different grids.

Please see our 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 instructions for downloading these data to your local disk server.

--Bob Y. 16:50, 18 February 2015 (EST)