Installing libraries for GEOS-Chem

From Geos-chem
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.

Check to see if netCDF is already installed on your system

If you are going to use GEOS-Chem on a shared computer system, chances are that your IT staff will have already installed one or more netCDF library versions that you can use. 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 system administrator or IT staff to see 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.

You can load a combination of compiler and netCDF libraries in the same command. For example:

   module load intel netcdf

will load the default Intel Fortran Compiler version and the default netCDF version that was built with the Intel Fortran Compiler. You can also load specific compiler and netCDF versions by giving the version numbers, such as:

   module load intel/13.0.0.079 netcdf/intel/4.1.3

You can place these module load commands into your .bashrc or .cshrc startup file so that they will be executed every time you log in.

On most computer systems, the module command will also export one or more environment variables containing the directory paths where the libraries and relevant files can be found. This will allow you to always find the proper netCDF library on disk without having to hardwire the directory path in your .bashrc or .cshrc system startup file.

For example, the module load command listed above will export the NETCDF_HOME, NETCDF_INCLUDE, and NETCDF_LIB variables into your Unix environment. The NETCDF_HOME variable is the root folder of the netCDF library. Include files (*.h) and compiled module files (*.mod) are stored in the NETCDF_INCLUDE folder. Library files (*.a) are stored in the NETCDF_LIB folder.

The names of these environment variables will differ from system to system. Ask your IT staff about how the module command is implemented on your computer.

Special handling for netCDF-4.2 and higher versions

The C and Fortran library files are built from different installation packages in netCDF-4.2 and higher versions. Because of this dichotomy, your IT staff may have installed the netCDF Fortran library as a completely separate software module.

For example, we use these commands on the Odyssey cluster at Harvard to load the version of netCDF that was compiled with the GNU Fortran compiler:

   module load gcc/4.8.2-fasrc01      openmpi/1.10.1-fasrc01
   module load netcdf/4.3.3.1-fasrc02 netcdf-fortran/4.4.2-fasrc01

As you can see, the netCDF Fortran library (version 4.4.2) has to be loaded separately from the netCDF C-language library (version 4.3.3.1). In this particular case, both the netCDF C and Fortran libraries also rely on the OpenMPI library (although GEOS-Chem "Classic" doesn't need it).

The above module load commands will export the following variables into your Unix environment: NETCDF_HOME, NETCDF_INCLUDE, NETCDF_LIB, NETCDF_FORTRAN_HOME, NETCDF_FORTRAN_INCLUDE, NETCDF_FORTRAN_LIB.

Because the netCDF Fortran library is loaded as a separate module, it has own environment variables (NETCDF_FORTRAN_HOME, NETCDF_FORTRAN_INCLUDE, NETCDF_FORTRAN_LIB) to define the relevant directory paths. These are analogous to NETCDF_HOME, NETCDF_INCLUDE, and NETCDF_LIB as mentioned in the prior section.

Build your own netCDF libraries if your system doesn't have them

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 https://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:

Item Description
README File containing resources for how to build the netCDF libraries (directs the reader to this page)
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.

--Lizzie Lundgren (talk) 15:10, 24 November 2015 (UTC)

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:

Item or Option Description
README File containing resources for how to build the netCDF libraries (directs the reader to this page)
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 Yantosca (talk) 17:41, 9 December 2016 (UTC)

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:

Item or Option Description
README File containing resources for how to build the netCDF libraries (directs the reader to this page)
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 Yantosca (talk) 17:45, 9 December 2016 (UTC)

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)

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)

Setting environment variables for GEOS-Chem

This discussion has been moved. For complete information, see our Environment variables that specify library paths wiki post.

--Bob Yantosca (talk) 16:51, 10 March 2017 (UTC)

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 links to the main HDF5 library (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?

Obsolete.jpg

NOTE: Most modern Unix clusters load netCDF and other pre-built software libraries with the module command. The information below may be out of date. We shall leave it here for reference.

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)