Quickstart Guide¶
This quickstart guide assumes your environment satisfies GCHP’s requirements. This means you should load a compute environment so that programs like cmake and mpirun are available before continuing. If you do not have some of GCHP’s software dependencies, you can find instructions for installing GCHP’s external dependencies in our Spack instructions. More detailed instructions on downloading, compiling, and running GCHP can be found in the User Guide.
1. Clone GCHP¶
Download the source code:
gcuser:~$ git clone https://github.com/geoschem/GCHP.git ~/GCHP
gcuser:~$ cd ~/GCHP
Checkout the GEOS-Chem version that you want to use:
gcuser:~/GCHP$ git checkout 13.0.0-beta.1
Note
Version 13 is not officially released yet. Until then, the most recent
commit to main
is the most stable version of GCHP. Therefore,
we recommend you checkout main
, rather than a version
like 13.0.0-beta.1
. E.g.:
$ git checkout main # recommended until version 13 is officially released
Once version 13 is released, we will resume recommending users checkout a specific version.
Initialize and update all the submodules:
gcuser:~/GCHP$ git submodule update --init --recursive
2. Create a run directory¶
Navigate to the run/
subdirectory.
To create a run directory, run ./createRunDir.sh
and answer the prompts:
gcuser:~/GCHP$ cd run/
gcuser:~/GCHP$ ./createRunDir.sh
3. Configure your build¶
Create a build directory and cd into it.
A good name for this directory is build/
, and a good place to put it is the
top-level of the source code:
gcuser:~/GCHP$ mkdir ~/GCHP/build
gcuser:~/GCHP$ cd ~/GCHP/build
Initialize your build directory by running cmake, passing it the path to your source code:
gcuser:~/GCHP/build$ cmake ~/GCHP
Now you can configure build options.
These are persistent settings that are saved to your build directory.
A common build option is -DRUNDIR
.
This option lets you specify one or more run directories that GCHP is “installed” to when you do make install.
Configure your build so it installs GCHP to the run directory you created in Step 2:
gcuser:~/GCHP/build$ cmake . -DRUNDIR="/path/to/your/run/directory"
Note
The .
in the cmake command above is important. It tells CMake that your
current working directory (i.e., .
) is your build directory.
4. Compile and install¶
Compiling GCHP takes about 20 minutes, but it can varry depending on your system. Next, compile GCHP:
gcuser:~/GCHP/build$ make -j
Next, install the compiled executable to your run directory (or directories):
gcuser:~/GCHP/build$ make install
This copies bin/gchp
and supplemental files to your run directory.
Note
You can update build settings at any time:
Navigate to your build directory.
Update your build settings with cmake. See
Recompile with make -j. Note that the build system automatically figures out what (if any) files need to be recompiled.
Install the rebuilt executable with make install.
5. Configure your run directory¶
Now, navigate to your run directory:
$ cd path/to/your/run/directory
Most simulation settings are set in ./runConfig.sh
.
You should review this file as it explains most settings.
Note that ./runConfig.sh
is actually a helper script that updates other configuration files.
Therefore, you need to run it to actually apply the updates:
$ vim runConfig.sh # edit simulation settings here
$ ./runConfig.sh # applies the updated settings
6. Run GCHP¶
Running GCHP is slightly different depending on your MPI library (e.g., OpenMPI, Intel MPI, MVAPICH2, etc.) and scheduler (e.g., SLURM, LSF, etc.). If you aren’t familiar with running MPI programs on your system, see Running GCHP in the user guide, or ask your system administrator.
Your MPI library and scheduler will have a command for launching MPI programs—it’s usually something like mpirun, mpiexec, or srun. This is the command that you will use to launch the gchp executable. You’ll have to refer to your system’s documentation for specific instructions on running MPI programs, but generally it looks something like this:
$ mpirun -np 6 ./gchp # example of running GCHP with 6 slots with OpenMPI
It’s recommended you run GCHP as a batch job. This means that you write a (bash) script that runs your GCHP simulation, and then you submit that script to your scheduler (SLURM, LSF, etc.).
Note
When GCHP runs, partially or to completion, it generates several files including
cap_restart
and gcchem_internal_checkpoint
. Subsequent runs won’t
overwrite these files, and instead the run will exit with an error. Because of this it is
common to do
$ rm -f cap_restart gcchem_internal_checkpoint
before starting a GCHP simulation.
Those are the basics of using GCHP! See the user guide, step-by-step guides, and reference pages for more detailed instructions.