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:
=================================================================
GCClassic X.Y.Z (superproject wrapper)
Current status: X.Y.Z
=================================================================
-- Found NetCDF: /path/to/netcdf-fortran/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*
* LUO_WETDEP: ON *OFF*
* FASTJX: ON *OFF*
=================================================================
HEMCO A.B.C
Current status: A.B.C
=================================================================
=================================================================
HETP D.E.F
=================================================================
=================================================================
Cloud-J G
Current status: G
=================================================================
=================================================================
GEOS-Chem X.Y.Z (science codebase)
Current status: X.Y.Z
=================================================================
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
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
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. 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
.
- 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 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).
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 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 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 releaseX.Y.Z-rc.n
: Denotes a release candidateX.Y.Z-alpha.n
: Denotes an internal “alpha” benchmark
where
n
is the number of the release candidate or alpha benchmark (starting from 0).
- 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.