t3toolbox 2026.0.0__tar.gz

t3toolbox-2026.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Alger and Blake Christierson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

t3toolbox-2026.0.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: t3toolbox
+Version: 2026.0.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
+decomposition whose central core is stored as a tensor train. 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)** — the two names refer to
+the same format. This library uses "Tucker tensor train" (and the abbreviation T3) throughout, but
+everything here applies equally if you know these objects as extended tensor trains.
+
+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`.
+- 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) 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).

t3toolbox-2026.0.0/README.md

@@ -0,0 +1,138 @@
+# 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
+decomposition whose central core is stored as a tensor train. 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)** — the two names refer to
+the same format. This library uses "Tucker tensor train" (and the abbreviation T3) throughout, but
+everything here applies equally if you know these objects as extended tensor trains.
+
+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`.
+- 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) 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).

t3toolbox-2026.0.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+# Only the library package ships. Without this, setuptools' flat-layout auto-discovery finds every
+# top-level directory that looks like a package (dev/, paper_experiments/, ...) and aborts with
+# "Multiple top-level packages discovered in a flat-layout". Restrict discovery to t3toolbox (+ its
+# subpackages, e.g. t3toolbox.backend); dev/, docs/, examples/, tests/, paper_experiments/ are not packaged.
+[tool.setuptools.packages.find]
+include = ["t3toolbox*"]
+
+[project]
+name = "t3toolbox"
+version = "2026.0.0"
+description = "Library for working with Tucker tensor trains (extended tensor trains)"
+requires-python = ">=3.9"
+# Floors = the tested compatibility floor (CI: numpy 1.x + jax 0.4.30 on py3.9; numpy 2.x + latest jax on py3.11)
+dependencies = [
+    "numpy>=1.22",
+]
+
+authors = [
+  {name = "Nick Alger", email = "nalger225@gmail.com"},
+  {name = "Blake Christierson", email="bechristierson@utexas.edu"},
+]
+maintainers = [
+  {name = "Nick Alger", email = "nalger225@gmail.com"}
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["Tucker tensor train", "extended tensor train", "ETT", "Tucker decomposition", "tensor train", "tensor"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Mathematics",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+
+[project.optional-dependencies]
+jax = ["jax>=0.4.30"]
+
+[project.urls]
+Homepage = "https://github.com/NickAlger/T3Toolbox"
+Documentation = "https://nickalger.github.io/T3Toolbox/"
+Repository = "https://github.com/NickAlger/T3Toolbox"
+"Bug Tracker" = "https://github.com/NickAlger/T3Toolbox/issues"
+Changelog = "https://github.com/NickAlger/T3Toolbox/blob/main/CHANGELOG.md"
+

t3toolbox-2026.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

t3toolbox-2026.0.0/t3toolbox/__init__.py

@@ -0,0 +1,76 @@
+# Authors: Nick Alger and Blake Christierson
+# Copyright: MIT License (2026)
+# Github: https://github.com/NickAlger/T3Toolbox
+# Documentation: https://nickalger.github.io/T3Toolbox/index.html
+"""T3Toolbox: Tucker tensor trains (T3) -- a Tucker decomposition whose central core is
+stored as a tensor train.
+
+This package root re-exports the **frontend** surface: the tensor classes (ragged and
+uniform), the frame/variations/tangent classes, the geometry singletons, the Gauss-Newton
+fitting models, and the optimizers. **Backend users import submodules explicitly** (e.g.
+``from t3toolbox.backend import probing``) -- the backend is namespaced by module and
+deliberately not re-exported here. Naming conventions: ``docs/naming_conventions.md``.
+"""
+from t3toolbox.tucker_tensor_train import TuckerTensorTrain
+from t3toolbox.uniform_tucker_tensor_train import UniformTuckerTensorTrain
+from t3toolbox.frame_variations_format import T3Frame, T3Variations, t3_orthogonal_representations
+from t3toolbox.uniform_frame_variations_format import UT3Frame, UT3Variations, ut3_orthogonal_representations
+from t3toolbox.manifold import T3Tangent, MANIFOLD, COREWISE
+from t3toolbox.uniform_manifold import UT3Tangent, UNIFORM_MANIFOLD, UNIFORM_COREWISE
+from t3toolbox.fitting import (
+    GaussNewtonModel,
+    UniformGaussNewtonModel,
+    apply_model,
+    entries_model,
+    probe_model,
+    apply_derivatives_model,
+    entries_derivatives_model,
+    probe_derivatives_model,
+)
+from t3toolbox.optimizers import gradient_descent, mc_sgd, adam, newton_cg
+from t3toolbox import safety
+from t3toolbox.safety import safe, unsafe
+
+try:
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version('t3toolbox')
+except Exception:  # not installed (e.g. PYTHONPATH use) -- keep in sync with pyproject.toml
+    __version__ = '2026.0.0'
+
+__all__ = [
+    # tensors
+    'TuckerTensorTrain',
+    'UniformTuckerTensorTrain',
+    # frames / variations / tangents
+    'T3Frame',
+    'T3Variations',
+    'T3Tangent',
+    'UT3Frame',
+    'UT3Variations',
+    'UT3Tangent',
+    't3_orthogonal_representations',
+    'ut3_orthogonal_representations',
+    # geometries
+    'MANIFOLD',
+    'COREWISE',
+    'UNIFORM_MANIFOLD',
+    'UNIFORM_COREWISE',
+    # fitting models
+    'GaussNewtonModel',
+    'UniformGaussNewtonModel',
+    'apply_model',
+    'entries_model',
+    'probe_model',
+    'apply_derivatives_model',
+    'entries_derivatives_model',
+    'probe_derivatives_model',
+    # optimizers
+    'gradient_descent',
+    'mc_sgd',
+    'adam',
+    'newton_cg',
+    # safety mode
+    'safety',
+    'safe',
+    'unsafe',
+]

t3toolbox-2026.0.0/t3toolbox/backend/__init__.py

@@ -0,0 +1,7 @@
+"""The pure-functional backend: stateless functions on raw core-tuple / supercore data.
+
+Deliberately empty: backend users import submodules explicitly (e.g.
+``from t3toolbox.backend import probing``) -- each module namespaces one
+(representation family) x (operation kind) cell, and each carries its own ``__all__``.
+See ``docs/naming_conventions.md`` for the family prefix grammar and the module map.
+"""