GEOS–Chem v9–02 Online User's Guide

Previous | Next | Printable View (no frames)

2. Installation

2.1 What you need to download before you can run GEOS–Chem

When setting up GEOS–Chem on your system, you will need to install the following components:

1. The GEOS–Chem source code directory. This is the directory where the Fortran-90 source code files (i.e. *.F, *.F90 files) and Makefiles reside. Your Fortran compiler will create an executable from these source code files.

2. A GEOS–Chem run directory. Here is where you will run the compiled GEOS–Chem executable. Each run directory contains:

   • Various input files that you can modify in order to select different options for your GEOS–Chem simulation
   • Files that define the GEOS–Chem's chemical and photolysis mechanisms
   • "Restart files" that hold the initial conditions for your GEOS–Chem simulation

   You can find a complete description of the run directory contents in Chapter 5.

3. The GEOS–Chem shared data directories. This is the directory tree where the following types of data are stored:

   • Meteorological data (a.k.a. the "met fields) used to drive GEOS–Chem
   • Emissions inventories for GEOS–Chem
   • Scale factors to used to scale emissions from a base year to a given year
   • Oxidant (OH, O3) concentrations for both full-chemistry and offline simulations
   • IPCC future scenarios (for GCAP simulatons)
   • Other GEOS–Chem specific data files.

   You can find a detailed description of the GEOS–Chem shared data directories in Chapter 4.

4. A netCDF library installation. Starting with GEOS–Chem v9–01–03, the model can read data files in netCDF format. Eventually, we shall replace all of GEOS–Chem's input and output files from binary punch file format to netCDF format. We are doing this as part of our Grid-Independent GEOS–Chem project, which seeks to interface GEOS–Chem with the NASA GEOS–5 GCM.

The GEOS–Chem source code directory and run directories are small enough to download directly to your own disk space in your Unix account. You can download these with the Git version control software. You may also download our GEOS-Chem-Libraries netCDF installer via Git, as described below.

On the other hand, the GEOS–Chem shared data directories contain many large files that probably cannot all fit into your own personal disk quota. Therefore, you (or your sysadmin) should download the shared data directories to a common disk space where all GEOS–Chem users in your group can access them. The volume of data contained in the shared data directories precludes using Git; you must instead download these files via FTP, wget, or similar file transfer programs.

2.2 Downloading the GEOS–Chem Source Code

The GEOS–Chem "standard" source code is kept in a Git repository at Harvard:

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

All official releases of the GEOS–Chem "standard" code shall originate from this repository.

You can download the directory containing the latest GEOS–Chem source code version by means of the git clone command. Type:

git clone git://git.as.harvard.edu/bmy/GEOS-Chem  Code.v9-02

This will create an exact copy (or "clone") of the official GEOS–Chem repository to your local disk space, in a directory named Code.v9-02. (You can choose a different name than Code.v9-02 if you wish.)

NOTE: When you clone, you will always get the most recent state of the repository. (i.e. the latest GEOS–Chem version or "bug fix" patch). If you wish to download an older version of GEOS–Chem (say v8–03–01) with Git, please follow these instructions.

Please see Chapter 3 for instructions on how to compile the GEOS–Chem source code into an executable file.

2.3 Downloading the GEOS–Chem run directories

As mentioned above, the GEOS–Chem run directory is where you will run the compiled executable file. The run directory contains several input files that you can modify in order to select the various options for your GEOS–Chem simulation.

We have compiled a collection of GEOS–Chem run directories, grouped by meteorological data type, horizontal resolution, and simulation type. These run directories are stored as individual Git repositories. This allows you to only download the particular run directories that you need.

You can use the Git clone command to download the run directories to your local disk space. The command will take the form:

git clone git://git.as.harvard.edu/bmy/GEOS-Chem-rundirs/DIR-OPTION LOCAL-DIR-NAME

LOCAL-DIR-NAME is the name you chose for your local directory to contain GEOS–Chem

DIR-OPTION may be one of the following:

Please note:

• In each run directory, we provide a GEOS–Chem restart file that you can use to initialize your simulation. However, it is highly recommended that you not use these restart files for any of your production runs. Rather, you will probably want to generate your own restart file by spinning up the model for at least a year.

• If you need a restart file for an offline simulation (e.g. offline aerosol, mercury, tagged CO, etc), you can use the GAMAP routine make_restart.pro to create a "fake" restart file. You can also ask the other members of the GEOS–Chem Mailing List if they have a restart file for the particular type of simulation that you are trying to do.

• When you clone, you will always get the most recent state of the repository. If, you wish to download the run directories for an older version of GEOS–Chem (say v8–03–01) with Git, please follow these instructions.

2.4 Downloading the GEOS–Chem shared data directories

The GEOS–Chem shared data directories contain the various met fields, emissions, and other data that GEOS–Chem will read in during the course of a simulation. You must download the shared data directories via FTP or a similar utility (e.g. wget, FireFTP, SecureFX, etc.) The large volume of data makes it impossible to track this directory structure with Git.

If your research group consists of several GEOS–Chem users, then perhaps someone (i.e. your sysadmin or local IT guru) has already downloaded the GEOS–Chem shared directory structure to a common disk space on your servers. Nevertheless, you should still check to make sure that you have the most recent data directories and subdirectories. See Chapter 4 for complete details about the contents of the GEOS–Chem shared data directories.

2.4.1 Data archives

You may download the GEOS–Chem shared data directories from one of two archives:

1. Harvard archive (ftp.as.harvard.edu)
2. Dalhousie archive (rain.ucis.dal.ca)

The Dalhousie archive is not as comprehensive as the Harvard archive. However, the Dalhousie archive stores data files for the various nested grids and global 1° x 1.25° grids that are not available on the Harvard archive.

For those of you who are interested in using GEOS–Chem with the GCAP data, please contact Loretta Mickley for more information.

2.4.2 Downloading instructions

We recommend that you use the GNU wget utility to download the GEOS–Chem shared data directories. Wget allows you to download the directories and subdirectories in one fell swoop. The wget commands take the form of:

wget -r -nH "ftp://ftp.as.harvard.edu/gcgrid/geos-chem/data/DIRECTORY_NAME/"

where DIRECTORY_NAME is the name of the directory you want to download. Please see our wiki page on how to download data with wget for more information.

You can also download the shared data directories via anonymous FTP:

ftp ftp.as.harvard.edu
cd gcgrid/geos-chem/data/GEOS_0.25x0.3125_CH
cd gcgrid/geos-chem/data/GEOS_0.25x0.3125_NA
cd gcgrid/geos-chem/data/GEOS_0.5x0.666_CH
cd gcgrid/geos-chem/data/GEOS_0.5x0.666_NA
cd gcgrid/geos-chem/data/GEOS_1x1
cd gcgrid/geos-chem/data/GEOS_2x2.5
cd gcgrid/geos-chem/data/GEOS_4x5
cd gcgrid/geos-chem/GEOS_MEAN
cd gcgrid/geos-chem/GEOS_NATIVE
cd gcgrid/gcap/GCAP_4x5

However, for those of you who are located at Harvard, you do not need to download this data, as it is available on the Harvard internal filesystem, in directories:

/as/data/geos/GEOS_0.25x0.3125_CH
/as/data/geos/GEOS_0.25x0.3125_NA
/as/data/geos/GEOS_0.5x0.666_CH
/as/data/geos/GEOS_0.5x0.666_CH
/as/data/geos/GEOS_1x1
/as/data/geos/GEOS_2x2.5
/as/data/geos/GEOS_4x5
/as/data/geos/GEOS_MEAN
/as/data/geos/GEOS_NATIVE
/as/data/gcap/GCAP_4x5

If you wish to download data from the Dalhousie data archive, use this command:

wget -r -nH "ftp://rain.ucis.dal.ca/ctm/DIRECTORY_NAME/"

Please see the following links for more information:

1. Chapter 4: GEOS–Chem data directories
2. GEOS–Chem wiki: Downloading GEOS–Chem data directories
3. GEOS–Chem wiki: Using wget to download data

2.5 Installing netCDF with the GEOS-Chem-Libraries package

GEOS–Chem v9–02 requires that you have a netCDF library installation on your 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	or netCDF classic
netcdf–4.2	netCDF "CLASSIC". This lacks the advanced features of netCDF–4.2, and is more or less identical to netCDF–3.6.
zlib–1.2.6 (netcdf–4.2 depends on this)
hdf5–1.8.8 (netcdf–4.2 depends on this)

We recommend that you try to build the netCDF-4.2 library first, since this a more recent netCDF version. The netCDF-4.2 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.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.

2.5.1 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:

File or Directory	Description
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.

2.5.2 Installing netCDF–4.2

Follow these instructions to install the netCDF–4.2 library and the libraries on which it depends.

2.5.2.1 Building the netCDF–4.2 library

To build the netCDF-4.2 library (and the dependent ZLIB and HDF5 libraries) using the Intel Fortran Compiler (ifort), type one of the following 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 one of the following commands:

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:

Option	Description
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 its related libraries were installed properly.

2.5.2.2 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

Now that you have installed netCDF–4.2, you may skip ahead to Chapter 2.5.4: Telling GEOS–Chem where to find the netCDF libraries.

2.5.3 Installing netCDF CLASSIC

If you have problems installing the netCDF–4.2 libraries on your system, try installing netCDF classic instead. Follow these instructions:

2.5.3.1 Building netCDF CLASSIC

To build the netCDF CLASSIC libraries (which lacks the advanced features of netCDF-4.2) using the Intel Fortran Compiler (ifort), type one of the following 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 compilers

Makefile options:

Option	Description
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 netCDF CLASSIC 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/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.

2.5.3.2 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

2.5.4 Telling GEOS-Chem where to find the netCDF libraries

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:

Setup file	Unix shell
.cshrc	If you use C-shell (csh) or T-shell (tcsh)
.profile	If you use Bourne shell (sh), or if you use a Macintosh
.bashrc	If you use Bourne-again shell (bash)

There are three environment variables that you need to set:

Variable	Description
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)

2.5.4.1 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.

2.5.4.2 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 ~/.profile or source ~/.bashrc at the Unix prompt.

2.5.5 For more information

Please see our Installing libraries for GEOS–Chem page on the GEOS–Chem wiki for more detailed information about the GEOS-Chem-Libraries installer program. On this page we give an overview of the individual library files that are generated and the commands used to link to them. You will find this useful if you need to write other Fortran data processing software requiring netCDF file I/O.

Previous | Next | Printable View (no frames)