Xped

Library for the manipulation of symmetric (block-sparse) tensors with arbitrary (X) amount of indices (ped).

Status

Builds	Tests	Coverage

Getting started

Xped/docs/snippets/quickstart.cpp

Lines 1 to 47 in 1eab6bf

	#include <type_traits>
	#include "Xped/Core/Tensor.hpp"
	int main()
	{
	// Make an alias for the symmetry. In this case a U1 symmetry for a spin.
	using Symmetry = Xped::Sym::U1<Xped::Sym::Spin>;
	// Initialize random basis objects which will be used to initialize tensors
	Xped::Qbasis<Symmetry, /*depth=*/1> B1;
	B1.setRandom(10);
	Xped::Qbasis<Symmetry, /*depth=*/1> B2;
	B2.setRandom(10);
	// Initialize a random rank-3 tensor with two incoming and one outgoing leg with double precision numbers constrained by the symmetry declared
	// above
	Xped::Tensor<double, /*Rank=*/2, /*CoRank=*/1, Symmetry> T({{B1, B2}}, {{B1.combine(B2).forgetHistory()}});
	T.setRandom();
	// Unary and binary coefficientwise operations:
	auto S = 3. * T; // this is an expression which is lazely evaluated
	Xped::Tensor<double, 2, 1, Symmetry> Q = S.eval() + T; //.eval() can be used to force evaluation and assignment to tensor also forces evaluation
	// makes a truncated singular value decomposition between domain and codomain keeping at most 50 singular values and discarding all singular
	// values less than 1.e-10:
	auto [U, Sigma, Vdag] = S.tSVD(50, 1.e-10);
	static_assert(std::is_same_v<decltype(U), Xped::Tensor<double, 2, 1, Symmetry>>);
	static_assert(std::is_same_v<decltype(S), Xped::Tensor<double, 1, 1, Symmetry>>);
	static_assert(std::is_same_v<decltype(Vdag), Xped::Tensor<double, 1, 1, Symmetry>>);
	// Permutation of the indices. shift specifies how much the domain is decreasing (and the codomain is increasing). The following indices
	// describes the permutation.
	auto X = T.permute</*shift1=*/+1, 2, 1, 0>(); // this gets evaluated immediately
	// This is an SVD with a different partitioning of the legs
	auto [U_, Sigma_, Vdag_] = X.tSVD(50, 1.e-10);
	static_assert(std::is_same_v<decltype(U_), Xped::Tensor<double, 1, 1, Symmetry>>);
	static_assert(std::is_same_v<decltype(S_), Xped::Tensor<double, 1, 1, Symmetry>>);
	static_assert(std::is_same_v<decltype(Vdag_), Xped::Tensor<double, 1, 2, Symmetry>>);
	// Multiplication of tensors is the contraction over the matching codomain/domain of the two tensors
	auto prod = T * T.adjoint(); // this gets also evaluated immediately
	// Arbitrary contractions are also possible:
	auto res = T.contract<std::array{-1, -2, 1}, std::array{1, -4, -3}, /*ResRank=*/2>(X);
	static_assert(std::is_same_v<decltype(res), Xped::Tensor<double, 2, 2, Symmetry>>);
	}

Build

1. Get the sources using: git clone --recurse-submodules https://github.com/cpp977/Xped
2. Configure with cmake: cmake --preset=<preset> /path/to/source/Xped This also installs dependencies via vcpkg so the first run takes several minutes. The build directory is specified in the presets: /path/to/source/Xped/../<preset-name>
3. Build tests: cmake --build --preset=<preset>
4. Run the tests: ctest --preset=<preset>

To control the build, it is recomennded to choose a CMake preset so that several options are already set automatically. The available presets follow the scheme <compiler>-<backend>-<build-type>. E.g. gcc-eigen-release uses the gnu c++ compiler and the Eigen backend and performs a release build. Supported compilers are gcc (version >= 10), clang (version >= 12), msvc (version >= 19.30) and intel icpx (version >= 2021.04).

