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
; andClones the HEMCO repo from GitHub to
GCClassic/src/HEMCO
.
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:
Cloning into 'GCClassic'...
remote: Enumerating objects: 2680, done.
remote: Counting objects: 100% (1146/1146), done.
remote: Compressing objects: 100% (312/312), done.
remote: Total 2680 (delta 858), reused 1099 (delta 825), pack-reused 1534
Receiving objects: 100% (2680/2680), 1.74 MiB | 13.16 MiB/s, done.
Resolving deltas: 100% (1411/1411), done.
Submodule 'docs/source/geos-chem-shared-docs' (https://github.com/geoschem/geos-chem-shared-docs.git) registered for path 'docs/source/geos-chem-shared-docs'
Submodule 'src/GEOS-Chem' (https://github.com/geoschem/geos-chem.git) registered for path 'src/GEOS-Chem'
Submodule 'src/HEMCO' (https://github.com/geoschem/hemco.git) registered for path 'src/HEMCO'
Cloning into '/local/ryantosca/GC/rundirs/epa-kpp/tmp/GCClassic/docs/source/geos-chem-shared-docs'...
remote: Enumerating objects: 148, done.
remote: Counting objects: 100% (148/148), done.
remote: Compressing objects: 100% (103/103), done.
remote: Total 148 (delta 77), reused 116 (delta 45), pack-reused 0
Receiving objects: 100% (148/148), 162.29 KiB | 2.90 MiB/s, done.
Resolving deltas: 100% (77/77), done.
Cloning into '/local/ryantosca/GC/rundirs/epa-kpp/tmp/GCClassic/src/GEOS-Chem'...
remote: Enumerating objects: 75574, done.
remote: Counting objects: 100% (410/410), done.
remote: Compressing objects: 100% (187/187), done.
remote: Total 75574 (delta 238), reused 364 (delta 216), pack-reused 75164
Receiving objects: 100% (75574/75574), 85.23 MiB | 30.59 MiB/s, done.
Resolving deltas: 100% (62327/62327), done.
Cloning into '/local/ryantosca/GC/rundirs/epa-kpp/tmp/GCClassic/src/HEMCO'...
remote: Enumerating objects: 3178, done.
remote: Counting objects: 100% (638/638), done.
remote: Compressing objects: 100% (195/195), done.
remote: Total 3178 (delta 476), reused 585 (delta 438), pack-reused 2540
Receiving objects: 100% (3178/3178), 2.24 MiB | 11.87 MiB/s, done.
Resolving deltas: 100% (2270/2270), done.
Submodule path 'docs/source/geos-chem-shared-docs': checked out '228507857eb53740dacf4055ce9268aa8ccf520d'
Submodule path 'src/GEOS-Chem': checked out '7e51a0674aba638c8322fef493ac9251095e8cf4'
Submodule path 'src/HEMCO': checked out '4a66bae48f33e6dc22cda5ec9d4633192dee2f73'
Submodule 'docs/source/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 '/local/ryantosca/GC/rundirs/epa-kpp/tmp/GCClassic/src/HEMCO/docs/source/geos-chem-shared-docs'...
remote: Enumerating objects: 148, done.
remote: Counting objects: 100% (148/148), done.
remote: Compressing objects: 100% (103/103), done.
remote: Total 148 (delta 77), reused 116 (delta 45), pack-reused 0
Receiving objects: 100% (148/148), 162.29 KiB | 3.00 MiB/s, done.
Resolving deltas: 100% (77/77), done.
Submodule path 'src/HEMCO/docs/source/geos-chem-shared-docs': checked out '645401baa35b6a6838b9bedede309a01a311517f'
When the git clone process has finished, navigate into the
GCClassic
folder and get a directory listing:
$ cd GCClassic
$ ls -CF src/*
and you will see output similar to this:
src/CMakeLists.txt src/gc_classic_version.H@ src/main.F90@
src/GEOS-Chem:
APM/ CMakeScripts/ GeosUtil/ History/ lib/ ObsPack/ run/
AUTHORS.txt doc/ GTMM/ Interfaces/ LICENSE.txt PKUCPL/
bin/ GeosCore/ Headers/ ISORROPIA/ mod/ README.md
CMakeLists.txt GeosRad/ help/ KPP/ NcdfUtil/ REVISIONS
src/HEMCO:
AUTHORS.txt CMakeLists.txt CMakeScripts/ LICENSE.txt README.md run/ src/
This confirms that the GCClassic/src/GEOS-Chem
and
GCClassic/src/HEMCO
folders have been populated with source
code from the GEOS-Chem Science Codebase
and HEMCO GitHub repositories.
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
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.
Instead of feature/my-git-updates
, you may choose a name that reflects
the nature of your updates (e.g. feature/new_reactions
, 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)