GEOS–Chem v9–02 Online User's Guide

Previous | Next | Printable View (no frames)

1. Introduction

1.1 Welcome to the GEOS–Chem user community!

We (the GEOS–Chem Support Team) welcome you to the international GEOS–Chem user community. The following sections describe the expectations and responsibilities that we expect from you as a GEOS–Chem user. For additional information, please see our GEOS–Chem overview page.

1.1.1 Expectations and responsibilities

We expect you to have the required hardware and software to run GEOS–Chem. If you are not sure what hardware or software is available to you, then please check with your local IT department.

We expect that you will have at least some familiarity with the following:

For more information about these topics, please follow these links:

1.1.2 Register your GEOS–Chem user group

We invite you to send us a paragraph describing how you and the other members of your research group plan to use GEOS–Chem. We will add this to our GEOS–Chem People and Projects web page.

Registering your group helps us to accurately track how many research groups are using GEOS–Chem. This helps us to plan accordingly.

1.1.3 Join a working group and subscribe to the email lists

We expect you to join the Working Group that is most relevant to your area of research. The Working Groups foster communication and collaboration between GEOS–Chem users, and identify priorities for model development to the GEOS–Chem Steering Committee. Please take a moment to introduce yourself to the Working Group Chairperson via email.

Each GEOS–Chem Working Group has its own email list, so that group members can discuss various aspects of model development and validation among themselves. We have also established a general GEOS–Chem email list where we shall make announcements about new model releases, bugs and fixes, and other information pertient to the entire GEOS–Chem community. Therefore, you should subscribe to the general GEOS–Chem email list and to the email list of your Working Group.

Click HERE for more information about subscribing to the GEOS–Chem email lists.

1.1.4 Be an active member of the community

As a GEOS–Chem user, we expect you to adhere to our 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!

Please feel free to send us your timing results from the 1-month benchmark simulation. 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 wiki.

1.2 The GEOS–Chem model of atmospheric chemistry and composition

1.2.1. Overview

The GEOS–Chem model is a global three-dimensional model of tropospheric chemistry driven by assimilated meteorological observations from the Goddard Earth Observing System (GEOS) of the NASA Global Modeling Assimilation Office. GEOS–Chem is being developed by personnel at Harvard University and other institutions in the Americas, Europe, and Asia.

GEOS–Chem began as a merging of Mian Chin's GEOS–CTM code with the emissions, dry deposition, and chemistry routines from the old Harvard–GISS 9-layer model. Since then, we have added many updates and improvements to GEOS–Chem. The model now uses detailed inventories for fossil fuel, biomass burning, biofuel burning, biogenic, and aerosol emissions. GEOS–Chem includes state-of-the-art transport (TPCORE) and photolysis (FAST–J) routines, as well as the SMVGEAR II chemistry solver package. Detailed aerosol microphysical simulations using GEOS–Chem may performed with the TOMAS aerosol microphysics code or the APM aerosol microphysics code.

GEOS–Chem has been parallelized using the OpenMP compiler directives, and it scales well when running across multiple CPU's on shared-memory machines. We are currently building a Grid-Independent version of GEOS-Chem in order to take advantage of distributed memory architectures and MPI parallelization.

GEOS–Chem has kept pace with changes in the meteorological data products being produced by GMAO. You can perform GEOS–Chem simulations with GMAO's GEOS–4, GEOS–5, MERRA, and GEOS–FP data products on 1° x 1.25°, 2° x 2.5° or 4° x 5° global grids. GEOS–Chem has become a popular tool for regional-scale modeling. You can perform nested-grid simulations (one-way nesting) using GEOS–5 at 0.5° x 0.666° horizontal resolution for the following regions: China, North America, and Europe. Nested-grid simuations may now also be performed using GEOS–FP at 0.25° x 0.3125° horizontal resolution over the following regions: China, North America, Europe, and SE Asia.

Those of you who are part of the GCAP project can use GEOS–Chem to perform simulations using meteorology from the GISS–II GCM (23 layers, 4° x 5° horizontal grid). You can select from several IPCC future-climate scenarios.

1.2.2. The benchmarking process

We updated our benchmarking procedure, starting with version GEOS–Chem v9–01–02. For details, GEOS–Chem benchmarking web page.

1.3 What's new in GEOS–Chem v9–02

The following features were introduced into GEOS–Chem public release v9–02:

Feature Developer(s)
Science updates

New soil NOx emission module

Rynda Hudman Kay (EPA), Neil Moore (formerly of Dalhousie), Bram Maasakkers (Eindhoven)

EPA/NEI05 North American Hg emissions

