Skip to content

tensor4all/tensor4all-rs

BranchesTags

Repository files navigation

tensor4all-rs

CI

A Rust implementation of tensor networks for AI-agentic development — rapid, AI-assisted development with fast trial-and-error cycles.

Design Philosophy

AI-Agentic Development Optimized: tensor4all-rs is designed for rapid prototyping with AI agents and code generation:

  • Modular architecture: Independent crates with unified core (tensor4all-core) enable fast compilation and isolated testing
  • ITensors.jl-like dynamic structure: Flexible Index system and dynamic-rank tensors preserve the intuitive API
  • Static error detection: Rust's type system catches errors at compile time while maintaining runtime flexibility
  • Multi-language support via C-API: Full functionality exposed through C-API; initial targets are Julia and Python

Scope: Initial focus on QTT (Quantics Tensor Train) and TCI (Tensor Cross Interpolation). The design is extensible to support Abelian and non-Abelian symmetries in the future.

Dense Layout Semantics

tensor4all-rs uses column-major dense linearization internally. Flat dense buffers, reshape/flatten semantics, the C API, the Python bindings, and the ITensors.jl-compatible HDF5 layer are all defined in terms of column-major ordering.

This matches Julia, ITensors.jl, and tenferro-rs. When exchanging dense data with NumPy, use order="F" semantics when you need explicit control over flattening or reshaping.

Type Correspondence

ITensors.jl QSpace v4 tensor4all-rs
Index{Int} — Index<Id, NoSymmSpace>
Index{QNBlocks} QIDX Index<Id, QNSpace> (future)
ITensor QSpace TensorDynLen
Dense DATA Storage::StructuredF64/C64
Diag — Storage::StructuredF64/C64 with diagonal axis_classes
A * B — a.contract(&b)

Legacy dense/diagonal kernel variants still exist inside the backend during the transition, but StructuredStorage is the intended public snapshot direction.

Truncation Tolerance

Library Parameter Conversion
tensor4all-rs rtol —
ITensors.jl cutoff rtol = √cutoff

Solve-Bug Entrypoints

Use bash ai/run-codex-solve-bug.sh or bash ai/run-claude-solve-bug.sh when you want a headless agent to pick one actionable bug or bug-like issue, fix it, and drive the repository-local PR workflow.

If there are effectively no open bug or bug-like issues, the workflow should terminate cleanly with no code changes and no PR creation.

Project Structure

tensor4all-rs/
├── crates/
│   ├── tensor4all-tensorbackend/     # Scalar types, storage backends
│   ├── tensor4all-core/              # Core: Index, Tensor, TensorLike trait, SVD, QR
│   ├── tensor4all-treetn/            # Tree Tensor Networks with arbitrary topology
│   ├── tensor4all-itensorlike/       # ITensorMPS.jl-like TensorTrain API
│   ├── tensor4all-simplett/          # Simple TT/MPS implementation
│   ├── tensor4all-tensorci/          # Tensor Cross Interpolation
│   ├── tensor4all-quanticstci/       # High-level Quantics TCI (QuanticsTCI.jl port)
│   ├── tensor4all-quanticstransform/ # Quantics transformation operators
│   ├── tensor4all-partitionedtt/     # Partitioned Tensor Train
│   ├── tensor4all-hdf5/              # ITensors.jl-compatible HDF5 serialization
│   ├── tensor4all-hdf5-ffi/          # HDF5 FFI with runtime loading support
│   ├── tensor4all-capi/              # C API for language bindings
│   ├── matrixci/                     # Matrix Cross Interpolation (internal)
│   └── quanticsgrids/                # Quantics grid structures (internal)
├── python/tensor4all/                # Python bindings
├── tools/api-dump/                   # API documentation generator
├── xtask/                            # Development task runner
└── docs/                             # Design documents

Crate Documentation

Crate Description
tensor4all-tensorbackend Scalar types (f64, Complex64) and storage backends
tensor4all-core Core types: Index, Tensor, TensorLike trait, SVD, QR, LU
tensor4all-treetn Tree tensor networks with arbitrary topology
tensor4all-itensorlike ITensorMPS.jl-like TensorTrain API
tensor4all-simplett Simple TT/MPS with multiple canonical forms
tensor4all-tensorci Tensor Cross Interpolation (TCI) algorithms
tensor4all-quanticstci High-level Quantics TCI interface
tensor4all-quanticstransform Quantics transformation operators
tensor4all-partitionedtt Partitioned Tensor Train
tensor4all-hdf5 ITensors.jl-compatible HDF5 serialization
tensor4all-hdf5-ffi HDF5 FFI with build-time linking and runtime loading
tensor4all-capi C FFI for language bindings
matrixci Matrix Cross Interpolation
quanticsgrids Quantics grid structures

Usage Example (Rust)

Simple Tensor Train (MPS)

use tensor4all_simplett::{AbstractTensorTrain, CompressionOptions, TensorTrain};

// Create a constant tensor train with local dimensions [2, 3, 4]
let tt = TensorTrain::<f64>::constant(&[2, 3, 4], 1.0);

// Evaluate at a specific multi-index
let value = tt.evaluate(&[0, 1, 2])?;

// Compute sum over all indices
let total = tt.sum();

// Compress with tolerance (rtol=1e-10, max bond dim = 20)
let options = CompressionOptions {
    tolerance: 1e-10,
    max_bond_dim: 20,
    ..Default::default()
};
let compressed = tt.compressed(&options)?;

Tensor Cross Interpolation (TCI)

use tensor4all_tensorci::{crossinterpolate2, TCI2Options};

