Installing libraries for GEOS-Chem

From Geos-chem
Revision as of 15:09, 24 November 2015 by Lizzie Lundgren (Talk | contribs) (Downloading the GEOS-Chem-Libraries installer package)

Jump to: navigation, search

On this page we provide instructions on how to install netCDF-4 and related libraries for GEOS-Chem. Alternate instructions for building the netCDF "CLASSIC" libraries are also given.

Overview

GEOS-Chem v9-01-03 (and higher versions) require that you have a copy of the netCDF libraries installed on your system. We are replacing the traditional "binary punch" file format with COARDS-compliant netCDF format.

First check to see if netCDF is already installed on your system

On many computer systems, you can load pre-compiled libraries and software packages (such as netCDF, HDF5, IDL ifort compiler, etc.) with the module command. Check with your sysadmin or IT staff if module is already installed on your system. If it is, we recommend that you use module to load a version of the netCDF libraries into your computing environment. Usually this is done by putting a line of code such as:

module load netcdf

into your ~./.bashrc or ~/.cshrc shell environment. Depending on your setup, you may have to give a specific version number. Ask your sysadmin or IT staff for more information.

--Bob Y. 16:58, 20 April 2015 (EDT)

If not, then you can use the GEOS-Chem-Libraries installer

If your computer system does not use the module command, then you (or your sysadmin/IT staff) can use our GEOS-Chem-Libraries installer package to build the netCDF libraries. With GEOS-Chem-Libraries, you can build one of the following sets of libraries:

EITHER: netCDF-4 installation OR: netCDF-CLASSIC installation
  • netcdf-4.2
  • netcdf-fortran-4.2
  • zlib-1.2.6
  • hdf5-1.8.9

  • netCDF-CLASSIC
  • zlib-1.2.6


We recommend that you try to build the netCDF-4 library first, since this is the most recent netCDF version. The netCDF-4 library is 100% backwards compatible with older netCDF-3 files. Also, many data files (e.g. GEOS-FP "raw" data) are now starting to be distributed in the newer netCDF-4 format. If you have problems building netCDF-4 then you can try to build the netCDF classic library, which has a simpler installation process.

Please note the following:

  1. If you are one of several GEOS-Chem users at your institution, and if you run GEOS-Chem on a common machine or cluster, then only one person (typically your IT guru) would have to install these libraries for GEOS-Chem.

  2. Any recent version of netCDF (version 3.0 or higher) may be used with GEOS-Chem. However, we recommend all GEOS-Chem users to build either netCDF-4 or netCDF CLASSIC with the GEOS-Chem-Libraries installer so that GEOS-Chem will be able to automatically determine the proper library linking commands.

--Bob Y. 16:05, 6 October 2014 (EDT)

Installation tests

The GEOS-Chem-Libraries package was beta-tested by the following users. Successful library builds were obtained with the following compiler/OS combinations.

Libraries Compilers OS Machine Name Tested by
netcdf-4.2
hdf5-1.8.8
zlib-1.2.6
  • Intel(R) Fortran Intel(R) 64 Compiler XE (ifort) for applications running on Intel(R) 64, Version 12.1.3.293 Build 20120212
  • gcc (GCC) 4.6.3 20120306 (Red Hat 4.6.3-2) Copyright (C) 2011 Free Software Foundation, Inc.
x86_64 GNU/Linux titan.as.harvard.edu Bob Yantosca (Harvard)
netcdf-4.2
hdf5-1.8.8
zlib-1.2.6
  • Intel(R) 64 compilers (ifort, icc, icpc) Version 11.1
    Build 20100203 Package ID: l_cprof_p_11.1.069
x86_64 GNU/Linux rhea.as.harvard.edu Bob Yantosca (Harvard)
Melissa Payer (Harvard)
netcdf "CLASSIC"
  • Intel(R) 64 compilers (ifort, icc, icpc) Version 11.1
    Build 20100203 Package ID: l_cprof_p_11.1.069
x86_64 GNU/Linux rhea.as.harvard.edu Bob Yantosca (Harvard)
Melissa Payer (Harvard)
netcdf-4.2
hdf5-1.8.8
zlib-1.2.6
  • Intel(R) 64 compiler (ifort only) Version 11.1
    Build 20100203 Package ID: l_cprof_p_11.1.069
  • gcc (GCC) 4.3.3 (C) 2008 Free Software Foundation, Inc
x86_64 GNU/Linux wumpus.seas.harvard.edu Bob Yantosca (Harvard)
netcdf "CLASSIC"
  • Intel(R) 64 compiler (ifort only) Version 11.1
    Build 20100203 Package ID: l_cprof_p_11.1.069
  • gcc (GCC) 4.3.3 (C) 2008 Free Software Foundation, Inc
