ut3svd

t3toolbox.backend.ut3_svd.ut3svd(data, max_tucker_ranks=None, max_tt_ranks=None, assume_orthogonal=False, sharing=None)

def ut3svd(
        data:             UT3Data,
        max_tucker_ranks: typ.Union[int, typ.Sequence[int], NDArray, None] = None,  # scalar / len=d / (d,)+stack
        max_tt_ranks:     typ.Union[int, typ.Sequence[int], NDArray, None] = None,  # scalar / len=d+1 / (d+1,)+stack
        assume_orthogonal: bool = False,
        sharing:          typ.Optional[typ.Sequence] = None,  # len=d, static; one hashable group label per mode (None = unshared)
) -> typ.Tuple[
    UT3Data,  # new_x (left-orthogonal; the raw-sweep ranks -- NOT necessarily minimal under truncation)
    NDArray,  # Tucker singular values, shape=(d,)+stack+(n',)
    NDArray,  # TT singular values,     shape=(d+1,)+stack+(r',)
]:

Mask-truncated T3-SVD of a uniform Tucker tensor train – the basic algorithm, matching ragged t3svd on real parts. Always left-orthogonal; under truncation not necessarily minimal.

Truncation is by max rank only (no rtol/atol – those would make data-dependent shapes): a single left-to-right sweep, shrinking the padded supercore to the raw-sweep content ranks (compute_raw_sweep_ranks). It does not re-tune to minimal ranks – use ut3_rank_adjustment_sweep(). Per-stack-element max_*_ranks arrays are allowed (the variety / rank sweep). assume_orthogonal=True skips the orthogonalization, asserting the input is already right-orthogonal (not enforced). See docs/t3svd_minimal_ranks.md.

sharing (SF-T3 grouped truncation, matching ragged t3svd(sharing=) on real parts): the input’s masked factors must be tied within groups (the frontend checks in safe mode; ranks/caps equal within groups is structural, checked here). sharing=None and all-singleton partitions dispatch to the literal unshared sweep above (bit-identical); a real group runs the two-phase grouped sweep (_ut3svd_shared_supercores()), with ONE group rank mask assigned to every group mode, and the reported spectra masked to the FINAL ranks (the ragged two-phase’s trimming; group modes carry the group spectrum s_g, sqrt(k)-inflated – see SharedFrameData).

Parameters:

• data (UT3Data)

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

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

• assume_orthogonal (bool)

• sharing (t3toolbox.backend.common.typ.Optional[t3toolbox.backend.common.typ.Sequence])

Return type:

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