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
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 |
|
Rynda Hudman Kay (EPA), Neil Moore (formerly of Dalhousie), Bram Maasakkers (Eindhoven) | |
Yanxu Zhang (U. Washington), Lyatt Jaeglé (U. Washington) | |
Yanxu Zhang (U. Washington), Lyatt Jaeglé (U. Washington) | |
Bess Corbitt (Harvard) | |
Correct Hg simulation to use updated Hg(0) oxidation kinetics |
Bess Corbitt (Harvard), Justin Parrella (Harvard) |
Bess Corbitt (Harvard), Justin Parrella (Harvard) | |
Carey Friedman (MIT), Noelle Selin (MIT) | |
Mat Evans (York) | |
Ellie Browne (UC Berkeley) | |
Fabien Paulot (Harvard), Eloise Marais (Harvard), Jingqiu Mao (NOAA/GFDL), Mat Evans (York) | |
Fabien Paulot (Harvard) | |
Jingqiu Mao (NOAA/GFDL) | |
GEOS-Chem Support Team | |
Lin Zhang (Peking University) | |
Jingqiu Mao (NOAA/GFDL) | |
Lin Zhang (Peking University) | |
Wai-Ho Lo (Dalhousie) | |
Chris Holmes (UC Irvine) | |
Kevin Wecht (Harvard) | |
Aaron van Donkelaar (Dalhousie) | |
Prasad Kasibhatla (Duke) | |
Jenny Fisher (U. Wollongong) | |
Sal Farina (CSU) | |
Sebastian Eastham (MIT), Steven Barrett (MIT) | |
Havala Pye (EPA), GEOS-Chem Support Team | |
Jintai Lin (Peking University), GEOS-Chem Support Team | |
Becky Alexander (U. Washington) | |
David Ridley (MIT), Randall Martin (Dalhousie) | |
Structural updates |
|
GEOS-Chem Support Team |
|
Sal Farina (CSU), GEOS-Chem Support Team | |
Additional modifications to enable GEOS-Chem to run within the GEOS-5 GCM |
GEOS-Chem Support Team |
Chris Holmes (UC Irvine) | |
Rewriting inefficient subroutine calls to avoid wasting memory and CPU cycles |
GEOS-Chem Support Team |
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 |
|
Sajeev Philip (Dalhousie) |
|
Sajeev Philip (Dalhousie) | |
Jenny Fisher (U. Wollongong), GEOS-Chem Support Team | |
Sajeev Philip (Dalhousie) | |
Aaron van Donkelaar (Dalhousie) | |
GEOS-Chem Support Team | |
Bug fix in regridding of anthropogenic emissions (NEI2005, Streets) |
GEOS-Chem Support Team |
GEOS-Chem Support Team | |
Tzung-May Fu (Peking University) | |
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 |
Jenny Fisher (U. Wollongong) | |
GEOS-Chem Support Team | |
Fabien Paulot (Harvard) | |
Emily Fischer (Harvard) | |
Fix diurnal NOx scale factors and fix double counting of biofuels over Mexico, Canada, and Europe |
Christoph Keller (Harvard) |
Christoph Keller (Harvard) | |
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) |
Chris Holmes (UC Irvine) | |
Thibaud Thonat (U. Edinburgh) | |
GEOS-Chem Support Team | |
Jenny Fisher (U. Wollongong) | |
GEOS-Chem Support Team | |
Corrected minor bugs for GCAP that were introduced by GIGC edits |
GEOS-Chem Support Team |
Sal Farina (CSU) | |
Bug fix in ND36 diagnostic when ship emissions are turned off |
Yanko Davila (U. Colorado) |
GEOS-Chem Support Team | |
GEOS-Chem Support Team | |
Gabriele Curci (U. L'Aquila) | |
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.
To run GEOS–Chem your hardware must have:
GEOS–Chem requires the following software:
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
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
Git avoids some of the limitations of the CVS version control system (which is by now 30-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.
Git is in general 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, one can easily create several branches off of the "master" branch of code development. (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 it is time to release the code.
The GitK tool 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 (the Git Gui) lets you control Git in a more visual manner than the command-line options.
With Git, GEOS–Chem developers will be 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, and
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)
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:
Installing the GEOS–Chem source code directory, run directories,and shared data directories will be the topic of Chapter 2: Installation.
Compiling the GEOS–Chem source code into an executable will be covered in Chapter 3: Compilation.
The various shared data files (met fields, emissions inventories, oxidants, etc.), contained in the data directory will be the focus of Chapter 4: Data Directories.
Setting up the files in your own personal run directory is discussed in Chapter 5: Run Directories.
Running and debugging the GEOS–Chem code is the topic of Chapter 6: Running GEOS–Chem.
F90 coding practices and parallelization are the subject of Chapter 7: Coding: Practice and Style.
A brief summary of the most common Git commands is covered in Chapter 8: Using Git to manage the GEOS–Chem source code.
The Reference Section in Chapter 9 contains links to the GEOS–Chem reference guides that are generated automatically with the ProTeX too. Here you will also find a list of acknowlegments and guidelines for offering credit to GEOS–Chem developers.