Building the NWChemEx Package

Prerequisites

To compile NWChemEx, some packages must be available on your system beforehand:

  1. A C++ compiler supporting the C++17 standard, currently we use gcc 9 (10.2 on Intel), clang has not been fully tested

  2. CMake (>= 3.17), usually the latest version is the best to use, be aware that some Linux distributions (Ubuntu for example) are often behind on CMake versions in the default build

  3. BLAS/LAPACK/ScaLAPACK or standards equivalent libraries, partially tested options include OpenBlas, NetLib, Blis, FLAME, MKL

  4. Boost, currently 1.59 as a minimum; note that bleeding edge Boost often requires bleeding edge compilers, so be careful here

  5. MPI, most of the code requires at least MPI-3 compliance, MPICH 3.4 has been tested

  6. Eigen, minimum of 3.4.0; the build will automatically pull this if you don’t have it available

  7. libint2 - see below for more information

  8. Depending on what type of GPU you have available to you, you will need CUDA 11 or higher, SYCL 2.0 (use the latest version of the OneAPI SDK), or HIP 4.5 (use the latest ROCm version)

If necessary, more installation details for a package will be provided in the subsections below.

NWChemEx also depends on a number of repositories listed below. Please visit the repositories and ensure that any additional packages that must be available before building are installed.

  1. integrals

  2. SCF

  3. MP2

BLAS/LAPACK/ScaLAPACK

Intel MKL (Intel oneAPI MKL): Ensure that all required environment variables for the Intel MKL are set by executing /path/to/intel/mkl/bin/ mklvars.sh <arch>, where <arch> must be either ia32 or intel64. The following command can be added to your .bashrc to set the required environment variables automatically for all new terminal sessions:

. /path/to/intel/mkl/bin/mklvars.sh <arch>

Other BLAS/LAPACK/ScaLAPACK: If not using the Intel MKL, ensure that environment variables for the packages are set up correctly according to the package-specific instructions and that paths to non-standard installation directories are included in the cmake variable CMAKE_PREFIX_PATH (which should be specified in your toolchain.cmake file (see below)).

libint2

Note

Important: Boost must be installed and in your path prior to building libint2. This is not required by libint2, as libint2 will use its own internal build of Boost. However, when building NWChemEx, errors related to using this internal build of Boost have been observed (by Zach Crandall as of April 29, 2021).

The libint2 build will take a long time (probably >2 hrs), and should be started well in advance. At the time of writing, libint v2.6.0 can be obtained from the libint v2.6.0 release page and built using instructions at libint Wiki if a custom library is needed.

The following build script can be used to build and install the libint2 pre-generated library “lmax=6 library (standard ints only)”, which can be downloaded from the libint v2.6.0 release page or directly from here. Download and extract the pre-generated libint v2.6.0 library. Inside the newly extracted libint-2.6.0 directory, create a file named build.sh and paste the below contents, modifying everything in angled brackets (<>) to be correct for your system.

#!/usr/bin/env bash

cmake -H . \
      -B build \
      -DCMAKE_INSTALL_PREFIX=<desired_install_location> \
      -DCMAKE_CXX_COMPILER=<c++_compiler> \
      -DCMAKE_CXX_FLAGS="-O3" \
      -DCMAKE_CXX_STANDARD=11 \
      -DCMAKE_POSITION_INDEPENDENT_CODE=TRUE \
      2>&1 | tee OUTPUT.GEN

cmake --build build --target install 2>&1 | tee OUTPUT.BUILD

GitHub Personal Access Token

A GitHub Personal Access Token (PAT) is necessary since, at the moment, NWChemEx and some dependencies are hosted in private repositories. To create a PAT, follow the instructions at GitHub’s Creating a personal access token page. Note: please create a classical personal access token, not a fine-grained personal access token. This PAT will be used when prompted for a password while cloning repositories.

Building NWChemEx

The build instructions are given in the following sections based on a few assumptions:

  1. You are using a sane Unix-like operating system.

  2. All components will be installed in the same location.

The following two files will be created to build NWChemEx, with instructions for each in the sections below:

  1. CMake Toolchain File: toolchain.cmake

  2. NWChemEx Build Script: build_nwx.sh

CMake Toolchain File

NWChemEx requires knowledge of many packages and tools which may have system- specific installation locations. Inside the top level directory where NWChemEx will be built, create a toolchain file named toolchain.cmake. This file should contain the following information, replacing everything in angled brackets (<>) for your system.

# Compilers
set(CMAKE_C_COMPILER   <C compiler>)
set(CMAKE_CXX_COMPILER <C++ compiler>)
set(MPI_C_COMPILER     <MPI C compiler>)
set(MPI_CXX_COMPILER   <MPI CXX compiler>)

# Token for private repos
set(CMAIZE_GITHUB_TOKEN <your_super_secret_github_PAT>)

# Options
set(CMAKE_POSITION_INDEPENDENT_CODE TRUE)
set(BUILD_SHARED_LIBS TRUE)
set(BUILD_TESTING TRUE)

# List directories for dependencies you have installed in non-standard
# locations. For example:
# set(CMAKE_PREFIX_PATH
#     /path/to/libint2_install
#     /path/to/personal/BLAS/install
#     ...
# )
# Uncomment the lines above and set CMAKE_PREFIX_PATH specifically in
# your case.

list(APPEND CMAKE_PREFIX_PATH <additional_prefix_directories>)
set(CMAKE_CXX_STANDARD 17)

# BLAS/LAPACK
set(ENABLE_SCALAPACK ON)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DOMPI_SKIP_MPICXX")

NWChemEx Build Script

Create a new file named build_nwx.sh next to toolchain.cmake and paste the script below into it. This script will download, build, and install NWChemEx and any remaining dependencies. Logs for the build will be generated beside this build script.

# Clone the repo
git clone https://github.com/NWChemEx/NWChemEx.git 2>&1 | tee "OUTPUT.GITCLONE"
# <Type login information if prompted.>

# Navigate into the newly created NWChemEx subdirectory
cd NWChemEx

# Generate project buildsystem
cmake -H. \
      -Bbuild \
      -DCMAKE_TOOLCHAIN_FILE=`pwd`/../toolchain.cmake \
      -DCMAKE_BUILD_TYPE=Debug \
      -DCMAKE_INSTALL_PREFIX=<where/you/want/to/install> \
      2>&1 | tee "../OUTPUT.GEN"

# Build the project. You can change the "1" to another integer,
# N, to instead build with N threads
cmake --build build -- -j 1 \
      2>&1 | tee "../OUTPUT.BUILD"

# Run tests
cd build && ctest 2>&1 | tee "../../OUTPUT.TEST"

# Back out of the build directory
cd ..

# Install the project
cmake --build build --target install 2>&1 | tee "../OUTPUT.INSTALL"

# Return to the top level directory
cd ..

CMAKE_BUILD_TYPE is currently set to "Debug", because a Release build may take an extremely long time to finish (a known issue to be resolved).

The toolchain.cmake file and the building script for NWChemEx can also be used (with minor modifications such as repo paths) to compile other packages in the NWChemEx project.

Running the NWChemEx Unit Tests

Assuming NWChemEx is built with BUILD_TESTING enabled, then once the NWChemEx package is successfully built the unit tests can be run by running ctest in the build directory. For debugging purposes, the log files resulting from running the unit tests can be found in the Testing/Temporary subdirectory of the build directory.

Note

For finer-grained control over the build, we direct the reader to the more thorough CMaize build instructions located here and note that NWChemEx depends on several other projects: