This repository (https://github.com/geoschem/geos-chem) contains the source code for the GEOS-Chem model of atmospheric chemistry and composition.

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.

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.

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):

The GEOS-Chem web site is a good place to get started. It will point you to many important GEOS-Chem resources.

• http://www.geos-chem.org

You can find the The GEOS-Chem User's Guide online here:

• http://manual.geos-chem.org

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.

• http://wiki-geos.chem.org

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.

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 [email protected].

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 [email protected]