Building GEOS-Chem with CMake

From Geos-chem
Revision as of 13:27, 20 August 2019 by Melissa Payer (Talk | contribs) (Created page with "On this page we provide instructions for building GEOS-Chem with CMake. This feature has been added to GEOS-Chem 12.6.0 as an option. By default, Co...")

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

On this page we provide instructions for building GEOS-Chem with CMake. This feature has been added to GEOS-Chem 12.6.0 as an option. By default, GNU Make is still used to compile GEOS-Chem but will be removed in eventually. This documentation was written by Liam Bindle (Dalhousie).

Setting up

Pick your compilers

The CC, CXX, and 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.

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.

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.

Specify where GEOS-Chem's dependencies are installed

The easiest way to tell CMake where GEOS-Chem's dependencies are found is with the NetCDF_C_ROOT, NetCDF_Fortran_ROOT, ESMF_ROOT and 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.

NOTE: NetCDF_C_ROOT and 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

NOTE 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 NetCDF_C_ROOT, NetCDF_Fortran_ROOT, ESMF_ROOT and gFTL_ROOT

Variable Required for Search files Comments
  • GC‑Classic
  • GCHP
  • Not required if nc-config --prefix is available
  • GC‑Classic
  • GCHP
  • Not required if nf-config --prefix is available
  • GCHP
  • ESMF's .inc files don't get installed when you install ESMF. To remedy this, you have to set ESMF_ROOT to ESMF's install prefix AND the path to ESMF's source code. Separate the two paths with a semicolon (;).
  • If you're using ESMF binaries from a different GCHP build, set ESMF_ROOT to the ESMF/ subdirectory of the other GCHP's source code (you should see a subdirectory of ESMF/ called DEFAULTINSTALLDIR). Only the one path is needed.
  • GCHP

Reload your environment

~/> source ~/.bashrc

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.

Create a build directory in your run directory

In your GEOS-Chem run directory create a directory called build and navigate to it.

~> cd ~/GC/rundirs/geosfp_4x5_standard
~/GC/rundirs/geosfp_4x5_standard/> mkdir build
~/GC/rundirs/geosfp_4x5_standard/> cd build


Initialize your build directory

In the build subdirectory, type the cmake command and pass it the path to your GEOS-Chem source code.

~/GC/rundirs/geosfp_4x5_standard/build/> cmake ~/GC/Code.12.6.0

Rerun with cmake . and review the status of your configuration. Read the output and check that the configuration finished (i.e. succeeded).

If you're building GC-Classic, your output should look similar to the following.

~/GC/rundirs/geosfp_4x5_standard/build/> cmake .
-- GEOS-Chem version: 12.6.0
-- Useful CMake variables:
  * 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:
  * APM:          TRUE  [FALSE]
  * RRTMG:        TRUE  [FALSE]
  * GTMM:         TRUE  [FALSE]
  * HCOSA:        TRUE  [FALSE]
-- Configuring done
-- Generating done
-- Build files have been written to: ~/GC/rundirs/geosfp_4x5_standard/build/


Compile the source code using the command

~/GC/rundirs/geosfp_4x5_standard/build/> make -j

NOTE: The -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 -j argument.

Install the geos executable to your run directory

The final step is to copy the geos executable in your run directory using:

~/GC/rundirs/geosfp_4x5_standard/build/> make install



What is CMake?

When will CMake support be available?

CMake is implemented as an option in GEOS-Chem 12.6.0. It will eventually become the default, replacing GNU Make.

A GCHP version compatible with CMake should be available by the end of 2019. At that time, support for GNU Make will be retired. See the Compiling GCHP wiki page for more information.

What are the benefits of CMake?

  1. You environment is verified before you compile.
  2. Incremental compiling and a simpler build procedure.
  3. Fewer wasted HPC jobs due to failed builds.

What is incremental compiling?

What is an "out of source" build?

Building GEOS-Chem

Can I build GEOS-Chem Classic and GCHP in the same environment?


= How do I build specific targets?

make <target name>

How do continue a build that was terminated before it finished?


How do I recompile after I make modifications to the source code?


How do I make clean?

make clean

This cleans everything. Normally you don't need to do this. Rerunning make with no arguments is usually what you want to do instead. See What is incremental compiling?

How do I disable multithreading (i.e. OpenMP)?

cmake -DOMP=FALSE .

How do I disable colorized output?


This disables colored output from CMake and the generated Makefiles.

How do I increase the build's verbosity?


This causes the generated Makefiles to print the compiler commands that get executed.

How do I build for debugging?

cmake -DCMAKE_BUILD_TYPE=Debug .

This causes the

How do I clean my build's configuration (i.e. CMake's files)?

rm -rf build
mkdir build
cd build

Advanced topics

Can I use Ninja rather than GNU Make?

Yes. You'll need CMake version 3.7 or greater and Kitware's Ninja distribution (for Fortran futures). To use the Ninja generator rather than the Makefile generator, initialize your build directory with cmake -GNinja <path to source code>.

Are the environment variables like FC and ESMF_ROOT necessary?

No, these are for convenience. You can configure the build with the standard CMAKE_C_COMPILER, CMAKE_CXX_COMPILER, CMAKE_Fortran_COMPILER, and CMAKE_PREFIX_PATH variables, rather than environment variables, if you'd prefer. This means GEOS-Chem doesn't impose environment variable requirements on superprojects.

How do I build GEOS-Chem as a part of an other project?