geometry#

Backend geometries on raw data – the where you optimize axis of a fit.

A geometry bundles the chart-level choices an optimizer needs and nothing else: the linearization frame, the gauge projection project (Pi), the retract, the coordinate inner, and the optional per-frame precompute companion. The frontend twins are t3toolbox.manifold.ManifoldGeometry / CorewiseGeometry and their uniform counterparts; these are the check-free versions a raw-.data user calls directly.

Parameters are fields, not closures. Each geometry is a frozen dataclass whose fields are its defining data – the mode shape, the rank masks it is fixed at, and the sharing groups. This matters for more than tidiness: a geometry rides as jax aux_data, so its __hash__/__eq__ are part of the jit compilation cache key. With the parameters sealed in closure cells (the previous GeometryOps record-of-lambdas) a rebuilt-but-identical geometry was always a new key, so every rank-continuation level and every rebuilt model recompiled. Value-based hash/eq over the fields (ValueHashedFields) makes the cache key reflect the geometry’s actual identity. Mathematically it is also the more faithful encoding: a uniform manifold at a given rank is a different manifold from one at another rank, so the rank belongs in the object’s data.

The math stays reachable. Per the backend rule, a method here only binds parameters and names a role – every line of actual math is also a standalone function, either in the operation modules (tv_operations, utv_operations, sharing) or named in this module (fv_base_point_tangent(), ufv_base_point_tangent(), t3_left_orthogonal_norm_sq(), t3_alias_tied_tucker_factors()).

Sharing is a field, not a wrapper. groups=() is the ordinary geometry; a non-empty partition restricts every projection to the TIED tangent subspace and keeps the retraction on the shared set (SF-T3; docs/sharing.md). One class, one code path. Build the canonical partition with validate_sharing(), or use the from_point / with_sharing constructors here.

Attributes#

canonical_groups

Classes#

ManifoldGeometryOps

The fixed-rank T3 manifold geometry on raw (tucker_cores, tt_cores) data -- the check-free twin

CorewiseGeometryOps

The core-parameter Euclidean geometry on raw (tucker_cores, tt_cores) data -- the check-free

UniformManifoldGeometryOps

The uniform manifold geometry at a fixed rank -- the raw-supercore twin of

UniformCorewiseGeometryOps

The uniform corewise geometry at a fixed rank -- the raw-supercore twin of

Functions#

t3_left_orthogonal_norm_sq(x_cores)

‖X‖²_HS = ‖last TT core‖² -- exact for a left-orthogonal T3 (the frame's (U,P) or a

fv_base_point_tangent(frame)

The attachment point X = (U, P) as a gauged tangent v_X -- the DIRECT construction: all

ufv_base_point_tangent(frame_data)

The uniform twin of fv_base_point_tangent(): the attachment point as a gauged tangent,

t3_alias_tied_tucker_factors(tucker_cores, groups)

Collapse each sharing group's Tucker factors to a single array object.

Module Contents#

canonical_groups#