All build options can be seen in the following table.

Build Options

Option	Default	Description
XPED_BUILD_BENCHMARKS	ON	Build the benchmarks.
XPED_BUILD_CYCLOPS	OFF	Build the cyclops library from source.
XPED_BUILD_EXAMPLES	OFF	Build the benchmarks.
XPED_BUILD_TESTS	ON	Build the tests.
XPED_BUILD_TOOLS	ON	Build the tools.
XPED_COMPILED_LIB	OFF	Configure the library as a compiled library. Long compile times.
XPED_EFFICIENCY_MODEL	XPED_TIME_EFFICIENT	Xped tries to be time efficient.
XPED_ENABLE_BUILD_WITH_TIME_TRACE	OFF	Enable -ftime-trace to generate time tracing .json files on clang
XPED_ENABLE_CCACHE	OFF	Enable a compiler cache if available
XPED_ENABLE_CLANG_FORMAT	ON	Enable clang-format target.
XPED_ENABLE_CLANG_TIDY	OFF	Enable static analysis with clang-tidy
XPED_ENABLE_COVERAGE	OFF	Enable coverage reporting for gcc/clang
XPED_ENABLE_CPPCHECK	OFF	Enable static analysis with cppcheck
XPED_ENABLE_DOXYGEN	OFF	Enable doxygen doc builds of source
XPED_ENABLE_INCLUDE_WHAT_YOU_USE	OFF	Enable static analysis with include-what-you-use
XPED_ENABLE_IPO	OFF	Enable Interprocedural Optimization, aka Link Time Optimization (LTO)
XPED_ENABLE_LRU_CACHE	OFF	Use lru cache library from github.
XPED_ENABLE_SANITIZER_ADDRESS	OFF	Enable address sanitizer
XPED_ENABLE_SANITIZER_LEAK	OFF	Enable leak sanitizer
XPED_ENABLE_SANITIZER_MEMORY	OFF	Enable memory sanitizer
XPED_ENABLE_SANITIZER_THREAD	OFF	Enable thread sanitizer
XPED_ENABLE_SANITIZER_UNDEFINED_BEHAVIOR	OFF	Enable undefined behavior sanitizer
XPED_LAPACKE	/usr/lib/x86_64-linux-gnu/liblapacke.so	Path to a library.
XPED_LOG_LEVEL	SPDLOG_LEVEL_CRITICAL	Compile time log level.
XPED_MATRIX_LIB	Eigen	Used matrix library for plain tensor operations.
XPED_OPTIM_LIB	ceres	Used library for nonlinear gradient-based optimization.
XPED_PEDANTIC_ASSERTS	OFF	Enables rigorous assertions for tensor operations.
XPED_STORAGE	Contiguous	Used storage for Xped::Tensor.
XPED_TENSOR_LIB	Eigen	Used tensor library for plain tensor operations.
XPED_USE_AD	ON	Use automatic differentiation (AD) with Xped Tensors.
XPED_USE_BLAS	ON	Enable blas linking.
XPED_USE_LAPACK	ON	Enable lapack linking.
XPED_USE_LIBCXX	OFF	Use libc++ from llvm.
XPED_USE_MKL	OFF	Enable use of intel math kernel library (MKL).
XPED_USE_MPI	OFF	Enable message parsing interface (mpi) parallelization
XPED_USE_NLO	ON	Use nonlinear optimization algorithms.
XPED_USE_OPENMP	ON	Enable openmp parallelization
XPED_USE_SCALAPACK	OFF	Enable scalapack linking (only useful for MPI programs).
XPED_VECTOR_LIB	Eigen	Used vector library for plain tensor operations.

Documentation

Browse the documenation to learn about the capabilities of the library.

Acknowledgment

This library is inspired by a tensor framework for symmetric tensors written in the Julia programming language: TensorKit.