Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Architecture & Crate Guide

This page describes how tensor4all-rs is organised, what each crate does, how to choose the right crate for your use case, and how the workspace is converging on a single TreeTN-based interface.

Two stacks today, one interface intended

The workspace currently contains two stacks, each owning its tensor-train representation and its algorithm crates. The intended direction is a single interface: TreeTN is the unified tensor-network type, and the positional SimpleTensorTrain stack is being retired. TCI, parts of quantics TCI and non-Fourier quantics transforms still produce or consume SimpleTensorTrain. Each Rust crate can be used on its own. tensor4all-capi provides the C FFI layer.

                        tensor4all-core (Index, Tensor, contraction, SVD/QR)
                                      |
              +-----------------------+------------------------+
              |                                                |
   NETWORK STACK (TreeTN, intended interface)     SIMPLETT STACK (positional, being retired)
              |                                                |
   tensor4all-treetn  (TreeTN)                    tensor4all-simplett (SimpleTensorTrain)
     |-- tensor4all-itensorlike (TensorTrain)                  |
     |-- tensor4all-treetci (tree TCI)            tensor4all-tensorci (TCI1/TCI2)
     |-- tensor4all-treeaci (tree ACI)            tensor4all-aci (chain ACI)
     |-- tensor4all-partitionedtreetn (TreeTN patches)
     |-- tensor4all-treersi (experimental RSI products)
     |-- tensor4all-interpolativeqtt (native interpolative chains)
     `-- tensor4all-quanticstransform (Fourier; optional partitionedtreetn)

   Crates that still use both stacks:
   tensor4all-quanticstci        (treetci + treetn + simplett)
   tensor4all-quanticstransform  (with the default simplett-transforms feature)

   tensor4all-capi  (C FFI for language bindings; depends on both stacks)
   tensor4all-hdf5  (MPS serialization, ITensors.jl-compatible)

The migration bridge: treetn::simplett_bridge

While both stacks exist, the only sanctioned place where they convert into each other is treetn::simplett_bridge, a migration aid rather than a permanent layer. It is available only with the explicit simplett-bridge feature; TreeTN’s default features do not resolve SimpleTT:

  • tensor_train_to_treetn / tensor_train_to_treetn_with_names / tensor_train_to_treetn_with_names_and_site_indices: simplett SimpleTensorTrain -> network TreeTN;
  • treetn_to_tensor_train: network TreeTN (linear chain) -> simplett SimpleTensorTrain;
  • insert_onehot_site_in_treetn_chain, weighted_remove_site_from_treetn_chain: chain-topology helpers.

General-tree, name-addressed site fixing lives on treetn::fix_and_remove_site and is not part of the simplett bridge.

Crates that need to cross stacks must route through this bridge. New ad hoc bridges (hand-rolled conversion logic inside another crate) are rejected. The TreeTN-native tensor4all-partitionedtreetn operates directly on named TreeTN<IdxTensor, V> values and does not depend on simplett, itensorlike, or TCI crates. Its adaptive interpolation driver sees interpolation engines only through the TreeInterpolator trait in tensor4all-treetn; engines such as tensor4all-treetci implement that trait.

The Fourier constructors in tensor4all-quanticstransform build operators directly as TreeTN. The optional partitioned feature adds a dependency on tensor4all-partitionedtreetn for the lazy reconstruction front end. The QFT guide shows how to select a CPU provider and build without SimpleTT or the TreeTN bridge.

The default simplett-transforms feature retains non-Fourier operators and SimpleTT conversions in the transform crate. Its tensortrain_to_linear_operator converts SimpleTT MPO data with two site indices per node into a TreeTN-based LinearOperator. MPO-specific index bookkeeping belongs in the transform layer. The TreeTN bridge handles MPS-shaped chains with one site index per node.

Which stack does a new feature crate target?

  • New features target TreeTN, chains included: operators, evolution, DMRG/TDVP, cross interpolation and quantics kernels build on tensor4all-treetn (or tensor4all-itensorlike when ITensors.jl-style semantics are wanted). Shared numerical substrate (factorizations, matrix CI, CachedFunction) lives in tensor4all-core.
  • The simplett stack is maintained, not extended: existing tensor4all-simplett / tensor4all-tensorci functionality stays available until its TreeTN replacement lands, but new capabilities are not added there.
  • While a feature still needs both stacks, it crosses through treetn::simplett_bridge; it is not duplicated in both.

Where tensor4all-rs sits in the tensor4all stack

This workspace is the algorithm layer of a five-layer stack. Every dense operation eventually executes in one of the layers below, and that layering is what keeps the public API stable while the kernels underneath are replaced.

LayerRepositories and cratesEntry point from this workspace
FrontendsTensor4all.jl; the tensor4all-capi (C FFI) and tensor4all-py crates in this workspacethis workspace is what they build on
Algorithmsthis repository; quanticsgrids-rs; hataori-rsquanticsgrids through tensor4all-quanticstci, tensor4all-quanticstransform, tensor4all-treetci and tensor4all-interpolativeqtt; hataori / hataori-tenferro through tensor4all-partitionedtreetn and the optional parallel feature of tensor4all-interpolativeqtt
Tensor runtimetenferro-rs (caller-owned engines); computegraph-rstensor4all-tensorbackend
Kernel providerscpueinsum-rs, tcontract-rs, tlinalg-rsnone: reached inside tenferro-rs
Foundationstrided-rs, t4a-faer (faer fork), BLAS/LAPACKnone: reached inside the kernel providers and t4a-faer

The GPU path is the same picture one layer lower: tenferro-gpu pulls t4a-cuda-kernels and t4a-cuda-runtime, which call cuBLAS and cuTENSOR. No CubeCL package remains in the lock, which is why the CUDA tutorial names the tenferro GPU stack instead.

Since late August the dense kernels were split out of tenferro into the kernel-provider crates, and tenferro’s BackendSession was replaced by the caller-owned CpuEngine that CpuBackend in tensor4all-tensorbackend wraps. Two rules follow:

  • No workspace crate depends directly on a kernel-provider or foundation crate. cpueinsum, tcontract, tlinalg, t4a-faer, gemm, t4a-private-gemm-x86 and the strided-* crates appear in Cargo.lock only as dependencies of tenferro and of each other.
  • Tensor operations enter the runtime through tensor4all-tensorbackend. It owns the engine objects and the backend feature switches (tenferro-cpu-platform, tenferro-cpu-faer, tenferro-system-blas, tenferro-cuda, tenferro-provider-inject). A crate that only needs tenferro’s value types may name tenferro-tensor or tenferro-cpu, but a new operation belongs in tensor4all-tensorbackend, not in the algorithm crate that calls it.

tensor4all-hdf5 additionally takes hdf5-rt for runtime HDF5 loading; that is an I/O helper, not part of the numeric stack.

The interactive layered map is at tensor4all.org/tensor4all-meta/stack.

Vocabulary conventions

Beyond the naming-policy suffixes (_mut, _into, _batched), the following operation names are unified across crates:

  • Addition: add is the exact sum on every tensor-network type. PartitionedTreeTN::add_truncated also truncates the keys present in both operands; its error is not bounded by the cutoff in its options.
  • Inner product: inner_product everywhere. (dot was retired in tensor4all-simplett.)
  • Densification: full_tensor materializes a tensor train/MPO into a flat column-major buffer plus shape; to_dense materializes a single tensor into a dense IdxTensor. The distinction is intentional (whole-TT vs one-tensor).
  • Canonicalization: treetn uses canonicalize / canonicalize_mut; itensorlike uses orthogonalize (ITensors.jl-compatible vocabulary) for the same center-site normalization. Each stack keeps its standard term; do not introduce a third synonym.
  • Options: bond caps use max_bond_dim: Option<usize>; truncation tolerances use SvdTruncationPolicy (rtol/cutoff); sweep counts use nfullsweeps/nsweeps (TreeTN) or nhalfsweeps (itensorlike) as documented in the skills guide. This is the target vocabulary; some older entry points still use other option names, and unifying them is tracked in #915.

TensorTrain naming resolution

Two different types are named TensorTrain-family, which is the historical naming trap that PR 3 resolves:

TypeCrateRepresentationUse when
SimpleTensorTrain<T>tensor4all-simplettpositional cores (Tensor3<T>), no named indiceslightweight create/evaluate/compress
TensorTraintensor4all-itensorlikeTreeTN<IdxTensor, usize> wrapper with orthogonality trackingITensors.jl-style interface

Rules:

  • tensor4all-simplett::SimpleTensorTrain is the positional chain type. Prefer it for numerical kernels.
  • tensor4all-itensorlike::TensorTrain is the tree-based chain type with named indices, canonical forms, and orthogonality tracking.
  • There are no compatibility aliases: TensorTrain alone always means the itensorlike type inside that crate, and simplett code must write SimpleTensorTrain.

The corresponding errors follow the representation names:

ErrorOwnerCovers
tensor4all_simplett::SimpleTensorTrainErrorSimpleTensorTrainpositional shapes, flat indices, and MatrixCI failures
tensor4all_itensorlike::TensorTrainErroritensorlike TensorTrainnamed indices, TreeTN structure, orthogonality, and factorization

They stay separate while both stacks exist; the distinct names prevent ambiguous imports.

Scalar capability boundaries

Scalar traits are layered capabilities rather than interchangeable numeric aliases:

CapabilityPurpose
tensor4all_core::Scalarcommon value arithmetic and conversion
tensor4all_core::MatrixLuciScalarcore Scalar plus MatrixLUCI backend dispatch; sealed to the four supported scalars
tensor4all_tensorbackend::TensorElementsupported Rust scalar ↔ native tensor conversion
tensor4all_tensorbackend::StorageScalarcompact storage construction
tensorbackend matrix/linalg traitsindividual backend kernel capabilities
tensor4all_simplett::TTScalarpositional tensor-train arithmetic requirements
ACI/TreeACI scalar traitssealed algorithm-supported types and algorithm-only operations

tensor4all_core::AnyScalar is the only public AnyScalar; it may retain an AD-tracked rank-0 tensor. The internal tensorbackend value is named BackendScalar and is an untracked compact scalar. Do not replace these capability boundaries with one all-purpose supertrait: that would force storage and algorithm requirements onto unrelated generic code.

Layer descriptions

Foundation

CrateDescription
tensorbackendPublic low-level infrastructure: the dense Matrix container, the CpuExecutionContext execution context (built from a caller-configured CpuBackend, re-exported here), compact f64/Complex64/f32/Complex32 storage, and tenferro-backed primitives. Most users reach it through the higher-level crates; depend on it directly when you need these building blocks. Not every pub item is a stability promise.
coreFoundation for everything else. Owns the shared abstractions (Index system, dynamic-rank Tensor, contraction, SVD/QR/LU factorizations) and the matrix-CI substrate (rrLU/LUCI, CachedFunction, MultiIndex).

Network stack

CrateDescription
treetnTree tensor networks with arbitrary graph topology. Supports canonicalization, truncation, contraction, DMRG/TDVP, and the opt-in simplett-bridge migration feature.
itensorlikeITensors.jl-inspired TensorTrain (tree-based) with orthogonality tracking and multiple canonical forms.
partitionedtreetnTreeTN-native eagerly masked subdomains, strict partition algebra, volume-budgeted adaptive patching, sequential adaptive patched interpolation through any TreeInterpolator engine, reconstruction against a fixed global L2 tolerance, and level-coupled merge-refine QFT scheduling.
treersiExperimental CPU Hadamard products on TreeTN via recursive sketched interpolation; requires independent accuracy checks.
treeaciExperimental Alternating Cross Interpolation directly on TreeTN with any validated tree topology (no path-order requirement, unlike tensor4all-aci).
treetciTree TCI: cross interpolation on tree-structured tensor networks; TreeTciInterpolator implements the TreeInterpolator engine trait.

Simplett stack

CrateDescription
simplettLightweight positional tensor train (SimpleTensorTrain) for numerical computation.
tensorciTensor Cross Interpolation. Contains TCI2 (primary algorithm) and TCI1 (legacy).
quanticstciHigh-level Quantics TCI. Interpolates functions on discrete or continuous grids in the quantics format.

Quantics & transforms

CrateDescription
quanticstransformConstructs TreeTN Fourier operators (including explicit multi-axis layouts). The optional partitioned feature provides lazy patched Fourier transforms on one tree path. The default simplett-transforms feature provides shift, flip, affine, and other transforms that use SimpleTT.
interpolativeqttNative TreeTN interpolative QTT construction on a coarse grid, returning ordered physical indices. See the interpolative-QTT tutorial.

Applications

CrateDescription
aciAlternating Cross Interpolation (ACI) for elementwise tensor-train operations.

I/O & bindings

CrateDescription
hdf5HDF5 serialization compatible with ITensors.jl/ITensorMPS.jl file formats.
capiC FFI for language bindings (Julia, C, C++). Out of scope for this guide; see Julia Bindings.
tensor4all-pyPyO3 bindings for Python (prototype). Not a workspace member; see its README.md.

Which crate should I use?

GoalRecommended crate
TCI on a black-box function (high level)tensor4all-quanticstci
TCI with fine-grained controltensor4all-tensorci
Sketched Hadamard products of existing TreeTNstensor4all-treersi (experimental)
Tree TCItensor4all-treetci
Simple positional tensor train (create, evaluate, compress)tensor4all-simplett (SimpleTensorTrain)
Tensor train with ITensors.jl-style interfacetensor4all-itensorlike (TensorTrain)
Tree tensor networkstensor4all-treetn
Subdomain decomposition on named TreeTNstensor4all-partitionedtreetn
Adaptive patched interpolation of a function on a named treetensor4all-partitionedtreetn::adaptive_interpolation with an engine such as tensor4all-treetci::TreeTciInterpolator
Reconstruct orthogonal patches or tensor products with a global L2 tolerancetensor4all-partitionedtreetn::reconstruction
Lazy patched Fourier transform on selected axestensor4all-quanticstransform with partitioned (see QFT guide)
Quantics transform operatorstensor4all-quanticstransform
HDF5 I/O compatible with Juliatensor4all-hdf5
Interpolative QTT on a coarse gridtensor4all-interpolativeqtt
Elementwise TT ops via ACItensor4all-aci (chains) or tensor4all-treeaci (any TreeTN)

Error remedies

Public error types use thiserror, preserve the source error, carry structured fields, and name an actionable remedy in the rustdoc when one is documented. Recurring cases avoid opaque string payloads. cargo clippy is configured with -D clippy::missing_errors_doc -D clippy::missing_panics_doc so every fallible or panicking public function documents its failure modes.

Low-level crates

tensor4all-tensorbackend is public low-level infrastructure; its Matrix container and execution contexts are meant to be used across crates, but lower-level items may change while the API settles. The former tensor4all-tcicore crate was dissolved into tensor4all-core (#639): the matrix CI / LUCI / rrLU algorithms, CachedFunction, and MultiIndex now live in core. These interfaces may still change without notice.