Download instructions

Follow these directions to download the GEOS-Chem Classic source code.

Clone GCClassic and fetch submodules

To download the latest stable GEOS-Chem Classic version, type:

$ git clone --recurse-submodules https://github.com/geoschem/GCClassic.git

This command does the following:

  1. Clones the GCClassic repo from GitHub to a local folder named GCClassic;

  2. Clones the GEOS-Chem “Science Codebase” repo from GitHub to GCClassic/src/GEOS-Chem;

  3. Clones the HEMCO repo from GitHub to GCClassic/src/HEMCO;

  4. Clones the Cloud-J repo from GitHub to GCClassic/src/Cloud-J;

  5. Clones the ISORROPIA/HETP repo from GitHub to GCClassic/src/HETP; and

  6. Clones the geos-chem-shared-docs from GitHub to GCClassic/docs/source/geos-chem-shared-docs.

Tip

To download GEOS-Chem Classic source code into a folder named something other than GCClassic, supply the name of the folder at the end of the git clone command. For example:

git clone --recurse-submodules https://github.com/geoschem/GCClassic.git my-code-dir

will download the GEOS-Chem Classic source code into my-code-dir instead of GCClassic.

Once the git clone process starts, you should see output similar to this:

$ git clone https://github.com/geoschem/GCClassic.git
Cloning into 'GCClassic'...
remote: Enumerating objects: 4410, done.
remote: Counting objects: 100% (1309/1309), done.
remote: Compressing objects: 100% (629/629), done.
remote: Total 4410 (delta 714), reused 1257 (delta 676), pack-reused 3101
Receiving objects: 100% (4410/4410), 2.10 MiB | 8.12 MiB/s, done.
Resolving deltas: 100% (2377/2377), done.
Submodule 'geos-chem-shared-docs' (https://github.com/geoschem/geos-chem-shared-docs.git) registered for path 'docs/source/geos-chem-shared-docs'
Submodule 'Cloud-J' (https://github.com/geoschem/Cloud-J.git) registered for path 'src/Cloud-J'
Submodule 'GEOS-Chem' (https://github.com/geoschem/geos-chem.git) registered for path 'src/GEOS-Chem'
Submodule 'HEMCO' (https://github.com/geoschem/hemco.git) registered for path 'src/HEMCO'
Submodule 'src/HETerogeneous-vectorized-or-Parallel' (https://github.com/geoschem/HETerogeneous-vectorized-or-Parallel) registered for path 'src/HETP'
Cloning into '/n/holyscratch01/jacob_lab/ryantosca/tests/14.4.0/release/example/docs/source/geos-chem-shared-docs'...
remote: Enumerating objects: 356, done.
remote: Counting objects: 100% (110/110), done.
remote: Compressing objects: 100% (71/71), done.
remote: Total 356 (delta 66), reused 79 (delta 39), pack-reused 246
Receiving objects: 100% (356/356), 524.63 KiB | 8.46 MiB/s, done.
Resolving deltas: 100% (205/205), done.
Cloning into '/n/holyscratch01/jacob_lab/ryantosca/tests/14.4.0/release/example/src/Cloud-J'...
remote: Enumerating objects: 488, done.
remote: Counting objects: 100% (149/149), done.
remote: Compressing objects: 100% (56/56), done.
remote: Total 488 (delta 104), reused 102 (delta 93), pack-reused 339
Receiving objects: 100% (488/488), 715.91 KiB | 9.67 MiB/s, done.
Resolving deltas: 100% (241/241), done.
Cloning into '/n/holyscratch01/jacob_lab/ryantosca/tests/14.4.0/release/example/src/GEOS-Chem'...
remote: Enumerating objects: 88738, done.
remote: Counting objects: 100% (8421/8421), done.
remote: Compressing objects: 100% (2309/2309), done.
remote: Total 88738 (delta 6574), reused 7742 (delta 6093), pack-reused 80317
Receiving objects: 100% (88738/88738), 98.58 MiB | 11.35 MiB/s, done.
Resolving deltas: 100% (72704/72704), done.
Cloning into '/n/holyscratch01/jacob_lab/ryantosca/tests/14.4.0/release/example/src/HEMCO'...
remote: Enumerating objects: 4752, done.
remote: Counting objects: 100% (1546/1546), done.
remote: Compressing objects: 100% (423/423), done.
remote: Total 4752 (delta 1177), reused 1426 (delta 1117), pack-reused 3206
Receiving objects: 100% (4752/4752), 2.88 MiB | 21.06 MiB/s, done.
Resolving deltas: 100% (3458/3458), done.
Cloning into '/n/holyscratch01/jacob_lab/ryantosca/tests/14.4.0/release/example/src/HETP'...
remote: Enumerating objects: 97, done.
remote: Counting objects: 100% (97/97), done.
remote: Compressing objects: 100% (69/69), done.
remote: Total 97 (delta 37), reused 68 (delta 21), pack-reused 0
Receiving objects: 100% (97/97), 81.51 KiB | 937.00 KiB/s, done.
Resolving deltas: 100% (37/37), done.
Submodule path 'docs/source/geos-chem-shared-docs': checked out '285d5904561a34d7c7941681a4fed19a68e1201f'
Submodule path 'src/Cloud-J': checked out '3162ea8baa9ab69c3b8473270abc0188ad54501b'
Submodule path 'src/GEOS-Chem': checked out 'c4c4c146ed9cd6bb8af42f080b766a0a0119b4a5'
Submodule path 'src/HEMCO': checked out 'fddcae53f73327e0da7f0a505b4d07a53dd0930b'
Submodule 'geos-chem-shared-docs' (https://github.com/geoschem/geos-chem-shared-docs.git) registered for path 'src/HEMCO/docs/source/geos-chem-shared-docs'
Cloning into '/n/holyscratch01/jacob_lab/ryantosca/tests/14.4.0/release/example/src/HEMCO/docs/source/geos-chem-shared-docs'...
remote: Enumerating objects: 356, done.
remote: Counting objects: 100% (110/110), done.
remote: Compressing objects: 100% (71/71), done.
remote: Total 356 (delta 66), reused 79 (delta 39), pack-reused 246
Receiving objects: 100% (356/356), 524.63 KiB | 8.33 MiB/s, done.
Resolving deltas: 100% (205/205), done.
Submodule path 'src/HEMCO/docs/source/geos-chem-shared-docs': checked out '4bb2b11e35953a8b0a8e1aec9161479bf0fc6bb6'
Submodule path 'src/HETP': checked out '2a99b24625ed26cf87ae88697ddd6cf8bbdec812'

When the git clone process has finished, navigate into the GCClassic folder and get a directory listing:

$ cd GCClassic
$ ls -CF src/*
src/CMakeLists.txt

src/Cloud-J:
AUTHORS.txt   CMakeLists.txt  CONTRIBUTING.md  LICENSE    src/        tables/
CHANGELOG.md  CMakeScripts/   docs/            README.md  SUPPORT.md  tools/

src/GEOS-Chem:
APM/          CMakeLists.txt  GeosRad/   Headers/     KPP/         ObsPack/   run/
AUTHORS.txt   CMakeScripts/   GeosUtil/  History/     LICENSE.txt  PKUCPL/    test/
CHANGELOG.md  GeosCore/       GTMM/      Interfaces/  NcdfUtil/    README.md

src/HEMCO:
AUTHORS.txt   CMakeLists.txt  CONTRIBUTING.md  LICENSE.txt  run/    src/
CHANGELOG.md  CMakeScripts/   docs/            README.md    spack@  SUPPORT.md

src/HETP:
CHANGELOG.md  CMakeLists.txt  CMakeScripts/  LICENSE  README.md  src/

This confirms that the GCClassic/src/GEOS-Chem and GCClassic/src/HEMCO folders have been populated with source code from the GitHub repositories listed above.

Tip

To use an older GEOS-Chem Classic version (e.g. 14.0.0), follow these additional steps:

$ git checkout tags/14.0.0                  # Points HEAD to the tag "14.0.0"
$ git branch version_14.0.0                 # Creates a new branch at tag "14.0.0"
$ git checkout version_14.0.0               # Checks out the version_14.0.0 branch
$ git submodule update --init --recursive   # Reverts submodules to the "14.0.0" tag

You can do this for any tag in the version history. For a list of all tags, type:

$ git tag

If you have any unsaved changes, make sure you commit those to a branch prior to updating versions.

Create a branch in src/GEOS-Chem for your work

Whter the git clone command described above finishes, the GEOS-Chem Science Codebase submodule code (in folder GCClassic/src/GEOS-Chem) and the HEMCO submodule code (in folder GCClassic/src/HEMCO) will be in detached HEAD state. In other words, the code is checked out but a branch is not created. Adding new code to a detached HEAD state is very dangerous and should be avoided. You should instead make a branch it the same point as the detached HEAD, and then add your own modifications into that branch.

Navigate from GCClassic to GCClassic/src/GEOS-Chem:

$ cd src/GEOS-Chem

and then type:

$ git branch

You will see output similar to this:

*(HEAD detached at xxxxxxxx)
main

where xxxxxxxx denotes the hash of the commit at which the code has been checked out.

At ths point, you may now create a branch in which to store your own modifications to the GEOS-Chem science codebase. Type:

$ git branch feature/my-git-updates
$ git checkout feature/my-git-updates

Instead of feature/my-git-updates, you may choose a name that reflects the nature of your updates (e.g. feature/new_reactions, etc.).

Note

This naming convention adheres to the Github Flow conventions (i.e. new feature branches start with feature/, bug fix branches start with bugfix/, etc.

If you now type:

$ git branch

You will see that we are checked out onto the branch that you just created and are no longer in detached HEAD state.

* feature/my-git-updates
main

At this point, you may proceed to add your modifications into the GEOS-Chem Science Codebase.

Note

If you need to also modify HEMCO source code, repeat the process above to create your own working branch in GCClassic/src/HEMCO.

See additional resources

For more information about downloading the GEOS-Chem source code, please see the following Youtube video tutorials: