Difference between revisions of "GEOS-Chem welcome letter for new users"

From Geos-chem
Jump to: navigation, search
m (Automatic documentation with ProTeX)
m (Automatic documentation with ProTeX)
Line 234: Line 234:
# GEOS-Chem wiki: [[Automatic documentation with protex]]
# GEOS-Chem wiki: [[Automatic documentation with protex]]
# GEOS-Chem User's Guide: [http://acmg.seas.harvard.edu/geos/doc/man/appendix_7.html '''GEOS-Chem Style Guide''']
# GEOS-Chem User's Guide: [http://acmg.seas.harvard.edu/geos/doc/man/appendix_7.html#A7.2 '''A7.2 Headers, declarations, indentations, and white space''']
=== Get familiar with Git ===
=== Get familiar with Git ===

Revision as of 17:03, 17 December 2014

Welcome to the GEOS-Chem user community! Here is a quick guide to getting started:

GEOS-Chem Support Team

The GEOS-Chem Support Team currently consists of Bob Yantosca, Michael Long, Melissa Payer Sulprizio, Sajeev Philip, Lizzie Lundgren, Matthew Yannetti, and Yanko Davila. They are responsible for developing and maintaining the GEOS-Chem and GEOS-Chem Adjoint codes for the user community. They may be reached by email at geos-chem-support@as.harvard.edu.

Expectations and Responsibilities for GEOS-Chem users

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.

Required hardware and software

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.

Computer language proficiency

We expect that each GEOS-Chem user will possess at least some familiarity with the following:

  • The Fortran programming language (F77 OK, F90 preferred)
  • 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

While we cannot provide you with general instruction in programming languages or answer general programming questions, we invite you to view the list of tutorials and other relevant resources listed on our GEOS-Chem programming resources page. We also invite you to read our document on User Resources, Code Development Guidelines, and Debugging Tips.

Being a member of the GEOS-Chem community

We ask that all new GEOS-Chem user groups submit a short research blurb (1 paragraph) about how you plan to use GEOS-Chem in your research. We will add this to our GEOS-Chem People and Projects web page. Please send your research blurb to the GEOS-Chem Support Team.

We also ask that each GEOS-Chem user join the Working Group that is most relevant to his/her 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)s) and sign up for the relevant email list(s).

Each GEOS-Chem user is 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.

Subscribing to the GEOS-Chem email lists

We use several GEOS-Chem email lists to share information among the user community:

  • We send information about new GEOS-Chem releases, bug fixes, and other notices of importance to the the GEOS-Chem "general" email list (geos-chem@seas.harvard.edu)
  • Each GEOS-Chem Working Group uses its own email list to exchange information between group members.

We invite you to join the Working Group that is most appropriate to your research, and to subscribe to the relevant email list. Consider joining more than one Working Group (and email list) if your research spans several topics.

For complete instructions on how to subscribe to (or unsubscribe from) the GEOS-Chem email lists, please see our Subscribing to the GEOS-Chem email lists wiki page.

Participating in GEOS-Chem code development

As a member of the GEOS-Chem user community, we expect that you will submit your mature code revisions to the GEOS-Chem Support Team so that they can be included in a future release of GEOS-Chem. We invite you to read our GEOS-Chem code development cycle wiki page for more information about the process.

For more detailed information about coding and debugging, see below.

Downloading GEOS-Chem

Before you can run GEOS-Chem for the first time, you must download and install these four elements:

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 compilers. The compilation is managed by the GNU Make Utility (aka gmake), 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 the Git version control software installed on your system. For more information and detailed downloading instructions, please see:

  1. GEOS-Chem User's Guide: Chapter 2.2, Downloading the GEOS-Chem source code
  2. GEOS-Chem User's Guide: Chapter 3, Compiling the GEOS-Chem source code
  3. GEOS-Chem wiki: Downloading GEOS-Chem source code and data

GEOS-Chem run directories

The GEOS-Chem run directory is the directory 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:

  1. To specify start and end dates of simulation
  2. To specify which GEOS-Chem options to turn on/off
  3. To specify the species/reactions in the chemical mechanism
  4. To specify the species/reactions/cross-sections in the photolysis mechanism
  5. To specify diagnostic output options