Yanxu Zhang (U. Washington), Lyatt Jaeglé (U. Washington)

Nested-grid Hg simulation

Yanxu Zhang (U. Washington), Lyatt Jaeglé (U. Washington)

Streets future Hg emissions

Bess Corbitt (Harvard)

Correct Hg simulation to use updated Hg(0) oxidation kinetics

Bess Corbitt (Harvard), Justin Parrella (Harvard)

Capability to use GEOS-Chem Br/BrO fields in Hg simulation

Bess Corbitt (Harvard), Justin Parrella (Harvard)

POPs simulation: Polycyclic aromatic hydrocarbons

Carey Friedman (MIT), Noelle Selin (MIT)

Inorganic chemistry updates

Mat Evans (York)

Methyl peroxy nitrate (MPN) chemistry

Ellie Browne (UC Berkeley)

Adopt Paulot isoprene scheme as standard

Fabien Paulot (Harvard), Eloise Marais (Harvard), Jingqiu Mao (NOAA/GFDL), Mat Evans (York)

Fix RO2+HO2 rate constant

Fabien Paulot (Harvard)

Increase NO3 uptake by aerosol

Jingqiu Mao (NOAA/GFDL)

Removal of NOx-Ox partitioning

GEOS-Chem Support Team

Inhibition of N2O5 uptake by nitrate aerosol

Lin Zhang (Peking University)

Improved HO2 uptake by aerosol

Jingqiu Mao (NOAA/GFDL)

Updated NH3 seasonal scaling factors over the US

Lin Zhang (Peking University)

Updated Canadian NH3 inventory

Wai-Ho Lo (Dalhousie)

RCP emission scenarios

Chris Holmes (UC Irvine)

EDGAR v4.2 emissions for CH4 simulation

Kevin Wecht (Harvard)

Update anthropogenic scale factors through 2010

Aaron van Donkelaar (Dalhousie)

Update GFED3 emissions to 2011

Prasad Kasibhatla (Duke)

Update TOMS overhead O3 columns to 2010

Jenny Fisher (U. Wollongong)

Include 12-bin and 15-bin configurations of TOMAS

Sal Farina (CSU)

AEIC aircraft emissions inventory

Sebastian Eastham (MIT), Steven Barrett (MIT)

SOA simulation with semi-volatile POA

Havala Pye (EPA), GEOS-Chem Support Team

Implement non-local PBL mixing in the Rn-Pb-Be simulation

Jintai Lin (Peking University), GEOS-Chem Support Team

Cloud water pH for sulfate formation

Becky Alexander (U. Washington)

Update jv_spec.dat and jv_spec_aod.dat with better representation of OC growth with RH and correction to sulfate optics

David Ridley (MIT), Randall Martin (Dalhousie)

Structural updates

Grid-independent GEOS-Chem updates: Activation of new data pathways and other structural modifications

GEOS-Chem Support Team

Inline the latest source code modifications updates for the TOMAS microphysics package into GEOS-Chem

Sal Farina (CSU), GEOS-Chem Support Team

Additional modifications to enable GEOS-Chem to run within the GEOS-5 GCM

GEOS-Chem Support Team

Streamlining of the code in GeosCore/mercury_mod.F

Chris Holmes (UC Irvine)

Rewriting inefficient subroutine calls to avoid wasting memory and CPU cycles

GEOS-Chem Support Team

Modifications for GEOS-Chem Unit Tester

GEOS-Chem Support Team

Nested-grid model at 0.25° x 0.3125° resolution using GEOS–FP met data product from GMAO

Yuxuan Wang (Tsinghua), GEOS-Chem Support Team

Global simulations with GEOS–FP data product from GMAO

GEOS-Chem Support Team

Bug fixes

Correction for GEOS-5 PBL heights

Sajeev Philip (Dalhousie)

Bug fix in hdf_mod.F

Sajeev Philip (Dalhousie)

Bug fixes for tagged CO simulation

Jenny Fisher (U. Wollongong), GEOS-Chem Support Team

Bug fix for nested simulation in nei_anthro_mod.F

Sajeev Philip (Dalhousie)

Bug fix for updated CAC emissions

Aaron van Donkelaar (Dalhousie)

Bug fix for Br2 emissions

GEOS-Chem Support Team

Bug fix in regridding of anthropogenic emissions (NEI2005, Streets)

GEOS-Chem Support Team

Additional bug fixes for MAP_A2A regridding

GEOS-Chem Support Team

Bug fix for MEGAN emissions when using MERRA or GEOS-FP

Tzung-May Fu (Peking University)

Bug fixes for nested Hg simulation

Yanxu Zhang (U. Washington)

