SyTen
Introduction

Table of Contents

The SyTen software package is primarily aimed to be a tensor network toolkit with a set of standard matrix-product state, binary tree-tensor network states and infinite projected entangled pair state utilities included.

A preliminary website exists at syten.eu, which also contains a (slightly stripped) version of the documentation generated from the current master branch.

For installation instructions, see INSTALL.md. For contributor guidelines, see CONTRIBUTING.md. For authors and contributors, see CONTRIBUTORS.md. A tutorial exists in TUTORIAL.md which was found to be helpful in at least one case. There is also a list of Works using the toolkit.

There is a small, fairly self-explanatory utility note included in the repository which can be used to manage the bugs branch. This branch acts as a rudimentary bug-tracking system. Execute ./note in the root directory of the repository to launch the utility.

Organisation and Structure

File Structure

inc contains the library itself. inc is structured into folders as follows:

  • inc/util contains a set of utility functions and files, e.g. generic types, configuration macros etc.
  • inc/dense and inc/sparse contain dense and sparse ‘bunch-of-numbers’ tensor classes syten::GenericDenseTensor and syten::SparseTensor. These are tensors in the pure sense, i.e. collections of numbers in some multidimensional grid. They do not know about quantum numbers, transformation properties or anything else. They are templated on the tensor rank and the contained scalar type. syten::SparseTensor uses a coordinate format to store Clebsch-Gordan coefficients. syten::GenericDenseTensor is a variant of some specialised dense tensor classes (at the moment, syten::DenseTensor, syten::IdentityDenseTensor and syten::OffsetDenseTensor) which aim to store the data in slightly more efficient ways.
  • inc/rep is for the lowest-level IREP representation, fusing, generation etc.
  • inc/tensor contains the full symmetry-protected tensor class syten::Tensor. As syten::GenericDenseTensor and syten::SparseTensor, it is templated on the tensor rank but fixes the scalar types to syten::SDef and syten::CDef. Tensor legs are defined via their number and the basis of a tensor on a given leg is defined by its tensor block structure.
  • inc/stensor contains a ‘smart’ tensor class syten::STensor. This tensor class builds on top of syten::Tensor but hides the compile-time rank into a run-time std::variant. It furthermore introduces named bases on each tensor leg, allowing for ITensor-like tensor-tensor products. The maximal tensor rank supported by this class is defined via the SYTEN_STENSOR_MAX_RANK macro and needs to be set at compile time. To use this class at all, you need to set the SYTEN_STENSOR macro; it is currently very much work in progress. Comments and commits welcome!
  • inc/mps contains representations of MPS and MPO as well as algorithms working on them such as DMRG, TDVP etc. Classes in this directory are contained in the namespace MPS.
  • inc/btt contains binary tree tensor states, classes therein are contained in the namespace BTT.
  • inc/ipeps contains the IPEPS code.
  • inc/alg contains generic, templated numerical algorithms.

bin contains a set of standard binaries, lat is intended for the definition of lattice models (in lat/mps, lat/btt and lat/ipeps respectively) and binaries generating those models (in lat directly).

helpers/ contains various helper scripts and files. See individual comments in those files for their expected input and use or the overall page Helper Scripts.

The directory ext/ is not really considered part of the toolkit and provided mainly for convenience. It holds external libraries (currently a copy of liblz4, pybind11 and fmt) along with some glue code (install and deinstall scripts and the like). While these files are often adapted to quite some extend, the original author is not the committer.

Logical Class Structure

  • Matrix Product Operators (syten::MPS::Operator) and Matrix Product States (syten::MPS::State) are represented as vectors of individual tensors (syten::Tensor). Binary Tree Tensor Network states (syten::BTT::State) and operators (syten::BTT::Operator) are similarly represented by binary trees of rank-4 and rank-5 tensors.
  • Each tensor (syten::Tensor) is stored as a vector of symmetry-protected blocks (syten::TensorBlock) and an array of directions (syten::Direction) denoting whether the corresponding leg of the tensor is incoming or outgoing.
  • Each block consists of one reduced, dense tensor (GenericDenseTensor) and for each symmetry in the system, one sparse tensor (syten::SparseTensor). Furthermore, it contains information on how its individual legs transform. To this end, it has an array of symmetry sectors (syten::Sector).
  • Each sector is a vector of irreps (syten::Rep) which denote how that leg of the tensor block transforms w.r.t. the physical symmetry.

Binary Structure

This follows very closely the structure in the matrix product toolkit by Ian McCulloch:

  • Physical models are implemented in lat as binaries. These binaries generate a lattice file on execution. The lattice file stores operators and bases as necessary for that lattice.
  • A collection of binaries in bin can read these lattice files and act based on them, e.g. to generate a random state compatible with a given model or to optimise a state given a random input state and operator. The idea is that these binaries work on all supported types of lattices/tensor network states, usually by differentiating the different types in the binary.

Python Bindings

Python bindings exposing many of the C++ functions are currently work in progress. Simple examples already work and more and more are expected to work in the future. Instead of using a compiled C++ binary to call e.g. into the C++ MPS library, the iPEPS code uses Python bindings to use the iPEPS library from an easily extended executable script.

Alternatives

Alternatives to the comparably small SyTen toolkit include:

Acknowledgements

  • This work was supported by grant INST 86/1885-1 FUGG of the German Research Foundation (DFG).