x86_64 GNU/Linux wumpus.as.harvard.edu Bob Yantosca (Harvard)
  • netcdf-4.3.2
  • netcdf-fortran-4.2
  • hdf5-1.8.9
  • zlib-1.2.6
  • ifort 11.1.069 Build 20100203
  • icc 11.1.069 Build 20100203
x86_64 GNU/Linux bmy.as.harvard.edu Bob Yantosca

--Bob Y. 15:22, 23 October 2014 (EDT)

Downloading the GEOS-Chem-Libraries installer package

You can use the Git source-code management software to download the GEOS-Chem-Libraries installer package onto your system with this command:

git clone -b netcdf-4.2 http://bitbucket.org/gcst/GEOS-Chem-Libraries

After you have downloaded the installer, then change into the GEOS-Chem-Libraries directory:

cd GEOS-Chem-Libraries

In this directory you will find the following files and subdirectories

README
File describing the contents of GEOS-Chem-Libraries and how to build the netCDF libraries
GNUmakefile
Main-level makefile. This calls down to the master GNUmakefile in the src/ sub-directory.
opt/
Default directory where libraries will be installed (if you do not choose an alternate directory)
src/
Directory containing netCDF and related library distributions.

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

Building the netCDF-4 library

netCDF-4 installation process

To build the netCDF-4 library (and the dependent ZLIB and HDF5 libraries) using the Intel Fortran Compiler ("IFORT"), type one of these commands:

  make PREFIX=root_library_dir                          # If you have the Intel C compilers

  make PREFIX=root_library_dir GCC=yes                  # If you don't have the Intel C compilers
  

To build the libraries for the PGI compiler, type:

  make COMPILER=pgi PREFIX=root_library_dir             # If you have the PGI C compilers

  make COMPILER=pgi PREFIX=root_library_dir GCC=yes     # If you don't have the PGI C compilers

Makefile options:

COMPILER
This option is used to pick the compiler that you wish to use to build netCDF-4.2 and the related libraries. At present, you may select either ifort or pgi. If you omit the COMPILER option, the default value of ifort will be selected.
PREFIX

This option is used to set root_library_dir, which is the full path name of the directory into which the netCDF-4 and related libraries will be installed. If you omit the PREFIX option, then root_library_dir will be automatically set to one of these default values:

GEOS-Chem-Libraries/opt/ifort/nc4/  # If COMPILER=ifort

GEOS-Chem-Libraries/opt/pgi/nc4/   # If COMPILER=pgi

If you do not have sysadmin privileges, then you can use the PREFIX option to set root_library_dir to a directory in your home space, such as /home/YOUR_USER_ID/lib (or you may install them in one of the default paths listed above). You can then ask your sysadmin to move the libraries to a common space on your machine (or cluster) where all users may access them.

GCC
If you do not have the Intel C/C++ compilers (icc, icpc) or PGI C/C++ compilers (pgcc, pgcpp) installed on your system, then you can tell the GEOS-Chem-Libraries installer to use the GNU C/C++ compilers (gcc, g++) instead. Otherwise, you can omit this option.

The libraries take approximately 20 minutes (or longer) to build. If the library installation process is successful, you will see this confirmation screen:

-------+---------+-------------------------------------
Config | Install |             Package
-------+---------+-------------------------------------
  ok   |   ok    | zlib-1.2.6 
  ok   |   ok    | hdf5-1.8.9
  ok   |   ok    | netcdf-4.2
  ok   |   ok    | netcdf-fortran-4.2
-------+---------+-------------------------------------

This tells you that the netCDF-4 (and related libraries) were installed properly.

--Bob Y. 15:56, 6 October 2014 (EDT)

netCDF-4 library paths

The netCDF-4.2 (and related libraries) will be installed into the following paths. As described above, you may use the PREFIX=root_library_dir option to set the value of root_library_dir.

root_library_dir/bin           # nc-config, nf-config, ncdump, ncgen, etc.
root_library_dir/include       # Include files (*.h)
root_library_dir/lib           # Library file (libz.a)
root_library_dir/share         # Manual pages & documentation

--Bob Y. 14:12, 8 May 2012 (EDT)

Telling GEOS-Chem where to find the netCDF-4libraries

Please jump to the Linking from GEOS-Chem section for information on how to set environment variables that will tell GEOS-Chem where to find the netCDF-4.2 library files.

--Bob Y. 15:56, 6 October 2014 (EDT)

Building the netCDF CLASSIC library

netCDF CLASSIC installation process

