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¶

CMake 3.28 or later
C++20 compatible compiler
Boost 1.81 or later (1.85 or later with MSVC)
Range-V3 0.12.0 or later
Eigen3 3.0 or later
libperm
polymorphic_variant
Utfcpp 4.0 or later
DTL 1.12 or later - only used for unit tests
CLI11 2.0 or later - only used for external interface
spdlog - only used for external interface
nlohmann::json 3.0 or later - only used for external interface

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_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	OFF	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

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.