GEOS–Chem v9–01–02 Online User's Guide
Previous | Next | Printable View (no frames)
1.1 Welcome to the GEOS–Chem user community!
The following sections describe the responsibilities that we expect from each GEOS–Chem user. Please also see our GEOS–Chem overview page, which lists some additional information for new GEOS–Chem users.
1.1.1 Expectations and responsibilities
We expect that each GEOS–Chem user (or user group, if there are several users at an institution) will have the required hardware and software available 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 each GEOS–Chem user will possess 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 submit to the GEOS–Chem Support Team a short research blurb (1 paragraph) that describes how you and your research group plan to use GEOS–Chem. We will add this to our GEOS–Chem People and Projects web page.
Registering your group will allow us to have an accurate count of 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
As a GEOS–Chem user, you are expected to join the Working Group that is most relevant to your area of research. The Working Groups are meant to foster communication and information sharing between GEOS–Chem users, as well as to identify priorities for model development to the GEOS–Chem Steering Committee. Please introduce yourself to the Working Group Chairperson.
We have set up several email lists for GEOS–Chem users. Each GEOS–hem Working Group has its own email list, so that group members can discuss various aspects of model development and validation among themselves. In addition, we have also set up 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 Being an active member of the community
Each GEOS–Chem user is also expected to adhere to our list of best practices. In particular, if you should discover a problem (e.g. bugs, missing files, numerical issues, etc.), please bring that to the attention of the GEOS–Chem support team right away. Other GEOS–Chem users will most certainly benefit from your discovery!
Please consider reporting your timing results from the 1-month benchmark simulation to the GEOS–Chem Support Team. This will allow us to keep a list of how the model is performing across several different platform/compiler combinations.
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. Over the years, 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 also investigating how to port GEOS–Chem to distributed memory machines using the MPI parallelization directives.
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–3, GEOS–4, or GEOS–5 data products at either 2° x 2.5° or 4° x 5° global resolution. Recent versions of GEOS–Chem will allow you to run at the native GEOS–4 horizontal resolution of 1° x 1.25°. You can also use GEOS–Chem (versions 9–01–01 and higher) with the GMAO's new MERRA 30-year reanalysis data set.
In recent years, GEOS–Chem has become a popular tool for regional-scale modeling. You can perform nested-grid simulations (one-way nesting) at 0.5° x 0.666° horizontal resolution for the following regions: China/SE Asia, North America, and Europe.
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. "Public" vs. "beta" releases
There are two types of GEOS–Chem versions: "public" releases and "beta" releases.
When we have many updates which need to be added into the GEOS–Chem standard code, it is often expedient for us to split these among several "beta" GEOS–Chem versions. This allows us to test each beta version individually with the usual 1-month benchmark simulation. For some GEOS–Chem versions (especially those with updates that need to be tested over a longer time period), we will also perform a 1-year benchmark simulation.
After iterating through several beta versions, when the code has attained stability, we will then announce a "public" GEOS–Chem version release with the customary fanfare. The GEOS–Chem Support Team will rewrite the GEOS–Chem Online User's Guide (i.e. this document) for each public version, but not for each beta version. Updates for GEOS–Chem beta releases shall be documented in the Addenda section (Appendix 8 of the User's Guide).
The GEOS–Chem Support Team will announce each GEOS–Chem version release via the GEOS–Chem website and email list.
1.3 What's new in GEOS–Chem v9–01–02
The following features were introduced into GEOS–Chem public release v9–01–02:
| Feature | Description |
|---|---|
| Science updates |
|
Updated dry deposition velocities for aerosols over ice and snow |
Modeled aerosol dry deposition velocities over snow and ice surfaces in the Arctic were much higher than estimated from measured values (e.g., Ibrahim et al. [1983]; Duan et al. [1988]; Nilsson and Rannik [2001]). In v9–01–02, a dry deposition velocity of 0.03 cm/s is imposed for all aerosols over snow and ice surfaces. |
Imposed seasonality on the NH3 emissions from David Streets 2000 inventory |
The Streets 2000 inventory for anthropogenic ammonia (NH3) does not include any seasonal cycle. This has been corrected by using the annual total from Streets 2000 superimposed with monthly scale factors from a global inventory compiled by Marcel Meinders and Lex Bouwman. |
RETRO anthropogenic VOC emissions |
Monthly RETRO anthropogenic VOC emissions have been added as an optional inventory. For more information, please see this document: |
APM aerosol microphysics |
Fangqun Yu and Gan Luo developed the Advanced Particle Microphysics (APM) package for implementation into GEOS–Chem. APM is now one of two microphysics packages in GEOS–Chem, the other being TOMAS. |
GFED3 biomass burning emissions |
Monthly mean GFED3 biomass burning emissions have been added to v9-01-02. The GFED3 emissions inventory will eventually replace GFED2. |
GEIA 2005 Hg emissions |
Bess Corbit prepared the GEIA 2005 emission inventory for anthropogenic Hg. |
| Structural updates |
|
Modifications for compatability with ESMF |
Modifications were made to GEOS–Chem source code to enable compatability with the Earth System Model Framework (ESMF). These changes were were aimed at cleaning up legacy code and making specific portions of the code FORTRAN 90/95 compliant. For more information, please see the following links: |
MERRA SEAICExx fields added to the planeflight diagnostic |
The MERRA SEAICExx fields are now saved to the plane flight diagnostic. |
Overhaul of AOD diagnostics |
Patrick Kim discovered some inconsistencies in the way aerosol optical depth diagnostics were being computed in v9–01–01 and prior versions. See this wiki page for more information. |
Archive MERRA SWGDN field in the ND67 diagnostic |
MERRA "incident shortwave radiation at the ground" (SWGDN) is now archived to ND67, not "net longwave radiation at the ground" (LWGNT). |
Centralized chemistry time step |
The time at which chemistry, emissions, photolysis, and drydep operations are performed has been moved to the midpoint of the chemistry time step. See this wiki page for more information. |
| Bug fixes |
|
Bug fixes for the offline Hg simulation |
The following issues were discovered in the offline Hg simulation shortly after the release of v9-01-01 and have been fixed in v9-01-02: |
Various other bug fixes |
The following updates were made to fix several bugs:
|
1.4 Requirements for GEOS–Chem v9–01–02
Here is a summary of what you will need on your computer system before you can run GEOS–Chem. We also invite you to read our wiki pages entitled Minimum System Requirements for GEOS–Chem and GEOS–Chem supported platforms and compilers for the most up-to-date information regarding supported systems, compilers, and other hardware and software issues.
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–01–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, and array operation syntax. Please view Appendix 7: GEOS–Chem Style Guide for more tips on how to write effective Fortran–90 code.
GEOS–Chem is now managed by the version control software Git. 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 advice users to install Git on their systems to manage their local GEOS–Chem source code.
1.5 The Git version control software
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. 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 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.
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
The GEOS–Chem User's Guide is arranged accordingly:
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.