ut3_orthogonal_representations
==============================

.. py:function:: t3toolbox.backend.ufv_conversions.ut3_orthogonal_representations(data, already_left_orthogonal = False, squash_tails = True)

   .. code-block:: python

      def ut3_orthogonal_representations(
              data: typ.Tuple[
                  NDArray,                          # tucker_supercore
                  NDArray,                          # tt_supercore
                  typ.Tuple[int, ...],              # shape
                  typ.Tuple[NDArray, NDArray],      # (tucker_edge_mask, tt_edge_mask) -- the plain-UT3 rank masks
              ],
              already_left_orthogonal: bool = False,
              squash_tails:                  bool = True,
      ) -> typ.Tuple[
          typ.Tuple[                                # frame .data:
              NDArray, NDArray, NDArray, NDArray,   #   up_sc, down_sc, left_sc, right_sc
              typ.Tuple[int, ...],                  #   shape
              typ.Tuple[NDArray, NDArray, NDArray, NDArray],  # (up, down, frame_left, frame_right) masks
          ],
          typ.Tuple[                                # variations .data:
              NDArray, NDArray,                     #   tucker_var_sc, tt_var_sc
              typ.Tuple[int, ...],                  #   shape
              typ.Tuple[NDArray, NDArray, NDArray, NDArray],  # (variations up, down, left, right) masks
          ],
      ]:


   Orthogonal (frame, variations) representation of a uniform Tucker tensor train, on raw ``.data``.

   Backend twin of the frontend ``ut3_orthogonal_representations`` (which wraps this into the OO
   ``UT3Frame`` / ``UT3Variations``). Takes a plain ``UniformTuckerTensorTrain.data`` and returns the
   **frame** and **variation** ``.data`` tuples (supercores + ``shape`` + the rank masks).

   WHY THIS IS A BACKEND FUNCTION (and not something to open-code): the output frame masks are **prefix**
   masks built from the orthogonal-representation *ranks* (``ufv_make_frame_masks`` = ``arange < rank``) --
   they assert the real orthonormal content sits in the **upper-left** ``[0, rank)`` slots of each
   supercore. That is correct ONLY because the orthogonalization is **SVD-based**: the SVD sorts content
   by singular value into the leading slots, with zeros / orthonormal completion trailing. A QR-based
   orthogonalization would scatter the real content across non-prefix positions and these masks would be
   WRONG -- see ``docs/contributor/uniform_svd_prefix_orthogonalization.md``. Building the masks any other way (e.g.
   from raw supercore magnitudes) is the easy mistake this function exists to prevent.

   The frame masks come from the orthogonal-representation ranks; the variation masks reuse the up/down
   masks and the frame left/right masks shifted by one (a variation occupies one TT slot, not a boundary
   edge -- hence ``left[:-1]`` / ``right[1:]``).