ManifoldGeometry#

class t3toolbox.manifold.ManifoldGeometry#

The Riemannian geometry of the fixed-rank Tucker tensor train manifold M.

Optimization happens on M: tangents live in T_xM with an orthonormal, gauged frame, the metric is Hilbert-Schmidt, and one moves by the manifold retraction (truncate the shifted doubled-rank embedding back to the frame ranks). A geometry is a stateless bundle of the three chart-level choices that distinguish this from the over-parametrized corewise geometry – the frame (frame()), the gauge projection Pi (project()), and the retraction (retract()) – plus the manifold-only ambient projection and transport. The point lives in the caller (or the fitting model), not the geometry; use the module singleton MANIFOLD.

See Section 6 and Appendix A.3 of Alger et al. (2026), “Tucker Tensor Train Taylor Series” (arXiv:2603.21141). The corewise counterpart is CorewiseGeometry.

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> import t3toolbox.manifold as t3m
>>> np.random.seed(0)
>>> x = t3.TuckerTensorTrain.randn((10, 11, 12), (3, 4, 3), (1, 2, 2, 1))
>>> frame = t3m.MANIFOLD.frame(x)            # orthonormal frame at x
>>> print(frame.is_orthogonal())
True
>>> v = t3m.MANIFOLD.randn(frame)           # a standard Gaussian on T_xM (gauged)
>>> print(v.is_gauged())
True
>>> y = t3m.MANIFOLD.retract(t3m.T3Tangent.zeros(frame))   # retract the zero tangent == the base point
>>> print(bool(np.allclose(y.to_dense(), x.to_dense())))
True

Methods#

frame(x)

The orthonormal frame at x (the left/right/outer-orthogonal representation).

randn(frame[, stack_shape])

Random tangent at frame: a standard Gaussian on the tangent space T_xM.

random_orthogonal(shape, tucker_ranks, tt_ranks[, ...])

A gauged random tangent at a random orthogonal base point (random direction, random frame).

randn_like(tangent)

A gauged random tangent at tangent's frame, with tangent's tangent stack K.

project(v)

The gauge projection Pi: raw cotangent -> Riemannian gradient (orthogonal gauge).

project_oblique(v)

Gauge v's variations while preserving the represented tangent vector (oblique projection).

inner(t1, t2)

The Hilbert-Schmidt inner product of two tangents -- the Riemannian metric on M.

norm(t)

The Hilbert-Schmidt norm of a tangent. Safe mode checks the frame orthogonal + variations

retract(p)

Retract the step p to the manifold: shifted doubled-rank embedding, truncated to frame ranks.

project_ambient(frame, grad[, method])

Project an ambient gradient onto T_xM -- the Riemannian gradient.

transport(v, new_frame)

Projective vector transport of v to the tangent space at new_frame.