GEOS–Chem v9–01–03 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:

• The Fortran programming language
• IDL (preferred), or other graphics software (e.g. Splus, Matlab)
• The Unix environment (i.e. commands, file paths, etc.)
• Unix scripts (not strictly required but is very helpful to know!)
• How version control works

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

• GEOS–Chem wiki: GEOS–Chem programming resources
• Presentation: GEOS–Chem User Resources, Code Development Guidelines, and Debugging Tips.

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 soon GEOS–5.7.2!) 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) 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. 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–01–03

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

1.4 Requirements for GEOS–Chem v9–01–03

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:

• Enough memory to run GEOS–Chem
• At least 2 GB RAM
• But more than 4 GB RAM for running at 2° x 2.5° or higher resolution
• You may want to consider 8 GB RAM if you plan on doing any of the following:
  • Running GEOS–4 1° x 1.25° global GEOS–Chem simulations
  • Running GEOS–5 0.5° x 0.667° 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)
• Sufficient disk storage for met fields

1.4.2. Software requirements

GEOS–Chem requires the following software:

1. Any Unix-style operating system, such as:
   • Linux (Red Hat, SuSE, CentOS, etc.)
   • Ubuntu
   • Fedora
   • Mac OS X (which is POSIX-compliant)
   • NOTE: GEOS–Chem cannot run on a Microsoft (XP, Vista, Windows 7) environment!
2. A Fortran 90 compiler that supports OpenMP parallelization
   • If using the Portland Group compiler, then a C compiler (such as GNU C compiler) is also required. The gcc comes installed with most Unix builds.
3. GNU Make (chances are your Unix system has this installed already)
4. Git version control system (free, open-source version control 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–03 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.

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 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

• Git avoids some of the limitations of CVS (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:

• Chapter 8: Using Git to manage the GEOS–Chem source code
• GEOS–Chem wiki: Version control with Git
• GEOS–Chem wiki: Using Git with GEOS–Chem
• The Git web page: http://www.git-scm.com

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.

• Supplementary information GEOS–Chem, including lists of tracers by simulation, horizontal and vertical grids, meteorological data fields, diagnostic output options, chemical species, etc. are contained in the Appendices.

Previous | Next | Printable View (no frames)