Installing libraries for GEOS-Chem

From Geos-chem
Revision as of 14:21, 22 May 2012 by Tom Roche (Talk | contribs) (fix typo)

Jump to: navigation, search

On this page we provide instructions on how to install the netCDF-4.2 library 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 install netCDF on your computer system. In order to facilitate building the netCDF library, the GEOS-Chem Support Team has constructed the GEOS-Chem-Libraries installer package. With GEOS-Chem-Libraries, you can build one of the following sets of libraries:

Either:

  • netCDF-4.2
  • ZLIB-1.2.6 (netCDF-4.2 depends on this)
  • HDF5-1.8.8 (netCDF-4.2 depends on this)

Or:

  • netCDF "CLASSIC" (i.e. lacking some of the new features that were introduced in netCDF-4)

We recommend that you try to build the netCDF-4.2 library first, since this is the most recent netCDF version. The netCDF-4.2 library is 100% backwards compatible with older netCDF-3 files. Also, many data files (e.g. GEOS-5.7.2 "raw" data) are now starting to be distributed in the newer netCDF-4 format. If you have problems building netCDF-4.2 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.2 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. 14:08, 10 May 2012 (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) 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.2
hdf5-1.8.8
zlib-1.2.6
  • ifort (IFORT) 10.1 20080312
  • gcc (GCC) 4.1.2 20080704 (Red Hat 4.1.2-52)
x86_64 GNU/Linux fujita06.atmosp.physics.utoronto.ca Thomas Walker (U. Toronto)
netcdf "CLASSIC"
  • ifort (IFORT) 10.1 20080312
  • gcc (GCC) 4.1.2 20080704 (Red Hat 4.1.2-52)
x86_64 GNU/Linux fujita06.atmosp.physics.utoronto.ca Thomas Walker (U. Toronto)

