utv_retract

t3toolbox.backend.utv_operations.utv_retract(frame_data, variations_data, shared_data=None)

def utv_retract(
        frame_data,       # UT3Frame .data:      supercore stack = C
        variations_data,  # UT3Variations .data: supercore stack = K + C
        shared_data: typ.Optional['sharing_module.SharedFrameData'] = None,  # tied retraction (SF-T3)
):  # -> retracted UniformTuckerTensorTrain .data (at the BASE point's ranks; stack = K + C)

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

Forms the shifted doubled-rank embedding base point + v (utv_to_ut3() with include_shift=True) and truncates it back to the base point’s own ranks – the Tucker up ranks and left TT ranks read off the frame masks – via the mask-truncated uniform T3-SVD. The output is a UT3 at the frame padded dims (ut3svd truncates by max rank to a fixed shape, so no extra slice is needed), one retracted point per stack element. The uniform mirror of tv_operations.tv_retract() (the implicit T3-SVD / Algorithm 10, Alger et al. 2026).

Varying ranks across ``C`` work for free: the per-C frame ranks are the per-element truncation targets. The ``K`` (tangent) stack: the frame ranks have stack C while the shifted UT3 has stack K + C, so the frame ranks are broadcast over K (the K tangents share the frame, hence the same truncation targets).

With shared_data, the SF-T3 tied retraction (mirroring ragged tv_retract): the TIED doubled-rank embedding (utv_to_ut3() with shared_data) followed by the GROUPED mask-truncated SVD (ut3svd(sharing=...)), so the retracted point’s factors stay exactly tied.

Parameters:

shared_data (t3toolbox.backend.common.typ.Optional[SharedFrameData])