UT3Variations

class t3toolbox.uniform_frame_variations_format.UT3Variations

Variation cores for the frame-variations representation of uniform Tucker tensor trains.

Uniform analog of T3Variations: two padded supercores (tucker_variations, tt_variations) + the static physical shape (an int tuple, shared across the stack) + a UT3VariationsMasks holder. The variations fit in the “holes” of a UT3Frame.

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
>>> tkv = np.random.randn(d, nD, N)
>>> ttv = np.random.randn(d, rL, nU, rR)
>>> shape = (4, 5, 6)
>>> up    = np.arange(nU) < np.array([[2],[3],[4]])       # (d, nU)
>>> down  = np.arange(nD) < np.array([[3],[4],[5]])       # (d, nD)
>>> left  = np.arange(rL) < np.array([[1],[2],[3]])       # (d, rL) -- note d, not d+1
>>> right = np.arange(rR) < np.array([[1],[2],[2]])       # (d, rR)
>>> masks = ubcf.UT3VariationsMasks(up, down, left, right)
>>> V = ubcf.UT3Variations(tkv, ttv, shape, masks)
>>> V.uniform_structure
(3, 6, 4, 5, 3, 2, ())
>>> V.uniform_variation_shapes
((3, 5, 6), (3, 3, 4, 2))

tucker_variations: NDArray

tt_variations: NDArray

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

masks: UT3VariationsMasks

__rmul__

Methods

d()
N()
nU()
nD()
rL()
rR()
stack_shape()
uniform_structure()
uniform_variation_shapes()
up_ranks()
down_ranks()
variation_left_ranks()
variation_right_ranks()
structure()
data()
apply_masks()	Apply masks to the variation supercores, zeroing out unmasked entries.
from_t3variations(variations[, N, nU, nD, rL, rR])	Pack a ragged T3Variations into uniform variations.
to_t3variations()	Convert to ragged T3Variations (or, if stacked, an
supercores()	The two padded supercores (tucker_variations, tt_variations) (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 variations (UT3Variations).
__post_init__()
unstack()	Unstack a stacked UT3Variations into an array-like tree (shaped like stack_shape) of them.
stack(xx)	Stack an array-like tree of UT3Variations into a single stacked UT3Variations.
__add__(other)	Corewise sum (variations form a vector space at a fixed frame; the mask is unchanged).
__sub__(other)	Corewise difference (mask unchanged).
__mul__(scalar)	Corewise scalar multiplication (mask unchanged).
__neg__()	Corewise negation (mask unchanged).
reverse()	Reverse the mode order (corewise): the tucker-variation supercore reverses; the tt-variation
save(file)	Save the two supercores + shape + masks to a .npz file (load with load()).
load(file[, use_jax])	Load variations saved by save(). Supercores follow use_jax; masks stay host numpy.
sum_stack([axis])	Corewise sum over stack axes (a batch of variations -> their sum; the tangent sum, by linearity).
allclose(other[, rtol, atol])	True (per stack element) if other matches self on the real (masked) content.
zeros(uniform_variation_shapes, shape[, stack_shape, ...])	Zero variations filling the padded supercores completely (additive identity). masks optional;
randn(uniform_variation_shapes, shape[, stack_shape, ...])	Variations with i.i.d. N(0,1) supercore entries (filled completely; ungauged). See randn_like().
unit(uniform_variation_shapes, shape, index[, ...])	Canonical unit variation: zero supercores except a single entry set to 1 (broadcast over the
zeros_like(x)	Zero variations matching the structure of x (a UT3Frame or UT3Variations).
randn_like(x)	Random variations matching the structure (incl. gauge masks) of x (a UT3Frame or UT3Variations).