UT3Frame

class t3toolbox.uniform_frame_variations_format.UT3Frame

Frame (orthogonal frame) for the frame-variations representation of uniform Tucker tensor trains.

Uniform analog of T3Frame: four padded supercores (up_tucker, down_tt, left_tt, right_tt) + the static physical shape (an int tuple, shared across the stack) + a UT3FrameMasks holder (the four per-stack rank masks).

Examples

>>> import numpy as np
>>> import t3toolbox.uniform_frame_variations_format as ubcf
>>> d, N, nU, nD, rL, rR = 3, 6, 4, 5, 3, 2
>>> up    = np.random.randn(d, nU, N)
>>> down  = np.random.randn(d, rL, nD, rR)
>>> left  = np.random.randn(d, rL, nU, rL)
>>> right = np.random.randn(d, rR, nU, rR)
>>> shape = (4, 5, 6)                                          # real mode dims (each <= N=6)
>>> up_mask    = np.arange(nU) < np.array([[2],[3],[4]])       # (d, nU); per-mode up rank
>>> down_mask  = np.arange(nD) < np.array([[3],[4],[5]])       # (d, nD)
>>> left_mask  = np.arange(rL) < np.array([[1],[2],[3],[1]])   # (d+1, rL); boundary TT ranks
>>> right_mask = np.arange(rR) < np.array([[1],[2],[2],[1]])   # (d+1, rR)
>>> masks = ubcf.UT3FrameMasks(up_mask, down_mask, left_mask, right_mask)
>>> B = ubcf.UT3Frame(up, down, left, right, shape, masks)
>>> B.shape
(4, 5, 6)
>>> np.asarray(B.up_ranks).tolist()
[2, 3, 4]
>>> B.stack_shape
()

up_tucker_supercore: NDArray

down_tt_supercore: NDArray

left_tt_supercore: NDArray

right_tt_supercore: NDArray

shape: t3toolbox.backend.common.typ.Tuple[int, Ellipsis]

masks: UT3FrameMasks

Methods

data()
d()
N()
nU()
nD()
rL()
rR()
stack_shape()
uniform_structure()
uniform_variation_shapes()
up_ranks()
down_ranks()
left_ranks()
right_ranks()
structure()
apply_masks()	Apply masks to the frame supercores, zeroing out unmasked entries.
orthogonality_residual()	Max deviation of the (masked) frame supercores from orthonormality, per stack element
is_orthogonal([atol])	True (per stack element) if the frame supercores are orthogonal in their respective senses on
minimal_ranks()	Structural minimal ranks (min_tucker_ranks, min_tt_ranks) for this frame's shape/ranks,
has_minimal_ranks()	True (per stack element) if the frame has structurally minimal ranks: left==right,
has_numerically_minimal_ranks([atol])	True (per stack element) if the frame is numerically minimal.
is_consistent([rtol])	True (per stack element) if the left- and right-canonical reconstructions of the base point
allclose(other[, rtol, atol])	True (per stack element) if other represents the same base point as self
from_t3frame(frame[, N, nU, nD, rL, rR])	Pack a ragged T3Frame into a uniform frame.
to_t3frame()	Convert to a ragged T3Frame (or, if stacked, an
from_ut3(x)	Orthogonal frame at the point x (the frame part of ut3_orthogonal_representations()).
to_ut3()	The base point this frame represents, as a UniformTuckerTensorTrain (right-canonical:
to_dense()	Dense tensor of the base point this frame represents (= to_ut3().to_dense()).
reverse()	Reverse the mode order. Left/right supercores (and masks) swap roles -- reversing a
orthogonalize()	Orthogonal representation of the base point this frame reconstructs to (= from_ut3(to_ut3())).
random_orthogonal(shape, tucker_ranks, tt_ranks[, ...])	Orthogonal representation of a random uniform T3 -- a genuine random base point (orthogonal,
random_orthogonal_like(frame)	A random orthogonal frame with the same shape / ranks / stack as frame.
save(file)	Save the four supercores + shape + masks to a .npz file (load with load()).
load(file[, use_jax])	Load a frame saved by save(). Supercores follow use_jax; masks stay host numpy.
supercores()	The four padded supercores (up, down, left, right) (the data; masks ride separately).
contains_jax()	True if any supercore is a jax array (the masks are always host numpy).
to_jax()
to_numpy()
copy()
__repr__()
validate()	Check rank and shape consistency of a uniform Tucker tensor train frame (UT3Frame).
__post_init__()
unstack()	Unstack a stacked UT3Frame into an array-like tree (shaped like stack_shape) of UT3Frame.
stack(xx)	Stack an array-like tree of UT3Frame into a single stacked UT3Frame.