README for the GEOS-Chem source code repository
This repository (https://github.com/geoschem/geos-chem) contains the source code for the GEOS-Chem model of atmospheric chemistry and composition.
GEOS-Chem Development
Branches
This repository contains several branches. Each branch contains code updates belonging to a particular line of development.
-
The master branch always contains the current stable version. You should never add new code directly into this branch. Instead, open a new branch off of master and add your code there.
-
The dev/X.Y.Z branches always contains in-development code for upcoming version X.Y.Z. Code in dev/X.Y.Z is very much "work in progress" and should not be relied upon until it has been fully debugged, validated, and merged back into the master branch.
-
The GEOS branch contains updates that are specific to the interface between GEOS-Chem and the NASA GEOS-DAS Earth System Model. Most GEOS-Chem users can simply ignore this branch.
-
From time to time, you will see other branches pertaining to new lines of development being created. These branches usually will start with feature/ or bugfix/. Once the code in these branches has been sufficiently validated, these branches will be merged back into the master branch. You should not use code in these branches.
Versions
GEOS-Chem versions are now denoted by 3 digits (X.Y.Z):
- The X digit is the major version number. A change in X denotes that the current version contains a significant update that breaks backwards-compatibility with the prior series of GEOS-Chem versions. Major structural updates typically will require an update to X. In the past we have changed the X digit when replacing SMVGEAR with FlexChem (version 10 to version 11) and replacing legacy emissions with HEMCO (version 9 to version 10).
-
The Y digit is the feature version number. A change in Y denotes that a 1-month benchmark has been performed to validate a new feature or set of features. Some (but not all) Y versions will have 1-year benchmarks performed as well. In general, the Y digit changes whenever a new feature breaks backwards compatibility with one or more run directories from the prior version.
-
The Z digit is the bug fix (or patch) version number. A change in Z denotes that a bug fix was made that does not break backwards compatibility with run directories from the prior verison. Z will also be updated when bug fixes or minor updates are made to one or more of the GEOS-Chem "Specialty" simulations. Updating specialty simulations should not affect the output of the GEOS-Chem 1-month or 1-year benchmark simulations.
For more information, please see this wiki page: http://wiki.geos-chem.org/GEOS-Chem_version_numbering_system
All benchmarked GEOS-Chem versions are tagged in the Git history. Use git tag in your terminal to see a list of available tags. Tags will also be highlighted in the gitk browser window.
Citing GEOS-Chem versions with DOI's
You can now cite GEOS-Chem in publications with a Digital Object Identifier (DOI). Each GEOS-Chem release will be assigned its own individual DOI. DOI's for each GEOS-Chem version will be posted on the GEOS-Chem website and GEOS-Chem wiki.
We have also generated a concept DOI, which will always point to the current stable version of GEOS-Chem (i.e. corresponding to the master branch):
Documentation
Web site
The GEOS-Chem web site is a good place to get started. It will point you to many important GEOS-Chem resources.
Online user's manual
You can find the The GEOS-Chem User's Guide online here:
Wiki
The most up-to-date information about GEOS-Chem is posted on the GEOS-Chem wiki. Here you will find information about technical issues, bug fixes, and other pertinent topics.
GEOS-Chem run directories
To generate GEOS-Chem run directories, please clone the geos-chem-unittest repository and follow the instructions as listed on the Creating GEOS-Chem run directories wiki page.
Support
We encourage GEOS-Chem users to use the Github issue tracker attached to this repository to report bugs or technical issues with the GEOS-Chem code.
You are also invited to direct GEOS-Chem support requests to the GEOS-Chem Support Team at geos-chem-support@g.harvard.edu.
License
GEOS-Chem (and related software) is distributed under the MIT license. Please see the license documents LICENSE.txt and AUTHORS.txt in the root folder.
14 Nov 2018 GEOS-Chem Support Team geos-chem-support@g.harvard.edu