tv_to_t3#

t3toolbox.backend.tv_operations.tv_to_t3(frame, variations, include_shift=False, shared_data=None)#
def tv_to_t3(
        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
        ],
        variations: typ.Tuple[
            typ.Sequence[NDArray],  # tucker_variations
            typ.Sequence[NDArray],  # tt_variations
        ],
        include_shift:  bool = False,  # False: tangent vector v. True: base point + v.
        shared_data: typ.Optional['sharing_module.SharedFrameData'] = None,  # tied embedding (SF-T3)
) -> typ.Tuple[
    typ.Tuple[NDArray, ...],  # tucker_cores (doubled Tucker ranks)
    typ.Tuple[NDArray, ...],  # tt_cores     (doubled TT ranks)
]:

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

The Tucker cores become [U_i; V_i] (stacked along the Tucker-rank axis); the TT cores form the standard block-bidiagonal embedding. With include_shift=True the base point is folded into the last TT core so the result represents base point + v. Stack-aware.

With shared_data (the frame’s SF-T3 companion), the embedding is built TIED: per nontrivial group, the common gauged ambient direction Udot is recovered from the (tied) coordinates (fv_tied_ambient_directions()) and takes the V_i slot at every group mode – ONE array per group, so the doubled factors [U_g; Udot] are exactly equal across the group – while the paired core block becomes the companion’s center core H_i (the identity S_i-absorbed-O_i == H_i makes this an exact rewrite of each Tucker term). The naive [U_g; V_i] embedding is NOT tied (the V_i = S_i^T Udot differ across a group in value, and in shape when the nD_i differ). Cf. the SF-ETT tangent representation, Molozhavenko & Rakhuba (2026) Sec. 5.2.

Equations (50)-(53) and Figure 20, Appendix A.3.1, of Alger et al. (2026), “Tucker Tensor Train Taylor Series” (arXiv:2603.21141).

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]])

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

  • include_shift (bool)

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

Return type:

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