To build the netCDF "CLASSIC" libraries (which lacks the advanced features of netCDF-4.2) using the Intel Fortran Compiler ("IFORT"), type one of these commands:

  make CLASSIC=yes PREFIX=root_library_dir                           # If you have the Intel C compilers

  make CLASSIC=yes PREFIX=root_library_dir GCC=yes                   # If you don't have the Intel C compilers

To build the netCDF "CLASSIC" libraries for the PGI compiler, type:

  make CLASSIC=yes COMPILER=pgi PREFIX=root_library_dir              # If you have the PGI C compilers

  make CLASSIC=yes COMPILER=pgi PREFIX=root_library_dir GCC=yes      # If you don't have the PGI C compiler

Makefile options:

COMPILER
This option is used to pick the compiler that you wish to use to build netCDF "CLASSIC". At present, you may select either ifort or pgi. If you omit the COMPILER option, the default value of ifort will be selected.
PREFIX

This option is used to set root_library_dir, which is the full path name of the directory into which the netCDF-4 and related libraries will be installed. If you omit the PREFIX option, then root_library_dir will be set to one of these default values:

GEOS-Chem-Libraries/opt/ifort/nc_classic/  # If COMPILER=ifort

GEOS-Chem-Libraries/opt/pgi/nc_classic/   # If COMPILER=pgi

If you do not have sysadmin privileges, then you can use the PREFIX option to set root_library_dir to a directory in your home space, such as /home/YOUR_USER_ID/lib (or you may install them in one of the default paths listed above). You can then ask your sysadmin to move the libraries to a common space on your machine (or cluster) where all users may access them.

GCC
If you do not have the Intel C/C++ compilers (icc, icpc) or PGI C/C++ compilers (pgcc, pgcpp) installed on your system, then you can tell the GEOS-Chem-Libraries installer to use the GNU C/C++ compilers (gcc, g++) instead. Otherwise, you can omit this option.

The netCDF "CLASSIC" library takes several minutes to build. If the library installation process is successful, you will see this confirmation screen:

-------+---------+-------------------------------------
Config | Install |             Package
-------+---------+-------------------------------------
  --   |   --    | zlib-1.2.6 
  --   |   --    | hdf5-1.8.9
  ok   |   ok    | netcdf-4.2 (netCDF classic)
  ok   |   ok    | netcdf-fortran-4.2 (netCDF classic)
-------+---------+-------------------------------------

This tells you that the netCDF "CLASSIC" library was installed properly. The ZLIB and HDF5 libraries are not needed for netCDF "CLASSIC", and are therefore not built.

--Bob Y. 15:24, 23 October 2014 (EDT)

netCDF CLASSIC library paths

The netCDF CLASSIC libraries will be installed into the following paths. As described above, you may use the PREFIX option to set the value of root_library_dir.

root_library_dir/bin        # nc-config, nf-config, ncdump, ncgen programs
root_library_dir/include    # Include files (*.h)
root_library_dir/lib        # Library files (*.a)
root_library_dir/share      # Manual pages & documentation

--Bob Y. 14:32, 8 May 2012 (EDT)

Telling GEOS-Chem where to find the netCDF CLASSIC libraries

Please jump to the Linking from GEOS-Chem section for information on how to set environment variables that will tell GEOS-Chem where to find the netCDF CLASSIC library files.

--Bob Y. 15:24, 23 October 2014 (EDT)

Linking to the netCDF libraries

Now that you have installed the netCDF-4.2 libraries or the netCDF CLASSIC libraries, you must let the compiler know where these files can be found when you are compiling your source code. Otherwise you will get errors during the compilation process.

Important files created by the library build process

The library build process creates several output files. Here is a description of the files that you will most commonly use. (Recall that the PREFIX=root_library_dir option can be used to specify the root library directory location.)

