# Quick Start¶

This quickstart guide assumes your environment satisfies GCHP’s requirements. This means you should load a compute environment such that programs like cmake and mpirun are available, before continuing. You can find more detailed instructions 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 submodules:

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 for it is in the top-level of the source code: gcuser:~/GCHP$ mkdir ~/GCHP/build
gcuser:~/GCHP$cd ~/GCHP/build  Initialize your build directory by running cmake and 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: 1. Navigate to your build directory. 2. Update your build settings with cmake. See 3. Recompile with make -j. Note that the build system automatically figures out what (if any) files need to be recompiled. 4. 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 configured in ./runConfig.sh. You should review this file as it explains how to configure most simulation 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 you use to launch the gchp executable that is in your run directory. You’ll need 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 will write a script that runs GCHP, and then you will submit that script to your scheduler. 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.