// Define a function to interpolate
let f = |idx: &Vec<usize>| -> f64 {
    ((1 + idx[0]) * (1 + idx[1]) * (1 + idx[2])) as f64
};

// Perform cross interpolation
let local_dims = vec![4, 4, 4];
let initial_pivots = vec![vec![0, 0, 0]];
let options = TCI2Options { tolerance: 1e-10, ..Default::default() };

let (tci, ranks, errors) = crossinterpolate2::<f64, _, fn(&[Vec<usize>]) -> Vec<f64>>(
    f, None, local_dims, initial_pivots, options
)?;

// Convert to tensor train
let tt = tci.to_tensor_train()?;
println!("Rank: {}, Final error: {:.2e}", tci.rank(), errors.last().unwrap());

Language Bindings

Binding documentation in this repo is built as an mdBook (docs/book/). Code blocks in the book are included from standalone scripts under docs/examples/ and are executed in CI.

Julia

Julia bindings are maintained in a separate repository: Tensor4all.jl

using Pkg
Pkg.add(url="https://github.com/tensor4all/Tensor4all.jl")

See the Tensor4all.jl README for detailed installation and usage instructions.

Python

Note: Python bindings require a Rust toolchain. Install from https://rustup.rs/.

Install from GitHub

uv pip install "tensor4all @ git+https://github.com/tensor4all/tensor4all-rs#subdirectory=python/tensor4all"

Development install

cd python/tensor4all
python scripts/build_capi.py   # Build the Rust C library
uv pip install -e .

After Rust code changes, re-run python scripts/build_capi.py.

Quick example

from tensor4all import crossinterpolate2

def f(i, j, k):
    return float((1 + i) * (1 + j) * (1 + k))

tt, err = crossinterpolate2(f, [4, 4, 4], tolerance=1e-10)
print(tt(0, 0, 0))  # 1.0

Available modules

Module Description
tensor4all.treetn Tree tensor networks (MPS, MPO, TTN)
tensor4all.tensorci Tensor cross interpolation
tensor4all.quanticsgrids Quantics grid representations
tensor4all.quanticstci Quantics TCI for function interpolation
tensor4all.quanticstransform Quantics operators (shift, flip, Fourier)
tensor4all.simplett Simple tensor trains

Executable documentation examples

All Python documentation examples live in docs/examples/python/ and are executed from the repo root:

cd python/tensor4all
python scripts/build_capi.py
uv pip install -e .
cd ../..
for f in docs/examples/python/*.py; do
  python "$f"
done

CI runs these examples as part of ./scripts/run_python_tests.sh.

Future Extensions

  • GPU acceleration via PyTorch backend (tch-rs)
  • In-place operations for memory efficiency
  • Optimization for block-sparse tensors
  • Automatic differentiation
  • Quantum number symmetries (Abelian: U(1), Z_n)
  • Non-Abelian symmetries (SU(2), SU(N))

Acknowledgments

This implementation is inspired by ITensors.jl (https://github.com/ITensor/ITensors.jl). We have borrowed API design concepts for compatibility, but the implementation is independently written in Rust.

We acknowledge many fruitful discussions with M. Fishman and E. M. Stoudenmire at the Center for Computational Quantum Physics (CCQ), Flatiron Institute. H. Shinaoka visited CCQ during his sabbatical (November–December 2025), which greatly contributed to this project.

Citation: If you use this code in research, please cite:

We used tensor4all-rs (https://github.com/tensor4all/tensor4all-rs), inspired by ITensors.jl.

For ITensors.jl:

M. Fishman, S. R. White, E. M. Stoudenmire, "The ITensor Software Library for Tensor Network Calculations", arXiv:2007.14822 (2020)

TODO / Known Issues

Naming Convention

  • Tolerance parameters: Standardize on rtol (relative tolerance) and atol (absolute tolerance)
    • Current inconsistency: cutoff, tolerance, rtol used interchangeably
    • cutoff (ITensors.jl style) should only appear in compatibility layers
    • Conversion: rtol = √cutoff

Incomplete Implementations

  • MPO canonical forms: VidalMPO and InverseMPO conversions not yet implemented
  • C API t4a_treetn_evaluate: TreeTN evaluate function not yet exposed in C API

Development

Development Tasks (xtask)

This project uses cargo xtask for common development tasks:

# Generate documentation with custom index page
cargo xtask doc

# Generate and open documentation in browser
cargo xtask doc --open

# Run all CI checks (fmt, clippy, test, doc)
cargo xtask ci

Pre-commit Checks

Before committing changes, ensure that both formatting and linting pass:

# Check code formatting
cargo fmt --all -- --check

# Run clippy with all warnings as errors
cargo clippy --workspace --all-targets -- -D warnings

If either command fails, fix the issues before committing:

# Auto-fix formatting
cargo fmt --all

# Fix clippy warnings (some may require manual fixes)
cargo clippy --workspace --all-targets -- -D warnings

These checks are also enforced in CI, so ensuring they pass locally will prevent CI failures.

Documentation

  • Index System Design — Overview of the index system, QSpace compatibility, and IndexLike/TensorLike design
  • AI-Agentic Development Workflow — Development workflow guidelines for rapid, AI-assisted development
  • mdBook user guide: mdbook build docs/book (output: docs/book/book/)

References

  • ITensors.jl — M. Fishman, S. R. White, E. M. Stoudenmire, arXiv:2007.14822 (2020)
  • QSpace v4 — A. Weichselbaum, Annals of Physics 327, 2972 (2012)

License

MIT License (see LICENSE-MIT)

About

Rust port of tensor4all tensor network ecosystem with C-API

tensor4all.org/tensor4all-rs/

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

22 stars

Watchers

0 watching

Forks

4 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages