UniformTuckerTensorTrain#

class t3toolbox.uniform_tucker_tensor_train.UniformTuckerTensorTrain#

A uniform Tucker tensor train: two supercores (the data) + a UT3Masks holder (the static structure).

  • tucker_supercore: shape (d,) + stack_shape + (n, N)

  • tt_supercore: shape (d,) + stack_shape + (r, n, r)

  • masks: the UT3Masks (shape mask + the two rank masks)

The mode index d leads (outside the stack) so sweeps compile to lax.scan over axis 0 (docs/uniform_supercore_layout.md). Ranks may differ across the stack; the physical shape may not (docs/uniform_ranks_and_varieties.md).

tucker_supercore: NDArray#
tt_supercore: NDArray#
shape: Tuple[int, Ellipsis]#
masks: UT3Masks#
property supercores: Tuple[NDArray, NDArray]#

(tucker_supercore, tt_supercore).

Return type:

Tuple[NDArray, NDArray]

property data: Tuple[NDArray, NDArray, Tuple[int, Ellipsis], Tuple[NDArray, NDArray]]#

(tucker_supercore, tt_supercore, shape, (2 rank masks)).

Backend ut3_* functions take this layout (supercore-only ops use .data[:2]; the static shape is .data[2]; mask-using ops unpack .data[3]). The UT3Masks holder stays a frontend concern.

Type:

Raw-array view, mirroring the fields

Return type:

Tuple[NDArray, NDArray, Tuple[int, Ellipsis], Tuple[NDArray, NDArray]]

property d: int#

Number of modes.

Return type:

int

property n: int#

Padded Tucker rank (n >= max of the real Tucker ranks).

Return type:

int

property N: int#

Padded mode dimension (N >= max of the real shapes).

Return type:

int

property r: int#

Padded TT rank (r >= max of the real TT ranks).

Return type:

int

property stack_shape: Tuple[int, Ellipsis]#

Stack shape (() if unstacked). Lives at axes 1 .. len(stack_shape) (d is axis 0).

Return type:

Tuple[int, Ellipsis]

property uniform_structure: Tuple[int, int, int, int, Tuple[int, Ellipsis]]#

(d, N, n, r, stack_shape) – the padded structure.

Return type:

Tuple[int, int, int, int, Tuple[int, Ellipsis]]

property tucker_ranks: NDArray#

Real Tucker ranks (from tucker_edge_mask; may vary across the stack).

Return type:

NDArray

property tt_ranks: NDArray#

Real TT ranks (from tt_edge_mask; may vary across the stack).

Return type:

NDArray

property structure: Tuple[Tuple[int, Ellipsis], NDArray, NDArray, Tuple[int, Ellipsis]]#

(shape, tucker_ranks, tt_ranks, stack_shape) – the real structure.

Return type:

Tuple[Tuple[int, Ellipsis], NDArray, NDArray, Tuple[int, Ellipsis]]

__rmul__#
property minimal_ranks: Tuple[NDArray, NDArray]#

Structural minimal ranks (min_tucker_ranks, min_tt_ranks) for this UT3’s shape/ranks.

Return type:

Tuple[NDArray, NDArray]

property has_minimal_ranks: NDArray#

True (per stack element) if this UT3’s ranks are structurally minimal. Per-element (uniform ranks vary across the stack), reduced over the mode axes; reduce with .all() for a single verdict.

Return type:

NDArray

property contains_jax: bool#
Return type:

bool

Methods#

validate()

