GEOS-Chem welcome letter for new users
Welcome to the GEOS-Chem user community! Here is a quick guide to getting started:
- 1 GEOS-Chem programming staff
- 2 Expectations and Responsibilities
- 3 Subscribing to the GEOS-Chem email lists
- 4 GEOS-Chem website
- 5 GEOS-Chem public wiki
- 6 GEOS-Chem data directory access
- 7 GEOS-Chem Code development cycle
- 8 GEOS-Chem manual updates
- 9 GEOS-Chem debugging tips
- 10 Reporting GEOS-Chem bugs and problems
GEOS-Chem programming staff
Bob Yantosca and Claire Carouge are responsible for developing and maintaining the GEOS-Chem source code for the user community. They are available during regular business hours (M-F, 9AM-5PM ET).
The general rule of thumb is that if you have a question about the GEOS-Chem code itself, or if your question deals with a programming or coding matter, then you should ask Bob and Claire. On the other hand, if you have a question about a scientific matter, a data source, etc., then you should direct your question to the person(s) who have worked on that particular topic.
For a list of GEOS-Chem users and their primary areas of research, please visit the GEOS-Chem People & Projects page.
Of course, if you do not know whom is the best person to ask, then feel free to contact Bob, Philippe or Claire, and they will be happy to forward your query to the proper person.
Here is the contact information for Bob and Claire:
|Name||Title||Group email||Individual email||Phone||FAX|
|Bob Yantosca||Software Engineerfirstname.lastname@example.orgemail@example.com||617-496-9424||617-495-4551|
|Claire Carouge||Research Associatefirstname.lastname@example.orgemail@example.com||617-495-2893||617-495-4551|
Please send any and all GEOS-Chem related inquiries to the group email firstname.lastname@example.org. This will send your email to Bob and Claire without you having to address your email to them individually.
Expectations and Responsibilities
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!)
We cannot provide you with general instruction in programming languages or answer general programming questions. We would like to invite you to view to view the list of tutorials and other relevant resources that are listed on the GEOS-Chem web page at GEOS-Chem Resources Page.
We invite you to read our document on User Resources, Code Development Guidelines, and Debugging Tips.
PLEASE NOTE: GEOS-Chem cannot be used in a Windows (XP/Vista) environment! You will need a Unix-like operating system (e.g. IRIX, Sun/Solaris, Linux, Ubuntu, Fedora, ...)
Being a member of the GEOS-Chem community
We would like to ask all new GEOS-Chem user groups to 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.
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.
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!
Subscribing to the GEOS-Chem email lists
There are several GEOS-Chem email lists:
|Email list address||Intended audience|
|email@example.com||All GEOS-Chem users and developers|
NOTE: This is the email list to which information about
new model versions, bugs & fixes, etc. will be sent
|firstname.lastname@example.org||Members of the Adjoint Model and Data Assimilation Working Group|
|email@example.com||Members of the Aerosols Working Group|
|firstname.lastname@example.org||Members of the Carbon Gases and Organics Working Group|
|email@example.com||Members of the Emissions Working Group|
|firstname.lastname@example.org||Members of the Oxidants and Chemistry Working Group|
|email@example.com||Members of the Regional Air Quality Working Group|
To subscribe to any of these lists, please visit the page: https://lists.seas.harvard.edu/mailman/listinfo and then click on the name of the list to which you wish to subscribe. You will be taken to a page where you can specify your email address and a password and then click SUBMIT. You will then receive a confirmation email from the system. Follow the directions in the confirmation email and then you will be added to the list.
PLEASE NOTE: If you wish to send an email to any of the above GEOS-Chem mailing lists, then please be sure to send your email from the same address with which you subscribed to the list. Otherwise your email may bounce back to you. The GEOS-Chem mailing lists are set up to reject emails from non-list members. This is done in order to prevent spam.
The GEOS-Chem website is located at http://acmg.seas.harvard.edu/geos/.
From this website you may:
- Download the GEOS-Chem source code and data
- Read the online GEOS-Chem User's Guide
- See which years of meteorological data are available
- Access GEOS-Chem-related publications
- View online presentations from GEOS-Chem user meetings
- View output from GEOS-Chem Near-Real-Time simulations
- See a list of who is using GEOS-Chem at other institutions
- Obtain information about the GAMAP visualization package
We also ask that you provide your contact information, a list of people who will be using GEOS-Chem, and a short description of your research for the GEOS-Chem People and Projects Page.
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. This has not been saved into PDF format at this time.
GEOS-Chem public wiki
The GEOS-Chem public wiki (i.e. this wiki) is located at: http://wiki.seas.harvard.edu/geos-chem/.
This wiki is meant to facilitate communication between GEOS-Chem users and developers. The following informaton is posted on the wiki:
- General information about GEOS-Chem
- Getting started with GEOS-Chem
- Technical Information
- Information about the specifics of:
- Chemistry mechanism
- Offline simulations (e.g. Mercury, Tagged CO)
- Machine and portability issues
- Bugs and fixes
- Information about met fields
- Data Visualization and Analysis
We invite all GEOS-Chem users to register for the wiki by clicking the "create account" link at the top right corner of the screen. Only registered users may edit the wiki, but anyone without an account may read the wiki pages.
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!
NOTE: Only registered users may edit the wiki. Please do not edit wiki pages unless you have new information to contribute!
GEOS-Chem data directory access
Primary download site
The GEOS-Chem source code, data and meteorological field directories may be accessed by anonymous FTP from
ftp ftp.as.harvard.edu login: anonymous password: your email address cd pub/geos-chem
The geos-chem directory is further divided into the following subdirectories:
HDF/ data/ evaluation/ beta_releases/ mean_OH/ patches/ public_releases/
Here is a quick look at the contents of these subdirectories:
|/data||Root Data Directory|
|/data/GEOS_1x1||1x1 global grid emissions etc. files|
|/data/GEOS_1x1_CH||1x1 China-nested grid emissions etc files|
|/data/GEOS_1x1_CH/GEOS_3||1x1 China-nested grid GEOS-3 met fields|
|/data/GEOS_1x1_NA/||1x1 NA-nested grid emissions etc files|
|/data/GEOS_1x1_NA/GEOS_3||1x1 NA-nested grid GEOS-3 met fields|
|/data/GEOS_2x2.5/||2x2.5 emissions and other data files|
|/data/GEOS_2x2.5/GEOS_3/YYYY/MM||GEOS-3 2x2.5 met data|
|/data/GEOS_2x2.5/GEOS_4_v4/YYYY/MM||GEOS-4 2x2.5 met data (late-look)|
|/data/GEOS_2x2.5/GEOS_4_flk/YYYY/MM||GEOS-4 2x2.5 met data (1st-look)|
|/data/GEOS_2x2.5/GEOS_4_5/YYYY/MM||GEOS-5 2x2.5 met data|
|/data/GEOS_4x5/||4x5 emissions and other data files|
|/data/GEOS_4x5/GEOS_3/YYYY/MM||GEOS-3 4x5 met data|
|/data/GEOS_4x5/GEOS_4_v4/YYYY/MM||GEOS-4 4x5 met data (late-look)|
|/data/GEOS_4x5/GEOS_4_flk/YYYY/MM||GEOS-4 4x5 met data (1st-look)|
|/data/GEOS_4x5/GEOS_5/YYYY/MM||GEOS-5 4x5 met data|
|/evaluation||Plots from 1-yr benchmark simulations|
|/HDF||Contains user code for reading HDF and HDF-EOS data files|
|/NRT-ARCTAS||Contains output from the GEOS-Chem Near-Real-Time simulations for ARCTAS|
|/public_releases||Directory containing TAR file source code and run directories for GEOS-Chem public releases|
|/beta_releases||Directory containing TAR file source code and run directories for "beta" GEOS-Chem releases|
|patches/||Directory containing bug-fix software patches (if necessary)|
|mean_OH/||Directory containing 3-D mean OH fields archived from previous GEOS-Chem simulations.|
NOTE: if you are interested in obtaining the GCAP met fields (at 4x5 resolution), then they are stored in a similar data structure from the root directory:
ftp ftp.as.harvard.edu cd pub/gcap/
Alternative download site
The GEOS-Chem data and meteorological fields used by Dalhousie University are also available via anonymous FTP from:
This site has overlap with many of the above directories from the Harvard site, but it is not as extensive. This site, however, additionally hosts the following unique datasets:
|/GEOS_0.5x0.666_EU/||1/2 x 2/3 European nested grid emission etc files|
|/GEOS_0.5x0.666_EU.d/||1/2 x 2/3 European nested grid met fields (GEOS-5)|
|/GEOS_0.5x0.666_NA/||1/2 x 2/3 North American nested grid emission etc files|
|/GEOS_0.5x0.666_NA.d/||1/2 x 2/3 North American nested grid met fields (GEOS-5)|
|/GEOS_1x1.25/||1 x 1.25 Global GEOS4 emission etc files|
|/GEOS_1x1.25.d/||1 x 1.25 Global GEOS4 met fields|
We recommend using the Unix wget utility for FTP download. This has some nice options, including recursive directory download and crontab scheduling.
GEOS-Chem Code development cycle
How GEOS-Chem code development works:
- First download a recent standard code version (public or internal)
- Add your modifications into the code
- Test your code thoroughly and make sure that it works
- Contact the GEOS-Chem Support Teamand request that your changes be included in the standard code
- The GEOS-Chem Support Team will add your changes to the standard code and benchmark it
- Daniel approves the benchmark results and declares the version APPROVED
- GOTO 1
GEOS-Chem manual updates
GEOS-Chem manual is only re-written for public releases.
But the Appendix 8 of the manual contains addenda for each beta version. You can find there every manual modification applying to each beta version (e.g explanation of new options, the path where to download each version, new data to be downloaded...)
GEOS-Chem debugging tips
When your run dies with an error, the most important thing is to try to isolate the place where the error occurs (i.e. does it die in chemistry, in transport, in dry deposition, etc.)
Here are a list of things that you can try if your run dies w/ an error:
- Look at the log file? Can you tell where the run stopped?
- If not, re-run with the ND70 diagnostic turned on (debug output)
- This will print debug output and should let you pinpoint the location of the error
- Did you run out of time in the queue?
- Did you modify the standard code?
- If so, then focus on your most recent changes
- You should keep a *clean* (unmodified) version for comparison
- Can you isolate the error to a particular operation?
- Turn off operations (e.g. transport, emissions, etc.) one at a time and run again
- Does the error happen consistently?
- If the error happens at the same model date & time, it could indicate bad input data
- If it happened only once, it could be caused by a network problem or other such transient condition
- Also check for math errors
- Is there a division by zero, logarithm of negative number, etc?
- Recompile with -C (or -CB for IFORT compiler) option to check for array-out-of-bounds errors
- Out-of-bounds errors can produce segmentation faults
- When in doubt, print it out!
- Print out the values of variables in the area where you suspect the error lies
- Also use "call flush(6)" to flush the output buffer after writing
- Maybe you will see something wrong in the output
- When all else fails, USE THE BRUTE FORCE METHOD!
- Comment out code until you find where the failure occurs
Reporting GEOS-Chem bugs and problems
If you should encounter a bug or a problem running GEOS-Chem, then please send an email to firstname.lastname@example.org with a description of the problem. Please include the following information:
|GEOS-Chem Version Number||(e.g. v8-01-01)|
|Met field type||(e.g. GEOS-3, GEOS-4, GEOS-5, GCAP)|
|Horizontal Resolution||(e.g. 4x5, 2x25, 1x1)|
|Type of Simulation||(e.g. full-chemistry, Hg, Tagged CO )|
|Platform||(e.g. Altix, SGI-Origin, Linux box)|
|Compiler||(e.g. IFORT, Sun, SGI Mips, PGI ...)|
|Number of Processors|
|Diagnostics Requested||(e.g. ND28, ND43, ND45, etc.)|
|Description of problem|
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.