utv_to_ut3#

t3toolbox.backend.utv_operations.utv_to_ut3(frame_data, variations_data, include_shift=False, shared_data=None)#
def utv_to_ut3(
        frame_data,       # UT3Frame .data:      (up, down, left, right, shape, (4 masks)),  supercore stack = C
        variations_data,  # UT3Variations .data: (tkv, ttv, shape, (4 masks)),               supercore stack = K + C
        include_shift: bool = False,  # False: tangent vector v. True: base point + v.
        shared_data: typ.Optional['sharing_module.SharedFrameData'] = None,  # tied embedding (SF-T3)
):  # -> doubled-rank UniformTuckerTensorTrain .data: (tucker_supercore, tt_supercore, shape, (tucker_mask, tt_mask))

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

The uniform mirror of tv_operations.tv_to_t3() (equations (50)-(53) / Figure 20, Appendix A.3.1 of Alger et al. 2026). The Tucker supercore becomes [U ; V] (concat along the Tucker-rank axis); the TT supercore is the block-bidiagonal embedding, uniform-padded to bonds rL+rR for every core with the frame-inner ``[R, L]`` bond order (mirroring the ragged build). The doubled rank masks are concatenations of the existing masks (the #1 trap: the appended boundary slots are FULL ones – the supercore is zero there, so to_dense’s mask-then-contract is unaffected): tucker_mask = concat([up, down]); tt_mask = concat([right_ext, left_ext]) with left_ext = [var_left, ones] and right_ext = [ones, var_right].

Stack-aware: the variation supercores carry K + C; the frame supercores (stack C) are broadcast up to K + C (mirror ragged bcast), and the masks (host numpy, carrying K + C already from the variations) are concatenated on the host. With include_shift=True the base point is folded into the last core (base point + v).

With shared_data (the frame’s uniform SF-T3 companion), the embedding is built TIED, mirroring the ragged branch: per nontrivial group the common gauged ambient direction Udot (fv_tied_ambient_directions() – garbage-immune through the companion’s masked U_M) takes the variation slot at EVERY group mode, and the companion’s center core H_i replaces O_i (an exact rewrite of each Tucker term). Udot has the UP width, so the variation block is rebuilt at height nU: singleton slices zero-pad from nD (block masks pad with False); group block masks are the frame’s UP mask.

Parameters:

  • include_shift (bool)

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