SharedGeometry#

class t3toolbox.shared_geometry.SharedGeometry(base, sharing)#

The shared (SF-T3) geometry: a base geometry restricted to tied Tucker factors.

Construct via shared() / shared_manifold() / shared_corewise(). The wrapper is stateless up to its static (base, sharing) identity (value-based __eq__/__hash__, so it is a stable jit aux); the per-frame companion (SharedFrameData) is DERIVED from a frame on demand – pass it explicitly (shared_data=) to amortize across calls at one frame, as the fitting models do via precompute().

On a MANIFOLD base the full surface is available (frame/project/project_oblique/ inner/norm/retract/project_ambient/transport/randn); on a COREWISE base the surface matches the base (no ambient projection / transport). Safe mode enforces the base geometry’s preconditions plus tied factors at frame/retract/transport entry. Full shared rank is deliberately NOT a precondition – zero-padded continuation restarts sit on the lower-shared-rank stratum by construction, and the tied projection’s clipped solve is well-defined (minimum-norm) there.

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> import t3toolbox.manifold as t3m
>>> import t3toolbox.shared_geometry as sg
>>> np.random.seed(0)
>>> x = t3.TuckerTensorTrain.randn((6, 6, 5), (3, 3, 2), (1, 2, 2, 1)).share((0, 0, 1))
>>> geom = sg.shared_manifold((0, 0, 1))
>>> frame = geom.frame(x)                       # safe-mode tied check + orthonormal frame
>>> v = geom.randn(frame)                       # a standard Gaussian on the TIED tangent space
>>> print(v.is_gauged())
True
>>> y = geom.retract(v)                         # grouped retraction: stays exactly tied
>>> print(y.data[0][0] is y.data[0][1])
True
>>> y0 = geom.retract(t3m.T3Tangent.zeros(frame))
>>> print(bool(np.allclose(y0.to_dense(), x.to_dense())))   # retract(0) == the base point
True
Parameters:

sharing (t3toolbox.backend.common.typ.Sequence)

base#
sharing#
property base_name: str#
Return type:

str

property is_uniform: bool#

True when the base is a uniform geometry singleton (points/tangents are uniform objects).

Return type:

bool

Methods#

__eq__(other)

__hash__()

__repr__()

groups(shape)

The canonical partition for a given mode-size tuple (validates the spec).

frame(x)

The base geometry's frame at x (ragged TuckerTensorTrain -> T3Frame;

shared_frame_data(frame)

The per-frame companion (centers + the stacked-S SVD), derived from frame

precompute(frame)

The fitting models' once-per-frame hook: the companion (manifold bases) or None

project(v[, shared_data])

The tied projection Pi_sh: orthogonal projection onto the TIED tangent subspace

project_oblique(v)

The base geometry's vector-preserving gauge fix (manifold bases only). Note it does

inner(t1, t2)

The base geometry's inner product -- the tied subspace is linear, so the restricted

norm(t)

The base geometry's norm (see inner()).

randn(frame[, stack_shape])

A standard Gaussian on the TIED tangent space: the base draw, tied-projected.

randn_like(tangent)

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

retract(p[, shared_data])

The shared retraction: stays on the shared set exactly (one factor array per group;

project_ambient(frame, grad[, method, shared_data])

Project an ambient gradient onto the TIED tangent space (manifold bases only). The

transport(v, new_frame[, shared_data])

Projective transport onto the TIED tangent space at new_frame (manifold bases