2. Installation and Compilation

2.1 Obtaining the GEOS–CHEM Source Code

The first step is to obtain the current version of the GEOS–CHEM model. The most recent GEOS–CHEM release is available for download from the GEOS–CHEM Source Code and Data Files page. You may also download data and input files for the GEOS–CHEM model from this site. For security reasons, the site is password protected. Contact Bob Yantosca (bmy@io.harvard.edu) to get the current password.

The current GEOS–CHEM source code and benchmark simulation output are contained in a GNU-zipped TAR file (i.e. the extension is *.tar.gz), which is also known as "tarball" format. To unzip the file, type:

gunzip GEOS–CHEM.v6–02–05.stdrun.tar.gz

and to extract the files, type:

tar xvf GEOS–CHEM.v6–02–05.stdrun.tar

This will create a directory named geos.v6–02–05, which is further divided into subdirectories:

Code.v6–02–05	Directory containing the GEOS–CHEM source code
IDL	Directory containing IDL code to process benchmark output
runs/geos.v6–02–05	Contains run.fullchem and run.Rn-Pb-Be directories.
runs/geos.v6–02–05/run.fullchem	Contains output from v5–07–08 full-chemistry benchmark simulation.
runs/geos.v6–02–05/run.Rn-Pb-Be	Contains output from v5–07–08 radionuclide (Radon-Lead-Beryllium) benchmark simulation.

Each GEOS–CHEM version is benchmarked with a standard full-chemistry simulation so that the results of a given version may be compared to the results of the prior version. In this way, errors in coding, emissions, or chemistry mechanisms may be readily discerned. Also, for GEOS–CHEM versions which may alter the convection or transport routines, a radionuclide (Radon-Lead-Beryllium) benchmark will also be performed. The output files from the benchmark runs as well as PostScript plots are provided in the run.fullchem and run.Rn-Pb-Be subdirectories of the geos.v6–02–05 directory.

For non-Harvard GEOS–CHEM users: you should attempt to perform both full-chemistry and radionuclide benchmark simulations on your own platform. This will help you to determine if GEOS–CHEM is working correctly at your location.

2.2 Obtaining the GEOS–CHEM run directories

TAR files containing sample GEOS–CHEM run directories are stored on the GEOS–CHEM download page. To install the 4 x 5 run directories, type the following at the Unix prompt:

gunzip GEOS–CHEM.v6–02–05.rundir4x5.tar.gz
tar xvf GEOS–CHEM.v6–02–05.rundir4x5.tar

This will create 4 x 5 run directories named:

/run.v6–02–05.geos1 /run.v6–02–05.geoss
/run.v6–02–05.geos3 /run.v6-02-05.geos4

which will store input files and a restart file for the 4 x 5 GEOS–1, GEOS–STRAT, GEOS–3 and GEOS–4 grids. The input files assume that you want to perform a full-chemistry simulation. You can modify the input files to specify other types of GEOS–CHEM simulations; see Section 5 for more details.

