Installation Guide

Short Version

To build and install SeQuant, run the following commands in the source directory:

cmake -B build -S .
cmake --build build
cmake --build build --target install

Prerequisites

Mandatory

Note

SeQuant can download and build Boost if configured with Boost_FETCH_IF_MISSING=ON, but the use of Boost provided by the system package manager is recommended. The following non-header-only Boost libraries are required, hence Boost must be configured/built:

  • Boost.Regex

  • Boost.Locale

Optional

  • TiledArray - for building coupled-cluster evaluation tests

Note

If not found, SeQuant can download and build all dependencies other than CMake and the C++ compiler, provided git is available on the system.

Useful CMake Variables

CMake Variable

Default

Description

CMAKE_CXX_COMPILER

Specifies the C++ compiler to use.

CMAKE_PREFIX_PATH

This semicolon-separated list specifies search paths for dependencies (Boost, Range-V3, etc.).

CMAKE_INSTALL_PREFIX

The installation path for SeQuant.

SEQUANT_TESTS

BUILD_TESTING

Enables test targets, e.g. check-sequant.

SEQUANT_SKIP_LONG_TESTS

OFF

Skip long test cases within unit and integration tests. Debug configurations always skip them, regardless of this option.

SEQUANT_BTAS

OFF

SeQuant will look for (or build) BTAS tensor library and enable its use as an evaluation backend.

SEQUANT_TILEDARRAY

OFF

SeQuant will look for (or build) TiledArray tensor framework and enable its use as an evaluation backend.

SEQUANT_TAPP

OFF

SeQuant will look for (or build) TAPP and enable its use as an evaluation backend.

SEQUANT_FETCH_MISSING_DEPENDENCIES

ON

If set to OFF, SeQuant will not fetch any dependency: a missing one is a configure error naming the package and its minimum version (and Boost_FETCH_IF_MISSING is forced to OFF). DTL, needed by the tests, can then be supplied with -DDTL_INCLUDE_DIR=<directory containing dtl/dtl.hpp>; spdlog (SEQUANT_UTILITIES only) cannot be located, so set SEQUANT_UTILITIES=OFF.

SEQUANT_INSTALL_FETCHED_DEPENDENCIES

ON

Master switch for installing what SeQuant had to fetch. If ON, the fetched primary prerequisites (Range-V3, polymorphic_variant, libPerm, nlohmann::json) are installed into CMAKE_INSTALL_PREFIX alongside SeQuant, and fetched evaluation backends can be selected for installation with SEQUANT_INSTALL_FETCHED_BACKENDS. Dependencies that were found are never installed. If OFF, nothing fetched is installed: the installed sequant-config.cmake looks for the prerequisites with find_dependency and the consumer must provide them (e.g. via CMAKE_PREFIX_PATH), and a non-empty SEQUANT_INSTALL_FETCHED_BACKENDS is a configure error.

SEQUANT_INSTALL_FETCHED_BACKENDS

(empty)

Semicolon-separated, case-insensitive subset of TiledArray;BTAS;TAPP: the fetched evaluation backends to install with SeQuant (requires SEQUANT_INSTALL_FETCHED_DEPENDENCIES=ON). A fetched backend that is not listed is usable from the build tree but is neither installed nor exported, so the installed SeQuant does not provide SeQuant::eval::<backend> for it. BTAS built as part of a fetched TiledArray is installed only together with TiledArray (listing BTAS alone warns).

SEQUANT_OVERWRITE_INSTALLED_DEPENDENCIES

OFF

By default the install fails rather than overwrite a different version of a package already present in the destination ($ENV{DESTDIR}${CMAKE_INSTALL_PREFIX}); the same version passes. If ON, the failure becomes a warning.

SEQUANT_BENCHMARKS

ON

Enable SeQuant benchmarks.

SEQUANT_MIMALLOC

OFF

Use mimalloc for fast memory allocation.

SEQUANT_BUILD_DOCS

OFF

Enables building of the documentation. See Documentation Guide for detailed information.

SEQUANT_PYTHON

OFF

Enables building of Python bindings. Changes the default of SEQUANT_ASSERT_BEHAVIOR to THROW (see below).

SEQUANT_USE_SYSTEM_BOOST_HASH

ON

Use system Boost for hashing? Set to OFF to make hashing independent of Boost, thus value-portable

SEQUANT_IWYU

OFF

Whether to use the include-what-you-use tool (if found)

Boost_FETCH_IF_MISSING

ON

If set to ON, SeQuant will download and build Boost if it is not found by find_package(Boost ...); this is not recommended.

ENABLE_TBB

OFF

Enable TBB as an optional prerequisite for C++’s parallel STL

SEQUANT_CONTEXT_MANIPULATION_THREADSAFE

ON

If set to OFF the default context must be initialized and manipulated from single thread only (most users will want to do this).

SEQUANT_ASSERT_BEHAVIOR

THROW if SEQUANT_PYTHON=ON; otherwise IGNORE in Release and MinSizeRel mode, ABORT otherwise

