UT3Tangent

class t3toolbox.uniform_manifold.UT3Tangent

Tangent vector to the uniform manifold of fixed-rank Tucker tensor trains (uniform analog of T3Tangent).

A UT3Tangent bundles a UT3Frame (the frame at the base point where the tangent space is attached) with a UT3Variations (the tangent direction in that frame). The K/C stack split (extra tangent stack K over the shared frame stack C) is inferred from the pair – the variation stack is K + C and the frame stack is C – never stored (the split-agnostic stacking of increment 2c).

Like the ragged class, the metric lives on the geometry, not here; this exposes only the raw coordinate corewise_inner() / corewise_norm() (no Hilbert-Schmidt claim), computed on the real (masked) content of the variations.

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> import t3toolbox.uniform_tucker_tensor_train as ut3
>>> import t3toolbox.uniform_frame_variations_format as ubv
>>> import t3toolbox.uniform_manifold as ut3m
>>> np.random.seed(0)
>>> x = t3.TuckerTensorTrain.randn((10, 11, 12), (3, 4, 3), (1, 2, 2, 1))
>>> frame, variations = ubv.ut3_orthogonal_representations(ut3.UniformTuckerTensorTrain.from_t3(x))
>>> v = ut3m.UT3Tangent(frame, variations)
>>> print(v.shape, v.stack_shape)
(10, 11, 12) ()
>>> print(bool(v.is_orthogonal()))   # frame from ut3_orthogonal_representations is orthogonal
True
>>> w = 2.0 * v - v                  # linear algebra stays in the same tangent space
>>> print(bool(w.allclose(v)))       # (2v - v) == v
True

frame: UT3Frame

variations: UT3Variations

__rmul__

Methods

__post_init__()
validate()	Validate this tangent: both components well-formed and a compatible (frame, variations) pair.
__repr__()
d()
shape()
frame_stack_shape()	Frame stack C: the batch of base points, shared with the frame (frame.stack_shape).
tangent_stack_shape()	Tangent stack K: the extra outer batch of tangent vectors sharing this frame.
stack_shape()	Full stack K + C (tangent_stack_shape + frame_stack_shape), outer-to-inner.
structure()	The frame's per-element structure tuple (ranks are arrays over the frame stack C).
data()
to_jax()	Copy with frame and variation supercores converted to jax arrays (masks stay host numpy).
to_numpy()	Copy with frame and variation supercores converted to numpy arrays.
copy()	Deep copy (copies the frame and variation supercores).
contains_jax()	True if any frame or variation supercore is a jax array.
__add__(other)	Add tangent vectors. Requires the same frame + matching stack/masks (same tangent space).
__sub__(other)	Subtract tangent vectors. Requires the same frame + matching stack/masks.
__mul__(scalar)	Scale a tangent vector by a scalar (the base point is unchanged).
__neg__()
corewise_inner(other)	The raw corewise (coordinate) dot of two tangents' variations -- not the HS inner product.
corewise_norm()	The raw corewise (coordinate) norm of the variations (masked content) -- not the HS norm.
absorb_weights(weights)	Absorb the metric weights into this tangent's variation supercores (down->V,
weighted_norm(weights)	The weighted (Grasedyck-Kramer) coordinate norm: absorb the metric into the variation
weighted_inner(other, weights)	The weighted coordinate inner product <absorb(W, self), absorb(W, other)> w.r.t. one
normalized()	Unit-norm rescaling self / self.corewise_norm(), vectorized over the stack (each stacked
allclose(other[, rtol, atol])	True (per stack element) if other is the same tangent vector as self at the same frame.
minimal_ranks()	Structural minimal ranks of this tangent's base point, per frame-stack element (the ranks
tangent_space_dimension()	Dimension of the tangent space at this base point (= the fixed-rank manifold dimension),
has_minimal_ranks()	True (per frame-stack element) if this tangent's frame has structurally minimal ranks. See
has_numerically_minimal_ranks([atol])	True (per frame-stack element) if this tangent's frame is numerically minimal. See
is_orthogonal([atol])	True (per frame-stack element) if this tangent's frame is orthogonal. See
gauge_residual()	Max absolute gauge-condition violation, per stack element (shape = variation stack K+C;
is_gauged([atol])	True (per stack element) if the variations are gauged w.r.t. the frame.
to_ut3([include_shift])	Doubled-rank UniformTuckerTensorTrain representation of this tangent vector.
to_dense([include_shift])	Form the dense tensor represented by this tangent vector (= to_ut3(...).to_dense()).
to_t3tangent()	Convert to a ragged T3Tangent (the cross-layer converter; uniform
from_t3tangent(tangent[, N, nU, nD, rL, rR])	Pack a ragged T3Tangent into a uniform one (inverse of
reverse()	Reverse the mode order of this tangent (reverses both the frame and the variations).
probe(ww)	Probe this tangent vector: the single-sample Riemannian Jacobian 𝒥 (contract all-but-one
apply(ww)	Apply this tangent vector in all modes (the all-modes special case of probe(); a scalar
entries(index)	Entries of the dense tangent at index (= apply() with unit vectors, by fiber
probe_derivatives(ww, pp, order)	Symmetric directional derivatives of probe(), in one repeated direction P (pp):
apply_derivatives(ww, pp, order)	Symmetric all-modes apply derivatives (derivative twin of apply(); the bare 𝒥, a
entries_derivatives(index, pp, order)	Symmetric entry derivatives at index in direction P (derivative twin of entries();
probe_transpose(ztildes, ww, frame[, sum_over_probes])	Apply the transpose 𝒥ᵀ of the probe map to residuals; returns a UT3Tangent at
apply_transpose(c, ww, frame[, sum_over_probes])	Apply the transpose 𝒥ᵀ of apply() -- back-project a residual c into a tangent
entries_transpose(c, index, frame[, sum_over_probes])	Apply the transpose 𝒥ᵀ of entries() -- scatter c at index into a tangent at
probe_derivatives_transpose(ztildes, ww, pp, frame, order)	Transpose 𝒥ᵀ of probe_derivatives(): back-project residual jets into a
apply_derivatives_transpose(c, ww, pp, frame, order[, ...])	Transpose 𝒥ᵀ of apply_derivatives() (the adjoint-state apply-derivative transpose).
entries_derivatives_transpose(c, index, pp, frame, order)	Transpose 𝒥ᵀ of entries_derivatives(): scatter residual jets c at index into a
sum_tangents([axis])	Sum over the tangent stack K (a batch of tangents at the shared frame) into one tangent.
zeros(frame[, stack_shape])	Zero tangent vector at a given frame (numpy/jax matching the frame).
unit(frame, index)	Canonical unit tangent at frame: variations zero except a single core entry.
zeros_like(tangent)	Zero tangent at tangent's frame, with tangent's tangent stack K.
unstack_tangents()	Unstack over the tangent stack K: a K-shaped tree of tangents sharing this frame.
unstack_frame()	Unstack over the frame stack C: a C-shaped tree of single-base-point tangents.
stack_tangents(tree)	Stack a K-shaped tree of tangents (sharing one frame) into a tangent-stacked UT3Tangent.
stack_frame(tree)	Stack a C-shaped tree of single-base-point tangents into a frame-stacked UT3Tangent.