tv_project_dense_onto_tangent_space#

t3toolbox.backend.tv_operations.tv_project_dense_onto_tangent_space(frame, Z)#
def tv_project_dense_onto_tangent_space(
        frame:  typ.Tuple[
            typ.Sequence[NDArray],  # up_tucker_cores
            typ.Sequence[NDArray],  # down_tt_cores
            typ.Sequence[NDArray],  # left_tt_cores
            typ.Sequence[NDArray],  # right_tt_cores
        ],
        Z:      NDArray,  # dense ambient tensor. shape = stack_shape + (N0, ..., N(d-1))
) -> typ.Tuple[
    typ.Tuple[NDArray, ...],  # gauged tucker_variations
    typ.Tuple[NDArray, ...],  # gauged tt_variations
]:

Orthogonal projection of a dense tensor onto the tangent space at an orthogonal frame.

Contraction-only: contracts Z directly against the frame’s orthonormal frames – no SVD and no large intermediate Tucker tensor train (unlike densifying Z with the T3-SVD first). Returns gauged variations representing the orthogonal projection of Z directly onto the tangent space (a linear subspace); it does not subtract the base point. Stack-aware (leading axes beyond the d tensor modes are a stack). Ragged path only (uniform deferred).

Requires an orthogonal frame: the canonical conditions (U row-orthonormal, L/R left/right- canonical, O outer-orthonormal) make each surrounding frame an isometry – so a bare contraction yields the orthogonal-projection coefficient – and make the gauged single-core directions mutually orthogonal. A minimal-rank frame is not required.

Algorithm. For each mode i, reduce Z over every other mode against the frame chains – the left interface (U, L) over modes < i and the right interface (U, R) over modes > i – leaving the single mode x_i open, giving the shared environment core_env_i of shape (r_i, N_i, r_{i+1}). Both variations at i read off it: dG_i = <U_i, core_env_i> (the TT variation) and dU_i = <O_i, core_env_i> (the Tucker variation; O = the outer/down cores). A single left sweep builds the left-reduced environments; each slot finishes with a right reduction. Finally tv_orthogonal_gauge_projection() orthogonalizes the 2d directions so the sum of their per-direction projections equals the projection onto the tangent space.

Parameters:

  • frame (t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.typ.Sequence[NDArray], t3toolbox.backend.common.typ.Sequence[NDArray], t3toolbox.backend.common.typ.Sequence[NDArray], t3toolbox.backend.common.typ.Sequence[NDArray]])

  • Z (NDArray)

Return type:

t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.typ.Tuple[NDArray, Ellipsis], t3toolbox.backend.common.typ.Tuple[NDArray, Ellipsis]]