Metadata-Version: 2.4
Name: t3toolbox
Version: 2026.1.0
Summary: Library for working with Tucker tensor trains (extended tensor trains)
Author-email: Nick Alger <nalger225@gmail.com>, Blake Christierson <bechristierson@utexas.edu>
Maintainer-email: Nick Alger <nalger225@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/NickAlger/T3Toolbox
Project-URL: Documentation, https://nickalger.github.io/T3Toolbox/
Project-URL: Repository, https://github.com/NickAlger/T3Toolbox
Project-URL: Bug Tracker, https://github.com/NickAlger/T3Toolbox/issues
Project-URL: Changelog, https://github.com/NickAlger/T3Toolbox/blob/main/CHANGELOG.md
Keywords: Tucker tensor train,extended tensor train,ETT,Tucker decomposition,tensor train,tensor
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Provides-Extra: jax
Requires-Dist: jax>=0.4.30; extra == "jax"
Dynamic: license-file

# T3Toolbox

[![tests](https://github.com/NickAlger/T3Toolbox/actions/workflows/tests.yaml/badge.svg)](https://github.com/NickAlger/T3Toolbox/actions/workflows/tests.yaml)
[![docs](https://github.com/NickAlger/T3Toolbox/actions/workflows/build-sphinx-docs.yaml/badge.svg)](https://github.com/NickAlger/T3Toolbox/actions/workflows/build-sphinx-docs.yaml)

A pure-Python (NumPy + optional JAX) library for **Tucker tensor trains (T3)**. A Tucker tensor train 
is a tensor network which consists of a Tucker decomposition composed with a tensor train 
decomposition of the central core. When the ranks are moderate, a T3 breaks the curse of dimensionality: 
storing a dense tensor costs O(N^d) memory, while the T3 representing it costs O(dnr^2 + dnN). 
Tucker tensor trains are also known as **extended tensor trains (ETT)**.

Tensor network diagram for a Tucker tensor train:

        r0        r1        r2       r(d-1)          rd
    1 ------ G0 ------ G1 ------ ... ------ G(d-1) ------ 1
             |         |                    |
             | n0      | n1                 | nd
             |         |                    |
             B0        B1                   Bd
             |         |                    |
             | N0      | N1                 | Nd
             |         |                    |

Here the Gi (TT cores) and Bi (Tucker cores) are small tensors contracted along the edges to form
a large dense N0 x ... x N(d-1) tensor. Unless stated otherwise, operations in this package are
defined with respect to the dense tensor that the T3 *represents*, even though that dense tensor
is never formed.

## Installation

The package is pure Python. Dependencies: [`numpy`](https://numpy.org/install/) (required),
[`jax`](https://docs.jax.dev/en/latest/installation.html) (optional).

	pip install t3toolbox

To include the optional JAX backend:

	pip install "t3toolbox[jax]"

From source (development install):

	git clone https://github.com/NickAlger/T3Toolbox.git
	cd T3Toolbox
	pip install -e .

## Quickstart

Create T3s and operate on the tensors they represent (arithmetic is dense-tensor arithmetic —
adding two T3s concatenates ranks; T3-SVD reduces back to minimal ranks):

```python
import numpy as np
import t3toolbox as t3t

np.random.seed(0)
x = t3t.TuckerTensorTrain.randn((10, 11, 12), (3, 4, 3), (1, 2, 2, 1))
y = t3t.TuckerTensorTrain.randn((10, 11, 12), (2, 2, 2), (1, 2, 2, 1))

z = x + y
print(z.tucker_ranks, z.tt_ranks)      # (5, 6, 5) (2, 4, 4, 2)   <- ranks add ...
np.linalg.norm(z.to_dense() - (x.to_dense() + y.to_dense()))  # ... tensors add: 0.0

z2, ss_tucker, ss_tt = z.t3svd()       # reduce to minimal ranks (lossless)
print(z2.tucker_ranks, z2.tt_ranks)    # (4, 6, 4) (1, 4, 4, 1)
```

Sample the represented tensor without forming it (`entries` / `apply` / `probe`, each also
available for tangent vectors and with symmetric-derivative generalizations):

```python
ww = [np.random.randn(N) for N in x.shape]
zz = x.probe(ww)                       # d vectors, one per mode (all but one mode contracted)
a  = x.apply(ww)                       # a scalar (all modes contracted)
e  = x.entries(np.array([3, 1, 2]))    # one entry
```

Fit a fixed-rank T3 to sampled measurements by Riemannian optimization (a zero start on the
manifold; unit-norm probe rows keep the least-squares well-conditioned):

```python
A  = t3t.TuckerTensorTrain.randn((6, 7, 8), (2, 2, 2), (1, 2, 2, 1))     # the unknown target
ww = [np.random.randn(120, N) for N in A.shape]
ww = [w / np.linalg.norm(w, axis=1, keepdims=True) for w in ww]          # unit-norm rows
b  = A.apply(ww)                                                         # 120 measurements

x0 = t3t.TuckerTensorTrain.zeros((6, 7, 8), (2, 2, 2), (1, 2, 2, 1))
x_fit, stats = t3t.newton_cg(t3t.MANIFOLD, 'apply', ww, b, x0, max_newton=30)
# relative error of the recovery: < 1e-6
```

Everything runs on NumPy or JAX — dispatch is inferred from the input array types, frontend
objects are jax pytrees (`jax.jit` applies to them directly), and passing a
`UniformTuckerTensorTrain` start runs the same fitting calls fully packed and jit-compile-once on
the uniform layer. See [Getting started](https://nickalger.github.io/T3Toolbox/getting_started.html)
for the full tour with verified outputs.

## Included functionality

- The **T3 format**: arithmetic with dense-tensor semantics, orthogonalization, minimal ranks,
  **T3-SVD** (truncation / minimal-rank reduction), save/load, batching (`stack_shape`) on every
  operation.
- The three **sampling operations** — `entries`, `apply`, `probe` — evaluating the represented
  tensor without forming it, plus their **symmetric directional derivatives** (jets) and the
  ambient/corewise/tangent **transposes**.
- The **fixed-rank T3 manifold**: orthogonal frame + gauged variations (`T3Frame`,
  `T3Variations`, `T3Tangent`), gauge projections, retraction, and two geometries — the
  Hilbert-Schmidt `MANIFOLD` and the Euclidean-coordinate `COREWISE`.
- **Least-squares fitting** from any of the sampling operations or their derivatives
  (Gauss-Newton models) with four optimizers: `gradient_descent`, `mc_sgd`, `adam`, `newton_cg` —
  with optional residual weighting, Tikhonov regularization, live Newton-CG diagnostics, and
  rank continuation.
- **Shared Tucker factors (SF-T3)**: optimize over T3s whose Tucker factors are constrained equal
  within user-specified groups of modes — `shared(MANIFOLD, sharing)` wraps any geometry, and the
  grouped T3-SVD, rank bookkeeping and continuation follow.
- **Edge weighting**: diagonal weights on a T3's internal edges (`T3Weights`) and on a tangent's
  coordinates (`T3FrameWeights`, the Grasedyck-Kramer preconditioner), with `absorb` into cores.
- The **uniform layer**: zero-padded supercores + boolean rank masks mirroring the whole stack —
  same results, uniform shapes — for `jax.lax.scan` vectorization, GPU efficiency, and
  compile-once `jit` (optimizers included).
- **NumPy / JAX** backends with dispatch inferred from the input arrays; frontend classes are
  registered jax pytrees.
- **Safe mode**: numerical preconditions (same tangent space, orthogonal frame, gauged
  variations, tied factors) checked by default, skippable for speed (`t3toolbox.unsafe()`);
  structural problems always error.

## Documentation

https://nickalger.github.io/T3Toolbox/ — [getting started](https://nickalger.github.io/T3Toolbox/getting_started.html),
[user guide](https://nickalger.github.io/T3Toolbox/user_guide.html),
[design notes](https://nickalger.github.io/T3Toolbox/design_notes.html), and the full
[API reference](https://nickalger.github.io/T3Toolbox/api_reference.html) (frontend **and**
backend — the backend is a first-class, fully documented surface). Worked end-to-end fitting
examples live in [`examples/`](examples/). Contributing? Start with the
[Contributor guide](https://nickalger.github.io/T3Toolbox/contributor_guide.html).

## Authors

* Nick Alger (nalger225@gmail.com)
* Blake Christierson (bechristierson@utexas.edu)

MIT License. The algorithms are described in *Alger, Christierson, Chen & Ghattas (2026), "Tucker
Tensor Train Taylor Series"*, [arXiv:2603.21141](https://arxiv.org/abs/2603.21141).
