Configure with CMake

You should think of CMake as an interactive tool for configuring GEOS-Chem Classic’s build. For example, compile-time options like disabling multithreading and turning on components (e.g. APM, RRTMG) are all configured with CMake commands.

Besides configuring GEOS-Chem’s build, CMake also performs checks on your build environment to detect problems that would cause the build to fail. If it identifies a problem, like a missing dependency or mismatched run directory and source code version numbers, CMake will print an error message that describes the problem.

If you are new to CMake and would like a rundown of how to use the cmake command, check out Liam Bindle’s Cmake Tutorial. This tutorial is not necessary, but it will make you more familiar with using CMake and help you better understand what is going on.

Below are the steps for building GEOS-Chem with CMake.

Navigate to your run directory

In this example, we will compile the GEOS-Chem code for the full-chemistry simulation. Navigate to your run directory and get a directory listing as shown below:

$ cd /path/to/gc_4x5_merra2_fullchem
$ ls
archiveRun.sh*     download_data.py*    HEMCO_Config.rc.gmao_metfields  README.md
build/             download_data.yml    HEMCO_Diagn.rc                  Restarts/
cleanRunDir.sh*    geoschem_config.yml  HISTORY.rc                      runScriptSamples@
CodeDir@           getRunInfo*          metrics.py*                     species_database.yml
CreateRunDirLogs/  HEMCO_Config.rc      OutputDir/

Note that each GEOS-Chem run directory that you generate has a folder named build/. This is where we will run CMake.

Navigate to the build directory

The build directory is where CMake and your compilers are going to put the files they generate. For this example, we will use the build/ folder that was automatically generated in the GEOS-Chem Classic run directory. For GCHP you will need to create one.

$ cd build

Tip

If you find yourself switching between different compilers, you can create multiple build directories with different names (e.g. build_gfortran10, build_ifort19, etc).

Initialize the build directory

Next, we need to initialize the build directory. Type:

$ cmake ../CodeDir -DRUNDIR=..

where ../CodeDir is the symbolic link from our run directory to the GEOS-Chem source code directory. CMake will generate output similar to this:

-- The Fortran compiler identification is GNU 12.2.0
-- Detecting Fortran compiler ABI info
-- Detecting Fortran compiler ABI info - done
-- Check for working Fortran compiler: /path/to/gcc/12.2.0/bin/gfortran
=================================================================
GCClassic X.Y.Z (superproject wrapper)
Current status: X.Y.Z
=================================================================
-- Found NetCDF: /n/sw/helmod-rocky8/apps/MPI/gcc/12.2.0-fasrc01/openmpi/4.1.4-fasrc01/netcdf-fortran/4.6.0-fasrc02/lib/libnetcdff.so
-- Useful CMake variables:
  + CMAKE_PREFIX_PATH:    /path/to/netcdf-c
  ...             /path/to/netcdf-fortran/
  + CMAKE_BUILD_TYPE:     Release
-- Run directory setup:
  + RUNDIR:       /path/to/run/directory
-- Threading:
  * OMP:          *ON*  OFF
-- Found OpenMP_Fortran: -fopenmp (found version "4.5")
-- Found OpenMP: TRUE (found version "4.5")
-- General settings:
  * MECH:         *fullchem*  carbon  Hg  custom
  * USE_REAL8:    *ON*  OFF
  * SANITIZE:     ON  *OFF*
-- Components:
  * TOMAS:        ON  *OFF*
  * TOMAS_BINS:   *NA*  15  40
  * APM:          ON  *OFF*
  * RRTMG:        ON  *OFF*
  * GTMM:         ON  *OFF*
  * HCOSA:        ON  *OFF*
  * KPPSA:        ON  *OFF*
  * LUO_WETDEP:   ON  *OFF*
  * FASTJX:       ON  *OFF*
=================================================================
HEMCO A.B.C
Current status: A.B.C
=================================================================
=================================================================
HETP D.E.F
=================================================================
=================================================================
Cloud-J G.H.I
Current status: G.H.I
=================================================================
=================================================================
GEOS-Chem X.Y.Z (science codebase)
Current status: X.Y.Z
=================================================================
-- KPP integrator (read from fullchem.kpp):
  + KPP_INTEGRATOR_NAME:          rosenbrock_autoreduce
  * KPP_INTEGRATOR_AUTOREDUCE:    *ON*  OFF
Creating /path/to/run/directory/CodeDir/src/GEOS-Chem/Interfaces/GCClassic/gc_classic_version.H
-- Configuring done
-- Generating done
-- Build files have been written to: /path/to/run/directory/build

Your CMake command’s output contains important information about your build’s configuration.

Note

The text X.Y.Z, A.B.C, D.E.F., and G.H.I refer to the version numbers (in semantic versioning style) of the GCClassic, HEMCO, ISORROPIA/HETP, and Cloud-J repositories, respectively.

The GEOS-Chem “Science Codebase” and GCClassic repositories share the same version number X.Y.Z.

Configure your build with extra options

Your build directory is now configured to compile GEOS-Chem using all default options. If you do not wish to change anything further, you may skip ahead to the next section.

However, if you wish to modify your build’s configuration, simply invoke CMake once more with optional parameters. Use this format:

$ cmake . -DOPTION=value

Note that the . argument is necessary. It tells CMake that your current working directory (i.e. .) is your build directory.

For example, to compile GEOS-Chem Classic with all debugging flags turned on, use:

$ cmake . -DCMAKE_BUILD_TYPE=Debug

Or to turn off OpenMP parallelization (so that GEOS-Chem Classic will execute on only one computational core), use:

$ cmake . -DOMP=n

The output of CMake tells you about your build’s configuration. Options are prefixed by a + or * in the output, and their values are displayed or highlighted.

Tip

If you are colorblind or if you are using a terminal that does not support colors, refer to the CMake FAQ for instructions on disabling colorized output. For a detailed explanation of CMake output, see the next section.

The table below contains the list of GEOS-Chem build options that you can pass to CMake. GEOS-Chem will be compiled with the default build options, unless you explicitly specify otherwise.

RUNDIR

Defines the path to the run directory. This is the path where the make -j install will copy the GEOS-Chem Classic executable upon successful compilation.

In this example, our build directory is a subfolder of the run directory, so we can use -DRUNDIR=... If your build directory is somewhere else, then specify the path such as:

$ cmake . -DRUNDIR=/path/to/run/dir

Multiple run directories can be specified by a semicolon separated list. A warning will be issued if one of these directories does not look like a run directory. Run directory paths can be relative paths or absolute paths. Relative paths are interpreted as relative to your build directory.

CMAKE_BUILD_TYPE

Specifies the type of build. Accepted values are:

Release: Tells CMake to configure GEOS-Chem in Release mode. This means that all optimizations will be applied and all debugging options will be disabled. (Default option).

Debug: Turns on several runtime error checks. This will make it easier to find errors but will adversely impact performance. Only use this option if you are actively debugging.

MECH

Specifies the chemical mechanism that you wish to use:

fullchem: Activates the fullchem mechanism. The source code files that define this mechanism are stored in KPP/fullchem. (Default option)

Hg: Activates the Hg mechanism. The source code files that define this mechanism are stored in KPP/Hg.

carbon: Activates the carbon mechanism (CH4-CO-CO2-OCS). The source code files that define this mechanism are stored in KPP/carbon.

custom: Activates a custom mechanism defined by the user. The source code files that define this mechanism are stored in KPP/custom.

OMP

Determines if GEOS-Chem Classic will activate OpenMP parallelization. Accepted values are:

y

Activates OpenMP parallelization. (Default option)

GEOS-Chem Classic will execute on as many computational cores as is specified with OMP_NUM_THREADS.

n: Deactivates OpenMP parallelization. GEOS-Chem Classic will execute on a single computational core. Useful for debugging.

TOMAS

Configure GEOS-Chem with the TOMAS aerosol microphysics package. Accepted values are:

y: Activate TOMAS microphysics.

n: Deactivate TOMAS microphysics (Default option)

TOMAS_BINS

Specifies the number of size-resolved bins for TOMAS. Accepted values are:

15: Use 15 size-resolved bins with TOMAS simulations.

40: Use 40 size-resolved bins with TOMAS simulations.

APM

Configures GEOS-Chem to use the APM microphysics package. Accepted values are:

y: Activate APM microphysics.

n: Deactivate APM microphysics. (Default option)

RRTMG

Configures GEOS-Chem to use the RRTMG radiative transfer model. Accepted values are:

y: Activates the RRTMG radiative transfer model.

n: Deactivates the RRTMG radiative transfer model. (Default option)

HCOSA

Compiles the HEMCO Standalone Model executable.

KPPSA

Compiles the KPP-Standalone Box Model executable.

LUO_WETDEP

Configures GEOS-Chem to use the Luo et al., 2020 wet deposition scheme.

Note

The Luo et al 2020 wet deposition scheme will eventually become the default wet deposition schem in GEOS-Chem. We have made it an option for the time being while further evaluation is being done.

Accepted values are:

y: Activates the Luo et al., 2020 wet deposition scheme.

n: Deactivates the Luo et al., 2020 wet deposition scheme. (Default option)

FASTJX

Configures GEOS-Chem to use the legacy FAST-JX v7.0 photolysis mechanism instead of its successor Cloud-J.

Note

We recommend using FAST-JX for the mercury simulation instead of Cloud-J. Further work is needed to make the mercury simulation compatible with Cloud-J. Once that work is completed the legacy FAST-JX option will be deleted from the model.

Accepted values are:

y: Uses the legacy FAST-JX v7.0 photolysis scheme rather than Cloud-J.

n: Uses the Cloud-J photolyis scheme rather than legacy FAST-JX. (Default option)

SANITIZE

Activates the AddressSanitizer/LeakSanitizer functionality in GNU Fortran to identify memory leaks. Accepted values are:

y: Activates AddressSanitizer/LeakSanitizer

n: Deactivates AddressSanitizer/LeakSanitizer (Default option).

Understand CMake output

As you can see from the example CMake output listed above, GEOS-Chem Classic contains code from the various repositories:

GCClassic wrapper (aka “the superproject”):
```
=================================================================
GCClassic X.Y.Z (superproject wrapper)
Current status: X.Y.Z
=================================================================
```
where X.Y.Z specifies the GEOS-Chem Classic “major”, “minor”, and “patch” version numbers.
Note

If you are cloning GEOS-Chem Classic between official releases, you may the see Current status reported like this:
```
X.Y.Z-alpha.n-C-gabcd1234.dirty  or

X.Y.Z.rc.n-C.gabcd1234.dirty
```
We will explain these formats below.
HEMCO (Harmonized Emissions Component) submodule:
```
=================================================================
HEMCO A.B.C
Current status: A.B.C
=================================================================
```
where A.B.C specifies the HEMCO “major”, “minor”, and “patch” version numbers. The HEMCO version number differs from GEOS-Chem because it is kept in a separate repository, and is considered a separate package.
GEOS-Chem submodule:
```
=================================================================
GEOS-Chem X.Y.Z (science codebase)
Current status: X.Y.Z
=================================================================
```
The GEOS-Chem science codebase and GEOS-Chem Classic wrapper will always share the same version number.

During the build configuration stage, CMake will display the version number (e.g. X.Y.Z) as well as the current status of the Git repository (e.g. TAG-C-gabcd1234.dirty) for GCClassic, GEOS-Chem, and HEMCO.
Similar messages will be displayed for the Cloud-J and ISORROPIA/HETP repositories.

Let’s take the Git repository status of GCClassic as our example. The status string uses the same format as the git describe --tags command, namely:

TAG-C-gabcd1234.dirty

where

TAG

Indicates the most recent tag in the GCClassic superproject repository.

Tags may use the following notations:

X.Y.Z: Denotes an official release
X.Y.Z-rc.n: Denotes a release candidate
X.Y.Z-alpha.n: Denotes an internal “alpha” benchmark

where n is the number of the release candidate or alpha benchmark (starting from 0).

C: Indicates the number of commits that were made on top of the commit that is referred to by TAG.

g: Indicates that the version control system is Git.

abcd1234: Indicates the Git commit hash. This is an alphanumeric string that denotes the commit at the HEAD of the GCClassic repository.

.dirty: If present, indicates that there are uncommitted updates atop the abcd1234 commit in the GCClassic repository.

Under each header are printed the various options that have been selected.