To install the 2 x 2.5 run directories, you can follow the same procedure listed above. (If you have just extracted the 4 x 5 run directories, make sure to rename them or move them to a new directory so that the extraction of the 2 x 2.5 directories won't overwrite them). Type the following at the Unix prompt:

gunzip GEOS–CHEM.v6–02–05.rundir2x25.tar.gz
tar xvf GEOS–CHEM.v6–02–05.rundir2x25.tar

This will extract directories named

/run.v6–02–05.geos1 /run.v6–02–05.geoss
/run.v6–02–05.geos3 /run.v6-01-05.geos4

these directories will contain input files and restart files for the 2 x 2.5 GEOS–1, GEOS–STRAT, GEOS–3 and GEOS–4 grids. As with the 4 x 5 directories, the input files are preset to select a full-chemistry simulation.

GEOS–CHEM restart files are provided in order to provide you with a set of initial conditions that you can start your model runs with. 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.

2.3 Obtaining the GEOS–CHEM data directories

You may now download all of the files in the GEOS–CHEM data directories from the data server geos.as.harvard.edu. If you do not have an account on this machine, please contact our systems administrator Jack Yatteau.

To download the 4 x 5 data directories, you may use ftp or sftp:

ftp geos.as.harvard.edu
cd /geos/data/GEOS_4x5

and then you can download each of the individual subdirectories which contain the various GEOS–CHEM 4 x 5 input files.

Likewise, to extract the 2 x 2.5 data directories, type the following at the Unix prompt:

ftp geos.as.harvard.edu
cd /geos/data/GEOS_2x2.5

and then you can download each of the individual subdirectories which contain the various GEOS–CHEM 2 x 2.5 input files.

2.4 Setting the C-preprocessor switches

Before compiling the GEOS–CHEM model, you must set the proper C-preprocessor switches to tell the compiler which options you would like compiled into the GEOS–CHEM executable. These switches are located in header file define.h, and are as follows:

GEOS_1	Use GEOS–1 met fields (20 layer, 1985-1995 )
GEOS_STRAT	Use GEOS–STRAT met fields (26 layer, 1996-1997 )
GEOS_3	Use GEOS–3 met fields (48 layer, 1998-2001 )
GEOS_4	Use GEOS–4 met fields (55 layer, hybrid, 1999-)
A_LLK_03	Use GEOS–4 obsolete "a_llk_03" data set for 2003
GRID1x1	Use 1 x 1 grid (for nested grids)
GRID2x25	Use 2 x 2.5 grid
GRID4x5	Use 4 x 5 grid
GRID30LEV	Use 30-level GEOS-3 or GEOS-4 vertical grid
FULLCHEM	Use full SMVGEAR chemistry mechanism
LGEOSCO	Use Bryan Duncan's CO chem w/ parameterized OH
LFASTJ	Use FAST-J photolysis code from UC Irvine
LSLOWJ	Use traditional SLOW-J photolysis code
COMPAQ	Compile for HP/Compaq Alpha
IBM_AIX	Compile for IBM/AIX
LINUX_PGI	Compile for Linux with PGI compiler
LINUX_IFC	Compile for Linux with 32-bit Intel IFC compiler
LINUX_EFC	Compile for Linux with 64-bit Intel EFC compiler
SGI_MIPS	Compile for SGI Origin with MIPSpro compiler
SPARC	Compile for Sun/Sparc

The C-Preprocessor Switches in define.h take the form of:

!#define GEOS_1 'GEOS_1'

The quotes are necessary to facilitate compilation on the Linux platforms.

In order to activate a particular switch, simply remove the comment character (exclamation mark) from the first column of the line. To de-activate a switch, simply place a comment character (exclamation mark) in the first column of the line.

Note that you may only select one particular met field type (GEOS_1, GEOS_STRAT, GEOS_3, GEOS_4), one particular grid type (GRID1x1, GRID2x25, GRID4x5), and one particular chemical mechanism (FULLCHEM, LGEOSCO).

Also, there are two different versions of GEOS–4 met field data. Data produced before January 1, 2004 are known as the "Version 3" or a_llk_03 data. Data produced on or after January 1, 2004 are known as the "Version 4" or a_flk_04 (first-look) and a_llk_04 (late-look) data. There are some minor scientific differences between the two data sets. However, a more significant difference is that the timestamps of the 6-hour averaged 3-D fields in the two data sets differ by 3 hours. If you are using the GEOS–4 "Version 3" data set, then you must uncomment the a_llk_03 flag in the define.h file.

If you will be running a simulation which requires photolysis, you must pick one of either LFASTJ or LSLOWJ. If your simulation does not require photolysis, you may leave both LFASTJ and LSLOWJ deactivated.

2.5 Compiling the GEOS–CHEM source code

Once you are satisfied that the C-preprocessor switches in the define.h header file are set properly for the type of simulation that you want to perform, you can proceed to compile the code.

At present, GEOS–CHEM ships with 7 makefiles, which are used to build the executable via the Unix make utility. The makefiles are named as follows:

Makefile.compaq		for HP/Compaq Alpha
Makefile.ibm		for IBM/AIX
Makefile.pgi		for Linux with PGI compiler (e.g. Linux Boxes)
Makefile.ifc		for Linux platform with IFC compiler (e.g. Linux boxes)
Makefile.efc		for Linux platform with EFC compiler (e.g Itanium)
Makefile.sgi		for SGI Origin
Makefile.sparc		for Sun/SPARC

NOTES:

• Sun compilers expect Fortran source code file names to end in the extension .F instead of the usual .f. Bob Yantosca has a Perl script which named f2F which can be used to rename the source code files. At some point in the future we may rename all of the GEOS–CHEM source code files to end in .F.
  
  
• The SGI Altix machines (with Itanium chips) run the Linux operating system. However, you must use the 64-bit EFC compiler in order to compile GEOS–CHEM on this type of machine. This is a slightly different compiler than the 32-bit IFC compiler, which is normally used for Linux boxes.

For your convenience, GEOS–CHEM now ships with a Perl script named build, which compiles the model using the proper Makefile for your operating system. To compile the GEOS–CHEM model, simply type:

To select a particular compilation option type:

build [option-name]

for any platform

where allowable Makefile option-names are:

geos		Compile GEOS–CHEM w/ FAST-J photolysis (Default)
geos_sj		Compile GEOS–CHEM w/ SLOW-J photolysis (mostly obsolete)
geosco		Compile GEOS–CHEM w/ parameterized CO-OH chemistry
clean		Removes all pre-compiled executables and object files

Note that geos_sj (GEOS–CHEM with SLOW–J photolysis) is now more or less obsolete; however, there may be a special instance when you want to compile with this option. Likewise, geosco should only be used if you are running GEOS–CHEM with parametericed CO and OH chemistry (cf. Bryan Duncan).

By default, the Makefile will create a multi-processor GEOS–CHEM executable (the name will be the same as option-name). This is adequate for most applications. However, for testing purposes, it may be desirable to create a single-processor GEOS–CHEM executable. This is possible and only involves a bit of extra effort.

If you look near the very top of the Makefile (for now let's assume the SGI version), you will see the following lines:

# F90 compiler options
FFLAGS = f90 -cpp -64 -O3 -OPT:reorg_common=off

# F90 Options -- multiprocessor
F90 = $(FFLAGS) -mp -Dmultitask

# F90 Options -- single processor
#F90 = $(FFLAGS)

If instead you would like to build a single-processor executable, then follow these steps:

1.	Type build clean. This will remove all previously compiled object files.
2.	Add a comment character (#) in front of the FF in the "F90 Options -- Multiprocessor" line near the top of the Makefile.
3.	Remove the comment character (#) from the FF in the "F90 Options -- Single Processor" line near the top of the Makefile.
4.	Type build [option-name] with the appropriate Makefile option (see above).

You may also add extra F90 compiler options to either the single processor or multi-processor compilation lines in the Makefile. For example, to also add subscript error checking to the multi-processor compile option (for SGI), then add a -C to the Fortran compiler options line:

FFLAGS = f90 -cpp -64 -O3 -OPT:reorg_common=off -C

For more information about subscript error checking, please see Section 6.5.1, GEOS–CHEM debugging tips.

2.6 Compiling the GEOS–CHEM Source Code with Unix Shell Scripts

It is possible to write a shell script to compile the GEOS–CHEM code, such as the following:

#!/bin/tcsh -f	# script definition line
cd Code.v6–02–05	# your code dir
rm -f log	# clear log file
build geos > log	# build code
exit(0)	# exit normally

which can then be submitted to either the LSF or PBS batch queue system (depending on which queue system is used on your computers).

You can even write one script to both compile and run the GEOS–CHEM model:

#!/bin/tcsh -f	# script definition line
cd Code.v6–02–05	# your code dir
rm -f log	# clear log file
build geos > log	# build code
mv geos ../run.v6–02–05	# move exec file
cd ../run.v6–02–05	# change dir
geos >> log	# append output to log file
exit(0)	# exit normally

Likewise, this script may also be submitted to the LSF or PBS batch queue systems.

(Non-Harvard users: ask your local computer guru about how to submit batch jobs on your own system.)

Bob Yantosca has compiled a convenient package of shell scripts named TESTRUN, which allows you to compile and run the GEOS–CHEM model automatically. A nice feature of TESTRUN is that it renames the log and binary punch files, so that successive model runs do not conflict with each other. TESTRUN is compatible with both LSF and PBS batch queue systems.

For more information on running the GEOS–CHEM model, see Section 6, Running GEOS–CHEM.