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: simplettSimpleTensorTrain-> networkTreeTN;treetn_to_tensor_train: networkTreeTN(linear chain) -> simplettSimpleTensorTrain;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 ontensor4all-treetn(ortensor4all-itensorlikewhen ITensors.jl-style semantics are wanted). Shared numerical substrate (factorizations, matrix CI,CachedFunction) lives intensor4all-core. - The simplett stack is maintained, not extended: existing
tensor4all-simplett/tensor4all-tensorcifunctionality 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.
| Layer | Repositories and crates | Entry point from this workspace |
|---|---|---|
| Frontends | Tensor4all.jl; the tensor4all-capi (C FFI) and tensor4all-py crates in this workspace | this workspace is what they build on |
| Algorithms | this repository; quanticsgrids-rs; hataori-rs | quanticsgrids 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 runtime | tenferro-rs (caller-owned engines); computegraph-rs | tensor4all-tensorbackend |
| Kernel providers | cpueinsum-rs, tcontract-rs, tlinalg-rs | none: reached inside tenferro-rs |
| Foundation | strided-rs, t4a-faer (faer fork), BLAS/LAPACK | none: 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-x86and thestrided-*crates appear inCargo.lockonly 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 nametenferro-tensorortenferro-cpu, but a new operation belongs intensor4all-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:
addis the exact sum on every tensor-network type.PartitionedTreeTN::add_truncatedalso truncates the keys present in both operands; its error is not bounded by the cutoff in its options. - Inner product:
inner_producteverywhere. (dotwas retired intensor4all-simplett.) - Densification:
full_tensormaterializes a tensor train/MPO into a flat column-major buffer plus shape;to_densematerializes a single tensor into a denseIdxTensor. The distinction is intentional (whole-TT vs one-tensor). - Canonicalization:
treetnusescanonicalize/canonicalize_mut;itensorlikeusesorthogonalize(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 useSvdTruncationPolicy(rtol/cutoff); sweep counts usenfullsweeps/nsweeps(TreeTN) ornhalfsweeps(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:
| Type | Crate | Representation | Use when |
|---|---|---|---|
SimpleTensorTrain<T> | tensor4all-simplett | positional cores (Tensor3<T>), no named indices | lightweight create/evaluate/compress |
TensorTrain | tensor4all-itensorlike | TreeTN<IdxTensor, usize> wrapper with orthogonality tracking | ITensors.jl-style interface |
Rules:
tensor4all-simplett::SimpleTensorTrainis the positional chain type. Prefer it for numerical kernels.tensor4all-itensorlike::TensorTrainis the tree-based chain type with named indices, canonical forms, and orthogonality tracking.- There are no compatibility aliases:
TensorTrainalone always means the itensorlike type inside that crate, and simplett code must writeSimpleTensorTrain.
The corresponding errors follow the representation names:
| Error | Owner | Covers |
|---|---|---|
tensor4all_simplett::SimpleTensorTrainError | SimpleTensorTrain | positional shapes, flat indices, and MatrixCI failures |
tensor4all_itensorlike::TensorTrainError | itensorlike TensorTrain | named 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:
| Capability | Purpose |
|---|---|
tensor4all_core::Scalar | common value arithmetic and conversion |
tensor4all_core::MatrixLuciScalar | core Scalar plus MatrixLUCI backend dispatch; sealed to the four supported scalars |
tensor4all_tensorbackend::TensorElement | supported Rust scalar ↔ native tensor conversion |
tensor4all_tensorbackend::StorageScalar | compact storage construction |
| tensorbackend matrix/linalg traits | individual backend kernel capabilities |
tensor4all_simplett::TTScalar | positional tensor-train arithmetic requirements |
| ACI/TreeACI scalar traits | sealed 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
| Crate | Description |
|---|---|
| tensorbackend | Public 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. |
| core | Foundation 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
| Crate | Description |
|---|---|
| treetn | Tree tensor networks with arbitrary graph topology. Supports canonicalization, truncation, contraction, DMRG/TDVP, and the opt-in simplett-bridge migration feature. |
| itensorlike | ITensors.jl-inspired TensorTrain (tree-based) with orthogonality tracking and multiple canonical forms. |
| partitionedtreetn | TreeTN-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. |
| treersi | Experimental CPU Hadamard products on TreeTN via recursive sketched interpolation; requires independent accuracy checks. |
| treeaci | Experimental Alternating Cross Interpolation directly on TreeTN with any validated tree topology (no path-order requirement, unlike tensor4all-aci). |
| treetci | Tree TCI: cross interpolation on tree-structured tensor networks; TreeTciInterpolator implements the TreeInterpolator engine trait. |
Simplett stack
| Crate | Description |
|---|---|
| simplett | Lightweight positional tensor train (SimpleTensorTrain) for numerical computation. |
| tensorci | Tensor Cross Interpolation. Contains TCI2 (primary algorithm) and TCI1 (legacy). |
| quanticstci | High-level Quantics TCI. Interpolates functions on discrete or continuous grids in the quantics format. |
Quantics & transforms
| Crate | Description |
|---|---|
| quanticstransform | Constructs 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. |
| interpolativeqtt | Native TreeTN interpolative QTT construction on a coarse grid, returning ordered physical indices. See the interpolative-QTT tutorial. |
Applications
| Crate | Description |
|---|---|
| aci | Alternating Cross Interpolation (ACI) for elementwise tensor-train operations. |
I/O & bindings
| Crate | Description |
|---|---|
| hdf5 | HDF5 serialization compatible with ITensors.jl/ITensorMPS.jl file formats. |
| capi | C FFI for language bindings (Julia, C, C++). Out of scope for this guide; see Julia Bindings. |
| tensor4all-py | PyO3 bindings for Python (prototype). Not a workspace member; see its README.md. |
Which crate should I use?
| Goal | Recommended crate |
|---|---|
| TCI on a black-box function (high level) | tensor4all-quanticstci |
| TCI with fine-grained control | tensor4all-tensorci |
| Sketched Hadamard products of existing TreeTNs | tensor4all-treersi (experimental) |
| Tree TCI | tensor4all-treetci |
| Simple positional tensor train (create, evaluate, compress) | tensor4all-simplett (SimpleTensorTrain) |
| Tensor train with ITensors.jl-style interface | tensor4all-itensorlike (TensorTrain) |
| Tree tensor networks | tensor4all-treetn |
| Subdomain decomposition on named TreeTNs | tensor4all-partitionedtreetn |
| Adaptive patched interpolation of a function on a named tree | tensor4all-partitionedtreetn::adaptive_interpolation with an engine such as tensor4all-treetci::TreeTciInterpolator |
| Reconstruct orthogonal patches or tensor products with a global L2 tolerance | tensor4all-partitionedtreetn::reconstruction |
| Lazy patched Fourier transform on selected axes | tensor4all-quanticstransform with partitioned (see QFT guide) |
| Quantics transform operators | tensor4all-quanticstransform |
| HDF5 I/O compatible with Julia | tensor4all-hdf5 |
| Interpolative QTT on a coarse grid | tensor4all-interpolativeqtt |
| Elementwise TT ops via ACI | tensor4all-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.