compute_minimal_ranks#

t3toolbox.backend.ranks.compute_minimal_ranks(shape, tucker_ranks, tt_ranks, sharing=None, use_jax=False)#
def compute_minimal_ranks(
        shape: typ.Sequence[int], # (N0, ..., N(d-1))
        tucker_ranks: typ.Union[
            typ.Sequence[int], # (n0,...,n(d-1))
            NDArray, # dtype=int, shape=(d,) + stack_shape
        ],
        tt_ranks: typ.Union[
            typ.Sequence[int], # (r0,...,rd)
            NDArray, # dtype=int, shape=(d+1,) + stack_shape
        ],
        sharing: typ.Optional[typ.Sequence] = None, # len=d, static; one hashable group label per mode (None = unshared)
        use_jax: bool = False,
) -> typ.Tuple[
    typ.Union[
        typ.Tuple[int,...],  # (n0',...,n(d-1)')
        NDArray,  # dtype=int, shape=(d,) + stack_shape
    ], # new_tucker_ranks
    typ.Union[
        typ.Tuple[int,...],  # (r0',...,rd')
        NDArray,  # dtype=int, shape=(d+1,) + stack_shape
    ], # new_tt_ranks
]:

Find minimal ranks for a generic Tucker tensor train with a given structure.

With sharing (one hashable group label per mode – validate_sharing()), minimality is with respect to Tucker factors tied within each group: Tucker reductions apply group-wide, and the per-mode ceiling n_i <= min(N_i, rL_i*rR_i) is replaced by the group ceiling

n_g <= min(N_g, sum_{i in g} min(N_g, rL_i*rR_i))

re-evaluated at every group-mode visit of the left-to-right phase. A shared basis column is useless only if it is useless for EVERY mode of the group, so the per-mode ceilings ADD across the group and n_g may legitimately exceed rL_i*rR_i at individual modes – the unshared reduction applied to a shared structure clips such ranks and unties the group. The result equals the generic dense edge-cut ranks of a tied T3 (group Tucker rank = the rank of the concatenated matricization [X_(i1)|...|X_(ik)]), and a single pass reaches the fixed point – a second pass changes nothing (asserted property-based in the tests, per the single-pass theorem’s sensitivity to the phase ordering). Input Tucker ranks must already be equal within each group (structural error otherwise – an unequal proposal is not a shared rank vector). sharing=None or an all-singleton partition is the existing unshared reduction exactly.

Parameters:

  • shape (t3toolbox.backend.common.typ.Sequence[int])

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

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

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

  • use_jax (bool)

Return type:

t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.typ.Union[t3toolbox.backend.common.typ.Tuple[int, …], NDArray], t3toolbox.backend.common.typ.Union[t3toolbox.backend.common.typ.Tuple[int, …], NDArray]]