File Type Location Built with How it's used
libnetcdf.a Library root_library_dir/lib netCDF-4.2 and netCDF CLASSIC This is the main netCDF library.
libnetcdff.a Library root_library_dir/lib netCDF-4.2 and netCDF CLASSIC This is the netCDF Fortran library. It contains the netCDF interface for the Fortran and Fortran-90 languages.
netcdf.inc Include file root_library_dir/include netCDF-4.2 and netCDF CLASSIC This include file is required to call netCDF library routines using the standard Fortran interface. Add the line #include "netcdf.inc" to your Fortran code.
netcdf.mod Module root_library_dir/include netCDF-4.2 and netCDF CLASSIC This module file is required to call netCDF library routines using the Fortran-90 interface. Add the line USE NETCDF_MOD to your Fortran code.
nc-config Executable root_library_dir/bin netCDF-4.2 and netCDF CLASSIC Use this program to find out information about the netCDF library. For example nc-config --libs will give you a list of the commands that you need to use to link to the netCDF libraries.
nf-config Executable root_library_dir/bin netCDF-4.2 and netCDF CLASSIC Use this program to find out information about the netCDF Fortran library. For example nf-config --libs will give you a list of the commands that you need to use to link to the netCDF Fortran libraries.
ncdump Executable root_library_dir/bin netCDF-4.2 and netCDF CLASSIC Use this program to print header information from a netCDF file. Useful for examining variable names, dimensions, and index array values. Type ncdump -c FILENAME.nc at the Unix prompt.
libhdf5_hl.a Library root_library_dir/lib netCDF-4.2 only HDF5 High-Level library. This contains functions on top of the standard HDF5 library interface. Required for netCDF-4.2.
libhdf5.a Library root_library_dir/lib netCDF-4.2 only The main HDF5 library. Required for netCDF-4.2.
libz.a Library file root_library_dir/lib netCDF-4.2 only The ZLIB library. Contains gzip, gunzip etc. routines for file compression and expansion. Required by HDF5.


We will discuss nc-config and nf-config in more depth below.

--Bob Y. 15:24, 23 October 2014 (EDT)

Linking from GEOS-Chem

Now that you have successfully built the netCDF (and related) libraries with the GEOS-Chem-Libraries installer, you must tell GEOS-Chem where to find the relevant library, include, and executable files. The easiest way to do this is to set environment variables in your setup files:

  1. .cshrc:   if you use C-shell (csh) or T-shell (tcsh)
  2. .profile:   if you use Bourne shell (sh)
  3. .bashrc:   if you use Bourne-Again shell (bash)

There are three environment variables that you need to set:

GC_BIN
Specifies the location of the executable files (e.g. nc-config, nf-config, ncdump, etc.)
GC_INCLUDE
Specifies the location of include files (*.h, *.inc) and module files (*.mod) for the netCDF (and HDF5) libraries
GC_LIB
Specifies the location of library files (*.a)

With csh or tcsh

If you use C-shell (csh) or T-shell (tcsh), then add the following lines to your .cshrc file:

setenv ROOT_LIBRARY_DIR root_library_dir
setenv GC_BIN           $(ROOT_LIBRARY_DIR)/bin
setenv GC_INCLUDE       $(ROOT_LIBRARY_DIR)/include
setenv GC_LIB           $(ROOT_LIBRARY_DIR)/lib 

where root_library_dir is the directory into which you installed the libraries, as described above. Then to accept the changes, type source ~/.cshrc at the Unix prompt.

With sh or bash

If you use Bourne-shell (sh), then add the following lines to your .profile file. If you use Bourne-Again shell (bash), then add these same lines to your .bashrc file.

export ROOT_LIBRARY_DIR=root_library_dir
export GC_BIN=$ROOT_LIBRARY_DIR/bin
export GC_INCLUDE=$ROOT_LIBRARY_DIR/include
export GC_LIB=$ROOT_LIBRARY_DIR/lib

where root_library_dir is the directory into which you installed the libraries, as described above. Then to accept the changes, type source ~/.bashrc at the Unix prompt.

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

More about nc-config and nf-config

The netCDF-4 distribution now will create two very useful executables named nc-config and nf-config. These executables are created regardless of whether you choose to build the full netCDF-4 library (which relies on HDF5 and ZLIB) or the netCDF CLASSIC library.

The nc-config and nf-config programs can be used to get information about the how the netCDF libraries and netCDF Fortran libraries were built. Typing:

nc-config --help
nf-config --help

will return a list of options that you can select from. For the time being, we shall concentrate on these two options:

--libs   : library linking information for netcdf
--flibs  : libraries needed to link a Fortran program

Program nc-config provides information about the main netCDF libraries (with the C/C++ language interface). If you type this at the Unix prompt:

$GC_BIN/nf-config --flibs 

You will get the proper library linking sequence for the main netCDF library:

-Lroot_library_dir/lib -Lroot_library_dir/lib -lnetcdf -lhdf5_hl -lhdf5 -lm -lz

where:

  1. -L is the command that tells the compiler where to look for library files
  2. root_library_dir is the main library path (that you specified with the PREFIX option) at the time when you first built the libraries.
    NOTE: Even if you move the libraries to a different location, the displayed value of root_library_dir will still be the original path!
  3. root_library_dir/lib is the subdirectory of root_library_dir where the library files (*.a) are located.
  4. -lnetcdf links to the main netCDF library (libnetcdf.a)
  5. -lhdf5_hl links to the HDF5 High-Level library (libhdf5_hl.a)
  6. -lhdf5<?tt> links to the main HDF5 library (<tt>libhdf5.a)
  7. -lm links to the math library that comes pre-installed with your Unix/Linux OS version (libm.a)
  8. -lz links to the ZLIB library (libz.a)

