Building GCHP with CMake (draft)

From AtmosWiki
Jump to: navigation, search

These instructions can be used for GC-Classic and GCHP.


Setting things up

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


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


3. 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 that 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
NetCDF_C_ROOT
  • GC‑Classic
  • GCHP
netcdf.h
libnetcdf.so
  • Not required if nc-config --prefix is available
NetCDF_Fortran_ROOT
  • GC‑Classic
  • GCHP
netcdf.inc
netcdf.mod
libnetcdff.so
  • Not required if nf-config --prefix is available
ESMF_ROOT
  • GCHP
ESMF_ErrReturnCodes.inc
ESMC.h
esmf.mod
libesmf.a
  • 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.
gFTL_ROOT
  • GCHP
types/key_deferredLengthString.inc


4. Reload your environment.

~/> source ~/.bashrc

Getting GEOS-Chem's source code

1. Clone the GEOS-Chem source code and checkout feature/CMake.

~/> git clone https://github.com/LiamBindle/geos-chem.git
~/> cd geos-chem
~/geos-chem/> git checkout feature/CMake

2. Clone the GCHP source code as a subdirectory of the GEOS-Chem source code and checkout feature/CMake. (Only required for GCHP)

~/geos-chem/> git clone https://github.com/LiamBindle/gchp.git GCHP
~/geos-chem/> cd GCHP
~/geos-chem/GCHP/> git checkout feature/CMake

Note: Make sure the name of the GCHP repo is GCHP/



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. Doing the tutorial isn't necessary, but if anything here looks like magic, I'd recommend it. I've been told it takes about 30-45 minutes to complete.


Note: The feature/CMake branch is version 12.4.0. These instructions assume you've already created a 12.4.0 run directory for GC-Classic or GCHP.


1. Navigate to your run directory.

~/geos-chem/GCHP/> cd ~/rundirs/gchp_standard

Note: Navigate to a GC-Classic run directory, like geosfp_4x5_standard, to build GC-Classic instead.


2. Create a build directory and cd into it.

~/rundirs/gchp_standard/> mkdir build
~/rundirs/gchp_standard/> cd build

3. Initialize your build directory.

~/rundirs/gchp_standard/build/> cmake ~/geos-chem

Note: The argument, ~/geos-chem, is the path to GEOS-Chem's source code.

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

If you're building GCHP, your output should look similar to the following.

~/rundirs/gchp_standard/build/> cmake .
-- GEOS-Chem version: 12.4.0
-- Useful CMake variables:
  + CMAKE_PREFIX_PATH:
  * CMAKE_BUILD_TYPE:     [Release]  Debug
-- Run directory setup:
  + RUNDIR:       ..
-- Bootstrapping ~/rundirs/gchp_standard/build/..
-- GCHP version: 12.4.0
-- Configuring done 
-- Generating done 
-- Build files have been written to: ~/rundirs/gchp_standard/build

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

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

4. Compile

~/rundirs/gchp_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.


5. Install the geos executable to your run directory.

~/rundirs/gchp_standard/build/> make install

This should have put the geos executable in your run directory.



FAQ

See the CMake FAQ. I'm still working on it, and it's a bit rough right now.