GEOS–Chem Support Staff

1. GEOS–Chem Model Clinic / Q & ABob YantoscaSoftware EngineerAtmospheric Chemistry Modeling GroupHarvard UniversityPhilippe Le SagerResearch AssociateAtmospheric Chemistry Modeling GroupHarvard University

2. GEOS–Chem Support Staff • Bob Yantosca (Software Engineer) and Philippe Le Sager (Research Associate) 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 Philippe. • 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 user groups the research topics they are working on, please visit the GEOS–Chem People & Projects page:http://www.as.harvard.edu/chemistry/trop/geos/

3. Documentation and Information • GEOS–Chem information will be disseminated via the mailing list • Please make sure that you have subscribed! • GEOS–Chem documentation and other resources are online! • GEOS–Chem users’ manual • GEOS–Chem programming style guide • Information about running GEOS–Chem on various platforms • Information about how to parallelize code with OpenMP commands • List of available met fields that can be used for GEOS–Chem simulations • List of GEOS–Chem related publications • Links to Fortran and IDL tutorial sites • Links to presentations from previous GEOS–Chem user meetings • TESTRUN — a script package for submitting GEOS–Chem runs via queues • GAMAP — our IDL visualization package for viewing GEOS–Chem output!

4. GEOS–Chem User Expectations • We expect all GEOS–Chem users to: • Have a working knowledge of Fortran, IDL, and Unix scripts • Be familiar with some basic debugging practices • Be familiar with the compiler commands for your given platform(s) • BE RESOURCEFUL! Try to exhaust all possible debugging options before asking Philiippe & Bob for assistance. • We encourage all users to: • “Discuss amongst yourselves” – especially those of you who are working with the same type of GEOS–Chem simulations • Use the GEOS–Chem email list to contact other GEOS–Chem users • Keep us updated as to the status of any GEOS–Chem related publications or other developments • Update to the latest GEOS–Chem version at the start of a new project

5. GEOS–Chem 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 Bob & Philippe and request that your changes be included in the standard code Bob & Philippe will add your changes to the standard code and benchmark it Daniel approves the benchmark results and declares the version APPROVED GOTO 1

6. GEOS–Chem Versions Public Releases • Each GEOS–Chem public release is benchmarked with both a 1-month benchmark and a 1-year benchmark before it is released to the user community.  • Daniel Jacob is currently responsible for examining the results of all GEOS–Chem benchmark simulations. • The GEOS–Chem users’ guide is updated for each new public release. Internal Releases • Not all GEOS–Chem revisions are released to the user community at large.  Some revisions are necessary for testing purposes.  • Also, if many changes to the code are required, it is often expedient to stretch these changes over several revisions, so that each individual revision can be fully tested and benchmarked. • Each internal release is tested with a 1-month benchmark simulation. • You are free to use Internal Releases, but they come “as-is”!

7. Considerations for GEOS–Chem Developers GEOS–Chem is a GRASSROOTS model • The research needs of our users drive GEOS–Chem development • We don’t have every possible type of simulation or diagnostic in the code “Offline” chemistry simulations • Philippe & Bob are responsible for maintaining the fullchem simulation • However, GEOS–Chem users are responsible for maintaning offline sims • Hg, CO, CO2, Ox, Rn/Pb/Be, offline dust & aerosols, CH3I, CH4, etc. • We do not have the resources to benchmark these simulations. We can, however, add your revisions into the std code and then ask for your help in evaluating if the model is producing correct results. • Be aware that some offline simulations may need updating with the latest new emissions or other such data files. • Also be aware that if the model does not have a particular diagnostic, you might have to add that in yourself.

8. Considerations for GEOS–Chem Developers Be aware that GEOS–Chem contains some “historical baggage” • In the past, we have ingested code in an “as-is” fashion from many sources • GEOS–Chem uses a number of 3rd-party code packages: • SMVGEAR, TPCORE, ISORROPIA, MARES, FAST-J, etc. • In many cases the original code structure was preserved, resulting in: • COMMON blocks • confusing nomenclature • confusing subroutine calling sequences • inadequate documentation When writing new code … • Avoid putting “spaghetti layers” atop of historical baggage • Use newer Fortran 90 language features • Add LOTS and LOTS of documentation !!

9. Considerations for GEOS–Chem Developers Restructuring of GEOS-Chem for ESMF compliance • GEOS–Chem will soon be rewritten for compatibility with the Earth System Model Framework (ESMF) – to allow interchangeability w/ NASA codes • Certain coding structures will be phased out for ESMF compliance • Variables will have to be passed as arguments for ESMF compliance • Transition from OpenMP (shared memory) to MPI (distributed memory) parallelization will require the separation of file I/O from the places where we do computations • Nomenclature will need to be updated to standard conventions (e.g. CF) • File format may be switched from binary to netCDF / HDF / HDF–EOS • And various other technical things not mentioned here … • If you can avoid using COMMON blocks and to try to structure your code to accept inputs via arguments, then that will help us out!

10. GEOS–Chem Debugging Tips • Take a good look at the log file • Many errors will be recognizeable by the text “GEOS–Chem ERROR!” in the log file. Sometimes the cause of error will be readily apparent (i.e. file not found, etc.) • Other types of errors (e.g. system errors, network errors, arithmetic exceptions, etc.), can be a little harder to diagnose. • Turn on extra debug output with ND70 diagnostic. • Did you modify the standard code? • If so, then focus on your most recent changes • You should always keep a clean (unmodified) version for comparison • Can you isolate the error to a particular operation? • Does the error occur in transport, chemistry, drydep, wetdep, … ?

11. GEOS–Chem Debugging Tips • 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 • Check for math errors • Is there a division by zero, logarithm of negative number, etc? • On Sun compiler, setting –fast optimization automatically will check for various kinds of math errors • Check for array-out-of-bounds errors • Recompile with –C (or –CB on Altix) option to check for array-out-of-bounds errors • Out-of-bounds errors can produce segmentation faults

12. GEOS–Chem Debugging Tips • When in doubt, print it out! • Print the values of variables in the area where you suspect the error lies • Use MINVAL, MAXVAL, SUM to print out min, max, sum of arrays • 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 • This is the method of last resort, but it will always work! • DON’T PANIC !!

13. Reporting GEOS–Chem bugs and errors • If you should encounter a bug or a problem running GEOS-Chem, then please contact both Bob and Philippe with a description of the problem. • Please include the following information: • GEOS-Chem Version # (e.g. v7–03–06, v7–04–01) • Met field type (e.g. GEOS-3, GEOS-4, 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 • Error Message • also, if possible, please attach a copy of the log file from the simulation.

14. Providing Emissions, etc. data For inclusion into GEOS–Chem • We ask that you provide us with the following: • The “raw” data files (e.g. on 0.5 x 0.5 or 1 x 1 grids) • References to journal articles or other documentation for the “raw” data • Any IDL or other code used to process the “raw” data files • The processed data files (at 2 x 2.5 or 4 x 5) for use with GEOS–Chem • A short description of the steps involved in going from the “raw” data to the “processed” data Rationale: • The reason we ask for all of this is because we need to have all of the machinery preserved so that we can reprocess the data at a later time. (For example, upon release of a new “raw” data version) • In the past, people have created data sets and then have moved on to other jobs or positions. Then we couldn’t contact them when we had to later on try to figure out what they actually did. We want to avoid this in the future!

15. Question and Answer Session • Philippe and Bob will take your questions on: • GEOS–Chem • GAMAP • TESTRUN • Unix Scripts • Simulation specifics • Or anything model-related !!