NOTE: For some reason, nc-config lists the [root_library_dir] path more than once.

Program nf-config is similar to nc-config, but it provides information only about the netCDF Fortran library. If you type the following at the Unix prompt:

$GC_BIN/nf-config --libs 

You will get the proper library link sequence for the netCDF fortran library:

-Lroot_library_dir/lib -lnetcdff -Lroot_library-dir/lib -lnetcdf -lnetcdf

where:

  1. -L is the command that tells the compiler where to look for library files
  2. root_library_dir is the library path (that you specified with the PREFIX option) at the time when you first built the libraries.
    NOTE: Even if you move the libraries to a different root path, the displayed value of root_library_dir will still be the original path!
  3. root_library_dir/lib is the subdirectory of root_library_dir where the library files (*.a) are located.
  4. -lnetcdff is the command to link to the netCDF Fortran library (libnetcdff.a)
  5. -lnetcdf is the command to link to the main netCDF library (libnetcdf.a)

Because the libraries must be linked in reverse order, the netCDF fortran library linking commands should precede the linking commands for the main netCDF library.

--Bob Y. 15:24, 23 October 2014 (EDT)

How GEOS-Chem uses nc-config and nf-config

GEOS-Chem can utilize the nc-config and nf-config programs that are built when you run the GEOS-Chem-Libraries installer. This allows GNU Make to automatically find the proper library linking commands.

In GEOS-Chem v10-01 and higher versions, we have updated the Makefile_header.mk file in order to make the library linking process more portable. You will see this code:

###############################################################################
###                                                                         ###
###  Set linker commands for local and external libraries (incl. netCDF)    ###
###                                                                         ###
###############################################################################

# Library include path
NC_INC_CMD           := -I$(GC_INCLUDE)

# Get the version number (e.g. "4130"=netCDF 4.1.3; "4200"=netCDF 4.2, etc.)
NC_VERSION           :=$(shell $(GC_BIN)/nc-config --version)
NC_VERSION           :=$(shell echo "$(NC_VERSION)" | sed 's|netCDF ||g')
NC_VERSION           :=$(shell echo "$(NC_VERSION)" | sed 's|\.||g')
NC_VERSION_LEN       :=$(shell perl -e "print length $(NC_VERSION)")
ifeq ($(NC_VERSION_LEN),3)
 NC_VERSION          :=$(NC_VERSION)0
endif
ifeq ($(NC_VERSION_LEN),2) 
 NC_VERSION          :=$(NC_VERSION)00
endif
 
# Test if we have at least netCDF 4.2.0.0
AT_LEAST_NC_4200     :=$(shell perl -e "print ($(NC_VERSION) ge 4200)")

ifeq ($(AT_LEAST_NC_4200),1)

  #-------------------------------------------------------------------------
  # netCDF 4.2 and higher:
  # Use "nf-config --flibs" and "nc-config --libs"
  #-------------------------------------------------------------------------
  NC_LINK_CMD        := $(shell $(GC_BIN)/nf-config --flibs)
  NC_LINK_CMD        += $(shell $(GC_BIN)/nc-config --libs)

else

  #-----------------------------------------------------------------------
  # Prior to netCDF 4.2:
  # Use "nc-config --flibs" and nc-config --libs
  #-----------------------------------------------------------------------
  NC_LINK_CMD        := $(shell $(GC_BIN)/nc-config --flibs)
  NC_LINK_CMD        += $(shell $(GC_BIN)/nc-config --libs)

endif

#=============================================================================
#%%%%% FIX FOR USE WITH THE GEOS-Chem-Libraries (bmy, 1/13/15)
#%%%%% 
#%%%%% If your GEOS-Chem-Libraries netCDF/HDF5 package was built in one 
#%%%%% directory and then moved somewhere else, then nf-config and nc-config 
#%%%%% may not return the proper link directory path.  
#%%%%% 
#%%%%% To avoid this error, we shall test if the $GC_LIB environment variable 
#%%%%% contains the text "GEOS-Chem-Libraries".  (Recall that $GC_LIB is 
#%%%%% defined in either your .bashrc or .cshrc file depending on which Unix 
#%%%%% shell you use.)  If we find the text "GEOS-Chem-Libraries" in $GC_LIB, 
#%%%%% then we shall override the library path returned by nf-config and 
#%%%%% nc-config with the path specified by $GC_LIB.  This will ensure that 
#%%%%% we point to the location where the GEOS-Chem-Libraries are installed.
#%%%%%
#%%%%% NOTE: This fix should work for most users.  If it does not work, then
#%%%%% contact the GEOS-Chem Support Team (geos-chem-support@as.harvard.edu).
#%%%%%
REGEXP               :="GEOS-Chem-Libraries"
ifeq ($(shell [[ "$(GC_LIB)" =~ $(REGEXP) ]] && echo true),true)
  NC_LINK_CMD        := $(filter -l%,$(NC_LINK_CMD))
  NC_LINK_CMD        :=-L$(GC_LIB) $(NC_LINK_CMD)
