Compiling with CMake

From Geos-chem
Revision as of 16:54, 8 December 2020 by Bmy (Talk | contribs) (→‎7. Install the geos executable in your run directory)

Jump to: navigation, search

Previous | Next | Getting Started with GEOS-Chem

  1. Minimum system requirements
  2. Installing required software
  3. Configuring your computational environment
  4. Downloading source code
  5. Downloading data directories
  6. Creating run directories
  7. Configuring runs
  8. Compiling GEOS-Chem
  9. Running
  10. Output files
  11. Visualizing and processing output
  12. Coding and debugging
  13. Further reading


Overview

CMake is a platform-independent build system. It creates Makefiles that can be used to compile GEOS-Chem source code into an executable file.

On this page, we will describe the basic steps that you need to compile GEOS-Chem with CMake. For a deeper dive into CMake, we recommend that you visit the CMake Frequently Asked Questions (FAQ) page that has been prepared by GCST member Liam Bindle.

As shown in the previous chapter, GEOS-Chem 12.6.0 and later versions can be compiled with either CMake or GNU Make. GNU Make will be retired in GEOS-Chem 13.0.0. Thus, in 13.0.0 and later versions, compiling GEOS-Chem will require CMake.

Before getting started

Before going through these instructions you should do the following:

Check if CMake is installed on your system

The only new software requirement for building GEOS-Chem with CMake is CMake version 3.5 or greater if using GEOS-Chem Classic, and CMake version 3.13 or greater if using GCHP. CMake is popular utility, and it might already be installed on your system. You can check which version of CMake (if any) is installed on your machine by typing: 

[~]$ cmake --version
cmake version 3.10.2

CMake suite maintained and supported by Kitware (kitware.com/cmake).
[~]$

If your computer system uses a software module system (such as Lmod or environment-modules), you can test if there is a pre-installed CMake module on your system with a command such as 

[~]$ module avail cmake

and then once you know the module name, you can load it into your Unix environment with a command such as: 

[~]$ module load cmake/3.15

Ask your IT staff what the proper module command syntax is for your system.

Even though GEOS-Chem "Classic" requires CMake version 3.5 or later, we recommend obtaining a recent CMake version (e.g. 3.15 or later), so as to ensure that all recent CMake updates and bug fixes are available.

If CMake is not installed on your system (or its version is less than the required) contact your system administator. The latest CMake code may be obtained here. You can also install CMake with the Spack package manager.

Set the proper environment variables

An objective of the transition to CMake has been simplifying the build environment. The only required environment variables are those that select your compilers. These are FC, CC, and CXX for Fortran, C, and C++ respectively. For GEOS-Chem Classic, only FC is required.

Optionally, if the nc-config or nf-config executables are not available on your machine, you can set NETCDF_ROOT, NETCDF_C_ROOT, or NETCDF_Fortran_ROOT environment variables to the directories where NetCDF's C and Fortran libraries are installed. Note that these variables have higher precidence than the install prefixes returned by nc-config and nf-config.

Below is an example ~/.bashrc that sets up an environment for building GEOS-Chem with CMake. 

# Picking the compiler I want to use
export FC=gfortran

# Misc environment variables
export NETCDF_C_ROOT=/usr/local/netcdf/4.6.1                    # only required if nc-config is not available
export NETCDF_Fortran_ROOT=/usr/local/netcdf-fortran/4.4.4      # only required if nf-config is not available

Don't forget to source ~/.bashrc after you modify it!

Download GEOS-Chem and create a run directory

Once you have CMake installed, then follow the instructions from previous chapters in this Guide to download the GEOS-Chem source code and to create a run directory for the simulation that you wish to perform.

Building GEOS-Chem

You should think of CMake as an interactive tool for configuring GEOS-Chem'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 my 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.

1. Navigate to your run directory

Let's assume our run directory is ~/gc_4x5_fullchem, so we'll cd there and get a directory listing: 

[~]$ cd ~/gc_4x5_fullchem
[gc_4x5_fullchem]$ ls
archiveRun.sh*                       getRunInfo*      OutputDir/
build/                               HEMCO_Config.rc  README
cleanRunDir.sh*                      HEMCO_Diagn.rc   rundir.version
CodeDir@                             HISTORY.rc       runScriptSamples/
download_data.py*                    input.geos       species_database.yml
GEOSChem.Restart.20190701_0000z.nc4  metrics.py*
[gc_4x5_fullchem]$

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

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

[gc_4x5_fullchem]$ cd build
[gc_4x5_fullchem/build]$

NOTE: You are free to create a build directory with a different name. Sometimes it is convenient to create multiple build directories for compiling GEOS-Chem with different compilers (e.g. build_gfortran93, build_ifort18), etc.).

3. Initialize your build directory

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

[gc_fullchem_4x5/build]$ cmake ../CodeDir

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

=================================================================
GCClassic 13.0.0 (top-level wrapper)
Current status: 13.0.0-alpha.8-27-g1158ac1
=================================================================
-- Useful CMake variables:
  + CMAKE_PREFIX_PATH:    /path/to/libraries/...
  + CMAKE_BUILD_TYPE:     Release
-- Run directory setup:
  + RUNDIR:       ..
-- Bootstrapping  ..
-- Threading:
  * OMP:          ON  OFF
-- General settings:
  * MECH:         fullchem  custom
  * BPCH_DIAG:    ON  OFF
  * USE_REAL8:    ON  OFF
-- Components:
  * APM:          ON  OFF
  * RRTMG:        ON  OFF
  * GTMM:         ON  OFF
  * HCOSA:        ON  OFF
  * LUO_WETDEP:   ON  OFF
=================================================================
HEMCO 3.0.0
Current status: gcc_13.0.0-alpha.4-12-g3b0a804
=================================================================
-- Settings:
  * OMP:          ON  OFF
  * USE_REAL8:    ON  OFF
=================================================================
GEOS-Chem 13.0.0 (science codebase)
Current status: gcc_13.0.0-alpha.8-57-gdd726b48
=================================================================
Creating /home/gc_4x5_fullchem/CodeDir/src/GEOS-Chem/Interfaces/GCClassic/gc_classic_version.H
-- Configuring done
-- Generating done
-- Build files have been written to: /home/gc_4x5_fullchem/build
~/gc_fullchem_4x5/build/$

Your CMake command's output contains important information about your build's configuration. We will explain this output below.

4. Configure your build (optional)

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: 

[gc_fullchem_4x5/build]$ cmake . -D<name>="<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. 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.

Item Default option To negate, use this option
Chemistry mechanism -DMECH=fullchem -DMECH=custom
Build GEOS-Chem with OpenMP parallelization -DOMP=y -DOMP=n
Build GEOS-Chem with binary punch (BPCH) diagnostics -DBPCH_DIAG=n -DBPCH_DIAG=y
Build GEOS-Chem with 64-byte (REAL*8) precision
NOTE: Not fully implemented! 		-DUSE_REAL8=y -DUSE_REAL8=n
Build GEOS-Chem with APM Microphysics -DAPM=n -DAPM=y
Build GEOS-Chem with the RRTMG radiative transfer model -DRRTMG=n -DRRTMG=y
Build GEOS-Chem with the Global Terrestrial Mercury Model
NOTE: Currently disabled 		-DHCOSA=n -DHCOSA=y
Build GEOS-Chem with the HEMCO standalone -DHCOSA=n -DHCOSA=y
Build GEOS-Chem with the Luo et al 2019 wet deposition scheme -DLUO_WETDEP=n -DLUO_WETDEP=y


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

[gc_fullchem_4x5/build]$ 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: 

[gc_fullchem_4x5/build]$ cmake . -DOMP=n

etc.

5. Understanding the output from CMake

As you can see from the example CMake output from Section 3, GEOS-Chem "Classic" 13.0.0 and later versions contain code from 3 independent repositories:

1. GCClassic wrapper (aka "the superproject"), https://github.com/geoschem/geos-chem-classic.git 

  =================================================================
  GCClassic 13.0.0 (top-level wrapper)
  Current status: 13.0.0-alpha.8-27-g1158ac1.dirty
  =================================================================

2. HEMCO (Harmonized Emissions Component) submodule, https://github.com/geoschem/hemco.git: 

  =================================================================
  HEMCO 3.0.0
  Current status: gcc_13.0.0-alpha.4-12-g3b0a804
  =================================================================

3. GEOS-Chem submodule, https://github.com/geos-chem/geos-chem.git: 

  =================================================================
  GEOS-Chem 13.0.0 (science codebase)
  Current status: gcc_13.0.0-alpha.8-57-gdd726b48
  =================================================================

During the build configuration stage, CMake will display the VERSION NUMBER (e.g. 13.0.0) as well as the CURRENT STATUS OF THE GIT REPOSITORY (e.g. 13.0.0-alpha.8-27-g1158ac1.dirty 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: 

 13.0.0-alpha.8-27-g1158ac1.dirty

where:

Item Description
13.0.0-alpha.8 Indicates the most recent tag in the GCClassic repository.
27 Indicates the number of commits that have been made on top of tag 13.0.0-alpha.8.
g Indicates that the version control system is Git.
1158ac1 Indicates the Git commit ID (short version) at which the HEAD of the GCClassic repository is located.
.dirty Indicates that there are code updates that have not yet been committed to this repository (if present).

Under each header are printed the various build options that have been selected, as well as other relevant information:

Item Description
CMAKE_PREFIX_PATH Indicates the path to important libraries such as netCDF and netCDF-Fortran.
CMAKE_BUILD_TYPE Indicates the type of build that was selected.
  1. Release: Debugging flags are turned off.
  2. Debug: Debugging flags are turned on (this will slow down the simulation).
* MECH: fullchem custom Indicates which chemistry mechanism is being used.
* X: ON OFF Indicates whether option X has been turned on or off.

6. Compile GEOS-Chem

Now that CMake has written build files to your build directory, you can compile GEOS-Chem with the make command: 

[gc_fullchem_4x5/build]$ $ make -j

You will see output similar to this: 

[  1%] Built target KPPFirstPass_fullchem
[  3%] Built target HeadersHco
[  4%] Building Fortran object src/GEOS-Chem/ISORROPIA/CMakeFiles/Isorropia.dir/isorropiaII_main_mod.F.o
[  6%] Built target JulDayHco
[  6%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/state_chm_mod.F90.o
[  6%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/state_met_mod.F90.o
[  7%] Building Fortran object src/HEMCO/src/Shared/NcdfUtil/CMakeFiles/NcdfUtilHco.dir/hco_ncdf_mod.F90.o
[  7%] Linking Fortran static library libNcdfUtilHco.a
[ 10%] Built target NcdfUtilHco
Scanning dependencies of target GeosUtilHco
[ 12%] Building Fortran object src/HEMCO/src/Shared/GeosUtil/CMakeFiles/GeosUtilHco.dir/hco_henry_mod.F90.o
[ 12%] Building Fortran object src/HEMCO/src/Shared/GeosUtil/CMakeFiles/GeosUtilHco.dir/hco_regrid_a2a_mod.F90.o
[ 13%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/state_diag_mod.F90.o
[ 13%] Linking Fortran static library libGeosUtilHco.a
[ 13%] Built target GeosUtilHco
...
[ 98%] Building Fortran object src/GEOS-Chem/GeosCore/CMakeFiles/GeosCore.dir/gc_environment_mod.F90.o
[ 98%] Building Fortran object src/GEOS-Chem/GeosCore/CMakeFiles/GeosCore.dir/chemistry_mod.F90.o
[ 98%] Building Fortran object src/GEOS-Chem/GeosCore/CMakeFiles/GeosCore.dir/cleanup.F90.o
[ 98%] Linking Fortran static library libGeosCore.a
[ 98%] Built target GeosCore
Scanning dependencies of target geos
[ 98%] Building Fortran object src/CMakeFiles/geos.dir/GEOS-Chem/Interfaces/GCClassic/main.F90.o
[100%] Linking Fortran executable ../bin/geos
[100%] Built target geos
[gc_fullchem_4x5/build]$

Note that the -j argument tells make that it can execute as many jobs as it wants simultaneously. If you want to restrict the number of simultaneous jobs (e.g. you are compiling on a machine with limited memory), you can add a number after -j. 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.

7. Install the geos executable in your run directory

Now that geos is built, install it to your run directory with make install. 

[gc_fullchem_4x5/build]$ make install

and you will see output similar to this: 

[  1%] Built target KPPFirstPass_fullchem
[ 10%] Built target Headers
[ 10%] Built target JulDay
[ 16%] Built target NcdfUtil
[ 22%] Built target GeosUtil
[ 25%] Built target Transport
[ 27%] Built target HeadersHco
[ 28%] Built target JulDayHco
[ 33%] Built target NcdfUtilHco
[ 34%] Built target GeosUtilHco
[ 50%] Built target HCO
[ 59%] Built target HCOX
[ 59%] Built target HCOI_Shared
[ 65%] Built target KPP_fullchem
[ 68%] Built target History
[ 69%] Built target ObsPack
[ 71%] Built target Isorropia
[ 98%] Built target GeosCore
[100%] Built target geos
Install the project...
-- Install configuration: "Release"
-- Installing: gc_4x5_fullchem/geos
[gc_fullchem_4x5/build]$

Let's now navigate back to the run directory and get a directory listing: 

[gc_fullchem_4x5/build]$ cd ..
[gc_fullchem_4x5]$ ls
archiveRun.sh*     geos*                                HISTORY.rc   rundir.version
build/             GEOSChem.Restart.20190701_0000z.nc4  input.geos   runScriptSamples/
cleanRunDir.sh*    getRunInfo*                          metrics.py*  species_database.yml
CodeDir@           HEMCO_Config.rc                      OutputDir/
download_data.py*  HEMCO_Diagn.rc                       README
[gc_fullchem_4x5]$

GEOS-Chem has now been configured, compiled, and installed in your run directory. You are now ready to run a GEOS-Chem simulation! Please skip ahead to Running GEOS-Chem.

Compiling GCHP with CMake

GCHP 13.0.0 will be compatible with CMake. This version is slated to be released by May 2020 (or possibly sooner). We will update the documentation in the near future.

--Bob Yantosca (talk) 20:59, 20 December 2019 (UTC)

Further reading

  1. CMake FAQ by Liam Bindle
  2. CMake tutorial (cmake.org)
  3. Learn X in Y minutes (where X is CMake)
  4. GEOS-Chem coding and debugging
  5. Guide to GEOS-Chem error messages


Previous | Next | Getting Started with GEOS-Chem

Retrieved from "https://wiki.seas.harvard.edu/geos-chem/index.php?title=Compiling_with_CMake&oldid=48744"