This repository (https://github.com/geoschem/geos-chem) contains the GEOS-Chem science codebase (aka the GEOS-Chem chemical module). Included in this repository are:
-
The source code for GEOS-Chem science routines;
-
Scripts to create GEOS-Chem run directories;
-
Scripts to run GEOS-Chem tests;
-
Driver routines (e.g. "main.F90") that enable GEOS-Chem to be run in several different contexts, including:
- GEOS-Chem "Classic" (suitable for running with less than ~64 cores on a single node)
- GCHP (GEOS-Chem "High Performance, which can run across multiple nodes for high scalability)
- GEOS-GC (GEOS-Chem coupled to the NASA GEOS ESM)
- WRF-GC (GEOS-Chem coupled with WRF)
- and GEOS-Chem coupled to other Earth System Models (e.g. CESM2, NCAR "next-generation" models, etc.)
One important note: The Harmonized Emissions Component (HEMCO) source code has been removed, and is maintained as a separate repository (geoschem/HEMCO). This is because HEMCO is now being developed independently of GEOS-Chem. This will facilitate HEMCO being used in external models (such as at NOAA and NCAR).
You should not clone geoschem/geos-chem directly. Instead, you should clone one of the "wrapper" repositories:
-
geoschem/GCClassic
-
geoschem/GCHP
which will then treat geoschem/geos-chem (and geoschem/HEMCO for that matter) as a Git submodule. For details, we refer you to our "Getting Started with GEOS-Chem" manual or our Youtube tutorial videos (discussed in the Documentation section below).
This repository contains several branches. Each branch contains code updates belonging to a particular line of development.
-
The main branch always contains the current stable version. You should never add new code directly into this branch. Instead, open a new branch off of main 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.
-
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.
-
You may also see branches beginning with e.g. GEOS, CESM, etc. These branches are intended for ongoing development to connect GEOS_Chem within other Earth System Models. You may ignore the 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.
You can find the The GEOS-Chem User's Guide online here:
NOTE: The above link currently points to Getting Started with GEOS-Chem on the GEOS-Chem wiki. In the near future, we will migrate this documentation to readthedocs.io.
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.
We have created several tutorial videos at our GEOS-Chem Youtube channel (https://youtube.com/c/geos-chem). Please take a few moments to view the following tutorials
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.
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.
06 Jan 2021 GEOS-Chem Support Team [email protected]