endif
#=============================================================================

Here is a brief explanation of these lines of Makefile code:

1. The Makefile variable $NC_INC_CMD tells the compiler in which directories to find any relevant netCDF or HDF5 include files and modules. This command is formed by prefixing an -I to the directory path specified in your $GC_INCLUDE directory (which is defined in your .bashrc or .cshrc startup file.)
2. The variables NC_VERSION and AT_LEAST_NC_4200 are used to determine which version of netCDF is installed. This distinction is important because the calling sequence for nc-config and nf-config are different depending on the netCDF version, as we will see in #3 and #4 below.
3. If you are using netCDF-4.2 or a higher version, then the netCDF and/or HDF5 library linking commands are constructed by executing these lines of code:
      NC_LINK_CMD        := $(shell $(GC_BIN)/nf-config --flibs)
      NC_LINK_CMD        += $(shell $(GC_BIN)/nc-config --libs)
This calls the executable files
  • $(GC_BIN)/nf-config : Returns the proper link commands for the netCDF Fortran-language library functions
  • $(GC_BIN)/nc-config : Returns the proper link commands for the netCDF C-language library functions
The library linking commands are stored in the variable NC_LINK_CMD, which is used by GNU Make further down in the GEOS-Chem build sequence. Using nf-config and/or nc-config makes the Makefile very portable from one system to another.
4. On the other hand, if you are using a version of netCDF prior to netCDF-4.2, NC_LINK_CMD will be constructed by executing these lines of code:
      NC_LINK_CMD        := $(shell $(GC_BIN)/nc-config --flibs)
      NC_LINK_CMD        += $(shell $(GC_BIN)/nc-config --libs)
This is similar to #3 above, but note that nc-config is used to return the link commands for both the netCDF Fortran-language functions and the netCDF C-language functions.
5. It should be noted that nf-config and nc-config will return the ORIGINAL directory path into which the netCDF and/or HDF5 libraries were first installed. This directory may or may not be the same as the directory where these libraries currently reside. To remove this ambiguity, we have applied a special fix that is only applied if you have used the GEOS-Chem-Libraries installer. This fix is executed by the following IF block:
    #=============================================================================
    #%%%%% FIX FOR USE WITH THE GEOS-Chem-Libraries (bmy, 1/13/15)
    #%%%%% ... etc. comment lines ...
    #%%%%%
    REGEXP               :="GEOS-Chem-Libraries"
    ifeq ($(shell [[ "$(GC_LIB)" =~ $(REGEXP) ]] && echo true),true)</nowiki>
      NC_LINK_CMD        := $(filter -l%,$(NC_LINK_CMD))
      NC_LINK_CMD        :=-L$(GC_LIB) $(NC_LINK_CMD)
    endif
    #=============================================================================
This IF statement looks for the text GEOS-Chem-Libraries in the library link command returned by the nf-config and/or nc-config, and proceeds as follows:
  • If the text "GEOS-Chem-Libraries" is found within the Makefile variable NC_LINK_CMD, then NC_LINK_CMD will be rewritten so that it points to the directory path specified by your $GC_LIB environment variable. (Recall that GC_LIB is defined in your .bashrc or .cshrc depending on which Unix shell you use.) This will remove any ambiguity
  • If the text "GEOS-Chem-Libraries" is not found, then no modification will be made to NC_LINK_CMD.

--Bob Y. 16:25, 13 January 2015 (EST)

Using ncdump

The ncdump utility is a quick way to get information about the dimensions, variable names, and index array values stored within a netCDF file. For example, if you wanted to quickly check the variable names and dimensions in one of the GEOS-FP met field files, you could type:

$GC_BIN/ncdump -c GEOS572.20120501.I3.4x5.nc

which returns information about the contents of the netCDF file:

