GEOS-Chem Online User's Guide

Previous | Next | Printable View (no frames)

8. Coding and Debugging

In this chapter we provide guidelines and resources for developing GEOS-Chem source code routines, debugging GEOS-Chem, and using Git version control software.

8.1 Coding: Practice and Style

GEOS-Chem source code is written in Fortran 90.

Files with the .F90 extension are free-format Fortran-90 layout while files with the .F extension are 72-character fixed format Fortran 77 layout. Each file falls into one of two categories:

Traditional subroutines and functions (*.F and *.F90 files): Each of these files contains one subroutine or function. The majority of these subroutines and functions come from third-party packages (e.g. FAST-J and SMVGEAR).
Fortran-90 modules (*_mod.F and *_mod.F90 files): Each of these files bundles global variables, subroutines, and functions into a coherent package that can be shared by other program units. Modules may contain dynamically allocatable arrays, which are more memory-efficient than the older Fortran 77 common blocks. Most GEOS-Chem source code files are now modules.

We strive for a clear and consistent programming style for all GEOS-Chem subroutines and modules. Some of our style points include:

Header lists of arguments and modification history in ProTeX format for all modules, subroutines, and functions to enable automated documentation generation
References to other variables or routines contained within modules
Use of IMPLICIT NONE to force explicit declaration of all variables
Comments aligned with mode -- major sections denoted by !=====
Copious use of white space to enhance readability
Indentation of IF-THEN-ELSE and DO-ENDDO blocks
OpenMP parallel DO-loops
Use of Fortran derived type objects to efficiently pass data between subroutines

We ask that you strive to maintain these style points as you develop GEOS-Chem. For more information on GEOS-Chem coding style, please read the GEOS-Chem coding style guide.

In addition, when making upgrades to the code, we recommend blocking off the section that you are replacing with comment characters (!), and labeling it with text Prior to MM/DD/YY. You can remove the blocked off section once your modified code has been declared stable.

Note that GEOS-Chem uses OpenMP parallelization to gain computational advantage by using several CPUs. OpenMP parallel loop directive syntax is different for *.F90 and *.F files and parallelization bugs can be difficult to detect. Please read the Parallelizing GEOS-Chem wiki page to learn how to correctly implement OpenMP parallel loops. For more information about OpenMP parallelization, please visit the OpenMP web page: openmp.org.

8.2 Debugging GEOS-Chem

The GEOS-Chem model evolves constantly. Our rapidly increasing user base frequently submits updates and new features for inclusion into the standard GEOS-Chem repository. As with any software project, mistakes are inevitable.

The bugs you may encounter (or inadvertently create) when working on GEOS-Chem fall into two categories:

True bugs, including typos, omissions, reading the wrong file, or other outright mistakes.
Design limitation bugs, defined as code written in such a way that precludes future expansion.

You can usually rectify the bugs of the first category easily once you find where they are. Fixing these usually means correcting incorrect syntax, updating an incorrect numerical value, or reading from the proper file. When diagnosing these types of bugs, we recommend that you first look at all log files generated during your run to identify the problem area. This includes checking the HEMCO.log file which will help you determine if the issue is related to reading an emissions inventory. You may enable more detailed output to the log files by turning on ND70 in input.geos and setting both WARNINGS and VERBOSE to 3 in HEMCO_Config.rc, and then rerunning with debug compiler flags (TRACEBACK=y FPE=y BOUNDS=y DEBUG=y).

Design limitation bugs are trickier to address. You may find that your simulation works perfectly—until you try to add in a new species, reaction, offline chemistry simulation, diagnostic, or third-party code package. You may have to invest significant time and effort in modifying GEOS-Chem before it finally does what you want.

For help with debugging, please see the following GEOS-Chem wiki pages:

In addition, browsing recent changes to the code and past bug fixes may help you troubleshoot your own issues encountered while developing GEOS-Chem. For a detailed list of GEOS-Chem updates and bug fixes, see the GEOS-Chem versions under development wiki page. You can also look at the Git history of your code for a complete history. See the Using Git with GEOS-Chem wiki page for resources on how to do this.

If you find a bug in GEOS-Chem, please alert the GEOS-Chem Support Team so that it may be fully addressed.

If you have a problem and cannot arrive at a solution even after exhausting the resources in the GEOS-Chem User's Manual and the GEOS-Chem wiki, you may reach out to the GEOS-Chem Support Team for assistance. We request that you read the Responsibilities of the GEOS-Chem User Community wiki post prior to contacting us to ensure that we are the most appropriate group to help you with your problem.

8.3 Using Git with GEOS-Chem

Git is a distributed revision control system that is freely distributed under the GNU General Public License version 2. You may use Git to obtain copies of the GEOS-Chem source code repository and to develop GEOS-Chem software under version control.

Please see the Version control with Git, Using Git with GEOS-Chem, and the Using Git with GAMAP wiki pages for more information about using Git with GEOS-Chem. Quick links to subsections of these wiki pages are included below:

Version control with Git :
Using Git with GEOS-Chem:

You can also find out more about Git by visiting the Git web page: http://www.git-scm.com.