Prevent bad drydep flux values from being passed to the soil NOx emissions module

Patrick Kim (Harvard), GEOS-Chem Support Team

Bug fix for declaration of GEOS-FP PFICU, PFLCU, PFILSAN, PFLLSAN fields

GEOS-Chem Support Team

Bug in EMIS_STREETS_ANTHRO_05x0666

Jenny Fisher (U. Wollongong)

Bug fix for reading OH file in offline simulations

GEOS-Chem Support Team

Bug in wet deposition Henry's constant

Fabien Paulot (Harvard)

Add DRYACET to globchem.dat

Emily Fischer (Harvard)

Fix diurnal NOx scale factors and fix double counting of biofuels over Mexico, Canada, and Europe

Christoph Keller (Harvard)

Bug fix for 3-hourly GFED3 emissions

Christoph Keller (Harvard)

Bug fix in grid_mod.F90

Christoph Keller (Harvard)

Bug fix for anthropogenic scaling factors for years 2006 and later

Jenny Fischer (U. Wollongong)

Correct additional bugs in ship emissions w/ non-local PBL mixing

Chris Holmes (UC Irvine), Geert Vinken (Eindhoven)

Bug fix for ship CO emissions

Chris Holmes (UC Irvine)

Fix typo in VOLCPRESS definition

Thibaud Thonat (U. Edinburgh)

Bug fixes in day-of-week computation

GEOS-Chem Support Team

Bug fixes in diag48_mod.F

Jenny Fisher (U. Wollongong)

Bug fix in emissions for offline aerosol simulation

GEOS-Chem Support Team

Corrected minor bugs for GCAP that were introduced by GIGC edits

GEOS-Chem Support Team

Minor bug fix in TOMAS sulfate emissions

Sal Farina (CSU)

Bug fix in ND36 diagnostic when ship emissions are turned off

Yanko Davila (U. Colorado)

Fix molecular weights of RIP and IEPOX used in drydep_mod.F

GEOS-Chem Support Team

Bug fixes to prevent floating-point invalid errors

GEOS-Chem Support Team

Bug fix in jv_spec_aod.dat for dust species

Gabriele Curci (U. L'Aquila)

Fix bug in CAC NH3 emission files

Wai Ho Lo (Dalhousie)


1.4 Requirements for GEOS–Chem v9–02

We summarize below the hardware and software requirements that you will need in order to run GEOS–Chem. For the most up-to-date information regarding supported systems, compilers, and other hardware and software issues, please also see our wiki pages entitled Minimum System Requirements for GEOS–Chem and GEOS–Chem supported platforms and compilers.

1.4.1. Hardware requirements

To run GEOS–Chem your hardware must have:

1.4.2. Software requirements

GEOS–Chem requires the following software:

  1. Any Unix-style operating system, such as:
  2. A Fortran 90 compiler that supports OpenMP parallelization
  3. GNU Make (chances are your Unix system has this installed already)
  4. Git version control system (free, open-source version control software)
  5. A netCDF library installation.

The Linux flavor (RedHat, SuSE, Fedora, Ubuntu, etc.) is not important. Also, 64-bit architecture is not an issue with GEOS–Chem.

GEOS–Chem v9–02 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 for more tips on how to write effective Fortran–90 code.

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 developements in the standard version. For all these reasons, we strongly advise you to install Git so that you can manage your local GEOS–Chem source code.

1.5 The Git version control software

1.5.1. Why use Git?

GEOS–Chem model development is done in a distributed manner. GEOS–Chem users from many different institutions download the most recent model version and modify it according to their own particular research interests. Once a GEOS–Chem user has deemed his or her source code modifications to be mature—usually coinciding with the submission of a paper to an academic journal—he or she will submit his or her source code modifications to us for inclusion into the mainline "standard" model.

We used to disseminate the GEOS–Chem source code and run directories as a series of TARBALL (i.e. *.tar.gz) files (one for each version) via anonymous FTP. The advantage of this method was that each GEOS–Chem user only had to download a single file. However, as the number of GEOS–Chem users (and the 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 led to confusion and error.

Given the large number of user code submissions, we must employ robust source code management techniques in order to ensure the integrity of the GEOS–Chem source code. Therefore, we have selected the Git version control software for GEOS–Chem source code management. Git is a relatively new version control system and offers many improvements over previous source code management software such as CVS and Subversion.

1.5.2. Advantages of using Git

For more information about using Git, please see our wiki pages:

1.6 Topics covered in the GEOS–Chem User's Guide

We have arranged the GEOS–Chem User's Guide as follows:

Previous | Next | Printable View (no frames)