netcdf GEOS572.20120501.I3.4x5 {
dimensions:
       lon = 72 ;
       lat = 46 ;
       lev = 72 ;
       time = 8 ;
       ap = 73 ;
       bp = 73 ;
variables:
       float lon(lon) ;
               lon:long_name = "longitude" ;
               lon:units = "degrees_east" ;
       float lat(lat) ;
               lat:long_name = "latitude" ;
               lat:units = "degrees_north" ;
       float lev(lev) ;
               lev:long_name = "levels" ;
               lev:units = "unitless" ;
       int time(time) ;
               time:long_name = "time" ;
               time:units = "minutes since 2012-05-01 00:00:00.0" ;
               time:delta_t = "0000-00-00 03:00:00" ;
               time:begin_date = "20120501" ;
               time:begin_time = "000000" ;
               time:time_increment = "030000" ;
       float ap(ap) ;
               ap:long_name = "Hybrid grid A parameter [ P = ap + ( bp * Psurface ) ]" ;
               ap:units = "hPa" ;
       float bp(bp) ;
               bp:long_name = "Hybrid grid B parameter [ P = ap + ( bp * Psurface ) ]" ;
               bp:units = "unitless" ;
       float PS(time, lat, lon) ;
               PS:long_name = "Surface pressure" ;
               PS:units = "hPa" ;
               PS:gamap_category = "GMAO-2D" ;
       float PV(time, lev, lat, lon) ;
               PV:long_name = "Ertel potential vorticity" ;
               PV:units = "K m-2 kg-1 s-1" ;
               PV:gamap_category = "GMAO-3D$" ;
       float QV(time, lev, lat, lon) ;
               QV:long_name = "Specific humidity" ;
               QV:units = "kg kg-1" ;
               QV:gamap_category = "GMAO-3D$" ;
       float T(time, lev, lat, lon) ;
               T:long_name = "Temperature" ;
               T:units = "K" ;
               T:gamap_category = "GMAO-3D$" ;

// global attributes:
               :title = "GEOS-5.7.2 instantaneous 3-hour (I3) fields for GEOS-Chem" ;
               :contact = "GEOS-Chem Support Team (geos-chem-support@as.harvard.edu)" ;
               :references = "www.geos-chem.org; wiki.geos-chem.org" ;
               :filename = "/as/scratch/bmy/GEOS572.20120501.I3.4x5.nc" ;
               :history = "File generated on: 2012/05/08 16:41:37 GMT-0400" ;
               :format = "NetCDF-3" ;
               :conventions = "COARDS" ;
               :version = "GEOS-5,7.2" ;
               :model = "GEOS5" ;
               :nlayers = "72" ;
               :start_date = "20120501" ;
               :start_time = "00:00:00.000000" ;
               :end_date = "20120501" ;
               :end_time = "23:59:59.99999" ;
               :delta_time = "30000" ;
               :delta_lon = "5" ;
               :delta_lat = "4" ;
data:
 
 lon = -180, -175, -170, -165, -160, -155, -150, -145, -140, -135, -130, 
    -125, -120, -115, -110, -105, -100, -95, -90, -85, -80, -75, -70, -65, 
    -60, -55, -50, -45, -40, -35, -30, -25, -20, -15, -10, -5, 0, 5, 10, 15, 
    20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90, 95, 100, 105, 
    110, 115, 120, 125, 130, 135, 140, 145, 150, 155, 160, 165, 170, 175 ;
 
 lat = -89, -86, -82, -78, -74, -70, -66, -62, -58, -54, -50, -46, -42, -38, 
    -34, -30, -26, -22, -18, -14, -10, -6, -2, 2, 6, 10, 14, 18, 22, 26, 30, 
    34, 38, 42, 46, 50, 54, 58, 62, 66, 70, 74, 78, 82, 86, 89 ;
 
 lev = 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 
    21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 
    39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 
    57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72 ;
 
 time = 0, 180, 360, 540, 720, 900, 1080, 1260 ;
 
 ap = 0, 0.04804826, 6.593752, 13.1348, 19.61311, 26.09201, 32.57081, 
    38.98201, 45.33901, 51.69611, 58.05321, 64.36264, 70.62198, 78.83422, 
    89.09992, 99.36521, 109.1817, 118.9586, 128.6959, 142.91, 156.26, 
    169.609, 181.619, 193.097, 203.259, 212.15, 218.776, 223.898, 224.363, 
    216.865, 201.192, 176.93, 150.393, 127.837, 108.663, 92.36572, 78.51231, 
    66.60341, 56.38791, 47.64391, 40.17541, 33.81001, 28.36781, 23.73041, 
    19.7916, 16.4571, 13.6434, 11.2769, 9.292942, 7.619842, 6.216801, 
    5.046801, 4.076571, 3.276431, 2.620211, 2.08497, 1.65079, 1.30051, 
    1.01944, 0.7951341, 0.6167791, 0.4758061, 0.3650411, 0.2785261, 0.211349, 
    0.159495, 0.119703, 0.08934502, 0.06600001, 0.04758501, 0.0327, 0.02, 0.01 ;

 bp = 1, 0.984952, 0.963406, 0.941865, 0.920387, 0.898908, 0.877429, 
    0.856018, 0.8346609, 0.8133039, 0.7919469, 0.7706375, 0.7493782, 
    0.721166, 0.6858999, 0.6506349, 0.6158184, 0.5810415, 0.5463042, 
    0.4945902, 0.4437402, 0.3928911, 0.3433811, 0.2944031, 0.2467411, 
    0.2003501, 0.1562241, 0.1136021, 0.06372006, 0.02801004, 0.006960025, 
    8.175413e-09, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ;
}

