GEOS-Chem v10-01 Online User's Guide
Previous | Next
| Printable View (no frames)
7. 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.
7.1 Coding: Practice and Style
GEOS-Chem source code is written in Fortran-90. Two different program units comprise the GEOS-Chem source code:
Traditional subroutines and functions (*.F): 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).
Note that the *.F90 extension denotes free-format Fortran-90 layout, as opposed to the 72-character fixed format layout in files with the *.Fextension. Also note that all header files (*.h) were either removed or replaced with Fortran-90 modules in GEOS-Chem v9-02.
We have attempted to create a clear and consistent programming style for 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
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 Appendix 7: GEOS-Chem 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 Parallelizating 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.
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. For GEOS-Chem v10-01, this includes the new HEMCO.log file which will help you determine if the issue is related to reading an emissions inventory.
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 v10-01. For a list of all GEOS-Chem bug fixes and updates in v10-01, please see the GEOS-Chem v10-01 wiki page. For a complete history of GEOS-Chem updates, see the GEOS-Chem versions under development wiki page. You can also look at the Git history of your code. See Section 7.3 below on using Git with GEOS-Chem for resources on how to do this.
If you find a pre-existing bug in GEOS-Chem v10-01, please alert the GEOS-Chem Support Team so that we may fully address it.
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 the GEOS-Chem Support Team for help. Contact information for the GEOS-Chem Support Team is located on the GEOS-Chem Support Team wiki page. We request that you read the Responsibilities of the GEOS-Chem User Community section of our wiki page prior to contacting us to ensure that we are the most appropriate group to help you with your problem.
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 wiki page, Using Git with GEOS-Chem wiki page, and the Using Git with GAMAP wiki page for more information about using Git with GEOS-Chem. Quick links to subsections of these wiki pages are included below:
You can also find out more about Git by visiting the Git web page: http://www.git-scm.com.