The stack for tensor network users

The typical workflow

Most QTT work follows the same four steps, and each step has a home crate.

1. Describe a grid. Map continuous variables to binary digits with a DiscretizedGrid (from quanticsgrids-rs, re-exported by tensor4all-quanticstci), choosing bounds, resolution and how variables are interleaved.
2. Learn a QTT from a function. Run quantics TCI on your function with tensor4all-quanticstci. The function is sampled in batches, so it can be an expensive solver call. The result can be evaluated, summed and integrated.
3. Transform it. Apply QTT operators from tensor4all-quanticstransform: Fourier transform, shift, flip, phase rotation, cumulative sum and affine coordinate maps, with multivariable variants.
4. Contract and compress. Multiply, contract and truncate with tensor4all-treetn (zip-up, variational fit, randomized SRC), or with tensor4all-simplett for plain tensor trains. Elementwise products of QTTs use tensor4all-aci. Save results in an ITensors.jl compatible HDF5 file with tensor4all-hdf5.

Coming from Julia

tensor4all-rs started as a port of the tensor4all Julia ecosystem, so most packages have a direct counterpart. Names follow the Julia ones where it made sense, but the APIs are Rust APIs, not transliterations.

Which crate to use

Two stacks and the bridge

tensor4all-rs deliberately contains two families of crates.

• The TT and TCI stack (simplett, tensorci, quanticstci, quanticstransform) works with tensor trains as arrays indexed by position. It is close to the Julia TCI packages and is the fastest path from a function to a QTT.
• The network stack (core, itensorlike, treetn, treetci, partitionedtreetn) works with named indices and arbitrary tree topologies. A chain is just a tree shaped like a path, so MPS and MPO algorithms live here too.

They coexist on purpose. Converting between them is the job of a single bridge in tensor4all-treetn: tensor_train_to_treetn and treetn_to_tensor_train (with variants that set node names and site indices). A common pattern is to learn a QTT with quantics TCI, move it to the network stack, then apply operators and contract there.

Getting started

The crates are not on crates.io yet. Add them as git dependencies; pin a revision with rev = "..." for reproducible runs.

[dependencies]
tensor4all-simplett = { git = "https://github.com/tensor4all/tensor4all-rs", package = "tensor4all-simplett" }
tensor4all-quanticstci = { git = "https://github.com/tensor4all/tensor4all-rs", package = "tensor4all-quanticstci" }

A tensor train, from the README (checked in CI):

use tensor4all_simplett::prelude::*;

let tt = SimpleTensorTrain::<f64>::constant(&[2, 3, 4], 1.0);
assert!((tt.evaluate(&[0, 1, 2]).unwrap() - 1.0).abs() < 1e-12);
assert!((tt.sum() - 24.0).abs() < 1e-12);

Quantics TCI of x² on [0, 1] with 2⁴ points, from the crate documentation (a doctest):

use tensor4all_quanticstci::{
    quanticscrossinterpolate_batch, DiscretizedGrid, QtciOptions, QuanticsBatch,
};

let grid = DiscretizedGrid::builder(&[4])
    .with_lower_bound(&[0.0])
    .with_upper_bound(&[1.0])
    .build()
    .unwrap();
let f = |batch: QuanticsBatch<'_, f64>| -> anyhow::Result<Vec<f64>> {
    Ok((0..batch.n_points())
        .map(|point| batch.get(0, point).unwrap().powi(2))
        .collect())
};
let (qtci, _ranks, _errors) =
    quanticscrossinterpolate_batch(&grid, f, None, QtciOptions::default()).unwrap();
let integral = qtci.integral().unwrap();

For longer runnable examples (operators, tree networks, patching, GPU contraction), go to the tensor4all-rs user guide and the API reference.

Other entry points

• Julia: Tensor4all.jl (best effort, see above). Its build step compiles tensor4all-rs for you.
• C: tensor4all-capi exposes indices, tensors, tree tensor networks and quantics materialization through a small FFI surface.
• Python: tensor4all-py is an early PyO3 prototype forwarding to the core, tree network, tree TCI and quantics TCI crates.

What runs underneath

You rarely need to look below tensor4all-rs, but knowing the shape helps when reading performance numbers or error messages.

• Every dense operation (contraction, SVD, QR) goes through tenferro-rs, reached through one adapter crate, tensor4all-tensorbackend. tenferro chooses CPU or GPU kernels and provides automatic differentiation.
• On the CPU, tenferro hands contractions to tcontract and factorizations to tlinalg (pure Rust, using tensor4all's fork of faer) or optionally to a vendor LAPACK.
• There is no hidden global thread pool. Parallelism comes from an execution context that the caller creates (in tensor4all-rs, a CpuExecutionContext) and that is reused across calls. If you construct a new context in a tight loop, you throw away its buffers.
• CUDA contraction of dense tree networks exists as an experimental path with explicit upload and download; see the CUDA tutorial.

The backend guide explains these layers in detail.

Parallel runs with hataori

Many tensor network studies are embarrassingly parallel at the outer level: a parameter scan, a set of momenta, independent patches. hataori provides map and a dynamically scheduled pmap (in the spirit of Distributed.jl) over serial, Rayon, MPI and hybrid MPI plus threads execution. Its MPI support can load the MPI library at run time, so the same binary can share the MPI installation used by MPI.jl or mpi4py.

hataori owns the processes and threads, and lends them to each task through the same explicit contexts described above, so outer and inner parallelism do not fight over cores. Adapters for tenferro and tensor4all exist in the hataori repository. The synchronous map and pmap are usable today; the asynchronous runtime is still under development.

Maturity and help

• Stable enough to build on: TT and TCI, quantics TCI, quantics operators, tree network contraction and compression. APIs can still change between revisions, so pin one.
• Experimental: tree ACI and RSI, CUDA contraction, the Python bindings.
• Deprecated: tensor4all-partitionedtt; use tensor4all-partitionedtreetn.

Using a coding agent? Install the tensor4all-rs agent skill, which teaches it the crate map and conventions:

npx skills add tensor4all/tensor4all-rs --skill use-tensor4all-rs -g

A machine oriented index of the documentation is in llms.txt. Questions and bug reports go to the tensor4all-rs issue tracker. If you publish results, please read the citation policy, which asks you to cite the algorithm papers your work relies on.