Like the GEOS-Chem source code, the various run directories are also archived as publicly-accessible Git repositories. For more information and detailed downloading instructions, please see:

  1. GEOS-Chem User's Guide: Chapter 2.3, Downloading the GEOS-Chem run directories
  2. GEOS-Chem User's Guide: Chapter 5, The GEOS-Chem run directories
  3. GEOS-Chem wiki: Downloading GEOS-Chem source code and data

GEOS-Chem shared data directories

In addition to the files contained in the run directories, GEOS-Chem also needs to access data directories containing:

  1. Meteorological data (a.k.a. the "met fields) used to drive GEOS–Chem
  2. Emissions inventories used by GEOS-Chem
  3. Scale factors used to scale emissions from a base year to a given year
  4. Oxidant (OH, O3) concentrations for both full-chemistry and offline simulations
  5. IPCC future scenarios (for GCAP simulatons)
  6. 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:

  1. GEOS-Chem User's Guide: Chapter 2.3, Downloading the GEOS-Chem shared data directories
  2. GEOS-Chem User's Guide: Chapter 4, The GEOS-Chem shared data directories
  3. GEOS-Chem wiki: Downloading GEOS-Chem source code and data

GEOS-Chem libraries

GEOS-Chem can read data files in netCDF format. Eventually, we shall replace all of GEOS–Chem's input and output files from binary punch file format to netCDF format. We are doing this as part of our Grid-independent GEOS-Chem project, which seeks to interface GEOS–Chem with the NASA GEOS–5 GCM.

In order to facilitate building the netCDF library, the GEOS-Chem Support Team has constructed the GEOS-Chem-Libraries installer package. With GEOS-Chem-Libraries, you can build one of the following sets of libraries:


  1. zlib-1.2.6 (netcdf-4.2 depends on this)
  2. hdf5-1.8.8 (netcdf-4.2 depends on this)
  3. netCDF 4.2


  1. netCDF classic

Please see our Installing libraries for GEOS-Chem wiki page for installation instructions.

GEOS-Chem documentation

GEOS-Chem website

The GEOS-Chem website is located at http://acmg.seas.harvard.edu/geos/) (aka http://www.geos-chem.org).

From this website you may:

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


The GEOS-Chem public wiki (i.e. this wiki) is located at: http://wiki.seas.harvard.edu/geos-chem/.

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 Main Page of the wiki contains links to several commonly-read pages. If you can't find your desired topic, then try typing it into the Search Box on the left hand panel.

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 started a new 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.


The best way to find information on the GEOS-Chem wiki is to type in your topic to the search box at the left of your browser window. 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!

In general, it is better to create smaller wiki pages that are cross-referenced rather than large wiki pages with a lot of text. This ensures that individual pages can be more easily navigated and searched. Also, the MediaWiki system will display a warning message if you try to save a wiki page that contains more than 32 KB of text. If that happens, you can just simply break up your page into smaller pages.

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

Each wiki page also has a corresponding discussion page. This is designed as the place to post information (e.g. a long email exchange, user comments, etc.) that would be too cumbersome to post on the front page.

Lastly, we invite all GEOS-Chem users to read our post about wiki user culture.

GEOS-Chem online user's guide

The GEOS-Chem Online User's Guide provides a wealth of information about how to install and run GEOS-Chem. The User's Guide is totally rewritten for each GEOS-Chem release.

Visualization software


The GAMAP visualization package is the standard visualization software that is used with GEOS-Chem. GAMAP is Interactive Data Language (IDL) software and is freely available. Please see the Online GAMAP Manual for more information about how to download and run GAMAP.

Other packages

Members of the GEOS-Chem User Community are developing visualization software for GEOS-Chem for languages other than IDL. You can find a full description of available visualization tools on our Related software tools for use with GEOS-Chem web page.

GEOS-Chem search engines

For your convenience, we have created several search engines that will allow you to search the GEOS-Chem web site, GEOS-Chem wiki, GEOS-Chem manual, and GAMAP manual. To use these search engines, please visit our GEOS-Chem Search Page.

Frequently asked questions

We have also created a wiki page devoted to Frequently asked questions about GEOS-Chem, which is especially geared to new GEOS-Chem users.

GEOS-Chem coding and debugging

As a new GEOS-Chem user, you will more than likely be adding your own modifications to GEOS-Chem. The following sections contain some helpful hints pertaining to source code style and management.

Coding style

In order to improve the readibility and appearance of the GEOS-Chem source code, we ask all users to conform to the GEOS-Chem Style Guide. The readability of your code can be greatly enhanced by simple steps, like adding white space between words and by indenting DO loops and IF statements.

The more comments, the better!

It is good practice to add copious comments to your source code. This will make sure that current and future GEOS-Chem users will be able to understand the modifications that you have added.

Keep in mind that many GEOS-Chem users (including the GEOS-Chem Support Team) will probably not be as familiar with your specific area of research as you are. While most users will probably get the "big picture" of what you are doing, they will be less knowledgeable about the little details (i.e. why does this reaction rate have a value of X, why is this parameter set to Y, why was this IF statement deleted, etc.). Providing sufficient source code documentation will eliminate any such guesswork.

Automatic documentation with ProTeX

Protex is a useful Perl script that can strip information from a standard Fortran document header and save that to a LaTeX file. The LaTeX file can then be converted into both PostScript and PDF output. (Protex was developed at the Goddard Space Flight Center by Arlindo Da Silva, Will Sawyer, and others.)

Since GEOS-Chem v8-01-03, the GEOS-Chem Support Team has been actively replacing the older GEOS-Chem source code documentation with ProTeX documentation headers. This will allow a "GEOS-Chem Reference Manual" (i.e. a list of all GEOS-Chem routines and their inputs and outputs) to be generated automatically when you invoke the make doc Makefile option.

For more information, please see:

  1. GEOS-Chem wiki: Automatic documentation with protex
  2. GEOS-Chem User's Guide: A7.2 Headers, declarations, indentations, and white space

Get familiar with Git

We use the Git source code management software to facilitate the version control for GEOS-Chem. Git allows us to easily merge and track codes from GEOS-Chem developers into the "mainline" standard source code repository.

When submitting source code updates for GEOS-Chem, we ask that you send us your update in Git-ready form.

For more information about Git, please see the following pages:

  1. Version control with Git
  2. Using Git with GEOS-Chem

Debugging GEOS-Chem

Please see our wiki page on tips and tricks for debugging GEOS-Chem. We expect all GEOS-Chem users to be proactive in debugging. Please try to do everything possible to solve your problem before contacting the GEOS-Chem Support Team.

If you have access to a debugger such as Totalview, this may help you to diagnose your problem. Ask your local IT department if you have a debugger installed at your location.

GEOS-Chem Unit Tester

We have a new tool that you can use to help find many common numerical errors and programming issues. The GEOS-Chem Unit Tester is an external package that can run several test GEOS-Chem simulations with a set of very strict debugging options. The debugging options are designed to detect issues such as floating-point math errors, array-out-of-bounds errors, inefficient subroutine calls, and parallelization errors.

For complete instructions on how the GEOS-Chem Unit Tester can assist your debugging efforts, please see our Debugging with the GEOS-Chem unit tester wiki page.

--Bob Y. 09:56, 17 January 2014 (EST)

Reporting GEOS-Chem bugs and problems

If you have tried to solve your code problem but cannot, then please report it to the GEOS-Chem Support Team. Please include the following information:

GEOS-Chem Version Number (e.g. v9-02)
Met field type (e.g. GEOS-4, GEOS-5, GCAP, GEOS-FP, MERRA)
Horizontal Resolution (e.g. 4° x 5°, 2° x 2.5°, 0.5° x 0.666°, 0.25° x 0.3125°)
Type of Simulation (e.g. full-chemistry, Hg, Tagged CO, etc. )
Platform & OS (e.g. Linux box, Solaris, etc.)
Compiler (e.g. IFORT, PGI ...)
Number of Processors  
Diagnostics Requested (e.g. ND28, ND43, ND45, etc.)
Description of problem  
Error Message  

also, please attach a copy of the log file from the simulation. It is very difficult for us to diagnose the problem without seeing the log file output.

--Bob Y. 16:02, 16 January 2014 (EST)