--Bob Y. 14:52, 11 May 2012 (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. Type:

git clone git://git.as.harvard.edu/bmy/GEOS-Chem-Libraries

and 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. 12:07, 30 April 2012 (EDT)

Building the netCDF-4.2 library

netCDF-4.2 installation process

To build the netCDF-4.2 library (and the dependent ZLIB and HDF5 libraries) using the Intel Fortran Compiler ("IFORT"), type:

  make PREFIX=root_library_dir [GCC=yes]

To build the libraries for the PGI compiler, type:

  make COMPILER=pgi PREFIX=root_library_dir [GCC=yes]

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.2 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.8 
  ok   |   ok    | netcdf-4.2 
  ok   |   ok    | netcdf-fortran-4.2 
-------+---------+-------------------------------------

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

--Bob Y. 11:25, 11 May 2012 (EDT)

netCDF-4.2 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-4.2 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-4.2 library files.

--Bob Y. 13:56, 11 May 2012 (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:

  make CLASSIC=yes PREFIX=root_library_dir [GCC=yes]

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

  make CLASSIC=yes COMPILER=pgi PREFIX=root_library_dir [GCC=yes]

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.8 
  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. 14:21, 8 May 2012 (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. 13:58, 11 May 2012 (EDT)

Building both netCDF-4.2 and netCDF CLASSIC

For most applications, you will only have to build either the netCDF-4.2 libraries or the netCDF CLASSIC libraries but not both. However, it is possible to build both sets of netCDF libraries. The only extra step that you have to do is to clean the netCDF directory in between builds. This is done as follows:

With the IFORT compiler:

make [PREFIX=...]                             # Builds netCDF-4.2 (PREFIX can be omitted)
make clean_netcdf                             # Cleans the netcdf-4.2 and netcdf-fortran-4.2 source code directories
make CLASSIC=yes [PREFIX=...]                 # Builds netCDF CLASSIC (PREFIX is optional)

With the PGI compiler:

make COMPILER=pgi [PREFIX=...]                # Builds netCDF-4.2 (PREFIX can be omitted)
make clean_netcdf                             # Cleans the netcdf-4.2 and netcdf-fortran-4.2 source code directories
make CLASSIC=yes COMPILER=pgi [PREFIX=...]    # Builds netCDF CLASSIC (PREFIX can be omitted)

Typing make clean_netcdf will remove all object (*.o), module (*.mod), and library (*.a)) files from the netCDF source code directories. Cleaning the source code directory allows you to build from scratch. This will not remove any libraries you may have previously installed in root_library_dir.

If you are using the PREFIX=root_library_dir option to specify the root library directory, then be sure to install the netCDF-4.2 and netCDF CLASSIC libraries into separate directories. This will prevent libraries from being overwritten.

--Bob Y. 14:46, 8 May 2012 (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. 10:43, 10 May 2012 (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.

ROOT_LIBRARY_DIR=root_library_dir
GC_BIN=$ROOT_LIBRARY_DIR/bin
GC_INCLUDE=$ROOT_LIBRARY_DIR/include
GC_LIB=$ROOT_LIBRARY_DIR/lib
export GC_BIN
export GC_INCLUDE
export GC_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. 10:24, 10 May 2012 (EDT)

More about nc-config and nf-config

The netCDF 4.2 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.2 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. 12:53, 10 May 2012 (EDT)

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

GEOS-Chem v9-01-03 and higher versions 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.

You will notice the following lines added to the Makefile_header.mk file in the top-level GEOS-Chem source code directory:

# Library link path: first try to get the list of proper linking flags
# for this build of netCDF with nf-config and nc-config. 
NCL       := $(shell $(GC_BIN)/nf-config --flibs)
NCL       += $(shell $(GC_BIN)/nc-config --libs)
NCL       := $(filter -l%,$(NCL))

#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
#%%%% NOTE TO GEOS-CHEM USERS: If you do not have netCDF-4.2 installed
#%%%% Then you can add/modify the linking sequence here.  (This sequence
#%%%% is a guess, but is probably good enough for other netCDF builds.)
ifeq ($(NCL),) 
NCL       := -lnetcdf -lhdf5_hl -lhdf5 -lz
endif
#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

# Prepend the library directory path to the linking sequence
NCL       := -L$(GC_LIB) $(NCL)

# Command to link to the various library files (-lHeaders should be last!)
LINK      := -L$(LIB) -lKpp -lIsoropia -lGeosUtil -lHeaders
LINK      := $(LINK) -lNcUtils $(NCL)

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

1. This first line:

NCL       := $(shell $(GC_BIN)/nf-config --flibs)

runs the executable file $(GC_BIN)/nf-config and asks for the linking sequence for the netCDF Fortran library (as described above). The sequence is saved in the Makefile variable NCL. If the GNU Make utility cannot find the nf-config executable, then a NULL space ("") will be saved to NCL.

2. The second line:

NCL       += $(shell $(GC_BIN)/nc-config --libs)

runs the executable file $(GC_BIN)/nf-config and asks for the library linking sequence to the main netCDF library (as described above). This sequence is appended to NCL (using the += operator of GNU Make). If the GNU Make utility cannot find the nf-config executable, then a NULL space ("") will be saved to NCL.

3. The third line:

NCL       := $(filter -l%,$(NCL))

only returns substrings in the NCL variable that begin with -l. This preserves the commands to link to the netCDF libraries (-lnetcdff, -lnetcdf, etc.) while ignoring the library directory specification (-L, etc.).

4. The next three lines of code are an IF statement:

ifeq ($(NCL),) 
NCL       := -lnetcdf -lhdf5_hl -lhdf5 -lz
endif

This tells GNU make to manually set NCL to the link sequence that is supplied by the user if the NCL variable is blank (""). (If NCL is blank, then this means that GNU Make could not find nf-config and nc-config).

NOTE: netCDF-4.2 is the first netCDF version that builds nf-config and nc-config. If you are using a netCDF installation that was not built with the GEOS-Chem-Libraries installer, then you will likely have to manually specify the library link commands at this point in the Makefile_header.mk file.

5. The next line of code after the IF statement:

# Prepend the library directory path to the linking sequence
NCL       := -L$(GC_LIB) $(NCL)

tells GNU make to look for the libraries in the $(GC_LIB) directory, and appends this to NCL. Recall that nf-config and nc-config will return the value of the ORIGINAL directory into which the netCDF libraries were first installed. This directory may or may not be the same as the directory where the libraries are currently found. To remove this ambiguity, we tell GNU Make to look for all libraries in the path specified by environment variable $GC_LIB.

6. The next lines of code after this:

LINK      := -L$(LIB) -lKpp -lIsoropia -lGeosUtil -lHeaders
LINK      := $(LINK) -lNcUtils $(NCL)

add the library link commands in the NCL variable to the LINK variable. LINK is used to specify all library linking commands for GEOS-Chem.

--Bob Y. 12:48, 10 May 2012 (EDT)

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-5.7.2 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-5.7.2 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)