Introduction To Atmospheric Chemistry

Atmospheric Sciences > GEOS-Chem Model > Manuals > GEOS-Chem Online User's Guide > Chapter 1
GEOS-Chem Online User's Guide
Previous | Next | Printable View (no frames)
GEOS-Chem v11-02-final will also carry the designation GEOS-Chem 12.0.0. We are migrating to
a purely numeric versioning system in order to adhere more closely to software development best
practices. For a complete description of the new versioning system, please see our GEOS-Chem
version numbering system wiki page.
1. Introduction
1.1 Overview
GEOS-Chem Community Mission: to advance understanding of human and natural influences on

the environment
through a comprehensive, state-of-the-science, readily accessible global model of atmospheric
composition.
GEOS-Chem is a global 3-D chemical transport model (CTM) for atmospheric composition driven by meteorological
input from the Goddard Earth Observing System (GEOS) of the NASA Global Modeling Assimilation Office (GMAO). It
is applied by research groups around the world to a wide range of atmospheric composition problems. Scientific
direction of the model is provided by the GEOS-Chem Steeting Committee and by User Working Groups. The model is
managed by the GEOS-Chem Support Team, based at Harvard University and Dalhousie University.
This User's Guide provides information and instructions for installing and running GEOS-Chem. Much of the GEOS-
Chem documentation has been moved to the GEOS-Chem online wiki located at http://wiki.geos-chem.org/. Wiki
hyperlinks are provided throughout this guide directing you to where you can find in-depth information on different
GEOS-Chem topics. We encourage you to explore the GEOS-Chem wiki to supplement the information provided in this
User's Guide and to access the most up-to-date information available for GEOS-Chem. If you are new to GEOS-Chem,
please read the GEOS-Chem welcome letter for new users as well as the GEOS-Chem Overview for a brief description
of GEOS-Chem and how it is managed.
This User's Guide is arranged as follows:
Chapter Description
1. Introduction (This page) Provides a brief overview of GEOS-Chem and

guidelines for how to be an active and responsible participant in
the GEOS-Chem community.
2. Requirements for Installing GEOS- Lists required software packages that you need to run GEOS-
Chem Chem.
NEW! GEOS-Chem can now be run on the Amazon EC2 cloud.
3. The NetCDF Library Describes how to load the netCDF library on your system.
4. The GEOS-Chem Shared Data Describes how to download the shared data directories for the
Directories emissions and meteorology data that drive GEOS-Chem
simulations.
5. The GEOS-Chem Source Code Describes how to download the GEOS-Chem source code.
Directory
6. The GEOS-Chem Run Directories Describes how to generate run directories for the various GEOS-
Chem simulations and the input and output files of GEOS-Chem.
7. Compiling GEOS-Chem Describes how to compile the GEOS-Chem source code into an
executable file.
8. Coding and Debugging Lists resources for writing efficient code and for debugging GEOS-
Chem.
9. GEOS-Chem Components Describes the various components that make up GEOS-Chem

(e.g. transport, chemistry).
10. GEOS-Chem Species Describes the GEOS-Chem species that are used in each type of
simulation and how you can add new species to an existing
simulation.
11. Meteorological Fields Describes the meteorological data fields used by GEOS-Chem.
12. Horizontal and Vertical Grids Describes the horizontal and vertical grids used by GEOS-Chem.
13. Diagnostics Describes the diagnostics generated by GEOS-Chem.
14. GEOS-Chem Reference Contains links to the reference guides that are automatically
generated from the GEOS-Chem source code and the GEOS-
Chem coding style guide.
15. GEOS-Chem Version History Lists new features in each GEOS-Chem version.
16. High Performance GEOS-Chem Describes the development of an MPI implementation for GEOS-
Chem.
1.2 Participation in the GEOS-Chem User Community
Development of the GEOS-Chem model and its adjoint is a grass-roots activity by individual scientists pursuing their
own research interests and sharing their work for the benefit of all. Being a GEOS-Chem user therefore comes with
expectations and responsibilities. Please read and follow the guidelines below to help us maintain an active and vibrant
GEOS-Chem community.
1. Send an email to geos-chem-support [at] as.harvard.edu containing a paragraph describing how you and
the other members of your research group plan to use GEOS-Chem. We will add this to the GEOS-Chem
People and Projects web page. Registering your group helps us to accurately track how many research
groups are using GEOS-Chem.
2. Subscribe to the general GEOS-Chem email list and to an email list of one or more Working Groups. The
general GEOS-Chem email list is where we make announcements about new model releases, bugs and fixes,
and other information of interest to the entire GEOS-Chem community. In addition, each GEOS-Chem
Working Group has its own email list that group members use to discuss various aspects of model
development and validation. Please see the Subscribing to the GEOS-Chem email lists wiki page for
instructions.
3. We encourage you to join a Working Group that is most relevant to your area of research. The Working
Groups foster communication and collaboration between GEOS-Chem users and they identify priorities for
model development to the GEOS-Chem Steering Committee. Please take a moment to introduce yourself to
any relevant Working Group via email.
4. Adhere to the list of best practices. In particular, if you discover a problem (e.g. bugs, missing files, numerical
issues, etc.), please alert the GEOS-Chem Support Team right away. Other GEOS-Chem users will most
certainly benefit from your discovery!
5. We encourage you to send us your timing results from a 7-day time test. This will allow us to keep a list of how
the model is performing across several different platform/compiler combinations. We will post this information
on the GEOS-Chem performance wiki page.
6. Please read the GEOS-Chem Credits and References page containing guidelines for giving appropriate credit
to developers through co-authorship or citation. You may also refer to the Narrative Description of the GEOS-
Chem Model wiki page for assistance with correctly citing relevant model components of the current standard
version of GEOS-Chem in your publications.
1.3 New features
See the following pages for a list of new features in GEOS-Chem v12.0.0 (aka v11-02-final) and for details on the 1-
month and 1-year benchmark simulations used to validate this version.
 List of new intermediate benchmarked versions and the features they contain
 GEOS-Chem v11-02 benchmark history
1.4 Bugs and technical issues that have been fixed
GEOS-Chem 12.0.0 (aka v11-02-final) contains fixes and for several bugs and technical issues. If you have been using
an older version of GEOS-Chem (e.g. v11-01, v10-01), please check this list to see if any outstanding issues have since
been resolved.
 Issues resolved in GEOS-Chem 12.0.0 (aka v11-02-final)

 Issues resolved in GEOS-Chem 12.0.0 (aka v11-02-final)
A few issues still remain unresolved (or cannot be resolved due to compiler bugs, etc.). For more information, please
see:
 Currently unresolved issues in GEOS-Chem

 Known issues caused by compiler bugs
Atmospheric Sciences > GEOS-Chem Model > Manuals > GEOS-Chem Online User's Guide > Chapter 2
GEOS-Chem v11-02-final will also carry the designation GEOS-Chem 12.0.0. We are migrating to
a purely numeric versioning system in order to adhere more closely to software development best
practices. For a complete description of the new versioning system, please see our GEOS-Chem
version numbering system wiki page.
2. Getting set up with GEOS-Chem
2.1 Useful skills for working with GEOS-Chem
In order to use GEOS-Chem, it is helpful to have general experience with the following:
 Programming using the Fortran programming language

 Generating graphics using visualization software (Python is gaining populatrity!)
 Working with a version of the Unix operating system (e.g. familiarity with unix commands and file paths)
 Exposure to working with and writing Unix scripts
 Familiarity with using Git for source code management
For a useful list of resorces, including tutorials, please see the GEOS-Chem basics and Version control with Git wiki
pages.
2.2 Where can I run GEOS-Chem?
You can run GEOS-Chem on the following types of machines:
Architecture Description
Any computer system running a These include the Linux (Red Hat, CentOS, SuSE), Fedora, Ubuntu,
version of the Unix operating etc. operating systems.
system
Please see the following wiki pages for a list of required system
software (compilers, libraries, and utilities) that you will need to install
before you can run GEOS-Chem on your system.
 GEOS-Chem basics
 Minimum system requirements for GEOS-Chem
o Hardware requirements
o Software requirement
o Disk space requirements
If you are not sure what hardware or software is available to you, then
please check with your IT department. For the most up-to-date
information regarding GEOS-Chem performance on specific platforms
and operating systems, please see ourGEOS-Chem performance wiki
page.
NOTE: While it may be possible to run GEOS-Chem on Windows (via a
Unix emulator such as CygWin), we cannot officially support this
platform.
Amazon Web Services If your institution does not have its own computer cluster, or if you are
Elastic Compute (EC2) cloud looking for some extra computational capacity not available at your
institution, you might want to consider running GEOS-Chem on the
Amazon EC2 cloud. This brings the following advantages:
 You can easily initialize your computational environment with a

predefined machine image. A machine image is a "snapshot"
of the operating system, CPU type, and required software
(such as compilers, netCDF, and MPI libraries).
 Your computational enviroment can be initialized with the
exact same hardware and software each time you log in. This
will ensure that your GEOS-Chem simulations will be 100%
reproducible.
 All of the input data (meteorological fields, emissions, etc.)
required to run GEOS-Chem have already been uploaded to
the Amazon S3 storage system. This will let you get started
with GEOS-Chem right away, without having to download
terabytes of data to a local disk server.
For more information, please see Jiawei Zhuang's very comprehensive

cloud computing tutorial: cloud-gc.readthedocs.io.
(NOTE FOR ADVANCED USERS: If you need to use a different

compiler, or a newer netCDF version than those provided with the
default machine image, then you can install those packages on your
own and create your own machine image. See Jiawei's tutorial for more
information.)
2.3 Additional downloads
The required software packages mentioned in the prior section—the compilers, the operating system, the Git version
control system, etc.—will usually come pre-installed on your system (or machine image if you are using the Amazon
cloud). The most important items that you will still need to download to your system are the following:
Item Description
A NetCDF Library Most of the data files read by GEOS-Chem v11-02 are now
in COARDS-compliant netCDF format. As part of the High-Performance
Computing (HPC) GEOS-Chem project, we are in the process of
converting the remaining binary data files to netCDF format. This will
facilitate running GEOS-Chem in HPC environments, a requirement for
several objectives such as interfacing GEOS-Chem with the NASA
GEOS-5 GCM.
 If you are using the Amazon EC2 cloud, then a netCDF

library will be included in the machine image that you use to
initialize your computational environment. (If you are an
advanced user, you can also create your own machine image
with the netCDF version that you wish.)
 If you are using your institution's computer system, then
your IT staff may have already pre-built one or more versions
of the netCDF library that you can load into your Unix
environment. If not, then you can build a netCDF library with
our installer package.
For more information, please see Chapter 3.
GEOS-Chem Shared Data The GEOS-Chem shared data directories contain many large files (e.g.
Directories(including the sample emissions, metorological fields) that cannot fit into your own personal
restart files) disk space. We recommend that you (or your IT staff) download the
shared data directories to a common disk space where all GEOS-Chem
users in your group or institution can access them.
 If you are using the Amazon EC2 cloud, then a copy of the
shared data directories has been synced to the Amazon S3
storage system. For more information about how to access the
data, please see Jiawei Zhuang's cloud computing
tutorial cloud-gc.readthedocs.io.
 If you are using your institution's computer system: You
will only need to download the shared data directories from
disk once from scratch. As new met fields or emissions data
are added, you can download the new folders and files
individually. (NOTE: If several people at your institution are
alreasy using GEOS-Chem, then chances are the shared data
directories have already been downloaded to a location on
your disk storage server. Check with your IT staff.)
GEOS-Chem Source Code The GEOS-Chem source code is available for download to your
Directory personal disk space using the Git source code management system.
GEOS-Chem Run Directories You must create a run directory for each combination of meteorology
field , grid resolution, and simulation type that you use. Run directories
are created with our GEOS-Chem Unit Tester and may be stored locally
in your personal disk space.

GEOS-Chem basics
The GEOS-Chem Support Team has created this page to assist new GEOS-Chem users to
download and run GEOS-Chem on their computer systems.
Contents
[hide]
 1 Overview
o 1.1 GEOS-Chem requirements
o 1.2 GEOS-Chem documentation and support
 2 Unix resources
o 2.1 Common Unix commands
o 2.2 Unix shells and shell scripting
o 2.3 Perl scripting
 3 The GNU Make utility
 4 The Git source code management system
 5 Fortran resources
o 5.1 Online tutorials
o 5.2 The GNU Fortran compiler
o 5.3 The Intel Fortran compiler
 6 The netCDF library
o 6.1 netCDF on Amazon cloud
o 6.2 netCDF on your system
o 6.3 netCDF references
 7 The GEOS-Chem source code
 8 The GEOS-Chem Unit Tester
o 8.1 Creating run directories with the Unit Tester
 9 The GEOS-Chem shared data directories
 10 Restart files
 11 Visualization packages
o 11.1 GAMAP and other IDL software
o 11.2 Python software
 12 The GEOS-Chem website
 13 The GEOS-Chem wiki
o 13.1 Overview
o 13.2 Wiki Philosophy
o 13.3 Logistics
 14 GEOS-Chem tutorials
 15 For more information
Overview
GEOS-Chem requirements
Before you can run GEOS-Chem, you will need to have the following items. Some of these will
be already pre-installed on your computer system.
Item Description
EITHER You will need a Unix operating system environment in order to run GEOS-Chem. Any flavor
of Unix (e.g. CentOS, Ubuntu, Fedora, etc.) should work just fine.
A Unix-based
computer system If your institution has computational resources (e.g. a shared computer cluster with many
cores, sufficient disk storage and memory), then you can run GEOS-Chem there. Contact
OR
your IT staff for assistance.
an account on
If your institution lacks computational resources (or if you need additional computational
the Amazon Web
resources beyond what is available), then you should consider signing up for access to the
Services cloud
Amazon Web Services cloud. Using the cloud has the following advantages:
 You can run GEOS-Chem without having to invest in local hardware and maintenance
personnel.
 You won't have to download any meteorological fields or emissions data. All of the
necessary data input for GEOS-Chem will be available on the cloud.
 You can initialize your computational environment with a pre-compiled "machine

image" containing all of the required software (e.g. compilers, libraries, utilities) that
you need for GEOS-Chem.
 Your GEOS-Chem runs will be 100% reproducible, because you will initialize your
computational environment the same way every time.
 You will avoid GEOS-Chem compilation errors due to library incompatibilities.
 You will be charged for the computational time that you use, and if you download data
off the cloud.
GEOS-Chem v11-02 will be the first version that is compatible for cloud-computing. You can
learn more about how to use GEOS-Chem on the cloud by visiting this tutorial.
We will post more information about how to get set up on the Amazon Web Services cloud
shortly.
GNU Make GNU Make directs the compilation sequence. It tells the compiler the order in which files
should be compiled, which compilation options to use.
You probably won't have to install GNU Make, since it comes with most Unix distributions
by default. GNU Make will also be available for you on the Amazon cloud.
Git (a source code The Git source-code management software is a free and open-source package that we use to
management system) enforce strict version control. You will also Git to download the GEOS-Chem source code
and the GEOS-Chem Unit Teseter.
Git is usually installed by default with most Unix distributions. It will also be available for
you on the Amazon cloud.
A Fortran compiler GEOS-Chem is written in the Fortran language. A Fortran compiler is used to create an
executable file from the GEOS-Chem source code. You can use either the GNU Fortran
Compiler (aka gfortran) or the Intel Fortran Compiler (aka ifort) to compile GEOS-Chem.
If you have an account on a shared computer cluster at your institution, chances are that you
will at least have a GNU Fortran Compiler version installed, and maybe a version of Intel
Fortran installed as well. Ask your IT staff for more information.
You will need the GNU Fortran Compiler to compile GEOS-Chem on the Amazon cloud.
This will already be available for you, so you won't have to install it manually.
A netCDF library GEOS-Chem uses the netCDF file format for I/O. Many GEOS-Chem restart and diagnostic
installation output files are written to netCDF format.
If you are using GEOS-Chem on a local computer cluster, then you (or your IT staff) will
need to install a version of netCDF. Chances are there might be one or more netCDF versions
pre-installed for you. Ask your IT staff for assistance.
If you are using GEOS-Chem on the Amazon cloud, then a netCDF library will already be
available for you to use.
A GEOS-Chem This directory contains the GEOS-Chem source code, which the compiler will assemble into
source code directory an executable file.
The GEOS-Chem source code can be downloaded via Git from our repository on
Bitbucket.org.
The GEOS-Chem The GEOS-Chem Unit Tester is used to error-check all of the GEOS-Chem simulations. It is
Unit Tester also needed to construct GEOS-Chem run directories, in which the compiled executable file
will run.
The GEOS-Chem Directory structure containing the meteorology and emissions data that GEOS-Chem reads as
shared data input.
directories
If you are using GEOS-Chem on a local computational cluster, then you will need to
download these data manually. We recommend to:
 Download the meteorological fields from the Dalhousie data archive
 Download the emissions data for HEMCO from the Harvard data archive.
The shared data directories for GEOS-Chem v11-02 and higher versions will be available on
the Amazon cloud, so you won't have to download them. You may need to tell your login
environment where to find these data. We will post more information on this shortly.
Restart files for These are the files containing the initial conditions for a GEOS-Chem simulation. They can
GEOS-Chem be downloaded from our data archive via FTP.
 GEOS-Chem v11-01 and higher versions only reads and writes restart files in netCDF
format.
A visualization This is software that is used to read and plot output from GEOS-Chem simulations.
package
Traditionally, the IDL-based GAMAP has been used for plotting GEOS-Chem-generated
data. Starting with GEOS-Chem v11-02, you will have the option to save diagnostic output
directly to netCDF data. This will give you the option to open-source plotting packages based
in the Python language.
Please also see our GEOS-Chem User's Guide for complete information about how to set up a
GEOS-Chem simulation.
--Bob Yantosca (talk) 17:20, 16 March 2018 (UTC)
GEOS-Chem documentation and support
We have compiled a list of online GEOS-Chem documentation.
Item Description
The GEOS-Chem Support

Team (aka GCST)  Responsible for GEOS-Chem software development, user support, and
documentation.
The GEOS-Chem website

(geos-chem.org)  The main GEOS-Chem website, which links to many other resources.
The GEOS-Chem wiki

(wiki.geos-chem.org)  The GEOS-Chem wiki (i.e. this wiki), which is now the main knowledge base
for GEOS-Chem.
The GEOS-Chem User's Guide

(manual.geos-chem.org)  The user manual for GEOS-Chem. Contains instructions on how to install,
download, compile, and run GEOS-Chem on your system.
The GEOS-Chem FAQ

 Answers to the most commonly-asked questions about GEOS-Chem.
GEOS-Chem licensing
 Information about the public license under which GEOS-Chem (and related
software) are distributed.
GEOS-Chem tutorial
presentations  Several online tutorial presentations about how to use GEOS-Chem
Coding and debugging tips

 Helpful hints for writing and debugging new GEOS-Chem source code.
Unix resources
GEOS-Chem is designed to run on computers with the Unix operating system. There is no
single version of Unix; rather, Unix comes packaged in several different distributions. Many
modern computer clusters use CentOS, which is an open-source Unix implementation. Other
systems may use a proprietary Unix distribution, such as Red Hat Enterprise. GEOS-Chem will
perform in the same way regardless of the specific Unix implementation on your system.
If you require assistance setting up or customizing your Unix login environment, please contact
your local IT staff. The GEOS-Chem Support Team can only provide support for GEOS-Chem-
related issues.
Very soon you will also have the opportunity to run GEOS-Chem on the Amazon Web Services
cloud infrastructure. We will post more information about that shortly.
IMPORTANT! Please make sure that your computer system meets the minimum system
requirements for memory and disk space in order to run GEOS-Chem.
Common Unix commands
The resources below cover many common Unix commands. You will find these useful,
particularly if you have never worked on a Unix machine before.
 Thirty useful Unix commands (U. Cambridge)

 Summary of Unix commands (PDF doc)
 A Brief Introduction to Unix (by Corey Satten)
 The 15 Essential Unix commands (by Pete Freitag)
Unix shells and shell scripting
One of the nice features of Unix is that you can highly customize your environment. You can also
write scripts to perform several commands (such as copying files or running programs)
sequentially. This will save you the trouble of having to type the same commands over and over
at the command-line prompt.
There are several Unix shells that you can use, but we recommend using bash. Here are some
resources that you can use to learn more about the bash shell:
 What is the .bashrc file on SuperUser

 The Bash Shell Startup Files from Beyond Linux from Scratch
 LinuxCommand.org—interactive tutorial
 How to use the Unix alias command
 Bash Guide for Beginners
 Advanced Bash scripting
 Bash programming—Introduction How-To
--Bob Yantosca (talk) 20:11, 19 September 2017 (UTC)
Perl scripting
Perl is a language that is often used for writing scripts. A Perl parser comes pre-installed with
your Unix distribution. Perl provides many of the same features as do Unix shell scripts, but also
make it very easy to do text comparison and manipulations.
For more information about writing Perl scripts, please see:
 Perl.com
 Perl in 20 pages
 Beginning Perl by Simon Cozens (free online book)
 Robert's Perl Tutorial
 Comprehensive Perl Archive Network (CPAN.org)
--Bob Yantosca (talk) 21:14, 2 November 2016 (UTC)
The GNU Make utility

The GNU Make utility is used to compile GEOS-Chem—that is, to create an executable file from
source code. GNU Make usually comes pre-packaged with your Unix distribution (e.g. CentOS,
Linux, Ubuntu, Fedora, etc.), so you will probably not need to install it yourself.
GEOS-Chem contains several Makefiles. A Makefile contains several commands in the GNU
Make language direct how the Fortran compiler will build GEOS-Chem. Makefiles determine the
sequence in which individual files are compiled, as well as the options that will be activated.
Unless you are going to be adding a significant amount of new code into GEOS-Chem, you will
probably not need to know the nitty-gritty details of how to create or modify Makefiles. But if you
do have to change an existing Makefile, you can contact the GEOS-Chem Support Team, who
will be happy to assist you.
If you are interested in learning more about the GNU Make utility, we invite you to consult the
following resources:
 The GNU Make manual

 GNU Make in detail for beginners at OpenSource.com
 Using Make and writing makefiles at Swarthmore U.
 Make at wikibooks.org
 Managing projects with GNU Make by O'Reilly
For specific information about compiling GEOS-Chem, see:
 GEOS-Chem User's Guide: Chapter 7: Compiling GEOS-Chem

 GEOS-Chem wiki: GEOS-Chem Makefile Structure
--Bob Yantosca (talk) 19:40, 19 December 2016 (UTC)
The Git source code management system

Given the large number of user code submissions, robust source code management techniques
must be employed in order to ensure the integrity of the GEOS–Chem code. The GEOS-Chem
Support Team has selected the Git version control software for GEOS–Chem source code
management.
There are several useful online resources for Git. We recommend starting with:
 GEOS-Chem wiki: Version control with Git

 GEOS-Chem wiki: Using Git with GEOS-Chem
 Our list of tutorials about Git
 git-scm.com—The official Git site
Fortran resources
GEOS-Chem is written in the Fortran computer language, and relies upon of the new features
that were introduced with the Fortran-90 standard. We list below several useful resources for
your reference. Please also see our list of supported compiler versions.
Online tutorials
If you are new to Fortran (or are familiar with the older Fortran-77 standard but not Fortran-90),
then we invite you to take one or more of these tutorials:
 FortranTutorial.com
 Introduction to Modern Fortran (Cambridge Univ, UK)
 Victor Decyk (UCLA) Fortran tutorial
 Fortran 90 for the Fortran 77 programmer
 Using OpenMP parallelization with Fortran
The GNU Fortran compiler
GEOS-Chem v11-01 and newer versions are compatible with the GNU Fortran compiler,
aka gfortran. This is a free and open-source compiler that comes pre-installed on many
modern computer systems. This will be our recommended compiler, starting with GEOS-Chem
v11-02.
 GNU Fortran compiler page on the GEOS-Chem wiki

 Gfortran home at GNU.org
If you will be running GEOS-Chem on the Amazon Web Services cloud computing environment,
we recommend that you use GNU Fortran.
The Intel Fortran compiler
Many users compile GEOS-Chem with the Intel Fortran compiler (aka ifort).
 Intel Fortran compiler page on the GEOS-Chem wiki

 Intel Fortran Compiler manual (Version 11.1)
The netCDF library

GEOS-Chem reads and writes data in the netCDF file format. NetCDF is a self-describing format,
which means that it can keep data fields together with "metadata"—the information describing
each data field— in the same file. This makes it very easy to share GEOS-Chem output with
other researchers.
netCDF on Amazon cloud
If you are running GEOS-Chem on the Amazon Web Services cloud, then you will initialize your
Unix environment with a machine image that contains a pre-built netCDF library. So you will not
need to build the netCDF library yourself.
The GEOS-Chem Support Team is currently preparing the Amazon cloud environment for
GEOS-Chem. We will post more information about this shortly.
netCDF on your system
Ask your IT staff if a version of netCDF has already been pre-built on your system. On many
systems, the IT staff will create several different builds of netCDF to accommodate different
compilers (and sometimes MPI versions). You may be able to load a netCDF library version with
the module command, i.e.
module load netcdf
Your system might also permit the use of Docker containers, which will allow you to load a pre-
built Unix environment with all necessary libraries, including netCDF.
netCDF references
We have also collated the following references about netCDF, which you might find useful.
 Our Preparing data files for use with HEMCO page on the GEOS-Chem wiki
 netCDF Home Page
 netCDF Documentation
 NCL (NCAR Command Language) (useful for netCDF and other file I/O)
The GEOS-Chem source code

The GEOS-Chem model source code is kept in a publicly-accessible Git repository. You
must compile the source code into an executable file with one of the supported Fortran
compilers. The compilation is managed by the GNU Make utility, which reads the various GEOS-
Chem makefiles to produce the executable with the desired options.
You can download the source code for the latest GEOS-Chem version if you have Git installed
on your system. For more information and detailed downloading instructions, please see:
 GEOS-Chem User's Guide: Chapter 2: Requirements for installing GEOS-Chem

 GEOS-Chem User's Guide: Chapter 5: The GEOS-Chem source code directory
 GEOS-Chem User's Guide: Chapter 7: Compiling GEOS-Chem
 GEOS-Chem wiki: Setting Unix environment variables for GEOS-Chem
 GEOS-Chem wiki: Downloading GEOS-Chem source code and data
The GEOS-Chem Unit Tester

The GEOS-Chem Unit Tester is a package of scripts and Makefiles that will compile and run
several GEOS-Chem with a set of standard debugging flags. The Unit Tester is one of our best
GEOS-Chem debugging tools. For more information, please see:
 GEOS-Chem wiki: GEOS-Chem Unit Tester

Creating run directories with the Unit Tester
You can use the GEOS-Chem Unit Tester to create a run directory specific to the GEOS-Chem
simulation that you want to perform. A run directory is where the GEOS-Chem executable file will
be placed. You will normally keep GEOS-Chem run directories in your own disk space. The run
directories contain several input files which are used to "customize" the GEOS-Chem simulation
as follows:
 To specify start and end dates of simulation

 To specify which GEOS-Chem options to turn on/off
 To specify the species/reactions/cross-sections in the photolysis mechanism
 To specify diagnostic output options
For more information, please see the following resources:
 GEOS-Chem wiki: Creating GEOS-Chem run directories
 GEOS-Chem wiki: HEMCO data directories
 GEOS-Chem wiki: Setting up the ExtData directory
The GEOS-Chem shared data directories

In addition to the files contained in the run directories, GEOS-Chem also needs to access data
directories containing:
 Meteorological data (a.k.a. the "met fields) used to drive GEOS–Chem

 Emissions inventories used by GEOS-Chem
 Scale factors 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.
These files are often too large to store in a single user's disk space. Therefore, they are meant to
be stored in shared disk space where all GEOS-Chem users in your group can have access to
them.
The GEOS-Chem shared data directories can be downloaded from archives at Harvard
University and Dalhousie University. Unlike the source code and run directories, the data
directory download can be done either by anonymous FTP or by the freely-available GNU wget
utility. (We recommend wget because it is much more flexible and can be used to download
several directories recursively.)
For more information and detailed downloading instructions, please see:

 GEOS-Chem wiki: HEMCO data directories
 GEOS-Chem wiki: Restart files
Restart files
You will need a restart file before you can start your GEOS-Chem simulation. A restart file
contains the initial conditions for a GEOS-Chem simulation. There are two restart files for GEOS-
Chem:
1. GEOS-Chem restart file containing instantaneous species concentrations (Required)

2. HEMCO restart file containing values needed for some of the HEMCO
extensions (Optional)
When you run a GEOS-Chem simulation, it will write new GEOS-Chem restart files at the
intervals you specify in input.geos. New HEMCO restart files are written with frequency
configured in HEMCO_Config.rc if HEMCO is used in your simulation.
GEOS-Chem v11-01 run directories are configured to use initial GEOS-Chem restart files
in netCDF format. These files are available for download at:
ftp://ftp.as.harvard.edu/gcgrid/data/ExtData/SPC_RESTARTS/
CAVEAT: The initial restart files do not reflect the actual atmospheric state and should
only be used to "spin up" the model. In other words, they should be used as initial values
in an initialization simulation to generate more accurate initial conditions for your
production runs.
Doing a one year spin up is usually sufficient; however, we recommend ten years for ozone,
carbon dioxide, and methane simulations, and four years for radon-lead-beryllium simulations. If
you are in doubt about how long your spin up should be for your simulation, we recommend
contacting the GEOS-Chem Working Group that specializes in your area of research.
You may spin up the model starting at any year for which there is met data, but you should
always start your simulations at the month and day corresponding to the restart file to more
accurately capture seasonal variation. If you want to start your production run at a specific date,
we recommend doing a spin up for the appropriate number of years plus the number of days
needed to reach your ultimate start date. For example, if you want to do a production simulation
starting on 12/1/13, you could spin up the model for one year using the initial GEOS-FP restart
file dated 7/1/13 and then use the new restart file to spin up the model for five additional months,
from 7/1/13 to 12/1/13.
To determine the date of a netCDF restart file, you may use ncdump For example:
ncdump -v time -t initial_GEOSChem_rst.4x5_standard.nc
The -t option will return the time value in human-readable date-time strings rather than
numerical values in unit such as "hours since 1985-1-1 00:00:0.0." The date of a binary punch
restart file can be determined by opening the file in GAMAP.
Using a HEMCO restart file for your initial spin up run is optional. The HEMCO restart file
contains fields for initializing variables required for Soil NOx emissions, MEGAN biogenic
emissions, and the UCX chemistry mechanism. The HEMCO restart file that comes with a run
directory may only be used for the date and time indicated in the filename. HEMCO will
automatically recognize when a restart file is not available for the date and time required, and in
that case HEMCO will use default values to initialize those fields. You can also force HEMCO to
use the default initialization values by setting "HEMCO_RESTART" to false
in HEMCO_Config.rc. For more information, see the HEMCO User's Guide.
You can read more about restart files at the GEOS-Chem output files wiki page.
--Melissa Sulprizio (talk) 16:03, 12 January 2017 (UTC)
Visualization packages
In this section we provide information about software packages that you can use to analyze and
plot GEOS-Chem output.
GAMAP and other IDL software
NOTE: IDL, which is proprietary software, can be very expensive. For this reason,
the GEOS-Chem Support Team and other GEOS-Chem developers are currently
developing several open-source software packages (mostly based on Python) for GEOS-
Chem data analysis and visualization. Please see our Python software section below.
The traditional GEOS-Chem visualization software is GAMAP. This package was customized to
GEOS-Chem and is still heavily used today. GAMAP requires the Interactive Data Language (a
proprietary package). For more information about GAMAP, please see:
 GAMAP web page

 GAMAP online manual
 Documentation for individual GAMAP routines
 GEOS-Chem wiki: GAMAP tips and tricks
We have also compiled a list of other useful IDL software sites.
 IDL Astronomy User's Library

 JHU/APL/S1R IDL routines page
 Craig Markwardt's IDL library
Python software
Several developers have started creating Python-based visualization software for GEOS-Chem.
Please see the following page for more information:
 GEOS-Chem wiki: Python code for GEOS-Chem

 GCPy: Python powered GEOS-Chem data analysis/visualization (Currently under
development)
If you are new to programming in Python, you may find these tutorials useful:
 Google's Python course

 Python 3 tutorial
 Learn Python the hard way book

The GEOS-Chem website is located at http://www.geos-chem.org.
From this website you may:
 Read a welcome letter which outlines user responsibilities

 Read the online GEOS-Chem User's Guide
 Access GEOS-Chem-related publications
 View online presentations from GEOS-Chem user meetings
 See a list of who is using GEOS-Chem at other institutions
 Obtain information about the GAMAP visualization package
Also, please take a minute to read the GEOS-Chem overview page. This document outlines the
responsibilities for all GEOS-Chem users.
PLEASE NOTE: At this time, the GEOS-Chem User's Guide is only viewable in HTML.
The GEOS-Chem wiki

Overview
The GEOS-Chem wiki (i.e. this wiki) is located at: http://wiki.seas.harvard.edu/geos-chem/. The
alias http://wiki.geos-chem.org also links to the wiki.
The wiki has many features that are designed to facilitate communication between GEOS-Chem
users and developers. The following informaton is posted on the wiki:
 The latest public version and current version in development

 Getting started with GEOS-Chem
 Technical Information
 Information about the specifics of:
 Chemistry mechanisms and specialty simulations
 Emissions
 Aerosols
 Diagnostics
 A list of bugs and when they were fixed
 Information about meteorology used as input to GEOS-Chem
 Information about data visualization and analysis
The Main Page of the wiki contains links to several commonly-read pages. If you can't find your
desired topic, the best way to search for information on the wiki is by using the Search Box
located in the upper right corner of each wiki page.
Wiki Philosophy
We encourage all GEOS-Chem code developers and users to check the wiki frequently, as this is
the place where the latest information about GEOS-Chem will be posted. The wiki is designed to
be a two-way street of communication. Users should feel free to add content to the wiki pages
that are most closely related to their research.
In particular, the GEOS-Chem Support Team has begun an effort to make sure that all 3rd-party
code and data that is submitted into GEOS-Chem has a corresponding wiki page. This will
ensure that all information can be shared transparently.
Logistics
All GEOS-Chem wiki posts can be read by anyone. However, to add or modify wiki pages, you
will need to register for a wiki account. Simply click on the "Log In/Create Account" link at the top
right of your browser window. The GEOS-Chem support team will confirm your account request
(this is an anti-spamming measure).
The best way to find information on the GEOS-Chem wiki is to use the Search Box located in the
upper right corner of each wiki page. The Main Page has links to several topics on the wiki but it
does not link to every single page.
You can let the GEOS-Chem wiki inform you of recent updates to the site via RSS. Click here to
find out how. You will never miss a discussion!
We invite all GEOS-Chem users to read our post about wiki user culture.
GEOS-Chem tutorials
Please see the following GEOS-Chem tutorials, mostly taken from previous GEOS-Chem
meetings:
 GEOS-Chem for beginners (IGC8 model clinic)

 GEOS-Chem for advanced users (IGC8 model clinic)
 GEOS-Chem adjoint (IGC8 model clinic)
 GEOS-Chem in massively parallel and ESM environments (IGC7 model clinic)
--Melissa Sulprizio (talk) 19:32, 12 May 2017 (UTC)
For more information

You can find much more information about GEOS-Chem on our website and wiki. We invite you
to consult the following resources:
 GEOS-Chem User's Guide

 The HEMCO User's Guide
 Frequently asked questions about GEOS-Chem
 What should I do if my GEOS-Chem simulation dies with an error?
 Where can I find information about GEOS-Chem performance and GEOS-Chem Scalability?
 Is there a comprehensive list of bugs and when they were fixed?
Minimum system requirements for GEOS-
Chem
GEOS-Chem v11-02-final will also carry the designation GEOS-Chem

12.0.0. We are migrating to a purely numeric versioning system in order to adhere
more closely to software development best practices. For a complete description of
the new versioning system, please see ourGEOS-Chem version numbering
system wiki page.
Several GEOS-Chem users have asked "What type of machine do I need to buy in order to run
GEOS-Chem?" Here are our suggestions.
Contents
[hide]
 1 Hardware Recommendations
o 1.1 Memory requirements
o 1.2 Computer architecture
o 1.3 Network and disk
o 1.4 Utilizing cloud-computing resources
 2 Software Requirements
o 2.1 Overview
o 2.2 Supported compilers
o 2.3 Parallelization
 2.3.1 OpenMP
 2.3.2 MPI
 3 Performance and scalability
 4 Estimated Disk Space
o 4.1 Emissions fields
o 4.2 Met fields
 5 Do I need to install any libraries for GEOS-Chem?
o 5.1 Required libraries for GEOS-Chem
o 5.2 Libraries that you may need for certain data sets
Hardware Recommendations
Here is some useful information that you can use to determine if your system has sufficient
resources to run GEOS-Chem simulations.
Memory requirements
Item Description
Enough memory to run For the 4° x 5° "standard" simulation

GEOS-Chem
 At least 6-8 GB RAM

For the 2° x 2.5° "standard" simulation:
 About 20-25 GB RAM

Chris Holmes reported that a 2° x 2.5° "standard" simulation required:
 20 GB memory (MaxRSS)
 26 GB virtual memory (MaxVMSize)
Extra memory for You may want to consider at least 30 GB RAM if you plan on doing any of the following:
special simulations
 Running high-resolution (e.g. 1° x 1° or higher resolution) global GEOS-Chem

simulations
 Running high-resolution (e.g. 0.5° x 0.667° or 0.25° x 0.3125°) nested-grid GEOS-

Chem simulations
 Running 2° x 2.5° global GEOS-Chem simulation and saving a lot of output fields (the
more output you generate the more memory GEOS-Chem will require)
Chris Holmes reported that a GEOS-FP 0.25° x 0.3125° NA tropchem nested simulation
required:
 31 GB memory (MaxRSS)
 38 GB virtual memory (MaxVMSize)
Sufficient disk storage

 Sufficient disk storage for met fields
for met fields
Computer architecture
Jun Wang wrote:
We have an opportunity to build a large HPC. Do you what configuration works best for GEOS-
Chem?
Bob Yantosca replied:

You won’t need the GPU-accelerated nodes for GEOS-Chem. GC or GCHP will probably not be
much able to take advantage of GPUs because (1) the Nvidia CUDA instructions are not
included in the Intel Fortran compiler, (2) Writing GPU code is probably above the GCST’s skill
level at this time, and (3) Right now the only Fortran compiler that can use GPUs is the PGI
compiler.
This is the output of the /proc/cpuinfo file on the computational nodes we use at Harvard (i.e. the
Odyssey cluster). You can ...see how it compares with [your system].
processor : 0
vendor_id : GenuineIntel
cpu family : 6
model : 63
model name : Intel(R) Xeon(R) CPU E5-2680 v3 @ 2.50GHz
stepping : 2
cpu MHz : 2494.085
cache size : 30720 KB
physical id : 0
siblings : 12
core id : 0
cpu cores : 12
apicid : 0
initial apicid : 0
fpu : yes
fpu_exception : yes
cpuid level : 15
wp : yes
flags : fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge
mca cmov pat pse36
clflush dts acpi mmx fxsr sse sse2 ss ht tm pbe
syscall nx pdpe1gb rdtscp
lm constant_tsc arch_perfmon pebs bts rep_good
xtopology nonstop_tsc aperfmperf
pni pclmulqdq dtes64 monitor ds_cpl vmx smx est tm2
ssse3 fma cx16 xtpr pdcm pcid
dca sse4_1 sse4_2 x2apic movbe popcnt
tsc_deadline_timer aes xsave avx f16c rdrand
lahf_lm abm ida arat epb xsaveopt pln pts dts
tpr_shadow vnmi flexpriority ept vpid
fsgsbase bmi1 avx2 smep bmi2 erms invpcid
bogomips : 4988.17
bogomips : 4988.17
clflush size : 64
cache_alignment : 64
address sizes : 46 bits physical, 48 bits virtual
power management:
So our CPUs run at 2.5 GHz, and there are 24 CPUs/node. Each CPU has 30 MB of cache. I
think there is 4.5 to 5 GB of memory per CPU available.
Also - if you are going to use the Intel Fortran Compiler, you will always get the best
performance when using Intel CPUs. It is a known issue that the Intel Fortran Compiler
does not optimize well on AMD CPUs. This was intentional. For more information, see this
article.
GEOS-Chem v11-01 and newer versions are compatible with the GNU Fortran compiler, which
yields nearly-identical results (within the bounds of numerical noise) to simulations that use the
Intel Fortran Compiler, at the cost of somewhat slower performance. GNU Fortran should also
perform more optimally on AMD CPUs than Intel Fortran.
--Bob Yantosca (talk) 19:11, 25 April 2017 (UTC)
Network and disk
Hong Liao wrote:
We are setting up a new cluster and we have the option of installing InfiniBand network (using
Mellanox hardware) and GPFS.
My questions are:
1. Will GEOS-Chem compile and run all right on clusters based on InfiniBand and GPFS?
2. Will GEOS-Chem benefit from InfiniBand?
I can say a couple of general things:
1. On our Harvard cluster (Odyssey) we use Infiniband to connect to a fast network disk
(/n/regal). I don't know if that filesystem is GPFS.
2. For GEOS-Chem "Classic" simulations, with OpenMP parallelization, you can only use
one node of the machine. So in that case you won't be doing node-to-node
communications. The only I/O would be from the CPU to the disk, and I think in that case
Infiniband can make a great difference.
3. For GCHP, which uses MPI parallelization, then you would also have to be concerned
with inter-node communication, as you will be using CPUs across more than 1 node.
4. The disk where our met fields live at Harvard is on a Lustre file system. This is more
efficient for applications like GC that read a large volume of data.
Judit Flo Gaya replied:
What Bob said is correct, I just want to point out that GPFS and Lustre are "similar" file systems
in the sense they both are parallel filesystems, they work differently and they charge differently.
They are both a lot more cumbersome to configure, maintain and debug than regular nfs, but
they provide (when well implemented and tweaked) a significant increase in the performance of
reading and writing files.
--Bob Yantosca (talk) 20:38, 27 October 2017 (UTC)

Utilizing cloud-computing resources
CAVEAT: We STRONGLY advise that you check with your cloud computing provider if
there are substantial fees to upload and store large amounts of data (such as the GEOS-
Chem met fields and emissions data) before starting any GEOS-Chem simulations "in the
cloud".
Bob Yantosca wrote:
Dear GEOS-Chem Users!
We have some exciting news to share with you! Jiawei Zhuang (Harvard) has proven that GEOS-
Chem “Classic” can run on cloud computing resources, such as the Amazon Elastic Compute
Cloud (EC2) servers. This important new development will allow you to:
 Set up GEOS-Chem simulations quickly without having to invest in a local computing

infrastructure
 Run GEOS-Chem simulations that are memory and/or data-intensive (e.g. 1/4 degree
nested-grid simulations)
 Purchase only the computational time and data storage that you need (and easily request
more resources)
 Easily share data with others through the “cloud”
Two important recent developments make GEOS-Chem cloud computing possible:
1. Compatibility with the GNU Fortran compiler
An important (but probably understated) development is that GEOS-Chem v11-01 and newer can
now be compiled with the free and open-source GNU Fortran compiler (aka gfortran). Bob
Yantosca and Seb Eastham have removed and/or rewritten several sections of legacy code that
GNU Fortran could not compile. Due to their diligence, GEOS-Chem v11-01 is now compatible
with GNU Fortran v4, and GEOS-Chem v11-02 will be compatible with GNU Fortran v6 (the
latest version).
GNU Fortran breaks GEOS-Chem’s dependence on proprietary compilers like Intel Fortran (aka
ifort) and PGI Fortran (aka pgfortran), which can be prohibitively expensive to purchase. The
GNU Fortran (and C/C++) compilers come pre-installed on most versions of the Linux operating
system today (and if not, they are easy to install). GNU Fortran also can produce executables
that can optimize well for many different types of CPUs (Intel, AMD, etc).
To validate the performance of GEOS-Chem with GNU Fortran, we ran two 1-month benchmark
simulations for v11-02, one with Intel Fortran v11.1 and another with GNU Fortran v6.2. We
posted a summary of the results on the GEOS-Chem wiki, which you can read by clicking this
link.
As you can see from the wiki, the v11-02a benchmark using GNU Fortran gives essentially
identical results (within the bounds of numerical noise) to the v11-02a benchmark using Intel
Fortran. The run time for several GEOS-Chem operations is somewhat slower, but we believe
that this might be improved with some streamlining of code. We believe that having a longer run
time is an acceptable tradeoff for not having to purchase an expensive Intel Fortran or PGI
Fortran license.
2. Development of a Python-based visualization and regridding software for GEOS-Chem
We are developing a new visualization/regridding package for GEOS-Chem (called GCPy) that is
based on the free and open source Python programming language. Our first use of GCPy
was to create the plots for the GCHP benchmark simulations. While GCPy is currently not ready
for public use (as of April 2017), we will work on improving its usability in the very near future.
Having an option like GCPy will finally let us reduce our dependence on IDL based software (e.g.
GAMAP). An IDL license is now very expensive to purchase, and is out of reach for some GEOS-
Chem user groups.
In addition to GCPy (which is still in development), there are other Python-based visualization
packages for GEOS-Chem (developed by several members of the GEOS-Chem user
community) that you can use right away. For more information, please see our Python code for
GEOS-Chemwiki page.
Jiawei Zhuang has created a tutorial on how you can set up GEOS-Chem on the Amazon EC2
compute platform. He also has collated several of the input files that you will need to customize
your login environment on EC2. For more information, please see his Github site: https://cloud-
gc.readthedocs.io.
P.S. At present it is not yet possible to run GCHP (our high-performance GEOS-Chem) on the
Amazon EC2 platform, due to various technical issues. We will be looking into this in the near
future.
Software Requirements
Overview
Please see this list of required software packages on our GEOS-Chem basics page.
A few notes:
1. The Linux flavor (RedHat, SuSE, Fedora, Ubuntu, etc.) is not important. Also, 64-bit
architecture is not an issue with GEOS-Chem.
2. GEOS-Chem is written in the Fortran–90 language. Fortran-90 is an extension of Fortran-
77, which for many years has been the standard programming language for scientific
computing. GEOS-Chem takes advantage of several powerful features of Fortran-90,
including dynamic memory allocation, modular program design, array operation syntax,
and derived data types. Please view Appendix 7: GEOS-Chem Style Guide in the
GEOS-Chem manual for more tips on how to write effective Fortran-90 code.
3. We use the Git version control software to manage and track GEOS-Chem software
updates. Git allows users at remote sites to easily download GEOS-Chem over the
network. Git also enables users to keep track of their changes when developing the code
and enables the creation of patches that would simplify the implementation of new
developments in the standard version. For all these reasons, you must install Git so that
you can download and manage your local GEOS-Chem source code.
Supported compilers
As of 2016, the following platforms and compilers are supported. The majority of GEOS-Chem
users compile GEOS-Chem with the Intel Fortran Compiler. GEOS-Chem v11-01 and higher
versions are now compatible with the GNU Fortran compiler as well.
In GEOS-Chem v11-01 and later versions, the Fortran compiler environment
variables must be set.
Tested
Platform Compiler Status
by
Linux ifort 15.0.0 and Supported GCST

similar builds
 NOTE: IFORT 15 has a compiler bug that causes errors when turning
on array-out-of-bounds checking and optimization.
Linux ifort 13.0.079 Supported GCST
and similar
builds
Linux ifort 12 Supported GCST
 NOTE: compiler bug in ifort 12 and higher versions has forced us to

add a workaround to HEMCO. In v11-01 we will test if this is resolved
by the recent code updates.
Linux ifort 11.1.069 Supported GCST

and similar
builds
 NOTE: This is an old version (2008). The GCST uses this version to
benchmark GEOS-Chem, in order to ensure numerical compatibility
between different benchmark versions.
Linux ifort 10.1 Supported (but this is an old version by now) GCST
Linux gfortran 4.4.7 Supported GCST
Linux gfortran 4.8.2 Supported GCST
Linux gfortran 5.x.x Supported GCST
Linux gfortran 6.x.x Supported GCST
Linux pgfortran 14.10 Supported GCST
 Validation of benchmark results is still needed.
--Bob Yantosca (talk) 20:40, 27 October 2017 (UTC)

Parallelization
OpenMP
You should be aware that because GEOS-Chem uses OpenMP parallelization, you can only run
on as many nodes as are shared by the memory. For example, if you had 2 PC's, and each PC
w/ 4 cores each, then you can only run on 1 PC at a time (i.e. 4 cores). This is because OpenMP
has a requirement that all of the processors on the machine must be able to see all of the
memory on the machine. In that case, you could run 2 jobs simultaneously on 4 cores, but not a
single job on 8 cores. See OpenMP.org for more information.
Our traditional configuration of GEOS-Chem, known as "GEOS-Chem Classic", cannot use MPI
capability. It is parallelized with the OpenMP parallelization directives.
MPI
MPI (Message Passing Interface) is required for passing memory from one physical system to
another. For example, if you wanted to run a GEOS-Chem simulation across several
independent machines (or nodes of a cluster), then this requires MPI parallelization. OpenMP
parallelization cannot be used unless all of the CPUs on the machine have access to all of the
memory on the machine (a.k.a. shared-memory architecture).
Our High-performance version of GEOS-Chem (aka GCHP) can use OpenMPI and MVAPICH2
versions of the MPI parallelzation library.
Performance and scalability

Please see the following resources for more information about the performance and scalability of
GEOS-Chem on various platform/compiler combinations:
1. GEOS-Chem performance wiki page

2. 1-month benchmark timing results for various platform/compiler combinations
3. Wiki post about GEOS-Chem scalability on hyperthreaded chipsets
4. Machine-specific issues and portability issues
5. GEOS-Chem v9-02 performance
Estimated Disk Space

Emissions fields
Please see our HEMCO data directories wiki page for a list of disk space requirements for each
of the emissions inventories read into GEOS-Chem by the HEMCOemissions component.
For GEOS-Chem v11-01, the entire size of the HEMCO data directories is about 375 GB total.
Depending on the types of GEOS-Chem simulations you run, you may not need to download the
entire set of emissions inventories.
Met fields
The amount of disk space that you will need depends on two things:
1. Which type of met data you will use, and

2. How many years of met data you will download
Typical disk space requirements are:
Met field Resolution File type Size
MERRA- COARDS-compliant netCDF

4° x 5° ~ 30 GB/yr
2 (compressed)
MERRA- COARDS-compliant netCDF ~ 110

2° x 2.5°
2 (compressed) GB/yr

0.5° x 0.625 Asia ("AS") nested grid
MERRA- COARDS-compliant netCDF
0.5° x 0.625 Europe ("EU") nested grid ~ 58 GB/yr
2 (compressed)

0.5° x 0.625 North America ("NA") nested grid
COARDS-compliant netCDF
GEOS-FP 4° x 5° ~ 30 GB/yr
(compressed)
COARDS-compliant netCDF ~ 120

GEOS-FP 2° x 2.5°
(compressed) GB/yr
COARDS-compliant netCDF ~ 175

GEOS-FP 0.25° x 0.3125° China ("CH") nested grid
(compressed) GB/yr
COARDS-compliant netCDF
GEOS-FP 0.25° x 0.3125° Europe ("EU") nested grid ~ 58 GB/yr
(compressed)
0.25° x 0.3125° North America ("NA") nested COARDS-compliant netCDF ~ 226

GEOS-FP
grid (compressed) GB/yr
MERRA 4° x 5° Binary (uncompressed) ~ 70 GB/yr
~ 200
MERRA 2° x 2.5° Binary (uncompressed)
GB/yr
GEOS-5 4° x 5° Binary (uncompressed) ~ 30 GB/yr
~ 120
GEOS-5 2° x 2.5° Binary (uncompressed)
GB/yr
~ 140
GEOS-5 0.5° x 0.666° nested CH Binary (uncompressed)
GB/yr
~ 160
GEOS-5 0.5° x 0.666° nested NA Binary (uncompressed)
GB/yr
Do I need to install any libraries for GEOS-Chem?

The short answer is yes.
Required libraries for GEOS-Chem
We have begun the process of migrating GEOS-Chem's file I/O from binary files to netCDF files.
If you are using GEOS-Chem v9-01-03 or higher versions, you will need a version of the netCDF
library.
On many modern computer systems, libraries such as netCDF are pre-installed and available for
use via the module command. Be sure to check with your sysadmin or IT staff if a version of
netCDF has already been installed on your system. If so, you can just use load the pre-built
netCDF library into your environment with one or more module load statements. You can
usually place these statements into your .bashrc or .cshrc startup file so that netCDF is
loaded into your environment each time you log in to your account.
If your computer system does NOT already have a pre-built version of the netCDF libraries
installed, you can use our GEOS-Chem-Libraries installer to automate much of the netCDF
library installation for you. For more information about how to use the GEOS-Chem-
Libraries installer, please see our Installing libraries for GEOS-Chem wiki page, as well as
Chapter 3 of the GEOS-Chem User's Guide. If you work at an institution with several GEOS-
Chem users, then your sysadmin can help you to installl the netCDF library into a common
directory where everyone can access it.
Libraries that you may need for certain data sets
If you are working with large raw data files (e.g. "raw" GMAO met field data or one of the many
satellite data products), you may also need to install additional libraries. You can then link these
libraries to the Fortran code that you use to process your data.
Here is a table that describes the file formats that are used by the various data products:
Data type File format used
GEOS-4 met ("raw" data) HDF4-EOS
GEOS-5 met ("raw" data) HDF4-EOS
MERRA met ("raw" data) HDF4-EOS
GEOS-FP met ("raw" data) netCDF-4
MERRA-2 met ("raw" data) netCDF-4
MOPITT satellite data HDF4-EOS
AIRS satellite data HDF4-EOS
OMI satellite data HDF5-EOS
NOTES:
1. HDF4 is an older version of HDF. HDF5 is the newer version.

 One of the major differences is that with HDF4 the file size may not exceed 2GB.
This restriction has been lifted in HDF5.
2. HDF-EOS is a "superset" of HDF that was developed by NASA and others to create extra
data structures (Grid, Point, and Swath) that are more relevant for earth science
applications.
 HDF4-EOS is HDF-EOS that is based on HDF4.
 HDF5-EOS is HDF-EOS that is based on HDF5.
3. You must first install HDF4 before installing HDF4-EOS.
 HDF4 requires that ZLIB, JPEG, (and optionally, SZLIB) libraries must also be
installed.
4. You must first install HDF5 before installing HDF5-EOS
 HDF5 requires that ZLIB, JPEG, (and optionally, SZLIB) libraries must also be
installed.
5. netCDF-4 is the latest version of netCDF.
 netCDF-4 is 100% compatible with the older netCDF-3 format.
 netCDF-4 relies on HDF5, so you have to first build the HDF5 and ZLIB libraries
before installing netCDF-4.
It is also possible to read HDF, HDF-EOS, and netCDF files into IDL with the GAMAP
package. See the GAMAP User's Guide for more information.
The NCAR command language (NCL) can read data in all of these file formats.
--Bob Y. 16:25, 16 January 2014 (EST)
GEOS-Chem v11-02-final will also carry the designation GEOS-Chem 12.0.0.

We are migrating to a purely numeric versioning system in order to adhere more
closely to software development best practices. For a complete description of the
new versioning system, please see our GEOS-Chem version numbering system wiki
page.
3. The netCDF Library
3.1 A brief introduction to netCDF
GEOS-Chem reads and writes data using the netCDF file format. NetCDF is a self-
describing file format that can store data fields as well as the relevant "metadata", or
information about the contents of the file. Types of metadata include descriptive names,
units, horizontal and vertical, coordinates, file creation date/time, file history, etc.
The netCDF frequently asked questions (FAQ) guide gives this short overview of netCDF:
NetCDF (network Common Data Form) is a set of interfaces for array-oriented data access
and a freely distributed collection of data access libraries for C, Fortran, C++, Java, and
other languages. The netCDF libraries support a machine-independent format for
representing scientific data. Together, the interfaces, libraries, and format support the
creation, access, and sharing of scientific data.
NetCDF data is:
 Self-Describing. A netCDF file includes information about the data it contains.

 Portable. A netCDF file can be accessed by computers with different ways of
storing integers, characters, and floating-point numbers.
 Scalable. A small subset of a large dataset may be accessed efficiently.
 Appendable. Data may be appended to a properly structured netCDF file
without copying the dataset or redefining its structure.
 Sharable. One writer and multiple readers may simultaneously access the
same netCDF file.
 Archivable. Access to all earlier forms of netCDF data will be supported by
current and future versions of the software.
There are two commonly-used major versions of netCDF in use today:
 netCDF-3, aka "netCDF classic".

 netCDF-4
The major difference between the two versions is that netCDF-4 relies on the HDF5 library
"under the hood" whereas netCDF-3 does not. For this reason, netCDF-4 can be used to
store more data per file than netCDF-3.
A netCDF installation contains library files (ending in .a) , which hold compiled utility
routines meant to be called from programs written in C or Fortran. In netCDF-4.1 and prior
versions, the C-language library file (libnetcdf.a) and the Fortran-language library file
(libnetcdff.a) were always installed into the same folder by default. But starting with
netCDF-4.2, the netCDF Fortran libraries now must be built from a separate distribution
package. Because of this new configuration, you might find that
the libnetcdff.a (Fortran) and libnetcdf.a (C) library files are stored in separate
folders on your system. Ask your IT staff for more information about how netCDF is installed
on your system.
3.2 Loading the netCDF libraries on your system
If you are using GEOS-Chem on the Amazon EC2 cloud, then a version of netCDF will
ship with the machine image that you'll use to initialize your computational environment.
Therefore, you will not have to install netCDF yourself (unless you are an advanced user and
need a specific version for a particular application.)
If you are using GEOS-Chem on your institution's computer system, chances are that
your IT staff will have already installed one or more netCDF library versions that you can
use. For users that do not have the netCDF libraries intstalled on their system, the GEOS-
Chem Support Team has constructed the GEOS-Chem-Libraries installer package. See
the Installing libraries for GEOS-Chem wiki page for detailed instructions. Quick links to
subsections of that wiki page are included below:
 Check to see if netCDF is already installed on your system

 Use the Spack package manager to install netCDF if your system doesn't already
have it
 Setting environment variables for GEOS-Chem
 Working with netCDF data files
Installing libraries for GEOS-Chem
On this page we provide instructions on how to install netCDF-4 and related libraries for GEOS-
Chem.
Contents
[hide]
 1 Check to see if netCDF is already installed on your system
o 1.1 Special handling for netCDF-4.2 and higher versions
 2 If you don't have netCDF on your system, use Spack to install it
o 2.1 Downloading Spack
o 2.2 Using Spack to install netCDF libraries
o 2.3 Pointing GEOS-Chem environment variables to the Spack library paths
o 2.4 For more information
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 modulecommand. 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.
If you don't have netCDF on your system, use Spack to install it

The GEOS-Chem-Libraries installer contains library versions that might not be compatible with
the most recent Linux/Ubuntu/Fedora operating systems and gcc/gfortran and icc/ifort compilers.
In particular, several users have noticed that the build fails for gcc/gfortran compiler versions 4.8
and higher.
If you do not already have a pre-built netCDF library on your system, we recommend using the
Spack package manager to install the required libraries. Spack should be able to install netCDF
and all required libraries for a variety of compiler/platform combinations.
Downloading Spack
Clone the Spack repository, which is hosted at Github, to your disk space:
git clone https://github.com/spack/spack.git
Using Spack to install netCDF libraries

Then install the libraries by issuing these commands:
cd spack/bin
./spack install netcdf-cxx4 netcdf-fortran
The initial installation may take more than a half-hour to complete.

Pointing GEOS-Chem environment variables to the Spack library paths
To find the root paths where Spack has installed these libraries, type:
spack find --paths netcdf-cxx4

spack find --paths netcdf-fortran
And then define the environment variables in your .bashrc startup script (or .cshrc if you are
using csh/tcsh) to point to the following folders:
GC_BIN --> point this to the bin sub-folder of the netcdf-cxx4

root path
GC_INCLUDE --> point this to the include sub-folder of the netcdf-cxx4
root path
GC_LIB --> point this to the lib sub-folder of the netcdf-cxx4
root path
GC_F_BIN --> point this to the bin sub-folder of the netcdf-

fortran root path
GC_F_INCLUDE --> point this to the include sub-folder of the netcdf-
fortran root path
GC_F_LIB --> point this to the lib sub-folder of the netcdf-
fortran root path

For complete instructions on using Spack, please see: https://spack.readthedocs.io/en/latest/.
If you encounter an error while using Spack, it could be due to an incompatibility with your
particular compiler/platform combination. We encourage you to report all issues to the Spack
developers by opening a ticket on the Spack issue tracker: https://github.com/spack/spack/issues
Working with netCDF data files
On this page we provide some useful information about working with data files in netCDF format.
Contents
[hide]
 1 Useful tools
 2 Converting files from binary punch format to netCDF
o 2.1 Using Python
o 2.2 Using IDL
 2.2.1 Use GAMAP routine BPCH2COARDS
 2.2.2 Concatenate the netCDF files
o 2.3 Further Edit variable names and attributes
 3 Examining the contents of a netCDF file
 4 Reading the contents of a netCDF file
o 4.1 Reading data in Python
 5 Determining if a netCDF file is COARDS-compliant
 6 Edit variable names and atributes for COARDS compliance
 7 Regridding netCDF files
o 7.1 Issue with CDO remapdis regridding tool
 8 Cropping netCDF files
 9 Adding a new variable to a netCDF file
 10 Chunking and deflating a netCDF file to improve I/O
Useful tools
There are many free and open-source software packages readily available for visualizing and
manipulating netCDF files. These tools will reduce the need for the GEOS-Chem user community
to rely on IDL (and GAMAP), which can be prohibitively expensive for some user groups. Some
recommend tools are listed below.
Name Description
ncdump This command-line tool generates a text representation of netCDF data and can be used to quickly
view the variables contained in a netCDF file. The ncdump utility is installed with your netCDF library
distribution.
ncview Visualization package for netCDF files. Ncview has limited features, but is great for getting a quick look
at the contents of netCDF files..
Panoply Data viewer for netCDF files. This package offers an alternative to ncview. From our experience,
Panoply works nicely when installed on the desktop, but is slow to respond in the Linux environment.
nco and cdo Command-line tools for manipulating and analyzing netCDF files. Useful for renaming variables and
attributes, and for regridding data.
xarray Python package that lets you read the contents of a netCDF file into a data structure. The data can
then be further manipulated or converted to e.g. numpy arrays for further processing.
xbpch Python package that lets you read the contents of a binary punch file into an xarray Dataset object.
Panoply Data viewer for netCDF files. This package offers an alternative to ncview. From our experience,
Panoply works nicely when installed on the desktop, but is slow to respond in the Linux environment.
GCPy Python based package for visualizing and analyzing GEOS-Chem output. Currently under development.
GCPy will soon be used to produce the plots from GEOS-Chem 1-month and 1-year benchmark
output.
GAMAP Data visualzation package written in IDL. Although GAMAP is currently being phased out, GAMAP
routine BPCH2COARDS is still useful for converting data stored in the GEOS-Chem "binary punch"
format to netCDF format. See our Converting files from binary punch format to netCDF section below:
Some of the tools listed above, such as ncdump and ncview, may come pre-installed on your
system. Others may need to be installed or loaded (e.g. via the module load command). Check
with your system administrator or IT staff to see what is available on your system.
Converting files from binary punch format to netCDF

GEOS-Chem versions prior to GEOS-Chem v10-01 read emissions data from binary punch data
format. You will need to convert these data files to COARDS-compliant netCDF for use with
HEMCO.
Using Python
Perhaps the simplest way to create a netCDF file from a bpch file is to use
the xbpch and xarray Python packages. This can be done in only a few lines of Python!
#!/usr/bin/env python
import xarray as xr
import xbpch as xb
# Open the bpch file and save it into an xarray Dataset object
# NOTE: For best results, also specify the corresponding
# tracerinfo.dat diaginfo.dat metadata files
ds = xb.open_bpchdataset(filename="my_data_file.bpch",
tracerinfo_file="tracerinfo.dat",
diaginfo_file="diaginfo.dat")
# Write the xarray Dataset object to a netCDF file

ds.to_netcdf(‘my_data_file.nc‘)
Using IDL
Follow these instructions:
Use GAMAP routine BPCH2COARDS
You can use the GAMAP routine BPCH2COARDS to create netCDF files from a GEOS-Chem
binary punch file. For example, start IDL and then type this command at the IDL prompt:
IDL> bpch2coards, 'uvalbedo.geos.2x25', 'uvalbedo.geos.2x25.%DATE%.nc'
will create the following netCDF files:
uvalbedo.geos.2x25.19850101.nc
Note that BPCH2COARDS will create a new file for each time slice. The %DATE% token in the output
file name will be replaced with the year-month-day value for each time stamp. In the above
example, the binary punch file uvalbedo.geos.2x25 contains monthly data,
therefore BPCH2COARDS will create 12 individual netCDF files.
NOTE: You might sometimes have better luck using the BPCH_SEP routine to split the
bpch files into smaller bpch files (e.g. one per month) band then using bpch2coards on
the smaller files.
Special note for timeseries data: To use BPCH2COARDS to convert timeseries (e.g. hourly, 3-
hourly, etc) data to netCDF format, add the %TIME% token to the netCDF file name. For example:
IDL> bpch2coards, 'timeseries.geos.2x25',

'timeseries.geos.2x25.%DATE%.%TIME%.nc'
This will create one new netCDF file for each timestamp in the bpch file. You can then proceed to
Step 2 and Step 3 below to concatenate these files into a single netCDF file.
--Bob Y. (talk) 18:11, 1 June 2015 (UTC)
Concatenate the netCDF files
You can use the ncrcat commmand of the netCDF Operators (nco) to concatenate the 12
individual files created by BPCH2COARDSinto a single netCDF file. Make sure you have exited IDL,
and then type the following command at the Unix prompt:
ncrcat -hO uvalbedo.geos.2x25.1985*.nc uvalbedo.geos.2x25.nc
You can then discard the uvalbedo.geos.2x25.1985*.nc files that were created directly
by BPCH2COARDS.
--Bob Y. 12:10, 3 March 2015 (EST)
Further Edit variable names and attributes
Whether you use Python or IDL to create a netCDF file from a bpch file, you will still need to edit
the variable attributes in order to make the file COARDS-compliant. Please see this section
below for more information.
Examining the contents of a netCDF file

An easy way to examine the contents of a netCDF file is to use this command:
ncdump -cts EMEP.geos.1x1
You will see output similar to this:
netcdf EMEP.geos.1x1 {
dimensions:
lon = 360 ;
lat = 181 ;
time = UNLIMITED ; // (17 currently)
variables:
float lon(lon) ;
lon:standard_name = "longitude" ;
lon:long_name = "Longitude" ;
lon:units = "degrees_east" ;
lon:axis = "X" ;
lon:_Storage = "chunked" ;
lon:_ChunkSizes = 360 ;
lon:_DeflateLevel = 1 ;
float lat(lat) ;
lat:standard_name = "latitude" ;
lat:long_name = "Latitude" ;
lat:units = "degrees_north" ;
lat:axis = "Y" ;
lat:_Storage = "chunked" ;
lat:_ChunkSizes = 181 ;
lat:_DeflateLevel = 1 ;
double time(time) ;
time:standard_name = "time" ;
time:units = "hours since 1985-01-01 00:00:00" ;
time:calendar = "standard" ;
time:_Storage = "chunked" ;
time:_ChunkSizes = 524288 ;
time:_DeflateLevel = 1 ;
float PRPE(time, lat, lon) ;
PRPE:long_name = "Propene" ;
PRPE:units = "kgC/m2/s" ;
PRPE:gamap_category = "ANTHSRCE" ;
PRPE:_Storage = "chunked" ;
PRPE:_ChunkSizes = 1, 181, 360 ;
PRPE:_DeflateLevel = 1 ;
float ALK4(time, lat, lon) ;
ALK4:long_name = "Alkanes(>C4)" ;
ALK4:units = "kgC/m2/s" ;
ALK4:gamap_category = "ANTHSRCE" ;
ALK4:_Storage = "chunked" ;
ALK4:_ChunkSizes = 1, 181, 360 ;
ALK4:_DeflateLevel = 1 ;
... etc ...
// global attributes:
:CDI = "Climate Data Interface version 1.5.5
(http://code.zmaw.de/projects/cdi)" ;
:Conventions = "COARDS" ;
:history = "Wed Apr 23 17:36:28 2014: cdo mulc,10000
tmptmp.nc EMEP.geos.1x1.nc\n",
:Title = "COARDS/netCDF file created by BPCH2COARDS (GAMAP
v2-03+)" ;
:Model = "GEOS3" ;
:Grid = "GEOS_1x1" ;
:Delta_Lon = 1.f ;
:Delta_Lat = 1.f ;
:NLayers = 48 ;
:Start_Date = 19800101 ;
:Start_Time = 0 ;
:End_Date = 19810101 ;
:End_Time = 0 ;
:Delta_Time = 240000 ;
:Temp_Res = "CONSTANT" ;
:CDO = "Climate Data Operators version 1.5.5
(http://code.zmaw.de/projects/cdo)" ;
data:
lon = 180.5, 181.5, 182.5 ... etc... ;
lat = -89.75, -89, -88, -87 ... etc ... ;
time = "1980-01-01", "1985-01-01", "1986-01-01", "1987-01-01", "1988-01-

01",
"1989-01-01", "1990-01-01", "1991-01-01", "1992-01-01", "1993-01-01",
"1994-01-01", "1995-01-01", "1996-01-01", "1997-01-01", "1998-01-01",
"1999-01-01", "2000-01-01" ;
}
You can also use ncdump to display the data values for a given variable in the netCDF file. This
command will display the values in the SpeciesRst_NO variable to the screen:
ncdump -v SpeciesRst_NO GEOSChem_restart.20160701_0000z.nc4 | less
Or you can redirect the output to a file:
ncdump -v SpeciesRst_NO GEOSChem_restart.20160701_0000z.nc4
Reading the contents of a netCDF file

Reading data in Python
The easiest way to read a netCDF file is to use the xarray Python package.
# Imports
import xarray as xr
import numpy as np
# Read a restart file into an xarray Dataset object

ds = xr.open_dataset("GEOSChem.Restart.20160101_0000z.nc4")
# Print the contents of the DataSet

print(ds)
# Print the units of the SpeciesRst_O3 field

print(ds["SpeciesRst_O3"].units)
# Convert the SpeciesRst_O3 (O3 concentration) to

# a numpy array so that we can take the sum
O3_values = ds["SpeciesRst_O3"].values
# Take the sum of SpeciesRst_O3

sum_O3 = np.sum(O3_values)
print("Sum of SpeciesRst_O3: {}".format(sum_O3))
... etc ...
This above script will print the following output:
<xarray.Dataset>
Dimensions: (lat: 46, lev: 72, lon: 72, time: 1)
Coordinates:
* lon (lon) float64 -180.0 -175.0 -170.0 -165.0 -160.0
...
* lat (lat) float64 -89.0 -86.0 -82.0 -78.0 -74.0 -70.0
...
* lev (lev) float64 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0
...
* time (time) datetime64[ns] 2016-07-01
Data variables:
AREA (lat, lon) float64 ...
SpeciesRst_RCOOH (time, lev, lat, lon) float32 ...
SpeciesRst_O2 (time, lev, lat, lon) float32 ...
... etc...
SpeciesRst_O3 (time, lev, lat, lon) float32 ...
SpeciesRst_NO (time, lev, lat, lon) float32 ...
Attributes:
title: GEOSChem restart
history: Created by routine NC_CREATE (in ncdf_mod.F90)
format: NetCDF-4
conventions: COARDS
Units of SpeciesRst_O3: mol/mol
Sum of SpeciesRst_O3: 0.40381380915641785
Determining if a netCDF file is COARDS-compliant

The GEOS-Chem Support Team has created a script named isCoards that will let you easily
determine if a netCDF file is COARDS-compliant. In GEOS-Chem v11-01 and later
versions, isCoards is included in the NcdfUtil/perl subfolder of the GEOS-Chem source
code directory.
The isCoards will give you detailed output of which elements of a netCDF file are COARDS-
compliant and which are not. Here is an example:
> cd /mnt/gcgrid/data/ExtData/HEMCO/GFED4/v2015-10/2013
> isCoards GFED4_3hrfrac_gen.025x025.201301.nc
===========================================================================
Filename: GFED4_3hrfrac_gen.025x025.201301.nc
===========================================================================
The following items adhere to the COARDS standard:

---------------------------------------------------------------------------
-> time(time)
-> time is monotonically increasing
-> time:units = "hours since 1985-01-01 00:00:00"
-> lon(lon)
-> lon is monotonically increasing
-> lon:units = "degrees_east"
-> lat(lat)
-> lat is monotonically increasing
-> lat:units = "degrees_north"
-> GFED_FRAC3HR(time,lat,lon)
-> GFED_FRAC3HR:units = "1"
The following items DO NOT ADHERE to the COARDS standard:

---------------------------------------------------------------------------
-> time:calendar is missing
-> time:long_name (or time:standard_name) is missing
-> lon:long_name (or lon:standard_name) is missing
-> lat:long_name (or lat:standard_name) is missing
-> GFED_FRAC3HR:long_name (or GFED_FRAC3HR:standard_name) is missing
-> The "Conventions" global attribute is missing
-> The "History" global attribute is missing
-> The "Title" global attribute is missing
The following optional items are RECOMMENDED:

---------------------------------------------------------------------------
-> Consider adding time:axis = "T"
-> Consider adding lon:axis ="X"
-> Consider adding lat:axis = "Y"
-> Consider adding GFED_FRAC3HR:_FillValue
-> Consider adding GFED_FRAC3HR:missing_value
-> Consider adding GFED_FRAC3HR:add_offset
-> Consider adding GFED_FRAC3HR:scale_factor
-> Consider adding the "Format" global attribute
-> Consider adding the "References" global attribute
For more information how to fix non COARDS-compliant items, see:

http://wiki.geos-chem.org/Preparing_data_files_for_use_with_HEMCO
--Bob Yantosca (talk) 16:58, 6 January 2016 (UTC)
Edit variable names and atributes for COARDS compliance

If you have obtained a netCDF file from a data archive (or have created a netCDF file from an
data file in bpch format), then you will probably have to further edit certain attributes and variable
names in order to make your file COARDS-compliant. You can use the isCoards script
mentioned above to determine which elements of your netCDF file need to be edited.
Christoph Keller has provided these useful commands for editing netCDF files. He writes:
NetCDF files must always adhere to the COARDS conventions and some hand-editing may be
required before using them in HEMCO. Fortunately, there are a number of excellent software
toolkits available to quickly and efficiently manipulate netCDF files, such as nco, cdo, and ncl.
Below is a short list of commands that I use almost every day:
Operation Command
Display the header ncdump -cts file.nc

and the coordinate
values of a netCDF file,
with the time
coordinate displayed
in human-readable
format:
Compress a netCDF nccopy -d0 in.nc out.nc # No compression

File. This can nccopy -d1 in.nc out.nc # Minimum compression (sufficent
considerably reduce for most purposes)
the file size! nccopy -d5 in.nc out.nc # Medium compression
nccopy -d9 in.nc out.nc # Maximum compression
NOTE: Also see our
section
on compressing and
chunking netCDF
files!
Change variable name ncrename -v IJ_AVG_S__NO,NO file.nc

from IJ_AVG_S__N
Oto NO:
Change the time from cdo settime,2000-01-01 in.nc out.nc
1 Jan 1985 to 1 Jan
2000:
Set all missing values cdo setmisstoc,0 in.nc out.nc

to zero:
Add/change ncatted -a long_name,lev,o,c,"GEOS-Chem levels" file.nc

the long_nameattri
bute of the vertical
coordinate (lev) to
"GEOS-Chem levels".
This will ensure that
HEMCO recognizes the
vertical levels of the
input file as GEOS-
Chem model levels.
Add/change ncatted -a axis,lev,o,c,"Z" file.nc

the axis and posit ncatted -a positive,lev,o,c,"up" file.nc
iveattributes to the
the vertical coordinate
(lev)
Add/change ncatted -a units,lat,o,c,"degrees_north" file.nc

the units attribute
of the latitude
coordinate (lat)
to degrees_north
:
Add/change ncatted -a references,global,o,c,"www.geos-chem.org;

the referencesglo wiki.geos-chem.org" file.nc
bal attribute:
Add a time dimension ncap2 -h -s

to a file with missing 'defdim(“time”,1);time[time]=0.0;time@long_name=“time”;tim
time dimension: e@calendar=“standard”;time@units=“days since 2007-01-01
00:00:00”' -O in.nc out.nc
Convert the units of ncap2 -v -s "CHLA=CHLA/1000000.0f" in.nc out.nc

the CHLA variable ncatted -a units,CHLA,o,c,"kg/m3" out.nc
from mg/m3 to kg/m mv out.nc in.nc
3 (i.e. divide by 1e6):
Here are some specific commands that we used on the uvalbedo.geos.2x25.nc file from our
example in a previous section. If you need to apply these commands to more than one file, you
can place them into a script.
# Add history global attribute
ncatted -a history,global,o,c,"Tue Mar 3 12:18:38 EST 2015"
uvalbedo.geos.2x25.nc
# Add contact info

ncatted -a contact,global,o,c,"GEOS-Chem Support Team (geos-chem-
support@as.harvard.edu)" uvalbedo.geos.2x25.nc
# Add references
ncatted -a references,global,o,c,"www.geos-chem.org; wiki.geos-chem.org"
uvalbedo.geos.2x25.nc
# Update title
ncatted -a title,global,o,c,"UV albedo data from Hermann & Celarier
(1997)" uvalbedo.geos.2x25.nc
Regridding netCDF files

The following tools can be used to regrid netCDF data files (such as GEOS-Chem restart
files and GEOS-Chem diagnostic files):
Name Description
cdo The Climate Data Operators include tools for regridding netCDF files. For example, the following command
will apply distance-weighted regridding:
cdo remapdis,gridfile infile.nc outfile.nc
For gridfile, you can use the files in ftp://ftp.as.harvard.edu/gcgrid/data/ExtData/HEMCO/grids/. See

the Interpolation section in the CDO Guide for more information.
nco The netCDF Operators also include tools for regridding. See the Regridding section of the NCO User
Guide for more information.
xESMF Jiawei Zhuang has created xESMF, universal regridding tool for geospatial data, which is written in Python.
It can be used to regrid data not only on cartesian grids, but also on cubed-sphere and unstructured grids.
more information, see: https://xesmf.readthedocs.io

Issue with CDO remapdis regridding tool
Bram Maasakkers wrote:
I have noticed a problem regridding a 4x5 restart file to 2x2.5 using cdo 1.9.4. When I use:
cdo remapdis,geos.2x25.grid GEOSChem_restart.200901010000.nc
GEOSChem_restart.2009_2x25.nc
The last latitudinal band (-89.5) remains empty and gets filled with the standard missing value of
cdo, which is really large. This leads to immediate problems in the methane simulation as
enormous concentrations enter the domain from the South Pole. For now I’ve solved this
problem by just using bicubic interpolation
cdo remapbic,geos.2x25.grid GEOSChem_restart.200901010000.nc

GEOSChem_restart.2009_2x25_bicub.nc
Cropping netCDF files

If needed, regrid a coarse netCDF file (such as a GEOS-Chem restart file) can be cropped to a
subset of the globe with the nco or cdoutilities (as mentioned above).
For example, cdo has a SELBOX operator for selecting a box by specifying the lat/lon bounds:
cdo sellonlatbox,lon1,lon2,lat1,lat2 infile outfile
See page 44 of the CDO guide for more information.

--Melissa Sulprizio (talk) 19:04, 3 May 2017 (UTC)
Adding a new variable to a netCDF file

You have a couple of options for adding a new variable to a netCDF file (for example, when
having to add a new species to an existing GEOS-Chem restart file
(1) You can use cdo and nco to copy the the data from one variable to another variable. For
example:
module load nco

module load cdo
# Extract field SpeciesRst_PMN from the original restart file

cdo selvar,SpeciesRst_PMN initial_GEOSChem_rst.4x5_standard.nc NPMN.nc4
# Rename selected field to SpeciesRst_NPMN

ncrename -h -v SpeciesRst_PMN,Species_Rst_NPMN NMPN.nc4
# Append new species to existing restart file

ncks -h -A -M NMPN.nc4 initial_GEOSChem_rst.4x5_standard.nc
(2) Sal Farina wrote a simple Python script for adding a new species to a netCDF restart file:
import netCDF4 as nc
import sys
import os
for nam in sys.argv[1:]:

f = nc.Dataset(nam,mode='a')
try:
o = f['SpeciesRst_OCPI']
except:
print "SpeciesRst_OCPI not defined"
f.createVariable('SpeciesRst_SOAP',o.datatype,dimensions=o.dimensions,fill_
value=o._FillValue)
soap = f['SpeciesRst_SOAP']
soap[:] = 0.0
soap.long_name= 'SOAP species'
soap.units = o.units
soap.add_offset = 0.0
soap.scale_factor = 1.0
soap.missing_value = 1.0e30
f.close()
--Melissa Sulprizio (talk) 23:33, 7 November 2017 (UTC)
Chunking and deflating a netCDF file to improve I/O

We recommend that you chunk the data in your netCDF file. Chunking specifies the order in
along which the data will be read from disk. The Unidata web site has a good overview of why
chunking a netCDF file matters.
For GEOS-Chem with the high-performance option (aka GCHP), the best file I/O performance
occurs when the file is split into one chunk per level (assuming your data has a lev dimension).
This allows each individual vertical level of data to be read in parallel,
You can use the nccopy command of the netCDF Operators (NCO) library to do the chunking.
For example, say you have a netCDF file called myfile.nc with these dimensions:
dimensions:
lev = 72 ;
lat = 181 ;
lon = 360 ;
Then you can issue this command to apply the optimal chunking along levels:
nccopy -c lon/360,lat/181,lev/1,time/1 -d1 myfile.nc tmp.nc
mv tmp.nc myfile.nc
This will create a new file called tmp.nc that has the proper chunking. We then
replace myfile.nc with this temporary file.
You can specify the chunk sizes that will be applied to the variables in the netCDF file with the -
c argument to nccopy. To obtain the optimal chunking, the lon chunksize must be identical to the
number of values along the longitude dimension (e.g. lon/360 and the lat chunksize must be
equal to the number of points in the latitude dimension (e.g. lat/181).
We also recommend that you deflate (i.e. compress) the netCDF data variables at the same time
you apply the chunking. Deflating can substantially reduce the file size, especially for emissions
data that are only defined over the land but not over the oceans. You can deflate the data in a
netCDF file by specifying the -d argumetnt to nccopy. There are 10 possible deflation levels,
ranging from 0 (no deflation) to 9 (max deflation). For most purposes, a deflation level of 1 -d1 is
sufficient.
The GEOS-Chem Support Team has created a script named nc_chunk.pl that will
automatically chunk and compress data for you. You may obtain this script from our NcdfUtilities
repository. We also recommend that you copy nc_chunk.pl into a folder that is in your search
path (such as ~/bin) so that it will be available to you in whatever directory you are working in.
git clone https://github.com/geoschem/ncdfutil NcdfUtil

cp NcdfUtil/perl/nc_chunk.pl ~/bin
To use the script, type:
nc_chunk.pl myfile.nc # Chunk netCDF file

nc_chunk.pl myfile.nc 1 # Chunk and compress file using deflate level 1
You can use the ncdump -cts myfile.nc command to view the chunk size and deflation level
in the file. After applying the chunking and compression to myfile.nc, you would see output
such as this:
dimensions:
lev = 72 ;
lat = 181 ;
lon = 360 ;
variables:
float PRPE(time, lev, lat, lon) ;
PRPE:long_name = "Propene" ;
PRPE:units = "kgC/m2/s" ;
PRPE:add_offset = 0.f ;
PRPE:scale_factor = 1.f ;
PRPE:_FillValue = 1.e+15f ;
PRPE:missing_value = 1.e+15f ;
PRPE:gamap_category = "ANTHSRCE" ;
PRPE:_Storage = "chunked" ;
PRPE:_ChunkSizes = 1, 1, 181, 360 ;
PRPE:_DeflateLevel = 1 ;
PRPE:_Endianness = "little" ;
float CO(time, lev, lat, lon) ;
CO:long_name = "CO" ;
CO:units = "kg/m2/s" ;
CO:add_offset = 0.f ;
CO:scale_factor = 1.f ;
CO:_FillValue = 1.e+15f ;
CO:missing_value = 1.e+15f ;
CO:gamap_category = "ANTHSRCE" ;
CO:_Storage = "chunked" ;
CO:_ChunkSizes = 1, 1, 181, 360 ;
CO:_DeflateLevel = 1 ;
CO:_Endianness = "little" ;
The attributes listed in BLUE, and which begin with an _ character are "hidden" netCDF
attributes. They represent file properties instead of user-defined properties (like the long name,
units, etc.). The "hidden" attributes can be shown by adding the -s argument to ncdump.

Please also see the following references for more information:
 Preparing data files for use with HEMCO

 Vertical coordinates in netCDF files produced by GEOS-Chem
 List of the GEOS-Chem diagnostics archived to netCDF format
GEOS-Chem v11-02-final will also carry the designation GEOS-Chem 12.0.0.

We are migrating to a purely numeric versioning system in order to adhere more
closely to software development best practices. For a complete description of the
new versioning system, please see our GEOS-Chem version numbering system wiki
page.
4. GEOS-Chem Shared Data Directories
4.1 Overview
The GEOS-Chem shared data directories contain the various meteorological fields, emission
inventories, scale factors, and other data that GEOS-Chem reads in during the course of a
simulation.
 If you are using the Amazon EC2 cloud: The GEOS-Chem shared data directories
are automatically synced to the Amazon S3 storage system. You can easily access
this data from the home directory of your Amazon EC2 cloud instance. For more
information, please see Jiawei Zhuang's comprehensive cloud computing
tutorial: cloud-gc.readthedocs.io.
 If you are using your institution's computer system: You (or your IT staff) will
have to download the meteorological fields and emissions data that are used to drive
GEOS-Chem. Please proceed to Section 4.2.
4.2 Downloading data to your local computer system
Because of the large volume of data, you must download the shared data directories via FTP
or a similar utility such as wget, FireFTP, or SecureFX. Tracking the shared data directory
structure with Git is impossible due to its size. See the Minimum system requirements for
GEOS-Chem wiki page for information on typical disk space requirements for GEOS-Chem.
If your research group is setting up GEOS-Chem for the first time: You (or your IT staff)
will only have to download the full set of the GEOS-Chem shared data directories once. As
new emissions inventories and met field files become available, you can download the new
files or directories individually on an as-needed basis.
If your research group already consists of several GEOS-Chem users: The GEOS-
Chem shared directory structure should already be stored in a common disk space on your
computer cluster. In this case, you (or your IT staff) will only need to download the new
emissions inventories and related data files that were introduced in this version.
For detailed instructions on downloading the shared data directories, please see the
following wiki page subsections:
Directory Type Wiki Resource
Shared data directories  Setting up the ExtData directory

 Shared data directory archives
 Using wget to download the shared data directories
 Downloading the shared directories via anonymous
FTP
Emissions files used by  HEMCO data directories

HEMCO  Downloading the HEMCO data directories
 New data directories for v11-02-final aka 12.0.0
Sample restart files that  Restart files

you can use to spin up
your own GEOS-Chem
simulations
Important Note! Alll shared data directories are now subdirectories of a single root directory
called ExtData. If downloading the shared data directories for the first time, you (or IT staff)
must set up the ExtData directory prior to running GEOS-Chem. If you have previously
downloaded the GEOS-Chem shared data directories, you can simply add symbolic links
from ExtData to the existing data directories. Please see the Setting up
the ExtData directory wiki page for detailed instructions on setting up your shared data
directories so that they are compatible with GEOS-Chem.
Setting up the ExtData directory

On this page we describe the top-level root directory for all GEOS-Chem data files, which is
called ExtData.
Contents
[hide]
 1 Overview
o 1.1 Data directory structure prior to v10-01
o 1.2 ExtData: a new top-level directory tree
 2 Creating the ExtData directory structure
o 2.1 Data directories
 3 Setting directories in input.geos
Overview
Data directory structure prior to v10-01
Emissions and meteorological data for GEOS-Chem is arranged into a directory tree. In versions
of GEOS-Chem prior to v10-01, you would specify the directory where GEOS-Chem could find
the emissions and meteorological field files for the given resolution that you were using by setting
this line in your input.geos file:
Root data directory : /dir/to/data/GEOS_4x5
In this case the root-level directory, or top of the directory tree, is /dir/to/data/ and the
specific data directory for the 4° x 5° resolution data is GEOS_4x5/.
NOTE: The example root-level directory /dir/to/data will vary from system to system. For
example, on the Harvard data servers, the root-level directory is /as/data/geos. If you are not
sure what the root-level directory is on your disk server, then ask your sysadmin or IT staff.
This would indicate you were running GEOS-Chem at 4° x 5° resolution. GEOS-Chem would
then look for the 4° x 5° meteorological field data via these data paths (all of which are
subfolders of the root data directory):
/dir/to/data/GEOS_4x5/GEOS_FP/YYYY/MM # 4 x 5 GEOS-FP met data

/dir/to/data/GEOS_4x5/MERRA/YYYY/MM # 4 x 5 MERRA met data
/dir/to/data/GEOS_4x5/GEOS_5/YYYY/MM # 4 x 5 GEOS-5 met data
/dir/to/data/GEOS_4x5/GEOS_4_v4/YYYY/MM # 4 x 5 GEOS-4 met data
/dir/to/data/GCAP_4x5/AGRID/YYYY/MM # 4 x 5 GCAP met data
If you wanted to run GEOS-Chem at 2° x 2.5° resolution, you would use this setting for the root
data directory:
Root data directory : /dir/to/data/GEOS_2x2.5/
and GEOS-Chem would read the 2° x 2.5° meteorological data via these paths:
/dir/to/data/GEOS_2x2.5/GEOS_FP/YYYY/MM # 2 x 2.5 GEOS-FP met data

/dir/to/data/GEOS_2x2.5/MERRA/YYYY/MM # 2 x 2.5 MERRA met data
/dir/to/data/GEOS_2x2.5/GEOS_5/YYYY/MM # 2 x 2.5 GEOS-5 met data
/dir/to/data/GEOS_2x2.5/GEOS_4_v4/YYYY/MM # 2 x 2.5 GEOS-4 met data
etc. for other horizontal resolutions.

In addition to specifying the root data directory, you would also have to specify
the GEOS_NATIVE directory (formerly known as the GEOS_1x1 directory). This directory,
which was parallel to the root data directory, contains emissions and other data files at 1° x 1° or
finer horizontal resolution. You would specify the GEOS_NATIVE directory by setting this line
in input.geos
Dir w/ 1x1 emissions etc: /dir/to/data/GEOS_NATIVE/
GEOS-Chem would store this value in the Input_Opt%DATA_DIR_1x1 variable.

In addition to the root data directory and GEOS_NATIVE directory, you had to specify a couple
more data directories. These contained OH concentrations for the offline GEOS-Chem specialty
simulations, and the O3 prod/loss data used by the tagged O3 simulation.
Dir w/ archived OH files: /dir/to/data/GEOS_MEAN/OHmerge/v5-07-08/
Dir w/ O3 P/L rate files: /dir/to/data/GEOS_MEAN/O3_PROD_LOSS/2003.v6-01-

05/
So in summary, these data directories were arranged as:
/dir/to/data/ # Top of the GEOS-Chem

directory tree
/dir/to/data/GEOS_4x5/ # Directory for 4 x 5 data
/dir/to/data/GEOS_2x2.5/ # Directory for 2 x 2.5 data
... etc for other horizontal resolutions ...
/dir/to/data/GEOS_NATIVE/ #
/dir/to/data/GEOS_MEAN/ # OH & O3 concentrations
--Bob Y. 15:49, 6 April 2015 (EDT)

ExtData: a new top-level directory tree
Several code updates made in GEOS-Chem v10-01 and later versions required a change in the
data directory naming structure:
 The HEMCO emissions component makes it possible to read emissions inventories and
other relevant data sets at much higher resolution than 4° x 5° or 2° x 2.5°.
 In addition, HEMCO has the capability to regrid data from its native resolution to the
resolution of your GEOS-Chem simulation. We no longer need to store separate copies of
emissions data on multiple grids.
 Under these circumstances, referring to a top-level directory
named GEOS_4x5 or GEOS_2x2.5 can lead to confusion.
 When running GEOS-Chem in the ESMF/MAPL environment, accepted practice is to read
data from a directory tree where all of the data folders are subdirectories of a folder
named ExtData.
For all of these reasons, we have decided to restructure the GEOS-Chem data directory tree.
Starting with GEOS-Chem v10-01, all of the GEOS-Chem data directories will be subdirectories
of the ExtData directory. As explained in the next section, you can make symbolic links from
ExtData to the existing GEOS-Chem data directories.
Note: Using wget to download directories within ExtData will not work for symbolically
linked directories such as those in the ExtData/CHEM_INPUTS/ folder. When downloading
data for the first time, you will need to use wget with non-symbolically linked data
directories only. The locations of these directories for ExtData/CHEM_INPUTS/ are listed
below.
Creating the ExtData directory structure

Follow these instructions to create the ExtData directory tree on your system. You will need to
have write permission in your root data directory. If you don't have this permission, then ask your
sysadmin or IT staff for assistance. Note that if you are downloading data for the first time
1. Change to the root-level data directory. For our example, we will call this /dir/to/data.
> cd /dir/to/data
2. Get a listing of all the subdirectories in /dir/to/data:
> ls -1
GEOS_0.25x0.3125_CH/
GEOS_0.25x0.3125_NA/
GEOS_0.25x0.3125_NA.d@
GEOS_0.5x0.666_CH/
GEOS_0.5x0.666_CH.d@
GEOS_0.5x0.666_NA/
GEOS_0.5x0.666_NA.d@
GEOS_2x2.5/
GEOS_2x2.5.d/
GEOS_4x5/
GEOS_4x5.d/
GEOS_MEAN/
GEOS_NATIVE/
Your actual listing will differ, depending on the data you have stored on your disk server. NOTE:
In the above example, / denotes directories, and @ denotes symbolic links.
NOTE: If none of these data directories have been previously downloaded to your disk
server, then you will have to download them from one of the GEOS-Chem data archives.
See our Downloading GEOS-Chem source code and data wiki page for more instructions.
3. Cut-and-paste the directory output from Step 2 to a text editor. You'll need to use this again in
a couple of steps.
4. Create the /dir/to/data/ExtData subdirectory and switch to it.
> mkdir ExtData

> cd ExtData
> pwd
/dir/to/data/ExtData
5. Create a symbolic link from ExtData to each directory in the listing that you saved from Step
2.
> ln -s ../GEOS_0.25x0.3125_CH
> ln -s ../GEOS_0.25x0.3125_NA
> ln -s ../GEOS_0.25x0.3125_NA.d
> ln -s ../GEOS_0.5x0.666_CH
> ln -s ../GEOS_0.5x0.666_CH.d
> ln -s ../GEOS_0.5x0.666_NA
> ln -s ../GEOS_0.5x0.666_NA.d
> ln -s ../GEOS_2x2.5
> ln -s ../GEOS_2x2.5.d
> ln -s ../GEOS_4x5
> ln -s ../GEOS_4x5.d
> ln -s ../GEOS_MEAN
> ln -s ../GEOS_NATIVE .
6. Create the subdirectory ExtData/CHEM_INPUTS and switch to it. This directory will hold
various input files needed for various chemistry modules.
> mkdir CHEM_INPUTS

> cd CHEM_INPUTS
> pwd
/dir/to/data/ExtData/CHEM_INPUTS
7. If you already have the GEOS_NATIVE data directory on your system, create symbolic links
from ExtData/CHEM_INPUTS to the following directories in ../GEOS_NATIVE:
ln -s ../GEOS_NATIVE/FastJ_201204
ln -s ../GEOS_NATIVE/Linoz_200910
ln -s ../GEOS_NATIVE/MODIS_LAI_201204
ln -s ../GEOS_NATIVE/Olson_Land_Map_201203
ln -s ../GEOS_NATIVE/TOMAS_201402
ln -s ../GEOS_NATIVE/UCX_201403
8. If you are downloading data for the first time and do not have the GEOS_NATIVE directory on
your system, use wget to retrieve the following directories that are now symbolically linked
within ExtData/CHEM_INPUTS. On your system, these ExtData/CHEM_INPUTS/ directories will
not be symbolic links.
> wget -r -nH --cut-dirs=3

"ftp://ftp.as.harvard.edu/gcgrid/data/GEOS_NATIVE/FastJ_201204"
"ftp://ftp.as.harvard.edu/gcgrid/data/GEOS_1x1/Linoz_200910"
"ftp://ftp.as.harvard.edu/gcgrid/data/GEOS_NATIVE/MODIS_LAI_201204"
"ftp://ftp.as.harvard.edu/gcgrid/data/GEOS_NATIVE/Olson_Land_Map_201203"
"ftp://ftp.as.harvard.edu/gcgrid/data/GEOS_NATIVE/TOMAS_201402"
"ftp://ftp.as.harvard.edu/gcgrid/data/GEOS_NATIVE/UCX_201403"
8a. If you plan to use the RRTMG radiative transfer model option in GEOS-Chem, then download
the following data directories, which are new to ExtData/CHEM_INPUTS:

"ftp://ftp.as.harvard.edu/gcgrid/data/ExtData/CHEM_INPUTS/RRTMG_201411/"
"ftp://ftp.as.harvard.edu/gcgrid/data/ExtData/CHEM_INPUTS/modis_surf_201210
/"
8b. If you use GEOS-4 or GCAP met fields, then also copy this data directory
to ExtData/CHEM_INPUTS:

"ftp://ftp.as.harvard.edu/gcgrid/data/ExtData/CHEM_INPUTS/ann_mean_trop_200
202/"
This data directory contains netCDF versions of the annual mean tropopause data files
used for the GEOS-4 and GCAP simulations. If you do not use these met fields, then you
can ignore this step.
9. Switch back to the ExtData directory:
> cd ../ExtData
> pwd
/dir/to/data/ExtData
10. Download the HEMCO data directories into ExtData. You can do this with our
'hemco_data_download package, which can be obtained via Git.
10a: Obtain the hemco_data_download package by following these directions.

10b. Add the
path /dir/to/data/ExtData/HEMCO to the hemcoDataDownload.rc configuration file,
as shown below. See the text in RED.
#################################################################
##############
#
#
# Specify the remote and local HEMCO data paths, plus other
options. #
#
#
#################################################################
##############
Remote HEMCO data path |

ftp://ftp.as.harvard.edu/gcgrid/data/ExtData/HEMCO
Your HEMCO data path | /dir/to/data/ExtData/HEMCO
Verbose output | yes
Dryrun only? | no
10c. Look at this list of emission inventories and data sets that you can use with HEMCO.
Decide which of these you would like to download. Modify
the hemcoDataDownload.rc configuration file according to these instructions.
10d. Once you have set up your configuration file, follow these instructions to download
the HEMCO data directories to /dir/to/data/ExtData.
--Bob Y. 17:29, 6 April 2015 (EDT)
Data directories
Here is a list of the data directories in the ExtData structure. NOTE: Your
listing may differ, depending on which met field data sets you have stored
on your disk server.
Directory Description
CHEM_INPUTS Non-emissions data for GEOS-
Chem chemistry modules, which
cannot be read via HEMCO:
 FASTJ_201204
 Symbolic link to directory
with inputs for FAST-JX
photolysis
 Linoz_200910
with inputs for the Linoz
stratospheric ozone
chemistry module
 MODIS_LAI_201204
with MODIS leaf area index
data (needed for drydep and
biogenic emissions)
 Olson_Land_Map_201203
with Olson land map data
files (needed for drydep)
 TOMAS_201402
with inputs for TOMAS
aerosol microphysics
 UCX_201403
 Inputs for the UCX
chemistry mechanism
 ann_mean_trop_200202
 Directory containing annual
mean tropopause data files
(netCDF format)
 Needed for backwards
compatibility for GMAO
GEOS-
4 and GCAP simulations
The following data directories are

ONLY required if you are using the
RRTMG radiative transfer model in
GEOS-Chem:
 RRTMG_201411/
 Directory containing
climatological N2O and
CH4 profiles for input into
RRTMG.
 modis_surf_201210/
 Directory containing surface
albedo & emissivity for
input into RRTMG.
GEOS_0.25x0.3125_CH and Symbolic links directories that store
GEOS_0.25x0.3125_CH.d data on the GEOS-FP 0.25° x
0.3125° China nested grid:
 ../GEOS_0.25x0.3125_CH
 ../GEOS_0.25x0.3125_CH.d
GEOS_0.25x0.3125_EU and Symbolic links to directories that

GEOS_0.25x0.3125 EU.d store data on the 0.25° x 0.3125°
Europe nested grid:
 ../GEOS_0.25_x_0.3125_EU
 ../GEOS_0.25_x_0.3125_EU.d
GEOS_0.25x0.3125_NA and Symbolic links to directories that

GEOS_0.25x0.3125 NA.d store data on the GEOS-FP 0.25° x
0.3125° North America nested grid:
 ../GEOS_0.25_x_0.3125_NA
 ../GEOS_0.25_x_0.3125_NA.d
GEOS_2x2.5 and GEOS_2x2.5.d Symbolic links to directories that

store data on the GEOS-Chem 2° x
2.5° grid:
 ../GEOS_2x2.5
 ../GEOS_2x2.5.d
GEOS_4x5 and Symbolic links to directories that

GEOS_4x5.d store data on the GEOS-Chem 4° x
5° degree grid.
 ../GEOS_4x5
 ../GEOS_4x5.d
GEOS_NATIVE Symbolic link to

the ../GEOS_NATIVE directory
GEOS_MEAN Symbolic link to
the ../GEOS_MEAN directory
HEMCO Emissions inventories and other
data sets for use with HEMCO
Obsolete data directories ignored by GEOS-Chem v11-02
GCAP_4x5 Symbolic link to
the ../GCAP_4x5 data directory
GEOS_0.5x0.666_CH and Symbolic links to directories that
GEOS_0.5x0.666_CH.d store data on the GEOS-5 0.5° x
0.666° China nested grid:
 ../GEOS_0.5_x_0.666_CH
 ../GEOS_0.5_x_0.666_CH.d
GEOS_0.5x0.666_EU and Symbolic links to directories that

GEOS_0.5x0.666_EU.d store data on the GEOS-5 0.5° x
0.666° Europe nested grid:
 ../GEOS_0.5_x_0.666_EU
 ../GEOS_0.5_x_0.666_EU.d
GEOS_0.5x0.666_NA and Symbolic links to directories that

GEOS_0.5x0.666_NA.d store data on the GEOS-5 0.5° x
0.666° North America nested grid:
 ../GEOS_0.5_x_0.666_NA
 ../GEOS_0.5_x_0.666_NA.d
GEOS_0.25x0.3125_SE and Symbolic links to directories that

GEOS_0.25x0.3125_SE.d store data on the GEOS-FP 0.25° x
0.3125° SE Asia nested grid:
 ../GEOS_0.25_x_0.3125_SE
 ../GEOS_0.25_x_0.3125_SE.d
etc.
NOTE: Directories ending in .d (such as GEOS_4x5.d) contain only met
field data. These are reachable by symbolic links from the corrresponding
directories not ending in .d. For example, GEOS_4x5/GEOS_FP/ links
to GEOS_4x5.d/GEOS_FP. The historical reason why this was done was to
separate met field data (which can be several GB or TB in size) from other
non-met field data files (e.g. emissions), in order to facilitate disk
management. Please see this wiki post for more information.
--Bob Y. 11:25, 10 April 2015 (EDT)
Setting directories in input.geos

Please add the following settings in the SIMULATION MENU section of
your input.geos file:
Root data directory : /dir/to/data/ExtData/

=> GEOS-FP subdir : GEOS_FP/YYYY/MM/
=> MERRA-2 subdir : MERRA2/YYYY/MM/
The Root data directory should be set to /dir/to/data/ExtData. Our

example text /dir/to/data refers to the root-level data directory on your
system.
GEOS-Chem will prefix the proper resolution-specific directory to the GEOS-
FP and MERRA-2 subdirectories. For example, if you compile GEOS-Chem
with
make GRID=4x5 ...etc...
then you should see the following output in the log file:
===========================================================
====================
G E O S - C H E M U S E R I N P U T
READ_INPUT_FILE: Reading input.geos
SIMULATION MENU
---------------
Start time of run : 20160701 000000
End time of run : 20160801 000000
Run directory : ./
Data Directory : /dir/to/data/ExtData/
CHEM_INPUTS directory :
/dir/to/data/ExtData/CHEM_INPUTS/
Resolution-specific dir : GEOS_4x5/
GEOS-FP sub-directory : GEOS_4x5/GEOS_FP/YYYY/MM/
MERRA-2 sub-directory : GEOS_4x5/MERRA2/YYYY/MM/
... etc ...
GEOS-Chem will also automatically create a variable

(Input_Opt%CHEM_INPUTS) that points to
the ExtData/CHEM_INPUTS directory. You can use this instead
of Input_Opt%DATA_DIR_1x1 where necessary.
--Bob Yantosca (talk) 19:10, 16 May 2018 (UTC
Downloading GEOS-Chem source code and
data
This page describes where you can obtain the GEOS-Chem source code and required data files.
Contents
[hide]
 1 What you need to download before you can run GEOS-Chem

 2 Shared data directory archives
o 2.1 Harvard data directory archive
 2.1.1 Directories for met fields and emissions data
 2.1.2 Directories for 1-month and 1-year benchmarks
o 2.2 Dalhousie data directory archive
 2.2.1 Dalhousie directory structure
o 2.3 Compute Canada data directory archive
 2.3.1 Compute Canada directory structure
 3 Using wget to download the shared data directories
o 3.1 Syntax
o 3.2 Examples
o 3.3 Obtain only updated files
 4 Downloading the shared data directories via anonymous FTP
 5 Downloading the HEMCO data directories
o 6.1 For GCAP users
o 6.2 Question about directory structure
 7 Previous issues that are now resolved
o 7.1 Inconsistency in GEOS-FP files at Harvard and Dalhousie for July 2013
o 7.2 Wrong No. of vertical layers in A3mstE files for 0.5x0.625 nested regions
What you need to download before you can run GEOS-Chem

Many of the required software packages mentioned on Our GEOS-Chem basics wiki page (e.g.
the operating system, the Git version control system, etc.) will already come pre-installed on your
system. The most important items that you will need to download to your system are the
following:
Item Description
A netCDF Most of the data files read by GEOS-Chem v11-01 are now in
library COARDS-compliant netCDF format. As part of our High-
installation. Performance Computing (HPC) GEOS-Chem project, we are in the
process of converting the remaining binary data files to netCDF
format. This will facilitate running GEOS-Chem in (HPC)
environments, such as our efforts to interface GEOS-Chem with the
NASA GEOS-5 GCM.
If you are using a shared computer system, then your IT staff may
have already pre-built a version of the netCDF library that you can
load into your Unix environment. If not, then you can build a
netCDF library with our installer package.
 GEOS-Chem User's Guide: Chapter 3: The netCDF Library

 The COARDS netCDF standard
 Installing libraries for GEOS-Chem
GEOS–Chem The GEOS-Chem shared data directories contain many large files,
shared data such as:
directories.
 Meteorological data (a.k.a. the "met fields) used to drive GEOS–
Chem
 Emissions inventories for the HEMCO emissions component
 Scale factors to used to scale emissions from a base year to a
given year
 Oxidant (OH, O3) concentrations for both full-
chemistry and specialty simulations
 Sample restart files for the various types of GEOS-Chem
simulations.
These data directories are too large to fit into your own personal
disk quota. We recommend that you (or your IT staff) download the
shared data directories to a common disk space where all GEOS-
Chem users in your group can access them.
You will only need to download the shared data directories from
disk once from scratch. As new met fields or emissions data are
added, you can download the new folders and files individually.
 GEOS-Chem User's Guide: Chapter 4: The shared data

directories
 Shared data directory archives
 HEMCO data directories
 Using wget to download the shared data directories
 Directories for met fields and emissions data
GEOS–Chem This is the directory where the Fortran-90 source code files
source code (i.e. *.F, *.F90 files) and Makefiles reside. Your Fortran compiler
directory. will create an executable (geos) from these source code files.
 GEOS-Chem User's Guide: Chapter 5: GEOS-Chem Source Code

Directory
GEOS–Chem You can create run directories for the various GEOS-Chem
run directories. simulations with our GEOS-Chem Unit Tester. You can store the run
directories in your personal disk space.
 GEOS-Chem User's Guide: Chapter 6: GEOS-Chem run

directories
 Creating GEOS-Chem run directories
 GEOS-Chem Unit Tester
Shared data directory archives

There are currently three data archives from which you may download the GEOS–Chem shared
data directories:
1. Harvard data directory archive (ftp.as.harvard.edu) - Recommended for emissions

data
2. Dalhousie data directory archive (rain.ucis.dal.ca) - Recommended for met fields
3. Compute Canada data directory archive (http://geoschemdata.computecanada.ca)
- For 0.5° x 0.625° global MERRA-2 met fields and 0.25° x 0.3125° global GEOS-FP
met fields
The GEOS-Chem met fields are currently processed at Dalhousie University. The Dalhousie
archive, as a result, includes met fields for more recent dates than the Harvard archive. In
addition, Dalhousie archive data files for the various nested grids that may not available be on
the Harvard archive.
Conversely, emissions data for HEMCO and non-emissions data for GEOS-Chem chemistry
modules are frequently processed at Harvard University. Therefore, we recommend downloading
those data from the Harvard archive.
Prior to downloading GEOS-FP data, please be aware of caveats regarding use of GEOS-FP.
See the GEOS-FP wiki page for more information.
Harvard data directory archive
You can access the primary GEOS-Chem data download site via anonymous FTP at:
ftp ftp.as.harvard.edu
We recommend that you use the wget utility to download these directories instead of anonymous
FTP. Wget allows you to download multiple directories at once, with a command such as this
one:
wget -r -nH --cut-dirs=4 "ftp://ftp.as.harvard.edu/DIRECTORY_NAME"
See the tables below for the DIRECTORY_NAME options.

Directories for met fields and emissions data
If you are downloading the GEOS-FP or MERRA-2 met data, then please note the
following:
1. You will need to download the "CN" (constant) data files for each horizontal grid
that you are using.
 For GEOS-FP these are timestamped for 2011/01/01 and are found in these
data directories of ftp.as.harvard.edu:
 gcgrid/data/GEOS_4x5/GEOS_FP/2011/01/GEOSFP.20110101.4x5.nc
 gcgrid/data/GEOS_2x2.5/GEOS_FP/2011/01/GEOSFP.20110101.2x25.nc
 gcgrid/data/GEOS_0.25x0.3125_CH/GEOS_FP/2011/01/GEOSFP.2011010
1.0.25x0.3125.CH.nc
 gcgrid/data/GEOS_0.25x0.3125_NA/GEOS_FP/2011/01/GEOSFP.2011010
1.0.25x0.3125.NA.nc
 For MERRA-2 these are timestamped for 2015/01/01 and are found in these
data directories of ftp.as.harvard.edu:
 gcgrid/data/GEOS_4x5/MERRA2/2015/01/20150101.cn.4x5
 gcgrid/data/GEOS_2x2.5/MERRA2/2015/01/20150101.cn.2x25
 gcgrid/data/GEOS_0.5x0.625_AS/MERRA2/2015/01/MERRA2.20150101.0
.5x0.625.AS.nc
 gcgrid/data/GEOS_0.5x0.625_NA/MERRA2/2015/01/MERRA2.20150101.0
.5x0.625.NA.nc
Also note: NASA/GMAO recommends to discontinue use of the GEOS-5 and MERRA met
field data products, as these have now been superseded by GEOS-FP and MERRA-2.
The path gcgrid/data/ExtData/ is the root path under which the GEOS–Chem shared data
directories reside. This is where you will find the GEOS-Chem met fields and emissions data.
Starting with GEOS-Chem v10-01, the data directory naming structure has changed since we no
longer need to store emissions data on multiple grids. All of the GEOS-Chem data directories are
now subdirectories of the ExtData directory. For more information, please see our Setting up the
ExtData directory wiki page.
gcgrid/data/ExtData/ Root Data Directory
gcgrid/data/ExtData/CHEM_INPUTS/ Contains non-

emissions data for
GEOS-Chem
chemistry modules
gcgrid/data/ExtData/HEMCO/ Contains emissions

data for
the HEMCO
emissions
component
0.25° x 0.3125° Data Directories Description
gcgrid/data/ExtData/GEOS_0.25x0.3125_CH/GEOS_FP/YYYY/MM/ GEOS-FP met fields

for 0.25° x 0.3125°
CH nested grid
simulations
gcgrid/data/ExtData/GEOS_0.25x0.3125_NA/GEOS_FP/YYYY/MM/ GEOS-FP met fields

for 0.25° x 0.3125°
NA nested grid
simulations
gcgrid/data/ExtData/GEOS_0.5x0.625_AS/MERRA2/YYYY/MM/ MERRA-2 met fields

for 0.5° x 0.625°
AS nested grid
simulations
gcgrid/data/ExtData/GEOS_0.5x0.625_NA/MERRA2/YYYY/MM/ MERRA-2 met fields

for 0.5° x 0.625°
NA nested grid
simulations
2° x 2.5° Data Directories Description
gcgrid/data/ExtData/GEOS_2x2.5/GEOS_FP/YYYY/MM GEOS-FP met data

for 2° x 2.5° global
simulations
gcgrid/data/ExtData/GEOS_2x2.5/MERRA2/YYYY/MM MERRA-2 met fields

for 2° x 2.5° global
simulations
4° x 5° Data Directories Description
gcgrid/data/ExtData/GEOS_4x5/GEOS_FP/YYYY/MM/ GEOS-FP met fields

for 4° x 5° global
simulations
gcgrid/data/ExtData/GEOS_4x5/MERRA2/YYYY/MM/ MERRA-2 met fields

for 4° x 5° global
simulations
--Melissa Sulprizio (talk) 18:26, 29 August 2018 (UTC)

Directories for 1-month and 1-year benchmarks
You can find output files and evaluation plots for 1-month and 1-year benchmark simulations in
the following directories:
gcgrid/geos- Contains the following types of data from the 1-month

chem/1mo_benchmarks/
benchmark simulations that are used to evaluate GEOS-
Chem:
 Restart files
 Model output (bpch and netCDF formats)
 Log files
 Input files
 Evaluation plots
gcgrid/geos- Contains the following types of data from the 1-year
chem/1yr_benchmarks/
benchmarks used to evaluate GEOS-Chem:
 Restart files
 Model output (bpch and netCDF formats)
 Log files
 Input files
 Evaluation plots
Dalhousie data directory archive
The GEOS-Chem data and meteorological fields used by Dalhousie University are also available
via anonymous FTP from:
ftp rain.ucis.dal.ca
We recommend that you use the wget utility to download these directories instead of anonymous
FTP. Wget allows you to download multiple directories at once. The Wget command will take the
form:
wget -r -nH --cut-dirs=4 "ftp://rain.ucis.dal.ca/DIRECTORY_NAME"
See the table below for the DIRECTORY_NAME options.

Dalhousie directory structure
If you are downloading the GEOS-FP or MERRA-2 met data, then please note the
following:
1. You will need to download the "CN" (constant) data files for each horizontal grid
that you are using.
data directories of rain.ucis.dal.ca:
 ctm/GEOS_4x5.d/GEOS_FP/2011/01/GEOSFP.20110101.4x5.nc
 ctm/GEOS_2x2.5.d/GEOS_FP/2011/01/GEOSFP.20110101.2x25.nc
 ctm/GEOS_0.25x0.3125_CH.d/GEOS_FP/2011/01/GEOSFP.20110101.0.25
x0.3125.CH.nc
 ctm/GEOS_0.25x0.3125_EU.d/GEOS_FP/2011/01/GEOSFP.20110101.0.25
x0.3125.EU.nc
 ctm/GEOS_0.25x0.3125_NA.d/GEOS_FP/2011/01/GEOSFP.20110101.0.25
x0.3125.NA.nc
 ctm/GEOS_4x5.d/MERRA2/2015/01/20150101.cn.4x5
 ctm/GEOS_2x2.5.d/MERRA2/2015/01/20150101.cn.2x25
 ctm/GEOS_0.5x0.625_AS.d/MERRA2/2015/01/MERRA2.20150101.0.5x0.6
25.AS.nc
 ctm/GEOS_0.5x0.625_EU.d/MERRA2/2015/01/MERRA2.20150101.0.5x0.6
25.EU.nc
 ctm/GEOS_0.5x0.625_NA.d/MERRA2/2015/01/MERRA2.20150101.0.5x0.6
25.NA.nc
Global MERRA-2 data at 0.5° x 0.625° resolution and GEOS-FP data at 0.25° x 0.3125°
resolution have been moved to the Compute Canada data directory archive.
ctm/ExtData/ Root Data Directory
ctm/CHEM_INPUTS/ Contains non-emissions data for

GEOS-Chem chemistry modules
ctm/ExtData/HEMCO/ Contains emissions data for

the HEMCO emissions component
ctm/GEOS_0.25x0.3125_CH.d/GEOS_FP/YYYY/MM GEOS-FP met fields for 0.25° x

0.3125° CH nested grid simulations
ctm/GEOS_0.25x0.3125_EU.d/GEOS_FP/YYYY/MM GEOS-FP met fields for 0.25° x

0.3125° EU nested grid simulations
ctm/GEOS_0.25x0.3125_NA.d/GEOS_FP/YYYY/MM GEOS-FP met fields for 0.25° x
0.3125° NA nested grid simulations
ctm/GEOS_0.5x0.666_CH.d/GEOS_5/YYYY/MM GEOS-5 met field files for 0.5° x 666°

CH nested grid simulations
ctm/GEOS_0.5x0.666_EU.d/GEOS_5/YYYY/MM GEOS-5 met field files for 0.5° x 666°

EU nested grid simulations
ctm/GEOS_0.5x0.666_NA.d/GEOS_5/YYYY/MM GEOS-5 met field files for 0.5° x 666°

NA nested grid simulations
ctm/GEOS_5x0.625_AS.d/MERRA2/YYYY/MM MERRA-2 met fields for 0.5° x 0.625°

AS nested grid simulations
ctm/GEOS_5x0.625_EU.d/MERRA2/YYYY/MM MERRA-2 met fields for 0.5° x 0.625°

ctm/GEOS_5x0.625_NA.d/MERRA2/YYYY/MM MERRA-2 met fields for 0.5° x 0.625°

ctm/GEOS_2x2.5.d/GEOS_4_v4/YYYY/MM/ GEOS-4 met fields for 2° x 2.5° global

simulations
ctm/GEOS_2x2.5.d/GEOS_5/YYYY/MM GEOS-5 met fields for 2° x 2.5° global

simulations
ctm/GEOS_2x2.5.d/GEOS_FP/YYYY/MM GEOS-FP met fields for 2° x

2.5° global simulations
ctm/GEOS_2x2.5.d/MERRA/YYYY/MM MERRA met fields for 2° x 2.5° global
simulations
ctm/GEOS_2x2.5.d/MERRA2/YYYY/MM MERRA-2 met fields for 2° x

ctm/GEOS_4x5.d/GEOS_4_v4/YYYY/MM GEOS-4 met fields for 4° x 5° global

simulations
ctm/GEOS_4x5.d/GEOS_5/YYYY/MM GEOS-5 met fields for 4° x 5° global

simulations
ctm/GEOS_4x5.d/GEOS_FP/YYYY/MM GEOS-FP met fields for 4° x 5° global

simulations
ctm/GEOS_4x5.d/MERRA/YYYY/MM MERRA met fields for 4° x 5° global

simulations
ctm/GEOS_4x5.d/MERRA2/YYYY/MM MERRA-2 met fields for 4° x 5° global

simulations
A catalog of available data may be found HERE.

--Melissa Sulprizio (talk) 14:22, 24 March 2017 (UTC)
Compute Canada data directory archive
A copy of the Dalhousie archive of global and nested met fields, as well as 0.5° x 0.625°
global MERRA-2 and 0.25° x 0.3125° global GEOS-FP data data are available from:
http://geoschemdata.computecanada.ca
We recommend that you use the wget utility to download these directories. Wget allows you to
download multiple directories at once. The Wget command will take the form:
wget -r -nH --cut-dirs=2

"http://geoschemdata.computecanada.ca/DIRECTORY_NAME"
See the table below for the DIRECTORY_NAME options.

Compute Canada directory structure
If you are downloading the met data, then please note the following: You will need to
download the "CN" (constant) data files for each horizontal grid that you are using.
1.
 GEOS_4x5.d/GEOS_FP/2011/01/GEOSFP.20110101.4x5.nc
 GEOS_2x2.5.d/GEOS_FP/2011/01/GEOSFP.20110101.2x25.nc
 GEOS_0.25x0.3125_CH.d/GEOS_FP/2011/01/GEOSFP.20110101.0.25x0.3
125.CH.nc
 GEOS_0.25x0.3125_EU.d/GEOS_FP/2011/01/GEOSFP.20110101.0.25x0.3
125.EU.nc
 GEOS_0.25x0.3125_NA.d/GEOS_FP/2011/01/GEOSFP.20110101.0.25x0.3
125.NA.nc
 GEOS_0.25x0.3125/GEOS_FP/2011/01/GEOSFP.20110101.CN.025x03125.
nc
 GEOS_4x5.d/MERRA2/2015/01/20150101.cn.4x5
 GEOS_2x2.5.d/MERRA2/2015/01/20150101.cn.2x25
 GEOS_0.5x0.625_AS.d/MERRA2/2015/01/MERRA2.20150101.0.5x0.625.A
S.nc
 GEOS_0.5x0.625_EU.d/MERRA2/2015/01/MERRA2.20150101.0.5x0.625.E
U.nc
 GEOS_0.5x0.625_NA.d/MERRA2/2015/01/MERRA2.20150101.0.5x0.625.N
A.nc
 GEOS_0.5x0.625/MERRA2/2015/01/MERRA2.20150101.CN.05x0625.nc
GEOS_0.25x0.3125/GEOS_FP/YYYY/MM GEOS-FP met fields for 0.25°

GEOS_0.5x0.625/MERRA2/YYYY/MM MERRA-2 met fields for 0.5° 0.625° global

simulations

GEOS_0.25x0.3125_CH.d/GEOS_FP/YYYY/MM GEOS-FP met fields for 0.25° x 0.3125°
CH nested grid simulations
GEOS_0.25x0.3125_EU.d/GEOS_FP/YYYY/MM GEOS-FP met fields for 0.25° x 0.3125°

GEOS_0.25x0.3125_NA.d/GEOS_FP/YYYY/MM GEOS-FP met fields for 0.25° x 0.3125°

GEOS_5x0.625_AS.d/MERRA2/YYYY/MM MERRA-2 met fields for 0.5° x 0.625°

AS nested grid simulations
GEOS_5x0.625_EU.d/MERRA2/YYYY/MM MERRA-2 met fields for 0.5° x 0.625°

GEOS_5x0.625_NA.d/MERRA2/YYYY/MM MERRA-2 met fields for 0.5° x 0.625°

GEOS_2x2.5.d/GEOS_4_v4/YYYY/MM/ GEOS-4 met fields for 2° x 2.5° global

simulations
GEOS_2x2.5.d/GEOS_5/YYYY/MM GEOS-5 met fields for 2° x 2.5° global

simulations
GEOS_2x2.5.d/GEOS_FP/YYYY/MM GEOS-FP met fields for 2° x 2.5° global

simulations
GEOS_2x2.5.d/MERRA/YYYY/MM MERRA met fields for 2° x 2.5° global

simulations
GEOS_2x2.5.d/MERRA2/YYYY/MM MERRA-2 met fields for 2° x 2.5° global

simulations
GEOS_4x5.d/GEOS_4_v4/YYYY/MM GEOS-4 met fields for 4° x 5° global

simulations
GEOS_4x5.d/GEOS_5/YYYY/MM GEOS-5 met fields for 4° x 5° global

simulations
GEOS_4x5.d/GEOS_FP/YYYY/MM GEOS-FP met fields for 4° x 5° global

simulations
GEOS_4x5.d/MERRA/YYYY/MM MERRA met fields for 4° x 5° global

simulations
GEOS_4x5.d/MERRA2/YYYY/MM MERRA-2 met fields for 4° x 5° global

simulations
Using wget to download the shared data directories

A simple way to download the GEOS-Chem emissions and met field data is to use the
Unix wget utility. This allows you to download multiple files and directories at a time.
The wget utility is free and open-source (published by GNU), and comes standard with pretty
much all builds of *nix (Linux, Ubuntu, Fedora, Centos, etc.). You can check out the user
manual for more information.
NOTE: wget will not retrieve symbolically linked directories. To download directories that
are symbolically linked, use wget with the paths that the symbolically linked directories
point to. This may be necessary when setting up the ExtData directory if you are
downloading data for the first time. See the Setting up the ExtData directory wiki page for
more information.
Syntax
Most of the time, the syntax you will use to download multiple directories is as follows:
Downloading data from Harvard:
wget -r -nH "ftp://ftp.as.harvard.edu/DIRECTORY_NAME/"
Downloading data from Dalhousie:
wget -r -nH "ftp://rain.ucis.dal.ca/DIRECTORY_NAME/"
The options to wget are as follows:

-r Specifies recursive directory transfer (i.e. will download all
subdirectories)
-nH Will store all directories and subdirectories in DIRECTORY_NAME, not
ftp.as.harvard.edu/DIRECTORY_NAME
If you wish to trim the name of the downloaded directory (i.e., so it downloads
as DIRECTORY_NAME, not pub/geos-chem/data/DIRECTORY_NAME), then use the --cut-
dirs option:
wget -r -nH --cut-dirs=X "ftp://ftp.as.harvard.edu/DIRECTORY_NAME/"
where X is the number of directories to trim.

NOTE: The URL must be enclosed in quotes for file transfer to occur. If you omit the
quotes then wget will just return a directory listing in a file named index.html without
any files being downloaded.
Examples
1. Download all available GEOS-Chem 2° x 2.5° met field data files in
the GEOS_2x2.5.d directory structure:
wget -r -nH "ftp://ftp.as.harvard.edu/gcgrid/geos-chem/data/GEOS_2x2.5.d/"

&
Due to the huge volume of data involved, this is not recommended, as the file downloads may
swamp your system. It's better to do download the data smaller chunks. For example:
2. Download all GEOS-5 met data at 2° x 2.5° resolution:
wget -r -nH "ftp://ftp.as.harvard.edu/gcgrid/geos-

chem/data/GEOS_2x2.5.d/GEOS_5/" &
It may even be better to download one year at a time.:

3. Download all GEOS-5 met data at 2° x 2.5° resolution for 2008:
wget -r -nH "ftp://ftp.as.harvard.edu/gcgrid/geos-

chem/data/GEOS_2x2.5.d/GEOS_5/2008/" &
--Melissa Sulprizio 16:57, 8 April 2015 (EDT)

Obtain only updated files
Prasad Kasibhatla wrote:
Maybe this is common knowledge, but I just discovered that using the -N option in wget
ensures that only files with newer timestamps than what resides on my local machines
are downloaded - found this very useful to update my shared data directories.
--Melissa Payer 10:39, 1 June 2012 (EDT)
Downloading the shared data directories via anonymous FTP

You can also download the shared data directories via anonymous FTP:
ftp ftp.as.harvard.edu
cd gcgrid/geos-chem/data/ExtData/GCAP_4x5
cd gcgrid/geos-chem/data/ExtData/GEOS_0.25x0.3125_CH
cd gcgrid/geos-chem/data/ExtData/GEOS_0.25x0.3125_NA
cd gcgrid/geos-chem/data/ExtData/GEOS_0.5x0.666_CH
cd gcgrid/geos-chem/data/ExtData/GEOS_0.5x0.666_NA
cd gcgrid/geos-chem/data/ExtData/GEOS_2x2.5
cd gcgrid/geos-chem/data/ExtData/GEOS_4x5
cd gcgrid/geos-chem/data/ExtData/GEOS_MEAN
cd gcgrid/geos-chem/data/ExtData/GEOS_NATIVE
cd gcgrid/geos-chem/data/ExtData/HEMCO
cd gcgrid/geos-chem/data/ExtData/CHEM_INPUTS
Downloading the HEMCO data directories

The GEOS-Chem Support Team has created a package called hemco_data_download.
With this package, you can download the various emissions inventories and related data files
for HEMCO to your own disk server. For complete instructions, please see our HEMCO data
directories wiki page

For GCAP users
For those users who wish to run GEOS-Chem with the GISS/GCAP met fields, please
contact Loretta Mickley.
--Bob Y. 09:52, 8 March 2010 (EST)
Question about directory structure
Shanna Shaked wrote:
We are working again on trying to run GEOS-Chem. However, we are encountering

some errors that may be due to the directory structure. We find a discrepancy between
the directory structure described in the GEOS-Chem manual and that available on the ftp
site.
The GEOS-Chem manual describes a directory structure of:
data/GEOS_4x5/GEOS_5/YYYY/MM
However, on the ftp site, we find a directory structure with an extra '.d':
data/GEOS_4x5.d/GEOS_5/YYYY/MM
(the GEOS_5 folder is in GEOS_4x5.d rather than GEOS_4x5). There does exist
a GEOS_4x5 that contains many of the emissions data, but does not contain GEOS_5.
If we leave the structure as is, and enter ../data/GEOS_4x5/ as our root data directory
in input.geos, we get a file not found error when it looks for GEOS_5 within this directory
(obviously).
If we instead enter ../data/GEOS_4x5.d as our root data directory, we get a file not
found error when the program looks for emissions within this directory (lightning NOx
emissions, in this case).
QUESTION: To solve this problem, we have moved the GEOS_5 folder into
the GEOS_4x5 directory. [Is this] okay?
The only difference on our system between e.g. GEOS_4x5 and GEOS_4x5.d is that our
sysadmin (Jack Yatteau) set up the ".d" directories separately so that they only contain
met data (which is much larger than the emissions etc. data). That way he could separate
the disks that just had met data from the disk that have the emissions data to facilitate
our configuration here. There are symbolic links from GEOS_4x5 to GEOS_4x5.d etc. (i.e.
the directory GEOS_4x5/GEOS_5 is actually a symbolic link to the corresponding directory
in GEOS_4x5.d/GEOS_5/ and etc. for the other met field resolutions & directories).
You don't necessarily have to do this on your end, but this is what we did here. You can
just make the GEOS_4x5/GEOS_5 etc. real subdirectories and not symbolic links and
store the data there. The solution you picked above is OK.
Also to facilitate FTP file transfer, you could do the following:
 Write a script or an FTP macro

 Use a 3rd-party GUI program like FireFTP in Mozilla Firefox.
 Or even better yet, use the Unix wget utility (see below)
Each user is responsible for their own file transfers.
--Bob Y. 11:04, 5 February 2009 (EST)
Previous issues that are now

resolved
Inconsistency in GEOS-FP files at
Harvard and Dalhousie for July 2013
NOTE: This inconsistency was fixed in
March 2018 and was validated with
benchmark simulations for v11-
02e (approved 24 Mar 2018). The solution
was to recopy all GEOS-FP met field files
from the Dalhousie archive to the Harvard
archive.
As always, we recommend downloading all
met fields from the Dalhousie shared data
directory archive to avoid issues like this in
the future.
Prasad Kasibhatla wrote:
I wanted to alert you about something you might know already. I have been trying to run
Tomas Sherwen's halogen chem code here and was seeing some substantial differences
in my output files compared to his, and I finally traced them to differences in *cld* met
files between the Harvard (where I got my met files) and Dalhousie (where he got his met
files) archives.
I have only looked at the GEOS_FP 4x5 2013 July *cld* files - I don't know if this is a
more widespread issue affecting other met files/met products/years/resolutions. But
thought I should alert you.
Chi Li wrote:
I have retrieved the original GMAO GEOS-FP data for July, 2013, and generated the 4x5
A3cld data. I double checked the code and recompiled it, to guarantee that the new way
of calculating CLOUD is included in the new processing.
I read in “CLOUD”, “OPTDEPTH” variables and compared the values. The differences
were 0 everywhere and every time step when compared with the Dalhousie data for
every day. Meanwhile when compared with the Harvard data, the maximum differences
in OPTDEPTH could reach ~15 for July 5-31.
I did not compress these data to nc4 but they readily agree with the Dalhousie data. So
from my view I would say the Dalhousie archive should represent the more recent
updates, at least for this month.
I am not sure how to look more into the difference between Harvard and Dal data. It is
strange that the Harvard data agree exactly with Dal and newly processed data on every
level and every time step for July 1-4. Anyway, if you recall something else to check with,
I am willing to help.
Bob Yantosca wrote:
Odd – it seems like on our end, July 1-4 files were created after the commit that was
made to use CLOUD (on 2013-12-12) but July 5-31 were made before (on 2013-11-23 or
thereabouts). I am not sure what happened. Now I’m thinking that the Harvard files for
this month might not be correct.
One thing – since we use July 2013 as our benchmarking year, this will affect the GC
benchmarks, if we change the met fields.
--Melissa
Sulprizio (talk)
20:13, 15
August 2017
(UTC)
Wrong No.
of vertical
layers in
A3mstE
files for
0.5x0.625
nested
regions
NOTE: This
inconsistenc
y is fixed
since
201710, but
not for
historical
data archive
since we are
uncertain
whether it
actually
would affect
the
simulation.
We welcome
future
inquiry and
discussion
from users of
the
GEOS_FP
0.5x0.625
data.
Chi Li wrote:
I have another bug in the code to report. After examining the processing Met field
processing code, I found another bug that affect the 0.5 degree GEOS-FP nested data
(NA, EU, AS, SE, CH regions). That is, the code mistakenly output 72 layers of data in
the “A3mstE” files instead of 73. This is due to:
IF
(
doNestCh
05 )
THEN
fName =
TRIM(
tempDirT
mplNestC
h05 ) //
TRIM(
dataTmpl
NestCh05
)
gName =
'nested
CH 05'
CALL
ExpandDa
te (
fName,
yyyymmdd
,
000000
)
CALL
StrRepl
( fName,
'%%%%%%'
,
'A3mstE'
)
CALL
NcOutFil
eDef(
I_NestCh
05,
J_NestCh
05,
L05x0625
,
TIMES_A3
, &
xMid_05x
0625(I0_
ch05:I1_
ch05),
&
yMid_05x
0625(J0_
ch05:J1_
ch05),
&
zEdge_05
x0625,
a3Mins,
&
gName,
fName,
fOut05Ne
stCh
)
ENDIF
The “L05x0625” (72 layers) should be ‘L05x0625+1’ (73 layers). Same problems exist for
the other 4 nested regions. The nested regions at native resolution (0.25 degree) are not
affected.
Bob
Yant
osca
wrote
:
As far as I know, nobody is using the GEOS-FP half-degree nested grids (or if there are,
we haven’t heard from them).
Also, for the A3mstE data, all of the data fields (e.g. CMFMC) are zero at the top of the
atmosphere anyway. Those are all cloud fields, which go to zero at about 20km above
the surface.
HEMCO data directories
On this page we describe the directory tree from which the HEMCO emissions component can
read emissions inventories and other atmospheric data sets.
Contents
[hide]
 1 Overview
 2 Default GEOS-Chem emissions configurations
 3 HEMCO data directory structure
o 3.1 Aerosol emissions
o 3.2 Anthropogenic and biofuel emissions
o 3.3 Anthropogenic aircraft and ship emissions
o 3.4 Biomass burning emissions
o 3.5 Emissions implemented as HEMCO extensions
o 3.6 Future and historical emissions
o 3.7 GEOS-Chem specialty simulation data
o 3.8 Halogen emissions
o 3.9 Natural emissions data
o 3.10 Non-emissions data
o 3.11 Oceanic emissions
o 3.12 Other inputs for HEMCO
 4 Downloading the HEMCO data directories
o 4.1 Obtaining the hemco_data_download package
o 4.2 Setting up the configuration file
o 4.3 Downloading the data
o 4.4 New features for the GEOS-Chem v10-01 public release
 5 Submitting new data for use with HEMCO
Overview
The HEMCO emissions component can read several types of emission inventories, as well as
other types atmospheric data sets, such as production and loss rates, or concentration data. We
have collated all of this data into a comprehensive directory tree structure. Each folder of the
HEMCO data directory tree represents a particular emissions inventory or other data set.
At present, the HEMCO data directory tree resides on the disk servers at Harvard University (and
soon at Dalhousie University). We have created a package that will let you download this
directory tree to your local disk storage space. For more information, please see
the Downloading the HEMCO data directories section below.
Please see our list of recommended default emission inventories, which has been compiled by
the Emissions and Deposition Working Group.
Default GEOS-Chem emissions configurations

Christoph Keller and the GEOS-Chem Support Team have prepared documents describing the
standard GEOS-Chem emissions configurations for recent GEOS-Chem versions. These
emissions configurations are specified in the HEMCO configuration file (aka HEMCO_Config.rc),
which is read by GEOS-Chem at startup.
Configuration Released Notes

Default emissions configuration for 26 Nov
GEOS-Chem 12.1.0 — current stable 2018
version
Default emissions configuration for 10 Aug Also applies to GEOS-
GEOS-Chem 12.0.0 2018 Chem 12.0.1, 12.0.2, and 12.0.3
Information about each individual inventory or data source may be found in the following
sections.
HEMCO data directory structure

The sections below describe each of the data sets contained in the HEMCO directory tree,
grouped by type.
In each of the tables below:
The Inventory column contains a link that describes each data set in more detail. Most of
these links point to existing pages on the GEOS-Chem wiki.
The Data file info column points to the README files that are stored with each data set.
Each README provides a list of the files contained within a given folder, information
about the data contained in each file, and (often) a description of how the files were
created.
The Path column shows the location of each data set, with respect to $ROOT, the top-
level HEMCO directory. For example, on the Harvard disk server, $ROOT points to the
directory /mnt/gcgrid/data/ExtData/HEMCO/.
The Status column describes the current status of each data set:
CURRENTLY Denotes that the data set is part of the standard emissions
USED configuration for GEOS-Chem, that is:
 It is used in the GEOS-Chem 1-month and 1-year full-

chemistry benchmark simulations, or
 It is used in one or more of the GEOS-Chem specialty
simulations.
OPTIONAL Denotes that the data set is not part of the the standard
GEOS-Chem emissions configuration.
 But you can still use the data set in your research
applications if you wish.
TO BE ADDED Denotes that the data set is not yet ready for use with
SOON HEMCO, but will be added soon.
OBSOLETE Denotes that the data set has been removed from the
standard GEOS-Chem emissions configuration.
 In most cases, OBSOLETE means that a newer version

of the data is available and should be used instead.
NOT USED Denotes that the data set is not used in the standard GEOS-
Chem emissions configuration, even if it is current.
 For example, another data source is being used in place

of this data set for a particular reason.
If use GEOS-Chem, then we recommend that you download the data sets that are listed
as CURRENTLY USED, as these form the standard GEOS-Chem emissions
configuration. You are free, however, to use any of the data sets listed below. Your
choice of data sets will depend on your particular research needs.
--Bob Y. 10:53, 18 March 2015 (EDT)
Aerosol emissions
The following subdirectories of the HEMCO directory tree contain
aerosol emission inventories.
Data Direct
Inventor
file Path ory Status
y
info size
Active inventories (turned ON by default in the standard
emissions configuration)
AEROC READ $ROOT/VOLCANO/v20 1.6 GB CURRENT
15-02
OM ME LY USED
volcanic
emission  Default
s global
invento
ry for
volcani
c SO2.
Tami READ $ROOT/BCOC_BOND/v 3.0 MB CURRENT
2014-07
Bond et ME LY USED
al (2007)
BC and  Default
OC global
emission
invento
s
ry for
black
carbon
(BC)
and
organic
carbon
(OC).
Secondar READ $ROOT/SOA/2014-07 3.0 MB CURRENT
y organic ME LY USED
aerosols
 Contain
various
inputs
for
SOA
simulati
ons.
Optional inventories (turned OFF by default in the standard
Spatially READ $ROOT/OMOC/v2018- 8.6 MB OPTIONA
01
varying ME L
OM/OC
ratios for  Control
SOA led by a
species
switch
in inpu
t.geos
(default
is OFF)
Future inventories (to be added in an upcoming version)
OMI- READ $ROOT/VOLCANO/v20 12 MB TO BE
18-03
based ME ADDED
volcanic SOON
emission
s  Will be
introdu
ced
in GC
12.0.3
 Covera
ge
extends
from
2005-
2012.
 Will
replace
the
AERO
COM
volcani
c
emissio
ns.
Obsolete inventories (superseded by newer developments)
Cooke et READ $ROOT/BCOC_COOKE/ 744 KB NOT
v2014-07
al BC ME USED
and OC
emission  Superse
s ded by
Bond et
al
(2007).
--Bob Yantosca (talk) 18:49, 2 July 2018 (UTC)
Anthropogenic and biofuel emissions
inventories of anthropogenic and biofuel emissions.
Please also see list of species included in each of these global
inventories and regional inventories.
Inventor Data Path Direc Status

y file tory
info size
CEDS READ $ROOT/CEDS/v2018 140 CURRENTLY
-04
anthropo ME GB USED
genic
emission  Introduced
s
in v11-02f
 New default
inventory
(replaces
EDGAR)
 CEDS is
also the
default ship
emissions
inventory
in GEOS-
Chem
12.1.0 and
later
versions.
C2H6 READ $ROOT/C2H6_2010/ 536 CURRENTLY
v2017-05
global ME KB USED
emission
s  Introduced
in v11-02f
 Will replace
the C2H6
emissions
from both
RETRO and
Y. Xiao
inventories.
DICE- READ $ROOT/DICE_Afric 202 CURRENTLY
a/v2016-10
Africa ME MB USED
anthropo
genic  Introduced
emission in v11-02f
s
GEIA READ $ROOT/NH3/v2014- 8.1 CURRENTLY
07
NH3 ME MB USED
(anthro,
biofuel,  Default
natural global
source) inventory
for biofuel
& natural
NH3.
 Anthro,
biofuel NH3
is
overwritten
by EDGAR
v4.2
RETRO READ $ROOT/RETRO/v201 38 CURRENTLY
4-07/orig_kgC
VOC ME MB USED
emission
s  Default
global
inventory
for VOC
species.
 C2H6 is
replaced by
Y. Xiao et
al
emissions.
 In v11-02,
C2H6 will
be taken
from
C2H6_2010
inventory
instead of
from
RETRO.
POET READ $ROOT/POET/v2017 38 CURRENTLY
-03/
(anthropo ME MB USED
genic
EOH  Introduced
inventory in v11-02a
)
Yevich & READ $ROOT/BIOFUEL/v2 1.1 CURRENTLY
014-07
Logan ME MB USED
biofuels
 Default
global
biofuel
emissions
inventory.
BRAVO READ $ROOT/BRAVO/v201 68 CURRENTLY
4-07
regional ME KB USED
anthropo
genic  Overwrites
CO, NO,
and SO2
over
Mexico.
EMEP READ $ROOT/EMEP/v2015 24 CURRENTLY
-03
regional ME MB USED
anthropo
genic  Overwrites
CO, NH3,
NO, SO2,
PRPE,
ALK4,
C2H6,
ALD2, and
MEK over
Europe.
MIX READ $ROOT/MIX/v2015- 623 CURRENTLY
03
Asian ME MB USED
anthropo
genic  Replaces
emission David
s
Streets et al
emissions.
 The base
years for
MIX is
2008 and
2010, as
opposed to
2006 for
Streets.
NEI2005 READ $ROOT/NEI2005/v2 8.1 CURRENTLY
014-09
regional ME MB USED
anthro/bi
ofuel  Overwrites
ACET,
ALK4,
ALD2, BC,
C2H6,
C3H8, CO,
CH2O,
MEK, NH3,
NIT, NO,
OC, PRPE,
SO2, and
SO4 over
the USA.
 Use
NEI2011
for
simulations
covering the
period
2006-2013;
otherwise
use
NEI2005.
 NOTE:
NEI2005 is
eventually
going to be
retired.
NEI/VIS READ $ROOT/VISTAS/v20 46 CURRENTLY
14-07
TAS ME1 $ROOT/VISTAS/v20 MB USED
14-07/VISTAS_NOX
scale READ $ROOT/VISTAS/v20
factors ME2 14-  Used to
07/VISTAS_WEWD
scale NO in
the
NEI2005
inventory.
NEI2011 READ $ROOT/NEI2011/v2 248 CURRENTLY
015-03
regional ME GB USED
anthro/bi
ofuel  Overwrites
(hourly CO, NO,
data)
NO2,
HNO2,
NH3,
CH2O,
RCHO,
MACR,
ACET,
ALK4,
PRPE,
EOH,
MOH,
XYLE,
TOLU,
BENZ,
SO2, SO4,
C2H4,
C2H6,
C3H8,
ALD2, BC,
and OC
over the
USA.
 Use
NEI2011
for
simulations
covering the
period
2006-2013;
otherwise
use
NEI2005.
NEI2011 READ $ROOT/NEI2011_ag 648 CURRENTLY
_only/v2015-03
agricultur ME MB USED
al
emission
s only
Trash READ HEMCO/TrashEmis/ 86 CURRENTLY
v2015-03/
burning ME MB USED
emission
s  Introduced
in #v11-
02f|v11-02f
EDGAR READ $ROOT/EDGARv42/v 4.5 OPTIONAL
2015-02
v4.2 ME $ROOT/EDGARv42/v GB
global 2015-02/CO  Was the
anthropo $ROOT/EDGARv42/v
2015-02/NH3 default
genic $ROOT/EDGARv42/v global
2015-02/NO
$ROOT/EDGARv42/v inventory
2015-02/SO2
$ROOT/EDGARv42/v
for NOx,
2015-02/VOCv2 CO, SO2,
and NH3
prior to v11-
02f|
 The
following
sectors are
not used:
 EDGAR
v4.2
ship
emission
s
 EDGAR
v4.2 soil
NO
emission
s
 EDGAR
v4.2
biomass
emission
s
 NAP is still
taken from
EDGAR v2
data.
EDGAR READ $ROOT/EDGARv43/v 6.2 OPTIONAL
2016-11
v4.3 ME GB
anthropo  Introduced
genic in v11-02f
emission
 Can be used
s
instead
of CEDS
MASAG READ $ROOT/MASAGE_NH3 4.4 OPTIONAL
/v2015-02
E ME MB
agricultur  Adds to the
al NH3 anthropogen
ic NH3
category.
HTAP READ $ROOT/HTAP/v2015 4.5 OPTIONAL
-03
global ME GB
anthro+bi  Can be used
ofuel instead of
EDGAR
v4.2
emissions.
 NOTE:
HTAP
includes
some
regional
emissions
from other
inventories.
If you select
HTAP you
might not
need to
select the
other
regional
inventories
in
HEMCO. S
ee this
document fo
r more
information.
Streets READ $ROOT/STREETS/v2 1.7 OPTIONAL
014-07
regional ME1 MB
anthro READ  Streets is
ME2 being
retired in
favor of
MIX.
 We will
keep Streets
as a
research
option. You
may use it if
you wish.
NEI2008 READ $ROOT/NEI2008/v2 3.0 OPTIONAL
015-02
regional ME GB
anthro/bi  We shall
ofuel
keep this as
a research
option
 NEI2008 is
superseded
by
NEI2011.
EPA/NEI READ $ROOT/NEI2011ek/ 365 TO BE
2018-04
2011ek ME GB ADDED SOON
anthropo
genic  Will replace
emission the
s (hourly
NEI2011
data)
hourly data
 To be
introduced
in a
future GEO
S-Chem
12version
EPA/NEI READ $ROOT/NEI2011ek/ 582 TO BE
v2018-04-MM
2011ek ME MB ADDED SOON
anthropo
genic  Aggregated
emission from the
s
hourly data
(monthly
-mean in HEMCO/NE
data) I2011ek/v2
018-04
 To be
introduced
in a
future GEO
S-Chem
12version
CAC READ $ROOT/CAC/v2014- 384 OBSOLETE
07
regional ME KB
anthropo  This was the
genic default
(1° x 1°
CAC
resolutio
n) inventory
for v10-
01and prior
versions
 Superseded
by v2016-09
GEIA READ $ROOT/GEIA/v2014 4.8 OBSOLETE
-07
global ME MB
anthropo  Slated for
genic replacement
by newer
inventories
EDGAR READ $ROOT/EDGAR/v201 40 OBSOLETE
4-07
v3 global ME MB
anthropo  EDGAR v3
genic has been
replaced
by EDGAR
v4.2.
CAC READ $ROOT/CAC/v2016- 29 OBSOLETE
09
regional ME MB
anthropo  Superseded
genic by the APEI
historical
Canadian
emissions
Yaping READ $ROOT/XIAO/v2014 308 OBSOLETE
-09
Xiao et al ME KB
C2H6  Superseded
and by
C3H8
CH26_2010
anthropo
genic and CEDS
in v11-02f
Anthropogenic aircraft and ship emissions
inventories of anthropogenic aircraft and ship emissions.
Data Direct
Invent
ory
info size
AEIC READ $ROOT/AEIC/v2015-01 2.0 GB CURRENT
aircraft ME LY USED
 Default
global
aircraft
emissio
ns
invento
ry.
 Contain
s fuel
burned,
NO,
CO,
and
hydroca
rbons.
EMEP READ $ROOT/EMEP/v2015-03 24 MB CURRENT
ship ME LY USED
(CO,
NO,  Overwr
SO2) ites
ship
CO,
NO,
SO2
over
Europe.
 Stored
togethe
r w/
other
EMEP
data
files.
ARCT READ $ROOT/ARCTAS_SHIP/v 508 OPTIONA
2014-07
AS ship ME KB L
emissio
ns  Superse
(SO2) ded by
CEDS
ship
emissio
ns
in GEO
S-
Chem
12.1.0 a
nd later
version
s.
 See
notes
below.
ICOAD READ $ROOT/ICOADS_SHIP/v 4.2 MB OPTIONA
2014-07
S ship ME L
(CO)
 Superse
ded by
CEDS
ship
emissio
ns
in GEO
S-
Chem
12.1.0 a
nd later
version
s.
 See
notes
below.
Corbett READ $ROOT/CORBETT_SHIP/ 1.8 MB OPTIONA
v2014-07
et al ME L
ship
emissio  Superse
ns ded by
(SO2)
CEDS
ship
emissio
ns
in GEO
S-
Chem
12.1.0 a
nd later
version
s.
 See
notes
below.
HTAP READ $ROOT/HTAP/v2015-03 4.5 GB OPTIONA
ship ME L
(CO,
NO,  Stored
SO2) togethe
r with
other
HTAP
data
files.
 See this
docume
nt for
more
informa
tion.
NEI201 READ $ROOT/NEI2011/v2015 248 OPTIONA
-03
1 ship ME GB L
(several
species  NOTE:
) Only
extends
a few
km
from
land, so
this is
more of
a
coastal
emissio
ns
invento
ry. It is
turned
off by
default.
EDGA READ $ROOT/EDGAR/v2014- 40 MB OBSOLET
07
R v3 ME E
ship
(CO)
EDGA READ $ROOT/EDGARv42/v201 4.5 GB NOT
5-02
R v4.2 ME USED
ship
 EDGA
R v4.2
ship
emissio
ns are
not
used
because
they are
lumped
with
other
non-
road
transpo
rtation
sectors
(aircraft
, rail,
etc),
and
thus
cannot
be
easily
separat
ed.
NOTES about ship emissions:
1. CEDS ship emissions are the default ship inventory in GEOS-

Chem 12.1.0 and later versions.
 Data files for CEDS ship emissions are stored with the
other CEDS emission sector files in the HEMCO data
path: $ROOT/CEDS/v2018-04/.
2. If CEDS emissions are turned off above then:
 ARCTAS should be used over ICOADS, CORBETT, and
HTAP for SO2
 ICOADS should be used for CO and NO.
3. Ship emissisons over Europe are ovewritten by EMEP.
4. The NEI2011 ship inventory only goes a few km from land, so it
isn’t a complete "ship inventory". This is turned off by default in
the HEMCO configuration files that ship with GEOS-Chem.
Biomass burning emissions
inventories of biomass burning emissions.
Invento Data Directo

Path Status
ry file info ry size
GFED4 READ $ROOT/GFED4/v20 692 CURRENTLY
15-10
biomass ME MB USED
burning
(v4.1)  This is
GFED
v4.1,
which is
the default
in v11-
01 and
higher
versions
 Monthly-
mean data
is available
from 1998-
2016
 Uses daily
scale
factors
from
GFED3.
 Uses 3-
hourly
scale
factors
from
GFED3.
FINN READ $ROOT/FINN/v201 1.1 GB TO BE
8-04
biomass ME ADDED
burning SOON
(v1.6)
 NOTE:
Awaiting
reprocesse
d data files
to correct
an error.
 Compatibl
e with v11-
02 and
higher
versions
FINN READ $ROOT/FINN/v201 689 OPTIONAL
5-02
biomass ME MB
burning  Compatibl
(v1.5) e with v11-
01
QFED READ $ROOT/QFED/v201 57 GB OPTIONAL
8-07
biomass ME
burning  QFED
(v2.5r1) v2.5r1 data
extends
from 2000-
2017 (at
present)
 Compatibl
e
with 12.0.0
|GEOS-
Chem
12.0.0
QFED READ $ROOT/QFED/v201 57 GB OPTIONAL
4-09
biomass ME
burning  QFED
(v2.4r6) v2.4r6 data
ends in
October
2016.
GFED4 READ $ROOT/GFED4/v20 115 OBSOLETE
15-06
biomass ME MB
burning  This was
(v4.0) the default
in v10-
01 and
prior
versions.
 Supersede
d by
GFED
v4.1
GFED3 READ $ROOT/GFED3/v20 343 OBSOLETE
14-10
biomass ME MB
burning  Retired
in GEOS-
Chem v11-
02
GFED2 READ $ROOT/GFED2/v20 196 KB OBSOLETE
14-07
biomass ME
burning  Supersede
d by
GFED4.
Duncan READ $ROOT/BIOBURN/v 925 OBSOLETE
2014-07
et al ME MB
biomass  Supersede
burning d by
GFED4.
--Bob Yantosca (talk) 15:08, 22 June 2018 (UTC)
Emissions implemented as HEMCO extensions
The following subdirectories of the HEMCO directory tree contain input
data used by various HEMCO extensions. These HEMCO extensions
compute emissions for quantities that depend on meteorological
variables (e.g. emissions from lighting, biogenic processes, etc.).
NOTE: GFED3, GFED4 and FINNv1 are implemented as HEMCO
extensions, but we have listed them with the other biomass burning
inventories, for clarity.
Data Direct
Inventor
y
info size
Acetone READ $ROOT/ACET/v201 52 KB CURRENTL
4-07
ocean ME Y USED
exchange
DEAD READ $ROOT/DUST_DEAD 712 CURRENTL
/2014-07
dust ME KB Y USED
model
 Default
dust
mobilizati
on scheme
Anthropo READ $ROOT/DUST_DEAD 4.4 CURRENTL
/2018-04
genic ME MB Y USED
PM2.5
dust  Introduced
source in GEOS-
(AFCID)
Chem
12.1.0.
 AFCID
will be
used if the
DEAD
dust
emissions
extension
is
activated.
DMS READ $ROOT/DMS/v2015 3.0 CURRENTL
-07
ocean ME MB Y USED
exchange
 This is the
default
in v11-
01 and
higher
versions
 Uses Lana
2011
climatolog
y
MEGAN READ $ROOT/MEGAN/v20 17 MB CURRENTL
17-07
biogenic ME Y USED
emissions
 Now uses
high-
resolution
(0.25°)
data files
READ $ROOT/MEGAN/v20 12 MB CURRENTL
18-05
ME Y USED
 Introduced
in v11-02-
rc
 Fixes a
regridding
issue in
the high-
resolution
MEGAN
AEF data
files.
NO from READ $ROOT/LIGHTNOX/ 8.5 CURRENTL
v2017-09
lightning ME MB Y USED
 Introduced
in GEOS-
Chem
v11-02
 GEOS-FP
OTD-LIS
factors for
2012/04 -
2017/07
 MERRA-
2 OTD-
LIS
factors for
any date
NO from READ $ROOT/LIGHTNOX/ 13 MB CURRENTL
v2014-07
lightning ME Y USED
 CDF table
from Ott
et al.
[JGR,
2010]
 OTD-LIS
factors
supersede
d
by LIGHTN
OX/v2017-
09
NO from READ $ROOT/SOILNOX/v 79 MB CURRENTL

2014-07
soils/fertil ME Y USED
izers
PARANO READ $ROOT/PARANOX/v 162 CURRENTL
2015-02
X ship ME MB Y USED
plume
model  Computes
the aging
of
emissions
in ship
exhaust
plumes.
GINOUX READ $ROOT/DUST_GINO 36 KB OPTIONAL
UX/2014-07
dust ME
model  You can
use this in
place of
the DEAD
dust
model.

DMS READ $ROOT/DMS/v2014 2.2 OBSOLETE
-07
ocean ME MB
exchange  Supersede
d by the
Lana 2011
climatolog
y
MEGAN READ $ROOT/MEGAN/v20 2.0 OBSOLETE
15-02
biogenic ME MB
emissions  Supersede
d
by MEGAN/
v2017-
07 and MEG
AN/v2018-
05.

Future and historical emissions
historical and future emissions inventories.
Invento Data file Directo

Path Status
ry info ry size
APEI READM $ROOT/APEI/v20 68 MB CURRENT
16-11/
historica E LY USED
l
Canadia  Introduc
n ed
emission
in v11-
s
(1989- 02f
2014)
RCP READM $ROOT/RCP/v201 368 MB OPTIONAL
5-02
future E
scenario  RCP
s emission
s are not
part of
the
standard
GEOS-
Chem
emission
s
configur
ation but
may be
used as a
research
option.
GEOS-Chem specialty simulation data
The following subdirectories of the HEMCO directory tree input data
(emissions, oxidants, etc.) for use with the GEOS-Chem specialty
simulations. If you do not regularly use these simulations, you may
choose not to download these data directories.
Direct
Invento Data
Path ory Status
ry file info
size
Aerosol- READ $ROOT/OFFLINE_AEROS 165 CURREN
OL/v2014-09
only ME MB TLY
simulati USED
on
CH4 READ $ROOT/CH4/v2014-09 274 CURREN
simulati ME MB TLY
on USED
CO2 READ $ROOT/CO2/v2015-04 1033 CURREN
$ROOT/CO2/v2015-
simulati ME1 04/BIO/ MB TLY
on READ $ROOT/CO2/v2015- USED
ME2 04/BIOFUEL/
$ROOT/CO2/v2015-
READ 04/CHEM/
ME3 $ROOT/CO2/v2015-
READ 04/FOSSIL/
$ROOT/CO2/v2015-
ME4 04/OCEAN/
READ
ME5
READ
ME6
Mercury READ $ROOT/MERCURY/v2014 342 CURREN
-09
simulati ME1 $ROOT/MERCURY/v2014 MB TLY
on READ -09/ARTISANAL USED
ME2 $ROOT/MERCURY/v2014
-09/BrOx
READ $ROOT/MERCURY/v2014
ME3 -09/Hg2_PARTITION
-09/JVALUES
READ -09/NATURAL
-09/NEI2005
ME6 -09/OCEAN
-09/SOIL
-09/STREETS
READ
ME8
READ
ME9
READ
ME10
POPs READ $$ROOT/POPs/v2015- 809 CURREN
08
simulati ME MB TLY
on USED
 Data
corres
ponds
to
the PO
Ps
simula
tion
update
in
v11-
01c
RRTM READ $ROOT/RRTMG/v2018- 19 MB TO BE
11
G ME ADDED
radiative SOON
transfer
model  Used
in GE
OS-
Chem
12.1.0
and
later
versio
ns
Tagged READ $ROOT/TAGGED_CO/v20 260 CURREN
17-04
CO ME KB TLY
simulati USED
on
 Contai
ns
files
for the
update
d
Tagge
d CO
simula
tion
in GE
OS-
Chem
v11-
02
Tagged READ $ROOT/TAGGED_O3/v20 372 CURREN
14-09
O3 ME MB TLY
simulati USED
on
O3 for READ $ROOT/O3/v2014-09 130 CURREN
offline ME MB TLY
simulati USED
ons
OH for $ROOT/OH/v2014-09 148 CURREN
$ROOT/OH/v2014-
offline READ 09/v5-07-08 MB TLY
simulati ME1 $ROOT/OH/v2014- USED
ons READ 09/v7-02-03.GMI
ME2
H2O2 READ $ROOT/OXIDANTS/v201 32 MB CURREN
4-07
for ME TLY
offline USED
simulati
ons
Oceanic READ $ROOT/CHLA/v2014-07 2.0 CURREN
Chlorop ME MB TLY
hyll-A USED
for Hg
simulati
ons
CH3I READ $ROOT/CH3I/v2014-07 280 OBSOLE
simulati ME KB TE
on
 This
simula
tion is
no
longer
used
in
GEOS
-Chem
(await
ing
reviva
l)
POPs READ $ROOT/POPs/v2014-09 622 OBSOLE
simulati ME MB TE
on
 Supers
eded
by v20
15-08
Tagged READ $ROOT/TAGGED_CO/v20 260 OBSOLE

CO ME 14-08q KB TE
simulati
on  Supers
eded
by v20
17-04

Halogen emissions
inventories of bromine and iodine emissions.
NOTE: See our Non-emissions data section for information about
stratospheric bromine concentration data.
Invento Data Directo
Path Status
ry file info ry size
Liang et READ $ROOT/BROMINE/v2 156 KB CURRENT
015-02
al VSL ME LY USED
emissio
ns
Ordonez READ $ROOT/IODINE/v20 4.4 MB CURRENT
17-03
et al ME LY USED
Iodine
emissio  Introduc
ns ed
in v11-
02
Natural emissions data
inventories natural emissions.
Inventor Data file Director

Path Status
y info y size
NH3 READM HEMCO/NH3/v201 104 MB CURRENTL
8-04/
emission E Y USED
s from
arctic sea  Introduce
birds d in v11-
02f
Non-emissions data
The following subdirectories of the HEMCO directory tree input data
contains non-emissions data sets. Most of these are used as inputs to
GEOS-Chem's chemistry modules (i.e. photolysis, stratospheric
chemistry, etc.).
Data Direct
Inventor
y
info size
GMI READ $ROOT/GMI/v201 16 GB CURRENTLY
5-02
strat ME USED
chem
mechani  Used to
sm compute P &
L of species
in the
stratosphere.
Stratosp READ $ROOT/STRAT/v2 385 CURRENTLY
015-01/Bry
heric ME MB USED
Bry from
CCM  Required for
the for the
full-chemistry
simulations.
Timezon READ $ROOT/TIMEZONE 264 CURRENTLY
S/v2015-02
e offsets ME KB USED
from
UTC  Used by
HEMCO to
compute
emissions that
depend on
local time
rather than on
UTC time.
TOMS/S READ $ROOT/TOMS_SBU 21 CURRENTLY
V/v2016-11
BUV O3 ME MB USED
columns
 This is default
in v11-01 and
higher
versions.
 These files are
the same data
as
in $ROOT/TOMS
_SBUV/v2015-
03,but were
reprocessed
by Barron
Henderson in
order in order
to fix a
strange cycle
in OH output
when running
GEOS-Chem
with GEOS-5
met.
 Ignored if you
are
using GEOS-
FP or MERR
A-
2 meteorology
.
UCX READ $ROOT/UCX/v201 12 GB CURRENTLY
8-02
chemistr ME USED
y
mechani  Used to
sm compute P &
L of species
in the
stratosphere.
 Can be used
instead of
GMI.
UV READ $ROOT/UVALBEDO 476 CURRENTLY
/v2015-03
surface ME KB USED
albedoes
 Required
inputs for
the FAST-JX
v7.0
photolysis
mechanism
TOMS/S READ $ROOT/TOMS_SBU 17 OBSOLETE
V/v2015-03
BUV O3 ME MB
columns  Superseded
by v2016-11
Oceanic emissions
The following folders contain data used to compute oceanic emissions
of GEOS-Chem species.
Data Directo
Inventory Path Status
file info ry size
Fields to READ $ROOT/ALD2/v2 0.5 MB CURRENT
017-03
compute ME LY USED
ALD2
emissions  Introdu
ced
 Seawater with
concentra the PA
tion of N
acetaldeh updates
yde in v11-
 Heterotro 02a.
phic
respiratio
n rates,
used to
compute
biogenic
emissions
of ALD2
and EOH
Other inputs for HEMCO
The following subdirectories of the HEMCO directory tree input data for
various HEMCO functions. These include regional masks, emission
scale factors, and grid information.
Invento Data Direct

Path Status
ry file ory
info size
Annual READ $ROOT/AnnualScalar 3.0 CURRENT
/v2014-07
scale ME MB LY USED
factors
 Used to
scale
NEI200
5 and
other
emissio
ns to
years
other
than the
inventor
y base
year.
ID READ $ROOT/COUNTRY_ID/v 15 MB CURRENT
2015-04
codes ME LY USED
for each
country  ISO
ALPHA
-3
standard
country
codes
are
containe
d on an
0.1° x
0.1°
grid.
HEMC
O can
use
these
ID's to
apply
country-
level
scale
factors
to any
emissio
ns field.
Mask READ $ROOT/MASKS/v2014- 51 MB CURRENT
07
files for ME LY USED
regional
emissio  Masks
ns define
the
geograp
hical
regions
where
the
various
regional
emissio
ns (e.g.
BRAVO
, CAC,
NEI) are
to be
applied.
MAP_A READ $ROOT/MAP_A2A/v201 152 CURRENT
4-07
2A ME KB LY USED
regriddi
ng data
Weekly READ $ROOT/WEEKSCALE/v2 4.0 KB OBSOLET
014-07
scale ME E
factors
 Not
currentl
y in use
Downloading the HEMCO data directories

The GEOS-Chem Support Team has created a package
called hemco_data_download. With this package, you can download
the various emissions inventories and related data files for HEMCO to
your own disk server. Furthermore, you can specify which data
directories that you would like to download (as well as those you would
like to ignore) via a configuration file.
Obtaining the hemco_data_download package
To obtain the hemco_data_download package, use Git to clone this
repository
git clone
https://github.com/GCST/hemco_data_download.git
This will create a directory named hemco_data_download, in which

you should see the following files:
File Description
README File with an overall description of the
directory contents
hemcoDataDownload.pl Perl script to download HEMCO data
directories
hemcoDataDownload.rc Configuration file for
the hemcoDataDownload.pl script. In
this file you can specify which
HEMCO data directories you would
like to download and which you would
like to omit.
forTesting.rc A configuration file that you can use
for testing or debugging. This will
tell hemcoDataDownload.pl only to
download a couple of emissions
inventories with files that do not take
up much disk space.
Setting up the configuration file
The configuration files
(i.e. hemcoDataDownload.rc and forTesting.rc) are pretty much
self-explanatory.
At the top of the configuration file you will see this section:
########################################################
#######################
#
#
# Specify the remote and local HEMCO data paths, plus
other options. #
#
#
########################################################
#######################
Remote HEMCO data path |

ftp://ftp.as.harvard.edu/gcgrid/data/ExtData/HEMCO
Your HEMCO data path | /as/scratch/bmy/HEMCO
Verbose output | yes
Dryrun only? | no
Path Description
Remote Location on the FTP server from which you are
HEMCO data
path going to download the data. This can be from
either Harvard or from Dalhousie. (For now we
will use the Harvard server). You can edit this
accordingly.
Your HEMCO The root-level directory for HEMCO data on your
data path
own disk space. If you are not sure where to place
this, then ask your sysadmin.
Verbose Lets you specify if you want to print out extra
output
output during the download process. This can be
set to either "yes" or "no".
Dryrun Allows you to print out the data download
only
commands without actually downloading the data.
This is useful for debugging. This can be set to
either "yes" or "no".
In the next section you specify all of the HEMCO inventories that you
want to download. You will see this header:
########################################################
#######################
#
#
# THE FOLLOWING DATA DIRECTORIES WILL BE DOWNLOADED.
#
#
#
# These data directories comprise the recommended
emissions configuration #
# for typical GEOS-Chem full-chemistry and specialty
simulations. #
#
#
# NOTE: In most cases, you only have to specify the
top-level folder. #
# All subfolders will be downloaded automatically.
#
#
#
########################################################
#######################
#=============================+=========================
=======================
# AEROSOLS | Directory paths
#=============================+=========================
=======================
AEROCOM volcano emissions | $ROOT/VOLCANO/v2014-10
Bond et al BC/OC | $ROOT/BCOC_BOND/v2014-07
Cooke et al BC/OC | $ROOT/BCOC_COOKE/v2014-
07
Secondary organic aerosols | $ROOT/SOA/v2014-07
... etc ...
Each line specifies the name of a HEMCO emissions inventory and the
data path where it can be found on disk, relative to the root data path.
NOTE: The script will replace the $ROOT token with the value you gave
to the "HEMCO remote data path" above. (Lines starting with the
comment character # will be ignored.)
Any inventory found in this section will be downloaded. To prevent an
inventory from being downloaded you can either comment it out (i.e.
place a # in the first column) or move the inventory to the next section.
The final section specifies HEMCO emission inventories that you do not
wish to download. The section looks like this:
########################################################
#######################
#
#
# THE FOLLOWING DATA DIRECTORIES WILL NOT BE
DOWNLOADED. #
#
#
# These data directories contain are optional emissions
inventories that #
# are not used in typical GEOS-Chem simulations. If
you wish to download #
# any of these inventories, simply move the
corresponding entry for each #
# inventory to the previous section.
#
#
#
########################################################
#######################
CH3I simulation (obsolete) | $ROOT/CH3I/v2014-07

Chlorophyll A | $ROOT/CHLA/v2014-07
... etc ...

Downloading the data
Once you have set up your configuration file, you can run
the hemcoDataDownload.pl script to start downloading the HEMCO
data to your local server. To run the script you can type:
hemcoDataDownload.pl
If you do not specify a configuration file name, then

the hemcoDataDownload.pl scriptwill read the default configuration
file hemcoDataDownload.rc configuration file. If you wish to specify a
different configuration file name, simply pass that as an argument to the
script, e.g.
hemcoDataDownload.pl myNewConfigFile.rc
Before you start downloading GB's of data, we recommend that you run
a short test to make sure that the data directories are being copied to
the proper locations on your disk server. For this purpose, we have
provided a configuration file named forTesting.rc. Typing
hemcoDataDownload.pl forTesting.pl
will only download a couple of data inventories that do not take up much
disk space. This allows you to ensure that the data transfer is sucessful
without making you wait a long time.
New features for the GEOS-Chem v10-01 public release
For the GEOS-Chem v10-01 public release, we modified the default
download options in the hemcoDataDownload.pl script. We changed
the default wget options from:
wget r -nH -q ...
to
wget -r -nH -c -N -q ...
This will tell wget to only download new or modified files, instead of
trying to download the entire data archive from scratch. This should
hopefully subsequent data download processes faster.
--Bob Y. (talk) 18:35, 16 June 2015 (UTC)
Submitting new data for use with HEMCO

If you have a new emissions inventory or other atmospheric data set
that you would like to add to the HEMCO data directories, then please
contact the GEOS-Chem Support Team. Data files must be in
COARDS-compliant or CF-compliant netCDF format. Please see
our Preparing data files for use with HEMCO wiki page for more
information.
Restart files
You will need a restart file before you can start your GEOS-Chem simulation.
A restart file contains the initial conditions for a GEOS-Chem simulation.
There are two restart files for GEOS-Chem:
1. GEOS-Chem restart file containing instantaneous species
concentrations (Required)
2. HEMCO restart file containing values needed for some of the HEMCO
extensions (Optional)
When you run a GEOS-Chem simulation, it will write new GEOS-Chem restart
files at the intervals you specify in input.geos. New HEMCO restart files are
written with frequency configured in HEMCO_Config.rc if HEMCO is used in your
simulation.
GEOS-Chem v11-01 run directories are configured to use initial GEOS-Chem
restart files in netCDF format. These files are available for download at:
ftp://ftp.as.harvard.edu/gcgrid/data/ExtData/SPC_RESTARTS
/
CAVEAT: The initial restart files do not reflect the actual atmospheric
state and should only be used to "spin up" the model. In other words,
they should be used as initial values in an initialization simulation to
generate more accurate initial conditions for your production runs.
Doing a one year spin up is usually sufficient; however, we recommend ten
years for ozone, carbon dioxide, and methane simulations, and four years for
radon-lead-beryllium simulations. If you are in doubt about how long your spin
up should be for your simulation, we recommend contacting the GEOS-Chem
Working Group that specializes in your area of research.
You may spin up the model starting at any year for which there is met data,
but you should always start your simulations at the month and day
corresponding to the restart file to more accurately capture seasonal variation.
If you want to start your production run at a specific date, we recommend
doing a spin up for the appropriate number of years plus the number of days
needed to reach your ultimate start date. For example, if you want to do a
production simulation starting on 12/1/13, you could spin up the model for one
year using the initial GEOS-FP restart file dated 7/1/13 and then use the new
restart file to spin up the model for five additional months, from 7/1/13 to
12/1/13.
To determine the date of a netCDF restart file, you may use ncdump For
example:
ncdump -v time -t initial_GEOSChem_rst.4x5_standard.nc
The -t option will return the time value in human-readable date-time strings
rather than numerical values in unit such as "hours since 1985-1-1 00:00:0.0."
The date of a binary punch restart file can be determined by opening the file in
GAMAP.
Using a HEMCO restart file for your initial spin up run is optional. The HEMCO
restart file contains fields for initializing variables required for Soil NOx
emissions, MEGAN biogenic emissions, and the UCX chemistry mechanism.
The HEMCO restart file that comes with a run directory may only be used for
the date and time indicated in the filename. HEMCO will automatically
recognize when a restart file is not available for the date and time required,
and in that case HEMCO will use default values to initialize those fields. You
can also force HEMCO to use the default initialization values by setting
"HEMCO_RESTART" to false in HEMCO_Config.rc. For more information, see
the HEMCO User's Guide.
You can read more about restart files at the GEOS-Chem output files wiki
page.
--Melissa Sulprizio (talk) 16:03, 12 January 2017 (UTC)
Visualization packages
In this section we provide information about software packages that you can
use to analyze and plot GEOS-Chem output.
GAMAP and other IDL software
NOTE: IDL, which is proprietary software, can be very expensive. For
this reason, the GEOS-Chem Support Team and other GEOS-Chem
developers are currently developing several open-source software
packages (mostly based on Python) for GEOS-Chem data analysis and
visualization. Please see our Python software section below.
The traditional GEOS-Chem visualization software is GAMAP. This package
was customized to GEOS-Chem and is still heavily used today. GAMAP
requires the Interactive Data Language (a proprietary package). For more
information about GAMAP, please see:
 GAMAP web page

 GAMAP online manual
 Documentation for individual GAMAP routines
 GEOS-Chem wiki: GAMAP tips and tricks
We have also compiled a list of other useful IDL software sites.
 IDL Astronomy User's Library

 JHU/APL/S1R IDL routines page
 Craig Markwardt's IDL library
Python software
Several developers have started creating Python-based visualization software
for GEOS-Chem. Please see the following page for more information:
 GEOS-Chem wiki: Python code for GEOS-Chem

 GCPy: Python powered GEOS-Chem data
analysis/visualization (Currently under development)
If you are new to programming in Python, you may find these tutorials useful:
 Google's Python course

 Python 3 tutorial
 Learn Python the hard way book

The GEOS-Chem website is located at http://www.geos-chem.org.
From this website you may:
 Read a welcome letter which outlines user responsibilities

 Read the online GEOS-Chem User's Guide
 Access GEOS-Chem-related publications
 View online presentations from GEOS-Chem user meetings
 See a list of who is using GEOS-Chem at other institutions
 Obtain information about the GAMAP visualization package
Also, please take a minute to read the GEOS-Chem overview page. This
document outlines the responsibilities for all GEOS-Chem users.
PLEASE NOTE: At this time, the GEOS-Chem User's Guide is only
viewable in HTML.

GEOS-Chem v11-02-final will also carry the
designation GEOS-Chem 12.0.0. We are migrating to a
purely numeric versioning system in order to adhere
more closely to software development best practices.
For a complete description of the new versioning
system, please see our GEOS-Chem version numbering
system wiki page.
5. GEOS-Chem Source Code Directory
The GEOS-Chem source code directory contains the Makefile and

Fortran-90 source code files (i.e. *.F, *.F90 files). Compiling the
source code with a Fortran compiler creates the GEOS-Chem
executable geos.
IMPORTANT NOTE! As of June 2018, we have migrated the

GEOS-Chem source code repository from Bitbucket back to
Github. Going forward, please make sure to clone or pull code
updates ONLY from the Github repository. Using Github will
allow us to define a DOI for each GEOS-Chem major version.
The GEOS-Chem source code directory is kept in the following Git

repository on Github.com:
https://github.com/geoschem/geos-chem
All official releases of the GEOS-Chem code shall originate from

this repository. You can download the latest stable version of
GEOS-Chem (currently 12.0.0) by means of the git
clone command by typing the following at the command line:
git clone https://github.com/geoschem/geos-chem

Code.12.0.0
cd Code.12.0.0
git checkout master
NOTE: We recommend using the current version number (i.e.
12.0.0) in the code-directory name.
This will create an exact copy (or clone) of the official GEOS-Chem
repository to your local disk space in a directory
named Code.GC12. Using Code.GC12 as your local repository
name is optional and you may specify a different directory name if
you wish. When you clone the source code you will always get the
most recent state of the repository, meaning the latest GEOS-Chem
version or bug fix patch.
You can download as many copies of the GEOS-Chem source

code as you wish. For example, you might want to keep a clean
source code directory and then have one or more source code
directories that you use for development or debugging.
Alternatively, you may use Git version control to keep all of your
work in different branches of a single clone of the repository. For
detailed information about Git and downloading the GEOS-Chem
source code, please visit the following GEOS-Chem wiki pages:
 Using Git with GEOS-Chem

 Version control with Git
If you wish to obtain an earlier version of GEOS-Chem, such as

v11-01, please see the Reverting to an older state of the code wiki
post.
Using Git with GEOS-Chem

This page describes how to use the Git version control system to download and manage the
GEOS-Chem source code package.
Contents
[hide]
 1 Obtaining and installing Git

 2 Downloading a new GEOS-Chem version
o 2.1 Initial download
 2.1.1 Code directory
 2.1.2 Run directories
 2.1.3 Shared data directories
o 2.2 Ignoring files
 3 Viewing the revision history
 4 Making revisions
o 4.1 Using the GUI browser
o 4.2 Creating branches
o 4.3 Committing
o 4.4 Renaming files
o 4.5 Switching between branches
o 4.6 Merging
o 4.7 Resolving conflicts caused by a merge
o 4.8 Tagging
o 4.9 Deleting branches
 5 Sharing your revisions with others (and vice versa)
o 5.1 Creating a patch file to share with others
o 5.2 Checking the validity of a patch file
o 5.3 Reading a patch file into your local repository
 5.3.1 Invalid email address error
 5.3.2 "Patch does not apply" error
o 5.4 More about patch files
 6 Getting updates from the remote repository
 7 Advanced Git usage
o 7.1 Reverting to an older state of the code
o 7.2 Adding a patch that was made to a previous version
o 7.3 Cherry-picking individual commits from another branch
 8 In summary
Obtaining and installing Git

You will need to make sure that Git is installed on your system. Git is free, open-source software.
You may want to ask your sysadmin or IT department to install Git for you. Please see this wiki
post for more information.
Downloading a new GEOS-Chem version
Initial download
Code directory
The GEOS-Chem source code repository is available for remote download via Git. We
recommend that you download each new version of GEOS-Chem into a separate source code
directory.
All users should use the following syntax:
git clone https://github.com/geoschem/geos-chem LOCAL_DIR_NAME
where LOCAL-DIR-NAME is the name of the local directory on your disk into which the GEOS-
Chem source code files will be placed. It is up to you to pick LOCAL-DIR-NAME.
For more information, please see Chapter 5: GEOS-Chem source code directory in the GEOS-
Chem Online User's Guide.
Run directories
There is a unique run directory for every combination of GEOS-Chem simulation type, grid
resolution, meteorological data source, and nested region. A collection of GEOS-Chem run
directories are stored in the GEOS-Chem Unit Tester which is available for download via Git.
More information can be found on the following wiki pages:
 Installing the GEOS-Chem Unit Tester

 Creating GEOS-Chem run directories
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.
For more information about how to download these directories, please see Chapter 4: GEOS-
Chem shared data directories in the GEOS-Chem Online User's Guide.
Ignoring files
Git also allows you to ignore certain types of files that we don't need to track (e.g. anything that
can be built from the source code). These typically include:
 Object files (*.o)

 Library files (*.a)
 Module files (*.mod)
 Autosave files (*~)
 Executable files (geos, geostomas)
You can tell Git that you don't want these files to be tracked by editing the .gitignore file in your
source code directory. Open this file in your favorite text editor and edit it.
Viewing the revision history

The best way to examine the contents of your Git-backed GEOS-Chem source code is to use
the gitk viewer. There are two ways to do this:
(1) Change into your code directory and start gitk as follows:
gitk --all & # This will show ALL open branches
(2) Or if you are using the git gui GUI browser (more on that below), you can
invoke gitk from the Repository/Visualize master's History menu item.
At the top left of the gitk screen, you will see the graph of revisions. Each dot represents
a commit, along with the log message that accompanied each commit.
Note that at the most recent commit (i.e. the line at the very top) there are 2 green
boxes, one labeled master and one labeled remotes/origin/master:
1. remotes/origin/master: This was the state of the repository on the remote

server when you checked it out for the first time. Therefore, this is the "pristine",
unchanged code that you got from the download.
2. master: This is the current state of the local repository now. Since we haven't
done anything to the code yet, master and remotes/origin/master point to the
same commit.
If you click on any of the commits in the top left window, in the window below, you will
see the log message and a list of changes to the source code. The old code is marked
in RED and the new code is marked in GREEN. At right you will also see a list of files
that were changed during the commit.
With gitk, it's really easy to see how the code has evolved over time.
Making revisions
Using the GUI browser
We recommend using the git gui for source code management. Start this in your code
directory:
git gui &
On the left there are 2 windows:
1. Unstaged Changes: An unstaged change is a modification that Git does not

know about yet. If you modified any files since the last commit, then they should
be displayed in this window. Also, right above this window you will find the name
of the current checked-out branch.
2. Staged Changes: These are changes that Git will add to the repository the very
next time you make a commit.
In general, anytime you need to modify the source code, you should NOT do it on
the master branch. You should create a new branch for your modifications. Then you
can test your modifications ad nauseum until you are sure that everything is functioning
as it should. When your modifications are complete, you can merge your branch into
the master branch. You can then delete the branch you created.
The advantage of this approach is that if you ever need to start over from scratch, you
can just go back to the master branch and you will get back the state of the code before
your modifications were added.
Creating branches
To create a new branch in the git gui, go to the Branch/Create on the menu bar (or
type CTRL-N). You will get a dialog box that prompts you for the new branch name.
Type a unique name and then click OK.
You should pick names that have meaning to you. Some good branch names are:
 Bug_fix_sulfate_mod
 CO2_simulation
 KPP_with_isoprene
 Methane_simulation
You will be automatically placed into the branch you have just created.
Committing
With Git, you should commit frequently, such as when you have completed making
revisions to a file or group of files. Commits that are made on one branch will not affect
the other branches.
Committing is best done with the git gui. Follow these steps:
1. Pick Commit/Rescan from the menu (or type the F5 key) to force the git gui to
show the latest changes.
2. You should get a list of files in the Unstaged Changes window. Clicking on the
icons on the left of the file names will send them to the Staged
Changes window. Git will add all of the files in Staged Changes to the
repository on the next time you commit. Note: Clicking on the icon of the files in
the Staged Changes moves back the file to the Unstaged Changes window.
3. Type a Commit message in the bottom right window. See this example of a
good commit message. Some pointers are:
1. The first line should only be 50 characters or less and succinctly
describe the commit
2. Then leave a blank line
3. Then add more in-depth text that describes the commit
4. Then click on the Signed-off by button. This will add your name, email
address, and a timestamp. Note: To modify your name and email
address, edit the .gitconfig file in your home directory.
4. There are two radio buttons above the Commit message window.
1. New commit: This is the default. Assumes we are making a totally new
commit.
2. Amend last commit: If for whatever reason we need to update the last
commit message, pick this button.
5. Click on the Commit button.
If you then start the gitk viewer, your new commit should be visible.
Renaming files
In some instances you may find it necessary to rename files. For example, in GEOS-
Chem v9-01-02, we have had to rename file ending in .f to .F and .f90 to .F90. If only
the name of the file changes, then Git will recognize it as a renamed file in the repository.
To rename a file, follow these steps:
1. Change the name of the file with the Unix mv command. For example: mv
myfile.f myfile.F
2. Open the git gui. You will see the two files myfile.f and myfile.F listed in
the Unstaged Changes window.
3. Click on myfile.f and myfile.F; this will move them to the Staged
Changes window.
4. In Staged Changes you will see:
1. File myfile.f is slated to be removed (i.e. a red "X" is listed next to the
file name).
2. File myfile.F is slated to be added (i.e. a green checkmark is listed
next to the file name).
5. Add a commit message, sign off, and click Commit as described above.
6. Start the gitk browser. In the lower left window, you should see text such as:
---------------- GeosCore/myfile.F --------------------------

similarity index 100%
rename from GeosCore/myfile.f
rename to GeosCore/myfile.F
From this point forward, file myfile.F will use the *.F file extension. However, it will still
possess the total revision history from when the file was still named myfile.f. If you
merge changes from another repository that still has myfile.f, then these changes will
be seamlessly integrated into myfile.F.
Switching between branches
Before you switch from one branch to another (aka "checking out a branch"), it is
recommended to commit any remaining unstaged files to the current open branch.
Unstaged files will remain in your working directory even after you checkout a different
branch. This can potentially lead to confusion or may cause an error message from Git.
To checkout a new branch in the git gui, go to Branch/Checkout on the menu and pick
the name of the branch you would like to switch to. The current branch name will be
displayed just below the menu at top left.
Once you have created your branch and have checked it out, then you may begin
making modifications to the source code with your favorite text editor.
We recommend keeping one open branch per new feature that you are adding into
GEOS-Chem. This lets you test each individual feature separately. After each feature
has been validated, you may merge each individual branch back into the master branch.
Merging
When you are ready to merge your changes back into the mainline master branch, then
you can follow this procedure.
1. Switch back to the master branch by selecting Branch/Checkout from the

menu (or type CTRL-O). You will be given a dialog box of available branches.
Select master and click Checkout.
2. From the menu, pick Merge/Local Merge (or CTRL-M). You will be given a
dialog box of available branches. Select the branch you would like to merge
into masterand click Merge.
This should merge your changes back into master. If you then start the gitk viewer, you
should see your changes merged into the master branch.
Resolving conflicts caused by a merge
Sometimes you may encounter conflicts when merging one branch into another branch.
This can happen when you are merging code from an older GEOS-Chem version into
the latest version. A conflict is just Git saying, "I found some code in a place where I
didn't expect to find it. Can you help me figure out which lines of code to keep and which
to throw away?"
When you encounter a conflict, open the git gui window. You will see each file
containing a conflict listed in the Unstaged Changes window. Clicking on each file will
display the lines of code where the conflicts are located. You will see one or
more slugs in the file. A slug is a block of text that displays the source code from the old
branch and the new branch.
<<<<<<< HEAD
! This is old source code that already exists in the branch
...
=======
! This is new source code that is being merged into the branch
...
>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086
At the top of the slug you see the string <<<<<<< HEAD followed by some source code.
This is the "old" code, i.e. the code that existed as of the last commit. A separator
line ======= then follows the source code.
Underneath the separator line, you will see the "new" source code, i.e. the code that we
are merging into the branch. This source code is followed by the text >>>>>>>
77976da35a11db4580b80ae27e8d65caf5208086. The long numeric string is the
SHA1 ID (the internal ID # used by Git) corresponding to the commit that we are merging
into the branch. Each commit has a unique SHA1 ID.
To resolve a file containing conflicts, do the following:
1. Open the file in your favorite text editor (vi, emacs, etc.)
2. Search for the word HEAD. This will take you to the location of each slug (where
conflicts exist).
3. Decide which code that you want to keep.
4. Delete the code that you do not want to keep.
5. Delete the lines <<<<<<< HEAD, =======, and >>>>>>> 7797... If you keep
these in the source code you will get compilation errors.
6. Repeat this process for each conflict that you find.
Once you have resolved the conflicts in each file, you can commit them back into the
repository.
Tagging
Git allows you to tag a particular commit with an alphanumeric string for easy reference.
This tag will allow users to just refer to the tag name using git pull.
You can add a tag via the command line:
git tag GEOS-Chem TAG_NAME
That command will create a tag at the current commit.

You may also add a tag via the gitk viewer utility, as follows:
1. Open the gitk browser:

 Type gitk (to view the current branch), or
 Type gitk --all to view all branches.
2. In the top-left window select a commit by clicking on it with the mouse
3. Right-click on the text of the commit to pull up the context menu. Select
the Create tag option.
4. Type in the name of your tag and click Create
You can remove a tag via the command line:
git tag -d TAG_NAME
NOTE: Tagging is something that typically only the GEOS-Chem Support Team will do.
Deleting branches
Once you have merged your changes back into the master branch, you may delete the
branch you just created. In the git gui, go to the Branch/Delete menu item. You will be
given a dialog box where you can select the name of the branch you wish to delete.
Sharing your revisions with others (and vice versa)
One of the really nice features of Git is that it can create patch files, or files which
contain a list of changes that can be imported into someone else's local Git repository.
Using patch files totally obviates the need of having to merge differences between codes
manually.
Creating a patch file to share with others
To create a patch file containing the code differences between a branch of your code
with your master branch, or since type the following text:
git format-patch master..BRANCH_NAME --stdout > my-patch-file.diff
where BRANCH_NAME is the name of the branch that you want to compare against
the master branch.
You can also create a patch file for a given number of past commits. Typing:
git format-patch -3 --stdout > my-patch-file.diff
will create a patch file for the last 3 commits. If you want the most recent commit then
use -1 instead, etc.
These commands will pipe the output from the git format-patch command to a file
named by you (in this case my-patch-file.diff, but you may select whatever name
you wish). You can then include the patch file as an email attachment and send it to
other GEOS-Chem users, or the GEOS-Chem Support Team.
When sending patch files to others, it is important that you specify the parent
commit (i.e. the commit that immediately precedes where the patch was made) for
your patch file.
Checking the validity of a patch file
Other users can also send you their source code revisions as patch files. If you want to
check the status of a Git patch file (i.e. what it will actually do) before you apply it to your
repository, you can use the git apply command as follows:
% git apply --stat my-patch-file.diff
GeosCore/aerosol_mod.f | 7 ++++---
1 files changed, 4 insertions(+), 3 deletions(-)
The sample output listed above indicates that the patch contained 4 insertions and 3
deletions from only one file (aerosol_mod.f).
Note that the git apply --stat command does not apply the patch, but only shows
you the stats about what it'll do. For more detailed information about the patch, you can
open it in a text editor and examine it manually.
You can also find out if the patch will install in your Git repository, or if there will be
problems. You can also use the git apply command to do this:
git apply --check my-patch-file.diff
The most often error that is encountered is that the patch was made from an earlier
version of GEOS-Chem. In that instance the situation can usually be rectified by having
the sender of the patch do a git pull to the last-released GEOS-Chem version and
then to create the patch again.
Reading a patch file into your local repository
To ingest a patch file into your local Git repository you should first make a new branch.
Follow this procedure:
1. Pick Branch/Create from the menu (or type CTRL-N). Give your branch a
descriptive name like Updates_from_xxxx" that will serve as a mnemonic.
2. Pick Branch/Checkout from the menu (or type CTRL-O) and switch to the
branch you just created.
3. To ingest the other person's source code changes, type:
git am < their-patch-file.diff
You can then test the other person's revisions in the separate branch until you are sure
they are OK. Once satisfied with the changes, you can merge them back into
the master branch as described above.
--Bob Y. 13:36, 2 October 2013 (EDT)
Invalid email address error
If you get the the following error while trying to run the command git am < their-
patch-file.diff:
Patch does not have a valid e-mail address.
Then use this command instead:
git apply their-patch-file.diff
which should ingest the changes from the patch file into your repository. Why the
difference? Long story short:
 If their-patch-file.diff was created with the git format-patch command, then

it will contain the name of the committer plus the commit log message at the top of
the file. The git am command uses this information to create the commit message in
your repository.
 If on the other hand, their-patch-file.diff was created in gitk by right-clicking
on the Make patch menu entry, then it will lack the email address of the committer
and log message. This will confuse the git am command. Using git apply will ingest
the changes into your repository, but you will have to add the commit message
yourself in the git gui.
--Bob Y. 13:35, 2 October 2013 (EDT)
"Patch does not apply" error
If you get error output similar to this while trying to run the command git am < their-
patch-file.diff:
error: patch failed: file.c:137

error: file.c: patch does not apply
error: patch failed: Makefile:24
error: libavfilter/Makefile: patch does not apply
Patch failed at 0001 PATCH DESCRIPTION
When you have resolved this problem run "git am --resolved".
If you would prefer to skip this patch, instead run "git am --skip".
To restore the original branch and stop patching run "git am --abort
Then follow these instructions.

--Bob Y. 14:04, 21 May 2014 (EDT)
More about patch files
For more information about Git patch files, please see the following links:
How to create and apply a patch with Git
Another nice explanation of how to use Git to send patch files.
Getting updates from the remote repository

When a new GEOS-Chem version is released, we recommend that you download it
into a new local directory with the git clone command.
However, there may be times when "patches" (i.e. minor updates to fix bugs or other
issues) need to be applied to an existing GEOS-Chem version. The easiest way to
obtain patches is to use the git pull command, as follows:
1. Change to your local code directory.

2. Make a new branch named patch (or something similar).
3. Check out the patch branch. Now we are ready to obtain the updates from
the remote server.
4. Use the git pull command to download the updated files. Type:
git pull origin master
1. Try compiling GEOS-Chem and running for few time steps to make sure
everything is fine.
2. Check out the master branch.
3. Merge the patch branch into your master branch.
4. Delete the patch branch.
This will merge the changes from the master branch of the remote repository into
your master branch.
Advanced Git usage

The following subsections describe how to perform some advanced functions with
Git.
Reverting to an older state of the code
When you clone GEOS-Chem from the remote repository to your local disk space
(with the git clone command), the repository will point to the most recent commit.
However, you may want to revert to an older state of the code. Git allows you to do
this very easily.
Let's assume that the latest version of the code is v10-01, but that you want to use
version v8-03-01. The procedure is as follows:
1. Clone GEOS-Chem
2. Open the gitk browser by typing gitk & at the command line.
3. In the top-left window of gitk, find the commit that you want to revert to.
Usually this will be denoted with a yellow tag (e.g. v8-03-01 or v8-03-01-
benchmark). However, if there are any post-release patches, be sure you
select the oldest one.
4. Right click on the commit text to open a context menu. Select Create new
branch.
5. A new dialog box will pop up asking you to name the branch.
Type Code.v8-03-01 and press OK.
6. Close gitk and open the Git GUI by typing git gui &
7. From the Git GUI dropdown menu, select Branch / Checkout, and then
pick Code.v8-03-01.
That's it! We now have two branches that represent different GEOS-Chem versions.
1. The master branch represents the state of the code as of the latest release
2. The Code.v8-03-01 branch represents the state of the code as of the v8-03-
01 release.
You can work on the v8-03-01 branch as you wish. You can create further branches
off of the v8-03-01 branch. The nice thing about this method is that you can always
revert to the latest release by just switching back to the master branch (with Branch
/ Checkout from the Git GUI dropdown menu).
You can also use this same method to check out older versions of files in any of
the GEOS-Chem run directories.
Adding a patch that was made to a previous version
Let's say you are currently working on the latest version of GEOS-Chem, and
somebody gives you a patch that they added into their own GEOS-Chem v8-03-02
code. You can add the patch into your code in such a way that the modification will
be at the head of the revision history. Here is the procedure.
1. If you haven't done so already, clone the current GEOS-Chem repository

2. Start the Git GUI interface:
git gui &
3. Start the Gitk browser. From the dropdown menu in Git Gui, select:
Repository / Visualize All Branch History
4. In the Gitk revision, look for the parent commit of the patch in the revision history
(upper-left) window. The parent commit is the one immediately preceding the patch. If
you are not sure where the parent commit is, you can ask the person who sent you the
patch.
5. We will create a new branch from the parent commit into which the code updates will
be placed. Once you have found the parent commit, right click on the commit text to open
a context menu. Select:
Create new branch (name it patch-install-

point and hit OK)
6. We need to checkout (i.e. switch to) the new branch. Go back to the Git GUI. From the
dropdown menu, select:
Branch / Checkout (and then click on patch-

install-point)
7. Locate the patch file that contains the update you wish to add to the code. Let's
assume that this is called patch-file.diff. We will now apply this to your source code
directory:
git am < ~/my_patch_directory/patch-

file.diff
NOTE: patch-file.diff does not have to be in the source code directory. It can be
anywhere, as long as you specify the full file path. Here we assume it’s
in ~/my_patch_directory.)
8. In the Git GUI, press the F5 key to refresh the display.
9. In the GitK browser, press the F5 key to refresh the display.
10. Now we want to merge the master branch into the patch-install-point branch. This
will bring in all of the previous commits from the master branch into the patch-install-
point branch, while keeping the new commits from the patch at the top of the revision
history. Switch to the Git Gui window and pick from the menu:
Merge / Local Merge (and

then click on master)
11. The merge may result in some conflicts in some source code files. A conflict is a
difference in the source code which Git cannot rectify. Most often conflicts are caused by
2 comments having the same number. Git will add the following lines to the source code:
<<<<<HEAD
... lines of existing
code ...
=====
... lines of new code
...
>>>>>
If there are conflicts, you will have to go through these manually. You can just hand-edit
the source code files with your favorite text editor. If there are no conflicts, you can skip
ahead to Step 14.
12. Once you have finished resolving all conflicts, commit the modified files to the
repository. In the Git Gui, click on each of the files in the “Unstaged Changes” window
(this will tell Git to commit them to the repository). Then click on the “Sign off” button and
click on the “Commit” button.
13. At this point you will have 2 branches. The master branch represents the pristine,
unmodified code from the remote repository. The patch-install-point branch
represents master branch plus the code from the patch that we added.
14. Test the code in patch-install-point to make sure that it is functioning properly (i.e.
run a benchmark simulation or a short test run).
15. Once you are certain that the code in patch-install-point is good, then merge patch-
install point back into the master branch. From the Git GUI dropdown menu:
Branch / Checkout and then click on master

# Switches to the master branch
Merge / Local Merge and then click on patch-install-
point # Merges patch-install-point into master
Branch / Delete and then click on patch-install-

point # Deletes patch-install-point branch
Cherry-picking individual commits from another branch

Git allows you to cherry-pick commits, that is to pull a single commit from a
different branch into the branch you are currently working on. This can prove
useful in many situations. For example, a colleague may have committed a
critical bug fix into his or her development version of GEOS-Chem. You may
want to only grab that particular bug fix into your current branch without also
getting all the other changes that your colleague made.
The best way to cherry-pick commits is via the gitk browser. Here is a simple
example. Let's assume the following:
1. You're working in branch my_branch of your local GEOS-Chem code

directory.
2. You've pulled the branch containing your colleague's bug fix update into
a new branch of your local code directory called Bug-fix-branch.
3. You are only interested in merging the commit labeled "Remove obsolete
LAVHRRLAI and LMODISLAI from input.geos" into my_branch.
Open the gitk browser by typing this at the command line:
gitk
Version control with Git

Contents
[hide]
 1 Overview
o 1.1 Why use Git?
o 1.2 Advantages of using Git
 2 Tutorials about Git
o 2.1 For beginners
o 2.2 For more advanced users
 3 Using Git with GEOS-Chem and GAMAP
o 3.1 Obtaining and installing Git
o 3.2 First-time setup
o 3.3 Downloading GEOS-Chem and GAMAP
 4 References
Overview
Why use Git?
GEOS–Chem model development is done in a distributed manner. Individual users from several
different institutions will download a recent GEOS–Chem version and modify it according to their
own particular research interests. When these source code modifications are deemed to be
mature, users will then submit them to the GEOS–Chem Support Team for inclusion into
the mainline "standard" model.
In the past, the GEOS–Chem source code and run directories were distributed to the user
community as a series of TARBALL (i.e. *.tar.gz) files via anonymous FTP. The advantage of this
method was that one would only have to download a single file. However, as the number of
GEOS–Chem users (and submitted source code modifications) grew, this method became
unwieldy. For example, if only a single file needed to be updated, the entire TARBALL file would
have to be regenerated. This often became a source of confusion and error.
Given the large number of user code submissions, robust source code management techniques
must be employed in order to ensure the integrity of the GEOS–Chem code. Therefore,
the GEOS-Chem Support Team has selected the Git version control software for GEOS–Chem
source code management.
Advantages of using Git
Git offers many improvements over previous source code management software such
as CVS and Subversion.
1. Git avoids some of the limitations of CVS (which is by now 20-year-old software).
 Git is a distributed source code management system. Instead of having one central
GEOS–Chem repository residing on a single server, Git allows you to keep an
identical copy (a.k.a. "clone") of the GEOS–Chem source code repository on your
own system. Having several copies of the GEOS–Chem repository allows for
redundancy in case of catastrophic server failure or other such calamity.
 Modifications that you make to your own repository will not affect the repositories of
other users. (That is, unless you consciously decide to "push" your changes to
another repository).
 When you are ready to submit your source code modifications for inclusion into the
"standard" code, the GEOS–Chem Support Team can simply get them with a Git
"pull" operation.
 Git allows you to save out your source code changes to a "patch" file (a text file with
a list of source code differences). This can be emailed to other users and applied to
their local source code repository.
2. In general, Git is much simpler to use than CVS.

 With Git, you can "pull" changes from other users directly into your own local source
code repository.
 With Git, you can easily create several branches off of code development of the
"master" branch. (Branching was always problematic in CVS).
 Each branch can hold a new "feature", which may be tested independently of
the rest of the code.
 Branches can be merged back into the "master" branch when the new feature
has been validated.
 The Git repository browser, called GitK, allows you to see every single line of code
that has been modified, going all the way back to the start of the project.
 A graphic user interface, called the Git Gui, lets you control Git in a visual manner
rather than using command-line options.
3. With Git, GEOS–Chem developers are able to:

 download the most current GEOS–Chem source code online.
 download the most current GEOS–Chem run directories online.
 develop and test their source code additions to GEOS–Chem in their own local
repository.
 submit their mature source code updates back to the GEOS-Chem Support
Team for inclusion in the standard mainline code (via "Git pull" or patch files).
Tutorials about Git

Here are some useful resources for learning the various Git commands:
For beginners
Git user manual
The official Git user manual
Github Cheat Sheet (PDF)
Brief overview of commonly used Git commands
Visual Git Cheat Sheet
Interactive guide for visual learners
Git tutorial video
Excellent lecture given by Bart Trojanowski for the Ottawa Group of Ruby
Enthusiasts. HIGHLY RECOMMENDED!
For more advanced users
ProGit
Excellent online book that discusses many of Git's features, and how to use them like a
pro.
GitMagic
Descriptive online book that goes into the nitty-gritty of Git usage. A worthwhile read!
Using Git with GEOS-Chem and GAMAP

Obtaining and installing Git
If you don't already have Git on your system then you (or your
sysadmin) will have to install it. To check if it is already installed, you
can ask for the version at the Unix prompt. Type:
git --version
If you get a string similar to:
git version 2.17.0
then you are good to go. (The actual version # doesn't matter.) If not,
then you (or your sysadmin) may obtain the Git source code (or
binaries) the Git website.
First-time setup
Before using Git for the first time, you need to set up
your ~/.gitconfig file. Open a text editor and then cut & paste the
text from this sample .gitconfig file. Then save it as ~/.gitconfig.
Be sure to change your name and email accordingly, this is how Git will
know who you are!
Please see the following pages which describe how to download the
GEOS-Chem and GAMAP source code packages via Git.
Downloading GEOS-Chem and GAMAP
Please see the following wiki pages which contain detailed information
about how to use Git to download and modify the GEOS-Chem and
GAMAP source code packages:
 Using Git with GEOS-Chem

 Using Git with GAMAP
--Bob Y. 09:43, 16 March 2010 (EDT)
References
1. Git web page

2. Git Cheat Sheet
3. Google "Tech Talk" by Linus Torvalds, the creator of Git (Video
on Youtube)
4. Google "Tech talk" by Randal Schwartz (Video on Youtube)
5. Setting up your .gitconfig file (Link)

system wiki page.
6. GEOS-Chem Run Directories
6.1 Installation instructions

There is a unique run directory for every combination
of meteorological field, grid resolution, and simulation type. Run
directories are small enough to store in your personal disk space.
Each run directory contains the following:
 Various input configuration files that you can modify in order to

select different options for your GEOS-Chem simulation
 Files that define GEOS-Chem's photolysis mechanism
 Router Makefile that enables actions such as
o Compiling the GEOS-Chem source code stored
elsewhere on your system
o Copying the executable to the run directory
o Running GEOS-Chem
A collection of GEOS-Chem run directories are stored in the GEOS-

Chem Unit Test repository, which is stored on Github.org. You can
create fresh copies of any GEOS-Chem run directories by using
the gcCopyRunDirs perl script and
the CopyRunDirs.input configuration file within the Unit Test's
perl directory. For detailed instructions on creating run directories
for your GEOS-Chem simulations, please see the Creating GEOS-
Chem run directories wiki page. Quick links to relevant subsections
of this wiki page are provided below.
 Downloading the GEOS-Chem unit tester

 Editing the CopyRunDirs.input file
 Generating a GEOS-Chem run directory
 Run directories available from the Unit Tester
 Run directory tips and tricks
The 1-month benchmark output for recent GEOS-Chem versions

are posted online. You may download them via anonymous FTP
from:
ftp://ftp.as.harvard.edu/gcgrid/geos-
chem/1mo_benchmarks
6.2 GEOS-Chem input files contained in the run

directory
For a complete list of GEOS-Chem input files that ship with each
run directory, please see the GEOS Chem Input Files wiki page. Of
these, the most important is input.geos, where users the set start
and end times and toggle the various GEOS-Chem components on
or off.
6.3 Output files created by GEOS-Chem in the run

directory
For a complete list output files that GEOS-Chem will create in the
run directory, please see the GEOS-Chem Output Files wiki page.
GEOS-Chem Input Files

On this page we describe the input files that ship with the various GEOS-Chem run directories.
For a list of files created by GEOS-Chem, please see our GEOS-Chem Output Files wiki page.
NOTE: This page describes the input files that you need for GEOS-Chem v11-02. If you are still
using GEOS-Chem v11-01, please see our GEOS-Chem input files for v11-01 wiki page.
Contents
[hide]
 1 Overview
o 1.1 List of GEOS-Chem input files
o 1.2 Chemical mechanism files ship with the GEOS-Chem source code
 2 The input.geos file
o 2.1 Simulation Menu
o 2.2 Timestep menu
o 2.3 Advected Species Menu
o 2.4 Transport Menu
o 2.5 Convection Menu
o 2.6 Emissions Menu
o 2.7 Aerosol Menu
o 2.8 Deposition Menu
o 2.9 Chemistry Menu
o 2.10 Output Menu
o 2.11 GAMAP Menu
o 2.12 Diagnostic Menu
o 2.13 Planeflight Menu
o 2.14 ND48 Menu
o 2.15 ND49 Menu
o 2.16 ND50 Menu
o 2.17 ND51 and ND51b Menus
o 2.18 ND63 Menu
o 2.19 Prod and Loss Menu
o 2.20 Benchmark Menu
o 2.21 Nested Grid Menu
o 2.22 Passive Species Menu
o 2.23 CH4 simulation menu
o 2.24 CO2 Simulation Menu
o 2.25 POPs simulation menu
o 2.26 Mercury Simulation Menu
o 2.27 Radiation Menu
 3 The HEMCO_Config.rc file
o 3.1 Overview
o 3.2 Enabling and disabling emissions
 4 The HEMCO_Diagn.rc file
 5 The HISTORY.rc file
 6 The Planeflight.dat file
 7 Input files for the photolysis mechanism
Overview
This page describes the input files that are read by GEOS-Chem. These files will reside in the
various GEOS-Chem run directories. Each run directory is customized for a unique combination
of simulation, horizontal resolution, and met field type, and contains the various input files with
which you select options for your GEOS-Chem simulation.
You can generate GEOS-Chem run directories from the GEOS-Chem Unit Tester. Please see
our our Creating GEOS-Chem run directories wiki page for detailed instructions. We recommend
that you create a different run directory for each of your GEOS-Chem simulations to avoid
overwriting output with subsequent model runs.
Note that run directories compatible with previous versions of GEOS-Chem will not work with
[[GEOS-Chem v11-01]|v11-01]].
List of GEOS-Chem input files
Below is a table listing GEOS-Chem input files that reside in the run directory.
GEOS-Chem user input files

input.geos File containing all GEOS-Chem user options. In this file, you may
specify the following options:
 Start & end time of the simulation

 Names of the input and output files
 Which diagnostics to save to disk
 Which processes (e.g. chemistry, transport, dry deposition, etc.)
to turn on, etc.
HEMCO_Config.rc Specifies emission inventories that you want to include in GEOS-
Chem via the HEMCO emissions component.
HEMCO_Diagn.rc Specifies diagnostic archival options for emissions and related
quantities computed by HEMCO emissions component.
 For more information, please see The Diagnostics section

of The HEMCO User's Guide.
HISTORY.rc Specifies which GEOS-Chem diagnostics will be archived to
netCDF output (for both GEOS-Chem "Classic" and GCHP modes)
 For more information, please our List of diagnostics archived to

netCDF format wiki page.
Planeflight.dat Specifies flight tracks for which you want to save out specific
tracers, chemical species, or met field quantities.
GEOS-Chem photolysis mechanism files
These are only found in the run directories for the various full-chemistry and
aerosol-only simulations.
FJX_spec.dat Contains cross-section and quantum yields for FAST-JX
photolysis species.
FJX_j2j.dat Links "GEOS-Chem species" to "FAST-JX" species. FAST-JX
photolysis species are defined in the data file FJX_spec.dat,
GEOS-Chem species in globchem.spc. See this post for more
information.
jv_spec_mie.dat Contains aerosol optical properties at 5 wavelengths.
dust.dat Contains aerosol optical properties for dust at multiple wavelengths
for use in Fast-JX and the RRTMG radiatiaive transfer model (if
enabled).
org.dat Contains aerosol optical properties for organic carbon at multiple
wavelengths for use in Fast-JX and the RRTMG radiatiaive
transfer model (if enabled).
so4.dat Contains aerosol optical properties for sulfate at multiple
soot.dat Contains aerosol optical properties for black carbon at multiple
ssa.dat Contains aerosol optical properties for accumulation mode sea salt
aerosol at multiple wavelengths for use in Fast-JX and the RRTMG
radiatiaive transfer model (if enabled).
ssc.dat Contains aerosol optical properties for coarse mode sea salt aerosol
at multiple wavelengths for use in Fast-JX and the RRTMG
radiatiaive transfer model (if enabled).
Chemical mechanism files ship with the GEOS-Chem source code
For your reference, we store the master KPP equation files for GEOS-Chem v11-
02 (globchem.def, globchem.eqn, and globchem.spc) in the various subfolders of the
GEOS-Chem source code directory, i.e.
 KPP/Standard
 KPP/Tropchem
 KPP/SOA_SVPOA
If you need to add new species or reactions, you can modify these globchem.* files and then
rebuild the KPP code. It is recommended that you place any custom modifications to the GEOS-
Chem chemistry mechanisms into this folder:
 KPP/Custom
You can ask the GEOS-Chem Support Team for assistance with this.
In the very near future, we hope to build KPP fresh each time when GEOS-Chem is compiled.
This will make it much easier to change the existing chemical mechanisms.
The input.geos file

GEOS-Chem combines all the input options and switches into a single input file, input.geos. All
user-defined input switches and settings which customize GEOS-Chem output options are now
defined within this file.
An input.geos file ships with each GEOS-Chem run directory. We invite you to create the run
directory for the simulation(s) that you are interested in and view the
corresponding input.geos file. You will note that the input.geos file is grouped into menus.
Each menu controls the options for a particular aspect of a GEOS-Chem simulation. The
sections below contain a list of the menus and the options that they control.
Most of the information listed in input.geos will be stored as fields of the Input_Opt derived-
type object.
Simulation Menu
Line numbers are not part of the input.geos file, but have been included for reference.
01: %%% SIMULATION MENU %%% :

02: Start YYYYMMDD, hhmmss : 20130701 000000
03: End YYYYMMDD, hhmmss : 20130801 000000
04: Run directory : ./
05: Input restart file : GEOSChem_restart.YYYYMMDDhhmm.nc
06: Root data directory : /path/to/data/
07: => GEOS-FP subdir : GEOS_FP/YYYY/MM/
08: => MERRA2 subdir : MERRA2/YYYY/MM/
09: Global offsets I0, J0 : 0 0
Note: /path/to/data/ indicates the path to the root data folder on your system. If you don't
know where this is, ask your IT staff.
Line What gets defined Description

1 nothing Header line
2 Input_Opt%NYMDb The starting date and time of the GEOS-Chem
Input_Opt%NHMSb
simulation. The date must be in YYYYMMDD format (4-
digit year, month, and day). The time must be
in hhmmss format (hour, minute, and seconds).
 Note that since the GEOS-Chem dynamic

timestep (see Transport Menu) is usually 10, 15,
or 30 minutes, you can always set the seconds to
zero.
3 Input_Opt%NYMDe Specify the ending date (YYYYMMDD format) and time
Input_Opt%NHMSe
(hhmmss format) of the GEOS-Chem simulation.
4 Input_Opt%RUN_DIR The name of the GEOS-Chem run directory (e.g.
where the executable file and input files reside).
 NOTE: This can usually be set to the current

directory (i.e. ./).
5 Input_Opt%IN_RST_FILE The name of GEOS-Chem input restart file, which
contains the instantaneous concentrations of the
advected species specified in the Advected Species
Menu. This file is used to initialize the species
concentrations at the start of your simulation.
You can change the name of the restart file to match
the file that you have. If you just specify the file
name, GEOS-Chem will look for the restart file in the
run directory. You may also specify an entire
directory path. Also, you may include the following
tokens in the file name:
 YYYY: Replaced by 4-digit year (e.g. 2013)

 MM: Replaced by 2-digit month (01-12)
 DD: Replaced by 2-digit day (01-31)
 hh: Replaced by 2-digit hour (0-23)
 mm: Replaced by 2-digit minutes (0-59)
 ss: Replaced by 2-digit seconds (0-59)
NOTE: Using YYYYMMDDhhmm in the restart file names

allow for test simulations of less than one hour to be
performed.
6 Input_Opt%DATA_DIR The the root-level data directory path. The various
shared data inputs (e.g. emissions, offline OH, offline
dust & aerosol concentrations, etc). are stored in
subdirectories of Input_Opt%DATA_DIR. The met fields
are also stored in subdirectories
of Input_Opt%DATA_DIR.
For more information, please see our Setting up the
ExtData directory wiki page.
7 Input_Opt%GEOS_FP_DIR The directory path where GEOS-FP met fields are

stored. You may include the YYYY and MM tokens as
described above.
8 Input_Opt%MERRA2_DIR The directory path where MERRA-2 met fields are
stored. You may include the YYYY and MM tokens as
described above.
9 Input_Opt%NESTED_I0 Nested grid offsets. For a global run, I0 and J0 must
Input_Opt%NESTED_J0
both be set to zero. However, for nested grid runs, we
must set I0 and J0 to the appropriate offsets.
See our Setting up GEOS-Chem nested grid
simulations wiki page for more information.
Timestep menu
NOTE: In GEOS-Chem v11-02, we have changed the units of all timesteps from minutes to
seconds. We made this change in order to be able to interface GEOS-Chem with the NASA
the GEOS-DAS Earth System Model more efficiently.
01: %%% TIMESTEP MENU %%% :

02: Tran/conv timestep [sec]: 600
03: Chem/emis timestep [sec]: 1200

2 Input_Opt%TS_DYN The dynamic (aka "Heartbeat") timestep in seconds.
Input_Opt%TS_CONV
This is the timestep at which transport, PBL
mixing, cloud convection, and wet deposition occur.
Recommended values:
 300 sec (=5 min) for:

 0.25° x 0.3125° GEOS-FP nested-grid
simulations
 0.5° x 0.625° MERRA-2 nested-grid simulations
 600 sec (=10 min) for:
 2° x 2.5° global simulations: 600 sec (=10 min)
 4° x 5° global simulations: 600 sec (=10 min)
3 Input_Opt%TS_CHEM The chemistry timestep in seconds. This is the timestep

Input_Opt%TS_EMIS
at which dry deposition, emissions, and chemistry
occur.
Recommended values:
 600 sec (=10 min) for:

 0.25° x 0.3125° GEOS-FP nested-grid
simulations
 0.5° x 0.625° MERRA-2 nested-grid simulations
 1200 sec (=20 min) for:
 2° x 2.5° global simulations: 600 sec (=10 min)
 4° x 5° global simulations: 600 sec (=10 min)
CAVEAT: Running GEOS-Chem with the recommended timesteps from Philip et

al. (2016)] has been shown to increase run times by approximately a factor of 2. For
tips on improving run time, please see our Speeding up GEOS-Chem wiki page.
Advected Species Menu
01: %%% ADVECTED SPECIES MENU %%%:

02: Type of simulation : 3
03: Species Entries ------->: Name
04: Species #1 : NO
05: Species #2 : O3
06: Species #3 : PAN
07: Species #4 : CO
... etc not shown here ...

2 Input_Opt%SIM_TYPE The type of GEOS-Chem simulation that you wish
to perform. The choices are:
1. Rn-Pb-Be simulation
2. UNUSED
3. One of the NOx-Ox-Hydrocarbon-aerosol
(aka "full chemistry") simulations
4. UNUSED
5. UNUSED
6. Tagged O3 simulation
7. Tagged CO simulation
8. C2H6 simulation
9. CH4 simulation
10. Aerosol-only simulation
11. Mercury simulation
12. CO2 simulation
13. UNUSED
14. POPs simulation
NOTE: In this example, the ADVECTED
SPECIES MENU is set up for a "Standard" full
chemistry simulation. This is the simulation we
use to generate the GEOS-Chem benchmark
output.

4- Input_Opt%AdvectSpc_Name A list of the advected species names. Place only
one species name on each line. These entries are
used to populate the species database.
Transport Menu
01: %%% TRANSPORT MENU %%% :

02: Turn on Transport : T
03: => Fill Negative Values: T
04: => IORD, JORD, KORD : 3 3 7

2 Input_Opt%LTRAN Set this to T to turn on TPCORE transport, or set to F
to turn off TPCORE transport.
3 Input_Opt%LFILL Set this to T to cause TPCORE to fill negative values
with zeroes.
4 Input_Opt%TPCORE_IORD These settings determine how TPCORE performs
Input_Opt%TPCORE_JORD
Input_Opt%TPCORE_KORD transport in the E/W, N/S, and vertical directions.
 Recommended values are 3, 3, 7.

Convection Menu
01: %%% CONVECTION MENU %%% :

02: Turn on Cloud Conv? : T
03: Turn on PBL Mixing? : T
04: => Use non-local PBL? : T
Line What gets Description

defined
2 Input_Opt%LCONV Set this to T to turn on cloud convection.
3 Input_Opt%LTURB Set this to T to turn on PBL mixing.
4 Input_Opt%LNLPBL The options are as follows:
 To use the non-local PBL mixing scheme (aka VDIFF),

then set this to T.
 To use the full mixing in the PBL (aka TURBDAY),
then set this to F.
NOTE: If Input_Opt%LTURB (Line 3) is set to F, then neither
PBL mixing option will be executed, regardless of the
setting of Input_Opt%LNLPBL.
CAVEAT: In this version, it has been noted that VDIFF
(the non-local mixing option) does not strictly conserve
mass. This will be more of a problem for long-lived
species like CH4 and CO2. Therefore, if you are using
the CH4 or CO2 specialty simulations, we recommend to
use the full TURBDAY mixing by setting
this Input_Opt%LNLPBL switch to F.
For more information please see these wiki posts below.
 Mass is not conserved when using non-local PBL

mixing (on our Boundary layer mixing page)
 Mass conservation (on our Flexible precision in GEOS-
Chem page
Emissions Menu
01: %%% EMISSIONS MENU %%% :

02: Turn on emissions? : T
03: HEMCO Input file : HEMCO_Config.rc
04: => 1ppt MBL BRO Sim.? : F
05: Switches for UCX :---
06: => Use CH4 emissions? : F
07: => Turn on surface BCs :---
08: => CH4? : T
19: => OCS? : T
10: => CFCs? : T
11: => Cl species? : T
12: => Br species? : F
13: => N2O? : T
14: => Set initial glob MRs:---
15: => strat. H2O? : T
16: => CFC emission year : 0

1 nothing Header Line
2 Input_Opt%LEMIS Set this to T to turn on emissions or F to turn off
emissions.
3 Input_Opt%HcoConfigFile The name of the HEMCO configuration file. The
emission inventories that your simulation will use
are set in this file.
4 Input_Opt%LFIX_PBL_BrO Set this to T to set Bro concentrations in the PBL
equal to 1 ppt during the day.
The following lines contain settings specific to the UCX chemistry mechanism.
You can turn all of these options off if your simulation does not use the UCX
mechanism (e.g "tropchem", "complexSOA").
5 nothing Header line.
6 Input_Opt%LCH4EMIS Set this T to use online methane emissions.
8 Input_Opt%LCH4SBC Set this T to fix surface mixing ratio of methane.
9 Input_Opt%LOCSEMIS Set this to T to fix surface mixing ratios of OCS.
10 Input_Opt%LCFCEMIS Set this to T to fix surface mixing ratios of CFCs,
HCFCs, and halons to match WMO projections
under the Montreal Protocol.
11 Input_Opt%LCLEMIS Set this to T to fix surface mixing ratios of other
chlorinated carbon and inorganic chlorine species
to match WMO projections under the Montreal
Protocol.
12 Input_Opt%LBREMIS Set this to T to fix surface mixing ratios of bromine
species. Not recommended if other bromine
emissions are enabled.
13 Input_Opt%LN2OEMIS Set this to T to fix surface mixing ratios of N2O.
15 Input_Opt%LSETH2O Set this to T to initialize stratospheric H2O mixing
ratios based on meteorology data for the first
timestep, overriding any restart file values.
16 Input_Opt%CFCYEAR Specify the starting year for CFC emissions.
Aerosol Menu
01: %%% AEROSOL MENU %%% :

02: Online SULFATE AEROSOLS : T
03: => Metal cat. SO2 ox.? : T
04: Online CARBON AEROSOLS : T
05: => Use Brown Carbon? : F
06: Online COMPLEX SOA : T
07: => Semivolatile POA? : F
08: Spatial & seasonal OM/OC: F
09: Online DUST AEROSOLS : T
10: => Acidic uptake ? : F
11: Online SEASALT AEROSOLS : T
12: => SALA radius bin [um]: 0.01 0.5
13: => SALC radius bin [um]: 0.5 8.0
14: => MARINE ORG AEROSOLS : F
15: Settle strat. aerosols : T
16: Online PSC AEROSOLS : T
17: Allow homogeneous NAT? : F
18: NAT supercooling req.(K): 3.0
19: Ice supersaturation req.: 1.2
20: Perform PSC het. chem.? : T
21: Calc. strat. aero. OD? : T
22: Enhance BC Absorption? : T
23: => hydrophilic BC : 1.5
24: => hydrophobic BC : 1.0

2 Input_Opt%LSULF Set this to T to turn on chemistry for sulfate
aerosols (DMS, SO2, SO4, MSA, NH3, NH4,
NIT).
3 Input_Opt%LMETALCATSO2 Set this to T to turn on metal-catalyzed oxidation
of SO2. This option is turned on by default.
4 Input_Opt%LCARB Set this to T to turn on chemistry for
carbonaceous aerosols (BCPI, BCPO, OCPI,
OCPO).
5 Input_Opt%LBRC Set this to T to turn on brown carbon aerosols.
6 Input_Opt%LSOA Set this to T to turn on the complex SOA
chemistry option. (Default is to use the simple
SOA option).
7 Input_Opt%LSVPOA Set this to T to use the semivolatile POA option.
8 Input_Opt%LOMOC Set this to T to make the ratios of Organic Matter
to Organic Carbon (OM:OC) for SOA species
vary by lon/lat location and season. The default
is to set these to a single global parameter.
9 Input_Opt%LDUST Set this to T to turn on removal for mineral dust
aerosol species (DST1, DST2, DST3, DST4)
10 Input_Opt%LDSTUP Set this to T to turn on acid uptake on dust
aerosols.
11 Input_Opt%LSSALT Set this to T to turn on chemistry for sea salt
aerosols (SALA, SALC).
12 Input_Opt%SALA_REDGE_um The bin edges (in microns) that denote
accumulation mode sea salt species.
 Recommended setting: 0.01 to 0.5 microns.

13 Input_Opt%SALC_REDGE_um The bin edges (in microns) that denote coarse
mode sea salt tracer in microns.
 Recommended setting: 0.5 to 8 microns.

14 Input_Opt%LMPOA Set this to T top turn on marine organic aerosols.
22 Input_Opt%LBCAE Set this to T to enhance black carbon (BC)
absorption due to coating.
23 Input_Opt%LBCAE_1 Specify the enhancement for hydrophilic BC.
24 Input_Opt%LBCAE_2 Specify the enhancement for hydrophobic BC.
The following lines contain settings specific to the UCX chemistry mechanism.
You can turn all of these options off if your simulation does not use the UCX
mechanism (e.g "tropchem", "complexSOA").
15 Input_Opt%LGRAVSTRAT Set this to T to apply gravitational settling to
stratospheric solid particulate aerosols (SPA,
trapezoidal scheme) and stratospheric liquid
aerosols (SLA, corrected Stokes' Law).
16 Input_Opt%LSOLIDPSC Set this to T to use solid polar stratospheric
clouds (PSCs).
17 Input_Opt%LHOMNUCNAT Set this to T to allow NAT to form
homogeneously from freezing of HNO3.
18 Input_Opt%T_NAT_SUPERCOOL The degrees Kelvin of cooling required for
homogeneous NAT nucleation.
19 Input_Opt%P_ICE_SUPERSAT The supersaturation factor required for ice
nucleation.
 Recommended values: 1.2 for coarse grids;

1.5 for fine grids.
20 Input_Opt%LPSCCHEM Set this to T to allow heterogeneous chemistry on
stratospheric aerosols.
21 Input_Opt%LSTRATOD Set this to T to include online stratospheric
aerosols in extinction calculations for photolysis.
Deposition Menu
01: %%% DEPOSITION MENU %%% :

02: Turn on Dry Deposition? : T
03: Turn on Wet Deposition? : T

defined
2 Input_Opt%LDRYD Set this to T to turn on dry deposition, or F to turn off dry
deposition.
3 Input_Opt%LWETD Set this to T to turn on wet deposition, or F to turn off wet
deposition.
Chemistry Menu
01: %%% CHEMISTRY MENU %%% :

02: Turn on Chemistry? : T
03: Use linear. strat. chem?: T
04: => Use Linoz for O3? : T
05: Use UCX strat. chem? : T
06: Online CH4 chemistry? : T
07: Active strat. H2O? : T
08: Overhead O3 for FAST-JX :---
09: => Online O3 from model: T
10: => O3 from met fields : T
11: => TOMS/SBUV O3 : F
12: Gamma HO2 : 0.2

2 Input_Opt%LCHEM Set this to T to turn on chemistry, or F to turn off
chemistry.
3 Input_Opt%LSCHEM Set this to T to turn on linearized stratospheric
chemistry, or F to turn off stratospheric
chemistry.
 NOTE: If the UCX chemistry mechanism is
used (see line 5), then linearized chemistry is
applied in the mesosphere.
4 Input_Opt%LLINOZ Set this to T to use Linoz stratospheric ozone
chemistry, otherwise Synoz will be used.
 NOTE: If the UCX chemistry mechanism is

used (see line 5), then Linoz is applied in the
mesosphere.
5 Input_Opt%LUCX Set this to T to use the UCX chemistry
mechanism. Otherwise online chemistry will
only be applied in the troposphere.
6 Input_Opt%LCH4CHEM Set this to T to use online methane chemistry.
7 Input_Opt%LACTIVEH2O Set this to T to allow the stratospheric H2O
tracer to influence specific humidity and relative
humidity.
 NOTE: To use this option, you must also turn

on UCX (see line 5).
8 nothing Separator line
9 Input_Opt%USE_ONLINE_O3 Set this to T to use online O3 from GEOS-Chem
in the extinction calculations for FAST-JX
photolysis.
 NOTE: This is the recommended option.

10 Input_Opt%USE_O3_FROM_MET Set this to T to use ozone columns from the met
fields (e.g. TO3).
11 Input_Opt%USE_TOMS_O3 Set this to T to use online O3 from the
TOMS/SBUV archive.
 NOTE: We recommend that you set this to F

for simulations with GEOS-FP and MERRA-
2 meteorology
12 Input_Opt%GAMMA_HO2 The recommended setting is 0.2.
Output Menu
01: %%% OUTPUT MENU %%% : 123456789.123456789.123456789.1--

1=ZERO+2=BPCH
02: Schedule output for JAN : 3000000000000000000000000000000
03: Schedule output for FEB : 30000000000000000000000000000
04: Schedule output for MAR : 3000000000000000000000000000000
05: Schedule output for APR : 300000000000000000000000000000
06: Schedule output for MAY : 3000000000000000000000000000000
07: Schedule output for JUN : 300000000000000000000000000000
08: Schedule output for JUL : 3000000000000000000000000000000
09: Schedule output for AUG : 3000000000000000000000000000000
10: Schedule output for SEP : 300000000000000000000000000000
11: Schedule output for OCT : 3000000000000000000000000000000
12: Schedule output for NOV : 300000000000000000000000000000
13: Schedule output for DEC : 3000000000000000000000000000000

defined
2 Input_Opt%NJDAY Schedule diagnostic output for JANUARY. Place a 3 in the
column corresponding to the day of the month (1-31) on
which you want diagnostic output saved to the binary punch
file.
In the example above, the columns which indicate January
1st and February 1st both have a 3 listed there. This will
cause GEOS-Chem to archive diagnostic data for the entire
month of January and then save it to disk at 0 GMT on
February 1st. (GEOS-Chem is smart enough not to write
anything to disk at 0 GMT on January 1st, since this is the
starting time of the simulation.) If you would like to save
daily diagnostic output to the binary punch file, put a 3 for
each day of each month.
 NOTE: You must place a 3 in the location

corresponding to the simulation end date. Otherwise, the
GEOS-Chem simulation will crash immediately with the
error No output scheduled on last day of run!
3 Schedule diagnostic output for FEBRUARY
4 Schedule diagnostic output for MARCH
5 Schedule diagnostic output for APRIL
6 Schedule diagnostic output for MAY
7 Schedule diagnostic output for JUNE
8 Schedule diagnostic output for JULY
9 Schedule diagnostic output for AUGUST
10 Schedule diagnostic output for SEPTEMBER
11 Schedule diagnostic output for OCTOBER
12 Schedule diagnostic output for NOVEMBER
13 Schedule diagnostic output for DECEMBER
GAMAP Menu
01: %%% GAMAP MENU %%% :

02: diaginfo.dat path : diaginfo.dat
03: tracerinfo.dat path : tracerinfo.dat

2 Input_Opt%GAMAP_DIAGINFO Path name of the diaginfo.dat file
for GAMAP. GEOS-Chem will create this file,
which will be customized to the particular
simulation that is being done. This may be
either a relative path name or an absolute path
name.
3 Input_Opt%GAMAP_TRACERINFO Path name of the tracerinfo.dat file for
GAMAP. GEOS-Chem will create this file,
which will be customized to the particular
simulation that is being done. This may be
either a relative path name or an absolute path
name.
Diagnostic Menu
NOTE: The binary punch file format will be preserved in GEOS-Chem v11-02, but will
probably be removed from the version following that (i.e. GEOS-Chem v11-03).
ALSO NOTE: In GEOS-Chem v11-02, you can also save diagnostic output to netCDF
format. To activate this option, you need to compile with NC_DIAG=yMakefile option.
Please see our List of diagnostics archived to netCDF format wiki page for more
information.
This menu lets you specify which GEOS_Chem diagnostic quantities will be archived to disk as
binary punch (aka bpch) format. For a complete list of diagnostic settings, please see our List of
diagnostics archived to bpch format wiki page.
%%% DIAGNOSTIC MENU %%% :

Binary punch file name : trac_avg.geosfp_4x5_standard.YYYYMMDDhhmm
Diagnostic Entries ---> : L Tracers to print out for each diagnostic
ND01: Rn/Pb/Be source : 0 all
ND02: Rn/Pb/Be decay : 0 all
ND03: Hg emissions, P/L : 0 all
ND04: CO2 Sources : 0 all
ND05: Sulfate prod/loss : 72 all
ND06: Dust aer source : 1 all
ND07: Carbon aer source : 72 all
ND08: Seasalt aer source: 1 all
ND09: - : 0 all
ND10: - : 0 all
ND11: Acetone sources : 1 all
ND12: BL fraction : 0 all
ND13: Sulfur sources : 72 all
ND14: Cld conv mass flx : 0 all
ND15: BL mix mass flx : 0 all
ND16: LS/Conv prec frac : 0 all
ND17: Rainout fraction : 0 all
ND18: Washout fraction : 0 all
ND19: CH4 loss : 0 all
ND21: Optical depths : 72 all
ND22: J-Values : 72 1 2 7 8 9 11 13 14 20 44 46 47 49 50 51 59
60 66 67 69 74 75 83 84 -1
=> JV time range : 11 13
ND24: E/W transpt flx : 0 all
ND25: N/S transpt flx : 0 all
ND26: U/D transpt flx : 0 all
ND27: Strat NOx,Ox,HNO3 : 0 1 2 7
ND28: Biomass emissions : 1 1 4 5 9 10 11 18 19 20 21 26 30 34 35 71
ND29: CO sources : 1 all
ND30: Land Map : 0 all
ND31: Pressure edges : 73 all
ND32: NOx sources : 1 all
ND33: Column tracer : 0 all
ND34: Biofuel emissions : 1 1 4 5 9 10 11 18 19 20 21
ND35: Tracers at 500 mb : 0 all
ND36: Anthro emissions : 1 1 2 4 5 7 9 10 11 18 19 20 21 71
ND37: Updraft scav frac : 0 all
ND38: Cld Conv scav loss: 72 all
ND39: Wetdep scav loss : 72 all
ND41: Afternoon PBL ht : 0 all
ND42: SOA concentrations: 72 all
ND43: Chem prod OH, HO2 : 72 all
==> OH/HO2 time range : 0 24
ND44: Drydep flx/vel : 1 2 3 7 8 9 11 13 14 15 16 17 20 22 26 27 28
29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 47 48 50 55 56 58 59 60 61
62 63 64 65 66 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
114 115 119 120 121 122 123 124 125
ND45: Tracer Conc's : 72 all
==> ND45 Time range : 0 24
ND46: Biogenic emissions: 1 all
ND47: 24-h avg trc conc : 0 all
ND52: GAMMA HO2 : 0 all
ND53: POPs Emissions : 0 all
ND54: Time in t'sphere : 72 all
ND55: Tropopause height : 72 all
ND56: Lightning flashes : 0 all
ND57: Potential T : 0 all
ND58: CH4 Emissions : 0 all
ND59: TOMAS aerosol emis: 0 all
ND60: Wetland Frac : 0 all
ND61: TOMAS 3D rate : 0 all
ND62: Inst column maps : 0 all
ND64: Radiative flux : 0 all
ND66: DAO 3-D fields : 72 all
ND67: DAO 2-D fields : 72 all
ND68: Airmass/Boxheight : 72 all
ND69: Surface area : 1 all
ND70: Debug output : 0 all
ND71: Hourly max ppbv : 0 2
ND72: Radiative output : 0 all

Planeflight Menu
01: %%% PLANEFLIGHT MENU %%%:

02: Turn on plane flt diag? : F
03: Flight track info file : Planeflight.dat.YYYYMMDD
04: Output file name : plane.log.YYYYMMDD

2 Input_Opt%DO_PF Set this to T to turn on the planeflight diagnostic (aka
ND40).
3 Input_Opt%PF_IFILE Specify the name of the input file (usually
called Planeflight.dat.YYYYMMDD) for the plane flight
diagnostic. This file is described below. You may use
date & time tokens YYYY, MM, DD, hh, mm, ss and
GEOS-Chem will replace these with the appropriate
values.
If the plane flight diagnostic is turned on, then GEOS-
Chem will look for a
new Planeflight.dat.YYYYMMDD file for each
YYYYMMDD date. Then it will save out various
quantities along the flight track(s) defined within
the Planeflight.dat.YYYYMMDD file.
4 Input_Opt%PF_OFILE Specify the name of the output file (usually

called plane.log.YYYYMMDD) for the plane flight
diagnostic. You may use date & time tokens YYYY, MM,
DD, hh, mm, ss and GEOS-Chem will replace these with
the appropriate values.
ND48 Menu
NOTE: This diagnostic is still available in GEOS-Chem v11-02. It will likely be replaced by
equivalent functionality in a future version.
01: %%% ND48 MENU %%% :

02: Turn on ND48 stations : F
03: Station Timeseries file : stations.YYYYMMDD
04: Frequency [sec] : 3600
05: Number of stations : 1
06: Station #1 (I,J,Lmax,N) : 133 29 15 2

2 Input_Opt%DO_ND48 Set this to T to turn on the ND48 station timeseries
diagnostic. This allows you to save timeseries data of
various quantities at specific grid boxes.
3 Input_Opt%ND48_FILE The name of the file which will contain output from
the ND48 station timeseries diagnostic. This file will
be in binary punch format and can be read by
GAMAP. You may use date & time tokens YYYY,
MM, DD, hh, mm, ss and GEOS-Chem will replace
these with the appropriate values.
4 Input_Opt%ND48_FREQ The frequency in seconds at which data will be
archived by the ND48 station timeseries diagnostic.
Recommended values: 3600 sec (= 1 hour) or 7200 sec
(=2 hours).
5 Input_Opt%ND48_N_STA The number of ND48 stations at which timeseries data
will be saved to disk.
6 Input_Opt%ND48_IARR For each ND48 station, you must provide the
Input_Opt%ND48_JARR
Input_Opt%ND48_LARR following information (separated by spaces):
Input_Opt%ND48_NARR
 Longitude index
 Latitude index
 Number of levels to save
 If you type 1, it will just save the surface level.
 If you type 10, then it will save all levels from
level 1 (surface) to level 10.
 ND48 diagnostic quantity number(s)
ND49 Menu
01: %%% ND49 MENU %%% :

02: Turn on ND49 diagnostic : F
03: Inst 3-D timeser. file : tsYYYYMMDD.bpch
04: Tracers to include : 94
06: IMIN, IMAX of region : 70 30
07: JMIN, JMAX of region : 23 46
08: LMIN, LMAX of region : 1 1

2 Input_Opt%DO_ND49 Set this to T to turn on the ND49 instantaneous 3D
timeseries diagnostic. This allows you to archive
instantaneous timeseries data for various quantities
from a 3D region of the globe.
4 Input_Opt%ND49_TRACERS The ND49 diagnostic quantities that you wish to
save to disk. Separate each number with a space.
5 Input_Opt%ND49_FREQ The frequency (in minutes) at which ND49 will save
data for a 3D region of the globe data to disk.
Recommended value: 7200 min (= 2 hours) or
10800 min (= 3 hours). You may save data at a
higher temporal resolution (e.g. every hour) but this
will create HUGE data files!
6 Input_Opt%ND49_IMIN The indices which determine the longitude extent of
Input_Opt%ND49_IMAX
the 3D region of the globe. Note that these are
indices and not actual longitude values. To specify
all 360 degrees of longitude, type the following:
 For GMAO 4° x 5° grid: 1 72

 For GMAO 2° x 2.5° grid: 1 144
Also, note you can wrap around the date line. In the
example shown above, IMIN=70 and IMAX=30.
This will create a 3D region (assuming 4x5 grid)
which starts at 165° E longitude and extends across
the date line to 35° W longitude.
7 Input_Opt%ND49_JMIN The indices which determine the latitude extent of

Input_Opt%ND49_JMAX
indices and not actual latitude values. To specify all
180 degrees of latitude, type the following:

 For GMAO 2° x 2.5° grid: 1 91
8 Input_Opt%ND51_LMIN The indices which determine the vertical extent of
Input_Opt%ND51_LMAX
the 3D region of the globe.
ND50 Menu
01: %%% ND50 MENU %%% :

03: 24-hr avg timeser. file : ts_24h_avg.YYYYMMDD.bpch
04: Output as HDF5? : F
05: Tracers to include : 82 83 84 85 86 87

2 Input_Opt%DO_ND50 Set this to T to turn on the ND50 24-hr average 3D
timeseries diagnostic. This allows you to archive 24-
hour time-averaged timeseries data for various
quantities from a 3D region of the globe.
4 nothing OBSOLETE
5 Input_Opt%ND50_TRACERS The ND50 diagnostic quantities that you wish to
Input_Opt%ND50_IMAX

 For GMAO 2° x 2.5° grid: 1 144
Also, note you can wrap around the date line.
Input_Opt%ND50_JMAX

 For GMAO 2° x 2.5° grid: 1 91
Input_Opt%ND50_LMAX
the 3D region of the globe.
ND51 and ND51b Menus
01: %%% ND51 MENU %%% :

03: LT avg timeseries file : ts_satellite.YYYYMMDD.bpch
05: Tracers to include : 82 83 84 85 86 87
06: GMT Hour for disk write : 0
07: Avg Period [LT hours] : 10 12
01: %%% ND51b MENU %%% :

02: Turn on ND51b diagnstic : F
03: LT avg timeseries file : ts_13_15.NA.YYYYMMDD.h5
05: Tracers to include : 1 4 20 25 26 27 28 29 30 31 32 33 34 35 36 37
38 39 40 41 42 43 44
06: GMT Hour for disk write : 1
07: Avg Period [LT hours] : 13 15

2 Input_Opt%DO_ND51 Set this to T to turn on the ND51 and/or ND51b
Input_Opt%DO_ND51b "satellite" 3D timeseries diagnostic. ND51 and/or
ND51b allows you to archive 3D data blocks for
various quantities which have been time-averaged
between 2 local times. This is useful for
comparing model data to sun-synchronous
satellites such as GOME or MOPITT which have
morning overpass times.
 NOTE: The ND51 and ND51b diagnostics

allow you to archive two separate time-
averaged timeseries files simultaneously in
GEOS-Chem. This is useful if you want to
only run GEOS-Chem once, but create
timeseries output corresponding to 2 different
satellite instruments simultaneously.
3 Input_Opt%ND51_FILE The name of the ND51 and/or ND51b files which
Input_Opt%ND51b_FILE
will contain output from the ND51 and/or ND51b
station timeseries diagnostic. This file will be in
binary punch format and can be read by GAMAP.
You may use date & time tokens YYYY, MM,
DD, hh, mm, ss and GEOS-Chem will replace
4 nothing OBSOLETE
5 Input_Opt%ND51_TRACERS The ND51 and/or ND51b diagnostic quantities to
Input_Opt%ND51b_TRACERS
6 Input_Opt%ND51_HR_WRITE The time of day (in GMT hours) at which the
Input_Opt%ND51b_HR_WRITE
ND51 timeseries file will be written to disk.
Recommended value: 0 GMT each day.
7 Input_Opt%ND51_HR_1 The ND51 and/or ND51b time averaging window
Input_Opt%ND51_HR2
Input_Opt%ND51b_HR_1 (in local time hours). Only data from grid boxes
Input_Opt%ND51b_HR2 where the local time falls within this window will
be included in the diagnostic averaging process.
Recommended values: 10:00 to 12:00 LT. This
will cover both GOME and MOPITT overpasses.
8 Input_Opt%ND51_IMIN The indices which determine the longitude extent
Input_Opt%ND51_IMAX
Input_Opt%ND51b_IMIN of the 3D region of the globe. Note that these are
Input_Opt%ND51b_IMAX indices and not actual longitude values. To specify

 For GMAO 2° x 2.5° grid: 1 144

Input_Opt%ND51_JMAX
Input_Opt%ND51b_JMIN the 3D region of the globe. Note that these are
Input_Opt%ND51b_JMAX indices and not actual latitude values. To specify
all 180 degrees of latitude, type the following:

 For GMAO 2° x 2.5° grid: 1 91
Input_Opt%ND51_LMAX
Input_Opt%ND51b_LMIN the 3D region of the globe.
Input_Opt%ND51b_LMAX

ND63 Menu
01: %%% ND63 MENU %%% :

03: Inst 3-D timeser. file : paranox_ts.YYYYMMDD.bpch
04: Tracers to include : 1

2 Input_Opt%DO_ND63 Set this to T to turn on the ND63 ship timeseries
diagnostic.
3 Input_Opt%ND63_FILE Specify the name of the file which will contain
output from the ND63 timeseries diagnostic. This
file will be in binary punch format and can be read
by GAMAP. You may use date & time tokens
YYYY, MM, DD, hh, mm, ss and GEOS-Chem will
replace these with the appropriate values.
4 Input_Opt%ND63_TRACERS Specify the ND63 diagnostic quantities that you
wish to save to disk. Separate each number with a
space.
5 Input_Opt%ND63_FREQ The frequency in seconds at which the ND63 ship
diagnostics will be written to disk.
Input_Opt%ND63_IMAX

 For GMAO 2° x 2.5° grid: 1 144

Input_Opt%ND63_JMAX

 For GMAO 2° x 2.5° grid: 1 91
Prod and Loss Menu
01: %%% PROD & LOSS MENU %%%:

02: Turn on P/L (ND65) diag?: T
03: # of levels for ND65 : 72
04: Save O3 P/L (ND20)? : F

2 Input_Opt%DO_SAVE_PL Set this switch to T if you wish to save out chemical
production for family tracers (a.k.a. the ND65
diagnostic), or F otherwise.
3 Input_Opt%ND65 Specify the number of levels to save for the chemical
family production & loss diagnostic.
 If you enter 1, it will just save the surface level.

 If you enter 20, then it will save all levels from
level 1 (surface) to level 20, etc.
4 Input_Opt%DO_SAVE_O3 Set this switch to T if you wish to archive P(Ox) and
L(Ox) rates from a full chemistry simulation into
binary punch format, so that these rates can be used to
drive a future tagged Ox simulation (a.k.a. ND20
diagnostic).
Benchmark Menu
01: %%% BENCHMARK MENU %%% :

02: Save benchmark output? : T
03: File w/ initial Ox : Ox.mass.initial
04: File w/ final Ox : Ox.mass.final

2 Input_Opt%LSTDRUN Set this switch to T if you wish to save out
benchmark diagnostics, or F otherwise. This
option will save out initial and final tracer
masses needed for the 1-month benchmark
simulation plotting routines.
3 Input_Opt%STDRUN_INIT_FILE Specify name of file (binary punch format)
that will contain initial tracer mass.
4 Input_Opt%STDRUN_FINAL_FILE Specify name of file (binary punch format)
that will contain final tracer mass.
Nested Grid Menu
NOTE: This menu controls options for the various GEOS-Chem nested grid simulations. This is
an optional menu and may be omitted from input.geos if you are not concerned with these
simulations.
For more information, please see:
 Nested-grid simulations
 Setting up GEOS-Chem nested grid simulations
 Available met data for nested grid simulations
01: %%% NESTED GRID MENU %%%:

02: Save TPCORE BC's : F
03: Input BCs at 2x2.5? : F
04: Over North America? : F
05: TPCORE NA BC directory : BC_4x5_NA/
06: Over Europe? : F
07: TPCORE EU BC directory : BC_4x5_EU/
08: Over China? : F
09: TPCORE CH BC directory : BC_4x5_CH/
10: Over Asia? : F
11: TPCORE AS BC directory : BC_4x5_AS/
12: Over Custom Region? : F
13: TPCORE BC directory : BC_4x5/
14: BC timestep [sec] : 10800
15: LL box of BC region : 9 26
16: UR box of BC region : 29 41
17: I0_W, J0_W, I0_E, J0_E : 3 3 3 3
Lin What gets defined Description

e
2 Input_Opt%LWINDO Set this to T if you wish to save out boundary conditions
from a GEOS-Chem simulation, or F otherwise. Before
you run at the nested-grid resolution, you must first save
out boundary conditions from a global GEOS-Chem
simulation (usually 2° x 2.5°).
3 Input_Opt%LWINDO2x Set this to T if you are using boundary conditions
25
archived from a 2° x 2.5° GEOS-Chem simulation, or F
otherwise.
4 Input_Opt%LWINDO_N Set this to T if you wish to perform a GEOS-Chem
A
nested grid simulation over the North American nested
domain.
5 Input_Opt%TPBC_DIR The directory path containing boundary conditions for
_NA
your North American nested-grid simulation.
6 Input_Opt%LWINDO_E Set this to T if you wish to perform a GEOS-Chem
U
nested grid simulation over the European nested domain.
_EU
your European nested-grid simulation.
8 Input_Opt%LWINDO_C Set this to T if you wish to perform a GEOS-Chem
H
nested grid simulation over the China/SE Asia nested
domain.
9 Input_Opt%TPBC_DIR Which is the directory path containing boundary
_CH conditions for your China/SE Asia nested-grid
simulation.
10 Input_Opt%LWINDO_A Set this T if you wish to perform a GEOS-Chem nested
S
grid simulation over the MERRA-2 extended Asia
region.
_AS
your SE Asia nested-grid simulation.
12 Input_Opt%LWINDO_C Set this to T if you wish to perform a GEOS-Chem
U
nested grid simulation a domain that you have
customized yourself.
13 Input_Opt%TPBC_DIR which is the directory path containing the boundary
_CU
conditions for your custom-domain nested-grid
simulation.
14 Input_Opt%NESTED_T Specify the frequency in seconds at which the 2° x 2.5°
S
or 4° x 5° boundary conditions will be saved to disk.
Recommended value: 10800 sec (= 3 hours).
15 Input_Opt%NESTED_I These are the longitude and latitude indices of the grid
1
Input_Opt%NESTED_J box at the LOWER LEFT CORNER of the window
1 region in which boundary conditions are being saved.
16 Input_Opt%NESTED_I These are the the longitude and latitude indices of the
2
Input_Opt%NESTED_J grid box at the UPPER RIGHT CORNER of the window
2 region in which boundary conditions are being saved.
17 Input_Opt%NESTED_I These are the nested grid longitude and latitude offsets
0W
Input_Opt%NESTED_J (in # of boxes) of the which are used to define an inner
0W window region in which transport is actually done. The
Input_Opt%NESTED_I region in which transport is done in the window is
0E
Input_Opt%NESTED_J
smaller than the actual size of them nested grid met
0E fields in order to account for the boundary conditions.
Please see the comments to the source code
file tpcore_bc_mod.F for more information.
Recommended values:
 Input_Opt%NESTED_I0W=3 and Input_Opt%NESTED_J0W

=3.
 Input_Opt%NESTED_I0E=3 and Input_Opt%NESTED_J0E
=3.
 But for some grids (e.g. SE Asia) you may want
to
use Input_Opt%NESTED_I0E=2 and Input_Opt%NES
TED_J0E=2.
For more information, please contact the Nested Model

Working Group.

Passive Species Menu
01: %%% PASSIVE SPECIES MENU %%%:

02: Number of passive spec. : 2
03: Passive species #1 : PASV1 1.0 -1 1.0e-7
04: Passive species #2 : PASV2 50.0 3600.0 1.0e-12

defined
2 nPassive The number of passive species that you want to include.
3-4 SpcName For each passive species, you must provide the following
SpcMW
SpcTau information (separated by spaces):
SpcInitConc
 Species name
 Species molecular weight (g/mol)
 Atmospheric lifetime (s)
 Specify 0 or negative value for no loss
 Default initial atmospheric concentration (v/v)
 This value will only be used if the species is not found
in the restart file.
There must be a matching entry in the advected species menu for every passive species defined
in the passive species menu. If the two menus aren't consistent, you will get a species database
error. For more information, see this wiki post on adding passive species.
CH4 simulation menu
This menu controls options for the tagged CH4 simulation only. This is an optional menu and
may be omitted from input.geos if you are not concerned with this simulation. For more
information, please see our CH4 simulation wiki page.
01: %%% CH4 MENU %%% :

02: Compute CH4 budget? : F
03: Use Gas & Oil emis? : T
04: Use Coal Mine emis? : T
05: Use Livestock emis? : T
06: Use Waste emis? : T
07: Use Biofuel emis? : T
07: Use Rice emis? : T
08: Use Ot. Anthro emis? : T
09: Use Biomass emis? : T
10: Use Wetlands emis? : T
11: Use Soil Absorption? : T
12: Use Ot. Natural? : T

2 Input_Opt%LCH4BUD Set this to T to calculate a monthly budget for CH4.
 NOTE: The CH4 budget is not working well, we

recommend setting leaving this set to F.
3 Input_Opt%LGAO Set this to F to turn off CH4 emissions from gas and oil.
4 Input_Opt%LCOL Set this to F to turn off CH4 emissions from coal.
5 Input_Opt%LLIV Set this to F to turn off CH4 emissions from livestock.
6 Input_Opt%LWAST Set this to F to turn off CH4 emissions from waste.
7 Input_Opt%LBFCH4 Set this to F to turn off CH4 emissions from biofuels.
8 Input_Opt%LRICE Set this to F to turn off CH4 emissions from rice fields.
9 Input_Opt%LOTANT Set this to F to turn off other CH4 anthropogenic
emissions.
10 Input_Opt%LBMCH4 Set this to F to turn off CH4 emissions from biomass
burning.
11 Input_Opt%LWETL Set this to F to turn off CH4 emissions from wetlands.
12 Input_Opt%LSOABS Set this to F to turn off CH4 absorption by soils.
13 Input_Opt%LOTNAT Set this F to turn off other CH4 natural emissions.
CO2 Simulation Menu
This menu only controls options for the CO2 and tagged CO2 simulations. This is an optional
menu and may be omitted from input.geos if you are not concerned with these simulations. For
more information, please see:
 Our CO2 simulation wiki page.
 A more detailed account of all settings can be found in:
 Nassar, R., D.B.A. Jones, P. Suntharalingam, J.M. Chen, R.J. Andres, K.J. Wecht, R.M.
Yantosca, S.S. Kulawik, K.W. Bowman, J.R. Worden, T. Machida, and H.
Matsueda, Modeling CO2 with improved emission inventories and CO2 production from
the oxidation of other carbon species, Geoscientific Model Development, 3, 689-716,
2010.
01: %%% CO2 SIM MENU %%% :

02: Fossil Fuel Emissions : T
03: Ocean Exchange : T
04: Balanced Biosphere Exch : T
05: Net Terrestrial Exch : T
06: Ship emissions : T
07: Aviation emissions 3-D : T
08: 3-D Chemical Oxid Source: T
09: Tagged CO2 runs :---
10: Save Fossil in Bckgrnd: F
11: Tag Bio/Ocean CO2 reg : F
12: Tag Land FF CO2 reg : F
13: Tag Global Ship CO2 : F
14: Tag Global Plane CO2 : F

2 Input_Opt%LFOSSIL Set this to T to use fossil-fuel emissions of CO2 as
computed by HEMCO.
3 Input_Opt%LOCEAN Set this to T to use ocean exchange of CO2 as as
computed by HEMCO.
4 Input_Opt%LBIODIURNAL Set this to T to turn on the CASA model 3-hourly Net
Ecosystem Production (balanced – no net annual
flux) [Potter et al., 1993; Olsen and Randerson,
2004].
5 Input_Opt%LBIONETCLIM Set this to T to turn on Net Terrestrial Exchange
(climatology) of -5.29 PgC/yr [Baker et al., 2006]
adjusted for biomass/biofuel burning.
6 Input_Opt%LSHIP Set this to T to use on ship emissions of CO2 as
computed by HEMCO.
7 Input_Opt%LPLANE Set this to T to turn on the aviation emission 3-D
distribution from fuel burn (GEOS-Chem sulfate
aerosol simulation) scaled to annual CO2 values for
1985-2002 [Sausen & Schumann, 2000; Kim et al.,
2005; 2007; Wilkerson et al., 2010] and estimates for
2002-2009. An associated surface correction
automatically removes domestic aviation emissions
from the main fossil fuel source in continental size
regions.
8 Input_Opt%LCHEMCO2 Set this to T to turn on the 3D CO2 chemical source
from oxidation of CO, CH4 and NMHCs based on
Suntharalingam et al. [2005], with appropriate surface
emission corrections.
10 Input_Opt%LFFBKGRD Set this to T to save CO2 background.
11 Input_Opt%LBIOSPHTAG Set this to T to tag biosphere regions (28), ocean
regions (11) and the Rest of the World (ROW) as
specified in
the Regions_land.dat and Regions_ocean.dat files.
 NOTE: Tagged tracers should be customized by

each user and the present configuration will not
work for resolutions other than 2x2.5.
12 Input_Opt%LFOSSILTAG Set this to T to tag fossil fuel regions (28) as specified
in the Regions_land.dat file and ROW.

13 Input_Opt%LSHIPTAG Set this to T to tag global ship emissions as a single
tracer.

14 Input_Opt%LPLANETAG Set this to T to Tag global aviation emissions as a
single tracer.

POPs simulation menu
This menu controls options for the persistent organic pollutants (POPs) simulation only. This is
an optional menu and may be omitted from input.geos if you are not concerned with this
simulation. For more information, please see our POPs simulation wiki page.
01: %%% POPS MENU %%% :

02: POP type [PHE,PYR,BAP] : PHE
03: Chemistry processing on?: T
04: POP_XMW : 178.23d-3
05: POP_KOA : 4.37d7
06: POP_KBC : 1.0d10
07: POP_K_POPG_OH : 2.7d-11
08: POP_K_POPG_O3A : 0d0
09: POP_K_POPG_O3B : 2.15d15
10: POP_HSTAR : 1.74d-3
11: POP_DEL_H : -74d3
12: POP_DEL_Hw : 47d0

2 Input_Opt%POP_TYPE Current options are PHE (phenanthrene), PYR
(pyrene), or BAP (benzo[a]pyrene).
3 Input_Opt%CHEM_PROCESS Set this to T to use POPs chemistry.
4 Input_Opt%POP_XMW The molecular weight of the POPs species in
kg/mol.
 NOTE: This should be superseded by the

molecular weight field from the GEOS-Chem
species database.
5 Input_Opt%POP_KOA The POP octanol-water partition coefficient.
6 Input_Opt%POP_KBC The POP black carbon-air partition coefficient.
7 Input_Opt%POP_K_POPG_OH The POP reaction rate constant for reaction of gas
phase POP with hydroxyl radical in cm3/molec/s.
8 Input_Opt%POP_K_POPP_O3A The POP reaction rate constant for reaction of
particle phase POP with ozone in s-1.
9 Input_Opt%POP_K_POPP_O3B The POP reaction rate constant for reaction of
particle phase POP with ozone in molec/cm3.
10 Input_Opt%POP_HSTAR The Henry's Law constant for the POPs species.
 NOTE: This should be superseded by the

Henry's law constant field from the GEOS-
Chem species database.
11 Input_Opt%POP_DEL_H The enthalpy of air-water exchange in J/mol.
12 Input_Opt%POP_DEL_Hw The enthalpy of phase transfer from gas phase to
particle phase.
Mercury Simulation Menu
NOTE: The Global Terrestrial Mercury Model is broken in v11-01. We need to convert the
GTMM restart file from bpch to netCDF. The work is ongoing.
This menu only controls options for the mercury simulation (with or without the Global Terrestrial
Mercury Model). This is an optional menu and may be omitted from input.geos if you are not
concerned with this simulation.
For more information, please see:
 Mercury simulation
 Global Terrestrial Mercury Model
01: %%% MERCURY MENU %%% :

02: Use anthro Hg emiss for : 2006
03: Use future emissions? : PRESENT
04: Error check tag/tot Hg? : F
05: Use dynamic ocean Hg? : T
06: Preindustrial sim? : F
07: Use GTMM soil model? : F
08: GTMM Hg rst file (bpch) : GTM.totHg.YYYYMMDDhh
09: Use Arctic river Hg? : T
10: Tie HgII(aq) red to UVB?: T

2 Input_Opt%ANTHRO_Hg_YEAR Baseline year of the anthropogenic mercury
emissions that are used in the tagged mercury
simulation. Current options are either 2006 or
2050.
3 Input_Opt%Hg_SCENARIO Future emissions are based on the four IPCC
SRES scenarios. Current options are PRESENT,
A1B, A2, B1, or B2.
4 Input_Opt%USE_CHECKS Set this to T to stop with an error message if the
sum of tagged tracers does not equal the total
tracer, or F otherwise. This is useful for
debugging.
5 Input_Opt%LDYNOCEAN. Set this to T to use the online ocean mercury
model (in source code file ocean_mercury_mod.F)
or F to read ocean mercury concentrations from
monthly mean files on disk.
6 Input_Opt%LPREINDHG Set to T if you want to run a preindustrial
simulation (turn off anthropogenic emissions), to
F otherwise.
8 Input_Opt%LGTMM Set to T if you want to run GTMM online in
GEOS-Chem. Note, that to use GTMM online,
you need to first run GTMM offline up to
equilibrium and to compile GEOS-Chem with
GTMM enabled. For more information, please
refer to this document.
8 Input_Opt%GTMM_RST_FILE If you are using the GTMM online, then you can
specify the name of the GTMM mercury restart
file. This file saves the monthly depositions of
mercury tracers for continuing the run at a later
stage. You may use date & time tokens YYYY,
MM, DD, hh, mm, ss and GEOS-Chem will
replace these with the appropriate values.
 NOTE: The GTMM restart file will have to be

converted from bpch to netCDF format.
Radiation Menu
This menu controls options for GEOS-Chem simulations coupled to the RRTMG radiative
transfer model. This is an optional menu and may be omitted from input.geos if you are not
concerned with this simulation. For more information, please see our Coupling GEOS-chem with
RRTMG wiki page.
01: %%% RADIATION MENU %%% :
02: AOD Wavelength (nm) : 550
03: Turn on RRTMG? : F
04: Calculate LW fluxes? : F
05: Calculate SW fluxes? : F
06: Clear-sky flux? : F
07: All-sky flux? : F
08: Radiation Timestep [sec]: 10800
09: Species fluxes : 0 0 0 0 0 0 0 0 0 1 0
10: ---[O3,ME,SU,NI,AM,BC,OA,SS,DU,PM,ST]

2 WVSELECT Specify wavelength(s) for the aerosol optical
properties. Up to three wavelengths can be output. The
wavelengths should be entered in nm with a space
between each entry. The specified wavelengths are
used for the Fast-JX photolysis mechanism, regardless
of whether the RRTMG radiative transfer model is
used.
3 Input_Opt%LRAD Set this to T to turn on online radiative transfer using
RRTMG, or F to turn off RRTMG.
4 Input_Opt%LLWRAD Set this to T to turn on longwave radiation calculation.
5 Input_Opt%LSWRAD Set this to T to turn on shortwave radiation calculation.
6 Input_Opt%LSYKRAD(1) Set this to T to turn turn on calculation for clear-sky
fluxes. This option will perform radiative calculations
without clouds.
7 Input_Opt%LSYKRAD(2) Set this to T to turn turn on calculation for all-sky
fluxes. This option will perform radiative with clouds.
Both clear sky and all-sky options can be turned on
without signigicant increase to run time.
8 Input_Opt%TS_RAD Radiation timestep in seconds. In all cases, the
radiation timesetp should be a multiple of the transport
timestep. The RRTMG calculation is instantaneous
(i.e. not averaged over the period selected) and is set to
occur at half the radiation timestep. We recommend
using a radiation timestep of 10800 sec = 3 hours
(producing RRTMG calls at 01:30, 4:30, etc.).
9 LSPECRADMENU Specify the species for which radiative fluxes will be
calculated. Set a value to 1 to calculate the radiative
effect for that species, or 0 to turn off radiative
calculations for that species. The first RRTMG call
(the "baseline") contains all species switched on and
each requested species calls RRTMG again with that
species omitted, so that the difference can be
calculated. The number of calls to RRTMG will be
equal to the total sum of this line plus one (for the first
"baseline" call), so this can substantially increase
model run time.
 NOTE: If you are using the UCX chemistry

mechanism, then you will need to add an additional
entry (0 or 1) at the end of this line for
stratospheric aerosols for a total of 11 possible
species.
10 nothing This line lists species available for output from the flux
calculations. This line is here for reference and is not
actually read by GEOS-Chem. Available species are:
 O3 (Ozone)
 ME (Methane)
 SU (Sulfate)
 NI (Nitrate)
 AM (Ammonium)
 BC (Black carbon)
 OA (Organic aerosol)
 SS (Sea salt)
 DU (Mineral dust)
 PM (All particulate matter)
 ST (Stratospheric aerosol, UCX simulation only)
The HEMCO_Config.rc file

Overview
In GEOS-Chem v10-01 and later versions, emissions are read, regridded, and calculated by
the HEMCO emissions component. The emission settings are specified in the HEMCO
Configuration file (HEMCO_Config.rc).
For more information about the HEMCO_Config.rc file, please see:
 The HEMCO User's Guide
 HEMCO examples
Enabling and disabling emissions
The HEMCO_Config.rc file for each GEOS-Chem simulation contains a set of switches that
allow you to quickly toggle individual emissions inventories on or off.
Each time you create a GEOS-Chem run directory from the Unit Tester, a
new HEMCO_Config.rc file with default emissions settings will be created in the run directory.
These default settings are located near the top of the HEMCO_Config.rc file.
For example, the default emissions settings for the "Standard" full-chemistry simulation are:
# ExtNr ExtName on/off Species

0 Base : on *
--> HEMCO_RESTART : true
--> AEIC : true
--> BIOFUEL : true
--> BOND : true
--> BRAVO : true
--> CAC : true
--> XIAO : true
--> EDGAR : true
--> HTAP : false
--> EMEP : true
--> EMEP_SHIP : true
--> GEIA : true
--> LIANG_BROMOCARB : true
--> NEI2005 : false
--> NEI2011 : true
--> RETRO : true
--> SHIP : true
--> NEI2011_SHIP : false
--> MIX : true
--> STREETS : false
--> VOLCANO : true
--> RCP_3PD : false
--> RCP_45 : false
--> RCP_60 : false
--> RCP_85 : false
--> QFED2 : false
# -------------------------------------------------------------------------
----
100 Custom : off -
101 SeaFlux : on DMS/ACET
102 ParaNOx : on NO/NO2/O3/HNO3
--> LUT data format : nc
--> LUT source dir : $ROOT/PARANOX/v2015-02
103 LightNOx : on NO
--> OTD-LIS factors : true
--> CDF table : $ROOT/LIGHTNOX/v2014-
07/light_dist.ott2010.dat
104 SoilNOx : on NO
--> Use fertilizer NOx: true
105 DustDead : on DST1/DST2/DST3/DST4
106 DustGinoux : off DST1/DST2/DST3/DST4
115 DustAlk : off DSTAL1/DSTAL2/DSTAL3/DSTAL4
107 SeaSalt : on SALA/SALC/Br2
--> SALA lower radius : 0.01
--> SALA upper radius : 0.5
--> SALC lower radius : 0.5
--> SALC upper radius : 8.0
--> Emit Br2 : true
--> Br2 scaling : 1.0
116 MarinePOA : off MOPO/MOPI
108 MEGAN : on ISOP/ACET/PRPE/C2H4/ALD2
--> Isoprene scaling : 1.0
--> CO2 inhibition : true
--> CO2 conc (ppmv) : 390.0
109 MEGAN_Mono : on CO/OCPI/MONX
110 MEGAN_SOA : on MTPA/MTPO/LIMO/SESQ
111 GFED : on
NO/CO/ALK4/ACET/MEK/ALD2/PRPE/C3H8/CH2O/C2H6/SO2/NH3/BCPO/BCPI/OCPO/OCPI/PO
G1/POG2/NAP
--> GFED3 : false
--> GFED4 : true
--> GFED_daily : false
--> GFED_3hourly : false
--> Scaling_CO : 1.05
--> Scaling_POG1 : 1.27
--> Scaling_POG2 : 1.27
--> Scaling_NAP : 2.75e-4
--> hydrophilic BC : 0.2
--> hydrophilic OC : 0.5
--> fraction POG1 : 0.49
114 FINN : off
NO/CO/ALK4/ACET/MEK/ALD2/PRPE/C3H8/CH2O/C2H6/SO2/NH3/BCPI/BCPO/OCPI/OCPO/GL
YC/HAC
--> FINN_daily : false
--> Scaling_CO : 1.0
--> hydrophilic BC : 0.2
--> hydrophilic OC : 0.5
If you would like to turn off NEI2011, simply change the true in this line:
--> NEI2011 : true
to false:
--> NEI2011 : false
And if you also wanted to turn off the MEGAN biogenic emissions, simply change the on in this
line:
108 MEGAN : on ISOP/ACET/PRPE/C2H4/ALD2
to off:
108 MEGAN : off ISOP/ACET/PRPE/C2H4/ALD2
etc.
The HEMCO_Diagn.rc file

You can archive any type of emissions (or other quantity) computed by the HEMCO emissions
component to netCDF-format diagnostic output. The HEMCO_Diagn.rc file controls diagnostic
output options for HEMCO.
Here is a snapshot of the HEMCO_Config.rc from the geosfp_4x5_benchmark run directory.
#--------------------------------------------------------------------------
----
# GEOS-Chem Global Chemical Transport Model
!
#--------------------------------------------------------------------------
----
#BOP
#
# !MODULE: HEMCO_Diagn.rc
#
# !DESCRIPTION: Configuration file for netCDF diagnostic output from HEMCO.
#\\
#\\
# !REMARKS:
# Customized for the benchmark simulation.
# TO DO: Add long names, which are used for netCDF variable attributes.
#
# !REVISION HISTORY:
# 13 Feb 2018 - E. Lundgren - Initial version
#EOP
#--------------------------------------------------------------------------
----
#BOC
# Name Spec ExtNr Cat Hier Dim OutUnit LongName
###########################################################################
####
##### ACET emissions (in bpch ND11, ND28, ND34, ND36, ND46)
#####
###########################################################################
####
EmisACET_Total ACET -1 -1 -1 3 molec/cm2/s
EmisACET_Anthro ACET 0 1 -1 3 atomsC/cm2/s
EmisACET_BioBurn ACET 111 -1 -1 2 atomsC/cm2/s
EmisACET_Biofuel ACET 0 2 -1 2 atomsC/cm2/s
EmisACET_Biogenic ACET 108 -1 -1 2 atomsC/cm2/s
EmisACET_DirectBio ACET 108 -1 -1 2 atomsC/cm2/s
ACET_from_direct_emissions
EmisACET_MethylBut ACET 108 -1 -1 2 atomsC/cm2/s
ACET_from_methyl_butenol
EmisACET_Monoterp ACET 108 -1 -1 2 atomsC/cm2/s
ACET_from_monoterpenes
EmisACET_Ocean ACET 101 -1 -1 2 atomsC/cm2/s
ACET_from_ocean_source
###########################################################################
####
##### ALD2 emissions (in bpch ND28, ND34, ND36, ND46. ALD2_Ocean
#####
##### and is new)
#####
###########################################################################
####
EmisALD2_Total ALD2 -1 -1 -1 3 molec/cm2/s
EmisALD2_Anthro ALD2 0 1 -1 3 atomsC/cm2/s
EmisALD2_BioBurn ALD2 111 -1 -1 2 atomsC/cm2/s
EmisALD2_Biofuel ALD2 0 2 -1 2 atomsC/cm2/s
EmisALD2_Biogenic ALD2 108 -1 -1 2 atomsC/cm2/s
EmisALD2_Ocean ALD2 101 -1 -1 2 atomsC/cm2/s
EmisALD2_Senesc ALD2 0 4 -1 2 atomsC/cm2/s
As you can see, you can archive not only the total emissions for a given species, but also the
individual emission sectors. This gives you much more flexibility over the GEOS-Chem bpch
diagnostic output.
Once you have your HEMCO_Diagn.rc file customized for your given simulation, make sure that
you have these settings in your HEMCO_Config.rc file:
DiagnFile: HEMCO_Diagn.rc
DiagnPrefix: HEMCO_diagnostics
DiagnFreq: End
where:
 DiagnFile specifies the location of the HEMCO_Diagn.rc file.

 DiagnPrefix specifies the the prefix for all HEMCO-generated diagnostic files.
 DiagnFreq specifies the diagnostic archival frequency.
For more information about how to archive diagnostics from HEMCO, please
see The Diagnostics section of The HEMCO User's Guide.
The HISTORY.rc file

The HISTORY.rc file allows you to specify which diagnostic quantities will be archived to netCDF
diagnostics in both GEOS-Chem "Classic" and GEOS-Chem with the High-Performance Option
(aka GCHP).
For a detailed description of this file, please see the Overview section of our List of diagnostics
archived to netCDF format wiki page.
--Bob Yantosca (talk) 18:41, 24 May 2018 (UTC)
The Planeflight.dat file

The Planeflight.dat.YYYYMMDD files allow you to specify the diagnostic quantities (species,
reaction rates, met fields) that you want to print out for a specific longitude, latitude, altitude, and
time. See our Planeflight diagnostic wiki page for more information.
Input files for the photolysis mechanism

GEOS-Chem v10-01 and later versions use the FAST-JX v7.0 photolysis mechanism. Several
input files for the FAST-JX photolysis mechanism ship with the GEOS-Chem run directories. You
should only have to modify these files if you wish to change the chemical mechanism or
photolysis mechanism.
For more information, please see our Input files for FAST-JX v7.0 wiki post.
Unit Tester for GEOS-Chem 12
(Redirected from GEOS-Chem unit tester for v11-02)
GEOS-Chem v11-02-final will also carry the designation GEOS-Chem

12.0.0. We are migrating to a purely numeric versioning system in order to adhere
more closely to software development best practices. For a complete description of
the new versioning system, please see ourGEOS-Chem version numbering
system wiki page.
This page describes the GEOS-Chem Unit Tester package that corresponds to GEOS-Chem
v11-02 (aka 12.0.0).
NOTE: If you are still using GEOS-Chem v11-01, then please see our GEOS-Chem unit tester
for v11-01 wiki page.
Contents
[hide]
 1 Overview
 2 Installing the GEOS-Chem Unit Tester
o 2.1 Requirements
o 2.2 Downloading the GEOS-Chem Unit Tester
 2.2.1 Reverting to an older state
o 2.3 Directory structure
 3 Using the GEOS-Chem Unit Tester
o 3.1 What the GEOS-Chem Unit Tester does
o 3.2 Specifying unit test options with an input file
 3.2.1 The INPUTS section
 3.2.2 The RUNS section
o 3.3 Running the GEOS-Chem Unit Tester
 4 Examining the results
o 4.1 Output files written to each unit test run directory
o 4.2 Log files written to the unit test log directory
o 4.3 Unit test results and error messages
o 4.4 How unit tests are scored
o 4.5 Unit test results displayed as a web page
 5 GEOS-Chem Unit Test Results
o 5.1 LEGEND
o 5.2 Unit test results displayed as a text file
 6 Cleaning old files
Overview
The GEOS-Chem Unit Tester contains the various Makefiles, scripts, and run directories that
you will need to run GEOS-Chem. With the Unit Tester, you can:
Action Description
Create GEOS- You can use a script to create fresh copies of GEOS-Chem run
Chem run directories for each supported GEOS-Chem simulation. Each run
directories directory that you create will contain all of the necessary input files
with the proper settings. For detailed instructions, please visit
our Creating GEOS-Chem run directories wiki page.
Set up GEOS- You can create run directories that can be used to perform 7-model-
Chem 7-day day timing tests. This will allow you to quickly evaluate the
timing tests performance of GEOS-Chem on your system. For more information,
please see our Timing tests with GEOS-Chem v11-02 wiki page.
Run GEOS- An individual GEOS-Chem Unit Test will look for computational and
Chem unit numerical issues in simulations for a given combination of:
tests
1. Met field type
2. Horizontal grid
3. Simulation type
We recommend that you perform frequent unit tests as you develop
code, as this is the best way to find many common types of errors.
For more information about how to submit unit tests, please
see the Using the Unit Testersection below.
Run GEOS- A Difference Test validates that structural updates in a given GEOS-
Chem Chem "Development" (or "Dev") produce identical results when
difference compared to a "Reference" (or "Ref") version.
tests
You can use a script that will create difference test run directories for
any of the supported GEOS-Chem simulations. For more information
on how to set up GEOS-Chem difference tests, please
see our Performing Difference Tests with GEOS-Chem wiki page.
Installing the GEOS-Chem Unit Tester

Requirements
Most GEOS-Chem users will already have the necessary software to be able to run the GEOS-
Chem Unit Test package. These are:
If you use GEOS-Chem

If you use GEOS-Chem
Item on the Amazon Web Services
on a computer cluster
cloud
A modern Unix This will be already This will be included in the

operating system installed on your cluster. Amazon Machine Image (AMI)
The particular flavor of that you use to initialize your
 CentOS, Ubuntu, Unix should not matter. login environment.
Fedora ...
The bash Unix shell This should be pre- ""

installed with your OS.
The Perl programming "" ""

language
The GNU make utility "" ""

Downloading the GEOS-Chem Unit Tester
IMPORTANT NOTE! As of June 2018, we have migrated the GEOS-Chem Unit Tester
repository from Bitbucket back to Github. Going forward, please make sure to clone or
pull code updates ONLY from the Github repository. Using Github will allow us to define a
DOI for each GEOS-Chem major version.
First, make sure that your system has these software packages installed. (Most of these come
standard with your Unix-based operating system.)
Next, clone the GEOS-Chem Unit Tester package with these commands:
git clone https://github.com/geoschem/geos-chem-unittest UT

git checkout master
This will download a fresh copy of the GEOS-Chem-UnitTest repository into a directory
named UT, and place you in the master branch. The master branch always corresponds to the
last publicly-released GEOS-Chem version.
If you would like to check out the Unit Tester that corresponds to a specific numbered GEOS-
Chem version you can type one of the following commands:
git checkout 12.0.0
git checkout v11-02-rc
git checkout v11-02e
etc.
Reverting to an older state
If you would like to use the Unit Tester to validate an older version of GEOS-Chem, then you can
use the gitk browser to open a new branch at a past commit as follows:
1. Open the gitk browser by typing gitk & at the command line.
2. In the top-left window of gitk, find the commit that you want to revert to. Usually this will
be denoted with a yellow tag (e.g. v9-02-Provisional-Release' or v10-01b, etc.).
3. Right click with the mouse. This will open a context menu. Select Create new branch.
4. A new dialog box will pop up asking you to name the branch.
Type OLDER_BRANCH and press OK.
5. Close gitk and open the Git GUI by typing git gui &
6. From the Git GUI dropdown menu, select Branch / Checkout, and then
pick OLDER_BRANCH.
That's it! We now have two branches that represent different GEOS-Chem versions.
1. The master branch represents current state of the unit tester

2. The OLDER_BRANCH branch represents the state of the unit tester that you checked
out (synced to an older GEOS-Chem version)
Directory structure
The GEOS-Chem Unit Tester adheres to the following directory structure:
jobs/ Job scripts created by the GEOS-Chem Unit Test driver

script gcUnitTest will be sent here.
logs/ Log files containing output from the GEOS-Chem Unit Test simulations will
be sent here.
perl/ Contains the Perl scripts that are used to submit GEOS-Chem Unit Test
simulations.
 The driver script is called gcUnitTest.

 The default input file for gcUnitTest is named UnitTest.input.
 Sample customized versions of UnitTest.input are stored in
the perl/inputs subdirectory.
 The cleanFiles script is used to remove job scripts, log files, and
output files created by GEOS-Chem.
runs/ Contains the various run directories. Each run directory is named
according to the met field, horizontal grid, and type of simulation
(4x5_standard, 2x25_RnPbBe, etc).
Using the GEOS-Chem Unit Tester

What the GEOS-Chem Unit Tester does
For each individual unit test (met field + horizontal grid + simulation type) that you specify in
the RUNS section of the input file (more on this below), the GEOS-Chem Unit Tester will do the
following:
1. Run GEOS-Chem with strict debugging flags with OpenMP parallelization turned OFF
 This is called the single processor or sp test phase.
2. Run GEOS-Chem with strict debugging flags with OpenMP parallelization turned ON
 This is called the multi processor or mp test phase.
The strict debugging flags will look for common computational and numerical issues, such as
1. Floating-point math exceptions: div-by-zero, invalid computations (i.e. SQRT(-1), LOG(-

1), etc.)
2. Array-out-of-bounds errors
3. Creation of array temporaries
Furthermore, the Unit Tester compare the output of the sp and mp test phases. If these outputs
differ, then this indicates a parallelization error.
--Bob Y. 10:08, 25 April 2014 (EDT)
Specifying unit test options with an input file
Before you can start the GEOS-Chem Unit Tester, you must first specify the options for the unit
test simulations in an input file. You can specify the directory paths for your system, the location
of the GEOS-Chem code directory, the submit command for your system, and the types of
simulations that you want the GEOS-Chem Unit Tester to validate. The default input file is
named UnitTest.input, but you can cut-n-paste this file to create as many customized input
files as you need.
The UnitTest.input file looks like this. All lines beginning with a # character are treated as
comments and will be ignored.
#--------------------------------------------------------------------------
----
# GEOS-Chem Global Chemical Transport Model
!
#--------------------------------------------------------------------------
----
#BOP
#
# !INCLUDE: UnitTest.input
#
# !DESCRIPTION: Input file that specifies debugging options for the
# GEOS-Chem unit tester.
#\\
#\\
# !REMARKS:
# To omit individual unit tests (or input settings), place a # comment
# character in the first column.
#
# For a complete explanation of how to customize the settings below for
# your installation, please see these wiki posts:
#
# http://wiki.geos-chem.org/GEOS-Chem_Unit_Tester#The_INPUTS_section
# http://wiki.geos-chem.org/GEOS-Chem_Unit_Tester#The_RUNS_section
#
# Type 'gitk' at the prompt to browse the revision history.
#EOP
#--------------------------------------------------------------------------
----
#
# !INPUTS:
#
# %%% ID tags %%%
#
VERSION : v11-02
DESCRIPTION : Tests GEOS-Chem v11-02
#
# %%% Data path and HEMCO settings %%%
#
DATA_ROOT : /n/holylfs/EXTERNAL_REPOS/GEOS-
CHEM/gcgrid/data/ExtData
HEMCO_ROOT : {DATAROOT}/HEMCO
VERBOSE : 3
WARNINGS : 3
#
# %%% Code and queue settings %%%
#
CODE_DIR : {HOME}/GC/Code.v11-02
MAKE_CMD : make -j4 BOUNDS=y DEBUG=y FPEX=y NO_ISO=y BPCH_DIAG=y
NC_DIAG=n
SUBMIT : sbatch
#
# %%% Unit tester path names %%%
#
UNIT_TEST_ROOT : {HOME}/UT
RUN_ROOT : {UTROOT}/runs
RUN_DIR : {RUNROOT}/{RUNDIR}
JOB_DIR : {UTROOT}/jobs
LOG_DIR : {UTROOT}/logs/{VERSION}
PERL_DIR : {UTROOT}/perl
#
# %%% Web and text display options %%%
#
TEMPLATE : {PERLDIR}/ut_template.html
TXT_GRID : {LOGDIR}/{VERSION}.results.txt
WEB_GRID : {LOGDIR}/{VERSION}.results.html
WEB_PUSH : NONE
#
# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
# %%% OPTIONAL COMMANDS: %%%
# %%% %%%
# %%% If your system uses the SLURM scheduler, then you can %%%
# %%% define several #SBATCH tags that will be added to the top %%%
# %%% of the job script. Otherwise you can comment these lines %%%
# %%% out with the # comment character. %%%
# %%% %%%
# %%% NOTE: If you do use these SLURM commands, then also be %%%
# %%% sure to set the SUBMIT command above to "sbatch". %%%
# %%% %%%
# %%% The INIT_COMMANDS tag will let you specify any optional %%%
# %%% initialization commands that will be placed at the top %%%
# %%% of the job script. For example, if your system requires %%%
# %%% that modules need to be loaded from within the job script, %%%
# %%% you can specify those instructions here. %%%
# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
#
SLURM_CPUS : 4
SLURM_NODES : 1
SLURM_TIME : 1-12:00
SLURM_MEMORY : 35000
SLURM_PARTITION : huce_intel
SLURM_CONSTRAINT : broadwell
SLURM_MAILTYPE : END
# Add initialization commands for your system here if necessary

# Otherwise, leave these commented out
#INIT_COMMANDS : . ~/.bashrc
#
# !RUNS:
# Specify the debugging runs that you want to perform below.
# You can deactivate runs by commenting them out with "#".
#
#--------|-----------|------|----------------|------------|--------------|-
----|
# MET | GRID | NEST | SIMULATION | START DATE | END DATE
|EXTRA|
#--------|-----------|------|----------------|------------|--------------|-
----|
# ======= GEOS-Chem benchmark
================================================
geosfp 4x5 - benchmark 2016070100 201607010020
-
# ======= Radon-Lead-Beryllium
===============================================
geosfp 4x5 - RnPbBe 2016010100 201601010020
-
merra2 4x5 - RnPbBe 2016010100 201601010020
-
geosfp 2x25 - RnPbBe 2016010100 201601010020
-
merra2 2x25 - RnPbBe 2016010100 201601010020
-
# ======= Mercury
============================================================
geosfp 4x5 - Hg 2016010100 201601010020
-
merra2 4x5 - Hg 2016010100 201601010020
-
geosfp 2x25 - Hg 2016010100 201601010020
-
merra2 2x25 - Hg 2016010100 201601010020
-
# ======= Tagged Mercury
=====================================================
geosfp 4x5 - tagHg 2016010100 201601010020
-
merra2 4x5 - tagHg 2016010100 201601010020
-
# ======= POPs
===============================================================
geosfp 4x5 - POPs 2016070100 201607010020
-
merra2 4x5 - POPs 2016070100 201607010020
-
geosfp 2x25 - POPs 2016070100 201607010020
-
merra2 2x25 - POPs 2016070100 201607010020
-
# ======= Methane
============================================================
geosfp 4x5 - CH4 2016070100 201607010020
-
merra2 4x5 - CH4 2016070100 201607010020
-
geosfp 2x25 - CH4 2016070100 201607010020
-
merra2 2x25 - CH4 2016070100 201607010020
-
geosfp 025x03125 na CH4 2016070100 201607010010
-
merra2 05x0625 na CH4 2016070100 201607010020
-
# ======= Tagged O3
==========================================================
geosfp 4x5 - tagO3 2016070100 201607010020
-
merra2 4x5 - tagO3 2016070100 201607010020
-
geosfp 2x25 - tagO3 2016070100 201607010020
-
merra2 2x25 - tagO3 2016070100 201607010020
-
# ======= Tagged CO
==========================================================
geosfp 4x5 - tagCO 2016070100 201607010020
-
merra2 4x5 - tagCO 2016070100 201607010020
-
geosfp 2x25 - tagCO 2016070100 201607010020
-
merra2 2x25 - tagCO 2016070100 201607010020
-
# ======= Carbon Dioxide
=====================================================
geosfp 2x25 - CO2 2016070100 201607010020
-
merra2 2x25 - CO2 2016070100 201607010020
-
# ======= Offline Aerosols
===================================================
geosfp 4x5 - aerosol 2016070100 201607010020
-
merra2 4x5 - aerosol 2016070100 201607010020
-
geosfp 2x25 - aerosol 2016070100 201607010020
-
merra2 2x25 - aerosol 2016070100 201607010020
-
# ======= Standard
===========================================================
geosfp 4x5 - standard 2016070100 201607010020
-
merra2 4x5 - standard 2016070100 201607010020
-
-
merra2 2x25 - standard 2016070100 201607010020
-
# ======= Tropchem
===========================================================
geosfp 4x5 - tropchem 2016070100 201607010020
-
merra2 4x5 - tropchem 2016070100 201607010020
-
-
merra2 2x25 - tropchem 2016070100 201607010020
-
# ======= Complex SOA (w/o and w/ SVPOA)
=====================================
geosfp 4x5 - complexSOA 2016070100 201607010020
-
merra2 4x5 - complexSOA 2016070100 201607010020
-
-
merra2 2x25 - complexSOA 2016070100 201607010020
-
geosfp 4x5 - complexSOA_SVPOA 2016070100 201607010020
-
merra2 4x5 - complexSOA_SVPOA 2016070100 201607010020
-
-
merra2 2x25 - complexSOA_SVPOA 2016070100 201607010020
-
# ======= Acid uptake on dust
================================================
geosfp 4x5 - aciduptake 2016070100 201607010020
-
-
# ======= Marine POA
=========================================================
geosfp 4x5 - marinePOA 2016070100 201607010020
-
-
# ======= TOMAS aerosol microphysics
=========================================
geosfp 4x5 - TOMAS15 2016070100 201607010030
-
geosfp 4x5 - TOMAS40 2016070100 201607010030
-
# ======= RRTMG online radiative transfer
====================================
geosfp 4x5 - RRTMG 2016070100 201607010040
-
merra2 4x5 - RRTMG 2016070100 201607010040
-
# geosfp 2x25 - RRTMG 2016070100 201607010040
-
# merra2 2x25 - RRTMG 2016070100 201607010040
-
# ======= Nested model runs
==================================================
merra2 05x0625 as tropchem 2016070100 201607010020
-
merra2 05x0625 na tropchem 2016070100 201607010020
-
geosfp 025x03125 ch tropchem 2016070100 201607010010
-
geosfp 025x03125 na tropchem 2016070100 201607010010
-
!END OF RUNS:
#EOP
#--------------------------------------------------------------------------
----
The INPUTS section

Under the !INPUTS: section, you can customize the directory paths and other options for your
system. As seen above, most of these inputs are self-explanatory.
Option DescriptionMet field type
VERSION An ID tag that will be added to all log files and output files.
DESCRIPTION A short (1-sentence) description of what features are being

validated by this unit test.
DATA_ROOT Specifies the path for your root-level data directory.
HEMCO_ROOT Specifies the top-level path for the HEMCO data directory tree.
 The {DATAROOT} token in HEMCO_ROOT will be replaced with the
value you specify for RUN_ROOT option. Leave this as-is.
VERBOSE Specifies the level of debug output that will be sent to the
HEMCO log file. (0=no debug output; 3=max debug output)
 Recommended setting: 0
WARNINGS Specifies the level of warning messages that will be sent to the
HEMCO log file. (0=no warnings; 3=max warnings)
CODE_DIR Specifies the path of the source code directory.
MAKE_CMD Specifies the make command for your system. Usually this
is make, but on some systems this may be gmake. Recommended
options are:
 BOUNDS=y: Turns on array-out-of-bounds checking

 DEBUG=y: Turns off optimization and enables features that will
facilitate running GEOS-Chem in a debugger (if need be). Will
cause GEOS-Chem to check for array temporaries. Also
enables program traceback.
 NO_ISO=y: Disables the ISORROPIA aerosol thermodynamical
equilibrium module, which is known to produce random
numerical noise.
 FPEX=y: Turns on checks for floating-point issues (div-by-zero,
floating invalid, underflow, overflow, etc).
 BPCH_DIAG=y: Turns on the bpch diagnostics. This option is
turned on by default in GEOS-Chem v11-02.
 NC_DIAG=y: Turns on netCDF diagnostics. By default, this will
prevent the bpch diagnostic code from being compiled into
the GEOS-Chem executable.
 NOTE: we recommend compiling with
either BPCH_DIAG=y or NC_DIAG=y, but not both.
SUBMIT Specifies the command that will send the Unit Test job to your
queue system.
 If you don't have a queue system, leave this blank, and the
Unit Tester will run interactively.
UNIT_TEST_ROOT Specifies the path to the GEOS-Chem Unit Tester.
RUN_ROOT Specifies the top-level unit test run directories.
Leave this as-is.
RUN_DIR Specifies the run directory subdirectory.
 The {RUNDIR} token in RUN_DIR will be replaced with the

name of a subdirectory.
Leave this as-is.
JOB_DIR Specifies the directory where the unit test job script will be
created.
Leave this as-is.
LOG_DIR Specifies the directory where log files from this unit test
simulation will be sent.
 The {VERSION} token in LOG_DIR will be replaced with the

value of VERSION that you specify above. This allows the Unit
Tester to send log files from different unit tests to
subdirectories of LOG_DIR. This will let you preserve older log
files.
PERL_DIR Specifies the directory where the unit test Perl scripts are found.
 Leave this as-is.

TEMPLATE Specifies the template HTML file that will be used to create a
web page with unit test results.
 Leave this as-is.

TXT_GRID Specifies the path of this summary text file
 The {LOGDIR} token in TXT_GRID will be replaced with the

value of LOG_DIR. Leave this as-is.
 The {VERSION} token in TXT_GRID will be replaced with the
value of VERSION that you specify above. Leave this as-is.
WEB_GRID Specifies the name of the web page that will contain the unit test
results.
 This web page is created from the template HTML file

specified with the TEMPLATE option.
 The {LOGDIR} token in WEB_GRID will be replaced with the
value of LOG_DIR. Leave this as-is.
 The {VERSION} token in WEB_GRID will be replaced with the
value of VERSION that you specify above. Leave this as-is.
WEB_PUSH Specifies the remote server to which the WEB_GRID web page will
be uploaded. Options are:
 NONE: Donot upload the page

 user@host|directory/: Specifies the remote directory.
(Example: geoschem@fas.harvard.edu|public_html/ut/)
The following commands are optional.

Most of these options are used to schedule the unit test jobs with the SLURM
scheduler.
If your computer cluster does not use SLURM, you can comment all of these
settings out in the UnitTest.input file.
SLURM_CPUS Specifies the number of CPUs that will be used for the unit test
(with #SBATCH -c)
SLURM_NODES Specifies the number of nodes that will be used for the unit test
(with #SBATCH -n)
 NOTE: For GEOS-Chem "Classic" simulations, this should

always = 1.
SLURM_TIME Specifies the requested time for the run. Recommended
format: DD-HH:MM
SLURM_MEM Specifies the total amount of memory (in MB) needed to run the
unit tests.
 NOTE: If you are going to run 2° x 2.5° and/or nested-grid unit

tests, then pick a high number like 30000 MB = 30 GB.
SLURM_PARTITION Specifies the partition (aka queue) in which the unit tests will run
(with #SBATCH -p).
SLURM_CONSTRAINT Allows you to restrict the unit test job to CPUs of a specific type
(with #SBATCH --constraint=. For example
 intel will restrictthe unit test job to Intel CPUs

 haswell will restrict the unit test job to Intel CPUs of type
"haswell"
 broadwell will restrict the unit test job to Intel CPUs of type
"broadwell"
SLURM_MAILTYPE Specifies when you would like to receive updates from the
SLURM scheduler (with #SBATCH --mail-type=).
 The most common option is END, which notifies you when the
unit test job ends. You can also use ALL which will send you
an email when the job starts, ends, and if it dies prematurely.
SLURM_MAILUSER Specifies the email address (with #SBATCH --mail-user=) where
notifications from SLURM will be sent.
SLURM_STDOUT Specifies the file that contains the redirected "stdout" stream
(i.e. echo-back of commands to the screen).
 Normally this is: {LOGDIR}/{VERSION}.stdout.log

SLURM_STDERR Specifies the file that contains the redirected "stderr" stream (i.e.
echo-back of error messages to the screen).
 NOTE: If the unit test fails, you should check this file first to
see what the specific error messages were.
INIT_COMMANDS Specify can specify any additional commands that are specific to
your computer system. For example, you might need to source a
.bashrc file, or to issue a command to load modules. You can
leave this commented out otherwise.
Note that you can use a symbolic link (i.e. /home/{USER}/UT/ in

the RUN_ROOT, RUN_DIR, JOB_DIR, LOG_DIR and PERL_DIR variables. This can help you
shorten the file paths.
The RUNS section
Under the !RUNS: section, you will list each of the combinations that you want the GEOS-Chem
Unit Tester to validate. Simply list the following information under the proper column heading.
Lines starting with # will be ignored.
# !RUNS:
# Specify the debugging runs that you want to perform below.
# You can deactivate runs by commenting them out with "#".
#
#--------|-----------|------|----------------|------------|--------------|-
----|
# MET | GRID | NEST | SIMULATION | START DATE | END DATE
|EXTRA|
#--------|-----------|------|----------------|------------|--------------|-
----|
geosfp 4x5 - benchmark 2016070100 201607010020
-
geosfp 4x5 - RnPbBe 2016010100 201601010020
-
geosfp 4x5 - Hg 2016010100 201601010020
-
geosfp 4x5 - tagHg 2016010100 201601010020
-
geosfp 4x5 - POPs 2016070100 201607010020
-
geosfp 4x5 - CH4 2016070100 201607010020
-
geosfp 025x03125 na CH4 2016070100 201607010010
-
geosfp 4x5 - tagO3 2016070100 201607010020
-
geosfp 4x5 - tagCO 2016070100 201607010020
-
geosfp 2x25 - CO2 2016070100 201607010020
-
geosfp 4x5 - aerosol 2016070100 201607010020
-
-
-
-
-
-
-
geosfp 4x5 - TOMAS15 2016070100 201607010030
-
geosfp 4x5 - TOMAS40 2016070100 201607010030
-
geosfp 4x5 - RRTMG 2016070100 201607010040
-
geosfp 025x03125 ch tropchem 2016070100 201607010010
-
geosfp 025x03125 na tropchem 2016070100 201607010010
-
!END OF RUNS:
#EOP
#--------------------------------------------------------------------------
----
NOTE: For clarity, only simulations using GEOS-FP meteorology have been shown above. You
can also schedule simulations using MERRA-2 meteorology.
Options:
MET
Specifies the met field type. Allowable values are:
Value Met field type
geosfp Selects the GEOS-FP met fields.
merra2 Selects the MERRA-2 met fields.
GRID
Specifies the horizontal grid. Allowable values are:
Value Grid type
4x5 Selects the GMAO 4° x 5° horizontal grid.
2x25 Selects the GMAO 2° x 2.5° horizontal grid.
05x0666 Selects the GMAO 0.5° x 0.666° grid for use with GEOS-5 met
fields only.
(You must also specify a value for NEST.)
05x0625 Selects the GMAO 0.5° x 0.625° grid for use with MERRA-2 met
fields only.
025x03125 Selects the GMAO 0.25° x 0.3125° grid for use with GEOS-FP met
fields only.
NEST
Specifies the nested grid. May only be used if the value
for GRID is 05x0625 or 025x03125. Allowable values are:
Value Nested grid option
- Skips the nested grid option (default). Use this for global
simulations.
as Selects the Asia (AS) nested grid option for use with MERRA-2 met
fields only.
ch Selects the China (CH) nested grid option for use with GEOS-
FP met fields only.
eu Selects the Europe (EU) nested grid option.
na Selects the North American (NA) nested grid option.
SIMULATION
Specifies the simulation type. Allowable values are:
Value Simulation
Full-chemistry simulations
benchmark Selects the Benchmark chemistry

mechanism used in the GEOS-Chem benchmark
simulations. This is the Standard chemistry
mechanism, plus both complex SOA and simple
SOA.
standard Selects the Standard chemistry mechanism.
tropchem Selects the The NOx-Ox-HC-Aer-Br tropospheric

chemistry simulation.
complexSOA Selects the Secondary organic

aerosols simulation, without semi-volatile POA.
complexSOA_SVPOAa Selects the Secondary organic

aerosols simulation, with semi-volatile POA.
aciduptake Selects the Standard chemistry simulation,

with acid uptake on dust aerosols turned on.
marinePOA Selects the Standard chemistry simulation,

with marine primary organic aerosols turned on.
RRTMG Selects the The NOx-Ox-HC-Aer-Br tropospheric

chemistry simulation, with RRTMG turned on.
Specialty simulations
RnPbBe Selects the Radon-Lead-Beryllium simulation. A

passive species is also included in this simulation
by default.
Hg Selects the Mercury simulation.
tagHg Selects the Tagged mercury simulation.
POPs Selects the Persistent Organic Pollutants (POPs)

simulation.
CH4 Selects the CH4 simulation.
tagCO Selects the Tagged CO simulation.
tagO3 Selects the Simple tagged O3 simulation (w/ 2

tracers: Total O3 and Stratospheric O3).
CO2 Selects the CO2 simulation.
TOMAS15 Selects the TOMAS aerosol

microphysics simulation with 15 size bins.
TOMAS40 Selects the TOMAS aerosol

microphysics simulation with 40 size bins.
START DATE
Specifies the start date (YYYYMMDD) and hour (hh) of the unit test.
END DATE
Specifies the ending date (YYYYMMDD), hour (hh), and minutes (mm) of the unit test.
 In most cases, a 1-hour simulation is sufficient to detect bugs.

 For unit tests at 2° x 2.5° resolution or higher, you can end the simulation after one
timestep, which is less than an hour.
EXTRA?
Specifies any simulation-specific Makefile options that need to be set at compile time for
a particular simulation. Typical values are:
Further notes about the !RUNS section:
1. We typically run
from 2016070100 to 2016070101 for GEOS-
FP and MERRA-2 met fields.
2. The actual year for the met fields does not matter so much
for the unit tests. The unit tests runs the same simulation
twice (with and without parallelization) and then tests for
identical results.
Running the GEOS-Chem Unit Tester
Once you have added your desired options to the input file, you
may then proceed to start the GEOS-Chem Unit Tester. At the Unix
prompt, type:
cd perl
./gcUnitTest FILENAME
where FILENAME is the name the input file (e.g. UnitTest.input)

that you have just edited. The settings in the input file will be used in
the Unit Test simulations. If FILENAME is omitted, then
the gcUnitTest script will use UnitTest.input by default.
You will usually want the Unit Test simulations to run in a queue on
your computational cluster. For example, you can set up a Unit Test
job to run overnight. The GEOS-Chem Unit Tester will compile and
run the code for each of the types of simulations that you specified
in the input file. The Unit Tester will compile and run GEOS-Chem
twice for each type of simulation (once with OpenMP parallelizaton
turned off, and again with OpenMP parallelization turned on). Then
the Unit tester will check to see if the output files from both
simulations are identical.
Log-file output generated by the GEOS-Chem Unit Tester is sent to
the logs/{VERSION} directory, where {VERSION} denotes the
version tag that you assigned in the input file. (This allows you to
preserve log file output from several previous Unit Test simulations.)
Examining the results

Output files written to each unit test run directory
The GEOS-Chem Unit Tester will run GEOS-Chem simulations in
the subdirectories of the runs/ directory. Each individual
subdirectory of runs/ corresponds to a particular unit test, or
combination of met field + horizontal grid + simulation type. Some
example run directory names are:
runs/4x5_tropchem # Run dir for 4x5 "tropchem"

simulations (both GEOS-FP and MERRA-2)
runs/2x25_CO2 # Run dir for 2x25 "CO2"
simulations (both GEOS-FP and MERRA-2)
runs/4x5_RnPbBe # Run dir for 4x5 grid "Rn-Pb-
Be" simulations (both GEOS-FP and MERRA-2)
etc.
etc. In each of these run directories, GEOS-Chem will create

several output files containing tracer concentrations and diagnostic
quantities. These files are:
Descriptio
File Notes
n
GEOSChem_restart.*.sp Restart file Includes all species

containing (advected and
instantane non-advected).
ous
For a complete list
species of GEOS-Chem
concentrat species, please
ions at the see our Species in
end of the GEOS-Chem wiki
page.
single-
processor
test.
GEOSChem_restart.*.mp Restart file

containing
species
concentrat
ions at the
end of the
multi-
processor
test.
HEMCO_restart.*.sp Restart file The HEMCO

generated restart archive
by HEMCO certain emissions
at the end quantities (such as
of the soil NO deposition)
single that need to be
processor preserved
test. between multiple
stages of a long
HEMCO_restart.*.mp Restart file GEOS-Chem
generated simulation.
by HEMCO
at the end
of the
multi-
processor
test
HEMCO_diagnostics.*.sp netCDF The HEMCO_Diagn.r

file c input file
containing (located in each
diagnostic run directory)
s archived specifies which
by quantities from
HEMCO, HEMCO will be
from the archived as
single- diagnostic output.
processor
For more
test. information, please
see
HEMCO_diagnostics.*.mp netCDF the the Diagnostics
file section of The
HEMCO User's
containing
Guide.
diagnostic
s archived
by
HEMCO,
from the
multi-
processor
test.
HEMCO.log.sp HEMCO The HEMCO.log*

log file files contains
generated detailed "echo-
by the back" information
single- about the creation
processor of the HEMCO
test. diagnostic
containers and I/O
HEMCO.log.mp HEMCO processes.
log file
These files are not
generated scanned by the
by the GEOS-Chem Unit
multi- Tester. If a unit test
processor fails, you should
look at these
test.
HEMCO.log* files
to determine if an
error occurred in
emissions.
If you specified bpch diagnostic output (with BPCH_DIAG=y),

the following files will be created:
trac.avg.*.sp Binary For a list of

punch available
(bpch) diagnostics, please
format file see our List of
containing diagnostics
diagnostic archived to bpch
output format wiki page.
from the
the single-
processor
test.
trac.avg.*.mp Binary
punch
(bpch)
format file
containing
diagnostic
output
from the
the multi-
processor
test.
If you specified netCDF diagnostic output

(with NC_DIAG=y), the following files will be created:
GEOSChem.*.YYYYMMDD_hhm netCDF One file will be

mz.nc4.sp
files created for each
containing diagnostic
diagnostic collection that is
output specified in
from the the HISTORY.rc inp
single- ut file.
processor
For a list of
test. diagnostic
collections, please
GEOSChem.*.YYYYMMDD_hhm netCDF see our List of
mz.nc4.mp diagnostics
files
archived to
containing
netCDF
diagnostic format wiki page.
output
from the
multi-
processor
test.

Log files written to the unit test log directory
The GEOS-Chem Unit Tester will also create a series of log files in
the logs/{VERSION} directory, where {VERSION} is specifed in
the The !INPUTS section of the unit test input file. These log files
are:
File Description Notes

{VERSION}.stderr.log File You
(SLURM scheduler) containing normally
the won't
job.{VERSION}.o*
Unix stderr o have to
(GridEngine scheduler)
utput. All look at
error and this file,
warning unless a
messages will particular
get sent to simulatio
this file. This n dies
is created if unexpect
you run the edly. The
Unit Tester in output
the Oracle containe
Grid Engine d can be
queue very
system. useful in
determin
ing
where
the error
ocurrred.
{VERSION}.stdout.log File In most

containing cases you
the will not
Unix stdout o need to
utput. look at
this file.
{VERSION}.results.log Log file

containing
the results
from each
individual
unit test
simulation
that you ran.
More
information
on this file is
contained
below.
{VERSION}.results.html Web page

(HTML)
containing a
graphical
representatio
n of the unit
test results.
More
information
on this file is
contained
below.
{VERSION}.results.txt Text file

containing a
table
representatio
n of the unit
test results.
More
information
on this file is
contained
below.
{VERSION}.{MET}_{GRID}_{SIM}. GEOS-Chem
log.sp
log file
(Global simulations)
output from
{VERSION}.{MET}_{GRID}_{SIM}_ the single-
{NEST}.log.sp processor
(Nested-grid simulations) test phase of
the unit test
for the given
met field,
grid,
simulation
type (and, if
applicable,
nested-grid
region).
{VERSION}.{MET}_{GRID}_{SIM}. GEOS-Chem
log.mp
log file
(Global simulations)
output from
{VERSION}.{MET}_{GRID}_{SIM}_ the multi-
{NEST}.log.mp processor
(Nested-grid simulations) test phase of
the unit test
for the given
met field,
grid,
simulation
type (and, if
applicable,
nested-grid
region).

Unit test results and error messages
The {VERSION}.results.log file will contain printout similar to
the following. Looking at this file will tell you if the output from
the sp and mp test phases of each unit test simulation were
identical to each other, or if they differed.
If you compiled with BPCH_DIAG=y then your results file will look
similar to this:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%
%%% GEOS-CHEM UNIT TEST RESULTS FOR VERSION:
BpchOnly_Mar19
%%% job sent to queue @ 2018/03/19 14:17:43
%%%
%%% DESCRIPTION: c40ec4d Restructure calculation of
binned dust AOD diag to avoid seg fault in GCHP
%%%
%%% BUILT WITH: make -j8 BOUNDS=y DEBUG=y FPEX=y
NO_ISO=y BPCH_DIAG=y NC_DIAG=n
%%%
%%% This is the main log file, which shows output
from
%%% each individual phase of the unit test
sequence.
%%%
%%% Log files from individual unit-test runs are
also
%%% stored in this same directory.
%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%
####################################################
###########################
### VALIDATION OF GEOS-CHEM OUTPUT FILES
### Run ID: geosfp_4x5_RnPbBe
##@
### IDENTICAL :
GEOSChem_restart.201607010020.nc.{sp,mp}
### IDENTICAL :
HEMCO_diagnostics.201607010000.nc.{sp,mp}
### IDENTICAL :
HEMCO_restart.201607010020.nc.{sp,mp}
### IDENTICAL :
trac_avg.geosfp_4x5_RnPbBe.201607010000.{sp,mp}
##%
####################################################
###########################
... etc ...
If, on the other hand, you compiled with NC_DIAG=y then your
results file will look similar to this:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%
%%% GEOS-CHEM UNIT TEST RESULTS FOR VERSION:
Nc_Mar19
%%% job sent to queue @ 2018/03/19 14:17:43
%%%
%%% DESCRIPTION: c40ec4d Restructure calculation of
binned dust AOD diag to avoid seg fault in GCHP
%%%
%%% BUILT WITH: make -j8 BOUNDS=y DEBUG=y FPEX=y
NO_ISO=y BPCH_DIAG=n NC_DIAG=y
%%%
%%% This is the main log file, which shows output
from
%%% each individual phase of the unit test
sequence.
%%%
%%% Log files from individual unit-test runs are
also
%%% stored in this same directory.
%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%
####################################################
###########################
### VALIDATION OF GEOS-CHEM OUTPUT FILES
### Run ID: geosfp_4x5_RnPbBe
##@
### IDENTICAL :
GEOSChem.CloudConvFlux.20130701_0000z.nc4.{sp,mp}
### IDENTICAL :
GEOSChem.DryDep.20130701_0000z.nc4.{sp,mp}
### IDENTICAL :
GEOSChem.LevelEdgeDiags.20130701_0000z.nc4.{sp,mp}
### IDENTICAL :
GEOSChem.RadioNuclide.20130701_0000z.nc4.{sp,mp}
### IDENTICAL :
GEOSChem.SpeciesConc.20130701_0000z.nc4.{sp,mp}
### IDENTICAL :
GEOSChem.StateMet.20130701_0000z.nc4.{sp,mp}
### IDENTICAL :
GEOSChem.WetLossConv.20130701_0000z.nc4.{sp,mp}
### IDENTICAL :
GEOSChem.WetLossLS.20130701_0000z.nc4.{sp,mp}
### IDENTICAL :
GEOSChem_restart.201307010020.nc.{sp,mp}
### IDENTICAL :
HEMCO_diagnostics.201307010000.nc.{sp,mp}
### IDENTICAL :
HEMCO_restart.201307010020.nc.{sp,mp}
##%
####################################################
###########################
Possible outcomes for each set of files being compared are:
Outcome Description
IDENTICAL This means that the corresponding .sp and

*.mp files being compared against each other
are 100% bitwise identical.
DIFFERENT This means that the corresponding *.sp. and

*.mp files being compared against each other
differ in some way.
MISSING This means that one of the corresponding *.sp

or *.mp files could not be found in the unit test
run directory.
The {VERSION}.stderr.log will contain any detailed error

messages (such as error traceback output). Check this if your unit
tests have halted unexpectedly.
How unit tests are scored
The following criteria are used to score GEOS-Chem unit tests:
Result Criteria
PASS  All corresponding pairs of {*.sp, *.mp} restart files are
IDENTICAL, and
 All corresponding pairs of {*.sp, *.mp} diagnostics
files are IDENTICAL
PASS WITH  All corresponding pairs of {*.sp, *.mp} restart files are
WARNINGS IDENTICAL, but
 One or more corresponding pairs of {*.sp, *.mp}
diagnostics files are DIFFERENT
FAIL  One or more corresponding pairs of {*.sp, *.mp}
restart files are DIFFERENT
 Any *.sp or *.mp restart file is MISSING
 Any *.sp or *.mp diagnostics file is MISSING

Unit test results displayed as a web page
The GEOS-Chem Unit Tester will also create a web page that summarizes the
results in an easy-to-read table. The name of the web page is specified with
the WEB_GRIDoption in the !INPUTS: section of the unit test input file. The web
page will contain output similar to this example:
GEOS-Chem Unit Test Results

Version: BpchOnly_Mar19
Date
2018/03/19 14:17:43
Submitted:
c40ec4d Restructure calculation of binned
Description:
dust AOD diag to avoid seg fault in GCHP
Compiled make -j8 BOUNDS=y DEBUG=y FPEX=y NO_ISO=y
BPCH_DIAG=y NC_DIAG=n
with:
co R
T
St mp A M n A
ro co R
Uni a lex ci ari - e TO TO
p mp R Ta P Ta Ta C C
t n- SO d ne P H r- M M
c lex T gH O gC gO H O
Tes d A- U P b g o AS AS
h SO M g Ps O 3 4 2
ts ar SV pt O - s 15 40
e A G
d PO k A B ol
m
A e
ME
RR
A-2
@
4° x
5°
GE
OS-
FP
@
4° x
5°
ME
RR
A-2
@
2° x
2.5°
GE
OS-
FP
@
2° x
2.5°
Benchmark Bench
Unit Tests mark
GEOS-FP @ 4° x 5°
<td width="40"> </td>
Nested-
Trop
LEGEND
Grid CH4 Hg
chem The unit test was successful.
Unit Tests
GEOS-FP Further investigation is necessary (e.g.
NA @ The restart files were identical but the
0.25° x diagnostic output differed).
0.3125°
The unit test failed.
GEOS-FP
CH @ A unit test was not performed for this
0.25° x combination of met field, horizontal
0.3125° grid, and simulation type.
MERRA-2
NA @
0.5° x
0.625°
MERRA-2
AS @
0.5° x
0.625°

Unit test results displayed as a text file
The GEOS-Chem Unit Tester will also send a simple text summary of the unit
test results to a file named {VERSION}.results.txt in the log directory.
(NOTE: {VERSION}will be overwritten with the version string that you specified
in the UnitTest.input file.) The file will contain output similar to this:
GEOS-Chem Unit Test : RESULT

------------------------------------------
geosfp_4x5_RnPbBe : GREEN
merra2_4x5_RnPbBe : GREEN
... etc ...
Cleaning old files

To clean all of the files created by the unit tester (job scripts, logs, bpch files),
type:
cd perl
./cleanFiles
Editing the CopyRunDirs.input file

Once you have downloaded the GEOS-Chem Unit Tester to your disk space,
switch to the perl/ directory:
cd UT/perl
In this directory there is a Perl script named gcCopyRunDirs that you will use to
generate fresh copies of GEOS-Chem run directories. This script uses an
input file named CopyRunDirs.input, which is also located in the perl directory.
IMPORTANT: The CopyRunDirs.input file that comes with the Unit Tester
provides only a small sample of the possible run directories that you can
create. You can add as many entries to the RUNS section as you wish. See
the UnitTest.input file for a complete list of all possible run directories that you
can add to CopyRunDirs.input.
Your CopyRunDirs.input file will look something like this:
#--------------------------------------------------------
----------------------
# GEOS-Chem Global Chemical Transport
Model !
#--------------------------------------------------------
----------------------
#BOP
#
# !DESCRIPTION: Input file that specifies configuration
for creating and
# copying a run directory from the UnitTester.
#\\
#\\
# !REMARKS:
# For a complete description of how to customize the
settings in the
# INPUTS and RUNS sections, see the following wiki
posts:
#
# wiki.geos-chem.org/Creating_GEOS-
Chem_run_directories#Section_1:_INPUTS
# wiki.geos-chem.org/Creating_GEOS-
Chem_run_directories#Section_2:_RUNS
#
# 18 Mar 2015 - R. Yantosca - Initial version
# 19 Mar 2015 - E. Lundgren - Simplify content for only
copying run dirs
# 19 May 2015 - R. Yantosca - Now can specify VERBOSE
and WARNINGS options
#EOP
#--------------------------------------------------------
----------------------
#
# !INPUTS:
#
# %%% ID tags %%%
#
VERSION : v11-01
DESCRIPTION : Create run directory from UnitTest
#
# %%% Data path and HEMCO settings %%%
#
DATA_ROOT : /n/holylfs/EXTERNAL_REPOS/GEOS-
CHEM/gcgrid/data/ExtData
HEMCO_ROOT : {DATAROOT}/HEMCO
VERBOSE : 0
WARNINGS : 1
#
# %%% Unit tester path names %%%
#
UNIT_TEST_ROOT : {HOME}/UT
RUN_ROOT : {UTROOT}/runs
RUN_DIR : {RUNROOT}/{RUNDIR}
PERL_DIR : {UTROOT}/perl
#
# %%% Target directory and copy command %%%
#
COPY_PATH : {HOME}/GC/rundirs
COPY_CMD : cp -rfL
#
# !RUNS:
# Specify the runs directories that you want to copy
below.
# Here we provide a few examples, but you may copy
additional entries from
# UnitTest.input and modify the dates as needed. You can
deactivate copying
# run certain directories by commenting them out with
"#".
#
#--------|-----------|------|------------|------------|--
----------|---------|
# MET | GRID | NEST | SIMULATION | START DATE |
END DATE | EXTRA? |
#--------|-----------|------|------------|------------|--
----------|---------|
geosfp 4x5 - standard 2013070100
2013080100 -
# geosfp 4x5 - gc_timing 2013070100
2013070800 -
# geosfp 4x5 - tropchem 2013070100
2013070101 -
# geosfp 4x5 - soa 2013070100
2013070101 -
# geosfp 4x5 - soa_svpoa 2013070100
2013070101 -
# geosfp 4x5 - aciduptake 2013070100
2013070101 -
# geosfp 4x5 - UCX 2013070100
2013070101 -
# geosfp 4x5 - RRTMG 2013070100
2013070101 -
# geosfp 4x5 - RnPbBe 2013070100
2013070101 -
# geosfp 4x5 - Hg 2013010100
2013010101 -
# geosfp 4x5 - POPs 2013070100
2013070101 -
# geosfp 4x5 - TOMAS40 2013070100
2013070101 -
# geosfp 4x5 - CH4 2013070100
2013070101 -
# geosfp 4x5 - tagO3 2013070100
2013070101 -
# geosfp 4x5 - tagCO 2013070100
2013070101 -
# geosfp 2x25 - CO2 2013070100
201307010030 -
# geosfp 4x5 - aerosol 2013070100
2013070101 -
# geosfp 025x03125 ch tropchem 2013070100
201307010010 -
# geosfp 025x03125 na tropchem 2013070100
201307010010 -
# gchp 4x5 - tropchem 2013070100
2013070101 -
!END OF RUNS:
#EOP
#--------------------------------------------------------
----------------------
NOTE: Lines starting with a # character will be treated as comments.

The CopyRunDirs.input file has a layout that is very similar to the GEOS-Chem
Unit Tester input files (UnitTest.input located within this directory). Like the
GEOS-Chem Unit Tester input files, CopyRunDirs.input is composed of
an INPUTS section and a RUNS section, which are described below.
Section 1: INPUTS
Under the INPUTS section, you can customize the directory paths and other
options for your system. Each configurable input is described in the table
below.
Option Description
VERSION An ID tag that will be added to all log files and output files.
DESCRIPTION A short (1-sentence) description of the purpose of this specific
file (optional). This may be used to differentiate different input
files, such as if you pre-configure several for future re-use.
DATA_ROOT Specifies the path for your root-level data directory.
HEMCO_ROOT Specifies the top-level path for the HEMCO data directory
tree.
 The {DATAROOT} token in HEMCO_ROOT will be replaced with

the value you specify for RUN_ROOT option.
Leave this as-is.
VERBOSE Specifies the level of debug output that will be sent to the
HEMCO log file. (0=no debug output; 3=max debug output)
WARNINGS Specifies the level of warning messages that will be sent to
the HEMCO log file. (0=no warnings; 3=max warnings)
UNIT_TEST_ROOT Specifies the path to the GEOS-Chem Unit Tester.
RUN_ROOT Specifies the top-level unit test run directories.
Leave this as-is.
RUN_DIR Specifies the run directory subdirectory.

Leave this as-is.
PERL_DIR Specifies the directory where the unit test Perl scripts are
found.
Leave this as-is.
COPY_PATH Specifies the directory on your disk server where copies of the
GEOS-Chem run directories will be created.
COPY_CMD Specifies the command used to copy run directories from the
GEOS-Chem Unit Tester to COPY_PATH.
 The default setting is cp -rfL. This will create a new copy

of the directory, even if the prior copy exists.
 The -L option to the cp will create "hard" copies of files that
are symbolic links. This command may differ slightly
depending on the flavor of your Unix-based Operating
system.
Section 2: RUNS
The layout of the RUNS section is identical to the RUNS section in the GEOS-
Chem Unit Tester input file. This enables copying and pasting simulation
settings text from UnitTest.input into CopyRunDirs.input.
For example, the following line:
#
# !RUNS:
# Specify the debugging runs that you want to perform
below.
# You can deactivate runs by commenting them out with
"#".
#
#--------|-----------|------|------------|------------|--
----------|---------|
# MET | GRID | NEST | SIMULATION | START DATE |
END DATE | EXTRA? |
#--------|-----------|------|------------|------------|--
----------|---------|
2013080100 -
will tell the gcCopyRunDirs script to create a run directory for a GEOS-Chem
simulation with the following settings:
 Using GEOS-FP met fields

 On the 4° x 5° GEOS-Chem horizontal grid
 For the GEOS-Chem standard full-chemistry simulation
 Starting at 00:00 GMT on 2013/07/01
 Ending at 00:00 GMT on 2013/08/01
The date range will be used to initialize the input.geos file that is read during a
GEOS-Chem simulation. Once the run directory is created, you may edit these
dates within the input.geos file. Note, however, that time ranges must remain
within the time range covered by the MET field you are using. You can check
the MET field temporal coverage on the GMAO met data products wiki
page. Also note that we recommend using the restart files to spin up
GEOS-Chem for at least one year prior to your simulation start date. You
may use the resulting output restart files as initial values for your
simulation.
You can add as many entries to the RUNS section as you wish. See
the UnitTest.input file for a complete list of all possible run directories entries
that you can add to CopyRunDirs.input.
Generating a GEOS-Chem Run Directory

Once you have edited the CopyRunDirs.input script to your liking, you can use
that to generate fresh copies of GEOS-Chem run directories. Make sure you
are in the perl directory, and then type:
./gcCopyRunDirs
If you do not pass a file name to gcCopyRunDirs, then the gcCopyRunDirs script
will use the CopyRunDirs.input file that you just modified.
If you wish, you can create many customized copies of CopyRunDirs.input. For
example, suppose you edit CopyRunDirs.input to generate a full-chemistry run
directory. You can then save it as a separate file and use it explicitly
with gcCopyRunDirs.
cp CopyRunDirs.input CopyRunDirs.fullchem # Input file
set up to only copy the full-chemistry run directories
gcCopyRunDirs CopyRunDirs.Hg
Executing gcCopyRunDirs will create a new GEOS-Chem run directory

corresponding to each entry that you specified in the input file RUNS section.
Each run directory will be created as a subdirectory of COPY_PATH that you
specified in the input file INPUTS section.
Let's examine the contents of a sample geosfp_4x5_standard run directory.
Navigate to your newly created run directory and tssue the following
commands:
make fileclean # Remove any files

left over from previous unit test runs
ls -1 # Get directory
listing
And you will see this directory listing:
brc.dat
dust.dat
FJX_j2j.dat
FJX_spec.dat
getRunInfo
h2so4.dat
HEMCO_Config.rc
HEMCO_restart.201307010000.nc
input.geos
jv_spec_mie.dat
Makefile
org.dat
output/
README
so4.dat
soot.dat
ssa.dat
ssc.dat
v11-01.run
validate
NOTE: Run directories for other simulations may contain other files not
pictured here.
The input.geos and HEMCO_Config.rc files have been customized for this
particular simulation. They were created from the corresponding template
files input.geos.template and HEMCO_Config.template in the Unit Tester. The
Perl script getRunInfo is used by the Makefile to extract information about the
simulation from input.geos. HEMCO and tracer restart files are also included
in every run directory but care must be taken when using them. See the
section below for more information about restart files.
Available run directories

Benchmark run directory
The GEOS-Chem Unit Tester includes a run directory
called 4x5_standard (GEOS-Chem v11-01 and later)
or geosfp_4x5_benchmark (GEOS-Chem v10-01). The standard GEOS-
Chem benchmark simulation utilizes the GEOS-FP met fields (4° x 5 °, 72
levels) with the UCX tropospheric-stratospheric chemistry
mechanism and secondary organic aerosols included.
To reproduce our latest 1-month benchmark simulation for v11-01, you can
edit the CopyRunDirs.input file so that the following line is uncommented
under RUNS:

2013080100 -
Make sure to check the start and end date so that your simulation will run for
July 2013. You can then create the GEOS-Chem benchmark run directory by
typing ./gcCopyRunDirs. Navigate to your the newly
created geosfp_4x5_benchmark run directory. To compile and run your
benchmark simulation, type:
make -j4 mp
To compile only, type:
make -j4 mpbuild
That will create a geos.mp executable file that you can use to submit your
GEOS-Chem benchmark simulation to a queue system.
NOTE: If you are compiling GEOS-Chem within the code directory, and
not within a run directory created from the GEOS-Chem Unit Tester, you
will need to pass the UCX=y option in your make command.

system wiki page.
7. Compiling GEOS-Chem
Prior to running GEOS-Chem, you must compile the source code

using a Fortran-90 compiler in order to create a GEOS-Chem
executable. Compiling GEOS-Chem invokes the GNU Make
utility which manages the entire compilation process. A series of
scripts called makefiles directs GNU Make to compile the GEOS-
Chem source code files in the proper order and with the proper
options. The resultant binary executable has filename geos and is
stored in the/bin and GeosCore/ subdirectories.
The GEOS-Chem source code is partitioned into several

subdirectories and each subdirectory contains its own makefile. You
will usually not have to modify any of the GEOS-Chem source code
makefiles unless you are introducing new modules or module-
dependencies into GEOS-Chem. In those cases, you will need to
add the new modules to the appropriate makefile and update
dependency lists accordingly.
In general there are two types of makefiles:
 Router makefiles: Makefiles that tell GNU Make to look at

makefiles in other directories.
 Regular makefiles: Makefiles that are used by GNU Make to
compile source code programs.
The top-level GEOS-Chem source code directory contains

a router makefile, which calls down to the regular makefiles in the
various subdirectories. In each subdirectory, the regular makefile
tells GNU Make how to compile the source code files. When the
source code in all subdirectories has been compiled, the top-level
Makefile tells GNU Make to create the GEOS-Chem executable file.
For this reason, you must always compile GEOS-Chem from the
top-level source code directory. You may do this either at the
command line within the top-level source code directory or using
another router makefile such as the one that comes with run
directories copied from the GEOS-Chem Unit Test repository.
Please consult the GEOS-Chem Makefile Structure wiki page for

detailed information about GEOS-Chem makefiles and instructions
for compiling GEOS-Chem. Quick links to subsections of this wiki
page are included below:
 Setting Unix environment variables to specify your Fortran

compiler and netCDF library paths
 GEOS-Chem directory structure
 Compilation sequence and information about dependency lists
 Compiling GEOS-Chem from the top-level source code
directory (includes a list of compilation options)
 Compiling GEOS-Chem from a run directory copied from the
Unit Tester (RECOMMENDED)
 Technical issues
You can find more information about GNU Make at the GNU
Operating System website: https://www.gnu.org/software/make/.
Note that executables generally cannot be easily swapped between

computers unless the computers have identical systems. We
therefore recommend that you recompile GEOS-Chem if you decide
to move GEOS-Chem to a different computer.
GEOS-Chem Makefile Structure

On this page we list information about the makefiles used to build the GEOS-Chem executable.
Contents
[hide]
 1 Overview
 2 Directory Structure
o 2.1 GEOS-Chem 12
o 2.2 GEOS-Chem v11-02
 3 Compilation sequence
 4 Compiling GEOS-Chem
o 4.1 Setting the proper environment variables
o 4.2 Ways to compile GEOS-Chem
o 4.3 Compiling in the top-level code directory
 4.3.1 Makefile Options
 4.3.2 Specifying compiler flags
 4.3.3 Setting default flags
 4.3.4 Compiling examples
o 4.4 Compiling in a run directory
 4.4.1 Setting up the run directory Makefile
 4.4.2 Makefile options
 4.4.3 Information from the last time GEOS-Chem was compiled
o 4.5 Advanced compilation techniques
 4.5.1 Compiling with Unix shell scripts
 5 Technical Issues
o 5.1 GNU Make is required
o 5.2 Install LaTeX utilities for auto documentation
o 5.3 Compile-time options that can slow down GEOS-Chem
 6 Previous issues that have now been resolved
o 6.1 Add a more robust test for netCDF-Fortran in Makefile_header.mk
o 6.2 Removed the COMPILER variable from Makefile_header.mk for a
cleaner build sequence
o 6.3 Bug fix: Specifying NO_REDUCED=no now compiles GEOS-Chem for
reduced grids
o 6.4 TRACEBACK=y is now the default setting
o 6.5 Compiler cannot find certain files
 7 References
 8 Obsolete information
o 8.3 Backup files not excluded from compilation
Overview
Starting with GEOS-Chem v8-02-03, we have modified the directory structure of GEOS-Chem.
Rather than keeping all source code files in a single directory, we now have partitioned source
code files into several subdirectories with most subdirectories having their own Makefile. This
was done for the following reasons:
1. To facilitate the installation of 3rd-party software packages such as:
 HEMCO
 RRTMG radiative transfer model
 KPP chemical solver
 Aerosol microphysics codes (e.g. APM)
 ISORROPIA II
 Terrestrial models (e.g. CASA, GTMM)
into GEOS-Chem. Our guiding principle is that all 3rd-party software packages should be
cleanly separable from the main-line GEOS-Chem code. This will allow the 3rd-party
software packages to be updated without having an impact on the rest of the GEOS-
Chem source code files.
2. To simplify the maintenance of the GEOS–Chem code files. Without subdirectories,
there would have been hundreds of source code files in a single directory, and it would
have been very difficult to keep track of them all.
Directory Structure
Here we list the directory structure for recent model versions.
GEOS-Chem 12
The table below lists the directory structure in GEOS-Chem 12 along with
descriptions of each subdirectory and its Makefile (if one is present).
Directory Description Is there a Makefile here?
Code Main-level directory Yes, there are two:

for GEOS-Chem
 Makefile is the main-
level router makefile
and it calls down to the
makefile in GeosCore.
 Makefile_header.mk de
fines compilation and
linking commands for
the Fortran-90
compilers. These
commands are
common to the
makefiles in all
subdirectories.
Code/GTMM Directory containing Yes, it compiles the code
source code files for in GTMM and creates library
the Global Terrestrial file lib/libHg.a
Mercury Model
(GTMM) simulation
Code/GeosCore Directory containing Yes, this is the main

most GEOS-Chem makefile for GEOS-Chem. It
modules and routines calls down to the makefiles
in the other subdirectories.
It then compiles the code
in the GeosCore directory
and creates
the geosexecutable.
Code/GeosRad Directory containing Yes, it compiles the code

source code files for in GeosRad and creates
the RRTMG radiative library file lib/librad.a.
transfer model
Code/GeosUtil Directory containing Yes, it compiles the code

GEOS-Chem utility in GeosUtil and creates
modules library
file lib/libGeosUtil.a.
Code/HEMCO Main-level directory Yes, it calls down to the

for HEMCO makefiles in the other
HEMCO subdirectories.
Code/HEMCO/Core Directory containing Yes, it compiles the code

HEMCO modules and in HEMCO/Core and creates
routines for reading, library file lib/libHCO.a.
storing, and updating
data used for
calculating emissions
Code/HEMCO/Extens Directory containing Yes, it compiles the code

ions HEMCO modules and in HEMCO/Extensions and
routines for calculating creates library
emissions that depend file lib/libHCOX.a.
on meteorological
input variables and/or
non-linear
parameterizations
Code/HEMCO/Interf Directory containing Yes, it compiles the code

aces
HEMCO modules and in HEMCO/Interfaces and
routines that provide creates library
the link between file lib/libHCOI.a.
HEMCO and the model
environment
Code/Headers Directory containing Yes, it compiles the code

module files with fixed in Headers and creates
parameters and library
derived-type file lib/libHeaders.a
definitions
 NOTE: In previous
versions, these files
were header files
that were inlined
via
the #include state
ment. These have
since been
converted to F90
modules in order to
facilitate GEOS-
Chem
HP development.
Code/History Directory containing Yes, it compiles the code
module files to archive in History and creates
diagnostics from GEOS- library
Chem "Classic" file lib/libHistory.a
simulations to netCDF
file format
Code/ISOROPIA Directory containing Yes, it compiles the code

the in ISOROPIA and creates
unmodified ISORROPIA library
II source code files file lib/libIsoropia.a.
from Thanos Nenes
and Havala Pye:
 isoropiaII_main_m
od.F
Code/KPP Main-level directory Yes, it calls down to the

for the KPP chemical makefiles in the other KPP
solver subdirectories.
Code/KPP/Custom Directory containing Yes, if you compile

KPP source code files with CHEM=customit
for the Standard compiles the code
chemistry mechanism in KPP/Custom and creates
library file lib/libKpp.a.
Code/KPP/int Directory containing No

the integrators
(rosenbrock, runge-
kutta, lsodes, etc.) for
KPP
Code/KPP/Standard Directory containing Yes, it compiles the code

KPP source code files in KPP/Standard and
for the Standard creates library
chemistry mechanism file lib/libKpp.a.
Code/KPP/Tropchem Directory containing Yes, it compiles the code

KPP source code files in KPP/Tropchem and
for the Troposphere- creates library
only mechanism file lib/libKpp.a.
Code/KPP/SOA_SVPO Directory containing Yes, it compiles the code

A
KPP source code files in KPP/SOA_SVPOA and
for the SOA or creates library
SOA_SVPOA chemistry file lib/libKpp.a.
mechanisms.
Code/NcdfUtil Directory containing Yes, it compiles the code

source code files for in NcdfUtil and creates
netCDF I/O. This code library
is from Bob Yantosca's file lib/libNcUtils.a.
NcdfUtilities package
Code/NcdfUtil/per Directory containing No

l
perl scripts from the
that can be used to
generate Fortran code
for defining, writing,
and reading a netCDF
file
Code/bin Directory where No

executable
(geos, geostomas, geosa
pm) files will be sent
Code/doc Directory where Yes, it calls the ProTeX

automatic script to create reference
documentation is built manuals (in PS and PDF
formats) from the
comments in GEOS-Chem
module and routine
headers.
Code/help Directory containing Yes, it prints the GEOS-

GEOS-Chem help Chem help screen to
screen stdout
Code/lib Directory where library No

(*.a) files will be
created
Code/mod Directory where No

module (*.mod) files
will be sent

GEOS-Chem v11-02
Please see the section for GEOS-Chem 12.
GEOS-Chem v11-01
The table below lists the directory structure in GEOS-Chem v11-01 along with
descriptions of each subdirectory and its Makefile (if one is present).
Directory Description Is there a Makefile here?
Code Main-level directory Yes, there are two:

for GEOS-Chem
 Makefile is the main-
level router makefile
and it calls down to the
makefile in GeosCore.
 Makefile_header.mk de
fines compilation and
linking commands for
the Fortran-90
compilers. These
commands are
common to the
makefiles in all
subdirectories.
Code/GTMM Directory containing Yes, it compiles the code
source code files for in GTMM and creates library
the Global Terrestrial
Mercury Model file lib/libHg.a
(GTMM) simulation
Code/GeosCore Directory containing Yes, this is the main

most GEOS-Chem makefile for GEOS-Chem. It
modules and routines calls down to the makefiles
in the other subdirectories.
It then compiles the code
in the GeosCore directory
and creates
the geos executable.
Code/GeosRad Directory containing Yes, it compiles the code

source code files for in GeosRad and creates
the RRTMG radiative library file lib/librad.a.
transfer model
Code/GeosUtil Directory containing Yes, it compiles the code

GEOS-Chem utility in GeosUtil and creates
modules library
file lib/libGeosUtil.a.
Code/HEMCO Main-level directory Yes, it calls down to the

for HEMCO makefiles in the other
HEMCO subdirectories.
Code/HEMCO/Core Directory containing Yes, it compiles the code

HEMCO modules and in HEMCO/Core and creates
routines for reading, library file lib/libHCO.a.
storing, and updating
data used for
Code/HEMCO/Extensi Directory containing Yes, it compiles the code

ons
HEMCO modules and in HEMCO/Extensions and
routines for creates library
that depend on file lib/libHCOX.a.
meteorological input
variables and/or non-
linear
parameterizations
Code/HEMCO/Interfa Directory containing Yes, it compiles the code

ces
HEMCO modules and in HEMCO/Interfaces and
routines that provide creates library
the link between file lib/libHCOI.a.
HEMCO and the
model environment
Code/Headers Directory containing Yes, it compiles the code

module files with fixed in Headers and creates
parameters and library
derived-type file lib/libHeaders.a
definitions
 NOTE: In previous
versions, these
files were header
files that were
inlined via
the #include state
ment. These have
since been
converted to F90
modules in order
to facilitate GEOS-
Chem
HP development.
Code/ISOROPIA Directory containing Yes, it compiles the code
the in ISOROPIA and creates
unmodified ISORROPI library
A II source code files file lib/libIsoropia.a.
from Thanos Nenes
and Havala Pye:
 isoropiaIIcode.F
 isrpia.inc
Code/KPP Main-level directory Yes, it calls down to the

for the KPP chemical makefiles in the other KPP
solver subdirectories.
Code/KPP/Standard Directory containing Yes, it compiles the code

KPP source code files in KPP/Standard and
for the Standard creates library
chemistry mechanism file lib/libKpp.a.
Code/KPP/Tropchem Directory containing Yes, it compiles the code

KPP source code files in KPP/Tropchem and
for the troposphere- creates library
only mechanism file lib/libKpp.a.
Code/KPP/SOA Directory containing Yes, it compiles the code

KPP source code files in KPP/SOA and creates
for the SOA chemistry library file lib/libKpp.a.
mechanism
Code/KPP/SOA_SVPOA Directory containing Yes, it compiles the code

KPP source code files in KPP/SOA_SVPOA and
for the SOA chemistry creates library
mechanism with file lib/libKpp.a.
secondary POA.
Code/KPP/UCX Directory containing Yes, it compiles the code

KPP source code files in KPP/UCX and creates
for the UCX chemistry library file lib/libKpp.a.
mechanism
Code/KPP/int Directory containing No

the integrators
(rosenbrock, runge-
kutta, lsodes, etc.) for
KPP
Code/NcdfUtil Directory containing Yes, it compiles the code

source code files for in NcdfUtil and creates
netCDF I/O. This code library
is from Bob Yantosca's file lib/libNcUtils.a.
Code/NcdfUtil/perl Directory containing No

perl scripts from the
that can be used to
generate Fortran code
for defining, writing,
and reading a netCDF
file
Code/bin Directory where No

executable
(geos, geostomas, geos
apm) files will be sent
Code/doc Directory where Yes, it calls the ProTeX

automatic script to create reference
documentation is built manuals (in PS and PDF
formats) from the
comments in GEOS-Chem
module and routine
headers.
Code/help Directory containing Yes, it prints the GEOS-

GEOS-Chem help Chem help screen to stdout
screen
Code/lib Directory where No

library (*.a) files will
be created
Code/mod Directory where No

module (*.mod) files
will be sent
Compilation sequence
GEOS-Chem's makefiles compile source code files in the following order:
1. Files in NcdfUtil/
2. Files in KPP (first pass)
3. Files in Headers/
4. Files in GeosUtil/
5. Files in KPP/ (second pass)
6. Files in History/
7. Files in HEMCO/Core/
8. Files in HEMCO/Extensions/
9. Files in HEMCO/Interfaces/
10. Files in ISOROPIA/
11. Files in GeosRad/ (if RRTMG is enabled)
12. Files in GeosCore/
Each of theses directories has its own makefile that contains a list of all of the
source code files within the directory, plus dependent routines (a.k.a. the
"dependencies" list). Source code files that do not refer to any modules have a
dependencies list such as:
dao_mod.o : dao_mod.F
Whereas a source code file that refers to several modules (in this
case, GeosCore/chemistry_mod.F) has a dependencies list like this:
chemistry_mod.o : chemistry_mod.F90
\
aerosol_mod.o
isoropiaII_mod.o \
c2h6_mod.o
carbon_mod.o \
dust_mod.o
drydep_mod.o \
global_ch4_mod.o
mercury_mod.o \
pops_mod.o
\
rpmares_mod.o
RnPbBe_mod.o \
seasalt_mod.o
strat_chem_mod.o \
sulfate_mod.o
tagged_co_mod.o \
tagged_o3_mod.o tomas_mod.o
\
flexchem_mod.o
Examination of GeosCore/chemistry_mod.F90 reveals that this module refers to

many other modules not listed above. However, many of those modules are found in
different directories (such as Headers/ and GeosUtil/), which are compiled prior
to GeosCore/. Therefore you do not need to list those modules when creating the
dependencies listing. In the example above, we have only specified the 6 modules
that are located in the same directory as aerosol_mod.F.
The order of modules in the dependencies list does not matter. The GNU
Make utility will define the order of compilation from the list of files (and their
dependencies) that you have specified in each Makefile. You will not have to worry
about this unless you add new source code files. If you have questions about how to
add dependency lists to makefiles, please let us know.
Compiling GEOS-Chem
In this section we provide information about how to compile the GEOS-Chem source
code into an executable file that you can run.
Setting the proper environment variables
Before you compile GEOS-Chem, please take a moment to make sure that you have
defined the proper Unix environment variables that tell GEOS-Chem which compiler
you are using, and where the netCDF library has been installed. For complete
information, please see our our Setting Unix environment variables for GEOS-
Chem wiki page.
Ways to compile GEOS-Chem
There are two basic ways to compile GEOS-Chem:
1. Execute make commands in the top-level code directory

2. Execute make commands in the run directory (RECOMMENDED)
Compiling in the top-level code directory
*** Please see Compiling in a run directory for the recommended compiling
approach ***
Makefile Options
This section will describe make options when compiling from within the GEOS-Chem
code directory. Note that starting in v11-01, we recommend that users compile from
within the run directory by using the Makefile that comes with all run directories
copied from the GEOS-Chem Unit Tester. Information about using a router Makefile,
such as the one included in run directories copied from the Unit Tester, is detailed in
the Advanced Compilation Techniques section of this page.
The GEOS-Chem Makefiles allow you to choose from several different options. The
best way to learn about these options is to type:
make help
at the Unix prompt. You will then get a screen similar to this:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% GEOS-Chem Help Screen %%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Usage: make -jN TARGET REQUIRED-FLAGS [ OPTIONAL-FLAGS ]
-jN Compiles N files at a time (to reduce compilation

time)
--------------------------------------------------------
TARGET may be one of the following:
--------------------------------------------------------
all Default target (synonym for "lib exe")
lib Builds GEOS-Chem source code
libcore Builds GEOS-Chem objs & libs only in GeosCore/
libheaders Builds GEOS-Chem objs & libs only in Headers/
libhistory Builds GEOS-Chem objs & libs only in History/
libiso Builds GEOS-Chem objs & libs only in ISOROPIA/
libkpp Builds GEOS-Chem objs & libs only in KPP/
libnc Builds GEOS-Chem objs & libs only in NcdfUtil/
librad Builds GEOS-Chem objs & libs only in GeosRad/
libutil Builds GEOS-Chem objs & libs only in GeosUtil/
ncdfcheck Determines if the netCDF library installation
works
exe Creates GEOS-Chem executable
clean Removes *.o, *.mod files in source code subdirs
only
realclean Removes all *.o, *mod, *.lib *.a, *.tex, *ps,
*pdf files everywhere
distclean Synonym for "make realclean"
doc Builds GEOS-Chem documentation (*.ps, *.pdf) in
doc/
docclean Removes *.tex, *.pdf, *,ps from doc/
tauclean Removes *.pdb, *.inst, *.pp, and *.continue.*
files produced by TAU
help Displays this help screen
--------------------------------------------------------
REQUIRED-FLAGS include:
--------------------------------------------------------
MET=____ Specifies the met field type
--> Options: geosfp merra2
GRID=___ Specifies the horizontal grid

--> Options: 4x5 2x25 05x0625 025x03125
--------------------------------------------------------
OPTIONAL-FLAGS may be one or more of the following:
--------------------------------------------------------
NEST=___ Specifies the nested-grid domain

--> Options: AS CH NA EU and CU (custom)
NO_REDUCED=y Compiles GEOS-Chem with the full vertical grid

--> Default: NO_REDUCED=y for CHEM=Standard
NO_REDUCED=n for CHEM=Tropchem or
SOA_SVPOA
Parallelization and optimization flags:

---------------------------------------
OMP=no Turns off OpenMP parallelization
--> Default: OMP=y
NONUMA=yes Turns on -mp=nonuma option (pgi only)

--> Default: OMP=n
IPO=yes Turns on optmization options -ipo -static (ifort
only)
--> Default: IPO=n
OPT=___ Specifies the optimization level

--> Defaults OPT=-O2 (ifort and pgi)
OPT=-O3 (gfortran)
M_ARCH=___ Specifies the CPU architecture (gfortran only)
Chemistry options:
------------------
CHEM=___ Specifies which chemistry mechanism is used
--> Options: Standard Tropchem UCX SOA SOA_SVPOA
--> Default: Standard
KPPSOLVER=___ Specifies the integrator used with KPP

--> Options: lsodes radau5 rosenbrock runge_kutta
--> Default: rosenbrock
RRTMG=y Turns on online radiative transfer using the

RRTMG model
--> Default: RRTMG=n
Diagnostics options:
--------------------
BPCH_DIAG=n Disable binary-punch output for diagnostics
--> Default: BPCH_DIAG=y
BPCH_TPBC=n Disable binary-punch I/O for nested-grid boundary

condition files for TPCORE.
--> Default: BPCH_TPBC=y (if NEST is specified)
BPCH_TIMESER=n Disable binary-punch output for timeseries

diagnostics
(i.e. to maintain backwards compatibility until
these
diagnostics are available in netCDF format)
--> Default: BPCH_TIMESER=y
NC_DIAG=y Enable netCDF output for diagnostics

--> Default: NC_DIAG=n
NC_NODEFLATE=y Disable netCDF file compression when writing

diagnostic or restart files to disk. This may
be necessary for debugging, in order to ensure
that file compression does not cause problems
when comparing netCDF files for identicality.
--> Default: NC_NODEFLATE=n
Debugging flags:
----------------
BOUNDS=y Turns on subscript-array checking
--> Default: BOUNDS=n
DEBUG=y Turns on options -g -O0 for running GEOS-Chem in

a debugger
--> Default: DEBUG=n
FPEX=y Turns on checking for floating-point exceptions

--> Default: FPEX=nn
FPE=y Synonym for FPEX=y

--> Default: FPE=n
TIMERS=___ Turn on GEOS-Chem timers (Use 1 for GEOS-Chem

"Classic")
--> Default: TIMERS=0
TRACEBACK=y Print out a list of called routines if the run

dies with an error
--> Default: TRACEBACK=y
--> To disable: TRACEBACK=n
GPROF=y Compiles GEOS-Chem for use with the GNU profiler

(aka gprof)
--> Default: GPROF=n
TAU_PROF=y Compiles GEOS-Chem for use with the TAU

performance profiler
--> Default: TAU_PROF=n
TAU_SF=___ Specifies the TAU selectfile for removing
throttled files
Aerosol microphysics flags:

---------------------------------------
TOMAS=y Turns on 30-bin TOMAS aerosol microphysics
--> Default: TOMAS=n
TOMAS12=y Turns on 12-bin TOMAS aerosol microphysics

--> Default: TOMAS12=n


GCHP (GEOS-Chem "High Peformance") flags:

---------------------------------------
HPC=y Compile GEOS-Chem for HPC environments (with ESMF
& MAPL)
--> Default: HPC=n

Specifying compiler flags
GEOS–Chem relies on several different C–preprocessor switches to inform the
Fortran–90 compiler which options to include in the executable file. The C–
preprocesor (or CPP for short) is a feature of the C and C++ programming
languages that allows you to compile blocks of code only if certain conditions are
met. All modern Fortran compilers have inherited the C–preprocessor feature.
Therefore, even though GEOS–Chem is written in Fortran–90, we can still
incorporate C–preprocesor commands into the source code.
The C-preprocessor switches used by GEOS-Chem include:
 Meteorological fields
 Horizontal and vertical grid information
 Compiler type
 Chemistry mechanism
 Options for special simulations (e.g. mercury)
 Debugging options
Switches are set with Makefile options from the command line by specifying compiler
flags (e.g. UCX=y). Options that are not relevant to your system will be ignored.
Type make help at the command line while in the top-level GEOS-Chem source
code directory for a complete list of compiler flag options (excerpted above).
Please keep the following items in mind when specifying compiler flags.
 When starting with a new version of GEOS-Chem or a new simulation type you
should always issue the following command:
make realclean
This is especially important if you are changing the met field type or horizontal grid
settings. The command will remove all previously-created compiler output files (e.g. *.a,
*.o, *.mod) and executables. After doing make realclean, you can recompile GEOS–
Chem again with your new options.
 You can speed up compilation by specifying make -j4 to compile four files
at a time. If you have more CPUs available you can change this number.
 You must specify a value for MET. Please see out Overview of GMAO met
data products wiki page for more information on the meteorology fields.
Note that the Makefile in run directories copied from the Unit Tester
automatically extract MET from input.geos and do not need to be passed in
the make command.
 Allowable values are: merra2, merrageosfp, geos5, geos4, and gcap
 You must specify a value for GRID. Please see Appendix 2 of the GEOS-
Chem User's Guide for more information on the horizontal grids. Note that
the Makefile in run directories copied from the Unit Tester automatically
extract GRID from input.geos and do not need to be passed in the make
command.
 Allowable values are: 4x5, 2x25, 05x0666, 025x03125
 If you select GRID=05x0666 or GRID=025x03125, then you must select
a nested-grid option. Note that the Makefile in run directories copied from
the Unit Tester automatically extract NEST from input.geos and do not need
to be passed in the make command. Options for NEST include:
 NEST=as for the Asia nested grid (MERRA-2 only)
 NEST=ch for the China nested grid
 NEST=na for the North America nested grid
 NEST=eu for the Europe nested grid
 Makefile target names are case-sensitive. For example, you should
type make all, not make ALL.
 Makefile flags will accept case-insensitive output. You may omit dashes
from met field names. Each of the following is acceptable:
 MET=geosfp, MET=GEOSFP, MET=GeosFp, MET=geos-fp, etc.
 Makefile flags that require a simple yes/no answer will accept case-
insensitive input. For example:
 DEBUG=yes, DEBUG=Yes, DEBUG=y, DEBUG=No, DEBUG=NO, etc.
 Some debug compiler flags may slow down your simulation, so we
recommend using them for short test simulations only. For more information,
see this wiki post.
--Lizzie Lundgren 14:31, 15 April 2015 (EDT)
Setting default flags
The REQUIRED-FLAGS and OPTIONAL-FLAGS can be specified in one of two
ways:
1. As a command-line argument to the GNU Make utility
For example, if you wanted to build the GEOS-Chem executable using the KPP solver
with Rosenbrock integrator and the SOA mechanism you could type:
make -j4 MET=geosfp GRID=4x5 KPPSOLVER=rosenbrock

CHEM=SOA
2. As an environment variable
If you don't wish to keep typing KPPSOLVER=rosenbrock CHEM=SOA every time, you
could instead use:
setenv KPPSOLVER rosenbrock

setenv CHEM SOA
make -j4 MET=geosfp GRID=4x5
Specifying options as environment variables allows you to predefine settings so that you
don't have to physically type them on the command line every time you build GEOS-
Chem. The environment variables can also be placed in your ~/.cshrc or .bashrc so
that they are initialized when you log in.
Compiling examples
All examples below are for compiling from the top-level GEOS-
Chem source code directory. Note that starting in v11-01, we
recommend that users compile from within the run directory by
using the Makefile that comes with all run directories copied from
the GEOS-Chem Unit Tester. The run directory router Makefile
invokes the top-level code directory Makefile to execute any of the
commands in the examples below but creates and stores log files
locally in the run directory. See Compile with a run-directory
Makefile section below for instructions.
Example of compiling with Make:
(1) To build GEOS-Chem executable for the 4x5 grid with GEOS-
FP meteorology, one can simply type:
make -j4 MET=geosfp GRID=4x5
(2) To select a different compiler (e.g. PGI), type:
make -j4 MET=geosfp GRID=4x5 COMPILER=pgi
 Depending on your PGI compiler setup, you may also have to

add the option NONUMA=yes .
(3) The default is to compile for multi-processor. To turn off the
parallelization and build the executable for a single-processor, type:
make -j4 MET=geosfp GRID=4x5 OMP=no
(4) To compile GEOS-Chem (multi-processor) for use with a

debugger (e.g. Totalview), type:
make -j4 MET=geosfp GRID=4x5 DEBUG=yes FPE=yes

OMP=yes
(5) To compile GEOS-Chem (single-processor) with the same

debugging options, type:
make -j4 MET=geosfp GRID=4x5 DEBUG=yes FPE=yes

OMP=no
(6) To test for array-out-of-bounds errors, type:
make -j4 MET=geosfp GRID=4x5 BOUNDS=yes
(7) If you wish to compile the code but not make the executable,
you may type:
make -j4 MET=geosfp GRID=4x5 BOUNDS=yes lib
(8) To print the GEOS-Chem help screen, type::

make help
(9) To generate GEOS-Chem Reference Guide documentation in

PostScript and PDF formats, type:
make doc
(10) To remove all *.o , *.mod , and executable files from the
source code directories (but not from the mod , lib ,
or bin directories), type:
make clean
(11) And to remove everything and start over from scratch, type:
make realclean
--Lizzie Lundgren (talk) 18:41, 4 January 2017 (UTC)

Compiling in a run directory
*** RECOMMENDED COMPILING APPROACH ***
All run directories downloaded from the GEOS-Chem Unit Tester
come with a router Makefile that enables you to easily compile and
run GEOS-Chem from the run directory. Using this feature enables
you to eliminate certain compile options from the make command
that are always the same for a given run directory (e.g. MET and
GRID) and thereby avoid common mistakes. It also creates and
stores compile logs locally for easy reference.
Please see the Creating GEOS-Chem run directories wiki page for
instructions on how to create a GEOS-Chem run directory from the
GEOS-Chem Unit Tester.
Setting up the run directory Makefile
Once you have a run directory, open the Makefile in a text editor
and edit the following three configurable variables with your
preferences:
# Source code location

ifndef CODE_DIR
CODE_DIR :=/home/$(USER)/GC/Code.v11-01
endif
# Output log file destination (default is run

directory)
ifndef LOG_DIR
LOG_DIR :=.
endif
# GEOS-Chem run log filename prefix

ifndef VERSION
VERSION :=v11-01
endif
Each of these three variables are automatically passed to the make

command using the default values you define in this file.
Alternatively, you may define them at the terminal within the make
call. For example, if you want to override your default CODE_DIR,
you can include CODE_DIR=/GC/Code.Ref to
compile Code.Ref rather than Code.Dev.
Makefile options
The compiler flags required for compiling GEOS-Chem,
specifically MET and GRID, and in some cases NEST, TOMAS, RRTMG,
or UCX, are automatically passed when you compile using the run
directory Makefile. The flags are set using the getRunInfo perl
script located in the run directory which reads the simulation
information from the input.geos configuration file. If you wish to
change any of these options you must create a new run directory.
There are two processing modes available for compiling GEOS-
Chem:
1. Single processor ("sp")

2. Multi-processor ("mp"), which uses OpenMP parallelization
Output files, including the GEOS-Chem executable geos, have
a .sp or .mp suffix depending on what processing mode is used.
The GEOS-Chem Makefiles allow you to choose from several
different options. The best way to learn about these options is to
type:
make help
at the Unix prompt. You will then get a screen similar to this:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%
%%% GEOS-Chem Run Directory Makefile Help Screen
%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%
Usage: make -jN TARGET [OPTIONAL-FLAGS]

-jN Compiles N files at a time
(reduces compile time)
----------------------------------------------------
------
TARGET may be one of the following:
----------------------------------------------------
------
all Default target (synonym for
"unittest")
%%% COMPILE AND RUN %%%

unittest Runs a GEOS-Chem unit test:
(1) Builds & runs GEOS-Chem with
parallelization OFF;
(2) Builds & runs GEOS-Chem with
parallelzation ON;
(3) Checks to see if the output is
identical.
sp Builds and runs GEOS-Chem with
parallelization OFF.
mp Builds and runs GEOS-Chem with
parallelization ON.
%%% BUILD ONLY %%%

spbuild Just builds GEOS-Chem with
mpbuild Just builds GEOS-Chem with
parallelization ON.
%%% RUN ONLY %%%

sprun Just runs GEOS-Chem with
mprun Just runs GEOS_Chem with
parallelization ON.
%%% REMOVE DATA FILES %%%

dataclean Removes ALL GEOS-Chem diagnostic
and restart files
spdataclean Removes diagnostic and restart
files from GEOS-Chem
simulations with parallelization
turned OFF.
mpdataclean Removes diagnostic and restart
turned ON.
%%% REMOVE LOG FILES %%%

logclean Removes all GEOS-Chem and HEMCO
output log files.
splogclean Removes GEOS-Chem and HEMCO log
turned OFF.
mplogclean Removes GEOS-Chem and HEMCO log
files from GEOS-Chems
turned ON.
%%% REMOVE EXECUTABLE FILES %%%

execlean Removes all GEOS-Chem executable
files
spexeclean Removes GEOS-Chem executable files
for which the
parallelization has been turned
OFF.
mpexeclean Removes GEOS-Chem executable files
for which the
parallelization has been turned
ON.
%%% REMOVE ALL FILES %%%

fileclean Synonym for: dataclean logclean
execlean
spclean Synonym for: spdataclean
splogclean spexeclean
mpclean Synonym for: mpdataclean
mplogclean mpexeclean
%%% REMOVE CONFIG FILES %%%

extrafileclean Removes input.geos and
HEMCO_Config.rc files
%%% CLEAN SOURCE CODE %%%
clean Makes "clean" in source code
directory ODE_DIR
realclean Makes "realclean" in the source
code directory ODE_DIR
tauclean Removes all TAU files in the
source code directory ODE_DIR
%%% CLEAN AND REMOVE ALL %%%

superclean Synonym for: fileclean realclean
...
To compile only, type the following at the command line, including

any optional compiler flags as needed:
make -j4 mpbuild
Prior to compiling, geos.mp, lastbuild.mp, and all .mp log files

will be removed from the directory by calling other make
targets mpexeclean and mplogclean. All standard output
generated while building the new executable will be displayed in
your terminal window. The executable created will reside in
the /bin directory within CODE_DIR and a copy will be placed in the
run directory with name geos.mp. Finally, your compile settings will
be stored in log lastbuild.mp and will also be printed to the
terminal window. The unix commands for each of these steps is
stored under various targets in the Makefile. Note that you make
call any of the make targets from the command line (e.g. make
mplogclean to remove all .mp logs).
To compile and run GEOS-Chem interactively, type the following at
the command line:
make -j4 mp
Prior to compiling, all .mp files (executable, log, and data) will be
removed from the directory. All standard output generated while
creating and then running the new executable will be sent to the run
log file. As when building only, the executable created will reside in
the /bin directory within CODE_DIR and a copy will be placed in the
run directory with name geos.mp. Your compile settings will be
stored in log lastbuild.mp as well as the run log file. Output data
files are appended with the .mp suffix except for restart and
HEMCO diagnostic files that do not correspond to the simulation
end date. Finally, your compile and run settings will be printed to the
terminal window.
The GNU Make utility is a powerful and flexible software
development tool and we encourage you to explore the existing
Makefile options and to customize the Makefile to optimize your
own needs.
--Lizzie Lundgren 10:59, 22 April 2015 (EDT)
Information from the last time GEOS-Chem was
compiled
When compiling GEOS-Chem v11-01 from one of the run directory
Makefiles, a file called lastbuild.mp or lastbuild.sp will be
created. This file contains the settings that were used to compile
GEOS-Chem, for your reference.
LAST BUILD INFORMATION:

CODE_DIR : ../Code.v11-01k
CODE_BRANCH : Precision
LAST_COMMIT : Update WEST_NS_DIV in
hcox_lightnox_mod.F90 to fix ozone overestimate in
the US
COMMIT_DATE : Fri Dec 2 15:47:35 2016 -0500
VERSION : v11-01
MET : geosfp
GRID : 4x5
SIM : standard
NEST : n
TRACEBACK : n
BOUNDS : n
DEBUG : n
FPE : n
NO_ISO : n
NO_REDUCED : y
CHEM : Standard
UCX : y
TOMAS12 : n
TOMAS15 : n
TOMAS30 : n
TOMAS40 : n
RRTMG : n
MASSCONS : n
TIMERS : 1
BPCH_RST_IN : n
BPCH_RST_OUT : n
BPCH_DIAG : y
NC_DIAG : n
COMPILER : gfortran 4.8.2
Datetime : 2016/12/02 17:53
Advanced compilation techniques
Compiling 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.v9-02 # your code
dir
rm -f log # clear log
file
make -j4 MET=geos5 GRID=4x5 > log # build the
code
exit(0) # exit
normally
You can then run this script interactively, or submit it to the queue
system on your computational cluster.
Technical Issues
GNU Make is required
The makefiles described above are designed to be used with GNU
Make. This is free, open-source software and is bundled with most
of the popular Unix versions today (e.g. various Linux builds,
Ubuntu, Fedora, etc.).
It is recommended to use GNU Make because not all Unix make
utilities are compatible with each other. GNU Make is probably the
most flexible make utility available.
If GNU Make is not already installed on your system, then you (or
your IT guru) will have to install it. You can check to see if GNU
Make is already installed by typing:
make --version
at the Unix prompt. GNU Make will display a version screen similar
to this:
GNU Make 3.81

Copyright (C) 2006 Free Software Foundation, Inc.
This is free software; see the source for copying
conditions.
There is NO warranty; not even for MERCHANTABILITY
or FITNESS FOR A
PARTICULAR PURPOSE.
This program built for x86_64-redhat-linux-gnu
Please also read the GNU Make Reference Document for more
detailed information.
Install LaTeX utilities for auto documentation
Many of the updated GEOS-Chem source code files now use
the ProTeX documentation headers. The protex script (included in
the Code/doc subdirectory) strips the information from the
documentation headers located in GEOS-Chem
 Modules
 Subroutines
 Functions
 Include files
and creates a LaTeX format (*.tex) file. The latex utility can
then be used to produce output in PDF (*.pdf) and PostScript
(*.ps) formats from the LaTeX file. This all happens automatically
when you type:
make doc
at the Unix prompt. However, you must make sure to have the
LaTeX utilities installed on your machine in order to be able to
generate this automatic documentation. The LaTeX utilities include:
Utility Description
latex Converts LaTeX format files to Device-Independent

format (*.dvi)
dvips Converts Device-Independent format to PostScript

format
dvipdf Converts Device-Independent format to PDF

format
The LaTeX utilities may be packaged with your version of Unix. Ask
your IT guru for more information.
You may also want to install the following packages:
Utility Description
ghostview Reader for PostScript files
acroread Adobe Acrobat Reader for PDF files

Compile-time options that can slow down GEOS-
Chem
The following compile-time options can cause a GEOS-Chem job to
run more slowly than usual:
Command Description
DEBUG=y This is required for running GEOS-Chem in a

debugger such as idb or Totalview. This will
invoke the -g -O0 compiler options, which
turn off all optimization.
BOUNDS=yes This option turns on runtime array-out-of-

bounds checking, which looks for instances of
invalid array indices (i.e. If the A array only has
10 elements but you try to reference A(11).)
FPEX=y or This option turns on error checking for

FPE=y floating-point exceptions (i.e. div-by-zero,
NaN, floating-invalid, and similar errors).
OMP=no This option turns off the OpenMP

parallelization (which is turned on by default).
If you have selected any of the above options, then try compiling
GEOS-Chem from scratch, i.e.,
make realclean
make -j4 MET=____ GRID=____
and then re-run your GEOS-Chem job.

--Bob Y. 15:47, 2 October 2013 (EDT)
Previous issues that have now been resolved

Add a more robust test for netCDF-Fortran in
Makefile_header.mk
This update was included in GEOS-Chem 12.0.1, which was
released on 24 Aug 2018.
We have rewritten the test that determines if the netCDF-Fortran
library file (libnetcdff.a) is in the same folder or a different folder
than the netCDF-C library file (libnetcdf.a). The new test should
be more robust and forgiving of user error.
Some users had reported an issue with the GEOS-Chem
environment variable GC_F_INCLUDE was being added to the build
sequence even if there is no netCDF-Fortran library. The new test
will only add GC_F_INCLUDE to the build sequence if the netCDF-
Fortran library is found on disk.
--Bob Yantosca (talk) 16:44, 24 August 2018 (UTC)
Removed the COMPILER variable from
Makefile_header.mk for a cleaner build sequence
This update was included in v11-02a and approved on 12 May
2017.
Farid Amid wrote:
I was trying to compile the model v11.01 with for the nested domain
using PGI compiler and following command:
make -j4 MET=GEOS-FP GRID=025x03125 NEST=NA
The issue was that mod dir remained empty and I had compiler had
difficulty finding mod files, the problem was resolved by changing
line 1317 of Makefile_header.mk from pgfortran to pgi.

We have made a fix to v11-02a (under development) to remove
the COMPILER variable in the Makefile. We now test the value of
the FC environment variable with a regular expression to determine
if it is the Intel, PGI, or GNU compiler family. (On most Unix
software builds, the environment variable FC is the standard name
for the Fortran compiler.) Sometimes the PGI compiler on a system
is called pgf90, or else pgfortran, or sometimes pgi. The new
Makefile test should be more robust and accept all of these
alternatives.

Bug fix: Specifying NO_REDUCED=no now compiles
GEOS-Chem for reduced grids
This fix was included in v11-02a and approved on 12 May 2017.
Jiawei Zhang wrote:
I found a small but annoying bug in Makefile_header.mk. The
problem is that if I use NO_REDUCED=n (i.e. use 47 levels) as a
compile option, then the makefile will treat it
as NO_REDUCED=yes (i.e. use 72 levels). The LLPAR parameter will
then be set to 72 instead of 47, leading to unexpected behavior.
That's because Makefile_header.mk contains something like:
# %%%%% REDUCED VERTICAL GRID (default, unless

specified otherwise) %%%%
ifndef NO_REDUCED
USER_DEFS += -DGRIDREDUCED
else
REGEXP :=(^[Yy]|^[Yy][Ee][Ss])
ifeq ($(shell [[ "$(NO_REDUCED)" =~
$(REGEXP) ]] && echo true),true)
endif
endif
The GRIDREDUCED C-preprocessor switch will only be activated

if NO_REDUCED is not provided. The following "yes" or "no" just
doesn't matter because the nested ifeq statement doesn't do
anything. With this problem, the only way to compile a 47L model is
NOT providing the NO_REDUCED option. It also affects compiling
GEOS-Chem from the geosfp_4x5_tropchem rundir,
because NO_REDUCED=n is one of the default options.
We have now fixed this issue by setting the NO_REDUCED Makefile

variable to "no" by default, and then evaluating its value in a
separate IF statement. This code has now been added to
the Makefile_header.mk.
# %%%%% REDUCED VERTICAL GRID (default, unless

specified otherwise) %%%%
ifndef NO_REDUCED
NO_REDUCED :=no
endif
REGEXP :=(^[Nn]|^[Nn][Oo])
ifeq ($(shell [[ "$(NO_REDUCED)" =~ $(REGEXP) ]]
&& echo true),true)
USER_DEFS += -DGRIDREDUCED
endif
This fix now will compile GEOS-Chem for 47 levels

when NO_REDUCED=no is specified, or if NO_REDUCED is omitted.
TRACEBACK=y is now the default setting
This update was included in GEOS-Chem v11-01 public release
Seb Eastham (Harvard) suggested that all GEOS-Chem simulations
should use the traceback option by default. An example of
traceback output generated by the Intel Fortran Compiler is shown
below:
Image PC Routine
Line Source
libifcoremt.so.5 00002B9EFA2188D3 Unknown
Unknown Unknown
geos.mp 00000000011FCE35
regrid_a2a_mod_mp 1914 regrid_a2a_mod.F90
libiomp5.so 00002B9EFB70A8A3 Unknown
Unknown Unknown
The above example shows that the GEOS-Chem simulation exited

abnormally at line 1914 of module regrid_a2a_mod.F90. We
believe that having this information available will help GEOS-Chem
users to better diagnose and report issues.
We have modified the Makefile_header.mk file in the GEOS-
Chem v11-01 public release to set the Makefile
option TRACEBACK=y if it is not already passed as an argument. To
disable the traceback output, you will now have to compile
with TRACEBACK=n.
It should be noted that the traceback option will increase the size of
the GEOS-Chem executable, but will not have any impact on
execution speeds.
Compiler cannot find certain files
This issue can occur in GEOS-Chem v9-01-01 and older versions.
We have added this fix into GEOS-Chem v9-01-02 and higher
versions.
Matthew Johnson wrote:
When looking into the core files I get error output such as this:
Symbol file not found for main

Core was generated by `./geos'.
Program terminated with signal 11,
Segmentation fault.
#0 0x0000000000733bde in
pjc_pfix_mod_mp_init_press_fix_ ()
Have you seen this portion of the code causing a seg fault before?
Try reordering the lines in GeosCore/Makefile from:

lib: libkpp libutil libiso libcore
to:
lib:
# Build all G-C libraries
@$(MAKE) libkpp
@$(MAKE) libutil
@$(MAKE) libiso
@$(MAKE) libcore
NOTE: All indented lines begin with a TAB!

This ordering will force GNU Make to compile all of the files in KPP/ first, then all of the
files in GeosUtil/, etc. This ought to prevent the build sequence from referencing files
that haven't yet been compiled.
--Bob Y. 14:02, 3 January 2013 (EST)
References
1. GNU Make Manual

2. Mecklenburg, Robert, Managing
Projects with GNU Make, Third
Edition,, O'Reilly and Associates,
2004.
--Bob Y. 12:07, 19 July 2011 (EDT)
Obsolete information
These sections pertain to makefile options
for obsolete versions of GEOS-Chem. We
shall keep this information here for
reference.
GEOS-Chem v10-01
The table below lists the directory structure
in GEOS-Chem v10-01 along with
descriptions of each subdirectory and its
Makefile (if one is present).
Is there a
Descriptio
Directory Makefile
n
here?
Code Main-level Yes, there

directory are two:
for GEOS-
Chem  Makefile
is the
main-
level
router
makefile
and it
calls
down to
the
makefile
in GeosCo
re.
 Makefile
_header.
mk define
s
compilati
on and
linking
comman
ds for the
Fortran-
90
compilers
. These
comman
ds are
common
to the
makefiles
in all
subdirect
ories.
Code/GTM Directory Yes, it

M
containing compiles the
source code
code files in GTMM and
for creates
the Global library
Terrestrial file lib/libH
Mercury g.a
Model
(GTMM) si
mulation
Code/Geo Directory Yes, this is

sApm
containing the main
parallel makefile for
copied of GEOS-Chem
GEOS- with APM. It
Chem calls down to
source the makefiles
code files in the other
that were subdirectorie
modified s. It then
for compiles the
the APM code
aerosol in GeosApman
microphysi d GeosCore a
cs package nd creates
the geosapm
executable.
NOTE: Due
to the many
wide-
sweeping
updates (e.g.
HEMCO,
UCX, SOA)
made in
recent
versions of
GEOS-
Chem, the
APM
package is
now no
longer
compatible
with GEOS-
Chem v10-
01. The
APM team
is currently
working on
bringing
APM up to
date.
Code/Geo Directory Yes, this is

sCore
containing the main
most makefile for
GEOS- GEOS-Chem.
Chem It calls down
modules to the
and makefiles in
routines the other
subdirectorie
s. It then
compiles the
code in
the GeosCore
directory and
creates
the geos exe
cutable.
Code/Geo Directory Yes, it

sRad
source code
code files in GeosRad an
for d creates
the RRTM library
G radiative file lib/libr
transfer ad.a.
model
Code/Geo Directory Yes, it

sUtil
GEOS- code
Chem in GeosUtil a
utility nd creates
modules library
file lib/libG
eosUtil.a.
Code/HEM Main-level Yes, it calls

CO
directory down to the
for HEMC makefiles in
O the other
HEMCO
subdirectorie
s.
Code/HEM Directory Yes, it

CO/Core
HEMCO code
modules in HEMCO/Cor
and e and creates
routines library
for file lib/libH
reading, CO.a.
storing,
and
updating
data used
for
calculating
emissions

CO/Exten
sions containing compiles the
HEMCO code
modules in HEMCO/Ext
and ensions and
routines creates
for library
calculating file lib/libH
emissions COX.a.
that
depend on
meteorolo
gical input
variables
and/or
non-linear
parameteri
zations
CO/Inter
faces containing compiles the
HEMCO code
modules in HEMCO/Int
and erfaces and
routines creates
that library
provide file lib/libH
the link COI.a.
between
HEMCO
and the
model
environme
nt
Code/Hea Directory Yes, it

ders
module code
files with in Headers an
fixed d creates
parameter library
s and file lib/libH
derived- eaders.a
type
definitions
 NOTE:
In
previo
us
version
s,
these
files
were
header
files
that
were
inlined
via
the #in
clude s
tateme
nt.
These
have
since
been
conver
ted to
F90
modul
es in
order
to
facilitat
e Grid-
Indepe
ndent
GEOS-
Chem
develo
pment.
Code/ISO Directory Yes, it
ROPIA
the code
unmodifie in ISOROPIA a
d ISORROP nd creates
IA II source library
code files file lib/libI
from soropia.a.
Thanos
Nenes and
Havala
Pye:
 isorop
iaIIco
de.F
 isrpia
.inc
Code/KPP Main-level Yes, it calls

for makefiles in
the KPP the other
chemical KPP
solver subdirectorie
s.
Code/KPP Directory Yes, it

/standar
d containing compiles the
KPP source code
code files in KPP/stand
for ard and
the standa creates
rd library
chemistry file lib/libK
mechanis pp.a.
m

/SOA
KPP source code
for ard and
the SOA creates
chemistry library
mechanis file lib/libK
m pp.a.
/UCX
KPP source code
for ard and
the UCX creates
chemistry library
mechanis file lib/libK
m pp.a.
Code/KPP Directory No
/int
containing
the
integrators
(rosenbroc
k, runge-
kutta,
lsodes,
etc.) for
KPP
Code/Ncd Directory Yes, it

fUtil
source code
code files in NcdfUtil a
for netCDF nd creates
I/O. This library
code is file lib/libN
from Bob cUtils.a.
Yantosca's
NcdfUtiliti
es package
Code/Ncd Directory No
fUtil/pe
rl containing
perl scripts
from the
NcdfUtiliti
es package
that can
be used to
generate
Fortran
code for
defining,
writing,
and
reading a
netCDF file
Code/bin Directory No
where
executable
(geos, geos
tomas, geo
sapm) files
will be
sent
Code/doc Directory Yes, it calls

where the ProTeX
automatic script to
document create
ation is reference
built manuals (in
PS and PDF
formats)
from the
comments in
GEOS-Chem
module and
routine
headers.
Code/hel Directory Yes, it prints
p
containing the GEOS-
GEOS- Chem help
Chem help screen to
screen stdout
Code/lib Directory No
where
library
(*.a) files
will be
created
Code/mod Directory No
where
module
(*.mod)
files will be
sent
Code/obs Directory No
olete
where
obsolete
source
code files
are placed
for
reference
if needed
--Lizzie Lundgren 13:46, 15 April 2015

(EDT)
GEOS-Chem v9-02
The table below lists the directory structure
in GEOS-Chem v9-02 along with a
description of each subdirectory and its
Makefile (if one is present).
Is there a
Director Descriptio
Makefile
y n
here?
Code Main level Yes, there are

GEOS- two:
Chem
directory  Makefile i
s the
main-level
router
makefile
and it calls
down to
the
makefile
in GeosCor
e.
 Makefile_
header.mk
defines
compilatio
n and
linking
commands
for the
Fortran-90
compilers.
These
commands
are
common
to the
makefiles
in all
subdirecto
ries.
Code/He Directory Yes, it
aders
module code
files with in Headers an
fixed d creates
parameter library
s and file lib/libHe
derived- aders.a
type
definitions
 NOTE:
In
previo
us
version
s,
these
files
were
header
files
that
were
inlined
via
the #in
clude s
tateme
nt.
These
have
since
been
conver
ted to
F90
modul
es in
order
to
facilitat
e Grid-
Indepe
ndent
GEOS-
Chem
develo
pment.
Code/Ge Directory Yes, it
osUtil
GEOS- code
Chem in GeosUtil an
utility d creates
modules library
file lib/libGe
osUtil.a
Code/Ge Directory Yes, this is the

osCore
containing main Makefile
most for GEOS-
GEOS- Chem. It calls
Chem down to the
modules makefiles in
and the other
routines subdirectories
.
Code/IS Directory Yes, it

OROPIA
the code
unmodifie in ISOROPIA an
d d creates
ISORROPIA library
II source file lib/libIs
code files oropia.a
from
Thanos
Nenes and
Havala
Pye:
 isorro
piaIIc
ode.F
 isrpia
.inc
Code/KP Main-level Yes, it calls

P
for KPP makefiles in
solver the other KPP
subdirectories
.
Code/KP Directory Yes, it

P/stand
ard containing compiles the
KPP source code
code files in KPP/standa
for the rd and creates
standard library
chemistry file lib/libKp
mechanis p.a
Code/KP Directory Yes, it

P/SOA
KPP source code
code files in KPP/standa
for SOA rd and creates
chemistry library
mechanis file lib/libKp
m p.a
Code/KP Contains No
P/int
the
integrators
(rosenbroc
k, runge-
kutta,
lsodes,
etc.) for
KPP.
Code/do Directory Yes, it calls

c
where the ProTeX
automatic script to
document create
ation is reference
built manuals (in PS
and PDF
formats) from
the comments
in GEOS-Chem
module and
routine
headers.
Code/li Directory No
b
where
library
(*.a) files
will be
created
Code/mo Directory No
d
where
module
(*.mod)
files will be
sent
Code/bi Directory No
n
where
executable
(geos) files
will be
sent
Code/he Directory Yes, it prints

lp
containing the GEOS-
GEOS- Chem help
Chem help screen to
screen stdout
Code/ob Directory No
solete
where
obsolete
source
code files
are placed
for future
reference
if need be
NOTE: Starting with GEOS-Chem v9-02,
the GeosTomas subdirectory has been
removed and code for the TOMAS
aerosol microphysics package has been
inlined into the GeosCore directory
using C-preprocessor statements. See
the TOMAS Aerosol Microphysics wiki
page for more information.
--Lizzie Lundgren 13:47, 15 April 2015
(EDT)
Backup files not excluded from
compilation
Maria Zatko wrote:
During compilation using version v8-02-04, the compilation cannot be completed

because the .f~ file type is not recognized. The model runs successfully once I manually
remove the .f~ files from the code.
Is there a way to run v8-02-04 while keeping the backup files in the code as done in v8-
03-01 and v8-02-01?
Bob Yantosca wrote:
Yes...I think in some v8-02-xx versions of the code we may have had a wildcard that
grepped for *.f* in the Makefile. This would have tried to compile the *.f~ files that are
generated when you use Emacs to edit the code.
In the GeosCore/Makefile you can replace any lines that look like:
# Source and
object files
SRC =
$(wildcard *.F*)
with
# Source and
object files
SRC =
$(wildcard *.F)
$(wildcard *.F90)
and this should exclude all *.f~ and *.f90~ files from the compilation. This fix has since
been standardized in GEOS-Chem v8-03-01.
--Bob Y. 13:58, 27
August 2010
(EDT)
We have been looking at the ammonia emissions in the model in our comparisons to
observational data from Africa and have a couple of questions.
Although the GEIA anthropogenic emissions are overwritten by other inventories, for
Africa at least, the model still uses the GEIA Natural and Biofuel emission of NH3:

Introduction To Atmospheric Chemistry

Uploaded by

Copyright:

Available Formats

Introduction To Atmospheric Chemistry

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Introduction To Atmospheric Chemistry

Uploaded by

Copyright:

Available Formats

Atmospheric Sciences > GEOS-Chem Model > Manuals > GEOS-Chem Online User's Guide > Chapter 1

GEOS-Chem Online User's Guide

Previous | Next | Printable View (no frames)

GEOS-Chem Community Mission: to advance understanding of human and natural influences on

This User's Guide is arranged as follows:

1. Introduction (This page) Provides a brief overview of GEOS-Chem and

NEW! GEOS-Chem can now be run on the Amazon EC2 cloud.

9. GEOS-Chem Components Describes the various components that make up GEOS-Chem

13. Diagnostics Describes the diagnostics generated by GEOS-Chem.

1.2 Participation in the GEOS-Chem User Community

1.3 New features

1.4 Bugs and technical issues that have been fixed

 Issues resolved in GEOS-Chem 12.0.0 (aka v11-02-final)

 Currently unresolved issues in GEOS-Chem

Previous | Next | Printable View (no frames)

Previous | Next | Printable View (no frames)

2. Getting set up with GEOS-Chem

2.1 Useful skills for working with GEOS-Chem

 Programming using the Fortran programming language

2.2 Where can I run GEOS-Chem?

You can run GEOS-Chem on the following types of machines:

 You can easily initialize your computational environment with a

For more information, please see Jiawei Zhuang's very comprehensive

(NOTE FOR ADVANCED USERS: If you need to use a different

2.3 Additional downloads

 If you are using the Amazon EC2 cloud, then a netCDF

For more information, please see Chapter 4.

For more information, please see Chapter 5.

For more information, please see Chapter 6.

Previous | Next | Printable View (no frames)

o 1.1 GEOS-Chem requirements

o 1.2 GEOS-Chem documentation and support

o 2.1 Common Unix commands

o 2.2 Unix shells and shell scripting

o 2.3 Perl scripting

 3 The GNU Make utility

 4 The Git source code management system

o 5.1 Online tutorials

o 5.2 The GNU Fortran compiler

o 5.3 The Intel Fortran compiler

 6 The netCDF library

o 6.1 netCDF on Amazon cloud

o 6.2 netCDF on your system

o 6.3 netCDF references

 7 The GEOS-Chem source code

 8 The GEOS-Chem Unit Tester

o 8.1 Creating run directories with the Unit Tester

 9 The GEOS-Chem shared data directories

o 11.1 GAMAP and other IDL software

o 11.2 Python software

 12 The GEOS-Chem website

 13 The GEOS-Chem wiki

o 13.2 Wiki Philosophy

 15 For more information

 You can initialize your computational environment with a pre-compiled "machine

 You will avoid GEOS-Chem compilation errors due to library incompatibilities.

 Download the meteorological fields from the Dalhousie data archive

The GEOS-Chem Support

The GEOS-Chem website