Controls how assertions within SeQuant’s code are handled. Valid options are ABORT, THROW and IGNORE. The latter disables assertions, whereas the former keep them active and either abort the program or throw an exception on violation respectively. SEQUANT_ENFORCE checks remain active in all three modes: they follow the configured assertion behavior, except that IGNORE makes them throw sequant::Exception on failure. Failure diagnostics include the checked condition, source file, line number, and enclosing function. The Python bindings need THROW so that a failed check raises a Python exception instead of aborting the interpreter or going unnoticed; configuring with SEQUANT_PYTHON=ON and any other value emits a warning. On the first configure of a build directory this also seeds the corresponding option of the dependencies SeQuant builds from source: TA_ASSERT_POLICY of TiledArray (which in turn seeds BTAS_ASSERT_POLICY of the BTAS it builds), or BTAS_ASSERT_POLICY of BTAS when SeQuant builds BTAS itself (SEQUANT_TILEDARRAY=OFF). As with any cached option, an explicit -DTA_ASSERT_POLICY=.../-DBTAS_ASSERT_POLICY=... wins, and a later change of SEQUANT_ASSERT_BEHAVIOR does not re-seed them: set them explicitly, or use a fresh build directory.

SEQUANT_LTO

context-dependent — see Description

Controls whether SeQuant will be built with link-time optimizations (LTO) in non-debug builds (CMAKE_BUILD_TYPE != Debug). Left unset, it defaults per target type: ON for static libraries if the compiler supports “fat” LTO objects, OFF otherwise; ON for other target types (shared libs, executables, etc.); OFF for all targets when SeQuant is consumed as a subproject. Set to ON or OFF explicitly to override the per-target-type default for all SeQuant targets; an explicit setting is honored regardless of whether SeQuant is the top-level project.

Configuring and Building

To configure and build SeQuant, you can use various CMake variables to customize the build process. These variables can be set using the -D flag when running the cmake command. For example:

cmake -B build -S . -D<VARIABLE_NAME>=<VALUE>

Now you can build SeQuant by running the following command in the source directory:

cmake --build build
cmake --build build --target check-sequant # for testing
cmake --build build --target install

What the Install Adds to the Prefix

Besides SeQuant itself, the default install also installs the primary prerequisites that SeQuant had to fetch (Range-V3, polymorphic_variant, libPerm, nlohmann::json) into CMAKE_INSTALL_PREFIX; the configure output lists them, e.g. SeQuant will install these fetched dependencies (and what they install themselves) into <prefix>: range-v3 0.12.0, .... Dependencies found on the system are never installed. Note that CMAKE_FIND_NO_INSTALL_PREFIX is ON by default, so a dependency already in CMAKE_INSTALL_PREFIX is found only if that prefix is on CMAKE_PREFIX_PATH (or <pkg>_DIR is set); otherwise it is fetched again and reinstalled.

  • Fetched evaluation backends are installed only if listed in SEQUANT_INSTALL_FETCHED_BACKENDS. A fetched backend that is not listed is neither installed nor exported, so a project that exports targets linking SeQuant::eval::<backend> must list it.

  • The install first stages itself into a scratch directory under the build directory and enumerates every CMake package (by its package version file) that it is about to install, including what the fetched dependencies install in turn (e.g. MADNESS with TiledArray); it prints that list, e.g. SeQuant installs these packages into <prefix>: ..., and refuses to overwrite a different version of any of them already in the destination unless SEQUANT_OVERWRITE_INSTALLED_DEPENDENCIES=ON. Instead, upgrade or remove the installed copy, make SeQuant use it instead of fetching (put its prefix on CMAKE_PREFIX_PATH, or set <pkg>_DIR, and reconfigure), or install into a different prefix. A package without a version file, or one with the same version but different contents (e.g. another commit of TiledArray’s 1.0.0), is not detected.

  • SEQUANT_INSTALL_FETCHED_DEPENDENCIES=OFF installs SeQuant alone, backends included; packagers who want no fetching at all should set SEQUANT_FETCH_MISSING_DEPENDENCIES=OFF.

  • Known gap: Boost built from source (Boost_FETCH_IF_MISSING) is installed by its own build system and is not covered by the configure summary or SEQUANT_INSTALL_FETCHED_DEPENDENCIES; the overwrite check sees it only if its files go through SeQuant’s install script.

Windows

SeQuant needs more stack space than the 1 MB that Windows reserves per thread by default (Linux and macOS typically provide 8 MB). SeQuant’s own executables are therefore linked with /STACK:8388608, and executables using SeQuant must be linked with an equivalent stack reserve too, e.g. via target_link_options(<target> PRIVATE /STACK:8388608). This reserve is the default for every thread of the program; threads created with an explicit stack size that call into SeQuant need a comparable size.

Versioning

SeQuant uses calendar versioning: YY.N for a release, where YY is the two-digit year and N counts the releases within that year starting from 0, and YY.N.P for the P-th patch release of YY.N; e.g. 26.2 is the third release of 2026 and 26.2.1 its first patch release. Releases up to 2.2.0 used semantic versioning; 26.2 is the first calendar-versioned release. Since a version is just a dot-separated sequence of integers, find_package(SeQuant 26.2) and similar version requirements work as usual. See Release Guide for details.