utv_to_ut3
==========

.. py:function:: t3toolbox.backend.utv_operations.utv_to_ut3(frame_data, variations_data, include_shift = False)

   .. code-block:: python

      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.
      ):  # -> 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 :py:func:`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 **base-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``).