Check the structural invariants (shapes mutually consistent, rank masks boolean, shape a

__post_init__()

__repr__()

apply_masks()

Zero the padded ("garbage") regions of the supercores (the masks are unchanged).

to_dense()

Form the dense tensor, shape = stack_shape + (N0,...,N(d-1)). (Inspection/tests only.)

from_t3(x[, N, n, r, squash_tails])

Pack a ragged TuckerTensorTrain into a uniform one.

to_t3()

Convert back to ragged form.

reverse()

Reverse the mode order.

squash_tails()

Sum the leading/trailing TT bonds down to rank 1 (preserves the represented tensor).

__mul__(s)

Scale by a scalar.

__neg__()

__add__(other)

Add two uniform Tucker tensor trains (direct sum, then squash). Requires matching shape / d /

__sub__(other)

sum_stack()

Sum the represented tensors over the entire stack -> one unstacked uniform T3 (genuine tensor

inner(other[, use_orthogonalization])

Hilbert-Schmidt inner product with another uniform Tucker tensor train (shape=stack_shape).

norm([use_orthogonalization])

Hilbert-Schmidt (Frobenius) norm of the represented tensor (shape=stack_shape).

entries(index)

Entry/entries of the represented dense tensor, evaluated without forming it (shares

apply(vecs)

Contract the represented tensor with vectors in all modes, without forming it (shares

probe(ww)

Probe: contract all-but-one mode, for each mode (leaving mode i free), without forming the

probe_derivatives(ww, pp, order)

Symmetric directional derivatives of probe(), in one repeated direction P (pp):

apply_derivatives(ww, pp, order)

Symmetric all-modes apply derivatives (the derivative twin of apply()), one repeated

entries_derivatives(index, pp, order)

Symmetric entry derivatives at index in direction P (the derivative twin of

apply_corewise_transpose(c, ww[, sum_over_probes])

Corewise (non-manifold) transpose of apply(): gradient of apply(X(cores), ww) w.r.t.

entries_corewise_transpose(c, index[, sum_over_probes])

Corewise transpose of entries(): gradient w.r.t. the supercores (= the one-hot

probe_corewise_transpose(ztildes, ww[, sum_over_probes])

Corewise transpose of probe(): gradient w.r.t. the supercores. Like

apply_corewise_derivatives_transpose(c, ww, pp, order)

Corewise (non-manifold) transpose of apply_derivatives(): gradient of the

entries_corewise_derivatives_transpose(c, index, pp, order)

Corewise transpose of entries_derivatives(): gradient w.r.t. the supercores (= the

probe_corewise_derivatives_transpose(ztildes, ww, pp, ...)

Corewise transpose of probe_derivatives(): gradient w.r.t. the supercores. See

sum([axis])

Sum the represented tensor over all physical modes (shape=stack_shape). Partial sums (axis

down_orthogonalize_tucker_cores()

Orthogonalize the Tucker cores, pushing the remainder up into the TT cores.

up_orthogonalize_tt_cores()

Up-orthogonalize the TT cores, pushing the remainder down into the Tucker cores.

left_orthogonalize_tt_cores()

Left-orthogonalize the TT cores.

right_orthogonalize_tt_cores()

Right-orthogonalize the TT cores.

is_left_orthogonal([atol])

True (per stack element) if in left-orthogonal form (Tucker supercores down-orthogonal AND TT

is_right_orthogonal([atol])

True (per stack element) if in right-orthogonal form (Tucker supercores down-orthogonal AND TT

t3svd([max_tt_ranks, max_tucker_ranks, assume_orthogonal])

Mask-truncated T3-SVD -- the basic algorithm, matching ragged TuckerTensorTrain.t3svd()

rank_adjustment_sweep([direction])

A single directional sweep that drops structurally-redundant ranks (the separate

unstack()

Unstack into an array-like tree (shaped like stack_shape) of unstacked UT3s.

stack(uxx)

Stack an array-like tree of UT3s into one stacked UT3.

to_jax()

to_numpy()

copy()

zeros(shape[, tucker_ranks, tt_ranks, stack_shape, ...])

Uniform Tucker tensor train of zeros (padded regions masked to zero).

ones(shape[, stack_shape, use_jax])

Rank-1 uniform Tucker tensor train representing a tensor full of ones (every real entry == 1).

randn(shape, tucker_ranks, tt_ranks[, stack_shape, ...])

Uniform Tucker tensor train with random N(0,1) supercores (padded regions masked to zero).

save(file)

Save to a .npz file (2 supercores + 2 rank masks + the shape ints). See load().

load(file[, use_jax])

Load from a .npz file written by save().