Avoiding memory issues

If you are trying to work with extremely large data sets (such as GEOS-FP 0.25° x 0.3125° nested grids), you may run into a memory error. To get around this limitation, do the following:

  1. Compile the netCDF, HDF5 and zlib libraries with the following compiler flags:
    1. -mcmodel=medium -i-dynamic  (for Intel Fortran Compiler)
    2. -mcmodel=medium  (for PGI Compiler)

These steps will already have been done for you if you used the GEOS-Chem-Libraries installer. The same flags are also set when you compile GEOS-Chem.

What is happening is that the compiler by default imposes a imposes maximum memory limit of ~2GB for static variables. If your code works with large data sets, then the combination of user memory + memory in the netCDF/HDF/Zlib libraries can exceed this limit. Using the -mcmodel=medium option tells the compiler to expect to use more than ~2GB of static memory.

--Bob Y. 17:25, 30 April 2012 (EDT)

What if my system has pre-installed netCDF and HDF5 libraries?

If netCDF and/or HDF5 libraries have already been pre-installed on your system, then you don't necessarily need to run the GEOS-Chem-Libraries installer. You can use these libraries with GEOS-Chem, with a couple of caveats:

GEOS-Chem expects that ...

  1. ... all netCDF, HDF5, zlib library files (*.a) will be placed together in a single directory (e.g. lib/)
  2. ... all netCDF, HDF5, zlib include files (*.h, *.mod) will be placed together in a single directory (e.g. include/)
  3. ... all netCDF, HDF5. zlib executable files (e.g. ncdump) will be placed together in a single directory (e.g. bin/)

If your libraries have all been installed in the above manner, then all you have to do is to define the GC_LIB, GC_INCLUDE and GC_BIN environment variables as described here.

If the library, include, and executable files from your netCDF, HDF5, and zlib builds are scattered among different directories, then do the following:

1. Create new directories in a convenient common space on your system. We'll use the following names in this example:
    /opt/GC_Libraries/lib
    /opt/GC_Libraries/include
    /opt/GC_Libraries/bin
2. In GC_libraries/lib, create a symbolic link to each of the pre-installed netCDF, HDF5, and zlib library files:
    cd /opt/GC_Libraries/lib
    ln -s /opt/netCDF/lib/libnetcdf.a .
    ln -s /opt/netCDF/lib/libnetcdff.a .
    ln -s /opt/HDF5/lib/libhdf5.a .
    ln -s /opt/zlib/lib/libz.a .
    ... etc ...
3. In GC_Libraries/include, create a symbolic link to each of the pre-installed netCDF, HDF5, and zlib include files:
    cd /opt/GC_Libraries/include
    ln -s /opt/HDF5/include/hdf5.h .
    ln -s /opt/HDF5/include/hdf5_hl.h .
    ln -s /opt/netCDF/include/netcdf.h .
    ln -s /opt/netCDF/include/netcdf.inc .
    ln -s /opt/netCDF/include/netcdf.mod .
    ln -s /opt/zlib/zlib.h .
    ... etc ...

4: In GC_Libraries/bin, create a symbolic link to each of the pre-installed netCDF, HDF5, and zlib executable files:

   cd /opt/GC_Libraries/bin
   ln -s /opt/netCDF/ncdump .
   ln -s /opt/netCDF/ncgen .
   ln -s /opt/netCDF/nc-config .
   ln -s /opt/netCDF/nf-config .
   ... etc ...
5. Set the following environment variables in your system startup file to reflect the directories that you just created, such that:
  1. GC_LIB points to /opt/GC_Libraries/lib
  2. GC_INCLUDE points to /opt/GC_Libraries/include
  3. GC_BIN points to /opt/GC_Libraries/bin

In this way, GEOS-Chem will find the relevant files even if they have been split up among several directories.

--Bob Y. 12:41, 10 January 2013 (EST)