t3m_swap
========

.. py:function:: t3toolbox.backend.t3_linalg.t3m_swap(x, y, max_tucker_ranks = None, max_tt_ranks = None, rtol = None, atol = None, oversample = 1)

   .. code-block:: python

      def t3m_swap(
              x: typ.Tuple[typ.Sequence[NDArray], typ.Sequence[NDArray]],  # (tucker_cores_x, tt_cores_x)
              y: typ.Tuple[typ.Sequence[NDArray], typ.Sequence[NDArray]],  # (tucker_cores_y, tt_cores_y)

              max_tucker_ranks:   typ.Union[int, typ.Sequence[int], None] = None,  # scalar caps all, or len=d
              max_tt_ranks:       typ.Union[int, typ.Sequence[int], None] = None,  # scalar caps all, or len=d+1

              rtol:               typ.Optional[float] = None,  # requires unstacked (enforced by the frontend)
              atol:               typ.Optional[float] = None,

              oversample:         float = 1,  # >= 1; intermediate rank/tol relaxation factor (see docs/ttm_t3m_ht_note.tex)
      ) -> typ.Tuple[
          typ.Tuple[NDArray, ...],  # x_times_y tucker_cores
          typ.Tuple[NDArray, ...],  # x_times_y tt_cores
      ]:


   Elementwise product ``x ⊙ y`` -- method (c): the swap-based TTM generalization, for
   ``r ≫ d`` (huge TT bonds, few modes); ``O(d²·r³)`` compute, ``O(r̃²)`` memory.

   Concatenates the two central TTs into a length-``2d`` chain (the second reversed so
   matching modes meet in ``d(d-1)/2`` swaps), keeps each core's Tucker factor riding on its
   leg, then for each mode (``d-1`` down to ``0``) bubbles the matching pair adjacent via
   **gauge-centered truncating swaps** and merges them (Khatri-Rao Tucker factor + joint
   weighted-Tucker truncation). The orthogonality center is tracked explicitly so every
   swap/merge SVD is locally optimal; the Tucker factors are down-orthogonalized up front.

   Because the merged Tucker leg of the last-merged mode is full-rank while its bonds are set
   (a tension absent from pure-TT TTM -- see ``docs/ttm_t3m_ht_note.tex``), in-process
   truncation is only quasi-optimal. ``oversample = k`` resolves this: intermediate ranks are
   capped at ``k×`` the target (tolerances at ``/k``) purely to bound memory, and a single
   ``t3svd`` cleanup at the exact targets does the decisive truncation. ``k=1`` (default) skips
   the cleanup (aggressive corner; with ``rtol`` the uncleaned per-step tolerances accumulate to
   ~``d·rtol`` overall -- use ``oversample>1`` for tighter tolerance-based quality); ``k≈3``
   recovers ``t3svd`` quality; a per-position
   ``max_tt_ranks`` sequence also triggers the cleanup (the swaps cannot honor per-position
   bonds). Stack-aware with max-rank truncation; ``rtol``/``atol`` require unstacked. No
   truncation requested -> the exact full product.