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; and

  3. Clones 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.

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: