Table of Contents

• Table of Contents
• Docker Image
• Compilation from Source
  • Quickstart Compilation
  • Prerequisites
    • Required external dependencies
    • ChronusQ installed dependencies
    • Libint2 for ChronusQ
  • MPI enabled build
    • Prerequisites
    • CMake invocation
  • CMake options
  • Tested Toolchains
  • Citations

Docker Image

With Docker Desktop installed on your local machine, you can pull the Chronus Quantum images using:

docker pull uwligroup/chronusq

If you need a specific version, use -t and specify a valid version tag:

docker pull -t uwligroup/chronusq:tag

To run the docker image, see running ChronusQ.

Note that the ChronusQ Docker images are not compiled with MPI, so currently CCSD is disabled in those images.

Compilation from Source

Quickstart Compilation

If you have all the prerequisites, all you have to do is:

git clone https://urania.chem.washington.edu/chronusq/chronusq_public.git
mkdir chronusq_public/build && cd chronusq_public/build
cmake ..
cmake --build .

To install, you then run

cmake --build . --target install

To run ChronusQ after installation from source, see running ChronusQ.

Prerequisites

Required external dependencies

The following dependencies must be installed prior to compiling ChronusQ. All dependencies must be compiled with a C++14 enabled compiler.

• C++14 compiler (see notes below on tested compilers)
• C compiler (for LibXC)
• Fortran compiler (for LibXC)
• CMake build system (Version 3.11+).
• HDF5
• Eigen3

MPI only:

We refer the user to the linked documentation for the installation details of the packages.

ChronusQ installed dependencies

During the build process, if ChronusQ cannot find a previously built version of each of these dependencies, the missing dependencies will be downloaded and built along ChronusQ. This can drastically slow the compilation of ChronusQ, so it is recommended to install these separately if you are planning to compile ChronusQ multiple times.

• Libint2 [1] GTO integral library.
• LibXC [2] for exchange-correlation kernel evaluation
• GTest Unit testing framework.
• OpenBLAS for threaded linear algebra (only compiled if MKL is not found)

Libint2 for ChronusQ

A Libint2 library has been generated specifically for ChronusQ, and can be found here. This library includes up to second order integral gradients for basis functions up to angular momentum 5 (H functions), so there are a large number of routines to compile. Because the compilation may take a while, it is recommended to install this separately if you plan to compile ChronusQ regularly. To do this, follow the procedure below:

git clone https://urania.chem.washington.edu/chronusq/libint-cq.git
cd libint-cq
mkdir build && cd build
cmake ..
cmake --build . --target install

If you would like to speed up the installation process, you may run make (or your given build system) in parallel. If you would like to install to a non-default location, specify -DCMAKE_INSTALL_PREFIX=<location/for/installation> in your cmake command.

MPI enabled build

In order to run at scale, ChronusQ uses hybrid OpenMP/MPI parallelism. The default build does not enable MPI, and this must be enabled at build time. This section assumes that the user has a working knowledge of building MPI programs.

Prerequisites

In order to build ChronusQ with MPI enabled, you need the following:

• An MPI enabled compiler (e.g. Intel MPI, MPICH, OpenMPI, etc.)
• ScaLAPACK

Additionally, the following are installed by ChronusQ:

• MXX C++11 MPI interface
• CXXBLACS C++11 BLACS interface

CMake invocation

The minimal CMake invocation to build ChronusQ with MPI is a simple extension of the build process above:

cmake -DCQ_ENABLE_MPI=On ..

Then you may build with your build system and install.

CMake options

In most cases, the defaults set by ChronusQ are sufficient. For those that wish to customize ChronusQ, however, the following are available:

Option	Type	Description
CQ_ENABLE_MPI	Boolean	Whether to build ChronusQ with MPI
CQ_LINALG_USESYSTEM	Boolean	Whether to use the system BLAS/LAPACK (Note: not recommended)
CQ_EXTERNAL_OPENMP	Boolean	Force linking to an external OpenMP library. This may be necessary on macOS systems
ENABLE_COVERAGE	Boolean	Enable code coverage. This gives a huge performance penalty, and is not recommended for general use

Tested Toolchains

The following toolchains are regularly tested in the compilation of ChronusQ.

SMP only toolchains

• GCC 8.2.0, Eigen 3.3.7, HDF5 1.10.5, CMake 3.14.2
• Intel 19.1, Eigen 3.3.7, HDF5 1.10.5, CMake 3.14.2

SMP + MPI toolchain

• GCC 8.2.0, Eigen 3.3.7, HDF5 1.10.5, CMake 3.14.2, MPICH 3.2.1, SCALAPACK 2.0.2

Note: For best performance on Intel CPUs, we highly recommend compiling ChronusQ with the Intel compilers and linking to MKL for threaded linear algebra. If the Intel compilers are specified, MKL will automatically be added to the compiler invocation.

Citations

[1] Edward F. Valeev; Libint: machine-generated library for efficient evaluation of molecular integrals over Gaussians, version 2.1.0; https://github.com/evaleev/libint/; 2015

[2] Miguel A. L. Marques; Micael J. T. Oliveira; and Tobias Burnus; Libxc: a library of exchange and correlation functionals for density functional theory; Comput. Phys. Commun. 183, 2272 (2012) OAI: arXiv:1203.1739