utv_operations#

Stateless tangent-stack reshuffles for the uniform tangent layer (UT3Tangent), uniform-fix 3b-1b.

The uniform mirror of the ragged tv_operations stack/unstack helpers, for the .data layout (*supercores, shape, masks) with a leading mode index d and the stack at axes 1 ... A uniform tangent’s variations carry the full K + C stack (tangent stack K outermost, frame stack C inner); the frame carries only C. These functions split that stack into a Python tree of per-element objects and recombine – a tree<->array conversion, NOT an axis permutation of the supercores. They are the backend the UT3Tangent unstack_tangents / unstack_frame / stack_tangents / stack_frame / sum_tangents methods delegate to.

Varying ranks across the frame C stack are first-class here (the rank-sweep use case): the per-element masks may differ, and utv_stack_frame_stack stacks frames of different ranks into one batch (the masks just ride along). Uniform rank is required only across K (one shared frame = one tangent space), which utv_stack_tangent_stack gets for free (the leaves share a frame). See docs/uniform_ranks_and_varieties.md.

Functions#

utv_unstack_tangent_stack(frame_data, variations_data)

Peel the tangent stack K off the variations, returning a K-shaped tree of variation-.data.

utv_stack_tangent_stack(variations_tree)

Stack a K-shaped tree of variation-.data over the tangent stack K (outermost; C stays

utv_unstack_frame_stack(frame_data, variations_data)

Peel the frame stack C off both the frame and the variations, returning a C-shaped tree whose

utv_stack_frame_stack(paired_tree)

Stack a C-shaped tree of (frame_data, variations_data) pairs over the frame stack C.

utv_sum_tangent_stack(variations_data, n_tangent[, axis])

Sum the variations over the tangent stack K (a batch of tangents at one frame -> their sum;

utv_to_ut3(frame_data, variations_data[, include_shift])

Doubled-rank uniform Tucker tensor train representing a uniform frame-variations tangent vector.

utv_retract(frame_data, variations_data)

Retract a uniform frame-variations tangent vector onto the fixed-rank manifold.

utv_corewise_retract(frame_data, variations_data)

Additive (corewise) retraction: cores += variations.

utv_corewise_inner(variations_a, variations_b, n_stack)

The raw coordinate (corewise) inner product of two uniform tangents' variations -- mask-applied and

utv_orthogonal_gauge_projection(frame_data, ...)

Orthogonally project the variations onto the gauge-satisfying subspace (the uniform mirror of

utv_oblique_gauge_projection(frame_data, variations_data)

Project the variations onto the gauge-satisfying subspace while PRESERVING the tangent vector (the

utv_gauge_residual(frame_data, variations_data)

Max violation of the gauge conditions for a uniform tangent vector, per stack element (the

utv_project_ut3_onto_tangent_space(frame_data, x_data)

Orthogonal projection of a uniform Tucker tensor train onto the tangent space at an orthogonal frame

utv_weighted_norm(variations, weights, n_stack)

Weighted (Grasedyck-Kramer) coordinate norm of a uniform tangent's variations: absorb the metric

utv_weighted_inner(variations_a, variations_b, ...)

Weighted coordinate inner product <absorb(W, A), absorb(W, B)> w.r.t. one metric -- absorb