t3m_swap#

t3toolbox.backend.t3_linalg.t3m_swap(x, y, max_tucker_ranks=None, max_tt_ranks=None, rtol=None, atol=None, oversample=1)#
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.

Parameters:

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

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

  • max_tucker_ranks (t3toolbox.backend.common.typ.Union[int, t3toolbox.backend.common.typ.Sequence[int], None])

  • max_tt_ranks (t3toolbox.backend.common.typ.Union[int, t3toolbox.backend.common.typ.Sequence[int], None])

  • rtol (t3toolbox.backend.common.typ.Optional[float])

  • atol (t3toolbox.backend.common.typ.Optional[float])

  • oversample (float)

Return type:

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