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.

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 9.3.0
-- Check for working Fortran compiler: /usr/bin/gfortran
-- Check for working Fortran compiler: /usr/bin/gfortran  -- works
-- Detecting Fortran compiler ABI info
-- Detecting Fortran compiler ABI info - done
-- Checking whether /usr/bin/gfortran supports Fortran 90
-- Checking whether /usr/bin/gfortran supports Fortran 90 -- yes
=================================================================
GCClassic 14.0.0 (superproject wrapper)
Current status: 14.0.0-alpha.3-1-g289a460
=================================================================
-- Found NetCDF: /usr/lib/x86_64-linux-gnu/libnetcdff.so
-- Useful CMake variables:
  + CMAKE_PREFIX_PATH:    /usr  /usr
  + CMAKE_BUILD_TYPE:     Release
-- Run directory setup:
  + RUNDIR:       /home/ubuntu/test_gcc
-- Threading:
  * OMP:          ON  OFF
-- Found OpenMP_Fortran: -fopenmp (found version "4.5")
-- Found OpenMP: TRUE (found version "4.5")
-- General settings:
  * MECH:         **fullchem**  Hg  custom
  * BPCH_DIAG:    ON  **OFF**
  * USE_REAL8:    ON  **OFF**
-- Components:
  * TOMAS:        ON  **OFF**
  * TOMAS_BINS:   **NA**  15  40
  * APM:          ON  **OFF**
  * RRTMG:        ON  **OFF**
  * GTMM:         ON  **OFF**
  * HCOSA:        ON  **OFF**
  * LUO_WETDEP:   ON  **OFF**
=================================================================
HEMCO 3.5.0
Current status: 3.4.0-10-g18b61cd
=================================================================
-- Found OpenMP_Fortran: -fopenmp
-- Found OpenMP: TRUE
=================================================================
GEOS-Chem 14.0.0 (science codebase)
Current status: 14.0.0-alpha.3-4-gf833fba4f
=================================================================
Creating /home/ubuntu/test_gcc/CodeDir/src/GEOS-Chem/Interfaces/GCClassic/gc_classic_version.H
-- Configuring done
-- Generating done
-- Build files have been written to: /home/ubuntu/test_gcc/gc_merra2_fullchem

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

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. 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.

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 to the run directory as an absolute path.

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.

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.

BPCH_DIAG

Toggles the legacy binary punch diagnostics on.

Attention

This option is deprecated and will be removed soon. Most binary-punch format diagnostics have been replaced by netCDF-based History diagnostics.

Accepted values are:

y

Activate legacy binary-punch diagnostics.

n

Deactivate legacy binary-punch diagnostics. (Default option)

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)

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)

If you plan to use the make -j install option (recommended) to copy your executable to your run directory, you must reconfigure CMake with the RUNDIR=/path/to/run/dir option. Multiple run directories can be specified by a semicolon separated list. A warning is issues if one of these directories does not look like a run directory. These paths can be relative paths or absolute paths. Relative paths are interpreted as relative to your build directory. For example:

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

For example if you wanted to build GEOS-Chem with all debugging flags on, you would type:

$ cmake . -DCMAKE_BUILD_TYPE=Debug

or if you wanted to turn off OpenMP parallelization (so that GEOS-Chem executes only on one computational core), you would type:

$ cmake . -DOMP=n

etc.

Understand CMake output

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

  1. GCClassic wrapper (aka “the superproject”):

=================================================================
GCClassic 14.0.0 (superproject wrapper)
Current status: 14.0.0-alpha.3-1-g289a460
=================================================================
  1. HEMCO (Harmonized Emissions Component) submodule:

=================================================================
HEMCO 3.5.0
Current status: 3.4.0-10-g18b61cd
=================================================================
  1. GEOS-Chem submodule:

=================================================================
GEOS-Chem 14.0.0 (science codebase)
Current status: 14.0.0-alpha.3-4-gf833fba4f
=================================================================

During the build configuration stage, CMake will display the version number (e.g. 14.0.0) as well as the current status of the Git repository (e.g. 14.0.0-alpha.3-1-g289a460) for GCClassic, GEOS-Chem, and HEMCO.

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:

14.0.0-alpha.3-1-g289a460

where

14.0.0-alpha.3

Indicates the most recent tag in the GCClassic superproject repository `.

1

Indicates the number of commits that were made atop 14.0.0-alpha.3.

g

Indicates that the version control system is Git.

289a460

Indicates the Git commit (short form) at the HEAD of the GCClassic repository.

.dirty

If present, indicates that there are uncommitted updates atop the 289a460 commit in the GCClassic repository.

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