Building GCHP with CMake (draft)
These instructions can be used for GC-Classic and GCHP.
Setting things up
1. Pick your compilers.
FC environment variables define the programs that compile C, C++, and Fortran code. Set these to your preferred compilers in
~/.bashrc (or similar).
# Environment's compilers export FC=ifort export CC=icc # only required for GCHP export CXX=icpc # only required for GCHP
Note: For those that are familiar with MPI, these don't have to be your MPI's compiler wrappers.
2. Make sure your environment satisfies GEOS-Chem's requirements.
The following are GC-Classics's requirements. Make sure the following libraries and software are available in your environment.
- CMake (version 3.5 or greater)
- NetCDF-C (version 4.0 or greater)
- NetCDF-Fortran (version 4.0 or greater)
The following are the additional requirements of GCHP.
- An MPI library (OpenMPI, MVAPICH2, MPICH, and SGI MPT).
- gFTL (version 1.0 or greater)
- ESMF (version 8.0 or greater)
- You can use the binaries from a previous GCHP build for this as long as that build's ESMF version is 8.0 or greater. Otherwise you'll have to install ESMF separately using their instructions.
3. Specify where GEOS-Chem's dependencies are installed.
The easiest way to tell CMake where GEOS-Chem's dependencies are found is with the
gFTL_ROOT environment variables. Later, when you configure the build, CMake is going to search the paths you specify in these variables to find GEOS-Chem's dependencies' files. Multiple paths can be specified with a semicolon-separated list.
NetCDF_Fortran_ROOT are not required if
nc-config --prefix and
nf-config --prefix are available.
Set these variables in
~/.bashrc (or similar).
# Paths to dependencies export NetCDF_C_ROOT=/software/netcdf/4.6.1 # only required if nc-config is not available export NetCDF_Fortran_ROOT=/software/netcdf-fortran/4.4.4 # only required if nf-config is not available export ESMF_ROOT="/software/ESMF/8.0.0;/home/liam/ESMF/src" # only required for GCHP export gFTL_ROOT=/software/gFTL # only required for GCHP
ESMF_ROOT should be set to ESMF's install prefix and the path to the ESMF source code (which is
$ESMF_DIR in some environments).
In the snippet above,
/software/ESMF/8.0.0 is ESMF's install prefix and
/home/liam/ESMF/src is the path to the ESMF source code.
Expand this box for more info on
|Variable||Required for||Search files||Comments|
4. Reload your environment.
~/> source ~/.bashrc
Getting GEOS-Chem's source code
1. Clone the GEOS-Chem source code and checkout
~/> git clone https://github.com/LiamBindle/geos-chem.git ~/> cd geos-chem ~/geos-chem/> git checkout feature/CMake
2. Clone the GCHP source code as a subdirectory of the GEOS-Chem source code and checkout
feature/CMake. (Only required for GCHP)
~/geos-chem/> git clone https://github.com/LiamBindle/gchp.git GCHP ~/geos-chem/> cd GCHP ~/geos-chem/GCHP/> git checkout feature/CMake
Note: Make sure the name of the GCHP repo is
Building GCHP or GC-Classic
If you're new to CMake and would like a rundown of how to use the
cmake command, check out my tutorial. Doing the tutorial isn't necessary, but if anything here looks like magic, I'd recommend it. I've been told it takes about 30-45 minutes to complete.
feature/CMake branch is version 12.4.0. These instructions assume you've already created a 12.4.0 run directory for GC-Classic or GCHP.
1. Navigate to your run directory.
~/geos-chem/GCHP/> cd ~/rundirs/gchp_standard
Note: Navigate to a GC-Classic run directory, like
geosfp_4x5_standard, to build GC-Classic instead.
2. Create a build directory and
cd into it.
~/rundirs/gchp_standard/> mkdir build ~/rundirs/gchp_standard/> cd build
3. Initialize your build directory.
~/rundirs/gchp_standard/build/> cmake ~/geos-chem
Note: The argument,
~/geos-chem, is the path to GEOS-Chem's source code.
cmake and review the status of your configuration. Read the output and check that the configuration finished (i.e. succeeded).
If you're building GCHP, your output should look similar to the following.
~/rundirs/gchp_standard/build/> cmake . -- GEOS-Chem version: 12.4.0 -- Useful CMake variables: + CMAKE_PREFIX_PATH: * CMAKE_BUILD_TYPE: [Release] Debug -- Run directory setup: + RUNDIR: .. -- Bootstrapping ~/rundirs/gchp_standard/build/.. -- GCHP version: 12.4.0 -- Configuring done -- Generating done -- Build files have been written to: ~/rundirs/gchp_standard/build
If you're building GC-Classic, your output should look similar to the following.
~/rundirs/geosfp_4x5_standard/build/> cmake . -- GEOS-Chem version: 12.4.0 -- Useful CMake variables: + CMAKE_PREFIX_PATH: * CMAKE_BUILD_TYPE: [Release] Debug -- Run directory setup: + RUNDIR: .. -- Bootstrapping ~/rundirs/geosfp_4x5_standard/build/.. -- Threading: * OMP: [TRUE] FALSE -- General settings: * MECH: [Standard] Tropchem SOA_SVPOA * BPCH: [DIAG] [TIMESER] [TPBC] * PREC: REAL4 [REAL8] * TIMERS: TRUE [FALSE] -- Other components: * RRTMG: TRUE [FALSE] * GTMM: TRUE [FALSE] * HCOSA: TRUE [FALSE] -- Configuring done -- Generating done -- Build files have been written to: ~/rundirs/geosfp_4x5_standard/build/
~/rundirs/gchp_standard/build/> make -j
-j argument tells
make that it can execute as many jobs as it wants simultaneously. This can eat up a lot of memory, so if you're running out of memory, you can restrict the number of simultaneous jobs by adding a number. For example, to restrict the number of jobs to 4, you would do
make -j4. If you don't want
make to run simultaneous jobs, don't use the
5. Install the
geos executable to your run directory.
~/rundirs/gchp_standard/build/> make install
This should have put the
geos executable in your run directory.
See the CMake FAQ. I'm still working on it, and it's a bit rough right now.