Download the model

The GCHP source code is hosted at https://github.com/geoschem/GCHP. To clone the repository and checkout all git submodules for the latest release:

gcuser:~$ git clone --recurse-submodules https://github.com/geoschem/GCHP.git GCHP

The GCHP repository has git submodules (other repositories that are nested inside the GCHP repository) that aren’t automatically retrieved when you do git clone. The --recurse-submodules option tells Git to finish retrieving the source code for each submodule. It will also initialize and update each submodule’s source code to the proper place in its version history. You can also download and checkout the git submodules in two steps if you prefer:

gcuser:~$ git clone https://github.com/geoschem/GCHP.git GCHP
gcuser:~$ git submodule update --init --recursive

By default, the source code will be on the main branch which is always the last official release of GCHP. Checking out the official release is recommended because it is a scientifically-validated version of the code and is easily citable. You can find the list of past and present GCHP releases on the GEOS-Chem versions page.

If you wish to use an older version of GCHP then you can checkout a version tag and then update the git submodules. Here is an example of downloading and checking out version 14.2.1:

gcuser:~$ git clone https://github.com/geoschem/GCHP.git GCHP
gcuser:~$ git tag                   # browse available version tags
gcuser:~$ git checkout tags/14.2.1
gcuser:~$ git submodule update --init --recursive

Before continuing, it is worth checking that the source code was retrieved correctly. Run git status to check that there are no differences. You can also run git log to see the recent git history, or open a gitk window to browse the history using a graphical user interface.

gcuser:~/GCHP$ git status
HEAD detached at 14.2.1
nothing to commit, working tree clean
gcuser:~/GCHP$ git log
gcuser:~/GCHP$ gitk &

The output of git status should confirm your GCHP version and that there are no modifications (nothing to commit, and a clean working tree). It also says that you are are in detached HEAD state, meaning you are not in a GCHP git software branch. This is true for all submodules in the model as well. If you plan to make changes to the source code then you must checkout a new branch within whatever submodules you plan to develop. Here is an example for developing GEOS-Chem.

gcuser:~/GCHP$ cd src/GCHP_GridComp/GEOSChem_GridComp/geos-chem
gcuser:~/GCHP$ git status
HEAD detached at c4c4c146e
nothing to commit, working tree clean
gcuser:~/GCHP$ git checkout -b feature/model_dev