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:
Clones the GCClassic repo from GitHub to a local folder named
GCClassic
;Clones the GEOS-Chem “Science Codebase” repo from GitHub to
GCClassic/src/GEOS-Chem
;Clones the HEMCO repo from GitHub to
GCClassic/src/HEMCO
;Clones the Cloud-J repo from GitHub to
GCClassic/src/Cloud-J
;Clones the ISORROPIA/HETP repo from GitHub to
GCClassic/src/HETP
; andClones 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:
Getting started with GEOS-Chem 13 (by Melissa Sulprizio)
Managing branches between superproject and submodules (by Bob Yantosca)