Installing ParallelZone

ParallelZone uses CMaize as its build system, more detailed build instructions can be found here.

Note

We strongly recommend users use CMake toolchains to pass arguments to the cmake command. Typically CMake toolchains live in files named <prefix>-toolchain.cmake, where <prefix>- is an optional prefix to distinguish among toolchains. The contents of the CMake toolchain file usually just sets configuration values set via the standard CMake set function, i.e., set(<option_name> <value>).

Todo

Figure out what’s going on with CUDA, HIP, SYCL, and PAPI and update documentation accordingly. Right now all of these are off by default (and not used by ParallelZone) so users can safely ignore them.

Install Command

In many cases ParallelZone can be installed by:

git clone https://github.com/NWChemEx/ParallelZone
cd ParallelZone
cmake -H. -Bbuild -DCMAKE_TOOLCHAIN_FILE=<path/to/toolchain/file> \
                  -DCMAKE_INSTALL_PREFIX=<where/to/install/parallelzone>
cmake --build build --target install

Where <path/to/toolchain/file> should be replaced by the path to your toolchain file, and <where/to/install/parallelzone> should be replaced with where you want to put the installed library (absolute path is recommended in both cases).

Note

The above command will build serially. To build ParallelZone with N processors additionally pass --parallel <N> to the last command in the above code block, i.e.,

cmake --build build --parallel <N> --target install

Configuration Options

This is a list of configuration options recognized by ParallelZone’s build system.

BUILD_TESTING.

Off by default. Set to a truth-y value to enable testing.

BUILD_DOCS.

Off by default. Set to a truth-y value to build the C++ API documentation.

ONLY_BUILD_DOCS.

Off by default. If BUILD_DOCS is set to a truth-y value and ONLY_BUILD_DOCS is also set to a truth-y value, then the configure process will skip all other aspects of the configuration aside from creating the parallelzone_cxx_api target.

BUILD_PYBINDINGS.

On by default. When enabled the optional Python API is built.

ParallelZone Dependencies

If you have a problem building ParallelZone it’s most likely because you don’t have a new enough version of CMake installed or because CMake can’t find one of ParallelZone’s dependencies. This section enumerates ParallelZone’s dependencies.

C++ Compiler

ParallelZone relies on the C++17 standard and should work with any C++17 compliant compiler (GCC 9.x or newer). C++ compilers can often be installed by your OS’s package manager. CMake detects your C++ compiler via the value of CMAKE_CXX_COMPILER. So ensure CMAKE_CXX_COMPILER is set to the C++ compiler you want to use.

Todo

Clang support.

MPI

Users must have an MPI distribution installed prior to building ParallelZone. MPI distributions exist in most major OS-level package managers, so check your package manager before installing MPI from source.

While CMake can find MPI if it is installed in your OS’s standard spot, you may need to give CMake a hint in some cases. MPI provides compiler wrappers and it’s best to let CMake discover MPI via the C++ wrapper. Add:

set(MPI_CXX_COMPILER <path/to/mpicxx>)

to your toolchain to point CMake to MPI’s C++ compiler wrapper.

Cppyy

URL: https://github.com/wlav/cppyy

If Python bindings are enabled (controlled by the CMake variable BUILD_PYBINDINGS, which is ON by default). Cppyy is obtainable via PyPI (i.e., the pip command). If Python bindings are desired, the python executable found by CMake must have Cppyy installed.

Other Dependencies

The dependencies in this section can be built by ParallelZone’s build system when they are not located. Under normal circumstances users can ignore them. They are listed here primarily for completeness.

Catch2

URL: https://github.com/catchorg/Catch2

Used for unit testing. Only needed if unit testing is enabled (controlled by the CMake variable BUILD_TESTING, which is OFF by default).

Cereal

URL: https://github.com/USCiLab/cereal

Used for serialization. The build system can automatically build Cereal for you if it’s not found.

CMaize

URL: https://cmakepp.github.io/CMaize/index.html

Used to simplify writing a CMake-based build system. The build system will grab it for you.

Doxygen

URL: https://www.doxygen.nl/

Used to generate the C++ API documentation. Only needed if BUILD_DOCS is set to a truth-y value.

spdlog

URL: https://www.github.com/gabime/spdlog

The guts of the logging system provided by ParallelZone.